% ======================================================================
% 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: 2023-07-31 15:38:10 +0200 (Mo, 31. Jul 2023) $
                  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{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,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: 
