diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex | 1911 |
1 files changed, 1036 insertions, 875 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex index 77492066753..65c8cf865d6 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex @@ -1,6 +1,6 @@ % ====================================================================== % scrlayer.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -18,7 +18,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrlayer.tex -% Copyright (c) Markus Kohm, 2013-2017 +% Copyright (c) Markus Kohm, 2013-2018 % % Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, % Version 1.3c, verteilt und/oder veraendert werden. @@ -46,111 +46,110 @@ % ============================================================================ \KOMAProvidesFile{scrlayer.tex} - [$Date: 2017-08-08 11:47:52 +0200 (Tue, 08 Aug 2017) $ + [$Date: 2018-02-28 13:23:23 +0100 (Wed, 28 Feb 2018) $ KOMA-Script guide (chapter:scrlayer)] -\translator{Markus Kohm} +\translator{Markus Kohm\and Karl Hagen} -% Date of the translated German file: 2017-08-08 +% Date of the translated German file: 2018-02-01 -\chapter[{Defining Layers and Page Styles Using \Package{scrlayer}}]% -{Defining Layers and Page Styles Using \Package{scrlayer}% -} +\chapter[{Defining Layers and Page Styles with \Package{scrlayer}}] + {Defining\ChangedAt{v3.12}{\Package{scrlayer}} Layers and Page Styles with + \Package{scrlayer}} \labelbase{scrlayer} + \BeginIndexGroup \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 +Most users of graphics software are already familiar with the layer model for +a page. Such a model is rather alien to \LaTeX{} itself, but some packages, +like \Package{eso-pic} or \Package{textpos}, provide a kind of +background or foreground layer. \Package{scrlayer} is another package that +provides such background and foreground layers, but unlike the packages +mentioned above, these layers are part of the page style. As a result, you can +switch between different layers simply by switching the page style. + +To do so, the package also supports a low-level interface for defining page +styles that are based on a stack or list of layers, for adding layers to such +a layer stack, either at the top or the bottom, or before or after a specific +layer, and for removing individual layers and duplicates from a stack. In a +nutshell, the page style interface of \Package{scrlayer} provides commands to +define page styles based on a stack of layers and to manage those stacks. + +Nevertheless, using the layers directly is recommended for advanced users +only. Interfaces for beginners and average users are provided by additional +packages that in turn load \Package{scrlayer}. 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. \LoadCommonFile{options} % \section{Early or Late Selection of Options} -\section{Some Generic Information} -\seclabel{generic} +\section{Generic Information} +\seclabel{generic.information} -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. +The package needs some generic information about the class being used. Class +authors can help \Package{scrlayer} by providing the appropriate information. +Otherwise the package will try to determine this information for itself. This +works, for example, for the standard and the \KOMAScript{} classes. It may +work with other classes, or it may fail in whole or in part. -This section describes some of the information, that class authors may -provide. Generally users need not to care about this. +This section describes some of the information that class authors can provide. +Normally, users should not have to worry about it. \begin{Declaration} \Macro{if@chapter}\ \PName{then code}\ \textMacro{else}\ % \PName{else code}\ \textMacro{fi}% \end{Declaration} -If \Macro{if@chapter} is \Macro{iftrue}, \Package{scrlayer} will additionally -consider the chapter level, e.g., processing option -\DescRef{\LabelBase.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 -\DescRef{maincls.cmd.chapter}. If \DescRef{maincls.cmd.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}.% +If \Macro{if@chapter} is defined and corresponds to +\Macro{iftrue}\IndexCmd{iftrue}, \Package{scrlayer} takes the chapter level +into account when, for example, processing the +\DescRef{\LabelBase.option.automark} option. If it is defined but is not +\Macro{iftrue}, \Package{scrlayer} handles only the +\DescRef{maincls.cmd.part}, \DescRef{maincls.cmd.section}, +\DescRef{maincls.cmd.subsection}, \Macro{sub\dots subsection}, +\DescRef{maincls.cmd.paragraph}, \DescRef{maincls.cmd.subparagraph}, +\Macro{sub\dots subparagraph} sectioning units. If the macro is undefined, +\Package{scrlayer} searches for \DescRef{maincls.cmd.chapter}. If +\DescRef{maincls.cmd.chapter} is defined and does not correspond to +\Macro{relax}, \Package{scrlayer} defines \Macro{if@chapter} to +\Macro{iftrue}. Otherwise \Macro{if@chapter} becomes +\Macro{iffalse}\IndexCmd{iffalse}.% \EndIndexGroup \begin{Declaration} - \Macro{if@mainmatter}\ \PName{then code}\ \textMacro{else}\ % - \PName{else code}\ \textMacro{fi}% + \Macro{if@mainmatter}\ \PName{then code}\ % + \textMacro{else}\ \PName{else code}\ \textMacro{fi}% \end{Declaration} -Classes like \Class{book} define \DescRef{maincls.cmd.frontmatter}, -\DescRef{maincls.cmd.mainmatter}, and \DescRef{maincls.cmd.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 \DescRef{maincls.cmd.frontmatter}, \DescRef{maincls.cmd.mainmatter}, -or \DescRef{maincls.cmd.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 \DescRef{maincls.cmd.frontmatter}, +Classes like \Class{book} or \Class{scrbook} provide +\DescRef{maincls.cmd.frontmatter}\IndexCmd{frontmatter}, +\DescRef{maincls.cmd.mainmatter}\IndexCmd{mainmatter}, and +\DescRef{maincls.cmd.backmatter}\IndexCmd{backmatter} to switch between the +front, main, and end parts of a book. Typically, these classes also use +\Macro{if@mainmatter} internally to decide whether the current text is part of +the main body of the document or not. Classes like \Class{report} and +\Class{article} have no \DescRef{maincls.cmd.frontmatter}, +\DescRef{maincls.cmd.mainmatter}, or \DescRef{maincls.cmd.backmatter} and +therefore also lack \Macro{if@mainmatter}. + +It is easier for \Package{scrlayer} to avoid constantly testing for the +existence of these commands to decide whether to work in the main matter or +not, and instead to use \Macro{if@mainmatter}\IndexCmd{iftrue} with classes +like \Class{report} and \Class{article}. So if \Macro{if@mainmatter} is not +defined, \Package{scrlayer} defines it as a synonym for \Macro{iftrue}. + +Some classes, however, define \DescRef{maincls.cmd.frontmatter}, \DescRef{maincls.cmd.mainmatter}, or \DescRef{maincls.cmd.backmatter} but not -\Macro{if@mainmatter}. In this case \Package{scrlayer} also defines +\Macro{if@mainmatter}. In this case, \Package{scrlayer} also defines \Macro{if@mainmatter} to be \Macro{iftrue} and it extends definition of \DescRef{maincls.cmd.frontmatter}, \DescRef{maincls.cmd.mainmatter}, and -\DescRef{maincls.cmd.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.% +\DescRef{maincls.cmd.backmatter} to set \Macro{if@mainmatter} properly. +However, if there are other, comparable commands for switching between +different document parts. \Package{scrlayer} will not recognize them, does not +test for them, and therefore cannot extend them appropriately. In this case, +\Package{scrlayer} needs help of the class author to set \Macro{if@mainmatter} +correctly.% \EndIndexGroup @@ -158,103 +157,115 @@ other matter commands \Package{scrlayer} needs help of the class author to set \Macro{DeclareSectionNumberDepth}\Parameter{level name}% \Parameter{level depth} \end{Declaration} -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.% +Generally each section level is assigned an integer number indicating its +depth in the document structure. \LaTeX{} needs this to manage the hierarchy +of the section levels. But normally these values are known only to the +particular class that defines the section commands. This class then uses the +appropriate numbers inside the corresponding commands. + +The \Package{scrlayer} package also needs information about the section +hierarchy. With the help of \Macro{DeclareSectionNumberDepth}, you can map the +name of a heading level to a corresponding \PName{level depth}. For example, +for the standard \Class{book} class, the \PName{level name}s would be +\PValue{part}, \PValue{chapter}, \PValue{section}, \PValue{subsection}, +\PValue{subsubsection}, \PValue{paragraph}, and \PValue{subparagraph}, and the +corresponding \PName{level depth}s would be -1, 0, 1, 2, 3, 4, and 5. + +The \Package{scrlayer} package tries to determine the \PName{level depth}s on +its own while loading and again during \Macro{begin}\PParameter{document}. But +if this fails, for example because you use completely different sectioning +commands, you can define the relationship explicitly with +\Macro{DeclareSectionNumberDepth}.% \EndIndexGroup -\section{Declaration of Layers} +\section{Declaring 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, which are the answers to some basic questions: -\begin{description} -\item[Is the layer part of the background or the - foreground?\textnote{background or foreground}]% - 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. Normally, it makes sense to restrict the layer in this aspect. -\item[What is the position of the layer?\textnote{horizontal and vertical - position}]% - There are some attributes to define the horizontal and the vertical position - of a layer. -\item[What is the size of the layer?\textnote{horizontal and vertical size}]% - As for the position there are several attributes to define the width and - height of a layer. So a layer can also be smaller or larger than the paper - and it can be placed everywhere on the paper. -\item[How is a layer aligned on the paper?\textnote{alignment}]% - This question is answered by the alignment attribute. The horizontal position - can be relative from the left edge of the paper either to the left edge of - the layer or to the centre of the layer or to the right edge of the - layer. Also the vertical position can be relative from the to edge of the - paper either to the top edge of the layer or to the centre of the layer or - to the bottom edge of the layer. -\item[Is the layer intended for text or picture output?\textnote{text or - picture}]% - This question is also related to the position. For picture output users - often expect the origin at the bottom left corner of the layer. But this - would not be suitable for text output. So the origin of a text layer is the - height of a standard text line below the top left corner of the - layer. Picture layers on the other hand span a - \Environment{picture}\IndexEnv{picture} environment and provide addition - positioning commands. -\item[Should the layer be printed on left or right pages?\textnote{left or - right page}]% - 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. -\item[Should the layer be printed in single-side mode or two-side - mode?\textnote{single-side or two-side}]% - 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. -\item[Should the layer be printed on float pages or non-float - pages?\textnote{float page or non-float page}]% - \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. -\item[What are the contents of the layer?\textnote{contents}]% - The corresponding attribute are the commands that produce the output. -\end{description} -So we have eight questions that immediately result in 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 these primary -attributes. +A layer is an abstract model of a page. Unlike a real, physical sheet of +paper, this page is completely transparent. Typically, multiple layers are +stacked atop one another and opaque material on one layer hides material on +the layers below. The stack of layers is then merged to form the physical +page. The \Package{scrlayer} package provides two such stacks for each page: a +background stack and a foreground stack. The background stack is printed +beneath the normal page content, while the foreground stack is printed above +it. The normal page content is therefore a kind of a dividing layer between +the two layer stacks. + +A layer has several attributes that can be understood as answers to some basic +questions: +\iffree{\begin{description}}{% + \begingroup + \RedeclareSectionCommand[beforeskip=.5\baselineskip plus .25\baselineskip + minus .1\baselineskip]{paragraph}% + \renewcommand*\item[4][]{\paragraph*{#3{#4}#1}}% + }% +\item[Does the layer belong to the foreground or the background?]% + \leavevmode\textnote{foreground or background}\hskip 0pt + Background layers are output before the normal content of the page. + Therefore they appear behind or beneath the normal content of the page. + Foreground layers are then output after the normal content. Therefore they + appear on top of the normal content of the page. By default, a layer is both + a background layer \emph{and} a foreground layer and therefore is printed + twice. Usually it makes sense to limit the layer explicitly to either the + foreground or the background. +\item[What is the position of the layer?]% + \leavevmode\textnote{horizontal and vertical position}\hskip 0pt + To answer this question, there are attributes to define the layer's + horizontal and vertical position. +\item[How big is the layer?\textnote{horizontal and vertical size}]% + As with the position, there are also attributes to define the width and + height of a layer. Thus a layer can be smaller or larger than the paper + and it can be placed at different positions on the paper. +\item[How are the horizontal and vertical positions measured?]% + \leavevmode\textnote{alignment}\hskip 0pt + This question is answered by the alignment attribute. The horizontal + position can be measured from the left edge of the paper to the left edge of + the layer, to the centre of the layer, to the right edge of the layer. + Similarly, the vertical position can be measured from the top edge of the + paper to the top edge of the layer, the centre of the layer, or the bottom + edge of the layer. +\item[Is the layer intended for text or picture output?]% + \leavevmode\textnote{text or picture}\hskip 0pt + This question is closely related to the position. For example, users often + expect the origin for a picture to be at the lower left corner of the layer. + But this would not be suitable for text output. Therefore the origin of a + text layer is the height of a standard text line below the top left corner + of the layer. Picture layers, on the other hand, create a + \Environment{picture}\IndexEnv{picture} environment in which additional + positioning commands are available. +\item[Should the layer be printed on left or right pages?]% + \leavevmode\textnote{left or right page}\hskip 0pt + By default a layer will be printed on all pages. Note that \LaTeX{} treats + even pages as left-side pages and odd pages as right-side pages, but in + one-sided printing, only right-hand pages exist regardless of the page + number. +\item[Should the layer be printed in one-sided or two-sided mode?]% + \leavevmode\textnote{one-sided or two-sided}\hskip 0pt + By default a layer will be printed in both one-sided and two-sided + printing. Nonetheless, a layer that is restricted to even pages will never + be printed in one-sided printing and therefore is not a one-sided layer. +\item[Should the layer be printed on float pages or normal pages?]% + \leavevmode\textnote{float page or normal page}\hskip 0pt + \LaTeX{} produces float pages for objects from environments like tables or + figures if they are allowed to appear on a page without normal page contents + (see option \PValue{p} for \Environment{figure} or \Environment{table}). In + effect, the entire page is allowed to float within the document. Normal + pages in this sense are all pages that are not float pages. Normal pages can + also contain floats at the top, in the middle, or at the bottom of the page. + Very large floats can give the impression of being page floats, while in + reality they are floating environments placed at the top of a normal page. +\item[What are the contents of the layer?]% + \leavevmode\textnote{contents}\hskip 0pt + The corresponding attribute simply contains what should be printed whenever + the layer is output. +\iffree{\end{description}}{% + \endgroup\par\bigskip\noindent\ignorespaces +}% +These eight questions immediately give rise to a number of attributes. Later +\iffree{in this guide}, we will describe additional attributes. However, they +are only defined for convenience and can be expressed by a combination of +these primary attributes. \begin{Declaration} @@ -264,100 +275,96 @@ attributes. \Macro{RedeclareLayer}\OParameter{option list}\Parameter{layer name}% \Macro{ModifyLayer}\OParameter{option list}\Parameter{layer name} \end{Declaration} -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. +These commands can be used to define layers. The \PName{layer name} must be +fully expandable and should expand to ASCII letters only. Some additional +characters are accepted, but their use is only recommended for advanced users. -Command \Macro{DeclareLayer} does not care whether or not a layer with the +The \Macro{DeclareLayer} command 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 +define the layer with the attributes specified in the \PName{option list}. An +\PName{option} can be either a key or a key followed by an equal sign and +a value. Multiple options are separated by commas. To use a comma or a white +space within the value of an option, you must 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. +Unlike \Macro{DeclareLayer}, \Macro{DeclareNewLayer} reports an error if a +layer with the same \PName{layer name} already exists. This prevents the user +from accidentally using the same \PName{layer name} more than once. This +is especially useful when classes or packages also define layers internally. + +In contrast, \Macro{ProvideLayer} only defines a layer if there is no layer +with the same name already. If the name is in use for another layer, the new +definition is ignored. Therefore this command has the meaning, \emph{define + the layer only if it does not already exist.} + +If you want to redefine an existing layer, you can use \Macro{RedeclareLayer} +or \Macro{ModifyLayer}. With \Macro{RedeclareLayer}, the layer is first reset +to the default settings and then completely redefined via the specified +options list. In contrast, \Macro{ModifyLayer} does not reset the layer. +Only those attributes which are explicitly set in the \PName{option list} will +be changed. Applying either command to a previously undefined \PName{layer + name} results in an error. \begin{desclist} \desccaption{% - Options for the definition of page layers with description of the + Options for defining page layers and the meaning of the corresponding layer attribute\label{tab:scrlayer.layerkeys}% }{% - Options for the definition of layers (\emph{Continuation})% + Options for defining layers (\emph{continued})% }% \entry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \OptionVName{addcontents}{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}.% + The specified \PName{code} will be appended to the current value of the + \Option{contents} attribute, so the new content will appear at the end of + the existing content. For more information about the handling of + \PName{code} see the \Option{contents} option.% }% \entry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \OptionVName{addheight}{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 + The current value of the \Option{height} attribute will be increased by + the value of this option. You can use the same kind of values as for \Option{height}.% }% \entry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \OptionVName{addhoffset}{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 + The current value of the \Option{hoffset} attribute will be increased by + the value of this option. You can use the same kind of values as for \Option{hoffset}.% }% \entry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \OptionVName{addvoffset}{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 + The current value of the \Option{voffset} attribute will be increased by + the value of this option. You can use the same kind of values as for \Option{voffset}.% }% \entry{% \ChangedAt{v3.16}{\Package{scrlayer}}% \OptionVName{addwidth}{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 + The current value of the \Option{width} attribute will be increased by + the value of this option. You can use the same kind of values as for \Option{width}.% }% \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: + layer. Each \PName{alignment character} determines how the \PName{length} + of either the \Option{hoffset} or the \Option{voffset} option is + interpreted. Multiple \PName{alignment character}s can be used together + (without spaces or commas) and are evaluated in the order they occur. + Macros are not permitted in the value of the option. 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{b} --] align the layer at its bottom edge; the value of + \Option{voffset} is the distance from the top edge of the paper to the + bottom 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 + \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 @@ -371,228 +378,227 @@ there has not been a layer with \PName{layer name} defined before. \entry{\KOption{area}{% \Parameter{hoffset}\Parameter{voffset}% \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}}.% + This composite option sets the primary attributes + \OptionValue{hoffset}{horizontal offset}, \OptionValue{voffset}{vertical + offset}, \OptionValue{width}{width}, \OptionValue{height}{height}.% }% \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% \Option{backandforeground}}{% - This option removes any foreground or background restriction of the layer. - Generally usage of this option makes no sense, but it is provided for - completeness of the user interface. The option does not expect any value.% + This option removes the restriction of a layer to the foreground or the + background. In general, this option makes little sense, but it is provided + for the sake of a complete user interface. This option does not expect or + allow a value.% }% \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.% + This option displays the layer in the background only. The default is to + display layers in both the background and the foreground. This option does + not expect or allow a value.% }% \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.% + This composite option sets the primary attributes \Option{hoffset}, + \Option{voffset}, \Option{width}, \Option{height}, and \Option{align} so + that the layer spans the paper horizontally from the left edge to the + right and vertically from immediately beneath the footer to the bottom + edge of the paper.% }% \entry{\KOption{clone}{\PName{layer name}}}{% - The composed option sets all primary attributes of the layer to the same + This composite 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!% + name}. See the notes on the \PName{layer name} at the beginning of the + explanation for \Macro{DeclareLayer}. The layer to be cloned must also + already exist.% }% \entry{\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.% + The specified \PName{code} will be expanded whenever the layer is printed. + This \PName{code} defines what you see for the layer. No tests are made to + see if the code is valid. Errors in the \PName{code} can therefore lead to + multiple error messages 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}.% + This option causes the layer to appear on even pages only, unlike the + default, where a layer will appear on both even and odd pages. Since even + pages only appear in two-sided printing, this option implies + \Option{twoside}. This option does not expect or allow a value.% }% \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% \Option{everypage}}{% - This is a combination of \Option{oddorevenpage} and - \Option{floatornonfloatpage}. The option does not expect any value.% + This option is a combination of \Option{oddorevenpage} and + \Option{floatornonfloatpage}. This option does not expect or allow a + value.% }% \entry{\Option{everyside}}{% - This option removes any restriction of the layer to single side or double - side printing. This is also the default of layers. The option does not - expect any value.% + This option removes any restriction of the layer to one-sided or two-sided + printing. This is the default setting. This option does not expect or + allow a value.% }% \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% \Option{floatornonfloatpage}}{% This option removes any restriction of the layer to float or non-float - pages. So the layer will be printed independent of whether a page is a - float page or not. This is also the default of layers. The option does - not expect any value.% + pages and restores the default setting. This option does not expect or + allow a value.% }% \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.% + This option restricts the layer to appearing on float pages only. The + default setting is for layers to appear on both float and non-float pages. + This option does not expect or allow a value.% }% \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}.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the page footer over the width of the text area. This option does + not expect or allow a value.% }% \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}).% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical distance between the text area and the page footer over + the width of the text area. Note, however, that although the height of + this area depends on \Length{footskip}, it is not the same. This option + does not expect or allow a value.% }% \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.% + This option displays the layer in the foreground only. The default is to + display layers in both the background and the foreground. The option does + not expect or allow a value.% }% \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}.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical area of the page header for the width of the text area. + The height corresponds to the length \Length{headheight}. This option does + not expect or allow a value.% }% \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.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical distance between the page header and the text area for + the width of the text area. The height corresponds to the length + \Length{headsep}. This option does not expect or allow a value.% }% \entry{\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}.% + Sets the height of the layer. Note that the \PName{length} can be a + \LaTeX{} length declared with \Macro{newlength}, a \TeX{} length declared + with \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}.% }% \entry{\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}.% + Sets the distance of the layer from the left edge of the paper. How the + distance is measured depends on the \Option{align} option. See the + \Option{height} option for more information about valid expressions for + \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.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the inner margin, from the edge of the page to the edge of the text + area and from the top to the bottom of the page. In one-sided printing, + the inner margin corresponds to the left margin. This option does not + expect or allow a value.% }% \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.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the left margin, from the left edge of the paper to the left edge of + the text area and from the top of the paper to the bottom. This option + does not expect or allow a value.% }% \entry{\ChangedAt{v3.19}{\Package{scrlayer}}% \OptionVName{mode}{mode}}{% - The primary option defines the \PName{mode} for the layer output. Default - is \OptionValue{mode}{text}. The Baseline of the first text line will be - placed the height of one standard text line below the top edge of the - layer. Therefore the text output will be top aligned in the layer. In - \PValue{picture} \PName{mode} the layer spans a \Environment{picture} - environment with the origin in the bottom left corner of the layer. The - also available \PValue{raw} \PName{mode} current is the same like - \PValue{text} \PName{mode}. - - Changing\textnote{Attention!} the \PName{mode} of a layer generally can - move the contents. Additionally, i.\,e., \PValue{picture} \PName{mode} + This primary option defines the \PName{mode} in which the layer's content + is output. The default is \OptionValue{mode}{text}. The baseline of the + first text line is placed the height of one standard text line below the + top edge of the layer, so the text is usually neatly aligned with the top + of the layer. In \PValue{picture} \PName{mode}, on the other hand, the + layer spans a \Environment{picture} environment with the origin at the + bottom left corner of the layer. The \PValue{raw} \PName{mode} is also + also defined. By default it corresponds to \PValue{text} \PName{mode}. + Changing\textnote{Attention!} the \PName{mode} of a layer usually results + the contents shifting. Furthermore, the \PValue{picture} \PName{mode} provides additional commands that result in errors with another - \PName{mode}. Therefore, generally it makes no sense to change the - \PName{mode} of a layer after it's initial declaration!% + \PName{mode}. Therefore it usually makes no sense to change the + \PName{mode} of a layer after its initial declaration!% }% \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.% + This option restricts the layer to pages that are not float pages. The + default is for the layer to appear on both float and non-float pages. This + option does not expect or allow a value.% }% \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% \Option{oddorevenpage}}{% - Removes any restriction of the layer to odd or even pages. So it will be - printed independently of whether a page is odd or even. This is also the - default of layers. The option does not expect any value.% + This option removes any restriction of the layer to odd or even pages, + restoring the default behaviour that the layer should appear on both odd + and even pages. The option does not expect or allow a value.% }% \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.% + This option restricts the layer to odd pages only. The default is for + layers to appear on both odd pages and on even pages. Note that in + one-sided printing, all pages are odd, regardless of the page number. This + option does not expect or allow a value.% }% \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.% + This option restricts the layer to one-sided printing only. The default is + for layers to appear in both one-sided and two-sided printing. This option + does not expect or allow a value.% }% \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.% + The composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the outer margin of the page, from the top to the bottom of the + paper. The outer margin corresponds to the right margin in one-sided + printing. This option does not expect or allow a value.% }% \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.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the the whole paper. This option does not expect or allow a value.% }% \entry{\ChangedAt{v3.16}{\Package{scrlayer}}% \OptionVName{pretocontents}{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}.% + The value of \PName{code} is prefixed the current value of the + \Option{contents} attribute, so the new content will appear before the + existing content. For more information about the handling of \PName{code}, + see the \Option{contents} option.% }% \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.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the right margin, from the right edge of the text area to the right + edge of the paper and from the top to the bottom edge of the paper. This + option does not expect or allow a value.% }% \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.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the entire text area. This option does not expect or allow a value.% }% \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.% + This composite option sets \Option{hoffset}, \Option{voffset}, + \Option{width}, \Option{height}, and \Option{align} so that the layer + spans the vertical distance between the top edge of the paper to the + header for the entire width of the paper. This option does not expect or + allow a value.% }% \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.% + This option restricts the layer to two-sided printing. The default is for + layers to appear in both one-sided and two-sided printing. This option + does not expect or allow a value.% }% \entry{\ChangedAt{v3.18}{\Package{scrlayer}}% \Option{unrestricted}}{% - This option removes all output restrictions of the layer. It is a - combination of \Option{backandforeground}, \Option{everyside}, and - \Option{floatornonfloatpage}. The option does not expect any value.% + This option removes all output restrictions. It is a combination of + \Option{backandforeground}, \Option{everyside}, and + \Option{floatornonfloatpage}. This option does not expect or allow a + value.% }% \entry{\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}.% + Sets the distance of the layer from the top of the paper. How the distance + is measured depends on the \Option{align} option. See the \Option{height} + option for more information about valid expressions for \PName{length}.% }% \entry{\KOption{width}{\PName{length}}}{% - Sets the width of the layer. See \Option{height} for more information - about valid content of \PName{length}.% + Sets the width of the layer. See the \Option{height} option for more + information about valid expressions for \PName{length}.% }% \end{desclist} % @@ -607,46 +613,48 @@ there has not been a layer with \PName{layer name} defined before. \Macro{layerwidth}% \Macro{layerheight}% \end{Declaration} -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 alignment, -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. +These commands are only valid in the \PName{code} specified with +\Option{contents}, \Option{addcontents}, or \Option{pretocontents}. In this +case, they contain the layer's actual alignment, position, and dimensions that +will be used for the output. However, this is not necessarily the actual +dimensions of the layer's contents, e.\,g., if the contents are oversized or +do not fill the layer completely. The primary layer attribute \PValue{align} is mapped to \Macro{layerhalign}\ChangedAt{v3.19}{\Package{scrlayer}} and \Macro{layervalign}. The horizontal values \PValue{l} and \PValue{r} are -copied to \Macro{layerhalign}. The vertical values \PValue{r} and \PValue{b} -are copied to \Macro{layervalign}. The also horizontal and vertical value -\PValue{c} is copied to both commands. If \PValue{align} has contradictory -values, only the last one is copied. Therefore the resulting -\Macro{layerhalign} is either \PValue{l}, \PValue{c}, or \PValue{r} and the -resulting \Macro{layervalign} is either \PValue{r}, \PValue{c}, or \PValue{b}. - -Redefinition of the commands to change the stored values is strictly forbidden -and would result in unpredictable issues.% +copied to \Macro{layerhalign}. The vertical values \PValue{t} and \PValue{b} +are copied to \Macro{layervalign}. The value \PValue{c}, which is both +horizontal and vertical, is copied to both commands. If there are several +conflicting values for \PValue{align}, only the last one is copied. Thus the +resulting \Macro{layerhalign} is either \PValue{l}, \PValue{c}, or \PValue{r}, +and the resulting \Macro{layervalign} is either \PValue{r}, \PValue{c}, or +\PValue{b}. + +Redefining\textnote{Attention!} these instructions to change the values stored +in them is not permitted, as it would lead to unpredictable results.% \EndIndexGroup \begin{Declaration} \Macro{LenToUnit}\Parameter{length} \end{Declaration} -This\ChangedAt{v3.19}{\Package{scrlayer}} command has been copied from -\Package{eso-pic}\IndexPackage{eso-pic} 2.0f. It converts lengths into -multiples of \Length{unitlength}. It can be used everywhere \LaTeX{} -expects \Environment{picture} coordinates or \Length{unitlength}-depending -values. For more information see \cite{package:eso-pic} and the following -descriptions of \Macro{putUR}, \Macro{putLL}, and \Macro{putLR}. If the -command is already defined, e.\,g., by loading \Package{eso-pic} before +This\ChangedAt{v3.19}{\Package{scrlayer}} command originally came from +\Package{eso-pic}\IndexPackage{eso-pic}~2.0f. It converts lengths into +multiples of \Length{unit length} and can therefore be used everywhere \LaTeX{} +expects \Environment{picture} coordinates or \Length{unit length}-dependent +values. For more information, see \cite{package:eso-pic} and the descriptions +of \Macro{putUR}, \Macro{putLL}, and \Macro{putLR} below. If the command is +already defined, e.\,g., by loading \Package{eso-pic} before \Package{scrlayer}, the package does not define it again.% - +\iffalse% Umbruchkorrekturtext +\par It should be noted at this point that using package \Package{picture}\IndexPackage{picture}\textnote{\Package{picture}} (see \cite{package:picture}) supersedes \Macro{LenToUnit} more or less. The package -extends environment \Environment{picture} and the picture commands to accept -\LaTeX{} lengths directly.% +extends environment \Environment{picture} and the picture commands so that you +can use \LaTeX{} lengths directly for coordinates.% +\fi \EndIndexGroup @@ -658,180 +666,198 @@ extends environment \Environment{picture} and the picture commands to accept \Macro{putC}\Parameter{content} \end{Declaration} You\ChangedAt{v3.19}{\Package{scrlayer}} can use these commands inside the -value of primary layer option \PValue{contents}, if the layer is declared with -\OptionValue{mode}{picture}. In that case, \Macro{putUL} places the +value of \PValue{contents} layer option if the layer is declared with +\OptionValue{mode}{picture}. In this case, \Macro{putUL} places the \PName{content} relative to the upper left corner of the layer and therefore -is the same like +is the same as \lstinline[breaklines=false]|\put(0,\LenToUnit{\layerheight})|. \Macro{putUR} places the \PName{content} relative to the upper right corner of the layer and -therefore is the same like -\lstinline[breaklines=false]|\put(\LenToUnit{\layerwidth},\LenToUnit{\layerheight})|. +therefore is the same as +\lstinline[breaklines=false] +|\put(\LenToUnit{\layerwidth},\LenToUnit{\layerheight})|. \Macro{putLL} places the \PName{content} relative to the lower left corner of -the layer and therefore is the same like +the layer and therefore is the same as \lstinline[breaklines=false]|\put(0,0)|. \Macro{putLR} places the \PName{content} relative to the lower right corner and therefore is the same -like \lstinline[breaklines=false]|\put(\LenToUnit{\layerwidth},0)|. Last but -not least \Macro{putC} places the \PName{content} relative to the centre of +as \lstinline[breaklines=false]|\put(\LenToUnit{\layerwidth},0)|. Last but +not least, \Macro{putC} places the \PName{content} relative to the centre of the layer.% \begin{Example} - You want to investigate, how accurate + You want to determine exactly how accurately \OptionValueRef{typearea}{DIV}{classic} sets the height of the text area to - the width of the page size. So you declare a layer that not only border the - text area, but also places a circle with paper width as diameter dimension - into the centre of the text area: + the width of the page size. You declare a layer that both borders the text + area and places a circle with a diameter of the paper width in the centre of + the text area: \begin{lstcode} -\documentclass[DIV=classic]{scrartcl} -\usepackage{pict2e} -\usepackage{scrlayer} -\DeclareNewLayer[% - textarea,background,mode=picture, - contents={% - \putLL{\line(1,0){\LenToUnit{\layerwidth}}}% - \putLR{\line(0,1){\LenToUnit{\layerheight}}}% - \putUR{\line(-1,0){\LenToUnit{\layerwidth}}}% - \putUL{\line(0,-1){\LenToUnit{\layerheight}}}% - \putC{\circle{\LenToUnit{\paperwidth}}}% - } -]{showtextarea} -\DeclareNewPageStyleByLayers{test}{showtextarea} -\pagestyle{test} -\begin{document} -\null -\end{document} + \documentclass[DIV=classic]{scrartcl} + \usepackage{pict2e} + \usepackage{scrlayer} + \DeclareNewLayer[% + textarea,background,mode=picture, + contents={% + \putLL{\line(1,0){\LenToUnit{\layerwidth}}}% + \putLR{\line(0,1){\LenToUnit{\layerheight}}}% + \putUR{\line(-1,0){\LenToUnit{\layerwidth}}}% + \putUL{\line(0,-1){\LenToUnit{\layerheight}}}% + \putC{\circle{\LenToUnit{\paperwidth}}}% + } + ]{showtextarea} + \DeclareNewPageStyleByLayers{test}{showtextarea} + \pagestyle{test} + \begin{document} + \null + \end{document} \end{lstcode} - You will see that \Package{typearea}'s mapping to an integer \PName{DIV} + You will notice that \Package{typearea}'s mapping to an integer \PName{DIV} value is very accurate in this example. \end{Example} -For more information about the sketched Middle Age method of generating a text -area see \autoref{sec:typearea.circleConstruction}, +Incidentally, you will find more information about late medieval book-page +canon sketched in the example in \autoref{sec:typearea.circleConstruction}, \autopageref{sec:typearea.circleConstruction}. -For more information about command -\Macro{DeclareNewPageStyleByLayers}\IndexCmd{DeclareNewPageStyleByLayers} see -the description later in \autoref{sec:scrlayer.pagestyles}, -\DescPageRef{scrlayer.cmd.DeclareNewPageStyleByLayers}. In short: It -defines a new page style using the newly declared layer.% +The \Macro{DeclareNewPageStyleByLayers}\IndexCmd{DeclareNewPageStyleByLayers} +command just used in the example defines a new page style using the newly +declared layer. It will be explained in \autoref{sec:scrlayer.pagestyles}, +\DescPageRef{scrlayer.cmd.DeclareNewPageStyleByLayers}.% \EndIndexGroup \begin{Declaration} - \Macro{GetLayerContents}\Parameter{layer name} + \Macro{GetLayerContents}\Parameter{layer~name} \end{Declaration} -This\ChangedAt{v3.16}{\Package{scrlayer}} command results in the whole content -of a layer. You have to note\textnote{Attention!} that using this +This\ChangedAt{v3.16}{\Package{scrlayer}} command returns the whole contents +of a layer. It is important 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!% +infinite recursion when referencing the contents of the current layer. You +are responsible for avoiding such situations!% \EndIndexGroup \begin{Declaration} - \Macro{IfLayerExists}% - \Parameter{string}\Parameter{then-code}\Parameter{else-code} + \Macro{IfLayerExists}\Parameter{layer~name} + \Parameter{then-code}\Parameter{else-code} \end{Declaration} -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.% +This command can be used to execute code depending on whether or not a layer +with the specified \PName{layer name} exists. If the layer exists, the +\PName{then-code} will be executed; otherwise, the \PName{else-code} will be +executed. Note that the command cannot really test whether a layer exists. +Instead it uses a heuristic which will never yield a false negative but which, +in extreme cases, could yield a false positive. +\iffalse% Umbruchvarianten +Nevertheless, if the test yields a false positive, something has gone wrong. +For example, this could indicate an incompatible package or that the user is +doing something he or she should not.% +\else +False positives indicate a problem, such as the use of an incompatible package +or a bad choice of internal macro names by the user. +\fi \EndIndexGroup \begin{Declaration} - \Macro{DestroyLayer}\Parameter{layer name} + \Macro{DestroyLayer}\Parameter{layer~name} \end{Declaration} -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 -\DescRef{\LabelBase.cmd.DeclareNewLayer} or -\DescRef{\LabelBase.cmd.ProvideLayer}, but cannot be changed using +If a layer with the given \PName{layer name} exists, all macros belonging to +it will be set to \Macro{relax}. In page styles already defined with +\Package{scrlayer}, such destroyed layers are ignored. Destroyed layers can be +redefined using \DescRef{\LabelBase.cmd.DeclareNewLayer} or +\DescRef{\LabelBase.cmd.ProvideLayer}, but they can no longer be changed using \DescRef{\LabelBase.cmd.RedeclareLayer} or -\DescRef{\LabelBase.cmd.ModifyLayer} any longer. +\DescRef{\LabelBase.cmd.ModifyLayer}. The command is intended to be used inside -\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} to remove layers, which have been -defined using removable macros of an interface, whenever the interface would -be removed.% +\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} (see +\autoref{sec:scrlayer.enduserinterfaces}, +\DescPageRef{scrlayer.cmd.scrlayerOnAutoRemoveInterface}) +to remove layers defined using removable macros of an interface along with +that interface.% \EndIndexGroup \begin{Declaration} \Macro{layercontentsmeasure}% \end{Declaration} -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 -\DescRef{\LabelBase.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.% +The \Macro{layercontentsmeasure} command prints a ruler at each layer edge, of +which the top and left one is labelled in centimetres and the right and bottom +one in inches. This command is used internally if the +\DescRef{\LabelBase.option.draft}\IndexOption{draft} option is enabled. The +rulers are drawn behind the content of each layer. This command can also be +used as exclusive content of a layer.% \EndIndexGroup -\section{Declaration and Management of Page Styles} +\section{Declaring and Managing 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 +\BeginIndexGroup +\BeginIndex{}{page>style}% +We now understand how to define and manage layers, but so far we do not know +how they are used. The possibly surprising answer is, with page styles. In +\LaTeX{}, page styles usually define headers and footers of the page. + +The header and footer of odd or right-hand pages\textnote{even or odd page} +are printed on pages with odd page numbers in two-sided printing or on all +pages in one-sided printing. This is directly comparable to the layer +options\important[i]{\Option{evenpage}\\\Option{oddpage}} \Option{oddpage} and +\Option{evenpage}. + +The page header\textnote{header or footer} is output before the main page +contents. The page footer is output after the main page contents. This +corresponds directly to the layer +options\important[i]{\Option{background}\\\Option{foreground}} +\Option{background} and \Option{foreground}. + +Therefore it makes sense to define page styles as lists of layers. But instead +of just the four options mentioned above, you can use all the properties +explained in \autoref{sec:scrlayer.layers}, \autoref{tab:scrlayer.layerkeys}, +on \autopageref{tab:scrlayer.layerkeys}. + +As a result of these considerations, layer page +styles\textnote{layer page style}\Index{page style>layer}% +\Index{layer>page style}\Index{page>style} are one type of page style that +\Package{scrlayer} provides. A layer page style consists of layers as well as +several hooks. The layers have already been described in +\autoref{sec:scrlayer.layers}. The hooks\Index[indexmain]{hooks}% +\textnote{hooks} are points in the expansion or execution of page styles to +which you can add code. Experienced users already know this concept from +commands like \Macro{AtBeginDocument} (see \cite{latex:usrguide}) or +\DescRef{scrlfile.cmd.BeforeClosingMainAux} (see \DescPageRef{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. +Page-style aliases are another type of page style which \Package{scrlayer} +provides. A page-style alias is actually a different page style. In other +words, the name of a page-style alias is an alternative name for another +page-style alias or for a page style. As a result, manipulating a page-style +alias results in manipulating the original page style. If the original page +style is itself an alias, its manipulation again results in the manipulation +of the alias's original page style, and so on until a real page style is +finally changed. The term \emph{real page style}\textnote{real page style} is +used to distinguish it from a page-style alias. All page styles that are not +page-style aliases are real page styles. Aliases can be defined for all page +styles, not just those defined with \Package{scrlayer}. \begin{Declaration} \Macro{currentpagestyle} \end{Declaration} -Package scrlayer patches \DescRef{maincls.cmd.pagestyle} to set -\Macro{currentpagestyle} to the currently active page style. Note, -\DescRef{maincls.cmd.thispagestyle} does not change -\Macro{currentpagestyle}. But if you use \DescRef{maincls.cmd.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 \DescRef{maincls.cmd.pagestyle} to set \Macro{currentpagestyle}. The -patch has been made for usage with other page styles. Additionally, -\Macro{currentpagestyle} is empty before the first -\DescRef{maincls.cmd.pagestyle} after loading \Package{scrlayer}. So if you -define an end user page style interface, it may be useful to use an implicit -\DescRef{maincls.cmd.pagestyle} to set the current page style to a default -page style.% +The \Package{scrlayer} package patches the \DescRef{maincls.cmd.pagestyle} +command so that it sets \Macro{currentpagestyle} to the currently active page +style. Note that \DescRef{maincls.cmd.thispagestyle} does not change +\Macro{currentpagestyle}. If you use \DescRef{maincls.cmd.thispagestyle}, +however, \Macro{currentpagestyle} can change within the \LaTeX{} output +routine. However, this change will only occur if \Macro{currentpagestyle} has +been actively protected from expansion until the execution of the output +routine. + +Note that the layer page styles described later in this section do not rely on +this \DescRef{maincls.cmd.pagestyle} extension because they redefine +\Macro{currentpagestyle} themselves. This patch was made so that other, +non-\Package{scrlayer} page styles can use \Macro{currentpagestyle}. +Additionally, \Macro{currentpagestyle} is empty after loading +\Package{scrlayer} and before using \DescRef{maincls.cmd.pagestyle} for the +first time. Therefore, when defining an end-user interface, you may find it +useful to set the current page style to a default with an implicit +\DescRef{maincls.cmd.pagestyle} statement.% \EndIndexGroup @@ -839,201 +865,248 @@ page style.% \Macro{BeforeSelectAnyPageStyle}\Parameter{code}% \Macro{AfterSelectAnyPageStyle}\Parameter{code}% \end{Declaration} -The command \Macro{BeforeSelectAnyPageStyle} adds \PName{code} to the hook -that will be executed inside of \DescRef{maincls.cmd.pagestyle} just before -the page style will be selected. You may use \texttt{\#1} as a placeholder for -the argument of \DescRef{maincls.cmd.pagestyle}. - -The command \Macro{AfterSelectAnyPageStyle} is similar, but the \PName{code} -will be executed just after the page style has been selected and after -\DescRef{\LabelBase.cmd.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 \DescRef{maincls.cmd.pagestyle}, but -not, e.\,g., if a page style will be selected using -\DescRef{maincls.cmd.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}.% +The \Macro{BeforeSelectAnyPageStyle} command adds \PName{code} to the hook% +\textnote{hook} that will be executed inside \DescRef{maincls.cmd.pagestyle}, +just before the page style is selected. Within the \PName{code}, you can use +\texttt{\#1} as a place-holder for the argument of +\DescRef{maincls.cmd.pagestyle}. + +The \Macro{AfterSelectAnyPageStyle} command works similarly, but the +\PName{code} will be executed just after the page style has been selected and +after \DescRef{\LabelBase.cmd.currentpagestyle} has been set to the name of +the real page style. + +Note\textnote{Attention!} that the \PName{code} of both commands is executed +only if a page style is selected with \DescRef{maincls.cmd.pagestyle} and not +if it is chosen in a different way, e.\,g., using +\DescRef{maincls.cmd.thispagestyle}. Note also that you cannot remove +\PName{code} from the hook after adding it. But the \PName{code} will be added +locally, so you can use a group to limit the scope of the \PName{code}.% \EndIndexGroup \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} + \Macro{DeclarePageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original~page~style~name} + \Macro{DeclareNewPageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original~page~style~name} + \Macro{ProvidePageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original~page~style~name} + \Macro{RedeclarePageStyleAlias}\Parameter{page~style~alias~name} + \Parameter{original page style name} \end{Declaration} -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 +\BeginIndex{}{page style>alias}% +\BeginIndex{}{alias>page style}% +These commands can be used to define a page style with name \PName{page style + alias name} that is simply an alias for an existing page style with the name \PName{original page style name}. If there is already a page style -\PName{alias page style name}, then using \Macro{DeclarePageStyleAlias} or +\PName{page style alias name}, 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.% +\Macro{DeclareNewPageStyleAlias} will throw an error message if a page style +\PName{page style alias name} has already been defined. It does not matter if +the previously defined page style is a layer-page style, a page style alias, +or another page style. + +\Macro{ProvidePageStyleAlias} will define the alias only if the +\PName{page style alias name} page style has not been defined before. If the +\PName{page style alias name} page style already exists, nothing will be done. + +\Macro{RedeclarePageStyleAlias} expects an existing +\PName{page style alias name} page style. It will destroy that page style and +afterwards define the alias. If the \PName{page style alias name} page style +does not exist, you will get an error.% +\iffree{\csname @tempswafalse\endcsname}{\csname @tempswatrue\endcsname}% +\csname if@tempswa\endcsname% Umbruchkorrekturtext + \begin{Example} + Suppose you write a class and use the \PageStyle{chapter} page style for the + first page of each chapter. By default, this page style should match the + \PageStyle{plain} page style. Therefore, you can use the \Package{scrlayer} + package and use +\begin{lstcode} + \DeclareNewPageStyleAlias{chapter}{plain} +\end{lstcode} + to define the \PageStyle{chapter} page style as an alias for the + \PageStyle{plain} page style. If, on the other hand, you later decide that + the \PageStyle{chapter} plage style should correspond to the + \PageStyle{empty} page style, you can achieve this with: +\begin{lstcode} + \RedeclarePageStyleAlias{chapter}{empty} +\end{lstcode}% + \end{Example}% +\fi \EndIndexGroup \begin{Declaration} - \Macro{DestroyPageStyleAlias}\Parameter{page style name}% + \Macro{DestroyPageStyleAlias}\Parameter{page~style~name}% \end{Declaration} -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 -\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} to remove page styles that have been -declared by an interface and use removable macros of that interface.% +\BeginIndex{}{page style>alias}% +\BeginIndex{}{alias>page style}% +This command renders the page style named \PName{page style name} undefined +for \LaTeX{} if it is an alias for another page style. Afterwards, the page +style can be newly defined with +\DescRef{\LabelBase.cmd.DeclareNewPageStyleAlias} or +\DescRef{\LabelBase.cmd.ProvidePageStyleAlias}. + +This command is intended to be used inside the argument code of +\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} to remove page styles +that have been declared as part of an end-user interface when removing this +interface automatically.% \EndIndexGroup \begin{Declaration} - \Macro{GetRealPageStyle}\Parameter{page style name}% + \Macro{GetRealPageStyle}\Parameter{page~style~name}% \end{Declaration} -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}.% +\BeginIndex{}{page style>alias}% +\BeginIndex{}{alias>page style}% +This command will result in the (recursive) real page name of the page style +if \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 is simply \PName{page style name}. The command is fully +expandable and may be used, e.g., in the second argument of \Macro{edef}.% \EndIndexGroup \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}% + \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} -These commands declare a page style with \PName{page style name}. The page +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +These commands declare a page style named \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 +separated list of layer names. Note\textnote{Attention!} that the \PName{page + style name} and the layer names in the \PName{layer list} must be fully +expandable and should expand to letters. Several other characters are also +accepted, but their use is recommended only for experienced users. + +The \PName{option list} is a comma-separated list of options in the form +\texttt{\PName{key}=\PName{value}}. 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 hooks\Index{hooks}. See the introduction to +this section for more general information about 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 + Hook options for page styles (in order of execution)\label{tab:scrlayer.pagestyle.hooks}% }{% - The \emph{hook} options for page styles (\emph{Continuation})% + Hook options for page styles (\emph{continued})% }% \entry{\OptionVName{onselect}{code}}{% - Execute \PName{code} whenever the page style is selected using, e.g., - \DescRef{maincls.cmd.pagestyle}. Note\textnote{Attention!}, - \DescRef{maincls.cmd.thispagestyle} does not select the page style - immediately, but asynchronously inside \LaTeX's output routine.% + The \PName{code} of this hook\Index{hook} is executed whenever the page + style is selected, for example with \DescRef{maincls.cmd.pagestyle}. Note + that \DescRef{maincls.cmd.thispagestyle} itself does not directly select a + page style. In this case, the page style is only activated within \LaTeX's + output routine.% }% \entry{\OptionVName{oninit}{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.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers is initialised. Note that this happens twice + for each page: once for background layers and once for foreground layers.% }% \entry{\OptionVName{ononeside}{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.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers in one-sided printing is initialised. Note that + this happens twice for each page: once for background layers and once for + foreground layers.% }% \entry{\OptionVName{ontwoside}{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.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers in two-sided printing is initialised. Note that + this happens twice for each page: once for background layers and once for + foreground layers.% }% \entry{\OptionVName{onoddpage}{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.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on an odd page is initialised. Note that this + happens twice for each page: once for background layers and once for + foreground layers. Note also that in one-sided printing all pages are odd + pages, not just those with odd page numbers.% }% \entry{\OptionVName{onevenpage}{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.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on an even page is initialised. Note that this + happens twice for each page: once for background layers and once for + foreground layers. Note also that in one-sided printing there are no even + pages. Instead, all pages are treated as odd pages, not just those with + odd page numbers.% }% \entry{\OptionVName{onfloatpage}{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.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on a float page is initialised. Note that this + happens twice for each page: once for background layers and once for + foreground layers. Note also that float pages are only those pages with + one or more p-placed floating environments.% }% \entry{\OptionVName{onnonfloatpage}{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.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's layers on a non-float page is initialised. Note that + this happens twice for each page: once for background layers and once for + foreground layers. Note also that float pages are only the pages on which + one or more p-placed floating environments are output. Other pages may + well have t-, h-, or b-placed floating environments.% }% \entry{\OptionVName{onbackground}{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.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's background layers is initialised. Note that this + happens once each page.% }% \entry{\OptionVName{onforeground}{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.% + The \PName{code} of this hook\Index{hook} is executed whenever the output + of the page style's foreground layers is initialised. Note that this + happens once each 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 -\DescRef{\LabelBase.cmd.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 +\iffalse% Umbruchvarianten + While the \Macro{DeclarePageStyleByLayers} command always defines the page + style, \Macro{DeclareNewPageStyleByLayers} generates an error message if a + page style with the same name already exists. Note\textnote{Attention!} that + the declaration of a page style that is already an alias for another page + style (see, for example, \Macro{DeclareAliasPageStyle} earlier in this + section) will redefine not the specified page style alias but the real page + style (see \DescRef{\LabelBase.cmd.GetRealPageStyle} earlier in this + section).% +\else% + The \Macro{DeclarePageStyleByLayers} command defines the page style + regardless of whether a page style of \PName{page style name} already + exists. If necessary, the existing page style is completely + redefined. However, if a page style alias \PName{page style name} already + exists, the associated real page style, not the page style alias itself, is + redefined (see \DescRef{\LabelBase.cmd.GetRealPageStyle} earlier in this + section). + + The \Macro{DeclareNewPageStyleByLayers} command differs if a page style of + the same name already exists. Regardless of whether it is a real or an alias + page style, an error will be reported in this case. +\fi + +In contrast, \Macro{ProvidePageStyleByLayers} preserves the page style +unchanged if a page style with name \PName{page style name} already exists. If +no such page style exists, it is defined as in +\Macro{DeclarePageStyleByLayers}. + +The \Macro{RedeclarePageStyleByLayers} in turn expects that a page style of +of the name \PName{page style name} already exists and then redefines its real +page style. However, if no page style of the specified name exists, an error +message results. + +Also note the remarks below about the pseudo-page style \PageStyle{@everystyle@}.% \EndIndexGroup @@ -1042,25 +1115,35 @@ Please have also a look at the notes to following pseudo page style \PageStyle{@everystyle@}% \PageStyle{empty} \end{Declaration} -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 -\DescRef{\LabelBase.cmd.ForEachLayerOfPageStyle}, -\DescRef{\LabelBase.cmd.AddLayersToPageStyleBeforeLayer}, or -\DescRef{\LabelBase.cmd.AddLayersToPageStyleAfterLayer} 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@}.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +The \Package{scrlayer} package defines two specific page styles worth noting. +The first of these is \PageStyle{@everystyle@}% +\important{\PageStyle{@everystyle@}}. This page style should never be used +like a normal page style, for example with \DescRef{maincls.cmd.pagestyle} or +\DescRef{maincls.cmd.thispagestyle}, or as the target of a page-style alias. +Instead, the layers and hooks\Index{hooks} of this page style are used by all +other layer page styles. The hooks of \PageStyle{@everystyle@} are placed in +front of their respective hooks, and the layers in front of the respective +layers, of the active page style. + +Thus adding a layer to the pseudo-page style \PageStyle{@everystyle@} or code +to a hook of this page style is like adding a layer or hook code to all layer +page styles, even the empty one. There's one crucial difference: commands that +reference the layers of a page style which include +\DescRef{\LabelBase.cmd.ForEachLayerOfPageStyle}, e.\,g., the commands +\DescRef{\LabelBase.cmd.AddLayersToPageStyleBeforeLayer} or +\DescRef{\LabelBase.cmd.AddLayersToPageStyleAfterLayer}, disregard the layers +of the page style \PageStyle{@everystyle@} when applied to a different layer +page style. + +The second, slightly different page style is \PageStyle{empty}. Normally the +\LaTeX{} kernel defines the \PageStyle{empty} page style to have an empty +header and footer. The \Package{scrlayer} package redefines this page style as +a layerless page style. Nonetheless, you can use it like any other layer page +style. The main advantage of the layer page style over the original page +style from the \LaTeX{} kernel is that it also executes the hooks and layers +of the psuedo-layer page style \PageStyle{@everystyle@}.% \EndIndexGroup @@ -1076,13 +1159,23 @@ style \PageStyle{@everysel@}.% \OptionVName{onpsbackground}{code}% \OptionVName{onpsforeground}{code} \end{Declaration} -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 -\DescRef{\LabelBase.cmd.ModifyLayerPageStyleOptions} described later in this section.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +There is also a \KOMAScript{} option for each of the hooks\Index{hooks} in +\autoref{tab:scrlayer.pagestyle.hooks}% +\iftrue +. The names of the \KOMAScript{} options are similar to those for declaring +page style layers, except that a ``\texttt{ps}'' is inserted after +``\texttt{on}'' at the beginning of the name +\else +, into the names of which a ``\texttt{ps}'' is inserted +\fi +. The values of these \KOMAScript{} options are used as the initial values for +the corresponding hooks. These initial values are then extended by all the +values assigned to the corresponding hooks in the \PName{option list} of the +declaration commands. You can remove the default with +\DescRef{\LabelBase.cmd.ModifyLayerPageStyleOptions}, which is explained later +in this section.% \EndIndexGroup @@ -1090,13 +1183,14 @@ style hook options via \PName{option list}. You may remove the default, using \OptionVName{singlespacing}{simple switch} \end{Declaration} If\ChangedAt{v3.24}{\Package{scrlayer}\and \Package{scrlayer-scrpage}} a -document is printed with increased line-spread, e.g., using package -\Package{setspace}\IndexPackage{setspace}, often the page head and foot should -be printed single-spaced. This is surely true if the page head and foot -consist of only a single line. In those cases you can use \KOMAScript{} option -\Option{singlespacing}. Nevertheless, the default is -\OptionValue{singlespacing}{false}! The option influences always all page -styles. If you want single-spacing for only some page styles, use +document is printed with increased line spacing, e.\,g., using the +\Package{setspace}\IndexPackage{setspace}\important{\Package{setspace}} +package, it is often undesirable for the header and footer to be printed with +this increased spacing. This is particularly true if the header and footer +consist of only a single line. In this case you can use \KOMAScript{} option +\Option{singlespacing}. However, the default\textnote{default} is +\OptionValue{singlespacing}{false}! The option generally applies to all layer +page styles. If you want single-spacing for only some page styles, use \OptionValue{oninit}{\Macro{linespread}\PParameter{1}\Macro{selectfont}} for those page styles.% \EndIndexGroup @@ -1107,38 +1201,41 @@ those page styles.% \Macro{ForEachLayerOfPageStyle}\Parameter{page style name}\Parameter{code}% \Macro{ForEachLayerOfPageStyle*}\Parameter{page style name}\Parameter{code} \end{Declaration} -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. +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +As long as the \KOMAScript{} option \Option{deactivatepagestylelayers} is not +enabled, the \Macro{ForEachLayerOfPageStyle} command can execute arbitrary +\PName{code} for each layer of the page style named \PName{page style name}. +Inside of \PName{code}, the place holder \PValue{\#1} serves as a +reference to 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: + If you want to print the names of all layers of the \PValue{scrheadings} + page style as a comma-separated list, you can use: \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. +In\textnote{Attention!} the example above, we had to use \Macro{gdef} instead +of \Macro{def} because \Macro{ForEachLayerOfPageStyle} executes the +\PName{code} inside a group to minimise side effects. However, \Macro{gdef} +redefines \Macro{commaatlist} globally so the change will persist when the +\PName{code} for the next layer is executed. Alternatively,\ChangedAt{v3.18}{\Package{scrlayer}} you can use \Macro{def} -but the star variant \Macro{ForEachLayerOfPageStyle*}. This type does not use -an additional group for executing \PName{code}. On the other hand the user has -to take care on side effects of \PName{code}, i.\,e., deactivation of all -layers using \OptionValue{deactivatepagestylelayers}{true} in \PName{code} -would persist after \Macro{ForEachLayerOfPageStyle*}. - -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.% +with the starred variant \Macro{ForEachLayerOfPageStyle*}. This form dispenses +with the extra group when executing \PName{code}. However, the user then has +to take make sure that the \PName{code} has no unwanted side effects. In +particular, deactivating all layers using +\OptionValue{deactivatepagestylelayers}{true} within \PName{code} would +persist beyond the call to \Macro{ForEachLayerOfPageStyle*}. + +Various \Package{scrlayer} commands also use \Macro{ForEachLayerOfPageStyle} +internally. Their behaviour can therefore also be changed using the +\KOMAScript{} option \Option{deactivatepagestylelayers}. With this option, +you can temporarily disable and thus hide all layers of all layer page +styles.% \EndIndexGroup @@ -1152,32 +1249,39 @@ page styles.% \Macro{RemoveLayersFromPageStyle}% \Parameter{page style name}\Parameter{layer list}% \end{Declaration} -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.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +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 is referenced by its +\PName{page style name}. The layers are given by a comma-separated +\PName{layer list}. + +Both the \Macro{AddLayersToPageStyle} and the +\Macro{AddLayersAtEndOfPageStyle}\textnote{add at the end} commands insert the +new layers at the bottom of the page style's layer list. Logically, the newly +added layers lie above or in front of the old layers. Background layers, of +course, still are logically behind the text layer and thus behind all +foreground layers. + +In contrast, the \Macro{AddLayersAtBeginOfPageStyle}\textnote{add at the + beginning} command inserts the new layers at the top of the page style's +layer list. The layers are separately inserted to the top of the list in the +same order they appear in the \PName{layer list} parameter. This means that +the last layer in the \PName{layer list} parameter will become the first, and +thus the lowest, layer of the page style. + +\iffalse% Umbruchkorrekturtext (beim Aktiveren muss unten \textnote{remove} +% entfernt werden!) +The \Macro{RemoveLayersFromPageStyle} command is exactly the opposite. It +removes\textnote{remove} the specified page-style levels.% +\fi + +The \Macro{RemoveLayersFromPageStyle}\textnote{remove} command removes layers +from the layer list of the page style named \PName{page style name}. +Attempting to remove layers which are not part of the page style's layer list +will be ignored. But attempting to add layers to or remove layers from a page +style that is neither a layer page style nor a page-style alias is an error +and will be reported as such.% \EndIndexGroup @@ -1189,29 +1293,46 @@ style, would be a mistake and result in an error message.% \Parameter{page style name}\Parameter{layer list}% \Parameter{reference layer name} \end{Declaration} -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.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +\iffalse% Umbruchvarianten +These two commands are similar to the previous ones, but they take an +additional parameter, \Parameter{reference layer name}. The layer list of +the page style named in \Parameter{page style name} is searched for this +reference layer. % +\else% +These commands are similar to the previous ones. The existing layers of the +page style, however, are searched for the \PName{reference layer name}. % +\fi% +The layers in the \Parameter{layer list} parameter are then inserted +before\textnote{add before/after layer} or after this reference layer% +\iffalse% Umbruchkorrekturtext +in the layers of the page style% +\fi% +. The order of the layers in the \PName{layer list} is retained. + +If the reference layer named \PName{reference layer name} is not part of the +given page style, nothing is inserted. On the other hand, if the page style is +neither a layer page style nor a page-style alias, an error will be reported.% \EndIndexGroup \begin{Declaration} \Macro{UnifyLayersAtPageStyle}\Parameter{page style name} \end{Declaration} -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}.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +The commands for defining page styles or adding layers to a page style do not +care how many times a layer appears in a page style, so it is quite +permissible for a layer to appear multiple times. In most cases, however, it +does not make sense to use the same layer several times in one page style. +Therefore, you can use \Macro{UnifyLayersAtPageStyle} to remove all layer +duplicates from the layer page style of the specified \Parameter{page style + name}. + +Note\textnote{Attention!} that this function can change the order of layers. +So if you need a specific order, you should remove all layers and add the +layers in the order you want instead of using \Macro{UnifyLayersAtPageStyle}.% \EndIndexGroup @@ -1221,19 +1342,25 @@ the order you want instead of using \Macro{UnifyLayersAtPageStyle}.% \Macro{AddToLayerPageStyleOptions}% \Parameter{page style name}\Parameter{option list} \end{Declaration} -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}.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +These two commands can be used to modify the options, and thus the +hooks\Index{hooks}, of a layer page style. With +\Macro{ModifyLayerPageStyleOptions}\textnote{change page-style options}, only +the options in the comma-separated \PName{option list} will be set to the new +values given there. The previous values are lost. All options from +\autoref{tab:scrlayer.pagestyle.hooks}, +\autopageref{tab:scrlayer.pagestyle.hooks} are allowed. Options or hooks that +are not specified in the \PName{option list} will remain unchanged. If you +want to set an option to do nothing you can set it to the value \Macro{relax}. +Setting an option to a new value using \Macro{ModifyLayerPageStyleOptions} +will remove the previous value, including the global default value. This +statement is the only way to remove the global defaults of the \KOMAScript{} +options from a page style. + +\Macro{AddToLayerPageStyleOptions}\textnote{extend page-style options}, on the +other hand, does not overwrite the previous values. Instead it adds\,---\,or, +more precisely, concatenates\,---\, the new values to old ones.% \EndIndexGroup @@ -1243,20 +1370,21 @@ values to the previous values of the options at \PName{option list}.% \Macro{IfRealLayerPageStyleExists}%^ \Parameter{page style name}\Parameter{then code}\Parameter{else code}% \end{Declaration} -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.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +With these commands, you can execute code depending on whether a page style is +a layer page style or not. The \Macro{IfLayerPageStyleExists} command executes +the \PName{then code} if \PName{page style name} is the name of a layer page +style or a page-style alias that results in a layer page style. Otherwise, the +command executes the \PName{else code}. 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 to a layer page style. + +The \Macro{IfRealLayerPageStyleExists} command goes one step further and +executes the \PName{then code} only if the page style specified by \PName{page + style name} is itself a layer page style. So if \PName{page style name} is a +page-style alias, this command executes the \PName{else code} even if the +alias resolves to a real layer page style.% \EndIndexGroup @@ -1271,85 +1399,106 @@ alias name of \dots\ a layer page style.% \Parameter{page style name}\Parameter{layer list}% \Parameter{then code}\Parameter{else code}% \end{Declaration} -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}.% +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +These commands can be used to test whether one or more layers are part of a +page style. The \Macro{IfLayerAtPageStyle} command expects exactly one +\PName{layer name}\textnote{exactly one layer} as the second argument. If this +layer is part of the page style specified in \PName{page style name}, the +\PName{then code} will be executed. Otherwise, the \PName{else code} will be +executed. + +The \Macro{IfSomeLayerAtPageStyle} and \Macro{IfLayersAtPageStyle} commands +allow a comma-separated \PName{layer list}. \Macro{IfSomeLayerAtPageStyle} +will execute the \PName{then code} if \emph{at least one} of the layers in the +\PName{layer list} parameter is part of the layer list of \PName{page style + name}. In contrast, \Macro{IfLayersAtPageStyle} executes the \PName{then + code} only if \emph{all} the layers in the \PName{layer list} parameter are +part of the page style. If the condition is not met, the \PName{else code} +will be executed. + +With suitable nesting of these commands, you can construct complex conditions. +If you use only one \PName{layer name} in the \PName{layer list}, all three +statements are synonymous.% \EndIndexGroup \begin{Declaration} \Macro{DestroyRealLayerPageStyle}\Parameter{page style name} \end{Declaration} -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 \DescRef{maincls.cmd.thispagestyle}\,---\,is -\PName{page style name}, this will be simply reset. So the previous -\DescRef{maincls.cmd.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 +\BeginIndex{}{page style>layers}% +\BeginIndex{}{layers>page style}% +\iftrue +This statement makes a layer page style undefined. If a page-style alias or +ordinary page style is specified, the command is ignored. +\else +With this command you can remove a the definition of a layer page style. +However, this only occurs if a layer page style named \PName{page style name} +exists. If, instead, it is a page-style alias, a different (non-layer) page +style, or not a page style at all, nothing happens; the command is ignored.% +\fi + +If \PName{page style name} is the name of the current page style, the current +page style will becomes a kind of empty page style. If the page style set with +\DescRef{maincls.cmd.thispagestyle} is \PName{page style name}, it will simply +be reset. The previous \DescRef{maincls.cmd.thispagestyle} command loses its +current effect. + +Note\textnote{Attention!} that the layers of the page style are not destroyed +automatically. If you want to destroy the layers too, you can do this with: \begin{lstcode} \ForEachLayerOfPageStyle{...}{\DestroyLayer{#1}} \end{lstcode} -\emph{before} destroying the layer page style. +before destroying the layer page style itself. -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.% +The command is intended to be used within the \PName{code} argument of +\DescRef{\LabelBase.cmd.scrlayerOnAutoRemoveInterface} to remove page styles +that are defined as part of an end-user interface. See +\autoref{sec:scrlayer.enduserinterfaces} below for more information about +auto-removal code.% +\EndIndexGroup \EndIndexGroup \LoadCommonFile{headfootheight}% \section{Height of Page Head and Foot} \LoadCommonFile{pagestylemanipulation}% \section{Manipulation of Defined Page Styles} -\section{End User Interfaces} +\section{Defining and Managing Interfaces for End Users} \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}. +The \Package{scrlayer} package provides an experimental interface to define +and manage (concurrent) interfaces for end users. \iffree{In the long run, + this interface may disappear from \Package{scrlayer} and be taken over by + \Package{scrbase} instead.}{} Currently, this interface is highly +experimental% +\iffree{ and therefore \Package{scrlayer} provides these interface commands + only for the use of subpackages of \Package{scrlayer}}{}% +. Given the current state of development, you should not depend on automatic +removal of a concurrent interface to work. Instead, you should avoid using +concurrent end-user interfaces. + +This section only describes the interface commands for defining an end-user +interface. For end users themselves, it is of little interest. Rather, this +section is intended for authors of packages and classes that build on +\Package{scrlayer}. End users will find information about specific end-user +interfaces in \autoref{cha:scrlayer-scrpage}, +\autoref{cha:scrlayer-scrpage-experts}, and \autoref{cha:scrlayer-notecolumn}. \begin{Declaration} \Macro{scrlayerInitInterface}\OParameter{interface name} \end{Declaration} -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.% +The \Macro{scrlayerInitInterface} command registers a new interface named +\PName{interface name}. The \PName{interface name} must be unique. If an +interface with the same name has already been registered, an error will occur. + +This command should always appear as the first command when defining an +end-user interface and therefore is described here first. If the optional +argument\,---\,including the square brackets\,---\,is omitted, +\PValue{\Macro{@currname}.\Macro{@currext}} will be used instead. For classes +and packages, this is the file name of the class or package. But of course you +can use any other sequence of characters with a category of \emph{letter} or +\emph{other}. This is useful, for example, when a class or package defines +multiple end-user interfaces% \EndIndexGroup @@ -1361,39 +1510,47 @@ characters with category letter or other.% \Macro{scrlayerAddCsToInterface}% \OParameter{interface name}\Parameter{command sequence}\Parameter{code} \end{Declaration} -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}% -. 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. +One of the special features of \Package{scrlayer}'s end user interfaces is +that they should register all interface-dependent commands (also known as +\emph{macros}). You can do this using \Macro{scrlayerAddToInterface}. The +optional argument \PName{interface name} must be an interface name previously +registered with \DescRef{\LabelBase.cmd.scrlayerInitInterface}. An error will +occur if the interface has not been initialised. + +If\textnote{Attention!} your interface defines macros not just when the class +or package is being loaded but also at runtime, you must provide the interface +name in the optional argument even if it corresponds to the file name of the +class or package, since the values of \Macro{@currname} and \Macro{@currext} +are only valid while the class or package is being loaded. 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{autoremoveinterfaces} 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.}.% + \PName{command} consists of a backslash followed by a \PName{command + sequence} that consists of characters of the category code \emph{letter}, + or of exactly one character of the category \emph{other}, or of a character + of the category \emph{active} (without the backslash).} to be added to the +interface. If the command can be defined, this will be done. In addition, it +will set to \Macro{relax} and \PName{code} will be executed. Within +\PName{code}, you can then define \PName{command}, e.\,g., using +\Macro{newcommand}. + +But when can a command be defined? If a command is undefined or \Macro{relax}, +it can always be defined. If a command has already been defined \emph{and} +registered for another interface \emph{and} if the \KOMAScript{} option +\Option{autoremoveinterfaces} has been activated, the other interface will be +removed automatically, and the \PName{command} will be set to \Macro{relax} +and registered for the new interface specified. If a \PName{command} is +already defined but is \emph{not} part of another interface, \emph{and} if the +\KOMAScript{} option \Option{forceoverwrite} has been activated, the +\PName{command} is also set to \Macro{relax} and registered for the specified +interface. In all other cases, however, the command is not definable, in +particular if it is already defined and the \KOMAScript{} options +\Option{autoremoveinterfaces} and \Option{forceoverwrite} are deactivated. + +The \Macro{scrlayerAddCsToInterface} command is similar to +\Macro{scrlayerAddToInterface} but it expects the first argument to be not a +\PName{command} but a command sequence\footnote{A command sequence must be + fully expandable and its expansion must result in characters of the category + code \emph{letter}, \emph{other}, or \emph{space}.}.% \EndIndexGroup @@ -1401,13 +1558,17 @@ mandatory argument, but a command sequence\footnote{A command sequence may \Macro{scrlayerOnAutoRemoveInterface}% \OParameter{interface name}\Parameter{code} \end{Declaration} -Command \Macro{scrlayerOnAutoRemoveInterface} registers \PName{code} to be -executed, if the interface will be automatically removed (see -\DescRef{\LabelBase.option.autoremoveinterfaces} prior in this section). This -may be used, e.g., to automatically destroy layers or page styles (see +The \Macro{scrlayerOnAutoRemoveInterface} command registers \PName{code} to be +executed in the event that the end-user interface with the specified +\PName{interface name} is automatically removed (see +\DescRef{\LabelBase.option.autoremoveinterfaces} earlier in this section). +This can be used, for example, to automatically destroy layers or page styles +that rely on commands from the end-user interface (see \DescRef{\LabelBase.cmd.DestroyLayer}, \DescRef{\LabelBase.cmd.DestroyPageStyleAlias}, and -\DescRef{\LabelBase.cmd.DestroyRealLayerPageStyle}).% +\DescRef{\LabelBase.cmd.DestroyRealLayerPageStyle}). Regarding the default for +the optional argument, please refer to the explanation for +\DescRef{\LabelBase.cmd.scrlayerInitInterface}.% \EndIndexGroup % \EndIndexGroup |