Creating letters with KOMA-Script scrlttr2 and Org-mode

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.

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, add the following to your Emacs configuration:

   (add-to-list 'load-path "/path/to/org-mode/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.

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.

* Preamble                                                         :noexport:

#+TITLE:  Mis-shapen chaos of well-seeming forms!
#+DATE: 1580
#+AUTHOR: Romeo

# This file is released by its authors and contributors under the GNU
# Free Documentation license v1.3 or later, code examples are released
# under the GNU General Public License v3 or later.

#+SUBJECT: Or: org-mode and KOMA-Script letters
#+PLACE: Verona, Italy

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

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

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

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

* From                                                                 :from:
House of Montague
Verona
* Location                                                         :location:
#+LATEX_HEADER: \usepackage{tikz}
#+BEGIN_CENTER
*Montague*
#+BEGIN_EXPORT latex
\tikz \draw (0,0) --+ (0,-1)
       arc [radius=1, start angle=-180, end angle=0]
       --+ (0,1) -- cycle
       node [below=1.5em,midway] {\bfseries M};
#+END_EXPORT
#+END_CENTER

* 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

* Yours truly,                                                      :closing:
Romeo of House Montague
* some arbitrary LaTeX code                              :my_after_signature:
#+BEGIN_EXPORT latex
% this special heading was added dynamically.
#+END_EXPORT
* 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 more arbitrary LaTeX code                               :after_letter:
#+BEGIN_EXPORT latex
% here we can place random LaTeX code, e.g. including PDFs via the pdfpages package.
#+END_EXPORT

Since no LaTeX_CLASS has been specified the default class will be used. The first block of lines specify title, subject and date. 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 heading¹. Notice that the text of this headline also serves as the opening of the letter. The closing of the letter is set via the closing special heading. Note that closing statement is the headline title and the signature is the content.

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.

org-koma-letter.el exports a LaTeX document utilizing the scrlttr2 class of KOMA-Script. The document class is described in great details in chapter 4 of the KOMA-Script manual. If you have TeXLive you can open the manual with the command texdoc KOMA-Script and with MiKTeX one might call mthelp KOMA-Script.

Elements such as the address-field is automatically typeset using user-provided metadata, or variables, such as address, sender name etc. A full list of variables are available in table 4.1 and an illustration of placement of variables is shown in figure 4.9, both the in KOMA-Script manual. A subset of these are supported directly by ox-koma-letter.el.

Placement of elements is typically defined by a LCO file. If, for instance, the DIN LCO file is loaded, letters are typeset to fit German DIN envelopes. See table 4.18 in the KOMA-Script manual for default classes.

You can customize the look of your letter by writing your own LCO files and including them with the #+LCO: keyword. See Setting letter metadata in LCO files.

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.

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