% ======================================================================
% scraddr.tex
% Copyright (c) Markus Kohm, 2001-2009
%
% This file is part of the LaTeX2e KOMA-Script bundle.
%
% This work may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, version 1.3b of the license.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3b or later is part of all distributions of LaTeX 
% version 2005/12/01 or later and of this work.
%
% This work has the LPPL maintenance status "author-maintained".
%
% The Current Maintainer and author of this work is Markus Kohm.
%
% This work consists of all files listed in manifest.txt.
% ----------------------------------------------------------------------
% scraddr.tex
% Copyright (c) Markus Kohm, 2001-2009
%
% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz,
% Version 1.3b, verteilt und/oder veraendert werden.
% Die neuste Version dieser Lizenz ist
%   http://www.latex-project.org/lppl.txt
% und Version 1.3b ist Teil aller Verteilungen von LaTeX
% Version 2005/12/01 oder spaeter und dieses Werks.
%
% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained"
% (allein durch den Autor verwaltet).
%
% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm.
% 
% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien.
% ======================================================================
%
% Chapter about scraddr of the KOMA-Script guide
% Maintained by Jens-Uwe Morawski (with help from Markus Kohm)
%
% ----------------------------------------------------------------------
%
% Kapitel ueber scraddr in der KOMA-Script-Anleitung
% Verwaltet von Jens-Uwe Morawski (mit Unterstuetzung von Markus Kohm)
%
% ======================================================================

\ProvidesFile{scraddr.tex}[2008/07/10 KOMA-Script guide (chapter: scraddr)]
\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm}

% Date of translated german file: 2005/08/10

\chapter{Access to Address Files with \Package{scraddr}}%
\labelbase{scraddr}%
\BeginIndex{Package}{scraddr}

\section{Overview}\label{sec:scraddr.overview}
The package \Package{scraddr} is a small extension to the
{\KOMAScript} letter class.  Its aim is to make access to the data of
address files more flexible and easier.  Basically, the package
implements a new loading mechanism for address files which contain
address entries in the form of \Macro{adrentry} and newer
\Macro{addrentry} commands, as described in the previous chapter.

\begin{Declaration}
\Macro{InputAddressFile}\Parameter{file name}
\end{Declaration}%
\BeginIndex{Cmd}{InputAddressFile}%
%
The command \Macro{InputAddressFile} is the main command of the
\Package{scraddr}, and reads the content of the address
file\Index{address>file} given as its parameter.  If the file does not
exist the command returns an error message.

For every entry in the address file the command generates a set of
macros for accessing the data. For large address files this will take
a lot of {\TeX} memory. 

\begin{Declaration}%
  \Macro{adrentry}\Parameter{Lastname}\Parameter{Firstname}%
  \Parameter{Address}\Parameter{Phone}\Parameter{F1}\Parameter{F2}%
  \Parameter{Comment}\Parameter{Key}\\
  %
  \Macro{addrentry}\Parameter{Lastname}\Parameter{Firstname}%
  \Parameter{Address}\Parameter{Phone}\Parameter{F1}\Parameter{F2}%
  \Parameter{F3}\Parameter{F4}\Parameter{Key}\\
  %
  \Macro{adrchar}\Parameter{initial}\\
  \Macro{addrchar}\Parameter{initial}%
\end{Declaration}%
\IndexCmd{adrentry}%
\IndexCmd{addrentry}%
\IndexCmd{adrchar}%
\IndexCmd{addrchar}%

The structure of the address entries in the address file was discussed
in detail in \autoref{sec:scrlttr2.addressFile} from
\autopageref{desc:scrlttr2.cmd.adrentry} onwards.  The division of
the address file with the help of \Macro{adrchar} or \Macro{addrchar},
also discussed therein, has no meaning for \Package{scraddr} and is
simply ignored.

The commands for accessing the data are given by the name of the data
field they are intended for.
\begin{Declaration}
\Macro{Name}\Parameter{Key}\\
\Macro{FirstName}\Parameter{Key}\\
\Macro{LastName}\Parameter{Key}\\
\Macro{Address}\Parameter{Key}\\
\Macro{Telephone}\Parameter{Key}\\
\Macro{FreeI}\Parameter{Key}\\
\Macro{FreeII}\Parameter{Key}\\
\Macro{Comment}\Parameter{Key}\\
\Macro{FreeIII}\Parameter{Key}\\
\Macro{FreeIV}\Parameter{Key}
\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}%
%

These commands give access to data of your address file.  The last
parameter, i.\,e., parameter 8 for the \Macro{adrentry} entry and
parameter 9 for the \Macro{addrentry} entry, is the identifier of an
entry, thus the \PName{Key} has to be unique and non-blank. The
\PName{Key} should only be composed of letters.

If the file contains more than one entry with the same \PName{Key}
value, the last occurrence will be used.


\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{Usage}\label{sec:scraddr.usage}

First of all, we need an address file with valid address entries.  In
this example the file has the name \File{lotr.adr} and contains the
following entries.
\begin{lstlisting}
  \addrentry{Baggins}{Frodo}%
            {The Hill\\ Bag End/Hobbiton in the Shire}{}%
            {Bilbo Baggins}{pipe-weed}%
            {the Ring-bearer}{Bilbo's heir}{FRODO}
  \adrentry{Gamgee}{Samwise}%
            {Bagshot Row 3\\Hobbiton in the Shire}{}%
            {Rosie Cotton}{taters}%
            {the Ring-bearer's faithful servant}{SAM}
  \adrentry{Bombadil}{Tom}%
            {The Old Forest}{}%
            {Goldberry}{trill queer songs}%
            {The Master of Wood, Water and Hill}{TOM}
\end{lstlisting}

The 4\textsuperscript{th} parameter, the telephone number, has been
left blank. If you know the story behind these addresses you will
agree that a telephone number makes no sense here, and besides, it
should simply be possible to leave them out. The command
\Macro{InputAddressFile} is used to load the address file shown above:
\begin{lstlisting}
  \InputAddressFile{lotr}
\end{lstlisting}


With the help of the commands introduced in this chapter we can now
write a letter to old \textsc{Tom Bombadil}.  In this letter we ask
him if he can remember two fellow-travelers from Elder Days.
\begin{lstlisting}
  \begin{letter}{\Name{TOM}\\\Address{TOM}}
     \opening{Dear \FirstName{TOM} \LastName{TOM},}
     
     or \FreeIII{TOM}, how your delightful \FreeI{TOM} calls you.  Can
     you remember Mr.\,\LastName{FRODO}, strictly speaking
     \Name{FRODO}, since there was Mr.\,\FreeI{FRODO} too.  He was
     \Comment{FRODO} in the Third Age and \FreeIV{FRODO} \Name{SAM},
     \Comment{SAM}, has attended him.
      
      Their passions were very worldly.  \FirstName{FRODO} enjoyed
      smoking \FreeII{FRODO}, his attendant appreciated a good meal with
      \FreeII{SAM}.

      Do you remember? Certainly Mithrandir has told you much
      about their deeds and adventures .
    \closing{``O spring-time and summer-time
                and spring again after!\\
               O wind on the waterfall,
                and the leaves' laughter!''}
  \end{letter}
\end{lstlisting}
In the address of letters often both firstname and lastname are
required.  Thus, the command \Macro{Name}\PParameter{Key} is an
abridgement for \Macro{FirstName}\PParameter{Key}
\Macro{LastName}\PParameter{Key}.

The 5\textsuperscript{th} and 6\textsuperscript{th} parameters of the
\Macro{adrentry} or \Macro{adrentry} commands are for free use.  They
are accessible with the commands \Macro{FreeI} and \Macro{FreeII}.  In
this example, the 5\textsuperscript{th} parameter contains the name of
a person who is the most important in the life of the entry's person,
the 6\textsuperscript{th} contains the person's passion.  The
7\textsuperscript{th} parameter is a comment or in general also a free
parameter. The commands \Macro{Comment} or \Macro{FreeIII} give access
to this data. Use of \Macro{FreeIV} is only valid for
\Macro{addrentry} entries; for \Macro{adrentry} entries it results in
an error. More on this is covered in the next section.
\EndIndex{Package}{scraddr}

\section{Package Warning Options}

As mentioned above, the command \Macro{FreeIV} leads to an error if it
is used for \Macro{adrentry} entries. How \Package{scraddr} reacts in
such a situation is decide by package options.

\begin{Declaration}
\Option{adrFreeIVempty}\\
\Option{adrFreeIVshow}\\
\Option{adrFreeIVwarn}\\
\Option{adrFreeIVstop}
\end{Declaration}
%
\BeginIndex{Option}{adrFreeIVempty}\BeginIndex{Option}{adrFreeIVshow}
\BeginIndex{Option}{adrFreeIVwarn}\BeginIndex{Option}{adrFreeIVstop}
%
These four options allow the user to choose between \emph{ignore} and
\emph{rupture} during the {\LaTeX} run if \Macro{FreeIV} has been used
with an \Macro{adrentry} entry.

\begin{labeling}[\,--]{\Option{adrFreeIVempty}}
\item[\Option{adrFreeIVempty}] 
        the command \Macro{FreeIV} will be ignored
\item[\Option{adrFreeIVshow}] 
        ``(entry FreeIV undefined at \PName{Key})'' will be
        written as warning in the text
\item[\Option{adrFreeIVwarn}]
        writes a warning in the logfile
\item[\Option{adrFreeIVstop}]
        the {\LaTeX} run will be interrupted with an error message
\end{labeling}
To choose the desired reaction, one of these options can be given in
the optional argument of the \Macro{usepackage} command. The default
setting is \Option{adrFreeIVshow}.
%
\EndIndex{Option}{adrFreeIVempty}\EndIndex{Option}{adrFreeIVshow}
\EndIndex{Option}{adrFreeIVwarn}\EndIndex{Option}{adrFreeIVstop}


%%% Local Variables: 
%%% mode: latex
%%% coding: iso-latin-1
%%% TeX-master: "../guide"
%%% End: