summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scraddr.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scraddr.tex')
-rw-r--r--Master/texmf-dist/source/latex/koma-script/doc/english/scraddr.tex200
1 files changed, 108 insertions, 92 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scraddr.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scraddr.tex
index a4a7c5454e2..ac5ef90a5e7 100644
--- a/Master/texmf-dist/source/latex/koma-script/doc/english/scraddr.tex
+++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scraddr.tex
@@ -1,6 +1,6 @@
% ======================================================================
% scraddr.tex
-% Copyright (c) Markus Kohm, 2001-2017
+% Copyright (c) Markus Kohm, 2001-2018
%
% This file is part of the LaTeX2e KOMA-Script bundle.
%
@@ -18,7 +18,7 @@
% This work consists of all files listed in manifest.txt.
% ----------------------------------------------------------------------
% scraddr.tex
-% Copyright (c) Markus Kohm, 2001-2017
+% Copyright (c) Markus Kohm, 2001-2018
%
% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz,
% Version 1.3c, verteilt und/oder veraendert werden.
@@ -46,36 +46,40 @@
% ======================================================================
\KOMAProvidesFile{scraddr.tex}
- [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $
+ [$Date: 2018-03-27 11:46:14 +0200 (Tue, 27 Mar 2018) $
KOMA-Script guide (chapter: scraddr)]
-\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm}
+\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm\and Karl
+ Hagen}
-% Date of the translated German file: 2017-01-02
+% Date of the translated German file: 2018-02-05
-\chapter{Access to Address Files with \Package{scraddr}}%
+\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}
-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 \DescRef{\LabelBase.cmd.adrentry}
-and newer \DescRef{\LabelBase.cmd.addrentry} commands, as described in \autoref{cha:scrlttr2}
-from \DescPageRef{scrlttr2.cmd.adrentry}.
+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 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.
+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 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.
+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}%
@@ -89,15 +93,12 @@ a lot of {\TeX} memory.
\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} from
-\DescPageRef{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.
+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}%
@@ -111,35 +112,32 @@ field they are intended for.
\Macro{FreeIII}\Parameter{key}%
\Macro{FreeIV}\Parameter{key}
\end{Declaration}%
-These commands give access to data of your address file. The last
-parameter, i.\,e., 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-blank. The
-\PName{key} should only be composed of multiple uppercase letters out of the
-namespace of \TeX{} macro names.
+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}.
-If the file contains more than one entry with the same \PName{key}
-value, the last occurrence will be used.%
-%
-\EndIndexGroup
-%
-\EndIndexGroup
+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}
-
-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.
+\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}%
- {Bagshot Row 3\\Hobbiton in the Shire}{}%
+ {3 Bagshot Row\\Hobbiton in the Shire}{}%
{Rosie Cotton}{taters}%
{the Ring-bearer's faithful servant}{SAM}
\adrentry{Bombadil}{Tom}%
@@ -148,64 +146,85 @@ following entries.
{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 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.
-The command
-\Macro{InputAddressFile} is used to load the address file shown above:
+\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
-
-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.
+\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}, 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.
+ 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 attendant appreciated a good meal with
- \FreeII{SAM}.
+ 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 .
+ 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 \DescRef{scrlttr2.cmd.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 \DescRef{\LabelBase.cmd.adrentry} or \DescRef{\LabelBase.cmd.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 \DescRef{\LabelBase.cmd.addrentry} entries; for \DescRef{\LabelBase.cmd.adrentry} entries
-it results in an error. More on this is covered in the next section.
+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, the command \Macro{FreeIV} leads to an error if it is used
-for \DescRef{\LabelBase.cmd.adrentry} entries. How \Package{scraddr} reacts in
-such a situation is decide by package 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}%
@@ -213,25 +232,22 @@ such a situation is decide by package options.
\Option{adrFreeIVwarn}%
\Option{adrFreeIVstop}%
\end{Declaration}%
-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 \DescRef{\LabelBase.cmd.adrentry} entry.
+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}]
- ``(entry FreeIV undefined at \PName{key})'' will be
- written as warning in the text
+ the warning ``(entry FreeIV undefined at \PName{key})'' will be
+ written in the text
\item[\Option{adrFreeIVwarn}]
- writes a warning in the logfile
+ a warning is written in the logfile
\item[\Option{adrFreeIVstop}]
- the {\LaTeX} run will be interrupted with an error message
+ the \LaTeX{} run will abort 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}.%
-%
+The default setting is \Option{adrFreeIVshow}.%
\EndIndexGroup
%
\EndIndexGroup