%% adrguide.tex %% Copyright 2006 Axel Kielhorn % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 % of this license or (at your option) any later version. % The latest version of this license is in % http://www.latex-project.org/lppl.txt % and version 1.3 or later is part of all distributions of LaTeX % version 2003/12/01 or later. % % This work has the LPPL maintenance status "maintained". % % This Current Maintainer of this work is Axel Kielhorn (A.Kielhorn@web.de) % % This work consists of the files adrconv.ins, adrconv.dtx, adrguide.tex % and the derived file adrguide.pdf. % % Use % tex adrconv.ins % or % latex adrconv.ins % to generate the other files, which are indirect parts of the % bundle. Use % latex adrconv.dtx % to generate the implementation documentation. Use % latex adrguide.tex % to generate the user documentation. \documentclass{article} \usepackage[T1]{fontenc} \usepackage{ae} \usepackage{german} \newcommand*{\File}[1]{\texttt{#1}} \newcommand*{\Class}[1]{\textsf{#1}} \newcommand*{\Macro}[1]{\texttt{\textbackslash #1}} \DeclareRobustCommand{\KOMAScript}{\textsf{K\kern.05em O\kern.05em% M\kern.05em A\kern.1em-\kern.1em Script}} \title{ADRconv Anleitung\\Version 1.2c} \author{Axel Kielhorn\thanks{A.Kielhorn@web.de}} \date{19. April 2006} \begin{document} \maketitle \section{Adressdatenbanken}\label{sec:adrconv.database} Wenn Sie Adressdateien zum Briefschreiben verwenden m"ussen Sie sich selbst um die Ordnung in einer solchen Datei k"ummern. Falls Sie nur gelegentlich und mit einem leicht "uberschaubaren Adressatenkreis per Brief korrespondieren, werden Sie mit den bisher gezeigten M"oglichkeiten meist auch zufrieden sein. Wenn jedoch die Menge der Adressen zunimmt und auch der Umfang der Adressinformationen "uber die blo"se Postanschrift hinausw"achst, beginnt die Verwaltung der Adressen zu einem eigenen Problem zu werden. Dieses Problem besteht zun"achst ganz unabh"angig davon welche Briefklasse Sie verwenden, und so war auch die L"osung, die Gerd Neugebauer 1994 vorstellte, nicht auf \KOMAScript{} und dessen Vorg"anger, sondern auf Bib\TeX{} bezogen. Sein Bibliographie-Stil \File{address.bst} in Verbindung mit einem speziell definierten Eintragstypen f"ur Bib\TeX-Datenbanken und einer \File{tex}-Datei machte sich den Umstand zunutze, dass Bib\TeX{} in der Lage ist, strukturierte Daten zu sortieren und in konfigurierbaren Listen auszugeben. Bib\TeX{} kann somit als Hilfsprogramm eingesetzt werden, das f"ur Ordnung in Adressdatenbest"anden sorgt. Damit Bib\TeX{} eine Datei bearbeiten kann, muss diese in einem bestimmten Format vorliegen. Normalerweise besitzt eine solche Datei die Dateinamenserweiterung \File{bib} und enth"alt bibliographische Daten. Diese Daten werden nach Eintragstypen klassifiziert. Es ist m"oglich, neue Eintragstypen zu bilden und von Bib\TeX{} auswerten zu lassen.% \footnote{Die f"ur \LaTeX{} standardm"a"sig definierten Eintragstypen, ihr formaler Aufbau und die Funktionsweise von Bib\TeX{} "uberhaupt k"onnen hier nicht beschrieben werden. F"ur sie sei auf die Originaldokumentation in \textsf{btxdoc} und \textsf{btxhak} sowie auf die Beschreibung im \LaTeX-Handbuch verwiesen.} Unter einer \emph{Adressdatenbank} verstehen wir eine Bib\TeX-konforme Datei. \begin{verbatim} @address{...} \end{verbatim} F"ur Eintr"age in einer Adressdatenbank gibt es den speziellen Eintragstyp \verb|@address|. Das folgende Beispiel beschreibt das Format eines \verb|@address|-Eintrags in einer \File{bib}-Datei: \begin{small} \begin{verbatim} @address{HMUS, name = {Hans Mustermann}, title = {Mag. art.}, organization = {Verband der Vereine}, city = {Heimstatt}, zip = 01234, country = {Germany}, street = {Mauerstra{\ss}e 1}, phone = {01234 / 5 67 89}, fax = {01234 / 5 67 89}, mobile = {0171 / 45 67 89}, email = {hm{@}work.com}, url = {http://www.work.com}, note = {Alles nur Erfindung}, key = {HMUS}, birthday = {13. August anno muri}, nbirthday = {0813} } @address{OEKZ, name = {{{"O}kologisches Zentrum~e.\,V.}}, sortas = {Okologisches Zentrum}, organization = {Verband der Vereine}, city = {Heimstatt}, zip = 01234, country = {Germany}, street = {Mauerstra{\ss}e 1}, phone = {01234 / 5 67 89}, fax = {01234 / 5 67 89}, email = {hm{@}work.com}, key = {OEKZ}, } \end{verbatim} \end{small} "Ahnliche Mustereintr"age wie diesen finden Sie in der Datei \File{example.bib}. Die Adresseintr"age dort sind jedoch weniger umfangreich. Die hier dargestellte ausf"uhrliche Form zeigt die Version~1.2. \begin{description} \item[name] Der Name im normalen Bib\TeX\ Format: Vorname von Nachname \item[sortas] Wenn der Name mit einem Umlaut beginnt, wird er falsch einsortiert, bei der Verwendung von UTF-8 kodierten Datenbanken kommt es sogar zu einem Bib\TeX\ Fehler. \texttt{sortas} hat Vorrang vor \texttt{name}. (Neu in Version 1.2c.) \item[title] Akademischer Titel oder "ahnliches (Wird z.\,Zt. nicht unterst\"{u}tzt) \item[organization] Organisation, Firma, Gewerkschaft, Verein (Wird z.\,Zt. nicht unterst\"{u}tzt) \item[city] Stadt \item[country] Das L"anderkennzeichen (Wird z.\,Zt. nicht unterst\"{u}tzt) \item[zip] Postleitzahl (ZIP-Code ist die US Bezeichnung) \item[street] Stra"se \item[phone] Telefonnummer \item[mobile] Zweite Telefonnummer, z.\,B. f"ur Mobiltelefon \item[fax] Telefaxnummer, wird von \File{adrfax.bst} zum Erstellen eines Telefaxbuches verwendet. \item[email] E-mail Adresse, wird von \File{email.bst} zum Erstellen eines E-mail Verzeichnisses benutzt. \item[url] Ein Link auf die Homepage. Hier w"are jetzt ein Konverter nach HTML gefragt. \item[key] Das K"urzel unter dem der betreffende Name in {\KOMAScript} Briefklasse aufgerufen werden kann. Dieses K"urzel muss f"ur alle \texttt{bib} Dateien eindeutig sein. \item[note] Notiz (Wird z.\,Zt. nicht unterst\"{u}tzt) \item[birthday] Geburtstagstext, so wie er gedruckt wird \item[nbirthday] Numerischer Geburtstag, wird zum Sortieren verwendet. Format: Monat zweistellig Tag zweistellig (MMDD) \end{description} \section{Adressdatenbankkonverter}% Bib\TeX{} erzeugt aus \File{bib}-Dateien (Datenbanken) \File{bbl}-Dateien. Eine \File{bbl}-Datei besteht im wesentlichen aus einer sortierten Liste. Welche Elemente einer \File{bib}-Datei hierf"ur ausgewertet werden und wie die resultierende \File{bbl}-Datei im einzelnen aufgebaut ist, wird dabei jeweils durch einen Bibliographie-Stil (eine \File{bst}-Datei) gesteuert. Die standardm"a"sig f"ur die Erzeugung von Literaturverzeichnissen mit \LaTeX{} eingesetzten Bibliographie-Stile k"onnen freilich weder \verb|@address|-Eintragstypen auswerten noch Adressdateien im \File{adr}-Format erzeugen. Um eine Adressdatenbank in eine Adressdatei zu konvertieren, wird also ein eigens daf"ur eingerichteter Bibliographie-Stil ben"otigt. Es wurden daf"ur mehrere Bibliographie-Stile entwickelt, die als Konverter von Adressdatenbanken in Adressdateien dienen k"onnen. \begin{description} \item[\File{adrconv.bst}] Erzeugt eine Adressdatei, die sowohl mit der {\KOMAScript} Briefklasse zum Einf"ugen von Adressen in Briefe als auch mit den Programmen \File{dir.tex} und \File{phone.tex} zur Erzeugung von Adress- und Telefonverzeichnissen verwendet werden kann. Es werden dabei jeweils die ersten vier Felder sowie das achte Feld der Adress-Eintr"age (\emph{Name}, \emph{Vorname}, \emph{Adresse}, \emph{Telefonnummer} und \emph{K"urzel}) belegt. Die Adress-Eintr"age in der Datei werden alphabetisch nach den Namen sortiert und die \Macro{adrchar}-Eintr"age werden am Beginn jeder Buchstabengruppe automatisch eingesetzt. Das K"urzel wird als Ged"achnisst"utze mit ausgegeben. Mit diesem K"urzel kann der Eintrag in der Briefklasse aus {\KOMAScript} aufrufen werden. \item[\File{adrfax.bst}] Ein Konvertierer zum Erstellen von Faxb"uchern. Statt der \emph{Telefonnummer} wird hier jedoch die \emph{Faxnummer} benutzt. \item[\File{birthday.bst}] Erzeugt eine Adressdatei, die mittels \File{dir.tex} als Geburtstagsverzeichnis ausgegeben werden kann. Hierf"ur werden die Eintr"age nach Monat und Tag sortiert. Damit das funktioniert, mu"s ein \emph{nbirthday} Eintrag vorhanden sein. Dieser wird als Sortierschl"ussel genutzt. \item[\File{email.bst}] Erzeugt eine Adressdatei, die durch Bearbeitung mit \File{dir.tex} ein E-Mail-Verzeichnis ergibt. Sie ist alphabetisch nach Namen sortiert. \end{description} \section{Ablauf der Konvertierung} Damit Bib\TeX{} eine Adressdatenbank mit Hilfe eines Bibliographie-Stils in eine Adressdatei konvertieren kann, ben"otigt es noch Informationen dar"uber, welche der Eintr"age aus der \File{bib}-Datei auf diese Weise bearbeitet werden sollen. Diese Informationen entnimmt Bib\TeX{} der \File{aux}-Datei, die beim \TeX-Lauf "uber eine \File{tex}-Datei entsteht und die Schl"usselw"orter f"ur Bib\TeX{} enth"alt, welche normalerweise durch \Macro{cite}-Befehle in der \File{tex}-Datei erzeugt werden. In unserem Fall gibt es keine derartige \File{tex}-Datei. Stattdessen m"ussen wir uns eine Hilfsdatei anlegen. \begin{verbatim} \citation{*} \bibstyle{adrconv} % oder adrfax, birthday, email \bibdata{example} % koennen auch mehrere Dateien sein \end{verbatim} \verb+\citation{*}+ w"ahlt alle Eintr"age der Datenbank aus, \verb+\bibstyle+ den gew"unschten Stil und \verb+\bibdata+ die Datenbank(en). Es k"onnen auch mehrere Datenbanken gleichzeitig ausgew"ahlt werden. Dadurch kann man private und berufliche Adressen in unterschiedlichen Datenbanken pflegen und bei Bedarf eine gemeinsame Adressliste erstellen. Die von Bib\TeX\ erstellte \File{bbl} Datei muss dann nur noch in \File{adr} umbenannt werden und schon kann sie mit \File{dir.tex} in ein Adressbuch umgewandelt werden. Das beiliegende \File{adrdir.tex} enth"alt eine etwas modifizierte Version von \File{dir.tex}. Diese Version kann "uber Konfigurationsdateien f"ur verschiedene Formate angepasst werden: \begin{description} \item[adrdir] Das Originalformat aus \File{dir.tex}, die Einzelseiten sind DIN A6 gro"s und k"onnen so platzsparend auf DIN A4 ausgedruckt werden. \item[adrschmal] Ist ein etwas schmaleres Format, das in viele Taschenkalender passt, z. B. in den Kalender den mir meine Sparkasse jedes Jahr schenkt. \item[adrplaner] Diese Woche hatte Aldi einen Taschenkalender im Angebot, wie "ublich auch mit Adressbuch. Aber warum soll ich jetzt alle Adressen von Hand eintragen, also musste eine neue Konfigurationsdatei her. Die sollte problemlos auch in andere Organizer passen. (Ich w"urde mich "uber R"uckmeldungen freuen.) \end{description} In den Konfigurationsdateien befinden sich auch die Parameter f"ur DVIDVI, damit man die Einzelseiten problemlos auf ein Blatt A4 verteilen kann. Die interaktive \TeX-Programme mit den Namen \File{adrconv.tex}, \File{birthday.tex} und \File{email.tex}, k"onnen die jeweils passende \File{aux}-Dateien selbst erzeugen. Die Konvertierung einer Adressdatenbank in eine Adressdatei l"auft daher in drei Schritten ab: \begin{enumerate} \item Vorbereitung der Konvertierung durch Erzeugen der \File{aux}-Datei f"ur die entsprechende \File{bib}-Datei. \item Konvertierung der \File{bib}-Datei mittels Bib\TeX. \item Umbenennung der entstandenen \File{bbl}-Datei in die \File{adr}-Namensform f"ur Adressdateien \end{enumerate} Angenommen, Sie haben einen neuen Eintrag in Ihre Adressdatenbank mit Namen \File{adressen.bib} aufgenommen, der so aussehen k"onnte: \begin{small} \begin{verbatim} @address{DANTE, name = {{DANTE~e.\,V.}}, sortas = {Dante}, street = {Postfach 10 18 40}, zip = {69008}, city = {Heidelberg}, phone = {0 62 21 / 2 97 66}, fax = {0 62 21 / 16 79 06}, email = {dante{@}dante.de}, url = {http://www.dante.de}, key = {DANTE}, birthday = {14. April 1989}, nbirthday = {0414} } \end{verbatim} \end{small} Wenn Sie eine Adressdatei f"ur Briefe und ein Adressverzeichnis brauchen, w"ahlen Sie den Konverter \File{adrconv} und erzeugen die \File{aux}-Datei. Die Protokolldatei \File{adrconv.log} zeigt, wie das abgelaufen ist: \begin{small} \begin{verbatim} sh>tex adrconv.tex This is TeX, Version 3.14159 (Web2C 7.3.2x) (format=tex 2001.8.1) 13 AUG 2001 05:26 **adrconv.tex (/texmf/tex/latex/koma-script/adrconv.tex Now you have to typein the name of the BibTeX adressfile, you want to convert to script-adress-file-format (without extension `.bib'): Geben Sie nun den Namen der BibTeX-Adressdatei ein, die Sie in das Script-Adressdateiformat konvertieren wollen (ohne `.bib'): adressfile=adressen \auxfile=\write0 \openout0 = `adressen.aux'. After running BibTeX rename file `adressen.bbl' to `adressen.adr'! Nach dem BibTeX-Lauf benennen Sie bitte die Datei `adressen.bbl' in `adressen.adr' um! [1] ) Output written on adrconv.dvi (1 page, 224 bytes). \end{verbatim} \end{small} Als zweiten Schritt rufen Sie Bib\TeX{} zur Konvertierung auf. Wir zeigen das Protokoll \File{adressen.blg}: \begin{small} \begin{verbatim} sh>bibtex adressen This is BibTeX, Version 0.99c (Web2C 7.3.2x) The top-level auxiliary file: adressen.aux The style file: adrconv.bst Database file #1: adressen.bib \end{verbatim} \end{small} Zuletzt benennen Sie die Datei um: \begin{small} \begin{verbatim} sh>mv adressen.bbl adressen.adr \end{verbatim} \end{small} Die konvertierte Adressdatei hat folgenden Inhalt: \begin{small} \begin{verbatim} \adrchar{K} \adrentry{Kalkweiss}{Achim} {Langer Weg 17 \\ 38118 Braunschweig}{0531 / 113 34 89}{}{}{}{} \adrentry{Kohlmeise}{Rudolf} {Stra{\ss}e des 11.~September 73 \\ 12345 Neu Jorg}{0513 / 89 55 66}{}{}{}{} \adrentry{Kuchennascher}{Mattse} {Fichtenstra{\ss}e 1 \\ 98765 Brummelsbach}{}{}{}{}{} \adrchar{M} \adrentry{Mustermann}{Hans} {Einbahnstra{\ss}e 1 \\ 01234 Heimstatt}{01234 / 5 67 89}{}{}{}{} \adrchar{D} \adrentry{{DANTE~e.\,V.}}{} {Postfach 10 18 40 \\ 69008 Heidelberg}{0 62 21 / 2 97 66}{}{}{}{DANTE} \end{verbatim} \end{small} In Version 1.2~c musste man den \Macro{adrchar}-Eintrag noch von Hand korrigieren, durch den \texttt{sortas}-Eintrag erfolgt das nun automatisch. Einen Brief an DANTE~e.\,V. k"onnen Sie mit Hilfe der \KOMAScript{} Briefklasse so beginnen: \begin{small} \begin{verbatim} \documentclass{scrlttr2} \usepackage{german} \begin{document} \begin{letter}{\DANTE} ... \end{verbatim} \end{small} Um Ihre Adressdateien aktuell zu halten, m"ussen Sie diese drei Schritte jedesmal wiederholen, wenn Sie "Anderungen an Ihrer Adressdatenbank vorgenommen haben. Bitte beachten Sie dabei, dass die drei Programme zum Erzeugen der \File{aux}-Datei (\File{adrconv.tex}, \File{birthday.tex} und \File{email.tex}) sowohl mit (Plain)\TeX{} als auch mit \LaTeX{} aufgerufen werden k"onnen, w"ahrend die beiden Programme \File{dir.tex} und \File{phone.tex}, die Sie nach erfolgreicher Konvertierung auf Ihre Adressdatei anwenden k"onnen, um daraus fertige Adress-, E-Mail- bzw. Telefonverzeichnisse zu produzieren, nur mit \LaTeX{} funktionieren. \end{document}