diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2.tex | 3475 |
1 files changed, 1836 insertions, 1639 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2.tex index ef26c720cab..ff758441c91 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrlttr2.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-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. % ---------------------------------------------------------------------- % scrlttr2.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,36 +46,56 @@ % ============================================================================ \KOMAProvidesFile{scrlttr2.tex}% - [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (chapter: scrlttr2)] \translator{Harald Bongartz\and Georg Grandke\and Raimund Kohl\and Jens-Uwe - Morawski\and Stephan Hennig\and Gernot Hassenpflug\and Markus Kohm} + Morawski\and Stephan Hennig\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-13 -\chapter{The New Letter Class \Class{scrlttr2}} +\chapter{Letters with the \Class{scrlttr2} Class or the \Package{scrletter} + Package} \labelbase{scrlttr2} -\BeginIndexGroup% -\BeginIndex{Class}{scrlttr2}% -\BeginIndex{}{letters}% -\iffalse - Since the June 2002 release {\KOMAScript} provides a completely - rewritten letter class\ChangedAt{v2.8q}{\Class{scrlttr2}}. Although - part of the code is identical to that of the main classes described - in \autoref{cha:maincls}, letters -\else - Letters -\fi -are quite different from articles, -reports, books, and suchlike. That alone justifies a separate -chapter about the letter class. But there is another reason for a -chapter on \Class{scrlttr2}. This class has been redeveloped from -scratch and provides a new user interface different from every other -class the author knows of. This new user interface may be uncommon, -but the author is convinced both experienced and new {\KOMAScript} -users will benefit from its advantages. +\BeginIndexGroup +\BeginIndex{Class}{scrlttr2}\BeginIndex{Package}{scrletter}% +\BeginIndex{}{letters}% +Letters are quite different in many ways from articles, reports, books, and +the like. That alone justifies a separate chapter on letters. But there are +other reasons for a separate chapter on \Class{scrlttr2} and +\Package{scrletter}. + +The \Class{scrlttr2}\important{\Class{scrlttr2}} class was developed from +scratch in 2002. It provides a completely new user interface, different from +every other class I know. This new user interface may be unusual, but it +offers benefits to both new and experienced {\KOMAScript} users. + +The \Package{scrletter}\important{\Package{scrletter}}% +\ChangedAt{v3.15}{\Package{scrletter}} package has supplemented \KOMAScript{} +since Version~3.15. It also provides all the letter-based functionality of +\Class{scrlttr2} to the other classes. I recommend you use one of the +\KOMAScript{} classes\,---\,\Class{scrbook}, \Class{scrreprt} or +\Class{scrartcl}\,---\, which are explained in the previous chapter. With +minor limitations, \Package{scrletter} also works well with the standard +classes. + +The starting point for developing \Package{scrletter} was, on the one hand, +requests from users who also wanted to have elements such as +section\textnote{headings, floating environments, indexes} headings, floating +environments, or a bibliography in letters. On the other hand, there were also +requests to use \Class{scrlttr2} variables in the remaining \KOMAScript{} +classes. You can achieve both by combining the desired \KOMAScript{} class +with \Package{scrletter}. + +Compared to the letter class, the letter package has a few small changes that +were necessary to avoid conflicts with other classes. These changes mainly +affect the page styles and are explicitly documented (see +\autoref{sec:\LabelBase.pagestyle}, starting at +\autopageref{sec:\LabelBase.pagestyle}). Where \Package{scrletter} is not +explicitly mentioned, everything that is documented for \Class{scrlttr2} +applies without change. \section{Variables} @@ -83,41 +103,39 @@ users will benefit from its advantages. \BeginIndexGroup \BeginIndex{}{variables} -Apart from options, commands, environments, counters and lengths, -additional elements have already been introduced in \KOMAScript. A -typical property of an element is the font style and the option to -change it (see \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}). At this point we now -introduce variables. Variables have a name by which they are called, -and they have a content. The content of a variable can be set -independently from time and location of the actual usage in the same -way as the contents of a command can be separated from its usage. The -main difference between a command and a variable is that a command -usually triggers an action, whereas a variable only consists of plain -text which is then output by a command. Furthermore, a variable can -additionally have a description which can be set and output. - -This section specifically only gives an introduction to the concept of -variables. The following examples have no special meaning. More -detailed examples can be found in the explanation of predefined -variables of the letter class in the following sections. An overview -of all variables is given in \autoref{tab:\LabelBase.variables}. +In addition to options, commands, environments, counters, and lengths, +\autoref{cha:maincls} introduced the concept of additional elements for +\KOMAScript{}. A typical property of an element is its font style and the +ability to change it (see \autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}). In this section we introduce +variables. Variables can have a label used to identify them when they are +output in the document as well as their actual content. To avoid confusion +with labels used for cross-references, this guide refers to such labels as the +``description'' of the variable. The content of a variable can be set +independently of the time and place it is used the same way that the content +of a command can be defined separately from its use. The main difference +between a command and a variable is that a command usually triggers an action, +whereas a variable usually consists of plain text which is then output by a +command. In addition, a variable can also have a description which can be +customised and output. + +This section deliberately confines itself to introducing the concept of +variables. The examples below have no special meaning. More detailed +examples can be found in the explanation of predefined variables used in the +class and the package. An overview of all defined variables is given in +\autoref{tab:\LabelBase.variables}. % \begin{desclist} - % Umbruchkorrektur - \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% - \desccaption{% - Alphabetical list of all supported variables in - \Class{scrlttr2}\label{tab:\LabelBase.variables}% - }{% - Alphabetical list of all supported variables in \Class{scrlttr2} - (\emph{continuation})% - }% + %\renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% + \desccaption{Supported variables in \Class{scrlttr2} and + \Package{scrletter}\label{tab:\LabelBase.variables}}% + {Supported variables in \Class{scrlttr2} and \Package{scrletter} + (\emph{continued})}% \ventry{addresseeimage}{% - instuctions, that will be used to print the Port-Pay\'e head of option - \OptionValueRef{\LabelBase}{addrfield}{backgroundimage} or the Port-Pay\'e - addressee of option \OptionValueRef{\LabelBase}{addrfield}{image} % - (\autoref{sec:\LabelBase.firstpage}, + commands used to print the postpaid postmark for the + \OptionValueRef{\LabelBase}{addrfield}{backgroundimage} option or the + postpaid address for the \OptionValueRef{\LabelBase}{addrfield}{image} + option (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.addresseeimage})}% \ventry{backaddress}{% return address for window envelopes % @@ -128,8 +146,8 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.backaddressseparator})}% \ventry{ccseparator}{% - separator between title of additional addressees, and additional - addressees % + separator between title of additional addresses (cc list) + and additional addresses % (\autoref{sec:\LabelBase.document}, \DescPageRef{\LabelBase.variable.ccseparator})}% \ventry{customer}{% @@ -141,23 +159,23 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.date})}% \ventry{emailseparator}{% - separator between e-mail name and e-mail address % + separator between email name and email address % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.emailseparator})}% \ventry{enclseparator}{% - separator between title of enclosure, and enclosures % + separator between title of enclosure and enclosures % (\autoref{sec:\LabelBase.document}, \DescPageRef{\LabelBase.variable.enclseparator})}% \ventry{faxseparator}{% - separator between title of fax, and fax number % + separator between title of fax and fax number % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.faxseparator})}% \ventry{firstfoot}{% - page\ChangedAt{v3.08}{\Class{scrlttr2}} foot of the note paper % + footer\ChangedAt{v3.08}{\Class{scrlttr2}} of the letterhead page % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.firstfoot})}% \ventry{firsthead}{% - page\ChangedAt{v3.08}{\Class{scrlttr2}} head of the note paper % + header\ChangedAt{v3.08}{\Class{scrlttr2}} of the letterhead page % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.firsthead})}% \ventry{fromaddress}{% @@ -165,7 +183,7 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.fromaddress})}% \ventry{frombank}{% - sender's bank account % + sender's bank details % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.frombank})}% \ventry{fromemail}{% @@ -194,12 +212,12 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.fromphone})}% \ventry{fromurl}{% - a URL of the sender, e.\,g., the URL of his homepage % + URL of the sender, e.\,g. of the sender's homepage % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.fromurl})}% \ventry{fromzipcode}{% - zip code or postcode of the sender used at the Port-Pay\'e head of option - \OptionValueRef{\LabelBase}{addrfield}{PP} % + ZIP code (postal code) of the sender for the postpaid postmark of the + \OptionValueRef{\LabelBase}{addrfield}{PP} option % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.fromzipcode})}% \ventry{invoice}{% @@ -207,7 +225,7 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.invoice})}% \ventry{location}{% - more details of the sender % + extra details of the sender % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.location})}% \ventry{myref}{% @@ -215,13 +233,13 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.myref})}% \ventry{nextfoot}{% - page\ChangedAt{v3.08}{\Class{scrlttr2}} foot using page style + footer\ChangedAt{v3.08}{\Class{scrlttr2}} using page style \PageStyle{headings}\IndexPagestyle{headings} or \PageStyle{myheadings}\IndexPagestyle{myheadings} % (\autoref{sec:\LabelBase.pagestyle}, \DescPageRef{\LabelBase.variable.nextfoot})}% \ventry{nexthead}{% - page\ChangedAt{v3.08}{\Class{scrlttr2}} head using page style + header\ChangedAt{v3.08}{\Class{scrlttr2}} using page style \PageStyle{headings}\IndexPagestyle{headings} or \PageStyle{myheadings}\IndexPagestyle{myheadings} % (\autoref{sec:\LabelBase.pagestyle}, @@ -231,29 +249,29 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.phoneseparator})}% \ventry{place}{% - sender's place used near date % + sender's location; used next to date % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.place})}% \ventry{placeseparator}{% - separator between place and date % + separator between location and date % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.placeseparator})}% \ventry{PPdatamatrix}{% - instruction, that print the data array of option - \OptionValueRef{\LabelBase}{addrfield}{PP} % + command to print the data array for the + \OptionValueRef{\LabelBase}{addrfield}{PP} option % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.PPdatamatrix})}% \ventry{PPcode}{% - instructions for the sender's identification code of option - \OptionValueRef{\LabelBase}{addrfield}{PP} % + commands for the sender's identification code for the + \OptionValueRef{\LabelBase}{addrfield}{PP} option % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.PPcode})}% \ventry{signature}{% - signature beneath the ending of the letter % + signature annotation beneath the closing text of the letter % (\autoref{sec:\LabelBase.closing}, \DescPageRef{\LabelBase.variable.signature})}% \ventry{specialmail}{% - mode of dispatch % + delivery method % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.specialmail})}% \ventry{subject}{% @@ -261,7 +279,7 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.subject})}% \ventry{subjectseparator}{% - separator between title of subject and subject % + separator between subject title and subject % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.subjectseparator})}% \ventry{title}{% @@ -269,23 +287,23 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.title})}% \ventry{toaddress}{% - address of addressee without addressee name % + address of recipient without recipient name % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.toaddress})}% \ventry{toname}{% - complete name of addressee % + complete name of recipient % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.toname})}% \ventry{yourmail}{% - date of addressee's referenced mail % + date of recipient's referenced mail % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.yourmail})}% \ventry{yourref}{% - addressee's reference % + recipient's reference % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.yourref})}% \ventry{zipcodeseparator}{% - separator between the zip code's or postcode's title and the code itself % + separator between the title of ZIP code (postal code) and the code itself % (\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.zipcodeseparator})}% \end{desclist} @@ -295,44 +313,44 @@ of all variables is given in \autoref{tab:\LabelBase.variables}. \Parameter{name}\OParameter{description}\Parameter{content}% \Macro{setkomavar*}\Parameter{name}\Parameter{description} \end{Declaration} -With the command \Macro{setkomavar} you determine the -\PName{content} of the variable \PName{name}. Using an optional -argument you can at the same time change the \PName{description} -of the variable. In contrast, \Macro{setkomavar*} can only set the -\PName{description} of the variable \PName{name}. -% Wir haben hier ein anderes Beispiel als in der deutschen Anleitung, aber das -% passt hier sehr gut so! +The \Macro{setkomavar} command sets the \PName{content} of the \PName{name} +variable. Using the optional argument, you can change the \PName{description} +of the variable at the same time. In contrast, \Macro{setkomavar*} sets only +the \PName{description} of the \PName{name} variable. \begin{Example} - Suppose you have defined a direct dialling as mentioned above - and you now want to set the content. You write: -\begin{lstlisting} - \setkomavar{myphone}{-\,11} -\end{lstlisting} - In addition, you want to replace the term ``direct dialling'' - with ``Connection''. Thus you add the description: -\begin{lstlisting} - \setkomavar*{myphone}{Connection} -\end{lstlisting} - or you can combine both in one command: -\begin{lstlisting} - \setkomavar{myphone}[Connection]{-\,11} -\end{lstlisting} + It is customary for letters to indicate the sender in the letterhead. + First, \KOMAScript{} must know the name of the sender. For + ``Joe Public'' that would be done with: +\begin{lstcode} + \setkomavar{fromname}{Joe Public} +\end{lstcode} + The default for the description of the sender is ``From''. Assuming, + however, that Mr Public wants to have ``Sender'' in the places where + \KOMAScript{} outputs his name, he would have to add +\begin{lstcode} + \setkomavar*{fromname}{Sender} +\end{lstcode} + or combine the two commands into one: +\begin{lstcode} + \setkomavar{fromname}[Sender]{Joe Public} +\end{lstcode} + He thus kills two birds with one stone, so to speak. \end{Example} -By the way: You may delete the content of a variable using an empty -\PName{content} argument. You can also delete the description using an -empty \PName{description} argument. +By the way, you can delete the content of the variable by providing an empty +\PName{content} argument. Of course, you can delete the \PName{description} of +the variable in the same way, with an empty argument for the description. \begin{Example} - Suppose you have defined a direct dialling as mentioned above and - you now no longer want a description to be set. You write: -\begin{lstlisting} - \setkomavar*{myphone}{} -\end{lstlisting} - You can combine this with the definition of the content: -\begin{lstlisting} - \setkomavar{myphone}[]{-\,11} -\end{lstlisting} - So you may setup the content and delete the description using only - one command. + Suppose Mr Public wants to have no label for the name of the sender. He can + either delete it for himself with +\begin{lstcode} + \setkomavar*{fromname}{} +\end{lstcode} + or he could again kill two birds with one stone and use +\begin{lstcode} + \setkomavar{fromname}[]{Joe Public} +\end{lstcode} + This will simultaneously set the contents of the variable and delete its + description. \end{Example} % \EndIndexGroup @@ -342,94 +360,91 @@ empty \PName{description} argument. \Macro{usekomavar}\OParameter{command}\Parameter{name}% \Macro{usekomavar*}\OParameter{command}\Parameter{name} \end{Declaration} -In\ChangedAt{v2.9i}{\Class{scrlttr2}} some cases it is necessary for the user -to access the content or the description of a variable, and not to leave this -only up to the class. This is specially important when you have defined a -variable which is not added to the reference fields line. Using the command -\Macro{usekomavar} you have access to the content of the variable -\PName{name}, whereas the starred version \Macro{usekomavar*} allows you to -access the description or title. In \autoref{sec:scrlttr2-experts.variables}, -\DescPageRef{scrlttr2-experts.cmd.newkomavar} you may find more -information about defining variable on your own.% +In\ChangedAt{v2.9i}{\Class{scrlttr2}} some cases, it is necessary to access +the content or description of a variable and not to leave this solely to the +class. This is especially important if you have defined a variable which is +not added to the reference fields line. Using the command \Macro{usekomavar} +you have access to the content of the \PName{name} variable, whereas the +starred version \Macro{usekomavar*} allows you to access the description or +title. In \autoref{sec:scrlttr2-experts.variables}, +\DescPageRef{scrlttr2-experts.cmd.newkomavar} you can find more information +about defining your own variables.% \EndIndexGroup \begin{Declaration} - \Macro{ifkomavar}\Parameter{name}\Parameter{true-code}\Parameter{false-code} + \Macro{ifkomavar}\Parameter{name}\Parameter{then code}\Parameter{else code} \end{Declaration} -This\ChangedAt{v3.03}{\Class{scrlttr2}} command may be used to test, whether -or not a variable has already been defined. The \PName{true-code} will be -executed only, if the variable already exists. The contents of the variable -will not be examined, so it may be empty. The \PName{false-code} will be -executed if the variable does not yet exist. Such tests make sense if a -variable will be defined at one -\File{lco}-file\Index{lco-file=\File{lco}-file} (see -\autoref{sec:\LabelBase.lcoFile} from \autopageref{sec:\LabelBase.lcoFile} -onward), but used in another \File{lco}-file if it exists only.% -% +With\ChangedAt{v3.03}{\Class{scrlttr2}} this command, you can determine if a +variable has already been defined. The \PName{then code} will be executed only +if the variable already exists. The variable's contents will not be examined +and so can be empty. The \PName{else code} will be executed if the variable +does not exist. Such tests can be useful, for example, if your own variables +are defined in one \File{lco} file\Index{lco file=\File{lco} file} (see +\autoref{sec:\LabelBase.lcoFile} starting at +\autopageref{sec:\LabelBase.lcoFile}) but used in another \File{lco} file only +if they exist.% \EndIndexGroup \begin{Declaration} - \Macro{ifkomavarempty}\Parameter{name}\Parameter{true-code}% - \Parameter{false-code}% - \Macro{ifkomavarempty*}\Parameter{name}\Parameter{true-code}% - \Parameter{false-code} + \Macro{ifkomavarempty}\Parameter{name}\Parameter{then code}% + \Parameter{else code}% + \Macro{ifkomavarempty*}\Parameter{name}\Parameter{then code}% + \Parameter{else code} \end{Declaration} -With\ChangedAt{v2.9i}{\Class{scrlttr2}} these commands you may check -whether or not the expanded content or description of a variable is -empty. The \PName{true-code} will be executed if the content or -description is empty. Otherwise the \PName{false-code} will be -executed. The starred variant handles the description of a variable, -the unstarred variant handles the contents.% +With\ChangedAt{v2.9i}{\Class{scrlttr2}} these commands, you can determine +whether either the content or the description of a variable is empty. The +\PName{then code} will be executed if the expanded content or the expanded +description of the \PName{name} variable is empty. Otherwise, the \PName{else +code} will be executed. The starred variant tests the variable's description, +while the normal variant tests its contents.% \EndIndexGroup % \EndIndexGroup -\section{Pseudo-Lengths} +\section{Pseudo-lengths} \seclabel{pseudoLength} - \BeginIndexGroup \BeginIndex{}{pseudo-lengths} -\LaTeX{} processes length with commands \Macro{newlength}, \Macro{setlength}, -\Macro{addtolength}, and \Macro{the\PName{length}}. Many packages also use -macros, that are commands, to storage lengths. \KOMAScript{} extends the -method of storing length at macros by some commands similar to the commands -above, that are used to handle real lengths. \KOMAScript calls this kind of -lengths, that are stored at macros instead of real \LaTeX{} lengths, -pseudo-lengths. - -A list of all pseudo-lengths in \Class{scrlttr2} is shown in -\autoref{tab:scrlttr2-experts.pseudoLength} starting at -\autopageref{tab:scrlttr2-experts.pseudoLength}. The meaning of the various -pseudo-lengths is shown graphically in + +\LaTeX{} processes lengths with three commands: +\Macro{newlength}\IndexCmd{newlength}, \Macro{setlength}\IndexCmd{setlength} +and \Macro{addtolength}\IndexCmd{addtolength}. Many packages also use macros, +which are commands, to store lengths. \KOMAScript{} extends this method with +the ability to process such lengths stored in macros with commands similar to +those used to handle real lengths. \KOMAScript{} calls lengths that are +actually stored in macros \emph{pseudo-lengths}. + +You can find a list of all pseudo-lengths defined by \Class{scrlttr2} in +\autoref{tab:scrlttr2-experts.pseudoLength}, +\autopageref{tab:scrlttr2-experts.pseudoLength}. A graphical representation of +the main pseudo-lengths for the letterhead page is given in \autoref{fig:scrlttr2-experts.pseudoLength}. The dimensions used in the figure correspond to the default settings of \Class{scrlttr2}. More detailed -description of the individual pseudo-lengths is found in the individual +descriptions of the individual pseudo-lengths are found in the individual sections of this chapter. -Normally users would not need to define a pseudo-length on their own. Because -of this, definition of pseudo-lengths will be described in the expert part at +Since users will usually not need to define their own pseudo-lengths, the +method for defining them is described in the part for experts, in \autoref{sec:scrlttr2-experts.pseudoLengths}, -\DescPageRef{scrlttr2-experts.cmd.@newplength}. Setting pseudo-lengths to -new values is also a work for advanced users. So this will be described in the -expert part too at \DescPageRef{scrlttr2-experts.cmd.@setplength}. +\DescPageRef{scrlttr2-experts.cmd.@newplength}. Setting pseudo-lengths to new +values should also be a matter for advanced users, so this is also described +in the part for experts, on \DescPageRef{scrlttr2-experts.cmd.@setplength}. -Please note\textnote{Attention!}: Even though these pseudo-lengths are -internally implemented as macros, the commands for pseudo-length management -expect only the names of the pseudo-lengths not the macros representing the -pseudo-lengths. The names of pseudo-lengths are without backslash at the very -beginning similar to the names of \LaTeX{} counters and in opposite to macros -or \LaTeX{} lengths. +Note\textnote{Attention!} that although these pseudo-lengths are internally +implemented as macros, the commands to use pseudo-lengths expect only the the +pseudo-length names. These are written without backslashes, like the names of +\LaTeX{} counters and unlike macros or real lengths. \begin{Declaration} \Macro{useplength}\Parameter{name} \end{Declaration} -Using this command you can access the value of the pseudo-length with +Using this command you can access the value of the pseudo-length of the given \PName{name}. This is one of the few user commands in connection with pseudo-lengths. Of course this command can also be -used with an \File{lco}-file\Index{lco-file=\File{lco}-file} (see +used with an \File{lco} file\Index{lco file=\File{lco} file} (see \autoref{sec:\LabelBase.lcoFile} ab \autopageref{sec:\LabelBase.lcoFile}).% % \EndIndexGroup @@ -441,30 +456,19 @@ used with an \File{lco}-file\Index{lco-file=\File{lco}-file} (see \Macro{addtolengthplength}% \OParameter{factor}\Parameter{length}\Parameter{pseudo-length} \end{Declaration} -\begin{Explain}% - While you can simply prepend a factor to a length, this is not - possible with pseudo-lengths. Suppose you have a length \Macro{test} - with the value 2\Unit{pt}; then \texttt{3\Macro{test}} gives you the - value 6\Unit{pt}. Using pseudo-lengths instead, - \texttt{3\Macro{useplength}\PParameter{test}} would give you - 32\Unit{pt}. This is especially annoying if you want a real - \PName{length} to take the value of a \PName{pseudo-length}. -\end{Explain} -Using the command \Macro{setlengthtoplength} you can assign the -multiple of a \PName{pseudo-length} to a real \PName{length}. Here, -instead of prepending the \PName{factor} to the \PName{pseudo-length}, -it is given as an optional argument. You should also use this command -when you want to assign the negative value of a \PName{pseudo-length} -to a \PName{length}. In this case you can either use a minus sign or -\PValue{-1} as the \PName{factor}. The command -\Macro{addtolengthplength} works very similarly; it adds the multiple -of a \PName{pseudo-length} to the \PName{length}. +With the \Macro{setlengthtoplength} command, you can assign a multiple of a +\PName{pseudo-length} to a real \PName{length}. The \PName{factor} is given +as an optional argument instead of directly preceding the +\PName{pseudo-length}. You should also use this command when you want to +assign the negative of a \PName{pseudo-length} to a \PName{length}. In this +case, you can use either a minus sign or \PValue{-1} as the \PName{factor}. +The \Macro{addtolengthplength} command works very similarly. It adds the +\PName{pseudo-length} multiplied by the \PName{factor} to the \PName{length}.% % \EndIndexGroup % \EndIndexGroup - \LoadCommonFile{options} % \section{Early or Late Selection of Options} \LoadCommonFile{compatibility} % \section{Compatibility with Earlier Versions of @@ -474,13 +478,14 @@ of a \PName{pseudo-length} to the \PName{length}. \LoadCommonFile{typearea} % \section{Page Layout} -Normally it makes no sense to distinguish letters with single-side layout and -letters with double-side layout. Mostly letters are not bound like -books. Therefor each page will be viewed on its own. This is also true if both -sides of the paper sheet will be used for printing. Vertical adjustment is -unusual at letters too. Nevertheless, if you need or want it, you may read the -description of \Macro{raggedbottom} and \Macro{flushbottom} in -\autoref{sec:maincls.typearea} at \DescPageRef{maincls.cmd.flushbottom}.% +For letters, it is normally not useful to distinguish one-sided and two-sided +printing. Since letters are not usually bound, each page of a letter will be +viewed on its own. This is also true even if both the letter is printed on +both sides of the paper. Vertical adjustment usually does not matter for +letters either. If you nevertheless need it, or want to understand what it is, +please refer to the commands \Macro{raggedbottom} and \Macro{flushbottom} +explained in \autoref{sec:maincls.typearea} on +\DescPageRef{maincls.cmd.flushbottom}.% % \EndIndexGroup @@ -490,20 +495,19 @@ description of \Macro{raggedbottom} and \Macro{flushbottom} in \BeginIndexGroup \BeginIndex{}{letter>structure} -The general structure of a letter document differs somewhat from the -structure of a normal document. Whereas a book document in general -contains only one book, a letter document can contain several -letters. As illustrated in \autoref{fig:\LabelBase.document}, a letter -document consists of a preamble, the individual letters, and the -closing. +The general structure of a letter document differs somewhat from the structure +of a normal document. Whereas a book document usually contains only one book, +a letter document can contain several letters. As illustrated in +\autoref{fig:\LabelBase.document}, a letter document consists of a preamble, +the individual letters, and the closing. \begin{figure} \KOMAoptions{captions=bottombeside}% \setcapindent{0pt}% \begin{captionbeside}[{% - General structure of a letter document with several individual letters% + General structure of a letter document containing several individual letters% }]{% - General structure of a letter document with several individual letters + General structure of a letter document containing several individual letters (the structure of a single letter is shown in \autoref{fig:\LabelBase.letter})% \label{fig:\LabelBase.document}% @@ -522,7 +526,7 @@ closing. \dots\\ }}\\ \fbox{\parbox{\linewidth}{\raggedright% - \Macro{begin}\PParameter{letter}\Parameter{addressee}\\ + \Macro{begin}\PParameter{letter}\Parameter{recipient}\\ \dots\\ {\centering\emph{content of the individual letter}\\} \dots\\ @@ -536,24 +540,29 @@ closing. \end{captionbeside} \end{figure} -The preamble comprises all settings that in general concern all letters. Most -of them can also be overwritten in the settings of the individual letters. The -only setting which can not be changed within a single letter is compatibility -to prior versions of \Class{scrlttr2} (see option \DescRef{\LabelBase.option.version} in +The preamble contains all the settings that apply generally to all letters. +Most of them can also be overwritten in the settings of the individual +letters. The only setting which cannot currently be changed within a single +letter is the version of \Class{scrlttr2} for which compatibility is required +(see the \DescRef{\LabelBase.option.version} option in \autoref{sec:\LabelBase.compatibilityOptions}, \DescPageRef{\LabelBase.option.version}). -It is recommended that only general settings such as the loading of packages -and the setting of options be placed before -\Macro{begin}\PParameter{document}. All settings that comprise the setting of -variables or other text features should be done after -\Macro{begin}\PParameter{document}. This is particularly recommended when the -\Package{babel} package\IndexPackage{babel} (see \cite{package:babel}) is -used, or language-dependent variables of \Class{scrlttr2} are to be changed. +If you use \Package{scrletter}\important{scrletter}, the only difference is +that another class is loaded, with +\DescRef{\LabelBase.cmd.usepackage}\PParameter{scrletter} added before the +settings for all letters. For setting options with \Package{scrletter}, see +\autoref{sec:\LabelBase.options}, on \autopageref{sec:\LabelBase.options}. -The closing usually consists only of -\Macro{end}\PParameter{document}. Of course you can also insert -additional comments at this point. +I recommended that you place only general settings such as loading packages +and setting options before \Macro{begin}\PParameter{document}. You should +initialise all variables or other textual features after +\Macro{begin}\PParameter{document}, particularly when you use the +\Package{babel} package\IndexPackage{babel} (see \cite{package:babel}) or +change language-dependent variables of \Class{scrlttr2}. + +The closing usually consists only of \Macro{end}\PParameter{document}. Of +course you can also add additional comments at this point. \begin{figure} \KOMAoptions{captions=bottombeside}% @@ -569,11 +578,11 @@ additional comments at this point. \addtolength{\linewidth}{-\dimexpr2\fboxrule+2\fboxsep\relax}% \fbox{\parbox{\linewidth}{\raggedright% \Macro{begin}\PParameter{letter}% - \OParameter{Optionen}\Parameter{addressee}\\ + \OParameter{options}\Parameter{recipient}\\ \dots\\[\dp\strutbox] {\centering\emph{settings for this letter}\\} \dots\\ - \DescRef{\LabelBase.cmd.opening}\Parameter{opening}\\ + \DescRef{\LabelBase.cmd.opening}\Parameter{salutation}\\ }}\\[1pt] \fbox{\parbox{\linewidth}{\raggedright% \dots\\[\dp\strutbox] @@ -581,71 +590,77 @@ additional comments at this point. \dots\\ }}\\[1pt] \fbox{\parbox{\linewidth}{\raggedright% - \DescRef{\LabelBase.cmd.closing}\Parameter{closing}\\ + \DescRef{\LabelBase.cmd.closing}\Parameter{concluding text}\\ \DescRef{\LabelBase.cmd.ps}\\ \dots\\[\dp\strutbox] {\centering\emph{postscript}\\} \dots\\ \DescRef{\LabelBase.cmd.encl}\Parameter{enclosures}\\ - \DescRef{\LabelBase.cmd.cc}\Parameter{additional addressees}\\ + \DescRef{\LabelBase.cmd.cc}\Parameter{additional recipients}\\ \Macro{end}\PParameter{letter}\\ }}\\[\dimexpr\fboxsep+\fboxrule\relax] \end{minipage} \end{captionbeside} \end{figure} -As shown in \autoref{fig:\LabelBase.letter}, every single letter itself consists -of an introduction, the letter body, and the closing. In the introduction, all -settings pertaining only to the current letter are defined. It is important -that this introduction always ends with -\DescRef{\LabelBase.cmd.opening}\IndexCmd{opening}. Similarly, the closing always starts with -\DescRef{\LabelBase.cmd.closing}\IndexCmd{closing}. The two arguments \PName{opening} and -\PName{closing} can be left empty, but both commands must be used and must -have an argument. - -It should be noted that several settings can be changed between the individual -letters. Such changes then have an effect on all subsequent letters. For -reasons of maintainability of your letter documents, it is however not -recommended to use further general settings with limited scope between the -letters. +As detailed in \autoref{fig:\LabelBase.letter}, individual letters each +consist of an introduction, the body of the letter, and the closing. In the +introduction, all settings pertaining to the current letter alone are defined. +It is important that this introduction always ends with +\DescRef{\LabelBase.cmd.opening}\IndexCmd{opening}. Similarly, the closing +always starts with \DescRef{\LabelBase.cmd.closing}\IndexCmd{closing}. The +\PName{opening} and \PName{closing} arguments of the two commands can be left +empty, but both commands must be used and must have an argument. + +Note that you can change additional settings between the individual letters. +Such changes then apply to all subsequent letters. However, to keep your +letter documents clear and maintainable, you should think carefully before +actually placing further general settings of limited scope between the +letters. I cannot recommend this practice. However, if you use +\Package{scrletter2}, there is nothing wrong with inserting additional parts +of the document between or after letters that should not be in the same scope. +For example, you can combine a cover letter and a CV in one document. \begin{Declaration} - \begin{Environment}{letter}\OParameter{options}\Parameter{addressee} + \begin{Environment}{letter}\OParameter{options}\Parameter{recipient} \end{Environment} \end{Declaration} -\BeginIndex{}{addressee}% +\BeginIndex{}{address}% The \Environment{letter} environment is one of the key environments of the -letter class. A special\textnote{\KOMAScript{} vs. standard classes} -\Class{scrlttr2} feature are optional arguments to the \Environment{letter} -environment. These \PName{options} are executed internally via the +letter class. A noteworthy\textnote{\KOMAScript{} vs. standard classes} +feature of \Class{scrlttr2} and \Package{scrletter} is that they can provide +additional \PName{options} for the \Environment{letter} environment. These +\PName{options} are executed internally using the \DescRef{\LabelBase.cmd.KOMAoptions} command. -The \PName{addressee} is a mandatory argument passed to the -\Environment{letter} environment. Parts\textnote{Attention!} of the addressee -contents are separated by double backslashes. These parts are output on -individual lines in the address field. Nevertheless, the double backslash -should not be interpreted as a certain line break. Vertical material such as -paragraphs or vertical space is not permitted within \PName{addressee}, and -could lead to unexpected results and error messages, as is the case also for -the standard letter class. +The \PName{recipient}, or addressee, is a mandatory argument passed to the +\Environment{letter} environment and includes both the name and the address of +the recipient of the letter. Double\textnote{Attention!} backslashes serve to +separate the individual parts of the address. These parts are output on +individual lines in the address field. Nevertheless, you should not interpret +the double backslash as a mandatory line break. Vertical material such as new +paragraphs or vertical space is not permitted within the address. They can +lead to unexpected results and error messages. Incidentally, this is the same +for the standard letter class. \begin{Example} \phantomsection\label{desc:\LabelBase.env.letter.example}% - Assumed, someone wants to send a letter to Joana Public. A minimalistic - letter document for this may be: + Suppose you want to write a letter to Joanna Public. A minimalist + letter document would look like this: \begin{lstcode} \documentclass[version=last]{scrlttr2} - \usepackage[english]{babel} + \usepackage[british]{babel} \begin{document} - \begin{letter}{Joana Public\\ - Hillside 1\\ - 12345 Public-City} + \begin{letter}{Joanna Public\\ + 1 Hillside\\ + SAMPLESTEAD\\ + WX12 3YZ} \end{letter} \end{document} \end{lstcode} - However, this would not result in any printable output. At least there - would not be an addressee at the note paper sheet. The reason for this will - be explained at the description of command \DescRef{\LabelBase.cmd.opening} at + However, this would not result in any output. It would not even print the + recipient on the letterhead page. Why this is the case is explained in the + description of the \DescRef{\LabelBase.cmd.opening} command on \DescPageRef{\LabelBase.cmd.opening}. \end{Example} % @@ -653,31 +668,32 @@ the standard letter class. \begin{Declaration} - \Macro{AtBeginLetter}\Parameter{instruction code}% - \Macro{AtEndLetter}\Parameter{instruction code} + \Macro{AtBeginLetter}\Parameter{code}% + \Macro{AtEndLetter}\Parameter{code} \end{Declaration} -{\LaTeX} enables the user to declare \PName{instruction code} whose execution -is delayed until a determined point. Such points are called -\emph{hooks}\Index{hook}. Known macros for using hooks are +As mentioned in \cite{latex:clsguide}, \LaTeX{} lets the user declare +additional \PName{code} to be executed at certain points in a \LaTeX{} run. +For this purpose, the \LaTeX{} kernel provides, for example, \Macro{AtBeginDocument}\IndexCmd{AtBeginDocument} and -\Macro{AtEndOfClass}\IndexCmd{AtEndOfClass} at the \LaTeX{} kernel. The class -\Class{scrlttr2} provides two more hooks. The \PName{instruction code} for -these may be declared using \Macro{AtBeginLetter} and +\Macro{AtEndOfClass}\IndexCmd{AtEndOfClass}. Such points are called +\emph{hooks}\Index{hook}. The \Class{scrlttr2} class and the +\Package{scrletter} package provide two additional hooks. You can declare the +\PName{code} for these using \Macro{AtBeginLetter} and \Macro{AtEndLetter}\ChangedAt{v2.95}{\Class{scrlttr2}}. Originally, hooks were -provided for package and class authors, so they are documented in -\cite{latex:clsguide} only, and not in \cite{latex:usrguide}. However, with -letters there are useful applications of \Macro{AtBeginLetter} as the -following example may illustrate. +intended for package and class authors, so they are documented only in +\cite{latex:clsguide} and not in \cite{latex:usrguide}. However, with letters +there are useful applications at the user level for both new hooks, as the +following example illustrates. % \begin{Example} - It is given that one has to set multiple letters with questionnaires - within one document. Questions are numbered automatically within - single letters using a counter. Since, in contrast to page - numbering, that counter is not known by \Class{scrlttr2}, it would - not be reset at the start of each new letter. Given that each - questionnaire contains ten questions, question~1 would get number~11 - in the second letter. A solution is to reset this counter at the - beginning of each new letter: + Suppose you have several letters in a document that use their own commands + to insert a questionnaire in the letters. The questions are numbered + automatically using a counter. Since \KOMAScript{} is unaware of this + counter, it would not be reset at the start of each new letter, unlike the + page number. If each questionnaire contains ten questions, the first + question in the fifth letter would get the number~41. You can solve this + problem by telling \KOMAScript{} to reset this counter at the beginning of + each letter: \begin{lstlisting} \newcounter{Question} \newcommand{\Question}[1]{% @@ -689,9 +705,10 @@ following example may illustrate. \AtBeginLetter{\setcounter{Question}{0}} \end{lstlisting} This way first question remains question~1, even in the 1001st letter. Of - course the definition at this example needs package - \Package{tabularx}\IndexPackage{tabularx} (see \cite{package:tabularx}). -\end{Example} + course the definition in this example requires the + \Package{tabularx}\IndexPackage{tabularx} package (see + \cite{package:tabularx}). +\end{Example}% % \EndIndexGroup @@ -702,14 +719,15 @@ following example may illustrate. \Macro{letterlastpage} \end{Declaration} If\ChangedAt{v3.19}{\Class{scrlttr2}\and \Package{scrletter}} you have more -than one letter in one document, it is useful to have a letter number. Since -version~3.19 \KOMAScript{} provides counter \Counter{letter} and increases it -at every \Macro{begin}\PParameter{letter}. +than one letter in a document, it is useful to have a letter number. For this +purpose, \KOMAScript{} has provided the \Counter{letter} counter, which +is incremented by one at each \Macro{begin}\PParameter{letter}, since +version~3.19. \begin{Example} - Have one more look into the \DescRef{\LabelBase.cmd.AtBeginLetter} + Let's return to the \DescRef{\LabelBase.cmd.AtBeginLetter} example. Instead of resetting the counter explicitly at - \Macro{begin}\PParameter{letter}, we can do it implicitly by defining - counter \Counter{Question} depending on counter \Counter{letter}: + \Macro{begin}\PParameter{letter}, we can do so implicitly by defining + counter \Counter{Question} to depend on counter \Counter{letter}: \begin{lstlisting} \newcounter{Question}[letter] \newcommand{\Question}[1]{% @@ -719,91 +737,100 @@ at every \Macro{begin}\PParameter{letter}. \end{tabularx}% }% \end{lstlisting} - Now, the new counter will be reset at every start of a new letter and - the first question of every letter will be number one. + Now the new counter will be reset at every start of each letter so that + the first question in each letter will be number one. \end{Example} -If you want the output of current value of \Counter{letter}, you may usually -use \Macro{theletter}. Indeed the letter can also be used for +If you want to display the current value of \Counter{letter}, this is +possible, as usual, with \Macro{theletter}. The counter can also be used for cross-references. So you can use \Macro{label}\Parameter{name} to generate a label immediately after \Macro{begin}\PParameter{letter} and reference it somewhere in the document using \Macro{ref}\Parameter{name}. Inside the same -letter you can simply use \Macro{thisletter} without generating a label to get -the same result. - -\KOMAScript{} itself uses \Macro{thisletter} to put a label onto the last page -of every letter. You can use -\Macro{letterlastpage}\IndexCmd{label}\IndexCmd{pageref} to reference the last -page number of the current letter. Please note, the value of -\Macro{letterlastpage} is valid after some \LaTeX{} runs, because it uses -\Macro{label} and \Macro{pageref}. So you need at least two or three \LaTeX{} -runs, if you use \Macro{letterlastpage}. Please have a look at \emph{Rerun} -terminal or \File{log}-file messages about labels that have been changed.% +letter you can get the same result by simply using \Macro{thisletter} without +creating a label. + +For labels in form letters, it is necessary to give them a unique name across +all letters. Once again, you can use \Macro{thisletter} for this purpose. +\KOMAScript{} also uses \Macro{thisletter} internally to put a label on the +last page of each letter. This makes it possible to use +\Macro{letterlastpage}\IndexCmd{label}\IndexCmd{pageref} to reference the +number of the last page of the current letter at any point within the letter. +Since \Macro{letterlastpage} uses \Macro{label} and \Macro{pageref}, it is +only valid after several \LaTeX{} runs\,---\,usually two or three. If you use +\Macro{letterlastpage}, pay attention to the \emph{Rerun} messages in the +terminal output or \File{log} file messages about labels that have been +changed.% \EndIndexGroup \begin{Declaration} - \Macro{opening}\Parameter{opening} + \Macro{opening}\Parameter{salutation} \end{Declaration} -This is one of the most important commands in \Class{scrlttr2}. For the user -it may seem that only the \PName{opening}\Index{letter>opening}, e.\,g., -``Dear Mrs~\dots'', is typeset, but\textnote{Attention!} the command also -typesets the folding marks\Index{folding marks}, -letterhead\Index{letter>head}, address field\Index{address field}, reference -fields line\Index{reference line}, subject\Index{subject}, the page -footer\Index{page>footer} and others. In short, without \Macro{opening} there -is no letter. And if you want to print a letter without opening you have to -use an \Macro{opening} command with an empty argument. +This is one of the most important commands for letters. On the surface, it may +seem that only the \PName{salutation}\Index{letter>salutation}, for example +``Dear Mrs~\dots'', is printed. Actually\textnote{Attention!}, this command +also prints the fold marks\Index{fold marks}, the +letterhead\Index{letterhead}, the address\Index{address}, the extra sender +information, the reference line\Index{reference line}, the title\Index{title}, +the subject\Index{subject}, and the footer\Index{page>footer}. In short, +without \Macro{opening} there is no letter. If, in fact, you want to print a +letter without a salutation, you have to use an \Macro{opening} command with +an empty argument. \begin{Example} - Let's extend the example from - \DescPageRef{\LabelBase.env.letter.example} by an opening: + Let's return to the example of + \DescPageRef{\LabelBase.env.letter.example} and add a salutation: \lstinputcode[xleftmargin=1em]{letter-0.tex} - This will result in a note paper sheet shown in + This will result in the letterhead shown in \autoref{fig:\LabelBase.letter-0}. \begin{figure} \setcapindent{0pt}% - \begin{captionbeside}[{Example: letter with addressee and opening}]{% - result of a minimalistic letter with addressee and opening only - (date and folding marks are defaults of DIN-letters)}[l] + \begin{captionbeside}[{Example: letter with recipient and salutation}]{% + result of a minimalist letter with recipient and salutation only + (the date is set by default)}[l] \frame{\includegraphics[width=.4\textwidth]{letter-0}} \end{captionbeside} \label{fig:\LabelBase.letter-0} \end{figure} \end{Example} \iffalse% Umbruchkorrekturtext - -In the early days of computer-generated letters, programs did not have many -capabilities, therefore the letters seldom had an opening. Today the -capabilities have been enhanced. Thus personal openings are very common, even -in mass-production advertising letters.% +\begin{Explain} + In the early days of computer-generated letters, a salutation was normally + omitted, since individualised form letters were hardly possible. Today + personalised greetings are common in in mass mailings.% +\end{Explain} \fi % \EndIndexGroup + \begin{Declaration} - \Macro{closing}\Parameter{closing phrase} + \Macro{closing}\Parameter{concluding text} \end{Declaration} The main purpose of the command \Macro{closing} is to typeset the -\PName{closing phrase}\Index{closing}. This may even consists of multiple -lines. The lines should be separated by double backslash. Paragraph breaks -inside the \PName{closing phrase} are not allowed. +\PName{concluding text}\Index{closing}. This can even consist of multiple +lines. In that case, the individual lines should be separated by a double +backslash. Paragraph breaks inside the \PName{concluding text} are not +allowed. -Beyond that the command also typesets the content of the variable -\DescRef{\LabelBase.variable.signature}. More information about the signature and the -configuration of the signature may be found at \autoref{sec:\LabelBase.closing} -ab \DescPageRef{\LabelBase.variable.signature}. +In addition, this command also prints the content of the +\DescRef{\LabelBase.variable.signature} variable. You can find more +information about the signature and its configuration in +\autoref{sec:\LabelBase.closing} on +\DescPageRef{\LabelBase.variable.signature}. \begin{Example} - Let's extend the our example by some lines of text and a closing phrase: + Let's extend the our example with a few lines of text and a closing phrase: \lstinputcode[xleftmargin=1em]{letter-1.tex} This will result in a the letter shown in \autoref{fig:\LabelBase.letter-1}. \begin{figure} \setcapindent{0pt}% - \begin{captionbeside}[{Example: letter with addressee, opening, text, and + \begin{captionbeside}[{Example: letter with recipient, opening, text, and closing}]{% - result of a small letter with addressee, opening, text, and closing - (date and folding marks are defaults of DIN-letters)}[l] + result of a short letter with recipient, opening, text, and closing + % The refernce to DIN-letters in the German guide isn't relevant for + % English-language letters + (the date is set by default)}[l] \frame{\includegraphics[width=.4\textwidth]{letter-1}} \end{captionbeside} \label{fig:\LabelBase.letter-1} @@ -815,25 +842,24 @@ ab \DescPageRef{\LabelBase.variable.signature}. \begin{Declaration} \Macro{ps} \end{Declaration}% -This instruction merely switches to the postscript. Hence, a new -paragraph begins, and a vertical distance\,---\,usually below the -signature\,---\,is inserted. The command \Macro{ps} is followed by -normal text. If you want the postscript to be introduced with the -acronym ``PS:'' , which by the way is written without a full stop, you -have to type this yourself. The acronym is typeset neither -automatically nor optionally by the class \Class{scrlttr2}. +This instruction merely switches to the postscript. To do so, a new paragraph +begins, and a vertical gap\,---\,usually below the signature\,---\,is +inserted. The \Macro{ps} text can be followed by any text. If you want the +postscript to be introduced with the acronym ``PS:'', which in most current +usage is written without full stops, you have to type this yourself. This +abbreviation is printed neither automatically nor optionally by the +\Class{scrlttr2} class. \begin{Example} - The example letter extended by a postscript + The sample letter with the addition of a postscript \lstinputcode[xleftmargin=1em]{letter-2.tex} results in \autoref{fig:\LabelBase.letter-2}. \begin{figure} \setcapindent{0pt}% - \begin{captionbeside}[{Example: letter with addressee, opening, text, + \begin{captionbeside}[{Example: letter with recipient, opening, text, closing, and postscript}]{% - result of a small letter with addressee, opening, text, closing, and - postscript - (date and folding marks are defaults of DIN-letters)}[l] + result of a short letter with recipient, opening, text, closing, and + postscript (the date is set by default)}[l] \frame{\includegraphics[width=.4\textwidth]{letter-2}} \end{captionbeside} \label{fig:\LabelBase.letter-2} @@ -841,13 +867,12 @@ automatically nor optionally by the class \Class{scrlttr2}. \end{Example} \begin{Explain} - In the time when letters were written by hand it was quite common to use a - postscript because this was the only way to add information which one had - forgotten to mention in the main part of the letter. Of course, in letters - written with {\LaTeX} you can insert additional lines easily. Nevertheless, - it is still popular to use the postscript. It gives one a good possibility - to underline again the most important or sometimes the less important things - of the particular letter. + When letters were written still by hand, it was quite common to use a + postscript because this was the only way to add information which had been + forgotten in the main part of the letter. For letters written with \LaTeX{}, + of course, you can easily insert additional lines. Nevertheless, postscripts + remain popular. They can be useful to emphasize important points once more, + or even to mention the less important matters. \end{Explain} % \EndIndexGroup @@ -857,34 +882,32 @@ automatically nor optionally by the class \Class{scrlttr2}. \Macro{cc}\Parameter{distribution list}% \Variable{ccseparator}% \end{Declaration} -With the command \Macro{cc}% -\Index{addressee>additional}\Index{distribution list}\Index{carbon copy} it is -possible to typeset a \PName{distribution list}. The command takes the -\PName{distribution list} as its argument. If the content of the variable -\Variable{ccseparator}\Index{separator}\Index{delimiter} is not empty, then -the name and the content of this variable is inserted before -\PName{distribution list}. In this case the \PName{distribution list} will be -indented appropriately. It is a good idea\textnote{Hint!} to set the +You can print a \PName{distribution list}\Index{recipient>additional}% +\Index{distribution list}\Index{carbon copy} with the \Macro{cc} command. The +command takes the \PName{distribution list} as its argument. If the content of +the variable \Variable{ccseparator}\Index{separator}\Index{delimiter} is not +empty, the name and content of this variable are inserted before the +\PName{distribution list}. In this case, the \PName{distribution list} will be +indented appropriately. It's a good idea\textnote{Hint!} to set the \PName{distribution list} \Macro{raggedright}\IndexCmd{raggedright} and to separate the individual entries with a double backslash. \begin{Example} - This time, the example letter should be send not only to the chairman, but - also to all club members: + This time, the sample letter should go not only to the chairman but also to + all club members: \lstinputcode[xleftmargin=1em]{letter-3.tex}% The result is shown in \autoref{fig:\LabelBase.letter-3}. \begin{figure} \setcapindent{0pt}% - \begin{captionbeside}[{Example: letter with addressee, opening, text, + \begin{captionbeside}[{Example: letter with recipient, opening, text, closing, postscript, and distribution list}]{% - result of a small letter with addressee, opening, text, closing, - postscript, and distribution list - (date and folding marks are defaults of DIN-letters)}[l] + result of a short letter with recipient, opening, text, closing, + postscript, and distribution list (the date is set by default)}[l] \frame{\includegraphics[width=.4\textwidth]{letter-3}} \end{captionbeside} \label{fig:\LabelBase.letter-3} \end{figure} \end{Example} -In front of the distribution list a vertical gap is inserted automatically.% +A vertical gap is inserted automatically before the distribution list.% % \EndIndexGroup @@ -893,24 +916,23 @@ In front of the distribution list a vertical gap is inserted automatically.% \Macro{encl}\Parameter{enclosures}% \Variable{enclseparator}% \end{Declaration} -The \PName{enclosures} have the same structure as the distribution list. -The only difference is that here the enclosures starts with the name -and content of the variable -\Variable{enclseparator}\Index{separator}\Index{delimiter}. +The \PName{enclosures} have the same structure as the distribution list. The +only difference is that the list of enclosures begins with the name and +content of the \Variable{enclseparator}\Index{separator}\Index{delimiter} +variable. \begin{Example} - Now, the example letter will be extended by some paragraphs from the - constitution. These will be added as an enclosure. The description title - will be changed also, because there is only one enclosure and the default - may be prepared for several enclosures: + To the sample letter we will attach an excerpt from the club's articles of + association. These will be added as an enclosure. Because there is only one + enclosure, we change the description title accordingly: \lstinputcode[xleftmargin=1em]{letter-4.tex} This will result in \autoref{fig:\LabelBase.letter-4}. \begin{figure} \setcapindent{0pt}% - \begin{captionbeside}[{Example: letter with addressee, opening, text, + \begin{captionbeside}[{Example: letter with recipient, opening, text, closing, postscript, distribution list, and enclosure}]{% - result of a small letter with addressee, opening, text, closing, - postscript, distribution list, and enclosure - (date and folding marks are defaults of DIN-letters)}[l] + result of a short letter with recipient, opening, text, closing, + postscript, distribution list, and enclosure (the date is set by + default)}[l] \frame{\includegraphics[width=.4\textwidth]{letter-4}} \end{captionbeside} \label{fig:\LabelBase.letter-4} @@ -922,69 +944,72 @@ and content of the variable \EndIndexGroup -\LoadCommonFile{fontsize} % \section{Selection of Document Font Size} +\LoadCommonFile{fontsize} % \section{Choosing the Document Font Size} \LoadCommonFile{textmarkup} % \section{Text Markup} -\section{Note Paper} +\section{Letterhead Page} \seclabel{firstpage} \BeginIndexGroup -\BeginIndex{}{note paper}% -\BeginIndex{}{letter>first page} - -The note paper is the first page and therefore the signboard of each -letter. In business scope often preprinted forms are used, that already -contains elements like the letter head with the sender's information and -logo. \KOMAScript{} provides to position these elements independent. With this -it is not only possible to replicate the note paper directly, but also to -complete the destined fields instantaneously. The independent position is -provided by pseudo-lengths (see \autoref{sec:\LabelBase.pseudoLength} from -\autopageref{sec:\LabelBase.pseudoLength} onward). A schematic display of the -note page and the used variable is shown by -\autoref{fig:\LabelBase.variables}. Thereby the names of the variables are -printed boldly for better distinction from the commands and their arguments. - -Following pages\Index{page>following}\Index{following page} are different from -the note paper. Following pages in the meaning of this manual are all letter -pages but the first one. +\BeginIndex{}{letterhead page}% + +The letterhead page is the first page of, and therefore the signpost for, each +letter. In a business context, the paper for this page is often preprinted +stationery containing elements such as a header with the sender's information +and logo. This header itself is also known as a letterhead. \KOMAScript{} lets +you position these elements freely, and so you can not only replicate the +letterhead page directly but also fill in the required fields instantaneously. +This free positioning is achieved with pseudo-lengths (see +\autoref{sec:\LabelBase.pseudoLength} starting on +\autopageref{sec:\LabelBase.pseudoLength}). You can find a schematic +representation of the letterhead page and the variables used for it in +\autoref{fig:\LabelBase.variables}. The names of the variables are printed in +bold to better distinguish the commands from their arguments. + +Subsequent pages\Index{page>subsequent}\Index{subsequent pages} should be +distinguished from the letterhead page. For the purposes of this manual, +subsequent pages are all pages of a letter except the first one. + \begin{figure} \centering \includegraphics[scale=0.99]{varDIN} - \caption{schematic display of the note paper with the most important - commands and variables for the drafted elements} + \caption{schematic display of the letterhead page outlining the most + important commands and variables} \label{fig:\LabelBase.variables} \end{figure} + \begin{Declaration} - \OptionVName{foldmarks}{selection} + \OptionVName{foldmarks}{setting} \end{Declaration} -Foldmarks\Index{foldmark} or folding marks\Index{folding mark} are tiny -horizontal rules at the left margin or tiny vertical rules at the top -margin. \KOMAScript{} currently provides three configurable horizontal folding -marks and one configurable vertical folding mark. Additionally it provides a -horizontal hole puncher mark, also known as page middle mark. This additional -mark cannot be moved vertically. - -This option activates or deactivates folding marks for vertical -two-, three- or four-panel folding, and a single horizontal folding, of the -letter, whereby the folding need not result in equal-sized parts. The position -of the four horizontal and the single vertical marks are configurable via -pseudo-lengths (see \autoref{sec:scrlttr2-experts.foldmarks} from -\DescPageRef{scrlttr2-experts.plength.foldmarkvpos} onwards). - -The user has a choice: Either one may use the standard values for simple -switches, as described in \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch}, to activate or deactivate at once all -configured folding marks on the left and upper edges of the paper; -or\ChangedAt{v2.97e}{\Class{scrlttr2}} one may specify by one or more letters, -as listed in \autoref{tab:\LabelBase.foldmark}, the use of the individual -folding marks independently. Also in the latter case the folding marks will only be -shown if they have not been switched off generally with one of \PValue{false}, -\PValue{off}, or \PValue{no}. The exact positioning of the folding marks is -specified in the user settings, that is, the \File{lco} files (see -\autoref{sec:\LabelBase.lcoFile} from \autopageref{sec:\LabelBase.lcoFile} onward) -chosen for a letter. Default values are \PValue{true} and \PValue{TBMPL}. +Fold marks\Index{fold mark}, or folding marks, are small horizontal rules in +the left margin and small vertical rules in the top margin. \KOMAScript{} +currently provides three configurable horizontal fold marks and one +configurable vertical fold mark. Additionally it provides a horizontal +hole-punch or page-centre mark. This additional mark cannot be moved +vertically. + +The \Option{foldmarks} option activates or deactivates fold marks for two, +three, or four vertical divisions and one horizontal division. The individual +parts do not have to be of equal size. The positions of three of the four +horizontal marks and the single vertical mark are configurable via +pseudo-lengths (see \autoref{sec:scrlttr2-experts.foldmarks} starting on +\DescPageRef{scrlttr2-experts.plength.foldmarkvpos}). + +With the \Option{foldmarks} option, you can either use the default values for +simple switches described in \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch} in order to activate or deactivate all +configured fold marks on the left and upper edges of the paper at once, +or\ChangedAt{v2.97e}{\Class{scrlttr2}} you can configure the individual fold +marks independently by specifying one or more letters, as listed in +\autoref{tab:\LabelBase.foldmark}. In the latter case, the fold marks are only +shown if they have not been deactivated globally with \PValue{false}, +\PValue{off}, or \PValue{no}. The exact position of the fold marks is depends +on the user settings or the \File{lco} files (see +\autoref{sec:\LabelBase.lcoFile} starting on +\autopageref{sec:\LabelBase.lcoFile}). The default values are \PValue{true} +and \PValue{TBMPL}.\textnote{default} % \begin{table} % \centering @@ -992,25 +1017,25 @@ chosen for a letter. Default values are \PValue{true} and \PValue{TBMPL}. \setcapindent{0pt}% % \caption \begin{captionbeside}{% - Combinable values for the configuration of folding marks with - option \Option{foldmarks}% + Combinable values for configuring fold marks with the + \Option{foldmarks} option% }[l] \begin{tabular}[t]{ll} \toprule - \PValue{B} & activate upper horizontal foldmark on left paper edge\\% - \PValue{b} & deactivate upper horizontal foldmark on left paper edge\\% - \PValue{H} & activate all horizontal folding marks on left paper edge\\% - \PValue{h} & deactivate all horizontal folding marks on left paper edge\\% - \PValue{L} & activate left vertical foldmark on upper paper edge\\% - \PValue{l} & deactivate left vertical foldmark on upper paper edge\\% - \PValue{M} & activate middle horizontal foldmark on left paper edge\\% - \PValue{m} & deactivate middle horizontal foldmark on left paper edge\\% - \PValue{P} & activate punch or center mark on left paper edge\\% - \PValue{p} & deactivate punch or center mark on left paper edge\\% - \PValue{T} & activate lower horizontal foldmark on left paper edge\\% - \PValue{t} & deactivate lower horizontal foldmark on left paper edge\\% - \PValue{V} & activate all vertical folding marks on upper paper edge\\% - \PValue{v} & deactivate all vertical folding marks on upper paper edge\\% + \PValue{B} & activate bottom horizontal fold mark on left paper edge\\% + \PValue{b} & deactivate bottom horizontal fold mark on left paper edge\\% + \PValue{H} & activate all horizontal fold marks on left paper edge\\% + \PValue{h} & deactivate all horizontal fold marks on left paper edge\\% + \PValue{L} & activate left vertical fold mark on upper paper edge\\% + \PValue{l} & deactivate left vertical fold mark on upper paper edge\\% + \PValue{M} & activate middle horizontal fold mark on left paper edge\\% + \PValue{m} & deactivate middle horizontal fold mark on left paper edge\\% + \PValue{P} & activate hole-punch or centre mark on left paper edge\\% + \PValue{p} & deactivate hole-punch or centre mark on left paper edge\\% + \PValue{T} & activate top horizontal fold mark on left paper edge\\% + \PValue{t} & deactivate top horizontal fold mark on left paper edge\\% + \PValue{V} & activate all vertical fold marks on upper paper edge\\% + \PValue{v} & deactivate all vertical fold marks on upper paper edge\\% \bottomrule \end{tabular} \end{captionbeside} @@ -1018,59 +1043,57 @@ chosen for a letter. Default values are \PValue{true} and \PValue{TBMPL}. \end{table} % \begin{Example} - Assume that you would like to deactivate all folding marks except the punching - mark. This you can accomplish with, for example: + Suppose you want to deactivate all fold marks except the hole-punch mark. If + the default has not already been changed, you can deactivate it as follows: \begin{lstlisting} \KOMAoptions{foldmarks=blmt} \end{lstlisting} - as long as the defaults have not been changed previously. If some changes - might have been made before, a safer method should be used. This changes our - example a little bit: + If there is a chance that the default has already been changed, you should + use a safer method. This changes our example a little bit: \lstinputcode[xleftmargin=1em]{letter-7}% The result is shown in \autoref{fig:\LabelBase.letter-7}. \begin{figure} \setcapindent{0pt}% - \begin{captionbeside}[{Example: letter with addressee, opening, text, - closing, postscript, distribution list, enclosure, and hole puncher + \begin{captionbeside}[{Example: letter with recipient, opening, text, + closing, postscript, distribution list, enclosure, and hole-punch mark}]{% - result of a small letter with addressee, opening, text, closing, - postscript, distribution list, enclosure, and hole puncher mark - (the date is a default of DIN-letters)}[l] + result of a short letter with recipient, opening, text, closing, + postscript, distribution list, enclosure, and hole-punch mark + (the date is set by default)}[l] \frame{\includegraphics[width=.4\textwidth]{letter-7}} \end{captionbeside} \label{fig:\LabelBase.letter-7} \end{figure} \end{Example} \BeginIndex{FontElement}{foldmark}\LabelFontElement{foldmark}% -The color of the folding mark may be changed -using\ChangedAt{v2.97c}{\Class{scrlttr2}} using the commands -\DescRef{\LabelBase.cmd.setkomafont} and -\DescRef{\LabelBase.cmd.addtokomafont} (see +You\ChangedAt{v2.97c}{\Class{scrlttr2}} can change the colour of the fold mark +with the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}) -with element \FontElement{foldmark}. Default is not change.% -\EndIndex{FontElement}{foldmark}% -% +with the \FontElement{foldmark} element. The default is no change.% \EndIndexGroup \begin{Declaration} \OptionVName{enlargefirstpage}{simple switch} \end{Declaration} -The first page of a letter always uses a different page layout. The -\Class{scrlttr2} class provides a mechanism to calculate height and vertical -alignment of header and footer of the first page independently of the -following pages. If, as a result, the footer of the first page would reach -into the text area, this text area is automatically made smaller using the -\Macro{enlargethispage}\IndexCmd{enlargethispage} macro. On the other hand, if -the text area should become larger, supposing that the footer on the first -page allows that, you can use this option. At best, a little more text will -then fit on the first page. See also the description of the pseudo-length -\PLength{firstfootvpos} on -\DescPageRef{scrlttr2-experts.plength.firstfootvpos}. This option can -take the standard values for simple switches, as listed in -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. Default is -\PValue{false}. -% +\begin{Explain} + The first page of a letter always uses a different page layout because of + the many predefined elements such as the letterhead or the address. The + \Class{scrlttr2} class provides a mechanism to calculate height and vertical + alignment of header and footer of the first page independently of the + subsequent pages. If, as a result, the footer of the first page would + protrude into the text area, this text area of the first page is + automatically reduced using + \Macro{enlargethispage}\IndexCmd{enlargethispage}. +\end{Explain} +If the text area should become larger, assuming the footer on the first page +permits this, you can use this option. At best, a little more text will then +fit on the first page. See also the description of the \PLength{firstfootvpos} +pseudo-length on \DescPageRef{scrlttr2-experts.plength.firstfootvpos}. This +option takes the standard values for simple switches, as listed in +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. The default +is \PValue{false}.\textnote{default}% \EndIndexGroup @@ -1078,12 +1101,12 @@ take the standard values for simple switches, as listed in \OptionVName{firsthead}{simple switch} \end{Declaration} \BeginIndex{}{letterhead}% -\BeginIndex{}{letter>head}% +\BeginIndex{}{letter>header}% The\ChangedAt{v2.97e}{\Class{scrlttr2}} letterhead is usually the topmost -element of the note paper. This option determines whether the letterhead will -be typeset at all. The option accepts the standard values for simple keys, -given in \autoref{tab:truefalseswitch} at -\autopageref{tab:truefalseswitch}. Default is for the letterhead to be set.% +element of the letterhead page. With the \Option{firsthead} option, you can +choose whether the letterhead will be typeset at all. The option accepts the +standard values for simple switches given in \autoref{tab:truefalseswitch} on +\autopageref{tab:truefalseswitch}. The default is to typeset the letterhead.% % \EndIndexGroup @@ -1093,47 +1116,49 @@ given in \autoref{tab:truefalseswitch} at \end{Declaration} \BeginIndex{}{letterhead}% \BeginIndex{}{letter>head}% -Option\important{\Option{fromalign}} \Option{fromalign} defines the placement -of the return address in the letterhead of the first page. Apart from the -various options for positioning the return address in the letterhead, there is -also the option\ChangedAt{v2.97e}{\Class{scrlttr2}} of adding the return -address to the sender's extension\Index{sender's - extension}. Further\textnote{Attention!}, this option serves as a switch to -activate or deactivate the letterhead extensions. If these extensions are -deactivated, some other options will have no effect. This will be noted in the -explanations of the respective options. Possible values for \Option{fromalign} -are shown in \autoref{tab:\LabelBase.fromalign}. Default is \PValue{left}.% +The\important{\Option{fromalign}} \Option{fromalign} option determines where +the sender information should be placed on the first page. In addition to the +various placement options in the letterhead, you also have the +ability\ChangedAt{v2.97e}{\Class{scrlttr2}} to accommodate extra sender +information\Index{extra sender information}. At the same +time\textnote{Attention!}, this option serves as a central switch to activate +or deactivate letterhead extensions. If these extensions are deactivated, some +other options will have no effect. This will be noted in the explanations of +the respective options. Available values for \Option{fromalign} are shown in +\autoref{tab:\LabelBase.fromalign}. The default value is \PValue{left}.% % \begin{table} - \caption[{Available values for option \Option{fromalign} with - \Class{scrlttr2}}]{Available values for option \Option{fromalign} to + \caption[{Available values for the \Option{fromalign} option with + \Class{scrlttr2}}]{Available values for the \Option{fromalign} option to define the position of the from address in the letterhead with \Class{scrlttr2}} \label{tab:\LabelBase.fromalign} \begin{desctabular} \entry{\PValue{center}, \PValue{centered}, \PValue{middle}}{% - return address centered; an optional logo will be above the extended - return address; letterhead extensions will be activated}% + Sender information is centred inside the letterhead; a logo is + placed at the beginning of the extra sender information, if + applicable; letterhead extensions are activated.}% \entry{\PValue{false}, \PValue{no}, \PValue{off}}{% - standard design will be used for the return address; the letterhead - extensions are deactivated}% + The default design will be used for the sender information; the + letterhead extensions are deactivated.}% \entry{\PValue{left}}{% - left-justified return address; an optional logo will be right justified; - letterhead extensions will be activated}% + Sender information is left-aligned in the letterhead; a logo is + placed right-aligned, if applicable; letterhead extensions are + activated.}% \entry{\PValue{locationleft}, \PValue{leftlocation}}{% - return address is set left-justified in the sender's extension; a logo, - if applicable, will be placed above it; the letterhead is automatically - deactivated but can be reactivated using option - \DescRef{\LabelBase.option.firsthead}.}% + Sender information is left-justified and uses the extra sender + information; a logo is placed at the top of it, if applicable; the + letterhead is automatically deactivated but can be reactivated using the + \DescRef{\LabelBase.option.firsthead} option.}% \entry{\PValue{locationright}, \PValue{rightlocation}, \PValue{location}}{% - return address is set right-justified in the sender's extension; a logo, - if applicable, will be placed above it; the letterhead is automatically - deactivated but can be reactivated using option - \DescRef{\LabelBase.option.firsthead}.}% + Sender information is right-justified and uses the extra sender + information; a logo is placed at the top of it, if applicable; the + letterhead is automatically deactivated but can be reactivated using the + \DescRef{\LabelBase.option.firsthead} option.}% \entry{\PValue{right}}{% - right-justified return address; an optional logo will be left justified; - letterhead extensions will be activated}% + Sender information is right-justified; a logo is placed left-justified, + if applicable; letterhead extensions are activated}% \end{desctabular} \end{table} % @@ -1147,31 +1172,31 @@ are shown in \autoref{tab:\LabelBase.fromalign}. Default is \PValue{left}.% \end{Declaration} \BeginIndex{}{letterhead}% \BeginIndex{}{letter>head}% -The\important{\Variable{fromname}} sender's name will be determined by -variable \Variable{fromname}. Thereby the \PName{description} (see also -\autoref{tab:\LabelBase.fromTerm}, \autopageref{tab:\LabelBase.fromTerm}) will not -be used by the predefined letterheads. +The\important{\Variable{fromname}} sender's name is determined by the +\Variable{fromname} variable. Its \PName{description} (see also +\autoref{tab:\LabelBase.fromTerm}, \autopageref{tab:\LabelBase.fromTerm}) is +not used in the default letterheads. -At\important{\OptionValue{fromrule}{aftername}} the extended letterhead an -optional horizontal rule below the name may be selected using +In\important{\OptionValue{fromrule}{aftername}} the extended letterhead, you +can create a horizontal rule below the sender's name with \OptionValue{fromrule}{aftername}. -Alternatively\important[i]{\begin{tabular}{@{}l@{}} - \KOption{fromrule}\\\quad\PValue{afteraddress}\end{tabular}} this rule may -be placed below the while sender using \OptionValue{fromrule}{afteraddress}. A -summary of all available rule position settings shows -\autoref{tab:\LabelBase.fromrule}. The length of this rule is determined by -pseudo-length \PLength{fromrulewidth}\IndexPLength[indexmain]{fromrulewidth}. +Alternatively\important{\OptionValue{fromrule}{afteraddress}} you can place +this rule below the complete sender information with +\OptionValue{fromrule}{afteraddress}. A summary of all available settings for +the rule position is shown in \autoref{tab:\LabelBase.fromrule}. The length of +this rule is determined by the +\PLength{fromrulewidth}\IndexPLength[indexmain]{fromrulewidth} pseudo-length. \begin{table} - \caption[{Possible values of option \Option{fromrule} with - \Class{scrlttr2}}]{Possible values of option \Option{fromrule} for the - position of the rule in the from address with + \caption[{Available values of the \Option{fromrule} option with + \Class{scrlttr2}}]{Available values of the \Option{fromrule} option for the + position of the rule in the sender information with \Class{scrlttr2}} \label{tab:\LabelBase.fromrule} \begin{desctabular} \entry{\PValue{afteraddress}, \PValue{below}, \PValue{on}, \PValue{true}, \PValue{yes}}{% - rule below the return address}% + rule below the sender's address}% \entry{\PValue{aftername}}{% rule directly below the sender's name}% \entry{\PValue{false}, \PValue{no}, \PValue{off}}{% @@ -1179,100 +1204,101 @@ pseudo-length \PLength{fromrulewidth}\IndexPLength[indexmain]{fromrulewidth}. \end{desctabular} \end{table} -Default for the rule at the extended letterhead is \PValue{false}. But at the -standard letterhead the rule will always be placed below the sender's name. +The default\textnote{default} for the rule with the extended letterhead is +\PValue{false}. But in the standard letterhead, the rule will always be placed +below the sender's name. -The\important{\Variable{fromaddress}} sender's address follows below the -name. The \PName{content} of variable \Variable{fromaddress} determines this -address. The \PName{description} (see also \autoref{tab:\LabelBase.fromTerm}) -will not be used at the predefined letterheads +The\important{\Variable{fromaddress}} sender's address follows below the name. +The \PName{content} of variable \Variable{fromaddress} determines this +address. The address \PName{description} (see also +\autoref{tab:\LabelBase.fromTerm}) is not used in the default letterheads \BeginIndexGroup \BeginIndex{FontElement}{fromaddress}\LabelFontElement{fromaddress}% \BeginIndex{FontElement}{fromname}\LabelFontElement{fromname}% \BeginIndex{FontElement}{fromrule}\LabelFontElement{fromrule}% -The font of the whole address is determined by the element +You can set the font used for the complete sender information with the \FontElement{fromaddress}\IndexFontElement{fromaddress}% -\important{\FontElement{fromaddress}}. Modifications to this may be defined -with element \FontElement{fromname}\IndexFontElement{fromname}% -\important{\FontElement{fromname}} for the sender's name and with element +\important{\FontElement{fromaddress}} element. You can define modifications to +this with the \FontElement{fromname}\IndexFontElement{fromname}% +\important{\FontElement{fromname}} element for the sender's name, and with the \FontElement{fromrule}\IndexFontElement{fromrule}% -\important{\FontElement{fromrule}} for the rule, that may be activated using -option \Option{fromrule}. Nevertheless changing the font style of the rule -would make sense. But you may use the elements also to change the color, -e.\,g. color the rule gray instead of black. See \cite{package:xcolor} for -information about colors.% +\important{\FontElement{fromrule}} element for the rule created with the +\Option{fromrule} option. The default setting does not change the font. For +the rule, font switching is mainly intended to change the colour of the rule, +for example to use grey instead of black. See \cite{package:xcolor} for +information about colours.% % \EndIndexGroup \begin{Example} - Let's now define the name of the sender at our letter example: + Now let's give the sender of our sample letter a name: \lstinputcode[xleftmargin=1em]{letter-8.tex} \begin{figure} \centering \frame{\includegraphics[width=.4\textwidth]{letter-8}}\quad \frame{\includegraphics[width=.4\textwidth]{letter-9}} - \caption[{Example: letter with sender, addressee, opening, text, closing, + \caption[{Example: letter with sender, recipient, opening, text, closing, postscript, distribution list, and enclosure}] - {result of a small letter with sender, addressee, opening, text, closing, - postscript, distribution list, and enclosure (date and folding marks are - defaults of DIN-letters): at left one the standard letterhead using - \OptionValueRef{\LabelBase}{fromalign}{false}, at right one the + {result of a short letter with sender, recipient, opening, text, closing, + postscript, distribution list, and enclosure (the date is set by + default): on the left, the standard letterhead using + \OptionValueRef{\LabelBase}{fromalign}{false}; on the right, the extended letterhead using \OptionValueRef{\LabelBase}{fromalign}{center}} \label{fig:\LabelBase.letter-8-9} \end{figure} - First of all not the extended but the standard letterhead has been used. The - result is shown at the left side of \autoref{fig:\LabelBase.letter-8-9}. The - right side shows almost the same letter but with - \OptionValueRef{\LabelBase}{fromalign}{center} and therefore with the extended - letterhead. You may see, that this variation is without any rule. - - For the first time \autoref{fig:\LabelBase.letter-8-9} also shows a signature - below the closing phrase. This has been generated automatically from the - sender's name. More information about configuration of the signature may be - found in \autoref{sec:\LabelBase.closing} from - \autopageref{sec:\LabelBase.closing} onward. - - Now, the letter with extended letterhead should use option \Option{fromrule} - to print a rule below the sender's name:% + Initially, the standard rather than the extended letterhead is used. The + result can be seen in \autoref{fig:\LabelBase.letter-8-9} on the left. For + comparison, the same example is shown on the right with + \OptionValueRef{\LabelBase}{fromalign}{center} (that is, with the extended + letterhead). You can see that this variation initially has no rule. + + For the first time, \autoref{fig:\LabelBase.letter-8-9} also shows a + signature below the closing phrase. This is generated automatically from the + sender's name. You can find more information about how to configure the + signature in \autoref{sec:\LabelBase.closing}, starting on + \autopageref{sec:\LabelBase.closing}. + + Next, the letter with the extended letterhead should use the + \Option{fromrule} option to print a rule below the sender's name:% \lstinputcode[xleftmargin=1em]{letter-11.tex}% - The result may be found at the right side of - \autoref{fig:\LabelBase.letter-10-11}. + You can see the result on the right in + \autoref{fig:\LabelBase.letter-10-11}. By comparison, the same example on + the left uses the standard letterhead, which ignores the additional options. + % \begin{figure} \centering \frame{\includegraphics[width=.4\textwidth]{letter-10}}\quad \frame{\includegraphics[width=.4\textwidth]{letter-11}} - \caption[{Example: letter with sender, separation rule, addressee, + \caption[{Example: letter with sender, rule, recipient, opening, text, closing, signature, postscript, distribution list, - enclosure, and puncher hole mark}] - {result of a small letter with sender, separation rule, addressee, + enclosure, and hole-punch mark}] + {result of a short letter with sender, rule, recipient, opening, text, closing, signature, postscript, distribution list, - enclosure and puncher hole mark (the date is a default of DIN-letters): + enclosure and hole-punch mark (the date is set by default): at left one the standard letterhead using \OptionValueRef{\LabelBase}{fromalign}{false}, at right one the extended letterhead using \OptionValueRef{\LabelBase}{fromalign}{center}} \label{fig:\LabelBase.letter-10-11} \end{figure} - In difference to this, the left letter has been set once again with the - standard letter head, that does not react on the additional option. \end{Example} An\textnote{Attention!} important note concerns the sender's address: within -the sender's address, parts such as street, P.O.~Box, state, country, etc., -are separated with a double backslash. Depending on how the sender's address -is used, this double backslash will be interpreted differently and therefore -is not strictly always a line break. Paragraphs, vertical spacing and the like -are usually not allowed within the sender's address declaration. One has to -have very good knowledge of \Class{scrlttr2} to use things like those -mentioned above, intelligently. Another point to note is the one should most -certainly set the variables for return address (see variable -\DescRef{\LabelBase.variable.backaddress}, \DescPageRef{\LabelBase.variable.backaddress}) and -signature (see variable \DescRef{\LabelBase.variable.signature}, -\DescPageRef{\LabelBase.variable.signature}) oneself.% +the sender's address, individual parts such as house number and street, city +and postal code, etc., are separated with a double backslash. This double +backslash is interpreted differently depending on how the sender's address is +used and therefore is not necessarily a line break. Paragraphs, vertical +spacing, and the like are usually not allowed within the sender's information. +You have to know \KOMAScript{} very well to put such things into the sender +information, if necessary. In addition, note that if you do so, you should +definitely set the variables for return address (see +\DescRef{\LabelBase.variable.backaddress}, +\DescPageRef{\LabelBase.variable.backaddress}) and signature (see +\DescRef{\LabelBase.variable.signature}, +\DescPageRef{\LabelBase.variable.signature}) yourself.% % \EndIndexGroup - \begin{Declaration} \OptionVName{symbolicnames}{simple switch}% \OptionVName{fromphone}{simple switch}% @@ -1290,42 +1316,47 @@ signature (see variable \DescRef{\LabelBase.variable.signature}, \Variable{faxseparator}% \Variable{emailseparator}% \Variable{urlseparator}% -\end{Declaration}% +\end{Declaration} \BeginIndex{}{letterhead}% -\BeginIndex{}{letter>head}% -Whether or not a telephone number\Index{telephone}\Index{phone}, a -mobile\ChangedAt{v3.12}{\Class{scrlttr2}} telephone number\Index{mobile - phone}\Index{cell phone}\Index{cellphone}, a fax number\Index{fax}, an -e-mail address\Index{e-mail}, or a sender's URL should be set as part of the -letterhead may be configured by the options \Option{fromphone}, -\Option{fromfax}, \Option{fromemail}, and \Option{fromurl}. Any standard value -for simple switches from \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch} may be assigned to these options. Default is -\PValue{false} for all of them. The \PName{contents} depends on the -corresponding variable. The default of the \PName{description} or title of -each variable may be found in \autoref{tab:\LabelBase.fromTerm}. The separators, -that will be inserted between \PName{description} and \PName{content}, may be -found in \autoref{tab:\LabelBase.fromSeparator}. - -You may\ChangedAt{v3.12}{\Class{scrlttr2}}\important{\Option{symbolicnames}} -change the defaults for the description of the separator variables at once -using option \Option{symbolicnames}. The option understands the values for -simple switches from \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch}. Switching on the option replaces the -descriptions from the language depending terms \DescRef{scrlttr2-experts.cmd.emailname}, -\DescRef{scrlttr2-experts.cmd.faxname}, \DescRef{scrlttr2-experts.cmd.mobilephonename}, and \DescRef{scrlttr2-experts.cmd.phonename} into symbols -of the package \Package{marvosym}\IndexPackage{marvosym}. Also the colon will -be removed from the content of the separator variables. And in this case the -description and the content of the URL separator will be -empty. Note\textnote{Attention!}, that you have to load package -\Package{marvosym} on your own, if you switch on \Option{symbolicnames} -first time after \Macro{begin}\PParameter{document}. +\BeginIndex{}{letter>header} +\iffree{\clearpage}{} +You can use the five options \Option{fromphone}, \Option{fromfax}, +\Option{fromemail}, and \Option{fromurl} to specify whether to include the +phone number\Index{telephone}\Index{phone}, +mobile\ChangedAt{v3.12}{\Class{scrlttr2}} phone number\Index{mobile +phone}\Index{cell phone}\Index{cellphone}, fax number\Index{fax}, e-mail +address\Index{e-mail}, or sender's URL should be as part of the sender's +information. You can assign any standard value for simple switches from +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} to these +options. The default for all of them is \PValue{false}. The \PName{contents} +themselves are determined by the variables of the same name. You can find the +defaults for the \PName{description} or title of each variable in +\autoref{tab:\LabelBase.fromTerm}. You can find the separators that will be +inserted between the \PName{description} and the \PName{content} in +\autoref{tab:\LabelBase.fromSeparator}. + +You can\ChangedAt{v3.12}{\Class{scrlttr2}}\important{\Option{symbolicnames}} +change the defaults for describing the variables all at once with the +\Option{symbolicnames} option. This option understands the values for simple +switches found in \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch}. Activating the option replaces the +descriptions from the language-dependant labels of +\DescRef{scrlttr2-experts.cmd.emailname}, +\DescRef{scrlttr2-experts.cmd.faxname}, +\DescRef{scrlttr2-experts.cmd.mobilephonename}, and +\DescRef{scrlttr2-experts.cmd.phonename} with symbols from the +\Package{marvosym}\IndexPackage{marvosym} package. At the same time, the colon +is omitted when defining the separators. In this case, both the description +and the content of the URL separator will be empty. Note\textnote{Attention!} +that you have to load the \Package{marvosym} package on your own if you activate +\Option{symbolicnames} for the first time after +\Macro{begin}\PParameter{document}. \begin{table} \centering - \caption[{Predefined descriptions of the variables of the - letterhead}]{Predefined descriptions of the variables of the letterhead - (the description and contents of the separator variables may be found at + \caption[{Default descriptions of the letterhead variables}]{Default + descriptions of the letterhead variables (you can find the description and + contents of the separator variables in \autoref{tab:\LabelBase.fromSeparator}} \begin{desctabular}[1.8em] \ventry{fromemail}{\DescRef{\LabelBase.cmd.usekomavar*}\PParameter{emailseparator}% @@ -1346,13 +1377,12 @@ first time after \Macro{begin}\PParameter{document}. \end{table} \begin{table}[tp] -% \centering - \KOMAoptions{captions=topbeside}% - \setcapindent{0pt}% -% \caption - \begin{captionbeside}{Predefined description and content of the separators - at the letterhead without option \Option{symbolicnames}} - [l] + \centering +% \KOMAoptions{captions=topbeside}% +% \setcapindent{0pt}% + \caption{Default descriptions and contents of the letterhead + separators without the \Option{symbolicnames} option} +% [l] \begin{tabular}[t]{lll} \toprule variable name & description & content \\ @@ -1364,56 +1394,58 @@ first time after \Macro{begin}\PParameter{document}. \Variable{urlseparator} & \DescRef{scrlttr2-experts.cmd.wwwname} & \texttt{:\~} \\ \bottomrule \end{tabular} - \end{captionbeside} +% \end{captionbeside} \label{tab:\LabelBase.fromSeparator} \end{table} \begin{Example} - Mr Public from the example letter has telephone and e-mail. He wants to show - this also in the letterhead. Furthermore the separation rule should be - placed below the letterhead. So he uses the corresponding options and - defines the content of the needed variables:% + Mr Public from our sample letter has a telephone and an e-mail address. He + also wants to show these in the letterhead. At the same time, the separation + rule should now be placed after the letterhead. So he uses the appropriate + options and also sets the required variables:% \lstinputcode[xleftmargin=1em]{letter-12.tex}% - Nevertheless the result at the left side of - \autoref{fig:\LabelBase.letter-12-13} is not disillusioning: the options are - ignored. That's the case because the additional variables and options will - be used at the extended letterhead only. So option \DescRef{\LabelBase.option.fromalign} has to - be used, like done at the right letter of + The results on the left side of \autoref{fig:\LabelBase.letter-12-13}, + however, are confounding: the options are ignored. That's because the + additional variables and options are only used in the extended letterhead. + So the \DescRef{\LabelBase.option.fromalign} option must be used, as it is + in the right side of \autoref{fig:\LabelBase.letter-12-13}. \begin{figure} \centering \frame{\includegraphics[width=.4\textwidth]{letter-12}}\quad \frame{\includegraphics[width=.4\textwidth]{letter-13}} - \caption[{Example: letter with extended sender, separation rule, addressee, - opening, text, closing, signature, postscript, distribution list, - enclosure, and puncher hole mark; standard vs. extended letterhead}] - {result of a small letter with sender, separation rule, addressee, - opening, text, closing, signature, postscript, distribution list, - enclosure and puncher hole mark (the date is a default of DIN-letters): - at left one the standard letterhead using - \OptionValueRef{\LabelBase}{fromalign}{false}, at right one the extended letterhead - using \OptionValueRef{\LabelBase}{fromalign}{center}} + \caption[{Example: letter with extra sender information, rule, + recipient, opening, text, closing, signature, postscript, distribution + list, enclosure, and hole-punch mark; standard vs. extended letterhead}] + {result of a short letter with sender, rule, recipient, opening, text, + closing, signature, postscript, distribution list, enclosure and + hole-punch mark (the date is set by default): the left one uses the + standard letterhead with + \OptionValueRef{\LabelBase}{fromalign}{false}; the right one uses the + extended letterhead with \OptionValueRef{\LabelBase}{fromalign}{center}} \label{fig:\LabelBase.letter-12-13} \end{figure} \lstinputcode[xleftmargin=1em]{letter-13.tex} - An arrangement of alternatives with left aligned using - \OptionValueRef{\LabelBase}{fromalign}{left} and right aligned sender - using \OptionValueRef{\LabelBase}{fromalign}{right} may be found in + You can compare two other alternatives with left-aligned sender information using + \OptionValueRef{\LabelBase}{fromalign}{left} and right-aligned sender information + using \OptionValueRef{\LabelBase}{fromalign}{right} in \autoref{fig:\LabelBase.letter-14-15}. \begin{figure} \centering \frame{\includegraphics[width=.4\textwidth]{letter-14}}\quad \frame{\includegraphics[width=.4\textwidth]{letter-15}} - \caption[{Example: letter with extended sender, separation rule, addressee, - opening, text, closing, signature, postscript, distribution list, - enclosure, and puncher hole mark; left vs. right aligned letterhead}] - {result of a small letter with sender, separation rule, addressee, - opening, text, closing, signature, postscript, distribution list, - enclosure and puncher hole mark (the date is a default of DIN-letters): - at left one left aligned letterhead using - \OptionValueRef{\LabelBase}{fromalign}{left}, at right one right aligned letterhead - using \OptionValueRef{\LabelBase}{fromalign}{right}} + \caption[{Example: letter with extra sender information, rule, + recipient, opening, text, closing, signature, postscript, distribution + list, enclosure, and hole-punch mark; left- vs. right-aligned + letterhead}] + {result of a short letter with extra sender information, rule, + recipient, opening, text, closing, signature, postscript, distribution + list, enclosure and hole-punch mark (the date is set by default): + the left one uses a left-aligned letterhead with + \OptionValueRef{\LabelBase}{fromalign}{left}; the right one uses a + right-aligned letterhead using + \OptionValueRef{\LabelBase}{fromalign}{right}} \label{fig:\LabelBase.letter-14-15} \end{figure} \end{Example} @@ -1427,37 +1459,38 @@ first time after \Macro{begin}\PParameter{document}. \end{Declaration} \BeginIndex{}{letterhead}% \BeginIndex{}{letter>head}% -With option \Option{fromlogo} you may configure whether or not to use a -logo\Index{Logo} at the letterhead. The option value may be any \PName{simple - switch} from \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch}. Default is \PValue{false}, that means no -logo. The logo itself is defined by the \PName{content} of variable -\Variable{fromlogo}. The \PName{description} of the logo is empty by default -and \KOMAScript{} does not use it anywhere at the predefined note papers (see -also \autoref{tab:\LabelBase.fromTerm}).% +You can use the \Option{fromlogo} to configure whether to put a +logo\Index{Logo} in the letterhead. You can use any of the default values from +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} for the +\PName{simple switch}. The default is \PValue{false}, which means no logo. The +logo itself is defined by the \PName{content} of the \Variable{fromlogo} +variable. The \PName{description} of the logo is empty by default and +\KOMAScript{} does not use it in the default letterhead pages (see also +\autoref{tab:\LabelBase.fromTerm}).% \begin{Example} - Mr Public likes to use a letterhead with logo. He generated a graphics file - with the logo and would like to include this using - \Macro{includegraphics}. Therefor he uses the additional package - \Package{graphics}\IndexPackage{graphics} (see \cite{package:graphics}).% + Mr Public finds it particularly stylish when he provides his letterhead with + a logo. He has saved his logo as a graphics file, which he would like to + load using \Macro{includegraphics}. To do this, he uses the loads the + \Package{graphics}\IndexPackage{graphics} package (see + \cite{package:graphics}).% \lstinputcode[xleftmargin=1em]{letter-16}% - The result may be seen at the left top position of - \autoref{fig:\LabelBase.letter-16-18}. The additional letter prints at this - figure shows the result with right aligned or centered sender. + You can see the result in the top left of + \autoref{fig:\LabelBase.letter-16-18}. The other two images in this figure + show the results with right-aligned and centred sender information. \begin{figure} \setcapindent{0pt}% {\hfill \frame{\includegraphics[width=.4\textwidth]{letter-16}}\quad \frame{\includegraphics[width=.4\textwidth]{letter-17}}\par\bigskip} - \begin{captionbeside}[{Example: letter with extended sender, logo, - separation rule, addressee, opening, text, closing, signature, - postscript, distribution list, enclosure, and puncher hole mark; left - vs. right aligned vs. centered sender}] - {result of a small letter with extended sender, logo, separation rule, - addressee, opening, text, closing, signature, postscript, distribution - list, enclosure and puncher hole mark (the date is a default of - DIN-letters): at top left one left aligned sender using, at right - beneath one with centered sender, and at right one right aligned + \begin{captionbeside}[{Example: letter with extra sender information, + logo, rule, recipient, opening, text, closing, signature, postscript, + distribution list, enclosure, and hole-punch mark; left-aligned vs. + right-aligned vs. centred sender information}] + {result of a short letter with extra sender information, logo, rule, + recipient, opening, text, closing, signature, postscript, distribution + list, enclosure and hole-punch mark (the date is set by default): + at top left the sender is left-aligned, at top right the sender is + centred, and at bottom right the sender is right-aligned sender}[l] \frame{\includegraphics[width=.4\textwidth]{letter-18}}\quad \end{captionbeside} @@ -1471,35 +1504,26 @@ also \autoref{tab:\LabelBase.fromTerm}).% \begin{Declaration} \Variable{firsthead}% \end{Declaration} -\BeginIndex{}{letterhead}% -\BeginIndex{}{letter>head}% -For many cases, \Class{scrlttr2} with its options and variables offers -enough possibilities to create a letterhead. In very rare situations -one may wish to have more freedom in terms of layout. In those -situations one will have to do without predefined letterheads, which -could have been chosen via options. Instead, one needs to create one's -own letterhead from scratch. To do so, one has to define the preferred -construction as content of variable \Variable{firsthead}. Within -\Macro{firsthead}, and with the help of the \Macro{parbox} command -(see \cite{latex:usrguide}), one can set several boxes side by side, -or one underneath the other. An advanced user will thus be able to -create a letterhead on his own. Of course the construct may -and should use other variables with the help of +In many cases, the capabilities that \Class{scrlttr2} offers with the +foregoing options and variables will be sufficient to design a letterhead. In +some cases, however, you may want even more flexibility. In those situations, +you will have to do without the possibilities offered by the predefined +letterhead, which you can select via the options described above. Instead, you +must create your own letterhead from scratch. To do so, you must specify the +desired structure as the \PName{contents} of the \Variable{firsthead} +variable. For example, you can set several boxes side by side or one beneath +the other using the \Macro{parbox} command (see \cite{latex:usrguide}). +Experienced users should thus be able to create their own a letterheads. Of +course you can and should use other variables with \DescRef{\LabelBase.cmd.usekomavar}. \KOMAScript{} does not use the -\PName{description} of variable \Variable{firsthead}. -\iffree{}{A detailed example for the definition of a letterhead will be shown - in \autoref{cha:modernletters}.} - -The\textnote{Attention!} command -\Macro{firsthead}\IndexCmd[indexmain]{firsthead} exists only for reason of -compatibility to former \Class{scrlttr2} versions. However it is deprecated -and you should not use it anymore.% -% +\PName{description} of variable \Variable{firsthead}. \iffree{}{You can find + a detailed example of a letterhead definition in + \autoref{cha:modernletters}.}% \EndIndexGroup \begin{Declaration} - \OptionVName{addrfield}{mode}% + \OptionVName{addrfield}{format}% \OptionVName{backaddress}{value}% \OptionVName{priority}{priority}% \Variable{toname}% @@ -1514,110 +1538,112 @@ and you should not use it anymore.% \Variable{PPdatamatrix}% \Variable{addresseeimage}% \end{Declaration}% -\BeginIndex{}{addressee}% +\BeginIndex{}{address}% +The \Option{addrfield} option determines whether or not to print an address +field. The default\textnote{default} is to include an address field. The +option recognizes the formats described in +\autoref{tab:\LabelBase.addrfield}\ChangedAt{v3.03}{\Class{scrlttr2}}. With +the values \PValue{true}, +\PValue{topaligned}\ChangedAt{v3.17}{\Class{scrlttr2}\and +\Package{scrletter}}, \PValue{PP}, and \PValue{backgroundimage}, the name and +address of the recipient are determined by the mandatory argument of the +\DescRef{\LabelBase.env.letter} environment (see +\autoref{sec:\LabelBase.document}, \DescPageRef{\LabelBase.env.letter}). This +information is also copied into the variables \Variable{toname} and +\Variable{toaddress}. + \BeginIndexGroup \BeginIndex{FontElement}{addressee}\LabelFontElement{addressee}% \BeginIndex{FontElement}{toname}\LabelFontElement{toname}% \BeginIndex{FontElement}{toaddress}\LabelFontElement{toaddress}% -Option \Option{addrfield} defines whether or not to set an address -field. Default is to use an address field. This option can take the mode -values from -\autoref{tab:\LabelBase.addrfield}\ChangedAt{v3.03}{\Class{scrlttr2}}. Default -is \PValue{true}. With values \PValue{true}, -\PValue{topaligned}\ChangedAt{v3.17}{\Class{scrlttr2}\and - \Package{scrletter}}, \PValue{PP}, and -\PValue{backgroundimage} name and address of the addressee will be defined by -the mandatory argument of the \DescRef{\LabelBase.env.letter} environment (see -\autoref{sec:\LabelBase.document}, -\DescPageRef{\LabelBase.env.letter}). These elements will additionally be -copied into the variables \Variable{toname} and \Variable{toaddress}. The -predefined font styles may be changed\ChangedAt{v2.97c}{\Class{scrlttr2}} by -execution of command \DescRef{\LabelBase.cmd.setkomafont} or \DescRef{\LabelBase.cmd.addtokomafont} (siehe +You can change the default font styles\ChangedAt{v2.97c}{\Class{scrlttr2}} +with the \DescRef{\LabelBase.cmd.setkomafont} or +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}). Thereby three elements -exist. First of all element -\FontElement{addressee}\important{\FontElement{addressee}}, that is -responsible for the addressee overall. The additional elements -\FontElement{toname}\important{\FontElement{toname}} and +\DescPageRef{\LabelBase.cmd.setkomafont}). There are three elements. First, +the \FontElement{addressee}\important{\FontElement{addressee}} element is +responsible for the overall style of the recipient's name and address. The +elements \FontElement{toname}\important{\FontElement{toname}} and \FontElement{toaddress}\important{\FontElement{toaddress}} are responsible -only either for the name or the address of the addressee. They may be used to -define modifications from the \FontElement{addressee} configuration.% +only for the name and the address of the recipient, respectively. You can use +\FontElement{toname} and \FontElement{toaddress} to define modifications from +the basic \FontElement{addressee} configuration.% \EndIndexGroup - +% \begin{table} - \caption[{available values for option \Option{addrfield} using - \Class{scrlttr2}}]{available values for option \Option{addrfield} to - change the addressee mode of \Class{scrlttr2}}% + \caption[{available values for the \Option{addrfield} option with + \Class{scrlttr2}}]{available values for the \Option{addrfield} option to + change the recipient format of \Class{scrlttr2}}% \label{tab:\LabelBase.addrfield}% \begin{desctabular} \entry{\PValue{backgroundimage}, \PValue{PPbackgroundimage}, \PValue{PPBackgroundImage}, \PValue{PPBackGroundImage}, \PValue{ppbackgroundimage}, \PValue{ppBackgroundImage}, \PValue{ppBackGroundImage}}{% - Prints an address field with Port-Pay\'e head, in variable - \Variable{addresseimage} defined background graphics, but without return - address or mode of dispatch.}% + Prints an address with a background image stored in the + \Variable{addresseimage} variable as the postpaid postmark, but without + a return address or delivery type.}% \entry{\PValue{false}, \PValue{off}, \PValue{no}}{% - Omits the address field.}% + Does not print an address.}% \entry{\PValue{image}, \PValue{Image}, \PValue{PPimage}, \PValue{PPImage}, \PValue{ppimage}, \PValue{ppImage}}{% - Prints variable \Variable{addresseeimage} as addressee with Port-Pay\'e, - but ignores addressee information and definitions for return address, - mode of dispatch or priority.}% + Prints an image stored in the \Variable{addresseeimage} variable as an + address with a postpaid postmark. Recipient information, return address, + and delivery type or priority are ignored.}% \entry{\PValue{PP}, \PValue{pp}, \PValue{PPexplicite}, \PValue{PPExplicite}, \PValue{ppexplicite}, \PValue{ppExplicite}}{% - Prints an address field with Port-Pay\'e head, defined by the variables - \Variable{fromzipcode}, \Variable{place}, and \Variable{PPcode} and when - indicated with priority and data array defined by - \Variable{PPdatamatrix} but without return address and mode of - dispatch.}% + Prints an address with a postage print impression (pospaid) header + filled in with the variables \Variable{fromzipcode}, \Variable{place}, + and \Variable{PPcode}, and when applicable with a priority and a data + array defined by \Variable{PPdatamatrix}, but without a return address + or delivery type.}% \entry{\PValue{topaligned}, \PValue{alignedtop}% \ChangedAt{v3.17}{\Class{scrlttr2}\and \Package{scrletter}}}{% - Prints an address field including a return address and a mode of - dispatch or priority without centring the address vertically in the - available space.}% + Prints an address including a return address and a delivery type + or priority. The address is not centred vertically beneath the delivery + type.}% \entry{\PValue{true}, \PValue{on}, \PValue{yes}}{% - Prints an address field including a return address and a mode of - dispatch or priority.}% + Prints an address field including a return address and delivery type + or priority.}% \end{desctabular} \end{table}% -With the default \OptionValue{addrfield}{true} an additional return address -will be printed. Option \Option{backaddress} defines whether a return address -for window envelopes will be set. This -option\important{\OptionValue{backaddress}{false}} can take the standard -values for simple switches, as listed in \autoref{tab:truefalseswitch}, +The default \OptionValue{addrfield}{true} also prints an underlined return +address in the address field. The \Option{backaddress} option defines if and +in what form a return address will be printed for window envelopes. On the one +hand, this option\important{\OptionValue{backaddress}{false}} accepts the +standard values for simple switches listed in \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. These values do not change style of the -return address. On the other hand, -additionally\ChangedAt{v2.96}{\Class{scrlttr2}} to switching on the return -address, the style of the return address may be selected. Option value -\PValue{underlined} selects an underlined return address. In opposite to -this value \PValue{plain}\important{\OptionValue{backaddress}{plain}} selects -a style without underline. Default is \PValue{underlined} and therefore -printing an underlined return address. - -\BeginIndex{FontElement}{backaddress}\LabelFontElement{backaddress}% -The return address itself is defined by the \PName{content} of variable -\Variable{backaddress}. Default is a combination of variable \Variable{toname} -and \Variable{toaddress} with redefinition of the double backslash to set the -\PName{content} of variable \Variable{backaddressseparator}. The predefined -separator \PName{content} is a comma followed by a non-breakable white -space. The \PName{description} of variable \Variable{backaddress} is not used -by \KOMAScript. The font style of the return address is configurable via -element -\FontElement{backaddress}\important{\FontElement{backaddress}}. Default for -this is \Macro{sffamily} (see -\autoref{tab:\LabelBase.AddresseeElements}). Before execution of the element's -font style \KOMAScript{} switches to \Macro{scriptsize}.% -\EndIndex{FontElement}{backaddress}% - -By default, \OptionValue{addrfield}{true}, the address will be vertically -centred in the available space below the mode of dispatch or -priority. In\ChangedAt{v3.17}{\Class{scrlttr2}\and \Package{scrletter}} -opposite to this, \OptionValue{addrfield}{topaligned}% +return address. On the other hand, when\ChangedAt{v2.96}{\Class{scrlttr2}} the +return address is enabled, you can select its format at the same time. For +example, the \PValue{underlined} option value enables an underlined return +address, while \PValue{plain}\important{\OptionValue{backaddress}{plain}} +selects a style without underlining. The default is \PValue{underlined} and +thus prints an underlined return address. + +The return address itself is defined by the \PName{content} of the +\Variable{backaddress} variable. The default is the name specified in +\DescRef{\LabelBase.variable.fromname} and the address specified in +\DescRef{\LabelBase.variable.fromaddress}. The double backslash is also +replaced with the \PName{content} of the \Variable{backaddressseparator} +variable. The default separator is a comma followed by a non-breaking space. +\KOMAScript{} does not use the \PName{description} of the +\Variable{backaddress} variable. +\BeginIndexGroup\BeginIndex{FontElement}{backaddress}% +\LabelFontElement{backaddress}% +You can configure the font style of the return address via the +\FontElement{backaddress}\important{\FontElement{backaddress}} element. The +default is \Macro{sffamily} (see \autoref{tab:\LabelBase.AddresseeElements}). +Before applying the element's font style \KOMAScript{} switches to +\Macro{scriptsize}.% +\EndIndexGroup + +The default \OptionValue{addrfield}{true}, centres the address vertically +within the space available for the address. +In\ChangedAt{v3.17}{\Class{scrlttr2}\and \Package{scrletter}} contrast, +\OptionValue{addrfield}{topaligned}% \important{\OptionValue{addrfield}{topaligned}} will not centre the address -but follow it aligned top at the available space. This is the only difference -to \OptionValue{addrfield}{true}.% +but place it flush with the top of the available space.% \begin{table} % \centering @@ -1625,7 +1651,7 @@ to \OptionValue{addrfield}{true}.% \setcapindent{0pt}% % \caption \begin{captionbeside}{% - Predefined font style for the elements of the address field.% + Default font styles for the elements of the address field.% }% [l] \begin{tabular}[t]{ll} @@ -1663,52 +1689,54 @@ to \OptionValue{addrfield}{true}.% \label{tab:\LabelBase.AddresseeElements}% \end{table} -\BeginIndex{FontElement}{specialmail}\LabelFontElement{specialmail}% -At the default \OptionValue{addrfield}{true} an optional dispatch -type\Index{mode of dispatch}\Index{dispatch type} can be output within the -address field between the return address and the addressee address, This will -be done only if variable \Variable{specialmail} is not empty and +\BeginIndexGroup +\BeginIndex{FontElement}{specialmail}\LabelFontElement{specialmail} +With the default \OptionValue{addrfield}{true} setting, you can output an +optional delivery type\Index{delivery type} between the return address and the +recipient address. This will be output only if the \Variable{specialmail} +variable has non-empty content and \OptionValue{priority}{manual}\ChangedAt{v3.03}{\Class{scrlttr2}} has been -selected, which is also the default. Class \Class{scrlttr2} itself does not use -the \PName{description} of variable \Variable{specialmail}. The alignment is -defined by the pseudo-lengths PLength{specialmailindent} and -\PLength{specialmailrightindent} (siehe -\DescPageRef{scrlttr2-experts.plength.specialmailindent}). The predefined -font style of element\ChangedAt{v2.97c}{\Class{scrlttr2}} -\FontElement{specialmail}\important{\FontElement{specialmail}}, that has been -listed in \autoref{tab:\LabelBase.AddresseeElements}, may be changed using -commands \DescRef{\LabelBase.cmd.setkomafont} and \DescRef{\LabelBase.cmd.addtokomafont} (see +selected, which is the default. The \Class{scrlttr2} class itself does not use +the \PName{description} of the \Variable{specialmail} variable. The alignment +is defined by the \PLength{specialmailindent} and +\PLength{specialmailrightindent} pseudo-lengths (see +\DescPageRef{scrlttr2-experts.plength.specialmailindent}). You can change the +default font style of the\ChangedAt{v2.97c}{\Class{scrlttr2}} +\FontElement{specialmail}\important{\FontElement{specialmail}} element, which +is listed in \autoref{tab:\LabelBase.AddresseeElements}, with the +\DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}).% -\EndIndex{FontElement}{specialmail}% +\EndIndexGroup \BeginIndexGroup \BeginIndex{FontElement}{priority}\LabelFontElement{priority}% \BeginIndex{FontElement}{prioritykey}\LabelFontElement{prioritykey}% -\BeginIndex{FontElement}{PPlogo}\LabelFontElement{PPlogo}% -On\ChangedAt{v3.03}{\Class{scrlttr2}}\important[i]{\OptionValue{priority}{A}\\ - \OptionValue{priority}{B}} the other hand, using an international priority +However\ChangedAt{v3.03}{\Class{scrlttr2}}\important{\normalcolor + \OptionValue{priority}{A}\\ + \normalcolor\OptionValue{priority}{B}}, selecting an international priority with \OptionValue{priority}{A} or \OptionValue{priority}{B} (see -\autoref{tab:\LabelBase.priority}) together with \OptionValue{addrfield}{true} -will print the priority as mode of dispatch. Using it together with -\OptionValue{addrfield}{PP}\important{\OptionValue{addrfield}{PP}} will print -the priority at the corresponding position in the Port-Pay\'e head. Thereby -the element \FontElement{priority} defines the basic font style and -\FontElement{prioritykey} the modification of the basic font style for the -priority key, ``A'' or ``B''. The Port-Pay\'e logo ``P.~P.'' uses the font -style of element \FontElement{PPlogo}. The default font styles are listed in -\autoref{tab:\LabelBase.AddresseeElements} and may be changed using commands -\DescRef{\LabelBase.cmd.setkomafont} und -\DescRef{\LabelBase.cmd.addtokomafont} (siehe +\autoref{tab:\LabelBase.priority}) together with +\OptionValue{addrfield}{true}, prints the priority as the delivery type. Using +it together with +\OptionValue{addrfield}{PP}\important{\OptionValue{addrfield}{PP}} prints the +priority at the corresponding position in the postpaid postmark (also known as +the postage print impression or \emph{port pay\'e}). The \FontElement{priority} +element defines the basic font style, and \FontElement{prioritykey} defines +the modification of the basic font style for the priority keys ``A'' or ``B''. +You can find the default font styles listed in +\autoref{tab:\LabelBase.AddresseeElements} and can change then using the +\DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}).% \EndIndexGroup - \begin{table} - \caption[{available values for option \Option{priority} in - \Class{scrlttr2}}]{available values for option \Option{priority} to select - the international priority at the address field of\Class{scrlttr2}} + \caption[{available values for the \Option{priority} option in + \Class{scrlttr2}}]{available values for the \Option{priority} option to + select the international priority in the address field of\Class{scrlttr2}} \label{tab:\LabelBase.priority} \begin{desctabular} \entry{\PValue{false}, \PValue{off}, \PValue{no}, \PValue{manual}}{% @@ -1717,99 +1745,106 @@ style of element \FontElement{PPlogo}. The default font styles are listed in \PValue{ECONOMY}, \PValue{B-ECONOMY}, \PValue{B-Economy}, \PValue{b-economy}}{% Use international priority B-Economy. With - \OptionValue{addrfield}{true} this will be printed instead of the mode - of dispatch.}% + \OptionValue{addrfield}{true}, this is printed instead of the delivery + type.}% \entry{\PValue{A}, \PValue{a}, \PValue{priority}, \PValue{Priority}, \PValue{PRIORITY}, \PValue{A-PRIORITY}, \PValue{A-Priority}, \PValue{a-priority}}{% Use international priority A-Priority. With - \OptionValue{addrfield}{true} this will be printed instead of the mode - of dispatch.}% + \OptionValue{addrfield}{true}, this is printed instead of the delivery + type.}% \end{desctabular} \end{table} With\ChangedAt{v3.03}{\Class{scrlttr2}}\important{\OptionValue{addrfield}{PP}} -\OptionValue{addrfield}{PP} also the zip-code of -variable \Variable{fromzipcode} and the place from \PName{content} of variable -\Variable{place} will be set in the Port-Pay\'e head. Thereby the -\PName{content} of variable \Variable{fromzipcode} will be preceded by the -\PName{description} of variable \Variable{fromzipcode} and the \PName{content} -of variable \Variable{zipcodeseparator}. The predefined \PName{description} -depends on the used \File{lco}-file (see \autoref{sec:\LabelBase.lcoFile} from -\autopageref{sec:\LabelBase.lcoFile} onward). On the other hand the default of -the \PName{content} of variable \Variable{zipcodeseparator} is a small -distance followed by an endash followed by one more small distance +\OptionValue{addrfield}{PP}, the postal code in the \Variable{fromzipcode} +variable and the location from the \Variable{place} pariable will be output in +the postpaid postmark. The postal code (that is, the \PName{content} of +\Variable{fromzipcode}) is preceded by the \PName{description} of the +\Variable{fromzipcode} variable and the \PName{content} of +\Variable{zipcodeseparator}. The default for the \PName{description} depends +on the \File{lco} file used (see \autoref{sec:\LabelBase.lcoFile} starting on +\autopageref{sec:\LabelBase.lcoFile}). On the other hand, the default +\PName{content} of the \Variable{zipcodeseparator} variable is a thin space +followed by an en rule followed by another thin space (\Macro{,}\texttt{-{}-}\Macro{,}). -Beyond\ChangedAt{v3.03}{\Class{scrlttr2}} that, with -\OptionValue{addrfield}{PP}\important{\OptionValue{addrfield}{PP}} and -sender's identification code will be used at the Port-Pay\'e head. This is the -\PName{content} of variable \Variable{PPcode}. Right beside the address of the -addressee an additional data array may be printed. The \PName{content} of -variable \Variable{PPdatamatrix} will be used for this. - -\BeginIndex{FontElement}{PPdata}\LabelFontElement{PPdata}% -Zip-code\ChangedAt{v3.03}{\Class{scrlttr2}}, place and code will be printed -with default font size 8\Unit{pt}. Thereby the font style of element -\FontElement{PPdata}\important{\FontElement{PPdata}} will be used. The default -of the element is listed in \autoref{tab:\LabelBase.AddresseeElements} and may -be changed using commands \DescRef{\LabelBase.cmd.setkomafont} and \DescRef{\LabelBase.cmd.addtokomafont} (see +With\ChangedAt{v3.03}{\Class{scrlttr2}} +\OptionValue{addrfield}{PP}\important{\OptionValue{addrfield}{PP}}, a code is +placed in the postpaid postmark that uniquely identifies the sender. This is +stored in the \Variable{PPcode} variable. You can also print an additional +data array to the right of the address, which is stored in the +\Variable{PPdatamatrix} variable. + +\BeginIndexGroup +\BeginIndex{FontElement}{PPdata}\LabelFontElement{PPdata} +The ZIP code\ChangedAt{v3.03}{\Class{scrlttr2}} (postal code), place, and +sender code will be printed by default in an 8\Unit{pt} font. The the font +style of the \FontElement{PPdata}\important{\FontElement{PPdata}} is used to +do so. The default is listed in \autoref{tab:\LabelBase.AddresseeElements} and +can be changed with the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}).% -\EndIndex{FontElement}{PPdata}% +\EndIndexGroup -With\important[i]{\begin{tabular}[t]{@{}l@{}} - \KOption{addrfield}\\\quad\PValue{backgroundimage}\end{tabular}\strut\\ - \strut\OptionValue{addrfield}{image}} options +\BeginIndexGroup +\BeginIndex{FontElement}{PPlogo}\LabelFontElement{PPlogo} For the postpaid +logo ``P.P.'', however, the font style of the +\FontElement{PPlogo}\important{\FontElement{PPlogo}} element is used. Its +default can also be found in \autoref{tab:\LabelBase.AddresseeElements}.% +\EndIndexGroup + +With\important{\OptionValue{addrfield}{backgroundimage}\\ + \OptionValue{addrfield}{image}} the two settings \OptionValue{addrfield}{backgroundimage}\ChangedAt{v3.03}{\Class{scrlttr2}} -or \OptionValue{addrfield}{image} a picture will be print inside the address -field. The \PName{content} of variable \Variable{addresseeimage} will be used -for this. \KOMAScript{} does not use the \PName{description} of that -variable. Nothing else but the picture will be printed with option -\OptionValue{addrfield}{image}. But with option -\OptionValue{addrfield}{backgroundimage} the addressee's name and address from +and \OptionValue{addrfield}{image}, an image is print inside the address +window. This image is stored in the \PName{content} of variable +\Variable{addresseeimage}. \KOMAScript{} does not use the \PName{description} +of this variable. Although only the image is printed with the +\OptionValue{addrfield}{image} option, the recipient's name and address from the mandatory argument of the \DescRef{\LabelBase.env.letter} environment will -be output. +be printed with the \OptionValue{addrfield}{backgroundimage} option. -The alignment of the Port-Pay\'e head as long as the alignment of the -Port-Pay\'e address is defined by pseudo-length \PLength{toaddrindent} (see +The position of the postpaid postmark and that of the +postpaid address is defined by the \PLength{toaddrindent} pseudo-length (see \DescPageRef{scrlttr2-experts.plength.toaddrindent}) as well as -\PLength{PPheadwidth} and \PLength{PPheadheight} (siehe -\DescPageRef{scrlttr2-experts.plength.PPheadheight}). The alignment of -the data array is defined by pseudo-length \PLength{PPdatamatrixvskip} +\PLength{PPheadwidth} and \PLength{PPheadheight} (see +\DescPageRef{scrlttr2-experts.plength.PPheadheight}). The position of +the data array is defined by the \PLength{PPdatamatrixvskip} pseudo-length (see \DescPageRef{scrlttr2-experts.plength.PPdatamatrixvskip}). -Please note\textnote{Attention!} that \KOMAScript{} itself cannot set any -external graphics or pictures. So, if you want to put external picture files +Note\textnote{Attention!} that \KOMAScript{} cannot print any external +graphics or pictures by itself. So if you want to put external picture files into variables like \Variable{addresseeimage} or \Variable{PPdatamatrix}, you -have to use an additional graphics package like +must load an additional graphics package like \Package{graphics}\IndexPackage{graphics} or -\Package{graphicx}\IndexPackage{graphicx} to use, i.\,e., the command -\Macro{includegraphics} at the \PName{content} of the variables.% +\Package{graphicx}\IndexPackage{graphicx} and use, for instance, the +\Macro{includegraphics} command in the \PName{content} of the variables.% % \EndIndexGroup \begin{Declaration} - \OptionVName{locfield}{selection} + \OptionVName{locfield}{setting} \end{Declaration} -\BeginIndex{}{sender>additional information}% -\Class{scrlttr2} places a field with additional sender attributes next to the -address field. This can be used, for example, for bank account -or similar additional information. -Depending\important[i]{\OptionValueRef{\LabelBase}{fromalign}{center}\\ - \begin{tabular}[t]{@{}l@{}} - \KOption{fromalign}\\\quad\PValue{locationleft}\end{tabular}\\ - \begin{tabular}[t]{@{}l@{}} - \KOption{fromalign}\\\quad\PValue{locationright}\end{tabular}} on the +\BeginIndex{}{extra sender information}% +In addition to the address field, \Class{scrlttr2} can print a field with +extra sender attributes next to the address field. Its content can be +anything you want, for example a location, a bank-account number, or other +information. Depending\important{% + \OptionValueRef{\LabelBase}{fromalign}{locationleft}\\ + \OptionValueRef{\LabelBase}{fromalign}{center}\\ + \OptionValueRef{\LabelBase}{fromalign}{locationright}} on the \DescRef{\LabelBase.option.fromalign} option, it will also be used for the -sender logo. The width of this field may be defined within an \File{lco} file -(see \autoref{sec:\LabelBase.lcoFile}). If the width is set to 0 in that file, -then the \Option{locfield} option can toggle between two presets for -the field width. See the explanation on the \PLength{locwidth} pseudo -length in \autoref{sec:scrlttr2-experts.locationField}, -\DescPageRef{scrlttr2-experts.plength.locwidth}. Possible values for this -option are shown in \autoref{tab:\LabelBase.locfield}. Default is +sender's logo. The width of this field can be specified in an \File{lco} file +(see \autoref{sec:\LabelBase.lcoFile}). If the width is set to zero there, the +\Option{locfield} option can toggle between two defaults for the field width. +This is the case for most of the \File{lco} files that come with +\KOMAScript{}. See also the explanation on the \PLength{locwidth} +pseudo-length in \autoref{sec:scrlttr2-experts.locationField}, +\DescPageRef{scrlttr2-experts.plength.locwidth}. Available values for this +option are shown in \autoref{tab:\LabelBase.locfield}. The default is \PValue{narrow}.% % \begin{table} @@ -1818,16 +1853,16 @@ option are shown in \autoref{tab:\LabelBase.locfield}. Default is \setcapindent{0pt}% % \caption \begin{captionbeside} - [{Possible values of option \Option{locfield} with - \Class{scrlttr2}}]{Possible values of option \Option{locfield} for - setting the width of the field with additional sender attributes with + [{Available values of the \Option{locfield} option with + \Class{scrlttr2}}]{Available values of the \Option{locfield} option to + set the width of the field for extra sender information with \Class{scrlttr2}% \label{tab:\LabelBase.locfield}}% [l] \begin{minipage}[t]{.45\linewidth} \begin{desctabular}[t] - \pventry{narrow}{narrow sender supplement field}% - \pventry{wide}{wide sender supplement field}% + \pventry{narrow}{narrow extra sender information field}% + \pventry{wide}{wide extra sender information field}% \end{desctabular} \end{minipage} \end{captionbeside} @@ -1836,36 +1871,34 @@ option are shown in \autoref{tab:\LabelBase.locfield}. Default is \begin{Declaration} \Variable{location}% \end{Declaration} -\BeginIndex{}{sender>additional information}% -The contents of the sender's extension field is determined by the -variable \Variable{location}. To set this variable's \PName{content}, it is -permitted to use formatting commands like \Macro{raggedright}. \KOMAScript{} -does not use the \PName{description} of the variable. +The contents of the extra sender information field, unless it contains +the logo or the basic sender information itself, are specified by the +\Variable{location} variable. You can use formatting commands like +\Macro{raggedright} within this variable's \PName{content}. \KOMAScript{} does +not use the \PName{description} of this variable. \begin{Example} - Mr Public likes to show some additional information about his - membership. Therefor he uses the \Variable{location} variable:% + Mr Public would like to provide some additional information about his + membership. Therefore he uses the \Variable{location} variable:% \lstinputcode[xleftmargin=1em]{letter-19.tex}% - This will define the field beside the addressee's address like shown in - \autoref{fig:\LabelBase.letter-19}. + This will place the corresponding field beside the recipient's address, as + shown in \autoref{fig:\LabelBase.letter-19}. \begin{figure} \setcapindent{0pt}% \begin{captionbeside}[{Example: letter with extended sender, logo, - addressee, additional sender information, opening, - text, closing, signature, postscript, distribution list, enclosure, - and puncher hole mark}] - {result of a small letter with extended sender, logo, - addressee, additional sender information, opening, text, closing, - signature, postscript, distribution list, enclosure and puncher hole - mark (the date is a default of DIN-letters)}[l] + recipient, extra sender information, opening, text, closing, + signature, postscript, distribution list, enclosure, and hole-punch + mark}] + {result of a short letter with extended sender, logo, recipient, + extra sender information, opening, text, closing, signature, + postscript, distribution list, enclosure, and hole-punch mark (the + date is set by default)}[l] \frame{\includegraphics[width=.4\textwidth]{letter-19}} \end{captionbeside} \label{fig:\LabelBase.letter-19} \end{figure} \end{Example} -% \EndIndexGroup -% \EndIndexGroup @@ -1874,30 +1907,30 @@ does not use the \PName{description} of the variable. \end{Declaration} This option toggles between the standard, language-dependent date\Index{date}\Index{reference line} presentation, and a short, numerical -one. {\KOMAScript} does not provide the standard presentation. It should be -defined by packages such as \Package{ngerman}\IndexPackage{ngerman}, +one. \KOMAScript{} does not provide the standard date format. It should be +defined by a package such as \Package{ngerman}\IndexPackage{ngerman}, \Package{babel}\IndexPackage{babel}, or \Package{isodate}\IndexPackage{isodate}. The\important{\OptionValue{numericaldate}{true}} short, numerical -presentation, on the other hand, is produced by \Class{scrlttr2} itself. This -option can take the standard values for simple switches, as listed in -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. Default is -\PValue{false}, which results in standard date presentation. +representation, however, is produced by \Class{scrlttr2} itself. The option +recognizes the standard values for simple switches as listed in +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. The default +is \PValue{false}, which results in standard date format. \begin{Declaration} \Variable{date}% \end{Declaration} -The date in the selected presentation will become the \PName{content} of -variable \Variable{date}. The selection of option -\DescRef{\LabelBase.option.numericaldate} does not influence the date any -longer, if the \PName{content} of this variable will be changed by the -user. Normally the date will be part of the reference line. If all other -elements of the reference line will be empty and therefore unused a date line -instead of a reference line will be printed. See the description of variable +The date in the selected format is stored as \PName{content} of the +\Variable{date} variable. Setting the +\DescRef{\LabelBase.option.numericaldate} option has no effect if this +variable is overridden. The date is usually output as part of the reference +line. If all other elements of the reference line are empty, a date line +consisting of the location and the date is printed instead. However in this +case, the settings of the \DescRef{\LabelBase.option.refline} option described +below also affect the date line. See the description of variable \DescRef{\LabelBase.variable.place} on \DescPageRef{\LabelBase.variable.placeseparator} for more information about -the date line. You should note, that you can change the automatic printing of -the date using option \DescRef{\LabelBase.option.refline}, that will be described next. +the location. % \EndIndexGroup \EndIndexGroup @@ -1907,37 +1940,39 @@ the date using option \DescRef{\LabelBase.option.refline}, that will be describe \OptionVName{refline}{selection} \end{Declaration} \BeginIndex{}{reference line}% -\index{business line|see{reference line}}% | -Especially in business letters a line with information like identification -code\Index{identification>code}, direct dial, customer's number, invoice's -number, or references to previous letters may be found usually. This line will -be named \emph{reference line}\textnote{reference line} in this manual. - -With the \Class{scrlttr2} class, the header, footer, address, and sender -attributes may extend beyond the normal type area to the left and to the -right. Option \OptionValue{refline}{wide} defines that this should also apply to -the reference fields line. Normally, the reference fields line contains at -least the date, but it can hold additional data. Possible values for this -option are shown in \autoref{tab:\LabelBase.refline}. Default is \PValue{narrow} -and \PValue{dateright}\ChangedAt{v3.09}{\Class{scrlttr2}}.% +\index{business line|see{reference line}}% +Business letters in particular often contain an area with information such as +an identification code\Index{identification code}, phone +extension\Index{phone>extension}, customer number\Index{customer number}, +invoice number\Index{invoice number}, or references to previous letters. This +guide calls this area the \emph{reference-field line}\textnote{reference-field + line}, or simply the \emph{reference line}. + +With \Class{scrlttr2} and \Package{scrletter}, the header, footer, address, +and extra sender information can extend left and right beyond the normal +type area. The +\OptionValue{refline}{wide}\important{\OptionValue{refline}{wide}} option +specifies that this should also apply to the reference-field line. Normally, +the reference-field line contains at least the date, but it can hold +additional data. Available values for this option are shown in +\autoref{tab:\LabelBase.refline}. The default is \PValue{narrow} and +\PValue{dateright}\ChangedAt{v3.09}{\Class{scrlttr2}}.% % \begin{table} - \caption[{Possible value of option \Option{refline} with - \Class{scrlttr2}}]{Possible value of option \Option{refline} for setting - the width of the reference fields line with - \Class{scrlttr2}} + \caption[{Available values of the \Option{refline} option with + \Class{scrlttr2}}]{Available value of the \Option{refline} option to set + the width of the reference line with \Class{scrlttr2}} \label{tab:\LabelBase.refline} \begin{desctabular} \pventry{dateleft}{\ChangedAt{v3.09}{\Class{scrlttr2}}% - The date will be placed leftmost at the reference line.}% + The date is placed leftmost in the reference line.}% \pventry{dateright}{\ChangedAt{v3.09}{\Class{scrlttr2}}% - The date will be placed rightmost at the reference line.}% - \pventry{narrow}{The reference line will be restricted to type - area.}% + The date is placed rightmost in the reference line.}% + \pventry{narrow}{The reference line is restricted to the type area.}% \pventry{nodate}{\ChangedAt{v3.09}{\Class{scrlttr2}}% The date is not placed automatically into the reference line.}% - \pventry{wide}{The with of the reference line corresponds to address and - sender's additional information.}% + \pventry{wide}{The width of the reference line depends on the positions of + the address and extra sender information.}% \end{desctabular} \end{table} @@ -1948,58 +1983,60 @@ and \PValue{dateright}\ChangedAt{v3.09}{\Class{scrlttr2}}.% \Variable{customer}% \Variable{invoice}% \end{Declaration} -These five variables represent typical fields of the reference line. Their -meanings are given in \autoref{tab:\LabelBase.variables} on -\autopageref{tab:\LabelBase.variables}. Each variable has also a predefined -\PName{description}, shown in \autoref{tab:\LabelBase.reflineTerm}. Additional -information about adding other variables to the reference line may be found -in \autoref{sec:scrlttr2-experts.variables} from -\DescPageRef{scrlttr2-experts.cmd.newkomavar} onward.% +You can manage the typical contents of the reference-field line with five +variables: \Variable{yourref}, \Variable{yourmail}, \Variable{myref}, +\Variable{customer} and \Variable{invoice}. Their meanings are listed in +\autoref{tab:\LabelBase.variables} on \autopageref{tab:\LabelBase.variables}. +Each variable has also a predefined \PName{description}, shown in +\autoref{tab:\LabelBase.reflineTerm}. How to add more variables to the +reference-field line is explained in \autoref{sec:scrlttr2-experts.variables} +starting on \DescPageRef{scrlttr2-experts.cmd.newkomavar}.% % \begin{table} % \centering \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% % \caption - \begin{captionbeside}[{predefined descriptions of variables of the reference - line}]{predefined descriptions of typical variables of the reference - fields line using macros depending on the current language}% + \begin{captionbeside}[{default descriptions of variables in the + reference line}]{default descriptions of typical variables in the + reference line using language-dependent commands}% [l] \begin{tabular}[t]{lll} \toprule - variable name & description & e.\,g., in english \\ + name & description & English default text\\ \midrule \Variable{yourref} & \DescRef{scrlttr2-experts.cmd.yourrefname} & Your reference \\ \Variable{yourmail} & \DescRef{scrlttr2-experts.cmd.yourmailname} & Your letter from \\ \Variable{myref} & \DescRef{scrlttr2-experts.cmd.myrefname} & Our reference \\ \Variable{customer} & \DescRef{scrlttr2-experts.cmd.customername} & Customer No.: \\ \Variable{invoice} & \DescRef{scrlttr2-experts.cmd.invoicename} & Invoice No.: \\ - \DescRef{\LabelBase.variable.date} & \DescRef{scrlttr2-experts.cmd.datename} & date \\ + \DescRef{\LabelBase.variable.date} & \DescRef{scrlttr2-experts.cmd.datename} & date \\ \bottomrule \end{tabular} \end{captionbeside} \label{tab:\LabelBase.reflineTerm} \end{table} +\BeginIndexGroup \BeginIndex{FontElement}{refname}\LabelFontElement{refname}% \BeginIndex{FontElement}{refvalue}\LabelFontElement{refvalue}% -Font style and color\ChangedAt{v2.97c}{\Class{scrlttr2}} of the -\PName{description} and \PName{content} of the fields of the reference line -may be changed with elements \FontElement{refname}% +You\ChangedAt{v2.97c}{\Class{scrlttr2}} can change the font style and colour +of the \PName{description} and \PName{content} of the fields in the reference +line with the \FontElement{refname}% \important[i]{\FontElement{refname}\\\FontElement{refvalue}} and -\FontElement{refvalue}. Therefor the commands \DescRef{\LabelBase.cmd.setkomafont} and \DescRef{\LabelBase.cmd.addtokomafont} (see +\FontElement{refvalue} elements using the \DescRef{\LabelBase.cmd.setkomafont} +and \DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}) should be used. The default -configuration of both elements is listed in -\autoref{tab:\LabelBase.refnamerefvalue}.% +\DescPageRef{\LabelBase.cmd.setkomafont}). The defaults for both elements are +listed in \autoref{tab:\LabelBase.refnamerefvalue}.% \begin{table}[tp] % \centering \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% % \caption \begin{captionbeside} - [{font style default of elements of the reference line}]{default font - style configuration of the elements of the reference line% + [{default font styles for elements in the reference line}]{default font + style settings for the elements in the reference line% \label{tab:\LabelBase.refnamerefvalue}} [l] \begin{tabular}[t]{ll} @@ -2013,8 +2050,6 @@ configuration of both elements is listed in \end{captionbeside} \end{table}% % -\EndIndex{FontElement}{refvalue}% -\EndIndex{FontElement}{refname}% \EndIndexGroup @@ -2022,48 +2057,56 @@ configuration of both elements is listed in \Variable{placeseparator}% \end{Declaration}% \BeginIndex{Variable}{place}% -If all variables of the reference line are empty, the line will be omitted. -In this case, the \PName{content} of \DescRef{\LabelBase.variable.place} and -\Variable{placeseparator} will be set, followed by the \PName{content} of -\DescRef{\LabelBase.variable.date}. The predefined \PName{content} of the -\Variable{placeseparator} is a comma followed by a non-breaking space. If the -variable \DescRef{\LabelBase.variable.place} has no \PName{content} value then -the hyphen remains unset also. The predefined \PName{content} of -\DescRef{\LabelBase.variable.date} is \Macro{today}\IndexCmd{today} and -depends on the setting of the option \DescRef{\LabelBase.option.numericaldate} -(see \DescPageRef{\LabelBase.option.numericaldate}). - -Since version~3.09\ChangedAt{v3.09}{\Class{scrlttr2}} place and date the -alignment of place and date is given by option \DescRef{\LabelBase.option.refline}. The available -alignment values for this option are listed in \autoref{tab:\LabelBase.refline}. +If all variables in the reference-field line, with the exception of +\DescRef{\LabelBase.variable.date}% +\important{\DescRef{\LabelBase.variable.date}}\IndexVariable{date}, are empty, +no actual reference line is output. Instead, a date line consisting only of a +location\Index{location} and a date\Index{date} is output. The \PName{content} +of the \DescRef{\LabelBase.variable.place} variable contains the location. The +delimiter, which in this case is placed after the location, is specified by +the \PName{content} of the \Variable{placeseparator} variable. The +default\textnote{default} \PName{content} of the delimiter is a comma followed +by a non-breaking space. If the location is empty, the delimiter is not +output. The default \PName{content} of \DescRef{\LabelBase.variable.date} is +\Macro{today}\IndexCmd{today} and depends on the setting of the +\DescRef{\LabelBase.option.numericaldate} option (see +\DescPageRef{\LabelBase.option.numericaldate}). + +Starting with version~3.09\ChangedAt{v3.09}{\Class{scrlttr2}}, the location +and date are no longer required to be right-aligned. Instead, when a date +line is used, its alignment is specified by the date setting of the +\DescRef{\LabelBase.option.refline} option, as listed in +\autoref{tab:\LabelBase.refline}. +\BeginIndexGroup \BeginIndex{FontElement}{placeanddate}\LabelFontElement{placeanddate}% -The\ChangedAt{v3.12}{\Class{scrlttr2}} font setting of place and date in the -date line are given by font -element\FontElement{placeanddate}\important[i]{\FontElement{placeanddate}} -instead of element \DescRef{\LabelBase.fontelement.refvalue}, which would be used for general -reference lines. You can change the empty default of the font element using -commands \DescRef{\LabelBase.cmd.setkomafont} and \DescRef{\LabelBase.cmd.addtokomafont} (see +If\ChangedAt{v3.12}{\Class{scrlttr2}} such a date line is output with a +location rather than a reference-field line, the font setting of the +\DescRef{\LabelBase.fontelement.refvalue} element does not apply. In this +case, the \FontElement{placeanddate}\important{\FontElement{placeanddate}} +element is used. You can change the empty default of this font element as +usual with the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}).% -\EndIndex{FontElement}{placeanddate}% +\EndIndexGroup \begin{Example} - Now Mr Public also sets the place:% + Now Mr Public also sets the variable for the location:% \lstinputcode[xleftmargin=1em]{letter-20.tex}% - In this case \autoref{fig:\LabelBase.letter-20} shows the place and the - automatic separator in front of the date. The date has been defined - explicitly to make the printed date independent from the date of the - \LaTeX{} run. + As seen in \autoref{fig:\LabelBase.letter-20}, the location appears + in front of the date, followed by the automatic delimiter. This date has + been defined explicitly so that the original date is maintained in any later + \LaTeX{} run rather than using the date of the \LaTeX{} run. \begin{figure} \setcapindent{0pt}% \begin{captionbeside}[{Example: letter with extended sender, logo, - addressee, additional sender information, place, date, opening, + recipient, extra sender information, location, date, opening, text, closing, signature, postscript, distribution list, enclosure, - and puncher hole mark}] - {result of a small letter with extended sender, logo, addressee, - additional sender information, place, date, opening, text, closing, - signature, postscript, distribution list, enclosure and puncher hole + and hole-punch mark}] + {result of a short letter with extended sender, logo, recipient, + extra sender information, location, date, opening, text, closing, + signature, postscript, distribution list, enclosure and hole-punch mark}[l] \frame{\includegraphics[width=.4\textwidth]{letter-20}} \end{captionbeside} @@ -2072,41 +2115,44 @@ commands \DescRef{\LabelBase.cmd.setkomafont} and \DescRef{\LabelBase.cmd.addtok \end{Example} % \EndIndexGroup -% +\EndIndexGroup \EndIndexGroup \begin{Declaration} \Variable{title}% \end{Declaration} -\BeginIndex{}{title}% +With \KOMAScript{}, you can also give a letter a title\Index{title}. The title +is centred, using the \Macro{LARGE} font size, and placed directly beneath the +reference-field line. + \BeginIndex{FontElement}{lettertitle}\LabelFontElement{lettertitle}% \BeginIndex{FontElement}{title}\LabelFontElement{title}% -With \Class{scrlttr2} a letter can carry an additional title. The title is -centered and set with font size \Macro{LARGE} directly after and beneath the -reference fields line. The predefined font setup for the element -\FontElement{lettertitle}\important{\FontElement{lettertitle}} can be changed -with commands \DescRef{\LabelBase.cmd.setkomafont} und \DescRef{\LabelBase.cmd.addtokomafont} (see +You can change the font style for the +\FontElement{lettertitle}\important{\FontElement{lettertitle}} element with +the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}). Font size declarations are -allowed. Font size \Macro{LARGE} is not part of the predefined default -\Macro{normalcolor}\Macro{sffamily}\Macro{bfseries} but nevertheless will be -used before the font style of the element. With \Class{scrlttr2} you can also -use \FontElement{title}\important{\FontElement{title}} as an alias of -\FontElement{lettertitle}. This is not provided using \Package{scrletter} with -a \KOMAScript{} class, because these classes already define an element -\FontElement{title} with different meaning for the document title.% +allowed. The \Macro{LARGE} font size always precedes the font selection in +\KOMAScript{}, and is therefore not part of the default setting +\Macro{normalcolor}\Macro{sffamily}\Macro{bfseries}. With \Class{scrlttr2}, +you can also use \FontElement{title}\important{\FontElement{title}} as an +alias for \FontElement{lettertitle}. This is not possible when using +\Package{scrletter} with a \KOMAScript{} class because these classes already +define a \FontElement{title} element for the document title with different +setting.% \EndIndex{FontElement}{title}% \EndIndex{FontElement}{lettertitle}% \begin{Example} - Assume that you are to write a reminder. Thus you put as title: + Suppose you are writing a reminder letter. You set a corresponding title: \begin{lstlisting} \setkomavar{title}{Reminder} \end{lstlisting} - This way the addressee will recognize a reminder as such. + This way the recipient should recognize the reminder as such. \end{Example} -Like shown in the example, the \PName{content} of the variable defines the -title. \KOMAScript{} will not use the \PName{description}.% +As shown in the example, the \PName{content} of the variable defines the +title. \KOMAScript{} does not use the \PName{description}.% % \EndIndexGroup @@ -2117,23 +2163,22 @@ title. \KOMAScript{} will not use the \PName{description}.% \Variable{subjectseparator}% \end{Declaration} \BeginIndex{}{subject}% -In case a subject should be set, the \PName{content} of the variable -\Variable{subject} need to be defined. First of all with option -\OptionValue{subject}{true}\important{\OptionValue{subject}{titled}} the usage -of the \PName{description} before the output of the subject may be -configured. See \autoref{tab:\LabelBase.subjectTerm} for the predefined -\PName{description}. In case of using the \PName{description} the -\PName{content} of variable \Variable{subjectseparator}\Index{separator} will -be set between the \PName{description} and \PName{content} of the -\Variable{subject}. The predefined \PName{content} of \PName{subjectseparator} -is a colon followed by a white space. +To include a subject, define the \PName{content} of the \Variable{subject} +variable accordingly. First of all, you can use the +\OptionValue{subject}{true}\important{\OptionValue{subject}{titled}} option, +to choose whether the subject should be preceded with a \PName{description} or +not. If you use the \PName{description} the \PName{content} of the +\Variable{subjectseparator}\Index{separator} variable is output between the +\PName{description} and the \PName{content} of the \Variable{subject} +variable. The default \PName{content} of \PName{subjectseparator} consists of +a colon followed by a space. \begin{table} % \centering \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% % \caption - \begin{captionbeside}{predefined descriptions of subject-related variables} + \begin{captionbeside}{default descriptions of variables for the subject} [l] \begin{tabular}[t]{lll} \toprule @@ -2150,17 +2195,18 @@ is a colon followed by a white space. \label{tab:\LabelBase.subjectTerm} \end{table} -On the other hand, \OptionValue{subject}{afteropening}% -\important{\OptionValue{subject}{afteropening}} may be used to place the -subject below instead of before the letter opening. Furthermore, the -formatting\important[i]{\OptionValue{subject}{underlined}\\ +Additionally, you can use \OptionValue{subject}{afteropening}% +\important{\OptionValue{subject}{afteropening}\\ + \OptionValue{subject}{beforeopening}} to place the subject after the letter +opening instead of the default \OptionValue{subject}{beforeopening}. You can +also specify other formatting\important{\OptionValue{subject}{underlined}\\ \OptionValue{subject}{centered}\\ - \OptionValue{subject}{right}} of the subject may be changed using either + \OptionValue{subject}{right}} for the subject with \OptionValue{subject}{underlined}, \OptionValue{subject}{centered}, or -\OptionValue{subject}{right}\ChangedAt{v2.97c}{\Class{scrlttr2}}. All -available values are listed in \autoref{tab:\LabelBase.subject}. Please -note\textnote{Attention!}, that with option \OptionValue{subject}{underlined} -the while subject must fit at one line! Defaults are +\OptionValue{subject}{right}\ChangedAt{v2.97c}{\Class{scrlttr2}}. The +available values are listed in \autoref{tab:\LabelBase.subject}. +Note\textnote{Attention!} that with the \OptionValue{subject}{underlined} +option, the whole subject must fit onto one line. The defaults are \OptionValue{subject}{left}, \OptionValue{subject}{beforeopening}, and \OptionValue{subject}{untitled}.% % @@ -2170,8 +2216,8 @@ the while subject must fit at one line! Defaults are \setcapindent{0pt}% % \caption \begin{captionbeside} - [{available values of option \Option{subject} with \Class{scrlttr2}}] - {available values of option \Option{subject} for the position and + [{Available values of the \Option{subject} option with \Class{scrlttr2}}] + {Available values of the \Option{subject} option for the position and formatting of the subject with \Class{scrlttr2}\label{tab:\LabelBase.subject}}% [l] @@ -2179,49 +2225,51 @@ the while subject must fit at one line! Defaults are \begin{desctabular}[t] \pventry{afteropening}{subject after opening}% \pventry{beforeopening}{subject before opening}% - \pventry{centered}{subject centered}% + \pventry{centered}{subject centred}% \pventry{left}{subject left-justified}% \pventry{right}{subject right-justified}% \pventry{titled}{add title/description to subject}% - \pventry{underlined}{set subject underlined (see note in text please)}% + \pventry{underlined}{set subject underlined (see note in text)}% \pventry{untitled}{do not add title/description to subject}% \end{desctabular} \end{minipage} \end{captionbeside} \end{table} +\BeginIndexGroup \BeginIndex{FontElement}{lettersubject}\LabelFontElement{lettersubject}% \BeginIndex{FontElement}{subject}\LabelFontElement{subject}% -The subject line is set in a separate font\Index{font>style}. To change this -use the commands \DescRef{\LabelBase.cmd.setkomafont} and -\DescRef{\LabelBase.cmd.addtokomafont} (siehe +The subject line is set in a separate font\Index{font>style}. To change this, +use the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}). For element -\FontElement{lettersubject}\important{\FontElement{lettersubject}} the -predetermined font is \Macro{normalcolor}\Macro{bfseries}. With -\Class{scrlttr2} you can also use +\DescPageRef{\LabelBase.cmd.setkomafont}). For the +\FontElement{lettersubject}\important{\FontElement{lettersubject}} element, +the default font is \Macro{normalcolor}\Macro{bfseries}. With the +\Class{scrlttr2} class, you can also use \FontElement{subject}\important{\FontElement{subject}} as an alias of -\FontElement{lettersubject}. This is not provided using \Package{scrletter} -with a \KOMAScript{} class, because these classes already define an element -\FontElement{subject} with different meaning for the document title.% -\EndIndex{FontElement}{subject}% -\EndIndex{FontElement}{lettersubject}% +\FontElement{lettersubject}. This is not possible with the \Package{scrletter} +package when using a \KOMAScript{} class, because these classes already define +a \FontElement{subject} element for the document title with different +settings.% +\EndIndexGroup + \begin{Example} - Now, Mr Public sets a subject. He's a more traditional person, so he likes - to have a kind of heading to the subject and therefor sets the corresponding + Mr Public now includes a subject. As a traditionalist, he also wants the + subject to be labelled accordingly and therefore sets the corresponding option:% \lstinputcode[xleftmargin=1em]{letter-21.tex}% - The result is shown by \autoref{fig:\LabelBase.letter-21}. + The result is shown in \autoref{fig:\LabelBase.letter-21}. \begin{figure} \setcapindent{0pt}% \begin{captionbeside}[{Example: letter with extended sender, logo, - addressee, additional sender information, place, date, subject, + recipient, extra sender information, place, date, subject, opening, text, closing, signature, postscript, distribution list, - enclosure, and puncher hole mark}] - {result of a small letter with extended sender, logo, addressee, - additional sender information, place, date, subject opening, text, + enclosure, and hole-punch mark}] + {result of a short letter with extended sender, logo, recipient, + extra sender information, place, date, subject, opening, text, closing, signature, postscript, distribution list, enclosure and - puncher hole mark}[l] + hole-punch mark}[l] \frame{\includegraphics[width=.4\textwidth]{letter-21}} \end{captionbeside} \label{fig:\LabelBase.letter-21} @@ -2234,51 +2282,36 @@ with a \KOMAScript{} class, because these classes already define an element \begin{Declaration} \OptionVName{firstfoot}{simple switch} \end{Declaration} -\BeginIndex{}{letter>foot}% -\BeginIndex{}{letterfoot}% -This\ChangedAt{v2.97e}{\Class{scrlttr2}} option determines whether the -letterfoot is set or not. Switching off the letterfoot, e.\,g., using -\OptionValue{firstfoot}{false}\important{\OptionValue{firstfoot}{false}}, has -an effect when the option \DescRef{\LabelBase.option.enlargefirstpage} (see -\DescPageRef{\LabelBase.option.enlargefirstpage}) is used concurrently. In -this case the text area of the page will be enlarged down to the bottom. Then -the normal distance between typing area and the letter foot will become the -only distance remaining between the end of the typing area and the end of the -page. - -The option understands the standard values for simple switches, as given in -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. Default is -the setting of the letter foot. +\BeginIndex{}{letterhead page>footer}% +This\ChangedAt{v2.97e}{\Class{scrlttr2}} option determines whether the footer +for the letterhead page is output. Switching off the letterhead page footer +with \OptionValue{firstfoot}{false}\important{\OptionValue{firstfoot}{false}}, +has an effect when the \DescRef{\LabelBase.option.enlargefirstpage} option +(see \DescPageRef{\LabelBase.option.enlargefirstpage}) is used at the same +time, as this will logically extend the page downwards. In this case, the +distance that is ordinarily between type area and the footer becomes the +distance between the end of the type area and the bottom of the page. + +The option recognizes the standard values for simple switches listed in +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. The default +is to include the letterhead page footer. \EndIndexGroup \begin{Declaration} \Variable{firstfoot}% \end{Declaration}% -\BeginIndex{}{letter>foot}% -\BeginIndex{}{letterfoot}% -The first page's footer is preset to -empty. However\ChangedAt{v3.08}{\Class{scrlttr2}}, a new construction may be -made at the \PName{content} of variable \Variable{firstfoot}. \KOMAScript{} -does not use the \PName{description} of the variable. For more information see -the example following the next description. Only for compatibility reason the -deprecated command \Macro{firstfoot}\IndexCmd[indexmain]{firstfoot} of -\Class{scrlttr2} before release~3.08 still exists. Nevertheless it should not -be used any longer. +\BeginIndex{}{letterhead page>footer}% +The footer of the first page is empty by default. +However\ChangedAt{v3.08}{\Class{scrlttr2}}, you can specify a new footer +in the \PName{content} of the \Variable{firstfoot} variable. \KOMAScript{} +does not use the \PName{description} of the variable. -\begin{Declaration} - \Variable{frombank}% -\end{Declaration}% -This variable at the moment takes on a special meaning: it is not used -internally at this point, and the user can make use of it to set, for example, -his bank account\Index{bank account} within the sender's additional -information (see variable \DescRef{\LabelBase.variable.location}, -\DescPageRef{\LabelBase.variable.location}) or the footer.% -% +\BeginIndex{Variable}{frombank}% \begin{Example} - In the first page's footer, you may want to set the \PName{content} of the - variable \Variable{frombank} (the bank account). The double - backslash should be exchanged with a comma at the same time: + You want to put the \PName{content} of the \Variable{frombank} variable + (i.\,e. the bank account details) in the footer of the first page. The + double backslash should be replaced with a comma: \begin{lstcode} \setkomavar{firstfoot}{% \parbox[b]{\linewidth}{% @@ -2286,12 +2319,11 @@ information (see variable \DescRef{\LabelBase.variable.location}, }% } \end{lstcode} - For the hyphen you might define a variable of your own if you like. - This is left as an exercise for the reader. + You can also define your own variable for the separator. I leave + this as an exercise for the reader. - Nowadays it has become very common to create a proper footer in - order to obtain some balance with respect to the letterhead. This - can be done as follows: + If you want to create a footer in order to counterbalance the letterhead, you + can do so, for example, as follows: \begin{lstcode} \setkomavar{firstfoot}{% \parbox[t]{\textwidth}{\footnotesize @@ -2302,9 +2334,9 @@ information (see variable \DescRef{\LabelBase.variable.location}, \end{tabular}% \hfill \begin{tabular}[t]{l@{}}% - \multicolumn{1}{@{}l@{}}{Manager:}\\ - Jane Fonda\\[1ex] - \multicolumn{1}{@{}l@{}}{Court Of Jurisdiction:}\\ + \multicolumn{1}{@{}l@{}}{Managing Director:}\\ + Lisa Mayer\\[1ex] + \multicolumn{1}{@{}l@{}}{Court Jurisdiction:}\\ Great Plains \end{tabular}% \ifkomavarempty{frombank}{}{% @@ -2317,90 +2349,105 @@ information (see variable \DescRef{\LabelBase.variable.location}, }% } \end{lstcode} - This example, by the way, came from Torsten Kr\"uger. With + This example originally came from Torsten Kr\"uger. You should + consider placing a definition intended for multiple use in different + documents in a separate \File{lco} file\Index{lco file=\File{lco} file}. \begin{lstcode} - \setkomavar{frombank}{Account No. 12\,345\,678\\ - at Citibank\\ - bank code no: 876\,543\,21} + \setkomavar{frombank}{Account No. 12345678\\ + Buffoon Bank\\ + Bank Code: 65-43-21} \end{lstcode} - the bank account can be set accordingly. -% If the footer will have such a large height then it might happen that you -% have to shift its position. You can do this with the pseudo-length -% \PLength{firstfootvpos}\IndexPLength{firstfootvpos}, which is -% described above in this section. + can then be used to set the bank details in the document. +% However depending on your settings, there may not be sufficient space +% for such a large footer, and it may therefore be placed too low on the +% page. In such a case, you can adjust its vertical position with the +% pseudo-length \PLength{firstfootvpos}\IndexPLength{firstfootvpos}. \end{Example} -In the previous example a multi-line footer was set. With a compatibility -setting to version 2.9u (see \DescRef{\LabelBase.option.version} in + +The previous example uses a multi-line footer. With a compatibility setting +of version 2.9u (see \DescRef{\LabelBase.option.version} in \autoref{sec:\LabelBase.compatibilityOptions}, -\DescPageRef{\LabelBase.option.version}) the space will in general not -suffice. In that case, you may need to reduce \PLength{firstfootvpos} (see +\DescPageRef{\LabelBase.option.version}) the space is generally insufficient. +In this case, you should reduce \PLength{firstfootvpos} (see \DescPageRef{scrlttr2-experts.plength.firstfootvpos}) appropriately.% -% \EndIndexGroup + +\begin{Declaration} + \Variable{frombank} +\end{Declaration}% +\BeginIndex{}{letterhead page>footer}% +The \Variable{frombank} variable used in the previous example +occupies a special position. It is not currently used internally. However, you +can use it to put the bank information\Index{bank information} in the +extra sender information field or in the footer, as in the example (see +the variable \DescRef{\LabelBase.variable.location}, +\DescPageRef{\LabelBase.variable.location}).% % \EndIndexGroup % \EndIndexGroup - \LoadCommonFile{parmarkup} % \section{Paragraph Markup} \LoadCommonFile{oddorevenpage} % \section{Detection of Odd and Even Pages} -\section{Head and Foot Using Predefined Page Style} +\section{Headers and Footers with the Default Page Style} \seclabel{pagestyle} \BeginIndexGroup \BeginIndex{}{page>style}% -\BeginIndex{}{page>head}% -\BeginIndex{}{page>foot}% +\BeginIndex{}{page>header}% +\BeginIndex{}{page>footer}% -One of the general properties of a document is the page style. In {\LaTeX} -this means mostly the contents of headers and -footers. Like\textnote{Attention!} already mentioned in -\autoref{sec:\LabelBase.firstpage}, the head and foot of the note paper are -treated as elements of the note paper. Therefore they do not depend on the -settings of the page style. So this section describes the page styles of the -consecutive pages of letter after the note paper. At single-side letters this is -the page style of the secondary letter sheet. At double-side letters this is -also the page style of all backsides. +One of the general properties of a document is its page style. In \LaTeX{} +this mostly consists of the contents of headers and footers. +As\textnote{Attention!} already mentioned in +\autoref{sec:\LabelBase.firstpage}, the header and footer of the letterhead +page are treated as elements of the letterhead page. Therefore they do not +depend on the settings of the page style. So this section describes the page +styles of the subsequent pages of a letter after the letterhead page. For +one-sided letters, this is the page style of the second sheet. For two-sided +letters, this is also the page style of all verso pages. \begin{Declaration} \Macro{letterpagestyle} \end{Declaration} The\ChangedAt{v3.19}{\Class{scrlttr2}\and \Package{scrletter}} default page -style used for letters is specified by the contents of command -\Macro{letterpagestyle}. With \Class{scrlttr2} an empty value has been -predefined that does not change the -page style of the letter from the page style of the document. This has been -done, because \Class{scrlttr2} has been made for letter-only-documents. So it -is much easier to define the page style of all letters with the page style of -the document using \DescRef{\LabelBase.cmd.pagestyle} inside the preamble or before starting -the first letter. - -The \PageStyle{plain} page style of letters differs from the \PageStyle{plain} -page style of most classes. Therefore package \Package{scrletter} defines -\Macro{letterpagestyle} with the contents -\PageStyle{plain.letter}\IndexPagestyle{plain.letter}. So all letters will use -the \PageStyle{plain} style of page style pair -\PageStyle{letter}\IndexPagestyle{letter} by default and independent from the -page style of the rest of the document. See +style for letters is specified by the contents of the \Macro{letterpagestyle} +command. By default\textnote{default}, +\Class{scrlttr2}\OnlyAt{\Class{scrlttr2}} leaves this command empty. This +means that the page style of letters is the same as in the rest of the +document. This is useful because \Class{scrlttr2} is intended for letter-only +documents, and it is easier to define the page style for all letters globally, +using \DescRef{\LabelBase.cmd.pagestyle} as usual. + +Since both the \DescRef{\LabelBase.pagestyle.plain} and the +\DescRef{\LabelBase.pagestyle.headings} page styles of other classes differs +from the page style necessary for letters, the +\Package{scrletter}\OnlyAt{\Package{scrletter}}\textnote{default} package +defines \Macro{letterpagestyle} with to be +\DescRef{\LabelBase.pagestyle.plain.letter}\IndexPagestyle{plain.letter}% +\important{\DescRef{\LabelBase.pagestyle.plain.letter}}. This causes all +letters to use the +\hyperref[desc:\LabelBase.pagestyle.plain.letter]{\PageStyle{plain}} style of +the \DescRef{\LabelBase.pagestyle.letter}\IndexPagestyle{letter} page style +pair, regardless of the page style of the rest of the document. See \autoref{sec:scrlttr2-experts.pagestyleatscrletter} for more information about -the characteristics of the page style of package \Package{scrletter}. +the characteristics of the page style of the \Package{scrletter} package. \begin{Example} - You are using package \Package{scrletter} and want to have the same page - style inside letters as for the rest of the document. So you are using + You are using the \Package{scrletter} package and want letters to use the + same page style that was set for the rest of the document with + \DescRef{\LabelBase.cmd.pagestyle}. To do this, put the command \begin{lstcode} \renewcommand*{\letterpagestyle}{} \end{lstcode} - in your document preamble. Take care about the star of - \Macro{renewcommand*}! + in your document preamble. Notice the star in \Macro{renewcommand*}. \end{Example} -Nevertheless, if you use \DescRef{\LabelBase.cmd.pagestyle} or \DescRef{\LabelBase.cmd.thispagestyle} inside a -letter, this will overwrite the setting of \Macro{letterpagestyle} that is -only the default for the initialisation inside -\Macro{begin}\PParameter{document}.% +Of course, if you use \DescRef{\LabelBase.cmd.pagestyle} or +\DescRef{\LabelBase.cmd.thispagestyle} inside a letter, this will take +precedence over the page style set in \Macro{begin}\PParameter{letter} with +\Macro{letterpagestyle}.% \EndIndexGroup @@ -2408,39 +2455,67 @@ only the default for the initialisation inside \OptionVName{headsepline}{simple switch}% \OptionVName{footsepline}{simple switch} \end{Declaration} -These two options select whether or not to insert a separator -line\Index{line>separator}\Index{rule>separator} below the header or above the -footer, respectively, on consecutive pages. This option can take the standard -values for simple switches, as listed in \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch}. -Activation\important{\OptionValue{headsepline}{true}} of option -\Option{headsepline} switches on a rule below the page -head. Activation\important{\OptionValue{footsepline}{true}} of option -\Option{footsepline} switches on a rule above the page foot. Deactivation of -the options switches of the corresponding rules. - -Obviously option \Option{headsepline} does not influence page style -\PValue{empty}\important[i]{\PageStyle{empty}} (see afterwards at this -section). This page style explicitly does not use any page head. - -Typographically\important[i]{\PageStyle{headings}\\ - \PageStyle{myheadings}\\\PageStyle{plain}} such a rule make a hard optical -connection of head or foot and the text area. This would not mean, that the -distance between head and text or text and foot should be increased. Instead -of this the head or foot should be seen as parts of the typing area, while -calculation of margins and typing area. To achieve this \KOMAScript{} will -pass option \DescRef{typearea.option.headinclude}% -\important[i]{\DescRef{typearea.option.headinclude}\\ - \DescRef{typearea.option.footinclude}} or -\DescRef{typearea.option.footinclude}, respectively, to the \Package{typearea} -package, if option \Option{headsepline} or \Option{footsepline}, respectively, -are used as a class option. In\important{\PageStyle{plain}} opposite to -\Option{headsepline} option \Option{footsepline} does influence page style -\PValue{plain} also, because \PValue{plain} uses a page number at the -foot. Package \Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage}% -\important{\Package{scrlayer-scrpage}} (see \autoref{cha:scrlayer-scrpage}) -provides additional features for rules at head and foot and may be combined -with \Class{scrlttr2}.% +With these options \Class{scrlttr2}\OnlyAt{scrlttr2} can select whether to put +a separator rule\Index{line>separator}\Index{rule>separator} below the header +or above the footer, respectively, on subsequent pages. This option acccepts +the standard values for simple switches listed in +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. +Activating\important{\OptionValue{headsepline}{true}} the \Option{headsepline} +option enables a rule below the header. +Activating\important{\OptionValue{footsepline}{true}} the \Option{footsepline} +option enables a rule above the footer. Deactivating the options disables the +corresponding rules. + +Of course, the \Option{headsepline} and \Option{footsepline} options have no +effect on the \DescRef{\LabelBase.pagestyle.empty}% +\important{\DescRef{\LabelBase.pagestyle.empty}} page style (see later in this +section). This page style explicitly does not use headers or footers. + +Typographically\important{\DescRef{\LabelBase.pagestyle.headings}\\ + \DescRef{\LabelBase.pagestyle.myheadings}\\ + \DescRef{\LabelBase.pagestyle.plain}} speaking, such a rule creates an +optical effect of making the header or footer appear to be closer to the text +area. This does not mean that the distance between the header or footer and +the text should be increased. Instead, they should be seen as part of the text +body\Index{text>body} when calculating the type area. To achieve this +\Class{scrlttr2} uses the \Option{headsepline} class option to automatically +pass the \DescRef{typearea.option.headinclude}% +\important{\DescRef{typearea.option.headinclude}} package option to the +\hyperref[cha:typearea]{\Package{typearea}} package. The same applies to +\DescRef{\LabelBase.option.footsepline} for +\DescRef{typearea.option.footinclude}% +\important{\DescRef{typearea.option.footinclude}}. + +The options themselves do not automatically recalculate the type area. To +recalculate the type area, see the \DescRef{typearea.option.DIV} option with +the \PValue{last} or \PValue{current} values (see +\DescPageRef{typearea.option.DIV.last}), or the +\DescRef{typearea.cmd.recalctypearea} command (see +\DescPageRef{typearea.cmd.recalctypearea}) in \autoref{cha:typearea}. + +The \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} +package (see \autoref{cha:scrlayer-scrpage}) provides further control over +header and footer rules and you can also combine it with \Class{scrlttr2}. The +\Package{scrletter} package automatically uses +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} to +define the \DescRef{\LabelBase.pagestyle.letter} and +\DescRef{\LabelBase.pagestyle.plain.letter} page styles. + +The\OnlyAt{\Package{scrletter}} \DescRef{\LabelBase.pagestyle.letter} and +\DescRef{\LabelBase.pagestyle.plain.letter} page styles defined by +\Package{scrletter} follow the rules of +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}. This particularly +applies to setting the header and footer rules of the \PageStyle{plain} page +style \DescRef{\LabelBase.pagestyle.plain.letter}. See in +\autoref{sec:scrlayer-scrpage.pagestyle.content}, +\DescPageRef{scrlayer-scrpage.option.headsepline} and +\DescPageRef{scrlayer-scrpage.option.plainheadsepline} the options +\DescRef{scrlayer-scrpage.option.headsepline} and +\DescRef{scrlayer-scrpage.option.plainheadsepline}. Also, settings like +\DescRef{scrlayer-scrpage.option.automark} are of some importance for the +\DescRef{\LabelBase.pagestyle.letter} page style.% % \EndIndexGroup @@ -2448,51 +2523,59 @@ with \Class{scrlttr2}.% \begin{Declaration} \OptionVName{pagenumber}{position} \end{Declaration} -This option defines if and where a page number will be placed on consecutive -pages. This option affects the page -styles\important[i]{\PageStyle{headings}\\ - \PageStyle{myheadings}\\ - \PageStyle{plain}} \PageStyle{headings}, \PageStyle{myheadings}, and -\PageStyle{plain}. It also affects the default page styles of the -\Package{scrlayer-scrpage}\important{\Package{scrlayer-scrpage}} package, if -set before loading the package (see \autoref{cha:scrlayer-scrpage}). It can -take values only influencing horizontal, only vertical, or both -positions. Available value are shown in -\autoref{tab:\LabelBase.pagenumber}. Default is \PValue{botcenter}. +With this option you can select if and where a page number should be placed on +subsequent pages. In \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}} this option +affects the page styles\important{\DescRef{\LabelBase.pagestyle.headings}\\ + \DescRef{\LabelBase.pagestyle.myheadings}\\ + \DescRef{\LabelBase.pagestyle.plain}} +\DescRef{\LabelBase.pagestyle.headings}, +\DescRef{\LabelBase.pagestyle.myheadings} and +\DescRef{\LabelBase.pagestyle.plain}; in +\Package{scrletter}\OnlyAt{\Package{scrletter}}, it affects the +\DescRef{\LabelBase.pagestyle.letter} and +\DescRef{\LabelBase.pagestyle.plain.letter} page styles. It also affects the +default page styles of the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}}% +\IndexPackage{scrlayer-scrpage} package, as long as it is set before that +package is loaded (see \autoref{cha:scrlayer-scrpage}). It accepts values that +influence only the horizontal position, only the vertical position, or both +positions simultaneously. Available values are listed in +\autoref{tab:\LabelBase.pagenumber}. The default is \PValue{botcenter}. \begin{table} - \caption[{available values of option \Option{pagenumber} with - \Class{scrlttr2}}]{available values of option \Option{pagenumber} for the - position of the page number in page styles \PageStyle{headings}, + \caption[{Available values for the \Option{pagenumber} option with + \Class{scrlttr2}}]{Available values of the \Option{pagenumber} option to + position the page number in page styles \PageStyle{headings}, \PageStyle{myheadings}, and \PValue{plain} with \Class{scrlttr2}} \label{tab:\LabelBase.pagenumber} \begin{desctabular} \entry{\PValue{bot}, \PValue{foot}}{% - page number in footer, horizontal position not changed}% + page number in footer, horizontal position unchanged}% \entry{\PValue{botcenter}, \PValue{botcentered}, \PValue{botmittle}, \PValue{footcenter}, \PValue{footcentered}, \PValue{footmiddle}}{% - page number in footer, centered}% + page number in footer, centred}% \entry{\PValue{botleft}, \PValue{footleft}}{% - page number in footer, left justified}% + page number in footer, left-justified}% \entry{\PValue{botright}, \PValue{footright}}{% - page number in footer, right justified}% + page number in footer, right-justified}% \entry{\PValue{center}, \PValue{centered}, \PValue{middle}}{% - page number centered horizontally, vertical position not changed}% + page number centred horizontally, vertical position unchanged}% \entry{\PValue{false}, \PValue{no}, \PValue{off}}{% no page number}% \entry{\PValue{head}, \PValue{top}}{% - page number in header, horizontal position not changed}% + page number in header, horizontal position unchanged}% \entry{\PValue{headcenter}, \PValue{headcentered}, \PValue{headmiddle}, \PValue{topcenter}, \PValue{topcentered}, \PValue{topmiddle}}{% - page number in header, centered}% + page number in header, centred}% \entry{\PValue{headleft}, \PValue{topleft}}{% - page number in header, left justified}% + page number in header, left-justified}% \entry{\PValue{headright}, \PValue{topright}}{% - page number in header, right justified}% + page number in header, right-justified}% \entry{\PValue{left}}{% - page number left, vertical position not changed}% + page number left, vertical position unchanged}% \entry{\PValue{right}}{% - page number right, vertical position not changed}% + page number right, vertical position unchanged}% \end{desctabular} \end{table} % @@ -2503,59 +2586,124 @@ positions. Available value are shown in \Macro{pagestyle}\Parameter{page style}% \Macro{thispagestyle}\Parameter{local page style} \end{Declaration}% -In letters written with \Class{scrlttr2} there are four different +\BeginIndex{Pagestyle}{empty}% +\BeginIndex{Pagestyle}{plain}% +\BeginIndex{Pagestyle}{headings}% +\BeginIndex{Pagestyle}{myheadings}% +Letters written with \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}} have four +different page styles available. In contrast, +\Package{scrletter}\OnlyAt{\Package{scrletter}} defines only two of its own page styles. -\begin{description} -\item[{\PageStyle{empty}% - \IndexPagestyle[indexmain]{empty}\LabelPageStyle{empty}}] is the page - style, in which the header and footer of consecutive pages are completely - empty. This page style is also used for the first page, because header and - footer of this page are set by other means using the macro +\begin{description}\setkomafont{descriptionlabel}{} +\item[{\PageStyle{empty}}] + \LabelPageStyle{empty} is the page style where the headers and footers of + subsequent pages are completely empty. This page style is also automatically + used for the first page of the letter because the header and footer of this + page are set by other means, using \DescRef{\LabelBase.cmd.opening}\IndexCmd{opening} (see \autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.cmd.opening}). -\item[{\PageStyle{headings}% - \IndexPagestyle[indexmain]{headings}\LabelPageStyle{heading}}] is the page - style for running (automatic) headings on consecutive pages. The inserted - marks are the sender's name from the variable - \DescRef{\LabelBase.variable.fromname}\IndexVariable{fromname} and the - subject from the variable \DescRef{\LabelBase.variable.subject}\IndexVariable{subject} (see - \autoref{sec:\LabelBase.firstpage}, +\item[{\PageStyle{headings}}] + \LabelPageStyle{headings} is, for \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}}, + the page style for automatic running heads on subsequent pages. The sender's + name from the \DescRef{\LabelBase.variable.fromname}\IndexVariable{fromname} + variable and the subject from the + \DescRef{\LabelBase.variable.subject}\IndexVariable{subject} variable are + used to set the marks (see \autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.variable.fromname} and - \DescPageRef{\LabelBase.variable.subject}). At which position these marks - and the page numbers are placed, depends on the previously described option - \DescRef{\LabelBase.option.pagenumber} and the \PName{content} of the variables + \DescPageRef{\LabelBase.variable.subject}). Where exactly these marks and + page numbers are placed depends on the + \DescRef{\LabelBase.option.pagenumber} described above and the + \PName{content} of the \DescRef{\LabelBase.variable.nexthead}\IndexVariable{nexthead} and - \DescRef{\LabelBase.variable.nextfoot}\IndexVariable{nextfoot}. The author can also change - these marks manually after the \DescRef{\LabelBase.cmd.opening} command. To - this end, the commands \DescRef{\LabelBase.cmd.markboth} and - \DescRef{\LabelBase.cmd.markright} are available as usual, and with the use - of package \Package{scrlayer-scrpage} also - \DescRef{scrlayer-scrpage.cmd.markleft} (see - \autoref{sec:scrlayer-scrpage.pagestyle.content}, - \DescPageRef{scrlayer-scrpage.cmd.automark}) is available. -\item[{\PageStyle{myheadings}% - \IndexPagestyle[indexmain]{myheadings}\LabelPageStyle{myheadings}}] is the - page style for manual page headings on consecutive pages. This is very - similar to \PValue{headings}, but here the marks must be set by the author - using the commands \DescRef{\LabelBase.cmd.markboth}\IndexCmd{markboth} and - \DescRef{\LabelBase.cmd.markright}\Index{markright}. With the use of package - \Package{scrlayer-scrpage} also \DescRef{scrlayer-scrpage.cmd.markleft} can be utilized. -\item[{\PageStyle{plain}% - \IndexPagestyle[indexmain]{plain}\LabelPageStyle{plain}}] is the page - style with only page numbers in the header or footer on consecutive - pages. The placement of these page numbers is influenced by the previously - described option \DescRef{\LabelBase.option.pagenumber}. + \DescRef{\LabelBase.variable.nextfoot}\IndexVariable{nextfoot} variables. An + author can also change these marks manually after the + \DescRef{\LabelBase.cmd.opening} command. As usual, the + \DescRef{\LabelBase.cmd.markboth} and \DescRef{\LabelBase.cmd.markright} + commands are available, as is \DescRef{scrlayer-scrpage.cmd.markleft} if you + use \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + \IndexPackage{scrlayer-scrpage}% + \important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} + (see \autoref{sec:scrlayer-scrpage.pagestyle.content}, + \DescPageRef{scrlayer-scrpage.cmd.automark}). + + Since \Package{scrletter}\OnlyAt{scrletter} uses + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} internally, any + page style \DescRef{maincls.pagestyle.headings} provided by the class are + redefined as an alias of \DescRef{scrlayer-scrpage.pagestyle.scrheadings}. + You can find more about this page style in \autoref{cha:scrlayer-scrpage} on + \DescPageRef{scrlayer-scrpage.pagestyle.scrheadings}. +\item[{\PageStyle{letter}}] + \LabelPageStyle{letter}% + Since the \PageStyle{headings} page style is generally already in use by + the classes, the \Package{scrletter}\OnlyAt{scrletter} package instead + defines the \PageStyle{letter} page style. This is accomplished with the + help of \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} in + \autoref{cha:scrlayer-scrpage}, \autopageref{cha:scrlayer-scrpage}. With the + \OptionValueRef{scrlayer-scrpage}{automark}{true}% + \important{\OptionValueRef{scrlayer-scrpage}{automark}{true}}% + \IndexOption{automark} setting enabled, \PageStyle{letter} then assumes the + role played by \PageStyle{headings} in \Class{scrlttr2}. With + \OptionValueRef{scrlayer-scrpage}{automark}{false}% + \important{\OptionValueRef{scrlayer-scrpage}{automark}{false}}% + \IndexOption{automark} set, \PageStyle{letter} assumes the role of + \PageStyle{myheadings}. + + When\textnote{Attention!} you use + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} with + \Package{scrletter}, you cannot use the obsolete + \Package{scrpage2}\IndexPackage{scrpage2} package or the + \Package{fancyhdr}\IndexPackage{fancyhdr} package, which is incompatible + with \KOMAScript{}. +\item[{\PageStyle{myheadings}}] + \LabelPageStyle{myheadings}% + in \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}} is the page style for manual + running heads on subsequent pages. Unlike \PValue{headings}, you must set + the marks yourself with the + \DescRef{\LabelBase.cmd.markboth}\IndexCmd{markboth} and + \DescRef{\LabelBase.cmd.markright}\IndexCmd{markright} commands. When you + use \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}, + \DescRef{scrlayer-scrpage.cmd.markleft}\IndexCmd{markleft} is also + available. + + With the \Package{scrletter}\OnlyAt{\Package{scrletter}} package, the + \PageStyle{letter} page style also assumes the role of + \PageStyle{myheadings}. +\item[{\PageStyle{plain}}] + \LabelPageStyle{plain}% + is the default page style for \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}}, + which does not use any headers on subsequent pages and only outputs + a single page number. Where this is placed depends on the + \DescRef{\LabelBase.option.pagenumber} option explained above. + + Since \Package{scrletter}\OnlyAt{scrletter} uses + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} internally, the + \DescRef{maincls.pagestyle.plain} page style is redefined as an alias of + \DescRef{scrlayer-scrpage.pagestyle.plain.scrheadings}. You can find more + about this page style in \autoref{cha:scrlayer-scrpage} on + \DescPageRef{scrlayer-scrpage.pagestyle.scrheadings}. +\item[{\PageStyle{plain.letter}}] + \LabelPageStyle{plain.letter}% + Since the \PageStyle{plain} page style is generally already in use by the + classes, the \Package{scrletter}\OnlyAt{scrletter} defines a + \PageStyle{plain.letter} page style instead. This is accomplished with the + help of \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}. + When\textnote{Attention!} you use + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} with + \Package{scrletter}, you cannot use the obsolete + \Package{scrpage2}\IndexPackage{scrpage2} package or the + \Package{fancyhdr}\IndexPackage{fancyhdr} package, which is incompatible + with \KOMAScript{}. \end{description} -Page styles are also influenced by the previously described -options\important[i]{\DescRef{\LabelBase.option.headsepline}\\ +The appearance of the page styles is also influenced by +the\important{\DescRef{\LabelBase.option.headsepline}\\ \DescRef{\LabelBase.option.footsepline}} \DescRef{\LabelBase.option.headsepline}\IndexOption{headsepline} and -\DescRef{\LabelBase.option.footsepline}\IndexOption{footsepline}. The page -style beginning with the current page is switched using \Macro{pagestyle}. In -contrast, \Macro{thispagestyle} changes only the page style of the current -page. The\textnote{Attention!} letter class itself uses -\Macro{thispagestyle}\PParameter{empty} within +\DescRef{\LabelBase.option.footsepline}\IndexOption{footsepline} options +described above. The page style beginning with the current page is changed +using \Macro{pagestyle}. In contrast, \Macro{thispagestyle} changes only the +page style of the current page. The\textnote{Attention!} letter class itself +uses \Macro{thispagestyle}\PParameter{empty} within \DescRef{\LabelBase.cmd.opening}\IndexCmd{opening} for the first page of the letter. @@ -2564,24 +2712,23 @@ letter. \BeginIndex{FontElement}{pageheadfoot}\LabelFontElement{pageheadfoot}% \BeginIndex{FontElement}{pagefoot}\LabelFontElement{pagefoot}% \BeginIndex{FontElement}{pagenumber}\LabelFontElement{pagenumber}% -For changing the font style of headers or footers you should use the user -interface described in \autoref{sec:maincls.textmarkup}. For header and -footer the same element is used, which you can name either +To changing the font style of headers or footers, you should use the user +interface described in \autoref{sec:maincls.textmarkup}. The header and footer +use the same element, which you can refer to by either \FontElement{pageheadfoot}\important{\FontElement{pagehead}} or -\FontElement{pagehead}. There\ChangedAt{v3.00}{\Class{scrlttr2}} is an -additional element \FontElement{pagefoot}\important{\FontElement{pagefoot}} -for the page foot. This will be used after \FontElement{pageheadfoot} at page -foots, that has been defined either with variable -\DescRef{\LabelBase.variable.nextfoot}\IndexVariable{nextfoot} or Package -\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} (see -\autoref{cha:scrlayer-scrpage}, -\DescPageRef{scrlayer-scrpage.fontelement.pagefoot}). The element for the -page number within the header or footer is named -\FontElement{pagenumber}\important{\FontElement{pagenumber}}. Default settings -are listed in \autoref{tab:maincls.defaultFontsHeadFoot}, -\autopageref{tab:maincls.defaultFontsHeadFoot}. Please have also a look at -the example in \autoref{sec:maincls.pagestyle}, -\PageRefxmpl{maincls.cmd.pagestyle}. +\FontElement{pagehead}. The\ChangedAt{v3.00}{\Class{scrlttr2}} +\FontElement{pagefoot}\important{\FontElement{pagefoot}} element +additionally controls the formatting of the footer. This element is applied +after \FontElement{pageheadfoot} in the +\DescRef{\LabelBase.variable.nextfoot}\IndexVariable{nextfoot} variable or +when \Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} page styles are +used (see \autoref{cha:scrlayer-scrpage}, +\DescPageRef{scrlayer-scrpage.fontelement.pagefoot}). The element for the page +number within the header or footer is called +\FontElement{pagenumber}\important{\FontElement{pagenumber}}. The default +settings are listed in \autoref{tab:maincls.defaultFontsHeadFoot}, +\autopageref{tab:maincls.defaultFontsHeadFoot}. Please also note the example +from \autoref{sec:maincls.pagestyle}, \PageRefxmpl{maincls.cmd.pagestyle}. % \EndIndexGroup % @@ -2592,55 +2739,56 @@ the example in \autoref{sec:maincls.pagestyle}, \Macro{markboth}\Parameter{left mark}\Parameter{right mark}% \Macro{markright}\Parameter{right mark} \end{Declaration} -The possibilities that are offered with variables and options in -\Class{scrlttr2} should be good enough in most cases to create letterheads and -footers for the consecutive pages that follow the first letter page. Even more -so since you can additionally change with \Macro{markboth} and -\Macro{markright} the sender's statements that \Class{scrlttr2} uses to create -the letterhead. The commands \Macro{markboth}\IndexCmd{markboth} and -\Macro{markright}\IndexCmd{markright} can in particular be used together with -pagestyle \PageStyle{myheadings}\IndexPagestyle{myheadings}% -\important{\PageStyle{myheadings}}. If the package -\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} is used then this, -of course, is valid also for pagestyle -\PValue{scrheadings}\IndexPagestyle{scrheadings}. There the command -\DescRef{scrlayer-scrpage.cmd.markleft}\IndexCmd{markleft} is furthermore +In most cases, \KOMAScript{}'s options and variables should be quite adequate +for creating headers\Index{header} and footers\Index{footer} for the +subsequent pages, all the more so because, in addition to \Macro{markboth} and +\Macro{markright}, you can change the sender information that \Class{scrlttr2} +or \Package{scrletter} puts in the header. You can, in particular, use the +\Macro{markboth}\IndexCmd{markboth} and \Macro{markright}\IndexCmd{markright} +commands with the \PageStyle{myheadings}\IndexPagestyle{myheadings}% +\important{\PageStyle{myheadings}} pagestyle. Of course, if you use the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} +package, this is also valid for the +\PValue{scrheadings}\IndexPagestyle{scrheadings} page style. In that case, the +\DescRef{scrlayer-scrpage.cmd.markleft}\IndexCmd{markleft} command is also available. \begin{Declaration} \Variable{nexthead}% \Variable{nextfoot}% \end{Declaration} -At times one wants to have more freedom with creating the letterhead or footer -of subsequent pages. Then one has to give up the previously described -possibilities of predefined letterheads or footers that could have been chosen -via the option -\DescRef{\LabelBase.option.pagenumber}\IndexOption{pagenumber}. Instead one is -free to create the letterhead and footer of consecutive pages just the way one -wants to have them set with page style -\PageStyle{headings}\IndexPagestyle{headings}\important{\PageStyle{headings}, - \PageStyle{myheadings}} or -\PageStyle{myheadings}\IndexPagestyle{myheadings}. For that, one creates the -desired letterhead or footer construction using the \PName{content} of -variable\ChangedAt{v3.08}{\Class{scrlttr2}} \Variable{nexthead} or -\Variable{nextfoot}, respectively. Within the \PName{content} of -\Variable{nexthead} and \Variable{nextfoot} you can, for example, have several -boxes side by side or one beneath the other by use of the \Macro{parbox} -command (see \cite{latex:usrguide}). A more advanced user should have no -problems creating letterheads of footers of his own. Within \PName{content} -you can and should of course also make use of other variables by using +At times, however, you may want to the header or the footer of subsequent pages +to more closely resemble the letterhead page. In these cases, you must dispense +with the predefined options that can be selected with the +\DescRef{\LabelBase.option.pagenumber}\IndexOption{pagenumber} option described above. +Instead, you can customise the header and footer of subsequent pages using the +\DescRef{\LabelBase.pagestyle.headings}\IndexPagestyle{headings}% +\important{\DescRef{\LabelBase.pagestyle.headings}, + \DescRef{\LabelBase.pagestyle.myheadings}} or +\DescRef{\LabelBase.pagestyle.myheadings}\IndexPagestyle{myheadings} page styles with \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}}, +and the \DescRef{\LabelBase.pagestyle.letter}% +\IndexPagestyle{letter}\important{\DescRef{\LabelBase.pagestyle.letter}} page style +with \Package{scrletter}\OnlyAt{\Package{scrletter}}. To do so, you create the +structure you want in the \PName{content} of +the\ChangedAt{v3.08}{\Class{scrlttr2}} \Variable{nexthead} or +\Variable{nextfoot} variables. Within the \PName{content} of +\Variable{nexthead} and \Variable{nextfoot} you can, for example, use the \Macro{parbox} +command to place several boxes next to or beneath each other (see \cite{latex:usrguide}). More advanced users should +be able to create their own headers and footers. Of course, you can +and should also make use of additional variables using \DescRef{\LabelBase.cmd.usekomavar}. \KOMAScript{} does not use the -\PName{description} of both variables. - -Only\textnote{Attention!} for compatibility reason the deprecated commands -\Macro{nexthead}\IndexCmd[indexmain]{nexthead} and -\Macro{nextfoot}\IndexCmd[indexmain]{nextfoot} of former \Class{scrlttr2} -releases before 3.08 are also implemented. Nevertheless, you should not use -those.% +\PName{description} for either variable. % -\EndIndexGroup +%Only\textnote{Attention!} for compatibility reason the deprecated commands +%\Macro{nexthead}\IndexCmd[indexmain]{nexthead} and +%\Macro{nextfoot}\IndexCmd[indexmain]{nextfoot} of former \Class{scrlttr2} +%releases before 3.08 are also implemented. Nevertheless, you should not use +%those.% % \EndIndexGroup +\EndIndexGroup % \EndIndexGroup @@ -2652,46 +2800,45 @@ those.% \LoadCommonFile{lists}% \section{Lists} -\section{Math} +\section{Mathematics} \seclabel{math}% \BeginIndexGroup \BeginIndex{}{equations}% \BeginIndex{}{formulas}% \BeginIndex{}{mathematics}% -There are not math environments implemented at the \KOMAScript{} -classes. Instead of this, the math features of the \LaTeX{} kernel have been -supported. Furthermore\textnote{Attention!} regular math with numbered -equations or formulas is very unusual at letters. Because of this -\Class{scrlttr2} does not actively support numbered equations. Therefore -options \DescRef{maincls.option.leqno} and \DescRef{maincls.option.fleqn}, -that has been described for \Class{scrbook}, \Class{scrreprt}, and -\Class{scrartcl} at \autoref{sec:maincls.math} are not available from -\Class{scrlttr2}. - -You will not find a description of the math environments of the \LaTeX{} kernel -here. If you want to use \Environment{displaymath}\IndexEnv{displaymath}, -\Environment{equation}\IndexEnv{equation} and -\Environment{eqnarray}\IndexEnv{eqnarray} you should read a short introduction -into \LaTeX{} like \cite{lshort}. But\textnote{Hint!} if you want more than -very simple mathematics, usage of package \Package{amsmath} would be -recommended (see \cite{package:amsmath}).% +The \KOMAScript{} classes do not provide their own maths environments. +Instead, \KOMAScript{} relies completely on the maths features of the \LaTeX{} +kernel. However\textnote{Attention!}, since numbered equations and formulas +are very unusual in letters, \KOMAScript{} does not actively support them. +Therefore, the \DescRef{maincls.option.leqno} and +\DescRef{maincls.option.fleqn} options for \Class{scrbook}, \Class{scrreprt}, +and \Class{scrartcl}, documented in \autoref{sec:maincls.math}, are not +available with \Class{scrlttr2}. + +You will not find a description here of the maths environments of the \LaTeX{} +kernel, that is \Environment{displaymath}\IndexEnv{displaymath}, +\Environment{equation}\IndexEnv{equation}, and +\Environment{eqnarray}\IndexEnv{eqnarray}. If you want to use them, consult an +introduction to \LaTeX{} like \cite{lshort}. But\textnote{Hint!} if you want +more than very simple mathematics, you should use the \Package{amsmath} +package (see \cite{package:amsmath}).% % \EndIndexGroup -\section{Floating Environments of Tables and Figures} +\section{Floating Environments for Tables and Figures} \seclabel{floats} -Floating environments for tables or figures are very unusual in -letters. Therefore\textnote{Attention!} \Class{scrlttr2} does not provide -them. If someone nevertheless needs floating environments, then this is often -points out a malpractice of the letter class. In such cases you may try to -define the floating environments with help of packages like \Package{tocbasic}\important{\Package{tocbasic}} (siehe -\autoref{cha:tocbasic}). Nevertheless, tabulars and pictures or graphics -without floating environment may still be done with the letter class -\Class{scrlttr2}. - +Floating environments for tables or figures are very unusual in letters. +Therefore\textnote{Attention!} \Class{scrlttr2} does not provide them. If you +still believe you need them, this often indicates a misuse of the letter +class. In such cases, it is advisable to combine one of the \KOMAScript{} +classes from \autoref{cha:maincls} with the +\Package{scrletter}\important{\Package{scrletter}} package instead. In this +case you, the floating environments documented for the class can also be used +in letters. You could also define your own floating environments with help of +\Package{tocbasic}\important{\Package{tocbasic}} (see \autoref{cha:tocbasic}). \LoadCommonFile{marginpar} % \section{Margin Notes} @@ -2704,68 +2851,73 @@ without floating environment may still be done with the letter class \BeginIndex{}{signature}% \BeginIndex{}{letter>signature}% -That the letter closing will be set by -\DescRef{\LabelBase.cmd.closing}\IndexCmd{closing} has been explained already -in \autoref{sec:\LabelBase.document}, \DescPageRef{\LabelBase.cmd.closing}. A kind -of annotation to the signature is often placed below the signature of the -letter. The signing or hand-written inscription itself is placed between this -signature annotation and the closing phrase. +It has already been mentioned in \autoref{sec:\LabelBase.document}, +\DescPageRef{\LabelBase.cmd.closing} that the letter's closing text is +provided by \DescRef{\LabelBase.cmd.closing}\IndexCmd{closing}. Beneath the +closing text, there is often a space for a handwritten signature, beneath +which there can be a printed name, which serves as a kind of annotation to the +actual signature. \begin{Declaration} \Variable{signature}% \end{Declaration} -The variable \Variable{signature} holds an explanation or annotation for the -inscription, the signing of the letter. The \PName{content} is predefined as -\DescRef{\LabelBase.cmd.usekomavar}\PParameter{fromname}. The annotation may -consist of multiple lines. The lines should then be separated by a double -backslash. Paragraph\textnote{Attention!} breaks in the annotation are however -not permitted.% +The \Variable{signature} variable contains the printed name or annotation for +the handwritten signature. Its default \PName{content} is the +\DescRef{\LabelBase.cmd.usekomavar}\PParameter{fromname}. This annotation can +consist of multiple lines. In that case, you should separate the individual +lines with double backslashes. Paragraph\textnote{Attention!} breaks in the +signature annotation, however, are not permitted.% \EndIndexGroup \begin{Declaration} \Macro{raggedsignature} \end{Declaration} -Closing phrase and signature will be typeset in a box. The width of -the box is determined by the length of the longest line of the closing -phrase or signature's \PName{content}. - -Where to place this box is determined by the pseudo-lengths -\PLength{sigindent}\IndexPLength{sigindent} and -\PLength{sigbeforevskip}\IndexPLength{sigbeforevskip} (see -\autoref{sec:scrlttr2-experts.closing}, -\DescPageRef{scrlttr2-experts.plength.sigindent}). The command -\Macro{raggedsignature} defines the alignment inside the box. In the -predefined \File{lco} files the command is either defined as \Macro{centering} -(all besides \Option{KOMAold}) or \Macro{raggedright} (\Option{KOMAold}). In -order to obtain flush-right or flush-left alignment inside the box, the -command can be redefined in the same way as -\DescRef{maincls.cmd.raggedsection} (see \autoref{sec:maincls.structure}, +The closing phrase and the signature will be typeset in a box. The width of +the box is determined by the length of the longest line in the closing +phrase or signature. + +The \PLength{sigindent}\IndexPLength{sigindent} and +\PLength{sigbeforevskip}\IndexPLength{sigbeforevskip} pseudo-lengths determine +exactly where this box is placed (see \autoref{sec:scrlttr2-experts.closing}, +\DescPageRef{scrlttr2-experts.plength.sigindent}). The \Macro{raggedsignature} +command defines the alignment inside the box. In the default \File{lco} files, +the command is either defined as \Macro{centering} (all besides +\Option{KOMAold}) or \Macro{raggedright} (\Option{KOMAold}). In order to +obtain flush-right or flush-left alignment inside the box, you can redefine +the command in the same way as \DescRef{maincls.cmd.raggedsection} (see the +example in \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.raggedsection}). \begin{Example} - Now, Mr Public really wants to aggrandize himself. Therefor he uses the - signature to show again, that he himself was formerly chairman. Because of - this he changes \PName{contents} of variable - \DescRef{\LabelBase.variable.signature}. Additionally he wants the signature - be flush-left aligned and so he also redefines \Macro{raggedsignature}:% + Now Mr Public wants to make himself seem really important, and therefore he uses the + signature to show once again that he was formerly a chairman himself. So + he changes \PName{contents} of the + \DescRef{\LabelBase.variable.signature} variable. He also wants the signature + be aligned flush-left and so he also redefines \Macro{raggedsignature}:% \lstinputcode[xleftmargin=1em]{letter-22}% See \autoref{fig:\LabelBase.letter-22} for the result. \begin{figure} \setcapindent{0pt}% \begin{captionbeside}[{Example: letter with extended sender, logo, - addressee, additional sender information, place, date, subject, + recipient, extra sender information, place, date, subject, opening, text, closing, modified signature, postscript, distribution - list, enclosure, and puncher hole mark}] - {result of a small letter with extended sender, logo, addressee, - additional sender information, place, date, subject opening, text, + list, enclosure, and hole-punch mark}] + {result of a short letter with extended sender, logo, recipient, + extra sender information, place, date, subject opening, text, closing, modified signature, postscript, distribution list, enclosure - and puncher hole mark}[l] + and hole-punch mark}[l] \frame{\includegraphics[width=.4\textwidth]{letter-22}} \end{captionbeside} \label{fig:\LabelBase.letter-22} \end{figure} \end{Example} + +\iftrue% Umbruchkorrekturtext + The preceding example shows the most important, although not all possible, + elements of a letter. It can, however, serve quite well as a general + template.% +\fi % \EndIndexGroup % @@ -2775,244 +2927,283 @@ command can be redefined in the same way as \section{Letter Class Option Files} \seclabel{lcoFile}% \BeginIndexGroup -\BeginIndex{}{lco-file=\File{lco}-file}% +\BeginIndex{}{lco file=\File{lco} file}% \BeginIndex{}{letter class option}% -\BeginIndex{}{letter>class option}% Normally, you would not redefine selections like the sender's information every time you write a letter. Instead, you would reuse a whole set of -parameters for certain occasions. It will be much the same for the letterhead -and footer used on the first page. Therefore, it is reasonable to save these -settings in a separate file. For this purpose, the \Class{scrlttr2} class -offers the \File{lco}-files. The \File{lco} suffix is an abbreviation for +parameters for certain occasions. The same applies to the letterhead +and footer used on the first page. Therefore it makes sense to save these +settings in a separate file. For this purpose, \KOMAScript{} offers +\File{lco} files. The \File{lco} suffix is an abbreviation for \emph{\emph{l}etter \emph{c}lass \emph{o}ption}. -In an \File{lco} file you can use all commands available to the document at -the time the \File{lco} file is loaded. Additionally, it can contain internal -commands available to package writers. For \Class{scrlttr2}, these are in -particular the commands +In an \File{lco} file, you can use all commands available to the document at +the time the \File{lco} file is loaded. You can also use internal commands +available to package writers. For \Class{scrlttr2} and \Package{scrletter}, +these are, in particular, the commands \DescRef{scrlttr2-experts.cmd.@newplength}\IndexCmd{@newplength}, \DescRef{scrlttr2-experts.cmd.@setplength}\IndexCmd{@setplength}, and \DescRef{scrlttr2-experts.cmd.@setplength}\IndexCmd{@addtoplength} (see \autoref{sec:scrlttr2-experts.pseudoLengths}). -There are already some \File{lco} files included in the {\KOMAScript} -distribution. The \File{DIN.lco}, \File{DINmtext.lco}, \File{SNleft.lco}, -\File{SN.lco}, \File{UScommercial9}, \File{UScommercial9DW}, -\File{NF.lco}\ChangedAt{v3.04}{\Class{scrlttr2}} files serve to adjust -{\KOMAScript} to different layout standards. They are well suited as templates -for your own parameter sets, while you become a \KOMAScript{} expert. The -\File{KOMAold.lco} file, on the other hand, serves to improve compatibility -with the old letter class \Class{scrlettr}. Since it contains internal -commands not open to package writers, you should not use this as a template -for your own \File{lco} files. You can find a list of predefined \File{lco} -files in \autoref{tab:lcoFiles}, \autopageref{tab:lcoFiles}. - -If you have defined a parameter set for a letter standard not yet supported by -\KOMAScript, you are explicitly invited to send this parameter set to the -{\KOMAScript} support address. Please do not forget to include the permission -for distribution under the {\KOMAScript} license (see the \File{lppl.txt} -file). If you know the necessary metrics for an unsupported letter standard, -but are not able to write a corresponding \File{lco} file yourself, you can -also contact the {\KOMAScript} author, Markus Kohm, directly. More -particular complex examples of \File{lco}-files are shown at \cite{homepage} -or in \cite{DANTE:TK0203:MJK}. Both locations are mainly in German. +\KOMAScript{} comes provided with some \File{lco} files. The \File{DIN.lco}, +\File{DINmtext.lco}, \File{SNleft.lco}, \File{SN.lco}, \File{UScommercial9}, +\File{UScommercial9DW}, and \File{NF.lco}\ChangedAt{v3.04}{\Class{scrlttr2}} +files serve to adapt \Class{scrlttr2} and \Package{scrletter} to different +standards. They are well suited as templates for your own parameter sets as +you become a \KOMAScript{} expert. The \File{KOMAold.lco} file, on the other +hand, serves to improve compatibility with the old letter class +\Class{scrlettr}. This class was removed from \KOMAScript{} over fifteen years +ago. It is therefore not discussed in any detail. Since this file also +contains internal commands that are not released for package writers, you +should not use this as a template for your own \File{lco} files. You can find +a list of predefined \File{lco} files in \autoref{tab:lcoFiles}, +\autopageref{tab:lcoFiles}. + +If you have defined a parameter set for a letter standard that is not yet +supported by \KOMAScript{}, you are explicitly requested to send this +parameter set to the \KOMAScript{} support address. Please also provide +permission for distribution under the \KOMAScript{} license (see the +\File{lppl.txt} file). If you have the necessary measurements for an +unsupported letter standard but are unable to write a corresponding \File{lco} +file yourself, you can also contact the \KOMAScript{} author, Markus Kohm, +directly. you can find further examples of \File{lco} files, some very +complex, at \cite{homepage} or in \cite{DANTE:TK0203:MJK}. Both sites are +mainly in German. + \begin{Declaration} \Macro{LoadLetterOption}\Parameter{name}% \Macro{LoadLetterOptions}\Parameter{list of names} \end{Declaration} -With \Class{scrlttr2} \File{lco}-files can be loaded by the -\Macro{documentclass} command. You enter the name of the \File{lco}-file -without suffix as an option\Index{option}. In this case, the \File{lco}-file -will be loaded right after the class file. - -However, it is recommended to load an \File{lco}-file using -\Macro{LoadLetterOption} or -\Macro{LoadLetterOptions}\ChangedAt{v3.14}{\Class{scrlttr2}}. You can do this -even from within another \File{lco}-file. Both commands take the \PName{name} -of the \File{lco}-file without suffix, \Macro{LoadLetterOption} as a single -parameter, \Macro{LoadLetterOptions} as one member of a comma-separated -\PName{list of names}. The corresponding \File{lco}-files will be loaded in -the order given by the list. +With \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}} you can load \File{lco} files +with the \Macro{documentclass} command. To do so, give the name of the +\File{lco} file without the extension as an option\Index{option}. The +\File{lco} file is then loaded directly after the class. The +\Package{scrletter}\textnote{Attention!} package does not offer this option. +To load \File{lco} files, you must use \Macro{LoadLetterOption} or +\Macro{LoadLetterOptions}\ChangedAt{v3.14}{\Class{scrlttr2}}. +This\textnote{Recommendation!} is also recommended for \Class{scrlttr2}. + +You can also use \Macro{LoadLetterOption} and \Macro{LoadLetterOptions} after +\Macro{begin}\PParameter{document}, or even from within another \File{lco} +file. Both commands take the \PName{name} of the \File{lco} file without the +extension. While the argument of \Macro{LoadLetterOption} should be exactly +one \File{lco} file, \Macro{LoadLetterOptions} accepts a comma-separated +\PName{list of names}. The corresponding \File{lco} files with those names are +loaded in the order given by the list. \begin{Example} - Mr Public also writes a document containing several letters. Most of them - should comply with the German DIN standard. So he starts with: + Joe Public also writes a document containing several letters. For most of + them, the default format, which follows the format of the German Institute + for Standardisation, or \emph{Deutsches Institut f\"{u}r Normung} (DIN), is + sufficient. So he starts with: \begin{lstcode} \documentclass{scrlttr2} \end{lstcode} - However, one letter should use the \File{DINmtext} variant, with the - address field placed more toward the top, which results in more text - fitting on the first page. The folding will be modified so that the - address field still matches the address window in a DIN~C6/5 envelope. - You can achieve this as follows: + However, he wants to send one letter in a C6/5 envelope, and so he + uses the \File{DINmtext} variant, in which the + address field appears higher on the page, so that more text + fits on the first page. The fold marks are adjusted so that the + address field still fits the address window in a C6/5 envelope. + He achieves this as follows: \begin{lstcode} \begin{letter}{% - Joana Public\\ - Hillside 1\\ - 12345 Public-City} + Joanna Public\\ + 1 Hillside\\ + SAMPLESTEAD\\ + WX12 3YZ} \LoadLetterOption{DINmtext} \opening{Hello,} \end{lstcode} - Since construction of the page does not start before the - \DescRef{\LabelBase.cmd.opening}\IndexCmd{opening} command, it is sufficient - to load the \File{lco}-file before this. In particular, the loading need not - be done before \Macro{begin}\PParameter{letter}. Therefore the changes made - by loading the \File{lco}-file are local to the corresponding letter. + Since construction of the first page only really begins with the + \DescRef{\LabelBase.cmd.opening}\IndexCmd{opening} command, you only need to + load the \File{lco} file before this point. In particular, you do not need + to load it before \Macro{begin}\PParameter{letter}. That way the changes + made by loading the \File{lco} file are local to the corresponding letter. \end{Example} -If\ChangedAt{v2.97}{\Class{scrlttr2}} an \File{lco}-file is loaded via -\Macro{documentclass}, then it may no longer have the same name as an option. +If\ChangedAt{v2.97}{\Class{scrlttr2}} an \File{lco} file is loaded via +\Macro{documentclass}, then it must not have the same name as an option. \begin{Example} - Since Mr~Public often writes letters with the same options and parameters, - he does not like to copy all these to each new letter. To simplify the effort - of writing a new letter, he therefore makes a \File{lco}-file:% + Since Mr Public often writes letters with the same options and parameters, + he finds it quite annoying to copy this information to each new letter. To + simplify the effort of writing a new letter, he therefore creates an + \File{lco} file:% \lstinputcode[xleftmargin=1em]{ich.lco}% - With this the size of the previous letter decreases to: - \lstinputcode[xleftmargin=1em]{letter-23.tex}% - Nevertheless, as shown in \autoref{fig:\LabelBase.letter-23}, the result - does not change. + With this, the size of his letter from the previous example shrinks + considerably: \lstinputcode[xleftmargin=1em]{letter-23.tex}% + Nevertheless, the result does not change, as shown in + \autoref{fig:\LabelBase.letter-23}. \begin{figure} \setcapindent{0pt}% \begin{captionbeside}[{Example: letter with extended sender, logo, - addressee, additional sender information, place, date, subject, + recipient, extra sender information, place, date, subject, opening, text, closing, modified signature, postscript, distribution - list, enclosure, and puncher hole mark using a \File{lco}-file}] - {result of a small letter with extended sender, logo, addressee, - additional sender information, place, date, subject opening, text, + list, enclosure, and hole-punch mark using an \File{lco} file}] + {result of a short letter with extended sender, logo, recipient, + extra sender information, place, date, subject opening, text, closing, modified signature, postscript, distribution list, enclosure - and puncher hole mark using a \File{lco}-file}[l] + and hole-punch mark using an \File{lco} file}[l] \frame{\includegraphics[width=.4\textwidth]{letter-23}} \end{captionbeside} \label{fig:\LabelBase.letter-23} \end{figure} \end{Example} -Please note\textnote{Attention!} that immediately after loading the -document class normally neither a package for the input encoding nor a -language package has been loaded. Because of this, you should use \TeX's 7-bit -encoding for all characters, e.\,g., use ``\Macro{ss}'' to produce a German +Note\textnote{Attention!} that immediately after loading the document class, +normally neither a package for the input encoding nor a language package has +been loaded. Because of this, you should use \TeX's 7-bit encoding for all +non-ASCII characters. For example, use ``\Macro{ss}'' to produce a German ``\ss''. In \autoref{tab:lcoFiles}, \autopageref{tab:lcoFiles} you can find a list of all predefined \File{lco} files. If\textnote{Attention!} you use a printer that has large unprintable areas on the left or right side, you might have problems with the \Option{SN}\IndexOption{SN} option. Since the Swiss standard -SN~101\,130 defines the address field to be placed 8\Unit{mm} from the right -paper edge, the headline and the sender attributes too will be set with the -same small distance from the paper edge. This also applies to the reference -line when using the \DescRef{\LabelBase.option.refline}\PValue{=wide} option -(see \autoref{sec:\LabelBase.firstpage}, -\DescPageRef{\LabelBase.option.refline}). If\textnote{Hint!} you have this -kind of problem, create your own \File{lco} file that loads \Option{SN} first -and then changes \PLength{toaddrhpos}\IndexPLength{toaddrhpos} (see +SN~101\,130 stipulates that the address field should be placed 8\Unit{mm} from +the right edge of the paper, the headline and the sender attributes are also +placed at a correspondingly small distance from the paper edge. This also +applies to the reference line when using the +\DescRef{\LabelBase.option.refline}\PValue{=wide} option (see +\autoref{sec:\LabelBase.firstpage}, \DescPageRef{\LabelBase.option.refline}). +If\textnote{Hint!} you have this kind of problem, create your own \File{lco} +file that loads \Option{SN} first and then changes +\PLength{toaddrhpos}\IndexPLength{toaddrhpos} (see \autoref{sec:scrlttr2-experts.addressee}, -\DescPageRef{scrlttr2-experts.plength.toaddrvpos}) to a smaller -value. Additionally, also reduce \PLength{toaddrwidth} accordingly.% +\DescPageRef{scrlttr2-experts.plength.toaddrvpos}) to a smaller value. In +addition, you should also reduce \PLength{toaddrwidth} accordingly.% -By\textnote{Hint!} the way, the \File{DIN} \File{lco}-file will always be -loaded as the first \File{lco} file. This ensures that all pseudo-lengths will -have more or less reasonable default values. Because of this, it is not -necessary to load this default file on your own. +By\textnote{Hint!} the way, the \File{DIN} \File{lco} file is always loaded +automatically as the first \File{lco} file. This ensures that all +pseudo-lengths will have more or less reasonable default values. Therefore you +do not need to load this default file on your own. -Please\textnote{Attention!} note that it is not possible to use -\Macro{PassOptionsToPackage} to pass options to packages from within an -\File{lco}-file that have already been loaded by the class. Normally, this -only applies to the \Package{typearea}, \Package{scrlfile}, \Package{scrbase}, -and \Package{keyval} packages.% +%Please\textnote{Attention!} note that it is not possible to use +%\Macro{PassOptionsToPackage} to pass options to packages from within an +%\File{lco} file that have already been loaded by the class. Normally, this +%only applies to the \Package{typearea}, \Package{scrlfile}, \Package{scrbase}, +%and \Package{keyval} packages.% \begin{desclist} \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% \desccaption{% - predefined \File{lco}-files\label{tab:lcoFiles}% + Predefined \File{lco} files\label{tab:lcoFiles}% }{% - predefined \File{lco}-files (\emph{continuation})% + Predefined \File{lco} files (\emph{continued})% }% \oentry{DIN}{% - parameter set for letters on A4-size paper, complying with German standard + \leavevmode% + \IndexOption[indexmain]{DIN}\IndexFile[indexmain]{DIN.lco}% + parameters for letters on A4 paper, complying with German standard DIN~676; suitable for window envelopes in the sizes C4, C5, C6, and C6/5 (C6 long).}% \oentry{DINmtext}{% - parameter set for letters on A4-size paper, complying with DIN~676, but - using an alternate layout with more text on the first page; only suitable - for window envelopes in the sizes C6 and C6/5 (C6 long).}% + \leavevmode% + \IndexOption[indexmain]{DINmtext}\IndexFile[indexmain]{DINmtext.lco}% + parameters for letters on A4 paper, complying with DIN~676 but using an + alternate layout with more text on the first page; only suitable for + window envelopes in the sizes C6 and C6/5 (C6 long).}% \oentry{KakuLL}{% - parameter set for Japanese letters in A4 format; suitable for Japanese - window envelopes of type Kaku A4, in which the windows is approximately - 90\Unit{mm} wide, 45\Unit{mm} high, and positioned 25\Unit{mm} from the + \leavevmode% + \IndexOption[indexmain]{KakuLL}\IndexFile[indexmain]{KakuLL.lco}% + parameters for Japanese letters on A4 paper; suitable for Japanese + window envelopes of type Kaku A4, in which the window is approximately + 90\Unit{mm} wide by 45\Unit{mm} high, and positioned 25\Unit{mm} from the left and 24\Unit{mm} from the top edge (see \autoref{cha:japanlco}).}% \oentry{KOMAold}{% - parameter set for letters on A4-size paper using a layout close to the now + \leavevmode% + \IndexOption[indexmain]{KOMAold}\IndexFile[indexmain]{KOMAold.lco}% + parameters for letters on A4 paper using a layout close to that of the obsolete \Class{scrlettr} letter class; suitable for window envelopes in the sizes C4, C5, C6, and C6/5 (C6 long); some additional commands to improve compatibility with obsolete \Class{scrlettr} commands are defined; - \Class{scrlttr2} may behave slightly different when used with this - \File{lco}-file than with the other \File{lco}-files.}% + \Class{scrlttr2} may behave slightly differently with this \File{lco} file + than with the other \File{lco} files.}% \oentry{NF}{% - parameter set for French letters, according to NF~Z~11-001; suitable for - window envelopes of type DL (110\Unit{mm} to 220\Unit{mm}) with a window - of about 20\Unit{mm} from right and bottom with width 45\Unit{mm} and - height 100\Unit{mm}; this file was originally developed by Jean-Marie - Pacquet, who provides an extended version and additional information on + \leavevmode% + \IndexOption[indexmain]{NF}\IndexFile[indexmain]{NF.lco}% + parameters for French letters, complying with NF~Z~11-001; suitable for + window envelopes of type DL (110\Unit{mm} by 220\Unit{mm}) with a window + 45\Unit{mm} wide by 100\Unit{mm} high placed about 20\Unit{mm} from the + lower right edge; this file was originally developed by Jean-Marie + Pacquet, who also provides LyX integration in addition to extensions at \cite{www:NF.lco}.}% \oentry{NipponEH}{% - parameter set for Japanese letters in A4 format; suitable for Japanese - window envelopes of types Chou or You 3 or 4, in which the windows is - approximately 90\Unit{mm} wide, 55\Unit{mm} high, and positioned + \leavevmode% + \IndexOption[indexmain]{NipponEH}\IndexFile[indexmain]{NipponEH.lco}% + parameters for Japanese letters on A4 paper; suitable for Japanese + window envelopes of types Chou or You 3 or 4, in which the window is + approximately 90\Unit{mm} wide by 55\Unit{mm} high, and positioned 22\Unit{mm} from the left and 12\Unit{mm} from the top edge (see \autoref{cha:japanlco}).}% \oentry{NipponEL}{% - parameter set for Japanese letters in A4 format; suitable for Japanese - window envelopes of types Chou or You 3 or 4, in which the windows is - approximately 90\Unit{mm} wide, 45\Unit{mm} high, and positioned + \leavevmode% + \IndexOption[indexmain]{NipponEL}\IndexFile[indexmain]{NipponEL.lco}% + parameters for Japanese letters on A4 paper; suitable for Japanese + window envelopes of types Chou or You 3 or 4, in which the window is + approximately 90\Unit{mm} wide by 45\Unit{mm} high, and positioned 22\Unit{mm} from the left and 12\Unit{mm} from the top edge (see \autoref{cha:japanlco}).}% \oentry{NipponLH}{% - parameter set for Japanese letters in A4 format; suitable for Japanese - window envelopes of types Chou or You 3 or 4, in which the windows is - approximately 90\Unit{mm} wide, 55\Unit{mm} high, and positioned + \leavevmode% + \IndexOption[indexmain]{NipponLH}\IndexFile[indexmain]{NipponLH.lco}% + parameters for Japanese letters on A4 paper; suitable for Japanese + window envelopes of types Chou or You 3 or 4, in which the window is + approximately 90\Unit{mm} wide by 55\Unit{mm} high, and positioned 25\Unit{mm} from the left and 12\Unit{mm} from the top edge (see \autoref{cha:japanlco}).}% \oentry{NipponLL}{% - parameter set for Japanese letters in A4 format; suitable for Japanese - window envelopes of types Chou or You 3 or 4, in which the windows is - approximately 90\Unit{mm} wide, 45\Unit{mm} high, and positioned + \leavevmode% + \IndexOption[indexmain]{NipponLL}\IndexFile[indexmain]{NipponLL.lco}% + parameters for Japanese letters on A4 paper; suitable for Japanese + window envelopes of types Chou or You 3 or 4, in which the window is + approximately 90\Unit{mm} wide by 45\Unit{mm} high, and positioned 25\Unit{mm} from the left and 12\Unit{mm} from the top edge (see \autoref{cha:japanlco}).}% \oentry{NipponRL}{% - parameter set for Japanese letters in A4 format; suitable for Japanese - window envelopes of types Chou or You 3 or 4, in which the windows is - approximately 90\Unit{mm} wide, 45\Unit{mm} high, and positioned + \leavevmode% + \IndexOption[indexmain]{NipponRL}\IndexFile[indexmain]{NipponRL.lco}% + parameters for Japanese letters on A4 paper; suitable for Japanese + window envelopes of types Chou or You 3 or 4, in which the window is + approximately 90\Unit{mm} wide by 45\Unit{mm} high, and positioned 25\Unit{mm} from the left and 24\Unit{mm} from the top edge (see \autoref{cha:japanlco}).}% \oentry{SN}{% - parameter set for Swiss letters with address field on the right side, + \leavevmode% + \IndexOption[indexmain]{SN}\IndexFile[indexmain]{SN.lco}% + parameters for Swiss letters with the address field on the right side, according to SN~010\,130; suitable for Swiss window envelopes in the sizes C4, C5, C6, and C6/5 (C6 long).}% \oentry{SNleft}{% - parameter set for Swiss letters with address field on the left side; - suitable for Swiss window envelopes with window on the left side in the - sizes C4, C5, C6, and C6/5 (C6 long).}% + \leavevmode% + \IndexOption[indexmain]{SNleft}\IndexFile[indexmain]{SNleft.lco}% + parameters for Swiss letters with the address field on the left side; + suitable for Swiss window envelopes with the window on the left side in + the sizes C4, C5, C6, and C6/5 (C6 long).}% \oentry{UScommercial9}{% - parameter set for US-American letters with paper size letter; suitable for - US-American window envelopes of size \emph{commercial~No.\,9} with window - width of 4\,1/2\Unit{in}, height of 1\,1/8\Unit{in}, and position of - 7/8\Unit{in} from the left and 1/2\Unit{in} from the bottom, without - sender's return address inside of the window; with folding it first at the - puncher mark then at the top folder mark also legal paper may be used but - would result in a page size warning}% + \leavevmode% + \IndexOption[indexmain]{UScommercial9}% + \IndexFile[indexmain]{UScommercial9.lco}% + parameters for US letters on American letter paper; suitable for + \emph{commercial~No.\,9} US window envelopes with a window 4\,1/2\Unit{in} + wide by 1\,1/8\Unit{in} high, positioned 7/8\Unit{in} from the left and + 1/2\Unit{in} from the bottom, without the return address inside the + window; when folded first at the middle mark then at the top fold mark, + legal paper can also be used but results in a paper-size warning}% \oentry{UScommercial9DW}{% - parameter set for US-American letters with paper size letter; suitable for - US-American window envelopes of size \emph{commercial~No.\,9} with - addressee's window width of 3\,5/8\Unit{in}, height of 1\,1/8\Unit{in}, - and position of 3/4\Unit{in} from the left and 1/2\Unit{in} from the - bottom, and with a sender's window width of 3\,1/2\Unit{in}, height of - 7/8\Unit{in}, and position of 5/16\Unit{in} from the left and - 2\,1/2\Unit{in} from the bottom, but without a sender's return address at - any of the windows; with folding it first at the puncher mark then at the - top folder mark also legal paper may be used but would result in a page - size warning}% + \leavevmode% + \IndexOption[indexmain]{UScommercial9DW}% + \IndexFile[indexmain]{UScommercial9DW.lco}% + parameters for US letters on American letter paper; suitable for + \emph{commercial~No.\,9} US window envelopes with an recipient-address + window 3\,5/8\Unit{in} wide by 1\,1/8\Unit{in} high, positioned + 3/4\Unit{in} from the left and 1/2\Unit{in} from the bottom, and with a + return-address window 3\,1/2\Unit{in} wide by 7/8\Unit{in} high, + positioned 5/16\Unit{in} from the left and 2\,1/2\Unit{in} from the + bottom; when folded first at the middle mark and then at the top fold + mark, legal paper can also be used but results in a paper-size warning}% \end{desclist} % \EndIndexGroup @@ -3020,182 +3211,183 @@ and \Package{keyval} packages.% \EndIndexGroup -\section{Address Files and Circular Letters} +\section{Address Files and Form Letters} \seclabel{addressFile}% \BeginIndexGroup \BeginIndex{}{address>file}% -\BeginIndex{}{circular letters}% -\index{serial letters|see circular letters}% +\BeginIndex{}{form letters}% +\index{serial letters|see form letters}% +\index{circular letters|see form letters}% -When people write circular letters one of the more odious tasks is the typing -of many different addresses. The class \Class{scrlttr2}% +One of the most annoying things about creating form letters is typing up +the different addresses. \KOMAScript{} provides basic support for this task% \iffalse% Umbruchkorrekturtext -, as did its predecessor \Class{scrlettr} as well,% +, as did its predecessor \Class{scrlettr}% \fi% -\ provides basic support for this task.% +.% \iffalse% Umbruchkorrekturtext -\ Currently there are plans for much enhanced support.% +\ Currently there are plans for greatly enhanced support.% \fi \begin{Declaration} - \Macro{adrentry}\Parameter{last-name}\Parameter{first-name}% + \Macro{adrentry}\Parameter{last~name}\Parameter{first~name}% \Parameter{address}\Parameter{phone}\Parameter{F1}\Parameter{F2}% \Parameter{comment}\Parameter{key} \end{Declaration}% -The class \Class{scrlttr2} supports the use of address files which -contain address entries, very useful for circular letters. The file -extension of the address file has to be \File{.adr}. Each entry is an -\Macro{adrentry} command with eight parameters, for example: +\Class{scrlttr2} and \Package{scrletter} can evaluate address files. +This can be very useful for form letters. An address file must have the +extension \File{.adr} and consists of a number \Macro{adrentry} entries. +An individual entry consists of eight parameters and may look, for example, +like this: \begin{lstcode} \adrentry{McEnvy} {Flann} - {Main Street 1\\ Glasgow} - {123 4567} - {male} + {1 High Street\\ Glasgow} + {0141 123 4567} + {builder} {} - {niggard} + {buys everything} {FLANN} \end{lstcode} -The 5\textsuperscript{th} and 6\textsuperscript{th} elements, \PValue{F1} and -\PValue{F2}, can be used freely: for example, for the gender, the academic -grade, the birthday, or the date on which the person joined a society. The -last parameter \PName{key} should only consist of more than one uppercase -letters in order to not interfere with existing {\TeX} or {\LaTeX} commands. +You can use the fifth and sixth elements, \PValue{F1} and \PValue{F2}, for +anything you want. Gender, academic grade, birth date, or the date the person +joined a society are all possibilities. The last parameter, \PName{key}, +should consist of more than one letter and be upper-case only so as not to +interfere with existing \TeX{} or \LaTeX{} commands. \begin{Example} - Mr McEnvy is one of your most important business partners, but - every day you receive correspondence from him. Before long you do - not want to bother typing his boring address again and again. Here - \Class{scrlttr2} can help. Assume that all your business partners - have an entry in your \File{partners.adr} address file. If you now - have to reply to Mr~McEnvy again, then you can save typing as - follows: + Mr McEnvy is one of your most important business partners. Since you + maintain a frequent correspondence with him, it is too tedious to + enter all his data again and again. \KOMAScript{} will do this work for you. + For example, if you have saved your customer contacts in the + \File{partners.adr} address file and you would like to write a letter to + Mr~McEnvy, you can save a great deal of effort by typing: \begin{lstcode} \input{partners.adr} \begin{letter}{\FLANN} Your correspondence of today \dots \end{letter} \end{lstcode} - Your {\TeX} system must be configured to have access to your address - file. Without access, the \Macro{input} command results in an - error. You can either put your address file in the same directory - where you are running {\LaTeX}, or configure your system to find the - file in a special directory. + Please make sure that your {\TeX} system can access your address file. + Otherwise the \Macro{input} command results in an error message. You can + either put your address file in the same directory as your letter or + configure your \TeX{} system to look for a dedicated address directory. \end{Example} % \EndIndexGroup + \begin{Declaration} \Macro{addrentry}\Parameter{last-name}\Parameter{first-name}% \Parameter{address}\Parameter{phone}\Parameter{F1}\Parameter{F2}% \Parameter{F3}\Parameter{F4}\Parameter{key} \end{Declaration}% -Over the years people have objected that the \DescRef{\LabelBase.cmd.adrentry} has only two -free parameters. To cater to this demand, there now exists a new command -called \Macro{addrentry}\,---\,note the additional ``d''\,---\,which supports -four freely-definable parameters. Since {\TeX} supports maximally nine -parameters per command, the comment parameter has fallen away. Other than this -difference, the use is the same as that of \DescRef{\LabelBase.cmd.adrentry}. - -Both \DescRef{\LabelBase.cmd.adrentry} and \Macro{addrentry} commands can be freely mixed in -the \File{adr} files. However, it should be noted that there are some packages -which are not suited to the use of \Macro{addrentry}. For example, the -\Package{adrconv} by Axel Kielhorn can be used to create address lists from -\File{adr} files, but it has currently no support for command -\Macro{addrentry}. In this case, the only choice is to extend the package -yourself.% +Before you object that a total of two free parameters is too few, +\KOMAScript{} alternatively offers the \Macro{addrentry} command\,---\,note +the additional ``d''\,---\,which adds two more freely definable parameters but +omits the comment parameter. Otherwise, you can use this command in exactly +the same way as \DescRef{\LabelBase.cmd.adrentry}. + +Both \DescRef{\LabelBase.cmd.adrentry} and \Macro{addrentry} commands can be +freely mixed in the \File{adr} files. I should note, however, that other +packages, such as \Package{adrconv}\IndexPackage{adrconv} by Axel Kielhorn, +may not be designed to use \Macro{addrentry}. If necessary, you have to create +the appropriate extensions yourself.% % \EndIndexGroup -Besides the simple access to addresses, the address files can be -easily used in order to write circular letters. Thus, there is no -requirement to access a complicated database system via {\TeX}. +In addition to simplifying access to addresses, you can also use the +\File{adr} files to create circulars or form letters. Thus you can create such +mass mailings without a complicated connection to a database system. % \begin{Example} - Suppose you are member of a society and want write an invitation for - the next general meeting to all members. + You want to sent a form letter to all members of your fishing club to invite + them to the next general meeting. \begin{lstcode} \documentclass{scrlttr2} \begin{document} \renewcommand*{\adrentry}[8]{ \begin{letter}{#2 #1\\#3} - \opening{Dear members,} Our next general meeting will be on - Monday, August 12, 2002. The following topics are \dots + \opening{Dear members,} + Our next general meeting will be on + Monday, 12 August 2002. + + The following topics are \dots \closing{Regards,} \end{letter} } \input{members.adr} \end{document} \end{lstcode} - If the address file contains \DescRef{\LabelBase.cmd.addrentry} commands too, than an - additional definition for \DescRef{\LabelBase.cmd.addrentry} is required before loading - the address file: + If the address file also contains \DescRef{\LabelBase.cmd.addrentry} + commands, you must add a corresponding definition before loading the address + file: \begin{lstcode} \renewcommand*{\addrentry}[9]{% \adrentry{#1}{#2}{#3}{#4}{#5}{#6}{#7}{#9}% } \end{lstcode} - In this simple example the extra freely-definable parameter is not - used, and therefore \DescRef{\LabelBase.cmd.addrentry} is defined with the help of + In this example, the extra freely-definable parameter is not used, and + therefore \DescRef{\LabelBase.cmd.addrentry} is defined using \DescRef{\LabelBase.cmd.adrentry}. \end{Example} -With some additional programming one can let the content of the -letters depend on the address data. For this the free parameters of -the \DescRef{\LabelBase.cmd.adrentry} and and \DescRef{\LabelBase.cmd.addrentry} commands can be used. - +Of course, the letter's contents can also be adapted to the characteristics of +the address data. You can use the free parameters of the +\DescRef{\LabelBase.cmd.adrentry} and \DescRef{\LabelBase.cmd.addrentry} +commands for this. \begin{Example} - Suppose the 5\textsuperscript{th} parameter of the \DescRef{\LabelBase.cmd.adrentry} - command contains the gender of a member (\PValue{m/f}), and the - 6\textsuperscript{th} parameter contains what amount of subscription - has not yet been paid by the member. If you would like to write a - more personal reminder to each such member, then the next example - can help you: + Suppose you use the fifth parameter of the \DescRef{\LabelBase.cmd.adrentry} + command to indicate the gender of a club member (\PValue{m/f}), and the + sixth parameter to indicate the amount of membership dues that is unpaid. + If you would like to write a reminder to each such member and address them + personally, the next example will help you: \begin{lstcode} \renewcommand*{\adrentry}[8]{ \ifdim #6pt>0pt\relax - % #6 is an amount greater than 0. - % Thus, this selects all members with due subscription. + % #6 is an amount (floating-point number) greater than 0. + % Thus, this selects all members owing dues. \begin{letter}{#2 #1\\#3} - \if #5m \opening{Dear Mr.\,#2,} \fi - \if #5f \opening{Dear Mrs.\,#2,} \fi + \if #5m \opening{Dear Mr #2,} \fi + \if #5f \opening{Dear Ms #2,} \fi - Unfortunately we have to remind you that you have - still not paid the member subscription for this - year. + Unfortunately, we have noticed that you are in arrears + with the payment of your membership fees. - Please remit EUR #6 to the account of the society. + Please remit the outstanding balance of \pounds #6 to the club + account. \closing{Regards,} \end{letter} \fi } \end{lstcode} \end{Example} -As you can see, the letter text can be made more personal by depending on -attributes of the letter's addressee. The number of attributes is only -restricted by number of two free parameters of the \DescRef{\LabelBase.cmd.adrentry} command, -or four free parameters of the \DescRef{\LabelBase.cmd.addrentry} command. +It is therefore possible to tailor the text of the letter to the specific +characteristics of the recipient and create the impression of a personal +letter. The extent of the customisation is only limited by the maximum number +of two free \DescRef{\LabelBase.cmd.adrentry} parameters and four free +\DescRef{\LabelBase.cmd.addrentry} parameters. \begin{Declaration} \Macro{adrchar}\Parameter{initial letter}% \Macro{addrchar}\Parameter{initial letter} \end{Declaration} -\Index[indexmain]{address>list}\Index[indexmain]{telephone list}% -As already mentioned above, it is possible to create address and telephone -lists using \File{adr} files. For that, the additional package -\Package{adrconv} by Axel Kielhorn (see \cite{package:adrconv}) is needed. -This package contains interactive {\LaTeX} documents which help to create -those lists. - -The address files have to be sorted already in order to obtain sorted -lists. It is recommended to separate the sorted entries at each different -initial letter of \PName{last name}. As a separator, the commands -\Macro{adrchar} and \Macro{addrchar} can be used. These commands will be -ignored if the address files are utilized in \Class{scrlettr2}. +\Index[indexmain]{address>list}\Index[indexmain]{telephone directory}% +It is possible to create address lists and telephone directories using +\File{adr} files. You also need the \Package{adrconv}\IndexPackage{adrconv} +package by Axel Kielhorn (see \cite{package:adrconv}). This package contains +interactive \LaTeX{} documents which make it easy to create such lists. + +The address files have to be sorted already in order to obtain sorted lists. +It is advisable to insert an \Macro{adrchar} or \Macro{addrchar} command +containing the initial letter of the \PName{last name} before the point in the +list where this letter changes. \Class{scrlettr2} and \Package{scrletter} will +ignore these commands. % \begin{Example} - Suppose you have the following short address file: + Suppose you have the following, rather tiny address file from which you + want to create an address book: \begin{lstlisting} \adrchar{A} \adrentry{Angel}{Gabriel} @@ -3210,9 +3402,16 @@ ignored if the address files are utilized in \Class{scrlettr2}. {+49~62\,03~1\,??\,??}{}{}{no angel at all} {KOMA} \end{lstlisting} - This address file can be treated with \File{adrdir.tex} of the - \Package{adrconv} package~\cite{package:adrconv}. - The result should look like this: + You can now process these entries using the \File{adrdir.tex} document from + \cite{package:adrconv}. One potential problem with this is that + \File{adrdir.tex} up to and including Version~1.3 uses both the obsolete + \Package{scrpage} package and obsolete font commands which \KOMAScript{} has + not supported for some time. If you receive an error message and cannot + install a newer version, you can find a listing of \File{adrdir.tex} which + indicates the changes necessary to avoid these errors at + \cite{https://komascript.de/node/2154} (in German). + + The result looks something like this: \begin{center} \setlength{\unitlength}{1mm} \begin{picture}(80,57) @@ -3237,15 +3436,15 @@ ignored if the address files are utilized in \Class{scrlettr2}. \qbezier(0,3)(10,6)(40,3)\qbezier(40,3)(60,0)(80,3) \end{picture} \end{center} - The letter in the page header is created by the \Macro{adrchar} - command. The definition can be found in \File{adrdir.tex}. + The letter in the header is generated by answering ``no'' to the + question ``Names in the header?'' See explanation in \File{adrdir.tex}. \end{Example} -More about the \Package{adrconv} package can be found in its -documentation. There you should also find information about whether the +You can find more about the \Package{adrconv}\IndexPackage{adrconv} package in +its documentation. There you should also find information about whether the current version of \Package{adrconv} supports the -\DescRef{\LabelBase.cmd.addrentry} and \Macro{addrchar} commands. Former -versions only know the commands \DescRef{\LabelBase.cmd.adrentry} and -\Macro{adrchar}.% +\DescRef{\LabelBase.cmd.addrentry} and \Macro{addrchar} commands. Previous +versions only recognised the \DescRef{\LabelBase.cmd.adrentry} and +\Macro{adrchar} commands.% % \EndIndexGroup % @@ -3253,6 +3452,7 @@ versions only know the commands \DescRef{\LabelBase.cmd.adrentry} and % \EndIndexGroup +\endinput %%% Local Variables: %%% mode: latex @@ -3261,6 +3461,3 @@ versions only know the commands \DescRef{\LabelBase.cmd.adrentry} and %%% ispell-local-dictionary: "en_GB" %%% TeX-master: "../guide" %%% End: - -% LocalWords: scrlttr simpleSwitchValues afteropening beforeopening Combinable -% LocalWords: locfield Hennig Kohm Foldmarks |