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