% ====================================================================== % 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: