path: root/Master/texmf-dist/doc/latex/adrconv/adrguide.tex

%% 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}