You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
393 lines
18 KiB
393 lines
18 KiB
% ======================================================================
|
|
% 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 (Fri, 06 Dec 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:
|
|
|