diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/koma-script/source-doc/english |
Initial commit
Diffstat (limited to 'macros/latex/contrib/koma-script/source-doc/english')
49 files changed, 33943 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/source-doc/english/Makefile b/macros/latex/contrib/koma-script/source-doc/english/Makefile new file mode 100644 index 0000000000..b418a621f7 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/Makefile @@ -0,0 +1,55 @@ +# ====================================================================== +# Makefile +# Copyright (c) Markus Kohm, 2002-2015 +# +# This file is part of the LaTeX2e KOMA-Script bundle. +# +# This work may be distributed and/or modified under the conditions of +# the LaTeX Project Public License, version 1.3c of the license. +# The latest version of this license is in +# http://www.latex-project.org/lppl.txt +# and version 1.3c or later is part of all distributions of LaTeX +# version 2005/12/01 or later and of this work. +# +# This work has the LPPL maintenance status "author-maintained". +# +# The Current Maintainer and author of this work is Markus Kohm. +# +# This work consists of all files listed in manifest.txt. +# ---------------------------------------------------------------------- +# Makefile +# Copyright (c) Markus Kohm, 2002-2015 +# +# Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +# Version 1.3c, verteilt und/oder veraendert werden. +# Die neuste Version dieser Lizenz ist +# http://www.latex-project.org/lppl.txt +# und Version 1.3c ist Teil aller Verteilungen von LaTeX +# Version 2005/12/01 oder spaeter und dieses Werks. +# +# Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +# (allein durch den Autor verwaltet). +# +# Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +# +# Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +# ====================================================================== + +# ---------------------------------------------------------------------- +# Directory with basics +BASEDIR ?= $(PWD)/../../ +DOCDIR = $(BASEDIR)doc/ +# language +LANGUAGE = english +LANGUAGESHORTCUT = en +LANGUAGELONG = english + +include $(DOCDIR)Makefile.guide + +# ---------------------------------------------------------------------- + +maintainclean_local: distclean_local + $(RM) guide.pdf $(GUIDENAME).pdf $(GUIDENAME).html + [ -L tocbasic.tex ] && $(RM) tocbasic.tex || true +# +# end of file `Makefile' diff --git a/macros/latex/contrib/koma-script/source-doc/english/adrconvnote.tex b/macros/latex/contrib/koma-script/source-doc/english/adrconvnote.tex new file mode 100644 index 0000000000..75b9b8f392 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/adrconvnote.tex @@ -0,0 +1,99 @@ +% ====================================================================== +% adrconvnote.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% adrconvnote.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about adrconv of the KOMA-Script guide +% Maintained by Jens-Uwe Morawski (with help from Markus Kohm) +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber adrconv in der KOMA-Script-Anleitung +% Verwaltet von Jens-Uwe Morawski (mit Unterstuetzung von Markus Kohm) +% +% ====================================================================== + +\KOMAProvidesFile{adrconvnote.tex} + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (chapter: adrconv)] + +\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm\and + Karl Hagen} + +% Date of the translated German file: 2018-01-29 + +\chapter{Creating Address Files from an Address Database}% +\labelbase{addrconv}% +\Index{address>file}% +\Index{address>database}% +\IndexPackage{addrconv} + +In previous versions of \KOMAScript{}, the \Package{addrconv} package was an +integral part of the \KOMAScript{} system. The main connection to +\KOMAScript{} was that with the help of this package, it was possible to +create address files compatible with the \KOMAScript{} letter class or with +the \Package{scraddr} package from an address database in \BibTeX{} format. + +\begin{lstlisting}[morekeywords={@address}] + @address{HMUS, + name = {Carl McExample}, + title = {Dr.}, + city = {Anywhere}, + zip = 01234, + country = {Great Britain}, + street = {A long Road}, + phone = {01234 / 5 67 89}, + note = {always forget his birthday}, + key = {HMUS}, + } +\end{lstlisting} + +From entries such as the one above, you can use \BibTeX{} and various +{\BibTeX} styles to create address files. There are also some special \LaTeX{} +files that make it possible to create various telephone and address lists from +the address files. + +However, the \Package{addrconv} package was actually an independent package, +including features beyond what is required for \KOMAScript{}. That is why +\Package{addrconv} has not been included in \KOMAScript{} for some time. The +\Package{adrconv} package, with a single \emph{d}, entirely replaces +\Package{addrconv}. If it is not included in your \TeX{} distribution, you can +download it from \cite{package:adrconv} and install it separately. + +%%% Local Variables: +%%% mode: latex +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/authorpart.tex b/macros/latex/contrib/koma-script/source-doc/english/authorpart.tex new file mode 100644 index 0000000000..37b4d7bc8a --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/authorpart.tex @@ -0,0 +1,80 @@ +% ====================================================================== +% authorpart.tex +% Copyright (c) Markus Kohm, 2002-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% authorpart.tex +% 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. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% First part: KOMA-Script for Authors +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Erster Teil: KOMA-Script fuer Autoren +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\ProvidesFile{authorpart.tex}[2012/04/02 Part KOMA-Script for Authors] +\translator{Markus Kohm\and Krickette Murabayashi\and Karl Hagen} + +\setpartpreamble{% + \vspace*{2\baselineskip}% + \setlength{\parindent}{1em}% + + \noindent This part provides information for writers of articles, reports, + books, and letters. The average user is probably less interested in how + things are implemented in \KOMAScript{} and what pitfalls exist. Also, + normal users aren't interested in obsolete options and instructions. They + want to know how to achieve things using current options and instructions, + and perhaps in some background information about typography. + + The few passages in this part which contain extra information and + explanations that may be of less interest for the impatient reader are set + in a sans-serif typeface and can be skipped if desired. For those who are + interested in more information about the implementation, side-effects with + other packages, or obsolete options and instructions, please refer to + \autoref{part:forExperts} beginning on \autopageref{part:forExperts}. That + part of the \KOMAScript{} guide also describes all the features that were + created specially for authors of packages and classes.% +} + +\part{\KOMAScript{} for Authors\label{part:forAuthors}} + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% coding: us-ascii +%%% TeX-master: "guide.tex" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-compatibility.tex b/macros/latex/contrib/koma-script/source-doc/english/common-compatibility.tex new file mode 100644 index 0000000000..bed043d8d3 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-compatibility.tex @@ -0,0 +1,197 @@ +% ====================================================================== +% common-compatibility.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-compatibility.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-compatibility.tex} + [$Date: 2018-02-28 13:23:23 +0100 (Wed, 28 Feb 2018) $ + KOMA-Script guide (common paragraphs)] +\translator{Markus Kohm\and Krickette Murabayashi\and Karl Hagen} + +% Date of the translated German file: 2018-01-30 + +\section{Compatibility with Earlier Versions of \KOMAScript} +\seclabel{compatibilityOptions} +\BeginIndexGroup +\BeginIndex{}{Compatibility} + +\IfThisCommonFirstRun{}{% + The information in + \autoref{sec:\ThisCommonFirstLabelBase.compatibilityOptions} applies equally + to this chapter. + \IfThisCommonLabelBase{scrlttr2}{However, this feature has existed in + \Class{scrlttr2} since version~2.9t, whereas \Package{scrletter} does not + offer it. }{}% + So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.compatibilityOptions} you can skip + ahead to \autopageref{sec:\ThisCommonLabelBase.compatibilityOptions.next}, + \autopageref{sec:\ThisCommonLabelBase.compatibilityOptions.next}.% +} + +\IfThisCommonLabelBaseOneOf{typearea,maincls,scrlttr2,scrextend}{% + Those who produce their documents from source code typically attach the + utmost importance to the fact that future \LaTeX{} runs will yield exactly + the same result. In some cases, however, improvements and bug fixes to the + \IfThisCommonLabelBaseOneOf{maincls,scrlttr2}{class}{package} will + result in changes of behaviour, especially to the layout. This, however, + may be undesirable.% +}{% + % \IfThisCommonLabelBase{scrextend}{% + % In some cases, improvements and bug fixes to the package will result + % in changes of behaviour, especially to the layout. This, however, + % may be undesirable. Those who produce their documents from source code + % typically attach the utmost importance to the fact that future + % \LaTeX{} runs will yield exactly the same result.% + % }{% + \ThisCommonLabelBaseFailure + % \IfThisCommonLabelBase{scrlttr2}{% + % In some cases, improvements and bug fixes to the package will result + % in changes of behaviour, especially to the layout. This, however, + % may be undesirable. + % }{}% + % }% +}% + + +\begin{Declaration} + \OptionVName{version}{value}% + \OptionValue{version}{first}% + \OptionValue{version}{last} +\end{Declaration} +%\ChangedAt{v2.96a}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% +%\ChangedAt{v2.9t}{\Class{scrlttr2}}% +%\ChangedAt{v3.01b}{\Package{typearea}}% +\IfThisCommonLabelBase{scrextend}{With \Package{scrextend}, you can}{Since + \IfThisCommonLabelBase{typearea}{% + Version~3.01b, \Package{typearea}\ChangedAt{v3.01b}{\Package{typearea}}}{% + \IfThisCommonLabelBase{maincls}{% + Version~2.96a, \KOMAScript{}\ChangedAt{v2.96a}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}}{% + \IfThisCommonLabelBase{scrlttr2}{% + Version~2.9t, \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}}% + \ChangedAt{v2.9t}{\Class{scrlttr2}}}{% + \InteralCommonFileUsageError}% + }% + }% +\ has been able to } +choose whether the source file should, as much as possible, +continue to produce exactly the same result within a \LaTeX{} run or should +be formatted according to the modifications of the latest version% +\IfThisCommonLabelBaseOneOf{maincls,scrlttr2}{ of the class}{}. You +can specify the version with which you want your file to be compatible by +using the \Option{version} option. Compatibility with the oldest supported +\KOMAScript{} version can be achieved with +\OptionValue{version}{first}\important{\OptionValue{version}{first}} or +\OptionValue{version}{2.9} or \OptionValue{version}{2.9t}. Setting +\PName{value} to an unknown release number will result in a warning message +and selects \OptionValue{version}{first} for safety. + +With \OptionValue{version}{last}\important{\OptionValue{version}{last}}% +\textnote{default}, you can select the latest version. In this case, you give +up backwards compatibility. If the option is used without a value, +\PValue{last} is assumed. This\ChangedAt{v3.01a}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}\and \Class{scrlttr2}\and + \Package{scrextend}} also corresponds to the default setting, as long as you +do not use any deprecated options. + +\IfThisCommonLabelBase{scrextend}{% scrextend doesn't recognize obsolete options +}{% + If\textnote{Attention!} you use a deprecated option of \KOMAScript~2, + \KOMAScript~3 will switch to \OptionValue{version}{first} automatically. + This will also result in a warning message that explains how to prevent + this switch. Alternatively, you can choose a different setting for + \Option{version} with the desired compatibility after the deprecated + option.% +} + +Compatibility is primarily a question of line and page breaks (wrapping). If +you choose compatibility with an older version, new options that do not affect +wrapping are still available. The \Option{version} option does not affect any +wrapping changes that are the result of fixing unambiguous errors. +If\textnote{Hint!} you need unconditional wrapping compatibility even in the +case of bugs, you should physically save the old \KOMAScript{} version you +need together with your document. + +\IfThisCommonLabelBase{scrlttr2}{% + \begin{Example} + The example letters in this chapter should use all the features of the + latest version of \KOMAScript{}. For this, the we set the compatibility + correspondingly when loading the class:% + \lstinputcode[xleftmargin=1em,lastline=1]{letter-0.tex}% + In this case the symbolic value \PValue{last} has been used to select the + latest version.% + \iftrue% Umbruchkorrektur + Here, the latest version was simply chosen with the symbolic value + \PValue{last}.% + \else% + In order not to have to specify a new version number for each new version, + the symbolic value \PValue{last} was chosen here.% + \fi + \end{Example}}{} + +Note\textnote{Attention!} that you cannot change the \Option{version} option +after loading the % +\IfThisCommonLabelBaseOneOf{maincls,scrlttr2}{class}{% + \IfThisCommonLabelBase{typearea}{\Package{typearea}}{% + \IfThisCommonLabelBase{scrextend}{\Package{scrextend}}{% + \InternalCommonFileUsageError }% + }% +\ package}. Setting this option with +\DescRef{\ThisCommonLabelBase.cmd.KOMAoptions} or +\DescRef{\ThisCommonLabelBase.cmd.KOMAoption} will +therefore cause an error.% +\EndIndexGroup +% +\EndIndexGroup + +\phantomsection +\label{sec:\ThisCommonLabelBase.compatibilityOptions.end} +\endinput + +%%% Local Variables: +%%% mode: latex +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-dictum.tex b/macros/latex/contrib/koma-script/source-doc/english/common-dictum.tex new file mode 100644 index 0000000000..5dff550ac7 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-dictum.tex @@ -0,0 +1,260 @@ +% ====================================================================== +% common-dictum.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-dictum.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-dictum.tex} + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (common paragraphs)] +\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi\and + Karl Hagen} + +% Date of the translated German file: 2018-01-29 + +\section{Dicta} +\seclabel{dictum}% +\BeginIndexGroup +\BeginIndex{}{saying}% +\BeginIndex{}{dictum}% +\BeginIndex{}{epigraph}% + +\IfThisCommonFirstRun{}{% + The information in \autoref{sec:\ThisCommonFirstLabelBase.dictum} applies + equally to this chapter. % + \IfThisCommonLabelBase{scrextend}{% + However, \Package{scrextend} does not support the commands + \DescRef{maincls.cmd.setchapterpreamble} and + \DescRef{maincls.cmd.setpartpreamble}. + \iftrue% Umbruchvariante + Whether the class you are using offers an equivalent instruction + can be found in the documentation for the respective class .% + \fi% + }{}% + So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.dictum}, you can skip ahead to + \autoref{sec:\ThisCommonLabelBase.dictum.next}, + \autopageref{sec:\ThisCommonLabelBase.dictum.next}.% +}{}% + +\IfThisCommonLabelBase{scrextend}{% Umbruchkorrekturvarianten + A common element in a document is an epigraph or quotation that is set above + or below a chapter or section heading, typically right-justified. The + epigraph and its source are usually specially formatted.% +}{% + A common element in a document is an epigraph or quotation that is set above + or below a chapter or section heading, along with a reference to the source + and its own formatting.% +} % +\KOMAScript{} refers to such an epigraph as a \emph{dictum}. + +\begin{Declaration} + \Macro{dictum}\OParameter{author}\Parameter{text}% + \Macro{dictumwidth}% + \Macro{dictumauthorformat}\Parameter{author}% + \Macro{dictumrule}% + \Macro{raggeddictum}% + \Macro{raggeddictumtext}% + \Macro{raggeddictumauthor} +\end{Declaration}% +You can set such a saying with the help of the \Macro{dictum} command. % +\IfThisCommonLabelBase{maincls}{% + This\textnote{Hint!} macro can be included in the mandatory argument of + either the \DescRef{maincls.cmd.setchapterpreamble} or the + \DescRef{maincls.cmd.setpartpreamble} command. However, this is not + obligatory.\par% +}{}% +The dictum, along with an optional \PName{author}, is inserted in a +\Macro{parbox}\IndexCmd{parbox} (see \cite{latex:usrguide}) of width +\Macro{dictumwidth}. However, \Macro{dictumwidth} is not a length which can be +set with \Macro{setlength}. It is a macro that can be redefined using +\Macro{renewcommand}. The default is \PValue{0.3333\Length{textwidth}}, which +is one third of the text width. The box itself is aligned with the command +\Macro{raggeddictum}. The default is \Macro{raggedleft}\IndexCmd{raggedleft}, +that is, right justified. \Macro{raggeddictum} can be redefined +with \IfThisCommonLabelBase{scrextend}{% Umbruchoptimierung +}{the help of }\Macro{renewcommand}. + +You can align the \PName{dictum} within the box using +\Macro{raggeddictumtext}\important{\Macro{raggeddictumtext}}. +The default is \Macro{raggedright}\IndexCmd{raggedright}, that is, left +justified. You can also redefine this macro with \Macro{renewcommand}.% +\BeginIndexGroup +\BeginIndex{FontElement}{dictum}\LabelFontElement{dictum}% +\LabelFontElement{dictumtext}% +The output uses the default font setting for the element +\FontElement{dictum}\important{\FontElement{dictum}}, which can be changed +with the commands \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} (see +\autoref{sec:\ThisCommonLabelBase.textmarkup}, +\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}). Default settings are +listed in \autoref{tab:maincls.dictumfont}% +\IfThisCommonFirstRun{.% + \begin{table} +% \centering% + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% +% \caption + \begin{captionbeside}{Default settings for the elements of a dictum} + [l] + \begin{tabular}[t]{ll} + \toprule + Element & Default \\ + \midrule + \DescRef{\LabelBase.fontelement.dictum} & + \Macro{normalfont}\Macro{normalcolor}\Macro{sffamily}\Macro{small}\\ + \DescRef{\LabelBase.fontelement.dictumauthor} & + \Macro{itshape}\\ + \bottomrule + \end{tabular} + \end{captionbeside} + \label{tab:\ThisCommonLabelBase.dictumfont} + \end{table} +}{% + , \autopageref{tab:\ThisCommonFirstLabelBase.dictumfont}.% +} +\EndIndexGroup + +If an \PName{author} is defined, it is separated from the \PName{dictum} by +a horizontal rule spanning the full width of the \Macro{parbox}. This% +\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrextend}{% + \ChangedAt{v3.10}{\Package{scrextend}}% + }{\InternalCommonFileUsageError}% +} % +rule is defined in \Macro{dictumrule}\important{\Macro{dictumrule}} as a +vertical object with +\begin{lstcode} + \newcommand*{\dictumrule}{\vskip-1ex\hrulefill\par} +\end{lstcode} + +The \Macro{raggeddictumauthor}\important{\Macro{raggeddictumauthor}} command +defines the alignment for the rule and the \PName{author}. The default is +\Macro{raggedleft}. This command can also be redefined using +\Macro{renewcommand}. The format is defined with +\Macro{dictumauthorformat}\important{\Macro{dictumauthorformat}}. This macro +expects the \PName{author} text as its argument. By default +\Macro{dictumauthorformat} is defined as +\begin{lstcode} + \newcommand*{\dictumauthorformat}[1]{(#1)} +\end{lstcode} +Thus the \PName{author} is set enclosed in rounded parentheses. +\BeginIndexGroup +\BeginIndex{FontElement}{dictumauthor}\LabelFontElement{dictumauthor}% +For the \FontElement{dictumauthor}\important{\FontElement{dictumauthor}} +element, you can define a different font than that used for the +\DescRef{\LabelBase.fontelement.dictum} element. The default settings are +listed in \autoref{tab:maincls.dictumfont}. Changes can be made using the +\DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see +\autoref{sec:\ThisCommonLabelBase.textmarkup}, +\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}).% +\EndIndexGroup + +\IfThisCommonLabelBase{maincls}{% + If you use \Macro{dictum} within the + \DescRef{maincls.cmd.setchapterpreamble} or + \DescRef{maincls.cmd.setpartpreamble} macro, you must ensure that + the horizontal positioning is always done with + \Macro{raggeddictum}. Therefore, the optional argument for horizontal + positioning which is implemented for these two commands has no effect. + \Length{textwidth} is not the width of the whole text body but the + current text width. If \Macro{dictumwidth} is set to + \PValue{.5\Length{textwidth}} and \DescRef{maincls.cmd.setchapterpreamble} + has an optional width of \PValue{.5\Length{textwidth}} too, you will get a + box with a width one quarter of the text width. Therefore, if you use + \Macro{dictum} you should refrain from setting the optional width for + \DescRef{maincls.cmd.setchapterpreamble} or + \DescRef{maincls.cmd.setpartpreamble}. + + If\textnote{Hint!} you have more than one dictum, one under another, you + should separate them by an additional vertical space, which is easily + accomplished using the \Macro{bigskip}\IndexCmd{bigskip} command.% + \iftrue% +}{\csname iffalse\endcsname} + + \begin{Example} + You are writing a chapter about modern marriage, and you want to place a + dictum in the preamble to the chapter heading. You write: +\begin{lstcode} + \setchapterpreamble[u]{% + \dictum[Schiller]{So pause ye who would link your fates~\dots}} + \chapter{Modern Marriage} +\end{lstcode} + The output would look as follows: + \begin{ShowOutput} + {\usekomafont{disposition}\usekomafont{chapter}% + 17\enskip Modern Marriage\par} \vspace{\baselineskip} + \dictum[Schiller]{So pause ye who would link + your fates~\dots} + \end{ShowOutput} + + If you want the dictum to span only a quarter of the text width + rather than a third, you can redefine \Macro{dictumwidth} this way: +\begin{lstcode} + \renewcommand*{\dictumwidth}{.25\textwidth} +\end{lstcode} +\end{Example} + +\IfThisCommonLabelBase{maincls}{}{% Umbruchkorrekturtext + At this point, note the \Package{ragged2e}\important{\Package{ragged2e}}% + \IndexPackage{ragged2e} package, with which you can produce unjustified text + that uses hyphenation (see \cite{package:ragged2e}).% +}% +\fi +% +\EndIndexGroup +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-draftmode.tex b/macros/latex/contrib/koma-script/source-doc/english/common-draftmode.tex new file mode 100644 index 0000000000..383c9236c5 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-draftmode.tex @@ -0,0 +1,129 @@ +% ====================================================================== +% common-draftmode.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-draftmode.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-draftmode.tex} + [$Date: 2018-02-28 13:23:23 +0100 (Wed, 28 Feb 2018) $ + KOMA-Script guide (common paragraphs)] +\translator{Markus Kohm\and Gernot Hassenpflug\and Krickette Murabayashi\and + Karl Hagen} + +% Date of the translated German file: 2018-01-30 + +\section{Draft Mode} +\seclabel{draft}% +\BeginIndexGroup +\BeginIndex{}{draft mode}% + +\IfThisCommonFirstRun{}{% + The information in \autoref{sec:\ThisCommonFirstLabelBase.draft} applies + equally to \IfThisCommonLabelBase{scrlttr2}{\Class{scrlttr2}% + \OnlyAt{\Class{scrlttr2}}}{this chapter}. So if you have already read + and understood \autoref{sec:\ThisCommonFirstLabelBase.draft}, you can skip + ahead to \autoref{sec:\ThisCommonLabelBase.draft.next} on + \autopageref{sec:\ThisCommonLabelBase.draft.next}.% + \IfThisCommonLabelBase{scrlttr2}{ The \Package{scrletter} package does not + provide a draft mode itself but relies upon the class you use.}{}% +} + +Many classes and packages provide a draft mode in addition to the normal +typesetting mode. The differences between these two are as diverse as +the classes and packages that offer this distinction.% +\IfThisCommonLabelBase{scrextend}{% Umbruchkorrekturtext + \ The draft mode of some packages also results in changes to the output + that affect the document's layout. This is not the case with + \Package{scrextend}.% +}{} + +\begin{Declaration} + \OptionVName{draft}{simple switch} + \OptionVName{overfullrule}{simple switch} +\end{Declaration}% +The \Option{draft}\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrartcl}\and + \Class{scrreprt}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.00}{\Class{scrlttr2}}\OnlyAt{\Class{scrlttr2}}% + }{}% +} option distinguishes between documents being drafted and finished +documents\Index{final version}. The \PName{simple switch} can be one of the +standard values for simple switches from \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch}. If you activate this +option\important{\OptionValue{draft}{true}}, small black boxes will be output +at the end of overly long lines. These boxes make it easier for the untrained +eye to locate the paragraphs that require manual post-processing. By contrast, +the default, \OptionValue{draft}{false}, shows no such boxes. Incidentally, +such lines often disappear when you use the +\Package{microtype}\IndexPackage{microtype}\important{\Package{microtype}} +package \cite{package:microtype}. + +Since\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.25}{\Class{scrbook}\and \Class{scrartcl}\and + \Class{scrreprt}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.25}{\Class{scrlttr2}}% + }{% + \IfThisCommonLabelBase{scrextend}{% + \ChangedAt{v3.25}{\Package{scrextend}}% + }{}% + }% +} the \Option{draft} option can lead to all sorts of unwanted effects with +various packages, \KOMAScript{} allows you to control this marking of overly +long lines separately with the +\Option{overfullrule}\important{\OptionValue{overfullrule}{true}} option. If +this option is enabled, the marker is again displayed.% +% +\EndIndexGroup +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-fontsize.tex b/macros/latex/contrib/koma-script/source-doc/english/common-fontsize.tex new file mode 100644 index 0000000000..843f9482f2 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-fontsize.tex @@ -0,0 +1,188 @@ +% ====================================================================== +% common-fontsize.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-fontsize.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-fontsize.tex} + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (common paragraphs: fontsize)] +\translator{Markus Kohm\and Krickette Murabayashi\and Karl Hagen} + +% Date of the translated German file: 2017-12-13 + +\section{Choosing the Document Font Size} +\seclabel{fontOptions}% +\BeginIndexGroup +\BeginIndex{}{font>size}% + +\IfThisCommonFirstRun{% + The main font and its size are central elements in the design of a document. + As stated in \autoref{cha:typearea}, the division of the page into the text + area and the margins fundamentally depends on them. The main font is the one + that is used for most of the text in a document. All variations, whether in + shape, thickness, slant, or size, are related to the main font.% +}{% + The information in \autoref{sec:\ThisCommonFirstLabelBase.fontOptions} + applies equally to + \IfThisCommonLabelBase{scrlttr2}{\Class{scrlttr2}\OnlyAt{scrlttr2}}% + {this chapter}. \IfThisCommonLabelBase{scrlttr2}{By contrast, the + \Package{scrletter} package by itself does not offer font-size selection + but depends completely on the class you use.}{} So if you have already + read and understood \autoref{sec:\ThisCommonFirstLabelBase.fontOptions}, you + can \IfThisCommonLabelBase{scrlttr2}{continue to + \autopageref{sec:\ThisCommonLabelBase.fontOptions.end} at the end of this + section. If you use \Package{scrletter}, you can }{}% + skip directly to \autoref{sec:\ThisCommonLabelBase.fontOptions.next}, + \autopageref{sec:\ThisCommonLabelBase.fontOptions.next}.% +} + +\begin{Declaration} + \OptionVName{fontsize}{size} +\end{Declaration} +While\IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{% + \textnote{\KOMAScript{} vs. standard classes}} the standard classes support +only a very limited number of font sizes, +\IfThisCommonLabelBase{scrlttr2}{\Class{scrlttr2}}{\KOMAScript} provides the +ability to specify any \PName{size} for the main font. You can also use any +known \TeX unit as a unit for the \PName{size}. If the \PName{size} is +specified without a unit, it is assumed to be \PValue{pt}.\iffree{}{ The exact + procedure for setting the font size is documented for experts and interested + users in \autoref{sec:maincls-experts.addInfos}, + \DescPageRef{maincls-experts.option.fontsize}.} + +If you set the option within the document, the main font size and the +dependent font sizes of the commands \Macro{tiny}, \Macro{scriptsize}, +\Macro{footnotesize}, \Macro{small}, \Macro{normalsize}, \Macro{large}, +\Macro{Large}, \Macro{LARGE}, \Macro{huge} and \Macro{Huge} are changed. This +can be useful, for example, if you want % +\IfThisCommonLabelBase{scrlttr2}{another letter }{the appendix }% +to be set in a smaller font size. + +Note\textnote{Attention!} that using this option after +\IfThisCommonLabelBase{scrextend}{potentially loading + \hyperref[cha:typearea]{\Package{typearea}}\IndexPackage{typearea}% + \important{\hyperref[cha:typearea]{\Package{typearea}}}}{loading the class} +does not automatically recalculate the type area and margins (see +\DescRef{typearea.cmd.recalctypearea}\IndexCmd{recalctypearea}, +\autoref{sec:typearea.typearea}, +\DescPageRef{typearea.cmd.recalctypearea}). However, if this recalculation is +performed, it will be based on the current main font size. The effects of +changing the main font size upon other loaded packages or the class used +depends on these packages and on the class. \IfThisCommonLabelBase{maincls}{% + This means that you can encounter errors which are not the fault of + \KOMAScript, and even the \KOMAScript{} classes themselves do not + recalculate all lengths if the main font size changes after loading the + class.% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + You can encounter errors which are not the fault of \KOMAScript{}, and + further, the \Class{scrlttr2} class itself does not recalculate all + lengths if the main font size changes after loading the class.% + }{% + This means that you can encounter errors which are not the fault of + \KOMAScript{}.% + }% +}% + +This\textnote{Attention!} option should by no means be misinterpreted as a +substitute for \Macro{fontsize} (see \cite{latex:fntguide}). Also, you should +not use it in place of one of the font size commands that are relative to the +main font, from \Macro{tiny} to \Macro{Huge}. +\IfThisCommonLabelBase{scrlttr2}{% + For \Class{scrlttr2} the default is \OptionValue{fontsize}{12pt}. + + \begin{Example} + \phantomsection\label{sec:\ThisCommonLabelBase.fontOptions.end}% + Suppose the organization in the sample letter is the \emph{``Friends of + Noxious Font Sizes''}, for which reason it should be set in 14\Unit{pt} + instead of 12\Unit{pt}. You can achieve this by making a small change to + the first line:% + \lstinputcode[xleftmargin=1em]{letter-6}% + Alternatively, the option could be set as an optional argument to + \DescRef{\LabelBase.env.letter}: + \lstinputcode[xleftmargin=1em]{letter-5}% + Since the text area is not recalculated in this late change of the font + size, the two results differ in \autoref{fig:scrlttr2.letter-5-6}. + \begin{figure} + \centering + \frame{\includegraphics[width=.4\textwidth]{letter-5}}\quad + \frame{\includegraphics[width=.4\textwidth]{letter-6}} + \caption[{Example: letter with address, salutation, text, closing phrase, + postscript, enclosures, distribution list, and noxiously large font + size}] + {result of a short letter with recipient, opening, text, closing, + postscript, enclosures, distribution list, and a noxiously large font + (the date is set by default): in the left-hand version, the font size + has been defined by the optional argument of + \DescRef{\LabelBase.env.letter}; in the right-hand one, the optional + argument of \DescRef{\LabelBase.cmd.documentclass} has been used} + \label{fig:scrlttr2.letter-5-6} + \end{figure} + \end{Example} +}{% + \IfThisCommonLabelBase{maincls}{% + \par + \phantomsection\label{sec:\ThisCommonLabelBase.fontOptions.end}% + The default for \Class{scrbook}, \Class{scrreprt}, and \Class{scrartcl} is + \OptionValue{fontsize}{11pt}.\textnote{\KOMAScript{} vs. standard classes} + In contrast, the default size in the standard classes is \Option{10pt}. + You may need to account for this difference if you switch from a standard + class to a \KOMAScript{} class\iffree{}{ or when using the + \DescRef{maincls-experts.option.emulatestandardclasses}% + \IndexOption{emulatestandardclasses} option}.% + }{}% +}% +% +\EndIndexGroup +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-footnotes.tex b/macros/latex/contrib/koma-script/source-doc/english/common-footnotes.tex new file mode 100644 index 0000000000..c08b203b29 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-footnotes.tex @@ -0,0 +1,626 @@ +% ====================================================================== +% common-footnotes.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-footnotes.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-footnotes.tex} + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (common paragraphs: Footnotes)] +\translator{Markus Kohm\and Krickette Murabayashi\and Karl Hagen} + +% Date of the translated German file: 2018-01-29 + +\section{Footnotes} +\seclabel{footnotes}% +\BeginIndexGroup +\BeginIndex{}{footnotes}% + +\IfThisCommonFirstRun{}{% + The information in \autoref{sec:\ThisCommonFirstLabelBase.footnotes} applies + equally to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.footnotes}, you can skip ahead to + \autopageref{sec:\ThisCommonLabelBase.footnotes.next}, + \autopageref{sec:\ThisCommonLabelBase.footnotes.next}.% + \IfThisCommonLabelBase{scrlttr2}{ % + If you do not use a \KOMAScript{} class, \Package{scrletter}% + \OnlyAt{\Package{scrletter}} relies on the + \hyperref[cha:scrextend]{\Package{scrextend}}\IndexPackage{scrextend}% + \important{\hyperref[cha:scrextend]{\Package{scrextend}}} package. + Therefore, see also \autoref{sec:scrextend.footnotes}, + \autopageref{sec:scrextend.footnotes} when using \Package{scrletter}.% + \iffalse% Umbruchkorrekturtext + \ Note in particular that in this case some typical \KOMAScript{} + extensions are not active by default\textnote{default}. Instead, the + footnotes make use of the class used, or the \LaTeX{} kernel.% + \fi% + }{}% +} + +\IfThisCommonLabelBase{maincls}{% + Unlike\textnote{\KOMAScript{} vs. standard classes} the standard classes, + \KOMAScript{} offers the ability to configure the format of the footnote + block.% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + You can find the basic commands to set footnotes in any introduction to + \LaTeX, for example \cite{lshort}. \KOMAScript{}% + \textnote{\KOMAScript{} vs. standard classes} provides additional features + to change the format of the footnote block. % + \iffalse % Umbruchoptimierung + + Whether footnotes should be allowed for letters depends very much on the + type of letter and its layout. For example, you should not allow + footnotes to overlap visually with the letterhead footer or be confused + with the courtesy-copy list. Doing so is the responsibility of the + user.% + + Since footnotes are rarely used in letters, examples in this section have + been omitted. If you need examples, you can find them in + \autoref{sec:\ThisCommonFirstLabelBase.footnotes}, + \autopageref{sec:\ThisCommonFirstLabelBase.footnotes}.% + \fi% + }{% + \IfThisCommonLabelBase{scrextend}{% + The footnote capabilities of the \KOMAScript{} classes are also + provided by \Package{scrextend}. By default, the formatting of + footnotes is left to the class used. This changes as soon as you + issue the \DescRef{\ThisCommonLabelBase.cmd.deffootnote} command, + which is explained in detail on + \DescPageRef{\ThisCommonLabelBase.cmd.deffootnote}. + + The options for adjusting the dividing line above footnotes, however, + are not provided by \Package{scrextend}.% + }{\InternalCommonFileUsageError}% + }% +}% + +\begin{Declaration} + \OptionVName{footnotes}{setting} + \Macro{multfootsep} +\end{Declaration} +\IfThisCommonLabelBase{scrextend}{Many classes mark footnotes }{% + Footnotes % + \IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + }{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.00}{\Class{scrlttr2}}% + }{}% + }% + are marked % +}% +by default in the text with a small superscript number. If several footnotes +appear in succession at the same point, it gives the impression that there is +one footnote with a large number rather than multiple footnotes (e.\,g. +footnote 12 instead of footnotes 1 and 2). +With\important{\OptionValue{footnotes}{multiple}} +\OptionValue{footnotes}{multiple}\IndexOption{footnotes=~multiple}, footnotes +that follow each other directly are separated with a delimiter instead. The +default delimiter in \Macro{multfootsep}\important{\Macro{multfootsep}} is +defined as a comma without a space: +\begin{lstcode} + \newcommand*{\multfootsep}{,} +\end{lstcode} +This can be redefined. + +The whole mechanism is compatible with the +\Package{footmisc}\IndexPackage{footmisc}\important{\Package{footmisc}} +package, version~5.3d to 5.5b (see \cite{package:footmisc}). It affects +footnote markers placed using +\DescRef{\ThisCommonLabelBase.cmd.footnote}\IndexCmd{footnote}, as well as +those placed directly with +\DescRef{\ThisCommonLabelBase.cmd.footnotemark}\IndexCmd{footnotemark}. + +You can switch back to the default +\OptionValue{footnotes}{nomultiple} at any time using the +\DescRef{\ThisCommonLabelBase.cmd.KOMAoptions} or +\DescRef{\ThisCommonLabelBase.cmd.KOMAoption} command. However, if you +encounter any problems using another package that alters the footnotes, you +should not use this option, nor should you change the \PName{setting} anywhere +inside the document. + +A summary of the available \PName{setting} values of \Option{footnotes} can +be found in \autoref{tab:\ThisCommonFirstLabelBase.footnotes}% +\IfThisCommonFirstRun{% + . + \begin{table} + \caption[{Available values for the \Option{footnotes} option}] + {Available values for the \Option{footnotes} option to configure footnotes} + \label{tab:\ThisCommonLabelBase.footnotes} + \begin{desctabular} + \pventry{multiple}{% + Consecutive footnote marks will be separated by + \DescRef{\ThisCommonLabelBase.cmd.multfootsep}\IndexCmd{multfootsep}.% + \IndexOption{footnotes~=\textKValue{multiple}}}% + \pventry{nomultiple}{% + Consecutive footnote marks will be handled like single footnotes + and not separated from each other.% + \IndexOption{footnotes~=\textKValue{nomultiple}}}% + \end{desctabular} + \end{table}% +}{, + \autopageref{tab:\ThisCommonFirstLabelBase.footnotes}.% +}% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{footnote}\OParameter{number}\Parameter{text}% + \Macro{footnotemark}\OParameter{number}% + \Macro{footnotetext}\OParameter{number}\Parameter{text}% + \Macro{multiplefootnoteseparator}% +\end{Declaration}% +Footnotes in \KOMAScript{} are produced, as they are in the standard classes, +with the \Macro{footnote} command, or alternatively the pair of commands +\Macro{footnotemark} and \Macro{footnotetext}. As in the standard classes, +it is possible for a page break to occur within a footnote. Normally this +happens if the footnote mark is placed so near the bottom of a page as to +leave \LaTeX{} no choice but to move the footnote to the next page. +Unlike\textnote{\KOMAScript{} vs. standard classes} +\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.00}{\Class{scrlttr2}}% + }{}% +} % +the standard classes, \KOMAScript{} can recognize and separate consecutive +footnotes automatically. +See\important{\DescRef{\ThisCommonLabelBase.option.footnotes}} the previously +documented option \DescRef{\ThisCommonLabelBase.option.footnotes}. + +If instead you want to place this delimiter manually, you can do so by calling +\Macro{multiplefootnoteseparator}. However, users should not redefine this +command, as it contains not only the delimiter but also the delimiter's +formatting, for example the font size selection and the superscript. The +delimiter itself is stored in the previously described +\DescRef{\ThisCommonLabelBase.cmd.multfootsep}% +\important{\DescRef{\ThisCommonLabelBase.cmd.multfootsep}}% +\IndexCmd{multfootsep} command. + +\IfThisCommonFirstRun{\iftrue}{% + You can find examples and additional hints in + \autoref{sec:\ThisCommonFirstLabelBase.footnotes} from + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.footnote}.% + \csname iffalse\endcsname }% + \begin{Example} + \phantomsection\xmpllabel{cmd.footnote}% + Suppose you want to put two footnotes after a single word. First you try +\begin{lstcode} + Word\footnote{1st footnote}\footnote{2nd footnote} +\end{lstcode} + Let's assume that the footnotes are numbered 1 and 2. Since the two + footnote numbers follow each other directly, it creates the impression + that the word has only one footnote numbered 12. You can change this + behaviour by using +\begin{lstcode} + \KOMAoptions{footnotes=multiple} +\end{lstcode} + to enable the automatic recognition of footnote sequences. Alternatively, + you can use +\begin{lstcode} + word\footnote{Footnote 1}% + \multiplefootnoteseparator + \footnote{Footnote 2} +\end{lstcode} + This should give you the desired result even if automatic detection + fails or cannot be used for some reason. + + Now suppose you also want the footnote numbers to be separated not just by + a comma, but by a comma and a space. In this case, write +\begin{lstcode} + \renewcommand*{\multfootsep}{,\nobreakspace} +\end{lstcode} + in the preamble of your document. + \Macro{nobreakspace}\IndexCmd{nobreakspace} was used here instead of a + normal space to avoid paragraph or page breaks within the sequence of + footnotes. + \end{Example}% +\fi% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{footref}\Parameter{reference} +\end{Declaration} +Sometimes\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.00}{\Class{scrlttr2}}% + }{}} you have a footnote in a document to which there are several references +in the text. An inconvenient way to typeset this would be to use +\DescRef{\ThisCommonLabelBase.cmd.footnotemark} to set the number directly. +The disadvantage of this method is that you need to know the number and +manually set every \DescRef{\ThisCommonLabelBase.cmd.footnotemark} command. +And if the number changes because you add or remove an earlier footnote, you +will have to change each \DescRef{\ThisCommonLabelBase.cmd.footnotemark}. +\KOMAScript{} thefore offers the \Macro{label}\IndexCmd{label}% +\important{\Macro{label}} mechanism to handle such cases. After placing a +\Macro{label} inside the footnote, you can use \Macro{footref} to set all the +other marks for this footnote in the text. +\IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname}% + \begin{Example} + \phantomsection\xmpllabel{cmd.footref}% + You are writing a text in which you must create a footnote each time a + brand name occurs, indicating that it is a registered trademark. You can + write, for example, +\begin{lstcode} + Company SplishSplash\footnote{This is a registered trade name. + All rights are reserved.\label{refnote}} + produces not only SplishPlump\footref{refnote} + but also SplishPlash\footref{refnote}. +\end{lstcode} + This will produce the same footnote mark three times, but only one + footnote text. The first footnote mark is produced by + \DescRef{\ThisCommonLabelBase.cmd.footnote} itself, and the following two + footnote marks are produced by the additional \Macro{footref} + commands. The footnote text will be produced by + \DescRef{\ThisCommonLabelBase.cmd.footnote}. + \end{Example} + \fi When setting footnote marks with the \Macro{label} mechanism, any + changes to the footnote numbers will require at least two \LaTeX{} runs to + ensure correct numbers for all \Macro{footref} marks.% + \IfThisCommonLabelBaseOneOf{scrlttr2,scrextend}{\par% + You can find an example of how to use \Macro{footref} in + \autoref{sec:\ThisCommonFirstLabelBase.footnotes} on + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.footref}.% + }{} \IfThisCommonLabelBase{scrlttr2}{}{% + \par + Note\textnote{Attention!} that statements like \Macro{ref}\IndexCmd{ref} + or \Macro{pageref}\IndexCmd{pageref} are fragile and therefore you should + put \Macro{protect}\IndexCmd{protect} in front of them if they appear in + moving arguments such as headings.% + }% +\EndIndexGroup + + +\begin{Declaration} + \Macro{deffootnote}\OParameter{mark width}\Parameter{indent}% + \Parameter{parindent}\Parameter{definition}% + \Macro{deffootnotemark}\Parameter{definition}% + \Macro{thefootnotemark} +\end{Declaration}% +\IfThisCommonLabelBase{maincls}{The \KOMAScript{} classes set}{\KOMAScript{} + sets}\textnote{\KOMAScript{} vs. standard classes} footnotes slightly +differently than the standard classes do. As in the standard classes, the +footnote mark in the text is rendered with small, superscript numbers. The +same formatting is used in the footnote itself. The mark in the footnote is +typeset right-justified in a box with a width of \PName{mark width}. The first +line of the footnote follows directly. + +All subsequent lines will be indented by the length of \PName{indent}. If the +optional parameter \PName{mark width} is not specified, it defaults to +\PName{indent}. If the footnote consists of more than one paragraph, the first +line of each paragraph is indented by the value of \PName{parindent}. + +\autoref{fig:\ThisCommonFirstLabelBase.deffootnote} % +\IfThisCommonFirstRun{}{on + \autopageref{fig:\ThisCommonFirstLabelBase.deffootnote} }{}% +shows the different parameters% +\IfThisCommonLabelBase{maincls}{ again}{}% +. The default configuration of the \KOMAScript{} classes is as follows: +\IfThisCommonLabelBase{scrextend}{\iftrue}{\csname iffalse\endcsname}% +\begin{lstcode} + \deffootnote[1em]{1.5em}{1em}{% + \textsuperscript{\thefootnotemark}} +\end{lstcode} +\else +\begin{lstcode} + \deffootnote[1em]{1.5em}{1em}{% + \textsuperscript{\thefootnotemark}% + } +\end{lstcode} +\fi% +\DescRef{\ThisCommonLabelBase.cmd.textsuperscript} controls both the +superscript and the smaller font size. The command \Macro{thefootnotemark} +contains the current footnote mark without any formatting.% +\IfThisCommonLabelBase{scrextend}{ % + The \Package{scrextend} package, by contrast, does not change the default + footnote settings of the class you are using. Simply loading the package, + therefore, should not lead to any changes in the formatting of footnote + marks or footnote text. To use the default settings of the \KOMAScript{} + classes with \Package{scrextend}, you must change the settings above + yourself. For example, you can insert the line of code above immediately + after loading the \Package{scrextend} package.% +}{}% + +\IfThisCommonLabelBase{maincls}{% + \begin{figure} +% \centering + \KOMAoption{captions}{bottombeside} + \setcapindent{0pt}% + \begin{captionbeside} + [{Parameters that control the footnote layout}]% + {\label{fig:\ThisCommonLabelBase.deffootnote}\hspace{0pt plus 1ex}% + Parameters that control the footnote layout}% + [l] + \setlength{\unitlength}{1mm} + \begin{picture}(100,22) + \thinlines + % frame of following paragraph + \put(5,0){\line(1,0){90}} + \put(5,0){\line(0,1){5}} + \put(10,5){\line(0,1){5}}\put(5,5){\line(1,0){5}} + \put(95,0){\line(0,1){10}} + \put(10,10){\line(1,0){85}} + % frame of first paragraph + \put(5,11){\line(1,0){90}} + \put(5,11){\line(0,1){5}} + \put(15,16){\line(0,1){5}}\put(5,16){\line(1,0){10}} + \put(95,11){\line(0,1){10}} + \put(15,21){\line(1,0){80}} + % box of the footnote mark + \put(0,16.5){\framebox(14.5,4.5){\mbox{}}} + % description of paragraphs + \put(45,16){\makebox(0,0)[l]{\textsf{first paragraph of a footnote}}} + \put(45,5){\makebox(0,0)[l]{\textsf{next paragraph of a footnote}}} + % help lines + \thicklines + \multiput(0,0)(0,3){7}{\line(0,1){2}} + \multiput(5,0)(0,3){3}{\line(0,1){2}} + % parameters + \put(2,7){\vector(1,0){3}} + \put(5,7){\line(1,0){5}} + \put(15,7){\vector(-1,0){5}} + \put(15,7){\makebox(0,0)[l]{\small\PName{parindent}}} + % + \put(-3,13){\vector(1,0){3}} + \put(0,13){\line(1,0){5}} + \put(10,13){\vector(-1,0){5}} + \put(10,13){\makebox(0,0)[l]{\small\PName{indent}}} + % + \put(-3,19){\vector(1,0){3}} + \put(0,19){\line(1,0){14.5}} + \put(19.5,19){\vector(-1,0){5}} + \put(19.5,19){\makebox(0,0)[l]{\small\PName{mark width}}} + \end{picture} + \end{captionbeside} + \end{figure}} + +\BeginIndexGroup +\BeginIndex{FontElement}{footnote}\LabelFontElement{footnote}% +\BeginIndex{FontElement}{footnotelabel}\LabelFontElement{footnotelabel}% +The footnote\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v2.8q}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}% +}}{}, including the footnote mark, uses the font specified in the +\FontElement{footnote}\important{\FontElement{footnote}} element. You can +change the font of the footnote mark separately using the +\DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see +\autoref{sec:\ThisCommonLabelBase.textmarkup}, +\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}) +for the \FontElement{footnotelabel}\important{\FontElement{footnotelabel}} +element. See also \autoref{tab:\ThisCommonLabelBase.fontelements}, +\autopageref{tab:\ThisCommonLabelBase.fontelements}. +The default setting is no change to the font.% +\IfThisCommonLabelBase{scrextend}{ % + However, with \Package{scrextend} these elements will only change the fonts + if footnotes are handled by the package, that is, after using + \Macro{deffootnote}.% +}{} Please don't misuse this element for other purposes, for example to set +the footnotes ragged right (see also \DescRef{\LabelBase.cmd.raggedfootnote}, +\DescPageRef{\LabelBase.cmd.raggedfootnote}). + +\BeginIndex{FontElement}{footnotereference}% +\LabelFontElement{footnotereference}% +The footnote mark in the text is defined separately from the mark in +front of the actual footnote. This is done with +\Macro{deffootnotemark}. The default setting is: +\begin{lstcode} + \deffootnotemark{% + \textsuperscript{\thefootnotemark}} +\end{lstcode} +With\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v2.8q}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{} this default, the font for the +\FontElement{footnotereference}\important{\FontElement{footnotereference}} +element is used (see \autoref{tab:\ThisCommonLabelBase.fontelements}, +\autopageref{tab:\ThisCommonLabelBase.fontelements}). Thus, the footnote marks +in the text and in the footnote itself are identical. You can change the font +with the commands \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} (see +\autoref{sec:\ThisCommonLabelBase.textmarkup}, +\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont})% +\IfThisCommonLabelBase{scrextend}{ after \Macro{deffootnotemark} is used}{}. + +\IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname}% + \begin{Example} + \phantomsection + \xmpllabel{cmd.deffootnote}% + One\textnote{Hint!} feature that is often requested is footnote marks + which are neither in superscript nor in a smaller font. They should not + touch the footnote text but be separated by a small space. You can + accomplish this as follows: +\begin{lstcode} + \deffootnote{1em}{1em}{\thefootnotemark\ } +\end{lstcode} + This will set the footnote mark and subsequent space right-aligned in a + box of width 1\Unit{em}. The lines of the footnote text that follow are + also indented by 1\Unit{em} from the left margin. + + Another\textnote{Hint!} layout that is often requested is footnote marks + that are left-aligned. You can obtain them with the following + definition: +\begin{lstcode} + \deffootnote{1.5em}{1em}{% + \makebox[1.5em][l]{\thefootnotemark}} +\end{lstcode} + + If, however you want to change the font for all footnotes, for example + to sans serif, this can easily be done with the commands + \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and + \DescRef{\ThisCommonLabelBase.cmd.addtokomafont} (see + \autoref{sec:\ThisCommonLabelBase.textmarkup}, + \DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}): +\begin{lstcode} + \setkomafont{footnote}{\sffamily} +\end{lstcode} + \end{Example}% + \IfThisCommonLabelBase{scrextend}{}{% + As the examples show, {\KOMAScript} allows a wide variety of different + footnote formats with this simple user interface.% + }% +\fi% +\IfThisCommonFirstRun{}{% + For examples, see \autoref{sec:\ThisCommonFirstLabelBase.footnotes}, + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.deffootnote}.% +}{}% +% +\EndIndexGroup +\EndIndexGroup + +\IfThisCommonLabelBase{scrextend}{\iffalse}{\csname iftrue\endcsname} +\begin{Declaration} + \Macro{setfootnoterule}\OParameter{thickness}\Parameter{length}% +\end{Declaration}% +Generally,\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.06}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.06}{\Class{scrlttr2}}% + }{% + \IfThisCommonLabelBase{scrextend}{% + \ChangedAt{v3.06}{\Package{scrextend}}% + }{}% + }% +} a horizontal rule is set between the text area and the footnote area, but +normally this rule does not extend the full width of the type area. With +\Macro{setfootnoterule}, you can set the exact thickness and length of the +rule. In this case, the parameters \PName{thickness} and \PName{length} are +only evaluated when setting the rule itself. If the optional argument +\PName{thickness} has been omitted, the thickness of the rule will not be +changed. Empty arguments for \PName{thickness} or \PName{length} are also +allowed and do not change the corresponding parameters. Using absurd values +will result in warning messages both when setting and when using the +parameters. + +\BeginIndexGroup +\BeginIndex{FontElement}{footnoterule}\LabelFontElement{footnoterule}% +You can% +\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.07}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.07}{\Class{scrlttr2}}% + }{% + \IfThisCommonLabelBase{scrextend}{% + \ChangedAt{v3.07}{\Package{scrextend}}% + }{}% + }% +} % +change the colour of the rule with the +\FontElement{footnoterule}\important{\FontElement{footnoterule}} element using +the \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see +\autoref{sec:\ThisCommonLabelBase.textmarkup}, +\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}). The default is no change +of font or colour. In order to change the colour, you must also load a colour +package like +\Package{xcolor}\IndexPackage{xcolor}\important{\Package{xcolor}}.% +\EndIndexGroup +\EndIndexGroup +\fi + +\begin{Declaration} + \Macro{raggedfootnote} +\end{Declaration} +By default% +\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.23}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.23}{\Class{scrlttr2}}% + }{% + \IfThisCommonLabelBase{scrextend}{% + \ChangedAt{v3.23}{\Package{scrextend}}% + }{}% + }% +} % +\KOMAScript{} justifies footnotes just as in the standard classes. +But\textnote{\KOMAScript{} vs. standard classes} you can also change the +justification separately from the rest of the document by redefining +\Macro{raggedfootnote}. Valid definitions are +\Macro{raggedright}\IndexCmd{raggedright}, +\Macro{raggedleft}\IndexCmd{raggedleft}, +\Macro{centering}\IndexCmd{centering}, \Macro{relax}\IndexCmd{relax} or an +empty definition, which is the default. The alignment commands of the +\Package{ragged2e}\IndexPackage{ragged2e} package are also valid (see +\cite{package:ragged2e}). \IfThisCommonLabelBase{scrextend}{% + You can find a suitable example in + \autoref{sec:\ThisCommonFirstLabelBase.footnotes}, + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.raggedfootnote}.% + \iffalse }{\csname iftrue\endcsname}% + \begin{Example} + \phantomsection\xmpllabel{cmd.raggedfootnote}% + Suppose you are using footnotes only to provide references to very long + links, where line breaks would produce poor results if justified. You can + use +\begin{lstcode} + \let\raggedfootnote\raggedright +\end{lstcode} + in your document's preamble to switch to ragged-right footnotes. + \end{Example}% +\fi +\EndIndexGroup +% +\EndIndexGroup + + +%%% Local Variables: +%%% mode: latex +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-headfootheight.tex b/macros/latex/contrib/koma-script/source-doc/english/common-headfootheight.tex new file mode 100644 index 0000000000..8f9fcbb946 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-headfootheight.tex @@ -0,0 +1,163 @@ +% ====================================================================== +% common-headfootheight.tex +% Copyright (c) Markus Kohm, 2013-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-headfootheight.tex +% Copyright (c) Markus Kohm, 2013-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Text that is common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapitels in der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{common-headfootheight.tex} + [$Date: 2018-02-28 13:23:23 +0100 (Wed, 28 Feb 2018) $ + KOMA-Script guide (common paragraph: Head and Foot Height)] +\translator{Markus Kohm\and Jana Schubert\and Jens H\"uhne\and Karl Hagen} + +% Date of the translated German file: 2018-01-16 + +\section{Header and Footer Height} +\seclabel{height} +\BeginIndexGroup +\BeginIndex{}{header>height}% +\BeginIndex{}{footer>height}% +\IfThisCommonLabelBase{scrlayer-scrpage}{% + \begin{Explain}% + The \LaTeX{} standard classes do not use the footer much, and if they do + use it, they put the contents into a \Macro{mbox} which results in the + footer being a single text line. This is probably the reason that \LaTeX{} + itself does not have a well-defined footer height. Although the distance + between the last baseline of the text area and the baseline of the footer + is defined with \Length{footskip}\IndexLength[indexmain]{footskip}, if the + footer consists of more than one text line, there is no definite statement + whether this length should be the distance to the first or the last + baseline of the footer. + + Although the page header of the standard classes will also be put into a + horizontal box, and therefore is also a single text line, \LaTeX{} in fact + provides a length to set the height of the header. The reason for this may + be that this height is needed to determine the start of the text area. + \end{Explain}% +}{% + The header and footer of a page are central elements not just of a page + style. They can also serve to restrict layers using the appropriate options + (see \autoref{tab:scrlayer.layerkeys}, + \autopageref{tab:scrlayer.layerkeys}). Therefore the heights of these + elements must be defined.% +} + +\IfThisCommonFirstRun{}{% + The information in \autoref{sec:\ThisCommonFirstLabelBase.height} applies + equally to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.height}, you can skip ahead to + \autoref{sec:\ThisCommonLabelBase.height.next}, + \autopageref{sec:\ThisCommonLabelBase.height.next}.% +} + +\begin{Declaration} + \Length{footheight} + \Length{headheight} + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \OptionVName{autoenlargeheadfoot}{simple switch}% + }{}% +\end{Declaration} +The \Package{scrlayer} package introduces a new length, \Length{footheight}, +analogous to \Length{headheight}% +\IfThisCommonLabelBase{scrlayer-scrpage}{}{of the \LaTeX{} kernel}. +Additionally, +\Package{scrlayer\IfThisCommonLabelBase{scrlayer-scrpage}{-scrpage}{}} +interprets \Length{footskip} to be the distance from the last baseline of the +text area to the first normal baseline of the footer. The +\hyperref[cha:typearea]{\Package{typearea}}\IndexPackage{typearea}% +\important{\hyperref[cha:typearea]{\Package{typearea}}} package interprets +\Length{footheight} in the same way, so \Package{typearea}'s options for the +footer height can also be used to set the values for the \Package{scrlayer} +package. See the \DescRef{typearea.option.footheight} and +\DescRef{typearea.option.footlines} options in +\autoref{sec:typearea.typearea}, \DescPageRef{typearea.option.footheight}) +and option \DescRef{typearea.option.footinclude} on +\DescPageRef{typearea.option.footinclude} of the same section. + +If you do not use the \hyperref[cha:typearea]{\Package{typearea}}% +\important{\hyperref[cha:typearea]{\Package{typearea}}} package, you should +adjust the header and footer heights using appropriate values for the lengths +where necessary. For the header, at least, the \Package{geometry} package, for +example, provides similar settings. +\IfThisCommonLabelBase{scrlayer-scrpage}{\par% + If you choose a header or footer height that is too small for the actual + content, \Package{scrlayer-scrpage} tries by default to adjust the lengths + appropriately. At the same time, it will issue a warning containing + suggestions for suitable settings. These automatic changes take effect + immediately after the need for them has been detected and are not + automatically reversed, for example, when the content of the header or + footer becomes smaller afterwards. + However,\ChangedAt{v3.25}{\Package{scrlayer-scrpage}}, this behaviour can be + changed by using the \Option{autoenlargeheadfoot} option. This option + recognizes the values for simple switches in \autoref{tab:truefalseswitch}, + \autopageref{tab:truefalseswitch}. The option is activated by default. If it + is deactivated, the header and footer are no longer enlarged + automatically. Only a warning with hints for suitable settings is issued.% +}{% + \IfThisCommonLabelBase{scrlayer}{\par% + If you choose a header or footer height that is too small for the actual + content, \Package{scrlayer} usually accepts this without issuing an error + message or a warning. The header then expands according to its height, + usually upwards, with the footer moved down accordingly. Information about + this change is not obtained automatically. However, packages like + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + \important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}}% + \IndexPackage{scrlayer-scrpage} that build upon \Package{scrlayer} may + contain their own tests which can lead to their own actions (see + \DescRef{scrlayer-scrpage.length.headheight} and + \DescRef{scrlayer-scrpage.length.footheight} on + \DescPageRef{scrlayer-scrpage.length.headheight}).% + }{}% +}% +\EndIndexGroup +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide.tex" +%%% TeX-PDF-mode: t +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-interleafpage.tex b/macros/latex/contrib/koma-script/source-doc/english/common-interleafpage.tex new file mode 100644 index 0000000000..36f9fb4ae4 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-interleafpage.tex @@ -0,0 +1,338 @@ +% ====================================================================== +% common-interleafpage.tex +% Copyright (c) Markus Kohm, 2001-2017 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-interleafpage.tex +% Copyright (c) Markus Kohm, 2001-2017 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-interleafpage.tex}% + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (common paragraphs: Interleaf Pages)] +\translator{Markus Kohm\and Gernot Hassenpflug\and Krickette Murabayashi\and + Karl Hagen} + +% Date of the translated German file: 2017-12-07 + +\section{Interleaf Pages} +\seclabel{emptypage}% +\BeginIndexGroup +\BeginIndex{}{interleaf page}%% +\BeginIndex{}{page>style}% + +\IfThisCommonFirstRun{}{% + The information in \autoref{sec:\ThisCommonFirstLabelBase.emptypage} applies + equally to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.emptypage}, you can skip ahead to + \autoref{sec:\ThisCommonLabelBase.emptypage.next}, + \autopageref{sec:\ThisCommonLabelBase.emptypage.next}.% +} + +Interleaf pages are pages that are inserted between parts of a document. +Traditionally, these pages are completely blank. \LaTeX{}, however, +sets them by default with the current page style. \KOMAScript{} provides +several extensions to this functionality. + +Interleaf pages are mostly found in books. Because book chapters commonly +start on the right (recto) page of a two-page spread, an empty left (verso) +page must be inserted if the previous chapter ends on a recto page. For this +reason, interleaf pages really only exist for two-sided printing. +% +\iffalse % Umbruchkorrektur + The blank versos in one-sided printing are not true interleaf pages, + although they may appear as such in counting the printed sheets. +\fi% + +\IfThisCommonLabelBase{scrlttr2}{% + Interleaf pages are unusual in letters. This is not least because two-sided + letters are rare, as letters are usually not bound. Nevertheless, + \KOMAScript{} also supports interleaf pages for two-sided letters. However, + since the commands described here are seldom used in letters, you will not + find any examples here. If necessary, please refer to the examples in + \autoref{sec:maincls.emptypage}, starting on + \autopageref{sec:maincls.emptypage}.% +}{}% + +\begin{Declaration} + \OptionVName{cleardoublepage}{page style} + \OptionValue{cleardoublepage}{current} +\end{Declaration}% +With this option,\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.00}{\Class{scrlttr2}}% + }{}% +} you can define the page style of the interleaf pages created by the commands +\DescRef{\LabelBase.cmd.cleardoublepage}, +\DescRef{\LabelBase.cmd.cleardoubleoddpage}, or +\DescRef{\LabelBase.cmd.cleardoubleevenpage} to advance to the desired page. +You can use any previously defined \PName{page style} (see +\autoref{sec:\ThisCommonLabelBase.pagestyle} from +\autopageref{sec:\ThisCommonLabelBase.pagestyle} and +\autoref{cha:scrlayer-scrpage} from \autopageref{cha:scrlayer-scrpage}). +In addition, \OptionValue{cleardoublepage}{current} is also possible. +This case corresponds to the default prior to \KOMAScript~2.98c and creates an +interleaf page without changing the page style. Starting with +\KOMAScript~3.00\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.00}{\Class{scrlttr2}}% + }{}% +}, the default\textnote{default} follows the recommendation of most +typographers and creates interleaf pages with the +\IfThisCommonLabelBase{scrextend}{% + \DescRef{maincls.pagestyle.empty}}{% + \DescRef{\ThisCommonLabelBase.pagestyle.empty}}\IndexPagestyle{empty} +page style unless you switch compatibility to earlier \KOMAScript{} versions +(see option \DescRef{\ThisCommonLabelBase.option.version}% +\important{\OptionValueRef{\LabelBase}{version}{2.98c}}, +\autoref{sec:\ThisCommonLabelBase.compatibilityOptions}, +\DescPageRef{\ThisCommonLabelBase.option.version}). +\IfThisCommonLabelBase{maincls}{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{option.cleardoublepage}% + Suppose you want interleaf pages that are empty except for the pagination% + \iffree{, so they are created with \IfThisCommonLabelBase{scrextend}{% + \DescRef{maincls.pagestyle.plain}}{% + \DescRef{\LabelBase.pagestyle.plain}}}{}. You can achieve this, + for example, with: +\begin{lstcode} + \KOMAoptions{cleardoublepage=plain} +\end{lstcode} + You can find more information about the + \IfThisCommonLabelBase{scrextend}{% + \DescRef{maincls.pagestyle.plain}}{\DescRef{\LabelBase.pagestyle.plain}} + page style in \IfThisCommonLabelBase{scrextend}{% + \autoref{sec:maincls.pagestyle}}{% + \autoref{sec:\LabelBase.pagestyle}}, + \IfThisCommonLabelBase{scrextend}{% + \DescPageRef{maincls.pagestyle.plain}}{% + \DescPageRef{\LabelBase.pagestyle.plain}}. + \end{Example} +\else + \IfThisCommonLabelBase{scrextend}{% + You can find an example for setting the page style of interleaf pages in + \autoref{sec:\ThisCommonFirstLabelBase.emptypage}, + \PageRefxmpl{\ThisCommonFirstLabelBase.option.cleardoublepage}.% + \iffalse% Umbruchvariante ohne Beispiel + }{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{option.cleardoublepage}% + Suppose you want interleaf pages that are empty except for the pagination, + so they are created with the \IfThisCommonLabelBase{scrextend}{% + \DescRef{maincls.pagestyle.plain}}{\DescRef{\LabelBase.pagestyle.plain}} + page style. You can achieve this with +\begin{lstcode} + \KOMAoptions{cleardoublepage=plain} +\end{lstcode} + You can find more information about the + \DescRef{maincls.pagestyle.plain} page style in + \autoref{sec:maincls.pagestyle}, \DescPageRef{maincls.pagestyle.plain}. + \end{Example}% + \fi% +\fi% +\EndIndexGroup + + +\begin{Declaration} + \Macro{clearpage}% + \Macro{cleardoublepage}% + \Macro{cleardoublepageusingstyle}\Parameter{page style}% + \Macro{cleardoubleemptypage}% + \Macro{cleardoubleplainpage}% + \Macro{cleardoublestandardpage}% + \Macro{cleardoubleoddpage}% + \Macro{cleardoubleoddpageusingstyle}\Parameter{page style}% + \Macro{cleardoubleoddemptypage}% + \Macro{cleardoubleoddplainpage}% + \Macro{cleardoubleoddstandardpage}% + \Macro{cleardoubleevenpage}% + \Macro{cleardoubleevenpageusingstyle}\Parameter{page style}% + \Macro{cleardoubleevenemptypage}% + \Macro{cleardoubleevenplainpage}% + \Macro{cleardoubleevenstandardpage} +\end{Declaration}% +The\textnote{standard classes} {\LaTeX} kernel provides the \Macro{clearpage} +command, which ensures that all pending floats are output and then starts a +new page. There is also the \Macro{cleardoublepage} command, which works like +\Macro{clearpage} but which starts a new right-hand page in two-sided printing +(see the \Option{twoside} layout option in \autoref{sec:typearea.options}, +\DescPageRef{typearea.option.twoside}). An empty left-hand page in the current +page style is output if necessary. + +With\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.00}{\Class{scrlttr2}}% + }{}% +} \Macro{cleardoubleoddstandardpage}, {\KOMAScript}\textnote{\KOMAScript} +works as exactly in the way just described for the standard classess. The +\Macro{cleardoubleoddplainpage}% +\important{\IfThisCommonLabelBase{scrextend}{% + \DescRef{maincls.pagestyle.plain}}{\DescRef{\LabelBase.pagestyle.plain}}} +command, on the other hand, additionally changes the page style of the empty +left page to \IfThisCommonLabelBase{scrextend}{% + \DescRef{maincls.pagestyle.plain}}{\DescRef{\LabelBase.pagestyle.plain}}% +\IndexPagestyle{plain} in order to suppress the +\IfThisCommonLabelBase{scrlttr2}{page header}{running title}. Likewise, the +\Macro{cleardoubleoddemptypage}\important{% + \IfThisCommonLabelBase{scrextend}{\DescRef{maincls.pagestyle.empty}}{% + \DescRef{\LabelBase.pagestyle.empty}}} command uses the +\IfThisCommonLabelBase{scrextend}{\DescRef{maincls.pagestyle.empty}}{% + \DescRef{\LabelBase.pagestyle.empty}}\IndexPagestyle{empty} page style to +suppress both \IfThisCommonLabelBase{scrlttr2}{page header and page footer}% +{running title and page number} on the empty left-hand side. The page is thus +completely empty. If you want to specify your own \PName{page style} for the +interleaf page, this should be given as an argument of +\Macro{cleardoubleoddusingpagestyle}. You can use any previously defined +\PName{page style} (see \autoref{cha:scrlayer-scrpage}). + +\IfThisCommonLabelBase{scrlttr2}{}{% + Sometimes\textnote{odd-side interleaf pages} you want chapters to start not + on the right-hand but on the left-hand page. Although this layout contradicts + classic typography, it can be appropriate if the double-page spread at the + beginning of the chapter very specific contents. For this reason, + \KOMAScript{} provides the \Macro{cleardoubleevenstandardpage} command, + which is equivalent to the \Macro{cleardoubleoddstandardpage} command + except that the next page is a left page. The same applies to the + \Macro{cleardoubleevenplainpage}, \Macro{cleardoubleevenemptypage}, and + \Macro{cleardoubleevenpageusingstyle} commands% + \IfThisCommonLabelBase{maincls}{% Umbruchoptimierungsalternative + , the last of which expects an argument}{}.% +} + +The \Macro{cleardoublestandardpage}, \Macro{cleardoubleemptypage}, and +\Macro{cleardoubleplainpage} commands, and the single-argument +\Macro{cleardoublepageusingstyle} command, as well as the standard +\Macro{cleardoublepage} command, % +\IfThisCommonLabelBase{maincls}{% + depend on the \DescRef{maincls.option.open}\IndexOption{open}% + \important{\DescRef{maincls.option.open}} option explained in + \autoref{sec:maincls.structure}, \DescPageRef{maincls.option.open} and, + depending on that setting, correspond to one of the commands explained in + the preceding paragraphs. }{% + correspond to the commands previously explained for the + \IfThisCommonLabelBase{scrlttr2}{\Class{scrlttr2} class}{% + \IfThisCommonLabelBase{scrextend}{\Package{scrextend} package}{% + \InternalCommonFileUsageError}% + }% + \IfThisCommonLabelBase{scrlttr2}{. % + The remaining commands are defined in \Class{scrlttr2} for completeness + only. You can find more information on them in + \autoref{sec:maincls.emptypage}, \DescPageRef{maincls.cmd.cleardoublepage} + if necessary% + }{% + \ to transition to the next odd page% + }.% +}% +\IfThisCommonLabelBaseOneOf{scrlttr2,scrextend}{\iffalse}{\csname + iftrue\endcsname} + \begin{Example} + \phantomsection\xmpllabel{cmd.cleardoublepage}% + Suppose you want to insert a double-page spread into your document with a + picture on the left-hand page and a new chapter starting on the right-hand + page. If the previous chapter ends with a left-hand page, an interleaf + page has to be added, which should be completely empty. The picture should + be the same size as the text area without any header or footer. +\iffalse% Umbruchkorrekturtext + First of all, +\begin{lstcode} + \KOMAoptions{cleardoublepage=empty} +\end{lstcode} + ensures that interleaf pages use the + \IfThisCommonLabelBase{scrextend}{\DescRef{maincls.pagestyle.empty}}{% + \DescRef{\LabelBase.pagestyle.empty}} page style. You can put this + setting in the document preamble, or you can set it as an optional + argument of \DescRef{\ThisCommonLabelBase.cmd.documentclass}. +\fi + + At the relevant place in your document, write: +\begin{lstcode} + \cleardoubleevenemptypage + \thispagestyle{empty} + \includegraphics[width=\textwidth,% + height=\textheight,% + keepaspectratio]% + {picture} + \chapter{Chapter Heading} +\end{lstcode} + The first of these lines switches to the next left-hand page. If needed it + also adds a completely blank right-hand page. The second line makes sure + that the following left-hand page will also be set using the + \IfThisCommonLabelBase{scrextend}{\DescRef{maincls.pagestyle.empty}}{% + \DescRef{\LabelBase.pagestyle.empty}} page style. The third through + sixth lines load an image file named \File{picture} and scale it to the + desired size without distorting it. This command requires the + \Package{graphicx}\IndexPackage{graphicx} package (see + \cite{package:graphics}). The last line starts + a new chapter on the next page, which will be a right-hand one. + \end{Example}% +\fi% + +In two-sided printing, \Macro{cleardoubleoddpage} always moves to the next +left-hand page and \Macro{cleardoubleevenpage} to the next right-hand +page. The style of the interleaf page to be inserted if necessary is defined +with the \DescRef{\LabelBase.option.cleardoublepage} option.% +\IfThisCommonLabelBase{scrextend}{\par% + For an example that uses \Macro{cleardoubleevenemptypage}, see + \autoref{sec:maincls.emptypage}, + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.cleardoublepage}.% +}{}% +\EndIndexGroup +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: + +% LocalWords: mutatis mutandis Interleaf interleaf diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-lists.tex b/macros/latex/contrib/koma-script/source-doc/english/common-lists.tex new file mode 100644 index 0000000000..79a0a697fd --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-lists.tex @@ -0,0 +1,837 @@ +% ====================================================================== +% common-lists.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-lists.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-lists.tex} + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (common paragraphs)] +\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi\and + Karl Hagen} + +% Date of the translated German file: 2018-02-06 + +\section{Lists} +\seclabel{lists}% +\BeginIndexGroup +\BeginIndex{}{lists}% + +\IfThisCommonFirstRun{}{% + The information in \autoref{sec:\ThisCommonFirstLabelBase.lists} applies + equally to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.lists}, you can skip ahead to + \autoref{sec:\ThisCommonLabelBase.lists.next}, + \autopageref{sec:\ThisCommonLabelBase.lists.next}.% + \IfThisCommonLabelBaseOneOf{scrextend,scrlttr2}{ % + \IfThisCommonLabelBase{scrlttr2}{% + The \Package{scrletter}\OnlyAt{\Package{scrletter}} package does not + define any list environments itself but leaves them to the class + used. If this is not a \KOMAScript{} class, it will load + \hyperref[cha:scrextend]{\Package{scrextend}}\IndexPackage{scrextend}% + \important{\hyperref[cha:scrextend]{\Package{scrextend}}}.% + }{} % + However, the \Package{scrextend} package only defines the + \DescRef{\ThisCommonLabelBase.env.labeling}, + \DescRef{\ThisCommonLabelBase.env.addmargin}, and + \DescRef{\ThisCommonLabelBase.env.addmargin*} environments. All other list + environments are left to the responsibility of the class used.% + }{}% +} + +\IfThisCommonLabelBase{scrextend}{}{% + Both {\LaTeX} and the standard classes\textnote{\KOMAScript{} vs. standard + classes} offer different environments for lists. Naturally, {\KOMAScript} + also offers all these environments, though slightly modified or extended in + some cases. In general, all lists\,---\,even those of different + kinds\,---\,can be nested up to four levels deep. From a typographical view, + anything more would make no sense, as lists of more than three levels cannot + easily be apprehended. In such cases, I recommend\textnote{Hint!} that you + split a large list into several smaller ones.% +} + +\IfThisCommonFirstRun{}{% + Because lists are standard elements of \LaTeX{}, examples have been omitted + in this section. Nevertheless, you can find examples either in + \autoref{sec:\ThisCommonFirstLabelBase.lists}, + \autopageref{sec:\ThisCommonFirstLabelBase.lists} or in any \LaTeX{} + tutorial.% +} + +\IfThisCommonLabelBase{scrextend}{\iffalse}{\csname iftrue\endcsname} + \begin{Declaration} + \begin{Environment}{itemize} + \begin{Body} + \Macro{item} \dots + \BodyDots + \end{Body} + \end{Environment} + \Macro{labelitemi} + \Macro{labelitemii} + \Macro{labelitemiii} + \Macro{labelitemiv} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}% + The simplest form of a list is the itemized list\textnote{itemized list}, + \Environment{itemize}. % + \iffalse % Umbruckoptimierungstext + The users of a certain disliked word processing package often refer to this + form of a list as \emph{bullet points}. Presumably, they cannot imagine + that, depending on the level, a symbol other than a large dot could be used + to introduce each point. % + \fi% + Depending on the level, \KOMAScript{} classes use the following marks: + ``{\labelitemi}'', ``{\labelitemii}'', ``{\labelitemiii}'', and + ``{\labelitemiv}''. The definition of these symbols is specified in + the macros \Macro{labelitemi}, \Macro{labelitemii}, + \Macro{labelitemiii}, and \Macro{labelitemiv}, all of which you can + redefine using \Macro{renewcommand}. Every item is introduced with + \Macro{item}.% + \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{env.itemize}% + You have a simple list which is nested in several levels. You write, + for example: +\begin{lstcode} + \minisec{Vehicles in the game} + \begin{itemize} + \item aeroplanes + \begin{itemize} + \item biplane + \item transport planes + \begin{itemize} + \item single-engine + \begin{itemize} + \item jet propelled + \item propeller driven + \end{itemize} + \item twin-engine + \begin{itemize} + \item jet propelled + \item propeller driven + \end{itemize} + \end{itemize} + \item helicopters + \end{itemize} + \item motorcycles + \item automobiles + \begin{itemize} + \item racing cars + \item passenger cars + \item lorries + \end{itemize} + \item bicycles + \end{itemize} +\end{lstcode} + As output you get: + \begin{ShowOutput}[\baselineskip] + \minisec{Vehicles in the game} + \begin{itemize} + \item aeroplanes + \begin{itemize} + \item biplanes + \item transport planes + \begin{itemize} + \item single-engine + \begin{itemize} + \item jet-propelled + \item propeller-driven + \end{itemize} + \item twin-engine + \begin{itemize} + \item jet propelled + \item propeller driven + \end{itemize} + \end{itemize} + \item helicopters + \end{itemize} + \item motorcycles + % \begin{itemize} + % \item historically accurate + % \item futuristic, not real + % \end{itemize} + \item automobiles + \begin{itemize} + \item racing cars + \item passenger cars + \item lorries + \end{itemize} + \item bicycles + \end{itemize} + \end{ShowOutput} + \end{Example} + \fi + % + \EndIndexGroup + + + \begin{Declaration} + \begin{Environment}{enumerate}\labelsuffix[enumerate] + \begin{Body} + \Macro{item} \dots + \BodyDots + \end{Body} + \end{Environment} + \Macro{theenumi}% + \Macro{theenumii}% + \Macro{theenumiii}% + \Macro{theenumiv}% + \Macro{labelenumi}% + \Macro{labelenumii}% + \Macro{labelenumiii}% + \Macro{labelenumiv} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}The numbered + list\textnote{numbered list} is also very common and already provided by the + {\LaTeX} kernel. The numbering\Index{numbering} differs according to the + level, with Arabic numbers, small letters, small Roman numerals, and capital + letters, respectively. The style of numbering is defined with the macros + \Macro{theenumi} down to \Macro{theenumiv}. The output format is determined + by the macros \Macro{labelenumi} to \Macro{labelenumiv}. While the small + letter of the second level is followed by a right parenthesis, the values of + all other levels are followed by a dot. Every item is introduced with + \Macro{item}.% + \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{env.enumerate}% + Let's shorten the previous example, using an + \DescRef{\ThisCommonLabelBase.env.itemize} environment instead of the + \Environment{enumerate} environment: + \begin{ShowOutput}[\baselineskip] + \minisec{Vehicles in the game} + \begin{enumerate} + \item aeroplanes + \begin{enumerate} + \item biplanes + \item transport planes + \begin{enumerate} + \item single-engine + \begin{enumerate} + \item jet-propelled\label{xmp:maincls.jets} + \item propeller-driven + \end{enumerate} + \item twin-engine + \end{enumerate} + % \item helicopters + \end{enumerate} + \item motorcycles + \begin{enumerate} + \item historically accurate + \item futuristic, not real + \end{enumerate} + %\item automobiles + % \begin{enumerate} + % \item racing cars + % \item private cars + % \item lorries + % \end{enumerate} + %\item bicycles + \end{enumerate} + \end{ShowOutput} + Within the list, you can set labels in the normal way with + \Macro{label} and then reference then with \Macro{ref}. + In the example above, a label was set after the jet-propelled, + single-engine transport planes with + ``\Macro{label}\PParameter{xmp:jets}''. The \Macro{ref} value is then + ``\ref{xmp:maincls.jets}''. + \end{Example} + \fi% + % + \EndIndexGroup + + + \begin{Declaration} + \begin{Environment}{description}\labelsuffix[description] + \begin{Body} + \Macro{item}\OParameter{keyword} \dots + \BodyDots + \end{Body} + \end{Environment} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}Another list + form is the description list\textnote{description list}. It primarily serves + to describe individual items or keywords. The item itself is specified as an + optional parameter in \Macro{item}. % + \BeginIndex{FontElement}{descriptionlabel}% + \LabelFontElement{descriptionlabel}% + The font\Index{font>style}\ChangedAt{v2.8p}{% + \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% + \ used to format the keyword can be changed with the + \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and + \DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see + \autoref{sec:\ThisCommonLabelBase.textmarkup}, + \DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}) for the + \FontElement{descriptionlabel}\important{\FontElement{descriptionlabel}} + element (see \autoref{tab:\ThisCommonLabelBase.fontelements}, + \autopageref{tab:\ThisCommonLabelBase.fontelements}). The default is + \Macro{sffamily}\linebreak[1]\Macro{bfseries}.% + \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{env.description}% + You want the keywords to be printed bold and in the normal font instead + of bold and sans serif. Using +\begin{lstcode} + \setkomafont{descriptionlabel}{\normalfont\bfseries} +\end{lstcode} + you redefine the font accordingly. + + An example for a description list is the output of the page styles + listed in \autoref{sec:maincls.pagestyle}. The (abbreviated) source is: +\begin{lstcode} + \begin{description} + \item[empty] is the page style without any header or footer. + \item[plain] is the page style without headings. + \item[headings] is the page style with running headings. + \item[myheadings] is the page style for manual headings. + \end{description} +\end{lstcode} + This gives: + \begin{ShowOutput} + \begin{description} + \item[empty] is the page style without any header or footer. + \item[plain] is the page style without headings. + \item[headings] is the page style with running headings. + \item[myheadings] is the page style for manual headings. + \end{description} + \end{ShowOutput} + \end{Example} + \fi% + % + \EndIndexGroup% +\fi + +\begin{Declaration} + \begin{Environment}{labeling}\OParameter{delimiter} + \Parameter{widest pattern} + \labelsuffix[labeling] + \begin{Body} + \Macro{item}\OParameter{keyword}\dots + \BodyDots + \end{Body} + \end{Environment} +\end{Declaration}% +Another form of description list\textnote{alternative description list} is +only available in the {\KOMAScript} classes% +\IfThisCommonLabelBase{scrextend}{ and \Package{scrextend} }{% + \IfThisCommonLabelBase{scrlttr2}{ and + \hyperref[cha:scrextend]{\Package{scrextend}}}{}% +}% +: the \Environment{labeling} environment. Unlike +\IfThisCommonLabelBase{scrextend}{% + \DescRef{\ThisCommonFirstLabelBase.env.description}% +}{% + the \DescRef{\ThisCommonLabelBase.env.description} described above% +}, you can specify a pattern for \Environment{labeling} whose length +determines the indentation of all items. Furthermore, you can put an optional +\PName{delimiter} between the item and its description. % +\BeginIndexGroup +\BeginIndex{FontElement}{labelinglabel}\LabelFontElement{labelinglabel}% +\BeginIndex{FontElement}{labelingseparator}% +\LabelFontElement{labelingseparator}% +The font\Index{font>style}% +\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.02}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.02}{\Class{scrlttr2}}% + }{% + \IfThisCommonLabelBase{scrextend}{% + \ChangedAt{v3.02}{\Package{scrextend}}% + }{\InternalCommonFileUsageError}% + }% +} used to format the item and the separator can be changed with the +\DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see +\autoref{sec:\ThisCommonLabelBase.textmarkup}, +\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}) for the element +\FontElement{labelinglabel} and \FontElement{labelingseparator} (see +\autoref{tab:\ThisCommonLabelBase.fontelements}, +\autopageref{tab:\ThisCommonLabelBase.fontelements}). +\IfThisCommonFirstRun{\iftrue}{\par\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{env.labeling}% + \IfThisCommonLabelBase{scrextend}{% + A small example of a list like this can be written as follows:% + }{% + Slightly changing the example from the + \DescRef{\ThisCommonLabelBase.env.description} environment, we could + write the following:% + }% +\begin{lstcode} + \setkomafont{labelinglabel}{\ttfamily} + \setkomafont{labelingseparator}{\normalfont} + \begin{labeling}[~--]{myheadings} + \item[empty] + Page style without header or footer + \item[plain] + Page style for chapter beginnings without headings + \item[headings] + Page style for running headings + \item[myheadings] + Page style for manual headings + \end{labeling} +\end{lstcode} + The result is this: + \begin{ShowOutput} + \setkomafont{labelinglabel}{\ttfamily} + \setkomafont{labelingseparator}{\normalfont} + \begin{labeling}[~--]{myheadings} + \item[empty] + Page style without header or footer + \item[plain] + Page style for chapter beginnings without headings + \item[headings] + Page style for running headings + \item[myheadings] + Page style for manual headings + \end{labeling} + \end{ShowOutput} + As this example shows, you can set a font-changing command in the usual + way. But if you do not want the font of the separator to be changed in the + same way as the font of the label, you have to set the font of the + separator as well. + \end{Example} +\fi% +\EndIndexGroup +Originally, this environment was implemented for things like ``Premise, +Evidence, Proof'', or ``Given, Find, Solution'' that are often used in +lecture handouts. These days, however, the environment has very different +applications. For example, the environment for examples in this guide was +defined with the \Environment{labeling} environment.% +% +\EndIndexGroup + + +\IfThisCommonLabelBase{scrextend}{\iffalse}{\csname iftrue\endcsname} + \begin{Declaration} + \begin{Environment}{verse}\end{Environment} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{} The + \Environment{verse} environment\textnote{verse} is not normally perceived + as a list environment because you do not work with \Macro{item} commands. + Instead, fixed line breaks are used within the \Environment{flushleft} + environment. Internally, however, both the standard classes as well as + {\KOMAScript} implement it as a list environment. + + In general, the \Environment{verse} environment is used for + poetry\Index{poetry}. Lines are indented both left and right. Individual + lines of verse are ended by a fixed line break: \verb|\\|. Verses are set as + paragraphs, separated by an empty line. Often also + \Macro{medskip}\IndexCmd{medskip} or \Macro{bigskip}\IndexCmd{bigskip} is + used instead. To avoid a page break at the end of a line of verse you can, + as usual, insert \verb|\\*| instead of \verb|\\|. + \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{env.verse}% + \iffalse + As an example, the first lines of ``Little Red Riding Hood and the + Wolf'' by Roald Dahl: +\begin{lstcode} + \begin{verse} + As soon as Wolf began to feel\\* + that he would like a decent meal,\\* + He went and knocked on Grandma's door.\\* + When Grandma opened it, she saw\\* + The sharp white teeth, the horrid grin,\\* + And Wolfie said, `May I come in?' + \end{verse} +\end{lstcode} + The result is as follows: + \begin{ShowOutput} + \begin{verse} + As soon as Wolf began to feel\\* + That he would like a decent meal,\\* + He went and knocked on Grandma's door.\\* + When Grandma opened it, she saw\\* + The sharp white teeth, the horrid grin,\\* + And Wolfie said, `May I come in?' + \end{verse} + \end{ShowOutput} + \else + As an example, Emma Lazarus's sonnet from the pedestal of Liberty + Enlightening the World\footnote{The lines from Roald Dahl's poem + ``Little Red Riding Hood and the Wolf'', which was used in former + releases, has been replaced, because in these times certain + politicians around the world really seem to need ``The New + Colossus'' as urgent reminder.}: +\begin{lstcode} + \begin{verse} + Not like the brazen giant of Greek fame\\* + With conquering limbs astride from land to land\\* + Here at our sea-washed, sunset gates shall stand\\* + A mighty woman with a torch, whose flame\\* + Is the imprisoned lightning, and her name\\* + Mother of Exiles. From her beacon-hand\\* + Glows world-wide welcome; her mild eyes command\\* + The air-bridged harbor that twin cities frame.\\* + ``Keep, ancient lands, your storied pomp!'' cries she\\* + With silent lips. ``Give me your tired, your poor,\\* + Your huddled masses yearning to breathe free,\\* + The wretched refuse of your teeming shore.\\* + Send these, the homeless, tempest-tossed to me:\\* + I lift my lamp beside the golden door.'' + \end{verse} +\end{lstcode} + The result is as follows: + \begin{ShowOutput} + \begin{verse} + Not like the brazen giant of Greek fame\\* + With conquering limbs astride from land to land\\* + Here at our sea-washed, sunset gates shall stand\\* + A mighty woman with a torch, whose flame\\* + Is the imprisoned lightning, and her name\\* + Mother of Exiles. From her beacon-hand\\* + Glows world-wide welcome; her mild eyes command\\* + The air-bridged harbor that twin cities frame.\\* + ``Keep, ancient lands, your storied pomp!'' cries she\\* + With silent lips. ``Give me your tired, your poor,\\* + Your huddled masses yearning to breathe free,\\* + The wretched refuse of your teeming shore.\\* + Send these, the homeless, tempest-tossed to me:\\* + I lift my lamp beside the golden door.'' + \end{verse} + \end{ShowOutput} + \fi + However, if you have very long lines of verse where a line + break occurs within a line of verse: +\begin{lstcode} + \begin{verse} + Both the philosopher and the house-owner + always have something to repair.\\* + \bigskip + Don't trust a man, my son, who tells you + that he has never lied. + \end{verse} +\end{lstcode} + \begin{ShowOutput} + \begin{verse} + Both the philosopher and the house-owner always have something to + repair.\\ + \bigskip Don't trust a man, my son, who tells you that he has never + lied. + \end{verse} + \end{ShowOutput} + in this case \verb|\\*| can not prevent a page break occurring within a + verse at such a line break. To prevent such a page break, a + \Macro{nopagebreak}\IndexCmd{nopagebreak} would have to be inserted + somewhere in the first line: +\begin{lstcode} + \begin{verse} + Both the philosopher and the house-owner\nopagebreak{} + always have something to repair.\\ + \bigskip + Don't trust a man, my son, who tells you\nopagebreak{} + that he has never lied. + \end{verse} +\end{lstcode} + \iftrue% Umbruchkorrekturtext + Here are two sayings that should always be considered when confronted + with seemingly strange questions about {\LaTeX} or its accompanying + explanations: +\begin{lstcode} + \begin{verse} + A little learning is a dangerous thing.\\* + Drink deep, or taste not the Pierian Spring;\\ + \bigskip + Our judgments, like our watches, none\\* + go just alike, yet each believes his own. + \end{verse} +\end{lstcode} + \begin{ShowOutput} + \iffree{}{\vskip-.8\baselineskip}% Umbruchkorrektur + \begin{verse} + A little learning is a dangerous thing.\\* + Drink deep, or taste not the Pierian Spring;\\ + \bigskip + Our judgments, like our watches, none\\* + go just alike, yet each believes his own. + \end{verse} + \end{ShowOutput} + \fi + Incidentally, \Macro{bigskip} was used in these examples to separate two + sayings. + \end{Example} + \fi + % + \EndIndexGroup + + \iftrue% Umbruchkorrekturvarianten + \begin{Declaration} + \begin{Environment}{quote}\end{Environment} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}This is + internally also a list environment\textnote{block quote with paragraph + spacing} and can be found both in the standard classes and in + {\KOMAScript}. The content of the environment is set fully justified. + The environment is often used to format longer quotes\Index{quotes}. + Paragraphs within the environment are distinguished with vertical space.% + \EndIndexGroup + + \begin{Declaration} + \begin{Environment}{quotation}\end{Environment} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{}This + environment\textnote{block quote with paragraph indent} is comparable to + \DescRef{\ThisCommonLabelBase.env.quote}. While + \DescRef{\ThisCommonLabelBase.env.quote} paragraphs are indicated by + vertical spacing, \Environment{quotation} indents the first line of each + paragraph horizontally. This also applies to the first paragraph of a + \Environment{quotation} environment. If you want to prevent the + indentation there, you must precede it with the + \Macro{noindent}\IndexCmd{noindent} command.% + \else + \begin{Declaration} + \begin{Environment}{quote}\end{Environment} + \begin{Environment}{quotation}\end{Environment} + \end{Declaration}% + \IfThisCommonLabelBase{scrlttr2}{\OnlyAt{\Class{scrlttr2}}}{} These two + environments\textnote{block quotes} are also set internally as list + environments and can be found in both the standard and the {\KOMAScript} + classes. Both environments use justified text which is indented on both + the left and the right side. Often they are used to separate longer + quotations\Index{quotations} from the main text. The difference between + the two lies in in the manner in which paragraphs are typeset. While + \Environment{quote} paragraphs are distinguished by vertical space, in + \Environment{quotation} paragraphs, the first line is indented. This also + applies to the first line of a \Environment{quotation} + environment% Umbruchkorrektur + \IfThisCommonLabelBase{maincls}{% + , unless it is preceded by \Macro{noindent}\IndexCmd{noindent}.% + }{% + \IfThisCommonLabelBase{scrlttr2}{% + . If you want to prevent the indentation there, you must precede it + with the \Macro{noindent} command\IndexCmd{noindent}.% + }{\InternalCommonFileUsageError}% + }% + \fi % Umbruchkorrekturvarianten + \IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{env.quote}% + You want to highlight a short anecdote. You write the following + \Environment{quotation} environment for this:% +\begin{lstcode} + A small example for a short anecdote: + \begin{quotation} + The old year was turning brown; the West Wind was + calling; + + Tom caught the beechen leaf in the forest falling. + ``I've caught the happy day blown me by the breezes! + Why wait till morrow-year? I'll take it when me pleases. + This I'll mend my boat and journey as it chances + west down the withy-stream, following my fancies!'' + + Little Bird sat on twig. ``Whillo, Tom! I heed you. + I've a guess, I've a guess where your fancies lead you. + Shall I go, shall I go, bring him word to meet you?'' + \end{quotation} +\end{lstcode} + The result is: + \begin{ShowOutput} + A small example for a short anecdote: + \begin{quotation} + The old year was turning brown; the West Wind was + calling; + + Tom caught the beechen leaf in the forest falling. + ``I've caught the happy day blown me by the breezes! + Why wait till morrow-year? I'll take it when me pleases. + This I'll mend my boat and journey as it chances + west down the withy-stream, following my fancies!'' + + Little Bird sat on twig. ``Whillo, Tom! I heed you. + I've a guess, I've a guess where your fancies lead you. + Shall I go, shall I go, bring him word to meet you?'' + \end{quotation} + \end{ShowOutput} + % + Using a \Environment{quote} environment instead you get: + % + \begin{ShowOutput} + A small example for a short anecdote: + \begin{quote}\setlength{\parskip}{4pt plus 2pt minus 2pt} + The old year was turning brown; the West Wind was + calling; + + Tom caught the beechen leaf in the forest falling. + ``I've caught the happy day blown me by the breezes! + Why wait till morrow-year? I'll take it when me pleases. + This I'll mend my boat and journey as it chances + west down the withy-stream, following my fancies!'' + + Little Bird sat on twig. ``Whillo, Tom! I heed you. + I've a guess, I've a guess where your fancies lead you. + Shall I go, shall I go, bring him word to meet you?'' + \end{quote} + \end{ShowOutput} + % + \end{Example} + \fi + % + \EndIndexGroup +\fi + +\begin{Declaration} + \begin{Environment}{addmargin} + \OParameter{left indentation}\Parameter{indentation} + \end{Environment} + \begin{Environment}{addmargin*} + \OParameter{inner indentation}\Parameter{indentation} + \end{Environment} +\end{Declaration} +Like \IfThisCommonLabelBase{scrextend}{% + \DescRef{\ThisCommonFirstLabelBase.env.quote} and + \DescRef{\ThisCommonFirstLabelBase.env.quotation}, which are available in + the standard and the \KOMAScript{} classes}{% + \DescRef{\ThisCommonLabelBase.env.quote} and + \DescRef{\ThisCommonLabelBase.env.quotation}% +}, the \Environment{addmargin} environment changes the margin\Index{margin}. +However, unlike the first two environments, \Environment{addmargin} lets the +user change the width of the indentation. Apart from this change, this +environment does not change the indentation of the first line nor the vertical +spacing between paragraphs. + +If only the obligatory argument \PName{indentation} is given, both the left +and right margin are expanded by this value. If the optional argument +\PName{left indentation} is given as well, then the value \PName{left + indentation} is used for the left margin instead of \PName{indentation}. + +The starred variant \Environment{addmargin*}% +\important{\Environment{addmargin*}} differs from the normal version only in +the two-sided mode. Furthermore, the difference only occurs if the optional +argument \PName{inner indentation} is used. In this case, the value of +\PName{inner indentation} is added to the normal inner indentation. For +right-hand pages this is the left margin; for left-hand pages, the right +margin. Then the value of \PName{indentation} determines the width of the +opposite margin. + +Both versions of this environment allow negative values for all parameters. +\IfThisCommonLabelBase{scrextend}{% + The environment then protrudes into the margin accordingly.% +}{% + This can be done so that the environment protrudes into the margin.% +}% +\IfThisCommonFirstRun{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{env.addmargin}% +\begin{lstcode} + \newenvironment{SourceCodeFrame}{% + \begin{addmargin*}[1em]{-1em}% + \begin{minipage}{\linewidth}% + \rule{\linewidth}{2pt}% + }{% + \rule[.25\baselineskip]{\linewidth}{2pt}% + \end{minipage}% + \end{addmargin*}% + } +\end{lstcode} + If you now put your source code in such an environment, it will show + up as: + \begin{ShowOutput} + \newenvironment{SourceCodeFrame}{% + \begin{addmargin*}[1em]{-1em}% + \begin{minipage}{\linewidth}% + \rule{\linewidth}{2pt}% + }{% + \rule[.25\baselineskip]{\linewidth}{2pt}% + \end{minipage}% + \end{addmargin*}% + } + You define the following environment: + \begin{SourceCodeFrame} +\begin{lstcode} +\newenvironment{\SourceCodeFrame}{% + \begin{addmargin*}[1em]{-1em}% + \begin{minipage}{\linewidth}% + \rule{\linewidth}{2pt}% +}{% + \rule[.25\baselineskip]{\linewidth}{2pt}% + \end{minipage}% + \end{addmargin*}% +} +\end{lstcode} + \end{SourceCodeFrame} + This may be feasible or not. In any case, it shows the usage of this + environment. + \end{ShowOutput} + The optional argument of the \Environment{addmargin*} environment + makes sure that the inner margin is extended by 1\Unit{em}. In turn + the outer margin is decreased by 1\Unit{em}. The result is a shift + by 1\Unit{em} to the outside. Instead of \PValue{1em}, you can of + course use a length, for example, \PValue{2\Macro{parindent}}. + \end{Example} +\fi% + +Whether a page is going to be on the left or right side of the book cannot be +determined reliably on the first {\LaTeX} run. For details please refer to +the explanation of the commands +\DescRef{\ThisCommonLabelBase.cmd.ifthispageodd} +(\autoref{sec:\ThisCommonLabelBase.oddOrEven}, +\DescPageRef{\ThisCommonLabelBase.cmd.ifthispageodd}) and +\iffree{\Macro{ifthispagewasodd}}{% + \DescRef{maincls-experts.cmd.ifthispagewasodd}} +(\autoref{sec:maincls-experts.addInfos}\iffree{}{, +\DescPageRef{maincls-experts.cmd.ifthispageodd}}). +\IfThisCommonLabelBase{scrlttr2}{}{% +\begin{Explain} + The interplay of environments such as lists and paragraphs gives rise to + frequent questions. Therefore, you can find further explanation in the + description of the \Option{parskip} option in + \autoref{sec:maincls-experts.addInfos}\iffree{}{, + \DescPageRef{maincls-experts.option.parskip}. Also in the expert section, in + \autoref{sec:maincls-experts.addInfos}, + \DescPageRef{maincls-experts.env.addmargin*}, you can find additional + information about page breaks inside \Environment{addmargin*}}.% +\end{Explain}}% +% +\EndIndexGroup +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-marginpar.tex b/macros/latex/contrib/koma-script/source-doc/english/common-marginpar.tex new file mode 100644 index 0000000000..05e2bdd1f3 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-marginpar.tex @@ -0,0 +1,144 @@ +% ====================================================================== +% common-marginpar.tex +% Copyright (c) Markus Kohm, 2001-2019 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-marginpar.tex +% Copyright (c) Markus Kohm, 2001-2019 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-marginpar.tex} + [$Date: 2019-01-15 08:29:44 +0100 (Tue, 15 Jan 2019) $ + KOMA-Script guide (common paragraphs)] +\translator{Gernot Hassenpflug\and Markus Kohm\and Karl Hagen} + +% Date of the translated German file: 2018-01-29 + +\section{Marginal Notes} +\seclabel{marginNotes}% +\BeginIndexGroup +\BeginIndex{}{marginal notes}% + +\IfThisCommonFirstRun{}{% + The information in \autoref{sec:\ThisCommonFirstLabelBase.marginNotes} + applies equally to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.marginNotes}, you can skip ahead to + \autoref{sec:\ThisCommonLabelBase.marginNotes.next}, + \autopageref{sec:\ThisCommonLabelBase.marginNotes.next}.% +} + +In addition to the text area, which normally fills the type area, documents +often contain a column for marginalia. You can set marginal notes in this +area. +\IfThisCommonLabelBase{scrlttr2}{% + In letters, however, marginal notes are unusual and should be used + sparingly.% +}{% + This \iffree{guide}{book} makes frequent use of them.% +}% + + +\begin{Declaration} + \Macro{marginpar}\OParameter{margin note left}\Parameter{margin note}% + \Macro{marginline}\Parameter{margin note} +\end{Declaration}% +Marginal notes\Index[indexmain]{marginal notes} in {\LaTeX} are usually +inserted with the \Macro{marginpar} command. They are placed in the outer +margin. One-sided documents use the right border. Although you can specify a +different marginal note for \Macro{marginpar} in case it winds up in the left +margin, marginal notes are always fully justified. However, experience has +shown that many users prefer left- or right-justified marginal notes +instead. For this purpose, {\KOMAScript} offers the \Macro{marginline} +command. + +\IfThisCommonFirstRun{% + \iftrue% +}{% + For a detailed example, see + \autoref{sec:\ThisCommonFirstLabelBase.marginNotes} at + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.marginline}.% + \csname iffalse\endcsname% +}% + \begin{Example} + \phantomsection\xmpllabel{cmd.marginline}% + In some parts of this \iffree{guide}{book}, the class name + \Class{scrartcl} can be found in the margin. You can produce this with:% + \iftrue% Umbruchkorrekturtext + \footnote{Actually, instead of \Macro{texttt}, a semantic markup + was used. To avoid confusion, this has been replaced in the example.}% + \fi +\begin{lstcode} + \marginline{\texttt{scrartcl}} +\end{lstcode} + + Instead of \Macro{marginline} you could have used \Macro{marginpar}. In fact + the first command is implemented internally as: +\begin{lstcode} + \marginpar[\raggedleft\texttt{scrartcl}] + {\raggedright\texttt{scrartcl}} +\end{lstcode} + Thus \Macro{marginline} is really just a shorthand notation for the + code above.% +\end{Example}% +\fi + +Advanced users\textnote{Attention!} will find notes about difficulties that +can arise using \Macro{marginpar} in \autoref{sec:maincls-experts.addInfos}% +\iffree{}{, on \DescPageRef{maincls-experts.cmd.marginpar}}. These remarks +also apply to \Macro{marginline}. In addition, +\autoref{cha:scrlayer-notecolumn} introduces a package that you can use to +create note columns with their own page breaks.% +\iftrue% Umbruchkorrektur + \ However, the + \hyperref[cha:scrlayer-notecolumn]{\Package{scrlayer-notecolumn}}% + \IndexPackage{scrlayer-notecolumn} package is more a proof of concept than a + finished package.% +\fi% +% +\EndIndexGroup +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-oddorevenpage.tex b/macros/latex/contrib/koma-script/source-doc/english/common-oddorevenpage.tex new file mode 100644 index 0000000000..04ff2b91ac --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-oddorevenpage.tex @@ -0,0 +1,132 @@ +% ====================================================================== +% common-oddorevenpage.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-oddorevenpage.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-oddorevenpage.tex} + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (common paragraph: Detection of Odd and + Even Pages)] +\translator{Markus Kohm\and Krickette Murabayashi\and Karl Hagen} + +% Date of the translated German file: 2018-01-30 + +\section{Detecting Odd and Even Pages} +\seclabel{oddOrEven}% +\BeginIndexGroup% +\BeginIndex{}{page>odd}% +\BeginIndex{}{page>even}% + +\IfThisCommonFirstRun{}{% + The information in \autoref{sec:maincls.oddOrEven} applies equally to this + chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.oddOrEven}, you can skip ahead to + \autopageref{sec:\ThisCommonLabelBase.oddOrEven.next}, + \autopageref{sec:\ThisCommonLabelBase.oddOrEven.next}.% +} + +In two-sided documents we distinguish left and right pages. Left pages always +have an even page number, and right pages always have an odd page number. % +\IfThisCommonLabelBase{maincls}{% + Identifying right and left pages is equivalent to identifying even- or + odd-numbered pages, and so we normally refer to them as even and odd pages + in this \iffree{guide}{book}. + + % Umbruchkorrekturtext + \iftrue% + In one-sided documents, the distinction between left and right pages does + not exist. Nevertheless, there are still pages with even and odd page + numbers.% + \fi% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + As a rule, letters will be set one-sided. However, if you need to print + letters using both sides of the paper or, in exceptional cases, are + generating real two-sided letters, it may be useful to know whether you + are currently on an even or odd page.% + }{}% +} + + +\begin{Declaration} + \Macro{ifthispageodd}\Parameter{true part}\Parameter{false part} +\end{Declaration}% +If you want to determine whether text appears on an even or odd page, +\KOMAScript{} provides the \Macro {ifthispageodd} command. The \PName{true + part} argument is executed only if you are currently on an odd page. +Otherwise the \PName{false part} argument is executed. + +\begin{Example} + Suppose you simply want to show whether a text will be placed onto an + even or odd page. You may achieve that using +\begin{lstcode} + This page has an \ifthispageodd{odd}{even} + page number. +\end{lstcode} + This results in the output + \begin{quote} + This page has an \ifthispageodd{odd}{even} page number. + \end{quote} +\end{Example} + +Because the \Macro{ifthispageodd} command uses a mechanism that is very +similar to a label and a reference to it, at least two {\LaTeX} runs are +required after each change to the text. Only then will the decision be +correct. In the first run, a heuristic is used to make the initial choice. + +\iffree{}{In \autoref{sec:maincls-experts.addInfos}, +\DescPageRef{maincls-experts.cmd.ifthispageodd}, advanced users can find more +information about the problems of detecting left and right pages, or even and +odd page numbers.}% +% +\EndIndexGroup +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-options.tex b/macros/latex/contrib/koma-script/source-doc/english/common-options.tex new file mode 100644 index 0000000000..fff22502bb --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-options.tex @@ -0,0 +1,231 @@ +% ====================================================================== +% common-options.tex +% Copyright (c) Markus Kohm, 2001-2019 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-options.tex +% Copyright (c) Markus Kohm, 2001-2019 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-options.tex} + [$Date: 2017-12-07 23:10:55 -0800 (Thu, 07 Dec 2017) $ + KOMA-Script guide (common paragraphs)] +\translator{Gernot Hassenpflug\and Krickette Murabayashi\and Karl Hagen} + +% Date of the translated German file: 2018-10-23 + +\section{Early or Late Selection of Options} +\seclabel{options} +\BeginIndexGroup +\BeginIndex{}{options}% + +\IfThisCommonFirstRun{% + This section introduces a special feature of \KOMAScript{} which, in + addition to \IfThisCommonLabelBase{typearea}{\Package{typearea}}{% + \IfThisCommonLabelBase{maincls}{\Class{scrbook}, \Class{scrreprt}, and + \Class{scrartcl}}{% + \IfThisCommonLabelBase{scrlttr2}{the \Class{scrlttr2} class}{% + \IfThisCommonLabelBase{scrextend}{the classes and + \Package{scrextend}}{% + \IfThisCommonLabelBase{scrhack}{\Package{scrhack}}{% + \IfThisCommonLabelBase{scrjura}{\Package{scrjura}}{% + \IfThisCommonLabelBase{scrlayer}{\Package{scrlayer}}{% + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}}{% + \IfThisCommonLabelBase{scrlayer-notecolumn}{% + \Package{scrlayer-notecolumn}}{% + \InternalCommonFileUsageError}}}}}}}}}% + , is also relevant to other \KOMAScript{} packages and classes. % + \IfThisCommonLabelBase{scrlttr2}{So that each chapter may stand on its own, + this section appears in nearly identical form in several chapters, but if + you are studying all of \KOMAScript{}, you of course only need to read it + one time.% + }{This section appears in nearly identical form in several chapters, so you + can find all the information about a single package or class in the + relevant chapter. Users who are interested not just in a particular + package or class but in getting an overview of \KOMAScript{} as a whole + only need to read this section in one of the chapters and can + \IfThisCommonLabelBase{maincls}{skip the rest of the chapter.}{% + then skip it as they study the guide.}% + }% +}{% + The information in \autoref{sec:\ThisCommonFirstLabelBase.options} applies + equally to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.options}, you can skip ahead to + \autoref{sec:\ThisCommonLabelBase.options.next}, + \autopageref{sec:\ThisCommonLabelBase.options.next}.% +} + + + +\begin{Declaration} + \Macro{documentclass}\OParameter{option list}% + \Parameter{{\KOMAScript} class} + \Macro{usepackage}\OParameter{option list}% + \Parameter{package list} +\end{Declaration} +\LaTeX{} allows users to pass class options\textnote{class options} as a +comma-separated list of keywords in the optional argument to +\Macro{documentclass}. In addition to being passed to the class, these options +are also passed on to all packages\textnote{global options} that can +understand them. Users can also pass a similar comma-separated list of +keywords in the optional argument of \Macro{usepackage}\textnote{packet + options}. \KOMAScript{} extends\ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}\and \Package{scrextend}\and + \Package{typearea}} the option mechanism for +\IfThisCommonLabelBaseOneOf{scrextend,scrjura}{}{the \KOMAScript{} classes and +} some packages with further options. Thus most \KOMAScript{} options can also +take a value, so an option does not necessarily take the form \PName{option}, +but can also take the form \PName{option}\texttt{=}\PName{value}% +\important{\PName{option}\texttt{=}\PName{value}}. Except for this difference, +\Macro{documentclass} and \Macro{usepackage} in \KOMAScript{} function as +described in \cite{latex:usrguide} or any introduction to \LaTeX, for example +\cite{lshort}.% +% +\iffree{}{\IfThisCommonLabelBase{scrlayer-scrpage}{\par + Incidentally, the \Package{scrpage2}\IndexPackage{scrpage2}% + \important{\Package{scrpage2}} package, which is considered obsolete, does + not have this extension. It therefore understands only simple options without + an assigned value.\par}{}}% + +\IfThisCommonLabelBaseNotOneOf{% + scrjura,scrhack,scrlayer,scrlayer-scrpage,scrlayer-notecolumn,scrextend% +}{% + When using a \KOMAScript{} class\textnote{Attention!}, you should not + specify options when loading the \Package{typearea} or \Package{scrbase} + packages. The reason for this restriction is that the class already loads + these packages without options, and \LaTeX{} refuses to load a package + multiple times with different option settings.% + \IfThisCommonLabelBaseOneOf{maincls,scrlttr2}{ In general, it is not + necessary to load either one of these packages explicitly when using any + \KOMAScript{} class.}{}% + \par +}{} + +% Umbruchoptimierung!!! +\IfThisCommonLabelBase{typearea}{Setting the options with + \Macro{documentclass} has one\textnote{Attention!} major disadvantage: % +}{% + Note that \Macro{documentclass} has one drawback when using the option + interface described bellow\textnote{Attention!}: % +}% +unlike the interface described below, the options in \Macro{documentclass} are +not robust. So commands, lengths, counters, and such constructs may break +inside the optional argument of this command. For example, with many +non-\KOMAScript{} classes, using a \LaTeX{} length in the value of an option +results in an error% +\IfThisCommonLabelBaseNotOneOf{maincls,scrlttr2}{ before the value is passed + to a \KOMAScript{} package and it can take control of the option + execution}{}% +. So if you want to use a \LaTeX{} length, counter, or command as part of the +value of an option, you should use \DescRef{\LabelBase.cmd.KOMAoptions} or +\DescRef{\LabelBase.cmd.KOMAoption}. These commands will be described next.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{KOMAoptions}\Parameter{option list} + \Macro{KOMAoption}\Parameter{option}\Parameter{value list} +\end{Declaration} +\KOMAScript{}\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}\and \Package{scrextend}\and \Package{typearea}} also +provides the ability to change the values of most +\IfThisCommonLabelBaseOneOf{scrextend,scrjura}{}{class and }package options +even after loading the \IfThisCommonLabelBaseOneOf{scrextend,scrjura}{}{% + class or} package. You can use the \Macro{KOMAoptions} command to change the +values of a list of options, as in +\DescRef{\ThisCommonLabelBase.cmd.documentclass} or +\DescRef{\ThisCommonLabelBase.cmd.usepackage}. Each option in the +\PName{option list} has the form \PName{option}\texttt{=}\PName{value}% +\important{\PName{option}\texttt{=}\PName{value},\dots}. + +Some options also have a default value. If you do not specify a value, that is +if you give the option simply as \PName{option}, then this default value will +be used. + +Some options can have several values simultaneously. For such options, it is +possible, with the help of \Macro{KOMAoption}, to pass a list of values to a +single \PName{option}. The individual values are given as a comma-separated +\PName{value list}\important{\PName{value},\dots}. + +\begin{Explain} + \KOMAScript{} uses the commands \DescRef{scrbase.cmd.FamilyOptions} and + \DescRef{scrbase.cmd.FamilyOption} with the family ``\PValue{KOMA}'' to + implement this ability. + \IfThisCommonLabelBaseOneOf{typearea}{% Umbruchkorrektur + Advanced users will find more on these instructions in + \autoref{sec:scrbase.keyvalue}, \DescPageRef{scrbase.cmd.FamilyOptions}. + }{% + See \autoref{part:forExperts}, \autoref{sec:scrbase.keyvalue}, + \DescPageRef{scrbase.cmd.FamilyOptions}. }% +\end{Explain} + +Options set with \Macro{KOMAoptions} or \Macro{KOMAoption} will reach +\IfThisCommonLabelBase{scrextend}{}{both the \KOMAScript{} class and }any +previously loaded \KOMAScript{} packages that recognise these options. If an +option or a value is unknown, \hyperref[cha:scrbase]{\Package{scrbase}}% +\IndexPackage{scrbase}\important{\hyperref[cha:scrbase]{\Package{scrbase}}} +will report it as an error.% +% +\iffalse% Umbruchkorrekturtext +\iffree{}{\IfThisCommonLabelBase{scrlayer-scrpage}{\par + Incidentally, the \Package{scrpage2}\IndexPackage{scrpage2}% + \important{\Package{scrpage2}}, which is considered obsolete, does not have + this extension. Options can therefore only be set when the package is loaded + with the option explained previously.}{}}% +\fi% +% +\EndIndexGroup +% +\EndIndexGroup + +\phantomsection +\label{sec:\ThisCommonLabelBase.options.end} +\endinput + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-pagestylemanipulation.tex b/macros/latex/contrib/koma-script/source-doc/english/common-pagestylemanipulation.tex new file mode 100644 index 0000000000..3a3933167d --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-pagestylemanipulation.tex @@ -0,0 +1,1038 @@ +% ====================================================================== +% common-pagestylemanipulation.tex +% Copyright (c) Markus Kohm, 2013-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-pagestylemanipulation.tex +% Copyright (c) Markus Kohm, 2013-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Text that is common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapitels in der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{common-pagestylemanipulation.tex} + [$Date: 2018-02-05 01:50:56 -0800 (Mon, 05 Feb 2018) $ + KOMA-Script guide (common paragraph: + Setting up defined page styles)] +\translator{Markus Kohm\and Jana Schubert\and Karl Hagen} + +% Date version of the translated file: 2018-02-05 + +\section{Manipulating Page Styles} +\seclabel{pagestyle.content} +\BeginIndexGroup +\BeginIndex{}{page>style} + +\IfThisCommonLabelBase{scrlayer}{% + Although \Package{scrlayer} itself does not define concrete page styles with + content\,---\,the previously mentioned page styles + \DescRef{\LabelBase.pagestyle.@everystyle@} and \PageStyle{empty} are + initially defined without any layers, i.\,e., without content\,---\,, the + package provides some options and commands to manipulate their contents.% +}{% + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \autoref{sec:scrlayer-scrpage.predefined.pagestyles} explains how the page + styles \DescRef{\LabelBase.pagestyle.scrheadings} and + \DescRef{\LabelBase.pagestyle.plain.scrheadings} are defined and how these + defaults can be changed. But topics such as creating running headers, + changing the widths of the header and footer, and putting horizontal lines + above or below the header or footer have yet to be described. Although + these capabilities are actually part of the + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + \important{\hyperref[cha:scrlayer]{\Package{scrlayer}}} package, they will + be explained below because these basic features of + \hyperref[cha:scrlayer]{\Package{scrlayer}} make up an important part of + \IfThisCommonLabelBase{scrlayer-scrpage}{\Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + }.% + }{% + \IfThisCommonLabelBase{scrlayer-scrpage-experts}{% + This section is a supplement to + \autoref{sec:scrlayer.pagestyle.content}. It describes features that may + be too complicated for beginners.% + }{\InternalCommonFileUsageError}% + }% +} + +\IfThisCommonLabelBase{scrlayer-scrpage-experts}{\iffalse}{% + \csname iftrue\endcsname}% + \begin{Declaration} + \Macro{automark}\OParameter{section level of the right mark} + \Parameter{section level of the left mark} + \Macro{automark*}\OParameter{section level of the right mark} + \Parameter{section level of the left mark} + \Macro{manualmark} + \end{Declaration} + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \begin{Explain} + In both the standard \LaTeX{} classes and the \KOMAScript{} classes, the + decision of whether to use automatic or static running + heads\Index{running heads>automatic}\Index{running heads>static} is made + by using the appropriate page style. Running heads repeat some + descriptive text, such as a title, that is appropriate to the page or + column, usually in the header, more rarely in the footer. As already + explained in + \autoref{sec:maincls.pagestyle}, you get automatic running heads with + \DescRef{maincls.pagestyle.headings}\IndexPagestyle{headings}% + \important{\DescRef{maincls.pagestyle.headings}} + + In the article classes\OnlyAt{\Class{article}\and \Class{scrartcl}} + \Class{article} or \hyperref[cha:maincls]{\Class{scrartcl}}, the + \PageStyle{headings}\IndexPagestyle{headings} page style uses the + section heading, which is either the mandatory or the optional argument + of \DescRef{maincls.cmd.section}, for the running head% + \textnote{automatic running head} of one-sided documents. Two-sided + documents use this section heading as the \emph{left mark} and the + subsection heading as the \emph{right mark}. The left mark is printed, + as the name indicates, on left-hand (verso) pages. The right mark is + printed on right-hand (recto)\,---\,in one-sided printing this means on + all\,---\,pages. The classes by default also delete the right mark + whenever they put the section heading into the left mark. + + The report and book classes \OnlyAt{\Class{report}\and + \Class{scrreprt}\and \Class{book}\and \Class{scrbook}} start one level + higher. Thus they use the chapter heading as the right mark in one-sided + printing. In two-sided printing, the chapter heading is the left mark + and the section heading is the right mark. + + If you use \DescRef{maincls.pagestyle.myheadings}% + \IndexPagestyle{myheadings}% + \important{\DescRef{maincls.pagestyle.myheadings}}\textnote{manual + running head}, the marks in the page header still exist, and the page + numbers are placed in the same way, but section commands no longer set + the marks automatically. You can set them manually\important{% + \DescRef{\ThisCommonLabelBase.cmd.markright}\\ + \DescRef{\ThisCommonLabelBase.cmd.markboth}} using the commands + \DescRef{\ThisCommonLabelBase.cmd.markright} and + \DescRef{\ThisCommonLabelBase.cmd.markboth}, which are described later + in this section. + \end{Explain}\par + }{% + \IfThisCommonLabelBase{scrlayer}{% + For most classes, the choice of a page style\,---\,generally + \PageStyle{headings} or \PageStyle{myheading}\,---\,determines whether + the running heads are created automatically or manually. % + }{\InternalCommonFileUsageError}% + }% + This distinction has been eliminated by % + \iffalse \Package{scrpage2} and now also by \fi% + \hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer}. Instead + of distinguishing between automatic\textnote{automatic and manual running + heads} and manual running heads by which page style is selected, there are + two new commands: \Macro{automark} and \Macro{manualmark}. + + The \Macro{manualmark}\important{\Macro{manualmark}} command switches to + manual marks and deactivates the automatic filling of the marks. In contrast, + \Macro{automark}\important{\Macro{automark}} and \Macro{automark*} define + which section levels should be used to set the mark automatically. The + optional argument is the \PName{section level of the right mark}, the + mandatory argument the \PName{section level of the left mark}. The + arguments should always be the name of a section level like + \PValue{part}, \PValue{chapter}, \PValue{section}, \PValue{subsection}, + \PValue{subsubsection}, \PValue{paragraph}, or \PValue{subparagraph}. + + Normally, the higher level should be used for the left mark and the lower + level for the right mark. This is only a convention and not a requirement, + but it makes sense. + + Please note\textnote{Attention!} that not every class provides running heads + for every section level. For example, the standard classes\textnote{% + \KOMAScript{} vs. standard classes} never use \DescRef{maincls.cmd.part} + in the heading. The \KOMAScript{} classes, on the other hand, support all + levels. + + The difference between \Macro{automark} and \Macro{automark*}% + \important{\Macro{automark*}} is that \Macro{automark} overrides all + previous commands to automatically set the mark, while \Macro{automark*} + changes only the behaviour of the section levels specified in its + arguments.% + \IfThisCommonLabelBase{scrlayer-scrpage}{}{ With this feature you can handle + relatively complex cases.}% Umbruchoptimierung + \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{\csname + iffalse\endcsname}% + \iffalse% Umbruchkorrekturtext + \iffree{}{\par + The obsolete package + \Package{scrpage2}\IndexPackage{scrpage2}\important{\Package{scrpage2}} + understands both \Macro{manualmark} and \Macro{automark}, but not + \Macro{automark*}. Therefore the following examples are not completely + transferable when using \Package{scrpage2}.% + }% + \fi + % + \begin{Example} + \phantomsection\xmpllabel{mark}% + Suppose you want chapter headings to be used as the running head of even + pages and the section heading to be the running head of odd pages, as + usual. But on odd pages you also want the chapter headings to be used as + the running head until the first section appears. To do so, you first + have to load \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} + and select the \DescRef{\LabelBase.pagestyle.scrheadings} page style, + so the document starts with: +\begin{lstcode} + \documentclass{scrbook} + \usepackage{scrlayer-scrpage} + \pagestyle{scrheadings} +\end{lstcode} + Next, ensure that the chapter headings set both the left and the right + marks: +\begin{lstcode} + \automark[chapter]{chapter} +\end{lstcode} + Then the section heading should also set right marks: +\begin{lstcode} + \automark*[section]{} +\end{lstcode} + Here the starred version is used, since the previous \Macro{automark} + command should remain in effect. Additionally, the mandatory argument + for the \PName{section level of the left mark} is empty because this + mark should remain unchanged. + + All that's missing now is a bit of document content to show the result: +\begin{lstcode} + \usepackage{lipsum} + \begin{document} + \chapter{Chapter Heading} + \lipsum[1-20] + \section{Section Heading} + \lipsum[21-40] + \end{document} +\end{lstcode} + We use the extremely useful \Package{lipsum}\IndexPackage{lipsum} + package to generate some dummy text with command + \Macro{lipsum}\IndexCmd{lipsum}. + + If you test the example, you will see that the first page of the chapter + appears, as usual, without a running head, since this page automatically + uses the \PageStyle{plain} page style + \DescRef{\LabelBase.pagestyle.plain.scrheadings} (see the + \DescRef{maincls.cmd.chapterpagestyle} on + \DescPageRef{maincls.cmd.chapterpagestyle}). Pages~2--4 have the + chapter headings in the running head. After the section heading on + page~4, the running head of page~5 changes to this section heading. From + this page to the end, the running head alternates from page to page + between the chapter and section headings.% + \end{Example} + \fi + + \begin{Declaration} + \Option{automark} + \OptionVName{autooneside}{simple switch} + \Option{manualmark} + \end{Declaration} + Instead of the commands described previously, you can also use the + \Option{manualmark}\important{\Option{manualmark}\\\Option{automark}} and + \Option{automark} options to switch between automatic and manual running + heads. \Option{automark} always uses the default\textnote{default} + \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{\csname + iffalse\endcsname}% + \lstinline|\automark[section]{chapter}| for classes with + \DescRef{maincls.cmd.chapter} and + \lstinline|\automark[subsection]{section}| for other classes. + \else +\begin{lstcode} + \automark[section]{chapter} +\end{lstcode} + for classes with \DescRef{maincls.cmd.chapter} and +\begin{lstcode} + \automark[subsection]{section} +\end{lstcode} + for other classes. + \fi + + \IfThisCommonLabelBase{scrlayer-scrpage}{% + In one-sided printing, you normally want only the higher section levels + to provide the running title.% + }{% + In one-sided printing, you normally do not want the lower section level + to influence the right mark. Instead, you want the higher section + level, which would appear in only the left mark in two-sided printing, to + be the running head of all pages.% + } The default option \Option{autooneside}\important{\Option{autooneside}} + corresponds to this behaviour. The option accepts the values for + simple switches listed in \autoref{tab:truefalseswitch}, + \autopageref{tab:truefalseswitch}. If you deactivate this option, the + optional and mandatory arguments of \Macro{automark} and \Macro{automark*} + will again control the running head in one-sided printing.% + \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{\csname + iffalse\endcsname}% + \begin{Example} + \phantomsection\xmpllabel{mark.oneside}% + Suppose you have a one-sided report but want running heads similar to + those in the previous book example. Specifically, the chapter headings + should be used as the running head until the first section appears. + From the then on, the section heading should be used. So we modify the + previous example a little bit: +\begin{lstcode} + \documentclass{scrreprt} + \usepackage[autooneside=false]{scrlayer-scrpage} + \pagestyle{scrheadings} + \automark[section]{chapter} + \usepackage{lipsum} + \begin{document} + \chapter{Chapter Heading} + \lipsum[1-20] + \section{Section Heading} + \lipsum[21-40] + \end{document} +\end{lstcode} + As you can see an \DescRef{\LabelBase.cmd.automark*} command is not + required in this case. You should try the example with + \Option{autooneside} set to \PValue{true}, or remove the option, for + comparison. You will notice a difference in the running head from + page~4 on. + \end{Example} + \fi + + Note\textnote{Attention!} that merely loading the package does not have any + effect on whether automatic or manual running heads are used, or what kind + of sectioning headings fill the marks. Only by explicitly using the option + \Option{automark} or \Option{manualmark}, or the command + \DescRef{\LabelBase.cmd.automark} or \DescRef{\LabelBase.cmd.manualmark}, + will the conditions here be initialized.% + \IfThisCommonLabelBase{scrlayer-scrpage}{\par% + You can find additional background information and examples of how to use + these commands in the documentation for the \Package{scrlayer} package + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + } in \autoref{sec:scrlayer-scrpage.pagestyle.content}, starting on + \DescPageRef{scrlayer-scrpage.cmd.manualmark}.% + }{}% + \EndIndexGroup + \EndIndexGroup + + + \begin{Declaration} + \OptionVName{draft}{simple switch} + \end{Declaration} + This \KOMAScript{} option accepts the values for simple switches + listed in \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. + If this option is active, all elements of the page styles will also show + rulers\index{ruler}% + \IfThisCommonLabelBase{scrlayer}{ for}{% + . This can sometimes be useful during} + the drafting process.% + \IfThisCommonLabelBase{scrlayer-scrpage}{ % + If this option has been set globally (see the optional argument + of \DescRef{\LabelBase.cmd.documentclass}) but you do not want the + rulers, you can deactivate them for this package alone by using + \OptionValue{draft}{false} as an optional argument of + \DescRef{\LabelBase.cmd.usepackage} while loading the package.% + }{}% + \EndIndexGroup + + \begin{Declaration} + \Macro{MakeMarkcase}\Parameter{text} + \end{Declaration} + Automatic running heads, but not manual ones, use \Macro{MakeMarkcase} for + their output. If the command has not been defined, e.\,g., by the class + while loading \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }, it is defined by default to output the argument \PName{text} without + changes. But the default can be changed either by redefining + \Macro{MakeMarkcase} or by using the \DescRef{\LabelBase.option.markcase}% + \IndexOption{markcase}\important{\DescRef{\LabelBase.option.markcase}} + option, which will be described next. Depending on the setting, the + argument can, e.\,g., be converted into upper or lower case.% + \EndIndexGroup + + + \begin{Declaration} + \OptionVName{markcase}{value} + \end{Declaration} + As explained earlier, with \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } you can choose between manual and automatic running heads. Using automatic + running heads, the corresponding marks are set using the section heading + commands. In some cultures, in contrast to the typography of German-speaking + countries, it is common practice to set the running heads in upper-case + letters. The \LaTeX{} standard classes do so by default. The + \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } package also offers this as an option. To do so, use the + \OptionValue{markcase}{upper}\important{\OptionValue{markcase}{upper}}% + \IndexOption[indexmain]{markcase~=upper} option, which redefines + \DescRef{scrlayer.cmd.MakeMarkcase}\IndexCmd[indexmain]{MakeMarkcase}. + + \IfThisCommonLabelBase{scrlayer}{% + Because of the poor typographical quality of the primitive capitalisation + routine (see the explanation of \DescRef{scrlayer-scrpage.option.markcase} + in \autoref{sec:scrlayer-scrpage.pagestyle.content}, + \autopageref{expl:scrlayer-scrpage.MakeUppercase}) the author of + \KOMAScript recommends that you avoid upper-case typesetting for running + heads.% + }{% + Unfortunately,\phantomsection\label{expl:\ThisCommonLabelBase.MakeUppercase} + the \LaTeX{} command for converting text to upper case\Index{upper case}, + \Macro{MakeUppercase}\IndexCmd{MakeUppercase}, does not produce good + results because it neither spaces characters nor balances lines + appropriately. This is certainly in part due to the fact that a + typographically correct upper-case conversion requires analysing the + glyphs to account for the different letter shapes \iffree{and their + combinations}{} while balancing the block. I therefore recommend that + you avoid upper-case typesetting for running heads.% + } This is usually possible with \OptionValue{markcase}{used}\important{% + \OptionValue{markcase}{used}}\IndexOption[indexmain]{markcase~=used}. + However, some classes insert \Macro{MarkUppercase}, or even the \TeX{} + command \Macro{uppercase}, into the running heads. For such cases, you can + use the option \OptionValue{markcase}{noupper}% + \important{\OptionValue{markcase}{noupper}}% + \IndexOption[indexmain]{markcase~=noupper}. This will also deactivate + \Macro{MakeUppercase} and \Macro{uppercase} inside the running heads. + + You can find all valid values for \Option{markcase} in + \autoref{tab:scrlayer-scrpage.markcase}% + \IfThisCommonLabelBase{scrlayer-scrpage}{}{, + \autopageref{tab:scrlayer-scrpage.markcase}}.% + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \begin{table} + \centering + \caption[Available values for the \Option{markcase} option]{Available + values for the \Option{markcase} option to select upper/lower case + typesetting in automatic running heads}% + \label{tab:\ThisCommonLabelBase.markcase}% + \begin{desctabular} + \pventry{lower}{\IndexOption[indexmain]{markcase~=lower}% + redefines \DescRef{\LabelBase.cmd.MakeMarkcase} to convert the + automatic running heads into lower-case letters using + \Macro{MakeLowercase} (lower case typesetting).% + }% + \pventry{upper}{\IndexOption[indexmain]{markcase~=upper}% + redefines \DescRef{\LabelBase.cmd.MakeMarkcase} to convert the + automatic running heads into upper-case letters using + \Macro{MakeUppercase} (upper case typesetting).% + }% + \pventry{used}{\IndexOption[indexmain]{markcase~=used}% + redefines \DescRef{\LabelBase.cmd.MakeMarkcase} to use automatic + running heads without any case changes.% + }% + \entry{\PValue{ignoreuppercase}, \PValue{nouppercase}, + \PValue{ignoreupper}, + \PValue{noupper}}{\IndexOption[indexmain]{markcase~=noupper}% + redefines not only \DescRef{\LabelBase.cmd.MakeMarkcase} but also + \Macro{MakeUppercase} and \Macro{uppercase} locally to the running + heads to leave the automatic running heads unchanged.% + }% + \end{desctabular} + \end{table} + }{}% + \EndIndexGroup + + + \begin{Declaration} + \Macro{leftmark} + \Macro{rightmark} + \Macro{headmark} + \Macro{pagemark} + \end{Declaration} + If you want to depart from the predefined page styles, you typically need to + decide where to place the marks' contents. With + \Macro{leftmark}\important{\Macro{leftmark}} you can define what will + appear in the left mark when the page is output. + + Similarly, you can use \Macro{rightmark}\important{\Macro{rightmark}} to + define the contents of the right mark.\iffree{}{ For information about some + subtleties when using these commands, see further + \DescRef{maincls-experts.cmd.rightmark} in + \autoref{sec:maincls-experts.addInfos}, + \DescPageRef{maincls-experts.cmd.rightmark}.} + + You can make life easier with \Macro{headmark}\important{\Macro{headmark}}. + This extension of \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } is a shorthand that resolves to either \Macro{leftmark} or + \Macro{rightmark} depending on whether the current page is even or odd. + + The \Macro{pagemark}\important{\Macro{pagemark}} command has nothing to do + with \TeX's mark mechanism. It is serves to output a formatted page number. + \BeginIndex{FontElement}{pagenumber}\LabelFontElement{pagenumber}% + The font of element + \FontElement{pagenumber}\important{\FontElement{pagenumber}} will be used + for the output. This can be changed using the \Macro{setkomafont} or + \DescRef{maincls.cmd.addtokomafont} commands (see also + \autoref{sec:maincls.textmarkup}, \DescPageRef{maincls.cmd.setkomafont}).% + \EndIndex{FontElement}{pagenumber}% + \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{% + \par % + If you are interested in an example showing the usage of the + \Macro{headmark} and \Macro{pagemark} commands, see + \autoref{sec:scrlayer-scrpage.pagestyle.content}, + \PageRefxmpl{scrlayer-scrpage.cmd.headmark}. Internally, the + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + } package uses many such features of + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }{% + \Package{scrlayer}% + }.% + \csname iffalse\endcsname}% + \begin{Example} + \phantomsection\xmpllabel{cmd.headmark}% + Suppose you want the running head to be aligned to the left margin and + the page number to the right margin in one-sided printing. The following + minimal working example does just this: +\begin{lstcode} + \documentclass{scrreprt} + \usepackage{blindtext} + \usepackage[automark]{scrlayer-scrpage} + \pagestyle{scrheadings} + \ihead{\headmark} + \ohead*{\pagemark} + \chead{} + \cfoot[]{} + \begin{document} + \blinddocument + \end{document} +\end{lstcode} + The \Package{blindtext}\IndexPackage{blindtext} package and its + \Macro{blinddocument}\IndexCmd{blinddocument} command have been used + here to quickly generate sample document content for the example. + + The \DescRef{scrlayer-scrpage.cmd.ihead}\IndexCmd{ihead} and + \DescRef{scrlayer-scrpage.cmd.ohead*}\IndexCmd{ohead*} commands + configure the desired marks. The starred variant + \DescRef{scrlayer-scrpage.cmd.ohead*} % + \iffalse% Umbruchvarianten + configures the page number mark not only on the pages set with the + \DescRef{\LabelBase.pagestyle.scrheadings}% + \IndexPagestyle{scrheadings} page style but also those set + with the \PageStyle{plain} % + \else% + also configures the page number with the % + \fi% + \DescRef{\LabelBase.pagestyle.plain.scrheadings}% + \IndexPagestyle{plain.scrheadings} page style used on the first page of + a chapter.% + + Because these page styles have predefined marks in the centre of the + header and footer, those elements are cleared by using + \DescRef{scrlayer-scrpage.cmd.chead} and + \DescRef{scrlayer-scrpage.cmd.cfoot} with empty arguments. Alternatively + you could use + \DescRef{scrlayer-scrpage-experts.cmd.clearpairofpagestyles} + \IndexCmd{clearpairofpagestyles} \emph{before} + \DescRef{scrlayer-scrpage.cmd.ihead}. You will find this command + described in \autoref{sec:scrlayer-scrpage-experts.pagestyle.pairs}. + \end{Example} + + Please note\textnote{Attention!} that the empty optional argument of + \DescRef{scrlayer-scrpage.cmd.cfoot} in the example above is not the same + as omitting the optional argument. You should try it yourself and have a + look at the difference in the footer of the first page.% + \fi + + \IfThisCommonLabelBase{scrlayer-scrpage}{% Umbruchvarianten + Advanced users can find more mark-setting commands% + }{% + If the options for the marks described above are not sufficient, + additional commands for advanced users are documented% + } % + starting on \IfThisCommonLabelBase{scrlayer-scrpage}{% + \DescPageRef{scrlayer-scrpage-experts.cmd.righttopmark}}{% + \DescPageRef{\ThisCommonLabelBase.cmd.righttopmark}}.% + \iffalse% Umbruchkorrektur + \ For example, there you can find + \DescRef{scrlayer-scrpage-experts.cmd.leftfirstmark} and + \DescRef{scrlayer-scrpage-experts.cmd.rightbotmark}, which are quite useful + for documents like lexicons.% + \fi% + \EndIndexGroup + + + \begin{Declaration} + \Macro{partmarkformat}% + \Macro{chaptermarkformat}% + \Macro{sectionmarkformat}% + \Macro{subsectionmarkformat}% + \Macro{subsubsectionmarkformat}% + \Macro{paragraphmarkformat}% + \Macro{subparagraphmarkformat} + \end{Declaration} + \KOMAScript{} classes and the \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } package typically use these commands internally to format the section + numbers. They also support the \DescRef{maincls.cmd.autodot} mechanism of + the \KOMAScript{} classes. If desired, these commands can be redefined to + achieve a different formatting of section numbers.% + \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{% + \ See the example in \autoref{sec:scrlayer-scrpage.pagestyle.content}, + \PageRefxmpl{scrlayer-scrpage.cmd.sectionmarkformat} for more + information.% + \csname iffalse\endcsname% + }% + \begin{Example} + \phantomsection\xmpllabel{cmd.sectionmarkformat}% + \iftrue + For example, if you want to have running heads without a section + number, this is how you do it: + \else + Suppose you want section headings without the section number to appear + in the running head. This can be accomplished easily with the + following: + \fi +\begin{lstcode}[belowskip=-\dp\strutbox] + \renewcommand*{\sectionmarkformat}{} +\end{lstcode} + \end{Example} + \fi% + \EndIndexGroup + + + \begin{Declaration} + \Macro{partmark}\Parameter{Text}% + \Macro{chaptermark}\Parameter{Text}% + \Macro{sectionmark}\Parameter{Text}% + \Macro{subsectionmark}\Parameter{Text}% + \Macro{subsubsectionmark}\Parameter{Text}% + \Macro{paragraphmark}\Parameter{Text}% + \Macro{subparagraphmark}\Parameter{Text} + \end{Declaration} + Most classes use these commands internally to set the marks according to the + sectioning commands. The argument should contain the text without the number + of the sectioning unit. The number is automatically determined using the + current section level if you use numbered headings. + + However\textnote{Attention!}, not all classes use such a command for + every section level. The standard classes\textnote{\KOMAScript{} vs. + standard classes}, for example, do not call \Macro{partmark} + \IfThisCommonLabelBase{scrlayer-scrpage}{% + upon a \Macro{part} command}{% + , whereas the \KOMAScript{} classes naturally support \Macro{partmark} as + well}. + + If you redefine these commands, be sure\textnote{Attention!} to check + whether the numbers will be output via the + \DescRef{maincls.counter.secnumdepth} before setting the number even if you + do not change the \DescRef{maincls.counter.secnumdepth} counter yourself, + because packages and classes may do so locally and rely on correct handling + of \DescRef{maincls.counter.secnumdepth}. + + The \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } package also redefines these commands whenever you use + \DescRef{scrlayer.cmd.automark} or \DescRef{scrlayer.cmd.manualmark} or the + corresponding options, to activate or deactivate the desired running heads.% + \EndIndexGroup + + + \begin{Declaration} + \Macro{markleft}\Parameter{left mark}% + \Macro{markright}\Parameter{right mark}% + \Macro{markboth}\Parameter{left mark}\Parameter{right mark} + \end{Declaration} + Regardless of whether you are working with manual or automatic running + heads, you can always change the contents of the \PName{left mark} or the + \PName{right mark} using these commands. Note that the left-hand mark + resulting from \Macro{leftmark}\IndexCmd{leftmark}% + \important{\Macro{leftmark}} will be the last mark placed on the + corresponding page, while the right-hand mark resulting from + \Macro{rightmark}\IndexCmd{rightmark}\important{\Macro{rightmark}} is the + first mark placed on the corresponding page. For more details, see + \iffree{}{the additional explanation of + \DescRef{maincls-experts.cmd.rightmark} in + \autoref{sec:maincls-experts.addInfos}, + \DescPageRef{maincls-experts.cmd.rightmark} or} to + \DescRef{scrlayer.cmd.rightfirstmark}\IfThisCommonLabelBase{scrlayer}{}{ in + \autoref{sec:scrlayer.pagestyle.content}}, + \DescPageRef{scrlayer.cmd.rightfirstmark}. + + If you are using manual running heads\Index{running head>manual}, the marks + remain valid until they are explicitly replaced by reusing the corresponding + commands. However, if you are using automatic running heads, the marks can + become invalid with the next section heading, depending on the automatic + configuration. + + You can also use these commands in conjunction with the starred versions of + the sectioning commands.% + \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{% + \ You can find detailed examples illustrating usage of \Macro{markboth} + with the \IfThisCommonLabelBase{scrlayer-scrpage}{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }{% + \Package{scrlayer}% + }-derived package \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + } in + \autoref{sec:scrlayer-scrpage.pagestyle.content}, + \PageRefxmpl{scrlayer-scrpage.cmd.markboth}.% + \csname iffalse\endcsname% + }% + \begin{Example} + \phantomsection\xmpllabel{cmd.markboth}% + Suppose you write a preface of several pages placed just before the + table of contents but not appearing in it. However, since you use + dividing lines in your header, you want a running head for this preface: +\begin{lstcode} + \documentclass[headsepline]{book} + \usepackage{scrlayer-scrpage} + \pagestyle{scrheadings} + \usepackage{blindtext} + \begin{document} + \chapter*{Preface} + \markboth{Preface}{Preface} + \blindtext[20] + \tableofcontents + \blinddocument + \end{document} +\end{lstcode} + At first glance, this seems to produce the desired result. Taking a + second look, however, you can see that the running title + ``\texttt{Preface}'' does not appear in upper-case letters, unlike the + other running heads. But that's easy to change: +\begin{lstcode} + \documentclass[headsepline]{book} + \usepackage{scrlayer-scrpage} + \pagestyle{scrheadings} + \usepackage{blindtext} + \begin{document} + \chapter*{Preface} + \markboth{\MakeMarkcase{Preface}}{\MakeMarkcase{Preface}} + \blindtext[20] + \tableofcontents + \blinddocument + \end{document} +\end{lstcode} + Using command \DescRef{\LabelBase.cmd.MakeMarkcase} results in getting + the same letter case as for automatic running heads. + + Now, let's move the \DescRef{maincls.cmd.tableofcontents} in front + of the preface and remove the \Macro{markboth} command. You'll + discover that the preface now has the running head + ``\texttt{CONTENTS}''. This is due to a quirk of + \DescRef{maincls.cmd.chapter*} (see also \autoref{sec:maincls.structure} + on \DescPageRef{maincls.cmd.chapter*}). If you do not want a running + head here, you can easily accomplish this by passing two empty arguments + to \Macro{markboth}: +\begin{lstcode} + \documentclass[headsepline]{book} + \usepackage{scrlayer-scrpage} + \pagestyle{scrheadings} + \usepackage{blindtext} + \begin{document} + \tableofcontents + \chapter*{Preface} + \markboth{}{} + \blindtext[20] + \blinddocument + \end{document} +\end{lstcode} + \end{Example} + \fi% + \EndIndexGroup +\fi + + +\IfThisCommonLabelBase{scrlayer-scrpage}{\iffalse}{\csname iftrue\endcsname} + \begin{Declaration} + \Macro{GenericMarkFormat}\Parameter{name of the section level} + \end{Declaration} + By default, this command is used to format all section numbers in running + heads below the subsection level, and for classes without + \DescRef{maincls.cmd.chapter}, also for the section and subsection levels, + unless the respective mark commands for those levels are defined before + loading \Package{scrlayer}. The command causes the package to use + \Macro{@seccntmarkformat}\IndexCmd{@seccntmarkformat}% + \important{\Macro{@seccntmarkformat}} if this internal command is defined, + as it is in the \KOMAScript{} classes. Otherwise \Macro{@seccntformat}% + \IndexCmd{@seccntformat}\important{\Macro{@seccntformat}} will be used, + which is provided by the \LaTeX{} kernel. The mandatory argument of the + command contains the name of a sectioning command, such as \PValue{chapter} + or \PValue{section} \emph{without} the backslash prefix. + + By redefining this command, you can change the default number format for all + sectioning commands that use it. Classes can also change the default + formatting also by defining this command.% + \IfThisCommonLabelBase{scrlayer-scrpage-experts}{\iftrue}{% + \par % + A detailed example illustrating the interplay of the + \Macro{GenericMarkFormat} command with the + \DescPageRef{\ThisCommonLabelBase.cmd.chaptermark} command and + \DescRef{\ThisCommonLabelBase.cmd.sectionmarkformat} or + \DescRef{\ThisCommonLabelBase.cmd.subsectionmarkformat} when using + the \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }-derived package \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + } is shown in \autoref{sec:scrlayer-scrpage-experts.pagestyle.content}, + \PageRefxmpl{scrlayer-scrpage-experts.cmd.GenericMarkFormat}.% + \csname iffalse\endcsname}% + \begin{Example} + \phantomsection + \xmpllabel{cmd.GenericMarkFormat}% + Suppose you want the section numbers of all levels in the running head + of an article to be printed in white within a black box. Since the + commands \Macro{sectionmarkformat} and \Macro{subsectionmarkformat} of + the \Package{scrlayer} package are defined with + \Macro{GenericMarkFormat} for articles using the standard \LaTeX{} + \Class{article} class, you need to redefine only this one command: +\begin{lstcode} + \documentclass{article} + \usepackage{blindtext} + \usepackage[automark]{scrlayer-scrpage} + \pagestyle{scrheadings} + \usepackage{xcolor} + \newcommand*{\numberbox}[1]{% + \colorbox{black}{\strut~\textcolor{white}{#1}~}} + \renewcommand*{\GenericMarkFormat}[1]{% + \protect\numberbox{\csname the#1\endcsname}\enskip} + \begin{document} + \blinddocument + \end{document} +\end{lstcode} + The colour has been changed using the + \Package{xcolor}\IndexPackage{xcolor} package. More details can be found + in that package's manual (see \cite{package:xcolor}). + + This example also uses an invisible strut. Any detailed \LaTeX{} + introduction should explain the related command \Macro{strut}. + + A helper macro, \Macro{numberbox}, has been defined to format the number + within a box. This command is prefixed in the redefinition of + \Macro{GenericMarkFormat} by \Macro{protect} in order to protect it from + expansion. This is necessary because otherwise the upper-case letter + conversion of \Macro{MakeUppercase} for the running head, would result + in using the colours ``\texttt{BLACK}'' and ``\texttt{WHITE}'' instead + of ``\texttt{black}'' and ``\texttt{white}'', and those colours are + undefined. Alternatively, you could define \Macro{numberbox} using + \Macro{DeclareRobustCommand*} instead of \Macro{newcommand*} and omit + \Macro{protect} (see \cite{latex:clsguide}). + + If you wanted to achieve the same effect with a \KOMAScript{} class or + with the standard \LaTeX{} classes \Class{book} or \Class{report}, you + would also have to redefine, respectively, + \DescRef{scrlayer.cmd.sectionmarkformat}\IndexCmd{sectionmarkformat}% + \important{\DescRef{scrlayer.cmd.sectionmarkformat}} and + \DescRef{scrlayer.cmd.subsectionmarkformat}% + \IndexCmd{subsectionmarkformat}% + \important{\DescRef{scrlayer.cmd.subsectionmarkformat}}, or + \DescRef{scrlayer.cmd.chaptermarkformat}% + \IndexCmd{chaptermarkformat}% + \important{\DescRef{scrlayer.cmd.chaptermarkformat}} and + \DescRef{scrlayer.cmd.sectionmarkformat}% + \IndexCmd{sectionmarkformat}% + \important{\DescRef{scrlayer.cmd.sectionmarkformat}}, because + these are not by default defined using \Macro{GenericMarkFormat}: +\begin{lstcode} + \documentclass{scrbook} + \usepackage{blindtext} + \usepackage[automark]{scrlayer-scrpage} + \pagestyle{scrheadings} + \usepackage{xcolor} + \newcommand*{\numberbox}[1]{% + \colorbox{black}{\strut~\textcolor{white}{#1}~}} + \renewcommand*{\GenericMarkFormat}[1]{% + \protect\numberbox{\csname the#1\endcsname}\enskip} + \renewcommand*{\chaptermarkformat}{\GenericMarkFormat{chapter}} + \renewcommand*{\sectionmarkformat}{\GenericMarkFormat{section}} + \begin{document} + \blinddocument + \end{document} +\end{lstcode} + \end{Example} + \fi% + \EndIndexGroup + + + \begin{Declaration} + \Macro{righttopmark}% + \Macro{rightbotmark}% + \Macro{rightfirstmark}% + \Macro{lefttopmark}% + \Macro{leftbotmark}% + \Macro{leftfirstmark} + \end{Declaration} + \LaTeX\ChangedAt{v3.16}{\Package{scrlayer}} typically uses a two-part + \TeX{} mark for page styles. Running heads can access the left part of that + mark with \DescRef{scrlayer.cmd.leftmark}% + \important{\DescRef{scrlayer.cmd.leftmark}}\IndexCmd{leftmark} and the right + part with \DescRef{scrlayer.cmd.rightmark}% + \important{\DescRef{scrlayer.cmd.rightmark}}\IndexCmd{rightmark}. In fact, + it was probably intended to use \DescRef{scrlayer.cmd.leftmark} for the + running head of left (even) pages and \DescRef{scrlayer.cmd.rightmark} for + the running head of right (odd) pages of two-sided documents. In + one-sided printing, however, the standard classes do not even set the left + part of the mark. + + \TeX{} itself knows three ways to access a mark. The \Macro{botmark}% + \IndexCmd{botmark}\important{\Macro{botmark}} is the last valid mark of the + most recent page that has been built. If no mark has been set on the page, + it corresponds to the last mark set on the pages that have already been + shipped out. The \LaTeX{} command \DescRef{scrlayer.cmd.leftmark} uses + precisely this mark, so it returns the left part of the last mark of the + page. This corresponds exactly to \Macro{leftbotmark}% + \important{\Macro{leftbotmark}}. By comparison, \Macro{rightbotmark}% + \important{\Macro{rightbotmark}} prints the right part of this mark. + + \Macro{firstmark}\IndexCmd{firstmark}\important{\Macro{firstmark}} is the + first mark of the last page that has been built. This is the first mark that + has been set on the page. If no mark has been set on the page, it + corresponds to the last mark of the pages that have already been shipped + out. The \LaTeX{} command \DescRef{scrlayer.cmd.rightmark} uses precisely + this mark, so it returns the right part of the first mark of the page. This + corresponds exactly to \Macro{rightfirstmark}% + \important{\Macro{rightfirstmark}}. By comparison, \Macro{leftfirstmark}% + \important{\Macro{leftfirstmark}} prints the left part of this mark. + + \Macro{topmark}\IndexCmd{topmark}\important{\Macro{topmark}} is the content + that \Macro{botmark} had before building the current page. \LaTeX{} itself + does not use it. Nevertheless, \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } provides \Macro{lefttopmark}\important{\Macro{lefttopmark}} to access the + left part of this mark and \Macro{righttopmark}% + \important{\Macro{righttopmark}} to access the right part. + + Note\textnote{Attention!} that the left and right portions of the mark + can only be set together. Even if you use + \DescRef{scrlayer.cmd.markright}\IndexCmd{markright} to change only the + right part, the left part will set again (unchanged). Accordingly, in + two-sided printing, using the \PageStyle{headings}% + \important{\PageStyle{headings}}\IndexPagestyle{headings} page style, + the higher section levels always make both parts. For example, + \DescRef{scrlayer.cmd.chaptermark} uses \DescRef{scrlayer.cmd.markboth} with + an empty right argument in this case. This is the reason + \DescRef{scrlayer.cmd.rightmark} or \Macro{rightfirstmark} always shows an + empty value on pages which start a chapter, even if there was a + \DescRef{scrlayer.cmd.sectionmark} or \DescRef{maincls.cmd.section} on the + same page to make the right part of the mark. + + Please note\textnote{Attention!} that using any of these commands to show + the left or right part of the mark as part of the page content may lead to + unexpected results. They are really meant for use in the header or footer + of a page style only. Therefore, they should always be part of the contents + of a layer when using \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }. But it does not matter whether the layer is restricted to the background + or the foreground, since all layers are shipped out after building the + current page. + + If you need more information about the mark mechanism + \iffree{of \TeX{}}{\unskip}, please have a look at + \cite[chapter~23]{knuth:texbook}. The topic is flagged there as an issue for + real experts. \IfThisCommonLabelBase{scrlayer}{% Umbruchkorrektur + So if the explanation above confused you, please don't worry about it.}{}% + \EndIndexGroup + + + \begin{Declaration} + \Macro{@mkleft}\Parameter{left mark}% + \Macro{@mkright}\Parameter{right mark}% + \Macro{@mkdouble}\Parameter{mark}% + \Macro{@mkboth}\Parameter{left mark}\Parameter{right mark} + \end{Declaration} + Within classes and packages, you may only want to use running heads if + automatic running heads are active (see the + \DescRef{scrlayer.option.automark} option and the + \DescRef{scrlayer.cmd.automark} command on + \DescPageRef{scrlayer-scrpage.cmd.automark}). In the standard \LaTeX{} + classes, this only works with \Macro{@mkboth}. This command corresponds to + either \Macro{@gobbletwo}, which simply consumes both mandatory arguments, + or \DescRef{scrlayer.cmd.markboth}, which sets both the \PValue{left mark} + and the \PValue{right mark}. Packages like \Package{babel} also change + \Macro{\@mkboth}, e.\,g., to enable language switching in the running head. + + However, if you want to change only the \PName{left mark} or the + \PName{right mark} without changing the other one, there is no corresponding + command. The \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } package itself needs such commands to implement automatic running heads. + So if \Macro{@mkleft}, for setting the left mark only, or \Macro{@mkright}, + for setting the right mark only, or \Macro{@mkdouble}, for setting both + marks with the same content, is undefined when loading + \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }, this package will define them. This definition uses the state of + \Macro{@mkboth} as an indication of whether to use automatic running heads. + The commands will set the marks only in the case of automatic running heads. + + Class and package authors can also fall back on these commands as appropriate + if they want to set the left or right the marks only if automatic running + heads are activated.% + \EndIndexGroup% +\fi% +% +\IfThisCommonLabelBase{scrlayer}{% + \par + For more information about manipulating the contents of page styles, see + also \autoref{sec:scrlayer-scrpage.pagestyle.content} starting at + \autopageref{sec:scrlayer-scrpage.pagestyle.content}.% +}{}% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: iso-latin-1 +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide.tex" +%%% TeX-PDF-mode: t +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-parmarkup.tex b/macros/latex/contrib/koma-script/source-doc/english/common-parmarkup.tex new file mode 100644 index 0000000000..647d09dde3 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-parmarkup.tex @@ -0,0 +1,270 @@ +% ====================================================================== +% common-parmarkup.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-parmarkup.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-parmarkup.tex} + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (common paragraph: Paragraph Markup)] +\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi\and + Karl Hagen} + +% Date of the translated German file: 2018-01-31 + +\section{Marking Paragraphs} +\seclabel{parmarkup}% +\BeginIndexGroup +\BeginIndex{}{paragraph>marking}% + +\IfThisCommonLabelBase{maincls}{% + The\textnote{paragraph indent vs. paragraph spacing} standard classes + normally set paragraphs\Index[indexmain]{paragraph} indented and without any + vertical, inter-paragraph space. This is the best solution when using a + regular page layout like the ones produced with the \Package{typearea} + package. If neither indentation nor vertical space is used, only the length + of the last line would give the reader a guide to the paragraph break. In + extreme cases, it is very difficult to tell whether a line is full or not. + Furthermore, typographers find that a signal given at the paragraph's end is + easily forgotten by the start of the next line. A signal at the paragraph's + beginning is more easily remembered. Inter-paragraph spacing has the + drawback of disappearing in some contexts. For instance, after a displayed + formula it would be impossible to detect if the previous paragraph continues + or a new one begins. Also, at the top of a new page, it might be necessary + to look at the previous page to determine if a new paragraph has been + started or not. All these problems disappear when using indentation. A + combination of indentation and vertical inter-paragraph spacing is redundant + and therefore should be avoided. Indentation\Index[indexmain]{indentation} + alone is sufficient. The only drawback of indentation is that it shortens + the line length. The use of inter-paragraph spacing\Index{paragraph>spacing} + is therefore justified when using short lines, such as in a newspaper.% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + The preliminaries of \autoref{sec:maincls.parmarkup}, + \autopageref{sec:maincls.parmarkup} explain why paragraph indentation is + preferred to paragraph spacing. But the elements to which this explanation + refers, for example figures, tables, lists, equations, and even new pages, + are rare in normal letters. Letters are usually not so long that an + unrecognised paragraph will have serious consequences to the readability + of the document. The arguments for indentation, therefore, are less + consequential for standard letters. This may be one reason that you often + find paragraphs in letters marked with vertical spacing. But two + advantages of paragraph indentation remain. One is that such a letter + stands out from the crowd. Another is that it maintains the \emph{brand + identity}, that is the uniform appearance, of all documents from a single + source.% + }{\InternalCommonFileUsageError}% +} % +\IfThisCommonFirstRun{}{% + Apart from these suggestions, the information described in + \autoref{sec:\ThisCommonFirstLabelBase.parmarkup} for the other + \KOMAScript{} classes is valid for letters too. So if you have already read + and understood \autoref{sec:\ThisCommonFirstLabelBase.parmarkup} you can + skip ahead to \autoref{sec:\ThisCommonLabelBase.parmarkup.next} on + \autopageref{sec:\ThisCommonLabelBase.parmarkup.next}.% + \IfThisCommonLabelBase{scrlttr2}{ % + This also applies if you work not with the + \Class{scrlttr2}\OnlyAt{scrlttr2} class but with the \Package{scrletter} + package. The package does not provide its own settings for paragraph + formatting but relies entirely on the class being used.% + }{}% +} + + +\begin{Declaration} + \OptionVName{parskip}{method} +\end{Declaration} +\IfThisCommonLabelBase{maincls}{% + Once in a while you may require a document layout with vertical + inter-paragraph spacing instead of indentation. The \KOMAScript{} classes + provide several ways to accomplish this with the + \Option{parskip}\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} option.% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + In letters, you often encounter paragraphs marked not by indentation of + the first line but by a vertical space between them. The \KOMAScript{} + class \Class{scrlttr2}\OnlyAt{scrlttr2} provides ways to accomplish this + with the \Option{parskip} option.% + }{\InternalCommonFileUsageError}% +} % +The \PName{method} consists of two elements. The first element is either +\PValue{full}\important{\OptionValue{parskip}{full}\\ + \OptionValue{parskip}{half}} or \PValue{half}, where \PValue{full} stands +for a paragraph spacing of one line and \PValue{half} stands for a paragraph +spacing of half a line. The second element consists of one of the characters +``\PValue{*}'', ``\PValue{+}'', or ``\PValue{-}'' and can be omitted. Without +the second element\important{\OptionVName{parskip}{distance}}, the final line +of a paragraph will end with a white space of at least 1\Unit{em}. With the +plus character as the second element% +\important{\OptionValue{parskip}{\PName{distance}+}}, the white space will be +at least one third\,---\,and with the +asterisk\important{\OptionValue{parskip}{\PName{distance}*}} one +fourth\,---\,the width of a normal line. With the minus variant% +\important{\OptionValue{parskip}{\PName{Abstand}-}}, no provision is made for +white space in the last line of a paragraph. + +You can change the setting at any time. If you change it inside the document, +the \Macro{selectfont}\IndexCmd{selectfont}% +\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.08}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.08}{\Class{scrlttr2}}% + }{% + \InternalComonFileUsageError% + }% +} % +command will be called implicitly. Changes to paragraph spacing within a +paragraph will not be visible until the end of the paragraph. + +In addition to the resulting eight combinations for \PName{method}, you can +use the values for simple switches shown in \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch}. Activating the option% +\important{\Option{parskip}\\\OptionValue{parskip}{true}} corresponds to using +\PValue{full} with no second element and therefore results in inter-paragraph +spacing of one line with at least 1\Unit{em} white space at the end of the +last line of each paragraph. Deactivating% +\important{\OptionValue{parskip}{false}} the option re-activates the default +indentation of 1\Unit{em} at the first line of the paragraph instead of +paragraph spacing. A summary of all possible values for \PName{method} are +shown in \autoref{tab:\ThisCommonFirstLabelBase.parskip}% +\IfThisCommonFirstRun{.% + \begin{desclist} + % Umbruchkorrektur + \vskip-\ht\strutbox + \renewcommand{\abovecaptionskipcorrection}{-\normalbaselineskip}% +% \begin{table} + \desccaption +% \caption + [{Available values of option \Option{parskip}}]{% + Available values of option \Option{parskip} to select + how paragraph are + distinguished\label{tab:\ThisCommonFirstLabelBase.parskip}% + }% + {% + Available values of option \Option{parskip} (\emph{continuation})% + }% + % \begin{desctabular} + \entry{\PValue{false}, \PValue{off}, \PValue{no}% + \IndexOption{parskip~=\textKValue{false}}}{% + paragraph indentation instead of vertical space; the last line of a + paragraph can be arbitrarily filled}% + \entry{\PValue{full}, \PValue{true}, \PValue{on}, \PValue{yes}% + \IndexOption{parskip~=\textKValue{full}}% + }{% + one line vertical space between paragraphs; there must be at least + 1\Unit{em} free space in the last line of a paragraph}% + \pventry{full-}{% + one line vertical space between paragraphs; the last line of a paragraph + can be arbitrarily filled\IndexOption{parskip~=\textKValue{full-}}}% + \pventry{full+}{% + one line vertical space between paragraphs; there must be at least a third + of a line of free space at the end of a + paragraph\IndexOption{parskip~=\textKValue{full+}}}% + \pventry{full*}{% + one line vertical space between paragraphs; there must be at least a + quarter of a line of free space at the end of a + paragraph\IndexOption{parskip~=\textKValue{full*}}}% + \pventry{half}{% + half a line vertical space between paragraphs; there must be at least + 1\Unit{em} free space in the last line of a + paragraph\IndexOption{parskip~=\textKValue{half}}}% + \pventry{half-}{% + one line vertical space between + paragraphs\IndexOption{parskip~=\textKValue{half-}}}% + \pventry{half+}{% + half a line vertical space between paragraphs; there must be at least a + third of a line of free space at the end of a + paragraph\IndexOption{parskip~=\textKValue{half+}}}% + \pventry{half*}{% + half a line vertical space between paragraphs; there must be at least a + quarter of a line of free space at the end of a + paragraph\IndexOption{parskip~=\textKValue{half*}}}% + \pventry{never}{% + there% + \IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.08}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + }{% + \IfThisCommonLabelBase{scrlttr2}{% + \ChangedAt{v3.08}{\Class{scrlttr2}}% + }{}% + } % + will be no inter-paragraph spacing even if additional vertical spacing is + needed for the vertical adjustment with + \Macro{flushbottom}\IndexCmd{flushbottom}% + \IndexOption{parskip~=\textKValue{never}}}% +% \end{desctabular} +% \end{table}% + \end{desclist}% +}{ at \autopageref{tab:\ThisCommonFirstLabelBase.parskip}.} + +All\textnote{Attention!} eight \PValue{full} and \PValue{half} option values +also change the spacing before, after, and inside list environments. This +prevents these environments or the paragraphs inside them from having +a larger separation than that between the paragraphs of normal text.% +\IfThisCommonLabelBase{maincls}{ % + Additionally, these options ensure that the table of contents and the lists + of figures and tables are set without any additional spacing.% +}{ % + Several elements of the letterhead are always set without inter-paragraph + spacing.% +}% + +The default\textnote{default} behaviour of \KOMAScript{} is +\OptionValue{parskip}{false}. In this case, there is no spacing between +paragraphs, only an indentation of the first line by 1\Unit{em}.% +% +\EndIndexGroup +% +\EndIndexGroup + + +%%% Local Variables: +%%% mode: latex +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-textmarkup.tex b/macros/latex/contrib/koma-script/source-doc/english/common-textmarkup.tex new file mode 100644 index 0000000000..49cbe456ed --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-textmarkup.tex @@ -0,0 +1,805 @@ +% ====================================================================== +% common-textmarkup.tex +% Copyright (c) Markus Kohm, 2001-2019 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-textmarkup.tex +% Copyright (c) Markus Kohm, 2001-2019 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-textmarkup.tex} + [$Date: 2019-01-15 08:29:44 +0100 (Tue, 15 Jan 2019) $ + KOMA-Script guide (common paragraphs)] +\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi\and + Karl Hagen} + +% Date of the translated German file: 2018-07-20 + +\section{Text Markup} +\seclabel{textmarkup}% +\BeginIndexGroup% +\BeginIndex{}{text>markup}% +\BeginIndex{}{font}% + +\IfThisCommonFirstRun{}{% + The information in in \autoref{sec:\ThisCommonFirstLabelBase.textmarkup} + largely applies to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.textmarkup}, you can + \IfThisCommonLabelBaseOneOf{scrextend,scrjura,scrlayer-notecolumn}{}{% + limit yourself to examining + \autoref{tab:\ThisCommonLabelBase.fontelements}, + \autopageref{tab:\ThisCommonLabelBase.fontelements} and then }% + skip ahead to \autoref{sec:\ThisCommonLabelBase.textmarkup.next}, + \autopageref{sec:\ThisCommonLabelBase.textmarkup.next}.% + \IfThisCommonLabelBase{scrextend}{\ In this case, however, + note\textnote{limitation} that \Package{scrextend} supports only the + elements for the document title, the dictum, the footnotes, and the + \DescRef{maincls.env.labeling} environment. from + \autoref{tab:maincls.fontelements}, + \autopageref{tab:maincls.fontelements}. Although the + \DescRef{maincls.fontelement.disposition} element exists, + \Package{scrextend} uses it only for the document title.% + }{}% +} + +% Umbruchkorrektur +\IfThisCommonLabelBase{scrlayer-scrpage}{}{% + {\LaTeX} offers different possibilities for logical and direct + markup\Index{logical markup}\Index{markup} of text. % + \IfThisCommonLabelBaseOneOf{scrlttr2}{}{% + In addition to the choice of the font, this includes commands for choosing + the font size and orientation. % + } For more information about the standard font facilities, see + \cite{lshort}, \cite{latex:usrguide}, and \cite{latex:fntguide}.} + +\IfThisCommonLabelBaseOneOf{scrlayer-scrpage,scrjura,scrlayer-notecolumn}{% + \iffalse}{% + \csname iftrue\endcsname}% + \begin{Declaration} + \Macro{textsuperscript}\Parameter{text}% + \Macro{textsubscript}\Parameter{text} + \end{Declaration} + The \LaTeX{} kernel defines the command + \Macro{textsuperscript}\IndexCmd{textsuperscript} to put text in + superscript\Index{text>superscript}\Index{superscript}. Unfortunately, + \LaTeX{}\textnote{\Latex~2015/01/01} itself did not offer a command to + produce text in subscript\Index{text>subscript}\Index{subscript} until + release 2015/01/01. \KOMAScript{} defines \Macro{textsubscript} for this + purpose. % + \ifthiscommonfirst + \begin{Example} + \phantomsection + \xmpllabel{cmd.textsubscript}% + You are writing a text on human metabolism. From time to time you + have to give some simple chemical formulas in which the numbers are + in subscript. To allow for logical markup, you first define in the + document preamble or in a separate package: +\begin{lstcode} + \newcommand*{\molec}[2]{#1\textsubscript{#2}} +\end{lstcode} + \newcommand*{\molec}[2]{#1\textsubscript{#2}} + Using this you then write: +\begin{lstcode} + The cell produces its energy partly from the reaction of \molec C6\molec + H{12}\molec O6 and \molec O2 to produce \molec H2\Molec O{} and + \molec C{}\molec O2. However, arsenic (\molec{As}{}) has quite a + detrimental effect on the metabolism. +\end{lstcode} + The output looks as follows: + \begin{ShowOutput} + The cell produces its energy partly from the reaction of \molec C6\molec + H{12}\molec O6 and \molec O2 to produce \molec H2\molec O{} and + \molec C{}\molec O2. However, arsenic (\molec{As}{}) has quite a + detrimental effect on the metabolism. + \end{ShowOutput} + + Some time later you decide that the chemical formulas should be + typeset in sans serif. Now you can see the advantages of using + logical markup. You only have the redefine the \Macro{molec} + command: +\begin{lstcode} + \newcommand*{\molec}[2]{\textsf{#1\textsubscript{#2}}} +\end{lstcode} + \renewcommand*{\molec}[2]{\textsf{#1\textsubscript{#2}}} + Now the output in the whole document changes to: + \begin{ShowOutput} + The cell produces its energy partly from the reaction of \molec + C6\molec H{12}\molec O6 and \molec O2 to produce \molec H2\molec + O{} and \molec C{}\molec O2. However, arsenic (\molec{As}{}) has + quite a detrimental effect on the metabolism. + \end{ShowOutput} + \end{Example} + \iftrue + \begin{Explain} + The example above uses the notation ``\verb|\molec C6|''. + This makes use of the fact that arguments consisting of only one + character do not have to be enclosed in parentheses. That is why + ``\verb|\molec C6|'' is similar to ``\verb|\molec{C}{6}|''. You + may already be familiar with this notation from indices or powers in + mathematical environments, such as ``\verb|$x^2$|'' instead of + ``\verb|$x^{2}$|'' + for ``$x^2$''. + \end{Explain} + \else % maybe some time I've made an English book + Advanced users can find information about the reason the example above + does work unless you put all arguments of \Macro{molec} into braces in + \autoref{sec:experts.knowhow}, + \DescPageRef{experts.macroargs}.% + \fi% + \else% + You can find an example that uses it in + \autoref{sec:\ThisCommonFirstLabelBase.textmarkup}, + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.textsubscript}. + \fi% + \EndIndexGroup% +\fi + + +\begin{Declaration} + \Macro{setkomafont}\Parameter{element}\Parameter{commands}% + \Macro{addtokomafont}\Parameter{element}\Parameter{commands}% + \Macro{usekomafont}\Parameter{element} +\end{Declaration}% +With% +\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v2.8p}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{} the help of the \Macro{setkomafont} and \Macro{addtokomafont} +commands, you can attach particular font styling \PName{commands} that change +the appearance of a given \PName{element}. Theoretically, all statements, +including literal text, can be used as \PName{commands}. You +should\textnote{Attention!}, however, limit yourself to those statements that +really change font attributes only. These are usually commands like +\Macro{rmfamily}, \Macro{sffamily}, \Macro{ttfamily}, \Macro{upshape}, +\Macro{itshape}, \Macro{slshape}, \Macro{scshape}, \Macro{mdseries}, +\Macro{bfseries}, \Macro{normalfont}, as well as the font size commands +\Macro{Huge}, \Macro{huge}, \Macro{LARGE}, \Macro{Large}, \Macro{large}, +\Macro{normalsize}, \Macro{small}, \Macro{footnotesize}, \Macro{scriptsize}, +and \Macro{tiny}. You can find these commands explained in \cite{lshort}, +\cite{latex:usrguide}, or \cite{latex:fntguide}. Colour switching commands +like \Macro{normalcolor} (see \cite{package:graphics} and +\cite{package:xcolor}) are also acceptable.% +\iffalse % Umbruchkorrekturtext + \ The behaviour when using other commands, especially those that lead to + redefinitions or generate output, is undefined. Strange behaviour is possible + and does not represent a bug. +\else + \ The use of other commands, in particular those that redefine things or + or lead to output, is not supported. Strange behaviour is possible in these + cases and does not represent a bug. +\fi + +The command \Macro{setkomafont} provides an element with a completely new +definition of its font styling. In contrast, the \Macro{addtokomafont} command +merely extends an existing definition. You should not use either command +inside the document body but only in the preamble. For examples of their use, +refer to the sections for the respective element.% +\IfThisCommonLabelBase{scrlayer-notecolumn}{}{% + \ The name and meaning of each element + \IfThisCommonLabelBaseOneOf{scrlayer-scrpage,scrjura}{, as well as their + defaults,}{} are listed in \IfThisCommonLabelBase{scrextend}{% + \autoref{tab:maincls.fontelements}, \autopageref{tab:maincls.fontelements} + }{% + \autoref{tab:\ThisCommonLabelBase.fontelements} % + }.% + \IfThisCommonLabelBase{scrextend}{ % + However, in \Package{scrextend} only\textnote{limitation} the listed + elements for the document title, dictum, footnotes, and the + \DescRef{maincls.env.labeling} environment are supported. Although the + \DescRef{maincls.fontelement.disposition} element exists, + \Package{scrextend} uses it only for the document title.% + }{% + \IfThisCommonLabelBase{scrlayer-scrpage}{ % + The specified defaults apply only if the corresponding element has not + already been defined before loading \Package{scrlayer-scrpage}. For + example, the \KOMAScript classes define + \DescRef{maincls.fontelement.pageheadfoot}, and then + \Package{scrlayer-scrpage} uses the setting it finds.% + }{% + \IfThisCommonLabelBase{scrjura}{}{ % + The default values can be found in the corresponding sections.% + }% + }% + }% +}% + +\IfThisCommonLabelBaseOneOf{scrlttr2,scrextend}{% Umbruchvarianten + The \Macro{usekomafont} command can be used to switch the current font style + to the specified \PName{Element}.% +}{% + With the \Macro{usekomafont} command, the current font style can be changed + to the one defined for the specified \PName{element}.% +} + +\IfThisCommonLabelBase{maincls}{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + \phantomsection\xmpllabel{cmd.setkomafont}% + Suppose you want to use the same font specification for the element + \DescRef{\ThisCommonLabelBase.fontelement.captionlabel} + that is used with + \DescRef{\ThisCommonLabelBase.fontelement.descriptionlabel}. This can be + easily done with: +\begin{lstcode} + \setkomafont{captionlabel}{% + \usekomafont{descriptionlabel}% + } +\end{lstcode} + You can find other examples in the explanation of each element. + \end{Example} + + \begin{desclist} + \desccaption{% + Elements whose font style can be changed in \Class{scrbook}, + \Class{scrreprt} or \Class{scrartcl} with \Macro{setkomafont} and + \Macro{addtokomafont}% + \label{tab:maincls.fontelements}% + \label{tab:scrextend.fontelements}% + }{% + Elements whose font style can be changed (\emph{continued})% + }% + \feentry{author}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}\and \Package{scrextend}}% + author of the document in the title, i.\,e., the argument of + \DescRef{\ThisCommonLabelBase.cmd.author} when + \DescRef{\ThisCommonLabelBase.cmd.maketitle} is used (see + \autoref{sec:maincls.titlepage}, \DescPageRef{maincls.cmd.author})}% + \feentry{caption}{text of a figure or table caption (see + \autoref{sec:maincls.floats}, \DescPageRef{maincls.cmd.caption})}% + \feentry{captionlabel}{label of a figure or table caption; applied in + addition to the \DescRef{\ThisCommonLabelBase.fontelement.caption} + element (see \autoref{sec:maincls.floats}, + \DescPageRef{maincls.cmd.caption})}% + \feentry{chapter}{title of the sectioning command + \DescRef{\ThisCommonLabelBase.cmd.chapter} (see + \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.chapter})}% + \feentry{chapterentry}{% + table of contents entry for the sectioning command + \DescRef{\ThisCommonLabelBase.cmd.chapter} (see + \autoref{sec:maincls.toc}, \DescPageRef{maincls.cmd.tableofcontents})}% + \feentry{chapterentrydots}{% + \ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}}% + optional points connecting table-of-content entries for the + \DescRef{\ThisCommonLabelBase.cmd.chapter} level, differing from the + \DescRef{\ThisCommonLabelBase.fontelement.chapterentrypagenumber} + element (see \autoref{sec:maincls.toc}, + \DescPageRef{maincls.cmd.tableofcontents})}% + \feentry{chapterentrypagenumber}{% + page number of the table of contents entry for the sectioning command + \DescRef{\ThisCommonLabelBase.cmd.chapter}, differing from the element + \DescRef{\ThisCommonLabelBase.fontelement.chapterentry} (see + \autoref{sec:maincls.toc}, \DescPageRef{maincls.cmd.tableofcontents})}% + \feentry{chapterprefix}{% + label, e.\,g., ``Chapter'', appearing before the chapter number in both + \OptionValueRef{maincls}{chapterprefix}{true} and + \OptionValueRef{maincls}{appendixprefix}{true} (see + \autoref{sec:maincls.structure}, + \DescPageRef{maincls.option.chapterprefix})}% + \feentry{date}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}\and \Package{scrextend}}% + date of the document in the main title, i.\,e., the argument of + \DescRef{\ThisCommonLabelBase.cmd.date} when + \DescRef{\ThisCommonLabelBase.cmd.maketitle} is used (see + \autoref{sec:maincls.titlepage}, \DescPageRef{maincls.cmd.date})}% + \feentry{dedication}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}\and \Package{scrextend}}% + dedication page after the main title, i.\,e., the argument of + \DescRef{\ThisCommonLabelBase.cmd.dedication} when + \DescRef{\ThisCommonLabelBase.cmd.maketitle} is used (see + \autoref{sec:maincls.titlepage}, \DescPageRef{maincls.cmd.dedication})}% + \feentry{descriptionlabel}{labels, i.\,e., the optional argument of + \DescRef{\ThisCommonLabelBase.cmd.item.description} in the + \DescRef{\ThisCommonLabelBase.env.description} environment (see + \autoref{sec:maincls.lists}, \DescPageRef{maincls.env.description})}% + \feentry{dictum}{dictum or epigraph (see \autoref{sec:maincls.dictum}, + \DescPageRef{maincls.cmd.dictum})}% + \feentry{dictumauthor}{author of a dictum or epigraph; applied in addition + to the element \DescRef{\ThisCommonLabelBase.fontelement.dictum} (see + \autoref{sec:maincls.dictum}, \DescPageRef{maincls.cmd.dictum})}% + \feentry{dictumtext}{alternative name for + \DescRef{\ThisCommonLabelBase.fontelement.dictum}}% + \feentry{disposition}{all sectioning command titles, i.\,e., the arguments + of \DescRef{\ThisCommonLabelBase.cmd.part} down to + \DescRef{\ThisCommonLabelBase.cmd.subparagraph} and + \DescRef{\ThisCommonLabelBase.cmd.minisec}, including the title of the + abstract; applied before the element of the respective unit (see + \autoref{sec:maincls.structure}, \autopageref{sec:maincls.structure})}% + \feentry{footnote}{footnote text and marker (see + \autoref{sec:maincls.footnotes}, \DescPageRef{maincls.cmd.footnote})}% + \feentry{footnotelabel}{marker for a footnote; applied in addition to the + element \DescRef{\ThisCommonLabelBase.fontelement.footnote} (see + \autoref{sec:maincls.footnotes}, \DescPageRef{maincls.cmd.footnote})}% + \feentry{footnotereference}{footnote reference in the text (see + \autoref{sec:maincls.footnotes}, \DescPageRef{maincls.cmd.footnote})}% + \feentry{footnoterule}{% + horizontal rule\ChangedAt{v3.07}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} above the footnotes at the end + of the text area (see \autoref{sec:maincls.footnotes}, + \DescPageRef{maincls.cmd.setfootnoterule})}% + \feentry{labelinglabel}{labels, i.\,e., the optional argument of + \DescRef{\ThisCommonLabelBase.cmd.item.labeling} in the + \DescRef{\ThisCommonLabelBase.env.labeling} environment (see + \autoref{sec:maincls.lists}, \DescPageRef{maincls.env.labeling})}% + \feentry{labelingseparator}{separator, i.\,e., the optional argument of + the \DescRef{\ThisCommonLabelBase.env.labeling} environment; applied in + addition to the element + \DescRef{\ThisCommonLabelBase.fontelement.labelinglabel} (see + \autoref{sec:maincls.lists}, \DescPageRef{maincls.env.labeling})}% + \feentry{minisec}{title of \DescRef{\ThisCommonLabelBase.cmd.minisec} (see + \autoref{sec:maincls.structure} ab \DescPageRef{maincls.cmd.minisec})}% + \feentry{pagefoot}{only used if package \Package{scrlayer-scrpage} has + been loaded (see \autoref{cha:scrlayer-scrpage}, + \DescPageRef{scrlayer-scrpage.fontelement.pagefoot})}% + \feentry{pagehead}{alternative name for + \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}}% + \feentry{pageheadfoot}{the header and footer of a page (see + \autoref{sec:maincls.pagestyle} from + \autopageref{sec:maincls.pagestyle})}% + \feentry{pagenumber}{page number in the header or footer (see + \autoref{sec:maincls.pagestyle})}% + \feentry{pagination}{alternative name for + \DescRef{\ThisCommonLabelBase.fontelement.pagenumber}}% + \feentry{paragraph}{title of the sectioning command + \DescRef{\ThisCommonLabelBase.cmd.paragraph} (see + \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.paragraph})}% + \feentry{part}{title of the \DescRef{\ThisCommonLabelBase.cmd.part} + sectioning command, without the line containing the part number (see + \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.part})}% + \feentry{partentry}{% + table of contents entry for the sectioning command + \DescRef{\ThisCommonLabelBase.cmd.part} (see \autoref{sec:maincls.toc}, + \DescPageRef{maincls.cmd.tableofcontents})}% + \feentry{partentrypagenumber}{% + page number of the table of contents entry for the sectioning command + \DescRef{\ThisCommonLabelBase.cmd.part}; applied in addition to the + element \DescRef{\ThisCommonLabelBase.fontelement.partentry} (see + \autoref{sec:maincls.toc}, \DescPageRef{maincls.cmd.tableofcontents})}% + \feentry{partnumber}{line containing the part number in a title of the + sectioning command \DescRef{\ThisCommonLabelBase.cmd.part} (see + \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.part})}% + \feentry{publishers}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}\and \Package{scrextend}}% + publishers of the document in the main title, i.\,e., the argument of + \DescRef{\ThisCommonLabelBase.cmd.publishers} when + \DescRef{\ThisCommonLabelBase.cmd.maketitle} is used (see + \autoref{sec:maincls.titlepage}, \DescPageRef{maincls.cmd.publishers})}% + \feentry{section}{title of the sectioning command + \DescRef{\ThisCommonLabelBase.cmd.section} (see + \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.section})}% + \feentry{sectionentry}{% + table of contents entry for sectioning command + \DescRef{\ThisCommonLabelBase.cmd.section} (only available in + \Class{scrartcl}, see \autoref{sec:maincls.toc}, + \DescPageRef{maincls.cmd.tableofcontents})}% + \feentry{sectionentrypagenumber}{% + page number of the table of contents entry for the sectioning command + \DescRef{\ThisCommonLabelBase.cmd.section}; applied in addition to + element \DescRef{\ThisCommonLabelBase.fontelement.sectionentry} (only + available in \Class{scrartcl, see \autoref{sec:maincls.toc}, + \DescPageRef{maincls.cmd.tableofcontents}})}% + \feentry{sectioning}{alternative name for + \DescRef{\ThisCommonLabelBase.fontelement.disposition}}% + \feentry{subject}{% + topic of the document, i.\,e., the argument of + \DescRef{\ThisCommonLabelBase.cmd.subject} on the main title page (see + \autoref{sec:maincls.titlepage}, \DescPageRef{maincls.cmd.subject})}% + \feentry{subparagraph}{title of the sectioning command + \DescRef{\ThisCommonLabelBase.cmd.subparagraph} (see + \autoref{sec:maincls.structure}, + \DescPageRef{maincls.cmd.subparagraph})}% + \feentry{subsection}{title of the sectioning command + \DescRef{\ThisCommonLabelBase.cmd.subsection} (see + \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.subsection})}% + \feentry{subsubsection}{title of the sectioning command + \DescRef{\ThisCommonLabelBase.cmd.subsubsection} (see + \autoref{sec:maincls.structure}, + \DescPageRef{maincls.cmd.subsubsection})}% + \feentry{subtitle}{% + subtitle of the document, i.\,e., the argument of + \DescRef{\ThisCommonLabelBase.cmd.subtitle} on the main title page (see + \autoref{sec:maincls.titlepage}, \DescPageRef{maincls.cmd.title})}% + \feentry{title}{main title of the document, i.\,e., the argument of + \DescRef{\ThisCommonLabelBase.cmd.title} (for details about the title + size see the additional note in the text of + \autoref{sec:maincls.titlepage} from \DescPageRef{maincls.cmd.title})}% + \feentry{titlehead}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}\and \Package{scrextend}}% + heading above the main title of the document, i.\,e., the argument of + \DescRef{\ThisCommonLabelBase.cmd.titlehead} when + \DescRef{\ThisCommonLabelBase.cmd.maketitle} is used (see + \autoref{sec:maincls.titlepage}, \DescPageRef{maincls.cmd.titlehead})}% + \end{desclist} +\else + \IfThisCommonLabelBase{scrextend}{\iftrue}{\csname iffalse\endcsname} + \begin{Example} + Suppose you want to print the document title in a red serif font. + You can do this using: +\begin{lstcode} + \setkomafont{title}{\color{red}} +\end{lstcode} + You will need the \Package{color} or the \Package{xcolor} package for + the \Macro{color}\PParameter{red} command. Using \Macro{normalfont} is + unnecessary in this case because it is already part of the definition of + the title itself. This\textnote{Attention!} example also needs the + \OptionValueRef{scrextend}{extendedfeature}{title} option (see + \autoref{sec:scrextend.optionalFeatures}, + \DescPageRef{scrextend.option.extendedfeature}). + \end{Example} + \else + \IfThisCommonLabelBase{scrlttr2}{% + You can find a general example that uses both \Macro{setkomafont} and + \Macro{usekomafont} in \autoref{sec:maincls.textmarkup} on + \PageRefxmpl{maincls.cmd.setkomafont}. + + \begin{desclist} + \desccaption{% + Elements whose font style can be changed in the \Class{scrlttr2} + class or the \Package{scrletter} package with the + \Macro{setkomafont} and \Macro{addtokomafont} + commands\label{tab:scrlttr2.fontelements}% + }{% + Elements whose font style can be changed (\emph{continued})% + }% + \feentry{addressee}{recipient's name and address in the address field + (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.option.addrfield})}% + \feentry{backaddress}{% + return address for a window envelope + (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.option.backaddress})}% + \feentry{descriptionlabel}{% + label, i.\,e. the optional argument of + \DescRef{\ThisCommonLabelBase.cmd.item.description}, in a + \DescRef{\ThisCommonLabelBase.env.description} environment + (\autoref{sec:scrlttr2.lists}, + \DescPageRef{scrlttr2.env.description})}% + \feentry{foldmark}{% + fold mark on the letterhead page; allows change of line colour + (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.option.foldmarks})}% + \feentry{footnote}{% + footnote text and marker (\autoref{sec:scrlttr2.footnotes}, + \DescPageRef{scrlttr2.cmd.footnote})}% + \feentry{footnotelabel}{% + footnote marker; applied in addition to the + \DescRef{\ThisCommonLabelBase.fontelement.footnote} element + (\autoref{sec:scrlttr2.footnotes}, + \DescPageRef{scrlttr2.cmd.footnote})}% + \feentry{footnotereference}{% + footnote reference in the text (\autoref{sec:scrlttr2.footnotes}, + \DescPageRef{scrlttr2.cmd.footnote})}% + \feentry{footnoterule}{% + horizontal rule\ChangedAt{v3.07}{\Class{scrlttr2}} above the + footnotes at the end of the text area + (\autoref{sec:maincls.footnotes}, + \DescPageRef{maincls.cmd.setfootnoterule})}% + \feentry{fromaddress}{% + sender's address in the letterhead + (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.variable.fromaddress})}% + \feentry{fromname}{% + sender's name in the letterhead, not including + \PValue{fromaddress} (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.variable.fromname})}% + \feentry{fromrule}{% + horizontal rule in the letterhead; intended for + colour changes (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.option.fromrule})}% + \feentry{labelinglabel}{% + labels, i.\,e. the optional argument of + \DescRef{\ThisCommonLabelBase.cmd.item.labeling} in the + \DescRef{\ThisCommonLabelBase.env.labeling} environment % + (see \autoref{sec:scrlttr2.lists}, + \DescPageRef{scrlttr2.env.labeling})}% + \feentry{labelingseparator}{% + separator, i.\,e. the optional argument of the + \DescRef{\ThisCommonLabelBase.env.labeling} environment; applied + in addition to the + \DescRef{\ThisCommonLabelBase.fontelement.labelinglabel} element + (see \autoref{sec:scrlttr2.lists}, + \DescPageRef{scrlttr2.env.labeling})}% + \feentry{pagefoot}{% + used after the + \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot} element for + the footer defined with the + \DescRef{scrlttr2.variable.nextfoot}\IndexVariable{nextfoot} + variable, or for the footer of the \Package{scrlayer-scrpage} + package (\autoref{cha:scrlayer-scrpage}, + \DescPageRef{scrlayer-scrpage.fontelement.pagefoot})}% + \feentry{pagehead}{% + alternative name for + \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}}% + \feentry{pageheadfoot}{% + the header and footer of a page for all page styles + that have been defined using \KOMAScript{} + (\autoref{sec:maincls.pagestyle}, + \DescPageRef{\ThisCommonLabelBase.fontelement.pageheadfoot})}% + \feentry{pagenumber}{% + page number in the header or footer % + (\autoref{sec:maincls.pagestyle}, + \DescPageRef{\ThisCommonLabelBase.fontelement.pagenumber})}% + \feentry{pagination}{% + alternative name for + \DescRef{\ThisCommonLabelBase.fontelement.pagenumber}}% + \feentry{placeanddate}{% + \ChangedAt{v3.12}{\Class{scrlttr2}}% + place and date, if a date line will be used instead of a normal + reference line (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.variable.placeseparator})}% + \feentry{refname}{% + description or title of the fields in the reference line % + (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.variable.yourref})}% + \feentry{refvalue}{% + content of the fields in the reference line % + (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.variable.yourref})}% + \feentry{specialmail}{% + delivery type in the address field % + (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.variable.specialmail})}% + \feentry{lettersubject}{% + \ChangedAt{v3.17}{\Class{scrlttr2}\and \Package{scrletter}}% + subject in the opening of the letter % + (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.variable.subject})}% + \feentry{lettertitle}{% + \ChangedAt{v3.17}{\Class{scrlttr2}\and \Package{scrletter}}% + title in the opening of the letter % + (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.variable.title})}% + \feentry{toaddress}{% + variation of the + \DescRef{\ThisCommonLabelBase.fontelement.addressee} element to + format the recipient's address, not including the name, in the + address field (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.variable.toaddress})}% + \feentry{toname}{% + variation of the + \DescRef{\ThisCommonLabelBase.fontelement.addressee} element to + format the recipient's name in the address field + (\autoref{sec:scrlttr2.firstpage}, + \DescPageRef{scrlttr2.variable.toname})}% + \end{desclist} + }{% + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \begin{desclist} + \desccaption[{Elements of \Package{scrlayer-scrpage} whose font + styles can be changed with the \Macro{setkomafont} and + \Macro{addtokomafont} commands}]% + {Elements of \Package{scrlayer-scrpage} whose font styles can be + changed with the \Macro{setkomafont} and \Macro{addtokomafont} + commands, and their defaults, if they have not been defined + before loading \Package{scrlayer-scrpage}% + \label{tab:scrlayer-scrpage.fontelements}% + }% + {Elements whose font style can be changed (\emph{continued})}% + \feentry{footbotline}{% + horizontal line below the footer of a page style defined using + \Package{scrlayer-scrpage}. The font will be applied after + \Macro{normalfont}\IndexCmd{normalfont} and the fonts of elements + \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}% + \IndexFontElement{pageheadfoot} and + \DescRef{\ThisCommonLabelBase.fontelement.pagefoot}% + \IndexFontElement{pagefoot}. It is recommended to use this element + for colour changes only.\par + \mbox{Default: \emph{empty}}% + }% + \feentry{footsepline}{% + horizontal line above the footer of a page style defined using + \Package{scrlayer-scrpage}. The font will be applied after + \Macro{normalfont}\IndexCmd{normalfont} and the fonts of elements + \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}% + \IndexFontElement{pageheadfoot} and + \DescRef{\ThisCommonLabelBase.fontelement.pagefoot}% + \IndexFontElement{pagefoot}. It is recommended to use this element + for colour changes only.\par + \mbox{Default: \emph{empty}}% + }% + \feentry{headsepline}{% + horizontal line below the header of a page style defined using + \Package{scrlayer-scrpage}. The font will be applied after + \Macro{normalfont}\IndexCmd{normalfont} and the fonts of elements + \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}% + \IndexFontElement{pageheadfoot} and + \DescRef{scrlayer-scrpage.fontelement.pagehead}% + \IndexFontElement{pagehead}. It is recommended to use this element + for colour changes only.\par + Default: \emph{empty}% + }% + \feentry{headtopline}{% + horizontal line above the header of a page style defined using + \Package{scrlayer-scrpage}. The font will be applied after + \Macro{normalfont}\IndexCmd{normalfont} and the fonts of elements + \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}% + \IndexFontElement{pageheadfoot} and + \DescRef{scrlayer-scrpage.fontelement.pagehead}% + \IndexFontElement{pagehead}. It is recommended to use this element + for colour changes only.\par + \mbox{Default: \emph{empty}}% + }% + \feentry{pagefoot}{% + contents of the page footer of a page style defined using + \Package{scrlayer-scrpage}. The font will be applied after + \Macro{normalfont}\IndexCmd{normalfont} and the font of element + \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}% + \IndexFontElement{pageheadfoot}.\par + \mbox{Default: \emph{empty}}% + }% + \feentry{pagehead}{% + contents of the page header of a page style defined using + \Package{scrlayer-scrpage}. The font will be applied after + \Macro{normalfont}\IndexCmd{normalfont} and the font of element + \DescRef{\ThisCommonLabelBase.fontelement.pageheadfoot}% + \IndexFontElement{pageheadfoot}.\par + \mbox{Default: \emph{empty}}% + }% + \feentry{pageheadfoot}{% + contents of the page header or footer of a page style defined + using \Package{scrlayer-scrpage}. The font will be applied after + \Macro{normalfont}\IndexCmd{normalfont}.\par + \mbox{Default: \Macro{normalcolor}\Macro{slshape}}% + }% + \feentry{pagenumber}{% + pagination set with + \DescRef{\ThisCommonLabelBase.cmd.pagemark}. If you redefine + \DescRef{\ThisCommonLabelBase.cmd.pagemark}, you have to be sure + that your redefinition also uses + \Macro{usekomafont}\PParameter{pagenumber}!\par + \mbox{Default: \Macro{normalfont}}% + }% + \end{desclist} + }{% + \IfThisCommonLabelBase{scrjura}{% + \begin{table} + \caption{Elements whose \Package{scrjura} font styles can be + changed with \Macro{setkomafont} and \Macro{addtokomafont}, + including their default settings}% + \label{tab:scrjura.fontelements}% + \begin{desctabular} + \feentry{Clause}{% + alias for \FontElement{\PName{environment name}.Clause} + within a contract environment, for example + \FontElement{contract.Clause} within + \DescRef{\ThisCommonLabelBase.env.contract}; if no + corresponding element is defined, + \FontElement{contract.Clause} is used% + }% + \feentry{contract.Clause}{% + heading of a paragraph within + \DescRef{\ThisCommonLabelBase.env.contract} (see + \autoref{sec:\ThisCommonLabelBase.contract}, + \DescPageRef{\ThisCommonLabelBase.fontelement.contract.Clause}); + \par + \mbox{Default: \Macro{sffamily}\Macro{bfseries}\Macro{large}}% + }% + \entry{\DescRef{\ThisCommonLabelBase.fontelement./Name/.Clause}}{% + \IndexFontElement[indexmain]{\PName{name}.Clause}% + heading of a paragraph within a \PName{name} environment + defined with + \DescRef{\ThisCommonLabelBase.cmd.DeclareNewJuraEnvironment} + as long as the setting was made with \Option{ClauseFont} or + the item was subsequently defined (see + \autoref{sec:\ThisCommonLabelBase.newenv}, + \DescPageRef{\ThisCommonLabelBase.fontelement./Name/.Clause}); + \par + \mbox{Default: \emph{none}}% + }% + \feentry{parnumber}{% + paragraph numbers within a contract environment (see + \autoref{sec:\ThisCommonLabelBase.par}, + \DescPageRef{\ThisCommonLabelBase.fontelement.parnumber});\par + \mbox{Default: \emph{empty}}% + }% + \feentry{sentencenumber}{% + \ChangedAt{v3.26}{\Package{scrjura}}% + sentence number of \DescRef{\ThisCommonLabelBase.cmd.Sentence} + (see \autoref{sec:\ThisCommonLabelBase.sentence}, + \DescPageRef{% + \ThisCommonLabelBase.fontelement.sentencenumber});\par + \mbox{Default: \emph{empty}}% + }% + \end{desctabular} + \end{table} + }{% + \IfThisCommonLabelBase{scrlayer-notecolumn}{}{% + \InternalCommonFileUsageError% + }% + }% + }% + }% + \fi% +\fi +\EndIndexGroup + + +\begin{Declaration} + \Macro{usefontofkomafont}\Parameter{element}% + \Macro{useencodingofkomafont}\Parameter{element}% + \Macro{usesizeofkomafont}\Parameter{element}% + \Macro{usefamilyofkomafont}\Parameter{element}% + \Macro{useseriesofkomafont}\Parameter{element}% + \Macro{useshapeofkomafont}\Parameter{element} +\end{Declaration} +Sometimes\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}\and \Package{scrextend}}, although this is not recommended, +the font setting of an element is used for settings that are not actually +related to the font. If you want to apply only the font setting of an element +but not those other settings, you can use \Macro{usefontofkomafont} instead of +\DescRef{\ThisCommonLabelBase.cmd.usekomafont}. This will activate the font +size and baseline skip, the font encoding, the font family, the font series, +and the font shape of an element, but no further settings as long as those +further settings are local. + +You can also switch to a single one of those attributes using one of the other +commands. Note that \Macro{usesizeofkomafont} uses both the font +size and the baseline skip.% +% +\IfThisCommonLabelBase{scrextend}{% Umbruchvariante! +}{% + \IfThisCommonLabelBase{scrjura}{% + \par% + However, the misuse of the font settings is strongly discouraged (see + \autoref{sec:maincls-experts.experts}, + \DescPageRef{maincls-experts.cmd.addtokomafontrelaxlist})!% + }{% + \par% + However, you should not take these commands as legitimizing the insertion + of arbitrary commands in an element's font setting. To do so can lead + quickly to errors (see \autoref{sec:maincls-experts.experts}, + \DescPageRef{maincls-experts.cmd.addtokomafontrelaxlist}).% + }% +}% +\EndIndexGroup +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-titles.tex b/macros/latex/contrib/koma-script/source-doc/english/common-titles.tex new file mode 100644 index 0000000000..e061743806 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-titles.tex @@ -0,0 +1,679 @@ +% ====================================================================== +% common-titles.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-titles.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-titles.tex} + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (common paragraphs)] + +\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi\and + Karl Hagen} + +% Date of the translated German file: 2018-01-30 + +\section{Document Titles} +\seclabel{titlepage}% +\BeginIndexGroup +\BeginIndex{}{title}% + +\IfThisCommonFirstRun{}{% + This information in \autoref{sec:\ThisCommonFirstLabelBase.titlepage} + largely applies to this chapter. So if you have already read and understood + \autoref{sec:\ThisCommonFirstLabelBase.titlepage}, you can skip to + \autoref{sec:\ThisCommonLabelBase.titlepage.next}, + \autopageref{sec:\ThisCommonLabelBase.titlepage.next}.% +}% +\IfThisCommonLabelBase{scrextend}{\iftrue}{\csname iffalse\endcsname}% + \ However,\textnote{Attention!} the capabilities of \Package{scrextend} + for handling the document title are part of the optional, advanced + features. Therfore they are only available, if + \OptionValueRef{\ThisCommonLabelBase}{extendedfeature}{title} is + selected while loading the package (see + \autoref{sec:\ThisCommonLabelBase.optionalFeatures}, + \DescRef{\ThisCommonLabelBase.option.extendedfeature}). + + Furthermore, \Package{scrextend} cannot be used with a \KOMAScript{} + class. Because of this, you should replace +\begin{lstcode} + \documentclass{scrbook} +\end{lstcode} + with +\begin{lstcode} + \documentclass{book} + \usepackage[extendedfeature=title]{scrextend} +\end{lstcode} + for all examples from \autoref{sec:maincls.titlepage}, if you want to + try them with \Package{scrextend}. +\fi + +In general, we distinguish two kinds of document titles. First, there are +title pages. These include title of the document, together with additional +information such as the author, on a separate page. In addition to the main +title page, there may be several other title pages, such as the half-title or +bastard title, publisher data, dedication, and so on. Second, there is the +in-page title. This kind of title appears at the top of a new page, usually +the first, and is specially emphasized. It too may be accompanied by +additional information, but it will be followed by more material on the same +page, for example by an abstract, the table of contents, or even a section. + + +\begin{Declaration} + \OptionVName{titlepage}{simple switch}% + \OptionValue{titlepage}{firstiscover} + \Macro{coverpagetopmargin} + \Macro{coverpageleftmargin} + \Macro{coverpagerightmargin} + \Macro{coverpagebottommargin} +\end{Declaration}% +This option\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{} determines whether to use document title pages\Index{title>pages} or +in-page titles\Index{title>in-page} when using +\DescRef{\ThisCommonLabelBase.cmd.maketitle} (see +\DescPageRef{\ThisCommonLabelBase.cmd.maketitle}). Any value from +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} can be used +for \PName{simple switch}. + +With the \OptionValue{titlepage}{true}% +\important{\OptionValue{titlepage}{true}} +\IfThisCommonLabelBase{scrextend}{}{or \Option{titlepage}} option, +invoking \DescRef{\ThisCommonLabelBase.cmd.maketitle} creates titles on +separate pages. These pages are set inside a +\DescRef{\ThisCommonLabelBase.env.titlepage} environment, and they +normally have neither header nor footer. Compared to standard {\LaTeX}, +{\KOMAScript} significantly expands the handling of the titles. These +additional elements can be found on the following pages. + +In contrast, with the +\OptionValue{titlepage}{false}\important{\OptionValue{titlepage}{false}} +option, invoking \DescRef{\ThisCommonLabelBase.cmd.maketitle} creates an +\emph{in-page} title. This means that the title is specially emphasized, but +it may be followed by more material on the same page, for instance an abstract +or a section.% + +The third choice,% +\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrextend}{% + \ChangedAt{v3.12}{\Package{scrextend}}% + }{\InternalCommonFileUseError}% +} \OptionValue{titlepage}{firstiscover}% +\important{\OptionValue{titlepage}{firstiscover}} not only activates title +pages but also prints the first title page of +\DescRef{\ThisCommonLabelBase.cmd.maketitle}\IndexCmd{maketitle}, i.\,e. +either the half-title or the main title, as a cover\Index{cover} page. Any +other setting of the \Option{titlepage} option will cancel this setting. The +margins\important{\Macro{coverpage\dots margin}} of the cover page are given +by \Macro{coverpagetopmargin}, \Macro{coverpageleftmargin}, +\Macro{coverpagerightmargin}, and \Macro{coverpagebottommargin}. The defaults +of these depend on the lengths of \Length{topmargin}\IndexLength{topmargin} +and \Length{evensidemargin}\IndexLength{evensidemargin} and can be changed +with \Macro{renewcommand}. + +\IfThisCommonLabelBase{maincls}{% + The default of the \Class{scrbook} and \Class{scrreprt} classes is to use + title pages. The \Class{scrartcl} class, on the other hand, uses in-page + titles by default.% +}{% + \IfThisCommonLabelBase{scrextend}{% + The default depends on the class used and \Package{scrextend} recognizes + it in a way that compatible with the standard class. If a class does not + set up a comparable default, it will be an in-page title.% + }{\InternalCommonFileUsageError}% +}% +% +\EndIndexGroup + + +\begin{Declaration} + \begin{Environment}{titlepage}\end{Environment}% +\end{Declaration}% +The standard classes and {\KOMAScript} set all title pages in a special +environment: the \Environment{titlepage} environment. This environment always +starts a new page\,---\,in two-sided printing a new right-hand page\,---\,and +in single-column mode. For this page, the style is changed to +\DescRef{maincls.cmd.thispagestyle}% +\PParameter{\DescRef{maincls.pagestyle.empty}}, so that neither page number +nor running head is output. At the end of the environment, the page is +automatically shipped out. Should you not be able to use the automatic layout +of the title pages provided by \DescRef{\ThisCommonLabelBase.cmd.maketitle}, +described next, you should design a new one with the help of this environment. + +\IfThisCommonFirstRun{\iftrue}{% + A simple example for a title page with \Environment{titlepage} is shown in + \autoref{sec:\ThisCommonFirstLabelBase.titlepage} on + \PageRefxmpl{\ThisCommonFirstLabelBase.env.titlepage}% + \csname iffalse\endcsname% +}% + \begin{Example} + \phantomsection\xmpllabel{env.titlepage} + Suppose you want a title page on which only the word ``Me'' stands at + the top on the left, as large as possible and in bold\,---\,no + author, no date, nothing else. The following document creates just + that: +\begin{lstcode} + \documentclass{scrbook} + \begin{document} + \begin{titlepage} + \textbf{\Huge Me} + \end{titlepage} + \end{document} +\end{lstcode} + It's simple, isn't it? + \end{Example} +\fi% +\EndIndexGroup + + +\begin{Declaration} + \Macro{maketitle}\OParameter{page number} +\end{Declaration}% +While\textnote{\KOMAScript{} vs. standard classes} the standard classes +produce at most one title page that can have three items (title, author, and +date), with \KOMAScript{} \Macro{maketitle} can produce up to six pages. In +contrast to the standard classes, \Macro{maketitle} in {\KOMAScript} accepts +an optional numeric argument. If it is used, this number is the page number of +the first title page. This page number is not output, but it affects the +subsequent numbering. You should definitely choose an odd number, because +otherwise the whole count gets mixed up. In my opinion, there are only two +useful applications for the optional argument. On the one hand, you could give +the the logical page number -1 to the half-title\Index[indexmain]{half-title} +in order to give the full title page the number 1. On the other hand, you +could use it to start at a higher page number, for example, 3, 5, or 7, to +accommodate other title pages added by the publishing house. The optional +argument is ignored for \emph{in-page} titles. You can change the page style +of such a title page by redefining the +\DescRef{\ThisCommonLabelBase.cmd.titlepagestyle} macro (see +\autoref{sec:maincls.pagestyle}, \DescPageRef{maincls.cmd.titlepagestyle}). + +The following commands do not lead immediately to the ship-out of the titles. +The typesetting and ship-out of the title pages are always done by +\Macro{maketitle}. Note also that \Macro{maketitle} should not be used inside +a \DescRef{\ThisCommonLabelBase.env.titlepage} environment. +As\textnote{Attention!} shown in the examples, you should use either +\Macro{maketitle} or \DescRef{\ThisCommonLabelBase.env.titlepage}, but not +both. + +The following commands only define the contents of the title. Therefore they +must be used before \Macro{maketitle}. It is, however, not necessary and, when +using the \Package{babel} package\IndexPackage{babel} not recommended, to +include these in the preamble before \Macro{begin}\PParameter{document} (see +\cite{package:babel}). You can find examples +\IfThisCommonFirstRun{in the descriptions of the other commands in this + section}{in \autoref{sec:\ThisCommonFirstLabelBase.titlepage}, starting on + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.extratitle}}. + + +\begin{Declaration} + \Macro{extratitle}\Parameter{half-title} + \Macro{frontispiece}\Parameter{frontispiece} +\end{Declaration}% +\begin{Explain}% + In earlier times the inner book was often not protected from dirt by a + cover. This function was then assumed by the first page of the book, which + usually had just a short title, known as the \emph{half-title}. Nowadays the + extra page often appears before the real main title and contains information + about the publisher, series number, and similar information. +\end{Explain} +With {\KOMAScript}, it is possible to include a page before the real title +page. The \PName{half-title} can be arbitrary text\,---\,even several +paragraphs. The contents of the \PName{half-title} are output by {\KOMAScript} +without additional formatting. Their organisation is completely left to the +user. The verso of the half-title\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.25}{\Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrextend}{% + \ChangedAt{v3.25}{\Package{scrextend}}% + }{\ThisCommonLabelBaseFailure}% +} is the frontispiece. The half-title is set on its own page even when in-page +titles are used. The output of the half-title defined with \Macro{extratitle} +takes place as part of the title produced by +\DescRef{\ThisCommonLabelBase.cmd.maketitle}. + +\IfThisCommonFirstRun{\iftrue}{% + An example of a simple title page with half-title and main title is shown + in \autoref{sec:\ThisCommonFirstLabelBase.titlepage} on + \PageRefxmpl{\ThisCommonFirstLabelBase.cmd.extratitle}% + \csname iffalse\endcsname% +}% + \begin{Example} + \phantomsection\xmpllabel{cmd.extratitle} + Let's return to the previous example and suppose + that the Spartan ``Me'' is the half-title. The full title should + still follow the half-title. You can proceed as follows: +\begin{lstcode} + \documentclass{scrbook} + \begin{document} + \extratitle{\textbf{\Huge Me}} + \title{It's me} + \maketitle + \end{document} +\end{lstcode} + You can centre the half-title horizontally and put it a little lower down + the page: +\begin{lstcode} + \documentclass{scrbook} + \begin{document} + \extratitle{\vspace*{4\baselineskip} + \begin{center}\textbf{\Huge Me}\end{center}} + \title{It's me} + \maketitle + \end{document} +\end{lstcode} + The command\textnote{Attention!} \DescRef{\ThisCommonLabelBase.cmd.title} + is necessary in order to make the examples above work correctly. It is + explained next. + \end{Example} +\fi% +\EndIndexGroup + + +\begin{Declaration} + \Macro{titlehead}\Parameter{title head}% + \Macro{subject}\Parameter{subject}% + \Macro{title}\Parameter{title}% + \Macro{subtitle}\Parameter{subtitle}% + \Macro{author}\Parameter{author}% + \Macro{date}\Parameter{date}% + \Macro{publishers}\Parameter{publisher}% + \Macro{and}% + \Macro{thanks}\Parameter{footnote} +\end{Declaration}% +There are seven elements available for the content of the main title page. The +main title page is output as part of the title pages created by +\DescRef{\ThisCommonLabelBase.cmd.maketitle}, while the definitions given here +only apply to the respective elements. + +\BeginIndexGroup\BeginIndex{FontElement}{titlehead}% +\LabelFontElement{titlehead}% +The\important{\Macro{titlehead}} \PName{title head}% +\Index[indexmain]{title>head} is defined with the command +\Macro{titlehead}. It occupies the entire text width, at the top of the page, +in normal justification, and it can be freely designed by the user. It uses +the font element\important{\FontElement{titlehead}} with same name (see +\autoref{tab:\ThisCommonFirstLabelBase.mainTitle}, +\autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}).% +\EndIndexGroup + +\BeginIndexGroup\BeginIndex{FontElement}{subject}\LabelFontElement{subject}% +The\important{\Macro{subject}} \PName{subject}\Index[indexmain]{subject} is +output with the font element\important{\FontElement{subject}} of the same name +immediately above the \PName{title}.% +\EndIndexGroup + +\BeginIndexGroup\BeginIndex{FontElement}{title}\LabelFontElement{title}% +The\important{\Macro{title}} \PName{title} is set in a very large font size. +Along\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v2.8p}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}}{} with the font size, the font element +\FontElement{title}\IndexFontElement[indexmain]{title}% +\important{\FontElement{title}} is applied (see +\autoref{tab:\ThisCommonFirstLabelBase.mainTitle}, +\autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}).% +\EndIndexGroup + +\BeginIndexGroup\BeginIndex{FontElement}{subtitle}\LabelFontElement{subtitle}% +The\important{\Macro{subtitle}} +\PName{subtitle}\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v2.97c}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}}{} is set just below the title using the font +element\important{\FontElement{subtitle}} of the same name (see +\autoref{tab:\ThisCommonFirstLabelBase.mainTitle}, +\autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}).% +\EndIndexGroup + +\BeginIndexGroup\BeginIndex{FontElement}{author}\LabelFontElement{author}% +Below\important{\Macro{author}} the \PName{subtitle} appears the +\PName{author}\Index[indexmain]{author}. Several authors can be specified in +the argument of \Macro{author}. They should be separated by +\Macro{and}\important{\Macro{and}}. The output uses the font +element\important{\FontElement{author}} of the same name. (see +\autoref{tab:\ThisCommonFirstLabelBase.mainTitle}, +\autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}).% +\EndIndexGroup + +\BeginIndexGroup\BeginIndex{FontElement}{date}\LabelFontElement{date}% +Below\important{\Macro{date}} the author or authors appears the +date\Index{date} in the font of the element of the same name. The default +value is the current date, as produced by \Macro{today}\IndexCmd{today}. The +\Macro{date} command accepts arbitrary information\,---\,even an empty +argument. The output uses the font element\important{\FontElement{date}} of +the same name (see \autoref{tab:\ThisCommonFirstLabelBase.mainTitle}, +\autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}).% +\EndIndexGroup + +\BeginIndexGroup\BeginIndex{FontElement}{publishers}% +\LabelFontElement{publishers}% +Finally\important{\Macro{publishers}} comes the +\PName{publisher}\Index[indexmain]{publisher}. Of course this command can also +be used for any other information of minor importance. If necessary, the +\Macro{parbox} command can be used to typeset this information over the full +page width like a regular paragraph instead of centring it. It should then be +considered equivalent to the title head. Note, however, that this field is +placed above any existing footnotes. The output uses the font +element\important{\FontElement{publishers}} of the same name (see +\autoref{tab:\ThisCommonFirstLabelBase.mainTitle}, +\autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}).% +\EndIndexGroup + +Footnotes\important{\Macro{thanks}}\Index{footnotes} on the title page are +produced not with \Macro{footnote}, but with \Macro{thanks}. They serve +typically for notes associated with the authors. Symbols are used as footnote +markers instead of numbers. Note\textnote{Attention!} that \Macro{thanks} has +to be used inside the argument of another command, such as in the +\PName{author} argument of the command \Macro{author}. +\IfThisCommonLabelBase{scrextend}{% + However, in order for the \DescRef{\ThisCommonLabelBase.fontelement.footnote} + element to be aware of the \Package{scrextend} package, not only does the + title extension need to be enabled, it must also be set to use footnotes + with this package (see the introduction to + \autoref{sec:\ThisCommonLabelBase.footnotes}, + \autopageref{sec:\ThisCommonLabelBase.footnotes}). Otherwise, the font + specified by the class or other packages used for the footnotes will be + used.% +}{}% + +For% +\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrextend}{% + \ChangedAt{v3.12}{\Package{scrextend}}% + }{\InternalCommonFileUsageError}% +} the output of the title elements, the font\textnote{font} can be set using +the \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} command (see +\autoref{sec:\ThisCommonLabelBase.textmarkup}, +\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}). The defaults are listed +in \autoref{tab:\ThisCommonFirstLabelBase.titlefonts}% +\IfThisCommonFirstRun{}{% + , \autopageref{tab:\ThisCommonFirstLabelBase.titlefonts}% +}.% +\IfThisCommonFirstRun{% + \begin{table} +% \centering +% \caption + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% +% \addtokomafont{caption}{\raggedright}% + \begin{captionbeside} + [{Font defaults for the elements of the title}] + {\label{tab:\ThisCommonLabelBase.titlefonts}% + \hspace{0pt plus 1ex}Font defaults for the elements of the title} + [l] + \begin{tabular}[t]{ll} + \toprule + Element name & Default \\ + \midrule + \FontElement{author} & \Macro{Large} \\ + \FontElement{date} & \Macro{Large} \\ + \FontElement{dedication} & \Macro{Large} \\ + \FontElement{publishers} & \Macro{Large} \\ + \FontElement{subject} & + \Macro{normalfont}\Macro{normalcolor}% + \Macro{bfseries}\Macro{Large} \\ + \FontElement{subtitle} & + \DescRef{\ThisCommonLabelBase.cmd.usekomafont}% + \PParameter{title}\Macro{large} \\ + \FontElement{title} & + \DescRef{\ThisCommonLabelBase.cmd.usekomafont}% + \PParameter{disposition} \\ + \FontElement{titlehead} & \\ + \bottomrule + \end{tabular} + \end{captionbeside} + \end{table}% +}{}% + +With the exception of \PName{title head} and any footnotes, all output is +centred horizontally. % +\iffree{% + \IfThisCommonLabelBase{scrextend}{The formatting of each element is}{These + details are} briefly summarized in + \autoref{tab:\ThisCommonFirstLabelBase.mainTitle}\IfThisCommonFirstRun{}{% + , \autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}}.% +}{% + \IfThisCommonLabelBase{scrextend}{% + The alignment of individual elements can also be found in + \autoref{tab:\ThisCommonFirstLabelBase.mainTitle}\IfThisCommonFirstRun{}{% + , \autopageref{tab:\ThisCommonFirstLabelBase.mainTitle}}.% + }{% + For a summary, see \autoref{tab:\ThisCommonFirstLabelBase.mainTitle}.% + }% +}% +\IfThisCommonFirstRun{% + \begin{table} + % \centering + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% + % \caption + \begin{captionbeside}[Main title]{% + \hspace{0pt plus 1ex}% + Font and horizontal positioning of the elements in the main title page + in the order of their vertical position from top to bottom when + typeset with \DescRef{\ThisCommonLabelBase.cmd.maketitle}} + [l] + \setlength{\tabcolsep}{.85\tabcolsep}% Umbruchoptimierung + \begin{tabular}[t]{llll} + \toprule + Element & Command & Font & Alignment \\ + \midrule + Title head & \Macro{titlehead} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{titlehead} & justified \\ + Subject & \Macro{subject} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{subject} & centred \\ + Title & \Macro{title} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{title}\Macro{huge} & centred \\ + Subtitle & \Macro{subtitle} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{subtitle} & centred \\ + Authors & \Macro{author} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{author} & centred \\ + Date & \Macro{date} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{date} & centred \\ + Publishers & \Macro{publishers} & \DescRef{\ThisCommonLabelBase.cmd.usekomafont}\PParameter{publishers} & centred \\ + \bottomrule + \end{tabular} + \end{captionbeside} + \label{tab:maincls.mainTitle} + \end{table} +}{} + +Note\textnote{Attention!} that for the main title, \Macro{huge} will be used +after the font switching element +\DescRef{\ThisCommonLabelBase.fontelement.title}\IndexFontElement{title}. So +you cannot change the size of the main title using +\DescRef{\ThisCommonLabelBase.cmd.setkomafont} or +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont}.% + +\IfThisCommonFirstRun{\iftrue}{% + An example for a title page using all the elements offered by \KOMAScript{} + is shown in \autoref{sec:\ThisCommonFirstLabelBase.titlepage} on + \PageRefxmpl{\ThisCommonFirstLabelBase.maintitle}.% + \csname iffalse\endcsname% +}% + \begin{Example} + \phantomsection\xmpllabel{maintitle}% + Suppose you are writing a dissertation. The title page should have the + university's name and address at the top, flush left, and the semester, + flush right. As usual, a title including author and submission date + should be given. The adviser must also be indicated, together with the + fact that the document is a dissertation. You can do this as follows: +\begin{lstcode} + \documentclass{scrbook} + \usepackage[english]{babel} + \begin{document} + \titlehead{{\Large Unseen University + \hfill SS~2002\\} + Higher Analytical Institute\\ + Mythological Rd\\ + 34567 Etherworld} + \subject{Dissertation} + \title{Digital space simulation with the DSP\,56004} + \subtitle{Short but sweet?} + \author{Fuzzy George} + \date{30. February 2002} + \publishers{Adviser Prof. John Eccentric Doe} + \maketitle + \end{document} +\end{lstcode} + \end{Example}% +\fi + +\begin{Explain} + A common misconception concerns the function of the full title page. It is + often erroneously assumed to be the cover\Index{cover} or dust jacket. + Therefore, it is frequently expected that the title page will not follow the + normal layout for two-sided typesetting but will have equally large left and + right margins. + + But if you pick up a book and open it, you will quickly find at least one + title page inside the cover, within the so-called book block. Precisely + these title pages are produced by + \DescRef{\ThisCommonLabelBase.cmd.maketitle}. + + As is the case with the half-title, the full title page belongs to the book + block, and therefore should have the same page layout as the rest of the + document. A cover is actually something that you should create in a + separate document. After all, it often has a very distinct format. It can + also be designed with the help of a graphics or DTP program. A separate + document should also be used because the cover will be printed on a + different medium, such as cardboard, and possibly with another printer. + + Nevertheless, since \KOMAScript~3.12 the first title page issued by + \DescRef{\ThisCommonLabelBase.cmd.maketitle} can be formatted as a cover + page with different margins. Changes to the margins on this page do not + affect the other margins. For more information about this option, see + \OptionValueRef{\ThisCommonLabelBase}{titlepage}{firstiscover}% + \IndexOption{titlepage~=\textKValue{firstiscover}} on + \DescPageRef{\ThisCommonLabelBase.option.titlepage}. +\end{Explain} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{uppertitleback}\Parameter{titlebackhead}% + \Macro{lowertitleback}\Parameter{titlebackfoot} +\end{Declaration}% +In\textnote{\KOMAScript{} vs. standard classes} two-sided printing, the +standard classes leave the back (verso) of the title page empty. However, with +{\KOMAScript} the back of the full title page can be used for other +information. There are exactly two elements which the user can freely format: +\PName{titlebackhead}\Index{title>back}\Index{title>verso} and +\PName{titlebackfoot}. The header can extend to the footer and vice versa. +\iffree{Using this guide as an example, the legal disclaimer was set with the + help of the \Macro{uppertitleback} command.}{The publishers information of + this book, for example, could have been set either with + \Macro{uppertitleback} or \Macro{lowertitleback}.}% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{dedication}\Parameter{dedication} +\end{Declaration}% +{\KOMAScript} offers its own dedication page. This +dedication\Index{dedication} is centred and set by default with a slightly +larger font\textnote{font}. +\BeginIndexGroup\BeginIndex{FontElement}{dedication}% +\LabelFontElement{dedication} +The% +\IfThisCommonLabelBase{maincls}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% +}{% + \IfThisCommonLabelBase{scrextend}{% + \ChangedAt{v3.12}{\Package{scrextend}}% + }{\InternalCommonFileUseError}% +}\important{\FontElement{dedication}} exact font setting for the +\FontElement{dedication} element, which is taken from +\autoref{tab:\ThisCommonFirstLabelBase.titlefonts}, +\autopageref{tab:\ThisCommonFirstLabelBase.titlefonts}, can be changed with +the \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and +\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see +\autoref{sec:\ThisCommonLabelBase.textmarkup}, +\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}).% +\EndIndexGroup + +\IfThisCommonFirstRun{\iftrue}{% + An example with all title pages provided by \KOMAScript{} is shown in + \autoref{sec:\ThisCommonFirstLabelBase.titlepage} on + \PageRefxmpl{\ThisCommonFirstLabelBase.fulltitle}.% + \csname iffalse\endcsname% +}% + \begin{Example} + \phantomsection\xmpllabel{fulltitle}% + Suppose you have written a book of poetry and want to + dedicate it to your spouse. A solution would look like this: +\begin{lstcode} + \documentclass{scrbook} + \usepackage[english]{babel} + \begin{document} + \extratitle{\textbf{\Huge In Love}} + \title{In Love} + \author{Prince Ironheart} + \date{1412} + \lowertitleback{This poem book was set with% + the help of {\KOMAScript} and {\LaTeX}} + \uppertitleback{Self-mockery Publishers} + \dedication{To my treasured hazel-hen\\ + in eternal love\\ + from your dormouse.} + \maketitle + \end{document} +\end{lstcode} + Please use your own favourite pet names to personalize it. + \end{Example}% +\fi% +\EndIndexGroup +% +\EndIndexGroup +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/common-typearea.tex b/macros/latex/contrib/koma-script/source-doc/english/common-typearea.tex new file mode 100644 index 0000000000..30b89d0331 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/common-typearea.tex @@ -0,0 +1,88 @@ +% ====================================================================== +% common-typearea.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% common-typearea.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Paragraphs that are common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{common-typearea.tex} + [$Date: 2018-03-30 09:37:06 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (common paragraphs: typearea)] +\translator{Markus Kohm\and Krickette Murabayashi\and Karl Hagen} + +% Date of the translated German file: 2018-02-01 + +\section{Page Layout} +\seclabel{typearea} +\BeginIndexGroup +\BeginIndex{}{page>layout} + +Each page of a document consists of different layout elements, such as the +margins, the header, the footer, the text area, the marginal note column, and +the distances between these elements. \KOMAScript{} additionally distinguishes +the entire page, also known as the paper, and the visible page. Without doubt, +the separation of the page into these different parts is one of the basic +features of a class\IfThisCommonLabelBase{scrlttr2}{\OnlyAt{scrlttr2}}{}. +\KOMAScript{} delegates this work to the package \Package{typearea}. This +package can also be used with other classes. The \KOMAScript{} classes, +however, load \Package{typearea} on their own. Therefore, it's neither +necessary nor sensible to load the package explicitly with \Macro{usepackage} +while using a \KOMAScript{} class. See also +\autoref{sec:\ThisCommonLabelBase.options}, +\autopageref{sec:\ThisCommonLabelBase.options}. + +Some settings of \KOMAScript{} classes affect the page layout and vice versa. +Those effects are documented at the corresponding settings. + +For more information about the choice of paper format, the division of the +page into margins and type area, and the choice between one- and two-column +typesetting, see the documentation for the \Package{typearea} package. You can +find it in \autoref{cha:typearea}, starting on \autopageref{cha:typearea}. + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/expertpart.tex b/macros/latex/contrib/koma-script/source-doc/english/expertpart.tex new file mode 100644 index 0000000000..60dd17e9b3 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/expertpart.tex @@ -0,0 +1,78 @@ +% ====================================================================== +% expertpart.tex +% Copyright (c) Markus Kohm, 2002-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% expertpart.tex +% 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. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% First part: KOMA-Script for Authors +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Erster Teil: KOMA-Script fuer Autoren +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{expertpart.tex} + [$Date: 2018-02-28 13:23:23 +0100 (Wed, 28 Feb 2018) $ + Part KOMA-Script for Experts] +\translator{Markus Kohm\and Karl Hagen} + +\setpartpreamble{% + \vspace*{2\baselineskip}% + \setlength{\parindent}{1em}% + + \noindent In this part, you can find information for the authors of LaTeX + packages and classes. This applies not only to commands that are useful for + implementing new packages and classes, but also to interfaces that allow + further alteration of \KOMAScript{}. Moreover, this part provides + information on obsolete options and instructions, as well as background + information on the implementation of \KOMAScript{}. + + This part is intended to supplement the information for authors of articles, + reports, books and letters in \autoref{part:forAuthors}. More information + and examples for those users can be found in that part. +} + +\part{\KOMAScript{} for Advanced Users and Experts} +\label{part:forExperts} + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% coding: us-ascii +%%% TeX-master: "guide.tex" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/guide-english.tex b/macros/latex/contrib/koma-script/source-doc/english/guide-english.tex new file mode 100644 index 0000000000..edebaee2b9 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/guide-english.tex @@ -0,0 +1,522 @@ +% ====================================================================== +% guide-english.tex +% Copyright (c) Markus Kohm, 2002-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% guide-english.tex +% 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. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Language dependencies (english) of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Sprachabhaengigkeiten (english) der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ====================================================================== +% +\KOMAProvidesFile{guide-english.tex} + [$Date: 2018-03-21 10:37:34 +0100 (Wed, 21 Mar 2018) $ + KOMA-Script guide language dependencies] +% +% \section{Extra Packages} +% +\RequirePackage[normal]{engord} +% +% \section{Title} +% +% \begin{macro}{\GuideSubject} +% \begin{macro}{\GuideTitle} +% \begin{macro}{\GuideSubTitle} +% \begin{macro}{\GuideAuthorHeadline} +% \begin{macro}{\GuideTranslatorHeadline} +% \begin{macro}{\GuideWarrantyHeadline} +% \begin{macro}{\GuideWarranty} +% \begin{macro}{\GuideCopyright} +% \begin{macro}{\GuideDedication} +% Language dependencies of all the title pages. +% \begin{macrocode} +\newcommand*{\GuideSubject}{The Guide}% +\newcommand*{\GuideTitle}{\KOMAScript}% +\newcommand*{\GuideSubTitle}{a versatile {\LaTeXe} bundle% + % Ugly note + \vfill + \noindent Note: This document is a translation of the German \KOMAScript{} + manual. Several authors have been involved to this translation. Some of them + are native English speakers. Others, like me, are not. Improvements of the + translation by native speakers or experts are welcome at all times!% +}% +\newcommand*{\GuideAuthorHeadline}{Authors of the {\KOMAScript} Bundle}% +\newcommand*{\GuideTranslatorHeadline}{English translation of this manual by: +} \newcommand*{\GuideWarrantyHeadline}{Legal Notes:}% +\newcommand*{\GuideWarranty}{There is no warranty for any part of the + documented software. The authors have taken care in the preparation of this + guide, but make no expressed or implied warranty of any kind and assume no + responsibility for errors or omissions. No liability is assumed for + incidental or consequential damages in connection with or arising out of the + use of the information or programs contained here.\par\medskip% + Many of the designations used by manufacturers and sellers to distinguish + their products are claimed as trademarks. Where those designations appear in + this book, and the authors were aware of a trademark claim, the designations + have been printed with initial capital letters or in all capitals.}% +\newcommand*{\GuideCopyright}{Free screen version without any optimization of + paragraph and page breaks\par\medskip% + This guide is part of {\KOMAScript}, which is free under the terms and + conditions of {\LaTeX} Project Public License Version 1.3c. A version of + this license, which is valid for {\KOMAScript}, is part of {\KOMAScript} (see + \File{lppl.txt}). Distribution of this manual\,---\,even if it is + printed\,---\,is allowed provided that all parts of {\KOMAScript} are + distributed with it. Distribution without the other parts of {\KOMAScript} + requires an explicit, additional authorization by the authors.}% +\newcommand*{\GuideDedication}{To all my friends all over the world!}% +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% \section{CTAN Server to be Used} +% +% \begin{macro}{\GuideCTANserver} +% Unused since 2015-09-30. +% \begin{macrocode} +%\newcommand*{\GuideCTANserver}{ftp.ctan.org} +% \end{macrocode} +% \end{macro} +% +% +% \section{Terms} +% +% Some terms, e.g. used at index notes. +% +% \begin{macro}{\GuideClass} +% \begin{macro}{\GuideClassIndexCategory} +% \begin{macro}{\GuideClassIndexCategoryExpanded} +% The term ``class''. +% \begin{macrocode} +\newcommand*{\GuideClass}{class} +\newcommand*{\GuideClassIndexCategory}{classes} +\let\GuideClassIndexCategoryExpanded\GuideClassIndexCategory +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuideCounter} +% \begin{macro}{\GuideCounterIndexCategory} +% \begin{macro}{\GuideCounterIndexCategoryExpanded} +% The term ``counter''. +% \begin{macrocode} +\newcommand*{\GuideCounter}{counter} +\newcommand*{\GuideCounterIndexCategory}{counters} +\let\GuideCounterIndexCategoryExpanded\GuideCounterIndexCategory +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuideEnvironment} +% \begin{macro}{\GuideEnvIndexCategory} +% \begin{macro}{\GuideEnvIndexCategoryExpanded} +% The term ``environment''. +% \begin{macrocode} +\newcommand*{\GuideEnvironment}{environment} +\newcommand*{\GuideEnvIndexCategory}{environments} +\let\GuideEnvIndexCategoryExpanded\GuideEnvIndexCategory +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuideExample} +% The term ``Example'' used at a kind of heading, so it should be upper case. +% \begin{macrocode} +\newcommand*{\GuideExample}{Example} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\GuideFile} +% \begin{macro}{\GuideFileIndexCategory} +% \begin{macro}{\GuideFileIndexCategoryExpanded} +% The term ``file''. +% \begin{macrocode} +\newcommand*{\GuideFile}{file} +\newcommand*{\GuideFileIndexCategory}{files} +\let\GuideFileIndexCategoryExpanded\GuideFileIndexCategory +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuideFloatstyle} +% \begin{macro}{\GuideFloatstyleIndexCategory} +% \begin{macro}{\GuideFloatstyleIndexCategoryExpanded} +% The term ``\Package{float} style''. +% \begin{macrocode} +\newcommand*{\GuideFloatstyle}{\Package{float} style} +\newcommand*{\GuideFloatstyleIndexCategory}{\Package{float} styles} +\newcommand*{\GuideFloatstyleIndexCategoryExpanded}{float styles} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuideFontElement} +% \begin{macro}{\GuideFontElementIndexCategory} +% \begin{macro}{\GuideFontElementIndexCategoryExpanded} +% The term ``element''. +% \begin{macrocode} +\newcommand*{\GuideFontElement}{element} +\newcommand*{\GuideFontElementIndexCategory}{elements} +\let\GuideFontElementIndexCategoryExpanded\GuideFontElementIndexCategory +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuideLength} +% \begin{macro}{\GuideLengthIndexCategory} +% \begin{macro}{\GuideLengthIndexCategoryExpanded} +% The term ``length''. +% \begin{macrocode} +\newcommand*{\GuideLength}{length} +\newcommand*{\GuideLengthIndexCategory}{lengths} +\let\GuideLengthIndexCategoryExpanded\GuideLengthIndexCategory +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuideMacro} +% \begin{macro}{\GuideMacroIndexCategory} +% \begin{macro}{\GuideMacroIndexCategoryExpanded} +% \begin{macro}{\GuideCommand} +% \begin{macro}{\GuideCommandIndexCategory} +% \begin{macro}{\GuideCommandIndexCategoryExpanded} +% The term ``command''. +% \begin{macrocode} +\newcommand*{\GuideMacro}{command} +\let\GuideCommand\GuideMacro +\newcommand*{\GuideMacroIndexCategory}{commands} +\let\GuideCommandIndexCategory\GuideMacroIndexCategory +\let\GuideMacroIndexCategoryExpanded\GuideMacroIndexCategory +\let\GuideCommandIndexCategoryExpanded\GuideCommandIndexCategory +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuideOption} +% \begin{macro}{\GuideOptionIndexCategory} +% \begin{macro}{\GuideOptionIndexCategoryExpanded} +% The term ``option''. +% \begin{macrocode} +\newcommand*{\GuideOption}{option} +\newcommand*{\GuideOptionIndexCategory}{options} +\let\GuideOptionIndexCategoryExpanded\GuideOptionIndexCategory +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuidePackage} +% \begin{macro}{\GuidePackageIndexCategory} +% \begin{macro}{\GuidePackageIndexCategoryExpanded} +% The term ``package''. +% \begin{macrocode} +\newcommand*{\GuidePackage}{package} +\newcommand*{\GuidePackageIndexCategory}{packages} +\let\GuidePackageIndexCategoryExpanded\GuidePackageIndexCategory +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuidePagestyle} +% \begin{macro}{\GuidePagestyleIndexCategory} +% \begin{macro}{\GuidePagestyleIndexCategoryExpanded} +% The term ``page style''. +% \begin{macrocode} +\newcommand*{\GuidePagestyle}{page style} +\newcommand*{\GuidePagestyleIndexCategory}{page styles} +\let\GuidePagestyleIndexCategoryExpanded\GuidePagestyleIndexCategory +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuidePLength} +% \begin{macro}{\GuidePLengthIndexCategory} +% \begin{macro}{\GuidePLengthIndexCategoryExpanded} +% \begin{macro}{\GuidePseudoPrefix} +% The prefix ``pseudo'' at the term ``pseudo length'' and the term itself. +% \begin{macrocode} +\newcommand*{\GuidePseudoPrefix}{pseudo-} +\newcommand*{\GuidePLength}{\GuidePseudoPrefix\GuideLength} +\newcommand*{\GuidePLengthIndexCategory}{\GuidePseudoPrefix\GuideLengthIndexCategory} +\let\GuidePLengthIndexCategoryExpanded\GuidePLengthIndexCategory +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuideVariable} +% \begin{macro}{\GuideVariableIndexCategory} +% \begin{macro}{\GuideVariableIndexCategoryExpanded} +% The termo ``variable''. +% \begin{macrocode} +\newcommand*{\GuideVariable}{variable} +\newcommand*{\GuideVariableIndexCategory}{variables} +\let\GuideVariableIndexCategoryExpanded\GuideVariableIndexCategory +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuideAnd} +% The ``and'' at a list of two. +% \begin{macrocode} +\newcommand*{\GuideAnd}{ and } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\GuideListAnd} +% The ``and'' at a list of more than two. +% \begin{macrocode} +\newcommand*{\GuideListAnd}{, and } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\GuideLoadNonFree} +% Note, that the non free manual contains more information. +% \begin{macrocode} +\newcommand*{\GuideLoadNonFree}{% + Currently, additional information on this topic can be found at the same + point in the German \KOMAScript{} book \cite{book:komascript} only. +} +% \end{macrocode} +% \end{macro} +% +% +% \section{Index} +% +% \begin{macro}{\GuidegenIndex} +% \begin{macro}{\GuidecmdIndex} +% \begin{macro}{\GuidecmdIndexShort} +% \begin{macro}{\GuidelenIndex} +% \begin{macro}{\GuidelenIndexShort} +% \begin{macro}{\GuideelmIndex} +% \begin{macro}{\GuideelmIndexShort} +% \begin{macro}{\GuidefilIndex} +% \begin{macro}{\GuidefilIndexShort} +% \begin{macro}{\GuideoptIndex} +% \begin{macro}{\GuideoptIndexShort} +% The titles and short titles of each single index. +\newcommand*{\GuidegenIndex}{General Index}% +\newcommand*{\GuidecmdIndex}{Index of Commands, Environments, and Variables}% +\newcommand*{\GuidecmdIndexShort}{Index of Commands, etc.}% +\newcommand*{\GuidelenIndex}{Index of Lengths and Counters}% +\newcommand*{\GuidelenIndexShort}{Index of Lengths, etc.}% +\newcommand*{\GuideelmIndex}{Index of Elements Capable of + Adjusting Fonts}% +\newcommand*{\GuideelmIndexShort}{Index of Elements}% +\newcommand*{\GuidefilIndex}{Index of Files, Classes, and Packages}% +\newcommand*{\GuidefilIndexShort}{Index of Files, etc.}% +\newcommand*{\GuideoptIndex}{Index of Class and Package Options}% +\newcommand*{\GuideoptIndexShort}{Index of Options}% +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuideIndexPreamble} +% The preamble text of the whole index. +\newcommand*{\GuideIndexPreamble}{% + There are two kinds of page numbers in this index. The numbers in bold + show the pages where the topic is defined or explained. The numbers in + ordinary type show the pages of where the topic is mentioned.% +} +% \end{macro} +% +% +% \begin{macro}{\GuideIndexSees} +% These are all see index entries. +\newcommand*{\GuideIndexSees}{% +} +% \end{macro} +% +% \begin{macro}{\GuideIndexSeeAlsos} +% These are all see also index entries. +\newcommand*{\GuideIndexSeeAlsos}{% +} +% \end{macro} +% +% \section{Bibliography} +% +% \begin{macro}{\GuideBibPreamble} +% \begin{macrocode} +\newcommand*{\GuideBibPreamble}{% + In the following, you will find many references. All of them are referenced + in the main text. In many cases the reference points to documents or + directories which can be accessed via the Internet. In these cases, the + reference includes a URL instead of a publisher. If the reference points to + a {\LaTeX} package then the URL is written in the form + ``\url{CTAN://}\emph{destination}''. The prefix ``\url{CTAN://}'' means the + \TeX{} archive on a CTAN server or mirror. For example, you can replace the + prefix with \url{http://mirror.ctan.org/}. For {\LaTeX} packages, it is also + important to mention that we have tried to give a version number appropriate + to the text that cites the reference. But for some packages is is very + difficult to find a consistent version number and release date. + Additionally, the given version is not always the current version. If you + want install new packages, be sure that the package is the most up-to-date + version and check first if the package is already available on your system.% +} +% \end{macrocode} +% \end{macro} +% +% +% \section{Change Log} +% +% \begin{macro}{\GuideChangeLogPreamble} +% The preamble of the change log index. +% \begin{macrocode} +\newcommand*{\GuideChangeLogPreamble}{% + In this list of changes, you will find all significant changes to the user + interface of the {\KOMAScript} bundle at the last few versions. The list was + sorted by the names of the classes and packages and their version. The + numbers after the version are the pages where the changes are described. In + the margins of these pages, you will find corresponding version marks.% +} +% \end{macrocode} +% \end{macro} +% +% +% \section{Language Extensions} +% +% Some terms should be part of the captions of the language. +% \begin{macro}{\GuideLanguageExtensions} +% This macro has to be defined, because the class will add it to the language +% at |\begin{document}| and it will also call it. +% \begin{macrocode} +\newcommand*{\GuideLanguageExtensions}{% +% \end{macrocode} +% \begin{macro}{\pageautorefname} +% The term ``page'' that will be put before the reference of a page set by +% |\autopageref|. +% \begin{macrocode} + \def\pageautorefname{page}% +% \end{macrocode} +% \end{macro} +% \begin{macro}{\partautorefname} +% \begin{macro}{\figureautorefname} +% \begin{macro}{\tableautorefname} +% \begin{macro}{\subsectionautorefname} +% \begin{macro}{\subsubsectionautorefname} +% \begin{macro}{\paragraphautorefname} +% \begin{macro}{\subparagraphautorefname} +% I'll call them all ``section''. +% \begin{macrocode} + \def\partautorefname{part}% + \def\figureautorefname{figure}% + \def\tableautorefname{table}% + \def\appendixautorefname{appendix}% + \let\subsectionautorefname=\sectionautorefname + \let\subsubsectionautorefname=\sectionautorefname + \let\paragraphautorefname=\sectionrefname + \let\subparagraphautorefname=\sectionrefname +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \begin{macro}{\changelogname} +% The name of the change log index. +% \begin{macrocode} + \def\changelogname{Change Log}% +% \end{macrocode} +% \end{macro} +% \begin{macro}{\descriptionname} +% \begin{macro}{\contentsname} +% \begin{macrocode] + \def\descriptionname{description}% + \def\contentname{contents}% +% \end{macrocode} +% \end{macro} +% \end{macro} +% \begin{macro}{\lengthname} +% \begin{macrocode} + \def\lengthname{length}% +% \end{macrocode} +% \end{macro} +% \begin{macrocode} +} +% \end{macrocode} +% \end{macro} +% +% +% \section{Hyphenation} +% +% This is not realy a good place to put them~-- but better late than never: +% \begin{macrocode} +\hyphenation{% +} +% \end{macrocode} +% +% +% +\endinput +%%% Local Variables: +%%% mode: doctex +%%% coding: us-ascii +%%% TeX-master: "guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/guide.tex b/macros/latex/contrib/koma-script/source-doc/english/guide.tex new file mode 120000 index 0000000000..4e897d1e39 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/guide.tex @@ -0,0 +1 @@ +../guide.tex
\ No newline at end of file diff --git a/macros/latex/contrib/koma-script/source-doc/english/htmlsetup b/macros/latex/contrib/koma-script/source-doc/english/htmlsetup new file mode 100644 index 0000000000..8c30c6ed56 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/htmlsetup @@ -0,0 +1,65 @@ +# ====================================================================== +# htmlsetup +# Copyright (c) Markus Kohm, 2002-2013 +# +# This file is part of the LaTeX2e KOMA-Script bundle. +# +# This work may be distributed and/or modified under the conditions of +# the LaTeX Project Public License, version 1.3c of the license. +# The latest version of this license is in +# http://www.latex-project.org/lppl.txt +# and version 1.3c or later is part of all distributions of LaTeX +# version 2005/12/01 or later and of this work. +# +# This work has the LPPL maintenance status "author-maintained". +# +# The Current Maintainer and author of this work is Markus Kohm. +# +# This work consists of all files listed in manifest.txt. +# ---------------------------------------------------------------------- +# htmlsetup +# Copyright (c) Markus Kohm, 2002-2013 +# +# Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +# Version 1.3c, verteilt und/oder veraendert werden. +# Die neuste Version dieser Lizenz ist +# http://www.latex-project.org/lppl.txt +# und Version 1.3c ist Teil aller Verteilungen von LaTeX +# Version 2005/12/01 oder spaeter und dieses Werks. +# +# Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +# (allein durch den Autor verwaltet). +# +# Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +# +# Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +# ====================================================================== + +$baselink="scrguien.pdf"; +$htmlhead="<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.0//EN\"> +<html> +<head><title>Index</title> +<meta http-equiv=\"content-type\" content=\"text/html; charset=utf-8\"> +</head> +<body> +<h1>Index of the KOMA-Script Guide</h1> +<p>This is an index of the elements defined at KOMA-Script. This index is related to the <a href=\"scrguien.pdf\">KOMA-Script guide</a>. To improve the survey this index has serveral functional sections:</p> +"; +$htmlend="<p> +<a href=\"http://validator.w3.org/check?uri=referer\"><img +src=\"http://www.w3.org/Icons/valid-html40\" +alt=\"Valid HTML 4.0 Strict\" height=\"31\" width=\"88\"></a> +</p> +</body></html>"; +%titles=( "option" => "Options", + "macro" => "Commands", + "environment" => "Environments", + "length" => "Lengths", + "plength" => "Pseudolengths", + "variable" => "Variables", + "pagestyle" => "Page Styles", + "counter" => "Counter", + "floatstyle" => "Styles for the float Package", + "fontelement" => "Elements (Font May Be Changed)" ); + +# end of file diff --git a/macros/latex/contrib/koma-script/source-doc/english/introduction.tex b/macros/latex/contrib/koma-script/source-doc/english/introduction.tex new file mode 100644 index 0000000000..9331720287 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/introduction.tex @@ -0,0 +1,352 @@ +% ====================================================================== +% introduction.tex +% Copyright (c) Markus Kohm, 2001-2019 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% introduction.tex +% Copyright (c) Markus Kohm, 2001-2019 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Introduction of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Einleitung der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{introduction.tex} + [$Date: 2019-01-15 08:39:58 +0100 (Tue, 15 Jan 2019) $ + KOMA-Script guide introduction] +\translator{Kevin Pfeiffer\and Gernot Hassenpflug\and + Krickette Murabayashi\and Markus Kohm\and Karl Hagen} + +% Date of the translated German file: 2018-02-05 + +\chapter{Introduction} +\labelbase{introduction} + +This chapter contains, among other things, important information about the +structure of the manual and the history of {\KOMAScript}, which begins +years before the first version. You will also find information on how to +install {\KOMAScript} and what to do if you encounter errors. + +\section{Preface}\seclabel{preface} + +{\KOMAScript} is very complex. This is due to the fact that it consists of not +just a single class or a single package but a bundle of many classes and +packages. Although the classes are designed as counterparts to the standard +classes, that does not mean they provide only the commands, environments, and +settings of the standard classes, or that they imitate their appearance. The +capabilities of {\KOMAScript} sometimes far surpass those of the standard +classes. Some of them should be considered extensions to the basic +capabilities of the \LaTeX{} kernel. + +The foregoing means that the documentation of {\KOMAScript} has to be +extensive. In addition, {\KOMAScript} is not normally taught. That means there +are no teachers who know their students and can therefore choose the teaching +materials and adapt them accordingly. It would be easy to write documentation +for a specific audience. The difficulty facing the author, however, is that +the manual must serve all potential audiences. I have tried to create a guide +that is equally suitable for the computer scientist and the fishmonger's +secretary. I have tried, although this is actually an impossible task. The +result is numerous compromises, and I would ask you to take this issue into +account if you have any complaints or suggestions to help improve the current +situation. + +Despite the length of this manual, I would ask you to consult the +documentation first in case you have problems. You should start by referring +to the multi-part index at the end of this document. In addition to this +manual, documentation includes all the text documents that are part of the +bundle. See \File{manifest.tex} for a complete list. + +\section{Structure of the Guide}\seclabel{structure} + +This manual is divided into several parts: There is a section for average +users, one for advanced users and experts, and an appendix with further +information and examples for those who want to understand {\KOMAScript} +thoroughly. + +\autoref{part:forAuthors} is intended for all {\KOMAScript} users. This means +that some information in this section is directed at newcomers to \LaTeX. In +particular, this part contains many examples that are intended to clarify the +explanations. Do not hesitate to try these examples yourself and discover how +{\KOMAScript} works by modifying them. That said, the {\KOMAScript} user guide +is not intended to be a {\LaTeX} primer. Those new to {\LaTeX} should look at +\emph{The Not So Short Introduction to {\LaTeXe}} \cite{lshort} or +\emph{{\LaTeXe} for Authors} \cite{latex:usrguide} or a {\LaTeX} reference +book. You will also find useful information in the many {\LaTeX} FAQs, +including the \emph{{\TeX} Frequently Asked Questions on the Web} +\cite{UK:FAQ}. Although the length of the \emph{{\TeX} Frequently Asked + Questions on the Web} is considerable, you should get at least a rough +overview of it and consult it in case you have problems, as well as this +\iffree{guide}{book}. + +\autoref{part:forExperts} is intended for advanced {\KOMAScript} users, those +who are already familiar with \LaTeX{} or who have been working with +{\KOMAScript} for a while and want to understand more about how {\KOMAScript} +works, how it interacts with other packages, and how to perform more +specialized tasks with it. For this purpose, we return to some aspects of the +class descriptions from \autoref{part:forAuthors} and explain them in more +detail. In addition we document some commands that are particularly intended +for advanced users and experts. This is supplemented by the documentation of +packages that are normally hidden from the user, insofar as they do their work +beneath the surface of the classes and user packages. These packages are +specifically designed to be used by authors of classes and packages. + +The appendix\iffree{, which can only be found in the German book version,}{} +contains information beyond that which is covered in \autoref{part:forAuthors} +and \autoref{part:forExperts}. Advanced users will find background information +on issues of typography to give them a basis for their own decisions. In +addition, the appendix provides examples for aspiring package authors. These +examples are not intended simply to be copied. Rather, they provide +information about planning and implementing projects, as well as some basic +\LaTeX{} commands for package authors. + +The guide's layout should help you read only those parts that are actually of +interest. Each class and package typically has its own chapter. +Cross-references to another chapter are thus usually also references to +another part of the overall package. However, since the three main classes +(\Class{scrbook}, \Class{scrrprt}, and \Class{scrartcl}) largely agree, they +are introduced together in \autoref{cha:maincls}. Differences between the +classes, e.\,g., for something that only affects the class +\Class{scrartcl}\OnlyAt{\Class{scrartcl}}, are clearly highlighted in the +margin, as shown here with \Class{scrartcl}. + +\begin{Explain} + The primary documentation for {\KOMAScript} is in German and has been + translated for your convenience; like most of the {\LaTeX} world, its + commands, environments, options, etc., are in English. In a few cases, the + name of a command may sound a little strange, but even so, we hope and + believe that with the help of this guide, {\KOMAScript} will be usable + and useful to you. +\end{Explain} + +At this point you should know enough to understand the guide. +It might, however, still be worth reading the rest of this chapter. + +\section{History of {\KOMAScript}}\seclabel{history} + +%\begin{Explain} +In the early 1990s, Frank Neukam needed a method to publish an instructor's +lecture notes. At that time {\LaTeX} was {\LaTeX}2.09 and there was no +distinction between classes and packages\,---\,there were only \emph{styles}. +Frank felt that the standard document styles were not good enough for his +work; he wanted additional commands and environments. At the same time he was +interested in typography and, after reading Tschichold's \emph{Ausgew\"ahlte + Aufs\"atze \"uber Fragen der Gestalt des Buches und der Typographie} +(Selected Articles on the Problems of Book Design and Typography) +\cite{JTsch87}, he decided to write his own document style\,---\,and not just +a one-time solution to his lecture notes, but an entire style family, one +specifically designed for European and German typography. Thus {\Script} was +born. + +Markus Kohm, the developer of {\KOMAScript}, came across {\Script} in December +1992 and added an option to use the A5 paper format. At that time neither the +standard style nor {\Script} provided support for A5 paper. Therefore it did +not take long until Markus made the first changes to {\Script}. This and other +changes were then incorporated into {\ScriptII}, released by Frank in December +1993. + +In mid-1994, {\LaTeXe} became available and brought with it many changes. +Users of {\ScriptII} were faced with either limiting their usage to +{\LaTeXe}'s compatibility mode or giving up {\Script} altogether. This +situation led Markus to put together a new {\LaTeXe} package, released on +7~July 1994 as {\KOMAScript}. A few months later, Frank declared {\KOMAScript} +to be the official successor to {\Script}. {\KOMAScript} originally provided +no \emph{letter} class, but this deficiency was soon remedied by Axel +Kielhorn, and the result became part of {\KOMAScript} in December 1994. Axel +also wrote the first true German-language user guide, which was followed by an +English-language guide by Werner Lemberg. + +Since then much time has passed. {\LaTeX} has changed in only minor ways, but +the {\LaTeX} landscape has changed a great deal; many new packages and classes +are now available and {\KOMAScript} itself has grown far beyond what it was in +1994. The initial goal was to provide good {\LaTeX} classes for +German-language authors, but today its primary purpose is to provide +more-flexible alternatives to the standard classes. {\KOMAScript}'s success +has led to e-mail from users all over the world, and this has led to many new +macros\,---\,all needing documentation; hence this ``small guide.'' +%\end{Explain} + + +\section{Special Thanks} +\seclabel{thanks} + +Acknowledgements in the introduction? No, the proper acknowledgements can be +found in the addendum. My comments here are not intended for the authors of +this guide\,---\,and those thanks should rightly come from you, the reader, +anyhow. I, the author of {\KOMAScript}, would like to extend my personal +thanks to Frank Neukam. Without his {\Script} family, {\KOMAScript} would not +have come about. I am indebted to the many persons who have contributed to +{\KOMAScript}, but with their indulgence, I would like to specifically mention +Jens-Uwe Morawski and Torsten Kr\"uger. The English translation of the guide +is, among many other things, due to Jens's untiring commitment. Torsten was +the best beta-tester I ever had. His work has particularly enhanced the +usability of \Class{scrlttr2} and \Class{scrpage2}. Many thanks to all who +encouraged me to go on, to make things better and less error-prone, or to +implement additional features. + +Special thanks go as well to the founders and members of DANTE, +Deutschsprachige Anwendervereinigung {\TeX}~e.V\kern-.18em, (the +German-Language {\TeX} User Group). Without the DANTE server, {\KOMAScript} +could not have been released and distributed. Thanks as well to everybody on +the {\TeX} newsgroups and mailing lists who answer questions and have helped +me provide support for {\KOMAScript}. + +My thanks also go to all those who have always encouraged me to go further and +to implement this or that feature better, with fewer flaws, or simply as an +extension. I would also like to thank the very generous donor who has given me +the most significant amount of money I have ever been paid for the work done +so far on \KOMAScript{}. + +\section{Legal Notes} +\seclabel{legal} + +{\KOMAScript} is released under the {\LaTeX} Project Public License. You will +find it in the file \File{lppl.txt}. An unofficial German-language translation +is also available in \File{lppl-de.txt} and is valid for all German-speaking +countries. + +\iffree{This document and the {\KOMAScript} bundle are provided ``as is'' and + without warranty of any kind.}% +{Please note: the printed version of this guide is not free under the + conditions of the {\LaTeX} Project Public Licence. If you need a free + version of this guide, use the version that is provided as part of the + {\KOMAScript} bundle.} + + +\section{Installation} +\seclabel{installation} + +The three most important \TeX{} distributions, Mac\TeX, MiK\TeX, and +\TeX{}~Live, make {\KOMAScript} available through their package management +software. You should install and update {\KOMAScript} using these tools, if +possible. Manual installation without using the package managers is described +in the file \File{INSTALL.txt}, which is part of every {\KOMAScript} +distribution. You should also read the documentation that comes with the +{\TeX} distribution you are using. + + +\section{Bug Reports and Other Requests} +\seclabel{errors} + +If you think you have found an error in the documentation or a bug in one of +the {\KOMAScript} classes, packages, or another part of {\KOMAScript}, please +do the following: First check on CTAN to see if a newer version of +{\KOMAScript} has been released. If a newer version is available, install this +new version and check if the problem persists. + +If the bug still occurs and your installation is fully up to date, please +provide a short {\LaTeX} file that demonstrates the problem. Such a file is +known as a minimal working example (MWE). You should include only minimal text +and use only the packages and definitions essential to demonstrate the +problem. Avoid using any unusual packages as much as possible. + +By preparing such an example it often becomes clear whether the problem is +truly a {\KOMAScript} bug or caused by something else. To check if another +package or class is actually causing the problem, you can also test your +example with the corresponding standard class instead of a {\KOMAScript} +class. If your problem still occurs, you should address your error report to +the author of the appropriate package than to the author of {\KOMAScript}. +Finally, you should carefully review the instructions for the appropriate +package, classes, and {\KOMAScript} component. A solution to your problem may +already exist, in which case an error report is unnecessary. + +If you think you have found a previously unreported error, or if for some +other reason you need to contact the author of {\KOMAScript}, don't forget the +following: + +\begin{itemize} +\item Does the problem also occur if a standard class is used instead of a + {\KOMAScript} class? In this case, the error is most likely not with + {\KOMAScript}, and it makes more sense to ask your question in a public + forum, a mailing list, or Usenet. +\item Which {\KOMAScript} version do you use? For related information, see the + \File{log} file of the \LaTeX{} run of any document that uses a + {\KOMAScript} class. +\item Which operating system and which \TeX{} distribution do you use? This + information might seem rather superfluous for a system-independent package + like {\KOMAScript} or {\LaTeX}, but time and again they have certainly been + shown to play a role. +\item What exactly is the problem or the error? Describe the problem. It's + better to be too detailed than too short. Often it makes sense to explain + the background. +\item What does a minimal working example look like? You can easily create one + by commenting out content and packages from the document step by step. The + result is a document that only contains the packages and parts necessary to + reproduce the problem. In addition, all loaded images should be replaced by + \Macro{rule} statements of the appropriate size. Before sending your + MWE,remove the commented-out parts, insert the command \Macro{listfiles} in + the preamble, and perform another {\LaTeX} run. At the end of the \File{log} + file, you will see an overview of the packages used. Add the MWE and the log + file to the end of your description of the problem. +\end{itemize} + +Do not send packages, PDF, PS, or DVI files. If the entire issue or bug +description, including the minimal example and the \File{log} file is larger +than a few tens of kilobytes, you're likely doing something wrong. + +If you've followed all these steps, please send your {\KOMAScript} (only) bug +report to \href{mailto:komascript@gmx.info}{komascript@gmx.info}. + +If you want to ask your question in a Usenet group, mailing list, or Internet +forum, you should follow the procedures mentioned above and include a minimal +working example as part of your question, but usually you don't need to +provide the \File{log}-file. Instead, just add the list of packages and +package versions from the \File{log}-file and, if your MWE compiles with +errors, you should quote those messages from the \File{log} file. + +Please note that default settings which are not typographically optimal do not +represent errors. For reasons of compatibility, defaults are preserved +whenever possible in new versions of {\KOMAScript}. Furthermore, typographical +best practices are partly a matter of language and culture, and so the default +settings of {\KOMAScript} are necessarily a compromise. + +\section{Additional Information} +\seclabel{moreinfos} + +Once you become familiar with {\KOMAScript}, you may want examples that show +how to accomplish more difficult tasks. Such examples go beyond the basic +instructional scope of this manual and so are not included. However, you will +find more examples on the website of the {\KOMAScript} Documentation Project +\cite{homepage}. These examples are designed for advanced {\LaTeX} users and +are not particularly suitable for beginners. The main language of the site +is German, but English is also welcome. + +\endinput +%%% Local Variables: +%%% mode: latex +%%% coding: us-ascii +%%% TeX-master: "../guide.tex" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/japanlco.tex b/macros/latex/contrib/koma-script/source-doc/english/japanlco.tex new file mode 100644 index 0000000000..6503afae06 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/japanlco.tex @@ -0,0 +1,601 @@ +% ====================================================================== +% japanlco.tex +% Copyright (c) Gernot Hassenpflug and Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% japanlco.tex +% Copyright (c) Gernot Hassenpflug und Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about Japanise paper size, envelopes and letters +% Maintained by Gernot Hassenplug (with help from Markus Kohm) +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber japanische Papierformate, Umschläge und Briefe +% Verwaltet von Gernot Hassenplug (mit Unterstuetzung von Markus Kohm) +% +% ====================================================================== +% +% Special Note: Originally in English by Gernot Hassenpflug as part of +% KOMA-Script bundle. +% + +\KOMAProvidesFile{japanlco.tex} + [$Date: 2018-03-21 10:37:34 +0100 (Wed, 21 Mar 2018) $ + KOMA-Script guide (appendix: japanlco)] + +\appendix + +\chapter[{Japanese Letter Support for \Class{scrlttr2}}] +{Japanese Letter Support for \Class{scrlttr2}\footnote{This chapter was + originally written by Gernot Hassenpflug.}} +\labelbase{japanlco} +\Index{letter>Japanese} + +Since version~2.97e, \Class{scrlttr2} has provided support not only for +European ISO~envelope sizes and window envelopes but also for Japanese +envelopes, in the form of \File{lco} files which set the layout of the paper. +This chapter documents this support and provides a few examples of using the +provided \File{lco} files to print letters intended for Japanese envelopes. + +\section{Japanese standard paper and envelope sizes} +\seclabel{PaperEnvelope} + +The Japan Industrial Standard (JIS) defines paper sizes and envelope sizes for +national use, which both overlap with the ISO and US sizes and include some +metricated traditional Japanese sizes. Envelope window size and position have +not been defined internationally as yet; hence, there exists a plethora of +envelopes with differing window sizes and positions. The following subsections +give some background on Japanese paper sizes and envelopes. + +\subsection{Japanese paper sizes} +\seclabel{Paper} + +The JIS defines two main series of paper sizes: +\begin{enumerate} +\item the JIS A-series, which is identical to the ISO A-series but + with slightly different tolerances; and +\item the JIS B-series, which is not identical to the ISO/DIN + B-series. Instead, the JIS B-series paper has an area 1.5 times that + of the corresponding A-series paper, so that the length ratio is + approximately 1.22 times the length of the corresponding A-series + paper. The aspect ratio of the paper is the same as for A-series + paper. +\end{enumerate} + +Both JIS A-series and B-series paper is widely available in Japan and most +photocopiers and printers are loaded with at least A4 and B4 paper. The +ISO/JIS~A-series and the different ISO and JIS~B-series sizes are listed in +\autoref{tab:japanlco.jpapersizes1}. + +%% ISO/JIS standard comparison +\begin{table} +\begin{minipage}{\textwidth}\renewcommand*{\footnoterule}{}% +\centering +\caption[{ISO and JIS standard paper sizes}] +{ISO and JIS standard paper sizes}%; trim sizes are given with width +% preceding height, both in millimeters} +\begin{tabular}{lr@{$\times$}llr@{$\times$}llr@{$\times$}l}\toprule +ISO/JIS\,A & \multicolumn2l{W$\times$H in mm} & ISO\,B & +\multicolumn2l{W$\times$H in mm} & JIS\,B & \multicolumn2l{W$\times$H + in mm} \\ \midrule +A0 & 841 & 1189 & B0 & 1000 & 1414 & B0 & 1030 & 1456 \\ +A1 & 594 & 841 & B1 & 707 & 1000 & B1 & 728 & 1030 \\ +A2 & 420 & 594 & B2 & 500 & 707 & B2 & 515 & 728 \\ +A3 & 297 & 420 & B3 & 353 & 500 & B3 & 364 & 515 \\ +A4 & 210 & 297 & B4 & 250 & 353 & B4 & 257 & 364 \\ +A5 & 148 & 210 & B5 & 176 & 250 & B5 & 182 & 257 \\ +A6 & 105 & 148\footnotemark[1] & B6 & 125 & 176 & B6 & 128 & 182 \\ +A7 & 74 & 105 & B7 & 88 & 125 & B7 & 91 & 128 \\ +A8 & 52 & 74 & B8 & 62 & 88 & B8 & 64 & 91 \\ +A9 & 37 & 52 & B9 & 44 & 62 & B9 & 45 & 64 \\ +A10 & 26 & 37 & B10 & 31 & 44 & B10 & 32 & 45 \\ +A11 & 18 & 26 & & \multicolumn2l{} & B11 & 22 & 32 \\ +A12 & 13 & 18 & & \multicolumn2l{} & B12 & 16 & 22 \\ +\bottomrule +\end{tabular} +\label{tab:japanlco.jpapersizes1} +\footnotetext[1]{Although Japan's official postcard size + appears to be A6, it is actually 100$\times$148\Unit{mm}, 5 millimetres + narrower than A6.} +\end{minipage} +\end{table} + +There are also a number of traditional paper sizes, which are now used +mostly only by printers. The most common of these old series are the +Shiroku-ban and the Kiku paper sizes. The difference of these types compared +to the JIS~B-series are shown in \autoref{tab:japanlco.jpapersizes2}. +Finally, there are some common stationery sizes, listed in +\autoref{tab:japanlco.jpapersizes3}. You may come across these when buying +stationery. + +%% JIS B-series variants +\begin{table} +\centering +\caption[{Japanese B-series variants}] +{Japanese B-series variants}%; trim sizes are given with width +% preceding height, both in millimeters} +\begin{tabular}{lr@{$\times$}lr@{$\times$}lr@{$\times$}l}\toprule +Format & \multicolumn{2}{l}{JIS B-series} & \multicolumn{2}{l}{Shiroku-ban} & +\multicolumn{2}{l}{Kiku} \\ +Size & \multicolumn{2}{l}{W$\times$H in mm} & \multicolumn{2}{l}{W$\times$H in mm} & \multicolumn{2}{l}{W$\times$H in mm} \\ \midrule +4 & 257 & 364 & 264 & 379 & 227 & 306 \\ +5 & 182 & 257 & 189 & 262 & 151 & 227 \\ +6 & 128 & 182 & 189 & 262 & \multicolumn2l{} \\ +7 & 91 & 128 & 127 & 188 & \multicolumn2l{} \\ +\bottomrule +\end{tabular} +\label{tab:japanlco.jpapersizes2} +\end{table} + +%% Japanese contemporary sizes +\begin{table} +\centering +\caption[{Main Japanese contemporary stationery}] +{Main Japanese contemporary stationery}%; trim sizes are given with width +% preceding height, both in millimeters} +\begin{tabular}{lr@{$\times$}ll}\toprule +Name & \multicolumn{2}{l}{W$\times$H in mm} & Usage and Comments \\ \midrule +Kokusai-ban & 216 & 280 & ``international size'' \\ + & \multicolumn2l{} & i.\,e., US letter size \\ +Semi B5 or & 177 & 250 & ``standard size'' \\ +Hyoujun-gata & \multicolumn2l{} & (formerly called ``Hyoujun-gata''),\\ + & \multicolumn2l{} & semi B5 is almost identical to ISO B5 \\ +Oo-gata & 177 & 230 & ``large size'' \\ +Chuu-gata & 162 & 210 & ``medium size'' \\ +Ko-gata & 148 & 210 & ``small size'' \\ +Ippitsu sen & 82 & 185 & ``note paper'' \\ +\bottomrule +\end{tabular} +\label{tab:japanlco.jpapersizes3} +\end{table} + +The ISO~C-series is not a paper size as such but a standard developed for +envelopes and intended for the corresponding A-series paper. It is discussed +in the next subsection. + +%\clearpage +\subsection{Japanese envelope sizes} +\seclabel{envelope} + +ISO (International Organization for Standardization) envelope sizes are the +official international metric envelope sizes; however, Japan uses also JIS and +metricated traditional envelope sizes. Sizes identified as non-standard do not +conform to Universal Postal Union requirements for correspondence envelopes. + +\subsubsection{ISO envelope sizes} +The ISO C-series envelope sizes, and possibly B-series envelope sizes, are +available in Japan. C-series envelopes can hold the corresponding A-series +paper, while B-series envelopes can hold either the corresponding A-series +paper or the corresponding C-series envelope. The ISO envelope sizes commonly +for Japan are listed in \autoref{tab:japanlco.jenvsizes1}, with the +corresponding paper they are intended for, and the folding required. + +%%%%%% JIS Japanese Envelopes + +%% ISO envelope sizes +%{\onelinecaptionsfalse +%\begin{longtable}{lr@{$\times$}ll} +\begin{table} +\begin{minipage}{\textwidth}\renewcommand*{\footnoterule}{} +\caption[{Japanese ISO envelope sizes}] +{Japanese ISO envelope sizes}%; trim sizes are given with width +% preceding height, both in millimeters% +\label{tab:japanlco.jenvsizes1}% +%}\\ +\begin{tabular}{lr@{$\times$}ll} +\toprule +Name & \multicolumn2l{W$\times$H in mm} & Usage and Comments \\ +%\endfirsthead +%\caption[]{Japanese envelope sizes (\emph{continued})}\\ +%\toprule +%Name & \multicolumn2l{W$\times$H in mm} & Usage and Comments \\ +%\midrule +%\endhead +%\midrule +%\multicolumn{4}{r@{}}{\dots}\\ +%\endfoot +%\bottomrule +%\endlastfoot +\midrule +C0 & 917 & 1297 & for flat A0 sheet; \\* + & \multicolumn2l{} & non-standard \\ +C1 & 648 & 917 & for flat A1 sheet; \\* + & \multicolumn2l{} & non-standard \\ +C2 & 458 & 648 & for flat A2 sheet, A1 sheet folded in half; \\* + & \multicolumn2l{} & non-standard \\ +C3 & 324 & 458 & for flat A3 sheet, A2 sheet folded in half; \\* + & \multicolumn2l{} & non-standard \\ +B4 & 250 & 353 & C4 envelope \\ +C4 & 229 & 324 & for flat A4 sheet, A3 sheet folded in half; \\* + & \multicolumn2l{} & very common; non-standard \\ +B5 & 176 & 250 & C5 envelope \\ +C5 & 162 & 229 & for flat A5 sheet, A4 sheet folded in half; \\* + & \multicolumn2l{} & very common; non-standard \\ +B6 & 125 & 176 & C6 envelope; A4 folded in quarters; \\* + & \multicolumn2l{} & very common \\ +C6 & 114 & 162 & for A5 sheet folded in half, \\* + & \multicolumn2l{} & A4 sheet folded in quarters; \\* + & \multicolumn2l{} & very common \\ +C6/C5 & 114 & 229 & A4 sheet folded in thirds; \\* + & \multicolumn2l{} & very common \\ +C7/6 & 81 & 162 & for A5 sheet folded in thirds; uncommon; \\* + & \multicolumn2l{} & non-standard \\ +C7 & 81 & 114 & for A5 sheet folded in quarters; uncommon; \\* + & \multicolumn2l{} & non-standard \\ +C8 & 57 & 81 & \\ +C9 & 40 & 57 & \\ +C10 & 28 & 40 & \\ +DL\footnotemark[1] & 110 & 220 & for A4 sheet folded in thirds, \\* + & \multicolumn2l{} & A5 sheet folded in half lengthwise; \\* + & \multicolumn2l{} & very common \\ +%\end{longtable}}\vspace{-\baselineskip} +\bottomrule +\end{tabular} +%\noindent\begin{minipage}{\textwidth} +%\renewcommand*{\footnoterule}{} +\footnotetext[1]{Although DL is not part of the + ISO C-series, it is a very widely used standard size. DL, probably + at one time the abbreviation of DIN Lang (Deutsche Industrie Norm, + long), is now identified as ``Dimension Lengthwise'' by ISO 269.} +\end{minipage} +\end{table} + +\subsubsection{JIS and traditional envelope sizes} +The JIS classifies envelopes into three categories based on the +general shape of the envelope and where the flap is located: + +\begin{description} +\item[You:] these envelopes are of the `commercial' type, rectangular, + and correspond largely to Western envelope sizes, and also have the + flap on the long dimension (`Open Side') in `commercial' or `square' + style. `You-kei' means Western-style. +\item[Chou:] these are also `commercial' type envelopes, with the same + shape as the corresponding `You' type, but with the flap on the + short dimension (`Open End') in `wallet' style. `Chou-kei' means + long-style. +\item[Kaku:] these envelopes are more square in appearance and are + made for special use, and correspond to `announcement' + envelopes. The flap is on the long side, in the `square' style. They + generally do not fall under the ordinary envelope postage + rates. `Kaku-kei' means square-style. +\end{description} + +The main JIS and traditional envelope sizes, the corresponding paper, and +its required folding are listed in \autoref{tab:japanlco.jenvsizes2}. + +%% JIS and other envelope sizes +%\begin{table} +%\begin{minipage}{\textwidth}\renewcommand*{\footnoterule}{}% +%\centering +{\onelinecaptionsfalse +\begin{longtable}{llr@{$\times$}ll} +\caption[{Japanese envelope sizes 3}] +{Japanese JIS and other envelope sizes\label{tab:japanlco.jenvsizes2}}% +%; trim sizes are given with width preceding height, both in millimeters}% +\\ +%\begin{tabular}{llr@{$\times$}ll} +\toprule +JIS & Name & \multicolumn2l{W$\times$ in mm} & Usage and Comments \\ +\endfirsthead +\caption[]{Japanese JIS and other envelope sizes (\emph{continued})}\\ +\toprule +JIS & Name & \multicolumn2l{W$\times$ in mm} & Usage and Comments \\ +\midrule +\endhead +\midrule +\multicolumn{5}{r@{}}{\dots}\\ +\endfoot +\bottomrule +\endlastfoot +\midrule + & Chou 1 & 142 & 332 & for A4 folded in half lengthwise;\\* + & & \multicolumn2l{} & non-standard \\ +Yes & Chou 2 & 119 & 277 & for B5 folded in half lengthwise;\\* + & & \multicolumn2l{} & non-standard \\ +Yes & Chou 3 & 120 & 235 & for A4 folded in thirds;\\* + & & \multicolumn2l{} & very common \\ + & Chou 31 & 105 & 235 & for A4 folded in thirds \\ + & Chou 30 & 92 & 235 & for A4 folded in fourths\footnotemark[3] \\ + & Chou 40 & 90 & 225 & for A4 folded in fourths\footnotemark[3] \\ +Yes & Chou 4 & 90 & 205 & for JIS B5 folded in fourths\footnotemark[3];\\* + & & \multicolumn2l{} & very common \\ + & Kaku A3 & 320 & 440 & for A3 flat, A2 folded in half\\* + & & \multicolumn2l{} &; non-standard \\ + & Kaku 0 & 287 & 382 & for B4 flat, B3 folded in half;\\* + & & \multicolumn2l{} & non-standard \\ + & Kaku 1 & 270 & 382 & for B4 flat, B3 folded in half;\\* + & & \multicolumn2l{} & non-standard \\ +Yes & Kaku 2 & 240 & 332 & for A4 flat, A3 folded in half;\\* + & & \multicolumn2l{} & non-standard \\ + & Kaku & 229 & 324 & for A4 flat, A3 folded in half;\\* + & Kokusai A4 & \multicolumn2l{} & same size as ISO C4;\\* + & & \multicolumn2l{} & non-standard \\ +Yes & Kaku 3 & 216 & 277 & for B5 flat, B4 folded in half;\\* + & & \multicolumn2l{} & non-standard \\ +Yes & Kaku 4 & 197 & 267 & for B5 flat, B4 folded in half;\\* + & & \multicolumn2l{} & non-standard \\ +Yes & Kaku 5 & 190 & 240 & for A5 flat, A4 folded in half\\* + & & \multicolumn2l{} &; non-standard \\ +Yes & Kaku 6 & 162 & 229 & for A5 flat, A4 folded in half;\\* + & & \multicolumn2l{} & same size as ISO C5;\\* + & & \multicolumn2l{} & non-standard \\ +Yes & Kaku 7 & 142 & 205 & for B6 flat, B5 folded in half;\\* + & & \multicolumn2l{} & non-standard \\ +Yes & Kaku 8 & 119 & 197 & pay envelope (for salaries, wages)\\* + & & \multicolumn2l{} &; common for direct mail \\ +Yes & You 0\footnotemark[1] & 235 & 120 & for A4 folded in thirds;\\* + & or Furusu 10 & \multicolumn2l{} & same size as Chou 3 but with \\* + & & \multicolumn2l{} & `Open Side' style flap \\ + & You 0\footnotemark[1] & 197 & 136 & for kyabine\footnotemark[1] (cabinet) size photos \\* + & & \multicolumn2l{} & (165\Unit{mm}$\times$120\Unit{mm});\\* + & & \multicolumn2l{} & non-standard \\ + & You 1\footnotemark[2] & 176 & 120 & for B5 folded in quarters \\ + & You 1\footnotemark[2] & 173 & 118 & for B5 folded in quarters \\ +Yes & You 2 & 162 & 114 & for A5 folded in half,\\* + & & \multicolumn2l{} & A4 folded in quarters;\\* + & & \multicolumn2l{} & same size as ISO C6 \\ +Yes & You 3 & 148 & 98 & for B6 folded in half \\ +Yes & You 4 & 235 & 105 & for A4 folded in thirds \\ +Yes & You 5 & 217 & 95 & for A4 folded in fourths\footnotemark[3] \\ +Yes & You 6 & 190 & 98 & for B5 folded in thirds \\ +Yes & You 7 & 165 & 92 & for A4 folded in quarters,\\* + & & \multicolumn2l{} & B4 folded in quarters \\ +%\bottomrule +%\end{tabular}% +\end{longtable}}\vskip-\baselineskip +\noindent\begin{minipage}{\textwidth}\renewcommand*{\footnoterule}{}% + \footnotetext[1]{Because two different sizes are called You~0, the + JIS You~0 is normally called Furusu~10; Furusu (`fools') derives + from `foolscap'; Kyabine is a metricated traditional Japanese + size.}% + \footnotetext[2]{Two slightly different sizes are sold as You~1; the + smaller size (173\Unit{mm}$\times$118\Unit{mm}) is the + paper-industry standard size.}% + \footnotetext[3]{Twice in the same direction.}% +\end{minipage} +%\end{table} + + +\subsubsection{Window variants} +There are a large number of window subtypes existing within the +framework explained in the previous subsection. The most common window +sizes and locations are listed in \autoref{tab:japanlco.jwinsizes1}. + +%% my table of windows +\begin{table} +\begin{minipage}{\textwidth}\renewcommand*{\footnoterule}{} +\centering +\caption[{Supported Japanese envelope types, window sizes, and + locations}] {Supported Japanese envelope types, window sizes, and + locations.} +\begin{tabular}{lllll} +\toprule +Envelope type & Window name\footnotemark[1] & - size\footnotemark[2] & - location\footnotemark[3] & \File{lco} file\footnotemark[4] \\ +\midrule +Chou 3 & A & 90$\times$45 & l 23, t 13 & \Option{NipponEL} \\ +Chou 3 & F & 90$\times$55 & l 23, t 13 & \Option{NipponEH} \\ +Chou 3 & Hisago & 90$\times$45 & l 23, t 12 & \Option{NipponEL} \\ +Chou 3 & Mutoh 1 & 90$\times$45 & l 20, t 11 & \Option{NipponEL} \\ +Chou 3 & Mutoh 101 & 90$\times$55 & l 20, t 11 & \Option{NipponEH} \\ +Chou 3 & Mutoh 2 & 80$\times$45 & l 20, t 11 & \Option{NipponEL} \\ +Chou 3 & Mutoh 3 & 90$\times$45 & l 25, t 11 & \Option{NipponLL} \\ +Chou 3 & Mutoh 301 & 90$\times$55 & l 25, t 11 & \Option{NipponLH} \\ +Chou 3 & Mutoh 6 & 100$\times$45 & l 20, t 11 & \Option{NipponEL} \\ +Chou 3 & v.2\footnotemark[5] & 90$\times$45 & l 24, t 12 & \Option{NipponLL} \\ +Chou 40 & A & 90$\times$45 & l 23, t 13 & \Option{NipponEL} \\ +Chou 4 & A & 90$\times$45 & l 23, t 13 & \Option{NipponEL} \\ +Chou 4 & B & 80$\times$45 & l 98, t 28 & \Option{NipponRL} \\ +Chou 4 & C & 80$\times$45 & l 21, t 13 & \Option{NipponEL} \\ +Chou 4 & K & 80$\times$45 & l 22, t 13 & \Option{NipponEL} \\ +Chou 4 & Mutoh 1 & 80$\times$45 & l 40, b 11 & --- \\ +Chou 4 & Mutoh 2 & 80$\times$45 & l 20, t 11 & \Option{NipponEL} \\ +Chou 4 & Mutoh 3 & 90$\times$45 & l 20, t 11 & \Option{NipponEL} \\ +Chou 4 & Mutoh 6 & 100$\times$45 & l 20, t 11 & \Option{NipponEL} \\ +Chou 4 & v.2\footnotemark[5] & 80$\times$45 & l 20, t 12 & \Option{NipponEL} \\ +Chou 4 & v.3\footnotemark[5] & 90$\times$45 & l 20, t 12 & \Option{NipponEL} \\ +Kaku A4 & v.1\footnotemark[6] & 95$\times$45 & l 20, t 24 & \Option{KakuLL} \\ +You 0 & Cruise 6 & 90$\times$45 & l 20, t 12 & \Option{NipponEL} \\ +You 0 & Cruise 601 & 90$\times$55 & l 20, t 12 & \Option{NipponEH} \\ +You 0 & Cruise 7 & 90$\times$45 & l 20, b 12 & \Option{NipponEL} \\ +You 0 & Cruise 8 & 90$\times$45 & l 24, t 12 & \Option{NipponLL} \\ +You 0 & v.2\footnotemark[5] & 90$\times$45 & l 24, t 12 & \Option{NipponEL} \\ +You 0 & v.3\footnotemark[5] & 90$\times$45 & l 23, t 13 & \Option{NipponEL} \\ +You 4 & A & 90$\times$45 & l 23, t 13 & \Option{NipponEL} \\ +\bottomrule +\end{tabular}% +\footnotetext[1]{Names (acting as subtype information) are taken from + the manufacturer catalogue.}% +\footnotetext[2]{Given as width by height in millimetres.}% +\footnotetext[3]{Given as offset from left (l) or right (r), followed by + offset from bottom (b) or top (t).}% +\footnotetext[4]{The \File{lco} file, which provides support (see + \autoref{tab:japanlco.lcolist}).}% +\footnotetext[5]{In the absence of any other information, a numerical + variation number for the subtype name is provided.}% +\footnotetext[6]{Dimensions apply when envelope is held in portrait mode.}% +\label{tab:japanlco.jwinsizes1}% +\end{minipage} +\end{table} + +\section{Provided \File{lco} files} +In \Class{scrlttr2}, support is provided for Japanese envelope and +window sizes through a number of \File{lco} files which customize the +fold marks required for different envelope sizes and subvariants with +different window positions and sizes. + +The \File{lco} files provided together with the envelope types that they +support are listed at \autoref{tab:japanlco.lcolist}. See +\autoref{tab:japanlco.jenvsizes1} for the full list of Japanese envelopes and +the paper they take, and \autoref{tab:japanlco.jwinsizes1} for the common +window sizes and locations. The rightmost column indicates which \File{lco} +file provides the support. + +The tolerances for location is about 2\Unit{mm}, so it is possible to +accommodate all the envelope and window variants of +\autoref{tab:japanlco.jwinsizes1} with just a small number of \File{lco} +files. The difference between Chou/You~3 and Chou/You~4 is determined +by paper size. + +\begin{table} +\begin{minipage}{\textwidth}\renewcommand*{\footnoterule}{} +\centering +\caption{\File{lco} files provided by \Class{scrlttr2} for Japanese window + envelopes} +\begin{tabular}{llll} +\toprule +\File{lco} file & Supported & Window size\footnotemark[1] & Window +location\footnotemark[1] \\ +\midrule +\Option{NipponEL} & Chou/You 3 and 4 & 90$\times$45 & l 22, t 12 \\ +\Option{NipponEH} & Chou/You 3 and 4 & 90$\times$55 & l 22, t 12 \\ +\Option{NipponLL} & Chou/You 3 and 4 & 90$\times$45 & l 25, t 12 \\ +\Option{NipponLH} & Chou/You 3 and 4 & 90$\times$55 & l 25, t 12 \\ +\Option{NipponRL} & Chou/You 3 and 4 & 90$\times$45 & l 98, t 28 \\ +\Option{KakuLL} & Kaku A4 & 90$\times$45 & l 25, t 24 \\ +\bottomrule +\end{tabular}% +\label{tab:japanlco.lcolist}% +\footnotetext[1]{Window size is given in width by height, location as + offset from left (l) or right (r), followed by offset from bottom (b) or top + (t). All Values in millimeters.}% +\end{minipage} +\end{table} + +\section{Examples of Japanese Letter Usage} +Suppose you want to write a letter on A4 size paper and will post it in +a Japanese envelope. If the envelope has no window, then it is enough +to determine whether the envelope dimensions match a European +one\,---\,the standard \File{DIN.lco} style may suffice for many such +cases. + +If you wish to use a windowed envelope, please note that owing to the +large variety, not all existing subvariants are currently +supported. If you notice that the window dimensions and positions +of your particular windowed envelope differ significantly (more than +approximately 2\Unit{mm}) from those of any of the supported subvariants, +please contact the author of {\KOMAScript} to obtain support as soon as +possible, and in the meantime, create a customized \File{lco} file for your +own use, using one of the existing ones as a template and reading the +{\KOMAScript} documentation attentively. + +If your window envelope subvariant is supported, this is how you would +go about using it: simply select the required \File{lco} file and +activate the horizontal and vertical fold marks as required. Another, +independent, mark is the hole-punch mark, which divides a sheet in two +horizontally for easy punching and filing. + +\subsection{Example 1:} +Your favourite envelope happens to be a You~3 with window subvariant +Mutoh~3, left over from when the company had its previous name, and +you do not wish them to go to waste. Thus, you write your letter with +the following starting code placed before the letter environment: + +\begin{lstlisting} +\LoadLetterOption{NipponLL}\setkomavar{myref}{NipponLL} +\begin{letter}{Martina Muster\\Address} +... +\end{letter} +\end{lstlisting} + +\subsection{Example 2:} +You originally designed your letter for a You~3 envelope, but suddenly +you get handed a used electrical company envelope with cute manga +characters on it which you simply cannot pass up. Surprisingly, you +find it conforms fairly closely to the Chou~4 size and C window +subvariant, such that you realize you can alter the following in your +document preamble: + +\begin{lstlisting} +\LoadLetterOption{NipponEL}\setkomavar{myref}{NipponEL} +\begin{letter}{Martina Muster\\Address} +... +\end{letter} +\end{lstlisting} + +Now, \Class{scrlttr2} automatically reformats the letter for you to +fit the required envelope. + +% \LoadLetterOption{NipponEL}\setkomavar{myref}{NipponEL} +% \begin{letter}{Martina Muster\\at and\\there\\and one\\more} +% \opening{Dear Martina,} +% \lipsum[1-2] +% \closing{Regards} +% \ps{PS: Forgotten to say.} +% \encl{Something} +% \cc{Somebody\\Someone} +% \end{letter} + +% \LoadLetterOption{NipponEH}\setkomavar{myref}{NipponEH} +% \begin{letter}{Martina Muster\\at and\\there\\and one\\more} +% \opening{Dear Martina,} +% \lipsum[1-2] +% \closing{Regards} +% \end{letter} + +% \LoadLetterOption{NipponLL}\setkomavar{myref}{NipponLL} +% \begin{letter}{Martina Muster\\at and\\there\\and one\\more} +% \opening{Dear Martina,} +% \lipsum[1-2] +% \closing{Regards} +% \end{letter} + +% \LoadLetterOption{NipponLH}\setkomavar{myref}{NipponLH} +% \begin{letter}{Martina Muster\\at and\\there\\and one\\more} +% \opening{Dear Martina,} +% \lipsum[1-2] +% \closing{Regards} +% \end{letter} + +%% comparison of US common paper sizes, wider and shorter +% Millimetres Inches Points +% Height Width Height Width Height Width +% Letter 279.4 215.9 11.00 8.50 792 612 +% Legal 355.6 215.9 14.00 8.50 1008 612 +% Ledger 431.8 279.4 17.00 11.00 1224 792 +% Tabloid 279.4 431.8 11.00 17.00 792 1224 +% Executive 266.7 184.1 10.55 7.25 756 522 + +%% English foolscap is here for reference +% Millimetres Inches Points +% Height Width Height Width Height Width +%Foolscap 419 336 16.50 13.25 1188 954 +% + +%% nice reference on envelope types and windows in the US +%http://www.belightsoft.com/products/companion/paper/envelopes.php + +%%% Local Variables: +%%% mode: latex +%%% coding: iso-latin-1 +%%% TeX-master: t +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/linkalias.tex b/macros/latex/contrib/koma-script/source-doc/english/linkalias.tex new file mode 120000 index 0000000000..dd3b49476e --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/linkalias.tex @@ -0,0 +1 @@ +../linkalias.tex
\ No newline at end of file diff --git a/macros/latex/contrib/koma-script/source-doc/english/preface.tex b/macros/latex/contrib/koma-script/source-doc/english/preface.tex new file mode 100644 index 0000000000..873f303987 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/preface.tex @@ -0,0 +1,125 @@ +% ====================================================================== +% preface.tex +% Copyright (c) Markus Kohm, 2008-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% preface.tex +% Copyright (c) Markus Kohm, 2008-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== + +\KOMAProvidesFile{preface.tex} + [$Date: 2018-03-28 11:44:09 +0200 (Wed, 28 Mar 2018) $ + Preface to version 3.25] +\translator{Markus Kohm\and Karl Hagen} + +% Date of the translated German file: 2018-03-12 + +\addchap{Preface to \KOMAScript~3.25} + +The \KOMAScript~3.25 manual,\---\,especially the German version\,---\,once +again benefits from the fact that a new edition of the print version +\cite{book:komascript} and the eBook version \cite{ebook:komascript} will be +published at almost the same time as this version. This has led to many +improvements which also affect the free manual, in both the German and the +English version. + +One of these improvements is the linking to the explanations of commands, +environments, options, etc., within the manual. To avoid the temptation to +jump to the beginning of the explanation within the explanation itself, and +so to avoid reading recursively, as it were, these links only take effect +if they actually lead away from the current location. + +Another important improvement to the English guide has been accomplished by +Karl Hagen, who has newly translated the entire manual. Many, many thanks to +him! Additional editors or translators, however, would still be welcome! + +\iffree{Readers of this free, screen version, however, still have to live with + some restrictions. So some information\,---\,mainly intended for advanced + users or capable of turning an ordinary user into an advanced one\,---\,is + reserved for the printed book, which currently exists only in German. As a + result, some links in this manual lead to a page that simply mentions this + fact. In addition, the free version is scarcely suitable for making a + hard-copy. The focus, instead, is on using it on screen, in parallel with + the document you are working on. It still has no optimized wrapping but is + almost a first draft, in which both the paragraph and page breaks are in + some cases quite poor. Corresponding optimizations are reserved for the + German book editions.}{} + +It is not just about the manual that I now receive little criticism. For the +classes and packages as well, there are hardly any requests for new features. +For me, this means that my knowledge about user desires stagnates. So for a +few years, I mostly implemented things that I thought could be useful. +However, the feedback that I have received about these new possibilities was +largely limited to complaints that old \emph{hacks} based on undocumented +\KOMAScript{} features sometimes no longer work. Little was said about the +happiness that such dirty workarounds were no longer necessary. Therefore, I +have decided to limit extensions and improvements to \KOMAScript{} more and +more to those things that are explicitly requested by users. Could it be that +\KOMAScript{}, after only 25 years, has reached the level that it fulfils all +desires? + +Unfortunately, the declining number of error reports is not purely gratifying. +Over this period, I have often observed that those who discover a problem no +longer report it directly to me but work around it with the help of some +Internet forums. Often, there are more or less ingenious workarounds in these +forums. Although this is generally helpful, it unfortunately, as a rule, +causes the problem to remain unreported and therefore never really eliminated. +It goes without saying that such workarounds can sometimes become a problem +themselves, as mentioned in the previous paragraph. + +Thankfully, there are third parties who occasionally point out such issues. +This applies to individual contributions in a very few forums. Direct contact +with the person for whom the problem occurred is in this case usually not +possible, although it would sometimes be desirable. + +Therefore, let me please ask again explicitly that you report all suspected +bugs directly, either in German or in English. Linguistic perfection is less +important. The message should be reasonably understandable and the problem +comprehensible. A code example that is as short as possible is generally +independent of the language used. With direct contact, I can ask further +questions, if necessary. Please do not rely on anyone else to report the +problem at some point. Assume that it will only be fixed if you report it +yourself. More about error messages can be found in the first chapter of the +manual. + +\bigskip\noindent +Markus Kohm, Neckarhausen in the March rain, 2018. + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% ispell-local-dictionary: "english" +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: + diff --git a/macros/latex/contrib/koma-script/source-doc/english/scraddr.tex b/macros/latex/contrib/koma-script/source-doc/english/scraddr.tex new file mode 100644 index 0000000000..ac5ef90a5e --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scraddr.tex @@ -0,0 +1,261 @@ +% ====================================================================== +% scraddr.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scraddr.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scraddr of the KOMA-Script guide +% Maintained by Jens-Uwe Morawski (with help from Markus Kohm) +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber scraddr in der KOMA-Script-Anleitung +% Verwaltet von Jens-Uwe Morawski (mit Unterstuetzung von Markus Kohm) +% +% ====================================================================== + +\KOMAProvidesFile{scraddr.tex} + [$Date: 2018-03-27 11:46:14 +0200 (Tue, 27 Mar 2018) $ + KOMA-Script guide (chapter: scraddr)] +\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm\and Karl + Hagen} + +% Date of the translated German file: 2018-02-05 + +\chapter{Accessing Address Files with \Package{scraddr}}% +\labelbase{scraddr}% +\BeginIndexGroup +\BeginIndex{Package}{scraddr} + +The \Package{scraddr} package is a small extension to \KOMAScript{}'s letter +class and letter package. Its goal is to make access to the data in address +files easier and more flexible. + +\section{Overview}\seclabel{overview} +Basically, the package provides a new loading mechanism for address files +consisting of \DescRef{\LabelBase.cmd.adrentry} and the newer +\DescRef{\LabelBase.cmd.addrentry} format entries, as described in +\autoref{cha:scrlttr2} starting on \DescPageRef{scrlttr2.cmd.adrentry}. + +\begin{Declaration} +\Macro{InputAddressFile}\Parameter{file name} +\end{Declaration}% +The \Macro{InputAddressFile} command is the main command of \Package{scraddr}. +It reads the content of the address file\Index{address>file} given as its +parameter. If the file is not found, an error message is issued. + +For each entry in this address file, the command generates a set of +macros to access the data. For large address files, this will require +a lot of \TeX{} memory. +% +\EndIndexGroup + +\begin{Declaration}% + \Macro{adrentry}\Parameter{Lastname}\Parameter{Firstname}% + \Parameter{Address}\Parameter{Phone}\Parameter{F1}\Parameter{F2}% + \Parameter{Comment}\Parameter{Key}% + % + \Macro{addrentry}\Parameter{Lastname}\Parameter{Firstname}% + \Parameter{Address}\Parameter{Phone}\Parameter{F1}\Parameter{F2}% + \Parameter{F3}\Parameter{F4}\Parameter{Key}% + % + \Macro{adrchar}\Parameter{initial}% + \Macro{addrchar}\Parameter{initial}% +\end{Declaration}% +The structure of the address entries in the address file was discussed in +detail in \autoref{sec:scrlttr2.addressFile}, starting on +\DescPageRef{scrlttr2.cmd.adrentry}. The subdivision of the address file with +the help of \Macro{adrchar} or \Macro{addrchar}, also discussed there, has no +meaning for \Package{scraddr} and is simply ignored by the package.% +\EndIndexGroup + +\begin{Declaration} + \Macro{Name}\Parameter{key}% + \Macro{FirstName}\Parameter{key}% + \Macro{LastName}\Parameter{key}% + \Macro{Address}\Parameter{key}% + \Macro{Telephone}\Parameter{key}% + \Macro{FreeI}\Parameter{key}% + \Macro{FreeII}\Parameter{key}% + \Macro{Comment}\Parameter{key}% + \Macro{FreeIII}\Parameter{key}% + \Macro{FreeIV}\Parameter{key} +\end{Declaration}% +These commands give access to data of your address file. The last parameter, +that is, parameter 8 for the \DescRef{\LabelBase.cmd.adrentry} entry and +parameter 9 for the \DescRef{\LabelBase.cmd.addrentry} entry, is the +identifier of an entry, thus the \PName{key} has to be unique and non-empty. +To guarantee safe functioning, you should use only ASCII letters in the +\PName{key}. + +Furthermore, if the file contains more than one entry with the same +\PName{key} name, the last occurrence will be used.% +% +\EndIndexGroup + + +\section{Usage}\seclabel{usage} +\BeginIndexGroup +\BeginIndex[indexother]{Cmd}{addrentry}% +\BeginIndex[indexother]{Cmd}{adrentry}% +To use the package, we need a valid address file. For example, the file +\File{lotr.adr} contains the following entries: +\begin{lstcode} + \addrentry{Baggins}{Frodo}% + {The Hill\\ Bag End/Hobbiton in the Shire}{}% + {Bilbo Baggins}{pipe-weed}% + {the Ring-bearer}{Bilbo's heir}{FRODO} + \adrentry{Gamgee}{Samwise}% + {3 Bagshot Row\\Hobbiton in the Shire}{}% + {Rosie Cotton}{taters}% + {the Ring-bearer's faithful servant}{SAM} + \adrentry{Bombadil}{Tom}% + {The Old Forest}{}% + {Goldberry}{trill queer songs}% + {The Master of Wood, Water and Hill}{TOM} +\end{lstcode} + +The fourth parameter, the telephone number, has been left blank, since there +are no phones in Middle Earth. And as you can see, blank fields are possible. +On the other hand, you cannot simply omit an argument altogether. + +\BeginIndexGroup +\BeginIndex[indexother]{Cmd}{InputAddressFile} +With the \Macro{InputAddressFile} command described above, we read the address +file into our letter document: +\begin{lstcode} + \InputAddressFile{lotr} +\end{lstcode} +\EndIndexGroup + +\BeginIndexGroup +\BeginIndex[indexother]{Cmd}{Name}% +\BeginIndex[indexother]{Cmd}{Address}% +\BeginIndex[indexother]{Cmd}{FirstName}% +\BeginIndex[indexother]{Cmd}{LastName}% +\BeginIndex[indexother]{Cmd}{FreeI}% +\BeginIndex[indexother]{Cmd}{FreeII}% +\BeginIndex[indexother]{Cmd}{FreeIII}% +\BeginIndex[indexother]{Cmd}{FreeIV}% +\BeginIndex[indexother]{Cmd}{Comment}% +With the help of the commands introduced in this chapter we can now write a +letter to old \textsc{Tom Bombadil}, in which we ask him if he can remember +two companions from olden times. +\begin{lstcode} + \begin{letter}{\Name{TOM}\\\Address{TOM}} + \opening{Dear \FirstName{TOM} \LastName{TOM},} + + Or \FreeIII{TOM}, as your beloved \FreeI{TOM} calls you. Do + you still remember Mr \LastName{FRODO}, or more precisely + \Name{FRODO}, since there was also Mr \FreeI{FRODO}. He was + \Comment{FRODO} in the Third Age and \FreeIV{FRODO}. \Name{SAM}, + \Comment{SAM}, accompanied him. + + Their passions were very worldly. \FirstName{FRODO} enjoyed + smoking \FreeII{FRODO}. His companion appreciated a good meal + with \FreeII{SAM}. + + Do you remember? Certainly Mithrandir has told you much + about their deeds and adventures. + \closing{``O spring-time and summer-time + and spring again after!\\ + O wind on the waterfall, + and the leaves' laughter!''} + \end{letter} +\end{lstcode} +You can also produce the combination of \Macro{FirstName}\Parameter{key} and +\Macro{LastName}\Parameter{key} used in the \DescRef{scrlttr2.cmd.opening} of +this letter with \Macro{Name}\PParameter{key}. + +You can use the fifth and sixth parameters of the +\DescRef{\LabelBase.cmd.adrentry} or \DescRef{\LabelBase.cmd.adrentry} for any +purpose you wish. You can access them with the \Macro{FreeI} and +\Macro{FreeII} commands. In this example, the fifth parameter contains the +name of the most important person in the life of the person in the entry. The +sixth contains the person's favourite thing. The seventh parameter is a +comment or in general also a free parameter. You can access it with the +\Macro{Comment} or \Macro{FreeIII} commands. \Macro{FreeIV} is only valid for +\DescRef{\LabelBase.cmd.addrentry} entries. For +\DescRef{\LabelBase.cmd.adrentry} entries, it results in an error. You can +find more details in the next section. +% +\EndIndexGroup +\EndIndexGroup + + +\section{Package Warning Options} + +As mentioned above, you cannot use the \Macro{FreeIV} command with +\DescRef{\LabelBase.cmd.adrentry} entries. However, you can configure how +\Package{scraddr} reacts in such a situation by package options. +Note\textnote{Attention!} that this package does not support the extended +options interface with \DescRef{maincls.cmd.KOMAoptions} and +\DescRef{maincls.cmd.KOMAoption}. You should therefore specify the options +either as global options in \DescRef{maincls.cmd.documentclass} or as local +options in \DescRef{maincls.cmd.usepackage} + + +\begin{Declaration} + \Option{adrFreeIVempty}% + \Option{adrFreeIVshow}% + \Option{adrFreeIVwarn}% + \Option{adrFreeIVstop}% +\end{Declaration}% +These four options let you choose from four different reactions, ranging +from \emph{ignore} to \emph{abort}, if \Macro{FreeIV} is used +within an \DescRef{\LabelBase.cmd.adrentry} entry. + +\begin{labeling}[~--]{\Option{adrFreeIVempty}} +\item[\Option{adrFreeIVempty}] + the command \Macro{FreeIV} will be ignored +\item[\Option{adrFreeIVshow}] + the warning ``(entry FreeIV undefined at \PName{key})'' will be + written in the text +\item[\Option{adrFreeIVwarn}] + a warning is written in the logfile +\item[\Option{adrFreeIVstop}] + the \LaTeX{} run will abort with an error message +\end{labeling} +The default setting is \Option{adrFreeIVshow}.% +\EndIndexGroup +% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrbase.tex b/macros/latex/contrib/koma-script/source-doc/english/scrbase.tex new file mode 100644 index 0000000000..80ed5b2b03 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrbase.tex @@ -0,0 +1,1659 @@ +% ====================================================================== +% scrbase.tex +% Copyright (c) Markus Kohm, 2002-2019 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrbase.tex +% Copyright (c) Markus Kohm, 2002-2019 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Package scrbase for Package and Class Authors +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Paket scrbase fuer Paket- und Klassenautoren +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{scrbase.tex} + [$Date: 2019-01-15 08:29:44 +0100 (Tue, 15 Jan 2019) $ + KOMA-Script package scrbase] +\translator{Markus Kohm\and Melvin Hendrix\and Karl Hagen} + +% Date of the translated German file: 2018-08-27 + +\chapter{Basic Functions in the \Package{scrbase} Package} +\labelbase{scrbase} +\BeginIndexGroup +\BeginIndex{Package}{scrbase}% + +The \Package{scrbase} package provides basic features intended for use by +authors of packages and classes. Its use is not limited merely to wrapper +classes which in turn load a \KOMAScript{} class. Authors of classes that +otherwise have nothing to do with \KOMAScript{} can also benefit from the +functionality of \Package{scrbase}. + +\section{Loading the Package} +\seclabel{loadit} + +Whereas users load packages with \Macro{usepackage}, authors of packages or +classes should use \Macro{RequirePackage}\IndexCmd{RequirePackage}. Authors of +wrapper packages can also use \Macro{RequirePackageWithOptions}. The +\Macro{RequirePackage} command has the same optional argument for package +options as \Macro{usepackage}. In contrast, \Macro{RequirePackageWithOptions} +does not have an optional argument but passes to this package all the options +that were previously given when loading the wrapper package or class. See +\cite{latex:clsguide} for more information about these commands. + +The \Package{scrbase} package needs the functionality of the +\Package{keyval}\IndexPackage{keyval} package internally. This can also be +provided by the \Package{xkeyval} package. If needed, \Package{scrbase} itself +loads \Package{keyval}. + +The \Package{keyval} package lets you define keys and assign values to them. +The options provided by \Package{scrbase} also use \Package{keyval} syntax: +\PName{key}\texttt{=}\PName{value}. + + +\section{Keys as Attributes of Families and their Members} +\seclabel{keyvalue} + +As already mentioned in \autoref{sec:scrbase.loadit}, \Package{scrbase} uses +the \Package{keyval} package to set keys and their values. However, +\Package{scrbase} extends this functionality. Whereas with \Package{keyval} a +key belongs to only one family, \Package{scrbase} also recognizes family +members. A key can therefore belong to both a family and one or more family +members. Additionally, you can assign a value to the key of a family member, +to the key of a family, or to the keys of all family members. + +\begin{Declaration} + \Macro{DefineFamily}\Parameter{family}% + \Macro{DefineFamilyMember}\OParameter{member}\Parameter{family}% +\end{Declaration} +\Package{scrbase} needs to know the members of a family for various reasons. +Therefore, you must first define a new family using \Macro{DefineFamily}, +which produces an empty member list. If the family has already been defined, +nothing happens. Therefore an existing member list will not be overwritten. + +Next, you can add a new member to the family using \Macro{DefineFamilyMember}. +If the family does not exist, this will result in an error message. If the +member already exists, nothing happens. If the optional \PName{member} is +omitted, the default value +``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is used. While +the class or package is being loaded, \Macro{@currname} and \Macro{@currext} +together represent the file name of the class or package. + +Theoretically, it is possible, to define a member without a name using an +empty optional \PName{member} argument. But this is the same as the family +itself. You should use only letters and digits for the \PName{family} name, +and the first character of \PName{member} should be something else, preferably +a point. Otherwise, it could happen that the members of one family will clash +with the members of other families. + +\Package{scrbase} assigns the family ``\PValue{KOMA}'' to itself and adds the +member ``\PValue{.scrbase.sty}''. The values ``\PValue{KOMA}'' and +``\PValue{KOMAarg}'' are reserved for \KOMAScript{}. If you are creating a +bundle of packages, you should use the name of the bundle as \PName{family} +and the name of each package as \PName{member} of that \PName{family}. +% +\begin{Example} + Suppose you are writing a bundle called ``master butcher''. Within that + bundle, you have the packages \File{salami.sty}, \File{mettwurst.sty}, + and \File{kielbasa.sty}. Therefore, you decide to use family name + ``\PValue{butcher}'' and you add the lines +\begin{lstcode} + \DefineFamily{butcher} + \DefineFamilyMember{butcher} +\end{lstcode} + to each of the package files. When loading the three packages, this will + add the members ``\PValue{.salami.sty}'', ``\PValue{.mettwurst.sty}'', + and ``\PValue{.kielbasa.sty}'' to the family ``\PValue{butcher}''. After + loading all three packages, all three members will be defined. +\end{Example} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DefineFamilyKey}\OParameter{member}\Parameter{family}% + \Parameter{key}% + \OParameter{default}\Parameter{action}% + \Macro{FamilyKeyState}% + \Macro{FamilyKeyStateUnknown}% + \Macro{FamilyKeyStateProcessed}% + \Macro{FamilyKeyStateUnknownValue}% + \Macro{FamilyKeyStateNeedValue} +\end{Declaration} +The \Macro{DefineFamilyKey} command defines a \PName{key}. If you specify a +\PName{member}, the \PName{key} becomes an attribute of that member in the +given \PName{family}. If you do not specify a \PName{member}, the member +``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is assumed. If you +later assign a value to the \PName{key}, the \PName{action} will be +executed and the value made an argument of \PName{action}. Within +\PName{action}, ``\lstinline{#1}'' stands for that value. If you omit the value, +the \PName{default} is used instead. If you do not specify a \PName{default}, +the \PName{key} then always requires you to pass an explicit value. + +%\begin{Explain} + \phantomsection\label{explain:scrbase.macro.DefineFamilyKey}% + Ultimately, +\begin{lstcode}[escapeinside=`'] + \DefineFamilyKey[`\PName{member}']{`\PName{family}'}{`\PName{key}'} + [`\PName{default}']{`\PName{action}'} +\end{lstcode} + results in a call to +\begin{lstcode}[moretexcs={define@key},escapeinside=`'] + \define@key{`\PName{family\,member}'}{`\PName{key}'} + [`\PName{default}']{`\PName{extended action}'} +\end{lstcode} + where \Macro{define@key} is provided by the + \Package{keyval}\IndexPackage{keyval} package (see \cite{package:keyval}). + However, there are some additional precautions taken with the call to + \Macro{define@key}, and the \PName{action} will be extended to include these + precautions. +%\end{Explain} + +Success\ChangedAt{v3.12}{\Package{scrbase}} or failure in executing the +\PName{action} should be reported back to \Package{scrbase} through +\Macro{FamilyKeyState} so that the package itself can take further action as +needed. This could be, for example, an error message or merely warning of an +unknown option. You should not report errors directly! + +The default state of \PName{action} before execution is +\Macro{FamilyKeyStateUnknown}. This indicates that it is not known whether or +not the key could be processed successfully. If this state remains unchanged +after the \PName{action} has been executed, \Package{scrbase} writes a +message to the \File{log} file and assumes the that state is +\Macro{FamilyKeyStateProcessed}. + +The \Macro{FamilyKeyStateProcessed} state indicates that the key and the value +assigned to it have been successfully processed and everything is OK. You can +switch to this state by calling \Macro{FamilyKeyStateProcessed} itself. + +The \Macro{FamilyKeyStateUnknownValue} state indicates that the key has been +processed but that the value passed to it was either unknown or not allowed. +For example, \hyperref[cha:typearea]{\Package{typearea}} reports this +condition if you try to set the \DescRef{typearea.option.twoside} option to +\PValue{unknown}. You can set this state by simply calling +\Macro{FamilyKeyStateUnknownValue}. + +The \Macro{FamilyKeyStateNeedValue} state indicates that the key could not be +processed because it expects a value, but it was called without such a value. +This state is set automatically if you use a key that does not have a +\PName{default} value without assigning a value. Theoretically, you could +set this state explicitly with \Macro{FamilyKeyStateNeedValue}, but you should +not need to set it yourself. + +In addition, you can define additional error conditions by redefining +\Macro{FamilyKeyState} with a short text message. Generally, however, the four +predefined states should be sufficient. + +\begin{Example} + Suppose each of the three packages from the previous example should have a + key named \PValue{coldcuts}. When used, a switch should be set in each of + the packages. For the \Package{salami} package, for example, this could look + like this: +\begin{lstcode} + \newif\if@salami@coldcuts + \DefineFamilyKey{butcher}% + {coldcuts}[true]{% + \expandafter\let\expandafter\if@salami@coldcuts + \csname if#1\endcsname + \FamilyKeyStateProcessed + } +\end{lstcode} + When called, the value will therefore be either \PValue{true} or + \PValue{false}. This example does not test for illegal values. Instead, + it is always reported that the key was processed completely and correctly. + If the key is used later, one of the permitted values, or no value, must be + used. In the second case, the default \PName{true} value will be used. + + The definitions for the other packages are similar. Only ``\texttt{salami}'' + has to be replaced by the respective names. +\end{Example} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{RelaxFamilyKey}\OParameter{member}\Parameter{family}% + \Parameter{key} +\end{Declaration} +If\ChangedAt{v3.15}{\Package{scrbase}} a \PName{key} has been previously +defined as a \PName{member} of a \PName{family}, that definition will be +cancelled. Afterwards the \PName{key} will no longer be defined for this +\PName{member} of the \PName{family}. You can use \Macro{RelaxFamilyKey} for a +\PName{key} that is not defined for this \PName{member} of the \PName{family}. + +If you do not specify a \PName{member}, then the member +``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is assumed, just as +with \DescRef{\LabelBase.cmd.DefineFamilyKey}. However, \Macro{RelaxFamilyKey} +is only rarely used while loading a package rather than at runtime. Therefore +the \PName{member} should usually be specified explicitly as well.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{FamilyProcessOptions}\OParameter{member}\Parameter{family} +\end{Declaration} +In essence, extending keys from families to both families and family members +means that either keys or key-value pairs can be used as normal class or +package options. The \Macro{FamilyProcessOptions} command is an extension of +\Macro{ProcessOption*} from the \LaTeX{} kernel (see \cite{latex:clsguide}, +which processes not only options declared with \Macro{DeclareOption}, but also +all keys of the given member. If you omit the optional argument +\PName{member}, the member +``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is used. + +One feature worth noting is that keys which are attached not to a family +member but to a family have an empty family member. Such keys are set before +the keys of the members. +\begin{Example} + If, in the packages from the previous example, you add the line +\begin{lstcode} + \FamilyProcessOptions{butcher} +\end{lstcode} + after you define the key, you can specify the \Option{coldcuts} option when + loading the package. If you specify the option globally in + \Macro{documentclass}, the option will be passed automatically to all three + packages if they are loaded later. +\end{Example} +Note\textnote{Attention!} that packages always process global options +before local options. While unknown global options result in an entry in the +\File{log} file and the option being otherwise ignored, unknown local +options result in an error message. + +You can think of \Macro{FamilyProcessOptions} as an extension of either +\Macro{ProcessOption*} or the \PName{key=value} mechanism +of \Package{keyval}. Ultimately, with the help of +\Macro{FamilyProcessOptions}, \PName{key=value} pairs become options.% + +As with\textnote{Attention!} \Macro{ProcessOptions}, +\Macro{FamilyProcessOptions} must not be used while executing options code. +In particular, you cannot load packages while processing options.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{BeforeFamilyProcessOptions}\OParameter{member}\Parameter{family}% + \Parameter{code}% +\end{Declaration} +Authors\ChangedAt{v3.18}{\Package{scrbase}} of wrapper classes in particular +sometimes need a hook to execute \PName{code} before +\DescRef{\LabelBase.cmd.FamilyProcessOptions}. The \Package{scrbase} package +provides such a hook, and you can add \PName{code} to it with +\Macro{BeforeFamilyProcessOptions}. The \PName{member} and \PName{family} +parameters are same as those of \DescRef{\LabelBase.cmd.FamilyProcessOptions}. +However, you can also add \PName{code} to the hook for families or members +that have not yet been defined. + +Note that the hook of a family member is automatically deleted after it is +executed. But if you use an empty \PName{member}, this hook\Index{hook} will +be executed for every member of the \PName{family} and will not be deleted. + +\begin{Example} + You are writing a \Package{smokedsausage} package that loads + \Package{mettwurst}. But you do not want to be able to set the + \Option{coldcut} option with this package. So you use + \Macro{BeforeFamilyProcessOptions} to deactivate that option before you load + the package: +\begin{lstcode} + \RequirePackage{scrbase} + \BeforeFamilyProcessOptions[.mettwurst.sty]{butcher}{% + \RelaxFamilyKey[.mettwurst.sty]{butcher}{coldcut}% + } + \RequirePackageWithOptions{mettwurst} +\end{lstcode} + If a user tries to load your package with the \Option{coldcut} option, the + \Package{mettwurst} package will throw an undefined option error. If + \Option{coldcut} is used as a global option, the \Package{mettwurst} + package will ignore it. But default settings inside \Package{mettwurst}, + for example using \DescRef{\LabelBase.cmd.FamilyExecuteOptions} before + \DescRef{\LabelBase.cmd.FamilyProcessOptions} are not affected. Of course, + you can also insert your own default for \Package{smokedsausage} via + \Macro{BeforeFamilyProcessOptions} in \Package{mettwurst}. +\end{Example} +\EndIndexGroup + + +\begin{Declaration} + \Macro{FamilyExecuteOptions}\OParameter{member}\Parameter{family}% + \Parameter{options list} +\end{Declaration} +This command is an extension of \Macro{ExecuteOptions} from the \LaTeX{} +kernel (see \cite{latex:clsguide}). The command processes not only options +defined with \Macro{DeclareOption} but also all keys of the given +\PName{family}. If you omit the optional argument \Macro{member}, +``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is used. + +One feature worth noting is that keys which are attached not to a family +member but to a family have an empty family member. Such keys are set before +the keys of the members. +\begin{Example} + Suppose the \Option{coldcuts} option should be set by default in the + previous examples. In this case only line +\begin{lstcode} + \FamilyExecuteOptions{butcher}{coldcuts} +\end{lstcode} + has to be added. +\end{Example} + +If\ChangedAt{v3.20}{\Package{scrbase}} you call \Macro{FamilyExecuteOptions} +with an unknown option inside the \PName{options list}, you will get an error. +An exception to this rule occurs when the \PName{member} has an option called +\Option{@else@}. In this case, the \Option{@else@} option will be used instead +of the unknown option. \KOMAScript{} itself uses this feature, for example +inside the definition of sectioning commands, to evaluate the style option +before all other attributes. + +You can also use this command inside the code executed when processing the +option.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{FamilyOptions}\Parameter{family}\Parameter{options list}% +\end{Declaration} +Unlike normal options defined with \Macro{DeclareOption}, the \PName{key}s can +also be set after loading a class or package. To do this, you call +\Macro{FamilyOptions}. The \PName{options list} has the form +\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + \PName{key}\texttt{=}\PName{value}\texttt{,}% + \PName{key}\texttt{=}\PName{value}\dots +\end{tabular}\vskip\dp\strutbox\end{flushleft} +after which the value assignment can be omitted for \PName{key}s that have a +defined default. + +The statement sets the keys of all members of the specified family. If a +\PName{key} also exists as an attribute of the family itself, then the family +key is set first, followed by the member keys in the order in which they were +defined. If a given \PName{key} does not exist, either for the family or for +any member of the family, then \Macro{FamilyOptions} will throw an error. An +error also occurs if a \PName{key} exists for some members but each of those +members returns an error through \DescRef{\LabelBase.cmd.FamilyKeyState}. +\begin{Example} + You extend your butcher project with a \Package{sausagesalad} package. If + this package has been loaded, all sausage packages should generate cold + cuts: +\begin{lstcode} + \ProvidesPackage{sausagesalad}% + [2008/05/06 nonsense package] + \DefineFamily{butcher} + \DefineFamilyMember{butcher} + \FamilyProcessOptions{butcher}\relax + \FamilyOptions{butcher}{coldcuts} +\end{lstcode} + If no sausage package has yet been loaded, the undefined option + \Option{coldcuts} leads to an error message. You can avoid this by defining + a corresponding key for the package before the last line of the code above: +\begin{lstcode} + \DefineFamilyKey{butcher}% + {coldcuts}[true]{}% +\end{lstcode} + However, sausage packages loaded after \Package{sausagesalad} still do not + produce cold cuts. You can correct this by replacing the previous command + with: +\begin{lstcode} + \AtBeginDocument{% + \DefineFamiyKey[.sausagesalad.sty]% + {butcher}% + {coldcuts}[true]{}% + } + \DefineFamilyKey{butcher}% + {coldcuts}[true]{% + \AtBeginDocument{\FamilyOptions{butcher}% + {coldcuts=#1}}% + }% +\end{lstcode} + Thus, the option is defined during \Macro{begin}\PParameter{document} so + that it no longer functions for the \Package{sausagesalad} package. Because + \Macro{@currname} and \Macro{@currext} no longer contain the file name of + the package, you must use the optional argument of + \DescRef{\LabelBase.cmd.DefineFamilyKey}. + + But until this redefinition is performed, it uses a definition that executes + the option again for the family and all its members during + \Macro{begin}\PParameter{document}, thus setting it for other sausage + packages. The delay in executing \Macro{FamilyOptions} is crucial here. For + one thing, it includes only the packages loaded afterwards. For another, it + ensures that its own \Option{coldcuts} option has already been redefined. + This avoids endless recursion. +\end{Example} +% +\EndIndexGroup +\vskip-\ht\strutbox% Umbruchkorrektur wegen Beispiel am Ende + + +\begin{Declaration} + \Macro{FamilyOption}\Parameter{family}% + \Parameter{option}\Parameter{value list}% +\end{Declaration} +In addition to options that have mutually exclusive values, there may be +options that can take multiple values at the same time. To use +\DescRef{\LabelBase.cmd.FamilyOptions} for that type of option, it would be +necessary to invoke the same option several times with different value +assignments. Instead, you can easily assign a whole list of values to a single +\PName{option} using \Macro{FamilyOption}. The \PName{value list} is a comma +separated list of values, also known as \emph{csv}: +%\begin{flushleft}\begin{tabular}{l} + \PName{value}\texttt{,}\PName{value}\dots +%\end{tabular}\end{flushleft} +Note in this context that you can use a comma in a value by putting the value +inside braces. This command's other functionality is the same previously +described for \DescRef{\LabelBase.cmd.FamilyOptions}. +\begin{Example} + The \Package{sausagesalad} package should have one more option to add + additional ingredients. Each of the ingredients sets a switch, as was done + previously for the cold cuts. +\begin{lstcode} + \newif\if@saladwith@onions + \newif\if@saladwith@gherkins + \newif\if@saladwith@chillies + \DefineFamilyKey{butcher}{ingredient}{% + \csname @saladwith@#1true\endcsname + } +\end{lstcode} + Here the three ingredients ``onions'', ``gherkins'', and ``chillies'' have + been defined. There is no error message for unknown ingredients. + + For a salad with onions and gherkins, you can use +\begin{lstcode} + \FamilyOptions{butcher}{% + ingredient=onions,ingredient=gherkins} +\end{lstcode} + or simply +\begin{lstcode} + \FamilyOption{butcher} + {ingredient}{onions,gherkins} +\end{lstcode} +\end{Example} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{AtEndOfFamilyOptions}\Parameter{action}% + \Macro{AtEndOfFamilyOptions*}\Parameter{action}% +\end{Declaration} +Sometimes\ChangedAt{v3.12}{\Package{scrbase}} it is useful to delay the +execution of an \PName{action} that is part of a value assignment to a key +until all assignments inside one +\DescRef{\LabelBase.cmd.FamilyProcessOptions}\IndexCmd{FamilyProcessOptions}, +\DescRef{\LabelBase.cmd.FamilyExecuteOptions}\IndexCmd{FamilyExecuteOptions}, +\DescRef{\LabelBase.cmd.FamilyOptions}\IndexCmd{FamilyOptions}, or +\DescRef{\LabelBase.cmd.FamilyOption}\IndexCmd{FamilyOptions} is finished. +You can do this using \Macro{AtEndOfFamilyOptions} or its starred +variant\ChangedAt{v3.23}{\Package{scrbase}} inside an option definition. +However, reporting failure states of \PName{action} is not possible with this +command, nor should it be used outside an option definition. + +The two variants differ in case there are nested option definitions, when +executing an option requires further option calls. In this case all actions +specified by \Macro{AtEndOfFamilyOptions} will be executed when the innermost +option call returns. In contrast, the actions of \Macro{AtEndOfFamilyOptions*} +are not executed until the outermost option call returns. +However,\textnote{Attention!} the order of the actions of both commands is +emphatically undefined! It is not guaranteed that the action requested first +will be executed first, nor the converse.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{FamilyBoolKey}\OParameter{member}\Parameter{family}% + \Parameter{key}\Parameter{switch name}% + \Macro{FamilySetBool}\Parameter{family}% + \Parameter{key}\Parameter{switch name}\Parameter{value} +\end{Declaration} +Boolean switches have been used several times in the previous examples. In the +example with \Option{coldcuts} option, the user had to assign either +\PValue{true} or \PValue{false} as a value. There was no error message if the +user provided the wrong value. Because boolean switches are a common use case, +you can easily define them with \Package{scrbase} using \Macro{FamilyBoolKey}. +The \PName{member}, \PName{family}, and \PName{key} arguments are the same as +those used by \DescRef{\LabelBase.cmd.DefineFamilyKey} (see +\DescPageRef{scrbase.cmd.DefineFamilyKey}). The \PName{switch name} is the +name of the switch without the prefix \Macro{if}. If a switch with this name +does not exist already, \Macro{FamilyBoolKey} will define it and initialize it +to \PName{false}. Internally, \Macro{FamilyBooKey} uses \Macro{FamilySetBool} +as the \PName{action} of \DescRef{\LabelBase.cmd.DefineFamilyKey}. The +\PName{default} for such an option is always \PValue{true}. + +\Macro{FamilySetBool}, on the other hand, accepts \PValue{on} and +\PValue{yes}, in addition to \PName{true}, to turn the switch on, and +\PName{off} and \PName{no}, in addition to \PName{false}, to turn it off. +Unknown values will result in a call to +\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} with the arguments +\PName{family}, \PName{key}, and \PName{value}, which sets +\DescRef{\LabelBase.cmd.FamilyKeyState} accordingly. As a result, an error +message about an unknown value assignment is printed if necessary (see also +\DescPageRef{scrbase.cmd.FamilyUnknownKeyValue} and +\DescPageRef{scrbase.cmd.FamilyKeyState}). +\begin{Example} + The key \Option{coldcuts} should be defined more robustly in the sausage + packages. Additionally, all sausage packages should use the same key, so + that either all sausage packages will produce cold cuts or none will. +\begin{lstcode} + \FamilyBoolKey{butcher}{coldcuts}% + {@coldcuts} +\end{lstcode} + A test of whether to produce cold cuts would look like this: +\begin{lstcode} + \if@coldcuts + ... + \else + ... + \fi +\end{lstcode} + This would be the same in all three sausage packages, thereby + defining the attribute ``coldcuts'' as a family option: +\begin{lstcode}[moretexcs={define@key}] + \@ifundefined{if@coldcuts}{% + \expandafter\newif\csname if@coldcuts\endcsname + }{}% + \DefineFamilyKey[]{butcher}{coldcuts}[true]{% + \FamilySetBool{butcher}{coldcuts}% + {@coldcuts}% + {#1}% + } +\end{lstcode} + or shorter: +\begin{lstcode} + \FamilyBoolKey[]{butcher}{coldcuts}% + {@coldcuts} +\end{lstcode} + taking advantage of the treatment of empty family members as opposed to + omitting the optional argument explained on + \autopageref{explain:scrbase.macro.DefineFamilyKey}, which applies not only + to \DescRef{\LabelBase.cmd.DefineFamilyKey} but also for + \Macro{FamilyBoolKey}. + + Since \DescRef{\LabelBase.cmd.FamilyKeyState} is already set by + \Macro{FamilySetBool}, you can check its status with the help of + \DescRef{\LabelBase.cmd.DefineFamilyKey}. For example, in the first case you + could add an equivalence test to \Macro{FamilySetBool} to perform additional + actions depending on whether \Macro{FamilySetBool} succeeded or not: + \begin{lstcode} + \ifx\FamilyKeyState\FamilyKeyStateProcessed + ... + \else + ... + \fi + \end{lstcode} + Note\textnote{Attention!} that it is essential to perform the test with + \Macro{ifx} at this point. Fully expanding tests like \Macro{ifstr} should + be avoided here. Depending on the current status and the comparison status, + they can lead to different error messages as well as incorrect results. +\end{Example} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{FamilyNumericalKey}\OParameter{member}\Parameter{family}% + \Parameter{key}% + \OParameter{default}\Parameter{command}% + \Parameter{value list}% + \Macro{FamilySetNumerical}\Parameter{family}\Parameter{key}% + \Parameter{command}\Parameter{value list}% + \Parameter{value} +\end{Declaration} +While switches can accept only two values, there are also keys that recognize +several values. For example an alignment can be not just left or not-left, but +left, centred, or right. Internally, such differentiation is often made using +\Macro{ifcase}. This \TeX{} command expects a numerical value. Therefore in +\Package{scrbase} the command to define a macro by a \PName{key} has been +named \Macro{FamilyNumericalKey}. The \PName{value list} has the form: +%\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + \Parameter{value}\Parameter{definition}\texttt{,}\linebreak[1]% + \Parameter{value}\Parameter{definition}\texttt{,}~\dots +%\end{tabular}\vskip\dp\strutbox\end{flushleft} +The \PName{value list} defines not just the values permitted for the +\PName{key}. For each \PName{value}, the \PName{definition} of the macro +\Macro{\PName{command}} also is given. Usually, the \PName{definition} is just +a numerical value. Although other content is possible, there is currently a +restriction that the \PName{definition} must be fully expandable, and it will +be expanded during the assignment. +\begin{Example} + The sausage for the sausage salad can be cut differently. For example, the + cold cuts could simply remain uncut or be cut into thick or thin slices. + This information should be stored in the command \Macro{cuthow}. +\begin{lstcode} + \FamilyNumericalKey{butcher}% + {saladcut}{cuthow}{% + {none}{none},{no}{none},{not}{none}% + {thick}{thick},% + {thin}{thin}% + } +\end{lstcode} + Not cutting anything can be selected by +\begin{lstcode} + \FamilyOptions{butcher}{saladcut=none} +\end{lstcode} + or +\begin{lstcode} + \FamilyOptions{butcher}{saladcut=no} +\end{lstcode} + or +\begin{lstcode} + \FamilyOptions{butcher}{saladcut=not} +\end{lstcode} + In all three cases \Macro{cuthow} would be defined with the content + \PValue{none}. It can be useful to provide several values for the same + result, as shown in this example. + + Now it's very likely that the manner of cutting will not be printed but + should be evaluated later. In this case, a textual definition would be + rather impractical. If the key is defined like this: +\begin{lstcode} + \FamilyNumericalKey{butcher}% + {saladcut}{cuthow}{% + {none}{0},{no}{0},{not}{0}% + {thick}{1},% + {thin}{2}% + } +\end{lstcode} + then you can use a condition like the following: +\begin{lstcode} + \ifcase\cuthow + % uncut + \or + % thickly cut + \else + % thinly cut + \fi +\end{lstcode} +\end{Example} +Internally, \Macro{FamilyNumericalKey} uses \Macro{FamilySetNumerical} as the +\PName{action} of \DescRef{\LabelBase.cmd.DefineFamilyKey}. If an unknown +value is assigned to such a key, \Macro{FamilySetNumerical} will call +\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} with the \PName{family}, +\PName{key} and \PName{value} arguments. This leads to an error signalled with +the \DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue} status in +\DescRef{\LabelBase.cmd.FamilyKeyState}. Similarly, when calling +\Macro{FamilySetNumerical} the success is signalled via +\DescRef{\LabelBase.cmd.FamilyKeyStateProcessed} in +\DescRef{\LabelBase.cmd.FamilyKeyState}.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{FamilyCounterKey}\OParameter{member}\Parameter{family}% + \Parameter{key}% + \OParameter{default}\Parameter{\LaTeX{} counter}% + \Macro{FamilySetCounter}\Parameter{family}% + \Parameter{key}\Parameter{\LaTeX{} counter}\Parameter{value} +\end{Declaration} +While\ChangedAt{v3.12}{\Package{scrbase}} +\DescRef{\LabelBase.cmd.FamilyNumericalKey} defines a macro in which a numeric +value corresponds to a symbolic value, there are, of course, circumstances +when a \PName{key} directly represents a \PName{\LaTeX{} counter} to which a +numeric value should be assigned immediately. For this case, you can use +\Macro{FamilyCounterKey}, which calls \Macro{FamilySetCounter} internally. +There are some basic tests of the \PName{value} argument to determine if the +\PName{value} argument appears to be suitable for assignment to a counter. The +assignment will only be made if these tests succeed. However, not all errors +can be detected here, so an incorrect assignment can also lead to an error +message from \TeX{} itself. Errors that are detected, however, are signalled +by \DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue}. + +If\ChangedAt{v3.15}{\Package{scrbase}} the value is omitted, the +\PName{default} is used instead. If there is no \PName{default}, the +\PName{key} can be used only with an explicit value.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{FamilyCounterMacroKey}\OParameter{member}\Parameter{family}% + \Parameter{key}% + \OParameter{default}\Parameter{macro}% + \Macro{FamilySetCounterMacro}\Parameter{family}% + \Parameter{key}\Parameter{macro}\Parameter{value}% +\end{Declaration} +These\ChangedAt{v3.12}{\Package{scrbase}} two commands differ from the +previously described \DescRef{\LabelBase.cmd.FamilyCounterKey} and +\DescRef{\LabelBase.cmd.FamilySetCounter} only by the fact that they do not +assign a \PName{value} to a \LaTeX{} counter, but define a \Macro{macro} with +the \PName{value}. This \PName{value} is locally assigned to a counter and +then its expanded value is used. Therefore, its value at the time the option +is called applies.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{FamilyLengthKey}\OParameter{member}\Parameter{family} + \Parameter{key} + \OParameter{default}\Parameter{length} + \Macro{FamilySetLength}\Parameter{family} + \Parameter{key}\Parameter{length}\Parameter{value} + \Macro{FamilyLengthMacroKey}\OParameter{member}\Parameter{family} + \Parameter{key} + \OParameter{default}\Parameter{macro} + \Macro{FamilySetLengthMacro}\Parameter{family} + \Parameter{key}\Parameter{macro} + \Parameter{value}% + \Macro{FamilyUseLengthMacroKey}\OParameter{member}\Parameter{family} + \Parameter{key} + \OParameter{default}\Parameter{macro} + \Macro{FamilySetUseLengthMacro}\Parameter{family} + \Parameter{key}\Parameter{macro} + \Parameter{value}% +\end{Declaration} +With\ChangedAt{v3.12}{\Package{scrbase}} \Macro{FamilyLengthKey}, you can +define a \PName{key} that represents a \PName{length}. It does not matter +whether the \PName{length} is a \LaTeX{} length, a \TeX{} skip, or a \TeX{} +dimension. Internally the \PName{length} will be set to the \PName{value} +using \Macro{FamilySetLength}. There are some basic tests to decide whether +this \PName{value} is valid to assign to \PName{length}. The assignment will +only take place if these tests succeed. However, not all errors can be +detected, so an inaccurate \PName{value} can still result in a \TeX{} error. +Errors that are detected, however, are signalled by +\DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue}. + +If\ChangedAt{v3.15}{\Package{scrbase}} the value is omitted, the +\PName{default} is used instead. If there is no \PName{default}, the +\PName{key} can be used only with an explicit value. + +When you use \Macro{FamilyLengthMacroKey} and \Macro{FamilySetLengthMacroKey}, +or \Macro{FamilySetLengthMacro} and \Macro{FamilySetUseLengthMacro}, the +\PName{value} is stored not in a \PName{length} but in a +\PName{macro}. \Macro{FamilyLengthMacroKey} and +\Macro{FamilySetLengthMacroKey} define the \PName{macro} to be the +\PName{value} as evaluated at the point of definition, similar to +\Macro{setlength}. In contrast, +\Macro{FamilyUseLengthMacroKey}\ChangedAt{v3.20}{\Package{scrbase}} and +\Macro{FamilySetUseLengthMacroKey} store the \PName{value} directly, and +so the \PName{value} is reevaluated each time the \PName{macro} is used.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{FamilyStringKey}\OParameter{member}\Parameter{family}% + \Parameter{key}% + \OParameter{default}\Parameter{command} + \Macro{FamilyCSKey}\OParameter{member}\Parameter{family}% + \Parameter{key}% + \OParameter{default}\Parameter{command name} +\end{Declaration} +This defines\ChangedAt{v3.08}{\Package{scrbase}} a \PName{key} that accepts +any value. The value will be stored in the specified \Macro{command}. If there +is no optional argument for the \PName{default}, \Macro{FamilyStringKey} is +the same as: +\begin{lstcode}[escapeinside=`'] + \DefineFamilyKey[`\PName{member}']{`\PName{family}'}{`\PName{key}'} + {\def`\PName{command}'{#1}} +\end{lstcode} +If you use the optional argument \PName{default}, \Macro{FamilyStringKey} +corresponds to: +\begin{lstcode}[escapeinside=`'] + \DefineFamilyKey[`\PName{member}']{`\PName{family}'}{`\PName{key}'} + [`\PName{default}'] + {\def`\PName{command}'{#1}\FamilyKeyStateProcessed} +\end{lstcode} + +\begin{Example} + By default 250\Unit{g} of sausage salad should be produced. However, the + amount should be configurable by an option. To do so, the quantity to be + created is stored in the macro \Macro{saladweight}. The option to change + the weight should also be called \PValue{saladweight}: +\begin{lstcode} + \newcommand*{\saladweight}{250g} + \FamilyStringKey{butcher}% + {saladweight}[250g]{\saladweight} +\end{lstcode} + To switch back to the default weight after changing it, you can simply + call the option without the weight: +\begin{lstcode} + \FamilyOptions{butcher}{saladweight} +\end{lstcode} + This is possible because the default quantity was also set as the default + value in the definition. +\end{Example} +In this case, there are no unknown values because all values are simply used +for a macro definition. Note, however, that paragraph breaks are not allowed +when assigning a value to the key. + +In contrast\ChangedAt{v3.25}{\Package{scrbase}} to \Macro{FamilyStringKey}, +the \Macro{FamilyCSKey} command expects for the final argument not a macro but +only the name of a command, for example \PParameter{saladweight} instead of +\PParameter{\Macro{saladweight}}.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{FamilyUnknownKeyValue}\Parameter{family}\Parameter{key}% + \Parameter{value}\Parameter{value list}% +\end{Declaration} +The command \Macro{FamilyUnknownKeyValue} throws an error message due to an +unknown or illegal values by means of \DescRef{\LabelBase.cmd.FamilyKeyState}. +The \PName{value list} is a comma separated list of permissible values in the +form +%\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + `\PName{value}'\texttt{,} `\PName{value}' \dots +%\end{tabular}\vskip\dp\strutbox\end{flushleft} +However\ChangedAt{v3.12}{\Package{scrbase}}, the \PName{value list} is +currently not evaluated by \Package{scrbase}. +\begin{Example} + The user should now also be able to select whether the cold cuts should be + cut thick or thin. Thick should be the default setting, which should be used + even if the user does not specify how to cut the coldcuts. +\begin{lstcode} + \@ifundefined{if@thincut}{% + \expandafter + \newif\csname if@thincut\endcsname}{}% + \@ifundefined{if@coldcuts}{% + \expandafter + \newif\csname if@coldcuts\endcsname}{} + \DefineFamilyKey{butcher}% + {coldcuts}[true]{% + \FamilySetBool{butcher}{coldcuts}% + {@coldcuts}% + {#1}% + \ifx\FamilyKeyState\FamilyKeyStateProcessed + \@thincutfalse + \else + \ifstr{#1}{thin}{% + \@coltcutstrue + \@finecuttrue + \FamilyKeyStateProcessed + }{% + \FamilyUnknownKeyValue{butcher}% + {coldcuts}% + {#1}{% + `true', `on', `yes', + `false`, `off`, `no', + `thin'% + }% + }% + \fi + }% +\end{lstcode} + First we try to set the boolean coldcuts switch using + \DescRef{\LabelBase.cmd.FamilySetBool}. If this succeeds, i.\,e. if + \DescRef{\LabelBase.cmd.FamilyKeyState} corresponds to + \DescRef{\LabelBase.cmd.FamilyKeyStateProcessed}, thincut will be + deactivated. Otherwise, we check if the value is equal to \PValue{thin} + rather than one of the valid values for a boolean switch. In this case, both + coldcuts and thincut are activated and the state will be switched to + \DescRef{\LabelBase.cmd.FamilyKeyStateProcessed}. If the previous test + fails, the error state signalled by \DescRef{\LabelBase.cmd.FamilySetBool} + is reset to \DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue}. The list of + the permissible values will be added to it. However, since this list is no + longer used, it would have been easy to skip the call to + \Macro{FamilyUnknownKeyValue} in the example and thus assume the error + status of \DescRef{\LabelBase.cmd.FamilySetBool}. + + The \Macro{ifstr} command used in the test is explained on + \DescPageRef{scrbase.cmd.ifstr} in \autoref{sec:scrbase.if}. +\end{Example} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{FamilyElseValues} +\end{Declaration} +In\ChangedAt{v3.12}{\Package{scrbase}} previous\textnote{Obsolete!} versions +of \Package{scrbase}, you could use the \Macro{FamilyElseValues} command to +define additional values for processing by +\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} in the form +%\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + \texttt{,} `\PName{value}'\texttt{,} `\PName{value}' \dots, + %\end{tabular}\vskip\dp\strutbox\end{flushleft} +which were then output in an error message. Since version~3.12, +\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} no longer issues error messages +itself but signals them using \DescRef{\LabelBase.cmd.FamilyKeyState}. +Therefore, \Macro{FamilyElseValues} is now deprecated. Nevertheless, +\Package{scrbase} detects its use and issues a message requesting that you +update the code accordingly.% +\EndIndexGroup + + +\section{Conditional Execution} +\seclabel{if} + +The \Package{scrbase} package provides several commands for conditional +execution. It does not rely on the \TeX{} syntax of conditionals such as +\begin{lstcode} + \iftrue + ... + \else + ... + \fi +\end{lstcode} +but uses the \LaTeX{} syntax with arguments similar to those used by \LaTeX{} +commands like \Macro{IfFileExists}, \Macro{@ifundefined}, +\Macro{@ifpackageloaded}, and many others. Some package authors, however, +prefer to use the syntax of \TeX{} conditionals even for users working at the +\LaTeX{} interface level. Since the \Package{scrbase} conditionals are fairly +low-level instructions, it is possible that such packages could provide +commands with the same names but a different syntax, leading to problems even +if the underlying semantics were actually the same. Therefore, +\Package{scrbase} plays it safe. + +\begin{Declaration} + \OptionVName{internalonly}{value} +\end{Declaration} +The \Package{scrbase} package provides some commands for conditional +execution. It primarily uses names like +\Macro{scr@\PName{name}}\textnote{package authors}, which are internal +commands. \KOMAScript{} also uses these commands internally. Authors of +packages and classes can also use these commands but should not redefine them. +Because some of these commands may also be useful for users, they are provided +as \Macro{\PName{name}}\textnote{users} normally. Since other packages may +provide conflicting commands with the same name but different syntax or +functionality, \Package{scrbase} can suppress the definition of +\Macro{\PName{name}}. Using the \Option{internalonly} option without a +\PName{value} will define only the internal commands and suppress definition +of all the user commands for conditional execution. Alternatively, the user +can list all the commands that should not be defined as the \PName{value}, +replacing ``\Macro{}'' with ``\texttt{/}''. + +Authors of packages and classes normally should not use this option. Users can +specify it with or without the \PName{value} either as a global option with +\DescRef{maincls.cmd.documentclass} or using +\Macro{PassOptionsToPackage}\IndexCmd{PassOptionsToPackage}. +\begin{Example} + The user does not want \Package{scrbase} to define the + \DescRef{\LabelBase.cmd.ifVTeX} and + \DescRef{\LabelBase.cmd.ifundefinedorrelax} commands. So to load the class, + the user writes: +\begin{lstcode} + \documentclass% + [internalonly=/ifVTeX/ifundefinedorrelax]% + {foo} +\end{lstcode} + The class name \Class{foo} is used here as a placeholder for any class. The + commands \DescRef{\LabelBase.cmd.ifVTeX} and + \DescRef{\LabelBase.cmd.ifundefinedorrelax} are explained later in this + section. +\end{Example} + +Authors of packages and classes should use the same internal names as +\KOMAScript{} itself. For completeness, the user commands are also given in +the following explanations.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{scr@ifundefinedorrelax}% + \Parameter{name}\Parameter{then code}\Parameter{else code}% + \Macro{ifundefinedorrelax}% + \Parameter{name}\Parameter{then code}\Parameter{else code} +\end{Declaration} +This command works like \Macro{@ifundefined} from the \LaTeX{} kernel (see +\cite{latex:source2e}). So the \PName{then code} will be executed if +\PName{name} is the name of a command that is currently either not defined or +\Macro{relax}. Otherwise, the \PName{else code} will be executed. Unlike +\Macro{@ifundefined}, no hash memory is allocated nor is \Macro{\PName{Name}} +set to \Macro{relax} if \Macro{\PName{name}} was previously undefined.% +\EndIndexGroup + +\begin{Declaration} + \Macro{ifnotundefined}\Parameter{name}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If the command with the given name has already been defined, the \PName{then +code} will be executed. Otherwise, the \PName{else code} will be executed. +Since \eTeX{} already has a primitive \Macro{ifdefined}, this somewhat +unwieldy name, unfortunately, had to be chosen. There is no corresponding +internal command.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{scr@ifluatex} + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If\ChangedAt{v3.21}{\Package{scrbase}} you use lua\TeX{}, the \PName{then +code} will be executed. Otherwise, the \PName{else code} will be executed. +\iftrue% Umbruchkorrekturtext +This test is rarely useful. % +\fi% +As a rule, it is better to test directly for the command you want. +There\textnote{Attention!} is no user equivalent for this instruction. Use the +\Package{ifluatex}\important{\Package{ifluatex}} package instead (see +\cite{package:ifluatex}).% +\EndIndexGroup + + +\iffalse% It makes no sense to document this instruction yet +\begin{Declaration} + \Macro{scr@ifpdforluatex} + \Parameter{then code}\Parameter{else code} +\end{Declaration} +Until lua\TeX~0.85, it was mostly irrelevant whether you used pdf\TeX{} or +lua\TeX{}. This command, which executes the \PName{then code} in both cases, +derives from that fact. If neither pdf\TeX{} nor lua\TeX{} is used, the +\PName{else code} will be executed. Since version~0.85, lua\TeX{} has given up +compatibility with many of its commands. Therefore this distinction is no +longer useful in practice and is no longer used by \KOMAScript{} itself. There +is no user equivalent of this statement.% +\EndIndexGroup +\fi + +\begin{Declaration} + \Macro{scr@ifpdftex}% + \Parameter{then code}\Parameter{else code}% + \Macro{ifpdftex}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If you use pdf\TeX{}, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. It does not matter whether a PDF-file is +actually generated or not. This test is rarely useful. As a rule, you should +test directly for the command you want instead.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{scr@ifVTeX}% + \Parameter{then code}\Parameter{else code}% + \Macro{ifVTeX}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If you use V\TeX{}, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. This test is seldom useful. As a rule, +you should test directly for the command you want instead.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{scr@ifpdfoutput}% + \Parameter{then code}\Parameter{else code}% + \Macro{ifpdfoutput}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If a PDF file is generated, the \PName{then code} will be executed. Otherwise, +the \PName{else code} will be executed. It does not matter whether PDF file is +created using lua\TeX{}, pdf\TeX{}, or V\TeX{}, or \XeTeX{}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{scr@ifpsoutput}% + \Parameter{then code}\Parameter{else code}% + \Macro{ifpsoutput}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If a PostScript file is generated, the \PName{then code} will be executed. +Otherwise, the \PName{else code} will be executed. V\TeX{} can generate +PostScript directly, which is recognized here. However, if V\TeX{} is not used +but the switch \Macro{if@dvips} has been defined, the decision depends on that +switch. \KOMAScript{} provides \Macro{if@dvips} in +\hyperref[cha:typearea]{\Package{typearea}}\IndexPackage{typearea}% +\IndexCmd{if@dvips}. +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{scr@ifdvioutput}% + \Parameter{then code}\Parameter{else code}% + \Macro{ifdvioutput}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If a DVI-file is generated, the \PName{then code} will be executed. Otherwise, +the \PName{else code} will be executed. A DVI file is always assumed to be +generated if no direct output of a PDF file or a PostScript file can be +detected.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{if@atdocument}\ \PName{then code}\ % + \textMacro{else}\ \PName{else code}\ \textMacro{fi} +\end{Declaration} +This conditional command intentionally exists only as an internal command. In +the document preamble, \Macro{if@atdocument} corresponds to \Macro{iffalse}. +After \Macro{begin}\PParameter{document}, it corresponds to \Macro{iftrue}. +Authors of classes and packages may find this command useful if a command +should behave differently depending on whether it is used in the preamble or +inside document body. Note\textnote{Attention!} that this command is a +condition using \TeX{} syntax and not \LaTeX{} syntax! +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifstr}\Parameter{string 1}\Parameter{string 2}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +Both \PName{string} arguments are expanded and then compared. If the +expansions are the same, the \PName{then code} will be executed. Otherwise the +\PName{else code} will be executed. There is no corresponding internal +command. +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifstrstart}\Parameter{string 1}\Parameter{string 2}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +Both\ChangedAt{v3.12}{\Package{scrbase}} \PName{string} arguments are expanded +and then compared. If \PName{string 1}, apart from white space, begins with +\PName{string 2}, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. There is no corresponding internal +command.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifisdimen}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to a +\Macro{dimen}, i.\,e. a \TeX{} length register, the \PName{then code} will be +executed. Otherwise the \PName{else code} will be executed. The command is not +completely expandable, and there is no corresponding internal command.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifisdimension}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to something +syntactically equivalent to a length, the \PName{then code} will be executed. +Otherwise the \PName{else code} will be executed. Note\textnote{Attention!} +that unknown units will cause an error message. The command is not completely +expandable, and there is no corresponding internal command.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifdimen}\Parameter{string}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +The \PName{then code} will be executed if the first-order expansion of +\PName{string} consists of digits and a valid length unit. Otherwise, the +\PName{else code} will be used. There is no corresponding internal command.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifisdimexpr}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to an \eTeX{} +\Macro{dimexpr}\IndexCmd{dimexpr}, the \PName{then code} will be executed. +Otherwise, the \PName{else code} will be executed. Note\textnote{Attention!} +that illegal expressions will result in error messages. The command is not +completely expandable, and there is no corresponding internal command.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifisskip}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to a +\Macro{skip}, i.\,e. a \TeX{} distance, the \PName{then code} will be +executed. Otherwise, the \PName{else code} will be executed. The command is not +completely expandable, and there is no corresponding internal command.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifisglue}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to something +syntactically equivalent of the value of a skip, the \PName{then code} will be +executed. Otherwise, the \PName{else code} will be executed. +Note\textnote{Attention!} that invalid units will result in an error message. +The command is not completely expandable, and there is no corresponding +internal command.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifisglueexpr}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to a +\Macro{glueexpr}, i.\,e. an \eTeX{} distance expression, the \PName{then +code} will be executed. Otherwise, the \PName{else code} will be executed. +Note,\textnote{Attention!} that illegal expressions will result in error +messages. The command is not completely expandable, and there is no +corresponding internal command.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifiscounter}\Parameter{counter}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{counter} is defined as a +\LaTeX{} counter, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. The command is not completely expandable, +and there is no corresponding internal command.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifiscount}\Parameter{count}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{count} expands to a +\Macro{count}, i.\,e. a \TeX{} counter, the \PName{then code} will be +executed. Otherwise, the \PName{else code} will be executed. The command is +not completely expandable, and there is no corresponding internal command. For +tests of \LaTeX{} counters, see \DescRef{\LabelBase.cmd.ifiscounter}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifisinteger}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to something +syntactically equivalent to of the value of a counter, i.\,e. a negative or +positive integer, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. The command is not completely expandable, +and there is no corresponding internal command.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifnumber}\Parameter{string}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +The \PName{then code} will be executed if the first-order expansion of +\PName{string} consists only of digits. Otherwise, the \PName{else code} will +be used. There is no corresponding internal command. +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifisnumexpr}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to a +\Macro{numexpr}, i.\,e. an \eTeX{} number expression, the \PName{then code} +will be executed. Otherwise, the \PName{else code} will be executed. +Note\textnote{Attention!} that illegal expressions will result in error +messages. The command is not completely expandable, and there is no +corresponding internal command.% +\EndIndexGroup + + +\section{Defining Language-Dependent Terms} +\seclabel{languageSupport} +\BeginIndexGroup +\BeginIndex{}{language>definition} +\index{language>dependent terms|see{language definition}} +\index{terms>language-dependent|see{language definition}} + +Beginners often find it difficult to change language-dependent terms +\Macro{listfigurename}\IndexCmd{listfigurename}, by default usually ``List of +Figures.'' For example, if these are simply redefined with +\Macro{renewcommand} in the document preamble, they will not survive a later +change of language. If you use \Package{babel}\IndexCmd{babel}, the +redefinition in the preamble is overwritten with +\Macro{begin}\PParameter{document}. + +To define or change language-dependent terms, you normally have to redefine +commands like \Macro{captionsenglish} so that the new or redefined terms are +defined in addition to the previous terms. This is made more difficult by the +fact that some packages like \Package{german}\IndexPackage{german} or +\Package{ngerman}\IndexPackage{ngerman} redefine those settings when they are +loaded. These definitions, unfortunately, occur in a way that undoes all the +previous changes. For this reason, it makes sense to delay changes until +\Macro{begin}\PParameter{document} by using \Macro{AtBeginDocument}, that is, +after all packages have been loaded. A user can also use +\Macro{AtBeginDocument} or redefine the language-dependent terms not in the +preamble but after \Macro{begin}\PParameter{document}. + +Adding further to the difficulty, some packages define additional +language-dependent terms in \Macro{captions\PName{language}}, while others use +\Macro{extras\PName{language}}. So the user must understand the commands very +well in order to use the correct one in the right way. + +The \Package{scrbase} package therefore provides additional commands to define +or modify language-dependent terms, relieving the user of many of these +problems. These commands also let you simultaneously define or change the +language-dependent terms of several dialects or forms of a language. + +\begin{Declaration} + \Macro{defcaptionname}% + \Parameter{language list}\Parameter{term}\Parameter{definition}% + \Macro{providecaptionname}% + \Parameter{language list}\Parameter{term}\Parameter{definition}% + \Macro{newcaptionname}% + \Parameter{language list}\Parameter{term}\Parameter{definition}% + \Macro{renewcaptionname}% + \Parameter{language list}\Parameter{term}\Parameter{definition}% + \Macro{defcaptionname*}% + \Parameter{language list}\Parameter{term}\Parameter{definition}% + \Macro{providecaptionname*}% + \Parameter{language list}\Parameter{term}\Parameter{definition}% + \Macro{newcaptionname*}% + \Parameter{language list}\Parameter{term}\Parameter{definition}% + \Macro{renewcaptionname*}% + \Parameter{language list}\Parameter{term}\Parameter{definition} +\end{Declaration} +With these four commands and their starred variants, you can assign a +\PName{definition} for a particular language to a \PName{term}. Several +languages can be concatenated with comma in the \PName{language list}. + +The \PName{term} is always a macro. The commands differ depending on whether a +given language or a \PName{term} within a given language is already defined at +the time the command is called. + +If a language is not defined, \Macro{providecaptionname} does nothing other +than write a message to the log file. This happens only once for each +language. If a language is defined but does not yet contain a corresponding +\PName{term}, it will be defined using \PName{definition}. However, the +\PName{term} will not be redefined if the language already has such a +definition; instead, an appropriate message is written to the log file. + +On the other hand, if a language has not yet been defined, +\Macro{newcaptionname} defines a new language command will be created. For the +language \PValue{USenglish}, for example, this would be the language command +\Macro{captionsUSenglish}. This definition will also be noted in the log file. +If \PName{term} is not yet defined in this language, it will be defined using +\PName{definition}. If the \PName{term} already exists in a language, an error +message is issued. + +The \Macro{renewcaptionname} command behaves still differently. If a language +is undefined, an error message is issued. If the \PName{term} is not defined +in this language, an error message is also issued. If the \PName{term} is +defined in the language, it will be redefined to \PName{definition}. + +The\ChangedAt{v3.12}{\Package{scrbase}} \Macro{defcaptionname} command always +defines the \PName{term}, thus overwriting any previous definition. As with +\Macro{providecaptionname}, the language specified need not be previously +defined. + +\KOMAScript{} itself uses \Macro{providecaptionname} to define the commands in +\autoref{sec:scrlttr2-experts.languages}. +\DescPageRef{scrlttr2-experts.cmd.yourrefname}. + +\begin{Example} + If you prefer ``fig.'' instead of ``figure'' in \PValue{USenglish}, you can + achieve this using: +\begin{lstcode} + \renewcaptionname{USenglish}{\figurename}{fig.} +\end{lstcode} + If you want the same change not only in \PValue{USenglish} but also in + \PValue{UKenglish}, you do not need an additional: +\begin{lstcode} + \renewcaptionname{UKenglish}{\figurename}{fig.} +\end{lstcode} + but can simply extend the \PName{language list}: +\begin{lstcode} + \renewcaptionname{USenglish,UKenglish}{\figurename}{fig.} +\end{lstcode} + You can extend the \PName{language list} in the same manner with + \PValue{american}, \PValue{australian}, \PValue{british}, \PValue{canadian}, + and \PValue{newzealand}. +\end{Example} + +Since \KOMAScript~3.12\ChangedAt{v3.12}{\Package{scrbase}}, you no longer need +to delay the definition or redefinition until +\Macro{begin}\PParameter{document} using \Macro{AtBeginDocument} because +\Package{scrbase} does this itself if the commands are called in the +document's preamble. Additionally, \Package{scrbase} now checks if a term +should be redefined in \Macro{extras\PName{language}} instead of +\Macro{captions\PName{language}}. The new starred variants of the commands +always use \Macro{extras\PName{language}}. So redefining language-dependent +terms for packages like \Package{hyperref} that use +\Macro{extras\PName{language}} should work as expected. + +Language-dependent terms that are commonly defined by classes and language +packages are described in \autoref{tab:scrbase.commonNames}. + +\begin{desclist} + \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% + \desccaption[{% + Overview of common language-dependent terms% + }]{% + Overview of language-dependent terms of typical language packages% + \label{tab:scrbase.commonNames}% + }{% + Overview of common language dependent terms + (\emph{continued})% + }% + \entry{\Macro{abstractname}}{% + heading of the abstract% + \IndexCmd{abstractname}% + }% + \entry{\Macro{alsoname}}{% + ``see also'' in additional cross references of the index% + \IndexCmd{alsoname}% + }% + \entry{\Macro{appendixname}}{% + ``appendix'' in the heading of an appendix chapter% + \IndexCmd{appendixname}% + }% + \entry{\Macro{bibname}}{% + heading of the bibliography% + \IndexCmd{bibname}% + }% + \entry{\Macro{ccname}}{% + prefix heading for the distribution list of a letter% + \IndexCmd{ccname}% + }% + \entry{\Macro{chaptername}}{% + ``chapter'' in the heading of a chapter% + \IndexCmd{chaptername}% + }% + \entry{\Macro{contentsname}}{% + heading of the table of contents% + \IndexCmd{contentsname}% + }% + \entry{\Macro{enclname}}{% + prefix heading for the enclosures of a letter% + \IndexCmd{enclname}% + }% + \entry{\Macro{figurename}}{% + prefix heading of figure captions% + \IndexCmd{figurename}% + }% + \entry{\Macro{glossaryname}}{% + heading of the glossary% + \IndexCmd{glossaryname}% + }% + \entry{\Macro{headtoname}}{% + ``to'' in header of letter pages% + \IndexCmd{headtoname}% + }% + \entry{\Macro{indexname}}{% + heading of the index% + \IndexCmd{indexname}% + }% + \entry{\Macro{listfigurename}}{% + heading of the list of figures% + \IndexCmd{listfigurename}% + }% + \entry{\Macro{listtablename}}{% + heading of the list of tables% + \IndexCmd{listtablename}% + }% + \entry{\Macro{pagename}}{% + ``page'' in the pagination of letters% + \IndexCmd{pagename}% + }% + \entry{\Macro{partname}}{% + ``part'' in the heading of a part% + \IndexCmd{partname}% + }% + \entry{\Macro{prefacename}}{% + heading of the preface% + \IndexCmd{prefacename}% + }% + \entry{\Macro{proofname}}{% + prefix heading of mathematical proofs% + \IndexCmd{proofname}% + }% + \entry{\Macro{refname}}{% + heading of the list of references% + \IndexCmd{refname}% + }% + \entry{\Macro{seename}}{% + ``see'' in cross references of the index% + \IndexCmd{seename}% + }% + \entry{\Macro{tablename}}{% + prefix heading at table captions% + \IndexCmd{tablename}% + }% +\end{desclist} +% +\EndIndexGroup +% +\EndIndexGroup + + +\section{Identifying \KOMAScript} +\seclabel{identify} + +Although\,---\,or especially because\,---\,\Package{scrbase} is generally +designed as a package for authors of classes and packages, it is of course +used by the \KOMAScript{} classes and most \KOMAScript{} packages. It +therefore contains two commands that are present in all \KOMAScript{} classes +and all basic \KOMAScript{} packages. + +\begin{Declaration} + \Macro{KOMAScript} +\end{Declaration} +This command simply sets the word ``\KOMAScript'' in sans-serif font and with +a slight tracking for the capitals. By the way, all \KOMAScript{} classes and +packages define this command as required. The definition is robust using +\Macro{DeclareRobustCommand}. Since packages that do not belong to +\KOMAScript{} can also define this command, its existence should not be +interpreted as an indication that a \KOMAScript{} package is in use.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{KOMAScriptVersion} +\end{Declaration} +\KOMAScript{} defines the major version of \KOMAScript{} in this command. It +has the form ``\PName{date} \PName{version} \texttt{KOMA-Script}''. This major +version is same for all \KOMAScript{} classes and all \KOMAScript{} packages +used by the classes. For this reason, it can be queried after you +load \Package{scrbase}, too. For example, this guide was made using +\KOMAScript{} version ``\KOMAScriptVersion''. +% +\EndIndexGroup + + +\section{Extensions to the \LaTeX{} Kernel} +\seclabel{latexkernel} + +Sometimes the \LaTeX{} kernel itself provides commands but lacks other very +similar commands that would often be useful. A few such commands are provided +by \Package{scrbase} for authors of packages and classes. + +\begin{Declaration} + \Macro{ClassInfoNoLine}\Parameter{class name}\Parameter{information}% + \Macro{PackageInfoNoLine}\Parameter{package name}\Parameter{information}% +\end{Declaration}% +The \LaTeX{} kernel already provides authors of classes and packages commands +like \Macro{ClassInfo} and \Macro{PackageInfo} to write information, along +with the current line number, to the log file. In addition to +\Macro{PackageWarning} and \Macro{ClassWarning}, which throw warning messages +with line numbers, it also provides \Macro{PackageWarningNoLine} and +\Macro{ClassWarningNoLine} for warning messages without line numbers. However +the obvious commands \Macro{ClassInfoNoLine} and \Macro{PackageInfoNoLine}, +for writing information without line numbers into the log file, are missing. +The \Package{scrbase} package provides them. +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{l@addto@macro}\Parameter{command}\Parameter{extension}% +\end{Declaration}% +The \LaTeX{} kernel provides an internal command \Macro{g@addto@macro} to +extend the definition of macro \Macro{command} globally with +\PName{extension}. This works in this form only for macros that have no +arguments. However, sometimes you may need a command like this that works +locally within the current group. The \Package{scrbase} package provides such +a command with \Macro{l@addto@macro}. An alternative is to use the +\Package{etoolbox}\IndexPackage{etoolbox} or +\Package{xpatch}\IndexPackage{xpatch} package, which offers a whole range of +such commands for different purposes (see \cite{package:etoolbox} or +\cite{package:xpatch}).% +\EndIndexGroup + + +\section{Extensions to the Mathematical Features of \eTeX} +\seclabel{etex} + +\eTeX{}, which is used by \LaTeX{} and loaded by \KOMAScript{}, has extended +capabilities for calculating simple arithmetic with \TeX{} counters and +integers using \Macro{numexpr}\IndexCmd{numexpr}. The four basic arithmetic +operations and parentheses are supported. Division is rounded +correctly. Sometimes additional operators would be useful. + +\begin{Declaration} + \Macro{XdivY}\Parameter{dividend}\Parameter{divisor}% + \Macro{XmodY}\Parameter{dividend}\Parameter{divisor}% +\end{Declaration}% +The command\ChangedAt{v3.05a}{\Package{scrbase}} +\Macro{XdivY} returns the value of the integer quotient, with command +\Macro{XmodY} giving the value of the remainder. This type of of division is +defined by the equation +\[ +\textit{dividend} = \textit{divisor} \cdot +\textit{integer quotient} + \textit{remainder} +\] +where \textit{dividend}, \textit{divisor}, and \textit{remainder} are +integers, \textit{remainder} is greater or equal to 0 and less than +\textit{divisor}, and \textit{divisor} is a natural number greater than 0. + +You can assign the value to a counter or use it directly within an expression +using \Macro{numexpr}. To output the value as an Arabic number, you must +prefix it with \Macro{the}.% +% +\EndIndexGroup +% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% ispell-local-dictionary: "en_GB" +%%% coding: us-ascii +%%% TeX-master: "../guide.tex" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrbookreportarticle-experts.tex b/macros/latex/contrib/koma-script/source-doc/english/scrbookreportarticle-experts.tex new file mode 100644 index 0000000000..1629f29923 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrbookreportarticle-experts.tex @@ -0,0 +1,1786 @@ +% ====================================================================== +% scrbookreportarticle-experts.tex +% Copyright (c) Markus Kohm, 2001-2019 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrbookreportarticle-experts.tex +% Copyright (c) Markus Kohm, 2001-2019 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrbook, scrreprt, and scrartcl of the KOMA-Script guide +% expert part +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber scrbook, scrreprt und scrartcl im Experten-Teil der +% KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrbookreportarticle-experts.tex} + [$Date: 2019-01-15 08:29:44 +0100 (Tue, 15 Jan 2019) $ + KOMA-Script guide (chapter: scrbook, scrreprt, scrartcl for + experts)] + +\translator{Gernot Hassenpflug\and Markus Kohm\and Karl Hagen} + +% Date of the translated German file: 2018-10-14 + +\chapter[{Additional Information about the Main Classes and + \Package{scrextend}}]{Additional Information about the Main Classes + \Class{scrbook}, + \Class{scrreprt}, and \Class{scrartcl} as well as the Package + \Package{scrextend}} +\labelbase{maincls-experts} +\BeginIndexGroup +\BeginIndex{Class}{scrartcl}% +\BeginIndex{Class}{scrbook}% +\BeginIndex{Class}{scrreprt}% +\BeginIndex{Package}{scrextend}% +This chapter provides additional information about the \KOMAScript{} classes +\Class{scrbook}, \Class{scrreprt}, and \Class{scrartcl} and some commands that +are also available in \Package{scrextend}. \iffree{Some parts of the chapter + are found only in the German \KOMAScript{} book \cite{book:komascript}. This + should not be a problem because the}{The} average user, who only wants to +use the classes, will seldom need this information. Some of this information +is addressed to users with non-standard requirements or who want to write +their own classes based on a \KOMAScript{} class. Other parts describe +features that exist only for the sake of compatibility with the standard +classes or earlier versions of \KOMAScript{}. Portions that describe features +that exist only for reasons of compatibility with earlier versions of +\KOMAScript{} are printed in sans serif font. You should not use them any +longer. + +\LoadNonFree{scrbookreportarticle-experts}{0} + +\section{Extensions to User Commands} +\seclabel{addInfos} + +\LoadNonFree{scrbookreportarticle-experts}{1} + + +\section{\KOMAScript's Interaction with Other Packages} +\seclabel{coexistence} + +\LoadNonFree{scrbookreportarticle-experts}{2} + + +\section{Expert Commands} +\seclabel{experts} + +This sections describes commands that are of little or no interest to the +average user. These commands offer additional features for experts. Because +the information is addressed to experts, it is condensed. + +% \subsection{Identification} +% \seclabel{identification} + +\begin{Declaration} + \Macro{KOMAClassName}% + \Macro{ClassName} +\end{Declaration} +\Macro{KOMAClassName} stores the name of the \KOMAScript{} class currently in +use. So if you want to know if a \KOMAScript{} class is used, you can easily +test for this command. In contrast, \Macro{ClassName} indicates which standard +class has been replaced by this \KOMAScript{} class. + +Note\textnote{Attention!} in this context, however, that the existence of +\DescRef{scrbase.cmd.KOMAScript}\IndexCmd{KOMAScript} cannot guarantee that a +\KOMAScript{} class is in use. For one thing, all \KOMAScript{} packages +define this command. For another, other packages may find it useful to define +the \KOMAScript{} label using this name.% +% +\EndIndexGroup + +% \subsection{Entries to the Table of Contents} +% \seclabel{toc} + +\begin{Declaration} + \Macro{addtocentrydefault}\Parameter{level}\Parameter{number}% + \Parameter{heading} +\end{Declaration} +The\ChangedAt{v3.08}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} \KOMAScript{} classes do not use +\Macro{addcontentsline}\IndexCmd{addcontentsline}% +\important{\Macro{addcontentsline}} directly to make entries in the table of +contents. Instead, they call \Macro{addtocentrydefault} with similar +arguments. The command can be used for both numbered and unnumbered entries. +The \PName{level} is the sectioning level, that is \PValue{part}, +\PValue{chapter}, \PValue{section}, \PValue{subsection}, +\PValue{subsubsection}, \PValue{paragraph}, or \PValue{subparagraph}. The +formatted sectioning number is given the second argument, \PName{number}. This +argument can be empty. The text of the entry is given by the \PName{heading} +argument. You should protect fragile commands inside this argument with +\Macro{protect}\IndexCmd{protect}\important{\Macro{protect}}. + +One notable feature of the \PName{number} argument is that an empty argument +indicates that an unnumbered entry should be generated. By default, +\KOMAScript{} uses +\begin{quote} + \Macro{addcontentsline}\PParameter{toc}\Parameter{level}% + \Parameter{heading} +\end{quote} +for this. If the argument is not empty, however, an entry with number +will be created and \PName{number} is the formatted heading +number. \KOMAScript{} uses +\begin{quote}\raggedright + \Macro{addcontentsline}\PParameter{toc}\Parameter{level}% + \PParameter{\%\\ + \quad\Macro{protect}\DescRef{tocbasic.cmd.numberline}\Parameter{number}% + \PName{heading}\%\\ + } +\end{quote} +to create this entry. + +Package authors and authors of wrapper classes can redefine this command to +alter the entries. For example\textnote{Example}, you could use +\begin{lstcode} + \renewcommand{\addtocentrydefault}[3]{% + \ifstr{#3}{}{% + \ifstr{#2}{}{% + \addcontentsline{toc}{#1}{#3}% + }{% + \addcontentsline{toc}{#1}{\protect\numberline{#2}#3}% + }% + }% + }% +\end{lstcode} +to\IndexCmd{ifstr} omit entries with an empty \PName{heading}. In practice, +such a change is not necessary because the \KOMAScript{} classes already use +another method to suppress empty entries. See the description of the +sectioning commands in \autoref{sec:maincls.structure}, starting on +\DescPageRef{maincls.cmd.part} for this.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{addparttocentry}\Parameter{number}\Parameter{heading} + \Macro{addchaptertocentry}\Parameter{number}\Parameter{heading} + \Macro{addsectiontocentry}\Parameter{number}\Parameter{heading} + \Macro{addsubsectiontocentry}\Parameter{number}\Parameter{heading} + \Macro{addsubsubsectiontocentry}\Parameter{number}\Parameter{heading} + \Macro{addparagraphtocentry}\Parameter{number}\Parameter{heading} + \Macro{addsubparagraphtocentry}\Parameter{number}\Parameter{heading} +\end{Declaration}% +The\ChangedAt{v3.08}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} \KOMAScript{} classes call the previously described +command +\DescRef{\LabelBase.cmd.addtocentrydefault}\IndexCmd{addtocentrydefault}% +\important{\DescRef{\LabelBase.cmd.addtocentrydefault}} directly only if no +individual command for the \PName{level} has been defined or if that command +is \Macro{relax}\IndexCmd{relax}\important{\Macro{relax}}. By default, all +these commands simply pass their own \PName{level} and arguments directly to +\DescRef{\LabelBase.cmd.addtocentrydefault}.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{raggedchapterentry} +\end{Declaration} +In\ChangedAt{v3.21}{\Class{scrbook}\and \Class{scrreprt}} earlier versions of +\KOMAScript{}, it was possible to define the \Macro{raggedchapterentry} macro +as \Macro{raggedright} to print chapter entries in the table of contents +left-aligned instead of fully justified. Officially, this feature has not +existed in \KOMAScript{} since version~3.21. + +In fact, the \PValue{raggedentrytext} attribute for the \PValue{tocline} +TOC-entry style of the \Package{tocbasic}\IndexPackage{tocbasic} package is +implemented by setting the \Macro{ragged\PName{entry level}entry} macro to +either \Macro{relax} or \Macro{raggedright}. This attribute is evaluated by +checking whether the corresponding macro is defined as \Macro{raggedright}. If +so, the text is printed left-aligned. With any other definition, no ragged +margins are used. + +Since it was previously documented that \Macro{raggedchapterentry} should not +be defined as anything other than \Macro{raggedright}, this behaviour is +compatible with the documented behaviour of earlier versions. As noted in +earlier releases, other definitions of \Macro{raggedchapterentry}\,---\,and +now also of \Macro{raggedsectionentry} and similar macros for other entry +levels\,---\,may lead to unexpected results. + +You should select the desired justification for the all table-of-contents +entries using the \PValue{raggedentrytext} attribute of \PValue{tocline} +rather than attempting to set the attribute for specific entry levels.% +\EndIndexGroup + + +% \subsection{Font Settings} +% \seclabel{fonts} + + +\begin{Declaration} + \Macro{@fontsizefilebase}% + \Macro{changefontsizes}\Parameter{font size} +\end{Declaration} +The \File{scrsize} prefix for file names of font-size files described +in \autoref{sec:maincls-experts.addInfos}\iffree{}{ on +\DescPageRef{maincls-experts.option.fontsize}} is just the default for the +internal \Macro{@fontsizefilebase}\IndexCmd{@fontsizefilebase} macro. This +default is used only when the macro is not yet defined when loading a +\KOMAScript{} class or the \Package{scrextend} package. Authors of wrapper +classes can redefine this macro to use completely different font-size files. +Similarly\textnote{Hint!} authors of wrapper classes can change or deactivate +the fallback solution for unknown font sizes by redefining the +\Macro{changefontsizes}\important{\Macro{changefontsizes}} macro. This macro +has exactly one argument: the desired \PName{font size}. +However\textnote{Attention!}, the \Macro{changefontsizes} macro is not +designed as an end-user instruction.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{newkomafont}\OParameter{warning}\Parameter{element}% + \Parameter{default}% + \Macro{aliaskomafont}\Parameter{alias}\Parameter{element} +\end{Declaration} +Experts can use \Macro{newkomafont} to define a \PName{default} for the font +style of an \PName{element}. Subsequently, that default can be changed with +the \DescRef{maincls.cmd.setkomafont} and \DescRef{maincls.cmd.addtokomafont} +commands (see \autoref{sec:maincls.textmarkup}, +\DescPageRef{maincls.cmd.setkomafont}). Of course, merely defining the font +style does not actually put it to use. You must make sure you include the +\DescRef{maincls.cmd.usekomafont}% +\important{\DescRef{maincls.cmd.usekomafont}}\IndexCmd{usekomafont} command +(see \DescPageRef{maincls.cmd.usekomafont}) for this \PName{element} in your +code at the appropriate places. Calling \Macro{newkomafont} for an existing +element will result in error messages. + +The optional \PName{warning} argument defines a warning message. The +\KOMAScript{} classes output it with \Macro{ClassWarning}, and the +\Package{scrextend} package with \Macro{PackageWarning}, whenever the default +font style of that \PName{element} is changed. The package \Package{scrkbase} +is listed as the generator of the warning. + +The \Macro{aliaskomafont} command defines an \PName{alias} for a previously +defined \PName{element}. \KOMAScript{} informs the user in the \File{log} file +about the actual name of the element if it uses an \PName{alias}. +You\textnote{Hint!} can use an \PName{alias}, for example, if you think of a +better name for an element and the old name should remain usable for the sake +of compatibility. It can also increase user-friendliness by creating aliases +for all the terms that different users may intuitively choose. \KOMAScript{} +itself makes use of this possibility.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{addtokomafontrelaxlist}\Parameter{macro} + \Macro{addtokomafontonearglist}\Parameter{macro} + \Macro{addtokomafontgobblelist}\Parameter{macro} +\end{Declaration} +As already mentioned in \autoref{part:forAuthors} of this manual, font +settings of elements should consist only of commands to select the size, +family, encoding, series, shape, or colour. Colour changes are not +always transparent in \LaTeX{} and therefore can cause in unwanted side-effects +if you use \DescRef{maincls.cmd.usekomafont} at an inappropriate place. + +Users tend to put very different, sometimes critical, things into the font +setting of an element, such as \Macro{MakeUppercase} at the very end of the +setting. As much as possible, the internal use of the font settings has been +implemented so that many of these prohibited elements still do no harm, and it +usually works even if the last command in a font setting expects an argument, +for example using \Macro{textbf} instead of \Macro{bfseries}. But there is no +guarantee for that. + +Internally, \KOMAScript{} must sometimes limit font changes to real font +settings. This is accomplished, for example, by using +\DescRef{maincls.cmd.usefontofkomafont}% +\IndexCmd{usefontofkomafont}% +\IndexCmd{usesizeofkomafont}\IndexCmd{useencodingofkomafont}% +\IndexCmd{usefamilyofkomafont}\IndexCmd{useseriesofkomafont}% +\IndexCmd{useshapeofkomafont} instead of \DescRef{maincls.cmd.usekomafont} +(see \autoref{sec:maincls.textmarkup}, +\DescPageRef{maincls.cmd.usefontofkomafont}). + +Nevertheless, the \DescRef{maincls.cmd.usefontofkomafont} command and its +siblings have their limitations. Therefore you must not use a command that +always needs a fully expandable argument inside the font setting of an +element. But this is exactly what \Macro{MakeUppercase} needs. +Therefore\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and +\Class{scrartcl}} \KOMAScript{} maintains an internal list of macros that +should become \Macro{relax} inside \DescRef{maincls.cmd.usefontofkomafont} and +its siblings. Since \KOMAScript~3.24\ChangedAt{v3.24}{\Class{scrbook}\and +\Class{scrreprt}\and \Class{scrartcl}} only \Macro{normalcolor} is added to +this list by default. + +Note that the given \PName{macro} is actually just set to \Macro{relax}. So +any arguments within the font setting will be executed locally, if applicable. +Therefore you should never add commands like \Macro{setlength} to the list. +You are responsible for all errors resulting caused by using +\Macro{addtokomafontrelaxlist}. Also, do not take this command as license to +add all sorts of commands to the font settings! + +For\ChangedAt{v3.24}{\Class{scrbook}\and \Class{scrreprt}\and +\Class{scrartcl}} commands whose first argument should be executed without an +additional group, there is \Macro{addtokomatfontonearglist}. The specified +macro is set to \Macro{@firstofone}. By default \Macro{MakeUppercase} and +\Macro{MakeLowercase} are added to this list. + +If\ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}\and +\Class{scrartcl}}, on the other hand, a \PName{macro} and its first argument +should be ignored locally inside \DescRef{maincls.cmd.usefontofkomafont} and +its siblings, you can use \Macro{addtokomafontgobblelist} instead of +\Macro{addtokomafontrelaxlist}. An example of this is the command +\Macro{color}, which must be ignored along with the colour name and therefore +is a member of this list by default. + +Note the defaults of these three lists may change in future version. If you +need a certain commands in one of the lists, you should should explicitly add +them yourself.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{IfExistskomafont}\Parameter{element}\Parameter{then code}% + \Parameter{else code} + \Macro{IfIsAliaskomafont}\Parameter{element}\Parameter{then code}% + \Parameter{else code} +\end{Declaration} +Which\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}\and \Class{scrlttr2}} elements are defined depends on the +version of \KOMAScript. So it sometimes makes sense to test in advance whether +a specific \PName{element} even exists. The \Macro{IfExistskomafont} command +executes the \PName{then code} if and only if an \PName{element} has been +defined using \DescRef{\LabelBase.cmd.newkomafont} or +\DescRef{\LabelBase.cmd.aliaskomafont} and therefore can also be changed using +\DescRef{maincls.cmd.setkomafont} or \DescRef{maincls.cmd.addtokomafont} and +can be used by one of the \Macro{use\dots komafont} commands. Otherwise it +executes the \PName{else code}.% + +In contrast, \Macro{IfIsAliaskomafont}\ChangedAt{v3.25}{\Class{scrbook}\and +\Class{scrreprt}\and \Class{scrartcl}\and \Class{scrlttr2}} executes +\PName{then code} only if \PName{element} has been defined with +\DescRef{\LabelBase.cmd.aliaskomafont} as an alias of another element. For +undefined elements as well as for elements defined with +\DescRef{\LabelBase.cmd.newkomafont}, however, it executes the +\PName{else code}.% +\EndIndexGroup + +% \subsubsection{Paragraph Indention or Gap} +% \seclabel{parskip} + +\begin{Declaration} + \Macro{setparsizes}\Parameter{indent}\Parameter{distance} + \Parameter{last-line end space} +\end{Declaration} +\KOMAScript{} provides the option to set the indent of the first line of a new +paragraph, the distance between paragraphs, and the white space required at the +end of the last line of each paragraph. You should use this command whenever +the \OptionValueRef{maincls}{parskip}{relative} option should recognize these +changes. \KOMAScript{}\textnote{example} itself uses this command, for +example, in the form +\begin{lstcode} + \setparsizes{0pt}{0pt}{0pt plus 1fil} +\end{lstcode} +to eliminate both the paragraph indentation and inter-paragraph spacing, as +well as to allow any amount of white space at the end of the last line of the +paragraph. Such values are useful if a paragraph consists of only a box that +should be printed without vertical spacing and filling the whole column +width. If, on the other hand, the box should only span the whole width but use +the current settings for indentation and distance between paragraphs, then +\begin{lstcode} + \setlength{\parfillskip}{0pt plus 1fil} +\end{lstcode} +is preferable. + +Starting with \KOMAScript~3.17\ChangedAt{v3.17}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}, recalculating or +reactivating\IndexCmd{activateareas} the type area or the margins (see +\autoref{cha:typearea}) also readjusts the values of \Macro{setparsizes} if +they have not been changed in the meantime. This is one more reason not to +change these values without using \KOMAScript. Setting compatibility to a +\KOMAScript{} version prior to 3.17 (see +\autoref{sec:maincls.compatibilityOptions}, +\DescPageRef{maincls.option.version}, option \DescRef{maincls.option.version}% +\IndexOption{version}\important{\OptionValueRef{maincls}{version}{3.17}}) +disables this recalculation.% +% +\EndIndexGroup + +% \subsection{Counters} +% \seclabel{counter} + +\LoadNonFree{scrbookreportarticle-experts}{3} + +% \subsubsection{Sections} +% \seclabel{sections} + +\begin{Declaration} + \Macro{DeclareSectionCommand}\OParameter{attributes}\Parameter{name}% + \Macro{DeclareNewSectionCommand}\OParameter{attributes}\Parameter{name}% + \Macro{RedeclareSectionCommand}\OParameter{attributes}\Parameter{name}% + \Macro{ProvideSectionCommand}\OParameter{attributes}\Parameter{name} +\end{Declaration} +With\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} these commands you can either define a new sectioning +command, \Macro{\PName{name}}, or modify an existing sectioning command, +\Macro{\PName{name}}. To do so, you use the optional argument to set several +\PName{attributes}. The \PName{attributes} are a comma-separated list of +\PName{key}=\PName{value} assignments. In addition to the style-independent +attributes shown in \autoref{tab:maincls-experts.declaresection.keys}, +\autopageref{tab:maincls-experts.declaresection.keys}, there are also +attributes that depend on the style. Currently the following styles are +available: +\begin{description}\setkomafont{descriptionlabel}{} +\item[\PValue{chapter}:] \ChangedAt{v3.18}{\Class{scrbook}\and + \Class{scrreprt}}The style for chapter headings. This style is used by + default for \DescRef{maincls.cmd.chapter}\IndexCmd{chapter} and indirectly + for \DescRef{maincls.cmd.addchap}\IndexCmd{addchap}. You can define new + sectioning commands using this style, but then they do not automatically + have an \Macro{add\dots} variant. To configure existing or new sectioning + commands, you can also use the attributes of + \autoref{tab:maincls-experts.declarechapterstyle.keys}, + \autopageref{tab:maincls-experts.declarechapterstyle.keys}. + The\textnote{Attention!} \DescRef{maincls.cmd.addchap} command, + like the starred variants, is configured automatically with + \DescRef{maincls.cmd.chapter} and cannot be modified independently. Note + that \Class{scrartcl}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} does not + provide this style. +\item[\PValue{part}:] \ChangedAt{v3.18}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}The style for part headings. This + style is used by default for \DescRef{maincls.cmd.part}\IndexCmd{part} and + indirectly for \DescRef{maincls.cmd.addpart}\IndexCmd{addpart}. You can + define new sectioning commands using this style, but then they do not + automatically have an \Macro{add\dots} variant. To configure existing or new + sectioning commands, you can also use the attributes of + \autoref{tab:maincls-experts.declarepartstyle.keys}, + \autopageref{tab:maincls-experts.declarepartstyle.keys}. + Note\textnote{Attention!} that the \DescRef{maincls.cmd.addpart} command, + like the starred variants, is configured automatically with + \DescRef{maincls.cmd.part} and cannot be modified independently. +\item[\PValue{section}:] The style for section headings. This style is currently + used for \DescRef{maincls.cmd.section}\IndexCmd{section}, + \DescRef{maincls.cmd.subsection}\IndexCmd{subsection}, + \DescRef{maincls.cmd.subsubsection}\IndexCmd{subsubsection}, + \DescRef{maincls.cmd.paragraph}\IndexCmd{paragraph}, and + \DescRef{maincls.cmd.subparagraph}\IndexCmd{subparagraph}. You can define + new sectioning commands using this style. To configure existing or new + sectioning commands, you can also use the attributes of + \autoref{tab:maincls-experts.declaresectionstyle.keys}, + \autopageref{tab:maincls-experts.declaresectionstyle.keys}. When redefining + a command, the \ChangedAt{v3.24}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} \PName{key}s + \PValue{style}, \PValue{afterskip}, \PValue{beforeskip}, and \PValue{level} + are mandatory. The keys + \PValue{afterindent}\ChangedAt{v3.26}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}},\PValue{font} and \PValue{indent} + are recommended. \PValue{tocindent} and + \PValue{tocnumwidth} may also be required depending on the command's + \PName{name}. This also applies if a command that was not previously a + sectioning command is redefined as a sectioning command using + \Macro{RedeclareSectionCommand}. Note\textnote{Attention!} that the + \Macro{addsec} command and its starred variants are configured automatically + with \DescRef{maincls.cmd.section} and cannot be changed independently. +\end{description} +Defining a sectioning command also creates an element with the same +\PName{name}, if it does not already exist. For \PValue{chapter} and +\PValue{part}, elements are also created for the prefix line. You can change +its font settings using \DescRef{maincls.cmd.setkomafont} or +\DescRef{maincls.cmd.addtokomafont} (see \autoref{sec:maincls.textmarkup}, +\DescPageRef{maincls.cmd.setkomafont}). + +\begin{table} + \caption[{Style-independent attributes for declaring sectioning + commands}]{Available \PName{key}s and \PName{value}s for + style-independent \PName{attributes} when declaring sectioning command}% + \label{tab:maincls-experts.declaresection.keys}% + \begin{tabularx}{\linewidth}{llX} + \toprule + \PName{key} & \PName{value} & Description \\ + \midrule% + \PValue{counterwithin} + & \PName{counter name} + & The value of the counter of the heading should depend on \PName{counter + name}. Whenever \Macro{stepcounter} or \Macro{refstepcounter} increases + the value of \PName{counter name}, the value of the counter of this + heading is reset to 0. In addition, \Macro{the\PName{counter name}} is + prefixed with a dot when this counter is output.\\ + \ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + \PValue{counterwithout} + & \PName{counter name} + & Cancels a prior \PValue{counterwithin} setting. Therefore it makes sense + only if you redefine an existing sectioning command.\\ + \PValue{expandtopt} + & \PName{switch} + & If the switch is on, all subsequent values for lengths will be + completely expanded, evaluated, and stored as \texttt{pt} values when + they are defined. This means lengths no longer depend on the current + font size. If the switch is off, all subsequent values for lengths will + be tentatively expanded and evaluated but stored for full evaluation at + application time. You can use any values from + \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. + The default is \PValue{false}.\\ + \PValue{level} + & \PName{integer} + & The numerical value of the sectioning level (see the + \DescRef{maincls.counter.secnumdepth} counter, + \autoref{sec:maincls.structure}, + \DescPageRef{maincls.counter.secnumdepth}); the value should be unique + and is mandatory for new levels.\\ + \PValue{style} + & \PName{name} + & Defines the style of the heading.\\ + \ChangedAt{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + \PValue{tocstyle} + & \PName{name} + & Defines the style of the entries in the table of contents. You can use + every previously defined TOC-entry style (see + \autoref{sec:tocbasic.tocstyle}). An empty \PName{name} prevents a new + definition of the TOC-entry command \Macro{l@\dots}.\\ + \ChangedAt{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + \PValue{toc\PName{option}} + & \PName{value} + & Additional options depending on the TOC-entry style selected with + \Option{tocstyle}. See \autoref{sec:tocbasic.tocstyle}, + \autopageref{sec:tocbasic.tocstyle} for additional information about + TOC-entry styles. You can find the attributes that can be used as + \PName{option}s for the predefined TOC-entry styles of the + \Package{tocbasic} package in + \autoref{tab:tocbasic.tocstyle.attributes}, + \autopageref{tab:tocbasic.tocstyle.attributes}.\\ + % \PValue{tocindent} + % & \PName{length} + % & Total indentation from the left margin of the entry in the table of + % contents corresponding to this heading, if and only if such an + % entry will be made (see \DescRef{maincls.counter.tocdepth}, + % \autoref{sec:maincls.toc}, \DescPageRef{maincls.counter.tocdepth}).\\ + % \PValue{toclevel} + % & \PName{integer} + % & A number denoting the depth of the entry in the table of contents + % corresponding to this heading, if this should differ from + % \PValue{level} (see \DescRef{maincls.counter.tocdepth}, + % \autoref{sec:maincls.toc}, \DescPageRef{maincls.counter.tocdepth}). \\ + % \PValue{tocnumwidth} + % & \PName{length} + % & Width of the box for the number of the entry in the table of + % contents.\\ + \bottomrule + \end{tabularx} +\end{table} + +\begin{table} + \caption[{Attributes of the \PValue{section} style when declaring a + sectioning command}]{Additional \PName{key}s and \PName{value}s for + attributes when declaring a sectioning command with the \PValue{section} + style}% + \label{tab:maincls-experts.declaresectionstyle.keys}% + \begin{tabularx}{\linewidth}{llX} + \toprule + \PName{key} & \PName{value} & Description \\ + \midrule + \PValue{afterindent}% + \ChangedAt{v3.26}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + & \PName{switch} + & The \PName{switch} determines whether the current paragraph indent is + applied to the first line following a freestanding heading (see + \PValue{runin}). With the default, \PValue{bysign}, the sign of + \PValue{beforeskip} determines the behaviour. If the value of + \PValue{beforeskip} is negative, the indentation of the first paragraph + following the heading is suppressed. You can use any value from + \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} to + explicitly enable or disable this indentation.\\ + \PValue{afterskip} + & \PName{length} + & In the case of a run-in heading (see \PValue{runin}), the absolute value + of the \PName{length} is the horizontal space after the heading. That is, + a positive distance is always inserted. In the case of a freestanding + heading, the \PName{length} is the vertical skip below the heading. With + \OptionValue{runin}{bysign}, a positive value results in a freestanding + heading, while a negative value or zero results in a run-in heading.\\ + \PValue{beforeskip} + & \PName{length} + & Specifies the vertical space before the heading. With + \OptionValue{afterindent}{bysign}, if the value is negative, a positive + distance\,---\,the amount of \PName{length}\,---\,is still inserted, but + in this case the indentation of the paragraph following the heading is + suppressed.\\ + \PValue{font} + & \PName{font commands} + & The font settings that should be used for the heading in addition to + \DescRef{maincls.fontelement.disposition}. You can use all settings that + are allowed for \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for the element of the heading.\\ + \PValue{indent} + & \PName{length} + & The indentation of heading from the left margin.\\ + \PValue{runin} + \ChangedAt{v3.26}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + & \PName{switch} + & Defines whether to use a run-in or a freestanding heading. With + the default, \PValue{bysign}, the sign of \PValue{afterskip} determines + the behaviour. In this case, a positive value of \PValue{afterskip} + results in a freestanding heading. You can use any values from + \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} to + explicitly enable or disable a run-in heading.\\ + \bottomrule + \end{tabularx} +\end{table} + +\begin{table} + \caption[{Attributes of the \PValue{chapter} style when declaring a + sectioning command}]{Additional \PName{keys} and \PName{value}s for + attributes when declaring a sectioning command with the \PValue{chapter} + style}% + \label{tab:maincls-experts.declarechapterstyle.keys}% + \begin{tabularx}{\linewidth}{llX} + \toprule + \PName{key} & \PName{value} & Description \\ + \midrule + \PValue{afterindent}% + \ChangedAt{v3.26}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + & \PName{switch} + & The \PName{switch} determines whether to apply the indentation of the + first paragraph following a heading. With the default, \PValue{bysign}, + the sign of \PValue{beforeskip} defines the behaviour. If the value of + \PValue{beforeskip} is negative, the indentation of the paragraph + following the heading is suppressed. You can use any value from + \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} to + explicitly enable or disable this indentation.\\ + \PValue{afterskip}% + \ChangedAt{v3.26}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + & \PName{length} + & The vertical skip below the heading.\\ + \PValue{beforeskip} + & \PName{length} + & The vertical skip before the heading. With + \OptionValue{afterindent}{bysign}, if the value is negative, a positive + distance\,---\,the amount of \PName{length}\,---\,is still inserted, but + in this case the indentation of the first paragraph following the heading + is suppressed.\\ + \PValue{font} & \PName{font commands} & The font setting to use for the + heading in addition to \DescRef{maincls.fontelement.disposition}. You + can use all settings, that are allowed for + \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for this element.\\ + \PValue{innerskip} & \PName{length} & The vertical skip between the prefix + line and the heading's text, if a prefix line is used.\\ + \PValue{pagestyle} & \PName{page style name} & The name of the page style + to use automatically for pages with the heading. There is no check to + see if the \PName{page style name} is valid. Therefore, incorrect names + will result in error messages when the sectioning command is used.\\ + \PValue{prefixfont} & \PName{font commands} & The font setting to use + for the prefix line of the heading, in addition to the + \DescRef{maincls.fontelement.disposition} and sectioning command + elements. You can use all settings that are allowed for + \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for the element of the prefix + line.\\ + \bottomrule + \end{tabularx} +\end{table} + +\begin{table} + \caption[{Attributes of the \PValue{part} style when declaring a sectioning + command}]{Additional \PName{keys} and \PName{value}s for attributes + when declaring a sectioning command with the \PValue{part} style}% + \label{tab:maincls-experts.declarepartstyle.keys}% + \begin{tabularx}{\linewidth}{llX} + \toprule + \PName{key} & \PName{value} & Description \\ + \midrule + \PValue{afterindent}% + \ChangedAt{v3.26}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + & \PName{switch} + & The \PName{switch} determines whether to apply the indentation of the + first paragraph following a heading. With the value \PValue{bysign}, + the sign of \PValue{beforeskip} determines the behaviour. If the value + of \PValue{beforeskip} is negative, the indentation of the first + paragraph following the heading is suppressed. You can use any value + from \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} to + explicitly enable or disable this indentation. For compatibility, + the default is \PValue{false} for \Class{scrartcl} and \PValue{true} for + \Class{scrbook} and \Class{scrreprt}.\\ + \PValue{afterskip} & \PName{length} & The value is the vertical skip below + the heading.\\ + \PValue{beforeskip} + & \PName{length} + & The vertical skip before the heading. With + \OptionValue{afterindent}{bysign}, if the value is negative, a positive + distance\,---\,the amount of \PName{length}\,---\,is still inserted, but + in this case the indentation of the first paragraph following the heading + is suppressed.\\ + \PValue{font} & \PName{font commands} & The font setting to use for the + heading in addition to \DescRef{maincls.fontelement.disposition}. You + can use all settings that are allowed for + \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for the element of the heading.\\ + \PValue{innerskip} & \PName{length} & % \OnlyAt{\Class{scrbook}\and + % \Class{scrreprt}}% + The vertical skip between the prefix line and the heading text in + \Class{scrbook} and \Class{scrreprt}.\\ + \PValue{pagestyle} & \PName{page style name} & + % \OnlyAt{\Class{scrbook}\and + % \Class{scrreprt}}% + The name of the page style to use automatically on pages with the + heading. There is no check to see if \PName{page style name} is valid. + Therefore, incorrect names will result in error messages when the + sectioning command is used. This feature only exists in \Class{scrbook} + and\Class{scrreprt}.\\ + \PValue{prefixfont} & \PName{font commands} & The font setting to use for + the prefix line of the heading, in addition to the + \DescRef{maincls.fontelement.disposition} and sectioning command + elements. You can use all settings that are allowed for + \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for the element of the prefix + line.\\ + \bottomrule + \end{tabularx} +\end{table} + +\Macro{DeclareNewSectionCommand} defines a new sectioning command. If the +same \PName{name} is already used by \TeX{} for something else, the command +will result in an error message and will not define anything. + +\Macro{ProvideSectionSommand} behaves similarly but does not issue an error +message. + +\Macro{RedeclareSectionCommand}, on the other hand, can only change an +existing command to a sectioning command with the specified +\PName{attributes}. It does not check whether \Macro{\PName{name}} is already +a sectioning command. It only needs to be a \PName{name} already a \TeX +command. + +\Macro{DeclareSectionCommand} does not check whether or not \PName{name} is +an existing \TeX{} command name. It just defines a sectioning +command \Macro{\PName{name}} with the specified \PName{attributes}. + +Each sectioning command also has a corresponding counter with the same +\PName{name} that is allocated with \Macro{newcounter} if necessary. The same +naming rule applies to the corresponding output of the counter +(\Macro{the\PName{name}}), the counter's format (\Macro{\PName{name}format}), +the command to generate a running head (\Macro{\PName{name}mark}), the format +of the counter in the running head (\Macro{\PName{name}markformat}), the font +element (\FontElement{\PName{name}}), and the section-depth number +(\Macro{\PName{name}numdepth}). The command for the running head, +\Macro{\PName{name}mark}, is defined by default not to generate a running +head. The default output of the counter \Macro{the\PName{name}} is an Arabic +number. If the counter is defined as depending on another counter with the +\PValue{counterwithin} \PName{key}, the output of this counter will be +prefixed by a dot. + +In\ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} addition to the sectioning command itself, a command for +corresponding entries to the table of contents is also defined. This is done +using the \hyperref[cha:tocbasic]{\Package{tocbasic}}% +\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}}\IndexPackage{tocbasic} +package. The \PName{tocstyle} attribute defines the style of those entries. If +you set an empty \PName{name}, e.\,g. using \OptionValue{tocstyle}{} or +\OptionValue{tocstyle}{\{\}}, the command for the TOC entry will not be +changed. This is important, for example, if you use another package to modify +the table of contents. If you do not set the \PValue{tocstyle} attribute, the +previous style will be used again during the redefinition. + +The\ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} different TOC-entry styles also have different additional +attributes. You can set them directly if you prefix them with \PValue{toc}. +For example, you can set the level of the TOC entries, \PValue{level}, using +\PValue{toclevel}, the indention, \PValue{indent}, using \PValue{tocindent}, +or the number width, \PValue{numwidth}, using \PValue{tocnumwidth}. For more +TOC-entry style attributes see \autoref{sec:tocbasic.tocstyle}, +\autopageref{sec:tocbasic.tocstyle}. + +\begin{Example} + For some unknown reason, you want to redefine the + \DescRef{maincls.cmd.paragraph} headings so that they are no longer run-in + headings but are similar to \DescRef{maincls.cmd.subsubsection}. The + vertical skip above the heading should be 10\Unit{pt} and no additional + vertical skip below the heading. To do so, you can use: +\begin{lstcode} + \RedeclareSectionCommand[% + beforeskip=-10pt,% + afterskip=1sp% + ]{paragraph} +\end{lstcode} + The negative value of \PValue{beforeskip} creates a positive vertical skip + before the heading and simultaneously disables the paragraph indentation of + the following text. Even though the specification did not want any vertical + skip after the heading, a value of 1\Unit{sp} has been given here. This is + because \LaTeX{} doesn't recognize 0\Unit{pt} as positive value. So + 1\Unit{sp} is the smallest possible positive value. + + Generally, it is better to have some tolerance for adjusting the vertical + spacing, the so-called \emph{glue}: +\begin{lstcode} + \RedeclareSectionCommand[% + beforeskip=-10pt plus -2pt minus -1pt,% + afterskip=1sp plus -1sp minus 1sp% + ]{paragraph} +\end{lstcode} + Note that the glue also switches the algebraic sign before becoming a skip, + if the value is negative. That is the reason for the negative glue values in + the example. Additionally we used the occasion to minimize the vertical skip + after the heading using glue too. +\end{Example} + +In the example above, we only needed to define the keys \PValue{beforeskip} +and \PValue{afterskip} because since v3.15 \KOMAScript{} has defined +\DescRef{maincls.cmd.paragraph} internally using +\Macro{DeclareSectionCommand}, and therefore the other settings can be adopted +unchanged. The original definition of \DescRef{maincls.cmd.paragraph} in +\Class{scrartcl} reads: +\begin{lstcode} + \DeclareSectionCommand[% + level=4, + indent=0pt, + beforeskip=3.25ex plus 1ex minus .2ex, + afterskip=-1em, + font={}, + tocindent=7em, + tocnumwidth=4.1em, + counterwithin=subsubsection + ]{paragraph} +\end{lstcode} +\Class{scrreprt} and \Class{scrbook} use slightly different values. + +Some settings of \DescRef{maincls.cmd.chapter} depend on the +\DescRef{maincls.option.headings} option (see \autoref{sec:maincls.structure}, +\DescPageRef{maincls.option.headings}). +\hyperref[tab:maincls.chapter.skips]{Table~\ref*{tab:maincls.chapter.skips}} +shows the default values of these settings. An overview of all settings is +shown in \autoref{tab:maincls.section.defaults}. For more +information\ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and +\Class{scrartcl}} about the default of the TOC-entry styles see +\autoref{sec:tocbasic.tocstyle}\important{\Package{tocbasic}}, +\autopageref{sec:tocbasic.tocstyle}. Note that \PValue{1ex} and +\Length{baselineskip} depend on the default font size of the heading or the +table of contents entry.% + +\begin{table} + \centering + \caption{Defaults for the chapter headings of \Class{scrbook} + and \Class{scrreprt} depending on the \DescRef{maincls.option.headings} + option} + \label{tab:maincls.chapter.skips} + \begin{tabular}{ll} + \multicolumn{2}{@{}l}{\bfseries + With \OptionValueRef{maincls}{headings}{big}:}\\ + \toprule + Attribute & Default Value \\ + \midrule + \PValue{afterskip} + & \PValue{1.725\Length{baselineskip} plus .115\Length{baselineskip} + minus .192\Length{baselineskip}} \\ + \PValue{beforeskip} + & \PValue{-3.3\Length{baselineskip}-\Length{parskip}} \\ + \PValue{font} & \Macro{huge} \\ + \bottomrule\\ + \multicolumn{2}{@{}l}{\bfseries + With \OptionValueRef{maincls}{headings}{normal}:}\\ + \toprule + Attribute & Default Value \\ + \midrule + \PValue{afterskip} + & \PValue{1.5\Length{baselineskip} plus .1\Length{baselineskip} + minus .167\Length{baselineskip}} \\ + \PValue{beforeskip} + & \PValue{-3\Length{baselineskip}-\Length{parskip}} \\ + \PValue{font} & \Macro{LARGE} \\ + \bottomrule\\ + \multicolumn{2}{@{}l}{\bfseries + With \OptionValueRef{maincls}{headings}{small}:}\\ + \toprule + Attribute & Default Value \\ + \midrule + \PValue{afterskip} + & \PValue{1.35\Length{baselineskip} plus .09\Length{baselineskip} + minus .15\Length{baselineskip}} \\ + \PValue{beforeskip} + & \PValue{-2.8\Length{baselineskip}-\Length{parskip}} \\ + \PValue{font} & \Macro{Large} \\ + \bottomrule + \end{tabular} +\end{table} + +%begin{table} +% \centering + \begin{longtable}{@{}p{\columnwidth}@{}} + \caption{Defaults for the headings of \Class{scrbook} and + \Class{scrreprt}}% + \label{tab:maincls.section.defaults}\\ + \endfirsthead + \caption[]{Default for the headings of \Class{scrbook} and + \Class{scrreprt} \emph{(continued)}}\\ + \addlinespace[-\normalbaselineskip] + \endhead + \raggedleft\dots\\ + \endfoot + \endlastfoot + \DescRef{maincls.cmd.part}: \\* + \begin{tabularx}{\linewidth}{ll} + \toprule + Attribute & Default Value \\ + \midrule + \PValue{afterskip} & \PValue{0pt plus 1fil} \\ + \PValue{beforeskip} & \PValue{0pt plus 1fil + \Length{baselineskip}} \\ + \PValue{font} & see element \DescRef{maincls.fontelement.part}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{innerskip} & \PValue{20pt} \\ + \PValue{level} & -1 \\ + \PValue{prefixfont} & see element + \DescRef{maincls.fontelement.partnumber}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{tocindent} & \PValue{0pt} \\ + \PValue{toclevel} & -1 \\ + \PValue{tocnumwidth} & \PValue{2em} \\ + \PValue{tocstyle} & \PValue{part} \\ + \bottomrule + \end{tabularx} \\ + \addlinespace[\normalbaselineskip] + \DescRef{maincls.cmd.chapter}: \\* + \begin{tabularx}{\linewidth}{ll} + \toprule + Attribute & Default Value \\ + \midrule + \PValue{afterskip} & see \autoref{tab:maincls.chapter.skips} \\ + \PValue{beforeskip} & see \autoref{tab:maincls.chapter.skips} \\ + \PValue{font} & see element \DescRef{maincls.fontelement.chapter}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{innerskip} & \PValue{0.5\Length{baselineskip}} \\ + \PValue{level} & 0 \\ + \PValue{prefixfont} & see element + \DescRef{maincls.fontelement.chapterprefix}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{tocindent} & \PValue{0pt} \\ + \PValue{toclevel} & 0 \\ + \PValue{tocnumwidth} & \PValue{1.5em} \\ + \PValue{tocstyle} & \PValue{chapter} \\ + \bottomrule + \end{tabularx} \\ + \addlinespace[\normalbaselineskip] + \DescRef{maincls.cmd.section}: \\* + \begin{tabularx}{\linewidth}{ll} + \toprule + Attribute & Default Value \\ + \midrule + \PValue{afterskip} & \PValue{2.3ex plus .2ex} \\ + \PValue{beforeskip} & \PValue{-3.5ex plus -1ex minus -.2ex} \\ + \PValue{font} & see element \DescRef{maincls.fontelement.section}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{indent} & \PValue{0pt} \\ + \PValue{level} & 1 \\ + \PValue{tocindent} & \PValue{1.5em}\\ + \PValue{toclevel} & 1 \\ + \PValue{tocnumwidth} & \PValue{2.3em}\\ + \PValue{tocstyle} & \PValue{section} \\ + \bottomrule + \end{tabularx} \\ + \addlinespace[\normalbaselineskip] + \DescRef{maincls.cmd.subsection}: \\* + \begin{tabularx}{\linewidth}{ll} + \toprule + Attribute & Default Value \\ + \midrule\nopagebreak + \PValue{afterskip} & \PValue{1.5ex plus .2ex} \\ + \PValue{beforeskip} & \PValue{-3.25ex plus -1ex minus -.2ex} \\ + \PValue{font} & see element + \DescRef{maincls.fontelement.subsection}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{indent} & \PValue{0pt} \\ + \PValue{level} & 2 \\ + \PValue{tocindent} & \PValue{3.8em}\\ + \PValue{toclevel} & 2 \\ + \PValue{tocnumwidth} & \PValue{3.2em}\\ + \PValue{tocstyle} & \PValue{section} \\ + \bottomrule + \end{tabularx} \\ + \addlinespace[\normalbaselineskip] + \DescRef{maincls.cmd.subsubsection}: \\* + \begin{tabularx}{\linewidth}{ll} + \toprule + Attribute & Default Value \\ + \midrule\nopagebreak + \PValue{afterskip} & \PValue{1.5ex plus .2ex} \\ + \PValue{beforeskip} & \PValue{-3.25ex plus -1ex minus -.2ex} \\ + \PValue{font} & see element + \DescRef{maincls.fontelement.subsubsection}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{indent} & \PValue{0pt} \\ + \PValue{level} & 3 \\ + \PValue{tocindent} & \PValue{7.0em}\\ + \PValue{tocnumwidth} & \PValue{4.1em}\\ + \PValue{toclevel} & 3 \\ + \PValue{tocstyle} & \PValue{section} \\ + \bottomrule + \end{tabularx} \\ + \addlinespace[\normalbaselineskip] + \DescRef{maincls.cmd.paragraph}: \\* + \begin{tabularx}{\linewidth}{ll} + \toprule + Attribute & Default Value \\ + \midrule\nopagebreak + \PValue{afterskip} & \PValue{-1em} \\ + \PValue{beforeskip} & \PValue{3.25ex plus 1ex minus .2ex} \\ + \PValue{font} & see element \DescRef{maincls.fontelement.paragraph}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{indent} & \PValue{0pt} \\ + \PValue{level} & 4 \\ + \PValue{tocindent} & \PValue{10em}\\ + \PValue{toclevel} & 4 \\ + \PValue{tocnumwidth} & \PValue{5em}\\ + \PValue{tocstyle} & \PValue{section} \\ + \bottomrule + \end{tabularx} \\ + \addlinespace[\normalbaselineskip] + \DescRef{maincls.cmd.subparagraph}: \\* + \begin{tabularx}{\linewidth}{ll} + \toprule + Attribute & Default Value \\ + \midrule\nopagebreak + \PValue{afterskip} & \PValue{-1em} \\ + \PValue{beforeskip} & \PValue{3.25ex plus 1ex minus .2ex} \\ + \PValue{font} & see element + \DescRef{maincls.fontelement.subparagraph}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{indent} & \Macro{scr@parindent} \\ + \PValue{level} & 5 \\ + \PValue{tocindent} & \PValue{12em}\\ + \PValue{toclevel} & 5 \\ + \PValue{tocnumwidth} & \PValue{6em}\\ + \PValue{tocstyle} & \PValue{section} \\ + \bottomrule + \end{tabularx} + \end{longtable} +%end{table} +Incidentally, the internal macro \Macro{scr@parindent} used in the settings +for \DescRef{maincls.cmd.subparagraph} is the paragraph indent set by the +\DescRef{maincls.option.parskip} option or the +\DescRef{maincls-experts.cmd.setparsizes} command. +\EndIndexGroup + + +\begin{Declaration} + \Macro{DeclareSectionCommands}\OParameter{attributes} + \Parameter{list of names}% + \Macro{DeclareNewSectionCommands}\OParameter{attributes} + \Parameter{list of names}% + \Macro{RedeclareSectionCommands}\OParameter{attributes} + \Parameter{list of names}% + \Macro{ProvideSectionCommands}\OParameter{attributes} + \Parameter{list of names} +\end{Declaration} +These\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} commands can define or change a whole series of +sectioning commands at once. The names of the sectioning commands are given by +the comma-separated \PName{list of names}. + +These commands differ in two other ways from the previously described commands +that only define or change a single sectioning command. First, in case of +error\,---\,that is if a command already exists with +\Macro{DeclareNewSectionCommands} or is undefined with +\Macro{RedeclareSectionCommands}\,---\,the definition will be performed +regardless. An appropriate an error message will, of course, be reported +anyway. + +Second, there is another attribute, +\important{\PValue{increaselevel}}\OptionVName{increaselevel}{integer}. This +attribute changes the meaning of the attributes \PValue{level} and +\PValue{toclevel} (see \autoref{tab:maincls-experts.declaresection.keys}) so +that their values become starting values for the first sectioning command of +the \PName{list of names}. For all other sectioning command in the \PName{list +of names}, the values of \PValue{level} and \PValue{toclevel} are successively +increased by the value of \PValue{increaselevel}. If the +\PValue{increaselevel} attribute is used without assigning a value, 1 is +assumed. +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{chapterheadstartvskip} + \Macro{chapterheadmidvskip} + \Macro{chapterheadendvskip} + \Macro{partheadstartvskip} + \Macro{partheadmidvskip} + \Macro{partheadendvskip} + \Macro{partheademptypage} +\end{Declaration} +These\important[i]{\DescRef{maincls.cmd.chapter}\\ + \DescRef{maincls.cmd.part}\\ + \DescRef{maincls.cmd.addchap}\\ + \DescRef{maincls.cmd.addpart}\\ + \DescRef{maincls.cmd.chapter*}\\ + \DescRef{maincls.cmd.part*}\\ + \DescRef{maincls.cmd.addchap*}\\ + \DescRef{maincls.cmd.addpart*}} commands are used inside the headings of the +previously described \PValue{chapter} and \PValue{part} styles and thus for +the definitions of \DescRef{maincls.cmd.chapter}\IndexCmd{chapter}, +\DescRef{maincls.cmd.part}\IndexCmd{part}, +\DescRef{maincls.cmd.addchap}\IndexCmd{addchap}, and +\DescRef{maincls.cmd.addpart}\IndexCmd{addpart}, as well as their starred +variants \DescRef{maincls.cmd.chapter*}\IndexCmd{chapter*}, +\DescRef{maincls.cmd.part*}\IndexCmd{part*}, +\DescRef{maincls.cmd.addchap*}\IndexCmd{addchap*}, and +\DescRef{maincls.cmd.addpart*}\IndexCmd{addpart*}. +The \Macro{chapterheadstartvskip} command is intended to insert a +vertical skip before the chapter heading. Similarly, +\Macro{chapterheadendvskip} is a command intended to insert a vertical +skip after the chapter heading. If\ChangedAt{v3.15}{\Class{scrbook}\and + \Class{scrreprt}} the chapter heading has a prefix number line (see option +\DescRef{maincls.option.chapterprefix} in \autoref{sec:maincls.structure}, +\DescPageRef{maincls.option.chapterprefix}), \Macro{chapterheadmidvskip} +is also used between the number line and the heading text. + +The \Macro{partheadstartvskip} and \Macro{partheadendvskip} commands insert +vertical skips above and below part headings. A page break is interpreted as +part of the vertical distance. Such a page break is part of the default +definitions of \Macro{partheadendvskip} in +\Class{scrbook}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} and +\Class{scrreprt}. The +\Macro{partheademptypage}\ChangedAt{v3.02}{\Class{scrbook}\and +\Class{scrreprt}} command produces an empty page after the part heading page +of \Class{scrbook} and \Class{scrreprt}. + +Starting with \KOMAScript~3.15\ChangedAt{v3.15}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}, the defaults of these seven commands +are independent from the \DescRef{maincls.option.headings} option (see +\autoref{sec:maincls.structure}, +\DescPageRef{maincls.option.headings}). The default definitions for the +chapter headings starting with +\KOMAScript~3.17\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} correspond to:\IndexLength{@tempskipa} +\begin{lstcode} + \newcommand*{\chapterheadstartvskip}{\vspace{\@tempskipa}} + \newcommand*{\chapterheadmidvskip}{\par\nobreak\vskip\@tempskipa} + \newcommand*{\chapterheadendvskip}{\vskip\@tempskipa} +\end{lstcode} +These defaults are reactivated every time you use +\OptionValueRef{maincls}{headings}{big}\IndexOption{headings}, +\OptionValueRef{maincls}{headings}{normal}, or +\OptionValueRef{maincls}{headings}{small}. As a side effect, these options may +affect not only chapter titles but all headings in the \PValue{chapter} style + +The \PValue{chapter} style automatically sets the internal length +\Length{@tempskipa} to the value that results from the +\DescRef{\LabelBase.cmd.DeclareSectionCommand}\IndexCmd{DeclareSectionCommand} +attribute \PValue{beforeskip} before calling \Macro{chapterheadstartvskip}. +Similarly, it sets this length to the value of the \PValue{afterskip} +attribute before calling \Macro{chapterheadendvskip}, and to +\PValue{innerskip} before calling \Macro{chapterheadmidvskip}. + +The default values of the distances of \DescRef{maincls.cmd.part} do not +depend on the \DescRef{maincls.option.headings} option. So the corresponding +commands will not be redefined by this option. +Their\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and +\Class{scrartcl}} default definitions in \Class{scrbook} and \Class{scrreprt} +correspond to: +\begin{lstcode} + \newcommand*{\partheadstartvskip}{% + \null\vskip-\baselineskip\vskip\@tempskipa + } + \newcommand*{\partheadmidvskip}{% + \par\nobreak + \vskip\@tempskipa + } + \newcommand*{\partheadendvskip}{% + \vskip\@tempskipa\newpage + } +\end{lstcode} +and of \Class{scrartcl}: +\begin{lstcode} + \newcommand*{\partheadstartvskip}{% + \addvspace{\@tempskipa}% + } + \newcommand*{\partheadmidvskip}{% + \par\nobreak + } + \newcommand*{\partheadendvskip}{% + \vskip\@tempskipa + } +\end{lstcode} +The \PValue{part} style once again sets the internal length +\Length{@tempskipa}\IndexLength{@tempskipa} according to the settings of +\DescRef{\LabelBase.cmd.DeclareSectionCommand}\IndexCmd{DeclareSectionCommand} +before using the commands. + +If you redefine one of the commands used for the vertical skip in the original +\Length{@tempskipa} but still want to be able to configure the lengths, for +example with \DescRef{\LabelBase.cmd.RedeclareSectionCommand}, you should also +use \Length{@tempskipa} in the new definition. +Since\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} you can more easily configure the distances above, within, +and below the headings using \DescRef{\LabelBase.cmd.RedeclareSectionCommand}, +you generally should not redefine the commands described here. Changing them +should be reserved for more complex changes that cannot be accomplished with +\DescRef{\LabelBase.cmd.RedeclareSectionCommand}. An\textnote{Example!} +example that redefines \Macro{chapterheadstartvskip} and +\Macro{chapterheadendvskip} to print extra rules above and below the chapter +heading can be found at \cite{homepage} (in German).% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{partlineswithprefixformat}% + \Parameter{level}\Parameter{number}\Parameter{text}% +\end{Declaration} +This\ChangedAt{v3.25}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} command is used by headings with the \PValue{part} style to +output the heading number and heading text. The \PName{number} and +\PName{text} arguments are already formatted, including the font +selections. Ultimately, this command controls the arrangement of the two parts +of the heading. For unnumbered headings, \PName{number} is a completely empty +argument, so it does not contain any formatting commands. + +The default definition is rather Spartan: +\begin{lstcode} + \newcommand{\partlineswithprefixformat}[3]{% + #2#3% + } +\end{lstcode} + +\begin{Example} + You want to have part headings in a light blue box with blue frame. The + box should occupy only about three quarters of full width of the text + area. So you try: +\begin{lstcode} + \documentclass{scrbook} + \usepackage{xcolor} + \renewcommand*{\partlineswithprefixformat}[3]{% + \fcolorbox{blue}{blue!25}{% + \parbox{.75\linewidth}{#2#3}% + }% + } + \begin{document} + \part{Framed Part} + \end{document} +\end{lstcode} + But surprisingly the heading is not longer centred\,---\,neither the box + itself nor the text inside the box. + + The reason for the missing centring of the box is that the end of the + paragraph is hidden in the third argument of the command. So it still + finishes the paragraph of the text inside the box but not the paragraph of + the \Macro{parbox} itself. To solve this you add a \Macro{par} at the end of + the definition. + + The reason for the missing centring inside the box is that the alignment of + \DescRef{maincls.cmd.raggedpart} is valid outside the box but not + automatically inside a \Macro{parbox}. To solve this you add + \Macro{raggedpart} inside the box. + + With +\begin{lstcode} + \documentclass{scrbook} + \usepackage{xcolor} + \renewcommand*{\partlineswithprefixformat}[3]{% + \fcolorbox{blue}{blue!25}{% + \parbox{.75\linewidth}{\raggedpart #2#3}% + }% + } + \par + \begin{document} + \part{Framed Part} + \end{document} +\end{lstcode} + you get the expected result. +\end{Example} + +As the example shows, users who redefine this command must watch out for +several side effects. In addition to preserving the text alignment, they also +must prevent page breaks within the headings, for example if they insert extra +paragraphs or space. The example above does not have this problem. Not only +does the box prevent a page breaks anyway, but \KOMAScript{} itself also +changes \Macro{interlinepenalty} as part of \PName{text} so to prevent page +breaks there. It also finishes \PName{text} with an internal paragraph break +using \Macro{@@par}. + +The default definition of \Macro{partlineswithprefixformat} does not use the +first argument, \PName{level}, nor is it needed in the example above. It is of +interest only if you want to define several commands with the \PValue{part} +style and need to distinguish the different levels. The predefined commands +\DescRef{maincls.cmd.part}, \DescRef{maincls.cmd.part*}, +\DescRef{maincls.cmd.addpart}, and \DescRef{maincls.cmd.addpart*} all share +the same \PName{level} \PName{part}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{chapterlineswithprefixformat}% + \Parameter{level}\Parameter{number}\Parameter{text}% + \Macro{chapterlinesformat}% + \Parameter{level}\Parameter{number}\Parameter{text} +\end{Declaration} +These\ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}} commands are used +by headings with the \PValue{chapter} style to output the heading number and +heading text, depending on the +\DescRef{maincls.option.chapterprefix}\IndexOption{chapterprefix}% +\textnote{\DescRef{maincls.option.chapterprefix}} option (see +\autoref{sec:maincls.structure}, +\DescPageRef{maincls.option.chapterprefix}). If the option is \PValue{true}, +\Macro{chapterlineswithprefixformat} is used. Otherwise +\Macro{chapterlinesformat} determines the ouput. + +The \PName{number} and \PName{text} arguments are already formatted, including +the font selections. Ultimately, these commands thus control the arrangement +of the two parts of the heading. For unnumbered headings, the \PName{number} +argument is completely empty, so it does not contain any formatting commands. + +The\textnote{default} defaults for these commands are: +\begin{lstcode} + \newcommand{\chapterlinesformat}[3]{% + \@hangfrom{#2}{#3}% + } + \newcommand{\chapterlineswithprefixformat}[3]{% + #2#3% + } +\end{lstcode} + +\begin{Example} + You want to have chapter headings with yellow background. For the headings + without a prefix line, you use the following definition in the document + preamble: +\begin{lstcode} + \makeatletter + \renewcommand{\chapterlinesformat}[3]{% + \colorbox{yellow}{% + \parbox{\dimexpr\linewidth-2\fboxrule-2\fboxsep}{% + \@hangfrom{#2}#3% + }% + }% + } + \makeatother +\end{lstcode} + For chapter headings with prefix line, you use: +\begin{lstcode} + \renewcommand{\chapterlineswithprefixformat}[3]{% + \colorbox{yellow}{% + \parbox{\dimexpr\linewidth-2\fboxrule-2\fboxsep}{% + #2#3% + }% + }% + } +\end{lstcode} + Unfortunately, you discover that these redefinitions result in justified + text for the headings. The reason is the \Macro{parbox} command. To change + this, you can use the \DescRef{maincls.cmd.raggedchapter} command (see + \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.raggedchapter}) + inside the argument of \Macro{parbox}. Otherwise \Macro{raggedchapter} would + be used only before \Macro{chapterlineswithprefixformat} and + \Macro{chapterlinesformat}: +\begin{lstcode} + \makeatletter + \renewcommand{\chapterlinesformat}[3]{% + \colorbox{yellow}{% + \parbox{\dimexpr\linewidth-2\fboxrule-2\fboxsep}{% + \raggedchapter + \@hangfrom{#2}#3% + }% + }% + } + \makeatother + \renewcommand{\chapterlineswithprefixformat}[3]{% + \colorbox{yellow}{% + \parbox{\dimexpr\linewidth-2\fboxrule-2\fboxsep}{% + \raggedchapter + #2#3% + }% + }% + } +\end{lstcode} + Remember to use \Macro{makeatletter} and \Macro{makeatother} only in the + document preamble. Do not use it inside your own wrapper class or package. + They are only needed here because of \Macro{@hangfrom} in the definition of + \Macro{chapterlinesformat}. +\end{Example} + +As the example shows, users who redefine this command must watch out for +several side effects. In addition to preserving the text alignment, they also +must prevent page breaks within the headings, for example if they insert extra +paragraphs or space. The example above does not have this problem. Not only +does the box prevent a page breaks anyway, but \KOMAScript{} itself also +changes \Macro{interlinepenalty} as part of \PName{text} so to prevent page +breaks there. It also finishes \PName{text} with an internal paragraph break +using \Macro{@@par}. + +Incidentally, the \DescRef{maincls.cmd.raggedchapter} command is not part of +\PName{text}, as otherwise using \Macro{MakeUppercase} inside redefined +versions of these two commands would be much more difficult. Note, however, +that typographic rules require individual adjustments of letter spacing in +capitalised text. However the \LaTeX{} \Macro{MakeUppercase} command does not +do this. + +The default definitions do not use the first argument, \PName{level}, nor is +it needed in the example above. It is of interest only if you want to define +several commands with the \PValue{chapter} style and need to distinguish the +different levels. The predefined commands \DescRef{maincls.cmd.chapter}, +\DescRef{maincls.cmd.chapter*}, \DescRef{maincls.cmd.addchap}, and +\DescRef{maincls.cmd.addchap*} all share the same \PName{level} +\PName{chapter}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{sectionlinesformat}% + \Parameter{level}\Parameter{indent}\Parameter{number}\Parameter{text}% + \Macro{sectioncatchphraseformat}% + \Parameter{level}\Parameter{indent}\Parameter{number}\Parameter{text}% +\end{Declaration} +These\ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}\and +\Class{scrartcl}} commands are used by headings with the \PValue{section} +style depending on whether the reading is run-in or on its own line. +Free-standing headings use \Macro{sectionlinesformat} for their output, while +run-in headings use \Macro{sectioncatchphraseformat}. + +In both cases \PName{indent} is the value of the horizontal indention of the +heading relative to the text area. If the value is negative, the heading can +protrude into the left margin. + +The arguments \PName{number} and \PName{text} are already formatted, including +the font settings. Ultimately, these commands thus control the arrangement of +the two parts of the heading. For unnumbered headings, the \PName{number} +argument is completely empty, so it does not contain any formatting commands. + +The default definitions are: +\begin{lstcode} +\newcommand{\sectionlinesformat}[4]{% + \@hangfrom{\hskip #2#3}{#4}% +} +\newcommand{\sectioncatchphraseformat}[4]{% + \hskip #2#3#4% +} +\end{lstcode} + +If you redefine one of these commands, you are responsible for preventing page +breaks inside heading. \KOMAScript{} itself only changes +\Macro{interlinepenalty} to impede page breaks. + +\begin{Example} + As in the previous example with chapter headings, the free-standing headings + of the \PValue{section} \PName{level} should now be printed with a + background colour. Headings of lower levels should not be changed: +\begin{lstcode} + \makeatletter + \renewcommand{\sectionlinesformat}[4]{% + \@tempswafalse + \ifstr{#1}{section}{% + \hspace*{#2}% + \colorbox{yellow}{% + \parbox{\dimexpr\linewidth-2\fboxrule-2\fboxsep-#2}{% + \raggedsection + \@hangfrom{#3}{#4}% + }% + }% + }{% + \@hangfrom{\hskip #2#3}{#4}% + }% + } + \makeatother +\end{lstcode} + With this code, area of the indention is not coloured if the heading is + indented. If, however, the heading is placed in the left margin with + negative indention, this area of the margin is also highlighted. You can + move the \Macro{hspace*} command into the \Macro{colorbox} to change this + behaviour. + + Again, remember to use \Macro{makeatletter} and \Macro{makeatother} only in + the document preamble. You should omit them inside your own wrapper class or + package. They are only needed because of \Macro{@hangfrom} in the definition + of \Macro{sectionlinesformat}. +\end{Example} + +The first argument, \PName{level}, is not used by the default definition. The +example shows how to use it to distinguish different heading levels of the +same style \PValue{section}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{SecDef}\Parameter{star command}\Parameter{command}% + \Macro{scr@startsection}\Parameter{name}\Parameter{level}\Parameter{indent}% + \Parameter{beforeskip}\Parameter{afterskip}% + \Parameter{style commands}% + \OParameter{short version}\Parameter{heading}% + \labelsuffix[*]% + \Macro{scr@startsection}\Parameter{name}\Parameter{level}\Parameter{indent}% + \Parameter{beforeskip}\Parameter{afterskip}% + \Parameter{style commands}% + \PValue{*}\Parameter{heading}% + \labelsuffix% + \Macro{At@startsection}\Parameter{code}% + \Macro{Before@ssect}\Parameter{code}% + \Macro{Before@sect}\Parameter{code} +\end{Declaration} +As\ChangedAt[2014/09]{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and +\Class{scrartcl}} already explained in \autoref{sec:maincls.structure} in the +description of the sectioning commands beginning with +\DescPageRef{maincls.cmd.chapter}, \KOMAScript{} provides additional features +for the optional argument of those commands. To achieve this, it was necessary +to replace some \LaTeX{} kernel commands, especially +\Macro{secdef}\IndexCmd{secdef}\important{\Macro{secdef}} and +\Macro{@startsection}\IndexCmd{@startsection}% +\important{\Macro{@startsection}}. The meaning of the parameters of these +commands can be found in the \LaTeX{} kernel manual \cite{latex:source2e}. + +However, these commands are often completely redefined by other packages in a +way that clashes with the functionality of \KOMAScript. So \KOMAScript{} not +only changes the definition of these commands but also defines the additional, +alternative commands \Macro{SecDef} and \Macro{scr@startsection}. Package +authors can use these commands as they would use the corresponding \LaTeX{} +kernel commands and therefore gain access to the additional features of +\KOMAScript. However, these commands should not be redefined, as they may +changed at any time, and then this redefinition could compromise +\KOMAScript{}'s functionality. + +\KOMAScript{} itself uses \Macro{SecDef} and \Macro{scr@startsection} instead +of \Macro{secdef} and \Macro{@startsection}, for example to define sectioning +commands with \DescRef{\LabelBase.cmd.DeclareSectionCommand}. So later +redefinitions of \Macro{secdef} or \Macro{@startsection} will not influence +the sectioning commands of \KOMAScript. + +As an alternative to redefining such commands, \KOMAScript{} offers the +possibility to add additional \PName{code} at several points in +\KOMAScript{}'s own replacements. The \PName{code} of all calls to +\Macro{At@startsection}\important{\Macro{At@startsection}\\ + \Macro{Before@sect}\\ + \Macro{Before@sect}}, \Macro{Before@sect} and \Macro{Before@sect} is +collected separately for each command. There is no provision for removing +\PName{code} once it has been inserted. + +The \PName{code} of the \Macro{At@startsection}% + \important{\Macro{At@startsection}\\ + \Macro{scr@startsection}} macro is used in the \Macro{scr@startsection} +command immediately after evaluating \PName{beforeskip} and calculating the +resulting \Length{@tempskipa} but before adding the vertical skip itself. So +you can still change the value of \Length{@tempskipa}. + +The \PName{code} of \Macro{Before@sect} or \Macro{Before@ssect} is executed +within \Macro{scr@startsection} just before calling \Macro{@sect} or +\Macro{@ssect}, respectively. At this point, the vertical skip of +\Length{@tempskipa} has already been added using \Macro{addvspace}. + +These three commands, \Macro{At@startsection}, \Macro{Before@sect}, and +\Macro{Before@ssect}, are designed as an interface for package authors and +released for them to use.% +% +\EndIndexGroup + +% \subsection{Appendix} +% \seclabel{appendix} + + +\begin{Declaration} + \Macro{appendixmore} +\end{Declaration}% +The \KOMAScript{} classes have an unusual feature within the +\DescRef{maincls.cmd.appendix} command. If the \Macro{appendixmore} command +is defined, \DescRef{maincls.cmd.appendix} will also execute this +it. Internally, the \KOMAScript{} classes +\Class{scrbook}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} and +\Class{scrreprt} take advantage of this behaviour to implement the +\DescRef{maincls.option.appendixprefix} layout option (see +\autoref{sec:maincls.structure}, +\DescPageRef{maincls.option.appendixprefix}). You\textnote{Attention!} should +take note of this in case you decide to define or redefine the +\Macro{appendixmore} macro. If this option has been used, you will receive an +error message when using \verb|\newcommand{\appendixmore}{|\dots\verb|}|. This +behaviour is intended to prevent you from overriding the options without +realising it. + +\begin{Example} + You do not want the chapters in the main part of the classes \Class{scrbook} + or \Class{scrreprt} to be introduced by a prefix line (see the + \DescRef{maincls.option.chapterprefix} layout option in + \autoref{sec:maincls.structure}, + \DescPageRef{maincls.option.chapterprefix}). For consistency, you also do + not want such a line in the appendix either. Instead, you would like to see + the word ``Chapter'' in the language of your choice written in front of the + chapter letter and, simultaneously, in the page headings. Instead of using + the \DescRef{maincls.option.appendixprefix} layout option, you define the + following in the document preamble: +% +\begin{lstcode} + \newcommand*{\appendixmore}{% + \renewcommand*{\chapterformat}{% + \appendixname~\thechapter\autodot\enskip} + \renewcommand*{\chaptermarkformat}{% + \appendixname~\thechapter\autodot\enskip} + } +\end{lstcode} +% + In case you subsequently change your mind and decide to use the option + \DescRef{maincls.option.appendixprefix} at a later stage, you will get an + error message because of the already defined \Macro{appendixmore} command. + This behaviour prevents the definition made above from invisibly changing + the settings intended with the option. + + It is also possible to get a similar behaviour for the appendix of the class + \Class{scrartcl}. For example, you can write in the preamble of your + document: +\begin{lstcode}[moretexcs={ifthenelse,equal}] + \newcommand*{\appendixmore}{% + \renewcommand*{\sectionformat}{% + \appendixname~\thesection\autodot\enskip}% + \renewcommand*{\sectionmarkformat}{% + \appendixname~\thesection\autodot\enskip}} +\end{lstcode} + + The redefined commands are explained in more detail in + \autoref{sec:maincls.structure}, + \DescPageRef{maincls.cmd.chapterformat} and + \DescPageRef{maincls.cmd.chaptermarkformat}. +\end{Example} +% +\EndIndexGroup + + +% \subsection{Literaturverzeichnis} +% \seclabel{bibliography} + +\begin{Declaration} + \Macro{newbibstyle}\OParameter{parent style}\Parameter{name}%^^A + \Parameter{commands}% + \Macro{newblock}% + \Macro{@openbib@code}% + \Macro{bib@beginhook}% + \Macro{bib@endhook} +\end{Declaration} +The standard classes\textnote{standard classes} already provide the +\Macro{newblock} command to structure bibliography entries. The exact purpose +of this command depends on the class options. Using option +\Option{openbib}\important{\Option{openbib}} redefines the commands +\Macro{@openbib@code} and \Macro{newblock} itself at the end of the standard +class. The standard classes execute the \Macro{@openbib@code} command when +starting the bibliography list, or more precisely, when defining the +parameters for the list. You can assume that many packages which redefine the +bibliography will execute this command. + +The \KOMAScript{} classes\textnote{\KOMAScript} do something similar. However, +they do not redefine \Macro{@openbib@code} at the end of the class. Instead, +\Macro{newbibstyle} defines the \PValue{openstyle} bibliography style. The +\PName{commands} given in the implementation contain the appropriate +redefinition of \Macro{@openbib@code} and \Macro{newblock}. If you select this +bibliography style using the +\OptionValueRef{maincls}{bibliography}{openstyle}% +\IndexOption{bibliography~=\PValue{openstyle}}% +\important{\OptionValueRef{maincls}{bibliography}{openstyle}} option, the +\PName{commands} will be executed immediately. This will redefine +\Macro{@openbib@code} and \Macro{newblock}. + +In addition to \Macro{@openbib@code} and \Macro{newblock}, +\Macro{bib@beginhook} and \Macro{bib@endhook} can also be redefined by the +\PName{commands} of the style. The \Macro{bib@beginhook} command is executed +immediately after the heading and preamble of the bibliography but before the +beginning of the list of bibliographic entries. The \Macro{bib@endhook} +command will be executed immediately after this list, at the end of the +bibliography. If \DescRef{maincls.cmd.BreakBibliography} (see +\autoref{sec:maincls.bibliography}, +\DescPageRef{maincls.cmd.BreakBibliography}) is used to interrupt the +bibliography, these commands will also executed at the beginning and end of +each part of the bibliography, immediately before and after +\DescRef{maincls.cmd.BreakBibliography}. + +The \Macro{newblock}, \Macro{@openbib@code}, \Macro{bib@beginhook}, and +\Macro{bib@endhook} commands are initially defined to be empty when using a +new bibliography style. After this, the \PName{commands} of the \PName{parent +style} that was optionally specified when defining the style will be executed, +followed by the \PName{commands} for the bibliography style itself. As a +result, these commands must be defined, if necessary, with +\Macro{renewcommand}\IndexCmd{renewcommand}\important{\Macro{renewcommand}}, +not \Macro{newcommand}, inside the \PName{instructions} argument. + +If you use the +\DescRef{maincls.cmd.AtEndBibliography}\IndexCmd{AtEndBibliography} and +\DescRef{maincls.cmd.AfterBibliographyPreamble}% +\IndexCmd{AfterBibliographyPreamble} commands to declare additional +\PName{commands} to be executed after the preamble or at the end of the +bibliography, the \PName{commands} specified with +\DescRef{maincls.cmd.AfterBibliographyPreamble} will only be executed once, at +the beginning of the bibliography after the \Macro{bib@beginhook} +\PName{commands}, and the \PName{commands} of +\DescRef{maincls.cmd.AtEndBibliography} will be executed only once at the end +of the bibliography, before \Macro{bib@endhook}. + +For\textnote{Example!} example, the +\Package{multicol}\IndexPackage{multicol}\important{\Package{multicol}} +package (see \cite{package:multicol}) could be used to define a bibliography +style for printing the bibliography with two columns: +% Umbruchkorrektur: listings korrigiert +\begin{lstcode} + \newbibstyle{twocolumstyle}{% + \renewcommand*{\bib@beginhook}{\begin{multicols}{2}}% + \renewcommand*{\bib@endhook}{\end{multicols}}}% +\end{lstcode} +If you also want to define an open variation of this style, you can use +the possibilities of inheritance here and specify a \PName{parent style}: +% Umbruchkorrektur: listings korrigiert +\begin{lstcode} + \newbibstyle{twocolumopenstyle}[openstyle]{% + \renewcommand*{\bib@beginhook}{\begin{multicols}{2}}% + \renewcommand*{\bib@endhook}{\end{multicols}}}% +\end{lstcode} +You can then select these newly defined styles with the +\DescRef{maincls.option.bibliography} option as usual. + +Like\textnote{Achtung!} \DescRef{maincls.cmd.BreakBibliography}, these +commands lose all or part of their effect when \Environment{thebibliography} +is redefined, for example by using +\Package{biblatex}\IndexPackage{biblatex}\important{\Package{biblatex}}.% +\EndIndexGroup + + +\section{More or Less Obsolete Options and Commands} +\seclabel{obsolete} + +\LoadNonFree{scrbookreportarticle-experts}{4} +% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% ispell-local-dictionary: "english" +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: + +% LocalWords: Amongst legitimation diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrbookreportarticle.tex b/macros/latex/contrib/koma-script/source-doc/english/scrbookreportarticle.tex new file mode 100644 index 0000000000..b20b18726b --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrbookreportarticle.tex @@ -0,0 +1,4662 @@ +% ====================================================================== +% scrbookreportarticle.tex +% Copyright (c) Markus Kohm, 2001-2019 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrbookreportarticle.tex +% Copyright (c) Markus Kohm, 2001-2019 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrbook, scrreprt, and scrartcl of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber scrbook, scrreprt und scrartcl in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrbookreportarticle.tex} + [$Date: 2019-01-14 14:29:39 +0100 (Mon, 14 Jan 2019) $ + KOMA-Script guide (chapter: scrbook, scrreprt, scrartcl)] + +\translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm\and + Krickette Murabayashi\and Jana Schubert\and Jens H\"uhne\and Karl Hagen} + +% Date of the translated German file: 2019-01-14 + +\chapter{The Main Classes: \Class{scrbook}, \Class{scrreprt}, and + \Class{scrartcl}} +\labelbase{maincls}% +\BeginIndexGroup +\BeginIndex{Class}{scrbook}% +\BeginIndex{Class}{scrreprt}% +\BeginIndex{Class}{scrartcl}% + +\AddSeeIndex{instruction}{gen}{\GuidecmdIndexShort}{cmd}% +\AddSeeIndex{macro}{gen}{\GuidecmdIndexShort}{cmd}% +The main classes of the {\KOMAScript} bundle are designed as counterparts to +the standard {\LaTeX} classes. This means that the {\KOMAScript} bundle +contains replacements for the three standard classes, +\Class{book}\IndexClass{book}, \Class{report}\IndexClass{report}, and +\Class{article}\IndexClass{article}. There is also a replacement for the +standard \Class{letter}\IndexClass{letter} class. The document class for +letters is described in a separate chapter because it is fundamentally +different from the three main classes (see \autoref{cha:scrlttr2}). + +The simplest way to use a {\KOMAScript} class instead of a standard one is to +substitute the class name in the \verb|\documentclass| command in accordance +with \autoref{tab:\LabelBase.overview}. For example, you can replace +\Macro{documentclass}\PParameter{book} with +\Macro{documentclass}\PParameter{scrbook}. Normally, {\LaTeX} should process +the document without errors, just as before the substitution. The layout, +however, should be different. Additionally, the {\KOMAScript} classes provide +new possibilities and options that are described in the following sections. + +\begin{table} +% \centering + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% +% \caption + \begin{captionbeside} + [Class correspondence]{\label{tab:\LabelBase.overview}Correspondence between + standard classes and {\KOMAScript} classes} + [l] + \begin{tabular}[t]{ll} + \toprule + standard class & \KOMAScript{} class \\%& \Script-Stil (\LaTeX2.09)\\ + \midrule + \Class{article} & \Class{scrartcl} \\%& \File{script\textunderscore s} \\ + \Class{report} & \Class{scrreprt} \\%& \File{script} \\ + \Class{book} & \Class{scrbook} \\%& \File{script} \\ + \Class{letter} & \Class{scrlttr2} \\%& \File{script\textunderscore l} \\ + \bottomrule + \end{tabular} + \end{captionbeside} +\end{table} + +Let me say something before describing the classes. When beginning to write a +document, you are often unsure which specific options to choose. Some +settings, for instance the choice of paper size, may be fixed in advance. But +even the question of the appropriate page layout could be difficult to answer +initially. On the other hand, these settings should be nearly irrelevant, in +the beginning, to the main business of an author: planning the document +structure, writing the text, preparing figures, tables, lists, index, and +other data. As an author, you should concentrate initially on the content. +When that is done, you can take on the fine points of presentation. In +addition to the choice of options, this includes correcting hyphenation, +optimizing page breaks, and placing tables and figures. + + +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\LoadCommonFile{options}% \section{Early or Late Selection of Options} + +\LoadCommonFile{compatibility}% \section{Compatibility with Earlier Versions of KOMA-Script} + +\LoadCommonFile{draftmode}% \section{Draft Mode} + +\LoadCommonFile{typearea}% \section{Page Layout} + +\begin{Declaration} + \Macro{flushbottom} + \Macro{raggedbottom} +\end{Declaration} +\begin{Explain} + In two-sided documents especially, it is preferable to have the same visual + baseline not only for the first lines of each text area in a two-page spread + but also for the last lines. If a page consists only of text without + paragraphs or headings, this is generally the result. But a paragraph + spacing of half a line would be enough to prevent you from achieving this + goal if the number of paragraphs on each page of the two-page spread differs + by an odd number. In this case, at least some of the paragraph distances + need to be stretched or shrunk to reach the target again. \TeX{} defines + stretchable and shrinkable distances for this purpose, and \LaTeX{} lets you + perform this kind of \emph{vertical adjustment}\Index{adjustment} + automatically. +\end{Explain} + +Using two-sided printing with the +\Option{twoside}\IndexOption{twoside}\important{\Option{twoside}} option (see +\autoref{sec:typearea.options}, \DescPageRef{typearea.option.twoside}) or +two-column formatting with the +\Option{twocolumn}\IndexOption{twocolumn}\important{\Option{twocolumn}} option +(see \DescPageRef{typearea.option.twocolumn}) also activates this vertical +adjustment. But\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} this does not apply with a compatibility setting for a +\KOMAScript{} version prior to 3.17 (see +\autoref{sec:\LabelBase.compatibilityOptions}, +\DescPageRef{\LabelBase.option.version}, option +\DescRef{\LabelBase.option.version}\IndexOption{version}% +\important{\OptionValueRef{\LabelBase}{version}{3.17}}) if you use +\DescRef{\LabelBase.cmd.KOMAoption} or \DescRef{\LabelBase.cmd.KOMAoptions} to +change the setting of these options. + +You can also explicitly request vertical adjustment at any time starting with +the current page by using \Macro{flushbottom}. \Macro{raggedbottom} has the +opposite effect, switching off vertical adjustment starting with the current +page. This corresponds to the default for one-sided printing. + +By the way, \KOMAScript{} uses a slightly modified method for adjusting the +vertical skip. This has been done to move footnotes to the bottom of the +text area instead of having them close to the last text line used. +\iffree{}{ + You can find more information about this at + \autoref{sec:maincls-experts.addInfos}, + \DescPageRef{maincls-experts.cmd.footnoterule}.}% +% +\EndIndexGroup +% +\EndIndexGroup + + +\LoadCommonFile{fontsize}% \section{Choosing the Document Font Size} + +\LoadCommonFile{textmarkup}% \section{Text Markup} + +\LoadCommonFile{titles}% \section{Document Titles} + +\section{Abstract} +\seclabel{abstract} +\BeginIndexGroup +\BeginIndex{}{abstract}% + +Particularly with articles, more rarely with reports, there is an abstract, or +summary, directly beneath the title and before the table of contents. When +using an in-page title, this abstract is normally a kind of left- and +right-indented block. In comparison, the abstract appears as a chapter or +section when using title pages. + +\begin{Declaration} + \OptionVName{abstract}{simple switch} +\end{Declaration}% +In\OnlyAt{\Class{scrreprt}\and\Class{scrartcl}} the standard +classes\textnote{\KOMAScript{} vs. standard classes}, the +\DescRef{\LabelBase.env.abstract} environment sets the text ``\abstractname'' +centred before the abstract text. This used to be the normal practice. Since +then, reading newspapers has trained us to recognize a suitably highlighted +text at the beginning of an article or report as the abstract. This is even +more true when the text comes before the table of contents. It is also +confusing if, of all things, this title appears small and centred. +{\KOMAScript}\ChangedAt{v3.00}{\Class{scrreprt}\and \Class{scrartcl}} offers +the option to include or exclude the abstract's title with the +\Option{abstract} option. For \PName{simple switch}, you can use any value +from \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. The +default for \KOMAScript{} is \PValue{false}. + +Books typically use a different kind of summary. There, you usually place an +appropriate chapter at the beginning or the end of the work. This chapter is +often combined with either the introduction or a description of a larger +prospectus. Therefore, the \Class{scrbook} class has no +\DescRef{\LabelBase.env.abstract} environment. A\textnote{Hint!} summary +chapter is also recommended for reports in a wider sense, such as a Master's +thesis or Ph.D. dissertation. See the commands +\DescRef{\LabelBase.cmd.chapter*}\IndexCmd{chapter*}, +\DescRef{\LabelBase.cmd.addchap}\IndexCmd{addchap}, and +\DescRef{\LabelBase.cmd.addchap*}\IndexCmd{addchap*} documented in +\autoref{sec:maincls.structure}, from \DescPageRef{\LabelBase.cmd.chapter*}.% +\EndIndexGroup + + +\begin{Declaration} + \begin{Environment}{abstract}\end{Environment} +\end{Declaration}% +\OnlyAt{\Class{scrartcl}\and \Class{scrreprt}}% +Some {\LaTeX} classes provide a special environment for this summary: the +\Environment{abstract} environment. This is output directly, so it is not part +of the title created with \DescRef{\LabelBase.cmd.maketitle}. +Please\textnote{Attention!} note that \Environment{abstract} is an +environment, not a command. Whether the abstract has a heading or not is +determined by the \DescRef{\LabelBase.option.abstract} option (see above). + +For books, the abstract is usually part of the introduction or a separate +chapter at the end of the document. Therefore \Class{scrbook} does not provide +an \Environment{abstract} environment. When using the \Class{scrreprt} class, +it is definitely worth considering whether to proceed in the same way. See the +commands \DescRef{\LabelBase.cmd.chapter*}\IndexCmd{chapter*} and +\DescRef{\LabelBase.cmd.addchap}\IndexCmd{addchap}, or +\DescRef{\LabelBase.cmd.addchap*} in \autoref{sec:\LabelBase.structure} +from \DescPageRef{\LabelBase.cmd.chapter*} for more on this. + +When using an in-page title\Index{title>in-page} (see option +\DescRef{\LabelBase.option.titlepage}, \autoref{sec:\LabelBase.titlepage}, +\DescPageRef{\LabelBase.option.titlepage}), the abstract is set internally +using the \DescRef{\LabelBase.env.quotation}\IndexEnv{quotation} environment +(see \autoref{sec:\LabelBase.lists}, \DescPageRef{\LabelBase.env.quotation}). +This way paragraphs will be set with the first line indented. If the first +paragraph of the abstract should not be indented, you can suppress this indent +by using \Macro{noindent}\IndexCmd{noindent}% +\important{\Macro{noindent}} \iffree{just after + \Macro{begin}\PParameter{abstract}}{at the beginning of the environment}.% +% +\EndIndexGroup +% +\EndIndexGroup + + +\section{Table of Contents} +\seclabel{toc} +\BeginIndexGroup +\BeginIndex{}{table of contents} + +The title and optional abstract are normally followed by a table of contents. +Often you also find additional lists of the floating environments, such as +tables and figures, after the table of contents (see +\autoref{sec:\LabelBase.floats}). + +\iffalse% + Note that in addition to the options documented in this section, the + commands \DescRef{maincls-experts.cmd.DeclareSectionCommand}, + \DescRef{maincls-experts.cmd.DeclareNewSectionCommand}, + \DescRef{maincls-experts.cmd.RedeclareSectionCommand}, and + \DescRef{maincls-experts.cmd.ProvideSectionCommand} can also affect the + table of contents. See \autoref{sec:maincls-experts.experts}, + \DescPageRef{maincls-experts.cmd.DeclareSectionCommand}.% +\else% + In addition to the options documented in this section, the + \hyperref[cha:tocbasic]{\Package{tocbasic}}% + \important{\hyperref[cha:tocbasic]{\Package{tocbasic}}}% + \IndexPackage{tocbasic} package style selected and configured with + \DescRef{tocbasic.cmd.DeclareTOCStyleEntry}\IndexCmd{DeclareTOCStyleEntry}% + \important[O]{\DescRef{tocbasic.cmd.DeclareTOCStyleEntry}} (see + \DescPageRef{tocbasic.cmd.DeclareTOCStyleEntry}) also has a significant + impact on the appearance of the table of contents. Similarly, the commands + \DescRef{maincls-experts.cmd.DeclareSectionCommand}% + \important[O]{\DescRef{maincls-experts.cmd.DeclareSectionCommand}}% + \IndexCmd{DeclareSectionCommand}, + \DescRef{maincls-experts.cmd.ProvideSectionCommand}% + \IndexCmd{ProvideSectionCommand}, + \DescRef{maincls-experts.cmd.DeclareNewSectionCommand}% + \IndexCmd{DeclareNewSectionCommand} and + \DescRef{maincls-experts.cmd.RedeclareSectionCommand}% + \IndexCmd{RedeclareSectionCommand} documented in + \autoref{sec:maincls-experts.experts}, + \DescPageRef{maincls-experts.cmd.DeclareSectionCommand} can also affect the + table of contents.% +\fi + + +\begin{Declaration} + \OptionVName{toc}{setting} +\end{Declaration} +It is becoming increasingly common to to include lists of tables and figures, +the bibliography, and sometimes even the index in the table of contents. This +is surely related to the recent trend of putting lists of figures and tables +at the end of the document. Both lists are similar to the table of contents in +structure and intention. I'm therefore sceptical of this evolution. +Since\important{\OptionValue{toc}{listof}} it makes no sense to include only +the list of tables or that of figures in the table of contents without the +other, there is only one \PName{setting}\ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} +\PValue{listof}\IndexOption{toc~=\textKValue{listof}}, which causes entries +for both types of lists to be included. This also includes any lists produced +with version~1.2e or later of the \Package{float} package\IndexPackage{float} +from Version~1.2e (see \cite{package:float}) or \Package{floatrow} (see +\cite{package:floatrow}). None\important{\OptionValue{toc}{listofnumbered}} +of these lists are generally given a chapter number. If you want to ignore +this principle, use the \PName{setting} +\PValue{listofnumbered}\IndexOption{toc~=\textKValue{listofnumbered}}. + +\leavevmode\LabelOptionValue{toc}{index}\nobreak +The\important{\OptionValue{toc}{index}} +\OptionValue{toc}{index}\IndexOption{toc~=\textKValue{index}} option causes an +entry for the index to be included in the table of contents. The index is +unnumbered since it too only includes references to the contents of the other +sectioning levels. Despite\ChangedAt{v3.18}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} +\important{\OptionValue{toc}{indexnumbered}} the author's concerns, +\KOMAScript{} does support deviating from this principle with +\OptionValue{toc}{indexnumbered}\IndexOption{toc~=\textKValue{indexnumbered}}. + +\leavevmode\LabelOptionValue{toc}{bibliography}\nobreak The bibliography is a +slightly different kind of listing. It does not list the contents of the +present document but refers instead to external sources. +For\important{\OptionValue{toc}{bibliographynumbered}} that reason, it could +be argued that it qualifies as a chapter (or section) and, as such, should be +numbered. The \OptionValue{toc}{bibliographynumbered}% +\IndexOption{toc~=\textKValue{bibliographynumbered}} option has this effect, +and puts the appropriate entry in the table of contents. However, I think that +this reasoning would lead us to consider even a classic, annotated source list +to be a separate chapter. Moreover, the bibliography is ultimately not +something that you wrote yourself. +Therefore\important{\OptionValue{toc}{bibliography}} the bibliography merits, +at best, an unnumbered entry in the table of contents, and you can achieve +this achieved with +\OptionValue{toc}{bibliography}\IndexOption{toc~=\textKValue{bibliography}}. + +\leavevmode\LabelOptionValue{toc}{graduated}\nobreak +The table of contents is normally\ChangedAt{v2.8q}{% + \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% +\important{\OptionValue{toc}{graduated}} formatted so that different levels of +sectioning commands have different indentations. The number for each level is +set left-justified in a fixed-width field. This default set-up is selected +with the\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} +\OptionValue{toc}{graduated}\IndexOption{toc~=\textKValue{graduated}} option. + +\leavevmode\LabelOptionValue{toc}{flat}\nobreak +If the sectioning level which appears in the table of contents is too deep, the +number for that level can be so wide that the space reserved for the number is +insufficient. The German FAQ \cite{DANTE:FAQ} suggests redefining the table of +contents in such a case. \KOMAScript{}\important{\OptionValue{toc}{flat}} +offers an alternative format that avoids the problem completely. If you use +the \OptionValue{toc}{flat}\IndexOption{toc~=\textKValue{flat}} option, no +graduated indentation is applied to the headings of the sectioning levels. +Instead, a table-like organisation is used, where all sectioning numbers and +headings are set in a left-justified column. The space necessary for the +section numbers is thus determined automatically. + +You can find an overview of all available values for the \PName{setting} of +\Option{toc}. in \autoref{tab:\LabelBase.toc}. + +\begin{desclist} + \desccaption[{Available values for the \Option{toc} option}]{% + Available values for the \Option{toc} option to set the format and contents + of the table of contents\label{tab:\LabelBase.toc}% + }{% + Available values for the \Option{toc} option (\emph{continued})% + }% + \entry{\PValue{bibliography}, \PValue{bib}}{% + The bibliography has an unnumbered entry in the table of contents.% + \IndexOption{toc~=\textKValue{bibliography}}}% + \entry{\PValue{bibliographynumbered}, \PValue{bibnumbered}, + \PValue{numberedbibliography}, \PValue{numberedbib}}{% + The bibliography has a numbered entry in the table of contents.% + \IndexOption{toc~=\textKValue{bibliographynumbered}}}% + \entry{\PValue{chapterentrywithdots}, \PValue{chapterentrydotfill}}{% + \ChangedAt[2014/12]{v3.15}{\Class{scrbook}\and \Class{scrreprt}}% + The chapter entries for the \Class{scrbook} and \Class{scrreprt} classes + also use dots to separate the heading text from the page numbers.% + \IndexOption{toc~=\textKValue{chapterentrywithdots}}}% + \entry{\PValue{chapterentrywithoutdots}, \PValue{chapterentryfill}}{% + \ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}}% + The chapter entries of the \Class{scrbook} and \Class{scrreprt} classes + use white space to separate the heading text from the page numbers. This + corresponds to the default setting.% + \IndexOption{toc~=\textKValue{chapterentrywithoutdots}}}% + \entry{\PValue{flat}, \PValue{left}}{% + The table of contents is set in table form. The numbers of the headings + are in the first column, the heading text in the second column, and the + page number in the third column. The amount of space needed for the + numbers of the headings is determined by the required amount of space + detected during the previous \LaTeX{} run.% + \IndexOption{toc~=\textKValue{flat}}}% + \entry{\PValue{graduated}, \PValue{indent}, \PValue{indented}}{% + The table of contents is set in hierarchical form. The amount of space for + the heading numbers is limited. This corresponds to the default setting.% + \IndexOption{toc~=\textKValue{graduated}}}% + \entry{\PValue{indenttextentries}, \PValue{indentunnumbered}, + \PValue{numberline}}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The \PValue{numberline} property (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.setuptoc}) is set for the table of contents. As + a result, unnumbered entries are left aligned with the text of numbered + entries of the same level.% + \IndexOption{toc~=\textKValue{numberline}}}% + \entry{\PValue{index}, \PValue{idx}}{% + The index has an unnumbered entry in the table of contents.% + \IndexOption{toc~=\textKValue{index}}}% + \entry{\PValue{indexnumbered}}{% + \ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The index has a numbered entry in the table of contents.% + \IndexOption{toc~=\textKValue{index}}}% + \entry{\PValue{leftaligntextentries}, \PValue{leftalignunnumbered}, + \PValue{nonumberline}}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The \PValue{numberline} property (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.setuptoc}) is deleted for the table of contents. + This places unnumbered entries left-aligned with the number of + numbered entries of the same level. This corresponds to the default + setting.% + \IndexOption{toc~=\textKValue{numberline}}}% + \pventry{listof}{% + The lists of floating environments, e.\,g. figures and tables, have + unnumbered entries in the table of contents.% + \IndexOption{toc~=\textKValue{listof}}}% + \entry{\PValue{listofnumbered}, \PValue{numberedlistof}}{% + The lists of floating environments, e.\,g. figures and tables, have + numbered entries in the table of contents.% + \IndexOption{toc~=\textKValue{listofnumbered}}}% + \entry{\PValue{nobibliography}, \PValue{nobib}}{% + The bibliography does not have an entry in the table of contents. This + corresponds to the default setting.% + \IndexOption{toc~=\textKValue{nobibliography}}}% + \entry{\PValue{noindex}, \PValue{noidx}}{% + The index does not have an entry in the table of contents. This + corresponds to the default setting.% + \IndexOption{toc~=\textKValue{noindex}}}% + \pventry{nolistof}{% + The lists of floating environments, e.\,g. figures and tables, do not + have entries in the table of contents. This corresponds to the default + setting.% + \IndexOption{toc~=\textKValue{nolistof}}}% + \entry{\PValue{sectionentrywithdots}, \PValue{sectionentrydotfill}}{% + \ChangedAt[2014/12]{v3.15}{\Class{scrartcl}}% + The section entries of the \Class{scrartcl} class also use dots to + separate the heading text from the page numbers.% + \IndexOption{toc~=\textKValue{sectionentrywithdots}}}% + \entry{\PValue{sectionentrywithoutdots}, \PValue{sectionentryfill}}{% + \ChangedAt{v3.15}{\Class{scrartcl}}% + The section entries of the \Class{scrartcl} class use white space to + separate the heading text from the page number. This corresponds to the + default setting.% + \IndexOption{toc~=\textKValue{sectionentrywithoutdots}}}% +\end{desclist} +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{chapterentrydots}{simple switch}\\ + \OptionVName{sectionentrydots}{simple switch} +\end{Declaration} +These\ChangedAt[2014/12]{v3.15}{\Class{scrbook}\and \Class{scrreprt}} options +configure a dotted connecting line between the text and page number of the +chapter entries for the \Class{scrbook} and +\Class{scrreprt}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} classes, or for +the section entries of the \Class{scrartcl}\OnlyAt{\Class{scrartcl}} class, in +the table of contents. For the \PName{simple switch}, you can use any value from +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. +The default is \PValue{false}. It selects an empty gap instead of dots. + +\BeginIndex{FontElement}{chapterentrydots}\LabelFontElement{chapterentrydots}% +\BeginIndex{FontElement}{sectionentrydots}\LabelFontElement{sectionentrydots}% +If a dotted line is used, you can change its font using the element +\FontElement{chapterentrydots}% +\important[i]{\FontElement{chapterentrydots}\\ + \FontElement{sectionentrydots}} or \FontElement{sectionentrydots}. The font +also depends on the element of the page number of the entry (see also +\DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont}, \autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}, as well as +\autoref{tab:maincls.fontelements}, +\autopageref{tab:maincls.fontelements}). The defaults of the elements are +shown in \autoref{tab:maincls.tocelements}, from +\autopageref{tab:maincls.tocelements}. Note\textnote{Attention!} that the dots +of all entries will be equally spaced only if all dots use the same font.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{tableofcontents} +\end{Declaration}% +The table of contents is output by the \Macro{tableofcontents} command. To get +correct values in the table of contents requires at least two {\LaTeX} runs +after every change. The \DescRef{\LabelBase.option.toc} option described above +can also affect the extent and format of the table of contents. After changing +the settings of this option, at least two \LaTeX{} runs are needed again. + +Entries for \DescRef{\LabelBase.cmd.chapter}\IndexCmd{chapter} with +\Class{scrbook}\IndexClass{scrbook} and \Class{scrreprt}\IndexClass{scrreprt}, +or \DescRef{\LabelBase.cmd.section}\IndexCmd{section} with +\Class{scrartcl}\IndexClass{scrartcl}, and the sectioning level +\DescRef{\LabelBase.cmd.part}\IndexCmd{part} are not indented. Additionally, +there are no dots between the text of this heading and the page number. The +typographical logic for this behaviour is that the font is usually distinct +and appropriate emphasis is desirable. +However\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}, you can change this behaviour with the previously +documented options. The table of contents of this \iffree{guide}{book} is +created with the default settings and serves as an example. + +\BeginIndex{FontElement}{partentry}\LabelFontElement{partentry}% +\BeginIndex{FontElement}{chapterentry}\LabelFontElement{chapterentry}% +\BeginIndex{FontElement}{sectionentry}\LabelFontElement{sectionentry}% +The\ChangedAt{v2.97c}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\important{\FontElement{partentry}\\ + \FontElement{chapterentry}\\ + \FontElement{sectionentry}} font style of the top two levels in the table of +contents is also affected by the settings for the \FontElement{partentry} +element, as well as by the \FontElement{chapterentry} element for the +\Class{scrbook} and \Class{scrreprt} classes, and by the +\FontElement{sectionentry} element for the \Class{scrartcl} class. +\BeginIndex{FontElement}{partentrypagenumber}% +\LabelFontElement{partentrypagenumber}% +\LabelFontElement{pagination}% +\BeginIndex{FontElement}{chapterentrypagenumber}% +\LabelFontElement{chapterentrypagenumber}% +\BeginIndex{FontElement}{sectionentrypagenumber}% +\LabelFontElement{sectionentrypagenumber}% +You can set the font style of the page numbers separately from these elements +using \FontElement{partentrypagenumber}% +\important{\FontElement{partentrypagenumber}} and +\FontElement{chapterentrypagenumber}% +\important{\FontElement{chapterentrypagenumber}\\ + \FontElement{sectionentrypagenumber}}\,---\,for \Class{scrbook} and +\Class{scrreprt}\,---\,or \FontElement{sectionentrypagenumber}\,---\,for +\Class{scrartcl}\,---\, (see \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} in \autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}, or +\autoref{tab:maincls.fontelements}, \autopageref{tab:maincls.fontelements}). +If\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} you use dotted lines connecting the heading entries +(chapter or section depending on the class) to the page numbers using the +\DescRef{\LabelBase.option.toc}% +\IndexOption{toc~=\textKValue{chapterentrywithdots}}% +\IndexOption{toc~=\textKValue{sectionentrywithdots}} +\DescRef{\LabelBase.option.chapterentrydots}% +\IndexOption{chapterentrydots~=\PName{simple switch}} or +\DescRef{\LabelBase.option.sectionentrydots}% +\IndexOption{sectionentrydots~=\PName{simple switch}} option, you can change +their font style using the \DescRef{\LabelBase.fontelement.chapterentrydots}% +\IndexFontElement{chapterentrydots}% +\important{\DescRef{\LabelBase.fontelement.chapterentrydots}\\ + \DescRef{\LabelBase.fontelement.sectionentrydots}} and +\DescRef{\LabelBase.fontelement.sectionentrydots}% +\IndexFontElement{sectionentrydots} elements. The defaults for these +elements are found in \autoref{tab:maincls.tocelements}. +\begin{table} +% \centering +% \caption + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% + \begin{captionbeside} + [Default font styles for the elements of the table of contents] + {\label{tab:maincls.tocelements}% + Default font styles for the elements of the table of contents} + [l] + \setlength{\tabcolsep}{.9\tabcolsep}% Umbruchoptimierung! + \begin{tabular}[t]{ll} + \toprule + Element & Default font style \\ + \midrule + \FontElement{partentry} & + \DescRef{\LabelBase.cmd.usekomafont}\PParameter{disposition}\Macro{large} \\ + \FontElement{partentrypagenumber} & \\ + \FontElement{chapterentry} & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{disposition}\\ + \FontElement{chapterentrydots} & \Macro{normalfont} \\ + \FontElement{chapterentrypagenumber} & \\ + \FontElement{sectionentry} & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{disposition} \\ + \FontElement{sectionentrydots} & \Macro{normalfont} \\ + \FontElement{sectionentrypagenumber} & \\ + \bottomrule + \end{tabular} + \end{captionbeside} +\end{table} +% +\EndIndexGroup + + +\begin{Declaration} + \Counter{tocdepth} + \Macro{parttocdepth} + \Macro{sectiontocdepth} + \Macro{subsectiontocdepth} + \Macro{subsubsectiontocdepth} + \Macro{paragraphtocdepth} + \Macro{subparagraphtocdepth} +\end{Declaration}% +Normally, the sectioning divisions included in the table of contents are all +those from \DescRef{\LabelBase.cmd.part} to +\DescRef{\LabelBase.cmd.subsection} for the \Class{scrbook} and +\Class{scrreprt} classes, or from \DescRef{\LabelBase.cmd.part} to +\DescRef{\LabelBase.cmd.subsubsection} for the \Class{scrartcl} class. Whether +or not to include a sectioning level in the table of contents is controlled by +the \Counter{tocdepth} counter. This has the value -1 for +\DescRef{\LabelBase.cmd.part}, 0 for \DescRef{\LabelBase.cmd.chapter}, and so +on. By incrementing or decrementing the counter, you can choose the lowest +sectioning level to include in the table of contents. Incidentally, the +standard classes work the same way. +Unlike\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\textnote{\KOMAScript{} vs. standard classes} with the +standard classes, with \KOMAScript{} you do not need to remember these values. +\KOMAScript{} defines a \Macro{\PName{level}tocdepth} command for each +sectioning level with the appropriate value which you can use to set +\Counter{tocdepth}. + +Please note\textnote{Attention!} that in +\Class{scrartcl}\OnlyAt{\Class{scrartcl}}, the values of \Counter{tocdepth} +and \DescRef{\LabelBase.counter.secnumdepth}\IndexCounter{secnumdepth} (see +\autoref{sec:\LabelBase.structure}, +\DescPageRef{\LabelBase.counter.secnumdepth}) for +\DescRef{\LabelBase.cmd.part} are not the same. This behaviour was copied from +the standard \Class{article} class for compatibility. Thus, for example, you +should not use \DescRef{\LabelBase.cmd.partnumdepth}\IndexCmd{partnumdepth} to +set the value of \Counter{tocdepth}.% +\begin{Example} + Suppose you are preparing an article that uses the sectioning level + \DescRef{\LabelBase.cmd.subsubsection}. However, you do not want this + sectioning level to appear in the table of contents. The preamble of your + document might contain the following: +\begin{lstcode} + \documentclass{scrartcl} + \setcounter{tocdepth}{\subsectiontocdepth} +\end{lstcode} + Thus you set the \Counter{tocdepth} counter to the value of the + \Macro{subsectiontocdepth} command. That value is normally 2, but this way, + you do not have to remember it. + + If instead you simply want to include one less level in the table of + contents than you normally would, you can simply subtract one from the + default value of \Counter{tocdepth}: +\begin{lstcode} + \documentclass{scrartcl} + \addtocounter{tocdepth}{-1} +\end{lstcode} + The\textnote{Hint!} value that you need to add to or subtract from + \Counter{tocdepth} is listed in the table of contents after at least two + \LaTeX{} runs. +\end{Example}% +\EndIndexGroup +% +\EndIndexGroup + + +\LoadCommonFile{parmarkup}% \section{Paragraph Markup} + +\LoadCommonFile{oddorevenpage}% \section{Detecting Odd or Even Pages} + + +\section{Headers and Footers Using Predefined Page Styles} +\seclabel{pagestyle} + +\BeginIndexGroup +\BeginIndex{}{page>style}% +One of the general characteristics of a document is the page style. In +\LaTeX{} this primarily consists of the contents of headers and footers. + + +\begin{Declaration} + \OptionVName{headsepline}{simple switch} + \OptionVName{footsepline}{simple switch} +\end{Declaration}% +You\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} can use these options to specify whether a horizontal rule +appears beneath the header or above the footer. You can use any of the values +for simple switches shown in \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch}. Setting the \Option{headsepline} option to +true or invoking it with no value results in a line beneath the header. +Similarly, activating the \Option{footsepline} option results in a rule above +the footer. Deactivating either option switches off the respective rule. + +The\textnote{Attention!} \Option{headsepline} option naturally has no effect +with the \DescRef{\LabelBase.pagestyle.empty} and +\DescRef{\LabelBase.pagestyle.plain} page styles, which are described below, +because these styles explicitly dispense with a header\Index{page>header}. +Typographically, such a line has the effect of making the header appear to be +closer to the text. This does not mean that the header then needs to be moved +farther away from the body of the text\Index{text>body}. Instead, the header +should be considered as belonging to the text body for the purpose of +calculating the type area. \KOMAScript{} takes this into account by passing +the \Option{headsepline} option to the +\hyperref[cha:typearea]{\Package{typearea}}% +\important{\hyperref[cha:typearea]{\Package{typearea}}}\IndexPackage{typearea} +package, which then automatically executes the package option +\DescRef{typearea.option.headinclude}% +\IndexOption{headinclude}\important{\DescRef{typearea.option.headinclude}} +with the same value. The same applies to the footer separation line. Unlike +\Option{headsepline}, the \Option{footsepline} option also affects the +\PValue{plain} page style because \PValue{plain} prints a page number in the +footer. + +The options themselves do not automatically recalculate the type area. To +recalculate it, use the \DescRef{typearea.option.DIV} option with the values +\hyperref[desc:typearea.option.DIV.last]{\PValue{last}} or +\hyperref[desc:typearea.option.DIV.current]{\PValue{current}} (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}) offers further possibilities for +adjusting lines in headers and footers.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{pagestyle}\Parameter{page style} + \Macro{thispagestyle}\Parameter{local page style} +\end{Declaration}% +There are usually four different page styles: +\begin{description} +\item[{\PageStyle{empty}% + \BeginIndex[indexmain]{Pagestyle}{empty}\LabelPageStyle{empty}}] is the + page style with completely empty headers and footers. In {\KOMAScript} + this is identical to the standard classes.% +\item[{\PageStyle{headings}% + \BeginIndex[indexmain]{Pagestyle}{headings}\LabelPageStyle{headings}}] is + the page style with running heads in the header. In this style, headings are + automatically\Index[indexmain]{running heads>automatic} inserted into the + header. \OnlyAt{\Class{scrbook}\and\Class{scrreprt}}% + With the classes \Class{scrbook}\IndexClass{scrbook} and + \Class{scrreprt}\IndexClass{scrreprt}, the headings of chapters and sections + are repeated in the header for two-sided printing\,---\,on the outer side + with {\KOMAScript}\textnote{\KOMAScript{} vs. standard classes}, on the + inner side with the standard classes. {\KOMAScript} puts the page number on + the outer side of the footer; the standard classes put it on the inner side + of the header. In one-sided printing, {\KOMAScript} uses only the chapter + headings, which are centred in the header, and puts the page numbers centred + in the footer. + \OnlyAt{\Class{scrartcl}}\Class{scrartcl}\IndexClass{scrartcl} behaves + similarly but starts one a level deeper in the sectioning hierarchy, with + sections and subsections, because the chapter level does not exist in this + case. + + While the standard classes\textnote{\KOMAScript{} vs. standard classes} + automatically convert the running heads to upper-case letters, + {\KOMAScript} uses the capitalisation found in the headings. There are + several typographical reasons for this. Upper-case letters are actually far + too massive as a text decoration. If you use them anyway, they should be set + one point smaller and with slightly tighter spacing. The standard classes do + not take these points into consideration. + + In addition, the {\KOMAScript} classes support rules below the header and + above the footer with the \DescRef{\LabelBase.option.headsepline} and + \DescRef{\LabelBase.option.footsepline} options (see + \DescPageRef{\LabelBase.option.headsepline}).% +\item[{\PageStyle{myheadings}% + \BeginIndex[indexmain]{Pagestyle}{myheadings}\LabelPageStyle{myheadings}}] + mostly corresponds to the \PValue{headings} page style, but the running + heads are not generated automatically% + \Index[indexmain]{running heads>manual}\,---\,they have to be defined by the + user. You can use the \DescRef{\LabelBase.cmd.markboth}\IndexCmd{markboth} + and \DescRef{\LabelBase.cmd.markright}\IndexCmd{markright}\important{% + \DescRef{\LabelBase.cmd.markboth}\\ + \DescRef{\LabelBase.cmd.markright}} commands for that purpose (see + \DescPageRef{\LabelBase.cmd.markright}). +\item[{\PageStyle{plain}% + \BeginIndex[indexmain]{Pagestyle}{plain}\LabelPageStyle{plain}}] is the + page style with no running head\Index{running head} and only a page number% + \Index{page>number} in the footer. The\textnote{\KOMAScript{} vs. standard + classes} standard classes always centre this page number in the footer. + {\KOMAScript} puts the page number on the outer side of the footer in + two-sided\Index{two-sided} mode. {\KOMAScript} behaves like the + standard classes in one-sided printing.% +\end{description} + +You\important{\Macro{pagestyle}} can set the page style at any time with the +help of the \Macro{pagestyle} command, and this setting takes effect with the +next page that is output. If\textnote{Hint!} you use \Macro{pagestyle} just +before a command that results in an implicit page break and if the new page +style should be used on the resulting new page, a +\DescRef{\LabelBase.cmd.cleardoublepage} just before \Macro{pagestyle} will be +useful. But usually you set the page style only once, at the beginning of the +document or in the preamble. + +To\important{\Macro{thispagestyle}} change the page style of the current page +only, use the \Macro{thispagestyle} command. This occurs automatically at some +points in the document. For example, the +\Macro{thispagestyle}\PParameter{\DescRef{\LabelBase.cmd.chapterpagestyle}} +command is issued implicitly on the first page of a chapter. + +Note\textnote{Attention!} that when you use the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} +package, switching between automatic and manual running heads is no longer +accomplished by changing the page styles but with special instructions. You +should not use the \PValue{headings} and \PValue{myheadings} page styles with +this package. + +\BeginIndexGroup \BeginIndex[indexother]{}{font>style}% +\BeginIndex{FontElement}{pageheadfoot}\LabelFontElement{pageheadfoot}% +\LabelFontElement{pagehead}% +\BeginIndex{FontElement}{pagefoot}\LabelFontElement{pagefoot}% +\BeginIndex{FontElement}{pagenumber}\LabelFontElement{pagenumber}% +To change the font style used for the header, the footer, or the page +number\ChangedAt{v2.8p}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}, use the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see +\autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}). The same element, +\FontElement{pageheadfoot}\IndexFontElement{pageheadfoot}% +\important{\FontElement{pageheadfoot}}, is used for the header and the footer. +The element for the page number within the header or footer is called +\FontElement{pagenumber}\IndexFontElement{pagenumber}% +\important{\FontElement{pagenumber}}. The +\FontElement{pagefoot}\IndexFontElement{pagefoot}% +\important{\FontElement{pagefoot}} element, which is also provided by the +\KOMAScript{} classes, is used only if you define a page style with the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage} package in which the footer contains text (see +\autoref{cha:scrlayer-scrpage}, +\DescPageRef{scrlayer-scrpage.fontelement.pagefoot}). + +You can find the default settings in +\autoref{tab:\LabelBase.defaultFontsHeadFoot}. +% +\begin{table} +% \centering% +% \caption + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% +% \addtokomafont{caption}{\raggedright}% + \begin{captionbeside} + [{Default values for page style elements}] + {\label{tab:maincls.defaultFontsHeadFoot}% + \hspace{0pt plus 1ex}% + Default values for page style elements} + [l] + \begin{tabular}[t]{ll} + \toprule + Element & Default \\ + \midrule + \FontElement{pagefoot}\IndexFontElement{pagefoot} & + \\ + \FontElement{pageheadfoot}\IndexFontElement{pageheadfoot} & + \Macro{normalfont}\Macro{normalcolor}\Macro{slshape} \\ + \FontElement{pagenumber}\IndexFontElement{pagenumber} & + \Macro{normalfont}\Macro{normalcolor}\\ + \bottomrule + \end{tabular} + \end{captionbeside} +\end{table} +% +\begin{Example} + \leavevmode\phantomsection\xmpllabel{cmd.pagestyle}% + Suppose you want to set header and footer in a smaller type size + and in italics. However, the page number should not be set in + italics but in bold. Apart from the fact that the result will look + horrible, you can do this as follows: +\begin{lstcode} + \setkomafont{pageheadfoot}{% + \normalfont\normalcolor\itshape\small} + \setkomafont{pagenumber}{\normalfont\bfseries} +\end{lstcode} + On the other hand, if you only want a smaller font to be used along with the + default slanted text, you can use the following: +\begin{lstcode} + \addtokomafont{pagehead}{\small} +\end{lstcode} + As you can see, the previous example uses the + \FontElement{pagehead}\important{\FontElement{pagehead}} element. You can + achieve the same result using \PValue{pageheadfoot} instead (see + \autoref{tab:\LabelBase.fontelements} on + \autopageref{tab:\LabelBase.fontelements}). +\end{Example} +It is not possible to use these methods to force upper-case letters to be used +automatically for the running heads. Although you can redefine +\DescRef{tocbasic.cmd.MakeMarkcase}\IndexCmd{MakeMarkcase}, in such cases you +should instead use the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} package (see +\autoref{cha:scrlayer-scrpage}, +\DescPageRef{scrlayer-scrpage.option.markcase}). + +If\textnote{Hint!} you define your own page styles, the commands +\DescRef{\LabelBase.cmd.usekomafont}\PParameter{pageheadfoot}, +\DescRef{\LabelBase.cmd.usekomafont}\PParameter{pagenumber}, and +\DescRef{\LabelBase.cmd.usekomafont}\PParameter{pagefoot} can be useful. In +particular, if you do not use the {\KOMAScript} package +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} (see +\autoref{cha:scrlayer-scrpage}) but use, for example, the +\Package{fancyhdr}\IndexPackage{fancyhdr}\important{\Package{fancyhdr}} +package (see \cite{package:fancyhdr}), you can use these commands in your +definitions. In this way you can maintain compatibility with {\KOMAScript} as +much as possible. If you do not use these commands in your own definitions, +changes such as those shown in the previous examples have no effect. The +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage} package tries to maintain maximum +compatibility as long as, for example, +\iffree{\Macro{thepage}}{\DescRef{\LabelBase-experts.cmd.thepage}}% +\IndexCmd{thepage} is not used directly for the page number rather than the +\iffree{\Macro{pagemark}}{\DescRef{\LabelBase-experts.cmd.pagemark}}% +\IndexCmd{pagemark} which is provided for it.% +\EndIndexGroup +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{markboth}\Parameter{left mark}\Parameter{right mark} + \Macro{markright}\Parameter{right mark} +\end{Declaration} +The \DescRef{\LabelBase.pagestyle.myheadings}% +\important{\DescRef{\LabelBase.pagestyle.myheadings}}% +\IndexPagestyle{myheadings} page style does not set the running head. Instead, +you set it with the help of the \Macro{markboth} and \Macro{markright} +commands. This way the \PName{left mark} will normally be used in the header +of even pages and \PName{right mark} in the header of odd pages. With +one-sided printing, only the \PName{right mark} exists. With the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} +package, the \DescRef{scrlayer-scrpage.cmd.markleft}% +\IndexCmd{markleft}\important{\DescRef{scrlayer-scrpage.cmd.markleft}} command +is also available. + +You can use these commands with other page styles too. However, when combined +with automatic running heads, for example with the +\DescRef{\LabelBase.pagestyle.headings}\IndexPagestyle{headings} page style, +the effect of the commands lasts only until the next time the respective marks +are set automatically.% +% +\EndIndexGroup + +\begin{Declaration} + \Macro{titlepagestyle} + \Macro{partpagestyle} + \Macro{chapterpagestyle} + \Macro{indexpagestyle} +\end{Declaration}% +\Index{title>page style}% +\Index{part>page style}% +\Index{chapter>page style}% +\Index{index>page style}% +On some pages, a different page style is chosen automatically with the help of +the \DescRef{\LabelBase.cmd.thispagestyle} command. Which page style this +actually is, is defined by these four macros, of which \Macro{partpagestyle} +and \Macro{chapterpagestyle}\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} are +found only with classes \Class{scrbook} and \Class{scrreprt}, and not in +\Class{scrartcl}. The default value for all four cases is +\DescRef{\LabelBase.pagestyle.plain}\IndexPagestyle{plain}. You can find the +meaning of these macros in \autoref{tab:specialpagestyles}. +% +\begin{table} + \centering + \caption{Macros to set up the page style of special pages} + \label{tab:specialpagestyles} + \begin{desctabular} + \mentry{titlepagestyle}{Page style for a title page when using + \emph{in-page} titles.}% + \mentry{partpagestyle}{Page style for pages with + \DescRef{\LabelBase.cmd.part} titles.}% + \mentry{chapterpagestyle}{Page style for the first page of a chapter.}% + \mentry{indexpagestyle}{Page style for the first page of the index.}% + \end{desctabular} +\end{table} +% +You can redefine the page styles with the \Macro{renewcommand} macro. +\begin{Example} + Suppose you do not want the pages with a \DescRef{\LabelBase.cmd.part} + heading to be numbered. You can use the following command in the preamble of + your document: +\begin{lstcode} + \renewcommand*{\partpagestyle}{empty} +\end{lstcode} + As mentioned previously on \DescPageRef{\LabelBase.pagestyle.empty}, + the \PValue{empty} page style is exactly what is required in this + example. Of course, you can also use a user-defined page style. + + Suppose you have defined your own page style for initial chapter pages with + the \hyperref[cha:scrlayer]{\Package{scrlayer}} (see \autoref{cha:scrlayer}) + or the \hyperref[cha:scrlayer-scrpage-experts]{\Package{scrlayer-scrpage}} + package (see \autoref{cha:scrlayer-scrpage-experts}). You have given this + page style the fitting name of \PValue{chapter}. To actually use this style, + you must redefine \Macro{chapterpagestyle} in this way: +\begin{lstcode} + \renewcommand*{\chapterpagestyle}{chapter} +\end{lstcode} + + Suppose you do not want the table of contents\Index{table of contents}% + \textnote{table of contents} of a book to have page numbers. Everything + after the table of contents, however, should use the \PValue{headings} + page style, including the \PValue{plain} page style for the first + page of every chapter. You can use the following: +\begin{lstcode} + \clearpage + \pagestyle{empty} + \renewcommand*{\chapterpagestyle}{empty} + \tableofcontents + \clearpage + \pagestyle{headings} + \renewcommand*{\chapterpagestyle}{plain} +\end{lstcode} + You can also keep the redefinition local by using a group. This method has + the advantage that you do not need to make any assumptions about the what + the previous page style was in order to restore it after your local change: +\begin{lstcode} + \clearpage + \begingroup + \pagestyle{empty} + \renewcommand*{\chapterpagestyle}{empty} + \tableofcontents + \clearpage + \endgroup +\end{lstcode} + Note,\important{Attention!} however, that you never should put a numbered + sectioning command into a group. Otherwise you may get unpredictable results + with commands like \Macro{label}. + + On \DescPageRef{tocbasic.cmd.AfterTOCHead} in \autoref{sec:tocbasic.toc}, + you will discover the \DescRef{tocbasic.cmd.AfterTOCHead} command, which + makes a solution even easier: +\begin{lstcode} + \AfterTOCHead[toc]{% + \thispagestyle{empty}% + \pagestyle{empty}% + } +\end{lstcode}% + This takes advantage of the fact that if there are several + \DescRef{\LabelBase.cmd.thispagestyle} commands on the same page, the last + one always wins. +\end{Example} + +\begin{Explain} + You might think that you can put running heads on the first page of a + chapter simply by using the +\begin{lstcode} + \renewcommand*{\chapterpagestyle}{headings} +\end{lstcode} + command. Before you try this, you should read \iffree{}{more about the + background to \DescRef{maincls-experts.cmd.rightmark} in + \autoref{sec:maincls-experts.addInfos} on + \DescPageRef{maincls-experts.cmd.rightmark}. Also, }the remarks on + \DescRef{scrlayer-scrpage-experts.cmd.rightfirstmark} starting on page + \DescPageRef{scrlayer-scrpage-experts.cmd.rightfirstmark} in + \autoref{cha:scrlayer-scrpage-experts}, \autoref{part:forExperts} + \iffree{}{provide important information}.% +\end{Explain} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{pagenumbering}\Parameter{numbering style} +\end{Declaration} +This command works the same way in {\KOMAScript} as in the standard classes. +Strictly speaking, it is a feature of neither the standard classes nor the +\KOMAScript{} classes but of the {\LaTeX} kernel. This command is used to +change the \PName{numbering style} of page numbers. + +The changes take effect immediately, i.\,e., starting from the page that +contains the command. If necessary, you should first close the current page +with \DescRef{\LabelBase.cmd.clearpage} or better +\DescRef{\LabelBase.cmd.cleardoubleoddpage}% +\important{\DescRef{\LabelBase.cmd.cleardoubleoddpage}}% +\IndexCmd{cleardoubleoddpage}. You can find the available settings for +\PName{numbering style} in \autoref{tab:numberKind}. +% +\begin{table} + % \centering + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% + % \caption + \begin{captionbeside} + {\label{tab:numberKind}% + Available numbering styles of page numbers} + \begin{tabular}[t]{lll} + \toprule + numbering style & example & description \\ + \midrule + \PValue{arabic} & 8 & Arabic numbers \\ + \PValue{roman} & viii & lower-case Roman numbers \\ + \PValue{Roman} & VIII & upper-case Roman numbers \\ + \PValue{alph} & h & letters \\ + \PValue{Alph} & H & capital letters \\ + \bottomrule + \end{tabular} + \end{captionbeside} +\end{table} + +Calling\textnote{Attention!} \Macro{pagenumbering} always resets the page +number\Index{page>number}. The current page becomes number 1 in the selected +\PName{numbering style}. In order that two-sided documents produce the correct +results on an even page, so that the left-hand page is not missing, you should +always add \DescRef{\LabelBase.cmd.cleardoubleoddpage}% +\important{\DescRef{\LabelBase.cmd.cleardoubleoddpage}}% +\IndexCmd{cleardoubleoddpage} before \Macro{pagenumbering}. The next section +provides more information about potentially inserted blank pages. + +\begin{Explain} + Let me say a word about a common mistake found in various templates + circulating on the Internet. If you encounter lines like the + following\,---\,without the initial comment naturally\,---\,this is an + unmistakable sign that the creator did not read or understand the + remark above: +\begin{lstcode} + % Attention! This example contains errors! + % Please note the explanation in the text! + \tableofcontents + \pagenumbering{arabic} + \setcounter{page}{1} +\end{lstcode} + Since \DescRef{\LabelBase.cmd.tableofcontents} outputs the table of contents + but does not automatically issue a page break at the end, the page numbering + is already changed on the last page of the table of contents. Because it + lacks a \DescRef{\LabelBase.cmd.cleardoubleoddpage} command before + \Macro{pagenumbering}, it receives a pagination of the Arabic number 1. + Additionally, the final line which sets the page numbering to 1 is + superfluous, since this is already done by \Macro{pagenumbering}. + + Sometimes\,---\,without the initial comment, naturally\,---\, you find: +\begin{lstcode} + % Attention! This example contains errors! + % Please note the explanation in the text! + \tableofcontents + \pagebreak + \pagenumbering{arabic} + \setcounter{page}{1} +\end{lstcode} + Here the creator tried to solve the problem with the final page of the table + of contents with the help of \Macro{pagebreak}\IndexCmd{pagebreak}. + + Unfortunately, this solution is not much better. Here there is a page break + after the last page of the table of contents. This may cause entries on the + last page of a two-sided document to have excess vertical spacing (see + \DescRef{\LabelBase.cmd.flushbottom}, + \DescPageRef{\LabelBase.cmd.flushbottom}). \Macro{pagebreak} is clearly + the wrong command here. + + Furthermore, \Macro{newpage}\IndexCmd{newpage} or + \DescRef{\LabelBase.cmd.clearpage} would not be sufficient for a two-sided + document. For example, if the last page of the table of contents had the + Roman numeral vii, the Arabic numbered right-side page 1 would immediately + follow the Roman numeral right-side page. A left-side page between the two + would be missing, which could cause serious problems with later printing. + + My advice: Avoid using templates that contain errors with respect to such + simple things. Incidentally, the correct way would be: +\begin{lstcode} + \tableofcontents + \cleardoubleoddpage + \pagenumbering{arabic} +\end{lstcode} + This also applies if \Class{scrartcl}\OnlyAt{\Class{scrartcl}} uses a class + that usually does not start a new page after the table of contents. If you + switch the page numbering, a new right-hand page must be started. If you do + not want such a change, you should keep the numbering style of pages + consistent throughout the document without changing it in between. +\iffalse% Umbruchkorrekturtext + For articles or other short documents, this is generally recommended. +\fi + + It is easier to change the numbering style when using + \Class{scrbook}\OnlyAt{\Class{scrbook}}. There you have the support of two + commands, \DescRef{\LabelBase.cmd.frontmatter}% + \important{\DescRef{\LabelBase.cmd.frontmatter}\\ + \DescRef{\LabelBase.cmd.mainmatter}}% + \IndexCmd{fontmatter} and \DescRef{\LabelBase.cmd.mainmatter}% + \IndexCmd{mainmatter}, for the most commonly used switching. For more + information, please see + \autoref{sec:maincls.separation}, + \DescPageRef{\LabelBase.cmd.mainmatter}.% +\end{Explain}% +\EndIndexGroup +\EndIndexGroup + + +\LoadCommonFile{interleafpage}% \section{Interleaf Pages} + +\LoadCommonFile{footnotes}% \section{Footnotes} + +\section[Book Structure]{Book Structure\protect\OnlyAt{\Class{scrbook}}} +\seclabel{separation} + +Sometimes books are loosely divided into \emph{front matter}% +\Index{front matter}, \emph{main matter}\Index{main matter}, and +\emph{back matter}\Index{back matter}. \KOMAScript{} also provides this +capability for \Class{scrbook}. + + +\begin{Declaration} + \Macro{frontmatter} + \Macro{mainmatter} + \Macro{backmatter} +\end{Declaration}% +The front matter includes all the material which appears before the main +text begins, including title pages, preface, and table of contents. It is +initiated with +\Macro{frontmatter}\important{\Macro{frontmatter}}. In the front matter, +Roman numerals are used for the page numbers, and chapter headings in +the header are not numbered. However, section headings are numbered +consecutively, starting from chapter 0. This typically does not matter, as the +front matter is used only for the title pages, table of contents% +\Index{table of contents}, lists of figures\Index{list of>figures}% +\Index{figures>list of} and tables\Index{tables>list of}, and a +preface\Index{preface} or foreword\Index{foreword}. The preface can thus be +created as a normal chapter. A preface should be as short as possible and +never divided into sections. The preface thus does not require a deeper level +of structure than the chapter. + +If you see things differently and want to use numbered +sections\Index{section>number} in the chapters of the front matter, as of +version~2.97e,\ChangedAt{v2.97e}{\Class{scrbook}}% +\important{\OptionValueRef{\LabelBase}{version}{2.97e}} the section numbering +no longer contains the chapter number. This change only takes effect when the +compatibility option is set to at least version~2.97e (see option +\DescRef{\LabelBase.option.version}, +\autoref{sec:\LabelBase.compatibilityOptions}, +\DescPageRef{\LabelBase.option.version}). It is explicitly noted that this +creates confusion with chapter numbers! The use of +\DescRef{\LabelBase.cmd.addsec} and \DescRef{\LabelBase.cmd.section*} (see +\autoref{sec:\LabelBase.structure}, \DescPageRef{\LabelBase.cmd.section*} and +\DescPageRef{\LabelBase.cmd.addsec}) are thus, in the author's opinion, +greatly preferable. + +As of version~2.97e\ChangedAt{v2.97e}{\Class{scrbook}} the numbering of +floating environments, such as tables\Index{table>number} and +figures\Index{figure>number}, and equation numbers\Index{equation>number} in +the front matter also contains no chapter-number part. To take effect, this +too requires the corresponding compatibility setting (see the +\DescRef{\LabelBase.option.version} option, +\autoref{sec:\LabelBase.compatibilityOptions}, +\DescPageRef{\LabelBase.option.version}). + +The part of the book with the main text is introduced +with \Macro{mainmatter}\important{\Macro{mainmatter}}. If there is no front +matter, you can omit this command. The default page numbering in the main +matter uses Arabic numerals and (re)starts the page count at 1 at the start of +the main matter. + +The back matter is introduced with +\Macro{backmatter}\important{\Macro{backmatter}}. Opinions differ as to what +belongs in the back matter. So in some cases you will find only the +bibliography\Index{bibliography}, in some cases only the index\Index{index}, +and in other cases both of these as well as the appendices. The chapters in +the back matter are similar to the chapters in the front matter, but page +numbering is not reset. If you do require separate page numbering, you can use +the \DescRef{\LabelBase.cmd.pagenumbering}% +\important{\DescRef{\LabelBase.cmd.pagenumbering}} command in +\autoref{sec:\LabelBase.pagestyle}, +\DescPageRef{\LabelBase.cmd.pagenumbering}.% +% +\EndIndexGroup + + +\section{Document Structure} +\seclabel{structure}% +\BeginIndexGroup +\BeginIndex{}{document structure} + +The structure refers to dividing a document into parts, chapters, sections, +and additional levels of structure. + + +\begin{Declaration} + \OptionVName{open}{method} +\end{Declaration}% +The\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} \KOMAScript{} classes +\Class{scrbook} and \Class{scrreprt} give you the choice of where to start a +new chapter with two-sided printing. By default \Class{scrreprt} starts a new +chapter\Index{chapter>start} on the next page. This is equivalent to +\PName{method} \PValue{any}. However, \Class{scrbook} starts new chapters at +the next right-hand page. This is equivalent to \PName{method} \PValue{right} +and is usually used in books. But sometimes chapters should start on the +left-hand page of a two-page spread. You can accomplish this with the +\PName{method} \PValue{left}\ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}}. You can find a summary of the available values in +\autoref{tab:\LabelBase.open}. The table also describes the effects of +\DescRef{\LabelBase.cmd.cleardoublepage}, +\DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, +\DescRef{\LabelBase.cmd.cleardoublestandardpage}, +\DescRef{\LabelBase.cmd.cleardoubleplainpage}, and +\DescRef{\LabelBase.cmd.cleardoubleemptypage} (see +\autoref{sec:\LabelBase.emptypage}, +\DescPageRef{\LabelBase.cmd.cleardoublepage}). + +\begin{table} + \caption[{Available values for the \Option{open} option}]{Available values + for the \Option{open} option to select page breaks with interleaf pages + using \Class{scrbook} or \Class{scrreprt}} + \begin{desctabular} + \pventry{any}{% + Parts, chapter, index, and back matter use + \DescRef{\LabelBase.cmd.clearpage}, not + \DescRef{\LabelBase.cmd.cleardoublepage}; + \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, + \DescRef{\LabelBase.cmd.cleardoublestandardpage}, + \DescRef{\LabelBase.cmd.cleardoubleplainpage}, + \DescRef{\LabelBase.cmd.cleardoubleemptypage}, and + \DescRef{\LabelBase.cmd.cleardoublepage} behave the same as using + \OptionValue{open}{right}.% + \IndexOption{open~=\textKValue{any}}}% + \pventry{left}{% + Part, chapter, index, and back matter use + \DescRef{\LabelBase.cmd.cleardoublepage}; the commands + \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, + \DescRef{\LabelBase.cmd.cleardoublestandardpage}, + \DescRef{\LabelBase.cmd.cleardoubleplainpage}, + \DescRef{\LabelBase.cmd.cleardoubleemptypage}, and + \DescRef{\LabelBase.cmd.cleardoublepage} result in a page break and add + an interleaf page\Index{page>interleaf} if needed to reach the next + left-hand page.% + \IndexOption{open~=\textKValue{left}}}% + \pventry{right}{% + Part, chapter, index, and back matter use + \DescRef{\LabelBase.cmd.cleardoublepage}; the commands + \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, + \DescRef{\LabelBase.cmd.cleardoublestandardpage}, + \DescRef{\LabelBase.cmd.cleardoubleplainpage}, + \DescRef{\LabelBase.cmd.cleardoubleemptypage}, and + \DescRef{\LabelBase.cmd.cleardoublepage} result in a page break and add + an interleaf page\Index{page>interleaf} if needed to reach the next + right-hand page.% + \IndexOption{open~=\textKValue{right}}}% + \end{desctabular} + \label{tab:\LabelBase.open} +\end{table} + +Since \LaTeX{} does not differentiate between left-hand and right-hand pages +in one-sided printing, the option has no effect in that case. + +In the \Class{scrartcl} class, the section is the first structural element +below the part. For this reason, \Class{scrartcl} does not support this +option. +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{chapterprefix}{simple switch} + \OptionVName{appendixprefix}{simple switch} + \Macro{IfChapterUsesPrefixLine}\Parameter{then code}\Parameter{else code} +\end{Declaration}% +With\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} the standard classes +\Class{book} and \Class{report}, a chapter +heading\Index[indexmain]{chapter>heading} consists of a line with the word +``Chapter''\footnote{When using another language the word ``Chapter'' is of +course translated to the appropriate language.} followed by the chapter +number. The heading itself is set left-justified on the following line. The +same effect is obtained in {\KOMAScript} with the \Option{chapterprefix} +option. You can use any value from \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch} as the \PName{simple switch}. The default, +however, is \OptionValue{chapterprefix}{false}, the opposite +behaviour\textnote{\KOMAScript{} vs. standard classes} of that of the standard +classes, which corresponds to \OptionValue{chapterprefix}{true}. These options +also affect the automatic running heads in the headers (see +\autoref{sec:\LabelBase.pagestyle}, +\DescPageRef{\LabelBase.pagestyle.headings}). + +Sometimes you may want to use the simplified chapter headings produced by +\OptionValue{chapterprefix}{false} but at the same time to have the heading of +an appendix\Index{appendix} preceded by a line with ``Appendix'' followed by +the appendix letter. This is achieved by using the \Option{appendixprefix} +option (see \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}). +Since this results in an inconsistent document layout, I advise against using +this option. Ultimately, this option changes the \Option{chapterprefix} option +automatically at the beginning of the \DescRef{\LabelBase.cmd.appendix}. + +You\ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}} can execute code +depending on the current setting for the chapter preceding line using +\Macro{IfChapterUsesPrefixLine}. If \Option{chapterprefix} is currently +active, the \PName{then code} is executed; otherwise, the \PName{else code} is +executed. + +\BeginIndex{FontElement}{chapterprefix}% +You can change the font style of the chapter number line that uses +\OptionValue{chapterprefix}{true} or \OptionValue{appendixprefix}{true} +by using the +\FontElement{chapterprefix}\ChangedAt{v2.96a}{\Class{scrbook}\and + \Class{scrreprt}} element with the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see +\autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}). The default is to use the +\DescRef{\LabelBase.fontelement.chapter}\IndexFontElement{chapter} element +(see \DescPageRef{\LabelBase.cmd.chapter}, as well as +\autoref{tab:\LabelBase.structureElementsFont}, +\autopageref{tab:\LabelBase.structureElementsFont}). + +You can find additional settings for chapter headings in the explanation for +\DescRef{maincls-experts.cmd.RedeclareSectionCommand} and the commands +\DescRef{maincls-experts.cmd.chapterlineswithprefixformat} and +\DescRef{maincls-experts.cmd.chapterlinesformat} in +\autoref{sec:maincls-experts.experts}, \autoref{part:forExperts}.% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{headings}{setting} +\end{Declaration} +Headings\index{heading}\index{document structure} of sectioning levels +normally use a relatively large font size in both the standard classes and +{\KOMAScript}. This choice does not appeal to everyone and is especially +problematic for small paper sizes. Consequently, {\KOMAScript} provides, in +addition to the large headings defined by the +\OptionValue{headings}{big}\IndexOption{headings~=\textKValue{big}}% +\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% +\important{\OptionValue{headings}{big}\\ + \OptionValue{headings}{normal}\\ + \OptionValue{headings}{small}} option, the options +\OptionValue{headings}{normal}\IndexOption{headings~=\textKValue{normal}} and +\OptionValue{headings}{small}\IndexOption{headings~=\textKValue{small}}, which +allow for smaller headings. The font sizes resulting from these options for +\Class{scrbook} and \Class{scrreprt} are shown in +\autoref{tab:\LabelBase.structureElementsFont}, +\autopageref{tab:\LabelBase.structureElementsFont}. Specifically, all three +settings reset the elements \DescRef{\LabelBase.fontelement.chapter}% +\IndexFontElement{chapter}, +\DescRef{\LabelBase.fontelement.section}\IndexFontElement{section}, +\DescRef{\LabelBase.fontelement.subsection}\IndexFontElement{subsection}, +\DescRef{\LabelBase.fontelement.subsubsection}% +\IndexFontElement{subsubsection}, +\DescRef{\LabelBase.fontelement.paragraph}\IndexFontElement{paragraph}, and +\DescRef{\LabelBase.fontelement.subparagraph}\IndexFontElement{subparagraph} +to the corresponding defaults. \Class{scrartcl}\OnlyAt{\Class{scrbook}\and + \Class{scrreprt}} generally uses slightly smaller headings. The spacing +before and after chapter headings is also reset by these options. + +\iffalse% + Chapter headings also have the \Option{headings} option with the + \PValue{twolinechapter} or \PValue{onelinechapter} settings, which are + equivalent to the + \OptionValueRef{\LabelBase}{chapterprefix}{true} and + \OptionValueRef{\LabelBase}{chapterprefix}{false} options. In the appendix + there are additional effects of the \PValue{onelineappendix} and + \PValue{twolineappendix} options upon the \Option{headings} option, which + corresponds to + \OptionValueRef{\LabelBase}{appendixprefix}{false} and + \OptionValueRef{\LabelBase}{appendixprefix}{true} (see also + above). % +\else% + Chapter headings\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} also + have\important{% + \OptionValue{headings}{twolinechapter}\\ + \OptionValue{headings}{onelinechapter}\\ + \OptionValue{headings}{twolineappendix}\\ + \OptionValue{headings}{onelineappendix}% + } the two options \OptionValue{headings}{twolinechapter} and + \OptionValue{headings}{onelinechapter}, which correspond to + \OptionValueRef{\LabelBase}{chapterprefix}{true} and + \OptionValueRef{\LabelBase}{chapterprefix}{false} explained above. For the + appendix, + \OptionValueRef{\LabelBase}{appendixprefix}{true} and + \OptionValueRef{\LabelBase}{appendixprefix}{false} serve as alternatives for + the \OptionValue{headings}{twolineappendix} and + \OptionValue{headings}{onelineappendix} options. % + \iffalse% + For the appendix, \OptionValue{headings}{twolineappendix} and + \OptionValue{headings}{onelineappendix} are available, which correspond to + the \OptionValueRef{\LabelBase}{appendixprefix}{true} and + \OptionValueRef{\LabelBase}{appendixprefix}{false} options (also see above). + \fi% + Of course, these options do not exist with \Class{scrartcl}% + \iffree{}{% Umbruchkorrekturtext + , since this class does not have chapters}% + .% +\fi + +The\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} \OptionValue{headings}{standardclasses}% +\important{\OptionValue{headings}{standardclasses}} option adjusts the font +sizes of the headings to those of the standard classes. In addition, the font +for the \DescRef{\LabelBase.fontelement.disposition}% +\IndexFontElement{disposition} element is set to \Macro{bfseries}. It +therefore no longer uses a sans-serif font for the headings. If you use +\Class{scrbook}\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} or +\Class{scrreprt}, \OptionValue{headings}{twolinechapter} is also set and the +spacing between the chapter headings is adjusted to that of the standard +classes. + +You\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} can set the method to specify +the page on which new chapters begin with +\OptionValue{headings}{openany}\important{% + \OptionValue{headings}{openany}\\ + \OptionValue{headings}{openright}\\ + \OptionValue{headings}{openleft}}, \OptionValue{headings}{openright}, and +\OptionValue{headings}{openleft}, or alternatively with the +\DescRef{\LabelBase.option.open} option, which takes the values \PValue{any}, +\PValue{right}, and \PValue{left} (see above). + +Another\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} special feature of \KOMAScript{} is the handling of the +optional argument of the sectioning commands \DescRef{\LabelBase.cmd.part}, +\DescRef{\LabelBase.cmd.chapter}, etc. down to +\DescRef{\LabelBase.cmd.subparagraph}. You can change its function and +meaning\important{\OptionValue{headings}{optiontohead}\\ + \OptionValue{headings}{optiontotoc}\\ + \OptionValue{headings}{optiontoheadandtoc}} with the options +\OptionValue{headings}{optiontohead}% +\IndexOption{headings~=\textKValue{optiontohead}}, +\OptionValue{headings}{optiontotoc}% +\IndexOption{headings~=\textKValue{optiontotoc}} and +\OptionValue{headings}{optiontoheadandtoc}% +\IndexOption{headings~=\textKValue{optiontoheadandtoc}}. + +See \autoref{tab:\LabelBase.headings} for a summary of all available settings +for the \Option{headings} option. The explanations of the sectioning commands +below contain examples using some of these settings. +\begin{desclist} + \desccaption[{Available values for the \Option{headings} option}]{% + Available values for the \Option{headings} option to format + section headings% + \label{tab:\LabelBase.headings}% + }{% + Available values for the \Option{headings} option (\emph{continued})% + }% + \pventry{big}{% + Use large fonts in the headings for each of the default sectioning levels + with wide spacing above and below the titles. + \IndexOption{headings~=\textKValue{big}}}% + \pventry{normal}{% + Use medium-sized fonts in the headings with medium spacing above and below + the titles. \IndexOption{headings~=\textKValue{normal}}}% + \entry{\PValue{onelineappendix}, \PValue{noappendixprefix}, + \PValue{appendixwithoutprefix}, \PValue{appendixwithoutprefixline}% + \IndexOption{headings~=\textKValue{onelineappendix}}}{% + Chapter headings in the appendix are set like other headings.% + }% + \entry{\PValue{onelinechapter}, \PValue{nochapterprefix}, + \PValue{chapterwithoutprefix}, \PValue{chapterwithoutprefixline}% + \IndexOption{headings~=\textKValue{onelinechapter}}}{% + Chapter titles are set like other headings.% + }% + \pventry{openany}{% + The commands \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, + \DescRef{\LabelBase.cmd.cleardoublestandardpage}, + \DescRef{\LabelBase.cmd.cleardoubleplainpage}, + \DescRef{\LabelBase.cmd.cleardoubleemptypage}, and + \DescRef{\LabelBase.cmd.cleardoublepage} generate a page break and insert + an interleaf page\Index{interleaf page} if needed to reach the next + right-hand page in two-sided printing, the same as in + \OptionValue{headings}{openright}. Parts, chapter, the index, and back + matter use \DescRef{\LabelBase.cmd.clearpage} instead of + \DescRef{\LabelBase.cmd.cleardoublepage}.% + \IndexOption{headings~=\textKValue{openany}}}% + \pventry{openleft}{% + The commands \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, + \DescRef{\LabelBase.cmd.cleardoublestandardpage}, + \DescRef{\LabelBase.cmd.cleardoubleplainpage}, + \DescRef{\LabelBase.cmd.cleardoubleemptypage}, and + \DescRef{\LabelBase.cmd.cleardoublepage} generate a page break and insert + an interleaf page if needed to reach the next left-hand page in two-sided + printing. Part, chapter, index and back matter use + \DescRef{\LabelBase.cmd.cleardoublepage}.% + \IndexOption{headings~=\textKValue{openleft}}}% + \pventry{openright}{% + The commands \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, + \DescRef{\LabelBase.cmd.cleardoublestandardpage}, + \DescRef{\LabelBase.cmd.cleardoubleplainpage}, + \DescRef{\LabelBase.cmd.cleardoubleemptypage}, and + \DescRef{\LabelBase.cmd.cleardoublepage} generate a page break and insert + an interleaf page if needed to reach the next right-hand page in two-sided + printing. Part, chapter, index and back matter use + \DescRef{\LabelBase.cmd.cleardoublepage}.% + \IndexOption{headings~=\textKValue{openright}}}% + \pventry{optiontohead}{% + The\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} advanced functionality of the optional argument of the + sectioning commands \DescRef{\LabelBase.cmd.part} down to + \DescRef{\LabelBase.cmd.subparagraph} is activated. By default, the + optional argument is used only for the running head.% + \IndexOption{headings~=\textKValue{optiontohead}}% + }% + \entry{\PValue{optiontoheadandtoc}, \PValue{optiontotocandhead}% + \IndexOption{headings~=\textKValue{optiontoheadandtoc}}}{% + The\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} advanced functionality of the optional argument of the + sectioning commands \DescRef{\LabelBase.cmd.part} down to + \DescRef{\LabelBase.cmd.subparagraph} is activated. By default, the + optional argument is used for the running head and the table of contents.% + }% + \pventry{optiontotoc}{% + The\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} advanced functionality of the optional argument of the + sectioning commands \DescRef{\LabelBase.cmd.part} down to + \DescRef{\LabelBase.cmd.subparagraph} is activated. By default, the + optional argument is used only for the table of contents.% + \IndexOption{headings~=\textKValue{optiontohead}}% + }% + \pventry{small}{% + Use small fonts in the headings with small spacing above and below the + titles.% + \IndexOption{headings~=\textKValue{small}}}% + \pventry{standardclasses}{% + \ChangedAt{v3.12}{\Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}}% + Reset the font settings for each of the standard sectioning levels and use + headings with the sizes of the standard classes. For chapter headings, + \Class{scrbook} und \Class{scrreprt} set + \OptionValue{headings}{twolinechapter}.% + }% + \entry{\PValue{twolineappendix}, \PValue{appendixprefix}, + \PValue{appendixwithprefix}, \PValue{appendixwithprefixline}% + \IndexOption{headings~=\textKValue{twolineappendix}}}{% + Chapter titles in the appendix are set with a number line whose format is + determined by + \DescRef{\LabelBase.cmd.chapterformat}\IndexCmd{chapterformat}.% + }% + \entry{\PValue{twolinechapter}, \PValue{chapterprefix}, + \PValue{chapterwithprefix}, \PValue{chapterwithprefixline}% + \IndexOption{headings~=\textKValue{twolinechapter}}}{% + Chapter titles are set with a number line whose format is determined by + \DescRef{\LabelBase.cmd.chapterformat}\IndexCmd{chapterformat}.% + }% +\end{desclist} +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{numbers}{setting} +\end{Declaration}% +According to {\small DUDEN}, if only Arabic numerals are used to number +section headings\Index{headings}, the German practice is to have no point at +the end (see \cite[R\,3]{DUDEN}). On the other hand, if Roman numerals or +letters appear in the numbering, then a point should appear at the end of the +numbering (see \cite[R\,4]{DUDEN}). {\KOMAScript} has a mechanism that tries +to automate this somewhat complex rule. The result is that normally after +the sectioning commands \DescRef{\LabelBase.cmd.part} and +\DescRef{\LabelBase.cmd.appendix} the numbering switches to using a final +point. This information is saved in the \File{aux} file and takes effect on +the next {\LaTeX} run. + +Sometimes the mechanism for placing or omitting the final point may fail. +Sometimes other languages have different rules. Therefore you can force the +use of the final point with the option +\OptionValue{numbers}{endperiod}\IndexOption{numbers~=\textKValue{endperiod}}% +\important{\OptionValue{numbers}{endperiod}\\ +\OptionValue{numbers}{noendperiod}} or to prohibit it with +\OptionValue{numbers}{noendperiod}. + +Note\textnote{Attention!} that this mechanism only takes effect on the +next {\LaTeX} run. Therefore, before you try to use these options to force +the correct numbering format, you should always perform another \LaTeX{} run +without modifying the document. + +You can find a summary of the available values for the \PName{setting} of +\PName{numbers} in \autoref{tab:\LabelBase.numbers}. Unlike most other +settings, this option can only be set in the document preamble, i.\,e. before +\Macro{begin}\PParameter{document}. + +\begin{table} + \caption[{Available values for the \Option{numbers} option}]{Available values + of the \Option{numbers} option to configure the final points of the + numbers for section headings} + \label{tab:\LabelBase.numbers} + \begin{desctabular} + \entry{\PValue{autoendperiod}, \PValue{autoenddot}, \PValue{auto}}{% + \KOMAScript{} decides whether to set the point at the end of sectioning + command numbers. If there are only Arabic numerals, the point will + be omitted. If a letter or Roman numeral is found, the + point is set. However, references to these numbers are set without + a final point.% + \IndexOption{numbers~=\textKValue{autoendperiod}}}% + \entry{\PValue{endperiod}, \PValue{withendperiod}, \PValue{periodatend}, + \PValue{enddot}, \PValue{withenddot}, \PValue{dotatend}}{% + All numbers of sectioning commands and their subordinate numbers are set + with a final point. Only references will be set without the final + point.% + \IndexOption{numbers~=\textKValue{endperiod}}}% + \entry{\PValue{noendperiod}, \PValue{noperiodatend}, + \PValue{noenddot}, \PValue{nodotatend}}{% + All numbers of sectioning commands are set without a final point.% + \IndexOption{numbers~=\textKValue{noendperiod}}}% + \end{desctabular} +\end{table} +% +\EndIndexGroup + + +\begin{Declaration} + \Option{chapteratlists}% + \OptionVName{chapteratlists}{value} +\end{Declaration}% +As mentioned in \autoref{sec:\LabelBase.floats}, +\DescPageRef{\LabelBase.option.listof}\OnlyAt{\Class{scrbook}\and + \Class{scrreprt}}, every chapter that is created with +\DescRef{\LabelBase.cmd.chapter} normally inserts a vertical space in the +lists of floating environments (e.\,g., tables and figures). +Since version~2.96a,\important{\OptionValueRef{\LabelBase}{version}{2.96a}}% +\ChangedAt{v2.96a}{\Class{scrbook}\and \Class{scrreprt}} this also applies to +the \DescRef{\LabelBase.cmd.addchap} command unless you choose a compatibility +setting for an earlier version (see the \DescRef{\LabelBase.option.version} +option in \autoref{sec:\LabelBase.compatibilityOptions}, +\DescPageRef{\LabelBase.option.version}). + +In addition, you can use the \Option{chapteratlists} option to change the +vertical spacing by specifying the desired distance as the \PName{value}. +The default with \OptionValueRef{\LabelBase}{listof}{chaptergapsmall}% +\IndexOption{listof~=\textKValue{chaptergapsmall}} % +is 10\Unit{pt} (see the\DescRef{\LabelBase.option.version} option in +\autoref{sec:\LabelBase.compatibilityOptions}, +\DescPageRef{\LabelBase.option.version}). + +If you use \OptionValue{chapteratlists}{entry}% +\IndexOption{chapteratlists~=\textKValue{entry}}% +\important{\OptionValue{chapteratlists}{entry}} or \Option{chapteratlists} +without specifying a value, instead of a vertical space, the chapter entry +itself will be entered into the lists. Note that such an entry occurs even if +the chapter does not contain a floating environment. A method where only +chapters with floating environments are displayed in the respective list can +be found in the German-language \KOMAScript{} forum at +\cite{https://komascript.de/comment/5070}. + +Please\textnote{Attention!} note that changes to this option only takes +effect after two additional {\LaTeX} runs.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{part}\OParameter{short version}\Parameter{heading}% + \Macro{chapter}\OParameter{short version}\Parameter{heading}% + \Macro{section}\OParameter{short version}\Parameter{heading}% + \Macro{subsection}\OParameter{short version}\Parameter{heading}% + \Macro{subsubsection}\OParameter{short version}\Parameter{heading}% + \Macro{paragraph}\OParameter{short version}\Parameter{heading}% + \Macro{subparagraph}\OParameter{short version}\Parameter{heading} +\end{Declaration}% +\Index[indexmain]{part}% +\Index[indexmain]{chapter}% +\Index[indexmain]{section}% +The standard sectioning commands in {\KOMAScript} work the same way as those +in the standard classes. Thus, you can specify an alternative text for the +table of contents and running heads as an optional argument to the sectioning +commands. + +However, with\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\textnote{\KOMAScript{} vs. standard classes} the +\important{\DescRef{\LabelBase.option.headings}} +\OptionValueRef{\LabelBase}{headings}{optiontohead}% +\IndexOption[indexmain]{headings~=\textKValue{optiontohead}} option, +\KOMAScript{} only uses the optional argument \PName{short version} in the +running head, not the table of contents. Of course, this text will only appear +if you use a page style\Index{page>style} that puts the corresponding +sectioning level in the running head. See \autoref{sec:\LabelBase.pagestyle} +and \autoref{cha:scrlayer-scrpage}. With the +\OptionValueRef{\LabelBase}{headings}{optiontotoc}% +\IndexOption[indexmain]{headings~=\textKValue{optiontotoc}} option, +\KOMAScript{} uses the optional argument \PName{short version} exclusively for +the table of contents and not the running head. However, the entry will be +shown only if the \DescRef{\LabelBase.counter.tocdepth} counter is great +enough (see \autoref{sec:\LabelBase.toc}, +\DescPageRef{\LabelBase.counter.tocdepth}). With the +\OptionValueRef{\LabelBase}{headings}{optiontoheadandtoc}% +\IndexOption[indexmain]{headings~=\textKValue{optiontoheadandtoc}} option, +\KOMAScript{} uses the optional argument \PName{short version} in both the +table of contents and the running head. These three options all activate the +extended interpretation of the optional argument \PName{short version}, which +is not active by default. + +The \ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} extended interpretation of the optional argument +checks to see if there is an equals sign in \PName{short version}. If so, +the optional argument will be interpreted as an \PName{option list}. +Three options\,---\,\OptionVName{head}{running head}\important{\Option{head}\\ + \Option{tocentry}\\ + \Option{reference}}, \OptionVName{tocentry}{table of contents entry}, and +\OptionVName{reference}{reference title}% +\ChangedAt{v3.22}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% +\,---\,are supported with this format. To use commas or equals signs +within the values of those options, you must enclose them in braces. + +Please\textnote{Attention!} note that this mechanism only works as long as +\KOMAScript{} controls the sectioning commands. If you use package that +redefines the \KOMAScript{}'s or the internal \LaTeX{} kernel's sectioning +commands, \KOMAScript{} can no longer provide this extended mechanism. This +also applies to a \KOMAScript{} that is always active: sectioning commands +with no heading text\textnote{empty headings} do not create entries in the +table of contents. If you really want an entry with empty heading text, you +can use an invisible entry like \lstinline|\mbox{}|. + +\begin{Example} + Suppose you have a document with very long chapter headings. These headings + should appear in the table of contents, but you want to limit the running + head to short, single-line headings. You can do this with the optional + argument of \Macro{chapter}. +\begin{lstcode} + \chapter[short version of chapter heading] + {The Sectioning Command for Chapters + Supports not only the Heading Text + Itself but also a Short Version Whose + Use can be Controlled} +\end{lstcode} + + A little later you realize that the line breaks for this long heading are + very inappropriate. You therefore want to choose the breaks + yourself. Nevertheless, you still want automatic line breaking in the table + of contents. With +\begin{lstcode} + \chapter[head={short version of chapter heading}, + tocentry={The Sectioning + Command for Chapters Supports not + only the Heading Text Itself but + also a Short Version Whose Use + can be Controlled}] + {The Sectioning\\ + Command for Chapters\\ + Supports not only\\ + the Heading Text Itself\\ + but also\\ + a Short Version Whose\\ + Use can be Controlled} +\end{lstcode} + you create separate entries for the table of contents, running head, and + chapter heading itself. The arguments of the options \Option{head} and + \Option{tocentry} have been enclosed in braces so their contents + can be arbitrary. + + The need for braces in the example above is best illustrated by another + example. Suppose you chose the + \OptionValueRef{\LabelBase}{headings}{optiontotoc} option and set the title + this way: +\begin{lstcode} + \section[head=\emph{value}] + {Option head=\emph{value}} +\end{lstcode} + This results in the entry ``Option head=\emph{value}'' in the table of + contents but ``\emph{value}'' in the running head. But surely you wanted the + entry ``head=\emph{value}'' in the table of contents and the complete + heading text in the running head. You can do this using braces: +\begin{lstcode} + \section[head{=}\emph{value}] + {Option head=\emph{value}} +\end{lstcode} + + A similar case concerns the comma. Using the same + \DescRef{\LabelBase.option.headings} option as before +\begin{lstcode} + \section[head=0, 1, 2, 3, \dots] + {Natural Numbers Including the Zero} +\end{lstcode} + results in an error because the comma is interpreted as the + separator between the individual options of the option list % + ``\lstinline|0, 1, 2, 3, \dots|''. But writing +\begin{lstcode} + \section[head={0, 1, 2, 3, \dots}] + {Natural Numbers Including the Zero} +\end{lstcode} + makes ``\lstinline|0, 1, 2, 3, \dots|'' the argument of + the \Option{head} option. +\end{Example} + +Like\ChangedAt{v3.22}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} setting the title of a running head with the \Option{head} +option, or setting the title of a table-of-contents entry with the +\Option{tocentry} option, you can set the title of a reference with the +\Package{nameref}\IndexPackage{nameref}\important{\Package{nameref}\\ + \Package{titleref}\\ + \Package{zref-titleref}} or +\Package{titleref}\IndexPackage{titleref} packages, or with the +\Package{titleref}\IndexPackage{zref-titleref} module of the +\Package{zref}\IndexPackage{zref} package, using the \Option{reference}% +\important{\Option{reference}} option. Note that the support for the +\Package{titleref} package is rather rudimentary, since that package's +performance is poor compared to the other two, and it is not fully compatible +with \Package{hyperref}\IndexPackage{hyperref}\important{\Package{hyperref}}. + +The part-level title\important{\Macro{part}} (\Macro{part}) differs from other +sectioning levels by being numbered independently. This means that the chapter +level (in \Class{scrbook} or \Class{scrreprt}), or the section level (in +\Class{scrartcl}) is numbered consecutively over all parts. Furthermore, for +the \Class{scrbook}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} and +\Class{scrreprt} classes, the title of the part level together with the +corresponding preamble (see \DescRef{\LabelBase.cmd.setpartpreamble}, +\DescPageRef{\LabelBase.cmd.setpartpreamble}) is set on a separate page. + +The \Macro{chapter}\important{\Macro{chapter}}\OnlyAt{\Class{scrbook}\and + \Class{scrreprt}} command only exists in the book and report classes, that +is, in \Class{book}, \Class{scrbook}, \Class{report} and \Class{scrreport}, +but not in the article classes \Class{article} and \Class{scrartcl}. +Furthermore, the \Macro{chapter}\textnote{\KOMAScript{} vs. standard classes} +command in {\KOMAScript} differs substantially from the version in the +standard classes. In the standard classes, the chapter number is used together +with the prefix ``Chapter'', or the corresponding word in the appropriate +language, on a separate line above the actual chapter title text. +\KOMAScript{} replaces this +overpowering\important{\DescRef{\LabelBase.option.chapterprefix}\\ + \DescRef{\LabelBase.option.appendixprefix}} style with a simple chapter +number before the chapter title, but you can restore the original behaviour +with the \DescRef{\LabelBase.option.chapterprefix} option (see +\DescPageRef{\LabelBase.option.chapterprefix}). + +Please\textnote{Attention!} note that \Macro{part} and \Macro{chapter} in the +\Class{scrbook} and \Class{scrreprt} +\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} classes change the page style for +one page. The page style applied in {\KOMAScript} is defined in the macros +\DescRef{\LabelBase.cmd.partpagestyle} and +\DescRef{\LabelBase.cmd.chapterpagestyle} (see +\autoref{sec:\LabelBase.pagestyle}, +\DescPageRef{\LabelBase.cmd.titlepagestyle}). + +\BeginIndexGroup +\BeginIndex[indexother]{}{font}% +\BeginIndex[indexother]{}{font>style}% +\BeginIndex[indexother]{}{font>size}% +\BeginIndex{FontElement}{part}\LabelFontElement{part}% +\BeginIndex{FontElement}{partnumber}\LabelFontElement{partnumber}% +\BeginIndex{FontElement}{chapter}\LabelFontElement{chapter}% +\BeginIndex{FontElement}{chapterprefix}\LabelFontElement{chapterprefix}% +\BeginIndex{FontElement}{section}\LabelFontElement{section}% +\BeginIndex{FontElement}{subsection}\LabelFontElement{subsection}% +\BeginIndex{FontElement}{subsubsection}\LabelFontElement{subsubsection}% +\BeginIndex{FontElement}{paragraph}\LabelFontElement{paragraph}% +\BeginIndex{FontElement}{subparagraph}\LabelFontElement{subparagraph}% +\BeginIndex{FontElement}{disposition}\LabelFontElement{disposition}% +You\ChangedAt{v2.8p}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} can change the font style for all headings with the +\DescRef{\LabelBase.cmd.setkomafont}\IndexCmd{setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont}\IndexCmd{addtokomafont} commands (see +\autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}). In doing so, the element +\FontElement{disposition}\important{\FontElement{disposition}} is applied +first, followed by the specific element\important{% + \FontElement{part}\\ + \FontElement{chapter}\\ + \FontElement{section}\\ + \FontElement{subsection}\\ + \FontElement{paragraph}\\ + \FontElement{subparagraph}} for each sectioning level (see +\autoref{tab:\LabelBase.fontelements}, +\autopageref{tab:\LabelBase.fontelements}). There is a separate elements, +\FontElement{partnumber}, for the number of the part heading, and +\FontElement{chapterprefix}, for the optional prefix line of chapter headings. +The initial definition for the \FontElement{disposition} element is +\Macro{normalcolor}\linebreak[2]\Macro{sffamily}\linebreak[2]\Macro{bfseries}. +The default font sizes for the specific elements depends on the options +\OptionValueRef{\LabelBase}{headings}{big}, +\OptionValueRef{\LabelBase}{headings}{normal}, and +\OptionValueRef{\LabelBase}{headings}{small} (see +\DescPageRef{\LabelBase.option.headings}). They are listed in +\autoref{tab:\LabelBase.structureElementsFont}. +% Umbruchkorrektur: Tabelle verschoben +\begin{table} +% \centering% +% \caption + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% + \begin{captionbeside}[{Default font sizes for different levels of document + sectioning}]{% + \label{tab:\LabelBase.structureElementsFont}% + Default font sizes for different levels of document sectioning in + \Class{scrbook} and \Class{scrreprt}}[l] + \begin{tabular}[t]{lll} + \toprule + Class Option & Element & Default\\ + \midrule + \OptionValueRef{\LabelBase}{headings}{big} + & \DescRef{\LabelBase.fontelement.part}\IndexFontElement{part} + & \Macro{Huge} \\ + & \DescRef{\LabelBase.fontelement.partnumber}% + \IndexFontElement{partnumber} + & \Macro{huge} \\ + & \DescRef{\LabelBase.fontelement.chapter}\IndexFontElement{chapter} + & \Macro{huge} \\ + & \DescRef{\LabelBase.fontelement.chapterprefix}% + \IndexFontElement{chapterprefix} + & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{chapter} \\ + & \DescRef{\LabelBase.fontelement.section}\IndexFontElement{section} + & \Macro{Large} \\ + & \DescRef{\LabelBase.fontelement.subsection}% + \IndexFontElement{subsection} + & \Macro{large} \\ + & \DescRef{\LabelBase.fontelement.subsubsection}% + \IndexFontElement{subsubsection} + & \Macro{normalsize} \\ + & \DescRef{\LabelBase.fontelement.paragraph}\IndexFontElement{paragraph} + & \Macro{normalsize} \\ + & \DescRef{\LabelBase.fontelement.subparagraph}% + \IndexFontElement{subparagraph} + & \Macro{normalsize} \\[1ex] + \OptionValueRef{\LabelBase}{headings}{normal} + & \DescRef{\LabelBase.fontelement.part} & \Macro{huge} \\ + & \DescRef{\LabelBase.fontelement.partnumber} & \Macro{huge} \\ + & \DescRef{\LabelBase.fontelement.chapter} & \Macro{LARGE} \\ + & \FontElement{chapterprefix}\IndexFontElement{chapterprefix} + & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{chapter} \\ + & \DescRef{\LabelBase.fontelement.section} & \Macro{Large} \\ + & \DescRef{\LabelBase.fontelement.subsection} & \Macro{large} \\ + & \DescRef{\LabelBase.fontelement.subsubsection} & \Macro{normalsize} \\ + & \DescRef{\LabelBase.fontelement.paragraph} & \Macro{normalsize} \\ + & \DescRef{\LabelBase.fontelement.subparagraph} & \Macro{normalsize} \\[1ex] + \OptionValueRef{\LabelBase}{headings}{small} + & \DescRef{\LabelBase.fontelement.part} & \Macro{LARGE} \\ + & \DescRef{\LabelBase.fontelement.partnumber} & \Macro{LARGE} \\ + & \DescRef{\LabelBase.fontelement.chapter} & \Macro{Large} \\ + & \FontElement{chapterprefix}\IndexFontElement{chapterprefix} + & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{chapter} \\ + & \DescRef{\LabelBase.fontelement.section} & \Macro{large} \\ + & \DescRef{\LabelBase.fontelement.subsection} & \Macro{normalsize} \\ + & \DescRef{\LabelBase.fontelement.subsubsection} & \Macro{normalsize} \\ + & \DescRef{\LabelBase.fontelement.paragraph} & \Macro{normalsize} \\ + & \DescRef{\LabelBase.fontelement.subparagraph} & \Macro{normalsize}\\ + \bottomrule + \end{tabular} + \end{captionbeside} +\end{table} +% +\begin{Example} + Suppose you use the \OptionValueRef{\LabelBase}{headings}{big} class option + and notice that the very large headings of the document parts are too bold. + You could change this as follows: +\begin{lstcode} + \setkomafont{disposition}{\normalcolor\sffamily} + \part{Appendices} + \addtokomafont{disposition}{\bfseries} +\end{lstcode} +Using the command above you only switch off the font attribute +\textbf{bold} for a heading ``Appendices''. A much more convenient +and elegant solution is to change all \Macro{part} headings at once. +This is done either by: +\begin{lstcode} + \addtokomafont{part}{\normalfont\sffamily} + \addtokomafont{partnumber}{\normalfont\sffamily} +\end{lstcode} + or simply: +\begin{lstcode} + \addtokomafont{part}{\mdseries} + \addtokomafont{partnumber}{\mdseries} +\end{lstcode} +The second version is preferred because it gives you the correct result +even if you change the \DescRef{\LabelBase.fontelement.disposition} +element\IndexFontElement{disposition}, for instance: +\begin{lstcode} + \setkomafont{disposition}{\normalcolor\bfseries} +\end{lstcode} + With this change, it is possible to set all section levels at once to no + longer use sans serif fonts. +\end{Example} + +I strongly advise against using the ability to switch fonts in order to mix +fonts, font sizes, and font attributes wildly. Picking the right font for the +job is a matter for experts and has almost nothing to do with the personal +tastes of non-experts. See the citation at the end of +\autoref{sec:typearea.tips}, \autopageref{sec:typearea.tips.cite} and to the +following explanation. + +\begin{Explain} + It is possible to use different font types for different sectioning + levels in {\KOMAScript}. Non-experts in typography should absolutely avoid + doing so for excellent typographical reasons. + + A rule of typography states that you should mix as few fonts as possible. + Using sans serif for headings already seems to violate this rule. However, + you should realize that large, bold, serif letters are much too heavy for + headings. Strictly speaking, you should then use a normal instead of a bold + or semi-bold font. However, in deeper levels of the sectioning, a normal + font may then appear too light. On the other hand, sans serif fonts have a + very pleasant appearance in headings, and almost solely in headings. There + is, therefore, good reason why sans serif is the default in {\KOMAScript}. + + Greater variety should, however, be avoided. Font mixing is something for + professionals. For this reason, if you want to use fonts other than the + standard {\TeX} fonts\,---\,regardless of whether these are CM\Index{CM + fonts}, EC\Index{EC fonts}, or LM fonts\Index{LM fonts}\,---\,you should + consult an expert about the compatibility of the sans serif and serif fonts, + or redefine the element + \DescRef{\LabelBase.fontelement.disposition}\IndexFontElement{disposition} + as a precautionary measure. The author considers the commonly encountered + combinations of Times and Helvetica or Palatino with Helvetica to be + awkward. +\end{Explain} +\EndIndexGroup +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{part*}\Parameter{heading}% + \Macro{chapter*}\Parameter{heading}% + \Macro{section*}\Parameter{heading}% + \Macro{subsection*}\Parameter{heading}% + \Macro{subsubsection*}\Parameter{heading}% + \Macro{paragraph*}\Parameter{heading}% + \Macro{subparagraph*}\Parameter{heading} +\end{Declaration}% +The starred variants of all sectioning commands produce +unnumbered\Index{numbering} headings which do not appear in the table of +contents\Index{table>of contents}\Index{contents>table of} or in the running +head\Index{running head}. The absence of a running head often has an unwanted +side effect. If, for example, a chapter set using \Macro{chapter*} spans +several pages, then the running head of the previous chapter suddenly +reappears. {\KOMAScript} offers a solution for this problem, described below. +\Macro{chapter*}\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} only exists in +book and report classes, that is, \Class{book}, \Class{scrbook}, +\Class{report} and \Class{scrreport}, not in the article classes +\Class{article} and \Class{scrartcl}. + +Please\textnote{Attention!} note that \DescRef{\LabelBase.cmd.part} and +\DescRef{\LabelBase.cmd.chapter} change the page style for one page. While the +standard classes use the \PageStyle{plain} page style, {\KOMAScript} applies +the style defined in the \DescRef{\LabelBase.cmd.partpagestyle} and +\DescRef{\LabelBase.cmd.chapterpagestyle} macros (see +\autoref{sec:\LabelBase.pagestyle}, +\DescPageRef{\LabelBase.cmd.titlepagestyle}). + +The possibilities for switching fonts\ChangedAt{v2.8p}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} % +described above for the unstarred variants apply without change. The elements +use the same names since they do not indicate variants but structuring +levels.% +% +\EndIndexGroup + + +\iffalse% Umbruchkorrekturtext + In the standard classes\textnote{\KOMAScript{} vs. standard classes} there + are no further structuring commands. In particular, there are no commands + which can produce unnumbered chapters or sections which show up in the table + of contents and in the running heading.% +\fi + + +\begin{Declaration} + \Macro{addpart}\OParameter{short version}\Parameter{heading}% + \Macro{addpart*}\Parameter{heading}% + \Macro{addchap}\OParameter{short version}\Parameter{heading}% + \Macro{addchap*}\Parameter{heading}% + \Macro{addsec}\OParameter{short version}\Parameter{heading}% + \Macro{addsec*}\Parameter{heading} + \textnote[n]{\KOMAScript{} vs. standard classes} +\end{Declaration}% +In addition to the commands of the standard classes, {\KOMAScript} offers the +new commands \Macro{addpart}, \Macro{addsec} and \Macro{addchap}. They are +similar to the standard commands \DescRef{\LabelBase.cmd.part}\IndexCmd{part}% +\important{\DescRef{\LabelBase.cmd.part}, \DescRef{\LabelBase.cmd.chapter}, + \DescRef{\LabelBase.cmd.section}}, +\DescRef{\LabelBase.cmd.chapter}\IndexCmd{chapter} and +\DescRef{\LabelBase.cmd.section}\IndexCmd{section} except that they are +unnumbered. They thus produce both a running head and an entry in the table of +contents. + +The starred variants \Macro{addchap*} and \Macro{addsec*} are similar to the +standard commands \DescRef{\LabelBase.cmd.chapter*} and +\DescRef{\LabelBase.cmd.section*} except for a small but important difference: +the running heads are deleted. This eliminates the side effect of obsolete +headers mentioned above. Instead, the running heads on subsequent pages remain +empty. \OnlyAt{\Class{book}\and \Class{scrreprt}}\Macro{addchap} and +\Macro{addchap*} only exist, of course, in book and report classes, namely +\Class{book}, \Class{scrbook}, \Class{report} and \Class{scrreport}, not in +the article classes \Class{article} and \Class{scrartcl}. + +The \Macro{addpart} command produces an unnumbered document part with an +entry in the table of contents. Since the running heads are already deleted +by \DescRef{\LabelBase.cmd.part} and \DescRef{\LabelBase.cmd.part*} the +previously mentioned problem with obsolete headers does not exist. The starred +version \Macro{addpart*} is thus identical to \DescRef{\LabelBase.cmd.part*} +and is only defined for reasons of consistency. + +Please note\textnote{Attention!} that \Macro{addpart} and \Macro{addchap} and +their starred variants change the page style for one page. The particular page +style is defined in the macros \DescRef{\LabelBase.cmd.partpagestyle} and +\DescRef{\LabelBase.cmd.chapterpagestyle} (see +\autoref{sec:\LabelBase.pagestyle}, +\DescPageRef{\LabelBase.cmd.titlepagestyle}). +\iffree{\iffalse}{\csname iftrue\endcsname}% Umbruchkorrekturbeispiel + \begin{Example} + You write a book with a long afterword that spans several pages. This + should receive neither a running head nor an entry in the table of + contents. Therefore, you first use \DescRef{\LabelBase.cmd.chapter*}: +\begin{lstcode} + \documentclass{scrbook} + \usepackage{blindtext} + \begin{document} + \tableofcontents + \blinddocument + \chapter*{Afterword} + \Blindtext[10] + \end{document} +\end{lstcode} + However, you discover that the running head of the previous chapter + reappears on the second and third pages of the afterword. Naturally, you do + not want that. Therefore, you use \Macro{addchap*}: +\begin{lstcode} + \documentclass{scrbook} + \usepackage{blindtext} + \begin{document} + \tableofcontents + \blinddocument + \addchap*{Afterword} + \Blindtext[10] + \end{document} +\end{lstcode} + The complete postscript is now without a running head, if that is what you + want. But even that does not quite meet your expectations. A running head + would be nice. With +\begin{lstcode} + \documentclass{scrbook} + \usepackage{blindtext} + \begin{document} + \tableofcontents + \blinddocument + \addchap{Afterword} + \Blindtext[10] + \end{document} +\end{lstcode} + you now get both ``Afterword'' as the running head on the even pages and an + entry in the table of contents. But this entry bothers your publisher. He + insists that the afterword have no entry in the table of contents. Even if + that seems strange to you, you want to satisfy the publisher, so with + \OptionValueRef{\LabelBase}{headings}{optiontotocandhead} you first + activate the extended function for the optional argument and then + explicitly set an empty argument for the table of contents: +\begin{lstcode} + \documentclass[headings=optiontotocandhead] + {scrbook} + \usepackage{blindtext} + \begin{document} + \tableofcontents + \blinddocument + \addchap[tocentry={}]{Afterword} + \Blindtext[10] + \end{document} +\end{lstcode} + The running head is not changed by \OptionValue{tocentry}{\{\}}. Since + \Class{scrbook} automatically omits empty entries in the table of contents, + the publisher is now satisfied. + \end{Example}% +\fi + +The possibilities for switching fonts\ChangedAt{v2.8p}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} % +described above for the unstarred variant of the sectioning commands apply +without change. The elements have the same names since they do not designate +variants but sectioning levels.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{minisec}\Parameter{heading} +\end{Declaration}% +Sometimes you want a heading\Index{heading} that is highlighted but also +closely linked to the following text. Such a heading should not be separated +by a large vertical skip. + +The \Macro{minisec} command is designed for this situation. This heading is +not associated with any sectioning level\textnote{no sectioning level}. Such a +\emph{mini-section} does not produce an entry in the table of contents, nor +does it receive any numbering. + +\BeginIndexGroup +\BeginIndex{FontElement}{minisec}\LabelFontElement{minisec}% +You can change the font of the \Macro{minisec} command using the +\DescRef{\LabelBase.fontelement.disposition}% +\important{\DescRef{\LabelBase.fontelement.disposition}\\ +\FontElement{minisec}} and \FontElement{minisec}\ChangedAt{v2.96a}{% + \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} element (see +\autoref{tab:maincls.fontelements}, \autopageref{tab:maincls.fontelements}). +The default of the \FontElement{minisec} element is empty, so by default only +the \DescRef{\LabelBase.fontelement.disposition} element is used.% +\EndIndexGroup + +\begin{Example} + You have developed a kit for building a mouse trap and want the + documentation separated into a list of necessary items and an + assembly description. You could write the following: +\begin{lstcode} + \documentclass{scrartcl} + + \begin{document} + + \title{DIY Projects} + \author{Two Left Thumbs} + \date{\today} + \maketitle + + \section{Mousetrap} + + The first project is suitable for beginners and only requires + a few components that should be found in every household. + + \minisec{Material Required} + + \begin{flushleft} + 1 board ($100\times 50 \times 12$)\\ + 1 swing-top cap of a beer-bottle\\ + 1 ballpoint pen\\ + 1 push pin\\ + 2 screws\\ + 1 hammer\\ + 1 knife + \end{flushleft} + + \minisec{Assembly} + First, find the mouse hole and put the push pin directly behind + the hole so that the mouse cannot escape during the following + actions. + + Next tap the swing-top cap into the mouse hole with the hammer. + If the cap is not big enough to block the hole completely and + permanently, take the board instead and screw it to the front + of the mouse hole using the two screws and the knife. Of + course, you can use a screwdriver instead of a knife. The + ballpoint pen has fallen victim to animal welfare. + \end{document} +\end{lstcode} + The main part, starting with the heading ``Material Required'' will look + like this: + \begin{ShowOutput}[\baselineskip]\setlength{\parindent}{1em} + \minisec{Material Required} + + \begin{flushleft} + 1 board ($100\times 50 \times 12$)\\ + 1 swing-top cap of a beer-bottle\\ + 1 ballpoint pen\\ + 1 push pin\\ + 2 screws\\ + 1 hammer\\ + 1 knife + \end{flushleft} + + \minisec{Assembly} + First, find the mouse hole and put the push pin directly behind the hole + so that the mouse cannot escape during the following actions. + + Next tap the swing-top cap into the mouse hole with the hammer. If the cap + is not big enough to block the hole completely and permanently, take the + board instead and screw it to the front of the mouse hole using the two + screws and the knife. Of course, you can use a screwdriver instead of a + knife. The ballpoint pen has fallen victim to animal welfare. + \end{ShowOutput} +\end{Example} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{raggedsection}% + \Macro{raggedchapter}% + \Macro{raggedpart} +\end{Declaration}% +In the standard classes\textnote{\KOMAScript{} vs. standard classes}, headings +are set as justified text. That means that hyphenated words can occur and +multi-line headings are stretched up to the text width. This approach is +rather uncommon in typography. {\KOMAScript} therefore sets the +headings left aligned with hanging indentation using \Macro{raggedsection} +with the default: +\begin{lstcode} + \newcommand*{\raggedsection}{\raggedright} +\end{lstcode} +You can redefine this command with \Macro{renewcommand}. +\begin{Example} + You prefer justified headings, so you write in the preamble of your document: +\begin{lstcode} + \renewcommand*{\raggedsection}{} +\end{lstcode} + or more compactly: +\begin{lstcode} + \let\raggedsection\relax +\end{lstcode} + You will get heading formatting which is very close to that of the standard + classes. It will become even closer when you combine this change with the + change to the + \DescRef{\LabelBase.fontelement.disposition}\IndexFontElement{disposition} + element mentioned above. +\end{Example} + +Because\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}} some users want +a different alignment for the \DescRef{\LabelBase.cmd.chapter} level than for +the other sectioning levels, you can change the +\DescRef{\LabelBase.cmd.chapter} justification separately by redefining +\Macro{raggedchapter}. By default, however, this command simply uses +\Macro{raggedsection}, so changing \Macro{raggedsection} indirectly affects +\Macro{raggedchapter}. + +By default, part headings (\DescRef{\LabelBase.cmd.part}) are set horizontally +centred rather than ragged right. This formatting is performed by the +\Macro{raggedpart} statement, which has the default definition +\begin{lstcode} + \let\raggedpart\centering +\end{lstcode} +You can also redefine this command using \Macro{renewcommand}. +\begin{Example} + You want the headings for \DescRef{\LabelBase.cmd.part} to be formatted the + same as any other sectioning command. To do so, put +\begin{lstcode} + \renewcommand*{\raggedpart}{\raggedsection} +\end{lstcode} + in the preamble of your document. In\textnote{Hint!} this case, and unlike + in the example above, we did not use \Macro{let} because \Macro{let} would + set \Macro{raggedpart} to the underlying value of \Macro{raggedsection}. + Subsequent changes to \Macro{raggedsection} would then not change the + behaviour of \Macro{raggedpart}. By redefining with \Macro{renewcommand}, + \Macro{raggedpart} will use the current meaning of \Macro{raggedsection} at + the time it is used rather than when it was redefined. +\end{Example}% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{partformat} + \Macro{chapterformat} + \Macro{sectionformat} + \Macro{subsectionformat} + \Macro{subsubsectionformat} + \Macro{paragraphformat} + \Macro{subparagraphformat} + \Macro{othersectionlevelsformat}\Parameter{sectioning name}\Parameter{} + \Parameter{counter output} + \Macro{IfUsePrefixLine}\Parameter{then code}\Parameter{else code} + \Macro{autodot} +\end{Declaration}% +{\KOMAScript} adds another logical layer above \Macro{the\PName{sectioning + name}} to format the sectioning numbers. The counters for each heading are +not merely output. They are formatted using the commands \Macro{partformat}, +\Macro{chapterformat}, down to +\Macro{subparagraphformat}\ChangedAt{v3.17}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}. Of course the \Macro{chapterformat} +command, like \Macro{thechapter}, does not exist in the \Class{scrartcl} +class, but only in the \Class{scrbook} and \Class{scrreprt} +classes.\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} + +As already explained for the \DescRef{\LabelBase.option.numbers}% +\important{\DescRef{\LabelBase.option.numbers}} option at the beginning of +this section (see \DescPageRef{\LabelBase.option.numbers}), {\KOMAScript}'s +handling of points in section numbers implements the rules given in +\cite{DUDEN}, which are standard in German-language typography, in the +\Macro{autodot} command. In all levels except for +\DescRef{\LabelBase.cmd.part}, a point is followed by a further +\Macro{enskip}. This corresponds to a horizontal skip of 0.5\Unit{em}. + +Since \KOMAScript~3.17\ChangedAt{v3.17}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}, the command +\Macro{othersectionlevelsformat} is used only in rare circumstances, i.\,e., +if the corresponding format command to a section command does not exist or is +\Macro{relax}. This should not happen for any section commands defined by +\KOMAScript{} itself. Therefore the command is no longer officially +documented. Nevertheless, if you select a compatibility level prior to +3.17\important{\OptionValueRef{\LabelBase}{version}{3.17}} (see option +\DescRef{\LabelBase.option.version}, +\autoref{sec:\LabelBase.compatibilityOptions}, +\DescPageRef{\LabelBase.option.version}), commands \Macro{sectionformat} down +to \Macro{subparagraphformat} are ignored by \KOMAScript{}. Instead, these +layers will continue to use \Macro{othersectionlevelsformat}. + +You can redefine the formatting commands using \Macro{renewcommand} to fit +them to your personal needs. The following default definitions are used by the +{\KOMAScript} classes: +\begin{lstcode} + \newcommand*{\partformat}{\partname~\thepart\autodot} + \newcommand*{\chapterformat}{% + \mbox{\chapappifchapterprefix{\nobreakspace}\thechapter + \autodot\IfUsePrefixLine{}{\enskip}}} + \newcommand*{\sectionformat}{\thesection\autodot\enskip} + \newcommand*{\subsectionformat}{% + \thesubsection\autodot\enskip} + \newcommand*{\subsubsectionformat}{% + \thesubsubsection\autodot\enskip} + \newcommand*{\paragraphformat}{\theparagraph\autodot\enskip} + \newcommand*{\subparagraphformat}{% + \thesubparagraph\autodot\enskip} + \newcommand*{\othersectionlevelsformat}[3]{% + #3\autodot\enskip} +\end{lstcode} + +Because\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}} it uses +\Macro{IfUsePrefixLine}, \Macro{chapterformat} should not be used outside of +\DescRef{\LabelBase.cmd.chapter}. \Macro{IfUsePrefixLine} is only valid inside +\KOMAScript{} sectioning commands. Within those commands, it executes the +\PName{then code} if a prefix line for the number is used and the \PName{else +code} otherwise. + +Please also remember\textnote{Attention!} to replace \Macro{newcommand} with +\Macro{renewcommand} if you want to redefine one of the commands above. + +\begin{Example} + Suppose you do not want the word ``Part'' written in front of the part + number when you use \DescRef{\LabelBase.cmd.part}. You can put the + following command in the preamble of your document: +\begin{lstcode} + \renewcommand*{\partformat}{\thepart\autodot} +\end{lstcode} + In fact, you could do without \Macro{autodot} here and insert a fixed point + instead. Since \DescRef{\LabelBase.cmd.part} is numbered with Roman numerals, + it must be followed by a point according to \cite{DUDEN}. However, by using + \Macro{autodot} you retain the ability to use the + \DescRef{\LabelBase.option.numbers}% + \important{\DescRef{\LabelBase.option.numbers}} option + \OptionValueRef{\LabelBase}{numbers}{endperiod} and thus deviate from + the rule. You can find more details concerning class options on + \DescPageRef{\LabelBase.option.numbers}. + + Another possibility is to place the section numbers in the left margin in + such a way that the heading text is left aligned with the surrounding text. + You can accomplish this with: +\begin{lstcode} + \renewcommand*{\sectionformat}{% + \makebox[0pt][r]{\thesection\autodot\enskip}} + \renewcommand*{\subsectionformat}{% + \makebox[0pt][r]{\thesubsection\autodot\enskip}} + \renewcommand*{\subsubsectionformat}{% + \makebox[0pt][r]{% + \thesubsubsection\autodot\enskip}} + \renewcommand*{\paragraphformat}{% + \makebox[0pt][r]{\theparagraph\autodot\enskip}} + \renewcommand*{\paragraphformat}{% + \makebox[0pt][r]{% + \thesubparagraph\autodot\enskip}} +\end{lstcode} + The optional arguments of the \Macro{makebox} command require \LaTeX{} to + create a zero-width box with right-justified content. As a result, the + contents of the box are output to the left of the current position.% + \iffree{}{ %Umbruchkorrekturtext + This popular trick avoids the need first to measure the width of the + number and the spacing, and then to change the current position + appropriately with \Macro{hspace}.} + You can find more about the optional arguments of \Macro{makebox} in + \cite{latex:usrguide}. +\end{Example} + +For formatting changes in the headings that go beyond merely formatting the +unit number, please refer to +\DescRef{maincls-experts.cmd.partlineswithprefixformat}% +\IndexCmd{partlineswithprefixformat}, +\DescRef{maincls-experts.cmd.chapterlineswithprefixformat}% +\IndexCmd{chapterlineswithprefixformat} and +\DescRef{maincls-experts.cmd.chapterlinesformat}\IndexCmd{chapterlinesformat}, +as well as +\DescRef{maincls-experts.cmd.sectionlinesformat}\IndexCmd{sectionlinesformat} +and its \DescRef{maincls-experts.cmd.sectioncatchphraseformat}% +\IndexCmd{sectioncatchphraseformat} format in +\autoref{sec:maincls-experts.experts}, starting from +\DescPageRef{maincls-experts.cmd.partlineswithprefixformat}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{chapappifchapterprefix}\Parameter{additional text}% + \Macro{chapapp} +\end{Declaration}% +These\ChangedAt{v2.8o}{\Class{scrbook}\and\Class{scrreprt}} two commands are +used internally by {\KOMAScript} and also made available to the user. Later, +you will see how to use them, for example to redefine other commands.% +\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} + +If you use the layout option \OptionValueRef{\LabelBase}{chapterprefix}{true}% +\important{\DescRef{\LabelBase.option.chapterprefix}} (see +\DescPageRef{\LabelBase.option.chapterprefix}), \Macro{chapappifchapterprefix} +outputs the word ``Chapter''\Index{chapter>heading} in the body of the text in +the current language, followed by \PName{additional text}. In the +appendix\Index{appendix}, the word ``Appendix'' in the current language is +output instead, followed by \PName{additional text}. If the option +\OptionValue{\LabelBase}{chapterprefix}{false} is set, then nothing is output. + +The \Macro{chapapp} command always outputs the word ``Chapter'' or +``Appendix'', regardless of the setting of the +\DescRef{\LabelBase.option.chapterprefix} option. + +Since chapters only exist in the classes \Class{scrbook} and \Class{scrreprt}, +these commands only exist in these classes.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{chaptermark}\Parameter{running head}% + \Macro{addchapmark}\Parameter{running head}% + \Macro{sectionmark}\Parameter{running head}% + \Macro{addsecmark}\Parameter{running head}% + \Macro{subsectionmark}\Parameter{running head}% + \Macro{chaptermarkformat}% + \Macro{sectionmarkformat}% + \Macro{subsectionmarkformat} +\end{Declaration}% +\begin{Explain}% + As mentioned in \autoref{sec:\LabelBase.pagestyle}, the + \DescRef{\LabelBase.pagestyle.headings}\IndexPagestyle{headings}% + \important{\DescRef{\LabelBase.pagestyle.headings}} page style works with + automatic running heads\Index{running heads>automatic}. For this, the + commands \Macro{chaptermark} and \Macro{sectionmark}, or \Macro{sectionmark} + and \Macro{subsectionmark}, are defined accordingly. Every sectioning + command (\DescRef{\LabelBase.cmd.chapter}, \DescRef{\LabelBase.cmd.section}, + etc.) automatically executes the corresponding \Macro{\dots mark} command. + The parameter passed contains the text of the section heading% + \Index{heading}. The corresponding section number is added automatically in + the \Macro{\dots mark} command. The formatting is done according to the + sectioning level with one of the three commands \Macro{chaptermarkformat}, + \Macro{sectionmarkformat}, or \Macro{subsectionmarkformat}. + + Note\textnote{Attention!} that the running heads of + \DescRef{\LabelBase.cmd.addchap}\IndexCmd{addchap} and + \DescRef{\LabelBase.cmd.addsec}\IndexCmd{addsec} are also based on + \Macro{chaptermark} and \Macro{sectionmark}. However, the + \DescRef{\LabelBase.counter.secnumdepth} counter is set locally to a value + that switches off the numbering of chapters or sections. You should consider + this, for example, if you redefine \Macro{chaptermark} or + \Macro{sectionmark} (see \Macro{ifnumbered} on + \DescPageRef{\LabelBase.cmd.ifnumbered}). The starred variants + \DescRef{\LabelBase.cmd.addchap*} and \DescRef{\LabelBase.cmd.addsec*} use + additional commands \Macro{addchapmark} and \Macro{addsecmark} that are also + defined based on \Macro{chaptermark} and \Macro{sectionmark} with local + changes of \DescRef{\LabelBase.counter.secnumdepth}. + + Although\OnlyAt{\Class{scrartcl}} there is no \Macro{chaptermark} or + \Macro{chaptermarkformat} command in \Class{scrartcl}, there are two + commands, \Macro{subsectionmark} and \Macro{subsectionmarkformat}, which + exist only in \Class{scrartcl}. However using the + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + \IndexPackage{scrlayer-scrpage} package changes this (see + \autoref{cha:scrlayer-scrpage}). +\end{Explain} +Just as numbers in the sectioning-command headers are formatted with +\DescRef{\LabelBase.cmd.partformat} down to +\DescRef{\LabelBase.cmd.subparagraphformat}, \Macro{chaptermarkformat}, +\Macro{sectionmarkformat}, and \Macro{subsectionmarkformat} define the +formatting of the sectioning numbers in the automatic running heads. They can +be adapted to your personal needs with \Macro{renewcommand}. The original +definitions for the {\KOMAScript} classes are: +\begin{lstcode} + \newcommand*{\chaptermarkformat}{% + \chapappifchapterprefix{\ }\thechapter\autodot\enskip} + \newcommand*{\sectionmarkformat}{% + \thesection\autodot\enskip} + \newcommand*{\subsectionmarkformat}{% + \thesubsection\autodot\enskip} +\end{lstcode} +\begin{Example} + Suppose you want the word ``Chapter'' to precede the chapter number in the + running head. You could put the following definition in the preamble of your + document: +\begin{lstcode} + \renewcommand*{\chaptermarkformat}{% + \chapapp~\thechapter\autodot\enskip} +\end{lstcode} +\end{Example} +As you can see, both \DescRef{\LabelBase.cmd.chapapp} and +\DescRef{\LabelBase.cmd.chapappifchapterprefix}, explained above, are used +here.% +\EndIndexGroup + + +\begin{Declaration} + \Counter{secnumdepth} + \Macro{partnumdepth} + \Macro{chapternumdepth} + \Macro{sectionnumdepth} + \Macro{subsectionnumdepth} + \Macro{subsubsectionnumdepth} + \Macro{paragraphnumdepth} + \Macro{subparagraphnumdepth} +\end{Declaration}% +\BeginIndex{}{Nummerierung}% +Normally, the \Class{scrbook}\IndexClass{scrbook} and +\Class{scrreport}\IndexClass{scrreprt} classes number the section headings +from \DescRef{\LabelBase.cmd.part}\IndexCmd{part}\IndexCmd{chapter}% +\IndexCmd{section} down to +\DescRef{\LabelBase.cmd.subsection}\IndexCmd{subsection} and the +\Class{scrartcl}\IndexClass{scrartcl} class numbers them from +\DescRef{\LabelBase.cmd.part} down to +\DescRef{\LabelBase.cmd.subsubsection}\IndexCmd{subsubsection}. The actual +depth to which headings are numbered is controlled by the \LaTeX{} counter +\Counter{secnumdepth}. + +To\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} +save users the trouble of having to remember abstract numbers, the commands +\Macro{partnumdepth} to \Macro{subparagraphnumdepth} return the appropriate +number for the section level in their name. + +\begin{Example} + For a book project, you want the section levels from part down to section + to be numbered. To achieve this, you have to set counter + \Counter{secnumdepth} to the value represented by \Macro{sectionnumdepth} in + the preamble of your document: +\begin{lstcode} + \setcounter{secnumdepth}{\sectionnumdepth} +\end{lstcode} +\end{Example} +No provision is made for redefining these commands. Doing so could lead to +unexpected results, not only with \KOMAScript{} but also with third party +packages. Thus, you should never redefine them. + +Do\textnote{Attention!} not confuse the \Counter{secnumdepth} and +\DescRef{\LabelBase.counter.tocdepth} counters (see +\autoref{sec:\LabelBase.toc}, \DescPageRef{\LabelBase.counter.tocdepth}). +Depending on the class you are using, the meaning of the values of the +\Counter{secnumdepth} and \DescRef{\LabelBase.counter.tocdepth} counters may +differ for the same section level.% +% +\EndIndexGroup + +\begin{Declaration} + \Macro{ifnumbered}\Parameter{section level}% + \Parameter{then code}\Parameter{else code}% + \Macro{ifunnumbered}\Parameter{section level}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +The\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} commands \Macro{ifnumbered} and \Macro{ifunnumbered} +determine which section-level headings are numbered, using the technique +described above, and execute code depending on whether a \PName{section level} +is numbered or not. If a \PName{section level} is numbered with the current +settings, \Macro{ifnumbered} executes the \PName{then code}. If the section +level is unnumbered, the \PName{else code} is executed. The +\Macro{ifunnumbered} command behaves in exactly the opposite manner, executing +the \PName{then code} if the current level is unnumbered and the \PName{else + code} if it is. The \PName{section level} parameter is simply the \LaTeX{} +name of a section like \PValue{part}, \PValue{chapter}, \PValue{section}, +\PValue{subsection}, \PValue{subsubsection}, \PValue{paragraph} oder +\PValue{subparagraph}.\PValue{part}, \PValue{chapter}, \PValue{section}, +\PValue{subsection}, \PValue{subsubsection}, \PValue{paragraph}, or +\PValue{subparagraph}. + +\KOMAScript{} itself uses these tests, for example, in the definition of +\DescRef{\LabelBase.cmd.chaptermark}\IndexCmd{chaptermark} in the +\DescRef{\LabelBase.pagestyle.headings}\IndexPagestyle{headings} page style. +This indirectly ensures that headings inserted by +\DescRef{\LabelBase.cmd.addchap} do not set a number inside the running head +(see also \DescRef{\LabelBase.cmd.addchapmark}, +\DescPageRef{\LabelBase.cmd.addchapmark}).% +\EndIndexGroup + + +\begin{Declaration} + \Macro{setpartpreamble}% + \OParameter{position}\OParameter{width}\Parameter{preamble} + \Macro{setchapterpreamble}% + \OParameter{position}\OParameter{width}\Parameter{preamble} +\end{Declaration}% +Parts\OnlyAt{\Class{scrbook}\and + \Class{scrreprt}}\Index{part>preamble}\Index{chapter>preamble} and chapters +in {\KOMAScript} can be given a \PName{preamble}. This is particularly useful +when you are using a two-column format with the class option +\Option{twocolumn}\IndexOption{twocolumn}, since the heading and the +\PName{preamble} are always set in a one-column layout. The \PName{preamble} +can contain more than one paragraph. The command to set the \PName{preamble} +must come before the respective \DescRef{\LabelBase.cmd.part}, +\DescRef{\LabelBase.cmd.addpart}, \DescRef{\LabelBase.cmd.chapter}, or +\DescRef{\LabelBase.cmd.addchap} command. +\begin{Example} + You are writing a report about the condition of a company. You organize the + report in such a way that every department gets its own partial report. + Each of these parts should be introduced by an abstract on the corresponding + title page. You could write the following: +\begin{lstcode} + \setpartpreamble{% + \begin{abstract} + This is a filler text. It serves merely to demonstrate the + capabilities of {\KOMAScript}. If you read this text, you will + get no information. + \end{abstract} + } + \part{Department for Word Processing} +\end{lstcode} + Depending on the settings for the heading font size\Index{heading} + (see \DescPageRef{\LabelBase.option.headings}) and the options for + the \DescRef{\LabelBase.env.abstract} environment\IndexEnv{abstract} (see + \autoref{sec:\LabelBase.abstract}, + \DescPageRef{\LabelBase.option.abstract}), the result will look something + like this: + \begin{ShowOutput}\centering + {\LARGE\usekomafont{disposition} Part III.\par\vspace{14pt}} + {\LARGE\usekomafont{disposition} Department for Word Processing\strut\par} + \begin{quote}\small + \vspace{4ex} + \begin{center} + \usekomafont{disposition}\abstractname + \end{center} + \vspace{2ex} + This is a filler text. It serves merely to demonstrate the + capabilities of {\KOMAScript}. If you read this text, you will + get no information. + \end{quote} + \end{ShowOutput} +\end{Example} +Please\textnote{Attention!} note that \emph{you} are responsible for the +spacing between the heading, preamble, and the following text. Note also that +there is no \DescRef{\LabelBase.env.abstract} environment in the +\Class{scrbook} class (see \autoref{sec:\LabelBase.abstract}, +\DescPageRef{\LabelBase.env.abstract}). + +The\ChangedAt{v2.8p}{\Class{scrbook}\and\Class{scrreprt}} first optional +argument, \PName{position}, determines the position at which the preamble +is placed with the help of one or two letters. For vertical placement +there are two possibilities at present: +\begin{labeling}[~--]{\quad\PValue{o}}\itemsep=0pt +\item [\quad\texttt{o}] above the heading +\item [\quad\texttt{u}] below the heading +\end{labeling} +You can therefore put one preamble above and another below a heading. For +horizontal placement you have three options: +\begin{labeling}[~--]{\quad\PValue{o}}\itemsep=0pt +\item [\quad\texttt{l}] left-aligned +\item [\quad\texttt{r}] right-aligned +\item [\quad\texttt{c}] centred +\end{labeling} +This setting does not affect the alignment of the text in the +\PName{preamble}. Instead, it aligns the box that contains the preamble. The +width of this box is determined by the second optional argument, +\PName{width}. If you omit this second argument, the box uses the full text +width. In that case, the option for horizontal positioning has no effect. You +can combine exactly one letter from the vertical with one letter from the +horizontal positioning. + +A typical use for \Macro{setchapterpreamble} would be something like an +epigraph, a wise saying, or a dictum. The +\DescRef{\LabelBase.cmd.dictum}\IndexCmd{dictum} command, which you can use +for this purpose, is described in the next section. You will also find an +example there. + +Please note\textnote{Attention!} that a \PName{preamble} placed above the +heading is set within the existing vertical space above the heading. The +heading will not be moved down. You are therefore responsible for ensuring +that the \PName{preamble} is not too large and that the space above the +heading is sufficient. See also the \Option{beforeskip} setting for +\DescRef{maincls-experts.cmd.RedeclareSectionCommand} in +\autoref{sec:maincls-experts.experts}, +\autoref{tab:maincls-experts.declarechapterstyle.keys}, +\autopageref{tab:maincls-experts.declarechapterstyle.keys}. +% +% +\EndIndexGroup +% +\EndIndexGroup + + +\LoadCommonFile{dictum}% \section{Dicta} + +\LoadCommonFile{lists}% \section{Lists} + +\section{Mathematics} +\seclabel{math}% +\BeginIndexGroup +\BeginIndex{}{equations}% +\BeginIndex{}{formulas}% +\BeginIndex{}{mathematics}% + +\KOMAScript{} classes do not provide their own environments for formulas, +systems of equations, or similar mathematical elements. Instead, \KOMAScript{} +relies fully on the maths features of the \LaTeX{} kernel. This also applies to +the the options \DescRef{\LabelBase.option.leqno} and +\DescRef{\LabelBase.option.fleqn}. + +You will not find a description of the maths environments of the \LaTeX{} +kernel here. If you want to use +\Environment{displaymath}\IndexEnv{displaymath}, +\Environment{equation}\IndexEnv{equation}, or +\Environment{eqnarray}\IndexEnv{eqnarray} you should read 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}). + +\begin{Declaration} + \Option{leqno} +\end{Declaration}% +Equations are normally numbered\Index{equation>number} on the right. The +\Option{leqno} option loads the standard option file \File{leqno.clo}. The +equations are then numbered on the left. You\textnote{Attention!} must use +this option as an optional argument of \DescRef{\LabelBase.cmd.documentclass}. +Using it as an argument of \DescRef{\LabelBase.cmd.KOMAoptions} or +\DescRef{\LabelBase.cmd.KOMAoption} is not supported. The latter +would not make sense because the recommended maths package \Package{amsmath} +can only respond to this option at load time and does not react to run-time +changes of the option. +% +\EndIndexGroup + + +\begin{Declaration} + \Option{fleqn} +\end{Declaration}% +Displayed equations\Index{equation>alignment} are normally centred. The +standard option \Option{fleqn} loads the standard option file +\File{fleqn.clo}. Displayed equations are then left-justified. +You\textnote{Attention!} must use this option as an optional argument of +\DescRef{\LabelBase.cmd.documentclass}. Using it as an argument of +\DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption} is +not supported. The latter would not make sense because the recommended maths +package \Package{amsmath} can only respond to this option at load time and +does not react to run-time changes of the option. +% +\EndIndexGroup +% +\EndIndexGroup + + +\section{Floating Environments for Tables and Figures} +\seclabel{floats} +\BeginIndexGroup +\BeginIndex{}{floats}% +\BeginIndex{}{tables}% +\BeginIndex{}{figures}% + +With the floating environments, {\LaTeX} offers a powerful and convenient +mechanism to arrange figures\Index{figure} and tables\Index{table} +automatically. +% Im Deutschen ist hier ein Absatz, den wir nicht uebernehmen! +Frequently,\textnote{Attention!} beginners do not properly understand these +floating environments\Index[indexmain]{floating environments}. They often ask +to specify the exact position of a table or figure within the text. However, +this is usually unnecessary, since the text will contain references to these +floating environments. It is also not sensible because such an object can only +be set on the page if there is enough space left for it. If this is not the +case, the object would have to be shifted onto the next page, possibly leaving +a huge empty space on the previous page. + +Often\textnote{Attention!} a document will use the same optional argument to +position every floating object. This also makes no sense. In such cases, you +should instead change the default value globally. For more details, see +\cite{DANTE:FAQ}. + +One\textnote{Attention!} final, important note before starting this section: +most of mechanisms described here, which extend the capabilities of the +standard classes, no longer work correctly when used with packages that modify +the appearance of figure and table captions. This should be self-evident, but +it is often overlooked. + + +\begin{Declaration} + \OptionVName{captions}{setting} +\end{Declaration} +In the standard classes, the titles of floating environments, which are +formatted with the \DescRef{\LabelBase.cmd.caption}\IndexCmd{caption} command +(see below), are set off from the float with vertical spacing appropriate for +putting the caption beneath the float, like a signature. They also distinguish +between one-line and multi-line captions. One-line captions are centred while +multi-line captions are left-justified. + +\leavevmode\LabelOptionValue{captions}{tableheading}\nobreak% +For tables, however, you want the caption% +\important{\Option{captions}{tableheading}} to appear as a heading instead of +a signature. That's because tables can span multiple pages. With such tables, +the reader wants to know the purpose of the table on the first page. +Furthermore, tables are usually read row by row, from top to bottom. So there +are normally at least two good reasons to provide all tables with headings. +\KOMAScript{} therefore offers the \OptionValue{captions}{tableheading}% +\IndexOption{captions~=\textKValue{tableheading}} option, which changes the +formatting of table captions for use above the table. + +Note\textnote{Attention!} that multi-page tabulars cannot use a floating +environment. To have an automatic page break in a tabular you need an +additional package like \Package{longtable}\IndexPackage{longtable} (see +\cite{package:longtable}) or \Package{supertabular}\IndexPackage{supertabular} +(see \cite{package:supertabular}). + +You\important{\OptionValue{captions}{tablesignature}} can switch back to the +default caption formatting using \OptionValue{captions}{tablesignature}% +\IndexOption{captions~=\textKValue{tablesignature}}. Note\textnote{Attention!} +that these options change only the formatting, not the actual position of the +caption. Whether the caption is placed above or below a float depends solely +upon where you use the \DescRef{\LabelBase.cmd.caption} command inside float +environment. However, this can change when using the \Package{float}% +\IndexPackage{float} package with the \Macro{restylefloats} command (see +\cite{package:float}). + +Of course\important{\OptionValue{captions}{figureheading}\\ + \OptionValue{captions}{figuresignature}}, corresponding functions +exist\ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} for figures using the options +\OptionValue{captions}{figureheading}% +\IndexOption{captions~=\textKValue{figureheading}} and +\OptionValue{captions}{figuresignature}% +\IndexOption{captions~=\textKValue{figuresignature}}. However, figures such as +photos tend to be viewed as a whole, and a diagram or graph will mostly be +examined starting from the lower left. Therefore, it only rarely makes sense +to change the caption format for figures alone from signatures to headings. + +Sometimes, however, all floating environments should use headings. Therefore +\KOMAScript{} provides\ChangedAt{v3.09}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} +options\important{\OptionValue{captions}{heading}\\ + \OptionValue{captions}{signature}} +\OptionValue{captions}{heading}\IndexOption{captions~=\textKValue{heading}} +and \OptionValue{captions}{signature}% +\IndexOption{captions~=\textKValue{signature}} to switch the format of every +floating environment. These options can also be used inside a floating +environment. + +Please note\textnote{Achtung!}\OnlyAt{\Package{float}}\IndexPackage{float} +when using the \Package{float} package that the settings for signatures or +headings will no longer work once \Macro{restylefloat} is applied to tables or +figures. For details about the \Package{float} package and +\Macro{restylefloat}, please refer to \cite{package:float}. This also applies +to \DescRef{\LabelBase.cmd.caption} within new floating environments defined +with \Package{float}. You can find additional support which \KOMAScript{} +provides when using the \Package{float} package in the explanation of +\PValue{komaabove} (see \DescPageRef{\LabelBase.floatstyle.komaabove}). As an +alternative to \Package{float}, you can also consult +\DescRef{\LabelBase.cmd.captionof} (see +\DescPageRef{\LabelBase.cmd.captionof}) and +\DescRef{tocbasic.cmd.DeclareNewTOC} (see +\DescPageRef{tocbasic.cmd.DeclareNewTOC}). Additionally, when using +\Package{float}, the +\hyperref[cha:scrhack]{\Package{scrhack}}\IndexPackage{scrhack}% +\important{\hyperref[cha:scrhack]{\Package{scrhack}}} package is +expressly recommended (see \autoref{cha:scrhack} from +\autopageref{cha:scrhack} in \autoref{part:forExperts}). + +\leavevmode +\LabelOptionValue{captions}{nooneline}\nobreak +\LabelOptionValue{captions}{oneline}\nobreak +Furthermore\important{\OptionValue{captions}{nooneline}}, \KOMAScript{} offers +the option to disable the distinction between one-line and multi-line captions +using the \OptionValue{captions}{nooneline}% +\IndexOption{captions~=\textKValue{nooneline}}% +\important{\OptionValue{captions}{nooneline}} option. This can be useful, for +example, if you do not want one-line captions to be centred. The default, +where one-line captions are centred, corresponds to +\OptionValue{captions}{oneline}. + +Another special feature of \KOMAScript{} is the ability to put the caption +beside the floating object rather than above or below it. For this, you need +the environment\important{\DescRef{\LabelBase.env.captionbeside}} +\DescRef{\LabelBase.env.captionbeside}\IndexEnv{captionbeside}, which is +explained starting on \DescPageRef{\LabelBase.env.captionbeside}. The settings +for this environment can also be changed with the \Option{caption} option. You +can find the available values for the corresponding \PName{settings} in +\autoref{tab:\LabelBase.captions}. +% +\begin{desclist} + \desccaption[{Available values for the \Option{captions}} option]{% + Available values for the \Option{captions} option for setting formatting of + captions as headings or signatures in floating environments% + \label{tab:\LabelBase.captions}% + }{% + Available values for the \Option{captions} option (\emph{continued})% + }% + \entry{\PValue{bottombeside}, \PValue{besidebottom}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see + \autoref{sec:\LabelBase.floats}, + \DescPageRef{\LabelBase.env.captionbeside}) are vertically aligned with + the bottommost baseline of the contents of the floating environment.% + \IndexOption{captions~=\textKValue{bottombeside}}}% + \entry{\PValue{centeredbeside}, \PValue{besidecentered}, + \PValue{middlebeside}, \PValue{besidemiddle}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see + \autoref{sec:\LabelBase.floats}, + \DescPageRef{\LabelBase.env.captionbeside}) are vertically aligned with + the center of the contents of the floating environment.% + \IndexOption{captions~=\textKValue{centeredbeside}}}% + \entry{\PValue{figureheading}, \PValue{figureabove}, \PValue{abovefigure}, + \PValue{topatfigure}% + \IndexOption{captions~=\textKValue{figureheading}}}{% + \ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + Captions for figures use heading format\,---\,possibly deviating from + \OptionValue{captions}{signature}.% + }% + \entry{\PValue{figuresignature}, \PValue{belowfigure}, + \PValue{bottomatfiggure}% + \IndexOption{captions~=\textKValue{figuresignature}}}{% + \ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + Captions for figures use signature format\,---\,possibly deviating + from \OptionValue{captions}{headings}.% + }% + \entry{\PValue{heading}, \PValue{above}, \PValue{top}% + \IndexOption{captions~=\textKValue{heading}}}{% + \ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} Captions for floating environments use formatting + suitable for use in a heading. This setting does not control whether they + are placed at the top or the bottom of the object. This option also + implies \OptionValue{captions}{tableheading} and + \OptionValue{captions}{figureheading}.% + }% + \entry{\PValue{innerbeside}, + \PValue{besideinner}\IndexOption{captions~=\textKValue{innerbeside}}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see + \autoref{sec:\LabelBase.floats}, + \DescPageRef{\LabelBase.env.captionbeside}) are placed inside of and next + to the contents of the environment in two-sided printing. In one-sided + printing, \OptionValue{captions}{leftbeside} is used.% + }% + \entry{\PValue{leftbeside}, + \PValue{besideleft}\IndexOption{captions~=\textKValue{leftbeside}}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see + \autoref{sec:\LabelBase.floats}, + \DescPageRef{\LabelBase.env.captionbeside}) are placed to the left of + the contents of the floating environment.% + }% + \pventry{nooneline}{% + Single-line captions are handled the same as multi-line captions.% + \IndexOption{captions~=\textKValue{nooneline}}}% + \pventry{oneline}{% + Single-line captions are centred horizontally.% + \IndexOption{captions~=\textKValue{oneline}}}% + \entry{\PValue{outerbeside}, \PValue{besideouter}% + \IndexOption{captions~=\textKValue{outerbeside}}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see + \autoref{sec:\LabelBase.floats}, + \DescPageRef{\LabelBase.env.captionbeside}) are placed outside of and + next to the contents of the environment in two-sided printing. In + one-sided printing, \OptionValue{captions}{rightbeside} is used.% + }% + \entry{\PValue{rightbeside}, \PValue{besideright}% + \IndexOption{captions~=\textKValue{rightbeside}}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see + \autoref{sec:\LabelBase.floats}, + \DescPageRef{\LabelBase.env.captionbeside}) are placed to the right of the + contents of the floating environment.% + }% + \entry{\PValue{signature}, \PValue{below}, \PValue{bot}, \PValue{bottom}% + \IndexOption{captions~=\textKValue{signature}}}{% + \ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + Captions for floating environments use signature format. This setting + does not control whether they are placed at the top or the bottom of the + object. This options also implies \OptionValue{captions}{tablesignature} + and \OptionValue{captions}{figuresignature}.% + }% + \entry{\PValue{tableheading}, \PValue{tableabove}, \PValue{abovetable}, + \PValue{abovetabular}, \PValue{topattable}% + \IndexOption{captions~=\textKValue{tableheading}}}{% + Captions for tables use heading format\,---\,possibly deviating from + \OptionValue{captions}{signature}.% + }% + \entry{\PValue{tablesignature}, \PValue{belowtable}, \PValue{belowtabular}, + \PValue{bottomattable}% + \IndexOption{captions~=\textKValue{tablesignature}}}{% + Captions for tables use signature format\,---\,possibly deviating + from \OptionValue{captions}{heading}.% + }% + \entry{\PValue{topbeside}, \PValue{besidetop}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see + \autoref{sec:\LabelBase.floats}, + \DescPageRef{\LabelBase.env.captionbeside}) are vertically aligned to the + baseline at the top of the floating environment.% + \IndexOption{captions~=\textKValue{topbeside}}}% +\end{desclist}% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{caption}\OParameter{entry}\Parameter{title} + \Macro{captionbelow}\OParameter{entry}\Parameter{title} + \Macro{captionabove}\OParameter{entry}\Parameter{title} +\end{Declaration}% +In the standard classes, tables and figures are given captions with the +\Macro{caption} command placed below the table or figure. For figures, this is +generally correct. For tables, opinions differ as to whether captions should +be placed above the table or, consistent with captions of +figures\Index{caption>of figure}, below it\Index{caption>of table}. Therefore +{\KOMAScript}\textnote{\KOMAScript{} vs. standard classes}, +unlike the standard classes, offers \Macro{captionbelow} for captions +below and \Macro{captionabove} for captions above tables or +figures. + +For tables and figures, or in general for all floating environments, you can +control the behaviour of \Macro{caption} with the +\DescRef{\LabelBase.option.captions}\IndexOption{captions} option described at +the beginning of this section. For compatibility reasons, the default +behaviour of \Macro{caption} for all floating environments is like +\Macro{captionbelow}. However, you\textnote{Hint!} should use the +\OptionValueRef{\LabelBase}{captions}{tableheading} option, which switches the +behaviour of \Macro{caption} inside table environments to +\Macro{captionabove}. Alternatively, you can use \Macro{captionabove} instead +of \Macro{caption} inside every \Environment{table} environment. +% +\begin{Example} + Instead of using captions below a table, you want to place your + captions above it\Index{table>caption}, because you have tables + which span more then one page. In the standard classes you could + only write: +\begin{lstcode} + \begin{table} + \caption{This is an example table} + \begin{tabular}{llll} + This & is & an & example.\\\hline + This & is & an & example.\\ + This & is & an & example. + \end{tabular} + \end{table} +\end{lstcode} + Then you would get this unsatisfying result: + \begin{ShowOutput}\centering + {\usekomafont{caption}{\usekomafont{captionlabel}\tablename~30.2:} + This is an example table.}\\ + \begin{tabular}{llll} + This & is & an & example.\\\hline + This & is & an & example.\\ + This & is & an & example. + \end{tabular} +\end{ShowOutput} + Using {\KOMAScript} you write instead: +\begin{lstcode} + \begin{table} + \captionabove{This is just an example table} + \begin{tabular}{llll} + This & is & an & example.\\\hline + This & is & an & example.\\ + This & is & an & example. + \end{tabular} + \end{table} +\end{lstcode} + Then you get: + \begin{ShowOutput}\centering + {\usekomafont{caption}{\usekomafont{captionlabel}\tablename~30.2:} + This is just an example table}\\\vskip\abovecaptionskip + \begin{tabular}{llll} + This & is & an & example.\\\hline + This & is & an & example.\\ + This & is & an & example. + \end{tabular} + \end{ShowOutput} + Since you want all your tables typeset with captions above, you could + of course use the \OptionValueRef{\LabelBase}{captions}{tableheading} option + instead (see \DescPageRef{\LabelBase.option.captions.tableheading}). Then + you can use \Macro{caption} as you would in the standard classes. You will + get the same result as with \Macro{captionabove}. +\end{Example} + +\BeginIndex[indexother]{}{font>style}% +\BeginIndex{FontElement}{caption}\LabelFontElement{caption}% +\BeginIndex{FontElement}{captionlabel}\LabelFontElement{captionlabel}% +The font style\ChangedAt{v2.8p}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} for the description +and the label\,---\,``Figure'' or ``Table'', followed by the number and the +delimiter\,---\,can be changed with the commands +\DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} (see +\autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}). The respective elements for this +are \FontElement{caption}\important[i]{\FontElement{caption}\\ + \FontElement{captionlabel}} and \FontElement{captionlabel} (see +\autoref{tab:\LabelBase.fontelements}, +\autopageref{tab:\LabelBase.fontelements}). The font style for the element +\FontElement{caption} is applied to the element \FontElement{captionlabel} +before the font style of \FontElement{captionlabel} itself is applied. The +default settings are listed in \autoref{tab:\LabelBase.captionFont}. +% +\begin{table} +% \centering% +% \caption + \begin{captionbeside} + {Font defaults for the elements of figure or table captions} + [l] + \begin{tabular}[t]{ll} + \toprule + element & default \\ + \midrule + \DescRef{\LabelBase.fontelement.caption} & \Macro{normalfont} \\ + \DescRef{\LabelBase.fontelement.captionlabel} & \Macro{normalfont}\\ + \bottomrule + \end{tabular} + \end{captionbeside} + \label{tab:\LabelBase.captionFont} +\end{table} +% +\begin{Example} + You want the table and figure descriptions typeset in a smaller font + size. Thus you could write the following in the preamble of your + document: +\begin{lstcode} + \addtokomafont{caption}{\small} +\end{lstcode} + Furthermore, you would like the labels to be printed in sans serif and + bold. You add: +\begin{lstcode} + \setkomafont{captionlabel}{\sffamily\bfseries} +\end{lstcode} + As you can see, simple extensions of the default definitions are + possible. +\end{Example}% +\EndIndexGroup + + +\begin{Declaration} + \Macro{captionof}\Parameter{float type}\OParameter{entry}% + \Parameter{title}% + \Macro{captionbelowof}\Parameter{float type}\OParameter{entry}% + \Parameter{title}% + \Macro{captionaboveof}\Parameter{float type}\OParameter{entry}% + \Parameter{title} +\end{Declaration}% +Like\ChangedAt{v3.05}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} the \Package{caption}\IndexPackage{caption} and +\Package{capt-of}\IndexPackage{capt-of} packages, \KOMAScript{} offers the +\Macro{captionof} command, with which you can put a caption for a floating +environment, together with an entry in the corresponding environment list, +outside of the floating environment or even in a different floating +environment. Unlike \DescRef{\LabelBase.cmd.caption}, the type of floating +environment must be specified as the first parameter. + +In addition, \KOMAScript{} also provides the commands +\Macro{captionaboveof}\ChangedAt{v3.09}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} and \Macro{captionbelowof}. These are +like \DescRef{\LabelBase.cmd.captionabove} and +\DescRef{\LabelBase.cmd.captionbelow} but with the additional features and +parameter of \Macro{captionof}. + +Of course\ChangedAt{v3.09a}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} \Macro{captionof} takes into account the \PValue{heading} +and \PValue{signature} settings of the \DescRef{\LabelBase.option.captions} +option. But this feature may be lost if you load the +\Package{capt-of}\IndexPackage{capt-of} or +\Package{caption}\IndexPackage{caption} packages. When using +\Package{caption}, you must follow the instructions for that package (see +\cite{package:caption})! +\begin{Example} + Suppose you want to create a floating object with a table and a figure next + to each other. Since there are no mixed floating environments, you primarily + use a \Environment{figure} environment: +\begin{lstcode} + \begin{figure} + \begin{minipage}{.5\linewidth} + \centering + \rule{4cm}{5cm} + \caption{A rectangle}\label{fig:rechteck} + \end{minipage}% + \begin{minipage}{.5\linewidth} + \centering + \captionaboveof{table} + [Measure of the rectangle in + figure~\ref{fig:rechteck}]% + {Measure of the rectangle} + \label{tab:rechteck} + \begin{tabular}{ll} + Width: & 4\,cm\\ + Height: & 5\,cm + \end{tabular} + \end{minipage} + \end{figure} +\end{lstcode} + Two \Environment{minipage} environments were used to place the figure + and the table side by side. The\textnote{Attention!} percent sign after the + end of the first \Environment{minipage} is important. Without it, an + additional space would appear between the \Environment{minipage} + environments. + + The figure caption was created with \DescRef{\LabelBase.cmd.caption}. The + table caption was created with \Macro{captionaboveof} with \PValue{table} + as the first argument. Because of this, \KOMAScript{} knows that this is a + table caption even though it is inside the \Environment{figure} environment. + + The optional argument of \Macro{captionaboveof} creates an entry in the + list of tables. Without the optional argument, the caption specified in the + final mandatory argument would have been used for the list of tables too. + Although this caption text is sufficient for the environment itself, it + would not be very meaningful in the list of tables. Therefore, a different + title is used for the list of tables using the optional argument. + \autoref{fig:\LabelBase.captionaboveof} shows the result of the example code.% +\begin{figure} +% \centering +% \caption + \KOMAoptions{captions=bottombeside}% + \setcapindent{0pt}% + \begin{captionbeside} + [{Example: Using \Macro{captionaboveof} inside another floating + environment}] + {Example: Using \Macro{captionaboveof} inside another floating + environment\label{fig:\LabelBase.captionaboveof}} + [l] + \begin{minipage}[b]{.66\linewidth}% + \raisebox{\depth}{\fbox{\KOMAoptions{captions=oneline}% + \begin{minipage}{.5\dimexpr\linewidth-2\fboxsep-2\fboxrule\relax} + \centering + \rule{4cm}{5cm} + \caption[Example: A rectangle]{A rectangle}\label{fig:\LabelBase.rechteck} + \end{minipage}% + \begin{minipage}{.5\dimexpr\linewidth-2\fboxsep-2\fboxrule\relax} + \centering + \captionaboveof{table}[Example: Measure of the rectangle in + figure~\ref{fig:\LabelBase.rechteck}]{Rectangle size} + \label{tab:\LabelBase.rechteck} + \begin{tabular}{ll} + Width: & 4\,cm\\ + Height: & 5\,cm + \end{tabular} + \end{minipage}}}% + \end{minipage}% + \end{captionbeside}% +\end{figure}% +\end{Example}% +You can produce a non-floating table with a caption in the same way as the +table inside a figure environment in the example above. In such a case, a +\Environment{minipage} environment should also be used to avoid page breaks +between the caption and the table. In addition, you should embed the +\Environment{minipage} environment in a \Environment{flushleft} environment +both to achieve a pleasing separation between the surrounding text and to +avoid the paragraph indentation of the \Environment{minipage} environment.% +\EndIndexGroup + + +\begin{Declaration} + \begin{Environment}{captionbeside} + \OParameter{short title} + \Parameter{caption text} + \OParameter{placement} + \OParameter{width} + \OParameter{offset} + \end{Environment} + \labelsuffix[*]% + \begin{Environment}{captionbeside} + \OParameter{short title} + \Parameter{caption text} + \OParameter{placement} + \OParameter{width} + \OParameter{offset}\PValue{*}% + \end{Environment} +\end{Declaration} +In addition\ChangedAt{v2.8q}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} to captions above and below the figure, you will often +find captions, in particular for small figures, which are placed beside the +figure. The bottom edge of the caption is normally aligned with the bottom of +the figure. Of course, you can achieve the same thing in the standard classes +with some fiddling and the use of two \Macro{parbox} commands. However, +\KOMAScript{} offers a special environment for this which you can use within +the floating environments. The first optional parameter, +\PName{short title}\important{\PName{short title}\\\PName{caption text}}, and +the required parameter \PName{caption text} have the same meaning as the +corresponding parameters of \DescRef{\LabelBase.cmd.caption}, +\DescRef{\LabelBase.cmd.captionabove} or +\DescRef{\LabelBase.cmd.captionbelow}. The \PName{caption text} is +placed beside the content of the environment in this case. + +The \PName{placement}\important{\PName{placement}} parameter can determine +whether the \PName{caption text} is placed on the left or the right. Exactly +one of the following letters is allowed: +\begin{labeling}[~--]{\quad\PValue{o}}\setlength{\itemsep}{-1\parsep plus 1ex}% + \item[\PValue{l}] left + \item[\PValue{r}] right + \item[\PValue{i}] inner margin in two-sided printing + \item[\PValue{o}] outer margin in two-sided printing +\end{labeling} +The default placement is to the right of the content of the environment. You +can change this default\ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} using the +\DescRef{\LabelBase.option.captions}\IndexOption{captions}% +\important{\DescRef{\LabelBase.option.captions}} option (see +\DescPageRef{\LabelBase.option.captions}) with values like +\PValue{innerbeside}\IndexOption[indexmain]{captions~=\textKValue{innerbeside}}, +\PValue{leftbeside}\IndexOption[indexmain]{captions~=\textKValue{leftbeside}}, +\PValue{outerbeside}\IndexOption[indexmain]{captions~=\textKValue{outerbeside}}, +and +\PValue{rightbeside}\IndexOption[indexmain]{captions~=\textKValue{rightbeside}}. +If either \PValue{o} or \PValue{i} are used you may need to run {\LaTeX} twice +to obtain the correct placement. + +Normally\important{\PName{width}}, the content of the environment and the +\PName{caption text} fill the entire available text width. However, you can +specify a different width using the optional parameter \PName{width}. This can +be greater than the current text width. + +When specifying a \PName{width}\important{\PName{width}\\\PName{offset}}, the +width used is usually centred with respect to the body text. Using the +optional parameter \PName{offset}, you can shift the environment relative to +the left margin. A positive value corresponds to a shift to the right, whereas +a negative value corresponds to a shift to the left. An \PName{offset} of +0\Unit{pt} gives you a left-aligned output. + +If\important{\PValue{*}} you add a star to the optional \PName{offset} +parameter, the value represents a shift relative to the right margin on +left-hand pages in a two-sided layout. A positive value corresponds to a shift +towards the outer margin, whereas a negative value corresponds to a shift +towards the inner margin. An \PName{offset} of 0\Unit{pt} means alignment with +the inner margin. This variant may require two {\LaTeX} runs to achieve the +correct offset. + +The default vertical alignment is bottom. This means that the bottommost base +lines of the contents of the environment and of the caption are aligned. +You\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} can change this setting using the +\DescRef{\LabelBase.option.captions}\IndexOption{captions}% +\important{\DescRef{\LabelBase.option.captions}} option (see +\DescPageRef{\LabelBase.option.captions}) with the value +\PValue{topbeside}\IndexOption[indexmain]{captions~=\textKValue{topbeside}}, +\PValue{centeredbeside}% +\IndexOption[indexmain]{captions~=\textKValue{centeredbeside}}, or +\PValue{bottombeside}% +\IndexOption[indexmain]{captions~=\textKValue{bottombeside}}. +With the setting \PValue{topbeside}, the topmost base lines of the environment +contents and caption will be aligned. With \PValue{centeredbeside}, they will +be centred vertically. In this context, note that the base line of a figure is +usually the bottom of the figure. You can change this using, for example, +\Macro{raisebox}\IndexCmd{raisebox}. + +\begin{Example} + You can find an example using the \Environment{captionbeside} environment in + \autoref{fig:\LabelBase.captionbeside}. This figure was typeset with: +\begin{lstcode} + \begin{figure} + \begin{captionbeside}[Example: Figure beside description]% + {A figure description which is neither above nor + below, but beside the figure}[i][\linewidth][% + [i][\linewidth][% + \dimexpr\marginparwidth+\marginparsep\relax]* + \fbox{% + \parbox[b][5\baselineskip][c]{.25\textwidth} + {% + \hspace*{\fill}\KOMAScript + \hspace*{\fill}\par + }% + } + \end{captionbeside} + \label{fig:\LabelBase.captionbeside} + \end{figure} +\end{lstcode} + \begin{figure} + \begin{captionbeside}[Example: Figure beside description]% + {A figure description which is neither above nor + below, but beside the figure}[i][\linewidth][2em]* + \fbox{% + \parbox[b][5\baselineskip][c]{.25\textwidth}{% + \hspace*{\fill}\KOMAScript\hspace*{\fill}\par}} + \end{captionbeside} + \label{fig:\LabelBase.captionbeside} + \end{figure} + The total width is thus the currently available width of + \PValue{\Macro{linewidth}}. However, this width is shifted + $\Length{marginparwidth} + \Length{marginparsep}$ to the outside. The + caption text or description is placed on the inner side beside the figure. + The figure itself is shifted 2\Unit{em} into the outer margin. + +\iffalse% Umbruchkorrekturtext + The \Macro{dimexp} macro is an \eTeX{} command. This should not be a + problem at all because \KOMAScript{} itself requires \eTeX{} and every almost + up-to-date \LaTeX{} distribution uses \eTeX already. +\fi + + \hyperref[fig:\LabelBase.captionbesidecentered]% + {Figure~\ref*{fig:\LabelBase.captionbesidecentered}} + shows a centred caption with: +\begin{lstcode} + \KOMAoption{captions}{centeredbeside} +\end{lstcode} +\iffalse % Umbruchalternativen + Even a typographical novice will immediately realize that you should + usually avoid this alignment. +\else + This is certainly not a recommended solution. +\fi + + \begin{figure} + \begin{captionbeside}[Example: Description centered beside figure]% + {A figure description which is neither above nor + below, but centred beside the figure}[i][\linewidth][2em]* + \fbox{% + \parbox[b][5\baselineskip][c]{.25\textwidth}{% + \hspace*{\fill}\KOMAScript\hspace*{\fill}\par}} + \end{captionbeside} + \label{fig:\LabelBase.captionbesidecentered} + \end{figure} + + In contrast, you can use the top-aligned format seen in + \autoref{fig:\LabelBase.captionbesidetop}. To illustrate how to shift the + baseline using \Macro{raisebox}, here is a complete example. You can apply + this not only to a substitute figure, as previously shown, but also, for + example, to \Macro{includegraphics} (see \cite{package:graphics}). +\begin{lstcode} + \documentclass[captions=topbeside]{scrbook} + \usepackage[english]{babel} + \usepackage{graphics} + \begin{document} + \chapter{An Example} + \begin{figure} + \begin{captionbeside}% + [Example: Figure title top beside]% + {A figure description which is neither above nor + below, but top beside the figure}% + [i][\linewidth][% + \dimexpr\marginparwidth+\marginparsep\relax + ]* + \raisebox{% + \dimexpr\baselineskip-\totalheight\relax + }{% + \includegraphics{examplepicture}% + }% + \end{captionbeside} + \label{fig:\LabelBase.captionbesidetop} + \end{figure} + \end{document} +\end{lstcode} + \begin{figure} + \KOMAoption{captions}{topbeside} + \begin{captionbeside}[Example: Figure title top beside]% + {A figure description which is neither above nor + below, but top beside the figure}% + [i][\linewidth] + \raisebox{\dimexpr\baselineskip-\totalheight}{% + \fbox{% + \parbox[b][5\baselineskip][c]{.25\textwidth}{% + \hspace*{\fill}\KOMAScript\hspace*{\fill}\par}}% + }% + \end{captionbeside} + \label{fig:\LabelBase.captionbesidetop} + \end{figure} +\end{Example} +% +\EndIndexGroup + + +\begin{Declaration} + \begin{Environment}{captionofbeside} + \Parameter{float type} + \OParameter{short title} + \Parameter{caption text} + \OParameter{placement} + \OParameter{width} + \OParameter{offset} + \begin{Body}\BodyDots\end{Body} + \end{Environment} + \labelsuffix[*]% + \begin{Environment}{captionofbeside} + \Parameter{float type} + \OParameter{short title} + \Parameter{caption text} + \OParameter{placement} + \OParameter{width} + \OParameter{offset}\PValue{*}% + \begin{Body}\BodyDots\end{Body} + \end{Environment} +\end{Declaration} +As\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} is the case for \DescRef{\LabelBase.cmd.caption}, there is +a variant for \DescRef{\LabelBase.cmd.captionof} where the \PName{float type} +is not defined by using it within a floating environment of this type, so you +can specify a suitable environment for \DescRef{\LabelBase.env.captionbeside} +with \Environment{captionofbeside}. In contrast to +\DescRef{\LabelBase.env.captionbeside}, the \PName{float type} must be +specified as an additional, first argument.% +% +\EndIndexGroup + +\begin{Declaration} + \FloatStyle{komaabove}% + \FloatStyle{komabelow} +\end{Declaration}% +If you use\OnlyAt{\Package{float}} the \Package{float}\IndexPackage{float} +package, the appearance of the float environments is solely defined by the +\emph{float} style. This includes whether captions appear above or below. In +the \Package{float} package, there is no predefined style which gives you the +same output and offers the same setting options (see below) as \KOMAScript{}. +Therefore \KOMAScript{} defines the two additional styles, \PValue{komaabove} +and \PValue{komabelow}. When using the \Package{float} package, you can +activate these styles just like the styles +\PValue{plain}\IndexFloatstyle{plain}, \PValue{boxed}\IndexFloatstyle{boxed}, +or \PValue{ruled}\IndexFloatstyle{ruled} defined in \Package{float}. For +details refer to \cite{package:float}. The style \PValue{komaabove} inserts +\DescRef{\LabelBase.cmd.caption}, \DescRef{\LabelBase.cmd.captionabove}, and +\DescRef{\LabelBase.cmd.captionbelow} above, whereas \PValue{komabelow} +inserts them below the float content. +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{captionformat} +\end{Declaration}% +In {\KOMAScript} there are various ways to change the formatting of +the caption text. The definition of different font styles has already +been explained above. The delimiter or delimiters between the label and +actual caption text is specified by the macro \Macro{captionformat}. +In contrast to all other \Macro{\dots}format commands, this is not the counter +but only the items which follow it. The original definition is: +\begin{lstcode} + \newcommand*{\captionformat}{:\ } +\end{lstcode} +You can change this too with \Macro{renewcommand}. +\begin{Example} + For some inexplicable reason, you want a dash surrounded by spaces + instead of a colon followed by a space as a label delimiter. You + therefore define: +\begin{lstcode} + \renewcommand*{\captionformat}{~--~} +\end{lstcode} +This definition should be put in the preamble of your document. +\end{Example} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{figureformat}% + \Macro{tableformat} +\end{Declaration}% +It has already been mentioned that \DescRef{\LabelBase.cmd.captionformat} does +not contain formatting for the label itself. You should not alter this by +redefining the commands for the output of the \Macro{thefigure} or +\Macro{thetable} counters. Such a redefinition would have unwanted side +effects on the output of \Macro{ref}, the table of contents, the list of +figures, and the list of tables. Instead, {\KOMAScript} offers two +\Macro{\dots format} commands. These have the following defaults: +\begin{lstcode} + \newcommand*{\figureformat}{\figurename~\thefigure\autodot} + \newcommand*{\tableformat}{\tablename~\thetable\autodot} +\end{lstcode} +They can also be customised to your requirements with \Macro{renewcommand}. +\begin{Example} + From time to time, it is required to have captions without labels or + delimiters. With {\KOMAScript} the following definitions suffice to + achieve this: +\begin{lstcode} + \renewcommand*{\figureformat}{} + \renewcommand*{\tableformat}{} + \renewcommand*{\captionformat}{} +\end{lstcode} + It should be noted, however, that although no numbering is output, the + internal counters are nevertheless incremented. This becomes especially + important if this redefinition is applied only to selected + \Environment{figure} or \Environment{table} environments. +\end{Example} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{setcapindent}\Parameter{indent}% + \Macro{setcapindent*}\Parameter{xindent}% + \Macro{setcaphanging} +\end{Declaration}% +As mentioned previously, in the standard classes the captions are set in a +non-hanging style. In other words, in multi-line captions the second and +subsequent lines start directly beneath the label. The standard classes +provide no direct mechanism to change this behaviour. In {\KOMAScript}, on the +contrary, beginning at the second line all lines are indented by the width of +the label so that the caption text is aligned. + +You can change this behaviour, which corresponds to using +\Macro{setcaphanging}, at any time with the \Macro{setcapindent} or +\Macro{setcapindent*} command. Here the parameter \PName{indent} determines +the indentation of the second and subsequent lines. If you want a line break +after the label and before the caption text, then you can define the +indentation \PName{xindent} of the caption text with the starred version of +the command instead: \Macro{setcapindent*}. + +A negative value of \PName{indent}, on the other hand, results in a line break +before the caption text, and only the first line of the caption text, not +subsequent lines, is indented by the absolute value of \PName{indent}. + +Whether one-line captions are set the same way as multi-line captions or are +treated separately is specified with the option +\DescRef{\LabelBase.option.captions}. For details please refer to the +explanations of these option on +\DescPageRef{\LabelBase.option.captions.oneline}. + +\begin{Example} + The illustrations~\ref{fig:\LabelBase.caption.first} to + \ref{fig:\LabelBase.caption.last} show the effects of different settings. As + you can see, using a fully hanging indentation with a narrow column width is + awkward. To illustrate, the source code for the second figure is given here + with a modified caption text: +\begin{lstcode} + \begin{figure} + \setcapindent{1em} + \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} + \caption{Example with partially indented caption + starting from the second line} + \end{figure} +\end{lstcode} + As you can see, the formatting can also be changed locally within the + \Environment{figure} environment\IndexEnv{figure}. The change then affects + only the current figure. Subsequent figures once again use the default + settings or global settings that you set, for example, in the preamble. This + also, of course, applies to tables. + \begin{figure} + \typeout{^^J--- Ignore underfull and overfull \string\hbox:} + \addtokomafont{caption}{\small} + \addtokomafont{captionlabel}{\bfseries} + \centering% + \begin{minipage}{.9\linewidth} + \begin{minipage}[t]{.48\linewidth}\sloppy + \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} + \caption[Example: Default caption]% + {\sloppy With the default setting, like using + \Macro{setcaphanging}} + \label{fig:\LabelBase.caption.first} + \end{minipage} + \hspace{.02\linewidth} + \begin{minipage}[t]{.48\linewidth}\sloppy + \setcapindent{1em} + \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} + \caption[Example: Caption with partially hanging indention]% + {With partially hanging indentation starting from the second line + by using \Macro{setcapindent}\PParameter{1em}} + \end{minipage} + \end{minipage} + + \vspace*{2ex}\noindent% + \begin{minipage}{.9\linewidth} + \begin{minipage}[t]{.48\linewidth}\sloppy + \setcapindent*{1em} + \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} + \caption[Example: Caption with hanging indention and line break]% + {With hanging indentation starting from the second line and line + break before the description using + \Macro{setcapindent*}\PParameter{1em}} + \end{minipage} + \hspace{.02\linewidth} + \begin{minipage}[t]{.48\linewidth}\sloppy + \setcapindent{-1em} + \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} + \caption[Example: Caption with indention in the second line]% + {With indentation only in the second line and a line break + before the description using + \Macro{setcapindent}\PParameter{-1em}} + \label{fig:\LabelBase.caption.last} + \end{minipage} + \end{minipage} + \typeout{^^J--- Don't ignore underfull and overfull + \string\hbox:^^J} + \end{figure} +\end{Example} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{setcapwidth}\OParameter{justification}\Parameter{width}% + \Macro{setcapdynwidth}\OParameter{justification}\Parameter{width}% + \Macro{setcapmargin}\OParameter{left margin}\Parameter{margin}% + \Macro{setcapmargin*}\OParameter{inside margin}\Parameter{margin} +\end{Declaration} +Using\ChangedAt{v2.8q}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} these three +commands, you can specify the width and justification of the caption +text. Normally, the entire text or column width is available for the caption. + +With\important{\Macro{setcapwidth}} the \Macro{setcapwidth} command, you can +decrease this \PName{width}. The mandatory argument determines the maximum +\PName{width} of the caption. As an optional argument, you can supply exactly +one letter which specifies the horizontal justification. The possible +justifications are given in the following list: +\begin{labeling}[~--]{\quad\PValue{o}}% + \itemsep=.5\topsep plus .5\topsep minus .5\topsep + \rightskip=1em +\item[\PValue{l}] left-justified +\item[\PValue{c}] centred +\item[\PValue{r}] right-aligned +\item[\PValue{i}] aligned to the inner margin in two-sided printing +\item[\PValue{o}] aligned to the outer margin in two-sided printing +\end{labeling} +Inside and outside justification corresponds to left-aligned and right-aligned +justification, respectively, in one-sided printing. +Within\textnote{Attention!} \Package{longtable}\IndexPackage{longtable}% +\important{\Package{longtable}} tables, inside and outside justification does +not work correctly. In particular, the captions on subsequent pages of such +tables are aligned according to the format of the caption on the first page of +the table. This is a conceptual problem in the implementation of the +\Package{longtable} package. + +Note\ChangedAt{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\textnote{Attention!} that \Macro{setcapwidth} immediately +sets the width to the value of the \PName{width} parameter at the time of the +assignment, as \Macro{setlength} does. If\important{\Macro{setcapdynwidth}} +you instead want to use the current value of \PName{width} when the caption is +set, you should use \Macro{setcapdynwidth}. There can be significant +differences in the result if, for example, you use lengths like +\Length{linewidth} or other commands as \PName{width} arguments. + +With\important{\Macro{setcapmargin}} the \Macro{setcapmargin} command, instead +of specifying the width of the caption text, you can specify a \PName{margin} +to be set next to the caption text in addition to the normal text margin. If +you want margins with different widths on the left and right sides, you can +use the optional argument to specify a \PName{left margin} that differs from +\PName{margin}. Instead of a \PName{left margin}, the starred version +\Macro{setcapmargin*} defines an \PName{inside margin} in a two-sided layout. +The same problem arises here with with inside and outside justification inside +\Package{longtable}\IndexPackage{longtable}\important{\Package{longtable}} +tables that occurs with \Macro{setcapwidth}. Furthermore, using +\Macro{setcapmargin} or \Macro{setcapmargin*} activates the +\OptionValueRef{\LabelBase}{captions}{nooneline} option (see +\DescPageRef{\LabelBase.option.captions.nooneline}) for captions which are +typeset with this margin setting. + +You\textnote{Hint!} can also specify negative values for \PName{margin} and +\PName{left margin} or \PName{inside margin}. This has the effect of making +the caption protrude into the margin.% +\iffalse\par% Anhang wurde entfernt. +Experts\textnote{Hint!} and advanced users can find a a somewhat tricky +application of \Macro{setcapwidth} in +\iffree{\cite{book:komascript}}{\autoref{cha:floattricks}, + \autopageref{cha:floattricks}}.% +\fi% +% +\EndIndexGroup + +\begin{Declaration} + \Macro{setcaptionalignment}\OParameter{float type}\Parameter{alignment} +\end{Declaration} +Normally\ChangedAt{v3.25}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}, multi-line\textnote{alignment of multi-line captions} +captions are fully justified. This corresponds to +\Macro{setcaptionalignment}\PParameter{j}. Sometimes, however, you want a +different alignment, for example ragged right. An appropriate change is +possible at any time with \Macro{setcaptionalignment}. You can specify exactly +one of the letters listed in \autoref{tab:maincls.captionalignment} for the +\PName{alignment}. If you specify an unknown \PName{alignment}, you will +receive an error message. +% +\begin{table} +% \centering + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% + \begin{captionbeside} + [{Alignments for multi-line captions of floating environments}] + {\label{tab:maincls.captionalignment}% + Alignments for multi-line captions of floating environments} + [l] + \begin{tabular}[t]{ll} + \toprule + c & centred \\ + j & fully justified \\ + l & left justified \\ + r & right justified \\ + C & centred with \Package{ragged2e} \\ + J & fully justified with \Package{ragged2e} \\ + L & left justified with \Package{ragged2e} \\ + R & right justified with \Package{ragged2e} \\ + \bottomrule + \end{tabular} + \end{captionbeside} +\end{table} + +The four possibilities with the +\Package{ragged2e}\important{\Package{ragged2e}}\IndexPackage{ragged2e} +package are only available if that package was loaded before you use +\Macro{setcaptionalignment}. Otherwise, they are converted to the +corresponding options without \Package{ragged2e}. For safety reasons, a +warning is issued in this case. + +When using this command without\textnote{without optional parameter} the +optional parameter, the result depends on whether the call occurs inside our +outside of a floating environment. Within a floating environment, the +alignment is then set for this floating environment. Outside, on the other +hand, the optional parameter is assumed to be empty. + +Using this command with an empty\textnote{empty optional parameter} optional +parameter, or outside a floating environment and also without any optional +parameter, sets the general alignment. This is used whenever the current +floating environment type does not define an alignment. + +If you only want to set the alignment of a particular type of floating +environment\textnote{with \PName{float type}} without changing the +\PName{alignment} for other types of floating environments, then the type of +floating environment, e.\,g., \PValue{figure} or \PValue{table}, is given as +the optional parameter \PName{float type}. +% +\begin{Example} + You want captions to be centred under the images even if they are + multi-line. To text this for a single image, use\textnote{in the + floating environment}: +\begin{lstcode} + \begin{figure} + \centering + \setcaptionalignment{c} + \includegraphics{example-image} + \caption{\blindtext} + \end{figure} +\end{lstcode} + Since you are satisfied with the result, you move the\textnote{in the + preamble} +\begin{lstcode} + \setcaptionalignment{c} +\end{lstcode} + command to the document preamble. Thereafter, however, you decide you do not + like this change for table captions at all. Therefore, you use\textnote{only + for figures} +\begin{lstcode} + \setcaptionalignment[figure]{c} +\end{lstcode} + to limit the centring to figures. + + A little later, you realize that the centring is not so suitable. Instead, + you now prefer to have ragged right alignment. So you change the alignment + again: +\begin{lstcode} + \setcaptionalignment[figure]{l} +\end{lstcode} + However, you do not like the fact that the lines are very different in + length. This is caused by the lack of hyphenation, causing long words to + wrap completely onto the next line, leaving large gaps. You want to allow + hyphenation as needed. This is easy to achieve with the help of the + \Package{ragged2e}\important{\Package{ragged2e}}\IndexPackage{ragged2e} + package. However, it is not enough to use +\begin{lstcode} + \usepackage{ragged2e} +\end{lstcode} + to load the package. Using the \Option{newcommands} option when loading the + package does not help. Instead, the \PName{alignment} must also be changed: +\begin{lstcode} + \usepackage{ragged2e} + \setcaptionalignment[figure]{L} +\end{lstcode} + Note\textnote{Attention!} the upper-case letter for the \PName{alignment}. +\end{Example} +\EndIndexGroup + + +\begin{Declaration} + \Option{origlongtable} +\end{Declaration}% +\BeginIndex{Package}{longtable}% +If you do not want the table captions produced by the \Package{longtable} +package (see \cite{package:longtable}) to be redefined by the {\KOMAScript} +classes, activate the \Option{origlongtable} option. This\textnote{Attention!} +option must be used in the optional argument of +\DescRef{\LabelBase.cmd.documentclass}. It cannot be used as a setting of +\DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoptions}. +% +\EndIndexGroup +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{listof}{setting} +\end{Declaration} +Normally\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} lists of floating environments\,---\,like +tables\Index{tables>list of} or figures\Index{figures>list of}\,---\,are +neither numbered nor included in the table of contents. You can find more +information about this behaviour in \autoref{sec:\LabelBase.toc}. As an +alternative to the settings \OptionValueRef{\LabelBase}{toc}{nolistof}% +\IndexOption{toc~=\textKValue{nolistof}}, +\OptionValueRef{\LabelBase}{toc}{listof}\IndexOption{toc~=\textKValue{listof}}, +and \OptionValueRef{\LabelBase}{toc}{listofnumbered}% +\IndexOption{toc~=\textKValue{listofnumbered}} mentioned there, you can also +look at this behaviour from perspective of the lists themselves. Therefore +you can achieve the same results with the settings +\OptionValue{listof}{notoc}, \OptionValue{listof}{totoc}, and +\OptionValue{listof}{numbered}. + +By default, the headings in the lists of floating environments use the topmost +level below \DescRef{\LabelBase.cmd.part}. This is the chapter level in +\Class{scrbook} and \Class{scrreprt} and the section level in +\Class{scrartcl}. By contrast,\ChangedAt{v3.06}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} +\OptionValue{listof}{leveldown}\important{\OptionValue{listof}{leveldown}} +uses the next lower level to be used instead. +\important{\OptionValue{listof}{standardlevel}}% +\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% +\OptionValue{listof}{standardlevel} switches back to the default sectioning +level, if necessary. +\begin{Example} + In a book, you want to put the list of figures and the list of tables as + sub-lists into a common list named ``Figures and Tables''. Simply use: +\begin{lstcode} + \KOMAoption{listof}{leveldown} +\end{lstcode} + to use the section instead of the chapter level for both lists, and put the + following at the appropriate place in your document: +\begin{lstcode} + \addchap*{Figures and Tables} + \listoffigures + \listoftables +\end{lstcode} + You can find more information about the \DescRef{\LabelBase.cmd.addchap*} + command in \autoref{sec:\LabelBase.structure} on + \DescPageRef{\LabelBase.cmd.addchap*}. +\end{Example} + +Normally\ChangedAt{v2.8q}{% + \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} the lists of +floating environments use a fixed-width space for the caption number of the +entries. At the same time, all entries are somewhat indented. This behaviour +corresponds to the +\OptionValue{listof}{graduated}\IndexOption{listof~=\textKValue{graduated}} +setting. + +If the numbers become very wide, for example because you have many tables or +figures, the space provided may at some point no longer be sufficient. +\KOMAScript{} offers the setting \OptionValue{listof}{flat}% +\important{\OptionValue{listof}{flat}}\IndexOption{listof~=\textKValue{flat}} +for lists of floating environments, comparable to +\OptionValueRef{\LabelBase}{toc}{flat}\IndexOption{toc~=\textKValue{flat}} for +the table of contents. The width required to print the number is +determined automatically and the space is adjusted accordingly. See the +\OptionValueRef{\LabelBase}{toc}{flat} option, \autoref{sec:\LabelBase.toc}, +\DescPageRef{\LabelBase.option.toc.flat} for more information about side +effects and how it works. Note\textnote{Attention!} again that you need more +than one \LaTeX{} run before the lists of floating environments reach +their final state. + +The \OptionValue{listof}{entryprefix}\ChangedAt{v3.06}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} setting automatically activates +\OptionValue{listof}{flat} too. +Normally\important{\OptionValue{listof}{entryprefix}}, it does not make sense +to add a prefix such as ``figure'' or ``table'' to each entry in the lists of +floating environments because, of course, only figures are included in the +list of figures and only tables are included in the list of tables. Such a +prefix provides no additional information and is thus omitted by default. +However, you can add such prefixes using the +\OptionValue{listof}{entryprefix} option. With this, all entries in the same +list will get the same prefix. The prefix depends on the file extension of the +auxiliary file that is used for the corresponding list. For the list of +figures, the file extension is ``\File{lof}'' and therefore +\Macro{listoflofentryname} is used. For the list of tables, the file extension +is ``\File{lot}'' and \Macro{listoflotentryname} is used. + +For the \Class{scrbook} and \Class{scrreprt}\OnlyAt{\Class{scrbook}\and + \Class{scrreprt}} classes, \KOMAScript{} adds a vertical space to the lists +of floating environments whenever a new chapter starts. This behaviour, which +also exists in the standard classes, groups the lists by chapters. In +\KOMAScript{}, it corresponds to setting \ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}% +\OptionValue{listof}{chaptergapsmall}% +\LabelOptionValue{listof}{chaptergapsmall}% +\important{\OptionValue{listof}{chaptergapsmall}}% +\IndexOption{listof~=\textKValue{chaptergapsmall}}. In this case, is uses a +fixed vertical space of 10\Unit{pt}. +With\important{\OptionValue{listof}{chaptergapline}} the +\OptionValue{listof}{chaptergapline}% +\IndexOption{listof~=\textKValue{chaptergapline}} option, you instead get a +vertical space the height of one standard text line. With +\OptionValue{listof}{nochaptergap}% +\IndexOption{listof~=\textKValue{nochaptergap}}% +\important{\OptionValue{listof}{nochaptergap}}, you can completely remove the +vertical space. The\important{\OptionValue{listof}{chapterentry}} +\OptionValue{listof}{chapterentry}% +\IndexOption{listof~=\textKValue{chapterentry}} option is a special feature. +Instead of a vertical space, the table of contents entry for the chapter is +inserted into the lists of floating environments. Note\textnote{Attention!} +that this happens even if the chapter does not contain a floating environment. +You can find a method where only chapters containing floating environments +appear in the respective lists at \cite{https://komascript.de/comment/5070}. +You can achieve a more direct control over what appears in the lists of +floating environments with the \DescRef{\LabelBase.option.chapteratlists} +option, which is explained in \autoref{sec:\LabelBase.structure}, on +\DescPageRef{\LabelBase.option.chapteratlists}. + +You can find an overview of all settings for the \Option{listof} option in +\autoref{tab:\LabelBase.listof}. + +\begin{desclist} + \desccaption[{Available values for the \Option{listof} option}]{% + Available values for the \Option{listof} option for modifying the format + and contents of the lists of floating + environments\label{tab:\LabelBase.listof}% + }{% + Available values for the \Option{listof} option (\emph{continued})% + }% + \entry{\PValue{chapterentry}, \PValue{withchapterentry}}{% + Indicates the beginning of chapters in the lists of floating environments + with copies of their table-of-contents entries.% + \IndexOption{listof~=\textKValue{chapterentry}}}% + \entry{\PValue{chaptergapline}, \PValue{onelinechaptergap}}{% + Indicates the beginning of chapters in the lists of floating environments + with a vertical space the height of one standard text line.% + \IndexOption{listof~=\textKValue{chaptergapline}}}% + \entry{\PValue{chaptergapsmall}, \PValue{smallchaptergap}}{% + Indicates the beginning of chapters in the lists of floating environments + with a small vertical space.% + \IndexOption{listof~=\textKValue{chaptergapsmall}}}% + \entry{\PValue{entryprefix}}{% + \ChangedAt{v3.06}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + Adds a prefix before the number of each floating-environment list entry. + The prefix is usually language-dependent, e.\,g., in English ``Figure'' is + used for the list of figures and ``Table'' for the list of tables, each + followed by a white space.% + \IndexOption{listof~=\textKValue{entryprefix}}}% + \entry{\PValue{flat}, \PValue{left}}{% + Prints the lists of floating environments in tabular form. The caption + numbers are the first column, the caption texts the second column, and the + page numbers the third column. The space reserved for the caption numbers + depends on the previous \LaTeX{} run.% + \IndexOption{listof~=\textKValue{flat}}}% + \entry{\PValue{graduated}, \PValue{indent}, \PValue{indented}}{% + Prints the lists of floating environments in a hierarchical form. The + space reserved for the caption numbers is limited.% + \IndexOption{listof~=\textKValue{graduated}}}% + \entry{\PValue{leveldown}}{% + Uses headings that are one level lower in the sectioning hierarchy than + the default for lists of floating environments.% + \IndexOption{listof~=\textKValue{leveldown}}}% + \entry{\PValue{indenttextentries}, \PValue{indentunnumbered}, + \PValue{numberline}}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The \PValue{numberline} property (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.setuptoc}) is set for the lists of floating + environments such as figures and tables. As a result, unnumbered entries + are left-aligned with the text of numbered entries of the same level. + However, the \KOMAScript{} classes themselves do not put unnumbered + entries in these lists. This option therefore affects only entries that + are generated not by the \KOMAScript{} classes themselves but with the + help of \DescRef{tocbasic.cmd.addxcontentsline} (see + \autoref{sec:tocbasic.toc}, \DescPageRef{tocbasic.cmd.addxcontentsline}).% + \IndexOption{toc~=\textKValue{numberline}}}% + \entry{\PValue{leftaligntextentries}, \PValue{leftalignunnumbered}, + \PValue{nonumberline}}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The \PValue{nonumberline} property (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.setuptoc}) is set for the lists of floating + environments. This will place unnumbered entries left-aligned with the + number of numbered entries. However, the \KOMAScript{} classes themselves + do not put unnumbered entries in these lists. This option therefore + affects only entries that are generated not by the \KOMAScript{} classes + themselves but with the help of \DescRef{tocbasic.cmd.addxcontentsline} + (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.addxcontentsline}).% + \IndexOption{toc~=\textKValue{nonumberline}}}% + \entry{\PValue{nochaptergap}, \PValue{ignorechapter}}{% + The beginnings of chapters are not marked in the lists of floating + environments.% + \IndexOption{listof~=\textKValue{nochaptergap}}}% + \entry{\PValue{notoc}, \PValue{nottotoc}, \PValue{plainheading}}{% + The lists of floating environments do not generate entries in the table of + contents.% + \IndexOption{listof~=\textKValue{nottotoc}}}% + \entry{\PValue{numbered}, \PValue{totocnumbered}, \PValue{tocnumbered}, + \PValue{numberedtoc}, \PValue{numberedtotoc}}{% + The lists of floating environments receive numbered entries in the table + of contents.% + \IndexOption{listof~=\textKValue{numbered}}}% + \entry{\PValue{standardlevel}}{% + The lists use the normal sectioning level.% + \IndexOption{listof~=\textKValue{standardlevel}}}% + \entry{\PValue{totoc}, \PValue{toc}, \PValue{notnumbered}}{% + The lists of floating environment generate entries in the table of + contents, but their headings are unnumbered.% + \IndexOption{listof~=\textKValue{totoc}}}% +\end{desclist} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{listoftables}% + \Macro{listoffigures} +\end{Declaration} +These commands generate a list of tables or figures. Changes affecting these +lists will require two \LaTeX{} runs to take effect. The layout of the lists +can be influenced by the \DescRef{\LabelBase.option.listof}% +\important{\DescRef{\LabelBase.option.listof}} option with the values +\PValue{graduated} or \PValue{flat} (see +\DescPageRef{\LabelBase.option.listof}). In addition, the \PValue{listof} and +\PValue{listofnumbered} values of the \DescRef{\LabelBase.option.toc}% +\important{\DescRef{\LabelBase.option.toc}} option (see +\autoref{sec:\LabelBase.toc}), as well as the \PValue{totoc} and +\PValue{numbered} values of the \DescRef{\LabelBase.option.listof} option +described above indirectly affect these lists. + +As\textnote{Hint!} a rule, you will find the lists of the floating +environments immediately after the table of contents. In some documents, they +go into the appendix. However, the author of this guide prefers them +immediately after the table of contents.% +% +\EndIndexGroup + + +\LoadCommonFile{marginpar}% \section{Marginal Notes} + + +\section{Appendix} +\seclabel{appendix} +\BeginIndexGroup +\BeginIndex{}{Appendix} + +The appendix of a document mostly consists of supplements to the document. +Typical parts of an appendix include a bibliography, an index, and a glossary. +However you should not start an appendix for these parts alone because their +format already distinguishes them from the main document. But if there are +additional elements in the appendix, such as quoted third-party documents, +endnotes, figures, or tabulars, the standard elements such as the bibliography +should also be part of the appendix. + + +\begin{Declaration} + \Macro{appendix} +\end{Declaration}% +The appendix is started in the standard as well as the {\KOMAScript} classes +with \Macro{appendix}. Among other things, this command changes the chapter +numbering to upper-case letters while ensuring that the rules according to +\cite{DUDEN} for numbering the sectioning levels are followed (for +German-speaking regions). These rules are explained in more detail in the +description of the \DescRef{\LabelBase.option.numbers} option in +\autoref{sec:\LabelBase.structure}, \DescPageRef{\LabelBase.option.numbers}. + +The format of the chapter headings\OnlyAt{\Class{scrbook}\and + \Class{scrreprt}} in the appendix is influenced by the +\DescRef{\LabelBase.option.chapterprefix}% +\important{\DescRef{\LabelBase.option.chapterprefix}\\ + \DescRef{\LabelBase.option.appendixprefix}} and +\DescRef{\LabelBase.option.appendixprefix} options. See +\autoref{sec:\LabelBase.structure}, +\DescPageRef{\LabelBase.option.appendixprefix} for more information. + +Please\textnote{Attention!} note that \Macro{appendix} is a command, +\emph{not} an environment! This command does not expect an argument. Chapters +and sections in the appendix use \DescRef{\LabelBase.cmd.chapter} and +\DescRef{\LabelBase.cmd.section}, just as in the main text.% +% +\EndIndexGroup +% +\EndIndexGroup + + +\section{Bibliography} +\seclabel{bibliography} +\BeginIndexGroup +\BeginIndex{}{bibliography} + +The bibliography makes external sources accessible. As a rule, the +bibliography is created from an external file with a database-like structure +using the \BibTeX{} program. You can use the \BibTeX{} style to change both +the format of the entries and their sorting. If you use an additional +bibliography package like \Package{natbib}\IndexPackage{natbib}, +\Package{babelbib}\IndexPackage{babelbib}, or +\Package{biblatex}\IndexPackage{biblatex}, \KOMAScript{}'s influence over the +bibliography disappears. In such cases, you must follow the manual of the +relevant bibliography package. You can find general information about +bibliographies in \cite{lshort}. + + +\begin{Declaration} + \OptionVName{bibliography}{setting} +\end{Declaration} +For a start,\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} you can select any predefined bibliography style in +\PName{setting}. There are two such bibliography styles predefined in +\KOMAScript{}. You should not confuse them with the styles used by +\BibTeX\Index{BibTeX=\BibTeX}, which you select with +\Macro{bibstyle}. While \BibTeX{} determines both the sorting and the +contents of the bibliography, \KOMAScript{} influences only some basic +features of the bibliography and few properties of the entry format. + +The\important{\OptionValue{bibliography}{oldstyle}} +\OptionValue{bibliography}{oldstyle}% +\IndexOption{bibliography~=\textKValue{oldstyle}} option selects a compact +format for bibliography entries. In this case, using the +\DescRef{maincls-experts.cmd.newblock}\IndexCmd{newblock} command results in +only a small glue between the entries. The name comes from the fact that this +is the most common classic form of a bibliography. +In\important{\OptionValue{bibliography}{openstyle}} contrast, the +\OptionValue{bibliography}{openstyle}% +\IndexOption{bibliography~=\textKValue{openstyle}} setting selects a more +modern and open kind of bibliography. The name comes from the fact that the +\DescRef{maincls-experts.cmd.newblock} command inserts a paragraph break. The +bibliography entries appear more structured. They are less compact and seem +more relaxed or open. Information about defining new bibliography styles can +be found in the description of the \DescRef{maincls-experts.cmd.newbibstyle} +command in \autoref{sec:maincls-experts.experts}, +\DescPageRef{maincls-experts.cmd.newbibstyle}. + +In addition to the formatting style, you can select one more feature using +\PName{setting}. The bibliography is a kind of list of contents. But instead +of listing the contents of the document itself, it references external works. +With this reasoning, you could argue that the bibliography is a separate +chapter or section and therefore deserves a chapter or section number. The +\OptionValue{bibliography}{numbered}% +\important{\OptionValue{bibliography}{numbered}}% +\IndexOption{bibliography~=\textKValue{numbered}} setting does exactly that, +including creating an entry in the table of contents. In my opinion, a +traditional, annotated source list should by this reasoning be a separate +chapter too. Moreover, the bibliography is ultimately nothing you've written +yourself and so merits at most an unnumbered entry in the table of contents, +which is achieved with the \OptionValue{bibliography}{totoc}% +\IndexOption{bibliography~=\textKValue{totoc}} option. The default setting, +where the bibliography is produced as an unnumbered chapter and does not +receive an entry in the table of contents corresponds to +\OptionValue{bibliography}{nottotoc}% +\IndexOption{bibliography~=\textKValue{nottotoc}}. For more information, see +the \DescRef{\LabelBase.option.toc} option in \autoref{sec:\LabelBase.toc}, +especially the \PValue{bibliographynumbered}, \PValue{bibliography}, +and\PValue{nobibliography} values for this option on +\DescPageRef{\LabelBase.option.toc.bibliography}. + +Sometimes\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} a document made using \Class{scrbook} or \Class{scrreprt} +will have a bibliography for every chapter rather than one bibliography for +the whole document. In that case, it makes sense for the bibliography +itself\important{\OptionValue{bibliography=leveldown}} to be not a chapter but +a section. You can achieve this using the +\OptionValue{bibliography}{leveldown}% +\IndexOption{bibliography~=\textKValue{leveldown}} option. You can also use +this if you want the bibliography to appear with other lists under a common +heading, therefore this option is also available with \Class{scrartcl}. + +You can find a summary of available values for the \Option{bibliography} +option in \autoref{tab:\LabelBase.bibliography}. Note, however, that you can +define new values with +\DescRef{maincls-experts.cmd.newbibstyle}\IndexCmd{newbibstyle}. + +\begin{table} + \caption[{Available values for the \Option{bibliography} option}]{% + Predefined values for the \Option{bibliography} option for setting the + bibliography format} + \label{tab:\LabelBase.bibliography} + \begin{desctabular} + \pventry{leveldown}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The bibliography uses a sectioning command one level lower than + the default.% + \IndexOption{bibliography~=\textKValue{leveldown}}}% + \entry{\PValue{notoc}, \PValue{nottotoc}, \PValue{plainheading}}{% + The bibliography receives neither an entry in the table of contents nor + a number.% + \IndexOption{bibliography~=\textKValue{nottotoc}}}% + \entry{\PValue{numbered}, \PValue{tocnumbered}, \PValue{totocnumbered}, + \PValue{numberedtoc}, \PValue{numberedtotoc}}{% + The bibliography receives an entry in the table of contents and a + number.% + \IndexOption{bibliography~=\textKValue{numbered}}}% + \pventry{oldstyle}{% + The bibliography uses the classic, compact formation, where + \DescRef{maincls-experts.cmd.newblock}\IndexCmd{newblock} generates only + a horizontal glue.% + \IndexOption{bibliography~=\textKValue{oldstyle}}}% + \pventry{openstyle}{% + The bibliography uses the structured, open format where + \DescRef{maincls-experts.cmd.newblock}\IndexCmd{newblock} generates a + paragraph break.% + \IndexOption{bibliography~=\textKValue{openstyle}}}% + \pventry{standardlevel}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The bibliography uses the standard sectioning command level.% + \IndexOption{bibliography~=\textKValue{standardlevel}}}% + \entry{\PValue{toc}, \PValue{totoc}, \PValue{notnumbered}}{% + The bibliography receives an entry in the table of contents but no + number.% + \IndexOption{bibliography~=\textKValue{totoc}}}% + \end{desctabular} +\end{table} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{setbibpreamble}\Parameter{preamble} +\end{Declaration}% +You can use the \Macro{setbibpreamble} command to set a preamble for the +bibliography\Index{bibliography}. This preamble must be placed before the +command for issuing the bibliography. However, it need not be directly +in front of it. For example, it could be placed at the beginning of +the document. Like\textnote{Attention!} the +\OptionValueRef{\LabelBase}{bibliography}{totoc} and +\OptionValueRef{\LabelBase}{bibliography}{totocnumbered} options, this command +only works if you have not loaded a package which prevents this from happening +by redefining the \Environment{thebibliography} environment. Although the +\Package{natbib} package\IndexPackage{natbib} uses undocumented, internal +{\KOMAScript} macros, \Macro{setbibpreamble} could still work with the current +version of \Package{natbib} (see \cite{package:natbib}). +\begin{Example} + You want to point out that the bibliographical references are sorted + alphabetically by the names of the authors. You therefore use the following + command: +\begin{lstcode} + \setbibpreamble{References are in alphabetical order. + References with more than one author are sorted + according to the first author.\par\bigskip} +\end{lstcode} + The \Macro{bigskip}\IndexCmd{bigskip} command ensures that the + preamble and the first reference are separated by a large vertical + space.% +\end{Example}% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{BreakBibliography}\Parameter{interruption code} +\end{Declaration} +This\textnote{Attention!}\ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} command exists only if the +environment \Environment{thebibliography} has not been redefined by another +package. With this instruction, you can insert a break into the +bibliography. The \PName{interruption code} will be expanded inside a +group. Such a break may be, for example, a heading using +\DescRef{\LabelBase.cmd.minisec}. Unfortunately there is currently no way to +have this command automatically generated, for example by using a special +entry in the \BibTeX{} database. Therefore, it can currently only be used by +users who edit the bibliography directly. For this reason, its usefulness is +very limited.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{AfterBibliographyPreamble}\Parameter{code}% + \Macro{AtEndBibliography}\Parameter{code} +\end{Declaration} +In\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} +some cases, it may be useful to add some \PName{code} after the bibliography +preamble or just before the end of the bibliography. This is possible with the +help of these two instructions. +\begin{Example} + You want to set the bibliography not justified but ragged right. You can + achieve this with: +\begin{lstcode} + \AfterBibliographyPreamble{\raggedright} +\end{lstcode} + You can put this instruction anywhere before the bibliography. However, it is + recommended to do so in the preamble of the document or a separate package. +\end{Example} +The\textnote{Attention!} functionality of this instruction depends on +cooperation with packages modifying the bibliography, if you use such a +package\iffree{}{(see \autoref{sec:maincls-experts.coexistence}, +\DescPageRef{maincls-experts.cmd.AfterBibliographyPreamble})}.% +% +\EndIndexGroup +% +\EndIndexGroup + + +\section{Index} +\seclabel{index} +\BeginIndexGroup + +For general information about making a keyword index, see \cite{lshort}, +\cite{makeindex}, and \cite{xindy}. Using a package that redefines +commands or environments for the index \KOMAScript{}'s ability to influence +the index may disappear. This applies, for example, when using the +\Package{index}\IndexPackage{index} package, but not when using the +\Package{splitidx}\IndexPackage{splitidx} package (see +\cite{package:splitindex}). + +\begin{Declaration} + \OptionVName{index}{setting}% +\end{Declaration} +\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% +By default or with \OptionValue{index}{default}% +\IndexOption{index~=\textKValue{default}}, the index is an unnumbered chapter +(\Class{scrbook} or \Class{scrreprt}) or section (\Class{scrartcl}) without an +entry in the table of contents. Since\important{\OptionValue{index}{totoc}} +the index usually comes last in a book or similar document, it does not +actually need an entry in the table of contents. Nevertheless, if you want to +do this, for example because you are working with a multi-index keyword +dictionary such as the one that appears in this \iffree{guide}{book}, you can +create this with the +\OptionValue{index}{totoc}\IndexOption{index~=\textKValue{totoc}} option. +You\ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} can even number the index using the +\OptionValue{index}{numbered}\IndexOption{index~=\textKValue{numbered}} +setting. See also the \DescRef{\LabelBase.option.toc} option with the +\PValue{index} or \PValue{indexnumbered} values in +\autoref{sec:\LabelBase.toc} starting at +\DescPageRef{\LabelBase.option.toc.index}. + +For example, if you create multiple indexes with +\Package{splitidx}\IndexPackage{splitidx} (see \cite{package:splitindex}), +it may be useful to group them under a common heading. To make this possible, +\OptionValue{index}{leveldown}% +\ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\important{\OptionValue{index}{leveldown}} places the index +one sectioning level deeper than usual. In \Class{scrbook} and +\Class{scrreprt}, it is no longer a chapter but a section; with +\Class{scrartcl}, a subsection. The \OptionValue{index}{standardlevel}% +\ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\important{\OptionValue{index}{standardlevel}} option is +the counterpart to this and cancels any instance of +\OptionValue{index}{leveldown} used previously. + +You can find a summary of the available values for the \PName{setting} of +\Option{index} in \autoref{tab:maincls.index}. + +\begin{table} + \caption{Available values for the \Option{index} option} + \label{tab:maincls.index} + \begin{desctabular} + \pventry{leveldown}{% + \ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The index is moved down by one sectioning level.% + \IndexOption{index~=\textKValue{leveldown}}% + }% + \entry{\PValue{notoc}, \PValue{nottotoc}, \PValue{plainheading}}{% + The index does not receive an entry in the table of contents.% + \IndexOption{index~=\textKValue{nottotoc}}}% + \entry{\PValue{numbered}, \PValue{tocnumbered}, \PValue{totocnumbered}, + \PValue{numberedtoc}, \PValue{numberedtotoc}}{% + \ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The index receives an entry in the table of contents and is numbered.% + \IndexOption{index~=\textKValue{numbered}}}% + \pventry{standardlevel}{% + \ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The index is at the usual sectioning level.% + \IndexOption{index~=\textKValue{standardlevel}}% + }% + \entry{\PValue{toc}, \PValue{totoc}, \PValue{notnumbered}}{% + The index receives an entry in the table of contents without being + numbered.% + \IndexOption{index~=\textKValue{totoc}}}% + \end{desctabular} +\end{table} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{setindexpreamble}\Parameter{preamble} +\end{Declaration}% +As with the bibliography, you can also provide a preamble to the +index. This is often the case if you have more than one index or if +you mark different kinds of references by highlighting the page +numbers in different ways. +\begin{Example} + You have a document in which terms are both defined and used. The + page numbers of definitions are in bold. Of course you want to make + your reader aware of this fact. Thus you insert a preamble for the + index: +\begin{lstcode} + \setindexpreamble{All page numbers printed in \textbf{bold} + refer to definitions of terms. Page numbers printed + normally refer to pages where the term is used.\par\bigskip} +\end{lstcode} +\end{Example} + +Note\textnote{Attention!} that the page style is changed for the first page +of the index. The page style that is applied is defined in the macro +\DescRef{\LabelBase.cmd.indexpagestyle} (see +\autoref{sec:\LabelBase.pagestyle}, +\DescPageRef{\LabelBase.cmd.indexpagestyle}). + +The usual \LaTeX{} packages and additional programs are responsible for +creating, sorting, and outputting the index.% +\iftrue % Umbruchoptimierung + \iffree{}{ % + For example, the \Package{imakeidx}\IndexPackage{imakeidx} package + (see \cite{package:imakeidx}), which among other things automates the + invocation of the \File{makeindex} or \File{xindy} program, is highly + recommended. This eliminates a common source of error, particularly for + \LaTeX{} beginners.% + } + {\KOMAScript}, like the standard classes, provides only the basic macros + and environments for them.% +\fi +% +\EndIndexGroup +% +\EndIndexGroup +% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "english" +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrdatetime.tex b/macros/latex/contrib/koma-script/source-doc/english/scrdatetime.tex new file mode 100644 index 0000000000..7acd9f2bf7 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrdatetime.tex @@ -0,0 +1,443 @@ +% ====================================================================== +% scrdatetime.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrdatetime.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrpage2 of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber scrpage2 in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrdatetime.tex} + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (chapter: scrdate, scrtime)] +\translator{Markus Kohm\and Gernot Hassenpflug\and Karl Hagen} + +% Date of the translated German file: 2018-02-05 + +\chapter{The Day of the Week with \Package{scrdate}} +\labelbase{scrdate} +\BeginIndexGroup +\BeginIndex{Package}{scrdate} + +Originally, the \Package{scrdate} package could only give the day of the week +for the current date. Nowadays, it offers this and more for any date in the +Gregorian calendar. + +\begin{Declaration} + \Macro{CenturyPart}\Parameter{year}\\% + \Macro{DecadePart}\Parameter{year}% +\end{Declaration}% +The\ChangedAt{v3.05a}{\Package{scrdate}} \Macro{CenturyPart} command returns +the value of the century digits\,---\,thousands and hundreds\,---\,of a +\PName{year}. The \Macro{DecadePart} command, on the other hand, gives the +value of the remaining digits, i.\,e. the tens and the units. The +\PName{year} can have any number of digits. You can assign the value directly +to a counter or use it for calculations with +\Macro{numexpr}\IndexCmd{numexpr}. To output\textnote{Attention!} it as an +Arabic number, you should prefix it with \Macro{the}\IndexCmd{the}. + +\begin{Example} + You want to calculate and print the century of the current year. +\begin{lstcode} + The year \the\year\ is year \the\DecadePart{\year} + of the \engord{\numexpr\CenturyPart{\year}+1\relax} century. +\end{lstcode} + The result would be: + \begin{quote} + The year \the\year\ is year \the\DecadePart{\year} + of the \engordnumber{\numexpr\CenturyPart{\year}+1\relax} century. + \end{quote} + This example uses the \Package{engord}\IndexPackage{engord} package. + See \cite{package:engord} for more information. +\end{Example} + +Note\textnote{Attention!} that the counting method used here treats the year +2000 as year~0\,---\,and therefore the first year\,---\,of the 21st~century. +If necessary, however, you can make a correction with \Macro{numexpr}, as +shown for the ordinal number in the example.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DayNumber}\Parameter{year}\Parameter{month}\Parameter{day}\\% + \Macro{ISODayNumber}\Parameter{ISO-date}% +\end{Declaration}% +These\ChangedAt{v3.05a}{\Package{scrdate}} two commands return the value of +the day-of-the-week\Index{day>of the week} number for any date. They differ +only in the method of specifying the date. While the \Macro{DayNumber} command +requires the \PName{year}, \PName{month}, and \PName{day} as separate +parameters, the \Macro{ISODayNumber} command expects an \PName{ISO-date} as a +single argument, \PName{ISO-date}, using the ISO notation +\PName{year}\texttt{-}\PName{month}\texttt{-}\PName{day}. It does not matter +if the \PName{month} or \PName{day} have one or two digits. You can use the +result of both commands to assign directly to a counter or for calculations +using \Macro{numexpr}\IndexCmd{numexpr}. To print\textnote{Attention!} it as +an Arabic number, you should prefix it with \Macro{the}\IndexCmd{the}. + +\begin{Example} + You want to know the number of the day of the week of the 1st~May~2027. +\begin{lstcode} + The 1st~May~2027 has \the\ISODayNumber{2027-5-1} + as the number of the day of the week. +\end{lstcode} + The result will be: + \begin{quote} + The 1st~May~2027 has \the\ISODayNumber{2027-5-1} + as the number of the day of the week. + \end{quote} +\end{Example} + +It is particularly worth noting that you can even step a specified number of +days into the future or or the past from a given date. +\begin{Example} + You want to know the number of the day of the week 12~days from now + and 24~days before the 24th~December~2027. +\begin{lstcode} + In 12~days, the number of the day of the week + will be \the\DayNumber{\year}{\month}{\day+12}, and + 24~days before the 24th~December~2027 it will be + \the\ISODayNumber{2027-12-24-24}. +\end{lstcode} + The result could be, for example: + \begin{quote} + In 12~days, the number of the day of the week + will be \the\DayNumber{\year}{\month}{\day+12}, and + 24~days before the 24th~December~2027 it will be + \the\ISODayNumber{2027-12-24-24}. + \end{quote} +\end{Example} + +The days of the week are numbered as follows: Sunday\,=\,0, Monday\,=\,1, +Tuesday\,=\,2, Wednesday\,=\,3, Thursday\,=\,4, Friday\,=\,5, and +Saturday\,=\,6.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DayNameByNumber}\Parameter{number of the day of the week}\\% + \Macro{DayName}\Parameter{year}\Parameter{month}\Parameter{day}\\% + \Macro{ISODayName}\Parameter{ISO-date}% +\end{Declaration}% +Usually\ChangedAt{v3.05a}{\Package{scrdate}} you are less interested in the +number of the day of the week than in its name. Therefore, the +\Macro{DayNameByNumber} command returns the name of the day of the week +corresponding to a day-of-the-week number. This number can be the result, for +example, of \Macro{DayNumber} or \Macro{ISODayNumber}. The two commands +\Macro{DayName} and \Macro{ISODayName} directly return the name of the day of +the week of a given date. + +\begin{Example} + You want to know the name of the day of the week of the 24th~December~2027. +\begin{lstcode} + Please pay by \ISODayName{2027-12-24}, + 24th~December~2027 the amount of \dots. +\end{lstcode} + The result will be: + \begin{quote} + Please pay by \ISODayName{2027-12-24}, + 24th~December~2027 the amount of \dots. + \end{quote} +\end{Example} + +Once again, it is particularly worth noting that you can perform calculations, +to a certain extent: +\begin{Example} + You want to know the names of the day of the week 12~days from now + and 24~days before the 24th~December~2027. +\begin{lstcode} + In 12~days, the name of the day of the week + will be \DayName{\year}{\month}{\day+12}, and + 24~days before the 24th~December~2027 it will be + \ISODayName{2027-12-24-24}, while two weeks + and three days after a Wednesday will be a + \DayNameByNumber{3+2*7+3}. +\end{lstcode} + The result could be, for example: + \begin{quote} + In 12~days, the name of the day of the week + will be \DayName{\year}{\month}{\day+12}, and + 24~days before the 24th~December~2027 it will be + \ISODayName{2027-12-24-24}, while two weeks + and three days after a Wednesday will be a + \DayNameByNumber{3+2*7+3}. + \end{quote} +\end{Example}% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ISOToday}% + \Macro{IsoToday}% + \Macro{todaysname}% + \Macro{todaysnumber}% +\end{Declaration}% +In the previous examples, the current date was always specified cumbersomely +using the \TeX{} registers \Macro{year}\IndexCmd{year}, +\Macro{month}\IndexCmd{month}, and \Macro{day}\IndexCmd{day}. The +\Macro{ISOToday}\ChangedAt{v3.05a}{\Package{scrdate}} and \Macro{IsoToday} +commands directly return the current date in ISO-notation. These commands +differ only in the fact that \Macro{ISOToday} always outputs a two-digit month +and day, while \Macro{IsoToday} outputs single-digit numbers for values less +than 10. The \Macro{todaysname} command directly returns the name of the +current day of the week, while \Macro{todaysnumber} returns the number of the +current day of the week. You can find more information about using this value +in the explanations of \DescRef{scrdate.cmd.DayNumber} and +\DescRef{scrdate.cmd.ISODayNumber}. + +\begin{Example} + I want to show you on what day of the week this document was typeset: +\begin{lstlisting} + This document was created on a \todaysname. +\end{lstlisting} + This will result, for example, in: + \begin{quote} + This document was created on a \todaysname. + \end{quote} +\end{Example} + +For languages that have a case system for nouns, note that the package cannot +decline words. The terms are given in the form appropriate for displaying a +date in a letter, which is the nominative singular for the currently supported +languages. Given this limitation, the example above will not work correctly if +translated directly into some other languages. + +\begin{Explain} + The\textnote{Hint!} names of the weekdays in \Package{scrdate} all have + initial capital letters. If you need the names completely in lower case, for + example because that is the convention in the relevant language, simply wrap + the command with the \LaTeX{} \Macro{MakeLowercase}\IndexCmd{MakeLowercase}% + \important{\Macro{MakeLowercase}} command: + % Umbruchkorrektur: listings +\begin{lstcode} + \MakeLowercase{\todaysname} +\end{lstcode} + This converts the whole argument into lower-case letters. Of course, you can + also do this for + \DescRef{scrdate.cmd.DayNameByNumber}\IndexCmd{DayNameByNumber}, + \DescRef{scrdate.cmd.DayName}\IndexCmd{DayName}, and + \DescRef{scrdate.cmd.ISODayName}\IndexCmd{ISODayName} commands described + above.% +\end{Explain}% +\EndIndexGroup + + +\begin{Declaration} + \Macro{nameday}\Parameter{name} +\end{Declaration}% +Just as you can directly modify the output of \Macro{today} with +\DescRef{maincls.cmd.date}\IndexCmd{date}, so you can change the output of +\DescRef{scrdate.cmd.todaysname} to \PName{name} with \Macro{nameday}. +\begin{Example} + You change the current date to a fixed value using + \DescRef{maincls.cmd.date}. You are not interested in the actual name of the + day, but want only to show that it is a workday. So you write: +\begin{lstlisting} + \nameday{workday} +\end{lstlisting} + After this, the previous example will result in: + \begin{quote}\nameday{workday} + This document was created on a \todaysname. + \end{quote} +\end{Example} +There's no corresponding command to change the result of +\DescRef{scrdate.cmd.ISOToday}\IndexCmd{ISOToday} or +\DescRef{scrdate.cmd.IsoToday}\IndexCmd{IsoToday}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{newdaylanguage}\Parameter{language}% + \Parameter{Monday}\Parameter{Tuesday}% + \Parameter{Wednesday}\Parameter{Thursday}% + \Parameter{Friday}\Parameter{Saturday} + \Parameter{Sunday}% +\end{Declaration} +Currently the \Package{scrdate} package recognizes the following languages: +\begin{itemize}\setlength{\itemsep}{.5\itemsep} +\item Croatian (\PValue{croatian}), +\item Czech (\PValue{czech}\ChangedAt{v3.13}{\Package{scrdate}}), +\item Danish (\PValue{danish}), +\item Dutch (\PValue{dutch}), +\item English (\PValue{american}\ChangedAt{v3.13}{\Package{scrdate}}, + \PValue{australian}, \PValue{british}, \PValue{canadian}, \PValue{english}, + \PValue{UKenglish}, and USenglish), +\item Finnish (\PValue{finnish}), +\item French (\PValue{acadian}, \PValue{canadien}, + \PValue{francais}\ChangedAt{v3.13}{\Package{scrdate}}, and \PValue{french}), +\item German (\PValue{austrian}\ChangedAt{v3.08b}{\Package{scrdate}}, + \PValue{german}, \PValue{naustrian}, \PValue{ngerman}, + \PValue{nswissgerman}, and + \PValue{swissgerman}\ChangedAt{v3.13}{\Package{scrdate}}), +\item Italian (\PValue{italian}), +\item Norwegian (\PValue{norsk}), +\item Polish (\PValue{polish}\ChangedAt{v3.13}{\Package{scrdate}}), +\item Slovak (\PValue{slovak}), +\item Spanish (\PValue{spanish}), +\item Swedish (\PValue{swedish}). +\end{itemize} +You can also configure it for additional languages. To do so, the first +argument of \Macro{newdaylanguage} is the name of the language, and the other +arguments are the names of the corresponding days of the week. + +In the current implementation, it does not matter whether you load +\Package{scrdate} before or after \Package{ngerman}\IndexPackage{ngerman}, +\Package{babel}\IndexPackage{babel}, or similar packages. In each case the +correct language will be used provided it is supported. + +\begin{Explain} + To be more precise, as long as you select a language in a way that is + compatible with \Package{babel}\IndexPackage{babel}, \Package{scrdate} will + use the correct language. If this is not the case, you will get (US) English + names. +\end{Explain} + +Of course, if you create definitions for a language that was previously +unsupported, please mail them to the author of \KOMAScript{}. There is a good +chance that future versions of \KOMAScript{} will add support for that +language.% +\EndIndexGroup +% +\EndIndexGroup + + +\chapter{The Current Time with \Package{scrtime}} +\labelbase{scrtime} +\BeginIndexGroup +\BeginIndex{Package}{scrtime} + +This package lets you find the current time. Starting with version~3.05, the +package also supports the option interface already familiar from the +\KOMAScript{} classes and various other \KOMAScript{} packages. See, for +example, \autoref{sec:typearea.options} for more information. + +\begin{Declaration}% + \Macro{thistime}\OParameter{delimiter}% + \Macro{thistime*}\OParameter{delimiter} +\end{Declaration}% +\Macro{thistime} returns the current time\Index{time} in hours and minutes. +The delimiter between the values of hour, minutes and seconds can be given in +the optional argument. The default is the character ``\PValue{:}''. + +\Macro{thistime*} works in almost the same way as \Macro{thistime}. The only +difference is that, unlike \Macro{thistime}, \Macro{thistime*} does not add a +leading zero to the minute field when its value is less than 10. Thus, with +\Macro{thistime} the minute field has always two places. +\begin{Example} + The line +\begin{lstlisting} + Your train departs at \thistime. +\end{lstlisting} + results, for example, in: + \begin{quote} + Your train departs at \thistime. + \end{quote} + or: + \begin{quote} + Your train departs at 23:09. + \end{quote} + \bigskip + In contrast to the previous example a line like: +\begin{lstlisting} + This day is already \thistime*[\ hours and\ ] minutes old. +\end{lstlisting} + results in: + \begin{quote} + This day is already \thistime*[\ hours and\ ] minutes old. + \end{quote} + or: + \begin{quote} + This day is already 12 hours and 25 minutes old. + \end{quote} +\end{Example} +\EndIndexGroup + + +\begin{Declaration}% + \Macro{settime}\Parameter{time} +\end{Declaration}% +\Macro{settime} sets the output of \DescRef{scrtime.cmd.thistime} and +\DescRef{scrtime.cmd.thistime*} to a fixed value. In this case, the optional +parameter of \DescRef{scrtime.cmd.thistime} or \DescRef{scrtime.cmd.thistime*} +is ignored, since the complete string returned by +\DescRef{scrtime.cmd.thistime} or \DescRef{scrtime.cmd.thistime*} has been +explicitly defined. \Macro{settime}.% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{12h}{simple switch}% +\end{Declaration}% +\BeginIndex{Option}{24h}% +With the \Option{12h}\ChangedAt{v3.05a}{\Package{scrtime}} option, you can +select whether to print the time given by \DescRef{scrtime.cmd.thistime} and +\DescRef{scrtime.cmd.thistime*} in 12- or 24-hour format. The option accepts +the values for simple switches listed in \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch}. Using the option without a value is +equivalent to \OptionValue{12h}{true}, and therefore activates the +12-hour-format. The default, however, is \Option{24h}. + +You can set this option globally in the optional argument of +\DescRef{typearea.cmd.documentclass}, as a package option in the optional +argument of \DescRef{typearea.cmd.usepackage}, or even after loading the +package using \DescRef{typearea.cmd.KOMAoptions} or +\DescRef{typearea.cmd.KOMAoption} (see, e.\,g. \autoref{sec:typearea.options}, +\DescPageRef{typearea.cmd.KOMAoptions}). However the option no longer has any +effect on the if you call \DescRef{scrtime.cmd.settime}. After invoking this +command, the time is output only with the value and in the format specified +there. + +For\textnote{Attention!} the sake of compatibility with earlier versions of +\Package{scrtime}, the option \Option{24h} will switch to 24-hour format if +used in the optional argument of \Macro{documentclass} or \Macro{usepackage}. +However, you should not use this option any longer.% +\EndIndexGroup +% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrextend.tex b/macros/latex/contrib/koma-script/source-doc/english/scrextend.tex new file mode 100644 index 0000000000..5504ee4b0d --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrextend.tex @@ -0,0 +1,222 @@ +% ====================================================================== +% scrextend.tex +% Copyright (c) Markus Kohm, 2002-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrextend.tex +% 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. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Package scrextend for Document Writers +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Paket scrextend fuer Dokument-Autoren +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{scrextend.tex} + [$Date: 2018-04-09 10:14:11 +0200 (Mon, 09 Apr 2018) $ + KOMA-Script package scrextend] +\translator{Markus Kohm\and Karl Hagen} + +% Date of the translated German file: 2018-01-24 + +\chapter[{\KOMAScript{} Features for Other Classes with \Package{scrextend}}] + {Using Basic Features of the \KOMAScript{} Classes in Other Classes with the + \Package{scrextend} Package} +\labelbase{scrextend} +\BeginIndexGroup% +\BeginIndex{Package}{scrextend}% + +There are some features that are common to all \KOMAScript{} classes. This +applies not only to the \Class{scrbook}, \Class{scrreprt}, and +\Class{scrartcl} classes, which are intended to replace the standard classes +\Class{book}, \Class{report}, and \Class{article}, but also to a large extend +the \KOMAScript{} class \Class{scrlttr2}, the successor to \Class{scrlettr}, +which is intended for letters. These basic features, which can be found in the +classes mentioned above, are also provided by package \Package{scrextend} from +\KOMAScript{} version~3.00 onward. This\textnote{Attention!} package should +not be used with \KOMAScript{} classes. It is intended for use with other +classes only. If you attempt to load the package with a \KOMAScript{} class, +\Package{scrextend} will detect this and reject loading it with a warning +message. + +The fact that \hyperref[cha:scrlttr2]{\Package{scrletter}}% +\IndexPackage{scrletter} can be used not only with \KOMAScript{} classes but +also with the standard classes is partly due to \Package{scrextend}. If +\hyperref[cha:scrlttr2]{\Package{scrletter}} detects that it is not being used +with a \KOMAScript class, it automatically loads \Package{scrextend}. Doing +so makes all required \KOMAScript{} classes available. + +Of course, there is no guarantee that \Package{scrextend} will work with all +classes. The package has been designed primarily to extend the standard +classes and those derived from them. In any case, before you use +\Package{scrextend}, you should first make sure that the class you are using +does not already provide the feature you need. + +In addition to the features described in this chapter, there are a few more +that are primarily intended for authors of classes and packages. These can be +found in \autoref{cha:scrbase}, starting on \autopageref{cha:scrbase}. The +\hyperref[cha:scrbase]{\Package{scrbase}}% +\important{\hyperref[cha:scrbase]{\Package{scrbase}}}\IndexPackage{scrbase} +package documented there is used by all \KOMAScript{} classes and the +\Package{scrextend} package. + +All \KOMAScript{} classes and the \Package{scrextend} package also load the +\hyperref[cha:scrlfile]{\Package{scrlfile}}% +\important{\hyperref[cha:scrlfile]{\Package{scrlfile}}}\IndexPackage{scrlfile} +package described in \autoref{cha:scrlfile} starting on +\autopageref{cha:scrlfile}. Therefore the features of this package are also +available when using \Package{scrextend}. + +\iftrue % Umbruchkorrekturtext +In contrast, only the \KOMAScript{} classes \Class{scrbook}, \Class{scrreprt}, +and \Class{scrartcl} load the \hyperref[cha:tocbasic]{\Package{tocbasic}} +package (see \autoref{cha:tocbasic} starting on \autopageref{cha:tocbasic}), +which is designed for authors of classes and packages. For this reason, the +features defined there are found only in those classes and not in +\Package{scrextend}. Of course you can still use +\hyperref[cha:tocbasic]{\Package{tocbasic}} together with +\Package{scrextend}.% +\fi + +\LoadCommonFile{options}% \section{Early or late Selection of Options} + +\LoadCommonFile{compatibility}% \section{Compatibility with Earlier Versions of \KOMAScript} + + +\section{Optional, Extended Features} +\seclabel{optionalFeatures} + +The \Package{scrextend} package provides some optional, extended features. +These features are not available by default but can be activated. These +features are optional because, for example, they may conflict with features of +the standard classes of other commonly used packages. + +\begin{Declaration} + \OptionVName{extendedfeature}{feature} +\end{Declaration} +With this option, you can activate an extended \PName{feature} of +\Package{scrextend}. This option is available only while loading +\Package{scrextend}. You must therefore specify this option in the optional +argument of \DescRef{\LabelBase.cmd.usepackage}\PParameter{scrextend}. % +\iffree{% + An overview of all available features is shown in + \autoref{tab:scrextend.optionalFeatures}. + + \begin{table} + \caption[{Available extended features of + \Package{scrextend}}]{Overview of the optional extended + features of \Package{scrextend}} + \label{tab:scrextend.optionalFeatures} + \begin{desctabular} + \entry{\PName{title}}{% + title pages have the additional features of the \KOMAScript{} classes; + this applies not only to the commands for the title page but also to + the \DescRef{\LabelBase.option.titlepage} option (see + \autoref{sec:scrextend.titlepage}, from + \autopageref{sec:scrextend.titlepage})% + }% + \end{desctabular} + \end{table} +}{% + \par% + Currently the only available extended \PName{feature} is + \PValue{title}\IndexOption[indexmain]{extendedfeature~=\textKValue{title}}% + \important{\OptionValue{extendedfeature}{title}}. + This \PName{feature} gives title pages the features of the \KOMAScript{} + classes, as described in \autoref{sec:scrextend.titlepage} starting on + \autopageref{sec:scrextend.titlepage}.% +}% +% +\EndIndexGroup + + +\LoadCommonFile{draftmode}% \section{Draft Mode} + +\LoadCommonFile{fontsize}% + +\LoadCommonFile{textmarkup}% \section{Text Markup} + +\LoadCommonFile{titles}% \section{Document Title Pages} + +\LoadCommonFile{oddorevenpage}% \section{Detection of Odd and Even Pages} + +\section{Choosing a Predefined Page Style} +\seclabel{pagestyle} + +One of the basic features of a document is the page +style\Index[indexmain]{page>style}. In \LaTeX{}, the page style primarily +determines the content of headers and footers. The \Package{scrextend} package +does not define any page styles itself. Instead it uses the page styles of the +\LaTeX{} kernel. + + +\begin{Declaration} + \Macro{titlepagestyle} +\end{Declaration}% +\Index{title>page style}% +On some pages \DescRef{maincls.cmd.thispagestyle}\IndexCmd{thispagestyle} +automatically selects a different page style. Currently, \Package{scrextend} +only does this for title pages, and only if +\OptionValueRef{\LabelBase}{extendedfeature}{title} has been used (see +\autoref{sec:scrextend.optionalFeatures}, +\DescPageRef{scrextend.option.extendedfeature}). In this case the page style +specified in \DescRef{maincls.cmd.thispagestyle} will be used. The default for +\DescRef{maincls.cmd.thispagestyle} is +\PageStyle{plain}\IndexPagestyle{plain}. This page style is defined by the +\LaTeX{} kernel, so it should always be available.% +\EndIndexGroup + +\LoadCommonFile{interleafpage}% \section{Interleaf Pages} + +\LoadCommonFile{footnotes}% \section{Footnotes} + +\LoadCommonFile{dictum}% \section{Dicta} + +\LoadCommonFile{lists}% \section{Lists} + +\LoadCommonFile{marginpar}% \section{Margin Notes} +% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% ispell-local-dictionary: "english" +%%% coding: us-ascii +%%% TeX-master: "../guide.tex" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrhack.tex b/macros/latex/contrib/koma-script/source-doc/english/scrhack.tex new file mode 100644 index 0000000000..a7dfac605c --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrhack.tex @@ -0,0 +1,264 @@ +% ====================================================================== +% scrhack.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrhack.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrhack of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------------- +% +% Kapitel ueber scrhack in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrhack.tex} + [$Date: 2018-03-27 11:46:14 +0200 (Tue, 27 Mar 2018) $ + KOMA-Script guide (chapter: scrhack)] +\translator{Markus Kohm\and Karl Hagen} + +% Date of the translated German file: 2018-02-05 +\chapter{Improving Third-Party Packages with \Package{scrhack}} +\labelbase{scrhack} + +\BeginIndexGroup +\BeginIndex{Package}{scrhack} +Some packages from other authors do not work well with \KOMAScript{}. It is +often very tedious for the author of \KOMAScript{} to convince the authors of +these packages to make specific improvements. This also applies to packages +whose development has been discontinued. That's why the \Package{scrhack} was +created. This package alters the commands and definitions of other to work +better with \KOMAScript{}. Some changes are also useful when using other +classes. + +\section{Development Status} +\label{scr:scrhack.draft} + +Although this package has been part of \KOMAScript{} for long time and is used +by many users, there's one problem with it. Redefining macros from third-party +packages depends on knowing the exact definition and use of those macros. This +also means that it depends on specific versions of those packages. If you use +a unknown version of such a package, \Package{scrhack} may not be able to +execute the required patch. In extreme cases, patching an unknown version can +lead to an error. + +Because \Package{scrhack} must be continuously modified to accommodate new +releases of third-party packages, it can never be considered complete. +Therefore \Package{scrhack} will remain permanently in a beta version. +Although its use will generally be a benefit, its correct functioning cannot +be permanently guaranteed. + +\LoadCommonFile{options}% \section{Early or late Selection of Options} + +\section{Using \Package{tocbasic}} +\seclabel{improvement} + +In the early days of \KOMAScript{}, users wanted to handle lists of floating +environments created with the +\Package{float}\IndexPackage{float}\important{\Package{float}} package in the +same way as the list of figures and list of tables created by \KOMAScript{} +itself. At that time the author of \KOMAScript{} contacted the author of +\Package{float} to propose an interface to support such an extension. A +somewhat modified form of that interface was implemented with the +\Macro{float@listhead}\IndexCmd[indexmain]{float@listhead} and +\Macro{float@addtolists}\IndexCmd[indexmain]{float@addtolists} commands. + +Later it became apparent that these two commands were not flexible enough to +fully support all of \KOMAScript's capabilities. Unfortunately, the author of +\Package{float} had already ceased development by that point, so further +changes to this package cannot be expected. + +Other package authors have also adopted these two commands, and it became +apparent that the implementation in some packages, including \Package{float}, +means that all these packages can only be loaded in a specific order, even +though they are otherwise unrelated to each other. + +To overcome all these disadvantages and problems, \KOMAScript{} no longer +officially supports this old interface. Instead, \KOMAScript{} warns if the +old interface is used. At the same time, the +\Package{tocbasic}\IndexPackage{tocbasic}\important{\Package{tocbasic}} +package (see \autoref{cha:tocbasic}) has been designed and implemented as a +central interface for managing of table of contents and similar content lists. +This package provides many more advantages and features than the two old +commands. + +Although the effort to use this package is very small, so far the authors of +most of the packages that use the old interface have not made any adjustments. +Therefore \Package{scrhack} contains appropriate modifications of the +\Package{float}\IndexPackage{float}\important{\Package{float}, +\Package{floatrow}, \Package{listings}}, +\Package{floatrow}\IndexPackage{floatrow}, and +\Package{listings}\IndexPackage{listings} packages. Merely loading +\Package{scrhack} is sufficient to make these packages recognize not only the +setting of the \KOMAScript{} option +\DescRef{maincls.option.listof}\IndexOption{listof~=\PName{setting}}, but also +to react to the language switching features of the +\Package{babel}\IndexPackage{babel} package. You can find more information +about the features available by switching packages to \Package{tocbasic} in +\autoref{sec:tocbasic.toc}. + +If you do not want this modification for any of the packages, or if it causes +problems, you can deactivate it selectively with the +\OptionValue{float}{false}\IndexOption[indexmain]{float~=\textKValue{false}}, +\OptionValue{floatrow}{false}\IndexOption[indexmain]{floatrow~=\textKValue{false}}, +or +\OptionValue{listings}{false}\IndexOption[indexmain]{listings~=\textKValue{false}} +option. Note\textnote{Attention!} that changing these options after loading +the associated package has no effect! + + +\section{Incorrect Assumptions about \Macro{@ptsize}} +\seclabel{ptsize} + +Some packages assume that the class-internal macro +\Macro{@ptsize}\IndexCmd{@ptsize} both is defined and expands to an integer. +For compatibility, \KOMAScript{} defines \Macro{@ptsize} even if the basic +font size is something other than 10\Unit{pt}, 11\Unit{pt}, or 12\Unit{pt}. +\KOMAScript{} also allows non-integer font sizes. So \Macro{@ptsize} can, of +course, also expand to a non-integer number. + +One\ChangedAt{v3.17}{\Package{scrhack}} of the packages that cannot cope with +a non-integer \Macro{@ptsize} is +\Package{setspace}\IndexPackage[indexmain]{setspace}. Additionally, the values +set by this package are always dependent on the basic font size, even if the +setting is made in the context of another font size. The \Package{scrhack} +package solves both problems by redefining \Macro{onehalfspacing} and +\Macro{doublespacing} to set the spacing relative to the actual font size. + +If you do not want this modification for the package, or if it causes +problems, you can deactivate it selectively with the +\OptionValue{setspace}{false}\IndexOption[indexmain]{setspace~=\textKValue{false}} +option. Note\textnote{Attention!} that changing this option after loading +\Package{setspace} has no effect! Likewise, if you use \Package{setspace} with +either the \Option{onehalfspacing} or \Option{doublespacing} option, you must +load \Package{scrhack} first. + + +\section{Older Versions of \Package{hyperref}} +\seclabel{hyperref} + +Versions of \Package{hyperref} before 6.79h set the link +anchors after the heading of the starred versions of commands like +\DescRef{maincls.cmd.part*}, \DescRef{maincls.cmd.chapter*}, etc. instead of +before them. Since then, this problem has been resolved at the suggestion of +\KOMAScript{}'s author. But because the change took more than a year, a patch +was added to \Package{scrhack}. Although this can also be deactivated with +\OptionValue{hyperref}{false}, you should instead use the current +\Package{hyperref} release. In this case \Package{scrhack} automatically +deactivates this unnecessary patch.% + + +\section{Inconsistent Handling of \Length{textwidth} and \Length{textheight}} +\seclabel{lscape} + +The\ChangedAt{v3.18}{\Package{scrhack}} +\Package{lscape}\IndexPackage[indexmain]{lscape} package defines a +\Environment{landscape}\IndexEnv{landscape} environment to set the page +contents, but not the header or footer in landscape mode. Inside this +environment, \Length{textheight}\IndexLength{textheight} is set to the value +of \Length{textwidth}, but \Length{textwidth} is not set to the former value +of \Length{textheight}. This is inconsistent. As far as I know, +\Length{textwidth} is left unchanged because setting it to \Length{textheight} +could interfere with other packages or user commands. But changing +\Length{textheight} also has this potential, and indeed it breaks, for +example, \Package{showframe}\IndexPackage{showframe} and +\Package{scrlayer}\IndexPackage{scrlayer}. Thus it would be best if +\Length{textheight} too remained unchanged. \Package{scrhack} uses the +\Package{xpatch} package (see \cite{package:xpatch}) to modify the +\Macro{landscape} environment's start macro appropriately. + +If you do not want this modification, or if it causes problems, you can +deactivate it with the +\OptionValue{lscape}{false}\IndexOption[indexmain]{lscape~=\textKValue{false}} +option. Note\textnote{Attention!} that changing \Option{lscape} subsequently +with \DescRef{\LabelBase.cmd.KOMAoption}\IndexCmd{KOMAoption} or +\DescRef{\LabelBase.cmd.KOMAoptions}\IndexCmd{KOMAoptions} has an effect only +if it was not \PValue{false} while loading \Package{lscape}. + +Incidentally, the \Package{pdflscape}\IndexPackage[indexmain]{pdflscape} +package also uses \Package{lscape}, so \Package{scrhack} affects the +functioning of this package too.% + + +\section{Special Case \Package{nomencl}} +\label{sec:nomencl} + +The\ChangedAt{v3.23}{\Package{scrhack}} hack for the +\Package{nomencl}\IndexPackage[indexmain]{nomencl} represents a somewhat +special case. First, it ensures that the optional table of contents entry for +the nomenclature observes the \OptionValueRef{maincls}{toc}{indentunnumbered} +option. Somewhat incidentally, it also reserves the file extensions \File{nlo} +and \File{nls} for the owner \PValue{nomencl} (see +\DescRef{tocbasic.cmd.addtotoclist}, \autoref{sec:tocbasic.basics}, +\DescPageRef{tocbasic.cmd.addtotoclist}). + +It also changes the \Environment{thenomenclature}\IndexEnv{thenomenclature} +environment to use +\DescRef{tocbasic.cmd.tocbasic@listhead}\IndexCmd{tocbasic@listhead} for the +heading (see \autoref{sec:tocbasic.internals}, +\DescPageRef{tocbasic.cmd.tocbasic@listhead}). In this way, the hack lets you +set various attribute for the \File{nls} extension using +\DescRef{tocbasic.cmd.setuptoc}\IndexCmd{setuptoc}% +\important{\DescRef{tocbasic.cmd.setuptoc}}. For example, not only can you +enter the nomenclature in the table of contents with +\DescRef{tocbasic.cmd.setuptoc}\PParameter{nls}\PParameter{numbered}, but you +can also number it immediately. You can find more about +\DescRef{tocbasic.cmd.setuptoc} and its available settings in +\autoref{sec:tocbasic.toc}, starting on \DescPageRef{tocbasic.cmd.setuptoc}. +As a small but important side effect, this patch also gives the nomenclature +also matching running head, if automatic running heads are activated, for +example by using the \DescRef{maincls.pagestyle.headings} page style. + +This rather simple patch is an example of how packages that do not define +floating environments can still benefit from \Package{tocbasic}. However, you +do not want this change, or if it causes problems, you can deactivate it with +the \OptionValue{nomencl}{false}% +\IndexOption[indexmain]{nomencl~=\textKValue{false}} option. +The\textnote{Achtung!} setting of the option when \Package{nomencl} is loaded +is crucial! Later changes to the option with +\DescRef{\LabelBase.cmd.KOMAoption} or \DescRef{\LabelBase.cmd.KOMAoptions} +have no influence and will lead to a corresponding warning.% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% ispell-local-dictionary: "english" +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrjura.tex b/macros/latex/contrib/koma-script/source-doc/english/scrjura.tex new file mode 100644 index 0000000000..fb782ca3dc --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrjura.tex @@ -0,0 +1,1165 @@ +% ====================================================================== +% scrjura.tex +% Copyright (c) Markus Kohm, 2011-2019 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrjura.tex +% Copyright (c) Markus Kohm, 2011-2019 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrjura of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber scrjura in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{scrjura.tex}% + [$Date: 2019-01-15 08:29:44 +0100 (Tue, 15 Jan 2019) $ + KOMA-Script guide (chapter: scrjura)] + +\translator{Alexander Willand\and Markus Kohm\and Karl Hagen} + +% Date of the translated German file: 2018-07-20 + +\chapter{Support for the Law Office with \Package{scrjura}} +\labelbase{scrjura} +\BeginIndexGroup +\BeginIndex{Package}{scrjura} + +If you want to write a contract\Index{contract}, the articles of association +for a company or an association, a law, or a legal commentary, the package +\Package{scrjura} will provide typographical support. Although +\Package{scrjura} is intended to provide general help for legal documents, the +contract is the central element of the package. Particular attention is paid +to clauses, titles, and numbered provisions\,---\,if there are several of +them in a clause\,---, numbered sentences, entries in the table of +contents, and cross references according to German standards. + +The package has been developed in cooperation with Dr Alexander Willand of +Karlsruhe. Many of its features go back to constructive inquiries from Prof +Heiner Richter of the Hochschule Stralsund University of Applied Sciences. + +Note\textnote{Attention!} that the package works with +\Package{hyperref}\IndexPackage{hyperref}. Nevertheless, \Package{hyperref} +has to be loaded after \Package{scrjura} as usual. + +\LoadCommonFile{options}% \section{Early or late Selection of Options} + +\LoadCommonFile{textmarkup}% \section{Text Markup} + +\section{Table of Contents} +\label{sec:scrjura.toc} + +The headings of clauses can also be added automatically to the table of +contents, if desired. + +\begin{Declaration} + \OptionVName{juratotoc}{simple switch}% + \OptionVName{juratotoc}{level number} +\end{Declaration} +Clauses\Index{clause} are shown in the table of contents only if their +\PName{level number} is less than or equal to the +\DescRef{maincls.counter.tocdepth}% +\important{\DescRef{maincls.counter.tocdepth}}\IndexCounter{tocdepth} counter +(see \autoref{sec:maincls.toc}, \DescPageRef{maincls.counter.tocdepth}). By +default, the \PName{level number} is 10000, which is also used if the option +is switched off with the \PName{simple +switch}\important{\OptionValue{juratotoc}{false}} (see +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}). Because the +\DescRef{maincls.counter.tocdepth} counter usually has a one-digit value, +clause entries are therefore not normally displayed in the table of contents. + +If you switch on the option using the \PName{simple switch}% +\important{\OptionValue{juratotoc}{true}}, the \PName{level number} 2 is used +so that clauses are shown in the table of contents on the same level as +subsections. For the default setting of \DescRef{maincls.counter.tocdepth}, +clauses are then shown in all \KOMAScript{} classes.% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{juratocindent}{indent}% + \OptionVName{juratocnumberwidth}{number width} +\end{Declaration} +These two options can be used to determine the indentation for the clause +entries in the table of contents as well as the space reserved for the numbers +there. The defaults are the same as for subsection entries in +\Class{scrartcl}.% +\EndIndexGroup + + +\section{Environment for Contracts} +\label{sec:scrjura.contract} + +\BeginIndexGroup +\BeginIndex{}{contract} +The essential mechanisms of \Package{scrjura} are available only inside the +contract environment. + +\begin{Declaration} + \begin{Environment}{contract}\end{Environment} +\end{Declaration} +Currently, this is the one and only environment for \Package{scrjura}. Using +it activates automatic numbering of paragraphs and the +\DescRef{\LabelBase.cmd.Clause} and \DescRef{\LabelBase.cmd.SubClause} +commands, which will be documented below, are given concrete form. + +The\textnote{Attention!} \DescRef{\LabelBase.env.contract} environment must +not be nested within itself. Within a document, however, you can use the +environment several times. The clauses within these environments are treated +as if they were within a single environment. As a result, ending the +environment really only temporarily interrupts it, and the old environment is +continued by the beginning of a new environment. However, you cannot end the +environment within a clause.% +\EndIndexGroup + + +\begin{Declaration} + \Option{contract} +\end{Declaration} +The whole document becomes a contract if you use this option while loading the +package with \DescRef{\LabelBase.cmd.usepackage}% +\important{\DescRef{\LabelBase.cmd.usepackage}} or as a global option with +\DescRef{\LabelBase.cmd.documentclass}% +\important{\DescRef{\LabelBase.cmd.documentclass}}. The document then behaves +exactly as if it contained one \DescRef{\LabelBase.env.contract} environment. + +Note\textnote{Attention!} that you cannot set the \Option{contract} option +with \DescRef{\LabelBase.cmd.KOMAoption} or +\DescRef{\LabelBase.cmd.KOMAoptions}. Thus you cannot switch the option off +again. Instead, you should use a \DescRef{\LabelBase.env.contract} environment +directly.% +\EndIndexGroup + + +\subsection{Clauses} +\label{sec:scrjura.clause} +\index{section|seealso{clause}} + +Clauses\footnote{% + In English, a ``clause'' in a legal document is a section, paragraph, or + phrase that relates to a particular point. Although it is common in English + to also use the terms ``article'' or ``section'' for what we here call a + ``clause'', we use the latter term throughout to avoid confusion with the + \Class{article} class and the \DescRef{maincls.cmd.section} and + \DescRef{maincls.cmd.paragraph} sectioning divisions of most document + classes.} in a legal sense are defined in \Package{scrjura} only within +contracts, that is inside the \DescRef{\LabelBase.env.contract} environment or +other environments declared with +\DescRef{\LabelBase.cmd.DeclareNewJuraEnvironment} (see +\autoref{sec:\LabelBase.newenv}, +\DescPageRef{\LabelBase.cmd.DeclareNewJuraEnvironment}). + +\begin{Declaration} + \Macro{Clause}\OParameter{options}% + \Macro{SubClause}\OParameter{options} +\end{Declaration} +These are the most important commands inside of a contract. Without using any +additional \PName{options}, \Macro{Clause} creates the heading of a clause, +which consists of the sign »\S«, followed by its number. In contrast, +\Macro{SubClause} creates the heading of a clause with the last number used by +\Macro{Clause} and adds a lower-case letter. \Macro{SubClause} is mainly +intended for cases where an act or a contract is amended and not only are +clauses changed or deleted but new clauses are inserted between existing ones +without completely changing the numbering. + +Both commands accept a a comma-separated list of \PName{options}. An overview +of the available properties is shown in \autoref{tab:scrjura.Clause.options}. +The most important of them will be discussed in more detail. + +\begin{table} + \caption{Available properties for the optional argument of \Macro{Clause} and + \Macro{SubClause}} + \label{tab:scrjura.Clause.options} + \begin{desctabular} + \entry{\Option{dummy}}{% + The heading will not be printed but is counted in the automatic + numbering.% + }% + \entry{\OptionVName{head}{running head}}{% + If running heads are active, this \PName{running head} is used instead of + the clause \PName{title}.% + }% + \entry{\Option{nohead}}{% + The running head stays unchanged.% + }% + \entry{\Option{notocentry}}{% + Does not make an entry into the table of contents.% + }% + \entry{\OptionVName{number}{number}}{% + Uses \PName{number} for the output of the clause number.% + }% + \entry{\OptionVName{preskip}{skip}}{% + Changes the vertical \PName{skip} before the clause heading.% + }% + \entry{\OptionVName{postskip}{skip}}{% + Changes the vertical \PName{skip} after the clause heading.% + }% + \entry{\OptionVName{title}{title}}{% + The clause \PName{title} will be printed in addition to the clause + number. This is also used as the default for the \PName{running head} + and the \PName{entry} in the table of contents.% + }% + \entry{\OptionVName{tocentry}{entry}}{% + Regardless of the clause \PName{title}, an \PName{entry} into the + table of contents will be made, if such entries are activated.% + }% + \end{desctabular} +\end{table} + +By default, a skip of two lines is inserted before the heading and a skip of +one line afterwards. You can change the size of these skips with the +\Option{preskip}\important[i]{\Option{preskip}, \Option{postskip}} and +\Option{postskip} options. The new values apply not only to the current +clause but from the current clause until the end of the current contract +environment. You can also make the appropriate settings in advance with +\begin{flushleft}\quad\small + \textbf{\Macro{setkeys}}\PParameter{contract}% + \PParameter{preskip=\PName{skip},\\ + \normalsize\quad\small + \hspace{11.5em}postskip=\PName{skip}} +\end{flushleft} +regardless of the specific clause and outside of a contract environment. You +can also set these options inside the preamble after loading +\Package{scrjura}, but you cannot set them while loading the package or by +using \DescRef{\LabelBase.cmd.KOMAoptions} or +\DescRef{\LabelBase.cmd.KOMAoption}. + +\BeginIndex{FontElement}{contract.Clause}\LabelFontElement{contract.Clause}% +\BeginIndex{FontElement}{Clause}\LabelFontElement{Clause}% +By default, clause headings use the font style +\Macro{sffamily}\Macro{bfseries}\Macro{large}. You can change this font style +at any time using the +\FontElement{contract.Clause}\important{\FontElement{contract.Clause}} element +with \DescRef{\LabelBase.cmd.setkomafont}% +\important[i]{\DescRef{\LabelBase.cmd.setkomafont}, +\DescRef{\LabelBase.cmd.addtokomafont}} and +\DescRef{\LabelBase.cmd.addtokomafont} (see \autoref{sec:maincls.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}). Inside the +\DescRef{\LabelBase.env.contract} environment, you can also use +\FontElement{Clause}\important{\FontElement{Clause}} instead of +\FontElement{contract.Clause}.% +\EndIndex{FontElement}{Clause}% +\EndIndex{FontElement}{contract.Clause} + +With the \Option{title}\important[i]{\Option{title}, \Option{head}, + \Option{tocentry}}, \Option{head}, and \Option{tocentry} options, you can +title a clause in addition to the number. You\textnote{Attention!} should put +the value of each options inside curly brackets. Otherwise, for example, +commas which are meant to be part of the value will be confused with the +delimiters between different options. Empty values for \Option{head} and +\Option{tocentry} cause empty entries. If you want to avoid an entry, use the +\Option{nohead}\important[i]{\Option{nohead}, \Option{notocentry}} and +\Option{notocentry} options. + +Instead of consecutive numbers, you can also set a clause number manually with +the \Option{number}\important{\Option{number}} option. However, this does not +affect the numbers of the subsequent clauses. Empty numbers are not possible. +Fragile commands inside \PName{number} have to be protected with +\Macro{protect}. You\textnote{Attention!} should use only numbers and letters +as a \Option{number}. + +With the \Option{dummy}\important{\Option{dummy}} option, you can suppress the +output of the whole heading of a clause. The automatic numbering, however, +will still count this clause. In this way, you can skip an automatically +numbered clause with\textnote{Example} +\begin{lstcode} + \Clause{dummy} +\end{lstcode} +in case the clause corresponding clause has been deleted in a later version of +a contract. + +Note\textnote{Attention!} that the \Option{dummy} option only accepts the +values \PValue{true} and \PValue{false}. All other values are usually ignored, +but can lead to an error message in the worst case scenario.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{Clauseformat}\Parameter{number} +\end{Declaration} +As already mentioned, clauses and subclauses are normally numbered. The number +is formatted with the help of the \Macro{Clauseformat} command, which expects +the number as the only argument. The default is the following: +\begin{lstcode} + \newcommand*{\Clauseformat}[1]{\S~#1} +\end{lstcode} +This produces the section mark, \Macro{S}\IndexCmd{S} (\S), followed by a +non-breaking space and the number. If you redefine this command, be sure it +remains expandable.% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{juratitlepagebreak}{simple switch} +\end{Declaration}% +Usually, page breaks are prohibited within heading of all kinds. However, some +lawyers require page breaks within clause headings. You can allow such a break +by using \Option{juratitlepagebreak}\important{\Option{juratitlepagebreak}}. +You can find the available values for \PName{simple switch} in +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}.% +\EndIndexGroup + +\begin{Declaration} + \OptionVName{clausemark}{value} +\end{Declaration}% +Since clauses are a subordinate structure with independent numbering, they do +not produce running heads by default. You can, however, create running heads +with various settings. You can find the available \PName{values} and their +meanings in \autoref{tab:scrjura.clausemark}.% +% +\begin{table} + \caption{Available values for the \Option{clausemark} option to activate + running heads}% + \label{tab:scrjura.clausemark}% + \begin{desctabular} + \entry{\PValue{both}}{% + Clauses generate left and right marks for running heads, if the document + provides automatic running heads.% + \IndexOption{clausemark~=\textKValue{both}}% + }% + \entry{\PValue{false}, \PValue{off}, \PValue{no}}{% + Clauses do not generate marks for running heads and therefore do not + change running heads.% + \IndexOption{clausemark~=\textKValue{false}}% + }% + \entry{\PValue{forceboth}}{% + Clauses use \DescRef{maincls.cmd.markboth} to generate left and right + marks for running heads even if the document does not provide automatic + running heads for the current page style.% + \IndexOption{clausemark~=\textKValue{forceboth}}% + }% + \entry{\PValue{forceright}}{% + Clauses use \DescRef{maincls.cmd.markright} to generate right marks for + running heads even if the document does not provide automatic running + heads for the current page style.% + \IndexOption{clausemark~=\textKValue{forceright}}% + }% + \entry{\PValue{right}}{% + Clauses generate right marks for running heads, if the document provides + automatic running heads.% + \IndexOption{clausemark~=\textKValue{right}}% + }% + \end{desctabular} +\end{table} +% +\EndIndexGroup + + +\subsection{Paragraphs} +\label{sec:scrjura.par} +\BeginIndexGroup +\BeginIndex{}{paragraph>numbering}% +Within clauses, \Package{scrjura} usually numbers paragraphs automatically. +With this, the paragraphs provide a powerful structuring element, similar to +\DescRef{maincls.cmd.paragraph} or \DescRef{maincls.cmd.subparagraph} in +normal documents. For this reason, contracts usually use a vertical skip +between paragraphs. The \Package{scrjura} package does not provide its own +mechanism for this. Instead, it uses the \DescRef{maincls.option.parskip}% +\IndexOption{parskip}\important{\DescRef{maincls.option.parskip}} option of +the \KOMAScript{} classes (see \autoref{sec:maincls.parmarkup}, +\DescPageRef{maincls.option.parskip}). + + +\begin{Declaration} + \OptionVName{parnumber}{value} +\end{Declaration} +The default numbering of paragraphs is \OptionValue{parnumber}{auto} and +\OptionValue{parnumber}{true}. Sometimes you may need to disable the automatic +numbering. You can do this with \OptionValue{parnumber}{false}% +\important{\OptionValue{parnumber}{false}}% +\IndexOption{parnumber~=\textKValue{false}}. In this case, only the sentence +numbering is reset. + +To implement this option, it has been necessary to hook into the +paragraph-building mechanism of \LaTeX. In some rare cases, this can have a +negative effect. If so, you can undo the change with +\OptionValue{parnumber}{manual}% +\important{\OptionValue{parnumber}{manual}}% +\IndexOption{parnumber~=\textKValue{manual}}. On the other hand, \LaTeX{} +itself sometimes undoes the change. In those cases you can activate it again +with \OptionValue{parnumber}{auto}% +\important{\OptionValue{parnumber}{auto}}% +\IndexOption{parnumber~=\textKValue{auto}}. + +Clauses that consist of a single paragraph do not automatically receive a +paragraph number. For this to work, there must not be two clauses with an +identical number in a document. However should you ever need such numbering, +you should switch to another contract environment (see +\DescRef{\LabelBase.cmd.DeclareNewJuraEnvironment}, +\autoref{sec:\LabelBase.newenv}, +\DescPageRef{\LabelBase.cmd.DeclareNewJuraEnvironment}). +Note\textnote{Attention!} that the number of paragraphs in a clause is not +available before the end of the clause. Therefore you need a least two +\LaTeX{} runs before the automatic paragraph numbering is correct.% +\EndIndexGroup + + +\begin{Declaration} + \Counter{par}% + \Macro{thepar}% + \Macro{parformat}% + \Macro{parformatseparation} +\end{Declaration}% +For numbering the paragraphs inside a clause we use the \Counter{par} counter. +The output of \Macro{thepar} will display an Arabic number, because the +default is \Macro{arabic}\PParameter{par}. \Macro{parformat} provides the +format, which is \Macro{thepar} in rounded brackets. When numbering a +paragraph manually, you should also use \Macro{parformat}. It makes sense to +call \Macro{parformat} with a subsequent \Macro{parformatseparation}, or at +least a \Macro{nobreakspace} or tilde. + +With\ChangedAt{v0.7}{\Package{scrjura}} automatic numbering, \Macro{parformat} +is followed by \Macro{parformatseparation}, which currently consists of +\Macro{nonbreakspace}, the non-breakable space. + +\BeginIndex{FontElement}{parnumber}\LabelFontElement{parnumber}% +The paragraph number is usually printed using the currently active font. +However, you can change this default for the \FontElement{parnumber} element +at any time with \DescRef{\LabelBase.cmd.setkomafont}% +\important[i]{\DescRef{\LabelBase.cmd.setkomafont}, +\DescRef{\LabelBase.cmd.addtokomafont}} and +\DescRef{\LabelBase.cmd.addtokomafont} (see +\autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}).% +\EndIndex{FontElement}{parnumber}% + +Note\textnote{Attention!} that \Package{scrjura} assumes internally that +\Macro{thepar} is an Arabic number. Therefore you should definitely not +redefine it!% +\EndIndexGroup + + +\begin{Declaration} + \Macro{withoutparnumber} +\end{Declaration} +If the paragraph number is not printed, \Package{scrjura} executes the +\Macro{withoutparnumber} command at the beginning of the new paragraph. The +initial definition of this command is empty. This means it is a kind of dummy +command that does nothing. It has been implemented because of a user request. +Most users can ignore this command.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ellipsispar}\OParameter{number}% + \Macro{parellipsis} +\end{Declaration} +Sometimes\ChangedAt{v0.7}{\Package{scrjura}}\,---\,particularly in comparative +commentaries\,---\,it is desirable to omit paragraphs but to mark the +omission. Those omitted paragraphs\Index{paragraph>omission} should be taken +into account by the paragraph counter. The package \Package{scrjura} provides +the command \Macro{ellipsispar} to do this. + +By default, \Macro{ellipsispar} omits precisely one paragraph. Using the +optional argument, you can omit multiple paragraphs. In any case, the output +shows just one unnumbered paragraph, which consists only of the ellipsis +defined by \Macro{parellipsis}. The automatic numbering of paragraphs takes +the \PName{number} of omitted paragraphs into account. +\begin{Example} + Suppose you are writing a comment on the German\footnote{Please remember, + this translation does not refer to an existing law but is only an example + of how you might realise such a commentary with \Package{scrjura}.} penal + code, but only on paragraph 3 of \S~2. Nevertheless, you'd like to indicate + the omission indirectly. You can do this with: +\begin{lstcode} + \documentclass[parskip=half]{scrartcl} + \usepackage{scrjura} + \begin{document} + \begin{contract} + \Clause{title={Temporal application},number=2} + \ellipsispar[2] + + If the law that applies at the time the criminal act is + committed is changed before the verdict, then the most + lenient law shall be applicable. + + \ellipsispar[3] + \end{contract} + \end{document} +\end{lstcode} + To see the result, just give it a try. +\end{Example} + +The ellipsis is by default \Macro{textellipsis}\IndexCmd{textellipsis}, if +such a command is defined. If not, \Macro{dots} is used. You can redefine +\Macro{parellipsis} at any time with \Macro{renewcommand}.% +\EndIndexGroup +% +\EndIndexGroup + + +\subsection{Sentences} +\label{sec:scrjura.sentence} + +\BeginIndexGroup% +\BeginIndex{}{sentence>number}% +Paragraphs in contracts consist of one or more sentences, some of which may +also be numbered. However, as automatic numbering is cumbersome and +error-prone, it has not yet been implemented in +\Package{scrjura}. Semi-automatic numbering, however, is supported. + +\begin{Declaration} + \Counter{sentence} + \Macro{thesentence} + \Macro{sentencenumberformat} + \Macro{Sentence} +\end{Declaration} +Manual numbering of sentences is done with the \Macro{Sentence} command. It +adds one to the \Counter{sentence} counter. By default, +\Macro{sentencenumberformat}\ChangedAt{v3.26}{\Package{scrjura}} prints +\Macro{thesentence} as an Arabic number in superscript. + +\BeginIndex{FontElement}{sentencenumber}\LabelFontElement{sentencenumber}% +The\ChangedAt{v3.26}{\Package{scrjura}} sentence number is usually printed +using the currently active font. However, you can change this default for the +\FontElement{parnumber} element at any time with +\DescRef{\LabelBase.cmd.setkomafont}% +\important[i]{\DescRef{\LabelBase.cmd.setkomafont}, + \DescRef{\LabelBase.cmd.addtokomafont}} and +\DescRef{\LabelBase.cmd.addtokomafont} (see +\autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}).% +\EndIndex{FontElement}{sentencenumber}% + +Using\textnote{Hint!} \Package{babel}\IndexPackage{babel} offers an easy way +to define a shorthand for \Macro{Sentence}:% +\phantomsection\label{sec:scrjura.shorthandexample}% +\begin{lstcode}[moretexcs={useshorthands,defineshorthand}] + \useshorthands{'} + \defineshorthand{'S}{\Sentence\ignorespaces} +\end{lstcode} +With this definition, any space after \lstinline|'S| will be ignored. You can +even use the dot as an abbreviation for a dot and a new sentence number: +\begin{lstcode}[moretexcs={useshorthands,defineshorthand}] + \defineshorthand{'.}{. \Sentence\ignorespaces} +\end{lstcode} +For details regarding \Macro{useshorthands} and \Macro{defineshorthands}, +please consult the manual of the \Package{babel} package (see +\cite{package:babel}). You can find an example of their application in +\autoref{sec:scrjura.example}, \autopageref{sec:scrjura.example}.% +\EndIndexGroup +% +\EndIndexGroup +% +\EndIndexGroup + + +\section{Cross-References} +\label{sec:scrjura.ref} + +The conventional mechanism to set cross-references using +\Macro{label}\IndexCmd{label}\important{\Macro{label}}, \Macro{ref}, and +\Macro{pageref} does not suffice for clauses, paragraphs, and sentences. +Therefore \Package{scrjura} provides additional commands. + +\begin{Declaration} + \Macro{ref}\Parameter{label}% + \Macro{refL}\Parameter{label}% + \Macro{refS}\Parameter{label}% + \Macro{refN}\Parameter{label} +\end{Declaration} +The commands \Macro{refL}, \Macro{refS}, and \Macro{refN} give a full +reference to clause, paragraph and sentence. \Macro{refL} is a long text, +\Macro{refS} a short text, and \Macro{refN} an abbreviated, numeric form. +\Macro{ref} defaults to \Macro{refL}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{refClause}\Parameter{label}% + \Macro{refClauseN}\Parameter{label} +\end{Declaration} +These commands reference a clause without displaying the paragraph or +sentences. \Macro{refClause} puts a section mark (\S) in front of the +reference, while \Macro{refClauseN} does not.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{refPar}\Parameter{label}% + \Macro{refParL}\Parameter{label}% + \Macro{refParS}\Parameter{label}% + \Macro{refParN}\OParameter{number format}\Parameter{label} +\end{Declaration} +You can reference just a paragraph with \Macro{refParL}, \Macro{refParS} and +\Macro{refParN}. The differences between the forms correspond to the +differences between \DescRef{\LabelBase.cmd.refL}, +\DescRef{\LabelBase.cmd.refN} and \DescRef{\LabelBase.cmd.refS}. A feature +worth noting is the optional argument of \Macro{refParN}. Usually the numeric +reference to a paragraph uses a Roman number. You can, however, specify a +different \PName{number format} in the optional argument. This option +primarily makes sense to use Arabic numbers. By default, \Macro{refPar} is +\Macro{refParL}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{refSentence}\Parameter{label}% + \Macro{refSentenceL}\Parameter{label}% + \Macro{refSentenceS}\Parameter{label}% + \Macro{refSentenceN}\Parameter{label} +\end{Declaration} +You can reference a sentence with \Macro{refSentenceL}, \Macro{refSentenceS}, +or \Macro{refSentenceN}. Again, there is a long text form, a short text form, +and a numerical form. By default, \Macro{refSentence} is +\Macro{refSentenceL}.% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{ref}{value} +\end{Declaration} +The results of \DescRef{\LabelBase.cmd.ref}, \DescRef{\LabelBase.cmd.refPar}, +and \DescRef{\LabelBase.cmd.refSentence} depend on the \PName{value} of the +\Option{ref} option. The defaults are \DescRef{\LabelBase.cmd.refL}, +\DescRef{\LabelBase.cmd.refParL} and \DescRef{\LabelBase.cmd.refSentenceL}. +You can find the available values and their meaning in +\autoref{tab:scrjura.ref}.% +% +\begin{table} +%\begin{desclist} +% \desccaption + \caption[{% + Available values for the \Option{ref} option to configure the + cross-reference format% + }]{% + Available values for the \Option{ref} option to configure the + cross-reference format of \DescRef{\LabelBase.cmd.ref}, + \DescRef{\LabelBase.cmd.refPar}, and \DescRef{\LabelBase.cmd.refSentence}% + \label{tab:scrjura.ref}% + }% + \begin{desctabular} + \entry{\PValue{long}}{% + A combination of \PValue{parlong} and \PValue{sentencelong}.% + \IndexOption{ref~=\textKValue{long}}% + }% + \entry{\PValue{numeric}}{% + A combination of \PValue{parnumeric} and \PValue{sentencenumeric}.% + \IndexOption{ref~=\textKValue{numeric}}% + }% + \entry{\PValue{clauseonly}, \PValue{onlyclause}, \PValue{ClauseOnly}, + \PValue{OnlyClause}}{% + A combination of \PValue{paroff} and \PValue{sentenceoff}. Note that + \DescRef{\LabelBase.cmd.refPar} and \DescRef{\LabelBase.cmd.refSentence} + produce empty results!% + \IndexOption{ref~=\textKValue{long}}% + }% + \entry{\PValue{parlong}, \PValue{longpar}, \PValue{ParL}}{% + Paragraphs are referenced in long textual form.% + \IndexOption{ref~=\textKValue{parlong}}% + }% + \entry{\PValue{parnumeric}, \PValue{numericpar}, \PValue{ParN}}{% + Paragraphs are referenced in simple numerical form.% + \IndexOption{ref~=\textKValue{parnumeric}}% + }% + \entry{\PValue{paroff}, \PValue{nopar}}{% + Paragraphs have no reference. Note that \DescRef{\LabelBase.cmd.refPar} + produces an empty result!% + \IndexOption{ref~=\textKValue{paroff}}% + }% + \entry{\PValue{parshort}, \PValue{shortpar}, \PValue{ParS}}{% + Paragraphs are referenced in short textual form.% + \IndexOption{ref~=\textKValue{parshort}}% + }% + \entry{\PValue{sentencelong}, \PValue{longsentence}, \PValue{SentenceL}}{% + Sentences are referenced in long textual form.% + \IndexOption{ref~=\textKValue{parlong}}% + }% + \entry{\PValue{sentencenumeric}, \PValue{numericsentence}, + \PValue{SentenceN}}{% + Sentences are referenced in simple numeric form.% + \IndexOption{ref~=\textKValue{sentencenumeric}}% + }% + \entry{\PValue{sentenceoff}, \PValue{nosentence}}{% + Sentences have no reference. Note that + \DescRef{\LabelBase.cmd.refSentence} produces an empty result!% + \IndexOption{ref~=\textKValue{sentenceoff}}% + }% + \entry{\PValue{sentenceshort}, \PValue{shortsentence}, + \PValue{SentenceS}}{% + Sentences are referenced in short textual form.% + \IndexOption{ref~=\textKValue{sentenceshort}}% + }% + \entry{\PValue{short}}{% + A combination of \PValue{parshort} and \PValue{sentenceshort}.% + \IndexOption{ref~=\textKValue{value}}% + }% +\end{desctabular} +\end{table} + +\begin{Example} + Suppose you always want to reference paragraphs in the form ``paragraph 1 + in clause 1''. As there is no predefined command for this, you have + to create your own definition from the available options. You can achieve + this easily with:% +\begin{lstcode} + \newcommand*{\refParM}[1]{% + paragraph~\refParN[arabic]{#1} + in clause~\refClauseN{#1}% + } +\end{lstcode} + This new command can be used in the same way as + \DescRef{\LabelBase.cmd.refParL}.% +\end{Example}% + +You can find examples of results of the basic commands in +\autoref{tab:scrjura.refexamples}.% +% +\begin{table} + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% + \begin{captionbeside}{Example outputs of the \Option{ref}-independent + cross-reference commands}[l] + \begin{tabular}[t]{ll} + \toprule + Command & Example output \\ + \midrule + \DescRef{\LabelBase.cmd.refL}\Parameter{label} & § 1 paragraph 1 sentence 1 \\ + \DescRef{\LabelBase.cmd.refS}\Parameter{label} & § 1 par. 1 sent. 1 \\ + \DescRef{\LabelBase.cmd.refN}\Parameter{label} & § 1 I 1. \\ + \DescRef{\LabelBase.cmd.refClause}\Parameter{label} & § 1 \\ + \DescRef{\LabelBase.cmd.refClauseN}\Parameter{label} & 1 \\ + \DescRef{\LabelBase.cmd.refParL}\Parameter{label} & paragraph 1 \\ + \DescRef{\LabelBase.cmd.refParS}\Parameter{label} & par. 1 \\ + \DescRef{\LabelBase.cmd.refParN}\Parameter{label} & I \\ + \DescRef{\LabelBase.cmd.refParN}\POParameter{arabic}\Parameter{label} & 1 \\ + \DescRef{\LabelBase.cmd.refParN}\POParameter{roman}\Parameter{label} & i \\ + \DescRef{\LabelBase.cmd.refSentenceL}\Parameter{label} & sentence 1 \\ + \DescRef{\LabelBase.cmd.refSentenceS}\Parameter{label} & sent. 1 \\ + \DescRef{\LabelBase.cmd.refSentenceN}\Parameter{label} & 1. \\ + \bottomrule + \end{tabular} + \end{captionbeside} + \label{tab:scrjura.refexamples} +\end{table} +\EndIndexGroup + + +\section{Additional Environments} +\label{sec:scrjura.newenv} + +Some users do not use \Package{scrjura} to draft contracts or commentaries on +individual laws but to examine different types of laws, which may not +necessarily use the section prefix (\S) before the title of each clause but +perhaps something like ``Art.'' or ``IAS'', and so forth. An independent +counter is also required for each of these different clause types. + +\begin{Declaration} + \Macro{DeclareNewJuraEnvironment}\Parameter{name}\OParameter{options}% + \Parameter{start commands}\Parameter{end commands} +\end{Declaration} +You\ChangedAt{v0.9}{\Package{scrjura}} can use this command to define new and +independent environments for contracts or other legal texts. The argument +\PName{name} is the name of the new environment, of course. The \PName{start +commands} are commands which will be executed at the beginning of the +environment, as if they were added directly after +\Macro{begin}\Parameter{name}. Correspondingly \PName{end commands} will be +executed at the end of the environment, as if added directly before +\Macro{end}\Parameter{name}. Without any \PName{options} the new environment +behaves like the \DescRef{\LabelBase.env.contract} environment, but with its +own counters. It is possible to set \PName{options} in a comma-separated list. +See \autoref{tab:\LabelBase.DeclareNewJuraEnvironment} for the currently +supported \PName{options}. + +\begin{desclist} + \desccaption{Options provided by \Macro{DeclareNewJuraEnvironment} for new + contract environments\label{tab:\LabelBase.DeclareNewJuraEnvironment}}% + {Options of \Macro{DeclareNewJuraEnvironment} (\emph{continued})}% + \entry{\OptionVName{Clause}{command}}{% + Defines the \PName{command} to which the \DescRef{\LabelBase.cmd.Clause} + command is mapped within the environment. This \PName{command}, like the + one documented for \DescRef{\LabelBase.env.contract}, expects exactly one + argument. To use it correctly requires advanced knowledge of the + \Package{scrjura}'s internal functioning. Furthermore, the requirements + for the \PName{command} may change in future versions. Therefore it is + recommended not to use this option!% + }% + \entry{\OptionVName{ClauseFont}{commands}}{% + \leavevmode\BeginIndex{FontElement}{\PName{Name}.Clause}% + \LabelFontElement{\PName{Name}.Clause}% + If this option is used, a new + \FontElement{\PName{Name}.Clause}\IndexFontElement{\PName{Name}.Clause} + element is defined using + \DescRef{maincls-experts.cmd.newkomafont}\IndexCmd{newkomafont}, with the + \PName{commands} used as its default setting. If the element was + previously defined as an alias (see + \DescRef{maincls-experts.cmd.aliaskomafont} in + \autoref{sec:maincls-experts.experts}, + \DescPageRef{maincls-experts.cmd.aliaskomafont}), it will become an + independent element instead. If it has already been defined as an + independent element, \DescRef{\LabelBase.cmd.setkomafont} is used to set + the \PName{commands} a new font settings. Please note the limitations for + font settings in \autoref{sec:\LabelBase.textmarkup}, + \DescPageRef{\LabelBase.cmd.setkomafont}. + \EndIndex{FontElement}{\PName{Name}.Clause}% + }% + \entry{\OptionVName{SubClause}{command}}{% + Defines the \PName{command} to which the + \DescRef{\LabelBase.cmd.SubClause} command is mapped within the + environment. This \PName{command}, like the one documented for + \DescRef{\LabelBase.env.contract}, expects exactly one argument. To use it + correctly requires advanced knowledge of the \Package{scrjura}'s internal + functioning. Furthermore, the requirements for the \PName{command} may + change in future versions. Therefore it is recommended not to use this + option!% + }% + \entry{\OptionVName{Sentence}{command}}{% + Defines the \PName{command} to which the + \DescRef{\LabelBase.cmd.Sentence} is mapped within the environment. This + \PName{command} must not have an argument. Typically it should add one to + the \Counter{sentence}\IndexCounter{sentence} (using + \Macro{refstepcounter}\IndexCmd{refstepcounter}) counter and display it + appropriately. It is particularly important to avoid adding unwanted + spaces.% + }% + \entry{\OptionVName{ClauseNumberFormat}{command}}{% + Formats the numbers of clauses within the environment. The \PName{command} + should expect exactly one argument: the number of the clause. If the + \PName{command} implements a series of commands and the number is the last + argument of a that series, you can directly use the series of commands as + \PName{command}.% + } +\end{desclist} +\begin{Example} + To define the environment for articles we mentioned in the preface of this + section, it is sufficient to write: +\begin{lstcode} + \DeclareNewJuraEnvironment{Article}[ClauseNumberFormat=Art.]{}{} +\end{lstcode} + If we are using a \KOMAScript{} class and want to separate the paragraphs in + this environment with space instead of using paragraph indentation, we can + use: +\begin{lstcode} + \DeclareNewJuraEnvironment{Article}[ClauseNumberFormat=Art.~] + {\KOMAoptions{parskip}}{} +\end{lstcode} + In cross-references, ``Art.'' will of course be used instead of ``\S''.% + + The new environment is used like \DescRef{\LabelBase.env.contract}: +\begin{lstcode} + \begin{Article} + \Clause + Human dignity is inviolable. To respect and protect people is a + duty of all state authority. + \end{Article} +\end{lstcode} +\end{Example}% +\EndIndexGroup + + +\section{Support for Different Languages} +\label{sec:scrjura.babel} + +The \Package{scrjura} package has been developed in cooperation with a German +lawyer. Therefore it initially supported only the languages \PValue{german}, +\PValue{ngerman}, \PValue{austrian}, and \PValue{naustrian}. Nevertheless, it +has been designed to support common language packages like +\Package{babel}\important{\Package{babel}}\IndexPackage{babel}. Users can +easily make changes by using \DescRef{scrbase.cmd.providecaptionname} (see +\autoref{sec:scrbase.languageSupport}, +\DescPageRef{scrbase.cmd.providecaptionname}). If you have definitive +information about the correct legal terms and conventions of a language, +please contact the \KOMAScript{} author. Support for English has been added in +this way, and so \Package{scrjura} now also provides terms for the languages +\PValue{english}, \PValue{american}, \PValue{british}, \PValue{canadian}, +\PValue{USenglish}, and \PValue{UKenglish}. + +\begin{Declaration} + \Macro{parname}% + \Macro{parshortname}% + \Macro{sentencename}% + \Macro{sentenceshortname} +\end{Declaration} +These are the language-dependent terms used by \Package{scrjura}. The meaning +of the terms and their English defaults are shown in +\autoref{tab:scrjura.captionnames}. The package itself defines them by using +\DescRef{scrbase.cmd.providecaptionname} inside +\Macro{begin}\PParameter{document} only if other requirements have not already +been met. If you use \Package{scrjura} with an unsupported language, the +package will throw an error.% +% +\begin{table} + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% + \begin{captionbeside} + [{% + Meanings and English defaults of language-dependent terms% + }]{% + Meanings and English defaults of language-dependent terms, if not + already defined% + } [l] + \begin{tabular}[t]{lll} + \toprule + Command & Meaning & Default \\ + \midrule + \Macro{parname} & long form ``paragraph'' & paragraph \\ + \Macro{parshortname} & short form ``paragraph'' & par. \\ + \Macro{sentencename} & long form ``sentence'' & sentence \\ + \Macro{sentenceshortname} & short form ``sentence'' & sent. \\ + \bottomrule + \end{tabular} + \end{captionbeside} + \label{tab:scrjura.captionnames} +\end{table} +% +\EndIndexGroup + + +\section{A Detailed Example} +\label{sec:scrjura.example} + +You may remember the letter from \autoref{cha:scrlttr2}, in which a club +member wanted to remind the board about an overdue meeting that was prescribed +by the club's by-laws. Such club by-laws are a kind of contract, and you can +create them using \Package{scrjura}. + +\lstinputcode[{xleftmargin=2em,% + linerange=1-2}]{scrjuraexample.tex}% +We use class \Class{scrartcl}. Because paragraph distance instead of paragraph +indentation is usual in club by-laws, we load the class with option +\OptionValueRef{maincls}{parskip}{half} (see \autoref{sec:maincls.parmarkup}, +\DescPageRef{maincls.option.parskip}). + +\lstinputcode[{xleftmargin=2em,% + linerange=4-4}]{scrjuraexample.tex}% +The club rules are in British English. Therefore we load the \Package{babel} +package with the \Option{british} option too. + +\lstinputcode[{xleftmargin=2em,% + linerange={6-7,9-9}}]{scrjuraexample.tex}% +We make some default font settings and load the \Package{textcomp} package +because it provides an improved section mark (\S) and\,---\,something that may +be useful in other circumstances\,---\,a usable Euro symbol for some fonts. + +%\lstinputcode[{moretexcs=SelectInputMappings,xleftmargin=2em,% +% linerange=11-15}]{scrjuraexample.tex}% +Although it is not relevant for English, if we were writing an another +language, we would want to input non-ASCII characters directly. To do so, we +could let \LaTeX{} detect the input encoding with the \Package{selinput} or +set it with the \Package{inputenc} packages. + +\lstinputcode[{xleftmargin=2em,% + linerange=11-11}]{scrjuraexample.tex}% +Later in the document, we want lists numbered not with Arabic numbers but with +lower-case letters. We can do this easily with the \Package{enumerate} package. + +\lstinputcode[{moretexcs={useshorthands,defineshorthand},% + xleftmargin=2em,% + linerange=13-21}]{scrjuraexample.tex}% +Now it is time for \Package{scrjura}. The +\OptionValueRef{\LabelBase}{clausemark}{forceboth} option forces clauses to +create left and right marks for the running head. On the other hand, we do not +want \DescRef{maincls.cmd.section} to change the marks for the running head. +Therefore we use the \PageStyle{myheadings} page style. This page style +generally does not provide automatic running heads. + +Later, we also want a table of contents with the clauses. This can be achieved +with the \DescRef{\LabelBase.option.juratotoc} option. Doing so we will see +that the default width for these numbers is insufficient for the clause +numbers in the table of contents. With +\OptionValueRef{\LabelBase}{juratocnumberwidth}{2.5em}, we reserve more space. + +The definition of shorthands has already been explained in +\autoref{sec:scrjura.shorthandexample}. In this example we do the same thing +to simplify the input. + +\lstinputcode[{xleftmargin=2em,% + linerange=23-23}]{scrjuraexample.tex}% +It is time to begin the actual document. + +\lstinputcode[{xleftmargin=2em,% + linerange=25-29}]{scrjuraexample.tex}% +Like other documents, the by-laws have a title. We created it with the usual +\KOMAScript{} commands (see \autoref{sec:maincls.titlepage}, starting on +\autopageref{sec:maincls.titlepage}). + +\lstinputcode[{xleftmargin=2em,% + linerange=31-31}]{scrjuraexample.tex}% +As already mentioned, we want to create a table of contents. + +\lstinputcode[{xleftmargin=2em,% + linerange=33-37}]{scrjuraexample.tex}% +Preambles are not unusual in club by-laws. Here we use +\DescRef{maincls.cmd.addsec} to create one because we want it to have an entry +in the table of contents. + +\lstinputcode[{xleftmargin=2em,% + linerange=39-39}]{scrjuraexample.tex}% +Here we use a small trick. The articles of the club by-laws should be numbered +with upper-case letters instead of Arabic numbers, just as +the appendix sections of an article using \Class{scrartcl} are. + +\lstinputcode[{xleftmargin=2em,% + linerange=41-43}]{scrjuraexample.tex}% +We begin the contract with the first article. + +\lstinputcode[{xleftmargin=2em,% + linerange=44-54}]{scrjuraexample.tex}% +The first clause has a number and a title. We will do the same with all +following clauses. + +The first paragraph of the clause contains nothing unusual. Because it is not +the only paragraph, every paragraph will be automatically preceded by a +paragraph number. Note that the numbering the first paragraph requires at +least two \LaTeX{} runs. Since this is the case for the table of contents as +well, this does not create any additional problems. + +In the second paragraph we have two sentences. Here we can see the shorthands +\texttt{'S} and \texttt{'.} in action. The first one only generates the +sentence number. The second one generates not only the full stop but also the +sentence number. With this, both sentences are numbered. + +\lstinputcode[{xleftmargin=2em,% + linerange=55-70}]{scrjuraexample.tex}% +The second clause: again this contains several paragraphs, some of which +include several sentences. The second paragraph also has a numbered list. In +the last paragraph, we set a label, because we want to reference it later. + +\lstinputcode[{xleftmargin=2em,% + linerange=72-78}]{scrjuraexample.tex}% +The third clause contains something special: a cross-reference. Here we use +the long form with clause, paragraph, and sentence. If we decided later that +sentences should not be included in the reference, we could use the +\OptionValueRef{\LabelBase}{ref}{nosentence} option to set this globally. + +\lstinputcode[{xleftmargin=2em,% + linerange=80-81}]{scrjuraexample.tex}% +Here we have a special kind of clause. In earlier versions of the club by-laws, +this was a real clause, but it was later removed. However, the +numbering of the following clauses should not be changed by removing this +one. Therefore the \DescRef{\LabelBase.cmd.Clause} statement has not been +removed but supplemented by option \Option{dummy}. With this, we also can set +a label even though the clause will not be printed. + +\lstinputcode[{xleftmargin=2em,% + linerange=82-86}]{scrjuraexample.tex}% +Another article begins. To avoid problems with the paragraph numbering, we +interrupt the \DescRef{\LabelBase.env.contract} environment. + +\lstinputcode[{xleftmargin=2em,% + linerange=87-87}]{scrjuraexample.tex}% +The first clause of the next article also has been deleted. + +\lstinputcode[{xleftmargin=2em,% + linerange=89-98}]{scrjuraexample.tex}% +Here we have a real clause again. We cross-reference one of the deleted +clauses and also set a label. + +\lstinputcode[{xleftmargin=2em,% + linerange=100-104}]{scrjuraexample.tex}% +Once more, this is a special kind of clause. This time we have not removed a +clause but added one without renumbering the following clauses. To do so, +we use \DescRef{\LabelBase.cmd.SubClause}. Therefore the clause number is the +same like the previous one but with an appended ``a''. + +\lstinputcode[{xleftmargin=2em,% + linerange=106-126}]{scrjuraexample.tex}% +The other clauses of this article are very usual. You already know all the +features used for them. + +\lstinputcode[{xleftmargin=2em,% + linerange=128-141}]{scrjuraexample.tex}% +There follows another article no special features. + +\lstinputcode[{xleftmargin=2em,% + linerange=143-143}]{scrjuraexample.tex}% +Then the \LaTeX{} document ends. You can see first three pages in +\autoref{fig:scrjura.example}.% +% +\begin{figure} + \setcapindent{0pt}% + \iffree{% + {\hfill + \frame{\includegraphics[page=1,width=.482\textwidth,% + height=.49\textheight,keepaspectratio]{scrjuraexample}}\enskip + \frame{\includegraphics[page=2,width=.482\textwidth,% + height=.49\textheight,keepaspectratio]{scrjuraexample}}\par + \smallskip} + \begin{captionbeside}[{% + Example: First three pages of the example club by-laws of + \protect\autoref{sec:scrjura.example}% + }]{% + First three pages of the example club by-laws of + \protect\autoref{sec:scrjura.example}% + }% + [l] + \frame{\includegraphics[page=3,width=.482\textwidth,% + height=.49\textheight,keepaspectratio]{scrjuraexample}}\enskip + \end{captionbeside} + }{% + {\hfill + \frame{\includegraphics[page=1,width=.482\textwidth]{scrjuraexample}}% + \enskip + \frame{\includegraphics[page=2,width=.482\textwidth]{scrjuraexample}}\par + \smallskip} + \begin{captionbeside}[{% + Example: First three pages of the example club by-laws of + \protect\autoref{sec:scrjura.example}% + }]{% + First three pages of the example club by-laws of + \protect\autoref{sec:scrjura.example}% + }% + [l] + \frame{\includegraphics[page=3,width=.482\textwidth]{scrjuraexample}}% + \enskip + \end{captionbeside} + }% + \label{fig:scrjura.example} +\end{figure} + +\section{State of Development} +\label{sec:scrjura.draft} + +Since \KOMAScript~3.24, the \Package{scrjura} package has shared the version +number of the classes and other important packages of \KOMAScript. +Nevertheless, you should note that so far, the interaction of the +\DescRef{\LabelBase.env.contract} environment with the many different settings +possible with other \LaTeX{} environments, packages, or classes has not been +tested. The main reason for this is that \Package{scrjura} is very specialised +and far beyond the author's ordinary practice. So the author mostly relies on +detailed user feedback.% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: iso-latin-1 +%%% ispell-local-dictionary: "en_GB" +%%% TeX-PDF-mode: t +%%% TeX-master: "guide.tex" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrjuraexample.tex b/macros/latex/contrib/koma-script/source-doc/english/scrjuraexample.tex new file mode 100644 index 0000000000..013d1b60bc --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrjuraexample.tex @@ -0,0 +1,143 @@ +\documentclass[fontsize=12pt,pagesize,parskip=half] + {scrartcl} + +\usepackage[british]{babel} + +\usepackage[T1]{fontenc} +\usepackage{lmodern} +\usepackage{charter,helvet} +\usepackage{textcomp} + +\usepackage{enumerate} + +\usepackage[clausemark=forceboth, + juratotoc, + juratocnumberwidth=2.5em] + {scrjura} +\useshorthands{'} +\defineshorthand{'S}{\Sentence\ignorespaces} +\defineshorthand{'.}{. \Sentence\ignorespaces} + +\pagestyle{myheadings} + +\begin{document} + +\subject{By-Laws} +\title{CfCH} +\subtitle{Club for Club Hoppers} +\date{11.\,11.\,2011} +\maketitle + +\tableofcontents + +\addsec{Preamble} + +The club landscape in England is diverse. But we have +unfortunately been forced to conclude that it often +suffers seriously when dealing with seriousness. + +\appendix + +\section{Overview} + +\begin{contract} +\Clause{title={Name, Legal Form, Headquarters}} + +The name of this club shall be the ``Club for Club +Hoppers'' and is not registered in any club register. + +'S The club is a non-economic, useless club'. It has no +headquarters because its members heads are in their +hindquarters. + +The fiscal year is from March 31st through April 1st. + +\Clause{title={Purpose of the Club}} + +'S The club is pointless but not useless'. Rather, +it should put the serious handling of seriousness on a +sound footing. + +For this purpose, the club members can +\begin{enumerate}[\qquad a)] +\item pick their noses, +\item crack nuts, +\item such their thumbs. +\end{enumerate} + +The club is selfish and stands by it. + +The club has no financial means.\label{a:mittel} + +\Clause{title={Club Officers}} + +The club officers hold honorary positions. + +'S If the club had resources (see \ref{a:mittel}), it +could afford a full-time manager'. Without the necessary +funds, this is not possible. + +\Clause{title={Club Hopper},dummy} +\label{p.maier} +\end{contract} + +\section{Membership} + +\begin{contract} +\Clause{title={Types of Members},dummy} + +\Clause{title={Becoming a Member}} + +Everyone can purchase a membership from one of the +associations listed in \refClause{p.maier}.\label{a.preis} + +'S To become a member, an informal application is +required'. This application should be submitted in green +ink on pink paper. + +Membership applications cannot be rejected. + +\SubClause{title={Amendment to the Previous Clause}} + +'S With the repeal of \refClause{p.maier}, +\ref{a.preis} has become impractical'. In its place, +memberships can be inherited. + +\Clause{title={Termination of Membership}} + +'S Membership ends with one's life'. For non-living +members, membership does not end. + +\Clause{title={General Meeting}} + +A general meeting shall take place twice per year. + +The interval between two general meetings shall be +no more than 6~months, 1~week, and 2~days. + +The invitation to the next general meeting shall be sent +no earlier than 6~months from the previous general +meeting. + +\SubClause{title={Amendment to the General Meeting}} + +The general meeting may be held at the earliest 2~weeks after +the invitation is received. +\end{contract} + +\section{Validity} + +\begin{contract} +\Clause{title={Effective Date}} + +These articles will enter into force on 11.\,11.\,2011 at +11:11~am. + +'S If any provision of these by-laws is in conflict with +any other, the by-laws will be repealed on +11.\,11.\,2011 at 11:11~am and 11~seconds'. The club is +considered to be dissolved in this case. + +\end{contract} + +\end{document} diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrlayer-notecolumn-example.tex b/macros/latex/contrib/koma-script/source-doc/english/scrlayer-notecolumn-example.tex new file mode 100644 index 0000000000..164c646e1f --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrlayer-notecolumn-example.tex @@ -0,0 +1,121 @@ +% ====================================================================== +% scrlayer-notecolumn-example.tex +% Copyright (c) Markus Kohm, 2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrlayer-notecolumn-example.tex +% Copyright (c) Markus Kohm, 2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Example file for the chapter about scrlayer-notecolumn +% of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Beispieldatei für das Kapitel über scrlayer-notecolumn +% in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ +\documentclass{scrartcl} +\usepackage{lmodern} +\usepackage{xcolor} + +\usepackage{scrjura} +\setkomafont{contract.Clause}{\bfseries} +\setkeys{contract}{preskip=-\dp\strutbox} + +\usepackage{scrlayer-scrpage} +\usepackage{scrlayer-notecolumn} + +\newlength{\paragraphscolwidth} +\AfterCalculatingTypearea{% + \setlength{\paragraphscolwidth}{.333\textwidth}% + \addtolength{\paragraphscolwidth}{-\marginparsep}% +} +\recalctypearea +\DeclareNewNoteColumn[% + position=\oddsidemargin+1in + +.667\textwidth + +\marginparsep, + width=\paragraphscolwidth, + font=\raggedright\footnotesize + \color{blue} +]{paragraphs} + +\begin{document} + +\title{Commentary on the SCRACH} +\author{Professor R. O. Tenase} +\date{11/11/2011} +\maketitle +\tableofcontents + +\section{Preamble} +The SCRACH is without doubt the most important law on the manners of humour +that has been passed in the last thousand years. The first reading took place +on 11/11/1111 in the Supreme Manic Fun Congress, but the law was rejected by +the Vizier of Fun. Only after the ludicrous, Manic Fun monarchy was +transformed into a representative, witty monarchy by W. Itzbold, on 9/9/1999 +was the way finally clear for this law. + +\section{Analysis} + +\begin{addmargin}[0pt]{.333\textwidth} + \makenote[paragraphs]{% + \protect\begin{contract} + \protect\Clause{title={No Joke without an Audience}} + A joke can only be funny if is has an audience. + \protect\end{contract} + } + This is one of the most central statements of the law. It is so fundamental + that it is quite appropriate to bow to the wisdom of the authors. + + \syncwithnotecolumn[paragraphs]\bigskip + \makenote[paragraphs]{% + \protect\begin{contract} + \protect\Clause{title={Humor of a Culture}} + \setcounter{par}{0}The humour of a joke can be determined by the + cultural environment in which it is told. + + The humour of a joke can be determined by the cultural environment in + which it acts. + \protect\end{contract} + } + The cultural component of a joke is, in fact, not negligible. Although the + political correctness of using the cultural environment can easily be + disputed, nonetheless the accuracy of such comedy in the appropriate + environment is striking. On the other hand, a supposed joke in the wrong + cultural environment can also be a real danger for the joke teller. +\end{addmargin} + +\end{document} diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrlayer-notecolumn.tex b/macros/latex/contrib/koma-script/source-doc/english/scrlayer-notecolumn.tex new file mode 100644 index 0000000000..47cc29a8aa --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrlayer-notecolumn.tex @@ -0,0 +1,702 @@ +% ====================================================================== +% scrlayer-notecolumn.tex +% Copyright (c) Markus Kohm, 2013-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrlayer-notecolumn.tex +% Copyright (c) Markus Kohm, 2013-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrlayer-notecolumn of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber scrlayer-notecolumn in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrlayer-notecolumn.tex} + [$Date: 2018-02-05 01:50:56 -0800 (Mon, 05 Feb 2018) $ + KOMA-Script guide (chapter:scrlayer-notecolumn)] + +\translator{Markus Kohm\and Arndt Schubert\and Karl Hagen} + +% Date of the translated German file: 2018-02-05 + +\chapter{Note Columns with \Package{scrlayer-notecolumn}} +\labelbase{scrlayer-notecolumn} + +\BeginIndexGroup +\BeginIndex{Package}{scrlayer-notecolumn}% +Through version~3.11b, \KOMAScript{} supported note columns only in the form +of marginal notes that get their contents from \DescRef{maincls.cmd.marginpar} +and \DescRef{maincls.cmd.marginline} (see \autoref{sec:maincls.marginNotes}, +\DescPageRef{maincls.cmd.marginline}). This kind of note column has several +disadvantages: +\begin{itemize} +\item Marginal notes must be set completely on a single page. Page + breaks\textnote{page break} inside marginal notes are not possible. This + sometimes causes the marginal notes to protrude into the lower margin. +\item Marginal notes near page breaks sometimes float to the next page and + then, in the case of two-sided printing, cause alternate marginal columns to + appear in the wrong margin.\textnote{assignment to the correct margin}. This + problem can be solved with the additional package + \Package{mparhack}\IndexPackage{mparhack} or by using \Macro{marginnote} + from the \Package{marginnote}\IndexPackage{marginnote} package (see + \cite{package:marginnote}). +\item Marginal notes inside floating environments\textnote{floating + environments} or footnotes\textnote{footnotes} are not possible. This + problem can also be solved with \Macro{marginnote} of the + \Package{marginnote}\IndexPackage{marginnote} package. +\item There is only one marginal note column\textnote{several note columns}, + or at most two if you use \Macro{reversemarginpar} and + \Macro{normalmarginpar}. Note that \Macro{reversemarginpar} is of less + utility with two-sided documents. +\end{itemize} +Using \Package{marginnote}\IndexPackage{marginnote} leads to one more problem. +Because the package does not have any collision detection, marginal notes that +are set near to each other can partially or totally overlap. Moreover, +depending on the settings used, \Macro{marginnote} sometimes changes the +baseline distance of the normal text. + +The \Package{scrlayer-notecolumn} package should solve all these problems. To +do so, it relies on the basic functionality of +\hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer}% +\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}}. However, using this +package has a drawback:\textnote{Attention!} you can only output notes on +pages that use a page style based on +\hyperref[cha:scrlayer]{\Package{scrlayer}}. This disadvantage, however, can +easily be resolved, or even turned into an advantage, with the help of +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}}% +\IndexPackage{scrlayer-scrpage}. + +\section{Note about the State of Development} +\seclabel{draft} + +This package was originally developed as a so-called \emph{proof of + concept}\textnote{proof of concept} to demonstrate the potential of +\hyperref[cha:scrlayer]{\Package{scrlayer}}% +\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}}. Although it is still +in its early stages of development, most of its stability is less a question +of \Package{scrlayer-notecolumn} than of +\hyperref[cha:scrlayer]{\Package{scrlayer}}. Nevertheless, you can assume that +there are still bugs in \Package{scrlayer-notecolumn}. Please report such bugs +whenever you find them. Some of the package's shortcomings are caused by the +attempt to minimise complexity. For example, although note columns can break +across several pages, there is no new paragraph break. \TeX{} itself does not +provide this. + +Because the package is rather experimental\textnote{experimental}, its +instructions are found here in the second part of \iffree{the \KOMAScript{} +manual}{this book}. Accordingly, it is primarily directed towards experienced +users. If you are a beginner or a user on the way to become an +expert\textnote{for experts}, some of the following explanations may be +unclear or even incomprehensible. +\iffree{Please understand that I want to keep the effort spent on the manual + to something halfway bearable when it comes to experimental packages.}{% + However, this should be enough to solve simple tasks with + \Package{scrlayer-notecolumn}. At the same time, developers will hopefully + find useful stimulus for their own ideas.} + +\iffalse% Umbruchoptimierung +Note also\textnote{Attention!} that the author of \KOMAScript{} does not +guarantee the further development of this package and offers only limited +support for it. This is the nature of a package written solely for the +purposes of demonstration.% +\fi + +\LoadCommonFile{options}% \section{Early or late Selection of Options} + +\LoadCommonFile{textmarkup}% \section{Text Markup} + +\section{Declaring New Note Columns} +\seclabel{declaration} + +Loading the package automatically declares a note column named +\PValue{marginpar}. As the name implies, this note column is placed in the +area of the normal marginal column used by \DescRef{maincls.cmd.marginpar} and +\DescRef{maincls.cmd.marginline}. The \Macro{reversemarginpar} and +\Macro{normalmarginpar} settings are also taken into account, but only for all +the notes on a page instead of note by note. The relevant setting is the one +that applies at the end of the page, namely during the output of the note +column. If you want to have notes in both the left and right margin of the +same page, you should define a second note column. + +The default settings for all newly declared note columns are the same as the +defaults for \PValue{marginpar}. % +\iftrue% Umbruchoptimierung +But you can easily change them during their initialisation.% +\fi + +Note\textnote{Attention!} that note columns can be output only on pages that +use a page style based on the +\hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer}% +\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}} package. The +\Package{scrlayer-notecolumn} package automatically loads +\hyperref[cha:scrlayer]{\Package{scrlayer}}, which by default provides only +\PageStyle{empty}\IndexPagestyle{empty} page style. If you need additional +page styles, \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} is +recommended. + +\begin{Declaration} + \Macro{DeclareNoteColumn}% + \OParameter{option~list}\Parameter{note~column~name}% + \Macro{DeclareNewNoteColumn}% + \OParameter{option~list}\Parameter{note~column~name}% + \Macro{ProvideNoteColumn}% + \OParameter{option~list}\Parameter{note~column~name}% + \Macro{RedeclareNoteColumn}% + \OParameter{option~list}\Parameter{note~column~name}% +\end{Declaration} +You can use these commands to create note columns. \Macro{DeclareNoteColumn} +creates the note column regardless of whether it already exists. +\Macro{DeclareNewNoteColumn} throws an error if the \PName{note column name} +has already been used for another note column. \Macro{ProvideNoteColumn} +simply does nothing in that case. You can use \Macro{RedeclareNoteColumn} only +to reconfigure an existing note column. + +By the way, when reconfiguring existing note columns with +\Macro{DeclareNoteColumn} or \Macro{RedeclareNoteColumn}, the notes that have +already been generated for this column are retained. + +\BeginIndex{FontElement}{notecolumn.\PName{note column name}}% +\BeginIndex{FontElement}{notecolumn.marginpar}% +Declaring a new note column always defines a new element for changing its font +attributes with \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont}, if such an element does not yet exist. +The name of the element is \PValue{notecolumn.}\PName{note column name}. For +this reason, the default note column \PValue{marginnote} has the +element\textnote{element name} \FontElement{notecolumn.marginpar}. You can +directly specify the initial setting of the element's font when declaring a +note column by using the \Option{font} option within the \PName{option list}.% +\EndIndex{FontElement}{notecolumn.marginpar}% +\EndIndex{FontElement}{notecolumn.\PName{note column name}}% + +The \PName{option list} is a comma-separated list of keys with or without +values, also known as options. The available options are listed in +\autoref{tab:scrlayer-notecolumn.note.column.options}, +\autopageref{tab:scrlayer-notecolumn.note.column.options}. +The\textnote{default: option \Option{marginpar}} \Option{marginpar} option is +set by default, but you can overwrite this default with your individual +settings. + +Because note columns are implemented using \Package{scrlayer}, a +layer\Index{layer} is created for each note column. The layer +name\textnote{layer name} is the same as the name of the element, +\PValue{notecolumn.}\PName{note column name}. For more information about +layers see \autoref{sec:scrlayer.layers}, starting on +\autopageref{sec:scrlayer.layers}. +% +\begin{Example} + Suppose you are a professor of comedy law and want to write a treatise on + the new ``Statute Concerning the Riotous Airing of Common Humour'', SCRACH + for short. The better part of the work will consist of commentary on + individual paragraphs of the statute. You decide on a two-column layout, + with the comments in the main column and the paragraphs placed in a smaller + note column on the right of the main column using a font that is + smaller\iffree{ and in a different colour}{}. +\begin{lstcode} + \documentclass{scrartcl} + \usepackage{lmodern} + \usepackage{xcolor} + + \usepackage{scrjura} + \setkomafont{contract.Clause}{\bfseries} + \setkeys{contract}{preskip=-\dp\strutbox} + + \usepackage{scrlayer-scrpage} + \usepackage{scrlayer-notecolumn} + + \newlength{\paragraphscolwidth} + \AfterCalculatingTypearea{% + \setlength{\paragraphscolwidth}{% + .333\textwidth}% + \addtolength{\paragraphscolwidth}{% + -\marginparsep}% + } + \recalctypearea + \DeclareNewNoteColumn[% + position=\oddsidemargin+1in + +.667\textwidth + +\marginparsep, + width=\paragraphscolwidth, + font=\raggedright\footnotesize + \color{blue} + ]{paragraphs} +\end{lstcode} + The treatise should be a one-sided article. The font is Latin Modern, and + the colour selection uses the \Package{xcolor}\IndexPackage{xcolor} package. + + For formatting legal texts\textnote{legal texts with + \hyperref[cha:scrjura]{\Package{scrjura}}} with the + \hyperref[cha:scrjura]{\Package{scrjura}}\IndexPackage{scrjura} package, see + \autoref{cha:scrjura}. + + Since this document uses a page style\textnote{page style with + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} with a + page number, the + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + \IndexPackage{scrlayer-scrpage} package is loaded. Thus, note columns can be + output on all pages. + + Next, the \Package{scrlayer-notecolumn}\textnote{note columns with + \Package{scrlayer-notecolumn}} package is loaded. The required width of the + note column is calculated with + \DescRef{typearea-experts.cmd.AfterCalculatingTypearea}% + \IndexPackage{typearea}\IndexCmd{AfterCalculatingTypearea} after any + recalculation\textnote{type area with + \hyperref[cha:typearea]{\Package{typearea}}}% + \IndexPackage{typearea} of the type area. It should be one third of the type + area minus the distance between the main text and the note column. % + + With this information, we define the new note column. For the positions, we + use a simple dimension expression. Note that \Length{oddsidemargin} is not + the total left margin but for historical reasons the left margin minus + 1\Unit{inch}. So we have to add this value. + + This concludes the definition. Note that the note column would currently be + placed inside the type area. This means that the note column would overwrite + the text. + +\begin{lstcode} + \begin{document} + + \title{Commentary on the SCRACH} + \author{Professor R. O. Tenase} + \date{11/11/2011} + \maketitle + \tableofcontents + + \section{Preamble} + The SCRACH is without doubt the most important law + on the manners of humour that has been passed in + the last thousand years. The first reading took + place on 11/11/1111 in the Supreme Manic Fun + Congress, but the law was rejected by the Vizier + of Fun. Only after the ludicrous, Manic Fun + monarchy was transformed into a representative, + witty monarchy by W. Itzbold, on 9/9/1999 was + the way finally clear for this law. +\end{lstcode} + Because\textnote{Attention!} the text area was not reduced, the preamble is + output extending over the whole width of the type area. To test this, you + can temporarily add: +\begin{lstcode} + \end{document} +\end{lstcode} +\end{Example} +% +In the example, the question of how the text for the commentary can be set in +a narrower column remains unresolved. You will discover how to do this by +continuing the example below.% +% +%\begin{table}% Umbruchoptimierung: Tabelle hinter das Beispiel verschoben +\begin{desclist} + \desccaption{% +% \caption[Available settings for declaring note columns]{% + Available settings for declaring note columns% +% }% + \label{tab:scrlayer-notecolumn.note.column.options}% + }{% + Available settings for declaring note columns + (\emph{continued})% + }% +% \begin{desctabular} + \entry{\OptionVName{font}{font attribute}}{% + The font attributes of the note column set with + \DescRef{\LabelBase.cmd.setkomafont}. For possible values, refer to + \autoref{sec:maincls.textmarkup}, + \DescPageRef{maincls.cmd.setkomafont}.\par% + Default: \emph{empty}% + }% + \entry{\Option{marginpar}}{% + Sets \Option{position} and \Option{width} to correspond to the marginal + note column of \DescRef{maincls.cmd.marginpar}. Switching between + \Macro{reversemarginpar}\IndexCmd{reversemarginpar} and + \Macro{normalmarginpar}\IndexCmd{normalmarginpar} is only considered at + the end of the page when the note column is output. Note that this + option does not expect or allow any value.\par% + Default: \emph{yes}% + }% + \entry{\Option{normalmarginpar}}{% + Sets \Option{position} and \Option{width} to use the normal marginal + note column and ignore \Macro{reversemarginpar} and + \Macro{normalmarginpar}. Note that this option does not expect or allow + a value.\par% + Default: \emph{no}% + }% + \entry{\OptionVName{position}{offset}}{% + Sets the horizontal offset of the note column from the left edge of the + paper. The \PName{offset} can be a complex expression as long as it is + fully expandable and expands to a length or a dimensional expression at + the time the note column is output. See \cite[section~3.5]{manual:eTeX} + for more information about dimensional expressions.\par% + Default: \emph{through the \Option{marginpar} option}% + }% + \entry{\Option{reversemarginpar}}{% + Sets \Option{position} and \Option{width} to use the reverse marginal + note column of \DescRef{maincls.cmd.marginpar} with the + \Macro{reversemarginpar} setting. Note that this option does not expect + or allow a value.\par% + Default: \emph{no}% + }% + \entry{\OptionVName{width}{length}}{% + Sets the width of the note column. The \PName{length} can be a complex + expression as long as it is fully expandable and expands to a length or + a dimensional expression at the time the note column is output. See + \cite[section~3.5]{manual:eTeX} for more information about dimensional + expressions.\par% + Default: \emph{through the \Option{marginpar} option}% + }% +% \end{desctabular} +%\end{table} +\end{desclist} +\EndIndexGroup + + +\section{Making a Note} +\seclabel{makenote} + +After you declare a note column, you can create notes for this column. But +these notes are not be output immediately. Initially, they are written to an +auxiliary file with extension ``\File{.slnc}''. Specifically, they are first +written to the \File{aux}-file and, when the \File{aux}-file is read inside +\Macro{end}\PParameter{document}, they are copied to the \File{slnc}-file. If +necessary, the \Macro{nofiles}\IndexCmd{nofiles} setting is also taken into +account. At the next \LaTeX{} run, this auxiliary file will be read piece by +piece, according to the progress of the document, and at the end of the page +the notes for that page will be output. + +Note\textnote{Attention!}, however, that note columns are output only on pages +whose page style is based on the \Package{scrlayer}\IndexPackage{scrlayer} +package. This package is loaded automatically by \Package{scrlayer-notecolumn} +and by default provides only the \PageStyle{empty}\IndexPagestyle{empty} page +style. If you need additional page styles, the +\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} package is +recommended. + +\begin{Declaration} + \Macro{makenote}\OParameter{note-column name}\Parameter{note}\\ + \Macro{makenote*}\OParameter{note-column name}\Parameter{note}\\ +\end{Declaration} +You can use this command to make a new \PName{note}. The current vertical +position is used as the vertical position for the start of the \PName{note}. +The horizontal position for the note results from the defined position of the +note column. To work correctly, the package relies on +\Macro{pdfsavepos}\IndexCmd{pdfsavepos}, +\Macro{pdflastypos}\IndexCmd{pdflastypos}, and +\Macro{pdfpageheight}\IndexLength{pdfpageheight} or their equivalent in newer +Lua\TeX{} versions. Without these commands, \Package{scrlayer-notecolumn} will +not work. The primitives should act exactly as they would using pdf\TeX. + +However, if the package detects a collision\textnote{collision avoidance} with +a previous \PName{note} in the same note column, the new \PName{note} is moved +below that earlier \PName{note}. If the \PName{note} does not fit on the +page\textnote{page break}\Index{page>break}, it will be moved completely or +partially to the next page. + +The optional argument \PName{note column name} determines which note column +should be used for the \PName{note}. If the optional argument is omitted, the +default note column \PValue{marginpar} is used.% +\begin{Example} + Let's add a commented paragraph to the example of the previous section. The + paragraph itself should be placed in the newly defined note column: +\begin{lstcode} + \section{Analysis} + \begin{addmargin}[0pt]{.333\textwidth} + \makenote[paragraphs]{% + \protect\begin{contract} + \protect\Clause{% + title={No Joke without an Audience}% + } + A joke can only be funny if is has an + audience. + \protect\end{contract}% + } + This is one of the most central statements of + the law. It is so fundamental that it is quite + appropriate to bow to the wisdom of the authors. +\end{lstcode} + The \DescRef{maincls.env.addmargin}\IndexEnv{addmargin}% + \textnote{column width with \DescRef{maincls.env.addmargin}} environment, + which is described in \autoref{sec:maincls.lists}, + \DescPageRef{maincls.env.addmargin}, is used to reduce the width of the main + text by the width of the column for the paragraphs. + + Here you can see one of the few problems of using \Macro{makenote}. Because + the mandatory argument is written to an auxiliary file, + commands\textnote{fragile commands} inside this argument can, unfortunately, + \emph{break}. To avoid this, you should use \Macro{protect} in front of all + commands that should not expand when written to the auxiliary file. + Otherwise, using a command inside this argument could result in error + messages. + + In principle you could now finish this example with +\begin{lstcode} + \end{addmargin} + \end{document} +\end{lstcode} + to see a preliminary result. +\end{Example} +If you test this example, you will see that the column for the legal text is +longer than that of the commentary. If\textnote{Attention!} you add another +section with another paragraph, you may encounter the problem that the +commentary will not continue below the legal text but immediately after the +previous comment. Next you will find a solution to this problem. + +The\ChangedAt{v0.1.2583}{\Package{scrlayer-notecolumn}} problem with fragile +commands mentioned in the example above does not occur with the starred +variant\important{\Macro{makenote*}}. It uses \Macro{detokenize} to prevent +the expansion of commands. But this also means that you should not use +commands in the \PName{note} that change their definition within the +document.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{syncwithnotecolumn}\OParameter{note column name} +\end{Declaration} +This command adds a +synchronisation\textnote{synchronisation}\Index{synchronisation} point in a +note column and in the main text of the document. Whenever a synchronisation +point is reached during the output of a note column or the main text, a mark +will be generated that consists of the current page and the current vertical +position. + +In parallel with the generation of synchronisation points, +\Package{scrlayer-notecolumn} determines whether a mark has been set in the +note column or the main text during the previous \LaTeX{} run. If so, it +compares their values. If the mark of the note column is lower on the current +page or on a later page, the main text will be moved down to the position of +the mark. + +As a rule,\textnote{Hint!} you should not place synchronisation points within +paragraphs of the main text but only between them. If you nonetheless use +\Macro{syncwithnotecolumn} inside a paragraph, the synchronisation point will +be delayed until the current line has been output. This behaviour is similar +to that of, e.\,g., \Macro{vspace}\IndexCmd{vspace} in this respect. + +Because synchronisation points are not recognized until the next \LaTeX{} +run\textnote{several \LaTeX{} runs}, this mechanism requires at least three +\LaTeX{} runs. Any new synchronisation may also result in shifts of later +synchronisation points, which in turn will require additional \LaTeX{} runs. +Such shifts are usually indicated by the message: ``\LaTeX{} Warning: Label(s) +may have changed. Rerun to get cross-references right.'' But reports about +undefined labels may also indicate the need for another \LaTeX{} run. + +If you omit the optional argument, the default note column \PValue{marginpar} +will be used. Note\textnote{Attention!} that an empty optional argument is not +the same as omitting the optional argument! + +You cannot use\textnote{Attention!} \Macro{syncwithnotecolumn} inside a note +itself, that is, inside the mandatory argument of +\Macro{makenote}\IndexCmd{makenote}! Currently the package cannot recognise +such a mistake, and it causes new shifts of the synchronisation point with +each \LaTeX{} run, so the process will never terminate. To synchronise two or +more note columns, you have to synchronise each of them with the main text. +The recommended command for this is described below.% +% +\begin{Example} + Let's extend the example above by first adding a synchronisation point + and then another paragraph with a comment: +\begin{lstcode} + \syncwithnotecolumn[paragraphs]\bigskip + \makenote[paragraphs]{% + \protect\begin{contract} + \protect\Clause{title={Humor of a Culture}} + \setcounter{par}{0}% + The humour of a joke can be determined by the + cultural environment in which it is told. + + The humour of a joke can be determined by the + cultural environment in which it acts. + \protect\end{contract} + } + The cultural component of a joke is, in fact, not + negligible. Although the political correctness of + using the cultural environment can easily be + disputed, nonetheless the accuracy of such comedy + in the appropriate environment is striking. On + the other hand, a supposed joke in the wrong + cultural environment can also be a real danger + for the joke teller. +\end{lstcode} + In addition to the synchronisation point, a vertical skip has been added + with \Macro{bigskip} to better distinguish each paragraph and the + corresponding comments. + + Further\textnote{Attention}, this example illustrates another potential + problem. Because the note columns uses boxes that are assembled and + disassembled, counters\textnote{counter in note column} inside note columns + can sometimes jitter. In the example, therefore, the first paragraph would + be numbered 2 instead of 1. This, however, can easily be fixed by a direct + reset of the corresponding counter. + + The example is almost complete. You just have to close the environments: +\begin{lstcode} + \end{addmargin} + \end{document} +\end{lstcode} + In reality, of course, all the remaining section of the law should also be + commented. But let us focus on the main purpose. +\end{Example} +But stop! What if, in this example, the \PName{paragraphs} would no longer fit +on the page? Would it be printed on the next page? We will answer this +question in the next section.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{syncwithnotecolumns}\OParameter{list of note column names} +\end{Declaration} +This command synchronises the main text with all note columns of the +comma-separated \PName{list of note column names}. The main text +will be synchronised with the note column whose mark is closest to the +end of the document. As a side effect, the note columns will be synchronised +with each other. + +If the optional argument is omitted or empty (or begins with \Macro{relax}), +synchronisation will be done with all currently declared note columns.% +\EndIndexGroup + + +\section{Forced Output of Note Columns} +\seclabel{clearnotes} + +In addition to the normal output of note columns described in the previous +section, you may sometimes need to output all collected notes that have +not yet been output. This is especially useful when large notes cause more and +more notes to be moved down to new pages. A good time to force the +output\textnote{force output} is, for example, the end of a chapter or the end +of the document. + +\begin{Declaration} + \Macro{clearnotecolumn}\OParameter{note column name} +\end{Declaration} +This command prints all notes\textnote{pending notes} of a particular note +column that have not yet been output by the end of the current page but which +were created on that or a previous page. Blank pages are generated as needed +to output these pending notes. During the output of the pending notes of this +note column, notes of other note columns may also be output, but only as +necessary to output the pending notes of the specified note column. + +During the output of the pending notes, notes created in the previous \LaTeX{} +run on the pages that are now replaced by the inserted blank pages may be +output by mistake. This will be corrected automatically in one of the +subsequent \LaTeX{} runs. Such shifts are usually indicated by the message: +``\LaTeX{} Warning: Label(s) may have changed. Rerun to get cross-references +right.'' + +The note column whose pending notes are to be output is indicated by the +optional argument \PName{note column name}. If this argument is omitted, the +notes of the default note column \PValue{marginpar} will be output. + +The attentive reader\textnote{forced output vs. synchronisation} will have +noticed that the forced output of a note column is not unlike synchronisation. +But if the forced output actually results in an output, it will be at the +start of a new page and not just below the previous output. Nonetheless, a +forced output usually results in fewer \LaTeX{} runs.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{clearnotecolumns}\OParameter{list of note column names} +\end{Declaration} +This command is similar to \DescRef{\LabelBase.cmd.clearnotecolumn}, but the +the optional argument here can be not only the name of one note column but a +comma-separated \PName{list of note column names}. The pending notes of all +these note columns are then ouput. + +If you omit the optional argument or leave it empty, all pending notes of all +note columns will be output.% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{autoclearnotecolumns}{simple switch} +\end{Declaration} +As a rule, pending notes will always be output if a document +implicitly\,---\,e.\,g. because of a \DescRef{maincls.cmd.chapter} +command\,---\,or explicitly executes \DescRef{maincls.cmd.clearpage}. This is +also the case at the end of the document within +\Macro{end}\PParameter{document}. The \Option{autoclearnotecolumns} option can +be used to control whether \DescRef{\LabelBase.cmd.clearnotecolumns} should be +executed automatically without arguments when running +\DescRef{maincls.cmd.clearpage}. + +Since this is generally the desired behaviour, the option is active by +default. But you can change this with the appropriate value for a simple +switch (see \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}) +at any time. + +Note\textnote{Attention!} that disabling the automatic output of pending notes +can result in lost notes at the end of the document. So in this case you +should insert \DescRef{\LabelBase.cmd.clearnotecolumns} before +\Macro{end}\PParameter{document} fore safety's sake. + +The question from the end of the last section should now be answered. If the +paragraph is to be completely output, it had to be wrapped to the next page. +This is, of course, the default setting. However, since this would happen +after the end of the \DescRef{maincls.env.addmargin} environment, the forced +output could still overlap with subsequent text. So in the example it would +make sense to add another synchronisation point after the +\DescRef{maincls.env.addmargin} environment. + +The result of the example is shown in +\autoref{fig:scrlayer-notecolumn.example}.\iffree{}{ Only the colour has been +changed from blue to grey.} + +\begin{figure} + \KOMAoptions{captions=bottombeside}% + \setcapindent{0pt}% + \begin{captionbeside}[{A sample page for the example in + \autoref{cha:scrlayer-notecolumn}}]{A sample page for the example in + this chapter\label{fig:scrlayer-notecolumn.example}}[l] + \frame{\includegraphics[width=.5\textwidth,keepaspectratio]% + {scrlayer-notecolumn-example}} + \end{captionbeside} +\end{figure} +\EndIndexGroup +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: iso-latin-1 +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrlayer-scrpage-experts.tex b/macros/latex/contrib/koma-script/source-doc/english/scrlayer-scrpage-experts.tex new file mode 100644 index 0000000000..c9cdc98c8a --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrlayer-scrpage-experts.tex @@ -0,0 +1,393 @@ +% ====================================================================== +% scrlayer-scrpage-experts.tex +% Copyright (c) Markus Kohm, 2013-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrlayer-scrpage-experts.tex +% Copyright (c) Markus Kohm, 2013-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Expert chapter about scrlayer-scrpage of the KOMA-Script guide +% +% ---------------------------------------------------------------------- +% +% Expertenkapitel ueber scrlayer-scrpage in der KOMA-Script-Anleitung +% +% ============================================================================ + +\KOMAProvidesFile{scrlayer-scrpage-experts.tex}% + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (chapter: scrlayer-scrpage-experts)] +\translator{Markus Kohm\and Karl Hagen} + +% Date version of the translated file: 2018-01-31 + +\chapter[{Additional Features of \Package{scrlayer-scrpage}}] + {Additional Features\ChangedAt{v3.12}{\Package{scrlayer-scrpage}} with + the \Package{scrlayer-scrpage} package} +\labelbase{scrlayer-scrpage-experts} +% +\BeginIndexGroup +\BeginIndex{Package}{scrlayer-scrpage}% +The \Package{scrlayer-scrpage} package offers many features beyond what has +been described in \autoref{cha:scrlayer-scrpage} of \autoref{part:forAuthors} +of this \iffree{guide}{book}. However, the average user will not normally need +these extensions, and some of them are only provided for compatibility with +\Package{scrpage2}. The documentation here in \autoref{part:forExperts} serves +to deepen and broaded your knowledge, and its mastery goes beyond basic +skills. + +\LoadCommonFile{pagestylemanipulation}% \section{Manipulating Defined Page Styles} + +\section{Defining New Pairs of Page Styles} +\seclabel{pagestyle.pairs} + +The two page styles \PageStyle{scrheadings} and \PageStyle{plain.scrheadings} +were described in \autoref{sec:scrlayer-scrpage.predefined.pagestyles}. You +can view them as a kind of pair, with \PageStyle{scrheadings} intended as the +main page style for a running head and \PageStyle{plain.scrheadings} the +corresponding \PageStyle{plain} page style without a running head but +generally with pagination. In addition to configuring this predefined pair, +\Package{scrlayer-scrpage} also lets you define additional pairs of page +styles. The name of the main page style, for example \PageStyle{scrheadings}, +also serves as the name of the page-style pair. + +\iffree{ + The vast majority of users will not need more than the one predefined + page-style pair, \PageStyle{scrheadings}. So the commands documented in this + section are therefore extensions for special cases. Since I have not come + across any suitable applications while writing this manual, there are no + detailed examples. Should I ever run across a particularly nice application + while providing support, I will happily include it in future versions. At + the same time, however, I'm virtually certain that all such cases could also + be solved using the predefined pair only.}{} + +\begin{Declaration} + \Macro{defpairofpagestyles}% + \OParameter{parent pair}\Parameter{name}\Parameter{definition}% + \Macro{newpairofpagestyles}% + \OParameter{parent pair}\Parameter{name}\Parameter{definition}% + \Macro{renewpairofpagestyles}% + \OParameter{parent pair}\Parameter{name}\Parameter{definition}% + \Macro{providepairofpagestyles}% + \OParameter{parent pair}\Parameter{name}\Parameter{definition} +\end{Declaration} +You can use these commands to define pairs of page styles similar to +\PageStyle{scrheadings} and \PageStyle{plain.scrheadings}, where \PName{name} +is the name of the main page style corresponding to \PageStyle{scrheadings}. +The name of the equivalent \PageStyle{plain} page style will be prefixed by +\PValue{plain.} automatically. So \PName{name} is not only the name of the +pair of page styles, but also the name of the main page style of that pair, +while \PValue{plain.}\PName{name} is the name of the \PageStyle{plain} page +style of this pair. + +If you provide the optional \PName{parent pair} argument, this is the name of +a page-style pair whose settings are used to initialise the new page-style +pair. So the new pair inherits the configuration of the \PName{parent pair}. + +Although \autoref{sec:scrlayer-scrpage.predefined.pagestyles} might have +created the impression that the commands described there apply only to +\PageStyle{scrheadings} and \PageStyle{plain.scrheadings} only, this is true +only so long as those two page styles are the only defined page-style pair. As +soon as there are multiple page-style pairs, +\DescRef{scrlayer-scrpage.cmd.lehead}, \DescRef{scrlayer-scrpage.cmd.cehead}, +\DescRef{scrlayer-scrpage.cmd.rehead}, \DescRef{scrlayer-scrpage.cmd.lohead}, +\DescRef{scrlayer-scrpage.cmd.cohead}, \DescRef{scrlayer-scrpage.cmd.rohead}, +\DescRef{scrlayer-scrpage.cmd.lefoot}, \DescRef{scrlayer-scrpage.cmd.cefoot}, +\DescRef{scrlayer-scrpage.cmd.refoot}, \DescRef{scrlayer-scrpage.cmd.lofoot}, +\DescRef{scrlayer-scrpage.cmd.cofoot}, \DescRef{scrlayer-scrpage.cmd.rofoot}, +\DescRef{scrlayer-scrpage.cmd.ihead}, \DescRef{scrlayer-scrpage.cmd.chead}, +\DescRef{scrlayer-scrpage.cmd.ohead}, \DescRef{scrlayer-scrpage.cmd.ifoot}, +\DescRef{scrlayer-scrpage.cmd.cfoot}, and \DescRef{scrlayer-scrpage.cmd.ofoot} +all refer to page-style pair that was most recently activated. + +In addition to those eighteen commands mentioned above, the three commands +described below, \DescRef{\LabelBase.cmd.clearmainofpairofpagestyles}, +\DescRef{\LabelBase.cmd.clearplainofpairofpagestyles}, and +\DescRef{\LabelBase.cmd.clearpairofpagestyles}, are designed to be used inside +the \PName{definition} argument. In this case, they represent a kind of +default configuration of the page-style pair that is executed each time the +pair is activated. You activate a page-style pair by activating either one two +page styles in the pair. Typically, you do so with +\DescRef{maincls.cmd.pagestyle}\IndexCmd{pagestyle}. + +Note that the commands of \autoref{sec:scrlayer-scrpage.pagestyle.content} on +\autopageref{sec:scrlayer-scrpage.pagestyle.content} are general in nature and +apply to all page styles defined with \Package{scrlayer-scrpage}. + +Although \Macro{defpairofpagestyles} defines a page-style pair regardless of +whether the corresponding page styles already exist, +\Macro{newpairofpagestyles} and \Macro{providepairofpagestyles} do so only if +the page styles are currently undefined. If at least one of the page styles is +already defined, the new definition of \Macro{providepairofpagestyles} will be +ignored, whereas using \Macro{newpairofpagestyles} results in an error +message. To redefine existing page-style pairs, you can use +\Macro{renewpairofpagestyles}. With this an is thrown if either one of the two +page styles of the pair does not already exist.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{clearmainofpairofpagestyles}% + \Macro{clearplainofpairofpagestyles}% + \Macro{clearpairofpagestyles} +\end{Declaration} +The \Macro{clearmainofpairofpagestyles} command sets the main page style of +the most recently activated page-style pair to be empty. In contrast, the +\Macro{clearplainofpairofpagestyles} command sets the \PageStyle{plain} page +style of the active page-style pair to be empty. Finally, +\Macro{clearpairofpagestyle} sets both page styles of the activate pair to be +empty. + +But note\textnote{Attention!} that none of these commands removes the +definitions of the \PName{definition} argument that was specified when +defining the page-style pair (see above). So if you activate the pair of page +styles again, those definitions will be used again! + +You can use these commands inside the \PName{definition} of the page-style +pair explained above. But you can also use them outside this definition. In +this case, they refer to the most recently activated page-style pair.% +\EndIndexGroup + + +\section{Defining Complex Page Styles} +\seclabel{pagestyle.experts} + +In addition to the predefined page styles, \Package{scrlayer-scrpage} also +provides a more basic interface for defining new page styles. The page-style +definitions discussed so far use this interface internally, as do the obsolete +commands in \autoref{sec:\LabelBase.pagestyle.triple}. +\Package{scrlayer-scrpage}. Because of its complexity, however, only advanced +users should try to use it directly. Less experienced users can already +achieve almost everything possible with this low-level interface by using the +possibilities described previously. + +\begin{Declaration} + \Macro{defpagestyle}% + \Parameter{name}\Parameter{header specification}\Parameter{footer specification}% + \Macro{newpagestyle}% + \Parameter{name}\Parameter{header specification}\Parameter{footer specification}% + \Macro{providepagestyle}% + \Parameter{name}\Parameter{header specification}\Parameter{footer specification}% + \Macro{renewpagestyle}% + \Parameter{name}\Parameter{header specification}\Parameter{footer specification}% +\end{Declaration} +You can use these commands to define a single page style with maximum +flexibility, where \PName{name} is the name of the page style that you want to +define. + +The parameters \PName{header specification} and \PName{footer specification} +have identical structure: +\begin{quote}\raggedright + \texttt{% + (\PName{length of the line above},\PName{thickness of the line above})\%\\ + \Parameter{specification for the left page in two-side layout}\%\\ + \Parameter{specification for the right page in two-side layout}\%\\ + \Parameter{specification for all pages in one-side laypout}\%\\ + (\PName{length of the line below},\PName{thickness of the line below})% + } +\end{quote} +The arguments in the round brackets are optional. That is, you can omit them +together with the brackets. In that case, the length and thickness of the +corresponding horizontal rules are based on the \KOMAScript{} options +\DescRef{scrlayer-scrpage.option.headtopline}, +\DescRef{scrlayer-scrpage.option.headsepline}, +\DescRef{scrlayer-scrpage.option.footsepline}, and +\DescRef{scrlayer-scrpage.option.footbotline} (see +\autoref{sec:scrlayer-scrpage.pagestyle.content}, +\DescPageRef{scrlayer-scrpage.option.headtopline}). + +All three arguments in curly brackets are mandatory and are used depending on +the page and the layout settings. Their content can be anything you want. For +page styles with running heads, however, you should use +\DescRef{scrlayer-scrpage.cmd.headmark}, +\DescRef{scrlayer-scrpage.cmd.leftmark}, or +\DescRef{scrlayer-scrpage.cmd.rightmark} inside the specification. Under no +circumstances should you directly put the number or text of a sectioning +command here. Because of the \LaTeX{}'s asynchronous page construction, the +wrong numbers or text can appear in the header or footer if you do so. + +The \Macro{defpagestyle} command defines the page style regardless of whether +it already exists or not. In contrast, \Macro{newpagestyle} throws an error if +a page style of the same \PName{name} already exists. On the other hand, +\Macro{providepagestyle} simply ignores the definition if the \PName{name} has +already been used for a page style. Conversely, \Macro{renewpagestyle} can +only redefine an existing page style. For a new \PName{name}, it throws an +error. + +All four commands are based on the +\DescRef{scrlayer.cmd.DeclarePageStyleByLayers}% +\IndexCmd{DeclarePageStyleByLayers} command of the +\hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer} package. +You can find the layers that are defined for a page style \PName{name} in +\autoref{tab:scrlayer-scrpage-experts.layersperstyle}, and more information +about layers and layer-page in \autoref{cha:scrlayer}, starting on +\autopageref{cha:scrlayer}.% + +\begin{table} +% \KOMAoptions{captions=topbeside} +% \setcapindent{0pt} +% \begin{captionbeside} + \caption + [{The layers \Package{scrlayer-scrpage} defines for a page style}] + {The layers \Package{scrlayer-scrpage} defines for a \PName{name} page + style\label{tab:scrlayer-scrpage-experts.layersperstyle}} +% [l] + \begin{tabular}{ll} + \toprule + Name of the layer & Meaning of the layer \\ + \midrule + \PName{name}\PValue{.head.above.line} + & horizontal line above the header\\ + \PName{name}\PValue{.head.odd} + & header of odd pages in two-sided printing\\ + \PName{name}\PValue{.head.even} + & header of even pages in two-sided printing\\ + \PName{name}\PValue{.head.oneside} + & header in one-sided printing\\ + \PName{name}\PValue{.head.below.line} + & horizontal line below the header\\ + \PName{name}\PValue{.foot.above.line} + & horizontal line above the footer\\ + \PName{name}\PValue{.foot.odd} + & footer of odd pages in two-sided printing\\ + \PName{name}\PValue{.foot.even} + & footer of even pages in two-sided printing\\ + \PName{name}\PValue{.foot.oneside} + & footer in one-sided printing\\ + \PName{name}\PValue{.foot.below.line} + & horizontal line below the footer\\ + \bottomrule + \end{tabular} +% \end{captionbeside} +\end{table} + +\begin{Example} + Suppose you want to set a background colour for the header of the + \PageStyle{scrheadings} page style. From the introduction to this chapter + and \autoref{tab:scrlayer-scrpage-experts.layersperstyle}, you know that + \PageStyle{scrheadings} is a layer page style that includes the layers + \PValue{scrheadings.head.even}, \PValue{scrheadings.head.odd}, and + \PValue{scrheadings.head.oneside}. You now define three more layers for + their backgrounds and add them at the beginning of the page style: +\begin{lstcode} + \documentclass{scrartcl} + \usepackage[automark]{scrlayer-scrpage} + \usepackage{xcolor} + \usepackage{blindtext} + \DeclareLayer[clone=scrheadings.head.oneside, + contents={% + \color{yellow}\rule[-\dp\strutbox]{\layerwidth}{\layerheight}% + }% + ]{scrheadings.head.oneside.background} + \DeclareLayer[clone=scrheadings.head.odd, + contents={% + \color{yellow}\rule[-\dp\strutbox]{\layerwidth}{\layerheight}% + }% + ]{scrheadings.head.odd.background} + \DeclareLayer[clone=scrheadings.head.even, + contents={% + \color{yellow}\rule[-\dp\strutbox]{\layerwidth}{\layerheight}% + }% + ]{scrheadings.head.even.background} + \AddLayersAtBeginOfPageStyle{scrheadings}{% + scrheadings.head.oneside.background,% + scrheadings.head.odd.background,% + scrheadings.head.even.background% + } + \pagestyle{scrheadings} + \begin{document} + \blinddocument + \end{document} +\end{lstcode} + As you can see, the example uses three layers so that the position and size + of the background layers could simply be copied from the corresponding + header layer using the \Option{clone} option. This is easier than using only + one background layer and dynamically calculating its position each time. + + The coloured background itself was created using a \Macro{rule} command. The + size arguments of this \Macro{rule} are given by + \DescRef{scrlayer.cmd.layerwidth} and \DescRef{scrlayer.cmd.layerheight} + which contain the current width and height of the layer itself. The optional + argument of \Macro{rule} is used to move the rule down by the height of a + descender. +\end{Example} +% +Instead of using new layers to colour the background in the example above, +\Macro{colorbox} and \DescRef{scrlayer-scrpage.cmd.chead} could have been +used. You can work out a solution using this method as an exercise. Likewise, +you could have added the background layers individually just before the +corresponding content layer. You can implement this as an exercise too.% +\EndIndexGroup + +\section{Defining Simple Page Styles with a Tripartite Header and Footer} +\seclabel{pagestyle.triple} + +\LoadNonFree{scrlayer-scrpage-experts}{1} + +\section{Legacy Features of \Package{scrpage2}} +\seclabel{obsolete} + +\begin{Explain} + The \Package{scrlayer-scrpage} package contains some legacy features that + derive from \Package{scrpage2} and exist only to be as compatible as possible + with that package. Users only need to understand these features if they want + to edit an old document based on \Package{scrpage2}. You\textnote{Attention!} + should not use the items documented here in new documents! +\end{Explain} + +\begin{Declaration} + \KOption{hmode}\PValue{simple switch} +\end{Declaration} +The \Package{scrpage2} package always outputs headers and footers in +horizontal mode. In contrast, \Package{scrlayer-scrpage} in the default +setting only switches into horizontal mode when horizontal material is output. +However, if you activate the \Option{hmode} option, \Package{scrlayer-scrpage} +will behave like \Package{scrpage2} and switch to horizontal mode before any +output. This can affect both the processing of white space at the beginning of +the output and vertical alignment. + +The options recognizes the standard values for simple switches listed in +\autoref{tab:truefalseswitch} on \autopageref{tab:truefalseswitch}. The option +is deactivated by default.% +\EndIndexGroup + +\LoadNonFree{scrlayer-scrpage-experts}{0} +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrlayer-scrpage.tex b/macros/latex/contrib/koma-script/source-doc/english/scrlayer-scrpage.tex new file mode 100644 index 0000000000..d3c50bfef0 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrlayer-scrpage.tex @@ -0,0 +1,1190 @@ +% ====================================================================== +% scrlayer-scrpage.tex +% Copyright (c) Markus Kohm, 2013-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrlayer-scrpage.tex +% Copyright (c) Markus Kohm, 2013-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrlayer-scrpage of the KOMA-Script guide +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber scrlayer-scrpage in der KOMA-Script-Anleitung +% +% ============================================================================ + +\KOMAProvidesFile{scrlayer-scrpage.tex}% + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (chapter: scrlayer-scrpage)] +\translator{Markus Kohm\and Jana Schubert\and Jens H\"uhne\and Karl Hagen} + +% Date version of the translated file: 2018-02-13 + +\chapter[{Headers and Footers with \Package{scrlayer-scrpage}}] + {Headers\ChangedAt{v3.12}{\Package{scrlayer-scrpage}} and + Footers with \Package{scrlayer-scrpage}} +\labelbase{scrlayer-scrpage} +% +\BeginIndexGroup +\BeginIndex{Package}{scrlayer-scrpage}% +\begin{Explain} + Until version 3.11b of \KOMAScript, the \Package{scrpage2}% + \IndexPackage[indexmain]{scrpage2}\important{\Package{scrpage2}} package was + the recommended way to customise headers and footers beyond the options + provided by the \PageStyle{headings}, \PageStyle{myheadings}, + \PageStyle{plain}, and \PageStyle{empty} page styles of the \KOMAScript{} + classes. + \iffalse% + The still older \Package{scrpage}\IndexPackage{scrpage} package was marked + obsolete in 2001 and removed from the regular \KOMAScript{} distribution in + 2013.\par + \fi% + Since 2013, the \hyperref[cha:scrlayer]{\Package{scrlayer}}% + \important{\hyperref[cha:scrlayer]{\Package{scrlayer}}}% + \IndexPackage{scrlayer} package has been included as a basic module of + \KOMAScript. This package provides a layer model and a new page-style model + based upon it. However, the package's interface is almost too flexible and + consequently not easy for the average user to comprehend. For more + information about this interface, see \autoref{cha:scrlayer} in + \autoref{part:forExperts}. However, a few of the options that are actually + part of \Package{scrlayer}, and which are therefore taken up again in that + chapter, are also documented here because they are required to use + \Package{scrlayer-scrpage}. + + Many users are already familiar with the commands from \Package{scrpage2}. + For this reason, \Package{scrlayer-scrpage} provides a method for + manipulating headers and footers which is based on \Package{scrlayer}, is + largely compatible with \Package{scrpage2}, and at the same time greatly + expands the user interface. If you are already familiar with + \Package{scrpage2} and refrain from direct calls to its internal commands, + you can usually use \Package{scrlayer-scrpage} as a drop-in replacement. + This also applies to most examples using \Package{scrpage2} found in + \LaTeX{} books or on the Internet.% + \iffalse% + \iffree{}{\par With the release of this book, \Package{scrlayer-scrpage} + for \KOMAScript{} is recommended as the tool of choice when it comes to + changing the predefined page styles. Using the obsolete package + \Package{scrpage2}\IndexPackage[indexmain]{scrpage2}% + \important{\Package{scrpage2}} is now deprecated. Therefore, the + commands for this outdated package are no longer part of this book. If + you encounter older documents that still use \Package{scrpage2}, + consider switching to \Package{scrlayer-scrpage}. Notwithstanding, this + chapter does contain some hints for using \Package{scrpage2}.}% + \fi +\end{Explain} + +In addition to \Package{scrlayer-scrpage}\iffree{ or \Package{scrpage2}}{}, +you could also use \Package{fancyhdr}\IndexPackage{fancyhdr} (see +\cite{package:fancyhdr}) to configure the headers and footers of pages. +However, this package has no support for several \KOMAScript{} features, +for example the element scheme (see \DescRef{\LabelBase.cmd.setkomafont}, +\DescRef{\LabelBase.cmd.addtokomafont}, and +\DescRef{\LabelBase.cmd.usekomafont} in \autoref{sec:maincls.textmarkup}, +\DescPageRef{maincls.cmd.setkomafont}) or the configurable numbering format +for dynamic headers (see the \DescRef{maincls.option.numbers} option and, +for example, \DescRef{\LabelBase.cmd.chaptermarkformat} in +\autoref{sec:maincls.structure}, \DescPageRef{maincls.option.numbers} and +\DescPageRef{maincls.cmd.chaptermarkformat}). Hence, if you are using a +\KOMAScript{} class, you should use the new \Package{scrlayer-scrpage} +package. \iffree{If you have problems, you can still use +\Package{scrpage2}.}{\ignorespaces} Of course, you can also use +\Package{scrlayer-scrpage} with other classes, such as the standard \LaTeX{} +ones. + +Apart from the features described in this chapter, \Package{scrlayer-scrpage} +provides several more functions that are likely only of interest to a very +small number of users and therefore are described in +\autoref{cha:scrlayer-scrpage-experts} of \autoref{part:forExperts}, starting +at \autopageref{cha:scrlayer-scrpage-experts}. Nevertheless, if the options +described in \autoref{part:forAuthors} are insufficient for your purposes, you +should examine \autoref{cha:scrlayer-scrpage-experts}. + +\LoadCommonFile{options} % \section{Early or late Selection of Options} + +\LoadCommonFile{headfootheight} % \section{Header and Footer Height} + +\LoadCommonFile{textmarkup} % \section{Text Markup} + +\section{Using Predefined Page Styles} +\seclabel{predefined.pagestyles} + +The easiest way to create custom headers and footers with +\Package{scrlayer-scrpage} is to use one of the predefined page styles. +% +\iffalse % Umbruchoptimierung + This section introduces the page styles defined by the + \Package{scrlayer-scrpage} package as it loads. It also explains the + commands that you can use to create basic settings for these page + styles. You can find further options, commands, and background information + in the following sections and in + \autoref{sec:scrlayer-scrpage-experts.pagestyle.pairs} in + \autoref{part:forExperts}.% +\fi + +\begin{Declaration} + \PageStyle{scrheadings}% + \PageStyle{plain.scrheadings} +\end{Declaration} +The \Package{scrlayer-scrpage} package provides two page styles that you can +reconfigure to your liking. The first page style is +\PageStyle{scrheadings}\important{\PageStyle{scrheadings}}, which is intended +as a page style with running heads. Its defaults are similar to the page style +\PageStyle{headings}\IndexPagestyle{headings} of the standard \LaTeX{} or +\KOMAScript{} classes. You can configure exactly what appears in the header or +footer with the commands and options described below. + +The second page style is \PageStyle{plain.scrheadings}% +\important{\PageStyle{plain.scrheadings}}, which is intended to be a style +with no running head. Its defaults resemble those of the +\PageStyle{plain}\IndexPagestyle{plain} page style of the standard or +\KOMAScript{} classes. You can configure exactly what appears in the header or +footer with the commands and options described below. + +You could, of course, configure \PageStyle{scrheadings} to be a page style +without a running head and \PageStyle{plain.scrheadings} to be a page style +with a running head. It is, however, advisable to adhere to the conventions +mentioned above. The two page styles mutually influence one another. Once you +apply one of these page styles, \PageStyle{scrheadings} will become accessible +as \PageStyle{headings}\important{\PageStyle{headings}}% +\IndexPagestyle{headings} and the page style \PageStyle{plain.scrheadings} +will become accessible as \PageStyle{plain}\important{\PageStyle{plain}}% +\IndexPagestyle{plain}. Thus, if you use a class or package that automatically +switches between \PageStyle{headings} and \PageStyle{plain}, you only need to +select \PageStyle{scrheadings} or \PageStyle{plain.scrheadings} once. Direct +patches to the corresponding classes or packages are not necessary. This pair +of page styles can thus serve as a drop-in replacement for +\PageStyle{headings} and \PageStyle{plain}. If you need more such pairs, +please refer to \autoref{sec:scrlayer-scrpage-experts.pagestyle.pairs} in +\autoref{part:forExperts}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{lehead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cehead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{rehead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{lohead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cohead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{rohead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content} +\end{Declaration} +You can set the contents of the header for the +\DescRef{\LabelBase.pagestyle.plain.scrheadings} and +\DescRef{\LabelBase.pagestyle.scrheadings} page styles with these commands. +The optional argument sets the content of an element of the +\DescRef{\LabelBase.pagestyle.plain.scrheadings} page style, while the +mandatory argument sets the content of the corresponding element of the +\DescRef{\LabelBase.pagestyle.scrheadings} page style. + +The contents of even\,---\,or left-hand\,---\,pages\textnote{left-hand pages} +can be set with \Macro{lehead}, \Macro{cehead}, and \Macro{rehead}. The +``\texttt{e}'' appearing as the second letter of the commands' names stands +for ``\emph{even}''. + +The contents of odd\,---\,or right-hand\,---\,pages\textnote{right-hand pages} +can be set with \Macro{lohead}, \Macro{cohead}, and \Macro{rohead}. The +``\texttt{o}'' appearing as the second letter of the commands' names stands +for ``\emph{odd}''. + +Note\textnote{Attention!} that in one-sided printing, only right-hand pages +exist, and \LaTeX{} designates these as odd pages regardless of their page +number. + +Each header consists of a left-aligned\textnote{left aligned} element that can +be set with \Macro{lehead} or \Macro{lohead}. The ``\texttt{l}'' appearing as +the first letter of the commands' names stands for ``\emph{left aligned}''. + +Similarly, each header has a centred\textnote{centred} element that can be set +with \Macro{cehead} or \Macro{cohead}. The ``\texttt{c}'' appearing as the +first letter of the command' names stands for ``\emph{centred}''. + +Likewise, each header has a right-aligned\textnote{right aligned} element that +can be set with \Macro{rehead} or \Macro{rohead}. The ``\texttt{r}'' appearing +as the first letter of the commands' names stands for ``\emph{right +aligned}''. + +\BeginIndexGroup +\BeginIndex{FontElement}{pagehead}\LabelFontElement{pagehead}% +\BeginIndex{FontElement}{pageheadfoot}\LabelFontElement{pageheadfoot}% +These elements do not have individual font attributes that you can +change using the commands \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} (see \autoref{sec:maincls.textmarkup}, +\DescPageRef{maincls.cmd.setkomafont}). Instead, they use an element named +\FontElement{pagehead}. Before this element is applied, the +\FontElement{pageheadfoot} element will also be applied. See +\autoref{tab:scrlayer-scrpage.fontelements} for the defaults of these +elements.% +\EndIndexGroup + +The meaning of each command for headers in two-sided printing is illustrated +in \autoref{fig:scrlayer-scrpage.head}.% +% +\begin{figure}[tp] + \centering + \begin{picture}(\textwidth,30mm)(0,-10mm) + \thinlines + \small\ttfamily + % left/even page + \put(0,20mm){\line(1,0){.49\textwidth}}% + \put(0,0){\line(0,1){20mm}}% + \multiput(0,0)(0,-1mm){10}{\line(0,-1){.5mm}}% + \put(.49\textwidth,5mm){\line(0,1){15mm}}% + \put(.05\textwidth,10mm){% + \color{ImageRed}% + \put(-.5em,0){\line(1,0){4em}}% + \multiput(3.5em,0)(.25em,0){5}{\line(1,0){.125em}}% + \put(-.5em,0){\line(0,1){\baselineskip}}% + \put(-.5em,\baselineskip){\line(1,0){4em}}% + \multiput(3.5em,\baselineskip)(.25em,0){5}{\line(1,0){.125em}}% + \makebox(4em,5mm)[l]{\Macro{lehead}}% + }% + \put(.465\textwidth,10mm){% + \color{ImageBlue}% + \put(-4em,0){\line(1,0){4em}}% + \multiput(-4em,0)(-.25em,0){5}{\line(1,0){.125em}}% + \put(0,0){\line(0,1){\baselineskip}}% + \put(-4em,\baselineskip){\line(1,0){4em}}% + \multiput(-4em,\baselineskip)(-.25em,0){5}{\line(1,0){.125em}}% + \put(-4.5em,0){\makebox(4em,5mm)[r]{\Macro{rehead}}}% + }% + \put(.2525\textwidth,10mm){% + \color{ImageGreen}% + \put(-2em,0){\line(1,0){4em}}% + \multiput(2em,0)(.25em,0){5}{\line(1,0){.125em}}% + \multiput(-2em,0)(-.25em,0){5}{\line(1,0){.125em}}% + \put(-2em,\baselineskip){\line(1,0){4em}}% + \multiput(2em,\baselineskip)(.25em,0){5}{\line(1,0){.125em}}% + \multiput(-2em,\baselineskip)(-.25em,0){5}{\line(1,0){.125em}}% + \put(-2em,0){\makebox(4em,5mm)[c]{\Macro{cehead}}}% + }% + % right/odd page + \put(.51\textwidth,20mm){\line(1,0){.49\textwidth}}% + \put(.51\textwidth,5mm){\line(0,1){15mm}}% + \put(\textwidth,0){\line(0,1){20mm}}% + \multiput(\textwidth,0)(0,-1mm){10}{\line(0,-1){.5mm}}% + \put(.5325\textwidth,10mm){% + \color{ImageBlue}% + \put(0,0){\line(1,0){4em}}% + \multiput(4em,0)(.25em,0){5}{\line(1,0){.125em}}% + \put(0,0){\line(0,1){\baselineskip}}% + \put(0em,\baselineskip){\line(1,0){4em}}% + \multiput(4em,\baselineskip)(.25em,0){5}{\line(1,0){.125em}}% + \put(.5em,0){\makebox(4em,5mm)[l]{\Macro{lohead}}}% + }% + \put(.965\textwidth,10mm){% + \color{ImageRed}% + \put(-4em,0){\line(1,0){4em}}% + \multiput(-4em,0)(-.25em,0){5}{\line(1,0){.125em}}% + \put(0,0){\line(0,1){\baselineskip}}% + \put(-4em,\baselineskip){\line(1,0){4em}}% + \multiput(-4em,\baselineskip)(-.25em,0){5}{\line(1,0){.125em}}% + \put(-4.5em,0){\makebox(4em,5mm)[r]{\Macro{rohead}}}% + }% + \put(.75\textwidth,10mm){% + \color{ImageGreen}% + \put(-2em,0){\line(1,0){4em}}% + \multiput(2em,0)(.25em,0){5}{\line(1,0){.125em}}% + \multiput(-2em,0)(-.25em,0){5}{\line(1,0){.125em}}% + \put(-2em,\baselineskip){\line(1,0){4em}}% + \multiput(2em,\baselineskip)(.25em,0){5}{\line(1,0){.125em}}% + \multiput(-2em,\baselineskip)(-.25em,0){5}{\line(1,0){.125em}}% + \put(-2em,0){\makebox(4em,5mm)[c]{\Macro{cohead}}}% + }% + % commands for both pages + \color{ImageBlue}% + \put(.5\textwidth,0){\makebox(0,\baselineskip)[c]{\Macro{ihead}}}% + \color{ImageGreen}% + \put(.5\textwidth,-5mm){\makebox(0,\baselineskip)[c]{\Macro{chead}}} + \color{ImageRed}% + \put(.5\textwidth,-10mm){\makebox(0,\baselineskip)[c]{\Macro{ohead}}} + \put(\dimexpr.5\textwidth-2em,.5\baselineskip){% + \color{ImageBlue}% + \put(0,0){\line(-1,0){1.5em}}% + \put(-1.5em,0){\vector(0,1){5mm}}% + \color{ImageGreen}% + \put(0,-1.25\baselineskip){\line(-1,0){\dimexpr .25\textwidth-2em\relax}}% + \put(-\dimexpr + .25\textwidth-2em\relax,-1.25\baselineskip){\vector(0,1){\dimexpr + 5mm+1.25\baselineskip\relax}} + \color{ImageRed}% + \put(0,-2.5\baselineskip){\line(-1,0){\dimexpr .45\textwidth-4em\relax}}% + \put(-\dimexpr + .45\textwidth-4em\relax,-2.5\baselineskip){\vector(0,1){\dimexpr + 5mm+2.5\baselineskip\relax}} + }% + \put(\dimexpr.5\textwidth+2em,.5\baselineskip){% + \color{ImageBlue}% + \put(0,0){\line(1,0){1.5em}}% + \put(1.5em,0){\vector(0,1){5mm}}% + \color{ImageGreen}% + \put(0,-1.25\baselineskip){\line(1,0){\dimexpr .25\textwidth-2em\relax}} + \put(\dimexpr + .25\textwidth-2em\relax,-1.25\baselineskip){\vector(0,1){\dimexpr + 5mm+1.25\baselineskip\relax}} + \color{ImageRed}% + \put(0,-2.5\baselineskip){\line(1,0){\dimexpr .45\textwidth-4em\relax}} + \put(\dimexpr + .45\textwidth-4em\relax,-2.5\baselineskip){\vector(0,1){\dimexpr + 5mm+2.5\baselineskip\relax}} + }% + \end{picture} + \caption[Commands for setting the page header]% + {The meaning of the commands for setting the contents of page headers + shown on a two-page schematic} + \label{fig:scrlayer-scrpage.head} +\end{figure} +% +\begin{Example} + Suppose you're writing a short article and you want the author's name to + appear on the left side of the page and the article's title to appear + right. You can write, for example: +\begin{lstcode} + \documentclass{scrartcl} + \usepackage{scrlayer-scrpage} + \lohead{John Doe} + \rohead{Page style with \KOMAScript} + \pagestyle{scrheadings} + \begin{document} + \title{Page styles with \KOMAScript} + \author{John Doe} + \maketitle + \end{document} +\end{lstcode} + But what happens? On the first page there's only a page number in the + footer, while the header remains empty! + + The explanation is simple: The \Class{scrartcl} class, like the default + \Class{article} class, switches to the \PageStyle{plain} page style for the + page which contains the title. After the command + \DescRef{maincls.cmd.pagestyle}\PParameter{scrheadings} in the preamble of + our example, this actually refers to the + \DescRef{\LabelBase.pagestyle.plain.scrheadings} page style. The default for + this page style when using a \KOMAScript{} class is an empty page header and + a page number in the footer. In the example, the optional arguments of + \Macro{lohead} and \Macro{rohead} are omitted, so the + \DescRef{\LabelBase.pagestyle.plain.scrheadings} page style remains + unchanged and the result for the first page is actually correct. + + Now add enough text to the example after \DescRef{maincls.cmd.maketitle} + so that a second page is printed. You can simply add + \Macro{usepackage}\PParameter{lipsum}\IndexPackage{lipsum} to the document + preamble and \Macro{lipsum}\IndexCmd{lipsum} below + \DescRef{maincls.cmd.maketitle}. You will see that the header of the second + page now contains the author and the document title as we wanted. + + For comparison, you should also add the optional argument to + \Macro{lohead} and \Macro{rohead}. Change the example as follows: +\begin{lstcode} + \documentclass{scrartcl} + \usepackage{scrlayer-scrpage} + \lohead[John Doe] + {John Doe} + \rohead[Page style with \KOMAScript] + {Page style with \KOMAScript} + \pagestyle{scrheadings} + \begin{document} + \title{Page styles with \KOMAScript} + \author{John Doe} + \maketitle + \end{document} +\end{lstcode} + Now you have a header on the first page just above the title itself. + That is because you have reconfigured page style + \DescRef{\LabelBase.pagestyle.plain.scrheadings} with the two optional + arguments. As you probably appreciate, it would be better to leave this page + style unchanged, as a running head above the document title is rather + annoying. + + By the way, as an alternative to configuring + \DescRef{\LabelBase.pagestyle.plain.scrheadings} you could, if you were + using a \KOMAScript{} class, have changed the page style for pages that + contain title headers. See \DescRef{maincls.cmd.titlepagestyle}% + \important{\DescRef{maincls.cmd.titlepagestyle}}% + \IndexCmd{titlepagestyle} in \autoref{sec:maincls.pagestyle}, + \DescPageRef{maincls.cmd.titlepagestyle}. +\end{Example} + +Note\textnote{Attention!} that you should never put a section +heading or section number directly into the header using one of these +commands. Because of the asynchronous way that \TeX{} lays out and outputs +pages, doing so can easily result in the wrong number or heading text in the +running head. Instead you should use the mark mechanism, ideally in +conjunction with the procedures explained in the next section.% +\EndIndexGroup + +\begin{Declaration} + \Macro{lehead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cehead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{rehead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{lohead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cohead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{rohead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content} +\end{Declaration} +The starred versions\ChangedAt{v3.14}{\Package{scrlayer-scrpage}} of the +previously described commands differ from the ordinary versions only if you +omit the optional argument \PName{plain.scrheadings content}. In this case, +the version without the star does not change the contents of +\DescRef{\LabelBase.pagestyle.plain.scrheadings}. The starred version, on the +other hand, uses the mandatory argument \PName{scrheading content} +for \DescRef{\LabelBase.pagestyle.plain.scrheadings} as well. So if both +arguments should be the same, you can simply use the starred version with only +the mandatory argument.% + +\begin{Example} + You can shorten the previous example using the starred versions of + \DescRef{\LabelBase.cmd.lohead} and \DescRef{\LabelBase.cmd.rohead}: +\begin{lstcode} + \documentclass{scrartcl} + \usepackage{scrlayer-scrpage} + \lohead*{John Doe} + \rohead*{Page style with \KOMAScript} + \pagestyle{scrheadings} + \begin{document} + \title{Page styles with \KOMAScript} + \author{John Doe} + \maketitle + \end{document} +\end{lstcode}% +\end{Example}% +\EndIndexGroup + + +\begin{Declaration} + \Macro{lefoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cefoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{refoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{lofoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cofoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{rofoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content} +\end{Declaration} +You can define the contents of the footer for +\DescRef{\LabelBase.pagestyle.scrheadings} and +\DescRef{\LabelBase.pagestyle.plain.scrheadings} with these commands. The +optional argument defines the content of an element of +\DescRef{\LabelBase.pagestyle.plain.scrheadings}, while the mandatory argument +sets the content of the corresponding element of +\DescRef{\LabelBase.pagestyle.scrheadings}. + +The contents of even\,---\,or left-hand\,---\,pages\textnote{left-hand page} +are set with \Macro{lefoot}, \Macro{cefoot}, and \Macro{refoot}. The +``\texttt{e}'' appearing as the second letter of the commands' names stands +for ``\emph{even}''. + +The contents of odd\,---\,or right-hand\,---\,pages\textnote{right-hand page} +are set with \Macro{lofoot}, \Macro{cofoot}, and \Macro{rofoot}. The +``\texttt{o}'' appearing as the second letter of the commands' names stands +for ``\emph{odd}''. + +Note\textnote{Attention!} that in one-sided printing, only right-hand pages +exist, and \LaTeX{} designates these as odd pages regardless of their page +number. + +Each footer consists of a left-aligned\textnote{left aligned} element that can +be set with \Macro{lefoot} or \Macro{lofoot}. The ``\texttt{l}'' appearing as +the first letter of the commands' names stands for ``\emph{left aligned}''. + +Similarly, each footer has a centred\textnote{centred} element that can be set +with \Macro{cefoot} or \Macro{cofoot}. The ``\texttt{c}'' in the first letter +of the command' names stands for ``\emph{centred}''. + +Likewise, each footer has a right-aligned\textnote{right aligned} element that +can be set with \Macro{refoot} or \Macro{rofoot}. The ``\texttt{r}'' in the +first letter of the commands' names stands for ``\emph{right aligned}''. + +\BeginIndexGroup +\BeginIndex{FontElement}{pagefoot}\LabelFontElement{pagefoot}% +\BeginIndex{FontElement}{pageheadfoot}\LabelFontElement[foot]{pageheadfoot}% +However, these elements do not have individual font attributes that can be +changed with the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see +\autoref{sec:maincls.textmarkup}, \DescPageRef{maincls.cmd.setkomafont}). +Instead, they use an element named +\FontElement{pagefoot}\important{\FontElement{pagefoot}}. Before this element +is applied, the font element +\FontElement{pageheadfoot}\important{\FontElement{pageheadfoot}} is also +applied. See \autoref{tab:scrlayer-scrpage.fontelements} for the defaults of +the fonts of these elements.% +\EndIndexGroup + +The meaning of each command for footers in two-sided printing is illustrated +in \autoref{fig:scrlayer-scrpage.foot}.% +% +\begin{figure}[bp] + \centering + \begin{picture}(\textwidth,30mm) + \thinlines + \small\ttfamily + % left page + \put(0,0){\line(1,0){.49\textwidth}}% + \put(0,0){\line(0,1){20mm}}% + \multiput(0,20mm)(0,1mm){10}{\line(0,1){.5mm}}% + \put(.49\textwidth,0){\line(0,1){15mm}}% + \put(.05\textwidth,5mm){% + \color{ImageRed}% + \put(-.5em,0){\line(1,0){4em}}% + \multiput(3.5em,0)(.25em,0){5}{\line(1,0){.125em}}% + \put(-.5em,0){\line(0,1){\baselineskip}}% + \put(-.5em,\baselineskip){\line(1,0){4em}}% + \multiput(3.5em,\baselineskip)(.25em,0){5}{\line(1,0){.125em}}% + \makebox(4em,5mm)[l]{\Macro{lefoot}}% + }% + \put(.465\textwidth,5mm){% + \color{ImageBlue}% + \put(-4em,0){\line(1,0){4em}}% + \multiput(-4em,0)(-.25em,0){5}{\line(1,0){.125em}}% + \put(0,0){\line(0,1){\baselineskip}}% + \put(-4em,\baselineskip){\line(1,0){4em}}% + \multiput(-4em,\baselineskip)(-.25em,0){5}{\line(1,0){.125em}}% + \put(-4.5em,0){\makebox(4em,5mm)[r]{\Macro{refoot}}}% + }% + \put(.2525\textwidth,5mm){% + \color{ImageGreen}% + \put(-2em,0){\line(1,0){4em}}% + \multiput(2em,0)(.25em,0){5}{\line(1,0){.125em}}% + \multiput(-2em,0)(-.25em,0){5}{\line(1,0){.125em}}% + \put(-2em,\baselineskip){\line(1,0){4em}}% + \multiput(2em,\baselineskip)(.25em,0){5}{\line(1,0){.125em}}% + \multiput(-2em,\baselineskip)(-.25em,0){5}{\line(1,0){.125em}}% + \put(-2em,0){\makebox(4em,5mm)[c]{\Macro{cefoot}}}% + }% + % right page + \put(.51\textwidth,0){\line(1,0){.49\textwidth}}% + \put(.51\textwidth,0){\line(0,1){15mm}}% + \put(\textwidth,0){\line(0,1){20mm}}% + \multiput(\textwidth,20mm)(0,1mm){10}{\line(0,1){.5mm}}% + \put(.5325\textwidth,5mm){% + \color{ImageBlue}% + \put(0,0){\line(1,0){4em}}% + \multiput(4em,0)(.25em,0){5}{\line(1,0){.125em}}% + \put(0,0){\line(0,1){\baselineskip}}% + \put(0em,\baselineskip){\line(1,0){4em}}% + \multiput(4em,\baselineskip)(.25em,0){5}{\line(1,0){.125em}}% + \put(.5em,0){\makebox(4em,5mm)[l]{\Macro{lofoot}}}% + }% + \put(.965\textwidth,5mm){% + \color{ImageRed}% + \put(-4em,0){\line(1,0){4em}}% + \multiput(-4em,0)(-.25em,0){5}{\line(1,0){.125em}}% + \put(0,0){\line(0,1){\baselineskip}}% + \put(-4em,\baselineskip){\line(1,0){4em}}% + \multiput(-4em,\baselineskip)(-.25em,0){5}{\line(1,0){.125em}}% + \put(-4.5em,0){\makebox(4em,5mm)[r]{\Macro{rofoot}}}% + }% + \put(.75\textwidth,5mm){% + \color{ImageGreen}% + \put(-2em,0){\line(1,0){4em}}% + \multiput(2em,0)(.25em,0){5}{\line(1,0){.125em}}% + \multiput(-2em,0)(-.25em,0){5}{\line(1,0){.125em}}% + \put(-2em,\baselineskip){\line(1,0){4em}}% + \multiput(2em,\baselineskip)(.25em,0){5}{\line(1,0){.125em}}% + \multiput(-2em,\baselineskip)(-.25em,0){5}{\line(1,0){.125em}}% + \put(-2em,0){\makebox(4em,5mm)[c]{\Macro{cofoot}}}% + }% + % both pages + \color{ImageBlue}% + \put(.5\textwidth,15mm){\makebox(0,\baselineskip)[c]{\Macro{ifoot}}}% + \color{ImageGreen}% + \put(.5\textwidth,20mm){\makebox(0,\baselineskip)[c]{\Macro{cfoot}}} + \color{ImageRed}% + \put(.5\textwidth,25mm){\makebox(0,\baselineskip)[c]{\Macro{ofoot}}} + \put(\dimexpr.5\textwidth-2em,.5\baselineskip){% + \color{ImageBlue}% + \put(0,15mm){\line(-1,0){1.5em}}% + \put(-1.5em,15mm){\vector(0,-1){5mm}}% + \color{ImageGreen}% + \put(0,20mm){\line(-1,0){\dimexpr .25\textwidth-2em\relax}}% + \put(-\dimexpr .25\textwidth-2em\relax,20mm){\vector(0,-1){10mm}}% + \color{ImageRed}% + \put(0,25mm){\line(-1,0){\dimexpr .45\textwidth-4em\relax}}% + \put(-\dimexpr .45\textwidth-4em\relax,25mm){\vector(0,-1){15mm}}% + }% + \put(\dimexpr.5\textwidth+2em,.5\baselineskip){% + \color{ImageBlue}% + \put(0,15mm){\line(1,0){1.5em}}% + \put(1.5em,15mm){\vector(0,-1){5mm}}% + \color{ImageGreen}% + \put(0,20mm){\line(1,0){\dimexpr .25\textwidth-2em\relax}}% + \put(\dimexpr .25\textwidth-2em\relax,20mm){\vector(0,-1){10mm}}% + \color{ImageRed}% + \put(0,25mm){\line(1,0){\dimexpr .45\textwidth-4em\relax}}% + \put(\dimexpr .45\textwidth-4em\relax,25mm){\vector(0,-1){15mm}}% + }% + \end{picture} + \caption[Commands for setting the page footer]% + {The meaning of the commands for setting the contents of page + footers shown on a two-page schematic}% + \label{fig:scrlayer-scrpage.foot} +\end{figure} +% +\begin{Example} + Let's return to the example of the short article. Let's say you want to + specify the publisher in the left side of the footer. You would change the + example above to: +\begin{lstcode} + \documentclass{scrartcl} + \usepackage{scrlayer-scrpage} + \lohead{John Doe} + \rohead{Page style with \KOMAScript} + \lofoot{Smart Alec Publishing} + \pagestyle{scrheadings} + \usepackage{lipsum} + \begin{document} + \title{Page styles with \KOMAScript} + \author{John Doe} + \maketitle + \lipsum + \end{document} +\end{lstcode} + Once again the publisher is not printed on the first page with the title. + The reason is the same as in the example with + \DescRef{\LabelBase.cmd.lohead} above. And the solution for getting the + publisher on the first page is similar: +\begin{lstcode} + \lofoot[Smart Alec Publishing] + {Smart Alec Publishing} +\end{lstcode} + Now you decide\textnote{font change}\important{\FontElement{pageheadfoot}}% + \IndexFontElement{pageheadfoot} that the header and footer should use an + upright but smaller font in place of the default slanted font: +\begin{lstcode} + \setkomafont{pageheadfoot}{\small} +\end{lstcode} + In addition, the header, but not the footer, should be bold: +\begin{lstcode} + \setkomafont{pagehead}{\bfseries} +\end{lstcode} + It is important\textnote{Attention!} that this command does not occur until + after \Package{scrpage-scrlayer} has been loaded because the \KOMAScript{} + class defines \DescRef{\LabelBase.fontelement.pagehead} as an alias for + \DescRef{\LabelBase.fontelement.pageheadfoot}. Only by loading + \Package{scrpage-scrlayer} will \DescRef{\LabelBase.fontelement.pagehead} + become an element independent of + \DescRef{\LabelBase.fontelement.pageheadfoot}. + + Now add one more \Macro{lipsum} and the + \Option{twoside}\IndexOption{twoside}\important{\Option{twoside}} option + when loading \Class{scrartcl}. First of all, you will see the page number + moves from the centre to the outer margin of the page footer, due to the + changed defaults of \DescRef{\LabelBase.pagestyle.scrheadings} and + \DescRef{\LabelBase.pagestyle.plain.scrheadings} for two-sided printing with + a \KOMAScript{} class. + + Simultaneously, the author, document title, and publisher will vanish from + page~2. They only appear on page~3. That's because we've only used + commands for odd pages. You can recognise this by the ``\texttt{o}'' in the + second position of the command names. + + Now, we could simply copy those commands and replace the ``\texttt{o}'' with + an ``\texttt{e}'' to define the contents of \emph{even} pages. But with + two-sided printing, it makes more sense to use mirror-inverted elements, + i.\,e. the left element of an even page should become the right element of + the odd page and visa versa. To achieve this, we also replace the first + letter ``\texttt{l}'' with ``\texttt{r}'': +\begin{lstcode} + \documentclass[twoside]{scrartcl} + \usepackage{scrlayer-scrpage} + \lohead{John Doe} + \rohead{Page style with \KOMAScript} + \lofoot[Smart Alec Publishing] + {Smart Alec Publishing} + \rehead{John Doe} + \lohead{Page style with \KOMAScript} + \refoot[Smart Alec Publishing] + {Smart Alec Publishing} + \pagestyle{scrheadings} + \usepackage{lipsum} + \begin{document} + \title{Page styles with \KOMAScript} + \author{John Doe} + \maketitle + \lipsum\lipsum + \end{document} +\end{lstcode} +\end{Example} +% +Since it is a bit cumbersome to define left and right pages separately in +cases such as the previous example, a simpler solution for this common case is +introduced below. + +Allow me once again an important note:\textnote{Attention!} you should +never put a section heading or section number directly into the footer using +one of these commands. Because of the asynchronous way that \TeX{} lays out and +outputs pages, doing so can easily result in the wrong number or heading text +in the running head. Instead you should use the mark mechanism, ideally in +conjunction with the procedures explained in the next section.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{lefoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cefoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{refoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{lofoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cofoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{rofoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content} +\end{Declaration} +The starred versions\ChangedAt{v3.14}{\Package{scrlayer-scrpage}} of the +previously described commands differ only if you omit the optional argument +\OParameter{plain.scrheadings content}. In this case, the version without the +star does not change the contents of +\DescRef{\LabelBase.pagestyle.plain.scrheadings}. The starred version, on the +other hand, uses the mandatory argument \PName{scrheading content} for +\DescRef{\LabelBase.pagestyle.plain.scrheadings} as well. So if both arguments +should be the same, you can simply use the starred version with just the +mandatory argument.% + +\begin{Example} + You can shorten the previous example using the star versions of + \DescRef{\LabelBase.cmd.lofoot} and \DescRef{\LabelBase.cmd.refoot}: +\begin{lstcode} + \documentclass[twoside]{scrartcl} + \usepackage{scrlayer-scrpage} + \lohead{John Doe} + \rohead{Page style with \KOMAScript} + \lofoot*{Smart Alec Publishing} + \rehead{John Doe} + \lohead{Page style with \KOMAScript} + \refoot*{Smart Alec Publishing} + \pagestyle{scrheadings} + \usepackage{lipsum} + \begin{document} + \title{Page styles with \KOMAScript} + \author{John Doe} + \maketitle + \lipsum\lipsum + \end{document} +\end{lstcode} +\end{Example} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ohead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{chead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{ihead}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{ofoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cfoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{ifoot}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content} +\end{Declaration} +To configure the headers and footers for two-sided printing with the +previously described commands, you would have to configure the left and right +sides separately from one another. In most cases, however, the left and right +sides are more or less symmetrical. An item that appears on the left of an +even page should appear on the right of an odd page and vice versa. Centred +elements are usually centred on both sides. + +To simplify the definition of such symmetric page styles, +\Package{scrlayer-scrpage} has shortcuts. The \Macro{ohead} command +corresponds to a call to both \DescRef{\LabelBase.cmd.lehead} and +\DescRef{\LabelBase.cmd.rohead}. The \Macro{chead} command corresponds to a +call to both \DescRef{\LabelBase.cmd.cehead} and +\DescRef{\LabelBase.cmd.cohead}. And the \Macro{ihead} command corresponds to +a call to both \DescRef{\LabelBase.cmd.rehead} and +\DescRef{\LabelBase.cmd.lohead}. The same applies to the equivalent commands +for the page footer. An outline of these relationships can also be found in +\autoref{fig:scrlayer-scrpage.head} on \autopageref{fig:scrlayer-scrpage.head} +and \autoref{fig:scrlayer-scrpage.foot} on +\autopageref{fig:scrlayer-scrpage.foot}. +% +\begin{Example} + You can simplify the previous example using the new commands: +\begin{lstcode} + \documentclass[twoside]{scrartcl} + \usepackage{scrlayer-scrpage} + \ihead{John Doe} + \ohead{Page style with \KOMAScript} + \ifoot[Smart Alec Publishing] + {Smart Alec Publishing} + \pagestyle{scrheadings} + \usepackage{lipsum} + \begin{document} + \title{Page styles with \KOMAScript} + \author{John Doe} + \maketitle + \lipsum\lipsum + \end{document} +\end{lstcode} +\iffalse% + As you can see, you can use half the number of commands but get the same + result. % +\fi% +\end{Example}% +Because one-sided printing treats all pages as odd pages, these commands are +synonymous with the corresponding right-side commands when in one-sided mode. +Therefore in most cases you will only need these six commands instead of the +twelve described before. + +Allow me once again an important note:\textnote{Attention!} you should never +put a section heading or section number directly into the footer using one of +these commands. Because of the asynchronous way that \TeX{} lays out and +outputs pages, doing so can easily result in the wrong number or heading text +in the running head. Instead you should use the mark mechanism, ideally in +conjunction with the procedures explained in the next section.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ohead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{chead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{ihead*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{ofoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{cfoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content}% + \Macro{ifoot*}\OParameter{plain.scrheadings content}% + \Parameter{scrheadings content} +\end{Declaration} +The previously described commands also have starred +versions\ChangedAt{v3.14}{\Package{scrlayer-scrpage}} that differ only if you +omit the optional argument \OParameter{plain.scrheadings content}. In this +case, the version without a star does not change the content of +\DescRef{\LabelBase.pagestyle.plain.scrheadings}. The version with the star, +on the other hand, also uses the mandatory argument \PName{scrheadings +content} for \DescRef{\LabelBase.pagestyle.plain.scrheadings}. So if both +arguments should be the same, you can simply use the starred version with only +the mandatory argument.% + +\begin{Example} + You can shorten the previous example using the star version of + \DescRef{\LabelBase.cmd.ifoot}: +\begin{lstcode} + \documentclass[twoside]{scrartcl} + \usepackage{scrlayer-scrpage} + \ihead{John Doe} + \ohead{Page style with \KOMAScript} + \ifoot*{Smart Alec Publishing} + \pagestyle{scrheadings} + \usepackage{lipsum} + \begin{document} + \title{Page styles with \KOMAScript} + \author{John Doe} + \maketitle + \lipsum\lipsum + \end{document} +\end{lstcode}% +\end{Example}% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{pagestyleset}{setting} +\end{Declaration} +\BeginIndex{Option}{pagestyleset~=KOMA-Script}% +\BeginIndex{Option}{pagestyleset~=standard}% +The examples above refer several times to the default settings of the page +styles \DescRef{\LabelBase.pagestyle.scrheadings}\IndexPagestyle{scrheadings} +and \DescRef{\LabelBase.pagestyle.plain.scrheadings}% +\IndexPagestyle{plain.scrheadings}. In fact, \Package{scrlayer-scrpage} +currently provides two different defaults for these page styles. You can +select them manually with the \Option{pagestyleset} option. + +The +\PValue{KOMA-Script}\important{\OptionValue{pagestyleset}{KOMA-Script}} +\PName{setting} selects the defaults, which are also set automatically if the +option is not specified and a \KOMAScript{} class is detected. In two-sided +printing, \DescRef{\LabelBase.pagestyle.scrheadings} uses outer-aligned +running heads in the header and outer-aligned page numbers in the footer. +In one-sided printing, the running head will be printed in the +middle of the header and the page number in the middle of the footer. Upper- +and lower-case letters are used in the automatic running heads as they +actually appear in the sectioning headings. This corresponds to the +\OptionValueRef{\LabelBase}{markcase}{used}\IndexOption{markcase~=used}% +\important{\OptionValueRef{\LabelBase}{markcase}{used}} option. The +\DescRef{\LabelBase.pagestyle.plain.scrheadings} page style has no running +heads, but the page numbers are printed in the same manner. + +However, if the \hyperref[cha:scrlttr2]{\Class{scrlttr2}}% +\important{\hyperref[cha:scrlttr2]{\Class{scrlttr2}}}% +\IndexClass{scrlttr2} class is detected, the default settings are based on the +page styles of that class. See \autoref{sec:scrlttr2.pagestyle}, +\autopageref{sec:scrlttr2.pagestyle}. + +The +\PValue{standard}\important{\OptionValue{pagestyleset}{standard}} +\PName{setting} selects defaults that match the page styles of the standard +classes. This is also activated automatically if the option has not been +specified and no \KOMAScript{} class is detected. In this case, for two-sided +printing \DescRef{\LabelBase.pagestyle.scrheadings} uses running heads +inner-aligned in the header, and the page numbers will be printed\,---\,also +in the header\,---\,outer-aligned. One-sided printing uses the same settings, +but since only right-hand pages exist in this mode, the running head will +always be left-aligned and the page number right-aligned. The automatic +running heads\,---\,despite considerable typographic objections\,---\,are +converted to capital letters, as they would be with +\OptionValueRef{\LabelBase}{markcase}{upper}\IndexOption{markcase~=upper}% +\important{\OptionValueRef{\LabelBase}{markcase}{upper}}. In one-sided +printing, the \DescRef{\LabelBase.pagestyle.plain.scrheadings} page style +differs considerably from \DescRef{\LabelBase.pagestyle.scrheadings} because +the page number is printed in the middle of the footer. +Unlike\textnote{\KOMAScript{} vs. standard classes} the \PageStyle{plain} page +style in the standard classes, +\DescRef{\LabelBase.pagestyle.plain.scrheadings} omits the page number in +two-sided printing. The standard classes print the page number in the middle +of the footer, which does not match the rest of the page styles in two-sided +printing. +\iffalse % Umbruchkorrekturtext + If you want the page number back +\begin{lstcode} + \cfoot[\pagemark]{} +\end{lstcode} + will restore it. % +\fi% +The running head is omitted in \DescRef{\LabelBase.pagestyle.plain.scrheadings}. + +Note\textnote{Attention!} that using this option activates the +\DescRef{\LabelBase.pagestyle.scrheadings}\IndexPagestyle{scrheadings}% +\important{\DescRef{\LabelBase.pagestyle.scrheadings}} page style. +\iffalse% Umbruchkorrektur + This also applies if you use the option within the document.% +\fi +% +\EndIndexGroup + + +\LoadCommonFile{pagestylemanipulation} % \section{Manipulating Defined Page Styles} + +\begin{Declaration} + \OptionVName{headwidth}{width\textup{:}offset\textup{:}offset}% + \OptionVName{footwidth}{width\textup{:}offset\textup{:}offset} +\end{Declaration} +By default the header\Index{header>width} and footer\Index{footer>width} are +as wide as the type area. However, you can change this using these +\KOMAScript{} options. The value \PName{width} is the desired width of the +header or footer. The \PName{offset} defines how far the header or footer +should be moved towards the outer\,---\,in one-sided printing to the +right\,---\,margin. All three\ChangedAt{v3.14}{\Package{scrlayer-scrpage}} +values are optional and can be omitted. If you omit a value, you can also omit +the associated colon to the left of it. If only one \PName{offset} is +specified, it is used for both odd and even pages. Otherwise, the first +\PName{offset} is used for odd and the second \PName{offset} for even pages in +two-sided mode. If you only use one value without a colon, this will be the +\PName{width}. + +For both the \PName{width} and the \PName{offset} you can use any valid length +value, \LaTeX{} length, \TeX{} dimension, or \TeX{} skip. In addition, you can +use an \eTeX{} dimension expression with the basic arithmetic operations +\texttt{+}, \texttt{-}, \texttt{*}, \texttt{/}, and parentheses. See +\cite[section~3.5]{manual:eTeX} for more information on such expressions. See +\autoref{sec:scrlayer-scrpage.options} for more information on using a +\LaTeX{} length as an option value. The \PName{width} can also be one of the +symbolic values shown in \autoref{tab:scrlayer-scrpage.symbolic.values}. + +By default the header and the footer are the width of the text area. The +default \PName{offset} depends on the selected \PName{width}. One-sided +printing typically uses half the difference between \PName{width} and the +width of the text area. This centres the header horizontally above the text +area. Two-sided printing, on the other hand, uses only a third of the +difference between \PName{width} and the width of the text area. However, if +\PName{width} is the width of the whole text area and the marginal note +column, the default \PName{offset} will be zero. If this is too complicated +for you, you should simply specify the desired \PName{offset} yourself. +% +\begin{table} + \centering + \caption[Symbolic values for the \Option{headwidth} and \Option{footwidth} + options]{Available symbolic values for the \PName{width} value of options + \Option{headwidth} and \Option{footwidth}} + \label{tab:scrlayer-scrpage.symbolic.values} + \begin{desctabular} + \entry{\PValue{foot}}{% + the current width of the footer% + }% + \entry{\PValue{footbotline}}{% + the current length of the horizontal line below the footer% + }% + \entry{\PValue{footsepline}}{% + the current length of the horizontal line above the footer% + } \entry{\PValue{head}}{% + the current width of the header% + }% + \entry{\PValue{headsepline}}{% + the current length of the horizontal line below the header% + }% + \entry{\PValue{headtopline}}{% + the current length of the horizontal line above the header% + }% + \entry{\PValue{marginpar}}{% + the width of the marginal note column including the distance + between the text area and the marginal note column% + }% + \entry{\PValue{page}}{% + the width of the page taking into account any binding correction defined + with the help of the \Package{typearea} package (see the + \DescRef{typearea.option.BCOR} option in + \autoref{sec:typearea.typearea}, \DescPageRef{typearea.option.BCOR})% + }% + \entry{\PValue{paper}}{% + the width of the paper without considering any binding correction% + }% + \entry{\PValue{text}}{% + the width of the text area% + }% + \entry{\PValue{textwithmarginpar}}{% + the width of the text area including the marginal note column and + the distance between the two (Note: only in this case is + the default for \PName{offset} zero)% + }% + \end{desctabular} +\end{table} +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{headtopline}{thickness\textup{:}length}% + \OptionVName{headsepline}{thickness\textup{:}length}% + \OptionVName{footsepline}{thickness\textup{:}length}% + \OptionVName{footbotline}{thickness\textup{:}length} +\end{Declaration} +\BeginIndex{Option}{headtopline~=\PName{thickness\textup{:}length}}% +\BeginIndex{Option}{headsepline~=\PName{thickness\textup{:}length}}% +\BeginIndex{Option}{footsepline~=\PName{thickness\textup{:}length}}% +\BeginIndex{Option}{footbotline~=\PName{thickness\textup{:}length}}% +The \KOMAScript{} classes provide only one separation line below the header +and another above the footer, and you can only switch these lines on or off. +But the \Package{scrlayer-scrpage} package also lets you place lines above the +header and below the footer. And for all four lines, you can not only switch +them on an off but also configure their \PName{length} and \PName{thickness}. + +Both values are optional. If you omit the \PName{thickness}, a default value +of 0.4\Unit{pt} is used, producing a so-called \emph{hairline}. If you omit +the \PName{length}, the width of the header or footer will be used. If you +omit both, you can also omit the colon. If you use only one value without +colon, this is the \PName{thickness}. + +Of course, the \PName{length} can be not just shorter than the current width +of the header or footer but also longer. See also the options +\DescRef{\LabelBase.option.ilines}\IndexOption{ilines}% +\important{\DescRef{\LabelBase.option.ilines}, +\DescRef{\LabelBase.option.clines}, \DescRef{\LabelBase.option.olines}}, +\DescRef{\LabelBase.option.clines}\IndexOption{clines} and +\DescRef{\LabelBase.option.olines}\IndexOption{olines} later in this section. + +\BeginIndexGroup +\BeginIndex{FontElement}{headtopline}\LabelFontElement{headtopline}% +\BeginIndex{FontElement}{headsepline}\LabelFontElement{headsepline}% +\BeginIndex{FontElement}{footsepline}\LabelFontElement{footsepline}% +\BeginIndex{FontElement}{footbotline}\LabelFontElement{footbotline}% +In addition to the length and thickness, you can also change the colour of the +lines. Initially the colour depends on the colour of the header or footer. In +addition to this, however, the settings of the corresponding elements +\important[i]{\FontElement{headtopline}\\ + \FontElement{headsepline}\\ + \FontElement{footsepline}\\ + \FontElement{footbotline}} \FontElement{headtopline}, +\FontElement{headsepline}, \FontElement{footsepline} and +\FontElement{footbotline} are applied. You can +change these using the \DescRef{\LabelBase.cmd.setkomafont} or +\DescRef{\LabelBase.cmd.addtokomafont} commands (see +\autoref{sec:maincls.textmarkup}, \DescPageRef{maincls.cmd.setkomafont}). +By default these elements are empty, so they do not change the current font or +colour. Font changes at this point, unlike colour changes, make little sense +anyway and are therefore not recommended for these elements.% +\EndIndexGroup +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{plainheadtopline}{simple switch}% + \OptionVName{plainheadsepline}{simple switch}% + \OptionVName{plainfootsepline}{simple switch}% + \OptionVName{plainfootbotline}{simple switch} +\end{Declaration} +You can use these options to apply the settings for the lines to the +\PageStyle{plain} page style. You can find the available values for +\PName{simple switch} in \autoref{tab:truefalseswitch} on +\autopageref{tab:truefalseswitch}. If one of these options is activated, the +\PageStyle{plain} page style will use the line settings given by the options +and commands described above. If the option is deactivated, the +\PageStyle{plain} will not show the corresponding line.% +\EndIndexGroup + + +\begin{Declaration} + \Option{ilines}% + \Option{clines}% + \Option{olines} +\end{Declaration} +As previously explained, dividing lines for the header or footer can be longer +or shorter than the width of the header or footer respectively. But the +question remains how these lines are aligned. By default, all lines are +aligned to the left margin in one-sided printing and to the inner margin in +two-sided printing. This corresponds to using the \Option{ilines} option. +Alternatively, you can use the \Option{clines} option to centre the lines with +respect to the width of the header or footer, or the \Option{olines} option to +align them to the outer (or right) margin.% +\EndIndexGroup +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrlayer.tex b/macros/latex/contrib/koma-script/source-doc/english/scrlayer.tex new file mode 100644 index 0000000000..5488fe2cb0 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrlayer.tex @@ -0,0 +1,1596 @@ +% ====================================================================== +% scrlayer.tex +% Copyright (c) Markus Kohm, 2013-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrlayer.tex +% Copyright (c) Markus Kohm, 2013-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrlayer of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber scrlayer in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrlayer.tex} + [$Date: 2018-12-15 15:01:34 +0100 (Sat, 15 Dec 2018) $ + KOMA-Script guide (chapter:scrlayer)] + +\translator{Markus Kohm\and Karl Hagen} + +% Date of the translated German file: 2018-12-15 + +\chapter[{Defining Layers and Page Styles with \Package{scrlayer}}] + {Defining\ChangedAt{v3.12}{\Package{scrlayer}} Layers and Page Styles with + \Package{scrlayer}} +\labelbase{scrlayer} + +\BeginIndexGroup +\BeginIndex{Package}{scrlayer}% +\BeginIndex{}{layer}% +Most users of graphics software are already familiar with the layer model for +a page. Such a model is rather alien to \LaTeX{} itself, but some packages, +like \Package{eso-pic} or \Package{textpos}, provide a kind of +background or foreground layer. \Package{scrlayer} is another package that +provides such background and foreground layers, but unlike the packages +mentioned above, these layers are part of the page style. As a result, you can +switch between different layers simply by switching the page style. + +To do so, the package also supports a low-level interface for defining page +styles that are based on a stack or list of layers, for adding layers to such +a layer stack, either at the top or the bottom, or before or after a specific +layer, and for removing individual layers and duplicates from a stack. In a +nutshell, the page style interface of \Package{scrlayer} provides commands to +define page styles based on a stack of layers and to manage those stacks. + +Nevertheless, using the layers directly is recommended for advanced users +only. Interfaces for beginners and average users are provided by additional +packages that in turn load \Package{scrlayer}. See +\autoref{cha:scrlayer-scrpage} in \autoref{part:forAuthors} of this +\iffree{manual}{book}. + + +\LoadCommonFile{options} % \section{Early or Late Selection of Options} + +\section{Generic Information} +\seclabel{generic.information} + +The package needs some generic information about the class being used. Class +authors can help \Package{scrlayer} by providing the appropriate information. +Otherwise the package will try to determine this information for itself. This +works, for example, for the standard and the \KOMAScript{} classes. It may +work with other classes, or it may fail in whole or in part. + +This section describes some of the information that class authors can provide. +Normally, users should not have to worry about it. + +\begin{Declaration} + \Macro{if@chapter}\ \PName{then code}\ \textMacro{else}\ % + \PName{else code}\ \textMacro{fi}% +\end{Declaration} +If \Macro{if@chapter} is defined and corresponds to +\Macro{iftrue}\IndexCmd{iftrue}, \Package{scrlayer} takes the chapter level +into account when, for example, processing the +\DescRef{\LabelBase.option.automark} option. If it is defined but is not +\Macro{iftrue}, \Package{scrlayer} handles only the +\DescRef{maincls.cmd.part}, \DescRef{maincls.cmd.section}, +\DescRef{maincls.cmd.subsection}, \Macro{sub\dots subsection}, +\DescRef{maincls.cmd.paragraph}, \DescRef{maincls.cmd.subparagraph}, +\Macro{sub\dots subparagraph} sectioning units. If the macro is undefined, +\Package{scrlayer} searches for \DescRef{maincls.cmd.chapter}. If +\DescRef{maincls.cmd.chapter} is defined and does not correspond to +\Macro{relax}, \Package{scrlayer} defines \Macro{if@chapter} to +\Macro{iftrue}. Otherwise \Macro{if@chapter} becomes +\Macro{iffalse}\IndexCmd{iffalse}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{if@mainmatter}\ \PName{then code}\ % + \textMacro{else}\ \PName{else code}\ \textMacro{fi}% +\end{Declaration} +Classes like \Class{book} or \Class{scrbook} provide +\DescRef{maincls.cmd.frontmatter}\IndexCmd{frontmatter}, +\DescRef{maincls.cmd.mainmatter}\IndexCmd{mainmatter}, and +\DescRef{maincls.cmd.backmatter}\IndexCmd{backmatter} to switch between the +front, main, and end parts of a book. Typically, these classes also use +\Macro{if@mainmatter} internally to decide whether the current text is part of +the main body of the document or not. Classes like \Class{report} and +\Class{article} have no \DescRef{maincls.cmd.frontmatter}, +\DescRef{maincls.cmd.mainmatter}, or \DescRef{maincls.cmd.backmatter} and +therefore also lack \Macro{if@mainmatter}. + +It is easier for \Package{scrlayer} to avoid constantly testing for the +existence of these commands to decide whether to work in the main matter or +not, and instead to use \Macro{if@mainmatter}\IndexCmd{iftrue} with classes +like \Class{report} and \Class{article}. So if \Macro{if@mainmatter} is not +defined, \Package{scrlayer} defines it as a synonym for \Macro{iftrue}. + +Some classes, however, define \DescRef{maincls.cmd.frontmatter}, +\DescRef{maincls.cmd.mainmatter}, or \DescRef{maincls.cmd.backmatter} but not +\Macro{if@mainmatter}. In this case, \Package{scrlayer} also defines +\Macro{if@mainmatter} to be \Macro{iftrue} and it extends definition of +\DescRef{maincls.cmd.frontmatter}, \DescRef{maincls.cmd.mainmatter}, and +\DescRef{maincls.cmd.backmatter} to set \Macro{if@mainmatter} properly. +However, if there are other, comparable commands for switching between +different document parts. \Package{scrlayer} will not recognize them, does not +test for them, and therefore cannot extend them appropriately. In this case, +\Package{scrlayer} needs help of the class author to set \Macro{if@mainmatter} +correctly.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DeclareSectionNumberDepth}\Parameter{level name}% + \Parameter{level depth} +\end{Declaration} +Generally each section level is assigned an integer number indicating its +depth in the document structure. \LaTeX{} needs this to manage the hierarchy +of the section levels. But normally these values are known only to the +particular class that defines the section commands. This class then uses the +appropriate numbers inside the corresponding commands. + +The \Package{scrlayer} package also needs information about the section +hierarchy. With the help of \Macro{DeclareSectionNumberDepth}, you can map the +name of a heading level to a corresponding \PName{level depth}. For example, +for the standard \Class{book} class, the \PName{level name}s would be +\PValue{part}, \PValue{chapter}, \PValue{section}, \PValue{subsection}, +\PValue{subsubsection}, \PValue{paragraph}, and \PValue{subparagraph}, and the +corresponding \PName{level depth}s would be -1, 0, 1, 2, 3, 4, and 5. + +The \Package{scrlayer} package tries to determine the \PName{level depth}s on +its own while loading and again during \Macro{begin}\PParameter{document}. But +if this fails, for example because you use completely different sectioning +commands, you can define the relationship explicitly with +\Macro{DeclareSectionNumberDepth}.% +\EndIndexGroup + + +\section{Declaring Layers} +\seclabel{layers} + +A layer is an abstract model of a page. Unlike a real, physical sheet of +paper, this page is completely transparent. Typically, multiple layers are +stacked atop one another and opaque material on one layer hides material on +the layers below. The stack of layers is then merged to form the physical +page. The \Package{scrlayer} package provides two such stacks for each page: a +background stack and a foreground stack. The background stack is printed +beneath the normal page content, while the foreground stack is printed above +it. The normal page content is therefore a kind of a dividing layer between +the two layer stacks. + +A layer has several attributes that can be understood as answers to some basic +questions: +\iffree{\begin{description}}{% + \begingroup + \RedeclareSectionCommand[beforeskip=.5\baselineskip plus .25\baselineskip + minus .1\baselineskip]{paragraph}% + \renewcommand*\item[4][]{\paragraph*{#3{#4}#1}}% + }% +\item[Does the layer belong to the foreground or the background?]% + \leavevmode\textnote{foreground or background}\hskip 0pt + Background layers are output before the normal content of the page. + Therefore they appear behind or beneath the normal content of the page. + Foreground layers are then output after the normal content. Therefore they + appear on top of the normal content of the page. By default, a layer is both + a background layer \emph{and} a foreground layer and therefore is printed + twice. Usually it makes sense to limit the layer explicitly to either the + foreground or the background. +\item[What is the position of the layer?]% + \leavevmode\textnote{horizontal and vertical position}\hskip 0pt + To answer this question, there are attributes to define the layer's + horizontal and vertical position. +\item[How big is the layer?\textnote{horizontal and vertical size}]% + As with the position, there are also attributes to define the width and + height of a layer. Thus a layer can be smaller or larger than the paper + and it can be placed at different positions on the paper. +\item[How are the horizontal and vertical positions measured?]% + \leavevmode\textnote{alignment}\hskip 0pt + This question is answered by the alignment attribute. The horizontal + position can be measured from the left edge of the paper to the left edge of + the layer, to the centre of the layer, to the right edge of the layer. + Similarly, the vertical position can be measured from the top edge of the + paper to the top edge of the layer, the centre of the layer, or the bottom + edge of the layer. +\item[Is the layer intended for text or picture output?]% + \leavevmode\textnote{text or picture}\hskip 0pt + This question is closely related to the position. For example, users often + expect the origin for a picture to be at the lower left corner of the layer. + But this would not be suitable for text output. Therefore the origin of a + text layer is the height of a standard text line below the top left corner + of the layer. Picture layers, on the other hand, create a + \Environment{picture}\IndexEnv{picture} environment in which additional + positioning commands are available. +\item[Should the layer be printed on left or right pages?]% + \leavevmode\textnote{left or right page}\hskip 0pt + By default a layer will be printed on all pages. Note that \LaTeX{} treats + even pages as left-side pages and odd pages as right-side pages, but in + one-sided printing, only right-hand pages exist regardless of the page + number. +\item[Should the layer be printed in one-sided or two-sided mode?]% + \leavevmode\textnote{one-sided or two-sided}\hskip 0pt + By default a layer will be printed in both one-sided and two-sided + printing. Nonetheless, a layer that is restricted to even pages will never + be printed in one-sided printing and therefore is not a one-sided layer. +\item[Should the layer be printed on float pages or normal pages?]% + \leavevmode\textnote{float page or normal page}\hskip 0pt + \LaTeX{} produces float pages for objects from environments like tables or + figures if they are allowed to appear on a page without normal page contents + (see option \PValue{p} for \Environment{figure} or \Environment{table}). In + effect, the entire page is allowed to float within the document. Normal + pages in this sense are all pages that are not float pages. Normal pages can + also contain floats at the top, in the middle, or at the bottom of the page. + Very large floats can give the impression of being page floats, while in + reality they are floating environments placed at the top of a normal page. +\item[What are the contents of the layer?]% + \leavevmode\textnote{contents}\hskip 0pt + The corresponding attribute simply contains what should be printed whenever + the layer is output. +\iffree{\end{description}}{% + \endgroup\par\bigskip\noindent\ignorespaces +}% +These eight questions immediately give rise to a number of attributes. Later +\iffree{in this guide}, we will describe additional attributes. However, they +are only defined for convenience and can be expressed by a combination of +these primary attributes. + + +\begin{Declaration} + \Macro{DeclareLayer}\OParameter{option list}\Parameter{layer name}% + \Macro{DeclareNewLayer}\OParameter{option list}\Parameter{layer name}% + \Macro{ProvideLayer}\OParameter{option list}\Parameter{layer name}% + \Macro{RedeclareLayer}\OParameter{option list}\Parameter{layer name}% + \Macro{ModifyLayer}\OParameter{option list}\Parameter{layer name} +\end{Declaration} +These commands can be used to define layers. The \PName{layer name} must be +fully expandable and should expand to ASCII letters only. Some additional +characters are accepted, but their use is only recommended for advanced users. + +The \Macro{DeclareLayer} command does not care whether or not a layer with the +given \PName{layer name} already exists. It will under all circumstances +define the layer with the attributes specified in the \PName{option list}. An +\PName{option} can be either a key or a key followed by an equal sign and +a value. Multiple options are separated by commas. To use a comma or a white +space within the value of an option, you must put the value inside curly +brackets. See \autoref{tab:scrlayer.layerkeys} for more information on keys, +values, and the corresponding attributes. + +Unlike \Macro{DeclareLayer}, \Macro{DeclareNewLayer} reports an error if a +layer with the same \PName{layer name} already exists. This prevents the user +from accidentally using the same \PName{layer name} more than once. This +is especially useful when classes or packages also define layers internally. + +In contrast, \Macro{ProvideLayer} only defines a layer if there is no layer +with the same name already. If the name is in use for another layer, the new +definition is ignored. Therefore this command has the meaning, \emph{define + the layer only if it does not already exist.} + +If you want to redefine an existing layer, you can use \Macro{RedeclareLayer} +or \Macro{ModifyLayer}. With \Macro{RedeclareLayer}, the layer is first reset +to the default settings and then completely redefined via the specified +options list. In contrast, \Macro{ModifyLayer} does not reset the layer. +Only those attributes which are explicitly set in the \PName{option list} will +be changed. Applying either command to a previously undefined \PName{layer + name} results in an error. + +\begin{desclist} + \desccaption{% + Options for defining page layers and the meaning of the + corresponding layer attribute\label{tab:scrlayer.layerkeys}% + }{% + Options for defining layers (\emph{continued})% + }% + \entry{% + \ChangedAt{v3.16}{\Package{scrlayer}}% + \OptionVName{addcontents}{Code}}{% + The specified \PName{code} will be appended to the current value of the + \Option{contents} attribute, so the new content will appear at the end of + the existing content. For more information about the handling of + \PName{code} see the \Option{contents} option.% + }% + \entry{% + \ChangedAt{v3.16}{\Package{scrlayer}}% + \OptionVName{addheight}{additional height}}{% + The current value of the \Option{height} attribute will be increased by + the value of this option. You can use the same kind of values as for + \Option{height}.% + }% + \entry{% + \ChangedAt{v3.16}{\Package{scrlayer}}% + \OptionVName{addhoffset}{additional horizontal offset}}{% + The current value of the \Option{hoffset} attribute will be increased by + the value of this option. You can use the same kind of values as for + \Option{hoffset}.% + }% + \entry{% + \ChangedAt{v3.16}{\Package{scrlayer}}% + \OptionVName{addvoffset}{additional vertical offset}}{% + The current value of the \Option{voffset} attribute will be increased by + the value of this option. You can use the same kind of values as for + \Option{voffset}.% + }% + \entry{% + \ChangedAt{v3.16}{\Package{scrlayer}}% + \OptionVName{addwidth}{additional width}}{% + The current value of the \Option{width} attribute will be increased by + the value of this option. You can use the same kind of values as for + \Option{width}.% + }% + \nentry{\KOption{align}{\PName{alignment characters}}}{% + The \PName{alignment characters} define the desired alignment of the + layer. Each \PName{alignment character} determines how the \PName{length} + of either the \Option{hoffset} or the \Option{voffset} option is + interpreted. Multiple \PName{alignment character}s can be used together + (without spaces or commas) and are evaluated in the order they occur. + Macros are not permitted in the value of the option. Valid + \PName{alignment character}s are: + \begin{description} + \item[\PValue{b} --] align the layer at its bottom edge; the value of + \Option{voffset} is the distance from the top edge of the paper to the + bottom of the layer. + \item[\PValue{c} --] align the layer at its centre; the values of + \Option{voffset} and \Option{hoffset} are interpreted as the distance + from the top left corner of the paper to the centre of the layer. + \item[\PValue{l} --] align the layer at its left edge; the value of + \Option{hoffset} is interpreted as the distance from the left edge of + the paper to the left edge of the layer. + \item[\PValue{r} --] align the layer at its right edge; the value of + \Option{hoffset} is interpreted as the distance from the left edge of + the paper to the right edge of the layer. + \item[\PValue{t} --] align the layer at its top edge; the value of + \Option{voffset} is interpreted as the distance from the top edge of the + paper to the top edge of the layer. + \end{description}% + }% + \entry{\KOption{area}{% + \Parameter{hoffset}\Parameter{voffset}% + \Parameter{width}\Parameter{height}}}{% + This composite option sets the primary attributes + \OptionValue{hoffset}{horizontal offset}, \OptionValue{voffset}{vertical + offset}, \OptionValue{width}{width}, \OptionValue{height}{height}.% + }% + \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% + \Option{backandforeground}}{% + This option removes the restriction of a layer to the foreground or the + background. In general, this option makes little sense, but it is provided + for the sake of a complete user interface. This option does not expect or + allow a value.% + }% + \entry{\Option{background}}{% + This option displays the layer in the background only. The default is to + display layers in both the background and the foreground. This option does + not expect or allow a value.% + }% + \entry{\Option{bottommargin}}{% + This composite option sets the primary attributes \Option{hoffset}, + \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} so + that the layer spans the paper horizontally from the left edge to the + right and vertically from immediately beneath the footer to the bottom + edge of the paper.% + }% + \entry{\KOption{clone}{\PName{layer name}}}{% + This composite option sets all primary attributes of the layer to the same + values as the primary attributes of the layer with the given \PName{layer + name}. See the notes on the \PName{layer name} at the beginning of the + explanation for \Macro{DeclareLayer}. The layer to be cloned must also + already exist.% + }% + \entry{\KOption{contents}{\PName{code}}}{% + The specified \PName{code} will be expanded whenever the layer is printed. + This \PName{code} defines what you see for the layer. No tests are made to + see if the code is valid. Errors in the \PName{code} can therefore lead to + multiple error messages on each page that prints the layer.% + }% + \entry{\Option{evenpage}}{% + This option causes the layer to appear on even pages only, unlike the + default, where a layer will appear on both even and odd pages. Since even + pages only appear in two-sided printing, this option implies + \Option{twoside}. This option does not expect or allow a value.% + }% + \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% + \Option{everypage}}{% + This option is a combination of \Option{oddorevenpage} and + \Option{floatornonfloatpage}. This option does not expect or allow a + value.% + }% + \entry{\Option{everyside}}{% + This option removes any restriction of the layer to one-sided or two-sided + printing. This is the default setting. This option does not expect or + allow a value.% + }% + \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% + \Option{floatornonfloatpage}}{% + This option removes any restriction of the layer to float or non-float + pages and restores the default setting. This option does not expect or + allow a value.% + }% + \entry{\Option{floatpage}}{% + This option restricts the layer to appearing on float pages only. The + default setting is for layers to appear on both float and non-float pages. + This option does not expect or allow a value.% + }% + \entry{\Option{foot}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the page footer over the width of the text area. This option does + not expect or allow a value.% + }% + \entry{\Option{footskip}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical distance between the text area and the page footer over + the width of the text area. Note, however, that although the height of + this area depends on \Length{footskip}, it is not the same. This option + does not expect or allow a value.% + }% + \entry{\Option{foreground}}{% + This option displays the layer in the foreground only. The default is to + display layers in both the background and the foreground. The option does + not expect or allow a value.% + }% + \entry{\Option{head}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical area of the page header for the width of the text area. + The height corresponds to the length \Length{headheight}. This option does + not expect or allow a value.% + }% + \entry{\Option{headsep}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical distance between the page header and the text area for + the width of the text area. The height corresponds to the length + \Length{headsep}. This option does not expect or allow a value.% + }% + \entry{\KOption{height}{\PName{length}}}{% + Sets the height of the layer. Note that the \PName{length} can be a + \LaTeX{} length declared with \Macro{newlength}, a \TeX{} length declared + with \Macro{newdimen} or \Macro{newskip}, a length value like 10\,pt, or a + dimensional expression using +, -, /, *, (, and ). For more information + about valid dimensional expressions see \cite[section~3.5]{manual:eTeX}.% + }% + \entry{\KOption{hoffset}{\PName{length}}}{% + Sets the distance of the layer from the left edge of the paper. How the + distance is measured depends on the \Option{align} option. See the + \Option{height} option for more information about valid expressions for + \PName{length}.% + }% + \entry{\Option{innermargin}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the inner margin, from the edge of the page to the edge of the text + area and from the top to the bottom of the page. In one-sided printing, + the inner margin corresponds to the left margin. This option does not + expect or allow a value.% + }% + \entry{\Option{leftmargin}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the left margin, from the left edge of the paper to the left edge of + the text area and from the top of the paper to the bottom. This option + does not expect or allow a value.% + }% + \entry{\ChangedAt{v3.19}{\Package{scrlayer}}% + \OptionVName{mode}{mode}}{% + This primary option defines the \PName{mode} in which the layer's content + is output. The default is \OptionValue{mode}{text}. The baseline of the + first text line is placed the height of one standard text line below the + top edge of the layer, so the text is usually neatly aligned with the top + of the layer. In \PValue{picture} \PName{mode}, on the other hand, the + layer spans a \Environment{picture} environment with the origin at the + bottom left corner of the layer. The \PValue{raw} \PName{mode} is also + also defined. By default it corresponds to \PValue{text} \PName{mode}. + Changing\textnote{Attention!} the \PName{mode} of a layer usually results + the contents shifting. Furthermore, the \PValue{picture} \PName{mode} + provides additional commands that result in errors with another + \PName{mode}. Therefore it usually makes no sense to change the + \PName{mode} of a layer after its initial declaration!% + }% + \entry{\Option{nonfloatpage}}{% + This option restricts the layer to pages that are not float pages. The + default is for the layer to appear on both float and non-float pages. This + option does not expect or allow a value.% + }% + \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% + \Option{oddorevenpage}}{% + This option removes any restriction of the layer to odd or even pages, + restoring the default behaviour that the layer should appear on both odd + and even pages. The option does not expect or allow a value.% + }% + \entry{\Option{oddpage}}{% + This option restricts the layer to odd pages only. The default is for + layers to appear on both odd pages and on even pages. Note that in + one-sided printing, all pages are odd, regardless of the page number. This + option does not expect or allow a value.% + }% + \entry{\Option{oneside}}{% + This option restricts the layer to one-sided printing only. The default is + for layers to appear in both one-sided and two-sided printing. This option + does not expect or allow a value.% + }% + \entry{\Option{outermargin}}{% + The composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the outer margin of the page, from the top to the bottom of the + paper. The outer margin corresponds to the right margin in one-sided + printing. This option does not expect or allow a value.% + }% + \entry{\Option{page}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the the whole paper. This option does not expect or allow a value.% + }% + \entry{\ChangedAt{v3.16}{\Package{scrlayer}}% + \OptionVName{pretocontents}{code}}{% + The value of \PName{code} is prefixed the current value of the + \Option{contents} attribute, so the new content will appear before the + existing content. For more information about the handling of \PName{code}, + see the \Option{contents} option.% + }% + \entry{\Option{rightmargin}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the right margin, from the right edge of the text area to the right + edge of the paper and from the top to the bottom edge of the paper. This + option does not expect or allow a value.% + }% + \entry{\Option{textarea}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the entire text area. This option does not expect or allow a value.% + }% + \entry{\Option{topmargin}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical distance between the top edge of the paper to the + header for the entire width of the paper. This option does not expect or + allow a value.% + }% + \entry{\Option{twoside}}{% + This option restricts the layer to two-sided printing. The default is for + layers to appear in both one-sided and two-sided printing. This option + does not expect or allow a value.% + }% + \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% + \Option{unrestricted}}{% + This option removes all output restrictions. It is a combination of + \Option{backandforeground}, \Option{everyside}, and + \Option{floatornonfloatpage}. This option does not expect or allow a + value.% + }% + \entry{\KOption{voffset}{\PName{length}}}{% + Sets the distance of the layer from the top of the paper. How the distance + is measured depends on the \Option{align} option. See the \Option{height} + option for more information about valid expressions for \PName{length}.% + }% + \entry{\KOption{width}{\PName{length}}}{% + Sets the width of the layer. See the \Option{height} option for more + information about valid expressions for \PName{length}.% + }% +\end{desclist} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{layerhalign}% + \Macro{layervalign}% + \Macro{layerxoffset}% + \Macro{layeryoffset}% + \Macro{layerwidth}% + \Macro{layerheight}% +\end{Declaration} +These commands are only valid in the \PName{code} specified with +\Option{contents}, \Option{addcontents}, or \Option{pretocontents}. In this +case, they contain the layer's actual alignment, position, and dimensions that +will be used for the output. However, this is not necessarily the actual +dimensions of the layer's contents, e.\,g., if the contents are oversized or +do not fill the layer completely. + +The primary layer attribute \PValue{align} is mapped to +\Macro{layerhalign}\ChangedAt{v3.19}{\Package{scrlayer}} and +\Macro{layervalign}. The horizontal values \PValue{l} and \PValue{r} are +copied to \Macro{layerhalign}. The vertical values \PValue{t} and \PValue{b} +are copied to \Macro{layervalign}. The value \PValue{c}, which is both +horizontal and vertical, is copied to both commands. If there are several +conflicting values for \PValue{align}, only the last one is copied. Thus the +resulting \Macro{layerhalign} is either \PValue{l}, \PValue{c}, or \PValue{r}, +and the resulting \Macro{layervalign} is either \PValue{t}, \PValue{c}, or +\PValue{b}. + +Redefining\textnote{Attention!} these instructions to change the values stored +in them is not permitted, as it would lead to unpredictable results.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{LenToUnit}\Parameter{length} +\end{Declaration} +This\ChangedAt{v3.19}{\Package{scrlayer}} command originally came from +\Package{eso-pic}\IndexPackage{eso-pic}~2.0f. It converts lengths into +multiples of \Length{unit length} and can therefore be used everywhere \LaTeX{} +expects \Environment{picture} coordinates or \Length{unit length}-dependent +values. For more information, see \cite{package:eso-pic} and the descriptions +of \Macro{putUR}, \Macro{putLL}, and \Macro{putLR} below. If the command is +already defined, e.\,g., by loading \Package{eso-pic} before +\Package{scrlayer}, the package does not define it again.% +\iffalse% Umbruchkorrekturtext +\par +It should be noted at this point that using package +\Package{picture}\IndexPackage{picture}\textnote{\Package{picture}} (see +\cite{package:picture}) supersedes \Macro{LenToUnit} more or less. The package +extends environment \Environment{picture} and the picture commands so that you +can use \LaTeX{} lengths directly for coordinates.% +\fi +\EndIndexGroup + + +\begin{Declaration} + \Macro{putUL}\Parameter{content}% + \Macro{putUR}\Parameter{content}% + \Macro{putLL}\Parameter{content}% + \Macro{putLR}\Parameter{content}% + \Macro{putC}\Parameter{content} +\end{Declaration} +You\ChangedAt{v3.19}{\Package{scrlayer}} can use these commands inside the +value of \PValue{contents} layer option if the layer is declared with +\OptionValue{mode}{picture}. In this case, \Macro{putUL} places the +\PName{content} relative to the upper left corner of the layer and therefore +is the same as +\lstinline[breaklines=false]|\put(0,\LenToUnit{\layerheight})|. \Macro{putUR} +places the \PName{content} relative to the upper right corner of the layer and +therefore is the same as +\lstinline[breaklines=false] +|\put(\LenToUnit{\layerwidth},\LenToUnit{\layerheight})|. +\Macro{putLL} places the \PName{content} relative to the lower left corner of +the layer and therefore is the same as +\lstinline[breaklines=false]|\put(0,0)|. \Macro{putLR} places the +\PName{content} relative to the lower right corner and therefore is the same +as \lstinline[breaklines=false]|\put(\LenToUnit{\layerwidth},0)|. Last but +not least, \Macro{putC} places the \PName{content} relative to the centre of +the layer.% +\begin{Example} + You want to determine exactly how accurately + \OptionValueRef{typearea}{DIV}{classic} sets the height of the text area to + the width of the page size. You declare a layer that both borders the text + area and places a circle with a diameter of the paper width in the centre of + the text area: +\begin{lstcode} + \documentclass[DIV=classic]{scrartcl} + \usepackage{pict2e} + \usepackage{scrlayer} + \DeclareNewLayer[% + textarea,background,mode=picture, + contents={% + \putLL{\line(1,0){\LenToUnit{\layerwidth}}}% + \putLR{\line(0,1){\LenToUnit{\layerheight}}}% + \putUR{\line(-1,0){\LenToUnit{\layerwidth}}}% + \putUL{\line(0,-1){\LenToUnit{\layerheight}}}% + \putC{\circle{\LenToUnit{\paperwidth}}}% + } + ]{showtextarea} + \DeclareNewPageStyleByLayers{test}{showtextarea} + \pagestyle{test} + \begin{document} + \null + \end{document} +\end{lstcode} + You will notice that \Package{typearea}'s mapping to an integer \PName{DIV} + value is very accurate in this example. +\end{Example} +Incidentally, you will find more information about late medieval book-page +canon sketched in the example in \autoref{sec:typearea.circleConstruction}, +\autopageref{sec:typearea.circleConstruction}. + +The \Macro{DeclareNewPageStyleByLayers}\IndexCmd{DeclareNewPageStyleByLayers} +command just used in the example defines a new page style using the newly +declared layer. It will be explained in \autoref{sec:scrlayer.pagestyles}, +\DescPageRef{scrlayer.cmd.DeclareNewPageStyleByLayers}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{GetLayerContents}\Parameter{layer~name} +\end{Declaration} +This\ChangedAt{v3.16}{\Package{scrlayer}} command returns the whole contents +of a layer. It is important to note\textnote{Attention!} that using this +command inside the \PName{code} of the layer attributes \Option{contents}, +\Option{addcontents}, or \Option{pretocontents} can result in +infinite recursion when referencing the contents of the current layer. You +are responsible for avoiding such situations!% +\EndIndexGroup + + +\begin{Declaration} + \Macro{IfLayerExists}\Parameter{layer~name} + \Parameter{then-code}\Parameter{else-code} +\end{Declaration} +This command can be used to execute code depending on whether or not a layer +with the specified \PName{layer name} exists. If the layer exists, the +\PName{then-code} will be executed; otherwise, the \PName{else-code} will be +executed. Note that the command cannot really test whether a layer exists. +Instead it uses a heuristic which will never yield a false negative but which, +in extreme cases, could yield a false positive. +\iffalse% Umbruchvarianten +Nevertheless, if the test yields a false positive, something has gone wrong. +For example, this could indicate an incompatible package or that the user is +doing something he or she should not.% +\else +False positives indicate a problem, such as the use of an incompatible package +or a bad choice of internal macro names by the user. +\fi +\EndIndexGroup + + +\begin{Declaration} + \Macro{DestroyLayer}\Parameter{layer~name} +\end{Declaration} +If a layer with the given \PName{layer name} exists, all macros belonging to +it will be set to \Macro{relax}. In page styles already defined with +\Package{scrlayer}, such destroyed layers are ignored. Destroyed layers can be +redefined using \DescRef{\LabelBase.cmd.DeclareNewLayer} or +\DescRef{\LabelBase.cmd.ProvideLayer}, but they can no longer be changed using +\DescRef{\LabelBase.cmd.RedeclareLayer} or +\DescRef{\LabelBase.cmd.ModifyLayer}. + +The command is intended to be used inside +\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} (see +\autoref{sec:scrlayer.enduserinterfaces}, +\DescPageRef{scrlayer.cmd.scrlayerOnAutoRemoveInterface}) +to remove layers defined using removable macros of an interface along with +that interface.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{layercontentsmeasure}% +\end{Declaration} +The \Macro{layercontentsmeasure} command prints a ruler at each layer edge, of +which the top and left one is labelled in centimetres and the right and bottom +one in inches. This command is used internally if the +\DescRef{\LabelBase.option.draft}\IndexOption{draft} option is enabled. The +rulers are drawn behind the content of each layer. This command can also be +used as exclusive content of a layer.% +\EndIndexGroup + + +\section{Declaring and Managing Page Styles} +\seclabel{pagestyles} + +\BeginIndexGroup +\BeginIndex{}{page>style}% +We now understand how to define and manage layers, but so far we do not know +how they are used. The possibly surprising answer is, with page styles. In +\LaTeX{}, page styles usually define headers and footers of the page. + +The header and footer of odd or right-hand pages\textnote{even or odd page} +are printed on pages with odd page numbers in two-sided printing or on all +pages in one-sided printing. This is directly comparable to the layer +options\important[i]{\Option{evenpage}\\\Option{oddpage}} \Option{oddpage} and +\Option{evenpage}. + +The page header\textnote{header or footer} is output before the main page +contents. The page footer is output after the main page contents. This +corresponds directly to the layer +options\important[i]{\Option{background}\\\Option{foreground}} +\Option{background} and \Option{foreground}. + +Therefore it makes sense to define page styles as lists of layers. But instead +of just the four options mentioned above, you can use all the properties +explained in \autoref{sec:scrlayer.layers}, \autoref{tab:scrlayer.layerkeys}, +on \autopageref{tab:scrlayer.layerkeys}. + +As a result of these considerations, layer page +styles\textnote{layer page style}\Index{page style>layer}% +\Index{layer>page style}\Index{page>style} are one type of page style that +\Package{scrlayer} provides. A layer page style consists of layers as well as +several hooks. The layers have already been described in +\autoref{sec:scrlayer.layers}. The hooks\Index[indexmain]{hooks}% +\textnote{hooks} are points in the expansion or execution of page styles to +which you can add code. Experienced users already know this concept from +commands like \Macro{AtBeginDocument} (see \cite{latex:usrguide}) or +\DescRef{scrlfile.cmd.BeforeClosingMainAux} (see +\DescPageRef{scrlfile.cmd.BeforeClosingMainAux}). + +Page-style aliases are another type of page style which \Package{scrlayer} +provides. A page-style alias is actually a different page style. In other +words, the name of a page-style alias is an alternative name for another +page-style alias or for a page style. As a result, manipulating a page-style +alias results in manipulating the original page style. If the original page +style is itself an alias, its manipulation again results in the manipulation +of the alias's original page style, and so on until a real page style is +finally changed. The term \emph{real page style}\textnote{real page style} is +used to distinguish it from a page-style alias. All page styles that are not +page-style aliases are real page styles. Aliases can be defined for all page +styles, not just those defined with \Package{scrlayer}. + +\begin{Declaration} + \Macro{currentpagestyle} + \Macro{toplevelpagestyle} +\end{Declaration} +The \Package{scrlayer} package patches the \DescRef{maincls.cmd.pagestyle} +command so that it sets \Macro{currentpagestyle} to the currently active page +style. Note that \DescRef{maincls.cmd.thispagestyle} does not change +\Macro{currentpagestyle}. If you use \DescRef{maincls.cmd.thispagestyle}, +however, \Macro{currentpagestyle} can change within the \LaTeX{} output +routine. However, this change will only occur if \Macro{currentpagestyle} has +been actively protected from expansion until the execution of the output +routine. + +Note that the layer page styles described later in this section do not rely on +this \DescRef{maincls.cmd.pagestyle} extension because they redefine +\Macro{currentpagestyle} themselves. This patch was made so that other, +non-\Package{scrlayer} page styles can use \Macro{currentpagestyle}. +Additionally, \Macro{currentpagestyle} is empty after loading +\Package{scrlayer} and before using \DescRef{maincls.cmd.pagestyle} for the +first time. Therefore, when defining an end-user interface, you may find it +useful to set the current page style to a default with an implicit +\DescRef{maincls.cmd.pagestyle} statement. + +% Todo: New translation by Markus Kohm (please fix it!) +For page-style aliases activated using \DescRef{maincls.cmd.pagestyle} +\Macro{currentpagestyle} does not show the alternative name but the name of +the real page style. You\ChangedAt{v3.16}{\Package{scrlayer}} can get the +alternative name using \Macro{toplevelpagestyle}. However, it is not +recommended to define page styles, that have different results depending on +\Macro{toplevelpagestyle}, e.\,g., using \DescRef{scrbase.cmd.ifstr}. If you +would activate such a page style using \DescRef{maincls.cmd.thispagestyle} you +could get the wrong result.% +% End of new translation. +\EndIndexGroup + + +\begin{Declaration} + \Macro{BeforeSelectAnyPageStyle}\Parameter{code}% + \Macro{AfterSelectAnyPageStyle}\Parameter{code}% +\end{Declaration} +The \Macro{BeforeSelectAnyPageStyle} command adds \PName{code} to the hook% +\textnote{hook} that will be executed inside \DescRef{maincls.cmd.pagestyle}, +just before the page style is selected. Within the \PName{code}, you can use +\texttt{\#1} as a place-holder for the argument of +\DescRef{maincls.cmd.pagestyle}. + +The \Macro{AfterSelectAnyPageStyle} command works similarly, but the +\PName{code} will be executed just after the page style has been selected and +after \DescRef{\LabelBase.cmd.currentpagestyle} has been set to the name of +the real page style. + +Note\textnote{Attention!} that the \PName{code} of both commands is executed +only if a page style is selected with \DescRef{maincls.cmd.pagestyle} and not +if it is chosen in a different way, e.\,g., using +\DescRef{maincls.cmd.thispagestyle}. Note also that you cannot remove +\PName{code} from the hook after adding it. But the \PName{code} will be added +locally, so you can use a group to limit the scope of the \PName{code}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DeclarePageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original~page~style~name} + \Macro{DeclareNewPageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original~page~style~name} + \Macro{ProvidePageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original~page~style~name} + \Macro{RedeclarePageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original page style name} +\end{Declaration} +\BeginIndex{}{page style>alias}% +\BeginIndex{}{alias>page style}% +These commands can be used to define a page style with name \PName{page style + alias name} that is simply an alias for an existing page style with the +name \PName{original page style name}. If there is already a page style +\PName{page style alias name}, using \Macro{DeclarePageStyleAlias} or +\Macro{RedeclarePageStyleAlias} will destroy the alias before recreating it. + +\Macro{DeclareNewPageStyleAlias} will throw an error message if a page style +\PName{page style alias name} has already been defined. It does not matter if +the previously defined page style is a layer-page style, a page style alias, +or another page style. + +\Macro{ProvidePageStyleAlias} will define the alias only if the +\PName{page style alias name} page style has not been defined before. If the +\PName{page style alias name} page style already exists, nothing will be done. + +\Macro{RedeclarePageStyleAlias} expects an existing +\PName{page style alias name} page style. It will destroy that page style and +afterwards define the alias. If the \PName{page style alias name} page style +does not exist, you will get an error.% +\iffree{\csname @tempswafalse\endcsname}{\csname @tempswatrue\endcsname}% +\csname if@tempswa\endcsname% Umbruchkorrekturtext + \begin{Example} + Suppose you write a class and use the \PageStyle{chapter} page style for the + first page of each chapter. By default, this page style should match the + \PageStyle{plain} page style. Therefore, you can use the \Package{scrlayer} + package and use +\begin{lstcode} + \DeclareNewPageStyleAlias{chapter}{plain} +\end{lstcode} + to define the \PageStyle{chapter} page style as an alias for the + \PageStyle{plain} page style. If, on the other hand, you later decide that + the \PageStyle{chapter} plage style should correspond to the + \PageStyle{empty} page style, you can achieve this with: +\begin{lstcode} + \RedeclarePageStyleAlias{chapter}{empty} +\end{lstcode}% + \end{Example}% +\fi +\EndIndexGroup + + +\begin{Declaration} + \Macro{DestroyPageStyleAlias}\Parameter{page~style~name}% +\end{Declaration} +\BeginIndex{}{page style>alias}% +\BeginIndex{}{alias>page style}% +This command renders the page style named \PName{page style name} undefined +for \LaTeX{} if it is an alias for another page style. Afterwards, the page +style can be newly defined with +\DescRef{\LabelBase.cmd.DeclareNewPageStyleAlias} or +\DescRef{\LabelBase.cmd.ProvidePageStyleAlias}. + +This command is intended to be used inside the argument code of +\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} to remove page styles +that have been declared as part of an end-user interface when removing this +interface automatically.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{GetRealPageStyle}\Parameter{page~style~name}% +\end{Declaration} +\BeginIndex{}{page style>alias}% +\BeginIndex{}{alias>page style}% +This command will result in the (recursive) real page name of the page style +if \PName{page style name} is an alias of another page style. In all other +cases, even if there's no alias and no page style named \PName{page style + name}, the result is simply \PName{page style name}. The command is fully +expandable and may be used, e.g., in the second argument of \Macro{edef}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DeclarePageStyleByLayers}\OParameter{option list} + \Parameter{page style name} + \Parameter{layer list} + \Macro{DeclareNewPageStyleByLayers}\OParameter{option list} + \Parameter{page style name} + \Parameter{layer list} + \Macro{ProvidePageStyleByLayers}\OParameter{option list} + \Parameter{page style name} + \Parameter{layer list} + \Macro{RedeclarePageStyleByLayers}\OParameter{option list} + \Parameter{page style name} + \Parameter{layer list} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +These commands declare a page style named \PName{page style name}. The page +style will consist of the layers given in \PName{layer list}, a comma +separated list of layer names. Note\textnote{Attention!} that the \PName{page + style name} and the layer names in the \PName{layer list} must be fully +expandable and should expand to letters. Several other characters are also +accepted, but their use is recommended only for experienced users. + +The \PName{option list} is a comma-separated list of options in the form +\texttt{\PName{key}=\PName{value}}. These options may be used to set +additional features. Currently they are used to set the code that should be +expanded or executed at several hooks\Index{hooks}. See the introduction to +this section for more general information about hooks. See +\autoref{tab:scrlayer.pagestyle.hooks} for detailed information on specific +hooks. + +\begin{desclist} + \desccaption{% + Hook options for page styles (in order of + execution)\label{tab:scrlayer.pagestyle.hooks}% + }{% + Hook options for page styles (\emph{continued})% + }% + \entry{\OptionVName{onselect}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the page + style is selected, for example with \DescRef{maincls.cmd.pagestyle}. Note + that \DescRef{maincls.cmd.thispagestyle} itself does not directly select a + page style. In this case, the page style is only activated within \LaTeX's + output routine.% + }% + \entry{\OptionVName{oninit}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers is initialised. Note that this happens twice + for each page: once for background layers and once for foreground layers.% + }% + \entry{\OptionVName{ononeside}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers in one-sided printing is initialised. Note that + this happens twice for each page: once for background layers and once for + foreground layers.% + }% + \entry{\OptionVName{ontwoside}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers in two-sided printing is initialised. Note that + this happens twice for each page: once for background layers and once for + foreground layers.% + }% + \entry{\OptionVName{onoddpage}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on an odd page is initialised. Note that this + happens twice for each page: once for background layers and once for + foreground layers. Note also that in one-sided printing all pages are odd + pages, not just those with odd page numbers.% + }% + \entry{\OptionVName{onevenpage}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on an even page is initialised. Note that this + happens twice for each page: once for background layers and once for + foreground layers. Note also that in one-sided printing there are no even + pages. Instead, all pages are treated as odd pages, not just those with + odd page numbers.% + }% + \entry{\OptionVName{onfloatpage}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on a float page is initialised. Note that this + happens twice for each page: once for background layers and once for + foreground layers. Note also that float pages are only those pages with + one or more p-placed floating environments.% + }% + \entry{\OptionVName{onnonfloatpage}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on a non-float page is initialised. Note that + this happens twice for each page: once for background layers and once for + foreground layers. Note also that float pages are only the pages on which + one or more p-placed floating environments are output. Other pages may + well have t-, h-, or b-placed floating environments.% + }% + \entry{\OptionVName{onbackground}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's background layers is initialised. Note that this + happens once each page.% + }% + \entry{\OptionVName{onforeground}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's foreground layers is initialised. Note that this + happens once each page.% + }% +\end{desclist} + +\iffalse% Umbruchvarianten + While the \Macro{DeclarePageStyleByLayers} command always defines the page + style, \Macro{DeclareNewPageStyleByLayers} generates an error message if a + page style with the same name already exists. Note\textnote{Attention!} that + the declaration of a page style that is already an alias for another page + style (see, for example, \Macro{DeclareAliasPageStyle} earlier in this + section) will redefine not the specified page style alias but the real page + style (see \DescRef{\LabelBase.cmd.GetRealPageStyle} earlier in this + section).% +\else% + The \Macro{DeclarePageStyleByLayers} command defines the page style + regardless of whether a page style of \PName{page style name} already + exists. If necessary, the existing page style is completely + redefined. However, if a page style alias \PName{page style name} already + exists, the associated real page style, not the page style alias itself, is + redefined (see \DescRef{\LabelBase.cmd.GetRealPageStyle} earlier in this + section). + + The \Macro{DeclareNewPageStyleByLayers} command differs if a page style of + the same name already exists. Regardless of whether it is a real or an alias + page style, an error will be reported in this case. +\fi + +In contrast, \Macro{ProvidePageStyleByLayers} preserves the page style +unchanged if a page style with name \PName{page style name} already exists. If +no such page style exists, it is defined as in +\Macro{DeclarePageStyleByLayers}. + +The \Macro{RedeclarePageStyleByLayers} in turn expects that a page style of +of the name \PName{page style name} already exists and then redefines its real +page style. However, if no page style of the specified name exists, an error +message results. + +Also note the remarks below about the pseudo-page style +\PageStyle{@everystyle@}.% +\EndIndexGroup + + +\begin{Declaration} + \PageStyle{@everystyle@}% + \PageStyle{empty} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +The \Package{scrlayer} package defines two specific page styles worth noting. +The first of these is \PageStyle{@everystyle@}% +\important{\PageStyle{@everystyle@}}. This page style should never be used +like a normal page style, for example with \DescRef{maincls.cmd.pagestyle} or +\DescRef{maincls.cmd.thispagestyle}, or as the target of a page-style alias. +Instead, the layers and hooks\Index{hooks} of this page style are used by all +other layer page styles. The hooks of \PageStyle{@everystyle@} are placed in +front of their respective hooks, and the layers in front of the respective +layers, of the active page style. + +Thus adding a layer to the pseudo-page style \PageStyle{@everystyle@} or code +to a hook of this page style is like adding a layer or hook code to all layer +page styles, even the empty one. There's one crucial difference: commands that +reference the layers of a page style which include +\DescRef{\LabelBase.cmd.ForEachLayerOfPageStyle}, e.\,g., the commands +\DescRef{\LabelBase.cmd.AddLayersToPageStyleBeforeLayer} or +\DescRef{\LabelBase.cmd.AddLayersToPageStyleAfterLayer}, disregard the layers +of the page style \PageStyle{@everystyle@} when applied to a different layer +page style. + +The second, slightly different page style is \PageStyle{empty}. Normally the +\LaTeX{} kernel defines the \PageStyle{empty} page style to have an empty +header and footer. The \Package{scrlayer} package redefines this page style as +a layerless page style. Nonetheless, you can use it like any other layer page +style. The main advantage of the layer page style over the original page +style from the \LaTeX{} kernel is that it also executes the hooks and layers +of the psuedo-layer page style \PageStyle{@everystyle@}.% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{onpsselect}{code}% + \OptionVName{onpsinit}{code}% + \OptionVName{onpsoneside}{code}% + \OptionVName{onpstwoside}{code}% + \OptionVName{onpsoddpage}{code}% + \OptionVName{onpsevenpage}{code}% + \OptionVName{onpsfloatpage}{code}% + \OptionVName{onpsnonfloatpage}{code}% + \OptionVName{onpsbackground}{code}% + \OptionVName{onpsforeground}{code} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +There is also a \KOMAScript{} option for each of the hooks\Index{hooks} in +\autoref{tab:scrlayer.pagestyle.hooks}% +\iftrue +. The names of the \KOMAScript{} options are similar to those for declaring +page style layers, except that a ``\texttt{ps}'' is inserted after +``\texttt{on}'' at the beginning of the name +\else +, into the names of which a ``\texttt{ps}'' is inserted +\fi +. The values of these \KOMAScript{} options are used as the initial values for +the corresponding hooks. These initial values are then extended by all the +values assigned to the corresponding hooks in the \PName{option list} of the +declaration commands. You can remove the default with +\DescRef{\LabelBase.cmd.ModifyLayerPageStyleOptions}, which is explained later +in this section.% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{singlespacing}{simple switch} +\end{Declaration} +If\ChangedAt{v3.24}{\Package{scrlayer}\and \Package{scrlayer-scrpage}} a +document is printed with increased line spacing, e.\,g., using the +\Package{setspace}\IndexPackage{setspace}\important{\Package{setspace}} +package, it is often undesirable for the header and footer to be printed with +this increased spacing. This is particularly true if the header and footer +consist of only a single line. In this case you can use \KOMAScript{} option +\Option{singlespacing}. However, the default\textnote{default} is +\OptionValue{singlespacing}{false}! The option generally applies to all layer +page styles. If you want single-spacing for only some page styles, use +\OptionValue{oninit}{\Macro{linespread}\PParameter{1}\Macro{selectfont}} for +those page styles.% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{deactivatepagestylelayers}{simple switch}% + \Macro{ForEachLayerOfPageStyle}\Parameter{page style name}\Parameter{code}% + \Macro{ForEachLayerOfPageStyle*}\Parameter{page style name}\Parameter{code} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +As long as the \KOMAScript{} option \Option{deactivatepagestylelayers} is not +enabled, the \Macro{ForEachLayerOfPageStyle} command can execute arbitrary +\PName{code} for each layer of the page style named \PName{page style name}. +Inside of \PName{code}, the place holder \PValue{\#1} serves as a +reference to the name of the current layer. +\begin{Example} + If you want to print the names of all layers of the \PValue{scrheadings} + page style as a comma-separated list, you can use: +\begin{lstcode} + \let\commaatlist\empty + \ForEachLayerOfPageStyle{scrheadings}{% + \commaatlist#1\gdef\commaatlist{, }} +\end{lstcode} +\end{Example} +In\textnote{Attention!} the example above, we had to use \Macro{gdef} instead +of \Macro{def} because \Macro{ForEachLayerOfPageStyle} executes the +\PName{code} inside a group to minimise side effects. However, \Macro{gdef} +redefines \Macro{commaatlist} globally so the change will persist when the +\PName{code} for the next layer is executed. + +Alternatively,\ChangedAt{v3.18}{\Package{scrlayer}} you can use \Macro{def} +with the starred variant \Macro{ForEachLayerOfPageStyle*}. This form dispenses +with the extra group when executing \PName{code}. However, the user then has +to take make sure that the \PName{code} has no unwanted side effects. In +particular, deactivating all layers using +\OptionValue{deactivatepagestylelayers}{true} within \PName{code} would +persist beyond the call to \Macro{ForEachLayerOfPageStyle*}. + +Various \Package{scrlayer} commands also use \Macro{ForEachLayerOfPageStyle} +internally. Their behaviour can therefore also be changed using the +\KOMAScript{} option \Option{deactivatepagestylelayers}. With this option, +you can temporarily disable and thus hide all layers of all layer page +styles.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{AddLayersToPageStyle}% + \Parameter{page style name}\Parameter{layer list}% + \Macro{AddLayersAtBeginOfPageStyle}% + \Parameter{page style name}\Parameter{layer list}% + \Macro{AddLayersAtEndOfPageStyle}% + \Parameter{page style name}\Parameter{layer list}% + \Macro{RemoveLayersFromPageStyle}% + \Parameter{page style name}\Parameter{layer list}% +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +You can use these commands to add layers to a layer page style or to remove +layers from a layer page style. The page style is referenced by its +\PName{page style name}. The layers are given by a comma-separated +\PName{layer list}. + +Both the \Macro{AddLayersToPageStyle} and the +\Macro{AddLayersAtEndOfPageStyle}\textnote{add at the end} commands insert the +new layers at the bottom of the page style's layer list. Logically, the newly +added layers lie above or in front of the old layers. Background layers, of +course, still are logically behind the text layer and thus behind all +foreground layers. + +In contrast, the \Macro{AddLayersAtBeginOfPageStyle}\textnote{add at the + beginning} command inserts the new layers at the top of the page style's +layer list. The layers are separately inserted to the top of the list in the +same order they appear in the \PName{layer list} parameter. This means that +the last layer in the \PName{layer list} parameter will become the first, and +thus the lowest, layer of the page style. + +\iffalse% Umbruchkorrekturtext (beim Aktiveren muss unten \textnote{remove} +% entfernt werden!) +The \Macro{RemoveLayersFromPageStyle} command is exactly the opposite. It +removes\textnote{remove} the specified page-style levels.% +\fi + +The \Macro{RemoveLayersFromPageStyle}\textnote{remove} command removes layers +from the layer list of the page style named \PName{page style name}. +Attempting to remove layers which are not part of the page style's layer list +will be ignored. But attempting to add layers to or remove layers from a page +style that is neither a layer page style nor a page-style alias is an error +and will be reported as such.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{AddLayersToPageStyleBeforeLayer}% + \Parameter{page style name}\Parameter{layer list}% + \Parameter{reference layer name}% + \Macro{AddLayersToPageStyleAfterLayer}% + \Parameter{page style name}\Parameter{layer list}% + \Parameter{reference layer name} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +\iffalse% Umbruchvarianten +These two commands are similar to the previous ones, but they take an +additional parameter, \Parameter{reference layer name}. The layer list of +the page style named in \Parameter{page style name} is searched for this +reference layer. % +\else% +These commands are similar to the previous ones. The existing layers of the +page style, however, are searched for the \PName{reference layer name}. % +\fi% +The layers in the \Parameter{layer list} parameter are then inserted +before\textnote{add before/after layer} or after this reference layer% +\iffalse% Umbruchkorrekturtext +in the layers of the page style% +\fi% +. The order of the layers in the \PName{layer list} is retained. + +If the reference layer named \PName{reference layer name} is not part of the +given page style, nothing is inserted. On the other hand, if the page style is +neither a layer page style nor a page-style alias, an error will be reported.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{UnifyLayersAtPageStyle}\Parameter{page style name} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +The commands for defining page styles or adding layers to a page style do not +care how many times a layer appears in a page style, so it is quite +permissible for a layer to appear multiple times. In most cases, however, it +does not make sense to use the same layer several times in one page style. +Therefore, you can use \Macro{UnifyLayersAtPageStyle} to remove all layer +duplicates from the layer page style of the specified \Parameter{page style + name}. + +Note\textnote{Attention!} that this function can change the order of layers. +So if you need a specific order, you should remove all layers and add the +layers in the order you want instead of using \Macro{UnifyLayersAtPageStyle}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ModifyLayerPageStyleOptions}% + \Parameter{page style name}\Parameter{option list}% + \Macro{AddToLayerPageStyleOptions}% + \Parameter{page style name}\Parameter{option list} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +These two commands can be used to modify the options, and thus the +hooks\Index{hooks}, of a layer page style. With +\Macro{ModifyLayerPageStyleOptions}\textnote{change page-style options}, only +the options in the comma-separated \PName{option list} will be set to the new +values given there. The previous values are lost. All options from +\autoref{tab:scrlayer.pagestyle.hooks}, +\autopageref{tab:scrlayer.pagestyle.hooks} are allowed. Options or hooks that +are not specified in the \PName{option list} will remain unchanged. If you +want to set an option to do nothing you can set it to the value \Macro{relax}. +Setting an option to a new value using \Macro{ModifyLayerPageStyleOptions} +will remove the previous value, including the global default value. This +statement is the only way to remove the global defaults of the \KOMAScript{} +options from a page style. + +\Macro{AddToLayerPageStyleOptions}\textnote{extend page-style options}, on the +other hand, does not overwrite the previous values. Instead it adds\,---\,or, +more precisely, concatenates\,---\, the new values to old ones.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{IfLayerPageStyleExists}% + \Parameter{page style name}\Parameter{then code}\Parameter{else code}% + \Macro{IfRealLayerPageStyleExists}%^ + \Parameter{page style name}\Parameter{then code}\Parameter{else code}% +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +With these commands, you can execute code depending on whether a page style is +a layer page style or not. The \Macro{IfLayerPageStyleExists} command executes +the \PName{then code} if \PName{page style name} is the name of a layer page +style or a page-style alias that results in a layer page style. Otherwise, the +command executes the \PName{else code}. Internally, this command is often used +to throw an error message if you use one of the layer page style commands with +an \PName{page style name} that does not correspond to a layer page style. + +The \Macro{IfRealLayerPageStyleExists} command goes one step further and +executes the \PName{then code} only if the page style specified by \PName{page + style name} is itself a layer page style. So if \PName{page style name} is a +page-style alias, this command executes the \PName{else code} even if the +alias resolves to a real layer page style.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{IfLayerAtPageStyle}% + \Parameter{page style name}\Parameter{layer name}% + \Parameter{then code}\Parameter{else code}% + \Macro{IfSomeLayerAtPageStyle}% + \Parameter{page style name}\Parameter{layer list}%^ + \Parameter{then code}\Parameter{else code}% + \Macro{IfLayersAtPageStyle}% + \Parameter{page style name}\Parameter{layer list}% + \Parameter{then code}\Parameter{else code}% +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +These commands can be used to test whether one or more layers are part of a +page style. The \Macro{IfLayerAtPageStyle} command expects exactly one +\PName{layer name}\textnote{exactly one layer} as the second argument. If this +layer is part of the page style specified in \PName{page style name}, the +\PName{then code} will be executed. Otherwise, the \PName{else code} will be +executed. + +The \Macro{IfSomeLayerAtPageStyle} and \Macro{IfLayersAtPageStyle} commands +allow a comma-separated \PName{layer list}. \Macro{IfSomeLayerAtPageStyle} +will execute the \PName{then code} if \emph{at least one} of the layers in the +\PName{layer list} parameter is part of the layer list of \PName{page style + name}. In contrast, \Macro{IfLayersAtPageStyle} executes the \PName{then + code} only if \emph{all} the layers in the \PName{layer list} parameter are +part of the page style. If the condition is not met, the \PName{else code} +will be executed. + +With suitable nesting of these commands, you can construct complex conditions. +If you use only one \PName{layer name} in the \PName{layer list}, all three +statements are synonymous.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DestroyRealLayerPageStyle}\Parameter{page style name} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +\iftrue +This statement makes a layer page style undefined. If a page-style alias or +ordinary page style is specified, the command is ignored. +\else +With this command you can remove a the definition of a layer page style. +However, this only occurs if a layer page style named \PName{page style name} +exists. If, instead, it is a page-style alias, a different (non-layer) page +style, or not a page style at all, nothing happens; the command is ignored.% +\fi + +If \PName{page style name} is the name of the current page style, the current +page style will becomes a kind of empty page style. If the page style set with +\DescRef{maincls.cmd.thispagestyle} is \PName{page style name}, it will simply +be reset. The previous \DescRef{maincls.cmd.thispagestyle} command loses its +current effect. + +Note\textnote{Attention!} that the layers of the page style are not destroyed +automatically. If you want to destroy the layers too, you can do this with: +\begin{lstcode} + \ForEachLayerOfPageStyle{...}{\DestroyLayer{#1}} +\end{lstcode} +before destroying the layer page style itself. + +The command is intended to be used within the \PName{code} argument of +\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} to remove page styles +that are defined as part of an end-user interface. See +\autoref{sec:scrlayer.enduserinterfaces} below for more information about +auto-removal code.% +\EndIndexGroup +\EndIndexGroup + +\LoadCommonFile{headfootheight}% \section{Height of Page Head and Foot} + +\LoadCommonFile{pagestylemanipulation}% \section{Manipulation of Defined Page Styles} + +\section{Defining and Managing Interfaces for End Users} +\seclabel{enduserinterfaces} + +The \Package{scrlayer} package provides an experimental interface to define +and manage (concurrent) interfaces for end users. \iffree{In the long run, + this interface may disappear from \Package{scrlayer} and be taken over by + \Package{scrbase} instead.}{} Currently, this interface is highly +experimental% +\iffree{ and therefore \Package{scrlayer} provides these interface commands + only for the use of subpackages of \Package{scrlayer}}{}% +. Given the current state of development, you should not depend on automatic +removal of a concurrent interface to work. Instead, you should avoid using +concurrent end-user interfaces. + +This section only describes the interface commands for defining an end-user +interface. For end users themselves, it is of little interest. Rather, this +section is intended for authors of packages and classes that build on +\Package{scrlayer}. End users will find information about specific end-user +interfaces in \autoref{cha:scrlayer-scrpage}, +\autoref{cha:scrlayer-scrpage-experts}, and \autoref{cha:scrlayer-notecolumn}. + +\begin{Declaration} + \Macro{scrlayerInitInterface}\OParameter{interface name} +\end{Declaration} +The \Macro{scrlayerInitInterface} command registers a new interface named +\PName{interface name}. The \PName{interface name} must be unique. If an +interface with the same name has already been registered, an error will occur. + +This command should always appear as the first command when defining an +end-user interface and therefore is described here first. If the optional +argument\,---\,including the square brackets\,---\,is omitted, +\PValue{\Macro{@currname}.\Macro{@currext}} will be used instead. For classes +and packages, this is the file name of the class or package. But of course you +can use any other sequence of characters with a category of \emph{letter} or +\emph{other}. This is useful, for example, when a class or package defines +multiple end-user interfaces% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{forceoverwrite}{simple switch}% + \OptionVName{autoremoveinterfaces}{simple switch}% + \Macro{scrlayerAddToInterface}% + \OParameter{interface name}\Parameter{command}\Parameter{code}% + \Macro{scrlayerAddCsToInterface}% + \OParameter{interface name}\Parameter{command sequence}\Parameter{code} +\end{Declaration} +One of the special features of \Package{scrlayer}'s end user interfaces is +that they should register all interface-dependent commands (also known as +\emph{macros}). You can do this using \Macro{scrlayerAddToInterface}. The +optional argument \PName{interface name} must be an interface name previously +registered with \DescRef{\LabelBase.cmd.scrlayerInitInterface}. An error will +occur if the interface has not been initialised. + +If\textnote{Attention!} your interface defines macros not just when the class +or package is being loaded but also at runtime, you must provide the interface +name in the optional argument even if it corresponds to the file name of the +class or package, since the values of \Macro{@currname} and \Macro{@currext} +are only valid while the class or package is being loaded. + +The first mandatory argument is the \PName{command}\footnote{The + \PName{command} consists of a backslash followed by a \PName{command + sequence} that consists of characters of the category code \emph{letter}, + or of exactly one character of the category \emph{other}, or of a character + of the category \emph{active} (without the backslash).} to be added to the +interface. If the command can be defined, this will be done. In addition, it +will set to \Macro{relax} and \PName{code} will be executed. Within +\PName{code}, you can then define \PName{command}, e.\,g., using +\Macro{newcommand}. + +But when can a command be defined? If a command is undefined or \Macro{relax}, +it can always be defined. If a command has already been defined \emph{and} +registered for another interface \emph{and} if the \KOMAScript{} option +\Option{autoremoveinterfaces} has been activated, the other interface will be +removed automatically, and the \PName{command} will be set to \Macro{relax} +and registered for the new interface specified. If a \PName{command} is +already defined but is \emph{not} part of another interface, \emph{and} if the +\KOMAScript{} option \Option{forceoverwrite} has been activated, the +\PName{command} is also set to \Macro{relax} and registered for the specified +interface. In all other cases, however, the command is not definable, in +particular if it is already defined and the \KOMAScript{} options +\Option{autoremoveinterfaces} and \Option{forceoverwrite} are deactivated. + +The \Macro{scrlayerAddCsToInterface} command is similar to +\Macro{scrlayerAddToInterface} but it expects the first argument to be not a +\PName{command} but a command sequence\footnote{A command sequence must be + fully expandable and its expansion must result in characters of the category + code \emph{letter}, \emph{other}, or \emph{space}.}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{scrlayerOnAutoRemoveInterface}% + \OParameter{interface name}\Parameter{code} +\end{Declaration} +The \Macro{scrlayerOnAutoRemoveInterface} command registers \PName{code} to be +executed in the event that the end-user interface with the specified +\PName{interface name} is automatically removed (see +\DescRef{\LabelBase.option.autoremoveinterfaces} earlier in this section). +This can be used, for example, to automatically destroy layers or page styles +that rely on commands from the end-user interface (see +\DescRef{\LabelBase.cmd.DestroyLayer}, +\DescRef{\LabelBase.cmd.DestroyPageStyleAlias}, and +\DescRef{\LabelBase.cmd.DestroyRealLayerPageStyle}). Regarding the default for +the optional argument, please refer to the explanation for +\DescRef{\LabelBase.cmd.scrlayerInitInterface}.% +\EndIndexGroup +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: + + diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrlfile.tex b/macros/latex/contrib/koma-script/source-doc/english/scrlfile.tex new file mode 100644 index 0000000000..a01a4a0035 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrlfile.tex @@ -0,0 +1,722 @@ +% ====================================================================== +% scrlfile.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrlfile.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrlfile of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------------- +% +% Kapitel ueber scrlfile in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrlfile.tex} + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (chapter: scrlfile)] +\translator{Gernot Hassenpflug\and Markus Kohm\and Karl Hagen} + +% Date of the translated German file: 2018-02-15 + +\chapter{Controlling Package Dependencies with \Package{scrlfile}} +\labelbase{scrlfile} +\BeginIndexGroup +\BeginIndex{Package}{scrlfile} + +The introduction of \LaTeXe{} in 1994 brought many changes in the handling of +\LaTeX{} extensions. The package author today has a whole series of macros +available to determine if another package or class has been loaded and whether +specific options are being used. The package author can even load other +packages or specify certain options in case the package is loaded later. This +has led to the expectation that the order in which package are loaded would +not be important. Sadly, this hope has not been fulfilled. + +\section{About Package Dependencies} +\seclabel{dependency} +%\begin{Explain} +More and more often, different packages either newly define or redefine the +same macro. In such a case, the order in which a package is loaded becomes +very important. Sometimes, users find it very difficult to understand the +resulting behaviour. Sometimes it is necessary to react in a specific way when +another package is loaded. + +As a simple example, consider loading the \Package{longtable} package with a +\KOMAScript{} document class. The \Package{longtable} package defines its own +table captions. These are perfectly suited to the standard classes, but they +do not match the default settings for \KOMAScript{} captions, nor do they +react to the relevant configuration options. To solve this problem, the +\Package{longtable} package commands which are responsible for the table +captions need to be redefined. However, by the time the \Package{longtable} +package is loaded, the \KOMAScript{} class has already been processed. + +Previously, the only way to solve this problem was to delay the redefinition +until the beginning of the document using \Macro{AtBeginDocument}. However, if +users want to change the relevant commands themselves, they should do so in +the preamble of the document. But this is impossible because \KOMAScript{} +will overwrite the users' definitions at \Macro{begin}\PParameter{document}. +They would also need to perform the redefinition with \Macro{AtBeginDocument}. + +But \KOMAScript{} does not actually need to wait for +\Macro{begin}\PParameter{document} to redefine the macros. It would be +sufficient to postpone the redefinition until after the \Package{longtable} +package has been loaded. Unfortunately, the \LaTeX{} kernel does not define +necessary commands. The \Package{scrlfile} package provides a remedy for this +problem. + +It is also conceivable that you would like to save the definition of a macro +in a temporary macro before a package is loaded and restore it after the +package has been loaded. The \Package{scrlfile} package allows this, too. + +The use of \Package{scrlfile} is not limited to package dependencies. +Dependencies can also be considered for any other file. For example, you can +ensure that loading the not unimportant file \File{french.ldf} automatically +leads to a warning. + +Although the package is particularly of interest for package authors, there +are also applications for normal \LaTeX{} users. Therefore, this chapter +gives examples for both groups. +%\end{Explain} + + +\section{Actions Before and After Loading} +\seclabel{macros} + +The \Package{scrlfile} package can execute actions both before and after +loading files. The commands used to do so distinguish between ordinary files, +classes, and packages. + +\begin{Declaration} + \Macro{BeforeFile}\Parameter{file}\Parameter{commands}% + \Macro{AfterFile}\Parameter{file}\Parameter{commands} +\end{Declaration}% +\Macro{BeforeFile} ensures that the \PName{commands} are executed before the +next time \PName{file} is loaded. \Macro{AfterFile} works in a similar +fashion, and the \PName{commands} will be executed after the \PName{file} has +been loaded. Of course, if \PName{file} is never loaded, the \PName{commands} +will never be executed. For \PName{file}, you should specify any extensions as +part of the file name, as you would with \Macro{input}. + +To implement those features, \Package{scrlfile} redefines the well-known +\LaTeX{} command \Macro{InputIfFileExists}. If this command does not have the +expected definition, \Package{scrlfile} issues a warning. This occurs in case +the command is changed in future \LaTeX{} versions or has already been +redefined by another package. + +\LaTeX{} uses the \Macro{InputIfFileExists} command every time it loads a +file. This occurs regardless of whether the file is loaded with +\Macro{include}, \Macro{LoadClass}, \Macro{documentclass}, \Macro{usepackage}, +\Macro{RequirePackage}, or similar commands. Only +\begin{lstcode} + \input foo +\end{lstcode} +loads the file \texttt{foo} without using +\Macro{InputIfFileExists}. You should therefore always use +\begin{lstcode} + \input{foo} +\end{lstcode} +instead. Notice the parentheses surrounding the file name!% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{BeforeClass}\Parameter{class}\Parameter{commands}% + \Macro{BeforePackage}\Parameter{package}\Parameter{commands} +\end{Declaration}% +These two commands work the same way as \DescRef{\LabelBase.cmd.BeforeFile}. +The only difference is that the \PName{class} or \PName{package} is specified +with its class or package name and not with its file name. That means you +should omit the file extensions \File{.cls} or \File{.sty}.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{AfterClass}\Parameter{class}\Parameter{commands}% + \Macro{AfterClass*}\Parameter{class}\Parameter{commands}% + \Macro{AfterClass+}\Parameter{class}\Parameter{commands}% + \Macro{AfterClass!}\Parameter{class}\Parameter{commands}% + \Macro{AfterAtEndOfClass}\Parameter{class}\Parameter{commands}% + \Macro{AfterPackage}\Parameter{package}\Parameter{commands}% + \Macro{AfterPackage*}\Parameter{package}\Parameter{commands}% + \Macro{AfterPackage+}\Parameter{package}\Parameter{commands}% + \Macro{AfterPackage!}\Parameter{package}\Parameter{commands}% + \Macro{AfterAtEndOfPackage}\Parameter{package}\Parameter{commands} +\end{Declaration}% +The \Macro{AfterClass} and \Macro{AfterPackage} commands work much like +\DescRef{\LabelBase.cmd.AfterFile}. The only difference is that the +\PName{class} or \PName{package} is specified with its class or package name +and not with its file name. That means you should omit the file extensions +\File{.cls} or \File{.sty}. + +The\important[i]{\Macro{AfterClass*}\\\Macro{AfterPackage*}} starred versions +function somewhat differently. If the class or package has already been +loaded, they execute the \PName{commands} immediately rather than waiting +until the next time the class or package is loaded. + +The\important[i]{\Macro{AfterClass+}\\\Macro{AfterPackage+}} +plus\ChangedAt{v3.09}{\Package{scrlfile}} version executes the +\PName{commands} after the class or package has been completely loaded. This +behaviour differs from that of the starred version only if you use the command +when the class or package has begun loading but has not yet finished. If the +class or package has not finished loading, the \PName{commands} will always be +executed before the commands in \Macro{AtEndOfClass} or +\Macro{AtEndOfPackage}. + +If\important[i]{\Macro{AfterClass!}\\\Macro{AfterPackage!}} a class uses +\Macro{AtEndOfClass} or a package uses \Macro{AtEndOfPackage} to execute +commands after the class of package file has been loaded completely, and +if you want to execute \PName{commands} after these deferred +commands have been executed, you can use the exclamation-mark versions +\Macro{AfterClass!}\ChangedAt{v3.09}{\Package{scrlfile}} or +\Macro{AfterPackage!}. + +If\important[i]{\Macro{AfterAtEndOfClass}\\\Macro{AfterAtEndOfPackage}} you +want to execute the \PName{commands} only when the class or package is loaded +later and outside the context of that class or package, you can use +\Macro{AfterAtEndOfClass}\ChangedAt{v3.09}{\Package{scrlfile}} for classes and +\Macro{AfterAtEndOfPackage} for packages. + +\begin{Example} + The following example for class and package authors shows how \KOMAScript{} + itself makes use of the new commands. The class \Class{scrbook} contains the + following: +% CORRECTED MESSAGE: +% You are using an old version of the hyperref +% package!\MessageBreak% +% This version has a buggy hack in many +% drivers,\MessageBreak% +% causing \string\addchap\space to behave +% strangely.\MessageBreak% +% Please update hyperref to at least version +% 6.71b}% +\begin{lstcode} + \AfterPackage{hyperref}{% + \@ifpackagelater{hyperref}{2001/02/19}{}{% + \ClassWarningNoLine{scrbook}{% + You are using an old version of hyperref package!% + \MessageBreak% + This version has a buggy hack at many drivers% + \MessageBreak% + causing \string\addchap\space to behave strange.% + \MessageBreak% + Please update hyperref to at least version + 6.71b}}} +\end{lstcode} + Old versions of the \Package{hyperref} package redefine a macro of the + \Class{scrbook} class in a way that is incompatible with newer \KOMAScript{} + versions. Newer versions of \Package{hyperref} refrain from making this + change if a newer version of \KOMAScript{} is detected. In case + \Package{hyperref} is loaded at a later stage, \Class{scrbook} ensures that + a check for an acceptable version of \Package{hyperref} is performed + immediately after the package is loaded. If this is not the case, a warning + is issued. + + Elsewhere in three of the \KOMAScript{} classes, you can find the following: +\begin{lstcode} + \AfterPackage{caption2}{% + \renewcommand*{\setcapindent}{% +\end{lstcode} + After loading \Package{caption2}, and only if it has been loaded, + \KOMAScript{} redefines its own \DescRef{maincls.cmd.setcapindent} command. + The exact code of the redefinition is irrelevant. The important thing to + note is that \Package{caption2} takes control of the + \DescRef{maincls.cmd.caption} macro and that therefore the normal definition + of the \DescRef{maincls.cmd.setcapindent} command would have no effect. The + redefinition thus improves interoperability with \Package{caption2}. + + There are also, however, instances where these commands are useful to normal + \LaTeX{} users. For example, suppose you create a document from which you + want to generate both a PostScript file, using \LaTeX{} and dvips, and a PDF + file, using \mbox{pdf{\LaTeX}}. The document should also contain hyperlinks. + In the table of contents, you have entries that span several lines. This is + not a problem for the \mbox{pdf{\LaTeX}} method, since here hyperlinks can + be broken across multiple lines. However, this is not possible with the + \Package{hyperref} driver for dvips or \mbox{hyper{\TeX}}. In this case, you + would like \Package{hyperref} to use the \Option{linktocpage} option. The + decision as to which driver is loaded is made automatically by + \File{hyperref}. + + Everything else can now be left to \DescRef{\LabelBase.cmd.AfterFile}: +\begin{lstcode} + \documentclass{article} + \usepackage{scrlfile} + \AfterFile{hdvips.def}{\hypersetup{linktocpage}} + \AfterFile{hypertex.def}{\hypersetup{linktocpage}} + \usepackage{hyperref} + \begin{document} + \listoffigures + \clearpage + \begin{figure} + \caption{This is an example of a fairly long figure caption, but + one that does not use the optional caption argument that would + allow you to write a short caption in the list of figures.} + \end{figure} + \end{document} +\end{lstcode} + If either of the \Package{hyperref} drivers \Option{hypertex} or + \Option{dvips} is used, the useful \Package{hyperref} option + \Option{linktocpage} will be set. However, if you create a PDF file + with \mbox{pdf{\LaTeX}}, the option + will not be set because then the \Package{hyperref} driver + \File{hpdftex.def} will be used. This means that neither \File{hdvips.def} + nor \File{hypertex.def} will be loaded. +\end{Example} +\iffalse% Umbruchkorrekturtext (der besser nicht mehr verwendet wird!) + Furthermore\textnote{Hint!}, you can also load \Package{scrlfile} and the + \DescRef{\LabelBase.cmd.AfterFile} command into a private + \File{hyperref.cfg}. In this case, however, you should use + \Macro{RequirePackage} instead of \Macro{usepackage} to load the package + (see \cite{latex:clsguide}). In the example above, the new lines have to be + inserted directly after the \Macro{ProvidesFile} line, that is, immediately + before the \Option{dvips} or \Option{pdftex} options are executed.% +\fi +Incidentally\textnote{Hint!}, you can also load \Package{scrlfile} before +\DescRef{maincls.cmd.documentclass}\IndexCmd{documentclass}. In this case, +however, you should use \Macro{RequirePackage}\IndexCmd{RequirePackage} +instead of \DescRef{maincls.cmd.usepackage} (see \cite{latex:clsguide}).% +\EndIndexGroup + + +\begin{Declaration} + \Macro{BeforeClosingMainAux}\Parameter{commands}% + \Macro{AfterReadingMainAux}\Parameter{commands}% +\end{Declaration}% +These commands differ in one detail from the commands explained previously. +Those commands enable actions before or after loading files. That is not the +case here. Package authors often want to write something to the \File{aux} +file after the last document page has been shipped out. To do so, ignoring the +resulting problems they create, they often use code such as the following: +\begin{lstcode} + \AtEndDocument{% + \if@filesw + \write\@auxout{% + \protect\writethistoaux% + }% + \fi + } +\end{lstcode} +However, this does not really solve the problem. If the last page of the +document has already been shipped out before \Macro{end}\PParameter{document}, +the code above will not result in any output to the \File{aux} file. If you +try to fix this new problem using \Macro{immediate} just before \Macro{write}, +you would have the opposite problem: if the last page has not yet been shipped +out before \Macro{end}\PParameter{document}, \Macro{writethistoaux} would be +written to the \File{aux} file too early. Therefore you often see solutions +like: +\begin{lstcode} + \AtEndDocument{% + \if@filesw + \clearpage + \immediate\write\@auxout{% + \protect\writethistoaux% + }% + \fi + } +\end{lstcode} +However, this solution has the disadvantage that it forces the last page to be +shipped out. A command such as +\begin{lstcode} + \AtEndDocument{% + \par\vspace*{\fill}% + Note at the end of the document.\par + } +\end{lstcode} +will no longer cause the note to appear beneath the text of the last real page +of the document but at the end of one additional page. Furthermore, +\Macro{writethistoaux} will again be written to the \File{aux} file one page +too early. + +The best solution for this problem would be if you could write directly to the +\File{aux} file immediately after the final \DescRef{maincls.cmd.clearpage} +that is part of \Macro{end}\PParameter{document} but before closing the +\File{aux} file. This is the purpose of \Macro{BeforeClosingMainAux}: +\begin{lstcode} + \BeforeClosingMainAux{% + \if@filesw + \immediate\write\@auxout{% + \protect\writethistoaux% + }% + \fi + } +\end{lstcode} +This will be successful even if the final \DescRef{maincls.cmd.clearpage} +inside of \Macro{end}\PParameter{document} does not actually ship out any page +or if \DescRef{maincls.cmd.clearpage} is used within an \Macro{AtEndDocument} +command. + +However, there one important limitation using \Macro{BeforeClosingMainAux}: +you should not use any typesetting commands inside the \PName{commands} of +\Macro{BeforeClosingMainAux}! If you ignore this restriction, the result is +just as unpredictable as the results of the problematic suggestions above that +use \Macro{AtEndDocument}. + +The \Macro{AfterReadingMainAux}\ChangedAt{v3.03}{\Package{scrlfile}} command +actually executes the \PName{commands} after closing and reading the +\File{aux} file inside \Macro{end}\PParameter{document}. This is only useful +in a few very rare cases, for example to write statistical information to the +\File{log} file which is valid only after reading the \File{aux} file, or to +implement additional \emph{rerun} requests. Typesetting commands are even more +dangerous inside these \PName{commands} than inside the argument of +\Macro{BeforeClosingMainAux}.% +% +\EndIndexGroup + + +\section{Replacing Files at Input} +\seclabel{replace} + +The previous sections in this chapter have explained commands to perform +actions before or after loading a particular file, package, or class. You can +also use \Package{scrlfile} to input a completely different file than the one +that was requested. + + +\begin{Declaration} + \Macro{ReplaceInput}\Parameter{original file}% + \Parameter{replacement file}% +\end{Declaration}% +This\ChangedAt{v2.96}{\Package{scrlfile}} command defines a replacement for +the file specified in the first argument, \PName{original file}. If \LaTeX{} +is instructed to load this file, the \PName{replacement file} will be loaded +instead. The replacement-file definition affects all files loaded using +\Macro{InputIfFileExists}, whether they are loaded by the user or internally +by \LaTeX{}. To do so, \Package{scrlfile} redefines \Macro{InputIfFileExists}. + +\begin{Example} + You want to input the \File{\Macro{jobname}.xua} file instead of the + \File{\Macro{jobname.aux}} file. To do this, you use +\begin{lstcode} + \ReplaceInput{\jobname.aux}{\jobname.xua} +\end{lstcode} + If additionally you replace \File{\Macro{jobname}.xua} by + \File{\Macro{jobname}.uxa} using +\begin{lstcode} + \ReplaceInput{\jobname.xua}{\jobname.uxa} +\end{lstcode} + then \File{\Macro{jobname}.aux} will also be replaced by + \File{\Macro{jobname}.uxa}. In this way, you can process the whole + replacement chain. + + However, a replacement that results in a loop such as +\begin{lstcode} + \ReplaceInput{\jobname.aux}{\jobname.xua} + \ReplaceInput{\jobname.xua}{\jobname.aux} +\end{lstcode} + will cause a \emph{stack size error}. So it is not possible to replace + a file that has already been replaced once by itself again. +\end{Example} + +In theory, it would also be possible to use this command to replace one +package or class with another. But \LaTeX{} would recognize that the requested +file name does not match the name of the package or class. You can find a +solution for this problem below.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ReplaceClass}\Parameter{original class}% + \Parameter{replacement class}% + \Macro{ReplacePackage}\Parameter{original package}% + \Parameter{replacement package}% +\end{Declaration}% +You\ChangedAt{v2.96}{\Package{scrlfile}}\textnote{Attention!} should never +replace a class or package using the \DescRef{\LabelBase.cmd.ReplaceInput} +command described above. Doing so would result in a \LaTeX{} warning about +mismatched class or package names. Real errors are also possible if a class or +package is loaded under an incorrect file name. +\begin{Example} + You replace the \Package{scrpage2} package with its official successor, + \Package{scrlayer-scrpage}, by using +\begin{lstcode}[escapechar=\$] + \ReplaceInput{scrpage2.sty}{scrlayer-scrpage.sty}$\textnote{Do not try this!}$ +\end{lstcode} + Loading \Package{scrpage2} will then lead to the following warning: +\begin{lstcode} + LaTeX warning: You have requested `scrpage2', + but the package provides `scrlayer-scrpage'. +\end{lstcode} + Users may be greatly confused by such a warning because they requested not + \Package{scrlayer-scrpage} but \Package{scrpage2}, which was replaced by + \Package{scrlayer-scrpage}. +\end{Example} +One solution to this problem is to use \Macro{ReplaceClass} or +\Macro{ReplacePackage} instead of \DescRef{\LabelBase.cmd.ReplaceInput}. Note +that in this case, as with \Macro{documentclass} and \Macro{usepackage}, you +should give the name of the class or package and not the complete file name. + +The replacement class works for all classes loaded with +\Macro{documentclass}, \Macro{LoadClassWithOptions}, or \Macro{LoadClass}. The +replacement package works for all packages loaded with +\Macro{usepackage}, \Macro{RequirePackageWithOptions}, or +\Macro{RequirePackage}. + +Please\textnote{Attention!} note that the \PName{replacement class} or the +\PName{replacement package} will be loaded with the same options that would +have been passed to the \PName{original class} or \PName{original package}. If +you replace a class or package with one that does not support a requested +option, you will receive the usual warnings and errors. However, you can +declare such missing options using \DescRef{\LabelBase.cmd.BeforeClass} or +\DescRef{\LabelBase.cmd.BeforePackage}. + +\begin{Example} + Suppose you want to replace the \Package{oldfoo} package with the + \Package{newfoo} package when the former package is loaded. You can do this with +\begin{lstcode} + \ReplacePackage{oldfoo}{newfoo} +\end{lstcode} + Suppose the old package provides an \Option{oldopt} option, but the new + package does not. With +\begin{lstcode} + \BeforePackage{newfoo}{% + \DeclareOption{oldopt}{% + \PackageInfo{newfoo}% + {option `oldopt' not supported}% + }}% +\end{lstcode} + you can declare this missing option for the \Package{newfoo} package. This + avoids an error message when the \Package{oldfoo} package is loaded with the + option that is unsupported by \Package{newfoo}. + + If, on the other hand, the \Package{newfoo} package supports a + \Option{newopt} option that should be used instead of the \Option{oldopt} + option, you can also achieved this: +\begin{lstcode} + \BeforePackage{newfoo}{% + \DeclareOption{oldopt}{% + \ExecuteOptions{newopt}% + }}% +\end{lstcode} + You can even specify different default options that apply when loading the + new package: +\begin{lstcode} + \BeforePackage{newfoo}{% + \DeclareOption{oldopt}{% + \ExecuteOptions{newopt}% + }% + \PassOptionsToPackage{newdefoptA,newdefoptB}% + {newfoo}% + } +\end{lstcode} + or directly: +\begin{lstcode} + \BeforePackage{newfoo}{% + \DeclareOption{oldopt}{% + \ExecuteOptions{newopt}% + }% + }% + \PassOptionsToPackage{newdefoptA,newdefoptB}% + {newfoo}% +\end{lstcode} + Note that in the last example, the call to \Macro{PassOptionsToPackage} + occurs not within but after \Macro{BeforePackage} +\end{Example} + +Of course, to replace classes, you must load \Package{scrlfile} before the +class using \Macro{RequirePackage} instead of \Macro{usepackage}. +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{UnReplaceInput}\Parameter{file name}% + \Macro{UnReplacePackage}\Parameter{package}% + \Macro{UnReplaceClass}\Parameter{class}% +\end{Declaration} +You\ChangedAt{v3.12}{\Package{scrlfile}} can also remove a replacement. You +should remove the replacement definition for an input file using +\Macro{UnReplaceInput}, for a package using \Macro{UnReplacePackage}, and for +a class using \Macro{UnReplaceClass}.% +\EndIndexGroup + + +\section{Preventing File Loading} +\seclabel{prevent} + +Classes\ChangedAt{v3.08}{\Package{scrlfile}} and packages written for use +within companies or academic institutions often load many packages only +because users need them frequently, not because they are required by the class +or package itself. If a problem occurs with one of these automatically loaded +packages, you somehow have to keep the problematic package from being loaded. +Once again, \Package{scrlfile} provides a simple solution. + +\begin{Declaration} + \Macro{PreventPackageFromLoading}\OParameter{alternate code}% + \Parameter{package list}% + \Macro{PreventPackageFromLoading*}\OParameter{alternate code}% + \Parameter{package list} +\end{Declaration} +Calling this command\ChangedAt{v3.08}{\Package{scrlfile}} before loading a +package with \Macro{usepackage}\IndexCmd{usepackage}, +\Macro{RequirePackage}\IndexCmd{RequirePackage}, or +\Macro{RequirePackageWithOptions}\IndexCmd{RequirePackageWithOptions} +effectively prevents the package from being loaded if it is found in the the +\PName{package list}. +% +\begin{Example} + Suppose you work at a company where all documents are created using Latin + Modern. The company class, \Class{compycls}, therefore contains these lines: +\begin{lstcode} + \RequirePackage[T1]{fontenc} + \RequirePackage{lmodern} +\end{lstcode} + But now, for the first time, you want to use \XeLaTeX{} or Lua\LaTeX{}. + Since the recommended \Package{fontspec} package uses Latin Modern as the + default font anyway, and loading \Package{fontenc} would not be a good idea, + you want to prevent both packages from being loaded. Therefore, you load the + class in your own document as follows: +\begin{lstcode} + \RequirePackage{scrlfile} + \PreventPackageFromLoading{fontenc,lmodern} + \documentclass{firmenci} +\end{lstcode} +\end{Example} +The example above also shows that you can load \Package{scrlfile} before the +class. In this case, you must use +\Macro{RequirePackage}\IndexCmd{RequirePackage} because \Macro{usepackage} +before \Macro{documentclass} is not permitted. + +If you specify an empty \PName{package list} or if it contains a package that +has already been loaded, \Macro{PreventPackageFromLoading} issues a warning, +while\ChangedAt{v3.12}{\Package{scrlfile}} \Macro{PreventPackageFromLoading*} +merely writes a note to the log file only. + +You\ChangedAt{v3.12}{\Package{scrlfile}} can use the optional argument to +execute code instead of loading the package. But you cannot load any other +packages or files inside \PName{alternate code}. To load another package, see +\DescRef{\LabelBase.cmd.ReplacePackage} in \autoref{sec:scrlfile.macros} on +\DescPageRef{\LabelBase.cmd.ReplacePackage}. Note also that the +\PName{alternate code} will be executed several times if you try to load the +package more than once!% +\EndIndexGroup + + +\begin{Declaration} + \Macro{StorePreventPackageFromLoading}\Parameter{\textMacro{command}}% + \Macro{ResetPreventPackageFromLoading} +\end{Declaration} +\Macro{StorePreventPackageFromLoad}\ChangedAt{v3.08}{\Package{scrlfile}} +defines \Macro{command} to be the current list of packages that should not be +loaded. In contrast, +\Macro{ResetPreventPackageFromLoading}\ChangedAt{v3.08}{\Package{scrlfile}} +resets the list of packages that should not be loaded. After +\Macro{ResetPreventPackageFromLoading}, you can load all packages again. +\begin{Example} + Suppose you need to load a package inside another package and you do not + want the user to be able to prevent that package from being loaded with + \DescRef{\LabelBase.cmd.PreventPackageFromLoading}% + \IndexCmd{PreventPackageFromLoading}. So you reset the do-not-load list + before you load this package: +\begin{lstcode} + \ResetPreventPackageFromLoading + \RequirePackage{foo} +\end{lstcode} + Unfortunately, from this point on the user's entire do-not-load list would + be lost. To avoid this, you first store the list and then restore it later: +\begin{lstcode} + \newcommand*{\Users@PreventList}{}% + \StorePreventPackageFromLoading\Users@PreventList + \ResetPreventPackageFromLoading + \RequirePackage{foo} + \PreventPackageFromLoading{\Users@PreventList} +\end{lstcode} + Note\textnote{Attention!} that \Macro{StorePreventPackageFromLoading} + defines the \Macro{Users@PreventList} macro even if it has already been + defined. In other words, calling \Macro{StorePreventPackageFromLoading} + overwrites existing \Macro{command} definitions without checking. Therefore + this example uses \Macro{newcommand*} to get an error message if + \Macro{Users@PreventList} has already been defined. +\end{Example} +Note that when you manipulate the list stored by +\Macro{StorePreventPackageFromLoading}, you are responsible for making sure it +can be restored. For example, the list elements must be separated by comma, +must not contain white space or group braces, and must be fully expandable. + +Also note\textnote{Attention!}, that \Macro{ResetPreventPackageFromLoading} +does not clear the \PName{alternate code} for a package. But this code +will not be executed so long as the package is not added again to the +do-not-load list.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{UnPreventPackageFromLoading}\Parameter{package list}% + \Macro{UnPreventPackageFromLoading*}\Parameter{package list} +\end{Declaration} +Instead\ChangedAt{v3.12}{\Package{scrlfile}} of completely resetting the list +of packages that should not be loaded, you can also specify individual +packages to remove from the list. The starred version of the command also +deletes the \PName{alternate code}. For example, restoring packages to the +do-not-load list from a stored list will not reactivate their \PName{alternate +code} in this case.% +% +\begin{Example} + Suppose you want to prevent a \Package{foo} package from being loaded, but + you do not want to execute any outdated \PName{alternate code} that may + exist. Instead, only your new \PName{alternate code} should be executed. You + can do this as follows: +\begin{lstcode} + \UnPreventPackageFromLoading*{foo} + \PreventPackageFromLoading[\typeout{alternate code}]{foo} +\end{lstcode} + For the \Macro{UnPreventPackageFromLoading} command, it does not matter + whether or not the package has been prevented from being loaded before. + + Of course you can also use the command to indirectly delete the + \PName{alternate code} of all packages: +\begin{lstcode} + \StorePreventPackageFromLoading\TheWholePreventList + \UnPreventPackageFromLoading*{\TheWholePreventList} + \PreventPackageFromLoading{\TheWholePreventList} +\end{lstcode} + In this case the packages that have been prevented from being loaded are + still prevented from being loaded, but their \PName{alternate code} has been + deleted and will no longer be executed.% +\end{Example}% +\EndIndexGroup +% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% ispell-local-dictionary: "english" +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrlttr2-experts.tex b/macros/latex/contrib/koma-script/source-doc/english/scrlttr2-experts.tex new file mode 100644 index 0000000000..ffb397b6d2 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrlttr2-experts.tex @@ -0,0 +1,1897 @@ +% ====================================================================== +% scrlttr2-experts.tex +% Copyright (c) Markus Kohm, 2002-2019 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrlttr2-experts.tex +% Copyright (c) Markus Kohm, 2002-2019 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrlttr2 of the KOMA-Script guide expert part +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber scrlttr2 im Experten-Teil der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrlttr2-experts.tex} + [$Date: 2019-01-15 08:29:44 +0100 (Tue, 15 Jan 2019) $ + KOMA-Script guide (chapter: scrlttr2 for experts)] + +\translator{Harald Bongartz\and Georg Grandke\and Raimund Kohl\and Jens-Uwe + Morawski\and Stephan Hennig\and Gernot Hassenpflug\and Markus Kohm\and + Karl Hagen} + +% Date of the translated German file: 2018-07-20 + +\chapter{Additional Information about the \Class{scrlttr2} Class and the + \Package{scrletter} Package} +\labelbase{scrlttr2-experts} + +\BeginIndexGroup +\BeginIndex{Class}{scrlttr2} +This chapter provides additional information about the \KOMAScript{} class +\Class{scrlttr2}. \iffree{Some parts of the chapter are found only in the + German \KOMAScript{} book \cite{book:komascript}. This should not be a + problem, because the}{The} average user, who only wants to use the class +or package, will not normally need this information. Part of this information +is addressed to users for whom the default options are insufficient. Thus, +for example, the first section describes in detail the pseudo-lengths that +specify the letterhead page and which can be used be used to modify the its +layout.% +\iffalse% Es wird Zeit das komplett rauszuwerfen! + In addition, this chapter also describes features that exist only to + provide compatibility with the deprecated \Class{scrlettr} class. It also + explains in detail how to convert a document from this obsolete class + to the current class. +\fi + +\BeginIndex{Package}{scrletter}% +Starting with \KOMAScript~3.15\ChangedAt[2014/11]{v3.15}{\Package{scrletter}}, +you can use the \Package{scrletter} package with one of the \KOMAScript{} +classes \Class{scrartcl}, \Class{scrreprt}, or \Class{scrbook}. It provides +nearly all the features of \Class{scrlttr2} for those classes. There are, +however, a few differences described later in this chapter.% + + +\section{Pseudo-Lengths for Experienced Users} +\seclabel{pseudoLengths} +\BeginIndexGroup +\BeginIndex{}{pseudo-lengths} + +\TeX{} works with a fixed number of registers. There are registers for tokens, +for boxes, for counters, for skips, and for dimensions. Overall there are 256 +registers for each of these categories. For \LaTeX{} lengths, which are +defined with \Macro{newlength}, skip registers are used. Once all these +registers are in use, you can not define any more lengths. Both +\Class{scrlttr2} and \Package{scrletter} would normally use more than 20 of +these registers for the first page alone. \LaTeX{} itself already uses 40 of +these registers. The \hyperref[cha:typearea]{\Package{typearea}}% +\IndexPackage{typearea} package needs some of them too; thus, approximately a +quarter of these precious registers would already be in use. For this reason, +\KOMAScript{} stores letter-specific lengths in macros instead of lengths. The +drawback of this approach is that computations with macros are somewhat more +complicated than with real lengths. + +Note\textnote{Attention!} that 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 written without the initial +backslash, like the names of \LaTeX{} counters and unlike macros or \LaTeX{} +lengths. + +Anyone who wants to argue that the recommended \LaTeX{} installation with +\eTeX{}, which is required for \KOMAScript{} anyway, no longer suffers from +the above-mentioned limitation would be right. However, that improvement came +too late for \Class{scrlttr2}. With \Package{scrletter}, the concept of +psuedo-lengths was adopted for reasons of compatibility. + +The pseudo-lengths defined and uses by \KOMAScript{} are listed in +\autoref{tab:scrlttr2-experts.pseudoLength}, which also provides cross +references to the detailed descriptions of each pseudo-lengths in the +following sub-sections. + +A schematic display of the most important distances of the letterhead page is +shown in \autoref{fig:scrlttr2-experts.pseudoLength} on +\autopageref{fig:scrlttr2-experts.pseudoLength}. In addition to the +pseudo-lengths for the configurable distances, some non-configurable lengths +are also shown in light gray. For the sake of clarity, however, some rarely +required pseudo-lengths have been omitted. +% +\begin{desclist} + \renewcommand{\abovecaptionskipcorrection}{-\normalbaselineskip}% + \desccaption{% + Pseudo-lengths provided by \Class{scrlttr2} and \Package{scrletter}% + \label{tab:scrlttr2-experts.pseudoLength}% + }{% + Pseudo-lengths provided by \Class{scrlttr2} and \Package{scrletter} + (\emph{continued})% + }% + \pentry{backaddrheight}{% + the height of the return address at the upper edge of the address field + (\autoref{sec:scrlttr2-experts.addressee}, + \DescPageRef{scrlttr2-experts.plength.backaddrheight})% + }% + \pentry{bfoldmarklength}{% + the length of the bottommost fold mark + (\autoref{sec:scrlttr2-experts.foldmarks}, + \DescPageRef{scrlttr2-experts.plength.bfoldmarkvpos})% + }% + \pentry{bfoldmarkvpos}{% + the vertical distance of the bottommost fold mark from the top edge of the + paper (\autoref{sec:scrlttr2-experts.foldmarks}, + \DescPageRef{scrlttr2-experts.plength.bfoldmarkvpos})% + }% + \pentry{firstfoothpos}{% + the horizontal distance of the letterhead page footer from the left edge + of the paper; values greater than the width of the paper or less than the + negative value of the width of the paper activate special handling % + (\autoref{sec:scrlttr2-experts.firstFoot}, + \DescPageRef{scrlttr2-experts.plength.firstfoothpos})% + }% + \pentry{firstfootvpos}{% + the vertical distance of letterhead page footer from the top edge of the + paper (\autoref{sec:scrlttr2-experts.firstFoot}, + \DescPageRef{scrlttr2-experts.plength.firstfootvpos})% + }% + \pentry{firstfootwidth}{% + the width of the letterhead page footer + (\autoref{sec:scrlttr2-experts.firstFoot}, + \DescPageRef{scrlttr2-experts.plength.firstfootwidth})% + }% + \pentry{firstheadhpos}{% + the horizontal distance of the letterhead from the left edge of the paper; + values greater than the width of the paper or less than the negative value + of the width of the paper activate special handling + (\autoref{sec:scrlttr2-experts.firstHead}, + \DescPageRef{scrlttr2-experts.plength.firstheadhpos})% + }% + \pentry{firstheadvpos}{% + the vertical distance of the letterhead from the top edge of the paper + (\autoref{sec:scrlttr2-experts.firstHead}, + \DescPageRef{scrlttr2-experts.plength.firstheadvpos})% + }% + \pentry{firstheadwidth}{% + the width of the letterhead (\autoref{sec:scrlttr2-experts.firstHead}, + \DescPageRef{scrlttr2-experts.plength.firstheadwidth})% + }% + \pentry{foldmarkhpos}{% + the horizontal distance of the horizontal fold marks from the left edge of + the paper (\autoref{sec:scrlttr2-experts.foldmarks}, + \DescPageRef{scrlttr2-experts.plength.foldmarkhpos})% + }% + \pentry{foldmarkvpos}{% + the vertical distance of the vertical fold marks from the top edge of the + paper (\autoref{sec:scrlttr2-experts.foldmarks}, + \DescPageRef{scrlttr2-experts.plength.foldmarkvpos})% + }% + \pentry{fromrulethickness}{% + the thickness of an optional horizontal rule in the letterhead + (\autoref{sec:scrlttr2-experts.firstHead}, + \DescPageRef{scrlttr2-experts.plength.fromrulethickness})% + }% + \pentry{fromrulewidth}{% + the length of an optional horizontal rule in the letterhead + (\autoref{sec:scrlttr2-experts.firstHead}, + \DescPageRef{scrlttr2-experts.plength.fromrulewidth})% + }% + \pentry{lfoldmarkhpos}{% + the horizontal distance of the vertical fold mark from the left edge of + the paper (\autoref{sec:scrlttr2-experts.foldmarks}, + \DescPageRef{scrlttr2-experts.plength.lfoldmarkhpos})% + }% + \pentry{lfoldmarklength}{% + the length of the vertical fold mark + (\autoref{sec:scrlttr2-experts.foldmarks}, + \DescPageRef{scrlttr2-experts.plength.lfoldmarklength})% + }% + \pentry{locheight}{% + the height of the field containing the additional sender information if + the value is not 0; if it is 0, \PLength{toaddrheight} is used instead + (\autoref{sec:scrlttr2-experts.locationField}, + \DescPageRef{scrlttr2-experts.plength.locheight})% + }% + \pentry{lochpos}{% + the horizontal distance of the field containing the additional sender + information; if the value is positive, the distance is measured from the + right paper edge; if negative, from the left paper edge; if 0, the + negative value of \PLength{toaddrhpos} is used instead + (\autoref{sec:scrlttr2-experts.locationField}, + \DescPageRef{scrlttr2-experts.plength.lochpos})% + }% + \pentry{locvpos}{% + the vertical distance of the field containing the additional sender + information from the top edge of the paper if the value is not 0; if it is + 0, \PLength{toaddrvpos} is used instead + (\autoref{sec:scrlttr2-experts.locationField}, + \DescPageRef{scrlttr2-experts.plength.locvpos})% + }% + \pentry{locwidth}{% + the width of the field containing the additional sender information; if it + is 0, the width is calculated automatically based on the + \DescRef{scrlttr2.option.locfield} option described in + \autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.locfield} % + (\autoref{sec:scrlttr2-experts.locationField}, + \DescPageRef{scrlttr2-experts.plength.locwidth})% + }% + \pentry{mfoldmarklength}{% + the length of the middle horizontal fold mark + (\autoref{sec:scrlttr2-experts.foldmarks}, + \DescPageRef{scrlttr2-experts.plength.mfoldmarklength})% + }% + \pentry{mfoldmarkvpos}{% + the vertical distance of the middle horizontal fold mark from the top edge + of the paper (\autoref{sec:scrlttr2-experts.foldmarks}, + \DescPageRef{scrlttr2-experts.plength.mfoldmarkvpos})% + }% + \pentry{pfoldmarklength}{% + the length of the hole-punch mark + (\autoref{sec:scrlttr2-experts.foldmarks}, + \DescPageRef{scrlttr2-experts.plength.pfoldmarklength})% + }% + \pentry{PPdatamatrixvskip}{% + the vertical distance between the postpaid header and the data array with + \OptionValueRef{scrlttr2}{addrfield}{PP} + (\autoref{sec:scrlttr2-experts.addressee}, + \DescPageRef{scrlttr2-experts.plength.PPdatamatrixvskip})% + }% + \pentry{PPheadheight}{% + the height of the postpaid header + (\autoref{sec:scrlttr2-experts.addressee}, + \DescPageRef{scrlttr2-experts.plength.PPheadheight})% + }% + \pentry{PPheadwidth}{% + the width of the left postpaid field with + \OptionValueRef{scrlttr2}{addrfield}{PP} + (\autoref{sec:scrlttr2-experts.addressee}, + \DescPageRef{scrlttr2-experts.plength.PPheadwidth})% + }% + \pentry{refaftervskip}{% + vertical skip below reference-field line % + (\autoref{sec:scrlttr2-experts.refLine}, + \DescPageRef{scrlttr2-experts.plength.refaftervskip})% + }% + \pentry{refhpos}{% + the horizontal distance of reference-field line from the left + edge of the paper; if the value is 0, the reference-field line is centred + horizontally on the letterhead page + (\autoref{sec:scrlttr2-experts.refLine}, + \DescPageRef{scrlttr2-experts.plength.refhpos})% + }% + \pentry{refvpos}{% + the vertical distance of reference-field line from the top + edge of the paper (\autoref{sec:scrlttr2-experts.refLine}, + \DescPageRef{scrlttr2-experts.plength.refvpos})% + }% + \pentry{refwidth}{% + the width of the reference-field line + (\autoref{sec:scrlttr2-experts.refLine}, + \DescPageRef{scrlttr2-experts.plength.refwidth})% + }% + \pentry{sigbeforevskip}{% + the vertical skip between the closing and the signature + (\autoref{sec:scrlttr2-experts.closing}, + \DescPageRef{scrlttr2-experts.plength.sigbeforevskip})% + }% + \pentry{sigindent}{% + the indentation of the signature with respect to the text body + (\autoref{sec:scrlttr2-experts.closing}, + \DescPageRef{scrlttr2-experts.plength.sigindent})% + }% + \pentry{specialmailindent}{% + the left indentation of the delivery method within the address field + (\autoref{sec:scrlttr2-experts.addressee}, + \DescPageRef{scrlttr2-experts.plength.specialmailindent})% + }% + \pentry{specialmailrightindent}{% + the right indentation of the delivery method within the address field + (\autoref{sec:scrlttr2-experts.addressee}, + \DescPageRef{scrlttr2-experts.plength.specialmailrightindent})% + }% + \pentry{subjectaftervskip}{% + the vertical skip after the subject + (\autoref{sec:scrlttr2-experts.subject}, + \DescPageRef{scrlttr2-experts.plength.subjectaftervskip})% + }% + \pentry{subjectbeforevskip}{% + additional vertical skip before the subject + (\autoref{sec:scrlttr2-experts.subject}, + \DescPageRef{scrlttr2-experts.plength.subjectbeforevskip})% + }% + \pentry{subjectvpos}{% + the vertical distance of the subject from the top edge of the paper; if it + is 0, the position is calculated based on the + \DescRef{scrlttr2.option.subject} option + (\autoref{sec:scrlttr2-experts.subject}, + \DescPageRef{scrlttr2-experts.plength.subjectaftervskip})% + }% + \pentry{tfoldmarklength}{% + the length of the topmost horizontal fold mark + (\autoref{sec:scrlttr2-experts.foldmarks}, + \DescPageRef{scrlttr2-experts.plength.tfoldmarklength})% + }% + \pentry{tfoldmarkvpos}{% + the vertical distance of the topmost horizontal folding mark from the top + edge of the paper (\autoref{sec:scrlttr2-experts.foldmarks}, + \DescPageRef{scrlttr2-experts.plength.tfoldmarkvpos})% + }% + \pentry{toaddrheight}{% + the height of the address field (\autoref{sec:scrlttr2-experts.addressee}, + \DescPageRef{scrlttr2-experts.plength.toaddrheight})% + }% + \pentry{toaddrhpos}{% + the horizontal distance of the address field from left edge of the paper, + if the value is positive; if it is negative, the negative horizontal + distance of the address field from the right edge of the paper + (\autoref{sec:scrlttr2-experts.addressee}, + \DescPageRef{scrlttr2-experts.plength.toaddrhpos})% + }% + \pentry{toaddrindent}{% + the left and right indentation of the address within the address field + (\autoref{sec:scrlttr2-experts.addressee}, + \DescPageRef{scrlttr2-experts.plength.toaddrindent})% + }% + \pentry{toaddrvpos}{% + the vertical distance of the address field from the the top edge of the + paper (\autoref{sec:scrlttr2-experts.addressee}, + \DescPageRef{scrlttr2-experts.plength.toaddrvpos})% + }% + \pentry{toaddrwidth}{% + the width of the address field % + (\autoref{sec:scrlttr2-experts.addressee}, + \DescPageRef{scrlttr2-experts.plength.toaddrwidth})% + }% +\end{desclist} + +\begin{figure} + \centering + \includegraphics{plenDIN} + \caption{Schematic of the pseudo-lengths for a letter} + \label{fig:scrlttr2-experts.pseudoLength} +\end{figure} + + +\begin{Declaration} + \Macro{newplength}\Parameter{name} +\end{Declaration} +This\ChangedAt{v3.26}{\Class{scrlttr2}\and \Package{scrletter}} command +defines a new pseudo-length. The new pseudo-length is uniquely identified by +its \PName{name}. Each name can therefore be assigned only once. If you +attempt to redefine an existing pseudo-length, the commands exits with an +error message. + +\BeginIndex{Cmd}{@newplength}% +Since the ordinary user does not normally need to define pseudo-lengths, this +command was not a user instruction until \KOMAScript~3.26. Before then, +\Macro{@newplength} existed with the same functionality. This instruction still +exists for package authors.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{setplength}% + \OParameter{factor}\Parameter{pseudo-length}\Parameter{value}% + \Macro{addtoplength}% + \OParameter{factor}\Parameter{pseudo-length}\Parameter{value} +\end{Declaration} +Using \Macro{setplength}, you can assign the multiple of a +\PName{value} to a \PName{pseudo-length}. The \PName{factor} is given as an +optional argument (see also \DescRef{scrlttr2.cmd.setlengthtoplength}, +\autoref{sec:scrlttr2.pseudoLength}, +\DescPageRef{scrlttr2.cmd.setlengthtoplength}). + +With \Macro{addtoplength} you can add the multiple of a \PName{value} to a +\PName{pseudo-length}. Again, you can pass a \PName{factor} as an optional +argument. + +To assign or to add the multiple of one \PName{pseudo-length} to another +pseudo-length, use the \Macro{useplength} command (see +\autoref{sec:scrlttr2.pseudoLength}, \DescPageRef{scrlttr2.cmd.useplength}) +within the \PName{value}. To subtract the value of one \PName{pseudo-length} +from another \PName{pseudo-length}, you use should use at the same time a +minus sign or \PValue{-1} as the \PName{factor}. + +\BeginIndex{Cmd}{@setplength}% +\BeginIndex{Cmd}{@addtoplength}% +Since the ordinary user does not normally need to define pseudo-lengths, these +commands were not user instructions until \KOMAScript~3.26. Before then, +\Macro{@setplength} and \Macro{@addtoplength} existed with the +same functionality. These commands still exist for the use of package authors.% +\EndIndexGroup + +\begin{Declaration} + \Macro{setplengthtowidth} + \OParameter{factor}\Parameter{pseudo-length}\Parameter{content}% + \Macro{setplengthtoheight} + \OParameter{factor}\Parameter{pseudo-length}\Parameter{content}% + \Macro{setplengthtodepth} + \OParameter{factor}\Parameter{pseudo-length}\Parameter{content}% + \Macro{setplengthtototalheight} + \OParameter{factor}\Parameter{pseudo-length}\Parameter{content}% +\end{Declaration} +The\ChangedAt{v3.26}{\Class{scrlttr2}\and \Package{scrletter}} first three +commands essentially correspond with \Macro{settowidth}, +\Macro{settoheight}, and \Macro{settodepth} from the \LaTeX{} kernel, but set +\PName{pseudo-length}s instead of lengths. Like +\DescRef{\LabelBase.cmd.setplength}, these commands extend their \LaTeX{} +kernel equivalents with an optional \PName{factor}. They set a +\PName{pseudo-length} to the natural width, height or depth of the given +\PName{content}, multiplied by the optional \PName{factor}. The additional +command \Macro{setplengthtototalheight} sets the \PName{pseudo-length} to the +sum of the height and depth of \PName{content} multiplied by the optional +\PName{factor}.% +\EndIndexGroup + + +\subsection{Fold Marks} +\seclabel{foldmarks} +\BeginIndexGroup +\BeginIndex{}{fold marks}% +\index{marks>folding|see{fold marks}} + +Fold marks, or folding marks, are short horizontal lines at the left edge, and +short vertical lines at the upper edge of the paper. \KOMAScript{} currently +supports three configurable horizontal and one configurable vertical fold +marks. In addition, there is support for a hole-punch mark, or centre mark, +which cannot be shifted vertically. + +\begin{Declaration} + \PLength{tfoldmarkvpos}% + \PLength{mfoldmarkvpos}% + \PLength{bfoldmarkvpos} +\end{Declaration} +\KOMAScript{} recognises a total of three fold marks whose vertical position +can be configured. The distance of the top fold mark from the upper edge of +the paper is determined by the \PLength{tfoldmarkvpos} pseudo-length; the +distance of the middle fold mark, by the +\PLength{mfoldmarkvpos}\ChangedAt{v2.97e}{\Class{scrlttr2}} pseudo-length; the +distance of the bottommost fold mark, by \PLength{bfoldmarkvpos} +pseudo-length. With the addition of the hole-punch\Index{hole-punch mark} or +centre\Index{centre mark|see{hole-punch mark}} mark, there is yet a fourth +horizontal mark. This one is however always placed at the vertical centre of +the paper. +\iftrue% Umbruchkorrekturtext +There is no pseudo-length for this last mark because its vertical position is +not configurable. +\fi + +The\textnote{Attention!} top and bottom fold marks do not serve to divide the +paper exactly into equal thirds. Instead, the paper should be folded with +their help such that the address field can be seen in a window envelope. The +settings are therefore different depending on the \File{lco} file chosen. +Several such files are available offering predefined formats. One format +particularly worth noting is \Option{DINmtext}. This format assumes an +envelope format of C6/5 (also known as ``C6 long''). Letters written with this +option are typically not suited for C5 or C4 envelopes. + +The middle fold mark is not normally required for Western letters. In Japan, +however, a larger number of envelope formats exists, requiring one more fold +mark (see the Japanese \File{lco} files). Note that the terms ``top'', +``middle'', and ``bottom'' fold marks only represent a naming convention. In +fact, it is not required that \PLength{tfoldmarkvpos} must be smaller than +\PLength{mfoldmarkvpos}, which in turn must be smaller than +\PLength{bfoldmarkvpos}. If, though, one of the pseudo-lengths is zero, then +the corresponding fold mark will not be set even if the +\DescRef{scrlttr2.option.foldmarks}\IndexOption{foldmarks~=\PName{setting}}% +\important{\DescRef{scrlttr2.option.foldmarks}} option (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.foldmarks}) is +explicitly activated. +% +\EndIndexGroup + + +\begin{Declaration} + \PLength{tfoldmarklength}% + \PLength{mfoldmarklength}% + \PLength{bfoldmarklength}% + \PLength{pfoldmarklength} +\end{Declaration} +These\ChangedAt{v2.97e}{\Class{scrlttr2}} four pseudo-lengths determine the +lengths of the four horizontal fold marks. One\textnote{Attention!} feature is +particularly worth noting. If the length is given as zero, then the three +vertically configurable pseudo-lengths \PLength{tfoldmarklength}, +\PLength{mfoldmarklength} and \PLength{bfoldmarklength} are set to 2\Unit{mm}. +The length of the hole-punch mark, \PLength{pfoldmarklength}, however, is set +to 4\Unit{mm}.% +\EndIndexGroup + + +\begin{Declaration} + \PLength{foldmarkhpos} +\end{Declaration} +This pseudo-length gives the distance of all horizontal fold marks from the +left edge of the paper. Normally, this is 3.5\Unit{mm}. You\textnote{Hint!} +can change this value in your own \File{lco} file if you are using a printer +that has a wider unprintable left margin. Whether the fold marks are typeset +at all depends on the option \DescRef{scrlttr2.option.foldmarks}% +\important{\DescRef{scrlttr2.option.foldmarks}}% +\IndexOption{foldmarks~=\PName{setting}} (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.foldmarks}). +% +\EndIndexGroup + + +\begin{Declaration} + \PLength{lfoldmarkhpos} +\end{Declaration} +In\ChangedAt{v2.97e}{\Class{scrlttr2}} addition to the horizontal fold marks, +there is also a vertical fold mark. Its distance from the left margin is set +via the \PLength{lfoldmarkhpos} pseudo-length. This fold mark is used, for +example, in Japanese Chou- or You-format envelopes if you want to use them +with A4 paper. It can also be useful for envelopes in C6 format.% +\EndIndexGroup + + +\begin{Declaration} + \PLength{lfoldmarklength} +\end{Declaration} +The\ChangedAt{v2.97e}{\Class{scrlttr2}} \PLength{lfoldmarklength} +pseudo-length determines the length of the vertical fold mark. Once again, a +feature worth noting is that if the length is given as zero, a length of +4\Unit{mm} is actually used.% +\EndIndexGroup + + +\begin{Declaration} + \PLength{foldmarkvpos} +\end{Declaration} +This\ChangedAt{v2.97e}{\Class{scrlttr2}} pseudo-length determines the distance of +all vertical fold marks from the upper edge of the paper. Normally this is +3.5\Unit{mm}, but\textnote{Hint!} you can change the value in your own +\File{lco} file in case your printer has a wider unprintable +top margin. Whether or not the foldmarks are actually typeset depends on the +\DescRef{scrlttr2.option.foldmarks}% +\important{\DescRef{scrlttr2.option.foldmarks}}% +\IndexOption{foldmarks~=\PName{setting}} option (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.foldmarks}). +\iffree{At present there is only one vertical fold mark, called the left + vertical fold mark.}{}% +\EndIndexGroup + + +\begin{Declaration} + \PLength{foldmarkthickness} +\end{Declaration} +This\ChangedAt{v2.97c}{\Class{scrlttr2}} pseudo-length determines the +thickness of all fold marks. The default is 0.2\Unit{pt}, in other words a +very thin hairline. In\textnote{Hint!} particular, if the colour of the fold +marks is changed, this may not be enough.% +\EndIndexGroup +% +\EndIndexGroup + + +\subsection{Letterhead} +\seclabel{firstHead} +\BeginIndexGroup +\BeginIndex{}{letterhead}% + +The term letterhead refers here to all of the information concerning the +sender that appears above the recipient's address. Normally you would expect +that this information would be set through the page-style settings. In fact, +this was the case with the old letter class, \Class{scrlettr}. +But\textnote{Attention!} \Class{scrlttr2} and \Package{scrletter} output the +letterhead independently of the page style by means of the +\DescRef{scrlttr2.cmd.opening}\IndexCmd{opening} command. +% Fuellmaterial +\iftrue% + The letterhead is positioned absolutely, so that it is independent of the + type area. In fact, the first page of a letter, the page that holds the + letterhead, is set using the page style + \DescRef{scrlttr2.pagestyle.empty}\IndexPagestyle{empty}.% +\fi +% Ende des Fuellmaterials + + +\begin{Declaration} + \PLength{firstheadvpos} +\end{Declaration} +The \PLength{firstheadvpos} pseudo-length gives the distance between the top +edge of the paper and the start of the letterhead. This value is set +differently in the various predefined +\File{lco} files\textnote{\File{lco} file}\Index{lco file=\File{lco} file}. A +typical value is 8\Unit{mm}.% +\EndIndexGroup + + +\begin{Declaration} + \PLength{firstheadhpos} +\end{Declaration} +A positive value of the +\PLength{firstheadhpos}\ChangedAt{v3.05}{\Class{scrlttr2}} pseudo-length gives +the distance between the left edge of the paper and the start of the +letterhead. If\textnote{Attention!} the value is actually greater than or +equal to the paper width, +\Length{paperwidth}\important{\Length{paperwidth}}\IndexLength{paperwidth}, +the letterhead will be centred horizontally on the letterhead paper. A +negative value gives the distance between the right edge of the paper and the +right edge of the letterhead. If the value actually less than or equal to the +negative value of the width of the paper, the letterhead is placed flush with +the left edge of the type area. + +The default\textnote{Attention!} value is typically +\Length{maxdimen}\IndexLength{maxdimen}, which is the maximum allowed value of +a length. This results in horizontal centring.% +\EndIndexGroup + + +\begin{Declaration} + \PLength{firstheadwidth} +\end{Declaration} +The \PLength{firstheadwidth} pseudo-length gives the width of the letterhead. +This value is set differently in the various predefined \File{lco} +files\textnote{\File{lco} file}\Index{lco file=\File{lco} file}. While this +value usually depends on the paper width and the distance between the left +edge of the paper and the recipient's address field, it was the width of the +type area in \Option{KOMAold} and has a fixed value of 170\Unit{mm} in +\Option{NF}.% +\EndIndexGroup + + +\begin{Declaration} + \PLength{fromrulethickness}% + \PLength{fromrulewidth} +\end{Declaration} +As mentioned in the explanation of the +\DescRef{scrlttr2.option.fromrule}\IndexOption{fromrule} option in +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.fromrule}, you +can put a horizontal rule within or below the sender's address in the +predefined letterheads. If\textnote{Attention!} the \PLength{fromrulewidth} +pseudo-length has a value of 0\Unit{pt}, which is the default in the +predefined \File{lco} files, the length of this rule is calculated +automatically taking into account, for example, letterhead width or an +optional logo. You can adjust rule length manually in your own \File{lco} +files by setting this pseudo-length to positive values using +\Macro{setplength} (see \DescPageRef{scrlttr2-experts.cmd.setplength}). The +default thickness of the line\ChangedAt{v2.97c}{\Class{scrlttr2}}, +\PLength{fromrulethickness}, is 0.4\Unit{pt}.% +\EndIndexGroup +% +\EndIndexGroup + + +\subsection{Addressee} +\seclabel{addressee}% +\BeginIndexGroup +\BeginIndex{}{addressee} +\index{recipient|seealso{addressee}} + +The term \emph{addressee} normally refers only to the recipient's name and +address, which are output in an address field. Additional information, +however, can be placed within this address field, including the delivery +method, for example registered mail or special delivery. For window envelopes, +the return address also counts as part of the address field, as it will be +displayed in the address window. The address field directly follows the +letterhead. + +\begin{Declaration} + \PLength{toaddrvpos}% + \PLength{toaddrhpos} +\end{Declaration} +These pseudo-lengths define the vertical and horizontal distance of the +address field from the top-left corner of the paper. Values are set +differently in the various predefined \File{lco} files\textnote{\File{lco} +file}\Index{lco file=\File{lco} file}, according to standard envelope window +measures. For \PLength{toaddrhpos}, one property worth noting is that with +negative values, the offset is the distance from the right edge of the address +field to the right edge of the paper. You will find this, for instance, in +\Option{SN} or \Option{NF}. The smallest value of \PLength{toaddrvpos} is +found with \Option{DINmtext}. With this setting, the letterhead can easily +protrude into the address window. Whether the address field is output or not +depends on the \Option{addrfield} option (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.addrfield}).% +\EndIndexGroup + + +\begin{Declaration} + \PLength{toaddrheight} +\end{Declaration} +This pseudo-length defines the height of the address field, including the +delivery method. Whether the name and address of the recipient are vertically +centred in the address field, taking into account the presence or absence of +the delivery method, depends on the \DescRef{scrlttr2.option.addrfield} +option.% +\EndIndexGroup + + +\begin{Declaration} + \PLength{toaddrwidth} +\end{Declaration} +This pseudo-length defines the width of the address field. The various +predefined \File{lco} files\textnote{\File{lco} files}\Index{lco +file=\File{lco} files} use different settings according to the different +standards for window envelopes. Typical values are between 70\Unit{mm} and +100\Unit{mm}. +\begin{Example} + Suppose your printer has very wide, non-printable left and right margins of 15\Unit{mm}. + This means that the letterhead, the additional sender information, and the address field cannot + be completely printed if you use the \Option{SN} option. You therefore + create a new \File{lco} file with the following content: +\begin{lstcode} + \ProvidesFile{SNmmarg.lco} + [2002/06/04 v0.1 my lco] + \LoadLetterOption{SN} + \addtoplength{toaddrwidth}{% + -\useplength{toaddrhpos}} + \setplength{toaddrhpos}{-15mm} + \addtoplength{toaddrwidth}{% + \useplength{toaddrhpos}} + \endinput +\end{lstcode} + Then, until you can obtain a printer with smaller page margins, you + simply use the option \Option{SNmmarg} instead of \Option{SN}.% +\end{Example}% +% +\EndIndexGroup + + +\begin{Declaration} + \PLength{toaddrindent} +\end{Declaration} +Sometimes you do not want the address field to extend the full width of the +address window but to be indented a bit. You can set the amount of this +indentation with the \PLength{toaddrindent} pseudo-length. Typically, the +default value is 0\Unit{pt}. + +For\textnote{Attention!} the\ChangedAt{v3.03}{\Class{scrlttr2}} +\OptionValueRef{scrlttr2}{addrfield}{PP}\important{% + \OptionValueRef{scrlttr2}{addrfield}{PP}\\ + \OptionValueRef{scrlttr2}{addrfield}{image}\\ + \OptionValueRef{scrlttr2}{addrfield}{backgroundimage} +}\IndexOption{addrfield~=\textKValue{PP}}, +\OptionValueRef{scrlttr2}{addrfield}{image}% +\IndexOption{addrfield~=\textKValue{image}}, and +\OptionValueRef{scrlttr2}{addrfield}{backgroundimage}% +\IndexOption{addrfield~=\textKValue{backgroundimage}} settings (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.addrfield}) a +value of 0\Unit{pt} will be replaced by a value of 8\Unit{mm}. If you really +do not want any indentation, you can use a value of 1\Unit{sp} to set a +negligibly small indentation. Furthermore, \PLength{toaddrindent} is also used +for the distance to the right edge of the address window with the these +\Option{addrfield} settings.% +\EndIndexGroup + + +\begin{Declaration} + \PLength{backaddrheight} +\end{Declaration} +For window envelopes, the sender is often printed in a small font on one line +above the addressee. This sender information is called the return +address\textnote{return address}\Index{return address}, because it is visible +in the address window and will be used by the post office to return an +undeliverable letter to the sender. This return address, therefore, requires +only the information necessary for that purpose. + +The height reserved for the return address within the address window is given +by the \PLength{backaddrheight} pseudo-length. This value is typically +5\Unit{mm} in the predefined \File{lco} files\textnote{\File{lco} +file}\Index{}{lco file=\File{lco} file}. Whether to print the return address +at all depends on the \Option{addrfield} (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.addrfield}) and +\DescRef{scrlttr2.option.backaddress} options (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.backaddress}).% +\EndIndexGroup + + +\begin{Declaration} + \PLength{specialmailindent}% + \PLength{specialmailrightindent} +\end{Declaration} +You can print an optional delivery method between the return address and the +recipient's address. This field is printed only if the +\DescRef{scrlttr2.variable.specialmail} variable has non-empty contents. Its +alignment is determined by the \PLength{specialmailindent} and +\PLength{specialmailrightindent} pseudo-lengths, which specify the left and +right indentation, respectively. In the predefined \File{lco} +files\textnote{\File{lco} file}\Index{lco file=\File{lco} file}, +\PLength{specialmailindent} is set to rubber length \Macro{fill}, while +\PLength{specialmailrightindent} is set to 1\Unit{em}. Thus the delivery +method is set 1\Unit{em} from the address field's right margin.% +\EndIndexGroup + + +\begin{Declaration} + \PLength{PPheadheight}% + \PLength{PPheadwidth} +\end{Declaration} +The \PLength{PPheadheight}\ChangedAt{v3.03}{\Class{scrlttr2}} pseudo-length +specifies the height reserved for the postpaid header at the start of the +address field for the two options +\OptionValueRef{scrlttr2}{addrfield}{PP}\important{% + \OptionValueRef{scrlttr2}{addrfield}{PP}\\ + \OptionValueRef{scrlttr2}{addrfield}{backgroundimage}}% +\IndexOption{addrfield~=\textKValue{PP}} and +\OptionValueRef{scrlttr2}{addrfield}{backgroundimage}% +\IndexOption{addrfield~=\textKValue{backgroundimage}}. The +\PLength{PPheadwidth} pseudo-length is used only with +\OptionValueRef{scrlttr2}{addrfield}{PP} (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.addrfield}) and +gives the width of the left-hand field within the postpaid header, which +contains the postpaid logo, the postal code, and the location. The width of +the right-hand field containing the sender's code and the priority is the +remaining width. + +\KOMAScript{}\textnote{Attention!} automatically changes the default value of +0\Unit{mm} for the \PLength{PPheadheight} pseudo-length to 20.74\Unit{pt}, and +\PLength{PPheadwidth}'s default from 0\Unit{mm} to 42\Unit{mm}.% +% +\EndIndexGroup + + +\begin{Declaration} + \PLength{PPdatamatrixvskip} +\end{Declaration} +This\ChangedAt{v3.03}{\Class{scrlttr2}} pseudo-length specifies the vertical +distance between the postpaid header and the data array used with +\OptionValueRef{scrlttr2}{addrfield}{PP}% +\important{\OptionValueRef{scrlttr2}{addrfield}{PP}}% +\IndexOption{addrfield~=\PValue{PP}} (see \autoref{sec:scrlttr2.firstpage}, +\DescPageRef{scrlttr2.option.addrfield}). \KOMAScript{}\textnote{Attention!} +automatically changes the default value of 0\Unit{mm} to 9\Unit{mm}. The data +matrix is flush right within the postpaid header.% +\EndIndexGroup +% +\EndIndexGroup + + +\subsection{Extra Sender Information} +\seclabel{locationField} +\BeginIndexGroup +\BeginIndex{}{extra sender information} +\index{sender>extra information|see{extra sender information}} + +Often, especially with business letters, there is not enough space in the +letterhead and footer to accommodate all the information about the sender that +you want to include. For such additional information, you can use the space +next to the addressee. In this manual, this field is called the +\emph{extra sender information}. In earlier versions of this manual, it +was called the \emph{sender's extension} or the \emph{location field}. + +\begin{Declaration} + \PLength{locheight}% + \PLength{lochpos}% + \PLength{locvpos}% + \PLength{locwidth} +\end{Declaration} +The \PLength{locwidth} and +\PLength{locheight}\ChangedAt{v2.97d}{\Class{scrlttr2}} pseudo-lengths set the +width and height of the extra-sender-information field. The \PLength{lochpos} +and \PLength{locvpos} pseudo-lengths determine the distances from the +top-right edge of the paper. These values are typically set to 0\Unit{pt} in +the predefined \File{lco} files. These\textnote{Attention!} zero-length values +have a special meaning. They result in the actual values being set within +\DescRef{scrlttr2.cmd.opening} based on the paper width, the address-window +width, the address window's distance from the top-left edge of the paper, and +the \DescRef{scrlttr2.option.locfield} option (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.locfield}). As +is the case for \PLength{toaddrhpos}, negative values of \PLength{lochpos} +also take on a special meaning. Instead of referring to the distance from the +right edge of the paper, \PLength{lochpos} then refers to the distance from +the left edge of the paper. The meaning is thus the opposite of that of +\PLength{toaddrhpos} (see \autoref{sec:scrlttr2-experts.addressee}, +\DescPageRef{scrlttr2-experts.plength.toaddrhpos}).% +\EndIndexGroup +% +\EndIndexGroup + + +\subsection{Reference Line} +\seclabel{refLine}% +\BeginIndexGroup +\BeginIndex{}{reference line} +\index{business line|see{reference line}} + +The reference line can actually be longer than just one line. It is printed +only if at least one of variables for the reference line is not empty. Only +non-empty fields will be printed. To\textnote{Hint!} set a seemingly empty +field, you can provide content for the variable that appears empty, such as +\Macro{mbox}\Parameter{}. If the reference line is omitted, the description +and contents of the \DescRef{scrlttr2.variable.date} variable are printed in +its place. You can find information about adding variables to or removing them +from the reference line in \autoref{sec:scrlttr2-experts.variables}, +\DescPageRef{scrlttr2-experts.cmd.removereffields}. + + +\begin{Declaration} + \PLength{refvpos} +\end{Declaration} +This pseudo-length specifies the distance from the upper edge of the paper to +the reference line. Its value is set differently in the various predefined +\File{lco} files\textnote{\File{lco} file}\Index{lco file=\File{lco} file}. +Typical values are between 80.5\Unit{mm} and 98.5\Unit{mm}.% +\EndIndexGroup + + +\begin{Declaration} + \PLength{refwidth}% + \PLength{refhpos} +\end{Declaration} +The \PLength{refwidth} pseudo-length specifies the width available for the +reference line. Its value is typically set to 0\Unit{pt} in the predefined +\File{lco} files\textnote{\File{lco} file}\Index{lco file=\File{lco} file}. +This\textnote{Attention!} value has a special meaning. In no way does it +indicate that there is no available width for the reference line. Instead, it +indicates that the width will be calculated within the +\DescRef{scrlttr2.cmd.opening}\IndexCmd{opening} command. This calculated +width then depends on the value of the \DescRef{scrlttr2.option.refline}% +\important{\DescRef{scrlttr2.option.refline}}% +\IndexOption{refline~=\PName{setting}} options (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.refline}). At +the same time, \PLength{refhpos} will also be set according to this option. +With \OptionValueRef{scrlttr2}{refline}{wide}% +\IndexOption{refline~=\textKValue{wide}}, the reference fields line is +centred, while with \OptionValueRef{scrlttr2}{refline}{narrow}% +\IndexOption{refline~=\textKValue{narrow}} it is aligned flush left with the +type area. + +If \PLength{refwidth} is not zero, the width of the reference line is not +determined by the \DescRef{scrlttr2.option.refline} option, and so +\PLength{refhpos} specifies the distance of the reference line from the left +edge of the paper. If\textnote{Attention!} this distance is zero, the the +reference line is placed so that the ratio between its distances from the left +and right edges of the paper corresponds to the ratio of distance of the type +area from the left and right edges of the paper. Thus, for a type area +horizontally centred on the paper, the reference line will also be centred. + +As a rule, these special cases are likely of little interest to the normal +user. The\textnote{Attention!} simplest rule is as follows: either +\PLength{refhpos} remains zero, and so the width and alignment of the +reference line are determined with the \DescRef{scrlttr2.option.refline} +option, or the user sets both \PLength{refwidth} and \PLength{refhpos}.% +\EndIndexGroup + + +\begin{Declaration} + \PLength{refaftervskip} +\end{Declaration} +This pseudo-length specifies the vertical skip to be inserted beneath the +reference line. The value is set in the predefined \File{lco} +files\textnote{\File{lco} file}\Index{lco file=\File{lco} file}. It directly +affects the height of the text area on the first page. A typical value is +between one and two lines.% +\EndIndexGroup +% +\EndIndexGroup + + +\subsection{Subject} +\seclabel{subject}% +\BeginIndexGroup +\BeginIndex{}{subject} + +Different countries have different conventions for placing the subject line of +a letter. Some place it before the opening phrase; others place it after. Some +professional groups even want it before the reference line. + +\begin{Declaration} + \PLength{subjectvpos} +\end{Declaration} +\ChangedAt{v3.01}{\Class{scrlttr2}}% +If\textnote{Attention!} the value of this pseudo-length is 0\Unit{pt}, the +\DescRef{scrlttr2.option.subject}\important{\DescRef{scrlttr2.option.subject}}% +\IndexOption{subject~=\PName{Einstellung}} option (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.subject}) +determines the position of the subject. Any other value defines the distance +between the top edge of the paper and the subject. In this +case\textnote{Hint!}, you should ensure that there is enough space available +that overlapping with other elements is unlikely. +\begin{Example} + A few professionals prefer to have the subject above the reference line. For + this, you can specify the position as follows, which also changes the + position of the reference line itself: +\begin{lstcode} + \ProvidesFile{lawsubj.lco} + [2008/11/03 lawyers lco file] + \setplength{subjectvpos}{\useplength{refvpos}} + \addtoplength{refvpos}{3\baselineskip} + \endinput +\end{lstcode} + If you want to leave at least one empty line between the subject and the + reference, you have space for a maximum of two lines. +\end{Example} +\EndIndexGroup + + +\begin{Declaration} + \PLength{subjectbeforevskip}% + \PLength{subjectaftervskip} +\end{Declaration} +\ChangedAt{v3.01}{\Class{scrlttr2}}% +If the subject is placed not absolutely but before or after the salutation, +you can insert additional vertical space before and after the subject. The +space before the subject may interfere with other distances, such as the +automatic distance of one line after the title. Therefore the default is to +use no additional space here. The default of the class and the package for the +space after the subject is two lines.% +\EndIndexGroup +% +\EndIndexGroup + + +\subsection{Closing} +\seclabel{closing} +\BeginIndexGroup +\BeginIndex{}{closing} + +The closing of a letter consists of three parts: In addition to the closing +phrase, there is a hand-written signature and a printed text such as a name, +which acts as a kind of explanation of the hand-written signature. + +\begin{Declaration} + \PLength{sigindent}% + \PLength{sigbeforevskip} +\end{Declaration} +The closing phrase\Index{closing>phrase}\Index{signature} and signature +explanation are typeset in a box whose width is determined by the length of +the longest line of the closing phrase or explanation. + +The box will be indented by the distance specified in the \PLength{sigindent} +pseudo-length. In the predefined \File{lco} files\textnote{\File{lco} +file}\Index{lco file=\File{lco} file}, this length is set to 0\Unit{mm}. + +Between the closing phrase and the signature explanation, a vertical skip is +inserted whose height is defined in the \PLength{sigbeforevskip} +pseudo-length. In the predefined \File{lco} files\textnote{\File{lco} +file}\Index{lco file=\File{lco} file} this value is set to two lines. In this +space you can then write your signature.% +\iffalse% Umbruchkorrekturtext +\ If you decide to include a facsimile of your signature in the +\DescRef{scrlttr2.variable.signature}\IndexVariable{signature}% +\important{\DescRef{scrlttr2.variable.signature}} with the +\Package{graphicx}\IndexPackage{graphicx} package, it would be useful +to reduce the value of \PLength{sigbeforevskip} and thus the gap between +the closing phrase and the signature.% +\fi% +\EndIndexGroup +% +\EndIndexGroup + + +\subsection{Letterhead Page Footer} +\seclabel{firstFoot}% +\BeginIndexGroup +\BeginIndex{}{letterhead page>footer}% + +The first page of a letter, the letterhead page, contains not just its own +header, the letterhead, but also its own footer\Index{footer>letterhead +page}\Index{footer}. Just like the letterhead, it will be set not by the page +style but directly within \DescRef{scrlttr2.cmd.opening}\IndexCmd{opening}% +\important{\DescRef{scrlttr2.cmd.opening}}. + +\begin{Declaration} + \PLength{firstfootvpos} +\end{Declaration} +This pseudo-length gives the distance from the top of the paper to the footer +of the letterhead page. It also ensures that the text area does not protrude +into the footer. To do so, the height of the text area on the first page will +be decreased, if necessary, using +\Macro{enlargethispage}\IndexCmd{enlargethispage}% +\important{\Macro{enlargethispage}}. The +\DescRef{scrlttr2.option.enlargefirstpage}% +\important{\DescRef{scrlttr2.option.enlargefirstpage}} option (see +\autoref{sec:scrlttr2.firstpage}, +\DescPageRef{scrlttr2.option.enlargefirstpage}) can also ensure that the +height of the text area is increased, if necessary. Thus, the distance between +text area and the letterhead page footer can be reduced to the value of the +\Length{footskip}\IndexLength{footskip}\important{\Length{footskip}} length. + +With\textnote{Attention!} the compatibility option +set\ChangedAt{v2.9t}{\Class{scrlttr2}} to versions up to +2.9t\IndexOption{version~=\PValue{2.9t}} (see +\DescRef{scrlttr2.option.version} in +\autoref{sec:scrlttr2.compatibilityOptions}, +\DescPageRef{scrlttr2.option.version}) the footer is set independently of the +type area in all predefined \File{lco} files\textnote{\File{lco} +file}\Index{lco file=\File{lco} file} (see \autoref{sec:scrlttr2.lcoFile}) +except for \Option{KOMAold} and \Option{NF}. Thus the +\DescRef{scrlttr2.option.enlargefirstpage}% +\important{\DescRef{scrlttr2.option.enlargefirstpage}} option has no effect. +From version 2.9u on, the footer is placed at the bottom edge of the paper. +Thus, the height of the letterhead page's type area may also depend on the +\DescRef{scrlttr2.option.enlargefirstpage} option. + +If the letter footer is deactivated with the +\OptionValueRef{scrlttr2}{firstfoot}{false}% +\important{\OptionValueRef{scrlttr2}{firstfoot}{false}}% +\IndexOption{firstfoot~=\PValue{false}}\ChangedAt{v2.97e}{\Class{scrlttr2}} +option (see \autoref{sec:scrlttr2.firstpage}, +\DescPageRef{scrlttr2.option.firstfoot}), the setting of +\PLength{firstfootvpos} is ignored, and instead +\Length{paperheight}\IndexLength{paperheight} is applied. There remains then a +minimum bottom margin of length \Length{footskip}\IndexLength{footskip}.% +\EndIndexGroup + + +\begin{Declaration} + \PLength{firstfoothpos} +\end{Declaration} +\ChangedAt{v3.05}{\Class{scrlttr2}}% +A\textnote{Attention!} positive value of the \PLength{firstfoothpos} +pseudo-length specifies the distance from the left edge of the paper to the +letterhead page footer. If the value is greater than or equal to the paper +width, \Length{paperwidth}\IndexLength{paperwidth}, the footer is centred +horizontally on the letterhead page. But if the value is less than or equal to +the negative width of the paper, the footer is placed flush with the left edge +of the typing area. + +The typical default for this value is \Length{maxdimen}\IndexLength{maxdimen}, +which is the maximum possible value for a length. This results in horizontal +centring.% +\EndIndexGroup + + +\begin{Declaration} + \PLength{firstfootwidth} +\end{Declaration} +This pseudo-length specifies the width of the footer of the first page of the +letter, that is the letterhead page. The value in the predefined \File{lco} +files\textnote{\File{lco} file}\Index{lco file=\File{lco} file} matches +\PLength{firstheadwidth}\important{\PLength{firstheadwidth}}% +\IndexPLength{firstheadwidth}.% +% +\EndIndexGroup +% +\EndIndexGroup +% +\EndIndexGroup + + +\section{Variables for Experienced Users} +\seclabel{variables} +\BeginIndexGroup +\BeginIndex{}{variables} + +\KOMAScript{} provides commands not only to use predefined variables but also +to define new variables or to change their automatic use within the reference +line\Index{reference line}. + +\begin{Declaration} + \Macro{newkomavar}\OParameter{description}\Parameter{name}% + \Macro{newkomavar*}\OParameter{description}\Parameter{name}% + \Macro{removereffields}% + \Macro{defaultreffields}% + \Macro{addtoreffields}\Parameter{name} +\end{Declaration} +\Macro{newkomavar} defines a new variable. This variable is referenced as +\PName{name}. Optionally, you can define a \PName{description} for the +\PName{name} variable. Unlike the \PName{name}, the \PName{description} is not +used to reference a variable. Instead, the \PName{description} acts as a +supplement to the content of a variable that can be printed as a label along +with its content. + +You can use the \Macro{addtoreffields} command to add the \PName{name} +variable to the reference line\Index{reference line} (see +\autoref{sec:scrlttr2.firstpage}, \DescPageRef{scrlttr2.option.refline}). The +\PName{description} and the content of the variable are added to the end of +the reference line. The starred version \Macro{newkomavar*} is similar to the +unstarred version but also calls the \Macro{addtoreffields} command. Thus, the +starred version automatically adds the variable to the reference line. +\begin{Example} + Suppose you need an additional field for a telephone extension in the + reference line. You can define this field with +\begin{lstcode} + \newkomavar[Extension]{myphone} + \addtoreffields{myphone} +\end{lstcode} + or more concisely with +\begin{lstcode} + \newkomavar*[Extension]{myphone} +\end{lstcode} +\end{Example} +When\textnote{Attention!} you define a variable for the reference line, you +should always give it a description. + +You can use the \Macro{removereffields} command to remove all variables from +the reference field. This includes the predefined variables of the class. The +reference line is then empty. This can be useful, for example, if you wish to +change the order of the variables in the reference fields line. + +The \Macro{defaultreffields} command resets the reference fields line to its +predefined format. In doing so, all custom-defined variables are removed from +the reference fields line. + +You\textnote{Attention!} should not add the date to the reference line with +the \Macro{addtoreffields} command. Instead you should use the +\DescRef{scrlttr2.option.refline}% +\important{\OptionValueRef{scrlttr2}{refline}{dateleft}\\ +\OptionValueRef{scrlttr2}{refline}{dateright}\\ +\OptionValueRef{scrlttr2}{refline}{nodate}}% +\IndexOption{refline~=\textKValue{dateleft}}% +\IndexOption{refline~=\textKValue{dateright}}% +\IndexOption{refline~=\textKValue{nodate}} option to select whether the date +should appear on the left or right side of the reference line, or not at all. +These settings also affect the position of the date when no reference line is +used.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{usekomavar}\OParameter{command}\Parameter{name}% + \Macro{usekomavar*}\OParameter{command}\Parameter{name} +\end{Declaration} +The \DescRef{scrlttr2.cmd.usekomavar} and \DescRef{scrlttr2.cmd.usekomavar*} +commands are, like all commands where a starred version exists or which can +take an optional argument, not fully expandable. Nevertheless, if you use them +within \DescRef{scrlttr2.cmd.markboth}\IndexCmd{markboth}, +\DescRef{scrlttr2.cmd.markright}\IndexCmd{markright} or similar commands, you +need not insert \Macro{protect}\IndexCmd{protect} beforehand. Of course +this is also true for +\DescRef{scrlayer-scrpage.cmd.markleft}\IndexCmd{markleft} if you use the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage} package. These\textnote{Attention!} commands +cannot be used within commands that directly affect their argument, such as +\Macro{MakeUppercase}\important{\Macro{MakeUppercase}}% +\IndexCmd{MakeUppercase}. To avoid this problem you can use commands like +\Macro{MakeUppercase} as an optional argument to \Macro{usekomavar} or +\Macro{usekomavar*}. Then you will get the upper-case content of a variable +with +\begin{lstcode}[escapeinside=`'] + \usekomavar[\MakeUppercase]{`\PName{Name}'} +\end{lstcode} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ifkomavarempty}\Parameter{name}\Parameter{true}\Parameter{false}% + \Macro{ifkomavarempty*}\Parameter{name}\Parameter{true}\Parameter{false} +\end{Declaration} +It is important to know that the content of the variable will be expanded as +far as this is possible with \Macro{edef}. If this results in spaces or +unexpandable macros like \Macro{relax}, the result will be not empty even +where the use of the variable would not result in any visible output. + +Once\textnote{Attention!} again, this command cannot be used as the argument +of \Macro{MakeUppercase}\IndexCmd{MakeUppercase} or similar commands However, +it is robust enough to be used as the argument of +\DescRef{scrlttr2.cmd.markboth} or \DescRef{scrlttr2.cmd.footnote}, for +example.% +% +\EndIndexGroup +% +\EndIndexGroup + + +\section{Additional Information about Page Styles} +\seclabel{pagestyleatscrletter} +\BeginIndexGroup +\BeginIndex{}{page>style} + +\LoadNonFree{scrlttr2-experts}{0}% +\EndIndexGroup + +\iffalse% Wurde bereits in Kapitel 4.21 behandelt +\section{Differences in How \Package{scrletter} Handles \File{lco} Files} +\seclabel{lcoatscrletter} +\BeginIndexGroup +\BeginIndex{File}{lco} +\BeginIndex{}{lco file=\File{lco} file} + +As\ChangedAt{v3.15}{\Package{scrletter}} explained in +\autoref{sec:scrlttr2.lcoFile}, \Class{scrlttr2} can load \File{lco} files via +the optional argument of \Macro{documentclass}. The \Package{scrletter} package +does not support this. + +\begin{Declaration} + \Macro{LoadLetterOption}\Parameter{name}% + \Macro{LoadLetterOptions}\Parameter{list of names} +\end{Declaration} +For \Class{scrlttr2}, load \File{lco} files with +\DescRef{scrlttr2.cmd.LoadLetterOption} or +\DescRef{scrlttr2.cmd.LoadLetterOptions} is only a recommendation. For +\Package{scrletter}, it is mandatory. Of course, you can only load the +\File{lco} files after you load \Package{scrletter}. +% +\EndIndexGroup +% +\EndIndexGroup +\fi + + +\section{\File{lco} Files for Experienced Users} +\seclabel{lcoFile} +\BeginIndexGroup +\BeginIndex{File}{lco} +\BeginIndex{}{lco file=\File{lco} file} + +\BeginIndexGroup% +\BeginIndex{}{paper>format}% +Although you can use any paper size that the +\hyperref[cha:typearea]{\Package{typearea}}% +\IndexPackage{typearea} package can configure, the output of the letterhead +page may produce undesirable results with some formats. Unfortunately, there +are no general rules to calculate the position of the address fields and the +like for every available paper size. Instead, different parameter sets are +needed for different paper sizes.% + +%\subsection{Verifying the Paper Size} +%\seclabel{papersize} + +At present parameter sets and \File{lco} files exist only for A4-sized and +letter-sized paper. Theoretically, however, the \Class{scrlttr2} class can +support many more paper sizes. Therefore, it's necessary to verify that the +correct paper size is used. This is even more true if you use +\Package{scrletter}, since the paper size depends on the class you use. + +\begin{Declaration} + \Macro{LetterOptionNeedsPapersize}% + \Parameter{option name}\Parameter{paper size} +\end{Declaration} +To provide at least a warning when another \PName{paper size} is used, you can +find a \Macro{LetterOptionNeedsPapersize} command in every \File{lco} file +distributed with {\KOMAScript}. The first argument is the name of the +\File{lco} file without the ``\File{.lco}'' suffix. The second argument is the +paper size for which the \File{lco} file is designed. + +If several \File{lco} files are loaded in succession, a +\Macro{LetterOptionNeedsPapersize} command can be contained in each of them, +but the \DescRef{scrlttr2.cmd.opening} command will only check the last given +\PName{paper size}. As the following example shows, an experienced user can +thus easily write \File{lco} files with parameter sets for other paper sizes. +\iffalse% Umbruchoptimierung +If you do not plan to set up such \File{lco} files yourself, you can just +forget about this option and skip the example.% +\fi +\begin{Example} + Suppose you use A5-sized paper in normal, that is upright or portrait, + orientation for your letters. Let's assume that you want to put them into + standard C6 window envelopes. In that case, the position of the address + field would be the same as for a standard letter on A4-sized paper. The main + difference is that A5 paper needs only one fold. So you want to disable the + top and bottom fold marks. You can do this, for example, by placing the + marks outside the paper area. +\begin{lstcode} + \ProvidesFile{a5.lco} + [2002/05/02 letter class option] + \LetterOptionNeedsPapersize{a5}{a5} + \setplength{tfoldmarkvpos}{\paperheight} + \setplength{bfoldmarkvpos}{\paperheight} +\end{lstcode} + Of course, it would be more elegant to deactivate the marks with the + \DescRef{scrlttr2.option.foldmarks} option. In addition, you must adjust the + position of the footer, that is, the \PLength{firstfootvpos} pseudo-length. + I leave it to the reader to find an appropriate value. When using such an + \File{lco} file, you must declare other \File{lco} file options like + \File{SN} before you load ``\File{a5.lco}''. +\end{Example} +% +\EndIndexGroup% +\EndIndexGroup% +\vskip-\ht\strutbox% Wegen Beispiel am Ende der Erklaerung + + +%\subsection{Visualizing Positions} +%\seclabel{visualize} +%\BeginIndexGroup +\begin{Declaration} + \File{visualize.lco} +\end{Declaration} +\BeginIndex{Option}{visualize}% +If you develop your own \File{lco} file, for example to modify the positions +of various fields on the letterhead page because your own desires or +requirements, it is helpful if you can make at least some elements directly +visible. The \File{lco} file +\File{visualize.lco}\ChangedAt{v3.04}{\Class{scrlttr2}} exists for this +purpose. You can load this file as you would any other \File{lco} file. But +this \emph{letter class options} file must be loaded in the document preamble, +and its effects cannot be deactivated. The \File{lco} file uses the +\Package{eso-pic}\IndexPackage{eso-pic}% +\important[i]{\Package{eso-pic}\\\Package{graphicx}} and +\Package{graphicx}\IndexPackage{graphicx} packages, which are not part of +\KOMAScript. + + +\begin{Declaration} + \Macro{showfields}\Parameter{field list} +\end{Declaration} +This command makes the space occupied by the fields on the letterhead page +visible. The \PName{field list} argument is a comma-separated list of fields +to be shown. The following fields are supported: +\begin{labeling}[~--]{\PValue{location}} +\item[\PValue{test}] is a 10\Unit{cm} by 15\Unit{cm} test field, 1\Unit{cm} + from the top and left edges of the paper. This field exists for debugging. + You can use it as a benchmark to check whether the measurements have been + distorted during the creation of the document. +\item[\PValue{head}] is the header area of the letterhead page. This field + is open at the bottom. +\item[\PValue{foot}] is the footer area of the letterhead page. This field is + open at the top. +\item[\PValue{address}] is the address window area used by window envelopes. +\item[\PValue{location}] is the field for the extra sender information. +\item[\PValue{refline}] is the reference line. This field is open at the + bottom. +\end{labeling}% +\BeginIndex{FontElement}{field}\LabelFontElement{field}% +You can change the colour of the visualisation with +the\DescRef{scrlttr2.cmd.setkomafont} and \DescRef{scrlttr2.cmd.addtokomafont} +(see \autoref{sec:scrlttr2.textmarkup}, +\DescPageRef{scrlttr2.cmd.setkomafont}) commands using the +\FontElement{field}\important{\FontElement{field}} element. The default is +\Macro{normalcolor}.% +\EndIndex{FontElement}{field}% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{setshowstyle}\Parameter{style}% + \Macro{edgesize} +\end{Declaration} +By default, \File{visualize.lco} indicates the individual areas with +frames\important{\PValue{frame}}, which corresponds to the \PName{style} +\PValue{frame}. Areas open at top or bottom are not completely framed but have +an open edge with with small arrows pointing up or down. +Alternatively\important{\PValue{rule}}, you can use the \PName{style} +\PValue{rule}. In this case, the area is highlighted by a background colour. +It isnot possible to distinguish open and closed areas. Instead a minimal +height will be used for open areas. The third\important{\PValue{edges}} +available \PName{style} is \PValue{edges}, which shows the corners of the +areas. The corner marks at the open edge of open areas will be omitted. The +size of two edges of the corner marks are given by the \Macro{edgesize} macro +with a default of 1\Unit{ex}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{showenvelope}\AParameter{width\textup{,}height}% + \AParameter{h-offset\textup{,}v-offset}% + \OParameter{instructions}% + \Macro{showISOenvelope}\Parameter{format}\OParameter{instructions}% + \Macro{showUScommercial}\Parameter{format}\OParameter{instructions}% + \Macro{showUScheck}\OParameter{instructions}% + \Macro{unitfactor} +\end{Declaration} +If you have loaded \File{visualize.lco}, you can use these commands to output +a page with a drawing of an envelope. The envelope drawing is always rotated +by 90\textdegree{} on a separate page and printed in 1:1~scale. The addressee +window is generated automatically from the current data for the address +position of the letterhead page: \PLength{toaddrvpos}, \PLength{toaddrheight}, +\PLength{toaddrwidth}, and \PLength{toaddrhpos}. To do so requires knowing how +much smaller the folded letter pages are than the width and height of the +envelope. If you do not specify these two values, \PName{h-offset} and +\PName{v-offset}, when calling \Macro{showenvelope}, they are calculated from +the fold marks and the paper size itself. + +The \Macro{showISOenvelope}, \Macro{showUScommercial}, and \Macro{showUScheck} +commands are based on \Macro{showenvelope}. With \Macro{showISOenvelope}, you +can create ISO-envelopes in C4, C5, C5/6, DL (also known as C5/6) or C6 +\PName{format}. With \Macro{showUScommercial}, you can create a US commercial +envelope in the 9 or 10 \PName{format}. You can use \Macro{showUScheck} for +envelopes in US check format. + +\BeginIndex{FontElement}{letter}\LabelFontElement{letter}% +The position of the letterhead page inside the envelope is indicated with +dashed lines. You can change the colour of these lines with the +\DescRef{scrlttr2.cmd.setkomafont} and \DescRef{scrlttr2.cmd.addtokomafont} +(see \autoref{sec:scrlttr2.textmarkup}, +\DescPageRef{scrlttr2.cmd.setkomafont}) using the +\FontElement{letter}\important{\FontElement{letter}} element. The default is +\Macro{normalcolor}.% +\EndIndex{FontElement}{letter}% + +\BeginIndex{FontElement}{measure}\LabelFontElement{measure}% +The envelope drawing will be provided with dimensions automatically. You can +change the colour of these dimension labels with the commands +\DescRef{scrlttr2.cmd.setkomafont} and \DescRef{scrlttr2.cmd.addtokomafont} +(see \autoref{sec:scrlttr2.textmarkup}, +\DescPageRef{scrlttr2.cmd.setkomafont}) using the +\FontElement{measure}\important{\FontElement{measure}} element. The default is +\Macro{normalcolor}. The dimensions are given in multiples of +\Length{unitlength}, with an accuracy of $1/\Macro{unitfactor}$, where the +accuracy of \TeX{} arithmetic is the actual limits. The default is 1. You can +redefine \Macro{unitfactor} using \Macro{renewcommand}.% +\EndIndex{FontElement}{measure}% + +\begin{Example} + You are generating a sample letter using the ISO-A4 format. The supported + fields should be marked with yellow borders to check their position. + Furthermore, the position of the window for a DL-size envelope should be + checked with drawing. The dimension lines in this drawing should be red, and + the numbers should use a smaller font, with the dimensions printed in cm + with an accuracy of 1\Unit{mm}. The dashed letterhead page in the envelope + should be coloured green. +\begin{lstcode} + \documentclass[visualize]{scrlttr2} + \usepackage{xcolor} + \setkomafont{field}{\color{yellow}} + \setkomafont{measure}{\color{red}\small} + \setkomafont{letter}{\color{green}} + \showfields{head,address,location,refline,foot} + \usepackage[british]{babel} + \usepackage{lipsum} + \begin{document} + \setkomavar{fromname}{Joe Public} + \setkomavar{fromaddress}{2 Valley\\ + SAMPLEBY\\ + ZY32 1XW} + \begin{letter}{% + 1 Hillside\\ + SAMPLESTEAD\\ + WX12 3YZ% + } + \opening{Hello,} + \lipsum[1] + \closing{Good bye} + \end{letter} + \setlength{\unitlength}{1cm} + \renewcommand*{\unitfactor}{10} + \showISOenvelope{DL} + \end{document} +\end{lstcode} + This will show the letterhead page as the first page and the drawing of the + envelope on the second page. +\end{Example} + +Note that poorly chosen combinations of \Length{unitlength} and +\Macro{unitfactor} can quickly lead to a \TeX{} \emph{arithmetic overflow} +error. The dimension numbers shown may also differ slightly from the actual +values. Neither are errors in \Option{visualize} but merely implementation +limitations of \TeX. +% +\EndIndexGroup +% +\EndIndexGroup +% +\EndIndexGroup + + +\section{Language Support} +\seclabel{languages}% +\BeginIndexGroup +\BeginIndex{}{languages}% + +The \Class{scrlttr2} class and the \Package{scrletter} package support many +languages. These include German\Index{language>German} (\PValue{german} for +the old German orthography, \PValue{ngerman} for the new orthography; +\PValue{austrian} for Austrian with the old German orthography, +\PValue{naustrian}\ChangedAt{v3.09}{\Class{scrlttr2}} for Austrian with the +new orthography; and \PValue{nswissgerman}\ChangedAt{v3.13}{\Class{scrlttr2}} +for Swiss German with the new orthogrphy, \PValue{swissgerman} for Swiss +German with the old orthography), English\Index{language>English} (among +others, \PValue{english} without specification as to whether American or +British should be used, \PValue{american} and \PValue{USenglish} for American +English, and \PValue{british} and \PValue{UKenglish} for British English), +French\Index{language>French}, Italian\Index{language>Italian}, +Spanish\Index{language>Spanish}, Dutch\Index{language>Dutch}, +Croatian\Index{language>Croatian}, Finnish\Index{language>Finnish}, +Norwegian\Index{language>Norwegian}\ChangedAt{v3.02}{\Class{scrlttr2}}, +Swedish\Index{language>Swedish}\ChangedAt{v3.08}{\Class{scrlttr2}}, +Polish\ChangedAt{v3.13}{\Class{scrlttr2}}, +Czech\ChangedAt{v3.13}{\Class{scrlttr2}}, and Slovak. + +You can switch languages using the \Package{babel}\IndexPackage{babel} package +(see \cite{package:babel}) with the \Macro{selectlanguage}\Parameter{language} +command. Other packages like \Package{german}\IndexPackage{german} (see +\cite{package:german}) and \Package{ngerman}\IndexPackage{ngerman} (see +\cite{package:ngerman}) also define this command. As a rule though, the +language selection occurs immediately as a direct consequence of loading such +a package. +\iffalse% Umbruchkorrekturtext +For details, please refer to the documentation of the relevant packages. +\fi + +There\textnote{Attention!} is one more point to note about language-switching +packages. The +\Package{french}\IndexPackage{french}\important{\Package{french}} package (see +\cite{package:french}) makes changes well beyond redefining the terms in +\autoref{tab:scrlttr2-experts.languageTerms}. For instance, it redefines the +\DescRef{scrlttr2.cmd.opening} command, since the package simply assumes that +\DescRef{scrlttr2.cmd.opening} is always defined as it is in the standard +\Class{letter} class. This, however, is not the case with \KOMAScript{}. The +\Package{french} package thus overwrites the definition and does not work +correctly with \KOMAScript. I regard this as a fault in the \Package{french} +package which, although reported decades ago, was unfortunately never +eliminated. + +If you use the \Package{babel}\IndexPackage{babel} package to switch to +\PValue{french}, problems can occasionally occur. With \Package{babel}, +however, you can usually deactivate changes to a language in a targeted +manner.% +\iffalse% This is actually outdated! +\ If the package \Package{french} is not installed, the problem with + \Package{babel} does not arise. Similarly, the problem usually does not + exist when you use \Package{babel} with other varieties of French such as + \PValue{acadian}, \PValue{canadien}, \PValue{francais} or \PValue{frenchb} + instead of \PValue{french}. +\fi + +\iffalse% This is also outdated! + However, with \Package{babel} version 3.7j and above, this problem only occurs + if the option explicitly indicates that \Package{babel} should use the + \Package{french} package. +% +\iftrue + If you cannot be sure you are not using an old version of \Package{babel}, I + recommend you use +\begin{lstcode} + \usepackage[...,frenchb,...]{babel} +\end{lstcode} + to select French. + \iffalse % + If necessary, you can still switch to French with + \Macro{selectlanguage}\PParameter{french}.% + \fi% +\fi +\fi + +\iftrue + It cannot be ruled out that similar problems will not occur with other + languages or packages. For German and English, however, there are currently + no known problems with the \Package{babel} package. +\fi + + +\begin{Declaration} + \Macro{yourrefname}% + \Macro{yourmailname}% + \Macro{myrefname}% + \Macro{customername}% + \Macro{invoicename}% + \Macro{subjectname}% + \Macro{ccname}% + \Macro{enclname}% + \Macro{headtoname}% + \Macro{headfromname}% + \Macro{datename}% + \Macro{pagename}% + \Macro{mobilephonename}% + \Macro{phonename}% + \Macro{faxname}% + \Macro{emailname}% + \Macro{wwwname}% + \Macro{bankname} +\end{Declaration} +These commands contain the language-dependent terms. These\important[i]{% + \DescRef{scrbase.cmd.newcaptionname}\\ + \DescRef{scrbase.cmd.renewcaptionname}\\ + \DescRef{scrbase.cmd.providecaptionname}} definitions can be +modified to support a new language or for your private customization, as +described in +\autoref{sec:scrbase.languageSupport}. \KOMAScript{} sets these terms only in +\Macro{begin}\PParameter{document}. Therefore they are not available in the +preamble and cannot be redefined there. The default settings for +\Option{english} and \Option{ngerman} are listed in +\autoref{tab:scrlttr2-experts.languageTerms}.% +\EndIndexGroup +%\iffree{}{\clearpage}% Siehe Kommentar zur Tabelle + +\begin{Declaration} + \Macro{captionsacadian} + \Macro{captionsamerican} + \Macro{captionsaustralien} + \Macro{captionsaustrian} + \Macro{captionsbritish} + \Macro{captionscanadian} + \Macro{captionscanadien} + \Macro{captionscroatian} + \Macro{captionsczech} + \Macro{captionsdutch} + \Macro{captionsenglish} + \Macro{captionsfinnish} + \Macro{captionsfrancais} + \Macro{captionsfrench} + \Macro{captionsgerman} + \Macro{captionsitalian} + \Macro{captionsnaustrian} + \Macro{captionsnewzealand} + \Macro{captionsngerman} + \Macro{captionsnorsk} + \Macro{captionsnswissgerman} + \Macro{captionspolish} + \Macro{captionsslovak} + \Macro{captionsspanish} + \Macro{captionsswedish} + \Macro{captionsswissgerman} + \Macro{captionsUKenglish} + \Macro{captionsUSenglish} +\end{Declaration} +If you change the language of a letter, the language-dependent terms listed in +\autoref{tab:scrlttr2-experts.languageTerms}, +\autopageref{tab:scrlttr2-experts.languageTerms} are redefined using these +commands. If your language-switching package does not support this, you can +also use the above commands directly. +% +\begin{table} + \begin{minipage}{\textwidth} + \centering +% \KOMAoptions{captions=topbeside}% +% \setcapindent{0pt}% + \caption[{% + Defaults for language-dependent terms + }]{% + Defaults for language-dependent terms for the languages + \Option{english} and \Option{ngerman}, if they are not already defined + by the packages used for language switching% + \label{tab:scrlttr2-experts.languageTerms}% + }[l] + \begin{tabular}[t]{lll} + \toprule + Command & \Option{english} & \Option{ngerman} \\ + \midrule + \Macro{bankname} & Bank account & Bankverbindung \\ + \Macro{ccname}\footnotemark[1] & cc & Kopien an \\ + \Macro{customername} & Customer no. & Kundennummer \\ + \Macro{datename} & Date & Datum \\ + \Macro{emailname} & Email & E-Mail \\ + \Macro{enclname}\footnotemark[1] & encl & Anlagen \\ + \Macro{faxname} & Fax & Fax \\ + \Macro{headfromname} & From & Von \\ + \Macro{headtoname}\footnotemark[1] & To & An \\ + \Macro{invoicename} & Invoice no. & Rechnungsnummer \\ + \Macro{myrefname} & Our ref. & Unser Zeichen \\ + \Macro{pagename}\footnotemark[1] & Page & Seite \\ + \Macro{mobilephonename} & Mobile phone & Mobiltelefon \\ + \Macro{phonename} & Phone & Telefon \\ + \Macro{subjectname} & Subject & Betrifft \\ + \Macro{wwwname} & Url & URL \\ + \Macro{yourmailname} & Your letter of & Ihr Schreiben vom\\ + \Macro{yourrefname} & Your ref. & Ihr Zeichen \\ + \bottomrule + \end{tabular} + \deffootnote{1em}{1em}{1\ }% brutal aber effektiv + \footnotetext[1000]{Normally these terms are defined by language + packages like \Package{babel}. In this case, \KOMAScript{} does not + redefine them. The actual wording may therefore differ and can + be found in the documentation for the language package used.} +% \end{captionbeside} + \end{minipage} +\end{table} +% +\EndIndexGroup +\iffree{}{\clearpage}% Umbruchkorrektur + +\begin{Declaration} + \Macro{dateacadian} + \Macro{dateamerican} + \Macro{dateaustralien} + \Macro{dateaustrian} + \Macro{datebritish} + \Macro{datecanadian} + \Macro{datecanadien} + \Macro{datecroatian} + \Macro{dateczech} + \Macro{datedutch} + \Macro{dateenglish} + \Macro{datefinnish} + \Macro{datefrancais} + \Macro{datefrench} + \Macro{dategerman} + \Macro{dateitalian} + \Macro{datenaustrian} + \Macro{datenewzealand} + \Macro{datengerman} + \Macro{datenorsk} + \Macro{datenswissgerman} + \Macro{datepolish} + \Macro{dateslovak} + \Macro{datespanish} + \Macro{dateswedish} + \Macro{dateswissgerman} + \Macro{dateUKenglish} + \Macro{dateUSenglish} +\end{Declaration} +Depending on the language used, the numerical representation of the date\Index{date} (see option +\DescRef{scrlttr2.option.numericaldate} in \autoref{sec:scrlttr2.firstpage}, +\DescPageRef{scrlttr2.option.numericaldate}) is formatted in various ways. +The exact format can be found in \autoref{tab:date}.% +\EndIndexGroup +% +\EndIndexGroup +\iffree{}{\clearpage}% Umbruchkorrektur zwecks Ausgabe der Tabellen + +\begin{table}[!tp]% Umbruchoptimierung +% \centering + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% +% \caption + \begin{captionbeside}{Language-dependent forms of the date}[l] + \begin{tabular}[t]{ll} + \toprule + Command & Date Example \\ + \midrule + \Macro{dateacadian} & 24.\,12.\,1993\\ + \Macro{dateamerican} & 12/24/1993\\ + \Macro{dateaustralien}& 24/12/1993\\ + \Macro{dateaustrian} & 24.\,12.\,1993\\ + \Macro{datebritish} & 24/12/1993\\ + \Macro{datecanadian} & 1993/12/24\\ + \Macro{datecanadien} & 1993/12/24\\ + \Macro{datecroatian} & 24.\,12.\,1993.\\ + \Macro{dateczech} & 24.\,12.\,1993\\ + \Macro{datedutch} & 24.\,12.\,1993\\ + \Macro{dateenglish} & 24/12/1993\\ + \Macro{datefinnish } & 24.12.1993.\\ + \Macro{datefrancais} & 24.\,12.\,1993\\ + \Macro{datefrench} & 24.\,12.\,1993\\ + \Macro{dategerman} & 24.\,12.\,1993\\ + \Macro{dateitalian} & 24.\,12.\,1993\\ + \Macro{datenaustrian} & 24.\,12.\,1993\\ + \Macro{datenewzealand}& 24/12/1993\\ + \Macro{datengerman} & 24.\,12.\,1993\\ + \Macro{datenorsk} & 24.12.1993\\ + \Macro{datenswissgerman} & 24.\,12.\,1993\\ + \Macro{datepolish} & 24.\,12.\,1993\\ + \Macro{dateslovak} & 24.\,12.\,1993\\ + \Macro{datespanish} & 24.\,12.\,1993\\ + \Macro{dateswedish} & 24/12 1993\\ + \Macro{dateswissgerman} & 24.\,12.\,1993\\ + \Macro{dateUKenglish} & 24/12/1993\\ + \Macro{dateUSenglish} & 12/24/1993\\ + \bottomrule + \end{tabular} + \end{captionbeside} + \label{tab:date} +\end{table} +% +\section{Obsolete Commands in \Class{scrlttr2}} +\seclabel{obsolete} +\BeginIndexGroup + +\LoadNonFree{scrlttr2-experts}{1} +\EndIndexGroup +% +\iffalse% Es wird Zeit das komplett rauszuwerfen! +\section{From Obsolete \Class{scrlettr} to Current \Class{scrlttr2}} +\seclabel{fromscrlettr} + +With\textnote{Attention!} the 2002 release of \Class{scrlttr2} (see +\autoref{cha:scrlttr2}), the old letter class, \Class{scrlettr}, became +obsolete, and it is no longer part of \KOMAScript. If you still need the class +or information about it, you will find it in +\cite{package:koma-script-obsolete}. + +To facilitate the transition to the new class, there is the compatibility +option \Option{KOMAold}. Basically, all the older functionality still +exists in the new class. Without \Option{KOMAold}, however, the user +interface and the defaults are different. More details on +this option are provided in \autoref{sec:scrlttr2.lcoFile}, +\autoref{tab:lcoFiles}. + +\LoadNonFree{scrlttr2-experts}{2} +% +\EndIndexGroup +\fi +% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% ispell-local-dictionary: "english" +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrlttr2.tex b/macros/latex/contrib/koma-script/source-doc/english/scrlttr2.tex new file mode 100644 index 0000000000..e63f59c2ab --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrlttr2.tex @@ -0,0 +1,3463 @@ +% ====================================================================== +% scrlttr2.tex +% Copyright (c) Markus Kohm, 2002-2019 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrlttr2.tex +% Copyright (c) Markus Kohm, 2002-2019 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrlttr2 of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber scrlttr2 in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrlttr2.tex}% + [$Date: 2019-01-15 08:39:58 +0100 (Tue, 15 Jan 2019) $ + 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\and + Karl Hagen} + +% Date of the translated German file: 2018-04-26 + +\chapter{Letters with the \Class{scrlttr2} Class or the \Package{scrletter} + Package} +\labelbase{scrlttr2} + +\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} +\seclabel{variables}% +\BeginIndexGroup +\BeginIndex{}{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} + %\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}{% + 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 % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.backaddress})}% + \ventry{% + backaddressseparator}{separator within the return address % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.backaddressseparator})}% + \ventry{ccseparator}{% + separator between title of additional addresses (cc list) + and additional addresses % + (\autoref{sec:\LabelBase.document}, + \DescPageRef{\LabelBase.variable.ccseparator})}% + \ventry{customer}{% + customer number % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.customer})}% + \ventry{date}{% + date % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.date})}% + \ventry{emailseparator}{% + separator between email name and email address % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.emailseparator})}% + \ventry{enclseparator}{% + 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 % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.faxseparator})}% + \ventry{firstfoot}{% + footer\ChangedAt{v3.08}{\Class{scrlttr2}} of the letterhead page % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.firstfoot})}% + \ventry{firsthead}{% + header\ChangedAt{v3.08}{\Class{scrlttr2}} of the letterhead page % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.firsthead})}% + \ventry{fromaddress}{% + sender's address without sender name % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.fromaddress})}% + \ventry{frombank}{% + sender's bank details % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.frombank})}% + \ventry{fromemail}{% + sender's e-mail % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.fromemail})}% + \ventry{fromfax}{% + sender's fax number % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.fromfax})}% + \ventry{fromlogo}{% + commands for inserting the sender's logo % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.fromlogo})}% + \ventry{frommobilephone}{% + \ChangedAt{v3.12}{\Class{scrlttr2}}% + sender's mobile telephone number % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.frommobilephone})}% + \ventry{fromname}{% + complete name of sender % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.fromname})}% + \ventry{fromphone}{% + sender's telephone number % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.fromphone})}% + \ventry{fromurl}{% + URL of the sender, e.\,g. of the sender's homepage % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.fromurl})}% + \ventry{fromzipcode}{% + 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}{% + invoice number % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.invoice})}% + \ventry{location}{% + extra details of the sender % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.location})}% + \ventry{myref}{% + sender's reference % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.myref})}% + \ventry{nextfoot}{% + 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}{% + header\ChangedAt{v3.08}{\Class{scrlttr2}} using page style + \PageStyle{headings}\IndexPagestyle{headings} or + \PageStyle{myheadings}\IndexPagestyle{myheadings} % + (\autoref{sec:\LabelBase.pagestyle}, + \DescPageRef{\LabelBase.variable.nexthead})}% + \ventry{phoneseparator}{% + separator between title of telephone and telephone number % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.phoneseparator})}% + \ventry{place}{% + sender's location; used next to date % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.place})}% + \ventry{placeseparator}{% + separator between location and date % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.placeseparator})}% + \ventry{PPdatamatrix}{% + command to print the data array for the + \OptionValueRef{\LabelBase}{addrfield}{PP} option % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.PPdatamatrix})}% + \ventry{PPcode}{% + 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 annotation beneath the closing text of the letter % + (\autoref{sec:\LabelBase.closing}, + \DescPageRef{\LabelBase.variable.signature})}% + \ventry{specialmail}{% + delivery method % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.specialmail})}% + \ventry{subject}{% + letter's subject % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.subject})}% + \ventry{subjectseparator}{% + separator between subject title and subject % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.subjectseparator})}% + \ventry{title}{% + letter title % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.title})}% + \ventry{toaddress}{% + address of recipient without recipient name % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.toaddress})}% + \ventry{toname}{% + complete name of recipient % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.toname})}% + \ventry{yourmail}{% + date of recipient's referenced mail % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.yourmail})}% + \ventry{yourref}{% + recipient's reference % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.yourref})}% + \ventry{zipcodeseparator}{% + separator between the title of ZIP code (postal code) and the code itself % + (\autoref{sec:\LabelBase.firstpage}, + \DescPageRef{\LabelBase.variable.zipcodeseparator})}% +\end{desclist} + +\begin{Declaration} + \Macro{setkomavar}% + \Parameter{name}\OParameter{description}\Parameter{content}% + \Macro{setkomavar*}\Parameter{name}\Parameter{description} +\end{Declaration} +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} + 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 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 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 + + +\begin{Declaration} + \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 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{then code}\Parameter{else code} +\end{Declaration} +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{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 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} +\seclabel{pseudoLength} +\BeginIndexGroup +\BeginIndex{}{pseudo-lengths} + +\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 +descriptions of the individual pseudo-lengths are found in the individual +sections of this chapter. + +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 should also be a matter for advanced users, so this is also described +in the part for experts, on \DescPageRef{scrlttr2-experts.cmd.setplength}. + +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 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 +\autoref{sec:\LabelBase.lcoFile} ab \autopageref{sec:\LabelBase.lcoFile}).% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{setlengthtoplength}% + \OParameter{factor}\Parameter{length}\Parameter{pseudo-length}% + \Macro{addtolengthplength}% + \OParameter{factor}\Parameter{length}\Parameter{pseudo-length} +\end{Declaration} +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 + % \KOMAScript{}} + +\LoadCommonFile{draftmode} % \section{Draft-Mode} + +\LoadCommonFile{typearea} % \section{Page Layout} + +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 + + +\section{General Structure of Letter Documents} +\seclabel{document} +\BeginIndexGroup +\BeginIndex{}{letter>structure} + +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 containing 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}% + }[l] + \begin{minipage}[b]{.667\linewidth} + \centering\small\setlength{\fboxsep}{1.5ex}% + \addtolength{\linewidth}{-\dimexpr2\fboxrule+2\fboxsep\relax}% + \fbox{\parbox{\linewidth}{\raggedright% + \Macro{documentclass}\OParameter{\dots}\PParameter{scrlttr2}\\ + \dots\\ + {\centering\emph{settings for all letters}\\} + \dots\\ + \Macro{begin}\PParameter{document}\\ + \dots\\ + {\centering\emph{settings for all letters}\\} + \dots\\ + }}\\ + \fbox{\parbox{\linewidth}{\raggedright% + \Macro{begin}\PParameter{letter}\Parameter{recipient}\\ + \dots\\ + {\centering\emph{content of the individual letter}\\} + \dots\\ + \Macro{end}\PParameter{letter}\\ + }}\\[2pt] + \parbox{\linewidth}{\raggedright\vspace{-.5ex}\vdots\vspace{1ex}}\\ + \fbox{\parbox{\linewidth}{\raggedright% + \Macro{end}\PParameter{document}\\ + }}\\[\dimexpr\fboxsep+\fboxrule\relax] + \end{minipage} + \end{captionbeside} +\end{figure} + +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}). + +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}. + +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}% + \setcapindent{0pt}% + \begin{captionbeside}[{% + General structure of a single letter within a letter document% + }]{% + General structure of a single letter within a letter document (see also + \autoref{fig:\LabelBase.document})% + \label{fig:\LabelBase.letter}}[l] + \begin{minipage}[b]{.667\linewidth}% + \centering\small\setlength{\fboxsep}{1.5ex}% + \addtolength{\linewidth}{-\dimexpr2\fboxrule+2\fboxsep\relax}% + \fbox{\parbox{\linewidth}{\raggedright% + \Macro{begin}\PParameter{letter}% + \OParameter{options}\Parameter{recipient}\\ + \dots\\[\dp\strutbox] + {\centering\emph{settings for this letter}\\} + \dots\\ + \DescRef{\LabelBase.cmd.opening}\Parameter{salutation}\\ + }}\\[1pt] + \fbox{\parbox{\linewidth}{\raggedright% + \dots\\[\dp\strutbox] + {\centering\emph{letter text}\\} + \dots\\ + }}\\[1pt] + \fbox{\parbox{\linewidth}{\raggedright% + \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 recipients}\\ + \Macro{end}\PParameter{letter}\\ + }}\\[\dimexpr\fboxsep+\fboxrule\relax] + \end{minipage} + \end{captionbeside} +\end{figure} + +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{recipient} + \end{Environment} +\end{Declaration} +\BeginIndex{}{address}% +The \Environment{letter} environment is one of the key environments of 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{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}% + 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[british]{babel} + \begin{document} + \begin{letter}{Joanna Public\\ + 1 Hillside\\ + SAMPLESTEAD\\ + WX12 3YZ} + \end{letter} + \end{document} +\end{lstcode} + 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} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{AtBeginLetter}\Parameter{code}% + \Macro{AtEndLetter}\Parameter{code} +\end{Declaration} +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}. 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 +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} + 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]{% + \refstepcounter{Question}\par + \noindent\begin{tabularx}{\textwidth}{l@{}X} + \theQuestion:~ & #1\\ + \end{tabularx}% + }% + \AtBeginLetter{\setcounter{Question}{0}} +\end{lstlisting} + This way first question remains question~1, even in the 1001st letter. Of + course the definition in this example requires the + \Package{tabularx}\IndexPackage{tabularx} package (see + \cite{package:tabularx}). +\end{Example}% +% +\EndIndexGroup + + +\begin{Declaration} + \Counter{letter}% + \Macro{thisletter}% + \Macro{letterlastpage} +\end{Declaration} +If\ChangedAt{v3.19}{\Class{scrlttr2}\and \Package{scrletter}} you have more +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} + Let's return to the \DescRef{\LabelBase.cmd.AtBeginLetter} + example. Instead of resetting the counter explicitly at + \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]{% + \refstepcounter{Question}\par + \noindent\begin{tabularx}{\textwidth}{l@{}X} + \theQuestion:~ & #1\\ + \end{tabularx}% + }% +\end{lstlisting} + 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 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 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{salutation} +\end{Declaration} +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 return to the example of + \DescPageRef{\LabelBase.env.letter.example} and add a salutation: + \lstinputcode[xleftmargin=1em]{letter-0.tex} + This will result in the letterhead shown in + \autoref{fig:\LabelBase.letter-0}. + \begin{figure} + \setcapindent{0pt}% + \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 +\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{concluding text} +\end{Declaration} +The main purpose of the command \Macro{closing} is to typeset the +\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. + +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 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 recipient, opening, text, and + closing}]{% + 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} + \end{figure} +\end{Example} +% +\EndIndexGroup + +\begin{Declaration} + \Macro{ps} +\end{Declaration}% +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 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 recipient, opening, text, + closing, and postscript}]{% + 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} + \end{figure} +\end{Example} + +\begin{Explain} + 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 + + +\begin{Declaration} + \Macro{cc}\Parameter{distribution list}% + \Variable{ccseparator}% +\end{Declaration} +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 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 recipient, opening, text, + closing, postscript, and distribution list}]{% + 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} +A vertical gap is inserted automatically before the distribution list.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{encl}\Parameter{enclosures}% + \Variable{enclseparator}% +\end{Declaration} +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} + 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 recipient, opening, text, + closing, postscript, distribution list, and enclosure}]{% + 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} + \end{figure} +\end{Example} +% +\EndIndexGroup +% +\EndIndexGroup + + +\LoadCommonFile{fontsize} % \section{Choosing the Document Font Size} + +\LoadCommonFile{textmarkup} % \section{Text Markup} + +\section{Letterhead Page} +\seclabel{firstpage} +\BeginIndexGroup +\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 letterhead page outlining the most + important commands and variables} + \label{fig:\LabelBase.variables} +\end{figure} + + +\begin{Declaration} + \OptionVName{foldmarks}{setting} +\end{Declaration} +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 + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% +% \caption + \begin{captionbeside}{% + Combinable values for configuring fold marks with the + \Option{foldmarks} option% + }[l] + \begin{tabular}[t]{ll} + \toprule + \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} + \label{tab:\LabelBase.foldmark} +\end{table} +% +\begin{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} + 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 recipient, opening, text, + closing, postscript, distribution list, enclosure, and hole-punch + mark}]{% + 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}% +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 the \FontElement{foldmark} element. The default is no change.% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{enlargefirstpage}{simple switch} +\end{Declaration} +\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 + + +\begin{Declaration} + \OptionVName{firsthead}{simple switch} +\end{Declaration} +\BeginIndex{}{letterhead}% +\BeginIndex{}{letter>header}% +The\ChangedAt{v2.97e}{\Class{scrlttr2}} letterhead is usually the topmost +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 + + +\begin{Declaration} + \OptionVName{fromalign}{method} +\end{Declaration} +\BeginIndex{}{letterhead}% +\BeginIndex{}{letter>head}% +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 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}}{% + 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}}{% + The default design will be used for the sender information; the + letterhead extensions are deactivated.}% + \entry{\PValue{left}}{% + 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}}{% + 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}}{% + 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}}{% + Sender information is right-justified; a logo is placed left-justified, + if applicable; letterhead extensions are activated}% + \end{desctabular} +\end{table} +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{fromrule}{position}% + \Variable{fromname}% + \Variable{fromaddress}% +\end{Declaration} +\BeginIndex{}{letterhead}% +\BeginIndex{}{letter>head}% +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. + +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{\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[{Available values for the \Option{fromrule} option with + \Class{scrlttr2}}]{Available values for 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 sender's address}% + \entry{\PValue{aftername}}{% + rule directly below the sender's name}% + \entry{\PValue{false}, \PValue{no}, \PValue{off}}{% + no rule}% + \end{desctabular} +\end{table} + +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 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}% +You can set the font used for the complete sender information with the +\FontElement{fromaddress}\IndexFontElement{fromaddress}% +\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}} 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} + 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, recipient, opening, text, closing, + postscript, distribution list, and enclosure}] + {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} + 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}% + 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, rule, recipient, + opening, text, closing, signature, postscript, distribution list, + enclosure, and hole-punch mark}] + {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): + 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} +\end{Example} + +An\textnote{Attention!} important note concerns the sender's address: within +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}% + \OptionVName{frommobilephone}{simple switch}% + \OptionVName{fromfax}{simple switch}% + \OptionVName{fromemail}{simple switch}% + \OptionVName{fromurl}{simple switch}% + \Variable{fromphone}% + \Variable{frommobilephone}% + \Variable{fromfax}% + \Variable{fromemail}% + \Variable{fromurl}% + \Variable{phoneseparator}% + \Variable{mobilephoneseparator}% + \Variable{faxseparator}% + \Variable{emailseparator}% + \Variable{urlseparator}% +\end{Declaration} +\BeginIndex{}{letterhead}% +\BeginIndex{}{letter>header} +You can use the five options \Option{fromphone}, \Option{frommobilephone}\ChangedAt{v3.12}{\Class{scrlttr2}}, \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 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[{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}% + \DescRef{\LabelBase.cmd.usekomavar}\PParameter{emailseparator}}% + \ventry{fromfax}{\DescRef{\LabelBase.cmd.usekomavar*}\PParameter{faxseparator}% + \DescRef{\LabelBase.cmd.usekomavar}\PParameter{faxseparator}}% + \ventry{frommobilephone}{% + \ChangedAt{v3.12}{\Class{scrlttr2}}% + \DescRef{\LabelBase.cmd.usekomavar*}\PParameter{mobilephoneseparator}% + \DescRef{\LabelBase.cmd.usekomavar}\PParameter{mobilephoneseparator}}% + \ventry{fromname}{\DescRef{scrlttr2-experts.cmd.headfromname}}% + \ventry{fromphone}{\DescRef{\LabelBase.cmd.usekomavar*}\PParameter{phoneseparator}% + \DescRef{\LabelBase.cmd.usekomavar}\PParameter{phoneseparator}}% + \ventry{fromurl}{\DescRef{\LabelBase.cmd.usekomavar*}\PParameter{urlseparator}% + \DescRef{\LabelBase.cmd.usekomavar}\PParameter{urlseparator}}% + \end{desctabular} + \label{tab:\LabelBase.fromTerm} +\end{table} + +\begin{table}[tp] + \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 \\ + \midrule + \Variable{emailseparator} & \DescRef{scrlttr2-experts.cmd.emailname} & \texttt{:\~} \\ + \Variable{faxseparator} & \DescRef{scrlttr2-experts.cmd.faxname} & \texttt{:\~} \\ + \Variable{mobilephoneseparator} & \DescRef{scrlttr2-experts.cmd.mobilephonename} & \Macro{usekomavaer}\PParameter{phoneseparator} \\ + \Variable{phoneseparator} & \DescRef{scrlttr2-experts.cmd.phonename} & \texttt{:\~} \\ + \Variable{urlseparator} & \DescRef{scrlttr2-experts.cmd.wwwname} & \texttt{:\~} \\ + \bottomrule + \end{tabular} +% \end{captionbeside} + \label{tab:\LabelBase.fromSeparator} +\end{table} + +\begin{Example} + 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}% + 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 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} + + 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 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} +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{fromlogo}{simple switch}% + \Variable{fromlogo}% +\end{Declaration} +\BeginIndex{}{letterhead}% +\BeginIndex{}{letter>head}% +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 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 loads the + \Package{graphics}\IndexPackage{graphics} package (see + \cite{package:graphics}).% + \lstinputcode[xleftmargin=1em]{letter-16}% + 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 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} + \label{fig:\LabelBase.letter-16-18} + \end{figure} +\end{Example}% +% +\EndIndexGroup + + +\begin{Declaration} + \Variable{firsthead}% +\end{Declaration} +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{}{You can find + a detailed example of a letterhead definition in + \autoref{cha:modernletters}.}% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{addrfield}{format}% + \OptionVName{backaddress}{value}% + \OptionVName{priority}{priority}% + \Variable{toname}% + \Variable{toaddress}% + \Variable{backaddress}% + \Variable{backaddressseparator}% + \Variable{specialmail}% + \Variable{fromzipcode}% + \Variable{zipcodeseparator}% + \Variable{place}% + \Variable{PPcode}% + \Variable{PPdatamatrix}% + \Variable{addresseeimage}% +\end{Declaration}% +\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}% +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}). 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 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 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 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}}{% + Does not print an address.}% + \entry{\PValue{image}, \PValue{Image}, \PValue{PPimage}, \PValue{PPImage}, + \PValue{ppimage}, \PValue{ppImage}}{% + 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 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 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 delivery type + or priority.}% + \end{desctabular} +\end{table}% + +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, 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 place it flush with the top of the available space.% + +\begin{table} +% \centering + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% +% \caption + \begin{captionbeside}{% + Default font styles for the elements of the address field.% + }% + [l] + \begin{tabular}[t]{ll} + \toprule + element & font style \\ + \midrule + \DescRef{\LabelBase.fontelement.addressee}\IndexFontElement{addressee} & + \\ + \DescRef{\LabelBase.fontelement.backaddress}\IndexFontElement{backaddress} & + \Macro{sffamily}% + \\ + \DescRef{\LabelBase.fontelement.PPdata}\IndexFontElement{PPdata} & + \Macro{sffamily}% + \\ + \DescRef{\LabelBase.fontelement.PPlogo}\IndexFontElement{PPlogo} & + \Macro{sffamily}\Macro{bfseries}% + \\ + \DescRef{\LabelBase.fontelement.priority}\IndexFontElement{priority} & + \Macro{fontsize}\PParameter{10pt}\PParameter{10pt}% + \Macro{sffamily}\Macro{bfseries}% + \\ + \DescRef{\LabelBase.fontelement.prioritykey}\IndexFontElement{prioritykey} & + \Macro{fontsize}\PParameter{24.88pt}\PParameter{24.88pt}% + \Macro{selectfont}% + \\ + \DescRef{\LabelBase.fontelement.specialmail}\IndexFontElement{specialmail} & + \\ + \DescRef{\LabelBase.fontelement.toaddress}\IndexFontElement{toaddress} & + \\ + \DescRef{\LabelBase.fontelement.toname}\IndexFontElement{toname} & + \\ + \bottomrule + \end{tabular} + \end{captionbeside} + \label{tab:\LabelBase.AddresseeElements}% +\end{table} + +\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 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}).% +\EndIndexGroup + +\BeginIndexGroup +\BeginIndex{FontElement}{priority}\LabelFontElement{priority}% +\BeginIndex{FontElement}{prioritykey}\LabelFontElement{prioritykey}% +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}, 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 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}}{% + Priority will not be printed.}% + \entry{\PValue{B}, \PValue{b}, \PValue{economy}, \PValue{Economy}, + \PValue{ECONOMY}, \PValue{B-ECONOMY}, \PValue{B-Economy}, + \PValue{b-economy}}{% + Use international priority B-Economy. With + \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 is printed instead of the delivery + type.}% + \end{desctabular} +\end{table} + +With\ChangedAt{v3.03}{\Class{scrlttr2}}\important{\OptionValue{addrfield}{PP}} +\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{,}). + +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}).% +\EndIndexGroup + +\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}} +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 printed with the \OptionValue{addrfield}{backgroundimage} option. + +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} (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}). + +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 +must load an additional graphics package like +\Package{graphics}\IndexPackage{graphics} or +\Package{graphicx}\IndexPackage{graphicx} and use, for instance, the +\Macro{includegraphics} command in the \PName{content} of the variables.% +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{locfield}{setting} +\end{Declaration} +\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'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} +% \centering + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% +% \caption + \begin{captionbeside} + [{Available values for the \Option{locfield} option with + \Class{scrlttr2}}]{Available values for 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 extra sender information field}% + \pventry{wide}{wide extra sender information field}% + \end{desctabular} + \end{minipage} + \end{captionbeside} +\end{table} + +\begin{Declaration} + \Variable{location}% +\end{Declaration} +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 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 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, + 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 + + +\begin{Declaration} + \OptionVName{numericaldate}{simple switch} +\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 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 +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 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 location. +% +\EndIndexGroup +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{refline}{selection} +\end{Declaration} +\BeginIndex{}{reference line}% +\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[{Available values for the \Option{refline} option with + \Class{scrlttr2}}]{Available values for 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 is placed leftmost in the reference line.}% + \pventry{dateright}{\ChangedAt{v3.09}{\Class{scrlttr2}}% + 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 width of the reference line depends on the positions of + the address and extra sender information.}% + \end{desctabular} +\end{table} + +\begin{Declaration} + \Variable{yourref}% + \Variable{yourmail}% + \Variable{myref}% + \Variable{customer}% + \Variable{invoice}% +\end{Declaration} +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}[{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 + 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 \\ + \bottomrule + \end{tabular} + \end{captionbeside} + \label{tab:\LabelBase.reflineTerm} +\end{table} + +\BeginIndexGroup +\BeginIndex{FontElement}{refname}\LabelFontElement{refname}% +\BeginIndex{FontElement}{refvalue}\LabelFontElement{refvalue}% +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} elements using the \DescRef{\LabelBase.cmd.setkomafont} +and \DescRef{\LabelBase.cmd.addtokomafont} commands (see +\autoref{sec:\LabelBase.textmarkup}, +\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} + [{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} + \toprule + element & default configuration \\ + \midrule + \DescRef{\LabelBase.fontelement.refname} & \Macro{sffamily}\Macro{scriptsize} \\ + \DescRef{\LabelBase.fontelement.refvalue} & \\ + \bottomrule + \end{tabular} + \end{captionbeside} +\end{table}% +% +\EndIndexGroup + + +\begin{Declaration} + \Variable{placeseparator}% +\end{Declaration}% +\BeginIndex{Variable}{place}% +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}% +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}).% +\EndIndexGroup + +\begin{Example} + Now Mr Public also sets the variable for the location:% + \lstinputcode[xleftmargin=1em]{letter-20.tex}% + 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, + recipient, extra sender information, location, date, 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, location, date, opening, text, closing, + signature, postscript, distribution list, enclosure and hole-punch + mark}[l] + \frame{\includegraphics[width=.4\textwidth]{letter-20}} + \end{captionbeside} + \label{fig:\LabelBase.letter-20} + \end{figure} +\end{Example} +% +\EndIndexGroup +\EndIndexGroup +\EndIndexGroup + + +\begin{Declaration} + \Variable{title}% +\end{Declaration} +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}% +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. 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} + Suppose you are writing a reminder letter. You set a corresponding title: +\begin{lstlisting} + \setkomavar{title}{Reminder} +\end{lstlisting} + This way the recipient should recognize the reminder as such. +\end{Example} +As shown in the example, the \PName{content} of the variable defines the +title. \KOMAScript{} does not use the \PName{description}.% +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{subject}{selection}% + \Variable{subject}% + \Variable{subjectseparator}% +\end{Declaration} +\BeginIndex{}{subject}% +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}{Default descriptions of variables for the subject} + [l] + \begin{tabular}[t]{lll} + \toprule + variable name & description \\ + \midrule + \Variable{subject} & \DescRef{\LabelBase.cmd.usekomavar*}\PParameter{subjectseparator}% + \texttt{\%} \\ + & \texttt{\quad}% + \DescRef{\LabelBase.cmd.usekomavar}\PParameter{subjectseparator} \\ + \Variable{subjectseparator} & \DescRef{scrlttr2-experts.cmd.subjectname} \\ + \bottomrule + \end{tabular} + \end{captionbeside} + \label{tab:\LabelBase.subjectTerm} +\end{table} + +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}} for the subject with +\OptionValue{subject}{underlined}, \OptionValue{subject}{centered}, or +\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}.% +% +\begin{table} +% \centering + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% +% \caption + \begin{captionbeside} + [{Available values for the \Option{subject} option with \Class{scrlttr2}}] + {Available values for the \Option{subject} option for the position and + formatting of the subject with + \Class{scrlttr2}\label{tab:\LabelBase.subject}}% + [l] + \begin{minipage}[t]{.6\linewidth} + \begin{desctabular}[t] + \pventry{afteropening}{subject after opening}% + \pventry{beforeopening}{subject before opening}% + \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)}% + \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 \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see +\autoref{sec:\LabelBase.textmarkup}, +\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 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} + 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 in \autoref{fig:\LabelBase.letter-21}. + \begin{figure} + \setcapindent{0pt}% + \begin{captionbeside}[{Example: letter with extended sender, logo, + recipient, extra sender information, place, date, subject, + 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, place, date, subject, opening, text, + closing, signature, postscript, distribution list, enclosure and + hole-punch mark}[l] + \frame{\includegraphics[width=.4\textwidth]{letter-21}} + \end{captionbeside} + \label{fig:\LabelBase.letter-21} + \end{figure} +\end{Example} +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{firstfoot}{simple switch} +\end{Declaration} +\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{}{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. + +\BeginIndex{Variable}{frombank}% +\begin{Example} + 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}{% + \centering\def\\{, }\usekomavar{frombank}% + }% + } +\end{lstcode} + You can also define your own variable for the separator. I leave + this as an exercise for the reader. + + 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 + \begin{tabular}[t]{l@{}}% + \multicolumn{1}{@{}l@{}}{Partners:}\\ + Jim Smith\\ + Russ Mayer + \end{tabular}% + \hfill + \begin{tabular}[t]{l@{}}% + \multicolumn{1}{@{}l@{}}{Managing Director:}\\ + Lisa Mayer\\[1ex] + \multicolumn{1}{@{}l@{}}{Court Jurisdiction:}\\ + Great Plains + \end{tabular}% + \ifkomavarempty{frombank}{}{% + \hfill + \begin{tabular}[t]{l@{}}% + \multicolumn{1}{@{}l@{}}{\usekomavar*{frombank}:}\\ + \usekomavar{frombank} + \end{tabular}% + }% + }% + } +\end{lstcode} + 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. 12345678\\ + Buffoon Bank\\ + Bank Code: 65-43-21} +\end{lstcode} + 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} + +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 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{Headers and Footers with the Default Page Style} +\seclabel{pagestyle} +\BeginIndexGroup +\BeginIndex{}{page>style}% +\BeginIndex{}{page>header}% +\BeginIndex{}{page>footer}% + +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 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 the \Package{scrletter} package. +\begin{Example} + 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. Notice the star in \Macro{renewcommand*}. +\end{Example} +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 + + +\begin{Declaration} + \OptionVName{headsepline}{simple switch}% + \OptionVName{footsepline}{simple switch} +\end{Declaration} +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 + + +\begin{Declaration} + \OptionVName{pagenumber}{position} +\end{Declaration} +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 for the \Option{pagenumber} option with + \Class{scrlttr2}}]{Available values for the \Option{pagenumber} option to + position the page number in the \PageStyle{headings}, + \PageStyle{myheadings}, and \PValue{plain} page styles with + \Class{scrlttr2}} + \label{tab:\LabelBase.pagenumber} + \begin{desctabular} + \entry{\PValue{bot}, \PValue{foot}}{% + page number in footer, horizontal position unchanged}% + \entry{\PValue{botcenter}, \PValue{botcentered}, \PValue{botmittle}, + \PValue{footcenter}, \PValue{footcentered}, \PValue{footmiddle}}{% + page number in footer, centred}% + \entry{\PValue{botleft}, \PValue{footleft}}{% + page number in footer, left-justified}% + \entry{\PValue{botright}, \PValue{footright}}{% + page number in footer, right-justified}% + \entry{\PValue{center}, \PValue{centered}, \PValue{middle}}{% + 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 unchanged}% + \entry{\PValue{headcenter}, \PValue{headcentered}, \PValue{headmiddle}, + \PValue{topcenter}, \PValue{topcentered}, \PValue{topmiddle}}{% + page number in header, centred}% + \entry{\PValue{headleft}, \PValue{topleft}}{% + page number in header, left-justified}% + \entry{\PValue{headright}, \PValue{topright}}{% + page number in header, right-justified}% + \entry{\PValue{left}}{% + page number left, vertical position unchanged}% + \entry{\PValue{right}}{% + page number right, vertical position unchanged}% + \end{desctabular} +\end{table} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{pagestyle}\Parameter{page style}% + \Macro{thispagestyle}\Parameter{local page style} +\end{Declaration}% +\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}\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}}] + \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}). 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} 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} + +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} 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. + +\BeginIndexGroup +\BeginIndex[indexother]{}{font>style}% +\BeginIndex{FontElement}{pageheadfoot}\LabelFontElement{pageheadfoot}% +\BeginIndex{FontElement}{pagefoot}\LabelFontElement{pagefoot}% +\BeginIndex{FontElement}{pagenumber}\LabelFontElement{pagenumber}% +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}. 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 +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{markboth}\Parameter{left mark}\Parameter{right mark}% + \Macro{markright}\Parameter{right mark} +\end{Declaration} +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, 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} for either variable. +% +%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 + + +\LoadCommonFile{interleafpage}% \section{Interleaf Pages} + +\LoadCommonFile{footnotes}% \section{Footnotes} + +\LoadCommonFile{lists}% \section{Lists} + + +\section{Mathematics} +\seclabel{math}% +\BeginIndexGroup +\BeginIndex{}{equations}% +\BeginIndex{}{formulas}% +\BeginIndex{}{mathematics}% + +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 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 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} + + +\section{Closing} +\seclabel{closing} +\BeginIndexGroup% +\BeginIndex{}{closing}% +\BeginIndex{}{letter>closing}% +\BeginIndex{}{signature}% +\BeginIndex{}{letter>signature}% + +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{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} +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 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, + recipient, extra sender information, place, date, subject, + opening, text, closing, modified signature, postscript, distribution + 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 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 +% +\EndIndexGroup + + +\section{Letter Class Option Files} +\seclabel{lcoFile}% +\BeginIndexGroup +\BeginIndex{}{lco file=\File{lco} file}% +\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. 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. 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.addtoplength}\IndexCmd{addtoplength} (see +\autoref{sec:scrlttr2-experts.pseudoLengths}). + +\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}\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} + 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, 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}{% + Joanna Public\\ + 1 Hillside\\ + SAMPLESTEAD\\ + WX12 3YZ} + \LoadLetterOption{DINmtext} + \opening{Hello,} +\end{lstcode} + 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 must not have the same name as an option. + +\begin{Example} + 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 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, + recipient, extra sender information, place, date, subject, + opening, text, closing, modified signature, postscript, distribution + 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 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} + +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 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. In +addition, you should also reduce \PLength{toaddrwidth} accordingly.% + +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.% + +\begin{desclist} + \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% + \desccaption{% + Predefined \File{lco} files\label{tab:lcoFiles}% + }{% + Predefined \File{lco} files (\emph{continued})% + }% + \oentry{DIN}{% + \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}{% + \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}{% + \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}{% + \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 differently with this \File{lco} file + than with the other \File{lco} files.}% + \oentry{NF}{% + \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}{% + \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}{% + \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}{% + \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}{% + \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}{% + \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}{% + \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}{% + \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}{% + \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}{% + \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 +% +\EndIndexGroup + + +\section{Address Files and Form Letters} +\seclabel{addressFile}% +\BeginIndexGroup +\BeginIndex{}{address>file}% +\BeginIndex{}{form letters}% +\index{serial letters|see form letters}% +\index{circular letters|see form letters}% + +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}% +\fi% +.% +\iffalse% Umbruchkorrekturtext +\ Currently there are plans for greatly enhanced support.% +\fi + +\begin{Declaration} + \Macro{adrentry}\Parameter{last~name}\Parameter{first~name}% + \Parameter{address}\Parameter{phone}\Parameter{F1}\Parameter{F2}% + \Parameter{comment}\Parameter{key} +\end{Declaration}% +\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} + {1 High Street\\ Glasgow} + {0141 123 4567} + {builder} + {} + {buys everything} + {FLANN} +\end{lstcode} +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. 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} + 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}% +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 + +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} + 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, 12 August 2002. + + The following topics are \dots + \closing{Regards,} + \end{letter} + } + \input{members.adr} + \end{document} +\end{lstcode} + 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 example, the extra freely-definable parameter is not used, and + therefore \DescRef{\LabelBase.cmd.addrentry} is defined using + \DescRef{\LabelBase.cmd.adrentry}. +\end{Example} + +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 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 (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 Ms #2,} \fi + + Unfortunately, we have noticed that you are in arrears + with the payment of your membership fees. + + Please remit the outstanding balance of \pounds #6 to the club + account. + \closing{Regards,} + \end{letter} + \fi + } +\end{lstcode} +\end{Example} +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 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, rather tiny address file from which you + want to create an address book: +\begin{lstlisting} + \adrchar{A} + \adrentry{Angel}{Gabriel} + {Cloud 3\\12345 Heaven's Realm} + {000\,01\,02\,03}{}{}{archangel}{GABRIEL} + \adrentry{Angel}{Michael} + {Cloud 3a\\12345 Heaven's Realm} + {000\,01\,02\,04}{}{}{archangel}{MICHAEL} + \adrchar{K} + \adrentry{Kohm}{Markus} + {Freiherr-von-Drais-Stra\ss e 66\\68535 Edingen-Neckarhausen} + {+49~62\,03~1\,??\,??}{}{}{no angel at all} + {KOMA} +\end{lstlisting} + 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) + \put(0,57){\line(1,0){80}} + \put(0,3){\line(0,1){54}} + \put(80,3){\line(0,1){54}} + \thicklines + \put(10,42){\line(1,0){60}} + \put(70,45){\makebox(0,0)[r]{\textsf{\textbf{A}}}} + \put(10,23){\makebox(0,20)[l]{\parbox{5cm}{\raggedright + \textsc{Angel}, Gabriel\\\quad\small Cloud 3\\ + \quad 12345 Heaven's Realm\\ + \quad (archangel)}}} + \put(70,23){\makebox(0,20)[r]{\parbox{2cm}{\raggedright~\\ + \small~\\\textsc{gabriel}\\000\,01\,02\,03}}} + \put(10,4){\makebox(0,20)[l]{\parbox{5cm}{\raggedright + \textsc{Angel}, Michael\\\quad\small Cloud 3a\\ + \quad 12345 Heaven's Realm\\ + \quad (archangel)}}} + \put(70,4){\makebox(0,20)[r]{\parbox{2cm}{\raggedright~\\ + \small~\\\textsc{michael}\\000\,01\,02\,04}}} + \qbezier(0,3)(10,6)(40,3)\qbezier(40,3)(60,0)(80,3) + \end{picture} + \end{center} + 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} +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. Previous +versions only recognised the \DescRef{\LabelBase.cmd.adrentry} and +\Macro{adrchar} commands.% +% +\EndIndexGroup +% +\EndIndexGroup +% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrlttr2examples.dtx b/macros/latex/contrib/koma-script/source-doc/english/scrlttr2examples.dtx new file mode 100644 index 0000000000..18286886b3 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrlttr2examples.dtx @@ -0,0 +1,347 @@ +% \CheckSum{0} +% \iffalse +% ====================================================================== +% scrlttr2examples.dtx +% Copyright (c) Markus Kohm, 2008-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrlttr2examples.dtx +% Copyright (c) Markus Kohm, 2008-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Generation of letter example files for scrlttr2 chapter. +% +% --------------------------------------------------------------------------- +% +% Erzeugung der Brief-Beispiele für das scrlttr2-Kapitel. +% +% ============================================================================ +%<*ins> +\def\batchfile{scrlttr2examples.dtx} +\input docstrip.tex + +\keepsilent +\askforoverwritefalse + +\generate{% + \nopreamble\nopostamble + \file{musterlogo.eps}{\from{scrlttr2examples.dtx}{logo}}% +} + +\generate{% + \nopreamble\nopostamble + \file{ich.lco}{\from{scrlttr2examples.dtx}{lco,23,\languagename}}% +} + +\generate{% + \nopreamble\nopostamble + \file{letter-0.tex}{\from{scrlttr2examples.dtx}{example,0,\languagename}}% + \file{letter-1.tex}{\from{scrlttr2examples.dtx}{example,1,\languagename}}% + \file{letter-2.tex}{\from{scrlttr2examples.dtx}{example,2,\languagename}}% + \file{letter-3.tex}{\from{scrlttr2examples.dtx}{example,3,\languagename}}% + \file{letter-4.tex}{\from{scrlttr2examples.dtx}{example,4,\languagename}}% + \file{letter-5.tex}{\from{scrlttr2examples.dtx}{example,5,\languagename}}% + \file{letter-6.tex}{\from{scrlttr2examples.dtx}{example,6,\languagename}}% + \file{letter-7.tex}{\from{scrlttr2examples.dtx}{example,7,\languagename}}% + \file{letter-8.tex}{\from{scrlttr2examples.dtx}{example,8,\languagename}}% + \file{letter-9.tex}{\from{scrlttr2examples.dtx}{example,9,\languagename}}% + \file{letter-10.tex}{\from{scrlttr2examples.dtx}{example,10,\languagename}}% + \file{letter-11.tex}{\from{scrlttr2examples.dtx}{example,11,\languagename}}% + \file{letter-12.tex}{\from{scrlttr2examples.dtx}{example,12,\languagename}}% + \file{letter-13.tex}{\from{scrlttr2examples.dtx}{example,13,\languagename}}% + \file{letter-14.tex}{\from{scrlttr2examples.dtx}{example,14,\languagename}}% + \file{letter-15.tex}{\from{scrlttr2examples.dtx}{example,15,\languagename}}% + \file{letter-16.tex}{\from{scrlttr2examples.dtx}{example,16,\languagename}}% + \file{letter-17.tex}{\from{scrlttr2examples.dtx}{example,17,\languagename}}% + \file{letter-18.tex}{\from{scrlttr2examples.dtx}{example,18,\languagename}}% + \file{letter-19.tex}{\from{scrlttr2examples.dtx}{example,19,\languagename}}% + \file{letter-20.tex}{\from{scrlttr2examples.dtx}{example,20,\languagename}}% + \file{letter-21.tex}{\from{scrlttr2examples.dtx}{example,21,\languagename}}% + \file{letter-22.tex}{\from{scrlttr2examples.dtx}{example,22,\languagename}}% + \file{letter-23.tex}{\from{scrlttr2examples.dtx}{example,23,\languagename}}% + \file{letter-label.tex}{\from{scrlttr2examples.dtx}{% + example,label,\languagename}}% + \file{letter-nipponA.tex}{\from{scrlttr2examples.dtx}{% + example,22,nipponA,\languagename}}% + \file{letter-nipponB.tex}{\from{scrlttr2examples.dtx}{% + example,22,nipponB,\languagename}}% +} + +\csname endinput\endcsname +%</ins> +% +% \begin{macrocode} +%<*lco&23> +\ProvidesFile{ich.lco}[2008/06/11 lco +%<english> (Joe Public)] +%<ngerman> (Peter Musterfrau)] +\KOMAoptions{foldmarks=true,foldmarks=blmtP, + fromphone,fromemail,fromlogo,subject=titled} +%<*english> +\setkomavar{fromname}{Joe Public} +\setkomavar{signature}{Joe Public\\ + (former chairman)} +%</english> +%<*ngerman> +\setkomavar{fromname}{Peter Musterfrau} +\setkomavar{signature}{Peter Musterfrau\\ + (ehemaliger Vorsitzender)} +%</ngerman> +\renewcommand*{\raggedsignature}{\raggedright} +%<*english> +\setkomavar{fromaddress}{2 Valley\\ + SAMPLEBY\\ + ZY32 1XW} +%</english> +%<*ngerman> +\setkomavar{fromaddress}{Hinter dem Tal 2\\ + 54321 Musterheim} +%</ngerman> +\setkomavar{fromphone}{0\,12\,34~56\,78} +%<english>\setkomavar{fromemail}{joe@public.invalid} +%<ngerman>\setkomavar{fromemail}{Peter@Musterfrau.invalid} +\setkomavar{fromlogo}{% + \includegraphics{musterlogo}} +\setkomavar{location}{\raggedright +%<*english> + Club member no.~4711\\ + since 11.09.2001\\ + chairman 2003--2005} +\setkomavar{place}{Sampleby} +\setkomavar{frombank}{Bank of Friendly Greetings} +%</english> +%<*ngerman> + Mitglied Nr.~4711\\ + seit dem 11.09.2001\\ + Vorsitzender in den Jahren 2003--2005} +\setkomavar{place}{Musterheim} +\setkomavar{frombank}{Bank freundlichen Gru\ss es} +%</ngerman> +%</lco&23> +%<*example> +%<*label> +\AtBeginDocument{% + \usepackage{xcolor,eso-pic}% + \BeforeClosingMainAux{% + \AddToShipoutPicture*{% + \thinlines\color{gray!50}% + \AtPageLowerLeft{% + \put(0,\LenToUnit{8mm}){% + \line(0,1){\LenToUnit{180mm}}% + }% + \multiput(\LenToUnit{70mm},\LenToUnit{8mm})(\LenToUnit{70mm},0){3}{% + \line(0,1){\LenToUnit{216mm}}% + }% + \multiput(0,\LenToUnit{8mm})(0,\LenToUnit{36mm}){6}{% + \line(1,0){\LenToUnit{210mm}}% + }% + \put(\LenToUnit{70mm},\LenToUnit{224mm}){% + \line(1,0){\LenToUnit{140mm}}% + }% + }\color{black}% + }% + }% +} +%</label> +%<0|1|2|3|4|5>\documentclass[version=last]{scrlttr2} +%<6>\documentclass[version=last,fontsize=14pt]{scrlttr2} +%<!0&!1&!2&!3&!4&!5&!6&!23&!label&!nipponA&!nipponB>\documentclass[foldmarks=true,foldmarks=blmtP, +%<nipponA|nipponB>\documentclass[foldmarks=true,locfield=wide, +%<8> fromalign=false, +%<9> fromalign=center, +%<10> fromalign=false,fromrule=aftername, +%<11> fromalign=center,fromrule=aftername, +%<12> fromalign=false,fromrule=afteraddress, +%<13|17> fromalign=center,fromrule=afteraddress, +%<14|16> fromrule=afteraddress, +%<15|18> fromalign=right,fromrule=afteraddress, +%<12|13|14|15> fromphone,fromemail, +%<16|17|18|19|20|21|22> fromphone,fromemail,fromlogo, +%<nipponA|nipponB> fromphone=false,fromemail=false, +%<21|22> subject=titled, +%<!0&!1&!2&!3&!4&!5&!6&!23&!label> version=last]{scrlttr2} +%<23>\documentclass[version=last,ich]{scrlttr2} +%<nipponA>\LoadLetterOption{NipponLL} +%<nipponB>\LoadLetterOption{NipponEL} +%<label>\documentclass[version=last,ich,settleford600label]{scrlttr2} +%<ngerman>\usepackage[ngerman]{babel} +%<english>\usepackage[british]{babel} +%<16|17|18|19|20|21|22|23|label>\usepackage{graphics} +\begin{document} +%<*!0&!1&!2&!3&!4&!5&!6&!7&!23&!label> +%<english>\setkomavar{fromname}{Joe Public} +%<ngerman>\setkomavar{fromname}{Peter Musterfrau} +%<*22> +%<*english> +\setkomavar{signature}{Joe Public\\ + (former chairman)} +%</english> +%<*ngerman> +\setkomavar{signature}{Peter Musterfrau\\ + (ehemaliger Vorsitzender)} +%</ngerman> +\renewcommand*{\raggedsignature}{\raggedright} +%</22> +%<*english> +\setkomavar{fromaddress}{2 Valley\\ + SAMPLEBY\\ + ZY32 1XW} +%</english> +%<*ngerman> +\setkomavar{fromaddress}{Hinter dem Tal 2\\ + 54321 Musterheim} +%</ngerman> +%<*!9&!10&!11> +\setkomavar{fromphone}{0\,12\,34~56\,78} +%<english>\setkomavar{fromemail}{joe@public.invalid} +%<ngerman>\setkomavar{fromemail}{Peter@Musterfrau.invalid} +%<*!12&!13&!14&!15> +\setkomavar{fromlogo}{\includegraphics{musterlogo}} +%</!12&!13&!14&!15> +%</!9&!10&!11> +%</!0&!1&!2&!3&!4&!5&!6&!7&!23&!label> +%<*19|20|21|22|23|label> +%<*!23&!label&!nipponA&!nipponB> +\setkomavar{location}{\raggedright +%<*english> + Club member no.~4711\\ + since 11.09.2001\\ + chairman 2003--2005} +%</english> +%<*ngerman> + Mitglied Nr.~4711\\ + seit dem 11.09.2001\\ + Vorsitzender in den Jahren 2003--2005} +%</ngerman> +%</!23&!label&!nipponA&!nipponB> +%<*20|21|22|23|label> +%<english>\setkomavar{date}{29th February 2011} +%<ngerman>\setkomavar{date}{29. Februar 2011} +%<*!23&!label> +%<english>\setkomavar{place}{Sampleby} +%<ngerman>\setkomavar{place}{Musterheim} +%</!23&!label> +%<*21|22|23|label> +%<english>\setkomavar{subject}{Missing general meeting} +%<ngerman>\setkomavar{subject}{Mitgliederversammlung vermisst} +%</21|22|23|label> +%</20|21|22|23|label> +%</19|20|21|22|23|label> +%<!5>\begin{letter}{% +%<5>\begin{letter}[fontsize=14pt]{% +%<*english> + Joanna Public\\ + 1 Hillside\\ + SAMPLESTEAD\\ + WX12 3YZ% +%</english> +%<*ngerman> + Petra Mustermann\\ + Vor dem Berg 1\\ + 12345 Musterhausen% +%</ngerman> + } +%<label>\savelabel{3}{2} +%<english>\opening{Dear Madam Chair,} +%<ngerman>\opening{Liebe Vereinsvorsitzende,} +%<*!0> +%<*english> +The last general meeting was more than a year ago. +I would like to remind you that the articles of our +club stipulate that one should be held every +six months. For this reason, I call on the executive +board to arrange such a meeting immediately. +\closing{Anticipating an invitation} +%</english> +%<*ngerman> +seit einem Jahr gab es keine Mitgliederversammlung +mehr. Ich erinnere daran, dass unsere Satzung eine +solche jedes halbe Jahr vorsieht. Ich fordere den +Vorstand daher auf, umgehend eine solche in +Angriff zu nehmen. +\closing{In Erwartung einer Einladung} +%</ngerman> +%<*!1> +%<*english> +\ps PS: I hope you do not take this request amiss. +%</english> +%<*ngerman> +\ps PS: Ich hoffe, Du nimmst mir das nicht krumm. +%</ngerman> +%<*!2> +%<*!3> +%<*english> +\setkomavar*{enclseparator}{Enclosure} +\encl{Excerpt from the articles governing general + meetings} +%</english> +%<*ngerman> +\setkomavar*{enclseparator}{Anlage} +\encl{Auszug aus der Satzung, in dem die + Mitgliederversammlungen geregelt sind} +%</ngerman> +%</!3> +%<*english> +\cc{executive board\\all members} +%</english> +%<*ngerman> +\cc{Die Vereinsvorsitzende\\Alle Mitglieder} +%</ngerman> +%</!2> +%</!1> +%</!0> +\end{letter} +\end{document} +%</example> +%<*logo> +%%! +%%BoundingBox: 0 0 72 72 +0 0 moveto +72 72 rlineto +72 neg 0 rlineto +72 72 neg rlineto +stroke +0 0 moveto +/Bitstream-Charter findfont +72 scalefont +setfont +(M) show +showpage +%</logo> +% \end{macrocode} +% +% \iffalse +\endinput +%%% Local Variables: +%%% mode: doctex +%%% TeX-master: t +%%% End: +% \fi diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrwfile.tex b/macros/latex/contrib/koma-script/source-doc/english/scrwfile.tex new file mode 100644 index 0000000000..78253e34e0 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/scrwfile.tex @@ -0,0 +1,288 @@ +% ====================================================================== +% scrwfile.tex +% Copyright (c) Markus Kohm, 2010-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrwfile.tex +% Copyright (c) Markus Kohm, 2010-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrwfile of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber scrwfile in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrwfile.tex}% + [$Date: 2018-03-27 11:46:14 +0200 (Tue, 27 Mar 2018) $ + KOMA-Script guide (chapter: scrwfile)] + +% Date of the translated German file: 2018-02-15 + +\translator{Markus Kohm\and Jana Schubert\and Karl Hagen} + +\chapter{Economising and Replacing Files with \Package{scrwfile}} +\labelbase{scrwfile} +\BeginIndexGroup +\BeginIndex{Package}{scrwfile} + +One of the problems not solved by the introduction of \eTeX{} is the fact that +\TeX{} can support only 18 open write handles. This number seems quite large +at first, but many of these handles are already reserved. \TeX{} itself uses +handle 0 for the log file. \LaTeX{} needs handle 1 for \Macro{@mainaux}, +handle 2 for \Macro{@partaux}, one handle for \Macro{tableofcontents}, one +handle for \Macro{listoffigures}, one handle for \Macro{listoftables}, and one +handle for \Macro{makeindex}. Every other such list generates another handle, +and packages like \Package{hyperref} or \Package{minitoc} require write +handles too. + +The bottom line is that eventually you may get the following error message: +\begin{lstcode} + ! No room for a new \write . + \ch@ck ...\else \errmessage {No room for a new #3} + \fi +\end{lstcode} + +For some time, the simplest solution to this problem has been to use +\mbox{Lua\LaTeX} instead of \mbox{pdf\LaTeX} or \XeLaTeX. This eliminates the +restriction, and the maximum number of files you can have open for writing is +then limited only by the operating system. In reality, you usually so not need +to worry about it any more. + +The fact that \LaTeX{} always opens a new file for writing every table of +contents, list of figures, list of tables, etc. has another disadvantage. Such +lists are not only output by their respective commands, they also could not be +output a second time because the associated auxiliary file\footnote{The term + \emph{auxiliary file} here refers not to the main \File{aux} file but to the + other internal files used indirectly via the \File{aux} file, e.\,g. the + \File{toc} file, the \File{lof} file, or the \File{lot} file.} is empty +after the respective command until the end of the document. + +The \Package{scrwfile} package makes a fundamental change to the \LaTeX{} +kernel, which can solve both problems not only for \mbox{Lua\LaTeX} but also +for \mbox{pdf\LaTeX} or \XeLaTeX. + +\section{Fundamental Changes to the \LaTeX{} Kernel} +\seclabel{kernelpatches} + +\LaTeX{} classes use the \LaTeX{} kernel command +\Macro{@starttoc}\IndexCmd{@starttoc} to allocate a new file handle, such as +for \Macro{tableofcontents} or \Macro{listoffigures}. This command not only +loads the associated auxiliary file but also reopens it for writing. If +entries to these lists are added using \Macro{addcontentsline}, however, the +system does not write directly to these auxiliary files. Instead, \LaTeX{} +writes \Macro{@writefile}\IndexCmd{@writefile} commands to the \File{aux} +file. Only while reading the \File{aux} file at the end of the document do +those \Macro{@writefile} commands become actual write operations in the +auxiliary files. Additionally, \LaTeX{} does not close the auxiliary files +explicitly. Instead it relies on \TeX{} to close all open files at the end. + +This procedure ensures that the auxiliary files are only written to within +\Macro{end}\PParameter{document}, but they remain open throughout the entire +\LaTeX{} run. \Package{scrwfile} takes is starting point here, by redefining +\Macro{@starttoc} and \Macro{@writefile}. + +Of course\textnote{Attention!} changes to the \LaTeX{} kernel always have the +potential to cause incompatibilities with other packages. Those primarily +affected may be those which also redefine \Macro{@starttoc} or +\Macro{@writefile}. In some cases, it may help to change the order the +packages are loaded. If you encounter such a problem, please contact the +\KOMAScript{} author. + +\section{The Single-File Method} +\seclabel{singlefilefeature} + +As soon as the package is loaded with +\begin{lstcode} + \usepackage{scrwfile} +\end{lstcode} +\Package{scrwfile} redefines \Macro{@starttoc}\IndexCmd{@starttoc} so that it +no longer allocates a write handle or opens a file for writing. +\Macro{@writefile} is redefined so that immediately before closing the +\File{aux} file in \Macro{end}\PParameter{document}, it writes not to the +usual auxiliary files but to a single new file with extension \File{wrt}. +After reading the \File{aux} file, this \File{wrt} file will be processed once +for each of the auxiliary files that \Macro{@writefile} writes information to. +However these auxiliary files do not all have to be open at the same time. +Instead, only one is open at a time and is explicitly closed afterwards. Since +\LaTeX{} reuses an internal write file, \Package{scrwfile} doesn't need its +own write handle for this type of table of contents or list of floating +environments. + +Because of this behaviour, even if you have only one table of contents, once +you load \Package{scrwfile} you will have access to a write file handle for +bibliographies, indexes, glossaries, and similar lists that do not use +\Macro{@starttoc}. Additionally, you can create any number of tables of +contents and other lists that use \Macro{@starttoc}\IndexCmd{@starttoc}. + +\section{The File Cloning Method} +\seclabel{clonefilefeature} + +Since \Macro{@writefile}\IndexCmd{@writefile} has already been modified for +the single-file method described in the previous system so that it no longer +writes directly to the corresponding auxiliary file, a further possibility +suggests itself. When copying the \Macro{@writefile} statements into the +\File{wrt} file, you can also copy them to other destinations. + +\begin{Declaration} + \Macro{TOCclone}% + \OParameter{list heading}\Parameter{source extension}% + \Parameter{destination extension} +\end{Declaration} +This cloning of file entries copies entire tables of contents or other lists. +For this, you only need to specify the extension of the auxiliary file whose +entries should be copied and the extension of a destination file. The entries +are then copied there. Of course, you can also write additional entries to +this cloned file. + +You can manage the \PName{destination extention} using +\hyperref[cha:tocbasic]{\Package{tocbasic}}% +\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}} (see +\autoref{cha:tocbasic}). If such a file is already under the control of +\hyperref[cha:tocbasic]{\Package{tocbasic}}, a warning will be issued. +Otherwise, a new list for this extension will be created using +\hyperref[cha:tocbasic]{\Package{tocbasic}}. You can set the heading for this +list with the optional argument \PName{list heading}. + +You can then output this new content list, for example, with the command +\Macro{listof\PName{destination extension}}. The content-list +attributes\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}} +\PValue{leveldown}, \PValue{numbered}, \PValue{onecolumn}, and \PValue{totoc} +(see \DescRef{tocbasic.cmd.setuptoc} in \autoref{sec:tocbasic.toc}, +\DescPageRef{tocbasic.cmd.setuptoc}) are automatically copied to the +destination list if they were already set in the source list. The +\PValue{nobabel} attribute is always set for cloned content lists, because the +language-selection commands in the source content list are already copied +anyway. + +\begin{Example} + Suppose you want a short table of contents with only the chapter level in + addition to the normal the table of contents: +\begin{lstcode} + \usepackage{scrwfile} + \TOCclone[Summary Contents]{toc}{stoc} +\end{lstcode} + This creates a new table of contents with the heading ``Summary Contents''. + The new table of contents uses an auxiliary file with the extension + \File{stoc}. All entries to the auxiliary file with extension \File{toc} + will also be copied to this new auxiliary file. + + In order to have the new short table of contents display only the chapter + entries, we use: +\begin{lstcode} + \addtocontents{stoc}{\protect\value{tocdepth}=0} +\end{lstcode} + Although\textnote{Attention!} normally you cannot write to an auxiliary file + before \Macro{begin}\PParameter{document}, the code above works in the + preamble after loading \Package{scrwfile}. Owing to the unconventional way + of changing the \DescRef{maincls.counter.tocdepth} counter within the TOC + file, this change only applies to this content list. + + Later in the document, we then output the content list with the file + extension \File{stoc} with: +\begin{lstcode}[moretexcs={listofsttoc}] + \listofstoc +\end{lstcode} + and this shows only the parts and chapters of the document. + + Things become a bit more difficult if the summary contents are to be + listed in the table of contents. This would seem to be possible with +\begin{lstcode} + \addtocontents{toc}{% + \protect\addxcontentsline + {stoc}{chapter}{\protect\contentsname}% + } +\end{lstcode} +However, since all entries in \File{toc} are also copied to \File{stoc}, this +entry would also be copied from the summary contents. So we cannot generate +the entry from the content list. Because we use the +\Package{tocbasic}\important{\Package{tocbasic}} package, we can use the +following: +\phantomsection\xmpllabel{cmd.BeforeStartingTOC} +\begin{lstcode} + \BeforeStartingTOC[toc]{% + \addcontentslinedefault{stoc}{chapter} + {\protect\contentsname}% + } +\end{lstcode} +Of course, this assumes that the \File{toc} file is under the control +of the \Package{tocbasic} package, which is indeed the case for all +\KOMAScript{} classes. See \autoref{sec:tocbasic.toc} on +\DescPageRef{tocbasic.cmd.BeforeStartingTOC} for more information about +\DescRef{tocbasic.cmd.BeforeStartingTOC}.% +\end{Example} +Incidentally, the \DescRef{tocbasic.cmd.addxcontentsline} command used in the +examples is also documented in \autoref{cha:tocbasic}, +\DescPageRef{tocbasic.cmd.addxcontentsline}.% +\EndIndexGroup + + +\section{Note on the State of Development} +\seclabel{draft} + +Although this package has already been tested by many users and is often in +production use, its development is still ongoing. Therefore, it is +theoretically possible that there might be changes, especially to the internal +functionality. It is likely that the package will be extended in the future. +Some code for such extensions is already in the package. However, as there are +no user commands that make use of these features, they are currently +undocumented. + +\section{Known Package Incompatibilities} +\seclabel{incompatible} + +As mentioned in \autoref{sec:scrwfile.kernelpatches}, \Package{scrwfile} +redefines some commands of the \LaTeX{} kernel. This happens not only while +loading the package, but indeed at various times while the document is +processed, for example just before reading the \File{aux} file. +This\textnote{Attention!} results in incompatibility with packages that also +redefine these commands at run time. + +The \Package{titletoc}\important{Package{titletoc}}\IndexPackage{titletoc} +package is an example for such an incompatibility. That package redefines +\Macro{@writefile} under some conditions at run time. If you use both +\Package{scrwfile} and \Package{titletoc}, there is no warranty for the +correct behaviour of either one. This is neither an error of +\Package{titletoc} nor of \Package{scrwfile}.% +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/tocbasic.tex b/macros/latex/contrib/koma-script/source-doc/english/tocbasic.tex new file mode 100644 index 0000000000..36681ff609 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/tocbasic.tex @@ -0,0 +1,2439 @@ +% ====================================================================== +% tocbasic.tex +% Copyright (c) Markus Kohm, 2002-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% tocbasic.tex +% 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. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Package tocbasic for Package and Class Authors +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Paket tocbasic fuer Paket- und Klassenautoren +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{tocbasic.tex} + [$Date: 2018-08-31 09:11:20 +0200 (Fri, 31 Aug 2018) $ + KOMA-Script guide (package tocbasic)] + +% Date of the translated German file: 2018-08-31 + +\translator{Markus Kohm\and Arndt Schubert\and Karl Hagen} + +\chapter{Managing Content Lists with \Package{tocbasic}} +\labelbase{tocbasic} +\BeginIndexGroup% +\BeginIndex{Package}{tocbasic}% +\BeginIndex{}{table of contents}% +\BeginIndex{}{content list}% +\BeginIndex{}{file>extension}% +The main purpose of the \Package{tocbasic} package is to give authors of +packages and classes the ability to create their own tables or lists of +content, content lists for short, similar to the list of figures and the list +of tables, allowing classes and other packages some control over these lists. +The \Package{tocbasic} package also delegates control of the +language-dependent parts of these content lists to the +\Package{babel}\IndexPackage{babel} package (see \cite{package:babel}). Using +\Package{tocbasic} relieves package and class authors from the burden of +implementing such features themselves. + +As a minor side effect, the package can also be used to define new floating +environments, or floating environments like non-floating environments for +reference objects. For more details, after you read about the basic commands +in the next four sections, see the example in \autoref{sec:tocbasic.example}, +which is compactly summarized in \autoref{sec:tocbasic.declarenewtoc}. + +\KOMAScript{} itself uses \Package{tocbasic} not only for the table of +contents but also for the already mentioned lists of figures and tables. + +\section{Basic Commands} +\label{sec:tocbasic.basics} + +The basic commands are primarily used to handle a list of all known file +extensions\textnote{file extension, content lists} that +represent a table or list of contents. We call these auxiliary +files\Index{auxiliary file}\footnote{The term \emph{auxiliary file} here + refers not to the main \File{aux} file but to the other internal files used + indirectly via the \File{aux} file, e.\,g. the \File{toc} file, the + \File{lof} file, or the \File{lot} file.} TOC files\textnote{TOC + file}\Index[indexmain]{TOC file} regardless of the file extension that is +actually used. Entries to such files are typically written using +\Macro{addtocontents}\important{\Macro{addtocontents}, +\DescRef{\LabelBase.cmd.addxcontentsline}}, or +\DescRef{\LabelBase.cmd.addxcontentsline}. There are also commands to perform +actions on all of these file extensions. Additionally, there are commands to +set or unset features for the file associated with a given extension. +Typically an file extension also has an owner\textnote{file owner}. This owner +may be a class or package, or an identifier that the author of the class or +package using \Package{tocbasic} has chosen independently. For example, +\KOMAScript{} uses the owner \texttt{float} for the \File{lof} and \File{lot} +file extensions that are associated with the list of figures and list of +tables, respectively. For the table of contents, \KOMAScript{} uses the file +name of the class. + +\begin{Declaration} + \Macro{ifattoclist}\Parameter{extension}\Parameter{then code}% + \Parameter{else code} +\end{Declaration} +This command tests whether or not the \PName{extension} already exists in the +list of known file extensions. If the \PName{extension} is already known, the +\PName{then code} will be executed. Otherwise, the \PName{else code} will be +executed. +\begin{Example} + Suppose you want to know if the file name extension ``\File{foo}'' is + already in use in order to report an error because it cannot be used: +\begin{lstcode} + \ifattoclist{foo}{% + \PackageError{bar}{% + extension `foo' already in use% + }{% + Each extension may be used only + once.\MessageBreak + The class or another package already + uses extension `foo'.\MessageBreak + This error is fatal!\MessageBreak + You should not continue!}% + }{% + \PackageInfo{bar}{using extension `foo'}% + } +\end{lstcode} +\end{Example} +\EndIndexGroup + + +\begin{Declaration} + \Macro{addtotoclist}\OParameter{owner}\Parameter{extension} +\end{Declaration} +This command adds the \PName{extension} to the list of known extensions. But +if the \PName{extension} is known already, an error is reported to prevent +duplicate use of the same \PName{extension}. + +If you specify the optional \OParameter{owner} argument, the given +\PName{owner} for this file extension is also saved. If you omit the optional +argument, \Package{tocbasic} tries to determine the file name of the class or +package currently being processed and saves it as the owner. +This\textnote{Attention!} procedure only works if you call +\Macro{addtotoclist} while loading a class or package. It will fail if a user +calls \Macro{addtotoclist} afterwards. In this case, the owner is set to +``\PValue{.}''. + +Note\textnote{Attention!} that passing an empty \PName{owner} argument is not +the same as completely omitting the optional argument, including the square +brackets. An empty argument would also result in an empty owner. +\begin{Example} + Suppose you want to add the extension ``\File{foo}'' to the list of known + file extensions while loading your package with the file name + ``\File{bar.sty}'': +\begin{lstcode} + \addtotoclist{foo} +\end{lstcode}% + This will add the extension ``\PValue{foo}'' with the owner + ``\PValue{bar.sty}'' to the list of known extensions if this extension was + not already in the list. If the class or another package has already added + the extension, you will get the error: +\begin{lstoutput} + Package tocbasic Error: file extension `foo' cannot be used twice + + See the tocbasic package documentation for explanation. + Type H <return> for immediate help. +\end{lstoutput} + If you press the ``\texttt{h}'' key followed by return, you will get the + following help: +\begin{lstoutput} + File extension `foo' is already used by a toc-file, while bar.sty + tried to use it again for a toc-file. + This may be either an incompatibility of packages, an error at a package, + or a mistake by the user. +\end{lstoutput} + + Perhaps your package also provides a command that dynamically generates a + content list. In this case, you should use the optional argument of + \Macro{addtotoclist} to specify the owner. +\begin{lstcode} + \newcommand*{\createnewlistofsomething}[1]{% + \addtotoclist[bar.sty]{#1}% + % Do something more to make this content list available + } +\end{lstcode} + Now if the user calls this command, for example with +\begin{lstcode} + \createnewlistofsomething{foo} +\end{lstcode} + this will add the extension ``\PValue{foo}'' with the owner + ``\PValue{bar.sty}'' to the list of known extension or report an error, if + the extension is already in use. +\end{Example} +You can specify any \PName{owner} you want, but it must be unique. For +example, if you were the author of the \Package{float} package, you could +specify ``\PValue{float}'' instead of ``\PValue{float.sty}'' as the +\PName{owner}. In this case, the \KOMAScript{} +options\important{\DescRef{maincls.option.listof}}% +\IndexOption{listof~=\PName{setting}} for the list of figures and the list of +tables would also affect your content lists because these lists are already +added to the list of known file extensions at the time the option is set, and +\KOMAScript{} associates the file extensions ``\PValue{lof}'' for the list of +figures and ``\PValue{lot}'' for the list of tables with the owner +``\PValue{float}'' and sets the options for this owner. + +By the way, the \hyperref[cha:scrhack]{\Package{scrhack}}% +\IndexPackage{scrhack}\important{\hyperref[cha:scrhack]{\Package{scrhack}}} +package contains patches for several packages, such as \Package{float} or +\Package{listings}, which provide their own content lists. If you use +\hyperref[cha:scrhack]{\Package{scrhack}}, among other things, the respective +file extensions will be added to the list of known file extensions. Their +\PName{owner} is also ``\PValue{float}''. This is the basic building block, so +to speak, allowing you to use the features of \Package{tocbasic} and the +\KOMAScript{} classes with these content lists as well.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{AtAddToTocList}\OParameter{owner}\Parameter{commands} +\end{Declaration} +This command adds the \PName{commands} to an internal list of commands that +will be processed whenever a file extension with the specified \PName{owner} +is added to the list of known extensions with +\DescRef{\LabelBase.cmd.addtotoclist}. The optional argument is handled in the +same way as in the \DescRef{\LabelBase.cmd.addtotoclist} command. If you leave +the optional argument blank, the commands will always be executed, regardless +of the owner, every time a new file extension is added to the list of known +file extensions. Furthermore, while processing the \PValue{commands}, +\Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} is set to the +extension of the extension currently being added. +\begin{Example} + \Package{tocbasic} itself uses +\begin{lstcode} + \AtAddToTocList[]{% + \expandafter\tocbasic@extend@babel + \expandafter{\@currext}% + } +\end{lstcode} + to add every file extension to the existing \Package{tocbasic} integration + with the \Package{babel} package. +\end{Example} + +The two \Macro{expandafter} commands in the example are needed because the +argument of \DescRef{\LabelBase.cmd.tocbasic@extend@babel} has to be expanded. +See the description of \DescRef{\LabelBase.cmd.tocbasic@extend@babel} in +\autoref{sec:tocbasic.internals}, +\DescPageRef{\LabelBase.cmd.tocbasic@extend@babel} for more information.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{removefromtoclist}\OParameter{owner}\Parameter{extension} +\end{Declaration} +This command removes the \PName{extension} from the list of known extensions. +If the optional argument, \OParameter{owner}, is given, the \PName{extension} +will only be removed if it was added by this \PName{owner}. See +\DescRef{\LabelBase.cmd.addtotoclist} for an explanation of how the list owner +is determined if the optional argument is omitted. If you specify an empty +\PName{owner}, the owner is not tested and the \PName{extension} is removed +regardless of the owner.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{doforeachtocfile}\OParameter{owner}\Parameter{commands} +\end{Declaration} +To this point, we've introduced commands provide additional security for class +and package authors, but also more overhead. With \Macro{doforeachtocfile}, +you can reap the first benefit for this. This command lets you execute the +specified \PName{commands} for each file extension associated with an +\PName{owner}. While processing the \PName{commands}, \Macro{@currext} is the +extension of the current file. If you omit the optional \OParameter{owner} +argument, all file extensions are processed regardless of the owner. If the +optional argument is empty, on the other hand, only extensions with an empty +owner will be processed. +\begin{Example} + If you want to output a list of all known file extensions to the terminal + and to the \File{log} file, you can easily accomplish this: +\begin{lstcode} + \doforeachtocfile{\typeout{\@currext}} +\end{lstcode} + If, on the other hand, you only want to output the extensions owned by + ``\PValue{foo}'', this too is easy: +\begin{lstcode} + \doforeachtocfile[foo]{\typeout{\@currext}} +\end{lstcode} +\end{Example} +The \KOMAScript{} classes \Class{scrbook} and \Class{scrreprt} use this +command to optionally put a vertical skip or the chapter heading in content +lists using the \PValue{chapteratlist} feature. You can learn how to set this +feature in \autoref{sec:tocbasic.toc} on +\DescPageRef{\LabelBase.cmd.setuptoc}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{tocbasicautomode} +\end{Declaration} +This command redefines \LaTeX{} kernel macro \Macro{@starttoc} for class and +package authors so that every time \Macro{@starttoc} is called, the specified +file extension is added to the list of known extensions, if it has not already +been added. It also uses \DescRef{\LabelBase.cmd.tocbasic@starttoc} instead of +\Macro{@starttoc}. See \autoref{sec:tocbasic.internals}, +\DescPageRef{\LabelBase.cmd.tocbasic@starttoc} for more information about +\DescRef{\LabelBase.cmd.tocbasic@starttoc} and \Macro{@starttoc}. + +After you use \Macro{tocbasicautomode}, every content list created with +\Macro{@starttoc} is automatically put under the control of +\Package{tocbasic}. Whether or not this leads to the desired result, however, +depends very much on the individual content list. The \Package{babel} package +extensions, at least, will work for all those content lists. Nevertheless, it +is preferable for the class or package authors to use \Package{tocbasic} +explicitly. That way they can also take advantage of the other features of +\Package{tocbasic}, which are described in the following sections.% +\EndIndexGroup + + +\section{Creating a Content List} +\label{sec:tocbasic.toc} + +In the previous section, you learned how to maintain a list of known file +extensions and how to automatically execute commands when adding new +extensions to this list. You also saw a command that can be used to execute +instructions for all known extensions or all extensions belonging to one +owner. In this section, you will learn commands that apply to the files +associated with these file extensions. + +\begin{Declaration} + \Macro{addtoeachtocfile}\OParameter{owner}\Parameter{content} +\end{Declaration} +The \Macro{addtoeachtocfile} command uses the \LaTeX{} kernel command +\Macro{addtocontents} to write the \PName{content} to every TOC file\Index{TOC +file} in the list of known file extensions that has the specified +\PName{owner}. If you omit the optional argument, the \PName{content} is +written to each file in the list of known file extensions. Incidentally, the +actual file name is constructed from \Macro{jobname} and the file extension. +While writing the \PName{content}, +\Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} is the +extension of the file currently being processed. +\begin{Example} + You want to add a vertical space of one line to all TOC files. +\begin{lstcode} + \addtoeachtocfile{% + \protect\addvspace{\protect\baselineskip}% + } +\end{lstcode} + If, on the other hand, you want to do this only for the files that have the + owner ``\PValue{foo}'', use: +\begin{lstcode} + \addtoeachtocfile[foo]{% + \protect\addvspace{\protect\baselineskip}% + } +\end{lstcode} +\end{Example} +You should protect commands that should not be expanded when they are written +by prefixing them with \Macro{protect}, in the same way as you would in +\Macro{addtocontents}. +\EndIndexGroup + + +\begin{Declaration} + \Macro{addxcontentsline}% + \Parameter{extension}\Parameter{level}\OParameter{section number}% + \Parameter{text} +\end{Declaration} +This command is very similar to +\Macro{addcontentsline}\IndexCmd{addcontentsline} from the \LaTeX{} kernel. +However, it has an additional optional argument for the \PName{section number} +of the entry, whereas for \Macro{addcontentsline}, it is specified in the +\PName{text} argument. It is used to include numbered or unnumbered entries in +the content list specified by the file \PName{extension}, where \PName{level} +is the sectioning level and \PName{text} is the content of the corresponding +entry. The page number is determined automatically. + +In contrast to \Macro{addcontentsline}, \Macro{addxcontentsline} first tests +whether the \Macro{add\PName{level}\PName{extension}entry} command is defined. +If so, it will be used for the entry, passing the \PName{section number} as an +optional argument and \PName{text} as a mandatory argument. You can find an +example of such a command provided by the \KOMAScript{} classes in +\DescRef{maincls-experts.cmd.addparttocentry} (see +\autoref{sec:maincls-experts.experts}, +\DescPageRef{maincls-experts.cmd.addparttocentry}). If the corresponding +command is undefined, the internal command +\DescRef{\LabelBase.cmd.tocbasic@addxcontentsline} is used instead. This takes +all four arguments as mandatory arguments and then uses +\Macro{addcontentsline} to create the desired entry. You can find more about +\DescRef{\LabelBase.cmd.tocbasic@addxcontentsline} in +\autoref{sec:tocbasic.internals}, +\DescPageRef{\LabelBase.cmd.tocbasic@addxcontentsline}. + +One advantage of using \Macro{addxcontentsline} rather than +\Macro{addcontentsline} is that the \PValue{numberline} feature is respected +(see \DescPageRef{\LabelBase.cmd.setuptoc}). Furthermore, you can configure +the form of the entries by defining the appropriate commands specific to the +\PName{level} and file \PName{extension}.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{addxcontentslinetoeachtocfile}\OParameter{owner} + \Parameter{level} + \OParameter{section number}% + \Parameter{text} + \Macro{addcontentslinetoeachtocfile}\OParameter{owner} + \Parameter{level}\Parameter{text}% +\end{Declaration} +These two commands are directly related to +\DescRef{\LabelBase.cmd.addxcontentsline}\ChangedAt{v3.12}{\Package{tocbasic}} +explained above, or to \Macro{addcontentsline} from the \LaTeX kernel. The +difference is that these statements write \PName{text} not just to a single +file but to all the files of a given \PName{owner} and, if the first optional +argument is omitted, to all files in the list of known file extensions. +\begin{Example} + Suppose you are a class author and you want to write the chapter entry not + just in the table of contents but in all content-list files. Suppose further + that \PValue{\#1} currently contains the text to be written. +\begin{lstcode} + \addxcontentslinetoeachtocfile{chapter}% + [\thechapter]{#1} +\end{lstcode} + In this case, of course, the current chapter number should be expanded + directly when writing to the TOC file, which is why it was not protected + from expansion with \Macro{protect}. +\end{Example} +While writing the \PName{content}, +\Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} here is also +the extension of the file being written to, as it is with +\DescRef{\LabelBase.cmd.addtoeachtocfile}.% + +Whenever\ChangedAt{v3.12}{\Package{tocbasic}} possible, the +\Macro{addxcontentslinetoeachtocfile} command is preferable to +\Macro{addcontentslinetoeachtocfile} because only the former offers the +enhancements of \DescRef{\LabelBase.cmd.addxcontentsline}. You can find more +about these enhancements and benefits in the explanation of +\DescRef{\LabelBase.cmd.addxcontentsline} above.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{listoftoc}\OParameter{list-of title}\Parameter{extension}% + \Macro{listoftoc*}\Parameter{extension}% + \Macro{listofeachtoc}\OParameter{owner}% + \Macro{listof\PName{extension}name} +\end{Declaration} +You can use these commands to print the content lists. +The\important{\Macro{listoftoc*}} stared version \Macro{listoftoc*} needs only +one argument, the \PName{extension} of the file. The command first initializes +the vertical and horizontal spacing of paragraphs, calls the hook to execute +commands before reading the file, then reads the file, and finally executes +the hook to execute commands after reading the file. Thus you can think of +\Macro{listoftoc*} as a direct replacement for the \LaTeX{} kernel macro +\Macro{@starttoc}\IndexCmd{@starttoc}\important{\Macro{@starttoc}}. + +The\important{\Macro{listoftoc}} version of \Macro{listoftoc} without the star +prints the complete content list and also creates an optional entry in the +table of contents and the running heads. If you provide the optional +\OParameter{list-of title} argument, it is used both as the title for the list +and as an optional entry in the table of contents and the running head. +If\textnote{Attention!} the \OParameter{list-of title} argument is empty, the +title will be empty too. If, on the other hand, you completely omit the +optional argument, including the square brackets, the +\Macro{listof\PName{extension}name} command will be used if it is defined. If +it is undefined, a default replacement name is used and a warning is issued. + +The\important{\Macro{listofeachtoc}} \Macro{listofeachtoc} command outputs all +content lists associated with the given \PName{owner}, or of all known file +extensions if the optional argument is omitted. To\textnote{Attention!} output +the correct titles, \Macro{listof\PName{extension}name} should be defined. + +You\textnote{Hint!} should define \Macro{listof\PName{extension}name} +appropriately for all file extensions because users may use \Macro{listoftoc} +without the optional argument, or \Macro{listofeachtoc}, themselves. +\begin{Example} + Suppose you have a new ``list of algorithms'' with the file extension + \PValue{loa} and want to output it. The command +\begin{lstcode} + \listoftoc[List of Algorithms]{loa} +\end{lstcode} + will do it for you. If, however, you want to output this list without a + title, you could use +\begin{lstcode} + \listof*{loa} +\end{lstcode} + In the second case, of course, there will be no entry in the table of + contents. For more information about creating entries in the table of + contents, see the \DescRef{\LabelBase.cmd.setuptoc} command on + \DescPageRef{\LabelBase.cmd.setuptoc}. + + If you have defined +\begin{lstcode} + \newcommand*{\listofloaname}{% + List of Algorithms% + } +\end{lstcode} + already, then +\begin{lstcode} + \listoftoc{loa} +\end{lstcode} + will suffice to print the content list with the desired heading. It may be + easier for users to remember if you also define a simple list-of command: +\begin{lstcode} + \newcommand*{\listofalgorithms}{\listoftoc{loa}} +\end{lstcode} +\end{Example} + +Because\textnote{Attention!} \LaTeX{} normally opens a new file for each of +these content lists, calling each of these commands may +result in an error like: +\begin{lstoutput} + ! No room for a new \write . + \ch@ck ...\else \errmessage {No room for a new #3} + \fi +\end{lstoutput} +if there are no more write handles left. Loading the +\Package{scrwfile}\important{\Package{scrwfile}}\IndexPackage{scrwfile} +package (see \autoref{cha:scrwfile}) can solve this problem. + +Also, the \hyperref[cha:scrhack]{\Package{scrhack}}\IndexPackage{scrhack}% +\important{\hyperref[cha:scrhack]{\Package{scrhack}}} package contains patches +for several packages, such as \Package{float} or \Package{listings}, so that +their content-list commands can use \Macro{listoftoc}. As a result, many +features of \Package{tocbasic} and the \KOMAScript{} classes are also +available for their content lists.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{BeforeStartingTOC}\OParameter{extension}\Parameter{commands}% + \Macro{AfterStartingTOC}\OParameter{extension}\Parameter{commands} +\end{Declaration} +Sometimes it's useful to be able to execute \PName{commands} immediately +before reading the auxiliary TOC file. With \Macro{BeforeStartingTOC} you can +do so either for a single file \PName{extension} or for all files that are +read using \DescRef{\LabelBase.cmd.listoftoc*}, +\DescRef{\LabelBase.cmd.listoftoc}, or \DescRef{\LabelBase.cmd.listofeachtoc}. +You can also execute \PName{commands} after reading the file if you define +them with \Macro{AfterStartingTOC}. If you omit the optional argument (or set +an empty one) a general hook will be set and the commands will be applied to +all content lists. The general before-hook is called before the individual +one, and the general after-hook is called after the individual one. While +executing the commands in these hooks, +\Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} is the +extension of the TOC file which is about to be or has just been read. + +You can find an example\textnote{Example} using \Macro{BeforeStartingTOC} in +\autoref{sec:scrwfile.clonefilefeature} on +\PageRefxmpl{scrwfile.cmd.BeforeStartingTOC}. +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{BeforeTOCHead}\OParameter{extension}\Parameter{commands}% + \Macro{AfterTOCHead}\OParameter{extension}\Parameter{commands} +\end{Declaration} +You can also define \PName{commands} that will be executed immediately before +or after setting the title of a content list using +\DescRef{\LabelBase.cmd.listoftoc*} or \DescRef{\LabelBase.cmd.listoftoc}. The +treatment of the optional parameter and the meaning of +\Macro{@currext}\IndexCmd{@currext}\important{\Macro{@currext}} is the same as +described for \DescRef{\LabelBase.cmd.BeforeStartingTOC} and +\DescRef{\LabelBase.cmd.AfterStartingTOC}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{MakeMarkcase}\Parameter{text} +\end{Declaration} +Whenever \Package{tocbasic} sets a mark for a running head, The text of the +mark will be an argument of \Macro{MakeMarkcase}. You can use this command to +change the case of the running head if necessary. The \KOMAScript{} classes +use \Macro{@firstofone}\IndexCmd{@firstofone}\important{\Macro{@firstofone}} +by default. This means the text of the running head will be set without +changing the capitalisation. If you use a different class, +\Macro{MakeMarkcase} will be set to +\Macro{MakeUppercase}\IndexCmd{MakeUppercase}% +\important{\Macro{MakeUppercase}}. However, \Package{tocbasic} only defines +this command if it is not already defined. It can therefore be predefined by +another class or package and \Package{tocbasic} will use that definition +rather than overwriting it. +\begin{Example} + For some strange reason, you want to set the running heads entirely in + lower-case letters. To apply this change automatically for all running heads + set by \Package{tocbasic}, you define: +\begin{lstcode} + \let\MakeMarkcase\MakeLowercase +\end{lstcode} +\end{Example} +Let\textnote{Hint!} me give you some advice about +\Macro{MakeUppercase}\IndexCmd{MakeUppercase}. First of all, this command is +not fully expandable. This means that it can cause problems interacting with +other commands. Beyond that, typographers agree that whenever you set whole +words or phrases in capital letters, additional spacing is absolutely +necessary. However, adding a fixed spacing between all letters is not an +adequate solution. Different pairs of letters require different spaces between +them. Additionally, some letters already create gaps in the text that must be +taken into account. Packages like \Package{ulem} or \Package{soul} can +scarcely achieve this, nor can \Macro{MakeUppercase}. The automatic letter +spacing using the \Package{microtype} package is in this respect only an +approximate solution, because it does not take into account the concrete, +font-dependent glyphs. Because\textnote{Attention!} typesetting all-capital +text is expert work and almost always requires manual adjustment, ordinary +users are recommended avoid using it, or to use it only sparingly and not in +such an exposed place as the running head.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{deftocheading}\Parameter{extension}\Parameter{definition} +\end{Declaration} +The \Package{tocbasic} package contains a default definition for typesetting +the titles of content lists. You can configure this default definition through +various features discussed in the \DescRef{\LabelBase.cmd.setuptoc} comand +below. If those features are not enough, you can use \Macro{deftocheading} +to define your own title for the content list with the given file +\PName{extension}. The \PName{definition} of the title can use a single +parameter, \PValue{\#1}. When the command is called inside +\DescRef{\LabelBase.cmd.listoftoc} or \DescRef{\LabelBase.cmd.listofeachtoc}, +that \PValue{\#1} will be replaced by the title of this content list.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{setuptoc}\Parameter{extension}\Parameter{feature list}% + \Macro{unsettoc}\Parameter{extension}\Parameter{feature list} +\end{Declaration} +You can use these two commands to set and clear features for a TOC file +\PName{extension} or the content list associated with it. The \PName{feature +list} is a comma-separated list of features. The \Package{tocbasic} package +recognizes following features: +\begin{description} +\item[\texttt{leveldown}] means that the content list's heading is created not + with the highest sectioning level below + \DescRef{maincls.cmd.part}\,---\,\DescRef{maincls.cmd.chapter} if available, + \DescRef{maincls.cmd.section} otherwise\,---\,but with a heading of the next + level below that. This feature is evaluated by the internal heading command. + On the other hand, if a user-defined heading command has been created with + \DescRef{\LabelBase.cmd.deftocheading}, the person defining that command is + responsible for evaluating the feature. The \KOMAScript{} classes set this + feature using the \OptionValueRef{maincls}{listof}{leveldown}% + important{\OptionValueRef{maincls}{listof}{leveldown}}% + \IndexOption{listof~=\textKValue{leveldown}} option for all file extensions + with the owner \PValue{float}. +\item[\texttt{nobabel}] prevents using the language-switching features of + \Package{babel}\IndexPackage{babel} for the TOC file associated with the + this file \PName{extension}. This feature should be used only for content + lists that are created in a fixed language, which means that changes of the + language inside of the document will no longer affect the content list. The + \Package{scrwfile}\important{\Package{scrwfile}}\IndexPackage{scrwfile} + package also uses this feature for cloned destinations, as because those + files already inherit any language changes from the cloning source. + + Note\textnote{Attention!} that you must set this feature before you add a + file extension to the list of known extensions. Changing the feature + afterwards will have no effect. +\item[\texttt{noparskipfake}] prevents\ChangedAt{v3.17}{\Package{tocbasic}} + the insertion of a final \Length{parskip} before switched off paragraph + spacing for content lists. In general, this will cause documents that use + spacing between paragraphs to have less vertical space between the list + heading and first entry than between normal headings and normal text. + Normally, therefore, you will obtain a more uniform formatting without this + feature. +\item[\texttt{noprotrusion}] prevents\ChangedAt{v3.10}{\Package{tocbasic}} + character protrusion, which allows optical margin alignment, from being + disabled in the content lists. By default, character protrusion is disabled + when the \Package{microtype}\IndexPackage{microtype} package, or another + package that supports \Macro{microtypesetup}\IndexCmd{microtypesetup}, is + loaded. So if you want optical margin alignment in the content lists, you + must set this feature. Note\textnote{Attention!}, however, that character + protrusion in content lists often results in incorrect results. This is a + known issue with character protrusion. +\item[\texttt{numbered}] means that the heading for the content list should + be numbered and included in the table of contents. This feature is evaluated + by the internal heading command. However, if a user-defined heading command + has been created with \DescRef{\LabelBase.cmd.deftocheading}, the person + creating that definition is responsible evaluating the feature. The + \KOMAScript{} classes set this feature using the + \OptionValueRef{maincls}{listof}{numbered}% + \important{\OptionValueRef{maincls}{listof}{numbered}}% + \IndexOption{listof~=\textKValue{numbered}} option for all file extensions + with the owner \PValue{float}. +\item[\texttt{numberline}] \leavevmode\ChangedAt{v3.12}{\Package{tocbasic}}% + means that any entries made using \DescRef{\LabelBase.cmd.addxcontentsline} + or \DescRef{\LabelBase.cmd.addxcontentslinetoeachtocfile}, where the + optional argument for the number is missing or empty, will be provided with + an empty \DescRef{\LabelBase.cmd.numberline} command. This usually results + in these entries being left-aligned not with the number but with the text of + the numbered entries of the same level. + Using\ChangedAt{v3.20}{\Package{tocbasic}} the \PValue{tocline} entry style + can have additional side effects. See the style attribute + \Option{breakafternumber} and \Option{entrynumberformat} in + \autoref{tab:tocbasic.tocstyle.attributes} starting on + \autopageref{tab:tocbasic.tocstyle.attributes}. + + \KOMAScript{} classes set this feature for the file extensions with the + owner \PValue{float} if you use the + \OptionValueRef{maincls}{listof}{numberline}% + \important{\OptionValueRef{maincls}{listof}{numberline}}% + \IndexOption{listof~=\textKValue{numberline}} option and for the file + extension \PValue{toc} if you use the + \OptionValueRef{maincls}{toc}{numberline}% + \important{\OptionValueRef{maincls}{toc}{numberline}}% + \IndexOption{toc~=\textKValue{numberline}} option. Similarly, this feature + is reset if you use \OptionValueRef{maincls}{listof}{nonumberline}% + \important{\OptionValueRef{maincls}{listof}{nonumberline}}% + \IndexOption{listof~=\textKValue{nonumberline}} or + \OptionValueRef{maincls}{toc}{nonumberline}% + \important{\OptionValueRef{maincls}{toc}{nonumberline}}% + \IndexOption{toc~=\textKValue{nonumberline}}. +\item[\texttt{onecolumn}] \leavevmode\ChangedAt{v3.01}{\Package{tocbasic}}% + means that this content list will automatically use \LaTeX's internal + one-column mode with \Macro{onecolumn}\IndexCmd{onecolumn}. + However\textnote{Attention!}, this applies only if this content list does + not use the \PValue{leveldown}\important{\PValue{leveldown}} feature. The + \KOMAScript{} classes \Class{scrbook} and \Class{scrreprt} activate this + feature with \DescRef{\LabelBase.cmd.AtAddToTocList} (see + \autoref{sec:tocbasic.basics}, \DescPageRef{\LabelBase.cmd.AtAddToTocList}) + for all content lists with the owner \PValue{float} or with themselves as + owner. Thus, for example, the table of contents, the list of figures, and + the list of tables are automatically printed in a single column for both + these classes. The multicolumn mode of the + \Package{multicol}\IndexPackage{multicol} package is expressly unaffected by + this option. +\item[\texttt{totoc}] means that the title of content list should be included + in the table of contents. This feature will be evaluated by the internal + heading command. However, if an user-defined heading command has been + created with \DescRef{\LabelBase.cmd.deftocheading}, the person defining + that command is responsible for evaluating this feature. The \KOMAScript{} + classes set this feature using the \OptionValueRef{maincls}{listof}{totoc}% + \important{\OptionValueRef{maincls}{listof}{totoc}}% + \IndexOption{listof~=\textKValue{totoc}} option for all file extensions with + the owner \PValue{float}. +\end{description} +The \KOMAScript{} classes recognize an additional feature: +\begin{description} +\item[\texttt{chapteratlist}] ensures that an optional subdivision is added + to the content list for each new chapter. By default, this subdivision is a + vertical space. See \DescRef{maincls.option.listof}% + \IndexOption{listof}\important{\DescRef{maincls.option.listof}} in + \autoref{sec:maincls.floats}, \DescPageRef{maincls.option.listof} for more + information about this option. +\end{description} +\begin{Example} + Because \KOMAScript{} classes use \Package{tocbasic} for the list of figures + and list of tables, there is another way to prevent chapter subdivisions in + these lists: +\begin{lstcode} + \unsettoc{lof}{chapteratlist} + \unsettoc{lot}{chapteratlist} +\end{lstcode} + + If you want the chapter subdivisions for your own list that you have defined + with the file \PName{extension} ``\PValue{loa}'' to use the same subdivision + format used by the \KOMAScript{} classes, you can use +\begin{lstcode} + \setuptoc{loa}{chapteratlist} +\end{lstcode} + And if you also want classes that use \DescRef{maincls.cmd.chapter} as the + top-level structure to use the one-column mode automatically, you can + use +\begin{lstcode} + \ifundefinedorrelax{chapter}{}{% + \setuptoc{loa}{onecolumn}% + } +\end{lstcode} + Using \DescRef{scrbase.cmd.ifundefinedorrelax} requires the + \Package{scrbase} package (see \autoref{sec:scrbase.if}, + \DescPageRef{scrbase.cmd.ifundefinedorrelax}). + + Even\textnote{Hint!} if your package will be used with another class, it + does not hurt to set these features. To the contrary, if another class also + evaluates these features, then your package would automatically use the + features of that class. +\end{Example} +As you can see, packages that use \Package{tocbasic} already support a wide +range of options for content lists that would otherwise require a great deal +of effort to implement and which are therefore missing in many packages.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{iftocfeature}\Parameter{extension}\Parameter{feature}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +You can use this command to test if a \PName{feature} was set for the given +file \PName{extension}. If so the \PName{then code} will be executed, +otherwise the \PName{else code} will be. This can be useful, for example, if +you define your own heading command using +\DescRef{\LabelBase.cmd.deftocheading} but want to support the features +\PValue{totoc}, \PValue{numbered} or \PValue{leveldown}.% +\EndIndexGroup + + +\section{Configuring Content-List Entries} +\seclabel{tocstyle}% +\BeginIndexGroup +\BeginIndex{}{table of contents>entry}% +\Index{list of contents|\see{table of contents}} + +Since\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} version~3.20, the +\Package{tocbasic} package has been able not only to configure the tables or +lists of contents and their auxiliary files but also to influence their +entries. To do so, you can define new styles or you can use and configure one +of the predefined styles. In the medium term, \Package{tocbasic} will replace +the experimental \Package{tocstyle} package that never became an official part +of the \KOMAScript{} bundle. The \KOMAScript{} classes themselves have relied +completely on the \Package{tocbasic} entry styles since version~3.20. + +\begin{Declaration} + \Counter{tocdepth} +\end{Declaration} +Entries to content lists are usually hierarchical. For this purpose, each +entry level has a numerical value. The higher this value, the lower in the +hierarchy is this level. In the standard classes, for example, parts have the +level -1 and chapters have the value 0. The \LaTeX{} counter +\Counter{tocdepth} determines the deepest level that should be shown in the +table of contents and other content lists. + +For example, the \Class{book} class sets \Counter{tocdepth} to 2, so entries +of the levels \PValue{part}, \PValue{chapter}, \PValue{section}, and +\PValue{subsection} are printed. Deeper levels like \PValue{subsubsection}, +which has the numerical value 3, are not printed. Nevertheless the entries are +part of the auxiliary file for the table of contents. + +Note that most \Package{tocbasic} entry styles, with the exception of +\PValue{gobble} (see \DescRef{\LabelBase.cmd.DeclareTOCStyleEntry}\iffree{}{, +later in this section}) observe \Counter{tocdepth}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{numberline}\Parameter{entry number}% + \Macro{usetocbasicnumberline}\OParameter{code} +\end{Declaration} +Although\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} the \LaTeX{} kernel +already defines a \Macro{numberline} command, the definition is not sufficient +for \Package{tocbasic}. Therefore \Package{tocbasic} defines its own commands +and sets \Macro{numberline} as needed using \Macro{usetocbasicnumberline} for +each content-list entry. Redefining \Macro{numberline}, therefore, is often +ineffective and may result in warnings if you use \Package{tocbasic}. + +You can use the definition of \Package{tocbasic} by putting +\Macro{usetocbasicnumberline} into your document's preamble. The command first +checks if the current definition of \Macro{numberline} +uses certain important, internal commands of \Package{tocbasic}. If this is not +the case, \Macro{usetocbasicnumberline} redefines \Macro{numberline} and +executes \PName{code}. If you omit the optional argument, it issues +a message about the redefinition with \Macro{PackageInfo}. If +you just do not want such a message, use an empty optional argument. + +Note\textnote{Attention!} that \Macro{usetocbasicnumberline} can change the +internal switch \Macro{@tempswa} globally!% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DeclareTOCStyleEntry}\OParameter{option list}\Parameter{style}% + \Parameter{entry level} + \Macro{DeclareTOCStyleEntries}\OParameter{option list}\Parameter{style}% + \Parameter{entry level list} +\end{Declaration} +These\ChangedAt{v3.20}{\Package{tocbasic}} commands define or configure the +content-list entries of a given \PName{entry level}. The \PName{entry level} +argument is a symbolic name, e.\,g. \PValue{section}, for the entry to the +table of contents of the section level with the same name or \PValue{figure} +for an entry of a figure to the list of figures. A \PName{style} is assigned +to each \PName{entry level}. The \PName{style} has to be defined before using +it as an argument of \Macro{DeclareTOCStyleEntry} or +\Macro{DeclareTOCStyleEntries}. You can use the \PName{option list} to +configure the various, usually \PName{style}-dependent, attributes of the +entries. + +Currently, \Package{tocbasic} defines the following entry styles: +\begin{description} +\item[\PValue{default}] defaults to a clone of the \PValue{dottedtocline} + style. Class authors who use \Package{tocbasic} are encouraged to change + this style to the default content-list style of the class using + \Macro{CloneTOCStyle}. For example the \KOMAScript{} classes change + \PValue{default} into a clone of \PValue{tocline}. +\item[\PValue{dottedtocline}] is similar to the style used by the standard + classes \Class{book} and \Class{report} for the \PValue{section} down to + \PValue{subparagraph} entry levels of the table of contents and for the + entries at the list of figures or list of tables. It supports the attributes + \PValue{level}, \PValue{indent}, and \PValue{numwidth}. The entries are + indented by the value of \PValue{indent} from the left. The width of the + entry number is given by the value of \PValue{numwidth}. For multi-line + entries, the indent will be increased by the value of \PValue{numwidth} for + the second and following lines. The page number is printed using + \Macro{normalfont}\IndexCmd{normalfont}. The entry text and the page number + are connected by a dotted line. \hyperref[fig:tocbasic.dottedtocline]% + {Figure~\ref*{fig:tocbasic.dottedtocline}} illustrates the attributes of + this style. + \begin{figure} + \centering + \resizebox{.8\linewidth}{!}{% + \begin{tikzpicture} + \draw[color=lightgray] (0,2\baselineskip) -- (0,-2.5\baselineskip); + \draw[color=lightgray] (\linewidth,2\baselineskip) -- + (\linewidth,-2.5\baselineskip); + \node (dottedtocline) at (0,0) [anchor=west,inner sep=0,outer sep=0] + {% + \hspace*{7em}% + \parbox[t]{\dimexpr\linewidth-9.55em}{% + \setlength{\parindent}{-3.2em}% + \addtolength{\parfillskip}{-2.55em}% + \makebox[3.2em][l]{1.1.10}% + Text of an entry in the table of contents with the + \PValue{dottedtocline} style and more than one line% + \leaders\hbox{$\csname m@th\endcsname + \mkern 4.5mu\hbox{.}\mkern 4.5mu$}\hfill\nobreak + \makebox[1.55em][r]{12}% + }% + }; + \draw[|-|,color=gray,overlay] (0,0) -- + node [anchor=north,font=\small] { + \PValue{indent} + } + (3.8em,0); + \draw[|-|,color=gray,overlay] (3.8em,\baselineskip) -- + node [anchor=south,font=\small] { + \PValue{numwidth} + } + (7em,\baselineskip); + \draw[|-|,color=gray,overlay] (\linewidth,\ht\strutbox) -- + node [anchor=south,font=\small] { + \Macro{@tocrmarg} + } + (\linewidth-2.55em,\ht\strutbox); + \draw[|-|,color=gray,overlay] (\linewidth,-\baselineskip) -- + node [anchor=north,font=\small] { + \Macro{@pnumwidth} + } + (\linewidth-1.55em,-\baselineskip); + \end{tikzpicture}% + } + \caption{Illustrations of some attributes of a TOC entry with the + \PValue{dottedtocline} style} + \label{fig:tocbasic.dottedtocline} + \end{figure} +\item[\PValue{gobble}] is the simplest possible style. Entries in this style, + regardless of the setting of \DescRef{\LabelBase.counter.tocdepth}% + \IndexCounter{tocdepth}\important{\DescRef{\LabelBase.counter.tocdepth}}, + will never be printed. The style simply gobbles the + entries, so to speak. It has the default \PValue{level} attribute, but + it is never evaluated. +\item[\PValue{largetocline}] is similar to the style used by the standard + classes for the \PValue{part} level. It supports the \PValue{level} and + \PValue{indent} attributes only. The latter deviates from the standard + classes, which do not support an indent of the \PValue{part} entries. + + A penalty is set to permit page breaks before an entry of an appropriate + level. The entries will be indented by the value of \PValue{indent} from the + left and printed with the font style \Macro{large}\Macro{bfseries}. If + \DescRef{\LabelBase.cmd.numberline} is used, the number width is 3\Unit{em}. + \DescRef{\LabelBase.cmd.numberline} is not redefined. The standard classes + do not use \DescRef{\LabelBase.cmd.numberline} for \PName{part} entries. The + value of \PName{indent} also has no effect on the indentation from the + second line and after in a multi-line entry. + + \hyperref[fig:tocbasic.largetocline]% + {Figure~\ref*{fig:tocbasic.largetocline}} illustrates the characteristics of + this style. You will also notice that the style has adopted some + inconsistencies present in the standard classes, e.\,g. the missing indent + of the second and following lines of an entry or the different values of + \Macro{@pnumwidth} that results from the font-size dependency. This can + result, in extreme cases, in the entry text coming too close. Note that the + width of the entry number shown in the figure is only valid if + \DescRef{\LabelBase.cmd.numberline} has been used. The standard classes, + however, use a distance of 1\Unit{em} after the number. + \begin{figure} + \centering + \resizebox{.8\linewidth}{!}{% + \begin{tikzpicture} + \draw[color=lightgray] (0,2\baselineskip) -- (0,-2.5\baselineskip); + \draw[color=lightgray] (\linewidth,2\baselineskip) -- + (\linewidth,-2.5\baselineskip); + \node (largetocline) at (0,0) [anchor=west,inner sep=0,outer sep=0] {% + \parbox[t]{\dimexpr \linewidth-1.55em\relax}{% + \makebox[3em][l]{\large\bfseries I}% + \large\bfseries + Text of an entry to the table of contents with the + \PValue{largetocline} style and more than one line% + \hfill + \makebox[0pt][l]{\normalsize\normalfont + \makebox[1.55em][r]{\large\bfseries 1}}% + }% + }; + \draw[|-|,color=gray] (0,\baselineskip) -- + node [anchor=south] { 3\,em } + (3em,\baselineskip); + \draw[|-|,color=gray,overlay] (\linewidth,\ht\strutbox) -- + node [anchor=south] { \Macro{@pnumwidth} } + (\linewidth-1.55em,\ht\strutbox); + \large\bfseries + \draw[|-|,color=gray,overlay] (\linewidth,-\baselineskip) -- + node [anchor=north,font=\normalfont\normalsize] { + \Macro{large}\Macro{@pnumwidth} + } + (\linewidth-1.55em,-\baselineskip); + \end{tikzpicture}% + } + \caption{Illustrations of some attributes of a TOC entry with style + \PValue{largetocline}} + \label{fig:tocbasic.largetocline} + \end{figure} +\item[\PValue{tocline}] is a flexible style. The \KOMAScript{} classes use + this style by default for all kinds of entries. Likewise, these classes + define the clones \PValue{part}, \PValue{chapter}, and \PValue{section}, or + \PValue{section} and \PValue{subsection} using this style, but add extra + \PName{initial code} to the clones to change their defaults. + + The style supports 16\important{\PValue{level}, \PValue{beforeskip}, + \PValue{breakafternumber}, \PValue{dynnumwidth}, \PValue{entryformat}, + \PValue{entrynumberformat}, \PValue{indent}, \PValue{linefill}, + \PValue{numsep}, \PValue{numwidth}, \PValue{onstarthigherlevel}, + \PValue{onstartlowerlevel}, \PValue{onstartsamelevel}, + \PValue{pagenumberbox}, \PValue{pagenumberformat}, + \PValue{raggedentrytext}, \PValue{raggedpagenumber}} additional attributes + in addition to the default \PValue{level} attribute. The defaults of all + these attributes depend on the name of the \PName{entry level} and + correspond to the results of the standard classes. So after loading + \Package{tocbasic}, you can change the style of the entries in the table of + contents of the standard classes into \PValue{tocline} using + \DescRef{\LabelBase.cmd.DeclareTOCEntryStyle} without this leading directly + to major changes in their appearance. Thus you can precisely change only + those attributes that are necessary for the desired changes. The same + applies to the list of figures and the list of tables for the standard + classes. + + Because its great flexibility, this style can in principle replace the + \PValue{dottedtocline}, \PValue{undottedtocline}, and \PValue{largetocline} + styles, but this requires more effort to configure. + + \hyperref[fig:tocbasic.tocline]% + {Figure~\ref*{fig:tocbasic.tocline}} illustrates some of the length + attributes of this style. The others are explained in + \autoref{tab:tocbasic.tocstyle.attributes} starting on + \autopageref{tab:tocbasic.tocstyle.attributes}. + \begin{figure} + \centering + \resizebox{.8\linewidth}{!}{% + \begin{tikzpicture} + \coordinate (subsection) at (0,0); + \coordinate (section) at ($(subsection)+(0,2\baselineskip)$); + \coordinate (chapter) at ($(section)+(0,2\baselineskip)$); + \coordinate (part) at ($(chapter)+(0,2.4\baselineskip+1em)$); + + \draw[color=lightgray] + ($(part)+(0,2\baselineskip)$) -- + (0,-2.5\baselineskip); + \draw[color=lightgray] + ($(part)+(\linewidth,2\baselineskip)$) -- + (\linewidth,-2.5\baselineskip); + + \coordinate (subsection) at (0,0); + + \node at (part) [anchor=west,inner sep=0,outer sep=0] + {% + \hspace*{3em}% + \parbox[t]{\dimexpr\linewidth-5.55em}{% + \setlength{\parindent}{-3em}% + \addtolength{\parfillskip}{-2.55em}% + \makebox[3em][l]{\large\bfseries I.}% + \textbf{\large Text of a part entry with the + \PValue{tocline} style and at least two lines of text}% + \hfill + \makebox[1.55em][r]{\bfseries 12}\large + }% + }; + \draw[|-|,color=gray,overlay] + (part) -- + ($(part)+(3em,0)$) + node [anchor=north east,font=\small] { + \PValue{numwidth} + }; + \draw[|-|,color=gray,overlay] + ($(part)+(\linewidth,\ht\strutbox)$) + node [anchor=north,font=\small] { + \Macro{@tocrmarg} + } -- + ($(part)+(\linewidth-2.55em,\ht\strutbox)$); + \draw[|-|,color=gray,overlay] + ($(part)+(\linewidth,-\baselineskip)$) -- + node [anchor=north,font=\small] { + \Macro{@pnumwidth} + } + ($(part)+(\linewidth-1.55em,-\baselineskip)$); + \node at (chapter) [anchor=west,inner sep=0,outer sep=0] + {% + \hspace*{1.5em}% + \parbox[t]{\dimexpr\linewidth-4.05em}{% + \setlength{\parindent}{-1.5em}% + \addtolength{\parfillskip}{-2.55em}% + \makebox[1.5em][l]{\bfseries 1.}% + \textbf{Text of a chapter entry with the + \PValue{tocline} style and more than one line of text + for demonstration purposes}% + \hfill + \makebox[1.55em][r]{\bfseries 12}% + }% + }; + \draw[|-|,color=gray,overlay] + ($(chapter)+(3em,\baselineskip)$) -- + node [anchor=west,font=\small] { + \PValue{beforeskip} + } + ($(part)+(3em,-\baselineskip)$); + \draw[|-|,color=gray,overlay] + (chapter) -- + ($(chapter)+(1.5em,0)$) + node [anchor=north east,font=\small] { + \PValue{numwidth} + }; + \draw[|-|,color=gray,overlay] + ($(chapter)+(\linewidth,\ht\strutbox)$) + node [anchor=north,font=\small] { + \Macro{@tocrmarg} + } -- + ($(chapter)+(\linewidth-2.55em,\ht\strutbox)$); + \draw[|-|,color=gray,overlay] + ($(chapter)+(\linewidth,-\baselineskip)$) + node [anchor=north,font=\small] { + \Macro{@pnumwidth} + } -- + ($(chapter)+(\linewidth-1.55em,-\baselineskip)$); + \node at (section) [anchor=west,inner sep=0,outer sep=0] + { + \hspace*{3.8em}% + \parbox[t]{\dimexpr\linewidth-6.35em}{% + \setlength{\parindent}{-2.3em}% + \addtolength{\parfillskip}{-2.55em}% + \makebox[2.3em][l]{1.1.}% + Text of a section entry with the \PValue{tocline} + style and more than one line of text for + demonstration purposes% + \leaders\hbox{$\csname m@th\endcsname + \mkern 4.5mu\hbox{.}\mkern 4.5mu$}\hfill\nobreak + \makebox[1.55em][r]{3}% + }% + }; + \node at (subsection) [anchor=west,inner sep=0,outer sep=0] + {% + \hspace*{7em}% + \parbox[t]{\dimexpr\linewidth-9.55em}{% + \setlength{\parindent}{-3.2em}% + \addtolength{\parfillskip}{-2.55em}% + \makebox[3.2em][l]{1.1.10.}% + Text of a subsection entry with the \PValue{tocline} + and more than one line of text for demonstration + purposes% + \leaders\hbox{$\csname m@th\endcsname + \mkern 4.5mu\hbox{.}\mkern 4.5mu$}\hfill\nobreak + \makebox[1.55em][r]{12}% + }% + }; + \draw[|-|,color=gray,overlay] + ($(subsection)+(0,\ht\strutbox)$) -- + node [anchor=north,font=\small] { + \PValue{indent} + } + ($(subsection)+(3.8em,\ht\strutbox)$); + \draw[|-|,color=gray,overlay] + ($(subsection)+(3.8em,0)$) -- + ($(subsection)+(7em,0)$) + node [anchor=north east,font=\small] { + \PValue{numwidth} + }; + \draw[|-|,color=gray,overlay] + ($(subsection)+(\linewidth,\ht\strutbox)$) + node [anchor=north,font=\small] { + \Macro{@tocrmarg} + } -- + ($(subsection)+(\linewidth-2.55em,\ht\strutbox)$); + \draw[|-|,color=gray,overlay] + ($(subsection)+(\linewidth,-\baselineskip)$) -- + node [anchor=north,font=\small] { + \Macro{@pnumwidth} + } + ($(subsection)+(\linewidth-1.55em,-\baselineskip)$); + \end{tikzpicture}% + } + \caption{Illustrations of some attributes of a TOC entry with the + \PValue{tocline} style} + \label{fig:tocbasic.tocline} + \end{figure} +\item[\PValue{undottedtocline}] is similar to the style used by the standard + \Class{book} and \Class{report} classes for the \PValue{chapter} entry + level, or by \Class{article} for the \PValue{section} entry level in the + table of contents. It supports\important{\PValue{level}, \PValue{indent}, + \PValue{numwidth}} only three attributes. A penalty is inserted permitting + an appropriate page break before the entry, as is a vertical skip. The + entries are printed with an indentation of \PValue{indent} from the left and + in \Macro{bfseries}. This is a departure from the standard classes, which do + not support the indentation of these entry levels. + \DescRef{\LabelBase.cmd.numberline} is used unchanged. The width of the + entry number is determined by \PValue{numwidth}. For multi-line entries the + indent will be increased by the value of \PValue{numwidth} for the second + and following lines. \hyperref[fig:tocbasic.undottedtocline]% + {Figure~\ref*{fig:tocbasic.undottedtocline}} illustrates the attributes of + this style. + \begin{figure} + \centering + \resizebox{.8\linewidth}{!}{% + \begin{tikzpicture} + \draw[color=lightgray] (0,2\baselineskip) -- (0,-2.5\baselineskip); + \draw[color=lightgray] (\linewidth,2\baselineskip) -- + (\linewidth,-2.5\baselineskip); + \node (undottedtocline) at (0,0) [anchor=west,inner sep=0,outer sep=0] + {% + \makebox[1.5em][l]{\bfseries 1}% + \parbox[t]{\dimexpr \linewidth-4.05em\relax}{% + \bfseries + Text of an entry to the table of contents with the + \PValue{undottedtocline} style and more than one line% + }% + \raisebox{-\baselineskip}{\makebox[2.55em][r]{\bfseries 3}}% + }; + \draw[|-|,color=gray,overlay] (0,\baselineskip) -- + node [anchor=south,font=\small] { + \PValue{numwidth} + } + (1.5em,\baselineskip); + \draw[|-|,color=gray,overlay] (\linewidth,\ht\strutbox) -- + node [anchor=south,font=\small] { + \Macro{@tocrmarg} + } + (\linewidth-2.55em,\ht\strutbox); + \draw[|-|,color=gray,overlay] (\linewidth,-\baselineskip) -- + node [anchor=north,font=\small] { + \Macro{@pnumwidth} + } + (\linewidth-1.55em,-\baselineskip); + \end{tikzpicture}% + } + \caption{Illustration of some attributes of the \PValue{undottedtocline} + style with the example of a chapter title}% + \label{fig:tocbasic.undottedtocline} + \end{figure} +\end{description} +You can find an explanation of the attributes of all styles that +\Package{tocbasic} defines in \autoref{tab:tocbasic.tocstyle.attributes}. +If\ChangedAt{v3.21}{\Package{tocbasic}} you use these attributes as +options to \DescRef{\LabelBase.cmd.DeclareNewTOC} (see +\DescPageRef{\LabelBase.cmd.DeclareNewTOC}), you must prefix the names of the +attribute by \PValue{tocentry}, e\,g. \PValue{level} becomes +\Option{tocentrylevel}. If\ChangedAt{v3.20}{\Package{tocbasic}} use +these attributes as options for +\DescRef{maincls-experts.cmd.DeclareSectionCommand}% +\IndexCmd{DeclareSectionCommand}\IndexCmd{DeclareNewSectionCommand}% +\IndexCmd{RedeclareSectionCommand}\IndexCmd{ProvideSectionCommand} (see +\DescPageRef{maincls-experts.cmd.DeclareSectionCommand}) and similar commands, +you must prefix the names of the attributes with \PValue{toc}, e\,g. +\PValue{level} becomes \Option{toclevel}. + +Finally, using \Macro{DeclareTOCStyleEntry} will define the internal command +\Macro{l@\PName{entry level}}. + +\begin{desclist} + \desccaption{% + Attributes of the predefined TOC-entry styles of \Package{tocbasic}% + \label{tab:tocbasic.tocstyle.attributes}% + }{% + Attributes of the TOC-entry styles (\emph{continued})% + }% + \entry{\OptionVName{beforeskip}{length}}{% + The vertical distance inserted before an entry of this level in the + \PValue{tocline} style (see \autoref{fig:tocbasic.tocline}). The distance + is made using either \Macro{vskip} or \Macro{addvspace} depending on the + \PName{entry level}, to maintain compatibility as far as possible with the + standard classes and earlier versions of \KOMAScript. + + For the \PValue{part} \PName{entry level}, the attribute will be + initialised with \texttt{2.25em plus 1pt}; for \PValue{chapter}, with + \texttt{1em plus 1pt}. If the \PName{chapter} \PName{entry level} is + undefined, \PValue{section} is initialised with \texttt{1em plus 1pt} + instead. The initial value for all other levels is \texttt{0pt plus + .2pt}.% + }% + \entry{\OptionVName{breakafternumber}{switch}}{% + \PName{switch} is one of the values for simple switches from + \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. If the + switch is active in the \PValue{tocline} style, there will be a line break + after the number set with + \DescRef{\LabelBase.cmd.numberline}\IndexCmd{numberline}. The line after + the entry number again starts flush left with the number. The default is + false for the \PValue{tocline} style. + + If\textnote{Attention!} the \Option{numberline} feature has been activated + for a content list (see \DescRef{\LabelBase.cmd.setuptoc}, + \autoref{sec:tocbasic.toc}, \DescPageRef{\LabelBase.cmd.setuptoc}), as is + the case with the \KOMAScript{} classes when the + \OptionValueRef{maincls}{toc}{numberline}% + \IndexOption{toc~=\textKValue{numberline}} option is used, then the + unnumbered entries will nevertheless have a (by default empty) number line + using the formatting of \Option{entrynumberformat}.% + }% + \entry{\OptionVName{dynnumwidth}{switch}}{% + \PName{switch} is one of the values for simple switches from + \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. If the + switch is active with the \PValue{tocline} style, the \PValue{numwidth} + attribute specifies a minimum value. If a previous \LaTeX{} run has + determined that the maximum width of the entry numbers of the same level + plus the value of \PValue{numsep} is greater than this minimum, the + calculated value will be used instead.% + }% + \entry{\OptionVName{entryformat}{command}}{% + You can use this attributes to change the format of the entry. The value + should be a \PName{command} with exactly one argument. This argument is + not necessarily fully expandable. You should not use commands like + \Macro{MakeUppercase}, which expects a fully expandable argument. Font + changes are relative to \Macro{normalfont}\Macro{normalsize}. Note that + the output of \Option{linefill} and the page number are independent of + \Option{entryformat}. See also the \Option{pagenumberformat} attribute . + + The initial value of the attribute for the \PValue{part} \PName{entry + level} is \Macro{large}\Macro{bfseries}, and for \PValue{chapter}, it is + \Macro{bfseries}. If the \PValue{chapter} level is not defined, + \PValue{section} uses \Macro{bfseries}. All other levels print the + argument unchanged.% + }% + \entry{\OptionVName{entrynumberformat}{command}}{% + You can use this attribute to format the entry number within + \DescRef{\LabelBase.cmd.numberline}. The value should be a \PName{command} + with exactly one argument. Font changes are relative to the one of + attribute \Option{entryformat}. + + The initial \PName{command} prints the argument unchanged. This means the + entry number will be printed as it is. + + If\textnote{Attention!} the \Option{numberline} feature for a content list + has been activated (see \DescRef{\LabelBase.cmd.setuptoc}, + \autoref{sec:tocbasic.toc}, \DescPageRef{\LabelBase.cmd.setuptoc}), as is + the case with the \KOMAScript{} classes using the + \OptionValueRef{maincls}{toc}{numberline}% + \IndexOption{toc~=\textKValue{numberline}} option, the unnumbered entries + will execute the \PName{command} as well.% + }% + \entry{\OptionVName{indent}{length}}{% + The horizontal distance of the entry from the left margin (see + \autoref{fig:tocbasic.dottedtocline} and \autoref{fig:tocbasic.tocline}). + + For the \PValue{tocline} style, all entry levels whose names start with + ``\texttt{sub}'' are initialised with the + \PValue{indent}+\PValue{numwidth} of the entry level of the same name + without this prefix. For the \PValue{dottedtocline}, + \PValue{undottedtocline}, and \PValue{tocline} styles, the initial values + of levels \PValue{part} down to \PValue{subparagraph} and the levels + \PValue{figure} and \PValue{table} are compatible with the standard + classes. All other levels do not have an initial value. Therefore you have + to set an explicit value for such levels when they are defined first + time.% + }% + \entry{\OptionVName{level}{integer}}{% + The numerical value of the \PName{entry level}. Only those entries whose + numerical value is less than or equal to the + \DescRef{\LabelBase.counter.tocdepth}% + \important{\DescRef{\LabelBase.counter.tocdepth}}\IndexCounter{tocdepth} + counter are printed. + + This attribute is mandatory for all styles and will be defined + automatically when the style is declared. + + For the \PValue{tocline} style, all entry levels whose name starts with + ``\texttt{sub}'' are initialised with the value of the entry level of the + same name without this prefix plus one. For the \PValue{dottedtocline}, + \PValue{largetocline}, \PValue{tocline}, and \PValue{undottedtocline} + styles, the entry levels from \PValue{part} to \PValue{subparagraph}, as + well as \PValue{figure} and \PValue{table}, are initialised to be + compatible with the standard classes. For all other levels, the + initialisation is done with the value of \Macro{\PName{entry + level}numdepth}, if this is defined.% + }% + \entry{\OptionVName{linefill}{code}}{% + With the \PValue{tocline} style, you can change what is used to fill the + space between the end of the entry text and the page number. The + \PName{linefill} attribute contains the \PName{code} that prints this + filler. For the \PValue{part} and \PValue{chapter} \PName{entry level}s, + the attribute is initialised with \Macro{hfill}. If no \PValue{chapter} + \PName{entry level} has been defined, \PValue{section} also uses + \Macro{hfill}. All other entry levels are initialised with + \DescRef{\LabelBase.cmd.TOCLineLeaderFill} (see + \DescPageRef{\LabelBase.cmd.TOCLineLeaderFill}). + + Incidentally, if the \PName{code} specified does not automatically fill + the gap, you should also activate the \PValue{raggedpagenumber} attribute + to avoid ``\texttt{underfull \Macro{hbox}}'' messages.% + }% + \entry{\OptionVName{numsep}{length}}{% + The \PValue{tocline} style tries to ensure a minimum distance of + \PName{length} between the entry number and the entry text. If + \PValue{dynnumwidth} is active, it will correct the number width to achieve + this. Otherwise it simply throws a warning, if the condition is not met. + + The initial \PName{length} is 0.4\Unit{em}.% + }% + \entry{\OptionVName{numwidth}{length}}{% + The width reserved for the entry number (see + \autoref{fig:tocbasic.dottedtocline} to + \autoref{fig:tocbasic.undottedtocline}). With the \PValue{dottedtocline}, + \PValue{tocline}, and \PValue{undottedtocline} styles, this \PName{length} + is added to the \PName{length} of attribute \PValue{indent} for the second + and following lines of the entry text. + + With the \PValue{tocline} style, the initial \PName{length} of all entries + whose name starts with ``\texttt{sub}'' is the value of the level without + this prefix plus 0.9\Unit{em}, if such a level with corresponding + attributes exists. With the \PValue{dottedtocline}, + \PValue{undottedtocline}, and \PValue{tocline} styles, the initial + \PName{length}s of levels from \PValue{part} to \PValue{subparagraph}, as + well as \PName{figure} and \PName{table}, are compatible with those of the + standard classes. All other levels do not have an initial value. Therefore + you must set \PValue{numwidth} explicitly when the entry level is first + used.% + }% + \entry{\OptionVName{onstarthigherlevel}{code}}{% + The \PValue{tocline} style can execute \PName{code} at the start of an + entry, depending on whether the previous entry had numerical level greater + than, the same as, or less than the current entry. The \PName{code} + specified by this attribute will be executed if the current entry has a + greater numerical value, i.\,e. it is lower in the entry hierarchy, than + the previous one. + + Note that detecting the level of the previous entry only works so long as + \Macro{lastpenalty} has not changed since the previous entry. + + The initial \PName{code} is \DescRef{\LabelBase.cmd.LastTOCLevelWasLower} + (see \DescPageRef{\LabelBase.cmd.LastTOCLevelWasLower}).% + }% + \entry{\OptionVName{onstartlowerlevel}{code}}{% + The \PValue{tocline} style can execute \PName{code} at the start of an + entry, depending on whether the previous entry had numerical level greater + than, the same as, or less than the current entry. The \PName{code} + specified by this attribute will be executed if the current entry has a + lower numerical value, i.\,e. it is higher in the entry hierarchy, than + the previous one. + + Note that detecting the level of the previous entry only works so long as + \Macro{lastpenalty} has not changed since the previous entry. + + The initial \PName{code} is \DescRef{\LabelBase.cmd.LastTOCLevelWasHigher} + (see \DescPageRef{\LabelBase.cmd.LastTOCLevelWasHigher}), which usually + favours a page break before the entry.% + }% + \entry{\OptionVName{onstartsamelevel}{code}}{% + The \PValue{tocline} style can execute \PName{code} at the start of an + entry, depending on whether the previous entry had numerical level greater + than, the same as, or less than the current entry. The \PName{code} + specified by this attribute will be executed if the current entry has the + same numerical value, i.\,e. it is on the same level in the entry + hierarchy, as the previous one. + + Note that detecting the level of the previous entry only works so long as + \Macro{lastpenalty} has not changed since the previous entry. + + The initial \PName{code} is \DescRef{\LabelBase.cmd.LastTOCLevelWasSame} + (see \DescPageRef{\LabelBase.cmd.LastTOCLevelWasSame}), which usually + favours a page break before the entry.% + }% + \entry{\OptionVName{pagenumberbox}{command}}{% + By default the page number of an entry is printed flush right in a box + of width \Macro{@pnumwidth}. In the \PValue{tocline} style, you can + change the \PName{command} to print the number using this attribute. The + \PName{command} should expect exactly one argument, the page number. + + This attribute is initialised with the box already mentioned.% + }% + \entry{\OptionVName{pagenumberformat}{command}}{% + You can use this attribute to change the format of the page number of an + entry. The \PName{command} should expect exactly one argument, the page + number. Font changes are relative to the font of \Option{entryformat} + followed by \Macro{normalfont}\Macro{normalsize}. + + The initial \PName{command} of entry level \PValue{part} prints the + argument in \Macro{large}\Macro{bfseries}. The initial \PName{command} of + all other levels prints the argument in + \Macro{normalfont}\Macro{normalcolor}.% + }% + \entry{\OptionVName{raggedentrytext}{switch}}{% + The\ChangedAt{v3.21}{\Package{tocbasic}} \PName{switch} is one of the + values for simple switches from \autoref{tab:truefalseswitch}, + \autopageref{tab:truefalseswitch}. If the switch is active, the + \PValue{tocline} style prints the text of an entry ragged right instead of + fully justified, and only words that are longer than a text line are + automatically hyphenated. + + This \PName{switch} is false by default.% + }% + \entry{\OptionVName{raggedpagenumber}{switch}}{% + The \PName{switch} is one of the values for simple switches from + \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. If the + switch is active, the \PValue{tocline} style does not force the page + number to be right justified. + + Depending on the value of \PValue{linefill}, setting this attribute could + affect only whether a warning message appears, or the formatting of the + page number as well. So it is important to set both attributes so that + they correspond. + + By default the \PName{switch} is not activated and therefore corresponds + with an initial value of \Macro{hfill} or + \DescRef{\LabelBase.cmd.TOCLineLeaderFill} for the \PValue{linefill} + attribute.% + }% +\end{desclist} + +% New translation by Markus Kohm (please fix it!): +\Macro{DeclareTOCStyleEntries}\ChangedAt{v3.26}{\Package{tocbasic}} uses +\Macro{DeclareTOCStyleEntry} to define not only one \PName{entry level} but +several entry levels. Each of the entry levels, given by the comma-separated +\PName{entry level list}, is defined with the same \PName{style} and the +settings of the given \PName{option list}.% +% End of new translation. +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DeclareTOCEntryStyle}\Parameter{style}% + \OParameter{initial code}% + \Parameter{command code}% + \Macro{DefineTOCEntryOption}\Parameter{option}\OParameter{default value}% + \Parameter{code}% + \Macro{DefineTOCEntryBooleanOption}\Parameter{option}% + \OParameter{default value}% + \Parameter{prefix}% + \Parameter{postfix}% + \Parameter{description}%% + %\OParameter{initial code}% + \Macro{DefineTOCEntryCommandOption}\Parameter{option}% + \OParameter{default value}% + \Parameter{prefix}% + \Parameter{postfix}% + \Parameter{description}%% + %\OParameter{initial code}% + \Macro{DefineTOCEntryIfOption}\Parameter{option}% + \OParameter{default value}% + \Parameter{prefix}% + \Parameter{postfix}% + \Parameter{description}%% + %\OParameter{initial code}% + \Macro{DefineTOCEntryLengthOption}\Parameter{option}% + \OParameter{default value}% + \Parameter{prefix}% + \Parameter{postfix}% + \Parameter{description}%% + %\OParameter{initial code}% + \Macro{DefineTOCEntryNumberOption}\Parameter{option}% + \OParameter{default value}% + \Parameter{prefix}% + \Parameter{postfix}% + \Parameter{description}% + %\OParameter{initial code}% +\end{Declaration} +\Macro{DeclareTOCEntryStyle}\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} is +one of the most complex commands in \KOMAScript. It is therefore explicitly +intended for \LaTeX{} developers and not for ordinary \LaTeX{} users. It lets +you define new a \PName{style} for content-list entries. Usually, entries to +content lists are made using +\Macro{addcontentsline}\IndexCmd{addcontentsline}, or preferably, if you use +\Package{tocbasic}, with +\DescRef{\LabelBase.cmd.addxcontentsline}\IndexCmd{addxcontentsline} (see +\autoref{sec:tocbasic.basics}, \DescPageRef{\LabelBase.cmd.addxcontentsline}). +In both cases \LaTeX{} writes a corresponding +\Macro{contentsline}\IndexCmd{contentsline} to the appropriate auxiliary file. +When reading this auxiliary file, \LaTeX{} then executes a +\Macro{l@\PName{entry level}} command for each \Macro{contentsline}. + +If you later assign a \PName{style} to an entry level using +\DescRef{\LabelBase.cmd.DeclareTOCStyleEntry}, the \PName{initial code} is +executed first, if provided, and then the \PName{command code} for the +definition of \Macro{l@\PName{entry level}}. The \PName{command code} is the +code that will be expanded and executed by \Macro{l@\PName{entry level}}. +Inside \PName{command code} \texttt{\#1} is the name of the TOC entry level +and \texttt{\#\#1} and \texttt{\#\#2} are the arguments of +\Macro{l@\PName{entry level}}. + +The \PName{initial code} serves first to initialise all attributes of the +\PName{style}. Developers should make sure that all attributes are provided +with values here. Only then does \DescRef{\LabelBase.cmd.DeclareTOCStyleEntry} +work without errors if an \PName{option list} is not specified. The second +task of the \PName{initial code} is to define all the options that this +\PName{style} recognises. The \Option{level} option is always defined +automatically. The value of the \Option{level} can be queried within the +\PName{command code} with \Macro{@nameuse}\PParameter{\#1tocdepth}% +\important{\Macro{\PName{entry level}tocdepth}}, for example, to compare it +with the \DescRef{\LabelBase.counter.tocdepth}\IndexCounter{tocdepth} counter. + +To define options for the attributes of the +\PName{style} inside the \PName{initial code}, you can use the commands \Macro{DefineTOCEntryBooleanOption}, +\Macro{DefineTOCEntryCommandOption}, \Macro{DefineTOCEntryIfOption}, +\Macro{DefineTOCEntryLengthOption}, and \Macro{DefineTOCEntryNumberOption}. +These commands each define an \PName{option} that, when called, +defines a macro named \Macro{\PName{prefix}\PName{entry + level}\PName{postfix}} set to the given value or to the +\PName{default value} of the option. The +\Macro{DefineTOCEntryIfOption} command is a somewhat special case. It defines \Macro{\PName{prefix}\PName{entry + level}\PName{postfix}} as a command with two arguments. If the value passed to +the option is one of the activation (true) values from \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch}, the command expands to the first +argument. If the value to the option is a deactivation (false) value, the command +expands to the second argument. + +The \PName{description} should be a brief message that describes the sense +of the option with some keywords. The \Package{tocbasic} package uses this text +in error messages, warnings, and information output on the terminal and to the +\File{log} file. + +The simplest style of \Package{tocbasic}, \PValue{gobble}, is defined +using: +\begin{lstcode} + \DeclareTOCEntryStyle{gobble}{}% +\end{lstcode} +If you now define an entry level \PValue{dummy} in this style using: +\begin{lstcode} + \DeclareTOCStyleEntry[level=1]{gobble}{dummy} +\end{lstcode} +this would correspond, among other things, to: +\begin{lstcode} + \def\dummytocdepth{1} + \def\l@dummy#1#2{} +\end{lstcode} + +For example, within the \PValue{tocline} style, +\begin{lstcode} + \DefineTOCEntryCommandOption{linefill}[\TOCLineLeaderFill]% + {scr@tso@}{@linefill}{filling between text and page number}% +\end{lstcode} +is used to define the \Option{linefill} option. By specifying +\DescRef{\LabelBase.cmd.TOCLineLeaderFill} as the \PName{default value}, +a call such as +\begin{lstcode} + \DeclareTOCStyleEntry[linefill]{tocline}{part} +\end{lstcode} +would, among other things, create the definition +\begin{lstcode} + \def\scr@tso@part@linefill{\TOCLineLeaderFill} +\end{lstcode} + +If you want to define your own styles, you should first study the definition +of the \PValue{dottedtocline} style. After you understand this definition, you +can find many hints as to how to use the commands effectively in the much more +complex definition of the \PValue{tocline} style. + +However, in many cases it will be sufficient to clone an existing style using +\DescRef{\LabelBase.cmd.CloneTOCEntryStyle} and to change the initial code of +the new style using \DescRef{\LabelBase.cmd.TOCEntryStyleInitCode} or +\DescRef{\LabelBase.cmd.TOCEntryStyleStartInitCode}. + +\Macro{DefineTOCEntryOption} is merely used to define the other commands and +you should not use it directly. Normally, there is no need for it. It is +mentioned here only for the sake of completeness.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{CloneTOCEntryStyle}\Parameter{style}\Parameter{new style}% +\end{Declaration} +With\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} this command you can clone +an existing \PName{style}. It defines a \PName{new style} with the same +attributes and settings as the existing \PName{style}. The package itself uses +\Macro{CloneTOCEntryStyle} to declare the \PValue{default} style as a clone of +\PValue{dottedtocline}. The \KOMAScript{} classes use the command to declare +the styles \PValue{part}, \PValue{section}, and \PValue{chapter} or +\PValue{subsection} as clones of \PValue{tocline} and then modify them with +\DescRef{\LabelBase.cmd.TOCEntryStyleInitCode} and +\DescRef{\LabelBase.cmd.TOCEntryStyleStartInitCode}. The \Class{scrbook} and +\Class{scrreprt} classes newly declare the \PValue{default} style as a clone +of \PValue{section}, and \Class{scrartcl} declares it as a clone of +\PValue{subsection}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{TOCEntryStyleInitCode}\Parameter{style}% + \Parameter{initial code}% + \Macro{TOCEntryStyleStartInitCode}\Parameter{style}% + \Parameter{initial code} +\end{Declaration} +Every\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} TOC-entry style has an +initialisation code. This is used whenever a \PName{style} is assigned to an +TOC entry using \DescRef{\LabelBase.cmd.DeclareTOCEntryStyle}. This +\PName{initial code} should not have global side effects, because it is also +used for local initialisation inside other commands like +\DescRef{\LabelBase.cmd.DeclareNewTOC}\IndexCmd{DeclareNewTOC}. The +\PName{initial code} not only defines all attributes of a \PName{style}, but +it also sets the defaults for those attributes. + +You can use \Macro{TOCEntryStyleStartInitCode} and +\Macro{TOCEntryStyleInitCode} to extend previously existing initialisation +code with further \PName{initial code}. \Macro{TOCEntryStyleStartInitCode} +adds \PName{initial code} in front of the existing code. +\Macro{TOCEntryStyleInitCode} adds the \PName{initial code} at the end of the +existing initialisation code. The \KOMAScript{} classes, for example, use +\Macro{TOCEntryStyleStartInitCode} to properly initialise the fill, fonts, and +vertical spacing of the \PValue{part} style cloned from \PValue{tocline}. For +example, the \Class{scrbook} and \Class{scrreprt} classes use +\begin{lstcode} + \CloneTOCEntryStyle{tocline}{section} + \TOCEntryStyleStartInitCode{section}{% + \expandafter\providecommand% + \csname scr@tso@#1@linefill\endcsname + {\TOCLineLeaderFill\relax}% + } +\end{lstcode} +to define \PValue{section} as a modified clone of \PValue{tocline}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{LastTOCLevelWasHigher}% + \Macro{LastTOCLevelWasSame}% + \Macro{LastTOCLevelWasLower} +\end{Declaration} +At\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} the beginning of entries +using the \PValue{tocline} style, \Package{tocbasic} executes one of these +three commands depending on \Macro{lastpenalty}. \Macro{LastTOCLevelWasHigher} +and \Macro{LastTOCLevelWasSame} used in vertical mode add +\Macro{addpenalty}\PParameter{\Macro{@lowpenalty}} and therefore permit a page +break before an entry with the same or higher hierarchical position. +\Macro{LastTOCLevelWasLower} is empty, so a page break between an entry and +its first sub-entry is not permitted. + +Users should not redefine these commands. Instead, you should change the +behaviour of single entry levels using the \PValue{onstartlowerlevel}, +\PValue{onstartsamelevel}, and \PValue{onstarthigherlevel} attributes.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{TOCLineLeaderFill}\OParameter{leader} +\end{Declaration} +This\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} command is intended to be +used as a value for the \Option{linefill} option of the \PName{tocline} +TOC-entry style. It creates a connection between the end of the entry text and +the entry's page number. You can specify the \PName{leader}, which is repeated +at regular intervals, as an optional argument. The default is a dot. + +As the name suggests, the command uses \Macro{leaders} to output the +\PName{leader}. The spacing used is defined analogously to the \LaTeX{} kernel +command \Macro{@dottedtocline} by +\Macro{mkern}\Macro{@dotsep}\Unit{\texttt{mu}}.% +\EndIndexGroup +\EndIndexGroup + + +\section{Internal Commands for Class and Package Authors} +\seclabel{internals} + +The \Package{tocbasic} package provides some internal commands for the use of +class and package authors. These commands all begin with the prefix +\Macro{tocbasic@}. But\textnote{Attention!} even class or package authors +should not redefine them! Their inner functioning may be changed or extended +at any time, so redefining these commands could significantly damage the +\Package{tocbasic}'s operation. + +\begin{Declaration} + \Macro{tocbasic@extend@babel}\Parameter{extension} +\end{Declaration} +At every change of the current language, either at the beginning of the +document or inside the document, the \Package{babel}\IndexPackage{babel} +package (see \cite{package:babel}), or rather a \LaTeX{} kernel enhanced by +\Package{babel}'s language management, writes language-switching commands to +the files with the \File{toc}, \File{lof}, and \File{lot} extensions. The +\Package{tocbasic} package extends this mechanism with +\Macro{tocbasic@extend@babel} so that it also works for other file extensions. +The \PName{extension} argument must be completely expanded! Otherwise the +there is a risk that, for example, the meaning of the argument has already +change at the time it is actually evaluated. + +This command is typically invoked by default for every file \PName{extension} +added to the list of known extensions with +\DescRef{\LabelBase.cmd.addtotoclist}. You can suppress this with the +\PValue{nobabel}\important{\PValue{nobabel}} feature (see +\DescRef{\LabelBase.cmd.setuptoc}, \autoref{sec:tocbasic.toc}, +\DescPageRef{\LabelBase.cmd.setuptoc}). \Package{tocbasic} does this +automatically for the extensions \File{toc}, \File{lof}, and \File{lot} to +avoid switching languages twice in the corresponding files. + +There is usually no reason to call this command yourself. However, there could +conceivably be content lists that are not under the control of +\Package{tocbasic} and so are not in \Package{tocbasic}'s list of known file +extensions, but which nevertheless should use \Package{babel}'s language +switching mechanism. You can call the command explicitly for those files. +But\textnote{Attention!} please note that this should be done only once per +file extension!% +\EndIndexGroup + + +\begin{Declaration} + \Macro{tocbasic@starttoc}\Parameter{extension} +\end{Declaration} +This command is the actual replacement for the +\Macro{@starttoc}\IndexCmd{@starttoc}\important{\Macro{@starttoc}} command +from the \LaTeX{} kernel. It is the command behind +\DescRef{\LabelBase.cmd.listoftoc*} (see \autoref{sec:tocbasic.toc}, +\DescPageRef{\LabelBase.cmd.listoftoc*}). Class or package authors who want to +take advantage of \Package{tocbasic} should at least use this command, or even +better, \DescRef{\LabelBase.cmd.listoftoc}. The command uses +\Macro{\@starttoc} internally, but sets +\Length{parskip}\IndexLength{parskip}\important{\Length{parskip}\\ +\Length{parindent}\\ \Length{parfillskip}}, +\Length{parindent}\IndexLength{parindent} to 0, and \Length{parfillskip} to 0 +to infinity. Moreover, +\Macro{@currext}\important{\Macro{@currext}}\IndexCmd{@currext} is set to the +file extension of the current TOC file, so it can be evaluated during the +subsequent execution of the hooks. You can find an explanation of these hooks +below. + +Because\textnote{Attention!} \LaTeX{} opens a new content-list file for +writing after reading that file, calling this command may result in an error +message of the type +\begin{lstoutput} + ! No room for a new \write . + \ch@ck ...\else \errmessage {No room for a new #3} + \fi +\end{lstoutput} +if no more write handles are available. You can solve this problem by loading +the \Package{scrwfile}\important{\Package{scrwfile}}\IndexPackage{scrwfile} +package described in \autoref{cha:scrwfile}, or by using Lua\LaTeX{}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{tocbasic@@before@hook}% + \Macro{tocbasic@@after@hook} +\end{Declaration} +The \Macro{tocbasic@@before@hook} hook is executed immediately before reading +an auxiliary file for a content list, before executing the commands defined +with \DescRef{\LabelBase.cmd.BeforeStartingTOC} command. You can extend this +hook using \Macro{g@addto@macro}\IndexCmd{g@addto@macro}. + +Similarly, \Macro{tocbasic@@after@hook} is executed immediately after reading +such an auxiliary file and before executing the commands defined with +\DescRef{\LabelBase.cmd.AfterStartingTOC}. You can extend this hook using +\Macro{g@addto@macro}\IndexCmd{g@addto@macro}. + +\KOMAScript{} uses these hooks to dynamically adjust content lists to the +width of the heading numbers. Only classes and packages should use these +hooks. Users\textnote{Attention!} should really use +\DescRef{\LabelBase.cmd.BeforeStartingTOC} and +\DescRef{\LabelBase.cmd.AfterStartingTOC} instead. Authors of packages should +also prefer these commands. These hooks should not be used to generate any +output! + +If neither\textnote{Attention!} \DescRef{\LabelBase.cmd.listofeachtoc} nor +\DescRef{\LabelBase.cmd.listoftoc} nor \DescRef{\LabelBase.cmd.listoftoc*} are +used to output the content list, the hooks should be executed explicitly.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{tocbasic@\PName{extension}@before@hook}% + \Macro{tocbasic@\PName{extension}@after@hook} +\end{Declaration} +These hooks are executed directly after +\DescRef{\LabelBase.cmd.tocbasic@@before@hook} or before +\DescRef{\LabelBase.cmd.tocbasic@@after@hook} for the TOC file with the +corresponding file \PName{extension}. Class\textnote{Attention!} and package +authors should never change them under any circumstances! If +neither\textnote{Attention!} \DescRef{\LabelBase.cmd.listofeachtoc} nor +\DescRef{\LabelBase.cmd.listoftoc} nor \DescRef{\LabelBase.cmd.listoftoc*} are +used to output a content list, the hooks should nevertheless be called, if +they are defined. These commands can be undefined. For an appropriate test, +see \DescRef{scrbase.cmd.scr@ifundefinedorrelax}% +\IndexCmd{scr@ifundefinedorrelax} in \autoref{sec:scrbase.if}, +\DescPageRef{scrbase.cmd.scr@ifundefinedorrelax}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{tocbasic@listhead}\Parameter{title} +\end{Declaration} +This command is used by \DescRef{\LabelBase.cmd.listoftoc} and +\DescRef{\LabelBase.cmd.listofeachtoc} to set the heading of the content list. +This can be either the default heading of the \Package{tocbasic} package or a +custom definition. If you define your own command for the heading, you can +also use \Macro{tocbasic@listhead}. In this case, you should define +\Macro{@currext}\important{\Macro{@currext}}\IndexCmd{@currext} to be the file +extension of the corresponding TOC file before using +\Macro{tocbasic@listhead}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{tocbasic@listhead@\PName{extension}}\Parameter{title} +\end{Declaration} +This command is used in \DescRef{\LabelBase.cmd.tocbasic@listhead} to set the +individual headings, optional table of contents entry, and running head, if it +is defined. Otherwise, \DescRef{\LabelBase.cmd.tocbasic@listhead} defines them +before their use.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{tocbasic@addxcontentsline}% + \Parameter{extension}\Parameter{level}\Parameter{number}\Parameter{text}% + \Macro{nonumberline} +\end{Declaration} +The\ChangedAt{v3.12}{\Package{tocbasic}} \Macro{tocbasic@addxcontentsline} +command creates entry of the specified level in the TOC file with the given +\PName{extension}. Whether the entry is numbered or not depends on whether or +not the \PName{number} argument is empty. In this case the \PName{text} will +be prefixed by \Macro{nonumberline} without any argument. Otherwise, +\DescRef{\LabelBase.cmd.numberline} with the \PName{number} argument will used +as usual. + +The \Macro{nonumberline} command is redefined inside +\DescRef{\LabelBase.cmd.listoftoc} (see \autoref{sec:tocbasic.toc}, +\DescPageRef{\LabelBase.cmd.listoftoc}) depending on the \PValue{numberline} +feature (see \autoref{sec:tocbasic.toc}, +\DescPageRef{\LabelBase.cmd.setuptoc}). As a result, changing this feature +results in changes of the corresponding TOC immediately at the next \LaTeX{} +run.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{tocbasic@DependOnPenaltyAndTOCLevel}\Parameter{entry level}% + \Macro{tocbasic@SetPenaltyByTOCLevel}\Parameter{entry level} +\end{Declaration} +The\ChangedAt[2016/03]{v3.20}{\Package{tocbasic}} \PValue{tocline} +content-list style (see \autoref{sec:tocbasic.tocstyle}) sets a +\Macro{penalty} at the end of each entry via +\Macro{tocbasic@SetPenaltyByTOCLevel} so that no page break can occur after an +entry. The exact value chosen depends on the \PName{entry level}. + +At the beginning of an entry, \Macro{tocbasic@DependOnPenaltyAndTOCLevel} is +used to execute the value of the \Option{onstartlowerlevel}, the +\Option{onstartsamelevel}, or the \Option{onstarthigherlevel} style option, +depending on \Macro{lastpenalty} and the current \PName{entry level}. By +default, the first two permit a page break when executed in vertical mode. + +Developers of \PValue{tocline}-compatible styles should copy this behaviour. +To do so, they can fall back on these internal macros.% +\EndIndexGroup + + +\section{A Complete Example} +\seclabel{example} + +This section provides a complete example of how to define your own floating +environment including an associated content list and \KOMAScript{} integration +using \Package{tocbasic}. This example uses internal commands, that is, they +have a ``\texttt{@}'' in their name. This means\textnote{Attention}, that you +must either put the code into a package or class or placed it between +\Macro{makeatletter}\important[i]{\Macro{makeatletter}\\\Macro{makeatother}}% +\IndexCmd{makeatletter} and \Macro{makeatother}\IndexCmd{makeatother}. + +First\textnote{environment}, we need a new floating environment. +That's easy with the following: +\begin{lstcode} + \newenvironment{remarkbox}{% + \@float{remarkbox}% + }{% + \end@float + } +\end{lstcode} +The new environment is named \Environment{remarkbox}. + +Each\textnote{placement} floating environment has a default placement. It +consists of one or more of the well-known placement options: \PValue{b}, + \PValue{h}, \PValue{p} and \PValue{t}. +\begin{lstcode} + \newcommand*{\fps@remarkbox}{tbp} +\end{lstcode} +The new floating environment should be placed by default only either at +the top of a page, at the bottom of a page, or on a separate page. + +Floating\textnote{type} environments also have a numerical floating +type between 1 and 31. Environments with the same active bit at the floating type cannot change +their order. Figures and tables normally use type~1 and 2. So a figure that +comes later in the source code than a table may be output earlier than the +table and vice versa. +\begin{lstcode} + \newcommand*{\ftype@remarkbox}{4} +\end{lstcode} +The new environment has floating type~4, so it may pass figures and floats and +may be passed by those. + +The\textnote{number} captions of floating environment also have numbers. +\begin{lstcode} + \newcounter{remarkbox} + \newcommand*{\remarkboxformat}{% + Remark~\theremarkbox\csname autodot\endcsname} + \newcommand*{\fnum@remarkbox}{\remarkboxformat} +\end{lstcode} +Here, a new counter is defined first, which is independent of the chapters +or the counters of other structural levels. \LaTeX{} itself also defines +\Macro{theremarkbox} with the default output as an Arabic number. +This is then used to define the formatted output of the +counter. The formatted output is again defined as a floating-point +number for use in the \DescRef{maincls.cmd.caption} command. + +Floating\textnote{file name extension} environments have their own content lists +and those need an auxiliary file named \Macro{jobname} and a file +extension: +\begin{lstcode} + \newcommand*{\ext@remarkbox}{lor} +\end{lstcode} +As the file extension, we use ``\File{lor}''. + +With this, the floating environment works. But the content list of +is still missing. So that we do not have to implement it ourselves, we +use the \Package{tocbasic} package. This is loaded with +\begin{lstcode} + \usepackage{tocbasic} +\end{lstcode} +inside of document preambles. Class or package authors would use +\begin{lstcode} + \RequirePackage{tocbasic} +\end{lstcode} +instead. + +Now\textnote{extension} we register the file name extension with the +\Package{tocbasic} package: +\begin{lstcode} + \addtotoclist[float]{lor} +\end{lstcode} +We use \PValue{float} as the owner so that all subsequent \KOMAScript{} +options that relate to lists of floating environments also apply to the new +content list. + +Next\textnote{title} we define a title or heading for this content list: +\begin{lstcode} + \newcommand*{\listoflorname}{List of Remarks} +\end{lstcode} +When working with multiple languages, the normal practice is to define an +English title first and then, for example with the help of the +\Package{scrbase} package, to add titles for all the other languages you want +to support. See \autoref{sec:scrbase.languageSupport}, starting on +\autopageref{sec:scrbase.languageSupport}. + +Now\textnote{entry} all we have to do is define what a single entry in the +content list should look like: +\begin{lstcode} + \newcommand*{\l@remarkbox}{\l@figure} +\end{lstcode} +This specifies that entries in the list of remarks should look exactly like the +entries in the list of figures. This would be the easiest solution. A more +explicit definition would be something like: +\begin{lstcode} + \DeclareTOCStyleEntry[level=1,indent=1em,numwidth=1.5em]% + {tocline}{remarkbox} +\end{lstcode} + +You\textnote{chapter entry} also want chapter entries to affect the content +list. +\begin{lstcode} + \setuptoc{lor}{chapteratlist} +\end{lstcode} +Setting this property allows this when you use a \KOMAScript{} class, and other class +that supports this property. Unfortunately, the standard classes do not. + +This\textnote{list of remarks} should be enough. Users can now +select different kinds of headings using the corresponding options of +the \KOMAScript{} classes or \DescRef{\LabelBase.cmd.setuptoc}, (e.\,g. with +or without an entry in the table of contents, with or without numbering). But +with a simple +\begin{lstcode} + \newcommand*{\listofremarkboxes}{\listoftoc{lor}} +\end{lstcode} +you can simplify the usage even more. + +As you've seen, just five one-line commands, of which only three or four are +really necessary, refer to the content list. Nevertheless, the new list of +remarks already provides the ability to place both numbered and unnumbered +entries into the table of contents.You can use a lower sectioning level for +the headings. Running heads are set for the \KOMAScript{} classes, the +standard classes, and all classes that explicitly support \Package{tocbasic}. +Supporting classes even pay attention to this new list of remarks at each new +\DescRef{maincls.cmd.chapter}. Even changes to the current language made with +\Package{babel} are included in the list of remarks. + +Of course\textnote{additional features}, package authors can add more +features. For example, they could explicitly offer options to hide +\DescRef{\LabelBase.cmd.setuptoc} from users. Or they can refer to the +\Package{tocbasic} manual when explaining the appropriate features. The +advantage of this is that users automatically benefit from any future +extensions to \Package{tocbasic}. However, if you do not want to burden the +user with the fact that the file extension \File{lor} is used for the key +terms, then +\begin{lstcode} + \newcommand*{\setupremarkboxes}{\setuptoc{lor}} +\end{lstcode} +is sufficient to set a list of features passed as an argument to +\Macro{setupremarkboxes} as a list of features for the file extension +\File{lor}. + +\section{Everything with Only One Command} +\label{sec:tocbasic.declarenewtoc} + +The example in the previous section has shows that \Package{tocbasic} makes it +easy to define your own floating environments with their own content lists. +This section shows how it can be even easier. + +\begin{Declaration} + \Macro{DeclareNewTOC}\OParameter{options}\Parameter{extension} +\end{Declaration} +This command declares\ChangedAt{v3.06}{\Package{tocbasic}} a new content list, +its heading, and the description of the entries controlled by +\Package{tocbasic} all in a single step. Optionally, you can also define +floating and non-floating environments at the same time. Inside of both such +environments, \DescRef{maincls.cmd.caption}% +\important{\DescRef{maincls.cmd.caption}}\IndexCmd{caption} creates entries +for this new content list. You can also use the \KOMAScript{} extensions +\DescRef{maincls.cmd.captionabove}\important[i]{% + \DescRef{maincls.cmd.captionabove}\\ + \DescRef{maincls.cmd.captionbelow}}, \DescRef{maincls.cmd.captionbelow}, and +\DescRef{maincls.env.captionbeside} (see \autoref{sec:maincls.floats}). + +The \PName{extension} argument is the file extension of the TOC file that +represents the content list, as explained in \autoref{sec:tocbasic.basics}. +This argument is mandatory and must not be empty! + +The \PName{options} argument is a comma-separated list, of the same type as, +for example, \DescRef{maincls.cmd.KOMAoptions} (see +\autoref{sec:typearea.options}). However\textnote{Attention!}, those options +cannot be set using \DescRef{maincls.cmd.KOMAoptions}\IndexCmd{KOMAoptions}! +You can find an overview of all available options in +\autoref{tab:tocbasic.DeclareNewTOC-options}. + +If\ChangedAt[2015/12]{v3.20}{\Package{tocbasic}} the \Option{tocentrystyle} +option is not used, the \PValue{default} style will be used if required. For +information about this style, see \autoref{sec:tocbasic.tocstyle}. If you do +not want to define a command for entries to the content list, you can use an +empty argument, i.\,e. \OptionValue{tocentrystyle}{} or +\OptionValue{tocentrystyle}{\PParameter{}}. + +Depending\ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}% +\ChangedAt[2016/06]{v3.21}{\Package{tocbasic}} on the style of the entries to +the content list, you can set all valid attributes of the selected style as +part of the \PName{options}. To do so, you must add the prefix +\PValue{tocentry} to the names of the attributes given in +\autoref{tab:tocbasic.tocstyle.attributes}, starting on +\autopageref{tab:tocbasic.tocstyle.attributes}. You can make later changes to +the style of the entries at any time using +\DescRef{\LabelBase.cmd.DeclareTOCStyleEntry}% +\IndexCmd{DeclareTOCStyleEntry}% +\important{\DescRef{\LabelBase.cmd.DeclareTOCStyleEntry}}. See +\autoref{sec:tocbasic.tocstyle}, +\DescPageRef{\LabelBase.cmd.DeclareTOCStyleEntry} for more information about +the styles.% +% +\begin{desclist} + \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% + \desccaption[{Options for command \Macro{DeclareNewTOC}}]{% + Options for the + \Macro{DeclareNewTOC}\ChangedAt{v3.06}{\Package{tocbasic}} command% + \label{tab:tocbasic.DeclareNewTOC-options}% + }{% + Options for the \Macro{DeclareNewTOC} command (\emph{continued})% + }% + \entry{\OptionVName{atbegin}{commands}% + \ChangedAt{v3.09}{\Package{tocbasic}}}{% + The \PName{commands} will be executed at the begin of the floating or + non-floating environment.% + }% + \entry{\OptionVName{atend}{commands}% + \ChangedAt{v3.09}{\Package{tocbasic}}}{% + The \PName{commands} will be executed at the end of the floating or + non-floating environment.% + }% + \entry{\OptionVName{counterwithin}{\LaTeX{} counter}}{% + If you define a new floating or non-floating environment, a new counter + \Counter{\PName{type}} will be created as well (see option + \Option{type}). You can make this counter depenent another \LaTeX{} + counter in the same way, for example, that the \Counter{figure} counter in + the \Class{book} classes is dependent on the \Counter{chapter} counter.% + }% + \entry{\Option{float}}{% + If set, defines a new content list and a floating environment, both named + \PName{type}, and an environment for double-column floats named + \PName{type*}.% + }% + \entry{\OptionVName{floatpos}{float positions}}{% + Each floating environment has default \PName{float positions} that can be + changed through the optional argument of the floating environment. The + syntax and semantics are identical to those of the standard floating + environments. If the option is not used, the default \PName{float + positions} are ``\texttt{tbp}'', that is \emph{top}, \emph{bottom}, + \emph{page}.% + }% + \entry{\OptionVName{floattype}{number}}{% + Each floating environment has a \PName{number}. Floating environments + where only different bits are set can be moved past each other. The + floating environments \Environment{figure} and \Environment{table} usually + have the types 1 and 2, so they can move past each other. The numerical + float type can be between 1 and 31. If common bits are set, the float + types cannot be reordred. If no float type is given, the greatest possible + one-bit type, 16, will be used.% + }% + \entry{\Option{forcenames}}{% + If set, the names will be defined even if they were already defined + before.% + }% + \entry{\OptionVName{hang}{length}}{% + \ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}% + \ChangedAt[2015/12]{v3.21}{\Package{tocbasic}}% + This option has been deprecated since \KOMAScript~3.20. Instead, the + amount of the hanging indent of entries to the content list\index{content + list>entry} depends on attributes of the TOC-entry style given by the + \Option{tocentrystyle} option. The \KOMAScript{} styles provide the + \PValue{numwidth} attribute. If the style used has such an attribute, + \Macro{DeclareNewTOC} will initialise it with a default of 1.5\Unit{em}. + You can easily change the \PName{value} using + \OptionVName{tocentrynumwidth}{value}. The \KOMAScript{} classes, for + example, use \OptionValue{tocentrynumwidth}{2.3em}.% + }% + \entry{\OptionVName{indent}{length}}{% + \ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}% + \ChangedAt[2015/12]{v3.21}{\Package{tocbasic}}% + This option has been deprecated since \KOMAScript~3.20. Instead, the + amount that entries to the content list\index{content list>entry} are + indented depends on attributes of the TOC-entry style given by the + \Option{tocentrystyle} option. The \KOMAScript{} styles provide the + \PValue{indent} attribute. If the style used has such an attribute, + \Macro{DeclareNewTOC} will initialise it with a default of 1\Unit{em}. You + can easily change the \PName{value} using + \OptionVName{tocentryindent}{value}. The \KOMAScript{} classes for example + use \OptionValue{tocentrynumwidth}{1.5em}.% + }% + \entry{\OptionVName{level}{number}}{% + \ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}% + \ChangedAt[2015/12]{v3.21}{\Package{tocbasic}}% + This option has been deprecated since \KOMAScript~3.20. Instead, the level + of the entries to the content list\index{content list>entry} depends on + attributes of the TOC-entry style given by the \Option{tocentrystyle} + option. Nevertheless, all styles have the \PValue{level} attrobite, and + \Macro{DeclareNewTOC} initialises it with a default value of 1. You can + easily change the \PName{value} using \OptionVName{tocentrylevel}{value}.% + }% + \entry{\OptionVName{listname}{title}}{% + Each content list has a heading, or title, that you can specify with this + option. If the option is not specified, the title will be ``List of + \PName{entry type}'' (see the \Option{types} option), with the first + character of the \PName{entry type} changed to upper case. It also defines + the \Macro{list\PName{entry type}name} macro with this value, which you + can change at any time. This macro, however, is only defined if it is not + already defined or if the \Option{forcenames} option is also set.% + }% + \entry{\OptionVName{name}{entry name}}{% + Both the optional prefix for entries in the content list and the labels in + floating or non-floating environments (see the \Option{float} and + \Option{nonfloat} options) require an \PName{entry name} for an entry to + the content list. If no \PName{entry name} is given, the value of the + \PValue{type} (see the \Option{type} option) with the first character + changed to upper case will be used. It also defines a \Macro{\PName{entry + type}name} macro with this value, which you can change at any time. This + macro, however, is only defined if it is not already defined or if the + \Option{forcenames} option is also set.% + }% + \entry{\Option{nonfloat}}{% + If set, defines not only a content list but also a non-floating environment, + \Environment{\PName{entry type}-} (see the \Option{type} option), which can + be used similarly to a floating environment, but which does not move from + the place where it is used.% + }% + \entry{\OptionVName{owner}{string}}{% + Every new content list has an owner in \Package{tocbasic} (see + \autoref{sec:tocbasic.basics}). You can specify this here. If no owner is + specified, the owner ``\PValue{float}'' is used. The \KOMAScript{} classes + use this owner for the list of figures and the list of tables.% + }% + \entry{\OptionVName{setup}{list of attributes}}{% + \ChangedAt{v3.25}{\Package{tocbasic}}% + The \PName{list of attributes} is set with + \DescRef{\LabelBase.cmd.setuptoc}. Note that to specify multiple + attributes in a comma-separated list, you must put this list between + braces.% + }% + \entry{\OptionVName{tocentrystyle}{TOC-entry style}}{% + \ChangedAt{v3.20}{\Package{tocbasic}}% + \PName{TOC-entry style} specifies the style that should be used for all + entries to the content list corresponding to the \PName{extension}. The + name of the entry level is given by the \Option{type} option. In addition + to the options in this table, all attributes of the \PName{TOC-entry + style} can be used as options. To do so, you have to prefix the name of + such an attribute with \PValue{toc}. For example, you can change the + numerical level of the entries using the \Option{tocentrylevel} option. + For more information about the styles and their attributes see + \autoref{sec:tocbasic.tocstyle}, starting on + \autopageref{sec:tocbasic.tocstyle}.% + }% + \entry{\OptionVName{tocentry\PName{style-option}}{value}}{% + \ChangedAt[2015/12]{v3.20}{\Package{tocbasic}}% + Additional options depending on the \PName{TOC-entry style} given by + \Option{tocentrystyle}. See \autoref{sec:tocbasic.tocstyle}, + \autopageref{sec:tocbasic.tocstyle} for additional information about + TOC-entry styles. See \autoref{tab:tocbasic.tocstyle.attributes}, + \autopageref{tab:tocbasic.tocstyle.attributes} for information about the + attributes of the predefined TOC-entry styles of package + \Package{tocbasic} that can be used as \PName{style-option}.% + }% + \entry{\OptionVName{type}{entry type}}{% + Sets the type of the newly declared content list. The \PName{entry type} + is also used as a base name for various macros and possibly environments + and counters. It should therefore consist only of letters. If this option + is not used, the file \PName{extension} from the mandatory argument will + be used as the \PName{entry type}.% + }% + \entry{\OptionVName{types}{string}}{% + In several places, the plural form of the \PName{entry type} is required. + If no plural is given, the value of the \PValue{entry type} with an ``s'' + appended will be used.% + }% + \entry{\OptionVName{unset}{list of attributes}}{% + \ChangedAt{v3.25}{\Package{tocbasic}}% + The \PName{list of attributes} is unset with + \DescRef{\LabelBase.cmd.unsettoc}. Note that to specify a comma-separated + list of attributes, you must put this list between braces.% + }% +\end{desclist} + +\begin{Example} + Using \Macro{DeclareNewTOC} significantly shortens the example from + \autoref{sec:tocbasic.example}: +\begin{lstcode} + \DeclareNewTOC[% + type=remarkbox,% + types=remarkboxes,% + float,% define a floating environment + floattype=4,% + name=Remark,% + listname={List of Remarks}% + ]{lor} + \setuptoc{lor}{chapteratlist} +\end{lstcode} + In addition to the \Environment{remarkbox} and \Environment{remarkbox*} environments, + this also defines the \Counter{remarkbox} counter; the commands \Macro{theremarkbox}, + \Macro{remarkboxname}, and \Macro{remarkboxformat} that are used for + captions; the commands \Macro{listremarkboxnames} and + \Macro{listofremarkboxes} that are used in the list of remarks; and some + internal commands that depend on the file name extension \File{lor}. + If the package should use a default for the floating type, the + Option{floattype} option can be omitted. If the \Option{nonfloat} option is specified, + a non-floating environment, \Environment{remarkbox-}, will + also be defined, inside which you can use \DescRef{maincls.cmd.caption}\IndexCmd{caption}. + \hyperref[tab:tocbasic.comparison]{Figure~\ref*{tab:tocbasic.comparison}} + compares the commands, counters, and environments of the + example \Environment{remarkbox} environment to the commands, counters, + and environments of figures.% + \begin{table} + \centering + \caption{Comparing the example \Environment{remarkbox} environment + with the \Environment{figure} environment} + \label{tab:tocbasic.comparison} + \begin{tabularx}{\textwidth}{ll>{\raggedright}p{6em}X} + \toprule + \Environment{remarkbox} & \Environment{figure} + & options of \Macro{DeclareNewTOC} & short description \\[1ex] + \midrule + \Environment{remarkbox} & \Environment{figure} + & \Option{type}, \Option{float} + & floating environments of the respective types\\[1ex] + \Environment{remarkbox*} & \Environment{figure*} + & \Option{type}, \Option{float} + & columns spanning floating environments of the respective types\\[1ex] + \Counter{remarkbox} & \Counter{figure} + & \Option{type}, \Option{float} + & counter used by \DescRef{maincls.cmd.caption}\\[1ex] + \Macro{theremarkbox} & \Macro{thefigure} + & \Option{type}, \Option{float} + & output command to the respective counters\\[1ex] + \Macro{remarkboxformat} & \DescRef{maincls.cmd.figureformat} + & \Option{type}, \Option{float} + & formatting command to the respective counters used by + \DescRef{maincls.cmd.caption}\\[1ex] + \Macro{remarkboxname} & \Macro{figurename} + & \Option{type}, \Option{float}, \Option{name} + & names used in the label of \DescRef{maincls.cmd.caption}\\[1ex] + \Macro{listofremarkboxes} & \DescRef{maincls.cmd.listoffigures} + & \Option{types}, \Option{float} + & command to show the list of the respective environments\\[1ex] + \Macro{listremarboxname} & \Macro{listfigurename} + & \Option{type}, \Option{float}, \Option{listname} + & heading text of the respective list \\[1ex] + \Macro{fps@remarkbox} & \Macro{fps@figure} + & \Option{type}, \Option{float}, \Option{floattype} + & numeric float type for order perpetuation\\[1ex] + \File{lor} & \File{lof} + & + & file name extension of the TOC file of the respective list \\ + \bottomrule + \end{tabularx} + \end{table} + + And here is a possible use of the example environment: +\begin{lstcode} + \begin{remarkbox} + \centering + The same thing should always be typeset in the same way + and with the same appearance. + \caption{First Law of Typography} + \label{rem:typo1} + \end{remarkbox} +\end{lstcode} + A snippet of a sample page with this environment might look like this: + \begin{center}\footnotesize + \begin{tabular} + {|!{\hspace{.1\linewidth}}p{.55\linewidth}!{\hspace{.1\linewidth}}|} + \\ + \centering + The same thing should always be typeset in the same way + and with the same appearance.\\[\abovecaptionskip] + {% + \usekomafont{caption}\footnotesize{\usekomafont{captionlabel}% + Remark 1: }First Law of Typography + }\\ + \end{tabular}% + \end{center}% +\end{Example} + +Users of \Package{hyperref} should always use the \Option{listname} option. +Otherwise they may get an error message because \Package{hyperref} usually has +a problem with the \Macro{MakeUppercase}\IndexCmd{MakeUppercase} command that +is needed to convert the first letter of \Option{types} to upper case.% +\EndIndexGroup +% +\EndIndexGroup +% +\endinput + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: + + +% LocalWords: Multiline multiline diff --git a/macros/latex/contrib/koma-script/source-doc/english/typearea-experts.tex b/macros/latex/contrib/koma-script/source-doc/english/typearea-experts.tex new file mode 100644 index 0000000000..da2679cc7d --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/typearea-experts.tex @@ -0,0 +1,269 @@ +% ====================================================================== +% typearea-experts.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% typearea-experts.tex +% Copyright (c) Markus Kohm, 2001-2018 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about typearea for experts of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber typearea fuer Experten in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{typearea-experts.tex} + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ + KOMA-Script guide (chapter: typearea)] +\translator{Markus Kohm\and Gernot Hassenpflug\and Karl Hagen} + +% Date of the translated German file: 2018-01-31 + +\chapter{Additional Information about the \Package{typearea} package} +\labelbase{typearea-experts} +\BeginIndexGroup +\BeginIndex{Package}{typearea} + +This chapter provides additional information about the \Package{typearea} +package. \iffree{Some parts of the chapter are found only in the German + \KOMAScript{} book \cite{book:komascript}. This should not be a problem, + because the}{The} average user, who only wants to use the package, will not +normally need this information. Part of this material is intended for users +who want to solve unusual problems or write their own packages using +\Package{typearea}. Another part covers \Package{typearea} features that exist +only for compatibility with earlier versions of \KOMAScript{} or with the +standard classes. The features that exist only for compatibility with earlier +versions of \KOMAScript{} are printed in a sans serif font. You should not use +them any longer. + + +\section{Experimental Features} +\seclabel{experimental} + +This section describes experimental features. Experimental, in this context, +means that correct functioning cannot be guaranteed. There can be two reasons +for designating something experimental. First, the final function is not yet +defined or its implementation is not yet finalised. Second, a feature may +depend on internal functions of other packages and therefore the feature can +not be guaranteed, if the other packages change. + +\begin{Declaration} + \OptionVName{usegeometry}{simple switch} +\end{Declaration} +Usually \Package{typearea} does not care much if you use it with the +\Package{geometry}\IndexPackage{geometry} package (see +\cite{package:geometry}) in any configuration. In particular, this means that +\Package{geometry} does not recognise any changes to the page parameters done +with \Package{typearea}, for example when it changes the paper size\,---\,a +feature not provided by \Package{geometry} itself. + +Once\ChangedAt{v3.17}{\Package{typearea}} you set option \Option{usegeometry}, +\Package{typearea} tries to translate all of its options into options of +\Package{geometry}. If you activate new parameters inside the document, +\Package{typearea} even calls \Macro{newgeometry} (see +\DescRef{\LabelBase.cmd.activateareas} in the following section). Since +\Package{geometry} does not support changes of paper size or page orientation +with \Macro{newgeometry}, \Package{typearea} uses internal commands and +\Package{geometry} lengths to provide such changes as needed. This has been +tested with \Package{geometry}~5.3 through 5.6. + +Note that using \Package{geometry} and changing page size or orientation with +\Package{typearea} does not mean that \Package{geometry} will automatically +use the new paper size in an expected manner. For convenience, +\Package{geometry} provides far more options to adjust the page than are +required to determine the type area, margins, header, footer, etc.\,---\,this +is called \emph{overdetermination}\,---\, and at the same time +\Macro{newgeometry} derives missing information from the known +values\,---\,known as \emph{value preservation}\,---\,so you often must +explicitly specify all new values completely when you call \Macro{newgeometry} +on your own. Nevertheless, when \Package{typearea} takes \Package{geometry} +into consideration, it opens up additional possibilities.% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{areasetadvanced}{simple switch} + \Macro{areaset}\OParameter{BCOR}\Parameter{width}\Parameter{height} +\end{Declaration} +Usually, \DescRef{typearea.cmd.areaset} does not handle options to define the +height of the header or footer, or whether margin elements should count as +part of the type area in the same way as \DescRef{typearea.cmd.typearea}. With +the \Option{areasetadvanced}\ChangedAt{v3.11}{\Package{typearea}} option, you +can make \DescRef{typearea.cmd.areaset} behave more like +\DescRef{typearea.cmd.typearea} in this regard. Nevertheless, settings for the +two commands that result in type areas of equal size still can differ because +\DescRef{typearea.cmd.typearea} always adjusts the type area so that it +contains an integer number of lines, potentially making the bottom margin up +to one line smaller, whereas \DescRef{typearea.cmd.areaset} always sets the +ratio between the top and bottom margins at 1:2. The type area can therefore +be slightly shifted vertically depending on which command was used.% +\EndIndexGroup + + +\section{Expert Commands} +\seclabel{experts} + +This section describes commands that are of little or no interest to average +users. These commands give experts additional possibilities. Because this +information is addressed to experts, it appears in condensed form. + +\begin{Declaration} + \Macro{activateareas} +\end{Declaration}% +The \Package{typearea} package uses this command convert the settings for the +type area and margins to internal \LaTeX{} lengths whenever the type area has +been recalculated inside of the document, that is after +\Macro{begin}\PParameter{document}. If the \DescRef{typearea.option.pagesize} +option has been used, it will be executed again with the same value. Thus, for +example, the page size may actually vary within PDF documents. + +Experts can also use this command if they have manually changed lengths like +\Length{textwidth} or \Length{textheight} inside a document for any reason. If +you do so, however, you are responsible for any necessary page breaks before +or after you call \Macro{activateareas}. Moreover, all changes made by +\Macro{activateareas} are local.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{storeareas}\Parameter{\textMacro{command}}% + \Macro{BeforeRestoreareas}\Parameter{code}% + \Macro{BeforeRestoreareas*}\Parameter{code}% + \Macro{AfterRestoreareas}\Parameter{code}% + \Macro{AfterRestoreareas*}\Parameter{code} +\end{Declaration} +\Macro{storeareas} defines a \PName{\Macro{command}} which you can use to +restore all current type-area settings. So you can save the current settings, +change them, and then restore the previous settings afterwards. + +\begin{Example} + You want a landscape page inside a document with portrait format. That's + no problem using \Macro{storeareas}: +\begin{lstcode} + \documentclass[pagesize]{scrartcl} + + \begin{document} + \noindent\rule{\textwidth}{\textheight} + + \storeareas\MySavedValues + \KOMAoptions{paper=landscape,DIV=current} + \noindent\rule{\textwidth}{\textheight} + + \clearpage + \MySavedValues + \noindent\rule{\textwidth}{\textheight} + \end{document} +\end{lstcode} + It's\textnote{Attention} important to call \DescRef{maincls.cmd.clearpage} + before \Macro{MySavedValues} so that the saved values are restored on the + next page. With two-sided documents, changes to the paper format should even + use \DescRef{maincls.cmd.cleardoubleoddpage}\IndexCmd{cleardoubleoddpage} + or\,---\,if you are not using a \KOMAScript{} + class\,---\,\DescRef{maincls.cmd.cleardoublepage}% + \IndexCmd{cleardoublepage}.% + \iffree{\par In addition, \Macro{noindent} is used to avoid paragraph + indents of the black boxes. Otherwise, you would not produce a correct + image of the type area.}{}% +\end{Example} + +Note\textnote{Attention!} that neither \Macro{storeareas} nor the defined +\PName{\Macro{command}} defined with it should be used inside a group. +Internally, +\Macro{newcommand}\IndexCmd{newcommand*}\important{\Macro{newcommand*}} is +used to define the \PName{\Macro{command}}. So reusing a +\PName{\Macro{command}} to store settings again would result in a +corresponding error message. + +Often\ChangedAt{v3.18}{\Package{typearea}}, it is useful to automatically +execute commands like \DescRef{maincls.cmd.cleardoubleoddpage} before +restoring the settings of a \Macro{command} generated by \Macro{storeareas}. +You can do so using \Macro{BeforeRestoreareas} or \Macro{BeforeRestoreareas*}. +Similarly, you can use \Macro{AfterRestoreareas} or \Macro{AfterRestoreareas*} +to automatically execute \PName{code} after restoring the settings. The +variants with and without the star differ in that the starred variant only +applies the \PName{code} to future \PName{command}s generated by +\Macro{storeareas}, whereas the regular variant also adds the \PName{code} to +previously defined \PName{command}s.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{AfterCalculatingTypearea}\Parameter{code}% + \Macro{AfterCalculatingTypearea*}\Parameter{code}% + \Macro{AfterSettingArea}\Parameter{cod}% + \Macro{AfterSettingArea*}\Parameter{code} +\end{Declaration}% +These commands serve to manage two hooks\Index{hook}. The first two, +\Macro{AfterCalculatingTypearea} and its starred variant let experts execute +\PName{code} each time \Package{typearea} recalculates the type area and +margins, that is after every implicitly or explicit invocation of +\DescRef{typearea.cmd.typearea}. Similarly, +\Macro{AfterSettingArea}\ChangedAt{v3.11}{\Package{typearea}} and its starred +variant allow for executing \PName{code} every time +\DescRef{typearea.cmd.areaset} has been used. The normal versions have a +global scope, while changes made in the starred versions are only local. The +\PName{code} is executed immediately before \Macro{activateareas}.\iffree{}{ + In \autoref{cha:modernletters}, The letter-class-option file + \File{asymTypB.lco} uses it to change the distribution of the margins.}% +% +\EndIndexGroup + + +\section{Local Settings with the \File{typearea.cfg} File} +\seclabel{cfg} +\BeginIndexGroup +\BeginIndex{File}{typearea.cfg} + +\LoadNonFree{typearea-experts}{0} +% +\EndIndexGroup + +\section{More or Less Obsolete Options and Commands} +\seclabel{obsolete} +\LoadNonFree{typearea-experts}{1} +% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% ispell-local-dictionary: "english" +%%% coding: us-ascii +%%% TeX-master: "../guide" +%%% End: diff --git a/macros/latex/contrib/koma-script/source-doc/english/typearea.tex b/macros/latex/contrib/koma-script/source-doc/english/typearea.tex new file mode 100644 index 0000000000..1985498be3 --- /dev/null +++ b/macros/latex/contrib/koma-script/source-doc/english/typearea.tex @@ -0,0 +1,1807 @@ +% ====================================================================== +% typearea.tex +% Copyright (c) Markus Kohm, 2001-2019 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% typearea.tex +% Copyright (c) Markus Kohm, 2001-2019 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about typearea of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber typearea in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\KOMAProvidesFile{typearea.tex}% + [$Date: 2019-01-15 08:29:44 +0100 (Tue, 15 Jan 2019) $ + KOMA-Script guide (chapter: typearea)] +\translator{Markus Kohm\and Gernot Hassenpflug\and Krickette Murabayashi\and + Karl Hagen} + +% Date of the translated German file: 2018-01-31 + +\chapter{Calculating the Page Layout with \Package{typearea}} +\labelbase{typearea} + +\BeginIndexGroup% +\BeginIndex{Package}{typearea}% +Many {\LaTeX} classes\iffree{, including the standard classes,}{} present the +user with a largely fixed configuration of margins and page layout. In the +standard classes, the choice is limited to selecting a font size. +There are separate packages, such as \Package{geometry}\IndexPackage{geometry} +(see \cite{package:geometry}), which give the user complete control over, but +also full responsibility for, setting the type area and margins. + +\KOMAScript{} takes a somewhat different approach with the \Package{typearea} +package. Users are offered ways to adjust the design and algorithms based on +established typographic standards, making it easier for them to make good +choices. + +\iffalse% Umbruchoptimierung!!! + Note that the \Package{typearea} package makes use of the \Package{scrbase} + package. The latter is explained in the expert section of this + \iffree{guide}{book} in \autoref{cha:scrbase} on \autopageref{cha:scrbase}. + However, most of the features documented there are directed not to users but + to class and package authors. +\fi + +\section{Fundamentals of Page Layout} +\seclabel{basics} + +\begin{Explain} + At first glance, a single page of a book or other printed material + consists of the margins, + \iffalse% Umbruchkorrekturtext + \footnote{The author and the editor have considered the question as to + whether, since a page has only one periphery, the term should be + ``the margin.'' However, since \LaTeX{} logically divides this one + margin into several margins, which are determined separately, we + use the term ``the margins'' here.}% + \fi% + a header, a body of text, and a footer. More precisely, there + is also a space between the header area and the text + body, as well as between the body and the footer. The text body is + called, in the jargon of typographers and typesetters, the \emph{type area}. + The division of these areas, as well as their relations to each other and + to the paper, is called the \emph{page layout}.\Index[indexmain]{page layout} + + Various algorithms and heuristic methods for constructing an appropriate + type area have been discussed in the literature% + \iffree{ \cite{DANTE:TK0402:MJK}}{. A short introduction to the basics may + be found at \autoref{cha:typeareaconstruction}}. + These rules are known as the ``canons of page construction.'' One approach + often mentioned involves diagonals and their intersections. The result is + that the aspect ratio of the type area corresponds to the proportions of the + \emph{page}. In a one-sided document,\Index{one-sided} the left and right + margins should have equal widths, while the ratio of the top and bottom + margins should be 1:2. In a two-sided document\Index{two-sided} (e.\,g. a + book), however, the entire inner margin (the margin at the spine) should be + the same size as each of the two outer margins; in other words, a single + page contributes only half of the inner margin. + + In the previous paragraph, we mentioned and emphasised \emph{the page}. It + is often mistakenly thought that the format of the page is the same as the + format of the paper.\Index[indexmain]{page>format}% + \Index[indexmain]{paper>format} However, if you look at + a bound document, you can see that part of the paper disappears in the + binding\Index[indexmain]{binding} and is no longer part of the visible page. + For the type area, however, it is not the format of the paper which is + important; it is the impression of the visible page to the reader. Thus, it + is clear that the calculation of the type area must account for the ``lost'' + paper in the binding and add this amount to the width of the inner margin. + This is called the \emph{binding correction}.\Index[indexmain]{binding + correction} The binding correction is therefore calculated as part of the + \emph{gutter}\Index[indexmain]{gutter} but not the visible inner margin. + + The binding correction depends on the production process and cannot be + defined in general terms. It is therefore a parameter that must be redefined + for each project. In professional printing, this value plays only a minor + role, since printing is done on larger sheets of paper and then cropped to + the right size. The cropping is done so that the above relations for the + visible, two-sided page are maintained. + + So now we know how the individual parts of a page relate to each other. + However, we do not yet know how wide and high the type area is. Once we know + one of these two dimensions, we can calculate all the other dimensions from + the paper format and the page format or the binding correction. + \begin{align*} + \Var{type~area~height}\Index{type area} : \Var{type~area~width} &= + \Var{page~height}\Index{page} : \Var{page~width}\\ + \Var{top~margin}\Index{margin} : \Var{footer~margin} &= + \text{1} : \text{2} \\ +% + \Var{left~margin} : \Var{right~margin} &= \text{1} : \text{1} \\ +% + \Var{half~inner~margin} : \Var{outer~margin} &= \text{1} : \text{2} \\ +% + \Var{page~width} &= + \Var{paper~width}\Index{paper} - + \Var{binding~correction}\Index{binding correction}\\ +% + \Var{top~margin} + \Var{bottom~margin} &= + \Var{page~height} - \Var{type~area~height} \\ +% + \Var{left~margin} + \Var{right~margin} &= + \Var{page~width} - \Var{type~area~width} \\ +% + \Var{half~inner~margin} + \Var{outer~margin} &= + \Var{page~width} - \Var{type~area~width} \\ +% + \Var{half~inner~margin} + \Var{binding~correction} &= + \Var{gutter}\Index{gutter} + \end{align*} + \Index[indexmain]{margin}% + The values \Var{left~margin} and \Var{right~margin} only exist in a + one-sided document while \Var{half~inner~margin} and \Var{outer~margin} only + exist in a two-sided document. We use \Var{half~inner~margin} in these + equations, since the full inner margin is an element of the whole two-page + spread. Thus, only half of the inner margin, \Var{half~inner~margin}, + belongs to a single page. + + The question of the width of the type area is also discussed in the + literature. The optimum width depends on several factors: + \begin{itemize} + \item the size, width, and type of font used, + \item the line spacing, + \item the word length, + \item the available space. + \end{itemize} + The importance of the font becomes clear once you realize what serifs are + for. Serifs\Index[indexmain]{serifs} are small strokes that finish off the + lines of letters. Letters with vertical lines touching the text baseline + disturb the flow rather than keeping the eye on the line. It is precisely + with these letters that the serifs lie horizontally on the baseline and thus + enhance the horizontal effect of the font. The eye can better follow the + line of text, not only when reading the words but also when jumping back to + the beginning of the next line. Thus, the line length can actually be + slightly longer for a serif font than for a sans serif font. + + Leading\Index[indexmain]{leading}\textnote{leading} refers to the vertical + distance between individual lines of text. In \LaTeX{}, the leading is set + at about 20\% of the font size. With commands like + \Macro{linespread}\IndexCmd{linespread}, or better, packages like + \Package{setspace}\IndexPackage{setspace} (see \cite{package:setspace}), you + can change the leading. A wider leading makes it easy for the eye to follow + the line. A very wide leading, however, disturbs reading because the eye has + to travel long distances between the lines. In addition, the reader becomes + uncomfortable because of the visible striped effect. The uniform grey value + of the page is thereby spoiled. Nevertheless, the lines can be longer with a + wider leading. + + The literature gives different values for good line + lengths\Index[indexmain]{line length}, depending on the author. To some + extent, this is related to the author's native language. Since the eye + usually jumps from word to word, short words make this task easier. Across + all languages and fonts, a line length of 60 to 70 characters, including + spaces and punctuation, forms a usable compromise. This requires well-chosen + leading, but {\LaTeX}'s default is usually good enough. Longer line lengths + should only be considered for highly-developed readers who spend many hours + a day reading. But even then, line lengths beyond 80 characters are + unacceptable. In each case, the leading must be appropriately chosen. An + extra 5\% to 10\% is recommended as a good rule of thumb. For typefaces like + Palatino, which require more than 5\% leading for normal line lengths, even + more can be required. + + Before looking at the actual construction of the page layout, there are a + few minor points you should know. {\LaTeX} does not start the first line in + the text area of a page at the upper edge of the text area but sets the + baseline at a defined distance from the top of the text area. Also, {\LaTeX} + recognizes the commands + \DescRef{maincls.cmd.raggedbottom}\IndexCmd{raggedbottom} and + \DescRef{maincls.cmd.flushbottom}\IndexCmd{flushbottom}. + \DescRef{maincls.cmd.raggedbottom} specifies that the last line of a page + should be positioned wherever it was calculated. This means that the + position of this line can be different on each page, up to the height of one + line\,---\, even more when the end of the page coincides with headings, + figures, tables, or the like. In two-sided documents that is usually + undesirable. The second command, \DescRef{maincls.cmd.flushbottom}, makes + sure that the last line is always at the lower edge of the text area. To + achieve this vertical compensation, {\LaTeX} may have to stretch vertical + glue beyond what is normally allowed. Paragraph skip is such a stretchable, + vertical glue, even when set to zero. To avoid stretching on normal pages + where paragraph spacing is the only stretchable glue, the height of the text + area should be a multiple of the height of the text line, including the + distance of the first line from the top of the text area. + +\iffalse% Umbruchkorrektur + This explains all the basics of the type area calculation that play a role + in {\KOMAScript}. +\else + This concludes the fundamentals. +\fi +\iffalse% Umbruchkorrektur + Below are two methods of construction offered by \KOMAScript{}. +\else +\iffalse% Umbruchkorrektur + Now, we can begin with the actual construction. +\else + In the following two sections, the methods of construction offered by + {\KOMAScript} are presented in detail. +\fi +\fi +\end{Explain} + + +\section{Constructing the Type Area by Division} +\seclabel{divConstruction} + +\begin{Explain} + The easiest way to make sure that the text area has the same ratio as the + page is as follows: + \begin{itemize} + \item First, subtract the \Var{BCOR} required for the binding + correction\Index{binding correction} from the inner edge of the paper, and + divide the rest of the page vertically into \Var{DIV} rows of equal + height. + \item Next, divide the page horizontally into the same number (\Var{DIV}) of + columns of equal width. + \item Then, take the uppermost row as the upper margin and the two lowermost + rows as the lower margin. If you are printing two-sided, you similarly + take the innermost column as the inner margin and the two outermost + columns as the outer margin. + \item Then add the binding correction \Var{BCOR} to the inner margin. + \end{itemize} + What remains within the page is the text area.\Index{text area} The width + and height of the text area and margins result automatically from the + number of rows and columns, \Var{DIV}. Since the margins always need three + stripes, \Var{DIV} must be greater than three. In order that the + text area occupy at least twice as much space as the margins, \Var{DIV} + should really be at least nine. With this value, the design + is also known as the \emph{classical nine-part division} (see + \autoref{fig:typearea.nineparts}). + + \begin{figure} +% \centering + \KOMAoption{captions}{bottombeside}% + \setcapindent{0pt}% + \setlength{\columnsep}{.6em}% + \begin{captionbeside}[{% + Two-sided layout with the box construction of the classical + nine-part division, after subtracting a binding correction% + }]{% + \label{fig:typearea.nineparts}% + \hspace{0pt plus 1ex}% + Two-sided layout with the box construction of the classical + nine-part division, after subtracting a binding correction% + } + [l] + \setlength{\unitlength}{.25mm}% + \definecolor{komalight}{gray}{.75}% + \definecolor{komamed}{gray}{.6}% + \definecolor{komadark}{gray}{.3}% + \begin{picture}(420,297) + % BCOR + \put(198,0){\color{komalight}\rule{24\unitlength}{297\unitlength}} + \multiput(198,2)(0,20){15}{\thinlines\line(0,1){10}} + \multiput(222,2)(0,20){15}{\thinlines\line(0,1){10}} + % the paper + \put(0,0){\thicklines\framebox(420,297){}} +% \put(210,0){\thicklines\framebox(210,297){}} + % the page layout + \put(44,66){\color{komamed}\rule{132\unitlength}{198\unitlength}} + \put(244,66){\color{komamed}\rule{132\unitlength}{198\unitlength}} + % helper lines + \multiput(0,33)(0,33){8}{\thinlines\line(1,0){198}} + \multiput(222,33)(0,33){8}{\thinlines\line(1,0){198}} + \multiput(22,0)(22,0){8}{\thinlines\line(0,1){297}} + \multiput(244,0)(22,0){8}{\thinlines\line(0,1){297}} + % annotations + \put(198,0){\color{white}\makebox(24,297)[c]{% + \rotatebox[origin=c]{-90}{binding correction}}} + \put(44,66){\color{white}\makebox(132,198)[c]{page layout left}} + \put(244,66){\color{white}\makebox(132,198)[c]{page layout right}} + % box numbers + \makeatletter + \multiput(1,27)(0,33){9}{\footnotesize\makebox(0,0)[l]{\the\@multicnt}} + \multiput(177,291)(-22,0){9}{% + \footnotesize\makebox(0,0)[l]{\the\@multicnt}} + \multiput(419,27)(0,33){9}{% + \footnotesize\makebox(0,0)[r]{\the\@multicnt}} + \multiput(243,291)(22,0){8}{% + \footnotesize\makebox(0,0)[r]{\the\numexpr\@multicnt+1\relax}} + \makeatother + \end{picture} + \end{captionbeside} +% \caption{Two-sided layout with the box construction of the classical +% nine-part division, after subtracting a binding correction} +% \label{fig:typearea.nineparts} + \end{figure} + + In {\KOMAScript}, this kind of design is implemented with the + \Package{typearea} package, where the bottom margin may drop any fractions + of a line in order to comply with the constraint for the height of the type + area mentioned in the previous paragraph and thereby reduce the problem + mentioned with \Macro{flushbottom}. For A4 paper, \Var{DIV} is predefined + according to the font size (see \autoref{tab:typearea.div}, + \autopageref{tab:typearea.div}). If there is no binding correction + (\(\Var{BCOR} = 0\Unit{pt}\)), the results roughly match the values of + \autoref{tab:typearea.typearea}, \autopageref{tab:typearea.typearea}. + + In addition to the predefined values, you can specify \Var{BCOR} and + \Var{DIV} as options when loading the package (see + \autoref{sec:typearea.options}, starting on + \autopageref{sec:typearea.typearea}). There is also a command to calculate + the type area explicitly by providing these values as parameters (see also + \autoref{sec:typearea.options}, \DescPageRef{typearea.cmd.typearea}). + + The \Package{typearea} package can automatically determine the optimal value + of \Var{DIV} for the font and leading used. Again, see + \autoref{sec:typearea.options}, \DescPageRef{typearea.option.DIV.calc}. +\end{Explain} + + +\section{Constructing the Type Area by Describing a Circle} +\seclabel{circleConstruction} + +\begin{Explain} + In addition to the construction method for the type area\Index{type area} + described above, there is an even more traditional, or even medieval, method + found in the literature. The aim of this method is not just to have the same + ratios between page size and type area; it is considered optimal when the + height of the text area corresponds to the width of the page. This means + that a circle can be drawn that will touch both the sides of the page and + the top and bottom of the text area. The exact procedure can be found in + \cite{JTsch87}. + + A disadvantage of this late-medieval canon of page construction is that the + width of the text area no longer depends on the font. One no longer chooses + the text area to match the font. Instead, the author or typesetter must + choose the appropriate font for the text area. +% +\iftrue +% Umbruchkorrekturtext + This should be considered mandatory. +\fi + + In the \Package{typearea} package, this construction is modified to + determine the \Var{DIV} value by selecting a special (normally meaningless) + \Var{DIV} value or a special, symbolic indication of the \Var{DIV} value so + that the resulting type area comes as close as possible to the late-medieval + page canon. Hence it relies in turn on the method of constructing the type + area by division. +% +\iffalse +% Umbruchkorrekturtext + If you choose a good font, the result often coincides with the search for + the optimal \Var{DIV} value. See also \autoref{sec:typearea.options}, + \DescPageRef{typearea.option.DIV.calc}. +% +\fi +\end{Explain} + +\LoadCommonFile{options}% \section{Early or late Selection of Options} + +\LoadCommonFile{compatibility}% \section{Compatibility with Earlier Versions of \KOMAScript} + +\section{Adjusting the Type Area and Page Layout} +\seclabel{typearea} + +The \Package{typearea} package offers two different user interfaces to +influence the construction of the type area. The most important method is to +specify options when loading the package. For information on how to load +packages and pass options to packages, please refer to the {\LaTeX} +literature, for example \cite{lshort} and \cite{latex:usrguide}, or the +examples given here. Since the \Package{typearea} package is loaded +automatically when using the main {\KOMAScript} classes, the package options +can be given as class options (see \autoref{sec:maincls.options}). + +In\textnote{Note!} this section the classes used in the examples are not +existing {\KOMAScript} classes but hypothetical ones. This +\iffree{guide}{book} assumes that ideally an appropriate class is available +for each task. + +\begin{Declaration} + \OptionVName{BCOR}{correction} +\end{Declaration}% +Use the \OptionVName{BCOR}{correction}\ChangedAt{v3.00}{\Package{typearea}} +option to specify the absolute value of the binding correction\Index{binding + correction}\textnote{binding correction}, i.\,e. the width of the area lost +from the paper during the binding process. This value is then automatically +taken into account when constructing the page layout and is added back to the +inner (or left) margin during output. In the value of the \PName{correction}, +you can specify any measurement unit understood by \TeX{}. + +\begin{Example} + Suppose you create a financial report. The whole thing should be printed out + one-sided on A4 paper and then stapled in a binder folder. The clip of the + folder covers 7.5\Unit{mm}. The stack of pages is very thin, so at most + another 0.75\Unit{mm} will be lost from bending and the sheets themselves. + Therefore, you can write: +\begin{lstcode} + \documentclass[a4paper]{report} + \usepackage[BCOR=8.25mm]{typearea} +\end{lstcode} + with \OptionValue{BCOR}{8.25mm} as an option to \Package{typearea} or +\begin{lstcode} + \documentclass[a4paper,BCOR=8.25mm]{report} + \usepackage{typearea} +\end{lstcode} + when using \OptionValue{BCOR}{8.25mm} as a global option. + + When using a {\KOMAScript} class, you do not need to load the + \Package{typearea} package explicitly: +\begin{lstcode} + \documentclass[BCOR=8.25mm]{scrreprt} +\end{lstcode} + You can omit the \Option{a4paper} option with \Class{scrreprt}, since this + is the default for all {\KOMAScript} classes. + + If you want to set the option to a new value later, you can, for example, + use the following: +\begin{lstcode} + \documentclass{scrreprt} + \KOMAoptions{BCOR=8.25mm} +\end{lstcode} + Defaults are initialized when the \Class{scrreprt} class is loaded. + Changing a setting with the \DescRef{\LabelBase.cmd.KOMAoptions} or + \DescRef{\LabelBase.cmd.KOMAoption} commands will automatically calculate a + new type area with new margins. +\end{Example} + +Note\textnote{Attention!} you must pass this option as a class option when +loading one of the {\KOMAScript} classes, as in the example above, or via +\DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption} +after loading the class. When you use a {\KOMAScript} class, you should not +load the \Package{typearea} package explicitly with +\DescRef{\LabelBase.cmd.usepackage}, nor should you specify it as an optional +argument when loading the package if you are using another class. If the +option is changed with \DescRef{\LabelBase.cmd.KOMAoptions} or +\DescRef{\LabelBase.cmd.KOMAoption} after loading the package, the type area +and margins are automatically recalculated.% +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{DIV}{factor} +\end{Declaration}% +The \OptionVName{DIV}{factor}\ChangedAt{v3.00}{\Package{typearea}} option +specifies the number of strips into which the page is divided horizontally and +vertically during the construction of the type area. The exact construction +method is found in \autoref{sec:typearea.divConstruction}. It's important to +realise that the larger the \PName{factor}, the larger the text block and the +smaller the margins. Any integer value greater than 4 is valid for +\PName{factor}. Note, however, that large values can cause violations in the +constraints on the margins of the type area, depending on how you set other +options. In extreme cases, the header may fall outside of the page. When you +use the \OptionVName{DIV}{factor} option, you are responsible for complying +with the margin constraints and for choosing a typographically pleasing line +length. + +In \autoref{tab:typearea.typearea}, you will find the sizes of the type areas +for several \Var{DIV} factors for the A4 page with no binding correction. In +this case, the other constraints that are dependent on the font size are not +taken into account. + +\begin{table} +% \centering + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% + \begin{captionbeside} +% \caption + [{Type area dimensions dependent on \Var{DIV} for A4}] + {\label{tab:typearea.typearea}Type area dimensions dependent on \Var{DIV} + for A4 regardless of \Length{topskip} or \Var{BCOR}} + [l] + \begin{tabular}[t]{ccccc} + \toprule + & + \multicolumn{2}{c}{Type area} & \multicolumn{2}{c}{Margins}\\ + %\raisebox{1.5ex}[0pt]{ + \Var{DIV} + %} + & width & height & top & inner \\ + \midrule + 6 & 105.00 & 148.50 & 49.50 & 35.00 \\ + 7 & 120.00 & 169.71 & 42.43 & 30.00 \\ + 8 & 131.25 & 185.63 & 37.13 & 26.25 \\ + 9 & 140.00 & 198.00 & 33.00 & 23.33 \\ + 10 & 147.00 & 207.90 & 29.70 & 21.00 \\ + 11 & 152.73 & 216.00 & 27.00 & 19.09 \\ + 12 & 157.50 & 222.75 & 24.75 & 17.50 \\ + 13 & 161.54 & 228.46 & 22.85 & 16.15 \\ + 14 & 165.00 & 233.36 & 21.21 & 15.00 \\ + 15 & 168.00 & 237.60 & 19.80 & 14.00 \\ + \bottomrule + \multicolumn{5}{r}{\small (all lengths in mm)} + \end{tabular} + \end{captionbeside} +\end{table} + + +\begin{Example} + Suppose you are writing up the minutes of a meeting using the + \Class{minutes} class. The whole thing should be two-sided. Your company + uses 12\Unit{pt} Bookman font. This font, which is one of the standard + PostScript fonts, is enabled in {\LaTeX} with the command + \verb|\usepackage{bookman}|. Bookman is a very wide font, meaning that the + individual characters are relatively wide compared to their height. + Therefore, the default setting for \Var{DIV} in \Package{typearea} is too + small. After thoroughly studying this entire chapter, you conclude that a + value of 15, instead of 12, is most suitable. The minutes will not be bound + but punched and kept in a folder, and thus no binding correction is + necessary. So you write: +\begin{lstcode} + \documentclass[a4paper,twoside]{minutes} + \usepackage{bookman} + \usepackage[DIV=15]{typearea} +\end{lstcode} + When you're done, you become aware that the minutes will from now on be + collected and bound together as a book at the end of the quarter. The + binding is to be a simple glue binding because this is only being done to + conform to ISO\,9000 and nobody is actually going to read them. The binding, + including space lost in folding the pages, requires an average of + 12\Unit{mm} You change the options of the \Package{typearea} package + accordingly and use the class for minutes that conform to ISO\,9000 + regulations: +\begin{lstcode} + \documentclass[a4paper,twoside]{iso9000p} + \usepackage{bookman} + \usepackage[DIV=15,BCOR=12mm]{typearea} +\end{lstcode} + Of course, it is equally possible to use a {\KOMAScript} class here: +\begin{lstcode} + \documentclass[twoside,DIV=15,BCOR=12mm]{scrartcl} + \usepackage{bookman} +\end{lstcode} + The \Option{a4paper} option can be left out when using the + \Class{scrartcl} class, as it is predefined in all {\KOMAScript} + classes. +\end{Example} + +Note\textnote{Attention!} that when using this option with one of the +{\KOMAScript} classes, as in the example above, it must be passed either as a +class option, or via \DescRef{\LabelBase.cmd.KOMAoptions} or +\DescRef{\LabelBase.cmd.KOMAoption} after loading the class. When using a +{\KOMAScript} class, the \Package{typearea} package should not be loaded +explicitly with \DescRef{\LabelBase.cmd.usepackage}, nor should the option be +given as an optional argument thereto. If the option is changed via +\DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption} +after loading the package, the type area and margins are automatically +recalculated.% +\EndIndexGroup + +\begin{Declaration} + \OptionValue{DIV}{calc}% + \OptionValue{DIV}{classic} +\end{Declaration}% +As\ChangedAt{v3.00}{\Package{typearea}} already mentioned in +\autoref{sec:typearea.divConstruction}, there are fixed defaults for +\Var{DIV} when using A4 paper. These can be found in \autoref{tab:typearea.div}. +However, such fixed values have the disadvantage that they do not take into +account the letter spacing of the font used. With A4 and fairly narrow fonts, +this can quickly lead to an unpleasantly high number of characters per line. +See the considerations in \autoref{sec:typearea.basics}. If you choose a +different paper size, \Package{typearea} will calculate an appropriate +\Var{DIV} value for you. Of course, you can also apply this same calculation +to A4. To do so, simply use \OptionValue{DIV}{calc}% +\important{\OptionValue{DIV}{calc}} in place of +\OptionVNameRef{\LabelBase}{DIV}{factor}. Of course, you can also specify this +option explicitly for all other paper sizes. If you want automatic +calculation, this specification is useful, as it is possible to set different +preferences in a configuration file (see \autoref{sec:typearea-experts.cfg}). +Explicitly specifying the \OptionValue{DIV}{calc} option overrides such +configuration settings. + +\begin{table} +% \centering + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% + \begin{captionbeside} + %\caption + [{\PName{DIV} defaults for A4}] + {\label{tab:typearea.div}\PName{DIV} defaults for A4} + [l] + \begin{tabular}[t]{lccc} + \toprule + base font size: & 10\Unit{pt} & 11\Unit{pt} & 12\Unit{pt} \\ + \Var{DIV}: & 8 & 10 & 12 \\ + \bottomrule + \end{tabular} + \end{captionbeside} +\end{table} + +You can also select the traditional page layout mentioned in +\autoref{sec:typearea.circleConstruction}, the medieval page canon. Instead of +the \OptionVName{\DescRef{\LabelBase.option.DIV}}{factor} or +\OptionValue{DIV}{calc} option, simply use the \OptionValue{DIV}{classic} +option. A \Var{DIV} value which is as close as possible to the medieval page +canon is then chosen. + +\begin{Example} + In the example using the Bookman font and the + \OptionVNameRef{\LabelBase}{DIV}{factor} option, the problem was to select a + \Var{DIV} value that better matched the font. Modifying that example, you + can simply leave the calculation of this value to \Package{typearea}: +\begin{lstcode} + \documentclass[a4paper,twoside]{protocol} + \usepackage{bookman} + \usepackage[DIV=calc]{typearea} +\end{lstcode} +\end{Example} +\iffree{\par% + Note\textnote{Attention!} that when using this option with one of the + \KOMAScript{} classes% + \iftrue , as in the example above, \fi% + it must be passed either as a class option, or via + \DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption} + after loading the class. When using a {\KOMAScript} class, the + \Package{typearea} package should not be loaded explicitly with + \DescRef{\LabelBase.cmd.usepackage}, nor should the option be given as an + optional argument. If the option is changed via + \DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption} + after loading the package, the type area and margins are automatically + recalculated.% +}{% +\vskip-\dp\strutbox% Wegen Code im Beispiel am Ende +}% +% +\EndIndexGroup + + +\begin{Declaration} + \OptionValue{DIV}{current} + \OptionValue{DIV}{last} +\end{Declaration}% +If\ChangedAt{v3.00}{\Package{typearea}} you've been following the +examples closely, you already know how to calculate a \Var{DIV} value +based on the font you chose when using a {\KOMAScript} class together +with a font package. + +\begin{Explain} + The difficulty with doing so is that the {\KOMAScript} class already loads + the \Package{typearea} package itself. Thus, it is not possible to pass + options as optional arguments to \DescRef{\LabelBase.cmd.usepackage}. It + would also be pointless to specify the \OptionValueRef{\LabelBase}{DIV}{calc} + option as an optional argument to \DescRef{\LabelBase.cmd.documentclass}. + This option would be evaluated immediately on loading the \Package{typearea} + package and as a result the type area and margins would be calculated for the + standard {\LaTeX} font and not for the font loaded later. + + However, it is possible to recalculate the type area and margins after + loading the font with the aid of \DescRef{\LabelBase.cmd.KOMAoptions}% + \PParameter{\OptionValueRef{\LabelBase}{DIV}{calc}} or + \DescRef{\LabelBase.cmd.KOMAoption}% + \PParameter{\DescRef{\LabelBase.option.DIV}}\PParameter{calc}. The option + \PValue{calc} will then request a \Var{DIV} value for an appropriate line + length. + + As it is often more convenient to set the \Option{DIV} option not after + loading the font but at a more noticeable point, such as when loading the + class, the \Package{typearea} package offers two further symbolic values for + this option. +\end{Explain} + +The option \OptionVName{DIV}{current}\ChangedAt{v3.00}{\Package{typearea}} +recalculates the type area and margins using the current \Var{DIV} value. +This is less important for recalculating the type area after loading a +different font. Instead, it is useful if, for example, you change the +leading while keeping \Var{DIV} the same and want to ensure the +margin constraint that \Length{textheight} minus \Length{topskip} is a +multiple of \Length{baselineskip}. + +The option \OptionVName{DIV}{last}\ChangedAt{v3.00}{\Package{typearea}} will +recalculate the type area and margins using exactly the same settings as the +last calculation. + +\begin{Example} + Let's suppose again that we need to calculate an appropriate line length for + a type area using the Bookman font. At the same time, a {\KOMAScript} class + is used. This is very easy with the symbolic value \PValue{last} and the + command \DescRef{\LabelBase.cmd.KOMAoptions}: +\begin{lstcode} + \documentclass[BCOR=12mm,DIV=calc,twoside]{scrartcl} + \usepackage{bookman} + \KOMAoptions{DIV=last} +\end{lstcode} +If you decide later that you need a different \Var{DIV} value, just change the +setting of the optional argument to \DescRef{\LabelBase.cmd.documentclass}. +\end{Example} + +For a summary of all possible symbolic values for the \Option{DIV} option, see +\autoref{tab:symbolicDIV}. Note that the use of the +\Package{fontenc}\IndexPackage{fontenc} package may also cause \LaTeX{} to +load a different font. + +\begin{table} + \caption[{% + Symbolic values for the \DescRef{typearea.option.DIV} option and the + \PName{DIV} argument to \DescRef{\LabelBase.cmd.typearea}% + }]{% + Available symbolic values for the \DescRef{typearea.option.DIV} option or + the \PName{DIV} argument to + \DescRef{typearea.cmd.typearea}\OParameter{BCOR}\Parameter{DIV}% + } + \label{tab:symbolicDIV} + \begin{desctabular} + \pventry{areaset}{Recalculate page + layout.\IndexOption{DIV~=\textKValue{areaset}}}% + \pventry{calc}{Recalculate type area including choice of appropriate + \Var{DIV} value.\IndexOption{DIV~=\textKValue{calc}}}% + \pventry{classic}{Recalculate type area using medieval book design canon + (circle-based calculation).\IndexOption{DIV~=\textKValue{classic}}}% + \pventry{current}{Recalculate type area using current \Var{DIV} + value.\IndexOption{DIV~=\textKValue{current}}}% + \pventry{default}{Recalculate type area using the standard value for the + current page format and current font size. If no standard value exists, + \PValue{calc} is used.\IndexOption{DIV~=\textKValue{default}}}% + \pventry{last}{Recalculate type area using the same \PName{DIV} argument + as was used in the last call.\IndexOption{DIV~=\textKValue{last}}}% + \end{desctabular} +\end{table} + +Frequently\textnote{Attention!}, the type area must be recalculated in +combination with a change in the line spacing (\emph{leading})\Index{leading}. +Since the type area should be calculated in such a way that a whole number of +lines fits in the text block, a change in the leading normally requires a +recalculation of the type area. + +\begin{Example} + Suppose that you require a 10\Unit{pt} font and a spacing of 1.5 lines for a + dissertation. By default, {\LaTeX} sets the leading for 10\Unit{pt} fonts at + 2\Unit{pt}, in other words 1.2 lines. Therefore, you must use an additional + stretch factor of 1.25. Suppose also that you need a binding correction of + \(12\Unit{mm}\). Then the solution to the problem might look like this: +\begin{lstcode} + \documentclass[10pt,twoside,BCOR=12mm,DIV=calc]{scrreprt} + \linespread{1.25} + \KOMAoptions{DIV=last} +\end{lstcode}\IndexCmd{linespread} + Since \Package{typearea} always executes the \Macro{normalsize} command + itself when calculating a new type area, it is not strictly necessary to + set the chosen leading with \Macro{selectfont} after \Macro{linespread}, + since this will already be done in the recalculation. + + When using the \Package{setspace}\IndexPackage{setspace}% + \important{\Package{setspace}} package (see \cite{package:setspace}), the + same example would appear as follows: +\begin{lstcode} + \documentclass[10pt,twoside,BCOR=12mm,DIV=calc]{scrreprt} + \usepackage[onehalfspacing]{setspace} + \KOMAoptions{DIV=last} +\end{lstcode} +\end{Example} + +As\textnote{Hint!} you can see from the example, the \Package{setspace} +package saves you from needing to know the correct stretch value. However, +this only applies to the standard font sizes 10\Unit{pt}, 11\Unit{pt}, and +12\Unit{pt}. For all other font sizes, the package uses an approximate value. + +At\textnote{Attention!} this point, note that the line spacing for the title +page should be reset to the normal value, and the indexes should be set with +the normal line spacing as well. +\begin{Example} + Here\IndexPackage{setspace} is a complete example: +\begin{lstcode} + \documentclass[10pt,twoside,BCOR=12mm,DIV=calc] + {scrreprt} + \usepackage{setspace} + \onehalfspacing + \AfterTOCHead{\singlespacing} + \KOMAoptions{DIV=last} + \begin{document} + \title{Title} + \author{Markus Kohm} + \begin{spacing}{1} + \maketitle + \end{spacing} + \tableofcontents + \chapter{Ok} + \end{document} +\end{lstcode} + Also see the notes in \autoref{sec:typearea.tips}. The + \DescRef{tocbasic.cmd.AfterTOCHead}\IndexCmd{AfterTOCHead} command is + described in \autoref{cha:tocbasic} of \autoref{part:forExperts} on + \DescPageRef{tocbasic.cmd.AfterTOCHead}. +\end{Example} +Note also that changing the line spacing can also affect the page's header and +footer. For example, if you are using the \Package{scrlayer-scrpage} package, +you have to decide for yourself whether you prefer to have the normal or the +changed leading. See the \DescRef{scrlayer.option.singlespacing} option in +\autoref{cha:scrlayer}\important{\hyperref[cha:scrlayer]{\Package{scrlayer}}}% +\IndexPackage{scrlayer}\IndexOption{singlespacing}, +\DescPageRef{scrlayer.option.singlespacing}. + +Note\textnote{Attention!} that when using this option with one of the +{\KOMAScript} classes, as in the example above, it must be passed either as a +class option, or via \DescRef{\LabelBase.cmd.KOMAoptions} or +\DescRef{\LabelBase.cmd.KOMAoption} after loading the class. When using a +{\KOMAScript} class, the \Package{typearea} package should not be loaded +explicitly with \DescRef{\LabelBase.cmd.usepackage}, nor should the option be +given as an optional argument thereto. If the option is changed via +\DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption} +after loading the package, the type area and margins are automatically +recalculated.% +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{typearea}\OParameter{BCOR}\Parameter{DIV}% + \Macro{recalctypearea} +\end{Declaration}% +\begin{Explain} + If the \DescRef{\LabelBase.option.DIV} option or the + \DescRef{\LabelBase.option.BCOR} option is set after loading the + \Package{typearea} package, the \Macro{typearea} command will be called + internally. When setting the \DescRef{\LabelBase.option.DIV} option, the + symbolic value \PValue{current} is used internally for \PName{BCOR}, which + for reasons of completeness is also found in \autoref{tab:symbolicBCOR}. + When setting the \DescRef{\LabelBase.option.BCOR} option, the symbolic value + \PValue{last} is used internally for \PName{DIV}. If instead you want the + type area and margins to be recalculated using the symbolic value + \PValue{current} for \PName{DIV}, you can use + \Macro{typearea}\POParameter{current}\PParameter{current} directly. +\end{Explain} + +\begin{table} + \caption[{% + Symbolic \PName{BCOR} arguments for \DescRef{typearea.cmd.typearea}% + }]{% + Available symbolic \PName{BCOR} arguments for + \Macro{typearea}\OParameter{BCOR}\Parameter{DIV}% + } + \label{tab:symbolicBCOR} + \begin{desctabular} + \pventry{current}{Recalculate type area with the currently valid + \Var{BCOR} value.\IndexOption{BCOR~=\textKValue{current}}} + \end{desctabular} +\end{table} + +If you change both \PName{BCOR} and \PName{DIV}, you should use +\Macro{typearea}, since then the type area and margins are recalculated only +once. With \DescRef{\LabelBase.cmd.KOMAoptions}% +\PParameter{\OptionVNameRef{\LabelBase}{DIV}{factor},% + \OptionVNameRef{\LabelBase}{BCOR}{correction}} the type area and margins are +recalculated once for the change to \DescRef{\LabelBase.option.DIV} and again +for the change to \DescRef{\LabelBase.option.BCOR}. + +\begin{Explain} + The command \Macro{typearea} is currently defined so as to make it possible + to change the type area in the middle of a document. However, several + assumptions about the structure of the {\LaTeX} kernel are made, and + internal definitions and sizes of the kernel are changed. Since changes are + only made to the {\LaTeX} kernel to fix bugs, there is a high likelihood, + though no guarantee, that this will still work in future versions of + \LaTeXe{}. When used within the document, a page break will result. +\end{Explain} + +Since\important{\Macro{recalctypearea}} \DescRef{\LabelBase.cmd.KOMAoption}% +\PParameter{\hyperref[desc:\LabelBase.option.DIV.last]{\Option{DIV}}}% +\PParameter{\hyperref[desc:\LabelBase.option.DIV.last]{last}}, +\DescRef{\LabelBase.cmd.KOMAoptions}% +\PParameter{\OptionValueRef{\LabelBase}{DIV}{last}}, or +\Macro{typearea}\POParameter{current}\PParameter{last} is frequently needed +to recalculate the type area and margins, there is a convenience command, +\Macro{recalctypearea}\ChangedAt{v3.00}{\Package{typearea}}. +\begin{Example} + If you find the notation +\begin{lstcode} + \KOMAoptions{DIV=last} +\end{lstcode} + or +\begin{lstcode} + \typearea[current]{last} +\end{lstcode} + too cumbersome for recalculating text area and margins because of + the many special characters, you can simply use +\begin{lstcode} + \recalctypearea +\end{lstcode} +\end{Example}% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{twoside}{simple switch}% + \OptionValue{twoside}{semi} +\end{Declaration}% +As explained in \autoref{sec:typearea.basics}, the distribution of the margins +depends on whether the document is to be printed one-sided or two-sided. For +one-sided printing, the left and right margins are the same width, whereas for +two-sided printing the inner margin of one page is only half as wide as the +corresponding outer margin. To invoke two-sided printing, you must give the +\Package{typearea} package the \Option{twoside} option. For the +\PName{simple switch}, you can use any of the standard values for +simple switches in \autoref{tab:truefalseswitch}. If the option is passed +without a value, the value \PValue{true} is assumed, so two-sided printing is +enabled. Deactivating the option leads to one-sided printing. + +\begin{table} + \centering + \caption{Standard values for simple switches in \KOMAScript} + \begin{tabular}{ll} + \toprule + Value & Description \\ + \midrule + \PValue{true} & activates the option \\ + \PValue{on} & activates the option \\ + \PValue{yes} & activates the option \\ + \PValue{false}& deactivates the option \\ + \PValue{off} & deactivates the option \\ + \PValue{no} & deactivates the option \\ + \bottomrule + \end{tabular} + \label{tab:truefalseswitch} +\end{table} + +In addition to the values in \autoref{tab:truefalseswitch}, you can also use +the value \PValue{semi}\ChangedAt{v3.00}{\Package{typearea}}. This value +results in two-sided printing with one-sided margins and one-sided, that is +non-alternating, marginal notes. +Beginning\ChangedAt{v3.12}{\Package{typearea}} with \KOMAScript{} version +3.12, binding corrections (see \DescRef{\LabelBase.option.BCOR}, +\DescPageRef{typearea.option.BCOR}) will be part of the left margin on odd +pages but part of the right margin on even pages. But if you switch on +compatibility with a prior +version\important{\OptionValueRef{\LabelBase}{version}{3.12}} of \KOMAScript{} +(see \autoref{sec:typearea.compatibilityOptions}, +\autopageref{sec:typearea.compatibilityOptions}), the binding correction will +be part of the left margin on both pages while using +\OptionValue{twoside}{semi}. + +The option can also be passed as class option in +\DescRef{\LabelBase.cmd.documentclass}, as a package option with +\DescRef{\LabelBase.cmd.usepackage}, or even after loading +\Package{typearea} with \DescRef{\LabelBase.cmd.KOMAoptions} or +\DescRef{\LabelBase.cmd.KOMAoption}. Using this option after loading +\Package{typearea} automatically\textnote{automatic recalculation} results in +the recalculation of the type area using +\DescRef{\LabelBase.cmd.recalctypearea} (see +\DescPageRef{typearea.cmd.recalctypearea}). If the two-sided mode was active +before the option was set, a page break is made to the next odd page before +the recalculation.% +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{twocolumn}{simple switch} +\end{Declaration} +To compute an appropriate type area with the help of +\OptionValueRef{\LabelBase}{DIV}{calc}, it is useful to know in advance if the +document is to be typeset in one or two columns. Since the considerations +about line length in \autoref{sec:typearea.basics} apply to each column, the +type area in two-column documents can be up to twice as wide as in one-column +documents. + +To make this distinction, you must tell \Package{typearea} if the document is +to be set with two columns using the \Option{twocolumn} option. Since this is +a \PName{simple switch}, any of the standard values for simple switches +from \autoref{tab:truefalseswitch} are valid. If the option is passed without +a value, the value \PValue{true}\important{\OptionValue{twocolumn}{true}} is +used, i.\,e. the two-column setting. Deactivating the option returns you to +the default one-column setting. + +The option can also be passed as a class option in +\DescRef{\LabelBase.cmd.documentclass}, as a package option to +\DescRef{\LabelBase.cmd.usepackage}, or even after loading \Package{typearea} +with \DescRef{\LabelBase.cmd.KOMAoptions} or +\DescRef{\LabelBase.cmd.KOMAoption}. Using this option after loading +\Package{typearea} will\textnote{automatic recalculation} automatically +recalculate the type area using \DescRef{\LabelBase.cmd.recalctypearea} (see +\DescPageRef{typearea.cmd.recalctypearea}).% +% +\EndIndexGroup + +\begin{Declaration} + \OptionVName{headinclude}{simple switch}% + \OptionVName{footinclude}{simple switch} +\end{Declaration}% +\begin{Explain}% + So far we have discussed how the type area is calculated\Index{type area} + and the relationship of the margins\Index{margins} to one another and + between margins and body of the text. But one important question has not + been answered: What exactly are \emph{the margins}? + + At first glance the question appears trivial: Margins are those parts on the + right, left, top, and bottom of the page which remain empty. But this is + only half the story. Margins are not always empty. Sometimes there can be + marginal notes, for example (see the \DescRef{maincls.cmd.marginpar} command + in \cite{lshort} or \autoref{sec:maincls.marginNotes}). + + For the top and bottom margins, the question becomes how to handle + headers\Index{page header} and footers\Index{page footer}. Do these two + belong to the text body or to their respective margins? This question is not + easy to answer. Clearly an empty footer or header belongs to the margins, + since it cannot be distinguished from the rest of the margins. A footer that + contains only the + pagination\Index[indexmain]{pagination}\textnote{pagination} % + \iffalse % + \unskip\footnote{Pagination refers to the indication of the page number, + either inside or outside the type area, and usually appears in either the + header or the footer of the page.} % + \fi % + looks more like a margin and should therefore be counted as such. It is + irrelevant for the visual effect whether headers or footers are easily + recognized as such when reading or skimming. The decisive factor is how a + well-filled page appears when viewed \emph{out of focus}. For this purpose, + you could, for example, steal the glasses of a far-sighted grandparent and + hold the page about half a meter from the tip of your nose. If you lack an + available grandparent, you can also adjust your vision to infinity and look + at the page with one eye only. Those who wear glasses have a clear advantage + here. If the footer contains not only the pagination but also other material + like a copyright notice, it looks more like a slightly detached part of the + body of the text. This needs to be taken into account when calculating the + type area. + + For the header, this is even more complicated. The header often contains + running heads\Index[indexmain]{running heads}\textnote{running heads}. % + \iffalse% + \unskip\footnote{Running heads refer to the repetition of a title, in + titling font, which usually appears in the page header, or rarely in the + page footer.} % + \fi If you use the current chapter and section titles in your running head + and these titles are long, the header itself will necessarily be very + long. In this case, the header again acts like a detached part of the text + body and less like an empty margin. This effect is reinforced if the header + contains not only the chapter or section title but also the pagination. With + material on the right and left side, the header no longer appears as an + empty margin. It is more difficult if the pagination is in the footer and + the length of the running titles varies, so that the header may look like + part of the margin on one page and part of the text body on another. Under + no circumstances should you treat the pages differently. That would lead to + vertically jumping headers, which is not suitable even for a flip book. In + this case it is probably best to count the header as part of the text body. + + The decision is easy when the header or footer is separated from the actual + text body by a line. This will give a ``closed'' appearance and the header + or footer should be calculated as part of the text body. Remember: It is + irrelevant that the line improves the optical separation of text and header + or footer; only the appearance when viewed out of focus is important. +\end{Explain} + +The \Package{typearea} package cannot determine on its own whether +to count headers and footers\important{\OptionValue{headinclude}{true} + \OptionValue{headinclude}{false} \OptionValue{footinclude}{true} + \OptionValue{footinclude}{false}} as part of the text body or the +margin. The \Option{headinclude} and \Option{footinclude} options cause +the header or footer to be counted as part of the text. These +options, being \PName{simple switch}es\ChangedAt{v3.00}{\Package{typearea}}, +accept the standard values for simple switches in +\autoref{tab:truefalseswitch}. You can use the options without +specifying a value, in which case the value \PValue{true} is used for +the \PName{simple}, i.\,e. the header or footer is counted as part of +the text. + +If you are unsure what the correct setting should be, reread the explanations +above. The default is usually \OptionValue{headinclude}{false} and +\OptionValue{footinclude}{false}, but this can change in the {\KOMAScript} +classes or in other {\KOMAScript} packages depending on the options used (see +\autoref{sec:maincls.options} and \autoref{cha:scrlayer-scrpage}). + +Note\textnote{Attention!} that these options must be passed as class options +when using one of the {\KOMAScript} classes, or after loading the class with +\DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption}. +Changing these options after loading the \Package{typearea} package does not +automatically recalculate the type area. Instead, the changes only take effect +the next time the type area is recalculated. For recalculation of the type +area, see the \hyperref[desc:\LabelBase.option.DIV.last]{\Option{DIV}} option +with the values \hyperref[desc:\LabelBase.option.DIV.last]{\PValue{last}} or +\hyperref[desc:\LabelBase.option.DIV.current]{\PValue{current}} (see +\DescPageRef{typearea.option.DIV.last}) or the +\DescRef{\LabelBase.cmd.recalctypearea} command (see +\DescPageRef{typearea.cmd.recalctypearea}).% +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{mpinclude}{simple switch} +\end{Declaration} +In addition to\ChangedAt{v2.8q}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} documents where the header and footer are more likely to +be part of the text body than the margins, there are also documents where +marginal notes should be considered part of the text body as well. The option +\Option{mpinclude} does exactly this. The option, as a \PName{simple + switch}\ChangedAt{v3.00}{\Package{typearea}}, accepts the standard values +for simple switches in \autoref{tab:truefalseswitch}. You can also pass this +option without specifying a value, in which case \PValue{true} is assumed. + +The effect of \OptionValue{mpinclude}{true}% +\important{\OptionValue{mpinclude}{true}} is that a width-unit is removed from +the main text body and used as the area for marginal notes. With the +\OptionValue{mpinclude}{false} option, which is the default setting, part of +the normal margin is used for marginal notes. The width of that area is one or +one-and-a-half width units, depending on whether you have chosen one-sided or +two-sided printing. The \OptionValue{mpinclude}{true} option is mainly for +experts and so is not recommended. + +\begin{Explain} + In most cases where the option \Option{mpinclude} makes sense, you also + require a wider area for marginal notes. Often, however, only a part of the + marginal note's width should be part of the text area, not the whole width, + for example if the margin is used for quotations. Such quotations are + usually set as unjustified text, with the flush edge against the text area. + Since the unjustified text gives no homogeneous optical impression, these + lines can protrude partially into the margin. You can accomplish that by + using the option \Option{mpinclude} and by increasing the length + \Length{marginparwidth} after the type area has been set up. The length can + be easily enlarged with the command \Macro{addtolength}. How much the length + has to be increased depends on the individual situation and it requires a + certain amount of sensitivity. This is another reason the \Option{mpinclude} + option is primarily intended for experts. Of course you can specify, for + example, that the marginal notes should project a third of the way into the + normal margin by using the following: +\begin{lstcode} + \setlength{\marginparwidth}{1.5\marginparwidth} +\end{lstcode} + +Currently there is no option to enlarge the space for marginal notes within +the text area. There is only one way to accomplish this: first, either omit +the \Option{mpinclude} option or set it to \PValue{false}, and then, after the +type area has been calculated, reduce \Length{textwidth} (the width of the +text body) and increase \Length{marginparwidth} (the width of the marginal +notes) by the same amount. Unfortunately, this procedure cannot be combined +with automatic calculation of the \PName{DIV} value. In contrast, +\Option{mpinclude} is taken into account with +\OptionValueRef{\LabelBase}{DIV}{calc}\IndexOption{DIV~=calc} (see +\DescPageRef{typearea.option.DIV.calc}). +\end{Explain} + +Note\textnote{Attention!} that these options must be passed as class options +when using one of the {\KOMAScript} classes, or after loading the class with +\DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption}. +Changing these options after loading the \Package{typearea} package does not +automatically recalculate the type area. Instead, the changes only take effect +the next time the type area is recalculated. For recalculation of the type +area, see the \hyperref[desc:\LabelBase.option.DIV.last]{\Option{DIV}} option +with the values \hyperref[desc:\LabelBase.option.DIV.last]{\PValue{last}} or +\hyperref[desc:\LabelBase.option.DIV.current]{\PValue{current}} (see +\DescPageRef{typearea.option.DIV.last}) or the +\DescRef{\LabelBase.cmd.recalctypearea} command (see +\DescPageRef{typearea.cmd.recalctypearea}).% +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{headlines}{number of lines} + \OptionVName{headheight}{height} +\end{Declaration}% +\BeginIndex{}{header>height}% +We have seen how to calculate the type area using the \Package{typearea} +package and how to specify whether the header and footer are part of the text +or the margins. However, especially for the header, we still have to specify +the height. This is achieved with the options \Option{headlines} and +\Option{headheight}\ChangedAt{v3.00}{\Package{typearea}}. + +The \Option{headlines}\important{\Option{headlines}} option specifies the +number of lines of text in the header. The \Package{typearea} package uses a +default of 1.25. This is a compromise: large enough for underlined headers +(see \autoref{sec:maincls.pagestyle}) and small enough that the relative +weight of the top margin is not affected too much when the header is not +underlined. Thus the default value will usually be adequate. In special cases, +however, you may need to adjust the header height more precisely to your +actual requirements. + +\begin{Example} + Suppose you want to create a two-line header. Normally this would result in + {\LaTeX} issuing the warning ``\texttt{overfull} \Macro{vbox}'' for each + page. To prevent this from happening, you tell the \Package{typearea} + package to calculate an appropriate type area: +\begin{lstcode} + \documentclass[a4paper]{article} + \usepackage[headlines=2.1]{typearea} +\end{lstcode} + If you use a {\KOMAScript} class, you should pass this option directly to + the class: +\begin{lstcode} + \documentclass[a4paper,headlines=2.1]{scrartcl} +\end{lstcode} + Commands that can be used to define the contents of a two-line header + can be found in \autoref{cha:scrlayer-scrpage}. +\end{Example} + +In some cases it is useful to be able to specify the header height not in +lines but directly as a length. This is accomplished with the alternative +option \Option{headheight}\important{\Option{headheight}}. All lengths and +sizes that \LaTeX{} understands are valid for \PName{height}. +Note\textnote{Attention!}, however, that if you use a \LaTeX{} length such as +\Length{baselineskip}, its value is not fixed at the time the option is set. +The value that will be used will be the one current at the time the type area +and margins are calculated. Also\textnote{Attention!}, \LaTeX{} lengths like +\Length{baselineskip} should never be used in the optional argument of +\DescRef{\LabelBase.cmd.documentclass} or \DescRef{\LabelBase.cmd.usepackage}. + +Please be sure to note\textnote{Attention!} that these options must be passed +as class options when using one of the {\KOMAScript} classes, or after loading +the class with \DescRef{\LabelBase.cmd.KOMAoptions} or +\DescRef{\LabelBase.cmd.KOMAoption}. Changing these options after loading the +\Package{typearea} package does not\textnote{no automatic recalculation} +automatically recalculate the type area. Instead, the changes only take effect +the next time the type area is recalculated. For recalculation of the type +area, see the \hyperref[desc:\LabelBase.option.DIV.last]{\Option{DIV}} option +with the values \hyperref[desc:\LabelBase.option.DIV.last]{\PValue{last}} or +\hyperref[desc:\LabelBase.option.DIV.current]{\PValue{current}} (see +\DescPageRef{typearea.option.DIV.last}) or the +\DescRef{\LabelBase.cmd.recalctypearea} command (see +\DescPageRef{typearea.cmd.recalctypearea}).% +% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{footlines}{number of lines}% + \OptionVName{footheight}{height}% + \Length{footheight}% +\end{Declaration} +\BeginIndex{}{footer>height}% +Like\ChangedAt{v3.12}{\Package{typearea}} the header, the footer also requires +an indication of how high it should be. But unlike the height of the header, +the \LaTeX{} kernel does not provide a length for the height of the footer. So +\Package{typearea} defines a new length, +\Length{footheight}\IndexLength[indexmain]{footheight}, if it does not already +exist. Whether this length will be used by classes or packages to design the +headers and footers depends on the individual classes and packages. The +\KOMAScript{} package +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}}% +\IndexPackage{scrlayer-scrpage} incorporates +\Length{footheight} and actively cooperates with \Package{typearea}. The +\KOMAScript{} classes, on the other hand, do not recognize \Length{footheight} +because without the help of packages they offer only page styles with +single-line page footers. + +You can use \Option{footlines}\important{\Option{footlines}} to set the number +of lines in the footer, similar to \DescRef{\LabelBase.option.headlines} for +the number of lines in the header. By default the \Package{typearea} package +uses 1.25 footer lines. This value is a compromise: large enough to +accommodate an overlined or underlined footer (see +\autoref{sec:maincls.pagestyle}), and small enough that the relative weight of +the bottom margin is not affected too much when the footer lacks a dividing +line. Thus the default value will usually be adequate. In special cases, +however, you may need to adjust the footer height more precisely to your +actual requirements. + +\begin{Example} + Suppose you need to place a two-line copyright notice in the footer. + Although there is no test in \LaTeX{} itself to check the space available + for the footer, exceeding the designated height will likely result in + unbalanced distribution of type area and margins. Moreover, a package such + as \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + \important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}}% + \IndexPackage{scrlayer-scrpage}, which can be used to define such a footer, + performs the appropriate test and will report any overruns. So it makes + sense to specify the required footer height when calculating of the type + area: +\begin{lstcode} + \documentclass[a4paper]{article} + \usepackage[footlines=2.1]{typearea} +\end{lstcode} + Again, if you use a \KOMAScript{} class, you should pass this + option directly to the class: +\begin{lstcode} + \documentclass[footlines=2.1]{scrartcl} +\end{lstcode} + Commands that can be used to define the contents of a two-line footer + are described in \autoref{cha:scrlayer-scrpage}. +\end{Example} + +In some cases it is useful to be able to specify the footer height not in +lines but directly as a length. This is accomplished with the alternative +option \Option{footheight}\important{\Option{footheight}}. All lengths and +sizes that \LaTeX{} understands are valid for \PName{height}. Note, however, +that if you use a \LaTeX{} length such as \Length{baselineskip}, its value is +not fixed at the time the option is set. The value that will be used will be +the one current at the time the type area and margins are calculated. +Also\textnote{Attention!}, \LaTeX{} lengths like \Length{baselineskip} should +never be used in the optional argument of +\DescRef{\LabelBase.cmd.documentclass} or \DescRef{\LabelBase.cmd.usepackage}. + +Please be sure to note\textnote{Attention!} that these options must be passed +as class options when using one of the {\KOMAScript} classes, or after loading +the class with \DescRef{\LabelBase.cmd.KOMAoptions} or +\DescRef{\LabelBase.cmd.KOMAoption}. Changing these options after loading +\Package{typearea} does not\textnote{no automatic recalculation} automatically +recalculate the type area. Instead, the changes only take effect the next time +the type area is recalculated. For recalculation of the type area, see the +\hyperref[desc:\LabelBase.option.DIV.last]{\Option{DIV}} option with the +values \hyperref[desc:\LabelBase.option.DIV.last]{\PValue{last}} or +\hyperref[desc:\LabelBase.option.DIV.current]{\PValue{current}} (see +\DescPageRef{typearea.option.DIV.last}) or the +\DescRef{\LabelBase.cmd.recalctypearea} command (see +\DescPageRef{typearea.cmd.recalctypearea}).% +\EndIndexGroup + + +\begin{Declaration} + \Macro{areaset}\OParameter{BCOR}\Parameter{width}\Parameter{height} +\end{Declaration}% +So far, we have seen how to create a nice type area\Index{type area} for +standard situations and how the \Package{typearea} package makes it easier to +accomplish this while still giving the freedom to adapt the layout. However, +there are cases where the text body has to adhere precisely to specific +dimensions. At the same time, the margins should be distributed as nicely as +possible and, if necessary, a binding correction should be taken into account. +The \Package{typearea} package offers the command \Macro{areaset} for this +purpose. This command takes as parameters the width and height of the text +body, as well as the binding correction as an optional parameter. The width +and position of the margins are then calculated automatically, taking account +of the options \DescRef{\LabelBase.option.headinclude}, +\OptionValueRef{\LabelBase}{headinclude}{false}, +\DescRef{\LabelBase.option.footinclude} and +\OptionValueRef{\LabelBase}{footinclude}{false} where needed. On the other +hand, the options +\DescRef{\LabelBase.option.headlines}\IndexOption{headlines}, +\DescRef{\LabelBase.option.headheight}\IndexOption{headheight}, +\DescRef{\LabelBase.option.footlines}\IndexOption{footlines}, and +\DescRef{\LabelBase.option.footheight}\IndexOption{footheight} are ignored! +For more information, see \DescRef{typearea-experts.cmd.areaset} on +\DescPageRef{typearea-experts.cmd.areaset} of +\autoref{sec:typearea-experts.experimental}. + +The default for \PName{BCOR} is 0\Unit{pt}. If you want to preserve the +current binding correction, for example the value set by option +\DescRef{\LabelBase.option.BCOR}\IndexOption{BCOR}, you can use the symbolic +value \PValue{current} at an optional argument. + +\begin{Example} + Suppose a text on A4 paper needs a width of exactly 60 characters in a + typewriter font and a height of exactly 30 lines per page. You can + accomplish this with the following preamble: +\begin{lstcode} + \documentclass[a4paper,11pt]{article} + \usepackage{typearea} + \newlength{\CharsLX}% Width of 60 characters + \newlength{\LinesXXX}% Height of 30 lines + \settowidth{\CharsLX}{\texttt{1234567890}} + \setlength{\CharsLX}{6\CharsLX} + \setlength{\LinesXXX}{\topskip} + \addtolength{\LinesXXX}{29\baselineskip} + \areaset{\CharsLX}{\LinesXXX} +\end{lstcode} + The factor is 29 rather than 30 because the baseline of the topmost line of + text is \Macro{topskip} below the top margin of the type area, as long as + the height of the topmost line is less than \Macro{topskip}. So we don't + need to add any height for the first line. The descenders of characters on + the lowermost line, on the other hand, protrude below the dimensions of the + type area. + +\iffalse % Umbruchkorrekturtext + If instead you want to set a book of poetry in which the text area is + exactly square with a side length of 15\Unit{cm}, with a binding correction + of 1\Unit{cm} taken into account, you can achieve this as follows:% +\else% + To set a book of poetry with a square text area with a side length of + 15\Unit{cm} and a binding correction of 1\Unit{cm}, the following is + possible:% +\fi +\begin{lstcode} + \documentclass{poetry} + \usepackage{typearea} + \areaset[1cm]{15cm}{15cm} +\end{lstcode} +\end{Example} +\EndIndexGroup + + +\begin{Declaration} + \OptionValue{DIV}{areaset} +\end{Declaration}% +In\ChangedAt{v3.00}{\Package{typearea}} rare cases it is useful to be able to +realign the current type area. This is possible with the option +\OptionValue{DIV}{areaset}, where +\DescRef{\LabelBase.cmd.KOMAoptions}\PParameter{\OptionValue{DIV}{areaset}} +corresponds to the +\begin{lstcode} + \areaset[current]{\textwidth}{\textheight} +\end{lstcode} +command. The same result is obtained if you use +\OptionValueRef{\LabelBase}{DIV}{last} and the typearea was last set with +\DescRef{\LabelBase.cmd.areaset}.% +% +\EndIndexGroup + +\iftrue% Umbruchkorrekturtext: Alternativen + If you have concrete specifications for the margins, \Package{typearea} is + not suitable. In this case, you should use the + \Package{geometry}\IndexPackage{geometry}% + \important{\Package{geometry}} package (see \cite{package:geometry}).% +\fi% +\iffalse% + The \Package{typearea} package is not designed to set up predefined margins. + If you have to do so, the \Package{geometry}\IndexPackage{geometry} package + (see \cite{package:geometry}) is recommended.% +\fi + + +\section{Selecting the Paper Size} +\seclabel{paperTypes}% +\BeginIndexGroup + +The paper size is a key feature of a document. As already mentioned in the +description of the supported page layout constructions (see +\autoref{sec:typearea.basics} to \autoref{sec:typearea.circleConstruction} +starting on \autopageref{sec:typearea.basics}), the layout of the page, and +hence the entire document, depends on the paper size. Whereas the {\LaTeX} +standard classes are limited to a few formats, {\KOMAScript} supports even +unusual paper sizes in conjunction with the \Package{typearea} package. + + +\begin{Declaration} + \OptionVName{paper}{size} + \OptionVName{paper}{orientation} +\end{Declaration}% +The \Option{paper}\ChangedAt{v3.00}{\Package{typearea}} option is the central +element for paper-size selection\important[i]{% + \begin{tabular}[t]{@{}l@{}l@{}} + \KOption{paper} & \PValue{letter}, \\ + & \PValue{legal}, \\ + & \PValue{executive}, \\ + & \PValue{A0}, \PValue{A1}, \PValue{A2} \dots\\ + & \PValue{B0}, \PValue{B1}, \PValue{B2} \dots\\ + & \PValue{C0}, \PValue{C1}, \PValue{C2} \dots\\ + & \PValue{D0}, \PValue{D1}, \PValue{D2} \dots\end{tabular}} % +in \KOMAScript. \PName{Size} supports the American formats \Option{letter}, +\Option{legal}, and \Option{executive}. In addition, it supports the ISO +formats of the series A, B, C, and D, for example \PValue{A4} or\,---\,written +in lower case\,---\,\PValue{a4}. + +Landscape orientations\important{% + \begin{tabular}[t]{@{}l@{}l@{}} + \KOption{paper} & \PValue{landscape}, \\ + & \PValue{seascape} + \end{tabular}% +} are supported by specifying the option one more time +with the value \PValue{landscape}\Index{paper>orientation} or +\PValue{seascape}\ChangedAt{v3.02c}{\Package{typearea}}. The only difference +between \PValue{landscape} and \PValue{seascape} is that that the application +\File{dvips} rotates \PValue{landscape} pages by -90\Unit{\textdegree}, while +it rotates \PValue{seascape} pages by +90\Unit{\textdegree}. Thus +\PValue{seascape} is particularly useful whenever a PostScript viewer shows +landscape pages upside-down. In order for the difference to have an effect, +you must not deactivate the \DescRef{\LabelBase.option.pagesize}% +\IndexOption{pagesize}\important{\DescRef{\LabelBase.option.pagesize}} option +described below. + +Additionally, the \PName{size} can also be specified either in the form +\PName{width}\texttt{:}\PName{height}\ChangedAt{v3.01b}{\Package{typearea}}% +\important{\OptionVName{paper}{width\textup{:}height}} or in the form +\PName{height}\texttt{:}\PName{width}\ChangedAt{v3.22}{\Package{typearea}}% +\important{\OptionVName{paper}{height\textup{:}width}}. Which value is taken +as the \PName{height} and which as the \PName{width} depends on the +orientation of the paper. With \OptionValue{paper}{landscape} or +\OptionValue{paper}{seascape}, the smaller value is the \PName{height} and the +larger one is the \PName{width}. With +\OptionValue{paper}{portrait}\important{\OptionValue{paper}{portrait}}, the +smaller value is the \PName{width} and the larger one is the \PName{height}. + +Note\textnote{Attention!} that until version~3.01a the first value was always +the \PName{height} and the second one the \PName{width}. From version~3.01b +through version~3.21, the first value was always the \PName{width} and the +second one the \PName{height}. This is important if you use compatibility +settings (see option \DescRef{\LabelBase.option.version}% +\IndexOption{version}\important{\DescRef{\LabelBase.option.version}}, +\autoref{sec:typearea.compatibilityOptions}, +\DescPageRef{typearea.option.version}). + +\begin{Example} + Suppose you want to print an ISO-A8 index card in landscape orientation. The + margins should be very small and no header or footer will be used. +\begin{lstcode} + \documentclass{article} + \usepackage[headinclude=false,footinclude=false, + paper=A8,landscape]{typearea} + \areaset{7cm}{5cm} + \pagestyle{empty} + \begin{document} + \section*{Supported Paper Sizes} + letter, legal, executive, a0, a1 \dots\ % + b0, b1 \dots\ c0, c1 \dots\ d0, d1 \dots + \end{document} +\end{lstcode} + If the file cards have the special format (height:width) + 5\Unit{cm}\,:\,3\Unit{cm}, this can be achieved using the following: +\begin{lstcode} + \documentclass{article} + \usepackage[headinclude=false,footinclude=false,% + paper=landscape,paper=5cm:3cm]{typearea} + \areaset{4cm}{2.4cm} + \pagestyle{empty} + \begin{document} + \section*{Supported Paper Sizes} + letter, legal, executive, a0, a1 \dots\ % + b0, b1 \dots\ c0, c1 \dots\ d0, d1 \dots + \end{document} +\end{lstcode} +\end{Example} + +By default, {\KOMAScript} uses A4 paper in portrait orientation. This is in +contrast\textnote{\KOMAScript{} vs. standard classes} to the standard classes, +which by default use the American letter paper format. + +Please note\textnote{Attention!} that these options must be passed as class +options when using one of the {\KOMAScript} classes, or after loading the +class with \DescRef{\LabelBase.cmd.KOMAoptions} or +\DescRef{\LabelBase.cmd.KOMAoption}. Changing the paper size or orientation +with \DescRef{\LabelBase.cmd.KOMAoptions} or +\DescRef{\LabelBase.cmd.KOMAoption} does not\textnote{no automatic +recalculation} automatically recalculate the type area. Instead, the changes +only take effect the next time the type area is recalculated. For +recalculation of the type area, see the +\hyperref[desc:\LabelBase.option.DIV.last]{\Option{DIV}} option with the +values \hyperref[desc:\LabelBase.option.DIV.last]{\PValue{last}} or +\hyperref[desc:\LabelBase.option.DIV.current]{\PValue{current}} (see +\DescPageRef{typearea.option.DIV.last}) or the +\DescRef{\LabelBase.cmd.recalctypearea} command (see +\DescPageRef{typearea.cmd.recalctypearea}).% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{pagesize}{output driver} +\end{Declaration}% +\begin{Explain}% + The above-mentioned mechanisms for choosing the paper format only affect the + output insofar as internal {\LaTeX} lengths are set. The \Package{typearea} + package then uses them in dividing the page into type area and margins. + The specification of the DVI formats\Index{DVI}, however, does not include + any indication of paper size. % + \iffree{% + When outputting directly from the DVI format to a low-level printer + language such as PCL% + \iftrue% Umbruchkorrektur + \footnote{PCL is a family of printer languages that HP uses for its + inkjet and laser printers.}% + \fi \ or ESC/P2% + \iftrue% Umbruchkorrektur + \footnote{ESC/P2 is the printer language that EPSON uses for its + dot-matrix, and older inkjet or laser printers.}% + \fi \ or ESC/P-R% + \iftrue% Umbruchkorrektur + \footnote{ESC/P-R is the printer language that EPSON currently uses for + inkjet and laser printers.}% + \fi, this is usually not an issue% + }{% + In the past, when DVI was printed directly into a low-level printer + language, it did not matter% + }, since with these formats the reference zero-position is at the top left, + as in DVI. But nowadays, the output is normally translated into languages + such as PostScript\Index{PostScript} or PDF\Index{PDF}, in which the + zero-position is at a different point, and in which the paper format should + be specified in the output file, which is missing this information. To solve + this problem, the corresponding driver uses a default paper size, which the + user can change either by an option or by specifying it in the {\TeX} source + file. When using the DVI driver \File{dvips} or \File{dvipdfm}, the + information can be given in the form of a \Macro{special} command. When + using {pdf\TeX}, {lua\TeX}, {\XeTeX} or {V\TeX} their paper-size lengths are + set appropriately. +\end{Explain} +With the \Option{pagesize} option, you can select an output driver for writing +the paper size into the destination document. Supported output drivers are +listed at \autoref{tab:typearea.outputdriver}\iffalse% +, \autopageref{tab:typearea.outputdriver}\fi. The +default\ChangedAt{v3.17}{\Package{typearea}} is \Option{pagesize}. Using this +option without providing a value is equivalent to \OptionValue{pagesize}{auto}. +% +\begin{table} + \caption{Output driver for option \OptionVName{pagesize}{output driver}} + \begin{desctabular} + \pventry{auto}{Uses output driver \PValue{pdftex} if the pdf\TeX-specific + lengths \Macro{pdfpagewidth}\IndexLength{pdfpagewidth} and + \Macro{pdfpageheight}\IndexLength{pdfpageheight} or the lua\TeX-specific + lengths \Macro{pagewidth}\IndexLength{pagewidth} and + \Macro{pageheight}\IndexLength{pageheight} are defined. In addition, the + output driver \PValue{dvips} will also be used. This setting is in + principle also suitable for \XeTeX{}.% + \IndexOption{pagesize~=\textKValue{auto}}}% + \pventry{automedia}{Almost the same as \PValue{auto} but if the + \mbox{V\TeX}-specific lengths + \Macro{mediawidth}\IndexLength{mediawidth} and + \Macro{mediaheight}\IndexLength{mediaheight} are defined, they will be + set as well.\IndexOption{pagesize~=\textKValue{automedia}}}% + \entry{\PValue{false}, \PValue{no}, \PValue{off}}{% + Does not set any output driver and does not send page size information to + the output driver.\IndexOption{pagesize~=\textKValue{false}}}% + \pventry{dvipdfmx}{\ChangedAt{v3.05a}{\Package{typearea}} Writes the paper + size into DVI files using + \Macro{special}\PParameter{pagesize=\PName{width},\PName{height}}. The + name of the output driver is \PValue{dvipdfmx} because the application + \File{dvipdfmx} handles such specials not just in the preamble but + in the document body too.\IndexOption{pagesize~=\textKValue{dvipdfmx}}}% + \pventry{dvips}{Using this option in the preamble sets the paper size + using + \Macro{special}\PParameter{pagesize=\PName{width},\PName{height}}. Since + the \File{dvips} driver cannot handle changes of paper size in the + inner document pages, a hack is required to achieve such changes. Use + changes of paper size after \Macro{begin}\PParameter{document} at your + own risk, if you are using + \PValue{dvips}!\IndexOption{pagesize~=\textKValue{dvips}}}% + \entry{\PValue{pdftex}, \PValue{luatex}}{% + \ChangedAt{v3.20}{\Package{typearea}}Sets paper size using the + pdf\TeX-specific lengths + \Macro{pdfpagewidth}\IndexLength{pdfpagewidth} and + \Macro{pdfpageheight}\IndexLength{pdfpageheight} or the + lua\TeX-specific lengths \Macro{pagewidth}\IndexLength{pagewidth} + and \Macro{pageheight}\IndexLength{pageheight}. You can do this at any + time in your document.% + \IndexOption{pagesize~=\textKValue{pdftex}}% + \IndexOption{pagesize~=\textKValue{luatex}}}% + \end{desctabular} + \label{tab:typearea.outputdriver} +\end{table} + +\begin{Example} + Suppose a document should be available both as a DVI data file + and in PDF format for on-line viewing. The preamble might begin + as follows: +\begin{lstcode}[% + aboveskip=.5\baselineskip plus .1\baselineskip minus .1\baselineskip,% + belowskip=.4\baselineskip plus .1\baselineskip minus .1\baselineskip] + \documentclass{article} + \usepackage[paper=A4,pagesize]{typearea} +\end{lstcode} + If the {pdf\TeX} engine is used \emph{and} PDF output is enabled, the + lengths \Macro{pdfpagewidth} and \Macro{pdfpageheight} are set + appropriately. If, however, a DVI data file is created\,---\, whether by + {\LaTeX} or by {pdf\LaTeX}\,---\,then a \Macro{special} is written at the + start of this data file. +\end{Example}% +\iffree{% The recommendation is actually outdated. Those who use such old + % versions of typearea are the ones at fault. + If you use an older version of \Package{typearea}, you + should\textnote{Attention!} always specify the \Option{pagesize} option, + because older versions of \Package{typearea} did not set them by default. As + a rule, the method without an \PName{output driver} or with \PValue{auto} or + \PValue{automedia} is convenient.% +}{% + \vskip-1\ht\strutbox plus + .75\ht\strutbox% Wegen Beispiel am Ende der Erklaerung +}% +\EndIndexGroup +% +\EndIndexGroup + + +\section{Tips} +\seclabel{tips} + +For theses and dissertations, many rules exist that violate even the most +elementary rules of typography.\textnote{formatting rules vs. good typography} +The reasons for such rules include the typographical incompetence of those who +issue them, but also the fact that they were originally meant for mechanical +typewriters. With a typewriter or a primitive text processor from the early +1980s, it was not possible to produce typographically correct output without +extreme effort. So rules were created that appeared to be easy to follow and +were still accommodating to a proofreader. These include margins that lead to +usable line lengths for one-sided printing with a typewriter. To avoid +extremely short lines, which are made worse by unjustified text, the margins +were kept narrow and the leading was increased to 1.5 lines to allow space for +corrections. Before the advent of modern text processing systems, single +spacing would have been the only alternative\,---\,except with \TeX. In such a +single-spaced document, even correction signs would have been difficult to +add. When computers became more widely available for text processing, some +students showed their playful side and tried to spice up their work by using +an ornamental font to make their work look better than it really was. They did +not consider that such fonts are often more difficult to read and therefore +unsuitable for this purpose. Thus, two font families found their way +into the regulations which are neither compatible nor particularly suitable +for the job in the case of Times. Times is a relatively narrow typeface +designed at the beginning of the 20th century for the narrow columns of +British newspapers. Modern versions usually are somewhat improved. But still +the Times font, which is often required, does not really fit the prescribed +margins. + +{\LaTeX} already uses adequate line spacing, and the margins are wide enough +for corrections. Thus a page will look spacious, even when quite full of text. + +Often these typographically questionable rules are difficult to implement in +{\LaTeX}. A fixed number of characters per line can be achieved only when a +non-proportional font is used. There are very few good non-proportional fonts +available. Hardly any text typeset in this way looks really good. In many +cases font designers try to increase the serifs on the `i' or `l' to +compensate for the different character widths. This does not work and results +in a fragmented and agitated-looking text. If you use {\LaTeX} for your +thesis, some of these rules have to be either ignored or at least interpreted +generously. For example, ``60 characters per line'' can be interpreted not as +a fixed but as an average or maximum value.% + +As implemented, typesetting rules are usually intended to obtain a useful +result even if the author does not know what needs to be considered. +\emph{Useful} frequently means readable and correctable. In my opinion the +type area of a text set with {\LaTeX} and the \Package{typearea} package meets +these criteria well from the outset. So if you are confronted with regulations +which deviate substantially from it, I recommend that you present a sample of +the text to your advisor and ask whether you can submit the work despite +deviations in the format. If necessary the type area can be adapted somewhat +by changing the \DescRef{\LabelBase.option.DIV}% +\important{\DescRef{\LabelBase.option.DIV}} option. I advise against +using \DescRef{\LabelBase.cmd.areaset} for this purpose, however. In the +worst case, use the \Package{geometry} package% +\important{\Package{geometry}}\IndexPackage{geometry} (see +\cite{package:geometry}), which is not part of \KOMAScript, or change the page +layout parameters of \LaTeX{} yourself. You can find the values as determined +by \Package{typearea} in the \File{log} file of your document. The +\DescRef{typearea-experts.option.usegeometry}% +\important{\DescRef{typearea-experts.option.usegeometry}} option, which you +can find in \autoref{part:forExperts}, can also improve the interactions +between \Package{typearea} and \Package{geometry}. This should allow modest +adjustments. However, make sure that the proportions of the text area match +those of the page, taking the binding correction into account. + +If it is absolutely necessary to set the text with a line spacing of 1.5, do +not under any circumstances redefine \Macro{baselinestretch}. Although this +procedure is recommended all too frequently, it has been obsolete since the +introduction of {\LaTeXe} in 1994. In the worst case, use the +\Macro{linespread} command. I recommend the package +\Package{setspace}\important{\Package{setspace}}\IndexPackage{setspace} (see +\cite{package:setspace}), which is not part of \KOMAScript. You should also +let \Package{typearea} recalculate a new type area after changing the line +spacing. However, you should switch back to the normal line spacing for the +title, and preferably for the table of contents and various lists\,---\,as +well as the bibliography and the index. For details, see the explanation of +\OptionValueRef{\LabelBase}{DIV}{current}% +\important{\OptionValueRef{\LabelBase}{DIV}{current}}. + +The \Package{typearea} package, even with option +\OptionValueRef{\LabelBase}{DIV}{calc}% +\important{\OptionValueRef{\LabelBase}{DIV}{calc}}, calculates a very generous +text area. Many conservative typographers will find that the resulting line +length is still excessive. The calculated \Var{DIV} value may be found in the +\File{log} file for each document. So you can easily choose a smaller value +after the first {\LaTeX} run. + +Not\textnote{What is better?} infrequently I am asked why I dwell on type area +calculations for an entire chapter, when it would be much easier just to +provide a package with which you can adjust the margins as in a word +processor. Often it is said that such a package would be a better solution in +any case, since everyone knows how to choose appropriate margins, and that the +margins calculated by {\KOMAScript} are not that good anyway. I would like to +quote Hans Peter Willberg and Friedrich Forssmann, two of the most respected +contemporary typographers \cite{TYPO:ErsteHilfe}. (You can find the original +German in the German guide.) +\begin{quote} + \phantomsection\seclabel{tips.cite}% + \textit{The\textnote{Quote!} practice of doing things oneself has long been + widespread, but the results are often dubious because amateur typographers + do not see what is wrong and cannot know what is important. This is how + you get used to to incorrect and poor typography.} [\dots] \textit{Now the + objection could be made that typography is a matter of taste. When it + comes to decoration, one could perhaps accept that argument, but since + typography is primarily about information, not only can mistakes irritate, + but they may even cause damage.} +\end{quote} +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: |