diff options
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.tex | 127 |
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: |