summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex
diff options
context:
space:
mode:
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.tex1673
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
%