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 | 928 |
1 files changed, 589 insertions, 339 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 ce472d81292..376319b4d06 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-2012 +% Copyright (c) Markus Kohm, 2002-2013 % % 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-2012 +% Copyright (c) Markus Kohm, 2002-2013 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -45,21 +45,23 @@ % % ====================================================================== -\ProvidesFile{scrbase.tex}[2012/03/04 KOMA-Script package scrbase] -\translator{Markus Kohm} +\KOMAProvidesFile{scrbase.tex} + [$Date: 2013-12-13 16:32:18 +0100 (Fr, 13 Dez 2013) $ + KOMA-Script package scrbase] +\translator{Markus Kohm\and Melvin Hendrix} -% Date of the translated German file: 2012/03/04 +% Date of the translated German file: 2013/11/06 -\chapter{Basic Functions at Package \Package{scrbase}} +\chapter{Basic Functions of Package \Package{scrbase}} \labelbase{scrbase} \BeginIndex{Package}{scrbase}% -The package \Package{scrbase} provides basic features, that are designed and -implemented to be used by authors of packages and classes. Thereby it may not -only used for wrapper classes, that use a \KOMAScript{} class. Authors of -classes, that aren't related to anything else from \KOMAScript{}, may also -benefit from the functionality of \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. \section{Loading the Package} \label{sec:scrbase.loadit} @@ -68,10 +70,10 @@ Whereas users load packages using \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 opposite to this \Macro{RequirePackageWithOptions} -doesn't have an optional argument but passes all options given while loading -the wrapper package to the required package. See \cite{latex:clsguide} for -more information about these commands. +\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 @@ -79,7 +81,7 @@ 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 this keys. The options provided by \Package{scrbase} also use +values to these keys. The options provided by \Package{scrbase} also use \Package{keyval} syntax: \PName{key}\texttt{=}\PName{value}. \begin{Declaration} @@ -87,35 +89,37 @@ values to this keys. The options provided by \Package{scrbase} also use \end{Declaration} \BeginIndex{Option}{internalonly~=\PName{value}}% Package \Package{scrbase} provides some commands for conditional -execution. The primary names of those are build like -\Macro{scr@\PName{name}}. With this those are internal commands. \KOMAScript{} -really uses this internal commands internally. Authors of packages and classes -may use those internal commands too, but should not redefine them. Because -some of those commands may be useful for users too, they are also provided as -\Macro{\PName{name}} normally. But eventually other packages provide commands -with the same name but different syntax or different functionality. This would -result in an conflict. So \Package{scrbase} provides to suppress the -definition of the user commands, \Macro{\PName{name}}, only. 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 shouldn't -be defined as \PName{value}, but replaces ``\Macro{}'' by ``\texttt{/}''. +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 doesn't want \Package{scrbase} to define commands \Macro{ifVTeX} - and \Macro{ifundefinedorrelax}. Because of this, user uses: + The user does not want \Package{scrbase} to define commands \Macro{ifVTeX} + and \Macro{ifundefinedorrelax}. Because of this, to load the class, the user + writes: \begin{lstcode} \documentclass% [internalonly=/ifVTeX/ifundefinedorrelax]% {foo} \end{lstcode} - to load the class. Class name \Class{foo} has been used as an placeholder + Class name \Class{foo} is, therefore, an placeholder for any class in this example. The meanings of commands \Macro{ifVTeX} and \Macro{ifundefinedorrelax} and many more commands for conditional execution - may be found in \autoref{sec:scrbase.if}. + is located in \autoref{sec:scrbase.if}. \end{Example} % \EndIndex{Option}{internalonly~=\PName{value}}% @@ -127,54 +131,55 @@ use it with or without \PName{value} either as a global option with 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} knows also -family members. Now, 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, -of a family or of all family members. +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. \begin{Declaration} \Macro{DefineFamily}\Parameter{family}\\ - \Macro{DefineFamilyMember}\OParameter{family member}\Parameter{family} + \Macro{DefineFamilyMember}\OParameter{family member}\Parameter{family}% \end{Declaration} \BeginIndex{Cmd}{DefineFamily}% \BeginIndex{Cmd}{DefineFamilyMember}% \Package{scrbase} needs to know the members of a family for different -reasons. So it's necessary first to define a new family using -\Macro{DefineFamily}, that produces also an empty member list. If the family -has already been defined nothing would happen. Nothing means also, that an +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. -A new member may be added to the family using \Macro{DefineFamilyMember}. If -the family doesn't exist, this would result in an error message. If the member -already exists, nothing happens. If the member is omitted, the member won't -stay empty, but ``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' will -be assumed. While loading a class or package \Macro{@currname} and -\Macro{@currext} together represent the file name of the class or package. - -Theoretically is would be possible, to define a member without a name using an -empty optional argument \PName{family member}. But this would be same like the -family itself. It is recommended to use only letters and digits at the -\PName{family} an start the \PName{family member} with another char like a -period. Otherwise it could happen, that members of one family are same like -members of another family. - -\Package{scrbase} itself defines family ``\PValue{KOMA}'' and adds member -``\PValue{.scrbase.sty}'' to is. Generally family ``\PValue{KOMA}'' is -reserved to \KOMAScript{}. For your own packages it is recommended to use the -name of the bundle as \PName{family} and the name of the package as -\PName{family member} of that \PName{family}. +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. + +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}. % \begin{Example} - Assumed you're writing a bundle ``master butcher''. Within that bundle you - have packages \File{salami.sty}, \File{liversausage.sty}, and - \File{kielbasa.sty}. Therefor you decide to use family name - ``\PValue{butcher}'' and add the lines + 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 \begin{lstcode} \DefineFamily{butcher} \DefineFamilyMember{butcher} \end{lstcode} - to each of the package files. While loading the three packages this will - all the members ``\PValue{.salami.sty}'', ``\PValue{.liversausage.sty}'', + When loading the three packages, this will + add the members ``\PValue{.salami.sty}'', ``\PValue{.liversausage.sty}'', and ``\PValue{.kielbasa.sty}'' to the family ``\PValue{butcher}''. After loading all three packages, all three member will be defined. \end{Example} @@ -186,18 +191,29 @@ name of the bundle as \PName{family} and the name of the package as \begin{Declaration} \Macro{DefineFamilyKey}\OParameter{family member}\Parameter{family}% \Parameter{key}\OParameter{default}\\ - \hphantom{\Macro{DefineFamilyKey}}\Parameter{action} + \hphantom{\Macro{DefineFamilyKey}}\Parameter{action}\\ + \Macro{FamilyKeyState}\\ + \Macro{FamilyKeyStateUnknown}\\ + \Macro{FamilyKeyStateProcessed}\\ + \Macro{FamilyKeyStateUnknownValue}\\ + \Macro{FamilyKeyStateNeedValue} \end{Declaration} \BeginIndex{Cmd}{DefineFamilyKey}% -This command defines a \PName{key}. If a \PName{family member} is given, the -\PName{key} will become an attribute of that member of the also given -\PName{family}. If no \PName{family member} is given, the member -``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' will be assumed. If -later a value will be assigned to the \PName{key}, the \PName{action} will be -executed and the value will be an argument of this. So inside of -\PName{action} ``\lstinline{#1}'' would be that value. If the value will be -omitted, the \PName{default} will be used instead. If there's no -\PName{default}, the \PName{key} can be used only with value. +\BeginIndex{Cmd}{FamilyKeyState}% +\BeginIndex{Cmd}{FamilyKeyStateUnknown}% +\BeginIndex{Cmd}{FamilyKeyStateProcessed}% +\BeginIndex{Cmd}{FamilyKeyStateUnknownValue}% +\BeginIndex{Cmd}{FamilyKeyStateNeedValue}% +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} \phantomsection\label{explain:scrbase.macro.DefineFamilyKey}% At least @@ -208,33 +224,73 @@ omitted, the \PName{default} will be used instead. If there's no will result in a call of \begin{lstcode}[moretexcs={define@key},escapeinside=`'] \define@key{`\PName{family\,member}'}{`\PName{key}'} - [`\PName{default}']{`\PName{action}'} + [`\PName{default}']{`\PName{extended action}'} \end{lstcode} - with \Macro{define@key} is provided by package - \Package{keyval}\IndexPackage{keyval} (see \cite{package:keyval}). + 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. + \begin{Example} - Assumed, each of the three packages from the previous example should get a - key \PValue{coldcuts}. If this is used, a switch should be set at each of - the packages. For package \Package{salami} this may be, e.\,g., + 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: \begin{lstcode} \newif\if@Salami@Aufschnitt \DefineFamilyKey{butcher}% {coldcut}[true]{% \expandafter\let\expandafter\if@salami@coldcut \csname if#1\endcsname + \FamilyKeyStateProcessed } \end{lstcode} Available values for the key are \PValue{true} or \PValue{false} in this - case. There's no test on inappropriate values in this example. If the key - will be used later, this has to be done with one of the allowed values or - without assignment. In the second case the default \PName{true} will be - used. + 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. \end{Example} % +\EndIndex{Cmd}{FamilyKeyStateNeedValue}% +\EndIndex{Cmd}{FamilyKeyStateUnknownValue}% +\EndIndex{Cmd}{FamilyKeyStateProcessed}% +\EndIndex{Cmd}{FamilyKeyStateUnknown}% +\EndIndex{Cmd}{FamilyKeyState}% \EndIndex{Cmd}{DefineFamilyKey}% @@ -243,38 +299,37 @@ omitted, the \PName{default} will be used instead. If there's no \end{Declaration} \BeginIndex{Cmd}{FamilyProcessOptions}% Generally the extension of keys of families to keys of families and family -members was mentioned to use keys or key-value settings as class or package -options. This command therefor is an extension of \Macro{ProcessOption*} from -\LaTeX{} kernel (see \cite{latex:clsguide}. Thereby the command processes not -only options that has been declared using \Macro{DeclareOption}. It processes -even all keys of the given family member. If the optional argument +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 -``\texttt{.}\Macro{@currname}\texttt{.}\Macro{@currext}'' will be used. +``\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 will be set also -and before the keys of the family members. +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. \begin{Example} If a package in the previous example would be extended by the line \begin{lstcode} \FamilyProcessOptions{butcher} \end{lstcode} - then the user may select the option \Option{coldcut} while loading the - package. If the option will be used globally, this means at the optional + then the user may select the option \Option{coldcut} 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 will be loaded + automatically to all three packages, if all three packages are loaded later. \end{Example} -Please note\textnote{Attention!} that packages process global options always -before local options, that has been assigned locally to the package. In -opposite to unknown options while processing of global options, that will only -result in an information in the \File{log}-file, unknown options assigned to -the package result in error messages. +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. \Macro{FamilyProcessOptions} may be interpreted either as an extension of \Macro{ProcessOption*} or as an extension of the \PName{key=value} mechanism -of \Package{keyval}. Finally \PName{key=value} pairs become options with help -of \Macro{FamilyProcessOptions}.% +of \Package{keyval}. Ultimately, with the help of +\Macro{FamilyProcessOptions}, \PName{key=value} pairs become options.% % \EndIndex{Cmd}{FamilyProcessOptions}% @@ -285,17 +340,17 @@ of \Macro{FamilyProcessOptions}.% \end{Declaration} \BeginIndex{Cmd}{FamilyExecuteOptions}% This command is an extension of \Macro{ExecuteOptions} from the \LaTeX{} -kernel (see \cite{latex:clsguide}). Thereby the command processes not only -options, that has been defined using \Macro{DeclareOption}. Also all keys of -the given family member will be processed. If the optional argument -\Macro{family member} is omitted, then +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 ``\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 will be set also -and before the keys of the family members. +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. \begin{Example} - Assumed, option \Option{coldcut} should be set by default already in the + Assume option \Option{coldcut} should be set by default in the previous example. In this case only line \begin{lstcode} \FamilyExecuteOptions{butcher}{coldcut} @@ -307,31 +362,27 @@ and before the keys of the family members. \begin{Declaration} - \Macro{FamilyOptions}\Parameter{family}\Parameter{options list}\\ - \Macro{Family@Options}\Parameter{family}\Parameter{options list}% - \Parameter{error action} + \Macro{FamilyOptions}\Parameter{family}\Parameter{options list}% \end{Declaration} \BeginIndex{Cmd}{FamilyOptions}% -\BeginIndex{Cmd}{Family@Options}% -Thereby \PName{options list} is like: +Hence \PName{options list} is like: \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} -whereby the value assignment may be omitted for \PName{key}s, that have a +after which the value assignment may be omitted for \PName{key}s that have a defined default. -In opposite to average options, that has been defined using -\Macro{DeclareOption}, the \PName{key}s may also be set after loading a class -or package. For this the user uses \Macro{FamilyOptions}. Thereby the -\PName{key}s of all members of the given family will be set. If a \PName{key} -also exists as an family attribute, then the family key will be set -first. After this the member keys will follow in the order, the members has -been defined. If a given \PName{key} does exist neither in the family nor in -any member of the family, then \Macro{FamilyOptions} will result in an -error. In opposite to this with \Macro{Family@Options} the user may declare -his own \PName{error action}. But this internal command is reserved for -authors of classes and packages. +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 \Macro{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 cut: @@ -343,15 +394,15 @@ authors of classes and packages. \FamilyProcessOptions{butcher}\relax \FamilyOptions{butcher}{coldcut} \end{lstcode} - If currently non of the sausage packages has been loaded, then an error - message would result because of undefined option ``\Option{coldcut}''. Dies - may be avoided changing the last line of the previous code into: + If currently none of the sausage packages are loaded, then an error + message results because of undefined option ``\Option{coldcut}''. This is + avoided by changing the last line of the code to: \begin{lstcode}[moretexcs={Family@Options}] \Family@Options{butcher}{coldcut}{} \end{lstcode} - Nevertheless, sausage packages, that will be loaded after - \Package{sausagesalad}, won't produce cold cut. This may be changed - additionally, by changing the last line again: + Despite this, sausage packages loaded after + \Package{sausagesalad} still do not produce cold cut. This may be corrected + by editing the last line of the code again to: \begin{lstcode}[moretexcs={Family@Options}] \AtBeginDocument{% \Family@Options{butcher}{coldcut}{% @@ -361,40 +412,34 @@ authors of classes and packages. }% }% \end{lstcode} - This will also throw a warning message, if non of the sausage packages will - be loaded. + This may throw a warning message if none of the sausage packages are loaded. \end{Example} % -\EndIndex{Cmd}{Family@Options}% \EndIndex{Cmd}{FamilyOptions}% \begin{Declaration} \Macro{FamilyOption}\Parameter{family}% - \Parameter{option}\Parameter{values list}\\ - \Macro{Family@Option}\Parameter{family}% - \Parameter{option}\Parameter{values list}% - \Parameter{error action} + \Parameter{option}\Parameter{values list}% \end{Declaration} \BeginIndex{Cmd}{FamilyOption}% -\BeginIndex{Cmd}{Family@Option}% -Beside options that have concurrently excluding values, there may be options, -that have several values at the same time. Using \Macro{FamilyOptions} for -that kind of options would result in using the same option several times with +Besides options that have concurrently excluding values, there may be options +that produce several values at the same time. Using \Macro{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: +\PName{values 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 into braces. The general functionality of these commands -is the same like that of the previous commands \Macro{FamilyOptions} and -\Macro{Family@Options}. +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 \Macro{FamilyOptions}. \begin{Example} Package \Package{sausagesalad} should have one mire option, to add - additional ingredients. Each of the ingredients will set a switch like done - before for the cold cut. + additional ingredients. Each of the ingredients sets a switch as was done + previously for the cold cut. \begin{lstcode} \newif\if@saladwith@onions \newif\if@saladwith@gherkins @@ -403,8 +448,9 @@ is the same like that of the previous commands \Macro{FamilyOptions} and \csname @saladwith@#1true\endcsname } \end{lstcode} - Here the three ingredients ``onions'', ``gherkins'', and ``chillies'' has - been defined. An error message for not defined ingredients doesn't exist. + Here the three ingredients ``onions'', ``gherkins'', and ``chillies'' have + been defined. An error message for ``not defined'' ingredients does not + exist. For a salad with onions and gherkins the user may use \begin{lstcode} @@ -418,11 +464,26 @@ is the same like that of the previous commands \Macro{FamilyOptions} and \end{lstcode} \end{Example} % -\EndIndex{Cmd}{Family@Option}% \EndIndex{Cmd}{FamilyOption}% \begin{Declaration} + \Macro{AtEndOfFamilyOptions}\Parameter{action}% +\end{Declaration} +\BeginIndex{Cmd}{AtEndOfFamilyOptions}% +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 \Macro{FamilyProcessOptions}, +\Macro{FamilyExecuteOptions}, \Macro{FamilyOptions}, or \Macro{FamilyOption} +is finished. This may be done using \Macro{AtEndOfFamilyOptions} 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. +% +\EndIndex{Cmd}{AtEndOfFamilyOptions}% + + +\begin{Declaration} \Macro{FamilyBoolKey}\OParameter{family member}\Parameter{family}% \Parameter{key}\Parameter{switch name}\\ \Macro{FamilySetBool}\Parameter{family}% @@ -430,31 +491,33 @@ is the same like that of the previous commands \Macro{FamilyOptions} and \end{Declaration} \BeginIndex{Cmd}{FamilyBoolKey}% \BeginIndex{Cmd}{FamilySetBool}% -In the previous examples boolean switches often have been used. In the example -with option \Option{coldcut} is was necessary, that the user assigns either -value \PValue{true} or value \PValue{false}. No error message existed on wrong -value assignment. Because of such boolean switches are an often needed -feature, \Package{scrbase} provides \Macro{FamilyBoolKey} for definition of -such options. Thereby the arguments \PName{family member}, \PName{family}, -and \PName{key} are same like used by \Macro{DefineFamilyKey} (see +In the previous examples, boolean switches often have been used. In the example +with option \Option{coldcut}, 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 \Macro{DefineFamilyKey} (see \autopageref{desc:scrbase.cmd.DefineFamilyKey}). Argument \PName{switch name} is the name of the switch without the prefix \Macro{if}. If a switch with this -name doesn't exist already, \Macro{FamilyBoolKey} will define it and +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 \Macro{DefineFamilyKey}. The \PName{default} for those options is always \PValue{true}. -\Macro{FamilySetBool} on the other side understands \PName{value} \PValue{on} +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 \Macro{FamilyUnknownKeyValue} with the arguments \PName{family}, -\PName{key}, and \PName{value}. This will normally result in an error message -about unknown value assignment (see also -\autopageref{desc:scrbase.cmd.FamilyUnkownKeyValue}). +\PName{key}, and \PName{value}, which results in setting of +\Macro{FamilyKeyState}. Depending on the command used and other family +members, this may result in an error message about unknown value assignment +(see also \autopageref{desc:scrbase.cmd.FamilyUnkownKeyValue} and +\autopageref{desc:scrbase.cmd.FamilyKeyState}). \begin{Example} - The key \Option{coldcut} 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 cut. + The key \Option{coldcut} 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 cut. \begin{lstcode} \FamilyBoolKey{butcher}{coldcut}% {@coldcut} @@ -467,13 +530,13 @@ about unknown value assignment (see also ... \fi \end{lstcode} - This would be the same in each of the three sausage packages. With this the - attribute ``coldcut'' may be defined as a family option: + This would be the same in each of the three sausage packages, thereby + defining the attribute ``coldcut'' as a family option: \begin{lstcode}[moretexcs={define@key}] \@ifundefined{if@coldcut}{% \expandafter\newif\csname if@coldcut\endcsname }{}% - \define@key{butcher}{coldcut}[true]{% + \DefineFamilyKey[]{butcher}{coldcut}[true]{% \FamilySetBool{butcher}{coldcut}% {@coldcut}% {#1}% @@ -485,7 +548,7 @@ about unknown value assignment (see also {@coldcut} \end{lstcode} using the additional information at - \autopageref{explain:scrbase.macro.DefineFamilyKey}, that's not only valid + \autopageref{explain:scrbase.macro.DefineFamilyKey}, this is not only valid for \Macro{DefineFamilyKey} but for \Macro{FamilyBoolKey} too. \end{Example} % @@ -506,10 +569,10 @@ about unknown value assignment (see also \end{Declaration} \BeginIndex{Cmd}{FamilyNumericalKey}% \BeginIndex{Cmd}{FamilySetNumerical}% -In opposite to switches that may be either true or false, also key exists, +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, e.\,g., left, centered, or right. Internally such -differentiations are often made using \Macro{ifcase}. This \TeX{} command +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: @@ -518,16 +581,16 @@ a \PName{key} has been named \Macro{FamilyNumericalKey} in \Parameter{value}\Parameter{definition}\texttt{,}% \dots \end{tabular}\vskip\dp\strutbox\end{flushleft} -So the \PName{values list} does not only define the supported values to the -\PName{key}. For each of the \PName{value}s it also gives the -\PName{definition} of macro \Macro{\PName{command}}. 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 while the +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. \begin{Example} The sausage may be cut different. For example the cold cut may stay uncut or - will by cut roughly or may be cut thinly. This information should be stored + will be cut roughly or may be cut thinly. This information should be stored in command \Macro{cuthow}. \begin{lstcode} \FamilyNumericalKey{butcher}% @@ -551,10 +614,10 @@ assignment. \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 like shown in this example. + 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 wouldn't be + should be evaluated later. In this case a textual definition would not be useful. If the key is defined like this: \begin{lstcode} \FamilyNumericalKey{butcher}% @@ -564,7 +627,7 @@ assignment. {thin}{2}% } \end{lstcode} - then a condition like this: + then a condition like the following may be used: \begin{lstcode} \ifcase\cuthow % no cut @@ -574,9 +637,8 @@ assignment. % thin cut \fi \end{lstcode} - may be used. \end{Example} -Internally \Macro{FamilyNumericalKey} uses \Macro{FamilySetNumerical} as +Internally, \Macro{FamilyNumericalKey} uses \Macro{FamilySetNumerical} as \PName{action} of \Macro{DefineFamilyKey}. If a unknown value is assigned to such a key, \Macro{FamilySetNumerical} will call \Macro{FamilyUnkownKeyValue} with the arguments \PName{family}, \PName{key} and \PName{value}. This will @@ -593,18 +655,19 @@ normally result in an error message about assigning an unknown value. \OParameter{default}\Parameter{command} \end{Declaration} \BeginIndex{Cmd}{FamilyStringKey}% -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 their +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 is no optional argument for the \PName{default}, \Macro{FamilyStringKey} is -the same like +the same as: \begin{quote} \Macro{DefineFamilyKey}\OParameter{family member}\Parameter{family}% \Parameter{key}\\ \hphantom{\Macro{DefineFamilyKey}}% -\PParameter{\Macro{def}\PName{command}\string{\#1\string}}. +\PParameter{\Macro{def}\PName{command}\string{\#1\string}% +\Macro{FamilyKeyStateProcessed}}. \end{quote} -If an optional argument \PName{default} has been used, \Macro{FamilyStringKey} -is the same like +If an optional argument \PName{default} is used, \Macro{FamilyStringKey} +is the same as: \begin{quote} \Macro{DefineFamilyKey}\OParameter{family member}\Parameter{family}% \Parameter{key}\\ @@ -612,13 +675,12 @@ is the same like \OParameter{default}% \PParameter{\Macro{def}\PName{command}\string{\#1\string}}. \end{quote} -If \PName{command} hasn't been defined already, an empty macro will be -defined. +If \PName{command} is not been defined, an empty macro will be defined. \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: + \PValue{saladweight}, too: \begin{lstcode} \newcommand*{\saladweight}{250g} \FamilyStringKey{butcher}% @@ -629,11 +691,11 @@ defined. \begin{lstcode} \FamilyOptions{butcher}{saladweight} \end{lstcode} - That may be done, because the default weight has been set as default at the + This may be done, because the default weight has been set as default at the definition of the option above. \end{Example} -In this case there are no unknown values, because all values are simply used -for a macro definition. Nevertheless, you should note, that paragraph breaks +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. % \EndIndex{Cmd}{FamilyStringKey}% @@ -641,8 +703,7 @@ at the value assignment to the key are not allowed. \begin{Declaration} \Macro{FamilyUnkownKeyValue}\Parameter{family}\Parameter{key}% - \Parameter{value}\Parameter{values list}\\ - \Macro{FamilyElseValues} + \Parameter{value}\Parameter{values list}% \end{Declaration} \BeginIndex{Cmd}{FamilyUnkownKeyValue}% \BeginIndex{Cmd}{FamilyElseValues}% @@ -652,17 +713,10 @@ 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} -Additional allowed values may be set by \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} -These will also be shown in the error message. \Macro{FamilySetBool} as well -as \Macro{FamilySetNumerical} will reset \Macro{FamilyElseValue} to an empty -definition automatically\,---\,independent of whether or not a error has been -thrown. +Currently\ChangedAt{v3.12}{\Package{scrbase}}, \PName{values list} is +not used by \Package{scrbase}. \begin{Example} - Now, for the cold cut the choices should be cut or no cut and in case of cut + Now, for the cold cut, the choices should be cut or no-cut and in case of cut rough or thin. Rough should be the default for cutting. \begin{lstcode} \@ifundefined{if@thincut}{% @@ -673,31 +727,62 @@ thrown. \newif\csname if@coldcut\endcsname}{} \DefineFamilyKey{butcher}% {coldcut}[true]{% - \ifstr{#1}{thin}{% - \@coldcuttrue - \@thincuttrue - }{% + \FamilySetBool{butcher}{coldcut}% + {@coldcut}% + {#1}% + \ifx\FamilyKeyState\FamilyKeyStateProcessed \@thincutfalse - \def\FamilyElseValue{, `thin'}% - \FamilySetBool{butcher}{coldcut}% - {@coldcut}% - {#1}% - }% + \else + \ifstr{#1}{thin}{% + \@coldcuttrue + \@thincuttrue + \FamilyKeyStateProcessed + }{}% + \fi }% \end{lstcode} - Command \Macro{ifstr} used at the example code above will be described at - \autopageref{desc:scrbase.cmd.ifstr} in \autoref{sec:scrbase.if}. + Let's have a look at the definition of \Option{butcher}: + First of all, we try to set the boolean switch of cold cut using + \Macro{FamilySetBool}. After this command, we test whether or not + \Macro{FamilyKeyState} signals the success of the command with state + \Macro{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 cut and thin cut are activated and the state will be + switched to \Macro{FamilyKeyStateProcessed}. If the last test failed also, + the failure state of \Macro{FamilySetBool} is still valid at the end of the + execution. + + Command \Macro{ifstr} is used for the thin test. It is + described on \autopageref{desc:scrbase.cmd.ifstr} in + \autoref{sec:scrbase.if}. \end{Example} % -\EndIndex{Cmd}{FamilyElseValues}% \EndIndex{Cmd}{FamilyUnkownKeyValue}% +\begin{Declaration} + \Macro{FamilyElseValues} +\end{Declaration} +\BeginIndex{Cmd}{FamilyElseValues}% +With former releases\ChangedAt{v3.12}{\Package{scrbase}} of \Package{scrbase}, +additional allowed values reported by \Macro{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 \Macro{FamilyUnknownValue} does not report errors itself, +but signals them using \Macro{FamilyKeyState}. Therefore, +\Macro{FamilyElseValues} became deprecated. Nevertheless, its former usage is +recognised by \Package{scrbase} and results in a code change demand message.% +\EndIndex{Cmd}{FamilyElseValues}% + \section{Conditional Execution} \label{sec:scrbase.if} The package \Package{scrbase} provides several commands for conditional -execution. Thereby not the \TeX{} syntax of conditionals, e.\,g., +execution. other than the \TeX{} syntax of conditionals, e.\,g., % Umbruchkorrektur \begin{lstcode}[belowskip=\dp\strutbox] \iftrue @@ -706,21 +791,21 @@ execution. Thereby not the \TeX{} syntax of conditionals, e.\,g., ... \fi \end{lstcode} -but the \LaTeX{} syntax also known from \LaTeX{} commands like +yet the \LaTeX{} syntax also known from \LaTeX{} commands like \Macro{IfFileExists}, \Macro{@ifundefined}, \Macro{@ifpackageloaded}, and many -others will be used. Nevertheless, some package authors prefer to use the -\TeX{} syntax even for users at the \LaTeX{} interface level. In fact the -conditionals of \Package{scrbase} are very basic conditionals, this could -result in conditionals with the same name but different syntax and though in -naming conflicts. Because of this \Package{scrbase} firstly defines these -conditionals as internal commands with prefix \Macro{scr@}. Additional user -commands without this prefix are additionally defined. But the definition of -the user commands may be suppressed with option \Option{internalonly} (see +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 \Option{internalonly} (see \autoref{sec:scrbase.loadit}, \autopageref{desc:scrbase.option.internalonly}). -Authors of packages and classes should use the internal commands like +Authors of packages and classes should use the internal commands as \KOMAScript{} itself does. Nevertheless, for completeness the user commands -are described additionally. +are described separately. \begin{Declaration} @@ -733,12 +818,12 @@ are described additionally. \BeginIndex{Cmd}{ifundefinedorrelax}% 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 opposite to -\Macro{@ifundefined} \Macro{\PName{name}} won't be defined to be \Macro{relax} -in the case it wasn't defined before. Using \eTeX{} this case won't at least -consume any hash memory.% + 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.% % \EndIndex{Cmd}{ifundefinedorrelax}% \EndIndex{Cmd}{scr@ifundefinedorrelax}% @@ -753,11 +838,10 @@ consume any hash memory.% \BeginIndex{Cmd}{scr@ifpdftex}% \BeginIndex{Cmd}{ifpdftex}% If pdf\TeX{} has been used, the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. Whether or not a PDF-file will be -out, doesn't matter. Nevertheless, this pdf\TeX{} test seems so make sense -seldom only. Generally it's recommended to test for the wanted commands -instead (see previous \Macro{scr@ifundefinedorrelax} and -\Macro{ifundefinedorrelax}). +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 \Macro{ifundefinedorrelax}). % \EndIndex{Cmd}{ifpdftex}% \EndIndex{Cmd}{scr@ifpdftex}% @@ -772,9 +856,9 @@ instead (see previous \Macro{scr@ifundefinedorrelax} and \BeginIndex{Cmd}{scr@ifVTeX}% \BeginIndex{Cmd}{ifVTeX}% If V\TeX{} has been used, the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. This test seems so make sense -seldom only. Generally it's recommended to test for the wanted commands instead -(see previous \Macro{scr@ifundefinedorrelax} and \Macro{ifundefinedorrelax}). +otherwise the \PName{else instructions}. This test is seldom useful. Test for +the desired command instead (see previous \Macro{scr@ifundefinedorrelax} and +\Macro{ifundefinedorrelax}). % \EndIndex{Cmd}{ifVTeX}% \EndIndex{Cmd}{scr@ifVTeX}% @@ -788,9 +872,9 @@ seldom only. Generally it's recommended to test for the wanted commands instead \end{Declaration} \BeginIndex{Cmd}{scr@ifpdfoutput}% \BeginIndex{Cmd}{ifpdfoutput}% -While PDF-file generation the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. Whether, e.\,g., pdf\TeX{} or V\TeX{} -is used to generate the PDF-file doesn't matter. +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. % \EndIndex{Cmd}{ifpdfoutput}% \EndIndex{Cmd}{scr@ifpdfoutput}% @@ -804,12 +888,11 @@ is used to generate the PDF-file doesn't matter. \end{Declaration} \BeginIndex{Cmd}{scr@ifpsoutput}% \BeginIndex{Cmd}{ifpsoutput}% -While PostScript-file generation the \PName{then instructions} will be executed, -otherwise the \PName{else instructions}. V\TeX{} provides direct PostScript -generation, that will be recognized here. If V\TeX{} is not used but a switch -\Macro{if@dvips} has been defined, the decision depends on that -switch. \KOMAScript{}, e.\,g., provides \Macro{if@dvips} in -\Package{typearea}. +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}. % \EndIndex{Cmd}{ifpsoutput}% \EndIndex{Cmd}{scr@ifpsoutput}% @@ -823,7 +906,7 @@ switch. \KOMAScript{}, e.\,g., provides \Macro{if@dvips} in \end{Declaration} \BeginIndex{Cmd}{scr@ifdvioutput}% \BeginIndex{Cmd}{ifdvioutput}% -While DVI-file generation the \PName{then instructions} will be executed, +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. @@ -839,8 +922,8 @@ generation is assumed. \BeginIndex{Cmd}{ifnotundefined}% \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, the \PName{else instructions} -otherwise. There's no corresponding internal command for this. +executed if the command is defined, otherwise the \PName{else + instructions}. There is no corresponding internal command. % \EndIndex{Cmd}{ifnotundefined}% @@ -850,23 +933,159 @@ otherwise. There's no corresponding internal command for this. \Parameter{then instructions}\Parameter{else instructions} \end{Declaration} \BeginIndex{Cmd}{ifstr}% -Both \PName{string} arguments will be expanded and afterward compared. If the -expansions are same, the \PName{then instructions} will be -executed, otherwise the \PName{else instructions}. There's no corresponding -internal command for this. +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 +command. % \EndIndex{Cmd}{ifstr}% +\begin{Declaration} + \Macro{ifstrstart}\Parameter{string}\Parameter{string}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifstrstart}% +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.% +\EndIndex{Cmd}{ifstrstart}% + +\begin{Declaration} + \Macro{ifisdimen}\Parameter{code}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifisdimen}% +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.% +\EndIndex{Cmd}{ifisdimen}% + +\begin{Declaration} + \Macro{ifisdimension}\Parameter{code}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifisdimension}% +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.% +\EndIndex{Cmd}{ifisdimension}% + +\begin{Declaration} + \Macro{ifisdimexpr}\Parameter{code}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifisdimexpr}% +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.% +\EndIndex{Cmd}{ifisdimexpr}% + +\begin{Declaration} + \Macro{ifisskip}\Parameter{code}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifisskip}% +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.% +\EndIndex{Cmd}{ifisskip}% + +\begin{Declaration} + \Macro{ifisglue}\Parameter{code}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifisglue}% +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.% +\EndIndex{Cmd}{ifisglue}% + +\begin{Declaration} + \Macro{ifisglueexpr}\Parameter{code}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifisglueexpr}% +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.% +\EndIndex{Cmd}{ifisglueexpr}% + +\begin{Declaration} + \Macro{ifiscount}\Parameter{code}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifiscount}% +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 +\Macro{ifiscounter}.% +\EndIndex{Cmd}{ifiscount}% + +\begin{Declaration} + \Macro{ifisnumber}\Parameter{code}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifisnumber}% +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.% +\EndIndex{Cmd}{ifisnumber}% + +\begin{Declaration} + \Macro{ifisnumexpr}\Parameter{code}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifisnumexpr}% +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.% +\EndIndex{Cmd}{ifisnumexpr}% + +\begin{Declaration} + \Macro{ifiscounter}\Parameter{counter}% + \Parameter{then instructions}\Parameter{else instructions} +\end{Declaration} +\BeginIndex{Cmd}{ifiscounter}% +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.% +\EndIndex{Cmd}{ifiscounter}% \begin{Declaration} \Macro{ifnumber}\Parameter{string}% \Parameter{then instructions}\Parameter{else instructions} \end{Declaration} \BeginIndex{Cmd}{ifnumber}% -Note, that this does not compare numbers. The \PName{then instructions} will -be executed, if the expansion of \PName{string} consists of digits -only. Otherwise the \PName{else instructions} will be used. There's no -corresponding internal command for this. +Note that this does not compare numbers. The \PName{then instructions} will +be executed if the expansion of \PName{string} consists of digits +only. Otherwise the \PName{else instructions} will be used. There is no +corresponding internal command. % \EndIndex{Cmd}{ifnumber}% @@ -876,10 +1095,10 @@ corresponding internal command for this. \Parameter{then instructions}\Parameter{else instructions} \end{Declaration} \BeginIndex{Cmd}{ifdimen}% -Note, that this does not compare dimensions. The \PName{then instructions} will +Note that this does not compare dimensions. The \PName{then instructions} will be executed, if the expansion of \PName{string} consists of digits and a valid -unit of length. Otherwise the \PName{else instructions} will be used. There's no -corresponding internal command for this. +unit of length. Otherwise, the \PName{else instructions} will be used. There +is no corresponding internal command. % \EndIndex{Cmd}{ifdimen}% @@ -890,11 +1109,11 @@ corresponding internal command for this. \end{Declaration} \BeginIndex{Cmd}{if@atdocument}% This command exists intentionally as internal command only. In the document -preamble \Macro{if@atdocument} is same like \Macro{iffalse}. After -\Macro{begin}\PParameter{document} it's same like \Macro{iftrue}. Authors of -classes and packages may use this, if a command should work somehow different -depending in whether it has been used in the preamble or inside the documents -body. Please note\textnote{Attention!}, that this is a condition in \TeX{} +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! % \EndIndex{Cmd}{if@atdocument}% @@ -906,77 +1125,106 @@ syntax not in \LaTeX{} syntax! \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 +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 fact that some packages like \Package{german}\IndexPackage{german} or \Package{ngerman}\IndexPackage{ngerman} redefine those settings when the -packages are loaded. This definitions unfortunately occurs in such a manner as +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 own 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, +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. \begin{Declaration} + \Macro{defcaptionname}% + \Parameter{language list}\Parameter{term}\Parameter{definition}\\ \Macro{providecaptionname}% - \Parameter{language}\Parameter{term}\Parameter{definition}\\ + \Parameter{language list}\Parameter{term}\Parameter{definition}\\ \Macro{newcaptionname}% - \Parameter{language}\Parameter{term}\Parameter{definition}\\ + \Parameter{language list}\Parameter{term}\Parameter{definition}\\ \Macro{renewcaptionname}% - \Parameter{language}\Parameter{term}\Parameter{definition} + \Parameter{language list}\Parameter{term}\Parameter{definition}\\ + \Macro{defcaptionname*}% + \Parameter{language list}\Parameter{term}\Parameter{definition}\\ + \Macro{providecaptionname*}% + \Parameter{language list}\Parameter{term}\Parameter{definition}\\ + \Macro{newcaptionname*}% + \Parameter{language list}\Parameter{term}\Parameter{definition}\\ + \Macro{renewcaptionname*}% + \Parameter{language list}\Parameter{term}\Parameter{definition} \end{Declaration} +\BeginIndex{Cmd}{defcaptionname}% \BeginIndex{Cmd}{providecaptionname}% \BeginIndex{Cmd}{newcaptionname}% \BeginIndex{Cmd}{renewcaptionname}% Using one of these commands, the user can assign a \PName{definition} for a -particular \PName{language} to a \PName{term}. The \PName{term} is always a -macro. The commands differ dependent on whether a given \PName{language} or a -\PName{term} within a given \PName{language} are already defined or not at the +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 \PName{language} is not defined, then \Macro{providecaptionname} does -nothing other than writes a message in the log file. This happens only once -for each language. If \PName{language} is defined but \PName{term} is not yet +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 -\PName{term} will not be redefined if the \PName{language} already has such a +\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 the -\PName{language} is not yet defined, then a new language command will be -created and a message written to the log file. For \PName{language} -\PValue{USenglish}, e.\,g.\, this would be the language command -\Macro{captionsUSenglish}. If \PName{term} is not yet defined in -\PName{language}, then it will be defined using \PName{definition}. If -\PName{term} already exists in \PName{language}, then this results in an error +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 \PName{language}. If neither -\PName{language} nor \PName{term} exist or \PName{term} is unknown in a -defined language then a error message will be given. Otherwise, the -\PName{term} for \PName{language} will be redefined according to +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}. -\KOMAScript{} itself employs \Macro{providecaptionname} in order to define the +\KOMAScript{} employs \Macro{providecaptionname} in order to define the commands in \autoref{sec:scrlttr2-experts.languages}. \begin{Example} - If you prefer ``fig.'' instead of ``figure'', you may achieve this using: + If you prefer ``fig.'' instead of ``figure'' in \PValue{USenglish}, you may + achieve this using: \begin{lstcode} \renewcaptionname{USenglish}{\figurename}{fig.} \end{lstcode} + If you want the same change not only in \PValue{USenglish} but also in + \PValue{UKenglish}, you do not need an additional: +\begin{lstcode} + \renewcaptionname{UKenglish}{\figurename}{fig.} +\end{lstcode} + but can simply extend the \PName{language list}: +\begin{lstcode} + \renewcaptionname{USenglish,UKenglish}{\figurename}{fig.} +\end{lstcode} + You can extend the \PName{language list} in the same manner by + \PValue{american}, \PValue{australian}, \PValue{british}, \PValue{canadian}, + and \PValue{newzealand}. \end{Example} -Since\textnote{Attention!} only existing terms in available languages can be -redefined using \Macro{renewcaptionname}, you have to put the command after -\Macro{begin}\PParameter{document} or delay the command by using -\Macro{AtBeginDocument}. Furthermore, you will get an error message if there -is no package used that switches language selection to, e.\,g., -\PName{USenglish} in the example above. +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}. @@ -1081,6 +1329,7 @@ packages are listed and described in \autoref{tab:scrbase.commonNames}. \EndIndex{Cmd}{providecaptionname}% \EndIndex{Cmd}{newcaptionname}% \EndIndex{Cmd}{renewcaptionname}% +\EndIndex{Cmd}{defcaptionname}% % \EndIndex{}{language>definition} @@ -1088,18 +1337,18 @@ packages are listed and described in \autoref{tab:scrbase.commonNames}. \section{Identification of \KOMAScript} \label{sec:scrbase.identify} -\Package{scrbase} may be used independent of \KOMAScript{} with -other packages and classes, nevertheless it's a \KOMAScript{} package. For -this is also provides commands to identify \KOMAScript{} and itself as a -\KOMAScript{} package. +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. \begin{Declaration} \Macro{KOMAScript} \end{Declaration} \BeginIndex{Cmd}{KOMAScript}% This command only sets the word ``\KOMAScript'' with sans-serif font and -a little bit tracking of the capitals. Bay the way: All \KOMAScript{} classes -and packages define this command, if it hasn't been defined already. The +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}. % \EndIndex{Cmd}{KOMAScript} @@ -1111,9 +1360,9 @@ definition is robust using \Macro{DeclareRobustCommand}. \BeginIndex{Cmd}{KOMAScriptVersion}% \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, +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. This document has been made, e.\,g., using +loading \Package{scrbase}, too. For example, this document has been made using \KOMAScript{} version ``\KOMAScriptVersion''. % \EndIndex{Cmd}{KOMAScriptVersion}% @@ -1122,8 +1371,8 @@ loading \Package{scrbase} too. This document has been made, e.\,g., using \section{Extension of the \LaTeX{} Kernel} \label{sec:scrbase:latexkernel} -Sometimes the \LaTeX{} kernel itself provides commands, but lacks of other, -similar commands, that would often be useful too. Some of those commands for +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}. \begin{Declaration} @@ -1133,14 +1382,14 @@ authors of packages and classes are provided by \Package{scrbase}. \BeginIndex{Cmd}{PackageInfoNoLine}% \BeginIndex{Cmd}{ClassInfoNoLine}% 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. Beside +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}, to write information without line numbers into the -log-file, are missing. Package \Package{scrbase} provides them. +\Macro{PackageInfoNoLine} for writing information without line numbers into the +log-file are missing. Package \Package{scrbase} provides them. % \EndIndex{Cmd}{ClassInfoNoLine}% \EndIndex{Cmd}{PackageInfoNoLine} @@ -1156,8 +1405,8 @@ 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}, that provides -several of such commands for different purpose (see \cite{package:etoolbox}). +usage of package \Package{etoolbox}\IndexPackage{etoolbox}, which provides +several of such commands for different purposes (see \cite{package:etoolbox}). % \EndIndex{Cmd}{l@addto@macro} @@ -1166,7 +1415,7 @@ several of such commands for different purpose (see \cite{package:etoolbox}). \label{sec:scrbase:etex} \eTeX{}, that is meanwhile used by \LaTeX{} and needed by \KOMAScript{}, -provides with \Macro{numexpr}\IndexCmd{numexpr} an extended feature for +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 @@ -1178,9 +1427,10 @@ operators would be useful. \end{Declaration}% \BeginIndex{Cmd}{XdivY}% \BeginIndex{Cmd}{XmodY}% -Having a division with remainder, command\ChangedAt{v3.05a}{\Package{scrbase}} -\Macro{XdivY} gives the value of the integer quotient, command \Macro{XmodY} -the value of the remainder. This kind of division is defined: +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: \[ \textit{dividend} = \textit{divisor} \cdot \textit{integer quotient} + \textit{remainder} @@ -1190,7 +1440,7 @@ is greater or equal to \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 is has +expression of \Macro{numexpr}. For output the value as an Arabic number has to be prefixed by \Macro{the}.% % \EndIndex{Cmd}{XmodY}% @@ -1203,7 +1453,7 @@ to be prefixed by \Macro{the}.% %%% Local Variables: %%% mode: latex %%% mode: flyspell -%%% ispell-local-dictionary: "english" +%%% ispell-local-dictionary: "en_GB" %%% coding: us-ascii %%% TeX-master: "../guide.tex" %%% End: |