% ======================================================================
% scrlayer-scrpage-experts-en.tex
% Copyright (c) Markus Kohm, 2013-2022
%
% This file is part of the LaTeX2e KOMA-Script bundle.
%
% This work may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, version 1.3c of the license.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX 
% version 2005/12/01 or later and of this work.
%
% This work has the LPPL maintenance status "author-maintained".
%
% The Current Maintainer and author of this work is Markus Kohm.
%
% This work consists of all files listed in MANIFEST.md.
% ======================================================================
%
% Expert chapter about scrlayer-scrpage of the KOMA-Script guide
%
% ============================================================================

\KOMAProvidesFile{scrlayer-scrpage-experts-en.tex}%
                 [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $
                  KOMA-Script guide (chapter: scrlayer-scrpage-experts)]
\translator{Markus Kohm\and Karl Hagen}

\chapter[{Additional Features of \Package{scrlayer-scrpage}}]
  {Additional Features\ChangedAt{v3.12}{\Package{scrlayer-scrpage}} with
    the \Package{scrlayer-scrpage} package}
\labelbase{scrlayer-scrpage-experts}
%
\BeginIndexGroup
\BeginIndex{Package}{scrlayer-scrpage}%
The \Package{scrlayer-scrpage} package offers many features beyond what has
been described in \autoref{cha:scrlayer-scrpage} of \autoref{part:forAuthors}
of this \iffree{guide}{book}. However, the average user will not normally need
these extensions, and some of them are only provided for compatibility with
\Package{scrpage2}. The documentation here in \autoref{part:forExperts} serves
to deepen and broaded your knowledge, and its mastery goes beyond basic
skills.

\LoadCommonFile{pagestylemanipulation}% \section{Manipulating Defined Page Styles}

\section{Defining New Pairs of Page Styles}
\seclabel{pagestyle.pairs}

The two page styles \PageStyle{scrheadings} and \PageStyle{plain.scrheadings}
were described in \autoref{sec:scrlayer-scrpage.predefined.pagestyles}. You
can view them as a kind of pair, with \PageStyle{scrheadings} intended as the
main page style for a running head and \PageStyle{plain.scrheadings} the
corresponding \PageStyle{plain} page style without a running head but
generally with pagination. In addition to configuring this predefined pair,
\Package{scrlayer-scrpage} also lets you define additional pairs of page
styles. The name of the main page style, for example \PageStyle{scrheadings},
also serves as the name of the page-style pair.

\iffree{
  The vast majority of users will not need more than the one predefined
  page-style pair, \PageStyle{scrheadings}. So the commands documented in this
  section are therefore extensions for special cases. Since I have not come
  across any suitable applications while writing this manual, there are no
  detailed examples. Should I ever run across a particularly nice application
  while providing support, I will happily include it in future versions. At
  the same time, however, I'm virtually certain that all such cases could also
  be solved using the predefined pair only.}{}

\begin{Declaration}
  \Macro{defpairofpagestyles}%
  \OParameter{parent pair}\Parameter{name}\Parameter{definition}%
  \Macro{newpairofpagestyles}%
  \OParameter{parent pair}\Parameter{name}\Parameter{definition}%
  \Macro{renewpairofpagestyles}%
  \OParameter{parent pair}\Parameter{name}\Parameter{definition}%
  \Macro{providepairofpagestyles}%
  \OParameter{parent pair}\Parameter{name}\Parameter{definition}
\end{Declaration}
You can use these commands to define pairs of page styles similar to
\PageStyle{scrheadings} and \PageStyle{plain.scrheadings}, where \PName{name}
is the name of the main page style corresponding to \PageStyle{scrheadings}.
The name of the equivalent \PageStyle{plain} page style will be prefixed by
\PValue{plain.} automatically. So \PName{name} is not only the name of the
pair of page styles, but also the name of the main page style of that pair,
while \PValue{plain.}\PName{name} is the name of the \PageStyle{plain} page
style of this pair.

If you provide the optional \PName{parent pair} argument, this is the name of
a page-style pair whose settings are used to initialise the new page-style
pair. So the new pair inherits the configuration of the \PName{parent pair}.

Although \autoref{sec:scrlayer-scrpage.predefined.pagestyles} might have
created the impression that the commands described there apply only to
\PageStyle{scrheadings} and \PageStyle{plain.scrheadings} only, this is true
only so long as those two page styles are the only defined page-style pair. As
soon as there are multiple page-style pairs,
\DescRef{scrlayer-scrpage.cmd.lehead}, \DescRef{scrlayer-scrpage.cmd.cehead},
\DescRef{scrlayer-scrpage.cmd.rehead}, \DescRef{scrlayer-scrpage.cmd.lohead},
\DescRef{scrlayer-scrpage.cmd.cohead}, \DescRef{scrlayer-scrpage.cmd.rohead},
\DescRef{scrlayer-scrpage.cmd.lefoot}, \DescRef{scrlayer-scrpage.cmd.cefoot},
\DescRef{scrlayer-scrpage.cmd.refoot}, \DescRef{scrlayer-scrpage.cmd.lofoot},
\DescRef{scrlayer-scrpage.cmd.cofoot}, \DescRef{scrlayer-scrpage.cmd.rofoot},
\DescRef{scrlayer-scrpage.cmd.ihead}, \DescRef{scrlayer-scrpage.cmd.chead},
\DescRef{scrlayer-scrpage.cmd.ohead}, \DescRef{scrlayer-scrpage.cmd.ifoot},
\DescRef{scrlayer-scrpage.cmd.cfoot}, and \DescRef{scrlayer-scrpage.cmd.ofoot}
all refer to page-style pair that was most recently activated.

In addition to those eighteen commands mentioned above, the three commands
described below, \DescRef{\LabelBase.cmd.clearmainofpairofpagestyles},
\DescRef{\LabelBase.cmd.clearplainofpairofpagestyles}, and
\DescRef{\LabelBase.cmd.clearpairofpagestyles}, are designed to be used inside
the \PName{definition} argument. In this case, they represent a kind of
default configuration of the page-style pair that is executed each time the
pair is activated. You activate a page-style pair by activating either one two
page styles in the pair. Typically, you do so with
\DescRef{maincls.cmd.pagestyle}\IndexCmd{pagestyle}.

Note that the commands of \autoref{sec:scrlayer-scrpage.pagestyle.content} on
\autopageref{sec:scrlayer-scrpage.pagestyle.content} are general in nature and
apply to all page styles defined with \Package{scrlayer-scrpage}.

Although \Macro{defpairofpagestyles} defines a page-style pair regardless of
whether the corresponding page styles already exist,
\Macro{newpairofpagestyles} and \Macro{providepairofpagestyles} do so only if
the page styles are currently undefined. If at least one of the page styles is
already defined, the new definition of \Macro{providepairofpagestyles} will be
ignored, whereas using \Macro{newpairofpagestyles} results in an error
message. To redefine existing page-style pairs, you can use
\Macro{renewpairofpagestyles}. With this an is thrown if either one of the two
page styles of the pair does not already exist.%
\EndIndexGroup


\begin{Declaration}
  \Macro{clearmainofpairofpagestyles}%
  \Macro{clearplainofpairofpagestyles}%
  \Macro{clearpairofpagestyles}
\end{Declaration}
The \Macro{clearmainofpairofpagestyles} command sets the main page style of
the most recently activated page-style pair to be empty. In contrast, the
\Macro{clearplainofpairofpagestyles} command sets the \PageStyle{plain} page
style of the active page-style pair to be empty. Finally,
\Macro{clearpairofpagestyle} sets both page styles of the activate pair to be
empty.

But note\textnote{Attention!} that none of these commands removes the
definitions of the \PName{definition} argument that was specified when
defining the page-style pair (see above). So if you activate the pair of page
styles again, those definitions will be used again!

You can use these commands inside the \PName{definition} of the page-style
pair explained above. But you can also use them outside this definition. In
this case, they refer to the most recently activated page-style pair.%
\EndIndexGroup


\section{Defining Complex Page Styles}
\seclabel{pagestyle.experts}

In addition to the predefined page styles, \Package{scrlayer-scrpage} also
provides a more basic interface for defining new page styles. The page-style
definitions discussed so far use this interface internally, as do the obsolete
commands in \autoref{sec:\LabelBase.pagestyle.triple}.
\Package{scrlayer-scrpage}. Because of its complexity, however, only advanced
users should try to use it directly. Less experienced users can already
achieve almost everything possible with this low-level interface by using the
possibilities described previously.

\begin{Declaration}
  \Macro{defpagestyle}%
  \Parameter{name}\Parameter{header specification}\Parameter{footer specification}%
  \Macro{newpagestyle}%
  \Parameter{name}\Parameter{header specification}\Parameter{footer specification}%
  \Macro{providepagestyle}%
  \Parameter{name}\Parameter{header specification}\Parameter{footer specification}%
  \Macro{renewpagestyle}%
  \Parameter{name}\Parameter{header specification}\Parameter{footer specification}%
\end{Declaration}
You can use these commands to define a single page style with maximum
flexibility, where \PName{name} is the name of the page style that you want to
define.

The parameters \PName{header specification} and \PName{footer specification}
have identical structure:
\begin{quote}\raggedright
  \texttt{%
    (\PName{length of the line above},\PName{thickness of the line above})\%\\
    \Parameter{specification for the left page in two-side layout}\%\\
    \Parameter{specification for the right page in two-side layout}\%\\
    \Parameter{specification for all pages in one-side laypout}\%\\
    (\PName{length of the line below},\PName{thickness of the line below})%
  }
\end{quote}
The arguments in the round brackets are optional. That is, you can omit them
together with the brackets. In that case, the length and thickness of the
corresponding horizontal rules are based on the \KOMAScript{} options
\DescRef{scrlayer-scrpage.option.headtopline},
\DescRef{scrlayer-scrpage.option.headsepline},
\DescRef{scrlayer-scrpage.option.footsepline}, and
\DescRef{scrlayer-scrpage.option.footbotline} (see
\autoref{sec:scrlayer-scrpage.pagestyle.content},
\DescPageRef{scrlayer-scrpage.option.headtopline}).

All three arguments in curly brackets are mandatory and are used depending on
the page and the layout settings. Their content can be anything you want. For
page styles with running heads, however, you should use
\DescRef{scrlayer-scrpage.cmd.headmark},
\DescRef{scrlayer-scrpage.cmd.leftmark}, or
\DescRef{scrlayer-scrpage.cmd.rightmark} inside the specification. Under no
circumstances should you directly put the number or text of a sectioning
command here. Because of the \LaTeX{}'s asynchronous page construction, the
wrong numbers or text can appear in the header or footer if you do so.

The \Macro{defpagestyle} command defines the page style regardless of whether
it already exists or not. In contrast, \Macro{newpagestyle} throws an error if
a page style of the same \PName{name} already exists. On the other hand,
\Macro{providepagestyle} simply ignores the definition if the \PName{name} has
already been used for a page style. Conversely, \Macro{renewpagestyle} can
only redefine an existing page style. For a new \PName{name}, it throws an
error.

All four commands are based on the
\DescRef{scrlayer.cmd.DeclarePageStyleByLayers}%
\IndexCmd{DeclarePageStyleByLayers} command of the
\hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer} package.
You can find the layers that are defined for a page style \PName{name} in
\autoref{tab:scrlayer-scrpage-experts.layersperstyle}, and more information
about layers and layer-page in \autoref{cha:scrlayer}, starting on
\autopageref{cha:scrlayer}.%

\begin{table}
%  \KOMAoptions{captions=topbeside}
%  \setcapindent{0pt}
%  \begin{captionbeside}
  \caption
    [{The layers \Package{scrlayer-scrpage} defines for a page style}]
    {The layers \Package{scrlayer-scrpage} defines for a \PName{name} page
     style\label{tab:scrlayer-scrpage-experts.layersperstyle}}
%    [l]
    \begin{tabular}{ll}
      \toprule
      Name of the layer & Meaning of the layer \\
      \midrule
      \PName{name}\PValue{.head.above.line} 
        & horizontal line above the header\\
      \PName{name}\PValue{.head.odd} 
        & header of odd pages in two-sided printing\\
      \PName{name}\PValue{.head.even}
        & header of even pages in two-sided printing\\
      \PName{name}\PValue{.head.oneside} 
        & header in one-sided printing\\
      \PName{name}\PValue{.head.below.line} 
        & horizontal line below the header\\
      \PName{name}\PValue{.foot.above.line} 
        & horizontal line above the footer\\
      \PName{name}\PValue{.foot.odd} 
        & footer of odd pages in two-sided printing\\
      \PName{name}\PValue{.foot.even} 
        & footer of even pages in two-sided printing\\
     \PName{name}\PValue{.foot.oneside} 
        & footer in one-sided printing\\
      \PName{name}\PValue{.foot.below.line}
        & horizontal line below the footer\\
      \bottomrule
    \end{tabular}
%  \end{captionbeside}
\end{table}

\begin{Example}
  Suppose you want to set a background colour for the header of the
  \PageStyle{scrheadings} page style. From the introduction to this chapter
  and \autoref{tab:scrlayer-scrpage-experts.layersperstyle}, you know that
  \PageStyle{scrheadings} is a layer page style that includes the layers
  \PValue{scrheadings.head.even}, \PValue{scrheadings.head.odd}, and
  \PValue{scrheadings.head.oneside}. You now define three more layers for
  their backgrounds and add them at the beginning of the page style:
\begin{lstcode}
 \documentclass{scrartcl}
  \usepackage[automark]{scrlayer-scrpage}
  \usepackage{xcolor}
  \usepackage{blindtext}
  \DeclareLayer[clone=scrheadings.head.oneside,
    contents={%
      \color{yellow}\rule[-\dp\strutbox]{\layerwidth}{\layerheight}%
    }%
  ]{scrheadings.head.oneside.background}
  \DeclareLayer[clone=scrheadings.head.odd,
    contents={%
      \color{yellow}\rule[-\dp\strutbox]{\layerwidth}{\layerheight}%
    }%
  ]{scrheadings.head.odd.background}
  \DeclareLayer[clone=scrheadings.head.even,
    contents={%
      \color{yellow}\rule[-\dp\strutbox]{\layerwidth}{\layerheight}%
    }%
  ]{scrheadings.head.even.background}
  \AddLayersAtBeginOfPageStyle{scrheadings}{%
    scrheadings.head.oneside.background,%
    scrheadings.head.odd.background,%
    scrheadings.head.even.background%
  }
  \pagestyle{scrheadings}
  \begin{document}
  \blinddocument
  \end{document}
\end{lstcode}
  As you can see, the example uses three layers so that the position and size
  of the background layers could simply be copied from the corresponding
  header layer using the \Option{clone} option. This is easier than using only
  one background layer and dynamically calculating its position each time.

  The coloured background itself was created using a \Macro{rule} command. The
  size arguments of this \Macro{rule} are given by
  \DescRef{scrlayer.cmd.layerwidth} and \DescRef{scrlayer.cmd.layerheight}
  which contain the current width and height of the layer itself. The optional
  argument of \Macro{rule} is used to move the rule down by the height of a
  descender.
\end{Example}
%
Instead of using new layers to colour the background in the example above,
\Macro{colorbox} and \DescRef{scrlayer-scrpage.cmd.chead} could have been
used. You can work out a solution using this method as an exercise. Likewise,
you could have added the background layers individually just before the
corresponding content layer. You can implement this as an exercise too.%
\EndIndexGroup

\section{Defining Simple Page Styles with a Tripartite Header and Footer}
\seclabel{pagestyle.triple}

\LoadNonFree{scrlayer-scrpage-experts}{1}

\section{Legacy Features of \Package{scrpage2}}
\seclabel{obsolete}

\begin{Explain}
  The \Package{scrlayer-scrpage} package contains some legacy features that
  derive from \Package{scrpage2} and exist only to be as compatible as possible
  with that package. Users only need to understand these features if they want
  to edit an old document based on \Package{scrpage2}. You\textnote{Attention!}
  should not use the items documented here in new documents!
\end{Explain}

\begin{Declaration}
  \OptionVName{hmode}{simple switch}
\end{Declaration}
The \Package{scrpage2} package always outputs headers and footers in
horizontal mode. In contrast, \Package{scrlayer-scrpage} in the default
setting only switches into horizontal mode when horizontal material is output.
However, if you activate the \Option{hmode} option, \Package{scrlayer-scrpage}
will behave like \Package{scrpage2} and switch to horizontal mode before any
output. This can affect both the processing of white space at the beginning of
the output and vertical alignment.

The options recognizes the standard values for simple switches listed in
\autoref{tab:truefalseswitch} on \autopageref{tab:truefalseswitch}. The option
is deactivated by default.%
\EndIndexGroup

\LoadNonFree{scrlayer-scrpage-experts}{0}
%
\EndIndexGroup

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "scrguide-en.tex"
%%% coding: utf-8
%%% ispell-local-dictionary: "en_GB"
%%% eval: (flyspell-mode 1)
%%% End:
