diff options
author | Karl Berry <karl@freefriends.org> | 2019-10-13 21:40:52 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-10-13 21:40:52 +0000 |
commit | ed8702df3768e21a3ef87a2eec9ca8341aad9b7a (patch) | |
tree | d2eb8a06d685acdcb364d57efb2334dbd3b2914d /Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle-experts.tex | |
parent | 4b6c2d7660365ff9963bcecf7a802e8060eb1bbc (diff) |
koma-script (13oct19)
git-svn-id: svn://tug.org/texlive/trunk@52369 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle-experts.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle-experts.tex | 295 |
1 files changed, 213 insertions, 82 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 1629f299237..247aaf6f023 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 @@ -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 |