path: root/macros/latex/contrib/koma-script/doc/common-pagestylemanipulation-en.tex

% ======================================================================
% 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: 2023-09-18 09:02:03 +0200 (Mo, 18. Sep 2023) $
                  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}.%
        }\\[-1.7ex]
        \pventry{upper}{\IndexOption[indexmain]{markcase~=upper}%
          redefines \DescRef{\LabelBase.cmd.MakeMarkcase} to convert the
          automatic running heads into upper-case letters using
          \Macro{MakeUppercase}.%
        }\\[-1.7ex]
        \pventry{title}{\IndexOption[indexmain]{markcase~=title}%
          \IfThisCommonLabelBase{scrlayer}{%
            \ChangedAt{v3.41}{\Package{scrlayer}}}{%
            \IfThisCommonLabelBase{scrlayer-scrpage}{%
              \ChangedAt{v3.41}{\Package{scrlayer-scrpage}}}}{}%
          redefines \DescRef{\LabelBase.cmd.MakeMarkcase} to convert the
          automatic running heads into title-case using
          \Macro{MakeTitlecase}. This is done separately for the number
          and the text. If \Macro{MakeTitlecase} is not defined, i.\,e.,
          because you are using an old \LaTeX{} kernel, you will get a warning
          message and the option will be ignored.%
        }\\[-1.7ex]
        \pventry{used}{\IndexOption[indexmain]{markcase~=used}%
          redefines \DescRef{\LabelBase.cmd.MakeMarkcase} to use automatic
          running heads without any case changes.%
        }\\[-1.7ex]
        \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