# Creating letters with KOMA scrlttr2

This tutorial describes the necessary steps to produce beautiful letters using Org-mode's LaTeX exporter and KOMA-Script's scrlttr2 class.

## Quick start guide

### Requirements

The code in this tutorial depends on the following:

• Org-mode version 8.0 or greater.
• A LaTeX installation including KOMA-Script, e.g., TeX Live.

Note: The information in this tutorial depends on functionality that has not yet been released. You can either use the latest development version from the Org-mode git repository or download a current version of the KOMA letter exporter and install it in contrib/lisp.

### Minimal configuration of the KOMA letter exporter

To use the KOMA letter exporter, you have to add it to Emacs' load path, activate it, and configure a LaTeX class for the LaTeX exporter (the KOMA letter exporter uses the LaTeX exporter internally).

1. Add the path containing ox-koma-letter.el to Emacs' load path. For example, if you use the version contained in the directory contrib/lisp of Org-mode, add the following to your Emacs configuration:
(add-to-list 'load-path "~/path/to/org-mode/contrib/lisp" t)

2. Activate the KOMA letter exporter by adding the following to your Emacs configuration:
(require 'ox-koma-letter)

3. Configure a LaTeX class for the LaTeX exporter to use for the export of KOMA letters by adding the following to your Emacs configuration:

#+BEGINSRC emacs-lisp

(add-to-list 'org-latex-classes '("my-letter" "\\documentclass\{scrlttr2\} \\usepackage[english]{babel} \[NO-DEFAULT-PACKAGES] \[NO-PACKAGES] \[EXTRA]"))

#+ENDSRC

For more information about this step, refer to the documentation of the variables org-latex-classes, org-latex-default-packages-alist, and org-latex-packages-alist.

### A simple letter example

Printed below is a minimal Org file that can be exported to a KOMA letter. In this file, press C-c C-e to bring up the exporter dispatcher and then press k o to export the Org file to a PDF file containing the letter. For your convenience, you can download the KOMA letter example and you can also download the example PDF letter.

#+LATEX_CLASS: my-letter
#+TITLE: A simple letter
#+DATE: April 22, 2013
#+AUTHOR: Jane Doe
#+FROM_ADDRESS: Some Street 1\\
#+FROM_ADDRESS: 12345 Some City
#+TO_ADDRESS: Other Street 1\\
#+TO_ADDRESS: 54321 Other City
#+OPENING: Dear John,
#+CLOSING: Yours truly,
#+SIGNATURE: Jane
#+LANGUAGE: en

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enimad
minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.


The first line selects the letter LaTeX class we defined above. The following lines configure the letter's sender and recipient and other information of the letter. These settings are described in the next section. Finally, the content of the letter is written as plain text.

## Configuration guide

In addition to the actual content a typical letter also contains additional information, such as the sender's and recipient's addresses, a date, and so on. From now on we refer to this additional data as letter metadata.

A special group of letter metadata control the appearance of the letter, such as the presence of foldmarks or a back address. These are called letter options.

### Setting letter metadata and letter options

Letter metadata can be configured in one of three ways, listed below from the most specific to the most general:

1. Using Org option lines, as show in the simple letter example above,
2. By setting Emacs variables, or
3. In a KOMA-Script Letter Class Option file (LCO file).

It is also possible to define multiple LaTeX classes for different letters in addition to the letter LaTeX class shown above. For example, one could have separate classes for private and business letters.

#### Setting letter metadata in Org option lines

The simplest way to set letter metadata is by using Org option lines as used in the simple letter example above. In the example, these lines are used to set the subject and the date of the letter, the sender's and the recipient's addresses, the opening and closing lines of the letter, and, finally, the sender's signature.

Note that the first option line, #+LATEX_CLASS: my-letter, does not set letter metadata but instead is used to select the letter LaTeX class we defined above. The #+LATEX_CLASS: option line is mandatory for the KOMA letter exporter.

Letter options are set using an #+OPTIONS: line in the same manner as other Org mode export options.

A full list of KOMA letter metadata settings is provided below.

Setting letter metadata by Org option lines take precedence over the other two ways of setting letter metadata. Thus, you can set default letter metadata using Emacs variables or in an LCO file (see below) and overwrite these defaults for an individual letter using Org option lines.

If you define a letter below an Org heading, you must use Org properties inside a :PROPERTIES: drawer and prefix every option property with the string EXPORT_. See the chapter Export options in the Org manual for details.

#### Setting letter metadata in Emacs variables

Letter metadata can also be set using Emacs variables. For example, the Emacs Lisp snippet below sets the letter's closing line:

(setq org-koma-letter-closing "See you soon,")


A full list of KOMA letter metadata settings is provided below.

Letter metadata set by Emacs variables take precedence over letter metadata defined in LCO files but can be overwritten for an individual letter (or a file) by setting letter metadata in Org option lines.

#### Setting letter metadata in LCO files

As a third way, letter metadata can be set in so-called letter class option files (LCO files) . LCO files are regular TeX files which are included in the TeX source of the letter. Consequently, one has access to the entirety of KOMA options in LCO files and can also include other LaTeX code. For more information about LCO files, see the KOMA-Script documentation.

LCO files are set by the #+LCO: option line or the Emacs variable org-koma-letter-class-option-file. KOMA-Script comes with a variety of pre-made LCO files, such as DIN for German letters, NF for French letters, or UScommercial9 for US-American letters.

Letter metadata set in LCO files can be overwritten globally by setting letter metadata in Emacs variables or for an individual letter or file by setting letter metadata in Org option lines.

LCO files are especially convenient for setting letter metadata which is fairly constant across multiple letters, e.g., the sender's address and banking information.

The following LCO file, called DefaultAddress.lco, sets the default address. It can loaded using the Org option line #+LCO: DefaultAddress (without the .lco extension).

% Default letter configuration file

\setkomavar{fromname}{Jane Doe}
\setkomavar{fromaddress}{Some Street 1\\12345 Some City}
\setkomavar{fromemail}{jane.doe@email.com}
\setkomavar{fromphone}{(555) 526-3363}
\setkomavar{signature}{\usekomavar{fromname}}


The following LCO file, called Banking.lco, configures a footer with banking information. To load it together with the default address defined above one can use the Org option line #+LCO: DefaultAddress Banking.

% Banking information configuration file
\ProvidesFile{Banking.lco}

% Banking information in the footer
\setkomavar{frombank}{Jane Doe\\Account number: 12\,345\,678\\Somebank\\Bank code number: 876\,543\,21}
\setkomavar{firstfoot}{%
\footnotesize
\parbox[b]{\linewidth}{%
\centering\def\\{ \textbullet{} }\usekomavar{frombank}%
}%
}


Custom LCO files must be placed in a directory where LaTeX will find them. On Linux, this defaults to ~/texmf/tex/latex. On OS X, use ~/Library/texmf/tex/latex instead. These paths can be configured using the following command:

tlmgr conf texmf TEXMFHOME /some/path


You can test whether foo.lco is recognized by TeX Live by running the commmand kpsewhich foo.lco. After adding a file to the TeX Live path you may have to run mktexlsr.

### List of KOMA letter metadata settings

This section lists all Org option lines, Emacs variables, and the corresponding KOMA variables or options that control the behavior of the KOMA letter exporter.

#### List of KOMA letter metadata

The following letter metadata can be set by respective Org option lines. In general, they correspond to a LaTeX command such as:

\setkomavar{<KOMA variable>}{<value>}

Option line Emacs variable KOMA variable Default value Description
#+LCO: org-koma-letter-class-option-file   DIN The default LCO file.
#+TITLE:   subject Empty1 The letter's subject.
#+DATE:   date Today's date The letter's date stamp.
#+PLACE: org-koma-letter-place place nil The letter's place stamp.
#+AUTHOR: org-koma-letter-sender fromname value of user-full-name The sender's name.
#+FROM_ADDRESS: org-koma-letter-from-address fromaddress nil The sender's address.2
#+PHONE_NUMBER: org-koma-letter-phone fromphone nil The sender's phone number.
#+EMAIL: org-koma-letter-email fromemail value of user-mail-address The sender's email.
#+TO_ADDRESS:       The recipient's address.2, 3
#+OPENING: org-koma-letter-opening   nil The opening line of the letter.4
#+CLOSING: org-koma-letter-closing   nil The closing line of the letter.4
#+SIGNATURE: org-koma-letter-signature signature nil The sender's signature.

#### List of KOMA letter options

The following letter options can be set in an #+OPTIONS: line. In general, they correspond to a LaTeX command such as:

\KOMAoption{<KOMA option>}{<value>}

Option Emacs variable KOMA option Default value Accepted values Description
backaddress org-koma-letter-use-backaddress backaddress t t or nil Print the sender's address in a small line above the recipient's address.
phone org-koma-letter-use-phone fromphone t t or nil Print the sender's phone.
email org-koma-letter-use-email fromemail t t or nil Print the sender's email.
foldmarks org-koma-letter-use-foldmarks foldmarks true any string5 or nil Print foldmarks.
subject org-koma-letter-use-subject subject untitled any string5 or nil If and how to print the letter's subject line.
place org-koma-letter-use-place   t t or nil Print the letter's place stamp.

## Footnotes:

1

If the letter is exported below an Org headline, the default subject contains the Org headline text.

2

The options lines #+FROM_ADDRESS: and #+TO_ADDRESS: can be used multiple times.

3

The recipient's address must be different for every letter. Therefore one cannot set a default value using Emacs variables or LCO files.

4

The options lines #+OPENING: and #+CLOSING: cannot be set in an LCO file.

5

See the KOMA script documentation for a list of accepted values.

Documentation from the http://orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.