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

Chapter 4: The New Letter Class scrlttr2

146

Example: Suppose you have defined a direct dialling as mentioned above and you now want

to set the content. You write:

\setkomavar{myphone}{-\,11}

In addition, you want to replace the term “direct dialling” with “Connection”.

Thus you add the description:

\setkomavar*{myphone}{Connection}

or you can combine both in one command:

\setkomavar{myphone}[Connection]{-\,11}

By the way: You may delete the content of a variable using an empty content argument.

You can also delete the description using an empty description argument.

Example: Suppose you have defined a direct dialling as mentioned above and you now no

longer want a description to be set. You write:

\setkomavar*{myphone}{}

You can combine this with the definition of the content:

\setkomavar{myphone}[]{-\,11}

So you may setup the content and delete the description using only one command.

\usekomavar[command ]{name }

\usekomavar*[command ]{name }

In

v2.9i

some cases it is necessary for the user to access the content or the description of a variable,

and not to leave this only up to the class. This is specially important when you have defined a

variable which is not added to the reference fields line. Using the command \usekomavar you

have access to the content of the variable name , whereas the starred version \usekomavar*

allows you to access the description or title. In

section 22.2

,

page 480

you may find more

information about defining variable on your own.

\ifkomavar{name }{true-code }{false-code }

This

v3.03

command may be used to test, whether or not a variable has already been defined. The

true-code

will be executed only, if the variable already exists. The contents of the variable

will not be examined, so it may be empty. The false-code will be executed if the variable

does not yet exist. Such tests make sense if a variable will be defined at one lco-file (see

section 4.21

from

page 214

onward), but used in another lco-file if it exists only.

Chapter 4: The New Letter Class scrlttr2

147

\ifkomavarempty{name }{true-code }{false-code }

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

With

v2.9i

these commands you may check whether or not the expanded content or description of

a variable is empty. The true-code will be executed if the content or description is empty.

Otherwise the false-code will be executed. The starred variant handles the description of a

variable, the unstarred variant handles the contents.

4.2. Pseudo-Lengths

L

A

TEX processes length with commands \newlength, \setlength, \addtolength, and

\thelength

. Many packages also use macros, that are commands, to storage lengths. KOMA-

Script extends the method of storing length at macros by some commands similar to the com-

mands above, that are used to handle real lengths. KOMA-Scriptcalls this kind of lengths,

that are stored at macros instead of real L

A

TEX lengths, pseudo-lengths.

A list of all pseudo-lengths in scrlttr2 is shown in

table 22.1

starting at

page 465

. The

meaning of the various pseudo-lengths is shown graphically in

figure 22.1

. The dimensions

used in the figure correspond to the default settings of scrlttr2. More detailed description of

the individual pseudo-lengths is found in the individual sections of this chapter.

Normally users would not need to define a pseudo-length on their own. Because of this,

definition of pseudo-lengths will be described in the expert part at

section 22.1

,

page 468

.

Setting pseudo-lengths to new values is also a work for advanced users. So this will be described

in the expert part too at

page 470

.

Please note: Even though these pseudo-lengths are internally implemented as macros, the

commands for pseudo-length management expect only the names of the pseudo-lengths not the

macros representing the pseudo-lengths. The names of pseudo-lengths are without backslash

at the very beginning similar to the names of L

A

TEX counters and in opposite to macros or

L

A

TEX lengths.

\useplength{name }

Using this command you can access the value of the pseudo-length with the given name . This

is one of the few user commands in connection with pseudo-lengths. Of course this command

can also be used with an lco-file (see

section 4.21

ab

page 214

).

\setlengthtoplength[factor ]{length }{pseudo-length }

\addtolengthplength[factor ]{length }{pseudo-length }

While you can simply prepend a factor to a length, this is not possible with pseudo-lengths. Suppose

you have a length \test with the value 2 pt; then 3\test gives you the value 6 pt. Using pseudo-

lengths instead, 3\useplength{test} would give you 32 pt. This is especially annoying if you

want a real length to take the value of a pseudo-length .

Chapter 4: The New Letter Class scrlttr2

148

Using the command \setlengthtoplength you can assign the multiple of a pseudo-length

to a real length . Here, instead of prepending the factor to the pseudo-length , it is given

as an optional argument. You should also use this command when you want to assign the

negative value of a pseudo-length to a length . In this case you can either use a minus sign

or -1 as the factor . The command \addtolengthplength works very similarly; it adds the

multiple of a pseudo-length to the length .

4.3. 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 4.4

,

page 149

.

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

is also relevant to other KOMA-Script classes and packages. 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

].

When using a KOMA-Script class, no options should be passed on loading of the typearea

or scrbase packages. The reason for this is that the class already loads these packages without

options and L

A

TEX refuses multiple loadings of a package with different option settings. Actu-

ally, it is no longer necessary when using any KOMA-Script class to explicity load either one

of these packages.

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

Chapter 4: The New Letter Class scrlttr2

149

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

,

section 12.2

,

page 313

.

4.4. Compatibility with Earlier Versions of KOMA-Script

It applies, mutatis mutandis, what is written in

section 2.5

. However, this feature exists at

scrlttr2 since version 2.9t. o if you have alread read and understood

section 2.5

you can switch

to

page 150

,

page 150

.

In some cases improvement and bug corrections of classes will result in changes of the

behaviour and make-up. But sometimes this is not wanted.

version=value

version=first

version=last

Since

v2.96a

v2.9t

v3.01b

version 2.9t of scrlttr2 it’s your choice if your source code should result in the same

make-up at future L

A

TEX runs or if you like to participate in all improvements of new releases

of the class. You may select the compatible version of KOMA-Script with option version.

Compatibility to the lowest supported KOMA-Script release may be achieved by version=

first

or version=2.9 or version=2.9t. Setting value to an unknown release number will

result in a warning message and selects version=first for safety.

With version=last the most recent version will be selected at every L

A

TEX run. Be warned,

though, that using version=last poses possibilities of compatibility issues for future L

A

TEX

runs. Option version without any value means the same.

v3.01a

This is the default behaviour as

long as you do not use any deprecated options.

Chapter 4: The New Letter Class scrlttr2

150

If you use a deprecated option of KOMA-Script 2, KOMA-Script 3 will switch to version=

first

automatically. This will also result in a warning message that explains how to prevent

this switching. Alternatively you may select another adjustment using option version with

the wanted compatibility after the deprecated option.

Compatibility is primarily make-up compatibility. New features not related to the mark-up

will be available even if you switch compatibility to a version before first implementation of

the feature. Option version does not influence make-up changes that are motivated by bug

fixes. If you need bug compatibility you should physically save the used KOMA-Script version

together with your document.

Example: The letter examples of this chapter should use and show all the features of the

recent KOMA-Script release. To achieve this, we set the corresponding compati-

bility:

\documentclass[version=last]{scrlttr2}

In this case the symbolic value last has been used to select the latest version.

Please note that you cannot change option version anymore after loading the class. There-

fore, the usage of option version within the argument of

\KOMAoptions

or

\KOMAoption

is

not recommended and will cause an error.

4.5. Draft Mode

What is written in

section 3.3

applies, mutatis mutandis. So if you have alread read and

understood

section 3.3

you can jump to

section 4.6

on

page 151

.

Many classes and packages provide a draft mode aside from the final typesetting mode. The

difference of draft and final mode may be as manifold as the classes and package that support

these modes. For instance, the graphics and the graphicx packages do not actually output the

graphics in their own draft mode. Instead they output a framed box of the appropriate size

containing only the graphic’s file name (see [

Car05

]).

draft=simple switch

This option

v3.00

is normally used to distinguish between the draft and final versions of a document.

simple switch

value may be any standard value from

table 2.5

,

page 39

. In particular,

switching on the option activates small black boxes that are set at the end of overly long

lines. The boxes help the untrained eye to find paragraphs that have to be treated manually.

With the default draft=false option no such boxes are shown. Such overly long lines often

vanish using package microtype [

Sch13

].

Chapter 4: The New Letter Class scrlttr2

151

4.6. Page Layout

Each page of a document is separated into several different layout elements, e. g., margins,

head, foot, text area, margin note column, and the distances between all these elements.

KOMA-Script additionally distinguishes the page as a whole also known as the paper and

the viewable area of the page. Without doubt, the separation of the page into the several

parts is one of the basic features of a class. Nevertheless at KOMA-Script the classes delegate

that business to the package typearea. This package may be used with other classes too. In

difference to those other classes the KOMA-Script classes load typearea on their own. Because

of this, there’s no need to load the package explicitly with \usepackage while using a KOMA-

Script class. Nor would this make sense or be useful. See also

section 4.3

.

Some settings of KOMA-Script classes do influence the page layout. Those effects will be

documented at the corresponding settings.

For more information about page size, separation of pages into margins and type area, and

about selection of one or two column typesetting see the documentation of package typearea.

You may find it at

chapter 2

from

page 25

onwards.

Normally it makes no sense to distinguish letters with single-side layout and letters with

double-side layout. Mostly letters are not bound like books. Therefor each page will be viewed

on its own. This is also true if both sides of the paper sheet will be used for printing. Vertical

adjustment is unusual at letters too. Nevertheless, if you need or want it, you may read the

description of \raggedbottom and \flushbottom in

section 3.4

at

page 54

.

4.7. General Structure of Letter Documents

The general structure of a letter document differs somewhat from the structure of a normal

document. Whereas a book document in general contains only one book, a letter document can

contain several letters. As illustrated in

figure 4.1

, a letter document consists of a preamble,

the individual letters, and the closing.

The preamble comprises all settings that in general concern all letters. Most of them can

also be overwritten in the settings of the individual letters. The only setting which can not be

changed within a single letter is compatibility to prior versions of scrlttr2 (see option

version

in

section 4.4

,

page 149

).

It is recommended that only general settings such as the loading of packages and the setting

of options be placed before \begin{document}. All settings that comprise the setting of

variables or other text features should be done after \begin{document}. This is particularly

recommended when the babel package (see [

BB13

]) is used, or language-dependent variables

of scrlttr2 are to be changed.

The closing usually consists only of \end{document}. Of course you can also insert addi-

tional comments at this point.

As shown in

figure 4.2

, every single letter itself consists of an introduction, the letter body,

Chapter 4: The New Letter Class scrlttr2

152

Figure 4.1.: General structure

of a letter document with

several individual letters (the

structure of a single letter is

shown in

figure 4.2

)

\documentclass[...]{scrlttr2}

. . .

settings for all letters

. . .

\begin{document}

. . .

settings for all letters

. . .

\begin{letter}{addressee }

. . .

content of the individual letter

. . .

\end{letter}

...

\end{document}

Figure 4.2.: General structure

of a single letter within a letter

document (see also

figure 4.1

)

\begin{letter}[Optionen ]{addressee }

. . .

settings for this letter

. . .

\opening

{opening }

. . .

letter text

. . .

\closing

{closing }

\ps

. . .

postscript

. . .

\encl

{enclosures }

\cc

{additional addressees }

\end{letter}

Chapter 4: The New Letter Class scrlttr2

153

and the closing. In the introduction, all settings pertaining only to the current letter are

defined. It is important that this introduction always ends with

\opening

. Similarly, the

closing always starts with

\closing

. The two arguments opening and closing can be left

empty, but both commands must be used and must have an argument.

It should be noted that several settings can be changed between the individual letters. Such

changes then have an effect on all subsequent letters. For reasons of maintainability of your

letter documents, it is however not recommended to use further general settings with limited

scope between the letters.

\begin{letter}[options ]{addressee }

. . . \end{letter}

The letter environment is one of the key environments of the letter class. A special scrlttr2

feature are optional arguments to the letter environment. These options are executed

internally via the

\KOMAoptions

command.

The addressee is a mandatory argument passed to the letter environment. Parts of the

addressee contents are separated by double backslashes. These parts are output on individual

lines in the address field. Nevertheless, the double backslash should not be interpreted as a

certain line break. Vertical material such as paragraphs or vertical space is not permitted

within addressee , and could lead to unexpected results and error messages, as is the case

also for the standard letter class.

Example: Assumed, someone wants to send a letter to Joana Public. A minimalistic letter

document for this may be:

\documentclass[version=last]{scrlttr2}

\usepackage[english]{babel}

\begin{document}

\begin{letter}{Joana Public\\

Hillside 1\\

12345 Public-City}

\end{letter}

\end{document}

However, this would not result in any printable output. At least there would not

be an addressee at the note paper sheet. The reason for this will be explained at

the description of command

\opening

at

page 155

.

Chapter 4: The New Letter Class scrlttr2

154

\AtBeginLetter{instruction code }

\AtEndLetter{instruction code }

L

A

TEX enables the user to declare instruction code whose execution is delayed until a

determined point. Such points are called hooks. Known macros for using hooks are

\AtBeginDocument

and \AtEndOfClass at the L

A

TEX kernel. The class scrlttr2 provides two

more hooks. The instruction code for these may be declared using \AtBeginLetter and

\AtEndLetter

v2.95

. Originally, hooks were provided for package and class authors, so they are

documented in [

Tea06

] only, and not in [

Tea05b

]. However, with letters there are useful

applications of \AtBeginLetter as the following example may illustrate.