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 | 872 |
1 files changed, 872 insertions, 0 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 new file mode 100644 index 00000000000..8c85bf399fc --- /dev/null +++ b/Master/texmf-dist/source/latex/koma-script/doc/english/common-pagestylemanipulation.tex @@ -0,0 +1,872 @@ +% ====================================================================== +% common-pagestylemanipulation.tex +% Copyright (c) Markus Kohm, 2013-2017 +% +% 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.txt. +% ---------------------------------------------------------------------- +% common-pagestylemanipulation.tex +% Copyright (c) Markus Kohm, 2013-2017 +% +% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz, +% Version 1.3c, verteilt und/oder veraendert werden. +% Die neuste Version dieser Lizenz ist +% http://www.latex-project.org/lppl.txt +% und Version 1.3c ist Teil aller Verteilungen von LaTeX +% Version 2005/12/01 oder spaeter und dieses Werks. +% +% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained" +% (allein durch den Autor verwaltet). +% +% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm. +% +% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien. +% ====================================================================== +% +% Text that is common for several chapters of the KOMA-Script guide +% Maintained by Markus Kohm +% +% ---------------------------------------------------------------------- +% +% Absaetze, die mehreren Kapitels in der KOMA-Script-Anleitung gemeinsam sind +% Verwaltet von Markus Kohm +% +% ============================================================================ + +\KOMAProvidesFile{common-pagestylemanipulation.tex} + [$Date: 2013-10-22 11:17:09 +0200 (Di, 22 Okt 2013) $ + KOMA-Script guide (common paragraph: + Manipulation of defined page styles)] +\translator{Markus Kohm\and Jana Schubert} + +% Date version of the translated file: 2015-06-18 + +\section{Manipulation of Defined 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.% +}{% + \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}.% + }{% + \IfThisCommonLabelBase{scrlayer-scrpage-experts}{% + This section is an add-on to + \autoref{sec:scrlayer.pagestyle.content}. It describes features that may + be to 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} + \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 + \DescRef{\ThisCommonLabelBase.cmd.markright} and + \DescRef{\ThisCommonLabelBase.cmd.markboth}, which will be 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. % + }{\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. + \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{\csname + iffalse\endcsname}% + \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: +\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: +\begin{lstcode} + \automark[chapter]{chapter} +\end{lstcode} + Then the section heading should also become a right mark: +\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. + + Now you just need some document contents to see a result: +\begin{lstcode} + \usepackage{lipsum} + \begin{document} + \chapter{Chapter Heading} + \lipsum[1-20] + \section{Section Heading} + \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. + \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{lstcode} + \automark[section]{chapter} +\end{lstcode} + 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.% + \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 + 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} + 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. + \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.% + \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 + \OptionValue{draft}{false} as an optional argument of + \DescRef{\LabelBase.cmd.usepackage} while loading the package.% + }{}% + \EndIndexGroup + + \begin{Declaration} + \Macro{MakeMarkcase}\Parameter{string} + \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. + % + \EndIndexGroup + + + \begin{Declaration} + \OptionVName{markcase}{Wert} + \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 + \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[Possible values for option \Option{markcase}]{Possible 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 + \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 + locally to the running heads \Macro{MakeUppercase} and + \Macro{uppercase} to leave the automatic running heads unchanged.% + }% + \end{desctabular} + \end{table} + }{}% + \EndIndexGroup + + \begin{Declaration} + \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 + \autoref{sec:maincls-experts.addInfos}, + \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. + + Strictly thought command \Macro{pagemark} is not involved by \TeX's mark + mechanism. It is only 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 command \Macro{setkomafont} or + \DescRef{maincls.cmd.addtokomafont} (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 + \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}.% + \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: +\begin{lstcode} + \documentclass{scrreprt} + \usepackage{blindtext} + \usepackage[automark]{scrlayer-scrpage} + \pagestyle{scrheadings} + \ihead{\headmark} + \ohead[\pagemark]{\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 + \DescRef{scrlayer-scrpage.cmd.chead} and + \DescRef{scrlayer-scrpage.cmd.cfoot}\IndexCmd{cfoot} with empty + arguments. Alternatively you'd 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}. + \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 + like omitting the optional argument. Please try it out 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}{% + \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.% + \EndIndexGroup + + + \begin{Declaration} + \Macro{partmarkformat}% + \Macro{chaptermarkformat}% + \Macro{sectionmarkformat}% + \Macro{subsectionmarkformat}% + \Macro{subsubsectionmarkformat}% + \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.% + \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}% + Assume you do not want section numbers but section heading text only in + the running head. So: +\begin{lstcode} + \renewcommand*{\sectionmarkformat}{} +\end{lstcode} + would be a simple solution for this. + \end{Example} + \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 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.% + \EndIndexGroup + + + \begin{Declaration} + \Macro{markleft}\Parameter{left mark}% + \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.% + \IfThisCommonLabelBase{scrlayer-scrpage}{\iftrue}{% + \ You can find a detailed example about usage of \Macro{markboth} with + \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}.% + \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: +\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} + 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: +\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 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 + \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: +\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 + % + \EndIndexGroup +\fi + + +\IfThisCommonLabelBase{scrlayer-scrpage}{\iffalse}{\csname iftrue\endcsname} + \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 + 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}, + \PageRefxmpl{scrlayer-scrpage-experts.cmd.GenericMarkFormat}.% + \csname iffalse\endcsname}% + \begin{Example} + \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: +\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 done using package + \Package{xcolor}\IndexPackage{xcolor}. See the package manual for more + information about this. + + Additionally a not visible strut has been used. Every complete \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}% + \important{\DescRef{scrlayer.cmd.sectionmarkformat}} and + \DescRef{scrlayer.cmd.subsectionmarkformat}% + \IndexCmd{subsectionmarkformat}% + \important{\DescRef{scrlayer.cmd.subsectionmarkformat}} respectively + \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}: +\begin{lstcode} + \documentclass{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} + \end{Example} + \fi + % + \EndIndexGroup + + + \begin{Declaration} + \Macro{righttopmark}% + \Macro{rightbotmark}% + \Macro{rightfirstmark}% + \Macro{lefttopmark}% + \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}% + \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 + \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 + \DescRef{scrlayer.cmd.chaptermark} uses \DescRef{scrlayer.cmd.markboth} with + an empty right argument in this case. This is the reason why + \DescRef{scrlayer.cmd.rightmark} or \Macro{rightfirstmark} always shows an + empty value on pages with chapter beginnings, 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.% + \EndIndexGroup + + + \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} + 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 + +\IfThisCommonLabelBase{scrlayer}{% + For more information about manipulation of the contents of page styles see + also \autoref{sec:scrlayer-scrpage.pagestyle.content} from + \autopageref{sec:scrlayer-scrpage.pagestyle.content}.% +}{}% +\EndIndexGroup + +%%% Local Variables: +%%% mode: latex +%%% mode: flyspell +%%% coding: iso-latin-1 +%%% ispell-local-dictionary: "en_GB" +%%% TeX-master: "../guide.tex" +%%% TeX-PDF-mode: t +%%% End: |