% ====================================================================== % scrlayer-scrpage-experts.tex % Copyright (c) Markus Kohm, 2013-2019 % % 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-scrpage-experts.tex % Copyright (c) Markus Kohm, 2013-2019 % % 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. % ====================================================================== % % Expert chapter about scrlayer-scrpage of the KOMA-Script guide % % ---------------------------------------------------------------------- % % Expertenkapitel ueber scrlayer-scrpage in der KOMA-Script-Anleitung % % ============================================================================ \KOMAProvidesFile{scrlayer-scrpage-experts.tex}% [$Date: 2019-12-06 10:44:53 +0100 (Fr, 06. Dez 2019) $ KOMA-Script guide (chapter: scrlayer-scrpage-experts)] \translator{Markus Kohm\and Karl Hagen} % Date version of the translated file: 2019-12-06 \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 %%% mode: flyspell %%% coding: us-ascii %%% ispell-local-dictionary: "en_GB" %%% TeX-master: "../guide" %%% End: