diff options
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.tex | 197 |
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: |