diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/common-options.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/english/common-options.tex | 260 |
1 files changed, 138 insertions, 122 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-options.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-options.tex index 5d97ff8d26a..241a6f2200f 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-options.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-options.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-options.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % common-options.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,57 +46,55 @@ % ====================================================================== \KOMAProvidesFile{common-options.tex} - [$Date: 2016-11-14 21:06:12 +0100 (Mo, 14. Nov 2016) $ + [$Date: 2017-12-07 23:10:55 -0800 (Thu, 07 Dec 2017) $ KOMA-Script guide (common paragraphs)] -\translator{Gernot Hassenpflug\and Krickette Murabayashi} +\translator{Gernot Hassenpflug\and Krickette Murabayashi\and Karl Hagen} -% Date of the translated German file: 2017-06-23 +% Date of the translated German file: 2017-12-07 -\section{Early or late Selection of Options} +\section{Early or Late Selection of Options} \seclabel{options} \BeginIndexGroup \BeginIndex{}{options}% -\IfThisCommonFirstRun{}{% - All of what is described in - \autoref{sec:\ThisCommonFirstLabelBase.options} is generally - applicable. So if you have alread read and understood - \autoref{sec:\ThisCommonFirstLabelBase.options} you can switch to +\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}.% } -In this section a peculiarity of {\KOMAScript} is presented, which, apart -from % -\IfThisCommonLabelBase{typearea}{the \Package{typearea} package, is also - relevant to other {\KOMAScript} packages and classes}{% - \IfThisCommonLabelBase{maincls}{the classes \Class{scrbook}, - \Class{scrreprt}, and \Class{scrartcl} is also relevant to other - {\KOMAScript} classes and packages}{% - \IfThisCommonLabelBase{scrlttr2}{the class \Class{scrlttr2} is also - relevant to other {\KOMAScript} classes and packages}{% - \IfThisCommonLabelBase{scrextend}{the classes and the - \Package{scrextend} package is also relevant to several other - {\KOMAScript} packages}{% - \IfThisCommonLabelBase{scrhack}{the \Package{scrhack} package, is also - relevant to other \KOMAScript{} packages and classes}{% - \IfThisCommonLabelBase{scrjura}{the \Package{scrjura} package, is - also relevant to other \KOMAScript{} packages and classes}{% - \IfThisCommonLabelBase{scrlayer}{the \Package{scrlayer} package, - is also relevant to other \KOMAScript{} packages and classes}{% - \IfThisCommonLabelBase{scrlayer-scrpage}{the - \Package{scrlayer-scrpage} package, is also relevant to other - \KOMAScript{} packages and classes}{% - \IfThisCommonLabelBase{scrlayer-notecolumn}{the - \Package{scrlayer-notecolumn} package, is also relevant to - other \KOMAScript{} packages and classes}{% - \InternalCommonFileUsageError}}}}}}}}}% -. Such that the user can find all information corresponding to a single -package or a single class in the relevant chapter, this section is found -almost identically in several chapters. Users who are not only interested in a -particular package or class, but wish to gain an overview of {\KOMAScript} as -a whole, may read the section in one chapter and may thereafter skip it -wherever coming across it in the document. + \begin{Declaration} \Macro{documentclass}\OParameter{option list}% @@ -104,49 +102,59 @@ wherever coming across it in the document. \Macro{usepackage}\OParameter{option list}% \Parameter{package list} \end{Declaration} -In \LaTeX{}, provision is made for the user to pass class options as a -comma-separated list of keywords as optional arguments to -\Macro{documentclass}. -Apart from being passed to the class, -these options are also passed on to all packages which can understand -the options. Provision is also made for the user to pass optional -arguments as a comma-separated list of keywords as optional arguments -to \Macro{usepackage}. {\KOMAScript} -expands\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}\and \Package{scrextend}\and \Package{typearea}} the -option mechanism for the {\KOMAScript} classes and various packages to -use further possibilities. Thus, most {\KOMAScript} options can also -take a value. An option may have not only the form \PName{Option}, but -may also have the form \PName{option}\texttt{=}\PName{value}. Apart -from this difference \Macro{documentclass} and \Macro{usepackage} -function the same in {\KOMAScript} as described in -\cite{latex:usrguide} or any introduction to \LaTeX, for example +\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 +} - When using a {\KOMAScript} class, no options should be passed on -% Die Alternativen an dieser Stelle dienen der Verbesserung des Umbruchs - \IfThisCommonLabelBase{typearea}{unnecessary, explicit }{}% - loading of the \Package{typearea} or \Package{scrbase} packages. The reason - for this is that the class already loads these packages without options and - \LaTeX{} refuses multiple loadings of a package with different option - settings.% - \IfThisCommonLabelBaseOneOf{maincls,scrlttr2}{\ Actually, it is no longer - necessary when using any {\KOMAScript} class to explicity load either one - of these packages.}{}% -}{} - -You should note\textnote{Attention!}, that in opposite to the interface -described below the options interface of \Macro{documentclass} and -\Macro{usepackage} is not robust. So commands, lengths, counters and such -constructs may break inside the optional argument of these commands. Because -of this, the usage of a \LaTeX{} length inside the value of an option would -cause an error before \KOMAScript{} can get the control over the option -execution. So, if you want to use a \LaTeX{} length, counter or command as part -of the value of an option, you have to use +% Umbruchoptimierung!!! +\IfThisCommonLabelBase{typearea}{Setting the options with + \Macro{documentclass} or \Macro{usepackage} has one\textnote{Attention!} + major disadvantage: +}{% + Note that the \Macro{documentclass} and \Macro{usepackage} have one drawback + when using the option interface described bellow\textnote{Attention!}: +}% +unlike the interface described below, the options in \Macro{documentclass} and +\Macro{usepackage} are not robust. So commands, lengths, counters, and such +constructs may break inside the optional argument of these commands. For +example, using a \LaTeX{} length in the value of an option results in an error +before the value is passed to \KOMAScript{} 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 have to use \DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption}. These commands will be described next.% % @@ -157,58 +165,66 @@ of the value of an option, you have to use \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}} offers most class and package options the -opportunity to change the value of options even after loading of the -class or package. One may then change the values of a list of options -at will with the \Macro{KOMAoptions} command. Each option in the -\PName{option list} has the form -\PName{option}\texttt{=}\PName{value}. - -Some options also have a default value. If one does not give a value, -i.\,e., gives the option simply in the form \PName{option}, then the -default value will be used. - -Some options can assume several values simultaneously. For such options there -exists the possibility, with the help of \Macro{KOMAoption}, to pass a single -\PName{option} a list of values. The individual values are given as a -comma-separated \PName{value list}. +\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} - % If in the \PName{option list} one sets an option to a disallowed - % value, or the \PName{value list} contains an invalid value, then an - % error is produced. If \LaTeX{} is run in an interactive mode, then - % it stops at this point. Entering ``\texttt{h}'' displays a help - % screen, in which also the valid values for the corresponding option - % are given. - - % If a \PName{value} includes an equal sign or a comma, then the - % \PName{value} must be enclosed in curly brackets. - - To implement this possibility {\KOMAScript} uses the commands - \DescRef{scrbase.cmd.FamilyOptions} and \DescRef{scrbase.cmd.FamilyOption} - with the family ``\PValue{KOMA}''. -\iffalse % Umbruchkorrektur - More information on these commands % - \IfThisCommonLabelBase{maincls}{for experts }{% - \IfThisCommonLabelBase{scrlttr2}{for experts }{}}% - is found in \autoref{sec:scrbase.keyvalue}, - \DescPageRef{scrbase.cmd.FamilyOptions}. -\else - For more information in these commands see \autoref{part:forExperts}, - \autoref{sec:scrbase.keyvalue}, - \DescPageRef{scrbase.cmd.FamilyOptions}. -\fi + \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 -%%% coding: iso-latin-1 +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" %%% TeX-master: "../guide" -%%% End: +%%% End: |