diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english')
12 files changed, 12558 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/Makefile b/Master/texmf-dist/source/latex/koma-script/doc/english/Makefile new file mode 100644 index 00000000000..651ac8e7daa --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/Makefile @@ -0,0 +1,50 @@ +# ====================================================================== +# Makefile +# Copyright (c) Markus Kohm, 2002-2006 +# +# This file is part of the LaTeX2e KOMA-Script bundle. +# +# This work may be distributed and/or modified under the conditions of +# the LaTeX Project Public License, version 1.3b of the license. +# The latest version of this license is in +# http://www.latex-project.org/lppl.txt +# and version 1.3b or later is part of all distributions of LaTeX +# version 2005/12/01 or later and of this work. +# +# This work has the LPPL maintenance status "author-maintained". +# +# The Current Maintainer and author of this work is Markus Kohm. +# +# This work consists of all files listed in manifest.txt. +# ---------------------------------------------------------------------- +# Makefile +# Copyright (c) Markus Kohm, 2002-2006 +# +# Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +# Version 1.3b, verteilt und/oder veraendert werden. +# Die neuste Version dieser Lizenz ist +# http://www.latex-project.org/lppl.txt +# und Version 1.3b ist Teil aller Verteilungen von LaTeX +# Version 2005/12/01 oder spaeter und dieses Werks. +# +# Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +# (allein durch den Autor verwaltet). +# +# Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +# +# Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +# ====================================================================== + +# ---------------------------------------------------------------------- +# Directory with basics +BASEDIR ?= $(PWD)/../../ +DOCDIR = $(BASEDIR)doc/ +# language +LANGUAGE = english +LANGUAGESHORTCUT = en +LANGUAGELONG = english + +include $(DOCDIR)Makefile.guide + +# +# end of file `Makefile' diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/adrconvnote.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/adrconvnote.tex new file mode 100644 index 00000000000..66dea8ddbf7 --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/adrconvnote.tex @@ -0,0 +1,96 @@ +% ====================================================================== +% adrconvnote.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3b of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3b or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% adrconvnote.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3b, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3b ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about adrconv of the KOMA-Script guide +% Maintained by Jens-Uwe Morawski (with help from Markus Kohm) +% +% ---------------------------------------------------------------------- +% +% Kapitel über adrconv in der KOMA-Script-Anleitung +% Verwaltet von Jens-Uwe Morawski (mit Unterstützung von Markus Kohm) +% +% ====================================================================== + +\ProvidesFile{adrconvnote.tex}[{2005/11/27 KOMA-Script guide (chapter: + adrconv)}] +% Date of translated german file: 2005/08/10 + +\chapter{Creating Address Files from a Address Database}% +\labelbase{addrconv}% +\index{address file}% +\index{address database}% +\IndexPackage{addrconv} + +In former versions of \KOMAScript{} the package \Package{addrconv} was a +permanent part of the \KOMAScript{} sytem. The chief involvment with +\KOMAScript{} was that with the help of \Package{addrconv} it was possible to +create address files from a address database in \BibTeX{} format. Next the +address file could be used for the \KOMAScript{} letter class or with the +package \Package{scraddr}. + +\begin{lstlisting} + @address{HMUS, + name = {Carl McExample}, + title = {Dr.}, + city = {Anywhere}, + zip = 01234, + country = {Great Britain}, + street = {A long Road}, + phone = {01234 / 5 67 89}, + note = {always forget his birthday}, + key = {HMUS}, + } +\end{lstlisting} + +From entries, as can be seen above, address files can be generated. For this +\Package{addrconv} employs \BibTeX{} and some \BibTeX{} styles. Additionally +there are some \LaTeX{} files which help to create various telephon and +address lists for printing. + +The package \Package{addrconv} was indeed a separate package, since besides +what is required for \KOMAScript{} it includes some interessting features +more. Therefore the package \Package{addrconv}, as announced in the previous +\KOMAScript{} release, is removed from the \KOMAScript{} system. + +The package \Package{adrconv}, only one \emph{d}, replaces \Package{addrconv} +entirely. If it is not included in your \TeX{} distribution then it can be +downloaded from \cite{package:adrconv} and you can install it separately. + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "../guide" +%%% End: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/guide-english.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/guide-english.tex new file mode 100644 index 00000000000..bfec76cae44 --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/guide-english.tex @@ -0,0 +1,424 @@ +% ====================================================================== +% guide-english.tex +% Copyright (c) Markus Kohm, 2002-2006 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3b of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3b or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% guide-english.tex +% Copyright (c) Markus Kohm, 2002-2006 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3b, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3b ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Language dependencies (english) of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Sprachabhängigkeiten (english) der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ====================================================================== +% +\ProvidesFile{guide-english.tex}[{2006/05/10 + KOMA-Script guide language dependencies}] +% +% \section{Title} +% +% \begin{macro}{\GuideSubject} +% \begin{macro}{\GuideTitle} +% \begin{macro}{\GuideSubTitle} +% \begin{macro}{\GuideAuthorHeadline} +% \begin{macro}{\GuideWarrantyHeadline} +% \begin{macro}{\GuideWarranty} +% \begin{macro}{\GuideCopyright} +% \begin{macro}{\GuideDedication} +% Language dependencies of all the title pages. +% \begin{macrocode} +\newcommand*{\GuideSubject}{The Guide}% +\newcommand*{\GuideTitle}{\KOMAScript}% +\newcommand*{\GuideSubTitle}{a versatile \LaTeXe{} bundle}% +\newcommand*{\GuideAuthorHeadline}{Authors of the \KOMAScript{} Bundle}% +\newcommand*{\GuideWarrantyHeadline}{Legal Notes:}% +\newcommand*{\GuideWarranty}{There is no warranty for any part of the + documented Software. The authors have taken care in the preparation of this + book, but make no expressed or implied warranty of any kind and assume no + responsibility for errors or omissions. No liability is assumed for + incidental or consequential damages in connection with or arising out of the + use of the inromation or programs contained here.\par\medskip% + Many of the designations used by manufacturers and sellers to distinguish + their products are claimed as trademarks. Where those designations appear in + this book, and the authors were aware ot a trademark claim, the designations + have been printed with initial capital letters or in all capitals.}% +\newcommand*{\GuideCopyright}{Free screen version without any optimization of + paragraph and page breaks\par\medskip% + This guide is part of \KOMAScript{}, which is free under the terms and + conditions of LaTeX Project Public License Version 1.3b. A version of this + license, which is valid to \KOMAScript{}, is part of \KOMAScript{} (see + \File{lppl.txt}). Distribution of this manual\,---\,even if it is + printed\,---\,is allowed provided that all parts of \KOMAScript{} are + distributed. Distribution without the other parts of \KOMAScript{} needs a + explicit, additional authorization by the authors.}% +\newcommand*{\GuideDedication}{To All Friends of Typography!}% +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% \section{CTAN Server to be Used} +% +% \begin{macro}{\GuideCTANserver} +% \begin{macrocode} +\newcommand*{\GuideCTANserver}{ftp.ctan.org} +% \end{macrocode} +% \end{macro} +% +% +% \section{Terms} +% +% Some terms, e.g. used at index notes. +% +% \begin{macro}{\GuideClass} +% The term »class«. +% \begin{macrocode} +\newcommand*{\GuideClass}{class} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\GuideCounter} +% The term »counter«. +% \begin{macrocode} +\newcommand*{\GuideCounter}{counter} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\GuideEnvironment} +% The term »environment«. +% \begin{macrocode} +\newcommand*{\GuideEnvironment}{environment} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\GuideExample} +% The term »Example« used at a kind of heading, so it should be upper case. +% \begin{macrocode} +\newcommand*{\GuideExample}{Example} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\GuideFile} +% The term »file«. +% \begin{macrocode} +\newcommand*{\GuideFile}{file} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\GuideFloatstyle} +% The term »\Package{float} style«. +% \begin{macrocode} +\newcommand*{\GuideFloatstyle}{\Package{float} style} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\GuideFontElement} +% The term »element«. +% \begin{macrocode} +\newcommand*{\GuideFontElement}{element} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\GuideLength} +% The term »length«. +% \begin{macrocode} +\newcommand*{\GuideLength}{length} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\GuideMacro} +% \begin{macro}{\GuideCommand} +% The term »command«. +% \begin{macrocode} +\newcommand*{\GuideMacro}{command} +\let\GuideCommand\GuideMacro +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuideOption} +% The term »option«. +% \begin{macrocode} +\newcommand*{\GuideOption}{option} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\GuidePackage} +% The term »package«. +% \begin{macrocode} +\newcommand*{\GuidePackage}{package} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\GuidePagestyle} +% The term »page style«. +% \begin{macrocode} +\newcommand*{\GuidePagestyle}{page style} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\GuidePLength} +% \begin{macro}{\GuidePseudoPrefix} +% The prefix »pseudo« at the term »pseudo length« and the term itself. +% \begin{macrocode} +\newcommand*{\GuidePseudoPrefix}{pseudo } +\newcommand*{\GuidePLength}{\GuidePseudoPrefix\GuideLength} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuideVariable} +% The termo »variable«. +% \begin{macrocode} +\newcommand*{\GuideVariable}{variable} +% \end{macrocode} +% \end{macro} +% +% +% \section{Index} +% +% \begin{macro}{\GuidegenIndex} +% \begin{macro}{\GuidecmdIndex} +% \begin{macro}{\GuidecmdIndexShort} +% \begin{macro}{\GuidelenIndex} +% \begin{macro}{\GuidelenIndexShort} +% \begin{macro}{\GuideelmIndex} +% \begin{macro}{\GuideelmIndexShort} +% \begin{macro}{\GuidefilIndex} +% \begin{macro}{\GuidefilIndexShort} +% \begin{macro}{\GuideoptIndex} +% \begin{macro}{\GuideoptIndexShort} +% The titles and short titles of each single index. +\newcommand*{\GuidegenIndex}{General Index}% +\newcommand*{\GuidecmdIndex}{Index of Commands, Environments, and Variables}% +\newcommand*{\GuidecmdIndexShort}{Index of Commands etc.}% +\newcommand*{\GuidelenIndex}{Index of Lengths and Counters}% +\newcommand*{\GuidelenIndexShort}{Index der Lengths etc.}% +\newcommand*{\GuideelmIndex}{Index of Elements with Capability of + Font Adjustment}% +\newcommand*{\GuideelmIndexShort}{Index of Elements}% +\newcommand*{\GuidefilIndex}{Index of Files, Classes, and Packages}% +\newcommand*{\GuidefilIndexShort}{Index of Files etc.}% +\newcommand*{\GuideoptIndex}{Index of Class and Package Options}% +\newcommand*{\GuideoptIndexShort}{Index of Options}% +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GuideIndexPreamble} +% The preamble text of the whole index. +\newcommand*{\GuideIndexPreamble}{% + There are two kinds of page numbers at this index. The bold printed numbers + show the pages of declaration or explanation of the topic. The normal + printed numbers show the pages of using a topic.% +} +% \end{macro} +% +% +% \section{Bibliography} +% +% \begin{macro}{\GuideBibPreamble} +% \begin{macrocode} +\newcommand*{\GuideBibPreamble}{% + In the following you can find many references. All of them are referenced + from the main text. In many cases the reference points to documents or + directories which can be accessed via Internet. In these cases the + reference includes a URL instead of a publisher. If the reference points to + a \LaTeX{} package then the URL is written in the form + ``\url{CTAN://}\emph{destination}''. The prefix ``\url{CTAN://}'' means the + \TeX{} archive on a CTAN server or mirror. For example, you can substitude + the prefix with \url{ftp://\GuideCTANserver/tex-archive/}. For \LaTeX{} + packages it is also important to mention that we have tried to give a + version number appropriate to the text that cites the reference. But for + some packages is is very difficult to find a consistent version number and + release date. Additionally the given version is not always the current + version. If you want install new packages take care that the package is the + most up-to-date version and check first whether the package is already + available on your system or not.% +} +% \end{macrocode} +% \end{macro} +% +% +% \section{Change Log} +% +% \begin{macro}{\GuideChangeLogPreamble} +% The preamble of the change log index. +% \begin{macrocode} +\newcommand*{\GuideChangeLogPreamble}{% + At this list of changes you will find all significant changes of the user + interface of the \KOMAScript{} bundle at the last few versions. The list was + sorted about the names of the classes and packages and their version. The + numbers behind the versions are the pages, where the changes are + described. At the margins of these pages you will find corresponding version + marks.% +} +% \end{macrocode} +% \end{macro} +% +% +% \section{Jens-Uwe's Example Text} +% +% TODO: These should be merged with other example text. +% \begin{macro}{\XmpText} +% Example text command; the default definition (50) returns the whole text. +% \begin{macrocode} +\newcommand*{\XmpText}[1][50]{% + \ifnum #1<51 + This f\/ill text is currently seized by 130 million receptors + in your retina. + \ifnum #1>1 + Thereby the nerve cells are put in a state of stimulation, + which spreads + \ifnum #1>2 + into the rear part of your brain originating from + \ifnum #1>3 + the optic nerve. + From there the stimulation is transmitted in a split second + also in other parts of your cerebrum. + Your frontal lobe becomes stimulated. + Intention-impulses spread from there, which your + central nervous + \fi\fi\fi + \fi + \ifnum #1>49 + system transforms in actual deeds. + Head and eyes already react. + They follow the text, taking the informations present there + and transmit them via the optic nerve. + \fi +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\XmpTopText} +% \begin{macro}{\XmpBotText} +% These two commands are language-dependent, since in some languages +% additional commands may required. +% \begin{macrocode} +\newcommand*{\XmpTopText}{\XmpText[3]} +\newcommand*{\XmpBotText}{\XmpText[2]} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\XmpMarginTextA} +% \begin{macro}{\XmpMarginTextB} +% Margin notes. +% \begin{macrocode} +\newcommand*{\XmpMarginTextA}{Retina} +\newcommand*{\XmpMarginTextB}{} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% \section{Language Extensions} +% +% Some terms should be part of the captions of the language. +% \begin{macro}{\GuideLanguageExtensions} +% This macro has to be defined, because the class will add it to the language +% at |\begin{document}| and it will also call it. +% \begin{macrocode} +\newcommand*{\GuideLanguageExtensions}{% +% \end{macrocode} +% \begin{macro}{\pageautorefname} +% The term »page« that will be put before the reference of a page set by +% |\autopageref|. +% \begin{macrocode} + \def\pageautorefname{page}% +% \end{macrocode} +% \end{macro} +% \begin{macro}{\subsectionautorefname} +% \begin{macro}{\subsubsectionautorefname} +% \begin{macro}{\paragraphautorefname} +% \begin{macro}{\subparagraphautorefname} +% I'll call them all »section«. +% \begin{macrocode} + \def\figureautorefname{figure}% + \def\tableautorefname{table}% + \def\appendixautorefname{appendix}% + \let\subsectionautorefname=\sectionautorefname + \let\subsubsectionautorefname=\sectionautorefname + \let\paragraphautorefname=\sectionrefname + \let\subparagraphautorefname=\sectionrefname +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \begin{macro}{\changelogname} +% The name of the change log index. +% \begin{macrocode} + \def\changelogname{Change Log} +% \end{macrocode} +% \end{macro} +% \begin{macrocode} +} +% \end{macrocode} +% \end{macro} +% +% +% \section{Hyphenation} +% +% This is not realy a good place to put them~-- but better late than never: +% \begin{macrocode} +\hyphenation{% +} +% \end{macrocode} +% +% +% +\endinput +%%% Local Variables: +%%% mode: doctex +%%% TeX-master: "guide" +%%% End: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/htmlsetup b/Master/texmf-dist/source/latex/koma-script/doc/english/htmlsetup new file mode 100644 index 00000000000..c0c6857792b --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/htmlsetup @@ -0,0 +1,63 @@ +# ====================================================================== +# htmlsetup +# Copyright (c) Markus Kohm, 2002-2006 +# +# This file is part of the LaTeX2e KOMA-Script bundle. +# +# This work may be distributed and/or modified under the conditions of +# the LaTeX Project Public License, version 1.3b of the license. +# The latest version of this license is in +# http://www.latex-project.org/lppl.txt +# and version 1.3b or later is part of all distributions of LaTeX +# version 2005/12/01 or later and of this work. +# +# This work has the LPPL maintenance status "author-maintained". +# +# The Current Maintainer and author of this work is Markus Kohm. +# +# This work consists of all files listed in manifest.txt. +# ---------------------------------------------------------------------- +# htmlsetup +# Copyright (c) Markus Kohm, 2002-2006 +# +# Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +# Version 1.3b, verteilt und/oder veraendert werden. +# Die neuste Version dieser Lizenz ist +# http://www.latex-project.org/lppl.txt +# und Version 1.3b ist Teil aller Verteilungen von LaTeX +# Version 2005/12/01 oder spaeter und dieses Werks. +# +# Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +# (allein durch den Autor verwaltet). +# +# Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +# +# Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +# ====================================================================== + +$baselink="scrguien.pdf"; +$htmlhead="<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.0//EN\"> +<html> +<head><title>Index</title> +<meta http-equiv=\"content-type\" content=\"text/html; charset=utf-8\"> +</head> +<body> +<h1>Index of the KOMA-Script Guide</h1> +<p>This is an index of the elements defined at KOMA-Script. This index is related to the <a href=\"scrguien.pdf\">KOMA-Script guide</a>. To improve the survey this index has serveral functional sections:</p> +"; +$htmlend="<p> +<a href=\"http://validator.w3.org/check?uri=referer\"><img +src=\"http://www.w3.org/Icons/valid-html40\" +alt=\"Valid HTML 4.0 Strict\" height=\"31\" width=\"88\"></a> +</p> +</body></html>"; +%titles=( "option" => "Options", + "macro" => "Commands", + "environment" => "Environments", + "plength" => "Pseudolengths", + "variable" => "Variables", + "pagestyle" => "Page Styles", + "counter" => "Counter", + "floatstyle" => "Styles for the float Package" ); + +# end of file diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/introduction.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/introduction.tex new file mode 100644 index 00000000000..4bd76279e91 --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/introduction.tex @@ -0,0 +1,228 @@ +% ====================================================================== +% introduction.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3b of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3b or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% introduction.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3b, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3b ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Introduction of the KOMA-Script guide +% Maintained by Markus Kohm +% Translation: Kevin Pfeiffer, Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Einleitung der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% Übersetzung: Kevin Pfeiffer, Markus Kohm +% +% ====================================================================== + +\ProvidesFile{introduction.tex}[2006/07/04 KOMA-Script guide introduction] +% Date of translated german file: 2006-07-01 + +\chapter{Introduction} +\labelbase{introduction} + +\section{Preface}\label{sec:introduction.preface} + +The {\KOMAScript} bundle is actually several packages and classes. It +provides counterparts or replacements for the standard \LaTeX{} classes such +as \emph{article}, \emph{book}, etc. (see \autoref{cha:maincls}), but offers +many additional features and its own unique look and feel. + +The \KOMAScript{} user guide is intended to serve the advanced as well as the +inexperienced \LaTeX{} user and is accordingly quite large. The result is a +compromise and we hope that you will keep this in mind when using it. +Your suggestions for improvement are, of course, always welcome. + + +\section{Structure of the Guide}\label{sec:introduction.structure} + +The \KOMAScript{} user guide is not intended to be a \LaTeX{} primer. +Those new to \LaTeX{} should look at \emph{The Not So Short Introduction +to \LaTeXe{}} \cite{lshort} or \emph{\LaTeXe{} for Authors} +\cite{latex:usrguide} or a \LaTeX{} reference book. You will also find +useful information in the many \LaTeX{} FAQs, including the \emph{TeX +Frequently Asked Questions on the Web} \cite{UK:FAQ}. + +\begin{Explain} + In this guide you will find supplemental information about \LaTeX{} and + \KOMAScript{} in (san serif) paragraphs like this one. + The information given in these explanatory sections is not essential for + using \KOMAScript{}, but if you experience problems you should + take a look at it -- particularly before sending a bug report. +\end{Explain} + +If you are only interested in using a single \KOMAScript{} class or +package you can probably successfully avoid reading the entire guide. +Each class and package typically has its own chapter; however, the three +main classes (\Class{scrbook}, \Class{scrrprt}, and \Class{scrartcl}) +are introduced together in chapter three. Where an example or note only +applies to one or two of the three classes, it is called out in the +margin. \OnlyAt{\Class{Like this.}} + +\begin{Explain} + The primary documentation for \KOMAScript is in German and has been + translated for your convenience; like most of the \LaTeX{} world, its + commands, environments, options, etc., are in English. In a few cases, the + name of a command may sound a little strange, but even so, we hope and + believe that with the help of this guide \KOMAScript{} will still be usable + and useful to you. +\end{Explain} + + +\section{History of \KOMAScript}\label{sec:introduction.history} + +In the early 1990s, Frank Neukam needed a method to publish an +instructor's lecture notes. At that time \LaTeX was \LaTeX2.09 and there +was no distinction between classes and packages -- there were only +\emph{styles}. Frank felt that the standard document styles were not +good enough for his work; he wanted additional commands and +environments. At the same time he was interested in typography and, +after reading Tschichold's \emph{Ausgewählte Aufsätze über Fragen der +Gestalt des Buches und der Typographie} (Selected Articles on the +Problems of Book Design and Typography) \cite{JTsch87}, he decided to +write his own document style -- and not just a one-time solution to his +lecture notes, but an entire style family, one specifically designed for +European and German typography. Thus \Script{} was born. + +Markus Kohm, the developer of \KOMAScript{}, came across {\Script} in +December 1992 and added an option to use the A5 paper format. This and +other changes were then incorporated in to\ScriptII{}, released by Frank +in December 1993. + +Beginning in mid-1994, \LaTeXe{} became available and brought with it +many changes. Users of \ScriptII{} were faced with either limiting their +usage to \LaTeXe{}'s compatibility mode or giving up \Script{} +altogether. This situation lead Markus to put together a new \LaTeXe{} +package, released on 7~July 1994 as \KOMAScript{}; a few months later +Frank declared \KOMAScript{} to be the official successor to \Script{}. +\KOMAScript{} originally provided no \emph{letter} class, but this +deficiency was soon remedied by Axel Kielhorn, and the result became part +of \KOMAScript{} in December 1994. Axel also wrote the first true +German-language user guide, which was followed by an English-language +guide by Werner Lemberg. + +Since then much time has passed. \LaTeX{} has changed in only minor ways, but +the \LaTeX{} lanscape has changed a great deal; many new packages and classes +are now available and \KOMAScript{} itself has grown far beyond what it was in +1994. The initial goal was to provide good \LaTeX classes for German-language +authors, but today its primary purpose is to provide more-flexible +alternatives to the standard classes. \KOMAScript{}'s success has lead to +e-mail from users all over the world and this has lead to many new macros -- all +needing documentation; hence this ``small guide.'' + + +\section{Special Thanks}\label{sec:introduction.thanks} + +Acknowledgements in the introduction? No, the proper acknowledgements can be +found in the addendum. My comments here are not intended for the authors of +this guide -- and those thanks should rightly come from you, the reader, +anyhow. I, the author of \KOMAScript, would like to extend my personal thanks +to Frank Neukam. Without his \Script{} family, \KOMAScript{} would not have +come about. I am indebted to the many persons who have contributed to +{\KOMAScript}, but with their indulgence, I would like to specifically mention +Jens-Uwe Morawski and Torsten Kr\"uger. The English translation of the guide +is, among many other things, due to Jens's untiring commitment. Torsten was +the best beta-tester I ever had. His work has particularly enhanced the +usability of \Class{scrlttr2} und \Class{scrpage2}. Many thanks to all who +encouraged me to go on, to make things better and less error-prone, or to +implement additional features. + +Thanks go as well to DANTE, Deutschsprachige +Anwendervereinigung \TeX~e.V\kern-.18em, (the German-Language TeX User Group). +Without the DANTE server, \KOMAScript{} could not have been released and +distributed. Thanks as well to everybody in the \TeX{} newsgroups and mailing +lists who answer questions and have helped me to provide support for +\KOMAScript{}. + +\section{Legal Notes}\label{sec:introduction.legal} + +{\KOMAScript} was released under the {\LaTeX} Project Public License. You +will find it in the file \File{lppl.txt}. An unofficial German-language +translation is also available in \File{lppl-de.txt} and is valid for all +German-speaking countries. + +\iffree{This document and the \KOMAScript{} bundle are provided ``as is'' and +without warranty of any kind.}% +{Please note: the printed version of this guide is not free under the +conditions of the LaTeX{} Project Public Licence. If you need a free version +of this guide, use the version that is provided as part of the \KOMAScript{} +bundle.} + +\section{Installation}\label{sec:introduction.installation} +Installation information can be found in the file \File{INSTALL.txt}. You +should also read the documentation that comes with the \TeX{} distribution you +are using. + +\section{Bugreports and Other Requests} +\label{sec:introduction.errors} + +If you think you have found an error in the documentation or a bug in one of +the \KOMAScript{} classes, one of the \KOMAScript{} packages, or another +part of \KOMAScript{}, please do the following: first have a look at +CTAN to see if a newer version of \KOMAScript{} is available; in this case +install the applicable section and try again. + +If you are using the most recent version of \KOMAScript and still have a +bug, please provide a short \LaTeX{} document that demonstrates the problem. You +should only use the packages and definitions needed to demonstrate the +problem; do not use any unusual packages. + +By preparing such an example it often becomes clear whether the problem is +truly a \KOMAScript{} bug or something else. Please report \KOMAScript{} (only) +bugs to the author of \KOMAScript{}. Please use \File{komabug.tex}, an +interactive \LaTeX{} document, to generate your bug report and send it to the +address you may find at \File{komabug.tex}. + +If you want to ask your question in a newsgroup or mailing list, you +should also include such an example as part of your question, but in this +case, using \File{komabug.tex} is not necessary. To find out the version +numbers of all packages in use, simply put \Macro{listfiles} in the preamble of +your example and read the end of the \File{log}-file. + + +\section{Additional Informations} +\label{sec:introduction.moreinfos} + +Once you become an experienced \KOMAScript{} user you may want to look at some +more advanced examples and information. These you will find on the +\KOMAScript{} documentation web site \cite{homepage}. The main +language of the site is German, but nevertheless English is +welcome. + +\endinput +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "../guide.tex" +%%% End: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scraddr.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scraddr.tex new file mode 100644 index 00000000000..50d661953d5 --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scraddr.tex @@ -0,0 +1,235 @@ +% ====================================================================== +% scraddr.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3b of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3b or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scraddr.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3b, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3b ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scraddr of the KOMA-Script guide +% Maintained by Jens-Uwe Morawski (with help from Markus Kohm) +% +% ---------------------------------------------------------------------- +% +% Kapitel über scraddr in der KOMA-Script-Anleitung +% Verwaltet von Jens-Uwe Morawski (mit Unterstützung von Markus Kohm) +% +% ====================================================================== + +\ProvidesFile{scraddr.tex}[2005/11/27 KOMA-Script guide (chapter: scraddr)] +% Date of translated german file: 2002/10/15 + +\chapter{Access to Address Files with \Package{scraddr}}% +\labelbase{scraddr}% +\BeginIndex{Package}{scraddr} + +\section{Overview}\label{sec:scraddr.overview} +The package \Package{scraddr} is a small extension to +the \KOMAScript{} letter class. +Its aim is to make access to the data of address files +more flexible and easier. +Basically the package implements a new loading mechanism +for address files, which contain address entries of the kind +described in the previous chapter. + +\begin{Declaration} +\Macro{InputAddressFile}\Parameter{file name} +\end{Declaration}% +\BeginIndex{Cmd}{InputAddressFile}% +% +The command \Macro{InputAddressFile} reads the content +of the address file, given as its parameter. +If the file does not exist the command returns an +error message. + +For every entry in the address file the command generates a +set of macros for accessing the data. +First a short reminder of how an address entry is structured. + +\begin{Declaration}% + \Macro{adrentry}\Parameter{Lastname}\Parameter{Firstname}% + \Parameter{Address}\Parameter{Telephone}\Parameter{F1}\Parameter{F2}% + \Parameter{Comment}\Parameter{Key}\\ + \Macro{addrentry}\Parameter{Lastname}\Parameter{Firstname}% + \Parameter{Address}\Parameter{Telephone}\Parameter{F1}\Parameter{F2}% + \Parameter{F3}\Parameter{F4}\Parameter{Key} +\end{Declaration}% +The last parameter is the identifier of an entry, thus the +\PName{Key} has to be unique and not blank. If the file contains more +than one entry with the same \PName{Key} value, the last occurrence +will be used. The \PName{Key} should only be composed of letters. +\begin{Declaration} +\Macro{Name}\Parameter{Key}\\ +\Macro{FirstName}\Parameter{Key}\\ +\Macro{LastName}\Parameter{Key}\\ +\Macro{Address}\Parameter{Key}\\ +\Macro{Telephone}\Parameter{Key}\\ +\Macro{FreeI}\Parameter{Key}\\ +\Macro{FreeII}\Parameter{Key}\\ +\Macro{Comment}\Parameter{Key}\\ +\Macro{FreeIII}\Parameter{Key}\\ +\Macro{FreeIV}\Parameter{Key} +\end{Declaration}% +\BeginIndex{Cmd}{Name}\BeginIndex{Cmd}{FirstName}\BeginIndex{Cmd}{LastName}% +\BeginIndex{Cmd}{Address}\BeginIndex{Cmd}{Telephone}\BeginIndex{Cmd}{FreeI}% +\BeginIndex{Cmd}{FreeII}\BeginIndex{Cmd}{FreeIII}\BeginIndex{Cmd}{FreeIV}% +\BeginIndex{Cmd}{Comment}% +% +These commands give access to data of your address file. +The parameter \PName{Key} is the same as in the +\Macro{adrentry} or \Macro{addrentry} command. +In the address of letters often both, first-name and +last-name, are required. +The command \Macro{Name}\PParameter{Key} is an abridgement for +\Macro{FirstName}\PParameter{Key} \Macro{LastName}\PParameter{Key}. + +\EndIndex{Cmd}{InputAddressFile}% +\EndIndex{Cmd}{Name}\EndIndex{Cmd}{FirstName}\EndIndex{Cmd}{LastName}% +\EndIndex{Cmd}{Address}\EndIndex{Cmd}{Telephone}\EndIndex{Cmd}{FreeI}% +\EndIndex{Cmd}{FreeII}\EndIndex{Cmd}{FreeIII}\EndIndex{Cmd}{FreeIV}% +\EndIndex{Cmd}{Comment}% + +\section{Usage}\label{sec:scraddr.usage} + +First of all, we need an address file with valid address entries. +In this example the file has the name \emph{lotr.adr} and contains +the following entries. +\begin{lstlisting} + \addrentry{Baggins}{Frodo}% + {The Hill\\ Bag End/Hobbiton in the Shire}{}% + {Bilbo Baggins}{pipe-weed}% + {the Ring-bearer}{Bilbo's heir}{FRODO} + \adrentry{Gamgee}{Samwise}% + {Bagshot Row 3\\Hobbiton in the Shire}{}% + {Rosie Cotton}{taters}% + {the Ring-bearer's faithful servant}{SAM} + \adrentry{Bombadil}{Tom}% + {The Old Forest}{}% + {Goldberry}{trill queer songs}% + {The Master of Wood, Water and Hill}{TOM} +\end{lstlisting} + +The 4\textsuperscript{th} parameter, the telephone number, has been left +blank. If you know the story behind these addresses you +will agree that a telephone number makes no sense here. +The command \Macro{InputAddressFile} is used to load +the address file shown above. +\begin{lstlisting} + \InputAddressFile{lotr} +\end{lstlisting} + + +With the help of the commands introduced in this chapter +we can now write a letter to the old \textsc{Tom Bombadil}. +In this letter we ask him, if he can remember two +fellow-travelers from Elder Days. +\begin{lstlisting} + \begin{letter}{\Name{TOM}\\\Address{TOM}} + \opening{Dear \FirstName{TOM} \LastName{TOM},} + + or \FreeIII{TOM}, how your delightful \FreeI{TOM} calls + you. + Can you remember Mr.\,\LastName{FRODO}, + strictly speaking \Name{FRODO}, since there was + Mr.\,\FreeI{FRODO} too. + He was \Comment{FRODO} in the Third Age + and \FreeIV{FRODO} + \Name{SAM}, \Comment{SAM}, has attended him. + + Their pasions were very wordly. + \FirstName{FRODO} enjoyed to smoke \FreeII{FRODO}, + his attendant has appreciate a good meal with + \FreeII{SAM}. + + Do you remember? Certainly Mithrandir has told you much + about their deeds and adventures . + \closing{``O spring-time and summer-time + and spring again after!\\ + O wind on the waterfall, + and the leaves' laughter!''} + \end{letter} +\end{lstlisting} +The 5\textsuperscript{th} and 6\textsuperscript{th} parameter of the +\Macro{adrentry} or \Macro{adrentry} command are for free use. They are +accessible with the commands \Macro{FreeI} and \Macro{FreeII}. In this +example the 5\textsuperscript{th} parameter contains the name of a person who +is the most important in the life of the entry's person, the +6\textsuperscript{th} contains the person's passion. The +7\textsuperscript{th} parameter is a comment or in general also a free +parameter. The commands \Macro{Comment} or \Macro{FreeIII} give access to the +data. Using \Macro{FreeIV} is only valid for \Macro{addrentry} entries; for +\Macro{adrentry} entries it results in a warning. +\EndIndex{Package}{scraddr} + +\section{Package Warning Options} + +As mentioned above the command \Macro{FreeIV} leads +to a fault if it is used for \Macro{adrentry} entries. + +Therefore \Package{scraddr} supports package options +in order to give the user the possibility to +choose how the package should react in such situation. +It is possible to choose different settings between +\emph{ignore} and \emph{rupture} of the \LaTeX{} run. + +\begin{Declaration} +\Option{adrFreeIVempty}\\ +\Option{adrFreeIVshow}\\ +\Option{adrFreeIVwarn}\\ +\Option{adrFreeIVstop} +\end{Declaration} +% +\BeginIndex{Option}{adrFreeIVempty}\BeginIndex{Option}{adrFreeIVshow} +\BeginIndex{Option}{adrFreeIVwarn}\BeginIndex{Option}{adrFreeIVstop} +% +One of these options can be given in the optional argument +of the \Macro{usepackage} command. The default setting is +\Option{adrFreeIVshow}. + +\begin{labeling}[\,--]{\Option{adrFreeIVempty}} +\item[\Option{adrFreeIVempty}] + the command \Macro{FreeIV} will be ignored +\item[\Option{adrFreeIVshow}] + ``(entry FreeIV undefined at \PName{Key})'' will be + written as warning in the text +\item[\Option{adrFreeIVwarn}] + writes a warning in the log-file +\item[\Option{adrFreeIVstop}] + the \LaTeX{} run will be interrupted with an error message +\end{labeling} +\EndIndex{Option}{adrFreeIVempty}\EndIndex{Option}{adrFreeIVshow} +\EndIndex{Option}{adrFreeIVwarn}\EndIndex{Option}{adrFreeIVstop} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "../guide" +%%% End: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle.tex new file mode 100644 index 00000000000..7dd0e09f809 --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrbookreportarticle.tex @@ -0,0 +1,4788 @@ +% ====================================================================== +% scrbookreportarticle.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3b of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3b or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrbookreportarticle.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3b, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3b ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrbook, scrreprt, and scrartcl of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel über scrbook, scrreprt und scrartcl in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\ProvidesFile{scrbookreportarticle.tex}[2006/07/01 KOMA-Script guide (chapter: +scrbook, scrreprt, scrartcl)] +% Date of translated german file: 2005-11-26 + +% TODO: See further TODO comments + +\chapter{The Main Classes \Class{scrbook}, \Class{scrrprt} and + \Class{scrartcl}} +\labelbase{maincls} + +\AddSeeIndex{command}{gen}{\GuidecmdIndexShort}{cmd} +\AddSeeIndex{macro}{gen}{\GuidecmdIndexShort}{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} + +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 + \caption[Class correspondence]{Correspondence between + standard classes, \KOMAScript{} classes and + \Script{} styles.} + \begin{tabular}{ll} + \toprule + standard class & \KOMAScript{} class \\%& \Script-Stil (\LaTeX2.09)\\ + \midrule + \Class{article} & \Class{scrartcl} \\%& \File{script\textunderscore s} \\ + \Class{report} & \Class{scrreprt} \\%& \File{script} \\ + \Class{book} & \Class{scrbook} \\%& \File{script} \\ + \Class{letter} & \Class{scrlettr} \\%& \File{script\textunderscore l} \\ + \bottomrule + \end{tabular} + \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 + \caption{Default options of the \KOMAScript{} classes} + \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} + \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 +\Macro{usepackage}\OParameter{package options}\PParameter{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}, +\autopageref{desc:typearea.option.letterpaper}). 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}, \autopageref{desc:typearea.option.BCOR} +till \autopageref{desc:typearea.option.headlines}). 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{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{Explain}% +\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}% + 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{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{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{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. The resulting font sizes for headings at \Class{scrbook} and +\Class{scrreprt} shows\autoref{tab:maincls.structureElementsFont}, +\autopageref{tab:maincls.structureElementsFont}. At \Class{scrartcl} smaller +font sizes are used. + +\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}, +\autopageref{desc:maincls.option.chapterprefix}. +% +\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{Explain}% +\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}% + 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}, \autopageref{desc:maincls.option.tocleft} +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. Some people asked me not +to fix this ``funny little mistake'' so I didn't. +% +\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}, +\autopageref{desc:maincls.macro.caption}, 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 that using any of these options does not changes the possition of the +caption from above the top of the table to the bottom of the table or vica +versa. It only changes the spacing between caption and e.g. tabular. + +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}. Additional support for \Package{float} may be found at +\autoref{sec:maincls.floats}, \autopageref{desc:maincls.floatstyle.komaabove}. +% +\EndIndex{Option}{tablecaptionbelow}% +\EndIndex{Option}{tablecaptionabove}% + + +\begin{Explain}% +\begin{Declaration} + \Option{origlongtable} +\end{Declaration}% +\BeginIndex{Option}{origlongtable}% +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}, +\autopageref{desc:maincls.macro.caption.longtable} 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:caption}) 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. + +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{lstlisting} + \setkomafont{captionlabel}{\usekomafont{descriptionlabel}} +\end{lstlisting} + You can find other examples in the paragraphs on each element. +\end{Example} + +\begin{desctable} + \caption{Elements, whose type style can be + changed with the {\KOMAScript} command \Macro{setkomafont} or + \Macro{addtokomafont}\label{tab:maincls.elementsWithoutText}}\\ + \Endfirsthead + \caption[]{Elements, whose type style can be + changed (\emph{pursuit})}\\ + \Endhead + \standardfoot% + \feentry{caption}{Text of a table or figure caption}% + \feentry{captionlabel}{Label of a table or figure caption; used according to + the element \FontElement{caption}}% + \feentry{chapter}{Title of the sectional unit \Macro{chapter}}% + \feentry{descriptionlabel}{Labels, i.e. the optional argument of + \Macro{item}, in the \Environment{description} environment}% + \feentry{dictumauthor}{Author of a smart saying; used according to the + element \FontElement{dictumtext}}% + \feentry{dictumtext}{Text of a smart saing (see command \Macro{dictum})}% + \feentry{footnote}{Footnote text and marker}% + \feentry{footnotelabel}{Mark of a footnote; used according to the element + \FontElement{footnote}}% + \feentry{footnotereference}{Footnote reference in the text}% + \feentry{pagefoot}{The foot of a page, but also the head of a page}% + \feentry{pagehead}{The head of a page, but also the foot of a page}% + \feentry{pagenumber}{Page number in the header or footer}% + \feentry{paragraph}{Title of the sectional unit \Macro{paragraph}}% + \feentry{part}{Title of the \Macro{part} sectional unit, without the line + with the part number}% + \feentry{partnumber}{Line with the part number in a title of the sectional + unit \Macro{part}}% + \feentry{section}{Title of the sectional unit \Macro{section}}% + \feentry{sectioning}{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}% + \feentry{subparagraph}{Title of the sectional unit \Macro{subparagraph}}% + \feentry{subsection}{Title of the sectional unit \Macro{subsection}}% + \feentry{subsubsection}{Title of the sectional unit \Macro{subsubsection}}% + \feentry{title}{Main title of the document, i.e. the argument of + \Macro{title} (for details about the size see the additional note at the + text on \autopageref{desc:maincls.macro.title})}% +\end{desctable} +% +\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}\\ + \XMacro{pagestyle}\PParameter{plain}\\ + \XMacro{pagestyle}\PParameter{headings}\\ + \XMacro{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[\phantomsection\label{desc:maincls.pagestyle.empty}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}, +\autopageref{desc:maincls.option.headsepline}). +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}, +\autopageref{desc:scrpage.pagestyle.useheadings}). +% +\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% + \caption{Default values for the elements of a page style} + \begin{tabular}{ll} + \toprule + Element & Default value \\ + \midrule + \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}\\ + \bottomrule + \end{tabular} + \label{tab:maincls.defaultFontsHeadFoot} +\end{table} +% +\begin{Example} + \phantomsection\label{sec:maincls.pageStyle.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{lstlisting} + \setkomafont{pagehead}{% + \normalfont\normalcolor\itshape\small + } + \setkomafont{pagenumber}{\normalfont\bfseries} +\end{lstlisting} + 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{lstlisting} + \addtokomafont{pagefoot}{\small} +\end{lstlisting} + 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}, +\autopageref{desc:scrpage.option.markuppercase}). + +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 +\autoref{tab:specialpagestyles}. +% +\begin{table} + \centering + \caption{Macros to set up page style of special pages} + \label{tab:specialpagestyles} + \begin{desctabular} + \mentry{titlepagestyle}{Page style for a title page when using + \emph{in-page} titles.}% + \mentry{partpagestyle}{Page style for the pages with \Macro{part} + titles.}% + \mentry{chapterpagestyle}{Page style for the first page of a chapter.}% + \mentry{indexpagestyle}{Page style for the first page of the index.}% + \end{desctabular} +\end{table} +% +The page styles can be redefined with the \Macro{renewcommand} macro. +\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{lstlisting} + \renewcommand*{\partpagestyle}{empty} +\end{lstlisting} + 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{lstlisting} + \renewcommand*{\chapterpagestyle}{chapter} +\end{lstlisting} + + 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{lstlisting} + \clearpage + \pagestyle{empty} + \renewcommand*{\chapterpagestyle}{empty} + \tableofcontents + \clearpage + \pagestyle{headings} + \renewcommand*{\chapterpagestyle}{plain} +\end{lstlisting} + Instead of the above you may do a local redefinition using a group. The + advantage will be that you don't need to know the current page style before + the change to switch back at the end. +\begin{lstlisting} + \clearpage + \begingroup + \pagestyle{empty} + \renewcommand*{\chapterpagestyle}{empty} + \tableofcontents + \clearpage + \endgroup +\end{lstlisting} + But notice that you never should put a numbered head into a group. Otherwise + you may get funny results with commands like \Macro{label}. +\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{lstlisting} + \renewcommand*{\chapterpagestyle}{headings} +\end{lstlisting} + 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{lstlisting} + \let\@rightmark\@secondoftwo + \def\rightmark{\expandafter\@rightmark + \firstmark\@empty\@empty} +\end{lstlisting} + 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{lstlisting} + \makeatletter + \renewcommand*{\rightmark}{% + \expandafter\@rightmark\botmark\@empty\@empty} + \makeatother +\end{lstlisting} + 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}, +\autopageref{desc:maincls.option.twoside}) 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}, +\autopageref{desc:maincls.option.cleardoublestandard} 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} + \Macro{ifthispagewasodd} \PName{true}\Macro{else} \PName{false}\Macro{fi} +\end{Declaration}% +\BeginIndex{Cmd}{ifthispageodd}% +\BeginIndex{Cmd}{ifthispagewasodd}% +\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{lstlisting} + This is a page with an \ifthispageodd{odd}{even} + page number. +\end{lstlisting} + 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. + + Sometimes you need to know the state of the last decision. This may be done + using the expert command \Macro{ifthispagewasodd}. This is either same like + \Macro{iftrue} or \Macro{iffalse} and may be used like those. +\end{Explain} +% +\EndIndex{Cmd}{ifthispageodd}% +\EndIndex{Cmd}{ifthispagewasodd}% + +\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 + \caption{Available numbering styles of page numbers} + \begin{tabular}{lll} + \toprule + numbering style & example & description \\ + \midrule + \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 \\ + \bottomrule + \end{tabular} + \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}, + \autopageref{desc:maincls.option.titlepage}, 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{lstlisting} + \documentclass{scrbook} + \begin{document} + \begin{titlepage} + \textbf{\Huge Me} + \end{titlepage} + \end{document} +\end{lstlisting} + 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}, +\autopageref{desc:maincls.macro.titlepagestyle}. + +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{Explain}% +\begin{Declaration} + \Macro{extratitle}\Parameter{half-title} +\end{Declaration}% +\BeginIndex{Cmd}{extratitle}% + 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{lstlisting} + \documentclass{scrbook} + \begin{document} + \extratitle{\textbf{\Huge Me}} + \title{It's me} + \maketitle + \end{document} +\end{lstlisting} + You can center the half-title and put it a little lower down the page: +\begin{lstlisting} + \documentclass{scrbook} + \begin{document} + \extratitle{\vspace*{4\baselineskip} + \begin{center}\textbf{\Huge Me}\end{center}} + \title{It's me} + \maketitle + \end{document} +\end{lstlisting} + 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}, +\autopageref{tab:maincls.elementsWithoutText}). The font size is however +not affected (see \autoref{tab:maincls.elementsWithoutText}, +\autopageref{tab:maincls.mainTitle}). 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 + \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}} + \begin{tabular}{llll} + \toprule + Element & Command & Font & Justification \\ + \midrule + 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 \\ + \bottomrule + \end{tabular} + \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{lstlisting} + \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{lstlisting} +\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{lstlisting} + \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 hazel-hen\\ + in eternal love\\ + from your dormouse.} + \maketitle + \end{document} +\end{lstlisting} + Please use your own favorite pet names. +\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}, +\autopageref{desc:maincls.option.abstracton}) + +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}, +\autopageref{desc:maincls.option.liststotoc}. + +\begin{Explain} + The table of contents is set as a not numbered chapter and is therefore + subjected to the side effects of the standard \Macro{chapter*} command, + which are described in \autoref{sec:maincls.structure}, + \autopageref{desc:maincls.macro.chapter*}. 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}. +\end{Explain}% +\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}. + +\begin{Explain} +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}, +\autopageref{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.% +\end{Explain} + +\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{lstlisting} + \documentclass{scrartcl} + \setcounter{tocdepth}{2} +\end{lstlisting} +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{lstlisting} + \documentclass{scrartcl} + \addtocounter{tocdepth}{-1} +\end{lstlisting} +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}\\ + \Macro{listtablename}\\ + \Macro{listfigurename} +\end{Declaration} +\BeginIndex{Cmd}{listoftables}% +\BeginIndex{Cmd}{listoffigures}% +\BeginIndex{Cmd}{listtablename}% +\BeginIndex{Cmd}{listfigurename}% +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}, +\autopageref{desc:maincls.option.listsleft}. Moreover, the options +\Option{liststotoc} and \Option{liststotocnumbered} have indirect influence, +see \autoref{sec:maincls.tocOptions}, +\autopageref{desc:maincls.option.liststotoc}). + +\begin{Explain} +The terms of the titles of this tables are stored at the macros +\Macro{listtablename} and \Macro{listfigurename}. If you're using a language +package like \Package{babel} and want to change these terms, you should read +the documentation of the language package. +\end{Explain} +% +\EndIndex{Cmd}{listoftables}% +\EndIndex{Cmd}{listoffigures}% +\EndIndex{Cmd}{listtablename}% +\EndIndex{Cmd}{listfigurename}% + + +\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}{Separation\protect\OnlyAt{\Class{scrbook}}} +\label{sec:maincls.separation} + +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{font matter}\Index{front matter}, the \emph{main + matter}\Index{main matter} and the \emph{back matter}\Index{back matter} of +a book. + +\begin{Declaration} + \Macro{frontmatter}\\ + \Macro{mainmatter}\\ + \Macro{backmatter} +\end{Declaration}% +\BeginIndex{Cmd}{frontmatter}% +\BeginIndex{Cmd}{mainmatter}% +\BeginIndex{Cmd}{backmatter}% +The macro \Macro{frontmatter} introduces the font matter in which roman +numbers are used for the page numbers. Chapter headings in a front matter +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 matter with the main text. If there is +no fton matter this command can be omitted. The default in the main matter is +arabic page numbering (re)starting with 1. + +The back matter is introduced with \Macro{backmatter}. Opinions differ in +what should be part of the back matter. 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 and the appendix. +Besides, the chapters at the back matter are similar to the chapters at the +front matter, but page numbering doesn't change. Nevertheless you may use +command \Macro{pagenumbering} from \autoref{sec:maincls.pageStyle}, +\autopageref{desc:maincls.macro.pagenumbering} of you want to change this. +% +\EndIndex{Cmd}{frontmatter}% +\EndIndex{Cmd}{mainmatter}% +\EndIndex{Cmd}{backmatter}% + + +\subsection{Structuring the Document}\Index[indexmain]{structuring} +\label{sec:maincls.structure} + +There are several commands to structure a document into parts, chapters, +sections and so on. + +\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}, +\autopageref{desc:maincls.macro.titlepagestyle}). + +\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}, +\autopageref{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}, +\autopageref{desc:maincls.option.smallheadings}). The +defaults are listed in \autoref{tab:maincls.structureElementsFont} +% +\begin{table} + \centering% + \caption[{Default font sizes for different levels of document + structuring}]{Default font sizes for different levels of document + structuring at \Class{scrbook} and \Class{scrreprt}} + \begin{tabular}{lll} + \toprule + class option & element & default\\ + \midrule + \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}\\ + \bottomrule + \end{tabular} + \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{lstlisting} + \setkomafont{sectioning}{\normalcolor\sffamily} + \part{Appendices} + \addtokomafont{sectioning}{\bfseries} +\end{lstlisting} + 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{lstlisting} + \addtokomafont{part}{\normalfont\sffamily} + \addtokomafont{partnumber}{\normalfont\sffamily} +\end{lstlisting} + or using: +\begin{lstlisting} + \addtokomafont{part}{\mdseries} + \addtokomafont{partnumber}{\mdseries} +\end{lstlisting} + 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{lstlisting} + \setkomafont{sectioning}{\normalcolor\bfseries} +\end{lstlisting} + 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}, \autopageref{sec:typearea.tips.cite} 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}, +\autopageref{desc:maincls.macro.titlepagestyle}). + +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}, +\autopageref{desc:maincls.macro.titlepagestyle}). + +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{lstlisting} + \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{lstlisting} + 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}, +\autopageref{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{lstlisting} + \newcommand*{\raggedsection}{\raggedright} +\end{lstlisting} +This command can be redefined with \Macro{renewcommand}. +\begin{Example} + You prefer justified headings. You write in the preamble of your document: +\begin{lstlisting} + \renewcommand*{\raggedsection}{} +\end{lstlisting} + or short: +\begin{lstlisting} + \let\raggedsection\relax +\end{lstlisting} + 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{Explain}% +\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}% + 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}, +\autopageref{desc:maincls.option.pointlessnumbers} +{\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{lstlisting} + \newcommand*{\partformat}{\partname~\thepart\autodot} + \newcommand*{\chapterformat}{% + \chapappifchapterprefix{\ }\thechapter\autodot\enskip} + \newcommand*{\othersectionlevelsformat}[1]{% + \csname the#1\endcsname\autodot\enskip} +\end{lstlisting} + +\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{lstlisting} + \renewcommand*{\partformat}{\thepart\autodot} +\end{lstlisting} + 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}, + \autopageref{desc:maincls.option.pointlessnumbers}). + + 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{lstlisting} + \renewcommand*{\othersectionlevelsformat}[1]{% + \llap{\csname the#1\endcsname\autodot\enskip}} +\end{lstlisting} + The almost unknown command \Macro{llap} in the definition above, + puts its argument left to the current possition without changing the + position. A much better \LaTeX{} solution would be: +\begin{lstlisting} + \renewcommand*{\othersectionlevelsformat}[1]{% + \makebox[0pt][r]{% + \csname the#1\endcsname\autodot\enskip}} +\end{lstlisting} + See \cite{latex:usrguide} for more information about the optional arguments + of \Macro{makebox}. +\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}, +\autopageref{desc:maincls.option.chapterprefix}) +\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{lstlisting} + \newcommand*{\chaptermarkformat}{% + \chapappifchapterprefix{\ }\thechapter\autodot\enskip} + \newcommand*{\sectionmarkformat}{\thesection\autodot\enskip} + \newcommand*{\subsectionmarkformat}{% + \thesubsection\autodot\enskip} +\end{lstlisting} +\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{lstlisting} + \renewcommand*{\chaptermarkformat}{% + \chapapp~\thechapter\autodot\enskip} +\end{lstlisting} +\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}, \autopageref{desc:maincls.counter.tocdepth}. +% +\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{lstlisting} + \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{lstlisting} + Depending on the settings for the heading\Index{heading} (see + \autoref{sec:maincls.fontOptions}, + \autopageref{desc:maincls.option.smallheadings}) size and the + \Environment{abstract} environment\IndexEnv{abstract} (see + \autoref{sec:maincls.formattingOptions}, + \autopageref{desc:maincls.option.abstracton}), 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}, +\autopageref{desc:maincls.environment.abstract}). + +The\ChangedAt{v2.8p}{\Class{scrbook}\and\Class{scrreprt}} first +optional argument \PName{position} determines the position at which +the preamble is placed with the help of one or two letters. For the +vertical placement there are two possibilities at present: +\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{lstlisting} + \newcommand*{\dictumauthorformat}[1]{(#1)} +\end{lstlisting} +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% + \caption{Default settings for the elements of a dictum} + \begin{tabular}{ll} + \toprule + Element & Default \\ + \midrule + \FontElement{dictumtext} & + \Macro{normalfont}\Macro{normalcolor}\Macro{sffamily}\Macro{small}\\ + \FontElement{dictumauthor} & + \Macro{itshape}\\ + \bottomrule + \end{tabular} + \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{lstlisting} + \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{lstlisting} + 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{lstlisting} + \renewcommand*{\dictumwidth}{.25\textwidth} +\end{lstlisting} +\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{lstlisting} + \deffootnote[1em]{1.5em}{1em} + {\textsuperscript{\thefootnotemark}} +\end{lstlisting} +\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}, +\autopageref{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{lstlisting} + \deffootnotemark{% + \textsuperscript{\thefootnotemark}} +\end{lstlisting} +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}, +\autopageref{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{lstlisting} + \deffootnote{1em}{1em}{\thefootnotemark\ } +\end{lstlisting} + 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{lstlisting} + \deffootnote{1.5em}{1em}{% + \makebox[1.5em][l]{\thefootnotemark}} +\end{lstlisting} + + 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{lstlisting} + \setkomafont{footnote}{\sffamily} +\end{lstlisting} +\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{lstlisting} + \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{lstlisting} + 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}\\ + \XMacro{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}\\ + \XMacro{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}, +\autopageref{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{lstlisting} + \setkomafont{descriptionlabel}{\normalfont\bfseries} +\end{lstlisting} + 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{lstlisting} + \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{lstlisting} + 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}\\ + \XMacro{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{lstlisting} + \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{lstlisting} + 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{lstlisting} + \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{lstlisting} + 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\nopagebreak + have always something to repair\\ + \bigskip + Don't trust a men, my son, who tells you\nopagebreak + 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{lstlisting} + 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{lstlisting} + 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{lstlisting} + \newenvironment{SourceCodeFrame}{% + \begin{addmargin*}[1em]{-1em}% + \begin{minipage}{\linewidth}% + \rule{\linewidth}{2pt}% + }{% + \rule[.25\baselineskip]{\linewidth}{2pt}% + \end{minipage}% + \end{addmargin*}% + } +\end{lstlisting} + 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{lstlisting} +\newenvironment{\SourceCodeFrame}{% + \begin{addmargin*}[1em]{-1em}% + \begin{minipage}{\linewidth}% + \rule{\linewidth}{2pt}% +}{% + \rule[.25\baselineskip]{\linewidth}{2pt}% + \end{minipage}% + \end{addmargin*}% +} +\end{lstlisting} + \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} and +\Macro{ifthispagewasodd} at \autoref{sec:maincls.pageStyle}, +\autopageref{desc:maincls.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{lstlisting} + \marginline{\texttt{scrartcl}} +\end{lstlisting} + + Instead of \Macro{marginline} you could have used \Macro{marginpar} + too. In fact the first command is implemented internally as: +\begin{lstlisting} + \marginpar[\raggedleft\texttt{scrartcl}] + {\raggedright\texttt{scrartcl}} +\end{lstlisting} + 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. The package \Package{mparhack}\IndexPackage{mparhack} (see + \cite{package:mparhack}) would be a solution for this problem with both + \Macro{marginpar} and \Macro{marginline}. + + Note that you may not use \Macro{marginpar} or \Macro{marginnote} within + float environemnts like tables or figures. And you may not use these + commands at displayed math. +\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. + + % TODO: Translate this: +% Haeufig werden die Fliessumgebungen\Index[indexmain]% +% {Fliessumgebung=Fliessumgebung} von Anfaengern nicht richtig +% verstanden. So wird oft die Forderung aufgestellt, eine Tabelle oder +% Abbildung genau an einer bestimmten Position im Text zu setzen. Dies +% ist jedoch nicht erforderlich, da auf Fliessumgebungen im Text ueber +% eine Referenz verwiesen wird. Es ist auch nicht sinnvoll, da ein +% solches Objekt an einer Stelle nur dann gesetzt werden kann, wenn +% auf der Seite noch genuegend Platz fuer das Objekt vorhanden ist. Ist +% dies nicht der Fall, muesste das Objekt auf die naechste Seite +% umbrochen werden und auf der aktuellen Seite wuerde ein +% moeglicherweise sehr grosser leerer Raum bleiben. + + 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}, +\autopageref{desc:maincls.option.tablecaptionabove}). 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{lstlisting} + \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{lstlisting} + 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{lstlisting} + \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{lstlisting} + 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}, + \autopageref{desc:maincls.option.tablecaptionabove}). 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}, + \autopageref{desc:maincls.option.origlongtable}). If + \Package{caption2}\IndexPackage{caption2} (see \cite{package:caption}) 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}\\% + \XEnvironment{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{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} +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{lstlisting} + \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{lstlisting} + \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}, +\autopageref{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% + \caption{Font defaults for the elements of figure or table captions} + \begin{tabular}{ll} + \toprule + element & default \\ + \midrule + \FontElement{caption} & \Macro{normalfont} \\ + \FontElement{captionlabel} & \Macro{normalfont}\\ + \bottomrule + \end{tabular} + \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{lstlisting} + \addtokomafont{caption}{\small} +\end{lstlisting} + Furthermore, you would like the labels to be printed in sans serif and + bold. You add: +\begin{lstlisting} + \setkomafont{captionlabel}{\sffamily\bfseries} +\end{lstlisting} + 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} + \FloatStyle{komaabove}\\ + \FloatStyle{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{lstlisting} + \newcommand*{\captionformat}{:\ } +\end{lstlisting} +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{lstlisting} + \renewcommand*{\captionformat}{~--~} +\end{lstlisting} + 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{lstlisting} + \newcommand*{\figureformat}{\figurename~\thefigure\autodot} + \newcommand*{\tableformat}{\tablename~\thetable\autodot} +\end{lstlisting} +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{lstlisting} + \renewcommand*{\figureformat}{} + \renewcommand*{\tableformat}{} + \renewcommand*{\captionformat}{} +\end{lstlisting} +\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}, +\autopageref{desc:maincls.option.noonelinecaption}. + +\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{lstlisting} + \begin{figure} + \setcapindent{1em} + \fbox{\parbox{.95\linewidth}{\centering{\KOMAScript}}} + \caption{Examples with slightly indented caption + starting at the second line} + \end{figure} +\end{lstlisting} + 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{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} +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}, +\autopageref{desc:maincls.option.noonelinecaption}) 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{lstlisting} + \setcapwidth[c]{8cm} +\end{lstlisting} + 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{lstlisting} + \newlength{\Figurewidth} +\end{lstlisting} + 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{lstlisting} + \begin{figure} + \centering% + \settowidth{\Figurewidth}{% + \fbox{\quad\KOMAScript\qaud}% + }% + \fbox{\quad\KOMAScript\quad}% + \setcapwidth[c]{\Figurewidth} + \caption{Example of a centered caption below the figure} + \end{figure} +\end{lstlisting} + 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{lstlisting} + \newcommand{\Figure}[1]{% + \settowidth{\Figurewidth}{#1}% + \setcapwidth[c]{\Figurewidth}% + #1} +\end{lstlisting} + Using this command the example abbreviates to: +\begin{lstlisting} + \begin{figure} + \centering% + \Figure{\fbox{\quad\KOMAScript\quad}}% + \caption{Example of a centered caption below the figure} + \end{figure} +\end{lstlisting} + + 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{lstlisting} + \newsavebox{\Figurebox} + \newenvironment{FigureDefinesCaptionWidth}{% + \begin{lrbox}{\Figurebox}% + }{% + \end{lrbox}% + \global\setbox\Figurebox=\box\Figurebox% + \aftergroup\Setfigurebox% + } + \newcommand{\Setfigurebox}{% + \Figure{\usebox{\Figurebox}}} +\end{lstlisting} + This definition uses the macro \Macro{Figure} defined above. In + the main text you write: +\begin{lstlisting} + \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{lstlisting} + 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{lstlisting} + \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{lstlisting} + As the next step you only have to put the \Macro{caption} command in + a \Macro{parbox} too: +\begin{lstlisting} + \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{lstlisting} + 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}, +\autopageref{desc:maincls.macro.textsuperscript} 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{lstlisting} + \newcommand*{\Molek}[2]{#1\textsubscript{#2}} +\end{lstlisting} + \newcommand*{\Molek}[2]{#1\textsubscript{#2}} + Using this you then write: +\begin{lstlisting} + 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{lstlisting} + 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{lstlisting} + \newcommand*{\Molek}[2]{\textsf{#1\textsubscript{#2}}} +\end{lstlisting} + \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}, +\autopageref{desc:maincls.option.pointlessnumbers}. + +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}, +\autopageref{desc:maincls.option.appendixprefix}). 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}, + \autopageref{desc:maincls.option.chapterprefix}). 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{lstlisting} + \newcommand*{\appendixmore}{% + \renewcommand*{\chapterformat}{% + \appendixname~\thechapter\autodot\enskip} + \renewcommand*{\chaptermarkformat}{% + \appendixname~\thechapter\autodot\enskip} + } +\end{lstlisting} +% + 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{lstlisting} + \newcommand*{\appendixmore}{% + \renewcommand*{\othersectionlevelsformat}[1]{% + \ifthenelse{\equal{##1}{section}}{\appendixname~}{}% + \csname the##1\endcsname\autodot\enskip} + \renewcommand*{\sectionmarkformat}{% + \appendixname~\thesection\autodot\enskip} + } +\end{lstlisting} + 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}, \autopageref{desc:maincls.macro.partformat} + and \autopageref{desc:maincls.macro.chaptermark}. +\end{Example} +% +\EndIndex{Cmd}{appendixmore}% + + +\begin{Declaration} + \Macro{setbibpreamble}\Parameter{preamble} +\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{lstlisting} + \setbibpreamble{References are in alphabetical order. + References with more than one author are sorted + according to the first author.} +\end{lstlisting} + 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{lstlisting} + \setbibpreamble{\raggedright} +\end{lstlisting} + You can have a look at the result in the bibliography of this guide. +\end{Example} +% +\EndIndex{Cmd}{setbibpreamble} + + +\begin{Declaration} + \Macro{setindexpreamble}\Parameter{preamble} +\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{lstlisting} + \setindexpreamble{In \textbf{bold} printed page numbers + are references to the definition of terms.\par\bigskip} +\end{lstlisting} +\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}, +\autopageref{desc:maincls.macro.titlepagestyle}). + +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{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}% + + \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}% + +\end{Explain} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "../guide" +%%% End: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrdatetime.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrdatetime.tex new file mode 100644 index 00000000000..021dd9172fc --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrdatetime.tex @@ -0,0 +1,233 @@ +% ====================================================================== +% scrdatetime.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3b of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3b or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrdatetime.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3b, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3b ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrpage2 of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel über scrpage2 in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\ProvidesFile{scrdatetime.tex}[{2005/11/27 KOMA-Script guide (chapter: + scrdate, scrtime)}] +% Date of translated german file: 2005-11-27 + +\chapter{Week-Day and Time Using \Package{scrdate} and \Package{scrtime}} +\labelbase{datetime} + +There are two packages at \KOMAScript{} to improve and extend the +handling of date\Index{date} and time\Index{time}. So you have not +only the standard commands \Macro{today} and \Macro{date}. Like all +the other packages from \KOMAScript{} bundle these two packages may be used +not only with \KOMAScript{} classes but also with standard and many +other classes. + +\section{The Name of the Current Day of Week Using \Package{scrdate}} +\label{sec:sec:datetime.scrdate} +\BeginIndex{Package}{scrdate} + +The first problem is the question about the current day of week. The answer +may be given by the package \Package{scrdate}. + +\begin{Declaration} + \Macro{todaysname} +\end{Declaration}% +\BeginIndex{Cmd}{todaysname}% +You should know, that you may get the current date with +\Macro{today}\IndexCmd{today} in a language dependend +spelling. \Package{scrdate} offers you the command \Macro{todaysname}. This +results in the name of the current day of week in a language dependend +spelling. + +\begin{Example} + At your document you want to show the name of the week-day at which + the \File{dvi}-file was generated using \LaTeX. To do this, you + write: +\begin{lstlisting} + I've done the \LaTeX-run of this document on a \todaysname. +\end{lstlisting} + This will result in e.g.: + \begin{quote} + I've done the \LaTeX-run of this document on a \todaysname. + \end{quote} +\end{Example} + +Note that the package isn't able to decline. The known terms are the nominativ +singular that may be used e.g. at the date of a letter. For this the example +above is correct only at some languages. + +\begin{Explain} + \textbf{Tip:} The names of the week-days are saved in + capitalization. So the first letter is a capital letter, all the + others are small letters. But at some languages you also need the + names with a first letter in lower case. You may achieve this using + the standard \LaTeX{} command \Macro{MakeLowercase}. You simply have + to write \Macro{MakeLowercase}\PParameter{\Macro{todaysname}}. +\end{Explain} +\EndIndex{Cmd}{todaysname} + +\begin{Declaration} + \Macro{nameday}\Parameter{name} +\end{Declaration}% +\BeginIndex{Cmd}{nameday}% +You should know, that you may change the output of \Macro{today} using +\Macro{date}\IndexCmd{date}. In a analogous way you can change the +output of \Macro{todaysname} using \Macro{nameday} into \PName{name}. +\begin{Example} + You're changing the current date into a fix value using + \Macro{date}. You are not interested in the name of the day, but + you want to show, that it is a workday. So you set: +\begin{lstlisting} + \nameday{workday} +\end{lstlisting} + After this the previous example will result in: + \begin{quote} + I've done the \LaTeX-run of this document on a workday. + \end{quote} +\end{Example} +\EndIndex{Cmd}{nameday} + +Package \Package{scrdate} knows the languages english (english, american, +USenglish, UKenglish and british), german (german, ngerman and austrian), +french, italian, spanish, croatian, and finnish. If you want to configure it +for other languages, see \File{scrdate.dtx}. + +At current implementation it doesn't matter, if you're loading +\Package{scrdate} before or after +\Package{german}\IndexPackage{german}, +\Package{ngerman}\IndexPackage{ngerman}, +\Package{babel}\IndexPackage{babel} or similar packages. The current +language will be setup at \Macro{begin}\PParameter{document}. + +\begin{Explain} + To explain it a little bit more exactly: While you are using a + language selection, which works in a compatible way to + \Package{babel}\IndexPackage{babel} or + \Package{german}\IndexPackage{german}, the correct language will be + used by \Package{scrdate}. If you are using another language + selection you will get english caption names. At \File{scrdate.dtx} + you will find the description of the \Package{scrdate}-commands for + defining the names. +\end{Explain} +\EndIndex{Package}{scrdate} + + +\section{Getting the Time with Package \Package{scrtime}} +\label{sec:datetime.scrtime} +\BeginIndex{Package}{scrtime} + +The second problem is the question about current time. The solution may be +found using package \Package{scrtime}. + +\begin{Declaration}% + \Macro{thistime}\OParameter{delimiter}\\ + \Macro{thistime*}\OParameter{delimiter} +\end{Declaration}% +\BeginIndex{Cmd}{thistime}\BeginIndex{Cmd}{thistime*}% +\Macro{thistime} results in the current\Index{time}. +The delimiter between the values of hour and minute +can be given in the optional argument. +The default symbol of the delimiter is "\PValue{:}". + +\Macro{thistime*} works in the same way as \Macro{thistime}. +The difference between both is that the value of the minute +using \Macro{thistime*} is not preceded with zero when its value +is less than 10, thus using \Macro{thistime} the minute-value +has always two places. +\begin{Example} + The line +\begin{lstlisting} + Your train departs at \thistime . +\end{lstlisting} + results for example in: + \begin{quote} + Your train departs at \thistime . + \end{quote} + or: + \begin{quote} + Your train departs at 23:09. + \end{quote} + \bigskip + In contrast to the prevous example a line like: +\begin{lstlisting} + This day is already \thistime*[\ hours and\ ] minutes old. +\end{lstlisting} + results in: + \begin{quote} + This day is already \thistime*[\ hours and\ ] minutes old. + \end{quote} + or: + \begin{quote} + This day is already 12 hours and 25 minutes old. + \end{quote} +\end{Example} +\EndIndex{Cmd}{thistime}\EndIndex{Cmd}{thistime*} + +\begin{Declaration}% + \Macro{settime}\Parameter{Time} +\end{Declaration}% +\BeginIndex{Cmd}{settime}% +\Macro{settime} sets the output \Macro{thistime} and +\Macro{thistime*} on the value of \PName{Time}. +Afterwards the optinal parameter of \Macro{thistime} or +\Macro{thistime*} is ignored, since the result +of \Macro{thistime} or \Macro{thistime*} +was completely determined using \Macro{settime}.% +\EndIndex{Cmd}{settime} + +\begin{Declaration} + \Option{12h}\\ + \Option{24h} +\end{Declaration}% +\BeginIndex{Option}{12h}\BeginIndex{Option}{24h}% +Using the options \Option{12h} and \Option{24h} one can +select whether the result of \Macro{thistime} and \Macro{thistime*} +is in 12- or in 24-hour format. The default is \Option{24h}.% + +The option has no effect on the results of +\Macro{thistime} and \Macro{thistime*} if \Macro{settime} +has been used.% +\EndIndex{Option}{12h}\EndIndex{Option}{24h} +\EndIndex{Package}{scrtime} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "../guide" +%%% End: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex new file mode 100644 index 00000000000..52e3f8e610a --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlfile.tex @@ -0,0 +1,310 @@ +% ====================================================================== +% scrlfile.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3b of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3b or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrlfile.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3b, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3b ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrlfile of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------------- +% +% Kapitel über scrlfile in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\ProvidesFile{scrlfile.tex}[2005/11/27 KOMA-Script guide (chapter: scrlfile)] +% Date of translated german file: 2005/08/10 + +\chapter{Control Package Dependencies with \Package{scrlfile}} +\labelbase{scrlfile} + +\BeginIndex{Package}{scrlfile} + +\begin{Explain} + The introduction of \LaTeXe{} in 1994 brought many changes in the handling + with \LaTeX-extensions. Today the package author has many macros in order + to determine if another package or class is employed and whether specific + options are used. The author can load other packages or can specify options + in the the case the package is loaded later. This has led to the + expectation that the order of package-loading will be not important. But + this hope has not been fulfilled. +\end{Explain} + +\section{About Package Dependencies} +\label{sec:scrlfile.dependency} +\begin{Explain} + Often different packages define or redefine one macro again and again. In + such a case the order of package-loading becomes very important. For the + user this is sometimes difficult to understand the behaviour and in some + cases the user wants only react on the loading of a package. This is also + not really simple. + + Assuming the simple example that loads the package \Package{longtable} with + a \KOMAScript{} document-class employed. The \Package{longtable} package + defines table captions suitable for the standard classes, but the captions + are totally unsuitable for documents using \KOMAScript{} and thus the + provided configuration commands have no influence. In order to solve this + problem the commands which are responsible for the table captions of the + \Package{longtable} package have to be re-defined. But at the moment when + the \Package{longtable} is loaded the \KOMAScript{} class is already + processed. + + The only chance for \KOMAScript{} was to delay the re-definition until the + begin of the document with help of the macro \Macro{AtBeginDocument}. If + the user wants to change the definitions too, it is recommended to do this + in the preamble of the document. But this is impossible since later at + \Macro{begin}\PParameter{document} \KOMAScript will again overwrite the + user-definition with its own. Therefore the user has to delay his + definition with \Macro{AtBeginDocument} as well. + + However, \KOMAScript{} shouldn't delay the re-definition until + \Macro{begin}\PParameter{document}. It would be enough to delay until the + package \Package{longtable} has been loaded. But unfortunately the basic + \LaTeX{} does not define appropriate commands. The package + \Package{scrlfile} provides redress here. + + Likewise, it might be conceivable that before a package is loaded one would + like to save the definition of a macro in a help-macro, in order to restore + its meaning after the package has been loaded. The package + \Package{scrlfile} allows this too. + + The employment of \Package{scrlfile} is not limited to package dependencies + only. Even dependencies with any other file can be attended. For example + the user can be warned if the not uncritical file \File{french.ldf} has been + loaded. + + Though the package is particularly interesting for package authors, there + are of course applications for normal \LaTeX{} users too. Therefore this + chapter gives and explains examples for both groups of users. +\end{Explain} + + +\section{Actions Prior and After Loading} +\label{sec:scrlfile.macros} + +\begin{Declaration} + \Macro{BeforeFile}\Parameter{file}\Parameter{instructions}\\ + \Macro{AfterFile}\Parameter{file}\Parameter{instructions} +\end{Declaration}% +\BeginIndex{Cmd}{BeforeFile}% +\BeginIndex{Cmd}{AfterFile}% +The macro \Macro{BeforeFile} enables to execute \PName{instructions} +the next time the \PName{file} is loaded. +In the same way works \Macro{AfterFile}, but here the +\PName{instructions} will be executed after the \PName{file} +has been loaded. +If \PName{file} will never be loaded then the \PName{instructions} +will never be executed. + +\begin{Explain} + In order to implement those features \Package{scrlfile} + re-defines the well known \LaTeX{} command + \Macro{InputIfFileExists}. + If this macro has not the expected definition \Package{scrlfile} + gives a warning. + This is for the case that in future \LaTeX{} versions + the macro can have a different definition or an other package + has already re-defined it. + + The command \Macro{InputIfFileExists} is used + everytime \LaTeX{} has to load a file. + This is independent from whether the actual command was \Macro{LoadClass}, + \Macro{documentclass}, \Macro{usepackage}, \Macro{RequiresPackage}, + or \Macro{include}. Exclusively the command +\begin{lstlisting} + \input foo +\end{lstlisting} + loads the file \texttt{foo} without to utilize + \Macro{InputIfFileExists}. Therefore one should always use +\begin{lstlisting} + \input{foo} +\end{lstlisting} + instead. Notice the parentheses surrounding the file name! +\end{Explain} +% +\EndIndex{Cmd}{BeforeFile}% +\EndIndex{Cmd}{AfterFile}% + +\begin{Declaration} + \Macro{BeforeClass}\Parameter{class}\Parameter{instructions}\\ + \Macro{BeforePackage}\Parameter{package}\Parameter{instructions} +\end{Declaration}% +\BeginIndex{Cmd}{BeforeClass}% +\BeginIndex{Cmd}{BeforePackage}% +These both commands work the same way as \Macro{BeforeFile}. +The only difference is that the document class \PName{class} +and the \LaTeX{} package \PName{package} are specified +with their names and not with their file names. +That means the file extensions \File{.cls} and \File{.sty} +can be omitted. +% +\EndIndex{Cmd}{BeforeClass}% +\EndIndex{Cmd}{BeforePackage}% + +\begin{Declaration} + \Macro{AfterClass}\Parameter{class}\Parameter{instructions}\\ + \Macro{AfterClass*}\Parameter{class}\Parameter{instructions}\\ + \Macro{AfterPackage}\Parameter{package}\Parameter{instructions}\\ + \Macro{AfterPackage*}\Parameter{package}\Parameter{instructions} +\end{Declaration}% +\BeginIndex{Cmd}{AfterClass}% +\BeginIndex{Cmd}{AfterClass*}% +\BeginIndex{Cmd}{AfterPackage}% +\BeginIndex{Cmd}{AfterPackage*}% +The commands \Macro{AfterClass} und \Macro{AfterPackage} +work the same way as \Macro{AfterFile}. +The only difference is that the document class \PName{class} +and the \LaTeX{} package \PName{package} are specified +with their names and not with their file names. +That means the file extensions \File{.cls} and \File{.sty} +can be omitted. +The starred versions execute the \PName{instructions} not +only next time the class or package is loaded, but also +immediately if the class or package has been loaded already. +% +\EndIndex{Cmd}{AfterClass}% +\EndIndex{Cmd}{AfterClass*}% +\EndIndex{Cmd}{AfterPackage}% +\EndIndex{Cmd}{AfterPackage*}% + +\begin{Example} + In the following an example for class and package authors + shall be given. + It shows how \KOMAScript{} itself employs the new commands. + The class \Class{scrbook} contains: +\begin{lstlisting} +\AfterPackage{hyperref}{% + \@ifpackagelater{hyperref}{2001/02/19}{}{% + \ClassWarningNoLine{scrbook}{% + You are using an old version of hyperref package!% + \MessageBreak% + This version has a buggy hack at many drivers% + \MessageBreak% + causing \string\addchap\space to behave strange.% + \MessageBreak% + Please update hyperref to at least version + 6.71b}}} +\end{lstlisting} + Old versions of the \Package{hyperref} package re-define + a macro of the \Class{scrbook} class in a way that does not + work with newer \KOMAScript{} versions. + New versions of \Package{hyperref} neglect these changes + if a new \KOMAScript{} version is detected. + For the case that \Package{hyperref} is loaded the code + in \Class{scrbook} verifies that a appropriate + \Package{hyperref} version is used. If not the command gives + a warning. + + At other places in three \KOMAScript{} classes following can be found: +\begin{lstlisting} + \AfterPackage{caption2}{% + \renewcommand*{\setcapindent}{% +\end{lstlisting} + Next the package \Package{caption2} has been loaded, and only + if the package has been loaded really, \KOMAScript{} re-defines + its own command \Macro{setcapindent}. + The exact code of the definition is not important. + It should only be noted that \Package{caption2} claims the + control over the \Macro{caption} macro. + Thus the normal definition of the \Macro{setcapindent} macro + would not work as expected. + The re-definition improves the collaboration with \Package{caption2}. + + There are of course useful examples for normal \LaTeX{} user too. + Suppose a document that should be availbale as PS file, using + LaTeX{} and dvips, and as PDF file, using pdf\LaTeX. + The document should contain hyper-links. + In the List of Tables there are entries longer than one line. + This is not a problem for the pdf\LaTeX{} way, since here + hyper-links can run across multiple lines. + But if a \Package{hyperref} driver for dvips or + hyper\TeX{} is used then this is not possible. + In this case one wants that for the \Package{hyperref} setup + the \Option{linktocpage} is used. + + The decision what \Package{hyperref} driver has to be used + happens automatically via \File{hyperref.cfg}. + The file has for example the content below. +\begin{lstlisting} + \ProvidesFile{hyperref.cfg} + \@ifundefined{pdfoutput}{\ExecuteOptions{dvips}} + {\ExecuteOptions{pdftex}} + \endinput +\end{lstlisting} + + All following is now the task of \Macro{AfterFile}. +\begin{lstlisting} + \documentclass{article} + \usepackage{scrlfile} + \AfterFile{hdvips.def}{\hypersetup{linktocpage}} + \AfterFile{hypertex.def}{\hypersetup{linktocpage}} + \usepackage{hyperref} + \begin{document} + \listoffigures + \clearpage + \begin{figure} + \caption{This is an example for a long figure caption, + but even though it does not employ the optional + caption argument that would allow to write + a short caption in the List of Figures.} + \end{figure} + \end{document} +\end{lstlisting} + If now \Package{hyperref} drivers \Option{hypertex} or + \Option{dvips} are used then the useful \Package{hyperref} option + \Option{linktocpage} will be set. + In the pdf\LaTeX{} case the option will not be set, since + in that case an other \Package{hyperref} driver \File{hpdftex.def} + will be used. That means neither \File{hdvips.def} nor + \File{hypertex.def} will be loaded. +\end{Example} + +\begin{Explain} + Furthermore the loading of package \Package{scrlfile} + and the \Macro{AfterFile} statement can be written + in the private \File{hyperref.cfg}. + But then instead of \Macro{usepackage} the macro + \Macro{RequiresPackage} ought be used, see \cite{latex:clsguide}. + The new lines have to be inserted directly after + \Macro{ProvidesFile} line, thus prior to the execution + of the options \Option{dvips} or \Option{pdftex}. +\end{Explain}% +\EndIndex{Package}{scrlfile} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "../guide" +%%% End: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2.tex new file mode 100644 index 00000000000..cb23e248da3 --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlttr2.tex @@ -0,0 +1,3586 @@ +% ====================================================================== +% scrlttr2.tex +% Copyright (c) Markus Kohm, 2002-2006 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3b of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3b or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrlttr2.tex +% Copyright (c) Markus Kohm, 2002-2006 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3b, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3b ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrlttr2 of the KOMA-Script guide +% Maintained by Markus Kohm +% Translation: Harald Bongartz, Georg Grandke, Raimund Kohl, +% Jens-Uwe Morawski, Markus Kohm. Stephan Hennig +% +% ---------------------------------------------------------------------- +% +% Kapitel über scrlttr2 in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% Übersetzung: Harald Bongartz, Georg Grandke, Raimund Kohl, +% Jens-Uwe Morawski, Markus Kohm, Stephan Hennig +% +% ============================================================================ + +\ProvidesFile{scrlttr2.tex}[2006/07/06 KOMA-Script guide (chapter: scrlttr2)] +% Date of translated german file: 2006-04-24 +% + +\chapter{The New Letter Class \Class{scrlttr2}} +\labelbase{scrlttr2} + +\BeginIndex{Class}{scrlttr2}\BeginIndex{}{Letters}% +\begin{Explain} +Since June 2002 release \KOMAScript{} provides a completely +rewritten letter class\ChangedAt{v2.8q}{\Class{scrlttr2}}. Although part +of the code is identical to main classes described in \autoref{cha:maincls}, +letters are quite different from articles, reports, books, and such. +That alone justifies a separate chapter about the letter class. But +there is another reason for a chapter on \Class{scrlttr2}. This class has +been redeveloped from scratch and provides a new user interface different +from every other class the author knows. This new user interface may be +uncommon but the author is convinced both old and new \KOMAScript{} users +will benefit from its advantages. + +\section{Looking Back on the Old Letter Class} +\label{sec:scrlttr2.scrlettr} + +With June 2002 release the old letter class +\Class{scrlettr}\IndexClass{scrlettr} became obsolete. It is recommended +not to use that class for new applications. There is no development on +the old letter class anymore, and support is very restricted. However, +if you really need the documentation of the old letter class, you can +still find it in file \File{scrlettr.dtx}, but only in German. You can +run it through \LaTeX{} some times, like that: +\begin{lstlisting} + latex scrlettr.dtx + latex scrlettr.dtx + latex scrlettr.dtx +\end{lstlisting} +You get file \File{scrlettr.dvi} containing the old German manual. + +To facilitate the transition to the new class, there is a compatibility +option. In general, the complete functionality still remains in the new class. +Without that compatibility option, the user interface and the defaults will be +different. More detail on this option is provided in +\autoref{sec:scrlttr2.options} and \autoref{sec:scrlttr2.fromscrlettr}. +\end{Explain} + +\section{Options} +\label{sec:scrlttr2.options} + +The letter class \Class{scrlttr2} uses the package +\Package{keyval}\IndexPackage{keyval} to handle options. This is part of +the \Package{graphics} package (see \cite{package:graphics}). Since +\Package{graphics} is part of the \emph{required} section of \LaTeX, it +should be found in every \LaTeX{} distribution. Should your \TeX{} +distribution contain \LaTeX, but not the packages \Package{graphics} +and \Package{keyval}, please complain to your \TeX{} distributor. If you +want to use \Class{scrlttr2}, you will have to install the +\Package{graphics} package yourself in that case. + +\begin{Explain} + The special feature of the \Package{keyval} package is the possibility to + accompany options by values. You do not only need a lot less options, but + maybe even fewer optional arguments. You will see that when discussing the + \Environment{letter} environment in \autoref{sec:scrlttr2.addressee}, + \autopageref{desc:scrlttr2.environment.letter}. The class will automatically + load the \Package{keyval} package. If you need to supply options to the + \Package{keyval} package, you should use the \Macro{PassOptionsToPackage} + command before \Macro{documentclass}. +\end{Explain} + +\subsection{Defining Options Later} +\label{sec:scrlttr2.options.late} + +This section anticipates a feature of the new letter class. The meaning +of this feature will not become clear until the structure of a document +with more than one letter inside and another feature of \Class{scrlttr2} +will be understood. But to keep the number of forward references low, it +is reasonable to describe them this early. + +\begin{Declaration} + \Macro{KOMAoptions}\Parameter{option list} +\end{Declaration} +\BeginIndex{Cmd}{KOMAoptions}% +The possibility to change many options after loading the class is a +special feature of the \Class{scrlttr2} class. The \Macro{KOMAoptions} +command serves this purpose, taking options and their values as +arguments. You can list multiple options, separated by commas, like in +the optional argument of \Macro{documentclass}. If an option is only +available when loading the class, i.\,e.\ as an optional argument to +\Macro{documentclass}, there will be an explicit remark in the option's +description. + +\begin{Explain} +If you set an option to an illegal value within the \PName{option +list}, \LaTeX{} will stop and show an error message. By entering +``\texttt{h}'' you will get an explanation that will also list possible +values for that particular option. +\end{Explain} +% +\EndIndex{Cmd}{KOMAoptions}% + +\subsection{Page Layout Options} +\label{sec:scrlttr2.typeareaOptions} + +In contrast to the old \Class{scrlettr} class, but in correspondence +with the other \KOMAScript{} classes, the \Class{scrlttr2} class refers +to the \Package{typearea} package for the construction of the page +layout (see \autoref{cha:typearea}). The package will be loaded +by the class automatically, and the class controls the package. The +necessary options will be explained in this section. + +\begin{Declaration} + \Option{paper}=\PName{format} +\end{Declaration} +\BeginIndex{Option}{paper}% +This option defines the paper format. Theoretically, all paper formats +the \Package{typearea} package knows about are supported. But you have +to leave out the suffix \PValue{paper} when entering a value. So, for +letter format you would use the value \PValue{letter}. The formats of +the ISO A, B, C, and D series must be entered with small letters, e.,g. +\PValue{a4} for ISO A4. See also \autoref{sec:typearea.paperTypes}. + +\begin{Explain} +Although every paper size supported by \Package{typearea} can be used, +several formats may result in unexpected results on the first page of +a letter by now. That is not a matter of the class concept, but there +exist only parameter sets for ISO A4 at this time. Unfortunately, there +are no general rules to define the placement of the address field and +similar for an arbitrary paper size. But it is possible to define +additional parameter sets. See \autoref{sec:lcoFile} for more +information. + +\end{Explain} +% +\EndIndex{Option}{paper}% + +\begin{Declaration} + \Option{BCOR}=\PName{length}\\ + \Option{DIV}=\PName{value}\\ + \Option{headlines}=\PName{count} +\end{Declaration} +\BeginIndex{Option}{BCOR}% +\BeginIndex{Option}{DIV}% +\BeginIndex{Option}{headlines}% +The options for the divisor, the binding correction\Index{binding correction}, +and the number of headlines will be translated directly into the corresponding +options of the \Package{typearea} package. If the options are set using +\Macro{KOMAoptions} and not as class options, the \Macro{typearea} command +from the \Package{typearea} package will be used instead. See +\autoref{sec:typearea.options}, \autopageref{desc:typearea.macro.typearea}. +% +\EndIndex{Option}{BCOR}% +\EndIndex{Option}{DIV}% +\EndIndex{Option}{headlines}% + +\begin{Declaration} + \Option{enlargefirstpage} +\end{Declaration} +\BeginIndex{Option}{enlargefirstpage}% +As described later in this chapter, the first page of a letter always +uses a different page layout. The \Class{scrlttr2} class provides a +mechanism to calculate height and vertical alignment of head and foot +of the first page independently of the following pages. If, as a +result, the foot of the first page would reach into the text area, +this text area would automatically be made smaller using the +\Macro{enlargethispage}\IndexCmd{enlargethispage} macro. On the other +hand, if the text area should become larger, supposed the foot on the +first page allows that, you could use this option. At best, some more +text would fit on the first page. See also the description of pseudo +length \PLength{firstfootvpos} at \autoref{sec:scrlttr2.firstFoot}, +\autopageref{desc:scrlttr2.plength.firstfootvpos}. +This option can take the standard values for simple switches, as +listed in \autoref{tab:scrlttr2.simpleSwitchValues}, +\autopageref{tab:scrlttr2.simpleSwitchValues}. Default is +\PValue{false}. +% +\EndIndex{Option}{enlargefirstpage}% + +\begin{table} + \centering + \begin{tabular}{ll} + Value & Description \\\hline\\[-1.75ex] + \PValue{true} & activates the option \\ + \PValue{on} & activates the option \\ + \PValue{false}& deactivates the option \\ + \PValue{off} & deactivates the option \\ + \end{tabular} + \caption{Standard values for simple switches in \Class{scrlttr2}} + \label{tab:scrlttr2.simpleSwitchValues} +\end{table} + +\subsection{Other Layout Options} +\label{sec:scrlttr2.layout} + +In this subsection, you will find all options that have influence on +the layout in general, except page layout. Strictly speaking, all page +layout options (see~\ref{sec:scrlttr2.typeareaOptions}) are also layout +options, and vice versa for some of them. + +\begin{Declaration} + \Option{twoside} +\end{Declaration}% +\BeginIndex{Option}{oneside}% +From the author's point of view, double-sided letters do not make much +sense. Therefore, the option \Option{twoside} only partially switches to +double-sided layout. You get the possibility to have different margins +on left and right pages, but it is not used. So this option really means +\emph{activate the possibilities of a double-sided document, but stay + with the one-sided layout as far and as long as possible.} +This option can take the standard values for simple switches, as listed +in \autoref{tab:scrlttr2.simpleSwitchValues}, +\autopageref{tab:scrlttr2.simpleSwitchValues}. Default is +\PValue{false}. +% +\EndIndex{Option}{twoside}% + +By the way, double-sided letters are not supported, because they seem +unreasonable. + +\begin{Declaration} + \Option{cleardoublepage}=\PName{style} +\end{Declaration} +\BeginIndex{Option}{cleardoublepage}% +If you want pages inserted by the \Macro{cleardoublepage} command to +just contain a page number in head and foot or to be empty, this can be +accomplished with this option. There are three different styles +supported that are listed at \autoref{tab:scrlttr2.cleardoublepage}. Default +is \PValue{standard}. + +\begin{table} + \caption[{Possible values of option \Option{cleardoublepage} with + \Class{scrlttr2}}]{Possible values of option \Option{cleardoublepage} for + selection of page style of empty left pages with \Class{scrlttr2}} + \label{tab:scrlttr2.cleardoublepage} + \begin{desctabular} + \pventry{empty}{switches to page style\Index{page style} + \PValue{empty}\IndexPagestyle{empty} for inserted pages}% + \pventry{plain}{switches to page style + \PValue{plain}\IndexPagestyle{plain} for inserted pages} + \pventry{standard}{keeps the current page style for inserted pages} + \end{desctabular} +\end{table} +% +\EndIndex{Option}{cleardoublepage}% + +\begin{Declaration} + \Option{headsepline}\\ + \Option{footsepline} +\end{Declaration} +\BeginIndex{Option}{headsepline}% +\BeginIndex{Option}{footsepline}% +These two options insert a separator line below the head or above the +foot, resp., on consecutive pages. In the lingo of this manual, all +pages of a letter except the first one are consecutive pages. +This option can take the standard values for simple switches, as listed +in \autoref{tab:scrlttr2.simpleSwitchValues}, +\autopageref{tab:scrlttr2.simpleSwitchValues}. Default is +\PValue{false}. If one of the options is used without value, like in the +declaration above, this evaluates as \PValue{true}, so the separator +line will be activated. When used as a \Macro{documentclass} option, the +\Package{typearea} package will be called with the option +\Option{headinclude} or \Option{footinclude}, resp.\ +(see~\ref{sec:typearea.options}). +% +\EndIndex{Option}{headsepline}% +\EndIndex{Option}{footsepline}% + +\begin{Declaration} + \Option{mpinclude}\\ + \Option{mpexclude} +\end{Declaration} +\BeginIndex{Option}{mpinclude}% +\BeginIndex{Option}{mpexclude}% +These two options of the \Package{typearea} package should not be used +with the \Class{scrlttr2} class, because the first page in particular +does not take this option into account. To anticipate any complaints, a +warning will be issued when this option is used. If you feel adventurous +you could try how these options, especially \Option{mpinclude}, interact +with other class options. +% +\EndIndex{Option}{mpinclude}% \EndIndex{Option}{mpexclude}% + +\begin{Declaration} + \Option{pagenumber}=\PName{position} +\end{Declaration} +\BeginIndex{Option}{pagenumber}% +This option defines if and where a page number will be placed on +consecutive pages. All pages without a letter-head are consecutive +pages. This option effects the page layouts\Index{page layout} +\PValue{headings} and \PValue{plain}. It also effects the default page +styles of the \Package{scrpage2} package, if set before loading the +package (see \autoref{cha:scrpage}). It can take values only +influencing horizontal, only vertical, or both positions. Possible value +are shown in \autoref{tab:scrlttr2.pagenumber}. Default is \PValue{botcenter}. + +\begin{table} + \caption[{Possible values of option \Option{pagenumber} with + \Class{scrlttr2}}]{Possible values of option \Option{pagenumber} for the + position of the page number at page styles \PValue{headings} and + \PValue{plain} with \Class{scrlttr2}} + \label{tab:scrlttr2.pagenumber} + \begin{desctabular} + \entry{\PValue{bot}, \PValue{foot}}{% + page number in foot, horizontal position not changed}% + \entry{\PValue{botcenter}, \PValue{botcentered}, \PValue{botmittle}, + \PValue{footcenter}, \PValue{footcentered}, \PValue{footmiddle}}{% + page number in foot, centered}% + \entry{\PValue{botleft}, \PValue{footleft}}{% + page number in foot, left justified}% + \entry{\PValue{botright}, \PValue{footright}}{% + page number in foot, right justified}% + \entry{\PValue{center}, \PValue{centered}, \PValue{middle}}{% + page number centered horizontally, vertical position not changed}% + \entry{\PValue{false}, \PValue{no}, \PValue{off}}{% + no page number}% + \entry{\PValue{head}, \PValue{top}}{% + page number in head, horizontal position not changed}% + \entry{\PValue{headcenter}, \PValue{headcentered}, \PValue{headmiddle}, + \PValue{topcenter}, \PValue{topcentered}, \PValue{topmiddle}}{% + page number in head, centered}% + \entry{\PValue{headleft}, \PValue{topleft}}{% + page number in head, left justified}% + \entry{\PValue{headright}, \PValue{topright}}{% + page number in head, right justified}% + \entry{\PValue{left}}{% + page number left, vertical position not changed}% + \entry{\PValue{right}}{% + page number right, vertical position not changed}% + \end{desctabular} +\end{table} +% +\EndIndex{Option}{pagenumber}% + +\begin{Declaration} + \Option{parskip}=\PName{value} +\end{Declaration}% +\BeginIndex{Option}{parskip}% +\begin{Explain}% +Especially in letters you often encounter paragraphs marked not with +indentation of the first line, but with a vertical skip between them. It +is a matter of tradition. Apparently it has been easier for a secretary +to operate the carriage return lever twice than setting an indentation +using a tab stop or the space bar. Correct justification is almost +impossible using a typewriter, so letters are traditionally typeset +unjustified. + +However, typographers like Jan Tschichold take the view that letters, +written using means of modern typesetting, should take advantage of +their possibilities like other documents do. Under these circumstances, +letters should also be typeset using paragraph indentation and +justification. The author of \Class{scrlttr2} shares this point of view, +but nevertheless refrains from imposing to many restrictions upon the +user. +\end{Explain} + +As as reaction to many serious requests, \Class{scrlttr2} offers the +possibility to mark paragraphs not only by indentation of the first +line, but alternatively by vertical skip. You can choose between full or +half a line of vertical space. When using paragraph spacing, it seems +often useful to keep the last line of a paragraph shorter, so that +paragraph recognition will be eased. All these features are controlled +by different values for the \Option{parskip} option shown at +\autoref{tab:scrlttr2.parskip}. Default is \PValue{false}. + +\begin{table} + \caption[{Possible values of option \Option{parskip} with + \Class{scrlttr2}}]{Possible values of option \Option{parskip} to select + the paragraph mark with \Class{scrlttr2}} + \label{tab:scrlttr2.parskip} + \begin{desctabular} + \entry{\PValue{false}, \PValue{off}}{% + paragraph indentation instead of vertical space; the last line of a + paragraph may be arbitrarily filled}% + \entry{\PValue{full}, \PValue{on}, \PValue{true}}{% + one line vertical space between paragraphs; there must be at least + 1\Unit{em} free space in the last line of a paragraph}% + \pventry{full*}{one line vertical space between paragraphs; there must be + at least a quarter of a line free space at the end of a paragraph}% + \pventry{full+}{one line vertical space between paragraphs; there must be + at least a third of a line free space at the end of a paragraph}% + \pventry{full-}{one line vertical space between paragraphs; the last line + of a paragraph may be arbitrarily filled}% + \pventry{half}{half a line vertical space between paragraphs; there must + be at least 1\Unit{em} free space in the last line of a paragraph}% + \pventry{half*}{half a line vertical space between paragraphs; there must + be at least a quarter of a line free space at the end of a paragraph}% + \pventry{half+}{half a line vertical space between paragraphs; there must + be at least a third of a line free space at the end of a paragraph}% + \pventry{half-}{one line vertical space between paragraphs}% + \end{desctabular} +\end{table} +% +\EndIndex{Option}{parskip}% + +\subsection{Font Options} +\label{sec:scrlttr2.fontOptions} + +Fonts options are any options with influence on the size of the base +font or of fonts for letter parts. In theory, options affecting the font +type would also count as font options. At present there is only one +option for font size in \Class{scrlttr2}. + +\begin{Declaration} + \Option{fontsize}=\PName{size} +\end{Declaration} +\BeginIndex{Option}{fontsize}% +In the main classes, you choose the font size\Index{font size} for the +document using the \Option{10pt}, \Option{12pt}, etc. options. In the +\Class{scrlttr2} class, the desired \PName{size} is set using the +\Option{fontsize} option. The functionality is the same. This option can +only be used with \Macro{documentclass}, not with \Macro{KOMAoptions}. +Default is \PValue{12pt}. +% +\EndIndex{Option}{fontsize}% + +\subsection{Options for Letter-Head and Address} +\label{sec:scrlttr2.headoptions} + +The \Class{scrlttr2} class offers lots of extensions for the design of +the letter-head. There are also options for address formatting, +extending the possibilities of the standard letter class, although these +features could already be found in the now obsolete \Class{scrlettr} +class. + +\begin{Declaration} + \Option{fromalign} +\end{Declaration} +\BeginIndex{Option}{fromalign}% +This option defines the placement of the from address in the letter-head +of the first page. At the same time, this option serves as a switch to +activate or deactivate the extended letter-head options. If these +extensions are deactivated, some other options will have no effect. This +will be noted with the respecting options. Possible values for +\Option{fromalign} are shown at \autoref{tab:scrlttr2.fromalign}. Default is +\PValue{left}. + +\begin{table} + \caption[{Possible values of option \Option{fromalign} with + \Class{scrlttr2}}]{Possible values of option \Option{fromalign} for + setting the position of the from address at the letter head with + \Class{scrlttr2}} + \label{tab:scrlttr2.fromalign} + \begin{desctabular} + \entry{\PValue{center}, \PValue{centered}, \PValue{middle}}{% + return address centered; an optional logo will be on top of the extended + return address; letter-head extensions will be activated}% + \entry{\PValue{false}, \PValue{no}, \PValue{off}}{% + standard design will be used for the return address; the letter-head + extensions are deactivated}% + \entry{\PValue{left}}{% + left justified return address; an optional logo will be right justified; + letter-head extensions will be activated}% + \entry{\PValue{right}}{% + right justified return address; an optional logo will be left justified; + letter-head extensions will be activated}% + \end{desctabular} +\end{table} +% +\EndIndex{Option}{fromalign}% + +\begin{Declaration} + \Option{fromrule} +\end{Declaration} +\BeginIndex{Option}{fromrule}% +This option is part of the letter-head extensions (see option +\Option{fromalign} above). It allows you to place a horizontal line within the +return address. The possible values are shown at +\autoref{tab:scrlttr2.fromrule}. Default is \PValue{false}. You can not +activate more than one line at a time. + +\begin{table} + \caption[{Possible values of option \Option{fromrule} with + \Class{scrlttr2}}]{Possible values of option \Option{fromrule} for the + position of the rule at the from address with + \Class{scrlttr2}} + \label{tab:scrlttr2.fromrule} + \begin{desctabular} + \entry{\PValue{afteraddress}, \PValue{below}, \PValue{on}, \PValue{true}, + \PValue{yes}}{% + rule below the return address}% + \entry{\PValue{aftername}}{% + rule right below the sender's name}% + \entry{\PValue{false}, \PValue{no}, \PValue{off}}{% + no rule}% + \end{desctabular} +\end{table} +% +\EndIndex{Option}{fromrule}% + +\begin{Declaration} + \Option{fromphone} +\end{Declaration} +\BeginIndex{Option}{fromphone}% +This option is part of the letter-head extensions (see option +\Option{fromalign} above). It defines whether the phone number will be part of +the return address. This option can take the standard values for simple +switches, as listed in \autoref{tab:scrlttr2.simpleSwitchValues}, +\autopageref{tab:scrlttr2.simpleSwitchValues}. Default is \PValue{false}. +% +\EndIndex{Option}{fromphone}% + +\begin{Declaration} + \Option{fromfax} +\end{Declaration} +\BeginIndex{Option}{fromfax}% +This option is part of the letter-head extensions (see option +\Option{fromalign} above). It defines whether the facsimile number will be +part of the return address. This option can take the standard values for +simple switches, as listed in \autoref{tab:scrlttr2.simpleSwitchValues}, +\autopageref{tab:scrlttr2.simpleSwitchValues}. Default is \PValue{false}. +% +\EndIndex{Option}{fromfax}% + +\begin{Declaration} + \Option{fromemail} +\end{Declaration} +\BeginIndex{Option}{fromemail}% +This option is part of the letter-head extensions (see option +\Option{fromalign} above). It defines whether the +email address will be part of the return address. This option can take +the standard values for simple switches, as listed in +\autoref{tab:scrlttr2.simpleSwitchValues}, +\autopageref{tab:scrlttr2.simpleSwitchValues}. Default is \PValue{false}. +% +\EndIndex{Option}{fromemail}% + +\begin{Declaration} + \Option{fromurl} +\end{Declaration} +\BeginIndex{Option}{fromurl}% +This option is part of the letter-head extensions (see option +\Option{fromalign} above). It defines whether the +URL will be part of the return address. This option can take +the standard values for simple switches, as listed in +\autoref{tab:scrlttr2.simpleSwitchValues}, +\autopageref{tab:scrlttr2.simpleSwitchValues}. Default is \PValue{false}. +% +\EndIndex{Option}{fromurl}% + +\begin{Declaration} + \Option{fromlogo} +\end{Declaration} +\BeginIndex{Option}{fromlogo}% +This option is part of the letter-head extensions (see option +\Option{fromalign} above). It defines whether the +logo will be part of the return address. This option can take +the standard values for simple switches, as listed in +\autoref{tab:scrlttr2.simpleSwitchValues}, +\autopageref{tab:scrlttr2.simpleSwitchValues}. Default is \PValue{false}. +% +\EndIndex{Option}{fromlogo}% + +\begin{Declaration} + \Option{addrfield} +\end{Declaration} +\BeginIndex{Option}{addrfield}% +This option defines whether an address field will be set. Default is to +use the address field. This option can take the standard values for +simple switches, as listed in +\autoref{tab:scrlttr2.simpleSwitchValues}, +\autopageref{tab:scrlttr2.simpleSwitchValues}. Default is \PValue{true}. +% +\EndIndex{Option}{addrfield}% + +\begin{Declaration} + \Option{backaddress} +\end{Declaration} +\BeginIndex{Option}{backaddress}% +This option defines whether a return address for window envelopes will +be set. Default is to use the return address. If the address field is +suppressed (see option \Option{addrfield}), there will be no return +address either. This option can take the standard values for simple +switches, as listed in \autoref{tab:scrlttr2.simpleSwitchValues}, +\autopageref{tab:scrlttr2.simpleSwitchValues}. +Default is \PValue{true}. +% +\EndIndex{Option}{backaddress}% + +\begin{Declaration} + \Option{subject} +\end{Declaration} +\BeginIndex{Option}{subject}% +This option serves two purposes: First, you can choose if your subject should +have a title, given by the \PName{subject} variable (see +\autoref{tab:scrlttr2.subjectTerm}, +\autopageref{tab:scrlttr2.subjectTerm}). Second, you can choose if the subject +should be set before or after the opening. Possible values for this option +are shown at \autoref{tab:scrlttr2.subject}. Defaults are +\PValue{beforeopening} and \PValue{untitled}. + +\begin{table} + \caption[{Possible values of option \Option{subject} with + \Class{scrlttr2}}]{Possible values of option \Option{subject} for the + position of the subject with + \Class{scrlttr2}} + \label{tab:scrlttr2.subject} + \begin{desctabular} + \pventry{afteropening}{set subject after opening}% + \pventry{beforeopening}{set subject before opening}% + \pventry{titled}{add title to subject}% + \pventry{untitled}{do not add title to subject}% + \end{desctabular} +\end{table} +% +\EndIndex{Option}{subject}% + +\begin{Declaration} + \Option{locfield} +\end{Declaration} +\BeginIndex{Option}{locfield}% +\Class{scrlttr2} places a field with additional sender attributes next +to the address field. This can be used for bank accounts or similar. +Depending on the \Option{fromalign} option, it will also be used for the +sender logo. The width of this field may be defined within an \File{lco} +file (see \autoref{sec:lcoFile}). If the width is set to 0 in that +file, then the \Option{locfield} option can toggle between two presets +for the field width. See the explanation on the \Variable{locwidth} +pseudo length in \autoref{sec:scrlttr2.locationField}, +\autopageref{desc:scrlttr2.plength.locwidth}. Possible +values for this option are shown at \autoref{tab:scrlttr2.locfield}. Default +is \PValue{narrow}. + +\begin{table} + \caption[{Possible values of option \Option{locfield} with + \Class{scrlttr2}}]{Possible values of option \Option{locfield} for setting + the width of the field with additional sender attributes with + \Class{scrlttr2}} + \label{tab:scrlttr2.locfield} + \begin{desctabular} + \pventry{narrow}{small sender supplement field}% + \pventry{wide}{large sender supplement field}% + \end{desctabular} +\end{table} +% +\EndIndex{Option}{locfield}% + +\begin{Declaration} + \Option{foldmarks} +\end{Declaration} +\BeginIndex{Option}{foldmarks}% +This option activates fold marks for two or three panel folding of the +letter. The exact placement of the fold marks for three panel letter fold +depends on user settings or the \File{lco} file, resp.\ (see +\autoref{sec:lcoFile}). The folding need not result in equal sized +parts. This option can take the standard values for simple switches, as +listed in \autoref{tab:scrlttr2.simpleSwitchValues}, +\autopageref{tab:scrlttr2.simpleSwitchValues}. Default is +\PValue{true}, which implies setting the fold marks. +% +\EndIndex{Option}{foldmarks}% + +\begin{Declaration} + \Option{numericaldate} +\end{Declaration} +\BeginIndex{Option}{numericaldate}% +This option toggles between the standard, language-dependent date +presentation and a short, numerical one. \KOMAScript{} does not +provide the standard presentation. It should be defined by packages +like \Package{german}\IndexPackage{german}, +\Package{babel}\IndexPackage{babel}, or +\Package{isodate}\IndexPackage{isodate}. The short, numerical +presentation will be produced by \Class{scrlttr2} itself. This option +can take the standard values for simple switches, as listed in +\autoref{tab:scrlttr2.simpleSwitchValues}, +\autopageref{tab:scrlttr2.simpleSwitchValues}. Default is +\PValue{false}, which results in standard date presentation. In the +now obsolete \Class{scrlettr} class, this was achieved using the +\Option{orgdate} option, but with opposite results. +% +\EndIndex{Option}{numericaldate}% + +\begin{Declaration} + \Option{refline} +\end{Declaration} +\BeginIndex{Option}{refline}% +With the \Class{scrlttr2} class, the head, foot, address, and +sender attributes may extend beyond the normal type area to the left +and to the right. This option defines if that also applies to the +reference line. Normally, the reference line contains at least the date, +but it can hold additional data. Possible values for this option are shown at +\autoref{tab:scrlttr2.refline}. Default is \PValue{narrow}. + +\begin{table} + \caption[{Possible value of option \Option{refline} with + \Class{scrlttr2}}]{Possible value of option \Option{refline} for setting + the width of the reference line with + \Class{scrlttr2}} + \label{tab:scrlttr2.refline} + \begin{desctabular} + \pventry{narrow}{reference line restricted to type area}% + \pventry{wide}{reference line corresponds to address and sender + attributes}% + \end{desctabular} +\end{table} +% +\EndIndex{Option}{refline}% + +\subsection{Format Options} +\label{sec:scrlttr2.formatingOptions} + +Format options are those, which influence form or format of the +output and do not belong to another section. You might also call them +the \emph{miscellaneous options}. + +\begin{Declaration} + \Option{draft} +\end{Declaration} +\BeginIndex{Option}{draft}% +This option toggles between the final\Index{final version} and the +draft\Index{draft version} version of a document. In particular, +enabling the \Option{draft} option activates little black boxes that +will be drawn at the end of overfull lines. For the unpracticed eye, +these boxes ease the identification of paragraphs that need manual +improvement. When the \Option{draft} option is disabled, there will be +no such boxes. This option can take the standard values for simple +switches, as listed in \autoref{tab:scrlttr2.simpleSwitchValues}, +\autopageref{tab:scrlttr2.simpleSwitchValues}. +Default is \PValue{false}, as usual. But I strongly recommend enabling +the \Option{draft} option when designing a letter, as for every other +document. +% +\EndIndex{Option}{draft}% + +\subsection{The Letter Class Option Files} +\label{sec:lcoFile} + +\BeginIndex{}{lco=\File{lco}}% +Normally, you would not redefine parameters like the distance between +the address field and the top edge of the paper every time you write a +letter. Instead, you would reuse a whole set of parameters for certain +occasions. It will be much the same for the letter-head and foot used on +the first page. Therefore, it is reasonable to save these settings in a +separate file. For this purpose, the \Class{scrlttr2} class offers the +\File{lco} files. The \File{lco} suffix is an abbreviation for +\emph{\emph{l}etter \emph{c}lass \emph{o}ption}. + +In an \File{lco} file you can use all commands available to the document +at the time the \File{lco} file is loaded. Additionally, it can contain +internal commands available to package writers. For \Class{scrlttr2}, +these are in particular the commands \Macro{@newplength}, \Macro{@setplength}, +\Macro{@addtoplength} and \Macro{addtolengthplength} (see +\autoref{sec:scrlttr2.pseudoLength}). + +There are already some \File{lco} files included in the \KOMAScript{} +distribution. The \File{DIN.lco}, \File{DINmtext.lco}, \File{SNleft.lco}, and +\File{SN.lco} files serve to adjust \KOMAScript{} to different layout +standards. They are well suited as templates for your own parameter sets. The +\File{KOMAold.lco} file, however, serves to improve compatibility with the old +letter class \Class{scrlettr}. Because it contains internal commands not open +to package writers, you should not use them as a template for your own +\File{lco} files. You can find a list of predefined \File{lco} files in +\autoref{tab:lcoFiles}, \autopageref{tab:lcoFiles}. + +\begin{Explain} +If you have defined a parameter set for a letter standard not yet +supported by \KOMAScript{}, you are explicitly invited to send this +parameter set to the \KOMAScript{} support address. Please do not forget +to include the permission for distribution under the \KOMAScript{} +license (see the \File{lppl.txt} file). If you know the necessary +metrics for an unsupported letter standard, but are not able to write a +corresponding \File{lco} file yourself, you can also contact the \KOMAScript{} +author. +\end{Explain} + +\begin{Declaration} + \Macro{LoadLetterOption}\Parameter{name} +\end{Declaration} +\BeginIndex{Cmd}{LoadLetterOption}% +Usually, the \File{lco} files will be loaded by the +\Macro{documentclass} command. You enter the name of the \File{lco} file +without suffix as an option. The \File{lco} file will be loaded right +after the class file. + +But it is also possible to load an \File{lco} file later, or even from +within another \File{lco} file. This can be done with the +\Macro{LoadLetterOption} command, which gets the \PName{name} of the +\File{lco} file without suffix as a parameter. +\begin{Example} +You write a document containing several letters. Most of them should +comply with the German DIN standard. So you start with: +\begin{lstlisting} + \documentclass{scrlttr2} +\end{lstlisting} +But one letter should use the \File{DINmtext} variant, with the address +field placed more to the top, which results in more text fitting on the +first page. The folding will be modified so that the address field still +matches the address window in a DIN~C6/5 envelope. +You can achieve this as follows: +\begin{lstlisting} + \begin{letter}{Markus Kohm\\ + Fichtenstra\ss e 63\\68535 Edingen-Neckarhausen} + \LoadLetterOption{DINmtext} + \opening{Hello,} +\end{lstlisting} +Since construction of the page does not start before the +\Macro{opening}, it is sufficient to load the \File{lco} file before the +\Macro{opening} command. In particular, this need not be done before +\Macro{begin}\PParameter{letter}. So the changes made by loading the +\File{lco} file are local to the corresponding letter. +\end{Example} + +\begin{Explain} +If an \File{lco} file is loaded via \Macro{documentclass}, it may +nevertheless take the name of an option, provided it is an option that +does not take an argument. However, it would be possible to give the +name \File{fromalign=left.lco} to an \File{lco} file. It will get +loaded every time the \Macro{documentclass} option \Option{fromalign} +is used with the value \PValue{left}. Admittedly, this is quite +academic. Of course you can use this feature only if your operating and +file system support this kind of file names. Otherwise you have to +choose another file name and add the corresponding option, if +needed. +\end{Explain} + +\begin{Example} + You do not want to enter your sender address every time, so you + create an \File{lco} file with the necessary data, like this: +\begin{lstlisting} + \ProvidesFile{mkohm.lco}[2002/02/25 letter class option] + \setkomavar{fromname}{Markus Kohm} + \setkomavar{fromaddress}{Fichtenstra\ss e 63\\ + 68535 Edingen-Neckarhausen} +\end{lstlisting} + Please note that the German sharp s, ``\ss'', was entered using the + \TeX{} macro \Macro{ss}, because right after \Macro{documentclass} + no packages for input encoding, for example + \Macro{usepackage}\PValue{[latin1]}\PParameter{inputenc} for Unix or + \Macro{usepackage}\PValue{[ansinew]}\PParameter{inputenc} for + Windows, and no language packages, like + \Macro{usepackage}\PParameter{ngerman}\IndexPackage{ngerman} for the + new German orthography, are loaded. + + But if you would always use the same input encoding, you could also + include it into your \File{lco} file. This would look like this: +\begin{lstlisting} + \ProvidesFile{mkohm.lco}[2002/02/25 letter class option] + \RequirePackage[latin1]{inputenc} + \setkomavar{fromname}{Markus Kohm} + \setkomavar{fromaddress}{Fichtenstraße 63\\ + 68535 Edingen-Neckarhausen} +\end{lstlisting} + There is one problem with this usage: you cannot load this + \File{lco} file later in your document. If you want to have letters + with different senders in one document, you should refrain from + loading packages in your \File{lco} file. + + Let us further assume that I always typeset letters using the preset + \File{KOMAold}. Then I could add the following line to my + \File{mkohm.lco} file: +\begin{lstlisting} + \LoadLetterOption{KOMAold} +\end{lstlisting} + + Anyway, now you can preset my sender address using +\begin{lstlisting} + \documentclass[mkohm]{scrlttr2} +\end{lstlisting} +\end{Example} + +In \autoref{tab:lcoFiles}, \autopageref{tab:lcoFiles} you find a list of all +predefined \File{lco} files. If you use a printer that has large unprintable +areas on the left or right side, you might have problems with the +\Option{SN}\IndexOption{SN} option. The Swiss standard SN~101\,130 defines the +address field to be placed 8\,mm from the right paper edge, so the headline +and the sender attributes will be set with the same small distance to the +paper edge. This also applies to the reference line when using the +\Option{refline}\PValue{=wide} option (see \autoref{sec:scrlttr2.headoptions}, +\autopageref{desc:scrlttr2.option.refline}). If you have this kind of problem, +create your own \File{lco} file that loads \Option{SN} first and then changes +\PLength{toaddrhpos}\IndexPLength{toaddrhpos} (see +\autoref{sec:scrlttr2.addressee}, +\autopageref{desc:scrlttr2.plength.toaddrvpos}) to a smaller value. Please +also reduce \PLength{toaddrwidth} accordingly. +% +\EndIndex{Cmd}{LoadLetterOption}% + +\begin{table} +\centering +\caption{The predefined \File{lco} files} +\begin{tabular}{lp{.7\textwidth}} + \toprule + \File{lco} file & Description and features \\ + \midrule + \Option{DIN}\IndexOption[indexmain]{DIN}% + & parameter set for letters on A4 size paper, + complying with German standard DIN~676; + suitable for window envelopes in the sizes C4, C5, C6, + and C6/5 (C6 long).\\ + \Option{DINmtext}\IndexOption[indexmain]{DINmtext}% + & parameter set for letters on A4 size paper, + complying with DIN~676, but using an alternate layout + with more text on the first page; + only suitable for window envelopes in the sizes C6 and + C6/5 (C6 long).\\ + \Option{KOMAold}\IndexOption[indexmain]{KOMAold}% + & parameter set for letters on A4 size paper using a + layout close to the now obsolete \Class{scrlettr} + letter class; suitable for window envelopes in the sizes + C4, C5, C6, and C6/5 (C6 long); + some additional commands to improve compatibility with + obsolete \Class{scrlettr} commands are defined; + \Class{scrlttr2} may behave slightly different when + used with this \File{lco} file than with the other + \File{lco} files.\\ + \Option{SN}\IndexOption[indexmain]{SN}% + & parameter set for Swiss letters with address field on + the right side, according to SN~010\,130; suitable for + Swiss window envelopes in the sizes C4, C5, C6, and + C6/5 (C6 long).\\ + \Option{SNleft}\IndexOption[indexmain]{SNleft}% + & parameter set for Swiss letters with address field on + the left side; + suitable for Swiss window envelopes with window on the + left side in the sizes C4, C5, C6, and C6/5 (C6 long). + \\ + \bottomrule +\end{tabular} +\label{tab:lcoFiles} +\end{table} + +\begin{Explain} +\begin{Declaration} + \Macro{LetterOptionNeedsPapersize}% + \Parameter{option name}\Parameter{paper size} +\end{Declaration} +\BeginIndex{Cmd}{LetterOptionNeedsPapersize} +As mentioned in \autoref{sec:scrlttr2.typeareaOptions}, there are +only parameter sets and \File{lco} files for A4 sized paper. But in +every \File{lco} file distributed with \KOMAScript{} you will find a +\Macro{LetterOptionNeedsPapersize} command so that you will be warned +when using another \PName{paper size}. The first argument is the name of +the \File{lco} file without the ``\File{.lco}'' suffix. Second argument +is the paper size the \File{lco} file is designed for. + +If several \File{lco} files are loaded, the +\Macro{LetterOptionNeedsPapersize} command can be contained in each of +them, but the \Macro{opening} +command will only check the last given \PName{paper size}. As shown in +the following example, an experienced user can thus easily write +\File{lco} files with parameter sets for other paper sizes. If you do +not plan to set up \File{lco} files yourself, you may just forget about +this option and skip the example. + +\begin{Example} +Supposed you use A5 sized paper in normal, i.\,e.\ upright or +portrait, orientation for your letters. We further assume that you want +to put them into standard C6 window envelopes. Then, the position of the +address field would be the same as for a DIN standard letter on A4 sized +paper. The main difference is that A5 paper needs only one fold. So you +want to disable the upper and lower fold marks. The easiest way to +achieve this is to place the marks outside the paper area. +\begin{lstlisting} + \ProvidesFile{paper=a5.lco}[2002/05/02 letter class option] + \LetterOptionNeedsPapersize{paper=a5}{a5} + \@setplength{tfoldmarkvpos}{\paperheight} + \@setplength{bfoldmarkvpos}{\paperheight} +\end{lstlisting} +Besides, the placement of the foot must be adjusted. It is left to the +reader to find an appropriate value. When using such an \File{lco} file, +you must only take care that other \File{lco} file options, like +\File{SN}, are declared before the paper size, i.\,e.\ before loading +``\File{paper=a5.lco}''. This seems too complicated? Only before you +used it the first time. Anyway, how often do you write letters not using +your standard format? +\end{Example} +% +\EndIndex{Cmd}{LetterOptionNeedsPapersize} +\end{Explain} + +By the way, the \File{DIN} \File{lco} file will always be loaded as the +first \File{lco} file. This ensures that all pseudo lengths will have +more or less reasonable default values. + +Please note that it is not possible to use \Macro{PassOptionsToPackage} +to pass options to packages from within an \File{lco} file that have +already been loaded by the class. Normally, this only applies to the +\Package{typearea}, \Package{scrlfile}, and \Package{keyval} packages. +% +\EndIndex{}{lco=\File{lco}}% + +\section{General Document Properties} +\label{sec:scrlttr2.general} + +Some document properties aren't assigned to a certain part of the +document such as the letter-head or the letter body. Several of +these properties have already been mentioned in +\autoref{sec:scrlttr2.options}. + + +\subsection{Font Selection} +\label{sec:scrlttr2.font} + +\BeginIndex{}{font style}\BeginIndex{}{font size}% +\begin{Explain} +Commands for defining, extending and querying the font of a specific +element can be found~\ref{sec:maincls.font}. These commands work exactly +the same in \Class{scrlttr2}. The elements which can be influenced in +this way are listed in \autoref{tab:scrlttr2.elementsWithoutText}. +% +\begin{table} + \centering% + \caption{Alphabetical list of the elements, whose font can be + changed in \Class{scrlttr2} using the commands \Macro{setkomafont} and + \Macro{addtokomafont}} + \begin{desctabular} + \feentry{backaddress}{% + return address for a window envelope}% + \feentry{descriptionlabel}{% + label, i.e. the optional argument of \Macro{item}, in a + \Environment{description} environment}% + \feentry{fromaddress}{% + sender's address in the letter-head}% + \feentry{fromname}{% + sender's address in the letter-head if different from + \FontElement{fromaddress}}% + \feentry{pagefoot}{% + in most cases the footer, sometimes the header of a page}% + \feentry{pagehead}{% + in most cases the header, sometimes the footer of page}% + \feentry{pagenumber}{% + page number in the footer or header which is inserted with + \Macro{pagemark}}% + \feentry{subject}{% + subject in the opening of the letter}% + \feentry{title}{% + headline in the opening of the letter}% + \end{desctabular} + \label{tab:scrlttr2.elementsWithoutText} +\end{table} +\end{Explain} +% +\EndIndex{}{font style}\EndIndex{}{font size}% + + +\subsection{Page Style} +\label{sec:scrlttr2.pageStyle} One of the general properties of a +document is the page style. Please refer also the +\autoref{sec:maincls.pageStyle} and \autoref{cha:scrpage}. + +\begin{Declaration} +\Macro{pagestyle}\PParameter{empty}\\ +\XMacro{pagestyle}\PParameter{plain}\\ +\XMacro{pagestyle}\PParameter{headings}\\ +\XMacro{pagestyle}\PParameter{myheadings}\\ +\XMacro{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}% +In letters written with \Class{scrlttr2} there are four different +page styles. +\begin{description} +\item[empty] is the page style, in which the header and footer of + subsequent pages (all pages apart from the first) are completely + empty. This page style is also used for the first page, because + header and footer of this page are set using the macro + \Macro{opening}. + +\item[plain] is the page style with only page numbers in the header or + footer on subsequent pages. The placement of these page numbers is + determined by the option \Option{pagenumber} (see + \autoref{sec:scrlttr2.layout}). + +\item[headings] is the page style for automatic page headings of + subsequent pages. The inserted marks are the sender's name from the + variable \Variable{fromname}\IndexVariable{fromname} and the subject + from the variable \Variable{subject}\IndexVariable{subject} (see + \autoref{sec:scrlttr2.firstHead} and + \autoref{sec;scrlttr2.titleSubject}). At which position these + marks and the page numbers are placed depends on the option + \Option{pagenumber} (see \autoref{sec:scrlttr2.layout}). Apart + from that, the author can change these marks after \Macro{opening} + manually. +\item[myheadings] is the page style for manual page headings of + subsequent pages. This is very similar to \PValue{headings}, but + here the marks are set by the author using the commands + \Macro{markboth}\IndexCmd{markboth} and + \Macro{markright}\Index{markright}. +\end{description} + +Page styles are also influenced by the option +\Option{headsepline}\IndexOption{headsepline} or +\Option{footsepline}\IndexOption{footsepline} (see +\autoref{sec:scrlttr2.layout}). The page style beginning with +the current page is switched with \Macro{pagestyle}. In contrast, +\Macro{thispagestyle} changes only the page style of the current +page. The letter class itself uses +\Macro{thispagestyle}\PParameter{empty} within +\Macro{opening}\IndexCmd{opening} for the first page of the +letter. +% +\EndIndex{Cmd}{pagestyle}% +\EndIndex{Cmd}{thispagestyle}% +\EndIndex{Pagestyle}{empty}% +\EndIndex{Pagestyle}{plain}% +\EndIndex{Pagestyle}{headings}% +\EndIndex{Pagestyle}{myheadings}% + +\BeginIndex[indexother]{}{font style}% +For changing the font style of headers or footers you should use the +user interface described in \autoref{sec:maincls.font}. For +header and footer the same element is used which you can name either +\FontElement{pagehead}\IndexFontElement{pagehead} or +\FontElement{pagefoot}\IndexFontElement{pagefoot}. The element for the +page number within the header or footer is named +\FontElement{pagenumber}\IndexFontElement{pagenumber}. Default +settings are listed in \autoref{tab:maincls.defaultFontsHeadFoot}, +\autopageref{tab:maincls.defaultFontsHeadFoot}. +Please have also a look at the example in +\autoref{sec:maincls.pageStyle}, +\autopageref{sec:maincls.pageStyle.example}. +% +\EndIndex[indexother]{}{font style}% + +\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}% +Please refer to \autoref{sec:maincls.pageStyle}, +\autopageref{desc:maincls.macro.clearpage}. The function +of \Macro{cleardoublepage} in \Class{scrlttr2} depends on the +option \Option{cleardoublepage} which is described in more detail +in \autoref{sec:scrlttr2.layout}, +\autopageref{desc:scrlttr2.option.cleardoublepage}. +% +\EndIndex{Cmd}{clearpage}% +\EndIndex{Cmd}{cleardoublepage}% +\EndIndex{Cmd}{cleardoublestandardpage}% +\EndIndex{Cmd}{cleardoubleplainpage}% +\EndIndex{Cmd}{cleardoubleemptypage}% + + + +\subsection{Variables} +\label{sec:scrlttr2.variables} + +\BeginIndex{}{Variables}% +Apart from options, commands, environments, counters and lengths +additional elements have already been introduced in \KOMAScript{}. +A typical property of an element is the font style and the option +to change it (see \autoref{sec:maincls.font}). At this point +we now are going to introduce variables. Variables have a name by +which they are called and they have a content. The content of a +variable can be set independently from time and location of the +actual usage. The main difference between a command and a variable +is that a command usually triggers an action whereas a variable +only consist of plain text. Furthermore a variable can have an +additional description, which can be set and issued. + +This section only gives a short introduction to the term variable. +The following examples have no special meaning. More detailed +examples can be found in the explanation of predefined variables +of the letter class in the following sections. An overview of all +variables is given in \autoref{tab:scrlttr2.variables}. + +\begin{desctable} + \caption{Alphabetical list of all supported variables in + \Class{scrlttr2}\label{tab:scrlttr2.variables}}\\ + \Endfirsthead + \caption[]{Alphabetical list of all supported variables in + \Class{scrlttr2} (\emph{pursuit})}\\ + \Endhead% + \standardfoot% + \ventry{backaddress}{return address for window envelopes + (\autoref{sec:scrlttr2.addressee}, + \autopageref{desc:scrlttr2.variable.backaddress})}% + \ventry{backaddressseparator}{separator within the return address + (\autoref{sec:scrlttr2.addressee}, + \autopageref{desc:scrlttr2.variable.backaddressseparator})}% + \ventry{ccseparator}{separator between title of additional addressees and + additional addressees + (\autoref{sec:scrlttr2.afterClosing}, + \autopageref{desc:scrlttr2.variable.ccseparator})}% + \ventry{customer}{customer number + (\autoref{sec:scrlttr2.refLine}, + \autopageref{desc:scrlttr2.variable.customer})}% + \ventry{date}{date + (\autoref{sec:scrlttr2.refLine}, + \autopageref{desc:scrlttr2.variable.date})}% + \ventry{emailseparator}{separator between e-mail name and e-mail address + (\autoref{sec:scrlttr2.firstHead}, + \autopageref{desc:scrlttr2.variable.emailseparator})}% + \ventry{enclseparator}{separator between title of enclosure and enclosures + (\autoref{sec:scrlttr2.afterClosing}, + \autopageref{desc:scrlttr2.variable.enclseparator})}% + \ventry{faxseparator}{separator between title of fax and fax number + (\autoref{sec:scrlttr2.firstHead}, + \autopageref{desc:scrlttr2.variable.faxseparator})}% + \ventry{fromaddress}{sender's address without its name + (\autoref{sec:scrlttr2.firstHead}, + \autopageref{desc:scrlttr2.variable.fromaddress})}% + \ventry{frombank}{sender's bank account + (\autoref{sec:scrlttr2.other}, + \autopageref{desc:scrlttr2.variable.frombank})}% + \ventry{fromemail}{sender's e-mail + (\autoref{sec:scrlttr2.firstHead}, + \autopageref{desc:scrlttr2.variable.fromemail})}% + \ventry{fromfax}{sender's fax number + (\autoref{sec:scrlttr2.firstHead}, + \autopageref{desc:scrlttr2.variable.fromfax})}% + \ventry{fromlogo}{commands for inserting the sender's logo + (\autoref{sec:scrlttr2.firstHead}, + \autopageref{desc:scrlttr2.variable.fromlogo})}% + \ventry{fromname}{complete name of the sender + (\autoref{sec:scrlttr2.firstHead}, + \autopageref{desc:scrlttr2.variable.fromname})}% + \ventry{fromphone}{sender's telephone number + (\autoref{sec:scrlttr2.firstHead}, + \autopageref{desc:scrlttr2.variable.fromphone})}% + \ventry{fromurl}{one url of the sender + (\autoref{sec:scrlttr2.firstHead}, + \autopageref{desc:scrlttr2.variable.fromurl})}% + \ventry{invoice}{invoice number + (\autoref{sec:scrlttr2.refLine}, + \autopageref{desc:scrlttr2.variable.invoice})}% + \ventry{location}{more details of the sender + (\autoref{sec:scrlttr2.locationField}, + \autopageref{desc:scrlttr2.variable.location})}% + \ventry{myref}{ sender's reference + (\autoref{sec:scrlttr2.refLine}, + \autopageref{desc:scrlttr2.variable.myref})}% + \ventry{place}{place + (\autoref{sec:scrlttr2.refLine}, + \autopageref{desc:scrlttr2.variable.place})}% + \ventry{placeseparator}{separator between place and date + (\autoref{sec:scrlttr2.refLine}, + \autopageref{desc:scrlttr2.variable.placeseparator})}% + \ventry{phoneseparator}{separator between title of telephone and telephone + number + (\autoref{sec:scrlttr2.firstHead}, + \autopageref{desc:scrlttr2.variable.phoneseparator})}% + \ventry{signature}{signature beneath the ending of the letter + (\autoref{sec:scrlttr2.closing}, + \autopageref{desc:scrlttr2.variable.signature})}% + \ventry{specialmail}{special mail + (\autoref{sec:scrlttr2.addressee}, + \autopageref{desc:scrlttr2.variable.specialmail})}% + \ventry{subject}{subject + (\autoref{sec:scrlttr2.titleSubject}, + \autopageref{desc:scrlttr2.variable.subject})}% + \ventry{subjectseparator}{separator between title of subject and subject + (\autoref{sec:scrlttr2.titleSubject}, + \autopageref{desc:scrlttr2.variable.subjectseparator})}% + \ventry{title}{letter title + (\autoref{sec:scrlttr2.titleSubject}, + \autopageref{desc:scrlttr2.variable.title})}% + \ventry{toname}{complete name of addressee + (\autoref{sec:scrlttr2.addressee}, + \autopageref{desc:scrlttr2.variable.toname})}% + \ventry{toaddress}{address of addressee without its name + (\autoref{sec:scrlttr2.addressee}, + \autopageref{desc:scrlttr2.variable.toaddress})}% + \ventry{yourmail}{date of addressee's mail + (\autoref{sec:scrlttr2.refLine}, + \autopageref{desc:scrlttr2.variable.yourmail})}% + \ventry{yourref}{addressee's reference + (\autoref{sec:scrlttr2.refLine}, + \autopageref{desc:scrlttr2.variable.yourref})}% +\end{desctable} + +\begin{Declaration} + \Macro{newkomavar}\OParameter{description}\Parameter{name}\\ + \Macro{newkomavar*}\OParameter{description}\Parameter{name}\\ + \Macro{addtoreffields}\Parameter{name} +\end{Declaration} +\BeginIndex{Cmd}{newkomavar}\BeginIndex{Cmd}{newkomavar*}% +\BeginIndex{Cmd}{addtoreffields}% +With \Macro{newkomavar} a new variable is defined. This variable +is addressed via \PName{name}. As an option you can define a +\PName{description} for the variable \PName{name}. Using the +command \Macro{addtoreffields} you can add the variable +\PName{name} to the reference fields (see +\autoref{sec:scrlttr2.refLine}). The \PName{description} and +the content of the variable are added at the end of the reference +fields. The starred version \Macro{newkomavar*} is similar to the +one without star with a subsequent call of the command +\Macro{addtoreffields}. Thus, the starred version automatically +adds the variable to the reference fields. +\begin{Example} + Suppose you need an additional field for a direct dialling. You + can define this field either with +\begin{lstlisting} + \newkomavar[Direct dialling]{myphone} + \addtoreffields{myphone} +\end{lstlisting} + or more concise with +\begin{lstlisting} + \newkomavar*[direct dialling]{myphone} +\end{lstlisting} + +\end{Example} +When you define a variable for the reference fields you should +always give them a description. +% +\EndIndex{Cmd}{newkomavar}\EndIndex{Cmd}{newkomavar*}% +\EndIndex{Cmd}{addtoreffields}% + + +\begin{Declaration} + \Macro{setkomavar}% + \Parameter{name}\OParameter{description}\Parameter{content}\\ + \Macro{setkomavar*}\Parameter{name}\Parameter{description} +\end{Declaration} +\BeginIndex{Cmd}{setkomavar}\BeginIndex{Cmd}{setkomavar*}% +With the command \Macro{setkomavar} you determine the +\PName{content} of the variable \PName{name}. Using an optional +argument you can at the same time change the \PName{description} +of the variable. In contrast, \Macro{setkomavar*} can only set the +\PName{description} of the variable \PName{name}. +\begin{Example} + Suppose you have defined a direct dialling as mentioned above + and you now want to set the content. You write: +\begin{lstlisting} + \setkomavar{myphone}{-\,11} +\end{lstlisting} + In addition, you want to replace the term ``direct dialling'' + with ``Connexion''. Thus you add the description +\begin{lstlisting} + \setkomavar*{myphone}{Connexion} +\end{lstlisting} + or you can put both in one command: +\begin{lstlisting} + \setkomavar{myphone}[Connexion]{-\,11} +\end{lstlisting} +\end{Example} +By the way: You may delete the content of a variable using an empty +\PName{content} argument. You can also delete the description using an +empty \PName{description} argument. +\begin{Example} + Suppose you have defined a direct dialling as mentioned above and + you now don't want a description to be set. You write: +\begin{lstlisting} + \setkomavar*{myphone}{} +\end{lstlisting} + You can combine this with the definition of the content: +\begin{lstlisting} + \setkomavar{myphone}[]{-\,11} +\end{lstlisting} + So you may setup the content and delete the description using only + one command. +\end{Example} +% +\EndIndex{Cmd}{setkomavar}\EndIndex{Cmd}{setkomavar*}% + + +\begin{Declaration} + \Macro{usekomavar}\OParameter{command}\Parameter{name}\\ + \Macro{usekomavar*}\OParameter{command}\Parameter{name} +\end{Declaration} +\BeginIndex{Cmd}{usekomavar}\BeginIndex{Cmd}{usekomavar*}% +In\ChangedAt{v2.9i}{\Class{scrlttr2}} some cases it is necessary that +the user can access the content or the description of a variable. This +is specially important when you have defined a variable which is not +added to the reference fields. Using the command \Macro{usekomavar} you +have access to the content of the variable \PName{name} whereas the +starred version \Macro{usekomavar*} gives you the description. + +\begin{Explain} + The commands \Macro{usekomavar} and \Macro{usekomavar*} are, similar + to all commands where a starred version or an optional argument + exists, not fully expandable. Nevertheless if used within + \Macro{markboth}\IndexCmd{markboth}, + \Macro{markright}\IndexCmd{markright} or similar commands you + needn't insert a \Macro{protect}\IndexCmd{protect} before using + them. Of course this is also true in \Package{scrpage2} for + \Macro{markleft}\IndexCmd{markleft}. But they couldn't be used at + commands like \Macro{MakeUppercase}\IndexCmd{MakeUppercase}. + \Macro{MakeUppercase}\PParameter{\Macro{usekomavar}\Parameter{name}} + would result in \Macro{usekomavar}\Parameter{NAME}. To avoid this + problem you may use commands like \Macro{MakeUppercase} as optional + argument of \Macro{usekomavar} or \Macro{usekomavar*}. So you'll get + the upper case content of a variable using + \Macro{usekomavar}\PValue{[\Macro{MakeUppercase}]}\Parameter{name}. +\end{Explain} +% +\EndIndex{Cmd}{usekomavar}\EndIndex{Cmd}{usekomavar*}% +% +\EndIndex{}{variables} + +\begin{Declaration} + \Macro{ifkomavarempty}\Parameter{name}\Parameter{true}\Parameter{false}\\ + \Macro{ifkomavarempty*}\Parameter{name}\Parameter{true}\Parameter{false} +\end{Declaration} +\BeginIndex{Cmd}{ifkomavarempty}% +With\ChangedAt{v2.9i}{\Class{scrlttr2}} these commands you may check +whether or not the expanded contents or description of a variable is +empty. The \PName{true} argument will be executed if the contents or +description is empty. Otherwise the \PName{false} argument will be +executed. The variant with star sign handles the description of a +variable, the variant without star the contents. + +\begin{Explain} + Maybe it is important to know, that the contents or description of + the variable will be expanded using \Macro{edef}. If this results in + spaces or unexpandable macros like \Macro{relax}, it is not + empty. This is even true, if the use of the variable would not + result in any output. + + Both variants of the command must not be used at the argument of + \Macro{MakeUppercase}\IndexCmd{MakeUppercase} or commands, which + have similar effects to their arguments. See the description of + \Macro{usekomavar} above for more information about using commands + like \Macro{usekomavar} or \Macro{ifkomavarempty} at the argument of + \Macro{MakeUppercase}. But they are robust enough to be used at the + argument of e.g. \Macro{markboth} or \Macro{footnote}. +\end{Explain} + + +\subsection{The Pseudo Lengths} +\label{sec:scrlttr2.pseudoLength} + +\begin{Explain} + \TeX{} works with a fixed number of registers. There are registers + for tokens, for boxes, for counters, for skips and for dimensions. + Overall there are 256 for each of them. For \LaTeX{} lengths, which + are addressed with \Macro{newlength} skip registers are used. If all + of these registers are in use you can not define additional lengths. + The letter class \Class{scrlttr2} only for the first page would use + up more than 20 of such registers. \LaTeX{} itself already uses 40 + of these registers. The \Package{typearea} package needs some of + them too. Thus approximately a quarter of the precious registers is + already in use. That's the reason why lengths specific to letters in + \Class{scrlttr2} are defined with macros instead of lengths. The + drawback of this is that computations withs macros is somewhat more + complicated than with real lengths. +\end{Explain} + +A list of all pseudo length at \Class{scrlttr2} is shown at +\autoref{tab:scrlttr2.pseudoLength} from +\autopageref{tab:scrlttr2.pseudoLength}. The meaning is shown at +\autoref{fig:scrlttr2.pseudoLength}. + +\begin{figure} + \centering + \includegraphics{plenDIN} + \caption{Schematic of letter paper's pseudo lengths} + \label{fig:scrlttr2.pseudoLength} +\end{figure} + +\begin{desctable} + \caption{Pseudo lengths provided by class \Class{scrlttr2}% + \label{tab:scrlttr2.pseudoLength}}\\ + \Endfirsthead % + \caption[]{Pseudo lengths provided by class \Class{scrlttr2} + (\emph{pursuit})}\\% + \Endhead% + \standardfoot% + \pentry{foldmarkhpos}{% + horizontal distance of all foldmarks from left paper edge + (\autoref{sec:scrlttr2.other}, + \autopageref{desc:scrlttr2.plength.foldmarkhpos})}% + \pentry{tfoldmarkvpos}{% + vertical distance of upper foldmark from top paper edge + (\autoref{sec:scrlttr2.other}, + \autopageref{desc:scrlttr2.plength.tfoldmarkvpos})}% + \pentry{bfoldmarkvpos}{% + vertical distance of lower foldmark from top paper edge + (\autoref{sec:scrlttr2.other}, + \autopageref{desc:scrlttr2.plength.bfoldmarkvpos})}% + \pentry{firstheadvpos}{% + vertical distance of letter-head from top paper edge + (\autoref{sec:scrlttr2.firstHead}, + \autopageref{desc:scrlttr2.plength.firstheadvpos})}% + \pentry{firstheadwidth}{% + width of letter-head; letter-head is centered horizontally + on letter paper (\autoref{sec:scrlttr2.firstHead}, + \autopageref{desc:scrlttr2.plength.firstheadwidth})}% + \pentry{fromrulewidth}{% + length of an optional horizontal rule in letter-head + (\autoref{sec:scrlttr2.firstHead}, + \autopageref{desc:scrlttr2.plength.fromrulewidth})}% + \pentry{toaddrvpos}{% + vertical distance of address field from top paper edge + (\autoref{sec:scrlttr2.addressee}, + \autopageref{desc:scrlttr2.plength.toaddrvpos})}% + \pentry{toaddrhpos}{% + horizontal distance of address field from left paper edge + -- for positive values -- or negative horizontal distance of address + field from right paper edge -- for negative values -- + (\autoref{sec:scrlttr2.addressee}, + \autopageref{desc:scrlttr2.plength.toaddrhpos})}% + \pentry{toaddrindent}{% + left and right indentation of address within address field + (\autoref{sec:scrlttr2.addressee}, + \autopageref{desc:scrlttr2.plength.toaddrindent})}% + \pentry{toaddrwidth}{% + width of address field (\autoref{sec:scrlttr2.addressee}, + \autopageref{desc:scrlttr2.plength.toaddrwidth})}% + \pentry{toaddrheight}{% + height of address field (\autoref{sec:scrlttr2.addressee}, + \autopageref{desc:scrlttr2.plength.toaddrheight})}% + \pentry{backaddrheight}{% + height of return address field on top of address field + (\autoref{sec:scrlttr2.addressee}, + \autopageref{desc:scrlttr2.plength.backaddrheight})}% + \pentry{specialmailindent}{% + left indentation of special mail within address field + (\autoref{sec:scrlttr2.addressee}, + \autopageref{desc:scrlttr2.plength.specialmailindent})}% + \pentry{specialmailrightindent}{% + right indentation of special mail within address field + (\autoref{sec:scrlttr2.addressee}, + \autopageref{desc:scrlttr2.plength.specialmailrightindent})}% + \pentry{locwidth}{% + width of supplemental data field; for zero value width is + calculated automatically with respect to option \Option{locfield} + that is described in \autoref{sec:scrlttr2.headoptions} + (\autoref{sec:scrlttr2.locationField}, + \autopageref{desc:scrlttr2.plength.locwidth})}% + \pentry{refvpos}{% + vertical distance of business line from top paper edge + (\autoref{sec:scrlttr2.refLine}, + \autopageref{desc:scrlttr2.plength.refvpos})}% + \pentry{refwidth}{% + width of business line + (\autoref{sec:scrlttr2.refLine}, + \autopageref{desc:scrlttr2.plength.refwidth})}% + \pentry{refhpos}{% + horizontal distance of business line from left paper edge; for zero + value business line is centered horizontally on letter paper + (\autoref{sec:scrlttr2.refLine}, + \autopageref{desc:scrlttr2.plength.refhpos})}% + \pentry{refaftervskip}{% + vertical skip below business line + (\autoref{sec:scrlttr2.refLine}, + \autopageref{desc:scrlttr2.plength.refaftervskip})}% + \pentry{sigbeforevskip}{% + vertical skip between closing and signature + (\autoref{sec:scrlttr2.closing}, + \autopageref{desc:scrlttr2.plength.sigbeforevskip})}% + \pentry{sigindent}{% + indentation of signature with respect to text body + (\autoref{sec:scrlttr2.closing}, + \autopageref{desc:scrlttr2.plength.sigindent})}% + \pentry{firstfootvpos}{% + vertical distance of letter foot from top paper edge + (\autoref{sec:scrlttr2.firstFoot}, + \autopageref{desc:scrlttr2.plength.firstfootvpos})}% + \pentry{firstfootwidth}{% + width of letter foot; letter foot is centered horizontally + on letter paper + (\autoref{sec:scrlttr2.firstFoot}, + \autopageref{desc:scrlttr2.plength.firstfootwidth})}% +\end{desctable} + + +\begin{Declaration} + \Macro{@newplength}\Parameter{name} +\end{Declaration} +\BeginIndex{Cmd}{@newplength}% +This command defines an new pseudo length. This new pseudo length +can clearly identified with its \PName{name}. It is made sure that +every \PName{name} can only be given once. + +Since the user in general doesn't define its own pseudo lengths it +is not intended as a user command. Thus, it can not be used within +a document, but for example within a \File{lco} file. +% +\EndIndex{Cmd}{@newplength}% + +\begin{Declaration} + \Macro{useplength}\Parameter{name} +\end{Declaration} +\BeginIndex{Cmd}{useplength}% +Using this command you can access the value of the pseudo length +with the given \PName{name}. This is the only user command in +connection with pseudo lengths. Of course this command can also be +used with a \File{lco} file. +% +\EndIndex{Cmd}{useplength}% + +\begin{Declaration} + \Macro{setlengthtoplength}% + \OParameter{factor}\Parameter{length}\Parameter{pseudo length}\\ + \Macro{addtolengthplength}% + \OParameter{factor}\Parameter{length}\Parameter{pseudo length} +\end{Declaration} +\BeginIndex{Cmd}{setlengthtoplength}% +\BeginIndex{Cmd}{addtolengthplength}% +\begin{Explain}% +While you can combine a length with a factor this is not possible +with pseudo lengths. Suppose you have a length \Macro{test} with +the value 2\Unit{pt}, then \texttt{3\Macro{test}} gives you the +value 6\Unit{pt}. Using pseudo lengths instead +\texttt{3\Macro{useplength}\PParameter{test}} would give you +32\Unit{pt}. This is especially annoying if you want a real +\PName{length} assign the value of a \PName{pseudo length}. +\end{Explain} +Using the command \Macro{setlengthtoplength} you can assign a +multiple of a \PName{pseudo length} to a real \PName{length}. +Instead of putting the \PName{factor} in front of the +\PName{pseudo length} it is given as an optional argument. You +should also use this command when you want to assign a negative +value of a \PName{pseudo length} to a \PName{length}. In this case +you can either use a minus sign or \PValue{-1} as the +\PName{factor}. The command \Macro{addtolengthplength} works very +similar to that. It adds a multiple of \PName{pseudo length} to +\PName{length}. +% +\EndIndex{Cmd}{setlengthtoplength}% +\EndIndex{Cmd}{addtolengthplength}% + +\begin{Declaration} + \Macro{@setplength}% + \OParameter{factor}\Parameter{pseudo length}\Parameter{value}\\ + \Macro{@addtoplength}% + \OParameter{factor}\Parameter{pseudo length}\Parameter{value} +\end{Declaration} +\BeginIndex{Cmd}{@setplength}% +\BeginIndex{Cmd}{@addtoplength}% +Using the command \Macro{@setplength} you assign a multiple of a +\PName{value} to a \PName{pseudo length}. The \PName{factor} is +given as an optional argument. +The command \Macro{@addtoplength} +adds the \PName{value} to a \PName{pseudo length}. For assigning +or adding the multiple of \PName{pseudo length} to another pseudo +length the command \Macro{useplength} is used within \PName{value}. +To subtract the value of a \PName{pseudo length} from another +\PName{pseudo length} a minus sign or \PValue{-1} as +\PName{factor} is used. + +Since the user in general doesn't define its own pseudo lengths it +is not intended as a user command. Thus, it can not be used within +a document, but for example within a \File{lco} file. +% +\EndIndex{Cmd}{@setplength}% +\EndIndex{Cmd}{@addtoplength}% + + + +\subsection{The General Structure of a Letter Document} +\label{sec:scrlttr2.document} + +The general structure of a letter document differs somewhat from +the structure of a normal document. Whereas a book document in +general contains only one book, a letter document can contain +several letters. As illustrated in +\autoref{fig:scrlttr2.document} a letter document consists of a +preamble, the individual letters and the closing. + +The preamble comprises all settings that in general concern all +letters. Most of them can be overwritten in the settings of the +individual letters. The only setting which can not be changed within a +single letter is the font size (see option \Option{fontsize} in +\autoref{sec:scrlttr2.fontOptions}, +\autopageref{desc:scrlttr2.option.fontsize})). General settings such as the +loading of packages and the setting of options should be placed before +\Macro{begin}\PParameter{document} only. All settings that comprise +the setting of variables or other text features should be done after +\Macro{begin}\PParameter{document}. This is particularly recommend +when the \Package{babel} package\IndexPackage{babel} (see +\cite{package:babel}) is used or language dependent variables of +\Class{scrlttr2} are to be changed. + +The closing usually consists only of the standard closing for the +end of a document. Of course you can also insert additional +comments at this point. + +\begin{figure} +\centering\small\setlength{\fboxsep}{1.5ex} +\fbox{\parbox{.667\linewidth}{\raggedright% + \Macro{documentclass}\OParameter{\dots}\PParameter{scrlttr2}\\ + \dots\\ + {\centering\emph{Settings for all letters}\\} + \dots\\ + \Macro{begin}\PParameter{document}\\ + \dots\\ + {\centering\emph{Settings for all letters}\\} + \dots\\ + }}\\ +\fbox{\parbox{.667\linewidth}{\raggedright% + \Macro{begin}\PParameter{letter}\Parameter{addressee}\\ + \dots\\ + {\centering\emph{Content of the individual letter}\\} + \dots\\ + \Macro{end}\PParameter{letter}\\ + }}\\ +\parbox{.667\linewidth}{\raggedright\vspace{-.5ex}\vdots\vspace{1ex}}\\ +\fbox{\parbox{.667\linewidth}{\raggedright% + \Macro{end}\PParameter{document}\\ + }}\\ +\caption{General structure of a letter document with several +individual letters (the structure of a single letter is shown in + \autoref{fig:scrlttr2.letter})} +\label{fig:scrlttr2.document} +\vspace{2\abovecaptionskip} +\fbox{\parbox{.667\linewidth}{\raggedright% + \Macro{begin}\PParameter{letter}% + \OParameter{options}\Parameter{addressee}\\ + \dots\\ + {\centering\emph{Settings for this letter}\\} + \dots\\ + \Macro{opening}\Parameter{opening}\\ + }}\\ +\fbox{\parbox{.667\linewidth}{\raggedright% + \dots\\ + {\centering\emph{letter text}\\} + \dots\\ + }}\\ +\fbox{\parbox{.667\linewidth}{\raggedright% + \Macro{closing}\Parameter{closing}\\ + \Macro{ps}\\ + \dots\\ + {\centering\emph{postscript}\\} + \dots\\ + \Macro{encl}\Parameter{enclosures}\\ + \Macro{cc}\Parameter{additional addressees}\\ + \Macro{end}\PParameter{letter}\\ + }}\\ +\caption{General structure of a single letter within a letter +document (see also \autoref{fig:scrlttr2.document})} +\label{fig:scrlttr2.letter} +\end{figure} + +As shown in \autoref{fig:scrlttr2.letter} every single letter +itself consists of an introduction, the letter body and the +closing. In the introduction all settings for only this letter are +defined. It is important that this introduction always ends with +\Macro{opening}. Similarly the closing starts with +\Macro{closing}. If needed both arguments \PName{opening} and +\PName{closing} can be left empty. Nevertheless both commands have +to be used and must have an argument. + +\begin{Explain} +There are further settings that can be changed between the +individual letters. These settings have an effect on all +subsequent letters. For reasons of maintainability of your letter +documents it is not recommended to use further general settings +with limited validity between the letters. +\end{Explain} + +As already mentioned you can use all settings in the preamble of a +letter document in the preamble of the individual letters apart +from the font size. Therefore you will not find more detailed +explanations for the possible settings at this point. Please refer +to \autoref{sec:scrlttr2.startLetter}. + + +\section{The Letter Declaration} +\label{sec:scrlttr2.startLetter} + +The letter declaration gives all settings for the letter itself as well +as for the first page of the body. The first page consists of more than just the +prelims of the letter; it consists of several different parts. + +\subsection{The Letter-Head} +\label{sec:scrlttr2.firstHead} + +The term letter-head here refers to all of the sender's data and is printed +above the addressee's address. It usually is expected to have all this set via +the page style setting. The earlier version of letter class \Class{scrlettr} +worked that way. But with \Class{scrlttr2}, the letter-head has gotten +independent of the page style setting and is run by the command +\Macro{opening}. +% Fuellmaterial +\iftrue +The position of the letter-head is absolute and independent of the type +area. In fact the first page of a letter, that page that holds the letter-head, +is set by \PValue{empty}. +\fi +% Ende des Fuellmaterials + +\begin{Declaration} + \PLength{firstheadvpos} +\end{Declaration} +\BeginIndex{PLength}{firstheadvpos}% +The pseudo length \PLength{firstheadvpos} gives the distance between the top of +the sheet and the letter-head. This value is set differently in the predefined +\File{lco}-files. A typical value is 8\Unit{mm}. +% +\EndIndex{PLength}{firstheadvpos} + +\begin{Declaration} + \PLength{firstheadwidth} +\end{Declaration} +\BeginIndex{PLength}{firstheadwidth}% +The pseudo length \PLength{firstheadwidth} gives the width of the +letter-head. This value is set differently in the predefined +\File{lco}-files. While this value usually depends on the paper width and the +distance between the left side of the sheet and the address' field, it was +the type area width in \Option{KOMAold}. +% +\EndIndex{PLength}{firstheadwidth}% + +\begin{Declaration} + \Variable{fromname}\\ + \Variable{fromaddress}\\ + \Variable{fromphone}\\ + \Variable{fromfax}\\ + \Variable{fromemail}\\ + \Variable{fromurl}\\ + \Variable{fromlogo} +\end{Declaration} +\BeginIndex{Variable}{fromname}% +\BeginIndex{Variable}{fromaddress}% +\BeginIndex{Variable}{fromphone}% +\BeginIndex{Variable}{fromfax}% +\BeginIndex{Variable}{fromemail}% +\BeginIndex{Variable}{fromurl}% +\BeginIndex{Variable}{fromlogo}% +% +These variables give all statements concerning the sender necessary to create +the letter-head. Which variable will be used to build the letter-head in the +end can be chosen by use of the letter-head extensions (see option +\Option{fromalign} in \autoref{sec:scrlttr2.headoptions}, +\autopageref{desc:scrlttr2.option.fromalign}) and the options +given there. The variables \Variable{fromname}, and \Variable{fromaddress}, +and \Variable{fromlogo} will be set in the letter-head without their label; +the variables \Variable{fromphone}, \Variable{fromfax}, \Variable{fromemail} +and \Variable{fromurl} will be set with it's label. The labels are taken from +\autoref{tab:scrlttr2.fromTerm}, +\autopageref{tab:scrlttr2.fromTerm}. +% +\begin{table} + \centering + \caption{The sender's predefined labels for the letter head} + \begin{desctabular}[1.8em] + \ventry{fromemail}{\Macro{usekomavar*}\PParameter{emailseparator}% + \Macro{usekomavar}\PParameter{emailseparator}}% + \ventry{fromfax}{\Macro{usekomavar*}\PParameter{faxseparator} + \Macro{usekomavar}\PParameter{faxseparator}}% + \ventry{fromname}{\Macro{headfromname}} + \ventry{fromphone}{\Macro{usekomavar*}\PParameter{phoneseparator}% + \Macro{usekomavar}\PParameter{phoneseparator}}% + \ventry{fromurl}{\Macro{usekomavar*}\PParameter{urlseparator}% + \Macro{usekomavar}\PParameter{urlseparator}}% + \end{desctabular} +\label{tab:scrlttr2.fromTerm} +\end{table} + +An important hint concerns the sender's address. Within the sender's address, +parts such as Street, P.O.~Box, State, Country etc, are separated with a +double backslash. Depending on how the sender's address is used this double +backslash will be interpreted differently and therefore not strictly as a line +break. Paragraphs, vertical distances and the like usually aren't allowed within +the sender's address declaration. One has to have very good knowledge of +\Class{scrlttr2} to use things like those mentioned above, intelligently. + +It's possible, by the way, to load an external picture to use it as a logo. In +this case then put the content of \Variable{fromlogo} to a +\Macro{includegraphics}-command. The corresponding package (see +\cite{package:graphics}) of course has to be given with the letter declaration +(see \autoref{sec:scrlttr2.document}). +% +\EndIndex{Variable}{fromname}% +\EndIndex{Variable}{fromaddress}% +\EndIndex{Variable}{fromphone}% +\EndIndex{Variable}{fromfax}% +\EndIndex{Variable}{fromemail}% +\EndIndex{Variable}{fromurl}% +\EndIndex{Variable}{fromlogo}% + +\begin{Declaration} + \PLength{fromrulewidth} +\end{Declaration} +\BeginIndex{PLength}{fromrulewidth}% +Depending on class options \Option{fromrule} and \Option{fromalign} a +horizontal rule is drawn in the letter-head (see +\autoref{sec:scrlttr2.headoptions}, +\autopageref{desc:scrlttr2.option.fromrule}). If pseudo length +\PLength{fromrulewidth} has a value of 0\Unit{pt}, which is the default, rule +length is calculated automatically taking into account, e.\,g., letter-head +width or an optional logo. Users can adjust rule length manually by setting +this pseudo length to positive values using \Macro{\@setplength} (see +\autoref{sec:scrlttr2.pseudoLength}, +\autopageref{desc:scrlttr2.macro.@setplength}) in a \File{lco}-file on his +own. +% +\EndIndex{PLength}{fromrulewidth}% + +\begin{Declaration} + \Variable{phoneseparator}\\ + \Variable{faxseparator}\\ + \Variable{emailseparator}\\ + \Variable{urlseparator} +\end{Declaration} +\BeginIndex{Variable}{phoneseparator}% +\BeginIndex{Variable}{faxseparator}% +\BeginIndex{Variable}{emailseparator}% +\BeginIndex{Variable}{urlseparator}% +With these variables, hyphens are defined. If applicable they are used with the +sender's data in the letter-head (see \autoref{tab:scrlttr2.fromTerm}). As +a feature, they are labeled and used in the sender's details +of the letter-head. To look up the predefined labels +and their contents, see \autoref{tab:scrlttr2.fromSeparator}. +% +% table moved in following paragraph (JUM) >>> +% +\EndIndex{Variable}{phoneseparator}% +\EndIndex{Variable}{faxseparator}% +\EndIndex{Variable}{emailseparator}% +\EndIndex{Variable}{urlseparator}% + + +\begin{Declaration} + \Macro{firsthead}\Parameter{construction} +\end{Declaration} +\BeginIndex{Cmd}{firsthead}% +Mostly \Class{scrlttr2} and its variables offer enough possibilities to create +a letter-head. In very rare situations one may wish to have more freedom to +create. In those situations one will have to do without predefined +letter-heads, which could have been chosen via options. Instead one is to +create freely. Therefore one has to define the preferred \PName{construction} +with the command \Macro{firsthead}. Within \Macro{firsthead} and with the help +of the \Macro{parbox}-command (see \cite{latex:usrguide}) one can set several +boxes side by side or one underneath the other. An advanced user will thus be +able to create a letter-head on his own. And doing this of course the +\PName{construct} may use variables with the help of \Macro{usekomavar}. +% +% <<< table of previous paragraph +\begin{table} + \centering + \caption{predefined labels and contents of hyphens for sender's data in the + letter-head} + \begin{tabular}{lll} + \toprule + name & label & content \\ + \midrule + \Variable{emailseparator} & \Macro{emailname} & \texttt{:\~} \\ + \Variable{faxseparator} & \Macro{faxname} & \texttt{:\~} \\ + \Variable{phoneseparator} & \Macro{phonename} & \texttt{:\~} \\ + \Variable{urlseparator} & \Macro{wwwname} & \texttt{:\~} \\ + \bottomrule + \end{tabular} + \label{tab:scrlttr2.fromSeparator} +\end{table} +% +\EndIndex{Cmd}{firsthead}% + + +\subsection{The Footer} +\label{sec:scrlttr2.firstFoot} +As the first page holds a letter-head of its own it holds a footer of its own +too. And, same as with the letter-head, it will be printed independent of the +page style settings but with the use of \Macro{opening}. + +\begin{Declaration} + \PLength{firstfootvpos} +\end{Declaration} +\BeginIndex{PLength}{firstfootvpos}% +% +This pseudo length gives the distance between the footer and the upper +border of the sheet. This value is set different in the predefined +\File{lco}-files. Also it takes care of preventing text jutting into the +footer area. If needed, it can help to shorten the text height on the first page +using \Macro{enlargethispage}. +Likewise and if it is needed the textheight can +be extended with help of the option \Option{enlargefirstpage}. This way, the +distance between text area and the first page's footer can be reduced to +the value \Length{footskip}. See also \autoref{sec:scrlttr2.typeareaOptions}, +\autopageref{desc:scrlttr2.option.enlargefirstpage}. +% +\EndIndex{PLength}{firstfootvpos}% + + +\begin{Declaration} + \PLength{firstfootwidth} +\end{Declaration} +\BeginIndex{PLength}{firstfootwidth}% +This pseudo length gives the width of the letter's first page footer. The +value is set in dependency of the pseudo length \PLength{firstheadwidth} in the +\File{lco} files. +% +\EndIndex{PLength}{firstfootwidth}% + + +\begin{Declaration} + \Macro{firstfoot}\Parameter{construction} +\end{Declaration} +\BeginIndex{Cmd}{firstfoot}% +The first page's footer is preset to empty. But with the +\Macro{firstfoot} command it is possible to give definitions the same +way as with defining the letter-head with \Macro{firsthead}. +\begin{Example} + As the first page's footer, you may want to set the content of the variable + \Variable{bank} (the bank account). The double backslash shall be exchanged + with a comma at the same time: +\begin{lstlisting} + \firstfoot{% + \parbox[b]{\linewidth}{% + \centering\def\\{, }\usekomavar{frombank}% + }% + } +\end{lstlisting} + For the hyphen you might define a variable of your own if you like. Consider + that has been left to the reader as an exercise. + + Nowadays it has become very common to create a proper footer to have + some balance to the letter-head. This can be done like this: +\begin{lstlisting} + \firstfoot{% + \parbox[t]{\textwidth}{\footnotesize + \begin{tabular}[t]{l@{}}% + \multicolumn{1}{@{}l@{}}{partners:}\\ + Jim Smith\\ + Russ Mayer + \end{tabular}% + \hfill + \begin{tabular}[t]{l@{}}% + \multicolumn{1}{@{}l@{}}{Manager:}\\ + Jane Fonda\\[1ex] + \multicolumn{1}{@{}l@{}}{Court Of Jurisdiction:}\\ + Great Plains + \end{tabular}% + \ifkomavarempty{frombank}{}{% + \hfill + \begin{tabular}[t]{l@{}}% + \multicolumn{1}{@{}l@{}}{\usekomavar*{frombank}:}\\ + \usekomavar{frombank} + \end{tabular}% + }% + }% + } +\end{lstlisting} + This example, by the way, came from Torsten Kr\"uger. With +\begin{lstlisting} + \setkomavar{frombank}{Account No. 12\,345\,678\\ + at Citibank\\ + bank code no: 876\,543\,21} +\end{lstlisting} + the bank account can be set accordingly. If the footer will have a + height like that it might happen that you have to shift its position. You + do this with the pseudo length + \PLength{firstfootvpos}\IndexPLength{firstfootvpos}, which is described + above in this section. +\end{Example} +% +\EndIndex{Cmd}{firstfoot}% + + +\subsection{The Address} +\label{sec:scrlttr2.addressee} +The term address here refers to addressee's name and address which are +output in an address field. Additional information can be output within +this address field such as dispatch type or a return address. The latter +being especially useful when using window envelopes. The address is +centered vertically within the remaining part of the address field below +dispatch type information. + +\begin{Declaration} + \PLength{toaddrvpos}\\ + \PLength{toaddrhpos} +\end{Declaration} +\BeginIndex{PLength}{toaddrvpos}% +\BeginIndex{PLength}{toaddrhpos}% +These pseudo lengths define vertical and horizontal position of the +address field. Values should be set in \File{lco} files according to +standard envelopes window's measures. Care must be taken to avoid +letter-head and address field to overlap. Whether address field is +output or not can be controlled by class option \Option{addrfield} +(see \autoref{sec:scrlttr2.headoptions}). +% +\EndIndex{PLength}{toaddrhpos}% +\EndIndex{PLength}{toaddrvpos}% + + +\begin{Declaration} + \PLength{toaddrwidth} +\end{Declaration} +\BeginIndex{PLength}{toaddrwidth}% +Pseudo length \PLength{toaddrwidth} defines the width of the address +field. It should be set in an \File{lco} file according to standard +envelopes window's measures. Typical values are 70\Unit{mm} to +100\Unit{mm}. +% +\EndIndex{PLength}{toaddrwidth}% + + +\begin{Declaration} + \PLength{toaddrindent} +\end{Declaration} +\BeginIndex{PLength}{toaddrindent}% +Additional indentation of addressee within address field can be +controlled by pseudo length \PLength{toaddrindent}. Its value applies +to both left and right margin. Default value is 0\Unit{pt}. +% +\EndIndex{PLength}{toaddrindent}% + + +\begin{Declaration} + \Variable{backaddress}\\ + \Variable{backaddressseparator}\\ + \PLength{backaddrheight} +\end{Declaration} +\BeginIndex{Variable}{backaddress}\BeginIndex{Variable}{backaddressseparator}% +\BeginIndex{PLength}{backaddrheight}% +When using window envelopes sender's address is often included within +the window. This information, called return address, is placed at the +top of the window above addressee and dispatch type information, +separated by a horizontal rule and set at a smaller font size. Variable +\Variable{backaddress} is usually built automatically from variables +\Variable{fromname} and \Variable{fromaddress}. During output double +backslashes within return address are replaced by content of variable +\Variable{backaddressseparator}, whose default value is a +comma followed by a white space. Return address field's height is +defined by pseudo length \PLength{backaddrheight}, which should be set +in a proper \File{lco} file. DIN and SN values are 5\Unit{mm}. Document +class options \Option{addrfield} and \Option{backaddress} control +whether return address is output or not (see +\autoref{sec:scrlttr2.headoptions}). +% +\EndIndex{PLength}{backaddrheight}% +\EndIndex{Variable}{backaddress}\EndIndex{Variable}{backaddressseparator}% + + +\begin{Declaration} + \Variable{specialmail}\\ + \PLength{specialmailindent}\\ + \PLength{specialmailrightindent} +\end{Declaration} +\BeginIndex{Variable}{specialmail}% +\BeginIndex{PLength}{specialmailindent}% +\BeginIndex{PLength}{specialmailrightindent}% +An optional dispatch type can be output within address field above +the addressee by setting variable \Variable{specialmail}. Left and +right alignment are determined by pseudo lengths +\PLength{specialmailindent} and \PLength{specialmailrightindent}. +In the \File{lco} files provided by \KOMAScript{} +\PLength{specialmailindent} is set to rubber length \Macro{fill}, +while \PLength{specialmailrightindent} is set to 1\Unit{em}. Thus +dispatch type is printed 1\Unit{em} off address field's right margin. +% +\EndIndex{PLength}{specialmailindent}% +\EndIndex{PLength}{specialmailrightindent}% +\EndIndex{Variable}{specialmail}% + + +\begin{Declaration} + \Variable{toname}\\ + \Variable{toaddress} +\end{Declaration} +\BeginIndex{Variable}{toname}% +\BeginIndex{Variable}{toaddress}% +These two variables contain addressee's name and address as output in +the address field. Usually you won't access these variables manually, +but their values are taken from the argument to the +\Environment{letter}-environment\IndexEnv{letter}. Hints on +address formatting given in \autoref{sec:scrlttr2.firstHead} apply +here as well. +% +\EndIndex{Variable}{toname}% +\EndIndex{Variable}{toaddress}% + + +\begin{Declaration} + \Environment{letter}\OParameter{options}\Parameter{addressee} +\end{Declaration} +\BeginIndex{Env}{letter}% +As in standard letter class \Environment{letter} environment is the +key environment of \Class{scrlttr2}. A special \Class{scrlttr2} feature +are optional arguments to the \Environment{letter} environment. These +\PName{options} are executed via \Macro{KOMAoptions} command. +Mandatory \Environment{letter} environment argument is +\PName{addressee}. Addressee's parts have to be separated by double +backslashes. These parts are output on individual lines in the address +field. First part of \PName{addressee} is stored in variable +\Variable{toname}, while the rest is stored in variable +\Variable{toaddress} for further use. Vertical material such as +paragraphs or vertical space is not permitted within \PName{addressee}. The \Environment{letter} environment doesn't actually start +letter output. This is done by the \Macro{opening} command. +\EndIndex{Env}{letter}% + + +\begin{Declaration} + \Macro{AtBeginLetter}\Parameter{commands} +\end{Declaration} +\BeginIndex{Cmd}{AtBeginLetter}% +\LaTeX{} enables the user to declare \PName{commands} whose execution +is delayed until a determined point. Such points are called +\emph{hooks}. Known macros for using hooks are \Macro{AtBeginDocument} +and \Macro{AtEndOfClass}. Letter class \Class{scrlttr2} provides an +additional hook that can be used via macro \Macro{AtBeginLetter}. +Originally, hooks were provided for package and class authors, as they +are documented in \cite{latex:clsguide} only. But in letters there are +useful applications of \Macro{AtBeginLetter} as the following example +may illustrate: +% +\begin{Example} + Given one has to set multiple letters with questionnaires within one + document. Questions are numbered automatically within single letters + using a counter. Since, in contrast to page numbering, that counter is + not known by \Class{scrlttr2}, it wouldn't be reset at each start of a + new letter. Given each questionnaire contains ten questions, question~1 + would get number~11 in the second letter. Solution is to reset this + counter at the beginning of each new letter: +\begin{lstlisting} + \newcounter{Question} + \newcommand{\Question}[1]{% + \refstepcounter{Question}\par + \@hangfrom{\makebox[2em][r]{\theQuestion:~}}{#1}} + \AtBeginLetter{\setcounter{Question}{0}} +\end{lstlisting} + This way question~1 remains question~1, even in the 1001st letter. Of course + definitions like those mentioned above need to be stated either between + macros \Macro{makeatletter} and \Macro{makeatother} (see \cite{DANTE:FAQ}) + in letter declarations (see \autoref{sec:scrlttr2.document} and + \autoref{fig:scrlttr2.document}, \autopageref{fig:scrlttr2.document}), + in a unique package, or in an \File{lco}-file + (see \autoref{sec:lcoFile}). +\end{Example} +% +\EndIndex{Cmd}{AtBeginLetter}% + + +\subsection{The Sender's Extensions} +\label{sec:scrlttr2.locationField} + +Often, especially with business letters, the space for letter-head or page foot +seems to be too tight to put all you want to have set. To give more details +about the sender, often the space right beside the addressee's field is +used. In this manual this field is called \emph{sender's extension} + + +\begin{Declaration} + \PLength{locwidth} +\end{Declaration} +\BeginIndex{PLength}{locwidth}% +This pseudo length \PLength{locwidth} declares the width of the sender's +extensions. Its value is set typically 0\Unit{pt} in the predefined +\File{lco} files. This value takes on a special position. It does not mean +that the sender's extension has no width. Instead it's actual width is set +with the \Macro{opening} when paper width, address window width, and distance +between left border of the sheet and address window is given. With it the +option \Option{locfield} (see \autoref{sec:scrlttr2.headoptions}, +\autopageref{desc:scrlttr2.option.locfield}) is +taken into account. +% +\EndIndex{PLength}{locwidth} + + +\begin{Declaration} + \Variable{location} +\end{Declaration} +\BeginIndex{Variable}{location}% +The content of the sender's extension is determined by the variable +\Variable{location}. To set this variable's content it's allowed to use +formatting commands like \Macro{raggedright}. One has to consider that +depending on the use of the options \Option{fromalign} and \Option{fromlogo}, +a part of the space for the sender's extension may be in use already (see +\autoref{sec:scrlttr2.headoptions}, +\autopageref{desc:scrlttr2.option.fromalign} and +\autopageref{desc:scrlttr2.option.fromlogo}). +% +\begin{Example} + Given you like to put the names of your partners, manager, or court of + jurisdiction with the sender's extension, you can do this like: +\begin{lstlisting} + \KOMAoptions{locfield=wide} + \setkomavar{location}{\raggedright + \textbf{Partners:}\\ + \quad Hugo Mayer\\ + \quad Bernd Miller\\[1ex] + \textbf{Manager:}\\ + \quad Liselotte Mayer\\[1ex] + \textbf{Court of jurisdiction:}\\ + \quad Washington, DC + } +\end{lstlisting} + The option \Option{locfield=wide} is set to make the details fit in + horizontally. Sender details like those mentioned in the above example, + can be given together with the common sender address with your own + \File{lco}-file. +\end{Example} +% +\EndIndex{Variable}{location}% + + +\subsection{The Business Line} +\label{sec:scrlttr2.refLine} + +Especially with business letters, a line can be found that gives initials, dial +code, customer number, invoice number, or a reference to a previous letter. +In this manual this line is called \emph{business line}. The business line can +consist of more than just one line and is set only if one of those variables +mentioned above is given. Only those fields will be set that are given. To set +a seemingly empty field, one needs to give as value at least a white space or +\Macro{null}. If you want to have your letter without a business line, then +just the variable \Variable{date} will be set instead. + + +\begin{Declaration} + \PLength{refvpos} +\end{Declaration} +\BeginIndex{PLength}{refvpos}% +This pseudo length gives the distance between the upper border of the sheet +and the business line. It's value is set differently in the predefined +\File{lco} files. Typical values are between 80{,}5\Unit{mm} and +98{,}5\Unit{mm}. +% +\EndIndex{PLength}{refvpos}% + + +\begin{Declaration} + \PLength{refwidth} +\end{Declaration} +\BeginIndex{PLength}{refwidth}% +This pseudo length gives the width that is available for the business line. +The value is set typically to 0\Unit{pt} in the predefined \File{lco}-files. +This value has a special meaning. In no way does it determine that there is +no available width for the business line. Instead this value means that the +width will be calculated with the \Macro{opening}. Thus the calculated width +depends on the determination of the options \Option{refline} (see +\autoref{sec:scrlttr2.headoptions}, +\autopageref{desc:scrlttr2.option.refline}). +% +\EndIndex{PLength}{refwidth}% + + +\begin{Declaration} + \PLength{refaftervskip} +\end{Declaration} +\BeginIndex{PLength}{refaftervskip}% +This pseudo length gives the vertical space that has to be inserted beneath +the business line. The value is set in the predefined \File{lco} files. It +effects directly the textheight of the first page. A typical value is +something between one and two lines. +% +\EndIndex{PLength}{refaftervskip}% + + +\begin{Declaration} + \Variable{place}\\ + \Variable{placeseparator} +\end{Declaration} +\BeginIndex{Variable}{place}% +\BeginIndex{Variable}{placeseparator}% +As said before in the introduction of this paragraph, the business line can be +left out. This happens if all variables of the business line are empty with +the exception of the variable for the date. In this case, the content of +\Variable{place} and \Variable{placeseparator} will be set, followed by the +content of \Variable{date}. The predefined content of the +\Variable{placeseparator} is a comma followed by a white space. If this +variable \Variable{place} has no value then the hyphen remains unset also. +The predefined subject of \Variable{date} is \Macro{today} and depends on the +setting of the option \Option{numericaldate} (see +\autoref{sec:scrlttr2.headoptions}). +% +\EndIndex{Variable}{place}% +\EndIndex{Variable}{placeseparator}% + + +\begin{Declaration} + \Variable{yourref}\\ + \Variable{yourmail}\\ + \Variable{myref}\\ + \Variable{customer}\\ + \Variable{invoice} \\ + \Variable{date} +\end{Declaration} +\BeginIndex{Variable}{yourref}% +\BeginIndex{Variable}{yourmail}% +\BeginIndex{Variable}{myref}% +\BeginIndex{Variable}{customer}% +\BeginIndex{Variable}{invoice}% +\BeginIndex{Variable}{date}% +These variables are typical for business line fields. To find out about their +meaning, see table~\ref{tab:scrlttr2.variables} on +\autopageref{tab:scrlttr2.variables}. Each variable covers a predefined label +that can be seen at \autoref{tab:scrlttr2.reflineTerm}. The field width that +belongs to each variable, adjusts itself automatically to its label and +content. +% +\begin{table} + \centering + \caption{predefined labels of the business line's typical variables. The + content of the macros depend on language.} + \begin{tabular}{lll} + \toprule + name & label & in english \\ + \midrule + \Variable{yourref} & \Macro{yourrefname} & Your reference \\ + \Variable{yourmail} & \Macro{yourmailname} & Your letter from \\ + \Variable{myref} & \Macro{myrefname} & Our reference \\ + \Variable{customer} & \Macro{customername} & Customer No.: \\ + \Variable{invoice} & \Macro{invoicename} & Invoice No.: \\ + \Variable{date} & \Macro{datename} & date \\ + \bottomrule + \end{tabular} + \label{tab:scrlttr2.reflineTerm} +\end{table} +% +\EndIndex{Variable}{yourref}% +\EndIndex{Variable}{yourmail}% +\EndIndex{Variable}{myref}% +\EndIndex{Variable}{customer}% +\EndIndex{Variable}{invoice}% +\EndIndex{Variable}{date}% + + + +\subsection{The Title and the Subject Line} +\label{sec;scrlttr2.titleSubject} +Business letters most often carry a subject line. The subject line indicates +in short of what that letter is about. Usually the subject should be short and +precise and not run across several lines. The letter may also carry a title. +Titles find usage with unregular letters like an Invoice or a Reminder. + + +\begin{Declaration} + \Variable{title} +\end{Declaration} +\BeginIndex{Variable}{title}% +With \Class{scrlttr2} a letter can carry an additional title. The title +becomes centered and set with letter size \Macro{LARGE} right +after and beneath the business line. +The predefined font setup for this element +(\Macro{normalcolor}\Macro{sffamily}\Macro{bfseries}) can be changed with +help of the interface described in \autoref{sec:maincls.font}. Font size +declarations are allowed. +\begin{Example} + Given you are to write a reminder. Thus you put the title: +\begin{lstlisting} + \setkomavar{title}{Reminder} +\end{lstlisting} + This way the addressee will recognize a reminder as such. +\end{Example} +% +\EndIndex{Variable}{title} + + +\begin{Declaration} + \Variable{subject}\\ + \Variable{subjectseparator} +\end{Declaration} +\BeginIndex{Variable}{subject}% +\BeginIndex{Variable}{subjectseparator}% +In case a subject should be set then you have to determine the variable +\Variable{subject} fit. Depending on what the option \Option{subject} is set +to a label can be put in front of the subject issue; also the vertical +position of the subject issue can be changed (see +\autoref{sec:scrlttr2.headoptions}, +\autopageref{desc:scrlttr2.option.subject}). To see the predetermined labels +look at \autoref{tab:scrlttr2.subjectTerm}. The predefined value of +\Variable{subjectseparator} is a colon followed by a white space. +% +\begin{table} + \centering + \caption{Predefined Labels Of The Subject's Variables.} + \begin{tabular}{lll} + \toprule + name & label \\ + \midrule + \Variable{subject} & \Macro{usekomavar*}\PParameter{subjectseparator}% + \texttt{\%} \\ + & \texttt{\quad}% + \Macro{usekomavar}\PParameter{subjectseparator} \\ + \Variable{subjectseparator} & \Macro{subjectname} \\ + \bottomrule + \end{tabular} + \label{tab:scrlttr2.subjectTerm} +\end{table} + +The subject line is set in a separate type face. To change this use +the user interface described in \autoref{sec:maincls.font}. For +the element \FontElement{subject}\IndexFontElement{subject} the +predetermined type face in \Class{scrlttr2} is +\Macro{normalfont}\Macro{normalcolor}\Macro{bfseries}. +\begin{Example} + Given you are a board member and want to write a letter to another member of + that board about a few internals of the organization. You want to + clarify with your subject line what this letter is all about, but without + labeling it thus. You can do this that way: +\begin{lstlisting} + \setkomavar{subject}[Subject ]{% + organization's internals} +\end{lstlisting} + or easier: +\begin{lstlisting} + \setkomavar{subject}[]{% + about organization's internals} +\end{lstlisting} + More than just that you may want to have set the subject line not only bold but + also with sans serif types: +\begin{lstlisting} + \addtokomafont{subject}{\sffamily} +\end{lstlisting} + As you can see, it's really easy to solve this problem. +\end{Example} +% +\EndIndex{Variable}{subject}% +\EndIndex{Variable}{subjectseparator}% + + +\subsection{Further Issues} +In this paragraph variables and settings are listed which couldn't be assigned +to any other paragraph of the letter declaration but somehow belong to this +chapter. + +\begin{Declaration} + \PLength{tfoldmarkvpos}\\ + \PLength{bfoldmarkvpos} +\end{Declaration} +\BeginIndex{PLength}{tfoldmarkvpos}% +\BeginIndex{PLength}{bfoldmarkvpos}% +The letterclass \Class{scrlttr2} all in all has 3 fold marks. The one in the +middle serves to halve the paper and is therefore printed always in the middle +of paper height. The position of the upper fold mark, seen from the upper +sheet's border, is determined by the pseudo length \PLength{tfoldmarkvpos}; the +lower one is determined by the pseudo length \PLength{bfoldmarkvpos}. All three +fold marks do not serve to exactly fold to a standard 3 panel letter +fold. Instead the idea is to have the paper folded so that the address +field is seen in the window of a window envelope. The settings therefore are +different in the predefined \File{lco}-files. A special case is +\Option{DINmtext}. In this case the envelope format C6/5 (also called +``C6~long'') is necessary. Letters produced in this format aren't compatible +with neither format C~5 nor C~4. +% +\EndIndex{PLength}{tfoldmarkvpos}% +\EndIndex{PLength}{bfoldmarkvpos}% + + +\begin{Declaration} + \PLength{foldmarkhpos} +\end{Declaration} +\BeginIndex{PLength}{foldmarkhpos}% +This pseudo length gives the distance between all of the three fold marks +and the sheet's left border. Usually it's 3{,}5\Unit{mm}. In case you work +with a printer with a broader unprintable left margin this value can be +changed in your own \File{lco}-file. The length of the upper and lower +fold mark is the same and 4\Unit{mm} long. The thickness of all three is +2\Unit{pt}. At the moment there are no plans to change this value. If the fold +marks will be set at all depends on the option \Option{foldmarks} (see +\autoref{sec:scrlttr2.headoptions}, +\autopageref{desc:scrlttr2.option.foldmarks}). +% +\EndIndex{PLength}{foldmarkhpos}% + + +\begin{Declaration} + \Variable{frombank} +\end{Declaration} +\BeginIndex{Variable}{frombank}% +This variable at the moment takes on a special position. Not in use internally +up to this moment it can come into usage if one e.g. wants to have set his +bank account within the sender's extension field or the footer. +% +\EndIndex{Variable}{frombank}% + + +\begin{Declaration} + \Macro{nexthead}\Parameter{construction}\\ + \Macro{nextfoot}\Parameter{construction} +\end{Declaration} +\BeginIndex{Cmd}{nexthead}% +\BeginIndex{Cmd}{nextfoot}% +The possibilities that are offered with variables and options in +\Class{scrlttr2} should be good enough in most of the cases to create +letter-heads and foots for those pages that follow the first letter page. This +even more since you can additionally change the sender's statements with +\Macro{markboth} and \Macro{markright} that \Class{scrlttr2} uses to create +the letter head. With the term ``follow up pages'' in this manual all pages +are meant excepted the first letter page. The commands +\Macro{markboth}\IndexCmd{markboth} and \Macro{markright}\IndexCmd{markright} +can be used all together with pagestyle\Index{page style} +\PValue{myheadings}\IndexPagestyle{myheadings}. If the package +\Package{scrpage2}\IndexPackage{scrpage2} is used this, of course, is valid +also for pagestyle \PValue{scrheadings}\IndexPagestyle{scrheadings}. Then too +the command \Macro{markleft}\IndexCmd{markleft} is available. + +At times one wants to have more freedom with creating letter head or foot of +the follow up pages. Then one has to let go of the possibilities of predefined +letter heads or foots, that could have been chosen via option. Instead one is +free to create it just the way one wants to have them set. Therefore one is to +create the desired \PName{construction} with use of the command +\Macro{nexthead} or \Macro{nextfoot} respectively. Within \Macro{nexthead} and +\Macro{nextfoot} for example you can have several boxes side by side or one +beneath the other by use of \Macro{parbox}-command (see +\cite{latex:usrguide}). With this a more advanced user should have no problems +with creating letter heads of foots of his own. With \PName{construction} of +course you can make use of the variables of \Macro{usekomavar} too. +% +\EndIndex{Cmd}{nexthead}% +\EndIndex{Cmd}{nextfoot}% + + + +\section{The Text} +\label{sec:scrlttr2.text} + +In contrast to an article, a report or a book the letter has +no chapter or section structure. +Even float environments with tables and figure are unusual. +Therefore a letter has no table of contents, lists of +figures and tables, index, bibliography, glossary or other things. +The letter texts mainly consist of an opening and the main +text. Thereupon follows the signature, a postscript +and different listings. + + +\subsection{The Opening} +\label{sec:scrlttr2.opening} + +\begin{Explain} +In the early days of computer generated letters the programs didn't +have many capabilities, therefore the letters seldom had +an opening. +Today the capabilities have been enhanced. Thus personal +openings are very common, even in mass-production +advertising letters. +\end{Explain} + +\begin{Declaration} + \Macro{opening}\Parameter{opening} +\end{Declaration} +\BeginIndex{Cmd}{opening}% +This is the most important command in \Class{scrlttr2}. +For the user it seems that only the opening will be typeset, +but the command also typesets the folding marks, headings, +address field, subject, the page foot and others. +That means: without \Macro{opening} there is no letter. +% +\EndIndex{Cmd}{opening}% + +\subsection{Footnotes} +\label{sec:scrlttr2.footnotes} + +In letters footnotes should be used more sparingly than in normal +documents. However, \Class{scrlttr2} is equipped with all +mechanisms mentioned in \autoref{sec:maincls.footnotes} for +the main document classes. Therefore it will not be discussed +here again. + +\subsection{Lists} +\label{sec:scrlttr2.lists} + +Lists have the same validity in letters as in normal documents. +Thus \Class{scrlttr2} provides the same possibilities +as mentioned in \autoref{sec:maincls.lists} for the +main document classes. + +\subsection{Margin Notes} +\label{sec:scrlttr2.marginNotes} + +Margin notes are quite uncommon in letters. Therefore the +option \Option{mpinclude} is not supported by \Class{scrlttr2}. +However, \Class{scrlttr2} is equipped with all +mechanisms mentioned in \autoref{sec:maincls.marginNotes} for +the main document classes. Therefore it will not be discussed +here again. + +\subsection{Text Emphasis} +\label{sec:scrlttr2.emphasis} + +The distinction of text has the same importance in letters as in +other documents. Thus the same rules apply that means: emphasize +text sparingly. Even letters should be readable and a letter +where each word is typeset in an other font is indeed unreadable. + +The class \Class{scrlttr2} is equipped with all +mechanisms mentioned in \autoref{sec:maincls.emphasis} for +the main document classes. Therefore it will not be discussed +here again. + +\section{The Closing Part} +\label{sec:scrlttr2.backend} + +A letter always ends with a closing phrase. +Even computer generated letters without signature +have this phrase. +Sometimes this is a sentence like ``This letter has been +generated automatically.''. +Sometimes a sentence like this will even be used as signature. +Thereupon can follow a postscript and some listings. + +\subsection{Closing} +\label{sec:scrlttr2.closing} + +The closing consists of three parts. Besides the closing phrase +there are a hand-written inscription and the signature, an explanation +for the inscription. + +\begin{Declaration} + \Variable{signature} +\end{Declaration} +\BeginIndex{Variable}{signature}% +The variable \Variable{signature} includes an explanation +for the inscription. Their content is predefined as +\Macro{usekomavar}\PParameter{fromname}. +The explanation can consist of multiple lines. The lines +should be separated by a double backslash. Paragraphs +in the explanation are not permitted. +% +\EndIndex{Variable}{signature}% + +\begin{Declaration} + \Macro{closing}\Parameter{closing phrase} +\end{Declaration} +\BeginIndex{Cmd}{closing}% +The command \Macro{closing} does not only typeset the +closing phrase, but moreover it typesets the phrase followed +by a vertical space and the content of the variable \Variable{signature}. +The closing phrase can consists of multiple lines, but +paragraphs are not permitted. +% +\EndIndex{Cmd}{closing}% + + +\begin{Declaration} + \PLength{sigindent}\\ + \PLength{sigbeforevskip}\\ + \Macro{raggedsignature} +\end{Declaration} +\BeginIndex{PLength}{sigindent}% +\BeginIndex{PLength}{sigbeforevskip}% +\BeginIndex{Cmd}{raggedsignature}% +Closing phrase, inscription and signature will be typeset +in a box. The width of the box is determined by the length +of the longest line of the closing phrase or signature. + +The box will be typeset with indentation of the length +in pseudo-length \PLength{sigindent}. In the default +\File{lco} file this length is set to 0\Unit{mm}. + +The command \Macro{raggedsignature} defines the alignment +inside the box. In the default \File{lco} file the command +is either defined as \Macro{centering} (all besides \Option{KOMAold}) +or \Macro{raggedright} (\Option{KOMAold}). +In order to get flush-right or flush-left alignment inside the box +the command can be redefined in the same way as +\Macro{raggedsection} (see \autoref{sec:maincls.structure}, +\autopageref{desc:maincls.macro.raggedsection}). + +Between closing phrase and signature a vertical space is +inserted. The height of this space is defined in the pseudo-length +\PLength{sigbeforevskip}. It defaults to 2 lines. +In this space you can write your inscription. +\begin{Example} + You are writing as directorate of a society a letter + to all members. + Moreover you want in one respect elucidate that you are writing + in the name of the board of directors and on the other hand + you want indicate your position in the board of directors. +\begin{lstlisting} + \setkomavar{signature}{John McEnvy\\ + {\small (Vice-President ``The Other Society'')}} + \closing{Regards\\ + (for the board of directors)} +\end{lstlisting} + Certainly you can set the variable \Variable{signature} + in your private \File{lco} file. + Usually you should prefer to define the variable in the + letter preamble. +\end{Example} +% +\EndIndex{PLength}{sigindent}% +\EndIndex{PLength}{sigbeforevskip}% +\EndIndex{Cmd}{raggedsignature}% + +\subsection{Postscript, Carbon Copy and Enclosures} +\label{sec:scrlttr2.afterClosing} + +After the closing can follow some other statements. +Besides the postscript there are the distribution list +of carbon copies and the reference to enclosures. + +\begin{Explain}% +\begin{Declaration} + \Macro{ps} +\end{Declaration}% +\BeginIndex{Cmd}{ps}% +In the time when letters were written by hand it was quite usual +to use a postscript because this was the only way to add +information which one had forget to mention in the main part of +the letter. Of course, in letters written with \LaTeX{} you can +insert additional lines easily. Nevertheless, it is still popular +to use the postscript. It gives a good possibility to underline +again the most important or sometimes the less important things of +this letter. +% +\end{Explain} +This instruction just switches to the postscript. +Therefore a new paragraph begins and a vertical distance +-- usually below the signature -- is inserted. +The command \Macro{ps} is followed by normal text. If you +want the postscript to be introduced with the acronym "PS:" you +have to type the acronym inside the command. By the way, this +acronym is been written without a full stop. The acronym is +neither be typeset automatically nor optionally by the class +\Class{scrlttr2}. +% +\EndIndex{Cmd}{ps} + + +\begin{Declaration} + \Macro{cc}\Parameter{distribution list}\\ + \Variable{ccseparator} +\end{Declaration} +\BeginIndex{Cmd}{cc}% +\BeginIndex{Variable}{ccseparator}% +With the command \Macro{cc} it is possible to typeset a +\PName{distribution list}. +The command gets the \PName{distribution list} as argument. +If the content of the variable \Variable{ccseparator} +isn't empty then the name and the content of the variable +is inserted prior to \PName{distribution list}. +In this case the \PName{distribution list} will be indented +appropriately. +It is a good idea to set the \PName{distribution list} +\Macro{raggedright} and to separate the lines by a double backslash. +\begin{Example} +You want to indicate that your letter is addressed to all members of a +society and to the board of directors: +\begin{lstlisting} + \cc{% + the board of directors\\ + all society members\\ +\end{lstlisting} + Write this instruction below the \Macro{closing}-instruction + from the previous example or below a possible postscript. +\end{Example} +A vertical space is inserted automatically before the distribution +list. +% +\EndIndex{Cmd}{cc}% +\EndIndex{Variable}{ccseparator}% + + +\begin{Declaration} + \Macro{encl}\Parameter{enclosures}\\ + \Variable{enclseparator} +\end{Declaration} +\BeginIndex{Cmd}{encl}% +\BeginIndex{Variable}{enclseparator}% +\PName{Enclosures} have the same structure as the distribution list. +There is just a single difference, the enclosures starts with +the name and the content of the variable \Variable{enclseparator}. +% +\EndIndex{Cmd}{encl}% +\EndIndex{Variable}{enclseparator}% + + +\section{Language Support} +\label{sec:scrlttr2.languages} + +The document class \Class{scrlttr2} supports many languages. These +are German \PValue{ngerman} (\PValue{german} for old German +orthography), \PValue{austrian} for Austrian, English +(\PValue{english} without specification whether American or British +should be used, \PValue{american} and \PValue{USenglish} for American, +\PValue{british} and \PValue{UKenglish} for British), French, Italian, +Spanish, Dutch and Croatian. + +\subsection{Language Selection} +\label{sec:scrlttr2.switchLanguage} +\Index[indexmain]{language selection} + +If the package \Package{babel}\IndexPackage{babel} is used one can +switch between languages with the command +\Macro{selectlanguage}\Parameter{language}. Other packages like +\Package{german}\IndexPackage{german} and +\Package{ngerman}\IndexPackage{ngerman} also define this command. As +a rule the language selection takes place when such a package is +loaded. + +There is one thing more to mention about language packages. The +package \Package{french}\IndexPackage{french} re-defines not only the +terms of \autoref{sec:scrlttr2.languageTerms}. The package even +re-defines the command \Macro{opening}, since it assumes that the +definition of the standard \Class{letter} is used. Therefore the +package \Package{french} spoils the definition of the \Class{scrlttr2} +class. I think this is a fault of the \Package{french} package. + +If one utilizes the \Package{babel}\IndexPackage{babel} package in +order to switch to language \PValue{french} and the package +\Package{french}\IndexPackage{french} is installed too, then the same +problems occur since \Package{babel} employs definitions from the +\Package{french} package. If the package \Package{french} is not +installed then there are no problems. + +Additionally there is no problem if for \Package{babel} instead of +\PValue{french} other languages like \PValue{acadian}, +\PValue{canadien}, \PValue{francais} or \PValue{frenchb} are chosen. +Therefore I recommend +\Macro{usepackage}\PValue{[frenchb]}\PParameter{babel} in order to +select french. + +Other languages can cause these problems too. Currently there are no +problems known with the \Package{babel} package for the german +language and the various english language selections. + +\iftrue +% You may use this paragraphs to improve page break: +Most \Package{babel} features at \Package{babel} or original +language definition files of \Package{babel} (e.g. \File{frenchb.ldf}), +which may cause problems with other packages or classes, can be +switched off. This is a great advantage of babel. So if you have a +problem, try to switch of such features or ask the authors of +\Package{babel}. + +There are no problems known using the +\Package{german}\IndexPackage{german} or +\Package{ngerman}\IndexPackage{ngerman} package for german selection +with old or new orthography. +\fi + +\begin{Declaration} + \Macro{captionsenglish}\\ + \Macro{captionsUSenglish}\\ + \Macro{captionsamerican}\\ + \Macro{captionsbritish}\\ + \Macro{captionsUKenglish}\\ + \Macro{captionsgerman}\\ + \Macro{captionsngerman}\\ + \Macro{captionsaustrian}\\ + \Macro{captionsfrench}\\ + \Macro{captionsitalian}\\ + \Macro{captionsspanish}\\ + \Macro{captionsdutch}\\ + \Macro{captionscroatian} +\end{Declaration} +\BeginIndex{Cmd}{captionsenglish}\BeginIndex{Cmd}{captionsUSenglish} +\BeginIndex{Cmd}{captionsamerican}\BeginIndex{Cmd}{captionsbritish} +\BeginIndex{Cmd}{captionsUKenglish}\BeginIndex{Cmd}{captionsgerman} +\BeginIndex{Cmd}{captionsngerman} +\BeginIndex{Cmd}{captionsaustrian}\BeginIndex{Cmd}{captionsfrench} +\BeginIndex{Cmd}{captionsitalian}\BeginIndex{Cmd}{captionsspanish} +\BeginIndex{Cmd}{captionsdutch}\BeginIndex{Cmd}{captionscroatian} If +one switches the language then using these commands the language-terms +from \autoref{sec:scrlttr2.languageTerms} are re-defined. +If the used language selection scheme does not support this +then the commands above can be used directly. +% +\EndIndex{Cmd}{captionsenglish}\EndIndex{Cmd}{captionsUSenglish} +\EndIndex{Cmd}{captionsamerican}\EndIndex{Cmd}{captionsbritish} +\EndIndex{Cmd}{captionsUKenglish}\EndIndex{Cmd}{captionsgerman} +\EndIndex{Cmd}{captionsngerman} +\EndIndex{Cmd}{captionsaustrian}\EndIndex{Cmd}{captionsfrench} +\EndIndex{Cmd}{captionsitalian}\EndIndex{Cmd}{captionsspanish} +\EndIndex{Cmd}{captionsdutch}\EndIndex{Cmd}{captionscroatian} + + +\begin{Declaration} + \Macro{dateenglish}\\ + \Macro{dateUSenglish}\\ + \Macro{dateamerican}\\ + \Macro{datebritish}\\ + \Macro{dateUKenglish}\\ + \Macro{dategerman}\\ + \Macro{datengerman}\\ + \Macro{dateaustrian}\\ + \Macro{datefrench}\\ + \Macro{dateitalian}\\ + \Macro{datespanish}\\ + \Macro{datedutch}\\ + \Macro{datecroatian}\\ + \Macro{datefinnish} +\end{Declaration} +\BeginIndex{Cmd}{dateenglish}\BeginIndex{Cmd}{dateUSenglish} +\BeginIndex{Cmd}{dateamerican}\BeginIndex{Cmd}{datebritish} +\BeginIndex{Cmd}{dateUKenglish}\BeginIndex{Cmd}{dategerman} +\BeginIndex{Cmd}{datengerman} +\BeginIndex{Cmd}{dateaustrian}\BeginIndex{Cmd}{datefrench} +\BeginIndex{Cmd}{dateitalian}\BeginIndex{Cmd}{datespanish} +\BeginIndex{Cmd}{datedutch}\BeginIndex{Cmd}{datecroatian}% +\BeginIndex{Cmd}{datefinnish}% +The date\Index{Date} in its numerical representation +(see option \Option{numericaldate} in +\autoref{sec:scrlttr2.headoptions}) will be written depending +on the selected language. Some examples can be found in +\autoref{tab:date}. +% +\EndIndex{Cmd}{dateenglish}\EndIndex{Cmd}{dateUSenglish} +\EndIndex{Cmd}{dateamerican}\EndIndex{Cmd}{datebritish} +\EndIndex{Cmd}{dateUKenglish}\EndIndex{Cmd}{dategerman} +\EndIndex{Cmd}{datengerman} +\EndIndex{Cmd}{dateaustrian}\EndIndex{Cmd}{datefrench} +\EndIndex{Cmd}{dateitalian}\EndIndex{Cmd}{datespanish} +\EndIndex{Cmd}{datedutch}\EndIndex{Cmd}{datecroatian}% +\EndIndex{Cmd}{datefinnish}% + +\begin{table}[t] + \centering + \caption{Language-dependent forms of the date} + \begin{tabular}{ll} + \toprule + Command & Date example \\ + \midrule + \Macro{dateenglish} & 1/12/1993\\ + \Macro{dateUSenglish} & 12/1/1993\\ + \Macro{dateamerican} & 12/1/1993\\ + \Macro{datebritish} & 1/12/1993\\ + \Macro{dateUKenglish} & 1/12/1993\\ + \Macro{dategerman} & 1.\,12.\,1993\\ + \Macro{datengerman} & 1.\,12.\,1993\\ + \Macro{dateaustrian} & 1.\,12.\,1993\\ + \Macro{datefrench} & 1.\,12.\,1993\\ + \Macro{dateitalian} & 1.\,12.\,1993\\ + \Macro{datespanish} & 1.\,12.\,1993\\ + \Macro{datedutch} & 1.\,12.\,1993\\ + \Macro{datecroatian} & 1.\,12.\,1993.\\ + \Macro{datefinnish } & 1.\,12.\,1993.\\ + \bottomrule + \end{tabular} + \label{tab:date} +\end{table} +% + + +\subsection{Language-Dependent Terms}% +\label{sec:scrlttr2.languageTerms}% +\Index[indexmain]{language-dependent terms}% +\Index[indexmain]{terms, language-dependent} + +As usual in \LaTeX{}, the language-dependent terms are defined +by commands. These commands are re-defined when one switches +the language. + +\begin{Declaration} + \Macro{yourrefname}\\ + \Macro{yourmailname}\\ + \Macro{myrefname}\\ + \Macro{customername}\\ + \Macro{invoicename}\\ + \Macro{subjectname}\\ + \Macro{ccname}\\ + \Macro{enclname}\\ + \Macro{headtoname}\\ + \Macro{headfromname}\\ + \Macro{datename}\\ + \Macro{pagename}\\ + \Macro{phonename}\\ + \Macro{faxname}\\ + \Macro{emailname}\\ + \Macro{wwwname}\\ + \Macro{bankname} +\end{Declaration} +\BeginIndex{Cmd}{yourrefname}\BeginIndex{Cmd}{yourmailname} +\BeginIndex{Cmd}{myrefname} +\BeginIndex{Cmd}{customername}\BeginIndex{Cmd}{invoicename} +\BeginIndex{Cmd}{subjectname} +\BeginIndex{Cmd}{ccname}\BeginIndex{Cmd}{enclname} +\BeginIndex{Cmd}{headtoname}\BeginIndex{Cmd}{headfromname} +\BeginIndex{Cmd}{datename}\BeginIndex{Cmd}{pagename} +\BeginIndex{Cmd}{phonename}\BeginIndex{Cmd}{faxname} +\BeginIndex{Cmd}{emailname}\BeginIndex{Cmd}{wwwname} +\BeginIndex{Cmd}{bankname} The commands above contain the +language-dependent terms. These definitions can be modified in +order to support a new language or for private customization. +How this can be done is described in +\autoref{sec:scrlttr2.defLanguageTerms}. +The definitions become active at \Macro{begin}\PParameter{document}. +Therefore they are not available in the \LaTeX{} preamble. +Thus they even can not be re-defined there. +In \autoref{tab:scrlttr2.languageTerms} the default settings +for \Option{english} and \Option{ngerman} can be found. +% +\EndIndex{Cmd}{yourrefname}\EndIndex{Cmd}{yourmailname} +\EndIndex{Cmd}{myrefname} +\EndIndex{Cmd}{customername}\EndIndex{Cmd}{invoicename} +\EndIndex{Cmd}{subjectname} +\EndIndex{Cmd}{ccname}\EndIndex{Cmd}{enclname} +\EndIndex{Cmd}{headtoname}\EndIndex{Cmd}{headfromname} +\EndIndex{Cmd}{datename}\EndIndex{Cmd}{pagename} +\EndIndex{Cmd}{phonename}\EndIndex{Cmd}{faxname} +\EndIndex{Cmd}{emailname}\EndIndex{Cmd}{wwwname} +\EndIndex{Cmd}{bankname} + +\begin{table}[!t] + \begin{minipage}{\textwidth} + \centering + \caption{Default settings for languages \Option{english} + and \Option{ngerman}} + \begin{tabular}{lll} + \toprule + Command & \Option{english} & \Option{ngerman} \\ + \midrule + \Macro{bankname} & Bank account & Bankverbindung \\ + \Macro{ccname}\footnotemark[1] & cc & Kopien an \\ + \Macro{customername} & Customer no. & Kundennummer \\ + \Macro{datename} & Date & Datum \\ + \Macro{emailname} & Email & E-Mail \\ + \Macro{enclname}\footnotemark[1] & encl & Anlagen \\ + \Macro{faxname} & Fax & Fax \\ + \Macro{headfromname} & From & Von \\ + \Macro{headtoname}\footnotemark[1] & To & An \\ + \Macro{invoicename} & Invoice no. & Rechnungsnummer \\ + \Macro{myrefname} & Our ref. & Unser Zeichen \\ + \Macro{pagename}\footnotemark[1] & Page & Seite \\ + \Macro{phonename} & Phone & Telefon \\ + \Macro{subjectname} & Subject & Betrifft \\ + \Macro{wwwname} & Url & URL \\ + \Macro{yourmailname} & Your letter of & Ihr Schreiben vom\\ + \Macro{yourrefname} & Your ref. & Ihr Zeichen \\ + \bottomrule + \end{tabular} + \label{tab:scrlttr2.languageTerms} + \deffootnote{1em}{1em}{\textsuperscript{1}}% + \footnotetext[1000]{Normally these terms are defined by language packages + like \Package{babel}. At this case they are not redefined by + \Class{scrlttr2} and may differ from the table above.} + \end{minipage} +\end{table} +% + +\subsection{Defining Language Terms} +\label{sec:scrlttr2.defLanguageTerms} +\Index[indexmain]{language definition} +\begin{Explain} + Normally one has to change or define the language terms of + \autoref{sec:scrlttr2.switchLanguage} in a way that additionally + to the available terms even the new or re-defined terms are + defined. Some packages like \Package{german}\IndexPackage{german} or + \Package{ngerman}\IndexPackage{ngerman} re-define those settings + when they are loaded. These packages re-define the definitions in a + way that spoils all previous private settings. That is also the + reason, why \Class{scrlttr2} delays its own changes with + \Macro{AtBeginDocument} until + \Macro{begin}\PParameter{document}. The user can also use + \Macro{AtBeginDocument} or re-define the language terms after + \Macro{begin}\PParameter{document}. The class \Class{scrlttr2} + provides some commands for defining language terms. +\end{Explain} + +\begin{Declaration} + \Macro{providecaptionname}% + \Parameter{language}\Parameter{term}\Parameter{definition}\\ + \Macro{newcaptionname}% + \Parameter{language}\Parameter{term}\Parameter{definition}\\ + \Macro{renewcaptionname}% + \Parameter{language}\Parameter{term}\Parameter{definition} +\end{Declaration} +\BeginIndex{Cmd}{providecaptionname}% +\BeginIndex{Cmd}{newcaptionname}% +\BeginIndex{Cmd}{renewcaptionname}% +Using one of the commands above the user can assign +a \PName{definition} for a \PName{language} to a \PName{term} . +The \PName{term} is always a command. The commands differ +dependent from whether a \PName{term} is already define +in \PName{language} or not. + +If \PName{language} is not defined then \Macro{providecaptionname} +writes only a message in the log-file. This happens only +once for each language. +If \PName{language} is defined but \PName{term} isn't defined +yet, then it will be defined using \PName{definition}. +The \PName{term} will not be re-defined if the \PName{language} +already has a definition. Instead of this a log-message will be written. + +The command \Macro{newcaptionname} has a slightly different behaviour. +If the \PName{language} is not yet defined then a new language +command (see \autoref{sec:scrlttr2.switchLanguage}) +will be created and a log-message will be written. +If \PName{term} is not yet defined in \PName{language} then +it will be defined with \PName{definition}. +If \PName{term} already exists in \PName{language} then this +results in an error message. + +The command \Macro{renewcaptionname} requires an existing +definition of \PName{term} in \PName{language}. +In this case \PName{term} for \PName{language} will be re-defined +according to \PName{definition}. If neither \PName{language} +nor \PName{term} exist or \PName{term} is unknown in a defined +language then a error message will be given. + +The class \Class{scrlttr2} itself employs \Macro{providecaptionname} +in order to define the commands in +\autoref{sec:scrlttr2.languageTerms}. +\begin{Example} + If you prefer ``Your message of'' instead of ``Your letter of'' + you have to re-define the definition of \Macro{yourmailname}. +\begin{lstlisting} + \renewcaptionname{english}{\yourmailname}{% + Your message of} +\end{lstlisting} + + Since only available terms can be re-defined you have to + delay the command until \Macro{begin}\PParameter{document} + using \Macro{AtBeginDocument}. + Furthermore you will get an error message if there is no + package used that defines a language selection command + for \PName{english}. +\end{Example} +% +\EndIndex{Cmd}{providecaptionname}% +\EndIndex{Cmd}{newcaptionname}% +\EndIndex{Cmd}{renewcaptionname}% + +\section{Address Files and Circular Letters} +\label{sec:scrlttr2.addressFile} + +When people write circular letters they mostly dislike to +type the many addresses. +The class \Class{scrlttr2} and its predecessor \Class{scrlettr} +as well provide basic support for it. +Currently there are plans for a much enhanced support. + +\typeout{^^J--- Ignore underfull and overfull \string\hbox:}% +\begin{Declaration} + \Macro{adrentry}\Parameter{Lastname}\Parameter{Firstname}% + \Parameter{Address}\Parameter{Telephone}\Parameter{F1}\Parameter{F2}% + \Parameter{Comment}\Parameter{Key} +\end{Declaration}% +\typeout{^^J--- Don't ignore underfull and overfull \string\hbox:} +\BeginIndex{Cmd}{adrentry} +\label{decl:adrentry} + +The class \Class{scrlttr2} supports to use address files. +These address files contain address entries. +Each entry is an \Macro{adrentry} command with eight parameters as +can be seen above. +The file extension of the address file has to be \File{.adr}. +\begin{lstlisting} + \adrentry{McEnvy} + {Flann} + {Main Street 1\\ Glasgow} + {123 4567} + {male} + {} + {niggard} + {FLANN} +\end{lstlisting} +The 5\textsuperscript{th} and 6\textsuperscript{th} element, \PValue{F1} and +\PValue{F2}, can be used freely, for example for the gender, the academic +grade, the birthday or the date the person has joined a society. The last +parameter \PName{Key} should only consist of uppercase letters in order to not +interfere with other \TeX{} or \LaTeX{} commands. + +\begin{Example} + Mr.\,McEnvy is one of your most important business partners, + but every day you get a reclamation from him. + Before long you don't want to bother typing his boring + address again and again. + Here \Class{scrlttr2} can help. + All your business partners have an entry in your + \File{partners.adr} address file. + If you now have to answer Mr.\,McEnvy again, then you + can save typing as can be seen below: +\begin{lstlisting} + \input{partners.adr} + \begin{letter}{\FLANN} + Your today's reclamation \dots + \end{letter} +\end{lstlisting} + Your \TeX{} system must be configured to have access to your + address file. Without access the \Macro{input} command results + in an error. You can either put your address file where you + are running \LaTeX{} or configure your system to find + the file in a special directory. +\end{Example} +% +\EndIndex{Cmd}{adrentry} + +\typeout{^^J--- Ignore underfull and overfull \string\hbox:}% +\begin{Declaration} + \Macro{addrentry}\Parameter{Lastname}\Parameter{Firstname}% + \Parameter{Address}\Parameter{Telephone}\Parameter{F1}\Parameter{F2}% + \Parameter{F3}\Parameter{F4}\Parameter{Key} +\end{Declaration}% +\typeout{^^J--- Dont't ignore underfull and overfull \string\hbox:} +\BeginIndex{Cmd}{addrentry}% +Over the years people objected that the \Macro{adrentry} has only +two free parameters. Since \TeX{} supports at maximum nine +parameters per command, there now exists a new command called +\Macro{addrentry}, note the additional ``d''. +This command supports four freely definable parameters, that +means one parameter more than \Macro{adrentry}, since the comment +parameter has been replaced with the fourth free parameter. +The numbers of parameters is the only difference between +both commands. Thus you can mix both entry types in +one address file. + +There are some packages which can employ \File{adr} files. +For example \Package{adrconv} by Axel Kielhorn can be used +to create address lists from \File{adr} files. +But it has currently no support for command \Macro{addrentry}. +The only choice is to extent the package yourself. +% +\EndIndex{Cmd}{addrentry} + +Besides the simple access to addresses the address files can +be easily used in order to write circular letters. +Thus there is no complicated data-base system and its connection +to \TeX{} required. +% +\begin{Example} + Suppose you are member of a society and want write a invitation + for the next general meeting to all members. +\begin{lstlisting} + \documentclass{scrlttr2} + \begin{document} + \renewcommand*{\adrentry}[8]{ + \begin{letter}{#2 #1\\#3} + \opening{Dear members,} + our next general meeting will be on monday + August 12, 2002. The following topics are \dots + \closing{Regards,} + \end{letter} + } + \input{members.adr} + \end{document} +\end{lstlisting} + If the address file contains \Macro{addrentry} statements + too, then even an additional definition for \Macro{addrentry} + is required. +\begin{lstlisting} + \renewcommand*{\addrentry}[9]{ + \begin{letter}{#2 #1\\#3} + \opening{Dear members,} + our next general meeting will be on Monday + August 12, 2002. The topics of the meeting are \dots + \closing{Regards,} + \end{letter} + } +\end{lstlisting} + In this simple example the extra freely definable parameter + is not used. +\end{Example} + +With some additional programming one can let the contents +depend on the address data. For this the free parameters +can be used. + +\begin{Example} + Suppose the fifth parameter of the \Macro{adrentry} command + contains the gender of a member (\PValue{m/f}). + The sixth parameter contains what member subscription + has still not been discharged by the member. + If you would like to write a more personal reminder + then the next example can help you. +\begin{lstlisting} + \renewcommand*{\adrentry}[8]{ + \ifcase #6 + % #6 greater than 0? + % this selects all members with open subscription + \else + \begin{letter}{#2 #1\\#3} + \if #5m \opening{Dear Mr.\,#2,} \fi + \if #5f \opening{Dear Mrs.\,#2,} \fi + + Unfortunately we have to remind you that you have + still not paid the member subscription for this + year. + + Please remit EUR #6 to the account of the society. + \closing{Regards,} + \end{letter} + \fi + } +\end{lstlisting} +\end{Example} +As you can see the letter text can be made more personal +depending on attributes of the letter's addressee. +The number of attributes is only restricted by number of the +two free parameters of the \Macro{adrentry} command or +four free parameters of the \Macro{addrentry} command. + +\begin{Declaration} + \Macro{adrchar}\Parameter{initial letter}\\ + \Macro{addrchar}\Parameter{initial letter} +\end{Declaration} +\BeginIndex{Cmd}{adrchar}\BeginIndex{Cmd}{addrchar} +\Index[indexmain]{address list}\Index[indexmain]{telephone list}% +As already mentioned above it is possible to create address +and telephone lists using \File{adr} files. +For that the additional package \Package{adrconv} by +Axel Kielhorn (see \cite{package:adrconv}) is needed. +This package contains interactive \LaTeX{} documents +which help to create those lists. + +The address files have to be sorted already in order to +get sorted lists. It is recommended to sort and separate the +entries by the initial letter of \PName{Lastname}. +As a separator the commands \Macro{adrchar} and \Macro{addrchar} +can be used. These commands will be ignored if the address files +are utilized in \Class{scrlettr2}. +% +\begin{Example} + Suppose the following address file: +\begin{lstlisting} + \adrchar{A} + \adrentry{Angel}{Gabriel} + {Cloud 3\\12345 Heaven's Realm} + {000\,01\,02\,03}{}{}{archangel}{GABRIEL} + \adrentry{Angel}{Michael} + {Cloud 3a\\12345 Heaven's Realm} + {000\,01\,02\,04}{}{}{archangel}{MICHAEL} + \adrchar{K} + \adrentry{Kohm}{Markus} + {Fichtenstra\ss e 63\\68535 Edingen-Neckarhausen} + {+49~62\,03~1\,??\,??}{}{}{no angel at all} + {KOMA} +\end{lstlisting} + This address file can be treated with \File{adrdir.tex} of the + \Package{adrconv} package \cite{package:adrconv}. + The result should look like this: + \begin{center} + \setlength{\unitlength}{1mm} + \begin{picture}(80,57) + \put(0,57){\line(1,0){80}} + \put(0,3){\line(0,1){54}} + \put(80,3){\line(0,1){54}} + \thicklines + \put(10,42){\line(1,0){60}} + \put(70,45){\makebox(0,0)[r]{\textsf{\textbf{A}}}} + \put(10,23){\makebox(0,20)[l]{\parbox{5cm}{\raggedright + \textsc{Angel}, Gabriel\\\quad\small Cloud 3\\ + \quad 12345 Heaven's Realm\\ + \quad (archangel)}}} + \put(70,23){\makebox(0,20)[r]{\parbox{2cm}{\raggedright~\\ + \small~\\\textsc{gabriel}\\000\,01\,02\,03}}} + \put(10,4){\makebox(0,20)[l]{\parbox{5cm}{\raggedright + \textsc{Angel}, Michael\\\quad\small Cloud 3a\\ + \quad 12345 Heaven'S Realm\\ + \quad (archangel)}}} + \put(70,4){\makebox(0,20)[r]{\parbox{2cm}{\raggedright~\\ + \small~\\\textsc{michael}\\000\,01\,02\,04}}} + \qbezier(0,3)(10,6)(40,3)\qbezier(40,3)(60,0)(80,3) + \end{picture} + \end{center} + The letter in the page heading is created by the + \Macro{adrchar} command, see the definition in \File{adrdir.tex}. +\end{Example} +More about the \Package{adrconv} package can be found in its +documentation. There you should even find information if +the version of \Package{adrconv} supports already the +\Macro{addrentry} and \Macro{addrchar} commands. +Former versions only know the commands \Macro{adrentry} and +\Macro{adrchar}. +% +\EndIndex{Cmd}{adrchar}\EndIndex{Cmd}{addrchar}% + + +\section{From \Class{scrlettr} to \Class{scrlttr2}} +\label{sec:scrlttr2.fromscrlettr} + +The first step in the conversion of an old letter written with +the \Class{scrlettr} class is to load the appropriate +\File{lco} file using option \Option{KOMAold} at +\Macro{documentclass}. +Thereupon most commands of the old class should work. +But you will encounter some differences in the output, since +the page layout of both classes is not the same. +The reason is that the calculation of the type-area in \Class{scrlettr} +has some minor bugs. For example the position of the folding marks +used to depend on the height of the page heading, which again has +dependence to the font size. That was an unambiguous design fault. + +There is no compatibility regarding the defined lengths +in \Class{scrlettr}. +If one has changed the page layout of \Class{scrlettr} +then those statements have to be deleted or commented out. +In some cases the modification of length can cause +an error, since this length is not defined anymore. +You should delete or comment these modifications as well. + +The old letter example: +\begin{lstlisting} + \documentclass[10pt,KOMAold]{scrlttr2} + \name{\KOMAScript{} team} + \address{Class Alley 1\\12345 \LaTeX{} City} + \signature{Your \KOMAScript{} team} + \begin{document} + \begin{letter}{\KOMAScript{} users\\ + Everywhere\\world-wide} + \opening{Dear \KOMAScript{} users,} + the \KOMAScript{} team is proud to announce \dots + \closing{Happy \TeX{}ing} + \end{letter} + \end{document} +\end{lstlisting} +works as expected only by option \Option{KOMAold}. + + +The next step is that the layout of the old letter will +not be used anymore, but the old commands should still +be available. +If for example one wants the layout of \Option{DIN} +then this option can be given in \Macro{documentclass}, +but is has to be specified \emph{after} the option +\Option{KOMAold}. + +\begin{lstlisting} + \documentclass[10pt,KOMAold,DIN]{scrlttr2} + \name{\KOMAScript{} team} + \address{Class Alley 1\\12345 \LaTeX{} City} + \signature{Your \KOMAScript{} team} + \begin{document} + \begin{letter}{\KOMAScript{} users\\ + Everywhere\\world-wide} + \opening{Dear \KOMAScript{} users,} + the \KOMAScript{} team is proud to announce \dots + \closing{Happy \TeX{}ing} + \end{letter} + \end{document} +\end{lstlisting} +Using more options this way you have further influence on the +layout, but a more inherent change is really recommended. + +That is to replace all old commands with its new representations +and omit the option \Option{KOMAold}. +It can help to read the contents of \File{KOMAold.lco}. +In that file the old commands are defined using the new ones. + +\begin{lstlisting} + \documentclass{scrlttr2} + \setkomavar{fromname}{\KOMAScript{} team} + \setkomavar{fromaddress}{Class Alley 1\\ + 12345 \LaTeX{} City} + \setkomavar{signature}{Your \KOMAScript{} team} + \let\raggedsignature=\raggedright + \begin{document} + \begin{letter}{\KOMAScript{} users\\ + Everywhere\\ + world-wide} + \opening{Dear \KOMAScript{} users,} + the \KOMAScript{} team is proud to announce \dots + \closing{Happy \TeX{}ing} + \end{letter} + \end{document} +\end{lstlisting} +This example shows also the possibility to change the +alignment of the signature by re-defining the command +\Macro{raggedsignature}. +This is recommended if the width of the real signature +is greater than the signature-definition of the command +\Macro{setkomavar}\PParameter{signature}\PParameter{\dots}. +% +\EndIndex{Class}{scrlttr2}\EndIndex{}{Letters} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "../guide" +%%% End: + +% LocalWords: scrlttr simpleSwitchValues afteropening beforeopening lcoFile +% LocalWords: locfield diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrpage2.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrpage2.tex new file mode 100644 index 00000000000..5c85e5779db --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrpage2.tex @@ -0,0 +1,1396 @@ +% ====================================================================== +% scrpage2.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3b of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3b or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% scrpage2.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3b, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3b ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about scrpage2 of the KOMA-Script guide +% Maintained by Jens-Uwe Morawski (and sometimes Markus Kohm) +% +% ---------------------------------------------------------------------- +% +% Kapitel über scrpage2 in der KOMA-Script-Anleitung +% Verwaltet von Jens-Uwe Morawski (unterstützt von Markus Kohm) +% +% ============================================================================ + +\ProvidesFile{scrpage2.tex}[2006/07/01 KOMA-Script guide (chapter:scrpage2)] +% date of translated german file: 2004/08/10 + +\chapter{Adapt Head and Foot with \Package{scrpage2}} +\labelbase{scrpage} + +% +\BeginIndex{Package}{scrpage2}% +% +In \autoref{cha:typearea} this guide referenced a package +to customise the head and foot lines of a document. +This package \Package{scrpage2}, the successor of \Package{scrpage}, +enables the user to create versatile head and foot layouts with +less effort, due to a simple but powerful user interface. While +\Package{scrpage} is obsolete since 2001, this documentation only describes +\Package{scrpage2}. + +\begin{Explain} + The package's focus is its good integration into the whole + \KOMAScript{}-bundle, thus it extents the base functionality of + \KOMAScript{} perfectly. It is very flexible in either its layout and + usage, compared to other packages often to be seen like + \Package{fancyhdr}\cite{package:fancyhdr}. You don't need to use + \Package{scrpage2} with \KOMAScript{}, the package can be used in any other + document-class environment. +\end{Explain} + + +\section{Basic Functionality}\label{sec:scrpage.basics} + +\begin{Explain}% Introduction to headings + \LaTeX{}'s head and foot mechanism is a little complicated, thus a + brief view in its depth is needed. + Basically the \LaTeX{} kernel defines the chief page styles + \PValue{empty} and \PValue{plain}. + The latter writes only a page number in the foot, in contrast + using \PValue{empty} results in blank head and foot. + Besides, many document classes provide the style + \PValue{headings}, which allows more complex style settings. + The \PValue{headings} style often has a subvariant, the + \emph{my}-variant. In contrast to the \PValue{headings} style + the \PValue{myheadings} switches off the automatic update + of the running head, thus it is the users task keeping headings + in sync with the current document content. + A more detailed discription can be found in + \autoref{sec:maincls.pageStyle}. + + Another important note is that some \LaTeX{} commands + switch to the pagestyle \PValue{plain} for the current page, + independent from what pagestyle was choosen by the author, + consequently the document needs an appropriate + \PValue{plain} pagestyle. + + Therefore \Package{scrpage2} defines its own \PValue{plain} + and \PValue{headings} page styles, named \PValue{scrplain} + and \PValue{scrheadings}. + The manual activation of \PValue{scrplain} is not necessary, + since the activation of \PValue{scrheadings} takes care of it + automatically. + Only if one wants to use his own page style in combination + with \PValue{scrplain}, the page style \PValue{scrplain} has to + be activated first, i.e. \Macro{pagestyle}\Parameter{scrplain}% + \Macro{pagestyle}\Parameter{personalPagestyle}. +\end{Explain} + +The original \PValue{headings} page style of the document class is available +as \PValue{useheadings}. This re-definition is required since +\Package{scrpage2} uses another way to deal with automatic and manual +headings. This way is more flexible and allows configurations usually +difficult to implement for unexperienced users. The required commands to work +with the \Package{scrpage2} implementation are introduced at the end of +\autoref{sec:scrpage.basics.buildIn} and the begin of +\autoref{sec:scrpage.basics.mark}. + +\subsection{Predefined Page Styles}\label{sec:scrpage.basics.buildIn} +% \lehead ... +% scrheadings +% \headmark \pagemark + +\begin{Declaration} + \PValue{scrheadings}\\ + \PValue{scrplain} +\end{Declaration}% +\BeginIndex{Pagestyle}{scrheadings}\BeginIndex{Pagestyle}{scrplain}% +\Index{page style}% +% +Package \Package{scrpage2} delivers an own pagestyle, named +\PValue{scrheadings}. +The command \Macro{pagestyle}\PParameter{scrheadings} activates +this page style, likewise +after activation an appropriate \PValue{plain} pagestyle +is available. +In this case \emph{appropriate} meens that the \PValue{plain} +page style is also configureable by the commands introduced in +\autoref{sec:scrpage.basics.format}, which, for example, +configure the head and foot width. +Neither the activation of \PValue{scrheadings} nor \PValue{scrplain} +influences the mode of manual or automatic headings, +see \autoref{sec:scrpage.basics.mark}. + +\begin{Declaration} + \Macro{lehead}% + \OParameter{scrplain-left-even}\Parameter{scrheadings-left-even}\\ + \Macro{cehead}% + \OParameter{scrplain-concentric-even}\Parameter{scrheadings-concentric-even}\\ + \Macro{rehead}% + \OParameter{scrplain-right-even}\Parameter{scrheadings-right-even}\\ + \Macro{lefoot}% + \OParameter{scrplain-left-even}\Parameter{scrheadings-left-even}\\ + \Macro{cefoot}% + \OParameter{scrplain-concentric-even}\Parameter{scrheadings-concentric-even}\\ + \Macro{refoot}% + \OParameter{scrplain-right-even}\Parameter{scrheadings-right-even}\\ + \Macro{lohead}% + \OParameter{scrplain-left-odd}\Parameter{scrheadings-left-odd}\\ + \Macro{cohead}% + \OParameter{scrplain-concentric-odd}\Parameter{scrheadings-concentric-odd}\\ + \Macro{rohead}% + \OParameter{scrplain-right-odd}\Parameter{scrheadings-right-odd}\\ + \Macro{lofoot}% + \OParameter{scrplain-left-odd}\Parameter{scrheadings-left-odd}\\ + \Macro{cofoot}% + \OParameter{scrplain-concentric-odd}\Parameter{scrheadings-concentric-odd}\\ + \Macro{rofoot}% + \OParameter{scrplain-right-odd}\Parameter{scrheadings-right-odd}\\ + \Macro{ihead}% + \OParameter{scrplain-inside}\Parameter{scrheadings-inside}\\ + \Macro{chead}% + \OParameter{scrplain-concentric}\Parameter{scrheadings-concentric}\\ + \Macro{ohead}% + \OParameter{scrplain-outside}\Parameter{scrheadings-outside}\\ + \Macro{ifoot}% + \OParameter{scrplain-inside}\Parameter{scrheadings-inside}\\ + \Macro{cfoot}% + \OParameter{scrplain-concentric}\Parameter{scrheadings-concentric}\\ + \Macro{ofoot}% + \OParameter{scrplain-outside}\Parameter{scrheadings-outside} +\end{Declaration}% +\BeginIndex{Cmd}{lehead}\BeginIndex{Cmd}{cehead}\BeginIndex{Cmd}{rehead}% +\BeginIndex{Cmd}{ihead}\BeginIndex{Cmd}{chead}\BeginIndex{Cmd}{ohead}% +\BeginIndex{Cmd}{lohead}\BeginIndex{Cmd}{cohead}\BeginIndex{Cmd}{rohead}% +\BeginIndex{Cmd}{lefoot}\BeginIndex{Cmd}{cefoot}\BeginIndex{Cmd}{refoot}% +\BeginIndex{Cmd}{ifoot}\BeginIndex{Cmd}{cfoot}\BeginIndex{Cmd}{rfoot}% +\BeginIndex{Cmd}{lofoot}\BeginIndex{Cmd}{cofoot}\BeginIndex{Cmd}{rofoot}% +% +The page styles include three boxes either in head and foot. +The commands modifying the content of these boxes can be seen +in \autoref{fig:scrpage.leheadetall}. +Commands in the middle column modify the boxes content on both the odd +and even pages. + +\begin{figure} + \centering + \setlength{\unitlength}{1mm}\begin{picture}(100,65)(0,10)\small + \put(0,12){\dashbox{2}(40,56){even page}} + \put(60,12){\dashbox{2}(40,56){odd page}} + % items top left + \put(1,63){\framebox(8,4){~}} + \put(16,63){\framebox(8,4){~}} + \put(31,63){\framebox(8,4){~}} + % items top right + \put(61,63){\framebox(8,4){~}} + \put(76,63){\framebox(8,4){~}} + \put(91,63){\framebox(8,4){~}} + % items bottom left + \put(1,13){\framebox(8,4){~}} + \put(16,13){\framebox(8,4){~}} + \put(31,13){\framebox(8,4){~}} + % items bottom right + \put(61,13){\framebox(8,4){~}} + \put(76,13){\framebox(8,4){~}} + \put(91,13){\framebox(8,4){~}} + % commands and arrow + % for twoside + % + \put(50,65){\makebox(0,0){\Macro{ihead}}} + \put(44,65){\vector(-1,0){4}}\put(56,65){\vector(1,0){4}} + \put(50,58){\makebox(0,0){\Macro{chead}}} + \put(44,58){\line(-1,0){24}}\put(56,58){\line(1,0){24}} + \put(20,58){\vector(0,1){4}}\put(80,58){\vector(0,1){4}} + \put(50,51){\makebox(0,0){\Macro{ohead}}} + \put(44,51){\line(-1,0){40}}\put(56,51){\line(1,0){40}} + \put(4,51){\vector(0,1){11}}\put(96,51){\vector(0,1){11}} + % + \put(50,15){\makebox(0,0){\Macro{ifoot}}} + \put(56,15){\vector(1,0){4}}\put(44,15){\vector(-1,0){4}} + \put(50,22){\makebox(0,0){\Macro{cfoot}}} + \put(44,22){\line(-1,0){24}}\put(56,22){\line(1,0){24}} + \put(20,22){\vector(0,-1){4}}\put(80,22){\vector(0,-1){4}} + \put(50,29){\makebox(0,0){\Macro{ofoot}}} + \put(44,29){\line(-1,0){40}}\put(56,29){\line(1,0){40}} + \put(4,29){\vector(0,-1){11}}\put(96,29){\vector(0,-1){11}} + % commands for oneside + \put(5,69){\makebox(0,0)[b]{\Macro{lehead}}} + \put(20,69){\makebox(0,0)[b]{\Macro{cehead}}} + \put(35,69){\makebox(0,0)[b]{\Macro{rehead}}} + % + \put(65,69){\makebox(0,0)[b]{\Macro{lohead}}} + \put(80,69){\makebox(0,0)[b]{\Macro{cohead}}} + \put(95,69){\makebox(0,0)[b]{\Macro{rohead}}} + % + \put(5,11){\makebox(0,0)[t]{\Macro{lefoot}}} + \put(20,11){\makebox(0,0)[t]{\Macro{cefoot}}} + \put(35,11){\makebox(0,0)[t]{\Macro{refoot}}} + % + \put(65,11){\makebox(0,0)[t]{\Macro{lofoot}}} + \put(80,11){\makebox(0,0)[t]{\Macro{cofoot}}} + \put(95,11){\makebox(0,0)[t]{\Macro{rofoot}}} + \end{picture} + \caption[Commands for modification of + \Package{scrpage2}-pagestyles elements]% + {Commands for modification of pagestyles \PValue{scrheadings} and + \PValue{scrplain} and their association to head and foot elements} + \label{fig:scrpage.leheadetall} +\end{figure} + +\begin{Example} +If one wants the page number be placed in the middle of the +foot, then following can be used: +\begin{lstlisting} + \cfoot{\pagemark} +\end{lstlisting} +The next example shows how to place both running head and +page number in the head; the running head inside and the page number +outside. +\begin{lstlisting} + \ohead{\pagemark} + \ihead{\headmark} + \cfoot{} +\end{lstlisting} +The command \Macro{cfoot}\PParameter{} is only required in order +to empty the item in middle of the foot, +which normally contains the page number. +\end{Example} + +Using the commands which are associated with only one item +allows more advanced settings. + +\begin{Example} +Assuming one has the order to write an annual report for his +company, he could use commands like this: +\begin{lstlisting} + \ohead{\pagemark} + \rehead{Annual Report 2001} + \lohead{\headmark} + \cefoot{TheCompanyName Inc.} + \cofoot{Department: Development} +\end{lstlisting} +In order to keep in sync the data in the foot with the content +of the document, the foot has to be updated using \Macro{cofoot} +when a new department is discussed in the report. +\end{Example} + +As mentioned above, there is an \PValue{plain}-pagestyle which corresponds to +\PValue{scrheadings}. Since it should also be possible to adapt this style, +the commands support an optional argument. Thus the contents of the +appropriate field of the \PValue{plain}-pagestyle can be modified. + +\begin{Example} +The position of the page number for the pagestyle \PValue{scrheadings} +can be declared as follows: +\begin{lstlisting} + \cfoot[\pagemark]{} + \ohead[]{\pagemark} +\end{lstlisting} +When now the command \Macro{chapter}, after it has started a new page, +switches to the \PValue{plain}-pagestyle, then the page number +is centered in the foot. +\end{Example} +% +\EndIndex{Pagestyle}{scrheadings}\EndIndex{Pagestyle}{scrplain}% + +\begin{Declaration} + \Macro{clearscrheadings}\\ + \Macro{clearscrplain}\\ + \Macro{clearscrheadfoot} +\end{Declaration}% +\BeginIndex{Cmd}{clearscrheadings}% +\BeginIndex{Cmd}{clearscrplain}% +\BeginIndex{Cmd}{clearscrheadfoot}% +If one wants to redefine both the page style \PValue{scrheadings} +and the \PValue{plain} page style, frequently one must delete +some already occupied page items. Since one fills all items +rarely with new contents, in most cases several +instruction with empty parameters are necessary. +With the help of these three instructions the deletion is fast and +thoroughly possible. +While \Macro{clearscrheadings} only deletes all fields of the +page style \PValue{scrheadings} and \Macro{clearscrplain} deletes +all fields of the appropriate \PValue{plain} page style, +\Macro{clearscrheadfoot} sets all fields of both page styles on +empty contents. + +\begin{Example} + If one wants to reset the page style to the default \KOMAScript{} settings, + independent from the actual configuration, only these three commands are + sufficient. +\begin{lstlisting} + \clearscrheadfoot + \ohead{\headmark} + \ofoot[\pagemark]{\pagemark} +\end{lstlisting} + Without the commands \Macro{clearscrheadfoot}, \Macro{clearscrheadings} and + \Macro{clearscrplain} 6 commands with 9 empty arguments are required. +\begin{lstlisting} + \ihead[]{} + \chead[]{} + \ohead[]{\headmark} + \ifoot[]{} + \cfoot[]{} + \ofoot[\pagemark]{\pagemark} +\end{lstlisting} + Of course, assuming a special configuration some of them can + be dropped.% +\end{Example}% +% +\EndIndex{Cmd}{clearscrheadings}% +\EndIndex{Cmd}{clearscrplain}% +\EndIndex{Cmd}{clearscrheadfoot}% +% +\EndIndex{Cmd}{lehead}\EndIndex{Cmd}{cehead}\EndIndex{Cmd}{rehead}% +\EndIndex{Cmd}{ihead}\EndIndex{Cmd}{chead}\EndIndex{Cmd}{ohead}% +\EndIndex{Cmd}{lohead}\EndIndex{Cmd}{cohead}\EndIndex{Cmd}{rohead}% +\EndIndex{Cmd}{lefoot}\EndIndex{Cmd}{cefoot}\EndIndex{Cmd}{refoot}% +\EndIndex{Cmd}{ifoot}\EndIndex{Cmd}{cfoot}\EndIndex{Cmd}{rfoot}% +\EndIndex{Cmd}{lofoot}\EndIndex{Cmd}{cofoot}\EndIndex{Cmd}{rofoot}% + +In previous examples two commands already have been used, which +haven't been introduced yet. Now, the description of these +commands shall follow. + +\begin{Declaration} + \Macro{leftmark}\\ + \Macro{rightmark} +\end{Declaration}% +\BeginIndex{Cmd}{leftmark}\BeginIndex{Cmd}{rightmark}% +These two instructions make it possible to access the running headlines, +which are normally meant for the left or for the right page. These two +instruction are not made available by scrpage or scrpage2, but directly +by the \LaTeX{} kernel. If in this section running headline of the +left side or the right page are mentioned, +then the contents of \Macro{leftmark} or \Macro{rightmark} +is meant. +% +\EndIndex{Cmd}{leftmark}\EndIndex{Cmd}{rightmark}% + +\BeginIndex{Cmd}{headmark} +\begin{Declaration} +\Macro{headmark} +\end{Declaration}% +This command gives access to the content of running heads. +In contrast to \Macro{leftmark} and \Macro{rightmark}, one +need not regard the proper assignment to left or right page. +\EndIndex{Cmd}{headmark} + +\BeginIndex{Cmd}{pagemark} +\begin{Declaration} +\Macro{pagemark} +\end{Declaration}% +This command returns the formatted page number. The formatting can be +controlled by \Macro{pnumfont} introduced in +\autoref{sec:scrpage.basics.format}, \autopageref{desc:scrpage.macro.pnumfont} +or by \Macro{setkomafont} if a newer version \KOMAScript{} is used, see +\autoref{sec:maincls.font}. +% the last describtion \setkomafont ... is only fill-text +\EndIndex{Cmd}{pagemark} + +\BeginIndex{Cmd}{pagestyle}\BeginIndex{Pagestyle}{useheadings} +\begin{Declaration} +\Option{useheadings} +\end{Declaration}% +\phantomsection\label{desc:scrpage.pagestyle.useheadings}% +The package \Package{scrpage2} is meant primarily for the fact that the +supplied styles are used or own styles are defined. However it can be +necessary to shift back also to the style provided by the document class. It +would be obvious to do this with \Macro{pagestyle}\PParameter{headings}, but +this has however the disadvantage that commands \Macro{automark} and +\Macro{manualmark} discussed in the following do not function as expected. +For this reason one should shift back to the original styles using +\Macro{pagestyle}\PParameter{useheadings}. Such a switching has then no +effect on it whether one operates with manual or automatic running headlines. +% +\EndIndex{Cmd}{pagestyle}\EndIndex{Pagestyle}{useheadings} + +\subsection{Manual and Automatic Headings} +\label{sec:scrpage.basics.mark} +% \automark \manualmark +% +Usually there is a \emph{my}-version of the \PValue{headings}-style. If such +a style is active, then the running headlines are updated no longer +automatically. With \Package{scrpage2} another path is taken. Whether the +running headlines are living or not, determines the instructions +\Macro{automark} and \Macro{manualmark}. The default can be also already +influenced while the loading of the package with the options \Option{automark} +and \Option{manualmark}, see \autoref{sec:scrpage.basics.options}, +\autopageref{desc:scrpage.option.automark}. + +\BeginIndex{Cmd}{manualmark} +\begin{Declaration} +\Macro{manualmark} +\end{Declaration}% +As the name already clarifies, \Macro{manualmark} switches off the updating +of the running headlines. It is left to the user to provide for +updating or for contents of the running headlines. +For that purpose the instructions \Macro{markboth}\IndexCmd{markboth} +und \Macro{markright}\IndexCmd{markright} are available. +\EndIndex{Cmd}{manualmark} + +\BeginIndex{Cmd}{automark} +\begin{Declaration} + \Macro{automark}\OParameter{right page}\Parameter{left page} +\end{Declaration}% +The macro \Macro{automark} however activates the automatic updating. +For the two parameters the designations of the document level +are to be used, whose title in appropriate place is to appear. +Valid values for the parameters are: +\PValue{part}\ChangedAt{2.2}{\Package{scrpage2}}, \PValue{chapter}, +\PValue{section}, \PValue{subsection}, \PValue{subsubsection}, +\PValue{paragraph}, \PValue{subparagraph}. +For most of the classes usage of \PValue{part} will not produce +the expected results. So far only \KOMAScript\ classes from version~2.9s +up are known to support this value. + +The optional argument \PName{right page} is meant understandably only for +two-sided documents. +In the one-sided case you should normally not use it. +With the help of the option \Option{autooneside} one can also adjust +that the optional argument in one-sided mode is ignored automatically, +see \autoref{sec:scrpage.basics.options}, +\autopageref{desc:scrpage.option.autooneside}. +% +\begin{Example} +Assuming that the document uses a \emph{book} class, +which topmost section level is \emph{chapter}, +then after a preceding \Macro{manualmark} +\begin{lstlisting} + \automark[section]{chapter} +\end{lstlisting} +restores the original behaviour. +If one prefers one of the lower section levels in running head +following can be used. +\begin{lstlisting} + \automark[subsection]{section} +\end{lstlisting} +How useful the last declaration is, everybody has to decide +for oneself. +\end{Example} + +\begin{Explain} +The data of the headings is set by the command +\Macro{markboth}\IndexCmd{markboth} for the top-most +section levels, for the lower levels +\Macro{markright}\IndexCmd{markright} or +\Macro{markleft}\IndexCmd{markleft} are used. +These commands are called indirectly by the sectioning commands. +The macro \Macro{markleft} is provided by the package +\Package{scrpage2}. +Its definition is similar to \Macro{markright} originating from +the \LaTeX{} kernel. +Although \Macro{markleft} is not defined as an internal command, +the direct use is not recommended. +\end{Explain} +\EndIndex{Cmd}{automark} + + +\subsection{Formatting of Heading and Footing} +\label{sec:scrpage.basics.format} +% \headfont \pnumfont +% \setheadwidth \setfootwidth +% \set(head|foot)(top|sep|bot)line +In the previous paragraph it concerned mainly contentwise things. Is +not sufficient naturally, in order to satisfy the formative +ambitions. Therefore it is to turn in this paragraph exclusive therefore. +% +\BeginIndex{Cmd}{headfont}\BeginIndex{Cmd}{pnumfont} +\begin{Declaration} +\Macro{headfont}\\ +\Macro{pnumfont} +\end{Declaration}% +The command \Macro{headfont} contains the commands +which determine the formatting of head and foot lines. +The style of the page number defines the command +\Macro{pnumfont}. +\begin{Example} +If, for example, one wants the head and foot to be typeset in bold +sans-serif and the page number in a slanted style, then it can be +used the configuration: +\begin{lstlisting} + \renewcommand{\headfont}{\normalfont\sffamily\bfseries} + \renewcommand{\pnumfont}{\normalfont\rmfamily\slshape} +\end{lstlisting} +\end{Example} +\EndIndex{Cmd}{headfont}\EndIndex{Cmd}{pnumfont} +% +Since version 2.8p of the \KOMAScript{} classes a new +configuration scheme is implemented. +If \Package{scrpage2} is used together with these classes then +it is recommended to setup font attributes the way described +in \autoref{sec:maincls.font}. +\begin{Example} +This interfaces implements the command \Macro{setkomafont} +in order to configure the font attributes. +The previous definition can then be written as: +\begin{lstlisting} + \setkomafont{pagehead}\normalfont\sffamily\bfseries} + \setkomafont{pagenumber}{\normalfont\rmfamily\slshape} +\end{lstlisting} +\end{Example} + +\BeginIndex{Cmd}{setheadwidth}\BeginIndex{Cmd}{setfootwidth} +\begin{Declaration} +\Macro{setheadwidth}\OParameter{shift}\Parameter{width}\\ +\Macro{setfootwidth}\OParameter{shift}\Parameter{width} +\end{Declaration}% +Normally the widths of heading and footing line +correspond to the width of the text body. +The commands \Macro{setheadwidth} and \Macro{setfootwidth} enable the +user to adapt in a simple manner the widths to his needs. +The mandatory argument \PName{width} takes up the value for the width +of the page head or foot, +\PName{shift} is a longitudinal dimension for the shift of the +appropriate item toward the outside page edge. + +For the most common situations the mandatory argument \PName{width} +accepts the following symbolic values: +\begin{labeling}[\,--]{\PValue{textwithmarginpar}} +\item[\PValue{paper}] the width of the paper +\item[\PValue{page}] the width of the page +\item[\PValue{text}] the width of the text body +\item[\PValue{textwithmarginpar}] the width of the text body including margin. +\item[\PValue{head}] the current head width +\item[\PValue{foot}] the current foot width +\end{labeling} +The difference between \PValue{paper} and \PValue{page} is, that +\PValue{page} means the width of the paper less the binding correction. +This only applies if the package \Package{typearea}\IndexPackage{typearea} +is used (see \autoref{cha:typearea}). +Without \Package{typearea} both values are equal. + +\begin{Example} +The layout of the \emph{\LaTeX\,Companion}, the head-line projects +into the margin, can be obtained with: +\begin{lstlisting} + \setheadwidth[0pt]{textwithmarginpar} +\end{lstlisting} +% +and looks on an odd page like this: +% +\begin{XmpTopPage} + \XmpHeading{10,25}{85} + \thinlines\XmpRule{10,23}{85} + \XmpSetText[\XmpTopText]{10,21} + \XmpMarginNote{83,11.8} +\end{XmpTopPage} +% +If the foot-line shall have the same width and alignment, then +two ways are possible. The first simply repeats the settings +for the foot-line: +\begin{lstlisting} + \setfootwidth[0pt]{textwithmarginpar} +\end{lstlisting} +% +In the second way the symbolic value \PValue{head} is used, since the +head has already the desired settings. +\begin{lstlisting} + \setfootwidth[0pt]{head} +\end{lstlisting} +\end{Example} + +If no \PName{shift} is indicated, +i.e. without the optional argument, then +the heading or the foot appears symmetrically on the page arranged. +A value for the \PName{shift} is determined automatically, which +corresponds to the current page shape. +% +\begin{Example} +According to the previous example the optional argument is abandoned: +\begin{lstlisting} + \setheadwidth{textwithmarginpar} +\end{lstlisting} +% +and looks on an odd page like this: +% +\begin{XmpTopPage} + \XmpHeading{5,25}{85} + \thinlines\XmpRule{5,23}{85} + \XmpSetText[\XmpTopText]{10,21} + \XmpMarginNote{83,11.8} +\end{XmpTopPage} +\end{Example} + +As to be seen, the heading is now shifted inward, while the +heading width has not changed. +The shift is calculated in a way that the configuration of the typearea +become visible also here. +% +\EndIndex{Cmd}{setheadwidth}\EndIndex{Cmd}{setfootwidth} + +\BeginIndex{Cmd}{setheadtopline}\BeginIndex{Cmd}{setheadsepline} +\BeginIndex{Cmd}{setfootseptline}\BeginIndex{Cmd}{setfootbotline} +\begin{Declaration} +\Macro{setheadtopline}\OParameter{length}\Parameter{thickness}\OParameter{commands}\\ +\Macro{setheadsepline}\OParameter{length}\Parameter{thickness}\OParameter{commands}\\ +\Macro{setfootsepline}\OParameter{length}\Parameter{thickness}\OParameter{commands}\\ +\Macro{setfootbotline}\OParameter{length}\Parameter{thickness}\OParameter{commands} +\end{Declaration}% +According to the configuration of head and foot there are +commands to modify the lines above and below the head and foot. + +\begin{labeling}[\,--]{\Macro{setfootsepline}} +\item[\Macro{setheadtopline}] configures the line above the head +\item[\Macro{setheadsepline}] configures the line below the head +\item[\Macro{setfootsepline}] configures the line above the foot +\item[\Macro{setfootbotline}] configures the line below the foot +\end{labeling} + +The mandatory argument \PName{thickness} determines, +how strongly the line is drawn. +The optional argument \PName{length} accepts the same symbolic values as +\PName{width} with \Macro{setheadwidth}, as also a normal length expression. +As long as in the document \PName{length} value was not assigned to the +optional argument, the appropriate line length adapts automatically +the width of the heading or the foot. + +Use \PValue{auto} in the length argument to restore this +automatism for the length of a line. + +The\ChangedAt{2.2}{\Package{scrpage2}} +optional argument \PName{commands} may be used to specify additional commands +to be executed before the respective line is drawn. +For example such commands could be used for changing the +color\Index{header>color}\Index{footer>color}\Index{color>in + header}\Index{color>in footer} of that line. +When using a \KOMAScript\ class you could also use +\Macro{setkomafont}\IndexCmd{setkomafont} to specify commands +for one of the elements +\FontElement{headtopline}\IndexFontElement{headtopline}, +\FontElement{headsepline}\IndexFontElement{headsepline}, +\FontElement{footsepline}\IndexFontElement{footsepline}, +\FontElement{footbottomline}\IndexFontElement{footbottomline}, +\FontElement{footbotline}\IndexFontElement{footbotline}. +These could be extended by adding \Macro{addtokomafont}\IndexCmd{addtokomafont}. +See \autoref{sec:maincls.font} for details on the \Macro{setkomafont} and +\Macro{addkomafont} commands. + +\begin{Declaration} +\XMacro{setheadtopline}\OParameter{\upshape\PValue{auto}}\Parameter{\upshape\PValue{current}}\\ +\XMacro{setheadtopline}\OParameter{\upshape\PValue{auto}}\Parameter{}\\ +\XMacro{setheadtopline}\OParameter{\upshape\PValue{auto}}\Parameter{}\OParameter{} +\end{Declaration}% +The arguments shown here for the command \Macro{setheadtopline}, +are of course valid for the other three configuration commands, too. + +If the mandatory parameter has the value \PValue{current} or has been +left empty then the line height is not changed. +This may be used to modify the length of the line without changing its height. + +\PName{commands} is an optional argument, if omitted all command setting +will remain active that might have been specified before, while using +an empty \PName{commands} argument will revoke any previously valid +commands. + +\begin{Example} +If the head for example is to be contrasted by a strong line of 2\,pt +above and a normal line of 0.4\,pt between head and body, it can be +achieved with: +\begin{lstlisting} + \setheadtopline{2pt} + \setheadsepline{.4pt} +\end{lstlisting} +% +\begin{XmpTopPage} + \XmpHeading{10,25}{70} + \thinlines\XmpRule{10,23}{70} + \thicklines\XmpRule{10,28}{70} + \XmpSetText[\XmpTopText]{10,21} + \XmpMarginNote{83,11.8} +\end{XmpTopPage} + +To specify that this line is to be drawn also e.\,g. in red color you +would change the commands like this: +\begin{lstlisting} + \setheadtopline{2pt}[\color{red}] + \setheadsepline{.4pt}[\color{red}] +\end{lstlisting} +In this sample as well as in the following one line color is activated +by applying the syntax of the \Package{color}\IndexPackage{color} package, +so this package must be loaded of course. Since \Package{scrpage2} comes +without built-in color handling any package providing color support +may be used. + +\KOMAScript\ classes also support the following way of color specification: +\begin{lstlisting} + \setheadtopline{2pt} + \setheadsepline{.4pt} + \setkomafont{headtopline}[\color{red}] + \setkomafont{headsepline}[\color{red}] +\end{lstlisting} + +The automatic adjustment of the head and foot width is illustrated +in the following example: +\begin{lstlisting} + \setfootbotline{2pt} + \setfootsepline[text]{.4pt} + \setfootwidth[0pt]{textwithmarginpar} +\end{lstlisting} + +% \phantomsection for hyperref-\pageref-links jum-2001/11/24 +\phantomsection\label{page:scrpage.autoLineLength} +\begin{XmpBotPage} + \XmpHeading{10,18}{85} + \thinlines\XmpRule{17,21}{70} + \thicklines\XmpRule{10,16}{85} + \XmpSetText[\XmpBotText]{10,33} + \XmpMarginNote{83,24} +\end{XmpBotPage} +\end{Example} + +Now not everybody will like the alignment of the line above +the foot, instead one will expect the line left-aligned. +This can only be achieved with a global package option, which +will be described together with other package option +in the next \autoref{sec:scrpage.basics.options}. +\EndIndex{Cmd}{setheadtopline}\EndIndex{Cmd}{setheadsepline} +\EndIndex{Cmd}{setfootseptline}\EndIndex{Cmd}{setfootbotline} + +\subsection{Package Options}\label{sec:scrpage.basics.options} +% head(in|ex)clude foot(in|ex)clude --> typearea +% headtopline headsepline footbotline footsepline (plain...) +% komastyle standardstyle +% markuppercase markusecase +% automark manualmark + +\BeginIndex{Option}{headinclude}\BeginIndex{Option}{footinclude} +\BeginIndex{Option}{headexclude}\BeginIndex{Option}{footexclude} +\begin{Declaration} +\Option{headinclude}\\ +\Option{headexclude}\\ +\Option{footinclude}\\ +\Option{footexclude} +\end{Declaration}% +These options intend whether the page-header or that page-footing +are reckoned in with the page-body for the calculation of the type-area. +The adjustments necessary by the use of these parameters +are made by the package +\Package{typearea} (see \autoref{sec:typearea.options}), if this +package is loaded after \Package{scrpage2}. +Important is here that on use of a \KOMAScript{} class +these options must be indicated for the document class and not +for \Package{scrpage2}, in order to obtain an effect. +% +\EndIndex{Option}{headinclude}\EndIndex{Option}{footinclude} +\EndIndex{Option}{headexclude}\EndIndex{Option}{footexclude} + +\BeginIndex{Option}{headtopline}\BeginIndex{Option}{plainheadtopline} +\BeginIndex{Option}{headsepline}\BeginIndex{Option}{plainheadsepline} +\BeginIndex{Option}{footsepline}\BeginIndex{Option}{plainfootsepline} +\BeginIndex{Option}{footbotline}\BeginIndex{Option}{plainfootbotline} +\begin{Declaration} +\Option{headtopline} und \Option{plainheadtopline}\\ +\Option{headsepline} und \Option{plainheadsepline}\\ +\Option{footsepline} und \Option{plainfootsepline}\\ +\Option{footbotline} und \Option{plainfootbotline} +\end{Declaration}% +A basic adjustment for the lines under and over heading and footing +can be made with these options. +These adjustments are considered then as default to all +page styles defined with \Package{scrpage2}. +If one of these options is used, then a line thickness +is used by 0.4\,pt. + +Since there is an appropriate \PValue{plain}-style to the page style +\PValue{scrheadings}, with the \Option{plain\dots}-options also the +appropriate line of the plain style can be configured. +These \Option{plain}-options work however only, even if the +corresponding option without plain are activated. +Thus \Option{plainheadtopline} shows no effect without the +\Option{headtopline} option set. + +With these options it is to be noted that the appropriate page part, +heading or footing, is reckoned in with the text-area +for the calculation of the type-area in case a line has been activated. +This means, if with \Option{headsepline} the separation-line +between heading and text is activated, then the packge \Package{typearea} +calculates the type-area in such a way that the page-header +is part of the text block automatically. + +The conditions for the options of the preceding paragraph, apply also to +this automatism. That means that the package \Package{typearea} +must be loaded to scrpage2, or that on use of a \KOMAScript{} class, +the options \Option{headinclude} and \Option{footinclude} +must be set explicitly with \Macro{documentclass} in order to +transfer heading or footing line in the text-area. +% +\EndIndex{Option}{headtopline}\EndIndex{Option}{plainheadtopline} +\EndIndex{Option}{headsepline}\EndIndex{Option}{plainheadsepline} +\EndIndex{Option}{footsepline}\EndIndex{Option}{plainfootsepline} +\EndIndex{Option}{footbotline}\EndIndex{Option}{plainfootbotline} + +\BeginIndex{Option}{ilines}% +\BeginIndex{Option}{clines}% +\BeginIndex{Option}{olines}% +\Index{rule}\Index{line}% +\begin{Declaration} +\Option{ilines}\\ +\Option{clines}\\ +\Option{olines} +\end{Declaration}% +% +The definition of the line lengths can lead to an +undesired adjustment, since +the line is centered in the heading or footing area. +With the package options presented here, this specification can be +modified for all page styles defined with \Package{scrpage2}. +The option \Option{ilines} sets the adjustment in such a +way that the lines align to the inside edge. +The option \Option{clines} behaves like the standard adjustment and +\Option{olines} aligns at the outside edge. + +\begin{Example} + The next example illustrates the influence of the + option \Option{ilines}. Please compare to the example for + \Macro{setfootsepline} on \autopageref{page:scrpage.autoLineLength}. +\begin{lstlisting} + \usepackage[ilines]{scrpage2} + \setfootbotline{2pt} + \setfootsepline[text]{.4pt} + \setfootwidth[0pt]{textwithmarginpar} +\end{lstlisting} + + Only the use of the option \Option{ilines} leads to the different + result shown below: +\begin{XmpBotPage} + \XmpHeading{10,18}{85} + \thinlines\XmpRule{10,21}{70} + \thicklines\XmpRule{10,16}{85} + \XmpSetText[\XmpBotText]{10,33} + \XmpMarginNote{83,24} +\end{XmpBotPage} + In contrast to the default configuration the separation line + between text and foot is now left-aligned not centered.% +\end{Example}% +\EndIndex{Option}{ilines}\EndIndex{Option}{clines}\EndIndex{Option}{olines}% + +% \phantomsection for hyperref-\pageref-links jum-2001/11/24 +\phantomsection\label{page:scrpage.automark}% +\BeginIndex{Option}{automark}\BeginIndex{Option}{manualmark} +\begin{Declaration} +\Option{automark}\\ +\Option{manualmark} +\end{Declaration}% +These options set the adjustment at the beginning of the document +whether automatic updating of the running headlines takes place. +The option \Option{automark} switches the automatic updating on, +\Option{manualmark} deactivates it. +Without use of one of the two options the adjustment is preserved, +which was valid while the loading of the package. +% +\begin{Example} + One loads the package \Package{scrpage2} directly after the document class + \Class{scrreprt} without any package options. +\begin{lstlisting} + \documentclass{scrreprt} + \usepackage{scrpage2} +\end{lstlisting} + Since the default page style of \Class{scrreprt} is \PValue{plain}, + this page style is also active yet. + Futhermore \PValue{plain} means manual headings. + If one now activates the page style \PValue{scrheadings} with +\begin{lstlisting} + \pagestyle{scrheadings} +\end{lstlisting} + then the manual headings are always active. + + If one uses the document class \Class{scrbook} instead, then after: +\begin{lstlisting} + \documentclass{scrbook} + \usepackage{scrpage2} +\end{lstlisting} + the page style \PValue{headings} is active and the running headings + are updated automatically. + Switching to the page style \PValue{scrheadings} keeps this + setting present. + The marking-commands of \Class{scrbook} continue to be used. + + However, the use of +\begin{lstlisting} + \usepackage[automark]{scrpage2} +\end{lstlisting} + activates the automatic update of the running heading independent + from the used document class. + The option does not effect the used page style \PValue{plain} of + the class \Class{scrreprt}. + The headings are not visible until the page style has been changed to + \PValue{scrheadings}\IndexPagestyle{scrheadings}, + \PValue{useheadings} or another self-defined page style with headings.% +\end{Example}% +\EndIndex{Option}{automark}\EndIndex{Option}{manualmark}% + +\BeginIndex{Option}{autooneside} +\begin{Declaration} + \Option{autooneside} +\end{Declaration}% +This option ensures that the optional parameter of +\Macro{automark}\IndexCmd{automark} will be ignored automatically +in one-side mode. See the explanation of the command +\Macro{automark} in \autoref{sec:scrpage.basics.mark}, +\autopageref{desc:scrpage.macro.automark}. +\EndIndex{Option}{autooneside} + +\BeginIndex{Option}{komastyle}\BeginIndex{Option}{standardstyle} +\begin{Declaration} +\Option{komastyle}\\ +\Option{standardstyle} +\end{Declaration}% +These options determine the kind of the pre-defined page style +\PValue{scrheadings}. +The option \Option{komastyle} takes up a configuration like +the \KOMAScript{} classes. +This is the default for \KOMAScript{} classes and can this way +also be set for other classes. + +A configuration expected from the standard classes can be +defined using option \Option{standardstyle}. +Automatically the option \Option{markuppercase} will be +activated, but only if option \Option{markusedcase} is not given. +\EndIndex{Option}{komastyle}\EndIndex{Option}{standardstyle} + +\BeginIndex{Option}{markuppercase}\BeginIndex{Option}{markusedcase} +\begin{Declaration} +\Option{markuppercase}\\ +\Option{markusedcase} +\end{Declaration}% +The package \Package{scrpage2} has +to modify internal commands, which are used by document structuring +commands, in order to get the function of \Macro{automark} working. +Since some classes, in contrast to the \KOMAScript{} classes, +write the headings in uppercase letters, \Package{scrpage2} +has to know how the used document class represents the headings. + +Option \Option{markuppercase} shows \Package{scrpage2} that +the document class uses uppercase letters. +If the document class does not represent the headings in +uppercase letters the option \Option{markusedcase} should +be given. +These options are not suitable to force a representation, thus +unexpected effects may occur, if the given option does not match +the behaviour of the document class. +\EndIndex{Option}{markuppercase}\EndIndex{Option}{markusedcase} + +\begin{Declaration} + \Option{nouppercase} +\end{Declaration}% +\BeginIndex{Option}{nouppercase}% +In the previous paragraph about \Option{markuppercase} and +\Option{markusedcase} it has been already stated that some +document classes represent the running headings\Index{heading} in +uppercase letters using the commands +\Macro{MakeUppercase} or \Macro{uppercase}. +Setting the option \Option{nouppercase} allows to disable these +both commands. +The option \Option{nouppercase} only is valid as long page styles +defined by \Package{scrpage2} are used, including +\PValue{scrheadings} and its appropriate \PValue{plain} page style. + +The applicated method is very brutal and can cause that desired +changes of normal letters to uppercase letters +\Index{uppercase letters} do not occur. +Since these cases appear not frequently the option \Option{nouppercase} +is a useful solution. + +\begin{Example} +If a document uses the standard class \Class{book}\IndexClass{book}, +but the uppercase headings are not desired, then the preamble of +the document could start with: +\begin{lstlisting} + \documentclass{book} + \usepackage[nouppercase]{scrpage2} + \pagestyle{scrheadings} +\end{lstlisting} + The selection of the page style \PValue{scrheadings} is necessary, + since otherwise the page style \PValue{headings} is active, which + does not respect the settings made by option \Option{nouppercase}. +\end{Example} + +In some cases not only classes but also packages set the running +headings in uppercase letters. +Also in these cases the option \Option{nouppercase} should be able +to switch back to the normal non-uppercase headings. +\EndIndex{Option}{nouppercase} + +\section{Defining Own Page Styles}\label{sec:scrpage.UI} +% +% +\subsection{The Interface for Beginners}\label{sec:scrpage.UI.user} +% \deftripstyle +\BeginIndex{Cmd}{deftripstyle}\Index{page style} + +Now one would not always be bound only to the provided page styles, +but moreover there will be the wish to define own page styles. +Sometimes there will be a special need, since a specific +\emph{Corporate Identity} requires the declaration of own page styles. +The easiest way to deal with is: +\begin{Declaration} +\Macro{deftripstyle}\Parameter{name}% +\OParameter{LO}\OParameter{LI}% +\Parameter{HI}\Parameter{HC}\Parameter{HO}% +\Parameter{FI}\Parameter{FC}\Parameter{FO} +\end{Declaration}% +The parameters have the following meaning: +\begin{labeling}[\,--]{\PName{Name}} +\item[\PName{name}] the name of the page style, in order to activate them + using the command \Macro{pagestyle}\Parameter{name} +\item[\PName{LO}] the thickness of the outside lines, + i.e. the line above the head + and the line below the foot (optional) +\item[\PName{LI}] the thickness of the separation lines, + i.e. the line below the head + and the line above the foot (optional) +\item[\PName{HI}] contents of the inside box in the page head for two-side + layout or left for one-side layout +\item[\PName{HC}] contents of the centered box in the page head +\item[\PName{HO}] contents of the outside box in the page head for two-side + layout or right for one-side layout +\item[\PName{FI}] contents of the inside box in the page foot for two-side + layout or left for one-side layout +\item[\PName{FC}] contents of the centered box in the page foot +\item[\PName{FO}] contents of the outside box in the page foot for two-side + layout or right for one-side layout +\end{labeling} + +The command \Macro{deftripstyle} surely represents the simplest +possibility of defining page styles. +Unfortunately also restrictions are connected with since in a +page range with one via deftripstyle defined page style +no modification of the lines above and below heading and footing +can take place. + +\begin{Example} +Assuming a two-side layout, where the running headings are placed inside. +Furthermore the document title, here "`Report"`, shall be placed outside +in the head, the page number is centered in the foot. +\begin{lstlisting} + \deftripstyle{TheReport}% + {\headmark}{}{Report}% + {}{\pagemark}{} +\end{lstlisting} + +Shall moreover the lines above the head and below the foot be +drawn with a thickness of 2\,pt and the text body be separated +>from head and foot with 0.4\,pt lines, then the definition has to +be extended. +\begin{lstlisting} + \deftripstyle{TheReport}[2pt][.4pt]% + {\headmark}{}{Report}% + {}{\pagemark}{} +\end{lstlisting} +% +\typeout{^^J--- Ignore underfull and overfull \string\hbox:} +\begin{center}\setlength{\unitlength}{1mm}\begin{picture}(100,50)\scriptsize +\thinlines +\put(5,0){\line(0,1){50}} +\put(55,0){\line(0,1){50}} +\put(5,50){\line(1,0){40}} +\put(55,50){\line(1,0){40}} +% +\thicklines +\put(45,0){\line(0,1){50}} +\put(95,0){\line(0,1){50}} +\put(5,0,){\line(1,0){40}} +\put(55,0){\line(1,0){40}} +% +\XmpHeading[Report\hfill 2. The Eye]{11,46}{30} +\XmpHeading[2.1 Retina\hfill Report]{59,46}{30} +\XmpHeading[\hfill 14\hfill]{11,6.5}{30} +\XmpHeading[\hfill 15\hfill]{59,6.5}{30} +\put(11,43){\makebox(0,0)[tl]{\parbox{30mm}{\tiny% + \textbf{2.1 Retina}\\ + \XmpText[49]}}} +\put(59,43){\makebox(0,0)[tl]{\parbox{30mm}{\tiny% + \XmpText[51]}}} +% +\thinlines +\XmpRule{11,44.5}{30}\XmpRule{59,44.5}{30} +\XmpRule{11,8}{30}\XmpRule{59,8}{30} +\linethickness{1pt} +\XmpRule{11,48}{30}\XmpRule{59,48}{30} +\XmpRule{11,5}{30}\XmpRule{59,5}{30} +\end{picture}\end{center} +\typeout{^^J--- Don't ignore underfull and overfull \string\hbox:^^J} +\end{Example} +\EndIndex{Cmd}{deftripstyle} + +\subsection{The Interface for Experts}\label{sec:scrpage.UI.expert} +% \defpagestyle \newpagestyle \providepagestyle \renewpagestyle +\BeginIndex{Cmd}{defpagestyle}\BeginIndex{Cmd}{newpagestyle} +\BeginIndex{Cmd}{renewpagestyle}\BeginIndex{Cmd}{providepagestyle} +\Index{page style} +Simple page styles, how they can be defined with \Macro{deftripstyle}, +are rare according to experience. +Either a professor requires that the thesis looks in +such a way like its own, and who wants to contradict +it seriously, or a company would like that the half +financial department emerges in the page footing. +No problem, the solution is: +% +\begin{Declaration} +\Macro{defpagestyle}\Parameter{name}\Parameter{head-definition}\Parameter{foot-definition}\\ +\Macro{newpagestyle}\Parameter{name}\Parameter{head-definition}\Parameter{foot-definition}\\ +\Macro{renewpagestyle}\Parameter{name}\Parameter{head-definition}\Parameter{foot-definition}\\ +\Macro{providepagestyle}\Parameter{name}\Parameter{head-definition}\Parameter{foot-definition} +\end{Declaration}% +These four commands give full access to the capabilities of +\Package{scrpage2} according to define page styles. +Their structure is indentical, they differ only the manner of working. + +\begin{labeling}[\,--]{\Macro{providepagestyle}} +\item[\Macro{defpagestyle}] defines always a new pagestyle. +If a page style with this name already exists it will be overwritten. +\item[\Macro{newpagestyle}] defines a new pagestyle. +If a page style with this name already exists a error message will be given. +\item[\Macro{renewpagestyle}] redefines a pagestyle. +If apage style with this name does not exist a error message will be given. +\item[\Macro{providepagestyle}] defines a new pagestyle, +but only if there is no page style with that name already present. +\end{labeling} + +The syntax of the four commands is explained on command +\Macro{defpagestyle} examplary. +\begin{labeling}[\,--]{\PName{head definition}} +\item[\PName{name}] the name of the page style for + \Macro{pagestyle}\Parameter{name} +\item[\PName{head-definition}] the declaration of the heading consisting + of five element; elements in round parenthesis are optional:\\ +\AParameter{ALL,ALT}\Parameter{EP}\Parameter{OP}\Parameter{OS}\AParameter{BLL,BLT} +\item[\PName{foot-definition}] the declaration of the footing consisting + of five element; elements in round parenthesis are optional:\\ +\AParameter{ALL,ALT}\Parameter{EP}\Parameter{OP}\Parameter{OS}\AParameter{BLL,BLT} +\end{labeling} + +It can be seen, that head and foot declaration are identical. +The parameters have the following meaning: +\begin{labeling}[\,--]{\PName{OLD}} +\item[\PName{ALL}] above line length: (head = outside, foot = separation line) +\item[\PName{ALT}] above line thickness +\item[\PName{EP}] definition for \emph{even} pages +\item[\PName{OP}] definition for \emph{odd} pages +\item[\PName{OS}] definition for \emph{one-side} layout +\item[\PName{BLL}] below line length: (head = separation line, foot = outside) +\item[\PName{BLT}] below line thickness +\end{labeling} +If the optional line-parameters are omitted, then the line behaviour keeps +configurable by the commands introduced in +\autoref{sec:scrpage.basics.format}, +\autopageref{desc:scrpage.macro.setheadtopline}. + +The three elements \PName{EP}, \PName{OP} and \PName{OS} are boxes with +the width of page head or foot respectively. +The definition occur on the left side in the box, thus the space between +two text elements has to be stretched using \Macro{hfill}, in order to +write the first text element on the left edge \emph{and} the second text +element on the right edge. +% +\begin{lstlisting} + {\headmark\hfill\pagemark} +\end{lstlisting} + +If one would like a third text-element centered in the box, then an +extended definition must be used. +The commands \Macro{rlap} and \Macro{llap} simply write the given +arguments, but for \LaTeX{} they take no horizontal space. +Only this way the middle text is really centered. +% +\begin{lstlisting} + {\rlap{\headmark}\hfill centered text\hfill\llap{\pagemark}} +\end{lstlisting} + +This and more examples of the expert's interface and other commands +provided by \Package{scpage2} follow now in the final example. + +\begin{Example} +This examples uses the document class \Class{scrbook}, which +means that the default page layout is two-side. +While the loading of the package \Package{scrpage2} the +options \Option{automark} and \Option{headsepline} are +given. +The first switches on the automatic update of running +headings, the second determines that a separation line between +head and text-body is drawn in the \PValue{scrheadings} page style. + +\begin{lstlisting} + \documentclass{scrbook} + \usepackage[automark,headsepline]{scrpage2} +\end{lstlisting} + +The expert's interface is used to define two page styles. +The page style \PValue{withoutLines} does not define any +line parameters. +The second page style \PValue{withLines} defines +a line thicknes of 1\,pt for the line above the head +and 0\,pt for the separation-line between head and text. + +\begin{lstlisting} + \defpagestyle{withoutLines}{% + {Example\hfill\headmark}{\headmark\hfill without lines} + {\rlap{Example}\hfill\headmark\hfill% + \llap{without lines}} + }{% + {\pagemark\hfill}{\hfill\pagemark} + {\hfill\pagemark\hfill} + } +\end{lstlisting} + +\begin{lstlisting} + \defpagestyle{withLines}{% + (\textwidth,1pt) + {with lines\hfill\headmark}{\headmark\hfill with lines} + {\rlap{\KOMAScript}\hfill \headmark\hfill% + \llap{with lines}} + (0pt,0pt) + }{% + (\textwidth,.4pt) + {\pagemark\hfill}{\hfill\pagemark} + {\hfill\pagemark\hfill} + (\textwidth,1pt) + } +\end{lstlisting} + +At the document's begin the page style \PValue{scrheadings} +is choosen. +The command \Macro{chapter} starts a new chapter and sets +automatically the page style for this page to \PValue{plain}. + +The command \Macro{chead} shows how running headings can +be represented even on a \PValue{plain} page. +Running headings on chapter start-pages are not usual, +since in this case the page looses its emphasis-character. +Basically it is more important to show that a new +chapter starts here than that a section of this page has +a special title. + +\begin{Explain}% not important, only to enhance the paragraph breaking +Instead of \Macro{leftmark} one would expect +the use of \Macro{rightmark} in the parameter +of \Macro{chead}, since the chapter starts on an even +page. But, because of internal \LaTeX{} definitions, +this does not work. It only returns an empty string. +\end{Explain} +\begin{lstlisting} + \begin{document} + \pagestyle{scrheadings} + \chapter{Thermodynamics} + + \chead[\leftmark]{} + + \section{Main Laws} + Every system has an extensive condition unit called + Energy. In a closed system the energy is constant. +\end{lstlisting} + +\begin{XmpTopPage} + \XmpHeading[\hfill\textsl{1. Thermodynamics}\hfill]{10,27}{70} + \put(10,17){\normalsize\textbf{\sffamily 1.Thermodynamics}} + \put(10,12){\textbf{\sffamily 1.1 Main Laws}} + \XmpSetText[% + Every System has an extensive condition unit]{10,9} +\end{XmpTopPage} + +After starting a new page the page style \PValue{scrheadings} +is active and thus the separation line below the heading is +visible. +\begin{lstlisting} + There is a condition unit of a system, called entropy, + which temporal alteration consits of entropy stream + and entropy generation. +\end{lstlisting} +\begin{XmpTopPage} + \XmpHeading[\textsl{1. Thermodynamics}\hfill]{20,27}{70} + \thinlines\XmpRule{20,25}{70} + \XmpSetText[% + There is a condition unit of a system, called entropy, + which temporal alteration consits of entropy stream + and entropy generation.]{20,20} +\end{XmpTopPage} + +After switching to the next page, the automatic update of the +running headings is disabled using \Macro{manualmark}. +The page style \PValue{withoutLines} becomes active. +Since no line parameters are given in the definition of this +page style, the default configuration is used, which draws +a separation line between head and text-body. +\begin{XmpTopPage} + \XmpHeading[\slshape Energy Conversion\hfill without lines]{10,27}{70} + \thinlines\XmpRule{10,25}{70} + \XmpSetText[% + \textbf{\sffamily 1.2 Exergy and Anergy}\\ + While the transition of a system to an equilibrium state + with its environment the maximum work gainable is called + exergy.]{10,21} +\end{XmpTopPage} + +\begin{lstlisting} + \manualmark + \pagestyle{withoutLines} + \section{Exergy and Anergy}\markright{Energy Conversion} + While the transition of a system to an equilibrium state + with its environment the maximum work gainable is called + exergy. +\end{lstlisting} + +At the next page of the document the page style \PValue{withLines} +is activated. +The line settings of its definition are taken in account and the +lines are drawn accordingly. +\begin{lstlisting} + \pagestyle{mitLinien} + \renewcommand{\headfont}{\itshape\bfseries} + The portion of an energy not conversable in exergie + is named anergy \Var{B}. + \[ B = U + T (S_1 - S_u) - p (V_1 - V_u)\] + \end{document} +\end{lstlisting} +\begin{XmpTopPage} + \XmpHeading[\itshape\bfseries with lines\hfill 1. Thermodynamics]{20,27}{70} + \thicklines\XmpRule{20,29}{70} + \XmpSetText[% + The portion of an energy not conversable in exergie + is named anergy $B$. + \[ B = U + T (S_1 - S_u) - p (V_1 - V_u)\] ]{20,20} +\end{XmpTopPage} +\end{Example} +\EndIndex{Cmd}{defpagestyle}\EndIndex{Cmd}{newpagestyle} +\EndIndex{Cmd}{renewpagestyle}\EndIndex{Cmd}{providepagestyle} + +\subsection{Managing Page Styles}\label{sec:scrpage.UI.cfgFile} +% scrpage.cfg +\BeginIndex{File}{scrpage.cfg} +Before long the work with different page styles will establish a +common set of employed page styles, depending on taste and tasks. +In order to make the management of page styles easier, +\Package{scrpage2} reads after initialisation the file \File{scrpage.cfg}. +This file can contain a set of user-defined page styles, which +many projects can share. +\EndIndex{File}{scrpage.cfg} +\EndIndex{Package}{scrpage2} +%%% Local Variables: +%%% mode: latex +%%% TeX-master: ../guide" +%%% End: diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/typearea.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/typearea.tex new file mode 100644 index 00000000000..c7dc6e55109 --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/typearea.tex @@ -0,0 +1,1149 @@ +% ====================================================================== +% typearea.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3b of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3b or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in manifest.txt. +% ---------------------------------------------------------------------- +% typearea.tex +% Copyright (c) Markus Kohm, 2001-2006 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3b, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3b ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Chapter about typearea of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel über typearea in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ====================================================================== + +\ProvidesFile{typearea.tex}[2005/11/26 KOMA-Script guide (chapter: typearea)] +% Date of translated german file: 2005-03-17 + +% TODO: Translation of the changed equation array at 2.1, "Fundamentals of +% Page Layout". + +\chapter{Construction of the Page Layout with \Package{typearea}} +\labelbase{typearea} + +\section{Fundamentals of Page Layout} + +\begin{Explain} + If you look at a single page of a book or other prints, you will see + that it consists of top, foot, left and right margins, a (running) + head area, the text block and a (running) foot area. Looking + closer, there is space between the head area and the text block + and between the text block and the foot area. The relations + between these areas are called \emph{page layout}. + + The literature offers and discusses different algorithms and + heuristic approaches for constructing a good page layout. Often, + they are mentioning an approach which involves diagonals and their + intersections. The result is a page where the text block + proportions relate to the proportions of the \emph{page}. In a + single-sided document, the left and the right margin should have + equal widths. + The relation of the upper margin to the lower margin should + be 1\(:\)2. In a double-sided document (e.\,g. a book) however, + the inner margin (the margin at the spine) should be the same as + each of the two outer margins. + + In the previous paragraph, we mentioned and emphasized the + \emph{page}. Erroneously, often it is thought that the format of + the page would be the format of the paper. However, if you look at + a bound document, it is obvious that part of the paper vanishes in + the binding and is not part of the visible page. But the format of + the paper is not important for the layout of a page, it is the + impression of the visible page to the reader. Therefore, it is + clear that the calculation if the page layout must account for the + ``lost'' paper in the binding and add this amount to the width of + the inner margin. This is called \emph{binding correction}. + + The binding correction depends on the process of actually + producing the document and thus can not be calculated in general. + Every production process needs its own parameter. In professional + binding, this parameter is not too important since the printing is + done on oversized paper which is then cropped to the right size. + The cropping is done in a way so that the relations for the + visible double-sided page are as explained above. + + Now we know about the relation of the individual parts of a page. + However, we do not know about the width and the height of the + text block yet. Once we know one of these values, we can calculate + all the other values from the paper format and the page format or + the binding correction. + \begin{eqnarray*} + \Var{textblock~heigth} : \Var{textblock~width} &=& + \Var{page~height} : \Var{page~width}\\ +% + \Var{page~width} &=& \Var{paper~width} - \Var{binding~correction}\\ +% + \Var{top~margin} + \Var{foot~margin} &=& + \Var{page~height} - \Var{textblock~height} \\ +% + \Var{top~margin} : \Var{foot~margin} &=& 1 : 2 \\ +% + \Var{left~margin} : \Var{right~margin} &=& 1 : 1 \\ +% + \Var{half~inner~margin} &=& + \frac{1}{2}\Var{outer~margin} + \Var{binding~correction} \\ + \end{eqnarray*} + The values \Var{left~margin} and \Var{right~margin} are only + existent in a single-sided document while \Var{inner~margin} and + \Var{outer~margin} are only existent in a double-sided document. In + these equations, we work with \Var{half~inner~margin} since the full + inner margin belongs to a double-page. Thus, one page has half of + the inner margin. + + The question of the width of the textblock is also discussed in + the literature. The optimum width depends on several factors: + \begin{itemize} + \item size, width, type of the used font % !!! + \item line spacing % !!! + \item word length + \item available room + \end{itemize} + The importance of the font becomes clear once you think about + serifs. Serifs are fine lines % !!! + finishing off the letters. Letters whose main strokes are running + orthogonal to the text line are disturbing the flow more than they + are leading the eye along the line. These letters have serifs at + the end of the vertical strokes, however, so the horizontal serifs + lead the eye horizontally too. In addition, it helps the eye to + find the beginning of the next line. Thus, the line length for a + serif font can be slightly longer than for a non-serif font. + + In \LaTeX{}, the line spacing is about 20\% of the font + size. With commands like \Macro{linespread} or, better, packages like + \Package{setspace} the line spacing can be changed. A wider line + spacing helps the eye to follow the line. A very wide line + spacing, on the other hand, disturbs reading because the eye has + to move a wide distance between lines. Also, the reader gets + uncomfortable because of the visible stripe effect. The uniform + gray value of the page gets spoiled. Still, with a wider line + spacing, the lines can be longer. + + Literature gives different values for good line lengths, depending + on the author. To some extent, this is due to the native language + of the author. Since the eye jumps from word to word, short words + make this task easier. Not considering language and font, a line + length of 60 to 70 letters including spaces and + punctuation is a usable compromise. This requires well-chosen line + spacing, but \LaTeX{}'s default is usually good enough. + + Before looking at the actual construction of the page layout, + there are some minor things to know. \LaTeX{} doesn't start the + first line of the text block at the upper edge of the text block, + but with a defined distance. Also, \LaTeX{} knows the commands + \Macro{raggedbottom} and \Macro{flushbottom}. \Macro{raggedbottom} + specifies that the last line of a page should be positioned + wherever it was calculated. This means that the position of this + line can be different on each page, up to the height of one line. + In double-sided documents this is usually unwanted. + \Macro{flushbottom} makes sure that the last line is always at the + lower edge of the text block. To achieve this, \LaTeX{} sometimes + needs to stretch vertical glue more than allowed. Paragraph skip + is such a stretchable, vertical glue, even when set to zero. In + order not to stretch the paragraph skip on normal pages where it + is the only stretchable glue, the height of the text block should + be a multiple of the height of the text line, including the + distance from the upper edge of the text block to the first line. + + This concludes the introduction to page layout as handled by + \KOMAScript. Now, we can begin with the actual construction.\par +\end{Explain} + + +\section{Page Layout Construction by Dividing} +\label{sec:typearea.divConstruction} + +\begin{Explain} + The easiest way to make sure that the text area has the same + ratios as the page is as follows: First, you subtract the + binding correction \Var{BCOR} from the inner edge of the paper. + Then you divide the rest of the page vertically into + \Var{DIV} rows of equal height. Next, you divide the page + horizontally into the same number (\Var{DIV}) of columns. Then you + take the uppermost row as the upper margin and the two lowermost + rows as the lower margin. If you print double-sided, you also take + the innermost column as the inner margin and the two outermost + columns as the outer margin. Then, you add the binding correction + \Var{BCOR} to the inner margin. The remainder of + the page is the text area. The width and the height of the text area result + automatically from the number of rows and columns \Var{DIV}. Since + the margins always need three rows/columns, \Var{DIV} must + be necessarily greater than three. + + In \KOMAScript, this kind of construction is implemented in the + \Package{typearea} package. For A4 paper, \Var{DIV} is predefined + according to the font size (see \autoref{tab:typearea.div}). If there is + no binding correction (\(\Var{BCOR} = 0\Unit{pt}\)), the results + roughly match the values of \autoref{tab:typearea.typearea}. + + In addition to the predefined values, you can specify \Var{BCOR} + and \Var{DIV} as options when loading the package (see + \autoref{sec:typearea.options}). There is also a command to + explicitly calculate the type area by providing these values as + parameters (also see \autoref{sec:typearea.options}). + + The \Package{typearea} package can determine the optimal value + of \Var{DIV} for the font used automatically. Again, see + \autoref{sec:typearea.options}.\par +\end{Explain} + + +\section{Page Layout Construction by Drawing a Circle} +\label{sec:typearea.circleConstruction} + +\begin{Explain} + In addition to the construction method previously described, a somewhat + more classical method can be found in the literature. Aim of this method is + not only identical ratios in the page proportions, but it is considered + optimal when the height of the text block is the same a the width of the + page. The exact method is described in \cite{JTsch87}. + + A disadvantage of this late dark age method is that the width of + the text area is not dependent on the font anymore. Thus, one + doesn't choose the text area to match the font, but the author or + typesetter has to choose the font according to the text area. This + can be considered a ``must''. + + In the \Package{typearea} package this construction is changed + slightly. By using a special (normally senseless) \Var{DIV} value + or a special package option, a \Var{DIV} value is chosen to match + the perfect values as closely as possible. See also + \autoref{sec:typearea.options}.\par +\end{Explain} + + +\section{Options and Macros to Influence the Page Layout} +\label{sec:typearea.options} + +The package \Package{typearea} offers two different user interfaces to +influence type area construction. The first method is to load the +package with options. For information on how to load packages and to +give package options, please refer to the \LaTeX{} literature, e.g. +\cite{lshort} and \cite{latex:usrguide}, or the examples given here. +Since the \Package{typearea} package is loaded automatically when +using the \KOMAScript{} main classes, the package options can be given +as class options (see \autoref{sec:maincls.options}). + +\begin{Declaration} + \Option{BCOR}\PName{Correction} +\end{Declaration}% +\BeginIndex{Option}{BCOR}% +With the \Option{BCOR}\PName{Correction} option you specify the +absolute value of the binding correction, i.e., the width of the area +that is used for the binding, thus ``lost'' from the paper width. + +This value will be used in the layout calculation automatically and +will be added to the inner or left margin respectively. You can use +any valid \TeX{} unit for \PName{Correction}. + +\begin{Example} + Assume you want to produce a financial report, which is to be printed on A4 + paper and bound in a folder. The rim of the folder covers + \(7{,}5\Unit{mm}\). Since the report is thin, only an additional + \(0{,}75\Unit{mm}\) are lost by folding when leafing through the pages. You + would use the following commands: +\begin{lstlisting} + \documentclass[a4paper]{report} + \usepackage[BCOR8.25mm]{typearea} +\end{lstlisting} + or, using a \KOMAScript-class: +\begin{lstlisting} + \documentclass[a4paper,BCOR8.25mm]{scrreprt} +\end{lstlisting} +\end{Example} + +Please note: if you use one of the \KOMAScript{} classes, this option +must be given as a class option. If you use another class, this only +works if the class has explicit support for typearea. So when using +the standard classes, you need to give the option when you load +\Package{typearea}. You can also use \Macro{PassOptionsToPackage} +(see \cite{latex:clsguide}) before you are loading +\Package{typearea}, this always works. +% +\EndIndex{Option}{BCOR} + +\begin{Declaration} + \Option{DIV}\PName{Factor} +\end{Declaration}% +\BeginIndex{Option}{DIV}% +\Option{DIV}\PName{Factor} defines the number of stripes the page +is split into when the page layout is constructed. The exact +method can be found in \autoref{sec:typearea.divConstruction}, +but the most important thing is: the higher \PName{Factor}, the +bigger the resulting text area, and the smaller the margins. For +\PName{Factor}, you can use any integer value larger than 4. +Please note that depending on your other options a very high value +for \PName{Factor} can result in problems: For instance, in +extreme cases, the running title might be outside the actual page +area. So if you use \Option{DIV}\PName{Factor}, it is your own +responsibility to choose a typographically acceptable line length +and to pay attention to the other parameters. + +In \autoref{tab:typearea.typearea} you'll find some page layout +values for the page format A4 without binding correction, with +varying \Var{DIV} factors. Font size is not taken into account. + +\begin{table} + \centering + \caption{Page layout values depending on \Var{DIV} for A4} + \begin{tabular}{ccccc} + \toprule + & \multicolumn{2}{c|}{Text area} & \multicolumn{2}{c}{Margins}\\ + \emph{DIV}& Width [mm] & Height [mm] & upper [mm] & inner [mm] \\ + \midrule + 6 & 105,00 & 148,50 & 49,50 & 35,00 \\ + 7 & 120,00 & 169,71 & 42,43 & 30,00 \\ + 8 & 131,25 & 185,63 & 37,13 & 26,25 \\ + 9 & 140,00 & 198,00 & 33,00 & 23,33 \\ + 10 & 147,00 & 207,90 & 29,70 & 21,00 \\ + 11 & 152,73 & 216,00 & 27,00 & 19,09 \\ + 12 & 157,50 & 222,75 & 24,75 & 17,50 \\ + 13 & 161,54 & 228,46 & 22,85 & 16,15 \\ + 14 & 165,00 & 233,36 & 21,21 & 15,00 \\ + 15 & 168,00 & 237,60 & 19,80 & 14,00 \\ + \bottomrule + \end{tabular} + \label{tab:typearea.typearea} +\end{table} + +\begin{Example} + Imagine you are writing meeting minutes with the + \Class{protocol}\footnote{The class \Class{protocol} is + hypothetical. This manual considers the ideal case where you have + a special class for every use.}-class. The whole thing is supposed to + be double sided. In your company, the Bookman font in 12\Unit{pt} + is used. This standard PostScript font is activated in {\LaTeX} + with the command \Macro{usepackage}\Parameter{bookman}. Bookman runs very + wide, that means, the characters are wide in relation to its + height. Because of that, the default for the \Var{DIV} value in + \Package{typearea} is too small for you. Instead of 12, you want 15. + The minutes will not be bound but punched and filed into a folder, + so you don't need any binding correction. Thus, you write: +\begin{lstlisting} + \documentclass[a4paper,twoside]{protocol} + \usepackage{bookman} + \usepackage[DIV15]{typearea} +\end{lstlisting} + After you are done you get told that the minutes are collected and + bound as a book by the end of the year. The binding is done as a + simple glue binding in a copy shop, since it is done just for ISO\,9000 + anyway and nobody will ever bother to look at the minutes again. For + binding you need \(12\Unit{mm}\) in average. So you change the options + for \Package{typearea} accordingly and use the ISO\,9000 document class: +\begin{lstlisting} + \documentclass[a4paper,twoside]{iso9000p} + \usepackage{bookman} + \usepackage[DIV15,BCOR12mm]{typearea} +\end{lstlisting} + Of course, you can also use a \KOMAScript{} class here: +\begin{lstlisting} + \documentclass[twoside,DIV15,BCOR12mm]{scrartcl} + \usepackage{bookman} +\end{lstlisting} + The option \Option{a4paper} was omitted using class \Class{scrartcl}, + because it's the default at all \KOMAScript{} classes. +\end{Example} +% +Please note: if you use one of the \KOMAScript{} classes, \Option{BCOR} must +be given as a class option. If you use another class, this only works if the +class has explicit support for typearea. So when using the standard classes, +you need to give \Option{BCOR} when you load \Package{typearea}. You can use +\Macro{PassOptionsToPackage} (see \cite{latex:clsguide}) too before you are +loading \Package{typearea}, this always works. +% +\EndIndex{Option}{DIV} + +\begin{Declaration} + \Option{DIVcalc}\\ + \Option{DIVclassic} +\end{Declaration}% +\BeginIndex{Option}{DIVcalc}% +\BeginIndex{Option}{DIVclassic}% +As mentioned in \autoref{sec:typearea.divConstruction}, only +paper format A4 has fixed defaults for the \Var{DIV} value. These +are listed in \autoref{tab:typearea.div}. If you choose a +different paper format, \Package{typearea} calculates a good +\Var{DIV} value itself. Of course, you can also have it calculate +that for A4: use \Option{DIVcalc} instead of +\Option{DIV}\PName{Factor}. This works for all other paper formats +as well. If you want to use the automatic calculation, this is +even very useful, since you can then override the defaults that +are given in a configuration file (see +\autoref{sec:typearea.cfg}) with this option. + +\begin{table} + \centering + \caption{\label{tab:typearea.div}\PName{DIV} defaults for A4} + \begin{tabular}{lccc} + \toprule + Base font size: & 10\Unit{pt} & 11\Unit{pt} & 12\Unit{pt} \\ + \Var{DIV}: & 8 & 10 & 12 \\ + \bottomrule + \end{tabular} +\end{table} + +The classic construction method as described in +\autoref{sec:typearea.circleConstruction} can also be selected +(with the difference that a good \Var{DIV} value is chosen). In +this case, instead of \Option{DIV}\PName{Factor} or +\Option{DIVcalc}, use the option \Option{DIVclassic}. + +\begin{Example} + In the example for \Option{DIV}\PName{Factor} which used the + Bookman font, there was the problem that we needed a \Var{DIV} + value which suited the font better. As a modification of the first + example, this calculation can be left to \Package{typearea}: +\begin{lstlisting} + \documentclass[a4paper,twoside]{protocol} + \usepackage{bookman} + \usepackage[DIVcalc]{typearea} +\end{lstlisting} +\end{Example} + + +\begin{Declaration} + \Macro{typearea}\OParameter{BCOR}\Parameter{DIV} +\end{Declaration}% +\BeginIndex{Cmd}{typearea}% +If you followed the examples till here, you'll ask yourself how +one can make the calculation of \Var{DIV} depend on the selected +font when one uses one of the \KOMAScript{} classes. Then the +options to \Package{typearea} would have to be made before loading +the e.g. \Package{bookman} package. In this case, +\Package{typearea} could only calculate the page layout for the +standard font, but not for the Bookman font which is really +used. After evaluating the options, \Package{typearea} +calculates the page layout by using the +\Macro{typearea}\OParameter{BCOR}\Parameter{DIV} command. Here, +the chosen \Var{BCOR} value is given as an optional parameter and +\Var{DIV} as a parameter. With the option \Option{DIVcalc}, the +(normally invalid) value~\(1\) is given; with the option +\Option{DIVclassic} the (normally invalid) value~\(3\). You can +also call \Macro{typearea} explicitly in the preamble. + +\begin{Example} + Let us assume again that we want to calculate a good page layout for the + Bookman font. We also want to use a \KOMAScript{} class. This is possible + using the \Macro{typearea}-command with \Option{DIVcalc} = 1 as + \PName{DIV}-parameter: +\begin{lstlisting} + \documentclass[BCOR12mm,DIVcalc,twoside]{scrartcl} + \usepackage{bookman} + \typearea[12mm]{1}% same as class options above +\end{lstlisting} + Again option \Option{a4paper} was not used explicitly, because it's the + default of the \KOMAScript{} class \Class{scrartcl}. +\end{Example} + +It would be ridiculous if one had to use the +\Macro{typearea}-command with some pseudo-values, while the +\Option{DIV}-Option allows the use of \Option{DIVcalc} and +\Option{DIVclassic}. Thus the \Macro{typearea} also accepts +symbolic values for the parameter \PName{DIV} are listed at +\autoref{tab:symbolicDIV}. + +\begin{table} + \caption[{Available symbolic \PName{DIV} values for + \Macro{typearea}}]{Available symbolic \PName{DIV} values for + \Macro{typearea}\OParameter{BCOR}\Parameter{DIV}} + \label{tab:symbolicDIV} + \begin{desctabular} + \pventry{calc}{re-calculate page layout and determine \Var{DIV}.}% + \pventry{classic}{re-calculate page layout using the classical method + (circle).}% + \pventry{current}{re-calculate page layout with current value of + \Var{DIV}.}% + \pventry{default}{re-calculate page layout with default values for the + current page- and font size. If no default values exist, apply + \PValue{calc}.}% + \pventry{last}{re-calculate page layout using the same + \PName{DIV}-argument, which was set last time.}% + \end{desctabular} +\end{table} + +The \Macro{typearea} also understands the symbolic values for the parameter +\PName{BCOR} shown in \autoref{tab:symbolicBCOR}. Thus it is not neccesary to +re-enter the current value. + +\begin{table} + \caption[{Available symbolic \PName{BCOR} values for + \Macro{typearea}}]{Available symbolic \PName{BCOR} values for + \Macro{typearea}\OParameter{BCOR}\Parameter{DIV}} + \label{tab:symbolicBCOR} + \begin{desctabular} + \pventry{current}{Re-calculate page layout using the current value for + \Var{BCOR}.}% + \end{desctabular} +\end{table} + +\begin{Example} + Thus calculating a good page layout for the Bookman font and a + \KOMAScript-class is easy when we use symbolic parameter values for + \PName{BCOR} and \PName{DIV}: +\begin{lstlisting} + \documentclass[BCOR12mm,DIVcalc,twoside]{scrartcl} + \usepackage{bookman} + \typearea[current]{calc} +\end{lstlisting} + If we want to use a fixed value for \Var{DIV} we can use either: +\begin{lstlisting} + \documentclass[BCOR12mm,DIV11,twoside]{scrartcl} + \usepackage{bookman} + \typearea[current]{last} +\end{lstlisting} + or the old method: +\begin{lstlisting} + \documentclass[a4paper,twoside]{scrartcl} + \usepackage{bookman} + \typearea[12mm]{11} +\end{lstlisting} + In the end it is a matter of personal taste which of these solution you want + to use. +\end{Example} + +Frequently the re-calculation of the page layout is necessary +because the line spacing was changed. Since it is essential that +an integer number of lines fit into the text area, any change in +line spacing requires a re-calculation of page layout. + +\begin{Example} + Assume you want to write a thesis and university regulations require a font + size of 10\Unit{pt} with one and a half line spacing. {\LaTeX} uses by + default a line spacing of 2\Unit{pt} at font size 10\Unit{pt}. Thus a + stretch-factor of 1.25 is required. Let us also assume that binding + correction needs 12\Unit{mm}. Then you might use: +\begin{lstlisting} + \documentclass[10pt,twoside,% + BCOR12mm,DIVcalc]{scrreprt} + \linespread{1.25} + \typearea[current]{last} +\end{lstlisting}\IndexCmd{linespread} + \Macro{typearea} automaticly calls \Macro{normalsize}. So it is not + neccessary to use \Macro{selectfont} after \Macro{linespread} to activate + the changed line spacing before re-calclulation of the page layout. + + The same example again, using the \Package{setspace} package (see + \cite{package:setspace}): +\begin{lstlisting} + \documentclass[10pt,twoside,% + BCOR12mm,DIVcalc]{scrreprt} + \usepackage{setspace} + \onehalfspacing + \typearea[current]{last} +\end{lstlisting} + Using the \Package{setspace}-package simplifies things, because you no + longer need to calculate the correct stretch-factor, and you no longer need + the \Macro{selectfont} macro. + + In this context it is appropriate to point out that the line spacing should + be reset for the title page. A complete example therefore would look like + this: +\begin{lstlisting} + \documentclass[10pt,twoside,% + BCOR12mm,DIVcalc]{scrreprt} + \usepackage{setspace} + \onehalfspacing + \typearea[current]{last} + \begin{document} + \title{Title} + \author{Markus Kohm} + \begin{spacing}{1} + \maketitle + \tableofcontents + \end{spacing} + \chapter{Ok} + \end{document} +\end{lstlisting} + See also the notes in \autoref{sec:typearea.tips}. +\end{Example} + +\begin{Explain} + The command \Macro{typearea} is currently defined in such a way that it is + possible to change the page layout in the middle of a text. This however + makes assumptions about the inner workings of the \LaTeX-kernel and changes + some internal values and definitions of that kernel. There is some + probability, but no guarantee that this will also work in future versions of + \LaTeX. It must be assumed that this method will not give correct results + in \LaTeX3. However, as author of \KOMAScript{} I expect considerable + incompatibilities when we change to \LaTeX3.% +\end{Explain}% +\EndIndex{Cmd}{typearea}% +\EndIndex{Option}{DIVclassic}% +\EndIndex{Option}{DIVcalc}% + +\begin{Explain} +\begin{Declaration} + \Option{headinclude}\\ + \Option{headexclude}\\ + \Option{footinclude}\\ + \Option{footexclude} +\end{Declaration}% +\BeginIndex{Option}{headinclude}% +\BeginIndex{Option}{headexclude}% +\BeginIndex{Option}{footinclude}% +\BeginIndex{Option}{footexclude}% +So far we have discussed how the page layout is calculated and what the ratios +are between the borders and between borders and text area. However, one +important question has not been answered: What constitutes the borders? This +question appears trivial: Borders are those parts on the right, left, top and +bottom which remain empty. But this is only half of it. Borders are not always +empty. There could be marginals, for example (for the +\Macro{marginpar} command refer to \cite{lshort} or +\autoref{sec:maincls.marginNotes}). + +One could also ask, whether headers and footers belong to the upper +and lower borders or to the text. This can not be answered +unambiguously. Of course an empty footer or header belong to the +borders, since they can not be distinguished from the rest of the +border. A header or footer, that contains only a page number, will +optically appear more like border. For the optical appearance it is +not important whether headers or footers are easily recognised as such +during reading. Important is only, how a well filled page appears +when viewed out of focus. You could use the glasses of your +far-sighted grand parents, or, lacking those, adjust your vision to +infinity and look at the page with one eye only. Those wearing +spectacles will find this much easier, of course. If the footer +contains not only the page number, but other material like a copyright +notice, it will optically appear more like a part of the text body. +This needs to be taken into account when calculating text layout. + +For the header this is even more complicated. The header frequently +contains running heads \Index[indexmain]{running head}. In case of +running heads with long chapter and section titles the header lines +will be very long and appear to be part of the text body. This effect +becomes even more significant when the header contains not only the +chapter or section title but also the page number. With material on +the right and left side, the header will no longer appear as empty +border. If the length of the titles varies, the header may appear as +border on one page and as text on another. However, this pages should +not be treated differently under any circumstances, as this would lead +to jumping headers. In this case it is probably best to count the +header with the text. + +The decision is easy when text and header or footer are separated +from the text body by a line. This will give a ``closed'' +appearance and header or footer become part of the text body. +Remember: It is irrelevant that the line improves the optical +separation of text and header or footer, important is only the +appearance when viewed out of focus. +\end{Explain} + +The \Package{typearea}-package can not make the decision whether +or not to count headers and footers to the text body or the +border. Options \Option{headinclude} and \Option{footinclude} +cause the header or footer to be counted as text, options +\Option{headexclude} and \Option{footexclude} cause them to be +counted as border. If you are unsure about the correct setting, +re-read above explanations. Default is usually +\Option{headexclude} and \Option{footexclude}., but this can +change depending on \KOMAScript-class and \KOMAScript-packages used +(see \autoref{sec:maincls.options} and \autoref{cha:scrpage}). +% +\EndIndex{Option}{headinclude}% +\EndIndex{Option}{headexclude}% +\EndIndex{Option}{footinclude}% +\EndIndex{Option}{footexclude}% + +\begin{Declaration} + \Option{mpinclude}\\ + \Option{mpexclude} +\end{Declaration} +\BeginIndex{Option}{mpinclude}% +\BeginIndex{Option}{mpexclude}% +Besides\ChangedAt{v2.8q}{\Class{scrbook}\and \Class{scrreprt}\and + \Class{scrartcl}} documents where the head and foot is part of the text +area, there are also documents where the margin-note area must be counted to +the text body as well. The option \Option{mpinclude} does exactly this. The +effect is that one width-unit of the text-body is taken for the margin-note +area. Using option \Option{mpexclude}, the default setting, then the normal +margin is used for the margin-note area. The width of that area is one or one +and a half width-unit, depending on whether one-side or two-side page layout +has been chosen. The option \Option{mpinclude} is mainly for experts and so +not recommended. + +\begin{Explain} + In the cases where the option \Option{mpinclude} is used often a wider + margin-note area is required. In many cases not the whole margin-note width + should be part of the text area, for example if the margin is used for + quotations. Such quotations are typeset as ragged text with the flushed + side where the text body is. Since ragged text gives no homogeneous optical + impression the long lines can reach right into the normal margin. This can + be done using option \Option{mpinclude} and by an enlargement of length + \Length{marginparwidth} after the type-area has been setup. The length can + be easily enlarged with the command \Macro{addtolength}. How much the the + length has to be enlarged depends on the special situation and it requires + some flair. Therefore the option is primarily for experts. Of course one + can setup the margin-width to reach a third right into the normal margin, + for example using + \begin{lstlisting} + \setlength{\marginparwidth}{1.5\marginparwidth} + \end{lstlisting} + gives the desired result. + + Currently there is no option to enlarge the margin by a given amount. The + only solution is that the option \Option{mpinclude} is not used, but after + the type-area has been calculated one reduces the width of the text-body + \Length{textwidth} and enlarges the margin width \Length{marginparwidth} by + the same amount. Unfortunately, this can not be attended when automatic + calculation of the \PName{DIV} value is used. In contrast + \Option{DIVcalc}\IndexOption{DIVcalc} heeds \Option{mpinclude}. +\end{Explain} +% +\EndIndex{Option}{mpinclude}% +\EndIndex{Option}{mpexclude}% + + +\begin{Declaration} + \PName{Value}\Option{headlines} +\end{Declaration}% +\BeginIndex{Option}{headlines}% +We have seen how to calculate the text layout and how to specify +whether header and footer are part of the text body or the +borders. However, we still have to specify the height in +particular of the header. This is achieved with the option +\Option{headlines}, which is preceded by the number of lines in +the header. \Package{typearea} uses a default of 1.25. This is a +compromise, large enough for underlined headers (see +\autoref{sec:maincls.options}) and small enough that the +relative weight of the top border is not affected to much when +the header is not underlined. Thus in most cases you may leave +\Option{headlines} at its default value and adapt it only in +special cases. + +\begin{Example} + Assume that you want to use a header with two lines. Normally this would + result in a "`\texttt{overfull} \Macro{vbox}"' warning for each page. To + prevent this from hapening, the \Package{typearea}-package is told to + calculate an appropriate page layout: +\begin{lstlisting} + \documentclass[a4paper]{article} + \usepackage[2.1headlines]{typearea} +\end{lstlisting} + If you use a \KOMAScript{} class this must be given as a class option: +\begin{lstlisting} + \documentclass[a4paper,2.1headlines]{scrartcl} +\end{lstlisting} + A tool that can be used to define the contents of a header with two + lines is described in \autoref{cha:scrpage}. +\end{Example} + +If you use a \KOMAScript{} class, this option must be given as +class option. With other classes this works only, if these classes explicitly +supports \Package{typearea}. If you use the standard classes, the option must +be given when loading \Package{typearea}. \Macro{PassOptionsToPackage} will +work in both cases (see also \cite{latex:clsguide}). +% +\EndIndex{Option}{headlines} + +\begin{Declaration} + \Macro{areaset}\OParameter{BCOR}\Parameter{Width}\Parameter{Height} +\end{Declaration}% +\BeginIndex{Cmd}{areaset}% +So far we have seen how a good or even very good page layout is +calculated and how the \Package{typearea}-package can support these +calculations, giving you at the same time the freedom to adapt the +layout to your needs. However, there are cases where the text body +has to fit exactly into specified dimensions. At the same time the +borders should be well spaced and a binding correction should be +possible. The \Package{typearea}-package offers the command +\Macro{areaset} for this purpose. As parameters this command accepts +the binding correction and the width and height of the text body. +Width and position of the borders will then be calculated +automatically, taking account of the options \Option{headinclude}, +\Option{headexclude}, \Option{footinclude} and \Option{footexclude} +where needed. + +\begin{Example} + Assume a text, printed on A4 paper, should have a width of exactly 60 + characters of typewriter-font and a height of exactly 30 lines. This could + be achieved as follows: +\begin{lstlisting} + \documentclass[a4paper,11pt]{article} + \usepackage{typearea} + \newlength{\CharsLX}% Width of 60 characters + \newlength{\LinesXXX}% Height of 30 lines + \settowidth{\CharsLX}{\texttt{1234567890}} + \setlength{\CharsLX}{6\CharsLX} + \setlength{\LinesXXX}{\topskip} + \addtolength{\LinesXXX}{30\baselineskip} + \areaset{\CharsLX}{\LinesXXX} +\end{lstlisting} + +\item A poetry book with a square text body with a page length of + 15\Unit{cm} and a binding correction of 1\Unit{cm} could be + achieved like this: +\begin{lstlisting} + \documentclass{gedichte} + \usepackage{typearea} + \areaset[1cm]{15cm}{15cm} +\end{lstlisting} +\end{Example} +\EndIndex{Cmd}{areaset} + +The \Package{typearea} package was not made to set up predefined margin +values. If you have to do so you may use package \Package{geometry} (see +\cite{package:geometry}). + + +\section{Options and Macros for Paper Format Selection} +\label{sec:typearea.paperTypes} + +\Index{paper format}% +The \LaTeX standard classes support the options \Option{a4paper}, +\Option{a5paper}, \Option{b5paper}, \Option{letterpaper}, +\Option{legalpaper} and \Option{executivepaper}. +\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} \\ + \Macro{isopaper}\OParameter{series}\Parameter{number} +\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} +\BeginIndex{Cmd}{isopaper}% +The three American formats are supported by \Package{typearea} +in the same way. In addition, all ISO-A-, ISO-B-, ISO-C- and +ISO-D-formats are supported and derived from their basic sizes A0, B0, +C0 and D0. They may be selected directly with options +\Option{a0paper}, \Option{a1paper} and so on. Landscape orientation is +selected with the \Option{landscape}-option just as in the standard +classes. + +Alternatively the paper size can be adjusted with the macro +\Macro{isopaper}. This however required re-calculation of the +text layout with \Macro{typearea} or \Macro{areaset}. I do not +recommend the use of \Macro{isopaper}. + +\begin{Example} + Assume you want to print on ISO-A8 file cards in landscape + orientation. Borders should be very small, no header or footer + will be used. +\begin{lstlisting} + \documentclass{article} + \usepackage[headexclude,footexclude, + a8paper,landscape]{typearea} + \areaset{7cm}{5cm} + \pagestyle{empty} + \begin{document} + \section*{Paper Size Options} + letterpaper, legalpaper, executivepaper, a0paper, + a1paper \dots\ b0paper, b1paper \dots\ c0paper, + c1paper \dots\ d0paper, d1paper \dots + \end{document} +\end{lstlisting} +\end{Example} + +All \Option{a\Var{X}paper}-, \Option{b\Var{X}paper}-, +\Option{c\Var{X}paper}- and \Option{d\Var{X}paper}-options need +to be given as class options when \KOMAScript{} classes are used. +For other classes this works only if they support +\Package{typearea}. For the standard \LaTeX-classes these options +need to be declared when \Package{typearea} is loaded. +\Macro{PassOptionsToPackage} (see \cite{latex:clsguide}) works in +both cases. +% +\EndIndex{Option}{letterpaper} +\EndIndex{Option}{legalpaper} +\EndIndex{Option}{executivepaper} +\EndIndex{Option}{a0paper} +\EndIndex{Option}{b0paper} +\EndIndex{Option}{c0paper} +\EndIndex{Option}{d0paper} +\EndIndex{Option}{landscape} +\EndIndex{Cmd}{isopaper} + +\begin{Declaration} + \Macro{paperwidth}\\ + \Macro{paperheight} +\end{Declaration}% +\BeginIndex{Cmd}{paperwidth}% +\BeginIndex{Cmd}{paperheight}% +Particularly exotic paper sizes can be defined using the lengths +\Macro{paperwidth} and \Macro{paperheight}. +This requires the re-calculation of the text layout using the +commands \Macro{typearea} or \Macro{areaset}. +% +\begin{Example} +Assume you want to print on endless paper with the dimensions +\(8\frac{1}{4}\Unit{inch} \times 12\Unit{inch}\). This format is +not directly supported by \Package{typearea}. Thus you have to +define it befor calculating the text layout: +\begin{lstlisting} + \documentclass{article} + \usepackage{typearea} + \setlength{\paperwidth}{8.25in} + \setlength{\paperheight}{12in} + \typearea{1} +\end{lstlisting} +\end{Example} +\EndIndex{Cmd}{paperheight} +\EndIndex{Cmd}{paperwidth} + +\begin{Explain}% +\begin{Declaration} + \Option{dvips}\\ + \Option{pdftex}\\ + \Option{pagesize} +\end{Declaration}% +\BeginIndex{Option}{dvips}% +\BeginIndex{Option}{pdftex}% +\BeginIndex{Option}{pagesize}% + These mechanisms will set internal \LaTeX{} dimensions to values that + header, text body and footer can be printed on paper of the given + size. However, the specifications of the DVI-format\index{DVI} do + not allow the paper format to be specified. If DVI is translated + directly into a low level printer language like PCL (Hewlett-Packard + printers) or Esc-P (Epson), this is usually not important, because + in all these cases the origin is the upper left corner. If however + the DVI-source is translated into languages like + PostScript\Index{PostScript} or PDF\Index{PDF}, that have an origin + in a different position and also contain the paper size explicitly, + the required information is not available in the DVI-file. To solve + this problem the DVI-driver will use the default paper size, which + the user may set per option or in the \TeX-source. In case of the + DVI-driver \File{dvips} this can be done with a + \Macro{special}-command. For {pdf\TeX} two dimensions are set + instead. +\end{Explain} +The option \Option{dvips} writes the paper size as a \Macro{special} +into the DVI-file. This macro is then evaluated by \File{dvips}. +\Option{pdftex} on the other hand writes the paper size into the +pdf\TeX{} page register at the beginning of the document, so that the +correct paper size is used when the resulting PDF-file is viewed or +printed. The option \Option{pagesize} is more flexible and uses the +correct mechanism if either a PDF- or DVI-file is produced. +% +\begin{Example} + Assume you want to create a DVI-file from a document and an + online version in PDF. Then the preamble could look like this: +\begin{lstlisting} + \documentclass{article} + \usepackage[a4paper,pagesize]{typearea} +\end{lstlisting} + If the file is run through {pdf\TeX} then the lengths + \Macro{pdfpagewidth} and \Macro{pdfpageheight} will be set to + appropriate values. If on the other hand you create a DVI-file -- + either with {\LaTeX} or {pdf\LaTeX} -- a \Macro{special} will be + written to the beginning of the file. +\end{Example}\IndexCmd{pdfpagewidth}\IndexCmd{pdfpageheight} +\EndIndex{Option}{dvips}% +\EndIndex{Option}{pdftex}% +\EndIndex{Option}{pagesize}% + +\section{Odd Bits without Direct Relevance to Text Layout} +\label{sec:typearea.else} + +\begin{Declaration} + \Macro{ifpdfoutput}\Parameter{then}\Parameter{else} +\end{Declaration}% +\BeginIndex{Cmd}{ifpdfoutput}% +Sometimes it would be nice if certain things would be done +differently in a file, depending on output format. \TeX{} normally +uses DVI as output format. With {pdf\TeX} however we now have the +option to create PDF-files directly. The command +\Macro{ifpdfoutput} is a branching command. If PDF-output is +active, the \PName{then} branch will be executed, if PDF-output +is inactive or {pdf\TeX} is not used at all, the +\PName{else} branch. +\begin{Example} + As you may know {pdf\LaTeX} will produce a DVI-file instead of a + PDF-file, if the counter \Macro{pdfoutput} is assigned the value 0. + Only is the counter is assigned a value different from 0 output is + switched to PDF. Since \Macro{pdfoutput} is unknown when {\LaTeX} is + used instead of {pdf\LaTeX}, \Macro{pdfoutput} can not be set to 0 + generally, if you want DVI-output. A simple solution to this problem + is to execute following command: +\begin{lstlisting} + \ifpdfoutput{\pdfoutput=0}{} +\end{lstlisting} + This only works after loading \Package{typearea} package. If you + want the line above to be executed after af package, which set's + \Macro{pdfoutput} to 1 whenever the counter exist, you may combine + it with the \Macro{AfterPackage}\IndexCmd{AfterPackage} command + from \Package{scrlfile} package (see \autoref{cha:scrlfile}). +\end{Example}\IndexCmd{pdfoutput} +\EndIndex{Cmd}{ifpdfoutput} + +\section{Local Defaults in the File \File{typearea.cfg}} +\label{sec:typearea.cfg} +Even before the packet options are used, \Package{typearea} will check +for the presence of the file +\File{typearea.cfg}\IndexFile{typearea.cfg} and, if found, load it. +Thus it is possble to define in this file the parameters for +additional paper sizes. + +\begin{Declaration} + \Macro{SetDIVList}\Parameter{List} +\end{Declaration}% +\BeginIndex{Cmd}{SetDIVList}% +\begin{Explain}% + The \Macro{SetDIVList}-parameter was also intended for use in this + file. Befor the option \Option{DIVcalc} was introduced this was the + only possibility to define \Var{DIV}-values for different paper and + font sizes. This list consists of a number of values in curly + parenthesis. The leftmost value is the font size, \(10\Unit{pt}\), + the next for \(11\Unit{pt}\), the third for \(12\Unit{pt}\) and so + on. If you don't use \Macro{SetDIVList} the predefined + \Macro{SetDIVList}% + \PParameter{\PParameter{8}\PParameter{10}\PParameter{12}} will be + used. If no default value is given for a particular font size, + \(10\) will be used. +\end{Explain} + +This command should no longer be used, automatic calculation of text +layout is recommended instead (see +\autoref{sec:typearea.options}). +% +\EndIndex{Cmd}{SetDIVList} + +\section{Hints} +\label{sec:typearea.tips} +\begin{Explain} + In particular for thesis many rules exist that violate even the most + elementary rules of typography. The reasons for such rules include + typographical incompetence of those making them, but also the fact that they + were originally meant for mechanical typewriters. With a typewriter or a + primitive text processor dating back to the early ´80s it is not possible to + produce typographically correct output without extreme effort. Thus rules + were created that appeared to be achievable and still allowed easy + correction. To avoid short lines made worse by ragged margins the borders + were kept narrow, and the line spacing increased to 1.5 for corrections. In + a single spaced document even correction signs would have been difficult to + add. When computers became widely available for text processing, some + students tried to use a particularly ``nice'' font to make their work look + better than it really was. They forgot however that such fonts are often + more difficult to read and therefore unsuitable for this purpose. Thus two + bread-and-butter fonts became widely used which neither fit together nor are + particularly suitable for the job. In particular Times is a relatively + narrow font which was developed at the beginning of the 20$^{th}$ century + for the narrow columns of British newspapers. Modern versions usually are + somewhat improved. But still the Times font required in many rules does not + really fit to the border sizes prescribed. + + {\LaTeX} already uses sufficient line spacing, and the borders are wide + enough for corrections. Thus a page will look generous, even when quite full + of text. With \Package{typearea} this is even more true, especially if the + calculation of line length is left to \Package{typearea} too. For fonts that + are sensitive to long lines the line length can easily be reduced. + + To some extend the questionable rules are difficult to implement in + {\LaTeX}. A fixed number of characters per line can be kept only when a + non-proportional font is used. There are very few good non-proportional + fonts around. Hardly a text typeset in this way looks really good. In many + cases font designers try to increase the serifes on the `i' or `l' to + compensate for the different character width. This can not work and results + in a fragmented and agitated looking text. If you use {\LaTeX} for your + paper, some of these rules have to be either ignored or at least interpreted + generously. For example you may interpret ``60 characters per line'' not as + a fixed, but average or maximal value.% +\end{Explain} + +As executed, record regulations are usually meant to obtaining an +useful result even if the author does not know, what to be consider +thereby. Usefully means frequently: readable and correctable. In my +opinion the type-area of a text set with \LaTeX{} and the +\Package{typearea} package becomes well done from the beginning fair. +Thus if you are confronted with regulations, which deviate obviously +substantially from it, then I recommend to submit a text single dump +to the responsible person and inquire whether it is permitted to +supply the work despite the deviations in this form. If necessary the +type-area can be moderately adapted by modification of option +\Option{DIV}. I advise against use of \Macro{areaset} for this +purpose however. At worst you may use geometry package (see +\cite{package:geometry}), which is not part of \KOMAScript{}, or +change the type-area parameters of \LaTeX. You may find the values +determined by \Package{typearea} at the log file of your document. +Thus moderate adjustments should be possible. However absolutely make +sure that the proportions of the text area correspond approximate with +those the page with consideration of the binding correction. + +If it should be absolutely necessary to set the text +one-and-a-half-lined then you should not redefine +\Macro{baselinestretch} under any circumstances. Although this +procedure is recommended very frequently, it is however obsolet since +the introduction of \LaTeXe{} in 1994. Use at least the instruction +\Macro{linespread}. I recommend package \Package{setspace} (see +\cite{package:setspace}), which is not part of \KOMAScript. Also you +should use \Package{typearea} to calculate a new type-area after the +conversion of the line space. However you should switch back to the +normal line space for the title, better also for the +directories\,---\,as well as the bibliography and the index. The +\Package{setspace} package offers for this a special environment and +own instructions. + +The \Package{typearea} package even with option \Option{DIVcalc} +calculates a very generous text area. Many conservative typographers +will state that the resulting line length is still excessive. The +calculated \Var{DIV}-value may be found in the \File{log} file to the +respective document. Thus you can select a smaller value easily after +the first \LaTeX{} run. + +The question is asked to me not rarely, why I actually talk section by +section about a type-area calculation, while it would be very many +simpler, only to give you a package, with which one can adjust the +edges as during a text processing. Often also one states, such a +package would be anyway the better solution, since everyone knew, how +good edges are to be selected, and the edges from {\KOMAScript} anyway +would not be well. I take the liberty of translating a suitable +quotation from \cite{TYPO:ErsteHilfe}. You may find the original +german words at the german scrguide. + +\begin{quote} + \phantomsection\label{sec:typearea.tips.cite}% + \textit{The making by oneself is long usually, the results are often + doubtful, because layman typographers do not see, what is correct + and cannot not know, on what it important. Thus one gets + accustomed to false and bad typography.} [\dots] \textit{Now the + objection could come, typography is nevertheless taste thing. If + it concerned decoration, perhaps one could let apply the argument, + since it concerns however primarily information with typography, + errors cannot only disturb, but even cause damage.} +\end{quote} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "../guide" +%%% End: |