diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle.tex | 5322 |
1 files changed, 2937 insertions, 2385 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle.tex index c9c2fb5f163..c362c2d42c4 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrbookreportarticle.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.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. @@ -46,88 +46,78 @@ % ============================================================================ \KOMAProvidesFile{scrbookreportarticle.tex} - [$Date: 2017-05-31 11:06:42 +0200 (Wed, 31 May 2017) $ + [$Date: 2018-03-30 11:57:25 +0200 (Fri, 30 Mar 2018) $ KOMA-Script guide (chapter: scrbook, scrreprt, scrartcl)] \translator{Jens-Uwe Morawski\and Gernot Hassenpflug\and Markus Kohm\and - Krickette Murabayashi\and Jana Schubert\and Jens H\"uhne} + Krickette Murabayashi\and Jana Schubert\and Jens H\"uhne\and Karl Hagen} -% Date of the translated German file: 2017-05-31 +% Date of the translated German file: 2018-02-01 \chapter{The Main Classes: \Class{scrbook}, \Class{scrreprt}, and - \Class{scrartcl}} -\labelbase{maincls} + \Class{scrartcl}} +\labelbase{maincls}% \BeginIndexGroup \BeginIndex{Class}{scrbook}% \BeginIndex{Class}{scrreprt}% \BeginIndex{Class}{scrartcl}% -%\AddSeeIndex{command}{gen}{\GuidecmdIndexShort}{cmd}% <-- set automatically -\AddSeeIndex{macro}{gen}{\GuidecmdIndexShort}{cmd}% \AddSeeIndex{instruction}{gen}{\GuidecmdIndexShort}{cmd}% - +\AddSeeIndex{macro}{gen}{\GuidecmdIndexShort}{cmd}% The main classes of the {\KOMAScript} bundle are designed as counterparts to the standard {\LaTeX} classes. This means that the {\KOMAScript} bundle -contains replacements for the three standard classes: +contains replacements for the three standard classes, \Class{book}\IndexClass{book}, \Class{report}\IndexClass{report}, and \Class{article}\IndexClass{article}. There is also a replacement for the -standard class \Class{letter}\IndexClass{letter}. The document class for -letters is described in a separate chapter, because it is fundamentally +standard \Class{letter}\IndexClass{letter} class. The document class for +letters is described in a separate chapter because it is fundamentally different from the three main classes (see \autoref{cha:scrlttr2}). -\iffalse% Umbruchkorrekturtext - The names of the {\KOMAScript} classes are composed of the prefix - ``\texttt{scr}'' and the abbreviated name of the corresponding standard - class. In order to restrict the length of the names to eight letters, the - vowels, starting with the last one, are left off as necessary. The - \autoref{tab:\LabelBase.overview} shows an overview of the correspondence - between the standard classes and the {\KOMAScript} classes. -\fi - The simplest way to use a {\KOMAScript} class instead of a standard one is to -substitute the class name in the \verb|\documentclass| command according to -\autoref{tab:\LabelBase.overview}. For example, you may replace -\Macro{documentclass}\PParameter{book} by -\Macro{documentclass}\PParameter{scrbook}. Normally, the document should be -processed without errors by {\LaTeX}, just like before the substitution. The -look, however, should be different. Additionally, the {\KOMAScript} classes -provide new possibilities and options that are described in the following -sections. +substitute the class name in the \verb|\documentclass| command in accordance +with \autoref{tab:\LabelBase.overview}. For example, you can replace +\Macro{documentclass}\PParameter{book} with +\Macro{documentclass}\PParameter{scrbook}. Normally, {\LaTeX} should process +the document without errors, just as before the substitution. The layout, +however, should be different. Additionally, the {\KOMAScript} classes provide +new possibilities and options that are described in the following sections. \begin{table} % \centering - \KOMAoptions{captions=topbeside} - \setcapindent{0pt} + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% % \caption \begin{captionbeside} - [Class correspondence]{\label{tab:\LabelBase.overview}Correspondence between - standard classes and {\KOMAScript} classes}% and \Script{} styles.} - [l] - \begin{tabular}[t]{ll} - \toprule - standard class & {\KOMAScript} class \\%& \Script-Stil (\LaTeX2.09)\\ - \midrule - \Class{article} & \Class{scrartcl} \\%& \File{script\textunderscore s} \\ - \Class{report} & \Class{scrreprt} \\%& \File{script} \\ - \Class{book} & \Class{scrbook} \\%& \File{script} \\ - \Class{letter} & \Class{scrlttr2} \\%& \File{script\textunderscore l} \\ - \bottomrule - \end{tabular} + [Class correspondence]{\label{tab:\LabelBase.overview}Correspondence between + standard classes and {\KOMAScript} classes} + [l] + \begin{tabular}[t]{ll} + \toprule + standard class & \KOMAScript{} class \\%& \Script-Stil (\LaTeX2.09)\\ + \midrule + \Class{article} & \Class{scrartcl} \\%& \File{script\textunderscore s} \\ + \Class{report} & \Class{scrreprt} \\%& \File{script} \\ + \Class{book} & \Class{scrbook} \\%& \File{script} \\ + \Class{letter} & \Class{scrlttr2} \\%& \File{script\textunderscore l} \\ + \bottomrule + \end{tabular} \end{captionbeside} \end{table} -Allow me an observation before proceeding with the descriptions of the -options. It is often the case that at the beginning of a document one is often -unsure which options to choose for that specific document. Some options, for -instance the choice of paper size, may be fixed from the beginning. But -already the question of the size of the text area and the margins could be -difficult to answer initially. On the other hand, the main business of an -author\,---\,planning the document structure, writing the text, preparing -figures, tables, lists, index, and other data\,---\,should be almost -independent of those settings. As an author you should concentrate initially -on this work. When that is done, you can concentrate on the fine points of -presentation. Besides the choice of options, this means correcting -hyphenation, optimizing page breaks, and the placement of tables and figures. +Let me say something before describing the classes. When beginning to write a +document, you are often unsure which specific options to choose. Some +settings, for instance the choice of paper size, may be fixed in advance. But +even the question of the appropriate page layout could be difficult to answer +initially. On the other hand, these settings should be nearly irrelevant, in +the beginning, to the main business of an author: planning the document +structure, writing the text, preparing figures, tables, lists, index, and +other data. As an author, you should concentrate initially on the content. +When that is done, you can take on the fine points of presentation. In +addition to the choice of options, this includes correcting hyphenation, +optimizing page breaks, and placing tables and figures. + + +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \LoadCommonFile{options}% \section{Early or Late Selection of Options} @@ -138,46 +128,49 @@ hyphenation, optimizing page breaks, and the placement of tables and figures. \LoadCommonFile{typearea}% \section{Page Layout} \begin{Declaration} - \Macro{flushbottom}% + \Macro{flushbottom} \Macro{raggedbottom} \end{Declaration} \begin{Explain} - In double-sided documents, it's preferred to have the same visual baseline - in not only the first lines of the text areas in a double-side spread, but - also in the last lines. If pages consist of text without paragraphs or - headlines only, this is the result in general. But a paragraph distance of - half of a line would be enough to prevent achieving this, if the difference - in the number of paragraphs on each page of the double-page spread is - odd-numbered. In this case at least some of the paragraph distances need to - be shrunk or stretched to fit the rule again. \TeX{} knows shrinkable and - stretchable distances for this purpose. \LaTeX{} provides an automatism for - this kind of vertical adjustment\Index{adjustment>vertical}. + In two-sided documents especially, it is preferable to have the same visual + baseline not only for the first lines of each text area in a two-page spread + but also for the last lines. If a page consists only of text without + paragraphs or headings, this is generally the result. But a paragraph + spacing of half a line would be enough to prevent you from achieving this + goal if the number of paragraphs on each page of the two-page spread differs + by an odd number. In this case, at least some of the paragraph distances + need to be stretched or shrunk to reach the target again. \TeX{} defines + stretchable and shrinkable distances for this purpose, and \LaTeX{} lets you + perform this kind of \emph{vertical adjustment}\Index{adjustment} + automatically. \end{Explain} -Using double-sided typesetting with option -\Option{twoside}\IndexOption{twoside}\important{\Option{twoside}} (see +Using two-sided printing with the +\Option{twoside}\IndexOption{twoside}\important{\Option{twoside}} option (see \autoref{sec:typearea.options}, \DescPageRef{typearea.option.twoside}) or -two-column typesetting with option -\Option{twocolumn}\IndexOption{twocolumn}\important{\Option{twocolumn}} (see -\DescPageRef{typearea.option.twocolumn}) switches on vertical adjustment -also. But\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} with compatibility selection to a \KOMAScript{} version -prior to 3.17 (see \autoref{sec:\LabelBase.compatibilityOptions}, +two-column formatting with the +\Option{twocolumn}\IndexOption{twocolumn}\important{\Option{twocolumn}} option +(see \DescPageRef{typearea.option.twocolumn}) also activates this vertical +adjustment. But\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} this does not apply with a compatibility setting for a +\KOMAScript{} version prior to 3.17 (see +\autoref{sec:\LabelBase.compatibilityOptions}, \DescPageRef{\LabelBase.option.version}, option -\DescRef{\LabelBase.option.version}\IndexOption{version}\important{\OptionValueRef{\LabelBase}{version}{3.17}}) -this is not the case, if you use \DescRef{\LabelBase.cmd.KOMAoption} or \DescRef{\LabelBase.cmd.KOMAoptions} to +\DescRef{\LabelBase.option.version}\IndexOption{version}% +\important{\OptionValueRef{\LabelBase}{version}{3.17}}) if you use +\DescRef{\LabelBase.cmd.KOMAoption} or \DescRef{\LabelBase.cmd.KOMAoptions} to change the setting of these options. -Alternatively, vertical adjustment may be switched on -at any time valid from the current page using -\Macro{flushbottom}. \Macro{raggedbottom} would have the opposite -effect, switching off vertical adjustment from the current page -on. This is also the default at one-sided typesetting. +You can also explicitly request vertical adjustment at any time starting with +the current page by using \Macro{flushbottom}. \Macro{raggedbottom} has the +opposite effect, switching off vertical adjustment starting with the current +page. This corresponds to the default for one-sided printing. -By the way, \KOMAScript{} uses a slightly modified kind of abdication of -vertical adjustment. This has been done to move footnotes to the bottom of the -text area instead of having them close to the last used text line.\iffree{}{ - More information about this may be found at +By the way, \KOMAScript{} uses a slightly modified method for adjusting the +vertical skip. This has been done to move footnotes to the bottom of the +text area instead of having them close to the last text line used. +\iffree{}{ + You can find more information about this at \autoref{sec:maincls-experts.addInfos}, \DescPageRef{maincls-experts.cmd.footnoterule}.}% % @@ -186,8 +179,7 @@ text area instead of having them close to the last used text line.\iffree{}{ \EndIndexGroup -\LoadCommonFile{fontsize} - +\LoadCommonFile{fontsize}% \section{Choosing the Document Font Size} \LoadCommonFile{textmarkup}% \section{Text Markup} @@ -196,38 +188,42 @@ text area instead of having them close to the last used text line.\iffree{}{ \section{Abstract} \seclabel{abstract} \BeginIndexGroup -\BeginIndex{}{summary}% \BeginIndex{}{abstract}% -Particularly\OnlyAt{\Class{scrartcl}\and\Class{scrreprt}} with -articles, more rarely with reports, there is a summary\Index{summary} -directly under the title and before the table of contents. When using an in-page -title, this summary is normally a kind of left- and right-indented block. In -contrast to this, a kind of chapter or section is printed using title pages. +Particularly with articles, more rarely with reports, there is an abstract, or +summary, directly beneath the title and before the table of contents. When +using an in-page title, this abstract is normally a kind of left- and +right-indented block. In comparison, the abstract appears as a chapter or +section when using title pages. \begin{Declaration} \OptionVName{abstract}{simple switch} \end{Declaration}% -In\ChangedAt{v3.00}{\Class{scrreprt}\and \Class{scrartcl}}% -\OnlyAt{\Class{scrreprt}\and\Class{scrartcl}} the standard classes the -\DescRef{\LabelBase.env.abstract} environment sets the text ``\abstractname'' centered -before the summary text\Index[indexmain]{summary}. This was normal practice in -the past. In the meantime, newspaper reading has trained readers to recognize -a displayed text at the beginning of an article or report as the -abstract. This is even more true when the text comes before the table of -contents. It is also surprising when precisely this title appears small and -centered. {\KOMAScript} provides the possibility of including or excluding the -abstract's title with the options \Option{abstract}. For \PName{simple - switch}, any value from -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} may be used. - -Books typically use another type of summary. In that case there is usually a -dedicated summary chapter at the beginning or end of the book. This chapter is -often combined with the introduction or a description of wider -prospects. Therefore, the class \Class{scrbook} has no \DescRef{\LabelBase.env.abstract} -environment. A\textnote{Hint!} summary chapter is also recommended for reports in a wider -sense, like a Master's or Ph.D. thesis.% -% +In\OnlyAt{\Class{scrreprt}\and\Class{scrartcl}} the standard +classes\textnote{\KOMAScript{} vs. standard classes}, the +\DescRef{\LabelBase.env.abstract} environment sets the text ``\abstractname'' +centred before the abstract text. This used to be the normal practice. Since +then, reading newspapers has trained us to recognize a suitably highlighted +text at the beginning of an article or report as the abstract. This is even +more true when the text comes before the table of contents. It is also +confusing if, of all things, this title appears small and centred. +{\KOMAScript}\ChangedAt{v3.00}{\Class{scrreprt}\and \Class{scrartcl}} offers +the option to include or exclude the abstract's title with the +\Option{abstract} option. For \PName{simple switch}, you can use any value +from \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. The +default for \KOMAScript{} is \PValue{false}. + +Books typically use a different kind of summary. There, you usually place an +appropriate chapter at the beginning or the end of the work. This chapter is +often combined with either the introduction or a description of a larger +prospectus. Therefore, the \Class{scrbook} class has no +\DescRef{\LabelBase.env.abstract} environment. A\textnote{Hint!} summary +chapter is also recommended for reports in a wider sense, such as a Master's +thesis or Ph.D. dissertation. See the commands +\DescRef{\LabelBase.cmd.chapter*}\IndexCmd{chapter*}, +\DescRef{\LabelBase.cmd.addchap}\IndexCmd{addchap}, and +\DescRef{\LabelBase.cmd.addchap*}\IndexCmd{addchap*} documented in +\autoref{sec:maincls.structure}, from \DescPageRef{\LabelBase.cmd.chapter*}.% \EndIndexGroup @@ -235,32 +231,32 @@ sense, like a Master's or Ph.D. thesis.% \begin{Environment}{abstract}\end{Environment} \end{Declaration}% \OnlyAt{\Class{scrartcl}\and \Class{scrreprt}}% -Some {\LaTeX} classes offer a special environment for this summary, the -\Environment{abstract} environment. This is output directly, as it is not a -component of the titles set by \DescRef{\LabelBase.cmd.maketitle}. -Please\textnote{Attention!} note that \Environment{abstract} is an -environment, not a command. Whether the summary has a heading or not is -determined by the option \DescRef{\LabelBase.option.abstract} (see above). - -With books (\Class{scrbook}) the summary is frequently a component of the -introduction or a separate chapter at the end of the document. Therefore no -\Environment{abstract} environment is provided. When using the class -\Class{scrreprt} it is surely worth considering whether one should not proceed -likewise. See commands \DescRef{\LabelBase.cmd.chapter*}\IndexCmd{chapter*} and -\DescRef{\LabelBase.cmd.addchap}\IndexCmd{addchap} or \DescRef{\LabelBase.cmd.addchap*} at -\autoref{sec:\LabelBase.structure} from \DescPageRef{\LabelBase.cmd.chapter*} -onwards. +Some {\LaTeX} classes provide a special environment for this summary: the +\Environment{abstract} environment. This is output directly, so it is not part +of the title created with \DescRef{\LabelBase.cmd.maketitle}. +Please\textnote{Attention!} note that \Environment{abstract} is an +environment, not a command. Whether the abstract has a heading or not is +determined by the \DescRef{\LabelBase.option.abstract} option (see above). + +For books, the abstract is usually part of the introduction or a separate +chapter at the end of the document. Therefore \Class{scrbook} does not provide +an \Environment{abstract} environment. When using the \Class{scrreprt} class, +it is definitely worth considering whether to proceed in the same way. See the +commands \DescRef{\LabelBase.cmd.chapter*}\IndexCmd{chapter*} and +\DescRef{\LabelBase.cmd.addchap}\IndexCmd{addchap}, or +\DescRef{\LabelBase.cmd.addchap*} in \autoref{sec:\LabelBase.structure} +from \DescPageRef{\LabelBase.cmd.chapter*} for more on this. When using an in-page title\Index{title>in-page} (see option \DescRef{\LabelBase.option.titlepage}, \autoref{sec:\LabelBase.titlepage}, -\DescPageRef{\LabelBase.option.titlepage}), the abstract is set using the -environment \Environment{quotation}\IndexEnv{quotation} (see -\autoref{sec:\LabelBase.lists}, \DescPageRef{\LabelBase.env.quotation}) -internally. Thereby paragraphs will be set with indentation of the first -line. If that first paragraph of the abstract should not be indented, this -indent may be disabled using -\Macro{noindent}\IndexCmd{noindent}\important{\Macro{noindent}} \iffree{just - after \Macro{begin}\PParameter{abstract}}{at the begin of the environment}.% +\DescPageRef{\LabelBase.option.titlepage}), the abstract is set internally +using the \DescRef{\LabelBase.env.quotation}\IndexEnv{quotation} environment +(see \autoref{sec:\LabelBase.lists}, \DescPageRef{\LabelBase.env.quotation}). +This way paragraphs will be set with the first line indented. If the first +paragraph of the abstract should not be indented, you can suppress this indent +by using \Macro{noindent}\IndexCmd{noindent}% +\important{\Macro{noindent}} \iffree{just after + \Macro{begin}\PParameter{abstract}}{at the beginning of the environment}.% % \EndIndexGroup % @@ -272,289 +268,339 @@ indent may be disabled using \BeginIndexGroup \BeginIndex{}{table of contents} -The table of contents is normally set after the document title and an -optional existing abstract. Often one may find additional lists of -floating environments, e.\,g., the list of tables and the list of -figures, after the table of contents (see +The title and optional abstract are normally followed by a table of contents. +Often you also find additional lists of the floating environments, such as +tables and figures, after the table of contents (see \autoref{sec:\LabelBase.floats}). +\iffalse% + Note that in addition to the options documented in this section, the + commands \DescRef{maincls-experts.cmd.DeclareSectionCommand}, + \DescRef{maincls-experts.cmd.DeclareNewSectionCommand}, + \DescRef{maincls-experts.cmd.RedeclareSectionCommand}, and + \DescRef{maincls-experts.cmd.ProvideSectionCommand} can also affect the + table of contents. See \autoref{sec:maincls-experts.experts}, + \DescPageRef{maincls-experts.cmd.DeclareSectionCommand}.% +\else% + In addition to the options documented in this section, the + \hyperref[cha:tocbasic]{\Package{tocbasic}}% + \important{\hyperref[cha:tocbasic]{\Package{tocbasic}}}% + \IndexPackage{tocbasic} package style selected and configured with + \DescRef{tocbasic.cmd.DeclareTOCStyleEntry}\IndexCmd{DeclareTOCStyleEntry}% + \important[O]{\DescRef{tocbasic.cmd.DeclareTOCStyleEntry}} (see + \DescPageRef{tocbasic.cmd.DeclareTOCStyleEntry}) also has a significant + impact on the appearance of the table of contents. Similarly, the commands + \DescRef{maincls-experts.cmd.DeclareSectionCommand}% + \important[O]{\DescRef{maincls-experts.cmd.DeclareSectionCommand}}% + \IndexCmd{DeclareSectionCommand}, + \DescRef{maincls-experts.cmd.ProvideSectionCommand}% + \IndexCmd{ProvideSectionCommand}, + \DescRef{maincls-experts.cmd.DeclareNewSectionCommand}% + \IndexCmd{DeclareNewSectionCommand} and + \DescRef{maincls-experts.cmd.RedeclareSectionCommand}% + \IndexCmd{RedeclareSectionCommand} documented in + \autoref{sec:maincls-experts.experts}, + \DescPageRef{maincls-experts.cmd.DeclareSectionCommand} can also affect the + table of contents.% +\fi + + \begin{Declaration} - \OptionVName{toc}{selection} + \OptionVName{toc}{setting} \end{Declaration} -\label{desc:\LabelBase.option.toc.listof}% -\label{desc:\LabelBase.option.toc.nolistof}% -\label{desc:\LabelBase.option.toc.listofnumbered}\nobreak -It is becoming increasingly common to find entries in the table of contents -for the lists of tables and figures, for the bibliography, and, sometimes, -even for the index. This is surely also related to the recent trend of putting -lists of figures and tables at the end of the document. Both lists are -similiar to the table of contents in structure and intention. I'm therefore -sceptical of this evolution. Since\important{\OptionValue{toc}{listof}} it -makes no sense to include only one of the lists of tables and figures in the -table of contents, there exists only one -\PName{selection}\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} \PValue{listof}\IndexOption{toc~=\PValue{listof}} that -causes entries for both types of lists to be included. This also includes any -lists produced with version~1.2e or later of the -\Package{float}\IndexPackage{float} package (see \cite{package:float}) or the -\Package{floatrow} (see \cite{package:floatrow}). -All\important{\OptionValue{toc}{listofnumbered}} these lists are unnumbered, -since they contain entries that reference other sections of the document. If -one wants to ignore this general agreement, one may use \PName{selection} -\PValue{listofnumbered}% -\IndexOption{toc~=\PValue{listofnumbered}}. - -\leavevmode\phantomsection\nobreak -\label{desc:\LabelBase.option.toc.index}\nobreak -The\important{\OptionValue{toc}{index}} option \OptionValue{index}{totoc} -causes an entry for the index to be included in the table of contents. The -index is unnumbered since it too only includes references to the contents of -the other sectional units. Despite\ChangedAt{v3.18}{\Class{scrbook}\and +It is becoming increasingly common to to include lists of tables and figures, +the bibliography, and sometimes even the index in the table of contents. This +is surely related to the recent trend of putting lists of figures and tables +at the end of the document. Both lists are similar to the table of contents in +structure and intention. I'm therefore sceptical of this evolution. +Since\important{\OptionValue{toc}{listof}} it makes no sense to include only +the list of tables or that of figures in the table of contents without the +other, there is only one \PName{setting}\ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} +\PValue{listof}\IndexOption{toc~=\textKValue{listof}}, which causes entries +for both types of lists to be included. This also includes any lists produced +with version~1.2e or later of the \Package{float} package\IndexPackage{float} +from Version~1.2e (see \cite{package:float}) or \Package{floatrow} (see +\cite{package:floatrow}). None\important{\OptionValue{toc}{listofnumbered}} +of these lists are generally given a chapter number. If you want to ignore +this principle, use the \PName{setting} +\PValue{listofnumbered}\IndexOption{toc~=\textKValue{listofnumbered}}. + +\leavevmode\LabelOptionValue{toc}{index}\nobreak +The\important{\OptionValue{toc}{index}} +\OptionValue{toc}{index}\IndexOption{toc~=\textKValue{index}} option causes an +entry for the index to be included in the table of contents. The index is +unnumbered since it too only includes references to the contents of the other +sectioning levels. Despite\ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -\important{\OptionValue{toc}{indexnumbered}}objection of the author, -\KOMAScript{} does also support to ignore this general agreement using -\OptionValue{toc}{indexnumbered}\IndexOption{toc~=\PValue{indexnumbered}}. - -\leavevmode\phantomsection\nobreak -\label{desc:\LabelBase.option.toc.bibliography}\nobreak -The bibliography is a different kind of listing. It does not list the contents -of the present document but refers instead to external -documents. For\important{\begin{tabular}{@{}r@{}} - \multicolumn{1}{@{}l@{}}{\Option{toc=}}\\ - ~\PValue{bibliographynumbered}\\ - \end{tabular}} that -reason, it could be argued that it qualifies as a chapter (or section) and, as -such, should be numbered. The option \OptionValue{toc}{bibliographynumbered}% -\IndexOption{toc~=\PValue{bibliographynumbered}} -has this effect, including the generation of the corresponding entry in the -table of contents. I personally think that this reasoning would lead us to -consider a classical list of sources also to be a separate chapter. On the -other hand, the bibliography is finally not something that was written by the -document's author. In\important{\OptionValue{toc}{bibliography}} view of this, the bibliography merits nothing more than -an unnumbered entry in the table of contents, and that can be achieved with -\OptionValue{toc}{bibliography}\IndexOption{toc~=\PValue{bibliography}}. - -\leavevmode\phantomsection\nobreak -\label{desc:\LabelBase.option.toc.graduated}\nobreak +\important{\OptionValue{toc}{indexnumbered}} the author's concerns, +\KOMAScript{} does support deviating from this principle with +\OptionValue{toc}{indexnumbered}\IndexOption{toc~=\textKValue{indexnumbered}}. + +\leavevmode\LabelOptionValue{toc}{bibliography}\nobreak The bibliography is a +slightly different kind of listing. It does not list the contents of the +present document but refers instead to external sources. +For\important{\OptionValue{toc}{bibliographynumbered}} that reason, it could +be argued that it qualifies as a chapter (or section) and, as such, should be +numbered. The \OptionValue{toc}{bibliographynumbered}% +\IndexOption{toc~=\textKValue{bibliographynumbered}} option has this effect, +and puts the appropriate entry in the table of contents. However, I think that +this reasoning would lead us to consider even a classic, annotated source list +to be a separate chapter. Moreover, the bibliography is ultimately not +something that you wrote yourself. +Therefore\important{\OptionValue{toc}{bibliography}} the bibliography merits, +at best, an unnumbered entry in the table of contents, and you can achieve +this achieved with +\OptionValue{toc}{bibliography}\IndexOption{toc~=\textKValue{bibliography}}. + +\leavevmode\LabelOptionValue{toc}{graduated}\nobreak The table of contents is normally\ChangedAt{v2.8q}{% \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% -\important{\OptionValue{toc}{graduated}} set up so that different sectional -units have different indentations. The section number is set left-justified in -a fixed-width field. This default setup is selected with the option -\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -\OptionValue{toc}{graduated}\IndexOption{toc~=\PValue{graduated}}. - -\leavevmode\phantomsection\nobreak -\label{desc:\LabelBase.option.toc.flat}\nobreak -When there are many sections, the corresponding numbering tends to become very -wide, so that the reserved field overflows. The German FAQ \cite{DANTE:FAQ} -suggests that the table of contents should be redefined in such a -case. {\KOMAScript}\important{\OptionValue{toc}{flat}} offers an alternative -format that avoids the problem completely. If the option -\OptionValue{toc}{flat}\IndexOption{toc~=\PValue{flat}} is selected, then no variable indentation is applied -to the titles of the sectional units. Instead, a table-like organisation is -used, where all unit numbers and titles, respectively, are set in a -left-justified column. The space necessary for the unit numbers is thus -determined automatically.% - -The \autoref{tab:\LabelBase.toc} shows an overview of possible values for -\PName{selection} of \Option{toc}. +\important{\OptionValue{toc}{graduated}} formatted so that different levels of +sectioning commands have different indentations. The number for each level is +set left-justified in a fixed-width field. This default set-up is selected +with the\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} +\OptionValue{toc}{graduated}\IndexOption{toc~=\textKValue{graduated}} option. + +\leavevmode\LabelOptionValue{toc}{flat}\nobreak +If the sectioning level which appears in the table of contents is too deep, the +number for that level can be so wide that the space reserved for the number is +insufficient. The German FAQ \cite{DANTE:FAQ} suggests redefining the table of +contents in such a case. \KOMAScript{}\important{\OptionValue{toc}{flat}} +offers an alternative format that avoids the problem completely. If you use +the \OptionValue{toc}{flat}\IndexOption{toc~=\textKValue{flat}} option, no +graduated indentation is applied to the headings of the sectioning levels. +Instead, a table-like organisation is used, where all sectioning numbers and +headings are set in a left-justified column. The space necessary for the +section numbers is thus determined automatically. + +You can find an overview of all available values for the \PName{setting} of +\Option{toc}. in \autoref{tab:\LabelBase.toc}. \begin{desclist} - \desccaption[{Possible values of option \Option{toc}}]{% - Possible values of option \Option{toc} to set form and contents of the - table of contents\label{tab:\LabelBase.toc}% + \desccaption[{Available values of the \Option{toc} option}]{% + Available values of the \Option{toc} option to set the format and contents + of the table of contents\label{tab:\LabelBase.toc}% }{% - Possible values of option \Option{toc} (\emph{continuation})% + Available values of the \Option{toc} option (\emph{continued})% }% \entry{\PValue{bibliography}, \PValue{bib}}{% - The bibliography will be represented by an entry at the table of contents, - but will not be numbered.% - \IndexOption{toc~=\PValue{bibliography}}}% + The bibliography has an unnumbered entry in the table of contents.% + \IndexOption{toc~=\textKValue{bibliography}}}% \entry{\PValue{bibliographynumbered}, \PValue{bibnumbered}, \PValue{numberedbibliography}, \PValue{numberedbib}}{% - The bibliography will be represented by an entry at the table of contents - and will be numbered.% - \IndexOption{toc~=\PValue{bibliographynumbered}}}% + The bibliography has a numbered entry in the table of contents.% + \IndexOption{toc~=\textKValue{bibliographynumbered}}}% \entry{\PValue{chapterentrywithdots}, \PValue{chapterentrydotfill}}{% \ChangedAt[2014/12]{v3.15}{\Class{scrbook}\and \Class{scrreprt}}% - The chapter entries of classes \Class{scrbook} and \Class{scrreprt} also - use dots to separate the headings text from the page number.% - \IndexOption{toc~=\PValue{chapterentrywithdots}}}% + The chapter entries for the \Class{scrbook} and \Class{scrreprt} classes + also use dots to separate the heading text from the page numbers.% + \IndexOption{toc~=\textKValue{chapterentrywithdots}}}% \entry{\PValue{chapterentrywithoutdots}, \PValue{chapterentryfill}}{% \ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}}% - The chapter entries of classes \Class{scrbook} and \Class{scrreprt} - use white space to separate the headings text from the page number.% - \IndexOption{toc~=\PValue{chapterentrywithoutdots}}}% + The chapter entries of the \Class{scrbook} and \Class{scrreprt} classes + use white space to separate the heading text from the page numbers. This + corresponds to the default setting.% + \IndexOption{toc~=\textKValue{chapterentrywithoutdots}}}% \entry{\PValue{flat}, \PValue{left}}{% - The table of contents will be set in table form. The numbers of the - headings will be at the first column, the heading text at the second - column, and the page number at the third column. The amount of space - needed for the numbers of the headings will be determined by the detected - needed amount of space at the previous \LaTeX{} run.% - \IndexOption{toc~=\PValue{flat}}}% + The table of contents is set in table form. The numbers of the headings + are in the first column, the heading text in the second column, and the + page number in the third column. The amount of space needed for the + numbers of the headings is determined by the required amount of space + detected during the previous \LaTeX{} run.% + \IndexOption{toc~=\textKValue{flat}}}% \entry{\PValue{graduated}, \PValue{indent}, \PValue{indented}}{% - The table of contents will be set in hierarchical form. The amount of - space for the heading numbers is limited.% - \IndexOption{toc~=\PValue{graduated}}}% + The table of contents is set in hierarchical form. The amount of space for + the heading numbers is limited. This corresponds to the default setting.% + \IndexOption{toc~=\textKValue{graduated}}}% + \entry{\PValue{indenttextentries}, \PValue{indentunnumbered}, + \PValue{numberline}}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The \PValue{numberline} property (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.setuptoc}) is set for the table of contents. As + a result, unnumbered entries are left aligned with the text of numbered + entries of the same level.% + \IndexOption{toc~=\textKValue{numberline}}}% \entry{\PValue{index}, \PValue{idx}}{% - The index will be represented by an entry at the table of contents, but - will not be numbered.% - \IndexOption{toc~=\PValue{index}}}% + The index has an unnumbered entry in the table of contents.% + \IndexOption{toc~=\textKValue{index}}}% \entry{\PValue{indexnumbered}}{% \ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - The index will be represented by an entry at the table of contents and - will be numbered.% - \IndexOption{toc~=\PValue{index}}}% + The index has a numbered entry in the table of contents.% + \IndexOption{toc~=\textKValue{index}}}% + \entry{\PValue{leftaligntextentries}, \PValue{leftalignunnumbered}, + \PValue{nonumberline}}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The \PValue{numberline} property (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.setuptoc}) is deleted for the table of contents. + This places unnumbered entries left-aligned with the number of + numbered entries of the same level. This corresponds to the default + setting.% + \IndexOption{toc~=\textKValue{numberline}}}% \pventry{listof}{% - The lists of floating environments, e.\,g., the list of figures and the - list of tables, will be represented by entries at the table of contents, - but will not be numbered.% - \IndexOption{toc~=\PValue{listof}}}% + The lists of floating environments, e.\,g. figures and tables, have + unnumbered entries in the table of contents.% + \IndexOption{toc~=\textKValue{listof}}}% \entry{\PValue{listofnumbered}, \PValue{numberedlistof}}{% - The lists of floating environments, e.\,g., the list of figures and the - list of tables, will be represented by entries at the table of contents - and will be numbered.% - \IndexOption{toc~=\PValue{listofnumbered}}}% + The lists of floating environments, e.\,g. figures and tables, have + numbered entries in the table of contents.% + \IndexOption{toc~=\textKValue{listofnumbered}}}% \entry{\PValue{nobibliography}, \PValue{nobib}}{% - The bibliography will not be represented by an entry at the table of - contents.% - \IndexOption{toc~=\PValue{nobibliography}}}% + The bibliography does not have an entry in the table of contents. This + corresponds to the default setting.% + \IndexOption{toc~=\textKValue{nobibliography}}}% \entry{\PValue{noindex}, \PValue{noidx}}{% - The index will not be represented by an entry at the table of - contents.% - \IndexOption{toc~=\PValue{noindex}}}% + The index does not have an entry in the table of contents. This + corresponds to the default setting.% + \IndexOption{toc~=\textKValue{noindex}}}% \pventry{nolistof}{% - The lists of floating environments, e.\,g., the list of figures and the - list of tables, will not be represented by entries at the table of - contents.% - \IndexOption{toc~=\PValue{nolistof}}}% + The lists of floating environments, e.\,g. figures and tables, do not + have entries in the table of contents. This corresponds to the default + setting.% + \IndexOption{toc~=\textKValue{nolistof}}}% \entry{\PValue{sectionentrywithdots}, \PValue{sectionentrydotfill}}{% \ChangedAt[2014/12]{v3.15}{\Class{scrartcl}}% - The section entries of class \Class{scrartcl} also - use dots to separate the headings text from the page number.% - \IndexOption{toc~=\PValue{sectionentrywithdots}}}% + The section entries of the \Class{scrartcl} class also use dots to + separate the heading text from the page numbers.% + \IndexOption{toc~=\textKValue{sectionentrywithdots}}}% \entry{\PValue{sectionentrywithoutdots}, \PValue{sectionentryfill}}{% \ChangedAt{v3.15}{\Class{scrartcl}}% - The section entries of class \Class{scrartcl} - use white space to separate the headings text from the page number.% - \IndexOption{toc~=\PValue{sectionentrywithoutdots}}}% + The section entries of the \Class{scrartcl} class use white space to + separate the heading text from the page number. This corresponds to the + default setting.% + \IndexOption{toc~=\textKValue{sectionentrywithoutdots}}}% \end{desclist} % \EndIndexGroup \begin{Declaration} - \OptionVName{chapterentrydots}{simple switch}% + \OptionVName{chapterentrydots}{simple switch}\\ \OptionVName{sectionentrydots}{simple switch} \end{Declaration} These\ChangedAt[2014/12]{v3.15}{\Class{scrbook}\and \Class{scrreprt}} options -configure a dotted separation line between the text and the page number of the -chapter entries of classes \Class{scrbook} and -\Class{scrreprt}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}}, or of the -section entries of class \Class{scrartcl}\OnlyAt{\Class{scrartcl}} in the -table of contents. For \PName{simple switch}, any value from -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} may be -used. The default is \PValue{false}. It selects an empty gap instead of -dots. +configure a dotted connecting line between the text and page number of the +chapter entries for the \Class{scrbook} and +\Class{scrreprt}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} classes, or for +the section entries of the \Class{scrartcl}\OnlyAt{\Class{scrartcl}} class, in +the table of contents. For the \PName{simple switch}, you can use any value from +\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. +The default is \PValue{false}. It selects an empty gap instead of dots. \BeginIndex{FontElement}{chapterentrydots}\LabelFontElement{chapterentrydots}% \BeginIndex{FontElement}{sectionentrydots}\LabelFontElement{sectionentrydots}% -If a dotted line is selected, you can change their font using element +If a dotted line is used, you can change its font using the element \FontElement{chapterentrydots}% \important[i]{\FontElement{chapterentrydots}\\ \FontElement{sectionentrydots}} or \FontElement{sectionentrydots}. The font -also depends on the element of the page number of the entry (see also -\autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont} -and \autoref{tab:\LabelBase.fontelements}, -\autopageref{tab:\LabelBase.fontelements}). The defaults of the elements are -shown in \autoref{tab:\LabelBase.tocelements}. Please note\textnote{Attention!} -that the dots of all entries are equally aligned only if all dots use the same -font.% +also depends on the element of the page number of the entry (see also +\DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont}, \autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}, as well as +\autoref{tab:maincls.fontelements}, +\autopageref{tab:maincls.fontelements}). The defaults of the elements are +shown in \autoref{tab:maincls.tocelements}, from +\autopageref{tab:maincls.tocelements}. Note\textnote{Attention!} that the dots +of all entries will be equally spaced only if all dots use the same font.% \EndIndexGroup \begin{Declaration} \Macro{tableofcontents} \end{Declaration}% -The production of the table of contents is done by the \Macro{tableofcontents} -command. To get a correct table of contents, at least two {\LaTeX} runs are -necessary after every change. The contents and the form of the table of -contents may be influenced with the above described option \DescRef{\LabelBase.option.toc}. After -changing the settings of this option, at least two \LaTeX{} runs are needed -again. - -The entry for the highest sectional unit below \DescRef{\LabelBase.cmd.part}, -i.\,e., \DescRef{\LabelBase.cmd.chapter} with -\Class{scrbook}\IndexClass{scrbook} and \Class{scrreprt}\IndexClass{scrreprt} -or \DescRef{\LabelBase.cmd.section} with \Class{scrartcl}\IndexClass -{scrartcl} is not indented. There are no dots between the text of the -sectional unit heading and the page number. The typographic reasons for this -are that the font is usually different, and the desire for appropriate -emphasis. The table of contents of this manual is a good example of these -considerations. +The table of contents is output by the \Macro{tableofcontents} command. To get +correct values in the table of contents requires at least two {\LaTeX} runs +after every change. The \DescRef{\LabelBase.option.toc} option described above +can also affect the extent and format of the table of contents. After changing +the settings of this option, at least two \LaTeX{} runs are needed again. + +Entries for \DescRef{\LabelBase.cmd.chapter}\IndexCmd{chapter} with +\Class{scrbook}\IndexClass{scrbook} and \Class{scrreprt}\IndexClass{scrreprt}, +or \DescRef{\LabelBase.cmd.section}\IndexCmd{section} with +\Class{scrartcl}\IndexClass{scrartcl}, and the sectioning level +\DescRef{\LabelBase.cmd.part}\IndexCmd{part} are not indented. Additionally, +there are no dots between the text of this heading and the page number. The +typographical logic for this behaviour is that the font is usually distinct +and appropriate emphasis is desirable. +However\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}, you can change this behaviour with the previously +documented options. The table of contents of this \iffree{guide}{book} is +created with the default settings and serves as an example. + \BeginIndex{FontElement}{partentry}\LabelFontElement{partentry}% \BeginIndex{FontElement}{chapterentry}\LabelFontElement{chapterentry}% \BeginIndex{FontElement}{sectionentry}\LabelFontElement{sectionentry}% -The font style\ChangedAt{v2.97c}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}}\important[i]{\FontElement{partentry}\\ +The\ChangedAt{v2.97c}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\important{\FontElement{partentry}\\ \FontElement{chapterentry}\\ - \FontElement{sectionentry}} is, however, affected by the settings of the -element \FontElement{partentry}, and for classes \Class{scrbook} and -\Class{scrreprt} by \FontElement{chapterentry}, and for class \Class{scrartcl} -by \FontElement{sectionentry}. % + \FontElement{sectionentry}} font style of the top two levels in the table of +contents is also affected by the settings for the \FontElement{partentry} +element, as well as by the \FontElement{chapterentry} element for the +\Class{scrbook} and \Class{scrreprt} classes, and by the +\FontElement{sectionentry} element for the \Class{scrartcl} class. \BeginIndex{FontElement}{partentrypagenumber}% \LabelFontElement{partentrypagenumber}% +\LabelFontElement{pagination}% \BeginIndex{FontElement}{chapterentrypagenumber}% \LabelFontElement{chapterentrypagenumber}% \BeginIndex{FontElement}{sectionentrypagenumber}% \LabelFontElement{sectionentrypagenumber}% -The font style of the page numbers may be set dissenting from these elements -using \FontElement{partentrypagenumber} and -\FontElement{chapterentrypagenumber} respectively -\FontElement{sectionentrypagenumber} (see \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}, and -\autoref{tab:\LabelBase.fontelements}, -\autopageref{tab:\LabelBase.fontelements}). % -\BeginIndex{FontElement}{chapterentrydots}% -\BeginIndex{FontElement}{sectionentrydots}% -If the optional dots of the entries of \DescRef{\LabelBase.cmd.chapter} or -\DescRef{\LabelBase.cmd.section} are used, you can change their font using -element \FontElement{chapterentrydots}% -\important[i]{\FontElement{chapterentrydots}\\ - \FontElement{sectionentrydots}} or \FontElement{sectionentrydots}. The font -also depends on the element of the page number of the entry (see also -\autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont} -and \autoref{tab:\LabelBase.fontelements}, -\autopageref{tab:\LabelBase.fontelements}). The defaults of the elements are -shown in \autoref{tab:\LabelBase.tocelements}. Please note\textnote{Attention!} -that the dots of all entries are aligned same only if all dots use the same -font.% +You can set the font style of the page numbers separately from these elements +using \FontElement{partentrypagenumber}% +\important{\FontElement{partentrypagenumber}} and +\FontElement{chapterentrypagenumber}% +\important{\FontElement{chapterentrypagenumber}\\ + \FontElement{sectionentrypagenumber}}\,---\,for \Class{scrbook} and +\Class{scrreprt}\,---\,or \FontElement{sectionentrypagenumber}\,---\,for +\Class{scrartcl}\,---\, (see \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} in \autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}, or +\autoref{tab:maincls.fontelements}, \autopageref{tab:maincls.fontelements}). +If\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} you use dotted lines connecting the heading entries +(chapter or section depending on the class) to the page numbers using the +\DescRef{\LabelBase.option.toc}% +\IndexOption{toc~=\textKValue{chapterentrywithdots}}% +\IndexOption{toc~=\textKValue{sectionentrywithdots}} +\DescRef{\LabelBase.option.chapterentrydots}% +\IndexOption{chapterentrydots~=\PName{simple switch}} or +\DescRef{\LabelBase.option.sectionentrydots}% +\IndexOption{sectionentrydots~=\PName{simple switch}} option, you can change +their font style using the \DescRef{\LabelBase.fontelement.chapterentrydots}% +\IndexFontElement{chapterentrydots}% +\important{\DescRef{\LabelBase.fontelement.chapterentrydots}\\ + \DescRef{\LabelBase.fontelement.sectionentrydots}} and +\DescRef{\LabelBase.fontelement.sectionentrydots}% +\IndexFontElement{sectionentrydots} elements. The defaults for these +elements are found in \autoref{tab:maincls.tocelements}. \begin{table} % \centering % \caption \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% \begin{captionbeside} - [Font style defaults of the elements of the table of contents] - {\label{tab:\LabelBase.tocelements}% - Font style defaults of the elements of the table of contents}% + [Default font styles for the elements of the table of contents] + {\label{tab:maincls.tocelements}% + Default font styles for the elements of the table of contents} [l] \setlength{\tabcolsep}{.9\tabcolsep}% Umbruchoptimierung! \begin{tabular}[t]{ll} \toprule Element & Default font style \\ \midrule - \DescRef{\LabelBase.fontelement.partentry} & + \FontElement{partentry} & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{disposition}\Macro{large} \\ - \DescRef{\LabelBase.fontelement.partentrypagenumber} & \\ - \DescRef{\LabelBase.fontelement.chapterentry} & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{disposition}\\ - \DescRef{\LabelBase.fontelement.chapterentrydots} & \Macro{normalfont} \\ - \DescRef{\LabelBase.fontelement.chapterentrypagenumber} & \\ - \DescRef{\LabelBase.fontelement.sectionentry} & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{disposition}\\ - \DescRef{\LabelBase.fontelement.sectionentrydots} & \Macro{normalfont} \\ - \DescRef{\LabelBase.fontelement.sectionentrypagenumber} & \\ + \FontElement{partentrypagenumber} & \\ + \FontElement{chapterentry} & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{disposition}\\ + \FontElement{chapterentrydots} & \Macro{normalfont} \\ + \FontElement{chapterentrypagenumber} & \\ + \FontElement{sectionentry} & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{disposition} \\ + \FontElement{sectionentrydots} & \Macro{normalfont} \\ + \FontElement{sectionentrypagenumber} & \\ \bottomrule \end{tabular} \end{captionbeside} @@ -565,53 +611,64 @@ font.% \begin{Declaration} \Counter{tocdepth} + \Macro{parttocdepth} + \Macro{sectiontocdepth} + \Macro{subsectiontocdepth} + \Macro{subsubsectiontocdepth} + \Macro{paragraphtocdepth} + \Macro{subparagraphtocdepth} \end{Declaration}% -Normally, the units included in the table of contents are all the units from -\DescRef{\LabelBase.cmd.part} to \DescRef{\LabelBase.cmd.subsection} for the classes \Class{scrbook} and -\Class{scrreprt} or from \DescRef{\LabelBase.cmd.part} to \DescRef{\LabelBase.cmd.subsubsection} for the class -\Class{scrartcl}. The inclusion of a sectional unit in the table of contents -is controlled by the counter \Counter{tocdepth}. This has the value \(-\)1 for -\DescRef{\LabelBase.cmd.part}, 0 for \DescRef{\LabelBase.cmd.chapter}, and so on. By incrementing -or decrementing the counter, one can choose the lowest sectional unit level to -be included in the table of contents. The same happens with the standard -classes. - -Please note\textnote{Attention!} that for \DescRef{\LabelBase.cmd.part} the -values of \Counter{tocdepth} and -\DescRef{\LabelBase.counter.secnumdepth}\IndexCounter{secnumdepth} (see +Normally, the sectioning divisions included in the table of contents are all +those from \DescRef{\LabelBase.cmd.part} to +\DescRef{\LabelBase.cmd.subsection} for the \Class{scrbook} and +\Class{scrreprt} classes, or from \DescRef{\LabelBase.cmd.part} to +\DescRef{\LabelBase.cmd.subsubsection} for the \Class{scrartcl} class. Whether +or not to include a sectioning level in the table of contents is controlled by +the \Counter{tocdepth} counter. This has the value -1 for +\DescRef{\LabelBase.cmd.part}, 0 for \DescRef{\LabelBase.cmd.chapter}, and so +on. By incrementing or decrementing the counter, you can choose the lowest +sectioning level to include in the table of contents. Incidentally, the +standard classes work the same way. +Unlike\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\textnote{\KOMAScript{} vs. standard classes} with the +standard classes, with \KOMAScript{} you do not need to remember these values. +\KOMAScript{} defines a \Macro{\PName{level}tocdepth} command for each +sectioning level with the appropriate value which you can use to set +\Counter{tocdepth}. + +Please note\textnote{Attention!} that in +\Class{scrartcl}\OnlyAt{\Class{scrartcl}}, the values of \Counter{tocdepth} +and \DescRef{\LabelBase.counter.secnumdepth}\IndexCounter{secnumdepth} (see \autoref{sec:\LabelBase.structure}, -\DescPageRef{\LabelBase.counter.secnumdepth}) are not the same in -\Class{scrartcl}\OnlyAt{\Class{scrartcl}}. Therefore, you should not use -\DescRef{\LabelBase.cmd.partnumdepth}\IndexCmd{partnumdepth} to set the value -of \Counter{tocdepth}.% +\DescPageRef{\LabelBase.counter.secnumdepth}) for +\DescRef{\LabelBase.cmd.part} are not the same. This behaviour was copied from +the standard \Class{article} class for compatibility. Thus, for example, you +should not use \DescRef{\LabelBase.cmd.partnumdepth}\IndexCmd{partnumdepth} to +set the value of \Counter{tocdepth}.% \begin{Example} - Assume that you are preparing an article that uses the sectional - unit \DescRef{\LabelBase.cmd.subsubsection}. However, you do not want this sectional - unit to appear in the table of contents. The preamble of your + Suppose you are preparing an article that uses the sectioning level + \DescRef{\LabelBase.cmd.subsubsection}. However, you do not want this + sectioning level to appear in the table of contents. The preamble of your document might contain the following: \begin{lstcode} \documentclass{scrartcl} - \setcounter{tocdepth}{2} + \setcounter{tocdepth}{\subsectiontocdepth} \end{lstcode} - You set the counter \Counter{tocdepth} to 2 because you know that - this is the value for \DescRef{\LabelBase.cmd.subsection}. If you know that - \Class{scrartcl} normally includes all levels down to - \DescRef{\LabelBase.cmd.subsubsection} in the table of contents, you can simply - decrement the counter \Counter{tocdepth} by one: + Thus you set the \Counter{tocdepth} counter to the value of the + \Macro{subsectiontocdepth} command. That value is normally 2, but this way, + you do not have to remember it. + + If instead you simply want to include one less level in the table of + contents than you normally would, you can simply subtract one from the + default value of \Counter{tocdepth}: \begin{lstcode} \documentclass{scrartcl} \addtocounter{tocdepth}{-1} \end{lstcode} - How much you should add to or subtract from the \Counter{tocdepth} counter - can also be found by looking at the table of contents after the first - {\LaTeX} run. -\end{Example} -A\textnote{Hint!} small hint in order that you do not need to remember which -sectional unit has which number: in the table of contents count the number of -units required extra or less and then, as in the above example, use -\Macro{addtocounter} to add or subtract that number to or from -\Counter{tocdepth}.% -% + The\textnote{Hint!} value that you need to add to or subtract from + \Counter{tocdepth} is listed in the table of contents after at least two + \LaTeX{} runs. +\end{Example}% \EndIndexGroup % \EndIndexGroup @@ -619,161 +676,200 @@ units required extra or less and then, as in the above example, use \LoadCommonFile{parmarkup}% \section{Paragraph Markup} -\LoadCommonFile{oddorevenpage}% \section{Detection of Odd and Even Pages} +\LoadCommonFile{oddorevenpage}% \section{Detecting Odd or Even Pages} -\section{Head and Foot Using Predefined Page Styles} +\section{Headers and Footers Using Predefined Page Styles} \seclabel{pagestyle} -\BeginIndexGroup -\BeginIndex{}{page>style} +\BeginIndexGroup +\BeginIndex{}{page>style}% One of the general characteristics of a document is the page style. In -{\LaTeX} this means mostly the contents of headers and footers. +\LaTeX{} this primarily consists of the contents of headers and footers. + \begin{Declaration} - \OptionVName{headsepline}{simple switch}% + \OptionVName{headsepline}{simple switch} \OptionVName{footsepline}{simple switch} \end{Declaration}% -In\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -order to have or not to have a rule separating the header from the text body, -use the option \Option{headsepline} with any value shown in -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. Activation -of the option will result in such a separation line. Similarly, activation of -option \Option{footsepline} switches on a rule above the foot -line. Deactivation of any of the options will deactivate the corresponding -rule. - -These options have no effect with the page styles \PValue{empty} and -\PValue{plain}, because there is no header in this case. Such a line always -has the effect of visually bringing header and text body closer together. That -does not mean that the header must now be moved farther from the text -body. Instead, the header should be considered as belonging to the text body -for the purpose of page layout calculations. {\KOMAScript} takes this into -account by automatically passing the option -\DescRef{typearea.option.headinclude} to the \Package{typearea} package -whenever the \Option{headsepline} option is used. \KOMAScript{} behaves -similar to \DescRef{typearea.option.footinclude} using -\Option{footsepline}. Package \Package{scrlayer-scrpage} (see -\autoref{cha:scrlayer-scrpage}) adds additional features to this.% +You\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} can use these options to specify whether a horizontal rule +appears beneath the header or above the footer. You can use any of the values +for simple switches shown in \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch}. Setting the \Option{headsepline} option to +true or invoking it with no value results in a line beneath the header. +Similarly, activating the \Option{footsepline} option results in a rule above +the footer. Deactivating either option switches off the respective rule. + +The\textnote{Attention!} \Option{headsepline} option naturally has no effect +with the \DescRef{\LabelBase.pagestyle.empty} and +\DescRef{\LabelBase.pagestyle.plain} page styles, which are described below, +because these styles explicitly dispense with a header\Index{page>header}. +Typographically, such a line has the effect of making the header appear to be +closer to the text. This does not mean that the header then needs to be moved +farther away from the body of the text\Index{text>body}. Instead, the header +should be considered as belonging to the text body for the purpose of +calculating the type area. \KOMAScript{} takes this into account by passing +the \Option{headsepline} option to the +\hyperref[cha:typearea]{\Package{typearea}}% +\important{\hyperref[cha:typearea]{\Package{typearea}}}\IndexPackage{typearea} +package, which then automatically executes the package option +\DescRef{typearea.option.headinclude}% +\IndexOption{headinclude}\important{\DescRef{typearea.option.headinclude}} +with the same value. The same applies to the footer separation line. Unlike +\Option{headsepline}, the \Option{footsepline} option also affects the +\PValue{plain} page style because \PValue{plain} prints a page number in the +footer. + +The options themselves do not automatically recalculate the type area. To +recalculate it, use the \DescRef{typearea.option.DIV} option with the values +\hyperref[desc:typearea.option.DIV.last]{\PValue{last}} or +\hyperref[desc:typearea.option.DIV.current]{\PValue{current}} (see +\DescPageRef{typearea.option.DIV.last}) or the +\DescRef{typearea.cmd.recalctypearea} command (see +\DescPageRef{typearea.cmd.recalctypearea}) in \autoref{cha:typearea}. + +The \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} +package (see \autoref{cha:scrlayer-scrpage}) offers further possibilities for +adjusting lines in headers and footers.% % \EndIndexGroup \begin{Declaration} - \Macro{pagestyle}\PParameter{page style}% + \Macro{pagestyle}\Parameter{page style} \Macro{thispagestyle}\Parameter{local page style} \end{Declaration}% -Usually one distinguishes four different page styles: +There are usually four different page styles: \begin{description} -\item[empty\BeginIndex{Pagestyle}{empty}\LabelPageStyle{empty}] is the page - style with entirely empty headers and footers. In {\KOMAScript} this is - completely identical to the standard classes. -\item[headings\BeginIndex{Pagestyle}{headings}\LabelPageStyle{headings}] is - the page style with running headings in the header. These are headings for - which titles are automatically inserted into the header. - \OnlyAt{\Class{scrbook}\and\Class{scrreprt}}With the classes - \Class{scrbook}\IndexClass{scrbook} and - \Class{scrreprt}\IndexClass{scrreprt} the titles of chapters and sections - are repeated in the header for double-sided layout\,---\,with {\KOMAScript} - on the outer side, with the standard classes on the inner side. The page - number is set on the outer side of the footer with {\KOMAScript}; with the - standard classes it is set on the inner side of the header. In one-sided - layouts only the titles of the chapters are used and are, with - {\KOMAScript}, centered in the header. The page numbers are set centered in - the footer with {\KOMAScript}. +\item[{\PageStyle{empty}% + \BeginIndex[indexmain]{Pagestyle}{empty}\LabelPageStyle{empty}}] is the + page style with completely empty headers and footers. In {\KOMAScript} + this is identical to the standard classes.% +\item[{\PageStyle{headings}% + \BeginIndex[indexmain]{Pagestyle}{headings}\LabelPageStyle{headings}}] is + the page style with running heads in the header. In this style, headings are + automatically\Index[indexmain]{running heads>automatic} inserted into the + header. \OnlyAt{\Class{scrbook}\and\Class{scrreprt}}% + With the classes \Class{scrbook}\IndexClass{scrbook} and + \Class{scrreprt}\IndexClass{scrreprt}, the headings of chapters and sections + are repeated in the header for two-sided printing\,---\,on the outer side + with {\KOMAScript}\textnote{\KOMAScript{} vs. standard classes}, on the + inner side with the standard classes. {\KOMAScript} puts the page number on + the outer side of the footer; the standard classes put it on the inner side + of the header. In one-sided printing, {\KOMAScript} uses only the chapter + headings, which are centred in the header, and puts the page numbers centred + in the footer. \OnlyAt{\Class{scrartcl}}\Class{scrartcl}\IndexClass{scrartcl} behaves - similarly, but starting a level deeper in the section hierarchy with + similarly but starts one a level deeper in the sectioning hierarchy, with sections and subsections, because the chapter level does not exist in this case. - While the standard classes automatically set running headings always - in capitals, {\KOMAScript} applies the style of the title. This has - several typographic reasons. Capitals as a decoration are actually - far too strong. If one applies them nevertheless, they should be set - in a one point smaller type size and with tighter spacing. The - standard classes do not take these points into consideration. - - Beyond this {\KOMAScript} classes support rules below the head and above the - foot using options \DescRef{\LabelBase.option.headsepline} and - \DescRef{\LabelBase.option.footsepline} which are described above. -\item[myheadings\BeginIndex{Pagestyle}{myheadings}\LabelPageStyle{myheadings}] - corresponds mostly to the page style \PValue{headings}, but the running - headings are not automatically produced\,---\,they have to be defined by the - user. The commands \Macro {markboth}\IndexCmd{markboth} and - \DescRef{\LabelBase.cmd.markright}\IndexCmd{markright} can be used for that - purpose (see below). -\item[plain\BeginIndex{Pagestyle}{plain}\LabelPageStyle{plain}] is the page - style with empty header and only a page number in the footer. With the - standard classes this page number is always centered in the footer. With - {\KOMAScript} the page number appears on double-sided\Index {double-sided} - layout on the outer side of the footer. The one-sided page style behaves - like the standard setup. + While the standard classes\textnote{\KOMAScript{} vs. standard classes} + automatically convert the running heads to upper-case letters, + {\KOMAScript} uses the capitalisation found in the headings. There are + several typographical reasons for this. Upper-case letters are actually far + too massive as a text decoration. If you use them anyway, they should be set + one point smaller and with slightly tighter spacing. The standard classes do + not take these points into consideration. + + In addition, the {\KOMAScript} classes support rules below the header and + above the footer with the \DescRef{\LabelBase.option.headsepline} and + \DescRef{\LabelBase.option.footsepline} options (see + \DescPageRef{\LabelBase.option.headsepline}).% +\item[{\PageStyle{myheadings}% + \BeginIndex[indexmain]{Pagestyle}{myheadings}\LabelPageStyle{myheadings}}] + mostly corresponds to the \PValue{headings} page style, but the running + heads are not generated automatically% + \Index[indexmain]{running heads>manual}\,---\,they have to be defined by the + user. You can use the \DescRef{\LabelBase.cmd.markboth}\IndexCmd{markboth} + and \DescRef{\LabelBase.cmd.markright}\IndexCmd{markright}\important{% + \DescRef{\LabelBase.cmd.markboth}\\ + \DescRef{\LabelBase.cmd.markright}} commands for that purpose (see + \DescPageRef{\LabelBase.cmd.markright}). +\item[{\PageStyle{plain}% + \BeginIndex[indexmain]{Pagestyle}{plain}\LabelPageStyle{plain}}] is the + page style with no running head\Index{running head} and only a page number% + \Index{page>number} in the footer. The\textnote{\KOMAScript{} vs. standard + classes} standard classes always centre this page number in the footer. + {\KOMAScript} puts the page number on the outer side of the footer in + two-sided\Index{two-sided} mode. {\KOMAScript} behaves like the + standard classes in one-sided printing.% \end{description} -The page style can be set at any time with the help of the \Macro{pagestyle} -command and takes effect with the next page that is output. If\textnote{Hint!} -one uses \Macro{pagestyle} just before a command, that results in an implicit -page break and if the new page style should be used at the resulting new page -first, a \DescRef{\LabelBase.cmd.cleardoublepage} just before -\Macro{pagestyle} will be useful. But usually one sets the page style only -once at the beginning of the document or in the preamble. +You\important{\Macro{pagestyle}} can set the page style at any time with the +help of the \Macro{pagestyle} command, and this setting takes effect with the +next page that is output. If\textnote{Hint!} you use \Macro{pagestyle} just +before a command that results in an implicit page break and if the new page +style should be used on the resulting new page, a +\DescRef{\LabelBase.cmd.cleardoublepage} just before \Macro{pagestyle} will be +useful. But usually you set the page style only once, at the beginning of the +document or in the preamble. To\important{\Macro{thispagestyle}} change the page style of the current page -only, one uses the \Macro{thispagestyle} command. This also happens -automatically at some places in the document. For example, the instruction -\Macro{thispagestyle}\PParameter{\DescRef{\LabelBase.cmd.chapterpagestyle}} is issued -implicitly on the first page of a chapter. - -Please\textnote{Attention!} note that the change between automatic and manual -running headings is no longer performed by page style changes when using the -\Package{scrlayer-scrpage} package, but instead via special instructions. The -page styles \PValue{headings} and \PValue{myheadings} should not be used -together with this package.% -% - -\BeginIndexGroup -\BeginIndex[indexother]{}{font>style}% +only, use the \Macro{thispagestyle} command. This occurs automatically at some +points in the document. For example, the +\Macro{thispagestyle}\PParameter{\DescRef{\LabelBase.cmd.chapterpagestyle}} +command is issued implicitly on the first page of a chapter. + +Note\textnote{Attention!} that when you use the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} +package, switching between automatic and manual running heads is no longer +accomplished by changing the page styles but with special instructions. You +should not use the \PValue{headings} and \PValue{myheadings} page styles with +this package. + +\BeginIndexGroup \BeginIndex[indexother]{}{font>style}% \BeginIndex{FontElement}{pageheadfoot}\LabelFontElement{pageheadfoot}% +\LabelFontElement{pagehead}% \BeginIndex{FontElement}{pagefoot}\LabelFontElement{pagefoot}% \BeginIndex{FontElement}{pagenumber}\LabelFontElement{pagenumber}% -In order to change the font style used in the header, footer, or for the page -number\ChangedAt{v2.8p}{% - \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% -, please use the interface described in \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}. The same element is used for header -and footer, which you can designate with -\FontElement{pageheadfoot}\important{\FontElement{pageheadfoot}}. The element -for the page number within the header or footer is called -\FontElement{pagenumber}\important{\FontElement{pagenumber}}. The element -\FontElement{pagefoot}, that is additionally supported by the \KOMAScript{} -classes, will be used only if a page style has been defined that has text at -the foot line, using package -\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} (see +To change the font style used for the header, the footer, or the page +number\ChangedAt{v2.8p}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}, use the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see +\autoref{sec:\LabelBase.textmarkup}, +\DescPageRef{\LabelBase.cmd.setkomafont}). The same element, +\FontElement{pageheadfoot}\IndexFontElement{pageheadfoot}% +\important{\FontElement{pageheadfoot}}, is used for the header and the footer. +The element for the page number within the header or footer is called +\FontElement{pagenumber}\IndexFontElement{pagenumber}% +\important{\FontElement{pagenumber}}. The +\FontElement{pagefoot}\IndexFontElement{pagefoot}% +\important{\FontElement{pagefoot}} element, which is also provided by the +\KOMAScript{} classes, is used only if you define a page style with the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage} package in which the footer contains text (see \autoref{cha:scrlayer-scrpage}, \DescPageRef{scrlayer-scrpage.fontelement.pagefoot}). -The default settings can be found in -\autoref{tab:\LabelBase.defaultFontsHeadFoot}.% +You can find the default settings in +\autoref{tab:\LabelBase.defaultFontsHeadFoot}. % \begin{table} % \centering% +% \caption \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% -% \caption +% \addtokomafont{caption}{\raggedright}% \begin{captionbeside} - [{Default values for the elements of a page style}] - {\label{tab:\LabelBase.defaultFontsHeadFoot}% - Default values for the elements of a page style} + [{Default values for page style elements}] + {\label{tab:maincls.defaultFontsHeadFoot}% + \hspace{0pt plus 1ex}% + Default values for page style elements} [l] \begin{tabular}[t]{ll} \toprule - Element & Default value \\ + Element & Default \\ \midrule - \DescRef{\LabelBase.fontelement.pagefoot}\IndexFontElement{pagefoot} & + \FontElement{pagefoot}\IndexFontElement{pagefoot} & \\ - \DescRef{\LabelBase.fontelement.pageheadfoot}\IndexFontElement{pagefoothead} & + \FontElement{pageheadfoot}\IndexFontElement{pageheadfoot} & \Macro{normalfont}\Macro{normalcolor}\Macro{slshape} \\ - \DescRef{\LabelBase.fontelement.pagenumber}\IndexFontElement{pagenumber} & + \FontElement{pagenumber}\IndexFontElement{pagenumber} & \Macro{normalfont}\Macro{normalcolor}\\ \bottomrule \end{tabular} @@ -782,133 +878,143 @@ The default settings can be found in % \begin{Example} \leavevmode\phantomsection\xmpllabel{cmd.pagestyle}% - Assume that you want to set header and footer in a smaller type size + Suppose you want to set header and footer in a smaller type size and in italics. However, the page number should not be set in - italics but bold. Apart from the fact that the result will look - horrible, you can obtain this as follows: + italics but in bold. Apart from the fact that the result will look + horrible, you can do this as follows: \begin{lstcode} \setkomafont{pageheadfoot}{% - \normalfont\normalcolor\itshape\small - } + \normalfont\normalcolor\itshape\small} \setkomafont{pagenumber}{\normalfont\bfseries} \end{lstcode} - If you want only that, in addition to the default slanted variant, a smaller - type size is used, it is sufficient to use the following: + On the other hand, if you only want a smaller font to be used along with the + default slanted text, you can use the following: \begin{lstcode} \addtokomafont{pagehead}{\small} \end{lstcode} - As you can see, the last example uses the element - \FontElement{pagehead}\important{\FontElement{pagehead}}. You can achieve - the same result using \PValue{pageheadfoot} instead (see + As you can see, the previous example uses the + \FontElement{pagehead}\important{\FontElement{pagehead}} element. You can + achieve the same result using \PValue{pageheadfoot} instead (see \autoref{tab:\LabelBase.fontelements} on \autopageref{tab:\LabelBase.fontelements}). \end{Example} -It is not possible to use these methods to force capitals to be used -automatically for the running headings. For that, please use the -\Package{scrlayer-scrpage} package (see \autoref{cha:scrlayer-scrpage}, +It is not possible to use these methods to force upper-case letters to be used +automatically for the running heads. Although you can redefine +\DescRef{tocbasic.cmd.MakeMarkcase}\IndexCmd{MakeMarkcase}, in such cases you +should instead use the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} package (see +\autoref{cha:scrlayer-scrpage}, \DescPageRef{scrlayer-scrpage.option.markcase}). -If you define your own page styles, the commands +If\textnote{Hint!} you define your own page styles, the commands \DescRef{\LabelBase.cmd.usekomafont}\PParameter{pageheadfoot}, -\DescRef{\LabelBase.cmd.usekomafont}\PParameter {pagenumber}, and -\DescRef{\LabelBase.cmd.usekomafont}\PParameter{pagefoot} can be useful. If -you do not use the {\KOMAScript} package \Package{scrlayer-scrpage} (see -\autoref{cha:scrlayer-scrpage}) for that, but, for example, the package -\Package{fancyhdr}\IndexPackage{fancyhdr} (see \cite{package:fancyhdr}), you -can use these commands in your definitions. Thereby you can remain compatible -with {\KOMAScript} as much as possible. If you do not use these commands in -your own definitions, changes like those shown in the previous examples have -no effect. The package -\Package{scrlayer-scrpage}\IndexPackage{scrlayer-scrpage} takes care to keep -the maximum possible compatibility with other packages itself. -% +\DescRef{\LabelBase.cmd.usekomafont}\PParameter{pagenumber}, and +\DescRef{\LabelBase.cmd.usekomafont}\PParameter{pagefoot} can be useful. In +particular, if you do not use the {\KOMAScript} package +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} (see +\autoref{cha:scrlayer-scrpage}) but use, for example, the +\Package{fancyhdr}\IndexPackage{fancyhdr}\important{\Package{fancyhdr}} +package (see \cite{package:fancyhdr}), you can use these commands in your +definitions. In this way you can maintain compatibility with {\KOMAScript} as +much as possible. If you do not use these commands in your own definitions, +changes such as those shown in the previous examples have no effect. The +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage} package tries to maintain maximum +compatibility as long as, for example, +\iffree{\Macro{thepage}}{\DescRef{\LabelBase-experts.cmd.thepage}}% +\IndexCmd{thepage} is not used directly for the page number rather than the +\iffree{\Macro{pagemark}}{\DescRef{\LabelBase-experts.cmd.pagemark}}% +\IndexCmd{pagemark} which is provided for it.% \EndIndexGroup % \EndIndexGroup \begin{Declaration} - \Macro{markboth}\Parameter{left mark}\Parameter{right mark}% + \Macro{markboth}\Parameter{left mark}\Parameter{right mark} \Macro{markright}\Parameter{right mark} \end{Declaration} -\BeginIndex{Pagestyle}{headings}% -\BeginIndex{Pagestyle}{myheadings}% -With page style \PageStyle{myheadings}\important{\PageStyle{myheadings}}% -\IndexPagestyle{myheadings}, there's no automatic setting of the running head. -Instead of this one would set it with the help of commands \Macro{markboth} -and \Macro{markright}. Thereby \PName{left mark} normally will be used at the -head of even pages and \PName{right mark} at the heads of odd pages. With -one-sided printing, only the \PName{right mark} exists. Using package -\Package{scrlayer-scrpage}% -\IndexPackage{scrlayer-scrpage}\important{\Package{scrlayer-scrpage}}, the -additional command \DescRef{scrlayer-scrpage.cmd.markleft}% -\IndexCmd{markleft}\important{\DescRef{scrlayer-scrpage.cmd.markleft}} exists. - -The commands may be used with other page styles too. Combination with automatic -running head, e.\,g., with page style \PageStyle{headings}, limits the effect -of the commands until the next automatic setting of the corresponding marks.% +The \DescRef{\LabelBase.pagestyle.myheadings}% +\important{\DescRef{\LabelBase.pagestyle.myheadings}}% +\IndexPagestyle{myheadings} page style does not set the running head. Instead, +you set it with the help of the \Macro{markboth} and \Macro{markright} +commands. This way the \PName{left mark} will normally be used in the header +of even pages and \PName{right mark} in the header of odd pages. With +one-sided printing, only the \PName{right mark} exists. With the +\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% +\IndexPackage{scrlayer-scrpage}% +\important{\hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} +package, the \DescRef{scrlayer-scrpage.cmd.markleft}% +\IndexCmd{markleft}\important{\DescRef{scrlayer-scrpage.cmd.markleft}} command +is also available. + +You can use these commands with other page styles too. However, when combined +with automatic running heads, for example with the +\DescRef{\LabelBase.pagestyle.headings}\IndexPagestyle{headings} page style, +the effect of the commands lasts only until the next time the respective marks +are set automatically.% % \EndIndexGroup - \begin{Declaration} - \Macro{titlepagestyle}% - \Macro{partpagestyle}% - \Macro{chapterpagestyle}% + \Macro{titlepagestyle} + \Macro{partpagestyle} + \Macro{chapterpagestyle} \Macro{indexpagestyle} \end{Declaration}% \Index{title>page style}% \Index{part>page style}% \Index{chapter>page style}% \Index{index>page style}% -For some pages, a different page style is chosen with the help of the command -\DescRef{\LabelBase.cmd.thispagestyle}. Which page style this actually is, is -defined by these four macros, of which \Macro{partpagestyle} and -\Macro{chapterpagestyle}\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} are found -only with classes \Class{scrbook} and \Class{scrreprt}, but not in -\Class{scrartcl}. The default value for all four cases is \PValue{plain}. The -meaning of these macros can be taken from \autoref{tab:specialpagestyles}. +On some pages, a different page style is chosen automatically with the help of +the \DescRef{\LabelBase.cmd.thispagestyle} command. Which page style this +actually is, is defined by these four macros, of which \Macro{partpagestyle} +and \Macro{chapterpagestyle}\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} are +found only with classes \Class{scrbook} and \Class{scrreprt}, and not in +\Class{scrartcl}. The default value for all four cases is +\DescRef{\LabelBase.pagestyle.plain}\IndexPagestyle{plain}. You can find the +meaning of these macros in \autoref{tab:specialpagestyles}. % \begin{table} \centering - \caption{Macros to set up page style of special pages} + \caption{Macros to set up the page style of special pages} \label{tab:specialpagestyles} \begin{desctabular} \mentry{titlepagestyle}{Page style for a title page when using \emph{in-page} titles.}% - \mentry{partpagestyle}{Page style for the pages with \DescRef{\LabelBase.cmd.part} - titles.}% + \mentry{partpagestyle}{Page style for pages with + \DescRef{\LabelBase.cmd.part} titles.}% \mentry{chapterpagestyle}{Page style for the first page of a chapter.}% \mentry{indexpagestyle}{Page style for the first page of the index.}% \end{desctabular} \end{table} % -The page styles can be redefined with the \Macro{renewcommand} macro. +You can redefine the page styles with the \Macro{renewcommand} macro. \begin{Example} - Assume that you want the pages with a \DescRef{\LabelBase.cmd.part} heading to have - no number. Then you can use the following command, for example in - the preamble of your document: + Suppose you do not want the pages with a \DescRef{\LabelBase.cmd.part} + heading to be numbered. You can use the following command in the preamble of + your document: \begin{lstcode} \renewcommand*{\partpagestyle}{empty} \end{lstcode} As mentioned previously on \DescPageRef{\LabelBase.pagestyle.empty}, - the page style \PValue{empty} is exactly what is required in this - example. Naturally you can also use a user-defined page style. - - Assume you have defined your own page style for initial chapter pages - with the package \Package{scrlayer-scrpage} (see - \autoref{cha:scrlayer-scrpage}). You have given to this page style the - fitting name \PValue{chapter}. To actually use this style, you must - redefine the macro \Macro{chapterpagestyle} accordingly: + the \PValue{empty} page style is exactly what is required in this + example. Of course, you can also use a user-defined page style. + + Suppose you have defined your own page style for initial chapter pages + with the \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}} package + (see \autoref{cha:scrlayer-scrpage}). You have given this page style the + fitting name of \PValue{chapter}. To actually use this style, you must + redefine \Macro{chapterpagestyle} in this way: \begin{lstcode} \renewcommand*{\chapterpagestyle}{chapter} \end{lstcode} - - Assume that you want the table of contents\Index{table of - contents}\textnote{table of contents} of a book to have no page - numbers. However, everything after the table of contents should work again - with the page style \PValue{headings}, as well as with \PValue{plain} on - every first page of a chapter. You can use the following commands: + + Suppose you do not want the table of contents\Index{table of contents}% + \textnote{table of contents} of a book to have page numbers. Everything + after the table of contents, however, should use the \PValue{headings} + page style, including the \PValue{plain} page style for the first + page of every chapter. You can use the following: \begin{lstcode} \clearpage \pagestyle{empty} @@ -918,33 +1024,50 @@ The page styles can be redefined with the \Macro{renewcommand} macro. \pagestyle{headings} \renewcommand*{\chapterpagestyle}{plain} \end{lstcode} - Instead of the above you may do a local redefinition using a group. The - advantage will be that you do not need to know the current page style before - the change to switch back at the end. + You can also keep the redefinition local by using a group. This method has + the advantage that you do not need to make any assumptions about the what + the previous page style was in order to restore it after your local change: \begin{lstcode} \clearpage \begingroup - \pagestyle{empty} - \renewcommand*{\chapterpagestyle}{empty} - \tableofcontents - \clearpage + \pagestyle{empty} + \renewcommand*{\chapterpagestyle}{empty} + \tableofcontents + \clearpage \endgroup \end{lstcode} + Note,\important{Attention!} however, that you never should put a numbered + sectioning command into a group. Otherwise you may get unpredictable results + with commands like \Macro{label}. - But\important{Attention!} notice that you never should put a numbered head - into a group. Otherwise you may get funny results with commands like - \Macro{label}. + On \DescPageRef{tocbasic.cmd.AfterTOCHead} in \autoref{sec:tocbasic.toc}, + you will discover the \DescRef{tocbasic.cmd.AfterTOCHead} command, which + makes a solution even easier: +\begin{lstcode} + \AfterTOCHead[toc]{% + \thispagestyle{empty}% + \pagestyle{empty}% + } +\end{lstcode}% + This takes advantage of the fact that if there are several + \DescRef{\LabelBase.cmd.thispagestyle} commands on the same page, the last + one always wins. \end{Example} \begin{Explain} - Whoever thinks that it is possible to put running headings on the - first page of a chapter by using the command + You might think that you can put running heads on the first page of a + chapter simply by using the \begin{lstcode} \renewcommand*{\chapterpagestyle}{headings} \end{lstcode} - should read more about the background of \Macro{rightmark} at - \autoref{sec:maincls-experts.addInfos}, - \DescPageRef{maincls-experts.cmd.rightmark}. + command. Before you try this, you should read \iffree{}{more about the + background to \DescRef{maincls-experts.cmd.rightmark} in + \autoref{sec:maincls-experts.addInfos} on + \DescPageRef{maincls-experts.cmd.rightmark}. Also, }the remarks on + \DescRef{scrlayer-scrpage-experts.cmd.rightfirstmark} starting on page + \DescPageRef{scrlayer-scrpage-experts.cmd.rightfirstmark} in + \autoref{cha:scrlayer-scrpage-experts}, \autoref{part:forExperts} + \iffree{}{provide important information}.% \end{Explain} % \EndIndexGroup @@ -953,27 +1076,24 @@ The page styles can be redefined with the \Macro{renewcommand} macro. \begin{Declaration} \Macro{pagenumbering}\Parameter{numbering style} \end{Declaration} -This command works the same way in {\KOMAScript} as in the standard -classes. More precisely it is a feature neither of the standard classes nor of -the \KOMAScript{} classes but of the {\LaTeX} kernel. You can specify with -this command the \PName{numbering style} of page numbers. - -The changes take effect immediately, hence starting with the -page that contains the command. It is recommended to use -\DescRef{\LabelBase.cmd.cleardoubleoddpage} to close the last page and start a new odd page -before. The possible settings can be found in -\autoref{tab:numberKind}. - -Using\textnote{Attention!} the command \Macro{pagenumbering} also resets the -page counter\Index{page>counter}\Index{page>number}. Thus the page number of -the next page which {\TeX} outputs will have the number 1 in the style -\PName{numbering style}. +This command works the same way in {\KOMAScript} as in the standard classes. +Strictly speaking, it is a feature of neither the standard classes nor the +\KOMAScript{} classes but of the {\LaTeX} kernel. This command is used to +change the \PName{numbering style} of page numbers. + +The changes take effect immediately, i.\,e., starting from the page that +contains the command. If necessary, you should first close the current page +with \DescRef{\LabelBase.cmd.clearpage} or better +\DescRef{\LabelBase.cmd.cleardoubleoddpage}% +\important{\DescRef{\LabelBase.cmd.cleardoubleoddpage}}% +\IndexCmd{cleardoubleoddpage}. You can find the available settings for +\PName{numbering style} in \autoref{tab:numberKind}. % \begin{table} -% \centering + % \centering \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% -% \caption + % \caption \begin{captionbeside} {\label{tab:numberKind}% Available numbering styles of page numbers} @@ -990,9 +1110,91 @@ the next page which {\TeX} outputs will have the number 1 in the style \end{tabular} \end{captionbeside} \end{table} -% + +Calling\textnote{Attention!} \Macro{pagenumbering} always resets the page +number\Index{page>number}. The current page becomes number 1 in the selected +\PName{numbering style}. In order that two-sided documents produce the correct +results on an even page, so that the left-hand page is not missing, you should +always add \DescRef{\LabelBase.cmd.cleardoubleoddpage}% +\important{\DescRef{\LabelBase.cmd.cleardoubleoddpage}}% +\IndexCmd{cleardoubleoddpage} before \Macro{pagenumbering}. The next section +provides more information about potentially inserted blank pages. + +\begin{Explain} + Let me say a word about a common mistake found in various templates + circulating on the Internet. If you encounter lines like the + following\,---\,without the initial comment naturally\,---\,this is an + unmistakable sign that the creator did not read or understand the + remark above: +\begin{lstcode} + % Attention! This example contains errors! + % Please note the explanation in the text! + \tableofcontents + \pagenumbering{arabic} + \setcounter{page}{1} +\end{lstcode} + Since \DescRef{\LabelBase.cmd.tableofcontents} outputs the table of contents + but does not automatically issue a page break at the end, the page numbering + is already changed on the last page of the table of contents. Because it + lacks a \DescRef{\LabelBase.cmd.cleardoubleoddpage} command before + \Macro{pagenumbering}, it receives a pagination of the Arabic number 1. + Additionally, the final line which sets the page numbering to 1 is + superfluous, since this is already done by \Macro{pagenumbering}. + + Sometimes\,---\,without the initial comment, naturally\,---\, you find: +\begin{lstcode} + % Attention! This example contains errors! + % Please note the explanation in the text! + \tableofcontents + \pagebreak + \pagenumbering{arabic} + \setcounter{page}{1} +\end{lstcode} + Here the creator tried to solve the problem with the final page of the table + of contents with the help of \Macro{pagebreak}\IndexCmd{pagebreak}. + + Unfortunately, this solution is not much better. Here there is a page break + after the last page of the table of contents. This may cause entries on the + last page of a two-sided document to have excess vertical spacing (see + \DescRef{\LabelBase.cmd.flushbottom}, + \DescPageRef{\LabelBase.cmd.flushbottom}). \Macro{pagebreak} is clearly + the wrong command here. + + Furthermore, \Macro{newpage}\IndexCmd{newpage} or + \DescRef{\LabelBase.cmd.clearpage} would not be sufficient for a two-sided + document. For example, if the last page of the table of contents had the + Roman numeral vii, the Arabic numbered right-side page 1 would immediately + follow the Roman numeral right-side page. A left-side page between the two + would be missing, which could cause serious problems with later printing. + + My advice: Avoid using templates that contain errors with respect to such + simple things. Incidentally, the correct way would be: +\begin{lstcode} + \tableofcontents + \cleardoubleoddpage + \pagenumbering{arabic} +\end{lstcode} + This also applies if \Class{scrartcl}\OnlyAt{\Class{scrartcl}} uses a class + that usually does not start a new page after the table of contents. If you + switch the page numbering, a new right-hand page must be started. If you do + not want such a change, you should keep the numbering style of pages + consistent throughout the document without changing it in between. +\iffalse% Umbruchkorrekturtext + For articles or other short documents, this is generally recommended. +\fi + + It is easier to change the numbering style when using + \Class{scrbook}\OnlyAt{\Class{scrbook}}. There you have the support of two + commands, \DescRef{\LabelBase.cmd.frontmatter}% + \important{\DescRef{\LabelBase.cmd.frontmatter}\\ + \DescRef{\LabelBase.cmd.mainmatter}}% + \IndexCmd{fontmatter} and \DescRef{\LabelBase.cmd.mainmatter}% + \IndexCmd{mainmatter}, for the most commonly used switching. For more + information, please see + \autoref{sec:maincls.separation}, + \DescPageRef{\LabelBase.cmd.mainmatter}.% +\end{Explain}% \EndIndexGroup -% \EndIndexGroup @@ -1000,126 +1202,130 @@ the next page which {\TeX} outputs will have the number 1 in the style \LoadCommonFile{footnotes}% \section{Footnotes} - -\section[Demarcation]{Demarcation\protect\OnlyAt{\Class{scrbook}}} +\section[Book Structure]{Book Structure\protect\OnlyAt{\Class{scrbook}}} \seclabel{separation} -\BeginIndexGroup -\BeginIndex{}{front matter}% -\BeginIndex{}{main matter}% -\BeginIndex{}{back matter}% -\BeginIndex{}{matter>front}% -\BeginIndex{}{matter>main}% -\BeginIndex{}{matter>back}% -Sometimes books are roughly separated into front matter, main matter, and -back matter. \KOMAScript{} provides this for \Class{scrbook} also. +Sometimes books are loosely divided into \emph{front matter}% +\Index{front matter}, \emph{main matter}\Index{main matter}, and +\emph{back matter}\Index{back matter}. \KOMAScript{} also provides this +capability for \Class{scrbook}. + \begin{Declaration} - \Macro{frontmatter}% - \Macro{mainmatter}% + \Macro{frontmatter} + \Macro{mainmatter} \Macro{backmatter} \end{Declaration}% -The macro \Macro{frontmatter}\important{\Macro{frontmatter}} introduces the -front matter in which roman numerals are used for the page numbers. Chapter -headings in a front matter are not numbered. The section titles which would be -numbered start at chapter 0, and would be consecutively numbered across -chapter boundaries. However, this is of no import, as the front matter is used -only for the title pages, table of contents\Index{table of contents}, lists of -figures\Index{list of>figures}\Index{figures>list of} and -tables\Index{tables>list of}, and a foreword\Index{foreword}. The foreword can -thus be set as a normal chapter. A foreword should never be divided into -sections but kept as short as possible. Therefore, in the foreword there is no -need for a deeper structuring than the chapter level. - -In case the user sees things differently and wishes to use numbered +The front matter includes all the material which appears before the main +text begins, including title pages, preface, and table of contents. It is +initiated with +\Macro{frontmatter}\important{\Macro{frontmatter}}. In the front matter, +Roman numerals are used for the page numbers, and chapter headings in +the header are not numbered. However, section headings are numbered +consecutively, starting from chapter 0. This typically does not matter, as the +front matter is used only for the title pages, table of contents% +\Index{table of contents}, lists of figures\Index{list of>figures}% +\Index{figures>list of} and tables\Index{tables>list of}, and a +preface\Index{preface} or foreword\Index{foreword}. The preface can thus be +created as a normal chapter. A preface should be as short as possible and +never divided into sections. The preface thus does not require a deeper level +of structure than the chapter. + +If you see things differently and want to use numbered sections\Index{section>number} in the chapters of the front matter, as of -version~2.97e\ChangedAt{v2.97e}{\Class{scrbook}}% +version~2.97e,\ChangedAt{v2.97e}{\Class{scrbook}}% \important{\OptionValueRef{\LabelBase}{version}{2.97e}} the section numbering no longer contains the chapter number. This change only takes effect when the compatibility option is set to at least version~2.97e (see option \DescRef{\LabelBase.option.version}, \autoref{sec:\LabelBase.compatibilityOptions}, -\DescPageRef{\LabelBase.option.version}). It is explicity noted that this -creates a confusion with chapter numbers! The use of \DescRef{\LabelBase.cmd.addsec} and -\DescRef{\LabelBase.cmd.section*} (see \autoref{sec:\LabelBase.structure}, -\DescPageRef{\LabelBase.cmd.section*} and \DescPageRef{\LabelBase.cmd.addsec}) -are thus, in the author's opinion, far more preferable. - -As of version~2.97e\ChangedAt{v2.97e}{\Class{scrbook}} the numbering of float -environments, such as tables\Index{table>number} and +\DescPageRef{\LabelBase.option.version}). It is explicitly noted that this +creates confusion with chapter numbers! The use of +\DescRef{\LabelBase.cmd.addsec} and \DescRef{\LabelBase.cmd.section*} (see +\autoref{sec:\LabelBase.structure}, \DescPageRef{\LabelBase.cmd.section*} and +\DescPageRef{\LabelBase.cmd.addsec}) are thus, in the author's opinion, +greatly preferable. + +As of version~2.97e\ChangedAt{v2.97e}{\Class{scrbook}} the numbering of +floating environments, such as tables\Index{table>number} and figures\Index{figure>number}, and equation numbers\Index{equation>number} in -the front matter also contain no chapter number part. To take effect this too -requires the corresponding compatibility setting (see option -\DescRef{\LabelBase.option.version}, +the front matter also contains no chapter-number part. To take effect, this +too requires the corresponding compatibility setting (see the +\DescRef{\LabelBase.option.version} option, \autoref{sec:\LabelBase.compatibilityOptions}, \DescPageRef{\LabelBase.option.version}). -\Macro{mainmatter}\important{\Macro{mainmatter}} introduces the main matter -with the main text. If there is no front matter, then this command can be -omitted. The default page numbering in the main matter uses Arabic numerals -(re)starting in the main matter at 1. +The part of the book with the main text is introduced +with \Macro{mainmatter}\important{\Macro{mainmatter}}. If there is no front +matter, you can omit this command. The default page numbering in the main +matter uses Arabic numerals and (re)starts the page count at 1 at the start of +the main matter. The back matter is introduced with -\Macro{backmatter}\important{\Macro{backmatter}}. Opinions differ in what -should be part of the back matter. So in some cases you will find only the +\Macro{backmatter}\important{\Macro{backmatter}}. Opinions differ as to what +belongs in the back matter. So in some cases you will find only the bibliography\Index{bibliography}, in some cases only the index\Index{index}, -and in other cases both of these as well as the appendices. The chapters in +and in other cases both of these as well as the appendices. The chapters in the back matter are similar to the chapters in the front matter, but page -numbering is not reset. If you do require separate page numbering you may use -the command \DescRef{\LabelBase.cmd.pagenumbering} from +numbering is not reset. If you do require separate page numbering, you can use +the \DescRef{\LabelBase.cmd.pagenumbering}% +\important{\DescRef{\LabelBase.cmd.pagenumbering}} command in \autoref{sec:\LabelBase.pagestyle}, -\DescPageRef{\LabelBase.cmd.pagenumbering}. -% -\EndIndexGroup +\DescPageRef{\LabelBase.cmd.pagenumbering}.% % \EndIndexGroup -\section{Structuring of Documents} -\seclabel{structure} +\section{Document Structure} +\seclabel{structure}% +\BeginIndexGroup +\BeginIndex{}{document structure} + +The structure refers to dividing a document into parts, chapters, sections, +and additional levels of structure. -Structuring of documents means to divide them into parts, chapters, sections, -and several other structural elements. \begin{Declaration} - \OptionVName{open}{method} + \OptionVName{open}{method} \end{Declaration}% -\OnlyAt{\Class{scrbook}\and\Class{scrreprt}}% -\KOMAScript{} classes \Class{scrbook} and \Class{scrreprt} give you the choice -of where to start\Index{chapter>start} a new chapter with double-sided -printing. By default \Class{scrreprt} starts a new chapter at the next -page. This is like \PName{method} \PValue{any}. However, \Class{scrbook} -starts new chapters at the next right-hand page. This is like \PName{method} -\PValue{right} and is usually used in books. But sometimes chapters should -start at the left-hand page of a double-page spread. This would be -accomplished with \PName{method} -\PValue{left}\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}}. An -overview of the supported methods may be found at -\autoref{tab:\LabelBase.open}. The table also describes the effect on -\DescRef{\LabelBase.cmd.cleardoublepage}, \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, -\DescRef{\LabelBase.cmd.cleardoublestandardpage}, \DescRef{\LabelBase.cmd.cleardoubleplainpage}, and -\DescRef{\LabelBase.cmd.cleardoubleemptypage} (see \autoref{sec:\LabelBase.emptypage}, +The\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} \KOMAScript{} classes +\Class{scrbook} and \Class{scrreprt} give you the choice of where to start a +new chapter with two-sided printing. By default \Class{scrreprt} starts a new +chapter\Index{chapter>start} on the next page. This is equivalent to +\PName{method} \PValue{any}. However, \Class{scrbook} starts new chapters at +the next right-hand page. This is equivalent to \PName{method} \PValue{right} +and is usually used in books. But sometimes chapters should start on the +left-hand page of a two-page spread. You can accomplish this with the +\PName{method} \PValue{left}\ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}}. You can find a summary of the available values in +\autoref{tab:\LabelBase.open}. The table also describes the effects of +\DescRef{\LabelBase.cmd.cleardoublepage}, +\DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, +\DescRef{\LabelBase.cmd.cleardoublestandardpage}, +\DescRef{\LabelBase.cmd.cleardoubleplainpage}, and +\DescRef{\LabelBase.cmd.cleardoubleemptypage} (see +\autoref{sec:\LabelBase.emptypage}, \DescPageRef{\LabelBase.cmd.cleardoublepage}). \begin{table} - \caption[{Available values for option \Option{open}}]{Available values for - option \Option{open} to select page breaks with interleaf pages using - \Class{scrbook} or \Class{scrreprt}} + \caption[{Available values for the \Option{open} option}]{Available values + for the \Option{open} option to select page breaks with interleaf pages + using \Class{scrbook} or \Class{scrreprt}} \begin{desctabular} \pventry{any}{% Parts, chapter, index, and back matter use - \DescRef{\LabelBase.cmd.clearpage} instead of - \DescRef{\LabelBase.cmd.cleardoublepage};% + \DescRef{\LabelBase.cmd.clearpage}, not + \DescRef{\LabelBase.cmd.cleardoublepage}; \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, \DescRef{\LabelBase.cmd.cleardoublestandardpage}, \DescRef{\LabelBase.cmd.cleardoubleplainpage}, \DescRef{\LabelBase.cmd.cleardoubleemptypage}, and - \DescRef{\LabelBase.cmd.cleardoublepage} behaves same like using + \DescRef{\LabelBase.cmd.cleardoublepage} behave the same as using \OptionValue{open}{right}.% - \IndexOption{open~=\PValue{any}}}% + \IndexOption{open~=\textKValue{any}}}% \pventry{left}{% - Part, chapter, index and back matter use - \DescRef{\LabelBase.cmd.cleardoublepage};% + Part, chapter, index, and back matter use + \DescRef{\LabelBase.cmd.cleardoublepage}; the commands \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, \DescRef{\LabelBase.cmd.cleardoublestandardpage}, \DescRef{\LabelBase.cmd.cleardoubleplainpage}, @@ -1127,10 +1333,10 @@ overview of the supported methods may be found at \DescRef{\LabelBase.cmd.cleardoublepage} result in a page break and add an interleaf page\Index{page>interleaf} if needed to reach the next left-hand page.% - \IndexOption{open~=\PValue{left}}}% + \IndexOption{open~=\textKValue{left}}}% \pventry{right}{% - Part, chapter, index and back matter use - \DescRef{\LabelBase.cmd.cleardoublepage};% + Part, chapter, index, and back matter use + \DescRef{\LabelBase.cmd.cleardoublepage}; the commands \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, \DescRef{\LabelBase.cmd.cleardoublestandardpage}, \DescRef{\LabelBase.cmd.cleardoubleplainpage}, @@ -1138,95 +1344,99 @@ overview of the supported methods may be found at \DescRef{\LabelBase.cmd.cleardoublepage} result in a page break and add an interleaf page\Index{page>interleaf} if needed to reach the next right-hand page.% - \IndexOption{open~=\PValue{right}}}% + \IndexOption{open~=\textKValue{right}}}% \end{desctabular} \label{tab:\LabelBase.open} \end{table} Since \LaTeX{} does not differentiate between left-hand and right-hand pages -in single-sided printing, the option does not have any influence in that case. +in one-sided printing, the option has no effect in that case. -In class \Class{scrartcl} the section is the first structural element below -the part. Because of this, \Class{scrartcl} does not support this option. +In the \Class{scrartcl} class, the section is the first structural element +below the part. For this reason, \Class{scrartcl} does not support this +option. % \EndIndexGroup \begin{Declaration} - \OptionVName{chapterprefix}{simple switch}% - \OptionVName{appendixprefix}{simple switch}% + \OptionVName{chapterprefix}{simple switch} + \OptionVName{appendixprefix}{simple switch} \Macro{IfChapterUsesPrefixLine}\Parameter{then code}\Parameter{else code} \end{Declaration}% With\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} the standard classes \Class{book} and \Class{report}, a chapter -title\Index[indexmain]{chapter>title} consists of a line with the word -``Chapter''\footnote{When using another language the word ``Chapter'' - is naturally translated to the appropriate language.} followed by -the chapter number. The title itself is set left-justified on the -following lines. The same effect is obtained in {\KOMAScript} with the -option \Option{chapterprefix}. Any value from table -\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch} may -be used as \PName{simple switch}. The default, however, is -\OptionValue{chapterprefix}{false}, which is opposite of the behaviour -of the standard classes, which would correspond to -\OptionValue{chapterprefix}{true}. -These options also affect the automatic -running titles in the headers (see \autoref{sec:\LabelBase.pagestyle}, +heading\Index[indexmain]{chapter>heading} consists of a line with the word +``Chapter''\footnote{When using another language the word ``Chapter'' is of +course translated to the appropriate language.} followed by the chapter +number. The heading itself is set left-justified on the following line. The +same effect is obtained in {\KOMAScript} with the \Option{chapterprefix} +option. You can use any value from \autoref{tab:truefalseswitch}, +\autopageref{tab:truefalseswitch} as the \PName{simple switch}. The default, +however, is \OptionValue{chapterprefix}{false}, the opposite +behaviour\textnote{\KOMAScript{} vs. standard classes} of that of the standard +classes, which corresponds to \OptionValue{chapterprefix}{true}. These options +also affect the automatic running heads in the headers (see +\autoref{sec:\LabelBase.pagestyle}, \DescPageRef{\LabelBase.pagestyle.headings}). -Sometimes one wishes to have the -chapter titles in simplified form according to -\OptionValue{chapterprefix}{false}. But at the same time, one wishes a title -of an appendix\Index{appendix} to be preceded by a line with ``Appendix'' -followed by the appendix letter. This is achieved by using the -\Option{appendixprefix} option (see \autoref{tab:truefalseswitch}, -\autopageref{tab:truefalseswitch}). Since this results in an inconsistent -document layout, I advise against using this option. Final consequence of -using the option is, that \DescRef{\LabelBase.cmd.appendix} changes setting of option -\Option{chapterprefix}. +Sometimes you may want to use the simplified chapter headings produced by +\OptionValue{chapterprefix}{false} but at the same time to have the heading of +an appendix\Index{appendix} preceded by a line with ``Appendix'' followed by +the appendix letter. This is achieved by using the \Option{appendixprefix} +option (see \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}). +Since this results in an inconsistent document layout, I advise against using +this option. Ultimately, this option changes the \Option{chapterprefix} option +automatically at the beginning of the \DescRef{\LabelBase.cmd.appendix}. You\ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}} can execute code depending on the current setting for the chapter preceding line using \Macro{IfChapterUsesPrefixLine}. If \Option{chapterprefix} is currently -active, the \PName{then code} will be executed, otherwise the \PName{else - code}. +active, the \PName{then code} is executed; otherwise, the \PName{else code} is +executed. -\BeginIndex{FontElement}{chapterprefix}\LabelFontElement{chapterprefix}% -The font style of the chapter number line using -\OptionValue{chapterprefix}{true} or \OptionValue{appendixprefix}{true} may be -changed with element +\BeginIndex{FontElement}{chapterprefix}% +You can change the font style of the chapter number line that uses +\OptionValue{chapterprefix}{true} or \OptionValue{appendixprefix}{true} +by using the \FontElement{chapterprefix}\ChangedAt{v2.96a}{\Class{scrbook}\and - \Class{scrreprt}} using commands \DescRef{\LabelBase.cmd.setkomafont} and -\DescRef{\LabelBase.cmd.addtokomafont} (see + \Class{scrreprt}} element with the \DescRef{\LabelBase.cmd.setkomafont} and +\DescRef{\LabelBase.cmd.addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}). Default is the usage of element -\DescRef{\LabelBase.fontelement.chapter}\IndexFontElement{chapter} (see -\DescPageRef{\LabelBase.cmd.chapter}, as well as +\DescPageRef{\LabelBase.cmd.setkomafont}). The default is to use the +\DescRef{\LabelBase.fontelement.chapter}\IndexFontElement{chapter} element +(see \DescPageRef{\LabelBase.cmd.chapter}, as well as \autoref{tab:\LabelBase.structureElementsFont}, -\autopageref{tab:\LabelBase.structureElementsFont}).% +\autopageref{tab:\LabelBase.structureElementsFont}). + +You can find additional settings for chapter headings in the explanation for +\DescRef{maincls-experts.cmd.RedeclareSectionCommand} and the commands +\DescRef{maincls-experts.cmd.chapterlineswithprefixformat} and +\DescRef{maincls-experts.cmd.chapterlinesformat} in +\autoref{sec:maincls-experts.experts}, \autoref{part:forExperts}.% \EndIndexGroup \begin{Declaration} - \OptionVName{headings}{selection} -\end{Declaration}% -The font size used for the titles\index{title}\index{document structure} is -relatively big, both with the standard classes and with {\KOMAScript}. Not -everyone likes this choice; moreover it is especially problematic for small -paper sizes. Consequently, {\KOMAScript} provides, besides the large title -font size defined by the -\OptionValue{headings}{big}\IndexOption{headings~=\PValue{big}}% + \OptionVName{headings}{setting} +\end{Declaration} +Headings\index{heading}\index{document structure} of sectioning levels +normally use a relatively large font size in both the standard classes and +{\KOMAScript}. This choice does not appeal to everyone and is especially +problematic for small paper sizes. Consequently, {\KOMAScript} provides, in +addition to the large headings defined by the +\OptionValue{headings}{big}\IndexOption{headings~=\textKValue{big}}% \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% -\important[i]{\OptionValue{headings}{big}\\ +\important{\OptionValue{headings}{big}\\ \OptionValue{headings}{normal}\\ - \OptionValue{headings}{small}} option, the two options -\OptionValue{headings}{normal}\IndexOption{headings~=\PValue{normal}} and -\OptionValue{headings}{small}\IndexOption{headings~=\PValue{small}}, that -allow for smaller title font sizes. The font sizes for headings resulting from -these options for \Class{scrbook} and \Class{scrreprt} are shown in + \OptionValue{headings}{small}} option, the options +\OptionValue{headings}{normal}\IndexOption{headings~=\textKValue{normal}} and +\OptionValue{headings}{small}\IndexOption{headings~=\textKValue{small}}, which +allow for smaller headings. The font sizes resulting from these options for +\Class{scrbook} and \Class{scrreprt} are shown in \autoref{tab:\LabelBase.structureElementsFont}, -\autopageref{tab:\LabelBase.structureElementsFont}. Respectively, the fonts of -the elements \DescRef{\LabelBase.fontelement.chapter}% +\autopageref{tab:\LabelBase.structureElementsFont}. Specifically, all three +settings reset the elements \DescRef{\LabelBase.fontelement.chapter}% \IndexFontElement{chapter}, \DescRef{\LabelBase.fontelement.section}\IndexFontElement{section}, \DescRef{\LabelBase.fontelement.subsection}\IndexFontElement{subsection}, @@ -1234,158 +1444,193 @@ the elements \DescRef{\LabelBase.fontelement.chapter}% \IndexFontElement{subsubsection}, \DescRef{\LabelBase.fontelement.paragraph}\IndexFontElement{paragraph}, and \DescRef{\LabelBase.fontelement.subparagraph}\IndexFontElement{subparagraph} -will be reset to these default. - -For \Class{scrartcl}, smaller -font sizes are generally used. \OnlyAt{\Class{scrbook}\and - \Class{scrreprt}}The spacing before and after chapter titles is also -influenced by these options. - -Chapter\important[i]{\begin{tabular}[t]{@{}l@{}} - \Option{headings=}\\ \quad\PValue{twolinechapter}\end{tabular}\\ - \begin{tabular}[t]{@{}l@{}} - \Option{headings=}\\ \quad\PValue{onelinechapter}\end{tabular}\\ - \begin{tabular}[t]{@{}l@{}} - \Option{headings=}\\ \quad\PValue{twolineappendix}\end{tabular}} -titles are also influenced by the options -\OptionValue{headings}{twolinechapter} and -\OptionValue{headings}{onelinechapter}, that are same as -\OptionValueRef{\LabelBase}{chapterprefix}{true} and -\OptionValueRef{\LabelBase}{chapterprefix}{false} (see above). The appendix -titles are influenced by \OptionValue{headings}{twolineappendix} and -\OptionValue{headings}{onelineappendix}\important[i]{% - \begin{tabular}[b]{@{}l@{}} - \Option{headings=}\\ \quad\PValue{onelineappendix} - \end{tabular}}, that are the same as the options -\OptionValueRef{\LabelBase}{appendixprefix}{true} and -\OptionValueRef{\LabelBase}{appendixprefix}{false} (see also above). - -The\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} method of beginning new -chapters may be switched by \OptionValue{headings}{openany}\important[i]{% +to the corresponding defaults. \Class{scrartcl}\OnlyAt{\Class{scrbook}\and + \Class{scrreprt}} generally uses slightly smaller headings. The spacing +before and after chapter headings is also reset by these options. + +\iffalse% + Chapter headings also have the \Option{headings} option with the + \PValue{twolinechapter} or \PValue{onelinechapter} settings, which are + equivalent to the + \OptionValueRef{\LabelBase}{chapterprefix}{true} and + \OptionValueRef{\LabelBase}{chapterprefix}{false} options. In the appendix + there are additional effects of the \PValue{onelineappendix} and + \PValue{twolineappendix} options upon the \Option{headings} option, which + corresponds to + \OptionValueRef{\LabelBase}{appendixprefix}{false} and + \OptionValueRef{\LabelBase}{appendixprefix}{true} (see also + above). % +\else% + Chapter headings\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} also + have\important{% + \OptionValue{headings}{twolinechapter}\\ + \OptionValue{headings}{onelinechapter}\\ + \OptionValue{headings}{twolineappendix}\\ + \OptionValue{headings}{onelineappendix}% + } the two options \OptionValue{headings}{twolinechapter} and + \OptionValue{headings}{onelinechapter}, which correspond to + \OptionValueRef{\LabelBase}{chapterprefix}{true} and + \OptionValueRef{\LabelBase}{chapterprefix}{false} explained above. For the + appendix, + \OptionValueRef{\LabelBase}{appendixprefix}{true} and + \OptionValueRef{\LabelBase}{appendixprefix}{false} serve as alternatives for + the \OptionValue{headings}{twolineappendix} and + \OptionValue{headings}{onelineappendix} options. % + \iffalse% + For the appendix, \OptionValue{headings}{twolineappendix} and + \OptionValue{headings}{onelineappendix} are available, which correspond to + the \OptionValueRef{\LabelBase}{appendixprefix}{true} and + \OptionValueRef{\LabelBase}{appendixprefix}{false} options (also see above). + \fi% + Of course, these options do not exist with \Class{scrartcl}% + \iffree{}{% Umbruchkorrekturtext + , since this class does not have chapters}% + .% +\fi + +The\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} \OptionValue{headings}{standardclasses}% +\important{\OptionValue{headings}{standardclasses}} option adjusts the font +sizes of the headings to those of the standard classes. In addition, the font +for the \DescRef{\LabelBase.fontelement.disposition}% +\IndexFontElement{disposition} element is set to \Macro{bfseries}. It +therefore no longer uses a sans-serif font for the headings. If you use +\Class{scrbook}\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} or +\Class{scrreprt}, \OptionValue{headings}{twolinechapter} is also set and the +spacing between the chapter headings is adjusted to that of the standard +classes. + +You\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} can set the method to specify +the page on which new chapters begin with +\OptionValue{headings}{openany}\important{% \OptionValue{headings}{openany}\\ \OptionValue{headings}{openright}\\ \OptionValue{headings}{openleft}}, \OptionValue{headings}{openright}, and -\OptionValue{headings}{openleft} alternatively to option -\DescRef{\LabelBase.option.open} with the values \PValue{any}, +\OptionValue{headings}{openleft}, or alternatively with the +\DescRef{\LabelBase.option.open} option, which takes the values \PValue{any}, \PValue{right}, and \PValue{left} (see above). Another\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} special feature of \KOMAScript{} is the handling of the -optional argument of the structural commands \DescRef{\LabelBase.cmd.part}, \DescRef{\LabelBase.cmd.chapter}, -etc., down to \DescRef{\LabelBase.cmd.subparagraph}. Function and -meaning\important[i]{% - \begin{tabular}[t]{@{}l@{}} - \Option{headings=}\\\quad\PValue{optiontohead} - \end{tabular}\\ +optional argument of the sectioning commands \DescRef{\LabelBase.cmd.part}, +\DescRef{\LabelBase.cmd.chapter}, etc. down to +\DescRef{\LabelBase.cmd.subparagraph}. You can change its function and +meaning\important{\OptionValue{headings}{optiontohead}\\ \OptionValue{headings}{optiontotoc}\\ - \begin{tabular}[t]{@{}l@{}} - \Option{headings=}\\\quad\PValue{optiontoheadandtoc} - \end{tabular}% -} may be influenced by the options \OptionValue{headings}{optiontohead}% -\IndexOption{headings~=\PValue{optiontohead}}, -\OptionValue{headings}{optiontotoc}\IndexOption{headings~=\PValue{optiontotoc}}, -and \OptionValue{headings}{optiontoheadandtoc}% -\IndexOption{headings~=\PValue{optiontoheadandtoc}}. - -A summary of all the available selections of option \Option{headings} may be -found in \autoref{tab:\LabelBase.headings}. Examples are at the following -description of the structural commands. - + \OptionValue{headings}{optiontoheadandtoc}} with the options +\OptionValue{headings}{optiontohead}% +\IndexOption{headings~=\textKValue{optiontohead}}, +\OptionValue{headings}{optiontotoc}% +\IndexOption{headings~=\textKValue{optiontotoc}} and +\OptionValue{headings}{optiontoheadandtoc}% +\IndexOption{headings~=\textKValue{optiontoheadandtoc}}. + +See \autoref{tab:\LabelBase.headings} for a summary of all available settings +for the \Option{headings} option. The explanations of the sectioning commands +below contain examples using some of these settings. \begin{desclist} - \renewcommand*{\abovecaptionskipcorrection}{-\normalbaselineskip}% - \desccaption[{Available values for option \Option{headings}}]{% - Available values for option \Option{headings} to select different kinds of - structural headings% + \desccaption[{Available values for the \Option{headings} option}]{% + Available values for the \Option{headings} option to format + section headings% \label{tab:\LabelBase.headings}% }{% - Available values for option \Option{headings} (\emph{continuation})% + Available values for the \Option{headings} option (\emph{continued})% }% \pventry{big}{% - Use very large headings with large distances above and below. - \IndexOption{headings~=\PValue{big}}}% + Use large fonts in the headings for each of the default sectioning levels + with wide spacing above and below the titles. + \IndexOption{headings~=\textKValue{big}}}% \pventry{normal}{% - Use mid-size headings with medium distances above and below. - \IndexOption{headings~=\PValue{normal}}}% + Use medium-sized fonts in the headings with medium spacing above and below + the titles. \IndexOption{headings~=\textKValue{normal}}}% \entry{\PValue{onelineappendix}, \PValue{noappendixprefix}, \PValue{appendixwithoutprefix}, \PValue{appendixwithoutprefixline}% - \IndexOption{headings~=\PValue{onelineappendix}}}{% - Chapter headings at the appendix will be set like other headings too.% + \IndexOption{headings~=\textKValue{onelineappendix}}}{% + Chapter headings in the appendix are set like other headings.% }% \entry{\PValue{onelinechapter}, \PValue{nochapterprefix}, \PValue{chapterwithoutprefix}, \PValue{chapterwithoutprefixline}% - \IndexOption{headings~=\PValue{onelinechapter}}}{% - Chapter headings will be set like other headings too.% + \IndexOption{headings~=\textKValue{onelinechapter}}}{% + Chapter titles are set like other headings.% }% \pventry{openany}{% The commands \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, \DescRef{\LabelBase.cmd.cleardoublestandardpage}, \DescRef{\LabelBase.cmd.cleardoubleplainpage}, \DescRef{\LabelBase.cmd.cleardoubleemptypage}, and - \DescRef{\LabelBase.cmd.cleardoublepage} behave same like using - \OptionValue{headings}{openright}.% - Parts, chapter, index, and back matter use - \DescRef{\LabelBase.cmd.clearpage} instead of + \DescRef{\LabelBase.cmd.cleardoublepage} generate a page break and insert + an interleaf page\Index{interleaf page} if needed to reach the next + right-hand page in two-sided printing, the same as in + \OptionValue{headings}{openright}. Parts, chapter, the index, and back + matter use \DescRef{\LabelBase.cmd.clearpage} instead of \DescRef{\LabelBase.cmd.cleardoublepage}.% - \IndexOption{headings~=\PValue{openany}}}% + \IndexOption{headings~=\textKValue{openany}}}% \pventry{openleft}{% The commands \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, \DescRef{\LabelBase.cmd.cleardoublestandardpage}, \DescRef{\LabelBase.cmd.cleardoubleplainpage}, \DescRef{\LabelBase.cmd.cleardoubleemptypage}, and - \DescRef{\LabelBase.cmd.cleardoublepage} generate a page break and if - needed insert an interleaf page to reach the next left-hand page at - double-page printing.% - Part, chapter, index and back matter use + \DescRef{\LabelBase.cmd.cleardoublepage} generate a page break and insert + an interleaf page if needed to reach the next left-hand page in two-sided + printing. Part, chapter, index and back matter use \DescRef{\LabelBase.cmd.cleardoublepage}.% - \IndexOption{headings~=\PValue{openleft}}}% + \IndexOption{headings~=\textKValue{openleft}}}% \pventry{openright}{% The commands \DescRef{\LabelBase.cmd.cleardoublepageusingstyle}, \DescRef{\LabelBase.cmd.cleardoublestandardpage}, \DescRef{\LabelBase.cmd.cleardoubleplainpage}, \DescRef{\LabelBase.cmd.cleardoubleemptypage}, and - \DescRef{\LabelBase.cmd.cleardoublepage} generate a page break and if - needed insert an interleaf page to reach the next right-hand page at - double-page printing.% - Part, chapter, index and back matter use + \DescRef{\LabelBase.cmd.cleardoublepage} generate a page break and insert + an interleaf page if needed to reach the next right-hand page in two-sided + printing. Part, chapter, index and back matter use \DescRef{\LabelBase.cmd.cleardoublepage}.% - \IndexOption{headings~=\PValue{openright}}}% + \IndexOption{headings~=\textKValue{openright}}}% \pventry{optiontohead}{% The\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} advanced functionality of the optional argument of the - structural commands \DescRef{\LabelBase.cmd.part} down to \DescRef{\LabelBase.cmd.subparagraph} will be - activated. By default the optional argument will be used for the running - head only.% - \IndexOption{headings~=\PValue{optiontohead}}% + sectioning commands \DescRef{\LabelBase.cmd.part} down to + \DescRef{\LabelBase.cmd.subparagraph} is activated. By default, the + optional argument is used only for the running head.% + \IndexOption{headings~=\textKValue{optiontohead}}% }% \entry{\PValue{optiontoheadandtoc}, \PValue{optiontotocandhead}% - \IndexOption{headings~=\PValue{optiontoheadandtoc}}}{% + \IndexOption{headings~=\textKValue{optiontoheadandtoc}}}{% The\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} advanced functionality of the optional argument of the - structural commands \DescRef{\LabelBase.cmd.part} down to \DescRef{\LabelBase.cmd.subparagraph} will be - activated. By default the optional argument will be used for the running - head and the table of contents.% + sectioning commands \DescRef{\LabelBase.cmd.part} down to + \DescRef{\LabelBase.cmd.subparagraph} is activated. By default, the + optional argument is used for the running head and the table of contents.% }% \pventry{optiontotoc}{% The\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} advanced functionality of the optional argument of the - structural commands \DescRef{\LabelBase.cmd.part} down to \DescRef{\LabelBase.cmd.subparagraph} will be - activated. By default the optional argument will be used for the table of - contents only.% - \IndexOption{headings~=\PValue{optiontohead}}% + sectioning commands \DescRef{\LabelBase.cmd.part} down to + \DescRef{\LabelBase.cmd.subparagraph} is activated. By default, the + optional argument is used only for the table of contents.% + \IndexOption{headings~=\textKValue{optiontohead}}% }% \pventry{small}{% - Use small headings with small distances above and below.% - \IndexOption{headings~=\PValue{small}}}% + Use small fonts in the headings with small spacing above and below the + titles.% + \IndexOption{headings~=\textKValue{small}}}% + \pventry{standardclasses}{% + \ChangedAt{v3.12}{\Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}}% + Reset the font settings for each of the standard sectioning levels and use + headings with the sizes of the standard classes. For chapter headings, + \Class{scrbook} und \Class{scrreprt} set + \OptionValue{headings}{twolinechapter}.% + }% \entry{\PValue{twolineappendix}, \PValue{appendixprefix}, \PValue{appendixwithprefix}, \PValue{appendixwithprefixline}% - \IndexOption{headings~=\PValue{twolineappendix}}}{% - Chapters at the appendix will be set with a number line with the contents - of \DescRef{\LabelBase.cmd.chapterformat}\IndexCmd{chapterformat}.% + \IndexOption{headings~=\textKValue{twolineappendix}}}{% + Chapter titles in the appendix are set with a number line whose format is + determined by + \DescRef{\LabelBase.cmd.chapterformat}\IndexCmd{chapterformat}.% }% \entry{\PValue{twolinechapter}, \PValue{chapterprefix}, \PValue{chapterwithprefix}, \PValue{chapterwithprefixline}% - \IndexOption{headings~=\PValue{twolinechapter}}}{% - Chapters will be set with a number line with the contents of + \IndexOption{headings~=\textKValue{twolinechapter}}}{% + Chapter titles are set with a number line whose format is determined by \DescRef{\LabelBase.cmd.chapterformat}\IndexCmd{chapterformat}.% }% \end{desclist} @@ -1394,66 +1639,60 @@ description of the structural commands. \begin{Declaration} - \OptionVName{numbers}{selection} + \OptionVName{numbers}{setting} \end{Declaration}% -\begin{Explain}% - In German, according to {\small DUDEN}, the numbering of sectional - units should have no period at the end if only arabic numbers are used - (see \cite[R\,3]{DUDEN}). On the other hand, if roman numerals or - letters are appear in the numbering, then a period should appear at the - end of the numbering (see \cite[R\,4]{DUDEN}). {\KOMAScript} has an - internal mechanism that tries to implement this somewhat complex - rule. The resulting effect is that, normally, after the sectional - commands \DescRef{\LabelBase.cmd.part} and \DescRef{\LabelBase.cmd.appendix} a switch is made to - numbering with an ending period. The information is saved in the - \File{aux} file and takes effect on the next {\LaTeX} run. -\end{Explain} - -In some cases the mechanism for placing or leaving off the ending period may -fail, or other languagues may have different -rules. Therefore\important[i]{\OptionValue{numbers}{endperiod}\\ - \OptionValue{numbers}{noendperiod}} it is possible to activate the use of -the ending period manually with the option -\OptionValue{numbers}{endperiod}\IndexOption{numbers~=\PValue{endperiod}} or -to deactivate it with -\OptionValue{numbers}{noendperiod}\IndexOption{numbers~=\PValue{noendperiod}}. -Default is \OptionValue{numbers}{autoendperiod}% -\IndexOption{numbers~=\PValue{autoendperiod}} with auto detection whether to -set the period or not. - -Please\textnote{Attention!} note that the mechanism only takes effect on the -next {\LaTeX} run. Therefore, before trying to use these options to forcibly -control the numbering format, a further run without changing any options -should be made. - -The\textnote{Attention!} available values are summarized in -\autoref{tab:\LabelBase.numbers}. Unlike most other selections, this -option may be changed at the document preamble, before -\Macro{begin}\PParameter{document}, only. +According to {\small DUDEN}, if only Arabic numerals are used to number +section headings\Index{headings}, the German practice is to have no point at +the end (see \cite[R\,3]{DUDEN}). On the other hand, if Roman numerals or +letters appear in the numbering, then a point should appear at the end of the +numbering (see \cite[R\,4]{DUDEN}). {\KOMAScript} has a mechanism that tries +to automate this somewhat complex rule. The result is that normally after +the sectioning commands \DescRef{\LabelBase.cmd.part} and +\DescRef{\LabelBase.cmd.appendix} the numbering switches to using a final +point. This information is saved in the \File{aux} file and takes effect on +the next {\LaTeX} run. + +Sometimes the mechanism for placing or omitting the final point may fail. +Sometimes other languages have different rules. Therefore you can force the +use of the final point with the option +\OptionValue{numbers}{endperiod}\IndexOption{numbers~=\textKValue{endperiod}}% +\important{\OptionValue{numbers}{endperiod}\\ +\OptionValue{numbers}{noendperiod}} or to prohibit it with +\OptionValue{numbers}{noendperiod}. + +Note\textnote{Attention!} that this mechanism only takes effect on the +next {\LaTeX} run. Therefore, before you try to use these options to force +the correct numbering format, you should always perform another \LaTeX{} run +without modifying the document. + +You can find a summary of the available values for the \PName{setting} of +\PName{numbers} in \autoref{tab:\LabelBase.numbers}. Unlike most other +settings, this option can only be set in the document preamble, i.\,e. before +\Macro{begin}\PParameter{document}. \begin{table} - \caption[{Available values of option \Option{numbers}}]{Available values of - option \Option{numbers} for selection of the period at the end of numbers - of structural headings} + \caption[{Available values for the \Option{numbers} option}]{Available values + of the \Option{numbers} option to configure the final points of the + numbers for section headings} \label{tab:\LabelBase.numbers} \begin{desctabular} \entry{\PValue{autoendperiod}, \PValue{autoenddot}, \PValue{auto}}{% - \KOMAScript{} decides, whether or not to set the period at the end of - the numbers. The numbers consists in Arabic digits only, the period will - be omitted. If there are alphabetic characters or roman numbers the - period will always be set. References to numbers will be set without - ending period always.% - \IndexOption{numbers~=\PValue{autoendperiod}}}% + \KOMAScript{} decides whether to set the point at the end of sectioning + command numbers. If there are only Arabic numerals, the point will + be omitted. If a letter or Roman numeral is found, the + point is set. However, references to these numbers are set without + a final point.% + \IndexOption{numbers~=\textKValue{autoendperiod}}}% \entry{\PValue{endperiod}, \PValue{withendperiod}, \PValue{periodatend}, \PValue{enddot}, \PValue{withenddot}, \PValue{dotatend}}{% - All numbers of structural commands and all dependent numbers will be set - with ending period. Only references will be set without the ending - period.% - \IndexOption{numbers~=\PValue{endperiod}}}% + All numbers of sectioning commands and their subordinate numbers are set + with a final point. Only references will be set without the final + point.% + \IndexOption{numbers~=\textKValue{endperiod}}}% \entry{\PValue{noendperiod}, \PValue{noperiodatend}, \PValue{noenddot}, \PValue{nodotatend}}{% - All the numbers are without ending period.% - \IndexOption{numbers~=\PValue{noendperiod}}}% + All numbers of sectioning commands are set without a final point.% + \IndexOption{numbers~=\textKValue{noendperiod}}}% \end{desctabular} \end{table} % @@ -1466,27 +1705,36 @@ option may be changed at the document preamble, before \end{Declaration}% As mentioned in \autoref{sec:\LabelBase.floats}, \DescPageRef{\LabelBase.option.listof}\OnlyAt{\Class{scrbook}\and - \Class{scrreprt}}, normally, every chapter entry generated with -\DescRef{\LabelBase.cmd.chapter} introduces vertical spacing into the lists of floats. Since -version~2.96a\ChangedAt{v2.96a}{\Class{scrbook}\and \Class{scrreprt}} this -applies also for the command \DescRef{\LabelBase.cmd.addchap}, if no compatibility option to an -earlier version was chosen (see option \DescRef{\LabelBase.option.version} in + \Class{scrreprt}}, every chapter that is created with +\DescRef{\LabelBase.cmd.chapter} normally inserts a vertical space in the +lists of floating environments (e.\,g., tables and figures). +Since version~2.96a,\important{\OptionValueRef{\LabelBase}{version}{2.96a}}% +\ChangedAt{v2.96a}{\Class{scrbook}\and \Class{scrreprt}} this also applies to +the \DescRef{\LabelBase.cmd.addchap} command unless you choose a compatibility +setting for an earlier version (see the \DescRef{\LabelBase.option.version} +option in \autoref{sec:\LabelBase.compatibilityOptions}, +\DescPageRef{\LabelBase.option.version}). + +In addition, you can use the \Option{chapteratlists} option to change the +vertical spacing by specifying the desired distance as the \PName{value}. +The default with \OptionValueRef{\LabelBase}{listof}{chaptergapsmall}% +\IndexOption{listof~=\textKValue{chaptergapsmall}} % +is 10\Unit{pt} (see the\DescRef{\LabelBase.option.version} option in \autoref{sec:\LabelBase.compatibilityOptions}, \DescPageRef{\LabelBase.option.version}). -Furthermore, now the option \Option{chapteratlists} can be used to change the -spacing, by passing the desired distance as \PName{value}. The default setting -with \OptionValueRef{\LabelBase}{listof}{chaptergapsmall}% -\IndexOption{listof~=\PValue{chaptergapsmall}} % -is 10\,pt. If \OptionValue{chapteratlists}{entry}% -\IndexOption{chapteratlists~=\PValue{entry}}% +If you use \OptionValue{chapteratlists}{entry}% +\IndexOption{chapteratlists~=\textKValue{entry}}% \important{\OptionValue{chapteratlists}{entry}} or \Option{chapteratlists} -without value is specified, then instead of a vertical distance, the chapter -entry itself will be entered into the lists. This will be done even if -there's no floating environment inside of the chapter. - -Please\textnote{Attention!} note that changes to the option will only become -effective in the lists following two more {\LaTeX} runs.% +without specifying a value, instead of a vertical space, the chapter entry +itself will be entered into the lists. Note that such an entry occurs even if +the chapter does not contain a floating environment. A method where only +chapters with floating environments are displayed in the respective list can +be found in the German-language \KOMAScript{} forum at +\cite{https://komascript.de/comment/5070}. + +Please\textnote{Attention!} note that changes to this option only takes +effect after two additional {\LaTeX} runs.% % \EndIndexGroup @@ -1503,218 +1751,227 @@ effective in the lists following two more {\LaTeX} runs.% \Index[indexmain]{part}% \Index[indexmain]{chapter}% \Index[indexmain]{section}% -The standard sectioning commands in {\KOMAScript} work in a similar -fashion to those of the standard classes. Thus, an alternative entry -for the table of contents and running headings can be specified as an -optional argument to the sectioning commands. - -In addition to this, with\ChangedAt{v3.10}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}}\textnote{\KOMAScript{} vs. standard - classes} option \important{\DescRef{\LabelBase.option.headings}} +The standard sectioning commands in {\KOMAScript} work the same way as those +in the standard classes. Thus, you can specify an alternative text for the +table of contents and running heads as an optional argument to the sectioning +commands. + +However, with\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\textnote{\KOMAScript{} vs. standard classes} the +\important{\DescRef{\LabelBase.option.headings}} \OptionValueRef{\LabelBase}{headings}{optiontohead}% -\IndexOption[indexmain]{headings~=\PValue{optiontohead}}, \KOMAScript{} -does not use -the optional argument \PName{short version} at the table of -contents, but for the running head only. Nevertheless, such a running head -needs an appropriate page style. See \autoref{sec:\LabelBase.pagestyle} and -\autoref{cha:scrlayer-scrpage} about this. With option +\IndexOption[indexmain]{headings~=\textKValue{optiontohead}} option, +\KOMAScript{} only uses the optional argument \PName{short version} in the +running head, not the table of contents. Of course, this text will only appear +if you use a page style\Index{page>style} that puts the corresponding +sectioning level in the running head. See \autoref{sec:\LabelBase.pagestyle} +and \autoref{cha:scrlayer-scrpage}. With the \OptionValueRef{\LabelBase}{headings}{optiontotoc}% -\IndexOption[indexmain]{headings~=\PValue{optiontotoc}}, \KOMAScript{} does not -use the -optional argument \PName{short version} for the running head, but -at the table of contents. Nevertheless, the entry will be shown only if -counter \DescRef{\LabelBase.counter.tocdepth} (see \autoref{sec:\LabelBase.toc}, -\DescPageRef{\LabelBase.counter.tocdepth}) is great enough. With option +\IndexOption[indexmain]{headings~=\textKValue{optiontotoc}} option, +\KOMAScript{} uses the optional argument \PName{short version} exclusively for +the table of contents and not the running head. However, the entry will be +shown only if the \DescRef{\LabelBase.counter.tocdepth} counter is great +enough (see \autoref{sec:\LabelBase.toc}, +\DescPageRef{\LabelBase.counter.tocdepth}). With the \OptionValueRef{\LabelBase}{headings}{optiontoheadandtoc}% -\IndexOption[indexmain]{headings~=\PValue{optiontoheadandtoc}}, \KOMAScript{} -uses the optional argument \PName{short version} in both the table of contents -and running head. All these three selections will also activate the extended -interpretation of the optional argument \PName{short version}, which is not -active by default. +\IndexOption[indexmain]{headings~=\textKValue{optiontoheadandtoc}} option, +\KOMAScript{} uses the optional argument \PName{short version} in both the +table of contents and the running head. These three options all activate the +extended interpretation of the optional argument \PName{short version}, which +is not active by default. The \ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} extended interpretation of the optional argument -determines whether there's an equality sign in \PName{short version}. If so, -the optional argument will be interpreted as \PName{option list} instead of -simple \PName{short version}. Thereby the three options -\OptionVName{head}{running head}\important{\Option{head}}, -\OptionVName{tocentry}{table of contents entry}\important{\Option{tocentry}}, -and \OptionVName{reference}{reference title}\important{\Option{reference}}% -\ChangedAt{v3.22}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -are supported. Commas or equality signs inside of the values of those options -will be accepted only if they are enclosed by braces. - -Please\textnote{Attention!} note that this mechanism is only -functional as long as \KOMAScript{} controls the described -commands. From using a package that controls the sectioning commands -or the internal \LaTeX{} kernel commands for sectioning commands, -\KOMAScript{} can no longer provide this extended mechanism. This is -also valid for the always active extension of \KOMAScript{} to not -create entries to the table of contents % if the heading text -if the text of the -entry is empty. If you really want an entry with empty heading text, -you may use an invisible entry like \lstinline|\mbox{}| instead. +checks to see if there is an equals sign in \PName{short version}. If so, +the optional argument will be interpreted as an \PName{option list}. +Three options\,---\,\OptionVName{head}{running head}\important{\Option{head}\\ + \Option{tocentry}\\ + \Option{reference}}, \OptionVName{tocentry}{table of contents entry}, and +\OptionVName{reference}{reference title}% +\ChangedAt{v3.22}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% +\,---\,are supported with this format. To use commas or equals signs +within the values of those options, you must enclose them in braces. + +Please\textnote{Attention!} note that this mechanism only works as long as +\KOMAScript{} controls the sectioning commands. If you use package that +redefines the \KOMAScript{}'s or the internal \LaTeX{} kernel's sectioning +commands, \KOMAScript{} can no longer provide this extended mechanism. This +also applies to a \KOMAScript{} that is always active: sectioning commands +with no heading text\textnote{empty headings} do not create entries in the +table of contents. If you really want an entry with empty heading text, you +can use an invisible entry like \lstinline|\mbox{}|. \begin{Example} - Assume you're writing a document with some very extensive chapter - headings. These headings should be shown in the table of contents too. But - for the running head you want only single-line short headings. You will do - this using the optional argument of \Macro{chapter}. + Suppose you have a document with very long chapter headings. These headings + should appear in the table of contents, but you want to limit the running + head to short, single-line headings. You can do this with the optional + argument of \Macro{chapter}. \begin{lstcode} \chapter[short version of chapter heading] - {The Structural Sectioning Command - for Chapters Supports not only the - Heading Text itself but also a - Short Version with Selectable - Usage} + {The Sectioning Command for Chapters + Supports not only the Heading Text + Itself but also a Short Version Whose + Use can be Controlled} \end{lstcode} - Sometimes later you become aware that the automatic line breaking of this - heading is somehow inappropriate. Therefore you want to make the breaking - yourself. Nevertheless, the automatic line breaking should be still used at - the table of contents. With + A little later you realize that the line breaks for this long heading are + very inappropriate. You therefore want to choose the breaks + yourself. Nevertheless, you still want automatic line breaking in the table + of contents. With \begin{lstcode} \chapter[head={short version of chapter heading}, - tocentry={The Structural Sectioning + tocentry={The Sectioning Command for Chapters Supports not - only the Heading Text itself but - also a Short Version with - Selectable Usage}] - {The Structural\\ - Sectioning Command for Chapters\\ + only the Heading Text Itself but + also a Short Version Whose Use + can be Controlled}] + {The Sectioning\\ + Command for Chapters\\ Supports not only\\ - the Heading Text itself\\ + the Heading Text Itself\\ but also\\ - a Short Version\\ - with Selectable Usage} + a Short Version Whose\\ + Use can be Controlled} \end{lstcode} - you use independent entries for table of contents, running head, and the + you create separate entries for the table of contents, running head, and chapter heading itself. The arguments of the options \Option{head} and - \Option{tocentry} have been enclosed into braces, so the contents of the - options cannot influence the interpretation of the optional argument. + \Option{tocentry} have been enclosed in braces so their contents + can be arbitrary. - The recommendation of the braces in the example above will make more sense - with one more example. Assume you're using option - \OptionValueRef{\LabelBase}{headings}{optiontotoc} and now have a heading: + The need for braces in the example above is best illustrated by another + example. Suppose you chose the + \OptionValueRef{\LabelBase}{headings}{optiontotoc} option and set the title + this way: \begin{lstcode} \section[head=\emph{value}] {Option head=\emph{value}} \end{lstcode} - This would result in the entry ``Option head=\emph{value}'' at the table of - contents but ``\emph{value}'' at the running head. But surely you wanted the - entry ``head=\emph{value}'' at the table of contents and the complete - heading text at the running head. You may do this using braces: + This results in the entry ``Option head=\emph{value}'' in the table of + contents but ``\emph{value}'' in the running head. But surely you wanted the + entry ``head=\emph{value}'' in the table of contents and the complete + heading text in the running head. You can do this using braces: \begin{lstcode} \section[head{=}\emph{value}] {Option head=\emph{value}} \end{lstcode} - A similar case would be a comma. With the same - \DescRef{\LabelBase.option.headings} option like before: + A similar case concerns the comma. Using the same + \DescRef{\LabelBase.option.headings} option as before \begin{lstcode} \section[head=0, 1, 2, 3, \dots] {Natural Numbers Including the Zero} \end{lstcode} - would result in an error, because the comma would be interpreted as the - separator between the single options of the option list % + results in an error because the comma is interpreted as the + separator between the individual options of the option list % ``\lstinline|0, 1, 2, 3, \dots|''. But writing \begin{lstcode} \section[head={0, 1, 2, 3, \dots}] {Natural Numbers Including the Zero} \end{lstcode} - will change ``\lstinline|0, 1, 2, 3, \dots|'' into the argument of - option \Option{head}. + makes ``\lstinline|0, 1, 2, 3, \dots|'' the argument of + the \Option{head} option. \end{Example} -Similar\ChangedAt{v3.22}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} to setup the title of a running head using option -\Option{head} or to setup the title for the entry to the table of contents -using option \Option{tocentry} you can set the title of a reference with -package \Package{nameref}\IndexPackage{nameref}, -\Package{titleref}\IndexPackage{titleref}, or the -\Package{titleref}\IndexPackage{zref-titleref} module of package -\Package{zref}\IndexPackage{zref} using option \Option{reference}. Note, the -support for package \Package{titleref} is somehow rudimentary, and the package -is not fully compatible with \Package{hyperref}\IndexPackage{hyperref}. - -The title of the level part\important{\Macro{part}} (\Macro{part}) is -distinguished from other sectioning levels by being numbered independently -from the other parts. This means that the chapter level (in \Class{scrbook} or -\Class{scrreprt}), or the section level (in \Class{scrartcl}) is numbered -consecutively over all parts. Furthermore, for classes -\Class{scrbook}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} and -\Class{scrreprt}, the title of the part level together with the corresponding -preamble (see \Macro{setpartpreamble}, +Like\ChangedAt{v3.22}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} setting the title of a running head with the \Option{head} +option, or setting the title of a table-of-contents entry with the +\Option{tocentry} option, you can set the title of a reference with the +\Package{nameref}\IndexPackage{nameref}\important{\Package{nameref}\\ + \Package{titleref}\\ + \Package{zref-titleref}} or +\Package{titleref}\IndexPackage{titleref} packages, or with the +\Package{titleref}\IndexPackage{zref-titleref} module of the +\Package{zref}\IndexPackage{zref} package, using the \Option{reference}% +\important{\Option{reference}} option. Note that the support for the +\Package{titleref} package is rather rudimentary, since that package's +performance is poor compared to the other two, and it is not fully compatible +with \Package{hyperref}\IndexPackage{hyperref}\important{\Package{hyperref}}. + +The part-level title\important{\Macro{part}} (\Macro{part}) differs from other +sectioning levels by being numbered independently. This means that the chapter +level (in \Class{scrbook} or \Class{scrreprt}), or the section level (in +\Class{scrartcl}) is numbered consecutively over all parts. Furthermore, for +the \Class{scrbook}\OnlyAt{\Class{scrbook}\and \Class{scrreprt}} and +\Class{scrreprt} classes, the title of the part level together with the +corresponding preamble (see \DescRef{\LabelBase.cmd.setpartpreamble}, \DescPageRef{\LabelBase.cmd.setpartpreamble}) is set on a separate page. -\Macro{chapter}\important{\Macro{chapter}}\OnlyAt{\Class{scrbook}\and - \Class{scrreprt}} only exists in book or report classes, that is, in classes -\Class{book}, \Class{scrbook}, \Class{report} and \Class{scrreport}, but not -in the article classes \Class{article} and \Class{scrartcl}. In addition to -this, the command \Macro{chapter} in {\KOMAScript} differs substantially from -the version in the standard class. In the standard classes the chapter number -is used together with the prefix ``Chapter'', or the corresponding word in the -appropriate language, on a separate line above the actual chapter title -text. This overpowering\important[i]{\DescRef{\LabelBase.option.chapterprefix}\\ - \DescRef{\LabelBase.option.appendixprefix}} style is replaced in {\KOMAScript} by a simple -chapter number before the chapter heading text, but can be reverted by the -option \DescRef{\LabelBase.option.chapterprefix} (see +The \Macro{chapter}\important{\Macro{chapter}}\OnlyAt{\Class{scrbook}\and + \Class{scrreprt}} command only exists in the book and report classes, that +is, in \Class{book}, \Class{scrbook}, \Class{report} and \Class{scrreport}, +but not in the article classes \Class{article} and \Class{scrartcl}. +Furthermore, the \Macro{chapter}\textnote{\KOMAScript{} vs. standard classes} +command in {\KOMAScript} differs substantially from the version in the +standard classes. In the standard classes, the chapter number is used together +with the prefix ``Chapter'', or the corresponding word in the appropriate +language, on a separate line above the actual chapter title text. +\KOMAScript{} replaces this +overpowering\important{\DescRef{\LabelBase.option.chapterprefix}\\ + \DescRef{\LabelBase.option.appendixprefix}} style with a simple chapter +number before the chapter title, but you can restore the original behaviour +with the \DescRef{\LabelBase.option.chapterprefix} option (see \DescPageRef{\LabelBase.option.chapterprefix}). -Please\textnote{Attention!} note that \Macro{part} and \Macro{chapter} in -classes \Class{scrbook} and \Class{scrreprt} -\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} change the page style for one -page. The applied page style in {\KOMAScript} is defined in the macros -\DescRef{\LabelBase.cmd.partpagestyle} and \DescRef{\LabelBase.cmd.chapterpagestyle} (see +Please\textnote{Attention!} note that \Macro{part} and \Macro{chapter} in the +\Class{scrbook} and \Class{scrreprt} +\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} classes change the page style for +one page. The page style applied in {\KOMAScript} is defined in the macros +\DescRef{\LabelBase.cmd.partpagestyle} and +\DescRef{\LabelBase.cmd.chapterpagestyle} (see \autoref{sec:\LabelBase.pagestyle}, \DescPageRef{\LabelBase.cmd.titlepagestyle}). +\BeginIndexGroup \BeginIndex[indexother]{}{font}% \BeginIndex[indexother]{}{font>style}% \BeginIndex[indexother]{}{font>size}% \BeginIndex{FontElement}{part}\LabelFontElement{part}% \BeginIndex{FontElement}{partnumber}\LabelFontElement{partnumber}% \BeginIndex{FontElement}{chapter}\LabelFontElement{chapter}% +\BeginIndex{FontElement}{chapterprefix}\LabelFontElement{chapterprefix}% \BeginIndex{FontElement}{section}\LabelFontElement{section}% \BeginIndex{FontElement}{subsection}\LabelFontElement{subsection}% \BeginIndex{FontElement}{subsubsection}\LabelFontElement{subsubsection}% \BeginIndex{FontElement}{paragraph}\LabelFontElement{paragraph}% \BeginIndex{FontElement}{subparagraph}\LabelFontElement{subparagraph}% \BeginIndex{FontElement}{disposition}\LabelFontElement{disposition}% -The font of all headings\ChangedAt{v2.8p}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} can be changed with the commands +You\ChangedAt{v2.8p}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} can change the font style for all headings with the \DescRef{\LabelBase.cmd.setkomafont}\IndexCmd{setkomafont} and -\DescRef{\LabelBase.cmd.addtokomafont}\IndexCmd{addtokomafont} (see +\DescRef{\LabelBase.cmd.addtokomafont}\IndexCmd{addtokomafont} commands (see \autoref{sec:\LabelBase.textmarkup}, -\DescPageRef{\LabelBase.cmd.setkomafont}). In doing this, generally the -element \FontElement{disposition}\important{\FontElement{disposition}} is -used, followed by a specific element\important[s]{% +\DescPageRef{\LabelBase.cmd.setkomafont}). In doing so, the element +\FontElement{disposition}\important{\FontElement{disposition}} is applied +first, followed by the specific element\important{% \FontElement{part}\\ \FontElement{chapter}\\ \FontElement{section}\\ \FontElement{subsection}\\ \FontElement{paragraph}\\ - \FontElement{subparagraph}} for every section level (see + \FontElement{subparagraph}} for each sectioning level (see \autoref{tab:\LabelBase.fontelements}, -\autopageref{tab:\LabelBase.fontelements}). There is a separate element -\FontElement{partnumber} for the number part of parts. The font for the -element \FontElement{disposition} is predefined as +\autopageref{tab:\LabelBase.fontelements}). There is a separate elements, +\FontElement{partnumber}, for the number of the part heading, and +\FontElement{chapterprefix}, for the optional prefix line of chapter headings. +The initial definition for the \FontElement{disposition} element is \Macro{normalcolor}\linebreak[2]\Macro{sffamily}\linebreak[2]\Macro{bfseries}. -The default font size for the specific elements depends on the options +The default font sizes for the specific elements depends on the options \OptionValueRef{\LabelBase}{headings}{big}, -\OptionValueRef{\LabelBase}{headings}{normal} and +\OptionValueRef{\LabelBase}{headings}{normal}, and \OptionValueRef{\LabelBase}{headings}{small} (see -\DescPageRef{\LabelBase.option.headings}). The defaults are listed in +\DescPageRef{\LabelBase.option.headings}). They are listed in \autoref{tab:\LabelBase.structureElementsFont}. -% +% Umbruchkorrektur: Tabelle verschoben \begin{table} % \centering% +% \caption \KOMAoptions{captions=topbeside}% \setcapindent{0pt}% -% \caption \begin{captionbeside}[{Default font sizes for different levels of document - structuring}]{Default font sizes for different levels of document - structuring in \Class{scrbook} and \Class{scrreprt}}[l] + sectioning}]{% + \label{tab:\LabelBase.structureElementsFont}% + Default font sizes for different levels of document sectioning in + \Class{scrbook} and \Class{scrreprt}}[l] \begin{tabular}[t]{lll} \toprule Class Option & Element & Default\\ @@ -1727,6 +1984,9 @@ The default font size for the specific elements depends on the options & \Macro{huge} \\ & \DescRef{\LabelBase.fontelement.chapter}\IndexFontElement{chapter} & \Macro{huge} \\ + & \DescRef{\LabelBase.fontelement.chapterprefix}% + \IndexFontElement{chapterprefix} + & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{chapter} \\ & \DescRef{\LabelBase.fontelement.section}\IndexFontElement{section} & \Macro{Large} \\ & \DescRef{\LabelBase.fontelement.subsection}% @@ -1744,6 +2004,8 @@ The default font size for the specific elements depends on the options & \DescRef{\LabelBase.fontelement.part} & \Macro{huge} \\ & \DescRef{\LabelBase.fontelement.partnumber} & \Macro{huge} \\ & \DescRef{\LabelBase.fontelement.chapter} & \Macro{LARGE} \\ + & \FontElement{chapterprefix}\IndexFontElement{chapterprefix} + & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{chapter} \\ & \DescRef{\LabelBase.fontelement.section} & \Macro{Large} \\ & \DescRef{\LabelBase.fontelement.subsection} & \Macro{large} \\ & \DescRef{\LabelBase.fontelement.subsubsection} & \Macro{normalsize} \\ @@ -1753,6 +2015,8 @@ The default font size for the specific elements depends on the options & \DescRef{\LabelBase.fontelement.part} & \Macro{LARGE} \\ & \DescRef{\LabelBase.fontelement.partnumber} & \Macro{LARGE} \\ & \DescRef{\LabelBase.fontelement.chapter} & \Macro{Large} \\ + & \FontElement{chapterprefix}\IndexFontElement{chapterprefix} + & \DescRef{\LabelBase.cmd.usekomafont}\PParameter{chapter} \\ & \DescRef{\LabelBase.fontelement.section} & \Macro{large} \\ & \DescRef{\LabelBase.fontelement.subsection} & \Macro{normalsize} \\ & \DescRef{\LabelBase.fontelement.subsubsection} & \Macro{normalsize} \\ @@ -1761,250 +2025,331 @@ The default font size for the specific elements depends on the options \bottomrule \end{tabular} \end{captionbeside} - \label{tab:\LabelBase.structureElementsFont} \end{table} - +% \begin{Example} - Suppose you are using the class option - \OptionValueRef{\LabelBase}{headings}{big} and notice that the very big - headings of document parts are too bold. You could change this as follows: + Suppose you use the \OptionValueRef{\LabelBase}{headings}{big} class option + and notice that the very large headings of the document parts are too bold. + You could change this as follows: \begin{lstcode} \setkomafont{disposition}{\normalcolor\sffamily} \part{Appendices} \addtokomafont{disposition}{\bfseries} \end{lstcode} Using the command above you only switch off the font attribute -\textbf{bold} for a heading ``Appendices''. A much more comfortable +\textbf{bold} for a heading ``Appendices''. A much more convenient and elegant solution is to change all \Macro{part} headings at once. This is done either by: \begin{lstcode} \addtokomafont{part}{\normalfont\sffamily} \addtokomafont{partnumber}{\normalfont\sffamily} \end{lstcode} - or simply using: + or simply: \begin{lstcode} \addtokomafont{part}{\mdseries} \addtokomafont{partnumber}{\mdseries} \end{lstcode} -The last version is to be preferred because it gives you the correct result -even when you make changes to the \DescRef{\LabelBase.fontelement.disposition} +The second version is preferred because it gives you the correct result +even if you change the \DescRef{\LabelBase.fontelement.disposition} element\IndexFontElement{disposition}, for instance: \begin{lstcode} \setkomafont{disposition}{\normalcolor\bfseries} \end{lstcode} - With this change it is possible to set all section levels at once to no + With this change, it is possible to set all section levels at once to no longer use sans serif fonts. \end{Example} -Please be warned of misusing the possibilities of font switching to -mix fonts, font sizes and font attributes excessively. Picking the -most suitable font for a given task is a hard task even for -professionals and has almost nothing to do with the personal tastes of -non-experts. Please refer to the citation at the end of -\autoref{sec:typearea.tips}, \autopageref{sec:typearea.tips.cite} and -to the following explanation. +I strongly advise against using the ability to switch fonts in order to mix +fonts, font sizes, and font attributes wildly. Picking the right font for the +job is a matter for experts and has almost nothing to do with the personal +tastes of non-experts. See the citation at the end of +\autoref{sec:typearea.tips}, \autopageref{sec:typearea.tips.cite} and to the +following explanation. \begin{Explain} - It is possible to use different font types for different section - levels in {\KOMAScript}. Non-experts in typography should for very - good typographical reasons refrain absolutely from using these - possibilities. - - There is a rule in typography which states that one should mix as - few fonts as possible. Using sans serif for headings already seems - to be a breach of this rule. However, one should know that bold, - large serif letters are much too heavy for headings. Strictly - speaking, one would then have to at least use a normal instead of a - bold or semi-bold font. However, in deeper levels of the structuring, - a normal font may then appear too lightly weighted. On the other - hand, sans serif fonts in headings have a very pleasant appearance - and in fact find acceptance almost solely for headings. That is why - sans serif is the carefully chosen default in {\KOMAScript}. - - More variety should, however, be avoided. Font mixing is only for - professionals. In case you want to use other fonts than the standard {\TeX} - fonts\,---\,regardless of whether these are CM\Index{CM fonts}, EC\Index{EC - fonts}, or LM fonts\Index{LM fonts}\,---\,you should consult an expert, or - for safety's sake redefine the font for the element + It is possible to use different font types for different sectioning + levels in {\KOMAScript}. Non-experts in typography should absolutely avoid + doing so for excellent typographical reasons. + + A rule of typography states that you should mix as few fonts as possible. + Using sans serif for headings already seems to violate this rule. However, + you should realize that large, bold, serif letters are much too heavy for + headings. Strictly speaking, you should then use a normal instead of a bold + or semi-bold font. However, in deeper levels of the sectioning, a normal + font may then appear too light. On the other hand, sans serif fonts have a + very pleasant appearance in headings, and almost solely in headings. There + is, therefore, good reason why sans serif is the default in {\KOMAScript}. + + Greater variety should, however, be avoided. Font mixing is something for + professionals. For this reason, if you want to use fonts other than the + standard {\TeX} fonts\,---\,regardless of whether these are CM\Index{CM + fonts}, EC\Index{EC fonts}, or LM fonts\Index{LM fonts}\,---\,you should + consult an expert about the compatibility of the sans serif and serif fonts, + or redefine the element \DescRef{\LabelBase.fontelement.disposition}\IndexFontElement{disposition} - as seen in the example above. The author of this documentation considers the - commonly encountered combinations Times and Helvetica or Palatino with - Helvetica as unfavourable. + as a precautionary measure. The author considers the commonly encountered + combinations of Times and Helvetica or Palatino with Helvetica to be + awkward. \end{Explain} +\EndIndexGroup % \EndIndexGroup \begin{Declaration} - \Macro{part*}\Parameter{Heading}% - \Macro{chapter*}\Parameter{Heading}% - \Macro{section*}\Parameter{Heading}% - \Macro{subsection*}\Parameter{Heading}% - \Macro{subsubsection*}\Parameter{Heading}% - \Macro{paragraph*}\Parameter{Heading}% - \Macro{subparagraph*}\Parameter{Heading} + \Macro{part*}\Parameter{heading}% + \Macro{chapter*}\Parameter{heading}% + \Macro{section*}\Parameter{heading}% + \Macro{subsection*}\Parameter{heading}% + \Macro{subsubsection*}\Parameter{heading}% + \Macro{paragraph*}\Parameter{heading}% + \Macro{subparagraph*}\Parameter{heading} \end{Declaration}% -All disposition commands have starred versions, which are -unnumbered\Index{numbering}, and produce section headings which do not -show up in the table of contents\Index{table>of contents}\Index{contents>table - of} or in the -running heading\Index{header}. The absence of a running heading often -has an unwanted side effect. For example, if a chapter which is set -using \Macro{chapter*} spans several pages, then the running heading -of the previous chapter suddenly reappears. {\KOMAScript} offers a -solution for this which is described -below. \OnlyAt{\Class{scrbook}\and\Class{scrreprt}}\Macro{chapter*} -only exists in book and report classes, that is, \Class{book}, -\Class{scrbook}, \Class{report} and \Class{scrreport}, but not the -article classes \Class{article} and \Class{scrartcl}. - -Please\textnote{Attention!} note that \DescRef{\LabelBase.cmd.part} and \DescRef{\LabelBase.cmd.chapter} change -the page style for one page. The applied style is defined in the macros -\DescRef{\LabelBase.cmd.partpagestyle} and -\DescRef{\LabelBase.cmd.chapterpagestyle} in {\KOMAScript} (see -\autoref{sec:\LabelBase.pagestyle}, \DescPageRef{\LabelBase.cmd.titlepagestyle}). - -As for the possibilities of font switching\ChangedAt{v2.8p}{% - \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}}, % -the same explanations apply as were given above for the unstarred -variants. The structuring elements are named the same since they do -not indicate variants but structuring levels.% +The starred variants of all sectioning commands produce +unnumbered\Index{numbering} headings which do not appear in the table of +contents\Index{table>of contents}\Index{contents>table of} or in the running +head\Index{running head}. The absence of a running head often has an unwanted +side effect. If, for example, a chapter set using \Macro{chapter*} spans +several pages, then the running head of the previous chapter suddenly +reappears. {\KOMAScript} offers a solution for this problem, described below. +\Macro{chapter*}\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} only exists in +book and report classes, that is, \Class{book}, \Class{scrbook}, +\Class{report} and \Class{scrreport}, not in the article classes +\Class{article} and \Class{scrartcl}. + +Please\textnote{Attention!} note that \DescRef{\LabelBase.cmd.part} and +\DescRef{\LabelBase.cmd.chapter} change the page style for one page. While the +standard classes use the \PageStyle{plain} page style, {\KOMAScript} applies +the style defined in the \DescRef{\LabelBase.cmd.partpagestyle} and +\DescRef{\LabelBase.cmd.chapterpagestyle} macros (see +\autoref{sec:\LabelBase.pagestyle}, +\DescPageRef{\LabelBase.cmd.titlepagestyle}). + +The possibilities for switching fonts\ChangedAt{v2.8p}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} % +described above for the unstarred variants apply without change. The elements +use the same names since they do not indicate variants but structuring +levels.% % \EndIndexGroup -\iftrue% Umbruchkorrekturtext -In the standard classes\textnote{\KOMAScript{} vs. standard classes} there are -no further structuring commands. In particular, there are no commands which -can produce unnumbered chapters or sections which show up in the table of -contents and in the running heading.% +\iffalse% Umbruchkorrekturtext + In the standard classes\textnote{\KOMAScript{} vs. standard classes} there + are no further structuring commands. In particular, there are no commands + which can produce unnumbered chapters or sections which show up in the table + of contents and in the running heading.% \fi + \begin{Declaration} - \Macro{addpart}\OParameter{Short version}\Parameter{Heading}% - \Macro{addpart*}\Parameter{Heading}% - \Macro{addchap}\OParameter{Short version}\Parameter{Heading}% - \Macro{addchap*}\Parameter{Heading}% - \Macro{addsec}\OParameter{Short version}\Parameter{Heading}% - \Macro{addsec*}\Parameter{Heading}\textnote[n]{\KOMAScript{} vs. standard classes} + \Macro{addpart}\OParameter{short version}\Parameter{heading}% + \Macro{addpart*}\Parameter{heading}% + \Macro{addchap}\OParameter{short version}\Parameter{heading}% + \Macro{addchap*}\Parameter{heading}% + \Macro{addsec}\OParameter{short version}\Parameter{heading}% + \Macro{addsec*}\Parameter{heading} + \textnote[n]{\KOMAScript{} vs. standard classes} \end{Declaration}% -In addition to the commands of the standard classes, {\KOMAScript} -offers the new commands \Macro{addsec} and \Macro{addchap}. They are -similar to the standard commands \DescRef{\LabelBase.cmd.chapter} and -\DescRef{\LabelBase.cmd.section}, except that they are unnumbered. They thus produce -both a running heading and an entry in the table of contents. +In addition to the commands of the standard classes, {\KOMAScript} offers the +new commands \Macro{addpart}, \Macro{addsec} and \Macro{addchap}. They are +similar to the standard commands \DescRef{\LabelBase.cmd.part}\IndexCmd{part}% +\important{\DescRef{\LabelBase.cmd.part}, \DescRef{\LabelBase.cmd.chapter}, + \DescRef{\LabelBase.cmd.section}}, +\DescRef{\LabelBase.cmd.chapter}\IndexCmd{chapter} and +\DescRef{\LabelBase.cmd.section}\IndexCmd{section} except that they are +unnumbered. They thus produce both a running head and an entry in the table of +contents. The starred variants \Macro{addchap*} and \Macro{addsec*} are similar to the -standard commands \DescRef{\LabelBase.cmd.chapter*} and \DescRef{\LabelBase.cmd.section*} except for a tiny but -important difference: The running headings are deleted. This eliminates the -side effect of obsolete headers mentioned above. Instead, the running headings -on following pages remain empty. \OnlyAt{\Class{book}\and - \Class{scrreprt}}\Macro{addchap} and \Macro{addchap*} of course only exist -in book and report classes, namely \Class{book}, \Class{scrbook}, -\Class{report} and \Class{scrreport}, but not in the article classes -\Class{article} and \Class{scrartcl}. - -Similarly, the command \Macro{addpart} produces an unnumbered document -part with an entry in the table of contents. Since the running -headings are already deleted by \DescRef{\LabelBase.cmd.part} and \DescRef{\LabelBase.cmd.part*} the -problem of obsolete headers does not exist. The starred version -\Macro{addpart*} is thus identical to \DescRef{\LabelBase.cmd.part*} and is only -defined for consistency reasons. +standard commands \DescRef{\LabelBase.cmd.chapter*} and +\DescRef{\LabelBase.cmd.section*} except for a small but important difference: +the running heads are deleted. This eliminates the side effect of obsolete +headers mentioned above. Instead, the running heads on subsequent pages remain +empty. \OnlyAt{\Class{book}\and \Class{scrreprt}}\Macro{addchap} and +\Macro{addchap*} only exist, of course, in book and report classes, namely +\Class{book}, \Class{scrbook}, \Class{report} and \Class{scrreport}, not in +the article classes \Class{article} and \Class{scrartcl}. + +The \Macro{addpart} command produces an unnumbered document part with an +entry in the table of contents. Since the running heads are already deleted +by \DescRef{\LabelBase.cmd.part} and \DescRef{\LabelBase.cmd.part*} the +previously mentioned problem with obsolete headers does not exist. The starred +version \Macro{addpart*} is thus identical to \DescRef{\LabelBase.cmd.part*} +and is only defined for reasons of consistency. Please note\textnote{Attention!} that \Macro{addpart} and \Macro{addchap} and -their starred versions change the page style for one page. The particular page +their starred variants change the page style for one page. The particular page style is defined in the macros \DescRef{\LabelBase.cmd.partpagestyle} and \DescRef{\LabelBase.cmd.chapterpagestyle} (see -\autoref{sec:\LabelBase.pagestyle}, \DescPageRef{\LabelBase.cmd.chapterpagestyle}). +\autoref{sec:\LabelBase.pagestyle}, +\DescPageRef{\LabelBase.cmd.titlepagestyle}). +\iffree{\iffalse}{\csname iftrue\endcsname}% Umbruchkorrekturbeispiel + \begin{Example} + You write a book with a long afterword that spans several pages. This + should receive neither a running head nor an entry in the table of + contents. Therefore, you first use \DescRef{\LabelBase.cmd.chapter*}: +\begin{lstcode} + \documentclass{scrbook} + \usepackage{blindtext} + \begin{document} + \tableofcontents + \blinddocument + \chapter*{Afterword} + \Blindtext[10] + \end{document} +\end{lstcode} + However, you discover that the running head of the previous chapter + reappears on the second and third pages of the afterword. Naturally, you do + not want that. Therefore, you use \Macro{addchap*}: +\begin{lstcode} + \documentclass{scrbook} + \usepackage{blindtext} + \begin{document} + \tableofcontents + \blinddocument + \addchap*{Afterword} + \Blindtext[10] + \end{document} +\end{lstcode} + The complete postscript is now without a running head, if that is what you + want. But even that does not quite meet your expectations. A running head + would be nice. With +\begin{lstcode} + \documentclass{scrbook} + \usepackage{blindtext} + \begin{document} + \tableofcontents + \blinddocument + \addchap{Afterword} + \Blindtext[10] + \end{document} +\end{lstcode} + you now get both ``Afterword'' as the running head on the even pages and an + entry in the table of contents. But this entry bothers your publisher. He + insists that the afterword have no entry in the table of contents. Even if + that seems strange to you, you want to satisfy the publisher, so with + \OptionValueRef{\LabelBase}{headings}{optiontotocandhead} you first + activate the extended function for the optional argument and then + explicitly set an empty argument for the table of contents: +\begin{lstcode} + \documentclass[headings=optiontotocandhead] + {scrbook} + \usepackage{blindtext} + \begin{document} + \tableofcontents + \blinddocument + \addchap[tocentry={}]{Afterword} + \Blindtext[10] + \end{document} +\end{lstcode} + The running head is not changed by \OptionValue{tocentry}{\{\}}. Since + \Class{scrbook} automatically omits empty entries in the table of contents, + the publisher is now satisfied. + \end{Example}% +\fi -As for the possibilities of font switching\ChangedAt{v2.8p}{% - \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}}, % -the same explanations apply as given above for the normal structuring -commands. The elements are named the same since they describe not -variants but structuring levels.% +The possibilities for switching fonts\ChangedAt{v2.8p}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} % +described above for the unstarred variant of the sectioning commands apply +without change. The elements have the same names since they do not designate +variants but sectioning levels.% % \EndIndexGroup \begin{Declaration} - \Macro{minisec}\Parameter{Heading} + \Macro{minisec}\Parameter{heading} \end{Declaration}% -Sometimes a heading\Index{heading} is wanted which is highlighted but -also closely linked to the following text. Such a heading should not -be separated by a large vertical skip. +Sometimes you want a heading\Index{heading} that is highlighted but also +closely linked to the following text. Such a heading should not be separated +by a large vertical skip. -The command \Macro{minisec} is designed for this situation. This -heading is not associated with any structuring level. Such a -\emph{mini section} does not produce an entry in the table of contents -nor does it receive any numbering. +The \Macro{minisec} command is designed for this situation. This heading is +not associated with any sectioning level\textnote{no sectioning level}. Such a +\emph{mini-section} does not produce an entry in the table of contents, nor +does it receive any numbering. +\BeginIndexGroup \BeginIndex{FontElement}{minisec}\LabelFontElement{minisec}% -The font type of the structuring command \Macro{minisec} can be changed using -the element -\DescRef{\LabelBase.fontelement.disposition}\IndexFontElement{disposition} -(see \autoref{tab:\LabelBase.fontelements}, -\autopageref{tab:\LabelBase.fontelements}) and -\FontElement{minisec}\ChangedAt{v2.96a}{% - \Class{scrbook} \and\Class{scrreprt} \and\Class{scrartcl}}. Default setting -of element \FontElement{minisec} is empty, so the default of the element -\DescRef{\LabelBase.fontelement.disposition}\IndexFontElement{disposition} is -active.% -\EndIndex{FontElement}{minisec}% +You can change the font of the \Macro{minisec} command using the +\DescRef{\LabelBase.fontelement.disposition}% +\important{\DescRef{\LabelBase.fontelement.disposition}\\ +\FontElement{minisec}} and \FontElement{minisec}\ChangedAt{v2.96a}{% + \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} element (see +\autoref{tab:maincls.fontelements}, \autopageref{tab:maincls.fontelements}). +The default of the \FontElement{minisec} element is empty, so by default only +the \DescRef{\LabelBase.fontelement.disposition} element is used.% +\EndIndexGroup \begin{Example} You have developed a kit for building a mouse trap and want the documentation separated into a list of necessary items and an assembly description. You could write the following: \begin{lstcode} - \minisec{Items needed} - - \begin{flushleft} - 1 plank ($100\times 50 \times 12$)\\ - 1 spring-plug of a beer-bottle\\ - 1 spring of a ball-point pen\\ - 1 drawing pin\\ - 2 screws\\ - 1 hammer\\ - 1 knife - \end{flushleft} - - \minisec{Assembly} - At first one searches the mouse-hole and puts the drawing pin - directly behind the hole. Thus the mouse cannot escape during the - following actions. - - Then one knocks the spring-plug with the hammer into the mouse-hole. - If the spring-plug's size is not big enough in order to shut the - mouse-hole entirely, then one can utilize the plank instead and - fasten it against the front of the mouse-hole utilizing the two - screws and the knife. Instead of the knife one can use a - screw-driver instead. + \documentclass{scrartcl} + + \begin{document} + + \title{DIY Projects} + \author{Two Left Thumbs} + \date{\today} + \maketitle + + \section{Mousetrap} + + The first project is suitable for beginners and only requires + a few components that should be found in every household. + + \minisec{Material Required} + + \begin{flushleft} + 1 board ($100\times 50 \times 12$)\\ + 1 swing-top cap of a beer-bottle\\ + 1 ballpoint pen\\ + 1 push pin\\ + 2 screws\\ + 1 hammer\\ + 1 knife + \end{flushleft} + + \minisec{Assembly} + First, find the mouse hole and put the push pin directly behind + the hole so that the mouse cannot escape during the following + actions. + + Next tap the swing-top cap into the mouse hole with the hammer. + If the cap is not big enough to block the hole completely and + permanently, take the board instead and screw it to the front + of the mouse hole using the two screws and the knife. Of + course, you can use a screwdriver instead of a knife. The + ballpoint pen has fallen victim to animal welfare. + \end{document} \end{lstcode} - Which gives: + The main part, starting with the heading ``Material Required'' will look + like this: \begin{ShowOutput}[\baselineskip]\setlength{\parindent}{1em} - \minisec{Items needed} - - \begin{flushleft} - 1 plank ($100\times 50 \times 12$)\\ - 1 spring-plug of a beer-bottle\\ - 1 spring of a ball-point pen\\ - 1 drawing pin\\ - 2 screws\\ - 1 hammer\\ - 1 knife - \end{flushleft} - - \minisec{Assembly} - At first one searches the mouse-hole and puts the drawing pin - directly behind the hole. Thus the mouse cannot escape during the - following actions. - - Then one knocks the spring-plug with the hammer into the - mouse-hole. If the spring-plug's size is not big enough in order - to shut the mouse-hole entirely, then one can utilize the plank - instead and fasten it against the front of the mouse-hole - utilizing the two screws and the knife. Instead of the knife one - can use a screw-driver instead. + \minisec{Material Required} + + \begin{flushleft} + 1 board ($100\times 50 \times 12$)\\ + 1 swing-top cap of a beer-bottle\\ + 1 ballpoint pen\\ + 1 push pin\\ + 2 screws\\ + 1 hammer\\ + 1 knife + \end{flushleft} + + \minisec{Assembly} + First, find the mouse hole and put the push pin directly behind the hole + so that the mouse cannot escape during the following actions. + + Next tap the swing-top cap into the mouse hole with the hammer. If the cap + is not big enough to block the hole completely and permanently, take the + board instead and screw it to the front of the mouse hole using the two + screws and the knife. Of course, you can use a screwdriver instead of a + knife. The ballpoint pen has fallen victim to animal welfare. \end{ShowOutput} \end{Example} % @@ -2018,14 +2363,14 @@ active.% \end{Declaration}% In the standard classes\textnote{\KOMAScript{} vs. standard classes}, headings are set as justified text. That means that hyphenated words can occur and -headings with more than one line are stretched up to the text border. This is -a rather uncommon approach in typography. {\KOMAScript} therefore formats the +multi-line headings are stretched up to the text width. This approach is +rather uncommon in typography. {\KOMAScript} therefore sets the headings left aligned with hanging indentation using \Macro{raggedsection} -with the definition: +with the default: \begin{lstcode} \newcommand*{\raggedsection}{\raggedright} \end{lstcode} -This command can be redefined with \Macro{renewcommand}. +You can redefine this command with \Macro{renewcommand}. \begin{Example} You prefer justified headings, so you write in the preamble of your document: \begin{lstcode} @@ -2035,162 +2380,180 @@ This command can be redefined with \Macro{renewcommand}. \begin{lstcode} \let\raggedsection\relax \end{lstcode} - You will get a formatting of the headings which is very close to that - of the standard classes. It will become even closer when you combine - this change with the change of the element + You will get heading formatting which is very close to that of the standard + classes. It will become even closer when you combine this change with the + change to the \DescRef{\LabelBase.fontelement.disposition}\IndexFontElement{disposition} - mentioned above. + element mentioned above. \end{Example} Because\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}} some users want -for \DescRef{\LabelBase.cmd.chapter} another alignment than for all other -sections, you can change only \DescRef{\LabelBase.cmd.chapter} redefining -\Macro{raggedchapter}. The default of this command is usage of -\Macro{raggedsection}. So every change of \Macro{raggedsection} will also -change the alignment of chapter headings. - -Unlike all others, the headings of parts (\DescRef{\LabelBase.cmd.part}) will -be horizontally centered instead of set ragged right. This is because command -\Macro{raggedpart} is defined as +a different alignment for the \DescRef{\LabelBase.cmd.chapter} level than for +the other sectioning levels, you can change the +\DescRef{\LabelBase.cmd.chapter} justification separately by redefining +\Macro{raggedchapter}. By default, however, this command simply uses +\Macro{raggedsection}, so changing \Macro{raggedsection} indirectly affects +\Macro{raggedchapter}. + +By default, part headings (\DescRef{\LabelBase.cmd.part}) are set horizontally +centred rather than ragged right. This formatting is performed by the +\Macro{raggedpart} statement, which has the default definition \begin{lstcode} \let\raggedpart\centering \end{lstcode} -You may also redefine this using \Macro{renewcommand} too. +You can also redefine this command using \Macro{renewcommand}. \begin{Example} - You do not want different alignment at headings of - \DescRef{\LabelBase.cmd.part}. So you put + You want the headings for \DescRef{\LabelBase.cmd.part} to be formatted the + same as any other sectioning command. To do so, put \begin{lstcode} \renewcommand*{\raggedpart}{\raggedsection} \end{lstcode} - into the preamble of your document. In\textnote{Hint!} this case, - and unlike in the example above, \Macro{let} has not been used, because - \Macro{let} would give \Macro{raggedpart} the current meaning of - \Macro{raggedsection}. Further changes of \Macro{raggedsection} would then - stay disregarded at the usage of \Macro{raggedpart}. Doing the redefinition - using \Macro{renewcommand} gives \Macro{raggedpart} the meaning of - \Macro{raggedsection} not at definition time, but each time - \Macro{raggedpart} will be used. + in the preamble of your document. In\textnote{Hint!} this case, and unlike + in the example above, we did not use \Macro{let} because \Macro{let} would + set \Macro{raggedpart} to the underlying value of \Macro{raggedsection}. + Subsequent changes to \Macro{raggedsection} would then not change the + behaviour of \Macro{raggedpart}. By redefining with \Macro{renewcommand}, + \Macro{raggedpart} will use the current meaning of \Macro{raggedsection} at + the time it is used rather than when it was redefined. \end{Example}% % \EndIndexGroup \begin{Declaration} - \Macro{partformat}% - \Macro{chapterformat}% - \Macro{sectionformat}% - \Macro{subsectionformat}% - \Macro{subsubsectionformat}% - \Macro{paragraphformat}% - \Macro{subparagraphformat}% - \Macro{othersectionlevelsformat}\Parameter{sectioning - name}\Parameter{}\Parameter{counter output}% - \Macro{IfUsePrefixLine}\Parameter{then code}\Parameter{else code}% + \Macro{partformat} + \Macro{chapterformat} + \Macro{sectionformat} + \Macro{subsectionformat} + \Macro{subsubsectionformat} + \Macro{paragraphformat} + \Macro{subparagraphformat} + \Macro{othersectionlevelsformat}\Parameter{sectioning name}\Parameter{} + \Parameter{counter output} + \Macro{IfUsePrefixLine}\Parameter{then code}\Parameter{else code} \Macro{autodot} \end{Declaration}% -\Index{part>number}% -\Index{chapter>number}% -\Index{section>number}% -{\KOMAScript} has added a further logical level on top of -\Macro{the\PName{sectioning name}} to the output of the sectioning -numbers. The counters for the respective heading are not merely output. They -are formatted using the commands \Macro{partformat}, \Macro{chapterformat} -down to \Macro{subparagraphformat}\ChangedAt{v3.17}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}}. -\OnlyAt{\Class{scrbook}\and\Class{scrreprt}}Of course the command -\Macro{chapterformat} like \Macro{thechapter} does not exist in the class -\Class{scrartcl} but only in the classes \Class{scrbook} and \Class{scrreprt}. - -As described for option \DescRef{\LabelBase.option.numbers}\important{\DescRef{\LabelBase.option.numbers}} at the -beginning of this section (see \DescPageRef{\LabelBase.option.numbers}), -periods in section numbers should be handled for the German-speaking region -according to the rules given in \cite{DUDEN}. The command \Macro{autodot} in -{\KOMAScript} ensures that these rules are followed. In all levels -except for \DescRef{\LabelBase.cmd.part}, a dot is followed by a further \Macro{enskip}. This -corresponds to a horizontal skip of 0.5\Unit{em}. +{\KOMAScript} adds another logical layer above \Macro{the\PName{sectioning + name}} to format the sectioning numbers. The counters for each heading are +not merely output. They are formatted using the commands \Macro{partformat}, +\Macro{chapterformat}, down to +\Macro{subparagraphformat}\ChangedAt{v3.17}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}. Of course the \Macro{chapterformat} +command, like \Macro{thechapter}, does not exist in the \Class{scrartcl} +class, but only in the \Class{scrbook} and \Class{scrreprt} +classes.\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} + +As already explained for the \DescRef{\LabelBase.option.numbers}% +\important{\DescRef{\LabelBase.option.numbers}} option at the beginning of +this section (see \DescPageRef{\LabelBase.option.numbers}), {\KOMAScript}'s +handling of points in section numbers implements the rules given in +\cite{DUDEN}, which are standard in German-language typography, in the +\Macro{autodot} command. In all levels except for +\DescRef{\LabelBase.cmd.part}, a point is followed by a further +\Macro{enskip}. This corresponds to a horizontal skip of 0.5\Unit{em}. Since \KOMAScript~3.17\ChangedAt{v3.17}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} the command + \Class{scrreprt}\and \Class{scrartcl}}, the command \Macro{othersectionlevelsformat} is used only in rare circumstances, i.\,e., if the corresponding format command to a section command does not exist or is -\Macro{relax}. This should not happen for all section commands defined by -\KOMAScript{} itself. Therefore the command is not officially documented any -longer. Nevertheless, if a compatibility level prior to 3.17 (see option +\Macro{relax}. This should not happen for any section commands defined by +\KOMAScript{} itself. Therefore the command is no longer officially +documented. Nevertheless, if you select a compatibility level prior to +3.17\important{\OptionValueRef{\LabelBase}{version}{3.17}} (see option \DescRef{\LabelBase.option.version}, \autoref{sec:\LabelBase.compatibilityOptions}, -\DescPageRef{\LabelBase.option.version}) has been selected, commands -\Macro{sectionformat} down to \Macro{subparagraphformat} are ignored by -\KOMAScript{}. In this case \Macro{othersectionlevelsformat} indeed will be -used. - -The formatting commands can be redefined using \Macro{renewcommand} to -fit them to your personal needs. The following original definitions -are used by the {\KOMAScript} classes: +\DescPageRef{\LabelBase.option.version}), commands \Macro{sectionformat} down +to \Macro{subparagraphformat} are ignored by \KOMAScript{}. Instead, these +layers will continue to use \Macro{othersectionlevelsformat}. + +You can redefine the formatting commands using \Macro{renewcommand} to fit +them to your personal needs. The following default definitions are used by the +{\KOMAScript} classes: \begin{lstcode} \newcommand*{\partformat}{\partname~\thepart\autodot} \newcommand*{\chapterformat}{% \mbox{\chapappifchapterprefix{\nobreakspace}\thechapter \autodot\IfUsePrefixLine{}{\enskip}}} \newcommand*{\sectionformat}{\thesection\autodot\enskip} + \newcommand*{\subsectionformat}{% + \thesubsection\autodot\enskip} + \newcommand*{\subsubsectionformat}{% + \thesubsubsection\autodot\enskip} + \newcommand*{\paragraphformat}{\theparagraph\autodot\enskip} + \newcommand*{\subparagraphformat}{% + \thesubparagraph\autodot\enskip} \newcommand*{\othersectionlevelsformat}[3]{% #3\autodot\enskip} \end{lstcode} -The definitions of the lower levels correspond to -\Macro{sectionformat}. -Because\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}} of -\Macro{IfUsePrefixLine} command \Macro{chapterformat} should not be used -outside of \DescRef{\LabelBase.cmd.chapter}. \Macro{IfUsePrefixLine} is only valid inside -section commands of \KOMAScript{}. In this case, it executes the \PName{then - code} if a prefix line for the number is used, but \PName{else code} -otherwise. +Because\ChangedAt{v3.17}{\Class{scrbook}\and \Class{scrreprt}} it uses +\Macro{IfUsePrefixLine}, \Macro{chapterformat} should not be used outside of +\DescRef{\LabelBase.cmd.chapter}. \Macro{IfUsePrefixLine} is only valid inside +\KOMAScript{} sectioning commands. Within those commands, it executes the +\PName{then code} if a prefix line for the number is used and the \PName{else +code} otherwise. -Do\textnote{Attention!} not forget to change \Macro{newcommand} into -\Macro{renewcommand} if you like to re-define one of the commands. +Please also remember\textnote{Attention!} to replace \Macro{newcommand} with +\Macro{renewcommand} if you want to redefine one of the commands above. \begin{Example} - Assume that when using \DescRef{\LabelBase.cmd.part} you do not want the word - ``Part'' written in front of the part number. You could use the + Suppose you do not want the word ``Part'' written in front of the part + number when you use \DescRef{\LabelBase.cmd.part}. You can put the following command in the preamble of your document: \begin{lstcode} \renewcommand*{\partformat}{\thepart\autodot} \end{lstcode} - Strictly speaking, you could do without \Macro{autodot} at this point and - insert a fixed dot instead. As \DescRef{\LabelBase.cmd.part} is numbered with roman numerals, - according to \cite{DUDEN} a period has to be applied. However, you thereby - give up the possibility to use one of the options - \OptionValueRef{\LabelBase}{numbers}{endperiod} and - \OptionValueRef{\LabelBase}{numbers}{noendperiod} and optionally depart from - the rules. More details concerning class options can be found at + In fact, you could do without \Macro{autodot} here and insert a fixed point + instead. Since \DescRef{\LabelBase.cmd.part} is numbered with Roman numerals, + it must be followed by a point according to \cite{DUDEN}. However, by using + \Macro{autodot} you retain the ability to use the + \DescRef{\LabelBase.option.numbers}% + \important{\DescRef{\LabelBase.option.numbers}} option + \OptionValueRef{\LabelBase}{numbers}{endperiod} and thus deviate from + the rule. You can find more details concerning class options on \DescPageRef{\LabelBase.option.numbers}. - An additional possibility could be to place the section numbers in the - left margin in such a way that the heading text is left aligned with - the surrounding text. This can be accomplished with: + Another possibility is to place the section numbers in the left margin in + such a way that the heading text is left aligned with the surrounding text. + You can accomplish this with: \begin{lstcode} \renewcommand*{\sectionformat}{% \makebox[0pt][r]{\thesection\autodot\enskip}} \renewcommand*{\subsectionformat}{% \makebox[0pt][r]{\thesubsection\autodot\enskip}} \renewcommand*{\subsubsectionformat}{% - \makebox[0pt][r]{\thesubsubsection\autodot\enskip}} + \makebox[0pt][r]{% + \thesubsubsection\autodot\enskip}} \renewcommand*{\paragraphformat}{% \makebox[0pt][r]{\theparagraph\autodot\enskip}} \renewcommand*{\paragraphformat}{% - \makebox[0pt][r]{\thesubparagraph\autodot\enskip}} + \makebox[0pt][r]{% + \thesubparagraph\autodot\enskip}} \end{lstcode} - See \cite{latex:usrguide} for more information about the optional arguments - of \Macro{makebox}. + The optional arguments of the \Macro{makebox} command require \LaTeX{} to + create a zero-width box with right-justified content. As a result, the + contents of the box are output to the left of the current position.% + \iffree{}{ %Umbruchkorrekturtext + This popular trick avoids the need first to measure the width of the + number and the spacing, and then to change the current position + appropriately with \Macro{hspace}.} + You can find more about the optional arguments of \Macro{makebox} in + \cite{latex:usrguide}. \end{Example} -If you would like to change more than only the printing of the counter of a -heading, please have a look at -\DescRef{maincls-experts.cmd.chapterlineswithprefixformat}, -\DescRef{maincls-experts.cmd.chapterlinesformat}, -\DescRef{maincls-experts.cmd.sectionlinesformat}, and -\DescRef{maincls-experts.cmd.sectioncatchphraseformat} in -\autoref{sec:maincls-experts.experts} from -\DescPageRef{maincls-experts.cmd.chapterlineswithprefixformat}.% +For formatting changes in the headings that go beyond merely formatting the +unit number, please refer to +\DescRef{maincls-experts.cmd.partlineswithprefixformat}% +\IndexCmd{partlineswithprefixformat}, +\DescRef{maincls-experts.cmd.chapterlineswithprefixformat}% +\IndexCmd{chapterlineswithprefixformat} and +\DescRef{maincls-experts.cmd.chapterlinesformat}\IndexCmd{chapterlinesformat}, +as well as +\DescRef{maincls-experts.cmd.sectionlinesformat}\IndexCmd{sectionlinesformat} +and its \DescRef{maincls-experts.cmd.sectioncatchphraseformat}% +\IndexCmd{sectioncatchphraseformat} format in +\autoref{sec:maincls-experts.experts}, starting from +\DescPageRef{maincls-experts.cmd.partlineswithprefixformat}.% \EndIndexGroup @@ -2198,28 +2561,26 @@ heading, please have a look at \Macro{chapappifchapterprefix}\Parameter{additional text}% \Macro{chapapp} \end{Declaration}% -These\OnlyAt{\Class{scrbook}\and\Class{scrreprt}}% -\ChangedAt{v2.8o}{\Class{scrbook}\and\Class{scrreprt}} two commands -are not only used internally by {\KOMAScript} but are also provided to -the user. Later it will be shown how they can be used, for example, to -redefine other commands. - -Using the layout option -\OptionValueRef{\LabelBase}{chapterprefix}{true}\important{\DescRef{\LabelBase.option.chapterprefix}} -(see \DescPageRef{\LabelBase.option.chapterprefix}) -\Macro{chapappifchapterprefix} outputs the word -``Chapter''\Index{chapter>heading} in the main part of the document in the -current language, followed by \PName{additional text}. In the +These\ChangedAt{v2.8o}{\Class{scrbook}\and\Class{scrreprt}} two commands are +used internally by {\KOMAScript} and also made available to the user. Later, +you will see how to use them, for example to redefine other commands.% +\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} + +If you use the layout option \OptionValueRef{\LabelBase}{chapterprefix}{true}% +\important{\DescRef{\LabelBase.option.chapterprefix}} (see +\DescPageRef{\LabelBase.option.chapterprefix}), \Macro{chapappifchapterprefix} +outputs the word ``Chapter''\Index{chapter>heading} in the body of the text in +the current language, followed by \PName{additional text}. In the appendix\Index{appendix}, the word ``Appendix'' in the current language is output instead, followed by \PName{additional text}. If the option \OptionValue{\LabelBase}{chapterprefix}{false} is set, then nothing is output. -The command \Macro{chapapp} always outputs the word ``Chapter'' or -``Appendix''. In this case the selection of option -\DescRef{\LabelBase.option.chapterprefix} has no effect. +The \Macro{chapapp} command always outputs the word ``Chapter'' or +``Appendix'', regardless of the setting of the +\DescRef{\LabelBase.option.chapterprefix} option. -Since chapters only exist in the classes \Class{scrbook} and -\Class{scrreprt}, these commands only exist in these classes.% +Since chapters only exist in the classes \Class{scrbook} and \Class{scrreprt}, +these commands only exist in these classes.% % \EndIndexGroup @@ -2235,104 +2596,101 @@ Since chapters only exist in the classes \Class{scrbook} and \Macro{subsectionmarkformat} \end{Declaration}% \begin{Explain}% - As mentioned in \autoref{sec:\LabelBase.pagestyle} the page style - \PValue{headings} works with automatic running heads\Index{running - head}. For this, the commands \Macro{chaptermark} and \Macro{sectionmark}, - or \Macro{sectionmark} and \Macro{subsectionmark}, respectively, are - defined. Every structuring command (\DescRef{\LabelBase.cmd.chapter}, - \DescRef{\LabelBase.cmd.section}, etc.) automatically carries out the - respective \Macro{\dots mark} command. The parameter passed contains the - text of the section heading\Index{heading}. The respective section number is - added automatically in the \Macro{\dots mark} command. The formatting is - done according to the section level with one of the three commands - \Macro{chaptermarkformat}, \Macro{sectionmarkformat}, or - \Macro{subsectionmarkformat}. - - Please note\textnote{Attention!}, the running heads of + As mentioned in \autoref{sec:\LabelBase.pagestyle}, the + \DescRef{\LabelBase.pagestyle.headings}\IndexPagestyle{headings}% + \important{\DescRef{\LabelBase.pagestyle.headings}} page style works with + automatic running heads\Index{running heads>automatic}. For this, the + commands \Macro{chaptermark} and \Macro{sectionmark}, or \Macro{sectionmark} + and \Macro{subsectionmark}, are defined accordingly. Every sectioning + command (\DescRef{\LabelBase.cmd.chapter}, \DescRef{\LabelBase.cmd.section}, + etc.) automatically executes the corresponding \Macro{\dots mark} command. + The parameter passed contains the text of the section heading% + \Index{heading}. The corresponding section number is added automatically in + the \Macro{\dots mark} command. The formatting is done according to the + sectioning level with one of the three commands \Macro{chaptermarkformat}, + \Macro{sectionmarkformat}, or \Macro{subsectionmarkformat}. + + Note\textnote{Attention!} that the running heads of \DescRef{\LabelBase.cmd.addchap}\IndexCmd{addchap} and \DescRef{\LabelBase.cmd.addsec}\IndexCmd{addsec} are also based on - \Macro{chaptermark} and \Macro{addsecmark} but locally set counter - \DescRef{\LabelBase.counter.secnumdepth} to a value that makes chapters - respectively sections not numbered. You should pay attention for this - especially if you redefine \Macro{chaptermark} or \Macro{sectionmark} (see - \Macro{ifnumbered} on \DescPageRef{\LabelBase.cmd.ifnumbered}). The star - variants \DescRef{\LabelBase.cmd.addchap*} and - \DescRef{\LabelBase.cmd.addsec*} use additional commands \Macro{addchapmark} - and \Macro{addsecmark} that are defined also basing on \Macro{chaptermark} - and \Macro{sectionmark} with local changes of - \DescRef{\LabelBase.counter.secnumdepth}. - - \OnlyAt{\Class{scrbook}\and\Class{scrreprt}}Of course there is no command - \Macro{chaptermark} or \Macro{chaptermarkformat} in - \Class{scrartcl}. \OnlyAt{\Class{scrartcl}}Accordingly, - \Macro{subsectionmark} and \Macro{subsectionmarkformat} exist only in - \Class{scrartcl}. This changes when you use the \Package{scrlayer-scrpage} - package (see \autoref{cha:scrlayer-scrpage}).\par + \Macro{chaptermark} and \Macro{sectionmark}. However, the + \DescRef{\LabelBase.counter.secnumdepth} counter is set locally to a value + that switches off the numbering of chapters or sections. You should consider + this, for example, if you redefine \Macro{chaptermark} or + \Macro{sectionmark} (see \Macro{ifnumbered} on + \DescPageRef{\LabelBase.cmd.ifnumbered}). The starred variants + \DescRef{\LabelBase.cmd.addchap*} and \DescRef{\LabelBase.cmd.addsec*} use + additional commands \Macro{addchapmark} and \Macro{addsecmark} that are also + defined based on \Macro{chaptermark} and \Macro{sectionmark} with local + changes of \DescRef{\LabelBase.counter.secnumdepth}. + + Although\OnlyAt{\Class{scrartcl}} there is no \Macro{chaptermark} or + \Macro{chaptermarkformat} command in \Class{scrartcl}, there are two + commands, \Macro{subsectionmark} and \Macro{subsectionmarkformat}, which + exist only in \Class{scrartcl}. However using the + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + \IndexPackage{scrlayer-scrpage} package changes this (see + \autoref{cha:scrlayer-scrpage}). \end{Explain} -Similar to \DescRef{\LabelBase.cmd.partformat} down to -\DescRef{\LabelBase.cmd.subparagraphformat} for formatting the numbers in the -headings, the commands \Macro{chaptermarkformat} (not in \Class{scrartcl}), -\Macro{sectionmarkformat}, and \Macro{subsectionmarkformat} (only in -\Class{scrartcl}) define the formatting of the sectioning numbers in the -automatic running heads. They can be adapted to your personal needs with -\Macro{renewcommand}. The original definitions for the {\KOMAScript} classes -are: +Just as numbers in the sectioning-command headers are formatted with +\DescRef{\LabelBase.cmd.partformat} down to +\DescRef{\LabelBase.cmd.subparagraphformat}, \Macro{chaptermarkformat}, +\Macro{sectionmarkformat}, and \Macro{subsectionmarkformat} define the +formatting of the sectioning numbers in the automatic running heads. They can +be adapted to your personal needs with \Macro{renewcommand}. The original +definitions for the {\KOMAScript} classes are: \begin{lstcode} \newcommand*{\chaptermarkformat}{% \chapappifchapterprefix{\ }\thechapter\autodot\enskip} - \newcommand*{\sectionmarkformat}{\thesection\autodot\enskip} + \newcommand*{\sectionmarkformat}{% + \thesection\autodot\enskip} \newcommand*{\subsectionmarkformat}{% \thesubsection\autodot\enskip} \end{lstcode} \begin{Example} - Suppose you want to prepend the word ``Chapter'' to the chapter - number in the running heading. For example you could insert the - following definition in the preamble of your document: + Suppose you want the word ``Chapter'' to precede the chapter number in the + running head. You could put the following definition in the preamble of your + document: \begin{lstcode} \renewcommand*{\chaptermarkformat}{% \chapapp~\thechapter\autodot\enskip} \end{lstcode} \end{Example} -As you can see, both the commands -\DescRef{\LabelBase.cmd.chapappifchapterprefix} and -\DescRef{\LabelBase.cmd.chapapp} explained above are used here.% -% +As you can see, both \DescRef{\LabelBase.cmd.chapapp} and +\DescRef{\LabelBase.cmd.chapappifchapterprefix}, explained above, are used +here.% \EndIndexGroup \begin{Declaration} - \Counter{secnumdepth}% - \Macro{partnumdepth}% - \Macro{chapternumdepth}% - \Macro{sectionnumdepth}% - \Macro{subsectionnumdepth}% - \Macro{subsubsectionnumdepth}% - \Macro{paragraphnumdepth}% + \Counter{secnumdepth} + \Macro{partnumdepth} + \Macro{chapternumdepth} + \Macro{sectionnumdepth} + \Macro{subsectionnumdepth} + \Macro{subsubsectionnumdepth} + \Macro{paragraphnumdepth} \Macro{subparagraphnumdepth} \end{Declaration}% -\BeginIndex{}{numbering}% -Section levels in the classes \Class{scrbook}\IndexClass{scrbook} and -\Class{scrreport}\IndexClass{scrreprt} are, by default, numbered from -\DescRef{\LabelBase.cmd.part}\IndexCmd{part}\IndexCmd{chapter}\IndexCmd{section} -down to \DescRef{\LabelBase.cmd.subsection}\IndexCmd{subsection}. In class -\Class{scrartcl}\IndexClass{scrartcl} the default numbering is from +\BeginIndex{}{Nummerierung}% +Normally, the \Class{scrbook}\IndexClass{scrbook} and +\Class{scrreport}\IndexClass{scrreprt} classes number the section headings +from \DescRef{\LabelBase.cmd.part}\IndexCmd{part}\IndexCmd{chapter}% +\IndexCmd{section} down to +\DescRef{\LabelBase.cmd.subsection}\IndexCmd{subsection} and the +\Class{scrartcl}\IndexClass{scrartcl} class numbers them from \DescRef{\LabelBase.cmd.part} down to -\DescRef{\LabelBase.cmd.subsubsection}\IndexCmd{subsubsection}. The actual -depth to which headings will be numbered is controlled by the \LaTeX{} counter -\Counter{secnumdepth}. Since version~3.12 \KOMAScript{} provides the commands -\Macro{partnumdepth} to \Macro{subparagraphnumdepth} which return the number -that corresponds to the level they bear in their name. This saves users the -trouble of having to remember abstract numbers and allows them to define the -depth to which headings should be numbered with relative ease. - -\KOMAScript{} provides the commands \Macro{partnumdepth} to -\Macro{subparagraphnumdepth} so\ChangedAt{v3.12}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} users do not have to remember -abstract numbers, to be able to define the section level down to which -headings should be numbered. These commands stand for the corresponding -numbers of the section levels.% +\DescRef{\LabelBase.cmd.subsubsection}\IndexCmd{subsubsection}. The actual +depth to which headings are numbered is controlled by the \LaTeX{} counter +\Counter{secnumdepth}. + +To\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} +save users the trouble of having to remember abstract numbers, the commands +\Macro{partnumdepth} to \Macro{subparagraphnumdepth} return the appropriate +number for the section level in their name. + \begin{Example} - For a book project you want the section levels from part down to the section + For a book project, you want the section levels from part down to section to be numbered. To achieve this, you have to set counter \Counter{secnumdepth} to the value represented by \Macro{sectionnumdepth} in the preamble of your document: @@ -2340,37 +2698,34 @@ numbers of the section levels.% \setcounter{secnumdepth}{\sectionnumdepth} \end{lstcode} \end{Example} -Redefining these commands is not allowed. Doing so could lead to unexpected -results not only with \KOMAScript{} but also with third party packages. Thus, -it is recommended to never redefine any of them. - -Do not confuse the counters \Counter{secnumdepth} and -\DescRef{\LabelBase.counter.tocdepth}, please refer to the explanation -concerning the counter \DescRef{\LabelBase.counter.tocdepth} in -\autoref{sec:\LabelBase.toc}, -\DescPageRef{\LabelBase.counter.tocdepth}. Actually, depending on the class -you are using, the meaning of the values of the counters \Counter{secnumdepth} -and \DescRef{\LabelBase.counter.tocdepth} may deviate from one another for the -same section level.% +No provision is made for redefining these commands. Doing so could lead to +unexpected results, not only with \KOMAScript{} but also with third party +packages. Thus, you should never redefine them. + +Do\textnote{Attention!} not confuse the \Counter{secnumdepth} and +\DescRef{\LabelBase.counter.tocdepth} counters (see +\autoref{sec:\LabelBase.toc}, \DescPageRef{\LabelBase.counter.tocdepth}). +Depending on the class you are using, the meaning of the values of the +\Counter{secnumdepth} and \DescRef{\LabelBase.counter.tocdepth} counters may +differ for the same section level.% +% \EndIndexGroup - \begin{Declaration} \Macro{ifnumbered}\Parameter{section level}% \Parameter{then code}\Parameter{else code}% \Macro{ifunnumbered}\Parameter{section level}% \Parameter{then code}\Parameter{else code} \end{Declaration} -After\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} describing above how to define down to which section level -headings are numbered, the commands \Macro{ifnumbered} and -\Macro{ifunnumbered} can be used to execute code depending on whether a -\PName{section level} is numbered or not. If the current setting of -\DescRef{\LabelBase.counter.secnumdepth} stipulates that a \PName{section - level} will be numbered, the \PName{then code} after \Macro{ifnumbered} gets -executed. If it is not numbered, the \PName{else code} gets executed. The +The\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} commands \Macro{ifnumbered} and \Macro{ifunnumbered} +determine which section-level headings are numbered, using the technique +described above, and execute code depending on whether a \PName{section level} +is numbered or not. If a \PName{section level} is numbered with the current +settings, \Macro{ifnumbered} executes the \PName{then code}. If the section +level is unnumbered, the \PName{else code} is executed. The \Macro{ifunnumbered} command behaves in exactly the opposite manner, executing -the \PName{then code} if the current level is not numbered and the \PName{else +the \PName{then code} if the current level is unnumbered and the \PName{else code} if it is. The \PName{section level} parameter is simply the \LaTeX{} name of a section like \PValue{part}, \PValue{chapter}, \PValue{section}, \PValue{subsection}, \PValue{subsubsection}, \PValue{paragraph} oder @@ -2379,36 +2734,36 @@ name of a section like \PValue{part}, \PValue{chapter}, \PValue{section}, \PValue{subparagraph}. \KOMAScript{} itself uses these tests, for example, in the definition of -\DescRef{\LabelBase.cmd.chaptermark}\IndexCmd{chaptermark} within page style -\PageStyle{headings}\IndexPagestyle{headings}. This indirectly guarantees that -headings inserted by \DescRef{\LabelBase.cmd.addchap} do not set a number -inside the running head (see also \DescRef{\LabelBase.cmd.addchapmark}, +\DescRef{\LabelBase.cmd.chaptermark}\IndexCmd{chaptermark} in the +\DescRef{\LabelBase.pagestyle.headings}\IndexPagestyle{headings} page style. +This indirectly ensures that headings inserted by +\DescRef{\LabelBase.cmd.addchap} do not set a number inside the running head +(see also \DescRef{\LabelBase.cmd.addchapmark}, \DescPageRef{\LabelBase.cmd.addchapmark}).% \EndIndexGroup \begin{Declaration} \Macro{setpartpreamble}% - \OParameter{position}\OParameter{width}\Parameter{preamble}% + \OParameter{position}\OParameter{width}\Parameter{preamble} \Macro{setchapterpreamble}% \OParameter{position}\OParameter{width}\Parameter{preamble} \end{Declaration}% Parts\OnlyAt{\Class{scrbook}\and \Class{scrreprt}}\Index{part>preamble}\Index{chapter>preamble} and chapters -in {\KOMAScript} can be started with a \PName{preamble}. This is particularly -useful when you are using a two column layout with the class option -\Option{twocolumn}\IndexOption{twocolumn}, since the heading together with the -\PName{preamble} is always set in a one column layout. The \PName{preamble} -can comprise more than one paragraph. The command to output the -\PName{preamble} has to be placed before the respective \DescRef{\LabelBase.cmd.part}, +in {\KOMAScript} can be given a \PName{preamble}. This is particularly useful +when you are using a two-column format with the class option +\Option{twocolumn}\IndexOption{twocolumn}, since the heading and the +\PName{preamble} are always set in a one-column layout. The \PName{preamble} +can contain more than one paragraph. The command to set the \PName{preamble} +must come before the respective \DescRef{\LabelBase.cmd.part}, \DescRef{\LabelBase.cmd.addpart}, \DescRef{\LabelBase.cmd.chapter}, or \DescRef{\LabelBase.cmd.addchap} command. \begin{Example} - You are writing a report about the condition of a company. You - organize the report in such a way that every department gets its own - partial report. Every one of these parts should be introduced by an - abstract on the corresponding title page. You could write the - following: + You are writing a report about the condition of a company. You organize the + report in such a way that every department gets its own partial report. + Each of these parts should be introduced by an abstract on the corresponding + title page. You could write the following: \begin{lstcode} \setpartpreamble{% \begin{abstract} @@ -2423,10 +2778,10 @@ can comprise more than one paragraph. The command to output the (see \DescPageRef{\LabelBase.option.headings}) and the options for the \DescRef{\LabelBase.env.abstract} environment\IndexEnv{abstract} (see \autoref{sec:\LabelBase.abstract}, - \DescPageRef{\LabelBase.option.abstract}), the result would look - similar to: + \DescPageRef{\LabelBase.option.abstract}), the result will look something + like this: \begin{ShowOutput}\centering - {\LARGE\usekomafont{disposition} Part III.\par\vspace{20pt}} + {\LARGE\usekomafont{disposition} Part III.\par\vspace{14pt}} {\LARGE\usekomafont{disposition} Department for Word Processing\strut\par} \begin{quote}\small \vspace{4ex} @@ -2440,46 +2795,53 @@ can comprise more than one paragraph. The command to output the \end{quote} \end{ShowOutput} \end{Example} -Please\textnote{Attention!} note that it is \emph{you} who is responsible for -the spaces between the heading, preamble and the following text. Please note -also that there is no \DescRef{\LabelBase.env.abstract} environment in the -class \Class{scrbook} (see \autoref{sec:\LabelBase.abstract}, +Please\textnote{Attention!} note that \emph{you} are responsible for the +spacing between the heading, preamble, and the following text. Note also that +there is no \DescRef{\LabelBase.env.abstract} environment in the +\Class{scrbook} class (see \autoref{sec:\LabelBase.abstract}, \DescPageRef{\LabelBase.env.abstract}). -The\ChangedAt{v2.8p}{\Class{scrbook}\and\Class{scrreprt}} first -optional argument \PName{position} determines the position at which -the preamble is placed with the help of one or two letters. For the -vertical placement there are two possibilities at present: +The\ChangedAt{v2.8p}{\Class{scrbook}\and\Class{scrreprt}} first optional +argument, \PName{position}, determines the position at which the preamble +is placed with the help of one or two letters. For vertical placement +there are two possibilities at present: \begin{labeling}[~--]{\quad\PValue{o}}\itemsep=0pt \item [\quad\texttt{o}] above the heading \item [\quad\texttt{u}] below the heading \end{labeling} -You can insert one preamble above and another below a heading. For the -horizontal placement you have the choice between three alignments: +You can therefore put one preamble above and another below a heading. For +horizontal placement you have three options: \begin{labeling}[~--]{\quad\PValue{o}}\itemsep=0pt \item [\quad\texttt{l}] left-aligned \item [\quad\texttt{r}] right-aligned -\item [\quad\texttt{c}] centered +\item [\quad\texttt{c}] centred \end{labeling} -However, this does not output the text of the \PName{preamble} in such -a manner, but inserts a box whose width is determined by the second -optional argument \PName{width}. If you leave out this second argument -the whole text width is used. In that case the option for horizontal -positioning will have no effect. You can combine exactly one letter -from the vertical with one letter from the horizontal positioning. - -A more often usage of \Macro{setchapterpreamble} would be something like a -smart slogan or dictum to a heading. The command -\DescRef{\LabelBase.cmd.dictum}\IndexCmd{dictum}, that may be used for this, -will be described at the next section. You will also find an example there. +This setting does not affect the alignment of the text in the +\PName{preamble}. Instead, it aligns the box that contains the preamble. The +width of this box is determined by the second optional argument, +\PName{width}. If you omit this second argument, the box uses the full text +width. In that case, the option for horizontal positioning has no effect. You +can combine exactly one letter from the vertical with one letter from the +horizontal positioning. + +A typical use for \Macro{setchapterpreamble} would be something like an +epigraph, a wise saying, or a dictum. The +\DescRef{\LabelBase.cmd.dictum}\IndexCmd{dictum} command, which you can use +for this purpose, is described in the next section. You will also find an +example there. Please note\textnote{Attention!} that a \PName{preamble} placed above the -chapter headings will be set into the already existing vertical space above -the heading. The heading will not be moved down. It is you who is responsible -for ensuring that the preamble is small enough and the space is -sufficient. See also \DescRef{maincls-experts.cmd.chapterheadstartvskip} in +heading is set within the existing vertical space above the heading. The +heading will not be moved down. You are therefore responsible for ensuring +that the \PName{preamble} is not too large and that the space above the +heading is sufficient. See also the \Option{beforeskip} setting for +\DescRef{maincls-experts.cmd.RedeclareSectionCommand} in \autoref{sec:maincls-experts.experts}, -\DescPageRef{maincls-experts.cmd.chapterheadstartvskip} for this.% +\autoref{tab:maincls-experts.declarechapterstyle.keys}, +\autopageref{tab:maincls-experts.declarechapterstyle.keys}. +% +% +\EndIndexGroup % \EndIndexGroup @@ -2488,39 +2850,40 @@ sufficient. See also \DescRef{maincls-experts.cmd.chapterheadstartvskip} in \LoadCommonFile{lists}% \section{Lists} - -\section{Math} +\section{Mathematics} \seclabel{math}% \BeginIndexGroup \BeginIndex{}{equations}% \BeginIndex{}{formulas}% \BeginIndex{}{mathematics}% -There are no math environments implemented in the \KOMAScript{} -classes. Instead of this, the math features of the \LaTeX{} kernel have been -supported. With this also, the options \DescRef{\LabelBase.option.leqno} and -\DescRef{\LabelBase.option.fleqn} are available. - -You will not find a description of the math environments of the \LaTeX{} kernel -here. If you want to use \Environment{displaymath}\IndexEnv{displaymath}, -\Environment{equation}\IndexEnv{equation}, and -\Environment{eqnarray}\IndexEnv{eqnarray} you should read a short introduction -into \LaTeX{} like \cite{lshort}. But\textnote{Hint!} if you want more than -very simple mathematics, usage of package \Package{amsmath} would be -recommended (see \cite{package:amsmath}). +\KOMAScript{} classes do not provide their own environments for formulas, +systems of equations, or similar mathematical elements. Instead, \KOMAScript{} +relies fully on the maths features of the \LaTeX{} kernel. This also applies to +the the options \DescRef{\LabelBase.option.leqno} and +\DescRef{\LabelBase.option.fleqn}. + +You will not find a description of the maths environments of the \LaTeX{} +kernel here. If you want to use +\Environment{displaymath}\IndexEnv{displaymath}, +\Environment{equation}\IndexEnv{equation}, or +\Environment{eqnarray}\IndexEnv{eqnarray} you should read an introduction to +\LaTeX{} like \cite{lshort}. But\textnote{Hint!} if you want more than very +simple mathematics, you should use the \Package{amsmath} package (see +\cite{package:amsmath}). \begin{Declaration} \Option{leqno} \end{Declaration}% -Equations are normally numbered\Index{equation>number} on the right. The -standard option \Option{leqno} causes the standard option file -\File{leqno.clo} to be loaded. The equations are then numbered on the -left. This\textnote{Attention!} option has to be used as an optional argument -of \DescRef{\LabelBase.cmd.documentclass}. Usage as an argument of -\DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption} is -not supported. This would not make sense, because the recommended math package -\Package{amsmath} supports the option at loading time only too and would not -react on run-time changes of the option. +Equations are normally numbered\Index{equation>number} on the right. The +\Option{leqno} option loads the standard option file \File{leqno.clo}. The +equations are then numbered on the left. You\textnote{Attention!} must use +this option as an optional argument of \DescRef{\LabelBase.cmd.documentclass}. +Using it as an argument of \DescRef{\LabelBase.cmd.KOMAoptions} or +\DescRef{\LabelBase.cmd.KOMAoption} is not supported. The latter +would not make sense because the recommended maths package \Package{amsmath} +can only respond to this option at load time and does not react to run-time +changes of the option. % \EndIndexGroup @@ -2528,293 +2891,296 @@ react on run-time changes of the option. \begin{Declaration} \Option{fleqn} \end{Declaration}% -Displayed equations\Index{equation>alignment} are normally centered. The -standard option \Option{fleqn} causes the standard option file -\File{fleqn.clo} to be loaded. Displayed equations are then -left-justified. This option may be used as an optional argument of -\DescRef{\LabelBase.cmd.documentclass} but not as an argument of -\DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption}. -The latter would not make sense, because the recommended math package -\Package{amsmath} supports the option at loading time only too and would not -react on run-time changes of the option. +Displayed equations\Index{equation>alignment} are normally centred. The +standard option \Option{fleqn} loads the standard option file +\File{fleqn.clo}. Displayed equations are then left-justified. +You\textnote{Attention!} must use this option as an optional argument of +\DescRef{\LabelBase.cmd.documentclass}. Using it as an argument of +\DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoption} is +not supported. The latter would not make sense because the recommended maths +package \Package{amsmath} can only respond to this option at load time and +does not react to run-time changes of the option. % \EndIndexGroup % \EndIndexGroup -\section{Floating Environments of Tables and Figures} +\section{Floating Environments for Tables and Figures} \seclabel{floats} \BeginIndexGroup \BeginIndex{}{floats}% \BeginIndex{}{tables}% \BeginIndex{}{figures}% -With the floating environments, {\LaTeX} offers a very capable and comfortable -mechanism for automatic placement of figures\Index{figure} and -tables\Index{table}. +With the floating environments, {\LaTeX} offers a powerful and convenient +mechanism to arrange figures\Index{figure} and tables\Index{table} +automatically. % Im Deutschen ist hier ein Absatz, den wir nicht uebernehmen! -But\textnote{Attention!} often these floating environments\Index[indexmain] -{floating environments} are slightly misunderstood by beginners. They often -ask for a fixed position of a table or figure within the text. However, since -these floating environments are being referenced in the text this is not -necessary in most cases. It is also not sensible because such an object can -only be set on the page if there is enough space left for it. If this is not -the case the object would have to be shifted onto the next page, thereby -possibly leaving a huge blank space on the page before. - -Often\textnote{Attention!} one finds in a document for every floating object -the same optional argument for positioning the object. This also makes no -sense. In such cases one should rather change the standard parameter -globally. For more details refer to \cite{DANTE:FAQ}. +Frequently,\textnote{Attention!} beginners do not properly understand these +floating environments\Index[indexmain]{floating environments}. They often ask +to specify the exact position of a table or figure within the text. However, +this is usually unnecessary, since the text will contain references to these +floating environments. It is also not sensible because such an object can only +be set on the page if there is enough space left for it. If this is not the +case, the object would have to be shifted onto the next page, possibly leaving +a huge empty space on the previous page. + +Often\textnote{Attention!} a document will use the same optional argument to +position every floating object. This also makes no sense. In such cases, you +should instead change the default value globally. For more details, see +\cite{DANTE:FAQ}. + +One\textnote{Attention!} final, important note before starting this section: +most of mechanisms described here, which extend the capabilities of the +standard classes, no longer work correctly when used with packages that modify +the appearance of figure and table captions. This should be self-evident, but +it is often overlooked. -One\textnote{Attention!} last important note before starting this section: -most mechanisms described here which extend the capabilities of the standard -classes no longer work correctly when used together with packages which modify -the typesetting of captions of figures and tables. This should be self -evident, but it is often not understood. \begin{Declaration} - \OptionVName{captions}{selection} + \OptionVName{captions}{setting} \end{Declaration} -The standard classes format titles of floating environments, which are placed -with \DescRef{\LabelBase.cmd.caption}\IndexCmd{caption} (see below), like signatures. They -differentiate between one-line and multi-line table or figure -captions. One-line captions are centered while multi-line captions are -left-justified. - -\leavevmode\phantomsection\nobreak -\label{desc:\LabelBase.option.captions.tableheading}\nobreak -For tables, however, headings are often used. That's because there may -be tables that span several pages. Surely the reader wants to know the -purpose of the table at the first page already. Furthermore tables -will be read row by row from top down to bottom. So there are at least -two good reasons to generally use table -headings. \KOMAScript{}\important{\OptionValue{captions}{tableheading}} -therefor supports option \OptionValue{captions}{tableheading}% -\IndexOption{captions~=\PValue{tableheading}}, which changes the -caption format into headings at tables only. - -Please note\textnote{Attention!} that multi-page tabulars may not use any -floating environment. To have an automatic page break at any kind of tabular you -also need additional packages like \Package{longtable}\IndexPackage{longtable} -(see \cite{package:longtable}) or \Package{tabu}\IndexPackage{tabu} (see -\cite{package:tabu}). - -You may switch back\important[i]{\begin{tabular}[t]{@{}l@{}} - \Option{captions=}\\ - \quad\PValue{tablesignature} - \end{tabular}} to the default table signatures using -\OptionValue{captions}{tablesignature}% -\IndexOption{captions~=\PValue{tablesignature}}. -Note\textnote{Attention!} that using any of these options does not change the position of -the caption from above the top of the table to below the bottom of the -table or vice versa. It only affects whether the text is formatted as -a caption for use above or below a table. Whether the text is in fact -placed above or below a table is set through the position of the -\DescRef{\LabelBase.cmd.caption} command inside the \Environment{table} environment. This may -change using package \Package{float}\IndexPackage{float} and command -\Macro{restylefloats} (see \cite{package:float}). - -Of course similar features exist\ChangedAt{v3.09}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} for figures using options +In the standard classes, the titles of floating environments, which are +formatted with the \DescRef{\LabelBase.cmd.caption}\IndexCmd{caption} command +(see below), are set off from the float with vertical spacing appropriate for +putting the caption beneath the float, like a signature. They also distinguish +between one-line and multi-line captions. One-line captions are centred while +multi-line captions are left-justified. + +\leavevmode\LabelOptionValue{captions}{tableheading}\nobreak% +For tables, however, you want the caption% +\important{\Option{captions}{tableheading}} to appear as a heading instead of +a signature. That's because tables can span multiple pages. With such tables, +the reader wants to know the purpose of the table on the first page. +Furthermore, tables are usually read row by row, from top to bottom. So there +are normally at least two good reasons to provide all tables with headings. +\KOMAScript{} therefore offers the \OptionValue{captions}{tableheading}% +\IndexOption{captions~=\textKValue{tableheading}} option, which changes the +formatting of table captions for use above the table. + +Note\textnote{Attention!} that multi-page tabulars cannot use a floating +environment. To have an automatic page break in a tabular you need an +additional package like \Package{longtable}\IndexPackage{longtable} (see +\cite{package:longtable}) or \Package{supertabular}\IndexPackage{supertabular} +(see \cite{package:supertabular}). + +You\important{\OptionValue{captions}{tablesignature}} can switch back to the +default caption formatting using \OptionValue{captions}{tablesignature}% +\IndexOption{captions~=\textKValue{tablesignature}}. Note\textnote{Attention!} +that these options change only the formatting, not the actual position of the +caption. Whether the caption is placed above or below a float depends solely +upon where you use the \DescRef{\LabelBase.cmd.caption} command inside float +environment. However, this can change when using the \Package{float}% +\IndexPackage{float} package with the \Macro{restylefloats} command (see +\cite{package:float}). + +Of course\important{\OptionValue{captions}{figureheading}\\ + \OptionValue{captions}{figuresignature}}, corresponding functions +exist\ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} for figures using the options \OptionValue{captions}{figureheading}% -\IndexOption{captions~=\PValue{figureheading}} and +\IndexOption{captions~=\textKValue{figureheading}} and \OptionValue{captions}{figuresignature}% -\IndexOption{captions~=\PValue{figuresignature}}. Nevertheless, -figures like photos will be viewed as a whole, and a diagram or graph -will mostly be examined from left bottom to the right. Therefore, in -general, signatures should be used and it would not be useful to change -the caption format from signatures to headings. - -Nevertheless sometimes all floating environments shall use headings. For this -\KOMAScript{} supports\ChangedAt{v3.09}{\Class{scrbook}\and +\IndexOption{captions~=\textKValue{figuresignature}}. However, figures such as +photos tend to be viewed as a whole, and a diagram or graph will mostly be +examined starting from the lower left. Therefore, it only rarely makes sense +to change the caption format for figures alone from signatures to headings. + +Sometimes, however, all floating environments should use headings. Therefore +\KOMAScript{} provides\ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -options\important[i]{\OptionValue{captions}{heading}\\ - \OptionValue{captions}{signature}} -\OptionValue{captions}{heading}\IndexOption{captions~=\PValue{heading}} and -\OptionValue{captions}{signature}\IndexOption{captions~=\PValue{signature}} to -switch the format of every floating environment. These options may be used -also inside a floating environment but before using \DescRef{\LabelBase.cmd.caption}. - -Note\textnote{Attention!}\OnlyAt{\Package{float}}\IndexPackage{float} that -when using the \Package{float} package, the options -\OptionValue{captions}{tablesignature} and -\OptionValue{captions}{tableheading} cease to act correctly when -\Macro{restylefloat} is applied to tables. More details of the \Package{float} -package and \Macro{restylefloat} can be found in -\cite{package:float}. Additional support in {\KOMAScript} for the -\Package{float} package may be found at the explanation of \PValue{komaabove} -(see \DescPageRef{\LabelBase.floatstyle.komaabove}). - -\leavevmode\phantomsection\nobreak -\label{desc:\LabelBase.option.captions.nooneline}\nobreak -\label{desc:\LabelBase.option.captions.oneline}\nobreak -Furthermore, \KOMAScript{} supports to switch off the distinguish of captions -with only one line or more than one line using option -\OptionValue{captions}{nooneline}\IndexOption{captions~=\PValue{nooneline}}% -\important{\OptionValue{captions}{nooneline}}. This may be useful, if one-line -captions should not be centered. The default of centering one-line captions -corresponds to \OptionValue{captions}{oneline}. - -Another special feature of \KOMAScript{} is to alternatively put the caption -neither above nor below the floating object but beside -it. For this you need Environment\important{\DescRef{\LabelBase.env.captionbeside}} -\DescRef{\LabelBase.env.captionbeside}\IndexEnv{captionbeside}, that will be described -from \DescPageRef{\LabelBase.env.captionbeside}. Several settings -for this environment may be done also using \Option{caption}. You may find all -the available \PName{settings} at \autoref{tab:\LabelBase.captions}. +options\important{\OptionValue{captions}{heading}\\ + \OptionValue{captions}{signature}} +\OptionValue{captions}{heading}\IndexOption{captions~=\textKValue{heading}} +and \OptionValue{captions}{signature}% +\IndexOption{captions~=\textKValue{signature}} to switch the format of every +floating environment. These options can also be used inside a floating +environment. + +Please note\textnote{Achtung!}\OnlyAt{\Package{float}}\IndexPackage{float} +when using the \Package{float} package that the settings for signatures or +headings will no longer work once \Macro{restylefloat} is applied to tables or +figures. For details about the \Package{float} package and +\Macro{restylefloat}, please refer to \cite{package:float}. This also applies +to \DescRef{\LabelBase.cmd.caption} within new floating environments defined +with \Package{float}. You can find additional support which \KOMAScript{} +provides when using the \Package{float} package in the explanation of +\PValue{komaabove} (see \DescPageRef{\LabelBase.floatstyle.komaabove}). As an +alternative to \Package{float}, you can also consult +\DescRef{\LabelBase.cmd.captionof} (see +\DescPageRef{\LabelBase.cmd.captionof}) and +\DescRef{tocbasic.cmd.DeclareNewTOC} (see +\DescPageRef{tocbasic.cmd.DeclareNewTOC}). Additionally, when using +\Package{float}, the +\hyperref[cha:scrhack]{\Package{scrhack}}\IndexPackage{scrhack}% +\important{\hyperref[cha:scrhack]{\Package{scrhack}}} package is +expressly recommended (see \autoref{cha:scrhack} from +\autopageref{cha:scrhack} in \autoref{part:forExperts}). + +\leavevmode +\LabelOptionValue{captions}{nooneline}\nobreak +\LabelOptionValue{captions}{oneline}\nobreak +Furthermore\important{\OptionValue{captions}{nooneline}}, \KOMAScript{} offers +the option to disable the distinction between one-line and multi-line captions +using the \OptionValue{captions}{nooneline}% +\IndexOption{captions~=\textKValue{nooneline}}% +\important{\OptionValue{captions}{nooneline}} option. This can be useful, for +example, if you do not want one-line captions to be centred. The default, +where one-line captions are centred, corresponds to +\OptionValue{captions}{oneline}. + +Another special feature of \KOMAScript{} is the ability to put the caption +beside the floating object rather than above or below it. For this, you need +the environment\important{\DescRef{\LabelBase.env.captionbeside}} +\DescRef{\LabelBase.env.captionbeside}\IndexEnv{captionbeside}, which is +explained starting on \DescPageRef{\LabelBase.env.captionbeside}. The settings +for this environment can also be changed with the \Option{caption} option. You +can find the available values for the corresponding \PName{settings} in +\autoref{tab:\LabelBase.captions}. % \begin{desclist} - \desccaption[{Available values for option \Option{captions}}]{% - Available values for option \Option{captions} to select formation of - captions as headings or signatures at floating environments% + \desccaption[{Available values for the \Option{captions}} option]{% + Available values for the \Option{captions} option for setting formatting of + captions as headings or signatures in floating environments% \label{tab:\LabelBase.captions}% }{% - Available values for option \Option{captions} (\emph{continuation})% + Available values for the \Option{captions} option (\emph{continued})% }% \entry{\PValue{bottombeside}, \PValue{besidebottom}}{% - Captions and contents of environment - \DescRef{\LabelBase.env.captionbeside} (see - \autoref{sec:\LabelBase.floats}, - \DescPageRef{\LabelBase.env.captionbeside}) will be vertically align - depending on the bottommost base lines.% - \IndexOption{captions~=\PValue{bottombeside}}}% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see + \autoref{sec:\LabelBase.floats}, + \DescPageRef{\LabelBase.env.captionbeside}) are vertically aligned with + the bottommost baseline of the contents of the floating environment.% + \IndexOption{captions~=\textKValue{bottombeside}}}% \entry{\PValue{centeredbeside}, \PValue{besidecentered}, \PValue{middlebeside}, \PValue{besidemiddle}}{% - Captions and contents of environment - \DescRef{\LabelBase.env.captionbeside} (see + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see \autoref{sec:\LabelBase.floats}, - \DescPageRef{\LabelBase.env.captionbeside}) will be vertically centered% - \IndexOption{captions~=\PValue{centeredbeside}}}% + \DescPageRef{\LabelBase.env.captionbeside}) are vertically aligned with + the center of the contents of the floating environment.% + \IndexOption{captions~=\textKValue{centeredbeside}}}% \entry{\PValue{figureheading}, \PValue{figureabove}, \PValue{abovefigure}, \PValue{topatfigure}% - \IndexOption{captions~=\PValue{figureheading}}}{% + \IndexOption{captions~=\textKValue{figureheading}}}{% \ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - Captions of figures will use heading formation\,---\,maybe in discrepancy - to \OptionValue{captions}{signature}.% + Captions for figures use heading format\,---\,possibly deviating from + \OptionValue{captions}{signature}.% }% \entry{\PValue{figuresignature}, \PValue{belowfigure}, \PValue{bottomatfiggure}% - \IndexOption{captions~=\PValue{figuresignature}}}{% + \IndexOption{captions~=\textKValue{figuresignature}}}{% \ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - Captions of figures will use signature formation\,---\,maybe in - discrepancy to \OptionValue{captions}{headings}.% + Captions for figures use signature format\,---\,possibly deviating + from \OptionValue{captions}{headings}.% }% \entry{\PValue{heading}, \PValue{above}, \PValue{top}% - \IndexOption{captions~=\PValue{heading}}}{% + \IndexOption{captions~=\textKValue{heading}}}{% \ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} Captions of floating environments will use heading - formation. Nevertheless this does not influence whether they are really - placed at the top or at the bottom of the object. This options also + \Class{scrartcl}} Captions for floating environments use formatting + suitable for use in a heading. This setting does not control whether they + are placed at the top or the bottom of the object. This option also implies \OptionValue{captions}{tableheading} and \OptionValue{captions}{figureheading}.% }% \entry{\PValue{innerbeside}, - \PValue{besideinner}\IndexOption{captions~=\PValue{innerbeside}}}{% - Captions of environment \DescRef{\LabelBase.env.captionbeside} (siehe + \PValue{besideinner}\IndexOption{captions~=\textKValue{innerbeside}}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see \autoref{sec:\LabelBase.floats}, - \DescPageRef{\LabelBase.env.captionbeside}) will be placed innermost - beside the contents of the environment at double-side printing. At - single-side printing \OptionValue{captions}{leftbeside} will be used.% + \DescPageRef{\LabelBase.env.captionbeside}) are placed inside of and next + to the contents of the environment in two-sided printing. In one-sided + printing, \OptionValue{captions}{leftbeside} is used.% }% \entry{\PValue{leftbeside}, - \PValue{besideleft}\IndexOption{captions~=\PValue{leftbeside}}}{% - Captions of environment \DescRef{\LabelBase.env.captionbeside} (siehe + \PValue{besideleft}\IndexOption{captions~=\textKValue{leftbeside}}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see \autoref{sec:\LabelBase.floats}, - \DescPageRef{\LabelBase.env.captionbeside}) will be placed left beside the - contents of the environment.% + \DescPageRef{\LabelBase.env.captionbeside}) are placed to the left of + the contents of the floating environment.% }% \pventry{nooneline}{% - Captions with only one line will not be handled different from captions - with more than one line.% - \IndexOption{captions~=\PValue{nooneline}}}% + Single-line captions are handled the same as multi-line captions.% + \IndexOption{captions~=\textKValue{nooneline}}}% \pventry{oneline}{% - Captions with only one line will be centered horizontally.% - \IndexOption{captions~=\PValue{oneline}}}% + Single-line captions are centred horizontally.% + \IndexOption{captions~=\textKValue{oneline}}}% \entry{\PValue{outerbeside}, \PValue{besideouter}% - \IndexOption{captions~=\PValue{outerbeside}}}{% - Captions of environment \DescRef{\LabelBase.env.captionbeside} (siehe + \IndexOption{captions~=\textKValue{outerbeside}}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see \autoref{sec:\LabelBase.floats}, - \DescPageRef{\LabelBase.env.captionbeside}) will be placed outermost - beside the contents of the environment at double-side printing. At - single-side printing \OptionValue{captions}{rightbeside} will be used.% + \DescPageRef{\LabelBase.env.captionbeside}) are placed outside of and + next to the contents of the environment in two-sided printing. In + one-sided printing, \OptionValue{captions}{rightbeside} is used.% }% \entry{\PValue{rightbeside}, \PValue{besideright}% - \IndexOption{captions~=\PValue{rightbeside}}}{% - Captions of environment \DescRef{\LabelBase.env.captionbeside} (siehe + \IndexOption{captions~=\textKValue{rightbeside}}}{% + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see \autoref{sec:\LabelBase.floats}, - \DescPageRef{\LabelBase.env.captionbeside}) will be placed right beside - the contents of the environment.% + \DescPageRef{\LabelBase.env.captionbeside}) are placed to the right of the + contents of the floating environment.% }% \entry{\PValue{signature}, \PValue{below}, \PValue{bot}, \PValue{bottom}% - \IndexOption{captions~=\PValue{signature}}}{% + \IndexOption{captions~=\textKValue{signature}}}{% \ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - Captions of floating environments will use signature - formation. Nevertheless this does not influence whether they are really - placed at the top or at the bottom of the object. This options also - implies \OptionValue{captions}{tablesignature} and - \OptionValue{captions}{figuresignature}.% + Captions for floating environments use signature format. This setting + does not control whether they are placed at the top or the bottom of the + object. This options also implies \OptionValue{captions}{tablesignature} + and \OptionValue{captions}{figuresignature}.% }% \entry{\PValue{tableheading}, \PValue{tableabove}, \PValue{abovetable}, \PValue{abovetabular}, \PValue{topattable}% - \IndexOption{captions~=\PValue{tableheading}}}{% - Captions of tables will use heading formation\,---\,maybe in discrepancy - to \OptionValue{captions}{signature}.% + \IndexOption{captions~=\textKValue{tableheading}}}{% + Captions for tables use heading format\,---\,possibly deviating from + \OptionValue{captions}{signature}.% }% \entry{\PValue{tablesignature}, \PValue{belowtable}, \PValue{belowtabular}, \PValue{bottomattable}% - \IndexOption{captions~=\PValue{tablesignature}}}{% - Captions of tables will use signature formation\,---\,maybe in discrepancy - to \OptionValue{captions}{heading}.% + \IndexOption{captions~=\textKValue{tablesignature}}}{% + Captions for tables use signature format\,---\,possibly deviating + from \OptionValue{captions}{heading}.% }% \entry{\PValue{topbeside}, \PValue{besidetop}}{% - Captions and contents of environment - \DescRef{\LabelBase.env.captionbeside} (see + Captions for the \DescRef{\LabelBase.env.captionbeside} environment (see \autoref{sec:\LabelBase.floats}, - \DescPageRef{\LabelBase.env.captionbeside}) will be vertically align - depending on the topmost base lines.% - \IndexOption{captions~=\PValue{topbeside}}}% + \DescPageRef{\LabelBase.env.captionbeside}) are vertically aligned to the + baseline at the top of the floating environment.% + \IndexOption{captions~=\textKValue{topbeside}}}% \end{desclist}% % \EndIndexGroup \begin{Declaration} - \Macro{caption}\OParameter{entry}\Parameter{title}% - \Macro{captionbelow}\OParameter{entry}\Parameter{title}% + \Macro{caption}\OParameter{entry}\Parameter{title} + \Macro{captionbelow}\OParameter{entry}\Parameter{title} \Macro{captionabove}\OParameter{entry}\Parameter{title} \end{Declaration}% -In the standard classes caption text \PName{title} of tables and -figures is inserted with the \Macro{caption} command below the table -or figure. In general this is correct for figures. Opinions differ as -to whether captions of tables are to be placed above or, consistent -with captions of figures\Index{caption>of figure}, below the -table\Index{caption>of table}. That is the reason why +In the standard classes, tables and figures are given captions with the +\Macro{caption} command placed below the table or figure. For figures, this is +generally correct. For tables, opinions differ as to whether captions should +be placed above the table or, consistent with captions of +figures\Index{caption>of figure}, below it\Index{caption>of table}. Therefore {\KOMAScript}\textnote{\KOMAScript{} vs. standard classes}, unlike the standard classes, offers \Macro{captionbelow} for captions below and \Macro{captionabove} for captions above tables or figures. -Not only for tables but also for figures or all kind of floating environments -the behaviour of \Macro{caption} may be modified using option -\DescRef{\LabelBase.option.captions}\IndexOption{captions} described at the beginning of this -section. For -compatibility reasons the default behaviour of \Macro{caption} used -with all kinds of floating environments is similar to -\Macro{captionbelow}. Nevertheless it -is recommended\textnote{Hint!} to use table headings and therefor switch -behaviour of \Macro{caption} inside table environments into -\Macro{captionabove} using option -\OptionValueRef{\LabelBase}{captions}{tableheading}. Alternatively you may use -\Macro{captionabove} instead of \Macro{caption} inside of every -\Environment{table} environment. +For tables and figures, or in general for all floating environments, you can +control the behaviour of \Macro{caption} with the +\DescRef{\LabelBase.option.captions}\IndexOption{captions} option described at +the beginning of this section. For compatibility reasons, the default +behaviour of \Macro{caption} for all floating environments is like +\Macro{captionbelow}. However, you\textnote{Hint!} should use the +\OptionValueRef{\LabelBase}{captions}{tableheading} option, which switches the +behaviour of \Macro{caption} inside table environments to +\Macro{captionabove}. Alternatively, you can use \Macro{captionabove} instead +of \Macro{caption} inside every \Environment{table} environment. % \begin{Example} - Instead of using captions below a table you want to place your + Instead of using captions below a table, you want to place your captions above it\Index{table>caption}, because you have tables which span more then one page. In the standard classes you could only write: @@ -2828,7 +3194,7 @@ behaviour of \Macro{caption} inside table environments into \end{tabular} \end{table} \end{lstcode} - Then you would get the unsatisfying result: + Then you would get this unsatisfying result: \begin{ShowOutput}\centering {\usekomafont{caption}{\usekomafont{captionlabel}\tablename~30.2:} This is an example table.}\\ @@ -2860,13 +3226,12 @@ behaviour of \Macro{caption} inside table environments into \end{tabular} \end{ShowOutput} Since you want all your tables typeset with captions above, you could - of course use the option \OptionValueRef{\LabelBase}{captions}{tableheading} instead (see - \DescPageRef{\LabelBase.option.captions.tableheading}). Then you can use - \Macro{caption} as you would in the standard classes. You will get - the same result as with \Macro{captionabove}. + of course use the \OptionValueRef{\LabelBase}{captions}{tableheading} option + instead (see \DescPageRef{\LabelBase.option.captions.tableheading}). Then + you can use \Macro{caption} as you would in the standard classes. You will + get the same result as with \Macro{captionabove}. \end{Example} -\BeginIndexGroup \BeginIndex[indexother]{}{font>style}% \BeginIndex{FontElement}{caption}\LabelFontElement{caption}% \BeginIndex{FontElement}{captionlabel}\LabelFontElement{captionlabel}% @@ -2875,20 +3240,19 @@ The font style\ChangedAt{v2.8p}{% and the label\,---\,``Figure'' or ``Table'', followed by the number and the delimiter\,---\,can be changed with the commands \DescRef{\LabelBase.cmd.setkomafont} and -\DescRef{\LabelBase.cmd.addtokomafont} (see \autoref{sec:\LabelBase.textmarkup}, +\DescRef{\LabelBase.cmd.addtokomafont} (see +\autoref{sec:\LabelBase.textmarkup}, \DescPageRef{\LabelBase.cmd.setkomafont}). The respective elements for this -are \FontElement{caption}\important{\FontElement{caption}} and -\FontElement{captionlabel}\important{\FontElement{captionlabel}} (see -\autoref{tab:\LabelBase.fontelements}, \autopageref{tab:\LabelBase.fontelements}). -First the font style for the element \FontElement{caption} is applied to the -element \FontElement{captionlabel} too. After this the font style of -\FontElement{captionlabel} is applied on the respective element. The default -settings are listed in \autoref{tab:\LabelBase.captionFont}. +are \FontElement{caption}\important[i]{\FontElement{caption}\\ + \FontElement{captionlabel}} and \FontElement{captionlabel} (see +\autoref{tab:\LabelBase.fontelements}, +\autopageref{tab:\LabelBase.fontelements}). The font style for the element +\FontElement{caption} is applied to the element \FontElement{captionlabel} +before the font style of \FontElement{captionlabel} itself is applied. The +default settings are listed in \autoref{tab:\LabelBase.captionFont}. % \begin{table} % \centering% - \KOMAoptions{captions=topbeside}% - \setcapindent{0pt} % \caption \begin{captionbeside} {Font defaults for the elements of figure or table captions} @@ -2919,10 +3283,7 @@ settings are listed in \autoref{tab:\LabelBase.captionFont}. \end{lstcode} As you can see, simple extensions of the default definitions are possible. -\end{Example} -% -\EndIndexGroup -% +\end{Example}% \EndIndexGroup @@ -2934,38 +3295,39 @@ settings are listed in \autoref{tab:\LabelBase.captionFont}. \Macro{captionaboveof}\Parameter{float type}\OParameter{entry}% \Parameter{title} \end{Declaration}% -\KOMAScript{} supports a command -\Macro{captionof}\ChangedAt{v3.05}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} similar to packages -\Package{caption}\IndexPackage{caption} and -\Package{capt-of}\IndexPackage{capt-of}. You may use this command to place a -floating environment caption with corresponding entry into the list of that -kind of floating environment but even inside a another floating environment or -outside any floating environment. In difference to \DescRef{\LabelBase.cmd.caption} the kind of -floating environment has to be set as first parameter. - -Furthermore, \KOMAScript{} provides the additional commands +Like\ChangedAt{v3.05}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} the \Package{caption}\IndexPackage{caption} and +\Package{capt-of}\IndexPackage{capt-of} packages, \KOMAScript{} offers the +\Macro{captionof} command, with which you can put a caption for a floating +environment, together with an entry in the corresponding environment list, +outside of the floating environment or even in a different floating +environment. Unlike \DescRef{\LabelBase.cmd.caption}, the type of floating +environment must be specified as the first parameter. + +In addition, \KOMAScript{} also provides the commands \Macro{captionaboveof}\ChangedAt{v3.09}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} and \Macro{captionbelowof}. These are -like \Macro{captionabove} and \Macro{captionbelow} but with the additional -features and parameter of \Macro{captionof}. - -Of course \KOMAScript\ChangedAt{v3.09a}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} takes care of the \PValue{heading} -and \PValue{signature} setting of option -\DescRef{\LabelBase.option.captions}. But this feature may be lost, loading package -\Package{capt-of} or \Package{caption}. Please note the manual of package -\Package{caption} for this! -% +like \DescRef{\LabelBase.cmd.captionabove} and +\DescRef{\LabelBase.cmd.captionbelow} but with the additional features and +parameter of \Macro{captionof}. + +Of course\ChangedAt{v3.09a}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} \Macro{captionof} takes into account the \PValue{heading} +and \PValue{signature} settings of the \DescRef{\LabelBase.option.captions} +option. But this feature may be lost if you load the +\Package{capt-of}\IndexPackage{capt-of} or +\Package{caption}\IndexPackage{caption} packages. When using +\Package{caption}, you must follow the instructions for that package (see +\cite{package:caption})! \begin{Example} - Assumed you want to create a floating object with a table and a figure side - by side. As you know, there are now mixed floating environment. Therefor you - use a \Environment{figure} environment primarily: + Suppose you want to create a floating object with a table and a figure next + to each other. Since there are no mixed floating environments, you primarily + use a \Environment{figure} environment: \begin{lstcode} \begin{figure} \begin{minipage}{.5\linewidth} \centering - \rule{4cm}{3cm} + \rule{4cm}{5cm} \caption{A rectangle}\label{fig:rechteck} \end{minipage}% \begin{minipage}{.5\linewidth} @@ -2977,28 +3339,28 @@ and \PValue{signature} setting of option \label{tab:rechteck} \begin{tabular}{ll} Width: & 4\,cm\\ - Height: & 3\,cm + Height: & 5\,cm \end{tabular} \end{minipage} \end{figure} \end{lstcode} - Two \Environment{minipage} environments have been used to have figure and - table side by side. The\textnote{Attention!} percent char after the end of - the first \Environment{minipage} is important. Without an additional - inter-word distance would be made between the \Environment{minipage} + Two \Environment{minipage} environments were used to place the figure + and the table side by side. The\textnote{Attention!} percent sign after the + end of the first \Environment{minipage} is important. Without it, an + additional space would appear between the \Environment{minipage} environments. - The figure signature has been done using \DescRef{\LabelBase.cmd.caption}. The table heading - has been done using \Macro{captionaboveof} with first argument - \PValue{table}. Because of this \KOMAScript{} knows, that despite the - \Environment{figure} environment a table caption should be made. - - The optional argument of \Macro{captionaboveof} does make the entry into the - list of tables. Without the optional argument, the last mandatory argument - would have been used for the list of tables too. Although this caption text - is sufficient for the environment itself, it would be very useful at the - list of tables. Therefor a somehow more detailed description has been used - for the list of tables using the optional argument. The + The figure caption was created with \DescRef{\LabelBase.cmd.caption}. The + table caption was created with \Macro{captionaboveof} with \PValue{table} + as the first argument. Because of this, \KOMAScript{} knows that this is a + table caption even though it is inside the \Environment{figure} environment. + + The optional argument of \Macro{captionaboveof} creates an entry in the + list of tables. Without the optional argument, the caption specified in the + final mandatory argument would have been used for the list of tables too. + Although this caption text is sufficient for the environment itself, it + would not be very meaningful in the list of tables. Therefore, a different + title is used for the list of tables using the optional argument. \autoref{fig:\LabelBase.captionaboveof} shows the result of the example code.% \begin{figure} % \centering @@ -3006,16 +3368,16 @@ and \PValue{signature} setting of option \KOMAoptions{captions=bottombeside}% \setcapindent{0pt}% \begin{captionbeside} - [{Example: Usage of \Macro{captionaboveof} inside another floating + [{Example: Using \Macro{captionaboveof} inside another floating environment}] - {Example: Usage of \Macro{captionaboveof} inside another floating + {Example: Using \Macro{captionaboveof} inside another floating environment\label{fig:\LabelBase.captionaboveof}} [l] \begin{minipage}[b]{.66\linewidth}% \raisebox{\depth}{\fbox{\KOMAoptions{captions=oneline}% \begin{minipage}{.5\dimexpr\linewidth-2\fboxsep-2\fboxrule\relax} \centering - \rule{4cm}{3cm} + \rule{4cm}{5cm} \caption[Example: A rectangle]{A rectangle}\label{fig:\LabelBase.rechteck} \end{minipage}% \begin{minipage}{.5\dimexpr\linewidth-2\fboxsep-2\fboxrule\relax} @@ -3024,115 +3386,120 @@ and \PValue{signature} setting of option figure~\ref{fig:\LabelBase.rechteck}]{Rectangle size} \label{tab:\LabelBase.rechteck} \begin{tabular}{ll} - Width: & 4\,cm\\ - Height: & 3\,cm + Width: & 4\,cm\\ + Height: & 5\,cm \end{tabular} \end{minipage}}}% \end{minipage}% \end{captionbeside}% \end{figure}% \end{Example}% -A non-floating table with a caption may be produced in the same kind like the -table inside a figure environment in the example above. In such a case also a -\Environment{minipage} environment should be used, to avoid page breaks -between table caption an tabular. An additional \Environment{flushleft} -environment around the \Environment{minipage} environment may be used, to have -a pleasing distance above and below is and to avoid the paragraph indentation -of the \Environment{minipage} environment.% -% +You can produce a non-floating table with a caption in the same way as the +table inside a figure environment in the example above. In such a case, a +\Environment{minipage} environment should also be used to avoid page breaks +between the caption and the table. In addition, you should embed the +\Environment{minipage} environment in a \Environment{flushleft} environment +both to achieve a pleasing separation between the surrounding text and to +avoid the paragraph indentation of the \Environment{minipage} environment.% \EndIndexGroup \begin{Declaration} - \begin{Environment}{captionbeside}% - \OParameter{entry}\Parameter{title}% - \OParameter{placement}\OParameter{width}% - \OParameter{offset} + \begin{Environment}{captionbeside} + \OParameter{short title} + \Parameter{caption text} + \OParameter{placement} + \OParameter{width} + \OParameter{offset} \end{Environment} \labelsuffix[*]% - \begin{Environment}{captionbeside}% - \OParameter{entry}\Parameter{title}% - \OParameter{placement}\OParameter{width}% - \OParameter{offset}\PValue{*}% + \begin{Environment}{captionbeside} + \OParameter{short title} + \Parameter{caption text} + \OParameter{placement} + \OParameter{width} + \OParameter{offset}\PValue{*}% \end{Environment} \end{Declaration} -Apart\ChangedAt{v2.8q}{% - \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} from -captions above and below the figure, one often finds captions, in -particular with small figures, which are placed beside the figure. In -general in this case both the baseline of the figure and of the -caption are aligned at the bottom. With some fiddling and the use of -two \Macro{parbox} commands this could also be achieved in the -standard classes. However, {\KOMAScript} offers a special environment -for this which can be used within the floating environment. The first -optional parameter \PName{entry} and the obligatory parameter -\PName{title} mean the same as the corresponding parameters of -\DescRef{\LabelBase.cmd.caption}, \DescRef{\LabelBase.cmd.captionabove} or \DescRef{\LabelBase.cmd.captionbelow}. The -caption text \PName{title} is placed beside the content of the -environment in this case. - -Whether the caption text \PName{title} is placed on the left or the -right can be determined by the parameter \PName{placement}. Exactly +In addition\ChangedAt{v2.8q}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} to captions above and below the figure, you will often +find captions, in particular for small figures, which are placed beside the +figure. The bottom edge of the caption is normally aligned with the bottom of +the figure. Of course, you can achieve the same thing in the standard classes +with some fiddling and the use of two \Macro{parbox} commands. However, +\KOMAScript{} offers a special environment for this which you can use within +the floating environments. The first optional parameter, +\PName{short title}\important{\PName{short title}\\\PName{caption text}}, and +the required parameter \PName{caption text} have the same meaning as the +corresponding parameters of \DescRef{\LabelBase.cmd.caption}, +\DescRef{\LabelBase.cmd.captionabove} or +\DescRef{\LabelBase.cmd.captionbelow}. The \PName{caption text} is +placed beside the content of the environment in this case. + +The \PName{placement}\important{\PName{placement}} parameter can determine +whether the \PName{caption text} is placed on the left or the right. Exactly one of the following letters is allowed: -\begin{labeling}[~--]{\quad\PValue{o}}\setlength{\itemsep}{0pt}% -\item[\PValue{l}] left -\item[\PValue{r}] right -\item[\PValue{i}] inner margin in two-sided layout -\item[\PValue{o}] outer margin in two-sided layout +\begin{labeling}[~--]{\quad\PValue{o}}\setlength{\itemsep}{-1\parsep plus 1ex}% + \item[\PValue{l}] left + \item[\PValue{r}] right + \item[\PValue{i}] inner margin in two-sided printing + \item[\PValue{o}] outer margin in two-sided printing \end{labeling} -Default setting is to the right of the content of the environment. This -default\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} my be changed using option -\DescRef{\LabelBase.option.captions}\IndexOption{captions}\important{\DescRef{\LabelBase.option.captions}} (see +The default placement is to the right of the content of the environment. You +can change this default\ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} using the +\DescRef{\LabelBase.option.captions}\IndexOption{captions}% +\important{\DescRef{\LabelBase.option.captions}} option (see \DescPageRef{\LabelBase.option.captions}) with values like -\PValue{innerbeside}\IndexOption[indexmain]{captions~=\PValue{innerbeside}}, -\PValue{leftbeside}\IndexOption[indexmain]{captions~=\PValue{leftbeside}}, -\PValue{outerbeside}\IndexOption[indexmain]{captions~=\PValue{outerbeside}}, +\PValue{innerbeside}\IndexOption[indexmain]{captions~=\textKValue{innerbeside}}, +\PValue{leftbeside}\IndexOption[indexmain]{captions~=\textKValue{leftbeside}}, +\PValue{outerbeside}\IndexOption[indexmain]{captions~=\textKValue{outerbeside}}, and -\PValue{rightbeside}\IndexOption[indexmain]{captions~=\PValue{rightbeside}}. +\PValue{rightbeside}\IndexOption[indexmain]{captions~=\textKValue{rightbeside}}. If either \PValue{o} or \PValue{i} are used you may need to run {\LaTeX} twice to obtain the correct placement. -Per default the content of the environment and the caption text -\PName{title} fill the entire available text width. However, using the -optional parameter \PName{width}, it is possible to adjust the width -used. This width could even be larger than the current text width. - -When supplying a \PName{width} the used width is usually centered with -respect to the text width. Using the optional parameter -\PName{offset}, you can shift the environment relative to the left -margin. A positive value corresponds to a shift to the right, whereas -a negative value corresponds to a shift to the left. An \PName{offset} -of 0\Unit{pt} gives you a left-aligned output. - -Adding a star to the optional parameter \PName{offset} makes the the -value mean a shift relative to the right margin on left hand pages in -two-sided layout. A positive value corresponds to a shift towards the -outer margin, whereas a negative value corresponds to a shift towards -the inner margin. An \PName{offset} of 0\Unit{pt} means alignment with -the inner margin. As mentioned before, in some cases it takes two -{\LaTeX} runs for this to work correctly. +Normally\important{\PName{width}}, the content of the environment and the +\PName{caption text} fill the entire available text width. However, you can +specify a different width using the optional parameter \PName{width}. This can +be greater than the current text width. + +When specifying a \PName{width}\important{\PName{width}\\\PName{offset}}, the +width used is usually centred with respect to the body text. Using the +optional parameter \PName{offset}, you can shift the environment relative to +the left margin. A positive value corresponds to a shift to the right, whereas +a negative value corresponds to a shift to the left. An \PName{offset} of +0\Unit{pt} gives you a left-aligned output. + +If\important{\PValue{*}} you add a star to the optional \PName{offset} +parameter, the value represents a shift relative to the right margin on +left-hand pages in a two-sided layout. A positive value corresponds to a shift +towards the outer margin, whereas a negative value corresponds to a shift +towards the inner margin. An \PName{offset} of 0\Unit{pt} means alignment with +the inner margin. This variant may require two {\LaTeX} runs to achieve the +correct offset. The default vertical alignment is bottom. This means that the bottommost base -lines of the contents of the environment and of the caption are aligned. This -setting\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} may be changed using option -\DescRef{\LabelBase.option.captions}\IndexOption{captions} (see -\DescPageRef{\LabelBase.option.captions}) with value -\PValue{topbeside}\IndexOption[indexmain]{captions~=\PValue{topbeside}}, +lines of the contents of the environment and of the caption are aligned. +You\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} can change this setting using the +\DescRef{\LabelBase.option.captions}\IndexOption{captions}% +\important{\DescRef{\LabelBase.option.captions}} option (see +\DescPageRef{\LabelBase.option.captions}) with the value +\PValue{topbeside}\IndexOption[indexmain]{captions~=\textKValue{topbeside}}, \PValue{centeredbeside}% -\IndexOption[indexmain]{captions~=\PValue{centeredbeside}}, or -\PValue{bottombeside}\IndexOption[indexmain]{captions~=\PValue{bottombeside}}. With -setting \PValue{topbeside} the topmost base lines of the environment contents -and caption will be aligned. With \PValue{centeredbeside} they will be -centered vertically. In this context it should be known, that the base line of -a pictures is mostly at the bottom of the picture. This may be changed, -e.\,g., using \Macro{raisebox}\IndexCmd{raisebox}. +\IndexOption[indexmain]{captions~=\textKValue{centeredbeside}}, or +\PValue{bottombeside}% +\IndexOption[indexmain]{captions~=\textKValue{bottombeside}}. +With the setting \PValue{topbeside}, the topmost base lines of the environment +contents and caption will be aligned. With \PValue{centeredbeside}, they will +be centred vertically. In this context, note that the base line of a figure is +usually the bottom of the figure. You can change this using, for example, +\Macro{raisebox}\IndexCmd{raisebox}. \begin{Example} - An example for the usage of the \Environment{captionbeside} environment - can be found in \autoref{fig:\LabelBase.captionbeside}. - This figure was typeset with: + You can find an example using the \Environment{captionbeside} environment in + \autoref{fig:\LabelBase.captionbeside}. This figure was typeset with: \begin{lstcode} \begin{figure} \begin{captionbeside}[Example: Figure beside description]% @@ -3161,30 +3528,35 @@ e.\,g., using \Macro{raisebox}\IndexCmd{raisebox}. \end{captionbeside} \label{fig:\LabelBase.captionbeside} \end{figure} - The total width is thus the currently available width + The total width is thus the currently available width of \PValue{\Macro{linewidth}}. However, this width is shifted - $\Length{marginparwidth} - + \Length{marginparsep}$ to the outside. The caption text or description is - placed on the inner side beside the figure. The figure itself is - shifted 2\Unit{em} into the outer margin. + $\Length{marginparwidth} + \Length{marginparsep}$ to the outside. The + caption text or description is placed on the inner side beside the figure. + The figure itself is shifted 2\Unit{em} into the outer margin. - With \Macro{dimexp} a \eTeX{} command has been used. This should not be a - problem at all, because \KOMAScript{} itself needs \eTeX{} and every almost +\iffalse% Umbruchkorrekturtext + The \Macro{dimexp} macro is an \eTeX{} command. This should not be a + problem at all because \KOMAScript{} itself requires \eTeX{} and every almost up-to-date \LaTeX{} distribution uses \eTeX already. +\fi \hyperref[fig:\LabelBase.captionbesidecentered]% {Figure~\ref*{fig:\LabelBase.captionbesidecentered}} - shows a centered caption with: + shows a centred caption with: \begin{lstcode} \KOMAoption{captions}{centeredbeside} \end{lstcode} - Even if you are not a typographer you may see, that this is not a - recommended suggestion. +\iffalse % Umbruchalternativen + Even a typographical novice will immediately realize that you should + usually avoid this alignment. +\else + This is certainly not a recommended solution. +\fi \begin{figure} \begin{captionbeside}[Example: Description centered beside figure]% {A figure description which is neither above nor - below, but centered beside the figure}[i][\linewidth][2em]* + below, but centred beside the figure}[i][\linewidth][2em]* \fbox{% \parbox[b][5\baselineskip][c]{.25\textwidth}{% \hspace*{\fill}\KOMAScript\hspace*{\fill}\par}} @@ -3192,9 +3564,11 @@ e.\,g., using \Macro{raisebox}\IndexCmd{raisebox}. \label{fig:\LabelBase.captionbesidecentered} \end{figure} - In opposite to the centered example, the top aligned from - \autoref{fig:\LabelBase.captionbesidetop} may be used. To show how to change - the baseline using \Macro{raisebox}, the complete example code follows: + In contrast, you can use the top-aligned format seen in + \autoref{fig:\LabelBase.captionbesidetop}. To illustrate how to shift the + baseline using \Macro{raisebox}, here is a complete example. You can apply + this not only to a substitute figure, as previously shown, but also, for + example, to \Macro{includegraphics} (see \cite{package:graphics}). \begin{lstcode} \documentclass[captions=topbeside]{scrbook} \usepackage[english]{babel} @@ -3233,55 +3607,61 @@ e.\,g., using \Macro{raisebox}\IndexCmd{raisebox}. \end{captionbeside} \label{fig:\LabelBase.captionbesidetop} \end{figure} - You may use such a movement not only at graphics replacements like show, but - also using \Macro{includegraphics} (see \cite{package:graphics}). \end{Example} % \EndIndexGroup \begin{Declaration} - \begin{Environment}{captionofbeside}% - \Parameter{float type}% - \OParameter{entry}\Parameter{title}% - \OParameter{placement}\OParameter{width}% - \OParameter{offset} + \begin{Environment}{captionofbeside} + \Parameter{float type} + \OParameter{short title} + \Parameter{caption text} + \OParameter{placement} + \OParameter{width} + \OParameter{offset} + \begin{Body}\BodyDots\end{Body} \end{Environment} \labelsuffix[*]% - \begin{Environment}{captionofbeside}% - \Parameter{float type}% - \OParameter{entry}\Parameter{title}% - \OParameter{placement}\OParameter{width}% - \OParameter{offset}\PValue{*}% + \begin{Environment}{captionofbeside} + \Parameter{float type} + \OParameter{short title} + \Parameter{caption text} + \OParameter{placement} + \OParameter{width} + \OParameter{offset}\PValue{*}% + \begin{Body}\BodyDots\end{Body} \end{Environment} \end{Declaration} -This\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} environment corresponds to -\DescRef{\LabelBase.env.captionbeside} in the same manner like -\Macro{captionof} corresponds to \DescRef{\LabelBase.cmd.caption}. The float -type is not defined by a floating environment but by the first mandatory -argument.% +As\ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} is the case for \DescRef{\LabelBase.cmd.caption}, there is +a variant for \DescRef{\LabelBase.cmd.captionof} where the \PName{float type} +is not defined by using it within a floating environment of this type, so you +can specify a suitable environment for \DescRef{\LabelBase.env.captionbeside} +with \Environment{captionofbeside}. In contrast to +\DescRef{\LabelBase.env.captionbeside}, the \PName{float type} must be +specified as an additional, first argument.% % \EndIndexGroup - \begin{Declaration} \FloatStyle{komaabove}% \FloatStyle{komabelow} \end{Declaration}% If you use\OnlyAt{\Package{float}} the \Package{float}\IndexPackage{float} -package the appearance of the float environments is solely defined by the -\emph{float} style. This includes whether captions above or below are used. In -the \Package{float} package there is no predefined style which gives you the -same output and offers the same setting options (see below) as {\KOMAScript}. -Therefore {\KOMAScript} defines the two additional styles \PValue{komaabove} -and \PValue{komabelow}. When using the \Package{float} package these styles -can be activated just like the styles \PValue{plain}\IndexFloatstyle{plain}, -\PValue{boxed}\IndexFloatstyle{boxed} or \PValue{ruled}\IndexFloatstyle{ruled} -defined in \Package{float}. For details refer to \cite{package:float}. The -style \PValue{komaabove} inserts \DescRef{\LabelBase.cmd.caption}, \DescRef{\LabelBase.cmd.captionabove} and -\DescRef{\LabelBase.cmd.captionbelow} above, whereas \PValue{komabelow} inserts them below the -float content. +package, the appearance of the float environments is solely defined by the +\emph{float} style. This includes whether captions appear above or below. In +the \Package{float} package, there is no predefined style which gives you the +same output and offers the same setting options (see below) as \KOMAScript{}. +Therefore \KOMAScript{} defines the two additional styles, \PValue{komaabove} +and \PValue{komabelow}. When using the \Package{float} package, you can +activate these styles just like the styles +\PValue{plain}\IndexFloatstyle{plain}, \PValue{boxed}\IndexFloatstyle{boxed}, +or \PValue{ruled}\IndexFloatstyle{ruled} defined in \Package{float}. For +details refer to \cite{package:float}. The style \PValue{komaabove} inserts +\DescRef{\LabelBase.cmd.caption}, \DescRef{\LabelBase.cmd.captionabove}, and +\DescRef{\LabelBase.cmd.captionbelow} above, whereas \PValue{komabelow} +inserts them below the float content. % \EndIndexGroup @@ -3289,21 +3669,20 @@ float content. \begin{Declaration} \Macro{captionformat} \end{Declaration}% -In {\KOMAScript} there are different ways to change the formatting of -the caption text. The definition of different font styles was already -explained above. This or the caption delimiter between the label and -the label text itself is specified in the macro \Macro{captionformat}. -In contrast to all other \Macro{\dots}format commands, in this case it -does not contain the counter but only the items which follow it. The -original definition is: +In {\KOMAScript} there are various ways to change the formatting of +the caption text. The definition of different font styles has already +been explained above. The delimiter or delimiters between the label and +actual caption text is specified by the macro \Macro{captionformat}. +In contrast to all other \Macro{\dots}format commands, this is not the counter +but only the items which follow it. The original definition is: \begin{lstcode} \newcommand*{\captionformat}{:\ } \end{lstcode} -This too can be changed with \Macro{renewcommand}. +You can change this too with \Macro{renewcommand}. \begin{Example} - For some inexplicable reasons you want a dash with spaces before and - after instead of a colon followed by a space as label delimiter. You - define: + For some inexplicable reason, you want a dash surrounded by spaces + instead of a colon followed by a space as a label delimiter. You + therefore define: \begin{lstcode} \renewcommand*{\captionformat}{~--~} \end{lstcode} @@ -3317,33 +3696,30 @@ This definition should be put in the preamble of your document. \Macro{figureformat}% \Macro{tableformat} \end{Declaration}% -It was already mentioned that \DescRef{\LabelBase.cmd.captionformat} does not -contain formatting for the label itself. This situation should under no -circumstances be changed using redefinitions of the commands for the output of -counters, \Macro{thefigure} or \Macro{thetable}. Such a redefinition would -have unwanted side effects on the output of \Macro{ref} or the table of -contents, list of figures and list of tables. To deal with the situation, -{\KOMAScript} offers two \Macro{\dots format} commands instead. These are -predefined as follows: -% Umbruchkorrektur: listings +It has already been mentioned that \DescRef{\LabelBase.cmd.captionformat} does +not contain formatting for the label itself. You should not alter this by +redefining the commands for the output of the \Macro{thefigure} or +\Macro{thetable} counters. Such a redefinition would have unwanted side +effects on the output of \Macro{ref}, the table of contents, the list of +figures, and the list of tables. Instead, {\KOMAScript} offers two +\Macro{\dots format} commands. These have the following defaults: \begin{lstcode} \newcommand*{\figureformat}{\figurename~\thefigure\autodot} \newcommand*{\tableformat}{\tablename~\thetable\autodot} \end{lstcode} -They also can be adapted to your personal preferences with -\Macro{renewcommand}. +They can also be customised to your requirements with \Macro{renewcommand}. \begin{Example} - From time to time captions without any label and of course without - delimiter are desired. In {\KOMAScript} it takes only the following - definitions to achieve this: + From time to time, it is required to have captions without labels or + delimiters. With {\KOMAScript} the following definitions suffice to + achieve this: \begin{lstcode} \renewcommand*{\figureformat}{} \renewcommand*{\tableformat}{} \renewcommand*{\captionformat}{} \end{lstcode} It should be noted, however, that although no numbering is output, the - internal counters are nevertheless incremented. This becomes important - especially if this redefinition is applied only to selected + internal counters are nevertheless incremented. This becomes especially + important if this redefinition is applied only to selected \Environment{figure} or \Environment{table} environments. \end{Example} % @@ -3355,52 +3731,50 @@ They also can be adapted to your personal preferences with \Macro{setcapindent*}\Parameter{xindent}% \Macro{setcaphanging} \end{Declaration}% -As mentioned previously, in the standard classes the captions are set -in a non-hanging style, that is, in multi-line captions the second and -subsequent lines start directly beneath the label. The standard -classes provide no direct mechanism to change this behaviour. In -{\KOMAScript}, on the contrary, beginning at the second line all lines -are indented by the width of the label so that the caption text is -aligned. - -This behaviour, which corresponds to the usage of \Macro{setcaphanging}, can -easily be changed by using the command \Macro{setcapindent} or -\Macro{setcapindent*}. Here the parameter \PName{indent} determines the -indentation of the second and subsequent lines. If you want a line break after -the label and before the caption text, then you can define the indentation -\PName{xindent} of the caption text with the starred version of the command -instead: \Macro{setcapindent*}. -Using a negative value of \PName{indent} instead, a line break is also -inserted before the caption text and only the first line of the -caption text but not subsequent lines are indented by -the absolute value of \PName{indent}. - -Whether one-line captions are set as captions with more than one line or are +As mentioned previously, in the standard classes the captions are set in a +non-hanging style. In other words, in multi-line captions the second and +subsequent lines start directly beneath the label. The standard classes +provide no direct mechanism to change this behaviour. In {\KOMAScript}, on the +contrary, beginning at the second line all lines are indented by the width of +the label so that the caption text is aligned. + +You can change this behaviour, which corresponds to using +\Macro{setcaphanging}, at any time with the \Macro{setcapindent} or +\Macro{setcapindent*} command. Here the parameter \PName{indent} determines +the indentation of the second and subsequent lines. If you want a line break +after the label and before the caption text, then you can define the +indentation \PName{xindent} of the caption text with the starred version of +the command instead: \Macro{setcapindent*}. + +A negative value of \PName{indent}, on the other hand, results in a line break +before the caption text, and only the first line of the caption text, not +subsequent lines, is indented by the absolute value of \PName{indent}. + +Whether one-line captions are set the same way as multi-line captions or are treated separately is specified with the option \DescRef{\LabelBase.option.captions}. For details please refer to the -explanations of these option at +explanations of these option on \DescPageRef{\LabelBase.option.captions.oneline}. \begin{Example} - For the examples please refer to - figures~\ref{fig:\LabelBase.caption.first} to - \ref{fig:\LabelBase.caption.last}. As you can see the usage of a fully - hanging indentation is not advantageous when combined with narrow - column width. To illustrate, the source code for the second figure - is given here with a modified caption text: + The illustrations~\ref{fig:\LabelBase.caption.first} to + \ref{fig:\LabelBase.caption.last} show the effects of different settings. As + you can see, using a fully hanging indentation with a narrow column width is + awkward. To illustrate, the source code for the second figure is given here + with a modified caption text: \begin{lstcode} \begin{figure} \setcapindent{1em} \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} - \caption{Example with slightly indented caption - starting at the second line} + \caption{Example with partially indented caption + starting from the second line} \end{figure} \end{lstcode} -As can be seen the formatting can also be changed locally within the -\Environment{figure} environment\IndexEnv{figure}. The change then -affects only the current figure. Following figures once again use the -default settings or global settings set, for example, in the preamble -of the document. This also of course applies to tables. + As you can see, the formatting can also be changed locally within the + \Environment{figure} environment\IndexEnv{figure}. The change then affects + only the current figure. Subsequent figures once again use the default + settings or global settings that you set, for example, in the preamble. This + also, of course, applies to tables. \begin{figure} \typeout{^^J--- Ignore underfull and overfull \string\hbox:} \addtokomafont{caption}{\small} @@ -3409,18 +3783,18 @@ of the document. This also of course applies to tables. \begin{minipage}{.9\linewidth} \begin{minipage}[t]{.48\linewidth}\sloppy \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} - \caption[Example: Default figure caption]% - {\sloppy Equivalent to the standard setting, similar to the - usage of \Macro{setcaphanging}} + \caption[Example: Default caption]% + {\sloppy With the default setting, like using + \Macro{setcaphanging}} \label{fig:\LabelBase.caption.first} \end{minipage} \hspace{.02\linewidth} \begin{minipage}[t]{.48\linewidth}\sloppy \setcapindent{1em} \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} - \caption[Example: Figure caption with slightly hanging indention]% - {With slightly hanging indentation starting at the second line - using \Macro{setcapindent}\PParameter{1em}} + \caption[Example: Caption with partially hanging indention]% + {With partially hanging indentation starting from the second line + by using \Macro{setcapindent}\PParameter{1em}} \end{minipage} \end{minipage} @@ -3429,9 +3803,8 @@ of the document. This also of course applies to tables. \begin{minipage}[t]{.48\linewidth}\sloppy \setcapindent*{1em} \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} - \caption[Example: Figure caption with hanging indention and line - break]% - {With hanging indentation starting at the second line and line + \caption[Example: Caption with hanging indention and line break]% + {With hanging indentation starting from the second line and line break before the description using \Macro{setcapindent*}\PParameter{1em}} \end{minipage} @@ -3439,9 +3812,8 @@ of the document. This also of course applies to tables. \begin{minipage}[t]{.48\linewidth}\sloppy \setcapindent{-1em} \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} - \caption[Example: Figure caption with hanging indention at the second - line]% - {With indentation in the second line only and line break + \caption[Example: Caption with indention in the second line]% + {With indentation only in the second line and a line break before the description using \Macro{setcapindent}\PParameter{-1em}} \label{fig:\LabelBase.caption.last} @@ -3458,263 +3830,410 @@ of the document. This also of course applies to tables. \begin{Declaration} \Macro{setcapwidth}\OParameter{justification}\Parameter{width}% \Macro{setcapdynwidth}\OParameter{justification}\Parameter{width}% - \Macro{setcapmargin}\OParameter{margin left}\Parameter{margin}% - \Macro{setcapmargin*}\OParameter{margin inside}\Parameter{margin} + \Macro{setcapmargin}\OParameter{left margin}\Parameter{margin}% + \Macro{setcapmargin*}\OParameter{inside margin}\Parameter{margin} \end{Declaration} Using\ChangedAt{v2.8q}{% \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} these three -commands you can specify the width and justification of the caption -text. In general the whole text width or column width is available -for the caption. +commands, you can specify the width and justification of the caption +text. Normally, the entire text or column width is available for the caption. -With\important{\Macro{setcapwidth}} the command \Macro{setcapwidth} you can -decrease this \PName{width}. The obligatory argument determines the maximum -\PName{width} of the caption. As an optional argument you can supply exactly +With\important{\Macro{setcapwidth}} the \Macro{setcapwidth} command, you can +decrease this \PName{width}. The mandatory argument determines the maximum +\PName{width} of the caption. As an optional argument, you can supply exactly one letter which specifies the horizontal justification. The possible -justifications are given in the following list. -\begin{labeling}[~--]{\quad\PValue{o}}\rightskip=1em -\item[\PValue{l}] left-aligned -\item[\PValue{c}] centered +justifications are given in the following list: +\begin{labeling}[~--]{\quad\PValue{o}}% + \itemsep=.5\topsep plus .5\topsep minus .5\topsep + \rightskip=1em +\item[\PValue{l}] left-justified +\item[\PValue{c}] centred \item[\PValue{r}] right-aligned -\item[\PValue{i}] alignment at the inner margin in double-sided output -\item[\PValue{o}] alignment at the outer margin in double-sided output +\item[\PValue{i}] aligned to the inner margin in two-sided printing +\item[\PValue{o}] aligned to the outer margin in two-sided printing \end{labeling} -The justification inside and outside corresponds to left-aligned and -right-aligned, respectively, in single-sided -output. Within\textnote{Attention!} -\Package{longtable}\IndexPackage{longtable}% -\important{\Package{longtable}} tables the justification inside or outside -does not work correctly. In particular, the captions on subsequent pages of -such tables are aligned according to the format of the caption on the first -page of the table. This is a conceptual problem in the implementation of -\Package{longtable}. - -Please\ChangedAt{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}}\textnote{Attention!} note, \Macro{setcapwidth} sets the -width immediately to the value of parameter \PName{width} like -\Macro{setlength} would do. If you instead want the value of \PName{width} -when the caption is set, you can use \Macro{setcapdynwidth}. There can be -differences in the result, if you, e.\,g., use lengths like \Length{linewidth} -or other commands as argument \PName{width}. - -With\important{\Macro{setcapmargin}} the command \Macro{setcapmargin} you can -specify a \PName{margin} which is to be left free next to the description in -addition to the normal text margin. If you want margins with different widths -at the left and right side you can specify these using the optional argument -\PName{margin left}. The starred version \Macro{setcapmargin*} defines instead -of a \PName{margin left} a \PName{margin inside} in a double-sided layout. In -case of \Package{longtable}\IndexPackage{longtable}% -\important{\Package{longtable}} tables you have to deal with the same problem -with justification inside or outside as mentioned with the macro -\Macro{setcapwidth}. Furthermore, the usage of \Macro{setcapmargin} or -\Macro{setcapmargin*} switches on the option -\OptionValueRef{\LabelBase}{captions}{nooneline} (see -\DescPageRef{\LabelBase.option.captions.nooneline}) for the captions which are +Inside and outside justification corresponds to left-aligned and right-aligned +justification, respectively, in one-sided printing. +Within\textnote{Attention!} \Package{longtable}\IndexPackage{longtable}% +\important{\Package{longtable}} tables, inside and outside justification does +not work correctly. In particular, the captions on subsequent pages of such +tables are aligned according to the format of the caption on the first page of +the table. This is a conceptual problem in the implementation of the +\Package{longtable} package. + +Note\ChangedAt{v3.20}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\textnote{Attention!} that \Macro{setcapwidth} immediately +sets the width to the value of the \PName{width} parameter at the time of the +assignment, as \Macro{setlength} does. If\important{\Macro{setcapdynwidth}} +you instead want to use the current value of \PName{width} when the caption is +set, you should use \Macro{setcapdynwidth}. There can be significant +differences in the result if, for example, you use lengths like +\Length{linewidth} or other commands as \PName{width} arguments. + +With\important{\Macro{setcapmargin}} the \Macro{setcapmargin} command, instead +of specifying the width of the caption text, you can specify a \PName{margin} +to be set next to the caption text in addition to the normal text margin. If +you want margins with different widths on the left and right sides, you can +use the optional argument to specify a \PName{left margin} that differs from +\PName{margin}. Instead of a \PName{left margin}, the starred version +\Macro{setcapmargin*} defines an \PName{inside margin} in a two-sided layout. +The same problem arises here with with inside and outside justification inside +\Package{longtable}\IndexPackage{longtable}\important{\Package{longtable}} +tables that occurs with \Macro{setcapwidth}. Furthermore, using +\Macro{setcapmargin} or \Macro{setcapmargin*} activates the +\OptionValueRef{\LabelBase}{captions}{nooneline} option (see +\DescPageRef{\LabelBase.option.captions.nooneline}) for captions which are typeset with this margin setting. -You\textnote{Hint!} can also submit negative values for \PName{margin} and -\PName{margin left} or \PName{margin inside}. This has the effect of the -caption expanding into the margin. - -Experts\textnote{Hint!} and advanced users may find a tricky usage of -\Macro{setcapwidth} in +You\textnote{Hint!} can also specify negative values for \PName{margin} and +\PName{left margin} or \PName{inside margin}. This has the effect of making +the caption protrude into the margin.% +\iffalse\par% Anhang wurde entfernt. +Experts\textnote{Hint!} and advanced users can find a a somewhat tricky +application of \Macro{setcapwidth} in \iffree{\cite{book:komascript}}{\autoref{cha:floattricks}, \autopageref{cha:floattricks}}.% +\fi% % \EndIndexGroup +\begin{Declaration} + \Macro{setcaptionalignment}\OParameter{float type}\Parameter{alignment} +\end{Declaration} +Normally\ChangedAt{v3.25}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}, multi-line\textnote{alignment of multi-line captions} +captions are fully justified. This corresponds to +\Macro{setcaptionalignment}\PParameter{j}. Sometimes, however, you want a +different alignment, for example ragged right. An appropriate change is +possible at any time with \Macro{setcaptionalignment}. You can specify exactly +one of the letters listed in \autoref{tab:maincls.captionalignment} for the +\PName{alignment}. If you specify an unknown \PName{alignment}, you will +receive an error message. +% +\begin{table} +% \centering + \KOMAoptions{captions=topbeside}% + \setcapindent{0pt}% + \begin{captionbeside} + [{Alignments for multi-line captions of floating environments}] + {\label{tab:maincls.captionalignment}% + Alignments for multi-line captions of floating environments} + [l] + \begin{tabular}[t]{ll} + \toprule + c & centred \\ + j & fully justified \\ + l & left justified \\ + r & right justified \\ + C & centred with \Package{ragged2e} \\ + J & fully justified with \Package{ragged2e} \\ + L & left justified with \Package{ragged2e} \\ + R & right justified with \Package{ragged2e} \\ + \bottomrule + \end{tabular} + \end{captionbeside} +\end{table} + +The four possibilities with the +\Package{ragged2e}\important{\Package{ragged2e}}\IndexPackage{ragged2e} +package are only available if that package was loaded before you use +\Macro{setcaptionalignment}. Otherwise, they are converted to the +corresponding options without \Package{ragged2e}. For safety reasons, a +warning is issued in this case. + +When using this command without\textnote{without optional parameter} the +optional parameter, the result depends on whether the call occurs inside our +outside of a floating environment. Within a floating environment, the +alignment is then set for this floating environment. Outside, on the other +hand, the optional parameter is assumed to be empty. + +Using this command with an empty\textnote{empty optional parameter} optional +parameter, or outside a floating environment and also without any optional +parameter, sets the general alignment. This is used whenever the current +floating environment type does not define an alignment. + +If you only want to set the alignment of a particular type of floating +environment\textnote{with \PName{float type}} without changing the +\PName{alignment} for other types of floating environments, then the type of +floating environment, e.\,g., \PValue{figure} or \PValue{table}, is given as +the optional parameter \PName{float type}. +% +\begin{Example} + You want captions to be centred under the images even if they are + multi-line. To text this for a single image, use\textnote{in the + floating environment}: +\begin{lstcode} + \begin{figure} + \centering + \setcaptionalignment{c} + \includegraphics{example-image} + \caption{\blindtext} + \end{figure} +\end{lstcode} + Since you are satisfied with the result, you move the\textnote{in the + preamble} +\begin{lstcode} + \setcaptionalignment{c} +\end{lstcode} + command to the document preamble. Thereafter, however, you decide you do not + like this change for table captions at all. Therefore, you use\textnote{only + for figures} +\begin{lstcode} + \setcaptionalignment[figure]{c} +\end{lstcode} + to limit the centring to figures. + + A little later, you realize that the centring is not so suitable. Instead, + you now prefer to have ragged right alignment. So you change the alignment + again: +\begin{lstcode} + \setcaptionalignment[figure]{l} +\end{lstcode} + However, you do not like the fact that the lines are very different in + length. This is caused by the lack of hyphenation, causing long words to + wrap completely onto the next line, leaving large gaps. You want to allow + hyphenation as needed. This is easy to achieve with the help of the + \Package{ragged2e}\important{\Package{ragged2e}}\IndexPackage{ragged2e} + package. However, it is not enough to use +\begin{lstcode} + \usepackage{ragged2e} +\end{lstcode} + to load the package. Using the \Option{newcommands} option when loading the + package does not help. Instead, the \PName{alignment} must also be changed: +\begin{lstcode} + \usepackage{ragged2e} + \setcaptionalignment[figure]{L} +\end{lstcode} + Note\textnote{Attention!} the upper-case letter for the \PName{alignment}. +\end{Example} +\EndIndexGroup + \begin{Declaration} \Option{origlongtable} \end{Declaration}% \BeginIndex{Package}{longtable}% -If the table captions produced by the \Package{longtable} package (see -\cite{package:longtable}) should not be redefined by the {\KOMAScript} +If you do not want the table captions produced by the \Package{longtable} +package (see \cite{package:longtable}) to be redefined by the {\KOMAScript} classes, activate the \Option{origlongtable} option. This\textnote{Attention!} -option has to be used at the optional argument of -\DescRef{\LabelBase.cmd.documentclass}. It may not be used as a setting of +option must be used in the optional argument of +\DescRef{\LabelBase.cmd.documentclass}. It cannot be used as a setting of \DescRef{\LabelBase.cmd.KOMAoptions} or \DescRef{\LabelBase.cmd.KOMAoptions}. % \EndIndexGroup +% +\EndIndexGroup \begin{Declaration} \OptionVName{listof}{setting} \end{Declaration} -\BeginIndex{}{tables>list of}\BeginIndex{}{list of>tables}% -\BeginIndex{}{figures>list of}\BeginIndex{}{list of>figures}% Normally\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} lists of floating environments\,---\,like list of tables -or list of figures will neither get an entry at the table of contents nor have -a number at the heading. More information about that may be found in -\autoref{sec:\LabelBase.toc}. Alternative to the view from the table of -contents to the lists of floating environments, you may reconsider a view from -the lists of floating environments into the table of contents. Because of -this, there are not only the options -\OptionValueRef{\LabelBase}{toc}{nolistof}% -\IndexOption{toc~=\PValue{nolistof}}, -\OptionValueRef{\LabelBase}{toc}{listof}\IndexOption{toc~=\PValue{listof}}, + \Class{scrartcl}} lists of floating environments\,---\,like +tables\Index{tables>list of} or figures\Index{figures>list of}\,---\,are +neither numbered nor included in the table of contents. You can find more +information about this behaviour in \autoref{sec:\LabelBase.toc}. As an +alternative to the settings \OptionValueRef{\LabelBase}{toc}{nolistof}% +\IndexOption{toc~=\textKValue{nolistof}}, +\OptionValueRef{\LabelBase}{toc}{listof}\IndexOption{toc~=\textKValue{listof}}, and \OptionValueRef{\LabelBase}{toc}{listofnumbered}% -\IndexOption{toc~=\PValue{listofnumbered}} described in -\autoref{sec:\LabelBase.toc}, \DescPageRef{\LabelBase.option.toc.listof}, but -also \OptionValue{listof}{notoc}, \OptionValue{listof}{totoc}, and -\OptionValue{listof}{numbered} with the same meaning. - -By default the headings of the lists of floating environments use the topmost -level below \DescRef{\LabelBase.cmd.part}. This is the chapter level at -\Class{scrbook} and \Class{scrreprt} and the section level at -\Class{scrartcl}. With\ChangedAt{v3.06}{\Class{scrbook}\and +\IndexOption{toc~=\textKValue{listofnumbered}} mentioned there, you can also +look at this behaviour from perspective of the lists themselves. Therefore +you can achieve the same results with the settings +\OptionValue{listof}{notoc}, \OptionValue{listof}{totoc}, and +\OptionValue{listof}{numbered}. + +By default, the headings in the lists of floating environments use the topmost +level below \DescRef{\LabelBase.cmd.part}. This is the chapter level in +\Class{scrbook} and \Class{scrreprt} and the section level in +\Class{scrartcl}. By contrast,\ChangedAt{v3.06}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -\OptionValue{listof}{leveldown}\important{\OptionValue{listof}{leveldown}} a -one step lower level will be used instead. +\OptionValue{listof}{leveldown}\important{\OptionValue{listof}{leveldown}} +uses the next lower level to be used instead. +\important{\OptionValue{listof}{standardlevel}}% +\ChangedAt{v3.15}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% +\OptionValue{listof}{standardlevel} switches back to the default sectioning +level, if necessary. \begin{Example} - At a book you want to move the list of figures and the list of tables as - sub-lists into a common list named ``Figures and Tables''. With + In a book, you want to put the list of figures and the list of tables as + sub-lists into a common list named ``Figures and Tables''. Simply use: \begin{lstcode} \KOMAoption{listof}{leveldown} \end{lstcode} - you first declare to use the section instead of the chapter level for both - lists and then you use: + to use the section instead of the chapter level for both lists, and put the + following at the appropriate place in your document: \begin{lstcode} \addchap*{Figures and Tables} \listoffigures \listoftables \end{lstcode} - for the new list, that contains the list of figures and the list of - tables. More information about the command \DescRef{\LabelBase.cmd.addchap*} - may be found in \autoref{sec:\LabelBase.structure} at + You can find more information about the \DescRef{\LabelBase.cmd.addchap*} + command in \autoref{sec:\LabelBase.structure} on \DescPageRef{\LabelBase.cmd.addchap*}. \end{Example} Normally\ChangedAt{v2.8q}{% \Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} the lists of -floating environments use a constant with to place the caption number of the -entries. Additionally all entries will be indented a little bit. This -corresponds to setting -\OptionValue{listof}{graduated}\IndexOption{listof~=\PValue{graduated}}. - -If the numbers of the figures or tables, become very wide\,---\,i.\,e., if you -have a lot of tables or figures\,---\, their may be not enough width -predefined. There's\important{\OptionValue{listof}{flat}} a setting -\OptionValue{listof}{flat}\IndexOption{listof~=\PValue{flat}} for the lists of -floating environment similar to -\OptionValueRef{\LabelBase}{toc}{flat}\IndexOption{toc~=\PValue{flat}} for the -table of contents. Thereby the needed with for printing the number will be -determined at each \LaTeX{} run. See option -\OptionValueRef{\LabelBase}{toc}{flat}, \autoref{sec:\LabelBase.toc}, -\DescPageRef{\LabelBase.option.toc.flat} for information about how it -works. Please\textnote{Attention!} note again, that you need more than one -\LaTeX{} runs until the lists of floating environments will become their final -result. - -Setting \OptionValue{listof}{entryprefix}\ChangedAt{v3.06}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} will automatically activate -\OptionValue{listof}{flat} -too. Normally\important{\OptionValue{listof}{entryprefix}} it would not make -sense to add the prefix ``figure'' to each entry of the list of figures and -the prefix ``table'' to each entry of the list of tables, because nothing else -than figures would be and should be expected at the list of figures and -nothing else than tables would be and should be expected at the list of -tables. So this prefixes would not give any additional information and for this -would not be useful. Nevertheless, such prefixes may be added using option -\OptionValue{listof}{entryprefix}. With this all entries of the same list will -get the same prefix. The prefix will depend on the file extension of the -helper file, that will be used for the corresponding list. For the list of -figures the file extension would be ``\File{lof}'' and therefor -\Macro{listoflofentryname} would be used. For the list of tables, the file -extension would be ``\File{lot}'' and \Macro{listoflotentryname} would be -used. - -Within classes \Class{scrbook} and \Class{scrreprt}\OnlyAt{\Class{scrbook}\and - \Class{scrreprt}} \KOMAScript{} adds a vertical gap to the lists of floating -environments whenever a new chapter starts. This behaviour, that is same at -the standard classes, structures the lists by chapters. At \KOMAScript{} it -corresponds to setting \ChangedAt{v3.00}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} +floating environments use a fixed-width space for the caption number of the +entries. At the same time, all entries are somewhat indented. This behaviour +corresponds to the +\OptionValue{listof}{graduated}\IndexOption{listof~=\textKValue{graduated}} +setting. + +If the numbers become very wide, for example because you have many tables or +figures, the space provided may at some point no longer be sufficient. +\KOMAScript{} offers the setting \OptionValue{listof}{flat}% +\important{\OptionValue{listof}{flat}}\IndexOption{listof~=\textKValue{flat}} +for lists of floating environments, comparable to +\OptionValueRef{\LabelBase}{toc}{flat}\IndexOption{toc~=\textKValue{flat}} for +the table of contents. The width required to print the number is +determined automatically and the space is adjusted accordingly. See the +\OptionValueRef{\LabelBase}{toc}{flat} option, \autoref{sec:\LabelBase.toc}, +\DescPageRef{\LabelBase.option.toc.flat} for more information about side +effects and how it works. Note\textnote{Attention!} again that you need more +than one \LaTeX{} run before the lists of floating environments reach +their final state. + +The \OptionValue{listof}{entryprefix}\ChangedAt{v3.06}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}} setting automatically activates +\OptionValue{listof}{flat} too. +Normally\important{\OptionValue{listof}{entryprefix}}, it does not make sense +to add a prefix such as ``figure'' or ``table'' to each entry in the lists of +floating environments because, of course, only figures are included in the +list of figures and only tables are included in the list of tables. Such a +prefix provides no additional information and is thus omitted by default. +However, you can add such prefixes using the +\OptionValue{listof}{entryprefix} option. With this, all entries in the same +list will get the same prefix. The prefix depends on the file extension of the +auxiliary file that is used for the corresponding list. For the list of +figures, the file extension is ``\File{lof}'' and therefore +\Macro{listoflofentryname} is used. For the list of tables, the file extension +is ``\File{lot}'' and \Macro{listoflotentryname} is used. + +For the \Class{scrbook} and \Class{scrreprt}\OnlyAt{\Class{scrbook}\and + \Class{scrreprt}} classes, \KOMAScript{} adds a vertical space to the lists +of floating environments whenever a new chapter starts. This behaviour, which +also exists in the standard classes, groups the lists by chapters. In +\KOMAScript{}, it corresponds to setting \ChangedAt{v3.00}{\Class{scrbook}\and + \Class{scrreprt}\and \Class{scrartcl}}% \OptionValue{listof}{chaptergapsmall}% -\IndexOption{listof~=\PValue{chaptergapsmall}}. In this case a gap of width -10\Unit{pt} will be used. With\important{\OptionValue{listof}{chaptergapline}} -option \OptionValue{listof}{chaptergapline}% -\IndexOption{listof~=\PValue{chaptergapline}} a gap of the height of one -standard text line will be -used. The\important{\OptionValue{listof}{nochaptergap}} gap may be switched of -with \OptionValue{listof}{nochaptergap}% -\IndexOption{listof~=\PValue{nochaptergap}}. Option\important{\OptionValue{listof}{chapterentry}} +\LabelOptionValue{listof}{chaptergapsmall}% +\important{\OptionValue{listof}{chaptergapsmall}}% +\IndexOption{listof~=\textKValue{chaptergapsmall}}. In this case, is uses a +fixed vertical space of 10\Unit{pt}. +With\important{\OptionValue{listof}{chaptergapline}} the +\OptionValue{listof}{chaptergapline}% +\IndexOption{listof~=\textKValue{chaptergapline}} option, you instead get a +vertical space the height of one standard text line. With +\OptionValue{listof}{nochaptergap}% +\IndexOption{listof~=\textKValue{nochaptergap}}% +\important{\OptionValue{listof}{nochaptergap}}, you can completely remove the +vertical space. The\important{\OptionValue{listof}{chapterentry}} \OptionValue{listof}{chapterentry}% -\IndexOption{listof~=\PValue{chapterentry}} is somehow special. Instead of a -gap it adds the table of contents entry for the chapter additionally to the -lists of floating environments. Please\textnote{Attention!} note, that this -would also happen, if the chapter does not have any floating -environment. Additional influence of chapters to the lists of floating -environments is available with option -\DescRef{\LabelBase.option.chapteratlists}. See -\autoref{sec:\LabelBase.structure}, -\DescPageRef{\LabelBase.option.chapteratlists} for more information about -that. - -An overview about all settings to option \Option{listof} may be found at +\IndexOption{listof~=\textKValue{chapterentry}} option is a special feature. +Instead of a vertical space, the table of contents entry for the chapter is +inserted into the lists of floating environments. Note\textnote{Attention!} +that this happens even if the chapter does not contain a floating environment. +You can find a method where only chapters containing floating environments +appear in the respective lists at \cite{https://komascript.de/comment/5070}. +You can achieve a more direct control over what appears in the lists of +floating environments with the \DescRef{\LabelBase.option.chapteratlists} +option, which is explained in \autoref{sec:\LabelBase.structure}, on +\DescPageRef{\LabelBase.option.chapteratlists}. + +You can find an overview of all settings for the \Option{listof} option in \autoref{tab:\LabelBase.listof}. \begin{desclist} - \desccaption[{Available values for option \Option{listof}}]{% - Available values for option \Option{listof} to modify contents and - formation of the lists of floating environments\label{tab:\LabelBase.listof}% + \desccaption[{Available values for the \Option{listof} option}]{% + Available values for the \Option{listof} option for modifying the format + and contents of the lists of floating + environments\label{tab:\LabelBase.listof}% }{% - Available values for option \Option{listof} (\emph{continuation})% + Available values for the \Option{listof} option (\emph{continued})% }% \entry{\PValue{chapterentry}, \PValue{withchapterentry}}{% - Marks chapter starts at the lists of floating environments by a copy of - their entries to the table of contents.% - \IndexOption{listof~=\PValue{chapterentry}}}% + Indicates the beginning of chapters in the lists of floating environments + with copies of their table-of-contents entries.% + \IndexOption{listof~=\textKValue{chapterentry}}}% \entry{\PValue{chaptergapline}, \PValue{onelinechaptergap}}{% - Marks chapter starts at the lists of floating environments by a vertical - gap of the height of one standard text line.% - \IndexOption{listof~=\PValue{chaptergapline}}}% + Indicates the beginning of chapters in the lists of floating environments + with a vertical space the height of one standard text line.% + \IndexOption{listof~=\textKValue{chaptergapline}}}% \entry{\PValue{chaptergapsmall}, \PValue{smallchaptergap}}{% - Marks chapter starts at the lists of floating environments by a small - vertical gap.% - \IndexOption{listof~=\PValue{chaptergapsmall}}}% + Indicates the beginning of chapters in the lists of floating environments + with a small vertical space.% + \IndexOption{listof~=\textKValue{chaptergapsmall}}}% \entry{\PValue{entryprefix}}{% \ChangedAt{v3.06}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - Adds a prefix depending on the file extension of the list to each entry of - the lists of floating environments. The prefix additionally depends on the - language, e.\,g., in English ``Figure'' would be used for the entries to - the list of figures and ``Table'' for the entries to the list of - tables. Both prefixes will be followed by a white space.% - \IndexOption{listof~=\PValue{entryprefix}}}% + Adds a prefix before the number of each floating-environment list entry. + The prefix is usually language-dependent, e.\,g., in English ``Figure'' is + used for the list of figures and ``Table'' for the list of tables, each + followed by a white space.% + \IndexOption{listof~=\textKValue{entryprefix}}}% \entry{\PValue{flat}, \PValue{left}}{% - The lists of floating environments will be printed like a kind of - table. The caption numbers will be the first column, the caption texts the - second column, and the page numbers the last column. The width of the first - column depends on the previous \LaTeX{} run.% - \IndexOption{listof~=\PValue{flat}}}% + Prints the lists of floating environments in tabular form. The caption + numbers are the first column, the caption texts the second column, and the + page numbers the third column. The space reserved for the caption numbers + depends on the previous \LaTeX{} run.% + \IndexOption{listof~=\textKValue{flat}}}% \entry{\PValue{graduated}, \PValue{indent}, \PValue{indented}}{% - The lists of floating environments will be printed in hierarchical - form. The width for the caption numbers will be limited.% - \IndexOption{listof~=\PValue{graduated}}}% + Prints the lists of floating environments in a hierarchical form. The + space reserved for the caption numbers is limited.% + \IndexOption{listof~=\textKValue{graduated}}}% \entry{\PValue{leveldown}}{% - The lists of floating environments will use a heading of one step lower - sectioning level than default.% - \IndexOption{listof~=\PValue{leveldown}}}% + Uses headings that are one level lower in the sectioning hierarchy than + the default for lists of floating environments.% + \IndexOption{listof~=\textKValue{leveldown}}}% + \entry{\PValue{indenttextentries}, \PValue{indentunnumbered}, + \PValue{numberline}}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The \PValue{numberline} property (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.setuptoc}) is set for the lists of floating + environments such as figures and tables. As a result, unnumbered entries + are left-aligned with the text of numbered entries of the same level. + However, the \KOMAScript{} classes themselves do not put unnumbered + entries in these lists. This option therefore affects only entries that + are generated not by the \KOMAScript{} classes themselves but with the + help of \DescRef{tocbasic.cmd.addxcontentsline} (see + \autoref{sec:tocbasic.toc}, \DescPageRef{tocbasic.cmd.addxcontentsline}).% + \IndexOption{toc~=\textKValue{numberline}}}% + \entry{\PValue{leftaligntextentries}, \PValue{leftalignunnumbered}, + \PValue{nonumberline}}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The \PValue{nonumberline} property (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.setuptoc}) is set for the lists of floating + environments. This will place unnumbered entries left-aligned with the + number of numbered entries. However, the \KOMAScript{} classes themselves + do not put unnumbered entries in these lists. This option therefore + affects only entries that are generated not by the \KOMAScript{} classes + themselves but with the help of \DescRef{tocbasic.cmd.addxcontentsline} + (see \autoref{sec:tocbasic.toc}, + \DescPageRef{tocbasic.cmd.addxcontentsline}).% + \IndexOption{toc~=\textKValue{nonumberline}}}% \entry{\PValue{nochaptergap}, \PValue{ignorechapter}}{% - Chapter starts are not marked at the lists of floating environments.% - \IndexOption{listof~=\PValue{nochaptergap}}}% - \entry{\PValue{notoc}, \PValue{plainheading}}{% - The lists of floating environments, e.\,g., list of figures and list of - tables do not generate an entry at the table of contents.% - \IndexOption{listof~=\PValue{notoc}}}% + The beginnings of chapters are not marked in the lists of floating + environments.% + \IndexOption{listof~=\textKValue{nochaptergap}}}% + \entry{\PValue{notoc}, \PValue{nottotoc}, \PValue{plainheading}}{% + The lists of floating environments do not generate entries in the table of + contents.% + \IndexOption{listof~=\textKValue{nottotoc}}}% \entry{\PValue{numbered}, \PValue{totocnumbered}, \PValue{tocnumbered}, - \PValue{numberedtotoc}}{% - The lists of floating environments, e.\,g., list of figures and list of - tables, would get a numbered heading and therefor generate an entry at the - table of contents.% - \IndexOption{listof~=\PValue{numbered}}}% + \PValue{numberedtoc}, \PValue{numberedtotoc}}{% + The lists of floating environments receive numbered entries in the table + of contents.% + \IndexOption{listof~=\textKValue{numbered}}}% + \entry{\PValue{standardlevel}}{% + The lists use the normal sectioning level.% + \IndexOption{listof~=\textKValue{standardlevel}}}% \entry{\PValue{totoc}, \PValue{toc}, \PValue{notnumbered}}{% - The lists of floating environments, e.\,g., list of figures and list of - tables, would generate an entry at the table of contents, but their - headings are not numbered.% - \IndexOption{listof~=\PValue{totoc}}}% + The lists of floating environment generate entries in the table of + contents, but their headings are unnumbered.% + \IndexOption{listof~=\textKValue{totoc}}}% \end{desclist} % \EndIndexGroup @@ -3724,69 +4243,67 @@ An overview about all settings to option \Option{listof} may be found at \Macro{listoftables}% \Macro{listoffigures} \end{Declaration} -\BeginIndex{}{tables>list of}\BeginIndex{}{list of>tables}% -\BeginIndex{}{figures>list of}\BeginIndex{}{list of>figures}% -These commands generate a list of tables or figures. Changes in the document -that modify these lists will require two {\LaTeX} runs in order to take -effect. The layout of the lists can be influenced by the option -\DescRef{\LabelBase.option.listof}\important{\DescRef{\LabelBase.option.listof}} -with values \PValue{graduated} or \PValue{flat} (see -\DescPageRef{\LabelBase.option.listof}). Moreover, the values \PValue{listof} -and \PValue{listofnumbered} of option -\DescRef{\LabelBase.option.toc}\important{\DescRef{\LabelBase.option.toc}} -(see \autoref{sec:\LabelBase.toc}) as well as the values \PValue{totoc} and -\PValue{numbered} of the previous described option -\DescRef{\LabelBase.option.listof} have influence to the lists of floating -environments. - -Mostly\textnote{Hint!} the lists of floating environment may be found after -the table of contents. But some publishers like to have these lists at the -appendix. Nevertheless the author of this guide prefers to find them +These commands generate a list of tables or figures. Changes affecting these +lists will require two \LaTeX{} runs to take effect. The layout of the lists +can be influenced by the \DescRef{\LabelBase.option.listof}% +\important{\DescRef{\LabelBase.option.listof}} option with the values +\PValue{graduated} or \PValue{flat} (see +\DescPageRef{\LabelBase.option.listof}). In addition, the \PValue{listof} and +\PValue{listofnumbered} values of the \DescRef{\LabelBase.option.toc}% +\important{\DescRef{\LabelBase.option.toc}} option (see +\autoref{sec:\LabelBase.toc}), as well as the \PValue{totoc} and +\PValue{numbered} values of the \DescRef{\LabelBase.option.listof} option +described above indirectly affect these lists. + +As\textnote{Hint!} a rule, you will find the lists of the floating +environments immediately after the table of contents. In some documents, they +go into the appendix. However, the author of this guide prefers them immediately after the table of contents.% -\EndIndexGroup % \EndIndexGroup -\LoadCommonFile{marginpar}% \section{Margin Notes} +\LoadCommonFile{marginpar}% \section{Marginal Notes} \section{Appendix} \seclabel{appendix} \BeginIndexGroup -\BeginIndex{}{appendix} - -The appendix of a document contains mainly the enclosures to the -document. These are typically bibliography, index, glossary. But only for this -parts nobody would and should start an appendix, because the formation of -these already distinguishes them from the main document. But if there are -additional elements at the appendix, i.\,e., cited third party documents, -endnotes, figures or tabulars, the standard elements like the bibliography +\BeginIndex{}{Appendix} + +The appendix of a document mostly consists of supplements to the document. +Typical parts of an appendix include a bibliography, an index, and a glossary. +However you should not start an appendix for these parts alone because their +format already distinguishes them from the main document. But if there are +additional elements in the appendix, such as quoted third-party documents, +endnotes, figures, or tabulars, the standard elements such as the bibliography should also be part of the appendix. + \begin{Declaration} \Macro{appendix} \end{Declaration}% -The appendix in the standard as well as the {\KOMAScript} classes is -introduced with \Macro{appendix}. This command switches, among other things, -the chapter numbering to upper case letters, also ensuring that the rules -according to \cite{DUDEN} are followed (for German-speaking regions). These -rules are explained in more detail in the description of the option -\DescRef{\LabelBase.option.numbers} in \autoref{sec:\LabelBase.structure}, -\DescPageRef{\LabelBase.option.numbers}. - -Die output of the chapter headings\OnlyAt{\Class{scrbook}\and - \Class{scrreprt}} in the appendix are influenced by the options -\DescRef{\LabelBase.option.chapterprefix} and -\DescRef{\LabelBase.option.appendixprefix}. See +The appendix is started in the standard as well as the {\KOMAScript} classes +with \Macro{appendix}. Among other things, this command changes the chapter +numbering to upper-case letters while ensuring that the rules according to +\cite{DUDEN} for numbering the sectioning levels are followed (for +German-speaking regions). These rules are explained in more detail in the +description of the \DescRef{\LabelBase.option.numbers} option in +\autoref{sec:\LabelBase.structure}, \DescPageRef{\LabelBase.option.numbers}. + +The format of the chapter headings\OnlyAt{\Class{scrbook}\and + \Class{scrreprt}} in the appendix is influenced by the +\DescRef{\LabelBase.option.chapterprefix}% +\important{\DescRef{\LabelBase.option.chapterprefix}\\ + \DescRef{\LabelBase.option.appendixprefix}} and +\DescRef{\LabelBase.option.appendixprefix} options. See \autoref{sec:\LabelBase.structure}, \DescPageRef{\LabelBase.option.appendixprefix} for more information. Please\textnote{Attention!} note that \Macro{appendix} is a command, -\emph{not} an environment! This command does not expect any -argument. Chapters and sections in the appendix uses -\DescRef{\LabelBase.cmd.chapter} and \DescRef{\LabelBase.cmd.section} just as -does the main text.% +\emph{not} an environment! This command does not expect an argument. Chapters +and sections in the appendix use \DescRef{\LabelBase.cmd.chapter} and +\DescRef{\LabelBase.cmd.section}, just as in the main text.% % \EndIndexGroup % @@ -3798,125 +4315,127 @@ does the main text.% \BeginIndexGroup \BeginIndex{}{bibliography} -The bibliography opens up external resources. Mainly bibliographies will be -made by program \BibTeX{} or biber using an external file in database like -structure. Thereby \BibTeX{} style influences not only the formation of the -bibliography entries but also their sorting. Using an additional bibliography -style like \Package{natbib}\IndexPackage{natbib}, +The bibliography makes external sources accessible. As a rule, the +bibliography is created from an external file with a database-like structure +using the \BibTeX{} program. You can use the \BibTeX{} style to change both +the format of the entries and their sorting. If you use an additional +bibliography package like \Package{natbib}\IndexPackage{natbib}, \Package{babelbib}\IndexPackage{babelbib}, or -\Package{biblatex}\IndexPackage{bublatex} limits the influence of -\KOMAScript{} to the bibliography hardly. In such cases it is important so see -the manual of the bibliography package! General information about bibliography -may be found in \cite{lshort}. +\Package{biblatex}\IndexPackage{biblatex}, \KOMAScript{}'s influence over the +bibliography disappears. In such cases, you must follow the manual of the +relevant bibliography package. You can find general information about +bibliographies in \cite{lshort}. \begin{Declaration} - \OptionVName{bibliography}{selection} + \OptionVName{bibliography}{setting} \end{Declaration} -For a start, \PName{selection}\ChangedAt{v3.00}{\Class{scrbook}\and - \Class{scrreprt}\and \Class{scrartcl}} may be any already defined -bibliography formation style. There are two predefined formation styles at -\KOMAScript{}. You should not misconceive them with the styles used by -\BibTeX\Index{BibTeX=\BibTeX} which you may select using -\Macro{bibstyle}. While \BibTeX{} influences not only the sorting but also the +For a start,\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} you can select any predefined bibliography style in +\PName{setting}. There are two such bibliography styles predefined in +\KOMAScript{}. You should not confuse them with the styles used by +\BibTeX\Index{BibTeX=\BibTeX}, which you select with +\Macro{bibstyle}. While \BibTeX{} determines both the sorting and the contents of the bibliography, \KOMAScript{} influences only some basic -features of the bibliography or a tiny amount of formation features of the -entries to the bibliography. +features of the bibliography and few properties of the entry format. -Option\important{\OptionValue{bibliography}{oldstyle}} +The\important{\OptionValue{bibliography}{oldstyle}} \OptionValue{bibliography}{oldstyle}% -\IndexOption{bibliography~=\PValue{oldstyle}} selects a compact formation of -the bibliography entries. In this case command -\DescRef{maincls-experts.cmd.newblock}\IndexCmd{newblock} inside of the entries will only result in -a small horizontal distance. The name is a result of the fact, that this is -the mostly used classic kind of bibliography. In opposite to -this\important[i]{\begin{tabular}[t]{@{}l@{}} - \Option{bibliography=}\\ - \quad\PValue{openstyle}\end{tabular}}% +\IndexOption{bibliography~=\textKValue{oldstyle}} option selects a compact +format for bibliography entries. In this case, using the +\DescRef{maincls-experts.cmd.newblock}\IndexCmd{newblock} command results in +only a small glue between the entries. The name comes from the fact that this +is the most common classic form of a bibliography. +In\important{\OptionValue{bibliography}{openstyle}} contrast, the \OptionValue{bibliography}{openstyle}% -\IndexOption{bibliography~=\PValue{openstyle}}. selects a more modern and open -kind of bibliography. The name is a result of the fact, that command -\DescRef{maincls-experts.cmd.newblock} inserts a paragraph break. The entries will be more -structured by this. They are less compact and seem more relaxed or -open. Information about definition of new formation styles may be found in -description of command \DescRef{maincls-experts.cmd.newbibstyle} in -\autoref{sec:maincls-experts.experts} at +\IndexOption{bibliography~=\textKValue{openstyle}} setting selects a more +modern and open kind of bibliography. The name comes from the fact that the +\DescRef{maincls-experts.cmd.newblock} command inserts a paragraph break. The +bibliography entries appear more structured. They are less compact and seem +more relaxed or open. Information about defining new bibliography styles can +be found in the description of the \DescRef{maincls-experts.cmd.newbibstyle} +command in \autoref{sec:maincls-experts.experts}, \DescPageRef{maincls-experts.cmd.newbibstyle}. -Beside the formation style one more feature may be selected using -\PName{selection}. The bibliography is a kind of contents list. But instead of -listing contents of the document itself, it references to external -contents. Because of this, someone may say, that -the\important[i]{\begin{tabular}[t]{@{}l@{}} - \Option{bibliography=}\\ - \quad\PValue{totocnumbered} - \end{tabular}} bibliography is a chapter -or section on its own and should have a chapter or section number. You may -select this with option \OptionValue{bibliography}{totocnumbered}% -\IndexOption{bibliography~=\PValue{totocnumbered}} which will therefor also -generate an entry to the table of contents.In my opinion the bibliography is -nothing you've written on your own and so does not merits a numbered entry to -the table of contents. A entry without number may be set with option -\OptionValue{bibliography}{totoc}% -\IndexOption{bibliography~=\PValue{totoc}}. Nevertheless, the default would be -neither a number nor an entry to the table of contents and corresponds to +In addition to the formatting style, you can select one more feature using +\PName{setting}. The bibliography is a kind of list of contents. But instead +of listing the contents of the document itself, it references external works. +With this reasoning, you could argue that the bibliography is a separate +chapter or section and therefore deserves a chapter or section number. The +\OptionValue{bibliography}{numbered}% +\important{\OptionValue{bibliography}{numbered}}% +\IndexOption{bibliography~=\textKValue{numbered}} setting does exactly that, +including creating an entry in the table of contents. In my opinion, a +traditional, annotated source list should by this reasoning be a separate +chapter too. Moreover, the bibliography is ultimately nothing you've written +yourself and so merits at most an unnumbered entry in the table of contents, +which is achieved with the \OptionValue{bibliography}{totoc}% +\IndexOption{bibliography~=\textKValue{totoc}} option. The default setting, +where the bibliography is produced as an unnumbered chapter and does not +receive an entry in the table of contents corresponds to \OptionValue{bibliography}{nottotoc}% -\IndexOption{bibliography~=\PValue{nottotoc}}. For more information see option -\DescRef{\LabelBase.option.toc} in \autoref{sec:\LabelBase.toc}, especially values -\PValue{bibliographynumbered}, \PValue{bibliography}, and -\PValue{nobibliography} to this option at +\IndexOption{bibliography~=\textKValue{nottotoc}}. For more information, see +the \DescRef{\LabelBase.option.toc} option in \autoref{sec:\LabelBase.toc}, +especially the \PValue{bibliographynumbered}, \PValue{bibliography}, +and\PValue{nobibliography} values for this option on \DescPageRef{\LabelBase.option.toc.bibliography}. Sometimes\ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} it is not usefull to have one bibliography for the whole -document but a bibliography at every chapter of a document made using -\Class{scrbook} or \Class{scrreprt}. In that case -you'd\important{\OptionValue{bibliography=leveldown}} need the bibliography -itself not to be a chapter but one level below, a section. You may achieve -this using Option \OptionValue{bibliography}{leveldown}% -\IndexOption{bibliography~=\PValue{leveldown}}. You may use this also if you'd -combine several lists and the bibliography together below one heading. So this -option is also available with \Class{scrartcl}. - -A summary of all available values for option \Option{bibliography} may be -found in \autoref{tab:\LabelBase.bibliography}. Nevertheless you should note, -that additional values may be generated using + \Class{scrartcl}} a document made using \Class{scrbook} or \Class{scrreprt} +will have a bibliography for every chapter rather than one bibliography for +the whole document. In that case, it makes sense for the bibliography +itself\important{\OptionValue{bibliography=leveldown}} to be not a chapter but +a section. You can achieve this using the +\OptionValue{bibliography}{leveldown}% +\IndexOption{bibliography~=\textKValue{leveldown}} option. You can also use +this if you want the bibliography to appear with other lists under a common +heading, therefore this option is also available with \Class{scrartcl}. + +You can find a summary of available values for the \Option{bibliography} +option in \autoref{tab:\LabelBase.bibliography}. Note, however, that you can +define new values with \DescRef{maincls-experts.cmd.newbibstyle}\IndexCmd{newbibstyle}. \begin{table} - \caption[{Available values of option \Option{bibliography}}]{% - Predefined values of option \Option{bibliography} to select the formation - of the bibliography} + \caption[{Available values for the \Option{bibliography} option}]{% + Predefined values for the \Option{bibliography} option for setting the + bibliography format} \label{tab:\LabelBase.bibliography} \begin{desctabular} \pventry{leveldown}{% \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - The bibliography will use a heading of one step lower section level than - default.% - \IndexOption{bibliography~=\PValue{leveldown}}}% - \pventry{nottotoc}{% - The bibliography will neither have an entry at the table of contents nor - a number,% - \IndexOption{bibliography~=\PValue{nottotoc}}}% + The bibliography uses a sectioning command one level lower than + the default.% + \IndexOption{bibliography~=\textKValue{leveldown}}}% + \entry{\PValue{notoc}, \PValue{nottotoc}, \PValue{plainheading}}{% + The bibliography receives neither an entry in the table of contents nor + a number.% + \IndexOption{bibliography~=\textKValue{nottotoc}}}% + \entry{\PValue{numbered}, \PValue{tocnumbered}, \PValue{totocnumbered}, + \PValue{numberedtoc}, \PValue{numberedtotoc}}{% + The bibliography receives an entry in the table of contents and a + number.% + \IndexOption{bibliography~=\textKValue{numbered}}}% \pventry{oldstyle}{% - The bibliography will use the classic, compact formation, where - \DescRef{maincls-experts.cmd.newblock}\IndexCmd{newblock} generates an - expandable horizontal distance only.% - \IndexOption{bibliography~=\PValue{oldstyle}}}% + The bibliography uses the classic, compact formation, where + \DescRef{maincls-experts.cmd.newblock}\IndexCmd{newblock} generates only + a horizontal glue.% + \IndexOption{bibliography~=\textKValue{oldstyle}}}% \pventry{openstyle}{% - The bibliography will use the structured, open formation, where + The bibliography uses the structured, open format where \DescRef{maincls-experts.cmd.newblock}\IndexCmd{newblock} generates a paragraph break.% - \IndexOption{bibliography~=\PValue{openstyle}}}% - \pventry{totoc}{% - The bibliography will have an entry at the table of contents but no + \IndexOption{bibliography~=\textKValue{openstyle}}}% + \pventry{standardlevel}{% + \ChangedAt{v3.12}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The bibliography uses the standard sectioning command level.% + \IndexOption{bibliography~=\textKValue{standardlevel}}}% + \entry{\PValue{toc}, \PValue{totoc}, \PValue{notnumbered}}{% + The bibliography receives an entry in the table of contents but no number.% - \IndexOption{bibliography~=\PValue{totoc}}}% - \pventry{totocnumbered}{% - The bibliography will have an entry at the table of contents and a - number at the heading.% - \IndexOption{bibliography~=\PValue{totocnumbered}}}% + \IndexOption{bibliography~=\textKValue{totoc}}}% \end{desctabular} \end{table} % @@ -3926,29 +4445,28 @@ that additional values may be generated using \begin{Declaration} \Macro{setbibpreamble}\Parameter{preamble} \end{Declaration}% -The command \Macro{setbibpreamble} can be used to set a preamble for the -bibliography\Index{bibliography}. This can be achieved by placing the preamble -before the command for issuing the bibliography. However, it need not be -directly in front of it. For example, it could be placed at the beginning of -the document. Similar\textnote{Attention!} to the options +You can use the \Macro{setbibpreamble} command to set a preamble for the +bibliography\Index{bibliography}. This preamble must be placed before the +command for issuing the bibliography. However, it need not be directly +in front of it. For example, it could be placed at the beginning of +the document. Like\textnote{Attention!} the \OptionValueRef{\LabelBase}{bibliography}{totoc} and -\OptionValueRef{\LabelBase}{bibliography}{totocnumbered}, this command can -only be successful if you have not loaded a package which prevents this by -redefining the \Environment{thebibliography} environment. Even though the -\Package{natbib} package\IndexPackage{natbib} makes unauthorized use of -internal macros of {\KOMAScript} it could be achieved that -\Macro{setbibpreamble} works with the current version of \Package{natbib} (see -\cite{package:natbib}). +\OptionValueRef{\LabelBase}{bibliography}{totocnumbered} options, this command +only works if you have not loaded a package which prevents this from happening +by redefining the \Environment{thebibliography} environment. Although the +\Package{natbib} package\IndexPackage{natbib} uses undocumented, internal +{\KOMAScript} macros, \Macro{setbibpreamble} could still work with the current +version of \Package{natbib} (see \cite{package:natbib}). \begin{Example} - You want to point out that the sorting of the references in the - bibliography is not according to their occurrence in the text, but - in alphabetical order. You use the following command: + You want to point out that the bibliographical references are sorted + alphabetically by the names of the authors. You therefore use the following + command: \begin{lstcode} \setbibpreamble{References are in alphabetical order. References with more than one author are sorted according to the first author.\par\bigskip} \end{lstcode} - The \Macro{bigskip}\IndexCmd{bigskip} command makes sure that the + The \Macro{bigskip}\IndexCmd{bigskip} command ensures that the preamble and the first reference are separated by a large vertical space.% \end{Example}% @@ -3962,13 +4480,14 @@ internal macros of {\KOMAScript} it could be achieved that This\textnote{Attention!}\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} command exists only if the environment \Environment{thebibliography} has not been redefined by another -package. It provides a break at the bibliography. The \PName{interruption - code} will be expanded inside a group. Such a break may be, e.\,g., a -heading using \DescRef{\LabelBase.cmd.minisec}. Unfortunately it is not -possible to add this command to the \BibTeX{} database using, e.\,g., a -special kind of \BibTeX{} entry. Because of this, users may use is currently -only if they make the bibliography on their own. Because of this usage is very -limited.% +package. With this instruction, you can insert a break into the +bibliography. The \PName{interruption code} will be expanded inside a +group. Such a break may be, for example, a heading using +\DescRef{\LabelBase.cmd.minisec}. Unfortunately there is currently no way to +have this command automatically generated, for example by using a special +entry in the \BibTeX{} database. Therefore, it can currently only be used by +users who edit the bibliography directly. For this reason, its usefulness is +very limited.% % \EndIndexGroup @@ -3978,23 +4497,22 @@ limited.% \Macro{AtEndBibliography}\Parameter{code} \end{Declaration} In\ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}} -some cases it may be useful to add some \PName{code} after the bibliography -preamble or just before the end of the bibliography. This may be achieved -using one of this instructions. +some cases, it may be useful to add some \PName{code} after the bibliography +preamble or just before the end of the bibliography. This is possible with the +help of these two instructions. \begin{Example} - You want to set the bibliography not justified but ragged right. This may be - achieved using: + You want to set the bibliography not justified but ragged right. You can + achieve this with: \begin{lstcode} \AfterBibliographyPreamble{\raggedright} \end{lstcode} - You may place this instruction anywhere before the - bibliography. Nevertheless it is recommended to do so at the preamble of the - document or inside your own package. + You can put this instruction anywhere before the bibliography. However, it is + recommended to do so in the preamble of the document or a separate package. \end{Example} The\textnote{Attention!} functionality of this instruction depends on -cooperation with packages modifying the bibliography, if such a package should -be used (see \autoref{sec:maincls-experts.coexistence}, -\DescPageRef{maincls-experts.cmd.AfterBibliographyPreamble}).% +cooperation with packages modifying the bibliography, if you use such a +package\iffree{}{(see \autoref{sec:maincls-experts.coexistence}, +\DescPageRef{maincls-experts.cmd.AfterBibliographyPreamble})}.% % \EndIndexGroup % @@ -4004,54 +4522,83 @@ be used (see \autoref{sec:maincls-experts.coexistence}, \section{Index} \seclabel{index} \BeginIndexGroup -\BeginIndex{}{index} -For general information about making an index see \cite{lshort}, -\cite{makeindex}, and \cite{xindy}. Using a package, that redefines commands -or environments for the index, may limit the influence of \KOMAScript{} to the -index hardly. This would be valid, e.\,g., for usage of package -\Package{index}\IndexPackage{index} but not for usage of package -\Package{splitidx}\IndexPackage{splitidx} (see \cite{package:splitindex}). +For general information about making a keyword index, see \cite{lshort}, +\cite{makeindex}, and \cite{xindy}. Using a package that redefines +commands or environments for the index \KOMAScript{}'s ability to influence +the index may disappear. This applies, for example, when using the +\Package{index}\IndexPackage{index} package, but not when using the +\Package{splitidx}\IndexPackage{splitidx} package (see +\cite{package:splitindex}). \begin{Declaration} - \OptionVName{index}{selection}% + \OptionVName{index}{setting}% \end{Declaration} \ChangedAt{v3.00}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% -The index is chapter (\Class{scrbook} or \Class{scrreprt}) or section -(\Class{scrartcl}) without heading number or entry at the table of contents by -default or option -\OptionValue{index}{default}\IndexOption{index~=\PValue{default}}. -The\important{\OptionValue{index}{totoc}} index does not need an entry at the -table of contents, because it should always be the last element of a -document. Nevertheless, such an entry may be achieved using option -\OptionValue{index}{totoc}\IndexOption{index~=\PValue{totoc}}. +By default or with \OptionValue{index}{default}% +\IndexOption{index~=\textKValue{default}}, the index is an unnumbered chapter +(\Class{scrbook} or \Class{scrreprt}) or section (\Class{scrartcl}) without an +entry in the table of contents. Since\important{\OptionValue{index}{totoc}} +the index usually comes last in a book or similar document, it does not +actually need an entry in the table of contents. Nevertheless, if you want to +do this, for example because you are working with a multi-index keyword +dictionary such as the one that appears in this \iffree{guide}{book}, you can +create this with the +\OptionValue{index}{totoc}\IndexOption{index~=\textKValue{totoc}} option. You\ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and - \Class{scrartcl}} can even number the index using option -\OptionValue{index}{numbered}\IndexOption{index~=\PValue{numbered}}. See also -option \DescRef{\LabelBase.option.toc} with value \PValue{index} or -\PValue{indexnumbered} in \autoref{sec:\LabelBase.toc} from -\DescPageRef{\LabelBase.option.toc.index} onward. - -A summary of all available values for option \Option{index} may be found in -\autoref{tab:\LabelBase.index}. + \Class{scrartcl}} can even number the index using the +\OptionValue{index}{numbered}\IndexOption{index~=\textKValue{numbered}} +setting. See also the \DescRef{\LabelBase.option.toc} option with the +\PValue{index} or \PValue{indexnumbered} values in +\autoref{sec:\LabelBase.toc} starting at +\DescPageRef{\LabelBase.option.toc.index}. + +For example, if you create multiple indexes with +\Package{splitidx}\IndexPackage{splitidx} (see \cite{package:splitindex}), +it may be useful to group them under a common heading. To make this possible, +\OptionValue{index}{leveldown}% +\ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\important{\OptionValue{index}{leveldown}} places the index +one sectioning level deeper than usual. In \Class{scrbook} and +\Class{scrreprt}, it is no longer a chapter but a section; with +\Class{scrartcl}, a subsection. The \OptionValue{index}{standardlevel}% +\ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}\important{\OptionValue{index}{standardlevel}} option is +the counterpart to this and cancels any instance of +\OptionValue{index}{leveldown} used previously. + +You can find a summary of the available values for the \PName{setting} of +\Option{index} in \autoref{tab:maincls.index}. \begin{table} - \caption{Available values of option \Option{index}}% - \label{tab:\LabelBase.index} + \caption{Available values for the \Option{index} option} + \label{tab:maincls.index} \begin{desctabular} - \entry{\PValue{default}, \PValue{nottotoc}, \PValue{plainheading}}{% - The index will not have an entry at the table of contents.% - \IndexOption{index~=\PValue{default}}}% - \entry{\PValue{numbered}, \PValue{totocnumbered}}{% + \pventry{leveldown}{% + \ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The index is moved down by one sectioning level.% + \IndexOption{index~=\textKValue{leveldown}}% + }% + \entry{\PValue{notoc}, \PValue{nottotoc}, \PValue{plainheading}}{% + The index does not receive an entry in the table of contents.% + \IndexOption{index~=\textKValue{nottotoc}}}% + \entry{\PValue{numbered}, \PValue{tocnumbered}, \PValue{totocnumbered}, + \PValue{numberedtoc}, \PValue{numberedtotoc}}{% + \ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}}% + The index receives an entry in the table of contents and is numbered.% + \IndexOption{index~=\textKValue{numbered}}}% + \pventry{standardlevel}{% \ChangedAt{v3.18}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}% - The index will have an entry at the table of contents and also will have - a heading number.% - \IndexOption{index~=\PValue{numbered}}}% - \entry{\PValue{totoc}, \PValue{toc}, \PValue{notnumbered}}{% - The index will have an entry at the table of contents, but will not have - a heading number.% - \IndexOption{index~=\PValue{totoc}}}% + The index is at the usual sectioning level.% + \IndexOption{index~=\textKValue{standardlevel}}% + }% + \entry{\PValue{toc}, \PValue{totoc}, \PValue{notnumbered}}{% + The index receives an entry in the table of contents without being + numbered.% + \IndexOption{index~=\textKValue{totoc}}}% \end{desctabular} \end{table} % @@ -4061,9 +4608,9 @@ A summary of all available values for option \Option{index} may be found in \begin{Declaration} \Macro{setindexpreamble}\Parameter{preamble} \end{Declaration}% -Similarly to the bibliography you can use a preamble to the +As with the bibliography, you can also provide a preamble to the index. This is often the case if you have more than one index or if -you use different kinds of referencing by highlighting the page +you mark different kinds of references by highlighting the page numbers in different ways. \begin{Example} You have a document in which terms are both defined and used. The @@ -4071,31 +4618,38 @@ numbers in different ways. your reader aware of this fact. Thus you insert a preamble for the index: \begin{lstcode} - \setindexpreamble{In \textbf{bold} printed page numbers are - references to the definition of terms. Other page numbers - indicate the use of a term.\par\bigskip} + \setindexpreamble{All page numbers printed in \textbf{bold} + refer to definitions of terms. Page numbers printed + normally refer to pages where the term is used.\par\bigskip} \end{lstcode} \end{Example} -Please note that the page style of the first page of the index is changed. The -applied page style is defined in the macro +Note\textnote{Attention!} that the page style is changed for the first page +of the index. The page style that is applied is defined in the macro \DescRef{\LabelBase.cmd.indexpagestyle} (see \autoref{sec:\LabelBase.pagestyle}, \DescPageRef{\LabelBase.cmd.indexpagestyle}). -The production, sorting and output of the index is done by the -standard {\LaTeX} packages and additional programs. Similar to the -standard classes {\KOMAScript} only provides the basic macros and -environments.% +The usual \LaTeX{} packages and additional programs are responsible for +creating, sorting, and outputting the index.% +\iftrue % Umbruchoptimierung + \iffree{}{ % + For example, the \Package{imakeidx}\IndexPackage{imakeidx} package + (see \cite{package:imakeidx}), which among other things automates the + invocation of the \File{makeindex} or \File{xindy} program, is highly + recommended. This eliminates a common source of error, particularly for + \LaTeX{} beginners.% + } + {\KOMAScript}, like the standard classes, provides only the basic macros + and environments for them.% +\fi % \EndIndexGroup % \EndIndexGroup % -% \EndIndexGroup - \endinput %%% Local Variables: @@ -4105,5 +4659,3 @@ environments.% %%% ispell-local-dictionary: "english" %%% TeX-master: "../guide" %%% End: - -% LocalWords: endnotes interleaf |