summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex
blob: 5dee2a97c870f482d8da064dcd895b989251a71f (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
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
% ======================================================================
% scrlayer.tex
% Copyright (c) Markus Kohm, 2013-2015
%
% 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.tex
% Copyright (c) Markus Kohm, 2013-2015
%
% 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.
% ======================================================================
%
% Chapter about scrlayer of the KOMA-Script guide
% Maintained by Markus Kohm
%
% ----------------------------------------------------------------------
%
% Kapitel ueber scrlayer in der KOMA-Script-Anleitung
% Verwaltet von Markus Kohm
%
% ============================================================================

\KOMAProvidesFile{scrlayer.tex}
                 [$Date: 2015-03-31 11:10:59 +0200 (Tue, 31 Mar 2015) $
                  KOMA-Script guide (chapter:scrlayer)]

\translator{Markus Kohm}

% Date of the translated file: 2015-03-31

\chapter[{Defining Layers and Page Styles Using \Package{scrlayer}}]%
{Defining Layers and Page Styles Using \Package{scrlayer}%
}
\labelbase{scrlayer}

\BeginIndex{Package}{scrlayer}%
\BeginIndex{}{layer}%
Most users of graphics software already know layer models for pages or working
sheets. \LaTeX{} itself does not know layers, but there are already packages
like \Package{eso-pic} or \Package{textpos}, that provide a kind of
background or foreground layer. \Package{scrlayer} is another package,
that provides such background and foreground layers, but in difference
to the other packages mentioned above these layers are part of the
page style definition. With this you may simply switch between usage
of layers by switching the page style.

To do so, the package also supports a low level interface to define page
styles using a layer stack, to put layers onto a page style's layer stack, to
put layers at the lowest position of a page style's layer stack, to put layers
before or after a layer of a page style's layer stack, to remove a layer from
a page style's layer stack and to remove doublets of layers of a page style's
layer stack. In short words: The page style interface of \Package{scrlayer}
provides commands to define layer-stack-based page styles and to manage those
layer stacks.

Nevertheless, using the layers directly is recommended for advanced users only.
End user interfaces for beginners or average users are provided by additional
packages, that load \Package{scrlayer} on their own. See
\autoref{cha:scrlayer-scrpage} in \autoref{part:forAuthors} of this
\iffree{manual}{book}.

\section{State of Development Note}
\seclabel{draft}

Development of this package has not been finished yet. Parts of the package
are even still experimental. Because of this, especially internal
functionality may be changed in future. Most likely the package will be
extended. And because of the early state of development, you should not expect
a complete and finished user manual. Nevertheless, this manual, which is
recommended for advanced users and developers, describes the current state of
development and the released parts of \Package{scrlayer}. Everything, not
documented here, should not be used for anything else but testing.

\LoadCommon{0} % \section{Early or Late Selection of Options}

\section{Some Generic Information}
\seclabel{generic}

The package needs some generic information about the class. Class authors may
help \Package{scrlayer} by setting this information. Otherwise the package tries
to detect the information itself. This works, e.g., for the standard classes
and the \KOMAScript{} classes. But it may or may not fail with other classes.

This section describes some of the information, that class authors may
provide. Generally users need not to care about this.

\begin{Declaration}
  \Macro{if@chapter}\ \PName{then code} \Macro{else}\ \PName{else code}
  \Macro{fi}%
\end{Declaration}
\BeginIndex{Cmd}{if@chapter}%
If \Macro{if@chapter} is \Macro{iftrue}, \Package{scrlayer} will additionally
consider the chapter level, e.g., processing option \Option{automark}. If it
is defined, but differs from \Macro{iftrue}, only part, section, subsection,
sub\dots subsection, paragraph, subparagraph, sub\dots subparagraph will be
considered. If the macro is not defined, \Package{scrlayer} searches for
\Macro{chapter}. If \Macro{chapter} is defined and not \Macro{relax},
\Package{scrlayer} will define \Macro{if@chapter} to \Macro{iftrue}, otherwise
\Macro{if@chapter} will become \Macro{iffalse}.%
\EndIndex{Cmd}{if@chapter}

\begin{Declaration}
  \Macro{if@mainmatter}\ \PName{then code} \Macro{else}\ \PName{else code}
  \Macro{fi}%
\end{Declaration}
\BeginIndex{Cmd}{if@mainmatter}%
Classes like \Class{book} define \Macro{frontmatter}, \Macro{mainmatter}, and
\Macro{backmatter}. They also use \Macro{if@mainmatter} to distinguish whether
or not the current matter is the main matter. Classes like \Class{report} and
\Class{article} do not have \Macro{frontmatter}, \Macro{mainmatter}, or
\Macro{backmatter} and therefore also do not have \Macro{if@mainmatter}.

For \Package{scrlayer} it's easier not to test always for the existence of the
matter commands, but to use \Macro{if@mainmatter} even with classes like
\Class{report} and \Class{article}, simply set to \Macro{iftrue}. So if
\Macro{if@mainmatter} is not defined, it will be defined to \Macro{iftrue}.

Some classes have \Macro{frontmatter}, \Macro{mainmatter}, or
\Macro{backmatter} but not \Macro{if@mainmatter}. In this case
\Package{scrlayer} also defines \Macro{if@mainmatter} to be \Macro{iftrue}
and it extends definition of \Macro{frontmatter}, \Macro{mainmatter}, and
\Macro{backmatter} to set \Macro{if@mainmatter} properly. Other matter
commands are not known, not tested, and not extended. So if there are other
matter commands \Package{scrlayer} needs help of the class author to set
\Macro{if@mainmatter} correctly.%
\EndIndex{Cmd}{if@mainmatter}

\begin{Declaration}
  \Macro{DeclareSectionNumberDepth}%^^A
  \Parameter{level name}\Parameter{level depth}
\end{Declaration}
\BeginIndex{Cmd}{DeclareSectionNumberDepth}%
Generally each section level is related to an integer number indicating its
depth in the document structure. \LaTeX{} needs this to manage hierarchic
section levels. But normally only the document class, that defines the section
commands, itself knows that \PName{level depth} of a section level and uses
these numerical values inside the corresponding commands, when needed.

But \Package{scrlayer} also needs information about the section hierarchy.
With command \Macro{DeclareSectionNumberDepth} you can map
the name of a heading level to a \PName{level depth}. With standard class
book, e.g., the \PName{level name} could be \PValue{part}, \PValue{chapter},
\PValue{section}, \PValue{subsection}, \PValue{subsubsection},
\PValue{paragraph}, or \PValue{subparagraph} and the corresponding
\PName{level depth}s would be -1, 0, 1, 2, 3, 4, and 5. 

Package \Package{scrlayer} tries to determine the \PName{level depth}s on its
own while loading and again while \Macro{begin}\PParameter{document}. But, if
it fails, i.\,e., if completely different section commands are used, it would
be useful, to be able to define the relationship explicitly. For such cases
\Macro{DeclareSectionNumberDepth} gives the class author the opportunity to
define the relationship explicitly.%
\EndIndex{Cmd}{DeclareSectionNumberDepth}

\section{Declaration of Layers}
\seclabel{layers}

A layer is a kind of virtual sheet of transparent paper (in opposite to a
physical sheet of paper). One layer is stacked onto another layer and opaque
material on one layer may hide material on the layers below. The stack of all
layers together makes the physical page. Package \Package{scrlayer}
provides two such layer stacks for each page: a background layer stack and a
foreground layer stack. The background layer stack is behind the normal page
contents, the foreground layer stack is above the normal page contents. So the
normal contents is a kind of a separating layer between the background layer
stack and the foreground layer stack.

A layer has several attributes. The first attribute states, whether or not the
layer is part of the foreground or the background. During page building
background layers will be printed first, followed by the main contents and the
foreground layers. Therefore, in the output the background layers show up
behind the main contents and the foreground layers in front of the main
contents. By default, a layer is both, a background layer \emph{and} a
foreground layer and therefore will be printed twice.

The horizontal position of the layer is set by the second attribute, the
vertical position by the third. The forth and fifth attributes determine the
horizontal and vertical size of the layer. As you can see, a layer may be
smaller or larger than the paper.

But having two numerical values of the second and third attribute does not
directly give us the position of the layer on the page. For each dimension we
need two reference points, one on the page and one on the layer. The
numerical value than states the distance between these reference.
Reference points in layouts are also known as alignment and are set by the
sixth attribute.

The seventh attribute states, whether or not a layer should be
printed onto left or right pages. By default a layer will be printed on both,
left and right pages. Note, that \LaTeX{} names left pages as even pages and
right pages as odd pages and that there are no left or even pages in
single-sided mode.

The eighth attribute states, whether or not a layer should be printed in
single-side mode or in two-side mode. By default a layer will be printed in
both, single-side mode and two-side mode. Nevertheless, an even page layer will
never be printed in single-side mode and therefore is not really a two-side
mode layer.

The ninth attribute is, whether or not a layer should be printed onto float
pages or non-float pages. \LaTeX{} produces float pages for float environments
like tables or figures, if they are allowed to be printed on a page without
normal page contents (see option \PValue{p} for \Environment{figure} or
\Environment{table}). So from some point of view a float page is a page, that
may itself flow. Non-float pages are not pages without floats, but pages, that
are not float pages. They may contain floats inside the text, on the top of
the page, or on the bottom of the page. Very large floats may seem to be page
floats, while in reality they are top floats.

The tenth and last attribute is the contents of the layer. This is simply,
what should be printed, whenever the layer will be printed.

So we have ten attributes yet. Below in this manual we will describe
additional attributes. However, they are just defined for convenience and can
be expressed by a combination of the ten attributes stated above. We call
these ten attributes the primary attributes.

\begin{Declaration}
  \Macro{DeclareLayer}\OParameter{option list}\Parameter{layer name}\\
  \Macro{DeclareNewLayer}\OParameter{option list}\Parameter{layer name}\\
  \Macro{ProvideLayer}\OParameter{option list}\Parameter{layer name}\\
  \Macro{RedeclareLayer}\OParameter{option list}\Parameter{layer name}\\
  \Macro{ModifyLayer}\OParameter{option list}\Parameter{layer name}
\end{Declaration}
\BeginIndex{Cmd}{DeclareLayer}%
\BeginIndex{Cmd}{DeclareNewLayer}%
\BeginIndex{Cmd}{ProvideLayer}%
\BeginIndex{Cmd}{RedeclareLayer}%
\BeginIndex{Cmd}{ModifyLayer}%
These commands can be used to define a layer. The \PName{layer name} has to be
fully expandable and should expand to letters only. Some additional characters
are tolerated, but are not recommended.

Command \Macro{DeclareLayer} does not care whether or not a layer with the
given \PName{layer name} already exists. It will under all circumstances
define the layer with the attribute defined by the \PName{option list}.
An
\PName{option} can be either a key or a key followed by an
equal sign followed by a value. Several options may be concatenated to
a \PName{option list} and have to be separated by comma. If you'd like to have
a comma or a white space inside the value of an option, you should put the
value inside curly brackets. See \autoref{tab:scrlayer.layerkeys} for
more information on keys, values, and the corresponding
attributes.

In contrast to \Macro{DeclareLayer} using \Macro{DeclareNewLayer} results in
an error, if a layer with the same \PName{layer name} already exists. So you
may prevent yourself using the same \PName{layer name} more than once by
mistake. This would be useful, e.\,g., if a class or package also defines
layers internally.

If you use \Macro{ProvideLayer} instead of \Macro{DeclareLayer}, the
declaration will be ignored in case a layer with the same layer name already
exists. It could be paraphrased by: \emph{declare the layer only if it has not
  been declared already.}

If an existing layer should be redefined, \Macro{RedeclareLayer} or
\Macro{ModifyLayer} can be used. \Macro{RedeclareLayer} would simply define
the layer as if it would be defined newly. In difference to this,
\Macro{ModifyLayer} would change only those attributes, that are represented
by an option of the \PName{option list}. All other attributes will stay
unchanged and will not be reset to the initial default value. Using either
\Macro{RedeclareLayer} or \Macro{ModifyLayer} will result in an error, in case
there has not been a layer with \PName{layer name} defined before.

\begin{desclist}
  \desccaption{%
    Options for the definition of page layers with description of the
    corresponding layer attribute\label{tab:scrlayer.layerkeys}%
  }{%
    Options for the definition of layers (\emph{Continuation})%
  }%
  \ifnum\currentversionlt{3.16}\else
  \nentry{%
    \ChangedAt{v3.16}{\Package{scrlayer}}%
    \KOption{addcontents}\PName{Code}}{%
    Value \PName{code} will be added (or appended) at the very end of the
    current value of attribute \Option{contents}. So the new content will be
    generated behind the end of the already existing content. For more
    information about the handling of \PName{code} see option
    \Option{contents}.%
  }%
  \nentry{%
    \ChangedAt{v3.16}{\Package{scrlayer}}%
    \KOption{addheight}\PName{additional height}}{%
    The current value of attribute \Option{height} will be increased by the
    value of this option. You can use the same kind of values as for
    \Option{height}.%
  }%
  \nentry{%
    \ChangedAt{v3.16}{\Package{scrlayer}}%
    \KOption{addhoffset}\PName{additional horizontal offset}}{%
    The current value of attribute \Option{hoffset} will be increased by the
    value of this option. You can use the same kind of values as for
    \Option{hoffset}.%
  }%
  \nentry{%
    \ChangedAt{v3.16}{\Package{scrlayer}}%
    \KOption{addvoffset}\PName{additional vertical offset}}{%
    The current value of attribute \Option{voffset} will be increased by the
    value of this option. You can use the same kind of values as for
    \Option{voffset}.%
  }%
  \nentry{%
    \ChangedAt{v3.16}{\Package{scrlayer}}%
    \KOption{addwidth}\PName{additional width}}{%
    The current value of attribute \Option{width} will be increased by the
    value of this option. You can use the same kind of values as for
    \Option{width}.%
  }%
  \fi
  \nentry{\KOption{align}{\PName{alignment characters}}}{%
    The \PName{alignment characters} define the desired alignment of the
    layer. Each \PName{alignment character} influences either, how argument
    \PName{length} of option \Option{hoffset} or \Option{voffset} will be
    used. Several \PName{alignment characters} may be used together (without
    comma or space) and will be interpreted in the order of occurrence. No
    macros should be used here! Valid \PName{alignment character}s are:
    \begin{description}
    \item[\PValue{b} --] align the layer at its bottom edge; the
      value of
      \Option{voffset} is interpreted as the distance from the top edge of the
      paper to the bottom edge of the layer.
    \item[\PValue{c} --] align the layer at its centre; the values of
      \Option{voffset} and \Option{hoffset} are interpreted as the distance
      from the top left corner of the paper to the centre of the layer.
    \item[\PValue{l} --] align the layer at its left edge: the value of
      \Option{hoffset} is interpreted as the distance from the left edge of
      the paper to the left edge of the layer.
    \item[\PValue{r} --] align the layer at its right edge; the value of
      \Option{hoffset} is interpreted as the distance from the left edge of
      the paper to the right edge of the layer.
    \item[\PValue{t} --] align the layer at its top edge; the value of
      \Option{voffset} is interpreted as the distance from the top edge of the
      paper to the top edge of the layer.
    \end{description}%
  }%
  \nentry{\KOption{area}{%^^A
      \Parameter{hoffset}\Parameter{voffset}%^^A
      \Parameter{width}\Parameter{height}}}{%
    The composed option results in \OptionValue{hoffset}{\PName{hoffset}},
    \OptionValue{voffset}{\PName{voffset}},
    \OptionValue{width}{\PName{width}}, \OptionValue{height}{\PName{height}}.%
  }%
  \entry{\Option{background}}{%
    Print the layer only in the background, but not in the foreground. This
    makes a background-only layer in opposite to the default of layers which
    are both, background and foreground layers and therefore would be printed
    twice. The option does not expect any value. By the default the attribute
    is not set.%
  }%
  \entry{\Option{bottommargin}}{%
    The composed option sets \Option{hoffset}, \Option{voffset},
    \Option{width}, \Option{height}, and \Option{align} to horizontally span
    the paper from the left edge to the right and vertically span the area
    below the footer down to the bottom edge of the paper.%
  }%
  \nentry{\KOption{clone}{\PName{layer name}}}{%
    The composed option sets all primary attributes of the layer to the same
    values as the primary attributes of the layer with the given \PName{layer
      name}. Note, that \PName{layer name} has to be fully expandable and
    should expand to letters only. Some additional characters are tolerated,
    but are not recommended!%
  }%
  \nentry{\KOption{contents}{\PName{code}}}{%
    The \PName{code} will be expanded whenever the layer is printed. So the
    \PName{code} is what you will see. Code validity is not checked. So errors
    in \PName{code} may result in several failures on each page, that prints
    the layer.%
  }%
  \entry{\Option{evenpage}}{%
    Print the layer on even pages only, but not on odd pages. The option does
    not expect any value. By the default the option is not set and therefore
    layers would be printed on odd pages and on even pages. Note, that this
    attribute subsumes \Option{twoside}.%
  }%
  \entry{\Option{floatpage}}{%
    Print the layer on float pages only, but not on other pages. The option
    does not expect any value. By the default the attribute is not set and
    therefore layers would be printed on float pages and on non-float pages.%
  }%
  \entry{\Option{foot}}{%
    The composed option sets \Option{hoffset}, \Option{voffset},
    \Option{width}, \Option{height}, and \Option{align} to horizontally span
    the text area and vertically span the page footer defined by the new
    \LaTeX{} length \Length{footheight}.%
  }%
  \entry{\Option{footskip}}{%
    The composed option sets \Option{hoffset}, \Option{voffset},
    \Option{width}, \Option{height}, and \Option{align} to horizontally span
    the text area and vertically span the distance between the text area and
    the page footer (note, that this is not the same like \Length{footskip}).%
  }%
  \entry{\Option{foreground}}{%
    Print the layer only in the foreground, but not in the background. This
    makes a foreground-only layer in opposite to the default of layers which
    are both, background and foreground layers and therefore would be printed
    twice. The option does not expect any value. By the default the attribute
    is not set.%
  }%
  \entry{\Option{head}}{%
    The composed option sets \Option{hoffset}, \Option{voffset},
    \Option{width}, \Option{height}, and \Option{align} to horizontally span
    the text area and vertically span the page head defined by usual \LaTeX{}
    length \Length{headheight}.%
  }%
  \entry{\Option{headsep}}{%
    The composed option sets \Option{hoffset}, \Option{voffset},
    \Option{width}, \Option{height}, and \Option{align} to horizontally span
    the text area and vertically span the distance between the page head and
    the text area.%
  }%
  \nentry{\KOption{height}{\PName{length}}}{%
    Sets the height of the layer. Note, that \PName{length} can either be a
    \LaTeX{} length, declared using \Macro{newlength}, or a \TeX{} length,
    declared using \Macro{newdimen} or \Macro{newskip}, a length value like
    10\,pt, or a dimensional expression using +, -, /, *, (, and ). For more
    information about valid dimensional expressions see
    \cite[section~3.5]{manual:eTeX}.%
  }%
  \nentry{\KOption{hoffset}{\PName{length}}}{%
    Sets the offset of the layer (depending on \Option{align} either left edge
    of the layer, middle of the layer or right edge of the layer) from the
    left edge of the paper. See \Option{height} for more information about
    valid content of \PName{length}.%
  }%
  \entry{\Option{innermargin}}{%
    The composed option sets \Option{hoffset}, \Option{voffset},
    \Option{width}, \Option{height}, and \Option{align} to horizontally span
    the distance between the right edge of text area and the right edge of the
    paper on even pages or the distance between the left edge of the paper and
    the left edge of the text area on odd pages and vertically span the whole
    paper from the top edge to the bottom edge.%
  }%
  \entry{\Option{leftmargin}}{%
    The composed option sets \Option{hoffset}, \Option{voffset},
    \Option{width}, \Option{height}, and \Option{align} to horizontally span
    the distance between the left edge of the paper and the left edge of the
    text area and vertically span the whole paper from the top edge to the
    bottom edge.%
  }%
  \entry{\Option{nonfloatpage}}{%
    Restricts the layer to pages, that are not float pages. The option does
    not expect any value. By the default the attribute is not set and
    therefore layers would be printed on float pages and on non-float pages.%
  }%
  \entry{\Option{oddpage}}{%
    Print the layer on odd pages only, but not on even pages. The option does
    not expect any value. By the default the option is not set and therefore
    layers would be printed on odd pages and on even pages.%
  }%
  \entry{\Option{oneside}}{%
    Print the layer in single-side mode only, but not in two-side mode. The
    option does not expect any value. By the default the attribute is not set
    and therefore layers would be printed in single-side and two-side mode.%
  }%
  \entry{\Option{outermargin}}{%
    The composed option sets \Option{hoffset}, \Option{voffset},
    \Option{width}, \Option{height}, and \Option{align} to horizontally span
    the distance between the left edge of the paper and the left edge of the
    text area on even pages or the distance between the right edge of the text
    area and the right edge of the paper on odd pages and vertically span the
    whole paper from the top edge to the bottom edge.%
  }%
  \entry{\Option{page}}{%
    The composed option sets \Option{hoffset}, \Option{voffset},
    \Option{width}, \Option{height}, and \Option{align} to horizontally and
    vertically span the whole paper from the left edge to the right edge and
    the top edge to the bottom edge.%
  }%
  \ifnum\currentversionlt{3.16}\else
  \nentry{%
    \ChangedAt{v3.16}{\Package{scrlayer}}%
    \KOption{pretocontents}\PName{code}}{%
    Value \PName{code} will be added at the very beginning of the current
    value of attribute \Option{contents}. So the new content will be generated
    in front of the already existing content. For more information about the
    handling of \PName{code} see option \Option{contents}.%
  }%
  \fi
  \entry{\Option{rightmargin}}{%
    The composed option sets \Option{hoffset}, \Option{voffset},
    \Option{width}, \Option{height}, and \Option{align} to horizontally span
    the distance between the right edge of text area and the right edge of the
    paper and vertically span the whole paper from the top edge to the bottom
    edge.%
  }%
  \entry{\Option{textarea}}{%
    The composed option sets \Option{hoffset}, \Option{voffset},
    \Option{width}, \Option{height}, and \Option{align} to horizontally and
    vertically span the whole text area from the left edge to the right edge
    and the top edge to the bottom edge.%
  }%
  \entry{\Option{topmargin}}{%
    The composed option sets \Option{hoffset}, \Option{voffset},
    \Option{width}, \Option{height}, and \Option{align} to horizontally span
    the whole page from the left edge to the right edge and vertically span
    the distance between the top edge of the paper and the page head.%
  }%
  \entry{\Option{twoside}}{%
    Print the layer in two-side mode only, but not in single-side mode. The
    option does not expect any value. By the default the attribute is not set
    and therefore layers would be printed in single-side and two-side mode.%
  }%
  \nentry{\KOption{voffset}{\PName{length}}}{%
    Sets the offset of the layer (depending on \Option{align} either top edge
    of the layer, middle of the layer or bottom edge of the layer) from the
    top edge of the paper. See \Option{height} for more information about
    valid content of \PName{length}.%
  }%
  \nentry{\KOption{width}{\PName{length}}}{%
    Sets the width of the layer. See \Option{height} for more information
    about valid content of \PName{length}.%
  }%
\end{desclist}
%
\EndIndex{Cmd}{ModifyLayer}%
\EndIndex{Cmd}{RedeclareLayer}%
\EndIndex{Cmd}{ProvideLayer}%
\EndIndex{Cmd}{DeclareNewLayer}%
\EndIndex{Cmd}{DeclareLayer}%

\begin{Declaration}
  \Macro{layerxoffset}\\
  \Macro{layeryoffset}\\
  \Macro{layerwidth}\\
  \Macro{layerheight}%
\end{Declaration}
\BeginIndex{Cmd}{layerxoffset}%
\BeginIndex{Cmd}{layeryoffset}%
\BeginIndex{Cmd}{layerwidth}%
\BeginIndex{Cmd}{layerheight}%
These commands are valid during output of the layer's contents only. So they
can only be used inside the \PName{code} of option \Option{contents} of the
previously described commands. In this case they give the effective position
and dimension of the layer, that will be used for the output. However, the
effective dimension of the layer's contents may differ, i.\,e., if the
contents are oversized or do not fill the layer completely. Redefinition of
the commands to change the stored values is strictly forbidden and would
result in unpredictable issues.%
\EndIndex{Cmd}{layerheight}%
\EndIndex{Cmd}{layerwidth}%
\EndIndex{Cmd}{layeryoffset}%
\EndIndex{Cmd}{layerxoffset}%

\ifnum\currentversionlt{3.16}\else
\begin{Declaration}
  \Macro{GetLayerContents}\Parameter{layer name}
\end{Declaration}
\BeginIndex{Cmd}{GetLayerContents}%
This\ChangedAt{v3.16}{\Package{scrlayer}} command results in the whole content
of a layer. You have to note\textnote{Attention!} that using this
command inside the \PName{code} of the layer attributes \Option{contents},
\Option{addcontents}, or \Option{pretocontents} can result in
an infinite recursion, if the content of the current layer is referenced. You
yourself should avoid such situations!%
\EndIndex{Cmd}{GetLayerContents}%
\fi

\begin{Declaration}
  \Macro{IfLayerExists}%
  \Parameter{string}\Parameter{then-code}\Parameter{else-code}
\end{Declaration}
\BeginIndex{Cmd}{IfLayerExists}%
This command may be used to execute code depending on whether or not a layer
has been defined already. If the layer exists \PName{then-code} will be
executed, otherwise \PName{else-code}. Note, the command cannot really
test whether a layer exists. It uses a heuristic, that will never be false
negative, but may be false positive. Nevertheless, if it is false positive
something went wrong, either an incompatible package has been used or the user
made something he should not do.%
\EndIndex{Cmd}{IfLayerExists}

\begin{Declaration}
  \Macro{DestroyLayer}\Parameter{layer name}
\end{Declaration}
\BeginIndex{Cmd}{DestroyLayer}%
This command sets all macros corresponding with the layer with given
\PName{layer name} to \Macro{relax}, if a layer with that name exists. As a result the layer cannot be used any longer. It does not matter, if the layer
is still part of the layer list of a page style, because such destroyed layers
will be ignored. Nevertheless, destroyed layers may be defined again using
\Macro{DeclareNewLayer} or \Macro{ProvideLayer}, but cannot be changed using
\Macro{RedeclareLayer} or \Macro{ModifyLayer} any longer. 

The command is intended to be used inside
\Macro{scrlayerOnAutoRemoveInterface} to remove layers, which have been
defined using removable macros of an interface, whenever the interface would
be removed.%
\EndIndex{Cmd}{DestroyLayer}

\begin{Declaration}
  \Macro{layercontentsmeasure}%
\end{Declaration}
\BeginIndex{Cmd}{layercontentsmeasure}%
The command \Macro{layercontentsmeasure} prints a ruler at each layer edge, of
which the top and left one is labelled with centimeters, the right and bottom
one with inches.  This command is used internally, if option
\Option{draft}\IndexOption{draft} is enabled. The rulers will be drawn behind
the content of each layer.  It can also be used as exclusive content of a
layer.%
\EndIndex{Cmd}{layercontentsmeasure}


\section{Declaration and Management of Page Styles}
\seclabel{pagestyles}

Until now we know layers, but we do not know how to use them. The
perhaps astonishing answer is: with page styles. In \LaTeX{}, page
styles usually define heads and foots of odd and even pages.

The head and foot of odd pages will be printed on pages with odd
page number in two-side mode or on all pages in single-side mode. This is
something like the layer attributes \Option{oddpage} and \Option{evenpage}.

The page head will be printed before the main contents of a page. The page
footer will be printed after the main contents of a page. So this is something
like the layer attributes \Option{background} and \Option{foreground}.

So it suggests itself to declare page styles as a list of layers. But instead of
having only four attributes \Option{oddpage}, \Option{evenpage},
\Option{background}, and \Option{foreground} all the attributes of layers
shown in \autoref{sec:scrlayer.layers} may be used.

The outcome of all such considerations is that layer page styles are one type
of page styles \Package{scrlayer} provides. A layer page style consists of
layers and several \emph{hooks}. For description of layers see
\autoref{sec:scrlayer.layers}.  The \emph{hooks} are points in the expansion
or execution of page styles you may add additional code to. Advanced users
know this already from commands like \Macro{AtBeginDocument} (see
\cite{latex:usrguide}) or \Macro{BeforeClosingMainAux} (see
\autopageref{desc:scrlfile.cmd.BeforeClosingMainAux}).

Alias page styles are another type of page styles provided by
\Package{scrlayer}. An alias page style wraps another page style. In other
words, the name of an alias page style is an alias name of another page style,
the aliased or original page style. Because of this, the manipulation of an
alias page style results in the manipulation of the original page style. If
the original page style is an alias page style too, the manipulation will
result in the manipulation of the aliased page style of that original page
style and so on until a real page style will be manipulated. Aliasing is not
restricted to \Package{scrlayer} page styles, but possible for all page
styles.

\begin{Declaration}
  \Macro{currentpagestyle}
\end{Declaration}
\BeginIndex{Cmd}{currentpagestyle}%
Package scrlayer patches \Macro{pagestyle} to set \Macro{currentpagestyle} to
the currently active page style. Note, \Macro{thispagestyle} does not change
\Macro{currentpagestyle}. But if you use \Macro{thispagestyle} the result of
\Macro{currentpagestyle} may be changed while executing the \LaTeX{} output
routine. However, this change will only occur, if \Macro{currentpagestyle} has
been actively protected from expansion up to execution of the output routine.

Note, the layer page styles described later in this section, will not need
the patch of \Macro{pagestyle} to set \Macro{currentpagestyle}. The patch has
been made for usage with other page styles. Additionally, 
\Macro{currentpagestyle} is empty before the first \Macro{pagestyle} after
loading \Package{scrlayer}. So if you define an end user page style interface,
it may be useful to use an implicit \Macro{pagestyle} to set the current page
style to a default page style.%
\EndIndex{Cmd}{currentpagestyle}

\begin{Declaration}
  \Macro{BeforeSelectAnyPageStyle}\Parameter{code}\\
  \Macro{AfterSelectAnyPageStyle}\Parameter{code}%^^A
\end{Declaration}
\BeginIndex{Cmd}{BeforeSelectAnyPageStyle}%
\BeginIndex{Cmd}{AfterSelectAnyPageStyle}%
The command \Macro{BeforeSelectAnyPageStyle} adds \PName{code} to the hook
that will be executed inside of \Macro{pagestyle} just before the page style
will be selected. You may use \texttt{\#1} as a placeholder for the argument
of \Macro{pagestyle}.

The command \Macro{AfterSelectAnyPageStyle} is similar, but the \PName{code}
will be executed just after the page style has been selected and after
\Macro{currentpagestyle} has been set to the name of the real page style.

Note\textnote{Attention!}, \PName{code} of both commands will be executed
only if a page style will be selected using \Macro{pagestyle}, but not,
e.\,g., if a page style will be selected using \Macro{thispagestyle}. Note
also, you cannot remove \PName{code} from the hook after adding it. But
the \PName{code} will be added locally, so you may use a group to limit the
scope of \PName{code}.%^^A
\EndIndex{Cmd}{AfterSelectAnyPageStyle}
\EndIndex{Cmd}{BeforeSelectAnyPageStyle}

\begin{Declaration}
  \Macro{DeclarePageStyleAlias}%
  \Parameter{alias page style name}\Parameter{original page style name}\\
  \Macro{DeclareNewPageStyleAlias}%
  \Parameter{alias page style name}\Parameter{original page style name}\\
  \Macro{ProvidePageStyleAlias}%
  \Parameter{alias page style name}\Parameter{original page style name}\\
  \Macro{RedeclarePageStyleAlias}%
  \Parameter{alias page style name}\Parameter{original page style name}
\end{Declaration}
\BeginIndex{Cmd}{DeclarePageStyleAlias}%
\BeginIndex{Cmd}{DeclareNewPageStyleAlias}%
\BeginIndex{Cmd}{ProvidePageStyleAlias}%
\BeginIndex{Cmd}{RedeclarePageStyleAlias}%
These commands may be used to define a page style with name \PName{alias page
  style name} that is simply an alias for an already existing page style with
name \PName{original page style name}. If there is already a page style
\PName{alias page style name}, then using \Macro{DeclarePageStyleAlias} or
\Macro{RedeclarePageStyleAlias} will destroy the alias before recreating it.

\Macro{DeclareNewPageStyleAlias} will throw an error message, if a page style
\PName{alias page style name} has already been defined before. It does not
matter if the already defined page style is a layer page style, an alias page
style or another page style.

\Macro{ProvidePageStyleAlias} will define the alias only if a page style
\PName{alias page style name} has not been defined before. If a page style
\PName{alias page style name} already exists nothing will be done.

\Macro{RedeclarePageStyleAlias} expects an already existing page style
\PName{alias page style name}. It will destroy that page style and afterwards
define the alias. If the page style \PName{alias page style name} does not
exist, then you will get an error.%
\EndIndex{Cmd}{RedeclarePageStyleAlias}%
\EndIndex{Cmd}{ProvidePageStyleAlias}%
\EndIndex{Cmd}{DeclareNewPageStyleAlias}%
\EndIndex{Cmd}{DeclarePageStyleAlias}

\begin{Declaration}
  \Macro{DestroyPageStyleAlias}\Parameter{page style name}%
\end{Declaration}
\BeginIndex{Cmd}{DestroyPageStyleAlias}%
This command makes the page style with given \PName{page style name}
\LaTeX-undefined, if it is an alias for another page style. Afterwards, the
page style may be defined newly with, e.g., \Macro{DeclareNewAliasPageStyle}
or \Macro{ProvideAliasPageStyle}. 

The command is intended to be used inside of
\Macro{scrlayerOnAutoRemoveInterface} to remove page styles that have been
declared by an interface and use removable macros of that interface.%
\EndIndex{Cmd}{DestroyPageStyleAlias}

\begin{Declaration}
  \Macro{GetRealPageStyle}\Parameter{page style name}%
\end{Declaration}
\BeginIndex{Cmd}{GetRealPageStyle}%
The command will result in the (recursive) real page name of the page style,
if the page style with given name \PName{page style name} is an alias of
another page style. In all other cases, even if there's no alias and no page
style named \PName{page style name}, the result would be simply \PName{page
  style name}. The command is fully expandable and may be used, e.g., in the
second argument of \Macro{edef}.%
\EndIndex{Cmd}{GetRealPageStyle}

\begin{Declaration}
  \Macro{DeclarePageStyleByLayers}%
  \OParameter{option list}\Parameter{page style name}\Parameter{layer list}\\
  \Macro{DeclareNewPageStyleByLayers}%
  \OParameter{option list}\Parameter{page style name}\Parameter{layer list}\\
  \Macro{ProvidePageStyleByLayers}%
  \OParameter{option list}\Parameter{page style name}\Parameter{layer list}\\
  \Macro{RedeclarePageStyleByLayers}%^
  \OParameter{option list}\Parameter{page style name}\Parameter{layer list}%
\end{Declaration}
\BeginIndex{Cmd}{DeclarePageStyleByLayers}%
\BeginIndex{Cmd}{DeclareNewPageStyleByLayers}%
\BeginIndex{Cmd}{ProvidePageStyleByLayers}%
\BeginIndex{Cmd}{RedeclarePageStyleByLayers}%
These commands declare a page style with \PName{page style name}. The page
style will consist of the layers given in \PName{layer list}, a comma
separated list of layer names. Note, the \PName{page style name} and the
layer names at the \PName{layer list} must be fully expandable and should
expand to letters. Several other characters are tolerated, but,
nevertheless, not recommended.

The \PName{option list} is a comma separated list of
\OptionValue{\PName{key}}{\PName{value}} options. These options may be used to
set additional features. Currently they are used to set the code that should
be expanded or executed at several \emph{hooks}. See the introduction to this
section for more general information about \emph{hooks}. See
\autoref{tab:scrlayer.pagestyle.hooks} for detailed information on specific
hooks.

\begin{desclist}
  \desccaption{%
    The \emph{hook} options for page styles (in order of
    execution)\label{tab:scrlayer.pagestyle.hooks}%
  }{%
    The \emph{hook} options for page styles (\emph{Continuation})%
  }%
  \entry{\KOption{onselect}\PName{code}}{%
    Execute \PName{code} whenever the page style is selected using, e.g.,
    \Macro{pagestyle}. Note\textnote{Attention!}, \Macro{thispagestyle}
    does not select the page style immediately, but asynchronously inside
    \LaTeX's output routine.%
  }%
  \entry{\KOption{oninit}\PName{code}}{%
    Execute \PName{code} whenever the output of page style's layers
    is initialised. Note\textnote{Attention!}, this is done
    twice for every page: once for background layers and once for foreground
    layers.%
  }%
  \entry{\KOption{ononeside}\PName{code}}{%
    Execute \PName{code} whenever the output of page style's layers in
    single-side mode is initialised.  Note\textnote{Attention!}, this
    is done twice for every page: once for background layers and once for
    foreground layers.%
  }%
  \entry{\KOption{ontwoside}\PName{code}}{%
    Execute \PName{code} whenever the output of page style's layers in
    two-side mode is initialised.  Note\textnote{Attention!}, this is
    done twice for every page: once for background layers and once for
    foreground layers.%
  }%
  \entry{\KOption{onoddpage}\PName{code}}{%
    Execute \PName{code} whenever the output of page style's layers on
    an odd page is initialised. Note\textnote{Attention!}, this is
    done twice for every page: once for background layers and once for
    foreground layers. Note\textnote{Attention!} also that in single-side
    mode all pages are odd pages, not only pages with odd page numbers.%
  }%
  \entry{\KOption{onevenpage}\PName{code}}{%
    Execute \PName{code} whenever the output of page style's layers on
    an even page is initialised. Note\textnote{Attention!}, this is
    done twice for every page: once for background layers and once for
    foreground layers. Note\textnote{Attention!} also that there are not even
    pages in single-side mode, but all pages are odd pages, not only pages
    with odd page numbers.%
  }%
  \entry{\KOption{onfloatpage}\PName{code}}{%
    Execute \PName{code} whenever the output of page style's layers on
    a float page are initialised. Note\textnote{Attention!}, this is
    be done twice for every page: once for background layers and once for
    foreground layers. Note\textnote{Attention!} also that float pages are
    only those pages with p-placed floating objects.%
  }%
  \entry{\KOption{onnonfloatpage}\PName{code}}{%
    Execute \PName{code} whenever the output of page style's layers on
    a non-float page is initialised. Note\textnote{Attention!}, this
    is done twice for every page: once for background layers and once for
    foreground layers. Note\textnote{Attention!} also that non-float pages
    are all pages that are not float-pages. Those pages may have t-placed,
    h-placed, b-placed, or no floating objects.%
  }%
  \entry{\KOption{onbackground}\PName{code}}{%
    Execute \PName{code} whenever the output of page style's layers in
    the background of a page is initialised. Note\textnote{Attention!},
    this is done once for every page.%
  }%
  \entry{\KOption{onforeground}\PName{code}}{%
    Execute \PName{code} whenever the output page style's layers in
    the foreground of a page is initialised. Note\textnote{Attention!},
    this is done once for every page.%
  }%
\end{desclist}

The difference of \Macro{DeclarePageStyleByLayers} and
\Macro{DeclareNewPageStyleByLayers} is that \Macro{DeclareNewPageStyleByLayers}
will result in an error, if a page style with name \PName{page style name}
already exists. Note, declaring a page style, which is an alias of another
page style (see \Macro{DeclareAliasPageStyle} prior in this section), will not
re-declare the page style itself, but it's real page style (see
\Macro{GetRealPageStyle} prior in this section).

The difference of \Macro{DeclarePageStyleByLayers} and
\Macro{ProvidePageStyleByLayers} is that \Macro{ProvidePageStyleByLayers}
will simply do nothing, if there's already a page style with name \PName{page
  style name}. In difference to \Macro{DeclareNewPageStyleByLayers} it will not
raise an error.

The difference of \Macro{DeclarePageStyleByLayers} and
\Macro{RedeclarePageStyleByLayers} is, that \Macro{RedeclarePageStyleByLayers}
may be used only if the real page style of \PName{page style name} already
exists. Otherwise an error occurs.

Please have also a look at the notes to following pseudo page style
\Pagestyle{@everystyle@}.%
\EndIndex{Cmd}{RedeclarePageStyleByLayers}%
\EndIndex{Cmd}{ProvidePageStyleByLayers}%
\EndIndex{Cmd}{DeclareNewPageStyleByLayers}%
\EndIndex{Cmd}{DeclarePageStyleByLayers}%

\begin{Declaration}
  \Pagestyle{@everystyle@}\\
  \Pagestyle{empty}
\end{Declaration}
\BeginIndex{Pagestyle}{@everysel@}%
\BeginIndex{Pagestyle}{empty}%
There are two default layer page styles that are somehow special. The first
one is \Pagestyle{@everystyle@}. This page style should not be used like any
other page style, but the layers of this page style will be used by all the
other layer page styles. So adding a layer to this page style is similar to
adding this layer to all other layer page styles even the empty one. There's
one difference: Layer referencing commands of the page style interface like
\Macro{ForEachLayerOfPageStyle}, \Macro{AddLayerToPageStyleBeforeLayer}, or
\Macro{AddLayerToPageStyleAfterLayer} process only the layers of the page
style that has been referenced but not the layers implicated by
\Pagestyle{@everystyle@}.

The other somehow special page style is \Pagestyle{empty}. Normally page style
\Pagestyle{empty} is defined by the \LaTeX{} kernel, to be a page style
without page head or page foot. Package \Package{scrlayer} re-defines it to be
a layer page style without any layer. Nevertheless, you may use it like every
other layer page style too. The main advantage above the \LaTeX{} kernel's
empty page style is that it also executes the layers of special layer page
style \Pagestyle{@everysel@}.%
\EndIndex{Pagestyle}{empty}%
\EndIndex{Pagestyle}{@everysel@}%

\begin{Declaration}
  \KOption{onpsselect}\PValue{code}\\
  \KOption{onpsinit}\PValue{code}\\
  \KOption{onpsoneside}\PValue{code}\\
  \KOption{onpstwoside}\PValue{code}\\
  \KOption{onpsoddpage}\PValue{code}\\
  \KOption{onpsevenpage}\PValue{code}\\
  \KOption{onpsfloatpage}\PValue{code}\\
  \KOption{onpsnonfloatpage}\PValue{code}\\
  \KOption{onpsbackground}\PValue{code}\\
  \KOption{onpsforeground}\PValue{code}
\end{Declaration}
\BeginIndex{Option}{onpsselect~=\PName{code}}%
\BeginIndex{Option}{onpsinit~=\PName{code}}%
\BeginIndex{Option}{onpsoneside~=\PName{code}}%
\BeginIndex{Option}{onpstwoside~=\PName{code}}%
\BeginIndex{Option}{onpsoddpage~=\PName{code}}%
\BeginIndex{Option}{onpsevenpage~=\PName{code}}%
\BeginIndex{Option}{onpsfloatpage~=\PName{code}}%
\BeginIndex{Option}{onpsnonfloatpage~=\PName{code}}%
\BeginIndex{Option}{onpsbackground~=\PName{code}}%
\BeginIndex{Option}{onpsforeground~=\PName{code}}%
There's also a \KOMAScript{} option for each of those \texttt{hooks}. The
names of the \KOMAScript{} options are similar to the names of the page style
options, but with ``\texttt{ps}'' inserted behind ``\texttt{on}''. The value
of the \KOMAScript{} options are the initial defaults of the corresponding
\texttt{hooks}. These defaults will be extended at every declaration of page
style hook options via \PName{option list}. You may remove the default, using
\Macro{ModifyLayerPageStyleOptions} described later in this section.%
\EndIndex{Option}{onpsforeground~=\PName{code}}%
\EndIndex{Option}{onpsbackground~=\PName{code}}%
\EndIndex{Option}{onpsnonfloatpage~=\PName{code}}%
\EndIndex{Option}{onpsfloatpage~=\PName{code}}%
\EndIndex{Option}{onpsevenpage~=\PName{code}}%
\EndIndex{Option}{onpsoddpage~=\PName{code}}%
\EndIndex{Option}{onpstwoside~=\PName{code}}%
\EndIndex{Option}{onpsoneside~=\PName{code}}%
\EndIndex{Option}{onpsinit~=\PName{code}}%
\EndIndex{Option}{onpsselect~=\PName{code}}%

\begin{Declaration}
  \KOption{deactivatepagestylelayers}\PName{simple switch}\\
  \Macro{ForEachLayerOfPageStyle}\Parameter{page style name}\Parameter{code}
\end{Declaration}
\BeginIndex{Cmd}{ForEachLayerOfPageStyle}%
As long as \KOMAScript{} option \Option{deactivatepagestylelayers} has not
been activated command \Macro{ForEachLayerOfPageStyle} can be used to process
\PName{code} for every member layer of \PName{page style name}'s layers
list. Inside of \PName{code} the place holder \PValue{\#1} may be used to
reference the name of the current layer.
\begin{Example}
  If you want to print the names of all layers of page style
  \PValue{scrheadings}, you may us:
\begin{lstcode}
  \let\commaatlist\empty
  \ForEachLayerOfPageStyle{scrheadings}{%
    \commaatlist#1\gdef\commaatlist{, }}
\end{lstcode}
\end{Example}
Usage of \Macro{gdef} instead of \Macro{def} is necessary in the example
above, because \Macro{ForEachLayerOfPageStyle} executes the \PName{code}
inside of a group to minimise side effects. Here \Macro{gdef} redefines
\Macro{commaatlist} globally, so it would be still valid at the execution of
\PName{code} for the next layer.

Several other commands of \Package{scrlayer} also
use \Macro{ForEachLayerOfPageStyle} internally. So these also do not process
any layer if \KOMAScript{} option \Option{deactivatepagestylelayers} would be
activated. So you may use this options, e.g., to hide all layers of all layer
page styles.%
\EndIndex{Cmd}{ForEachLayerOfPageStyle}%

\begin{Declaration}
  \Macro{AddLayersToPageStyle}%
  \Parameter{page style name}\Parameter{layer list}\\
  \Macro{AddLayersAtBeginOfPageStyle}%
  \Parameter{page style name}\Parameter{layer list}\\
  \Macro{AddLayersAtEndOfPageStyle}%
  \Parameter{page style name}\Parameter{layer list}\\
  \Macro{RemoveLayersFromPageStyle}%
  \Parameter{page style name}\Parameter{layer list}%
\end{Declaration}
\BeginIndex{Cmd}{AddLayersToPageStyle}%
\BeginIndex{Cmd}{AddLayersAtBeginOfPageStyle}%
\BeginIndex{Cmd}{AddLayersAtEndOfPageStyle}%
\BeginIndex{Cmd}{RemoveLayersFromPageStyle}%
You can use these commands to add layers to a layer page style or to remove 
layers from a layer page style. The page style will be referenced by
\PName{page style name}. The layers are given by a comma separated
\PName{layer list}. 

The commands \Macro{AddLayersToPageStyle} and \Macro{AddLayersAtEndOfPageStyle}
add all layers of the comma separated list of layers \PName{layer list} at
the end of the layer list of layer page style \PName{page style
  name}. Logically the added layers would be above or in front of the old
layers of the page style. Nevertheless, new background layers would be behind
the text layer and therefore behind all foreground layers.

Command \Macro{AddLayersAtBeginOfPageStyle} adds the new layers at the begin
of the layer list of the page style. Note, the layers
will be added in the order of the \PName{layer list}. The first layer at
\PName{layer list} will be added first, the second layer will be added second
and so on. So with \Macro{AddLayersAtBeginOfPageStyle} the last layer at
\PName{layer list} will become the new first layer of the layer list of layer
page style \PName{page style name}.

Command \Macro{RemoveLayersFromPageStyle} may be used to remove layers from
the layer list of layer page style \PName{page style name} instead of adding
them. Note, layers, which are part of \PName{layer list}, but not part of
the page style's layer list, will be ignored. But adding or removing layers
from a page style, which is not a layer page style or an alias of a layer page
style, would be a mistake and result in an error message.%
\EndIndex{Cmd}{RemoveLayersFromPageStyle}%
\EndIndex{Cmd}{AddLayersAtEndOfPageStyle}%
\EndIndex{Cmd}{AddLayersAtBeginOfPageStyle}%
\EndIndex{Cmd}{AddLayersToPageStyle}

\begin{Declaration}
  \Macro{AddLayersToPageStyleBeforeLayer}%
  \Parameter{page style name}\Parameter{layer list}%
  \Parameter{reference layer name}\\
  \Macro{AddLayersToPageStyleAfterLayer}%
  \Parameter{page style name}\Parameter{layer list}%
  \Parameter{reference layer name}
\end{Declaration}
\BeginIndex{Cmd}{AddLayersToPageStyleBeforeLayer}%
\BeginIndex{Cmd}{AddLayersToPageStyleAfterLayer}%
These commands are similar to the commands described before, but they do not
add the layers at the begin or end of the layer list of a layer page style,
but just before or after a reference layer at the layer list of a layer page
style. Note, in this case the order of the \PName{layer list} will be
same in the layer list of \PName{page style name} after adding. If the
reference layer named \PName{reference layer name} is not part of the layer
list of the layer page style, nothing happens.%
\EndIndex{Cmd}{AddLayersToPageStyleAfterLayer}%
\EndIndex{Cmd}{AddLayersToPageStyleBeforeLayer}

\begin{Declaration}
  \Macro{UnifyLayersAtPageStyle}\Parameter{page style name}
\end{Declaration}
\BeginIndex{Cmd}{UnifyLayersAtPageStyle}%
With the commands described before in this section you may not only add
different layers to a page style, but even add the same layer several times to
a page style. In most cases it does not make sense to have one layer several
times at the layer list of a layer page style. So you may use
\Macro{UnifyLayersAtPageStyle} to remove all dupes of layers from the layer
list of a layer page style. 

Note\textnote{Attention!}, the order of layers may change! So if
you want a special order, you should remove all layers and add the layers in
the order you want instead of using \Macro{UnifyLayersAtPageStyle}.%
\EndIndex{Cmd}{UnifyLayersAtPageStyle}

\begin{Declaration}
  \Macro{ModifyLayerPageStyleOptions}%
  \Parameter{page style name}\Parameter{option list}\\
  \Macro{AddToLayerPageStyleOptions}%
  \Parameter{page style name}\Parameter{option list}
\end{Declaration}
\BeginIndex{Cmd}{ModifyLayerPageStyleOptions}%
\BeginIndex{Cmd}{AddToLayerPageStyleOptions}%
Command \Macro{ModifyLayerPageStyleOptions} may be used to modify the page
style options of a layer page style. Only options at the comma separated
\PName{option list} will be set to the new values given in \PName{option list}
if the new value is not empty. Options, which are not at \PName{option list},
will stay unchanged. If you want to set an option to \emph{do nothing} you may
use value \Macro{relax}. Note, setting an option to a new value using
\Macro{ModifyLayerPageStyleOptions} will remove the previous value including
the global default value.

\Macro{AddToLayerPageStyleOptions} differs from
\Macro{ModifyLayerPageStyleOptions} in that point. It will not overwrite the
previous values, but adds\,---\,or more precisely: concatenates\,---\, the new
values to the previous values of the options at \PName{option list}.%
\EndIndex{Cmd}{AddToLayerPageStyleOptions}%
\EndIndex{Cmd}{ModifyLayerPageStyleOptions}%

\begin{Declaration}
  \Macro{IfLayerPageStyleExists}%
  \Parameter{page style name}\Parameter{then code}\Parameter{else code}\\
  \Macro{IfRealLayerPageStyleExists}%^
  \Parameter{page style name}\Parameter{then code}\Parameter{else code}%
\end{Declaration}
\BeginIndex{Cmd}{IfLayerPageStyleExists}%
\BeginIndex{Cmd}{IfRealLayerPageStyleExists}%
Command \Macro{IfLayerPageStyleExists} tests, whether or not the real page
style of \PName{page style name} is a layer page style. If the test is true,
\PName{then code} will be executed. If \PName{page style name} is neither a
layer page style, nor an alias of a layer page style, nor an alias of an alias
of \dots\ a layer page style, \PName{else code} will be executed. Internally
this command is often used to throw an error message if you use one of the
layer page style commands with an \PName{page style name} that does not
correspond with a layer page style.

Command \Macro{IfRealLayerPageStyleExists} is similar, but \PName{then code}
will only be executed, if \PName{page style name} itself is the name of a
layer page style. So \PName{else code} will even be executed, if \PName{page
  style name} is an alias name of a layer page style or the alias name of an
alias name of \dots\ a layer page style.%
\EndIndex{Cmd}{IfRealLayerPageStyleExists}%
\EndIndex{Cmd}{IfLayerPageStyleExists}%

\begin{Declaration}
  \Macro{IfLayerAtPageStyle}%
  \Parameter{page style name}\Parameter{layer name}%
  \Parameter{then code}\Parameter{else code}\\
  \Macro{IfSomeLayerAtPageStyle}%
  \Parameter{page style name}\Parameter{layer list}%^
  \Parameter{then code}\Parameter{else code}\\
  \Macro{IfLayerAtPageStyle}%
  \Parameter{page style name}\Parameter{layer list}%
  \Parameter{then code}\Parameter{else code}%
\end{Declaration}
\BeginIndex{Cmd}{IfLayerAtPageStyle}%
\BeginIndex{Cmd}{IfSomeLayersAtPageStyle}%
\BeginIndex{Cmd}{IfLayersAtPageStyle}%
Command \Macro{IfLayerAtPageStyle} may be used to test, whether or not a layer
named \PName{layer name} is a member of the layer list of a given page
style. If the test is true, the \PName{then code} will be executed. If the
layer is not a member of the layer list of \PName{page style name}, the
\PName{else code} will be executed.

Commands \Macro{IfSomeLayerAtPageStyle} and \Macro{IfLayersAtPageStyle} do not
only test one layer but several layers at a given, comma separated
\PName{layer list}. \Macro{IfSomeLayerAtPageStyle} will execute the
\PName{then code} if \emph{at least one} of the layers at \PName{layer list}
is a member of the layer list of \PName{page style name}. In difference
\Macro{IfLayersAtPageStyle} executes the \PName{then code} only if \emph{all}
of the layers at \PName{layer list} are members of the layer list of
\PName{page style name}.%
\EndIndex{Cmd}{IfLayersAtPageStyle}%
\EndIndex{Cmd}{IfSomeLayersAtPageStyle}%
\EndIndex{Cmd}{IfLayerAtPageStyle}

\begin{Declaration}
  \Macro{DestroyRealLayerPageStyle}\Parameter{page style name}
\end{Declaration}
\BeginIndex{Cmd}{DestroyRealLayerPageStyle}%
Command \Macro{DestroyRealLayerPageStyle} makes the page style named
\PName{page style name} undefined, if and only if it is a layer page
style. Nothing will be happen if it is an alias name of a layer page style, if
it is another page style, or if it is not a page style. 

If \PName{page style name} is the name of the current page style the current
page style will become a kind of empty page style. If the special page
style\,---\,this may be set using \Macro{thispagestyle}\,---\,is \PName{page
  style name}, this will be simply reset. So the previous
\Macro{thispagestyle} will become invalid.

Note, the layers of the page style will not be destroyed
automatically. If you want to destroy the layers too, you may use
% Umbruchkorrektur
\begin{lstcode}[belowskip=\dp\strutbox]
  \ForEachLayerOfPageStyle{...}{\DestroyLayer{#1}}
\end{lstcode}
\emph{before} destroying the layer page style.

The command is intended to be used inside the auto-remove code of an interface
See \autoref{sec:scrlayer.enduserinterfaces} below for more information about
auto-remove code.%
\EndIndex{Cmd}{DestroyRealLayerPageStyle}

\LoadCommon{20} % \section{Height of Page Head and Foot}

\LoadCommon{21} % \section{Manipulation of Defined Page Styles}

\section{End User Interfaces}
\seclabel{enduserinterfaces}

Package \Package{scrlayer} provides an interface to define and manage
(concurrent) end user interfaces. Maybe future releases of \KOMAScript{} will
provide parts of this by package \Package{scrbase} and remove those commands
from \Package{scrlayer}. But currently this part if \Package{scrlayer} is very
experimental, so package \Package{scrlayer} provides its own interface
definition commands. Currently you should not depend on correct working of
auto-removing a concurrent end user interface. Instead you should avoid using
concurrent end user interfaces.

This section only describes the interface commands for defining end user
interfaces. This is not interesting for end users, but only for authors of end
user interfaces. End users will find information about the end user interfaces
in the sections about the particular end user interface, e.g.,
\autoref{cha:scrlayer-scrpage}, \autoref{cha:scrlayer-scrpage-experts}, and
\autoref{cha:scrlayer-notecolumn}.

\begin{Declaration}
  \Macro{scrlayerInitInterface}\OParameter{interface name}
\end{Declaration}
\BeginIndex{Cmd}{scrlayerInitInterface}%
Command \Macro{scrlayerInitInterface}
registers a new interface. The \PName{interface name} must be unique. If you
try to initialise an already initialised interface an error will occur. This
command is obligatory and mandatory for interfaces. It should be the first
interface command and therefore has been described first. If the optional
argument is omitted, \PValue{\Macro{@currname}.\Macro{@currext}} will be
used instead. For classes and packages this will be the file name of the class
or package while loading the class or package. But you may use any sequence of
characters with category letter or other.%
\EndIndex{Cmd}{scrlayerInitInterface}

\begin{Declaration}
  \KOption{forceoverwrite}\PName{simple switch}\\
  \KOption{autoremoveinterfaces}\PName{simple switch}\\
  \Macro{scrlayerAddToInterface}%
  \OParameter{interface name}\Parameter{command}\Parameter{code}\\
  \Macro{scrlayerAddCsToInterface}%
  \OParameter{interface name}\Parameter{command sequence}\Parameter{code}
\end{Declaration}
\BeginIndex{Option}{forceoverwrite}%
\BeginIndex{Option}{autoremoveinterfaces}%
\BeginIndex{Cmd}{scrlayerAddToInterface}%
\BeginIndex{Cmd}{scrlayerAddCsToInterface}%
One of the special features of end user interfaces is that they should
register all interface dependent commands (also known as \emph{macros}). You
may do this using \Macro{scrlayerAddToInterface}%^^A
. If your interface generates macros not only at load time but also at run
time or if the interface name should not be the class's or package's name, you
have to use the optional argument to add the command to a dedicated
interface. An error will occur, if the interface has not been initialised
before.

The first mandatory argument is the \PName{command}\footnote{The
  \PName{command} consists of the backslash followed by a \PName{command
    sequence} consisting of characters with category code letter or one other
  character, or \PName{command} consists of one active character (without
  backslash).} that should be added to the interface. If the command can be
added to the interface, it will be added to the interface, will be set to
\Macro{relax} and \PName{code} will be executed. You can use, e.g.,
\Macro{newcommand}\PName{command} inside of \PName{code} to define
\PName{command}.

But when can a command be defined? If a command is undefined or \Macro{relax}
it can be defined. If a command has already been defined and registered for
another interface \emph{and} if \KOMAScript{} option
\Option{autoremoveinterface} has been switched on, the other interface will be
removed automatically and the new command will be set to \Macro{relax} and
will be registered for the given interface. If a command
has already been defined but is not part of another interface \emph{and} if
\KOMAScript{} option \Option{forceoverwrite} has been switched on, the command
will be set to \Macro{relax} and will be registered for the given interface.

Command \Macro{scrlayerAddCsToInterface} is similar to
\Macro{scrlayerAddToInterface} but does not expect a command as first,
mandatory argument, but a command sequence\footnote{A command sequence may
  consist of any characters with category code letter or other.}.%
\EndIndex{Cmd}{scrlayerAddCsToInterface}%
\EndIndex{Cmd}{scrlayerAddToInterface}
\EndIndex{Option}{autoremoveinterfaces}%
\EndIndex{Option}{forceoverwrite}%

\begin{Declaration}
  \Macro{scrlayerOnAutoRemoveInterface}%^^A
  \OParameter{interface name}\Parameter{code}
\end{Declaration}
\BeginIndex{Cmd}{scrlayerOnAutoRemoveInterface}%
Command \Macro{scrlayerOnAutoRemoveInterface}
registers \PName{code} to be executed, if the interface will be automatically
removed (see \Option{autoremoveinterfaces} prior in this section). This may be
used, e.g., to automatically destroy layers or page styles (see
\Macro{DestroyLayer}, \Macro{DestroyAliasPageStyle}, and
\Macro{DestroyRealLayerPageStyle}).%
\EndIndex{Cmd}{scrlayerOnAutoRemoveInterface}%
%
\EndIndex{}{layer}
\EndIndex{Package}{scrlayer}

%%% Local Variables:
%%% mode: latex
%%% mode: flyspell
%%% coding: us-ascii
%%% ispell-local-dictionary: "en_GB"
%%% TeX-master: "../guide"
%%% End: