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

4.22. Address Files and Circular Letters

When people write circular letters one of the more odious tasks is the typing of many different

addresses. The class scrlttr2 provides basic support for this task.

\adrentry{last-name }{first-name }{address }{phone }{F1 }{F2 }{comment }{key }

The class scrlttr2 supports the use of address files which contain address entries, very useful

for circular letters. The file extension of the address file has to be .adr. Each entry is an

\adrentry

command with eight parameters, for example:

\adrentry{McEnvy}

{Flann}

{Main Street 1\\ Glasgow}

{123 4567}

{male}

{}

{niggard}

{FLANN}

The 5

th

and 6

th

elements, F1 and F2, can be used freely: for example, for the gender, the

academic grade, the birthday, or the date on which the person joined a society. The last

parameter key should only consist of more than one uppercase letters in order to not interfere

with existing TEX or L

A

TEX commands.

Chapter 4: The New Letter Class scrlttr2

221

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}

Chapter 4: The New Letter Class scrlttr2

222

}

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

Chapter 4: The New Letter Class scrlttr2

223

\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

Chapter 4: The New Letter Class scrlttr2

224

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.

Chapter 5: Adapting Page Headers and Footers with scrlayer-scrpage

225

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 57

) or the configurable num-

bering format for dynamic headers (see option

numbers

and, e. g.,

\chaptermarkformat

in

section 3.16

,

page 93

and

page 105

). 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 413

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. So if you have alread read and

understood

section 2.4

you can switch to

section 5.2

,

page 227

.

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

Chapter 5: Adapting Page Headers and Footers with scrlayer-scrpage

226

scrlayer-scrpage 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.

\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

,

Chapter 5: Adapting Page Headers and Footers with scrlayer-scrpage

227

section 12.2

,

page 313

.

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 43

) and option

footinclude

at

page 40

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. So if you have alread read and

understood

section 3.7

you can switch to

page 230

. But you should have a look at

table 5.1

,

page 228

.

L

A

TEX offers different possibilities for logical and direct markup of text. Selection of the font

family commands, as well as choosing the font size and width is supported. More information

about the standard font facilities may be found at [

OPHS11

], [

Tea05b

], and [

Tea05a

].

Chapter 5: Adapting Page Headers and Footers with scrlayer-scrpage

228

\setkomafont{element }{commands }

\addtokomafont{element }{commands }

\usekomafont{element }

With

v2.8p

the help of the two commands \setkomafont and \addtokomafont, it is possible to

define the commands that change the characteristics of a given element . Theoretically, all

possible statements including literal text could be used as commands . You should, however,

absolutely limit yourself to those statements that really switch only one font attribute. This

will usually be the commands \normalfont, \rmfamily, \sffamily, \ttfamily, \mdseries,

\bfseries

, \upshape, \itshape, \slshape, and \scshape, as well as the font size commands

\Huge

, \huge, \LARGE, \Large, \large, \normalsize, \small, \footnotesize, \scriptsize,

and \tiny. The description of these commands can be found in [

OPHS11

], [

Tea05b

], or

[

Tea05a

]. Color switching commands like \normalcolor (see [

Car05

] and [

Ker07

]) are also

acceptable. The behavior when using other commands, especially those that make redefinitions

or generate output, is not defined. Strange behavior is possible and does not represent a bug.

The command \setkomafont provides a font switching command with a completely new

definition. In contrast to this, the \addtokomafont command merely extends an existing

definition. It is recommended to not use both commands inside the document body, but

only in the document preamble. Usage examples can be found in the paragraphs on the

corresponding element. Names, defaults, and meanings of the individual items are listed in

table 5.1

.

With command \usekomafont the current font style may be changed into the font style of

the selected element .

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

pagefoot

. 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

pagefoot

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

Default: empty

. . .

Chapter 5: Adapting Page Headers and Footers with scrlayer-scrpage

229

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

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

pagehead

. 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

pagehead

. 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

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