diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/scrlayer.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/scrlayer.dtx | 1392 |
1 files changed, 35 insertions, 1357 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/scrlayer.dtx b/Master/texmf-dist/source/latex/koma-script/scrlayer.dtx index 99ff0c5771d..b28620dc017 100644 --- a/Master/texmf-dist/source/latex/koma-script/scrlayer.dtx +++ b/Master/texmf-dist/source/latex/koma-script/scrlayer.dtx @@ -1,8 +1,8 @@ -% \CheckSum{3307} +% \CheckSum{3314} % \iffalse^^A meta-comment % ====================================================================== % scrlayer.dtx -% Copyright (c) Markus Kohm, 2012-2013 +% Copyright (c) Markus Kohm, 2012-2014 % % This file is part of the LaTeX2e KOMA-Script bundle. % @@ -20,7 +20,7 @@ % This work consists of all files listed in manifest.txt. % ---------------------------------------------------------------------- % scrlayer.dtx -% Copyright (c) Markus Kohm, 2012-2013 +% Copyright (c) Markus Kohm, 2012-2014 % % Diese Datei ist Teil der LaTeX2e KOMA-Script-Sammlung. % @@ -57,18 +57,18 @@ % Right brace \} Tilde \~} % % \iffalse^^A meta-comment -%<identify>%%% From File: $Id: scrlayer.dtx 1480 2013-10-31 10:00:02Z mjk $ (identify) -%<init>%%% From File: $Id: scrlayer.dtx 1480 2013-10-31 10:00:02Z mjk $ (init) -%<options>%%% From File: $Id: scrlayer.dtx 1480 2013-10-31 10:00:02Z mjk $ (options) -%<body>%%% From File: $Id: scrlayer.dtx 1480 2013-10-31 10:00:02Z mjk $ (body) -%<final>%%% From File: $Id: scrlayer.dtx 1480 2013-10-31 10:00:02Z mjk $ (final) +%<identify>%%% From File: $Id: scrlayer.dtx 1810 2014-10-20 07:35:25Z kohm $ (identify) +%<init>%%% From File: $Id: scrlayer.dtx 1810 2014-10-20 07:35:25Z kohm $ (init) +%<options>%%% From File: $Id: scrlayer.dtx 1810 2014-10-20 07:35:25Z kohm $ (options) +%<body>%%% From File: $Id: scrlayer.dtx 1810 2014-10-20 07:35:25Z kohm $ (body) +%<final>%%% From File: $Id: scrlayer.dtx 1810 2014-10-20 07:35:25Z kohm $ (final) %<*dtx> \ifx\ProvidesFile\undefined\def\ProvidesFile#1[#2]{}\fi \begingroup - \def\filedate$#1: #2-#3-#4 #5${\gdef\filedate{#4/#3/#2}} - \filedate$Date: 2013-10-31 11:00:02 +0100 (Do, 31. Okt 2013) $ - \def\filerevision$#1: #2 ${\gdef\filerevision{v0.9.#2}} - \filerevision$Revision: 1480 $ + \def\filedate$#1: #2-#3-#4 #5${\gdef\filedate{#2/#3/#4}} + \filedate$Date: 2014-10-20 09:35:25 +0200 (Mon, 20 Oct 2014) $ + \def\filerevision$#1: #2 ${\gdef\filerevision{r#2}} + \filerevision$Revision: 1810 $ \endgroup \ProvidesFile{scrlayer.dtx}[\filedate\space\filerevision\space %</dtx> @@ -76,8 +76,7 @@ %<package>\NeedsTeXFormat{LaTeX2e}[1995/12/01] %<package>\ProvidesPackage{scrlayer}[% %<doc>\ProvidesFile{scrlayer.tex}[% -% Sometimes following will be replaced by !KOMASCRIPTVERSION: -%!SCRLAYERVERSION +%!KOMAScriptVersion %<package> package %</identify|doc> %<*dtx|identify|doc> @@ -89,7 +88,6 @@ \@@input scrkernel-version.dtx \@@input scrstrip.inc \KOMAdefVariable{COPYRIGHTFROM}{2012} - \KOMAdefVariable{SCRLAYERVERSION}{\space\space\filedate\space\filerevision}% \generate{\usepreamble\defaultpreamble \file{scrlayer.sty}{% \from{scrlayer.dtx}{package,trace,scrlayer,identify}% @@ -189,1339 +187,7 @@ % \selectlanguage{english} % % \changes{v0.0}{2012/01/01}{Start of new package} -% -%\iffalse^^A meta comment -%<*dtx|doc> -\chapter[{Defining Layers and Page Styles Using \Package{scrlayer}}]% -{Defining Layers and Page Styles Using \Package{scrlayer}% -%\footnote{This chapter has been generated from \File{scrlayer.dtx}.}% -} -\labelbase{scrlayer} - -\BeginIndex{Package}{scrlayer} - -%\fi^^A meta comment -% \begin{abstract} -\LaTeX{} itself doesn't 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. -% \end{abstract} -% -% \tableofcontents -% - -\section{State of Development Note} -\label{sec:scrlayer.draft} - -Development of this package hasn't been finished yet. 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 any user documentation. In fact there's at least only some -developers documentation needed by the main developer himself. - -%\iffalse^^A meta-comment -\EndIndex{Package}{scrlayer} -%\fi^^A meta-comment - -\section{Early or Late Selection of Options} -\label{sec:scrlayer.options} - -Package \Package{scrlayer} uses the option interface of \KOMAScript. Therefore -you may set options either within the optional argument of -\Macro{documentclass} as global options, or within the optional argument of -\Macro{usepackage} as local options, or with \Macro{KOMAoptions} or -\Macro{KOMAoption} as \KOMAScript{} option. Several of these options expect a -value. See the \KOMAScript{} manual, \File{scrguide.pdf}, for more information -about this. - - -\section{Some Generic Information} -\label{sec:scrlayer.generic} - -The package needs some generic information about the class. Class authors may -help \Package{scrlayer} setting this information. Otherwise the package tries -to detect the information itself. This works, e.g., for the standard classes -and the \KOMAScript{} classes. But it may or may not fail with other classes. - -This section describes some of the information, that class authors may -provide. Generally users need not to care about this. - -%\iffalse^^A meta-comment -\begin{Declaration} - \Macro{if@chapter}\ \PName{then code} \Macro{else}\ \PName{else code} \Macro{fi}% -\end{Declaration} -\BeginIndex{Cmd}{if@chapter}% -%\fi^^A meta-comment -% \DescribeMacro{\if@chapter} -If \Macro{if@chapter} is defined and \Macro{iftrue}, \Package{scrlayer} will -work including the chapter level, e.g., at option \Option{automark}. If it is -defined, but not \Macro{iftrue}, it only handles part, section, subsection, -sub\dots subsection, paragraph, subparagraph, sub\dots subparagraph. If the -macro isn't defined, \Package{scrlayer} searches for \Macro{chapter}. If -\Macro{chapter} is defined and not \Macro{relax}, \Package{scrlayer} will -define \Macro{if@chapter} to \Macro{iftrue}, otherwise \Macro{if@chapter} will -become \Macro{iffalse}. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{if@chapter} -%\fi^^A meta-comment - -%\iffalse^^A meta-comment -\begin{Declaration} - \Macro{if@mainmatter}\ \PName{then code} \Macro{else}\ \PName{else code} \Macro{fi}% -\end{Declaration} -\BeginIndex{Cmd}{if@mainmatter}% -%\fi^^A meta-comment -% \DescribeMacro{\if@mainmatter} -Classes like \Class{book} define \Macro{frontmatter}, \Macro{mainmatter}, and -\Macro{backmatter}. They also use \Macro{if@mainmatter} to distinguish whether -or the current matter is the main matter. Classes like \Class{report} and -\Class{article} don't have \Macro{frontmatter}, \Macro{mainmatter}, or -\Macro{backmatter} and therefore also don't have \Macro{if@mainmatter}. - -For \Package{scrlayer} it's easier not to test always for the existence of the -matter commands, but to have \Macro{if@mainmatter} even with classes like -\Class{report} and \Class{article}, simply set to \Macro{iftrue}. So if -\Macro{if@mainmatter} is not defined, it will be defined to \Macro{iftrue}. - -Some classes have \Macro{frontmatter}, \Macro{mainmatter}, or -\Macro{backmatter} but not \Macro{if@mainmatter}. In this case -\Package{scrlayer} will also define \Macro{if@mainmatter} to be \Macro{iftrue} -and it'll extend definition of \Macro{frontmatter}, \Macro{mainmatter}, and -\Macro{backmatter} to set \Macro{if@mainmatter} properly. Other matter -commands are not known, not tested, and not extended. So if there other matter -commands \Package{scrlayer} needs help of the class author to get -\Macro{if@mainmatter} set correctly. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{if@mainmatter} -%\fi^^A meta-comment - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\DeclareSectionNumberDepth} -% The command - \Macro{DeclareSectionNumberDepth}%^^A - \Parameter{level name}\Parameter{level depth} -% maps -%\iffalse^^A meta-comment -\end{Declaration} -\BeginIndex{Cmd}{DeclareSectionNumberDepth}% -With this command you may map -%\fi^^A meta-comment -the name of a heading level to a section numbering 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 levels on it's own while loading -and while \Macro{begin}\PParameter{document}. But, if it fails, you may set it -on yourself using this command. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{DeclareSectionNumberDepth} -%\fi^^A meta-comment - - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\footheight} -%\iffalse^^A meta-comment - \Length{footheight}% -\end{Declaration} -\BeginIndex{Length}{footheight}% -%\fi^^A meta-comment -While \LaTeX{} already provides \Length{headheight} to set up the height of -the page head, it doesn't provide a corresponding length for the page -footer. Nevertheless \Package{scrlayer} needs this in several cases. So if -\Length{footheight} doesn't already exist, \Package{scrlayer} will define -it and initialise it to -12345\,sp. If it's value is still this magic value -while \Macro{begin}\PParameter{document}, it will be set to -\Length{baselineskip} then. -%\iffalse^^A meta-comment -\EndIndex{Length}{footheight} -%\fi^^A meta-comment - - -\section{Declaration of Layers} -\label{sec:scrlayer.layers} - -A layer is a kind of logical 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. - -A layer has several attributes. The first attribute is, whether or not -the layer is part of the foreground or the background. Background -layers will be printed before the main contents of the page. Optically -they will be behind the main contents. Foreground layers will be -printed after the main contents of the page. Optically they will be in -front of the main contents. By default, a layer is both, a background -layer \emph{and} a foreground layer and therefore will be printed -twice. - -The second and third attributes are the horizontal and vertical position of -the layer. The forth and fifth attributes are the horizontal and vertical size -of the layer. As you can see, a layer may be smaller or larger than the -paper. - -But how are the horizontal an vertical positions measured? The answer -is the sixth attribute, the alignment. We can measure from the left edge of -the paper to the left edge of the layer, or from the left edge of the paper to -the middle of the layer, or from the left edge of the paper to the right edge -of the layer. We can measure from the top edge of the paper to the top edge of -the layer, or to the middle of the layer, or to the bottom edge of the layer. - -The seventh and eights attributes are, whether or not a layer should be -printed onto left or right pages. By default a layer will be printed at both, -left and right pages. Note, that \LaTeX{} names left pages as even pages and -right pages as odd pages and that there are no left or even pages in -single-sided mode. - -The ninth and tenth attributes are, whether or not a layer should be printed in -single-side mode or in two-side mode. By default a layer will be printed in -both, single-side mode and two-side mode. Nevertheless an even page layer will -never be printed in single-side mode and therefore isn't really a two-side -mode layer. - -The eleventh and twelveth attributes are, whether or not a layer should be -printed onto float pages or non-float pages. \LaTeX{} produces float pages for -float environment 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}). Non-float pages aren't pages -without floats, but pages, that aren't float pages. They may contain floats -inside the text, on the top of the page, or on the bottom of the page. Very -large floats may seem to be page floats, while in reality they are top floats. - -The thirteenth and last attribute is the contents of the layer. This is simply, -what should be printed, whenever the layer will be printed. - -So we have thirteen attributes yet. Below in this manual we will see additional -attributes, that may be build by these twelve attribute. Because of this, we -call these twelve attributes the primary attributes. - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\DeclareLayer} -% \DescribeMacro{\DeclareNewLayer} -% \DescribeMacro{\ProvideLayer} -% \DescribeMacro{\RedeclareLayer} -% \DescribeMacro{\ModifyLayer} -% The command: - \Macro{DeclareLayer}\OParameter{option list}\Parameter{layer name} -%\iffalse^^A meta-comment - \\\Macro{DeclareNewLayer}\OParameter{option list}\Parameter{layer name} - \\\Macro{ProvideLayer}\OParameter{option list}\Parameter{layer name} - \\\Macro{RedeclareLayer}\OParameter{option list}\Parameter{layer name} - \\\Macro{ModifyLayer}\OParameter{option list}\Parameter{layer name} -\end{Declaration} -\BeginIndex{Cmd}{DeclareLayer}% -\BeginIndex{Cmd}{DeclareNewLayer}% -\BeginIndex{Cmd}{ProvideLayer}% -\BeginIndex{Cmd}{RedeclareLayer}% -\BeginIndex{Cmd}{ModifyLayer}% -Command \Macro{DeclareLayer} -%\fi^^A meta-comment -declares or defines a layer with the name \PName{layer name}. It doesn't care -whether or not a layer with this name already exists. Argument \PName{layer - name} must be fully expandable and the expansion has to result in -letters. Some other characters will be tolerated, but only letters are -recommended. - -The \PName{option list} is a comma separated list of \PName{option}s. An -\PName{option} may be either a \PName{key} or a \PName{key} followed be an -equal sign followed by a \PName{value}. We call this a -\OptionValue{\PName{key}}{\PName{value}} option. Each \PName{key} is the -representation of a layer attribute. See \autoref{tab:scrlayer.layerkeys} for -more information about the names of the \PName{key}s and the corresponding -attributes. - -\begin{center} - \captionaboveof{table}{The \PName{key}s representing a layer attribute}% - \label{tab:scrlayer.layerkeys}% - \begin{description} - \item[\OptionValue{align}{\PName{alignment character}s} --] a description - of the wanted alignment. Each \PName{alignment character} influences - either, how the \PName{length} of \Option{hoffset} or \Option{voffset} - will be used. Several \PName{alignment character}s may be used together - (without comma or space). No macros should be used here! Valid - \PName{alignment character}s are: - \begin{description} - \item[\PValue{b} --] align the layer with its bottom edge to the given - \Option{length} of \Option{voffset} from the top edge of the paper. - \item[\PValue{c} --] align the layer with its centre to the given - \PValue{length} of \Option{hoffset} from the left edge and of - \Option{voffset} from the top edge of the paper. - \item[\PValue{l} --] align the layer with its left edge to the given - \PValue{length} of \Option{hoffset} from the left edge of the paper. - \item[\PValue{r} --] align the layer with its right edge to the given - \PValue{length} of \Option{hoffset} from the left edge of the paper. - \item[\PValue{t} --] align the layer with its top edge to the given - \Option{length} of \Option{voffset} from the top edge of the paper. - \end{description} - \item[\OptionValue{area}{%^^A - \Parameter{hoffset}\Parameter{voffset}%^^A - \Parameter{width}\Parameter{height}} --] composing option, that results - in \OptionValue{hoffset}{\PName{hoffset}}, - \OptionValue{voffset}{\PName{voffset}}, - \OptionValue{width}{\PName{width}}, \OptionValue{height}{\PName{height}}. - \item[\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. The - option doesn't expect any value. By the default the attribute is not set. - \item[\Option{bottommargin} --] composing option, that 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. - \item[\OptionValue{clone}{\PName{layer name}} --] composing option, that - 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 will be tolerated, but they are not - recommended! - \item[\OptionValue{contents}{\PName{code}} --] the \PName{code} will be - expanded whenever the layer is printed. So the \PName{code} is what you - will see. No checks for valid code will be done. So errors in \PName{code} - may result in several failures on each page, that prints the layer. - \item[\Option{evenpage} --] print the layer on even pages only, but not on - odd pages. The option doesn't expect any value. By the default the - attribute is not set. Note, that this attribute includes \Option{twoside}. - \item[\Option{floatpage} --] print the layer on float pages only, but not on - other pages. The option doesn't expect any value. By the default the - attribute is not set. - \item[\Option{foot} --] composing option, that 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}. - \item[\Option{footskip} --] composing option, that 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}). - \item[\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. The - option doesn't expect any value. By the default the attribute is not set. - \item[\Option{head} --] composing option, that 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}. - \item[\Option{headsep} --] composing option, that 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. - \item[\OptionValue{height}{\PName{length}} --] the height of the - layer. Note, that \PName{length} may either 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 expression see \cite[section~3.5]{manual:eTeX}. - \item[\OptionValue{hoffset}{\PName{length}} --] 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}. - \item[\Option{innermargin} --] composing option, that 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. - \item[\Option{leftmargin} --] composing option, that 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. - \item[\Option{nonfloatpage} --] don't print the layer on float pages, but on - other pages only. The option doesn't expect any value. By the default the - attribute is not set. - \item[\Option{oddpage} --] print the layer on odd pages only, but not on even - pages. The option doesn't expect any value. By the default the attribute - is not set. - \item[\Option{oneside} --] print the layer in single-side mode only, but not - in two-side mode. The option doesn't expect any value. By the default the - attribute is not set. - \item[\Option{outermargin} --] composing option, that 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. - \item[\Option{page} --] composing option, that 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. - \item[\Option{rightmargin} --] composing option, that 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. - \item[\Option{textarea} --] composing option, that 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. - \item[\Option{topmargin} --] composing option, that 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. - \item[\Option{twoside} --] print the layer in two-side mode only, but not in - single-side mode. The option doesn't expect any value. By the default the - attribute is not set. - \item[\OptionValue{voffset}{\PName{length}} --] 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}. - \item[\OptionValue{width}{\PName{length}} --] the width of the layer. See - \Option{height} for more information about valid content of - \PName{length}. - \end{description} -\end{center} - -The difference between \Macro{DeclareLayer} and \Macro{DeclareNewLayer} is, -that using \Macro{DeclareNewLayer} would result 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} twice by mistake. - -The difference between \Macro{DeclareLayer} and \Macro{ProvideLayer} is, that -using \Macro{ProvideLayer} would be simply ignored, if a layer with the same -\PName{layer name} already exists. So it is something like: \emph{declare the - layer only, if is hasn't been declared already.} - -The difference between \Macro{DeclareLayer} and \Macro{RedeclareLayer} is, -that using \Macro{RedeclareLayer} would result in an error, if a layer with -the same \PName{layer name} doesn't exist already. So it may not be used to -define a new layer. - -The difference between \Macro{RedeclareLayer} and \Macro{ModifyLayer} is, that -\Macro{RedeclareLayer} resets the layer to the default, before declaring it -new. \Macro{ModifyLayer} doesn't reset it, so only the attributes, set by the -\PName{option list} will be changed. -% -%\iffalse^^A meta-comment -\EndIndex{Cmd}{ModifyLayer}% -\EndIndex{Cmd}{RedeclareLayer}% -\EndIndex{Cmd}{ProvideLayer}% -\EndIndex{Cmd}{DeclareNewLayer}% -\EndIndex{Cmd}{DeclareLayer}% -%\fi^^A meta-comment - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\IfLayerExists} -% The command - \Macro{IfLayerExists}%^^A - \Parameter{string}\Parameter{then-code}\Parameter{else-code} -%\iffalse^^A meta-comment -\end{Declaration} -\BeginIndex{Cmd}{IfLayerExists}% -This command -%\fi^^A meta-comment -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, that 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 shouldn't do. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{IfLayerExists} -%\fi^^A meta-comment - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\DestroyLayer} -% The command - \Macro{DestroyLayer}%^^A - \Parameter{layer name} -%\iffalse^^A meta-comment -\end{Declaration} -\BeginIndex{Cmd}{DestroyLayer}% -This command -%\fi^^A meta-comment -sets all macros corresponding with the layer with given \PName{layer name} to -\Macro{relax}, if a layer with that name exists. After this the layer may not -be used any longer. But it doesn't 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 new using -\Macro{DeclareNewLayer} or \Macro{ProvideLayer}, but couldn't be changed using -\Macro{RedeclareLayer} or \Macro{ModifyLayer} any longer. The command is -intended to be used inside \Macro{scrlayerOnAutoRemoveInterface} to remove -layers, that have been defined by an interface using removable macros of that -interface. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{DestroyLayer} -%\fi^^A meta-comment - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% The command -% \DescribeMacro{\layercontentsmeasure} -% \DescribeOption{draft} - \Macro{layercontentsmeasure}% -%\iffalse^^A meta-comment - \\\KOption{draft}{\PName{simple switch}}% -\end{Declaration} -\BeginIndex{Option}{draft~=\PName{simple switch}} -\BeginIndex{Cmd}{layercontentsmeasure}% -The command \Macro{layercontentsmeasure} -%\fi^^A meta-comment -is internally used, if option \Option{draft} has been set, so visualise -the layers. The visualisation will be done with a centimetre ruler at the top -and left edge of the layer and an inch ruler at the bottom and right edge of -the layer. The rulers will be drawn behind the content of the layer. If you -would you, could also use it as content of a layer. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{layercontentsmeasure} -\EndIndex{Option}{draft~=\PName{simple switch}} -%\fi^^A meta-comment - - -\section{Declaration and Management of Page Styles} -\label{sec:scrlayer.pagestyles} - -Until now we know layers, but we don't 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's obvious to declare page styles to be 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 this is, that one kind of page styles \Package{scrlayer} -provides are layer page styles. 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 and you may add additional code, that will be -expanded there. - -Another kind of page styles \Package{scrlayer} provides are alias page -style. An alias page style simply consists of one other page style. In -other words, the name of an alias page style is only 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. You may not only -alias layer page styles made with \Package{scrlayer}, but all kind of -page styles. - - -% \DescribeMacro{\currentpagestyle} -%\iffalse^^A meta-comment -\begin{Declaration} - \Macro{currentpagestyle} -\end{Declaration} -\BeginIndex{Cmd}{currentpagestyle}% -%\fi^^A meta-comment -Package scrlayer patches \Macro{pagestyle} to set \Macro{currentpagestyle} to -the currently active page style. Note, that \Macro{thispagestyle} does not -change \Macro{currentpagestyle}. But if you use \Macro{thispagestyle} the -result of \Macro{currentpagestyle} may be changed while execution of the -\LaTeX{} output routine. This may be relevant only, if -\Macro{currentpagestyle} has been used protected until execution of the output -routine. - -Note, that the layer page styles described later in this section, won't need -the patch of \Macro{pagestyle} to set \Macro{currentpagestyle}. The patch has -been made for usage with other page styles. Note also, that -\Macro{currentpagestyle} is empty before the first \Macro{pagestyle} after -loading \Package{scrlayer}. So if you define an end user page style interface, -it may be useful to use an implicit \Macro{pagestyle} to set the current page -style to a default page style. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{currentpagestyle} -%\fi^^A meta-comment - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\BeforeSelectAnyPageStyle} -% \DescribeMacro{\AfterSelectAnyPageStyle} -% The command - \Macro{BeforeSelectAnyPageStyle}\Parameter{code}% -%\iffalse^^A meta-comment - \\\Macro{AfterSelectAnyPageStyle}\Parameter{code}%^^A -\end{Declaration} -\BeginIndex{Cmd}{BeforeSelectAnyPageStyle}% -\BeginIndex{Cmd}{AfterSelectAnyPageStyle}% -The command \Macro{BeforeSelectAnyPageStyle} -%\fi^^A meta-comment -adds \PName{code} to hook, that will be executed inside of \Macro{pagestyle} -just before the page style will be selected. You may use \texttt{\#1} as a -placeholder for the argument of \Macro{pagestyle}. - -The command \Macro{AfterSelectAnyPageStyle}%^^A -% \iffalse^^A meta-comment -\Parameter{code}%^^A -% \fi^^A meta-comment -\ is similar, but the \PName{code} will be executed just after the page style -has been selected and after \Macro{currentpagestyle} has been set to the name -of real page style. - -Note, that \PName{code} of both commands will be executed only, if a page -style will be selected using \Macro{pagestyle}, but not, e.\,g., if a page -style will be selected using \Macro{thispagestyle}. Note also, that you cannot -remove \PName{code} from the hook after adding it. But the \PName{code} will -be added locally, so you may use a group to limit the scope of -\PName{code}.%^^A -%\iffalse^^A meta-comment -\EndIndex{Cmd}{AfterSelectAnyPageStyle} -\EndIndex{Cmd}{BeforeSelectAnyPageStyle} -%\fi^^A meta-comment - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\DeclarePageStyleAlias} -% \DescribeMacro{\DeclareNewPageStyleAlias} -% \DescribeMacro{\ProvidePageStyleAlias} -% \DescribeMacro{\RedeclarePageStyleAlias} -% The command - \Macro{DeclarePageStyleAlias}%^^A - \Parameter{alias page style name}\Parameter{original page style name} -%\iffalse^^A meta-comment - \\\Macro{DeclareNewPageStyleAlias}% - \Parameter{alias page style name}\Parameter{original page style name} - \\\Macro{ProvidePageStyleAlias}% - \Parameter{alias page style name}\Parameter{original page style name} - \\\Macro{RedeclarePageStyleAlias}% - \Parameter{alias page style name}\Parameter{original page style name} -\end{Declaration} -\BeginIndex{Cmd}{DeclarePageStyleAlias}% -\BeginIndex{Cmd}{DeclareNewPageStyleAlias}% -\BeginIndex{Cmd}{ProvidePageStyleAlias}% -\BeginIndex{Cmd}{RedeclarePageStyleAlias}% -These Commands -%\fi^^A meta-comment -may be used to define a page style with name \PName{alias page style name}, -that is simply an alias for already existing page style with name -\PName{original page style name}. If there's already a page style \PName{alias - page style name} it will be destroyed before creating the alias using -\Macro{DeclarePageStyleAlias} or \Macro{RedeclarePageStyleAlias}. - -\Macro{DeclareNewPageStyleAlias} will throw an error message, if a page style -\PName{alias page style name} has already been defined before. It doesn't -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} hasn't been defined before. If a page style -\PName{alias page style name} already exists nothing will be done. - -\Macro{RedeclarePageStyleAlias} expects, that a page style \PName{alias page - style name} already exists. In this case it will destroy it and define the -alias newly. In the other case you'll get an error. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{RedeclarePageStyleAlias}% -\EndIndex{Cmd}{ProvidePageStyleAlias}% -\EndIndex{Cmd}{DeclareNewPageStyleAlias}% -\EndIndex{Cmd}{DeclarePageStyleAlias} -%\fi^^A meta-comment - - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\DestroyPageStyleAlias} -% The command - \Macro{DestroyPageStyleAlias}\Parameter{page style name}% -%\iffalse^^A meta-comment -\end{Declaration} -\BeginIndex{Cmd}{DestroyPageStyleAlias}% -This command -%\fi^^A meta-comment -makes the page style with given \PName{page style name} \LaTeX-undefined, if -it is an alias for another page style. After this, the page style may be -defined newly with, e.g., \Macro{DeclareNewAliasPageStyle} or -\Macro{ProvideAliasPageStyle}. The command is intended to be used inside of -\Macro{scrlayerOnAutoRemoveInterface} to remove page styles, that have been -declared by an interface and uses removable macros of that interface. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{DestroyPageStyleAlias} -%\fi^^A meta-comment - - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\GetRealPageStyle} -% The command - \Macro{GetRealPageStyle}\Parameter{page style name}% -%\iffalse^^A meta-comment -\end{Declaration} -\BeginIndex{Cmd}{GetRealPageStyle}% -The command -%\fi^^A meta-comment -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}. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{GetRealPageStyle} -%\fi^^A meta-comment - - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\DeclarePageStyleByLayers} -% \DescribeMacro{\DeclareNewPageStyleByLayers} -% \DescribeMacro{\ProvidePageStyleByLayers} -% \DescribeMacro{\RedeclarePageStyleByLayers} -% The command - \Macro{DeclarePageStyleByLayers}%^^A - \OParameter{option list}\Parameter{page style name}\Parameter{layer list}% -%\iffalse^^A meta-comment - \\\Macro{DeclareNewPageStyleByLayers}%^^A - \OParameter{option list}\Parameter{page style name}\Parameter{layer list}% - \\\Macro{ProvidePageStyleByLayers}%^^A - \OParameter{option list}\Parameter{page style name}\Parameter{layer list}% - \\\Macro{RedeclarePageStyleByLayers}%^^A - \OParameter{option list}\Parameter{page style name}\Parameter{layer list}% -\end{Declaration} -\BeginIndex{Cmd}{DeclarePageStyleByLayers}% -\BeginIndex{Cmd}{DeclareNewPageStyleByLayers}% -\BeginIndex{Cmd}{ProvidePageStyleByLayers}% -\BeginIndex{Cmd}{RedeclarePageStyleByLayers}% -These commands -%\fi^^A meta-comment -declares a page style with \PName{page style name}. The page style will -consist of the layers given in \PName{layer list}, a comma separated list of -layer names. Note, that 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 will be tolerated, but nevertheless, they -aren't recommended. - -The \PName{option list} is a comma separated list of -\OptionValue{\PName{key}}{\PName{value}} options. These options may be used to -set additional features. Currently they are used to set the code, that should -be expanded or executed at several \emph{hooks}. See the introduction to this -section for more general information about \emph{hooks}. See -\autoref{tab:scrlayer.pagestyle.hooks} for more information about the hooks -and their purpose. - -\begin{center} - \parbox{\textwidth}{% - \captionaboveof{table}{The \emph{hook} options for page styles (in order of - execution)}\nobreak\vskip4\baselineskip}\vskip-5\baselineskip - \label{tab:scrlayer.pagestyle.hooks} - \begin{description} - \item[\texttt{\KOption{onselect}\PName{code}}:] Execute \PName{code} - whenever the page style will be selected using, e.g., - \Macro{pagestyle}. Note, that \Macro{thispagestyle} doesn't select the - page style immediately, but asynchronously inside \LaTeX's output routine. - \item[\texttt{\KOption{oninit}\PName{code}}:] Execute \PName{code} whenever - the output of the layers of a page style will be initialised. Note, that - this will be done twice for every page: once for background layers and - once for foreground layers. - \item[\texttt{\KOption{ononeside}\PName{code}}:] Execute \PName{code} - whenever the output of the layers of a page style in single-side mode will - initialised. Note, that this will be done twice for every page: once for - background layers and once for foreground layers. - \item[\texttt{\KOption{ontwoside}\PName{code}}:] Execute \PName{code} - whenever the output of the layers of a page style in two-side mode will - initialised. Note, that this will be done twice for every page: once for - background layers and once for foreground layers. - \item[\texttt{\KOption{onoddpage}\PName{code}}:] Execute \PName{code} - whenever the output of the layers of a page style on an odd page will - initialised. Note, that this will be done twice for every page: once for - background layers and once for foreground layers. Note also, that in - single-side mode all pages are odd pages, not only pages with odd page - numbers. - \item[\texttt{\KOption{onevenpage}\PName{code}}:] Execute \PName{code} - whenever the output of the layers of a page style on an even page will - initialised. Note, that this will be done twice for every page: once for - background layers and once for foreground layers. Note also, that there - aren't even pages in single-side mode, but all pages are odd pages, not - only pages with odd page numbers. - \item[\texttt{\KOption{onfloatpage}\PName{code}}:] Execute \PName{code} - whenever the output of the layers of a page style on a float page will - initialised. Note, that this will be done twice for every page: once for - background layers and once for foreground layers. Note also, that float - pages are only those pages with p-placed floating objects. - \item[\texttt{\KOption{onnonfloatpage}\PName{code}}:] Execute \PName{code} - whenever the output of the layers of a page style on a non-float page will - initialised. Note, that this will be done twice for every page: once for - background layers and once for foreground layers. Note also, that - non-float pages are all pages, that aren't float-pages. Those pages may - have t-placed, h-placed, b-placed, or no floating objects. - \item[\texttt{\KOption{onbackground}\PName{code}}:] Execute \PName{code} - whenever the output of the layers of a page style in the background of a - page will initialised. Note, that this will be done once for every page. - \item[\texttt{\KOption{onforeground}\PName{code}}:] Execute \PName{code} - whenever the output of the layers of a page style in the foreground of a - page will initialised. Note, that this will be done once for every page. - \end{description} -\end{center} - -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, that declaring a page style, that is an alias of another -page style (see \Macro{DeclareAliasPageStyle} prior in this section), will not -re-declare the page style itself, but it's real page style (see -\Macro{GetRealPageStyle} prior in this section). - -The difference of \Macro{DeclarePageStyleByLayers} and -\Macro{ProvidePageStyleByLayers} is, that \Macro{ProvidePageStyleByLayers} -will simply do nothing, if there's already a page style with name \PName{page - style name}. In difference to \Macro{DeclareNewPageStyleByLayers} it won't -raise an error in this case. - -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 would occur. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{RedeclarePageStyleByLayers}% -\EndIndex{Cmd}{ProvidePageStyleByLayers}% -\EndIndex{Cmd}{DeclareNewPageStyleByLayers}% -\EndIndex{Cmd}{DeclarePageStyleByLayers}% -%\fi^^A meta-comment - - -%\iffalse^^A meta-comment -\begin{Declaration} - \Pagestyle{@everystyle@}\\ - \Pagestyle{empty} -\end{Declaration} -\BeginIndex{Pagestyle}{@everysel@}% -\BeginIndex{Pagestyle}{empty}% -%\fi^^A meta-comment -There are two somehow special, default layer page styles. The first one is -\Pagestyle{@everystyle@}. This page style shouldn't be used normally, 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 would be similar to adding this layer to all -other layer page styles even the empty one. There's one difference: Layer -referencing commands of the page style interface like -\Macro{ForEachLayerOfPageStyle}, \Macro{AddLayerToPageStyleBeforeLayer}, or -\Macro{AddLayerToPageStyleAfterLayer} ignore the layers of -\Pagestyle{@everystyle@} if they are used for another layer page style. - -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{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@}. -%\iffalse^^A meta-comment -\EndIndex{Pagestyle}{empty}% -\EndIndex{Pagestyle}{@everysel@}% -%\fi^^A meta-comment - - -% \iffalse^^A meta-comment -\begin{Declaration} -% \fi^^A meta-comment -% \DescribeOption{onpsselect}% -% \DescribeOption{onpsinit}% -% \DeleteShortVerb{\|}% -% \DescribeOption{onps(one|two)side}% -% \DescribeOption{onps(odd|even)page}% -% \DescribeOption{onps(float|nonfloat)page}% -% \DescribeOption{onps(back|fore)ground}% -% \MakeShortVerb{\|}% -% \iffalse^^A meta-comment - \KOption{onpsselect}\PValue{code}\\ - \KOption{onpsinit}\PValue{code}\\ - \KOption{onpsoneside}\PValue{code}\\ - \KOption{onpstwoside}\PValue{code}\\ - \KOption{onpsoddpage}\PValue{code}\\ - \KOption{onpsevenpage}\PValue{code}\\ - \KOption{onpsfloatpage}\PValue{code}\\ - \KOption{onpsnonfloatpage}\PValue{code}\\ - \KOption{onpsbackground}\PValue{code}\\ - \KOption{onpsforeground}\PValue{code} -\end{Declaration} -\BeginIndex{Option}{onpsselect}% -\BeginIndex{Option}{onpsinit}% -\BeginIndex{Option}{onpsoneside}% -\BeginIndex{Option}{onpstwoside}% -\BeginIndex{Option}{onpsoddpage}% -\BeginIndex{Option}{onpsevenpage}% -\BeginIndex{Option}{onpsfloatpage}% -\BeginIndex{Option}{onpsnonfloatpage}% -\BeginIndex{Option}{onpsbackground}% -\BeginIndex{Option}{onpsforeground}% -% \fi^^A meta-comment -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}. This default will be extended by every usage of the page style -options at the \PName{option list}. You may remove the default, using -\Macro{ModifyLayerPageStyleOptions} described later in this section. -% \iffalse^^A meta-comment -\EndIndex{Option}{onpsforeground}% -\EndIndex{Option}{onpsbackground}% -\EndIndex{Option}{onpsnonfloatpage}% -\EndIndex{Option}{onpsfloatpage}% -\EndIndex{Option}{onpsevenpage}% -\EndIndex{Option}{onpsoddpage}% -\EndIndex{Option}{onpstwoside}% -\EndIndex{Option}{onpsoneside}% -\EndIndex{Option}{onpsinit}% -\EndIndex{Option}{onpsselect}% -% \fi^^A meta-comment - - -%\iffalse^^A meta-comment -\begin{Declaration} - \KOption{deactivatepagestylelayers}\PName{simple switch}\\ -%\fi^^A meta-comment -% \DescribeMacro{\ForEachLayerOfPageStyle} -% The command - \Macro{ForEachLayerOfPageStyle}%^^A - \Parameter{page style name}\Parameter{code} -%\iffalse^^A meta-comment -\end{Declaration} -\BeginIndex{Cmd}{ForEachLayerOfPageStyle}% -This command -%\fi^^A meta-comment -may be used to process \PName{code} for every layer, that is a member of the -layers list of a page style with given \PName{page style name}. Inside of -\PName{code} the place holder \PValue{\#1} may be used for the name of the -current layer. -%\iffalse^^A meta-comment -\begin{Example} -%\fi^^A meta-comment -% \par -If you want to output the names of all layers of page style -\PValue{scrheadings}, you may us: -\begin{lstcode} - \let\commaatlist\empty - \ForEachLayerOfPageStyle{scrheadings}{% - \commaatlist#1\gdef\commaatlist{, }} -\end{lstcode} -%\iffalse^^A meta-comment -\end{Example} -%\fi^^A meta-comment -\KOMAScript{} option \Option{deactivatepagestylelayers} may be used to -deactivate all layers within \Macro{ForEachLayerOfPageStyle}. If the options -has been switched on, \Macro{ForEachLayerOfPageStyle} will not longer process -\PName{code} for any layer. Several other commands of \Package{scrlayer} also -uses \Macro{ForEachLayerOfPageStyle} internally. So these also won't process -any layer. You may use this options, e.g., to hide all layers. - -Please note, that \PName{code} will be executed inside a group! -% \iffalse^^A meta-comment -\EndIndex{Cmd}{ForEachLayerOfPageStyle} -%\fi^^A meta-comment - - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\AddLayersToPageStyle} -% \DescribeMacro{\AddLayersAtBeginOfPageStyle} -% \DescribeMacro{\AddLayersAtEndOfageStyle} -% \DescribeMacro{\RemoveLayersFromPageStyle} -% The command - \Macro{AddLayersToPageStyle}%^^A - \Parameter{page style name}\Parameter{layer list}% -%\iffalse^^A meta-comment - \\\Macro{AddLayersAtBeginOfPageStyle}%^^A - \Parameter{page style name}\Parameter{layer list}% - \\\Macro{AddLayersAtEndOfPageStyle}%^^A - \Parameter{page style name}\Parameter{layer list}% - \\\Macro{RemoveLayersFromPageStyle}%^^A - \Parameter{page style name}\Parameter{layer list}% -\end{Declaration} -\BeginIndex{Cmd}{AddLayersToPageStyle}% -\BeginIndex{Cmd}{AddLayersAtBeginOfPageStyle}% -\BeginIndex{Cmd}{AddLayersAtEndOfPageStyle}% -\BeginIndex{Cmd}{RemoveLayersFromPageStyle}% -The first command -%\fi^^A meta-comment -adds 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}. \Macro{AddLayersAtEndOfPageStyle} is an alias for the same. If you -want to add the new layers at the begin of the layer list of a layer page -style you may use \Macro{AddLayersAtBeginOfPageStyle}. Note, that 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, that layers, that are part of \PName{layer list} but not part of -the page style's layer list, will be ignored. - -Adding or removing layers from a page style, that is not a layer page style or -an alias of a layer page style would be an error and result in an error -message.% -%\iffalse^^A meta-comment -\EndIndex{Cmd}{RemoveLayersFromPageStyle}% -\EndIndex{Cmd}{AddLayersAtEndOfPageStyle}% -\EndIndex{Cmd}{AddLayersAtBeginOfPageStyle}% -\EndIndex{Cmd}{AddLayersToPageStyle} -%\fi^^A meta-comment - - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\AddLayersToPageStyleBeforeLayer} -% The commands - \Macro{AddLayersToPageStyleBeforeLayer}%^^A - \Parameter{page style name}\Parameter{layer list}%^^A - \Parameter{reference layer name} -% and - \\\Macro{AddLayersToPageStyleAfterLayer}%^^A - \Parameter{page style name}\Parameter{layer list}%^^A - \Parameter{reference layer name} -%\iffalse^^A meta-comment -\end{Declaration} -\BeginIndex{Cmd}{AddLayersToPageStyleBeforeLayer}% -\BeginIndex{Cmd}{AddLayersToPageStyleAfterLayer}% -These commands -%\fi^^A meta-comment -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, that -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. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{AddLayersToPageStyleAfterLayer} -\EndIndex{Cmd}{AddLayersToPageStyleBeforeLayer} -%\fi^^A meta-comment - - -% \DescribeMacro{\UnifyLayersAtPageStyle} -%\iffalse^^A meta-comment -\begin{Declaration} - \Macro{UnifyLayersAtPageStyle}\Parameter{page style name} -\end{Declaration} -\BeginIndex{Cmd}{UnifyLayersAtPageStyle}% -%\fi^^A meta-comment -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 doesn't make sense to have one layer several -times at the layer list of a layer page style. So you may use -\Macro{UnifyLayersAtPageStyle}%^^A -%\Parameter{page style name}^^A -\ to remove all dupes of layers from the layer list of a layer page -style. Note that 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}. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{UnifyLayersAtPageStyle} -%\fi^^A meta-comment - - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\ModifyLayerPageStyleOptions} -% \DescribeMacro{\AddToLayerPageStyleOptions} -% The command - \Macro{ModifyLayerPageStyleOptions}%^^A - \Parameter{page style name}\Parameter{option list} -%\iffalse^^A meta-comment - \\\Macro{AddToLayerPageStyleOptions}%^^A - \Parameter{page style name}\Parameter{option list} -\end{Declaration} -\BeginIndex{Cmd}{ModifyLayerPageStyleOptions}% -\BeginIndex{Cmd}{AddToLayerPageStyleOptions}% -Command \Macro{ModifyLayerPageStyleOptions} -%\fi^^A meta-comment -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, -that 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, that -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}. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{AddToLayerPageStyleOptions} -\EndIndex{Cmd}{ModifyLayerPageStyleOptions} -%\fi^^A meta-comment - - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\IfLayerPageStyleExists} -% \DescribeMacro{\IfRealLayerPageStyleExists} -% The command - \Macro{IfLayerPageStyleExists}%^^A - \Parameter{page style name}\Parameter{then code}\Parameter{else code}% -%\iffalse^^A meta-comment - \\\Macro{IfRealLayerPageStyleExists}%^^A - \Parameter{page style name}\Parameter{then code}\Parameter{else code}% -\end{Declaration} -\BeginIndex{Cmd}{IfLayerPageStyleExists}% -\BeginIndex{Cmd}{IfRealLayerPageStyleExists}% -Command \Macro{IfLayerPageStyleExists} -%\fi^^A meta-comment -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 doesn't 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. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{IfRealLayerPageStyleExists} -\EndIndex{Cmd}{IfLayerPageStyleExists} -%\fi^^A meta-comment - - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\IfLayerAtPageStyle} -% \DescribeMacro{\IfSomeLayersAtPageStyle} -% \DescribeMacro{\IfLayersAtPageStyle} -% The command - \Macro{IfLayerAtPageStyle}% - \Parameter{page style name}\Parameter{layer name}%^^A - \Parameter{then code}\Parameter{else code}% -%\iffalse^^A meta-comment - \\\Macro{IfSomeLayerAtPageStyle}% - \Parameter{page style name}\Parameter{layer list}%^^A - \Parameter{then code}\Parameter{else code}% - \\\Macro{IfLayerAtPageStyle}% - \Parameter{page style name}\Parameter{layer list}%^^A - \Parameter{then code}\Parameter{else code}% -\end{Declaration} -\BeginIndex{Cmd}{IfLayerAtPageStyle}% -\BeginIndex{Cmd}{IfSomeLayersAtPageStyle}% -\BeginIndex{Cmd}{IfLayersAtPageStyle}% -Command \PName{IfLayerAtPageStyle} -%\fi^^A meta-comment -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}. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{IfLayersAtPageStyle} -\EndIndex{Cmd}{IfSomeLayersAtPageStyle} -\EndIndex{Cmd}{IfLayerAtPageStyle} -%\fi^^A meta-comment - - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\DestroyRealLayerPageStyle} -% The command - \Macro{DestroyRealLayerPageStyle}\Parameter{page style name} -%\iffalse^^A meta-comment -\end{Declaration} -\BeginIndex{Cmd}{DestroyRealLayerPageStyle}% -Command \Macro{DestroyRealLayerPageStyle} -%\fi^^A meta-comment -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 isn't a page style. If -\PName{page style name} is the name of the current page style the current page -style will become a kind of empty page style. If the special page -style\,---\,this may be set using \Macro{thispagestyle}\,---\,is \PName{page - style name}, this will be simply reset. - -Note, that the layers of the page style won't be destroyed automatically. If -you want to destroy the layers too, you may use -\begin{lstcode} - \ForEachLayerOfPageStyle{...}{\DestroyLayer{#1}} -\end{lstcode} -\emph{before} destroying the layer page style. - -The command is intended to be used inside the auto-remove code of an interface -See following \ref{sec:scrlayer.enduserinterfaces} for more information about -auto-remove code. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{DestroyRealLayerPageStyle} -%\fi^^A meta-comment - - -\section{End User Interfaces} -\label{sec:scrlayer.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}, but currently package -\Package{scrlayer} provides its own interface definition commands. - -This section only describes the interface commands for defining end user -interfaces. This is not of interest 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{sec:scrlayer.scrpage}. - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\scrlayerInitInterface} -% The command - \Macro{scrlayerInitInterface}\OParameter{interface name} -%\iffalse^^A meta-comment -\end{Declaration} -\BeginIndex{Cmd}{scrlayerInitInterface}% -Command \Macro{scrlayerInitInterface} -%\fi^^A meta-comment -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. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{scrlayerInitInterface} -%\fi^^A meta-comment - - -%\iffalse^^A meta-comment -\begin{Declaration} - \KOption{forceoverwrite}\PName{simple switch}\\ - \KOption{autoremoveinterfaces}\PName{simple switch}\\ -%\fi^^A meta-comment -% \DescribeMacro{\scrlayerAddToInterface} -% \DescribeMacro{\scrlayerAddCsToInterface} -%\iffalse^^A meta-comment - \Macro{scrlayerAddToInterface}% - \OParameter{interface name}\Parameter{command}\Parameter{code}\\ - \Macro{scrlayerAddCsToInterface}% - \OParameter{interface name}\Parameter{command sequence}\Parameter{code} -\end{Declaration} -\BeginIndex{Option}{forceoverwrite}% -\BeginIndex{Option}{autoremoveinterfaces}% -\BeginIndex{Cmd}{scrlayerAddToInterface}% -\BeginIndex{Cmd}{scrlayerAddCsToInterface}% -%\fi^^A meta-comment -One of the special features of end user interfaces is, that they should -register all interface dependent commands (also known as \emph{macros}). You -may do this using \Macro{scrlayerAddToInterface}%^^A -%\OParameter{interface name}\Parameter{command}\Parameter{code}%^^A -. If your interface generates macros not only at load time but also at run -time or if the interface name shouldn't 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 hasn't been initialised -before. - -The first mandatory argument is the \PName{command}\footnote{The - \PName{command} consists in the backslash followed by a \PName{command - sequence} consisting in characters with category code letter or one other - character, or \PName{command} consists in one active character (without - backslash).}, that should be added to the interface. If the command can be -added to the interface, it will be added to the interface, will be set to -\Macro{relax} and \PName{code} will be executed. You can use, e.g., -\Macro{newcommand}\PName{command} inside of \PName{code} to define -\PName{command}. - -But when can a command be defined? If a command is undefined or \Macro{relax} -it can be defined. If a command has already been defined and registered for -another interface \emph{and} if \KOMAScript{} option -\Option{autoremoveinterface} has been switched on, the other interface will be -removed automatically and the new command will be set to \Macro{relax} and -will be registered for the given interface. If a command -has already been defined but isn't 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 doesn't 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.}. -%\iffalse^^A meta-comment -\EndIndex{Cmd}{scrlayerAddCsToInterface}% -\EndIndex{Cmd}{scrlayerAddToInterface} -\EndIndex{Option}{autoremoveinterfaces}% -\EndIndex{Option}{forceoverwrite}% -%\fi^^A meta-comment - - -%\iffalse^^A meta-comment -\begin{Declaration} -%\fi^^A meta-comment -% \DescribeMacro{\scrlayerOnAutoRemoveInterface} -% The command - \Macro{scrlayerOnAutoRemoveInterface}%^^A - \OParameter{interface name}\Parameter{code} -%\iffalse^^A meta-comment -\end{Declaration} -\BeginIndex{Cmd}{scrlayerOnAutoRemoveInterface}% -Command \Macro{scrlayerOnAutoRemoveInterface} -%\fi^^A meta-comment -registers \PName{code} to be executed, if the interface will be automatically -removed (see \Option{autoremoveinterfaces} prior in this section). This may be -used, e.g., to automatically destroy layers or page styles (see -\Macro{DestroyLayer}, \Macro{DestroyAliasPageStyle}, and -\Macro{DestroyRealLayerPageStyle}). -%\iffalse^^A meta-comment -\EndIndex{Cmd}{scrlayerOnAutoRemoveInterface} -%\fi^^A meta-comment - - -%\iffalse -%</dtx|doc> -%\fi +% \changes{v0.9}{2014/07/25}{User documentation removed} % % \StopEventually{} % @@ -1529,8 +195,6 @@ used, e.g., to automatically destroy layers or page styles (see % \section{Implementation of \Package{scrlayer}} % % This section if for developers only. -% Users may continue at \autoref{sec:scrlayer.scrpage} at -% page~\pageref{sec:scrlayer.scrpage}. % % \iffalse %<*package> @@ -2412,9 +1076,10 @@ used, e.g., to automatically destroy layers or page styles (see % \end{macrocode} % \item[\texttt{contents=\meta{output}}:] whatever should be printed by the % layer. +% \changes{v3.14}{2014/10/20}{\texttt{contents} is \cs{long}}^^A % \begin{macrocode} \DefineFamilyKey[.definelayer]{KOMAarg}{contents}{% - \@namedef{scr@l@\scr@current@layer @contents}{#1}% + \long\@namedef{scr@l@\scr@current@layer @contents}{#1}% \FamilyKeyStateProcessed } % \end{macrocode} @@ -2795,8 +1460,11 @@ used, e.g., to automatically destroy layers or page styles (see % \end{macro}^^A \scrlayer@clone@attribute % \end{description} % +% \changes{v0.9}{2014/08/31}{missing reset of \cs{scr@current@layer} +% added}%^^A +% \changes{v3.14}{2014/10/20}{\cs{long}}^^A % \begin{macrocode} -\newcommand*{\DeclareLayer}[2][]{% +\newcommand{\DeclareLayer}[2][]{% \def\scr@current@layer{#2}% \@namedef{scr@l@#2@x}{\z@}% \@namedef{scr@l@#2@y}{\z@}% @@ -2821,6 +1489,7 @@ used, e.g., to automatically destroy layers or page styles (see \expandafter\newif\csname if@scr@l@#2@nonfloatpage\endcsname \csname @scr@l@#2@nonfloatpagetrue\endcsname \FamilyExecuteOptions[.definelayer]{KOMAarg}{#1}% + \let\scr@current@layer\@empty } % \end{macrocode} % \begin{macro}{\scr@current@layer} @@ -2856,9 +1525,15 @@ used, e.g., to automatically destroy layers or page styles (see % \end{macro}%^^A \IfLayerExists % % \begin{macro}{\DeclareNewLayer} +% \changes{v3.14}{2014/10/20}{\cs{long}}^^A % \begin{macro}{\ProvideLayer} +% \changes{v3.14}{2014/10/20}{\cs{long}}^^A % \begin{macro}{\RedeclareLayer} +% \changes{v3.14}{2014/10/20}{\cs{long}}^^A % \begin{macro}{\ModifyLayer} +% \changes{v3.14}{2014/10/20}{\cs{long}}^^A +% \changes{v0.9}{2014/08/31}{missing definition and reset of +% \cs{scr@current@layer} added}%^^A % There are also two commands for declaration of layers, that haven't been % declared before, with or without error message for already declared layers, % and two commands for changing already declared layers, first one beginning @@ -2866,7 +1541,7 @@ used, e.g., to automatically destroy layers or page styles (see % be changed. % \begin{macrocode} %<*package&body> -\newcommand*{\DeclareNewLayer}[2][]{% +\newcommand{\DeclareNewLayer}[2][]{% \IfLayerExists{#2}{% \PackageError{scrlayer}{layer `#2' already defined}{% You may declare only layer, that haven't been declared previously @@ -2877,7 +1552,7 @@ used, e.g., to automatically destroy layers or page styles (see If you'll continue, declaration will be ignored.}% }{\DeclareLayer[{#1}]{#2}}% } -\newcommand*{\ProvideLayer}[2][]{% +\newcommand{\ProvideLayer}[2][]{% \IfLayerExists{#2}{% %<*trace> \PackageInfo{scrlayer}{\string\ProvideLayer{#2} ignored,\MessageBreak @@ -2885,7 +1560,7 @@ used, e.g., to automatically destroy layers or page styles (see %</trace> }{\DeclareNewLayer[{#1}]{#2}}% } -\newcommand*{\RedeclareLayer}[2][]{% +\newcommand{\RedeclareLayer}[2][]{% \IfLayerExists{#2}{}{% \PackageError{scrlayer}{layer `#2' not yet defined}{% You may declare only already declared layers using @@ -2896,9 +1571,11 @@ used, e.g., to automatically destroy layers or page styles (see }% \DeclareLayer[{#1}]{#2}% } -\newcommand*{\ModifyLayer}[2][]{% +\newcommand{\ModifyLayer}[2][]{% \IfLayerExists{#2}{% + \def\scr@current@layer{#2}% \FamilyExecuteOptions[.definelayer]{KOMAarg}{#1}% + \let\scr@current@layer\@empty }{% \PackageError{scrlayer}{layer `#2' not yet defined}{% You may modify only already declared layers using @@ -4018,12 +2695,13 @@ used, e.g., to automatically destroy layers or page styles (see } % \end{macrocode} % \begin{macro}{\remove@layer@from@page@style} +% \changes{v0.9}{2014/07/25}{cleaning of layer list must be global} % Helper macro to remove exactly one layer (arg 1) from a page style (arg 2). % \begin{macrocode} \newcommand*{\remove@layer@from@page@style}[2]{% \begingroup \expandafter\let\expandafter\reserved@a\csname @ps@#2@layers\endcsname - \@namedef{@ps@#2@layers}{}% + \expandafter\global\expandafter\let\csname @ps@#2@layers\endcsname\@empty \def\@elt##1{% \ifstr{#1}{##1}{}{% \expandafter\@cons\csname @ps@#2@layers\endcsname{{##1}}% |