10e02fe985e35024d7513c45ff4e29b7fea7f0c6
[worg.git] / exporters / koma-letter-export.org
1 #+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
2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) 
5 #+TITLE:      Creating letters with KOMA =scrlttr2=
6 #+AUTHOR:     Viktor Rosenfeld
7 #+EMAIL:      v.rosenfeld@gmx.de
8 #+LANGUAGE:   en
9 #+PRIORITIES: A C B
10 #+CATEGORY:   worg
11
12 This tutorial describes the necessary steps to produce beautiful
13 letters using Org-mode's LaTeX exporter and KOMA-Script's =scrlttr2=
14 class.
15
16 * DONE Quick start guide
17
18 ** DONE Requirements
19
20 The code in this tutorial depends on the following:
21
22 - Org-mode version 8.0 or greater.
23 - A LaTeX installation including KOMA-Script, e.g., [[http://www.tug.org/texlive/][TeX Live]].
24
25 *Note*: The information in this tutorial depends on functionality that
26 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
27 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
28 of the KOMA letter exporter]] and install it in =contrib/lisp=.
29
30 ** DONE Minimal configuration of the KOMA letter exporter
31
32 To use the KOMA letter exporter, you have to add it to Emacs' load
33 path, activate it, and configure a LaTeX class for the LaTeX exporter
34 (the KOMA letter exporter uses the LaTeX exporter internally).
35
36 1. Add the path containing =ox-koma-letter.el= to Emacs' load
37    path. For example, if you use the version contained in the
38    directory =contrib/lisp= of Org-mode, add the following to your
39    Emacs configuration:
40
41    #+BEGIN_SRC emacs-lisp
42    (add-to-list 'load-path "~/path/to/org-mode/contrib/lisp" t)
43    #+END_SRC
44
45 2. Activate the KOMA letter exporter by adding the following to your
46    Emacs configuration:
47
48    #+BEGIN_SRC emacs-lisp
49    (require 'ox-koma-letter)
50    #+END_SRC
51
52 3. <<letter-class-definition>> Configure a LaTeX class for the LaTeX
53    exporter to use for the export of KOMA letters by adding the
54    following to your Emacs configuration:
55
56    #+BEGIN_SRC emacs-lisp
57 (add-to-list 'org-latex-classes
58              '("my-letter"
59                "\\documentclass\{scrlttr2\}
60 \\usepackage[english]{babel}
61 \[NO-DEFAULT-PACKAGES]
62 \[NO-PACKAGES]
63 \[EXTRA]"))
64    #+END_SRC
65
66    For more information about this step, refer to the documentation of
67    the variables [[http://orgmode.org/worg/doc.html#org-latex-classes][org-latex-classes]], [[http://orgmode.org/worg/doc.html#org-latex-default-packages-alist][org-latex-default-packages-alist]],
68    and [[http://orgmode.org/worg/doc.html#org-latex-packages-alist][org-latex-packages-alist]].
69
70 ** DONE A simple letter example
71
72 Printed below is a minimal Org file that can be exported to a KOMA
73 letter. In this file, press =C-c C-e= to bring up the exporter
74 dispatcher and then press =k o= to export the Org file to a PDF file
75 containing the letter. For your convenience, you can [[http://orgmode.org/worg/sources/exporters/koma-letter-example.org][download the KOMA
76 letter example]] and you can also [[file:~/Desktop/worg/images/ox-koma-letter/koma-letter-example.pdf][download the example PDF letter]].
77
78 #+INCLUDE: "koma-letter-example.org" src org
79
80 The first line selects the [[letter-class-definition][letter LaTeX class]] we defined above. The
81 following lines configure the letter's sender and recipient and other
82 information of the letter. These settings are described in the next
83 section. Finally, the content of the letter is written as plain text.
84
85 * DONE Configuration guide
86
87 In addition to the actual content a typical letter also contains
88 additional information, such as the sender's and recipient's
89 addresses, a date, and so on. From now on we refer to this additional
90 data as /letter metadata/.
91
92 A special group of letter metadata control the appearance of the
93 letter, such as the presence of foldmarks or a back address. These are
94 called /letter options/.
95
96 ** DONE Setting letter metadata and letter options
97
98 Letter metadata can be configured in one of three ways, listed below
99 from the most specific to the most general:
100
101 1. Using Org option lines, as show in the [[*A%20simple%20letter%20example][simple letter example]] above,
102 2. By setting Emacs variables, or
103 3. In a KOMA-Script Letter Class Option file (LCO file).
104
105 It is also possible to define multiple LaTeX classes for different
106 letters in addition to the [[letter-class-definition][letter LaTeX class]] shown above. For
107 example, one could have separate classes for private and business
108 letters.
109
110 *** DONE Setting letter metadata in Org option lines
111
112 The simplest way to set letter metadata is by using Org option lines
113 as used in the [[*A%20simple%20letter%20example][simple letter example]] above. In the example, these
114 lines are used to set the subject and the date of the letter, the
115 sender's and the recipient's addresses, the opening and closing lines
116 of the letter, and, finally, the sender's signature.
117
118 Note that the first option line, =#+LATEX_CLASS: my-letter=, does not
119 set letter metadata but instead is used to select the [[letter-class-definition][letter LaTeX
120 class]] we defined above. /The/ =#+LATEX_CLASS:= /option line is
121 mandatory for the KOMA letter exporter./
122
123 Letter options are set using an =#+OPTIONS:= line in the same manner
124 as other [[http://orgmode.org/manual/Export-options.html][Org mode export options]].
125
126 A full [[*List%20of%20KOMA%20letter%20meta%20data%20settings][list of KOMA letter metadata settings]] is provided below.
127
128 Setting letter metadata by Org option lines take precedence over the
129 other two ways of setting letter metadata. Thus, you can set default
130 letter metadata using Emacs variables or in an LCO file (see below)
131 and overwrite these defaults for an individual letter using Org option
132 lines.
133
134 If you define a letter below an Org heading, you must use Org
135 properties inside a =:PROPERTIES:= drawer and prefix every option
136 property with the string =EXPORT_=. See the [[http://orgmode.org/manual/Export-options.html][chapter Export options in
137 the Org manual]] for details.
138
139 *** DONE Setting letter metadata in Emacs variables
140
141 Letter metadata can also be set using Emacs variables. For example,
142 the Emacs Lisp snippet below sets the letter's closing line:
143
144 #+BEGIN_SRC emacs-lisp
145 (setq org-koma-letter-closing "See you soon,")
146 #+END_SRC
147
148 A full [[*List%20of%20KOMA%20letter%20meta%20data%20settings][list of KOMA letter metadata settings]] is provided below.
149
150 Letter metadata set by Emacs variables take precedence over letter
151 metadata defined in LCO files but can be overwritten for an
152 individual letter (or a file) by [[*Setting%20letter%20meta%20data%20in%20Org%20option%20lines][setting letter metadata in Org
153 option lines]].
154
155 *** DONE Setting letter metadata in LCO files
156
157 As a third way, letter metadata can be set in so-called letter class
158 option files (LCO files) . LCO files are regular TeX files which are
159 included in the TeX source of the letter. Consequently, one has access
160 to the entirety of KOMA options in LCO files and can also include
161 other LaTeX code. For more information about LCO files, see the
162 [[http://www.ctan.org/pkg/koma-script][KOMA-Script documentation]].
163
164 LCO files are set by the =#+LCO:= option line or the Emacs variable
165 =org-koma-letter-class-option-file=. KOMA-Script comes with a variety
166 of pre-made LCO files, such as =DIN= for German letters, =NF= for
167 French letters, or =UScommercial9= for US-American letters.
168
169 Letter metadata set in LCO files can be overwritten globally by
170 [[*Setting%20letter%20meta%20data%20in%20Emacs%20variables][setting letter metadata in Emacs variables]] or for an individual
171 letter or file by [[*Setting%20letter%20meta%20data%20in%20Org%20option%20lines][setting letter metadata in Org option lines]].
172
173 LCO files are especially convenient for setting letter metadata which
174 is fairly constant across multiple letters, e.g., the sender's address
175 and banking information.
176
177 The following LCO file, called =DefaultAddress.lco=, sets the default
178 address. It can loaded using the Org option line =#+LCO:¬†DefaultAddress= 
179 (without the =.lco= extension).
180
181 #+BEGIN_SRC latex :exports code
182 % Default letter configuration file
183 \ProvidesFile{DefaultAddress.lco}
184
185 % Default address
186 \setkomavar{fromname}{Jane Doe}
187 \setkomavar{fromaddress}{Some Street 1\\12345 Some City}
188 \setkomavar{fromemail}{jane.doe@email.com}
189 \setkomavar{fromphone}{(555) 526-3363}
190 \setkomavar{signature}{\usekomavar{fromname}}
191 #+END_SRC
192
193 The following LCO file, called =Banking.lco=, configures a footer with
194 banking information. To load it together with the default address
195 defined above one can use the Org option line =#+LCO: DefaultAddress
196 Banking=.
197
198 #+BEGIN_SRC latex :exports code
199 % Banking information configuration file
200 \ProvidesFile{Banking.lco}
201
202 % Banking information in the footer
203 \setkomavar{frombank}{Jane Doe\\Account number: 12\,345\,678\\Somebank\\Bank code number: 876\,543\,21}
204 \setkomavar{firstfoot}{% 
205   \footnotesize
206   \parbox[b]{\linewidth}{%
207     \centering\def\\{ \textbullet{} }\usekomavar{frombank}% 
208   }%
209 }
210 #+END_SRC
211
212 Custom LCO files must be placed in a directory where LaTeX will find
213 them. On Linux, this defaults to =~/texmf/tex/latex=. On OS X, use
214 =~/Library/texmf/tex/latex= instead. These paths can be configured
215 using the following command:
216
217 #+BEGIN_SRC sh
218 tlmgr conf texmf TEXMFHOME /some/path
219 #+END_SRC
220
221 You can test whether =foo.lco= is recognized by TeX Live by running
222 the commmand =kpsewhich foo.lco=. After adding a file to the TeX Live
223 path you may have to run =mktexlsr=.
224
225 ** DONE List of KOMA letter metadata settings
226
227 This section lists all Org option lines, Emacs variables, and the
228 corresponding KOMA variables or options that control the behavior of
229 the KOMA letter exporter.
230
231 *** DONE List of KOMA letter metadata
232
233 The following letter metadata can be set by respective Org option
234 lines. In general, they correspond to a LaTeX command such as:
235
236 #+BEGIN_SRC latex :exports code
237 \setkomavar{<KOMA variable>}{<value>}
238 #+END_SRC
239
240 | Option line       | Emacs variable                      | KOMA variable | Default value | Description                           |
241 |-------------------+-------------------------------------+---------------+---------------+---------------------------------------|
242 | =#+LCO:=          | =org-koma-letter-class-option-file= |               | =DIN=         | The default LCO file.                 |
243 | =#+TITLE:=        |                                     | =subject=     | Empty[fn:1]   | The letter's subject.                 |
244 | =#+DATE:=         |                                     | =date=        | Today's date  | The letter's date stamp.              |
245 | =#+PLACE:=        | =org-koma-letter-place=             | =place=       | =nil=         | The letter's place stamp.             |
246 | =#+SENDER:=       | =org-koma-letter-sender=            | =fromname=    | =nil=         | The sender's name.                    |
247 | =#+FROM_ADDRESS:= | =org-koma-letter-from-address=      | =fromaddress= | =nil=         | The sender's address.[fn:2]           |
248 | =#+PHONE_NUMBER:= | =org-koma-letter-phone=             | =fromphone=   | =nil=         | The sender's phone number.            |
249 | =#+EMAIL:=        | =org-koma-letter-email=             | =fromemail=   | =nil=         | The sender's email.                   |
250 | =#+TO_ADDRESS:=   |                                     |               |               | The recipient's address.[fn:2][fn:3]  |
251 | =#+OPENING:=      | =org-koma-letter-opening=           |               | =nil=         | The opening line of the letter.[fn:4] |
252 | =#+CLOSING:=      | =org-koma-letter-closing=           |               | =nil=         | The closing line of the letter.[fn:4] |
253 | =#+SIGNATURE:=    | =org-koma-letter-signature=         | =signature=   | =nil=         | The sender's signature.               |
254
255 *** DONE List of KOMA letter options
256
257 The following letter options can be set in an =#+OPTIONS:= line. In
258 general, they correspond to a LaTeX command such as:
259
260 #+BEGIN_SRC latex :exports code
261 \KOMAoption{<KOMA option>}{<value>}
262 #+END_SRC
263
264 | Option        | Emacs variable                    | KOMA option   | Default value | Accepted values           | Description                                                               |
265 |---------------+-----------------------------------+---------------+---------------+---------------------------+---------------------------------------------------------------------------|
266 | =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. |
267 | =phone=       | =org-koma-letter-use-phone=       | =fromphone=   | =t=           | =t= or =nil=              | Print the sender's phone.                                                 |
268 | =email=       | =org-koma-letter-use-email=       | =fromemail=   | =t=           | =t= or =nil=              | Print the sender's email.                                                 |
269 | =foldmarks=   | =org-koma-letter-use-foldmarks=   | =foldmarks=   | =true=        | any string[fn:5] or =nil= | Print foldmarks.                                                          |
270 | =subject=     | =org-koma-letter-use-subject=     | =subject=     | =untitled=    | any string[fn:5] or =nil= | If and how to print the letter's subject line.                            |
271 | =place=       | =org-koma-letter-use-place=       |               | =t=           | =t= or =nil=              | Print the letter's place stamp.                                           |
272
273 * Footnotes
274
275 [fn:1] If the letter is exported below an Org headline, the default
276 subject contains the Org headline text.
277
278 [fn:2] The options lines =#+FROM_ADDRESS:= and =#+TO_ADDRESS:= can be
279 used multiple times.
280
281 [fn:3] The recipient's address must be different for every
282 letter. Therefore one cannot set a default value using Emacs variables
283 or LCO files.
284
285 [fn:4] The options lines =#+OPENING:= and =#+CLOSING:= cannot be set
286 in an LCO file.
287
288 [fn:5] See the [[http://www.komascript.de/][KOMA script documentation]] for a list of accepted
289 values.
290