diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/scrguide/english/maincls.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/scrguide/english/maincls.tex | 4825 |
1 files changed, 4825 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/scrguide/english/maincls.tex b/Master/texmf-dist/source/latex/koma-script/scrguide/english/maincls.tex new file mode 100644 index 00000000000..5b7fb566be5 --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/scrguide/english/maincls.tex @@ -0,0 +1,4825 @@ +\ProvidesFile{maincls.tex}[2004/09/13 KOMA-Script Manual] +% ============================================================================ +% maincls.tex +% Copyright (c) 2002 Markus Kohm and the authors. +% +% This file is part of the LaTeX2e KOMA-Script-Bundle +% +% This file can be redistributed and/or modified under the terms of the LaTeX +% Project Public License Version 1.0 distributed together with this file. See +% LEGAL.TXT or LEGALDE.TXT. +% +% This bundle is written specialy for use at german-language. So the main +% documentation is german. There may also be an english documentation. See +% readme.txt, if you search for it. +% ---------------------------------------------------------------------------- +% maincls.tex +% Copyright (c) 2002 Markus Kohm und bei den weiteren Autoren. +% +% Diese Datei ist Teil des LaTeX2e KOMA-Script-Pakets. +% +% Diese Datei kann nach den Regeln der LaTeX Project Public Licence +% Version 1.0, wie sie zusammen mit dieser Datei verteilt wird, +% weiterverbreitet und/oder modifiziert werden. Siehe dazu auch LEGAL.TXT oder +% LEGALDE.TXT. +% +% Dieses Paket ist fuer den deutschen Sprachraum konzipiert. Daher ist auch +% diese Anleitung komplett in Deutsch. Moeglicherweise existiert auch eine +% englische Version der Anleitung. Falls Sie eine solche benoetigen, schauen +% Sie bitte in liesmich.txt nach, ob eine solche vorhanden ist. +% ============================================================================ +% +% Module: maincls +% Translation by: Jo\~{a}o Canas Ferreira +% Georg Grandke +% Markus Kohm (only some) +% Contents: the main KOMA-Script classes +% Language: English +% Charset of comments: US-ASCII +% Translation of german file: hauptcls.tex +% Date of translated german file: 2004-01-08 +% + +\chapter{The Main Classes \Class{scrbook}, \Class{scrrprt} and + \Class{scrartcl}} +\label{cha:maincls} + +\AddSeeIndex{macro}{gen}{\cmdIndexShortName}{cmd}% + +\begin{Explain} + 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 \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 different from the three main classes + (see \autoref{cha:scrlttr2}).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 if necessary. The + \autoref{tab:maincls.overview} shows an overview. The table also + includes the names of the \LaTeX2.09 style files that were used in + {\KOMAScript}. +\end{Explain} +\par + +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:maincls.overview}. 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. + +\begin{table}[htbp] + \centering + \begin{tabular}{lll} + Standard class & \KOMAScript{} class & \Script{} Style + (\LaTeX2.09)\\ + \hline\rule{0pt}{2.7ex}% + \Class{article} & \Class{scrartcl} & \File{script\textunderscore + s} \\ + \Class{report} & \Class{scrreprt} & \File{script} \\ + \Class{book} & \Class{scrbook} & \File{script} \\ + \Class{letter} & \Class{scrlettr} & \File{script\textunderscore + l} \\ + \end{tabular} + \caption[Class correspondence]{Correspondence between + standard classes, \KOMAScript{} classes and + \Script{} styles.} + \label{tab:maincls.overview} +\end{table} + + +\section{The Options} +\label{sec:maincls.options} + + +This section describes the global options of the three main classes. +The majority of the options can also be found in the standard classes. +Since experience shows that many options of the standard classes are +unknown, their description is included here. This is a departure from +the rule that the \File{scrguide} should only describe those aspects +whose implementation differs from the standard one. + +Table~\ref{tab:maincls.stdOptions} lists those options that are set by +default in at least one of the {\KOMAScript} classes. The table shows +for each {\KOMAScript} main class if the option is set by default and +if it is even defined for that class. An undefined option cannot be +set, either by default or by the user. + +\begin{table}[htbp] + \centering + \begin{tabular}{llll} + Option & + \Class{scrbook} & \Class{scrreprt} & \Class{scrartcl} \\ + \hline\rule{0pt}{2.7ex}% + \Option{11pt} & + default & default & default \\ + \Option{a4paper} & + default & default & default \\ + \Option{abstractoff} & + \emph{undefined} & default & default \\ + \Option{bigheadings} & + default & default & default \\ + \Option{final} & + default & default & default \\ + \Option{footnosepline} & + default & default & default \\ + \Option{headnosepline} & + default & default & default \\ + \Option{listsindent} & + default & default & default \\ + \Option{nochapterprefix} & + default & default & \emph{undefined} \\ + \Option{onelinecaption} & + default & default & default \\ + \Option{notitlepage} & + & & default \\ + \Option{onecolumn} & + default & default & default \\ + \Option{oneside} & + & default & default \\ + \Option{openany} & + & default & default \\ + \Option{openright} & + default & & \\ + \Option{parindent} & + default & default & default \\ + \Option{tablecaptionbelow} & + default & default & default \\ + \Option{titlepage} & + default & default \\ + \Option{tocindent} & + default & default & default \\ + \Option{twoside} & + default & & \\ + \end{tabular} + \caption{Default options of the \KOMAScript{} classes} + \label{tab:maincls.stdOptions} +\end{table} + +\begin{Explain} + 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 + which \Var{DIV} value to use could be difficult to answer initially. + On the other hand, this kind of information should be initially + irrelevant for the main tasks of an author: design of the document + structure, text writing, preparation of figures, tables and index. + As an author you should concentrate initially on the contents. When + that is done, you can concentrate on the fine points of + presentation. Besides the choice of options, this means correcting + things like hyphenation, page breaks, and the distribution of tables + and figures. As an example consider the + \autoref{tab:maincls.stdOptions} that I have moved repeatedly + between the beginning and the end of this section. The choice of the + actual position will only be made during the final production of the + document. +\end{Explain} +\par + +\subsection{Options for Page Layout} +\label{sec:maincls.typeareaOptions} + +With the standard classes the page layout\Index{page layout} is +established by the option files \File{size10.clo}, \File{size11.clo}, +\File{size12.clo} (or \File{bk10.clo}, \File{bk11.clo}, +\File{bk12.clo} for the book class) and by fixed values in the class +definitions. The \KOMAScript{} classes, however, do not use a fixed +page layout, but one that depends on the paper format\Index{paper + format} and font size. For this task all three main classes use the +\Package{typearea} package\IndexPackage{typearea} (see +\autoref{cha:typearea}). The package is automatically loaded by +the \KOMAScript{} main classes. Therefore it is not necessary to use +the command \verb|\usepackage{typearea}| explicitly. + + +\begin{Declaration} + \Option{letterpaper} \\ + \Option{legalpaper} \\ + \Option{executivepaper} \\ + \Option{a\Var{X}paper} \\ + \Option{b\Var{X}paper} \\ + \Option{c\Var{X}paper} \\ + \Option{d\Var{X}paper} \\ + \Option{landscape} +\end{Declaration}% +\BeginIndex{Option}{letterpaper} \BeginIndex{Option}{legalpaper} +\BeginIndex{Option}{executivepaper} \BeginIndex{Option}{a0paper} +\BeginIndex{Option}{b0paper} \BeginIndex{Option}{c0paper} +\BeginIndex{Option}{d0paper} +\BeginIndex{Option}{landscape}% +The basic options for the choice of paper format are not processed +directly by the classes. They are automatically processed by the +\Package{typearea} package as global options (see +\autoref{sec:typearea.options}). The options \Option{a5paper}, +\Option{a4paper}, \Option{letterpaper}, \Option{legalpaper} and +\Option{executivepaper} correspond to the options of the standard +classes that have the same name and define the same paper format. The +page layout calculated for each is different, however. +% +\EndIndex{Option}{letterpaper} \EndIndex{Option}{legalpaper} +\EndIndex{Option}{executivepaper} \EndIndex{Option}{a0paper} +\EndIndex{Option}{b0paper} \EndIndex{Option}{c0paper} +\EndIndex{Option}{d0paper} \EndIndex{Option}{landscape} + +\begin{Explain} + The options for the A, B, C or D format are actually not processed + by the \Package{typearea}, because they are global options, but + because the \KOMAScript{} classes explicitly pass them to the + \Package{typearea} package. This is caused by the way option + processing is implemented in the \Package{typearea} package and by + the operation of the underlying option passing and processing + mechanism of \LaTeX. + + This is also valid for the options, described subsequently, that set + the binding correcting, the divisor and the number of header lines. +\end{Explain} + + +\begin{Declaration} + \Option{BCOR}\PName{correction}\\ + \Option{DIV}\PName{factor}\\ + \Option{DIVcalc}\\ + \Option{DIVclassic}\\ + \PName{Value}\Option{headlines} +\end{Declaration}% +\BeginIndex{Option}{BCOR}% +\BeginIndex{Option}{DIV}% +\BeginIndex{Option}{DIVcalc}% +\BeginIndex{Option}{DIVclassic}% +\BeginIndex{Option}{headlines}% +The options for the divisor and the binding correction\Index{binding + correction} are passed directly to the \Package{typearea} package +(see \autoref{sec:typearea.options}). This differs from the +standard classes, where there is no such transfer. This is also valid +for the option that sets the number of header lines. +% +\EndIndex{Option}{BCOR}% +\EndIndex{Option}{DIV}% +\EndIndex{Option}{DIVcalc}% +\EndIndex{Option}{DIVclassic}% +\EndIndex{Option}{headlines} + + +\subsection{Options for Document Layout} +\label{sec:maincls.layoutOptions} + +This subsection collects all the options that affect the document +layout, not only the page layout. Strictly speaking all page layout +options (see \autoref{sec:maincls.typeareaOptions}) are also +document layout options. The reverse is also partially true. + +\begin{Declaration} + \Option{oneside}\\ + \Option{twoside} +\end{Declaration}% +\BeginIndex{Option}{oneside} +\BeginIndex{Option}{twoside}% +These two options have the same effect as with the standard classes. +The option \Option{oneside} defines a one-sided document layout with a +one-sided page layout. This means in particular that normally a ragged +page bottom is used. + +The option \Option{twoside} defines a two-sided document layout with a +two-sided page layout. This means that the \LaTeX{} command +\Macro{flushbottom}\IndexCmd{flushbottom} is used to ensure that page +breaks don't leave a variable empty space at the bottom of the page. A +ragged page bottom can be obtained with the \LaTeX{} command +\Macro{raggedbottom}\IndexCmd{raggedbottom}. +% +\EndIndex{Option}{oneside}% +\EndIndex{Option}{twoside}% + + +\begin{Declaration} + \Option{onecolumn}\\ + \Option{twocolumn} +\end{Declaration}% +\BeginIndex{Option}{onecolumn} +\BeginIndex{Option}{twocolumn}% +These options have the same effect as the corresponding standard +options. They are used to switch between a one-column and a two-column +layout. The standard \LaTeX{} capabilities for multi-column layout are +only useful for very simple uses. The standard package +\Package{multicol} is much more versatile (see +\cite{package:multicol}).\Index{columns}\IndexPackage{multicol} +% +\EndIndex{Option}{onecolumn} \EndIndex{Option}{twocolumn} + + +\begin{Declaration} + \Option{openany}\\ + \Option{openright} +\end{Declaration}% +\BeginIndex{Option}{openany}% +\BeginIndex{Option}{openright}% +These\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} options have the +same effect as the corresponding standard options. They affect the +choice of the page where a chapter\Index[indexmain]{chapter} can begin, +so they are not available with the \Class{scrartcl} class, since there +the main unit below ``part'' is the ``section''. The chapter level is +not available in \Class{scrartcl}. + +A chapter always begins with a new page. When the option +\Option{openany} is active, any page can be used. The option +\Option{openright} causes the chapter to begin with a new right page. +An empty left page may be inserted automatically in this case. The +empty pages are created by the implicit execution of the \LaTeX{} +command \Macro{cleardoublepage}\IndexCmd{cleardoublepage}. + +The option \Option{openright} has no effect with a one-sided layout, +because only the two-sided layout differentiates between left and +right pages. For this reason it should only be used together with the +\Option{twoside} option. +% +\EndIndex{Option}{openany} \EndIndex{Option}{openright} + + +\begin{Declaration} + \Option{cleardoublestandard}\\ + \Option{cleardoubleplain}\\ + \Option{cleardoubleempty} +\end{Declaration}% +\BeginIndex{Option}{cleardoublestandard}% +\BeginIndex{Option}{cleardoubleplain}% +\BeginIndex{Option}{cleardoubleempty}% +If one wishes the empty pages created by the \Macro{cleardoublepage} +command to have no headers or footers while using the standard +classes, the only possibility is to redefine the command +appropriately. {\KOMAScript} provides options that avoid this. The +option \Option{cleardoublestandard} enables the default +\Macro{cleardoublepage} behaviour. If the option +\Option{cleardoubleplain} is used, then the +\PValue{plain}\IndexPagestyle{plain} page style is applied to the +empty left page. The option \Option{cleardoubleempty} causes the +\PValue{empty}\IndexPagestyle{empty} page style to be used. The page +styles are described in \autoref{sec:maincls.pageStyle}. +% +\EndIndex{Option}{cleardoublestandard}% +\EndIndex{Option}{cleardoubleplain}% +\EndIndex{Option}{cleardoubleempty}% + + +\begin{Declaration} + \Option{headsepline}\\ + \Option{headnosepline}\\ + \Option{footsepline}\\ + \Option{footnosepline} +\end{Declaration}% +\BeginIndex{Option}{headsepline}% +\BeginIndex{Option}{headnosepline}% +\BeginIndex{Option}{footsepline}% +\BeginIndex{Option}{footnosepline}% +In order to have a line separating the header from the text body use +the option \Option{headsepline}. The option \Option{headnosepline} has +the reverse effect. 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 approximating +header and text body. That doesn't mean that the header must be put +farther apart from the text body. Instead, the header should be +considered to belong to the text body for the purpose of page layout +calculations. {\KOMAScript} takes this into account by automatically +passing the option \Option{headinclude} to the \Package{typearea} +package whenever the \Option{headsepline} option is used. + +The presence of a line between text body and footer is controlled by +the options \Option{footsepline} and \Option{footnosepline}, that +behave like the corresponding header functions. Whenever a line is +requested by the \Option{footsepline} option, the \Option{footinclude} +option is automatically passed to the \Package{typearea} package. In +contrast to \Option{headsepline}, \Option{footsepline} takes effect +when used together with the page style \PValue{plain}, because the +\PValue{plain} style produces a page number in the footer. +% +\EndIndex{Option}{headsepline}% +\EndIndex{Option}{headnosepline}% +\EndIndex{Option}{footsepline}% +\EndIndex{Option}{footnosepline}% + + +\begin{Declaration} + \Option{titlepage}\\ + \Option{notitlepage} +\end{Declaration}% +\BeginIndex{Option}{titlepage}% +\BeginIndex{Option}{notitlepage}% +Both options have the same effect as the corresponding standard ones. +The \Option{titlepage} option makes {\LaTeX} use separate pages for +the titles. These pages are set inside a \Environment{titlepage} +environment and normally have neither header nor footer. In comparison +with standard \LaTeX, \KOMAScript{} expands the handling of the titles +significantly (see \autoref{sec:maincls.titles}). + +The option \Option{notitlepage} specifies that an \emph{in-page} title +is used. This means that the title is specially emphasized, but it may +be followed by more material on the same page, for instance by an +abstract or a section. +% +\EndIndex{Option}{titlepage}% +\EndIndex{Option}{notitlepage}% + + +\begin{Declaration} + \Option{chapterprefix}\\ + \Option{nochapterprefix} +\end{Declaration}% +\BeginIndex{Option}{chapterprefix}% +\BeginIndex{Option}{nochapterprefix}% +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 class option \Option{chapterprefix}. The default however is +\Option{nochapterprefix}. These options also affect the automatic +running titles in the headers (see +\autoref{sec:maincls.pageStyle}). +% +\EndIndex{Option}{chapterprefix}% +\EndIndex{Option}{nochapterprefix}% + + +\begin{Declaration} + \Option{appendixprefix}\\ + \Option{noappendixprefix} +\end{Declaration}% +\BeginIndex{Option}{appendixprefix}% +\BeginIndex{Option}{noappendixprefix}% +Sometimes\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} one wishes to +have the chapter titles in simplified form according to +\Option{nochapterprefix}. 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. Since this results in an inconsistent +document layout, I advise against using this option. + +The reverse option \Option{noappendixprefix} exists only for +completeness' sake. I don't know of any sensible use for it. +% +\EndIndex{Option}{appendixprefix}% +\EndIndex{Option}{noappendixprefix}% + +\begin{Declaration} + \Option{parskip}\\ + \Option{parskip*}\\ + \Option{parskip+}\\ + \Option{parskip-}\\ + \Option{halfparskip}\\ + \Option{halfparskip*}\\ + \Option{halfparskip+}\\ + \Option{halfparskip-}\\ + \Option{parindent} +\end{Declaration}% +\BeginIndex{Option}{parskip}% +\BeginIndex{Option}{parskip*}% +\BeginIndex{Option}{parskip+}% +\BeginIndex{Option}{parskip-}% +\BeginIndex{Option}{halfparskip}% +\BeginIndex{Option}{halfparskip*}% +\BeginIndex{Option}{halfparskip+}% +\BeginIndex{Option}{halfparskip-}% +\BeginIndex{Option}{parindent}% +\begin{Explain}% + The standard classes normally set + paragraphs\Index[indexmain]{paragraph} indented and without any + vertical inter-paragraph space. This is the best solution when + using a regular page layout, like the ones produced with the + \Package{typearea} package. If there where no indentation and no + vertical space, only the length of last line would give the reader a + reference point. In extreme cases, it is very difficult to detect if + a line is full or not. Furthermore, it is found that a marker at the + paragraph's end tends to be easily forgotten. A marker at the + paragraph's beginning is easily remembered. Inter-paragraph spacing + has the drawback of disappearing in some contexts. For instance, + after a displayed formula it would be impossible to detect if the + previous paragraph continues or if a new one begins. Also, when + starting to read at a new page it might be necessary to look at the + previous page in order determine if a new paragraph has been started + or not. All these problems disappear when using indentation. A + combination of indentation and vertical inter-paragraph spacing is + redundant and should be rejected. The + indentation\Index[indexmain]{indentation} is perfectly sufficient by + itself. The only drawback of indentation is the reduction of the + line length. The use of inter-paragraph spacing is therefore + justified when using short lines, for instance in a newspaper. +\end{Explain} + + +Independently of the explanation above, there are often requests for a +document layout with vertical inter-paragraph spacing instead of +indentation. \KOMAScript{} provides a large number of related +options: \Option{parskip}, \Option{parskip-}, \Option{parskip*}, +\Option{parskip+} and \Option{halfparskip}, \Option{halfparskip-}, +\Option{halfparskip*} and \Option{halfparskip+}. + +The four \Option{parskip} options define an inter-paragraph spacing of +one line. The four \Option{halfparskip} options use just a spacing of +half a line. In order to avoid a change of paragraph going unnoticed, +for instance after a page break, three of the options of each set +ensure that the last line of a paragraph is not full. The variants +without plus or star sign ensure a free space of 1\Unit{em}. The plus +variant ensures that at least a third of the line is free and the star +variant ensures that at least a fourth of the line is free. The minus +variants make no special provision for the last line of a paragraph. + +All eight options change the spacing before, after and inside list +environments. This avoids the problem of having these environments or +the paragraphs inside them with a larger separation than the +separation between the paragraphs of normal text. Additionally, these +options ensure that the table of contents and the lists of figures and +tables are set without any additional spacing. + +The default behaviour of \KOMAScript{} follows the \Option{parindent} +option. In this case, there is no spacing between paragraphs, only an +indentation of the first line by 1\Unit{em}. +% +\EndIndex{Option}{parskip}% +\EndIndex{Option}{parskip*}% +\EndIndex{Option}{parskip+}% +\EndIndex{Option}{parskip-}% +\EndIndex{Option}{halfparskip}% +\EndIndex{Option}{halfparskip*}% +\EndIndex{Option}{halfparskip+}% +\EndIndex{Option}{halfparskip-}% +\EndIndex{Option}{parindent}% + +\begin{Declaration} + \Option{onelinecaption}\\ + \Option{noonelinecaption} +\end{Declaration} +\BeginIndex{Option}{onelinecaption}% +The standard classes differentiate between one-line and multi-line +table or figure captions. One-line captions are centered while +multi-line captions are left-justified. This behavior, which is also +the default with \KOMAScript, corresponds to the option +\Option{onelinecaption}. There is no special handling of one-line +captions when the \Option{noonelinecaption} option is given. + +\begin{Explain} + The avoidance of a special treatment for the caption has an + additional effect that is sometimes greatly desired. Footnotes + that appear inside a \Macro{caption} command often have a wrong + number assigned to them. This happens because the footnote counter + is incremented once when the line is measured. When the + \Option{noonelinecaption} option is used no such measurement is + made. The footnote numbers are therefore correct. + + But since \KOMAScript{} version 2.9 you don't need the option + \Option{noonelinecaption} to avoid the above described + effect. \KOMAScript{} classes contain a workaround, so if you have + footnotes at captions you simply should put the contents of the + figure or table into a minipage and everything will be nice. +\end{Explain} +% +\EndIndex{Option}{onelinecaption}% +\EndIndex{Option}{noonelinecaption}% + +\subsection{Options for Font Selection} +\label{sec:maincls.fontOptions} + +Font options are those options that affect the font size of the +document or the fonts of individual elements. Options that affect the +font style are also theoretically font options. However {\KOMAScript} +currently has no such options. + +\begin{Declaration} + \Option{10pt}\\% + \Option{11pt}\\% + \Option{12pt}\\ + \Option{\Var{X}pt} +\end{Declaration}% +\BeginIndex{Option}{10pt}% +\BeginIndex{Option}{11pt}% +\BeginIndex{Option}{12pt}% +\BeginIndex{Option}{\Var{X}pt}% +The options \Option{10pt}, \Option{11pt} and \Option{12pt} have the +same effect as the corresponding standard options. In contrast to the +standard classes, {\KOMAScript} can be used to choose other font +sizes\Index[indexmain]{font size}. However {\LaTeX} provides the +necessary class option files only for 10\Unit{pt}, 11\Unit{pt} und +12\Unit{pt}, so that the user must provide any other class option +files. The package \Package{extsizes} (see +\cite{package:extsizes})\IndexPackage{extsizes} can be used for that +task. Very big font sizes may lead to arithmetic overflow inside the +page layout calculations of the \Package{typearea} package. +% +\EndIndex{Option}{10pt}% +\EndIndex{Option}{11pt}% +\EndIndex{Option}{12pt}% +\EndIndex{Option}{\Var{X}pt}% + + +\begin{Declaration} + \Option{smallheadings}\\ + \Option{normalheadings}\\ + \Option{bigheadings} +\end{Declaration}% +\BeginIndex{Option}{smallheadings}% +\BeginIndex{Option}{normalheadings}% +\BeginIndex{Option}{bigheadings}% +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 +specially problematic for small paper sizes. Consequently +{\KOMAScript} provides, besides the large title font size defined by +the \Option{bigheadings} option, the two options +\Option{normalheadings} and \Option{smallheadings}, that allow for +smaller title font sizes. +\OnlyAt{\Class{scrbook}\and\Class{scrreprt}}The spacing before and +after chapter titles is also influenced by these options. Chapter +titles are also influenced by the options \Option{chapterprefix} and +\Option{nochapterprefix}, and appendix titles by the options +\Option{appendixprefix} and \Option{noappendixprefix}, all of them +are described in \autoref{sec:maincls.layoutOptions}. +% +\EndIndex{Option}{smallheadings}% +\EndIndex{Option}{normalheadings}% +\EndIndex{Option}{bigheadings}% + +\subsection{Options Affecting the Table of Contents} +\label{sec:maincls.tocOptions} + +{\KOMAScript} has several options that affect the entries in the table +of contents\Index[indexmain]{table of contents}. The form of the table +of contents is fixed but several variations of the contents can be +obtained with the options provided. + +\begin{Declaration} + \Option{liststotoc}\\ + \Option{idxtotoc}\\ + \Option{bibtotoc}\\ + \Option{bibtotocnumbered}\\ + \Option{liststotocnumbered} +\end{Declaration}% +\BeginIndex{Option}{liststotoc}% +\BeginIndex{Option}{idxtotoc}% +\BeginIndex{Option}{bibtotoc}% +\BeginIndex{Option}{bibtotocnumbered}% +\BeginIndex{Option}{liststotocnumbered}% +\begin{Explain}% + Lists of tables and figures, index and bibliography are not normally + included in the table of contents. These entries are omitted in + classical typography because it is silently assumed that, if at all, + lists of figures and tables come after the table of contents, the + index comes at the end and the bibliography comes before the index. + Books with all these parts often include ribbons that can be used to + mark the location of these parts in the book, so that the reader + only has to look for them once. +\end{Explain} + +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 certainly 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 it makes no sense to include only one of the aforementioned lists +in the table of contents, there exists only one option +\Option{liststotoc} 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}). All these lists are unnumbered, since they +contain entries that reference other sections of the document. + +The option \Option{idxtotoc} causes an entry for the index to be +included in the table of contents. The index is also unnumbered since +it only includes references to the contents of the other sectional +units. + +The bibliography is a different kind of listing. It does not list the +contents of the present document but refers instead to external +documents. On these reasons it could be argued that it is a different +chapter (or section) and, as such, should be numbered. The option +\Option{bibtotocnumbered} has this effect, including the generation of +the corresponding entry in the table of contents. I think that a +similar reasoning would lead us to consider a classical list of +sources to be a separate chapter. Also, the bibliography is not +something that was written by the document's author. In view of this, +the bibliography merits nothing more than an unnumbered entry in the +table of contents, and that can be achieved with the \Option{bibtotoc} +option. + +The author of \KOMAScript{} doesn't like option +\Option{bibtotocnumbered}. He almost detests option +\Option{liststotocnumbered}. Because of this you won't find a detailed +description of this option. Nevertheless it exists. +% +\EndIndex{Option}{liststotoc}% +\EndIndex{Option}{idxtotoc}% +\EndIndex{Option}{bibtotoc}% +\EndIndex{Option}{bibtotocnumbered}% +\EndIndex{Option}{liststotocnumbered}% + + +\begin{Declaration} + \Option{tocindent}\\ + \Option{tocleft} +\end{Declaration}% +\BeginIndex{Option}{tocindent}% +\BeginIndex{Option}{tocleft}% +The table of contents is normally\ChangedAt{v2.8q}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} setup so +that different sectional units have different indentations. The +section number is set left-justified in a fixed-width field. This +setup is selected with the option \Option{tocindent}. + +When there are many sections, the corresponding numbering tends to +become very wide, so that the reserved field overflows. The FAQ +\cite{DANTE:FAQ} suggests that the table of contents should be redefined +in such a case. \KOMAScript{} offers an alternative format that avoids +the problem completely. If the option \Option{tocleft} 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 determined automatically. + +\begin{Explain} + In order to calculate automatically the space taken by the unit + numbers when using the option \Option{tocleft} it is necessary to + redefine some macros. It is improbable but not impossible that this + leads to problems when using other packages. If you think this may + be causing problems, you should try the alternative option + \Option{tocindent}, since it does not make any redefinitions. When + using packages that affect the format of the table of contents, it + is possible that the use of options \Option{tocleft} and + \Option{tocindent} may lead to problems. In that case, one should + use neither of these global (class) option. + + If the \Option{tocleft} option is active, the width of the field for + unit numbering is determined when outputting the table of contents. + After a change that affects the table of contents, at most three + \LaTeX{} runs are necessary to obtain a correctly set table of + contents. +\end{Explain} +% +\EndIndex{Option}{tocindent}% +\EndIndex{Option}{tocleft}% + +\subsection{Options for Lists of Floats} +\label{sec:maincls.listsOptions} + +The best known lists of floats are the list of figures and the list of tables. +With help from the \Package{float}\IndexPackage{float} package, for instance, +it is possible to produce new float environments with the corresponding lists. + +\begin{Explain} + Whether \KOMAScript{} options have any effect on lists of floats + produced by other packages depends mainly on those packages. This is + generally the case with the lists of floats produced by the + \Package{float}\IndexPackage{float} package. + + Besides the options described here, there are others that affect the + lists of floats though not their formatting or contents. Instead + they affect what is included in the table of contents. The + corresponding descriptions can therefore be found in + \autoref{sec:maincls.tocOptions}. +\end{Explain} + +\begin{Declaration} + \Option{listsindent}\\ + \Option{listsleft} +\end{Declaration}% +\BeginIndex{Option}{listsindent}% +\BeginIndex{Option}{listsleft}% +Lists of figures and tables\ChangedAt{v2.8q}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} are +generally setup so that their numbering uses a fixed space. This +corresponds to the use of option \Option{listsindent}. + +If the numbers get too large, for instance because many tables are +used, it may happen that the available space is exceeded. Therefore +\KOMAScript{} supplies an option called \Option{listsleft} that is +similar to the \Option{tocleft} option. The width of the numbers is +automatically determined and the space for them correspondingly +adjusted. Concerning the mode of operation and the side effects, the +observations made in \autoref{sec:maincls.tocOptions} for the +\Option{tocleft} option are equally valid in this case. Please note +that when using the \Option{listsleft} option several \LaTeX{} runs +are necessary before the lists of floats achieve their final form. +% +\EndIndex{Option}{listsindent}% +\EndIndex{Option}{listsleft}% + + + +\subsection{Options Affecting the Formatting} +\label{sec:maincls.formattingOptions} + +Formatting options are all those options that affect the form or +formatting of the document and are not assigned to other sections. +They are the \emph{remaining options}. + +\begin{Declaration} + \Option{abstracton}\\ + \Option{abstractoff} +\end{Declaration}% +\BeginIndex{Option}{abstracton}% +\BeginIndex{Option}{abstractoff}% +In\OnlyAt{\Class{scrreprt}\and\Class{scrartcl}} the standard classes +the \Environment{abstract} environment sets the text "\abstractname" +centered before the summary text\Index[indexmain]{summary}. This was the +normal procedure in the past. In the meantime, newspaper reading has +trained the readers to recognize a displayed text at the beginning of +an article or report as the abstract. This is even more so when the +abstract comes before the table of contents. It is also surprising +that precisely this title appears small and centered. {\KOMAScript} +provides the possibility of including or excluding the abstract's +title with the options \Option{abstracton} and \Option{abstractoff}. + +\begin{Explain} + 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 with a + description of further aspects. Therefore, the class \Class{scrbook} + has no \Environment{abstract} environment. A summary chapter is also + recommended for reports in a wider sense, like a Master's or Ph.D. + thesis. +\end{Explain} +% +\EndIndex{Option}{abstracton}% +\EndIndex{Option}{abstractoff}% + + +\begin{Declaration} + \Option{pointednumbers}\\ + \Option{pointlessnumbers} +\end{Declaration}% +\BeginIndex{Option}{pointednumbers}% +\BeginIndex{Option}{pointlessnumbers}% +\begin{Explain}% + According to {\small DUDEN}, the numbering of sectional units should + have no point at the end if only arabic numbers are used (see + \cite[R\,3]{DUDEN}). On the other hand, if roman numerals or letters + are used, then a point should appear at the end of the numbering (see + \cite[R\,4]{DUDEN}). {\KOMAScript} has an internal mechanisms that + tries to implement these rules. The resulting effect is that, + normally, after the sectional commands \Macro{part} and + \Macro{appendix} a switch is made to numbering with a point at the + end. The information is saved in the \File{aux} file and takes + effect on the next \LaTeX{} run. +\end{Explain} + +In some cases the mechanism that switches the end point may fail or +other languagues may have different rules. Therefore it is possible to +activate the use of the end point with the option +\Option{pointednumbers} or to deactivate it with +\Option{pointlessnumbers}. + +Please note that the mechanism only takes effect on the next \LaTeX{} +run. When trying to use these options to control the numbering +format, a run without changing any options should be made. + +Calling these options +\Option{dottednumbers}\IndexOption{dottednumbers} and +\Option{dotlessnumbers}\IndexOption{dotlessnumbers} or similar would +be more correct. It so happened that the meaning of the chosen names +was not clear to me a few years ago when the options were implemented. +% +\EndIndex{Option}{pointednumbers}% +\EndIndex{Option}{pointlessnumbers}% + +\begin{Declaration} + \Option{leqno} +\end{Declaration}% +\BeginIndex{Option}{leqno}% +Equations\Index{equation} are normally numbered 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. +% +\EndIndex{Option}{leqno}% + + +\begin{Declaration} + \Option{fleqn} +\end{Declaration}% +\BeginIndex{Option}{fleqn}% +Displayed equations 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. +% +\EndIndex{Option}{fleqn}% + +\begin{Declaration} + \Option{tablecaptionbelow}\\ + \Option{tablecaptionabove} +\end{Declaration}% +\BeginIndex{Option}{tablecaptionbelow}% +\BeginIndex{Option}{tablecaptionabove}% +As described in \autoref{sec:maincls.floats}, the +\Macro{caption}\IndexCmd{caption} command acts with figures like the +\Macro{captionbelow}\IndexCmd{captionbelow} command. The behaviour +with tables depends on two options. With the default +\Option{tablecaptionbelow} options, the \Macro{caption} macro acts +like the \Macro{captionbelow} command. With the +\Option{tablecaptionabove} option, \Macro{caption} acts like the +\Macro{captionabove}\IndexCmd{captionabove} command. + +Note\OnlyAt{\Package{float}}\IndexPackage{float} that when using +the \Package{float} package, the options \Option{tablecaptionbelow} +and \Option{tablecaptionabove} cease to act correctly when the +\Macro{refloatstyle} is applied to tables. More details of the +\Package{float} package's \Macro{refloatstyle} can be obtained from +\cite{package:float}. +% +\EndIndex{Option}{tablecaptionbelow}% +\EndIndex{Option}{tablecaptionabove}% + + +\begin{Declaration} + \Option{origlongtable} +\end{Declaration}% +\BeginIndex{Option}{origlongtable}% +\begin{Explain}% + The package\OnlyAt{\Package{longtable}} + \Package{longtable}\IndexPackage{longtable} (see + \cite{package:longtable}) sets table captions internally by calling + the command \Macro{LT@makecaption}. In order to ensure that these + table captions match the ones used with normal tables, the + \KOMAScript{} classes normally redefine that command. See + \autoref{sec:maincls.floats} for more details. The redefinition + is performed with help of the command \Macro{AfterPackage} + immediately after the loading of package \Package{longtable}. If + the package \Package{caption2}\IndexPackage{caption2} (see + \cite{package:caption2}) has been previously loaded, the + redefinition is not made in order not to interfere with the + \Package{caption2} package. +\end{Explain} +If the table captions produced by the \Package{longtable} package +should not be redefined by the \KOMAScript{}, activate the +\Option{origlongtable} option. +% +\EndIndex{Option}{origlongtable}% + + +\begin{Declaration} + \Option{openbib} +\end{Declaration}% +\BeginIndex{Option}{openbib}% +The standard option \Option{openbib} switches to an alternative +bibliography format. The effects are twofold: The first line of a +bibliography entry, normally containing the author's name, gets a +smaller indentation; and the command \Macro{newblock} is redefined to +produce a paragraph. Without this option, \Macro{newblock} introduces +only a stretchable horizontal space. +% +\EndIndex{Option}{openbib} + + +\begin{Declaration} + \Option{draft}\\ + \Option{final} +\end{Declaration}% +\BeginIndex{Option}{draft}% +\BeginIndex{Option}{final}% +The two standard options \Option{draft} and \Option{final} are +normally used to distinguish between the draft and final versions of a +document. The option \Option{draft} activates small black boxes that +are set at the end of overly long lines. The boxes help the untrained +eye to find paragraphs that have to be treated manually. With the +\Option{final} option no such boxes are shown. + +The two options are also processed by other packages and affect their +workings. For instance, the \Package{graphics}\IndexPackage{graphics} +and the \Package{graphicx}\IndexPackage{graphicx} packages don't +actually output the graphics when the option \Option{draft} is +specified. Instead they output a framed box of the appropriate size +containing only the graphic's filename (see \cite{package:graphics}). +% +\EndIndex{Option}{draft}% +\EndIndex{Option}{final}% + + +\section{General Document Characteristics} +\label{sec:maincls.general} + +Some document characteristics do not apply to a particular section of +the document like the titling, the text body or the bibliography, but +they affect the entire document. Some of these characteristics were +already described in \autoref{sec:maincls.options}. + +\subsection{Changing Fonts} +\label{sec:maincls.font} + +\BeginIndex{}{font}\BeginIndex{}{font size}% +\begin{Explain} + \KOMAScript{} does not use fixed fonts and attributes to emphasize + different elements of the text. Instead there are variables + that contain the commands used for changing fonts and other text + attributes. In previous versions of \KOMAScript{} the user had to + use \Macro{renewcommand} to redefine those variables. It was also + not easy to determine the name of the variable affecting an element + given the element's name. It was also often necessary to determine + the original definition before proceeding to redefine it. + + These difficulties were actually intended, since the interface was not + for users, but only for package authors building their + packages on top of \KOMAScript{}. The years have shown that the + interface was mainly used by document authors. So a new, simpler + interface was created. However, the author advises explicitly the + typographically inexperienced user against changing font sizes and + other graphical characteristics according to his taste. Knowledge + and feeling are basic conditions for the selection and mixture of + different font sizes, attributes and families. +\end{Explain} + +\begin{Declaration} + \Macro{setkomafont}\Parameter{element}\Parameter{commands}\\ + \Macro{addtokomafont}\Parameter{element}\Parameter{commands}\\ + \Macro{usekomafont}\Parameter{element} +\end{Declaration}% +\BeginIndex{Cmd}{setkomafont}% +\BeginIndex{Cmd}{addtokomafont}% +\BeginIndex{Cmd}{usekomafont}% +With\ChangedAt{v2.8p}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} the help of the two commands \Macro{setkomafont} +and \Macro{addtokomafont} it is possible to define the +\PName{commands} that change the characteristics of a given +\PName{element}. Theoretically all possible statements including +literal text could be used as \PName{commands}. You should however +absolutely limit yourself to those statements that really switch only +one font attribute. This are usually the commands \Macro{normalfont}, +\Macro{rmfamily}, \Macro{sffamily}, \Macro{ttfamily}, +\Macro{mdseries}, \Macro{bfseries}, \Macro{upshape}, \Macro{itshape}, +\Macro{slshape}, \Macro{scshape} and the font size commands +\Macro{Huge}, \Macro{huge}, \Macro{LARGE} etc. The description of +these commands can be found in \cite{lshort}, \cite{latex:usrguide} or +\cite{latex:fntguide}. Color switching commands like +\Macro{normalcolor} (see \cite{package:graphics}) are also acceptable. +The behavior when using other commands, specially those that make +redefinitions or generate output, is not defined. Strange behavior is +possible and does not represent a bug. + + +The command \Macro{setkomafont } provides a font switching command +with a completely new definition. In contrast to this the +\Macro{addtokomafont} commands extends the existing definition. + +It is not recommended to use both statements in the same +document. Usage examples can be found in the paragraphs on the +corresponding element. Names and meanings of the individual items are +listed in \autoref{tab:maincls.elementsWithoutText}. The default +values are shown in the corresponding paragraphs. +% +% Mit tabularx.sty oder array.sty waere folgende Tabelle viel +% einfacher zu loesen: +\begin{table} + \centering% + \begin{tabular}{lp{.6\linewidth}} + Element & Description \\\hline\\[-2ex] + \FontElement{caption}\IndexFontElement[indexmain]{caption} + & \raggedright Text of a table or figure caption\tabularnewline%[.75ex] + \FontElement{captionlabel}\IndexFontElement[indexmain]{captionlabel} + & \raggedright Label of a table or figure caption; used according + to the element \FontElement{caption}\tabularnewline%[.75ex] + \FontElement{chapter}\IndexFontElement[indexmain]{chapter} + & \raggedright Title of the sectional unit + \Macro{chapter} \tabularnewline%[.75ex] + \FontElement{descriptionlabel}% + \IndexFontElement[indexmain]{descriptionlabel} + & \raggedright Labels, i.e. the optional + argument of \Macro{item}, in the + \Environment{description} environment\tabularnewline%[.75ex] + \FontElement{dictumauthor}\IndexFontElement[indexmain]{dictumauthor} + & \raggedright Author of a smart saying; used according + to the element \FontElement{dictumtext}\tabularnewline%[.75ex] + \FontElement{dictumtext}\IndexFontElement[indexmain]{dictumtext} + & \raggedright Text of a smart saing (see command + \Macro{dictum}) \tabularnewline%[.75ex] + \FontElement{pagefoot}\IndexFontElement[indexmain]{pagefoot} + & \raggedright The foot of a page, but also the head of a page + \tabularnewline%[.75ex] + \FontElement{footnote}\IndexFontElement[indexmain]{footnote} + & \raggedright Footnote text and marker \tabularnewline%[.75ex] + \FontElement{footnotelabel}\IndexFontElement[indexmain]{footnotelabel} + & \raggedright Mark of a footnote; used according to the + element \FontElement{footnote}\tabularnewline%[.75ex] + \FontElement{footnotereference}% + \IndexFontElement[indexmain]{footnotereference} + & Footnote reference in the text \tabularnewline%[.75ex] + \FontElement{pagehead}\IndexFontElement[indexmain]{pagehead} + & \raggedright The head of a page, but also the foot of a page + \tabularnewline%[.75ex] + \FontElement{pagenumber}\IndexFontElement[indexmain]{pagenumber} + & \raggedright Page number in the header or footer + \tabularnewline%[.75ex] + \FontElement{paragraph}\IndexFontElement[indexmain]{paragraph} + & \raggedright Title of the sectional unit + \Macro{paragraph} \tabularnewline%[.75ex] + \FontElement{part}\IndexFontElement[indexmain]{part} + & \raggedright Title of the \Macro{part} sectional unit, without + the line with the part number\tabularnewline%[.75ex] + \FontElement{partnumber}\IndexFontElement[indexmain]{partnumber} + & \raggedright Line with the part number in a title of the + sectional unit \Macro{part} + \tabularnewline%[.75ex] + \FontElement{section}\IndexFontElement[indexmain]{section} + & \raggedright Title of the sectional unit + \Macro{section} \tabularnewline%[.75ex] + \FontElement{sectioning}\IndexFontElement[indexmain]{sectioning} + & \raggedright All sectional unit titles, i.e. the arguments of + \Macro{part} down to \Macro{subparagraph} and + \Macro{minisec}, including the title of the abstract; used before + the element of the corresponding unit + \tabularnewline%[.75ex] + \FontElement{subparagraph}\IndexFontElement[indexmain]{subparagraph} + & \raggedright Title of the sectional unit + \Macro{subparagraph} \tabularnewline%[.75ex] + \FontElement{subsection}\IndexFontElement[indexmain]{subsection} + & \raggedright Title of the sectional unit + \Macro{subsection} \tabularnewline%[.75ex] + \FontElement{subsubsection}\IndexFontElement[indexmain]{subsubsection} + & \raggedright Title of the sectional unit + \Macro{subsubsection} \tabularnewline%[.75ex] + \FontElement{title}\IndexFontElement[indexmain]{title} + & \raggedright Main title of the document, i.e. the argument + of \Macro{title} \tabularnewline%[.75ex] + \end{tabular} + \caption{Elements, whose type style can be + changed with the {\KOMAScript} command \Macro{setkomafont} or + \Macro{addtokomafont}} + \label{tab:maincls.elementsWithoutText} +\end{table} + +The command \Macro{usekomafont} can change the current font +specification to the one used with the specified \PName{element}. +\begin{Example} + Assume that you want to use for the element + \FontElement{captionlabel} the same font specification that is used + with \FontElement{descriptionlabel}. This can be easily done with: + \begin{small} +\begin{verbatim} + \setkomafont{captionlabel}{\usekomafont{descriptionlabel}} +\end{verbatim} + \end{small} + You can find other examples in the paragraphs on each element. +\end{Example} +% +\EndIndex{Cmd}{setkomafont}% +\EndIndex{Cmd}{addtokomafont}% +\EndIndex{Cmd}{usekomafont}% +\EndIndex{}{font}\EndIndex{}{font size}% + +\subsection{Page Style} +\label{sec:maincls.pageStyle} + +\begin{Declaration} + \Macro{pagestyle}\PParameter{empty}\\ + \Macro{pagestyle}\PParameter{plain}\\ + \Macro{pagestyle}\PParameter{headings}\\ + \Macro{pagestyle}\PParameter{myheadings}\\ + \Macro{thispagestyle}\Parameter{local page style} +\end{Declaration}% +\BeginIndex{Cmd}{pagestyle}% +\BeginIndex{Cmd}{thispagestyle}% +\BeginIndex{Pagestyle}{empty}% +\BeginIndex{Pagestyle}{plain}% +\BeginIndex{Pagestyle}{headings}% +\BeginIndex{Pagestyle}{myheadings}% +One of the general characteristics of a document is the page +style\Index[indexmain]{page style}. In {\LaTeX} this means mostly the +contents of headers and footers. Usually one distinguishes four +different page styles. +\begin{description} +\item[empty] is the page style with entirely empty headers and + footers. In {\KOMAScript} this is completely identical to the + standard classes. +\item [plain] is the page style with empty head and only a page number + in the foot. With the standard classes this page number is + always centered in the foot. With {\KOMAScript} the page number + appears on double-sided\Index {double-sided} layout on the outer + side of the foot. The one-sided page style behaves like the + standard setup. +\item[headings] is the page style with running titles in the head. + With the classes \Class{scrbook}\IndexClass{scrbook} and + \Class{scrreprt}\IndexClass{scrreprt} the titles of chapters and + sections are repeated in the head -- with {\KOMAScript} on the outer + side, with the standard classes on the inner side. The page number + comes with {\KOMAScript} on the outer side of the foot, with the + standard classes it comes on the inner side of the head. In + one-sided layouts only the headings of the chapters are used and + are, with {\KOMAScript}, centered in the head. The page numbers are + set with {\KOMAScript} centered in the foot. + \OnlyAt{\Class{scrartcl}}\Class{scrartcl}\IndexClass{scrartcl} + behaves similarly, but starting a level deeper in the section + 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 + too strong. If one applies them nevertheless, they should be set + with a smaller type size and tighter spacing. The standard classes + don't take these points in consideration. +\item [myheadings] corresponds mostly to the page style + \PValue{headings}, but the running headings s are not automatically + produced, but have to be defined by the user. The commands \Macro + {markboth}\IndexCmd{markboth} and + \Macro{markright}\IndexCmd{markright} can be used for that purpose. +\end{description} +Besides, the form of the page styles \PValue{headings} and +\PValue{myheadings} is affected by each of the four class options +\Option{headsepline}, \Option{headnosepline}, \Option{footsepline} and +\Option {footnosepline} (see \autoref{sec:maincls.layoutOptions}). +The page style starting with the current page is changed by the +command \Macro{pagestyle}. On the other hand \Macro{thispagestyle} +changes only the style of the current page. + +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. Usually one sets the page style only once at the beginning of the +document or in the preamble. To change the page style of the current +page one uses the \Macro{thispagestyle} command. This also happens at +some places in the document automatically. For example, the +instruction \Macro{thispagestyle}\PParameter{plain} is issued +implicitly on the first page of a chapter. + +Please note that the change between automatic and manual running +headings is not performed by page style changes when using the +\Package{scrpage2} package, but instead special instructions must be +used. The page styles \PValue{headings} and \PValue{myheadings} should +not be used together with this package (see +\autoref{cha:scrpage}). +% +\EndIndex{Cmd}{pagestyle}% +\EndIndex{Cmd}{thispagestyle}% +\EndIndex{Pagestyle}{empty}% +\EndIndex{Pagestyle}{plain}% +\EndIndex{Pagestyle}{headings}% +\EndIndex{Pagestyle}{myheadings}% + +\BeginIndex[indexother]{}{type style}% +In order to change the type style used in the head, foot or for the +page number\ChangedAt{v2.8p}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}}% +, please use the interface described in +\autoref{sec:maincls.font}. The same element is used for head and +foot, which you can designate equivalently with +\FontElement{pagehead}\IndexFontElement{pagehead} or +\FontElement{pagefoot}\IndexFontElement{pagefoot}. The element for +the page number within the head or foot is called +\FontElement{pagenumber}\IndexFontElement{pagenumber}. The default +settings can be found in \autoref{tab:maincls.defaultFontsHeadFoot}. +% +% +\begin{table} + \centering% + \begin{tabular}{ll} + Element & Default value \\\hline\\[-1.75ex] + \FontElement{pagefoot}\IndexFontElement{pagefoot} & + \Macro{normalfont}\Macro{normalcolor}\Macro{slshape} \\ + \FontElement{pagehead}\IndexFontElement{pagehead} & + \Macro{normalfont}\Macro{normalcolor}\Macro{slshape} \\ + \FontElement{pagenumber}\IndexFontElement{pagenumber} & + \Macro{normalfont}\Macro{normalcolor}\\ + \end{tabular} + \caption{Default values for the elements of a page style} + \label{tab:maincls.defaultFontsHeadFoot} +\end{table} +% +\begin{Example} + Assume that you want to set head and foot 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 horribly, + you can reach this as follows: + \begin{small} +\begin{verbatim} + \setkomafont{pagehead}{\normalfont\normalcolor\itshape% + \small} + \setkomafont{pagenumber}{\normalfont\bfseries} +\end{verbatim} + \end{small} + 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: + \begin{small} +\begin{verbatim} + \addtokomafont{pagefoot}{\small} +\end{verbatim} + \end{small} + As you can see, the last example uses the element + \FontElement{pagefoot}. You can achieve the same result using + \PValue{pagehead} instead (see + \autoref{tab:maincls.elementsWithoutText} on + \autopageref{tab:maincls.elementsWithoutText}). +\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{scrpage2} package (see \autoref{cha:scrpage}). + +If you define your own page styles, the commands +\Macro{usekomafont}\PParameter{pagehead} and +\Macro{usekomafont}\PParameter {pagenumber} can find a meaningful use. +If you use for that not the \KOMAScript{} package \Package{scrpage2} +(see \autoref{cha:scrpage}), 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. If +you do not use these commands in your own definitions, changes like +those shown in the previous examples have no effect. The packages +\Package{scrpage}\IndexPackage{scrpage} and +\Package{scrpage2}\IndexPackage {scrpage2} take care to keep the +maximum possible compatibility with other packages. +% +\EndIndex[indexother]{}{type style}% + + +\begin{Declaration} + \Macro{titlepagestyle}\\ + \Macro{partpagestyle}\\ + \Macro{chapterpagestyle}\\ + \Macro{indexpagestyle} +\end{Declaration}% +\BeginIndex{Cmd}{titlepagestyle}% +\BeginIndex{Cmd}{partpagestyle}% +\BeginIndex{Cmd}{chapterpagestyle}% +\BeginIndex{Cmd}{indexpagestyle}% +For some pages a different page style is chosen with the help of the +command \Macro{thispagestyle}. Which page style this actually is, is +defined by these four macros. The default values for all four cases is +\PValue{plain}. The meaning of these macros can be taken from the +following list: +\begin{labeling}[~--]{\Macro{chapterpagestyle}} +\item[\Macro{titlepagestyle}] Page style for a title page when using + \emph{in-page} titles. +\item[\Macro{partpagestyle}] Page style for the pages with + \Macro{part} titles. +\item[\Macro{chapterpagestyle}] + \OnlyAt{\Class{scrbook}\and\Class{scrreprt}} Page style for the + first page of a chapter. +\item[\Macro{indexpagestyle}] Page style for the first page of the index. +\end{labeling} + +The page styles can be redefined with the \Macro{renewcommand} macro. + +\begin{Example} + Assume that you want the pages with a \Macro{part} heading to have + no number. Then you can use the following command, for example in + the preamble of your document: + \begin{small} +\begin{verbatim} + \renewcommand*{\partpagestyle}{empty} +\end{verbatim} + \end{small} + As mentioned previously, 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{scrpage2} (see + \autoref{cha: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: + \begin{small} +\begin{verbatim} + \renewcommand*{\chapterpagestyle}{chapter} +\end{verbatim} + \end{small} + + Assume that you want that the 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: + \begin{small} +\begin{verbatim} + \clearpage + \pagestyle{empty} + \renewcommand*{\chapterpagestyle}{empty} + \tableofcontents + \clearpage + \pagestyle{headings} + \renewcommand*{\chapterpagestyle}{plain} +\end{verbatim} + \end{small} + + The redefinition of the other page styles is done in the same way. +\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 +\begin{verbatim} + \renewcommand*{\chapterpagestyle}{headings} +\end{verbatim} + will be surprised at the results. + For sure, the page style \PValue{headings} is thereby applied to the + initial page of a chapter. But nevertheless no running headings appear + when using the \Option{openright} option. + The reason for this behaviour can be found in the \LaTeX{} + core. There, the command \Macro{rightmark}, that generates the marks + for right-hand pages, is defined with; +\begin{verbatim} + \let\@rightmark\@secondoftwo + \def\rightmark{\expandafter\@rightmark\firstmark\@empty\@empty} +\end{verbatim} + The right-hand mark is set with \Macro{firstmark}. \Macro{firstmark} + contains the left-hand and right-hand marks that were first set + for a page. Within \Macro{chapter}, \Macro{markboth} is used to set + the left mark to the chapter header and the right mark to empty. + Hence, the first right + mark on a chapter beginning with a right-hand page is empty. Therefore, + the running heading is also empty on those pages. + + You could redefine \Macro{rightmark} in the preamble so that the + last mark on the page is used instead of the first: +\begin{verbatim} + \makeatother + \renewcommand*{\rightmark}{% + \expandafter\@rightmark\botmark\@empty\@empty} + \makeatletter +\end{verbatim} + This would however cause the running heading of the first page of a + chapter to use the title of the last section in the page. This is + confusing and should be avoided. + + It is also confusing (and hence should be avoided) to have as + running heading of the first page of a chapter the chapter title + instead of the the section title. Therefore, the current behavior + should be considered to be correct. +\end{Explain} +% +\EndIndex{Cmd}{titlepagestyle}% +\EndIndex{Cmd}{partpagestyle}% +\EndIndex{Cmd}{chapterpagestyle}% +\EndIndex{Cmd}{indexpagestyle}% + + +\begin{Declaration} + \Macro{clearpage}\\ + \Macro{cleardoublepage}\\ + \Macro{cleardoublestandardpage}\\ + \Macro{cleardoubleplainpage}\\ + \Macro{cleardoubleemptypage} +\end{Declaration}% +\BeginIndex{Cmd}{clearpage}% +\BeginIndex{Cmd}{cleardoublepage}% +\BeginIndex{Cmd}{cleardoublestandardpage}% +\BeginIndex{Cmd}{cleardoubleplainpage}% +\BeginIndex{Cmd}{cleardoubleemptypage}% +The \LaTeX{} core contains the \Macro{clearpage} command, which takes +care of the fact that all floats that have not yet been output and +starts a new page. There exists the instruction +\Macro{cleardoublepage} which works like \Macro{clearpage} but that, +in the double-sided layouts (see layout option \Option{twoside} in +\autoref{sec:maincls.layoutOptions}) starts a new right-hand page. +An empty left page in the current page style is output if necessary. + +With \Macro{cleardoublestandardpage} \KOMAScript{} works as described +above. The \Macro{cleardoubleplainpage} command changes the page +style of the empty left page to \PValue{plain} in order to suppress +the running heading. Analogously, the page style \PValue{empty} is +applied to the empty page with \Macro{cleardoubleemptypage}, +suppressing the page number as well as the runnning title. The page is +thus entirely empty. However, the approach used by +\Macro{cleardoublepage} is dependent on the layout options +\Option{cleardoublestandard}, \Option{cleardoubleplain} and +\Option{cleardoubleempty} described in +\autoref{sec:maincls.layoutOptions} and acts according to the +active option. +% +\EndIndex{Cmd}{clearpage}% +\EndIndex{Cmd}{cleardoublepage}% +\EndIndex{Cmd}{cleardoublestandardpage}% +\EndIndex{Cmd}{cleardoubleplainpage}% +\EndIndex{Cmd}{cleardoubleemptypage}% + + +\begin{Declaration} + \Macro{ifthispageodd}\Parameter{true}\Parameter{false} +\end{Declaration}% +\BeginIndex{Cmd}{ifthispageodd}% +\begin{Explain}% + A peculiarity of \LaTeX{} consists in the fact that it is not + possible to determine on which page the current text will fall. It + is also difficult to say whether the current page has an odd or an + even page number. Now some will argue that there is, nevertheless, + the \TeX test macro \Macro{ifodd} which one needs only to apply to + the current page counter. However, this is an error. At the time of + the evaluation of such a test \LaTeX{} does not know at all whether + the text just processed will be typeset on the current page or only + on the next. The page breaks take place not while reading the paragraph, + but only in the \emph{output} routine of \LaTeX{}. However, at that + moment a command of the form \verb|\ifodd\value{page}| would already + have been completely evaluated. + + To find out reliably whether a text falls on an even or odd + page, one must usually work with a label and a page reference to + this label. One must also take special precautionary measures during + the first \LaTeX{} run, when the label is not yet known. +\end{Explain} +If one wants to find out with {\KOMAScript} whether a text falls on an +even or odd page, one can use the \Macro {ifthispageodd} command. The +\PName{true} argument is executed only if the command falls on an odd +page. Otherwise the \PName{false} argument is executed. + +\begin{Explain} + More precisely stated, the question is not where the text is, but + whether a page reference to a label placed in this location would + refer to an odd or an even page. +\end{Explain} +\begin{Example} + Assume that you want to indicate if an odd or even page is + output. This could be achieved with the command: + \begin{small} +\begin{verbatim} + This is a page with an \ifthispageodd{odd}{even} + page number. +\end{verbatim} + \end{small} + The output would then be: + \begin{quote} + This is a page with an \ifthispageodd{odd}{even} + page number. + \end{quote} +\end{Example} + +Because the \Macro{ifthispageodd} command uses a mechanism that is +very similar to a label and a reference to it, at least two \LaTeX{} +runs are required after every text modification. Only then the +decision is correct. In the first run a heuristic is used to make the +first choice. + + +\begin{Explain} + There are situations where the \Macro{ifthispageodd} command never + leads to the correct result. Suppose that the command is used within + a box. A box is set by \LaTeX{} always as a whole. No page breaks + take place inside. Assume further that the \PName{true} part is very + big, but the \PName{false} part is empty. If we suppose further that + the box with the \PName {false} part still fits on the current, even + page, but that with the \PName{true} part it does not. Further + assume that \KOMAScript{} heuristically decides for the first run + that the \PName{true} part applies. The decision is wrong and is + revised in the next run. The \PName{false} part is thereby + processed, instead of the \PName{true} part. The decision must again + be revised in the next run and so on. + + These cases are rare. Nevertheless it should not be said that I have + not pointed out that they are possible. +\end{Explain} +% +\EndIndex{Cmd}{ifthispageodd} + +\begin{Declaration} + \Macro{pagenumbering}\Parameter{numbering style} +\end{Declaration} +\BeginIndex{Cmd}{pagenumbering}% +This command works the same way in \KOMAScript{} as in the standard +classes. More precisely it is a command from 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. The possible settings can be found in +\autoref{tab:numberKind}. Using 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}. +% +\begin{table} +\centering +\begin{tabular}{lll} +numbering style & example & description \\\hline\\[-2ex] +\PValue{arabic} & 8 & Arabic numbers \\ +\PValue{roman} & viii & lower-case Roman numbers \\ +\PValue{Roman} & VIII & upper-case Roman numbers \\ +\PValue{alph} & h & letters \\ +\PValue{Alph} & H & capital letters \\ +\end{tabular} +\caption{Available numbering styles of page numbers} +\label{tab:numberKind} +\end{table} +% +\EndIndex{Cmd}{pagenumbering} + + +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{Titles} +\label{sec:maincls.titles} + +\begin{Explain} + After having described the options and some general issues, we begin + the document where it usually begins: with the titles. The titles + comprise everything that belongs in the widest sense to the title of + a document. Like already mentioned in + \autoref{sec:maincls.layoutOptions}, we can distinguish + between title pages and \emph{in-page} titles. Article classes like + \Class{article} or \Class{scrartcl} have by default \emph{in-page} + titles, while classes like \Class{report}, \Class{book}, + \Class{scrreprt} and \Class{scrbook} have title pages as default. + The defaults can be changed with the class options + \Option{titlepage} and \Option{notitlepage}. +\end{Explain} + + +\begin{Declaration} + \Environment{titlepage} +\end{Declaration}% +\BeginIndex{Env}{titlepage}% +With the standard classes and with {\KOMAScript} all title pages are +defined in a special environment, the \Environment{titlepage} +environment. This environment always starts a new page -- in the +two-sided layout a new right page. For this page, the style is changed +as by \Macro{thispagestyle}\PParameter{empty}, so that neither page +number nor running title are output. At the end of the environment the +page is automatically shipped out. Should you not be able to use the +automatic layout of the title page, it is advisable to design a new +one with the help of this environment. + + +\begin{Example} + Assume you want a title page on which only the word " ` Me " ' + stands at the top on the left, as large as possible and in bold -- + no author, no date, nothing else. The following document makes just + that: + \begin{small} +\begin{verbatim} + \documentclass{scrbook} + \begin{document} + \begin{titlepage} + \textbf{\Huge Me} + \end{titlepage} + \end{document} +\end{verbatim} + \end{small} + Simple? Right. +\end{Example} +% +\EndIndex{Env}{titlepage} + +\begin{Declaration} + \Macro{maketitle}\OParameter{page number} +\end{Declaration}% +\BeginIndex{Cmd}{maketitle}% +While the the standard classes produce a title page that may have the +three items title, author and date, with {\KOMAScript} the +\Macro{maketitle} command can produce up to six pages. + +In contrast to the standard classes, the \Macro{maketitle} macro in +{\KOMAScript} accepts an optional numeric argument. If it is used, the +number is made the page number of the first title page. However, this +page number is not output, but affects only the numbering. You should +choose an odd number, because otherwise the whole counting gets mixed +up. In my opinion there are only two meaningful applications for the +optional argument. On the one hand, one could give to the +half-title\Index[indexmain]{half-title} the logical page number \(-1\) +in order to give the full title page the number 1. On the other hand +it could be used to start at a higher page number, for instance, 3, 5, +or 7 to accommodate other title pages added by the publishing house. +The optional argument is ignored for \emph{in-page} titles. However +the page style of such a title page can be changed by redefining the +\Macro{titlepagestyle} macro. For that see +\autoref{sec:maincls.pageStyle}. + +The following commands do not lead necessarily to the production of +the titles. The typesetting of the title pages is always done by +\Macro{maketitle}. The commands explained below only define the +contents of the title pages. It is however not necessary, and when +using the \Package{babel} package\IndexPackage{babel} not recommended, +to use these in the preamble before \Macro{begin}\PParameter{document} +(see \cite{package:babel}). Examples can be found at the end of this +section. + +\begin{Declaration} + \Macro{extratitle}\Parameter{half-title} +\end{Declaration}% +\BeginIndex{Cmd}{extratitle}% +\begin{Explain}% + In earlier times the inner book was often not protected from dirt by a cover. + This task was then taken over by the first page of the book which + carried mostly a shortened title, precisely the \emph{half-title}. + Nowadays the extra page is often applied before the real full title + and contains information on the publisher, series number and similar + information. +\end{Explain} + +With {\KOMAScript} it is possible to include a page before the real +title page. The \PName{half-title} can be arbitrary text -- even +several paragraphs. The contents of the \PName {half-title} are output +by {\KOMAScript} without additional formatting. Their organisation is +completely left to the user. The back of the half-title remains empty. +The half-title has its own title page even when \emph{in-page} titles +are used. The output of the half-title defined with \Macro{extratitle} +takes place as part of the titles produced by \Macro{maketitle}. + + +\begin{Example} + Let's go back to the previous example and assume + that the spartan "Me" is the half-title. The full title should + still follow the half-title. One can proceed as follows: + \begin{small} +\begin{verbatim} + \documentclass{scrbook} + \begin{document} + \extratitle{\textbf{\Huge Me}} + \title{It's me} + \maketitle + \end{document} +\end{verbatim} + \end{small} + You can center the half-title and put it a little lower down the page: + \begin{small} +\begin{verbatim} + \documentclass{scrbook} + \begin{document} + \extratitle{\vspace*{4\baselineskip} + \begin{center}\textbf{\Huge Me}\end{center}} + \title{It's me} + \maketitle + \end{document} +\end{verbatim} + \end{small} + The command \Macro{title} is necessary in order to make the examples + above work correctly. It is explained next. +\end{Example} +% +\EndIndex{Cmd}{extratitle} + + +\begin{Declaration} + \Macro{titlehead}\Parameter{Titlehead}\\ + \Macro{subject}\Parameter{Subject}\\ + \Macro{title}\Parameter{Title}\\ + \Macro{author}\Parameter{Author}\\ + \Macro{date}\Parameter{Date}\\ + \Macro{publishers}\Parameter{Publisher}\\ + \Macro{and}\\ + \Macro{thanks}\Parameter{Footnote} +\end{Declaration}% +\BeginIndex{Cmd}{titlehead}% +\BeginIndex{Cmd}{subject}% +\BeginIndex{Cmd}{title}% +\BeginIndex{Cmd}{author}% +\BeginIndex{Cmd}{date}% +\BeginIndex{Cmd}{publishers}% +\BeginIndex{Cmd}{and}% +\BeginIndex{Cmd}{thanks}% +The contents of the full title page are defined by six elements. The +\PName{title head}\Index[indexmain]{title head} is defined with the +command \Macro {titlehead}. It is typeset in regular paragraph style +and full width at the top of the page. It can be freely designed by +the user. + +The \PName{Subject}\Index[indexmain]{subject} is output immediately +above the \PName{Title}. A slightly larger font size than the regular +one is used. + +The \PName{Title} is output with a very large font size. +Besides\ChangedAt{v2.8p}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} the change +of size, the settings for the element +\FontElement{title}\IndexFontElement{title} also take effect. By +default these settings are identical to the settings for the element +\FontElement{sectioning}\IndexFontElement{sectioning} (see +\autoref{tab:maincls.elementsWithoutText}). The font size is however +not affected (see \autoref{tab:maincls.elementsWithoutText}). The +default settings can be changed with the commands of +\autoref{sec:maincls.font}. + +Below the \PName{Title} appears the +\PName{Author}\Index[indexmain]{author}. Several authors can be +specified in the argument of \Macro{author}. They should be separated +by \Macro{and}. + +Below the author or authors appears the date\Index{date}. The default +value is the present date, as produced by +\Macro{today}\IndexCmd{today}. The \Macro{date} command accepts +arbitrary information or even an empty argument. + +Finally comes the \PName{Publisher}\Index[indexmain]{publisher}. Of +course this command can also be used for any other information of +little importance. If necessary, the \Macro{parbox} command can be +used to typeset this information over the full page width like a +regular paragraph. Then it is to be considered equivalent to the +title head. However, note that this field is put above any existing +footnotes. + +Footnotes\Index{footnotes} on the title page are produced not with +\Macro{footnote}, but with \Macro{thanks}. They serve typically for +notes associated with the authors. Symbols are used as footnote +markers instead of numbers. + +With the exception of \PName{titlehead} and possible footnotes, all +the items are centered horizontally. The information is summarised in +\autoref{tab:maincls.mainTitle}. +\begin{table} + \centering + \begin{tabular}{llll} + Element & Command & Font + & Justification \\ + \hline\rule{0pt}{2.7ex}% + Title head & \Macro{titlehead} & \Macro{normalsize} + & Regular paragraph \\ + Subject & \Macro{subject} & \Macro{Large} + & centered \\ + Title & \Macro{title} & \Macro{huge} + & centered \\ + Authors & \Macro{author} & \Macro{Large} + & centered \\ + Date & \Macro{date} & \Macro{Large} + & centered \\ + Publishers & \Macro{publishers} & \Macro{Large} + & centered \\ + \end{tabular} + \caption[Main title]{Font size and horizontal positioning of the + elements in the main title page in the order of their vertical + position from top to bottom when typeset with \Macro{maketitle}} + \label{tab:maincls.mainTitle} +\end{table} + + +\begin{Example} + Assume you are writing a dissertation. The title page should have + the university's name and address at the top, flush left, and the + semester flush right. As usual a title is to be used, including + author and delivery date. + The advisor must also be indicated, together with the fact that the + document is a dissertation. This can be obtained as follows: + \begin{small} +\begin{verbatim} + \documentclass{scrbook} + \begin{document} + \titlehead{{\Large Unseen University + \hfill SS~2002\\} + Higher Analytical Institut\\ + Mythological Rd\\ + 34567 Etherworld} + \subject{Dissertation} + \title{Digital space simulation with the DSP\,56004} + \author{Fuzzy George} + \date{30. February 2002} + \publishers{Advisor Prof. John Excentric Doe} + \maketitle + \end{document} +\end{verbatim} + \end{small} +\end{Example} + + +\begin{Explain} +A frequent misunderstanding concerns the role of the full title side. +It is often erroneous assumed that the cover (or dust cover) is meant. +Therefore, it is frequently expected that the title page does not follow +the normal page layout, but have equally large left and right margins. + +However if one takes a book and opens it, one hits very quickly on at +least one title page under the cover within the so-called inner book. +Precisely these title pages are produced by \Macro{maketitle}. Like it +happens with the half-title, the full title page belongs to the inner +book, and therefore should have the same page layout as the rest of +the document. A cover is actually something that should be created in +a separate document. The cover often has a very individual format. It +can also be designed with the help of a graphics or DTP program. A +separate document should also be used because the cover will be +printed on a different medium, possibly cardboard, and possibly with +another printer. +\end{Explain} +% +\EndIndex{Cmd}{titlehead}% +\EndIndex{Cmd}{subject}% +\EndIndex{Cmd}{title}% +\EndIndex{Cmd}{author}% +\EndIndex{Cmd}{date}% +\EndIndex{Cmd}{publishers}% +\EndIndex{Cmd}{and}% +\EndIndex{Cmd}{thanks}% + + + +\begin{Declaration} + \Macro{uppertitleback}\Parameter{titlebackhead}\\ + \Macro{lowertitleback}\Parameter{titlebackfoot} +\end{Declaration}% +\BeginIndex{Cmd}{uppertitleback}% +\BeginIndex{Cmd}{lowertitleback}% +% +With the standard classes, the back of the title page is left empty. +However, with {\KOMAScript} the back of the full title page can be +used for other information. Exactly two elements which the user can +freely format are recognized: \PName {titlebackhead} and \PName +{titlebackfoot}. The head can reach up to the foot and vice versa. If +one takes this manual as an example, the exclusion of liability was +set with the help of the \Macro{uppertitleback} command. +\EndIndex{Cmd}{uppertitleback}% +\EndIndex{Cmd}{lowertitleback}% + + +\begin{Declaration} + \Macro{dedication}\Parameter{dedication} +\end{Declaration}% +\BeginIndex{Cmd}{dedication}% +{\KOMAScript} provides a page for dedications. The +dedication\Index{dedication} is centered and uses a slightly larger +type size. The back is empty like the back page of the half-title. +The dedication page is produced by \Macro{maketitle} and must +therefore be defined before this command is issued. + +\begin{Example} + This time assume that you have written a poetry book and you want to + dedicate it to your wife. A solution would look like this: + \begin{small} +\begin{verbatim} + \documentclass{scrbook} + \begin{document} + \extratitle{\textbf{\Huge In Love}} + \title{In Love} + \author{Prince Ironheart} + \date{1412} + \lowertitleback{This poem book was set with% + the help of {\KOMAScript} and {\LaTeX}} + \uppertitleback{Selfmockery Publishers} + \dedication{To my treasure\\ + in eternal love.} + \maketitle + \end{document} +\end{verbatim} + \end{small} +\end{Example} +% +\EndIndex{Cmd}{dedication} +% +\EndIndex{Cmd}{maketitle} + + +\begin{Declaration} + \Environment{abstract} +\end{Declaration}% +\BeginIndex{Env}{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. Therefore, +this is often considered a part of the titles. Some {\LaTeX} classes +offer a special environment for this summary, the +\Environment{abstract} environment. This is output directly, at it is +not a component of the titles set by \Macro{maketitle}. Please note +that \Environment{abstract} is an environment, not a command. Whether +the summary has a heading or not is determined by the options +\Option{abstracton} and \Option{abstractoff} (see +\autoref{sec:maincls.formattingOptions}) + +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. +% +\EndIndex{Env}{abstract} + +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{The Table of Contents} +\label{sec:maincls.toc} + +The titles are normally followed by the table of contents\Index{table +of contents}. +Often the table of contents is followed by lists of floats, e.g. lists +of tables and figures, see \autoref{sec:maincls.floats}). + +\begin{Declaration} + \Macro{tableofcontents}\\ + \Macro{contentsname} +\end{Declaration}% +\BeginIndex{Cmd}{tableofcontents}% +\BeginIndex{Cmd}{contentsname}% + 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 option \Option{liststotoc} causes +the lists of figures and tables to be included in the table of +contents. \Option{idxtotoc} is the corresponding option for the index. +This is rather uncommon in classical typography. One finds the +bibliography included in the table of contents a little bit more +frequently. This can be obtained with the options \Option{bibtotoc} +and \Option{bibtotocnumbered}. These options are explained in +\autoref{sec:maincls.tocOptions}. + +The table of contents is not set as a numbered chapter and is +therefore subjected to the side effects of the standard +\Macro{chapter*} command, which are described in +\autoref{sec:maincls.structure}. However, the running +titles\Index {running title} for left and right pages are correctly +filled with the heading of the table of contents. The text of the +heading is given by the macro \Macro{contentsname}. +% +\EndIndex{Cmd}{tableofcontents}% +\EndIndex{Cmd}{contentsname}% + + +There is only one variant for the construction of the table of +contents. The titles of the sectional units are indented so that the +unit number is flush left to the edge of the title of the next upper +unit. However, the place for the numbers is thereby limited and is +only sufficient for a little bit more than 1.5 places per level. +Should this become a problem, help can be found in \cite{DANTE:FAQ}. + +The entry for the highest sectional unit below \Macro{part}, i.e., +\Macro{chapter} with \Class{scrbook}\IndexClass{scrbook} and +\Class{scrreprt}\IndexClass{scrreprt} or \Macro{section} with +\Class{scrartcl}\IndexClass {scrartcl} is not indented. It is however +affected by the settings of the element +\FontElement{sectioning}\IndexFontElement{sectioning} (see +\autoref{tab:maincls.elementsWithoutText}). There is no point +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. + + +\begin{Declaration} + \Counter{tocdepth} +\end{Declaration}% +\BeginIndex{Counter}{tocdepth}% +Normally, the units included in the table of contents are all the +units from \Macro{part} to \Macro{subsection} (for the classes +\Class{scrbook} and \Class{scrreprt}) or from \Macro{part} to +\Macro{subsubsection} (for the class \Class{scrartcl}). The inclusion +of a sectional unit in the table of contents is controlled by the +counter \Counter{tocdepth}. It has the value \(-1\) for \Macro{part}, +\(0\) for \Macro{chapter} and so on. Since the class \Class{scrartcl} has +no \Macro{chapter}, the counter starts with 0 for the \Macro{part}. By +setting, 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. + +The user of the \Package{scrpage2}\IndexPackage{scrpage2} package (see +\autoref{cha:scrpage}) does not need to remember the numerical +values of each sectional unit. They are given by the values of the +macros \Macro{chapterlevel}, \Macro{sectionlevel} and so on down to +\Macro{subparagraphlevel}. +\begin{Example} + Assume that you are preparing an article that uses the sectional + unit \Macro{subsubsection}. However, you don't want this sectional + unit to appear in the table of contents. The preamble of your + document might contain the following: + \begin{small} +\begin{verbatim} + \documentclass{scrartcl} + \setcounter{tocdepth}{2} +\end{verbatim} +\end{small} +You set the counter \Counter{tocdepth} to 2, because you know that +this is the value for \Macro{subsection}. If you know that +\Class{scrartcl} normally includes all levels up to +\Macro{subsubsection} in the table of contents, you can simply +decrement the counter \Counter{tocdepth} by one: +\begin{small} +\begin{verbatim} + \documentclass{scrartcl} + \addtocounter{tocdepth}{-1} +\end{verbatim} +\end{small} +How much you should add to or take from the \Counter{tocdepth} counter +can also be found by looking at the table of contents after the first +\LaTeX{} run. +\end{Example} +% +\EndIndex{Counter}{tocdepth}% + +\section{Lists of Floats} + +As a rule, the lists of floats\index{float environments}, +e.g. list of tables\index{list of tables} and +list of figures\index{list of figures}, can be found directly +after the table of contents. +In some documents, they even can be found in the appendix. +However, the author of this manual prefers the location +after the table of contents, therefore it is discussed here. + +\begin{Declaration} + \Macro{listoftables}\\ + \Macro{listoffigures} +\end{Declaration} +\BeginIndex{Cmd}{listoftables}% +\BeginIndex{Cmd}{listoffigures}% +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 options +\Option{listsindent} and \Option{listsleft}, see +\autoref{sec:maincls.listsOptions}. +Moreover, the options \Option{liststotoc} and +\Option{liststotocnumbered} have indirect influence, +see \autoref{sec:maincls.tocOptions}). +% +\EndIndex{Cmd}{listoftables}% +\EndIndex{Cmd}{listoffigures}% + + +\section{Main Text} +\label{sec:maincls.mainText} + +This section explains everything provided by \KOMAScript{} +in order to write the main text. The main text is the +part that the author should focus on first. +Of course this includes tables, figures and comparable +information as well. + +\subsection{Separation} +\label{sec:maincls.separation} + +\begin{Declaration} + \Macro{frontmatter}\\ + \Macro{mainmatter}\\ + \Macro{backmatter} +\end{Declaration}% +\BeginIndex{Cmd}{frontmatter}% +\BeginIndex{Cmd}{mainmatter}% +\BeginIndex{Cmd}{backmatter}% +Before\OnlyAt{\Class{scrbook}} getting to the main text eventually +we will have a short look at three commands which exist both in the +standard class \Class{book} and the {\KOMAScript} class +\Class{scrbook}. They are used for separation of the +\emph{prefix}\Index{prefix}, the \emph{main text}\Index{main text} and +the \emph{appendix}\Index{appendix} in a book. + +The macro \Macro{frontmatter} introduces the prefix in which roman +numbers are used for the page numbers. Chapter headings in a prefix +don't have any numbers. The foreword can be set as a normal chapter. +A foreword should never be divided into sections but kept short. +Therefore there is no need for a deeper structuring than chapter. + +\Macro{mainmatter} introduces the main text. If there is no prefix +this command can be omitted. The default in the main text is arabic +page numbering (re)starting with 1. + +The appendix is introduced with \Macro{backmatter}. Opinions differ in +what should be part of the prefix. So in some cases you will only find +the bibliography\Index{bibliography}, in some cases only the +index\Index{index} and in other cases both of it in the appendix. +Besides, the appendix is similar to the prefix. +% +\EndIndex{Cmd}{frontmatter}% +\EndIndex{Cmd}{mainmatter}% +\EndIndex{Cmd}{backmatter}% + + +\subsection{Structuring the Document}\Index[indexmain]{structuring} +\label{sec:maincls.structure} + +\begin{Declaration} + \Macro{part}\OParameter{Short version}\Parameter{Heading}\\ + \Macro{chapter}\OParameter{Short version}\Parameter{Heading}\\ + \Macro{section}\OParameter{Short version}\Parameter{Heading}\\ + \Macro{subsection}\OParameter{Short version}\Parameter{Heading}\\ + \Macro{subsubsection}\OParameter{Short version}\Parameter{Heading}\\ + \Macro{paragraph}\OParameter{Short version}\Parameter{Heading}\\ + \Macro{subparagraph}\OParameter{Short version}\Parameter{Heading} +\end{Declaration}% +\BeginIndex{Cmd}{part}% +\BeginIndex{Cmd}{chapter}% +\BeginIndex{Cmd}{section}% +\BeginIndex{Cmd}{subsection}% +\BeginIndex{Cmd}{subsubsection}% +\BeginIndex{Cmd}{paragraph}% +\BeginIndex{Cmd}{subparagraph}% +The standard sectioning commands in {\KOMAScript} work quite similar +to the standard classes. Normally the section headings show up in the +table of contents exactly as they are entered in the text. The entry +for the table of contents can be specified as an optional argument in +front of the actual heading. +\OnlyAt{\Class{scrartcl}}\Macro{chapter} only exists in book or +report classes but not in article classes. In addition to this, the +command \Macro{chapter} in {\KOMAScript} differs substantially from +the version in the standard class. While in the standard classes every +chapter number is used together with the prefix ``Chapter'' on a +separate line above the heading, {\KOMAScript} only places the chapter +number in front of the heading. + +Please note that \Macro{part} and \Macro{chapter} change the page +style for one page. The applied page style in \KOMAScript{} is defined +in \Macro{partpagestyle} and \Macro{chapterpagestyle} (see +\autoref{sec:maincls.pageStyle}). + +\BeginIndex[indexother]{}{font}% +\BeginIndex[indexother]{}{font size}% +The font of all headings\ChangedAt{v2.8p}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} % +can be changed with the commands +\Macro{setkomafont}\IndexCmd{setkomafont} and +\Macro{addtokomafont}\IndexCmd{addtokomafont} described in +\autoref{sec:maincls.font}. First of all the element +\FontElement{sectioning}\IndexFontElement{sectioning} is used, which +is followed by a specific element for every section level (see +\autoref{tab:maincls.elementsWithoutText}). The font for the element +\FontElement{sectioning}\IndexFontElement{sectioning} is predefined as +\Macro{normalfont}\Macro{normalcolor}\Macro{sffamily}% +\Macro{bfseries}. The default font size for the specific elements depends +on the options \Option{bigheadings}, \Option{normalheadings} and +\Option{smallheadings} (see \autoref{sec:maincls.fontOptions}). The +defaults are listed in \autoref{tab:maincls.structureElementsFont} +% +\begin{table} + \centering% + \begin{tabular}{lll} + class option & element & default\\\hline\\[-1.6ex] + \Option{bigheadings} + & \FontElement{part}\IndexFontElement{part} + & \Macro{Huge} \\ + & \FontElement{partnumber}\IndexFontElement{partnumber} + & \Macro{huge} \\ + & \FontElement{chapter}\IndexFontElement{chapter} + & \Macro{huge} \\ + & \FontElement{section}\IndexFontElement{section} + & \Macro{Large} \\ + & \FontElement{subsection}\IndexFontElement{subsection} + & \Macro{large} \\ + & \FontElement{subsubsection}% + \IndexFontElement{subsubsection} + & \Macro{normalsize} \\ + & \FontElement{paragraph}\IndexFontElement{paragraph} + & \Macro{normalsize} \\ + & \FontElement{subparagraph}\IndexFontElement{subparagraph} + & \Macro{normalsize} \\[1ex] + \Option{normalheadings} + & \FontElement{part} & \Macro{huge} \\ + & \FontElement{partnumber} & \Macro{huge} \\ + & \FontElement{chapter} & \Macro{LARGE} \\ + & \FontElement{section} & \Macro{Large} \\ + & \FontElement{subsection} & \Macro{large} \\ + & \FontElement{subsubsection} & \Macro{normalsize} \\ + & \FontElement{paragraph} & \Macro{normalsize} \\ + & \FontElement{subparagraph} & \Macro{normalsize} \\[1ex] + \Option{smallheadings} + & \FontElement{part} & \Macro{LARGE} \\ + & \FontElement{partnumber} & \Macro{LARGE} \\ + & \FontElement{chapter} & \Macro{Large} \\ + & \FontElement{section} & \Macro{large} \\ + & \FontElement{subsection} & \Macro{normalsize} \\ + & \FontElement{subsubsection} & \Macro{normalsize} \\ + & \FontElement{paragraph} & \Macro{normalsize} \\ + & \FontElement{subparagraph} & \Macro{normalsize} + \end{tabular} + \caption{Default font sizes for different levels of document structuring} + \label{tab:maincls.structureElementsFont} +\end{table} + +\begin{Example} + Suppose you are using the class option \Option{bigheadings} and notice + that the very big headings of document parts are to bold. You could change + this as follows: + \begin{small} +\begin{verbatim} + \setkomafont{sectioning}{\normalcolor\sffamily} + \part{Appendices} + \addtokomafont{sectioning}{\bfseries} +\end{verbatim} + \end{small} + Using the command above you only switch off the font attribute + \textbf{bold} for the heading ``Appendices''. A much more comfortable + and elegant solution is to change all \Macro{part} headings in one go. + This is done either by: + \begin{small} +\begin{verbatim} + \addtokomafont{part}{\normalfont\sffamily} + \addtokomafont{partnumber}{\normalfont\sffamily} +\end{verbatim} + \end{small} + or using: + \begin{small} +\begin{verbatim} + \addtokomafont{part}{\mdseries} + \addtokomafont{partnumber}{\mdseries} +\end{verbatim} + \end{small} + The last version is to be preferred because it gives you the correct + result even when you change the \FontElement{sectioning} + element\IndexFontElement{sectioning} as follows: + \begin{small} +\begin{verbatim} + \setkomafont{sectioning}{\normalcolor\bfseries} +\end{verbatim} + \end{small} + With this change it is possible to set all section levels at once to not + longer use sans serif fonts. +\end{Example} + +Please be warned of using 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 thing even for professionals +and has nothing to do with personal taste of beginners. Please refer +to the citation at the end of \autoref{sec:typearea.tips} and the +following explanation. + +\begin{Explain} + It is possible to use different font types for different section levels + in {\KOMAScript}. As a typographical beginner you should refrain from + using these possibilities for typographical reasons. There is a rule + which states that you should mix fonts only as few as possible. Using + sans serif for headings seems already a breach of this rule. However, + you should know that bold, huge and serif letters are much to heavy for + headings. In general you would have to use a normal instead of a bold + or semi bold font. However, in deeper levels of the structuring a normal + font appears rather leight weighted. On the other hand sans serif fonts + in headings have a very pleasant appearance and are to be used only in + headings. That's why sans serif is the default in {\KOMAScript}. More + variety should be avoided. Font mixing is only for professionals. In + case you want to use other fonts than the standard \TeX-Fonts -- no + matter whether using CM \Index{CM fonts} or EC fonts\Index{EC fonts} -- + you should consult an expert or redefine the font for the element + \FontElement{sectioning}\IndexFontElement{sectioning} as seen in + the example above. You often find the combinations Times and Helvetica + or Palatino with Helvetica. The author of this documentation does not + favour these combinations. +\end{Explain} +\EndIndex[indexother]{}{font}% +\EndIndex[indexother]{}{font size}% +% +\EndIndex{Cmd}{part}% +\EndIndex{Cmd}{chapter}% +\EndIndex{Cmd}{section}% +\EndIndex{Cmd}{subsection}% +\EndIndex{Cmd}{subsubsection}% +\EndIndex{Cmd}{paragraph}% +\EndIndex{Cmd}{subparagraph}% + + +\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} +\end{Declaration}% +\BeginIndex{Cmd}{part*}% +\BeginIndex{Cmd}{chapter*}% +\BeginIndex{Cmd}{section*}% +\BeginIndex{Cmd}{subsection*}% +\BeginIndex{Cmd}{subsubsection*}% +\BeginIndex{Cmd}{paragraph*}% +\BeginIndex{Cmd}{subparagraph*}% +All sectioning commands exist as ``starred'' versions. They produce +section headings which do not show up in the table of +contents\Index{table of contents}, in the page header\Index{header} +and which are not numbered\Index{numbering}. Not using a headline +often has an unwanted side effect. For example, if a chapter which is +set using \Macro{chapter*} spans over several pages the headline of +the chapter before comes up again. {\KOMAScript} offers a solution +which is described below. +\OnlyAt{\Class{scrartcl}}\Macro{chapter*} only exists in book and +report classes which includes \Class{book}, \Class{scrbook}, +\Class{report} and \Class{scrreport}, but not the article classes +\Class{article} and \Class{scrartcl}. + +Please note that \Macro{part} and \Macro{chapter} change the page +style for one page. The applied style is defined in +\Macro{partpagestyle} and \Macro{chapterpagestyle} in \KOMAScript{} +(see \autoref{sec:maincls.pageStyle}). + +As for the possibilities of font switching\ChangedAt{v2.8p}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} % +the same explanations apply which were given above with the normal +sectioning commands. The elements of structuring are named in the same +way as the ``unstarred'' versions. +% +\EndIndex{Cmd}{part*}% +\EndIndex{Cmd}{chapter*}% +\EndIndex{Cmd}{section*}% +\EndIndex{Cmd}{subsection*}% +\EndIndex{Cmd}{subsubsection*}% +\EndIndex{Cmd}{paragraph*}% +\EndIndex{Cmd}{subparagraph*}% + +\iffalse In the standard classes there are no further sectioning commands. In +particular, there are no commands which produce unnumbered chapters or +sections which show up in the table of contents or in the page header. \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} +\end{Declaration}% +\BeginIndex{Cmd}{addpart}% +\BeginIndex{Cmd}{addpart*}% +\BeginIndex{Cmd}{addchap}% +\BeginIndex{Cmd}{addchap*}% +\BeginIndex{Cmd}{addsec}% +\BeginIndex{Cmd}{addsec*}% +In addition to the standard classes {\KOMAScript} offers the new +commands \Macro{addsec} and \Macro{addchap}. They are similar to the +standard commands \Macro{chapter} und \Macro{section} except the +missing numbering. The produce both a running headline and an entry in +the table of contents. The starred versions \Macro{addchap*} and +\Macro{addsec*} are similar to the standard commands \Macro{chapter*} +and \Macro{section*} apart from a tiny but important difference: The +headlines are deleted. This eliminates the side effect of obsolete +headers mentioned above. \OnlyAt{\Class{scrartcl}}\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}. + +Similar to this, the command \Macro{addpart} produces an unnumbered +document part with an entry in the table of contents. Since the +headers are already deleted by \Macro{part} and \Macro{part*} the +problem of obsolete headers doesn't exist. The starred version +\Macro{addpart*} is identical to \Macro{part*} and is only defined for +consistency reasons. + +Please note that \Macro{addpart} and \Macro{addchap} including their +starred versions change the page style for one page. The particular +page style is defined in the macros \Macro{partpagestyle} and +\Macro{chapterpagestyle} (see \autoref{sec:maincls.pageStyle}). + +As for the possibilities of font switching\ChangedAt{v2.8p}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} % +the same explanations apply which were given above with the normal +sectioning commands. The elements of structuring are named in the same +way as the ``unstarred'' versions. +% +\EndIndex{Cmd}{addpart}% +\EndIndex{Cmd}{addpart*}% +\EndIndex{Cmd}{addchap}% +\EndIndex{Cmd}{addchap*}% +\EndIndex{Cmd}{addsec}% +\EndIndex{Cmd}{addsec*}% + + +\begin{Declaration} + \Macro{minisec}\Parameter{Heading} +\end{Declaration}% +\BeginIndex{Cmd}{minisec}% +Sometimes a heading\Index{heading} is wanted which is highlighted but +closely linked to the following text. Such a heading shouldn't be +separated by a vertical skip. + +The command \Macro{minisec} is designed for this situation. This heading +isn't linked to a level of structuring. Such a \emph{Mini-section} +does not produce an entry in the table of contents nor does it receive +any numbering. +\begin{Example} + You have developed a kit for building a mouse trap and want the + documentation separated into the things needed and an assembly + description. Using \Macro{minisec} you could write the following: + \begin{small} +\begin{verbatim} + \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 meanwhile the following + actions. + + Afterwards one knocks in the spring-plug with the hammer + in 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 with the two screws + employing the knife on the mouse-hole. + Instead of the knife one can use a screw-driver as well. +\end{verbatim} + \end{small} + Which gives: + \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 + meanwhile the following actions. + + Afterwards one knocks in the spring-plug with the hammer + in 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 with the two screws + employing the knife on the mouse-hole. + Instead of the knife one can use a screw-driver as well. + + \end{ShowOutput} +\end{Example} + +The font type of the sectioning command \Macro{minisec} can only be +changed using the element +\FontElement{sectioning}\IndexFontElement{sectioning} (see +\autoref{tab:maincls.elementsWithoutText}). There is no specific +element for \Macro{minisec}. This means you can't change the font size +manually. +% +\EndIndex{Cmd}{minisec}% + + +\begin{Declaration} + \Macro{raggedsection} +\end{Declaration}% +\BeginIndex{Cmd}{raggedsection}% +In the 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} formats the headings left +aligned with hanging indentation using \Macro{raggedsection} with the +definition: +\begin{verbatim} + \newcommand*{\raggedsection}{\raggedright} +\end{verbatim} +This command can be redefined with \Macro{renewcommand}. +\begin{Example} + You prefer justified headings. You write in the preamble of your document: + \begin{small} +\begin{verbatim} + \renewcommand*{\raggedsection}{} +\end{verbatim} + \end{small} + or short: + \begin{small} +\begin{verbatim} + \let\raggedsection\relax +\end{verbatim} + \end{small} + You will get a formatting of the headings which is very close to the + standard classes. Even closer it will get when you combine this change + with the change of the element + \FontElement{sectioning}\IndexFontElement{sectioning} mentioned + above. +\end{Example} +% +\EndIndex{Cmd}{raggedsection}% + + +\begin{Declaration} + \Macro{partformat}\\ + \Macro{chapterformat}\\ + \Macro{othersectionlevelsformat}\Parameter{section name}\\ + \Macro{autodot} +\end{Declaration}% +\BeginIndex{Cmd}{partformat}% +\BeginIndex{Cmd}{chapterformat}% +\BeginIndex{Cmd}{othersectionlevelsformat}% +\BeginIndex{Cmd}{autodot}% +\begin{Explain}% + As you might know, for every counter in {\LaTeX} there is a command + \Macro{the}\PName{counter name}, which gives you the value of the + counter. Depending on the class the counter for a particular level + starting from \Macro{section} (\Class{book}, \Class{scrbook}, + \Class{report}, \Class{scrreprt}) or \Macro{subsection} + (\Class{article}, \Class{scrartcl}) is composed of the counter for the + higher level followed by a dot and the arabic number of the + \PName{counter name} of the respective level.\par +\end{Explain} + +\KOMAScript{} has added to the output of the section number a further +logical level. The counter for the respective heading are formatted +using \Macro{partformat}, \Macro{chapterformat} and +\Macro{othersectionlevelsformat}. +\OnlyAt{\Class{scrbook}\and\Class{scrreprt}}Of course the command +\Macro{chapterformat} doesn't exist in the class \Class{scrartcl}. + +As described in \autoref{sec:maincls.formattingOptions} +{\KOMAScript} handles dots in section numbers according to +\cite{DUDEN}. The command \Macro{autodot} makes sure that these rules +are being followed. Except from \Macro{part} in all levels a dot is +followed by a \Macro{enskip}. This is similar to a horizontal skip of +\(0.5\Unit{em}\). + +The command \Macro{othersectionlevelsformat} takes the name of the +section level, such as ``\PName{section}'', ``\PName{subsection}'' +\dots{}, as parameter. As default, only the levels \Macro{part} and +\Macro{chapter} have formatting commands on their own, while all other +section levels are covered by one formatting command only. This has +historical reasons. At the time Werner Lemberg suggested a suitable +extension of {\KOMAScript} for his \Package{CJK} package, only this +differentiation was needed. + +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: +\begin{verbatim} + \newcommand*{\partformat}{\partname~\thepart\autodot} + \newcommand*{\chapterformat}{% + \chapappifchapterprefix{\ }\thechapter\autodot\enskip} + \newcommand*{\othersectionlevelsformat}[1]{% + \csname the#1\endcsname\autodot\enskip} +\end{verbatim} + +\begin{Example} + Assume you don't want the word ``Part'' written in front of the part number. + You could use the following command in the preamble of your document: + \begin{small} +\begin{verbatim} + \renewcommand*{\partformat}{\thepart\autodot} +\end{verbatim} + \end{small} + In fact, you could do without \Macro{autodot} at this point and insert + a fixed point instead. As \Macro{part} is numbered with roman numbers, + according to \cite{DUDEN} a dot has to be applied. However, you would + give up the possibility to use one of the options + \Option{pointednumbers} und \Option{pointlessnumbers} then. More + details concerning class options you can find in + \autoref{sec:maincls.formattingOptions}). + + An additional possibility could be to place the section numbers + in the left margin. That can be done in a way that the heading + text is left aligned with the surrounding text. + This can be accomplished with: + \begin{small} +\begin{verbatim} + \renewcommand*{\othersectionlevelsformat}[1]{% + \llap{\csname the#1\endcsname\autodot\enskip}} +\end{verbatim} + \end{small} + The almost unknown command \Macro{llap} in the definition above, + puts its argument left to the current possition without changing the + position. +\end{Example} +% +\EndIndex{Cmd}{partformat}% +\EndIndex{Cmd}{chapterformat}% +\EndIndex{Cmd}{othersectionlevelsformat}% +\EndIndex{Cmd}{autodot}% + + +\begin{Declaration} + \Macro{chapappifchapterprefix}\Parameter{additional text}\\ + \Macro{chapapp} +\end{Declaration}% +\BeginIndex{Cmd}{chapappifchapterprefix}% +\BeginIndex{Cmd}{chapapp}% +These\OnlyAt{\Class{scrbook}\and\Class{scrreprt}}% +\ChangedAt{v2.8o}{\Class{scrbook}\and\Class{scrreprt}} two commands +are used internally by {\KOMAScript} and are also provided at the user +interface. Using the layout option \Option{chapterprefix} (see +\autoref{sec:maincls.layoutOptions}) +\Macro{chapappifchapterprefix} issues the word +``Chapter''\Index{chapter} in the main part of your document in the +current language followed by \PName{additional text}. In the +appendix\Index{appendix} instead, the word ``Appendix'' in the current +language followed by \PName{additional text} is issued. Having set the +option \Option{nochapterprefix} there is no additional output. + +The command \Macro{chapapp} always issues the word ``Chapter'' or +``Appendix''. In this case the options \Option{chapterprefix} and +\Option{nochapterprefix} have no effect. + +Since chapters only exist in the classes \Class{scrbook} and +\Class{scrreprt} these commands only exist in these classes. +% +\EndIndex{Cmd}{chapappifchapterprefix}% +\EndIndex{Cmd}{chapapp}% + + +\begin{Declaration} + \Macro{chaptermark}\Parameter{Running head}\\ + \Macro{sectionmark}\Parameter{Running head}\\ + \Macro{subsectionmark}\Parameter{Running head}\\ + \Macro{chaptermarkformat}\\ + \Macro{sectionmarkformat}\\ + \Macro{subsectionmarkformat} +\end{Declaration}% +\BeginIndex{Cmd}{chaptermark}% +\BeginIndex{Cmd}{sectionmark}% +\BeginIndex{Cmd}{subsectionmark}% +\BeginIndex{Cmd}{chaptermarkformat}% +\BeginIndex{Cmd}{sectionmarkformat}% +\BeginIndex{Cmd}{subsectionmarkformat}% +\begin{Explain}% + As mentioned in \autoref{sec:maincls.pageStyle} the page style + \PValue{headings} works with running heads\Index{running + head}. For this, the commands \Macro{chaptermark} and + \Macro{sectionmark} as well as \Macro{sectionmark} and + \Macro{subsectionmark} respectively are defined. Every sectioning + command (\Macro{chapter}, \Macro{section}, \Macro{subsection} \dots) + automatically carries out the respective \Macro{\dots mark} command. + The parameter handed over takes the text of the section + heading\Index{heading}. The respective section number is added + automatically to the \Macro{\dots mark} command. The formatting is done + according to the section level with the command + \Macro{chaptermarkformat}, \Macro{sectionmarkformat} or + \Macro{subsectionmarkformat}. + \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 the command \Macro{subsectionmarkformat} + only exist in \Class{scrartcl}. This changes when you use the + \Package{scrpage2} package (see \autoref{cha:scrpage}).\par +\end{Explain} +Similar to \Macro{chapterformat} and \Macro{othersectionlevelsformat} the +commands \Macro{chaptermarkformat} (not at \Class{scrartcl}), +\Macro{sectionmarkformat} and the command \Macro{subsectionmarkformat} +(only at \Class{scrartcl}) define the formatting of the section numbers +in running heads. They can be adapted to your personal needs with +\Macro{renewcommand}. The original definitions from the {\KOMAScript} +classes are: +\begin{verbatim} + \newcommand*{\chaptermarkformat}{% + \chapappifchapterprefix{\ }\thechapter\autodot\enskip} + \newcommand*{\sectionmarkformat}{\thesection\autodot\enskip} + \newcommand*{\subsectionmarkformat}{% + \thesubsection\autodot\enskip} +\end{verbatim} +\begin{Example} + Suppose you want to combine the chapter number in the header with the word + ``Chapter''. For example you could insert in the preamble of your + document the following definition: + \begin{small} +\begin{verbatim} + \renewcommand*{\chaptermarkformat}{% + \chapapp~\thechapter\autodot\enskip} +\end{verbatim} + \end{small} +\end{Example} +As you can see both the commands \Macro{chapappifchapterprefix} and +\Macro{chapapp} explained above are used. +% +\EndIndex{Cmd}{chaptermark}% +\EndIndex{Cmd}{sectionmark}% +\EndIndex{Cmd}{subsectionmark}% +\EndIndex{Cmd}{chaptermarkformat}% +\EndIndex{Cmd}{sectionmarkformat}% +\EndIndex{Cmd}{subsectionmarkformat}% + + +\begin{Declaration} + \Counter{secnumdepth} +\end{Declaration}% +\BeginIndex{Counter}{secnumdepth}\BeginIndex{}{numbering}% +As default in the classes \Class{scrbook}\IndexClass{scrbook} and +\Class{scrreprt}\IndexClass{scrreprt} the section levels from +\Macro{part}\IndexCmd{part}\IndexCmd{chapter}\IndexCmd{section} down +to \Macro{subsection}\IndexCmd{subsection} and in the class +\Class{scrartcl}\IndexClass{scrartcl} the levels from \Macro{part} +down to \Macro{subsubsection}\IndexCmd{subsubsection} are numbered. +This is controlled by the \LaTeX\ counter \Counter{secnumdepth}. The +value \(-1\) represents \Macro{part}, \(0\) the level \Macro{chapter} +and so on. Since in \Class{scrartcl} there is no \Macro{chapter} the +counting in this class starts with \(0\) at the level \Macro{part}. By +way of defining, decrementing or incrementing this counter you can +determine down to which level the headings are numbered. The same +applies in the standard classes. Please refer also to the explanations +concerning the counter \Counter{tocdepth} in +\autoref{sec:maincls.toc}. +% +\EndIndex{Counter}{secnumdepth}\EndIndex{}{numbering} + + +\begin{Declaration} + \Macro{setpartpreamble}% + \OParameter{position}\OParameter{width}\Parameter{preamble}\\ + \Macro{setchapterpreamble}% + \OParameter{position}\OParameter{width}\Parameter{preamble} +\end{Declaration}% +\BeginIndex{Cmd}{setpartpreamble}% +\BeginIndex{Cmd}{setchapterpreamble}% +Parts\OnlyAt{\Class{scrbook}\and\Class{scrreprt}} and chapters in +{\KOMAScript} can be started with a \PName{preamble}. This is +particularily useful when you are using a two column layout with the +class option \Option{twocolumn}\IndexOption{twocolumn}. Together with +the heading the \PName{preamble} is always set in a one column layout. +The \PName{preamble} can comprise more than one paragraph. The command +for issuing the \PName{preamble} has to be put in front of the +respective \Macro{part}, \Macro{addpart}, \Macro{chapter} or +\Macro{addchap} command. +\begin{Example} + You are writing a report on the situation 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 a short abstract on the + title page. You could write the following: + \begin{small} +\begin{verbatim} + \setpartpreamble{% + \begin{abstract} + This is a blind text. This text should show, how a + printed text will look like at this place. If you + read this text, you will get no information. + \end{abstract} + } + \part{Department for Word Processing} +\end{verbatim} + \end{small} + Depending on the settings for the heading\Index{heading} (see + \autoref{sec:maincls.fontOptions}) size and the \Environment{abstract} + environment\IndexEnv{abstract} (see + \autoref{sec:maincls.formattingOptions}), the result would look similar + to: + \begin{ShowOutput}\centering + {\LARGE\usekomafont{sectioning} Part III.\par\vspace{20pt}} + {\LARGE\usekomafont{sectioning} Department for Word Processing\strut\par} + \begin{quote}\small + \vspace{3ex} + \begin{center} + \usekomafont{sectioning}\abstractname + \end{center} + \vspace{2ex} This is a blind text. This text should show, how a + printed text will look like at this place. If you read this text, + you will get no information. + \end{quote} + \end{ShowOutput} +\end{Example} +Please 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 \Environment{abstract} environment in the class +\Class{scrbook} (see \autoref{sec:maincls.titles}). + +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: +\begin{description} +\item [\quad\texttt{o}:] above the heading +\item [\quad\texttt{u}:] below the heading +\end{description} +You can insert a preamble both above and below a heading. For the +horizontal placement you have the choice between three alignments: +\begin{description} +\item [\quad\texttt{l}:] left-aligned +\item [\quad\texttt{r}:] right-aligned +\item [\quad\texttt{c}:] centered +\end{description} +However, this does not issue the text of the \PName{preamble} 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 this case the option for horizontal +positioning will have no effect. You can combine one letter from the +vertical with one letter from the horizontal positioning. +% +\EndIndex{Cmd}{setpartpreamble}% +\EndIndex{Cmd}{setchapterpreamble}% + + +\begin{Declaration} + \Macro{dictum}\OParameter{author}\Parameter{dictum}\\ + \Macro{dictumwidth}\\ + \Macro{dictumauthorformat}\Parameter{author}\\ + \Macro{raggeddictum}\\ + \Macro{raggeddictumtext}\\ + \Macro{raggeddictumauthor} +\end{Declaration}% +\BeginIndex{Cmd}{dictum}% +\BeginIndex{Cmd}{dictumwidth}% +\BeginIndex{Cmd}{dictumauthorformat}% +\BeginIndex{Cmd}{raggeddictum}% +\BeginIndex{Cmd}{raggeddictumtext}% +\BeginIndex{Cmd}{raggeddictumauthor}% +Apart\OnlyAt{\Class{scrbook}\and\Class{scrreprt}}% +\ChangedAt{v2.8q}{\Class{scrbook}\and\Class{scrreprt}} from an +introducing paragraph you can use \Macro{setpartpreamble} or +\Macro{setchapterpreamble} for a kind of +\PName{aphorism}\Index{aphorism} (also known as ``dictum'') at the +beginning of a chapter or section. The command \Macro{dictum} inserts +such an aphorism. This macro can be used as obligatory argument of +either the command \Macro{setchapterpreamble} or +\Macro{setpartpreamble}. However, this is not obligatory. + +The dictum together with an optional \PName{author} is inserted in a +\Macro{parbox}\IndexCmd{parbox} (see \cite{latex:usrguide}) of the +width \Macro{dictumwidth}. Yet \Macro{dictumwidth} is not a length +which is set with \Macro{setlength}. It is a macro that can be +redefined using \Macro{renewcommand}. Default setting is +\verb;0.3333\textwidth;, which is a third of the textwidth. The box +itself is positioned with the command \Macro{raggeddictum}. Default +here is \Macro{raggedleft}\IndexCmd{raggedleft}. The command +\Macro{raggeddictum} can be redefined using \Macro{renewcommand}. + +Within the box the \PName{dictum} is set using +\Macro{raggeddictumtext}. Default setting is +\Macro{raggedright}\IndexCmd{raggedright}. Similar to +\Macro{raggeddictum} it can be redefined with \Macro{renewcommand}. +The output uses the default font which is set for the element +\FontElement{dictumtext}. It can be changed with the commands from +\autoref{sec:maincls.font}. Default settings are listed in +\autoref{tab:maincls.dictumfont}. + +If there is an \PName{author} it is separated from the \PName{dictum} +by a line with the width of the \Macro{parbox}. This is defined by the +macro \Macro{raggeddictumauthor}. Default is \Macro{raggedleft}. This +command can also be redefined using \Macro{renewcommand}. The format +of the output is defined with \Macro{dictumauthorformat}. This macro +expects the \Macro{author} as argument. As default +\Macro{dictumauthorformat} is defined as: +\begin{small} +\begin{verbatim} + \newcommand*{\dictumauthorformat}[1]{(#1)} +\end{verbatim} +\end{small} +Thus the \PName{author} is set in in round parenthesis. For the +element \FontElement{dictumauthor} a different font as for the element +\FontElement{dictumtext} can be defined. Default settings are listed +in \autoref{tab:maincls.dictumfont}. Changes can be made using the +commands from \autoref{sec:maincls.font}. +% +\begin{table} + \centering% + \begin{tabular}{ll} + Element & Default \\\hline\\[-1.6ex] + \FontElement{dictumtext} & + \Macro{normalfont}\Macro{normalcolor}\Macro{sffamily}\Macro{small}\\ + \FontElement{dictumauthor} & + \Macro{itshape}\\ + \end{tabular} + \caption{Default settings for the elements of a dictum} + \label{tab:maincls.dictumfont} +\end{table} +% +If \Macro{dictum} is used within the macro \Macro{setchapterpreamble} +or \Macro{setpartpreamble} you have to take care of the following: The +horizontal positioning is always done with \Macro{raggeddictum}. +Therefore, the optional argument for horizontal positioning, which is +implemented for these two commands, has no effect. \Macro{textwidth} +is not the width of the whole text corpus but the actually used text +width. If \Macro{dictumwidth} is set to \verb;.5\textwidth; and +\Macro{setchapterpreamble} has an optional width of +\verb;.5\textwidth; too, you will get a box with a width of a quarter +of the text width. Therefore, if you use \Macro{dictum} it is +recommended to refrain from setting the optional width for +\Macro{setchapterpreamble} or \Macro{setpartpreamble}. + +If you have more than one dictum you should separate them by an +additional vertical space. You could easely use the command +\Macro{bigskip}\IndexCmd{bigskip} for that. + +\begin{Example} + You are writing a chapter on an aspect of weather forecasting. You + have come across an aphorism which you would like to place at the + beginning of the chapter beneath the heading. You could write: + \begin{small} +\begin{verbatim} + \setchapterpreamble[u]{% + \dictum[Anonymous]{Forecasting is the art of saying + what is going to happen and then to explain + why it didn't.}} + \chapter{Weather forecasting} +\end{verbatim} + \end{small} + The output would look as follows: + \begin{ShowOutput} + {\usekomafont{sectioning}\usekomafont{chapter}% + 17\enskip Weather forecasting\par} \vspace{\baselineskip} + \dictum[Anonymous]{Forecasting is the art of saying what is going to + happen and then to explain why it didn't.} + \end{ShowOutput} + + If you would rather prefer the dictum to span over only a quarter of + the text width you can redefine \Macro{dictumwidth}: + \begin{small} +\begin{verbatim} + \renewcommand*{\dictumwidth}{.25\textwidth} +\end{verbatim} + \end{small} +\end{Example} + +For a somewhat more sophisticated formatting of left- or right-aligned +paragraphs including hyphenation you can use the +package~\Package{ragged2e}~\cite{package:ragged2e}. +\EndIndex{Cmd}{dictum}% +\EndIndex{Cmd}{dictumwidth}% +\EndIndex{Cmd}{dictumauthorformat}% +\EndIndex{Cmd}{raggeddictum}% +\EndIndex{Cmd}{raggeddictumtext}% +\EndIndex{Cmd}{raggeddictumauthor}% + + +\subsection{Footnotes} +\label{sec:maincls.footnotes} + +Footnotes are not limited to the main part of the document. Since +footnotes\Index{footnotes} are mainly used in the main text they are +being covered in this section. + +\begin{Declaration} + \Macro{footnote}\OParameter{number}\Parameter{text}\\ + \Macro{footnotemark}\OParameter{number}\\ + \Macro{footnotetext}\OParameter{number}\Parameter{text} +\end{Declaration}% +\BeginIndex{Cmd}{footnote}% +\BeginIndex{Cmd}{footnotemark}% +\BeginIndex{Cmd}{footnotetext}% +Similar to the standard classes footnotes in {\KOMAScript} are +produced with the \Macro{footnote} command. +An alternative is the usage in pairs of the commands +\Macro{footnotemark} and \Macro{footnotetext}. +As in the standard classes it is possible that a page break occurs +within a footnote. Normally this happens if the footnote mark is +placed near the bottom of a page thus leaving \LaTeX\ no choice as to +break the page at this point. +% +\EndIndex{Cmd}{footnote}% +\EndIndex{Cmd}{footnotemark}% +\EndIndex{Cmd}{footnotetext}% + + +\begin{Declaration} + \Macro{deffootnote}\OParameter{mark width}% + \Parameter{indent}% + \Parameter{parindent}\Parameter{definition}\\ + \Macro{deffootnotemark}\Parameter{definition}\\ + \Macro{thefootnotemark}\\ + \Macro{textsuperscript}\Parameter{text} +\end{Declaration}% +\BeginIndex{Cmd}{deffootnote}% +\BeginIndex{Cmd}{deffootnotemark}% +\BeginIndex{Cmd}{thefootnotemark}% +\BeginIndex{Cmd}{textsuperscript}% +Formatting footnotes in {\KOMAScript} is slightly different to the +standard classes. As in the standard classes the footnote mark in the +text is formed as a small number in superscript. The same formatting +is used in the footnote itself. + +The mark in the footnote is type-set right-aligned in a box +with width \PName{mark width}. The first line of the footnote +follows directly. + +All following lines will be indented by the length of +\PName{indent}. If the optional parameter \PName{mark width} +was not specified, then it defaults to \PName{indent}. +If the footnote consists of more than one paragraph, then the +first line of a paragraph is indented in addition to \PName{indent} +by the value of \PName{parindent}. +\begin{figure} +\centering\setlength{\unitlength}{1mm} +\begin{picture}(100,22) + \thinlines + % frame of following paragraph + \put(5,0){\line(1,0){90}} + \put(5,0){\line(0,1){5}} + \put(10,5){\line(0,1){5}}\put(5,5){\line(1,0){5}} + \put(95,0){\line(0,1){10}} + \put(10,10){\line(1,0){85}} + % frame of first paragraph + \put(5,11){\line(1,0){90}} + \put(5,11){\line(0,1){5}} + \put(15,16){\line(0,1){5}}\put(5,16){\line(1,0){10}} + \put(95,11){\line(0,1){10}} + \put(15,21){\line(1,0){80}} + % box of the footnote mark + \put(0,16.5){\framebox(14.5,4.5){\mbox{}}} + % description of paragraphs + \put(45,16){\makebox(0,0)[l]{\textsf{first paragraph of a footnote}}} + \put(45,5){\makebox(0,0)[l]{\textsf{next paragraph of a footnote}}} + % help lines + \thicklines + \multiput(0,0)(0,3){7}{\line(0,1){2}} + \multiput(5,0)(0,3){3}{\line(0,1){2}} + % parameters + \put(2,7){\vector(1,0){3}} + \put(5,7){\line(1,0){5}} + \put(15,7){\vector(-1,0){5}} + \put(15,7){\makebox(0,0)[l]{\small\PName{parindent}}} + % + \put(-3,13){\vector(1,0){3}} + \put(0,13){\line(1,0){5}} + \put(10,13){\vector(-1,0){5}} + \put(10,13){\makebox(0,0)[l]{\small\PName{indent}}} + % + \put(-3,19){\vector(1,0){3}} + \put(0,19){\line(1,0){14.5}} + \put(19.5,19){\vector(-1,0){5}} + \put(19.5,19){\makebox(0,0)[l]{\small\PName{mark width}}} +\end{picture} +\caption{Parameters that control the footnote layout} +\label{fig:maincls.deffootnote} +\end{figure} + +Figure \ref{fig:maincls.deffootnote} illustrates the layout parameters +ones more. The default configuration of \KOMAScript{} is: +\begin{verbatim} + \deffootnote[1em]{1.5em}{1em} + {\textsuperscript{\thefootnotemark}} +\end{verbatim} +\Macro{textsuperscript} causes both the superscript and the smaller +font size. \Macro{thefootnotemark} is the current footnote mark +without any formatting. + +The\ChangedAt{v2.8q}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} font element +\FontElement{footnote}\IndexFontElement{footnote} determines the font +of the footnote including the footnote mark. Using the element +\FontElement{footnotelabel}\IndexFontElement{footnotelabel} the font +of the footnote mark can be changed separately with the commands +mentioned in \autoref{sec:maincls.font} Please refer also to the +\autoref{tab:maincls.elementsWithoutText}. Default setting is no +changing of the font. + +The footnote mark in the text is defined separately with +\Macro{deffootnotemark}. Default setting is: +\begin{verbatim} + \deffootnotemark{% + \textsuperscript{\thefootnotemark}} +\end{verbatim} +Above\ChangedAt{v2.8q}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} the font +for the element +\FontElement{footnotereference}\IndexFontElement{footnotereference} is +applied (see \autoref{tab:maincls.elementsWithoutText}). Thus the +footnote marks in the text and the footnote itself are identical. The +font can be changed with the commands described in +\autoref{sec:maincls.font}. + +\begin{Example} + A feature often asked for are footnote marks which are neither in + superscript nor in a smaller font size. They should not touch the + footnote text but have a small space in between. This can be + accomplished as follows: + \begin{small} +\begin{verbatim} + \deffootnote{1.5em}{1em}{\thefootnotemark\ } +\end{verbatim} + \end{small} + The footnote mark and the space is set right-aligned into a + box of the width 1\Unit{em}. The following lines of the footnote + text is also indented by 1\Unit{em} from the left margin. + + Another often requested footnote layout are left-aligned + footnote marks. These can be reached with: + \begin{small} +\begin{verbatim} + \deffootnote{1.5em}{1em}{% + \makebox[1.5em][l]{\thefootnotemark}} +\end{verbatim} + \end{small} + + If you want however change the font for all footnotes, for example + to sans serif, you can simply solve this problem using the commands + from \autoref{sec:maincls.fontOptions}: + \begin{small} +\begin{verbatim} + \setkomafont{footnote}{\sffamily} +\end{verbatim} + \end{small} +\end{Example} +As demonstrated with the examples above the simple user interface of +{\KOMAScript} provides a great variety of different footnote +formattings. +% +\EndIndex{Cmd}{deffootnote}% +\EndIndex{Cmd}{deffootnotemark}% +\EndIndex{Cmd}{thefootnotemark}% +\EndIndex{Cmd}{textsuperscript}% + + +\subsection{Lists} +\label{sec:maincls.lists} \BeginIndex[indexother]{}{lists} + +Both {\LaTeX} and the standard classes offer different environments +for lists. Though slightly changed or extended all these list are of +course offered in {\KOMAScript} as well. In general all lists -- even +of different kind -- can be nested up to four levels. From a +typographical view, anything more would make no sense. Even more than +three levels are hard to perceive. Recommendation in these cases is to +split your huge list in several small ones. + +\begin{Declaration} + \Environment{itemize}\\ + \Macro{item}\\ + \Macro{labelitemi}\\ + \Macro{labelitemii}\\ + \Macro{labelitemiii}\\ + \Macro{labelitemiv} +\end{Declaration}% +\BeginIndex{Env}{itemize}% +\BeginIndex{Cmd}{item}% +\BeginIndex{Cmd}{labelitemi}% +\BeginIndex{Cmd}{labelitemii}% +\BeginIndex{Cmd}{labelitemiii}% +\BeginIndex{Cmd}{labelitemiv}% +The most simple form of a list is an \Environment{itemize} list. +Depending on the level {\KOMAScript} uses the following marks: +"`{\labelitemi}"', "`{\labelitemii}"', "`{\labelitemiii}"' and +"`{\labelitemiv}"'. The definition of these symbols is specified in +the macros \Macro{labelitemi}, \Macro{labelitemii}, +\Macro{labelitemiii} and \Macro{labelitemiv}. All of this macros can +be redefined using \Macro{renewcommand}. Every item is introduced with +\Macro{item}. +\begin{Example} + You have a simple list which is nested in several levels. You write + for example: + \begin{small} +\begin{verbatim} + \minisec{Vehicles} + \begin{itemize} + \item aeroplans + \begin{itemize} + \item biplane + \item jets + \item transport planes + \begin{itemize} + \item single-engined + \begin{itemize} + \item{jet-driven} + \item{propeller-driven} + \end{itemize} + \item multi-engined + \end{itemize} + \item helicopter + \end{itemize} + \item automobiles + \begin{itemize} + \item racing car + \item private car + \item lorry + \end{itemize} + \item bicycles + \end{itemize} +\end{verbatim} + \end{small} + As output you get: + \begin{ShowOutput}[\baselineskip] + \minisec{Vehicles} + \begin{itemize} + \item aeroplans + \begin{itemize} + \item biplane + \item jets + \item transport planes + \begin{itemize} + \item single-engined + \begin{itemize} + \item{jet-driven} + \item{propeller-driven} + \end{itemize} + \item multi-engined + \end{itemize} + \item helicopter + \end{itemize} + \item automobiles + \begin{itemize} + \item racing car + \item private car + \item lorry + \end{itemize} + \item bicycles + \end{itemize} + \end{ShowOutput} +\end{Example} +% +\EndIndex{Env}{itemize}% +\EndIndex{Cmd}{item}% +\EndIndex{Cmd}{labelitemi}% +\EndIndex{Cmd}{labelitemii}% +\EndIndex{Cmd}{labelitemiii}% +\EndIndex{Cmd}{labelitemiv}% + + +\begin{Declaration} + \Environment{enumerate}\\ + \Macro{item}\\ + \Macro{theenumi}\\ + \Macro{theenumii}\\ + \Macro{theenumiii}\\ + \Macro{theenumiv}\\ + \Macro{labelenumi}\\ + \Macro{labelenumii}\\ + \Macro{labelenumiii}\\ + \Macro{labelenumiv} +\end{Declaration}% +\BeginIndex{Env}{enumerate}% +\BeginIndex{Cmd}{item}% +\BeginIndex{Cmd}{theenumi}% +\BeginIndex{Cmd}{theenumii}% +\BeginIndex{Cmd}{theenumiii}% +\BeginIndex{Cmd}{theenumiv}% +\BeginIndex{Cmd}{labelenumi}% +\BeginIndex{Cmd}{labelenumii}% +\BeginIndex{Cmd}{labelenumiii}% +\BeginIndex{Cmd}{labelenumiv}% +Another form of a list often used is a numbered list which is already +implemented by the {\LaTeX} kernel. Depending on the level the +numbering\Index{numbering} uses the following characters: arabic +numbers, small letters, small roman numerals and capital letters. The +kind of numbering is defined with the macros \Macro{theenumi} down to +\Macro{theenumiv}. The output format is determined by the macros +\Macro{labelenumi} to \Macro{labelenumiv}. While the small letter of +the second level is followed by a round parenthesis, the values of all +other levels are followed by a dot. Every item is introduced with +\Macro{item}. +\begin{Example} + Replacing every occurence of an \Environment{itemize} environment + with an \Environment{enumerate} environment in the example above we + get the following result: + \begin{ShowOutput}[\baselineskip] + \minisec{Vehicles} + \begin{enumerate} + \item aeroplans + \begin{enumerate} + \item biplane + \item jets + \item transport planes + \begin{enumerate} + \item single-engined + \begin{enumerate} + \item{jet-driven}\label{xmp:maincls.jets} + \item{propeller-driven} + \end{enumerate} + \item multi-engined + \end{enumerate} + \item helicopter + \end{enumerate} + \item automobiles + \begin{enumerate} + \item racing car + \item private car + \item lorry + \end{enumerate} + \item bicycles + \end{enumerate} + \end{ShowOutput} + Using \Macro{label} within a list you can set labels which are + referenced with \Macro{ref}. In the example above a label + was set after the jet-driven, single-engined transport plane with + \Macro{label}\PParameter{xmp:jets}. The \Macro{ref} value is then + \ref{xmp:maincls.jets}. +\end{Example} +% +\EndIndex{Env}{enumerate}% +\EndIndex{Cmd}{item}% +\EndIndex{Cmd}{theenumi}% +\EndIndex{Cmd}{theenumii}% +\EndIndex{Cmd}{theenumiii}% +\EndIndex{Cmd}{theenumiv}% +\EndIndex{Cmd}{labelenumi}% +\EndIndex{Cmd}{labelenumii}% +\EndIndex{Cmd}{labelenumiii}% +\EndIndex{Cmd}{labelenumiv}% + + +\begin{Declaration} + \Environment{description}\\ + \Macro{item}\OParameter{item} +\end{Declaration}% +\BeginIndex{Env}{description}% +\BeginIndex{Cmd}{item}% +Another list form is the description list. Its main use is the +description of several items. The item itself is an optional parameter +in \Macro{item}. The font\Index{font}\ChangedAt{v2.8p}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}}% +, which is responsible for emphasizing the item can be changed with +the commands for the element +\FontElement{descriptionlabel}\IndexFontElement{descriptionlabel} (see +\autoref{tab:maincls.elementsWithoutText}) described in +\autoref{sec:maincls.font}. Default setting is +\Macro{sffamily}\Macro{bfseries}. +\begin{Example} + Instead of items in sans serif and bold you want them printed in the + standard font in bold. Using + \begin{small} +\begin{verbatim} + \setkomafont{descriptionlabel}{\normalfont\bfseries} +\end{verbatim} + \end{small} + you redefine the font accordingly. + + An example for a description list is the output of the page styles + listed in \autoref{sec:maincls.pageStyle}. The heavily + abbreviated source code is: + \begin{small} +\begin{verbatim} + \begin{description} + \item[empty] is the page style without + any header or footer + \item[plain] is the page style without running headline. + \item[headings] is the page style with running headline. + \item[myheadings] is the page style for manual headline. + \end{description} +\end{verbatim} + \end{small} + This abbreviated version gives: + \begin{ShowOutput} + \begin{description} + \item[empty] is the page style without any header or footer + \item[plain] is the page style without running headline. + \item[headings] is the page style with running headline. + \item[myheadings] is the page style for manual headline. + \end{description} + \end{ShowOutput} +\end{Example} +% +\EndIndex{Env}{description}% +\EndIndex{Cmd}{item}% + + +\begin{Declaration} + \Environment{labeling}\OParameter{delimiter}\Parameter{widest pattern}\\ + \Macro{item}\OParameter{key word} +\end{Declaration}% +\BeginIndex{Env}{labeling}% +\BeginIndex{Cmd}{item}% +An additional form of a description list in {\KOMAScript} is the +\Environment{labeling} environment. In difference to the +\Environment{description} environment you can provide a pattern, which +determines the indentation of all items. Furthermore you can put an +optional \PName{delimiter} between item and description. +\begin{Example} + Slightly changing the example from the \Environment{description} + environment we could write: + \begin{small} +\begin{verbatim} + \begin{labeling}[~--]{% + \usekomafont{descriptionlabel}myheadings} + \item[\usekomafont{descriptionlabel}empty] + Page style without header and footer + \item[\usekomafont{descriptionlabel}plain] + Page style for chapter beginnings without headline + \item[\usekomafont{descriptionlabel}headings] + Page style for running headline + \item[\usekomafont{descriptionlabel}myheadings] + Page style for manual headline + \end{labeling} +\end{verbatim} + \end{small} + As result we get: + \begin{ShowOutput} + \begin{labeling}[~--]{\usekomafont{descriptionlabel}myheadings} + \item[\usekomafont{descriptionlabel}empty] + Page style without header and footer + \item[\usekomafont{descriptionlabel}plain] + Page style for chapter beginnings without headline + \item[\usekomafont{descriptionlabel}headings] + Page style for running headline + \item[\usekomafont{descriptionlabel}myheadings] + Page style for manual headline + \end{labeling} + \end{ShowOutput} + As can be seen in this example a font changing command has to be + repeated both in the pattern and in the optional parameter in every + \Macro{item} command in this environment. +\end{Example} +Originally this environment was implemented for things like ``Given +is\dots, Asked is\dots, Solution'' that are often used in hand-outs. +By now this environment has found many different applications. For +example the environment for examples in this guide was defined with +the \Environment{labeling} environment. +% +\EndIndex{Env}{labeling}% +\EndIndex{Cmd}{item}% + + +\begin{Declaration} + \Environment{verse} +\end{Declaration}% +\BeginIndex{Env}{verse}% +Normally the \Environment{verse} environment isn't perceived as a list +environment because you don't work with \Macro{item} commands. Instead +fixed line breaks are used like within the \Environment{flushleft} +environment. Yet internally in both the standard classes as well +as {\KOMAScript} it is a list environment. + +In general the \Environment{verse} environment is used for +poems\Index{poems}. Lines are indented both left and right. Single +verses are ended by a fixed line break \verb|\\|. Verses are set as a +paragraph, thus separated by an empty line. Often also +\Macro{medskip}\IndexCmd{medskip} or \Macro{bigskip}\IndexCmd{bigskip} +is used instead. To avoid a page break at the end of a line you insert +\verb|\\*| instead of \verb|\\|. +\begin{Example} + As example the first lines of ``Little Red Riding Hood and the + Wolf'' by Roald Dahl: + \begin{small} +\begin{verbatim} + \begin{verse} + As soon as Wolf began to feel\\* + that he would like a decent meal,\\* + He went and knocked on Grandma's door.\\* + When Grandma opened it, she saw\\* + The sharp white teeth, the horrid grin,\\* + And Wolfie said, 'May I come in?' + \end{verse} +\end{verbatim} + \end{small} + The result would like as follows: + \begin{ShowOutput} + \begin{verse} + As soon as Wolf began to feel\\* + That he would like a decent meal,\\* + He went and knocked on Grandma's door.\\* + When Grandma opened it, she saw\\* + The sharp white teeth, the horrid grin,\\* + And Wolfie said, 'May I come in?' + \end{verse} + \end{ShowOutput} + Yet if you have very long lines \verb|\\*| can not prevent a page + break within a verse. That would be possible here for example: + \begin{ShowOutput} + \begin{verse} + Both the philosoph and the house-owner have always + something to repair\\ + \bigskip + Don't trust a men, my son, who tells you that he has never lain. + \end{verse} + \end{ShowOutput} + + These two verses were separated by a \Macro{bigskip}. +\end{Example} +% +\EndIndex{Env}{verse}% + + +\begin{Declaration} + \Environment{quote}\\ + \Environment{quotation} +\end{Declaration}% +\BeginIndex{Env}{quote}% +\BeginIndex{Env}{quotation}% +These two environments are also list environments and can be found +both in the standard and the {\KOMAScript} classes. Both environments +use justified text which is indented both on the left and right side. +Usually they are used to separate long citations\Index{citations} from +the main text. The difference between these two lies in the matter how +paragraphs are typeset. While \Environment{quote} paragraphs are +highlighted by vertical space, in \Environment{quotation} paragraphs +the first line is indented. This is also true for the first line of a +\Environment{quotation} environment. To get around this behaviour you +have to insert a \Macro{noindent} command\IndexCmd{noindent} in front. +\begin{Example} + You want to highlight a short anecdote. You write the following + \Environment{quotation} environment for this: + % + \begin{small} +\begin{verbatim} + A small example for a short anecdote: + \begin{quotation} + The old year was turning brown; the West Wind was + calling; + + Tom caught the beechen leaf in the forest falling. + ``I've caught the happy day blown me by the breezes! + Why wait till morrow-year? I'll take it when me pleases. + This I'll mend my boat and journey as it chances + west down the withy-stream, following my fancies!'' + + Little Bird sat on twig. ``Whillo, Tom! I heed you. + I've a guess, I've a guess where your fancies lead you. + Shall I go, shall I go, bring him word to meet you?'' + \end{quotation} +\end{verbatim} + \end{small} + The result is: + \begin{ShowOutput} + A small example for a short anecdote: + \begin{quotation} + The old year was turning brown; the West Wind was + calling; + + Tom caught the beechen leaf in the forest falling. + ``I've caught the happy day blown me by the breezes! + Why wait till morrow-year? I'll take it when me pleases. + This I'll mend my boat and journey as it chances + west down the withy-stream, following my fancies!'' + + Little Bird sat on twig. ``Whillo, Tom! I heed you. + I've a guess, I've a guess where your fancies lead you. + Shall I go, shall I go, bring him word to meet you?'' + \end{quotation} + \end{ShowOutput} + % + Using a \Environment{quote} environment instead you get: + % + \begin{ShowOutput} + A small example for a short anecdote: + \begin{quote}\setlength{\parskip}{4pt plus 2pt minus 2pt} + The old year was turning brown; the West Wind was + calling; + + Tom caught the beechen leaf in the forest falling. + ``I've caught the happy day blown me by the breezes! + Why wait till morrow-year? I'll take it when me pleases. + This I'll mend my boat and journey as it chances + west down the withy-stream, following my fancies!'' + + Little Bird sat on twig. ``Whillo, Tom! I heed you. + I've a guess, I've a guess where your fancies lead you. + Shall I go, shall I go, bring him word to meet you?'' + \end{quote} + \end{ShowOutput} + % +\end{Example} +% +\EndIndex{Env}{quote}% +\EndIndex{Env}{quotation}% + + + +\begin{Declaration} + \Environment{addmargin}\OParameter{left indentation}\Parameter{indentation}\\ + \Environment{addmargin*}\OParameter{inner indentation}\Parameter{indentation} +\end{Declaration} +\BeginIndex{Env}{addmargin}% +Similar to \Environment{quote} and \Environment{quotation} the +\Environment{addmargin} environment changes the margin\Index{margin}. +Different to the first two environments using \Environment{addmargin} +the user can influence the width of the indentation. Furthermore this +environment doesn't change the indentation of the first line and the +vertical spacing between paragraphs. + +If only the obligatory argument \PName{indentation} is given, both the +left and right margin are expanded by this value. If the optional +argument \PName{indentation} is given the value \PName{left + indentation} is added to \PName{indentation} at the left margin. + +The starred \Environment{addmargin*} only differs from the normal +version in a twoside layout. In addition the difference only occurs if +the optional argument \PName{inner indentation} is used. In this case +this value is added to the normal inner indentation. Then the value of +\PName{indentation} determines the width of the opposite margin. + +Both versions of this environment take also negative values for all +parameters. This has the effect of expanding the environment into the +margin. +\begin{Example} + Suppose you write a documentation which includes short source code + examples. To highlight these you want them separated from the text + by a horizontal line and slightly spanning into the outer + margin. First you define the environment: + \begin{small} +\begin{verbatim} + \newenvironment{SourceCodeFrame}{% + \begin{addmargin*}[1em]{-1em}% + \begin{minipage}{\linewidth}% + \rule{\linewidth}{2pt}% + }{% + \rule[.25\baselineskip]{\linewidth}{2pt}% + \end{minipage}% + \end{addmargin*}% + } +\end{verbatim} + \end{small} + If you now put your source code in such an environment it will show + up as: + \begin{ShowOutput} + \newenvironment{SourceCodeFrame}{% + \begin{addmargin*}[1em]{-1em}% + \begin{minipage}{\linewidth}% + \rule{\linewidth}{2pt}% + }{% + \rule[.25\baselineskip]{\linewidth}{2pt}% + \end{minipage}% + \end{addmargin*}% + } + You define yourself the following environment: + \begin{SourceCodeFrame} +\begin{verbatim} +\newenvironment{\SourceCodeFrame}{% + \begin{addmargin*}[1em]{-1em}% + \begin{minipage}{\linewidth}% + \rule{\linewidth}{2pt}% +}{% + \rule[.25\baselineskip]{\linewidth}{2pt}% + \end{minipage}% + \end{addmargin*}% +} +\end{verbatim} + \end{SourceCodeFrame} + This may be feasible or not. In any way it shows the usage of this + environment. + \end{ShowOutput} + The optional argument of the \Environment{addmargin*} environment + makes sure that the inner margin is extended by 1\Unit{em}. In turn + the outer margin is decreased by 1\Unit{em}. The result is a shift + by 1\Unit{em} to the outside. Instead of \PValue{1em} you can use a + length of, for example, \PValue{2\Macro{parindent}} of course. +\end{Example} +There is one problem with the \Environment{addmargin*} which you +should be aware of. If a page break occurs within an +\Environment{addmargin*} environment the indentation on the following +page is on the wrong side. This means that suddenly the \PName{inner + indentation} is applied on the outside of the page. Therefore it is +recommended to prevent page breaks within this environment. This can +be achieved by using an additional \Macro{parbox} or, as in the +example above, a \Environment{minipage}. This makes use of the fact +that neither the argument of a \Macro{parbox} nor the content of a +\Environment{minipage} is broken at the end of a page. Unfortunately +this is not without disadvantages: In some cases pages can't be filled +correctly which has the effect of several warnings. + +By the way, whether a page is going to be on the left or right side of +the book can't be determined in the first \LaTeX\ compiling for sure. +For details please refer to the explanation for the command +\Macro{ifthispageodd}. +% +\EndIndex{Env}{addmargin}% + + +\begin{Explain} + One concluding note to the list environments: In the internet and + support it is often asked why such an environment is followed by a + indented\Index{indentation} paragraph. In fact this is the result of + demanding a new paragraph. In \LaTeX\ empty lines are interpreted as + a new paragraph. This is also the case before and after list + environments. Thus, if you want a list environment to be set within + a paragraph you have to omit empty lines before and after. To + separate this environment from the rest of your text nevertheless, + you can insert a comment line which only consists of a percent + character in the {\LaTeX} source. +\end{Explain} +\EndIndex[indexother]{}{lists} + +\subsection{Margin Notes} +\label{sec:maincls.marginNotes} + +\begin{Declaration} + \Macro{marginpar}\OParameter{margin note left}\Parameter{margin note}\\ + \Macro{marginline}\Parameter{margin note} +\end{Declaration}% +\BeginIndex{Cmd}{marginpar}% +\BeginIndex{Cmd}{marginline}% +Usually margin notes\Index[indexmain]{margin notes} in {\LaTeX} are +inserted with the command \Macro{marginpar}. They are placed in the +outer margin. In documents with oneside layout the right border is +used. Though \Macro{marginpar} optionally can take a different margin +note in case the output is on the left margin, margin notes are always +in justified layout. But many users prefer left- or right-aligned +margin notes instead. {\KOMAScript} offers the command +\Macro{marginline} for that. +\begin{Example} + At several places in this documentation you find the classes mentioned + written in the margin. This can be produced\footnote{In fact, instead + of \Macro{texttt}, a semantic highlighting was used. To avoid confusion + this was replaced in the example.} with: + \begin{small} +\begin{verbatim} + \marginline{\texttt{scrartcl}} +\end{verbatim} + \end{small} + + Instead of \Macro{marginline} you could have used \Macro{marginpar} + too. In fact the first command is implemented internally as: +\begin{verbatim} + \marginpar[\raggedleft\texttt{scrartcl}] + {\raggedright\texttt{scrartcl}} +\end{verbatim} + Eventually \Macro{marginline} is only an abbreviating writing of the + code above. +\end{Example} +% +\begin{Explain} + Unfortunately \Macro{marginpar} doesn't always work correctly in the + twoside\Index{twoside} layout. Whether a margin note is going to show + up on the left or right is already decided while evaluating the command + \Macro{marginpar}. If the output routine now shifts the margin note + onto the next page the alignment isn't correct anymore. This behaviour + is deeply founded within {\LaTeX} and was therefore declared a feature + by the \LaTeX3 team. \Macro{marginline} suffers from this ``feature'' + too.\par +\end{Explain} +% +\EndIndex{Cmd}{marginpar}% +\EndIndex{Cmd}{marginline}% + + +\subsection{Tables and Figures} +\label{sec:maincls.floats} + +\begin{Explain} + With the floating environments {\LaTeX} offers a very capable and + comfortable mechanism for automatic placement of + figures\Index{figures} and tables\Index{tables}. But 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. As these floating + environments are being referenced in the text this is not necessary + in most cases. It is not sensible too because such an object can + only be set on the page if there is enough space left. If this is + not the case the object would have to be shifted onto the next page + leaving a huge space on the page before. + + Often in many documents the same optional argument for positioning + an object is found with every floating object. This also makes no + sense. In such cases you should change the standard parameters + globally. For more details refer to \cite{DANTE:FAQ}.\par +\end{Explain} + +One last important note before starting this section: The most +mechanisms described here which extend the capabilities of the +standard classes do not work correctly when used together with +packages which interfere with the typesetting of captions of figures +and tables. This should be without saying but is often neglected. + +\begin{Declaration} + \Macro{caption}\OParameter{entry}\Parameter{title}\\ + \Macro{captionbelow}\OParameter{entry}\Parameter{title}\\ + \Macro{captionabove}\OParameter{entry}\Parameter{title} +\end{Declaration}% +\BeginIndex{Cmd}{caption}% +\BeginIndex{Cmd}{captionabove}% +\BeginIndex{Cmd}{captionbelow}% +In the standard classes captions of tables and figures are inserted +with the \Macro{caption} command below the table or figure. In general +this is correct with figures. Opinions differ as to whether captions +of tables are to be placed above or together with captions of +figures\Index{captions of figures} below the table\Index{captions of + tables}. That's the reason why \KOMAScript{}, unlike the standard +classes, offers \Macro{captionbelow} for captions below and +\Macro{captionabove} for captions above tables or figures. Using +\Macro{caption} together with figures always produces captions below +the figure whereas the behaviour of \Macro{captionbelow} can be +modified using the options +\Option{tablecaptionabove}\IndexOption{tablecaptionabove} and +\Option{tablecaptionbelow}\IndexOption{tablecaptionbelow} (see +\autoref{sec:maincls.formattingOptions}). For compatibility +reasons the default behaviour of \Macro{caption} together with tables +is similar to \Macro{captionbelow}. +% +\begin{Example} + Instead of using captions below the table you want to place your + captions above it\Index{table caption}, because you have tables + which span over more then one page. In the standard classes you + could only write: + \begin{small} +\begin{verbatim} + \begin{table} + \caption{This is an example table} + \begin{tabular}{llll} + This & is & an & example.\\\hline + This & is & an & example.\\ + This & is & an & example. + \end{tabular} + \end{table} +\end{verbatim} + \end{small} + Then you would get the unsatisfying result: + \begin{ShowOutput}\centering + {\usekomafont{caption}{\usekomafont{captionlabel}\tablename~30.2:} + This is an example table.}\\ + \begin{tabular}{llll} + This & is & an & example.\\\hline + This & is & an & example.\\ + This & is & an & example. + \end{tabular} +\end{ShowOutput} + Using \KOMAScript{} you write instead: + \begin{small} +\begin{verbatim} + \begin{table} + \captionabove{This is just an example table} + \begin{tabular}{llll} + This & is & an & example.\\\hline + This & is & an & example.\\ + This & is & an & example. + \end{tabular} + \end{table} +\end{verbatim} + \end{small} + Then you get: + \begin{ShowOutput}\centering + {\usekomafont{caption}{\usekomafont{captionlabel}\tablename~30.2:} + This is just an example table}\\\vskip\abovecaptionskip + \begin{tabular}{llll} + This & is & an & example.\\\hline + This & is & an & example.\\ + This & is & an & example. + \end{tabular} + \end{ShowOutput} + + Since you want all your tables typeset with captions above you could + of course use the option \Option{tablecaptionabove} instead (see + \autoref{sec:maincls.formattingOptions}). 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} + +\begin{Explain} + Some would argue that you could achieve the same result using the + \Macro{topcaption} from the \Package{topcapt} + package\IndexPackage{topcapt} (see \cite{package:topcapt}). But that + is not the case. The command \Macro{topcaption} is neglected by + packages which directly redefine the \Macro{caption} macro. The + \Package{hyperref} package (see \cite{package:hyperref}) is one example + for this. In \KOMAScript{} \Macro{captionabove} and + \Macro{captionbelow} are implemented so, that the changes have an + effect on both of these commands. + + If the \Package{longtable} package\IndexPackage{longtable} is used + \KOMAScript{} makes sure that captions above tables which are placed + within a \Environment{longtable} environment have the same + appearance as in a normal \Environment{table} environment. This also + means that you can apply the same settings as in a + \Environment{table} environment. Please note that in the + \Package{longtable} package the maximum width of a table caption can + be limited and the default is set to 4\Unit{in} (see + \cite{package:longtable}). Using \KOMAScript{} this mechanism in + \Package{longtable} only works when the class option + \Option{origlongtable} is set (see + \autoref{sec:maincls.formattingOptions}). If + \Package{caption2}\IndexPackage{caption2} (see + \cite{package:caption2}) is loaded, table captions are handled by + this package. + + Please note that \Macro{captionabove} and \Macro{captionbelow} if placed + within a \Environment{float} environment which was defined using the + \Package{float}\IndexPackage{float} package have the same behaviour as + described in \cite{package:float} for the \Macro{caption} command. In this + case, only the float style determines whether it is a caption below or above + the figure or table. +\end{Explain} + + +\begin{Declaration} + \Environment{captionbeside}\OParameter{entry}% + \Parameter{title}\OParameter{placement}\OParameter{width}% + \OParameter{offset}\\% + \Environment{captionbeside}\OParameter{entry}% + \Parameter{title}\OParameter{placement}\OParameter{width}% + \OParameter{offset}\PValue{*} +\end{Declaration} +\BeginIndex{Env}{captionbeside}% +Apart\ChangedAt{v2.8q}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} from +captions above and below the figure you often find captions, in +particular with small figures, which are placed beside the figure. In +general in this case both the baseline of the figure and the caption +are aligned at the bottom. With some fiddling and the use of two +\Macro{parbox} commands this could be achieved in the standard +classes. But \KOMAScript{} offers a special environment for this +problem. This environment can be used within the floating environment. +The first optional parameter \PName{entry} and the obligatory +parameter \PName{title} are similar to the parameters of +\Macro{caption}, \Macro{captionabove} or \Macro{captionbelow}. The +\PName{title} is placed beside the content of the environment in this +case. + +Whether the \PName{title} is placed left or right can be determined by +the parameter \PName{placement}. One of the following letters is +accepted: +\begin{quote} +\begin{labeling}[--~]{\PValue[o]} +\item[\PValue{l}] left +\item[\PValue{r}] right +\item[\PValue{i}] inner margin in twoside layout +\item[\PValue{o}] outer margin in twoside layout +\end{labeling} +\end{quote} +Default setting is at the right side of the content of the +environment. If either \PValue{o} or \PValue{i} are used you have to +run {\LaTeX} twice to get the correct placement. + +As default the content of the environment and the \PName{title} fill +the whole available text width. However, using the optional parameter +\PName{width} it is possible to adjust the used width. This width +could even be more than the current text width. + +When supplying a \PName{width} the used width is 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} the value means +a shift relative to the right margin on left pages in double 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. + +\begin{Example} + An example for the usage of the \Environment{captionbeside} environment + can be found in \autoref{fig:maincls.captionbeside}. + This figure was typeset with: + \begin{small} +\begin{verbatim} + \begin{figure} + \begin{captionbeside}[Example for a figure description]% + {A figure description which is neither above nor + below, but beside the figure}[i][\linewidth][2em]* + \fbox{% + \parbox[b][5\baselineskip][c]{.25\textwidth}{% + \hspace*{\fill}\KOMAScript\hspace*{\fill}\par}} + \end{captionbeside} + \label{fig:maincls.captionbeside} + \end{figure} +\end{verbatim} + \end{small} + \begin{figure} + \begin{captionbeside}[Example for a figure description]% + {A figure description which is neither above nor + below, but beside the figure}[i][\linewidth][2em]* + \fbox{% + \parbox[b][5\baselineskip][c]{.25\textwidth}{% + \hspace*{\fill}\KOMAScript\hspace*{\fill}\par}} + \end{captionbeside} + \label{fig:maincls.captionbeside} + \end{figure} + Thus, the width is the current available width + \PValue{\Macro{linewidth}}. However, this width is shifted + \PValue{2em} to the outside. The title or the description is placed + inside beside the figure. Therefore, the figure itself is shifted + 2\Unit{em} into the margin. +\end{Example} +% +\EndIndex{Env}{captionbeside} + + +\BeginIndex[indexother]{}{font style} +The font style\ChangedAt{v2.8p}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} for the +description and the label~-- ``Figure'' or ``Table'' followed by the +number and the delimiter -- can be changed with the commands mentioned +in \autoref{sec:maincls.font}. The respective elements for this +are \FontElement{caption}\IndexFontElement{caption} and +\FontElement{captionlabel}\IndexFontElement{captionlabel} (see +\autoref{tab:maincls.elementsWithoutText}). First the font style +for the element \FontElement{caption} is applied on 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:maincls.captionFont}. +% +\begin{table} + \centering% + \begin{tabular}{ll} + element & default \\\hline\\[-1.75ex] + \FontElement{caption} & \Macro{normalfont} \\ + \FontElement{captionlabel} & \Macro{normalfont} + \end{tabular} + \caption{Font defaults for the elements of figure or table captions} + \label{tab:maincls.captionFont} +\end{table} +% +\begin{Example} + You want the table and figure descriptions typeset in a smaller font + size. Thus you could write the following in the preamble of your + document: + \begin{small} +\begin{verbatim} + \addtokomafont{caption}{\small} +\end{verbatim} + \end{small} + Furthermore, you would like the labels to be printed in sans serif and + bold. You add: + \begin{small} +\begin{verbatim} + \setkomafont{captionlabel}{\sffamily\bfseries} +\end{verbatim} + \end{small} + As you can see, simple extensions of the default definitions are + possible. +\end{Example} +\EndIndex[indexother]{}{font style} +% +\EndIndex{Cmd}{caption}% +\EndIndex{Cmd}{captionabove}% +\EndIndex{Cmd}{captionbelow}% + + +\begin{Explain} +\begin{Declaration} + \PValue{komaabove}\\ + \PValue{komabelow} +\end{Declaration}% +\BeginIndex{Floatstyle}{komaabove}% +\BeginIndex{Floatstyle}{komabelow}% +Using\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 the fact 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 both these +styles can be activated as the styles \PValue{plain}\IndexFloatstyle{plain}, +\PValue{boxed}\IndexFloatstyle{boxed} or \PValue{ruled}\IndexFloatstyle{ruled} +in \Package{float} are defined. For details refer to \cite{package:float}. +The style \PValue{komaabove} inserts \Macro{caption}, \Macro{captionabove} and +\Macro{captionbelow} above whereas \PValue{komabelow} inserts them below the +float content. +% +\EndIndex{Floatstyle}{komaabove}% +\EndIndex{Floatstyle}{komabelow}% +\end{Explain} + + +\begin{Declaration} + \Macro{captionformat} +\end{Declaration}% +\BeginIndex{Cmd}{captionformat}% +In {\KOMAScript} there are different ways to change the formatting of +the description. 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 difference to all other \Macro{\dots}format commands in this case +it doesn't contain the counter but the items which follow it. The +original definition is: +\begin{verbatim} + \newcommand*{\captionformat}{:\ } +\end{verbatim} +This too can be changed 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: + \begin{small} +\begin{verbatim} + \renewcommand*{\captionformat}{~--~} +\end{verbatim} + \end{small} + This definition you should put in the preamble of your document. +\end{Example} +% +\EndIndex{Cmd}{captionformat}% + + +\begin{Declaration} + \Macro{figureformat}\\ + \Macro{tableformat} +\end{Declaration}% +\BeginIndex{Cmd}{figureformat}% +\BeginIndex{Cmd}{tableformat}% +It was already mentioned that \Macro{captionformat} doesn't contain a +formatting for the label itself. But this label shouldn't in any case +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, for +example, of the list of figures. For this case {\KOMAScript} offers +two \Macro{\dots format} commands instead. These are predefined as +follows: +\begin{verbatim} + \newcommand*{\figureformat}{\figurename~\thefigure\autodot} + \newcommand*{\tableformat}{\tablename~\thetable\autodot} +\end{verbatim} +They also can be adapted to your personal preferences with +\Macro{renewcommand}. +\begin{Example} + From time to time label texts without any label and delimiter are + wanted. In {\KOMAScript} it takes only the following definitions to + achieve this: + \begin{small} +\begin{verbatim} + \renewcommand*{\figureformat}{} + \renewcommand*{\tableformat}{} + \renewcommand*{\captionformat}{} +\end{verbatim} + \end{small} +\end{Example} +% +\EndIndex{Cmd}{figureformat}% +\EndIndex{Cmd}{tableformat}% + +\begin{Declaration} + \Macro{setcapindent}\Parameter{indent}\\ + \Macro{setcapindent*}\Parameter{xindent}\\ + \Macro{setcaphanging} +\end{Declaration}% +\BeginIndex{Cmd}{setcapindent}% +\BeginIndex{Cmd}{setcapindent*}% +\BeginIndex{Cmd}{setcaphanging}% +As mentioned previously, in the standard classes the captions are set +in a not-hanging style. That means that in descriptions with more than +one line the second and subsequent lines start directly beneath the +label. There is no straight way in the standard classes to change +this behaviour. In {\KOMAScript}, on the contrary, beginning at the +second line all lines are indented by the width of the label. + +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{Einzug} determines +the indentation of the second and subsequent lines. + +If you want a line break before the label and the description you +define the indentation \PName{xindent} of the description with the +starred version of the command instead: \Macro{setcapindent*}. + +Using a negative value of \PName{indent} instead, a page break is +inserted and only the first line but not the subsequent lines are +indented by \(-\PName{indent}\). + +Whether one-line captions are set as captions with more than one line +or are treated separately is specified with the class options +\Option{onelinecaption} and \Option{noonelinecaption}. For details +please refer to the explanations of this options in +\autoref{sec:maincls.layoutOptions}. + +\begin{Example} + As examples please refer to the + figures~\ref{fig:maincls.caption.first} to + \ref{fig:maincls.caption.last}. As you can see the usage of a + complete hanging indentation is not preferable together with a small + column width: + \begin{small} +\begin{verbatim} + \begin{figure} + \setcapindent{1em} + \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} + \caption{Examples with slightly indented caption + starting at the second line} + \end{figure} +\end{verbatim} + \end{small} + As can be seen the formatting can also be changed locally within the + \Environment{figure} environment\IndexEnv{figure}. + \begin{figure} + \typeout{^^J--- Ignore underfull and overfull \string\hbox:} + \addtokomafont{caption}{\small} + \addtokomafont{captionlabel}{\bfseries} + \centering% + \begin{minipage}{.9\linewidth} + \begin{minipage}[t]{.48\linewidth}\sloppy + \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} + \caption[Example for figure caption]% + {\sloppy Equivalent to the standard setting, similar to the + usage of \Macro{setcaphanging}} + \label{fig:maincls.caption.first} + \end{minipage} + \hspace{.02\linewidth} + \begin{minipage}[t]{.48\linewidth}\sloppy + \setcapindent{1em} + \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} + \caption[Example for figure caption]% + {With slightly hanging indentation starting at the second line + using \Macro{setcapindent}\PParameter{1em}} + \end{minipage} + \end{minipage} + + \vspace*{2ex}\noindent% + \begin{minipage}{.9\linewidth} + \begin{minipage}[t]{.48\linewidth}\sloppy + \setcapindent*{1em} + \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} + \caption[Example for a figure caption]% + {With hanging indentation starting at the second line and line + break before the description using + \Macro{setcapindent*}\PParameter{1em}} + \end{minipage} + \hspace{.02\linewidth} + \begin{minipage}[t]{.48\linewidth}\sloppy + \setcapindent{-1em} + \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} + \caption[Example for a figure caption]% + {With indentation in the second line only and line break + before the description using + \Macro{setcapindent}\PParameter{-1em}} + \label{fig:maincls.caption.last} + \end{minipage} + \end{minipage} + \typeout{^^J--- Don't ignore underfull and overfull + \string\hbox:^^J} + \end{figure} +\end{Example} +% +\EndIndex{Cmd}{setcapindent}% +\EndIndex{Cmd}{setcapindent*}% +\EndIndex{Cmd}{setcaphanging}% + + +\begin{Declaration} + \Macro{setcapwidth}\OParameter{justification}\Parameter{width}\\ + \Macro{setcapmargin}\OParameter{margin left}\Parameter{margin}\\ + \Macro{setcapmargin*}\OParameter{margin inside}\Parameter{margin} +\end{Declaration} +\BeginIndex{Cmd}{setcapwidth}% +\BeginIndex{Cmd}{setcapmargin}% +\BeginIndex{Cmd}{setcapmargin*}% +Using\ChangedAt{v2.8q}{% + \Class{scrbook}\and\Class{scrreprt}\and\Class{scrartcl}} these three +commands you can specify the width and justification of the label +text. In general the whole text or column width is available for the +description. + +With the command \Macro{setcapwidth} you can decrease this +\PName{width}. The obligatory argument determines the \PName{with} of +the description. As an optional argument you can supply one letter +which specifies the horizontal justification. The possible +justifications are given in the following list. +\begin{quote} +\begin{labeling}[--~]{\PValue[o]} +\item[\PValue{l}] left-aligned +\item[\PValue{c}] centered +\item[\PValue{r}] right-aligned +\item[\PValue{i}] alignment at the inner margin in a double sided output +\item[\PValue{o}] alignment at the outer margin in a double sided output +\end{labeling} +\end{quote} +The justification inside and outside corresponds to left-aligned and +right-aligned respectively in single sided output. Within +\Package{longtable}\IndexPackage{longtable} tables the justification +inside or outside doesn't work correctly. In particular the captions +of tables of subsequent pages are aligned corresponding to the first +part of the table. This is a problem which has its roots in the +implementation of \Package{longtable}. + +With 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} +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 the option \Option{noonelinecaption} (see +\autoref{sec:maincls.layoutOptions}) for the descriptions which +are typeset with this margin setting. + +\begin{Explain} + \Package{longtable} places the description in a box, which is issued + again at the subsequent pages if needed. While treating a box the + macros needed for the creation of it aren't run through + again. That's why it is not possible for \KOMAScript{} to swop + margin settings in double sided layout on even pages. This would be + necessary to produce a justification which is shifted towards the + outside or inside. + + You can also submit negative values for \PName{margin} and + \PName{margin right} or \PName{margin outside}. This has the effect + of the description spanning into the margin. +\end{Explain} + +\begin{Example} + A rather odd problem is a figure caption which is both centered and + of the same width as the figure itself. If the width of the figure + is known the solution with \KOMAScript{} is quite easy. Suppose the + figure has a width of 8\Unit{cm}, it only takes: + \begin{small} +\begin{verbatim} + \setcapwidth[c]{8cm} +\end{verbatim} + \end{small} + directly in front of \Macro{caption} or \Macro{captionbelow}. If it + is unknown first you have to define a length in the preamble of your + document: + \begin{small} +\begin{verbatim} + \newlength{\figurewidth} +\end{verbatim} + \end{small} + Having done this you can calculate the width directly with the + \LaTeX{} command \Macro{settowidth} (see \cite{latex:usrguide}) + in many cases. A possible solution would look as follows: + \begin{small} +\begin{verbatim} + \begin{figure} + \centering% + \settowidth{\figurewidth}{% + \fbox{\hspace{1em}\KOMAScript\hspace{1em}}% + }% + \fbox{\hspace{1em}\KOMAScript\hspace{1em}}% + \setcapwidth[c]{\figurewidth} + \caption{Example of a centered caption below the figure} + \end{figure} +\end{verbatim} + \end{small} + However, it is awkward to write the content twice and to use + \Macro{setcapwidth} with every figure. But nothing is easier than + defining a new command in the preamble of your document which + hides the three steps: + \begin{enumerate} + \item Defining the width of the argument + \item Specifying the width of the caption + \item Output of the argument + \end{enumerate} + in: + \begin{small} +\begin{verbatim} + \newcommand{\figure2}[1]{% + \settowidth{\figurewidth}{#1}% + \setcapwidth[c]{\figurewidth}% + #1} +\end{verbatim} + \end{small} + Using this command the example abbreviates to: + \begin{small} +\begin{verbatim} + \begin{figure} + \centering% + \figure2{\fbox{\hspace{1em}\KOMAScript\hspace{1em}}}% + \caption{Example of a centered caption below the figure} + \end{figure} +\end{verbatim} + \end{small} + + But a command has the disadvantage that errors in the macros of the + argument in case of arguments with more than one line aren't + reported with the very correct line number by \LaTeX{}. In these + cases the usage of an environment has advantages. But then the + question is raised how the width of the content of the environment + can be determined. The solution offers the \Environment{lrbox} + environment, which is described in \cite{latex:usrguide}: + \begin{small} +\begin{verbatim} + \newsavebox{\figurebox} + \newenvironment{FigureDefinesCaptionWidth}{% + \begin{lrbox}{\figurebox}% + }{% + \end{lrbox}% + \global\setbox\figurebox=\box\figurebox% + \aftergroup\setfigurebox% + } + \newcommand{\setfigurebox}{% + \figure2{\usebox{\figurebox}}} +\end{verbatim} + \end{small} + This definition uses the macro \Macro{figure2} defined above. In + the main text you write: + \begin{small} +\begin{verbatim} + \begin{figure} + \centering% + \begin{FigureDefinesCaptionWidth} + \fbox{\hspace{1em}\KOMAScript\hspace{1em}} + \end{FigureDefinesCaptionWidth} + \caption{Example of a centered caption below the figure} + \end{figure} +\end{verbatim} + \end{small} + Admittingly, the environment in this example is not necessary. But + its definition using \Macro{global} is quite clever. Most users + wouldn't be able to define such an environment without help. But as + this can be very useful, it was introduced in the example above. + + If the \Environment{captionbeside} environment wouldn't exist you + could nevertheless place the figure caption beside the figure in a + quite simple way. For this \Macro{setfigurebox} from the example + above would have to be redefined first: + \begin{small} +\begin{verbatim} + \renewcommand{\setfigurebox}{% + \settowidth{\captionwidth}{\usebox{\figurebox}}% + \parbox[b]{\captionwidth}{\usebox{\figurebox}}% + \hfill% + \addtolength{\captionwidth}{1em}% + \addtolength{\captionwidth}{-\hsize}% + \setlength{\captionwidth}{-\captionwidth}% + \setcapwidth[c]{\captionwidth}% + } +\end{verbatim} + \end{small} + As the next step you only have to put the \Macro{caption} command in + a \Macro{parbox} too: + \begin{small} +\begin{verbatim} + \begin{figure} + \centering% + \begin{FigureSetsCaptionWidth} + \fbox{\rule{0pt}{5\baselineskip}% + \hspace{1em}\KOMAScript\hspace{1em}} + \end{FigureSetsCaptionWidth} + \parbox[b]{\figurewidth}{% + \caption{Example of a centered caption + below the figure} + } + \end{figure} +\end{verbatim} + \end{small} + The \Macro{rule} command in this example only serves as an unvisible + support to produce an example figure with a greater vertical height. +\end{Example} +% +\EndIndex{Cmd}{setcapwidth}% +\EndIndex{Cmd}{setcapmargin}% +\EndIndex{Cmd}{setcapmargin*}% + + +\subsection{Logical Markup of Text} +\label{sec:maincls.emphasis} + +\begin{Explain} + \LaTeX{} offers different possibilities for logical + markup\Index{logical markup}\Index{markup} of text. In a sense, a + heading is a kind of markup too. However, in this section we are + only concerned with direct markup, i.e. markup which doesn't have an + additional meaning and which can be used for different + purposes. More details to the normally defined possibilities you can + find in \cite{lshort}, \cite{latex:usrguide} and + \cite{latex:fntguide}. +\end{Explain} + +\begin{Declaration} + \Macro{textsubscript}\Parameter{text} +\end{Declaration} +\BeginIndex{Cmd}{textsubscript}% +In \autoref{sec:maincls.footnotes} the command +\Macro{textsuperscript}\IndexCmd{textsuperscript} was already +introduced which is a part of the \LaTeX{} kernel. Unfortunately +\LaTeX{} itself doesn't offer a command to produce a text in +subscript\Index{text, subscript}\Index{subscript} instead of +superscript\Index{text, superscript}\Index{superscript}. \KOMAScript{} +defines \Macro{textsubscript} for this. +% +\begin{Example} + You are writing a text on the human metabolism. From time to time + you have to mention some simple sum formulas in which the + numbers are in subscript. Being convinced from logical markup you + first define in the document preamble or in a separate package: + \begin{small} +\begin{verbatim} + \newcommand*{\Molek}[2]{#1\textsubscript{#2}} +\end{verbatim} + \end{small} + \newcommand*{\Molek}[2]{#1\textsubscript{#2}} + Using this you then write: + \begin{small} +\begin{verbatim} + The cell produces its energy from reaction of + \Molek C6\Molek H{12}\Molek O6 and \Molek O2 to + \Molek H2\Molek O{} and \Molek C{}\Molek O2. + However, Arsenic (\Molek{As}{}) has a detrimental + effect on the metabolism. +\end{verbatim} + \end{small} + The output looks as follows: + \begin{ShowOutput} + The cell produces its energy from reaction of \Molek C6\Molek + H{12}\Molek O6 and \Molek O2 to \Molek H2\Molek O{} and \Molek + C{}\Molek O2. However, Arsenic (\Molek{As}{}) has a detrimental + effect on the metabolism. + \end{ShowOutput} + Some time later you decide that the sum formulas should be + typeset in sans serif. Now you can see the advantages of a + consequent logical markup. You only have the redefine the + \Macro{Molek} command: + \begin{small} +\begin{verbatim} + \newcommand*{\Molek}[2]{\textsf{#1\textsubscript{#2}}} +\end{verbatim} + \end{small} + \renewcommand*{\Molek}[2]{\textsf{#1\textsubscript{#2}}} + Now the output in the whole document changes to: + \begin{ShowOutput} + The cell produces its energy from reaction of \Molek C6\Molek + H{12}\Molek O6 and \Molek O2 to \Molek H2\Molek O{} and \Molek + C{}\Molek O2. However, Arsenic (\Molek{As}{}) has a detrimental + effect on the metabolism. + \end{ShowOutput} +\end{Example} +\begin{Explain} + In the example above the writing ``\verb|\Molek C6|'' is used. This + makes use of the fact that arguments which consist of only one + character doesn't have to be enclosed in parenthesis. That's why + ``\verb|\Molek C6|'' is similar to ``\verb|\Molek{C}{6}|''. You + might already know this from indices or powers in mathematical + environments, such as ``\verb|$x^2$|'' instead of ``\verb|$x^{2}$|'' + for ``$x^2$''. +\end{Explain} +% +\EndIndex{Cmd}{textsubscript}% + + +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{Appendix} +\label{sec:maincls.appendix} + +The last part of a document usually contains the +appendix\Index{appendix}, the bibliography\Index{bibliography} and, if +necessary, the index\Index{index}. + +\begin{Declaration} + \Macro{appendix} +\end{Declaration}% +\BeginIndex{Cmd}{appendix}% +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 thus making sure +that the rules according to \cite{DUDEN} are being followed. These +rules are explained in more detail in the description of the class +options \Option{pointednumbers} and \Option{pointlessnumbers} in +\autoref{sec:maincls.formattingOptions}. + +Please note that \Macro{appendix} is a command, \emph{not} an +environment! This command does not need an argument. The sectioning +commands in the appendix are used in the same way as in the main part. + +% +\EndIndex{Cmd}{appendix} + + +\begin{Declaration} + \Macro{appendixmore} +\end{Declaration}% +\BeginIndex{Cmd}{appendixmore}% +There is a peculiarity within the \Macro{appendix} command in the +{\KOMAScript} classes. In case the command \Macro{appendixmore} is +defined, \Macro{appendix} is executed too. Internally the +{\KOMAScript} classes \Class{scrbook} and \Class{scrreprt} take +advantage of this behaviour for implementing the options +\Option{appendixprefix} and \Option{noappendixprefix} (see +\autoref{sec:maincls.layoutOptions}). You should take care of this +in case you are going to define or redefine the \Macro{appendixmore} +by yourself. In case one of these options is set, you will receive an +error message when using +\verb|\newcommand{\appendixmore}{|\dots\verb|}|. This is thought to +prevent you from changing options without noticing. + +\begin{Example} + You do not want the chapters in the main part of the classes + \Class{scrbook} or \Class{scrreprt} to be introduced by a prefix line + (see layout options \Option{chapterprefix} and \Option{nochapterprefix} + in \autoref{sec:maincls.layoutOptions}). For being consistent you + do not want such a line in the appendix either. Instead you would like + to see the word "`Chapter"' in the language of your choice written in + front of the chapter letter and, simultaneously, in the page headings. + Instead of using the layout options \Option{appendixprefix} or + \Option{noappendixprefix}, you would define in the document preamble: +% + \begin{small} +\begin{verbatim} + \newcommand*{\appendixmore}{% + \renewcommand*{\chapterformat}{% + \appendixname~\thechapter\autodot\enskip} + \renewcommand*{\chaptermarkformat}{% + \appendixname~\thechapter\autodot\enskip} + } +\end{verbatim} + \end{small} +% + In case you are going to change your mind and want to use the option + \Option{appendixprefix} at a later state, you will get an error + message because of the already defined \Macro{appendixmore} command. + This prevents the definition mentioned above from changing the + settings already set using \Option{chapterprefix} and + \Option{nochapterprefix}. + + It is also possible to get a similar behaviour of the appendix for + the class \Class{scrartcl}. You would write in the preamble of your + document: + \begin{small} +\begin{verbatim} + \newcommand*{\appendixmore}{% + \renewcommand*{\othersectionlevelsformat}[1]{% + \ifthenelse{\equal{##1}{section}}{\appendixname~}{}% + \csname the##1\endcsname\autodot\enskip} + \renewcommand*{\sectionmarkformat}{% + \appendixname~\thesection\autodot\enskip} + } +\end{verbatim} + \end{small} + In addition the package \Package{ifthen}\IndexPackage{ifthen} (see + \cite{package:ifthen}) is required. + + Redefined commands are explained in more detail in + \autoref{sec:maincls.structure}. +\end{Example} +% +\EndIndex{Cmd}{appendixmore}% + + +\begin{Declaration} + \Macro{setbibpreamble}\Parameter{Pr\"{a}ambel} +\end{Declaration}% +\BeginIndex{Cmd}{setbibpreamble}% +The command \Macro{setbibpreamble} can be used for setting a preamble +for the bibliography\Index{bibliography}. This can be achieved by +placing the preamble before the command for issuing the bibliography. +However, it doesn't have to be directly in front of it. For example it +could be placed at the beginning of the document. Similar to the class +options \Option{bibtotoc} and \Option{bibtotocnumbered} this command +can only be successful if you haven't loaded a package which prevents +this by redefining the \Environment{thebibliography} environment. +Though the \Package{natbib} package \IndexPackage{natbib} unauthorized +uses internal macros of {\KOMAScript} it could be made sure that +\Macro{setbibpreamble} works 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 occuring in the text but in + alphabetical order. You use the following command: + \begin{small} +\begin{verbatim} + \setbibpreamble{References are in alphabetical order. + References with more than one author are sorted + according to the first author.} +\end{verbatim} + \end{small} + The \Macro{bigskip}\IndexCmd{bigskip} command makes sure that the + preamble and the first reference are separated by a big skip. + + Another usage of the preamble in the bibliography would be setting + the references ragged right. Just put the preamble as follows: + \begin{small} +\begin{verbatim} + \setbibpreamble{\raggedright} +\end{verbatim} + \end{small} + You can have a look at the result in the bibliography of this guide. +\end{Example} +% +\EndIndex{Cmd}{setbibpreamble} + + +\begin{Declaration} + \Macro{setindexpreamble} +\end{Declaration}% +\BeginIndex{Cmd}{setindexpreamble}% +Similar to the bibliography you can use a preamble in 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 numbers in +different ways. + +\begin{Example} + You have a document in which terms are both defined an used. The + page numbers of definitions are in bold. Of course you want to make + your reader aware of this fact. Thus you insert a preamble in the + index: + \begin{small} +\begin{verbatim} + \setindexpreamble{In \textbf{bold} printed page numbers + are references to the definition of terms.\par\bigskip} +\end{verbatim} + \end{small} +\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 +\Macro{indexpagestyle}(see \autoref{sec:maincls.pageStyle}). +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. +% +\EndIndex{Cmd}{setindexpreamble}% + + +\section{Obsolete Commands} +\label{sec:maincls.obsolete} + +\begin{Explain} + In this section you will find commands, which should not be used any + more. They are part of older \KOMAScript{} versions. For compatibility + reasons they can still be used in the new \KOMAScript{} release. There + are new mechanisms and user interfaces however, which you should use + instead. The reason for listing the obsolete macros in this + documentation is to aid users with understanding old documents. + Furthermore, package authors are free to use these macros in the future. + + \begin{Declaration} + \Macro{capfont} \\ + \Macro{caplabelfont} + \end{Declaration} + \BeginIndex{Cmd}{capfont}% + \BeginIndex{Cmd}{caplabelfont}% + The macro \Macro{capfont} sets the font which is used for captions + in tables and figures. The macro \Macro{caplabelfont} sets the font + which is used for the label and numbering of tables and pictures. + Please use element \FontElement{caption} and + \FontElement{captionlabel} of the current \KOMAScript{} instead + which are described in \autoref{sec:maincls.font}. +% + \EndIndex{Cmd}{capfont}% + \EndIndex{Cmd}{caplabelfont}% + + \begin{Declaration} + \Macro{descfont} + \end{Declaration} + \BeginIndex{Cmd}{descfont}% + This macro sets the font for the optional item arguments of an + \Environment{description} environment. Please use element + \FontElement{descriptionlabel} instead, which are described in + section ~\ref{sec:maincls.font}. +% + \EndIndex{Cmd}{descfont}% + + \begin{Declaration} + \Macro{sectfont} + \end{Declaration} + \BeginIndex{Cmd}{sectfont}% + This macro sets the font which is used for all section headings, the + main title an the highest level below \Macro{part} in the table of + contents. Use element \FontElement{sectioning} instead, which is + described in more detail in \autoref{sec:maincls.font}. +% + \EndIndex{Cmd}{sectfont}% + +\end{Explain} + +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{Authors} +\label{sec:maincls.authors} + +The authors listed below are responsible for this chapter or have +contributed to this chapter in different ways. +% In folgender Aufzaehlung den Namen des Autors, der fuer das Kapitel +% verantwortlich ist bitte mit \textbf{} hervorheben. +\begin{itemize} +\item Frank Neukam +\item \textbf{Markus Kohm} \TextEMail{Markus.Kohm@gmx.de} +\item Axel Sommerfeldt +\item \textit{Jo\~{a}o Canas Ferreira} +\item \textit{Georg Grandke} +\end{itemize} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "main" +%%% End: |