Creating letters with KOMA-Script scrlttr2 and Org-mode

Table of Contents

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

Quick start guide

Requirements

The code in this tutorial depends on the following:

  • org-mode version 8.0 or greater (part of Emacs 24.4);
  • 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 and it not part of Emacs. You can either use the latest development version from the Org-mode git repository or download a current version of the KOMA-Script letter exporter and install it in your load-path, e.g. contrib/lisp in the Org-tree or ~/.emacs.d/lisp. It is also strongly recommended to read the comments at the beginning of the file for information or changes that have not yet been documented here.

Minimal configuration of the KOMA-Script letter exporter

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

  1. Add the path containing ox-koma-letter.el to the 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")
    
  2. Activate the KOMA-Script letter exporter by adding the following to your Emacs configuration:
    (eval-after-load 'ox '(require 'ox-koma-letter))
    
  3. The KOMA-Script exporter comes with minimal latex class default-koma-letter that is enabled by default. You may add your own customized class, my-letter, as follows:
    (eval-after-load 'ox-koma-letter
      '(progn
         (add-to-list 'org-latex-classes
                      '("my-letter"
                        "\\documentclass\{scrlttr2\}
         \\usepackage[english]{babel}
         \\setkomavar{frombank}{(1234)\\,567\\,890}
         \[DEFAULT-PACKAGES]
         \[PACKAGES]
         \[EXTRA]"))
    
         (setq org-koma-letter-default-class "my-letter")))
    

    A more complicated example is presented in the commentary section of ox-koma-script.el.

    Note that you may have to add the LaTeX Babel package to you preamble, e.g., as

    (eval-after-load 'ox-latex
      '(add-to-list 'org-latex-packages-alist '("AUTO" "babel" t) t))
    

    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 as a KOMA-Script 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. For your convenience, you can download the KOMA letter example and you can also download the example PDF letter.

# -*- org-export-allow-bind-keywords: t -*-
* Preamble                                                         :noexport:
#+TITLE:  Mis-shapen chaos of well-seeming forms!
#+SUBJECT: Or: Org-mode and KOMA-Script Letters
#+DATE: <1580-07-03 Thu>
# NOTE: Check the variable `org-export-date-timestamp-format' for
# formatting.
#+BIND: org-export-date-timestamp-format "%Y"

#+AUTHOR: Romeo
#+CLOSING: Yours truly,
#+PLACE: Verona, Italy

#+LCO: DINmtext
# NOTE: Check the KOMA-Script manual to find a LCO that fits the
#       envelope standards of your country.

#+OPTIONS: after-closing-order:(ps cc encl) ':t backaddress:t subject:centered
# NOTE: Change the order of the backletter, use smart quotes and
#       include backaddress

# Remove the first header
#+LATEX_HEADER: \setkomavar{firsthead}{}

* To-address of the lovely Juliet                                        :to:
# NOTE: New lines are not necessary in TO and FROM
Juliet
House of Capulet
Verona

* From                                                                 :from:
House of Montague
Verona

* Dear Juliet,
# NOTE: Your letter is the first non-special heading.  The title of
# this heading may used as an opening.

#+BEGIN_VERSE
Then plainly know my heart's dear love is set
On the fair daughter of rich Capulet:
As mine on hers, so hers is set on mine;
And all combin'd, save what thou must combine
By holy marriage: when, and where, and how
We met, we woo'd, and made exchange of vow,
I'll tell thee as we pass; but this I pray,
That thou consent to marry us to-day.
#+END_VERSE

* PS                                                                     :ps:
PS: "PS" is not typeset automatically by KOMA-Script


@@latex:\noindent@@ PPS: This is a feature!
* CC                                                                     :cc:
Paris and Lawrence.
* ENCL                                                                 :encl:
See also The Tragedy of Romeo and Juliet
* some arbitrary LaTeX code                                    :after_letter:
#+BEGIN_LaTeX
% here we can place random LaTeX code, e.g. including PDFs via the pdfpages package.
#+END_LaTeX

Since no LaTeX_CLASS has been specified the default class will be used. The first block of lines specify title, subject and date. CLOSING and PLACE specify the closing sentence and the place from which the letter is send.

The address of the receiver is specified in the special heading with the :to: tag. Note that the headline text is arbitrary and ignored.

The main letter is the first non-special heading1. Notice that the text of this headline also serves as the opening of the letter.

Finally, the 'backmatter' printed after the signature are defined in the tree special heading with the tags ps, cc and encl. With the OPTION after-closing-order we can reorder the ordering of the 'backmatter'. The content of the after_letter heading is inserted after \end{letter}. This is useful executing arbitrary latex commands. For instance, we may want to include PDFs via the pdfpages package.

ox-koma-letter.el also supports an alternative syntax that relies less on headings as illustrated by the example in this Org-file and the corresponding pdf.

When composing new letters it may be useful to start with template by typing C-c C-e # and choosing koma-letter.

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 controls 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 four 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 using separate Org LaTeX classes,
  3. by setting Emacs variables, or
  4. in a KOMA-Script Letter Class Option file (LCO file).

We cover these in turn.

Multiple LaTeX Classes

It is possible to define multiple LaTeX classes for different types of letters using the method used above. For example one could add a special Org LaTeX class, say foo-copr, for sending letters to the stakeholders of Foo Corp, that loads the Foo Logo, specifies the footer and so forth. The class is then loaded by inserting #+LATEX_CLASS: foo-corp.

Setting letter metadata in Org option lines

A simple way to set letter metadata on-the-fly is by using Org option lines as used in the simple letter example above where we used both special headings and keywords.

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

A list of KOMA letter metadata settings is provided below.

Metadata set in the file takes the highest priority. Thus, you can set default letter metadata using Emacs variables or in an LCO file (see below). Then, you can tweak your letter options in the file itself.

If you write a letter as a subtree of 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, e.g., in your init-file. For example, the Emacs Lisp snippet below sets the letter's closing line and the location.

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

A list of KOMA letter metadata settings is provided below.

Setting letter metadata in LCO files

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-Script 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: LCO1 LCO2 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 overwrites letter metadata set in Emacs variables but not letter metadata set in the Org file.

LCO files are convenient as modules that can be loaded to access particular setups across letters. Examples include the sender's address, the first footer and header, banking information, or the inclusion of a scanned signature. A particularly useful LaTeX command is \ifkomavarempty{KOMAVAR}{TRUE}{FALSE} that can be used to condition the printed output depending on whether KOMAVAR is set or not. See the example under \setkomavar{frombank} in the KOMA-Script manual (currently page 183).

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
\ProvidesFile{DefaultAddress.lco}

% Default address
\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\usekomavar{frombank}}}

Custom LCO files must be placed in a directory where LaTeX will find them. On GNU/Linux, this defaults to ~/texmf/tex/latex. On OS X, use ~/Library/texmf/tex/latex. In TeX Live, 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 command kpsewhich foo.lco. After adding a file to the TeX Live path you may have to run mktexlsr.

List of KOMA-Script letter metadata settings

This section tries to list all Org option lines, Emacs variables, and the corresponding ox-koma-letter variables or options that control the behavior of the KOMA-Script letter exporter.

To get a complete list of variables please use the Customize interface, e.g. by typing

M-x custromize-group org-export-koma-letter

List of ox-koma-letter 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-Script variable Description
#+LCO: org-koma-letter-class-option-file   The default LCO file.
#+TITLE:   title The title of the letter.
#+SUBJECT:   subject The subject of the letter
#+DATE:   date The time-stamp of the letter.
#+PLACE: org-koma-letter-place place The place of the letter.
#+AUTHOR: org-koma-letter-sender fromname The sender's name.
#+FROM_ADDRESS: org-koma-letter-from-address fromaddress The sender's address.2
#+PHONE_NUMBER: org-koma-letter-phone fromphone The sender's phone number.
#+EMAIL: org-koma-letter-email fromemail The sender's email.
#+TO_ADDRESS:     The recipient's address.2
#+OPENING: org-koma-letter-opening   The opening line of the letter.3
#+CLOSING: org-koma-letter-closing   The closing line of the letter.3
#+SIGNATURE: org-koma-letter-signature signature The sender's signature.
#+LATEX_CLASS: org-koma-letter-default-class   Corresponds to org-latex-default-class

List of ox-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-Script option Description
after-closing-order org-koma-letter-special-tags-after-closing   Order or special headlines such as ps, cc, and encl
after-letter-order org-koma-letter-special-tags-after-letter   Order or special headlines such as after_letter
backaddress org-koma-letter-use-backaddress backaddress Print the sender's address in a line above the recipient's address.
phone org-koma-letter-use-phone fromphone Print the sender's phone.
email org-koma-letter-use-email fromemail Print the sender's email.
foldmarks org-koma-letter-use-foldmarks foldmarks If and how foldmarks are printed.
subject org-koma-letter-subject-format subject If and how to print the letter's subject line.
place org-koma-letter-use-place   Print the letter's place stamp.

List of ox-koma-letter special headings

Special headings may be used to input metadata in ox-koma-letter documents. A special heading is simply a heading with a recognized tag. Their usages were illustrated in the example above. Special headings tags are defined in the variables org-koma-letter-special-tags-in-letter, org-koma-letter-special-tags-after-closing, and org-koma-letter-special-tags-after-letter. Currently the following special headings are recognized.

Tag KOMA-Script Description
to \begin{letter}{to} To-address. Alternative to #+TO_ADDRESS:.
from fromaddress From-address. Alternative to +FROM_ADDRESS:.
ps \ps{} Wrap content in a ps-macro.
cc \cc{} Wrap content in a cc-macro.
encl \encl{} Wrap content in a encl macro.
after_letter   Content is inserted after \end{letter}.

Footnotes:

1

A special headings in ox-koma-letter is a heading with a recognized tag. These headings are treated specially.

2

The options lines #+FROM_ADDRESS: and #+TO_ADDRESS: can be used multiple times and may also be specified using headlines cf. the example above.

3

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

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.