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