path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex

% ======================================================================
% scrlayer.tex
% Copyright (c) Markus Kohm, 2013-2015
%
% 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-2015
%
% 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: 2015-11-06 10:16:26 +0100 (Fri, 06 Nov 2015) $
                  KOMA-Script guide (chapter:scrlayer)]

\translator{Markus Kohm}

% Date of the translated file: 2015-11-06

\chapter[{Defining Layers and Page Styles Using \Package{scrlayer}}]%
{Defining Layers and Page Styles Using \Package{scrlayer}%
}
\labelbase{scrlayer}

\BeginIndex{Package}{scrlayer}%
\BeginIndex{}{layer}%
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}
\seclabel{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}
\seclabel{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}
\seclabel{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, which are the answers to some basic questions:
\begin{description}
\item[Is the layer part of the background or the
  foreground?\textnote{background or foreground}]%
  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. Normally, it makes sense to restrict the layer in this aspect.
\item[What is the position of the layer?\textnote{horizontal and vertical
    position}]%
  There are some attributes to define the horizontal and the vertical position
  of a layer.
\item[What is the size of the layer?\textnote{horizontal and vertical size}]%
  As for the position there are several attributes to define the width and
  height of a layer. So a layer can also be smaller or larger than the paper
  and it can be placed everywhere on the paper.
\item[How is a layer aligned on the paper?\textnote{alignment}]%
  This question is answered by the alignment attribute. The horizontal position
  can be relative from the left edge of the paper either to the left edge of
  the layer or to the centre of the layer or to the right edge of the
  layer. Also the vertical position can be relative from the to edge of the
  paper either to the top edge of the layer or to the centre of the layer or
  to the bottom edge of the layer.
\item[Is the layer intended for text or picture output?\textnote{text or
    picture}]%
  This question is also related to the position. For picture output users
  often expect the origin at the bottom left corner of the layer. But this
  would not be suitable for text output. So 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 span a
  \Environment{picture}\IndexEnv{picture} environment and provide addition
  positioning commands.
\item[Should the layer be printed on left or right pages?\textnote{left or
    right page}]%
  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.
\item[Should the layer be printed in single-side mode or two-side
  mode?\textnote{single-side or two-side}]%
  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.
\item[Should the layer be printed on float pages or non-float
  pages?\textnote{float page or non-float page}]%
  \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.
\item[What are the contents of the layer?\textnote{contents}]%
  The corresponding attribute are the commands that produce the output.
\end{description}
So we have eight questions that immediately result in 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 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}
\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})%
  }%
  \entry{%
    \ChangedAt{v3.16}{\Package{scrlayer}}%
    \KOption{addcontents}\PName{Code}}{%
    Value \PName{code} will be added (or appended) at the very end of the
    current value of attribute \Option{contents}. So the new content will be
    generated behind the end of the already existing content. For more
    information about the handling of \PName{code} see option
    \Option{contents}.%
  }%
  \entry{%
    \ChangedAt{v3.16}{\Package{scrlayer}}%
    \KOption{addheight}\PName{additional height}}{%
    The current value of attribute \Option{height} 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}}%
    \KOption{addhoffset}\PName{additional horizontal offset}}{%
    The current value of attribute \Option{hoffset} 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}}%
    \KOption{addvoffset}\PName{additional vertical offset}}{%
    The current value of attribute \Option{voffset} 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}}%
    \KOption{addwidth}\PName{additional width}}{%
    The current value of attribute \Option{width} 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} 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}%
  }%
  \entry{\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{\ChangedAt{v3.18}{\Package{scrlayer}}%
    \Option{backandforeground}}{%
    This option removes any foreground or background restriction of the layer.
    Generally usage of this option makes no sense, but it is provided for
    completeness of the user interface. The option does not expect any value.%
  }%
  \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.%
  }%
  \entry{\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!%
  }%
  \entry{\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{\ChangedAt{v3.18}{\Package{scrlayer}}%
    \Option{everypage}}{%
    This is a combination of \Option{oddorevenpage} and
    \Option{floatornonfloatpage}. The option does not expect any value.%
  }%
  \entry{\Option{everyside}}{%
    This option removes any restriction of the layer to single side or double
    side printing. This is also the default of layers.  The option does not
    expect any value.%
  }%
  \entry{\ChangedAt{v3.18}{\Package{scrlayer}}%
    \Option{floatornonfloatpage}}{%
    This option removes any restriction of the layer to float or non-float
    pages. So the layer will be printed independent of whether a page is a
    float page or not. This is also the default of layers.  The option does
    not expect any value.%
  }%
  \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.%
  }%
  \entry{\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}.%
  }%
  \entry{\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{\ChangedAt{v3.19}{\Package{scrlayer}}%
    \KOption{mode}\PName{mode}}{%
    The primary option defines the \PName{mode} for the layer output. Default
    is \OptionValue{mode}{text}. The Baseline of the first text line will be
    placed the height of one standard text line below the top edge of the
    layer. Therefore the text output will be top aligned in the layer. In
    \PValue{picture} \PName{mode} the layer spans a \Environment{picture}
    environment with the origin in the bottom left corner of the layer. The
    also available \PValue{raw} \PName{mode} current is the same like
    \PValue{text} \PName{mode}.

    Changing\textnote{Attention!} the \PName{mode} of a layer generally can
    move the contents. Additionally, i.\,e., \PValue{picture} \PName{mode}
    provides additional commands that result in errors with another
    \PName{mode}. Therefore, generally it makes no sense to change the
    \PName{mode} of a layer after it's initial declaration!%
  }%
  \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{\ChangedAt{v3.18}{\Package{scrlayer}}%
    \Option{oddorevenpage}}{%
    Removes any restriction of the layer to odd or even pages. So it will be
    printed independently of whether a page is odd or even. This is also the
    default of layers.  The option does not expect any value.%
  }%
  \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{\ChangedAt{v3.16}{\Package{scrlayer}}%
    \KOption{pretocontents}\PName{code}}{%
    Value \PName{code} will be added at the very beginning of the current
    value of attribute \Option{contents}. So the new content will be generated
    in front of the already existing content. For more information about the
    handling of \PName{code} see option \Option{contents}.%
  }%
  \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.%
  }%
  \entry{\ChangedAt{v3.18}{\Package{scrlayer}}%
    \Option{unrestricted}}{%
    This option removes all output restrictions of the layer. It is a
    combination of \Option{backandforground}, \Option{everyside}, and
    \Option{floatornonfloatpage}. The option does not expect any value.%
  }%
  \entry{\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}.%
  }%
  \entry{\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{layerhalign}\\
  \Macro{layervalign}\\
  \Macro{layerxoffset}\\
  \Macro{layeryoffset}\\
  \Macro{layerwidth}\\
  \Macro{layerheight}%
\end{Declaration}
\BeginIndex{Cmd}{layervalign}%
\BeginIndex{Cmd}{layerhalign}%
\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 alignment,
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.

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{r} and \PValue{b}
are copied to \Macro{layervalign}. The also horizontal and vertical value
\PValue{c} is copied to both commands. If \PValue{align} has contradictory
values, only the last one is copied. Therefore the resulting
\Macro{layerhalign} is either \PValue{l}, \PValue{c}, or \PValue{r} and the
resulting \Macro{layervalign} is either \PValue{r}, \PValue{c}, or \PValue{b}.

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}%
\EndIndex{Cmd}{layerhalign}%
\EndIndex{Cmd}{layervalign}%


\begin{Declaration}
  \Macro{LenToUnit}\Parameter{length}
\end{Declaration}
\BeginIndex{Cmd}{LenToUnit}%
This\ChangedAt{v3.19}{\Package{scrlayer}} command has been copied from
\Package{eso-pic}\IndexPackage{eso-pic} 2.0f. It converts lengths into
multiples of \Length{unitlength}. It can be used everywhere \LaTeX{}
expects \Environment{picture} coordinates or \Length{unitlength}-depending
values. For more information see \cite{package:eso-pic} and the following
descriptions of \Macro{putUR}, \Macro{putLL}, and \Macro{putLR}. If the
command is already defined, e.\,g., by loading \Package{eso-pic} before
\Package{scrlayer}, the package does not define it again.%

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 to accept
\LaTeX{} lengths directly.%
\EndIndex{Cmd}{LenToUnit}%


\begin{Declaration}
  \Macro{putUL}\Parameter{content}\\
  \Macro{putUR}\Parameter{content}\\
  \Macro{putLL}\Parameter{content}\\
  \Macro{putLR}\Parameter{content}\\
  \Macro{putC}\Parameter{content}
\end{Declaration}
\BeginIndex{Cmd}{putUL}%
\BeginIndex{Cmd}{putUR}%
\BeginIndex{Cmd}{putLL}%
\BeginIndex{Cmd}{putLR}%
\BeginIndex{Cmd}{putC}%
You\ChangedAt{v3.19}{\Package{scrlayer}} can use these commands inside the
value of primary layer option \PValue{contents}, if the layer is declared with
\OptionValue{mode}{picture}. In that case, \Macro{putUL} places the
\PName{content} relative to the upper left corner of the layer and therefore
is the same like
\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 like
\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 like
\lstinline[breaklines=false]|\put(0,0)|. \Macro{putLR} places the
\PName{content} relative to the lower right corner and therefore is the same
like \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 investigate, how accurate \OptionValue{DIV}{classic} sets the
  height of the text area to the width of the page size. So you declare a
  layer that not only border the text area, but also places a circle with
  paper width as diameter dimension into 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 see that \Package{typearea}'s mapping to an integer \PName{DIV}
  value is very accurate in this example.
\end{Example}
For more information about the sketched Middle Age method of generating a text
area see \autoref{sec:typearea.circleConstruction},
\autopageref{sec:typearea.circleConstruction}.

For more information about command
\Macro{DeclareNewPageStyleByLayers}\IndexCmd{DeclareNewPageStyleByLayers} see
the description later in \autoref{sec:scrlayer.pagestyles},
\autopageref{desc:scrlayer.cmd.DeclareNewPageStyleByLayers}. In short: It
defines a new page style using the newly declared layer.%
\EndIndex{Cmd}{putC}%
\EndIndex{Cmd}{putLR}%
\EndIndex{Cmd}{putLL}%
\EndIndex{Cmd}{putUR}%
\EndIndex{Cmd}{putUL}%


\begin{Declaration}
  \Macro{GetLayerContents}\Parameter{layer name}
\end{Declaration}
\BeginIndex{Cmd}{GetLayerContents}%
This\ChangedAt{v3.16}{\Package{scrlayer}} command results in the whole content
of a layer. You have 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
an infinite recursion, if the content of the current layer is referenced. You
yourself should avoid such situations!%
\EndIndex{Cmd}{GetLayerContents}%

\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} prints a ruler at each layer edge, of
which the top and left one is labelled with centimeters, the right and bottom
one with inches.  This command is used internally, if option
\Option{draft}\IndexOption{draft} is enabled. The rulers will be drawn behind
the content of each layer.  It can also be used as exclusive content of a
layer.%
\EndIndex{Cmd}{layercontentsmeasure}


\section{Declaration and Management of Page Styles}
\seclabel{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 suggests itself to declare page styles as 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 all such considerations 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 you may add additional code to. 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 wraps 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. Aliasing is not
restricted to \Package{scrlayer} page styles, but possible for all 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 executing the \LaTeX{} output
routine. However, this change will only occur, if \Macro{currentpagestyle} has
been actively protected from expansion up to 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. Additionally, 
\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 the 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 is already a page style
\PName{alias page style name}, then 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{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. Afterwards, 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 use 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, 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 detailed information on specific
hooks.

\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 is 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 page style's layers
    is initialised. Note\textnote{Attention!}, this is 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 page style's layers in
    single-side mode is initialised.  Note\textnote{Attention!}, this
    is 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 page style's layers in
    two-side mode is initialised.  Note\textnote{Attention!}, this is
    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 page style's layers on
    an odd page is initialised. Note\textnote{Attention!}, this is
    done twice for every page: once for background layers and once for
    foreground layers. Note\textnote{Attention!} also that 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 page style's layers on
    an even page is initialised. Note\textnote{Attention!}, this is
    done twice for every page: once for background layers and once for
    foreground layers. Note\textnote{Attention!} also that 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 page style's layers on
    a float page are initialised. Note\textnote{Attention!}, this is
    be done twice for every page: once for background layers and once for
    foreground layers. Note\textnote{Attention!} also that float pages are
    only those pages with p-placed floating objects.%
  }%
  \entry{\KOption{onnonfloatpage}\PName{code}}{%
    Execute \PName{code} whenever the output of page style's layers on
    a non-float page is initialised. Note\textnote{Attention!}, this
    is done twice for every page: once for background layers and once for
    foreground layers. Note\textnote{Attention!} also that 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 page style's layers in
    the background of a page is initialised. Note\textnote{Attention!},
    this is done once for every page.%
  }%
  \entry{\KOption{onforeground}\PName{code}}{%
    Execute \PName{code} whenever the output page style's layers in
    the foreground of a page is initialised. Note\textnote{Attention!},
    this is 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.

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 occurs.

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 default layer page styles that are somehow special. The first
one is \Pagestyle{@everystyle@}. This page style should not be used like any
other page style, 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 is 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} process only the layers of the page
style that has been referenced but not the layers implicated by
\Pagestyle{@everystyle@}.

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}. These defaults will be extended at every declaration of page
style hook options via \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}\\
  \Macro{ForEachLayerOfPageStyle*}\Parameter{page style name}\Parameter{code}
\end{Declaration}
\BeginIndex{Option}{deactivatepagestylelayers~=\PName{simple switch}}%
\BeginIndex{Cmd}{ForEachLayerOfPageStyle}%
\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 member layer of \PName{page style name}'s layers
list. Inside of \PName{code} the place holder \PValue{\#1} may be used to
reference the name of the current layer.
\begin{Example}
  If you want to print 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.

Alternatively,\ChangedAt{v3.18}{\Package{scrlayer}} you can use \Macro{def}
but the star variant \Macro{ForEachLayerOfPageStyle*}. This type does not use
an additional group for executing \PName{code}. On the other hand the user has
to take care on side effects of \PName{code}, i.\,e., deactivation of all
layers using \OptionValue{deactivatepagestylelayers}{true} in \PName{code}
would persist after \Macro{ForEachLayerOfPageStyle*}.

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*}%
\EndIndex{Cmd}{ForEachLayerOfPageStyle}%
\EndIndex{Option}{deactivatepagestylelayers~=\PName{simple switch}}%

\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
\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
% Umbruchkorrektur
\begin{lstcode}[belowskip=\dp\strutbox]
  \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}
\seclabel{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{}{layer}
\EndIndex{Package}{scrlayer}

%%% Local Variables:
%%% mode: latex
%%% mode: flyspell
%%% coding: us-ascii
%%% ispell-local-dictionary: "en_GB"
%%% TeX-master: "../guide"
%%% End: