diff options
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/scrlayer-en.tex')
-rw-r--r-- | macros/latex/contrib/koma-script/doc/scrlayer-en.tex | 1605 |
1 files changed, 1605 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/doc/scrlayer-en.tex b/macros/latex/contrib/koma-script/doc/scrlayer-en.tex new file mode 100644 index 0000000000..94e9846397 --- /dev/null +++ b/macros/latex/contrib/koma-script/doc/scrlayer-en.tex @@ -0,0 +1,1605 @@ +% ====================================================================== +% scrlayer-en.tex +% Copyright (c) Markus Kohm, 2013-2022 +% +% 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.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c 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.md. +% ====================================================================== +% +% Chapter about scrlayer of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrlayer-en.tex} + [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $ + KOMA-Script guide (chapter:scrlayer)] + +\translator{Markus Kohm\and Karl Hagen} + +\chapter[{Defining Layers and Page Styles with \Package{scrlayer}}] + {Defining\ChangedAt{v3.12}{\Package{scrlayer}} Layers and Page Styles with + \Package{scrlayer}} +\labelbase{scrlayer} + +\BeginIndexGroup +\BeginIndex{Package}{scrlayer}% +\BeginIndex{}{layer}% +Most users of graphics software are already familiar with the layer model for +a page. Such a model is rather alien to \LaTeX{} itself, but some packages, +like \Package{eso-pic} or \Package{textpos}, provide a kind of +background or foreground layer. \Package{scrlayer} is another package that +provides such background and foreground layers, but unlike the packages +mentioned above, these layers are part of the page style. As a result, you can +switch between different layers simply by switching the page style. + +To do so, the package also supports a low-level interface for defining page +styles that are based on a stack or list of layers, for adding layers to such +a layer stack, either at the top or the bottom, or before or after a specific +layer, and for removing individual layers and duplicates from a stack. In a +nutshell, the page style interface of \Package{scrlayer} provides commands to +define page styles based on a stack of layers and to manage those stacks. + +Nevertheless, using the layers directly is recommended for advanced users +only. Interfaces for beginners and average users are provided by additional +packages that in turn load \Package{scrlayer}. See +\autoref{cha:scrlayer-scrpage} in \autoref{part:forAuthors} of this +\iffree{manual}{book}. + + +\LoadCommonFile{options} % \section{Early or Late Selection of Options} + +\section{Generic Information} +\seclabel{generic.information} + +The package needs some generic information about the class being used. Class +authors can help \Package{scrlayer} by providing the appropriate information. +Otherwise the package will try to determine this information for itself. This +works, for example, for the standard and the \KOMAScript{} classes. It may +work with other classes, or it may fail in whole or in part. + +This section describes some of the information that class authors can provide. +Normally, users should not have to worry about it. + +\begin{Declaration} + \Macro{if@chapter}\ \PName{then code}\ \textMacro{else}\ % + \PName{else code}\ \textMacro{fi}% +\end{Declaration} +If \Macro{if@chapter} is defined and corresponds to +\Macro{iftrue}\IndexCmd{iftrue}, \Package{scrlayer} takes the chapter level +into account when, for example, processing the +\DescRef{\LabelBase.option.automark} option. If it is defined but is not +\Macro{iftrue}, \Package{scrlayer} handles only the +\DescRef{maincls.cmd.part}, \DescRef{maincls.cmd.section}, +\DescRef{maincls.cmd.subsection}, \Macro{sub\dots subsection}, +\DescRef{maincls.cmd.paragraph}, \DescRef{maincls.cmd.subparagraph}, +\Macro{sub\dots subparagraph} sectioning units. If the macro is undefined, +\Package{scrlayer} searches for \DescRef{maincls.cmd.chapter}. If +\DescRef{maincls.cmd.chapter} is defined and does not correspond to +\Macro{relax}, \Package{scrlayer} defines \Macro{if@chapter} to +\Macro{iftrue}. Otherwise \Macro{if@chapter} becomes +\Macro{iffalse}\IndexCmd{iffalse}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{if@mainmatter}\ \PName{then code}\ % + \textMacro{else}\ \PName{else code}\ \textMacro{fi}% +\end{Declaration} +Classes like \Class{book} or \Class{scrbook} provide +\DescRef{maincls.cmd.frontmatter}\IndexCmd{frontmatter}, +\DescRef{maincls.cmd.mainmatter}\IndexCmd{mainmatter}, and +\DescRef{maincls.cmd.backmatter}\IndexCmd{backmatter} to switch between the +front, main, and end parts of a book. Typically, these classes also use +\Macro{if@mainmatter} internally to decide whether the current text is part of +the main body of the document or not. Classes like \Class{report} and +\Class{article} have no \DescRef{maincls.cmd.frontmatter}, +\DescRef{maincls.cmd.mainmatter}, or \DescRef{maincls.cmd.backmatter} and +therefore also lack \Macro{if@mainmatter}. + +It is easier for \Package{scrlayer} to avoid constantly testing for the +existence of these commands to decide whether to work in the main matter or +not, and instead to use \Macro{if@mainmatter}\IndexCmd{iftrue} with classes +like \Class{report} and \Class{article}. So if \Macro{if@mainmatter} is not +defined, \Package{scrlayer} defines it as a synonym for \Macro{iftrue}. + +Some classes, however, define \DescRef{maincls.cmd.frontmatter}, +\DescRef{maincls.cmd.mainmatter}, or \DescRef{maincls.cmd.backmatter} but not +\Macro{if@mainmatter}. In this case, \Package{scrlayer} also defines +\Macro{if@mainmatter} to be \Macro{iftrue} and it extends definition of +\DescRef{maincls.cmd.frontmatter}, \DescRef{maincls.cmd.mainmatter}, and +\DescRef{maincls.cmd.backmatter} to set \Macro{if@mainmatter} properly. +However, if there are other, comparable commands for switching between +different document parts. \Package{scrlayer} will not recognize them, does not +test for them, and therefore cannot extend them appropriately. In this case, +\Package{scrlayer} needs help of the class author to set \Macro{if@mainmatter} +correctly.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DeclareSectionNumberDepth}\Parameter{level name}% + \Parameter{level depth} +\end{Declaration} +Generally each section level is assigned an integer number indicating its +depth in the document structure. \LaTeX{} needs this to manage the hierarchy +of the section levels. But normally these values are known only to the +particular class that defines the section commands. This class then uses the +appropriate numbers inside the corresponding commands. + +The \Package{scrlayer} package also needs information about the section +hierarchy. With the help of \Macro{DeclareSectionNumberDepth}, you can map the +name of a heading level to a corresponding \PName{level depth}. For example, +for the standard \Class{book} class, the \PName{level name}s would be +\PValue{part}, \PValue{chapter}, \PValue{section}, \PValue{subsection}, +\PValue{subsubsection}, \PValue{paragraph}, and \PValue{subparagraph}, and the +corresponding \PName{level depth}s would be -1, 0, 1, 2, 3, 4, and 5. + +The \Package{scrlayer} package tries to determine the \PName{level depth}s on +its own while loading and again during \Macro{begin}\PParameter{document}. But +if this fails, for example because you use completely different sectioning +commands, you can define the relationship explicitly with +\Macro{DeclareSectionNumberDepth}.% +\EndIndexGroup + + +\section{Declaring Layers} +\seclabel{layers} + +A layer is an abstract model of a page. Unlike a real, physical sheet of +paper, this page is completely transparent. Typically, multiple layers are +stacked atop one another and opaque material on one layer hides material on +the layers below. The stack of layers is then merged to form the physical +page. The \Package{scrlayer} package provides two such stacks for each page: a +background stack and a foreground stack. The background stack is printed +beneath the normal page content, while the foreground stack is printed above +it. The normal page content is therefore a kind of a dividing layer between +the two layer stacks. + +A layer has several attributes that can be understood as answers to some basic +questions: +\iffree{\begin{description}}{% + \begingroup + \RedeclareSectionCommand[beforeskip=.5\baselineskip plus .25\baselineskip + minus .1\baselineskip]{paragraph}% + \renewcommand*\item[4][]{\paragraph*{#3{#4}#1}}% + }% +\item[Does the layer belong to the foreground or the background?]% + \leavevmode\textnote{foreground or background}\hskip 0pt + Background layers are output before the normal content of the page. + Therefore they appear behind or beneath the normal content of the page. + Foreground layers are then output after the normal content. Therefore they + appear on top of the normal content of the page. By default, a layer is both + a background layer \emph{and} a foreground layer and therefore is printed + twice. Usually it makes sense to limit the layer explicitly to either the + foreground or the background. +\item[What is the position of the layer?]% + \leavevmode\textnote{horizontal and vertical position}\hskip 0pt + To answer this question, there are attributes to define the layer's + horizontal and vertical position. +\item[How big is the layer?\textnote{horizontal and vertical size}]% + As with the position, there are also attributes to define the width and + height of a layer. Thus a layer can be smaller or larger than the paper + and it can be placed at different positions on the paper. +\item[How are the horizontal and vertical positions measured?]% + \leavevmode\textnote{alignment}\hskip 0pt + This question is answered by the alignment attribute. The horizontal + position can be measured from the left edge of the paper to the left edge of + the layer, to the centre of the layer, to the right edge of the layer. + Similarly, the vertical position can be measured from the top edge of the + paper to the top edge of the layer, the centre of the layer, or the bottom + edge of the layer. +\item[Is the layer intended for text or picture output?]% + \leavevmode\textnote{text or picture}\hskip 0pt + This question is closely related to the position. For example, users often + expect the origin for a picture to be at the lower left corner of the layer. + But this would not be suitable for text output. Therefore the origin of a + text layer is the height of a standard text line below the top left corner + of the layer. Picture layers, on the other hand, create a + \Environment{picture}\IndexEnv{picture} environment in which additional + positioning commands are available. +\item[Should the layer be printed on left or right pages?]% + \leavevmode\textnote{left or right page}\hskip 0pt + By default a layer will be printed on all pages. Note that \LaTeX{} treats + even pages as left-side pages and odd pages as right-side pages, but in + one-sided printing, only right-hand pages exist regardless of the page + number. +\item[Should the layer be printed in one-sided or two-sided mode?]% + \leavevmode\textnote{one-sided or two-sided}\hskip 0pt + By default a layer will be printed in both one-sided and two-sided + printing. Nonetheless, a layer that is restricted to even pages will never + be printed in one-sided printing and therefore is not a one-sided layer. +\item[Should the layer be printed on float pages or normal pages?]% + \leavevmode\textnote{float page or normal page}\hskip 0pt + \LaTeX{} produces float pages for objects from environments like tables or + figures if they are allowed to appear on a page without normal page contents + (see option \PValue{p} for \Environment{figure} or \Environment{table}). In + effect, the entire page is allowed to float within the document. Normal + pages in this sense are all pages that are not float pages. Normal pages can + also contain floats at the top, in the middle, or at the bottom of the page. + Very large floats can give the impression of being page floats, while in + reality they are floating environments placed at the top of a normal page. +\item[What are the contents of the layer?]% + \leavevmode\textnote{contents}\hskip 0pt + The corresponding attribute simply contains what should be printed whenever + the layer is output. +\iffree{\end{description}}{% + \endgroup\par\bigskip\noindent\ignorespaces +}% +These eight questions immediately give rise to a number of attributes. Later +\iffree{in this guide}, we will describe additional attributes. However, they +are only defined for convenience and can be expressed by a combination of +these primary attributes. + + +\begin{Declaration} + \Macro{DeclareLayer}\OParameter{option list}\Parameter{layer name}% + \Macro{DeclareNewLayer}\OParameter{option list}\Parameter{layer name}% + \Macro{ProvideLayer}\OParameter{option list}\Parameter{layer name}% + \Macro{RedeclareLayer}\OParameter{option list}\Parameter{layer name}% + \Macro{ModifyLayer}\OParameter{option list}\Parameter{layer name} +\end{Declaration} +These commands can be used to define layers. The \PName{layer name} must be +fully expandable and should expand to ASCII letters only. Some additional +characters are accepted, but their use is only recommended for advanced users. + +The \Macro{DeclareLayer} command does not care whether or not a layer with the +given \PName{layer name} already exists. It will under all circumstances +define the layer with the attributes specified in the \PName{option list}. An +\PName{option} can be either a key or a key followed by an equal sign and +a value. Multiple options are separated by commas. To use a comma or a white +space within the value of an option, you must put the value inside curly +brackets. See \autoref{tab:scrlayer.layerkeys} for more information on keys, +values, and the corresponding attributes. + +Unlike \Macro{DeclareLayer}, \Macro{DeclareNewLayer} reports an error if a +layer with the same \PName{layer name} already exists. This prevents the user +from accidentally using the same \PName{layer name} more than once. This +is especially useful when classes or packages also define layers internally. + +In contrast, \Macro{ProvideLayer} only defines a layer if there is no layer +with the same name already. If the name is in use for another layer, the new +definition is ignored. Therefore this command has the meaning, \emph{define + the layer only if it does not already exist.} + +If you want to redefine an existing layer, you can use \Macro{RedeclareLayer} +or \Macro{ModifyLayer}. With \Macro{RedeclareLayer}, the layer is first reset +to the default settings and then completely redefined via the specified +options list. In contrast, \Macro{ModifyLayer} does not reset the layer. +Only those attributes which are explicitly set in the \PName{option list} will +be changed. Applying either command to a previously undefined \PName{layer + name} results in an error. + +\begin{desclist} + \desccaption{% + Options for defining page layers and the meaning of the + corresponding layer attribute\label{tab:scrlayer.layerkeys}% + }{% + Options for defining layers (\emph{continued})% + }% + \entry{% + \ChangedAt{v3.16}{\Package{scrlayer}}% + \OptionVName{addcontents}{Code}}{% + The specified \PName{code} will be appended to the current value of the + \Option{contents} attribute, so the new content will appear at the end of + the existing content. For more information about the handling of + \PName{code} see the \Option{contents} option.% + }% + \entry{% + \ChangedAt{v3.16}{\Package{scrlayer}}% + \OptionVName{addheight}{additional height}}{% + The current value of the \Option{height} attribute will be increased by + the value of this option. You can use the same kind of values as for + \Option{height}.% + }% + \entry{% + \ChangedAt{v3.16}{\Package{scrlayer}}% + \OptionVName{addhoffset}{additional horizontal offset}}{% + The current value of the \Option{hoffset} attribute will be increased by + the value of this option. You can use the same kind of values as for + \Option{hoffset}.% + }% + \entry{% + \ChangedAt{v3.16}{\Package{scrlayer}}% + \OptionVName{addvoffset}{additional vertical offset}}{% + The current value of the \Option{voffset} attribute will be increased by + the value of this option. You can use the same kind of values as for + \Option{voffset}.% + }% + \entry{% + \ChangedAt{v3.16}{\Package{scrlayer}}% + \OptionVName{addwidth}{additional width}}{% + The current value of the \Option{width} attribute will be increased by + the value of this option. You can use the same kind of values as for + \Option{width}.% + }% + \nentry{\KOption{align}{\PName{alignment characters}}}{% + The \PName{alignment characters} define the desired alignment of the + layer. Each \PName{alignment character} determines how the \PName{length} + of either the \Option{hoffset} or the \Option{voffset} option is + interpreted. Multiple \PName{alignment character}s can be used together + (without spaces or commas) and are evaluated in the order they occur. + Macros are not permitted in the value of the option. Valid + \PName{alignment character}s are: + \begin{description} + \item[\PValue{b} --] align the layer at its bottom edge; the value of + \Option{voffset} is the distance from the top edge of the paper to the + bottom of the layer. + \item[\PValue{c} --] align the layer at its centre; the values of + \Option{voffset} and \Option{hoffset} are interpreted as the distance + from the top left corner of the paper to the centre of the layer. + \item[\PValue{l} --] align the layer at its left edge; the value of + \Option{hoffset} is interpreted as the distance from the left edge of + the paper to the left edge of the layer. + \item[\PValue{r} --] align the layer at its right edge; the value of + \Option{hoffset} is interpreted as the distance from the left edge of + the paper to the right edge of the layer. + \item[\PValue{t} --] align the layer at its top edge; the value of + \Option{voffset} is interpreted as the distance from the top edge of the + paper to the top edge of the layer. + \end{description}% + }% + \entry{\KOption{area}{% + \Parameter{hoffset}\Parameter{voffset}% + \Parameter{width}\Parameter{height}}}{% + This composite option sets the primary attributes + \OptionValue{hoffset}{horizontal offset}, \OptionValue{voffset}{vertical + offset}, \OptionValue{width}{width}, \OptionValue{height}{height}.% + }% + \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% + \Option{backandforeground}}{% + This option removes the restriction of a layer to the foreground or the + background. In general, this option makes little sense, but it is provided + for the sake of a complete user interface. This option does not expect or + allow a value.% + }% + \entry{\Option{background}}{% + This option displays the layer in the background only. The default is to + display layers in both the background and the foreground. This option does + not expect or allow a value.% + }% + \entry{\Option{bottommargin}}{% + This composite option sets the primary attributes \Option{hoffset}, + \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} so + that the layer spans the paper horizontally from the left edge to the + right and vertically from immediately beneath the footer to the bottom + edge of the paper.% + }% + \entry{\KOption{clone}{\PName{layer name}}}{% + This composite option sets all primary attributes of the layer to the same + values as the primary attributes of the layer with the given \PName{layer + name}. See the notes on the \PName{layer name} at the beginning of the + explanation for \Macro{DeclareLayer}. The layer to be cloned must also + already exist.% + }% + \entry{\KOption{contents}{\PName{code}}}{% + The specified \PName{code} will be expanded whenever the layer is printed. + This \PName{code} defines what you see for the layer. No tests are made to + see if the code is valid. Errors in the \PName{code} can therefore lead to + multiple error messages on each page that prints the layer.% + }% + \entry{\Option{evenpage}}{% + This option causes the layer to appear on even pages only, unlike the + default, where a layer will appear on both even and odd pages. Since even + pages only appear in two-sided printing, this option implies + \Option{twoside}. This option does not expect or allow a value.% + }% + \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% + \Option{everypage}}{% + This option is a combination of \Option{oddorevenpage} and + \Option{floatornonfloatpage}. This option does not expect or allow a + value.% + }% + \entry{\Option{everyside}}{% + This option removes any restriction of the layer to one-sided or two-sided + printing. This is the default setting. This option does not expect or + allow a value.% + }% + \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% + \Option{floatornonfloatpage}}{% + This option removes any restriction of the layer to float or non-float + pages and restores the default setting. This option does not expect or + allow a value.% + }% + \entry{\Option{floatpage}}{% + This option restricts the layer to appearing on float pages only. The + default setting is for layers to appear on both float and non-float pages. + This option does not expect or allow a value.% + }% + \entry{\Option{foot}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the page footer over the width of the text area. This option does + not expect or allow a value.% + }% + \entry{\Option{footskip}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical distance between the text area and the page footer over + the width of the text area. Note, however, that although the height of + this area depends on \Length{footskip}, it is not the same. This option + does not expect or allow a value.% + }% + \entry{\Option{foreground}}{% + This option displays the layer in the foreground only. The default is to + display layers in both the background and the foreground. The option does + not expect or allow a value.% + }% + \entry{\Option{head}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical area of the page header for the width of the text area. + The height corresponds to the length \Length{headheight}. This option does + not expect or allow a value.% + }% + \entry{\Option{headsep}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical distance between the page header and the text area for + the width of the text area. The height corresponds to the length + \Length{headsep}. This option does not expect or allow a value.% + }% + \entry{\KOption{height}{\PName{length}}}{% + Sets the height of the layer. Note that the \PName{length} can be a + \LaTeX{} length declared with \Macro{newlength}, a \TeX{} length declared + with \Macro{newdimen} or \Macro{newskip}, a length value like 10\,pt, or a + dimensional expression using +, -, /, *, (, and ). For more information + about valid dimensional expressions see \cite[section~3.5]{manual:eTeX}.% + }% + \entry{\KOption{hoffset}{\PName{length}}}{% + Sets the distance of the layer from the left edge of the paper. How the + distance is measured depends on the \Option{align} option. See the + \Option{height} option for more information about valid expressions for + \PName{length}.% + }% + \entry{\Option{innermargin}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the inner margin, from the edge of the page to the edge of the text + area and from the top to the bottom of the page. In one-sided printing, + the inner margin corresponds to the left margin. This option does not + expect or allow a value.% + }% + \entry{\Option{leftmargin}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the left margin, from the left edge of the paper to the left edge of + the text area and from the top of the paper to the bottom. This option + does not expect or allow a value.% + }% + \entry{\ChangedAt{v3.19}{\Package{scrlayer}}% + \OptionVName{mode}{mode}}{% + This primary option defines the \PName{mode} in which the layer's content + is output. The default is \OptionValue{mode}{text}. The baseline of the + first text line is placed the height of one standard text line below the + top edge of the layer, so the text is usually neatly aligned with the top + of the layer. In \PValue{picture} \PName{mode}, on the other hand, the + layer spans a \Environment{picture} environment with the origin at the + bottom left corner of the layer. The \PValue{raw} \PName{mode} is also + also defined. By default it corresponds to \PValue{text} \PName{mode}. + Changing\textnote{Attention!} the \PName{mode} of a layer usually results + the contents shifting. Furthermore, the \PValue{picture} \PName{mode} + provides additional commands that result in errors with another + \PName{mode}. Therefore it usually makes no sense to change the + \PName{mode} of a layer after its initial declaration!% + }% + \entry{\Option{nonfloatpage}}{% + This option restricts the layer to pages that are not float pages. The + default is for the layer to appear on both float and non-float pages. This + option does not expect or allow a value.% + }% + \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% + \Option{oddorevenpage}}{% + This option removes any restriction of the layer to odd or even pages, + restoring the default behaviour that the layer should appear on both odd + and even pages. The option does not expect or allow a value.% + }% + \entry{\Option{oddpage}}{% + This option restricts the layer to odd pages only. The default is for + layers to appear on both odd pages and on even pages. Note that in + one-sided printing, all pages are odd, regardless of the page number. This + option does not expect or allow a value.% + }% + \entry{\Option{oneside}}{% + This option restricts the layer to one-sided printing only. The default is + for layers to appear in both one-sided and two-sided printing. This option + does not expect or allow a value.% + }% + \entry{\Option{outermargin}}{% + The composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the outer margin of the page, from the top to the bottom of the + paper. The outer margin corresponds to the right margin in one-sided + printing. This option does not expect or allow a value.% + }% + \entry{\Option{page}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the the whole paper. This option does not expect or allow a value.% + }% + \entry{\ChangedAt{v3.16}{\Package{scrlayer}}% + \OptionVName{pretocontents}{code}}{% + The value of \PName{code} is prefixed the current value of the + \Option{contents} attribute, so the new content will appear before the + existing content. For more information about the handling of \PName{code}, + see the \Option{contents} option.% + }% + \entry{\Option{rightmargin}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the right margin, from the right edge of the text area to the right + edge of the paper and from the top to the bottom edge of the paper. This + option does not expect or allow a value.% + }% + \entry{\Option{textarea}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the entire text area. This option does not expect or allow a value.% + }% + \entry{\Option{topmargin}}{% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical distance between the top edge of the paper to the + header for the entire width of the paper. This option does not expect or + allow a value.% + }% + \entry{\Option{twoside}}{% + This option restricts the layer to two-sided printing. The default is for + layers to appear in both one-sided and two-sided printing. This option + does not expect or allow a value.% + }% + \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% + \Option{unrestricted}}{% + This option removes all output restrictions. It is a combination of + \Option{backandforeground}, \Option{everyside}, and + \Option{floatornonfloatpage}. This option does not expect or allow a + value.% + }% + \entry{\KOption{voffset}{\PName{length}}}{% + Sets the distance of the layer from the top of the paper. How the distance + is measured depends on the \Option{align} option. See the \Option{height} + option for more information about valid expressions for \PName{length}.% + }% + \entry{\KOption{width}{\PName{length}}}{% + Sets the width of the layer. See the \Option{height} option for more + information about valid expressions for \PName{length}.% + }% +\end{desclist} +% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ModifyLayers}\OParameter{option list}\Parameter{layer list} +\end{Declaration} +This\ChangedAt{v3.26}{\Package{scrlayer}} command executes +\DescRef{\LabelBase.cmd.ModifyLayer} with the given \PName{option list} for +all layers of the comma-separated layer list. Therefore the option can be used +to change attributes of several layers simultaneously.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{layerhalign}% + \Macro{layervalign}% + \Macro{layerxoffset}% + \Macro{layeryoffset}% + \Macro{layerwidth}% + \Macro{layerheight}% +\end{Declaration} +These commands are only valid in the \PName{code} specified with +\Option{contents}, \Option{addcontents}, or \Option{pretocontents}. In this +case, they contain the layer's actual alignment, position, and dimensions that +will be used for the output. However, this is not necessarily the actual +dimensions of the layer's contents, e.\,g., if the contents are oversized or +do not fill the layer completely. + +The primary layer attribute \PValue{align} is mapped to +\Macro{layerhalign}\ChangedAt{v3.19}{\Package{scrlayer}} and +\Macro{layervalign}. The horizontal values \PValue{l} and \PValue{r} are +copied to \Macro{layerhalign}. The vertical values \PValue{t} and \PValue{b} +are copied to \Macro{layervalign}. The value \PValue{c}, which is both +horizontal and vertical, is copied to both commands. If there are several +conflicting values for \PValue{align}, only the last one is copied. Thus the +resulting \Macro{layerhalign} is either \PValue{l}, \PValue{c}, or \PValue{r}, +and the resulting \Macro{layervalign} is either \PValue{t}, \PValue{c}, or +\PValue{b}. + +Redefining\textnote{Attention!} these instructions to change the values stored +in them is not permitted, as it would lead to unpredictable results.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{LenToUnit}\Parameter{length} +\end{Declaration} +This\ChangedAt{v3.19}{\Package{scrlayer}} command originally came from +\Package{eso-pic}\IndexPackage{eso-pic}~2.0f. It converts lengths into +multiples of \Length{unit length} and can therefore be used everywhere \LaTeX{} +expects \Environment{picture} coordinates or \Length{unit length}-dependent +values. For more information, see \cite{package:eso-pic} and the descriptions +of \Macro{putUR}, \Macro{putLL}, and \Macro{putLR} below. If the command is +already defined, e.\,g., by loading \Package{eso-pic} before +\Package{scrlayer}, the package does not define it again.% +\iffalse% Umbruchkorrekturtext +\par +It should be noted at this point that using package +\Package{picture}\IndexPackage{picture}\textnote{\Package{picture}} (see +\cite{package:picture}) supersedes \Macro{LenToUnit} more or less. The package +extends environment \Environment{picture} and the picture commands so that you +can use \LaTeX{} lengths directly for coordinates.% +\fi +\EndIndexGroup + + +\begin{Declaration} + \Macro{putUL}\Parameter{content}% + \Macro{putUR}\Parameter{content}% + \Macro{putLL}\Parameter{content}% + \Macro{putLR}\Parameter{content}% + \Macro{putC}\Parameter{content} +\end{Declaration} +You\ChangedAt{v3.19}{\Package{scrlayer}} can use these commands inside the +value of \PValue{contents} layer option if the layer is declared with +\OptionValue{mode}{picture}. In this case, \Macro{putUL} places the +\PName{content} relative to the upper left corner of the layer and therefore +is the same as +\lstinline[breaklines=false]|\put(0,\LenToUnit{\layerheight})|. \Macro{putUR} +places the \PName{content} relative to the upper right corner of the layer and +therefore is the same as +\lstinline[breaklines=false] +|\put(\LenToUnit{\layerwidth},\LenToUnit{\layerheight})|. +\Macro{putLL} places the \PName{content} relative to the lower left corner of +the layer and therefore is the same as +\lstinline[breaklines=false]|\put(0,0)|. \Macro{putLR} places the +\PName{content} relative to the lower right corner and therefore is the same +as \lstinline[breaklines=false]|\put(\LenToUnit{\layerwidth},0)|. Last but +not least, \Macro{putC} places the \PName{content} relative to the centre of +the layer.% +\begin{Example} + You want to determine exactly how accurately + \OptionValueRef{typearea}{DIV}{classic} sets the height of the text area to + the width of the page size. You declare a layer that both borders the text + area and places a circle with a diameter of the paper width in the centre of + the text area: +\begin{lstcode} + \documentclass[DIV=classic]{scrartcl} + \usepackage{pict2e} + \usepackage{scrlayer} + \DeclareNewLayer[% + textarea,background,mode=picture, + contents={% + \putLL{\line(1,0){\LenToUnit{\layerwidth}}}% + \putLR{\line(0,1){\LenToUnit{\layerheight}}}% + \putUR{\line(-1,0){\LenToUnit{\layerwidth}}}% + \putUL{\line(0,-1){\LenToUnit{\layerheight}}}% + \putC{\circle{\LenToUnit{\paperwidth}}}% + } + ]{showtextarea} + \DeclareNewPageStyleByLayers{test}{showtextarea} + \pagestyle{test} + \begin{document} + \null + \end{document} +\end{lstcode} + You will notice that \Package{typearea}'s mapping to an integer \PName{DIV} + value is very accurate in this example. +\end{Example} +Incidentally, you will find more information about late medieval book-page +canon sketched in the example in \autoref{sec:typearea.circleConstruction}, +\autopageref{sec:typearea.circleConstruction}. + +The \Macro{DeclareNewPageStyleByLayers}\IndexCmd{DeclareNewPageStyleByLayers} +command just used in the example defines a new page style using the newly +declared layer. It will be explained in \autoref{sec:scrlayer.pagestyles}, +\DescPageRef{scrlayer.cmd.DeclareNewPageStyleByLayers}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{GetLayerContents}\Parameter{layer~name} +\end{Declaration} +This\ChangedAt{v3.16}{\Package{scrlayer}} command returns the whole contents +of a layer. It is important to note\textnote{Attention!} that using this +command inside the \PName{code} of the layer attributes \Option{contents}, +\Option{addcontents}, or \Option{pretocontents} can result in +infinite recursion when referencing the contents of the current layer. You +are responsible for avoiding such situations!% +\EndIndexGroup + + +\begin{Declaration} + \Macro{IfLayerExists}\Parameter{layer~name} + \Parameter{then-code}\Parameter{else-code} +\end{Declaration} +This command can be used to execute code depending on whether or not a layer +with the specified \PName{layer name} exists. If the layer exists, the +\PName{then-code} will be executed; otherwise, the \PName{else-code} will be +executed. Note that the command cannot really test whether a layer exists. +Instead it uses a heuristic which will never yield a false negative but which, +in extreme cases, could yield a false positive. +\iffalse% Umbruchvarianten +Nevertheless, if the test yields a false positive, something has gone wrong. +For example, this could indicate an incompatible package or that the user is +doing something he or she should not.% +\else +False positives indicate a problem, such as the use of an incompatible package +or a bad choice of internal macro names by the user. +\fi +\EndIndexGroup + + +\begin{Declaration} + \Macro{DestroyLayer}\Parameter{layer~name} +\end{Declaration} +If a layer with the given \PName{layer name} exists, all macros belonging to +it will be set to \Macro{relax}. In page styles already defined with +\Package{scrlayer}, such destroyed layers are ignored. Destroyed layers can be +redefined using \DescRef{\LabelBase.cmd.DeclareNewLayer} or +\DescRef{\LabelBase.cmd.ProvideLayer}, but they can no longer be changed using +\DescRef{\LabelBase.cmd.RedeclareLayer} or +\DescRef{\LabelBase.cmd.ModifyLayer}.% +\iffalse % See the note at the beginning of the end user interface section +\par +The command is intended to be used inside +\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} (see +\autoref{sec:scrlayer.enduserinterfaces}, +\DescPageRef{scrlayer.cmd.scrlayerOnAutoRemoveInterface}) +to remove layers defined using removable macros of an interface along with +that interface.% +\fi +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{draft}{simple switch} + \Macro{layercontentsmeasure}% +\end{Declaration} +The \KOMAScript{} option \Option{draft} can be used to active the draft mode +of \Package{scrlayer}. The draft mode uses the \Macro{layercontentsmeasure} +command to print a ruler at each layer edge, of which the top and left one is +labelled in centimetres and the right and bottom one in inches. The rulers are +drawn behind the content of each layer. This command can also be used as +exclusive content of a layer.% +\EndIndexGroup + + +\section{Declaring and Managing Page Styles} +\seclabel{pagestyles} + +\BeginIndexGroup +\BeginIndex{}{page>style}% +We now understand how to define and manage layers, but so far we do not know +how they are used. The possibly surprising answer is, with page styles. In +\LaTeX{}, page styles usually define headers and footers of the page. + +The header and footer of odd or right-hand pages\textnote{even or odd page} +are printed on pages with odd page numbers in two-sided printing or on all +pages in one-sided printing. This is directly comparable to the layer +options\important[i]{\Option{evenpage}\\\Option{oddpage}} \Option{oddpage} and +\Option{evenpage}. + +The page header\textnote{header or footer} is output before the main page +contents. The page footer is output after the main page contents. This +corresponds directly to the layer +options\important[i]{\Option{background}\\\Option{foreground}} +\Option{background} and \Option{foreground}. + +Therefore it makes sense to define page styles as lists of layers. But instead +of just the four options mentioned above, you can use all the properties +explained in \autoref{sec:scrlayer.layers}, \autoref{tab:scrlayer.layerkeys}, +on \autopageref{tab:scrlayer.layerkeys}. + +As a result of these considerations, layer page +styles\textnote{layer page style}\Index{page style>layer}% +\Index{layer>page style}\Index{page>style} are one type of page style that +\Package{scrlayer} provides. A layer page style consists of layers as well as +several hooks. The layers have already been described in +\autoref{sec:scrlayer.layers}. The hooks\Index[indexmain]{hooks}% +\textnote{hooks} are points in the expansion or execution of page styles to +which you can add code. Experienced users already know this concept from +commands like \Macro{AtBeginDocument} (see \cite{latex:usrguide}) or +\DescRef{scrlfile.cmd.BeforeClosingMainAux} (see +\DescPageRef{scrlfile.cmd.BeforeClosingMainAux}). + +Page-style aliases are another type of page style which \Package{scrlayer} +provides. A page-style alias is actually a different page style. In other +words, the name of a page-style alias is an alternative name for another +page-style alias or for a page style. As a result, manipulating a page-style +alias results in manipulating the original page style. If the original page +style is itself an alias, its manipulation again results in the manipulation +of the alias's original page style, and so on until a real page style is +finally changed. The term \emph{real page style}\textnote{real page style} is +used to distinguish it from a page-style alias. All page styles that are not +page-style aliases are real page styles. Aliases can be defined for all page +styles, not just those defined with \Package{scrlayer}. + +\begin{Declaration} + \Macro{currentpagestyle} + \Macro{toplevelpagestyle} +\end{Declaration} +The \Package{scrlayer} package patches the \DescRef{maincls.cmd.pagestyle} +command so that it sets \Macro{currentpagestyle} to the currently active page +style. Note that \DescRef{maincls.cmd.thispagestyle} does not change +\Macro{currentpagestyle}. If you use \DescRef{maincls.cmd.thispagestyle}, +however, \Macro{currentpagestyle} can change within the \LaTeX{} output +routine. However, this change will only occur if \Macro{currentpagestyle} has +been actively protected from expansion until the execution of the output +routine. + +Note that the layer page styles described later in this section do not rely on +this \DescRef{maincls.cmd.pagestyle} extension because they redefine +\Macro{currentpagestyle} themselves. This patch was made so that other, +non-\Package{scrlayer} page styles can use \Macro{currentpagestyle}. +Additionally, \Macro{currentpagestyle} is empty after loading +\Package{scrlayer} and before using \DescRef{maincls.cmd.pagestyle} for the +first time. Therefore, when defining an end-user interface, you may find it +useful to set the current page style to a default with an implicit +\DescRef{maincls.cmd.pagestyle} statement. + +If \DescRef{maincls.cmd.pagestyle} activates an alias page style, +\Macro{currentpagestyle} shows not the alternative name but the name of +the real page style. You\ChangedAt{v3.16}{\Package{scrlayer}} can get the +alternative name using \Macro{toplevelpagestyle}. However, it is not +recommended to define page styles that produce different results depending on +\Macro{toplevelpagestyle}, e.\,g., using \DescRef{scrbase.cmd.Ifstr}. If you +were to activate such a page style using \DescRef{maincls.cmd.thispagestyle} +you could get the wrong result.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{BeforeSelectAnyPageStyle}\Parameter{code}% + \Macro{AfterSelectAnyPageStyle}\Parameter{code}% +\end{Declaration} +The \Macro{BeforeSelectAnyPageStyle} command adds \PName{code} to the hook% +\textnote{hook} that will be executed inside \DescRef{maincls.cmd.pagestyle}, +just before the page style is selected. Within the \PName{code}, you can use +\texttt{\#1} as a place-holder for the argument of +\DescRef{maincls.cmd.pagestyle}. + +The \Macro{AfterSelectAnyPageStyle} command works similarly, but the +\PName{code} will be executed just after the page style has been selected and +after \DescRef{\LabelBase.cmd.currentpagestyle} has been set to the name of +the real page style. + +Note\textnote{Attention!} that the \PName{code} of both commands is executed +only if a page style is selected with \DescRef{maincls.cmd.pagestyle} and not +if it is chosen in a different way, e.\,g., using +\DescRef{maincls.cmd.thispagestyle}. Note also that you cannot remove +\PName{code} from the hook after adding it. But the \PName{code} will be added +locally, so you can use a group to limit the scope of the \PName{code}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DeclarePageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original~page~style~name} + \Macro{DeclareNewPageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original~page~style~name} + \Macro{ProvidePageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original~page~style~name} + \Macro{RedeclarePageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original page style name} +\end{Declaration} +\BeginIndex{}{page style>alias}% +\BeginIndex{}{alias>page style}% +These commands can be used to define a page style with name \PName{page style + alias name} that is simply an alias for an existing page style with the +name \PName{original page style name}. If there is already a page style +\PName{page style alias name}, using \Macro{DeclarePageStyleAlias} or +\Macro{RedeclarePageStyleAlias} will destroy the alias before recreating it. + +\Macro{DeclareNewPageStyleAlias} will throw an error message if a page style +\PName{page style alias name} has already been defined. It does not matter if +the previously defined page style is a layer-page style, a page style alias, +or another page style. + +\Macro{ProvidePageStyleAlias} will define the alias only if the +\PName{page style alias name} page style has not been defined before. If the +\PName{page style alias name} page style already exists, nothing will be done. + +\Macro{RedeclarePageStyleAlias} expects an existing +\PName{page style alias name} page style. It will destroy that page style and +afterwards define the alias. If the \PName{page style alias name} page style +does not exist, you will get an error.% +\iffree{\csname @tempswafalse\endcsname}{\csname @tempswatrue\endcsname}% +\csname if@tempswa\endcsname% Umbruchkorrekturtext + \begin{Example} + Suppose you write a class and use the \PageStyle{chapter} page style for the + first page of each chapter. By default, this page style should match the + \PageStyle{plain} page style. Therefore, you can use the \Package{scrlayer} + package and use +\begin{lstcode} + \DeclareNewPageStyleAlias{chapter}{plain} +\end{lstcode} + to define the \PageStyle{chapter} page style as an alias for the + \PageStyle{plain} page style. If, on the other hand, you later decide that + the \PageStyle{chapter} plage style should correspond to the + \PageStyle{empty} page style, you can achieve this with: +\begin{lstcode} + \RedeclarePageStyleAlias{chapter}{empty} +\end{lstcode}% + \end{Example}% +\fi +\EndIndexGroup + + +\begin{Declaration} + \Macro{DestroyPageStyleAlias}\Parameter{page~style~name}% +\end{Declaration} +\BeginIndex{}{page style>alias}% +\BeginIndex{}{alias>page style}% +This command renders the page style named \PName{page style name} undefined +for \LaTeX{} if it is an alias for another page style. Afterwards, the page +style can be newly defined with +\DescRef{\LabelBase.cmd.DeclareNewPageStyleAlias} or +\DescRef{\LabelBase.cmd.ProvidePageStyleAlias}.% +\iffalse % See the note at the beginning of the end user interface section +\par +This command is intended to be used inside the argument code of +\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} to remove page styles +that have been declared as part of an end-user interface when removing this +interface automatically.% +\fi% +\EndIndexGroup + + +\begin{Declaration} + \Macro{GetRealPageStyle}\Parameter{page~style~name}% +\end{Declaration} +\BeginIndex{}{page style>alias}% +\BeginIndex{}{alias>page style}% +This command will result in the (recursive) real page name of the page style +if \PName{page style name} is an alias of another page style. In all other +cases, even if there's no alias and no page style named \PName{page style + name}, the result is simply \PName{page style name}. The command is fully +expandable and may be used, e.g., in the second argument of \Macro{edef}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DeclarePageStyleByLayers}\OParameter{option list} + \Parameter{page style name} + \Parameter{layer list} + \Macro{DeclareNewPageStyleByLayers}\OParameter{option list} + \Parameter{page style name} + \Parameter{layer list} + \Macro{ProvidePageStyleByLayers}\OParameter{option list} + \Parameter{page style name} + \Parameter{layer list} + \Macro{RedeclarePageStyleByLayers}\OParameter{option list} + \Parameter{page style name} + \Parameter{layer list} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +These commands declare a page style named \PName{page style name}. The page +style will consist of the layers given in \PName{layer list}, a comma +separated list of layer names. Note\textnote{Attention!} that the \PName{page + style name} and the layer names in the \PName{layer list} must be fully +expandable and should expand to letters. Several other characters are also +accepted, but their use is recommended only for experienced users. + +The \PName{option list} is a comma-separated list of options in the form +\texttt{\PName{key}=\PName{value}}. These options may be used to set +additional features. Currently they are used to set the code that should be +expanded or executed at several hooks\Index{hooks}. See the introduction to +this section for more general information about hooks. See +\autoref{tab:scrlayer.pagestyle.hooks} for detailed information on specific +hooks. + +\begin{desclist} + \desccaption{% + Hook options for page styles (in order of + execution)\label{tab:scrlayer.pagestyle.hooks}% + }{% + Hook options for page styles (\emph{continued})% + }% + \entry{\OptionVName{onselect}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the page + style is selected, for example with \DescRef{maincls.cmd.pagestyle}. Note + that \DescRef{maincls.cmd.thispagestyle} itself does not directly select a + page style. In this case, the page style is only activated within \LaTeX's + output routine.% + }% + \entry{\OptionVName{oninit}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers is initialised. Note that this happens twice + for each page: once for background layers and once for foreground layers.% + }% + \entry{\OptionVName{ononeside}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers in one-sided printing is initialised. Note that + this happens twice for each page: once for background layers and once for + foreground layers.% + }% + \entry{\OptionVName{ontwoside}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers in two-sided printing is initialised. Note that + this happens twice for each page: once for background layers and once for + foreground layers.% + }% + \entry{\OptionVName{onoddpage}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on an odd page is initialised. Note that this + happens twice for each page: once for background layers and once for + foreground layers. Note also that in one-sided printing all pages are odd + pages, not just those with odd page numbers.% + }% + \entry{\OptionVName{onevenpage}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on an even page is initialised. Note that this + happens twice for each page: once for background layers and once for + foreground layers. Note also that in one-sided printing there are no even + pages. Instead, all pages are treated as odd pages, not just those with + odd page numbers.% + }% + \entry{\OptionVName{onfloatpage}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on a float page is initialised. Note that this + happens twice for each page: once for background layers and once for + foreground layers. Note also that float pages are only those pages with + one or more p-placed floating environments.% + }% + \entry{\OptionVName{onnonfloatpage}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on a non-float page is initialised. Note that + this happens twice for each page: once for background layers and once for + foreground layers. Note also that float pages are only the pages on which + one or more p-placed floating environments are output. Other pages may + well have t-, h-, or b-placed floating environments.% + }% + \entry{\OptionVName{onbackground}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's background layers is initialised. Note that this + happens once each page.% + }% + \entry{\OptionVName{onforeground}{code}}{% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's foreground layers is initialised. Note that this + happens once each page.% + }% +\end{desclist} + +\iffalse% Umbruchvarianten + While the \Macro{DeclarePageStyleByLayers} command always defines the page + style, \Macro{DeclareNewPageStyleByLayers} generates an error message if a + page style with the same name already exists. Note\textnote{Attention!} that + the declaration of a page style that is already an alias for another page + style (see, for example, \Macro{DeclareAliasPageStyle} earlier in this + section) will redefine not the specified page style alias but the real page + style (see \DescRef{\LabelBase.cmd.GetRealPageStyle} earlier in this + section).% +\else% + The \Macro{DeclarePageStyleByLayers} command defines the page style + regardless of whether a page style of \PName{page style name} already + exists. If necessary, the existing page style is completely + redefined. However, if a page style alias \PName{page style name} already + exists, the associated real page style, not the page style alias itself, is + redefined (see \DescRef{\LabelBase.cmd.GetRealPageStyle} earlier in this + section). + + The \Macro{DeclareNewPageStyleByLayers} command differs if a page style of + the same name already exists. Regardless of whether it is a real or an alias + page style, an error will be reported in this case. +\fi + +In contrast, \Macro{ProvidePageStyleByLayers} preserves the page style +unchanged if a page style with name \PName{page style name} already exists. If +no such page style exists, it is defined as in +\Macro{DeclarePageStyleByLayers}. + +The \Macro{RedeclarePageStyleByLayers} in turn expects that a page style of +of the name \PName{page style name} already exists and then redefines its real +page style. However, if no page style of the specified name exists, an error +message results. + +Also note the remarks below about the pseudo-page style +\PageStyle{@everystyle@}.% +\EndIndexGroup + + +\begin{Declaration} + \PageStyle{@everystyle@}% + \PageStyle{empty} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +The \Package{scrlayer} package defines two specific page styles worth noting. +The first of these is \PageStyle{@everystyle@}% +\important{\PageStyle{@everystyle@}}. This page style should never be used +like a normal page style, for example with \DescRef{maincls.cmd.pagestyle} or +\DescRef{maincls.cmd.thispagestyle}, or as the target of a page-style alias. +Instead, the layers and hooks\Index{hooks} of this page style are used by all +other layer page styles. The hooks of \PageStyle{@everystyle@} are placed in +front of their respective hooks, and the layers in front of the respective +layers, of the active page style. + +Thus adding a layer to the pseudo-page style \PageStyle{@everystyle@} or code +to a hook of this page style is like adding a layer or hook code to all layer +page styles, even the empty one. There's one crucial difference: commands that +reference the layers of a page style which include +\DescRef{\LabelBase.cmd.ForEachLayerOfPageStyle}, e.\,g., the commands +\DescRef{\LabelBase.cmd.AddLayersToPageStyleBeforeLayer} or +\DescRef{\LabelBase.cmd.AddLayersToPageStyleAfterLayer}, disregard the layers +of the page style \PageStyle{@everystyle@} when applied to a different layer +page style. + +The second, slightly different page style is \PageStyle{empty}. Normally the +\LaTeX{} kernel defines the \PageStyle{empty} page style to have an empty +header and footer. The \Package{scrlayer} package redefines this page style as +a layerless page style. Nonetheless, you can use it like any other layer page +style. The main advantage of the layer page style over the original page +style from the \LaTeX{} kernel is that it also executes the hooks and layers +of the psuedo-layer page style \PageStyle{@everystyle@}.% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{onpsselect}{code}% + \OptionVName{onpsinit}{code}% + \OptionVName{onpsoneside}{code}% + \OptionVName{onpstwoside}{code}% + \OptionVName{onpsoddpage}{code}% + \OptionVName{onpsevenpage}{code}% + \OptionVName{onpsfloatpage}{code}% + \OptionVName{onpsnonfloatpage}{code}% + \OptionVName{onpsbackground}{code}% + \OptionVName{onpsforeground}{code} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +There is also a \KOMAScript{} option for each of the hooks\Index{hooks} in +\autoref{tab:scrlayer.pagestyle.hooks}% +\iftrue +. The names of the \KOMAScript{} options are similar to those for declaring +page style layers, except that a ``\texttt{ps}'' is inserted after +``\texttt{on}'' at the beginning of the name +\else +, into the names of which a ``\texttt{ps}'' is inserted +\fi +. The values of these \KOMAScript{} options are used as the initial values for +the corresponding hooks. These initial values are then extended by all the +values assigned to the corresponding hooks in the \PName{option list} of the +declaration commands. You can remove the default with +\DescRef{\LabelBase.cmd.ModifyLayerPageStyleOptions}, which is explained later +in this section.% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{singlespacing}{simple switch} +\end{Declaration} +If\ChangedAt{v3.24}{\Package{scrlayer}\and \Package{scrlayer-scrpage}} a +document is printed with increased line spacing, e.\,g., using the +\Package{setspace}\IndexPackage{setspace}\important{\Package{setspace}} +package, it is often undesirable for the header and footer to be printed with +this increased spacing. This is particularly true if the header and footer +consist of only a single line. In this case you can use \KOMAScript{} option +\Option{singlespacing}. However, the default\textnote{default} is +\OptionValue{singlespacing}{false}! The option generally applies to all layer +page styles. If you want single-spacing for only some page styles, use +\OptionValue{oninit}{\Macro{linespread}\PParameter{1}\Macro{selectfont}} for +those page styles.% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{deactivatepagestylelayers}{simple switch}% + \Macro{ForEachLayerOfPageStyle}\Parameter{page style name}\Parameter{code}% + \Macro{ForEachLayerOfPageStyle*}\Parameter{page style name}\Parameter{code} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +As long as the \KOMAScript{} option \Option{deactivatepagestylelayers} is not +enabled, the \Macro{ForEachLayerOfPageStyle} command can execute arbitrary +\PName{code} for each layer of the page style named \PName{page style name}. +Inside of \PName{code}, the place holder \PValue{\#1} serves as a +reference to the name of the current layer. +\begin{Example} + If you want to print the names of all layers of the \PValue{scrheadings} + page style as a comma-separated list, you can use: +\begin{lstcode} + \let\commaatlist\empty + \ForEachLayerOfPageStyle{scrheadings}{% + \commaatlist#1\gdef\commaatlist{, }} +\end{lstcode} +\end{Example} +In\textnote{Attention!} the example above, we had to use \Macro{gdef} instead +of \Macro{def} because \Macro{ForEachLayerOfPageStyle} executes the +\PName{code} inside a group to minimise side effects. However, \Macro{gdef} +redefines \Macro{commaatlist} globally so the change will persist when the +\PName{code} for the next layer is executed. + +Alternatively,\ChangedAt{v3.18}{\Package{scrlayer}} you can use \Macro{def} +with the starred variant \Macro{ForEachLayerOfPageStyle*}. This form dispenses +with the extra group when executing \PName{code}. However, the user then has +to take make sure that the \PName{code} has no unwanted side effects. In +particular, deactivating all layers using +\OptionValue{deactivatepagestylelayers}{true} within \PName{code} would +persist beyond the call to \Macro{ForEachLayerOfPageStyle*}. + +Various \Package{scrlayer} commands also use \Macro{ForEachLayerOfPageStyle} +internally. Their behaviour can therefore also be changed using the +\KOMAScript{} option \Option{deactivatepagestylelayers}. With this option, +you can temporarily disable and thus hide all layers of all layer page +styles.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{AddLayersToPageStyle}% + \Parameter{page style name}\Parameter{layer list}% + \Macro{AddLayersAtBeginOfPageStyle}% + \Parameter{page style name}\Parameter{layer list}% + \Macro{AddLayersAtEndOfPageStyle}% + \Parameter{page style name}\Parameter{layer list}% + \Macro{RemoveLayersFromPageStyle}% + \Parameter{page style name}\Parameter{layer list}% +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +You can use these commands to add layers to a layer page style or to remove +layers from a layer page style. The page style is referenced by its +\PName{page style name}. The layers are given by a comma-separated +\PName{layer list}. + +Both the \Macro{AddLayersToPageStyle} and the +\Macro{AddLayersAtEndOfPageStyle}\textnote{add at the end} commands insert the +new layers at the bottom of the page style's layer list. Logically, the newly +added layers lie above or in front of the old layers. Background layers, of +course, still are logically behind the text layer and thus behind all +foreground layers. + +In contrast, the \Macro{AddLayersAtBeginOfPageStyle}\textnote{add at the + beginning} command inserts the new layers at the top of the page style's +layer list. The layers are separately inserted to the top of the list in the +same order they appear in the \PName{layer list} parameter. This means that +the last layer in the \PName{layer list} parameter will become the first, and +thus the lowest, layer of the page style. + +\iffalse% Umbruchkorrekturtext (beim Aktiveren muss unten \textnote{remove} +% entfernt werden!) +The \Macro{RemoveLayersFromPageStyle} command is exactly the opposite. It +removes\textnote{remove} the specified page-style levels.% +\fi + +The \Macro{RemoveLayersFromPageStyle}\textnote{remove} command removes layers +from the layer list of the page style named \PName{page style name}. +Attempting to remove layers which are not part of the page style's layer list +will be ignored. But attempting to add layers to or remove layers from a page +style that is neither a layer page style nor a page-style alias is an error +and will be reported as such.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{AddLayersToPageStyleBeforeLayer}% + \Parameter{page style name}\Parameter{layer list}% + \Parameter{reference layer name}% + \Macro{AddLayersToPageStyleAfterLayer}% + \Parameter{page style name}\Parameter{layer list}% + \Parameter{reference layer name} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +\iffalse% Umbruchvarianten +These two commands are similar to the previous ones, but they take an +additional parameter, \Parameter{reference layer name}. The layer list of +the page style named in \Parameter{page style name} is searched for this +reference layer. % +\else% +These commands are similar to the previous ones. The existing layers of the +page style, however, are searched for the \PName{reference layer name}. % +\fi% +The layers in the \Parameter{layer list} parameter are then inserted +before\textnote{add before/after layer} or after this reference layer% +\iffalse% Umbruchkorrekturtext +in the layers of the page style% +\fi% +. The order of the layers in the \PName{layer list} is retained. + +If the reference layer named \PName{reference layer name} is not part of the +given page style, nothing is inserted. On the other hand, if the page style is +neither a layer page style nor a page-style alias, an error will be reported.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{UnifyLayersAtPageStyle}\Parameter{page style name} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +The commands for defining page styles or adding layers to a page style do not +care how many times a layer appears in a page style, so it is quite +permissible for a layer to appear multiple times. In most cases, however, it +does not make sense to use the same layer several times in one page style. +Therefore, you can use \Macro{UnifyLayersAtPageStyle} to remove all layer +duplicates from the layer page style of the specified \Parameter{page style + name}. + +Note\textnote{Attention!} that this function can change the order of layers. +So if you need a specific order, you should remove all layers and add the +layers in the order you want instead of using \Macro{UnifyLayersAtPageStyle}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{ModifyLayerPageStyleOptions}% + \Parameter{page style name}\Parameter{option list}% + \Macro{AddToLayerPageStyleOptions}% + \Parameter{page style name}\Parameter{option list} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +These two commands can be used to modify the options, and thus the +hooks\Index{hooks}, of a layer page style. With +\Macro{ModifyLayerPageStyleOptions}\textnote{change page-style options}, only +the options in the comma-separated \PName{option list} will be set to the new +values given there. The previous values are lost. All options from +\autoref{tab:scrlayer.pagestyle.hooks}, +\autopageref{tab:scrlayer.pagestyle.hooks} are allowed. Options or hooks that +are not specified in the \PName{option list} will remain unchanged. If you +want to set an option to do nothing you can set it to the value \Macro{relax}. +Setting an option to a new value using \Macro{ModifyLayerPageStyleOptions} +will remove the previous value, including the global default value. This +statement is the only way to remove the global defaults of the \KOMAScript{} +options from a page style. + +\Macro{AddToLayerPageStyleOptions}\textnote{extend page-style options}, on the +other hand, does not overwrite the previous values. Instead it adds\,---\,or, +more precisely, concatenates\,---\, the new values to old ones.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{IfLayerPageStyleExists}% + \Parameter{page style name}\Parameter{then code}\Parameter{else code}% + \Macro{IfRealLayerPageStyleExists}%^ + \Parameter{page style name}\Parameter{then code}\Parameter{else code}% +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +With these commands, you can execute code depending on whether a page style is +a layer page style or not. The \Macro{IfLayerPageStyleExists} command executes +the \PName{then code} if \PName{page style name} is the name of a layer page +style or a page-style alias that results in a layer page style. Otherwise, the +command executes the \PName{else code}. Internally, this command is often used +to throw an error message if you use one of the layer page style commands with +an \PName{page style name} that does not correspond to a layer page style. + +The \Macro{IfRealLayerPageStyleExists} command goes one step further and +executes the \PName{then code} only if the page style specified by \PName{page + style name} is itself a layer page style. So if \PName{page style name} is a +page-style alias, this command executes the \PName{else code} even if the +alias resolves to a real layer page style.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{IfLayerAtPageStyle}% + \Parameter{page style name}\Parameter{layer name}% + \Parameter{then code}\Parameter{else code}% + \Macro{IfSomeLayerAtPageStyle}% + \Parameter{page style name}\Parameter{layer list}%^ + \Parameter{then code}\Parameter{else code}% + \Macro{IfLayersAtPageStyle}% + \Parameter{page style name}\Parameter{layer list}% + \Parameter{then code}\Parameter{else code}% +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +These commands can be used to test whether one or more layers are part of a +page style. The \Macro{IfLayerAtPageStyle} command expects exactly one +\PName{layer name}\textnote{exactly one layer} as the second argument. If this +layer is part of the page style specified in \PName{page style name}, the +\PName{then code} will be executed. Otherwise, the \PName{else code} will be +executed. + +The \Macro{IfSomeLayerAtPageStyle} and \Macro{IfLayersAtPageStyle} commands +allow a comma-separated \PName{layer list}. \Macro{IfSomeLayerAtPageStyle} +will execute the \PName{then code} if \emph{at least one} of the layers in the +\PName{layer list} parameter is part of the layer list of \PName{page style + name}. In contrast, \Macro{IfLayersAtPageStyle} executes the \PName{then + code} only if \emph{all} the layers in the \PName{layer list} parameter are +part of the page style. If the condition is not met, the \PName{else code} +will be executed. + +With suitable nesting of these commands, you can construct complex conditions. +If you use only one \PName{layer name} in the \PName{layer list}, all three +statements are synonymous.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{DestroyRealLayerPageStyle}\Parameter{page style name} +\end{Declaration} +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +\iftrue +This statement makes a layer page style undefined. If a page-style alias or +ordinary page style is specified, the command is ignored. +\else +With this command you can remove a the definition of a layer page style. +However, this only occurs if a layer page style named \PName{page style name} +exists. If, instead, it is a page-style alias, a different (non-layer) page +style, or not a page style at all, nothing happens; the command is ignored.% +\fi + +If \PName{page style name} is the name of the current page style, the current +page style will becomes a kind of empty page style. If the page style set with +\DescRef{maincls.cmd.thispagestyle} is \PName{page style name}, it will simply +be reset. The previous \DescRef{maincls.cmd.thispagestyle} command loses its +current effect. + +Note\textnote{Attention!} that the layers of the page style are not destroyed +automatically. If you want to destroy the layers too, you can do this with: +\begin{lstcode} + \ForEachLayerOfPageStyle{...}{\DestroyLayer{#1}} +\end{lstcode} +before destroying the layer page style itself.% +\iffalse % See the note at the beginning of the end user interface section +\par +The command is intended to be used within the \PName{code} argument of +\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} to remove page styles +that are defined as part of an end-user interface. See +\autoref{sec:scrlayer.enduserinterfaces} below for more information about +auto-removal code.% +\fi% +\EndIndexGroup +\EndIndexGroup + +\LoadCommonFile{headfootheight}% \section{Height of Page Head and Foot} + +\LoadCommonFile{pagestylemanipulation}% \section{Manipulation of Defined Page Styles} + +\section{Defining and Managing Interfaces for End Users} +\seclabel{enduserinterfaces} + +\iftrue% The whole mechanism is deprecated and should not be used any + % longer. So the documentation is also deactivated. +% TODO: Fix new translation +Until version 3.27\ChangedAt{v3.28}{\Package{scrlayer}} package +\Package{scrlayer} provided mechanism to manage concurrent end user +interfaces. The mechanism has been marked as experimental and the usability +limited. Only \KOMAScript{} itself has used this mechanism and from version +3.28 it is marked as deprecated. So the commands +\Macro{scrlayerInitInterface}\IndexCmd{scrlayerInitInterface}, +\Macro{scrlayerAddToInterface}\IndexCmd{scrlayerAddToInterface}, +\Macro{scrlayerAddCsToInterface}\IndexCmd{scrlayerAddCsToInterface}, +\Macro{scrlayerOnAutoRemoveInterface}\IndexCmd{scrlayerOnAutoRemoveInterface}% +\important{\Macro{scrlayerOnAutoRemoveInterface}} +and the options +\Option{forceoverwrite}\IndexOption{forceoverwrite}, +\Option{autoremoveinterfaces}\IndexOption{autoremoveinterfaces} +should not be used any longer.% +% :ODOT +\else% +The \Package{scrlayer} package provides an experimental interface to define +and manage (concurrent) interfaces for end users. \iffree{In the long run, + this interface may disappear from \Package{scrlayer} and be taken over by + \Package{scrbase} instead.}{} Currently, this interface is highly +experimental% +\iffree{ and therefore \Package{scrlayer} provides these interface commands + only for the use of subpackages of \Package{scrlayer}}{}% +. Given the current state of development, you should not depend on automatic +removal of a concurrent interface to work. Instead, you should avoid using +concurrent end-user interfaces. + +This section only describes the interface commands for defining an end-user +interface. For end users themselves, it is of little interest. Rather, this +section is intended for authors of packages and classes that build on +\Package{scrlayer}. End users will find information about specific end-user +interfaces in \autoref{cha:scrlayer-scrpage}, +\autoref{cha:scrlayer-scrpage-experts}, and \autoref{cha:scrlayer-notecolumn}. + +\begin{Declaration} + \Macro{scrlayerInitInterface}\OParameter{interface name} +\end{Declaration} +The \Macro{scrlayerInitInterface} command registers a new interface named +\PName{interface name}. The \PName{interface name} must be unique. If an +interface with the same name has already been registered, an error will occur. + +This command should always appear as the first command when defining an +end-user interface and therefore is described here first. If the optional +argument\,---\,including the square brackets\,---\,is omitted, +\PValue{\Macro{@currname}.\Macro{@currext}} will be used instead. For classes +and packages, this is the file name of the class or package. But of course you +can use any other sequence of characters with a category of \emph{letter} or +\emph{other}. This is useful, for example, when a class or package defines +multiple end-user interfaces% +\EndIndexGroup + + +\begin{Declaration} + \OptionVName{forceoverwrite}{simple switch}% + \OptionVName{autoremoveinterfaces}{simple switch}% + \Macro{scrlayerAddToInterface}% + \OParameter{interface name}\Parameter{command}\Parameter{code}% + \Macro{scrlayerAddCsToInterface}% + \OParameter{interface name}\Parameter{command sequence}\Parameter{code} +\end{Declaration} +One of the special features of \Package{scrlayer}'s end user interfaces is +that they should register all interface-dependent commands (also known as +\emph{macros}). You can do this using \Macro{scrlayerAddToInterface}. The +optional argument \PName{interface name} must be an interface name previously +registered with \DescRef{\LabelBase.cmd.scrlayerInitInterface}. An error will +occur if the interface has not been initialised. + +If\textnote{Attention!} your interface defines macros not just when the class +or package is being loaded but also at runtime, you must provide the interface +name in the optional argument even if it corresponds to the file name of the +class or package, since the values of \Macro{@currname} and \Macro{@currext} +are only valid while the class or package is being loaded. + +The first mandatory argument is the \PName{command}\footnote{The + \PName{command} consists of a backslash followed by a \PName{command + sequence} that consists of characters of the category code \emph{letter}, + or of exactly one character of the category \emph{other}, or of a character + of the category \emph{active} (without the backslash).} to be added to the +interface. If the command can be defined, this will be done. In addition, it +will set to \Macro{relax} and \PName{code} will be executed. Within +\PName{code}, you can then define \PName{command}, e.\,g., using +\Macro{newcommand}. + +But when can a command be defined? If a command is undefined or \Macro{relax}, +it can always be defined. If a command has already been defined \emph{and} +registered for another interface \emph{and} if the \KOMAScript{} option +\Option{autoremoveinterfaces} has been activated, the other interface will be +removed automatically, and the \PName{command} will be set to \Macro{relax} +and registered for the new interface specified. If a \PName{command} is +already defined but is \emph{not} part of another interface, \emph{and} if the +\KOMAScript{} option \Option{forceoverwrite} has been activated, the +\PName{command} is also set to \Macro{relax} and registered for the specified +interface. In all other cases, however, the command is not definable, in +particular if it is already defined and the \KOMAScript{} options +\Option{autoremoveinterfaces} and \Option{forceoverwrite} are deactivated. + +The \Macro{scrlayerAddCsToInterface} command is similar to +\Macro{scrlayerAddToInterface} but it expects the first argument to be not a +\PName{command} but a command sequence\footnote{A command sequence must be + fully expandable and its expansion must result in characters of the category + code \emph{letter}, \emph{other}, or \emph{space}.}.% +\EndIndexGroup + + +\begin{Declaration} + \Macro{scrlayerOnAutoRemoveInterface}% + \OParameter{interface name}\Parameter{code} +\end{Declaration} +The \Macro{scrlayerOnAutoRemoveInterface} command registers \PName{code} to be +executed in the event that the end-user interface with the specified +\PName{interface name} is automatically removed (see +\DescRef{\LabelBase.option.autoremoveinterfaces} earlier in this section). +This can be used, for example, to automatically destroy layers or page styles +that rely on commands from the end-user interface (see +\DescRef{\LabelBase.cmd.DestroyLayer}, +\DescRef{\LabelBase.cmd.DestroyPageStyleAlias}, and +\DescRef{\LabelBase.cmd.DestroyRealLayerPageStyle}). Regarding the default for +the optional argument, please refer to the explanation for +\DescRef{\LabelBase.cmd.scrlayerInitInterface}.% +\EndIndexGroup% +\fi% +% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "scrguide-en.tex" +%%% coding: utf-8 +%%% ispell-local-dictionary: "en_GB" +%%% eval: (flyspell-mode 1) +%%% End: |