summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/koma-script/source-doc/english/scrlayer-scrpage-experts.tex
blob: b5684a766e7c45ddf3b75ca3f77e4c6cbe4d0a25 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
% ======================================================================
% 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-10-10 09:50:23 +0200 (Thu, 10 Oct 2019) $
                  KOMA-Script guide (chapter: scrlayer-scrpage-experts)]
\translator{Markus Kohm\and Karl Hagen}

% Date version of the translated file: 2019-10-09

\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}
  \KOption{hmode}\PValue{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: