% ====================================================================== % scraddr.tex % Copyright (c) Markus Kohm, 2001-2010 % % 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-2010 % % 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) % % ====================================================================== \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: