diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex | 1242 |
1 files changed, 1242 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex new file mode 100644 index 00000000000..2e413bf8d7d --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex @@ -0,0 +1,1242 @@ +% ====================================================================== +% scrlayer.tex +% Copyright (c) Markus Kohm, 2013 +% +% 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.txt. +% ---------------------------------------------------------------------- +% scrlayer.tex +% Copyright (c) Markus Kohm, 2013 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c 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 scrlayer of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Kapitel ueber scrlayer in der KOMA-Script-Anleitung +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{scrlayer.tex} + [$Date: 2013-12-13 17:39:21 +0100 (Fr, 13 Dez 2013) $ + KOMA-Script guide (chapter:scrlayer)] + +\translator{Markus Kohm} + +% Date of the translated file: 2013-10-31 + +\chapter[{Defining Layers and Page Styles Using \Package{scrlayer}}]% +{Defining Layers and Page Styles Using \Package{scrlayer}% +} +\labelbase{scrlayer} + +\BeginIndex{Package}{scrlayer} + +Most users of graphics software already know layer models for pages or working +sheets. \LaTeX{} itself does not know layers, but there are already packages +like \Package{eso-pic} or \Package{textpos}, that provide a kind of +background or foreground layer. \Package{scrlayer} is another package, +that provides such background and foreground layers, but in difference +to the other packages mentioned above these layers are part of the +page style definition. With this you may simply switch between usage +of layers by switching the page style. + +To do so, the package also supports a low level interface to define page +styles using a layer stack, to put layers onto a page style's layer stack, to +put layers at the lowest position of a page style's layer stack, to put layers +before or after a layer of a page style's layer stack, to remove a layer from +a page style's layer stack and to remove doublets of layers of a page style's +layer stack. In short words: The page style interface of \Package{scrlayer} +provides commands to define layer-stack-based page styles and to manage those +layer stacks. + +Nevertheless, using the layers directly is recommended for advanced users only. +End user interfaces for beginners or average users are provided by additional +packages, that load \Package{scrlayer} on their own. See +\autoref{cha:scrlayer-scrpage} in \autoref{part:forAuthors} of this +\iffree{manual}{book}. + +\section{State of Development Note} +\label{sec:scrlayer.draft} + +Development of this package has not been finished yet. Parts of the package +are even still experimental. Because of this, especially internal +functionality may be changed in future. Most likely the package will be +extended. And because of the early state of development, you should not expect +a complete and finished user manual. Nevertheless, this manual, which is +recommended for advanced users and developers, describes the current state of +development and the released parts of \Package{scrlayer}. Everything, not +documented here, should not be used for anything else but testing. + +\LoadCommon{0} % \section{Early or Late Selection of Options} + +\section{Some Generic Information} +\label{sec:scrlayer.generic} + +The package needs some generic information about the class. Class authors may +help \Package{scrlayer} by setting this information. Otherwise the package tries +to detect the information itself. This works, e.g., for the standard classes +and the \KOMAScript{} classes. But it may or may not fail with other classes. + +This section describes some of the information, that class authors may +provide. Generally users need not to care about this. + +\begin{Declaration} + \Macro{if@chapter}\ \PName{then code} \Macro{else}\ \PName{else code} + \Macro{fi}% +\end{Declaration} +\BeginIndex{Cmd}{if@chapter}% +If \Macro{if@chapter} is \Macro{iftrue}, \Package{scrlayer} will additionally +consider the chapter level, e.g., processing option \Option{automark}. If it +is defined, but differs from \Macro{iftrue}, only part, section, subsection, +sub\dots subsection, paragraph, subparagraph, sub\dots subparagraph will be +considered. If the macro is not defined, \Package{scrlayer} searches for +\Macro{chapter}. If \Macro{chapter} is defined and not \Macro{relax}, +\Package{scrlayer} will define \Macro{if@chapter} to \Macro{iftrue}, otherwise +\Macro{if@chapter} will become \Macro{iffalse}.% +\EndIndex{Cmd}{if@chapter} + +\begin{Declaration} + \Macro{if@mainmatter}\ \PName{then code} \Macro{else}\ \PName{else code} + \Macro{fi}% +\end{Declaration} +\BeginIndex{Cmd}{if@mainmatter}% +Classes like \Class{book} define \Macro{frontmatter}, \Macro{mainmatter}, and +\Macro{backmatter}. They also use \Macro{if@mainmatter} to distinguish whether +or not the current matter is the main matter. Classes like \Class{report} and +\Class{article} do not have \Macro{frontmatter}, \Macro{mainmatter}, or +\Macro{backmatter} and therefore also do not have \Macro{if@mainmatter}. + +For \Package{scrlayer} it's easier not to test always for the existence of the +matter commands, but to use \Macro{if@mainmatter} even with classes like +\Class{report} and \Class{article}, simply set to \Macro{iftrue}. So if +\Macro{if@mainmatter} is not defined, it will be defined to \Macro{iftrue}. + +Some classes have \Macro{frontmatter}, \Macro{mainmatter}, or +\Macro{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 \Macro{frontmatter}, \Macro{mainmatter}, and +\Macro{backmatter} to set \Macro{if@mainmatter} properly. Other matter +commands are not known, not tested, and not extended. So if there are other +matter commands \Package{scrlayer} needs help of the class author to set +\Macro{if@mainmatter} correctly.% +\EndIndex{Cmd}{if@mainmatter} + +\begin{Declaration} + \Macro{DeclareSectionNumberDepth}%^^A + \Parameter{level name}\Parameter{level depth} +\end{Declaration} +\BeginIndex{Cmd}{DeclareSectionNumberDepth}% +Generally each section level is related to an integer number indicating its +depth in the document structure. \LaTeX{} needs this to manage hierarchic +section levels. But normally only the document class, that defines the section +commands, itself knows that \PName{level depth} of a section level and uses +these numerical values inside the corresponding commands, when needed. + +But \Package{scrlayer} also needs information about the section hierarchy. +With command \Macro{DeclareSectionNumberDepth} you can map +the name of a heading level to a \PName{level depth}. With standard class +book, e.g., the \PName{level name} could be \PValue{part}, \PValue{chapter}, +\PValue{section}, \PValue{subsection}, \PValue{subsubsection}, +\PValue{paragraph}, or \PValue{subparagraph} and the corresponding +\PName{level depth}s would be -1, 0, 1, 2, 3, 4, and 5. + +Package \Package{scrlayer} tries to determine the \PName{level depth}s on its +own while loading and again while \Macro{begin}\PParameter{document}. But, if +it fails, i.\,e., if completely different section commands are used, it would +be useful, to be able to define the relationship explicitly. For such cases +\Macro{DeclareSectionNumberDepth} gives the class author the opportunity to +define the relationship explicitly.% +\EndIndex{Cmd}{DeclareSectionNumberDepth} + +\section{Declaration of Layers} +\label{sec:scrlayer.layers} + +A layer is a kind of virtual sheet of transparent paper (in opposite to a +physical sheet of paper). One layer is stacked onto another layer and opaque +material on one layer may hide material on the layers below. The stack of all +layers together makes the physical page. Package \Package{scrlayer} +provides two such layer stacks for each page: a background layer stack and a +foreground layer stack. The background layer stack is behind the normal page +contents, the foreground layer stack is above the normal page contents. So the +normal contents is a kind of a separating layer between the background layer +stack and the foreground layer stack. + +A layer has several attributes. The first attribute states, whether or not the +layer is part of the foreground or the background. During page building +background layers will be printed first, followed by the main contents and the +foreground layers. Therefore, in the output the background layers show up +behind the main contents and the foreground layers in front of the main +contents. By default, a layer is both, a background layer \emph{and} a +foreground layer and therefore will be printed twice. + +The horizontal position of the layer is set by the second attribute, the +vertical position by the third. The forth and fifth attributes determine the +horizontal and vertical size of the layer. As you can see, a layer may be +smaller or larger than the paper. + +But having two numerical values of the second and third attribute does not +directly give us the position of the layer on the page. For each dimension we +need two reference points, one on the page and one on the layer. The +numerical value than states the distance between these reference. +Reference points in layouts are also known as alignment and are set by the +sixth attribute. + +The seventh attribute states, whether or not a layer should be +printed onto left or right pages. By default a layer will be printed on both, +left and right pages. Note, that \LaTeX{} names left pages as even pages and +right pages as odd pages and that there are no left or even pages in +single-sided mode. + +The eighth attribute states, whether or not a layer should be printed in +single-side mode or in two-side mode. By default a layer will be printed in +both, single-side mode and two-side mode. Nevertheless, an even page layer will +never be printed in single-side mode and therefore is not really a two-side +mode layer. + +The ninth attribute is, whether or not a layer should be printed onto float +pages or non-float pages. \LaTeX{} produces float pages for float environments +like tables or figures, if they are allowed to be printed on a page without +normal page contents (see option \PValue{p} for \Environment{figure} or +\Environment{table}). So from some point of view a float page is a page, that +may itself flow. Non-float pages are not pages without floats, but pages, that +are not float pages. They may contain floats inside the text, on the top of +the page, or on the bottom of the page. Very large floats may seem to be page +floats, while in reality they are top floats. + +The tenth and last attribute is the contents of the layer. This is simply, +what should be printed, whenever the layer will be printed. + +So we have ten attributes yet. Below in this manual we will describe +additional attributes. However, they are just defined for convenience and can +be expressed by a combination of the ten attributes stated above. We call +these ten attributes the 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} +\BeginIndex{Cmd}{DeclareLayer}% +\BeginIndex{Cmd}{DeclareNewLayer}% +\BeginIndex{Cmd}{ProvideLayer}% +\BeginIndex{Cmd}{RedeclareLayer}% +\BeginIndex{Cmd}{ModifyLayer}% +These commands can be used to define a layer. The \PName{layer name} has to be +fully expandable and should expand to letters only. Some additional characters +are tolerated, but are not recommended. + +Command \Macro{DeclareLayer} 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 attribute defined by the \PName{option list}. +An +\PName{option} can be either a key or a key followed by an +equal sign followed by a value. Several options may be concatenated to +a \PName{option list} and have to be separated by comma. If you'd like to have +a comma or a white space inside the value of an option, you should put the +value inside curly brackets. See \autoref{tab:scrlayer.layerkeys} for +more information on keys, values, and the corresponding +attributes. + +In contrast to \Macro{DeclareLayer} using \Macro{DeclareNewLayer} results in +an error, if a layer with the same \PName{layer name} already exists. So you +may prevent yourself using the same \PName{layer name} more than once by +mistake. This would be useful, e.\,g., if a class or package also defines +layers internally. + +If you use \Macro{ProvideLayer} instead of \Macro{DeclareLayer}, the +declaration will be ignored in case a layer with the same layer name already +exists. It could be paraphrased by: \emph{declare the layer only, if it has not + been declared already.} + +If an existing layer should be redefined, \Macro{RedeclareLayer} or +\Macro{ModifyLayer} can be used. \Macro{RedeclareLayer} would simply define +the layer as if it would be defined newly. In difference to this, +\Macro{ModifyLayer} would change only those attributes, that are represented +by an option of the \PName{option list}. All other attributes will stay +unchanged and will not be reset to the initial default value. Using either +\Macro{RedeclareLayer} or \Macro{ModifyLayer} will result in an error, in case +there has not been a layer with \PName{layer name} defined before. + +\begin{desclist} + \desccaption{% + Options for the definition of page layers with description of the + corresponding layer attribute\label{tab:scrlayer.layerkeys}% + }{% + Options for the definition of layers (\emph{Continuation})% + }% + \nentry{\KOption{align}{\PName{alignment characters}}}{% + The \PName{alignment characters} define the desired alignment of the + layer. Each \PName{alignment character} influences either, how argument + \PName{length} of option \Option{hoffset} or \Option{voffset} will be + used. Several \PName{alignment characters} may be used together (without + comma or space) and will be interpreted in the order of occurrence. No + macros should be used here! Valid \PName{alignment character}s are: + \begin{description} + \item[\PValue{b} --] align the layer at its bottom edge; the + value of + \Option{voffset} is interpreted as the distance from the top edge of the + paper to the bottom edge 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}% + }% + \nentry{\KOption{area}{%^^A + \Parameter{hoffset}\Parameter{voffset}%^^A + \Parameter{width}\Parameter{height}}}{% + The composed option results in \OptionValue{hoffset}{\PName{hoffset}}, + \OptionValue{voffset}{\PName{voffset}}, + \OptionValue{width}{\PName{width}}, \OptionValue{height}{\PName{height}}.% + }% + \entry{\Option{background}}{% + Print the layer only in the background, but not in the foreground. This + makes a background-only layer in opposite to the default of layers which + are both, background and foreground layers and therefore would be printed + twice. The option does not expect any value. By the default the attribute + is not set.% + }% + \entry{\Option{bottommargin}}{% + The composed option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} to horizontally span + the paper from the left edge to the right and vertically span the area + below the footer down to the bottom edge of the paper.% + }% + \nentry{\KOption{clone}{\PName{layer name}}}{% + The composed 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}. Note, that \PName{layer name} has to be fully expandable and + should expand to letters only. Some additional characters are tolerated, + but are not recommended!% + }% + \nentry{\KOption{contents}{\PName{code}}}{% + The \PName{code} will be expanded whenever the layer is printed. So the + \PName{code} is what you will see. Code validity is not checked. So errors + in \PName{code} may result in several failures on each page, that prints + the layer.% + }% + \entry{\Option{evenpage}}{% + Print the layer on even pages only, but not on odd pages. The option does + not expect any value. By the default the option is not set and therefore + layers would be printed on odd pages and on even pages. Note, that this + attribute subsumes \Option{twoside}.% + }% + \entry{\Option{floatpage}}{% + Print the layer on float pages only, but not on other pages. The option + does not expect any value. By the default the attribute is not set and + therefore layers would be printed on float pages and on non-float pages.% + }% + \entry{\Option{foot}}{% + The composed option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} to horizontally span + the text area and vertically span the page footer defined by the new + \LaTeX{} length \Length{footheight}.% + }% + \entry{\Option{footskip}}{% + The composed option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} to horizontally span + the text area and vertically span the distance between the text area and + the page footer (note, that this is not the same like \Length{footskip}).% + }% + \entry{\Option{foreground}}{% + Print the layer only in the foreground, but not in the background. This + makes a foreground-only layer in opposite to the default of layers which + are both, background and foreground layers and therefore would be printed + twice. The option does not expect any value. By the default the attribute + is not set.% + }% + \entry{\Option{head}}{% + The composed option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} to horizontally span + the text area and vertically span the page head defined by usual \LaTeX{} + length \Length{headheight}.% + }% + \entry{\Option{headsep}}{% + The composed option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} to horizontally span + the text area and vertically span the distance between the page head and + the text area.% + }% + \nentry{\KOption{height}{\PName{length}}}{% + Sets the height of the layer. Note, that \PName{length} can either be a + \LaTeX{} length, declared using \Macro{newlength}, or a \TeX{} length, + declared using \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}.% + }% + \nentry{\KOption{hoffset}{\PName{length}}}{% + Sets the offset of the layer (depending on \Option{align} either left edge + of the layer, middle of the layer or right edge of the layer) from the + left edge of the paper. See \Option{height} for more information about + valid content of \PName{length}.% + }% + \entry{\Option{innermargin}}{% + The composed option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} to horizontally span + the distance between the right edge of text area and the right edge of the + paper on even pages or the distance between the left edge of the paper and + the left edge of the text area on odd pages and vertically span the whole + paper from the top edge to the bottom edge.% + }% + \entry{\Option{leftmargin}}{% + The composed option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} to horizontally span + the distance between the left edge of the paper and the left edge of the + text area and vertically span the whole paper from the top edge to the + bottom edge.% + }% + \entry{\Option{nonfloatpage}}{% + Restricts the layer to pages, that are not float pages. The option does + not expect any value. By the default the attribute is not set and + therefore layers would be printed on float pages and on non-float pages.% + }% + \entry{\Option{oddpage}}{% + Print the layer on odd pages only, but not on even pages. The option does + not expect any value. By the default the option is not set and therefore + layers would be printed on odd pages and on even pages.% + }% + \entry{\Option{oneside}}{% + Print the layer in single-side mode only, but not in two-side mode. The + option does not expect any value. By the default the attribute is not set + and therefore layers would be printed in single-side and two-side mode.% + }% + \entry{\Option{outermargin}}{% + The composed option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} to horizontally span + the distance between the left edge of the paper and the left edge of the + text area on even pages or the distance between the right edge of the text + area and the right edge of the paper on odd pages and vertically span the + whole paper from the top edge to the bottom edge.% + }% + \entry{\Option{page}}{% + The composed option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} to horizontally and + vertically span the whole paper from the left edge to the right edge and + the top edge to the bottom edge.% + }% + \entry{\Option{rightmargin}}{% + The composed option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} to horizontally span + the distance between the right edge of text area and the right edge of the + paper and vertically span the whole paper from the top edge to the bottom + edge.% + }% + \entry{\Option{textarea}}{% + The composed option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} to horizontally and + vertically span the whole text area from the left edge to the right edge + and the top edge to the bottom edge.% + }% + \entry{\Option{topmargin}}{% + The composed option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} to horizontally span + the whole page from the left edge to the right edge and vertically span + the distance between the top edge of the paper and the page head.% + }% + \entry{\Option{twoside}}{% + Print the layer in two-side mode only, but not in single-side mode. The + option does not expect any value. By the default the attribute is not set + and therefore layers would be printed in single-side and two-side mode.% + }% + \nentry{\KOption{voffset}{\PName{length}}}{% + Sets the offset of the layer (depending on \Option{align} either top edge + of the layer, middle of the layer or bottom edge of the layer) from the + top edge of the paper. See \Option{height} for more information about + valid content of \PName{length}.% + }% + \nentry{\KOption{width}{\PName{length}}}{% + Sets the width of the layer. See \Option{height} for more information + about valid content of \PName{length}.% + }% +\end{desclist} +% +\EndIndex{Cmd}{ModifyLayer}% +\EndIndex{Cmd}{RedeclareLayer}% +\EndIndex{Cmd}{ProvideLayer}% +\EndIndex{Cmd}{DeclareNewLayer}% +\EndIndex{Cmd}{DeclareLayer}% + +\begin{Declaration} + \Macro{layerxoffset}\\ + \Macro{layeryoffset}\\ + \Macro{layerwidth}\\ + \Macro{layerheight}% +\end{Declaration} +\BeginIndex{Cmd}{layerxoffset}% +\BeginIndex{Cmd}{layeryoffset}% +\BeginIndex{Cmd}{layerwidth}% +\BeginIndex{Cmd}{layerheight}% +These commands are valid during output of the layer's contents only. So they +can only be used inside the \PName{code} of option \Option{contents} of the +previously described commands. In this case they give the effective position +and dimension of the layer, that will be used for the output. However, the +effective dimension of the layer's contents may differ, i.\,e., if the +contents are oversized or do not fill the layer completely. Redefinition of +the commands to change the stored values is strictly forbidden and would +result in unpredictable issues.% +\EndIndex{Cmd}{layerheight}% +\EndIndex{Cmd}{layerwidth}% +\EndIndex{Cmd}{layeryoffset}% +\EndIndex{Cmd}{layerxoffset}% + +\begin{Declaration} + \Macro{IfLayerExists}% + \Parameter{string}\Parameter{then-code}\Parameter{else-code} +\end{Declaration} +\BeginIndex{Cmd}{IfLayerExists}% +This command may be used to execute code depending on whether or not a layer +has been defined already. If the layer exists \PName{then-code} will be +executed, otherwise \PName{else-code}. Note, the command cannot really +test whether a layer exists. It uses a heuristic, that will never be false +negative, but may be false positive. Nevertheless, if it is false positive +something went wrong, either an incompatible package has been used or the user +made something he should not do.% +\EndIndex{Cmd}{IfLayerExists} + +\begin{Declaration} + \Macro{DestroyLayer}\Parameter{layer name} +\end{Declaration} +\BeginIndex{Cmd}{DestroyLayer}% +This command sets all macros corresponding with the layer with given +\PName{layer name} to \Macro{relax}, if a layer with that name exists. As a result the layer cannot be used any longer. It does not matter, if the layer +is still part of the layer list of a page style, because such destroyed layers +will be ignored. Nevertheless, destroyed layers may be defined again using +\Macro{DeclareNewLayer} or \Macro{ProvideLayer}, but cannot be changed using +\Macro{RedeclareLayer} or \Macro{ModifyLayer} any longer. + +The command is intended to be used inside +\Macro{scrlayerOnAutoRemoveInterface} to remove layers, which have been +defined using removable macros of an interface, whenever the interface would +be removed.% +\EndIndex{Cmd}{DestroyLayer} + +\begin{Declaration} + \Macro{layercontentsmeasure}% +\end{Declaration} +\BeginIndex{Cmd}{layercontentsmeasure}% +The command \Macro{layercontentsmeasure} is internally used, if option +\Option{draft} has been set, so visualise the layers. The visualisation will +be done with a centimetre ruler at the top and left edge of the layer and an +inch ruler at the bottom and right edge of the layer. The rulers will be drawn +behind the content of the layer. If you would, you could also use it as +exclusive content of a layer.% +\EndIndex{Cmd}{layercontentsmeasure} + + +\section{Declaration and Management of Page Styles} +\label{sec:scrlayer.pagestyles} + +Until now we know layers, but we do not know how to use them. The +perhaps astonishing answer is: with page styles. In \LaTeX{}, page +styles usually define heads and foots of odd and even pages. + +The head and foot of odd pages will be printed on pages with odd +page number in two-side mode or on all pages in single-side mode. This is +something like the layer attributes \Option{oddpage} and \Option{evenpage}. + +The page head will be printed before the main contents of a page. The page +footer will be printed after the main contents of a page. So this is something +like the layer attributes \Option{background} and \Option{foreground}. + +So it's obvious to declare page styles to be a list of layers. But instead of +having only four attributes \Option{oddpage}, \Option{evenpage}, +\Option{background}, and \Option{foreground} all the attributes of layers +shown in \autoref{sec:scrlayer.layers} may be used. + +The outcome of this is that layer page styles are one type of page styles +\Package{scrlayer} provides. A layer page style consists of layers and +several \emph{hooks}. For description of layers see +\autoref{sec:scrlayer.layers}. The \emph{hooks} are points in the expansion +or execution of page styles and you may add additional code that will be +expanded there. Advanced users know this already from commands like +\Macro{AtBeginDocument} (see \cite{latex:usrguide}) or +\Macro{BeforeClosingMainAux} (see +\autopageref{desc:scrlfile.cmd.BeforeClosingMainAux}). + +Alias page styles are another type of page styles, provided by +\Package{scrlayer}. An alias page style simply consists of another page +style. In other words, the name of an alias page style is an alias name of +another page style, the aliased or original page style. Because of this, the +manipulation of an alias page style results in the manipulation of the +original page style. If the original page style is an alias page style too, +the manipulation will result in the manipulation of the aliased page style of +that original page style and so on until a real page style will be +manipulated. You may not only alias layer page styles made with +\Package{scrlayer}, but all kind of page styles. + +\begin{Declaration} + \Macro{currentpagestyle} +\end{Declaration} +\BeginIndex{Cmd}{currentpagestyle}% +Package scrlayer patches \Macro{pagestyle} to set \Macro{currentpagestyle} to +the currently active page style. Note, \Macro{thispagestyle} does not +change \Macro{currentpagestyle}. But if you use \Macro{thispagestyle} the +result of \Macro{currentpagestyle} may be changed while execution of the +\LaTeX{} output routine. This may be relevant only, if +\Macro{currentpagestyle} has been used protected until execution of the output +routine. + +Note, the layer page styles described later in this section, will not need +the patch of \Macro{pagestyle} to set \Macro{currentpagestyle}. The patch has +been made for usage with other page styles. Note also, +\Macro{currentpagestyle} is empty before the first \Macro{pagestyle} after +loading \Package{scrlayer}. So if you define an end user page style interface, +it may be useful to use an implicit \Macro{pagestyle} to set the current page +style to a default page style.% +\EndIndex{Cmd}{currentpagestyle} + +\begin{Declaration} + \Macro{BeforeSelectAnyPageStyle}\Parameter{code}\\ + \Macro{AfterSelectAnyPageStyle}\Parameter{code}%^^A +\end{Declaration} +\BeginIndex{Cmd}{BeforeSelectAnyPageStyle}% +\BeginIndex{Cmd}{AfterSelectAnyPageStyle}% +The command \Macro{BeforeSelectAnyPageStyle} adds \PName{code} to the hook +that will be executed inside of \Macro{pagestyle} just before the page style +will be selected. You may use \texttt{\#1} as a placeholder for the argument +of \Macro{pagestyle}. + +The command \Macro{AfterSelectAnyPageStyle} is similar, but the \PName{code} +will be executed just after the page style has been selected and after +\Macro{currentpagestyle} has been set to the name of real page style. + +Note\textnote{Attention!}, \PName{code} of both commands will be executed +only, if a page style will be selected using \Macro{pagestyle}, but not, +e.\,g., if a page style will be selected using \Macro{thispagestyle}. Note +also, you cannot remove \PName{code} from the hook after adding it. But +the \PName{code} will be added locally, so you may use a group to limit the +scope of \PName{code}.%^^A +\EndIndex{Cmd}{AfterSelectAnyPageStyle} +\EndIndex{Cmd}{BeforeSelectAnyPageStyle} + +\begin{Declaration} + \Macro{DeclarePageStyleAlias}% + \Parameter{alias page style name}\Parameter{original page style name}\\ + \Macro{DeclareNewPageStyleAlias}% + \Parameter{alias page style name}\Parameter{original page style name}\\ + \Macro{ProvidePageStyleAlias}% + \Parameter{alias page style name}\Parameter{original page style name}\\ + \Macro{RedeclarePageStyleAlias}% + \Parameter{alias page style name}\Parameter{original page style name} +\end{Declaration} +\BeginIndex{Cmd}{DeclarePageStyleAlias}% +\BeginIndex{Cmd}{DeclareNewPageStyleAlias}% +\BeginIndex{Cmd}{ProvidePageStyleAlias}% +\BeginIndex{Cmd}{RedeclarePageStyleAlias}% +These commands may be used to define a page style with name \PName{alias page + style name} that is simply an alias for an already existing page style with +name \PName{original page style name}. If there's already a page style +\PName{alias page style name} it will be destroyed before creating the alias +using \Macro{DeclarePageStyleAlias} or \Macro{RedeclarePageStyleAlias}. + +\Macro{DeclareNewPageStyleAlias} will throw an error message, if a page style +\PName{alias page style name} has already been defined before. It does not +matter if the already defined page style is a layer page style, an alias page +style or another page style. + +\Macro{ProvidePageStyleAlias} will define the alias only, if a page style +\PName{alias page style name} has not been defined before. If a page style +\PName{alias page style name} already exists nothing will be done. + +\Macro{RedeclarePageStyleAlias} expects an already existing page style +\PName{alias page style name}. It will destroy that page style and afterwards +define the alias. If the page style \PName{alias page style name} does not +exist, then you will get an error.% +\EndIndex{Cmd}{RedeclarePageStyleAlias}% +\EndIndex{Cmd}{ProvidePageStyleAlias}% +\EndIndex{Cmd}{DeclareNewPageStyleAlias}% +\EndIndex{Cmd}{DeclarePageStyleAlias} + +\begin{Declaration} + \Macro{DestroyPageStyleAlias}\Parameter{page style name}% +\end{Declaration} +\BeginIndex{Cmd}{DestroyPageStyleAlias}% +This command makes the page style with given \PName{page style name} +\LaTeX-undefined, if it is an alias for another page style. After this, the +page style may be defined newly with, e.g., \Macro{DeclareNewAliasPageStyle} +or \Macro{ProvideAliasPageStyle}. + +The command is intended to be used inside of +\Macro{scrlayerOnAutoRemoveInterface} to remove page styles that have been +declared by an interface and uses removable macros of that interface.% +\EndIndex{Cmd}{DestroyPageStyleAlias} + +\begin{Declaration} + \Macro{GetRealPageStyle}\Parameter{page style name}% +\end{Declaration} +\BeginIndex{Cmd}{GetRealPageStyle}% +The command will result in the (recursive) real page name of the page style, +if the page style with given name \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 would be simply \PName{page + style name}. The command is fully expandable and may be used, e.g., in the +second argument of \Macro{edef}.% +\EndIndex{Cmd}{GetRealPageStyle} + +\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{Cmd}{DeclarePageStyleByLayers}% +\BeginIndex{Cmd}{DeclareNewPageStyleByLayers}% +\BeginIndex{Cmd}{ProvidePageStyleByLayers}% +\BeginIndex{Cmd}{RedeclarePageStyleByLayers}% +These commands declare a page style with \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, the \PName{page style name} and the +layer names at the \PName{layer list} must be fully expandable and should +expand to letters. Several other characters are tolerated, but, +nevertheless, are not recommended. + +The \PName{option list} is a comma separated list of +\OptionValue{\PName{key}}{\PName{value}} options. 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 \emph{hooks}. See the introduction to this +section for more general information about \emph{hooks}. See +\autoref{tab:scrlayer.pagestyle.hooks} for more information about the hooks +and their purpose. + +\begin{desclist} + \desccaption{% + The \emph{hook} options for page styles (in order of + execution)\label{tab:scrlayer.pagestyle.hooks}% + }{% + The \emph{hook} options for page styles (\emph{Continuation})% + }% + \entry{\KOption{onselect}\PName{code}}{% + Execute \PName{code} whenever the page style will be selected using, e.g., + \Macro{pagestyle}. Note\textnote{Attention!}, \Macro{thispagestyle} + does not select the page style immediately, but asynchronously inside + \LaTeX's output routine.% + }% + \entry{\KOption{oninit}\PName{code}}{% + Execute \PName{code} whenever the output of the layers of a page style + will be initialised. Note\textnote{Attention!}, this will be done + twice for every page: once for background layers and once for foreground + layers.% + }% + \entry{\KOption{ononeside}\PName{code}}{% + Execute \PName{code} whenever the output of the layers of a page style in + single-side mode will initialised. Note\textnote{Attention!}, this + will be done twice for every page: once for background layers and once for + foreground layers.% + }% + \entry{\KOption{ontwoside}\PName{code}}{% + Execute \PName{code} whenever the output of the layers of a page style in + two-side mode will initialised. Note\textnote{Attention!}, this will + be done twice for every page: once for background layers and once for + foreground layers.% + }% + \entry{\KOption{onoddpage}\PName{code}}{% + Execute \PName{code} whenever the output of the layers of a page style on + an odd page will initialised. Note\textnote{Attention!}, this will be + done twice for every page: once for background layers and once for + foreground layers. Note\textnote{Attention!} also, in single-side + mode all pages are odd pages, not only pages with odd page numbers.% + }% + \entry{\KOption{onevenpage}\PName{code}}{% + Execute \PName{code} whenever the output of the layers of a page style on + an even page will initialised. Note\textnote{Attention!}, this will + be done twice for every page: once for background layers and once for + foreground layers. Note\textnote{Attention!} also, there are not even + pages in single-side mode, but all pages are odd pages, not only pages + with odd page numbers.% + }% + \entry{\KOption{onfloatpage}\PName{code}}{% + Execute \PName{code} whenever the output of the layers of a page style on + a float page will initialised. Note\textnote{Attention!}, this will + be done twice for every page: once for background layers and once for + foreground layers. Note\textnote{Attention!} also, float pages are + only those pages with p-placed floating objects.% + }% + \entry{\KOption{onnonfloatpage}\PName{code}}{% + Execute \PName{code} whenever the output of the layers of a page style on + a non-float page will initialised. Note\textnote{Attention!}, this + will be done twice for every page: once for background layers and once for + foreground layers. Note\textnote{Attention!} also, non-float pages + are all pages that are not float-pages. Those pages may have t-placed, + h-placed, b-placed, or no floating objects.% + }% + \entry{\KOption{onbackground}\PName{code}}{% + Execute \PName{code} whenever the output of the layers of a page style in + the background of a page will initialised. Note\textnote{Attention!}, + this will be done once for every page.% + }% + \entry{\KOption{onforeground}\PName{code}}{% + Execute \PName{code} whenever the output of the layers of a page style in + the foreground of a page will initialised. Note\textnote{Attention!}, + this will be done once for every page.% + }% +\end{desclist} + +The difference of \Macro{DeclarePageStyleByLayers} and +\Macro{DeclareNewPageStyleByLayers} is that \Macro{DeclareNewPageStyleByLayers} +will result in an error, if a page style with name \PName{page style name} +already exists. Note, declaring a page style, which is an alias of another +page style (see \Macro{DeclareAliasPageStyle} prior in this section), will not +re-declare the page style itself, but it's real page style (see +\Macro{GetRealPageStyle} prior in this section). + +The difference of \Macro{DeclarePageStyleByLayers} and +\Macro{ProvidePageStyleByLayers} is that \Macro{ProvidePageStyleByLayers} +will simply do nothing, if there's already a page style with name \PName{page + style name}. In difference to \Macro{DeclareNewPageStyleByLayers} it will not +raise an error in this case. + +The difference of \Macro{DeclarePageStyleByLayers} and +\Macro{RedeclarePageStyleByLayers} is, that \Macro{RedeclarePageStyleByLayers} +may be used only, if the real page style of \PName{page style name} already +exists. Otherwise an error would occur. + +Please have also a look at the notes to following pseudo page style +\Pagestyle{@everystyle@}.% +\EndIndex{Cmd}{RedeclarePageStyleByLayers}% +\EndIndex{Cmd}{ProvidePageStyleByLayers}% +\EndIndex{Cmd}{DeclareNewPageStyleByLayers}% +\EndIndex{Cmd}{DeclarePageStyleByLayers}% + +\begin{Declaration} + \Pagestyle{@everystyle@}\\ + \Pagestyle{empty} +\end{Declaration} +\BeginIndex{Pagestyle}{@everysel@}% +\BeginIndex{Pagestyle}{empty}% +There are two somehow special, default layer page styles. The first one is +\Pagestyle{@everystyle@}. This page style should not be used normally, but the +layers of this page style will be used by all the other layer page styles. So +adding a layer to this page style would be similar to adding this layer to all +other layer page styles even the empty one. There's one difference: Layer +referencing commands of the page style interface like +\Macro{ForEachLayerOfPageStyle}, \Macro{AddLayerToPageStyleBeforeLayer}, or +\Macro{AddLayerToPageStyleAfterLayer} ignore the layers of +\Pagestyle{@everystyle@} if they are used for another layer page style. + +The other somehow special page style is \Pagestyle{empty}. Normally page style +\Pagestyle{empty} is defined by the \LaTeX{} kernel, to be a page style +without page head or page foot. Package \Package{scrlayer} re-defines it to be +a layer page style without any layer. Nevertheless, you may use it like every +other layer page style too. The main advantage above the \LaTeX{} kernel's +empty page style is that it also executes the layers of special layer page +style \Pagestyle{@everysel@}.% +\EndIndex{Pagestyle}{empty}% +\EndIndex{Pagestyle}{@everysel@}% + +\begin{Declaration} + \KOption{onpsselect}\PValue{code}\\ + \KOption{onpsinit}\PValue{code}\\ + \KOption{onpsoneside}\PValue{code}\\ + \KOption{onpstwoside}\PValue{code}\\ + \KOption{onpsoddpage}\PValue{code}\\ + \KOption{onpsevenpage}\PValue{code}\\ + \KOption{onpsfloatpage}\PValue{code}\\ + \KOption{onpsnonfloatpage}\PValue{code}\\ + \KOption{onpsbackground}\PValue{code}\\ + \KOption{onpsforeground}\PValue{code} +\end{Declaration} +\BeginIndex{Option}{onpsselect~=\PName{code}}% +\BeginIndex{Option}{onpsinit~=\PName{code}}% +\BeginIndex{Option}{onpsoneside~=\PName{code}}% +\BeginIndex{Option}{onpstwoside~=\PName{code}}% +\BeginIndex{Option}{onpsoddpage~=\PName{code}}% +\BeginIndex{Option}{onpsevenpage~=\PName{code}}% +\BeginIndex{Option}{onpsfloatpage~=\PName{code}}% +\BeginIndex{Option}{onpsnonfloatpage~=\PName{code}}% +\BeginIndex{Option}{onpsbackground~=\PName{code}}% +\BeginIndex{Option}{onpsforeground~=\PName{code}}% +There's also a \KOMAScript{} option for each of those \texttt{hooks}. The +names of the \KOMAScript{} options are similar to the names of the page style +options, but with ``\texttt{ps}'' inserted behind ``\texttt{on}''. The value of +the \KOMAScript{} options are the initial defaults of the corresponding +\texttt{hooks}. This default will be extended by every usage of the page style +options at the \PName{option list}. You may remove the default, using +\Macro{ModifyLayerPageStyleOptions} described later in this section.% +\EndIndex{Option}{onpsforeground~=\PName{code}}% +\EndIndex{Option}{onpsbackground~=\PName{code}}% +\EndIndex{Option}{onpsnonfloatpage~=\PName{code}}% +\EndIndex{Option}{onpsfloatpage~=\PName{code}}% +\EndIndex{Option}{onpsevenpage~=\PName{code}}% +\EndIndex{Option}{onpsoddpage~=\PName{code}}% +\EndIndex{Option}{onpstwoside~=\PName{code}}% +\EndIndex{Option}{onpsoneside~=\PName{code}}% +\EndIndex{Option}{onpsinit~=\PName{code}}% +\EndIndex{Option}{onpsselect~=\PName{code}}% + +\begin{Declaration} + \KOption{deactivatepagestylelayers}\PName{simple switch}\\ + \Macro{ForEachLayerOfPageStyle}\Parameter{page style name}\Parameter{code} +\end{Declaration} +\BeginIndex{Cmd}{ForEachLayerOfPageStyle}% +As long as \KOMAScript{} option \Option{deactivatepagestylelayers} has not been +activated command \Macro{ForEachLayerOfPageStyle} can be used to process +\PName{code} for every layer that is a member of the layers list of a page +style with given \PName{page style name}. Inside of \PName{code} the place +holder \PValue{\#1} may be used for the name of the current layer. +\begin{Example} + If you want to output the names of all layers of page style + \PValue{scrheadings}, you may us: +\begin{lstcode} + \let\commaatlist\empty + \ForEachLayerOfPageStyle{scrheadings}{% + \commaatlist#1\gdef\commaatlist{, }} +\end{lstcode} +\end{Example} +Usage of \Macro{gdef} instead of \Macro{def} is necessary in the example +above, because \Macro{ForEachLayerOfPageStyle} executes the \PName{code} +inside of a group to minimise side effects. Here \Macro{gdef} redefines +\Macro{commaatlist} globally, so it would be still valid at the execution of +\PName{code} for the next layer. + +Several other commands of \Package{scrlayer} also +use \Macro{ForEachLayerOfPageStyle} internally. So these also do not process +any layer if \KOMAScript{} option \Option{deactivatepagestylelayers} would be +activated. So you may use this options, e.g., to hide all layers of all layer +page styles.% +\EndIndex{Cmd}{ForEachLayerOfPageStyle}% + +\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{Cmd}{AddLayersToPageStyle}% +\BeginIndex{Cmd}{AddLayersAtBeginOfPageStyle}% +\BeginIndex{Cmd}{AddLayersAtEndOfPageStyle}% +\BeginIndex{Cmd}{RemoveLayersFromPageStyle}% +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 will be referenced by it +\PName{page style name}. The layers are given by a comma separated +\PName{layer list}. + +The commands \Macro{AddLayersToPageStyle} and \Macro{AddLayersAtEndOfPageStyle} +add all layers of the comma separated list of layers \PName{layer list} at +the end of the layer list of layer page style \PName{page style + name}. Logically the added layers would be above or in front of the old +layers of the page style. Nevertheless, new background layers would be behind +the text layer and therefore behind all foreground layers. + +Command \Macro{AddLayersAtBeginOfPageStyle} adds the new layers at the begin +of the layer list of the page style. Note, the layers +will be added in the order of the \PName{layer list}. The first layer at +\PName{layer list} will be added first, the second layer will be added second +and so on. So with \Macro{AddLayersAtBeginOfPageStyle} the last layer at +\PName{layer list} will become the new first layer of the layer list of layer +page style \PName{page style name}. + +Command \Macro{RemoveLayersFromPageStyle} may be used to remove layers from +the layer list of layer page style \PName{page style name} instead of adding +them. Note, layers, which are part of \PName{layer list}, but not part of +the page style's layer list, will be ignored. But adding or removing layers +from a page style, which is not a layer page style or an alias of a layer page +style, would be a mistake and result in an error message.% +\EndIndex{Cmd}{RemoveLayersFromPageStyle}% +\EndIndex{Cmd}{AddLayersAtEndOfPageStyle}% +\EndIndex{Cmd}{AddLayersAtBeginOfPageStyle}% +\EndIndex{Cmd}{AddLayersToPageStyle} + +\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{Cmd}{AddLayersToPageStyleBeforeLayer}% +\BeginIndex{Cmd}{AddLayersToPageStyleAfterLayer}% +These commands are similar to the commands described before, but they do not +add the layers at the begin or end of the layer list of a layer page style, +but just before or after a reference layer at the layer list of a layer page +style. Note, in this case the order of the \PName{layer list} will be +same in the layer list of \PName{page style name} after adding. If the +reference layer named \PName{reference layer name} is not part of the layer +list of the layer page style, nothing happens.% +\EndIndex{Cmd}{AddLayersToPageStyleAfterLayer}% +\EndIndex{Cmd}{AddLayersToPageStyleBeforeLayer} + +\begin{Declaration} + \Macro{UnifyLayersAtPageStyle}\Parameter{page style name} +\end{Declaration} +\BeginIndex{Cmd}{UnifyLayersAtPageStyle}% +With the commands described before in this section you may not only add +different layers to a page style, but even add the same layer several times to +a page style. In most cases it does not make sense to have one layer several +times at the layer list of a layer page style. So you may use +\Macro{UnifyLayersAtPageStyle} to remove all dupes of layers from the layer +list of a layer page style. + +Note\textnote{Attention!}, the order of layers may change! So if +you want a special order, you should remove all layers and add the layers in +the order you want instead of using \Macro{UnifyLayersAtPageStyle}.% +\EndIndex{Cmd}{UnifyLayersAtPageStyle} + +\begin{Declaration} + \Macro{ModifyLayerPageStyleOptions}% + \Parameter{page style name}\Parameter{option list}\\ + \Macro{AddToLayerPageStyleOptions}% + \Parameter{page style name}\Parameter{option list} +\end{Declaration} +\BeginIndex{Cmd}{ModifyLayerPageStyleOptions}% +\BeginIndex{Cmd}{AddToLayerPageStyleOptions}% +Command \Macro{ModifyLayerPageStyleOptions} may be used to modify the page +style options of a layer page style. Only options at the comma separated +\PName{option list} will be set to the new values given in \PName{option list} +if the new value is not empty. Options, which are not at \PName{option list}, +will stay unchanged. If you want to set an option to \emph{do nothing} you may +use value \Macro{relax}. Note, setting an option to a new value using +\Macro{ModifyLayerPageStyleOptions} will remove the previous value including +the global default value. + +\Macro{AddToLayerPageStyleOptions} differs from +\Macro{ModifyLayerPageStyleOptions} in that point. It will not overwrite the +previous values, but adds\,---\,or more precisely: concatenates\,---\, the new +values to the previous values of the options at \PName{option list}.% +\EndIndex{Cmd}{AddToLayerPageStyleOptions}% +\EndIndex{Cmd}{ModifyLayerPageStyleOptions}% + +\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{Cmd}{IfLayerPageStyleExists}% +\BeginIndex{Cmd}{IfRealLayerPageStyleExists}% +Command \Macro{IfLayerPageStyleExists} tests, whether or not the real page +style of \PName{page style name} is a layer page style. If the test is true, +\PName{then code} will be executed. If \PName{page style name} is neither a +layer page style, nor an alias of a layer page style, nor an alias of an alias +of \dots\ a layer page style, \PName{else code} will be executed. 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 with a layer page style. + +Command \Macro{IfRealLayerPageStyleExists} is similar, but \PName{then code} +will only be executed, if \PName{page style name} itself is the name of a +layer page style. So \PName{else code} will even be executed, if \PName{page + style name} is an alias name of a layer page style or the alias name of an +alias name of \dots\ a layer page style.% +\EndIndex{Cmd}{IfRealLayerPageStyleExists}% +\EndIndex{Cmd}{IfLayerPageStyleExists}% + +\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{IfLayerAtPageStyle}% + \Parameter{page style name}\Parameter{layer list}% + \Parameter{then code}\Parameter{else code}% +\end{Declaration} +\BeginIndex{Cmd}{IfLayerAtPageStyle}% +\BeginIndex{Cmd}{IfSomeLayersAtPageStyle}% +\BeginIndex{Cmd}{IfLayersAtPageStyle}% +Command \Macro{IfLayerAtPageStyle} may be used to test, whether or not a layer +named \PName{layer name} is a member of the layer list of a given page +style. If the test is true, the \PName{then code} will be executed. If the +layer is not a member of the layer list of \PName{page style name}, the +\PName{else code} will be executed. + +Commands \Macro{IfSomeLayerAtPageStyle} and \Macro{IfLayersAtPageStyle} do not +only test one layer but several layers at a given, comma separated +\PName{layer list}. \Macro{IfSomeLayerAtPageStyle} will execute the +\PName{then code} if \emph{at least one} of the layers at \PName{layer list} +is a member of the layer list of \PName{page style name}. In difference +\Macro{IfLayersAtPageStyle} executes the \PName{then code} only, if \emph{all} +of the layers at \PName{layer list} are members of the layer list of +\PName{page style name}.% +\EndIndex{Cmd}{IfLayersAtPageStyle}% +\EndIndex{Cmd}{IfSomeLayersAtPageStyle}% +\EndIndex{Cmd}{IfLayerAtPageStyle} + +\begin{Declaration} + \Macro{DestroyRealLayerPageStyle}\Parameter{page style name} +\end{Declaration} +\BeginIndex{Cmd}{DestroyRealLayerPageStyle}% +Command \Macro{DestroyRealLayerPageStyle} makes the page style named +\PName{page style name} undefined, if and only if it is a layer page +style. Nothing will be happen if it is an alias name of a layer page style, if +it is another page style, or if it is not a page style. + +If \PName{page style name} is the name of the current page style the current +page style will become a kind of empty page style. If the special page +style\,---\,this may be set using \Macro{thispagestyle}\,---\,is \PName{page + style name}, this will be simply reset. So the previous +\Macro{thispagestyle} will become invalid. + +Note, the layers of the page style will not be destroyed +automatically. If you want to destroy the layers too, you may use +\begin{lstcode} + \ForEachLayerOfPageStyle{...}{\DestroyLayer{#1}} +\end{lstcode} +\emph{before} destroying the layer page style. + +The command is intended to be used inside the auto-remove code of an interface +See \autoref{sec:scrlayer.enduserinterfaces} below for more information about +auto-remove code.% +\EndIndex{Cmd}{DestroyRealLayerPageStyle} + +\LoadCommon{20} % \section{Height of Page Head and Foot} + +\LoadCommon{21} % \section{Manipulation of Defined Page Styles} + +\section{End User Interfaces} +\label{sec:scrlayer.enduserinterfaces} + +Package \Package{scrlayer} provides an interface to define and manage +(concurrent) end user interfaces. Maybe future releases of \KOMAScript{} will +provide parts of this by package \Package{scrbase} and remove those commands +from \Package{scrlayer}. But currently this part if \Package{scrlayer} is very +experimental, so package \Package{scrlayer} provides its own interface +definition commands. Currently you should not depend on correct working of +auto-removing a concurrent end user interface. Instead you should avoid using +concurrent end user interfaces. + +This section only describes the interface commands for defining end user +interfaces. This is not interesting for end users, but only for authors of end +user interfaces. End users will find information about the end user interfaces +in the sections about the particular end user interface, e.g., +\autoref{cha:scrlayer-scrpage}, \autoref{cha:scrlayer-scrpage-experts}, and +\autoref{cha:scrlayer-notecolumn}. + +\begin{Declaration} + \Macro{scrlayerInitInterface}\OParameter{interface name} +\end{Declaration} +\BeginIndex{Cmd}{scrlayerInitInterface}% +Command \Macro{scrlayerInitInterface} +registers a new interface. The \PName{interface name} must be unique. If you +try to initialise an already initialised interface an error will occur. This +command is obligatory and mandatory for interfaces. It should be the first +interface command and therefore has been described first. If the optional +argument is omitted, \PValue{\Macro{@currname}.\Macro{@currext}} will be +used instead. For classes and packages this will be the file name of the class +or package while loading the class or package. But you may use any sequence of +characters with category letter or other.% +\EndIndex{Cmd}{scrlayerInitInterface} + +\begin{Declaration} + \KOption{forceoverwrite}\PName{simple switch}\\ + \KOption{autoremoveinterfaces}\PName{simple switch}\\ + \Macro{scrlayerAddToInterface}% + \OParameter{interface name}\Parameter{command}\Parameter{code}\\ + \Macro{scrlayerAddCsToInterface}% + \OParameter{interface name}\Parameter{command sequence}\Parameter{code} +\end{Declaration} +\BeginIndex{Option}{forceoverwrite}% +\BeginIndex{Option}{autoremoveinterfaces}% +\BeginIndex{Cmd}{scrlayerAddToInterface}% +\BeginIndex{Cmd}{scrlayerAddCsToInterface}% +One of the special features of end user interfaces is that they should +register all interface dependent commands (also known as \emph{macros}). You +may do this using \Macro{scrlayerAddToInterface}%^^A +. If your interface generates macros not only at load time but also at run +time or if the interface name should not be the class's or package's name, you +have to use the optional argument to add the command to a dedicated +interface. An error will occur, if the interface has not been initialised +before. + +The first mandatory argument is the \PName{command}\footnote{The + \PName{command} consists of the backslash followed by a \PName{command + sequence} consisting of characters with category code letter or one other + character, or \PName{command} consists of one active character (without + backslash).} that should be added to the interface. If the command can be +added to the interface, it will be added to the interface, will be set to +\Macro{relax} and \PName{code} will be executed. You can use, e.g., +\Macro{newcommand}\PName{command} inside of \PName{code} to define +\PName{command}. + +But when can a command be defined? If a command is undefined or \Macro{relax} +it can be defined. If a command has already been defined and registered for +another interface \emph{and} if \KOMAScript{} option +\Option{autoremoveinterface} has been switched on, the other interface will be +removed automatically and the new command will be set to \Macro{relax} and +will be registered for the given interface. If a command +has already been defined but is not part of another interface \emph{and} if +\KOMAScript{} option \Option{forceoverwrite} has been switched on, the command +will be set to \Macro{relax} and will be registered for the given interface. + +Command \Macro{scrlayerAddCsToInterface} is similar to +\Macro{scrlayerAddToInterface} but does not expect a command as first, +mandatory argument, but a command sequence\footnote{A command sequence may + consist of any characters with category code letter or other.}.% +\EndIndex{Cmd}{scrlayerAddCsToInterface}% +\EndIndex{Cmd}{scrlayerAddToInterface} +\EndIndex{Option}{autoremoveinterfaces}% +\EndIndex{Option}{forceoverwrite}% + +\begin{Declaration} + \Macro{scrlayerOnAutoRemoveInterface}%^^A + \OParameter{interface name}\Parameter{code} +\end{Declaration} +\BeginIndex{Cmd}{scrlayerOnAutoRemoveInterface}% +Command \Macro{scrlayerOnAutoRemoveInterface} +registers \PName{code} to be executed, if the interface will be automatically +removed (see \Option{autoremoveinterfaces} prior in this section). This may be +used, e.g., to automatically destroy layers or page styles (see +\Macro{DestroyLayer}, \Macro{DestroyAliasPageStyle}, and +\Macro{DestroyRealLayerPageStyle}).% +\EndIndex{Cmd}{scrlayerOnAutoRemoveInterface}% +% +\EndIndex{Package}{scrlayer} + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: us-ascii +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide" +%%% End: + + |