diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle-experts.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle-experts.tex | 1568 |
1 files changed, 824 insertions, 744 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle-experts.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle-experts.tex index 5eba7be2753..c01bbdada5d 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle-experts.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle-experts.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrbookreportarticle-experts.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrbookreportarticle-experts.tex -% Copyright (c) Markus Kohm, 2001-2017 +% Copyright (c) Markus Kohm, 2001-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -48,13 +48,13 @@ % ============================================================================ \KOMAProvidesFile{scrbookreportarticle-experts.tex} - [$Date: 2017-05-12 13:41:47 +0200 (Fri, 12 May 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (chapter: scrbook, scrreprt, scrartcl for experts)] -\translator{Gernot Hassenpflug\and Markus Kohm} +\translator{Gernot Hassenpflug\and Markus Kohm\and Karl Hagen} -% Date of the translated German file: 2017-05-08 +% Date of the translated German file: 2018-02-13 \chapter[{Additional Information about the Main Classes and \Package{scrextend}}]{Additional Information about the Main Classes @@ -67,29 +67,29 @@ \BeginIndex{Class}{scrbook}% \BeginIndex{Class}{scrreprt}% \BeginIndex{Package}{scrextend}% - -This chapter gives additional information about the \KOMAScript{} classes -\Class{scrbook}, \Class{scrreprt}, and \Class{scrartcl}. Some of the features -are also available for package \Package{scrextend}. \iffree{Some parts of the - chapter are subject to the \KOMAScript{} book \cite{book:komascript} - only. This should not be a problem, because the}{The} average user, who only -want to use the package, will not need the information, that is addressed to -users with non-standard requirements or who want to write their own classes -using a \KOMAScript{} class. Another part of the information describes features -of the classes that exist only because of compatibility to former -releases of \KOMAScript{} or the standard classes. The features, that exist -only because of compatibility to former \KOMAScript{} releases, are printed -with a sans serif font. You should not use them any longer. +This chapter provides additional information about the \KOMAScript{} classes +\Class{scrbook}, \Class{scrreprt}, and \Class{scrartcl} and some commands that +are also available in \Package{scrextend}. \iffree{Some parts of the chapter + are found only in the German \KOMAScript{} book \cite{book:komascript}. This + should not be a problem because the}{The} average user, who only wants to +use the classes, will seldom need this information. Some of this information +is addressed to users with non-standard requirements or who want to write +their own classes based on a \KOMAScript{} class. Other parts describe +features that exist only for the sake of compatibility with the standard +classes or earlier versions of \KOMAScript{}. Portions that describe features +that exist only for reasons of compatibility with earlier versions of +\KOMAScript{} are printed in sans serif font. You should not use them any +longer. \LoadNonFree{scrbookreportarticle-experts}{0} -\section{Additional Information to User Commands} +\section{Extensions to User Commands} \seclabel{addInfos} \LoadNonFree{scrbookreportarticle-experts}{1} -\section{Cooperation and Coexistence of \KOMAScript{} and Other Packages} +\section{\KOMAScript's Interaction with Other Packages} \seclabel{coexistence} \LoadNonFree{scrbookreportarticle-experts}{2} @@ -98,9 +98,9 @@ with a sans serif font. You should not use them any longer. \section{Expert Commands} \seclabel{experts} -This sections described commands, that are more or less out of average user's -interest. Nevertheless these commands provide additional features for -experts. Because the information is addressed to experts it's condensed. +This sections describes commands that are of little or no interest to the +average user. These commands offer additional features for experts. Because +the information is addressed to experts, it is condensed. % \subsection{Identification} % \seclabel{identification} @@ -109,17 +109,16 @@ experts. Because the information is addressed to experts it's condensed. \Macro{KOMAClassName}% \Macro{ClassName} \end{Declaration} -\Macro{KOMAClassName} stores the name of the currently used \KOMAScript{} -class. If someone wants to know, whether or not or a \KOMAScript{} class is -used or which \KOMAScript{} is used this may be tested with this command. In -difference to this, \Macro{ClassName} tells which would be the standard class, -that has been replaced by a \KOMAScript{} class. - -Please note\textnote{Attention!}, that the existence of -\DescRef{scrbase.cmd.KOMAScript}\IndexCmd{KOMAScript} is not a indication for -the usage of a \KOMAScript{} class. First of all: Every \KOMAScript{} package -and not only \KOMAScript{} classes define \Macro{KOMAScript}. Furthermore -other packages may also define the \KOMAScript{} word mark with this name.% +\Macro{KOMAClassName} stores the name of the \KOMAScript{} class currently in +use. So if you want to know if a \KOMAScript{} class is used, you can easily +test for this command. In contrast, \Macro{ClassName} indicates which standard +class has been replaced by this \KOMAScript{} class. + +Note\textnote{Attention!} in this context, however, that the existence of +\DescRef{scrbase.cmd.KOMAScript}\IndexCmd{KOMAScript} cannot guarantee that a +\KOMAScript{} class is in use. For one thing, all \KOMAScript{} packages +define this command. For another, other packages may find it useful to define +the \KOMAScript{} label using this name.% % \EndIndexGroup @@ -133,27 +132,26 @@ other packages may also define the \KOMAScript{} word mark with this name.% The\ChangedAt{v3.08}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} \KOMAScript{} classes do not use \Macro{addcontentsline}\IndexCmd{addcontentsline}% -\important{\Macro{addcontentsline}} directly. Instead they -call \Macro{addtocentrydefault} with similar arguments. The command may be used -for both, entries with and without number. Thereby \PName{level} is the -textual sectioning level, i.\,e., \PValue{part}, +\important{\Macro{addcontentsline}} directly to make entries in the table of +contents. Instead, they call \Macro{addtocentrydefault} with similar +arguments. The command can be used for both numbered and unnumbered entries. +The \PName{level} is the sectioning level, that is \PValue{part}, \PValue{chapter}, \PValue{section}, \PValue{subsection}, \PValue{subsubsection}, \PValue{paragraph}, or \PValue{subparagraph}. The -already formatted sectioning number is given by the second argument, -\PName{number}. This argument may be empty. The text of the entry is given by -argument \PName{heading}. It is recommended to protect fragile commands inside -this argument with prefix +formatted sectioning number is given the second argument, \PName{number}. This +argument can be empty. The text of the entry is given by the \PName{heading} +argument. You should protect fragile commands inside this argument with \Macro{protect}\IndexCmd{protect}\important{\Macro{protect}}. -There's one speciality for argument \PName{number}. An empty argument -signalizes, that an entry without number should be generated. \KOMAScript{} -uses +One notable feature of the \PName{number} argument is that an empty argument +indicates that an unnumbered entry should be generated. By default, +\KOMAScript{} uses \begin{quote} \Macro{addcontentsline}\PParameter{toc}\Parameter{level}% \Parameter{heading} \end{quote} -for this. Nevertheless, if the argument is not empty an entry with number -will be made and \PName{number} is the already formatted heading +for this. If the argument is not empty, however, an entry with number +will be created and \PName{number} is the formatted heading number. \KOMAScript{} uses \begin{quote}\raggedright \Macro{addcontentsline}\PParameter{toc}\Parameter{level}% @@ -162,10 +160,10 @@ number. \KOMAScript{} uses \PName{heading}\%\\ } \end{quote} -to make this. +to create this entry. -Package authors an authors of wrapper classes may redefined this command to -manipulate the entries. For example\textnote{Example} one could suggest +Package authors and authors of wrapper classes can redefine this command to +alter the entries. For example\textnote{Example}, you could use \begin{lstcode} \renewcommand{\addtocentrydefault}[3]{% \ifstr{#3}{}{% @@ -177,22 +175,22 @@ manipulate the entries. For example\textnote{Example} one could suggest }% }% \end{lstcode} -to omit entries with empty \PName{heading}. In real live this would not be -needed, because the \KOMAScript{} classes already use another method to -suppress empty entries. See the description of the structuring commands in -\autoref{sec:maincls.structure} from \DescPageRef{maincls.cmd.part} -onward for this.% +to\IndexCmd{ifstr} omit entries with an empty \PName{heading}. In practice, +such a change is not necessary because the \KOMAScript{} classes already use +another method to suppress empty entries. See the description of the +sectioning commands in \autoref{sec:maincls.structure}, starting on +\DescPageRef{maincls.cmd.part} for this.% % \EndIndexGroup \begin{Declaration} - \Macro{addparttocentry}\Parameter{number}\Parameter{heading}% - \Macro{addchaptertocentry}\Parameter{number}\Parameter{heading}% - \Macro{addsectiontocentry}\Parameter{number}\Parameter{heading}% - \Macro{addsubsectiontocentry}\Parameter{number}\Parameter{heading}% - \Macro{addsubsubsectiontocentry}\Parameter{number}\Parameter{heading}% - \Macro{addparagraphtocentry}\Parameter{number}\Parameter{heading}% + \Macro{addparttocentry}\Parameter{number}\Parameter{heading} + \Macro{addchaptertocentry}\Parameter{number}\Parameter{heading} + \Macro{addsectiontocentry}\Parameter{number}\Parameter{heading} + \Macro{addsubsectiontocentry}\Parameter{number}\Parameter{heading} + \Macro{addsubsubsectiontocentry}\Parameter{number}\Parameter{heading} + \Macro{addparagraphtocentry}\Parameter{number}\Parameter{heading} \Macro{addsubparagraphtocentry}\Parameter{number}\Parameter{heading} \end{Declaration}% The\ChangedAt{v3.08}{\Class{scrbook}\and \Class{scrreprt}\and @@ -201,10 +199,9 @@ command \DescRef{\LabelBase.cmd.addtocentrydefault}\IndexCmd{addtocentrydefault}% \important{\DescRef{\LabelBase.cmd.addtocentrydefault}} directly only if no individual command for the \PName{level} has been defined or if that command -is \Macro{relax}\IndexCmd{relax}\important{\Macro{relax}}. Nevertheless, the -default definition of all these individual commands simply call -\DescRef{\LabelBase.cmd.addtocentrydefault} with their own \PName{level} -passing their arguments through.% +is \Macro{relax}\IndexCmd{relax}\important{\Macro{relax}}. By default, all +these commands simply pass their own \PName{level} and arguments directly to +\DescRef{\LabelBase.cmd.addtocentrydefault}.% % \EndIndexGroup @@ -212,29 +209,33 @@ passing their arguments through.% \begin{Declaration} \Macro{raggedchapterentry} \end{Declaration} -Previous\ChangedAt{v3.21}{\Class{scrbook}\and \Class{scrreprt}} versions of -\KOMAScript{} provide a feature for printing chapter entries at the table of -contents left-aligned instead of justified by defining command -\Macro{raggedchapterentry} to be \Macro{raggedright}. Officially this feature -has been removed from \KOMAScript{} version 3.21 on. - -Indeed attribute \PValue{raggedentrytext} of toc-entry style \PValue{tocline} -of package \Package{tocbasic}\IndexPackage{tocbasic} has been implemented to -use such a macro \Macro{ragged\PName{entry level}entry} as an indicator for -left-aligned text. If such a macro is \Macro{raggedright}, the text is printed -left-aligned. With any other definition the text is printed justified. - -With this implementation of \PValue{raggedentrytext} full compatibility to the -previous documentation of \Macro{raggedchapterentry} is reached. As -stated formerly, other definitions of \Macro{raggedchapterentry}\,---\,and now -also of \Macro{raggedsectionentry} and similar macros for other entry -levels\,---\,could result in the potentially unexpected effect of justified -text. - -Nevertheless, it is recommended to use the attribute of style \PValue{tocline} -to select justified or left-aligned text.% +In\ChangedAt{v3.21}{\Class{scrbook}\and \Class{scrreprt}} earlier versions of +\KOMAScript{}, it was possible to define the \Macro{raggedchapterentry} macro +as \Macro{raggedright} to print chapter entries in the table of contents +left-aligned instead of fully justified. Officially, this feature has not +existed in \KOMAScript{} since version~3.21. + +In fact, the \PValue{raggedentrytext} attribute for the \PValue{tocline} +TOC-entry style of the \Package{tocbasic}\IndexPackage{tocbasic} package is +implemented by setting the \Macro{ragged\PName{entry level}entry} macro to +either \Macro{relax} or \Macro{raggedright}. This attribute is evaluated by +checking whether the corresponding macro is defined as \Macro{raggedright}. If +so, the text is printed left-aligned. With any other definition, no ragged +margins are used. + +Since it was previously documented that \Macro{raggedchapterentry} should not +be defined as anything other than \Macro{raggedright}, this behaviour is +compatible with the documented behaviour of earlier versions. As noted in +earlier releases, other definitions of \Macro{raggedchapterentry}\,---\,and +now also of \Macro{raggedsectionentry} and similar macros for other entry +levels\,---\,may lead to unexpected results. + +You should select the desired justification for the all table-of-contents +entries using the \PValue{raggedentrytext} attribute of \PValue{tocline} +rather than attempting to set the attribute for specific entry levels.% \EndIndexGroup + % \subsection{Font Settings} % \seclabel{fonts} @@ -243,53 +244,53 @@ to select justified or left-aligned text.% \Macro{@fontsizefilebase}% \Macro{changefontsizes}\Parameter{font size} \end{Declaration} -The prefix \File{scrsize} for file names of font size files, that has been -mentioned\iffree{ in \autoref{sec:maincls-experts.addInfos}}{} at -\DescPageRef{maincls-experts.option.fontsize} is only the default of the -internal macro \Macro{@fontsizefilebase}\IndexCmd{@fontsizefilebase}. This -default is used only, if the macro has not already be defined when loading a -\KOMAScript{} class or package \Package{scrextend}. Authors of wrapper classes -may define this macro with another file name prefix to use completely -different font size files. Also\textnote{Hint!} authors of wrapper classes -could change or deactivate the \emph{fallback} solution for unknown font sizes -by redefinition of macro -\Macro{changefontsizes}\important{\Macro{changefontsizes}}. This macro has -exactly one argument: the wanted \PName{font size}.% -% +The \File{scrsize} prefix for file names of font-size files described +in \autoref{sec:maincls-experts.addInfos}\iffree{}{ on +\DescPageRef{maincls-experts.option.fontsize}} is just the default for the +internal \Macro{@fontsizefilebase}\IndexCmd{@fontsizefilebase} macro. This +default is used only when the macro is not yet defined when loading a +\KOMAScript{} class or the \Package{scrextend} package. Authors of wrapper +classes can redefine this macro to use completely different font-size files. +Similarly\textnote{Hint!} authors of wrapper classes can change or deactivate +the fallback solution for unknown font sizes by redefining the +\Macro{changefontsizes}\important{\Macro{changefontsizes}} macro. This macro +has exactly one argument: the desired \PName{font size}. +However\textnote{Attention!}, the \Macro{changefontsizes} macro is not +designed as an end-user instruction.% \EndIndexGroup \begin{Declaration} - \Macro{newkomafont}\OParameter{warning message}\Parameter{element}% + \Macro{newkomafont}\OParameter{warning}\Parameter{element}% \Parameter{default}% - \Macro{aliaskomafont}\Parameter{alias name}\Parameter{element} + \Macro{aliaskomafont}\Parameter{alias}\Parameter{element} \end{Declaration} -Experts may use \Macro{newkomafont} to define a \PName{default} for the font -style of an \PName{element}. After this that default may be changed using -commands \DescRef{maincls.cmd.setkomafont} and -\DescRef{maincls.cmd.addtokomafont} (see \autoref{sec:maincls.textmarkup}, -\DescPageRef{maincls.cmd.setkomafont}). Of course this is not enough to use -the defined font style. The expert himself has to prepare his code to use -command \DescRef{maincls.cmd.usekomafont}% -\important{\DescRef{maincls.cmd.usekomafont}}\IndexCmd{usekomafont} (see -\DescPageRef{maincls.cmd.usekomafont}) with that \PName{element} at his code -definitions. - -The optional argument \PName{warning message} defines a warning message, -that \KOMAScript{} will show whenever the default font style of that -\PName{element} will be changed. The sender of the warning in such cases will -be the used \KOMAScript{} class or package \Package{scrextend}. - -Command \Macro{aliaskomafont} defines an \PName{alias name} to an already -defined \PName{element}. \KOMAScript{} will inform the user automatically -about the real name of the element, whenever an \PName{alias name} will be -used. An\textnote{Hint!} \PName{alias name} may be used, e.\,g., if a -developer finds a better name for an element, that has been defined formerly -with another name, if the old name should still be usable because of -compatibility. Also an \PName{alias name}s may increase usability, because -different users may find different names more or less intuitive. \KOMAScript{} -itself defines a lot of \PName{alias name}s for several \PName{element}s. -% +Experts can use \Macro{newkomafont} to define a \PName{default} for the font +style of an \PName{element}. Subsequently, that default can be changed with +the \DescRef{maincls.cmd.setkomafont} and \DescRef{maincls.cmd.addtokomafont} +commands (see \autoref{sec:maincls.textmarkup}, +\DescPageRef{maincls.cmd.setkomafont}). Of course, merely defining the font +style does not actually put it to use. You must make sure you include the +\DescRef{maincls.cmd.usekomafont}% +\important{\DescRef{maincls.cmd.usekomafont}}\IndexCmd{usekomafont} command +(see \DescPageRef{maincls.cmd.usekomafont}) for this \PName{element} in your +code at the appropriate places. Calling \Macro{newkomafont} for an existing +element will result in error messages. + +The optional \PName{warning} argument defines a warning message. The +\KOMAScript{} classes output it with \Macro{ClassWarning}, and the +\Package{scrextend} package with \Macro{PackageWarning}, whenever the default +font style of that \PName{element} is changed. The package \Package{scrkbase} +is listed as the generator of the warning. + +The \Macro{aliaskomafont} command defines an \PName{alias} for a previously +defined \PName{element}. \KOMAScript{} informs the user in the \File{log} file +about the actual name of the element if it uses an \PName{alias}. +You\textnote{Hint!} can use an \PName{alias}, for example, if you think of a +better name for an element and the old name should remain usable for the sake +of compatibility. It can also increase user-friendliness by creating aliases +for all the terms that different users may intuitively choose. \KOMAScript{} +itself makes use of this possibility.% \EndIndexGroup @@ -299,21 +300,21 @@ itself defines a lot of \PName{alias name}s for several \PName{element}s. \Macro{addtokomafontgobblelist}\Parameter{macro} \end{Declaration} As already mentioned in \autoref{part:forAuthors} of this manual, font -settings of elements should consist only in commands to select the size, -family, coding, series, shape, or colour. At least changing the colour is not -always transparent in \LaTeX{} and therefore could result in unwanted effects -if someone uses \DescRef{maincls.cmd.usekomafont} at an inappropriate state. - -Users tend to use different, somehow critical things in the font setting of an -element, e.\,g., \Macro{MakeUppercase} at the very end of the setting. As long -as possible, the internal usage of font settings has been implemented so that -such forbidden settings do not matter. Even using a command that expects an -argument, e.\,g., \Macro{textbf} instead of \Macro{bfseries}, would work -mostly, if it the last one in the font setting of an element\,---\,but without -warranty. - -Inside \KOMAScript, sometimes, it was necessary to restrict the font change to -real font settings. This has been done, e.\,g., using +settings of elements should consist only of commands to select the size, +family, encoding, series, shape, or colour. Colour changes are not +always transparent in \LaTeX{} and therefore can cause in unwanted side-effects +if you use \DescRef{maincls.cmd.usekomafont} at an inappropriate place. + +Users tend to put very different, sometimes critical, things into the font +setting of an element, such as \Macro{MakeUppercase} at the very end of the +setting. As much as possible, the internal use of the font settings has been +implemented so that many of these prohibited elements still do no harm, and it +usually works even if the last command in a font setting expects an argument, +for example using \Macro{textbf} instead of \Macro{bfseries}. But there is no +guarantee for that. + +Internally, \KOMAScript{} must sometimes limit font changes to real font +settings. This is accomplished, for example, by using \DescRef{maincls.cmd.usefontofkomafont}% \IndexCmd{usefontofkomafont}% \IndexCmd{usesizeofkomafont}\IndexCmd{useencodingofkomafont}% @@ -322,102 +323,108 @@ real font settings. This has been done, e.\,g., using (see \autoref{sec:maincls.textmarkup}, \DescPageRef{maincls.cmd.usefontofkomafont}). -Nevertheless, command \DescRef{maincls.cmd.usefontofkomafont} and it's -siblings have some limitations. Therefore you must not use a command that +Nevertheless, the \DescRef{maincls.cmd.usefontofkomafont} command and its +siblings have their limitations. Therefore you must not use a command that always needs a fully expandable argument inside the font setting of an -element. But this is exactly what \Macro{MakeUppercase} -needs. Therefore\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} \KOMAScript{} holds a list of macros, which should become -\Macro{relax} inside \DescRef{maincls.cmd.usefontofkomafont} and it's -siblings. Since \KOMAScript~3.24\ChangedAt{v3.24}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} only \Macro{normalcolor} is added to +element. But this is exactly what \Macro{MakeUppercase} needs. +Therefore\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and +\Class{scrartcl}} \KOMAScript{} maintains an internal list of macros that +should become \Macro{relax} inside \DescRef{maincls.cmd.usefontofkomafont} and +its siblings. Since \KOMAScript~3.24\ChangedAt{v3.24}{\Class{scrbook}\and +\Class{scrreprt}\and \Class{scrartcl}} only \Macro{normalcolor} is added to this list by default. -Amongst others, \Macro{normalcolor}, \Macro{MakeUppercase}, and -\Macro{MakeLowercase} are part of that list. More macros can be added one by -one using \Macro{addtokomafontrelaxlist}. - -Note that \PName{macro} will be set simply to \Macro{relax}. So if -\PName{macro} really has an argument, the argument will be execute -locally. Therefore you must not add commands like \Macro{setlength} to the -list. The user himself is responsible for all errors resulting in the usage of -\Macro{addtokomafontrelaxlist}. Additionally this command should not be -misunderstood as a legitimation for adding all kind of commands to the font -setting of an element! +Note that the given \PName{macro} is actually just set to \Macro{relax}. So +any arguments within the font setting will be executed locally, if applicable. +Therefore you should never add commands like \Macro{setlength} to the list. +You are responsible for all errors resulting caused by using +\Macro{addtokomafontrelaxlist}. Also, do not take this command as license to +add all sorts of commands to the font settings! For\ChangedAt{v3.24}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} some commands you may prefere to execute the first -argument unchanged. These commands can be added to another list using -\Macro{addtokomatfontonearglist}. By default \Macro{MakeUppercase} and +\Class{scrartcl}} commands whose first argument should be executed without an +additional group, there is \Macro{addtokomatfontonearglist}. The specified +macro is set to \Macro{@firstofone}. By default \Macro{MakeUppercase} and \Macro{MakeLowercase} are added to this list. -If\ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -a \PName{macro} and it's first argument should be ignored locally inside -\DescRef{maincls.cmd.usefontofkomafont} and it's siblings, you can use -\Macro{addtokomafontgobblelist} instead of \Macro{addtokomafontrelaxlist}. An -example for this is the command \Macro{color}, that has to be ignored with the -colour name and therefore is a default member of the gobble-list. - -Note, the defaults of the three lists can change. If you need a command inside -one of the lists you should add it yourself.% +If\ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}\and +\Class{scrartcl}}, on the other hand, a \PName{macro} and its first argument +should be ignored locally inside \DescRef{maincls.cmd.usefontofkomafont} and +its siblings, you can use \Macro{addtokomafontgobblelist} instead of +\Macro{addtokomafontrelaxlist}. An example of this is the command +\Macro{color}, which must be ignored along with the colour name and therefore +is a member of this list by default. + +Note the defaults of these three lists may change in future version. If you +need a certain commands in one of the lists, you should should explicitly add +them yourself.% \EndIndexGroup \begin{Declaration} \Macro{IfExistskomafont}\Parameter{element}\Parameter{then code}% - \Parameter{else code} + \Parameter{else code} + \Macro{IfIsAliaskomafont}\Parameter{element}\Parameter{then code}% + \Parameter{else code} \end{Declaration} Which\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}\and \Class{scrlttr2}} elements are defined depends on the -version of \KOMAScript. So sometimes it may be useful to be able to test, -whether or not an \PName{element} exists. The command executes the \PName{then - code} only if an \PName{element} has been defined using -\DescRef{\LabelBase.cmd.newkomafont} or \DescRef{\LabelBase.cmd.aliaskomafont} -and therefore can be changed using \DescRef{maincls.cmd.setkomafont} or -\DescRef{maincls.cmd.addtokomafont} and can be used by one of the -\Macro{use\dots komafont} commands. Otherwise it executes the \PName{else - code}.% +version of \KOMAScript. So it sometimes makes sense to test in advance whether +a specific \PName{element} even exists. The \Macro{IfExistskomafont} command +executes the \PName{then code} if and only if an \PName{element} has been +defined using \DescRef{\LabelBase.cmd.newkomafont} or +\DescRef{\LabelBase.cmd.aliaskomafont} and therefore can also be changed using +\DescRef{maincls.cmd.setkomafont} or \DescRef{maincls.cmd.addtokomafont} and +can be used by one of the \Macro{use\dots komafont} commands. Otherwise it +executes the \PName{else code}.% + +In contrast, \Macro{IfIsAliaskomafont}\ChangedAt{v3.25}{\Class{scrbook}\and +\Class{scrreprt}\and \Class{scrartcl}\and \Class{scrlttr2}} executes +\PName{then code} only if \PName{element} has been defined with +\DescRef{\LabelBase.cmd.aliaskomafont} as an alias of another element. For +undefined elements as well as for elements defined with +\DescRef{\LabelBase.cmd.newkomafont}, however, it executes the +\PName{else code}.% \EndIndexGroup % \subsubsection{Paragraph Indention or Gap} % \seclabel{parskip} \begin{Declaration} - \Macro{setparsizes}\Parameter{indent}\Parameter{distance}%^^A - \Parameter{last line end space} + \Macro{setparsizes}\Parameter{indent}\Parameter{distance} + \Parameter{last-line end space} \end{Declaration} -With this command \KOMAScript{} provides to set the indent of the first line -of a new paragraph, the distance between paragraphs and the white space that -has to be at the end of the last line of each paragraph. This command should -be used whenever changes should also be recognized by option -\OptionValueRef{maincls}{parskip}{relative}. \KOMAScript{}\textnote{Beispiel} -itself uses this command, e.\,g., with +\KOMAScript{} provides the option to set the indent of the first line of a new +paragraph, the distance between paragraphs, and the white space required at the +end of the last line of each paragraph. You should use this command whenever +the \OptionValueRef{maincls}{parskip}{relative} option should recognize these +changes. \KOMAScript{}\textnote{example} itself uses this command, for +example, in the form \begin{lstcode} \setparsizes{0pt}{0pt}{0pt plus 1fil} \end{lstcode} -to switch of paragraph indent and distance between paragraphs and to allow any -white space at the end of the last line of paragraphs. This make sense, if a -paragraph consists of a box only, that should be printed without vertical -distance but with the whole column width. If, in opposite to that, the box -should only span the whole width but should be printed with the current -settings of paragraph indent and distance between paragraphs, usage of +to eliminate both the paragraph indentation and inter-paragraph spacing, as +well as to allow any amount of white space at the end of the last line of the +paragraph. Such values are useful if a paragraph consists of only a box that +should be printed without vertical spacing and filling the whole column +width. If, on the other hand, the box should only span the whole width but use +the current settings for indentation and distance between paragraphs, then \begin{lstcode} \setlength{\parfillskip}{0pt plus 1fil} \end{lstcode} -would be recommended. - -Since \KOMAScript~3.17\ChangedAt{v3.17}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} changing or -reactivation\IndexCmd{activateareas} of the typing area or the margins (see -\autoref{cha:typearea}) will also reactivate the values of \Macro{setparsizes} -if they have not been changed since the last usage of this command. This is -one more reason not to change these values without using \KOMAScript. With -compatibility to a \KOMAScript{} version prior to 3.17 (see +is preferable. + +Starting with \KOMAScript~3.17\ChangedAt{v3.17}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}, recalculating or +reactivating\IndexCmd{activateareas} the type area or the margins (see +\autoref{cha:typearea}) also readjusts the values of \Macro{setparsizes} if +they have not been changed in the meantime. This is one more reason not to +change these values without using \KOMAScript. Setting compatibility to a +\KOMAScript{} version prior to 3.17 (see \autoref{sec:maincls.compatibilityOptions}, -\DescPageRef{maincls.option.version}, option -\DescRef{maincls.option.version}% +\DescPageRef{maincls.option.version}, option \DescRef{maincls.option.version}% \IndexOption{version}\important{\OptionValueRef{maincls}{version}{3.17}}) -this reactivation of the \Macro{setparsizes} values is deactivated.% +disables this recalculation.% % \EndIndexGroup @@ -436,70 +443,74 @@ this reactivation of the \Macro{setparsizes} values is deactivated.% \Macro{ProvideSectionCommand}\OParameter{attributes}\Parameter{name} \end{Declaration} With\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} these commands you can either define a new section-like -command \Macro{\PName{name}} or change an already defined sectioning command -\Macro{\PName{name}}. To do so you use the optional argument to setup several + \Class{scrartcl}} these commands you can either define a new sectioning +command, \Macro{\PName{name}}, or modify an existing sectioning command, +\Macro{\PName{name}}. To do so, you use the optional argument to set several \PName{attributes}. The \PName{attributes} are a comma-separated list of -\PName{key}=\PName{value} assignments. Beside the style-independent attributes -shown in \autoref{tab:maincls-experts.declaresection.keys}, there are style -dependent attributes, too. Currently the following styles are provided: -\begin{labeling}{\PValue{chapter}:} +\PName{key}=\PName{value} assignments. In addition to the style-independent +attributes shown in\autoref{tab:maincls-experts.declaresection.keys}, +\autopageref{tab:maincls-experts.declaresection.keys}, there are also +attributes that depend on the style. Currently the following styles are +available: +\begin{description}\setkomafont{descriptionlabel}{} \item[\PValue{chapter}:] \ChangedAt{v3.18}{\Class{scrbook}\and - \Class{scrreprt}}Style of chapter headings. This style is currently used - for \DescRef{maincls.cmd.chapter}\IndexCmd{chapter} and indirectly for - \DescRef{maincls.cmd.addchap}\IndexCmd{addchap}. You can define new - section-like commands using this style. To define new or to reconfigure - existing commands you can also use the additional attributes of + \Class{scrreprt}}The style for chapter headings. This style is used by + default for \DescRef{maincls.cmd.chapter}\IndexCmd{chapter} and indirectly + for \DescRef{maincls.cmd.addchap}\IndexCmd{addchap}. You can define new + sectioning commands using this style, but then they do not automatically + have an \Macro{add\dots} variant. To configure existing or new sectioning + commands, you can also use the attributes of \autoref{tab:maincls-experts.declarechapterstyle.keys}, \autopageref{tab:maincls-experts.declarechapterstyle.keys}. - Note\textnote{Attention!} that command \DescRef{maincls.cmd.addchap} and the - star variants are configured automatically together with - \DescRef{maincls.cmd.chapter} and should not be changed independently. Note + Note\textnote{Attention!} that the \DescRef{maincls.cmd.addchap} command, + like the starred variants, is configured automatically with + \DescRef{maincls.cmd.chapter} and cannot be modified independently. Note that \Class{scrartcl}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} does not provide this style. \item[\PValue{part}:] \ChangedAt{v3.18}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}}Style part headings. This style is - currently used for \DescRef{maincls.cmd.part}\IndexCmd{part} and indirectly - for \DescRef{maincls.cmd.addpart}\IndexCmd{addpart}. You can define new - section-like commands using this style. To define new or to reconfigure - existing commands you can also use the additional attributes of + \Class{scrreprt}\and \Class{scrartcl}}The style for part headings. This + style is used by default for \DescRef{maincls.cmd.part}\IndexCmd{part} and + indirectly for \DescRef{maincls.cmd.addpart}\IndexCmd{addpart}. You can + define new sectioning commands using this style, but then they do not + automatically have an \Macro{add\dots} variant. To configure existing or new + sectioning commands, you can also use the attributes of \autoref{tab:maincls-experts.declarepartstyle.keys}, \autopageref{tab:maincls-experts.declarepartstyle.keys}. - Note\textnote{Attention!} that command \DescRef{maincls.cmd.addpart} and the - star variants are configured automatically together with - \DescRef{maincls.cmd.part} and should not be changed independently. -\item[\PValue{section}:] Style of section headings. This style is currently + Note\textnote{Attention!} that the \DescRef{maincls.cmd.addpart} command, + like the starred variants, is configured automatically with + \DescRef{maincls.cmd.part} and cannot be modified independently. +\item[\PValue{section}:] The style for section headings. This style is currently used for \DescRef{maincls.cmd.section}\IndexCmd{section}, \DescRef{maincls.cmd.subsection}\IndexCmd{subsection}, \DescRef{maincls.cmd.subsubsection}\IndexCmd{subsubsection}, \DescRef{maincls.cmd.paragraph}\IndexCmd{paragraph}, and \DescRef{maincls.cmd.subparagraph}\IndexCmd{subparagraph}. You can define - new section-like commands using this style. To define new or to reconfigure - existing commands you can also use the additional attributes of + new sectioning commands using this style. To configure existing or new + sectioning commands, you can also use the attributes of \autoref{tab:maincls-experts.declaresectionstyle.keys}, - \autopageref{tab:maincls-experts.declaresectionstyle.keys}. Definitions of - new commands need\ChangedAt{v3.24}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} at least the \PName{key}s \PValue{style}, - \PValue{afterskip}, \PValue{beforeskip}, and \PValue{level}. \PValue{font} - and \PValue{indent} are recommended. Need for \PValue{tocindent} and - \PValue{tocnumwidth} depend on the command \PName{name}. This is also true - if a command that was not a section-like command before will be redefined as - a section-like command using - \Macro{RedeclareSectionCommand}. Note\textnote{Attention!} that command - \Macro{addsec} and the star variants are configured automatically together - with \DescRef{maincls.cmd.section} and should not be changed - independently. Defining a new section-like command with this style will also - define an element with the same \PName{name} and the possibility to change - its font using \DescRef{maincls.cmd.setkomafont} or - \DescRef{maincls.cmd.addtokomafont} (see \autoref{sec:maincls.textmarkup}, - \DescPageRef{maincls.cmd.setkomafont}), if such an element does not already - exist. -\end{labeling} - + \autopageref{tab:maincls-experts.declaresectionstyle.keys}. When redefining + a command, you need\ChangedAt{v3.24}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} at least the \PName{key}s + \PValue{style}, \PValue{afterskip}, \PValue{beforeskip}, and \PValue{level}. + \PValue{font} and \PValue{indent} are recommended. \PValue{tocindent} and + \PValue{tocnumwidth} may also be required depending on the command's + \PName{name}. This also applies if a command that was not previously a + sectioning command is redefined as a sectioning command using + \Macro{RedeclareSectionCommand}. Note\textnote{Attention!} that the + \Macro{addsec} command and its starred variants are configured automatically + with \DescRef{maincls.cmd.section} and cannot be changed independently. +\end{description} +Defining a sectioning command also creates an element with the same +\PName{name}, if it does not already exist. For \PValue{chapter} and +\PValue{part}, elements are also created for the prefix line. You can change +its font settings using \DescRef{maincls.cmd.setkomafont} or +\DescRef{maincls.cmd.addtokomafont} (see \autoref{sec:maincls.textmarkup}, +\DescPageRef{maincls.cmd.setkomafont}). + \begin{table} - \caption[{Style-independent attributes at the declaration of section-like - commands}]{Available \PName{key}s and \PName{value}s for the - style-independent \PName{attributes} declaring a section-like command}% + \caption[{Style-independent attributes for declaring sectioning + commands}]{Available \PName{key}s and \PName{value}s for + style-independent \PName{attributes} when declaring sectioning command}% \label{tab:maincls-experts.declaresection.keys}% \begin{tabularx}{\linewidth}{llX} \toprule @@ -508,48 +519,46 @@ dependent attributes, too. Currently the following styles are provided: \PValue{counterwithin} & \PName{counter name} & The value of the counter of the heading should depend on \PName{counter name}. Whenever \Macro{stepcounter} or \Macro{refstepcounter} increases the value of - \PName{counter name}, the value of the counter of this heading should be - set to 0. Also the output of the value of this heading should be prefixed - by \Macro{the\PName{counter name}} - followed by a dot.\\ + \PName{counter name}, the value of the counter of this heading is + reset to 0. In addition, \Macro{the\PName{counter name}} is prefixed + with a dot when this counter is output.\\ \ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartl}}% \PValue{counterwithout} & \PName{counter name} & Cancels a prior \PValue{counterwithin} setting. Therefore it makes sense only if you - re-define an existing - section-like command.\\ - \PValue{expandtopt} & \PName{switch}& If the switch is on, all following - values for lengths will be completely expanded, evaluated and stored as - \texttt{pt} values. If the switch is off, all following values for - lengths will be completely expanded, tentatively evaluated but only - expanded stored. Any values from \autoref{tab:truefalseswitch}, - \autopageref{tab:truefalseswitch} may be used. Default is - \PValue{false}.\\ - \PValue{level} & \PName{integer} & A number, denoting depth of section - (see counter \DescRef{maincls.counter.secnumdepth}, + redefine an existing sectioning command.\\ + \PValue{expandtopt} & \PName{switch}& If the switch is on, all subsequent + values for lengths will be completely expanded, evaluated, and stored as + \texttt{pt} values when they are defined. This means lengths no longer + depend on the current font size. If the switch is off, all subsequent + values for lengths will be tentatively expanded and evaluated but stored + for full evaluation at application time. You can use any values from + \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. The + default is \PValue{false}.\\ + \PValue{level} & \PName{integer} & The numerical value of the sectioning level + (see the \DescRef{maincls.counter.secnumdepth} counter, \autoref{sec:maincls.structure}, \DescPageRef{maincls.counter.secnumdepth}); - the value should be unique.\\ + the value should be unique and is mandatory for new levels.\\ \PValue{style} & \PName{name} & Defines the style of the heading.\\ \ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - \PValue{tocstyle} & \PName{name} & Defines the style of the entries into - the table of contents. You can use every already defined toc-entry style + \PValue{tocstyle} & \PName{name} & Defines the style of the entries in + the table of contents. You can use every previously defined TOC-entry style (see \autoref{sec:tocbasic.tocstyle}). An empty \PName{name} prevents a - new definition of the toc-entry + new definition of the TOC-entry command \Macro{l@\dots}.\\ \ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% \PValue{toc\PName{option}} & \PName{value} & Additional options depending - on the TOC-entry style given by \Option{tocstyle}. See + on the TOC-entry style selected with \Option{tocstyle}. See \autoref{sec:tocbasic.tocstyle}, \autopageref{sec:tocbasic.tocstyle} for - additional information about TOC-entry styles. See + additional information about TOC-entry styles. You can find the attributes + that can be used as \PName{option}s for the predefined TOC-entry styles of + the \Package{tocbasic} package in \autoref{tab:tocbasic.tocstyle.attributes}, - \autopageref{tab:tocbasic.tocstyle.attributes} for information about the - attributes of the predefined TOC-entry styles of package - \Package{tocbasic}, that can be used - as \PName{option}.\\ + \autopageref{tab:tocbasic.tocstyle.attributes}.\\ % \PValue{tocindent} & \PName{length} & Total indentation from the left % margin of the entry in the table of % contents corresponding to this @@ -575,250 +584,205 @@ dependent attributes, too. Currently the following styles are provided: \end{table} \begin{table} - \caption[{Attributes of the style \PValue{section} declaring a section-like - command}]{Additional \PName{keys} and \PName{value}s of attributes - declaring a section-like command with style \PValue{section}}% + \caption[{Attributes of the \PValue{section} style when declaring a + sectioning command}]{Additional \PName{key}s and \PName{value}s for + attributes when declaring a sectioning command with the \PValue{section} + style}% \label{tab:maincls-experts.declaresectionstyle.keys}% \begin{tabularx}{\linewidth}{llX} \toprule \PName{key} & \PName{value} & Description \\ \midrule \PValue{afterskip} & \PName{length} & A negative value activates a run-in - heading. The absolute value is the - skip to leave to right of the run-in - heading. A positive value is the - vertical skip below the heading.\\ - \PValue{beforeskip} & \PName{length}& The absolute value of the vertical - skip before the heading. If the - value is negative, then the - paragraph indent of the text - following the heading is - suppressed.\\ - \PValue{font} & \PName{font commands} & - The initial font setting that - should be used beside - \DescRef{maincls.fontelement.disposition} for the - heading. You can use all settings, - that are allowed for - \DescRef{maincls.cmd.setkomafont} and - \DescRef{maincls.cmd.addtokomafont} for the - element of the heading.\\ - \PValue{indent} & \PName{length} & Indentation of heading from the left - margin.\\ + heading. The absolute value is the horizontal space after the heading. A + positive value is the vertical skip below the heading.\\ + \PValue{beforeskip} & \PName{length} & The amount indicates the vertical + skip before the heading. If the value is negative, a positive distance + is still inserted, but in this case the paragraph indent of the text + following the heading is suppressed.\\ + \PValue{font} & \PName{font commands} & The font settings that should be + used for the heading in addition to + \DescRef{maincls.fontelement.disposition}. You can use all settings that + are allowed for \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for the element of the heading.\\ + \PValue{indent} & \PName{length} & The indentation of heading from the + left margin.\\ \bottomrule \end{tabularx} \end{table} \begin{table} - \caption[{Attributes of the style \PValue{chapter} declaring a section-like - command}]{Additional \PName{keys} and \PName{value}s of attributes - declaring a section-like command with style \PValue{chapter}}% + \caption[{Attributes of the \PValue{chapter} style when declaring a + sectioning command}]{Additional \PName{keys} and \PName{value}s for + attributes when declaring a sectioning command with the \PValue{chapter} + style}% \label{tab:maincls-experts.declarechapterstyle.keys}% \begin{tabularx}{\linewidth}{llX} \toprule \PName{key} & \PName{value} & Description \\ \midrule - \PValue{afterskip} & \PName{length} & The absolute value is the - vertical skip below the heading.\\ - \PValue{beforeskip} & \PName{length}& The absolute value of the vertical - skip before the heading. If the - value is negative, then the - paragraph indent of the text - following the heading is - suppressed. This will be done also - for positive values if class option - \DescRef{maincls.option.version} is - set to a value less than 3.22.\\ - \PValue{font} & \PName{font commands} & - The initial font setting that - should be used beside - \DescRef{maincls.fontelement.disposition} for the - heading. You can use all settings, - that are allowed for - \DescRef{maincls.cmd.setkomafont} and - \DescRef{maincls.cmd.addtokomafont} for the - element of the heading.\\ + \PValue{afterskip} & \PName{length} & The value is the vertical skip below + the heading.\\ + \PValue{beforeskip} & \PName{length} & The value of the vertical skip + before the heading. If the value is negative, then the positive distance + is nevertheless inserted, and the paragraph indent of the text following + the heading is suppressed. There will also be no indentation even for + positive values if the \DescRef{maincls.option.version} class option is + set to a value less than 3.22.\\ + \PValue{font} & \PName{font commands} & The font setting to use for the + heading in addition to \DescRef{maincls.fontelement.disposition}. You + can use all settings, that are allowed for + \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for this element.\\ \PValue{innerskip} & \PName{length} & The vertical skip between the prefix - line and the heading's text, if a - prefix line is used.\\ - \PValue{pagestyle} & \PName{page style name} & - The name of the page style that - should be used automatically on - pages with the heading. There is no - validation whether or not - \PName{page style name} is really - the name of a page style. Therefore, - wrong names will result in error - messages at usage of the - section-like command.\\ - \PValue{prefixfont} & \PName{font commands} & - The initial font setting that - should be used beside - \DescRef{maincls.fontelement.disposition} - and the - element of the heading for the - prefix line of the heading. You can - use all settings that are allowed - for - \DescRef{maincls.cmd.setkomafont} - and - \DescRef{maincls.cmd.addtokomafont} - for the element of the prefix - line.\\ + line and the heading's text, if a prefix line is used.\\ + \PValue{pagestyle} & \PName{page style name} & The name of the page style + to use automatically for pages with the heading. There is no check to + see if the \PName{page style name} is valid. Therefore, incorrect names + will result in error messages when the sectioning command is used.\\ + \PValue{prefixfont} & \PName{font commands} & The font setting to use + for the prefix line of the heading, in addition to the + \DescRef{maincls.fontelement.disposition} and sectioning command + elements. You can use all settings that are allowed for + \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for the element of the prefix + line.\\ \bottomrule \end{tabularx} \end{table} \begin{table} - \caption[{Attributes of the style \PValue{part} declaring a section-like - command}]{Additional \PName{keys} and \PName{value}s of attributes - declaring a section-like command with style \PValue{part}}% + \caption[{Attributes of the \PValue{part} style when declaring a sectioning + command}]{Additional \PName{keys} and \PName{value}s for attributes + when declaring a sectioning command with the \PValue{part} style}% \label{tab:maincls-experts.declarepartstyle.keys}% \begin{tabularx}{\linewidth}{llX} \toprule \PName{key} & \PName{value} & Description \\ \midrule - \PValue{afterskip} & \PName{length} & The absolute value is the - vertical skip below the heading.\\ - \PValue{beforeskip} & \PName{length}& The absolute value of the vertical - skip before the heading.\\ - \PValue{font} & \PName{font commands} & - The initial font setting that - should be used beside - \DescRef{maincls.fontelement.disposition} - for the - heading. You can use all settings, - that are allowed for - \DescRef{maincls.cmd.setkomafont} and - \DescRef{maincls.cmd.addtokomafont} - for the element of the heading.\\ + \PValue{afterskip} & \PName{length} & The value is the vertical skip below + the heading.\\ + \PValue{beforeskip} & \PName{length}& The value is the vertical skip above + the heading.\\ + \PValue{font} & \PName{font commands} & The font setting to use for the + heading in addition to \DescRef{maincls.fontelement.disposition}. You + can use all settings that are allowed for + \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for the element of the heading.\\ \PValue{innerskip} & \PName{length} & % \OnlyAt{\Class{scrbook}\and % \Class{scrreprt}}% - The vertical skip between the prefix - line and the heading's text of - \Class{scrbook} and - \Class{scrreprt}.\\ + The vertical skip between the prefix line and the heading text in + \Class{scrbook} and \Class{scrreprt}.\\ \PValue{pagestyle} & \PName{page style name} & % \OnlyAt{\Class{scrbook}\and % \Class{scrreprt}}% - The name of the page style that - should be used automatically on - pages with the heading. There is no - validation whether or not - \PName{page style name} is really - the name of a page style. Therefore, - wrong names will result in error - messages at usage of the - section-like command. This feature - is only available with - \Class{scrbook} or - \Class{scrreprt}.\\ - \PValue{prefixfont} & \PName{font commands} & - The initial font setting that - should be used beside - \DescRef{maincls.fontelement.disposition} - and the - element of the heading for the - prefix line of the heading. You can - use all settings that are allowed - for - \DescRef{maincls.cmd.setkomafont} - and - \DescRef{maincls.cmd.addtokomafont} - for the element of the prefix - line.\\ + The name of the page style to use automatically on pages with the + heading. There is no check to see if \PName{page style name} is valid. + Therefore, incorrect names will result in error messages when the + sectioning command is used. This feature only exists in \Class{scrbook} + and\Class{scrreprt}.\\ + \PValue{prefixfont} & \PName{font commands} & The font setting to use for + the prefix line of the heading, in addition to the + \DescRef{maincls.fontelement.disposition} and sectioning command + elements. You can use all settings that are allowed for + \DescRef{maincls.cmd.setkomafont} and + \DescRef{maincls.cmd.addtokomafont} for the element of the prefix + line.\\ \bottomrule \end{tabularx} \end{table} -\Macro{DeclareNewSectionCommand} defines a new section-like command. If the +\Macro{DeclareNewSectionCommand} defines a new sectioning command. If the same \PName{name} is already used by \TeX{} for something else, the command will result in an error message and will not define anything. -\Macro{ProvideSectionSommand} is similar but does not show any error message. +\Macro{ProvideSectionSommand} behaves similarly but does not issue an error +message. -\Macro{RedeclareSectionCommand} can only change an existing command to a -section-like command with given \PName{attributes}. There is no pre-validation -to make sure that \Macro{\PName{name}} was a section-like command -before. However, it has to be an already used command sequence \PName{name}. +\Macro{RedeclareSectionCommand}, on the other hand, can only change an +existing command to a sectioning command with the specified +\PName{attributes}. It does not check whether \Macro{\PName{name}} is already +a sectioning command. It only needs to be a \PName{name} already a \TeX +command. \Macro{DeclareSectionCommand} does not check whether or not \PName{name} is -an already used \TeX{} command sequence. It just defines a section-like -command \Macro{\PName{name}} with the given \PName{attributes}. - -Every section-like command has also a corresponding counter with the same -\PName{name}, that will be allocated using \Macro{newcounter} if -necessary. The same rule applies to the corresponding output of the counter: -\Macro{the\PName{name}}, the output format: \Macro{\PName{name}format}, the -command to generate a running head: \Macro{\PName{name}mark}, the counter -format of the running head: \Macro{\PName{name}markformat}, the font element: -\FontElement{\PName{name}}, and the section depth number: -\Macro{\PName{name}numdepth}. The command for the running head -\Macro{\PName{name}mark} will be defined to not generate any running head. The -output of the counter, \Macro{the\PName{name}}, will show an Arabic number. If -the \PName{key} \PValue{counterwithin} defines a counter the heading number -depends on, the output of the counter will be prefixed by the output of that -counter followed by a dot. - -Beside\ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} the section-like command, a command for corresponding -entries to the table of contents is defined also. This is done using package -\Package{tocbasic}\important{\Package{tocbasic}}\IndexPackage{tocbasic}. -Attribute \PName{tocstyle} defines the style of those entries. If you set an -empty \PName{name}, e.\,g., using \OptionValue{tocstyle}{} or -\OptionValue{tocstyle}{\{\}}, the entry command will not be changed. This is -important, if you use another package to modify the table of contents. If you -do not set attribute \PValue{tocstyle} the already configured style will be -used again. +an existing \TeX{} command name. It just defines a sectioning +command \Macro{\PName{name}} with the specified \PName{attributes}. + +Each sectioning command also has a corresponding counter with the same +\PName{name} that is allocated with \Macro{newcounter} if necessary. The same +naming rule applies to the corresponding output of the counter +(\Macro{the\PName{name}}), the counter's format (\Macro{\PName{name}format}), +the command to generate a running head (\Macro{\PName{name}mark}), the format +of the counter in the running head (\Macro{\PName{name}markformat}), the font +element (\FontElement{\PName{name}}), and the section-depth number +(\Macro{\PName{name}numdepth}). The command for the running head, +\Macro{\PName{name}mark}, is defined by default not to generate a running +head. The default output of the counter \Macro{the\PName{name}} is an Arabic +number. If the counter is defined as depending on another counter with the +\PValue{counterwithin} \PName{key}, the output of this counter will be +prefixed by a dot. + +In\ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} addition to the sectioning command itself, a command for +corresponding entries to the table of contents is also defined. This is done +using the \hyperref[cha:tocbasic]{\Package{tocbasic}}% +\important{\hyperref[cha:tocbasic]{\Package{tocbasic}}}\IndexPackage{tocbasic} +package. The \PName{tocstyle} attribute defines the style of those entries. If +you set an empty \PName{name}, e.\,g. using \OptionValue{tocstyle}{} or +\OptionValue{tocstyle}{\{\}}, the command for the TOC entry will not be +changed. This is important, for example, if you use another package to modify +the table of contents. If you do not set the \PValue{tocstyle} attribute, the +previous style will be used again during the redefinition. The\ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} different toc-entry styles also have different, additional -attributes. You can set them here too, if you prefix them with -\PValue{toc}. For example, you can setup the level of the toc-entries, -\PValue{level}, using \PValue{toclevel}, the indention, \PValue{indent}, using -\PValue{tocindent}, or the number width, \PValue{numwidth}, using -\PValue{tocnumwidth}. For more toc-entry style attributes see -\autoref{sec:tocbasic.tocstyle}, \autopageref{sec:tocbasic.tocstyle}. + \Class{scrartcl}} different TOC-entry styles also have different additional +attributes. You can set them directly if you prefix them with \PValue{toc}. +For example, you can set the level of the TOC entries, \PValue{level}, using +\PValue{toclevel}, the indention, \PValue{indent}, using \PValue{tocindent}, +or the number width, \PValue{numwidth}, using \PValue{tocnumwidth}. For more +TOC-entry style attributes see \autoref{sec:tocbasic.tocstyle}, +\autopageref{sec:tocbasic.tocstyle}. \begin{Example} - Because of incomprehensible reasons, the headings of - \DescRef{maincls.cmd.paragraph} shouldn't be run-in headings any longer but - headings similar to \DescRef{maincls.cmd.subsubsection}. The vertical skip - above the heading should be 10\,pt and the following text should be set - without any vertical distance. To do so, you can simply use: + For some unknown reason, you want to redefine the + \DescRef{maincls.cmd.paragraph} headings so that they are no longer run-in + headings but are similar to \DescRef{maincls.cmd.subsubsection}. The + vertical skip above the heading should be 10\Unit{pt} and no additional + vertical skip below the heading. To do so, you can use: \begin{lstcode} \RedeclareSectionCommand[% beforeskip=-10pt,% afterskip=1sp% ]{paragraph} \end{lstcode} - The negative value of \PValue{beforeskip} does not only result in a - positive vertical skip before the heading, but also deactivates the paragraph - indentation of the following text. Despite the specification of no vertical - skip after the heading a value of 1\,sp has been given to - \PValue{afterskip}. This is because \LaTeX{} here doesn't accept 0\,pt as - positive value. So 1\,sp is the lowest possible positive value. - - Generally, for the vertical adjustment it is better to have some - tolerance in the declaration of gaps\,---\,the so called \emph{glue}: + The negative value of \PValue{beforeskip} creates a positive vertical skip + before the heading and simultaneously disables the paragraph indentation of + the following text. Even though the specification did not want any vertical + skip after the heading, a value of 1\Unit{sp} has been given here. This is + because \LaTeX{} doesn't recognize 0\Unit{pt} as positive value. So + 1\Unit{sp} is the smallest possible positive value. + + Generally, it is better to have some tolerance for adjusting the vertical + spacing, the so-called \emph{glue}: \begin{lstcode} \RedeclareSectionCommand[% beforeskip=-10pt plus -2pt minus -1pt,% afterskip=1sp plus -1sp minus 1sp% ]{paragraph} \end{lstcode} - Doing so you have to know, that the glue also switches the algebraic sign - before becoming a skip, if the value is negative. That is the reason for the - negative glue values in the example. Additionally we used the occasion to - minimize the vertical skip after the heading using glue too. + Note that the glue also switches the algebraic sign before becoming a skip, + if the value is negative. That is the reason for the negative glue values in + the example. Additionally we used the occasion to minimize the vertical skip + after the heading using glue too. \end{Example} -In the example above only \PValue{beforeskip} and \PValue{afterskip} were -needed, because since v3.15 \KOMAScript{} defines -\DescRef{maincls.cmd.paragraph} itself using -\Macro{DeclareSectionCommand}. All other values are just reused with their -initial definition. Furthermore, the original definition of -\DescRef{maincls.cmd.paragraph} in \Class{scrartcl} reads: +In the example above, we only needed to define the keys \PValue{beforeskip} +and \PValue{afterskip} because since v3.15 \KOMAScript{} has defined +\DescRef{maincls.cmd.paragraph} internally using +\Macro{DeclareSectionCommand}, and therefore the other settings can be adopted +unchanged. The original definition of \DescRef{maincls.cmd.paragraph} in +\Class{scrartcl} reads: \begin{lstcode} \DeclareSectionCommand[% level=4, @@ -833,23 +797,24 @@ initial definition. Furthermore, the original definition of \end{lstcode} \Class{scrreprt} and \Class{scrbook} use slightly different values. -Some settings of \DescRef{maincls.cmd.chapter} depend on option -\DescRef{maincls.option.headings} (see \autoref{sec:maincls.structure}, +Some settings of \DescRef{maincls.cmd.chapter} depend on the +\DescRef{maincls.option.headings} option (see \autoref{sec:maincls.structure}, \DescPageRef{maincls.option.headings}). \hyperref[tab:maincls.chapter.skips]{Table~\ref*{tab:maincls.chapter.skips}} shows the default values of these settings. An overview of all settings is shown in \autoref{tab:maincls.section.defaults}. For more information\ChangedAt[2016/03]{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} about the default of the toc-entry styles see +\Class{scrartcl}} about the default of the TOC-entry styles see \autoref{sec:tocbasic.tocstyle}\important{\Package{tocbasic}}, -\autopageref{sec:tocbasic.tocstyle}. Please note, that \PValue{1ex} and +\autopageref{sec:tocbasic.tocstyle}. Note that \PValue{1ex} and \Length{baselineskip} depend on the default font size of the heading or the table of contents entry.% -% + \begin{table} \centering - \caption{Defaults of the chapter headings of \Class{scrbook} - and \Class{scrreprt} subject to option \DescRef{maincls.option.headings}} + \caption{Defaults for the chapter headings of \Class{scrbook} + and \Class{scrreprt} depending on the \DescRef{maincls.option.headings} + option} \label{tab:maincls.chapter.skips} \begin{tabular}{ll} \multicolumn{2}{@{}l}{\bfseries @@ -894,12 +859,12 @@ table of contents entry.% %begin{table} % \centering \begin{longtable}{@{}p{\columnwidth}@{}} - \caption{Default of the headings of \Class{scrbook} and + \caption{Defaults for the headings of \Class{scrbook} and \Class{scrreprt}}% \label{tab:maincls.section.defaults}\\ \endfirsthead - \caption[]{Default of the headings of \Class{scrbook} and - \Class{scrreprt} \emph{(Continuation)}}\\ + \caption[]{Default for the headings of \Class{scrbook} and + \Class{scrreprt} \emph{(continued)}}\\ \addlinespace[-\normalbaselineskip] \endhead \raggedleft\dots\\ @@ -938,7 +903,7 @@ table of contents entry.% \PValue{font} & see element \DescRef{maincls.fontelement.chapter}, \autoref{tab:maincls.structureElementsFont}, \autopageref{tab:maincls.structureElementsFont} \\ - \PValue{innerskip} & \PValue{0pt} \\ + \PValue{innerskip} & \PValue{0.5\Length{baselineskip}} \\ \PValue{level} & 0 \\ \PValue{prefixfont} & see element \DescRef{maincls.fontelement.chapterprefix}, @@ -1050,7 +1015,10 @@ table of contents entry.% \end{tabularx} \end{longtable} %end{table} -% +Incidentally, the internal macro \Macro{scr@parindent} used in the settings +for \DescRef{maincls.cmd.subparagraph} is the paragraph indent set by the +\DescRef{maincls.option.parskip} option or the +\DescRef{maincls-experts.cmd.setparsizes} command. \EndIndexGroup @@ -1064,98 +1032,111 @@ table of contents entry.% \Macro{ProvideSectionCommands}\OParameter{attributes} \Parameter{list of names} \end{Declaration} -With\ChangedAt[2014/11]{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} these commands you can either define or change several -section-like commands at once. The names of the section-like commands are -given by the comma-separated \PName{list of names}. - -There are two more differences to the previously described commands that only -define or change a single section-like command. Firstly, in case of error\,---\,if \Macro{DeclareNewSectionCommands} is used for an already defined \TeX{} -command sequence or if \Macro{RedeclareSectionCommands} is used for an -undefined \TeX{} command sequence\,---\,the definition will be done in spite -of raising an error message. - -Secondly, there is one more attribute \PValue{increaselevel} with an optional -integer argument. This attribute changes the meaning of the attributes -\PValue{level} and \PValue{toclevel} (see -\autoref{tab:maincls-experts.declaresection.keys}) so their values become -start values for the first section-like command of the \PName{list of - names}. From section-like command to section-like command of the \PName{list - of names} the value of \PValue{level} and \PValue{toclevel} -will be increased by the value of \PValue{increaselevel}. If attribute -\PValue{increaselevel} is used without an assignment the increase value is 1. +These\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} commands can define or change a whole series of +sectioning commands at once. The names of the sectioning commands are given by +the comma-separated \PName{list of names}. + +These commands differ in two other ways from the previously described commands +that only define or change a single sectioning command. First, in case of +error\,---\,that is if a command already exists with +\Macro{DeclareNewSectionCommands} or is undefined with +\Macro{RedeclareSectionCommands}\,---\,the definition will be performed +regardless. An appropriate an error message will, of course, be reported +anyway. + +Second, there is another attribute, +\important{\PValue{increaselevel}}\OptionVName{increaselevel}{integer}. This +attribute changes the meaning of the attributes \PValue{level} and +\PValue{toclevel} (see \autoref{tab:maincls-experts.declaresection.keys}) so +that their values become starting values for the first sectioning command of +the \PName{list of names}. For all other sectioning command in the \PName{list +of names}, the values of \PValue{level} and \PValue{toclevel} are successively +increased by the value of \PValue{increaselevel}. If the +\PValue{increaselevel} attribute is used without assigning a value, 1 is +assumed. % \EndIndexGroup \begin{Declaration} - \Macro{chapterheadstartvskip}% - \Macro{chapterheadmidvskip}% - \Macro{chapterheadendvskip}% - \Macro{partheadstartvskip}% - \Macro{partheadmidvskip}% - \Macro{partheadendvskip}% + \Macro{chapterheadstartvskip} + \Macro{chapterheadmidvskip} + \Macro{chapterheadendvskip} + \Macro{partheadstartvskip} + \Macro{partheadmidvskip} + \Macro{partheadendvskip} \Macro{partheademptypage} \end{Declaration} These\important[i]{\DescRef{maincls.cmd.chapter}\\ \DescRef{maincls.cmd.part}\\ \DescRef{maincls.cmd.addchap}\\ - \DescRef{maincls.cmd.addpart}} commands are used inside of the definition of the headings -\DescRef{maincls.cmd.chapter}\IndexCmd{chapter}, \DescRef{maincls.cmd.part}, \DescRef{maincls.cmd.addchap}, -\DescRef{maincls.cmd.addpart} and their star-variations. Thereby -\Macro{chapterheadstartvskip} is designed to be a command, that inserts a -vertical distance before the chapter heading. Analogues -\Macro{chapterheadendvskip} is designed to be a command, that inserts a vertical -distance after the chapter heading. If\ChangedAt{v3.15}{\Class{scrbook}\and + \DescRef{maincls.cmd.addpart}\\ + \DescRef{maincls.cmd.chapter*}\\ + \DescRef{maincls.cmd.part*}\\ + \DescRef{maincls.cmd.addchap*}\\ + \DescRef{maincls.cmd.addpart*}} commands are used inside the headings of the +previously described \PValue{chapter} and \PValue{part} styles and thus for +the definitions of \DescRef{maincls.cmd.chapter}\IndexCmd{chapter}, +\DescRef{maincls.cmd.part}\IndexCmd{part}, +\DescRef{maincls.cmd.addchap}\IndexCmd{addchap}, and +\DescRef{maincls.cmd.addpart}\IndexCmd{addpart}, as well as their starred +variants \DescRef{maincls.cmd.chapter*}\IndexCmd{chapter*}, +\DescRef{maincls.cmd.part*}\IndexCmd{part*}, +\DescRef{maincls.cmd.addchap*}\IndexCmd{addchap*}, and +\DescRef{maincls.cmd.addpart*}\IndexCmd{addpart*}. +The \Macro{chapterheadstartvskip} command is intended to insert a +vertical skip before the chapter heading. Similarly, +\Macro{chapterheadendvskip} is a command intended to insert a vertical +skip after the chapter heading. If\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}} the chapter heading has a prefix number line (see option \DescRef{maincls.option.chapterprefix} in \autoref{sec:maincls.structure}, \DescPageRef{maincls.option.chapterprefix}), \Macro{chapterheadmidvskip} -will be used between the number line and the heading text. +is also used between the number line and the heading text. -Vertical distance above and below part headings will be inserted using the -commands \Macro{partheadstartvskip} and \Macro{partheadendvskip}. A page break -would be interpreted to be part of the vertical distance and therefore is -already part of the default of \Macro{partheadendvskip} in +The \Macro{partheadstartvskip} and \Macro{partheadendvskip} commands insert +vertical skips above and below part headings. A page break is interpreted as +part of the vertical distance. Such a page break is part of the default +definitions of \Macro{partheadendvskip} in \Class{scrbook}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} and -\Class{scrreprt}. Command +\Class{scrreprt}. The \Macro{partheademptypage}\ChangedAt{v3.02}{\Class{scrbook}\and - \Class{scrreprt}} is used to produce the empty page after the part heading -page of \Class{scrbook} and \Class{scrreprt}. +\Class{scrreprt}} command produces an empty page after the part heading page +of \Class{scrbook} and \Class{scrreprt}. -Since \KOMAScript~3.15\ChangedAt{v3.15}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} the defaults of these seven commands -are independent from option \DescRef{maincls.option.headings} (see +Starting with \KOMAScript~3.15\ChangedAt{v3.15}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}, the defaults of these seven commands +are independent from the \DescRef{maincls.option.headings} option (see \autoref{sec:maincls.structure}, -\DescPageRef{maincls.option.headings}). The original definitions of the -chapter heading reads since -\KOMAScript~3.157\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}}:\IndexLength{@tempskipa} +\DescPageRef{maincls.option.headings}). The default definitions for the +chapter headings starting with +\KOMAScript~3.17\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} correspond to:\IndexLength{@tempskipa} \begin{lstcode} \newcommand*{\chapterheadstartvskip}{\vspace{\@tempskipa}} \newcommand*{\chapterheadmidvskip}{\par\nobreak\vskip\@tempskipa} \newcommand*{\chapterheadendvskip}{\vskip\@tempskipa} \end{lstcode} -Every usage of \OptionValueRef{maincls}{headings}{big}\IndexOption{headings}, +These defaults are reactivated every time you use +\OptionValueRef{maincls}{headings}{big}\IndexOption{headings}, \OptionValueRef{maincls}{headings}{normal}, or -\OptionValueRef{maincls}{headings}{small} reactivates these default -definitions. - -Command \DescRef{maincls.cmd.chapter} automatically sets the internal length -\Length{@tempskipa} to the value of the -\DescRef{\LabelBase.cmd.DeclareSectionCommand}\IndexCmd{DeclareSectionCommand} attribute -\PValue{beforeskip} before calling -\Macro{chapterheadstartvskip}. Correspondingly it sets the length to the value -of attribute \PValue{afterskip} before calling \Macro{chapterheadendvskip} and -\PValue{innerskip} before calling \Macro{chapterheadmidvskip}. If you redefine -\Macro{chapterheadstartvskip}, \Macro{chapterheadmidvskip}, or -\Macro{chapterheadendvskip} you should also correspond the new definition to -\Length{@tempskipa} to respect the values of \DescRef{\LabelBase.cmd.DeclareSectionCommand}. - -The default values of the distances of \DescRef{maincls.cmd.part} do not depend on option -\DescRef{maincls.option.headings}. So the corresponding commands will not be redefined using -the options. The\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} original definitions of these commands of \Class{scrbook} -and \Class{scrreprt} read: +\OptionValueRef{maincls}{headings}{small}. As a side effect, these options may +affect not only chapter titles but all headings in the \PValue{chapter} style + +The \PValue{chapter} style automatically sets the internal length +\Length{@tempskipa} to the value that results from the +\DescRef{\LabelBase.cmd.DeclareSectionCommand}\IndexCmd{DeclareSectionCommand} +attribute \PValue{beforeskip} before calling \Macro{chapterheadstartvskip}. +Similarly, it sets this length to the value of the \PValue{afterskip} +attribute before calling \Macro{chapterheadendvskip}, and to +\PValue{innerskip} before calling \Macro{chapterheadmidvskip}. + +The default values of the distances of \DescRef{maincls.cmd.part} do not +depend on the \DescRef{maincls.option.headings} option. So the corresponding +commands will not be redefined by this option. +Their\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and +\Class{scrartcl}} default definitions in \Class{scrbook} and \Class{scrreprt} +correspond to: \begin{lstcode} \newcommand*{\partheadstartvskip}{% \null\vskip-\baselineskip\vskip\@tempskipa @@ -1180,45 +1161,135 @@ and of \Class{scrartcl}: \vskip\@tempskipa } \end{lstcode} -Again \DescRef{maincls.cmd.part} sets -\Length{@tempskipa}\IndexLength{@tempskipa} to the values of +The \PValue{part} style once again sets the internal length +\Length{@tempskipa}\IndexLength{@tempskipa} according to the settings of \DescRef{\LabelBase.cmd.DeclareSectionCommand}\IndexCmd{DeclareSectionCommand} -before the internal usage of the command. - -It\ChangedAt[2015/03]{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} is not recommended to redefine the command for the -distances above or below the headings only for changing these distances, -because you can reconfigure these distances much easier using -\DescRef{\LabelBase.cmd.RedeclareSectionCommand}. Redefinition of the commands -should be reserved to more complex changes. An\textnote{Example!} example -that redefines \Macro{chapterheadstartvskip} and \Macro{chapterheadendvskip} -to print extra rules above and below the chapter heading may be found at -\cite{homepage} (in German).% +before using the commands. + +If you redefine one of the commands used for the vertical skip in the original +\Length{@tempskipa} but still want to be able to configure the lengths, for +example with \DescRef{\LabelBase.cmd.RedeclareSectionCommand}, you should also +use \Length{@tempskipa} in the new definition. +Since\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} you can more easily configure the distances above, within, +and below the headings using \DescRef{\LabelBase.cmd.RedeclareSectionCommand}, +you generally should not redefine the commands described here. Changing them +should be reserved for more complex changes that cannot be accomplished with +\DescRef{\LabelBase.cmd.RedeclareSectionCommand}. An\textnote{Example!} +example that redefines \Macro{chapterheadstartvskip} and +\Macro{chapterheadendvskip} to print extra rules above and below the chapter +heading can be found at \cite{homepage} (in German).% % \EndIndexGroup \begin{Declaration} + \Macro{partlineswithprefixformat}% + \Parameter{level}\Parameter{number}\Parameter{text}% +\end{Declaration} +This\ChangedAt{v3.25}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} command is used by headings with the \PValue{part} style to +output the heading number and heading text. The \PName{number} and +\PName{text} arguments are already formatted, including the font +selections. Ultimately, this command controls the arrangement of the two parts +of the heading. For unnumbered headings, \PName{number} is a completely empty +argument, so it does not contain any formatting commands. + +The default definition is rather Spartan: +\begin{lstcode} + \newcommand{\partlineswithprefixformat}[3]{% + #2#3% + } +\end{lstcode} + +\begin{Example} + You want to have part headings in a light blue box with blue frame. The + box should occupy only about three quarters of full width of the text + area. So you try: +\begin{lstcode} + \documentclass{scrbook} + \usepackage{xcolor} + \renewcommand*{\partlineswithprefixformat}[3]{% + \fcolorbox{blue}{blue!25}{% + \parbox{.75\linewidth}{#2#3}% + }% + } + \begin{document} + \part{Framed Part} + \end{document} +\end{lstcode} + But surprisingly the heading is not longer centred\,---\,neither the box + itself nor the text inside the box. + + The reason for the missing centring of the box is that the end of the + paragraph is hidden in the third argument of the command. So it still + finishes the paragraph of the text inside the box but not the paragraph of + the \Macro{parbox} itself. To solve this you add a \Macro{par} at the end of + the definition. + + The reason for the missing centring inside the box is that the alignment of + \DescRef{maincls.cmd.raggedpart} is valid outside the box but not + automatically inside a \Macro{parbox}. To solve this you add + \Macro{raggedpart} inside the box. + + With +\begin{lstcode} + \documentclass{scrbook} + \usepackage{xcolor} + \renewcommand*{\partlineswithprefixformat}[3]{% + \fcolorbox{blue}{blue!25}{% + \parbox{.75\linewidth}{\raggedpart #2#3}% + }% + } + \par + \begin{document} + \part{Framed Part} + \end{document} +\end{lstcode} + you get the expected result. +\end{Example} + +As the example shows, users who redefine this command must watch out for +several side effects. In addition to preserving the text alignment, they also +must prevent page breaks within the headings, for example if they insert extra +paragraphs or space. The example above does not have this problem. Not only +does the box prevent a page breaks anyway, but \KOMAScript{} itself also +changes \Macro{interlinepenalty} as part of \PName{text} so to prevent page +breaks there. It also finishes \PName{text} with an internal paragraph break +using \Macro{@@par}. + +The default definition of \Macro{partlineswithprefixformat} does not use the +first argument, \PName{level}, nor is it needed in the example above. It is of +interest only if you want to define several commands with the \PValue{part} +style and need to distinguish the different levels. The predefined commands +\DescRef{maincls.cmd.part}, \DescRef{maincls.cmd.part*}, +\DescRef{maincls.cmd.addpart}, and \DescRef{maincls.cmd.addpart*} all share +the same \PName{level} \PName{part}.% +\EndIndexGroup + + +\begin{Declaration} \Macro{chapterlineswithprefixformat}% \Parameter{level}\Parameter{number}\Parameter{text}% \Macro{chapterlinesformat}% \Parameter{level}\Parameter{number}\Parameter{text} \end{Declaration} These\ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}} commands are used -by headings with style \PValue{chapter} to output the heading number and -heading text depending on option +by headings with the \PValue{chapter} style to output the heading number and +heading text, depending on the \DescRef{maincls.option.chapterprefix}\IndexOption{chapterprefix}% -\textnote{\DescRef{maincls.option.chapterprefix}} (see \autoref{sec:maincls.structure}, -\DescPageRef{maincls.option.chapterprefix}). If the option is -\PValue{true} \Macro{chapterlineswithprefixformat} is used, otherwise -\Macro{chapterlinesformat}. +\textnote{\DescRef{maincls.option.chapterprefix}} option (see +\autoref{sec:maincls.structure}, +\DescPageRef{maincls.option.chapterprefix}). If the option is \PValue{true}, +\Macro{chapterlineswithprefixformat} is used. Otherwise +\Macro{chapterlinesformat} determines the ouput. -The arguments \PName{number} and \PName{text} are already formatted, i.\,e., -they contain font selections. At least the order and layout of both has to be -done with these commands. If a heading has no number argument \PName{number} -will be completely empty also without any format or font commands. +The \PName{number} and \PName{text} arguments are already formatted, including +the font selections. Ultimately, these commands thus control the arrangement +of the two parts of the heading. For unnumbered headings, the \PName{number} +argument is completely empty, so it does not contain any formatting commands. -The default definitions are very simple: +The\textnote{default} defaults for these commands are: \begin{lstcode} \newcommand{\chapterlinesformat}[3]{% \@hangfrom{#2}{#3}% @@ -1230,7 +1301,8 @@ The default definitions are very simple: \begin{Example} You want to have chapter headings with yellow background. For the headings - without prefix line you use the follow definition in the document preamble: + without a prefix line, you use the following definition in the document + preamble: \begin{lstcode} \makeatletter \renewcommand{\chapterlinesformat}[3]{% @@ -1242,7 +1314,7 @@ The default definitions are very simple: } \makeatother \end{lstcode} - For chapter headings without prefix line you use: + For chapter headings with prefix line, you use: \begin{lstcode} \renewcommand{\chapterlineswithprefixformat}[3]{% \colorbox{yellow}{% @@ -1252,9 +1324,9 @@ The default definitions are very simple: }% } \end{lstcode} - Unfortunately you will find, that these re-definitions result in justified + Unfortunately, you discover that these redefinitions result in justified text for the headings. The reason is the \Macro{parbox} command. To change - this, you can use \DescRef{maincls.cmd.raggedchapter} (see + this, you can use the \DescRef{maincls.cmd.raggedchapter} command (see \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.raggedchapter}) inside the argument of \Macro{parbox}. Otherwise \Macro{raggedchapter} would be used only before \Macro{chapterlineswithprefixformat} and @@ -1279,32 +1351,32 @@ The default definitions are very simple: }% } \end{lstcode} - Remember to use \Macro{makeatletter} and \Macro{makeatother} only at the - document preamble. Do not use it inside your own wrapper-class or - package. It is only needed because of \Macro{@hangfrom} in the definition of + Remember to use \Macro{makeatletter} and \Macro{makeatother} only in the + document preamble. Do not use it inside your own wrapper class or package. + They are only needed here because of \Macro{@hangfrom} in the definition of \Macro{chapterlinesformat}. \end{Example} -As the example shows, users, who change the definition of one of the commands, -should take care of several side effects. The alignment of the text is only -one thing. They also have to prevent page breaks in the headings, e.\,g., if -they add extra space into the output. The example above does not have page -break problems. Not only the boxes prevent page breaks. \KOMAScript{} itself -also changes \Macro{interlinepenalty} as part of \PName{text} to prevent page -breaks. It also finishes \PName{text} with an internal paragraph break using -\Macro{@par}. - -Command \DescRef{maincls.cmd.raggedchapter} is not part of \PName{text} but -executed before \Macro{chapterlineswithprefixformat} or -\Macro{chapterlinesformat}. This makes it much easier to use, e.\,g., -\Macro{MakeUppercase} at a re-definition. Please note, typographers use -individual letter spacing at majuscule text, but \LaTeX{} command -\Macro{MakeUppercase} does not. - -The first argument, \PName{level}, is not used by the default definition and -also not needed in the example above. It is of interest only, if a user would -define several commands with \PValue{chapter} style and need to distinguish -the different levels. The predefined commands \DescRef{maincls.cmd.chapter}, +As the example shows, users who redefine this command must watch out for +several side effects. In addition to preserving the text alignment, they also +must prevent page breaks within the headings, for example if they insert extra +paragraphs or space. The example above does not have this problem. Not only +does the box prevent a page breaks anyway, but \KOMAScript{} itself also +changes \Macro{interlinepenalty} as part of \PName{text} so to prevent page +breaks there. It also finishes \PName{text} with an internal paragraph break +using \Macro{@@par}. + +Incidentally, the \DescRef{maincls.cmd.raggedchapter} command is not part of +\PName{text}, as otherwise using \Macro{MakeUppercase} inside redefined +versions of these two commands would be much more difficult. Note, however, +that typographic rules require individual adjustments of letter spacing in +capitalised text. However the \LaTeX{} \Macro{MakeUppercase} command does not +do this. + +The default definitions do not use the first argument, \PName{level}, nor is +it needed in the example above. It is of interest only if you want to define +several commands with the \PValue{chapter} style and need to distinguish the +different levels. The predefined commands \DescRef{maincls.cmd.chapter}, \DescRef{maincls.cmd.chapter*}, \DescRef{maincls.cmd.addchap}, and \DescRef{maincls.cmd.addchap*} all share the same \PName{level} \PName{chapter}.% @@ -1318,20 +1390,19 @@ the different levels. The predefined commands \DescRef{maincls.cmd.chapter}, \Parameter{level}\Parameter{indent}\Parameter{number}\Parameter{text}% \end{Declaration} These\ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} commands are used by headings with style \PValue{section} -to output the heading number and heading text. If the heading is printed as -catch phrase at the very beginning of the following paragraph text -\Macro{sectioncatchphraseformat} is used, otherwise -\Macro{sectionlinesformat}. +\Class{scrartcl}} commands are used by headings with the \PValue{section} +style depending on whether the reading is run-in or on its own line. +Free-standing headings use \Macro{sectionlinesformat} for their output, while +run-in headings use \Macro{sectioncatchphraseformat}. In both cases \PName{indent} is the value of the horizontal indention of the -heading relative to the text area. If the value is negative the heading should -even move into the left margin. +heading relative to the text area. If the value is negative, the heading can +protrude into the left margin. -The arguments \PName{number} and \PName{text} are already formatted, i.\,e., -they contain font selections. At least the order and layout of both has to be -done with these commands. If a heading has no number argument \PName{number} -will be completely empty also without any format or font commands. +The arguments \PName{number} and \PName{text} are already formatted, including +the font settings. Ultimately, these commands thus control the arrangement of +the two parts of the heading. For unnumbered headings, the \PName{number} +argument is completely empty, so it does not contain any formatting commands. The default definitions are: \begin{lstcode} @@ -1343,14 +1414,14 @@ The default definitions are: } \end{lstcode} -If the user re-defines one of these commands, he has to take care to prevent -page breaks inside the printing of the heading. \KOMAScript{} itself only -changes \Macro{interlinepenalty} to impede page breaks. +If you redefine one of these commands, you are responsible for preventing page +breaks inside heading. \KOMAScript{} itself only changes +\Macro{interlinepenalty} to impede page breaks. \begin{Example} - Like chapter headings in the previous example, headings of \PName{level} - \PValue{section} should be printed with a background colour. The lower - levels should be affected: + As in the previous example with chapter headings, the free-standing headings + of the \PValue{section} \PName{level} should now be printed with a + background colour. Headings of lower levels should not be changed: \begin{lstcode} \makeatletter \renewcommand{\sectionlinesformat}[4]{% @@ -1369,15 +1440,16 @@ changes \Macro{interlinepenalty} to impede page breaks. } \makeatother \end{lstcode} - With this code the indention part of indented headings would not be - coloured, but with negative indention the background of the margin part of - the headings will also become yellow. You can move the \Macro{hspace*} - command into the \Macro{colorbox} to change this. - - Again remember to use \Macro{makeatletter} and \Macro{makeatother} only at the - document preamble. Do not use it inside your own wrapper-class or - package. It is only needed because of \Macro{@hangfrom} in the definition of - \Macro{sectionlinesformat}. + With this code, area of the indention is not coloured if the heading is + indented. If, however, the heading is placed in the left margin with + negative indention, this area of the margin is also highlighted. You can + move the \Macro{hspace*} command into the \Macro{colorbox} to change this + behaviour. + + Again, remember to use \Macro{makeatletter} and \Macro{makeatother} only in + the document preamble. You should omit them inside your own wrapper class or + package. They are only needed because of \Macro{@hangfrom} in the definition + of \Macro{sectionlinesformat}. \end{Example} The first argument, \PName{level}, is not used by the default definition. The @@ -1403,52 +1475,56 @@ same style \PValue{section}.% \Macro{Before@sect}\Parameter{code} \end{Declaration} As\ChangedAt[2014/09]{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} already explained in \autoref{sec:maincls.structure} in -the description of the sectioning commands beginning with -\DescPageRef{maincls.cmd.chapter}, \KOMAScript{} provides additional -features for the optional argument of those commands. Therefore, it was -necessary to replace some \LaTeX{} kernel commands, especially +\Class{scrartcl}} already explained in \autoref{sec:maincls.structure} in the +description of the sectioning commands beginning with +\DescPageRef{maincls.cmd.chapter}, \KOMAScript{} provides additional features +for the optional argument of those commands. To achieve this, it was necessary +to replace some \LaTeX{} kernel commands, especially \Macro{secdef}\IndexCmd{secdef}\important{\Macro{secdef}} and \Macro{@startsection}\IndexCmd{@startsection}% \important{\Macro{@startsection}}. The meaning of the parameters of these commands can be found in the \LaTeX{} kernel manual \cite{latex:source2e}. -Unfortunately these commands are often redefined by other packages in a way -that collides with the functionality of \KOMAScript. So \KOMAScript{} not only -changes the definition of these commands but also defines the additional, +However, these commands are often completely redefined by other packages in a +way that clashes with the functionality of \KOMAScript. So \KOMAScript{} not +only changes the definition of these commands but also defines the additional, alternative commands \Macro{SecDef} and \Macro{scr@startsection}. Package -authors are permitted to use these commands like they would use the -corresponding \LaTeX{} kernel commands and therefore participate in the -additional features of \KOMAScript. Nevertheless these commands should not be -redefined, because they could be changed in future and so the redefinition would -impair \KOMAScript{} again. - -\KOMAScript{} internally uses \Macro{SecDef} and \Macro{scr@startsection} -instead of \Macro{secdef} and \Macro{@startsection}, e.\,g., defining -section-like commands by \DescRef{\LabelBase.cmd.DeclareSectionCommand}. So -later redefinition of \Macro{secdef} or \Macro{@startsection} will not -influence the sectioning commands of \KOMAScript. - -As an alternative to the redefinition of such commands, \KOMAScript{} provides -the execution of additional \PName{code} at several states of the -\KOMAScript{} replacements. The \PName{code} of each usage of -\Macro{At@startsection}, \Macro{Before@sect}, or \Macro{Before@ssect} will be -cumulated independently. Later removing of added \PName{code} is not -provided. - -The \PName{code} of \Macro{At@startsection} is executed immediately after -the evaluation of \PName{beforeskip} and calculation of the resulting -\Length{@tempskipa}, before adding the vertical gap itself. So you still may -change the value of \Length{@tempskipa}. - -The \PName{code} of \Macro{Before@sect} and -\Macro{Before@ssect} is executed just before \Macro{@sect} -and \Macro{@ssect} inside \Macro{scr@startsection}, respectively. At this state -the vertical gap of \Length{@tempskipa} has already been added using -\Macro{addvspace}. - -The commands \Macro{At@startsection}, \Macro{Before@sect}, and -\Macro{Before@ssect} are suggested for package authors.% +authors can use these commands as they would use the corresponding \LaTeX{} +kernel commands and therefore gain access to the additional features of +\KOMAScript. However, these commands should not be redefined, as they may +changed at any time, and then this redefinition could compromise +\KOMAScript{}'s functionality. + +\KOMAScript{} itself uses \Macro{SecDef} and \Macro{scr@startsection} instead +of \Macro{secdef} and \Macro{@startsection}, for example to define sectioning +commands with \DescRef{\LabelBase.cmd.DeclareSectionCommand}. So later +redefinitions of \Macro{secdef} or \Macro{@startsection} will not influence +the sectioning commands of \KOMAScript. + +As an alternative to redefining such commands, \KOMAScript{} offers the +possibility to add additional \PName{code} at several points in +\KOMAScript{}'s own replacements. The \PName{code} of all calls to +\Macro{At@startsection}\important{\Macro{At@startsection}\\ + \Macro{Before@sect}\\ + \Macro{Before@sect}}, \Macro{Before@sect} and \Macro{Before@sect} is +collected separately for each command. There is no provision for removing +\PName{code} once it has been inserted. + +The \PName{code} of the \Macro{At@startsection}% + \important{\Macro{At@startsection}\\ + \Macro{scr@startsection}} macro is used in the \Macro{scr@startsection} +command immediately after evaluating \PName{beforeskip} and calculating the +resulting \Length{@tempskipa} but before adding the vertical skip itself. So +you can still change the value of \Length{@tempskipa}. + +The \PName{code} of \Macro{Before@sect} or \Macro{Before@ssect} is executed +within \Macro{scr@startsection} just before calling \Macro{@sect} or +\Macro{@ssect}, respectively. At this point, the vertical skip of +\Length{@tempskipa} has already been added using \Macro{addvspace}. + +These three commands, \Macro{At@startsection}, \Macro{Before@sect}, and +\Macro{Before@ssect}, are designed as an interface for package authors and +released for them to use.% % \EndIndexGroup @@ -1459,30 +1535,32 @@ The commands \Macro{At@startsection}, \Macro{Before@sect}, and \begin{Declaration} \Macro{appendixmore} \end{Declaration}% -There is a peculiarity within the \DescRef{maincls.cmd.appendix} command in -the {\KOMAScript} classes. If the command \Macro{appendixmore} is defined, -this command is executed also by the \DescRef{maincls.cmd.appendix} -command. Internally the {\KOMAScript} classes +The \KOMAScript{} classes have an unusual feature within the +\DescRef{maincls.cmd.appendix} command. If the \Macro{appendixmore} command +is defined, \DescRef{maincls.cmd.appendix} will also execute this +it. Internally, the \KOMAScript{} classes \Class{scrbook}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} and -\Class{scrreprt} take advantage of this behaviour to implement the options -\DescRef{maincls.option.appendixprefix} (see \autoref{sec:maincls.structure}, -\DescPageRef{maincls.option.appendixprefix}). You\textnote{Attention!} should -take note of this in case you decide to define or redefine the macro -\Macro{appendixmore}. In case one of this option has been used, you will -receive an error message when using -\verb|\newcommand{\appendixmore}{|\dots\verb|}|. This behaviour is intended to -prevent you from disabling options without noticing it. +\Class{scrreprt} take advantage of this behaviour to implement the +\DescRef{maincls.option.appendixprefix} layout option (see +\autoref{sec:maincls.structure}, +\DescPageRef{maincls.option.appendixprefix}). You\textnote{Attention!} should +take note of this in case you decide to define or redefine the +\Macro{appendixmore} macro. If this option has been used, you will receive an +error message when using \verb|\newcommand{\appendixmore}{|\dots\verb|}|. This +behaviour is intended to prevent you from overriding the options without +realising it. \begin{Example} You do not want the chapters in the main part of the classes \Class{scrbook} - or \Class{scrreprt} to be introduced by a prefix line (see layout options - \DescRef{maincls.option.chapterprefix} in \autoref{sec:maincls.structure}, - \DescPageRef{maincls.option.chapterprefix}). For consistency you also - do not want such a line in the appendix either. Instead, you would like to - see the word ``Chapter'' in the language of your choice written in front of - the chapter letter and, simultaneously, in the page headings. Instead of - using layout option \DescRef{maincls.option.appendixprefix}, you would define in the - document preamble: + or \Class{scrreprt} to be introduced by a prefix line (see the + \DescRef{maincls.option.chapterprefix} layout option in + \autoref{sec:maincls.structure}, + \DescPageRef{maincls.option.chapterprefix}). For consistency, you also do + not want such a line in the appendix either. Instead, you would like to see + the word ``Chapter'' in the language of your choice written in front of the + chapter letter and, simultaneously, in the page headings. Instead of using + the \DescRef{maincls.option.appendixprefix} layout option, you define the + following in the document preamble: % \begin{lstcode} \newcommand*{\appendixmore}{% @@ -1499,8 +1577,8 @@ prevent you from disabling options without noticing it. This behaviour prevents the definition made above from invisibly changing the settings intended with the option. - It is also possible to get a similar behaviour of the appendix for - the class \Class{scrartcl}. You can write in the preamble of your + It is also possible to get a similar behaviour for the appendix of the class + \Class{scrartcl}. For example, you can write in the preamble of your document: \begin{lstcode}[moretexcs={ifthenelse,equal}] \newcommand*{\appendixmore}{% @@ -1510,7 +1588,7 @@ prevent you from disabling options without noticing it. \appendixname~\thesection\autodot\enskip}} \end{lstcode} - Redefined commands are explained in more detail in + The redefined commands are explained in more detail in \autoref{sec:maincls.structure}, \DescPageRef{maincls.cmd.chapterformat} and \DescPageRef{maincls.cmd.chaptermarkformat}. @@ -1524,91 +1602,93 @@ prevent you from disabling options without noticing it. \begin{Declaration} \Macro{newbibstyle}\OParameter{parent style}\Parameter{name}%^^A - \Parameter{instructions}% + \Parameter{commands}% \Macro{newblock}% \Macro{@openbib@code}% \Macro{bib@beginhook}% \Macro{bib@endhook} \end{Declaration} -The standard classes\textnote{standard classes} already provide command -\Macro{newblock} for structuring of bibliography entries. The exact purpose of -this command depends on the class options. Using option -\Option{openbib}\important{\Option{openbib}} redefine commands -\Macro{@openbib@code} and \Macro{newblock} at the end of the used standard -class. These classes execute command \Macro{@openbib@code} at the -begin\,---\,or more precise: at the specification of the parameters of -the\,---\,list environment, that will be used for the bibliography. It should -be assumed, that many packages will execute this command in the same kind, if -they redefine the bibliography. - -The \KOMAScript{} classes do something similar. Nevertheless, they do not -redefine \Macro{@openbib@code} at the end of the class. Instead of, the -bibliography style \PValue{openstyle} is defined using -\Macro{newbibstyle}. The \PName{instructions}, that has been defined as part -of the implementation, contain the appropriate redefinition of -\Macro{@openbib@code} and \Macro{newblock}. Now, if this bibliography style -will be selected using option +The standard classes\textnote{standard classes} already provide the +\Macro{newblock} command to structure bibliography entries. The exact purpose +of this command depends on the class options. Using option +\Option{openbib}\important{\Option{openbib}} redefines the commands +\Macro{@openbib@code} and \Macro{newblock} itself at the end of the standard +class. The standard classes execute the \Macro{@openbib@code} command when +starting the bibliography list, or more precisely, when defining the +parameters for the list. You can assume that many packages which redefine the +bibliography will execute this command. + +The \KOMAScript{} classes\textnote{\KOMAScript} do something similar. However, +they do not redefine \Macro{@openbib@code} at the end of the class. Instead, +\Macro{newbibstyle} defines the \PValue{openstyle} bibliography style. The +\PName{commands} given in the implementation contain the appropriate +redefinition of \Macro{@openbib@code} and \Macro{newblock}. If you select this +bibliography style using the \OptionValueRef{maincls}{bibliography}{openstyle}% \IndexOption{bibliography~=\PValue{openstyle}}% -\important{\OptionValueRef{maincls}{bibliography}{openstyle}}, then the -\PName{instructions} will be executed immediately. This will redefine +\important{\OptionValueRef{maincls}{bibliography}{openstyle}} option, the +\PName{commands} will be executed immediately. This will redefine \Macro{@openbib@code} and \Macro{newblock}. -Beside \Macro{@openbib@code} and \Macro{newblock} also \Macro{bib@beginhook} -and \Macro{bib@endhook} may be redefined by the \PName{instructions} of the -style. Command \Macro{bib@beginhook} will be executed immediately after -heading and preamble of the bibliography, but before the begin of the list -with the bibliography entries. Command \Macro{bib@endhook} will be executed -immediately after this list at the end of the bibliography. If -\DescRef{maincls.cmd.BreakBibliography} (see +In addition to \Macro{@openbib@code} and \Macro{newblock}, +\Macro{bib@beginhook} and \Macro{bib@endhook} can also be redefined by the +\PName{commands} of the style. The \Macro{bib@beginhook} command is executed +immediately after the heading and preamble of the bibliography but before the +beginning of the list of bibliographic entries. The \Macro{bib@endhook} +command will be executed immediately after this list, at the end of the +bibliography. If \DescRef{maincls.cmd.BreakBibliography} (see \autoref{sec:maincls.bibliography}, -\DescPageRef{maincls.cmd.BreakBibliography}) intercepts the bibliography, -these commands will also executed at the begin and end of each part of the -bibliography, this would be immediately before and after +\DescPageRef{maincls.cmd.BreakBibliography}) is used to interrupt the +bibliography, these commands will also executed at the beginning and end of +each part of the bibliography, immediately before and after \DescRef{maincls.cmd.BreakBibliography}. -The commands \Macro{newblock}, \Macro{@openbib@code}, \Macro{bib@beginhook}, -and \Macro{bib@endhook} will be reset to an empty definition at the start of -each new bibliography style. After this the \PName{instructions} of the -\PName{parent style} of the bibliography style will be executed. After this -the \PName{instructions} of the bibliography style itself will be -executed. Because of this these commands has to be defined using -\Macro{renewcommand}\IndexCmd{renewcommand}\important{\Macro{renewcommand}} -not \Macro{newcommand} inside of argument \PName{instructions}. - -If the user declares additional \PName{instructions} using -\DescRef{maincls.cmd.AtEndBibliography}%\important[i]{\DescRef{maincls.cmd.AtEndBibliography}\\ -% \DescRef{maincls.cmd.AfterBibliographyPreamble}}% Passt bloeder Weise nicht! -\IndexCmd{AtEndBibliography} and -\DescRef{maincls.cmd.AfterBibliographyPreamble}\IndexCmd{AfterBibliographyPreamble} -to be executed after the preamble or at the end of the bibliography, the -\PName{instructions} of \DescRef{maincls.cmd.AfterBibliographyPreamble} will -be executed only once at the begin of the bibliography but after the -\Macro{bib@beginhook} \PName{instructions}, and the \PName{instructions} of +The \Macro{newblock}, \Macro{@openbib@code}, \Macro{bib@beginhook}, and +\Macro{bib@endhook} commands are initially defined to be empty when using a +new bibliography style. After this, the \PName{commands} of the \PName{parent +style} that was optionally specified when defining the style will be executed, +followed by the \PName{commands} for the bibliography style itself. As a +result, these commands must be defined, if necessary, with +\Macro{renewcommand}\IndexCmd{renewcommand}\important{\Macro{renewcommand}}, +not \Macro{newcommand}, inside the \PName{instructions} argument. + +If you use the +\DescRef{maincls.cmd.AtEndBibliography}\IndexCmd{AtEndBibliography} and +\DescRef{maincls.cmd.AfterBibliographyPreamble}% +\IndexCmd{AfterBibliographyPreamble} commands to declare additional +\PName{commands} to be executed after the preamble or at the end of the +bibliography, the \PName{commands} specified with +\DescRef{maincls.cmd.AfterBibliographyPreamble} will only be executed once, at +the beginning of the bibliography after the \Macro{bib@beginhook} +\PName{commands}, and the \PName{commands} of \DescRef{maincls.cmd.AtEndBibliography} will be executed only once at the end -of the bibliography but before \Macro{bib@endhook}. +of the bibliography, before \Macro{bib@endhook}. -Package\textnote{Example!} -\Package{multicol}\IndexPackage{multicol}\important{\Package{multicol}} (see -\cite{package:multicol}) could be used to define a bibliography style for -printing the bibliography with two columns: +For\textnote{Example!} example, the +\Package{multicol}\IndexPackage{multicol}\important{\Package{multicol}} +package (see \cite{package:multicol}) could be used to define a bibliography +style for printing the bibliography with two columns: % Umbruchkorrektur: listings korrigiert \begin{lstcode} \newbibstyle{twocolumstyle}{% \renewcommand*{\bib@beginhook}{\begin{multicols}{2}}% \renewcommand*{\bib@endhook}{\end{multicols}}}% \end{lstcode} -If also an \emph{open}-variation of this style should be defined, one may use -the provided heredity feature and specify a \PName{parent style}: +If you also want to define an open variation of this style, you can use +the possibilities of inheritance here and specify a \PName{parent style}: % Umbruchkorrektur: listings korrigiert \begin{lstcode} \newbibstyle{twocolumopenstyle}[openstyle]{% \renewcommand*{\bib@beginhook}{\begin{multicols}{2}}% \renewcommand*{\bib@endhook}{\end{multicols}}}% \end{lstcode} -These new defined styles may be selected using option -\DescRef{maincls.option.bibliography} as usual.% -% +You can then select these newly defined styles with the +\DescRef{maincls.option.bibliography} option as usual. + +Like\textnote{Achtung!} \DescRef{maincls.cmd.BreakBibliography}, these +commands lose all or part of their effect when \Environment{thebibliography} +is redefined, for example by using +\Package{biblatex}\IndexPackage{biblatex}\important{\Package{biblatex}}.% \EndIndexGroup |