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

Example: Mr McEnvy is one of your most important business partners, but every day you

receive correspondence from him. Before long you do not want to bother typing

his boring address again and again. Here scrlttr2 can help. Assume that all your

business partners have an entry in your partners.adr address file. If you now

have to reply to Mr McEnvy again, then you can save typing as follows:

\input{partners.adr}

\begin{letter}{\FLANN}

Your correspondence of today \dots

\end{letter}

Your TEX system must be configured to have access to your address file. Without

access, the \input command results in an error. You can either put your address

file in the same directory where you are running L

A

TEX, or configure your system

to find the file in a special directory.

\addrentry{last-name }{first-name }{address }{phone }{F1 }{F2 }{F3 }{F4 }{key }

Over the years people have objected that the \adrentry has only two free parameters. To cater

to this demand, there now exists a new command called \addrentry — note the additional

“d” — which supports four freely-definable parameters. Since TEX supports maximally nine

parameters per command, the comment parameter has fallen away. Other than this difference,

the use is the same as that of \adrentry.

Both \adrentry and \addrentry commands can be freely mixed in the adr files. However,

it should be noted that there are some packages which are not suited to the use of \addrentry.

For example, the adrconv by Axel Kielhorn can be used to create address lists from adr files,

but it has currently no support for command \addrentry. In this case, the only choice is to

extend the package yourself.

Besides the simple access to addresses, the address files can be easily used in order to write

circular letters. Thus, there is no requirement to access a complicated database system via

TEX.

Example: Suppose you are member of a society and want write an invitation for the next

general meeting to all members.

\documentclass{scrlttr2}

\begin{document}

\renewcommand*{\adrentry}[8]{

\begin{letter}{#2 #1\\#3}

\opening{Dear members,} Our next general meeting will be on

Monday, August 12, 2002. The following topics are \dots

\closing{Regards,}

\end{letter}

}

202

Chapter 4.

\input{members.adr}

\end{document}

If the address file contains \addrentry commands too, than an additional defini-

tion for \addrentry is required before loading the address file:

\renewcommand*{\addrentry}[9]{%

\adrentry{#1}{#2}{#3}{#4}{#5}{#6}{#7}{#9}%

}

In this simple example the extra freely-definable parameter is not used, and there-

fore \addrentry is defined with the help of \adrentry.

With some additional programming one can let the content of the letters depend on the

address data. For this the free parameters of the \adrentry and and \addrentry commands

can be used.

Example: Suppose the 5

th

parameter of the \adrentry command contains the gender of a

member (m/f), and the 6

th

parameter contains what amount of subscription has

not yet been paid by the member. If you would like to write a more personal

reminder to each such member, then the next example can help you:

\renewcommand*{\adrentry}[8]{

\ifdim #6pt>0pt\relax

% #6 is an amount greater than 0.

% Thus, this selects all members with due subscription.

\begin{letter}{#2 #1\\#3}

\if #5m \opening{Dear Mr.\,#2,} \fi

\if #5f \opening{Dear Mrs.\,#2,} \fi

Unfortunately we have to remind you that you have

still not paid the member subscription for this

year.

Please remit EUR #6 to the account of the society.

\closing{Regards,}

\end{letter}

\fi

}

As you can see, the letter text can be made more personal by depending on attributes of

the letter’s addressee. The number of attributes is only restricted by number of two free

parameters of the \adrentry command, or four free parameters of the \addrentry command.

203

Chapter 4.

\adrchar{initial letter }

\addrchar{initial letter }

As already mentioned above, it is possible to create address and telephone lists using adr

files. For that, the additional package adrconv by Axel Kielhorn (see [

Kie10

]) is needed. This

package contains interactive L

A

TEX documents which help to create those lists.

The address files have to be sorted already in order to obtain sorted lists. It is recommended

to separate the sorted entries at each different initial letter of last name . As a separator,

the commands \adrchar and \addrchar can be used. These commands will be ignored if the

address files are utilized in scrlettr2.

Example: Suppose you have the following short address file:

\adrchar{A}

\adrentry{Angel}{Gabriel}

{Cloud 3\\12345 Heaven’s Realm}

{000\,01\,02\,03}{}{}{archangel}{GABRIEL}

\adrentry{Angel}{Michael}

{Cloud 3a\\12345 Heaven’s Realm}

{000\,01\,02\,04}{}{}{archangel}{MICHAEL}

\adrchar{K}

\adrentry{Kohm}{Markus}

{Freiherr-von-Drais-Stra\ss e 66\\68535 Edingen-←

Neckarhausen}

{+49~62\,03~1\,??\,??}{}{}{no angel at all}

{KOMA}

This address file can be treated with adrdir.tex of the adrconv package [

Kie10

].

The result should look like this:

A

Angel, Gabriel

Cloud 3

12345 Heaven’s Realm

(archangel)

gabriel

000 01 02 03

Angel, Michael

Cloud 3a

12345 Heaven’s Realm

(archangel)

michael

000 01 02 04

204

Chapter 4.

The letter in the page header is created by the \adrchar command. The definition

can be found in adrdir.tex.

More about the adrconv package can be found in its documentation. There you should also

find information about whether the current version of adrconv supports the \addrentry and

\addrchar

commands. Former versions only know the commands \adrentry and \adrchar.

205

Chapter 5.

Adapting

v3.12

Page Headers and Footers with scrlayer-scrpage

Until version 3.11b of KOMA-Script, package scrpage2 has been the recommended way to

customise page headers and footers beyond the options provided by the page styles headings,

myheadings

, plain, and empty of the standard KOMA-Script classes. Until 2001 there was

also package scrpage as a supported solution for the same purpose. It was then made obsolete

and in 2013, more than ten years later, it was finally removed from the regular KOMA-

Script distribution.

In 2013 package scrlayer became a basic module of KOMA-Script. That package provides

a layer scheme and a new page style scheme based upon the layer scheme. Nevertheless, the

flexibility it provides and the resulting complexity may be too demanding for the average user

to handle. More about scrlayer may be found in

chapter 17

of

part II

. Potential problems with

the controllability of scrlayer apart, there are lots of users who are already familiar with the

user interface of package scrpage2.

As a consequence the additional package scrlayer-scrpage provides a user interface, which is

largely compatible with scrpage2 and based on scrlayer. Thus, if you are already familiar with

scrpage2 and refrain from using dirty tricks, like calling internal commands of scrpage2 directly,

it should be easy for you to use scrlayer-scrpage as a drop-in replacement. Most examples

covering scrpage2 in L

A

TEX books or online resources should also work with scrlayer-scrpage

either directly or with only minor code changes provided that they stick to the standard

interfaces.

Apart from the aforementioned KOMA-Script packages, you could in principle also use

fancyhdr (see [

vO04

]) in conjunction with a KOMA-Script class. However, fancyhdr has no

support for several KOMA-Script features, e. g., the element scheme (see \setkomafont,

\addtokomafont

, and \usekomafont in

section 3.6

, from

page 53

) or the configurable num-

bering format for dynamic headers (see option numbers and, e. g., \chaptermarkformat in

section 3.16

,

page 88

and

page 99

). Hence, if you are using a KOMA-Script class, the usage

of package scrlayer-scrpage is recommended. Of course you can use scrlayer-scrpage with other

classes, namely the L

A

TEX standard classes, too.

Besides the features described in this chapter, scrlayer-scrpage provides several more that

are likely only of minor interest to the average user and for this reason are described from

page 361

onwards in

chapter 18

of

part II

. Nevertheless, should the options described in

part I

be insufficient for your purposes you are encouraged to examine

chapter 18

.

5.1. Early or late Selection of Options

All of what is described in

section 2.4

is generally applicable.

206

Chapter 5.

5.2. Head and Foot Height

The L

A

TEX standard classes do not use the page footer a lot and if they do use it, they put the

contents into a \mbox which results in the footer being a single text line. This is probably the

reason that L

A

TEX itself does not have a well-defined foot height. Actually there is \footskip

giving the distance between the last base line of the text area and the base line of the footer.

However, if the footer consists of more than one text line, there is no definite statement whether

this length should be the distance to the first or the last base line of the footer.

Despite the fact that the page header of the standard classes will also be put into a horizontal

box and therefore is a single text line too, L

A

TEX indeed has a length to setup the height of

the page header. The reason for this may be that the height will be needed to determine the

start of the text area.

\footheight

\headheight

The package scrlayer introduces \footheight as a new length similar to \headheight of the

L

A

TEX kernel. Additionally scrlayer-scrpage interprets \footskip to be the distance from the

last possible base line of the text area to the first normal base line of the footer. Package

typearea interprets footheight in the same way. So typearea’s foot height options may also be

used to setup the values for packages scrlayer and scrlayer-scrpage. See option footheight and

footlines

in

section 2.6

,

page 42

) and option footinclude at

page 38

of the same section.

If you do not use package typearea, you should setup the head and foot height using the

lengths directly where necessary. At least for the head package geometry provides similar

settings. If you setup a head or foot height that is too small for the effective content,

scrlayer-scrpage will try to adjust the corresponding lengths properly. Furthermore, it will

warn you and give you additional information about the changes and proper settings you may

use yourself. The automatic changes will become valid immediately after the need for them

has been detected. They will never be removed automatically, however, even if content with

a lower height requirement should be detected at a later point in time.

5.3. Text Markup

What is described in

section 3.6

applies, mutatis mutandis. Names, defaults, and meanings of

the individual items are listed in

table 5.1

.

207

Chapter 5.

Table 5.1.: Elements of scrlayer-scrpage whose type style can be changed with KOMA-Script command

\setkomafont

or \addtokomafont and the default of those, if they have not been defined

before loading scrlayer-scrpage

footbotline

Horizontal line below the footer of a page style defined using scrlayer-scrpage. The

font will be used after \normalfont and the fonts of elements pageheadfoot and

pagefootpagefoot

. It is recommended to use this element for colour changes only.

Default: empty

footsepline

Horizontal line above the footer of a page style defined using scrlayer-scrpage. The

font will be used after \normalfont and the fonts of elements pageheadfoot and

pagefootpagefoot

. It is recommended to use this element for colour changes only.

Default: empty

headsepline

Horizontal line below the header of a page style defined using scrlayer-scrpage. The

font will be used after \normalfont and the fonts of elements pageheadfoot and

pageheadpagehead

. It is recommended to use this element for colour changes only.

Default: empty

headtopline

Horizontal line above the header of a page style defined using scrlayer-scrpage. The

font will be used after \normalfont and the fonts of elements pageheadfoot and

pageheadpagehead

. It is recommended to use this element for colour changes only.

Default: empty

pagefoot

Contents of the page footer of a page style defined using scrlayer-scrpage. The font

will be used after \normalfont and the font of element pageheadfoot.

Default: empty

pagehead

Contents of the page header of a page style defined using scrlayer-scrpage. The font

will be used after \normalfont and the font of element pageheadfoot.

Default: empty

. . .

208

Chapter 5.

Table 5.1.: Elements whose type style can be changed (continuation)

pageheadfoot

Contents of the page header or footer of a page style defined using scrlayer-scrpage.

The font will be used after \normalfont.

Default: \normalcolor\slshape

pagenumber

Pagination set with \pagemark. If you redefine \pagemark, you have to take care

that your redefinition also uses \usekomafont{pagenumber}!

Default: \normalfont

5.4. Usage of Predefined Page Styles

The easiest way to your desired design for page header and footer with scrlayer-scrpage is to

use one of the predefined page styles.

scrheadings

plain.scrheadings

Package scrlayer-scrpage provides two page styles, which may be reconfigured to meet your

individual reqirements. Let’s first of all discuss page style scrheadings which has been de-

signed as a style using running heads. Its defaults are similar to the page style headings

of the L

A

TEXstandard classes or the KOMA-Script classes. What exactly gets printed in the

header or footer can be configured via the commands and otions described hereafter.

The second page style to be mentioned here is plain.scrheadings, which has been designed

to be a style with no running head. Its defaults are very similar to page style plain of L

A

TEX’s

standard classes or the KOMA-Script classes. The following will describe the commands and

options you may use to adjust the contents of the header and footer .

You could of course configure scrheadings to be a page style without a running head

and plain.scrheadings to be a page style using running heads. It is, however, far

more expedient to adhere to the conventions mentioned above, if for the only reason that

both page styles mutually influence one another. Once you have opted to apply one of

these page styles, scrheadings will become accessible as headings and the page style

plain.scrheadings

will become accessible as plain. Thus, if you use a class or package that

automatically switches between headings and plain, you only need to select scrheadings

or plain.scrheadings once and the switching class or package will then switch between

scrheadings

and plain.scrheadings without even being aware of these page styles. Patches

or other adaptions of classes (or packages) will not be necessary. This pair of page styles may

thus serve as a drop-in replacement for headings and plain. Should additional similar pairs

be required I’d like to point you to

section 18.2

in

part II

for further reference.

209

Chapter 5.

For users of the older scrpage2, I’d like to mention that, for compatibility with scrpage2,

page style plain.scrheadings may also be used under its alias name of scrplain.

\lehead[plain.scrheadings’s content ]{scrheadings’s content }

\cehead[plain.scrheadings’s content ]{scrheadings’s content }

\rehead[plain.scrheadings’s content ]{scrheadings’s content }

\lohead[plain.scrheadings’s content ]{scrheadings’s content }

\cohead[plain.scrheadings’s content ]{scrheadings’s content }

\rohead[plain.scrheadings’s content ]{scrheadings’s content }

The contents of the header of page style plain.scrheadings and scrheadings can be defined

using these commands. Thereby the optional argument defines the content of an element

of page style plain.scrheadings, while the mandatory argument sets the content of the

corresponding element of page style scrheadings.

Contents of left — so called even — pages can be set with \lehead, \cehead, and \rohead.

Remark: The “e” at the second position of the commands’ names means “even”.

Contents of right — so called odd — pages can be set with \lohead, \cohead, and \rohead.

Remark: The “o” at the second position of the commands’ names means “odd”.

Please note that there are only odd pages within single side layouts independent of whether

or not they have an odd page number.

Each header consists of a left aligned element that will be defined by \lehead respectively

\lohead

. Remark: The “l” at the first position of the commands’ names means “left aligned”.

Similarly each header has a centred element that will be defined by \cehead respectively

\cohead

. Remark: The “c” at the first position of the command’ names means “centred”.

Similarly each header has a right aligned element that will be defined by \rehead respec-

tively \rohead. Remark: The “r” at the first position of the commands’ names means “right

aligned

”.

However, these elements do not have their own font attributes that may be changed using

commands \setkomafont and \addtokomafont (see

section 3.6

,

page 53

), but are grouped

in an element named pagehead. And before the font of that element additionally the font of

element pageheadfoot will be used. See

table 5.1

for the font default of these elements.

The semantics of the described commands within two-sided layouts are also sketched in

figure 5.1

.

Example: Assume you’re writing a short article and you want the title of that article to be

shown left aligned and the author’s name to be shown right aligned at the page

head. You may for example use:

\documentclass{scrartcl}

\usepackage{scrlayer-scrpage}

\lohead{John Doe}

\rohead{Page style with \KOMAScript}

\pagestyle{scrheadings}

210

Chapter 5.

\lehead

\rehead

\cehead

\lohead

\rohead

\cohead

\ihead

\chead

\ohead

6

6

6

6

6

6

Figure 5.1.: The meaning of the commands to define the contents of the page head of the page styles

sketched on a schematic double page

\begin{document}

\title{Page styles with \KOMAScript}

\author{John Doe}

\maketitle

\end{document}

But what happens: On the first page there’s only a page number at the page foot,

but the header is empty!

The explanation is very easy. Document class scrartcl switches to page style plain

for the page with the title head. After command \pagestyle{scrheadings}

in the preamble of the short document this will actually result in page style

plain.scrheadings

. Using a KOMA-Script class the default of this page style

is an empty page header and a page number in the footer. In the example

code the optional arguments of \lohead and \rohead are omitted. So page style

plain.scrheadings

remains unchanged as default and the result for the first page

is indeed correct.

Please add some text below \maketitle until a second page will be printed. Al-

ternatively you may just add \usepackage{lipsum} into the document preamble

and \lipsum below \maketitle. You will see that the head of the second page

will show the author and the document title as we wanted.

To see the difference you should also add an optional argument to \lohead and

\rohead

containing some content. To do so, change the example above:

\documentclass{scrartcl}

\usepackage{scrlayer-scrpage}

\lohead[John Doe]

{John Doe}

\rohead[Page style with \KOMAScript]

{Page style with \KOMAScript}

\pagestyle{scrheadings}

\begin{document}

\title{Page styles with \KOMAScript}

211

Chapter 5.

\author{John Doe}

\maketitle

\end{document}

Now, you also get a page header above the title head of the first page. That

is because you have reconfigured page style plain.scrheadings with the two

optional arguments. Most of you will also recognise that it would be better to

leave this page style unchanged, because the running head above the document

title is certainly annoying.

Allow me an important note: You should never put a section heading or section number

directly into the page head using a new declaration by one of these commands. This could

result in a wrong number or heading text in the running head, because of the asynchronous

page generation and output of TEX. Instead you should use the mark mechanism and ideally

you should use it together with the automatism described in the following section.

\lehead*[plain.scrheadings’s content ]{scrheadings’s content }

\cehead*[plain.scrheadings’s content ]{scrheadings’s content }

\rehead*[plain.scrheadings’s content ]{scrheadings’s content }

\lohead*[plain.scrheadings’s content ]{scrheadings’s content }

\cohead*[plain.scrheadings’s content ]{scrheadings’s content }

\rohead*[plain.scrheadings’s content ]{scrheadings’s content }

The previously described commands have also a version with star

v3.14

that differs only if you omit

the optional argument plain.scrheadings’s content . In this case the version without star

does not change the content of plain.scrheadings. The version with star on the other hand

uses the obligatory argument scrheading’s content also as default for plain.scrheadings.

So, if both arguments should be the same, you can simply use the star version with the

obligatory argument only.