diff options
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/scraddr-en.tex')
-rw-r--r-- | macros/latex/contrib/koma-script/doc/scraddr-en.tex | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/doc/scraddr-en.tex b/macros/latex/contrib/koma-script/doc/scraddr-en.tex new file mode 100644 index 0000000000..187ae5646c --- /dev/null +++ b/macros/latex/contrib/koma-script/doc/scraddr-en.tex @@ -0,0 +1,239 @@ +% ====================================================================== +% scraddr-en.tex +% Copyright (c) Markus Kohm, 2001-2022 +% +% 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.md. +% ====================================================================== +% +% Chapter about scraddr of the KOMA-Script guide +% Maintained by Jens-Uwe Morawski (with help from Markus Kohm) +% +% ====================================================================== + +\KOMAProvidesFile{scraddr-en.tex} + [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $ + KOMA-Script guide (chapter: scraddr)] +\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm\and Karl + Hagen} + +\chapter{Accessing Address Files with \Package{scraddr}}% +\labelbase{scraddr}% +\BeginIndexGroup +\BeginIndex{Package}{scraddr} + +The \Package{scraddr} package is a small extension to \KOMAScript{}'s letter +class and letter package. Its goal is to make access to the data in address +files easier and more flexible. + +\section{Overview}\seclabel{overview} +Basically, the package provides a new loading mechanism for address files +consisting of \DescRef{\LabelBase.cmd.adrentry} and the newer +\DescRef{\LabelBase.cmd.addrentry} format entries, as described in +\autoref{cha:scrlttr2} starting on \DescPageRef{scrlttr2.cmd.adrentry}. + +\begin{Declaration} +\Macro{InputAddressFile}\Parameter{file name} +\end{Declaration}% +The \Macro{InputAddressFile} command is the main command of \Package{scraddr}. +It reads the content of the address file\Index{address>file} given as its +parameter. If the file is not found, an error message is issued. + +For each entry in this address file, the command generates a set of +macros to access the data. For large address files, this will require +a lot of \TeX{} memory. +% +\EndIndexGroup + +\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}% +The structure of the address entries in the address file was discussed in +detail in \autoref{sec:scrlttr2.addressFile}, starting on +\DescPageRef{scrlttr2.cmd.adrentry}. The subdivision of the address file with +the help of \Macro{adrchar} or \Macro{addrchar}, also discussed there, has no +meaning for \Package{scraddr} and is simply ignored by the package.% +\EndIndexGroup + +\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}% +These commands give access to data of your address file. The last parameter, +that is, parameter 8 for the \DescRef{\LabelBase.cmd.adrentry} entry and +parameter 9 for the \DescRef{\LabelBase.cmd.addrentry} entry, is the +identifier of an entry, thus the \PName{key} has to be unique and non-empty. +To guarantee safe functioning, you should use only ASCII letters in the +\PName{key}. + +Furthermore, if the file contains more than one entry with the same +\PName{key} name, the last occurrence will be used.% +% +\EndIndexGroup + + +\section{Usage}\seclabel{usage} +\BeginIndexGroup +\BeginIndex[indexother]{Cmd}{addrentry}% +\BeginIndex[indexother]{Cmd}{adrentry}% +To use the package, we need a valid address file. For example, the file +\File{lotr.adr} 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}% + {3 Bagshot Row\\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 fourth parameter, the telephone number, has been left blank, since there +are no phones in Middle Earth. And as you can see, blank fields are possible. +On the other hand, you cannot simply omit an argument altogether. + +\BeginIndexGroup +\BeginIndex[indexother]{Cmd}{InputAddressFile} +With the \Macro{InputAddressFile} command described above, we read the address +file into our letter document: +\begin{lstcode} + \InputAddressFile{lotr} +\end{lstcode} +\EndIndexGroup + +\BeginIndexGroup +\BeginIndex[indexother]{Cmd}{Name}% +\BeginIndex[indexother]{Cmd}{Address}% +\BeginIndex[indexother]{Cmd}{FirstName}% +\BeginIndex[indexother]{Cmd}{LastName}% +\BeginIndex[indexother]{Cmd}{FreeI}% +\BeginIndex[indexother]{Cmd}{FreeII}% +\BeginIndex[indexother]{Cmd}{FreeIII}% +\BeginIndex[indexother]{Cmd}{FreeIV}% +\BeginIndex[indexother]{Cmd}{Comment}% +With the help of the commands introduced in this chapter we can now write a +letter to old \textsc{Tom Bombadil}, in which we ask him if he can remember +two companions from olden times. +\begin{lstcode} + \begin{letter}{\Name{TOM}\\\Address{TOM}} + \opening{Dear \FirstName{TOM} \LastName{TOM},} + + Or \FreeIII{TOM}, as your beloved \FreeI{TOM} calls you. Do + you still remember Mr \LastName{FRODO}, or more precisely + \Name{FRODO}, since there was also Mr \FreeI{FRODO}. He was + \Comment{FRODO} in the Third Age and \FreeIV{FRODO}. \Name{SAM}, + \Comment{SAM}, accompanied him. + + Their passions were very worldly. \FirstName{FRODO} enjoyed + smoking \FreeII{FRODO}. His companion 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} +You can also produce the combination of \Macro{FirstName}\Parameter{key} and +\Macro{LastName}\Parameter{key} used in the \DescRef{scrlttr2.cmd.opening} of +this letter with \Macro{Name}\PParameter{key}. + +You can use the fifth and sixth parameters of the +\DescRef{\LabelBase.cmd.adrentry} or \DescRef{\LabelBase.cmd.adrentry} for any +purpose you wish. You can access them with the \Macro{FreeI} and +\Macro{FreeII} commands. In this example, the fifth parameter contains the +name of the most important person in the life of the person in the entry. The +sixth contains the person's favourite thing. The seventh parameter is a +comment or in general also a free parameter. You can access it with the +\Macro{Comment} or \Macro{FreeIII} commands. \Macro{FreeIV} is only valid for +\DescRef{\LabelBase.cmd.addrentry} entries. For +\DescRef{\LabelBase.cmd.adrentry} entries, it results in an error. You can +find more details in the next section. +% +\EndIndexGroup +\EndIndexGroup + + +\section{Package Warning Options} + +As mentioned above, you cannot use the \Macro{FreeIV} command with +\DescRef{\LabelBase.cmd.adrentry} entries. However, you can configure how +\Package{scraddr} reacts in such a situation by package options. +Note\textnote{Attention!} that this package does not support the extended +options interface with \DescRef{maincls.cmd.KOMAoptions} and +\DescRef{maincls.cmd.KOMAoption}. You should therefore specify the options +either as global options in \DescRef{maincls.cmd.documentclass} or as local +options in \DescRef{maincls.cmd.usepackage} + + +\begin{Declaration} + \Option{adrFreeIVempty}% + \Option{adrFreeIVshow}% + \Option{adrFreeIVwarn}% + \Option{adrFreeIVstop}% +\end{Declaration}% +These four options let you choose from four different reactions, ranging +from \emph{ignore} to \emph{abort}, if \Macro{FreeIV} is used +within an \DescRef{\LabelBase.cmd.adrentry} entry. + +\begin{labeling}[~--]{\Option{adrFreeIVempty}} +\item[\Option{adrFreeIVempty}] + the command \Macro{FreeIV} will be ignored +\item[\Option{adrFreeIVshow}] + the warning ``(entry FreeIV undefined at \PName{key})'' will be + written in the text +\item[\Option{adrFreeIVwarn}] + a warning is written in the logfile +\item[\Option{adrFreeIVstop}] + the \LaTeX{} run will abort with an error message +\end{labeling} +The default setting is \Option{adrFreeIVshow}.% +\EndIndexGroup +% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "scrguide-en.tex" +%%% coding: utf-8 +%%% ispell-local-dictionary: "en_GB" +%%% eval: (flyspell-mode 1) +%%% End: |