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.tex127
1 files changed, 62 insertions, 65 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 7028b66dbd4..beec72d274b 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
@@ -45,28 +45,27 @@
%
% ======================================================================
-\ProvidesFile{scraddr.tex}[2008/07/10 KOMA-Script guide (chapter: scraddr)]
+\ProvidesFile{scraddr.tex}[2012/02/23 KOMA-Script guide (chapter: scraddr)]
\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm}
-% Date of translated german file: 2005/08/10
+% Date of translated german file: 2011/09/30
\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.
+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 \autoref{cha:scrlttr2}
+from \autopageref{desc:scrlttr2.cmd.adrentry}.
\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
@@ -103,45 +102,44 @@ 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}
+ \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.
-
+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.
+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}
+\begin{lstcode}
\addrentry{Baggins}{Frodo}%
{The Hill\\ Bag End/Hobbiton in the Shire}{}%
{Bilbo Baggins}{pipe-weed}%
@@ -154,22 +152,24 @@ following entries.
{The Old Forest}{}%
{Goldberry}{trill queer songs}%
{The Master of Wood, Water and Hill}{TOM}
-\end{lstlisting}
+\end{lstcode}
-The 4\textsuperscript{th} parameter, the telephone number, has been
+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 command
+should simply be possible to leave them out.
+
+The command
\Macro{InputAddressFile} is used to load the address file shown above:
-\begin{lstlisting}
+\begin{lstcode}[belowskip=\dp\strutbox]
\InputAddressFile{lotr}
-\end{lstlisting}
+\end{lstcode}
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{lstcode}[belowskip=\dp\strutbox]
\begin{letter}{\Name{TOM}\\\Address{TOM}}
\opening{Dear \FirstName{TOM} \LastName{TOM},}
@@ -190,23 +190,21 @@ him if he can remember two fellow-travelers from Elder Days.
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.
+\end{lstcode}
+In the address of letters often both firstname and lastname are required, als
+shown above in \Macro{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 \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 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 \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}
@@ -216,24 +214,22 @@ 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}
-%
+ \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}}
+\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
+ ``(entry FreeIV undefined at \PName{key})'' will be
written as warning in the text
\item[\Option{adrFreeIVwarn}]
writes a warning in the logfile
@@ -242,14 +238,15 @@ with an \Macro{adrentry} entry.
\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}.
+setting is \Option{adrFreeIVshow}.%
%
-\EndIndex{Option}{adrFreeIVempty}\EndIndex{Option}{adrFreeIVshow}
+\EndIndex{Option}{adrFreeIVempty}\EndIndex{Option}{adrFreeIVshow}%
\EndIndex{Option}{adrFreeIVwarn}\EndIndex{Option}{adrFreeIVstop}
+\endinput
%%% Local Variables:
%%% mode: latex
-%%% coding: iso-latin-1
+%%% coding: us-ascii
%%% TeX-master: "../guide"
%%% End: