\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} erschlieen}\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 fr Adressdateien
bereit, die aus \Macro{adrentry}- und neueren \Macro{addrentry}-Eintrgen
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.

Fr jeden Eintrag dieser Adressdatei wird eine Reihe von Makros generiert,
die es ermglichen, 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{Krzel}\\
  %
  %oder\\
  %
  \Macro{addrentry}\Parameter{Name}\Parameter{Vorname}\Parameter{Adresse}%

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

  \Parameter{F3}\Parameter{F4}\Parameter{Krzel}%
\end{Declaration}%

Die Zugriffsbefehle sind mit englischen, den Argumenten entsprechenden,
Bezeichnungen versehen.
\begin{Declaration}
\Macro{Name}\Parameter{Krzel}\\
\Macro{FirstName}\Parameter{Krzel}\\
\Macro{LastName}\Parameter{Krzel}\\
\Macro{Address}\Parameter{Krzel}\\
\Macro{Telephone}\Parameter{Krzel}\\
\Macro{FreeI}\Parameter{Krzel}\\
\Macro{FreeII}\Parameter{Krzel}\\
\Macro{Comment}\Parameter{Krzel}\\
\Macro{FreeIII}\Parameter{Krzel}\\
\Macro{FreeIV}\Parameter{Krzel}
\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 Krzels im letzten Argument eines
Eintrags, das heit Argument Nummer 8
fr \Macro{adrentry}-Eintrge beziehungsweise Argument Nummer 9
fr \Macro{addrentry}-Eintrge. Das bedeutet auch, dass dieses Argument
nicht leer sein darf.
Um eine sichere Funktionsweise zu garantieren, empfiehlt es sich,
das Krzel nur als Folge Buchstaben aufzubauen,
wobei jedoch keine Umlaute benutzt werden drfen.

Weiterhin ist zu beachten, dass bei mehrmaligem Auf"|treten
eines Krzels in den Eintrgen die Angaben beim
letzten Auf"|treten die gltigen 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 knnen, ist eine gltige
Adressdatei zu erstellen.
Diese, hier \emph{lotr.adr} genannt, knnte beispielsweise
folgendermaen aussehen:
\begin{verbatim}
  \addrentry{Beutlin}{Frodo}%
            {Der Bhl\\ Beutelsend/Hobbingen im Auenland}{}%
            {Bilbo Beutlin}{Rauchen von Pfeifenkraut}%
            {der Ringtrger}{Bilbo's Erbe}{FRODO}
  \adrentry{Gamdschie}{Samweis}%
            {Beutelhaldenweg 3\\Hobbingen im Auenland}{}%
            {Rosie Kattun}{Knullen}%
            {des Ringtrgers treuester Gefhrte}{SAM}
  \adrentry{Bombadil}{Tom}%
            {Im Alten Wald}{}%
            {Goldbeere}{trllern 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 mglich 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 knnen wir dann einen Brief
an den alten \textsc{Tom Bombadil} schreiben, in dem wir ihn
fragen, ob er sich noch an zwei Gefhrten 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
      Gefhrte schtzte eine gute Mahlzeit mit \FreeII{SAM}.
      
      Weit du noch? Mithrandir hat Dir bestimmt viel
      von ihnen erzhlt.
    \closing{\glqq O Frhling und Sommerzeit
                    und danach wieder Frhling!\\
                   O Wind auf dem Wasserfall
                    und Lachen des Laubes!\grqq}
  \end{letter}
\end{verbatim}

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

Das fnf"|te und sechste Argument von \Macro{adrentry} und
\Macro{addrentry} steht zur freien Verfgung.
Mit den Makros \Macro{FreeI} und \Macro{FreeII} kann auf
diese Inhalte zugegriffen werden. Im vorliegenden Fall wurde
das fnf"|te Argument fr die Person benutzt, die der Person des
Eintrags am nchsten steht. Das sechste Argument
enthlt 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 fr \Macro{addrentry}-Eintrge gltig.
Bei \Macro{adrentry}-Eintrgen liefert das eine Warnung.
\EndIndex{Package}{scraddr}

\section{Paketoptionen fr Warnungen}

Wie oben bereits beschrieben, fhrt die Benutzung des
Zugriffbefehls \Macro{FreeIV} zu einem Fehler, wenn der
Befehl auf Datenstze aus \Macro{adrentry}-Eintrgen
angewendet wird.

Die hier im Folgenden aufgefhrten Paketoptionen legen
fest, wie in solchen Situationen reagiert werden soll.
Dabei ist es mglich, im Bereich von \emph{Ignorieren} bis
\emph{Abbruch} verschiedene Mglichkeiten zu whlen.
Eine dieser Paketoptionen kann beim Laden des Pakets im
optionalen Argument des \Macro{usepackage}-Befehls
bergeben werden. Die standardmige Einstellung fr
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{Krzel})\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
dafr 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: