summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/source-doc/english/scrbookreportarticle-experts.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/koma-script/source-doc/english/scrbookreportarticle-experts.tex')
-rw-r--r--macros/latex/contrib/koma-script/source-doc/english/scrbookreportarticle-experts.tex295
1 files changed, 213 insertions, 82 deletions
diff --git a/macros/latex/contrib/koma-script/source-doc/english/scrbookreportarticle-experts.tex b/macros/latex/contrib/koma-script/source-doc/english/scrbookreportarticle-experts.tex
index 1629f29923..247aaf6f02 100644
--- a/macros/latex/contrib/koma-script/source-doc/english/scrbookreportarticle-experts.tex
+++ b/macros/latex/contrib/koma-script/source-doc/english/scrbookreportarticle-experts.tex
@@ -48,13 +48,13 @@
% ============================================================================
\KOMAProvidesFile{scrbookreportarticle-experts.tex}
- [$Date: 2019-01-15 08:29:44 +0100 (Tue, 15 Jan 2019) $
+ [$Date: 2019-10-09 16:34:25 +0200 (Wed, 09 Oct 2019) $
KOMA-Script guide (chapter: scrbook, scrreprt, scrartcl for
experts)]
\translator{Gernot Hassenpflug\and Markus Kohm\and Karl Hagen}
-% Date of the translated German file: 2018-10-14
+% Date of the translated German file: 2019-10-09
\chapter[{Additional Information about the Main Classes and
\Package{scrextend}}]{Additional Information about the Main Classes
@@ -62,7 +62,8 @@
\Class{scrreprt}, and \Class{scrartcl} as well as the Package
\Package{scrextend}}
\labelbase{maincls-experts}
-\BeginIndexGroup
+
+\BeginIndexGroup%
\BeginIndex{Class}{scrartcl}%
\BeginIndex{Class}{scrbook}%
\BeginIndex{Class}{scrreprt}%
@@ -74,12 +75,14 @@ are also available in \Package{scrextend}. \iffree{Some parts of the chapter
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.
+their own classes based on a \KOMAScript{} class. Because such descriptions
+are not addressed to beginners, they are condensed and require deeper
+knowledge of \LaTeX. Other parts describe features that exist only for the
+sake of compatibility with the standard classes or earlier versions of
+\KOMAScript{}.\iffree{}{
+ Portions that describe features that exist only for reasons of compatibility
+ with earlier versions of \KOMAScript{} are printed in sans serif font. You
+ should not use them any longer.}
\LoadNonFree{scrbookreportarticle-experts}{0}
@@ -95,15 +98,14 @@ longer.
\LoadNonFree{scrbookreportarticle-experts}{2}
-\section{Expert Commands}
-\seclabel{experts}
-
-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.
+\section{Detection of \KOMAScript{} Classes}
+\seclabel{identify}
-% \subsection{Identification}
-% \seclabel{identification}
+Package authors sometimes need to detect a \KOMAScript{} class. Mostly this is
+of little or no interest to the average user. To identify the version of
+\KOMAScript{} that is being used, refer to
+\DescRef{scrbase.cmd.KOMAScriptVersion} in \autoref{sec:scrbase.identify},
+\DescPageRef{scrbase.cmd.KOMAScriptVersion}.
\begin{Declaration}
\Macro{KOMAClassName}%
@@ -122,8 +124,14 @@ the \KOMAScript{} label using this name.%
%
\EndIndexGroup
-% \subsection{Entries to the Table of Contents}
-% \seclabel{toc}
+\section{Entries to the Table of Contents}
+\seclabel{toc}
+
+\KOMAScript{} classes provide advanced methods for generating and
+manipulating entries in the table of contents. Some of these are based on
+the \Package{tocbasic} package (see \autoref{sec:tocbasic.tocstyle} starting
+on \autopageref{sec:tocbasic.tocstyle}). Other are implemented directly in the
+classes.
\begin{Declaration}
\Macro{addtocentrydefault}\Parameter{level}\Parameter{number}%
@@ -236,9 +244,12 @@ rather than attempting to set the attribute for specific entry levels.%
\EndIndexGroup
-% \subsection{Font Settings}
-% \seclabel{fonts}
+\section{Font Settings}
+\seclabel{fonts}
+\KOMAScript{} classes not only provide an extended selection of basic font
+sizes, but they also let you define, manipulate, and apply elements with
+their own font settings.
\begin{Declaration}
\Macro{@fontsizefilebase}%
@@ -387,8 +398,14 @@ undefined elements as well as for elements defined with
\PName{else code}.%
\EndIndexGroup
-% \subsubsection{Paragraph Indention or Gap}
-% \seclabel{parskip}
+\section{Paragraph Indention or Gap}
+\seclabel{parskip}
+
+Because the \KOMAScript{} classes offer extended features for setting the
+paragraph indention or gap, direct changes of the standard lengths
+\Length{parskip}\IndexLength{parskip}, \Length{parindent}\IndexLength{parskip}
+and \Length{parfillskip}\IndexLength{parskip} are not only unnecessary but
+mostly inadvisable.
\begin{Declaration}
\Macro{setparsizes}\Parameter{indent}\Parameter{distance}
@@ -428,13 +445,17 @@ disables this recalculation.%
%
\EndIndexGroup
-% \subsection{Counters}
-% \seclabel{counter}
+\section{Counters}
+\seclabel{counter}
\LoadNonFree{scrbookreportarticle-experts}{3}
-% \subsubsection{Sections}
-% \seclabel{sections}
+\section{Sections}
+\seclabel{sections}
+
+The \KOMAScript{} classes provide a wide range of options for modifying
+sectioning levels and their corresponding headings. You can even define new
+levels.
\begin{Declaration}
\Macro{DeclareSectionCommand}\OParameter{attributes}\Parameter{name}%
@@ -526,9 +547,9 @@ its font settings using \DescRef{maincls.cmd.setkomafont} or
the value of \PName{counter name}, the value of the counter of this
heading is reset to 0. In addition, \Macro{the\PName{counter name}} is
prefixed with a dot when this counter is output.\\
+ \PValue{counterwithout}%
\ChangedAt{v3.19}{\Class{scrbook}\and \Class{scrreprt}\and
\Class{scrartcl}}%
- \PValue{counterwithout}
& \PName{counter name}
& Cancels a prior \PValue{counterwithin} setting. Therefore it makes sense
only if you redefine an existing sectioning command.\\
@@ -1128,8 +1149,21 @@ 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.
-%
+assumed.%
+\EndIndexGroup
+
+
+\begin{Declaration}
+ \Macro{IfSectionCommandStyleIs}\Parameter{name}\Parameter{style}
+ \Parameter{then code}\Parameter{else code}
+\end{Declaration}
+In\ChangedAt{v3.27}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}
+rare cases, it is useful to be able to test whether a sectioning command
+belongs to a specific \PName{style}. If \KOMAScript{} has defined the
+sectioning command \Macro{\PName{name}} using the given \PName{style}, the
+\PName{then code} will be used. Otherwise the \PName{else code} will be
+executed. An error is reported if \Macro{\PName{name}} is undefined or if it
+is not a \KOMAScript{} sectioning command.%
\EndIndexGroup
@@ -1533,6 +1567,87 @@ same style \PValue{section}.%
\begin{Declaration}
+\DoHook{heading/preinit/\PName{name}}%
+\DoHook{heading/postinit/\PName{name}}%
+\DoHook{heading/branch/star/\PName{name}}%
+\DoHook{heading/branch/nostar/\PName{name}}%
+\DoHook{heading/begingroup/\PName{name}}%
+\DoHook{heading/endgroup/\PName{name}}%
+\end{Declaration}
+\BeginIndex{}{hooks}%
+In\ChangedAt[2019/01]{v3.27}{\Class{scrbook}\and \Class{scrreprt}\and
+ \Class{scrartcl}} addition to all their attributes,
+\DescRef{\LabelBase.cmd.DeclareSectionCommand},
+\DescRef{\LabelBase.cmd.DeclareNewSectionCommand},
+\DescRef{\LabelBase.cmd.ProvideSectionCommand} and
+\DescRef{\LabelBase.cmd.RedeclareSectionCommand} provide several hooks in
+sectioning commands that can be manipulated using
+\DescRef{scrbase.cmd.AddtoDoHook}. For information about the functionality of
+these \emph{do-hooks} see \autoref{sec:scrbase.hooks},
+\autopageref{sec:scrbase.hooks}. The last element of the specifier is the
+\PName{name} of the sectioning command, as it is for the declaration commands
+mentioned above.
+
+It is important\important{Attention!} to avoid adding code to these hooks that
+would affect the page breaking or the position of the heading. Therefore only
+advanced users should use these hooks. In case of doubt, refer to the class's
+source code for information about exactly when a hook is executed. These hooks
+serve as a fallback before you indeed would need to resort to redefining
+a section command without using \KOMAScript{} features.
+
+The\textnote{\DoHHook{\dits/preinit/\dots}} hook
+\DoHook{heading/preinit/\PName{name}} is executed immediately before the
+sectioning command is initialised. At this point, no settings have been
+initialised. Even the paragraph that precedes the heading is not
+necessarily finished yet.
+
+The\textnote{\DoHook{\dots/postinit/\dots}} hook
+\DoHook{heading/postinit/\PName{name}} is executed somewhat later. At this
+point, some settings have been initialised and the previous paragraph has
+already ended.
+
+Only\textnote{\DoHook{\dots/branch/\dots}} one of the hooks
+\DoHook{heading/branch/nostar/\PName{name}} or
+\DoHook{heading/branch/star/\PName{name}} is executed, after determining
+whether the starred or normal variant of the section command is used. At this
+point, the vertical gap above the heading has already been inserted.
+
+The\textnote{\DoHook{\dots/begingroup/\dots}} hook
+\DoHook{heading/begingroup/\PName{name}} is executed at the beginning of
+the group used to process the heading. This is also the last opportunity to
+intervene before the heading is printed.
+
+Similarly\textnote{\DoHook{\dots/begingroup/\dots}}, the hook
+\DoHook{heading/begingroup/\PName{name}} will be executed at the end of the
+group used to process the heading. Currently this is the last hook inside
+a section command.
+
+Note\textnote{\DescRef{maincls.cmd.minisec}} that
+\DescRef{maincls.cmd.minisec} is not a real sectioning command and therefore
+these hooks are not available for it.%
+\EndIndexGroup
+
+\begin{Declaration}
+ \Macro{IfUseNumber}\Parameter{then code}\Parameter{else code}
+\end{Declaration}
+Strictly\ChangedAt{v3.27}{\Class{scrbook}\and \Class{scrreprt}\and
+ \Class{scrartcl}} speaking, this is an internal command. It is defined
+inside sectioning commands only between the \DoHook{\dots/begingroup/\dots}
+and \DoHook{\dots/endroup/\dots} hooks. In this case, the
+\Parameter{then code} is executed if the sectioning heading uses the non-star
+variant and should be numbered according to the value of
+\DescRef{maincls.counter.secnumdepth}. If the heading should not be numbered
+because the sectioning command uses the star variant or because of the value
+of \DescRef{maincls.counter.secnumdepth}, the \PName{else code} is executed.
+Headings in the \PValue{chapter} style also take into account whether
+the headings appears in the main matter.
+
+If you use the command outside a sectioning command, the result is
+unspecified. In this case, it will usually result in an error message and
+execute neither the \PName{then code} nor the \PName{else code}.%
+\EndIndexGroup
+
+\begin{Declaration}
\Macro{SecDef}\Parameter{star command}\Parameter{command}%
\Macro{scr@startsection}\Parameter{name}\Parameter{level}\Parameter{indent}%
\Parameter{beforeskip}\Parameter{afterskip}%
@@ -1544,65 +1659,77 @@ same style \PValue{section}.%
\Parameter{style commands}%
\PValue{*}\Parameter{heading}%
\labelsuffix%
- \Macro{At@startsection}\Parameter{code}%
- \Macro{Before@ssect}\Parameter{code}%
- \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. 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}.
-
-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 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
+to replace some \LaTeX{} kernel commands:
+\begin{itemize}
+\item Instead of
+ \Macro{@startsection}\IndexCmd{@startsection}\important{\Macro{@startsection}}
+ \KOMAScript{} uses \Macro{scr@startsection}. However, the definition of
+ \Macro{@startsection} is checked. If the implementation differs from the
+ expected one, a warning is issued, several features of \KOMAScript{}
+ are deactivated, and \Macro{scr@startsection} uses a copy of
+ \Macro{@startsection} while \Macro{@startsection} is redefined to use
+ \Macro{scr@startsection}.
+\item Instead of \Macro{@dblarg}\IndexCmd{@dblarg}\important{\Macro{@dblarg}}
+ \KOMAScript{} uses an internal command to define sectioning commands.
+\item Instead of \Macro{secdef}\IndexCmd{secdef}\important{\Macro{secdef}},
+ \KOMAScript{} uses \Macro{SecDef} to change \Macro{@dblarg} as
+ mentioned above. If the implementation of \Macro{secdef} differs from the
+ expected one, a warning is issued.
+\item \Macro{@sect}\IndexCmd{@sect}\important{\Macro{@sect}} is redefined to
+ implement various extensions of \KOMAScript.
+\item \Macro{@ssect}\IndexCmd{@ssect}\important{\Macro{@ssect}} is redefined
+ to implement various extensions of \KOMAScript.
+\item \Macro{@xsect}\IndexCmd{@xsect}\important{\Macro{@xsect}} is redefined
+ to implement various extensions of \KOMAScript.
+\end{itemize}
+In future versions of \KOMAScript{}, consideration is being given to avoid
+changing the \LaTeX{} kernel commands mentioned above and to replace them
+completely with custom, internal commands. Loading truly incompatible
+sectioning packages would automatically disable \KOMAScript{} extensions
+and transfer the responsibility for the sectioning commands entirely
+to these packages. On the other hand, extra effort would be required
+to maintain compatibility with other packages.
+
+Package authors can use these commands as they would use the corresponding
+\LaTeX{} kernel commands and therefore gain access to the additional features
+of \KOMAScript. However, these commands should not be redefined, as they may
changed at any time, and then this redefinition could compromise
-\KOMAScript{}'s functionality.
-
-\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.%
-%
+\KOMAScript{}'s functionality. The meaning of the parameters for these
+commands can be found in the \LaTeX{} kernel manual \cite{latex:source2e}.
+As\ChangedAt[2019/01]{v3.27}{\Class{scrbook}\and \Class{scrreprt}\and
+ \Class{scrartcl}} an alternative to redefining such commands, \KOMAScript{}
+offers the hooks described previously.%
\EndIndexGroup
-% \subsection{Appendix}
+\begin{Explain}
+ \begin{Declaration}
+ \Macro{At@startsection}\Parameter{code}
+ \Macro{Before@ssect}\Parameter{code}
+ \Macro{Before@sect}\Parameter{code}
+ \end{Declaration}
+ Until\ChangedAt[2019/01]{v3.27}{\Class{scrbook}\and \Class{scrreprt}\and
+ \Class{scrartcl}} \KOMAScript~v3.26b, these commands were available as an
+ alternative to redefine \DescRef{\LabelBase.cmd.scr@startsection} or
+ \DescRef{\LabelBase.cmd.SecDef}. Since\textnote{outdated \KOMAScript{}
+ command} \KOMAScript~v3.27, these commands are deprecated.
+
+ Internally \Macro{At@startsection} is now implemented with the
+ \DescRef{\LabelBase.dohook.heading/postinit} hook. \Macro{Before@ssect} is
+ implemented with \DescRef{\LabelBase.dohook.heading/branch/star}, and
+ \Macro{Before@sect} uses
+ \DescRef{\LabelBase.dohook.heading/branch/nostar}. The \PName{code} is added
+ using \DescRef{scrbase.cmd.AddtoDoHook}. There are no provisions to remove
+ this code once it has been added.%
+ \EndIndexGroup
+\end{Explain}
+
+% \section{Appendix}
% \seclabel{appendix}
@@ -1671,8 +1798,12 @@ realising it.
\EndIndexGroup
-% \subsection{Literaturverzeichnis}
-% \seclabel{bibliography}
+\section{Bibliography}
+\seclabel{bibliography}
+
+The information in this section is less important if you use packages like
+\Package{biblatex}. In that case, the extensive features of such packages
+will supersede the extensions of the \KOMAScript{} classes described here.
\begin{Declaration}
\Macro{newbibstyle}\OParameter{parent style}\Parameter{name}%^^A