diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex | 1673 |
1 files changed, 879 insertions, 794 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex index a6f4778ea9c..714e020a933 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrbase.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-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. % ---------------------------------------------------------------------- % scrbase.tex -% Copyright (c) Markus Kohm, 2002-2017 +% Copyright (c) Markus Kohm, 2002-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,146 +46,106 @@ % ====================================================================== \KOMAProvidesFile{scrbase.tex} - [$Date: 2017-04-22 16:16:15 +0200 (Sat, 22 Apr 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script package scrbase] -\translator{Markus Kohm\and Melvin Hendrix} +\translator{Markus Kohm\and Melvin Hendrix\and Karl Hagen} -% Date of the translated German file: 2017-04-13 +% Date of the translated German file: 2018-02-15 -\chapter{Basic Functions of Package \Package{scrbase}} +\chapter{Basic Functions in the \Package{scrbase} Package} \labelbase{scrbase} \BeginIndexGroup \BeginIndex{Package}{scrbase}% -The package \Package{scrbase} provides basic features designed and implemented -for use by authors of packages and classes. However, \Package{scrbase} cannot -only by used for wrapper classes related to \KOMAScript{} class. Authors of -classes that have nothing to do with \KOMAScript{} can benefit from -\Package{scrbase} functionality. +The \Package{scrbase} package provides basic features intended for use by +authors of packages and classes. Its use is not limited merely to wrapper +classes which in turn load a \KOMAScript{} class. Authors of classes that +otherwise have nothing to do with \KOMAScript{} can also benefit from the +functionality of \Package{scrbase}. \section{Loading the Package} \seclabel{loadit} -Whereas users load packages using \Macro{usepackage}, authors of packages or +Whereas users load packages with \Macro{usepackage}, authors of packages or classes should use \Macro{RequirePackage}\IndexCmd{RequirePackage}. Authors of -wrapper packages may also use \Macro{RequirePackageWithOptions}. Command -\Macro{RequirePackage} has the same optional argument for package options like -\Macro{usepackage}. In contrast, \Macro{RequirePackageWithOptions} does not -have an optional argument but passes all options given when loading the -wrapper package to the required package. See \cite{latex:clsguide} for more -information about these commands. - -The package \Package{scrbase} needs the functionality of package -\Package{keyval}\IndexPackage{keyval} internally. This may be provided by -package \Package{xkeyval} alternatively. Package \Package{scrbase} loads -\Package{keyval} as needed. - -The package \Package{keyval} provides definition of keys and assignment of -values to these keys. The options provided by \Package{scrbase} also use -\Package{keyval} syntax: \PName{key}\texttt{=}\PName{value}. +wrapper packages can also use \Macro{RequirePackageWithOptions}. The +\Macro{RequirePackage} command has the same optional argument for package +options as \Macro{usepackage}. In contrast, \Macro{RequirePackageWithOptions} +does not have an optional argument but passes to this package all the options +that were previously given when loading the wrapper package or class. See +\cite{latex:clsguide} for more information about these commands. -\begin{Declaration} - \OptionVName{internalonly}{value} -\end{Declaration} -Package \Package{scrbase} provides some commands for conditional -execution. The primary names for these are builds like -\Macro{scr@\PName{name}}, which are internal commands. \KOMAScript{} only uses -these internal commands internally. Authors of packages and classes may use -these internal commands, too, but should not redefine them. Because some of -these commands are useful for users, too, they are provided as -\Macro{\PName{name}} normally. But eventually, other packages may provide -commands with the same name but different syntax or different -functionality. As this would result in an conflict, \Package{scrbase} can -suppress the definition of the user commands \Macro{\PName{name}}. Using -option \Option{internalonly} without \PName{value} will define only the -internal commands and suppress definition of all the user commands for -conditional execution. Alternatively, the user may give all the commands that -should not be defined as \PName{value}, but replaces ``\Macro{}'' by -``\texttt{/}''. - -Authors of packages and classes normally should not use this option. Users may -use it with or without \PName{value} either as a global option with -\Macro{documentclass} or using \Macro{PassOptionsToPackage}. -\begin{Example} - The user does not want \Package{scrbase} to define commands \Macro{ifVTeX} - and \DescRef{\LabelBase.cmd.ifundefinedorrelax}. Because of this, to load the class, the user - writes: -\begin{lstcode} - \documentclass% - [internalonly=/ifVTeX/ifundefinedorrelax]% - {foo} -\end{lstcode} - Class name \Class{foo} is, therefore, an placeholder - for any class in this example. The meanings of commands \Macro{ifVTeX} and - \DescRef{\LabelBase.cmd.ifundefinedorrelax} and many more commands for conditional execution - is located in \autoref{sec:scrbase.if}. -\end{Example} -% -\EndIndexGroup +The \Package{scrbase} package needs the functionality of the +\Package{keyval}\IndexPackage{keyval} package internally. This can also be +provided by the \Package{xkeyval} package. If needed, \Package{scrbase} itself +loads \Package{keyval}. + +The \Package{keyval} package lets you define keys and assign values to them. +The options provided by \Package{scrbase} also use \Package{keyval} syntax: +\PName{key}\texttt{=}\PName{value}. \section{Keys as Attributes of Families and their Members} \seclabel{keyvalue} As already mentioned in \autoref{sec:scrbase.loadit}, \Package{scrbase} uses -package \Package{keyval} for keys and values of keys. Nevertheless -\Package{scrbase} extends the functionality of \Package{keyval}. Whereas only -one family owns all keys of \Package{keyval}, \Package{scrbase} recognises -also family members. Therefore, a key may be owned by a family or by one or -more family members. Additionally, a value may be assigned to the key of a -family member, to the key of a family, or to the keys of all family members. +the \Package{keyval} package to set keys and their values. However, +\Package{scrbase} extends this functionality. Whereas with \Package{keyval} a +key belongs to only one family, \Package{scrbase} also recognizes family +members. A key can therefore belong to both a family and one or more family +members. Additionally, you can assign a value to the key of a family member, +to the key of a family, or to the keys of all family members. \begin{Declaration} \Macro{DefineFamily}\Parameter{family}% - \Macro{DefineFamilyMember}\OParameter{family member}\Parameter{family}% + \Macro{DefineFamilyMember}\OParameter{member}\Parameter{family}% \end{Declaration} -\Package{scrbase} needs to know the members of a family for different -reasons. First, you have to define a new family using -\Macro{DefineFamily}, which produces an empty member list. If the family -has already been defined nothing would happen. Nothing also means that an -already existing member list would not be overwritten. - -Next, a new member can be added to the family using -\Macro{DefineFamilyMember}. If the family does not exist, this would result in -an error message. If the member already exists, nothing happens. If the -optional \PName{family member} is omitted, the default value -``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is used. During -class or package loading \Macro{@currname} and \Macro{@currext} together -represent the file name of the class or package. +\Package{scrbase} needs to know the members of a family for various reasons. +Therefore, you must first define a new family using \Macro{DefineFamily}, +which produces an empty member list. If the family has already been defined, +nothing happens. Therefore an existing member list will not be overwritten. + +Next, you can add a new member to the family using \Macro{DefineFamilyMember}. +If the family does not exist, this will result in an error message. If the +member already exists, nothing happens. If the optional \PName{member} is +omitted, the default value +``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is used. While +the class or package is being loaded, \Macro{@currname} and \Macro{@currext} +together represent the file name of the class or package. Theoretically, it is possible, to define a member without a name using an -empty optional \PName{family member} argument. But this is the same as the -family itself. It is recommended that only letters and digits be used for -\PName{family} and the first character of \PName{family member} should not be -a letter or digit. Otherwise, it could happen that members of one family are -the same as members of another family. - -\Package{scrbase} assigns family ``\PValue{KOMA}'' to itself and adds member -``\PValue{.scrbase.sty}'' to it. Family ``\PValue{KOMA}'' is reserved to -\KOMAScript{}. For your own packages, use the name of the bundle as -\PName{family} and the name of the package as \PName{family member} of that -\PName{family}. +empty optional \PName{member} argument. But this is the same as the family +itself. You should use only letters and digits for the \PName{family} name, +and the first character of \PName{member} should be something else, preferably +a point. Otherwise, it could happen that the members of one family will clash +with the members of other families. + +\Package{scrbase} assigns the family ``\PValue{KOMA}'' to itself and adds the +member ``\PValue{.scrbase.sty}''. The values ``\PValue{KOMA}'' and +``\PValue{KOMAarg}'' are reserved for \KOMAScript{}. If you are creating a +bundle of packages, you should use the name of the bundle as \PName{family} +and the name of each package as \PName{member} of that \PName{family}. % \begin{Example} - Assume you are writing a bundle called ``master butcher''. Within that - bundle you have packages \File{salami.sty}, \File{liversausage.sty}, and - \File{kielbasa.sty}. Therefore, you decide to use family name - ``\PValue{butcher}'' and,to each of the package file, you add the lines + Suppose you are writing a bundle called ``master butcher''. Within that + bundle, you have the packages \File{salami.sty}, \File{mettwurst.sty}, + and \File{kielbasa.sty}. Therefore, you decide to use family name + ``\PValue{butcher}'' and you add the lines \begin{lstcode} \DefineFamily{butcher} \DefineFamilyMember{butcher} \end{lstcode} - When loading the three packages, this will - add the members ``\PValue{.salami.sty}'', ``\PValue{.liversausage.sty}'', + to each of the package files. When loading the three packages, this will + add the members ``\PValue{.salami.sty}'', ``\PValue{.mettwurst.sty}'', and ``\PValue{.kielbasa.sty}'' to the family ``\PValue{butcher}''. After - loading all three packages, all three member will be defined. + loading all three packages, all three members will be defined. \end{Example} % \EndIndexGroup \begin{Declaration} - \Macro{DefineFamilyKey}\OParameter{family member}\Parameter{family}% + \Macro{DefineFamilyKey}\OParameter{member}\Parameter{family}% \Parameter{key}% \OParameter{default}\Parameter{action}% \Macro{FamilyKeyState}% @@ -194,71 +154,77 @@ the same as members of another family. \Macro{FamilyKeyStateUnknownValue}% \Macro{FamilyKeyStateNeedValue} \end{Declaration} -The command \Macro{DefineFamilyKey} defines a \PName{key}. If a \PName{family - member} is given, the \PName{key} becomes an attribute of that member in the -given \PName{family}. If a \PName{family member} is not given, the member -``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is assumed. If, -later, a value is assigned to the \PName{key}, the \PName{action} will be -executed and the value made an argument of \PName{action}. So inside -\PName{action} ``\lstinline{#1}'' would be that value. If the value is -omitted, the \PName{default} is used instead. If there is no \PName{default}, -the \PName{key} can be used only with a value being defined. - -\begin{Explain} +The \Macro{DefineFamilyKey} command defines a \PName{key}. If you specify a +\PName{member}, the \PName{key} becomes an attribute of that member in the +given \PName{family}. If you do not specify a \PName{member}, the member +``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is assumed. If you +later assign a value to the \PName{key}, the \PName{action} will be +executed and the value made an argument of \PName{action}. Within +\PName{action}, ``\lstinline{#1}'' stands for that value. If you omit the value, +the \PName{default} is used instead. If you do not specify a \PName{default}, +the \PName{key} then always requires you to pass an explicit value. + +%\begin{Explain} \phantomsection\label{explain:scrbase.macro.DefineFamilyKey}% - At least + Ultimately, \begin{lstcode}[escapeinside=`'] \DefineFamilyKey[`\PName{member}']{`\PName{family}'}{`\PName{key}'} [`\PName{default}']{`\PName{action}'} \end{lstcode} - will result in a call of + results in a call to \begin{lstcode}[moretexcs={define@key},escapeinside=`'] \define@key{`\PName{family\,member}'}{`\PName{key}'} [`\PName{default}']{`\PName{extended action}'} \end{lstcode} - with \Macro{define@key} provided by package - \Package{keyval}\IndexPackage{keyval} (see \cite{package:keyval}). However, - the call of \Macro{define@key} and the \PName{action} is, in fact, - extended by additional arrangements. -\end{Explain} - -Success\ChangedAt{v3.12}{\Package{scrbase}} or failure of the execution of the -\PName{action} should be reported back to \Package{scrbase} by -\Macro{FamilyKeyState}. The package itself will take care of additional -procedures if needed. You should not report errors by yourself! The default -state before execution of \PName{action} is -\Macro{FamilyKeyStateUnknown}. This signals that it is not known whether or -not the execution is successful. If this state does not change until end of -execution of the \PName{action}, \Package{scrbase} will write a message into -the \File{log} file and assumes state \Macro{FamilyKeyStateProcessed} during -the further procedure. - -State \Macro{FamilyKeyStateProcessed} signals that the option and the value -assignment to the option are completely and successfully finished. You may -switch to this state by using \Macro{FamilyKeyStateProcessed} itself. - -State \Macro{FamilyKeyStateUnknownValue} indicates that the option was -handled, but the value, that should be assigned to the key, was unknown or not -allowed. You should use \Macro{FamilyKeyStateUnknownValue} to switch to -this state. - -State \Macro{FamilyKeyStateNeedValue} signals that the option could not be -set because it needs a value, but no value was assigned to the -key. This state is used automatically, whenever an option has been -defined without \PName{default} value and is used without value -assignment. You should not set the state using \Macro{FamilyKeyStateNeedValue} -yourself. - -Last but not least you may switch to additional failure states, simply -re-defining \Macro{FamilyKeyState} with a very short text message. -Generally, the four predefined states should be sufficient. + where \Macro{define@key} is provided by the + \Package{keyval}\IndexPackage{keyval} package (see \cite{package:keyval}). + However, there are some additional precautions taken with the call to + \Macro{define@key}, and the \PName{action} will be extended to include these + precautions. +%\end{Explain} + +Success\ChangedAt{v3.12}{\Package{scrbase}} or failure in executing the +\PName{action} should be reported back to \Package{scrbase} through +\Macro{FamilyKeyState} so that the package itself can take further action as +needed. This could be, for example, an error message or merely warning of an +unknown option. You should not report errors directly! + +The default state of \PName{action} before execution is +\Macro{FamilyKeyStateUnknown}. This indicates that it is not known whether or +not the key could be processed successfully. If this state remains unchanged +after the \PName{action} has been executed, \Package{scrbase} writes a +message to the \File{log} file and assumes the that state is +\Macro{FamilyKeyStateProcessed}. + +The \Macro{FamilyKeyStateProcessed} state indicates that the key and the value +assigned to it have been successfully processed and everything is OK. You can +switch to this state by calling \Macro{FamilyKeyStateProcessed} itself. + +The \Macro{FamilyKeyStateUnknownValue} state indicates that the key has been +processed but that the value passed to it was either unknown or not allowed. +For example, \hyperref[cha:typearea]{\Package{typearea}} reports this +condition if you try to set the \DescRef{typearea.option.twoside} option to +\PValue{unknown}. You can set this state by simply calling +\Macro{FamilyKeyStateUnknownValue}. + +The \Macro{FamilyKeyStateNeedValue} state indicates that the key could not be +processed because it expects a value, but it was called without such a value. +This state is set automatically if you use a key that does not have a +\PName{default} value without assigning a value. Theoretically, you could +set this state explicitly with \Macro{FamilyKeyStateNeedValue}, but you should +not need to set it yourself. + +In addition, you can define additional error conditions by redefining +\Macro{FamilyKeyState} with a short text message. Generally, however, the four +predefined states should be sufficient. \begin{Example} - Assume each of the three packages from the previous example should get a - key named \PValue{coldcuts}. When used, a switch is set at each of - the packages. For package \Package{salami} this may be: + Suppose each of the three packages from the previous example should have a + key named \PValue{coldcuts}. When used, a switch should be set in each of + the packages. For the \Package{salami} package, for example, this could look + like this: \begin{lstcode} - \newif\if@Salami@Aufschnitt + \newif\if@salami@coldcuts \DefineFamilyKey{butcher}% {coldcuts}[true]{% \expandafter\let\expandafter\if@salami@coldcuts @@ -266,67 +232,75 @@ Generally, the four predefined states should be sufficient. \FamilyKeyStateProcessed } \end{lstcode} - Available values for the key are \PValue{true} or \PValue{false} in this - case. Instead of testing on inappropriate values, success will be signalled - for any case in this example. If the key is used later, it is executed with - one of the allowed values or without assignment. In the second case, the - default \PName{true} will be used. - - The definitions in the other packages are similar. Only ``\texttt{salami}'' - has to be replaced by the corresponding names. + When called, the value will therefore be either \PValue{true} or + \PValue{false}. This example does not test for illegal values. Instead, + it is always reported that the key was processed completely and correctly. + If the key is used later, one of the permitted values, or no value, must be + used. In the second case, the default \PName{true} value will be used. + + The definitions for the other packages are similar. Only ``\texttt{salami}'' + has to be replaced by the respective names. \end{Example} % \EndIndexGroup \begin{Declaration} - \Macro{RelaxFamilyKey}\OParameter{family member}\Parameter{family}% + \Macro{RelaxFamilyKey}\OParameter{member}\Parameter{family}% \Parameter{key} \end{Declaration} -If\ChangedAt{v3.15}{\Package{scrbase}} the \PName{key} of the \PName{family - member} of \PName{family} has been defined before, that definition will be -cancelled. Afterwards the \PName{key} will not be defined for the \PName{family - member} of \PName{family} any longer. Usage of \Macro{RelaxFamilyKey} for a -not yet defined \PName{key} of the \PName{family member} of the \PName{family} -is also allowed.% +If\ChangedAt{v3.15}{\Package{scrbase}} a \PName{key} has been previously +defined as a \PName{member} of a \PName{family}, that definition will be +cancelled. Afterwards the \PName{key} will no longer be defined for this +\PName{member} of the \PName{family}. You can use \Macro{RelaxFamilyKey} for a +\PName{key} that is not defined for this \PName{member} of the \PName{family}. + +If you do not specify a \PName{member}, then the member +``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is assumed, just as +with \DescRef{\LabelBase.cmd.DefineFamilyKey}. However, \Macro{RelaxFamilyKey} +is only rarely used while loading a package rather than at runtime. Therefore +the \PName{member} should usually be specified explicitly as well.% \EndIndexGroup \begin{Declaration} - \Macro{FamilyProcessOptions}\OParameter{family member}\Parameter{family} + \Macro{FamilyProcessOptions}\OParameter{member}\Parameter{family} \end{Declaration} -Generally the extension of keys of families to keys of families and family -members, as mentioned earlier, uses keys or key-value settings as class or -package options. The command \Macro{FamilyProcessOptions} is an extension of -\Macro{ProcessOption*} from \LaTeX{} kernel (see \cite{latex:clsguide}, which -processes not only options that has been declared using \Macro{DeclareOption}, -it processes all keys of the given family member. If the optional argument -\PName{family member} is omitted, family member +In essence, extending keys from families to both families and family members +means that either keys or key-value pairs can be used as normal class or +package options. The \Macro{FamilyProcessOptions} command is an extension of +\Macro{ProcessOption*} from the \LaTeX{} kernel (see \cite{latex:clsguide}, +which processes not only options declared with \Macro{DeclareOption}, but also +all keys of the given member. If you omit the optional argument +\PName{member}, the member ``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is used. -Somehow special are keys that are not attached to a family member, but to a -family. These are keys with an empty family member. Such keys are set before -the keys of the family members. +One feature worth noting is that keys which are attached not to a family +member but to a family have an empty family member. Such keys are set before +the keys of the members. \begin{Example} - If a package in the previous example would be extended by the line + If, in the packages from the previous example, you add the line \begin{lstcode} \FamilyProcessOptions{butcher} \end{lstcode} - then the user may select the option \Option{coldcuts} when loading the - package. If the option is used globally, this means at the optional - argument of \Macro{documentclass}, then the option would be passed - automatically to all three packages, if all three packages are loaded - later. + after you define the key, you can specify the \Option{coldcuts} option when + loading the package. If you specify the option globally in + \Macro{documentclass}, the option will be passed automatically to all three + packages if they are loaded later. \end{Example} -Please note\textnote{Attention!} that packages always process global options -before local options. When processing unknown options initiate an entry in the -\File{log}-file and the option is otherwise ignored. By contrast, unknown -options assigned to the package locally leads to an error message. +Note\textnote{Attention!} that packages always process global options +before local options. While unknown global options result in an entry in the +\File{log} file and the option being otherwise ignored, unknown local +options result in an error message. -\Macro{FamilyProcessOptions} may be interpreted either as an extension of -\Macro{ProcessOption*} or as an extension of the \PName{key=value} mechanism +You can think of \Macro{FamilyProcessOptions} as an extension of either +\Macro{ProcessOption*} or the \PName{key=value} mechanism of \Package{keyval}. Ultimately, with the help of \Macro{FamilyProcessOptions}, \PName{key=value} pairs become options.% + +As with\textnote{Attention!} \Macro{ProcessOptions}, +\Macro{FamilyProcessOptions} must not be used while executing options code. +In particular, you cannot load packages while processing options.% % \EndIndexGroup @@ -335,60 +309,60 @@ of \Package{keyval}. Ultimately, with the help of \Macro{BeforeFamilyProcessOptions}\OParameter{member}\Parameter{family}% \Parameter{code}% \end{Declaration} -Especially\ChangedAt{v3.18}{\Package{scrbase}} authors of wrapper classes or -wrapper packages sometimes need a hook to execute \PName{code} just before -\DescRef{\LabelBase.cmd.FamilyProcessOptions}. The package \Package{scrbase} -provides such a hook and you can add \PName{code} to it using -\Macro{BeforeFamilyProcessOptions}. The parameters \PName{member} and -\PName{family} are same to \DescRef{\LabelBase.cmd.FamilyProcessOptions}. In -difference to \DescRef{\LabelBase.cmd.FamilyProcessOptions} you can add -\PName{code} also to the hook of not yet defined \PName{family} or -\PName{member}. - -Note, the hook of a family member will be cleaned after execution. But if you -use an empty \PName{member} the \PName{code} will be executed before the -\DescRef{\LabelBase.cmd.FamilyProcessOptions} of every member of the \PName{family} and will -never be deleted. +Authors\ChangedAt{v3.18}{\Package{scrbase}} of wrapper classes in particular +sometimes need a hook to execute \PName{code} before +\DescRef{\LabelBase.cmd.FamilyProcessOptions}. The \Package{scrbase} package +provides such a hook, and you can add \PName{code} to it with +\Macro{BeforeFamilyProcessOptions}. The \PName{member} and \PName{family} +parameters are same as those of \DescRef{\LabelBase.cmd.FamilyProcessOptions}. +However, you can also add \PName{code} to the hook for families or members +that have not yet been defined. + +Note that the hook of a family member is automatically deleted after it is +executed. But if you use an empty \PName{member}, this hook\Index{hook} will +be executed for every member of the \PName{family} and will not be deleted. \begin{Example} - Now, you are writing a package that loads \Package{liversausage}. But you do - not provide option \Option{coldcut} with this package. So you use - \Macro{BeforeFamilyProcessOptions} to deactivate - that option before loading the package: + You are writing a \Package{smokedsausage} package that loads + \Package{mettwurst}. But you do not want to be able to set the + \Option{coldcut} option with this package. So you use + \Macro{BeforeFamilyProcessOptions} to deactivate that option before you load + the package: \begin{lstcode} \RequirePackage{scrbase} - \BeforeFamilyProcessOptions[.liversausage.sty]{butcher}{% - \RelaxFamilyKey[.liversausage.sty]{butcher}{coldcut}% + \BeforeFamilyProcessOptions[.mettwurst.sty]{butcher}{% + \RelaxFamilyKey[.mettwurst.sty]{butcher}{coldcut}% } - \RequirePackageWithOptions{liversausage} + \RequirePackageWithOptions{mettwurst} \end{lstcode} - If after this a user tries to load your package with option - \Option{coldcut}, package \Package{liversausage} will throw an undefined - option error. If \Option{coldcut} is used as a global option, package - \Package{liversausage} will ignore it. But default settings inside - \Package{liversausage}, e.\,g., using \DescRef{\LabelBase.cmd.FamilyExecuteOptions} before - \DescRef{\LabelBase.cmd.FamilyProcessOptions} are not effected. + If a user tries to load your package with the \Option{coldcut} option, the + \Package{mettwurst} package will throw an undefined option error. If + \Option{coldcut} is used as a global option, the \Package{mettwurst} + package will ignore it. But default settings inside \Package{mettwurst}, + for example using \DescRef{\LabelBase.cmd.FamilyExecuteOptions} before + \DescRef{\LabelBase.cmd.FamilyProcessOptions} are not affected. Of course, + you can also insert your own default for \Package{smokedsausage} via + \Macro{BeforeFamilyProcessOptions} in \Package{mettwurst}. \end{Example} \EndIndexGroup \begin{Declaration} - \Macro{FamilyExecuteOptions}\OParameter{family member}\Parameter{family}% + \Macro{FamilyExecuteOptions}\OParameter{member}\Parameter{family}% \Parameter{options list} \end{Declaration} This command is an extension of \Macro{ExecuteOptions} from the \LaTeX{} kernel (see \cite{latex:clsguide}). The command processes not only options -that are defined using \Macro{DeclareOption}, but also processes all keys of -the given \PName{family member}. If the optional argument \Macro{family - member} is omitted, then +defined with \Macro{DeclareOption} but also all keys of the given +\PName{family}. If you omit the optional argument \Macro{member}, ``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' is used. -Somehow special are keys of empty family members, which are not attached to a -family member, but to a family. Such keys are set before the keys of family -members. +One feature worth noting is that keys which are attached not to a family +member but to a family have an empty family member. Such keys are set before +the keys of the members. \begin{Example} - Assume option \Option{coldcuts} should be set by default in the - previous example. In this case only line + Suppose the \Option{coldcuts} option should be set by default in the + previous examples. In this case only line \begin{lstcode} \FamilyExecuteOptions{butcher}{coldcuts} \end{lstcode} @@ -396,14 +370,15 @@ members. \end{Example} If\ChangedAt{v3.20}{\Package{scrbase}} you call \Macro{FamilyExecuteOptions} -with an unknown option inside the \PName{options list}, you will get an -error. But you will not get an error, if the \PName{family member} has an -option \Option{@else@}. In this case option \Option{@else@} will be used -instead of the unknown option. \KOMAScript{} itself uses this feature, e.\,g., -inside the definition of section like commands to prior the style attribute -above all other attributes. - -Usage of the command inside the execution of an option is provided.% +with an unknown option inside the \PName{options list}, you will get an error. +An exception to this rule occurs when the \PName{member} has an option called +\Option{@else@}. In this case, the \Option{@else@} option will be used instead +of the unknown option. \KOMAScript{} itself uses this feature, for example +inside the definition of sectioning commands, to evaluate the style option +before all other attributes. + +You can also use this command inside the code executed when processing the +option.% % \EndIndexGroup @@ -411,27 +386,27 @@ Usage of the command inside the execution of an option is provided.% \begin{Declaration} \Macro{FamilyOptions}\Parameter{family}\Parameter{options list}% \end{Declaration} -Hence \PName{options list} is like: +Unlike normal options defined with \Macro{DeclareOption}, the \PName{key}s can +also be set after loading a class or package. To do this, you call +\Macro{FamilyOptions}. The \PName{options list} has the form \begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} \PName{key}\texttt{=}\PName{value}\texttt{,}% \PName{key}\texttt{=}\PName{value}\dots \end{tabular}\vskip\dp\strutbox\end{flushleft} -after which the value assignment may be omitted for \PName{key}s that have a +after which the value assignment can be omitted for \PName{key}s that have a defined default. -In contrast to average options that are defined using \Macro{DeclareOption}, -the \PName{key}s also may be set after loading a class or package. For this, -the user calls \Macro{FamilyOptions}. Thereafter, the \PName{key}s of all -members of the specified family are set. If a \PName{key} also exists as a -family attribute, then the family key is set first. After this, the member -keys follow in the order in which the members have been defined. If a given -\PName{key} does not exist, either for the family or for any member of the -family, then \Macro{FamilyOptions} will result in an error. Package -\Package{scrbase} reports an error also if there are members with key -\PName{key}, but all those members signal failure via \DescRef{\LabelBase.cmd.FamilyKeyState}. +The statement sets the keys of all members of the specified family. If a +\PName{key} also exists as an attribute of the family itself, then the family +key is set first, followed by the member keys in the order in which they were +defined. If a given \PName{key} does not exist, either for the family or for +any member of the family, then \Macro{FamilyOptions} will throw an error. An +error also occurs if a \PName{key} exists for some members but each of those +members returns an error through \DescRef{\LabelBase.cmd.FamilyKeyState}. \begin{Example} - You extend your butcher project by a package \Package{sausagesalad}. If this - package has been loaded, all sausage package should generate cold cuts: + You extend your butcher project with a \Package{sausagesalad} package. If + this package has been loaded, all sausage packages should generate cold + cuts: \begin{lstcode} \ProvidesPackage{sausagesalad}% [2008/05/06 nonsense package] @@ -440,16 +415,16 @@ family, then \Macro{FamilyOptions} will result in an error. Package \FamilyProcessOptions{butcher}\relax \FamilyOptions{butcher}{coldcuts} \end{lstcode} - If currently none of the sausage packages are loaded, the undefined option - \Option{coldcuts} leads to an error message. This is avoided by adding - before the last line of the code above: + If no sausage package has yet been loaded, the undefined option + \Option{coldcuts} leads to an error message. You can avoid this by defining + a corresponding key for the package before the last line of the code above: \begin{lstcode} \DefineFamilyKey{butcher}% {coldcuts}[true]{}% \end{lstcode} - However, sausage packages loaded after - \Package{sausagesalad} still do not produce cold cuts. This may be corrected - by editing the last line of the code again to: + However, sausage packages loaded after \Package{sausagesalad} still do not + produce cold cuts. You can correct this by replacing the previous command + with: \begin{lstcode} \AtBeginDocument{% \DefineFamiyKey[.sausagesalad.sty]% @@ -462,39 +437,45 @@ family, then \Macro{FamilyOptions} will result in an error. Package {coldcuts=#1}}% }% \end{lstcode} - This code does following: First the option will be defined while - \Macro{begin}\PParameter{document} to do nothing for package - \Package{sausagesalad}. Because \Macro{@currname} and \Macro{@currext} are - not longer valid at this time, the optional argument on - \DescRef{\LabelBase.cmd.DefineFamilyKey} has to be used. But until this re-definition of the - option, a second definition is made, that calls the option again while - \Macro{begin}\PParameter{document} for the whole family and so also for - other sausage salad packages. + Thus, the option is defined during \Macro{begin}\PParameter{document} so + that it no longer functions for the \Package{sausagesalad} package. Because + \Macro{@currname} and \Macro{@currext} no longer contain the file name of + the package, you must use the optional argument of + \DescRef{\LabelBase.cmd.DefineFamilyKey}. + + But until this redefinition is performed, it uses a definition that executes + the option again for the family and all its members during + \Macro{begin}\PParameter{document}, thus setting it for other sausage + packages. The delay in executing \Macro{FamilyOptions} is crucial here. For + one thing, it includes only the packages loaded afterwards. For another, it + ensures that its own \Option{coldcuts} option has already been redefined. + This avoids endless recursion. \end{Example} % \EndIndexGroup +\vskip-\ht\strutbox% Umbruchkorrektur wegen Beispiel am Ende \begin{Declaration} \Macro{FamilyOption}\Parameter{family}% - \Parameter{option}\Parameter{values list}% + \Parameter{option}\Parameter{value list}% \end{Declaration} -Besides options that have concurrently excluding values, there may be options -that produce several values at the same time. Using \DescRef{\LabelBase.cmd.FamilyOptions} for -that type of option would result in using the same option several times with -different value assignments. Instead of this, \Macro{FamilyOption} may be used -to assign a whole \PName{values list} to the same \PName{option}. The -\PName{values list} is a comma separated list of values, also known as -\emph{csv}: -\begin{flushleft}\begin{tabular}{l} +In addition to options that have mutually exclusive values, there may be +options that can take multiple values at the same time. To use +\DescRef{\LabelBase.cmd.FamilyOptions} for that type of option, it would be +necessary to invoke the same option several times with different value +assignments. Instead, you can easily assign a whole list of values to a single +\PName{option} using \Macro{FamilyOption}. The \PName{value list} is a comma +separated list of values, also known as \emph{csv}: +%\begin{flushleft}\begin{tabular}{l} \PName{value}\texttt{,}\PName{value}\dots -\end{tabular}\end{flushleft} -By the way, please note that usage of a comma inside a value may be done only -if the value is put inside braces. The general functionality of this command -is the same as that of the previous command \DescRef{\LabelBase.cmd.FamilyOptions}. +%\end{tabular}\end{flushleft} +Note in this context that you can use a comma in a value by putting the value +inside braces. This command's other functionality is the same previously +described for \DescRef{\LabelBase.cmd.FamilyOptions}. \begin{Example} - Package \Package{sausagesalad} should have one mire option, to add - additional ingredients. Each of the ingredients sets a switch as was done + The \Package{sausagesalad} package should have one more option to add + additional ingredients. Each of the ingredients sets a switch, as was done previously for the cold cuts. \begin{lstcode} \newif\if@saladwith@onions @@ -505,15 +486,14 @@ is the same as that of the previous command \DescRef{\LabelBase.cmd.FamilyOption } \end{lstcode} Here the three ingredients ``onions'', ``gherkins'', and ``chillies'' have - been defined. An error message for ``not defined'' ingredients does not - exist. + been defined. There is no error message for unknown ingredients. - For a salad with onions and gherkins the user may use + For a salad with onions and gherkins, you can use \begin{lstcode} \FamilyOptions{butcher}{% ingredient=onions,ingredient=gherkins} \end{lstcode} - or shorter + or simply \begin{lstcode} \FamilyOption{butcher} {ingredient}{onions,gherkins} @@ -530,63 +510,65 @@ is the same as that of the previous command \DescRef{\LabelBase.cmd.FamilyOption Sometimes\ChangedAt{v3.12}{\Package{scrbase}} it is useful to delay the execution of an \PName{action} that is part of a value assignment to a key until all assignments inside one -\DescRef{\LabelBase.cmd.FamilyProcessOptions}, -\DescRef{\LabelBase.cmd.FamilyExecuteOptions}, -\DescRef{\LabelBase.cmd.FamilyOptions}, or -\DescRef{\LabelBase.cmd.FamilyOption} is finished. This may be done using -\Macro{AtEndOfFamilyOptions} or its star -variation\ChangedAt{v3.23}{\Package{scrbase}} inside an option -definition. Reporting failure states of \PName{action} is not possible in this -case. Furthermore, the command should not be used outside an option -definition. - -The variations differ in cases when execution of an option results in further -option calls. In this case all actions of \Macro{AtEndOfFamilyOptions} will be -executed when the inner-most option call returns. The actions of -\Macro{AtEndOfFamilyOptions*} will be executed when the top-most option call -returns. Nevertheless, the order of the actions of both commands is -undefined!% +\DescRef{\LabelBase.cmd.FamilyProcessOptions}\IndexCmd{FamilyProcessOptions}, +\DescRef{\LabelBase.cmd.FamilyExecuteOptions}\IndexCmd{FamilyExecuteOptions}, +\DescRef{\LabelBase.cmd.FamilyOptions}\IndexCmd{FamilyOptions}, or +\DescRef{\LabelBase.cmd.FamilyOption}\IndexCmd{FamilyOptions} is finished. +You can do this using \Macro{AtEndOfFamilyOptions} or its starred +variant\ChangedAt{v3.23}{\Package{scrbase}} inside an option definition. +However, reporting failure states of \PName{action} is not possible with this +command, nor should it be used outside an option definition. + +The two variants differ in case there are nested option definitions, when +executing an option requires further option calls. In this case all actions +specified by \Macro{AtEndOfFamilyOptions} will be executed when the innermost +option call returns. In contrast, the actions of \Macro{AtEndOfFamilyOptions*} +are not executed until the outermost option call returns. +However,\textnote{Attention!} the order of the actions of both commands is +emphatically undefined! It is not guaranteed that the action requested first +will be executed first, nor the converse.% \EndIndexGroup \begin{Declaration} - \Macro{FamilyBoolKey}\OParameter{family member}\Parameter{family}% + \Macro{FamilyBoolKey}\OParameter{member}\Parameter{family}% \Parameter{key}\Parameter{switch name}% \Macro{FamilySetBool}\Parameter{family}% \Parameter{key}\Parameter{switch name}\Parameter{value} \end{Declaration} -In the previous examples, boolean switches often have been used. In the example -with option \Option{coldcuts}, it is necessary that the user assigns either -value \PValue{true} or value \PValue{false}. There is no error message for -wrong value assignment. Because of this, boolean switches are a necessary -feature. Package \Package{scrbase} provides \Macro{FamilyBoolKey} for definition of -such options. Therefore, the arguments \PName{family member}, \PName{family}, and -\PName{key} are the same as that used by \DescRef{\LabelBase.cmd.DefineFamilyKey} (see -\DescPageRef{scrbase.cmd.DefineFamilyKey}). Argument \PName{switch name} -is the name of the switch without the prefix \Macro{if}. If a switch with this -name does not exist already, \Macro{FamilyBoolKey} will define it and -initialize it to \PName{false}. Internally \Macro{FamilyBooKey} uses -\Macro{FamilySetBool} as \PName{action} of \DescRef{\LabelBase.cmd.DefineFamilyKey}. The -\PName{default} for those options is always \PValue{true}. - -On the other hand, \Macro{FamilySetBool} understands \PName{value} \PValue{on} -and \PValue{yes} beside \PName{true} for switching on and \PName{off} and -\PName{no} beside \PName{false} for switching off. Unknown values will result -in a call of \DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} with the arguments -\PName{family}, \PName{key}, and \PName{value}, which results in setting of -\DescRef{\LabelBase.cmd.FamilyKeyState}. Depending on the command used and -other family members, this may result in an error message about unknown value -assignment (see also \DescPageRef{scrbase.cmd.FamilyUnknownKeyValue} and +Boolean switches have been used several times in the previous examples. In the +example with \Option{coldcuts} option, the user had to assign either +\PValue{true} or \PValue{false} as a value. There was no error message if the +user provided the wrong value. Because boolean switches are a common use case, +you can easily define them with \Package{scrbase} using \Macro{FamilyBoolKey}. +The \PName{member}, \PName{family}, and \PName{key} arguments are the same as +those used by \DescRef{\LabelBase.cmd.DefineFamilyKey} (see +\DescPageRef{scrbase.cmd.DefineFamilyKey}). The \PName{switch name} is the +name of the switch without the prefix \Macro{if}. If a switch with this name +does not exist already, \Macro{FamilyBoolKey} will define it and initialize it +to \PName{false}. Internally, \Macro{FamilyBooKey} uses \Macro{FamilySetBool} +as the \PName{action} of \DescRef{\LabelBase.cmd.DefineFamilyKey}. The +\PName{default} for such an option is always \PValue{true}. + +\Macro{FamilySetBool}, on the other hand, accepts \PValue{on} and +\PValue{yes}, in addition to \PName{true}, to turn the switch on, and +\PName{off} and \PName{no}, in addition to \PName{false}, to turn it off. +Unknown values will result in a call to +\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} with the arguments +\PName{family}, \PName{key}, and \PName{value}, which sets +\DescRef{\LabelBase.cmd.FamilyKeyState} accordingly. As a result, an error +message about an unknown value assignment is printed if necessary (see also +\DescPageRef{scrbase.cmd.FamilyUnknownKeyValue} and \DescPageRef{scrbase.cmd.FamilyKeyState}). \begin{Example} - The key \Option{coldcuts} should be declared somehow more - robust. Additionally, all sausage packages should use the same key. So - either all or none of them will produce cold cuts. + The key \Option{coldcuts} should be defined more robustly in the sausage + packages. Additionally, all sausage packages should use the same key, so + that either all sausage packages will produce cold cuts or none will. \begin{lstcode} \FamilyBoolKey{butcher}{coldcuts}% {@coldcuts} \end{lstcode} - A test, whether or not to produce cold cuts, may be: + A test of whether to produce cold cuts would look like this: \begin{lstcode} \if@coldcuts ... @@ -594,7 +576,7 @@ assignment (see also \DescPageRef{scrbase.cmd.FamilyUnknownKeyValue} and ... \fi \end{lstcode} - This would be the same in each of the three sausage packages, thereby + This would be the same in all three sausage packages, thereby defining the attribute ``coldcuts'' as a family option: \begin{lstcode}[moretexcs={define@key}] \@ifundefined{if@coldcuts}{% @@ -611,55 +593,71 @@ assignment (see also \DescPageRef{scrbase.cmd.FamilyUnknownKeyValue} and \FamilyBoolKey[]{butcher}{coldcuts}% {@coldcuts} \end{lstcode} - using the additional information at - \autopageref{explain:scrbase.macro.DefineFamilyKey}, this is not only valid - for \DescRef{\LabelBase.cmd.DefineFamilyKey} but for \Macro{FamilyBoolKey} too. + taking advantage of the treatment of empty family members as opposed to + omitting the optional argument explained on + \autopageref{explain:scrbase.macro.DefineFamilyKey}, which applies not only + to \DescRef{\LabelBase.cmd.DefineFamilyKey} but also for + \Macro{FamilyBoolKey}. + + Since \DescRef{\LabelBase.cmd.FamilyKeyState} is already set by + \Macro{FamilySetBool}, you can check its status with the help of + \DescRef{\LabelBase.cmd.DefineFamilyKey}. For example, in the first case you + could add an equivalence test to \Macro{FamilySetBool} to perform additional + actions depending on whether \Macro{FamilySetBool} succeeded or not: + \begin{lstcode} + \ifx\FamilyKeyState\FamilyKeyStateProcessed + ... + \else + ... + \fi + \end{lstcode} + Note\textnote{Attention!} that it is essential to perform the test with + \Macro{ifx} at this point. Fully expanding tests like \Macro{ifstr} should + be avoided here. Depending on the current status and the comparison status, + they can lead to different error messages as well as incorrect results. \end{Example} % \EndIndexGroup \begin{Declaration} - \Macro{FamilyNumericalKey}\OParameter{family member}\Parameter{family}% + \Macro{FamilyNumericalKey}\OParameter{member}\Parameter{family}% \Parameter{key}% \OParameter{default}\Parameter{command}% - \Parameter{values list}% + \Parameter{value list}% \Macro{FamilySetNumerical}\Parameter{family}\Parameter{key}% - \Parameter{command}\Parameter{values list}% + \Parameter{command}\Parameter{value list}% \Parameter{value} \end{Declaration} -In contrast to switches that may be either true or false, a key exists -that accept several values. For example an alignment may not only be left or -not left, but left, centered, or right. Internally such -differentiation often is made using \Macro{ifcase}. This \TeX{} command -expects a numerical value. Because of this the command to define a macro by -a \PName{key} has been named \Macro{FamilyNumericalKey} in -\Package{scrbase}. The \PName{values list} thereby has the form: -\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} - \Parameter{value}\Parameter{definition}\texttt{,}% - \Parameter{value}\Parameter{definition}\texttt{,}% - \dots -\end{tabular}\vskip\dp\strutbox\end{flushleft} -Therefore, the \PName{values list} does not solely define the supported values to the -\PName{key}. For each of the \PName{value}s, the -\PName{definition} of macro \Macro{\PName{command}} also is given. Usually, -\PName{definition} is just a numerical value. Nevertheless, other content is -possible and allowed. Currently, the only limitation is that -\PName{definition} has to be fully expandable and will be expanded during the -assignment. +While switches can accept only two values, there are also keys that recognize +several values. For example an alignment can be not just left or not-left, but +left, centred, or right. Internally, such differentiation is often made using +\Macro{ifcase}. This \TeX{} command expects a numerical value. Therefore in +\Package{scrbase} the command to define a macro by a \PName{key} has been +named \Macro{FamilyNumericalKey}. The \PName{value list} has the form: +%\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + \Parameter{value}\Parameter{definition}\texttt{,}\linebreak[1]% + \Parameter{value}\Parameter{definition}\texttt{,}~\dots +%\end{tabular}\vskip\dp\strutbox\end{flushleft} +The \PName{value list} defines not just the values permitted for the +\PName{key}. For each \PName{value}, the \PName{definition} of the macro +\Macro{\PName{command}} also is given. Usually, the \PName{definition} is just +a numerical value. Although other content is possible, there is currently a +restriction that the \PName{definition} must be fully expandable, and it will +be expanded during the assignment. \begin{Example} - The sausage may be cut different. For example the cold cuts may stay uncut or - will be cut roughly or may be cut thinly. This information should be stored - in command \Macro{cuthow}. + The sausage for the sausage salad can be cut differently. For example, the + cold cuts could simply remain uncut or be cut into thick or thin slices. + This information should be stored in the command \Macro{cuthow}. \begin{lstcode} \FamilyNumericalKey{butcher}% {saladcut}{cuthow}{% {none}{none},{no}{none},{not}{none}% - {rough}{rough},% + {thick}{thick},% {thin}{thin}% } \end{lstcode} - Not cutting anything may be selected either by + Not cutting anything can be selected by \begin{lstcode} \FamilyOptions{butcher}{saladcut=none} \end{lstcode} @@ -671,182 +669,192 @@ assignment. \begin{lstcode} \FamilyOptions{butcher}{saladcut=not} \end{lstcode} - In all three cases \Macro{cuthow} would be defined with content - \PValue{none}. It may be very useful to provide several values for the same - result as shown in this example. + In all three cases \Macro{cuthow} would be defined with the content + \PValue{none}. It can be useful to provide several values for the same + result, as shown in this example. - Now, it's most likely, that the kind of cutting will not be printed, but - should be evaluated later. In this case a textual definition would not be - useful. If the key is defined like this: + Now it's very likely that the manner of cutting will not be printed but + should be evaluated later. In this case, a textual definition would be + rather impractical. If the key is defined like this: \begin{lstcode} \FamilyNumericalKey{butcher}% {saladcut}{cuthow}{% {none}{0},{no}{0},{not}{0}% - {rough}{1},% + {thick}{1},% {thin}{2}% } \end{lstcode} - then a condition like the following may be used: + then you can use a condition like the following: \begin{lstcode} \ifcase\cuthow - % no cut + % uncut \or - % rough cut + % thickly cut \else - % thin cut + % thinly cut \fi \end{lstcode} \end{Example} -Internally, \Macro{FamilyNumericalKey} uses \Macro{FamilySetNumerical} as -\PName{action} of \DescRef{\LabelBase.cmd.DefineFamilyKey}. If a unknown value -is assigned to such a key, \Macro{FamilySetNumerical} will call -\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} with the arguments -\PName{family}, \PName{key} and \PName{value}. This will normally result in an -error message about assigning an unknown value. +Internally, \Macro{FamilyNumericalKey} uses \Macro{FamilySetNumerical} as the +\PName{action} of \DescRef{\LabelBase.cmd.DefineFamilyKey}. If an unknown +value is assigned to such a key, \Macro{FamilySetNumerical} will call +\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} with the \PName{family}, +\PName{key} and \PName{value} arguments. This leads to an error signalled with +the \DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue} status in +\DescRef{\LabelBase.cmd.FamilyKeyState}. Similarly, when calling +\Macro{FamilySetNumerical} the success is signalled via +\DescRef{\LabelBase.cmd.FamilyKeyStateProcessed} in +\DescRef{\LabelBase.cmd.FamilyKeyState}.% % \EndIndexGroup \begin{Declaration} - \Macro{FamilyCounterKey}\OParameter{family member}\Parameter{family}% + \Macro{FamilyCounterKey}\OParameter{member}\Parameter{family}% \Parameter{key}% \OParameter{default}\Parameter{\LaTeX{} counter}% \Macro{FamilySetCounter}\Parameter{family}% \Parameter{key}\Parameter{\LaTeX{} counter}\Parameter{value} \end{Declaration} -Beside\ChangedAt{v3.12}{\Package{scrbase}} -\DescRef{\LabelBase.cmd.FamilyNumericalKey} that defines a macro to a numeric -value depending on a symbolic value, there are circumstances when a -\PName{key} directly represents a \PName{\LaTeX{} counter}, that should be -assigned directly to a numeric value. In those cases, \Macro{FamilyCounterKey} -can be used that internally will call \Macro{FamilySetCounter}. A primary test -of the \PName{value} argument is done that only detects whether or not usage -of \PName{value} as a number is plausible. The assignment is done, only if -this plausibility test is successful. Nevertheless the assignment can still -fail and result in a \TeX{} error. But if the plausibility test fails already, -this is signalled by \DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue}. +While\ChangedAt{v3.12}{\Package{scrbase}} +\DescRef{\LabelBase.cmd.FamilyNumericalKey} defines a macro in which a numeric +value corresponds to a symbolic value, there are, of course, circumstances +when a \PName{key} directly represents a \PName{\LaTeX{} counter} to which a +numeric value should be assigned immediately. For this case, you can use +\Macro{FamilyCounterKey}, which calls \Macro{FamilySetCounter} internally. +There are some basic tests of the \PName{value} argument to determine if the +\PName{value} argument appears to be suitable for assignment to a counter. The +assignment will only be made if these tests succeed. However, not all errors +can be detected here, so an incorrect assignment can also lead to an error +message from \TeX{} itself. Errors that are detected, however, are signalled +by \DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue}. If\ChangedAt{v3.15}{\Package{scrbase}} the value is omitted, the \PName{default} is used instead. If there is no \PName{default}, the -\PName{key} can be used only with a value being defined.% +\PName{key} can be used only with an explicit value.% \EndIndexGroup \begin{Declaration} - \Macro{FamilyCounterMacroKey}\OParameter{family member}\Parameter{family}% + \Macro{FamilyCounterMacroKey}\OParameter{member}\Parameter{family}% \Parameter{key}% \OParameter{default}\Parameter{macro}% \Macro{FamilySetCounterMacro}\Parameter{family}% \Parameter{key}\Parameter{macro}\Parameter{value}% \end{Declaration} These\ChangedAt{v3.12}{\Package{scrbase}} two commands differ from the -previously described \DescRef{\LabelBase.cmd.FamilyCounterKey} and \DescRef{\LabelBase.cmd.FamilySetCounter} -only by the fact, that they do not assign a \PName{value} to a \PName{\LaTeX - counter}, but define a \Macro{macro} with the -\PName{value}.% +previously described \DescRef{\LabelBase.cmd.FamilyCounterKey} and +\DescRef{\LabelBase.cmd.FamilySetCounter} only by the fact that they do not +assign a \PName{value} to a \LaTeX{} counter, but define a \Macro{macro} with +the \PName{value}. This \PName{value} is locally assigned to a counter and +then its expanded value is used. Therefore, its value at the time the option +is called applies.% \EndIndexGroup \begin{Declaration} - \Macro{FamilyLengthKey}\OParameter{family member}\Parameter{family}% + \Macro{FamilyLengthKey}\OParameter{member}\Parameter{family}% \Parameter{key}% \OParameter{default}\Parameter{length}% \Macro{FamilySetLength}\Parameter{family}% \Parameter{key}\Parameter{length}\Parameter{value}% - \Macro{FamilyLengthMacroKey}\OParameter{family member}\Parameter{family}% + \Macro{FamilyLengthMacroKey}\OParameter{member}\Parameter{family}% \Parameter{key}% \OParameter{default}\Parameter{Makro}% \Macro{FamilySetLengthMacro}\Parameter{family}% \Parameter{key}\Parameter{Makro}\Parameter{value}% \end{Declaration} -With\ChangedAt{v3.12}{\Package{scrbase}} \Macro{FamilyLengthKey} you can +With\ChangedAt{v3.12}{\Package{scrbase}} \Macro{FamilyLengthKey}, you can define a \PName{key} that represents a \PName{length}. It does not matter -whether the \PName{length} is a \LaTeX{} length, a \TeX{} skip or a \TeX{} +whether the \PName{length} is a \LaTeX{} length, a \TeX{} skip, or a \TeX{} dimension. Internally the \PName{length} will be set to the \PName{value} -using \Macro{FamilySetLength}. Thereby a primary test is used to decide, -whether or not it is plausible to assign \PName{length} to \PName{value}. The -assignment is done only if this plausibility test is successful. Nevertheless, -not all assignment errors can be recognised, so an inaccurate \PName{value} -can still result in \TeX{} error. Recognised errors however will be signalled -by \DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue}. +using \Macro{FamilySetLength}. There are some basic tests to decide whether +this \PName{value} is valid to assign to \PName{length}. The assignment will +only take place if these tests succeed. However, not all errors can be +detected, so an inaccurate \PName{value} can still result in a \TeX{} error. +Errors that are detected, however, are signalled by +\DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue}. -If\ChangedAt{v3.15}{\Package{scrbase}} the value is omitted, -the \PName{default} is used instead. If there is no \PName{default}, the -\PName{key} can be used only with a value being defined. +If\ChangedAt{v3.15}{\Package{scrbase}} the value is omitted, the +\PName{default} is used instead. If there is no \PName{default}, the +\PName{key} can be used only with an explicit value. -In difference to this, \Macro{FamilyLengthMacroKey} and -\Macro{FamilySetLengthMacro} do not assign \PName{value} to a \PName{length}, -but define a \Macro{macro} with this -\PName{value}.% +\Macro{FamilyLengthMacroKey} and \Macro{FamilySetLengthMacro} store the +\PName{value} not in a \PName{length} but in a \Macro{macro}.% \EndIndexGroup \begin{Declaration} - \Macro{FamilyStringKey}\OParameter{family member}\Parameter{family}% + \Macro{FamilyStringKey}\OParameter{member}\Parameter{family}% \Parameter{key}% \OParameter{default}\Parameter{command} + \Macro{FamilyCSKey}\OParameter{member}\Parameter{family}% + \Parameter{key}% + \OParameter{default}\Parameter{command name} \end{Declaration} This defines\ChangedAt{v3.08}{\Package{scrbase}} a \PName{key} that accepts -every value. The value will be stored into the given \Macro{command}. If there +any value. The value will be stored in the specified \Macro{command}. If there is no optional argument for the \PName{default}, \Macro{FamilyStringKey} is the same as: -\begin{quote} -\DescRef{\LabelBase.cmd.DefineFamilyKey}\OParameter{family member}\Parameter{family}% -\Parameter{key}\\ -\hphantom{\DescRef{\LabelBase.cmd.DefineFamilyKey}}% -\PParameter{\Macro{def}\PName{command}\string{\#1\string}% -\DescRef{\LabelBase.cmd.FamilyKeyStateProcessed}}. -\end{quote} -If an optional argument \PName{default} is used, \Macro{FamilyStringKey} -is the same as: -\begin{quote} -\DescRef{\LabelBase.cmd.DefineFamilyKey}\OParameter{family member}\Parameter{family}% -\Parameter{key}\\ -\hphantom{\DescRef{\LabelBase.cmd.DefineFamilyKey}}% -\OParameter{default}% -\PParameter{\Macro{def}\PName{command}\string{\#1\string}}. -\end{quote} -If \PName{command} is not been defined, an empty macro will be defined. +\begin{lstcode}[escapeinside=`'] + \DefineFamilyKey[`\PName{member}']{`\PName{family}'}{`\PName{key}'} + {\def`\PName{command}'{#1}} +\end{lstcode} +If you use the optional argument \PName{default}, \Macro{FamilyStringKey} +corresponds to: +\begin{lstcode}[escapeinside=`'] + \DefineFamilyKey[`\PName{member}']{`\PName{family}'}{`\PName{key}'} + [`\PName{default}'] + {\def`\PName{command}'{#1}\FamilyKeyStateProcessed} +\end{lstcode} + \begin{Example} - By default an amount of 250\Unit{g} sausage salad should be produced. The - amount should be configurable by an option. The wanted amount will be stored - in the macro \Macro{saladweight}. The option should be named - \PValue{saladweight}, too: + By default 250\Unit{g} of sausage salad should be produced. However, the + amount should be configurable by an option. To do so, the quantity to be + created is stored in the macro \Macro{saladweight}. The option to change + the weight should also be called \PValue{saladweight}: \begin{lstcode} \newcommand*{\saladweight}{250g} \FamilyStringKey{butcher}% {saladweight}[250g]{\saladweight} \end{lstcode} - To switch back to the default weight after changing it, the user may simply - use the option without weight: + To switch back to the default weight after changing it, you can simply + call the option without the weight: \begin{lstcode} \FamilyOptions{butcher}{saladweight} \end{lstcode} - This may be done, because the default weight has been set as default at the - definition of the option above. + This is possible because the default quantity was also set as the default + value in the definition. \end{Example} -In this case there are not unknown values because all values are simply used -for a macro definition. Nevertheless, you should note that paragraph breaks -at the value assignment to the key are not allowed. +In this case, there are no unknown values because all values are simply used +for a macro definition. Note, however, that paragraph breaks are not allowed +when assigning a value to the key. + +In contrast\ChangedAt{v3.25}{\Package{scrbase}} to \Macro{FamilyStringKey}, +the \Macro{FamilyCSKey} command expects for the final argument not a macro but +only the name of a command, for example \PParameter{saladweight} instead of +\PParameter{\Macro{saladweight}}.% % \EndIndexGroup \begin{Declaration} \Macro{FamilyUnknownKeyValue}\Parameter{family}\Parameter{key}% - \Parameter{value}\Parameter{values list}% + \Parameter{value}\Parameter{value list}% \end{Declaration} -The command \Macro{FamilyUnknownKeyValue} throws and error message about -unknown values assigned to a known key. The \PName{values list} is a comma -separated list of allowed values in the form: -\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} - `\PName{value}'\texttt{,} `\PName{value}' \dots -\end{tabular}\vskip\dp\strutbox\end{flushleft} -Currently\ChangedAt{v3.12}{\Package{scrbase}}, \PName{values list} is -not used by \Package{scrbase}. +The command \Macro{FamilyUnknownKeyValue} throws an error message due to an +unknown or illegal values by means of \DescRef{\LabelBase.cmd.FamilyKeyState}. +The \PName{value list} is a comma separated list of permissible values in the +form +%\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + `\PName{value}'\texttt{,} `\PName{value}' \dots +%\end{tabular}\vskip\dp\strutbox\end{flushleft} +However\ChangedAt{v3.12}{\Package{scrbase}}, the \PName{value list} is +currently not evaluated by \Package{scrbase}. \begin{Example} - Now, for the cold cuts, the choices should be cut or no-cut and in case of cut - rough or thin. Rough should be the default for cutting. + The user should now also be able to select whether the cold cuts should be + cut thick or thin. Thick should be the default setting, which should be used + even if the user does not specify how to cut the coldcuts. \begin{lstcode} \@ifundefined{if@thincut}{% \expandafter @@ -857,36 +865,44 @@ not used by \Package{scrbase}. \DefineFamilyKey{butcher}% {coldcuts}[true]{% \FamilySetBool{butcher}{coldcuts}% - {@coldcuts}% - {#1}% + {@coldcuts}% + {#1}% \ifx\FamilyKeyState\FamilyKeyStateProcessed \@thincutfalse - \else + \else \ifstr{#1}{thin}{% - \@coldcutstrue - \@thincuttrue + \@coltcutstrue + \@finecuttrue \FamilyKeyStateProcessed - }{}% + }{% + \FamilyUnknownKeyValue{butcher}% + {coldcuts}% + {#1}{% + `true', `on', `yes', + `false`, `off`, `no', + `thin'% + }% + }% \fi }% \end{lstcode} - Let's have a look at the definition of \Option{butcher}: - First of all, we try to set the boolean switch of cold cuts using - \DescRef{\LabelBase.cmd.FamilySetBool}. After this command, we test whether - or not \DescRef{\LabelBase.cmd.FamilyKeyState} signals the success of the - command with state \DescRef{\LabelBase.cmd.FamilyKeyStateProcessed}. If so, - only the thin cut has to be deactivated. - - In the other case, the value will be tested to be equal to \PValue{thin}. In - that case, cold cuts and thin cut are activated and the state will be - switched to \DescRef{\LabelBase.cmd.FamilyKeyStateProcessed}. If the last - test failed also, the failure state of - \DescRef{\LabelBase.cmd.FamilySetBool} is still valid at the end of the - execution. - - Command \Macro{ifstr} is used for the thin test. It is - described on \DescPageRef{scrbase.cmd.ifstr} in - \autoref{sec:scrbase.if}. + First we try to set the boolean coldcuts switch using + \DescRef{\LabelBase.cmd.FamilySetBool}. If this succeeds, i.\,e. if + \DescRef{\LabelBase.cmd.FamilyKeyState} corresponds to + \DescRef{\LabelBase.cmd.FamilyKeyStateProcessed}, thincut will be + deactivated. Otherwise, we check if the value is equal to \PValue{thin} + rather than one of the valid values for a boolean switch. In this case, both + coldcuts and thincut are activated and the state will be switched to + \DescRef{\LabelBase.cmd.FamilyKeyStateProcessed}. If the previous test + fails, the error state signalled by \DescRef{\LabelBase.cmd.FamilySetBool} + is reset to \DescRef{\LabelBase.cmd.FamilyKeyStateUnknownValue}. The list of + the permissible values will be added to it. However, since this list is no + longer used, it would have been easy to skip the call to + \Macro{FamilyUnknownKeyValue} in the example and thus assume the error + status of \DescRef{\LabelBase.cmd.FamilySetBool}. + + The \Macro{ifstr} command used in the test is explained on + \DescPageRef{scrbase.cmd.ifstr} in \autoref{sec:scrbase.if}. \end{Example} % \EndIndexGroup @@ -895,26 +911,27 @@ not used by \Package{scrbase}. \begin{Declaration} \Macro{FamilyElseValues} \end{Declaration} -With former releases\ChangedAt{v3.12}{\Package{scrbase}} of \Package{scrbase}, -additional allowed values reported by -\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} can be set re-defining -\Macro{FamilyElseValues} in the form: -\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} - \texttt{,} `\PName{value}'\texttt{,} `\PName{value}' \dots -\end{tabular}\vskip\dp\strutbox\end{flushleft} -Since release~3.12 \DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} does not -report errors itself, but signals them using -\DescRef{\LabelBase.cmd.FamilyKeyState}. Therefore, \Macro{FamilyElseValues} -became deprecated. Nevertheless, its former usage is recognised by -\Package{scrbase} and results in a code change demand message.% +In\ChangedAt{v3.12}{\Package{scrbase}} previous\textnote{Obsolete!} versions +of \Package{scrbase}, you could use the \Macro{FamilyElseValues} command to +define additional values for processing by +\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} in the form +%\begin{flushleft}\vskip\dp\strutbox\begin{tabular}{l} + \texttt{,} `\PName{value}'\texttt{,} `\PName{value}' \dots, + %\end{tabular}\vskip\dp\strutbox\end{flushleft} +which were then output in an error message. Since version~3.12, +\DescRef{\LabelBase.cmd.FamilyUnknownKeyValue} no longer issues error messages +itself but signals them using \DescRef{\LabelBase.cmd.FamilyKeyState}. +Therefore, \Macro{FamilyElseValues} is now deprecated. Nevertheless, +\Package{scrbase} detects its use and issues a message requesting that you +update the code accordingly.% \EndIndexGroup \section{Conditional Execution} \seclabel{if} -The package \Package{scrbase} provides several commands for conditional -execution. other than the \TeX{} syntax of conditionals, e.\,g., +The \Package{scrbase} package provides several commands for conditional +execution. It does not rely on the \TeX{} syntax of conditionals such as \begin{lstcode} \iftrue ... @@ -922,334 +939,401 @@ execution. other than the \TeX{} syntax of conditionals, e.\,g., ... \fi \end{lstcode} -yet the \LaTeX{} syntax also known from \LaTeX{} commands like -\Macro{IfFileExists}, \Macro{@ifundefined}, \Macro{@ifpackageloaded}, and many -others, is used. Nevertheless, some package authors prefer to use the \TeX{} -syntax even for users at the \LaTeX{} interface level that could inevitably -lead to naming conflicts with the \Package{scrbase} conditionals. In fact, the -conditionals of \Package{scrbase} are very basic. Because of this -\Package{scrbase} firstly defines these conditionals as internal commands with -prefix \Macro{scr@}. Additional user commands without this prefix are -subsequently defined. But the definition of the user commands may be -suppressed with option \DescRef{\LabelBase.option.internalonly} (see -\autoref{sec:scrbase.loadit}, \DescPageRef{scrbase.option.internalonly}). - -Authors of packages and classes should use the internal commands as -\KOMAScript{} itself does. Nevertheless, for completeness the user commands -are described separately. +but uses the \LaTeX{} syntax with arguments similar to those used by \LaTeX{} +commands like \Macro{IfFileExists}, \Macro{@ifundefined}, +\Macro{@ifpackageloaded}, and many others. Some package authors, however, +prefer to use the syntax of \TeX{} conditionals even for users working at the +\LaTeX{} interface level. Since the \Package{scrbase} conditionals are fairly +low-level instructions, it is possible that such packages could provide +commands with the same names but a different syntax, leading to problems even +if the underlying semantics were actually the same. Therefore, +\Package{scrbase} plays it safe. + +\begin{Declaration} + \OptionVName{internalonly}{value} +\end{Declaration} +The \Package{scrbase} package provides some commands for conditional +execution. It primarily uses names like +\Macro{scr@\PName{name}}\textnote{package authors}, which are internal +commands. \KOMAScript{} also uses these commands internally. Authors of +packages and classes can also use these commands but should not redefine them. +Because some of these commands may also be useful for users, they are provided +as \Macro{\PName{name}}\textnote{users} normally. Since other packages may +provide conflicting commands with the same name but different syntax or +functionality, \Package{scrbase} can suppress the definition of +\Macro{\PName{name}}. Using the \Option{internalonly} option without a +\PName{value} will define only the internal commands and suppress definition +of all the user commands for conditional execution. Alternatively, the user +can list all the commands that should not be defined as the \PName{value}, +replacing ``\Macro{}'' with ``\texttt{/}''. + +Authors of packages and classes normally should not use this option. Users can +specify it with or without the \PName{value} either as a global option with +\DescRef{maincls.cmd.documentclass} or using +\Macro{PassOptionsToPackage}\IndexCmd{PassOptionsToPackage}. +\begin{Example} + The user does not want \Package{scrbase} to define the + \DescRef{\LabelBase.cmd.ifVTeX} and + \DescRef{\LabelBase.cmd.ifundefinedorrelax} commands. So to load the class, + the user writes: +\begin{lstcode} + \documentclass% + [internalonly=/ifVTeX/ifundefinedorrelax]% + {foo} +\end{lstcode} + The class name \Class{foo} is used here as a placeholder for any class. The + commands \DescRef{\LabelBase.cmd.ifVTeX} and + \DescRef{\LabelBase.cmd.ifundefinedorrelax} are explained later in this + section. +\end{Example} + +Authors of packages and classes should use the same internal names as +\KOMAScript{} itself. For completeness, the user commands are also given in +the following explanations.% +\EndIndexGroup \begin{Declaration} \Macro{scr@ifundefinedorrelax}% - \Parameter{name}\Parameter{then instructions}\Parameter{else instructions}% + \Parameter{name}\Parameter{then code}\Parameter{else code}% \Macro{ifundefinedorrelax}% - \Parameter{name}\Parameter{then instructions}\Parameter{else instructions} + \Parameter{name}\Parameter{then code}\Parameter{else code} \end{Declaration} -This command has almost the same functionality as \Macro{@ifundefined} from -the \LaTeX{} kernel (see \cite{latex:source2e}). So the \PName{then - instructions} will be executed if \PName{name} is the name of a command -that is currently either not defined or \Macro{relax}. Otherwise, the -\PName{else instructions} will be executed. In contrast to -\Macro{@ifundefined}, \Macro{\PName{name}} is not defined to be \Macro{relax} -in the event it was not defined before. Moreover, using \eTeX{} this case will -not consume any hash memory.% -% +This command works like \Macro{@ifundefined} from the \LaTeX{} kernel (see +\cite{latex:source2e}). So the \PName{then code} will be executed if +\PName{name} is the name of a command that is currently either not defined or +\Macro{relax}. Otherwise, the \PName{else code} will be executed. Unlike +\Macro{@ifundefined}, no hash memory is allocated nor is \Macro{\PName{Name}} +set to \Macro{relax} if \Macro{\PName{name}} was previously undefined.% +\EndIndexGroup + +\begin{Declaration} + \Macro{ifnotundefined}\Parameter{name}% + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If the command with the given name has already been defined, the \PName{then +code} will be executed. Otherwise, the \PName{else code} will be executed. +Since \eTeX{} already has a primitive \Macro{ifdefined}, this somewhat +unwieldy name, unfortunately, had to be chosen. There is no corresponding +internal command.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{scr@ifluatex} + \Parameter{then code}\Parameter{else code} +\end{Declaration} +If\ChangedAt{v3.21}{\Package{scrbase}} you use lua\TeX{}, the \PName{then +code} will be executed. Otherwise, the \PName{else code} will be executed. +\iftrue% Umbruchkorrekturtext +This test is rarely useful. % +\fi% +As a rule, it is better to test directly for the command you want. +There\textnote{Attention!} is no user equivalent for this instruction. Use the +\Package{ifluatex}\important{\Package{ifluatex}} package instead (see +\cite{package:ifluatex}).% \EndIndexGroup +\iffalse% It makes no sense to document this instruction yet +\begin{Declaration} + \Macro{scr@ifpdforluatex} + \Parameter{then code}\Parameter{else code} +\end{Declaration} +Until lua\TeX~0.85, it was mostly irrelevant whether you used pdf\TeX{} or +lua\TeX{}. This command, which executes the \PName{then code} in both cases, +derives from that fact. If neither pdf\TeX{} nor lua\TeX{} is used, the +\PName{else code} will be executed. Since version~0.85, lua\TeX{} has given up +compatibility with many of its commands. Therefore this distinction is no +longer useful in practice and is no longer used by \KOMAScript{} itself. There +is no user equivalent of this statement.% +\EndIndexGroup +\fi + \begin{Declaration} \Macro{scr@ifpdftex}% - \Parameter{then instructions}\Parameter{else instructions}% + \Parameter{then code}\Parameter{else code}% \Macro{ifpdftex}% - \Parameter{then instructions}\Parameter{else instructions} + \Parameter{then code}\Parameter{else code} \end{Declaration} -If pdf\TeX{} has been used, the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. Whether or not a PDF-file is -generated does not matter, and the pdf\TeX{} test is rarely useful. In -general, test for the desired command instead (see previous -\Macro{scr@ifundefinedorrelax} and -\DescRef{\LabelBase.cmd.ifundefinedorrelax}). -% +If you use pdf\TeX{}, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. It does not matter whether a PDF-file is +actually generated or not. This test is rarely useful. As a rule, you should +test directly for the command you want instead.% \EndIndexGroup \begin{Declaration} \Macro{scr@ifVTeX}% - \Parameter{then instructions}\Parameter{else instructions}% + \Parameter{then code}\Parameter{else code}% \Macro{ifVTeX}% - \Parameter{then instructions}\Parameter{else instructions} + \Parameter{then code}\Parameter{else code} \end{Declaration} -If V\TeX{} has been used, the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. This test is seldom useful. Test for -the desired command instead (see previous \Macro{scr@ifundefinedorrelax} and -\DescRef{\LabelBase.cmd.ifundefinedorrelax}). +If you use V\TeX{}, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. This test is seldom useful. As a rule, +you should test directly for the command you want instead.% % \EndIndexGroup \begin{Declaration} \Macro{scr@ifpdfoutput}% - \Parameter{then instructions}\Parameter{else instructions}% + \Parameter{then code}\Parameter{else code}% \Macro{ifpdfoutput}% - \Parameter{then instructions}\Parameter{else instructions} + \Parameter{then code}\Parameter{else code} \end{Declaration} -When generating a PDF-file the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. Whether pdf\TeX{} or V\TeX{} or -another \TeX{} engine is used to generate the PDF-file does not matter. -% +If a PDF file is generated, the \PName{then code} will be executed. Otherwise, +the \PName{else code} will be executed. It does not matter whether PDF file is +created using lua\TeX{}, pdf\TeX{}, or V\TeX{}, or \XeTeX{}.% \EndIndexGroup \begin{Declaration} \Macro{scr@ifpsoutput}% - \Parameter{then instructions}\Parameter{else instructions}% + \Parameter{then code}\Parameter{else code}% \Macro{ifpsoutput}% - \Parameter{then instructions}\Parameter{else instructions} + \Parameter{then code}\Parameter{else code} \end{Declaration} -When generating a PostScript-file the \PName{then instructions} will be -executed, otherwise the \PName{else instructions}. V\TeX{} provides direct -PostScript generation that will be recognised here. If V\TeX{} is not used, -but a switch \Macro{if@dvips} has been defined, the decision depends on that -switch. \KOMAScript{} provides \Macro{if@dvips} in \Package{typearea}. +If a PostScript file is generated, the \PName{then code} will be executed. +Otherwise, the \PName{else code} will be executed. V\TeX{} can generate +PostScript directly, which is recognized here. However, if V\TeX{} is not used +but the switch \Macro{if@dvips} has been defined, the decision depends on that +switch. \KOMAScript{} provides \Macro{if@dvips} in +\hyperref[cha:typearea]{\Package{typearea}}\IndexPackage{typearea}% +\IndexCmd{if@dvips}. % \EndIndexGroup \begin{Declaration} \Macro{scr@ifdvioutput}% - \Parameter{then instructions}\Parameter{else instructions}% + \Parameter{then code}\Parameter{else code}% \Macro{ifdvioutput}% - \Parameter{then instructions}\Parameter{else instructions} + \Parameter{then code}\Parameter{else code} \end{Declaration} -When generating a DVI-file the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. If neither a direct PDF-file -generation nor a direct PostScript-file generation has been detected, DVI-file -generation is assumed. -% +If a DVI-file is generated, the \PName{then code} will be executed. Otherwise, +the \PName{else code} will be executed. A DVI file is always assumed to be +generated if no direct output of a PDF file or a PostScript file can be +detected.% \EndIndexGroup \begin{Declaration} - \Macro{ifnotundefined}\Parameter{name}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{if@atdocument}\ \PName{then code}\ % + \textMacro{else}\ \PName{else code}\ \textMacro{fi} \end{Declaration} -\eTeX{} will be used to test, whether or not a command with the given -\PName{name} has already been defined. The \PName{then instructions} will be -executed if the command is defined, otherwise the \PName{else - instructions}. There is no corresponding internal command. +This conditional command intentionally exists only as an internal command. In +the document preamble, \Macro{if@atdocument} corresponds to \Macro{iffalse}. +After \Macro{begin}\PParameter{document}, it corresponds to \Macro{iftrue}. +Authors of classes and packages may find this command useful if a command +should behave differently depending on whether it is used in the preamble or +inside document body. Note\textnote{Attention!} that this command is a +condition using \TeX{} syntax and not \LaTeX{} syntax! % \EndIndexGroup \begin{Declaration} - \Macro{ifstr}\Parameter{string}\Parameter{string}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifstr}\Parameter{string 1}\Parameter{string 2}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -Both \PName{string} arguments are expanded and afterwards compared. If the -expansions are the same, the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. There is no corresponding internal +Both \PName{string} arguments are expanded and then compared. If the +expansions are the same, the \PName{then code} will be executed. Otherwise the +\PName{else code} will be executed. There is no corresponding internal command. % \EndIndexGroup \begin{Declaration} - \Macro{ifstrstart}\Parameter{string}\Parameter{string}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifstrstart}\Parameter{string 1}\Parameter{string 2}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -Both\ChangedAt{v3.12}{\Package{scrbase}} \PName{string} arguments are -expanded and afterwards compared. If aside from white spaces the first string -starts with the second one, the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. The command is not completely -expandable and there is no corresponding internal command.% +Both\ChangedAt{v3.12}{\Package{scrbase}} \PName{string} arguments are expanded +and then compared. If \PName{string 1}, apart from white space, begins with +\PName{string 2}, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. There is no corresponding internal +command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisdimen}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifisdimen}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} the expansion of\PName{code} results in -a \Macro{dimen}, which is also known as \TeX{} length register, the -\PName{then instructions} will be executed, otherwise the \PName{else - instructions}. The command is not completely expandable and there is no -corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to a +\Macro{dimen}, i.\,e. a \TeX{} length register, the \PName{then code} will be +executed. Otherwise the \PName{else code} will be executed. The command is not +completely expandable, and there is no corresponding internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisdimension}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifisdimension}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} \PName{code} expands to something with -the syntax of the value of a length, the \PName{then instructions} will be -executed, otherwise the \PName{else instructions}. Please -note\textnote{Attention!} that currently an invalid unit will result in an -error message. The command is not completely expandable and there is no -corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to something +syntactically equivalent to a length, the \PName{then code} will be executed. +Otherwise the \PName{else code} will be executed. Note\textnote{Attention!} +that unknown units will cause an error message. The command is not completely +expandable, and there is no corresponding internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisdimexpr}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifdimen}\Parameter{string}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} the expansion of\PName{code} results in -a \Macro{dimexpr}, which is also known as \TeX{} length expression, the -\PName{then instructions} will be executed, otherwise the \PName{else - instructions}. Note\textnote{Attention!} that illegal expressions will -result in error messages. The command is not completely expandable and there -is no corresponding internal command.% +The \PName{then code} will be executed if the first-order expansion of +\PName{string} consists of digits and a valid length unit. Otherwise, the +\PName{else code} will be used. There is no corresponding internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisskip}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifisdimexpr}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} the expansion of\PName{code} results in -a \Macro{skip}, which is also known as \TeX{} distance register, the -\PName{then instructions} will be executed, otherwise the \PName{else - instructions}. The command is not completely expandable and there is no -corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to an \eTeX{} +\Macro{dimexpr}\IndexCmd{dimexpr}, the \PName{then code} will be executed. +Otherwise, the \PName{else code} will be executed. Note\textnote{Attention!} +that illegal expressions will result in error messages. The command is not +completely expandable, and there is no corresponding internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisglue}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifisskip}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} \PName{code} expands to something with -the syntax of the value of a skip, the \PName{then instructions} will be -executed, otherwise the \PName{else instructions}. Please -note\textnote{Attention!} that currently an invalid unit will result in an -error message. The command is not completely expandable and there is no -corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to a +\Macro{skip}, i.\,e. a \TeX{} distance, the \PName{then code} will be +executed. Otherwise, the \PName{else code} will be executed. The command is not +completely expandable, and there is no corresponding internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisglueexpr}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifisglue}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} the expansion of\PName{code} results in -a \Macro{glueexpr}, which is also known as \TeX{} distance expression, the -\PName{then instructions} will be executed, otherwise the \PName{else - instructions}. Note,\textnote{Attention!} that illegal expressions will -result in error messages. The command is not completely expandable and there -is no corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to something +syntactically equivalent of the value of a skip, the \PName{then code} will be +executed. Otherwise, the \PName{else code} will be executed. +Note\textnote{Attention!} that invalid units will result in an error message. +The command is not completely expandable, and there is no corresponding +internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifiscount}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifisglueexpr}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} the expansion of\PName{code} results in -a \Macro{count}, which is also known as \TeX{} counter register, the -\PName{then instructions} will be executed, otherwise the \PName{else - instructions}. The command is not completely expandable and there is no -corresponding internal command. For test with \LaTeX{} counters, see -\DescRef{\LabelBase.cmd.ifiscounter}.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to a +\Macro{glueexpr}, i.\,e. an \eTeX{} distance expression, the \PName{then +code} will be executed. Otherwise, the \PName{else code} will be executed. +Note,\textnote{Attention!} that illegal expressions will result in error +messages. The command is not completely expandable, and there is no +corresponding internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisinteger}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifiscounter}\Parameter{counter}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} \PName{code} expands to something with -the syntax of the value of a counter, which would be a negative or positive -integer, the \PName{then instructions} will be executed, otherwise the -\PName{else instructions}. The command is not completely expandable and there -is no corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{counter} is defined as a +\LaTeX{} counter, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. The command is not completely expandable, +and there is no corresponding internal command.% \EndIndexGroup \begin{Declaration} - \Macro{ifisnumexpr}\Parameter{code}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifiscount}\Parameter{count}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} the expansion of\PName{code} results in -a \Macro{numexpr}, which is also known as \TeX{} number expression, the -\PName{then instructions} will be executed, otherwise the \PName{else - instructions}. Note\textnote{Attention!} that illegal expressions will -result in error messages. The command is not completely expandable and there -is no corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{count} expands to a +\Macro{count}, i.\,e. a \TeX{} counter, the \PName{then code} will be +executed. Otherwise, the \PName{else code} will be executed. The command is +not completely expandable, and there is no corresponding internal command. For +tests of \LaTeX{} counters, see \DescRef{\LabelBase.cmd.ifiscounter}.% \EndIndexGroup \begin{Declaration} - \Macro{ifiscounter}\Parameter{counter}% - \Parameter{then instructions}\Parameter{else instructions} + \Macro{ifisinteger}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -If\ChangedAt{v3.12}{\Package{scrbase}} \PName{counter} is an already defined -\LaTeX{} counter, the \PName{then instructions} will be executed, otherwise -the \PName{else instructions}. The command is not completely expandable and -there is no corresponding internal command.% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to something +syntactically equivalent to of the value of a counter, i.\,e. a negative or +positive integer, the \PName{then code} will be executed. Otherwise, the +\PName{else code} will be executed. The command is not completely expandable, +and there is no corresponding internal command.% \EndIndexGroup \begin{Declaration} \Macro{ifnumber}\Parameter{string}% - \Parameter{then instructions}\Parameter{else instructions} -\end{Declaration} -Note that this does not compare numbers. The \PName{then instructions} will -be executed if the one step expansion of \PName{string} consists of digits -only. Otherwise the \PName{else instructions} will be used. There is no -corresponding internal command. -% -\EndIndexGroup - - -\begin{Declaration} - \Macro{ifdimen}\Parameter{string}% - \Parameter{then instructions}\Parameter{else instructions} + \Parameter{then code}\Parameter{else code} \end{Declaration} -Note that this does not compare dimensions. The \PName{then instructions} will -be executed, if the one step expansion of \PName{string} consists of digits -and a valid unit of length. Otherwise, the \PName{else instructions} will be -used. There is no corresponding internal command. +The \PName{then code} will be executed if the first-order expansion of +\PName{string} consists only of digits. Otherwise, the \PName{else code} will +be used. There is no corresponding internal command. % \EndIndexGroup \begin{Declaration} - \Macro{if@atdocument}\ \PName{the instructions}\ % - \textMacro{else}\ \PName{else instructions}\ \textMacro{fi} + \Macro{ifisnumexpr}\Parameter{expression}% + \Parameter{then code}\Parameter{else code} \end{Declaration} -This command exists intentionally as internal command only. In the document -preamble \Macro{if@atdocument} is same as \Macro{iffalse}. After -\Macro{begin}\PParameter{document} it's the same as \Macro{iftrue}. Authors of -classes and packages may use this if a command should work somehow different -depending on whether it has been used in the preamble or inside the documents -body. Please note\textnote{Attention!} that this is a condition in \TeX{} -syntax not in \LaTeX{} syntax! -% +If\ChangedAt{v3.12}{\Package{scrbase}} \PName{expression} expands to a +\Macro{numexpr}, i.\,e. an \eTeX{} number expression, the \PName{then code} +will be executed. Otherwise, the \PName{else code} will be executed. +Note\textnote{Attention!} that illegal expressions will result in error +messages. The command is not completely expandable, and there is no +corresponding internal command.% \EndIndexGroup -\section{Definition of Language-Dependent Terms} +\section{Defining Language-Dependent Terms} \seclabel{languageSupport} \BeginIndexGroup \BeginIndex{}{language>definition} \index{language>dependent terms|see{language definition}} \index{terms>language-dependent|see{language definition}} -Normally, one has to change or define language-dependent terms like -\Macro{captionsenglish} in such a way that, in addition to the available terms, -the new or redefined terms are defined. This is made more difficult by the +Beginners often find it difficult to change language-dependent terms +\Macro{listfigurename}\IndexCmd{listfigurename}, by default usually ``List of +Figures.'' For example, if these are simply redefined with +\Macro{renewcommand} in the document preamble, they will not survive a later +change of language. If you use \Package{babel}\IndexCmd{babel}, the +redefinition in the preamble is overwritten with +\Macro{begin}\PParameter{document}. + +To define or change language-dependent terms, you normally have to redefine +commands like \Macro{captionsenglish} so that the new or redefined terms are +defined in addition to the previous terms. This is made more difficult by the fact that some packages like \Package{german}\IndexPackage{german} or -\Package{ngerman}\IndexPackage{ngerman} redefine those settings when the -packages are loaded. These definitions unfortunately occur in such a manner as -to destroy all previous private settings. That is also the reason why it makes -sense to delay changes with \Macro{AtBeginDocument} until -\Macro{begin}\PParameter{document}; that is, after package loading is -completed. The user can also use \Macro{AtBeginDocument} or redefine the -language-dependent terms after \Macro{begin}\PParameter{document}; that is, -not put them in the preamble at all. The package \Package{scrbase} -provides some additional commands for defining language-dependent terms. - +\Package{ngerman}\IndexPackage{ngerman} redefine those settings when they are +loaded. These definitions, unfortunately, occur in a way that undoes all the +previous changes. For this reason, it makes sense to delay changes until +\Macro{begin}\PParameter{document} by using \Macro{AtBeginDocument}, that is, +after all packages have been loaded. A user can also use +\Macro{AtBeginDocument} or redefine the language-dependent terms not in the +preamble but after \Macro{begin}\PParameter{document}. + +Adding further to the difficulty, some packages define additional +language-dependent terms in \Macro{captions\PName{language}}, while others use +\Macro{extras\PName{language}}. So the user must understand the commands very +well in order to use the correct one in the right way. + +The \Package{scrbase} package therefore provides additional commands to define +or modify language-dependent terms, relieving the user of many of these +problems. These commands also let you simultaneously define or change the +language-dependent terms of several dialects or forms of a language. \begin{Declaration} \Macro{defcaptionname}% @@ -1269,46 +1353,45 @@ provides some additional commands for defining language-dependent terms. \Macro{renewcaptionname*}% \Parameter{language list}\Parameter{term}\Parameter{definition} \end{Declaration} -Using one of these commands, the user can assign a \PName{definition} for a -particular language to a \PName{term}. Several languages can be concatenated -with comma to a \PName{language list}. The \PName{term} is always a -macro. The commands differ depending on whether a given language or a -\PName{term} within a given language are already defined or not at the -time the command is called. - -If a language is not defined, then \Macro{providecaptionname} does -nothing other than write a message in the log file. This happens only once -for each language. If a language is defined, but \PName{term} is not yet -defined for it, then it will be defined using \PName{definition}. The +With these four commands and their starred variants, you can assign a +\PName{definition} for a particular language to a \PName{term}. Several +languages can be concatenated with comma in the \PName{language list}. + +The \PName{term} is always a macro. The commands differ depending on whether a +given language or a \PName{term} within a given language is already defined at +the time the command is called. + +If a language is not defined, \Macro{providecaptionname} does nothing other +than write a message to the log file. This happens only once for each +language. If a language is defined but does not yet contain a corresponding +\PName{term}, it will be defined using \PName{definition}. However, the \PName{term} will not be redefined if the language already has such a definition; instead, an appropriate message is written to the log file. -The command \Macro{newcaptionname} has a slightly different behaviour. If a -language is not yet defined, then a new language command will be -created and a message written to the log file. For language -\PValue{USenglish}, for example, this would be the language command -\Macro{captionsUSenglish}. If \PName{term} is not yet defined in a -language, then it will be defined using \PName{definition}. If -\PName{term} already exists in a language, then this results in an error -message. - -The command \Macro{renewcaptionname} again behaves differently. It requires an -existing definition of \PName{term} in the languages. If neither -a language nor \PName{term} exist or \PName{term} is unknown in a -defined language, then an error message is given. Otherwise, the -\PName{term} for the language will be redefined according to -\PName{definition}. - -The\ChangedAt{v3.12}{\Package{scrbase}} command \Macro{defcaptionname} always -defines the \PName{term}. So previous definitions of \PName{term} for the -given \PName{language} will be overwritten. You may use this command even for -undefined languages. - -\KOMAScript{} employs \Macro{providecaptionname} in order to define the -commands in \autoref{sec:scrlttr2-experts.languages}. +On the other hand, if a language has not yet been defined, +\Macro{newcaptionname} defines a new language command will be created. For the +language \PValue{USenglish}, for example, this would be the language command +\Macro{captionsUSenglish}. This definition will also be noted in the log file. +If \PName{term} is not yet defined in this language, it will be defined using +\PName{definition}. If the \PName{term} already exists in a language, an error +message is issued. + +The \Macro{renewcaptionname} command behaves still differently. If a language +is undefined, an error message is issued. If the \PName{term} is not defined +in this language, an error message is also issued. If the \PName{term} is +defined in the language, it will be redefined to \PName{definition}. + +The\ChangedAt{v3.12}{\Package{scrbase}} \Macro{defcaptionname} command always +defines the \PName{term}, thus overwriting any previous definition. As with +\Macro{providecaptionname}, the language specified need not be previously +defined. + +\KOMAScript{} itself uses \Macro{providecaptionname} to define the commands in +\autoref{sec:scrlttr2-experts.languages}. +\DescPageRef{scrlttr2-experts.cmd.yourrefname}. \begin{Example} - If you prefer ``fig.'' instead of ``figure'' in \PValue{USenglish}, you may + If you prefer ``fig.'' instead of ``figure'' in \PValue{USenglish}, you can achieve this using: \begin{lstcode} \renewcaptionname{USenglish}{\figurename}{fig.} @@ -1322,35 +1405,35 @@ commands in \autoref{sec:scrlttr2-experts.languages}. \begin{lstcode} \renewcaptionname{USenglish,UKenglish}{\figurename}{fig.} \end{lstcode} - You can extend the \PName{language list} in the same manner by + You can extend the \PName{language list} in the same manner with \PValue{american}, \PValue{australian}, \PValue{british}, \PValue{canadian}, and \PValue{newzealand}. \end{Example} - -Since \KOMAScript~3.12\ChangedAt{v3.12}{\Package{scrbase}} you do not need to -delay the definition or redefinition until \Macro{begin}\PParameter{document} -using \Macro{AtBeginDocument} any longer because \Package{scrbase} does the -delay automatically for (re)definitions in the document's -preamble. Additionally, \Package{scrbase} tests if a redefinition should be -made in \Macro{extras\PName{language}} instead of -\Macro{captions\PName{language}} and does so automatically. The new star -variants of the commands always use \Macro{extras\PName{language}}. So -redefinition of language dependent terms for packages like \Package{hyperref} -that use \Macro{extras\PName{language}} should work as expected by the user. - -Language dependent terms usually defined by classes and language -packages are listed and described in \autoref{tab:scrbase.commonNames}. + +Since \KOMAScript~3.12\ChangedAt{v3.12}{\Package{scrbase}}, you no longer need +to delay the definition or redefinition until +\Macro{begin}\PParameter{document} using \Macro{AtBeginDocument} because +\Package{scrbase} does this itself if the commands are called in the +document's preamble. Additionally, \Package{scrbase} now checks if a term +should be redefined in \Macro{extras\PName{language}} instead of +\Macro{captions\PName{language}}. The new starred variants of the commands +always use \Macro{extras\PName{language}}. So redefining language-dependent +terms for packages like \Package{hyperref} that use +\Macro{extras\PName{language}} should work as expected. + +Language-dependent terms that are commonly defined by classes and language +packages are described in \autoref{tab:scrbase.commonNames}. \begin{desclist} \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% \desccaption[{% - Overview of usual language dependent terms% + Overview of common language-dependent terms% }]{% - Overview of language dependent terms of usual language packages% + Overview of language-dependent terms of typical language packages% \label{tab:scrbase.commonNames}% }{% - Overview of usual language dependent terms - (\emph{continuation})% + Overview of common language dependent terms + (\emph{continued})% }% \entry{\Macro{abstractname}}{% heading of the abstract% @@ -1381,7 +1464,7 @@ packages are listed and described in \autoref{tab:scrbase.commonNames}. \IndexCmd{contentsname}% }% \entry{\Macro{enclname}}{% - prefix heading for the enclosure of a letter% + prefix heading for the enclosures of a letter% \IndexCmd{enclname}% }% \entry{\Macro{figurename}}{% @@ -1443,58 +1526,60 @@ packages are listed and described in \autoref{tab:scrbase.commonNames}. \EndIndexGroup -\section{Identification of \KOMAScript} +\section{Identifying \KOMAScript} \seclabel{identify} -Package \Package{scrbase} may be used independent of \KOMAScript{} with -other packages and classes. Nevertheless, it is a \KOMAScript{} package. For -this, \Package{scrbase} also provides commands to identify \KOMAScript{} and -to identify itself as a \KOMAScript{} package. +Although\,---\,or especially because\,---\,\Package{scrbase} is generally +designed as a package for authors of classes and packages, it is of course +used by the \KOMAScript{} classes and most \KOMAScript{} packages. It +therefore contains two commands that are present in all \KOMAScript{} classes +and all basic \KOMAScript{} packages. \begin{Declaration} \Macro{KOMAScript} \end{Declaration} -This command only sets the word ``\KOMAScript'' with sans-serif font and -a little bit tracking for the capitals. By the way: All \KOMAScript{} classes -and packages define this command, if it has not been defined already. The -definition is robust using \Macro{DeclareRobustCommand}. -% +This command simply sets the word ``\KOMAScript'' in sans-serif font and with +a slight tracking for the capitals. By the way, all \KOMAScript{} classes and +packages define this command as required. The definition is robust using +\Macro{DeclareRobustCommand}. Since packages that do not belong to +\KOMAScript{} can also define this command, its existence should not be +interpreted as an indication that a \KOMAScript{} package is in use.% \EndIndexGroup \begin{Declaration} \Macro{KOMAScriptVersion} \end{Declaration} -\KOMAScript{} defines the main version of \KOMAScript{} in this command. It -has the form ``\PName{date} \PName{version} \texttt{KOMA-Script}''. This main -version is same for all \KOMAScript{} classes and the \KOMAScript{} packages -that are essential for the classes. Because of this, it may be inquired after -loading \Package{scrbase}, too. For example, this document has been made using +\KOMAScript{} defines the major version of \KOMAScript{} in this command. It +has the form ``\PName{date} \PName{version} \texttt{KOMA-Script}''. This major +version is same for all \KOMAScript{} classes and all \KOMAScript{} packages +used by the classes. For this reason, it can be queried after you +load \Package{scrbase}, too. For example, this guide was made using \KOMAScript{} version ``\KOMAScriptVersion''. % \EndIndexGroup -\section{Extension of the \LaTeX{} Kernel} +\section{Extensions to the \LaTeX{} Kernel} \seclabel{latexkernel} -Sometimes the \LaTeX{} kernel itself provides commands, but lacks other, -similar commands that would often be useful, too. Some of those commands for -authors of packages and classes are provided by \Package{scrbase}. +Sometimes the \LaTeX{} kernel itself provides commands but lacks other very +similar commands that would often be useful. A few such commands are provided +by \Package{scrbase} for authors of packages and classes. \begin{Declaration} \Macro{ClassInfoNoLine}\Parameter{class name}\Parameter{information}% \Macro{PackageInfoNoLine}\Parameter{package name}\Parameter{information}% \end{Declaration}% -For authors of classes and package the \LaTeX{} kernel already provides -commands like \Macro{ClassInfo} and \Macro{PackageInfo} to write information. -together with the current line number, into the log-file. Besides -\Macro{PackageWarning} and \Macro{ClassWarning} to throw warning messages with -line numbers, it also provides \Macro{PackageWarningNoLine} and -\Macro{ClassWarningNoLine} for warning messages without line -numbers. Nevertheless, the commands \Macro{ClassInfoNoLine} and -\Macro{PackageInfoNoLine} for writing information without line numbers into the -log-file are missing. Package \Package{scrbase} provides them. +The \LaTeX{} kernel already provides authors of classes and packages commands +like \Macro{ClassInfo} and \Macro{PackageInfo} to write information, along +with the current line number, to the log file. In addition to +\Macro{PackageWarning} and \Macro{ClassWarning}, which throw warning messages +with line numbers, it also provides \Macro{PackageWarningNoLine} and +\Macro{ClassWarningNoLine} for warning messages without line numbers. However +the obvious commands \Macro{ClassInfoNoLine} and \Macro{PackageInfoNoLine}, +for writing information without line numbers into the log file, are missing. +The \Package{scrbase} package provides them. % \EndIndexGroup @@ -1502,47 +1587,47 @@ log-file are missing. Package \Package{scrbase} provides them. \begin{Declaration} \Macro{l@addto@macro}\Parameter{command}\Parameter{extension}% \end{Declaration}% -The \LaTeX{} kernel already provides an internal command \Macro{g@addto@macro} -to extend the definition of macro \Macro{command} by \PName{extension} -globally. This may be used only for macros that have no -arguments. Nevertheless, sometimes a command like this, that works locally to -a group instead of globally, could be useful. Package \Package{scrbase} -provides such a command with \Macro{l@addto@macro}. An alternative may be -usage of package \Package{etoolbox}\IndexPackage{etoolbox}, which provides -several of such commands for different purposes (see \cite{package:etoolbox}). -% +The \LaTeX{} kernel provides an internal command \Macro{g@addto@macro} to +extend the definition of macro \Macro{command} globally with +\PName{extension}. This works in this form only for macros that have no +arguments. However, sometimes you may need a command like this that works +locally within the current group. The \Package{scrbase} package provides such +a command with \Macro{l@addto@macro}. An alternative is to use the +\Package{etoolbox}\IndexPackage{etoolbox} or +\Package{xpatch}\IndexPackage{xpatch} package, which offers a whole range of +such commands for different purposes (see \cite{package:etoolbox} or +\cite{package:xpatch}).% \EndIndexGroup -\section{Extension of the Mathematical Features of \eTeX} +\section{Extensions to the Mathematical Features of \eTeX} \seclabel{etex} -\eTeX{}, that is meanwhile used by \LaTeX{} and needed by \KOMAScript{}, -provided with \Macro{numexpr}\IndexCmd{numexpr}, an extended feature for -calculation of simple arithmetic with \TeX{} counters and -integers. The four basic arithmetic operations and brackets are -supported. Correct rounding is done while division. Sometimes additional -operators would be useful. +\eTeX{}, which is used by \LaTeX{} and loaded by \KOMAScript{}, has extended +capabilities for calculating simple arithmetic with \TeX{} counters and +integers using \Macro{numexpr}\IndexCmd{numexpr}. The four basic arithmetic +operations and parentheses are supported. Division is rounded +correctly. Sometimes additional operators would be useful. \begin{Declaration} \Macro{XdivY}\Parameter{dividend}\Parameter{divisor}% \Macro{XmodY}\Parameter{dividend}\Parameter{divisor}% \end{Declaration}% -Having a division with remainder command\ChangedAt{v3.05a}{\Package{scrbase}} -\Macro{XdivY} gives the value of the integer quotient, with command -\Macro{XmodY} giving the value of the remainder. This kind of division is -defined: +The command\ChangedAt{v3.05a}{\Package{scrbase}} +\Macro{XdivY} returns the value of the integer quotient, with command +\Macro{XmodY} giving the value of the remainder. This type of of division is +defined by the equation \[ \textit{dividend} = \textit{divisor} \cdot \textit{integer quotient} + \textit{remainder} \] -with \textit{dividend} and \textit{remainder} are integer, \textit{remainder} -is greater or equal to \textit{divisor}, and \textit{divisor} is a natural -number greater than 0. +where \textit{dividend}, \textit{divisor}, and \textit{remainder} are +integers, \textit{remainder} is greater or equal to 0 and less than +\textit{divisor}, and \textit{divisor} is a natural number greater than 0. -The value may be used for assignment to a counter or directly in the -expression of \Macro{numexpr}. For output the value as an Arabic number has -to be prefixed by \Macro{the}.% +You can assign the value to a counter or use it directly within an expression +using \Macro{numexpr}. To output the value as an Arabic number, you must +prefix it with \Macro{the}.% % \EndIndexGroup % |