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

16.3. Usage of tocbasic

In the early days of KOMA-Script users asked for handling lists of floats, that will be generated

using package float, like list of figures and list of tables, that are generated by KOMA-Script

Chapter 16: Hacks for Third-Party Packages by Package scrhack

380

itself. At that time the KOMA-Script author contacted the author of float, to submit a pro-

posal of an interface with support for such an extention. A somehow modified version of that

interface has been implemented with commands \float@listhead and \float@addtolists.

Sometimes later it has appeared, that those two commands were not flexible enough to

support all of the comprehensive features supported by KOMA-Script. Unfortunately the

author of float has finalized the development already, so nobody should expect furthor changes

of this package.

Other package authors have also inherited these commands. Thereby it appeared, that the

implementation in some packages, even in package float, will need a certain package loading

order, though all these packages are not related to each other. Wrong loading order could

result in an error or break the functionality of the commands.

To clear all these disadvantages and problems, KOMA-Script officially does not support

this old interface any more. Instead, KOMA-Script warns if the old interface is used. At the

same time package tocbasic (see

chapter 15

) has been designed and implemented as a central

interface for management of table of contents, lists of floats and similar lists. Usage of this

package provides much more advantages and features than the two old commands that have

been mentioned above.

Though the effort using that package is very small, the authors of most of the packages,

that are using the old interface, have not done so currently. Because of this scrhack contains

appropriate modifications of packages float, floatrow, and listings. Loading scrhack is enough

to make these packages recognize not only setting of KOMA-Script option

listof

, but also

language switching of package babel. More information about the features provided by the

changeover to package tocbasic can be found in

section 15.2

.

If the modification for any of the packages is not wanted or causes problems, then it can

be deactivated selectively with option float=false, floatrow=false, or listings=false.

Please note that changing these options after loading the corresponding package would not do

it!

16.4. Incorrect Expectations to \@ptsize

Some packages always expect that the class-internal macro \@ptsize is not only defined but

also expands to an integer. For compatibility, KOMA-Script defines \@ptsize even if the

basic font size is neither 10 pt nor 11 pt nor 12 pt. KOMA-Script also provides non-integer

font sizes. So \@ptsize can expand to a non-integer number, too.

Package setspace is one of the packages that fail with non-integer number expansion of

\@ptsize

. Additionally the line stretching of that package always depends on the basic font

size even if setting is made in the context of another font size. Package scrhack solves both

problems by redefining \onehalfspacing and \doublespacing using always the current font

size while setting the stretch.

If the modification for the package is not wanted or causes problems, then it can be deacti-

Chapter 16: Hacks for Third-Party Packages by Package scrhack

381

vated selectively with option setspace=false. Please note that changing these option after

loading setspace would not do it! If you use setspace with either option onehalfspacing or

doublespacing

you have to load scrhack before it.

16.5. Special Case hyperref

Before version 6.79h package hyperref set the link anchors after instead of before the heading of

star version commands like

\part*

,

\chapter*

, and so on. In the meantime this problem have

been solved at the KOMA-Script author’s suggestion. But because the KOMA-Script author

was not patient enough to wait more than a year for the change of hyperref, a corresponding

patch has been added to scrhack. This can be deactivated by hyperref=false. Nevertheless,

it is recommended to use the current hyperref release. In this case scrhack does automatically

deactivate the not longer needed patch.

16.6. Inconsistent Handling of \textwidth and \textheight

Package lscape defines an environment landscape to set the page contents but not head and

foot landscape. Inside this environment it changes \textheight to the value of \textwidth,

but it does not change \textwidth to the former value of \textheight. This is inconsistent.

As far as I know, \textwidth is unchanged because setting it to \textheight could blame

other packages or user commands. But changing \textheight could also blame other packages

or user commands and indeed it breaks, e. g., showframe and scrlayer. So best would be, not to

change \textheight, too. scrhack uses package xpatch (see [

Gre12

]) to modify the environment

start macro \landscape appropriately.

If the modification for the package is not wanted or causes problems, then it can be de-

activated selectively with option lscape=false. Please note that changing this option after

loading lscape has an effect only, if it is not false while loading lscape respectively scrhack, if

scrhack is loaded after lscape.

Please note, pdflscape also uses lscape and therefore is influenced by scrhack, too.

Chapter 17: Defining Layers and Page Styles Using scrlayer

382

Defining Layers and Page Styles Using scrlayer

Most users of graphics software already know layer models for pages or working sheets. L

A

TEX

itself does not know layers, but there are already packages like eso-pic or textpos, that provide

a kind of background or foreground layer. scrlayer is another package, that provides such

background and foreground layers, but in difference to the other packages mentioned above

these layers are part of the page style definition. With this you may simply switch between

usage of layers by switching the page style.

To do so, the package also supports a low level interface to define page styles using a layer

stack, to put layers onto a page style’s layer stack, to put layers at the lowest position of a

page style’s layer stack, to put layers before or after a layer of a page style’s layer stack, to

remove a layer from a page style’s layer stack and to remove doublets of layers of a page style’s

layer stack. In short words: The page style interface of scrlayer provides commands to define

layer-stack-based page styles and to manage those layer stacks.

Nevertheless, using the layers directly is recommended for advanced users only. End user

interfaces for beginners or average users are provided by additional packages, that load scrlayer

on their own. See

chapter 5

in

part I

of this manual.

17.1. State of Development Note

Development of this package has not been finished yet. Parts of the package are even still

experimental. Because of this, especially internal functionality may be changed in future.

Most likely the package will be extended. And because of the early state of development, you

should not expect a complete and finished user manual. Nevertheless, this manual, which is

recommended for advanced users and developers, describes the current state of development

and the released parts of scrlayer. Everything, not documented here, should not be used for

anything else but testing.

17.2. Early or late Selection of Options

All of what is described in

section 2.4

is generally applicable. So if you have alread read and

understood

section 2.4

you can switch to

section 17.3

,

page 383

.

In this section a peculiarity of KOMA-Script is presented, which, apart from the scrlayer

package, is also relevant to other KOMA-Script packages and classes. Such that the user can

find all information corresponding to a single package or a single class in the relevant chapter,

this section is found almost identically in several chapters. Users who are not only interested

in a particular package or class, but wish to gain an overview of KOMA-Script as a whole,

may read the section in one chapter and may thereafter skip it wherever coming across it in

the document.

Chapter 17: Defining Layers and Page Styles Using scrlayer

383

\documentclass[option list ]{KOMA - Script class }

\usepackage[option list ]{package list }

In L

A

TEX, provision is made for the user to pass class options as a comma-separated list of

keywords as optional arguments to \documentclass. Apart from being passed to the class,

these options are also passed on to all packages which can understand the options. Provision

is also made for the user to pass optional arguments as a comma-separated list of keywords

as optional arguments to \usepackage. KOMA-Script expands

v3.00

the option mechanism for the

KOMA-Script classes and various packages to use further possibilities. Thus, most KOMA-

Script options can also take a value. An option may have not only the form Option , but

may also have the form option =value . Apart from this difference \documentclass and

\usepackage

function the same in KOMA-Script as described in [

Tea05b

] or any introduction

to L

A

TEX, for example [

OPHS11

].

You should note, that in opposite to the interface described below the options interface of

\documentclass

and \usepackage is not robust. So commands, lengths, counters and such

constructs may break inside the optional argument of these commands. Because of this, the

usage of a L

A

TEX length inside the value of an option would cause an error before KOMA-Script

can get the control over the option execution. So, if you want to use a L

A

TEX length, counter

or command a part of the value of an option, you have to use

\KOMAoptions

or

\KOMAoption

.

These commands will be described next.

\KOMAoptions{option list }

\KOMAoption{option }{value list }

KOMA-Script

v3.00

offers most class and package options the opportunity to change the value of

options even after loading of the class or package. One may then change the values of a list of

options at will with the \KOMAoptions command. Each option in the option list has the

form option =value .

Some options also have a default value. If one does not give a value, i. e., gives the option

simply in the form option , then the default value will be used.

Some options can assume several values simultaneously. For such options there exists the

possibility, with the help of \KOMAoption, to pass a single option a list of values. The

individual values are given as a comma-separated value list .

To implement this possibility KOMA-Script uses the commands

\FamilyOptions

and

\FamilyOption

with the family “KOMA”. For more information in these commands see

part II

,

section 12.2

,

page 313

.

17.3. Some Generic Information

The package needs some generic information about the class. Class authors may help scrlayer

by setting this information. Otherwise the package tries to detect the information itself. This

Chapter 17: Defining Layers and Page Styles Using scrlayer

384

works, e.g., for the standard classes and the KOMA-Script classes. But it may or may not fail

with other classes.

This section describes some of the information, that class authors may provide. Generally

users need not to care about this.

\if@chapter then code \else else code \fi

If \if@chapter is \iftrue, scrlayer will additionally consider the chapter level, e.g., processing

option

automark

. If it is defined, but differs from \iftrue, only part, section, subsection,

sub. . . subsection, paragraph, subparagraph, sub. . . subparagraph will be considered. If the

macro is not defined, scrlayer searches for

\chapter

. If

\chapter

is defined and not \relax,

scrlayer will define \if@chapter to \iftrue, otherwise \if@chapter will become \iffalse.

\if@mainmatter then code \else else code \fi

Classes like book define

\frontmatter

,

\mainmatter

, and

\backmatter

. They also use

\if@mainmatter

to distinguish whether or not the current matter is the main matter. Classes

like report and article do not have

\frontmatter

,

\mainmatter

, or

\backmatter

and therefore

also do not have \if@mainmatter.

For scrlayer it’s easier not to test always for the existence of the matter commands, but to

use \if@mainmatter even with classes like report and article, simply set to \iftrue. So if

\if@mainmatter

is not defined, it will be defined to \iftrue.

Some classes have

\frontmatter

,

\mainmatter

, or

\backmatter

but not \if@mainmatter.

In this case scrlayer also defines \if@mainmatter to be \iftrue and it extends definition

of

\frontmatter

,

\mainmatter

, and

\backmatter

to set \if@mainmatter properly. Other

matter commands are not known, not tested, and not extended. So if there are other matter

commands scrlayer needs help of the class author to set \if@mainmatter correctly.

\DeclareSectionNumberDepth{level name }{level depth }

Generally each section level is related to an integer number indicating its depth in the docu-

ment structure. L

A

TEX needs this to manage hierarchic section levels. But normally only the

document class, that defines the section commands, itself knows that level depth of a section

level and uses these numerical values inside the corresponding commands, when needed.

But scrlayer also needs information about the section hierarchy.

With command

\DeclareSectionNumberDepth

you can map the name of a heading level to a level

depth

. With standard class book, e.g., the level name could be part, chapter, section,

subsection

, subsubsection, paragraph, or subparagraph and the corresponding level

depth

s would be -1, 0, 1, 2, 3, 4, and 5.

Package scrlayer tries to determine the level depth s on its own while loading and again

while \begin{document}. But, if it fails, i. e., if completely different section commands are

used, it would be useful, to be able to define the relationship explicitly. For such cases

Chapter 17: Defining Layers and Page Styles Using scrlayer

385

\DeclareSectionNumberDepth

gives the class author the opportunity to define the relation-

ship explicitly.

17.4. Declaration of Layers

A layer is a kind of virtual sheet of transparent paper (in opposite to a physical sheet of paper).

One layer is stacked onto another layer and opaque material on one layer may hide material

on the layers below. The stack of all layers together makes the physical page. Package scrlayer

provides two such layer stacks for each page: a background layer stack and a foreground layer

stack. The background layer stack is behind the normal page contents, the foreground layer

stack is above the normal page contents. So the normal contents is a kind of a separating

layer between the background layer stack and the foreground layer stack.

A layer has several attributes, which are the answers to some basic questions:

Is the layer part of the background or the foreground? During page building background

layers will be printed first, followed by the main contents and the foreground layers.

Therefore, in the output the background layers show up behind the main contents and

the foreground layers in front of the main contents. By default, a layer is both, a back-

ground layer and a foreground layer and therefore will be printed twice. Normally, it

makes sense to restrict the layer in this aspect.

What is the position of the layer? There are some attributes to define the horizontal and

the vertical position of a layer.

What is the size of the layer? As for the position there are several attributes to define the

width and height of a layer. So a layer can also be smaller or larger than the paper and

it can be placed everywhere on the paper.

How is a layer aligned on the paper? This question is answered by the alignment attribute.

The horizontal position can be relative from the left edge of the paper either to the left

edge of the layer or to the centre of the layer or to the right edge of the layer. Also the

vertical position can be relative from the to edge of the paper either to the top edge of

the layer or to the centre of the layer or to the bottom edge of the layer.

Is the layer intended for text or picture output? This question is also related to the posi-

tion. For picture output users often expect the origin at the bottom left corner of the

layer. But this would not be suitable for text output. So the origin of a text layer is the

height of a standard text line below the top left corner of the layer. Picture layers on the

other hand span a picture environment and provide addition positioning commands.

Should the layer be printed on left or right pages? By default a layer will be printed on

both, left and right pages. Note, that L

A

TEX names left pages as even pages and right

pages as odd pages and that there are no left or even pages in single-sided mode.

Chapter 17: Defining Layers and Page Styles Using scrlayer

386

Should the layer be printed in single-side mode or two-side mode? By default a layer will

be printed in both, single-side mode and two-side mode. Nevertheless, an even page

layer will never be printed in single-side mode and therefore is not really a two-side

mode layer.

Should the layer be printed on float pages or non-float pages? L

A

TEX produces float pages

for float environments like tables or figures, if they are allowed to be printed on a page

without normal page contents (see option p for figure or table). So from some point of

view a float page is a page, that may itself flow. Non-float pages are not pages without

floats, but pages, that are not float pages. They may contain floats inside the text, on

the top of the page, or on the bottom of the page. Very large floats may seem to be

page floats, while in reality they are top floats.

What are the contents of the layer? The corresponding attribute are the commands that

produce the output.

So we have eight questions that immediately result in attributes yet. Below in this manual we

will describe additional attributes. However, they are just defined for convenience and can be

expressed by a combination of these primary attributes.

\DeclareLayer[option list ]{layer name }

\DeclareNewLayer[option list ]{layer name }

\ProvideLayer[option list ]{layer name }

\RedeclareLayer[option list ]{layer name }

\ModifyLayer[option list ]{layer name }

These commands can be used to define a layer. The layer name has to be fully expandable

and should expand to letters only. Some additional characters are tolerated, but are not

recommended.

Command \DeclareLayer does not care whether or not a layer with the given layer name

already exists. It will under all circumstances define the layer with the attribute defined by

the option list . An option can be either a key or a key followed by an equal sign followed

by a value. Several options may be concatenated to a option list and have to be separated

by comma. If you’d like to have a comma or a white space inside the value of an option, you

should put the value inside curly brackets. See

table 17.1

for more information on keys, values,

and the corresponding attributes.

In contrast to \DeclareLayer using \DeclareNewLayer results in an error, if a layer with

the same layer name already exists. So you may prevent yourself using the same layer name

more than once by mistake. This would be useful, e. g., if a class or package also defines layers

internally.

If you use \ProvideLayer instead of \DeclareLayer, the declaration will be ignored in case

a layer with the same layer name already exists. It could be paraphrased by: declare the layer

only if it has not been declared already.

Chapter 17: Defining Layers and Page Styles Using scrlayer

387

If an existing layer should be redefined, \RedeclareLayer or \ModifyLayer can be used.

\RedeclareLayer

would simply define the layer as if it would be defined newly. In difference

to this, \ModifyLayer would change only those attributes, that are represented by an option

of the option list . All other attributes will stay unchanged and will not be reset to the

initial default value. Using either \RedeclareLayer or \ModifyLayer will result in an error,

in case there has not been a layer with layer name defined before.

Table 17.1.: Options for the definition of page layers with description of the corresponding layer at-

tribute

v3.16

addcontents=Code

Value code will be added (or appended) at the very end of the current value of

attribute contents. So the new content will be generated behind the end of the

already existing content. For more information about the handling of code see

option contents.

v3.16

addheight=additional height

The current value of attribute height will be increased by the value of this option.

You can use the same kind of values as for height.

v3.16

addhoffset=additional horizontal offset

The current value of attribute hoffset will be increased by the value of this option.

You can use the same kind of values as for hoffset.

v3.16

addvoffset=additional vertical offset

The current value of attribute voffset will be increased by the value of this option.

You can use the same kind of values as for voffset.

v3.16

addwidth=additional width

The current value of attribute width will be increased by the value of this option.

You can use the same kind of values as for width.

. . .