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 | 174 |
1 files changed, 97 insertions, 77 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 b96d6c69320..b1d03f6f975 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 @@ -40,53 +40,68 @@ % % ---------------------------------------------------------------------- % -% Kapitel über scraddr in der KOMA-Script-Anleitung -% Verwaltet von Jens-Uwe Morawski (mit Unterstützung von Markus Kohm) +% Kapitel ueber scraddr in der KOMA-Script-Anleitung +% Verwaltet von Jens-Uwe Morawski (mit Unterstuetzung von Markus Kohm) % % ====================================================================== -\ProvidesFile{scraddr.tex}[2005/11/27 KOMA-Script guide (chapter: scraddr)] -% Date of translated german file: 2002/10/15 +\ProvidesFile{scraddr.tex}[2007/09/27 KOMA-Script guide (chapter: scraddr)] +\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm} + +% Date of translated german file: 2005/08/10 \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 of the kind -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 the previous chapter. \begin{Declaration} \Macro{InputAddressFile}\Parameter{file name} \end{Declaration}% \BeginIndex{Cmd}{InputAddressFile}% % -The command \Macro{InputAddressFile} reads the content -of the address file, given as its parameter. -If the file does not exist the command returns an -error message. +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. -For every entry in the address file the command generates a -set of macros for accessing the data. -First a short reminder of how an address entry is structured. +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. \begin{Declaration}% \Macro{adrentry}\Parameter{Lastname}\Parameter{Firstname}% - \Parameter{Address}\Parameter{Telephone}\Parameter{F1}\Parameter{F2}% + \Parameter{Address}\Parameter{Phone}\Parameter{F1}\Parameter{F2}% \Parameter{Comment}\Parameter{Key}\\ + % \Macro{addrentry}\Parameter{Lastname}\Parameter{Firstname}% - \Parameter{Address}\Parameter{Telephone}\Parameter{F1}\Parameter{F2}% - \Parameter{F3}\Parameter{F4}\Parameter{Key} + \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 last parameter is the identifier of an entry, thus the -\PName{Key} has to be unique and not blank. If the file contains more -than one entry with the same \PName{Key} value, the last occurrence -will be used. The \PName{Key} should only be composed of letters. +\IndexCmd{adrentry}% +\IndexCmd{addrentry}% +\IndexCmd{adrchar}% +\IndexCmd{addrchar}% + +The structure of the address entries in the address file was discussed +in detail in \autoref{sec:scrlttr2.addressFile} from +\autopageref{desc:scrlttr2.macro.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. \begin{Declaration} \Macro{Name}\Parameter{Key}\\ \Macro{FirstName}\Parameter{Key}\\ @@ -104,13 +119,16 @@ will be used. The \PName{Key} should only be composed of letters. \BeginIndex{Cmd}{FreeII}\BeginIndex{Cmd}{FreeIII}\BeginIndex{Cmd}{FreeIV}% \BeginIndex{Cmd}{Comment}% % -These commands give access to data of your address file. -The parameter \PName{Key} is the same as in the -\Macro{adrentry} or \Macro{addrentry} command. -In the address of letters often both, first-name and -last-name, are required. -The command \Macro{Name}\PParameter{Key} is an abridgement for -\Macro{FirstName}\PParameter{Key} \Macro{LastName}\PParameter{Key}. + +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. + \EndIndex{Cmd}{InputAddressFile}% \EndIndex{Cmd}{Name}\EndIndex{Cmd}{FirstName}\EndIndex{Cmd}{LastName}% @@ -120,9 +138,9 @@ The command \Macro{Name}\PParameter{Key} is an abridgement for \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 \emph{lotr.adr} and contains -the following entries. +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} \addrentry{Baggins}{Frodo}% {The Hill\\ Bag End/Hobbiton in the Shire}{}% @@ -138,36 +156,31 @@ the following entries. {The Master of Wood, Water and Hill}{TOM} \end{lstlisting} -The 4\textsuperscript{th} 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. -The command \Macro{InputAddressFile} is used to load -the address file shown above. +The 4\textsuperscript{th} 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 +\Macro{InputAddressFile} is used to load the address file shown above: \begin{lstlisting} \InputAddressFile{lotr} \end{lstlisting} -With the help of the commands introduced in this chapter -we can now write a letter to the old \textsc{Tom Bombadil}. -In this letter we ask him, if he can remember two -fellow-travelers from Elder Days. +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{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}, 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. - Their pasions were very wordly. - \FirstName{FRODO} enjoyed to smoke \FreeII{FRODO}, - his attendant has appreciate a good meal with + Their passions were very worldly. \FirstName{FRODO} enjoyed + smoking \FreeII{FRODO}, his attendant appreciated a good meal with \FreeII{SAM}. Do you remember? Certainly Mithrandir has told you much @@ -178,28 +191,29 @@ fellow-travelers from Elder Days. and the leaves' laughter!''} \end{letter} \end{lstlisting} -The 5\textsuperscript{th} and 6\textsuperscript{th} parameter of the -\Macro{adrentry} or \Macro{adrentry} command 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 +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 the -data. Using \Macro{FreeIV} is only valid for \Macro{addrentry} entries; for -\Macro{adrentry} entries it results in a warning. +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} -As mentioned above the command \Macro{FreeIV} leads -to a fault if it is used for \Macro{adrentry} entries. - -Therefore \Package{scraddr} supports package options -in order to give the user the possibility to -choose how the package should react in such situation. -It is possible to choose different settings between -\emph{ignore} and \emph{rupture} of the \LaTeX{} run. +As mentioned above, the command \Macro{FreeIV} leads to an error if it +is used for \Macro{adrentry} entries. How \Package{scraddr} reacts in +such a situation is decide by package options. \begin{Declaration} \Option{adrFreeIVempty}\\ @@ -211,9 +225,9 @@ It is possible to choose different settings between \BeginIndex{Option}{adrFreeIVempty}\BeginIndex{Option}{adrFreeIVshow} \BeginIndex{Option}{adrFreeIVwarn}\BeginIndex{Option}{adrFreeIVstop} % -One of these options can be given in the optional argument -of the \Macro{usepackage} command. The default setting is -\Option{adrFreeIVshow}. +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}} \item[\Option{adrFreeIVempty}] @@ -222,14 +236,20 @@ of the \Macro{usepackage} command. The default setting is ``(entry FreeIV undefined at \PName{Key})'' will be written as warning in the text \item[\Option{adrFreeIVwarn}] - writes a warning in the log-file + writes a warning in the logfile \item[\Option{adrFreeIVstop}] - the \LaTeX{} run will be interrupted with an error message + the {\LaTeX} run will be interrupted 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}. +% \EndIndex{Option}{adrFreeIVempty}\EndIndex{Option}{adrFreeIVshow} \EndIndex{Option}{adrFreeIVwarn}\EndIndex{Option}{adrFreeIVstop} + %%% Local Variables: %%% mode: latex +%%% coding: iso-latin-1 %%% TeX-master: "../guide" %%% End: |