summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/doc/scraddr-en.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/scraddr-en.tex')
-rw-r--r--macros/latex/contrib/koma-script/doc/scraddr-en.tex239
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: