summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/doc/common-options-en.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/common-options-en.tex')
-rw-r--r--macros/latex/contrib/koma-script/doc/common-options-en.tex197
1 files changed, 197 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/doc/common-options-en.tex b/macros/latex/contrib/koma-script/doc/common-options-en.tex
new file mode 100644
index 0000000000..638ea2a5d7
--- /dev/null
+++ b/macros/latex/contrib/koma-script/doc/common-options-en.tex
@@ -0,0 +1,197 @@
+% ======================================================================
+% common-options-en.tex
+% Copyright (c) Markus Kohm, 2001-2022
+%
+% 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.md.
+% ======================================================================
+%
+% Paragraphs that are common for several chapters of the KOMA-Script guide
+% Maintained by Markus Kohm
+%
+% ======================================================================
+
+\KOMAProvidesFile{common-options-en.tex}
+ [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $
+ KOMA-Script guide (common paragraphs)]
+\translator{Gernot Hassenpflug\and Krickette Murabayashi\and Karl Hagen}
+
+\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}.
+
+\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
+%%% TeX-master: "scrguide-en.tex"
+%%% coding: utf-8
+%%% ispell-local-dictionary: "en_GB"
+%%% eval: (flyspell-mode 1)
+%%% End: