diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/koma-script/doc/english/common-pagestylemanipulation.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/koma-script/doc/english/common-pagestylemanipulation.tex | 1086 |
1 files changed, 626 insertions, 460 deletions
diff --git a/Master/texmf-dist/source/latex/koma-script/doc/english/common-pagestylemanipulation.tex b/Master/texmf-dist/source/latex/koma-script/doc/english/common-pagestylemanipulation.tex index 8c85bf399fc..422721ad15d 100644 --- a/Master/texmf-dist/source/latex/koma-script/doc/english/common-pagestylemanipulation.tex +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-pagestylemanipulation.tex @@ -1,6 +1,6 @@ % ====================================================================== % common-pagestylemanipulation.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. % ---------------------------------------------------------------------- % common-pagestylemanipulation.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,166 +46,188 @@ % ============================================================================ \KOMAProvidesFile{common-pagestylemanipulation.tex} - [$Date: 2013-10-22 11:17:09 +0200 (Di, 22 Okt 2013) $ + [$Date: 2018-02-05 01:50:56 -0800 (Mon, 05 Feb 2018) $ KOMA-Script guide (common paragraph: - Manipulation of defined page styles)] -\translator{Markus Kohm\and Jana Schubert} + Setting up defined page styles)] +\translator{Markus Kohm\and Jana Schubert\and Karl Hagen} -% Date version of the translated file: 2015-06-18 +% Date version of the translated file: 2018-02-05 -\section{Manipulation of Defined Page Styles} +\section{Manipulating Page Styles} \seclabel{pagestyle.content} \BeginIndexGroup \BeginIndex{}{page>style} \IfThisCommonLabelBase{scrlayer}{% - Even though \Package{scrlayer} itself does not define a concrete page style - with content\,---\,the already mentioned page styles - \PageStyle{@everystyle@} and \PageStyle{empty} are initially defined without - any level and so empty and without content\,---\,, it provides some options - and commands for the manipulation of the contents.% + Although \Package{scrlayer} itself does not define concrete page styles with + content\,---\,the previously mentioned page styles + \DescRef{\LabelBase.pagestyle.@everystyle@} and \PageStyle{empty} are + initially defined without any layers, i.\,e., without content\,---\,, the + package provides some options and commands to manipulate their contents.% }{% \IfThisCommonLabelBase{scrlayer-scrpage}{% - \hyperref[sec:scrlayer-scrpage.predefined.pagestyles]% - {Section~\ref*{sec:scrlayer-scrpage.predefined.pagestyles}} states the - predefined defaults for the page style \PageStyle{scrheadings} and - \PageStyle{plain.scrheadings} and how they can be adapted. But - information about the generation of, i.\,e., the running heads, the - manipulation of the widths of page head and footer, and how you can get - horizontal lines printed above or below the page head or footer are still - missing. Even though all these are features of package \Package{scrlayer}, - they will be described consecutively, because these basic features of - \Package{scrlayer} are also a fundamental part of the features of - \Package{scrlayer-scrpage}.% + \autoref{sec:scrlayer-scrpage.predefined.pagestyles} explains how the page + styles \DescRef{\LabelBase.pagestyle.scrheadings} and + \DescRef{\LabelBase.pagestyle.plain.scrheadings} are defined and how these + defaults can be changed. But topics such as creating running headers, + changing the widths of the header and footer, and putting horizontal lines + above or below the header or footer have yet to be described. Although + these capabilities are actually part of the + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + \important{\hyperref[cha:scrlayer]{\Package{scrlayer}}} package, they will + be explained below because these basic features of + \hyperref[cha:scrlayer]{\Package{scrlayer}} make up an important part of + \IfThisCommonLabelBase{scrlayer-scrpage}{\Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + }.% }{% \IfThisCommonLabelBase{scrlayer-scrpage-experts}{% - This section is an add-on to + This section is a supplement to \autoref{sec:scrlayer.pagestyle.content}. It describes features that may - be to complicated for beginners.% + be too complicated for beginners.% }{\InternalCommonFileUsageError}% }% } - \IfThisCommonLabelBase{scrlayer-scrpage-experts}{\iffalse}{% \csname iftrue\endcsname}% \begin{Declaration} - \Macro{automark}\OParameter{section level of the right mark}% - \Parameter{section level of the left mark}% - \Macro{automark*}\OParameter{section level of the right mark}% - \Parameter{section level of the left mark}% - \Macro{manualmark}% - \Option{automark}% - \OptionVName{autooneside}{simple switch}% - \Option{manualmark} + \Macro{automark}\OParameter{section level of the right mark} + \Parameter{section level of the left mark} + \Macro{automark*}\OParameter{section level of the right mark} + \Parameter{section level of the left mark} + \Macro{manualmark} \end{Declaration} \IfThisCommonLabelBase{scrlayer-scrpage}{% \begin{Explain} - With the \LaTeX{} standard classes or the \KOMAScript{} classes the - decision whether using automatic running heads\Index{running - heads>automatic}, or static or manual running heads\Index{running - heads>static}\Index{running heads>manual} would be done using either - page style \PageStyle{headings} or \PageStyle{myheadings}. Automatic - running heads are replications of a significant, characterizing text - snippet of the page mostly inside the page head, sometimes in the page - footer. - - The article classes\OnlyAt{\Class{article}\and \Class{scrartcl}} - \Class{article} or \Class{scrartcl} with page style - \PageStyle{headings}\IndexPagestyle{headings} use the section heading, - which is either the mandatory or the optional argument of - \DescRef{maincls.cmd.section}, for the automatic running head of single side - documents. Double side documents use this section heading as the - \emph{left mark} and at once use the subsection heading as the - \emph{right mark}. The left mark will be printed on left pages, which - founds the name \emph{left mark}. The right mark will be printed on - right\,---\,in single side mode this means every\,---\,page. The classes - by default also remove the right mark whenever they put the section - heading into the left mark. - - The report and book classes \OnlyAt{\Class{report}\and - \Class{scrreprt}\and \Class{book}\and \Class{scrbook}} start one level - higher. So they use the chapter heading to be the right mark in single - side layout. In double side layout they use the chapter heading to be - the left mark and the section heading to be the right mark. - - If you are using \PageStyle{myheadings} instead of - \PageStyle{headings}\IndexPagestyle{myheadings}, the marks in the page - header still exists and would be printed same like using - \PageStyle{headings}. But section commands will not automatically set - the marks any longer. So\important{% - \DescRef{\ThisCommonLabelBase.cmd.markright}\\ - \DescRef{\ThisCommonLabelBase.cmd.markboth}}% - you can fill them only using the commands + In both the standard \LaTeX{} classes and the \KOMAScript{} classes, the + decision of whether to use automatic or static running + heads\Index{running heads>automatic}\Index{running heads>static} is made + by using the appropriate page style. Running heads repeat some + descriptive text, such as a title, that is appropriate to the page or + column, usually in the header, more rarely in the footer. As already + explained in + \autoref{sec:maincls.pagestyle}, you get automatic running heads with + \DescRef{maincls.pagestyle.headings}\IndexPagestyle{headings}% + \important{\DescRef{maincls.pagestyle.headings}} + + In the article classes\OnlyAt{\Class{article}\and \Class{scrartcl}} + \Class{article} or \hyperref[cha:maincls]{\Class{scrartcl}}, the + \PageStyle{headings}\IndexPagestyle{headings} page style uses the + section heading, which is either the mandatory or the optional argument + of \DescRef{maincls.cmd.section}, for the running head% + \textnote{automatic running head} of one-sided documents. Two-sided + documents use this section heading as the \emph{left mark} and the + subsection heading as the \emph{right mark}. The left mark is printed, + as the name indicates, on left-hand (verso) pages. The right mark is + printed on right-hand (recto)\,---\,in one-sided printing this means on + all\,---\,pages. The classes by default also delete the right mark + whenever they put the section heading into the left mark. + + The report and book classes \OnlyAt{\Class{report}\and + \Class{scrreprt}\and \Class{book}\and \Class{scrbook}} start one level + higher. Thus they use the chapter heading as the right mark in one-sided + printing. In two-sided printing, the chapter heading is the left mark + and the section heading is the right mark. + + If you use \DescRef{maincls.pagestyle.myheadings}% + \IndexPagestyle{myheadings}% + \important{\DescRef{maincls.pagestyle.myheadings}}\textnote{manual + running head}, the marks in the page header still exist, and the page + numbers are placed in the same way, but section commands no longer set + the marks automatically. You can set them manually\important{% + \DescRef{\ThisCommonLabelBase.cmd.markright}\\ + \DescRef{\ThisCommonLabelBase.cmd.markboth}} using the commands \DescRef{\ThisCommonLabelBase.cmd.markright} and - \DescRef{\ThisCommonLabelBase.cmd.markboth}, which will be described - later in this section. + \DescRef{\ThisCommonLabelBase.cmd.markboth}, which are described later + in this section. \end{Explain}\par }{% \IfThisCommonLabelBase{scrlayer}{% - In common classes the decision for a page style\,---\,generally - \PageStyle{headings} and \PageStyle{myheading}\,---\,is also a decision - to use either automatic or manual running heads. % + For most classes, the choice of a page style\,---\,generally + \PageStyle{headings} or \PageStyle{myheading}\,---\,determines whether + the running heads are created automatically or manually. % }{\InternalCommonFileUsageError}% }% - This difference between those two page styles has been abolished by - \Package{scrpage2} and also by \Package{scrlayer}. Instead of distinguishing - between automatic and manual running head by the selection of a page style, - two new commands, \Macro{automark} and \Macro{manualmark}, are provided. - - The command \Macro{manualmark} switches to manual marks and deactivates the - automatic filling of the marks. In contrast to this \Macro{automark} and - \Macro{automark*} can be used to define, which section levels should be used - for the automatic mark filling. The optional argument is the \PName{section - level of the right mark}, the mandatory argument the \PName{section level - of the left mark}. The arguments always should be the name of a section - level like \PValue{part}, \PValue{chapter}, \PValue{section}, - \PValue{subsection}, \PValue{subsubsection}, \PValue{paragraph}, or - \PValue{subparagraph}. - - Generally the higher level should be used for the left mark and the lower - level for the right mark. This is only a convention and not a need, but it - makes sense. - - Please note\textnote{Attention} that not every class provides running heads - for every section level. For example the standard classes never setup the - running head of \DescRef{maincls.cmd.part}. The \KOMAScript{} classes - provide running heads for every section level. - - The difference in \Macro{automark} and \Macro{automark*} is, that - \Macro{automark} deletes all prior usages of \Macro{automark} or - \Macro{automark*}, while \Macro{automark*} changes only the behaviour of the - section levels of its arguments. So you can even build more complex cases. + This distinction has been eliminated by % + \iffalse \Package{scrpage2} and now also by \fi% + \hyperref[cha:scrlayer]{\Package{scrlayer}}\IndexPackage{scrlayer}. Instead + of distinguishing between automatic\textnote{automatic and manual running + heads} and manual running heads by which page style is selected, there are + two new commands: \Macro{automark} and \Macro{manualmark}. + + The \Macro{manualmark}\important{\Macro{manualmark}} command switches to + manual marks and deactivates the automatic filling of the marks. In contrast, + \Macro{automark}\important{\Macro{automark}} and \Macro{automark*} define + which section levels should be used to set the mark automatically. The + optional argument is the \PName{section level of the right mark}, the + mandatory argument the \PName{section level of the left mark}. The + arguments should always be the name of a section level like + \PValue{part}, \PValue{chapter}, \PValue{section}, \PValue{subsection}, + \PValue{subsubsection}, \PValue{paragraph}, or \PValue{subparagraph}. + + Normally, the higher level should be used for the left mark and the lower + level for the right mark. This is only a convention and not a requirement, + but it makes sense. + + Please note\textnote{Attention!} that not every class provides running heads + for every section level. For example, the standard classes\textnote{% + \KOMAScript{} vs. standard classes} never use \DescRef{maincls.cmd.part} + in the heading. The \KOMAScript{} classes, on the other hand, support all + levels. + + The difference between \Macro{automark} and \Macro{automark*}% + \important{\Macro{automark*}} is that \Macro{automark} overrides all + previous commands to automatically set the mark, while \Macro{automark*} + changes only the behaviour of the section levels specified in its + arguments.% + \IfThisCommonLabelBase{scrlayer-scrpage}{}{ With this feature you can handle + relatively complex cases.}% Umbruchoptimierung \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{\csname iffalse\endcsname}% + \iffalse% Umbruchkorrekturtext + \iffree{}{\par + The obsolete package + \Package{scrpage2}\IndexPackage{scrpage2}\important{\Package{scrpage2}} + understands both \Macro{manualmark} and \Macro{automark}, but not + \Macro{automark*}. Therefore the following examples are not completely + transferable when using \Package{scrpage2}.% + }% + \fi + % \begin{Example} \phantomsection\xmpllabel{mark}% - Assume you want the chapter heading to be the running head of even pages - and the section heading to be the running head of odd pages like this is - usual for books. But on odd pages you also want the chapter headings as - a running head as long as the first section appears. To do so, you first - have to load \Package{scrlayer-scrpage} and select page style - \PageStyle{scrheadings}. So you're document starts with: + Suppose you want chapter headings to be used as the running head of even + pages and the section heading to be the running head of odd pages, as + usual. But on odd pages you also want the chapter headings to be used as + the running head until the first section appears. To do so, you first + have to load \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}} + and select the \DescRef{\LabelBase.pagestyle.scrheadings} page style, + so the document starts with: \begin{lstcode} \documentclass{scrbook} \usepackage{scrlayer-scrpage} \pagestyle{scrheadings} \end{lstcode} - Next you will setup the chapter heading to be not only the left but also - the right mark: + Next, ensure that the chapter headings set both the left and the right + marks: \begin{lstcode} \automark[chapter]{chapter} \end{lstcode} - Then the section heading should also become a right mark: + Then the section heading should also set right marks: \begin{lstcode} \automark*[section]{} \end{lstcode} - Here the star version is used, because the prior \Macro{automark} - command should be still valid. Additionally the mandatory argument for - the \PName{section level of the left mark} is empty, because this mark - should be unchanged. + Here the starred version is used, since the previous \Macro{automark} + command should remain in effect. Additionally, the mandatory argument + for the \PName{section level of the left mark} is empty because this + mark should remain unchanged. - Now you just need some document contents to see a result: + All that's missing now is a bit of document content to show the result: \begin{lstcode} \usepackage{lipsum} \begin{document} @@ -215,50 +237,70 @@ \lipsum[21-40] \end{document} \end{lstcode} - We once again use package \Package{lipsum}\IndexPackage{lipsum} to - generate some dummy text with command - \Macro{lipsum}\IndexCmd{lipsum}. The package is really useful. - - If you'd test the example, you'd see, that the chapter start page does - not have a running head as usual. This is, because it automatically uses - the \PageStyle{plain} page style - \PageStyle{plain.scrheadings}. Pages~2--4 have the chapter headings in - the running head. After the section heading on page~4 the running head - of page~5 changes into this section heading. From this page to the end - the running head alternates between chapter and section heading from - page to page. + We use the extremely useful \Package{lipsum}\IndexPackage{lipsum} + package to generate some dummy text with command + \Macro{lipsum}\IndexCmd{lipsum}. + + If you test the example, you will see that the first page of the chapter + appears, as usual, without a running head, since this page automatically + uses the \PageStyle{plain} page style + \DescRef{\LabelBase.pagestyle.plain.scrheadings} (see the + \DescRef{maincls.cmd.chapterpagestyle} on + \DescPageRef{maincls.cmd.chapterpagestyle}). Pages~2--4 have the + chapter headings in the running head. After the section heading on + page~4, the running head of page~5 changes to this section heading. From + this page to the end, the running head alternates from page to page + between the chapter and section headings.% \end{Example} \fi - Instead of the commands you may also use the options \Option{manualmark} and - \Option{automark} to switch between manual and automatic running - heads. Thereby \Option{automark} always uses the default + \begin{Declaration} + \Option{automark} + \OptionVName{autooneside}{simple switch} + \Option{manualmark} + \end{Declaration} + Instead of the commands described previously, you can also use the + \Option{manualmark}\important{\Option{manualmark}\\\Option{automark}} and + \Option{automark} options to switch between automatic and manual running + heads. \Option{automark} always uses the default\textnote{default} + \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{\csname + iffalse\endcsname}% + \lstinline|\automark[section]{chapter}| for classes with + \DescRef{maincls.cmd.chapter} and + \lstinline|\automark[subsection]{section}| for other classes. + \else \begin{lstcode} \automark[section]{chapter} \end{lstcode} - for classes with \DescRef{maincls.cmd.chapter} and + for classes with \DescRef{maincls.cmd.chapter} and \begin{lstcode} \automark[subsection]{section} \end{lstcode} - for classes without \DescRef{maincls.cmd.chapter}. - - But normally in single side mode you do not want that the lower level - influences the right mark, you want the higher level, that will fill only - the left mark in double side layout, to be the running head of all - pages. The default option \Option{autooneside} corresponds to this - behaviour. The option understands the values for simple switches, that can - be found in \autoref{tab:truefalseswitch} on - \autopageref{tab:truefalseswitch}. If you'd deactivate the option, in single - side layout the optional and the obligatory arguments of \Macro{automark} - and \Macro{automark*} will influence the running head again.% + for other classes. + \fi + + \IfThisCommonLabelBase{scrlayer-scrpage}{% + In one-sided printing, you normally want only the higher section levels + to provide the running title.% + }{% + In one-sided printing, you normally do not want the lower section level + to influence the right mark. Instead, you want the higher section + level, which would appear in only the left mark in two-sided printing, to + be the running head of all pages.% + } The default option \Option{autooneside}\important{\Option{autooneside}} + corresponds to this behaviour. The option accepts the values for + simple switches listed in \autoref{tab:truefalseswitch}, + \autopageref{tab:truefalseswitch}. If you deactivate this option, the + optional and mandatory arguments of \Macro{automark} and \Macro{automark*} + will again control the running head in one-sided printing.% \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{\csname iffalse\endcsname}% \begin{Example} \phantomsection\xmpllabel{mark.oneside}% - Assume you have a single sided report but want similar running heads as - in the book example before. The chapter headings should be used as a - running head as long as the first section appears. From the first - section on, the section heading should be used. So we modify the + Suppose you have a one-sided report but want running heads similar to + those in the previous book example. Specifically, the chapter headings + should be used as the running head until the first section appears. + From the then on, the section heading should be used. So we modify the previous example a little bit: \begin{lstcode} \documentclass{scrreprt} @@ -273,77 +315,116 @@ \lipsum[21-40] \end{document} \end{lstcode} - You can see, that we do not need a \Macro{automark*} command in this - case. Please try the example also with \Option{autooneside} set to - \PValue{true} or remove the option and its value. You should find a - difference at the running head in the pages' head from page~4 on. + As you can see an \DescRef{\LabelBase.cmd.automark*} command is not + required in this case. You should try the example with + \Option{autooneside} set to \PValue{true}, or remove the option, for + comparison. You will notice a difference in the running head from + page~4 on. \end{Example} \fi - Please note\textnote{Attention!}, only loading the package does not have any - effect on the fact whether automatic or manual running heads are used or - what kind of section headings do fill up the marks. Only using an explicit - option \Option{automark} or \Option{manualmark} or one of the commands - \Macro{automark} or \Macro{manualmark} can reach a well defined state.% + Note\textnote{Attention!} that merely loading the package does not have any + effect on whether automatic or manual running heads are used, or what kind + of sectioning headings fill the marks. Only by explicitly using the option + \Option{automark} or \Option{manualmark}, or the command + \DescRef{\LabelBase.cmd.automark} or \DescRef{\LabelBase.cmd.manualmark}, + will the conditions here be initialized.% + \IfThisCommonLabelBase{scrlayer-scrpage}{\par% + You can find additional background information and examples of how to use + these commands in the documentation for the \Package{scrlayer} package + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + } in \autoref{sec:scrlayer-scrpage.pagestyle.content}, starting on + \DescPageRef{scrlayer-scrpage.cmd.manualmark}.% + }{}% + \EndIndexGroup \EndIndexGroup \begin{Declaration} \OptionVName{draft}{simple switch} \end{Declaration} - This \KOMAScript{} option understands the values for simple switches, that - are shown in \autoref{tab:truefalseswitch} on - \autopageref{tab:truefalseswitch}. If the option is active, all elements of - the page styles will also show dimension lines. This might be useful while - draft editing.% - \IfThisCommonLabelBase{scrlayer-scrpage}{% - If the option has been set as a global option (see the optional argument - of \DescRef{\LabelBase.cmd.documentclass}), but you do not want the - dimension lines, you can deactivate them for the package only using + This \KOMAScript{} option accepts the values for simple switches + listed in \autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}. + If this option is active, all elements of the page styles will also show + rulers\index{ruler}% + \IfThisCommonLabelBase{scrlayer}{ for}{% + . This can sometimes be useful during} + the drafting process.% + \IfThisCommonLabelBase{scrlayer-scrpage}{ % + If this option has been set globally (see the optional argument + of \DescRef{\LabelBase.cmd.documentclass}) but you do not want the + rulers, you can deactivate them for this package alone by using \OptionValue{draft}{false} as an optional argument of \DescRef{\LabelBase.cmd.usepackage} while loading the package.% }{}% \EndIndexGroup \begin{Declaration} - \Macro{MakeMarkcase}\Parameter{string} + \Macro{MakeMarkcase}\Parameter{text} \end{Declaration} - The automatic running head and only this uses \Macro{MakeMarkcase} for its - output. If the command has not been defined, e.\,g., by the class, while - loading \Package{scrlayer}, it would be defined with the default of - outputting the argument \PName{string} without changes. But the default can - be change either redefining \Macro{MakeMarkcase} or using option - \DescRef{\LabelBase.option.markcase}, that will be described next. - Depending on the setting the argument could, e.\,g., be converted into upper - or lower cases. - % + Automatic running heads, but not manual ones, use \Macro{MakeMarkcase} for + their output. If the command has not been defined, e.\,g., by the class + while loading \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }, it is defined by default to output the argument \PName{text} without + changes. But the default can be changed either by redefining + \Macro{MakeMarkcase} or by using the \DescRef{\LabelBase.option.markcase}% + \IndexOption{markcase}\important{\DescRef{\LabelBase.option.markcase}} + option, which will be described next. Depending on the setting, the + argument can, e.\,g., be converted into upper or lower case.% \EndIndexGroup \begin{Declaration} - \OptionVName{markcase}{Wert} + \OptionVName{markcase}{value} \end{Declaration} - As already mentioned with \Package{scrlayer} you may switch between manual - and automatic running heads. Using automatic running heads the corresponding - marks will be filled by the section heading commands. Some culture areas do - convert the running heads into upper case letters in opposite to the German - typographic habit. The \LaTeX{} standard classes do so by default. Package - \Package{scrlayer} optionally provides this too. Therefor you'd use option - \OptionValue{markcase}{upper} which results in a redefinition of - \DescRef{scrlayer.cmd.MakeMarkcase}\IndexCmd[indexmain]{MakeMarkcase}, a - command, that is used by \Package{scrlayer} for automatic running heads. - - Unfortunately \LaTeX's command for upper case letter typesetting, - \Macro{MakeUppercase}\IndexCmd{MakeUppercase} results in an very inadequate - typesetting, because it neither uses letter spacing nor does it space - balancing. One reason for this behaviour might be, that a glyph analyzing - would be needed, to incorporate the letter shapes and their combination - while space balancing. Because of this \KOMAScript{} author suggests to - abstain from upper case letter typesetting for running heads. This could be - achieved using \OptionValue{markcase}{used}. Nevertheless, some classes - would add \Macro{MarkUppercase} or even \TeX{} command \Macro{uppercase} - into the running heads. For such cases option - \OptionValue{markcase}{noupper} can be used. This will also deactivate + As explained earlier, with \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } you can choose between manual and automatic running heads. Using automatic + running heads, the corresponding marks are set using the section heading + commands. In some cultures, in contrast to the typography of German-speaking + countries, it is common practice to set the running heads in upper-case + letters. The \LaTeX{} standard classes do so by default. The + \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } package also offers this as an option. To do so, use the + \OptionValue{markcase}{upper}\important{\OptionValue{markcase}{upper}}% + \IndexOption[indexmain]{markcase~=upper} option, which redefines + \DescRef{scrlayer.cmd.MakeMarkcase}\IndexCmd[indexmain]{MakeMarkcase}. + + \IfThisCommonLabelBase{scrlayer}{% + Because of the poor typographical quality of the primitive capitalisation + routine (see the explanation of \DescRef{scrlayer-scrpage.option.markcase} + in \autoref{sec:scrlayer-scrpage.pagestyle.content}, + \autopageref{expl:scrlayer-scrpage.MakeUppercase}) the author of + \KOMAScript recommends that you avoid upper-case typesetting for running + heads.% + }{% + Unfortunately,\phantomsection\label{expl:\ThisCommonLabelBase.MakeUppercase} + the \LaTeX{} command for converting text to upper case\Index{upper case}, + \Macro{MakeUppercase}\IndexCmd{MakeUppercase}, does not produce good + results because it neither spaces characters nor balances lines + appropriately. This is certainly in part due to the fact that a + typographically correct upper-case conversion requires analysing the + glyphs to account for the different letter shapes \iffree{and their + combinations}{} while balancing the block. I therefore recommend that + you avoid upper-case typesetting for running heads.% + } This is usually possible with \OptionValue{markcase}{used}\important{% + \OptionValue{markcase}{used}}\IndexOption[indexmain]{markcase~=used}. + However, some classes insert \Macro{MarkUppercase}, or even the \TeX{} + command \Macro{uppercase}, into the running heads. For such cases, you can + use the option \OptionValue{markcase}{noupper}% + \important{\OptionValue{markcase}{noupper}}% + \IndexOption[indexmain]{markcase~=noupper}. This will also deactivate \Macro{MakeUppercase} and \Macro{uppercase} inside the running heads. You can find all valid values for \Option{markcase} in @@ -353,19 +434,19 @@ \IfThisCommonLabelBase{scrlayer-scrpage}{% \begin{table} \centering - \caption[Possible values for option \Option{markcase}]{Possible values + \caption[Available values for option \Option{markcase}]{Available values for option \Option{markcase} to select upper/lower case letter typesetting in automatic running heads}% \label{tab:\ThisCommonLabelBase.markcase}% \begin{desctabular} \pventry{lower}{\IndexOption[indexmain]{markcase~=lower}% redefines \DescRef{\LabelBase.cmd.MakeMarkcase} to convert the - automatic running heads into lower case letters using + automatic running heads into lower-case letters using \Macro{MakeLowercase} (lower case typesetting).% }% \pventry{upper}{\IndexOption[indexmain]{markcase~=upper}% redefines \DescRef{\LabelBase.cmd.MakeMarkcase} to convert the - automatic running heads into upper case letters using + automatic running heads into upper-case letters using \Macro{MakeUppercase} (upper case typesetting).% }% \pventry{used}{\IndexOption[indexmain]{markcase~=used}% @@ -376,104 +457,137 @@ \PValue{ignoreupper}, \PValue{noupper}}{\IndexOption[indexmain]{markcase~=noupper}% redefines not only \DescRef{\LabelBase.cmd.MakeMarkcase} but also - locally to the running heads \Macro{MakeUppercase} and - \Macro{uppercase} to leave the automatic running heads unchanged.% + \Macro{MakeUppercase} and \Macro{uppercase} locally to the running + heads to leave the automatic running heads unchanged.% }% \end{desctabular} \end{table} }{}% \EndIndexGroup + \begin{Declaration} - \Macro{leftmark}% - \Macro{rightmark}% - \Macro{headmark}% + \Macro{leftmark} + \Macro{rightmark} + \Macro{headmark} \Macro{pagemark} \end{Declaration} - If you want to differ from the predefined page styles, usually you need to - decide, where to place the marks' contents. With \Macro{leftmark} you can - state the contents of the left mark. - - Similar you can use \Macro{rightmark} to state the contents of the right - mark. For more information about some intricacies of this see the further - description of \DescRef{maincls-experts.cmd.rightmark} in + If you want to depart from the predefined page styles, you typically need to + decide where to place the marks' contents. With + \Macro{leftmark}\important{\Macro{leftmark}} you can define what will + appear in the left mark when the page is output. + + Similarly, you can use \Macro{rightmark}\important{\Macro{rightmark}} to + define the contents of the right mark.\iffree{}{ For information about some + subtleties when using these commands, see further + \DescRef{maincls-experts.cmd.rightmark} in \autoref{sec:maincls-experts.addInfos}, - \DescPageRef{maincls-experts.cmd.rightmark}. + \DescPageRef{maincls-experts.cmd.rightmark}.} - Somehow easier would be usage of \Macro{headmark}. This extension of - \Package{scrlayer} aliases either \Macro{leftmark} or \Macro{rightmark} - depending on whether the current page is even or odd. + You can make life easier with \Macro{headmark}\important{\Macro{headmark}}. + This extension of \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } is a shorthand that resolves to either \Macro{leftmark} or + \Macro{rightmark} depending on whether the current page is even or odd. - Strictly thought command \Macro{pagemark} is not involved by \TeX's mark - mechanism. It is only used to output a formatted page number. + The \Macro{pagemark}\important{\Macro{pagemark}} command has nothing to do + with \TeX's mark mechanism. It is serves to output a formatted page number. \BeginIndex{FontElement}{pagenumber}\LabelFontElement{pagenumber}% The font of element \FontElement{pagenumber}\important{\FontElement{pagenumber}} will be used - for the output. This can be changed using command \Macro{setkomafont} or - \DescRef{maincls.cmd.addtokomafont} (see also + for the output. This can be changed using the \Macro{setkomafont} or + \DescRef{maincls.cmd.addtokomafont} commands (see also \autoref{sec:maincls.textmarkup}, \DescPageRef{maincls.cmd.setkomafont}).% \EndIndex{FontElement}{pagenumber}% \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{% \par % - If you are interested in an example about usage of commands - \Macro{headmark} and \Macro{pagemark}, have a look into + If you are interested in an example showing the usage of the + \Macro{headmark} and \Macro{pagemark} commands, see \autoref{sec:scrlayer-scrpage.pagestyle.content}, - \PageRefxmpl{scrlayer-scrpage.cmd.headmark}. The package - \Package{scrlayer-scrpage} internally uses a lot of such features of - \Package{scrlayer}.% + \PageRefxmpl{scrlayer-scrpage.cmd.headmark}. Internally, the + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + } package uses many such features of + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }{% + \Package{scrlayer}% + }.% \csname iffalse\endcsname}% \begin{Example} \phantomsection\xmpllabel{cmd.headmark}% - Assume you want to use a left aligned running head and right aligned - page number in the head of the pages of a document in single side - layout. The following minimal but working examples would do so: + Suppose you want the running head to be aligned to the left margin and + the page number to the right margin in one-sided printing. The following + minimal working example does just this: \begin{lstcode} \documentclass{scrreprt} \usepackage{blindtext} \usepackage[automark]{scrlayer-scrpage} \pagestyle{scrheadings} \ihead{\headmark} - \ohead[\pagemark]{\pagemark} + \ohead*{\pagemark} \chead{} \cfoot[]{} \begin{document} \blinddocument \end{document} \end{lstcode} - Here package \Package{blindtext}\IndexPackage{blindtext} with its - command \Macro{blinddocument}\IndexCmd{blinddocument} has been used to - easily generate content for an example document. - - Commands \DescRef{scrlayer-scrpage.cmd.ihead}\IndexCmd{ihead} and - \DescRef{scrlayer-scrpage.cmd.ohead}\IndexCmd{ohead} have been used to - place the wanted marks. Although the page mark will be place not only to - pages in page style \PageStyle{scrheadings} but using the optional - argument also to pages in page style \PageStyle{plain.scrheadings}. - - Because of both page styles already have marks in the middle of the page - head and page foot, those elements will be cleared using + The \Package{blindtext}\IndexPackage{blindtext} package and its + \Macro{blinddocument}\IndexCmd{blinddocument} command have been used + here to quickly generate sample document content for the example. + + The \DescRef{scrlayer-scrpage.cmd.ihead}\IndexCmd{ihead} and + \DescRef{scrlayer-scrpage.cmd.ohead*}\IndexCmd{ohead*} commands + configure the desired marks. The starred variant + \DescRef{scrlayer-scrpage.cmd.ohead*} % + \iffalse% Umbruchvarianten + configures the page number mark not only on the pages set with the + \DescRef{\LabelBase.pagestyle.scrheadings}% + \IndexPagestyle{scrheadings} page style but also those set + with the \PageStyle{plain} % + \else% + also configures the page number with the % + \fi% + \DescRef{\LabelBase.pagestyle.plain.scrheadings}% + \IndexPagestyle{plain.scrheadings} page style used on the first page of + a chapter.% + + Because these page styles have predefined marks in the centre of the + header and footer, those elements are cleared by using \DescRef{scrlayer-scrpage.cmd.chead} and - \DescRef{scrlayer-scrpage.cmd.cfoot}\IndexCmd{cfoot} with empty - arguments. Alternatively you'd use + \DescRef{scrlayer-scrpage.cmd.cfoot} with empty arguments. Alternatively + you could use \DescRef{scrlayer-scrpage-experts.cmd.clearpairofpagestyles} \IndexCmd{clearpairofpagestyles} \emph{before} - \DescRef{scrlayer-scrpage.cmd.ihead}. You will find a description of - this command in \autoref{sec:scrlayer-scrpage-experts.pagestyle.pairs}. + \DescRef{scrlayer-scrpage.cmd.ihead}. You will find this command + described in \autoref{sec:scrlayer-scrpage-experts.pagestyle.pairs}. \end{Example} - Please note\textnote{Attention!}, that the empty optional argument of + Please note\textnote{Attention!} that the empty optional argument of \DescRef{scrlayer-scrpage.cmd.cfoot} in the example above is not the same - like omitting the optional argument. Please try it out and have a look at - the difference in the footer of the first page.% + as omitting the optional argument. You should try it yourself and have a + look at the difference in the footer of the first page.% \fi - If all the mark features described above are not sufficient, experienced - users can find more of them on \IfThisCommonLabelBase{scrlayer-scrpage}{% + \IfThisCommonLabelBase{scrlayer-scrpage}{% Umbruchvarianten + Advanced users can find more mark-setting commands% + }{% + If the options for the marks described above are not sufficient, + additional commands for advanced users are documented% + } % + starting on \IfThisCommonLabelBase{scrlayer-scrpage}{% \DescPageRef{scrlayer-scrpage-experts.cmd.righttopmark}}{% - \DescPageRef{scrlayer.cmd.righttopmark}}. For example, you can find there - \DescRef{scrlayer-scrpage-experts.cmd.leftfirstmark} and - \DescRef{scrlayer-scrpage-experts.cmd.rightbotmark}, which seem to be useful - for lexicon like documents.% + \DescPageRef{\ThisCommonLabelBase.cmd.righttopmark}}.% + \iffalse% Umbruchkorrektur + \ For example, there you can find + \DescRef{scrlayer-scrpage-experts.cmd.leftfirstmark} and + \DescRef{scrlayer-scrpage-experts.cmd.rightbotmark}, which are quite useful + for documents like lexicons.% + \fi% \EndIndexGroup @@ -486,11 +600,14 @@ \Macro{paragraphmarkformat}% \Macro{subparagraphmarkformat} \end{Declaration} - Usually the \KOMAScript{} classes and package \Package{scrlayer} use these - commands internally to bring the section numbers into wanted form and - additionally they support the \DescRef{maincls.cmd.autodot} mechanism of the - \KOMAScript{} classes. If wanted these commands may be redefined to get - another form of section numbers.% + \KOMAScript{} classes and the \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } package typically use these commands internally to format the section + numbers. They also support the \DescRef{maincls.cmd.autodot} mechanism of + the \KOMAScript{} classes. If desired, these commands can be redefined to + achieve a different formatting of section numbers.% \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{% \ See the example in \autoref{sec:scrlayer-scrpage.pagestyle.content}, \PageRefxmpl{scrlayer-scrpage.cmd.sectionmarkformat} for more @@ -499,15 +616,19 @@ }% \begin{Example} \phantomsection\xmpllabel{cmd.sectionmarkformat}% - Assume you do not want section numbers but section heading text only in - the running head. So: -\begin{lstcode} + \iftrue + For example, if you want to have running heads without a section + number, this is how you do it: + \else + Suppose you want section headings without the section number to appear + in the running head. This can be accomplished easily with the + following: + \fi +\begin{lstcode}[belowskip=-\dp\strutbox] \renewcommand*{\sectionmarkformat}{} \end{lstcode} - would be a simple solution for this. \end{Example} - \fi - % + \fi% \EndIndexGroup @@ -520,28 +641,33 @@ \Macro{paragraphmark}\Parameter{Text}% \Macro{subparagraphmark}\Parameter{Text} \end{Declaration} - Most classes use these commands to setup marks corresponding to the section - commands. Thereby the only argument is the text without the number of the - section heading, that should be used for the running head. For the number - simply the number of the current section level will be used, if the current - level uses numbers. - - Unfortunately\textnote{Attention!}, not all classes use such a command for - every section level. The standard classes for example do not call - \Macro{partmark}. The \KOMAScript{} classes support such commands for all - section levels and therefore also use \Macro{partmark}. - - If users redefine these commands, they should\textnote{Attention!} take care - to also use the counter \DescRef{maincls.counter.secnumdepth} for the test - whether or not the section level should output a number, even in the case - the user does not change counter \DescRef{maincls.counter.secnumdepth} - himself, because packages and classes may do so locally and rely on correct - handling of \DescRef{maincls.counter.secnumdepth}. - - However, package \Package{scrlayer} redefines these commands whenever you - use \DescRef{scrlayer.cmd.automark} or \DescRef{scrlayer.cmd.manualmark} or - the corresponding options, to activate or deactivate the wanted running - heads.% + Most classes use these commands internally to set the marks according to the + sectioning commands. The argument should contain the text without the number + of the sectioning unit. The number is automatically determined using the + current section level if you use numbered headings. + + However\textnote{Attention!}, not all classes use such a command for + every section level. The standard classes\textnote{\KOMAScript{} vs. + standard classes}, for example, do not call \Macro{partmark} + \IfThisCommonLabelBase{scrlayer-scrpage}{% + upon a \Macro{part} command}{% + , whereas the \KOMAScript{} classes naturally support \Macro{partmark} as + well}. + + If you redefine these commands, be sure\textnote{Attention!} to check + whether the numbers will be output via the + \DescRef{maincls.counter.secnumdepth} before setting the number even if you + do not change the \DescRef{maincls.counter.secnumdepth} counter yourself, + because packages and classes may do so locally and rely on correct handling + of \DescRef{maincls.counter.secnumdepth}. + + The \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } package also redefines these commands whenever you use + \DescRef{scrlayer.cmd.automark} or \DescRef{scrlayer.cmd.manualmark} or the + corresponding options, to activate or deactivate the desired running heads.% \EndIndexGroup @@ -550,36 +676,50 @@ \Macro{markright}\Parameter{right mark}% \Macro{markboth}\Parameter{left mark}\Parameter{right mark} \end{Declaration} - Independent of whether currently manual or automatic running heads are - active, you may change the contents of the \PName{left mark} or the - \PName{right mark} at any time using these commands. You should note, that - the resulting contents of \Macro{leftmark}\IndexCmd{leftmark} is the - \PName{left mark} of the last \Macro{markleft} or \Macro{markboth} command - of the current page. In opposite to this the resulting contents of - \Macro{rightmark}\IndexCmd{rightmark} is the \PName{right mark} of the first - \Macro{rightmark} or \Macro{markboth} command of the current page. - - If you are using manual running heads, the marks will stay valid until one - of the corresponding commands will be used again. If you are using automatic - running heads the marks can loose their validity with the next section - heading depending on the configuration of the automatism. - - You may also use these commands together with the star versions of the - section commands.% + Regardless of whether you are working with manual or automatic running + heads, you can always change the contents of the \PName{left mark} or the + \PName{right mark} using these commands. Note that the left-hand mark + resulting from \Macro{leftmark}\IndexCmd{leftmark}% + \important{\Macro{leftmark}} will be the last mark placed on the + corresponding page, while the right-hand mark resulting from + \Macro{rightmark}\IndexCmd{rightmark}\important{\Macro{rightmark}} is the + first mark placed on the corresponding page. For more details, see + \iffree{}{the additional explanation of + \DescRef{maincls-experts.cmd.rightmark} in + \autoref{sec:maincls-experts.addInfos}, + \DescPageRef{maincls-experts.cmd.rightmark} or} to + \DescRef{scrlayer.cmd.rightfirstmark}\IfThisCommonLabelBase{scrlayer}{}{ in + \autoref{sec:scrlayer.pagestyle.content}}, + \DescPageRef{scrlayer.cmd.rightfirstmark}. + + If you are using manual running heads\Index{running head>manual}, the marks + remain valid until they are explicitly replaced by reusing the corresponding + commands. However, if you are using automatic running heads, the marks can + become invalid with the next section heading, depending on the automatic + configuration. + + You can also use these commands in conjunction with the starred versions of + the sectioning commands.% \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{% - \ You can find a detailed example about usage of \Macro{markboth} with - \Package{scrlayer-scrpage} in + \ You can find detailed examples illustrating usage of \Macro{markboth} + with the \IfThisCommonLabelBase{scrlayer-scrpage}{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }{% + \Package{scrlayer}% + }-derived package \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + } in \autoref{sec:scrlayer-scrpage.pagestyle.content}, - \PageRefxmpl{scrlayer-scrpage.cmd.markboth}. Package - \Package{scrlayer-scrpage} is a kind of extension of \Package{scrlayer}.% + \PageRefxmpl{scrlayer-scrpage.cmd.markboth}.% \csname iffalse\endcsname% }% \begin{Example} \phantomsection\xmpllabel{cmd.markboth}% - Assume you are using a preface with several pages just before the table - of contents, that should not have an entry at the table of contents - itself. Because of using a separation line at the page head, you want - also a running head for this preface: + Suppose you write a preface of several pages placed just before the + table of contents but not appearing in it. However, since you use + dividing lines in your header, you want a running head for this preface: \begin{lstcode} \documentclass[headsepline]{book} \usepackage{scrlayer-scrpage} @@ -593,9 +733,10 @@ \blinddocument \end{document} \end{lstcode} - First of all this seems to produce the wanted result. But have a closer - look: In difference to the other running heads ``\texttt{Preface}'' is - not in upper case letters. But you can fix this easily: + At first glance, this seems to produce the desired result. Taking a + second look, however, you can see that the running title + ``\texttt{Preface}'' does not appear in upper-case letters, unlike the + other running heads. But that's easy to change: \begin{lstcode} \documentclass[headsepline]{book} \usepackage{scrlayer-scrpage} @@ -612,14 +753,14 @@ Using command \DescRef{\LabelBase.cmd.MakeMarkcase} results in getting the same letter case as for automatic running heads. - Now, let's move command \DescRef{maincls.cmd.tableofcontents} in front - of the preface. Let's remove the \Macro{markboth} command too. You'll - realise, that the preface now has the running head - ``\texttt{CONTENTS}''. This is because of a quirk of + Now, let's move the \DescRef{maincls.cmd.tableofcontents} in front + of the preface and remove the \Macro{markboth} command. You'll + discover that the preface now has the running head + ``\texttt{CONTENTS}''. This is due to a quirk of \DescRef{maincls.cmd.chapter*} (see also \autoref{sec:maincls.structure} - on \DescPageRef{maincls.cmd.chapter*}). If in such cases the running - head should be removed, \Macro{markboth} with two empty arguments would - be useful: + on \DescPageRef{maincls.cmd.chapter*}). If you do not want a running + head here, you can easily accomplish this by passing two empty arguments + to \Macro{markboth}: \begin{lstcode} \documentclass[headsepline]{book} \usepackage{scrlayer-scrpage} @@ -634,8 +775,7 @@ \end{document} \end{lstcode} \end{Example} - \fi - % + \fi% \EndIndexGroup \fi @@ -644,39 +784,49 @@ \begin{Declaration} \Macro{GenericMarkFormat}\Parameter{name of the section level} \end{Declaration} - At the running head this command will be used by default for the formatting - of all section numbers below the subsection and with classes without - \DescRef{maincls.cmd.chapter} also for the section level and the subsection - level, if the mark commands for those numbers have not been defined before - loading \Package{scrlayer}. Thereby the package uses - \Macro{@seccntmarkformat} if such a command has been defined, like the - \KOMAScript{} classes do. Otherwise \Macro{@seccntformat} will be used, - which is provided by the \LaTeX{} kernel. The expected, mandatory argument - of the command is the \PName{name of a section level}, i.\,e., - \PValue{chapter} or \PValue{section} \emph{without} the backslash prefix. - - You can change the default formatting of the numbers, that use this command, - by redefining only this single command. Classes can change the default + By default, this command is used to format all section numbers in running + heads below the subsection level, and for classes without + \DescRef{maincls.cmd.chapter}, also for the section and subsection levels, + unless the respective mark commands for those levels are defined before + loading \Package{scrlayer}. The command causes the package to use + \Macro{@seccntmarkformat}\IndexCmd{@seccntmarkformat}% + \important{\Macro{@seccntmarkformat}} if this internal command is defined, + as it is in the \KOMAScript{} classes. Otherwise \Macro{@seccntformat}% + \IndexCmd{@seccntformat}\important{\Macro{@seccntformat}} will be used, + which is provided by the \LaTeX{} kernel. The mandatory argument of the + command contains the name of a sectioning command, such as \PValue{chapter} + or \PValue{section} \emph{without} the backslash prefix. + + By redefining this command, you can change the default number format for all + sectioning commands that use it. Classes can also change the default formatting also by defining this command.% \IfThisCommonLabelBase{scrlayer-scrpage-experts}{\iftrue}{% \par % - A detailed example about cooperation of command \Macro{GenericMarkFormat} - and the commands \DescRef{\ThisCommonLabelBase.cmd.sectionmarkformat} and - \DescRef{\ThisCommonLabelBase.cmd.subsectionmarkformat} that are described - at \DescPageRef{\ThisCommonLabelBase.cmd.chaptermark} is shown in - \autoref{sec:scrlayer-scrpage-experts.pagestyle.content}, + A detailed example illustrating the interplay of the + \Macro{GenericMarkFormat} command with the + \DescPageRef{\ThisCommonLabelBase.cmd.chaptermark} command and + \DescRef{\ThisCommonLabelBase.cmd.sectionmarkformat} or + \DescRef{\ThisCommonLabelBase.cmd.subsectionmarkformat} when using + the \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }-derived package \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Package{scrlayer-scrpage}% + }{% + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + } is shown in \autoref{sec:scrlayer-scrpage-experts.pagestyle.content}, \PageRefxmpl{scrlayer-scrpage-experts.cmd.GenericMarkFormat}.% \csname iffalse\endcsname}% \begin{Example} - \phantomsection + \phantomsection \xmpllabel{cmd.GenericMarkFormat}% - Assume you want the section numbers of all levels at the running head of - an article to be printed in white colour inside a black coloured - box. Using standard \LaTeX{} \Class{article} class, package - \Package{scrlayer} defines the number mark commands - \Macro{sectionmarkformat} and \Macro{subsectionmarkformat} using - \Macro{GenericMarkFormat}. So you need to redefine only this single - command: + Suppose you want the section numbers of all levels in the running head + of an article to be printed in white within a black box. Since the + commands \Macro{sectionmarkformat} and \Macro{subsectionmarkformat} of + the \Package{scrlayer} package are defined with + \Macro{GenericMarkFormat} for articles using the standard \LaTeX{} + \Class{article} class, you need to redefine only this one command: \begin{lstcode} \documentclass{article} \usepackage{blindtext} @@ -691,40 +841,39 @@ \blinddocument \end{document} \end{lstcode} - The colour has been done using package - \Package{xcolor}\IndexPackage{xcolor}. See the package manual for more - information about this. + The colour has been changed using the + \Package{xcolor}\IndexPackage{xcolor} package. More details can be found + in that package's manual (see \cite{package:xcolor}). - Additionally a not visible strut has been used. Every complete \LaTeX{} + This example also uses an invisible strut. Any detailed \LaTeX{} introduction should explain the related command \Macro{strut}. - A helper macro \Macro{numberbox} has been defined for the formatting of - the number within a box. In the redefinition of - \Macro{GenericMarkFormat} this has been prefixed by \Macro{protect} to - protect it from expansion. This is necessary because otherwise the upper - case letter conversion of \Macro{MakeUppercase} that will be used for - the running head, would result in an ask for colours ``\texttt{BLACK}'' - and ``\texttt{WHITE}'' instead of ``\texttt{black}'' and - ``\texttt{white}'' and those colours are undefined. Alternatively you - may define \Macro{numberbox} using \Macro{DeclareRobustCommand*} instead - of \Macro{newcommand*} and then omit \Macro{protect} (see - \cite{latex:clsguide}). - - If you'd do the same with a \KOMAScript{} class or with one of the - \LaTeX{} standard classes \Class{book} or \Class{report}, you'd - additionally have to redefine \DescRef{scrlayer.cmd.sectionmarkformat}% - \IndexCmd{sectionmarkformat}% + A helper macro, \Macro{numberbox}, has been defined to format the number + within a box. This command is prefixed in the redefinition of + \Macro{GenericMarkFormat} by \Macro{protect} in order to protect it from + expansion. This is necessary because otherwise the upper-case letter + conversion of \Macro{MakeUppercase} for the running head, would result + in using the colours ``\texttt{BLACK}'' and ``\texttt{WHITE}'' instead + of ``\texttt{black}'' and ``\texttt{white}'', and those colours are + undefined. Alternatively, you could define \Macro{numberbox} using + \Macro{DeclareRobustCommand*} instead of \Macro{newcommand*} and omit + \Macro{protect} (see \cite{latex:clsguide}). + + If you wanted to achieve the same effect with a \KOMAScript{} class or + with the standard \LaTeX{} classes \Class{book} or \Class{report}, you + would also have to redefine, respectively, + \DescRef{scrlayer.cmd.sectionmarkformat}\IndexCmd{sectionmarkformat}% \important{\DescRef{scrlayer.cmd.sectionmarkformat}} and \DescRef{scrlayer.cmd.subsectionmarkformat}% \IndexCmd{subsectionmarkformat}% - \important{\DescRef{scrlayer.cmd.subsectionmarkformat}} respectively + \important{\DescRef{scrlayer.cmd.subsectionmarkformat}}, or \DescRef{scrlayer.cmd.chaptermarkformat}% \IndexCmd{chaptermarkformat}% \important{\DescRef{scrlayer.cmd.chaptermarkformat}} and \DescRef{scrlayer.cmd.sectionmarkformat}% \IndexCmd{sectionmarkformat}% - \important{\DescRef{scrlayer.cmd.sectionmarkformat}} and too, because - then these would not have been defined using \Macro{GenericMarkFormat}: + \important{\DescRef{scrlayer.cmd.sectionmarkformat}}, because + these are not by default defined using \Macro{GenericMarkFormat}: \begin{lstcode} \documentclass{scrbook} \usepackage{blindtext} @@ -742,8 +891,7 @@ \end{document} \end{lstcode} \end{Example} - \fi - % + \fi% \EndIndexGroup @@ -755,66 +903,79 @@ \Macro{leftbotmark}% \Macro{leftfirstmark} \end{Declaration} - For page styles \LaTeX\ChangedAt{v3.16}{\Package{scrlayer}} uses a bipartite - \TeX{} mark. Running heads can use the left part of that mark by - \DescRef{scrlayer.cmd.leftmark}% + \LaTeX\ChangedAt{v3.16}{\Package{scrlayer}} typically uses a two-part + \TeX{} mark for page styles. Running heads can access the left part of that + mark with \DescRef{scrlayer.cmd.leftmark}% \important{\DescRef{scrlayer.cmd.leftmark}}\IndexCmd{leftmark} and the right - part by \DescRef{scrlayer.cmd.rightmark}% - \important{\DescRef{scrlayer.cmd.rightmark}}\IndexCmd{rightmark}. Indeed, it - seems that it was suggested to use \DescRef{scrlayer.cmd.leftmark} for the - running head of left, even pages and \DescRef{scrlayer.cmd.rightmark} for - the running head of right, odd pages of double-sided documents. Within - single-sided layouts the standard classes even do not set the left part of - the mark. - - \TeX{} itself knows three alternatives to make usage of a mark. The - \Macro{botmark} is the last valid mark of the page that has been build - last. If there has not been set any mark on the page, it is the last mark of - the already shipped out pages. \LaTeX{} command - \DescRef{scrlayer.cmd.leftmark} uses exactly this mark. So it shows the left - part of the last mark of the page. This is the same like - \Macro{leftbotmark}. In opposite to this \Macro{rightbotmark} shows the - right part of that mark. - - \Macro{firstmark} is the first mark of the page that has been build - last. This means the first mark, that has been set on the page. If there has - not been set any mark on the page, this is the last mark of the already - shipped out pages. \LaTeX{} command \DescRef{scrlayer.cmd.rightmark} uses - exaclty this mark. So it shows the right part of the first mark of the - page. This is the same like \Macro{rightfirstmark}. In opposite to this - \Macro{leftfirstmark} shows the left part of that mark. - - \Macro{topmark} is the content of \Macro{botmark} before building the - current page. \LaTeX{} itself does not use it. Nevertheless, - \Package{scrlayer} provides \Macro{lefttopmark} to show the left part of it - and \Macro{righttopmark} to show the right part of it. - - Note\textnote{Attention!} that the left part and the right part of the mark - can be made all together only. Even if you use + part with \DescRef{scrlayer.cmd.rightmark}% + \important{\DescRef{scrlayer.cmd.rightmark}}\IndexCmd{rightmark}. In fact, + it was probably intended to use \DescRef{scrlayer.cmd.leftmark} for the + running head of left (even) pages and \DescRef{scrlayer.cmd.rightmark} for + the running head of right (odd) pages of two-sided documents. In + one-sided printing, however, the standard classes do not even set the left + part of the mark. + + \TeX{} itself knows three ways to access a mark. The \Macro{botmark}% + \IndexCmd{botmark}\important{\Macro{botmark}} is the last valid mark of the + most recent page that has been built. If no mark has been set on the page, + it corresponds to the last mark set on the pages that have already been + shipped out. The \LaTeX{} command \DescRef{scrlayer.cmd.leftmark} uses + precisely this mark, so it returns the left part of the last mark of the + page. This corresponds exactly to \Macro{leftbotmark}% + \important{\Macro{leftbotmark}}. By comparison, \Macro{rightbotmark}% + \important{\Macro{rightbotmark}} prints the right part of this mark. + + \Macro{firstmark}\IndexCmd{firstmark}\important{\Macro{firstmark}} is the + first mark of the last page that has been built. This is the first mark that + has been set on the page. If no mark has been set on the page, it + corresponds to the last mark of the pages that have already been shipped + out. The \LaTeX{} command \DescRef{scrlayer.cmd.rightmark} uses precisely + this mark, so it returns the right part of the first mark of the page. This + corresponds exactly to \Macro{rightfirstmark}% + \important{\Macro{rightfirstmark}}. By comparison, \Macro{leftfirstmark}% + \important{\Macro{leftfirstmark}} prints the left part of this mark. + + \Macro{topmark}\IndexCmd{topmark}\important{\Macro{topmark}} is the content + that \Macro{botmark} had before building the current page. \LaTeX{} itself + does not use it. Nevertheless, \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } provides \Macro{lefttopmark}\important{\Macro{lefttopmark}} to access the + left part of this mark and \Macro{righttopmark}% + \important{\Macro{righttopmark}} to access the right part. + + Note\textnote{Attention!} that the left and right portions of the mark + can only be set together. Even if you use \DescRef{scrlayer.cmd.markright}\IndexCmd{markright} to change only the - right part, the left part will be made again (unchanged). Accordingly in - double-side mode using page style - \PageStyle{headings\important{\PageStyle{headings}}\IndexPagestyle{headings}} - the higher section levels always make both parts. For example + right part, the left part will set again (unchanged). Accordingly, in + two-sided printing, using the \PageStyle{headings}% + \important{\PageStyle{headings}}\IndexPagestyle{headings} page style, + the higher section levels always make both parts. For example, \DescRef{scrlayer.cmd.chaptermark} uses \DescRef{scrlayer.cmd.markboth} with - an empty right argument in this case. This is the reason why + an empty right argument in this case. This is the reason \DescRef{scrlayer.cmd.rightmark} or \Macro{rightfirstmark} always shows an - empty value on pages with chapter beginnings, even if there was a + empty value on pages which start a chapter, even if there was a \DescRef{scrlayer.cmd.sectionmark} or \DescRef{maincls.cmd.section} on the same page to make the right part of the mark. Please note\textnote{Attention!} that using any of these commands to show - the left or right part of the mark as part of the page content could have - unexpected results. They are recommended to be used in the head or foot of a - page style only. So with \Package{scrlayer} they should be part of the - contents of a layer. But it does not matter whether or not a layer is - restricted to the background or the foreground. Both kind of layers are - shipped out after building the current page. - - If you need more information about the mark mechanism of \TeX, please have a - look at \cite[chapter~23]{knuth:texbook}. You will find, that marks are an - issue for real experts. So if the explanation above was at least more - confusing than illuminative: Please don't worry.% + the left or right part of the mark as part of the page content may lead to + unexpected results. They are really meant for use in the header or footer + of a page style only. Therefore, they should always be part of the contents + of a layer when using \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }. But it does not matter whether the layer is restricted to the background + or the foreground, since all layers are shipped out after building the + current page. + + If you need more information about the mark mechanism + \iffree{of \TeX{}}{\unskip}, please have a look at + \cite[chapter~23]{knuth:texbook}. The topic is flagged there as an issue for + real experts. \IfThisCommonLabelBase{scrlayer}{% Umbruchkorrektur + So if the explanation above confused you, please don't worry about it.}{}% \EndIndexGroup @@ -824,40 +985,45 @@ \Macro{@mkdouble}\Parameter{mark}% \Macro{@mkboth}\Parameter{left mark}\Parameter{right mark} \end{Declaration} - Sometimes inside classes and packages the marks for running heads should be - filled up only if automatic running heads are active (see option - \DescRef{scrlayer.option.automark} and command - \DescRef{scrlayer.cmd.automark} on - \DescPageRef{scrlayer-scrpage.cmd.automark}). In the \LaTeX{} standard - classes only \Macro{@mkboth} has been used for this. This command is either - \Macro{@gobbletwo}, that simply destroys both mandatory arguments, or - \DescRef{scrlayer.cmd.markboth}, a command that fills up the left and - \PValue{left mark} and the \PValue{right mark}. Packages like - \Package{babel} also change \Macro{\@mkboth}, i.\,e., to add language - switching to the running head. - - But if a class or package author only wants to change either the \PName{left - mark} or the \PName{right mark} without the other one, a proper command is - missing. Package \Package{scrlayer} itself needs such commands for the - implementation of all cases of automatic running heads. So if command - \Macro{@mkleft} to fill up only the left mark or \Macro{@mkright} to fill up - only the right mark or \Macro{@mkdouble} to fill up both marks with the same - content is undefined while loading \Package{scrlayer}, the package will - define them. Thereby the actual definition of \Macro{@mkboth} will be used - as an indicator whether or not automatic running heads should be used. The - new commands will full up the marks only in the case of automatic running - heads. - - Class and package authors can use these commands too, if they want to fill - up only one of the marks or both marks with the same content but only if - automatic running heads are activated. This condition is also the difference - to the commands \Macro{markleft}, \Macro{markright}, and \Macro{markboth}.% - \EndIndexGroup -\fi - + Within classes and packages, you may only want to use running heads if + automatic running heads are active (see the + \DescRef{scrlayer.option.automark} option and the + \DescRef{scrlayer.cmd.automark} command on + \DescPageRef{scrlayer-scrpage.cmd.automark}). In the standard \LaTeX{} + classes, this only works with \Macro{@mkboth}. This command corresponds to + either \Macro{@gobbletwo}, which simply consumes both mandatory arguments, + or \DescRef{scrlayer.cmd.markboth}, which sets both the \PValue{left mark} + and the \PValue{right mark}. Packages like \Package{babel} also change + \Macro{\@mkboth}, e.\,g., to enable language switching in the running head. + + However, if you want to change only the \PName{left mark} or the + \PName{right mark} without changing the other one, there is no corresponding + command. The \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + } package itself needs such commands to implement automatic running heads. + So if \Macro{@mkleft}, for setting the left mark only, or \Macro{@mkright}, + for setting the right mark only, or \Macro{@mkdouble}, for setting both + marks with the same content, is undefined when loading + \IfThisCommonLabelBase{scrlayer}{% + \Package{scrlayer}% + }{% + \hyperref[cha:scrlayer]{\Package{scrlayer}}% + }, this package will define them. This definition uses the state of + \Macro{@mkboth} as an indication of whether to use automatic running heads. + The commands will set the marks only in the case of automatic running heads. + + Class and package authors can also fall back on these commands as appropriate + if they want to set the left or right the marks only if automatic running + heads are activated.% + \EndIndexGroup% +\fi% +% \IfThisCommonLabelBase{scrlayer}{% - For more information about manipulation of the contents of page styles see - also \autoref{sec:scrlayer-scrpage.pagestyle.content} from + \par + For more information about manipulating the contents of page styles, see + also \autoref{sec:scrlayer-scrpage.pagestyle.content} starting at \autopageref{sec:scrlayer-scrpage.pagestyle.content}.% }{}% \EndIndexGroup |