% ======================================================================
% scraddr.tex
% Copyright (c) Markus Kohm, 2001-2015
%
% 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.3c of the license.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3c 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-2015
%
% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz,
% Version 1.3c, verteilt und/oder veraendert werden.
% Die neuste Version dieser Lizenz ist
%   http://www.latex-project.org/lppl.txt
% und Version 1.3c 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)
%
% ======================================================================

\KOMAProvidesFile{scraddr.tex}
                 [$Date: 2015-03-31 11:10:59 +0200 (Tue, 31 Mar 2015) $
                  KOMA-Script guide (chapter: scraddr)]
\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm}

% Date of translated german file: 2015-03-31

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

\section{Overview}\seclabel{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 \autoref{cha:scrlttr2}
from \autopageref{desc:scrlttr2.cmd.adrentry}.

\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 multiple uppercase letters out of the
namespace of \TeX{} macro names.

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}\seclabel{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{lstcode}
  \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{lstcode}

The 4th 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{lstcode}[belowskip=\dp\strutbox]
  \InputAddressFile{lotr}
\end{lstcode}


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{lstcode}[belowskip=\dp\strutbox]
  \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{lstcode}
In the address of letters often both firstname and lastname are required, als
shown above in \Macro{opening}.  Thus, the command
\Macro{Name}\PParameter{key} is an abridgement for
\Macro{FirstName}\PParameter{key} \Macro{LastName}\PParameter{key}.

The 5th and 6th 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 5th parameter contains
the name of a person who is the most important in the life of the entry's
person, the 6th contains the person's passion.  The 7th 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}

\endinput

%%% Local Variables: 
%%% mode: latex
%%% coding: us-ascii
%%% TeX-master: "../guide"
%%% End: