diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/english/scrbase.tex | 352 |
1 files changed, 333 insertions, 19 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 80ed5b2b037..2b7fadda1a4 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 @@ -46,11 +46,11 @@ % ====================================================================== \KOMAProvidesFile{scrbase.tex} - [$Date: 2019-01-15 08:29:44 +0100 (Tue, 15 Jan 2019) $ + [$Date: 2019-10-10 09:50:23 +0200 (Thu, 10 Oct 2019) $ KOMA-Script package scrbase] \translator{Markus Kohm\and Melvin Hendrix\and Karl Hagen} -% Date of the translated German file: 2018-08-27 +% Date of the translated German file: 2019-10-09 \chapter{Basic Functions in the \Package{scrbase} Package} \labelbase{scrbase} @@ -85,7 +85,7 @@ 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} +\section{Keys as Attributes of Families and Their Members} \seclabel{keyvalue} As already mentioned in \autoref{sec:scrbase.loadit}, \Package{scrbase} uses @@ -238,8 +238,8 @@ predefined states should be sufficient. 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. + The definitions for the other packages are nearly identical. Only the string + ``\texttt{salami}'' has to be replaced. \end{Example} % \EndIndexGroup @@ -373,9 +373,10 @@ If\ChangedAt{v3.20}{\Package{scrbase}} you call \Macro{FamilyExecuteOptions} 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. +of the unknown one. The value passed to the \Option{@else@} option is the +unknown option with the value specified in the call. \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.% @@ -451,9 +452,17 @@ members returns an error through \DescRef{\LabelBase.cmd.FamilyKeyState}. ensures that its own \Option{coldcuts} option has already been redefined. This avoids endless recursion. \end{Example} -% + +Like\ChangedAt{v3.27}{\Package{scrbase}} +\DescRef{\LabelBase.cmd.FamilyExecuteOptions}, \Macro{FamilyOptions} offers +special handling for an option named +\Option{@else@}\important{\Option{@else@}}. If a family member has such an +option, it will be executed whenever an option in the \PName{option list} is +unrecognized by the member. If the family itself defines an option +\Option{@else@}, it will only be called if neither the family nor any of its +members were able to fully process the given option by executing +\DescRef{\LabelBase.cmd.FamilyKeyStateProcessed}.% \EndIndexGroup -\vskip-\ht\strutbox% Umbruchkorrektur wegen Beispiel am Ende \begin{Declaration} @@ -499,7 +508,9 @@ described for \DescRef{\LabelBase.cmd.FamilyOptions}. {ingredient}{onions,gherkins} \end{lstcode} \end{Example} -% + +An\ChangedAt{v3.27}{\Package{scrbase}} \Option{@else@} option is processed +in the same manner as with \DescRef{\LabelBase.cmd.FamilyOptions}.% \EndIndexGroup @@ -615,8 +626,24 @@ message about an unknown value assignment is printed if necessary (see also \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} -% +\end{Example}% +\EndIndexGroup + +\begin{Declaration} + \Macro{FamilyInverseBoolKey}\OParameter{member}\Parameter{family} + \Parameter{key}\Parameter{switch name} + \Macro{FamilySetInverseBool}\Parameter{family} + \Parameter{key}\Parameter{switch name} + \Parameter{value} +\end{Declaration} +These\ChangedAt{v3.27}{\Package{scrbase}} two commands differ from +\DescRef{\LabelBase.cmd.FamilyBoolKey} and +\DescRef{\LabelBase.cmd.FamilySetBool}, respectively, only in that the +logic is inverted. This means that the values \PValue{true}, \PValue{yes}, and +\PValue{on} set the boolean switch given by \PName{switch name} to +\Macro{iffalse} and therefore deactivate it. The values \PValue{false}, +\PValue{no}, and \PValue{off} set the boolean switch to \Macro{iftrue} and +therefore activate it.% \EndIndexGroup @@ -763,13 +790,13 @@ is called applies.% \OParameter{default}\Parameter{macro} \Macro{FamilySetLengthMacro}\Parameter{family} \Parameter{key}\Parameter{macro} - \Parameter{value}% + \Parameter{value} \Macro{FamilyUseLengthMacroKey}\OParameter{member}\Parameter{family} \Parameter{key} \OParameter{default}\Parameter{macro} \Macro{FamilySetUseLengthMacro}\Parameter{family} \Parameter{key}\Parameter{macro} - \Parameter{value}% + \Parameter{value} \end{Declaration} With\ChangedAt{v3.12}{\Package{scrbase}} \Macro{FamilyLengthKey}, you can define a \PName{key} that represents a \PName{length}. It does not matter @@ -1313,6 +1340,67 @@ corresponding internal command.% \EndIndexGroup +\begin{Declaration} + \Macro{IfActiveMkBoth}\Parameter{then code}\Parameter{else code} +\end{Declaration} +The\ChangedAt{v3.27}{\Package{scrbase}} \LaTeX{} kernel uses +\DescRef{scrlayer.cmd.@mkboth}\important{\Macro{@mkboth}}\IndexCmd{@mkboth} to +distinguish between automatic and manual running heads. Usually, it sets both +marks with automatic running heads. With manual running heads, it does not set +any mark. To determine whether automatic running heads are active, many +packages compare \DescRef{scrlayer.cmd.@mkboth} with either +\DescRef{maincls.cmd.markboth}\IndexCmd{markboth} or \Macro{@gobbletwo}. But +this does not account for all cases in which \DescRef{scrlayer.cmd.@mkboth} +may be redefined. Therefore \Macro{IfActiveMkBoth} tests if +\DescRef{scrlayer.cmd.@mkboth} would actually set a mark, even when +\Macro{marks} appears in the definition of \DescRef{scrlayer.cmd.@mkboth}. If +such an active \DescRef{scrlayer.cmd.@mkboth} is detected, the +\PName{then code} is executed. In all other cases, the \PName{else code} is +used.% +\begin{Example} + For example, suppose you want to set the right mark if and only if + automatic running heads are used, e.\,g., the pagestyle + \PageStyle{headings}\IndexPagestyle{headings}. For a first attempt, + you might use: +\begin{lstcode} + \ifx\@mkboth\markboth \markright{running head}\fi +\end{lstcode} + Later you discover that some package does not use the usual +\begin{lstcode} + \let\@mkboth\markboth +\end{lstcode} + but +\begin{lstcode} + \renewcommand{\@mkboth}{\markboth} +\end{lstcode} + to activate automatic running heads. Because of this, your comparison always + fails and never calls \DescRef{maincls.cmd.markright}. To solve this, you + try the following change: +\begin{lstcode} + \ifx\@mkboth\@gobbletwo\else \markright{running head}\fi +\end{lstcode} + Unfortunately, now \DescRef{maincls.cmd.markright} is also called for + manual running heads, because someone has defined +\begin{lstcode} + \renewcommand{\@mkboth}[2]{% + \typeout{DEBUG: ignoring running head setting}% + } +\end{lstcode} + for this case. + + Fortunately, both problems are easy to solve with \Package{scrbase}: +\begin{lstcode} + \IfActiveMKBoth{\markright{Kolumnentitel}}{} +\end{lstcode}% +\end{Example} +By the way, an even simpler solution for the problem in the example +would be to use \DescRef{scrlayer.cmd.@mkright} from package +\hyperref[cha:scrlayer]{\Package{scrlayer}} (see +\autoref{sec:scrlayer.pagestyle.content}, +\DescPageRef{scrlayer.cmd.@mkright}).% +\EndIndexGroup + + \section{Defining Language-Dependent Terms} \seclabel{languageSupport} \BeginIndexGroup @@ -1628,10 +1716,9 @@ correctly. Sometimes additional operators would be useful. \Macro{XdivY}\Parameter{dividend}\Parameter{divisor}% \Macro{XmodY}\Parameter{dividend}\Parameter{divisor}% \end{Declaration}% -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 +The\ChangedAt{v3.05a}{\Package{scrbase}} \Macro{XdivY} command returns the +value of the integer quotient, with the \Macro{XmodY} command 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} @@ -1645,9 +1732,236 @@ using \Macro{numexpr}. To output the value as an Arabic number, you must prefix it with \Macro{the}.% % \EndIndexGroup + + +\section[{General Mechanism for Multi-Level Hooks}] +{General Mechanism for Multi-Level + Hooks\ChangedAt[2019/01]{v3.27}{\Package{scrbase}}} +\seclabel{hooks} + +\BeginIndexGroup +\BeginIndex{}{Hooks} +The \LaTeX{} kernel provides a few \emph{hooks} in the processing of +a document where additional code can be inserted. Class and package authors +should be very familiar with \Macro{AtBeginDocument} and +\Macro{AtEndDocument}. \KOMAScript{} offers similar features in some places, +for example to hook code into the execution of +\hyperref[sec:maincls.structure]{sectioning commands}. Over the years, there +have been two problems: +\begin{itemize} + \item There are never enough hooks. + \item There is some code that should only be executed once, as if it almost + drops off the hook, as well as code that must be executed each time the + hook is encountered, thus remaining permanently on the hook. +\end{itemize} +Usually, to define a single hook you must define a command that collects the +code for each hook. This code is then stored in another internal macro, which +must be inserted at the point where the collected code is executed. The more +hooks you insert, the more such commands there are. To allow for both +single-use code and permanent code may even require two hooks, and therefore +twice the number of commands to be defined. + +The example of sectioning commands shows that the first problem can sometimes +be exacerbated by having only a single point for code execution. One package +author may need only one way to execute the same code for all sectioning +commands. Another package author would prefer to execute different code for +certain sectioning commands only. Meeting both these demands would require a +general hook as well as a hook for each sectioning command. These requirements +are doubled again because of the second problem. + +\KOMAScript{} therefore offers a generalized hook mechanism in +\Package{scrbase} that provides multi-level hooks for both single-use and +persistent code. These hooks are named \emph{do-hooks} because of their +implementation. From this also comes the names of the instructions by which +they are controlled. + +\begin{Declaration} + \Macro{ExecuteDoHook}\Parameter{specifier} +\end{Declaration} +Hooks\ChangedAt[2019/01]{v3.27}{\Package{scrbase}} are implemented with this +command. The \PName{specifier} determines the name or names of the hook. The +\PName{specifier} is always completely expanded for analysis. + +The \PName{specifier} generally consists of strings separated by forward +slashes (``/''). Initially, \Macro{ExecuteDoHook} divides the string at the +first slash. The first part is the name. The remainder (without the slash) is +the argument. Then the code for the hook with this name is executed. Next the +first part of the remaining string is divided again from the remainder, +combined with a slash after the name to form a new name, and the code with +this name is executed. This process continues until the code for the hook with +the name \PName{specifier} has been executed and the argument is empty. + +In the simplest case, the \PName{specifier} consists of a single name. In this +case, the persistent code is executed first, with an empty argument, for +exactly one hook specified by this name. + +At each stage of execution, single-use code is also executed after the hook's +persistent code, and then the single-use code is globally removed from the +hook. + +\begin{Example} + By inserting \DescRef{\LabelBase.cmd.ExecuteDoHook}% + \PParameter{heading/begingroup/\PName{name}} into the execution of each + sectioning command defined with + \DescRef{maincls-experts.cmd.DeclareSectionCommand}, the \KOMAScript{} + classes ultimately have six hooks inserted at that code-point, executed in + this order: + \begin{enumerate} + \item \PValue{heading} with the argument \PValue{begingroup/}\PName{name} + for persistent code, + \item \PValue{heading} with the argument \PValue{begingroup/}\PName{name} + for single-use code, + \item \PValue{heading/begingroup} with the argument \PName{name} for + persistent code, + \item \PValue{heading/begingroup} with the argument \PName{name} for + single-use code, + \item \PValue{heading/begingroup/}\PName{name} with an empty argument for + persistent code, + \item \PValue{heading/begingroup/}\PName{name} with an empty argument for + single-use code. + \end{enumerate} + The \PName{name} is the name of section level specified in + \DescRef{maincls-experts.cmd.DeclareSectionCommand}, + \DescRef{maincls-experts.cmd.DeclareNewSectionCommand} or + \DescRef{maincls-experts.cmd.ProvideSectionCommand}, or the sectioning + command specified by it, for example \PValue{chapter} or + \PValue{subparagraph}. Looking at the list above, and considering that there + are various sectioning commands, it becomes clear that the \PValue{heading} + and \PValue{heading/begingroup} hooks will be called multiple times for each + sectioning command.% +\end{Example}% % \EndIndexGroup +\begin{Declaration} + \Macro{AddtoDoHook}\Parameter{name}\Parameter{command} + \Macro{AddtoOneTimeDoHook}\Parameter{name}\Parameter{command} +\end{Declaration} +\Macro{AddtoDoHook}\ChangedAt[2019/01]{v3.27}{\Package{scrbase}} appends +persistent code to the hook named \PName{name}. The code to be added is the +\PName{command}, to which the argument mentioned in the description of +\DescRef{\LabelBase.cmd.ExecuteDoHook} is appended as a parameter. +\begin{Example} + Suppose you want to count how many times the \Macro{section} command is + executed. This would be simple, continuing the previous example: +\begin{lstcode} + \newcounter{sectionCounter} + \AddtoDoHook{heading/begingroup/section} + {\stepcounter{sectionCounter}} +\end{lstcode} + However, in reality, \Macro{stepcounter}\PParameter{sectionCounter}% + \PParameter{} would be executed. Remember that an argument is always appended + as a parameter. In the case of the hook named + \PValue{heading/begingroup/section}, this argument is empty. Since an empty + parameter becomes an empty group here, it is better to consume this empty + parameter: +\begin{lstcode} + \newcommand*{\stepcountergobble}[2]{% + \stepcounter{#1}% + } + \AddtoDoHook{heading/begingroup/section} + {\stepcountergobble{sectionCounter}} +\end{lstcode} + Here, the appended, empty parameter of \Macro{stepcountergobble} is read but + not used. + + If instead of \Macro{section}, you want to count all sectioning commands, you + only need to change the hook name: +\begin{lstcode} + \AddtoDoHook{heading/begingroup} + {\stepcountergobble{sectionCounter}} +\end{lstcode} + By the way, the appended parameter is not empty in this case but contains the + name of the sectioning level or sectioning command. If you wanted to count + the sectioning commands individually, you could just use this: +\begin{lstcode} + \newcommand*{\stepCounter}[1]{% + \stepcounter{#1Counter}% + } + \AddtoDoHook{heading/begingroup} + {\stepCounter} +\end{lstcode} + Of course, you must also define the counters \Counter{partCounter}, + \Counter{chapterCounter} down to \Counter{subparagraphCounter}. +\end{Example} + +The \Macro{AddtoOneTimeDoHook} command works similarly but adds the +\PName{command} to the single-use code. This code will be globally removed +after the first execution.% +\EndIndexGroup + +\begin{Declaration} + \Macro{ForDoHook}\Parameter{specification}\Parameter{command} +\end{Declaration} +While\ChangedAt[2019/01]{v3.27}{\Package{scrbase}} +\DescRef{\LabelBase.cmd.ExecuteDoHook} executes the commands previously stored +with \DescRef{\LabelBase.cmd.AddtoDoHook} or +\DescRef{\LabelBase.cmd.AddtoOneTimeDoHook} for the hook given by the +\PName{specifier}, this macro executes the \PName{command} immediately. There +are two parameters added to the \PName{command}. The first is the hook's name; +the second, the hook's argument. + +This command is a byproduct of the implementation of +\DescRef{\LabelBase.cmd.ExecuteDoHook}. Normally, neither end users nor package +authors should need this command.% +\EndIndexGroup + +\begin{Declaration} + \Macro{SplitDoHook}\Parameter{specifier}\Parameter{head macro} + \Parameter{remainder macro} +\end{Declaration} +As\ChangedAt[2019/01]{v3.27}{\Package{scrbase}} can be seen from the preceding +explanations, the parameter of a \PName{command} added with +\DescRef{\LabelBase.cmd.AddtoDoHook} or +\DescRef{\LabelBase.cmd.AddtoOneTimeDoHook} can also be a multi-part +\PName{specifier}. You can use \Macro{SplitDoHook} to divide a +\PName{specifier} into the front element and the remainder. The +\PName{head macro} will be set to the front element. The \PName{remainder +macro} will be set to the rest. If there is no remainder left, the +\PName{remainder macro} is set to empty. If the \PName{specifier} was already +empty, a warning is issued and both the \PName{head macro} and the +\PName{remainder macro} are set to empty. + +\begin{Example} + If you want to increase a counter at the start of a group in which a heading + is issued but decrease it at the end, you can do this with two hooks: +\begin{lstcode} + \AddtoDoHook{heading/begingroup} + {\stepCounter} + \newcommand*{\restepCounter}[1]{% + \addtocounter{#1Counter}{-1}% + } + \AddtoDoHook{heading/endgroup} + {\restepCounter} +\end{lstcode} + But you could also use a single hook and split its parameters: +\begin{lstcode} + \newcommand*{\changeCounter}[1]{% + \SplitDoHook{#1}{\Group}{\Level}% + \ifstr{\Group}{begingroup}{% + \stepcounter{\Level Counter}% + }{% + \ifstr{\Group}{endgroup}{% + \addtocounter{\Level Counter}{-1}% + }{}% + }% + } + \AddtoDoHook{heading} + {\changeCounter} +\end{lstcode} + As you can see, the first solution is much simpler. In addition, it would + be easy to overlook including the empty group for the second false-case in + the second example. That would be fatal, however, as there make be other + hooks with named \PValue{heading} but with different arguments. +\end{Example} + +Strictly speaking, this command is a byproduct of the implementation of +\DescRef{\LabelBase.cmd.ForDoHook}.% +\EndIndexGroup +% +\EndIndexGroup +\EndIndexGroup + \endinput %%% Local Variables: |