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 | 200 |
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 |