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

22.1.2. Letterhead

The term letterhead here refers to all of the data pertaining to the sender and which is set

above the addressee’s address. It is usually expected that this information is set via the page

style settings. In fact, this was the case in the earlier incarnation of the letter class, scrlettr.

But with scrlttr2, the letterhead is made independent of the page style setting, and is set by

the command \opening. The position of the letterhead is absolute and independent of the

type area. In fact, the first page of a letter, the page that holds the letterhead, is set using

the page style empty.

firstheadvpos

The pseudo-length firstheadvpos gives the distance between the top edge of the paper and

start of the letterhead. This value is set differently in the various predefined lco-files. A

typical value is 8 mm.

firstheadhpos

A positive value of pseudo-length firstheadhpos

v3.05

gives the distance between the left edge of

the paper and the start of the letterhead. If is actually greater than or equal to the paper

width, \paperwidth, then the letterhead will be centered to the note paper width. A negative

value gives the distance between the distance between the right paper edge and the end of the

letterhead. If the value is even less or equal to the negative value of the width of the paper,

then the letterhead will be left aligned to the left edge of the typing area.

Typical default is a value of \maxdimen, though the greatest allowed value of a length. This

will result in horizontal centering.

firstheadwidth

The pseudo-length firstheadwidth gives the width of the letterhead. This value is set differ-

ently in the various predefined lco-files. While this value usually depends on the paper width

and the distance between the left edge of the paper and the adressee address field, it was the

type area width in KOMAold and has a definite value of 170 mm in NF.

fromrulethickness

fromrulewidth

Depending on the class option fromrule (see

section 4.10

,

page 161

), a horizontal rule can

be drawn the predefined letterheads under or within the sender address. If the pseudo-length

fromrulewidth

has a value of 0 pt, which is the default in the predefined lco files, the rule

length is calculated automatically taking into account, e. g., letterhead width or an optional

logo. Users can adjust rule length manually in their own lco-files by setting this pseudo-

length to positive values using \setplength (see

page 413

). The default thickness of the line

v2.97c

,

fromrulethickness

, is 0.4 pt.

418

Chapter 22.

22.1.3. Addressee

The term addressee here refers to the addressee’s name and address which are output in an

address field. Additional information can be output within this address field, such as dispatch

type or a return address; the latter is especially useful when using window envelopes. The

address directly follows the letterhead.

toaddrvpos

toaddrhpos

These pseudo-lengths define vertical and horizontal position of the address field relative to

the top-left corner of the paper. Values are set differently in the various predefined lco-files,

according to standard envelope window measures. A special feature of toaddrhpos is that

with negative values the offset is that of the right edge of the address field relative to the right

edge of the paper. This can be found, for instance, in the case of SN or NF. The smallest value

of toaddrvpos is found with DINmtext. Care must be taken to avoid overlap of letterhead

and address field. Whether the address field is output or not can be controlled by class option

addrfield

(see

section 4.10

,

page 173

).

toaddrheight

The pseudo-length toaddrheight defines the height of the address field, including the dispatch

type. If no dispatch type is specified, then the address is vertically centered in the field. If

a dispatch type is specified, then the address is set below the dispatch type, and vertically

centered in the remaining field height.

toaddrwidth

This pseudo-length defines the width of the address field. Values are set differently in the

various predefined lco-files, according to standard envelope window measures. Typical values

are between 70 mm and 100 mm.

Example: Assume that your printer has a very wide left or right margin of 15 mm. In this

case, when using the option SN, the letterhead, sender’s extensions and the address

can not be completely printed. Thus, you create a new lco-file with the following

content:

\ProvidesFile{SNmmarg.lco}

[2002/06/04 v0.1 my own lco]

\LoadLetterOption{SN}

\@addtoplength{toaddrwidth}{%

-\useplength{toaddrhpos}}

\@setplength{toaddrhpos}{-15mm}

\@addtoplength{toaddrwidth}{%

\useplength{toaddrhpos}}

\endinput

419

Chapter 22.

Then, until you can obtain a printer with smaller page margins, you simply use

the option SNmmarg instead of SN.

toaddrindent

Additional indentation of the address within address field can be controlled by the pseudo-

length toaddrindent. Its value applies to both left and right margin. Default value is 0 pt.

With

each

of

the

settings

v3.03

addrfield=PP

,

addrfield=image

,

and

addrfield=backgroundimage

(see

section 4.10

,

page 173

) a value of 0 pt will be re-

placed by a value of 8 mm. If really no indent should be used in this case, then 1 sp may be

used to set a negligible small indent. Additionally toaddrindent will be used also for the

distance to the right edge of the address window with the mentioned addrfield settings.

backaddrheight

For window envelopes the sender is often printed with small font at one line above the ad-

dressee. This kind of sender’s information is known as return address, because it is visible at

the address window and will be used by the post officers to return the letter (back) to the

sender. In this return address only that information should be that is needed for this purpose.

The height, that is reserved for the return address at the top of the address field, is given

by pseudo-length backaddrheight. A typical value for this is 5 mm in the predefined lco-

fileslco-file=lco-file. Whether or not to print the return address depend on option addrfield

(see

section 4.10

,

page 173

) and backaddress (see

section 4.10

,

page 173

).

specialmailindent

specialmailrightindent

An optional dispatch type can be output within the address field between the return address

and the addressee address, by setting the variable specialmail. Left and right alignment are

determined by pseudo-lengths specialmailindent and specialmailrightindent, respec-

tively. In the predefined lco-files provided by KOMA-Script, specialmailindent is set to

rubber length \fill, while specialmailrightindent is set to 1 em. Thus the dispatch type

is set 1 em from the address field’s right margin.

PPheadheight

PPheadwidth

The pseudo-length PPheadheight

v3.03

is the height, that will be reserved for the Port-Payé

head using the options addrfield=PP and addrfield=backgroundimage. Pseudo-length

PPheadwidth

will be used only with addrfield=PP (see

section 4.10

,

page 173

) and gives

the width of the left field in the Port-Payé head that contains P. P. logo, zip-code and place.

The width of the right field with the sender’s code and the priority is the remaining width.

Class scrlttr2 automatically changes pseudo-length PPheadheight’s usual default value from

0 mm into 20,74 pt and PPheadwidth’s default from 0 mm into 42 mm.

420

Chapter 22.

PPdatamatrixvskip

This

v3.03

pseudo-length gives the vertical distance between the Port-Payé head and the data array

or data matrix of option addrfield=PP (see

section 4.10

,

page 173

). Class scrlttr2 automat-

ically changes the default value 0 mm into 9 mm. The data matrix will be set right aligned

with the Port-Payé head.

22.1.4. Sender’s Extensions

Often, especially with business letters, the space for the letterhead or page footer seems to be

too tight to include all you want. To give more details about the sender, often the space right

beside the addressee’s field is used. In this manual this field is called the sender’s extension.

In former manuals is has been called location field.

locheight

lochpos

locvpos

locwidth

The pseudo-lengths locwidth and locheight

v2.97d

set the width and height of the sender’s exten-

sion field. The pseudo-lengths lochpos and locvpos determine the distances from the right

and upper paper edges. These value is typically set to 0 pt in the predefined lco files. This

does not mean that the sender’s extension has no width; instead, it means that the actual

width is set within \opening when the paper width, address window width, and the distance

between the left and upper edges of the paper and the address window are known. The option

locfield

(see

section 4.10

,

page 176

) is also taken into account. As is the case for toaddrhpos,

negative values of lochpos take on a special meaning. In that case, instead of referring to a

distance from the right edge of the paper, lochpos now means a distance from the left edge

of the paper. The meaning is thus the opposite to that of toaddrhpos (see

section 22.1.3

,

page 418

).

22.1.5. Business Line

Especially with business letters, a line can be found that gives initials, dial code, customer

number, invoice number, or a reference to a previous letter. This line is sometimes called

reference fields line

or reference line, sometimes business line. The business line can consist of

more than just one line and is set only if one of those variables mentioned above is given. Only

those fields will be set that are given. To set a seemingly empty field, one needs to give as value

at least a forced white space or \null. If you want to have your letter without a business line,

then instead of it the label and contents of the variable date will be set. Information about

adding variables to the business line or clean up the business line may be found in

section 22.2

,

page 423

.

421

Chapter 22.

refvpos

This pseudo-length gives the distance between the upper edge of the paper and the reference

fields line. Its value is set differently in the various predefined lco-files. Typical values are

between 80.5 mm and 98.5 mm.

refwidth

refhpos

This pseudo-length gives the width that is available for the reference fields line. The value is

set typically to 0 pt in the predefined lco-files. This value has a special meaning: in no way

does it determine that there is no available width for the business line; instead, this value

means that the width will be calculated within the command \opening. Thus the calculated

width depends on the determination of the options refline (see

section 4.10

,

page 178

). At

the same time, refhpos will be set according to this option. With refline=wide, the reference

fields line is centered, while with refline=narrow it is aligned on the left inside the typing

area.

If refwidth is not null, i. e., the width of the reference fields line is therefore not determined

by the option refline, then refhpos gives the distance of the reference fields line from the

left edge of the paper. If this distance is null, then the reference fields line is set so that the

ratio between its distances from the left and right edges of the paper equal the ratio of distance

of the type area from the left and right edges of the paper. Thus, for a type area horizontally

centered on the paper, the reference fields line too will be centered.

As a rule, these special cases are likely to be of little interest to the normal user. The

simplest rule is as follows: either refhpos is left at null and so the width and alignment of the

reference fields line are left to the option refline, or refwidth as well as refhpos are set by

the user.

refaftervskip

This pseudo-length gives the vertical space that has to be inserted beneath the reference fields

line. The value is set in the predefined lco-files. It directly affects the text height of the first

page. A typical value lies between one and two lines.

22.1.6. Subject

In different countries the letter’s subject will be set different. Some like to have the subject be-

fore the opening phrase, some prefer the subject below the opening phrase. Some professional

guilds at least want the subject before the business line.

subjectvpos

v3.01

If the value of this pseudo-length is 0 pt, the position of the subject is given by option

subject

(see

section 4.10

,

page 182

). Every other value defines the distance between the top

422

Chapter 22.

edge of the paper and the subject. It is recommended to take care of the available space to

surely avoid interferences with other elements.

Example: Some professional guilds prefer to have the subject at least before the business line.

To achieve this, the position may be defined like this:

\ProvidesFile{lawsubj.lco}

[2008/11/03 lawyers lco file]

\@setplength{subjectvpos}{\useplength{refvpos}}

\@addtoplength{refvpos}{3\baselineskip}

\endinput

which also changes the position of the business line itself. If at least one empty line

between subject and business line should stay empty, this provides a maximum of

two subject lines.

subjectbeforevskip

subjectaftervskip

v3.01

If the subject is not positioned absolutely, but before or after the opening phrase, additional

vertical spaces may be inserted before and after the subject. Thereby, the space before the

subject may interfere with other distances like the automatic distance of one line after the

title. Because of this the default is to use no additional space here. In contrast, the class’s

default for the space after the subject is two lines.

22.1.7. Closing

The closing consists of three parts: besides the closing phrase there are a hand-written in-

scription and the signature, which acts as an explanation for the inscription.

sigindent

sigbeforevskip

Closing phrase and signature will be typeset in a box. The width of the box is determined by

the length of the longest line of the closing phrase or signature.

The box will be typeset with indentation of the length set in pseudo-length sigindent. In

the predefined lco-files this length is set to 0 mm.

Between closing phrase and signature a vertical space is inserted, the height of which is

defined in the pseudo-length sigbeforevskip. In the predefined lco-files this is set to two

lines. In this space you can then write your inscription.

22.1.8. Letter Footer

As the first page of a letter, the note paper, holds a letterhead of its own, it also holds a

footer of its own. And, as with the letterhead, it will not be set by the page style settings,

but directly with the use of \opening.

423

Chapter 22.

firstfootvpos

This pseudo-length gives the distance between the letter footer and the upper edge of the

paper. It also takes care of preventing text from jutting into the footer area. For this the

text height on the first page will be decreased using \enlargethispage if needed. Likewise,

and if it is wanted, the text height can conversely be extended with the help of the option

enlargefirstpage

(see

section 4.10

,

page 160

). This way, the distance between text area and

the first letter footer can be reduced to the value \footskip.

With the compatibility option set

v2.9t

up to version 2.9t (see version in

section 4.4

,

page 29

)

the footer is set independently of the type area in all predefined lco-files (see

section 4.21

)

except for KOMAold and NF. The option enlargefirstpage also loses its effect. From version

2.9u onwards the footer is set in a position at the bottom edge of the paper. In this situation,

the height of the type area also becomes dependent on enlargefirstpage.

If the letter footer be switched off using option firstfoot=false

v2.97e

(see

section 4.10

,

page 184

), then the setting of firstfootvpos is ignored, and instead \paperheight is applied.

Thus, there remains a mimimum bottom margin of length \footskip.

firstfoothpos

v3.05

A positive value of pseudo-length firstfoothpos gives the distance between the letter footer

and the left edge of the paper. If the value is even greater than or equal to the paper width,

\paperwidth

, then the footer will be centered horizontally to the note paper. But if the value

is less than or equal to the negative width of the paper, then the footer will be aligned left to

the typing area.

Typical default for this value is \maxdimen, that is the maximum allowed value of a length.

This results in horizontal centering.

firstfootwidth

This pseudo-length gives the width of the letter’s first page footer. The value is set equal to

that of the pseudo-length firstheadwidth in the predefined lco-files.

22.2. Variables for Experienced Users

KOMA-Script provides beside the feature of using predefined variable also commands to define

new variable or to manipulate the automatic usage of variables in the business line.

\newkomavar[description ]{name }

\newkomavar*[description ]{name }

\removereffields

\defaultreffields

\addtoreffields{name }

With \newkomavar a new variable is defined. This variable is addressed via name . As an option

you can define a description for the variable name . In opposite to name the description

424

Chapter 22.

is not used to reference a variable. In fact the description defines an addition to the content

of a variable, that may be output similar to the variable content.

Using the command \addtoreffields you can add the variable name to the reference

fields line (see

section 4.10

,

page 178

). The description and the content of the variable are

added at the end of the reference fields line. The starred version \newkomavar* is similar to

the unstarred version, with a subsequent call of the command \addtoreffields. Thus, the

starred version automatically adds the variable to the reference fields line.

Example: Suppose you need an additional field for direct dialling. You can define this field

either with

\newkomavar[Direct dialling]{myphone}

\addtoreffields{myphone}

or more concisely with

\newkomavar*[direct dialling]{myphone}

When you define a variable for the reference fields line you should always give it a description.

With the command \removereffields all variables in the reference field line can be re-

moved. This also includes the predefined variables of the class. The reference fields line is

then empty. This can be useful, for example, if you wish to change the order of the variables

in the reference fields line.

The command \defaultreffields acts to reset the reference fields line to its predefined

format. In doing so, all custom-defined variables are removed from the reference fields line.

The date should not be added to the reference fields line using \addtoreffields. Instead

option date should be used to select the date left, right or not at the business line. This

option also will change the position of the date if no reference fields will be output.

\usekomavar[command ]{name }

\usekomavar*[command ]{name }

The commands \usekomavar and \usekomavar* are, similarly to all commands where a

starred version exists or which can take an optional argument, not fully expandable. Nev-

ertheless, if used within \markboth, \markright or similar commands, you need not insert

a \protect before using them. Of course this is also true for \markleft if using package

scrlayer-scrpage. However, these kinds of commands can not be used within commands like

\MakeUppercase

which directly influence their argument. To avoid this problem you may use

commands like \MakeUppercase as an optional argument to \usekomavar or \usekomavar*.

Then you will get the uppercase content of a variable using:

\usekomavar[\MakeUppercase]{Name }

425

Chapter 22.

\ifkomavarempty{name }{true }{false }

\ifkomavarempty*{name }{true }{false }

It is important to know that the content or description of the variable will be expanded as far

as this is possible with \edef. If this results in spaces or unexpandable macros like \relax,

the result will be not empty even where the use of the variable would not result in any visible

output.

Both variants of the command also must not be used as the argument of \MakeUppercase

or other commands which have similar effects to their arguments However, they are robust

enough to be used as the argument of, e. g., \markboth or \footnote.

22.3. Differences in the Page Styles of scrletter

As described in

section 4.13

, the page style headings shows the content of variables nexthead

and nextfoot. Page style headings has already another meaning in the KOMA-Script classes

scrbook, scrreprt, and scrartcl. Therefore scrletter defines a new pair of page styles (see

sec-

tion 18.2

,

page 364

). The definition is done using package scrlayer-scrpage.

Hence, you cannot use scrletter with the outdated packages scrpage2 and scrpage. Same ap-

plies to fancyhdr that is in general not recommended for use with KOMA-Script. Additionally,

internally loading package scrlayer-scrpage automatically activates page style scrheadings.

This activation changes page styles headings and plain into aliases of scrheadings and

plain.scrheadings

. So these page styles are also controlled by scrlayer-scrpage.

\pagestyle{letter}

\pagestyle{plain.letter}

\setkomavar{nexthead}[description ]{content }

\setkomavar{nextfoot}[description ]{content }

Package scrletter defines the pair of page style letter using scrlayer-scrpage to become in-

dependent from the page styles of the document class. Variables nexthead and nextfoot

are used by scrletter’s letter in the same way as for scrlttr2’s headings. The corresponding

plain

page style is also similar to scrlttr2’s page style plain. Notably the position of the page

number depends on option pagenumber (see

page 188

).

headsepline

footsepline

Because of the different internal approach of scrletter, the options headsepline and

footsepline

differ slightly from class scrlttr2, because they are controlled by package

scrlayer-scrpage. Especially the horizontal lines in page head and foot of the plain page

style depend on the options of scrlayer-scrpage. See

section 5.5

,

page 226

and

page 228

for

information about those options.

426

Chapter 22.

\pagemark

\letterpagemark

The KOMA-Script classes already define and use \pagemark. So when scrletter is loaded, it

cannot simply redefine \pagemark to add the prefix “Page” using \pagename, because this

would not only influence the pagination of the letter pages but the pagination of the whole

document. Therefore

v3.17

scrletter defines a new command \letterpagemark with the prefix and

lets \pagemark become \letterpagemark in \begin{letter} until the end of the letter only.

If you want to redefine \pagemark for the whole document including the letter pages, you have

to add

\let\letterpagemark\pagemark

just after the normal redefinition of \pagemark. This add-on also will not violate anything if

you later decide to switch from package scrletter to class scrlttr2. Note that the class scrlttr2

does not provide or use \letterpagemark.