diff options
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.tex | 370 |
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: |