\ProvidesFile{adressen.tex}[2003/04/16 KOMA-Script Anleitung]
% ============================================================================
% adressen.tex 
% Copyright (c) 2001 Markus Kohm and the authors.
%
% This file is part of the LaTeX2e KOMA-Script-Bundle
%
% This file can be redistributed and/or modified under the terms of the LaTeX
% Project Public License Version 1.0 distributed together with this file. See
% LEGAL.TXT or LEGALDE.TXT.
%
% This bundle is written specialy for use at german-language. So the main
% documentation is german. There may also be an english documentation. See
% readme.txt, if you search for it.
% ----------------------------------------------------------------------------
% adressen.tex
% Copyright (c) 2001 Markus Kohm und bei den weiteren Autoren.
%
% Diese Datei ist Teil des LaTeX2e KOMA-Script-Pakets.
%
% Diese Datei kann nach den Regeln der LaTeX Project Public Licence 
% Version 1.0, wie sie zusammen mit dieser Datei verteilt wird,
% weiterverbreitet und/oder modifiziert werden. Siehe dazu auch LEGAL.TXT oder
% LEGALDE.TXT.
%
% Dieses Paket ist fuer den deutschen Sprachraum konzipiert. Daher ist auch
% diese Anleitung komplett in Deutsch. Moeglicherweise existiert auch eine
% englische Version der Anleitung. Falls Sie eine solche benoetigen, schauen
% Sie bitte in liesmich.txt nach, ob eine solche vorhanden ist.
% ============================================================================
%
% Modul:    scraddr Paket
% Autoren:  Jens-Uwe Morawski <morawski@gmx.net>
% Inhalt:   Zugriff auf Adressen mit Hilfe von scraddr
% Sprache:  Deutsch
% Zeichensatz der Kommentare:
%           US-ASCII
%

\chapter{Adressdateien mit \Package{scraddr} erschließen}\label{cha:scraddr}
\BeginIndex{Package}{scraddr}

\section{Überblick}\label{sec:scraddr.overview}
Das Paket \Package{scraddr} ist eine kleine Beigabe zur
\KOMAScript-Briefklasse.
Ziel ist, die Benutzung von Adressdateien zu vereinfachen
und ihre Anwendung flexibler zu gestalten.
Im Grunde stellt das Paket nur einen Lademechanismus für Adressdateien
bereit, die aus \Macro{adrentry}- und neueren \Macro{addrentry}-Einträgen
bestehen, wie sie im vorhergehenden Kapitel beschrieben sind.

\begin{Declaration}
\Macro{InputAddressFile}\Parameter{Dateiname}
\end{Declaration}%
\BeginIndex{Cmd}{InputAddressFile}%
%
Der Befehl \Macro{InputAddressFile} ist der zentrale Ladebefehl
von \Package{scraddr}.
Er erwartet als obligatorisches Argument den
Namen der einzulesenden Adressdatei.\Index{Adressdatei}
Wird diese Datei nicht gefunden, wird ein Fehler ausgegeben.

Für jeden Eintrag dieser Adressdatei wird eine Reihe von Makros generiert,
die es ermöglichen, auf die Daten der Adressdatei zuzugreifen.
Zur Erinnerung nochmals der Aufbau eines Eintrags.
\begin{Declaration}%

  \Macro{adrentry}\Parameter{Name}\Parameter{Vorname}\Parameter{Adresse}%

  \Parameter{Telefon}\Parameter{F1}\Parameter{F2}%

  \Parameter{Kommentar}\Parameter{Kürzel}\\
  %
  %oder\\
  %
  \Macro{addrentry}\Parameter{Name}\Parameter{Vorname}\Parameter{Adresse}%

  \Parameter{Telefon}\Parameter{F1}\Parameter{F2}%

  \Parameter{F3}\Parameter{F4}\Parameter{Kürzel}%
\end{Declaration}%

Die Zugriffsbefehle sind mit englischen, den Argumenten entsprechenden,
Bezeichnungen versehen.
\begin{Declaration}
\Macro{Name}\Parameter{Kürzel}\\
\Macro{FirstName}\Parameter{Kürzel}\\
\Macro{LastName}\Parameter{Kürzel}\\
\Macro{Address}\Parameter{Kürzel}\\
\Macro{Telephone}\Parameter{Kürzel}\\
\Macro{FreeI}\Parameter{Kürzel}\\
\Macro{FreeII}\Parameter{Kürzel}\\
\Macro{Comment}\Parameter{Kürzel}\\
\Macro{FreeIII}\Parameter{Kürzel}\\
\Macro{FreeIV}\Parameter{Kürzel}
\end{Declaration}%
\BeginIndex{Cmd}{Name}\BeginIndex{Cmd}{FirstName}\BeginIndex{Cmd}{LastName}%
\BeginIndex{Cmd}{Address}\BeginIndex{Cmd}{Telephone}\BeginIndex{Cmd}{FreeI}%
\BeginIndex{Cmd}{FreeII}\BeginIndex{Cmd}{FreeIII}\BeginIndex{Cmd}{FreeIV}
\BeginIndex{Cmd}{Comment}%
%
Der Zugriff erfolgt anhand des Kürzels im letzten Argument eines
Eintrags, das heißt Argument Nummer 8
für \Macro{adrentry}-Einträge beziehungsweise Argument Nummer 9
für \Macro{addrentry}-Einträge. Das bedeutet auch, dass dieses Argument
nicht leer sein darf.
Um eine sichere Funktionsweise zu garantieren, empfiehlt es sich,
das Kürzel nur als Folge Buchstaben aufzubauen,
wobei jedoch keine Umlaute benutzt werden dürfen.

Weiterhin ist zu beachten, dass bei mehrmaligem Auf"|treten
eines Kürzels in den Einträgen die Angaben beim
letzten Auf"|treten die gültigen sind.

\EndIndex{Cmd}{InputAddressFile}%
\EndIndex{Cmd}{Name}\EndIndex{Cmd}{FirstName}\EndIndex{Cmd}{LastName}%
\EndIndex{Cmd}{Address}\EndIndex{Cmd}{Telephone}\EndIndex{Cmd}{FreeI}%
\EndIndex{Cmd}{FreeII}\EndIndex{Cmd}{FreeIII}\EndIndex{Cmd}{FreeIV}%
\EndIndex{Cmd}{Comment}%

\section{Benutzung}\label{sec:scraddr.usage}

Um das Paket benutzen zu können, ist eine gültige
Adressdatei zu erstellen.
Diese, hier \emph{lotr.adr} genannt, könnte beispielsweise
folgendermaßen aussehen:
\begin{verbatim}
  \addrentry{Beutlin}{Frodo}%
            {Der Bühl\\ Beutelsend/Hobbingen im Auenland}{}%
            {Bilbo Beutlin}{Rauchen von Pfeifenkraut}%
            {der Ringträger}{Bilbo's Erbe}{FRODO}
  \adrentry{Gamdschie}{Samweis}%
            {Beutelhaldenweg 3\\Hobbingen im Auenland}{}%
            {Rosie Kattun}{Knullen}%
            {des Ringträgers treuester Gefährte}{SAM}
  \adrentry{Bombadil}{Tom}%
            {Im Alten Wald}{}%
            {Goldbeere}{trällern von Nonsensliedern}%
            {Meister von Wald, Wasser und Berg}{TOM}
\end{verbatim}

Das vierte Argument, die Telefonnummer, wurde hier leer gelassen.
Erstens macht es in dem Zusammenhang keinen Sinn, und zweitens sollte
dies ja auch möglich sein.

Mit dem oben beschriebenen Ladebefehl lesen wir die Adressdatei
in unser Briefdokument ein:
\begin{verbatim}
  \InputAddressFile{lotr}
\end{verbatim}

Mit Hilfe der vorgestellten Makros können wir dann einen Brief
an den alten \textsc{Tom Bombadil} schreiben, in dem wir ihn
fragen, ob er sich noch an zwei Gefährten aus alter Zeit
erinnern kann.
\begin{verbatim}
  \begin{letter}{\Name{TOM}\\\Address{TOM}}
     \opening{Lieber \FirstName{TOM} \LastName{TOM},}
     
      oder \FreeIII{TOM}, wie Dich Deine geliebte
      \FreeI{TOM} nennt.
      Kannst Du Dich noch an einen Herrn \LastName{FRODO},
      genauer gesagt \Name{FRODO}, denn es gab ja auch noch
      den Herrn \FreeI{FRODO}, erinnern.
      Er war \Comment{FRODO} im dritten Zeitalter und
      \FreeIV{FRODO}.
      Begleitet wurde er von \Name{SAM}, \Comment{SAM}.
      
      Beider Vorlieben waren sehr weltlich.
      Der \FirstName{FRODO} genoss das \FreeII{FRODO}, sein
      Gefährte schätzte eine gute Mahlzeit mit \FreeII{SAM}.
      
      Weißt du noch? Mithrandir hat Dir bestimmt viel
      von ihnen erzählt.
    \closing{\glqq O Frühling und Sommerzeit
                    und danach wieder Frühling!\\
                   O Wind auf dem Wasserfall
                    und Lachen des Laubes!\grqq}
  \end{letter}
\end{verbatim}

Die Zusammensetzung aus
\Macro{FirstName}\Parameter{Kürzel} \Macro{LastName}\Parameter{Kürzel}
kann direkt mittels \Macro{Name}\Parameter{Kürzel} erhalten werden.

Das fünf"|te und sechste Argument von \Macro{adrentry} und
\Macro{addrentry} steht zur freien Verfügung.
Mit den Makros \Macro{FreeI} und \Macro{FreeII} kann auf
diese Inhalte zugegriffen werden. Im vorliegenden Fall wurde
das fünf"|te Argument für die Person benutzt, die der Person des
Eintrags am nächsten steht. Das sechste Argument
enthält im Beispiel die besondere Vorliebe der jeweiligen Person.
Das siebente Argument ist ebenfalls ein freier Eintrag. Der Zugriff
erfolgt per \Macro{Comment} oder \Macro{FreeIII}.
Der Zugriff auf das vierte freie Argument mittels \Macro{FreeIV}
ist nur für \Macro{addrentry}-Einträge gültig.
Bei \Macro{adrentry}-Einträgen liefert das eine Warnung.
\EndIndex{Package}{scraddr}

\section{Paketoptionen für Warnungen}

Wie oben bereits beschrieben, führt die Benutzung des
Zugriffbefehls \Macro{FreeIV} zu einem Fehler, wenn der
Befehl auf Datensätze aus \Macro{adrentry}-Einträgen
angewendet wird.

Die hier im Folgenden aufgeführten Paketoptionen legen
fest, wie in solchen Situationen reagiert werden soll.
Dabei ist es möglich, im Bereich von \emph{Ignorieren} bis
\emph{Abbruch} verschiedene Möglichkeiten zu wählen.
Eine dieser Paketoptionen kann beim Laden des Pakets im
optionalen Argument des \Macro{usepackage}-Befehls
übergeben werden. Die standardmäßige Einstellung für
das Paket \Package{scraddr} ist die Option
\Option{adrFreeIVshow}.

\begin{Declaration}
\Option{adrFreeIVempty}\\
\Option{adrFreeIVshow}\\
\Option{adrFreeIVwarn}\\
\Option{adrFreeIVstop}
\end{Declaration}
%
\BeginIndex{Option}{adrFreeIVempty}\BeginIndex{Option}{adrFreeIVshow}
\BeginIndex{Option}{adrFreeIVwarn}\BeginIndex{Option}{adrFreeIVstop}
%
\begin{labeling}[\,--]{\Option{adrFreeIVempty}}
\item[\Option{adrFreeIVempty}] 
        Der Befehl \Macro{FreeIV} wird einfach ignoriert.
\item[\Option{adrFreeIVshow}] 
        Die Warnung \glqq(entry FreeIV undefined at \PName{Kürzel})\grqq{}
           wird in den Text geschrieben.
\item[\Option{adrFreeIVwarn}]
        In der Log-Datei erscheint eine Warnung.
\item[\Option{adrFreeIVstop}]
        Der \LaTeX{}-Lauf wird mit einer Fehlermeldung unterbrochen.
\end{labeling}
\EndIndex{Option}{adrFreeIVempty}\EndIndex{Option}{adrFreeIVshow}
\EndIndex{Option}{adrFreeIVwarn}\EndIndex{Option}{adrFreeIVstop}

\section{Autoren}
\label{sec:scraddr.autoren}
Die folgenden Autoren waren an diesem Kapitel beteiligt oder haben die Vorlage
dafür geliefert.
% In folgener Aufzaehlung den Namen des Autors, der fuer das Kapitel
% verantwortlich ist bitte mit \textbf{} hervorheben.
\begin{itemize}
\item \textbf{Jens-Uwe Morawski}
\end{itemize}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "scrguide2"
%%% End: 
