1 ;;; ox-koma-letter.el --- KOMA Scrlttr2 Back-End for Org Export Engine
3 ;; Copyright (C) 2007-2012 Free Software Foundation, Inc.
5 ;; Author: Nicolas Goaziou <n.goaziou AT gmail DOT com>
6 ;; Alan Schmitt <alan.schmitt AT polytechnique DOT org>
7 ;; Keywords: org, wp, tex
9 ;; This program is free software: you can redistribute it and/or modify
10 ;; it under the terms of the GNU General Public License as published by
11 ;; the Free Software Foundation, either version 3 of the License, or
12 ;; (at your option) any later version.
14 ;; This program is distributed in the hope that it will be useful,
15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 ;; GNU General Public License for more details.
19 ;; You should have received a copy of the GNU General Public License
20 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
24 ;; This library implements a KOMA Scrlttr2 back-end, derived from the
27 ;; Depending on the desired output format, three commands are provided
28 ;; for export: `org-koma-letter-export-as-latex' (temporary buffer),
29 ;; `org-koma-letter-export-to-latex' ("tex" file) and
30 ;; `org-koma-letter-export-to-pdf' ("pdf" file).
32 ;; On top of buffer keywords supported by `latex' back-end (see
33 ;; `org-latex-options-alist'), this back-end introduces the following
34 ;; keywords: "CLOSING" (see `org-koma-letter-closing'), "FROM_ADDRESS"
35 ;; (see `org-koma-letter-from-address'), "LCO" (see
36 ;; `org-koma-letter-class-option-file'), "OPENING" (see
37 ;; `org-koma-letter-opening'), "PHONE_NUMBER" (see
38 ;; `org-koma-letter-phone-number'), "SIGNATURE" (see
39 ;; `org-koma-letter-signature') and "TO_ADDRESS".
41 ;; You will need to add an appropriate association in
42 ;; `org-latex-classes' in order to use the KOMA Scrlttr2 class. For
43 ;; example, you can use the following code:
45 ;; (add-to-list 'org-latex-classes
47 ;; "\\documentclass\[%
55 ;; fromphone=true\]\{scrlttr2\}
56 ;; \[DEFAULT-PACKAGES]
60 ;; Then, in your Org document, be sure to require the proper class
63 ;; #+LATEX_CLASS: my-letter
71 ;;; User-Configurable Variables
73 (defgroup org-export-koma-letter nil
74 "Options for exporting to KOMA scrlttr2 class in LaTeX export."
75 :tag
"Org Koma-Letter"
78 (defcustom org-koma-letter-class-option-file
"NF"
79 "Letter Class Option File."
80 :group
'org-export-koma-letter
83 (defcustom org-koma-letter-author
'user-full-name
86 This variable defaults to calling the function `user-full-name'
87 which just returns the current `user-full-name'. Alternatively a
88 string, nil or a function may be given. Functions must return a
90 :group
'org-export-koma-letter
91 :type
'(radio (function-item user-full-name
)
96 (defcustom org-koma-letter-email
'org-koma-letter-email
97 "The sender's email address.
99 This variable defaults to the value `org-koma-letter-email' which
100 returns `user-mail-address'. Alternatively a string, nil or a
101 function may be given. Functions must return a string."
102 :group
'org-export-koma-letter
103 :type
'(radio (function-item org-koma-letter-email
)
108 (defcustom org-koma-letter-from-address nil
109 "Sender's address, as a string."
110 :group
'org-export-koma-letter
113 (defcustom org-koma-letter-phone-number nil
114 "Sender's phone number, as a string."
115 :group
'org-export-koma-letter
118 (defcustom org-koma-letter-place nil
119 "Place from which the letter is sent."
120 :group
'org-export-koma-letter
123 (defcustom org-koma-letter-opening nil
124 "Letter's opening, as a string."
125 :group
'org-export-koma-letter
128 (defcustom org-koma-letter-closing nil
129 "Koma-Letter's closing, as a string."
130 :group
'org-export-koma-letter
133 (defcustom org-koma-letter-signature nil
134 "String used as the signature."
135 :group
'org-export-koma-letter
138 (defcustom org-koma-letter-use-subject
"untitled"
139 "Use the title as the letter's subject."
140 :group
'org-export-koma-letter
143 (defcustom org-koma-letter-use-backaddress t
144 "Print return address in small line above to address."
145 :group
'org-export-koma-letter
148 (defcustom org-koma-letter-use-foldmarks
"true"
149 "Configure appearence of fold marks.
151 Accepts any valid value for the KOMA-Script `foldmarks' option.
153 Use `foldmarks:true' to activate default fold marks or
154 `foldmarks:nil' to deactivate fold marks."
155 :group
'org-export-koma-letter
158 (defcustom org-koma-letter-use-phone t
159 "Print sender's phone number."
160 :group
'org-export-koma-letter
163 (defcustom org-koma-letter-use-email t
164 "Print sender's email address."
165 :group
'org-export-koma-letter
168 (defcustom org-koma-letter-use-place t
169 "Print the letter's place next to the date."
170 :group
'org-export-koma-letter
173 (defconst org-koma-letter-special-tags-after-closing
175 "Header tags to be inserted after closing")
177 (defconst org-koma-letter-special-tags-after-letter
'("after_letter")
178 "Header tags to be inserted after closing")
180 (defvar org-koma-letter-special-contents nil
"holds special
181 content temporarily.")
187 (org-export-define-derived-backend 'koma-letter
'latex
189 '((:lco
"LCO" nil org-koma-letter-class-option-file
)
190 (:author
"AUTHOR" nil
(org-koma-letter--get-custom org-koma-letter-author
) t
)
191 (:from-address
"FROM_ADDRESS" nil org-koma-letter-from-address newline
)
192 (:phone-number
"PHONE_NUMBER" nil org-koma-letter-phone-number
)
193 (:email
"EMAIL" nil
(org-koma-letter--get-custom org-koma-letter-email
) t
)
194 (:to-address
"TO_ADDRESS" nil nil newline
)
195 (:place
"PLACE" nil org-koma-letter-place
)
196 (:opening
"OPENING" nil org-koma-letter-opening
)
197 (:closing
"CLOSING" nil org-koma-letter-closing
)
198 (:signature
"SIGNATURE" nil org-koma-letter-signature newline
)
199 (:special-tags nil nil
200 (append org-koma-letter-special-tags-after-closing
201 org-koma-letter-special-tags-after-letter
))
202 (:with-after-closing nil
"after-closing-order"
203 org-koma-letter-special-tags-after-closing
)
204 (:with-after-letter nil
"after-letter-order"
205 org-koma-letter-special-tags-after-letter
)
206 (:with-backaddress nil
"backaddress" org-koma-letter-use-backaddress
)
207 (:with-foldmarks nil
"foldmarks" org-koma-letter-use-foldmarks
)
208 (:with-phone nil
"phone" org-koma-letter-use-phone
)
209 (:with-email nil
"email" org-koma-letter-use-email
)
210 (:with-place nil
"place" org-koma-letter-use-place
)
211 (:with-subject nil
"subject" org-koma-letter-use-subject
))
212 :translate-alist
'((export-block . org-koma-letter-export-block
)
213 (export-snippet . org-koma-letter-export-snippet
)
214 (headline . org-koma-letter-headline
)
215 (keyword . org-koma-letter-keyword
)
216 (template . org-koma-letter-template
))
218 '(?k
"Export with KOMA Scrlttr2"
219 ((?L
"As LaTeX buffer" org-koma-letter-export-as-latex
)
220 (?l
"As LaTeX file" org-koma-letter-export-to-latex
)
221 (?p
"As PDF file" org-koma-letter-export-to-pdf
)
222 (?o
"As PDF file and open"
224 (if a
(org-koma-letter-export-to-pdf t s v b
)
225 (org-open-file (org-koma-letter-export-to-pdf nil s v b
))))))))
230 (defun org-koma-letter-email ()
231 "Return the current `user-mail-address'"
234 ;; The following is taken from/inspired by ox-grof.el
237 (defun org-koma-letter--get-tagged-contents (tag)
238 "Get tagged content from `org-koma-letter-special-contents'"
239 (cdr (assoc tag org-koma-letter-special-contents
)))
241 (defun org-koma-letter--get-custom (value)
242 "Determines whether a value is nil, a string or a
243 function (a symobl). If it is a function it it evaluates it."
245 (cond ((stringp value
) value
)
246 ((functionp value
) (funcall value
))
247 ((symbolp value
) (symbol-name value
)))))
250 (defun org-koma-letter--prepare-special-contents-as-macro (a-list &optional keep-newlines no-tag
)
251 "Finds all the components of `org-koma-letter-special-contents'
252 corresponding to members of the `a-list' and return them as a
253 string to be formatted. The function is used for inserting
254 content of speciall headings such as PS.
256 If keep-newlines is t newlines will not be removed. If no-tag is
257 is t the content in `org-koma-letter-special-contents' will not
258 be wrapped in a macro named whatever the members of a-list are called.
261 (dolist (ac a-list output
)
263 ((x (org-koma-letter--get-tagged-contents ac
))
264 (regexp (if keep-newlines
"" "\\`\n+\\|\n*\\'")))
269 ;; sometimes LaTeX complains about newlines
270 ;; at the end or beginning of macros. Remove them.
271 (org-koma-letter--format-string-as-macro
272 (format "%s" (replace-regexp-in-string regexp
"" x
))
273 (unless no-tag ac
)))))))))
275 (defun org-koma-letter--format-string-as-macro (string &optional macro
)
276 "If a macro is given format as string as \"\\macro{string}\" else as \"string\""
278 (format "\\%s{%s}" macro string
)
279 (format "%s" string
)))
281 ;;; Transcode Functions
285 (defun org-koma-letter-export-block (export-block contents info
)
286 "Transcode an EXPORT-BLOCK element into KOMA Scrlttr2 code.
287 CONTENTS is nil. INFO is a plist used as a communication
289 (when (member (org-element-property :type export-block
) '("KOMA-LETTER" "LATEX"))
290 (org-remove-indentation (org-element-property :value export-block
))))
294 (defun org-koma-letter-export-snippet (export-snippet contents info
)
295 "Transcode an EXPORT-SNIPPET object into KOMA Scrlttr2 code.
296 CONTENTS is nil. INFO is a plist used as a communication
298 (when (memq (org-export-snippet-backend export-snippet
) '(latex koma-letter
))
299 (org-element-property :value export-snippet
)))
303 (defun org-koma-letter-keyword (keyword contents info
)
304 "Transcode a KEYWORD element into KOMA Scrlttr2 code.
305 CONTENTS is nil. INFO is a plist used as a communication
307 (let ((key (org-element-property :key keyword
))
308 (value (org-element-property :value keyword
)))
309 ;; Handle specifically BEAMER and TOC (headlines only) keywords.
310 ;; Otherwise, fallback to `latex' back-end.
311 (if (equal key
"KOMA-LETTER") value
312 (org-export-with-backend 'latex keyword contents info
))))
317 (defun org-koma-letter-headline (headline contents info
)
318 "Transcode a HEADLINE element from Org to LaTeX.
319 CONTENTS holds the contents of the headline. INFO is a plist
320 holding contextual information.
322 Note that if a headline is tagged with a tag from
323 `org-koma-letter-special-tags' it will not be exported, but
324 stored in `org-koma-letter-special-contents' and included at the
327 ((tags (and (plist-get info
:with-tags
)
328 (org-export-get-tags headline info
)))
329 (tag (downcase (car tags
))))
330 (if (member tag
(plist-get info
:special-tags
))
332 (push (cons tag contents
)
333 org-koma-letter-special-contents
)
340 (defun org-koma-letter-template (contents info
)
341 "Return complete document string after KOMA Scrlttr2 conversion.
342 CONTENTS is the transcoded contents string. INFO is a plist
343 holding export options."
344 ;; FIXME: instead of setq'ing org-koma-letter-special-contents and
345 ;; callying varioues stuff it might be nice to put a big let* around the templace
346 ;; as in org-groff...
349 (and (plist-get info
:time-stamp-file
)
350 (format-time-string "%% Created %Y-%m-%d %a %H:%M\n"))
351 ;; Document class and packages.
352 (let ((class (plist-get info
:latex-class
))
353 (class-options (plist-get info
:latex-class-options
)))
354 (org-element-normalize-string
355 (let* ((header (nth 1 (assoc class org-latex-classes
)))
356 (document-class-string
357 (and (stringp header
)
358 (if (not class-options
) header
359 (replace-regexp-in-string
360 "^[ \t]*\\\\documentclass\\(\\(\\[[^]]*\\]\\)?\\)"
361 class-options header t nil
1)))))
362 (if (not document-class-string
)
363 (user-error "Unknown LaTeX class `%s'")
364 (org-latex-guess-babel-language
365 (org-latex-guess-inputenc
366 (org-splice-latex-header
367 document-class-string
368 org-latex-default-packages-alist
; defined in org.el
369 org-latex-packages-alist nil
; defined in org.el
370 (concat (plist-get info
:latex-header
)
371 (plist-get info
:latex-header-extra
))))
373 (let ((lco (plist-get info
:lco
))
374 (author (plist-get info
:author
))
375 (from-address (plist-get info
:from-address
))
376 (phone-number (plist-get info
:phone-number
))
377 (email (plist-get info
:email
))
378 (signature (plist-get info
:signature
)))
380 ;; Letter Class Option File
382 (let ((lco-files (split-string lco
" "))
384 (dolist (lco-file lco-files lco-def
)
385 (setq lco-def
(format "%s\\LoadLetterOption{%s}\n" lco-def lco-file
)))
387 ;; Define "From" data.
388 (when author
(format "\\setkomavar{fromname}{%s}\n"
389 (org-export-data author info
)))
390 (when from-address
(format "\\setkomavar{fromaddress}{%s}\n" from-address
))
391 (when phone-number
(format "\\setkomavar{fromphone}{%s}\n" phone-number
))
392 (when email
(format "\\setkomavar{fromemail}{%s}\n" email
))
393 (when signature
(format "\\setkomavar{signature}{%s}\n" signature
))))
395 (format "\\date{%s}\n" (org-export-data (org-export-get-date info
) info
))
397 (let ((with-place (plist-get info
:with-place
))
398 (place (plist-get info
:place
)))
399 (when (or place
(not with-place
))
400 (format "\\setkomavar{place}{%s}\n" (if with-place place
""))))
402 (let ((with-backaddress (plist-get info
:with-backaddress
))
403 (with-foldmarks (plist-get info
:with-foldmarks
))
404 (with-phone (plist-get info
:with-phone
))
405 (with-email (plist-get info
:with-email
)))
407 (format "\\KOMAoption{backaddress}{%s}\n" (if with-backaddress
"true" "false"))
408 (format "\\KOMAoption{foldmarks}{%s}\n" (if with-foldmarks with-foldmarks
"false"))
409 (format "\\KOMAoption{fromphone}{%s}\n" (if with-phone
"true" "false"))
410 (format "\\KOMAoption{fromemail}{%s}\n" (if with-email
"true" "false"))))
412 "\\begin{document}\n\n"
414 (let ((with-subject (plist-get info
:with-subject
)))
417 (format "\\KOMAoption{subject}{%s}\n" with-subject
)
418 (format "\\setkomavar{subject}{%s}\n\n"
419 (org-export-data (plist-get info
:title
) info
)))))
421 (format "\\begin{letter}{%%\n%s}\n\n"
422 (or (plist-get info
:to-address
) "no address given"))
424 (format "\\opening{%s}\n\n" (plist-get info
:opening
))
428 (format "\n\\closing{%s}\n" (plist-get info
:closing
))
429 (org-koma-letter--prepare-special-contents-as-macro
430 (plist-get info
:with-after-closing
))
433 (org-koma-letter--prepare-special-contents-as-macro
434 (plist-get info
:with-after-letter
) t t
)
443 (defun org-koma-letter-export-as-latex
444 (&optional async subtreep visible-only body-only ext-plist
)
445 "Export current buffer as a KOMA Scrlttr2 letter.
447 If narrowing is active in the current buffer, only export its
450 If a region is active, export that region.
452 A non-nil optional argument ASYNC means the process should happen
453 asynchronously. The resulting buffer should be accessible
454 through the `org-export-stack' interface.
456 When optional argument SUBTREEP is non-nil, export the sub-tree
457 at point, extracting information from the headline properties
460 When optional argument VISIBLE-ONLY is non-nil, don't export
461 contents of hidden elements.
463 When optional argument BODY-ONLY is non-nil, only write code
464 between \"\\begin{letter}\" and \"\\end{letter}\".
466 EXT-PLIST, when provided, is a proeprty list with external
467 parameters overriding Org default settings, but still inferior to
470 Export is done in a buffer named \"*Org KOMA-LETTER Export*\". It
471 will be displayed if `org-export-show-temporary-export-buffer' is
474 (let (org-koma-letter-special-contents)
476 (org-export-async-start
478 (with-current-buffer (get-buffer-create "*Org KOMA-LETTER Export*")
481 (goto-char (point-min))
483 (org-export-add-to-stack (current-buffer) 'koma-letter
)))
484 `(org-export-as 'koma-letter
,subtreep
,visible-only
,body-only
486 (let ((outbuf (org-export-to-buffer
487 'koma-letter
"*Org KOMA-LETTER Export*"
488 subtreep visible-only body-only ext-plist
)))
489 (with-current-buffer outbuf
(LaTeX-mode))
490 (when org-export-show-temporary-export-buffer
491 (switch-to-buffer-other-window outbuf
))))))
494 (defun org-koma-letter-export-to-latex
495 (&optional async subtreep visible-only body-only ext-plist
)
496 "Export current buffer as a KOMA Scrlttr2 letter (tex).
498 If narrowing is active in the current buffer, only export its
501 If a region is active, export that region.
503 A non-nil optional argument ASYNC means the process should happen
504 asynchronously. The resulting file should be accessible through
505 the `org-export-stack' interface.
507 When optional argument SUBTREEP is non-nil, export the sub-tree
508 at point, extracting information from the headline properties
511 When optional argument VISIBLE-ONLY is non-nil, don't export
512 contents of hidden elements.
514 When optional argument BODY-ONLY is non-nil, only write code
515 between \"\\begin{letter}\" and \"\\end{letter}\".
517 EXT-PLIST, when provided, is a property list with external
518 parameters overriding Org default settings, but still inferior to
521 When optional argument PUB-DIR is set, use it as the publishing
524 Return output file's name."
526 (let ((outfile (org-export-output-file-name ".tex" subtreep
)))
528 (org-export-async-start
529 (lambda (f) (org-export-add-to-stack f
'koma-letter
))
532 'koma-letter
,outfile
,subtreep
,visible-only
,body-only
535 'koma-letter outfile subtreep visible-only body-only ext-plist
))))
538 (defun org-koma-letter-export-to-pdf
539 (&optional async subtreep visible-only body-only ext-plist
)
540 "Export current buffer as a KOMA Scrlttr2 letter (pdf).
542 If narrowing is active in the current buffer, only export its
545 If a region is active, export that region.
547 A non-nil optional argument ASYNC means the process should happen
548 asynchronously. The resulting file should be accessible through
549 the `org-export-stack' interface.
551 When optional argument SUBTREEP is non-nil, export the sub-tree
552 at point, extracting information from the headline properties
555 When optional argument VISIBLE-ONLY is non-nil, don't export
556 contents of hidden elements.
558 When optional argument BODY-ONLY is non-nil, only write code
559 between \"\\begin{letter}\" and \"\\end{letter}\".
561 EXT-PLIST, when provided, is a property list with external
562 parameters overriding Org default settings, but still inferior to
565 Return PDF file's name."
568 (let ((outfile (org-export-output-file-name ".tex" subtreep
)))
569 (org-export-async-start
570 (lambda (f) (org-export-add-to-stack f
'koma-letter
))
574 'koma-letter
,outfile
,subtreep
,visible-only
,body-only
577 (org-koma-letter-export-to-latex
578 nil subtreep visible-only body-only ext-plist
))))
581 (provide 'ox-koma-letter
)
582 ;;; ox-koma-letter.el ends here