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

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.

\@setplength

{toaddrvpos}{length }

\@setplength

{toaddrhpos}{length }

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 182

).

Chapter 22: Additional Information about the Letter Class scrlttr2 and the Letter Package scrletter

474

\@setplength

{toaddrheight}{length }

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.

\@setplength

{toaddrwidth}{length }

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

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

the option SNmmarg instead of SN.

\@setplength

{toaddrindent}{length }

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 182

) a value of 0 pt will be replaced 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 negli-

gible small indent. Additionally toaddrindent will be used also for the distance to the right

edge of the address window with the mentioned addrfield settings.

Chapter 22: Additional Information about the Letter Class scrlttr2 and the Letter Package scrletter

475

\@setplength

{backaddrheight}{length }

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 182

) and

backaddress

(see

section 4.10

,

page 182

).

\@setplength

{specialmailindent}{length }

\@setplength

{specialmailrightindent}{length }

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.

\@setplength

{PPheadheight}{length }

\@setplength

{PPheadwidth}{length }

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 182

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

\@setplength

{PPdatamatrixvskip}{length }

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 182

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

Chapter 22: Additional Information about the Letter Class scrlttr2 and the Letter Package scrletter

476

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.

\@setplength

{locheight}{length }

\@setplength

{lochpos}{length }

\@setplength

{locvpos}{length }

\@setplength

{locwidth}{length }

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 187

) 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 473

).

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 480

.

\@setplength

{refvpos}{length }

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.

Chapter 22: Additional Information about the Letter Class scrlttr2 and the Letter Package scrletter

477

\@setplength

{refwidth}{length }

\@setplength

{refhpos}{length }

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 189

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

\@setplength

{refaftervskip}{length }

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.

\@setplength

{subjectvpos}{length }

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 193

). Every other value defines the distance between the top

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:

Chapter 22: Additional Information about the Letter Class scrlttr2 and the Letter Package scrletter

478

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

\@setplength

{subjectbeforevskip}{length }

\@setplength

{subjectaftervskip}{length }

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.

\@setplength

{sigindent}{length }

\@setplength

{sigbeforevskip}{length }

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

.

Chapter 22: Additional Information about the Letter Class scrlttr2 and the Letter Package scrletter

479

\@setplength

{firstfootvpos}{length }

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 170

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

)

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 195

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

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

\@setplength

{firstfoothpos}{length }

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.

\@setplength

{firstfootwidth}{length }

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.

Chapter 22: Additional Information about the Letter Class scrlttr2 and the Letter Package scrletter

480

\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

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 189

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

Chapter 22: Additional Information about the Letter Class scrlttr2 and the Letter Package scrletter

481

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

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

). 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 ]{contents }

\setkomavar{nextfoot}[description ]{contents }

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 200

).