diff options
author | Karl Berry <karl@freefriends.org> | 2015-09-30 21:16:51 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2015-09-30 21:16:51 +0000 |
commit | 21923df0aa733309adbfcc3169c7ffc0e0ab8b1c (patch) | |
tree | f81789ab91c6edd088e331eac5983464e7f21c6b /Master/texmf-dist/source/latex/koma-script/doc/english/scrlayer.tex | |
parent | 197071e9b5aaa66a56c464229f4a9fc81c0c8b1f (diff) |
koma-script (30sep15)
git-svn-id: svn://tug.org/texlive/trunk@38504 c570f23f-e606-0410-a88d-b1316a301751
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 | 266 |
1 files changed, 200 insertions, 66 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 e81a0a8a327..b1c0b73e789 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 @@ -46,12 +46,12 @@ % ============================================================================ \KOMAProvidesFile{scrlayer.tex} - [$Date: 2015-05-19 11:08:32 +0200 (Tue, 19 May 2015) $ + [$Date: 2015-09-15 11:35:31 +0200 (Tue, 15 Sep 2015) $ KOMA-Script guide (chapter:scrlayer)] \translator{Markus Kohm} -% Date of the translated file: 2015-05-19 +% Date of the translated file: 2015-09-15 \chapter[{Defining Layers and Page Styles Using \Package{scrlayer}}]% {Defining Layers and Page Styles Using \Package{scrlayer}% @@ -190,55 +190,68 @@ contents, the foreground layer stack is above the normal page contents. So the normal contents is a kind of a separating layer between the background layer stack and the foreground layer stack. -A layer has several attributes. The first attribute states, whether or not the -layer is part of the foreground or the background. During page building -background layers will be printed first, followed by the main contents and the -foreground layers. Therefore, in the output the background layers show up -behind the main contents and the foreground layers in front of the main -contents. By default, a layer is both, a background layer \emph{and} a -foreground layer and therefore will be printed twice. - -The horizontal position of the layer is set by the second attribute, the -vertical position by the third. The forth and fifth attributes determine the -horizontal and vertical size of the layer. As you can see, a layer may be -smaller or larger than the paper. - -But having two numerical values of the second and third attribute does not -directly give us the position of the layer on the page. For each dimension we -need two reference points, one on the page and one on the layer. The -numerical value than states the distance between these reference. -Reference points in layouts are also known as alignment and are set by the -sixth attribute. - -The seventh attribute states, whether or not a layer should be -printed onto left or right pages. By default a layer will be printed on both, -left and right pages. Note, that \LaTeX{} names left pages as even pages and -right pages as odd pages and that there are no left or even pages in -single-sided mode. - -The eighth attribute states, whether or not a layer should be printed in -single-side mode or in two-side mode. By default a layer will be printed in -both, single-side mode and two-side mode. Nevertheless, an even page layer will -never be printed in single-side mode and therefore is not really a two-side -mode layer. - -The ninth attribute is, whether or not a layer should be printed onto float -pages or non-float pages. \LaTeX{} produces float pages for float environments -like tables or figures, if they are allowed to be printed on a page without -normal page contents (see option \PValue{p} for \Environment{figure} or -\Environment{table}). So from some point of view a float page is a page, that -may itself flow. Non-float pages are not pages without floats, but pages, that -are not float pages. They may contain floats inside the text, on the top of -the page, or on the bottom of the page. Very large floats may seem to be page -floats, while in reality they are top floats. - -The tenth and last attribute is the contents of the layer. This is simply, -what should be printed, whenever the layer will be printed. - -So we have ten attributes yet. Below in this manual we will describe -additional attributes. However, they are just defined for convenience and can -be expressed by a combination of the ten attributes stated above. We call -these ten attributes the primary attributes. +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. + \begin{Declaration} \Macro{DeclareLayer}\OParameter{option list}\Parameter{layer name}\\ @@ -258,15 +271,13 @@ are tolerated, but are not recommended. Command \Macro{DeclareLayer} does not care whether or not a layer with the given \PName{layer name} already exists. It will under all circumstances -define the layer with the attribute defined by the \PName{option list}. -An -\PName{option} can be either a key or a key followed by an -equal sign followed by a value. Several options may be concatenated to -a \PName{option list} and have to be separated by comma. If you'd like to have -a comma or a white space inside the value of an option, you should put the -value inside curly brackets. See \autoref{tab:scrlayer.layerkeys} for -more information on keys, values, and the corresponding -attributes. +define the layer with the attribute defined by the \PName{option list}. An +\PName{option} can be either a key or a key followed by an equal sign followed +by a value. Several options may be concatenated to a \PName{option list} and +have to be separated by comma. If you'd like to have a comma or a white space +inside the value of an option, you should put the value inside curly +brackets. See \autoref{tab:scrlayer.layerkeys} for more information on keys, +values, and the corresponding attributes. In contrast to \Macro{DeclareLayer} using \Macro{DeclareNewLayer} results in an error, if a layer with the same \PName{layer name} already exists. So you @@ -485,6 +496,23 @@ there has not been a layer with \PName{layer name} defined before. text area and vertically span the whole paper from the top edge to the bottom edge.% }% + \entry{\ChangedAt{v3.19}{\Package{scrlayer}}% + \KOption{mode}\PName{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} + 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!% + }% \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 @@ -576,27 +604,133 @@ there has not been a layer with \PName{layer name} defined before. \EndIndex{Cmd}{DeclareLayer}% \begin{Declaration} + \Macro{layerhalign}\\ + \Macro{layervalign}\\ \Macro{layerxoffset}\\ \Macro{layeryoffset}\\ \Macro{layerwidth}\\ \Macro{layerheight}% \end{Declaration} +\BeginIndex{Cmd}{layervalign}% +\BeginIndex{Cmd}{layerhalign}% \BeginIndex{Cmd}{layerxoffset}% \BeginIndex{Cmd}{layeryoffset}% \BeginIndex{Cmd}{layerwidth}% \BeginIndex{Cmd}{layerheight}% These commands are valid during output of the layer's contents only. So they can only be used inside the \PName{code} of option \Option{contents} of the -previously described commands. In this case they give the effective position -and dimension of the layer, that will be used for the output. However, the -effective dimension of the layer's contents may differ, i.\,e., if the -contents are oversized or do not fill the layer completely. Redefinition of -the commands to change the stored values is strictly forbidden and would -result in unpredictable issues.% +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. + +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.% \EndIndex{Cmd}{layerheight}% \EndIndex{Cmd}{layerwidth}% \EndIndex{Cmd}{layeryoffset}% \EndIndex{Cmd}{layerxoffset}% +\EndIndex{Cmd}{layerhalign}% +\EndIndex{Cmd}{layervalign}% + + +\begin{Declaration} + \Macro{LenToUnit}\Parameter{length} +\end{Declaration} +\BeginIndex{Cmd}{LenToUnit}% +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 +\Package{scrlayer}, the package does not define it again.% +\EndIndex{Cmd}{LenToUnit}% + + +\begin{Declaration} + \Macro{putUL}\Parameter{content}\\ + \Macro{putUR}\Parameter{content}\\ + \Macro{putLL}\Parameter{content}\\ + \Macro{putLR}\Parameter{content}\\ + \Macro{putC}\Parameter{content} +\end{Declaration} +\BeginIndex{Cmd}{putUL}% +\BeginIndex{Cmd}{putUR}% +\BeginIndex{Cmd}{putLL}% +\BeginIndex{Cmd}{putLR}% +\BeginIndex{Cmd}{putC}% +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 +\PName{content} relative to the upper left corner of the layer and therefore +is the same like +\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})|. +\Macro{putLL} places the \PName{content} relative to the lower left corner of +the layer and therefore is the same like +\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 +the layer.% +\begin{Example} + You want to investigate, how accurate \OptionValue{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: +\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} +\end{lstcode} + You will see 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}, +\autopageref{sec:typearea.circleConstruction}. + +For more information about command +\Macro{DeclareNewPageStyleByLayers}\IndexCmd{DeclareNewPageStyleByLayers} see +the description later in \autoref{sec:scrlayer.pagestyles}, +\autopageref{desc:scrlayer.cmd.DeclareNewPageStyleByLayers}. In short: It +defines a new page style using the newly declared layer.% +\EndIndex{Cmd}{putC}% +\EndIndex{Cmd}{putLR}% +\EndIndex{Cmd}{putLL}% +\EndIndex{Cmd}{putUR}% +\EndIndex{Cmd}{putUL}% + \begin{Declaration} \Macro{GetLayerContents}\Parameter{layer name} |