summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/doc/scrlayer-scrpage-experts-en.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/scrlayer-scrpage-experts-en.tex')
-rw-r--r--macros/latex/contrib/koma-script/doc/scrlayer-scrpage-experts-en.tex370
1 files changed, 370 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/doc/scrlayer-scrpage-experts-en.tex b/macros/latex/contrib/koma-script/doc/scrlayer-scrpage-experts-en.tex
new file mode 100644
index 0000000000..8a9a43fa25
--- /dev/null
+++ b/macros/latex/contrib/koma-script/doc/scrlayer-scrpage-experts-en.tex
@@ -0,0 +1,370 @@
+% ======================================================================
+% 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: