3.2 ⁑Writing a Letter Using the `scrlttr2` Class

This section describes how to use the scrlttr2 KOMA-Script class [47] to write letters. (Don't be confused if you see a class called scrlettr. That's an older deprecated class.)

The scrlttr2 class defines the letter environment:

\begin {letter}[⟨options⟩]{⟨addressee⟩}

where ⟨addressee⟩ is the recipient's postal details. Use \\ to separate the lines of the address. As with the letter class described above, a document may have more than one letter environment, which will later come in useful when we look at mail merging in §3.5 Mail Merging. Within the letter environment you must start the letter with

\opening {⟨salutation⟩}

and close with

\closing {⟨sign-off text⟩}

The ⟨salutation⟩ is the greeting at the start of the letter, such as Dear Dr~Smith and the ⟨sign-off text⟩ is the closing text, such as Yours sincerely.

After \closing{⟨sign-off text⟩} you can optionally use:

\ps ⟨postscript text⟩

(As with the letter class, the ⟨postscript text⟩ is not an argument of \ps, and you need to include “PS” in ⟨postscript text⟩ if you want it as it's not automatically generated.)

\encl {⟨enclosures info⟩}

and

\cc {⟨cc list⟩}

These three commands, if required, must go after \closing and before the end of the letter environment.

⚠

The scrlttr2 class is designed for use with the babel package [7], so remember to load it. (See Volume 1.)

Example 13. A Simple Letter (scrlttr2 class)

Here's a simple example letter:

\documentclass{scrlttr2}

\usepackage[british]{babel}

\begin{document}

\begin{letter}{Mrs Mabel Canary\\24 The Street\\Some Village\\
Some Town\\Noshire\\AB1 2YZ}
  \opening{Dear Mrs~Canary}

  This is an imaginary letter.

  This is the second paragraph of the letter.

  \closing{Yours sincerely}

  \ps PS: this is a postscript.

  \encl{Photocopy of something interesting\\
   Photocopy of something rather dull}

  \cc{Prof Important Person\\
   Dr Bor Ing}
\end{letter}

\end{document}

⇩

(You can download or view this document.) The resulting document is shown in Figure 3.2. Things to note:

The first paragraph of the letter isn't indented, subsequent paragraphs are. If you prefer to have blank lines between paragraphs and no paragraph indentation you can use the parskip=full or parskip=half class options. For example:

\documentclass[parskip=full]{scrlttr2}
The date is automatically inserted. The date format is defined by the language dialect currently in use. Since I've loaded babel with the british option, the date is in the form ⟨day⟩ ⟨month⟩ ⟨year⟩.
There is space between the closing text and the postscript for you to sign your name.
The page has horizontal marks on the left hand side. These are guides for folding or punching and are discussed below.
This example assumes that you are going to print the letter on headed paper.

KOMA-Script has “variables” that represents document elements. Variable names don't start with a backslash. They are simple labels such as yourref. Variables have both content and a description. You can set the content, and optionally the description, using:

\setkomavar {⟨name⟩}[⟨description⟩]{⟨content⟩}

where ⟨name⟩ is the variable's name, ⟨description⟩ is the variable's description and ⟨content⟩ is the variable's content. Alternatively, you can just set the description, without modifying the content, using:

\setkomavar*{⟨name⟩}{⟨description⟩}

Example:

Suppose I want to add a “Your ref” line before the opening salutation. For example, supposing the recipient has requested the reference “ABC/123” in any correspondence, then I need to add

\setkomavar{yourref}{ABC/123}

before the \opening command. This will now appear in the letter as

Here, the variable is yourref and the content is “ABC/123”. The default description (in English) for this variable is “Your ref.” This can be changed with the optional argument:

\setkomavar{yourref}[Your Reference:]{ABC/123}

KOMA-Script also has “options” that correspond to the variables. The option name is the same as the variable name and can be set via:

\KOMAoption {⟨option⟩}{⟨value list⟩}

\KOMAoptions {⟨option=value list⟩}

For example, the subject option indicates how the subject text should be displayed. Possible values for this option are: afteropening, beforeopening, centered, left, right, titled, underlined or untitled. For example, to make the subject appear after the opening text you can use either

\KOMAoptions{subject=afteropening}

\KOMAoption{subject}{afteropening}

Some of these settings can be combined. For example:

% set the subject options:
\KOMAoption{subject}{afteropening,right,underlined,titled}
% set the subject contents:
\setkomavar{subject}{A sample letter}

There are a lot of other variables, such as invoice for the invoice number and customer for the customer number. Common variables are listed in Table 3.1. Common options with some of their possible values are listed in Table 3.2. See the KOMA-Script documentation [47] for a complete list of all variables and options.

Options can also be set via the optional argument of the letter environment. For example:

\begin{letter}[subject=afteropening]{Mrs~Mabel Canary}

or in the class options. For example:

\documentclass[subject=afteropening]{scrlttr2}

The foldmarks option may have the single letter values combined. For example:

\KOMAoptions{foldmarks=vpmBT}

\KOMAoption{foldmarks}{vpmBT}

Table 3.1: Common scrlttr2 Variables

Variable Description

customer Customer number.

date Letter date.

firstfoot Footer for the first page of the letter.

nextfoot Footer for subsequent pages of the letter.

firsthead Header for the first page of the letter.

nexthead Header for subsequent pages of the letter.

fromaddress Sender's address (without sender's name).

fromemail Sender's email.

fromfax Sender's fax number.

fromlogo Commands for inserting sender's logo.

frommobilephone Sender's mobile phone number.

fromname Sender's full name.

fromphone Sender's telephone number.

fromurl Sender's URL (e.g. home page).

invoice Invoice number.

myref Sender's reference.

location Additional sender details.

signature Signature beneath letter ending.

subject Letter's subject.

title Letter's title.

yourref Recipient's reference.

**Table 3.1:** Common `scrlttr2` Variables

Variable	Description
`customer`	Customer number.
`date`	Letter date.
`firstfoot`	Footer for the first page of the letter.
`nextfoot`	Footer for subsequent pages of the letter.
`firsthead`	Header for the first page of the letter.
`nexthead`	Header for subsequent pages of the letter.
`fromaddress`	Sender's address (without sender's name).
`fromemail`	Sender's email.
`fromfax`	Sender's fax number.
`fromlogo`	Commands for inserting sender's logo.
`frommobilephone`	Sender's mobile phone number.
`fromname`	Sender's full name.
`fromphone`	Sender's telephone number.
`fromurl`	Sender's URL (e.g. home page).
`invoice`	Invoice number.
`myref`	Sender's reference.
`location`	Additional sender details.
`signature`	Signature beneath letter ending.
`subject`	Letter's subject.
`title`	Letter's title.
`yourref`	Recipient's reference.

Table 3.2: Common scrlttr2 Options with Some of their Values
Option Value Description

firsthead true Display letter head.

false Don't display letter head.

fromalign center Centre return address.

left Left-justify return address.

right Right-justify return address.

fromphone true Include sender's phone number.

false Don't include sender's phone number.

frommobilephone true Include sender's mobile number.

false Don't include sender's mobile number.

fromfax true Include sender's fax number.

false Don't include sender's fax number.

fromemail true Include sender's email.

false Don't include sender's email.

fromurl true Include sender's web address.

false Don't include sender's web address.

fromlogo true Include sender's logo.

false Don't include sender's logo.

addrfield true Print an address field including a return address, mode of dispatch and priority.

false Don't print address field.

backaddress true Print return address for window envelope.

false Don't print return address for window envelope.

priority false Don't print priority field.

economy Use international priority B-Economy.

priority Use international priority A-Priority.

locfield narrow Narrow location field.

wide Wide location field.

numericaldate true Use numerical date.

false Use language-dependent date format.

refline dateleft Place date left-most on the reference line.

dateright Place date right-most on the reference line.

narrow Restrict reference line to typearea.

nodate Don't place date on reference line.

wide The width of the reference line corresponds to the address and sender's additional details.

subject true Print subject field.

afteropening Place subject field below letter opening.

beforeopening Place subject field above letter opening.

centered Centre subject field.

left Left-justify subject field.

right Right-justify subject field.

title Add title/description to subject field.

untitled Don't add title/description to subject field.

underlined Underline subject field (must be single-lined).

headsepline true Insert a separator line below the header.

false Don't insert a separator line below the header.

footsepline true Insert a separator line above the footer.

false Don't insert a separator line above the footer.

pagenumber foot Page number in footer.

head Page number in header.

false No page number.

center Page number centred.

left Page number left-aligned.

right Page number right-aligned.

foldmarks false Don't display fold marks.

B Activate upper horizontal foldmark on left paper edge.

b Deactivate upper horizontal foldmark on left paper edge.

H Activate all horizontal folding marks on left paper edge.

h Deactivate all horizontal folding marks on left paper edge.

L Activate left vertical foldmark on upper paper edge.

l Deactivate left vertical foldmark on upper paper edge.

M Activate middle horizontal foldmark on left paper edge.

m Deactivate middle horizontal foldmark on left paper edge.

P Activate punch or centre mark on left paper edge.

p Deactivate punch or centre mark on left paper edge.

T Activate lower horizontal foldmark on left paper edge.

t Deactivate lower horizontal foldmark on left paper edge.

V Activate all vertical folding marks on upper paper edge.

v Deactivate all vertical folding marks on upper paper edge.

**Table 3.2:** Common `scrlttr2` Options with Some of their Values
Option	Value	Description
`firsthead`	`true`	Display letter head.
	`false`	Don't display letter head.
`fromalign`	`center`	Centre return address.
	`left`	Left-justify return address.
	`right`	Right-justify return address.
`fromphone`	`true`	Include sender's phone number.
	`false`	Don't include sender's phone number.
`frommobilephone`	`true`	Include sender's mobile number.
	`false`	Don't include sender's mobile number.
`fromfax`	`true`	Include sender's fax number.
	`false`	Don't include sender's fax number.
`fromemail`	`true`	Include sender's email.
	`false`	Don't include sender's email.
`fromurl`	`true`	Include sender's web address.
	`false`	Don't include sender's web address.
`fromlogo`	`true`	Include sender's logo.
	`false`	Don't include sender's logo.
`addrfield`	`true`	Print an address field including a return address, mode of dispatch and priority.
	`false`	Don't print address field.
`backaddress`	`true`	Print return address for window envelope.
	`false`	Don't print return address for window envelope.
`priority`	`false`	Don't print priority field.
	`economy`	Use international priority B-Economy.
	`priority`	Use international priority A-Priority.
`locfield`	`narrow`	Narrow `location` field.
	`wide`	Wide `location` field.
`numericaldate`	`true`	Use numerical date.
	`false`	Use language-dependent date format.
`refline`	`dateleft`	Place date left-most on the reference line.
	`dateright`	Place date right-most on the reference line.
	`narrow`	Restrict reference line to typearea.
	`nodate`	Don't place date on reference line.
	`wide`	The width of the reference line corresponds to the address and sender's additional details.
`subject`	`true`	Print subject field.
	`afteropening`	Place subject field below letter opening.
	`beforeopening`	Place subject field above letter opening.
	`centered`	Centre subject field.
	`left`	Left-justify subject field.
	`right`	Right-justify subject field.
	`title`	Add title/description to subject field.
	`untitled`	Don't add title/description to subject field.
	`underlined`	Underline subject field (must be single-lined).
`headsepline`	`true`	Insert a separator line below the header.
	`false`	Don't insert a separator line below the header.
`footsepline`	`true`	Insert a separator line above the footer.
	`false`	Don't insert a separator line above the footer.
`pagenumber`	`foot`	Page number in footer.
	`head`	Page number in header.
	`false`	No page number.
	`center`	Page number centred.
	`left`	Page number left-aligned.
	`right`	Page number right-aligned.
`foldmarks`	`false`	Don't display fold marks.
	`B`	Activate upper horizontal foldmark on left paper edge.
	`b`	Deactivate upper horizontal foldmark on left paper edge.
	`H`	Activate all horizontal folding marks on left paper edge.
	`h`	Deactivate all horizontal folding marks on left paper edge.
	`L`	Activate left vertical foldmark on upper paper edge.
	`l`	Deactivate left vertical foldmark on upper paper edge.
	`M`	Activate middle horizontal foldmark on left paper edge.
	`m`	Deactivate middle horizontal foldmark on left paper edge.
	`P`	Activate punch or centre mark on left paper edge.
	`p`	Deactivate punch or centre mark on left paper edge.
	`T`	Activate lower horizontal foldmark on left paper edge.
	`t`	Deactivate lower horizontal foldmark on left paper edge.
	`V`	Activate all vertical folding marks on upper paper edge.
	`v`	Deactivate all vertical folding marks on upper paper edge.

Recall from Volume 1 that the graphicx package [14] provides the command:

\includegraphics [⟨options⟩]{⟨file⟩}

to include the image file called ⟨file⟩. (The extension may be omitted.)

By default, the logo isn't displayed, even if you set the fromlogo variable. If you want it displayed you need to activate it via:

\KOMAoption{fromlogo}{true}

as well as set the fromlogo variable:

\setkomavar{fromlogo}{\includegraphics{mylogo}}

Example 14. Writing a Letter: KOMA Settings

Remember that you can have multiple letters in the same document. If you want the content of a variable to be the same for all the letters in the document, put the \setkomavar or \setkomavar* command in the preamble. If the content of a variable depends on the recipient, then set it inside the letter environment (before \opening), as illustrated below:

\documentclass[12pt,parskip=full]{scrlttr2}

\usepackage[british]{babel}

\KOMAoption{subject}{afteropening,right,underlined,titled}

\KOMAoptions{foldmarks=vpmBT}

\setkomavar{signature}{Mr Big Head, Managing Director}
\setkomavar{subject}{A sample letter}

\begin{document}

\begin{letter}{Mrs Mabel Canary\\24 The Street\\Some Village\\
Some Town\\Noshire\\AB1 2YZ}
  \setkomavar{myref}{ABC/123}
  \setkomavar{invoice}{123456}
  \setkomavar{customer}{2}

  \opening{Dear Mrs~Canary}

  This is an imaginary letter.

  This is the second paragraph of the letter.

  \closing{Yours sincerely}

  \ps PS: this is a postscript.

  \encl{Photocopy of something interesting\\
   Photocopy of something rather dull}

  \cc{Prof Important Person\\Dr Bor Ing}
\end{letter}

\end{document}

(You can download or view this example.) The resulting document is shown in Figure 3.3.

Figure 3.3: A Simple Letter Using KOMA-Script Variables

⇩

Exercise 8. Writing a Letter (scrlttr2 class)

For this exercise, modify the sample letter from Example 14 so that it includes a return address and logo. You can make up the sender's address or use your own. If you don't have an image file, you can download the sample logo dummy-logo.png. Alternatively you can use the example-image.pdf file included with the mwe package [83]. (You don't need to load mwe in order to use this image.) Remember you can scale the image using the optional argument of \includegraphics. Also, try changing some of the options, such as switching off all the fold and punch marks. You can download or view a solution.

For the More Adventurous

Recall from §2.8 Fetching Data From a Given Row that you can fetch a single row of data from a database. Use one of the commands described in that section to fetch the recipient's details from the sample people.csv file or the people SQL table rather than explicitly typing them into the document. You can download or view a solution.

⇦

⇧

⇨

This book is also available as A4 PDF or 12.8cm x 9.6cm PDF or paperback (ISBN 978-1-909440-07-4).

3.2 ⁑Writing a Letter Using the scrlttr2 Class

3.2 ⁑Writing a Letter Using the `scrlttr2` Class