You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
261 lines
10 KiB
261 lines
10 KiB
% ======================================================================
|
|
% scraddr.tex
|
|
% Copyright (c) Markus Kohm, 2001-2019
|
|
%
|
|
% 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-2019
|
|
%
|
|
% 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: 2019-10-30 09:32:39 +0100 (Wed, 30 Oct 2019) $
|
|
KOMA-Script guide (chapter: scraddr)]
|
|
\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm\and Karl
|
|
Hagen}
|
|
|
|
% Date of the translated German file: 2019-10-30
|
|
|
|
\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
|
|
%%% coding: us-ascii
|
|
%%% TeX-master: "../guide"
|
|
%%% End:
|
|
|