summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/source-doc/english/common-options.tex
blob: b8c4d5fb70246d240c272cddf22f0a1b8b16831c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
% ======================================================================
% 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: 2019-10-09

\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
}{}

% The alternative text for wrapping optimization was redundant and, as
% it's not required for the English version, has been deleted.
Setting the options with \Macro{documentclass} has one\textnote{Attention!}
major disadvantage: unlike the interface described below, the options in 
\Macro{documentclass} are not robust. So commands, lengths, counters, and
similar 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: