doc 4

git-svn-id: svn://tug.org/texlive/trunk@80 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 395 insertions, 0 deletions

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}