diff options
Diffstat (limited to 'macros/latex/contrib/koma-script/doc/common-pagestylemanipulation-en.tex')
-rw-r--r-- | macros/latex/contrib/koma-script/doc/common-pagestylemanipulation-en.tex | 1034 |
1 files changed, 1034 insertions, 0 deletions
diff --git a/macros/latex/contrib/koma-script/doc/common-pagestylemanipulation-en.tex b/macros/latex/contrib/koma-script/doc/common-pagestylemanipulation-en.tex new file mode 100644 index 0000000000..c66ecb341b --- /dev/null +++ b/macros/latex/contrib/koma-script/doc/common-pagestylemanipulation-en.tex @@ -0,0 +1,1034 @@ +% ====================================================================== +% common-pagestylemanipulation-en.tex +% Copyright (c) Markus Kohm, 2013-2022 +% +% This file is part of the LaTeX2e KOMA-Script bundle. +% +% This work may be distributed and/or modified under the conditions of +% the LaTeX Project Public License, version 1.3c of the license. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later and of this work. +% +% This work has the LPPL maintenance status "author-maintained". +% +% The Current Maintainer and author of this work is Markus Kohm. +% +% This work consists of all files listed in MANIFEST.md. +% ====================================================================== +% +% Text that is common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{common-pagestylemanipulation-en.tex} + [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $ + KOMA-Script guide (common paragraph: + Setting up defined page styles)] +\translator{Markus Kohm\and Jana Schubert\and Karl Hagen} + +\section{Manipulating Page Styles} +\seclabel{pagestyle.content} +\BeginIndexGroup +\BeginIndex{}{page>style} + +\IfThisCommonLabelBase{scrlayer}{% + 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}{% + \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 a supplement to + \autoref{sec:scrlayer.pagestyle.content}. It describes features that may + be too complicated for beginners.% + }{\InternalCommonFileUsageError}% + }% +} + +\IfThisCommonLabelBase{scrlayer-scrpage-experts}{\iffalse}{% + \csname iftrue\endcsname}% + \begin{Declaration} + \IfThisCommonLabelBase{scrlayer}{% + \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} + 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 are described later + in this section. + \end{Explain}\par% + 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}.% + }{% + \IfThisCommonLabelBase{scrlayer}{% + 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. +% TODO: Fix new translation + With \Package{scrlayer} the distinction is done with the two commands + \Macro{automark} and \Macro{manualmark}.% +% :ODOT + }{\InternalCommonFileUsageError}% + }% + + 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}% + 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, 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 set right marks: +\begin{lstcode} + \automark*[section]{} +\end{lstcode} + 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. + + All that's missing now is a bit of document content to show the result: +\begin{lstcode} + \usepackage{lipsum} + \begin{document} + \chapter{Chapter Heading} + \lipsum[1-20] + \section{Section Heading} + \lipsum[21-40] + \end{document} +\end{lstcode} + 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 + + \IfThisCommonLabelBase{scrlayer}{}{% + \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 +\begin{lstcode} + \automark[subsection]{section} +\end{lstcode} + for other classes. + \fi + + \IfThisCommonLabelBaseOneOf{scrlayer,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}% + 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} + \usepackage[autooneside=false]{scrlayer-scrpage} + \pagestyle{scrheadings} + \automark[section]{chapter} + \usepackage{lipsum} + \begin{document} + \chapter{Chapter Heading} + \lipsum[1-20] + \section{Section Heading} + \lipsum[21-40] + \end{document} +\end{lstcode} + 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 + + 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}{\par% + You can find additional background information and examples of how to use + these commands in the documentation for the \Package{scrlayer} package + \hyperref[cha:scrlayer-scrpage]{\Package{scrlayer-scrpage}}% + in \autoref{sec:scrlayer-scrpage.pagestyle.content}, starting on + \DescPageRef{scrlayer-scrpage.cmd.manualmark}.% + }{% + \EndIndexGroup% + }% + \EndIndexGroup + + + \IfThisCommonLabelBase{scrlayer}{% already described at \layercontentsmeasure + }{% + \begin{Declaration} + \OptionVName{draft}{simple switch} + \end{Declaration} + 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{text} + \OptionVName{markcase}{value} + \end{Declaration} + 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}. Using the \DescRef{\LabelBase.option.markcase}% + \IndexOption{markcase}\important{\DescRef{\LabelBase.option.markcase}} + option with one of the values of \autoref{tab:scrlayer-scrpage.markcase} + also redefines \Macro{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 + \autoref{tab:scrlayer-scrpage.markcase}% + \IfThisCommonLabelBase{scrlayer-scrpage}{}{, + \autopageref{tab:scrlayer-scrpage.markcase}}.% + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \begin{table} + \centering + \caption[Available values for the \Option{markcase} option]{Available + values for the \Option{markcase} option to select upper/lower case + 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 + \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 + \Macro{MakeUppercase} (upper case typesetting).% + }% + \pventry{used}{\IndexOption[indexmain]{markcase~=used}% + redefines \DescRef{\LabelBase.cmd.MakeMarkcase} to use automatic + running heads without any case changes.% + }% + \entry{\PValue{ignoreuppercase}, \PValue{nouppercase}, + \PValue{ignoreupper}, + \PValue{noupper}}{\IndexOption[indexmain]{markcase~=noupper}% + redefines not only \DescRef{\LabelBase.cmd.MakeMarkcase} but also + \Macro{MakeUppercase} and \Macro{uppercase} locally to the running + heads to leave the automatic running heads unchanged.% + }% + \end{desctabular} + \end{table} + }{}% + \EndIndexGroup +\fi + + +\IfThisCommonLabelBase{scrlayer-scrpage}{\iffalse}{\csname iftrue\endcsname} + \begin{Declaration} + \Macro{righttopmark} + \Macro{rightbotmark} + \Macro{rightfirstmark} + \Macro{rightmark} + \Macro{lefttopmark} + \Macro{leftbotmark} + \Macro{leftfirstmark} + \Macro{leftmark} + \end{Declaration} + \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 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 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 + \DescRef{scrlayer.cmd.rightmark} or \Macro{rightfirstmark} always shows an + 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 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 +\fi + + +\IfThisCommonLabelBase{scrlayer-scrpage-experts}{\iffalse}{% + \csname iftrue\endcsname}% + \begin{Declaration} + \IfThisCommonLabelBase{scrlayer-scrpage}{% + \Macro{leftmark} + \Macro{rightmark} + }{}% + \Macro{headmark} + \Macro{pagemark} + \end{Declaration} + \IfThisCommonLabelBase{scrlayer-scrpage}{% + 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}.} + + }{}% + + 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. + + The \Macro{pagemark}\important{\Macro{pagemark}} command has nothing to do + with \TeX's mark mechanism. It is used 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 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 showing the usage of the + \Macro{headmark} and \Macro{pagemark} commands, see + \autoref{sec:scrlayer-scrpage.pagestyle.content}, + \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}% + 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} + \chead{} + \cfoot[]{} + \begin{document} + \blinddocument + \end{document} +\end{lstcode} + 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} 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 this command + described in \autoref{sec:scrlayer-scrpage-experts.pagestyle.pairs}. + \end{Example} + + Please note\textnote{Attention!} that the empty optional argument of + \DescRef{scrlayer-scrpage.cmd.cfoot} in the example above is not the same + 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 + + \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{\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 + + + \begin{Declaration} + \Macro{partmarkformat}% + \Macro{chaptermarkformat}% + \Macro{sectionmarkformat}% + \Macro{subsectionmarkformat}% + \Macro{subsubsectionmarkformat}% + \Macro{paragraphmarkformat}% + \Macro{subparagraphmarkformat} + \end{Declaration} + \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 + information.% + \csname iffalse\endcsname% + }% + \begin{Example} + \phantomsection\xmpllabel{cmd.sectionmarkformat}% + \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} + \renewcommand*{\sectionmarkformat}{} +\end{lstcode} + \end{Example} + \ExampleEndFix + \fi% + \EndIndexGroup + + + \begin{Declaration} + \Macro{partmark}\Parameter{Text}% + \Macro{chaptermark}\Parameter{Text}% + \Macro{sectionmark}\Parameter{Text}% + \Macro{subsectionmark}\Parameter{Text}% + \Macro{subsubsectionmark}\Parameter{Text}% + \Macro{paragraphmark}\Parameter{Text}% + \Macro{subparagraphmark}\Parameter{Text} + \end{Declaration} + 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 + + + \begin{Declaration} + \Macro{markleft}\Parameter{left mark} + \Macro{markright}\Parameter{right mark} + \Macro{markboth}\Parameter{left mark}\Parameter{right mark} + \Macro{markdouble}\Parameter{mark} + \end{Declaration} + 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 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}.% + \csname iffalse\endcsname% + }% + \begin{Example} + \phantomsection\xmpllabel{cmd.markboth}% + 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} + \pagestyle{scrheadings} + \usepackage{blindtext} + \begin{document} + \chapter*{Preface} + \markboth{Preface}{Preface} + \blindtext[20] + \tableofcontents + \blinddocument + \end{document} +\end{lstcode} + 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} + \pagestyle{scrheadings} + \usepackage{blindtext} + \begin{document} + \chapter*{Preface} + \markboth{\MakeMarkcase{Preface}}{\MakeMarkcase{Preface}} + \blindtext[20] + \tableofcontents + \blinddocument + \end{document} +\end{lstcode} + Using command \DescRef{\LabelBase.cmd.MakeMarkcase} results in getting + the same letter case as for automatic running heads. + + 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 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} + \pagestyle{scrheadings} + \usepackage{blindtext} + \begin{document} + \tableofcontents + \chapter*{Preface} + \markboth{}{} + \blindtext[20] + \blinddocument + \end{document} +\end{lstcode} + \end{Example} + \fi% +% TODO: Fix new translation + The\ChangedAt{v3.28}{\Package{scrlayer}} command + \Macro{markdouble}\important{\Macro{markdouble}} does change the left mark + and the right mark to the same contents. So + \Macro{markdouble}\Parameter{mark} is a shorter form of + \Macro{markboth}\Parameter{mark}\Parameter{mark} with two identical + arguments.% +% :ODOT + \EndIndexGroup +\fi + + +\IfThisCommonLabelBase{scrlayer-scrpage}{\iffalse}{\csname iftrue\endcsname} + \begin{Declaration} + \Macro{GenericMarkFormat}\Parameter{name of the section level} + \end{Declaration} + 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 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 + \xmpllabel{cmd.GenericMarkFormat}% + 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} + \usepackage[automark]{scrlayer-scrpage} + \pagestyle{scrheadings} + \usepackage{xcolor} + \newcommand*{\numberbox}[1]{% + \colorbox{black}{\strut~\textcolor{white}{#1}~}} + \renewcommand*{\GenericMarkFormat}[1]{% + \protect\numberbox{\csname the#1\endcsname}\enskip} + \begin{document} + \blinddocument + \end{document} +\end{lstcode} + 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}). + + 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 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}}, or + \DescRef{scrlayer.cmd.chaptermarkformat}% + \IndexCmd{chaptermarkformat}% + \important{\DescRef{scrlayer.cmd.chaptermarkformat}} and + \DescRef{scrlayer.cmd.sectionmarkformat}% + \IndexCmd{sectionmarkformat}% + \important{\DescRef{scrlayer.cmd.sectionmarkformat}}, because + these are not by default defined using \Macro{GenericMarkFormat}: +\begin{lstcode} + \documentclass[headheight=19.6pt]{scrbook} + \usepackage{blindtext} + \usepackage[automark]{scrlayer-scrpage} + \pagestyle{scrheadings} + \usepackage{xcolor} + \newcommand*{\numberbox}[1]{% + \colorbox{black}{\strut~\textcolor{white}{#1}~}} + \renewcommand*{\GenericMarkFormat}[1]{% + \protect\numberbox{\csname the#1\endcsname}\enskip} + \renewcommand*{\chaptermarkformat}{\GenericMarkFormat{chapter}} + \renewcommand*{\sectionmarkformat}{\GenericMarkFormat{section}} + \begin{document} + \blinddocument + \end{document} +\end{lstcode} + % TODO: New translation + Here, option \DescRef{typearea.option.headheight} is used to eliminate + the warning, that also has been reported in the previous example.% + % :ODOT + \end{Example} + \fi% + \EndIndexGroup +\fi + + +\IfThisCommonLabelBase{scrlayer-scrpage}{\iffalse}{\csname iftrue\endcsname} + \begin{Declaration} + \Macro{@mkleft}\Parameter{left mark}% + \Macro{@mkright}\Parameter{right mark}% + \Macro{@mkdouble}\Parameter{mark}% + \Macro{@mkboth}\Parameter{left mark}\Parameter{right mark} + \end{Declaration} + 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}{% + \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 + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "scrguide-en.tex" +%%% coding: utf-8 +%%% ispell-local-dictionary: "en_GB" +%%% eval: (flyspell-mode 1) +%%% End: + +% LocalWords: scrlayer |