summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/doc/scrbookreportarticle-experts-en.tex
diff options
context:
space:
mode:
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.tex1894
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: