From b4fc5f639874db951177ec539299d20908adb654 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 9 Jan 2006 00:44:40 +0000 Subject: doc 4 git-svn-id: svn://tug.org/texlive/trunk@80 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/adrconv/adrguide.tex | 395 +++++++++++++++++++++++ 1 file changed, 395 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/adrconv/adrguide.tex (limited to 'Master/texmf-dist/doc/latex/adrconv/adrguide.tex') diff --git a/Master/texmf-dist/doc/latex/adrconv/adrguide.tex b/Master/texmf-dist/doc/latex/adrconv/adrguide.tex new file mode 100644 index 00000000000..547e6dca80f --- /dev/null +++ b/Master/texmf-dist/doc/latex/adrconv/adrguide.tex @@ -0,0 +1,395 @@ +\documentclass{article} +\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.2b} +\author{Axel Kielhorn} +\date{31. Mai 2003} +\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} + } +\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[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.}}, + 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 17 \\ + 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{{} + \adrentry{{DANTE~e.\,V.}}{} + {Postfach 10 18 40 \\ + 69008 Heidelberg}{0 62 21 / 2 97 66}{}{}{}{DANTE} +\end{verbatim} +\end{small} + +Der fehlende Vorname f"uhrt hier zu einem Fehler im +\Macro{adrchar}-Eintrag. Nachdem Sie ihn in: + +\begin{small} +\begin{verbatim} + \adrchar{D} +\end{verbatim} +\end{small} + +verbessert und zusammen mit dem Adress-Eintrag an die richtige Stelle +verschoben haben, k"onnen Sie einen Brief an DANTE~e.\,V. dann +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} -- cgit v1.2.3