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

Hacks for Third-Party Packages by Package scrhack

Some packages from other authors could have problems with KOMA-Script. In my opinion

some packages could be improved. With some packages this makes only sense, if KOMA-Script

was used. With some other packages the package author has another opinion. Sometimes

proposals was never answered. Package scrhack contains all those improvement proposals for

other packages. This means, scrhack redefines macros of packages from other authors! The

redefinitions are only activated, if those packages were loaded. Users can prevent scrhack from

redefining macros of individual packages.

16.1. State of Development Note

Though this package is part of KOMA-Script for long time and though it has been used by

lot of users, there’s one problem with it. While redefinition of macros of foreign packages,

it depend on the exact definition an usage of those macros. This means additionally, that it

depends on dedicated releases of those packages. If a unknown release of such a package will

be used, scrhack eventually could not do the needed patch. Contrary, in extreme cases the

patch can cause errors and fault.

So scrhack has to be continuously modified to fit new releases of foreign packages and will

never be finished. Because of this scrhack will stay in beta state forever. Though the usage

will generally be a benefit, the correct function could not be guaranteed forever.

16.2. Early or late Selection of Options

All of what is described in

section 2.4

is generally applicable.

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

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

333

Chapter 16.

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-

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

334

Chapter 16.

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.

335

Chapter 17.

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.

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

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

with other classes.

336

Chapter 17.

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

\DeclareSectionNumberDepth

gives the class author the opportunity to define the relation-

ship explicitly.

337

Chapter 17.

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.

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

338

Chapter 17.

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.

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

339

Chapter 17.

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.

. . .

340

Chapter 17.

Table 17.1.: Options for the definition of layers (Continuation)

align=alignment characters

The alignment characters define the desired alignment of the layer. Each

alignment character

influences either, how argument length of option hoffset

or voffset will be used. Several alignment characters may be used together

(without comma or space) and will be interpreted in the order of occurrence. No

macros should be used here! Valid alignment character s are:

b

– align the layer at its bottom edge; the value of voffset is interpreted as the

distance from the top edge of the paper to the bottom edge of the layer.

c

– align the layer at its centre; the values of voffset and hoffset are interpreted

as the distance from the top left corner of the paper to the centre of the layer.

l

– align the layer at its left edge: the value of hoffset is interpreted as the distance

from the left edge of the paper to the left edge of the layer.

r

– align the layer at its right edge; the value of hoffset is interpreted as the

distance from the left edge of the paper to the right edge of the layer.

t

– align the layer at its top edge; the value of voffset is interpreted as the distance

from the top edge of the paper to the top edge of the layer.

area={hoffset }{voffset }{width }{height }

The composed option results in hoffset=hoffset ,

voffset=voffset

,

width=width

, height=height .

v3.18

backandforeground

This option removes any foreground or background restriction of the layer. Generally

usage of this option makes no sense, but it is provided for completeness of the user

interface. The option does not expect any value.

background

Print the layer only in the background, but not in the foreground. This makes a

background-only layer in opposite to the default of layers which are both, background

and foreground layers and therefore would be printed twice. The option does not

expect any value. By the default the attribute is not set.

. . .

341

Chapter 17.

Table 17.1.: Options for the definition of layers (Continuation)

bottommargin

The composed option sets hoffset, voffset, width, height, and align to hori-

zontally span the paper from the left edge to the right and vertically span the area

below the footer down to the bottom edge of the paper.

clone=layer name

The composed option sets all primary attributes of the layer to the same values as

the primary attributes of the layer with the given layer name . Note, that layer

name

has to be fully expandable and should expand to letters only. Some additional

characters are tolerated, but are not recommended!

contents=code

The code will be expanded whenever the layer is printed. So the code is what you

will see. Code validity is not checked. So errors in code may result in several failures

on each page, that prints the layer.

evenpage

Print the layer on even pages only, but not on odd pages. The option does not expect

any value. By the default the option is not set and therefore layers would be printed

on odd pages and on even pages. Note, that this attribute subsumes twoside.

v3.18

everypage

This is a combination of oddorevenpage and floatornonfloatpage. The option

does not expect any value.

everyside

This option removes any restriction of the layer to single side or double side printing.

This is also the default of layers. The option does not expect any value.

v3.18

floatornonfloatpage

This option removes any restriction of the layer to float or non-float pages. So the

layer will be printed independent of whether a page is a float page or not. This is

also the default of layers. The option does not expect any value.

floatpage

Print the layer on float pages only, but not on other pages. The option does not

expect any value. By the default the attribute is not set and therefore layers would

be printed on float pages and on non-float pages.

. . .

342

Chapter 17.

Table 17.1.: Options for the definition of layers (Continuation)

foot

The composed option sets hoffset, voffset, width, height, and align to hori-

zontally span the text area and vertically span the page footer defined by the new

L

A

TEX length \footheight.

footskip

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally span the text area and vertically span the distance between the text area and

the page footer (note, that this is not the same like \footskip).

foreground

Print the layer only in the foreground, but not in the background. This makes a

foreground-only layer in opposite to the default of layers which are both, background

and foreground layers and therefore would be printed twice. The option does not

expect any value. By the default the attribute is not set.

head

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally span the text area and vertically span the page head defined by usual L

A

TEX

length \headheight.

headsep

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally span the text area and vertically span the distance between the page head and

the text area.

height=length

Sets the height of the layer. Note, that length can either be a L

A

TEX length, declared

using \newlength, or a TEX length, declared using \newdimen or \newskip, a length

value like 10 pt, or a dimensional expression using +, -, /, *, (, and ). For more

information about valid dimensional expressions see [

Tea98

, section 3.5].

hoffset=length

Sets the offset of the layer (depending on align either left edge of the layer, middle

of the layer or right edge of the layer) from the left edge of the paper. See height

for more information about valid content of length .

. . .

343

Chapter 17.

Table 17.1.: Options for the definition of layers (Continuation)

innermargin

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally span the distance between the right edge of text area and the right edge of the

paper on even pages or the distance between the left edge of the paper and the left

edge of the text area on odd pages and vertically span the whole paper from the top

edge to the bottom edge.

leftmargin

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally span the distance between the left edge of the paper and the left edge of the

text area and vertically span the whole paper from the top edge to the bottom edge.

v3.19

mode=mode

The primary option defines the mode for the layer output. Default is mode=text.

The Baseline of the first text line will be placed the height of one standard text line

below the top edge of the layer. Therefore the text output will be top aligned in the

layer. In picture mode the layer spans a picture environment with the origin in

the bottom left corner of the layer. The also available raw mode current is the same

like text mode .

Changing the mode of a layer generally can move the contents. Additionally, i. e.,

picture mode

provides additional commands that result in errors with another mode .

Therefore, generally it makes no sense to change the mode of a layer after it’s initial

declaration!

nonfloatpage

Restricts the layer to pages, that are not float pages. The option does not expect any

value. By the default the attribute is not set and therefore layers would be printed

on float pages and on non-float pages.

v3.18

oddorevenpage

Removes any restriction of the layer to odd or even pages. So it will be printed

independently of whether a page is odd or even. This is also the default of layers.

The option does not expect any value.

oddpage

Print the layer on odd pages only, but not on even pages. The option does not expect

any value. By the default the option is not set and therefore layers would be printed

on odd pages and on even pages.

. . .

344

Chapter 17.

Table 17.1.: Options for the definition of layers (Continuation)

oneside

Print the layer in single-side mode only, but not in two-side mode. The option does

not expect any value. By the default the attribute is not set and therefore layers

would be printed in single-side and two-side mode.

outermargin

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally span the distance between the left edge of the paper and the left edge of the

text area on even pages or the distance between the right edge of the text area and

the right edge of the paper on odd pages and vertically span the whole paper from

the top edge to the bottom edge.

page

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally and vertically span the whole paper from the left edge to the right edge and

the top edge to the bottom edge.

v3.16

pretocontents=code

Value code will be added at the very beginning of the current value of attribute

contents

. So the new content will be generated in front of the already existing

content. For more information about the handling of code see option contents.

rightmargin

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally span the distance between the right edge of text area and the right edge of the

paper and vertically span the whole paper from the top edge to the bottom edge.

textarea

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally and vertically span the whole text area from the left edge to the right edge and

the top edge to the bottom edge.

topmargin

The composed option sets hoffset, voffset, width, height, and align to horizon-

tally span the whole page from the left edge to the right edge and vertically span

the distance between the top edge of the paper and the page head.

. . .

345

Chapter 17.

Table 17.1.: Options for the definition of layers (Continuation)

twoside

Print the layer in two-side mode only, but not in single-side mode. The option does

not expect any value. By the default the attribute is not set and therefore layers

would be printed in single-side and two-side mode.

v3.18

unrestricted

This option removes all output restrictions of the layer. It is a combination of

backandforground

, everyside, and floatornonfloatpage. The option does not

expect any value.

voffset=length

Sets the offset of the layer (depending on align either top edge of the layer, middle

of the layer or bottom edge of the layer) from the top edge of the paper. See height

for more information about valid content of length .

width=length

Sets the width of the layer. See height for more information about valid content of

length

.

\layerhalign

\layervalign

\layerxoffset

\layeryoffset

\layerwidth

\layerheight

These commands are valid during output of the layer’s contents only. So they can only be

used inside the code of option contents of the previously described commands. In this case

they give the effective alignment, position and dimension of the layer, that will be used for

the output. However, the effective dimension of the layer’s contents may differ, i. e., if the

contents are oversized or do not fill the layer completely.

The primary layer attribute align is mapped to \layerhalign

v3.19

and \layervalign. The

horizontal values l and r are copied to \layerhalign. The vertical values r and b are copied to

\layervalign

. The also horizontal and vertical value c is copied to both commands. If align

has contradictory values, only the last one is copied. Therefore the resulting \layerhalign is

either l, c, or r and the resulting \layervalign is either r, c, or b.

Redefinition of the commands to change the stored values is strictly forbidden and would

result in unpredictable issues.

346

Chapter 17.

\LenToUnit{length }

This

v3.19

command has been copied from eso-pic 2.0f. It converts lengths into multiples of

\unitlength

. It can be used everywhere L

A

TEX expects picture coordinates or \unitlength-

depending values. For more information see [

Nie15

] and the following descriptions of \putUR,

\putLL

, and \putLR. If the command is already defined, e. g., by loading eso-pic before scrlayer,

the package does not define it again.

It should be noted at this point that using package picture (see [

Obe09

]) supersedes

\LenToUnit

more or less. The package extends environment picture and the picture com-

mands to accept L

A

TEX lengths directly.

\putUL{content }

\putUR{content }

\putLL{content }

\putLR{content }

\putC{content }

You

v3.19

can use these commands inside the value of primary layer option contents, if the layer is

declared with mode=picture. In that case, \putUL places the content relative to the upper

left corner of the layer and therefore is the same like \put(0,\LenToUnit{\layerheight}).

\putUR

places the content relative to the upper right corner of the layer and therefore

is the same like \put(\LenToUnit{\layerwidth},\LenToUnit{\layerheight}). \putLL

places the content relative to the lower left corner of the layer and therefore is the same

like \put(0,0). \putLR places the content relative to the lower right corner and therefore

is the same like \put(\LenToUnit{\layerwidth},0). Last but not least \putC places the

content

relative to the centre of the layer.