diff options
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/scrbookreportarticle-experts-en.tex')
-rw-r--r-- | macros/latex/contrib/koma-script/doc/scrbookreportarticle-experts-en.tex | 1894 |
1 files changed, 1894 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/doc/scrbookreportarticle-experts-en.tex b/macros/latex/contrib/koma-script/doc/scrbookreportarticle-experts-en.tex new file mode 100644 index 0000000000..e3807a114c --- /dev/null +++ b/macros/latex/contrib/koma-script/doc/scrbookreportarticle-experts-en.tex @@ -0,0 +1,1894 @@ +% ====================================================================== +% scrbookreportarticle-experts-en.tex +% Copyright (c) Markus Kohm, 2001-2022 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in MANIFEST.md. +% ====================================================================== +% +% Chapter about scrbook, scrreprt, and scrartcl of the KOMA-Script guide +% expert part +% Maintained by Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrbookreportarticle-experts-en.tex} + [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $ + KOMA-Script guide (chapter: scrbook, scrreprt, scrartcl for + experts)] + +\translator{Gernot Hassenpflug\and Markus Kohm\and Karl Hagen} + +\chapter[{Additional Information about the Main Classes and + \Package{scrextend}}]{Additional Information about the Main Classes + \Class{scrbook}, + \Class{scrreprt}, and \Class{scrartcl} as well as the Package + \Package{scrextend}} +\labelbase{maincls-experts} + +\BeginIndexGroup% +\BeginIndex{Class}{scrartcl}% +\BeginIndex{Class}{scrbook}% +\BeginIndex{Class}{scrreprt}% +\BeginIndex{Package}{scrextend}% +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. Because such descriptions +are not addressed to beginners, they are condensed and require deeper +knowledge of \LaTeX. Other parts describe features that exist only for the +sake of compatibility with the standard classes or earlier versions of +\KOMAScript{}.\iffree{}{ + 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{Extensions to User Commands} +\seclabel{addInfos} + +\LoadNonFree{scrbookreportarticle-experts}{1} + +\iffree{\LoadCommonFile{footnotes-experts}}{} + +\section{\KOMAScript's Interaction with Other Packages} +\seclabel{coexistence} + +\LoadNonFree{scrbookreportarticle-experts}{2} + + +\section{Detection of \KOMAScript{} Classes} +\seclabel{identify} + +Package authors sometimes need to detect a \KOMAScript{} class. Mostly this is +of little or no interest to the average user. To identify the version of +\KOMAScript{} that is being used, refer to +\DescRef{scrbase.cmd.KOMAScriptVersion} in \autoref{sec:scrbase.identify}, +\DescPageRef{scrbase.cmd.KOMAScriptVersion}. + +\begin{Declaration} + \Macro{KOMAClassName}% + \Macro{ClassName} +\end{Declaration} +\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{scrlogo.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 + +\section{Entries to the Table of Contents} +\seclabel{toc} + +\KOMAScript{} classes provide advanced methods for generating and +manipulating entries in the table of contents. Some of these are based on +the \Package{tocbasic} package (see \autoref{sec:tocbasic.tocstyle} starting +on \autopageref{sec:tocbasic.tocstyle}). Other are implemented directly in the +classes. + +\begin{Declaration} + \Macro{raggedchapterentry} +\end{Declaration} +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 + + +\begin{Declaration} + \Macro{addtocentrydefault}\Parameter{level}\Parameter{number}% + \Parameter{heading} +\end{Declaration} +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 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 +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}}. + +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. 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}% + \PParameter{\%\\ + \quad\Macro{protect}\DescRef{tocbasic.cmd.numberline}\Parameter{number}% + \PName{heading}\%\\ + } +\end{quote} +to create this entry. + +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]{% + \IfArgIsEmpty{#3}{% + \IfArgIsEmpty{#2}{% + \addcontentsline{toc}{#1}{#3}% + }{% + \addcontentsline{toc}{#1}{\protect\numberline{#2}#3}% + }% + }% + }% +\end{lstcode} +to\IndexCmd{IfArgIsEmpty} 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{addsubparagraphtocentry}\Parameter{number}\Parameter{heading} +\end{Declaration}% +The\ChangedAt{v3.08}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} \KOMAScript{} classes call the previously described +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}}. By default, all +these commands simply pass their own \PName{level} and arguments directly to +\DescRef{\LabelBase.cmd.addtocentrydefault}.% +% +\EndIndexGroup + + +\section{Font Settings} +\seclabel{fonts} + +\KOMAScript{} classes not only provide an extended selection of basic font +sizes, but they also let you define, manipulate, and apply elements with +their own font settings. + +% Note: Instead of +% \LoadNonFree{scrbookreportarticle-experts}{5} +% here is the content of that file: +\begin{Declaration} + \Macro{@fontsizefilebase}% + \Macro{changefontsizes}\Parameter{font size} +\end{Declaration} +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}\Parameter{element}% + \Parameter{default}% + \Macro{aliaskomafont}\Parameter{alias}\Parameter{element} +\end{Declaration} +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 + + +\begin{Declaration} + \Macro{addtokomafontrelaxlist}\Parameter{macro} + \Macro{addtokomafontonearglist}\Parameter{macro} + \Macro{addtokomafontgobblelist}\Parameter{macro} +\end{Declaration} +As already mentioned in \autoref{part:forAuthors} of this manual, font +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}% +\IndexCmd{usefamilyofkomafont}\IndexCmd{useseriesofkomafont}% +\IndexCmd{useshapeofkomafont} instead of \DescRef{maincls.cmd.usekomafont} +(see \autoref{sec:maincls.textmarkup}, +\DescPageRef{maincls.cmd.usefontofkomafont}). + +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{} 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. + +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}} 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}}, 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} + \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 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 + +\section{Paragraph Indention or Gap} +\seclabel{parskip} + +Because the \KOMAScript{} classes offer extended features for setting the +paragraph indention or gap, direct changes of the standard lengths +\Length{parskip}\IndexLength{parskip}, \Length{parindent}\IndexLength{parskip} +and \Length{parfillskip}\IndexLength{parskip} are not only unnecessary but +mostly inadvisable. + +\begin{Declaration} + \Macro{setparsizes}\Parameter{indent}\Parameter{distance} + \Parameter{last-line end space} +\end{Declaration} +\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 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} +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}% +\IndexOption{version}\important{\OptionValueRef{maincls}{version}{3.17}}) +disables this recalculation.% +% +\EndIndexGroup + +\section{Counters} +\seclabel{counter} + +\LoadNonFree{scrbookreportarticle-experts}{3} + +\section{Sections} +\seclabel{sections} + +The \KOMAScript{} classes provide a wide range of options for modifying +sectioning levels and their corresponding headings. You can even define new +levels. + +\begin{Declaration} + \Macro{DeclareSectionCommand}\OParameter{attributes}\Parameter{name}% + \Macro{DeclareNewSectionCommand}\OParameter{attributes}\Parameter{name}% + \Macro{RedeclareSectionCommand}\OParameter{attributes}\Parameter{name}% + \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 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. 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}}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}. + The\textnote{Attention!} \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}}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 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 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}. When redefining + a command, the \ChangedAt{v3.24}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} \PName{key}s + \PValue{style}, \PValue{afterskip}, \PValue{beforeskip}, and \PValue{level} + are mandatory. The keys + \PValue{afterindent}\ChangedAt{v3.26}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}},\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 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 + \PName{key} & \PName{value} & Description \\ + \midrule% + \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 is reset to 0. In addition, \Macro{the\PName{counter name}} is + prefixed with a dot when this counter is output.\\ + \PValue{counterwithout}% + \ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + & \PName{counter name} + & Cancels a prior \PValue{counterwithin} setting. Therefore it makes sense + only if you 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 + and is mandatory for new levels.\\ + \PValue{style} + & \PName{name} + & Defines the style of the heading.\\ + \ChangedAt{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + \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 command \Macro{l@\dots}.\\ + \ChangedAt{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + \PValue{toc\PName{option}} + & \PName{value} + & Additional options depending 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. 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}.\\ + % \PValue{tocindent} + % & \PName{length} + % & Total indentation from the left margin of the entry in the table of + % contents corresponding to this heading, if and only if such an + % entry will be made (see \DescRef{maincls.counter.tocdepth}, + % \autoref{sec:maincls.toc}, \DescPageRef{maincls.counter.tocdepth}).\\ + % \PValue{toclevel} + % & \PName{integer} + % & A number denoting the depth of the entry in the table of contents + % corresponding to this heading, if this should differ from + % \PValue{level} (see \DescRef{maincls.counter.tocdepth}, + % \autoref{sec:maincls.toc}, \DescPageRef{maincls.counter.tocdepth}). \\ + % \PValue{tocnumwidth} + % & \PName{length} + % & Width of the box for the number of the entry in the table of + % contents.\\ + \bottomrule + \end{tabularx} +\end{table} + +\begin{table} + \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{afterindent}% + \ChangedAt{v3.26}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + & \PName{switch} + & The \PName{switch} determines whether the current paragraph indent is + applied to the first line following a freestanding heading (see + \PValue{runin}). With the default, \PValue{bysign}, the sign of + \PValue{beforeskip} determines the behaviour. If the value of + \PValue{beforeskip} is negative, the indentation of the first paragraph + following the heading is suppressed. You can use any value from + \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} to + explicitly enable or disable this indentation.\\ + \PValue{afterskip} + & \PName{length} + & In the case of a run-in heading (see \PValue{runin}), the absolute value + of the \PName{length} is the horizontal space after the heading. That is, + a positive distance is always inserted. In the case of a freestanding + heading, the \PName{length} is the vertical skip below the heading. With + \OptionValue{runin}{bysign}, a positive value results in a freestanding + heading, while a negative value or zero results in a run-in heading.\\ + \PValue{beforeskip} + & \PName{length} + & Specifies the vertical space before the heading. With + \OptionValue{afterindent}{bysign}, if the value is negative, a positive + distance\,---\,the amount of \PName{length}\,---\,is still inserted, but + in this case the indentation of the paragraph 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.\\ + \PValue{runin} + \ChangedAt{v3.26}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + & \PName{switch} + & Defines whether to use a run-in or a freestanding heading. With + the default, \PValue{bysign}, the sign of \PValue{afterskip} determines + the behaviour. In this case, a positive value of \PValue{afterskip} + results in a freestanding heading. You can use any values from + \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} to + explicitly enable or disable a run-in heading.\\ + \bottomrule + \end{tabularx} +\end{table} + +\begin{table} + \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{afterindent}% + \ChangedAt{v3.26}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + & \PName{switch} + & The \PName{switch} determines whether to apply the indentation of the + first paragraph following a heading. With the default, \PValue{bysign}, + the sign of \PValue{beforeskip} defines the behaviour. If the value of + \PValue{beforeskip} is negative, the indentation of the paragraph + following the heading is suppressed. You can use any value from + \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} to + explicitly enable or disable this indentation.\\ + \PValue{afterskip}% + \ChangedAt{v3.26}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + & \PName{length} + & The vertical skip below the heading.\\ + \PValue{beforeskip} + & \PName{length} + & The vertical skip before the heading. With + \OptionValue{afterindent}{bysign}, if the value is negative, a positive + distance\,---\,the amount of \PName{length}\,---\,is still inserted, but + in this case the indentation of the first paragraph following the heading + is suppressed.\\ + \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 + 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 \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{afterindent}% + \ChangedAt{v3.26}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + & \PName{switch} + & The \PName{switch} determines whether to apply the indentation of the + first paragraph following a heading. With the value \PValue{bysign}, + the sign of \PValue{beforeskip} determines the behaviour. If the value + of \PValue{beforeskip} is negative, the indentation of the first + paragraph following the heading is suppressed. You can use any value + from \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} to + explicitly enable or disable this indentation. For compatibility, + the default is \PValue{false} for \Class{scrartcl} and \PValue{true} for + \Class{scrbook} and \Class{scrreprt}.\\ + \PValue{afterskip} & \PName{length} & The value is the vertical skip below + the heading.\\ + \PValue{beforeskip} + & \PName{length} + & The vertical skip before the heading. With + \OptionValue{afterindent}{bysign}, if the value is negative, a positive + distance\,---\,the amount of \PName{length}\,---\,is still inserted, but + in this case the indentation of the first paragraph following the heading + is suppressed.\\ + \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 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 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 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} behaves similarly but does not issue an error +message. + +\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 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 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} + 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} 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} + 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, 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, + indent=0pt, + beforeskip=3.25ex plus 1ex minus .2ex, + afterskip=-1em, + font={}, + tocindent=7em, + tocnumwidth=4.1em, + counterwithin=subsubsection + ]{paragraph} +\end{lstcode} +\Class{scrreprt} and \Class{scrbook} use slightly different values. + +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 +\autoref{sec:tocbasic.tocstyle}\important{\Package{tocbasic}}, +\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 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 + With \OptionValueRef{maincls}{headings}{big}:}\\ + \toprule + Attribute & Default Value \\ + \midrule + \PValue{afterskip} + & \PValue{1.725\Length{baselineskip} plus .115\Length{baselineskip} + minus .192\Length{baselineskip}} \\ + \PValue{beforeskip} + & \PValue{-3.3\Length{baselineskip}-\Length{parskip}} \\ + \PValue{font} & \Macro{huge} \\ + \bottomrule\\ + \multicolumn{2}{@{}l}{\bfseries + With \OptionValueRef{maincls}{headings}{normal}:}\\ + \toprule + Attribute & Default Value \\ + \midrule + \PValue{afterskip} + & \PValue{1.5\Length{baselineskip} plus .1\Length{baselineskip} + minus .167\Length{baselineskip}} \\ + \PValue{beforeskip} + & \PValue{-3\Length{baselineskip}-\Length{parskip}} \\ + \PValue{font} & \Macro{LARGE} \\ + \bottomrule\\ + \multicolumn{2}{@{}l}{\bfseries + With \OptionValueRef{maincls}{headings}{small}:}\\ + \toprule + Attribute & Default Value \\ + \midrule + \PValue{afterskip} + & \PValue{1.35\Length{baselineskip} plus .09\Length{baselineskip} + minus .15\Length{baselineskip}} \\ + \PValue{beforeskip} + & \PValue{-2.8\Length{baselineskip}-\Length{parskip}} \\ + \PValue{font} & \Macro{Large} \\ + \bottomrule + \end{tabular} +\end{table} + +%begin{table} +% \centering + \begin{longtable}{@{}p{\columnwidth}@{}} + \caption{Defaults for the headings of \Class{scrbook} and + \Class{scrreprt}}% + \label{tab:maincls.section.defaults}\\ + \endfirsthead + \caption[]{Default for the headings of \Class{scrbook} and + \Class{scrreprt} \emph{(continued)}}\\ + \addlinespace[-\normalbaselineskip] + \endhead + \raggedleft\dots\\ + \endfoot + \endlastfoot + \DescRef{maincls.cmd.part}: \\* + \begin{tabularx}{\linewidth}{ll} + \toprule + Attribute & Default Value \\ + \midrule + \PValue{afterskip} & \PValue{0pt plus 1fil} \\ + \PValue{beforeskip} & \PValue{0pt plus 1fil + \Length{baselineskip}} \\ + \PValue{font} & see element \DescRef{maincls.fontelement.part}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{innerskip} & \PValue{20pt} \\ + \PValue{level} & -1 \\ + \PValue{prefixfont} & see element + \DescRef{maincls.fontelement.partnumber}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{tocindent} & \PValue{0pt} \\ + \PValue{toclevel} & -1 \\ + \PValue{tocnumwidth} & \PValue{2em} \\ + \PValue{tocstyle} & \PValue{part} \\ + \bottomrule + \end{tabularx} \\ + \addlinespace[\normalbaselineskip] + \DescRef{maincls.cmd.chapter}: \\* + \begin{tabularx}{\linewidth}{ll} + \toprule + Attribute & Default Value \\ + \midrule + \PValue{afterskip} & see \autoref{tab:maincls.chapter.skips} \\ + \PValue{beforeskip} & see \autoref{tab:maincls.chapter.skips} \\ + \PValue{font} & see element \DescRef{maincls.fontelement.chapter}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{innerskip} & \PValue{0.5\Length{baselineskip}} \\ + \PValue{level} & 0 \\ + \PValue{prefixfont} & see element + \DescRef{maincls.fontelement.chapterprefix}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{tocindent} & \PValue{0pt} \\ + \PValue{toclevel} & 0 \\ + \PValue{tocnumwidth} & \PValue{1.5em} \\ + \PValue{tocstyle} & \PValue{chapter} \\ + \bottomrule + \end{tabularx} \\ + \addlinespace[\normalbaselineskip] + \DescRef{maincls.cmd.section}: \\* + \begin{tabularx}{\linewidth}{ll} + \toprule + Attribute & Default Value \\ + \midrule + \PValue{afterskip} & \PValue{2.3ex plus .2ex} \\ + \PValue{beforeskip} & \PValue{-3.5ex plus -1ex minus -.2ex} \\ + \PValue{font} & see element \DescRef{maincls.fontelement.section}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{indent} & \PValue{0pt} \\ + \PValue{level} & 1 \\ + \PValue{tocindent} & \PValue{1.5em}\\ + \PValue{toclevel} & 1 \\ + \PValue{tocnumwidth} & \PValue{2.3em}\\ + \PValue{tocstyle} & \PValue{section} \\ + \bottomrule + \end{tabularx} \\ + \addlinespace[\normalbaselineskip] + \DescRef{maincls.cmd.subsection}: \\* + \begin{tabularx}{\linewidth}{ll} + \toprule + Attribute & Default Value \\ + \midrule\nopagebreak + \PValue{afterskip} & \PValue{1.5ex plus .2ex} \\ + \PValue{beforeskip} & \PValue{-3.25ex plus -1ex minus -.2ex} \\ + \PValue{font} & see element + \DescRef{maincls.fontelement.subsection}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{indent} & \PValue{0pt} \\ + \PValue{level} & 2 \\ + \PValue{tocindent} & \PValue{3.8em}\\ + \PValue{toclevel} & 2 \\ + \PValue{tocnumwidth} & \PValue{3.2em}\\ + \PValue{tocstyle} & \PValue{section} \\ + \bottomrule + \end{tabularx} \\ + \addlinespace[\normalbaselineskip] + \DescRef{maincls.cmd.subsubsection}: \\* + \begin{tabularx}{\linewidth}{ll} + \toprule + Attribute & Default Value \\ + \midrule\nopagebreak + \PValue{afterskip} & \PValue{1.5ex plus .2ex} \\ + \PValue{beforeskip} & \PValue{-3.25ex plus -1ex minus -.2ex} \\ + \PValue{font} & see element + \DescRef{maincls.fontelement.subsubsection}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{indent} & \PValue{0pt} \\ + \PValue{level} & 3 \\ + \PValue{tocindent} & \PValue{7.0em}\\ + \PValue{tocnumwidth} & \PValue{4.1em}\\ + \PValue{toclevel} & 3 \\ + \PValue{tocstyle} & \PValue{section} \\ + \bottomrule + \end{tabularx} \\ + \addlinespace[\normalbaselineskip] + \DescRef{maincls.cmd.paragraph}: \\* + \begin{tabularx}{\linewidth}{ll} + \toprule + Attribute & Default Value \\ + \midrule\nopagebreak + \PValue{afterskip} & \PValue{-1em} \\ + \PValue{beforeskip} & \PValue{3.25ex plus 1ex minus .2ex} \\ + \PValue{font} & see element \DescRef{maincls.fontelement.paragraph}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{indent} & \PValue{0pt} \\ + \PValue{level} & 4 \\ + \PValue{tocindent} & \PValue{10em}\\ + \PValue{toclevel} & 4 \\ + \PValue{tocnumwidth} & \PValue{5em}\\ + \PValue{tocstyle} & \PValue{section} \\ + \bottomrule + \end{tabularx} \\ + \addlinespace[\normalbaselineskip] + \DescRef{maincls.cmd.subparagraph}: \\* + \begin{tabularx}{\linewidth}{ll} + \toprule + Attribute & Default Value \\ + \midrule\nopagebreak + \PValue{afterskip} & \PValue{-1em} \\ + \PValue{beforeskip} & \PValue{3.25ex plus 1ex minus .2ex} \\ + \PValue{font} & see element + \DescRef{maincls.fontelement.subparagraph}, + \autoref{tab:maincls.structureElementsFont}, + \autopageref{tab:maincls.structureElementsFont} \\ + \PValue{indent} & \Macro{scr@parindent} \\ + \PValue{level} & 5 \\ + \PValue{tocindent} & \PValue{12em}\\ + \PValue{toclevel} & 5 \\ + \PValue{tocnumwidth} & \PValue{6em}\\ + \PValue{tocstyle} & \PValue{section} \\ + \bottomrule + \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 + + +\begin{Declaration} + \Macro{DeclareSectionCommands}\OParameter{attributes} + \Parameter{list of names}% + \Macro{DeclareNewSectionCommands}\OParameter{attributes} + \Parameter{list of names}% + \Macro{RedeclareSectionCommands}\OParameter{attributes} + \Parameter{list of names}% + \Macro{ProvideSectionCommands}\OParameter{attributes} + \Parameter{list of names} +\end{Declaration} +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{IfSectionCommandStyleIs}\Parameter{name}\Parameter{style} + \Parameter{then code}\Parameter{else code} +\end{Declaration} +In\ChangedAt{v3.27}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} +rare cases, it is useful to be able to test whether a sectioning command +belongs to a specific \PName{style}. If \KOMAScript{} has defined the +sectioning command \Macro{\PName{name}} using the given \PName{style}, the +\PName{then code} will be used. Otherwise the \PName{else code} will be +executed. An error is reported if \Macro{\PName{name}} is undefined or if it +is not a \KOMAScript{} sectioning command.% +\EndIndexGroup + + +\begin{Declaration} + \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}\\ + \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} +is also used between the number line and the heading text. + +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}. The +\Macro{partheademptypage}\ChangedAt{v3.02}{\Class{scrbook}\and +\Class{scrreprt}} command produces an empty page after the part heading page +of \Class{scrbook} and \Class{scrreprt}. + +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 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} +These defaults are reactivated every time you use +\OptionValueRef{maincls}{headings}{big}\IndexOption{headings}, +\OptionValueRef{maincls}{headings}{normal}, or +\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 + } + \newcommand*{\partheadmidvskip}{% + \par\nobreak + \vskip\@tempskipa + } + \newcommand*{\partheadendvskip}{% + \vskip\@tempskipa\newpage + } +\end{lstcode} +and of \Class{scrartcl}: +\begin{lstcode} + \newcommand*{\partheadstartvskip}{% + \addvspace{\@tempskipa}% + } + \newcommand*{\partheadmidvskip}{% + \par\nobreak + } + \newcommand*{\partheadendvskip}{% + \vskip\@tempskipa + } +\end{lstcode} +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 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 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}} 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 \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\textnote{default} defaults for these commands are: +\begin{lstcode} + \newcommand{\chapterlinesformat}[3]{% + \@hangfrom{#2}{#3}% + } + \newcommand{\chapterlineswithprefixformat}[3]{% + #2#3% + } +\end{lstcode} + +\begin{Example} + You want to have chapter headings with yellow background. For the headings + without a prefix line, you use the following definition in the document + preamble: +\begin{lstcode} + \makeatletter + \renewcommand{\chapterlinesformat}[3]{% + \colorbox{yellow}{% + \parbox{\dimexpr\linewidth-2\fboxrule-2\fboxsep}{% + \@hangfrom{#2}#3% + }% + }% + } + \makeatother +\end{lstcode} + For chapter headings with prefix line, you use: +\begin{lstcode} + \renewcommand{\chapterlineswithprefixformat}[3]{% + \colorbox{yellow}{% + \parbox{\dimexpr\linewidth-2\fboxrule-2\fboxsep}{% + #2#3% + }% + }% + } +\end{lstcode} + 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 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 + \Macro{chapterlinesformat}: +\begin{lstcode} + \makeatletter + \renewcommand{\chapterlinesformat}[3]{% + \colorbox{yellow}{% + \parbox{\dimexpr\linewidth-2\fboxrule-2\fboxsep}{% + \raggedchapter + \@hangfrom{#2}#3% + }% + }% + } + \makeatother + \renewcommand{\chapterlineswithprefixformat}[3]{% + \colorbox{yellow}{% + \parbox{\dimexpr\linewidth-2\fboxrule-2\fboxsep}{% + \raggedchapter + #2#3% + }% + }% + } +\end{lstcode} + 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 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}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{sectionlinesformat}% + \Parameter{level}\Parameter{indent}\Parameter{number}\Parameter{text}% + \Macro{sectioncatchphraseformat}% + \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 the \PValue{section} +style depending on whether the heading 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 can +protrude into the left margin. + +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} +\newcommand{\sectionlinesformat}[4]{% + \@hangfrom{\hskip #2#3}{#4}% +} +\newcommand{\sectioncatchphraseformat}[4]{% + \hskip #2#3#4% +} +\end{lstcode} + +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} + 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]{% + \@tempswafalse + \Ifstr{#1}{section}{% + \hspace*{#2}% + \colorbox{yellow}{% + \parbox{\dimexpr\linewidth-2\fboxrule-2\fboxsep-#2}{% + \raggedsection + \@hangfrom{#3}{#4}% + }% + }% + }{% + \@hangfrom{\hskip #2#3}{#4}% + }% + } + \makeatother +\end{lstcode} + 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 +example shows how to use it to distinguish different heading levels of the +same style \PValue{section}.% +\EndIndexGroup + + +\begin{Declaration} +\DoHook{heading/preinit/\PName{name}}% +\DoHook{heading/postinit/\PName{name}}% +\DoHook{heading/branch/star/\PName{name}}% +\DoHook{heading/branch/nostar/\PName{name}}% +\DoHook{heading/begingroup/\PName{name}}% +\DoHook{heading/endgroup/\PName{name}}% +\end{Declaration} +\BeginIndex{}{hooks}% +In\ChangedAt[2019/01]{v3.27}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} addition to all their attributes, +\DescRef{\LabelBase.cmd.DeclareSectionCommand}, +\DescRef{\LabelBase.cmd.DeclareNewSectionCommand}, +\DescRef{\LabelBase.cmd.ProvideSectionCommand} and +\DescRef{\LabelBase.cmd.RedeclareSectionCommand} provide several hooks in +sectioning commands that can be manipulated using +\DescRef{scrbase.cmd.AddtoDoHook}. For information about the functionality of +these \emph{do-hooks} see \autoref{sec:scrbase.hooks}, +\autopageref{sec:scrbase.hooks}. The last element of the specifier is the +\PName{name} of the sectioning command, as it is for the declaration commands +mentioned above. + +It is important\important{Attention!} to avoid adding code to these hooks that +would affect the page breaking or the position of the heading. Therefore only +advanced users should use these hooks. In case of doubt, refer to the class's +source code for information about exactly when a hook is executed. These hooks +serve as a fallback before you indeed would need to resort to redefining +a section command without using \KOMAScript{} features. + +The\textnote{\DoHHook{\dits/preinit/\dots}} hook +\DoHook{heading/preinit/\PName{name}} is executed immediately before the +sectioning command is initialised. At this point, no settings have been +initialised. Even the paragraph that precedes the heading is not +necessarily finished yet. + +The\textnote{\DoHook{\dots/postinit/\dots}} hook +\DoHook{heading/postinit/\PName{name}} is executed somewhat later. At this +point, some settings have been initialised and the previous paragraph has +already ended. + +Only\textnote{\DoHook{\dots/branch/\dots}} one of the hooks +\DoHook{heading/branch/nostar/\PName{name}} or +\DoHook{heading/branch/star/\PName{name}} is executed, after determining +whether the starred or normal variant of the section command is used. At this +point, the vertical gap above the heading has already been inserted. + +The\textnote{\DoHook{\dots/begingroup/\dots}} hook +\DoHook{heading/begingroup/\PName{name}} is executed at the beginning of +the group used to process the heading. This is also the last opportunity to +intervene before the heading is printed. + +Similarly\textnote{\DoHook{\dots/begingroup/\dots}}, the hook +\DoHook{heading/begingroup/\PName{name}} will be executed at the end of the +group used to process the heading. Currently this is the last hook inside +a section command. + +Note\textnote{\DescRef{maincls.cmd.minisec}} that +\DescRef{maincls.cmd.minisec} is not a real sectioning command and therefore +these hooks are not available for it.% +\EndIndexGroup + +\begin{Declaration} + \Macro{IfUseNumber}\Parameter{then code}\Parameter{else code} +\end{Declaration} +Strictly\ChangedAt{v3.27}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} speaking, this is an internal command. It is defined +inside sectioning commands only between the \DoHook{\dots/begingroup/\dots} +and \DoHook{\dots/endgroup/\dots} hooks. In this case, the +\Parameter{then code} is executed if the sectioning heading uses the non-star +variant and should be numbered according to the value of +\DescRef{maincls.counter.secnumdepth}. If the heading should not be numbered +because the sectioning command uses the star variant or because of the value +of \DescRef{maincls.counter.secnumdepth}, the \PName{else code} is executed. +Headings in the \PValue{chapter} style also take into account whether +the headings appears in the main matter. + +If you use the command outside a sectioning command, the result is +unspecified. In this case, it will usually result in an error message and +execute neither the \PName{then code} nor the \PName{else code}.% +\EndIndexGroup + +\begin{Declaration} + \Macro{SecDef}\Parameter{star command}\Parameter{command}% + \Macro{scr@startsection}\Parameter{name}\Parameter{level}\Parameter{indent}% + \Parameter{beforeskip}\Parameter{afterskip}% + \Parameter{style commands}% + \OParameter{short version}\Parameter{heading}% + \labelsuffix[*]% + \Macro{scr@startsection}\Parameter{name}\Parameter{level}\Parameter{indent}% + \Parameter{beforeskip}\Parameter{afterskip}% + \Parameter{style commands}% + \PValue{*}\Parameter{heading}% + \labelsuffix% +\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. To achieve this, it was necessary +to replace some \LaTeX{} kernel commands: +\begin{itemize} +\item Instead of + \Macro{@startsection}\IndexCmd{@startsection}\important{\Macro{@startsection}} + \KOMAScript{} uses \Macro{scr@startsection}. However, the definition of + \Macro{@startsection} is checked. If the implementation differs from the + expected one, a warning is issued, several features of \KOMAScript{} + are deactivated, and \Macro{scr@startsection} uses a copy of + \Macro{@startsection} while \Macro{@startsection} is redefined to use + \Macro{scr@startsection}. +\item Instead of \Macro{@dblarg}\IndexCmd{@dblarg}\important{\Macro{@dblarg}} + \KOMAScript{} uses an internal command to define sectioning commands. +\item Instead of \Macro{secdef}\IndexCmd{secdef}\important{\Macro{secdef}}, + \KOMAScript{} uses \Macro{SecDef} to change \Macro{@dblarg} as + mentioned above. If the implementation of \Macro{secdef} differs from the + expected one, a warning is issued. +\item \Macro{@sect}\IndexCmd{@sect}\important{\Macro{@sect}} is redefined to + implement various extensions of \KOMAScript. +\item \Macro{@ssect}\IndexCmd{@ssect}\important{\Macro{@ssect}} is redefined + to implement various extensions of \KOMAScript. +\item \Macro{@xsect}\IndexCmd{@xsect}\important{\Macro{@xsect}} is redefined + to implement various extensions of \KOMAScript. +\end{itemize} +In future versions of \KOMAScript{}, consideration is being given to avoid +changing the \LaTeX{} kernel commands mentioned above and to replace them +completely with custom, internal commands. Loading truly incompatible +sectioning packages would automatically disable \KOMAScript{} extensions +and transfer the responsibility for the sectioning commands entirely +to these packages. On the other hand, extra effort would be required +to maintain compatibility with other packages. + +Package 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. The meaning of the parameters for these +commands can be found in the \LaTeX{} kernel manual \cite{latex:source2e}. +As\ChangedAt[2019/01]{v3.27}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} an alternative to redefining such commands, \KOMAScript{} +offers the hooks described previously.% +\EndIndexGroup + +\begin{Explain} + \begin{Declaration} + \Macro{At@startsection}\Parameter{code} + \Macro{Before@ssect}\Parameter{code} + \Macro{Before@sect}\Parameter{code} + \end{Declaration} + Until\ChangedAt[2019/01]{v3.27}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} \KOMAScript~v3.26b, these commands were available as an + alternative to redefine \DescRef{\LabelBase.cmd.scr@startsection} or + \DescRef{\LabelBase.cmd.SecDef}. Since\textnote{outdated \KOMAScript{} + command} \KOMAScript~v3.27, these commands are deprecated. + + Internally \Macro{At@startsection} is now implemented with the + \DescRef{\LabelBase.dohook.heading/postinit} hook. \Macro{Before@ssect} is + implemented with \DescRef{\LabelBase.dohook.heading/branch/star}, and + \Macro{Before@sect} uses + \DescRef{\LabelBase.dohook.heading/branch/nostar}. The \PName{code} is added + using \DescRef{scrbase.cmd.AddtoDoHook}. There are no provisions to remove + this code once it has been added.% + \EndIndexGroup +\end{Explain} + +% \section{Appendix} +% \seclabel{appendix} + + +\begin{Declaration} + \Macro{appendixmore} +\end{Declaration}% +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 +\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 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}{% + \renewcommand*{\chapterformat}{% + \appendixname~\thechapter\autodot\enskip} + \renewcommand*{\chaptermarkformat}{% + \appendixname~\thechapter\autodot\enskip} + } +\end{lstcode} +% + In case you subsequently change your mind and decide to use the option + \DescRef{maincls.option.appendixprefix} at a later stage, you will get an + error message because of the already defined \Macro{appendixmore} command. + 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 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}{% + \renewcommand*{\sectionformat}{% + \appendixname~\thesection\autodot\enskip}% + \renewcommand*{\sectionmarkformat}{% + \appendixname~\thesection\autodot\enskip}} +\end{lstcode} + + The redefined commands are explained in more detail in + \autoref{sec:maincls.structure}, + \DescPageRef{maincls.cmd.chapterformat} and + \DescPageRef{maincls.cmd.chaptermarkformat}. +\end{Example} +% +\EndIndexGroup + + +\section{Bibliography} +\seclabel{bibliography} + +The information in this section is less important if you use packages like +\Package{biblatex}. In that case, the extensive features of such packages +will supersede the extensions of the \KOMAScript{} classes described here. + +\begin{Declaration} + \Macro{newbibstyle}\OParameter{parent style}\Parameter{name}%^^A + \Parameter{commands}% + \Macro{newblock}% + \Macro{@openbib@code}% + \Macro{bib@beginhook}% + \Macro{bib@endhook} +\end{Declaration} +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}} option, the +\PName{commands} will be executed immediately. This will redefine +\Macro{@openbib@code} and \Macro{newblock}. + +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}) 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 \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, before \Macro{bib@endhook}. + +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 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} +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 + + +\section{More or Less Obsolete Options and Commands} +\seclabel{obsolete} + +\LoadNonFree{scrbookreportarticle-experts}{4} +% +\EndIndexGroup + +\endinput + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "scrguide-en.tex" +%%% coding: utf-8 +%%% ispell-local-dictionary: "en_GB" +%%% eval: (flyspell-mode 1) +%%% End: |