Note: This document is a translation of the German koma script manual

Chapter 17: Defining Layers and Page Styles Using scrlayer

407

markcase=Wert

As already mentioned with 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 L

A

TEX standard classes do so by default.

Package scrlayer optionally provides this too. Therefor you’d use option markcase=upper

which results in a redefinition of

\MakeMarkcase

, a command, that is used by scrlayer for

automatic running heads.

Unfortunately L

A

TEX’s command for upper case letter typesetting, \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 KOMA-Script author suggests to abstain from upper case letter typesetting for run-

ning heads. This could be achieved using markcase=used. Nevertheless, some classes would

add \MarkUppercase or even TEX command \uppercase into the running heads. For such

cases option markcase=noupper can be used. This will also deactivate \MakeUppercase and

\uppercase

inside the running heads.

You can find all valid values for markcase in

table 5.2

,

page 245

.

\leftmark

\rightmark

\headmark

\pagemark

If you want to differ from the predefined page styles, usually you need to decide, where to

place the marks’ contents. With \leftmark you can state the contents of the left mark.

Similar you can use \rightmark to state the contents of the right mark. For more in-

formation about some intricacies of this see the further description of

21.1

in

section 21.1

,

page 441

.

Somehow easier would be usage of \headmark. This extension of scrlayer aliases either

\leftmark

or \rightmark depending on whether the current page is even or odd.

Strictly thought command \pagemark is not involved by TEX’s mark mechanism. It is only

used to output a formatted page number. The font of element pagenumber will be used for

the output. This can be changed using command \setkomafont or

\addtokomafont

(see also

section 3.6

,

page 57

).

If you are interested in an example about usage of commands \headmark and \pagemark,

have a look into

section 5.5

,

page 245

. The package scrlayer-scrpage internally uses a lot of

such features of scrlayer.

If all the mark features described above are not sufficient, experienced users can find more

of them on

page 409

. For example, you can find there

\leftfirstmark

and

\rightbotmark

,

which seem to be useful for lexicon like documents.

Chapter 17: Defining Layers and Page Styles Using scrlayer

408

\partmarkformat

\chaptermarkformat

\sectionmarkformat

\subsectionmarkformat

\subsubsectionmarkformat

\paragraphmarkformat

\subparagraphmarkformat

Usually the KOMA-Script classes and package scrlayer use these commands internally to bring

the section numbers into wanted form and additionally they support the

\autodot

mechanism

of the KOMA-Script classes. If wanted these commands may be redefined to get another form

of section numbers. See the example in

section 5.5

,

page 246

for more information.

\partmark{Text }

\chaptermark{Text }

\sectionmark{Text }

\subsectionmark{Text }

\subsubsectionmark{Text }

\paragraphmark{Text }

\subparagraphmark{Text }

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, not all classes use such a command for every section level. The standard

classes for example do not call \partmark. The KOMA-Script classes support such commands

for all section levels and therefore also use \partmark.

If users redefine these commands, they should take care to also use the 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

secnumdepth

himself, because packages and classes may do so locally

and rely on correct handling of

secnumdepth

.

However, package scrlayer redefines these commands whenever you use

\automark

or

\manualmark

or the corresponding options, to activate or deactivate the wanted running heads.

\markleft{left mark }

\markright{right mark }

\markboth{left mark }{right mark }

Independent of whether currently manual or automatic running heads are active, you may

change the contents of the left mark or the right mark at any time using these com-

mands. You should note, that the resulting contents of \leftmark is the left mark of the

last \markleft or \markboth command of the current page. In opposite to this the resulting

Chapter 17: Defining Layers and Page Styles Using scrlayer

409

contents of \rightmark is the right mark of the first \rightmark or \markboth command

of the current page.

If you are using manual running heads, the marks will stay valid until one of the corre-

sponding 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.

You can find a detailed example about usage of \markboth with scrlayer-scrpage in

section 5.5

,

page 247

. Package scrlayer-scrpage is a kind of extension of scrlayer.

\GenericMarkFormat{name of the section level }

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

\chapter

also for the section level and

the subsection level, if the mark commands for those numbers have not been defined before

loading scrlayer. Thereby the package uses \@seccntmarkformat if such a command has been

defined, like the KOMA-Script classes do. Otherwise \@seccntformat will be used, which is

provided by the L

A

TEX kernel. The expected, mandatory argument of the command is the

name of a section level

, i. e., chapter or section 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.

A detailed example about cooperation of command \GenericMarkFormat and the com-

mands

\sectionmarkformat

and

\subsectionmarkformat

that are described at

page 408

is

shown in

section 18.1

,

page 413

.

\righttopmark

\rightbotmark

\rightfirstmark

\lefttopmark

\leftbotmark

\leftfirstmark

For page styles L

A

TEX

v3.16

uses a bipartite TEX mark. Running heads can use the left part of that

mark by

\leftmark

and the right part by

\rightmark

. Indeed, it seems that it was suggested

to use

\leftmark

for the running head of left, even pages and

\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 \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. L

A

TEX command

\leftmark

uses

Chapter 17: Defining Layers and Page Styles Using scrlayer

410

exactly this mark. So it shows the left part of the last mark of the page. This is the same like

\leftbotmark

. In opposite to this \rightbotmark shows the right part of that mark.

\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. L

A

TEX command

\rightmark

uses exaclty

this mark. So it shows the right part of the first mark of the page. This is the same like

\rightfirstmark

. In opposite to this \leftfirstmark shows the left part of that mark.

\topmark

is the content of \botmark before building the current page. L

A

TEX itself does

not use it. Nevertheless, scrlayer provides \lefttopmark to show the left part of it and

\righttopmark

to show the right part of it.

Note that the left part and the right part of the mark can be made all together only.

Even if you use

\markright

to change only the right part, the left part will be made again

(unchanged). Accordingly in double-side mode using page style headings the higher section

levels always make both parts. For example

\chaptermark

uses

\markboth

with an empty

right argument in this case. This is the reason why

\rightmark

or \rightfirstmark always

shows an empty value on pages with chapter beginnings, even if there was a

\sectionmark

or

\section

on the same page to make the right part of the mark.

Please note 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 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

[

Knu90

, chapter 23]. You will find, that marks are an issue for real experts. So if the expla-

nation above was at least more confusing than illuminative: Please don’t worry.

\@mkleft{left mark }

\@mkright{right mark }

\@mkdouble{mark }

\@mkboth{left mark }{right mark }

Sometimes inside classes and packages the marks for running heads should be filled up only

if automatic running heads are active (see option

automark

and command

\automark

on

page 241

). In the L

A

TEX standard classes only \@mkboth has been used for this. This command

is either \@gobbletwo, that simply destroys both mandatory arguments, or

\markboth

, a

command that fills up the left and left mark and the right mark. Packages like babel also

change \mkboth, i. e., to add language switching to the running head.

But if a class or package author only wants to change either the left mark or the right

mark

without the other one, a proper command is missing. Package scrlayer itself needs such

commands for the implementation of all cases of automatic running heads. So if command

\@mkleft

to fill up only the left mark or \@mkright to fill up only the right mark or \@mkdouble

Chapter 17: Defining Layers and Page Styles Using scrlayer

411

to fill up both marks with the same content is undefined while loading scrlayer, the package will

define them. Thereby the actual definition of \@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 \markleft, \markright, and

\markboth

.

For more information about manipulation of the contents of page styles see also

section 5.5

from

page 240

.

17.8. End User Interfaces

Package scrlayer provides an interface to define and manage (concurrent) end user interfaces.

Maybe future releases of KOMA-Script will provide parts of this by package scrbase and

remove those commands from scrlayer. But currently this part if scrlayer is very experimental,

so package scrlayer provides its own interface definition commands. Currently you should not

depend on correct working of auto-removing a concurrent end user interface. Instead you

should avoid using concurrent end user interfaces.

This section only describes the interface commands for defining end user interfaces. This

is not interesting for end users, but only for authors of end user interfaces. End users will

find information about the end user interfaces in the sections about the particular end user

interface, e.g.,

chapter 5

,

chapter 18

, and

chapter 19

.

\scrlayerInitInterface[interface name ]

Command \scrlayerInitInterface registers a new interface. The interface name must

be unique. If you try to initialise an already initialised interface an error will occur. This com-

mand is obligatory and mandatory for interfaces. It should be the first interface command and

therefore has been described first. If the optional argument is omitted, \@currname.\@currext

will be used instead. For classes and packages this will be the file name of the class or package

while loading the class or package. But you may use any sequence of characters with category

letter or other.

Chapter 17: Defining Layers and Page Styles Using scrlayer

412

forceoverwrite=simple switch

autoremoveinterfaces=simple switch

\scrlayerAddToInterface[interface name ]{command }{code }

\scrlayerAddCsToInterface[interface name ]{command sequence }{code }

One of the special features of end user interfaces is that they should register all interface depen-

dent commands (also known as macros). You may do this using \scrlayerAddToInterface.

If your interface generates macros not only at load time but also at run time or if the interface

name should not be the class’s or package’s name, you have to use the optional argument to

add the command to a dedicated interface. An error will occur, if the interface has not been

initialised before.

The first mandatory argument is the command

1

that should be added to the interface. If

the command can be added to the interface, it will be added to the interface, will be set to

\relax

and code will be executed. You can use, e.g., \newcommandcommand inside of code

to define command .

But when can a command be defined? If a command is undefined or \relax it can be

defined. If a command has already been defined and registered for another interface and if

KOMA-Script option autoremoveinterfaces has been switched on, the other interface will

be removed automatically and the new command will be set to \relax and will be registered

for the given interface. If a command has already been defined but is not part of another

interface and if KOMA-Script option forceoverwrite has been switched on, the command

will be set to \relax and will be registered for the given interface.

Command \scrlayerAddCsToInterface is similar to \scrlayerAddToInterface but does

not expect a command as first, mandatory argument, but a command sequence

2

.

\scrlayerOnAutoRemoveInterface[interface name ]{code }

Command \scrlayerOnAutoRemoveInterface registers code to be executed, if the inter-

face will be automatically removed (see

autoremoveinterfaces

prior in this section). This

may be used, e.g., to automatically destroy layers or page styles (see

\DestroyLayer

,

\DestroyPageStyleAlias

, and

\DestroyRealLayerPageStyle

).

1

The command consists of the backslash followed by a command sequence consisting of characters with category

code letter or one other character, or command consists of one active character (without backslash).

2

A command sequence may consist of any characters with category code letter or other.

Chapter 18: Additional Features of scrlayer-scrpage

413

Additional Features

v3.12

with package scrlayer-scrpage

Package scrlayer-scrpage provides features that have not been described in

chapter 5

of this

user guide’s

part I

. In general, the average user will not need those extensions and some of

them are only provided for compatibility with scrpage2.

18.1. Manipulation of Defined Page Styles

This section is an add-on to

section 17.7

. It describes features that may be to complicated for

beginners.

\GenericMarkFormat{name of the section level }

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

\chapter

also for the section level and

the subsection level, if the mark commands for those numbers have not been defined before

loading scrlayer. Thereby the package uses \@seccntmarkformat if such a command has been

defined, like the KOMA-Script classes do. Otherwise \@seccntformat will be used, which is

provided by the L

A

TEX kernel. The expected, mandatory argument of the command is the

name of a section level

, i. e., chapter or section 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.

Example: 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 stan-

dard L

A

TEX article class, package scrlayer defines the number mark commands

\sectionmarkformat

and \subsectionmarkformat using \GenericMarkFormat.

So you need to redefine only this single command:

\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}

Chapter 18: Additional Features of scrlayer-scrpage

414

The colour has been done using package xcolor. See the package manual for more

information about this.

Additionally a not visible strut has been used. Every complete L

A

TEX introduction

should explain the related command \strut.

A helper macro \numberbox has been defined for the formatting of the number

within a box. In the redefinition of \GenericMarkFormat this has been prefixed

by \protect to protect it from expansion. This is necessary because otherwise

the upper case letter conversion of \MakeUppercase that will be used for the

running head, would result in an ask for colours “BLACK” and “WHITE” instead

of “black” and “white” and those colours are undefined. Alternatively you may

define \numberbox using \DeclareRobustCommand* instead of \newcommand* and

then omit \protect (see [

Tea06

]).

If you’d do the same with a KOMA-Script class or with one of the L

A

TEX standard

classes book or report, you’d additionally have to redefine

\sectionmarkformat

and

\subsectionmarkformat

respectively

\chaptermarkformat

and

\sectionmarkformat

and too, because then these would not have been de-

fined using \GenericMarkFormat:

\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}

Chapter 18: Additional Features of scrlayer-scrpage