Browse Source

Updated tutorial for ox-koma-letter

Rasmus 7 years ago
parent
commit
c42c362f3e

+ 1 - 2
exporters/koma-letter-example.org

@@ -1,5 +1,4 @@
-#+LATEX_CLASS: my-letter
-#+TITLE: A simple letter
+#+SUBJECT: A simple letter
 #+DATE: April 22, 2013
 #+AUTHOR: Jane Doe
 #+FROM_ADDRESS: Some Street 1

+ 208 - 143
exporters/koma-letter-export.org

@@ -1,17 +1,17 @@
 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc todo:nil
 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
-#+TAGS:       Write(w) Update(u) Fix(f) Check(c) 
-#+TITLE:      Creating letters with KOMA =scrlttr2=
-#+AUTHOR:     Viktor Rosenfeld
+#+TAGS:       Write(w) Update(u) Fix(f) Check(c)
+#+TITLE:      Creating letters with KOMA-Script =scrlttr2= and Org-mode
+#+AUTHOR:     Viktor Rosenfeld and Rasmus Pank Roulund
 #+EMAIL:      v.rosenfeld@gmx.de
 #+LANGUAGE:   en
 #+PRIORITIES: A C B
 #+CATEGORY:   worg
 
 This tutorial describes the necessary steps to produce beautiful
-letters using Org-mode's LaTeX exporter and KOMA-Script's =scrlttr2=
-class.
+letters using the Org-mode LaTeX exporter and the KOMA-Script
+=scrlttr2= letter class.
 
 * DONE Quick start guide
 
@@ -19,50 +19,66 @@ class.
 
 The code in this tutorial depends on the following:
 
-- Org-mode version 8.0 or greater.
-- A LaTeX installation including KOMA-Script, e.g., [[http://www.tug.org/texlive/][TeX Live]].
+- Org-mode version 8.0 or greater (part of Emacs 24.4).
+- A LaTeX installation including [[http://www.ctan.org/pkg/koma-script][KOMA-Script]], e.g., [[http://www.tug.org/texlive/][TeX Live]].
 
 *Note*: The information in this tutorial depends on functionality that
-has not yet been released. You can either [[http://orgmode.org/worg/org-faq.html#keeping-current-with-Org-mode-development][use the latest development version from the Org-mode git repository]] or [[http://orgmode.org/cgit.cgi/org-mode.git/plain/contrib/lisp/ox-koma-letter.el][download a current version
-of the KOMA letter exporter]] and install it in =contrib/lisp=. It is
-also strongly recommended to read the comments at the beginning of [[http://orgmode.org/cgit.cgi/org-mode.git/plain/contrib/lisp/ox-koma-letter.el][the
-file]] for information or changes that have not yet been documented
-here.
+has not yet been released and it not part of Emacs. You can either [[http://orgmode.org/worg/org-faq.html#keeping-current-with-Org-mode-development][use
+the latest development version from the Org-mode git repository]] or
+[[http://orgmode.org/cgit.cgi/org-mode.git/plain/contrib/lisp/ox-koma-letter.el][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 [[http://orgmode.org/cgit.cgi/org-mode.git/plain/contrib/lisp/ox-koma-letter.el][the file]] for information or changes that
+have not yet been documented here.
 
-** DONE Minimal configuration of the KOMA letter exporter
+** DONE Minimal configuration of the KOMA-Script letter exporter
 
-To use the KOMA letter exporter, you have to add it to Emacs' load
+To use the KOMA-Script 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).
+(the KOMA-Script 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
+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:
+   #+BEGIN_SRC emacs-lisp
+   (add-to-list 'load-path "/path/to/org-mode/contrib/lisp")
+   #+END_SRC
 
+2. Activate the KOMA-Script letter exporter by adding the following to
+   your Emacs configuration:
    #+BEGIN_SRC emacs-lisp
-   (add-to-list 'load-path "~/path/to/org-mode/contrib/lisp" t)
+   (eval-after-load 'ox '(require 'ox-koma-letter))
    #+END_SRC
 
-2. Activate the KOMA letter exporter by adding the following to your
-   Emacs configuration:
+3. <<letter-class-definition>> 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:
 
    #+BEGIN_SRC emacs-lisp
-   (require 'ox-koma-letter)
+     (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")))
    #+END_SRC
 
-3. <<letter-class-definition>> Configure a LaTeX class for the LaTeX
-   exporter to use for the export of KOMA letters by adding the
-   following to your Emacs configuration:
+   A more complicated example is presented in the commentary section
+   of [[http://orgmode.org/cgit.cgi/org-mode.git/plain/contrib/lisp/ox-koma-letter.el][=ox-koma-script.el=]].
 
+   Note that you may have to add the LaTeX Babel package to you
+   preamble, e.g. as
    #+BEGIN_SRC emacs-lisp
-     (add-to-list 'org-latex-classes
-                  '("my-letter"
-                    "\\documentclass\{scrlttr2\}
-     \\usepackage[english]{babel}
-     \[NO-DEFAULT-PACKAGES]
-     \[NO-PACKAGES]
-     \[EXTRA]"))
+     (eval-after-load 'ox-latex
+       '(add-to-list 'org-latex-packages-alist '("AUTO" "babel" t) t))
    #+END_SRC
 
    For more information about this step, refer to the documentation of
@@ -71,18 +87,39 @@ path, activate it, and configure a LaTeX class for the LaTeX exporter
 
 ** DONE 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 [[http://orgmode.org/worg/sources/exporters/koma-letter-example.org][download the KOMA
-letter example]] and you can also [[http://orgmode.org/worg/images/ox-koma-letter/koma-letter-example.pdf][download the example PDF letter]].
+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 [[http://orgmode.org/worg/sources/exporters/koma-letter-new-example.org][download the KOMA letter
+example]] and you can also [[http://orgmode.org/worg/images/ox-koma-letter/koma-letter-new-example.pdf][download the example PDF letter]].
+
+#+INCLUDE: "koma-letter-new-example.org" src org
+
+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.
 
-#+INCLUDE: "koma-letter-example.org" src org
+The address of the receiver is specified in the [[*%20List%20of%20special%20headings][special heading]]  with
+the =:to:= tag.  Note that the headline text is arbitrary and ignored.
 
-The first line selects the [[letter-class-definition][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.
+The main letter is the first non-special heading[fn:1].  Notice that
+the text of this headline also serves as the opening of the letter.
+
+Finally, the 'backmatter' printed after the esignature are defined in
+the tree [[*%20List%20of%20special%20headings][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
+=[[http://www.ctan.org/pkg/pdfpages][pdfpages=]].
+
+=ox-koma-letter.el= also supports an alternative syntax that relies
+less on headings as illustrated by the example in this [[http://orgmode.org/worg/sources/exporters/koma-letter-example.org][Org-file]] and
+the corresponding [[http://orgmode.org/worg/images/ox-koma-letter/koma-letter-example.pdf][pdf]].
+
+When composing new letters it may be useful to start with the template
+access by typing =C-c C-e
 
 * DONE Configuration guide
 
@@ -101,37 +138,35 @@ 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 [[*A%20simple%20letter%20example][simple letter example]] above,
-2. By setting Emacs variables, or
-3. In a KOMA-Script Letter Class Option file (LCO file).
+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.
+
+*** DONE Multiple LaTeX Classes
 It is also possible to define multiple LaTeX classes for different
-letters in addition to the [[letter-class-definition][letter LaTeX class]] shown above. For
-example, one could have separate classes for private and business
-letters.
+types of letters using the method used [[letter-class-definition][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=.
 
 *** DONE Setting letter metadata in Org option lines
 
-The simplest way to set letter metadata is by using Org option lines
-as used in the [[*A%20simple%20letter%20example][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-class-definition][letter LaTeX
-class]] we defined above. /The/ =#+LATEX_CLASS:= /option line is
-mandatory for the KOMA letter exporter./
+A simple way to set letter metadata on-the-fly is by using Org option
+lines as used in the [[*A%20simple%20letter%20example][simple letter example]] above where we used both
+special headings and keywords.
 
-Letter options are set using an =#+OPTIONS:= line in the same manner
-as other [[http://orgmode.org/manual/Export-options.html][Org mode export options]].
+Some letter options are set using an =#+OPTIONS:= line in the same
+manner as other [[http://orgmode.org/manual/Export-options.html][Org mode export options]].
 
-A full [[*List%20of%20KOMA%20letter%20meta%20data%20settings][list of KOMA letter metadata settings]] is provided below.
+A [[*List%20of%20KOMA%20letter%20meta%20data%20settings][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.
+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).  Therefor, you can tweak your default letter options in the
+fil.e
 
 If you define a letter below an Org heading, you must use Org
 properties inside a =:PROPERTIES:= drawer and prefix every option
@@ -140,44 +175,46 @@ the Org manual]] for details.
 
 *** DONE 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:
+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:
 
 #+BEGIN_SRC emacs-lisp
-(setq org-koma-letter-closing "See you soon,")
+  (setq org-koma-letter-closing "See you soon,"
+        org-koma-letter-from-address "Verona")
 #+END_SRC
 
-A full [[*List%20of%20KOMA%20letter%20meta%20data%20settings][list of KOMA letter metadata settings]] is provided below.
+A [[*List%20of%20KOMA%20letter%20meta%20data%20settings][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%20letter%20meta%20data%20in%20Org%20option%20lines][setting letter metadata in Org
-option lines]].
 
 *** DONE 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
+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
-[[http://www.ctan.org/pkg/koma-script][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%20letter%20meta%20data%20in%20Emacs%20variables][setting letter metadata in Emacs variables]] or for an individual
-letter or file by [[*Setting%20letter%20meta%20data%20in%20Org%20option%20lines][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.
+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 [[http://www.ctan.org/pkg/koma-script][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 [[*Setting%20letter%20meta%20data%20in%20Emacs%20variables][letter metadata set in
+Emacs variables]] but not [[*Setting%20letter%20meta%20data%20in%20Org%20option%20lines][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, and 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= 
+address. It can loaded using the Org option line =#+LCO: DefaultAddress=
 (without the =.lco= extension).
 
 #+BEGIN_SRC latex :exports code
@@ -198,37 +235,40 @@ defined above one can use the Org option line =#+LCO: DefaultAddress
 Banking=.
 
 #+BEGIN_SRC latex :exports code
-% 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}% 
-  }%
-}
+  % 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}}}
 #+END_SRC
 
 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:
-
+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:
 #+BEGIN_SRC sh
-tlmgr conf texmf TEXMFHOME /some/path
+tlmgr conf texmf TEXMFHOME ~/some/path
 #+END_SRC
 
 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
+the command =kpsewhich foo.lco=. After adding a file to the TeX Live
 path you may have to run =mktexlsr=.
 
-** DONE List of KOMA letter metadata settings
+** DONE 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
+#+BEGIN_EXAMPLE
+M-x custromize-group org-export-koma-letter.
+#+END_EXAMPLE
 
-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.
 
 *** DONE List of KOMA letter metadata
 
@@ -239,20 +279,22 @@ lines. In general, they correspond to a LaTeX command such as:
 \setkomavar{<KOMA variable>}{<value>}
 #+END_SRC
 
-| Option line       | Emacs variable                      | KOMA variable | Default value                | Description                           |
-|-------------------+-------------------------------------+---------------+------------------------------+---------------------------------------|
-| =#+LCO:=          | =org-koma-letter-class-option-file= |               | =NF=                         | The default LCO file.                 |
-| =#+TITLE:=        |                                     | =subject=     | Empty[fn:1]                  | The letter's subject.                 |
-| =#+DATE:=         |                                     | =date=        | Today's date                 | The letter's date stamp.              |
-| =#+PLACE:=        | =org-koma-letter-place=             | =place=       | Empty                        | 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= | Empty                        | The sender's address.[fn:2]           |
-| =#+PHONE_NUMBER:= | =org-koma-letter-phone=             | =fromphone=   | Empty                        | 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.[fn:2][fn:3]  |
-| =#+OPENING:=      | =org-koma-letter-opening=           |               | Empty                        | The opening line of the letter.[fn:4] |
-| =#+CLOSING:=      | =org-koma-letter-closing=           |               | Empty                        | The closing line of the letter.[fn:4] |
-| =#+SIGNATURE:=    | =org-koma-letter-signature=         | =signature=   | Empty                        | The sender's signature.               |
+| 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.[fn:3]              |
+| =#+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.[fn:3]           |
+| =#+OPENING:=      | =org-koma-letter-opening=           |                      | The opening line of the letter.[fn:5]    |
+| =#+CLOSING:=      | =org-koma-letter-closing=           |                      | The closing line of the letter.[fn:5]    |
+| =#+SIGNATURE:=    | =org-koma-letter-signature=         | =signature=          | The sender's signature.                  |
+| =#+LATEX_CLASS:=  | =org-koma-letter-default-class=     |                      | Corresponds to =org-latex-default-class= |
 
 *** DONE List of KOMA letter options
 
@@ -263,30 +305,53 @@ general, they correspond to a LaTeX command such as:
 \KOMAoption{<KOMA option>}{<value>}
 #+END_SRC
 
-| Option        | Emacs variable                    | KOMA option   | Default value | Accepted values                     | Description                                                               |
-|---------------+-----------------------------------+---------------+---------------+-------------------------------------+---------------------------------------------------------------------------|
-| =backaddress= | =org-koma-letter-use-backaddress= | =backaddress= | =nil=         | =t= or =nil=                        | Print the sender's address in a small line above the recipient's address. |
-| =phone=       | =org-koma-letter-use-phone=       | =fromphone=   | =nil=         | =t= or =nil=                        | Print the sender's phone.                                                 |
-| =email=       | =org-koma-letter-use-email=       | =fromemail=   | =nil=         | =t= or =nil=                        | Print the sender's email.                                                 |
-| =foldmarks=   | =org-koma-letter-use-foldmarks=   | =foldmarks=   | =t=           | list of symbols[fn:5], =t= or =nil= | Print foldmarks.                                                          |
-| =subject=     | =org-koma-letter-subject-format=  | =subject=     | =t=           | list of symbols[fn:5], =t= 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.                                           |
+| 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.                                      |
+
+*** DONE List of 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 [[*%20A%20simple%20letter%20example][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
 
-[fn:1] If the letter is exported below an Org headline, the default
+[fn:1] A special headings in =ox-koma-letter= is a heading with a
+recognized tag.  These headings are treated specially.
+
+[fn:2] If the letter is exported below an Org headline, the default
 subject contains the Org headline text.
 
-[fn:2] The options lines =#+FROM_ADDRESS:= and =#+TO_ADDRESS:= can be
-used multiple times.
+[fn:3] The options lines =#+FROM_ADDRESS:= and =#+TO_ADDRESS:= can be
+used multiple times and may also be specified using headlines cf. the
+[[*%20A%20simple%20letter%20example][example]] above.
 
-[fn:3] The recipient's address must be different for every
-letter. Therefore one cannot set a default value using Emacs variables
-or LCO files.
 
-[fn:4] The options lines =#+OPENING:= and =#+CLOSING:= cannot be set
+[fn:5] The options lines =#+OPENING:= and =#+CLOSING:= cannot be set
 in an LCO file.
 
-[fn:5] See the [[http://www.komascript.de/][KOMA script documentation]] for a list of accepted
+[fn:6] See the [[http://www.komascript.de/][KOMA script documentation]] for a list of accepted
 values.
-

+ 61 - 0
exporters/koma-letter-new-example.org

@@ -0,0 +1,61 @@
+# -*- org-export-allow-bind-keywords: t -*-
+#+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: You may check the KOMA-Script manual to figure out which LCO
+#       file fits the envelope standards of your country.
+
+# NOTE: Change the order of the backletter, use smart quotes and
+#       include backaddress
+#+OPTIONS: after-closing-order:(ps cc encl) ':t backaddress:t subject:centered 
+
+# 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 [[https://en.wikisource.org/wiki/The_Tragedy_of_Romeo_and_Juliet][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

BIN
exporters/koma-letter-new-example.pdf