contrib/lisp/ox-koma-letter.el

   1 ;;; ox-koma-letter.el --- KOMA Scrlttr2 Back-End for Org Export Engine
   2
   3 ;; Copyright (C) 2007-2015  Free Software Foundation, Inc.
   4
   5 ;; Author: Nicolas Goaziou <n.goaziou AT gmail DOT com>
   6 ;;         Alan Schmitt <alan.schmitt AT polytechnique DOT org>
   7 ;;         Viktor Rosenfeld <listuser36 AT gmail DOT com>
   8 ;;         Rasmus Pank Roulund <emacs AT pank DOT eu>
   9 ;; Keywords: org, wp, tex
  10
  11 ;; This program is free software: you can redistribute it and/or modify
  12 ;; it under the terms of the GNU General Public License as published by
  13 ;; the Free Software Foundation, either version 3 of the License, or
  14 ;; (at your option) any later version.
  15
  16 ;; This program is distributed in the hope that it will be useful,
  17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 ;; GNU General Public License for more details.
  20
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  23
  24 ;;; Commentary:
  25 ;;
  26 ;; This library implements a KOMA Scrlttr2 back-end, derived from the
  27 ;; LaTeX one.
  28 ;;
  29 ;; Depending on the desired output format, three commands are provided
  30 ;; for export: `org-koma-letter-export-as-latex' (temporary buffer),
  31 ;; `org-koma-letter-export-to-latex' ("tex" file) and
  32 ;; `org-koma-letter-export-to-pdf' ("pdf" file).
  33 ;;
  34 ;; On top of buffer keywords supported by `latex' back-end (see
  35 ;; `org-latex-options-alist'), this back-end introduces the following
  36 ;; keywords:
  37 ;;   - CLOSING: see `org-koma-letter-closing',
  38 ;;   - FROM_ADDRESS: see `org-koma-letter-from-address',
  39 ;;   - LCO: see `org-koma-letter-class-option-file',
  40 ;;   - OPENING: see `org-koma-letter-opening',
  41 ;;   - PHONE_NUMBER: see `org-koma-letter-phone-number',
  42 ;;   - SIGNATURE: see `org-koma-letter-signature',
  43 ;;   - PLACE: see `org-koma-letter-place',
  44 ;;   - TO_ADDRESS:  If unspecified this is set to "\mbox{}".
  45 ;;
  46 ;; TO_ADDRESS and FROM_ADDRESS can also be specified using heading
  47 ;; with the special tags specified in
  48 ;; `org-koma-letter-special-tags-in-letter', namely "to" and "from".
  49 ;; LaTeX line breaks are not necessary if using these headings.  If
  50 ;; both a headline and a keyword specify a to or from address the
  51 ;; value is determined in accordance with
  52 ;; `org-koma-letter-prefer-special-headings'.
  53 ;;
  54 ;; A number of OPTIONS settings can be set to change which contents is
  55 ;; exported.
  56 ;;   - backaddress (see `org-koma-letter-use-backaddress')
  57 ;;   - foldmarks (see `org-koma-letter-use-foldmarks')
  58 ;;   - phone (see `org-koma-letter-use-phone')
  59 ;;   - email (see `org-koma-letter-use-email')
  60 ;;   - place (see `org-koma-letter-use-place')
  61 ;;   - subject, a list of format options
  62 ;;     (see `org-koma-letter-subject-format')
  63 ;;   - after-closing-order, a list of the ordering of headings with
  64 ;;     special tags after closing (see
  65 ;;     `org-koma-letter-special-tags-after-closing')
  66 ;;   - after-letter-order, as above, but after the end of the letter
  67 ;;     (see `org-koma-letter-special-tags-after-letter').
  68 ;;
  69 ;; The following variables works differently from the main LaTeX class
  70 ;;   - AUTHOR: Default to user-full-name but may be disabled.
  71 ;;     (See also `org-koma-letter-author'),
  72 ;;   - EMAIL: Same as AUTHOR. (see also `org-koma-letter-email'),
  73 ;;
  74 ;; Headlines are in general ignored.  However, headlines with special
  75 ;; tags can be used for specified contents like postscript (ps),
  76 ;; carbon copy (cc), enclosures (encl) and code to be inserted after
  77 ;; \end{letter} (after_letter).  Specials tags are defined in
  78 ;; `org-koma-letter-special-tags-after-closing' and
  79 ;; `org-koma-letter-special-tags-after-letter'.  Currently members of
  80 ;; `org-koma-letter-special-tags-after-closing' used as macros and the
  81 ;; content of the headline is the argument.
  82 ;;
  83 ;; Headlines with two and from may also be used rather than the
  84 ;; keyword approach described above.  If both a keyword and a headline
  85 ;; with information is present precedence is determined by
  86 ;; `org-koma-letter-prefer-special-headings'.
  87 ;;
  88 ;; You need an appropriate association in `org-latex-classes' in order
  89 ;; to use the KOMA Scrlttr2 class.  By default, a sparse scrlttr2
  90 ;; class is provided: "default-koma-letter".  You can also add you own
  91 ;; letter class.  For instance:
  92 ;;
  93 ;;   (add-to-list 'org-latex-classes
  94 ;;                '("my-letter"
  95 ;;                  "\\documentclass\[%
  96 ;;   DIV=14,
  97 ;;   fontsize=12pt,
  98 ;;   parskip=half,
  99 ;;   subject=titled,
 100 ;;   backaddress=false,
 101 ;;   fromalign=left,
 102 ;;   fromemail=true,
 103 ;;   fromphone=true\]\{scrlttr2\}
 104 ;;   \[DEFAULT-PACKAGES]
 105 ;;   \[PACKAGES]
 106 ;;   \[EXTRA]"))
 107 ;;
 108 ;; Then, in your Org document, be sure to require the proper class
 109 ;; with:
 110 ;;
 111 ;;    #+LATEX_CLASS: my-letter
 112 ;;
 113 ;; Or by setting `org-koma-letter-default-class'.
 114 ;;
 115 ;; You may have to load (LaTeX) Babel as well, e.g., by adding
 116 ;; it to `org-latex-packages-alist',
 117 ;;
 118 ;;    (add-to-list 'org-latex-packages-alist '("AUTO" "babel" nil))
 119
 120 ;;; Code:
 121
 122 (require 'ox-latex)
 123
 124 ;; Install a default letter class.
 125 (unless (assoc "default-koma-letter" org-latex-classes)
 126   (add-to-list 'org-latex-classes
 127                '("default-koma-letter" "\\documentclass[11pt]{scrlttr2}")))
 128
 129 \f
 130 ;;; User-Configurable Variables
 131
 132 (defgroup org-export-koma-letter nil
 133   "Options for exporting to KOMA scrlttr2 class in LaTeX export."
 134   :tag "Org Koma-Letter"
 135   :group 'org-export)
 136
 137 (defcustom org-koma-letter-class-option-file "NF"
 138   "Letter Class Option File.
 139 This option can also be set with the LCO keyword."
 140   :group 'org-export-koma-letter
 141   :type 'string)
 142
 143 (defcustom org-koma-letter-author 'user-full-name
 144   "Sender's name.
 145
 146 This variable defaults to calling the function `user-full-name'
 147 which just returns the current function `user-full-name'.
 148 Alternatively a string, nil or a function may be given.
 149 Functions must return a string.
 150
 151 This option can also be set with the AUTHOR keyword."
 152   :group 'org-export-koma-letter
 153   :type '(radio (function-item user-full-name)
 154                 (string)
 155                 (function)
 156                 (const :tag "Do not export author" nil)))
 157
 158 (defcustom org-koma-letter-email 'org-koma-letter-email
 159   "Sender's email address.
 160
 161 This variable defaults to the value `org-koma-letter-email' which
 162 returns `user-mail-address'.  Alternatively a string, nil or
 163 a function may be given.  Functions must return a string.
 164
 165 This option can also be set with the EMAIL keyword."
 166   :group 'org-export-koma-letter
 167   :type '(radio (function-item org-koma-letter-email)
 168                 (string)
 169                 (function)
 170                 (const :tag "Do not export email" nil)))
 171
 172 (defcustom org-koma-letter-from-address ""
 173   "Sender's address, as a string.
 174 This option can also be set with one or more FROM_ADDRESS
 175 keywords."
 176   :group 'org-export-koma-letter
 177   :type 'string)
 178
 179 (defcustom org-koma-letter-phone-number ""
 180   "Sender's phone number, as a string.
 181 This option can also be set with the PHONE_NUMBER keyword."
 182   :group 'org-export-koma-letter
 183   :type 'string)
 184
 185 (defcustom org-koma-letter-place ""
 186   "Place from which the letter is sent, as a string.
 187 This option can also be set with the PLACE keyword."
 188   :group 'org-export-koma-letter
 189   :type 'string)
 190
 191 (defcustom org-koma-letter-opening ""
 192   "Letter's opening, as a string.
 193
 194 This option can also be set with the OPENING keyword.  Moreover,
 195 when:
 196   (1) this value is the empty string;
 197   (2) there's no OPENING keyword or it is empty;
 198   (3) `org-koma-letter-headline-is-opening-maybe' is non-nil;
 199   (4) the letter contains a headline without a special
 200       tag (e.g. \"to\" or \"ps\");
 201 then the opening will be implicitly set as the headline title."
 202   :group 'org-export-koma-letter
 203   :type 'string)
 204
 205 (defcustom org-koma-letter-closing ""
 206   "Letter's closing, as a string.
 207 This option can also be set with the CLOSING keyword.  Moreover,
 208 when:
 209   (1) there's no CLOSING keyword or it is empty;
 210   (2) `org-koma-letter-headline-is-opening-maybe' is non-nil;
 211   (3) the letter contains a headline with the special
 212       tag closing;
 213 then the opening will be set as the title of the closing special
 214 heading."
 215   :group 'org-export-koma-letter
 216   :type 'string)
 217
 218 (defcustom org-koma-letter-signature ""
 219   "Signature, as a string.
 220 This option can also be set with the SIGNATURE keyword.
 221 Moreover, when:
 222   (1) there's no CLOSING keyword or it is empty;
 223   (2) `org-koma-letter-headline-is-opening-maybe' is non-nil;
 224   (3) the letter contains a headline with the special
 225       tag closing;
 226 then the signature will be  set as the content of the
 227 closing special heading."
 228   :group 'org-export-koma-letter
 229   :type 'string)
 230
 231 (defcustom org-koma-letter-prefer-special-headings nil
 232   "Non-nil means prefer headlines over keywords for TO and FROM.
 233 This option can also be set with the OPTIONS keyword, e.g.:
 234 \"special-headings:t\"."
 235   :group 'org-export-koma-letter
 236   :type 'boolean)
 237
 238 (defcustom org-koma-letter-subject-format t
 239   "Non-nil means include the subject.
 240
 241 Support formatting options.
 242
 243 When t, insert a subject using default options.  When nil, do not
 244 insert a subject at all.  It can also be a list of symbols among
 245 the following ones:
 246
 247  `afteropening'  Subject after opening
 248  `beforeopening' Subject before opening
 249  `centered'      Subject centered
 250  `left'          Subject left-justified
 251  `right'         Subject right-justified
 252  `titled'        Add title/description to subject
 253  `underlined'    Set subject underlined
 254  `untitled'      Do not add title/description to subject
 255
 256 Please refer to the KOMA-script manual (Table 4.16. in the
 257 English manual of 2012-07-22).
 258
 259 This option can also be set with the OPTIONS keyword, e.g.:
 260 \"subject:(underlined centered)\"."
 261   :type
 262   '(choice
 263     (const :tag "No export" nil)
 264     (const :tag "Default options" t)
 265     (set :tag "Configure options"
 266          (const :tag "Subject after opening" afteropening)
 267          (const :tag "Subject before opening" beforeopening)
 268          (const :tag "Subject centered" centered)
 269          (const :tag "Subject left-justified" left)
 270          (const :tag "Subject right-justified" right)
 271          (const :tag "Add title or description to subject" underlined)
 272          (const :tag "Set subject underlined" titled)
 273          (const :tag "Do not add title or description to subject" untitled)))
 274   :group 'org-export-koma-letter)
 275
 276 (defcustom org-koma-letter-use-backaddress nil
 277   "Non-nil prints return address in line above to address.
 278 This option can also be set with the OPTIONS keyword, e.g.:
 279 \"backaddress:t\"."
 280   :group 'org-export-koma-letter
 281   :type 'boolean)
 282
 283 (defcustom org-koma-letter-use-foldmarks t
 284   "Configure appearance of folding marks.
 285
 286 When t, activate default folding marks.  When nil, do not insert
 287 folding marks at all.  It can also be a list of symbols among the
 288 following ones:
 289
 290   `B'  Activate upper horizontal mark on left paper edge
 291   `b'  Deactivate upper horizontal mark on left paper edge
 292
 293   `H'  Activate all horizontal marks on left paper edge
 294   `h'  Deactivate all horizontal marks on left paper edge
 295
 296   `L'  Activate left vertical mark on upper paper edge
 297   `l'  Deactivate left vertical mark on upper paper edge
 298
 299   `M'  Activate middle horizontal mark on left paper edge
 300   `m'  Deactivate middle horizontal mark on left paper edge
 301
 302   `P'  Activate punch or center mark on left paper edge
 303   `p'  Deactivate punch or center mark on left paper edge
 304
 305   `T'  Activate lower horizontal mark on left paper edge
 306   `t'  Deactivate lower horizontal mark on left paper edge
 307
 308   `V'  Activate all vertical marks on upper paper edge
 309   `v'  Deactivate all vertical marks on upper paper edge
 310
 311 This option can also be set with the OPTIONS keyword, e.g.:
 312 \"foldmarks:(b l m t)\"."
 313   :group 'org-export-koma-letter
 314   :type '(choice
 315           (const :tag "Activate default folding marks" t)
 316           (const :tag "Deactivate folding marks" nil)
 317           (set
 318            :tag "Configure folding marks"
 319            (const :tag "Activate upper horizontal mark on left paper edge" B)
 320            (const :tag "Deactivate upper horizontal mark on left paper edge" b)
 321            (const :tag "Activate all horizontal marks on left paper edge" H)
 322            (const :tag "Deactivate all horizontal marks on left paper edge" h)
 323            (const :tag "Activate left vertical mark on upper paper edge" L)
 324            (const :tag "Deactivate left vertical mark on upper paper edge" l)
 325            (const :tag "Activate middle horizontal mark on left paper edge" M)
 326            (const :tag "Deactivate middle horizontal mark on left paper edge" m)
 327            (const :tag "Activate punch or center mark on left paper edge" P)
 328            (const :tag "Deactivate punch or center mark on left paper edge" p)
 329            (const :tag "Activate lower horizontal mark on left paper edge" T)
 330            (const :tag "Deactivate lower horizontal mark on left paper edge" t)
 331            (const :tag "Activate all vertical marks on upper paper edge" V)
 332            (const :tag "Deactivate all vertical marks on upper paper edge" v))))
 333
 334 (defcustom org-koma-letter-use-phone nil
 335   "Non-nil prints sender's phone number.
 336 This option can also be set with the OPTIONS keyword, e.g.:
 337 \"phone:t\"."
 338   :group 'org-export-koma-letter
 339   :type 'boolean)
 340
 341 (defcustom org-koma-letter-use-email nil
 342   "Non-nil prints sender's email address.
 343 This option can also be set with the OPTIONS keyword, e.g.:
 344 \"email:t\"."
 345   :group 'org-export-koma-letter
 346   :type 'boolean)
 347
 348 (defcustom org-koma-letter-use-place t
 349   "Non-nil prints the letter's place next to the date.
 350 This option can also be set with the OPTIONS keyword, e.g.:
 351 \"place:nil\"."
 352   :group 'org-export-koma-letter
 353   :type 'boolean)
 354
 355 (defcustom org-koma-letter-default-class "default-koma-letter"
 356   "Default class for `org-koma-letter'.
 357 The value must be a member of `org-latex-classes'."
 358   :group 'org-export-koma-letter
 359   :type 'string)
 360
 361 (defcustom org-koma-letter-headline-is-opening-maybe t
 362   "Non-nil means a headline may be used as an opening.
 363 A headline is only used if #+OPENING is not set.  See also
 364 `org-koma-letter-opening'."
 365   :group 'org-export-koma-letter
 366   :type 'boolean)
 367
 368 (defcustom org-koma-letter-prefer-subject nil
 369   "Non-nil means title should be interpreted as subject if subject is missing.
 370 This option can also be set with the OPTIONS keyword,
 371 e.g. \"title-subject:t\"."
 372     :group 'org-export-koma-letter
 373     :type 'boolean)
 374
 375 (defconst org-koma-letter-special-tags-in-letter '(to from closing)
 376   "Header tags related to the letter itself.")
 377
 378 (defconst org-koma-letter-special-tags-after-closing '(ps encl cc)
 379   "Header tags to be inserted after closing.")
 380
 381 (defconst org-koma-letter-special-tags-after-letter '(after_letter)
 382   "Header tags to be inserted after closing.")
 383
 384 (defvar org-koma-letter-special-contents nil
 385   "Holds special content temporarily.")
 386
 387 (make-obsolete-variable 'org-koma-letter-use-title
 388                         'org-export-with-title
 389                         "25.1" 'set)
 390
 391 \f
 392 ;;; Define Back-End
 393
 394 (org-export-define-derived-backend 'koma-letter 'latex
 395   :options-alist
 396   '((:latex-class "LATEX_CLASS" nil org-koma-letter-default-class t)
 397     (:lco "LCO" nil org-koma-letter-class-option-file)
 398     (:author "AUTHOR" nil (org-koma-letter--get-value org-koma-letter-author) parse)
 399     (:author-changed-in-buffer-p "AUTHOR" nil nil t)
 400     (:from-address "FROM_ADDRESS" nil org-koma-letter-from-address newline)
 401     (:phone-number "PHONE_NUMBER" nil org-koma-letter-phone-number)
 402     (:email "EMAIL" nil (org-koma-letter--get-value org-koma-letter-email) t)
 403     (:to-address "TO_ADDRESS" nil nil newline)
 404     (:place "PLACE" nil org-koma-letter-place)
 405     (:subject "SUBJECT" nil nil parse)
 406     (:opening "OPENING" nil org-koma-letter-opening parse)
 407     (:closing "CLOSING" nil org-koma-letter-closing parse)
 408     (:signature "SIGNATURE" nil org-koma-letter-signature newline)
 409     (:special-headings nil "special-headings"
 410                        org-koma-letter-prefer-special-headings)
 411     (:special-tags nil nil (append
 412                             org-koma-letter-special-tags-in-letter
 413                             org-koma-letter-special-tags-after-closing
 414                             org-koma-letter-special-tags-after-letter))
 415     (:with-after-closing nil "after-closing-order"
 416                          org-koma-letter-special-tags-after-closing)
 417     (:with-after-letter nil "after-letter-order"
 418                         org-koma-letter-special-tags-after-letter)
 419     (:with-backaddress nil "backaddress" org-koma-letter-use-backaddress)
 420     (:with-email nil "email" org-koma-letter-use-email)
 421     (:with-foldmarks nil "foldmarks" org-koma-letter-use-foldmarks)
 422     (:with-phone nil "phone" org-koma-letter-use-phone)
 423     (:with-place nil "place" org-koma-letter-use-place)
 424     (:with-subject nil "subject" org-koma-letter-subject-format)
 425     (:with-title-as-subject nil "title-subject" org-koma-letter-prefer-subject)
 426     (:with-headline-opening nil nil org-koma-letter-headline-is-opening-maybe)
 427     ;; Special properties non-nil when a setting happened in buffer.
 428     ;; They are used to prioritize in-buffer settings over "lco"
 429     ;; files.  See `org-koma-letter-template'.
 430     (:inbuffer-author "AUTHOR" nil 'koma-letter:empty)
 431     (:inbuffer-email "EMAIL" nil 'koma-letter:empty)
 432     (:inbuffer-phone-number "PHONE_NUMBER" nil 'koma-letter:empty)
 433     (:inbuffer-place "PLACE" nil 'koma-letter:empty)
 434     (:inbuffer-signature "SIGNATURE" nil 'koma-letter:empty)
 435     (:inbuffer-with-backaddress nil "backaddress" 'koma-letter:empty)
 436     (:inbuffer-with-email nil "email" 'koma-letter:empty)
 437     (:inbuffer-with-foldmarks nil "foldmarks" 'koma-letter:empty)
 438     (:inbuffer-with-phone nil "phone" 'koma-letter:empty))
 439   :translate-alist '((export-block . org-koma-letter-export-block)
 440                      (export-snippet . org-koma-letter-export-snippet)
 441                      (headline . org-koma-letter-headline)
 442                      (keyword . org-koma-letter-keyword)
 443                      (template . org-koma-letter-template))
 444   :menu-entry
 445   '(?k "Export with KOMA Scrlttr2"
 446        ((?L "As LaTeX buffer" org-koma-letter-export-as-latex)
 447         (?l "As LaTeX file" org-koma-letter-export-to-latex)
 448         (?p "As PDF file" org-koma-letter-export-to-pdf)
 449         (?o "As PDF file and open"
 450             (lambda (a s v b)
 451               (if a (org-koma-letter-export-to-pdf t s v b)
 452                 (org-open-file (org-koma-letter-export-to-pdf nil s v b))))))))
 453
 454
 455 \f
 456 ;;; Helper functions
 457
 458 (defun org-koma-letter-email ()
 459   "Return the current `user-mail-address'."
 460   user-mail-address)
 461
 462 ;; The following is taken from/inspired by ox-grof.el
 463 ;; Thanks, Luis!
 464
 465 (defun org-koma-letter--get-tagged-contents (key)
 466   "Get contents from a headline tagged with KEY.
 467 The contents is stored in `org-koma-letter-special-contents'."
 468   (cdr (assoc-string (org-koma-letter--get-value key)
 469                      org-koma-letter-special-contents)))
 470
 471 (defun org-koma-letter--get-value (value)
 472   "Turn value into a string whenever possible.
 473 Determines if VALUE is nil, a string, a function or a symbol and
 474 return a string or nil."
 475   (when value
 476     (cond ((stringp value) value)
 477           ((functionp value) (funcall value))
 478           ((symbolp value) (symbol-name value))
 479           (t value))))
 480
 481 (defun org-koma-letter--special-contents-as-macro
 482     (keywords &optional keep-newlines no-tag)
 483   "Process KEYWORDS members of `org-koma-letter-special-contents'.
 484 KEYWORDS is a list of symbols.  Return them as a string to be
 485 formatted.
 486
 487 The function is used for inserting content of special headings
 488 such as PS.
 489
 490 If KEEP-NEWLINES is non-nil leading and trailing newlines are not
 491 removed.  If NO-TAG is non-nil the content in
 492 `org-koma-letter-special-contents' are not wrapped in a macro
 493 named whatever the members of KEYWORDS are called."
 494   (mapconcat
 495    (lambda (keyword)
 496      (let* ((name (org-koma-letter--get-value keyword))
 497             (value (org-koma-letter--get-tagged-contents name)))
 498        (cond ((not value) nil)
 499              (no-tag (if keep-newlines value (org-trim value)))
 500              (t (format "\\%s{%s}\n"
 501                         name
 502                         (if keep-newlines value (org-trim value)))))))
 503    keywords
 504    ""))
 505
 506 (defun org-koma-letter--determine-to-and-from (info key)
 507   "Given INFO determine KEY for the letter.
 508 KEY should be `to' or `from'.
 509
 510 `ox-koma-letter' allows two ways to specify TO and FROM.  If both
 511 are present return the preferred one as determined by
 512 `org-koma-letter-prefer-special-headings'."
 513   (let ((option (org-string-nw-p
 514                  (plist-get info (if (eq key 'to) :to-address :from-address))))
 515         (headline (org-koma-letter--get-tagged-contents key)))
 516     (replace-regexp-in-string
 517      "\n" "\\\\\\\\\n"
 518      (org-trim
 519       (if (plist-get info :special-headings) (or headline option "")
 520         (or option headline ""))))))
 521
 522
 523 \f
 524 ;;; Transcode Functions
 525
 526 ;;;; Export Block
 527
 528 (defun org-koma-letter-export-block (export-block contents info)
 529   "Transcode an EXPORT-BLOCK element into KOMA Scrlttr2 code.
 530 CONTENTS is nil.  INFO is a plist used as a communication
 531 channel."
 532   (when (member (org-element-property :type export-block) '("KOMA-LETTER" "LATEX"))
 533     (org-remove-indentation (org-element-property :value export-block))))
 534
 535 ;;;; Export Snippet
 536
 537 (defun org-koma-letter-export-snippet (export-snippet contents info)
 538   "Transcode an EXPORT-SNIPPET object into KOMA Scrlttr2 code.
 539 CONTENTS is nil.  INFO is a plist used as a communication
 540 channel."
 541   (when (memq (org-export-snippet-backend export-snippet) '(latex koma-letter))
 542     (org-element-property :value export-snippet)))
 543
 544 ;;;; Keyword
 545
 546 (defun org-koma-letter-keyword (keyword contents info)
 547   "Transcode a KEYWORD element into KOMA Scrlttr2 code.
 548 CONTENTS is nil.  INFO is a plist used as a communication
 549 channel."
 550   (let ((key (org-element-property :key keyword))
 551         (value (org-element-property :value keyword)))
 552     ;; Handle specifically KOMA-LETTER keywords.  Otherwise, fallback
 553     ;; to `latex' back-end.
 554     (if (equal key "KOMA-LETTER") value
 555       (org-export-with-backend 'latex keyword contents info))))
 556
 557 ;; Headline
 558
 559 (defun org-koma-letter-headline (headline contents info)
 560   "Transcode a HEADLINE element from Org to LaTeX.
 561 CONTENTS holds the contents of the headline.  INFO is a plist
 562 holding contextual information.
 563
 564 Note that if a headline is tagged with a tag from
 565 `org-koma-letter-special-tags' it will not be exported, but
 566 stored in `org-koma-letter-special-contents' and included at the
 567 appropriate place."
 568   (let ((special-tag (org-koma-letter--special-tag headline info)))
 569     (if (not special-tag)
 570         contents
 571       (push (cons special-tag contents) org-koma-letter-special-contents)
 572       "")))
 573
 574 (defun org-koma-letter--special-tag (headline info)
 575   "Non-nil if HEADLINE is a special headline.
 576 INFO is a plist holding contextual information.  Return first
 577 special tag headline."
 578   (let ((special-tags (plist-get info :special-tags)))
 579     (catch 'exit
 580       (dolist (tag (org-export-get-tags headline info))
 581         (let ((tag (assoc-string tag special-tags)))
 582           (when tag (throw 'exit tag)))))))
 583
 584 ;;;; Template
 585
 586 (defun org-koma-letter-template (contents info)
 587   "Return complete document string after KOMA Scrlttr2 conversion.
 588 CONTENTS is the transcoded contents string.  INFO is a plist
 589 holding export options."
 590   (concat
 591    ;; Time-stamp.
 592    (and (plist-get info :time-stamp-file)
 593         (format-time-string "%% Created %Y-%m-%d %a %H:%M\n"))
 594    ;; Document class and packages.
 595    (let* ((class (plist-get info :latex-class))
 596           (class-options (plist-get info :latex-class-options))
 597           (header (nth 1 (assoc class org-latex-classes)))
 598           (document-class-string
 599            (and (stringp header)
 600                 (if (not class-options) header
 601                   (replace-regexp-in-string
 602                    "^[ \t]*\\\\documentclass\\(\\(\\[[^]]*\\]\\)?\\)"
 603                    class-options header t nil 1)))))
 604      (if (not document-class-string)
 605          (user-error "Unknown LaTeX class `%s'" class)
 606        (org-latex-guess-babel-language
 607         (org-latex-guess-inputenc
 608          (org-element-normalize-string
 609           (org-splice-latex-header
 610            document-class-string
 611            org-latex-default-packages-alist ; Defined in org.el.
 612            org-latex-packages-alist nil     ; Defined in org.el.
 613            (concat (org-element-normalize-string (plist-get info :latex-header))
 614                    (plist-get info :latex-header-extra)))))
 615         info)))
 616    ;; Settings.  They can come from three locations, in increasing
 617    ;; order of precedence: global variables, LCO files and in-buffer
 618    ;; settings.  Thus, we first insert settings coming from global
 619    ;; variables, then we insert LCO files, and, eventually, we insert
 620    ;; settings coming from buffer keywords.
 621    (org-koma-letter--build-settings 'global info)
 622    (mapconcat #'(lambda (file) (format "\\LoadLetterOption{%s}\n" file))
 623               (org-split-string (or (plist-get info :lco) "") " ")
 624               "")
 625    (org-koma-letter--build-settings 'buffer info)
 626    ;; From address.
 627    (let ((from-address (org-koma-letter--determine-to-and-from info 'from)))
 628      (when (org-string-nw-p from-address)
 629        (format "\\setkomavar{fromaddress}{%s}\n" from-address)))
 630    ;; Date.
 631    (format "\\date{%s}\n" (org-export-data (org-export-get-date info) info))
 632    ;; Hyperref, document start, and subject and title.
 633    (let* ((with-subject (plist-get info :with-subject))
 634           (with-title (plist-get info :with-title))
 635           (title-as-subject (and with-subject
 636                                  (plist-get info :with-title-as-subject)))
 637           (subject* (org-string-nw-p
 638                      (org-export-data (plist-get info :subject) info)))
 639           (title* (and with-title
 640                        (org-string-nw-p
 641                         (org-export-data (plist-get info :title) info))))
 642           (subject (cond ((not with-subject) nil)
 643                          (title-as-subject (or subject* title*))
 644                          (t subject*)))
 645           (title (cond ((not with-title) nil)
 646                        (title-as-subject (and subject* title*))
 647                        (t title*)))
 648           (hyperref-template (plist-get info :latex-hyperref-template))
 649           (spec (append (list (cons ?t (or title subject "")))
 650                         (org-latex--format-spec info))))
 651      (concat
 652       (when (and with-subject (not (eq with-subject t)))
 653         (format "\\KOMAoption{subject}{%s}\n"
 654                 (if (symbolp with-subject) with-subject
 655                   (mapconcat #'symbol-name with-subject ","))))
 656       ;; Hyperref.
 657       (format-spec hyperref-template spec)
 658       ;; Document start.
 659       "\\begin{document}\n\n"
 660       ;; Subject and title.
 661       (when subject (format "\\setkomavar{subject}{%s}\n" subject))
 662       (when title (format "\\setkomavar{title}{%s}\n" title))
 663       (when (or (org-string-nw-p title) (org-string-nw-p subject)) "\n")))
 664    ;; Letter start.
 665    (format "\\begin{letter}{%%\n%s}\n\n"
 666            (org-koma-letter--determine-to-and-from info 'to))
 667    ;; Opening.
 668    (format "\\opening{%s}\n\n"
 669            (org-export-data
 670             (or (org-string-nw-p (plist-get info :opening))
 671                 (when (plist-get info :with-headline-opening)
 672                   (org-element-map (plist-get info :parse-tree) 'headline
 673                     (lambda (head)
 674                       (unless (org-koma-letter--special-tag head info)
 675                         (org-element-property :title head)))
 676                     info t))
 677                 "")
 678             info))
 679    ;; Letter body.
 680    contents
 681    ;; Closing.
 682    (format "\n\\closing{%s}\n"
 683            (org-export-data
 684             (or (org-string-nw-p (plist-get info :closing))
 685                 (when (plist-get info :with-headline-opening)
 686                   (org-element-map (plist-get info :parse-tree) 'headline
 687                     (lambda (head)
 688                       (when (eq (org-koma-letter--special-tag head info)
 689                                 'closing)
 690                         (org-element-property :title head)))
 691                     info t)))
 692             info))
 693    (org-koma-letter--special-contents-as-macro
 694     (plist-get info :with-after-closing))
 695    ;; Letter end.
 696    "\n\\end{letter}\n"
 697    (org-koma-letter--special-contents-as-macro
 698     (plist-get info :with-after-letter) t t)
 699    ;; Document end.
 700    "\n\\end{document}"))
 701
 702 (defun org-koma-letter--build-settings (scope info)
 703   "Build settings string according to type.
 704 SCOPE is either `global' or `buffer'.  INFO is a plist used as
 705 a communication channel."
 706   (let ((check-scope
 707          (function
 708           ;; Non-nil value when SETTING was defined in SCOPE.
 709           (lambda (setting)
 710             (let ((property (intern (format ":inbuffer-%s" setting))))
 711               (if (eq scope 'global)
 712                   (eq (plist-get info property) 'koma-letter:empty)
 713                 (not (eq (plist-get info property) 'koma-letter:empty))))))))
 714     (concat
 715      ;; Name.
 716      (let ((author (plist-get info :author)))
 717        (and author
 718             (funcall check-scope 'author)
 719             (format "\\setkomavar{fromname}{%s}\n"
 720                     (org-export-data author info))))
 721      ;; Email.
 722      (let ((email (plist-get info :email)))
 723        (and email
 724             (funcall check-scope 'email)
 725             (format "\\setkomavar{fromemail}{%s}\n" email)))
 726      (and (funcall check-scope 'with-email)
 727           (format "\\KOMAoption{fromemail}{%s}\n"
 728                   (if (plist-get info :with-email) "true" "false")))
 729      ;; Phone number.
 730      (let ((phone-number (plist-get info :phone-number)))
 731        (and (org-string-nw-p phone-number)
 732             (funcall check-scope 'phone-number)
 733             (format "\\setkomavar{fromphone}{%s}\n" phone-number)))
 734      (and (funcall check-scope 'with-phone)
 735           (format "\\KOMAoption{fromphone}{%s}\n"
 736                   (if (plist-get info :with-phone) "true" "false")))
 737      ;; Signature.
 738      (let* ((heading-val
 739              (and (plist-get info :with-headline-opening)
 740                   (org-string-nw-p
 741                    (org-trim
 742                     (org-export-data
 743                      (org-koma-letter--get-tagged-contents 'closing)
 744                      info)))))
 745             (signature (org-string-nw-p (plist-get info :signature)))
 746             (signature-scope (funcall check-scope 'signature)))
 747        (and (or (and signature signature-scope)
 748                 heading-val)
 749             (not (and (eq scope 'global) heading-val))
 750             (format "\\setkomavar{signature}{%s}\n"
 751                     (if signature-scope signature heading-val))))
 752      ;; Back address.
 753      (and (funcall check-scope 'with-backaddress)
 754           (format "\\KOMAoption{backaddress}{%s}\n"
 755                   (if (plist-get info :with-backaddress) "true" "false")))
 756      ;; Place.
 757      (and (funcall check-scope 'place)
 758           (format "\\setkomavar{place}{%s}\n"
 759                   (if (plist-get info :with-place) (plist-get info :place) "")))
 760      ;; Folding marks.
 761      (and (funcall check-scope 'with-foldmarks)
 762           (let ((foldmarks (plist-get info :with-foldmarks)))
 763             (cond ((consp foldmarks)
 764                    (format "\\KOMAoptions{foldmarks=true,foldmarks=%s}\n"
 765                            (mapconcat #'symbol-name foldmarks "")))
 766                   (foldmarks "\\KOMAoptions{foldmarks=true}\n")
 767                   (t "\\KOMAoptions{foldmarks=false}\n")))))))
 768
 769
 770 \f
 771 ;;; Commands
 772
 773 ;;;###autoload
 774 (defun org-koma-letter-export-as-latex
 775   (&optional async subtreep visible-only body-only ext-plist)
 776   "Export current buffer as a KOMA Scrlttr2 letter.
 777
 778 If narrowing is active in the current buffer, only export its
 779 narrowed part.
 780
 781 If a region is active, export that region.
 782
 783 A non-nil optional argument ASYNC means the process should happen
 784 asynchronously.  The resulting buffer should be accessible
 785 through the `org-export-stack' interface.
 786
 787 When optional argument SUBTREEP is non-nil, export the sub-tree
 788 at point, extracting information from the headline properties
 789 first.
 790
 791 When optional argument VISIBLE-ONLY is non-nil, don't export
 792 contents of hidden elements.
 793
 794 When optional argument BODY-ONLY is non-nil, only write code
 795 between \"\\begin{letter}\" and \"\\end{letter}\".
 796
 797 EXT-PLIST, when provided, is a proeprty list with external
 798 parameters overriding Org default settings, but still inferior to
 799 file-local settings.
 800
 801 Export is done in a buffer named \"*Org KOMA-LETTER Export*\".  It
 802 will be displayed if `org-export-show-temporary-export-buffer' is
 803 non-nil."
 804   (interactive)
 805   (let (org-koma-letter-special-contents)
 806     (org-export-to-buffer 'koma-letter "*Org KOMA-LETTER Export*"
 807       async subtreep visible-only body-only ext-plist
 808       (lambda () (LaTeX-mode)))))
 809
 810 ;;;###autoload
 811 (defun org-koma-letter-export-to-latex
 812   (&optional async subtreep visible-only body-only ext-plist)
 813   "Export current buffer as a KOMA Scrlttr2 letter (tex).
 814
 815 If narrowing is active in the current buffer, only export its
 816 narrowed part.
 817
 818 If a region is active, export that region.
 819
 820 A non-nil optional argument ASYNC means the process should happen
 821 asynchronously.  The resulting file should be accessible through
 822 the `org-export-stack' interface.
 823
 824 When optional argument SUBTREEP is non-nil, export the sub-tree
 825 at point, extracting information from the headline properties
 826 first.
 827
 828 When optional argument VISIBLE-ONLY is non-nil, don't export
 829 contents of hidden elements.
 830
 831 When optional argument BODY-ONLY is non-nil, only write code
 832 between \"\\begin{letter}\" and \"\\end{letter}\".
 833
 834 EXT-PLIST, when provided, is a property list with external
 835 parameters overriding Org default settings, but still inferior to
 836 file-local settings.
 837
 838 When optional argument PUB-DIR is set, use it as the publishing
 839 directory.
 840
 841 Return output file's name."
 842   (interactive)
 843   (let ((outfile (org-export-output-file-name ".tex" subtreep))
 844         (org-koma-letter-special-contents))
 845     (org-export-to-file 'koma-letter outfile
 846       async subtreep visible-only body-only ext-plist)))
 847
 848 ;;;###autoload
 849 (defun org-koma-letter-export-to-pdf
 850   (&optional async subtreep visible-only body-only ext-plist)
 851   "Export current buffer as a KOMA Scrlttr2 letter (pdf).
 852
 853 If narrowing is active in the current buffer, only export its
 854 narrowed part.
 855
 856 If a region is active, export that region.
 857
 858 A non-nil optional argument ASYNC means the process should happen
 859 asynchronously.  The resulting file should be accessible through
 860 the `org-export-stack' interface.
 861
 862 When optional argument SUBTREEP is non-nil, export the sub-tree
 863 at point, extracting information from the headline properties
 864 first.
 865
 866 When optional argument VISIBLE-ONLY is non-nil, don't export
 867 contents of hidden elements.
 868
 869 When optional argument BODY-ONLY is non-nil, only write code
 870 between \"\\begin{letter}\" and \"\\end{letter}\".
 871
 872 EXT-PLIST, when provided, is a property list with external
 873 parameters overriding Org default settings, but still inferior to
 874 file-local settings.
 875
 876 Return PDF file's name."
 877   (interactive)
 878   (let ((file (org-export-output-file-name ".tex" subtreep))
 879         (org-koma-letter-special-contents))
 880     (org-export-to-file 'koma-letter file
 881       async subtreep visible-only body-only ext-plist
 882       (lambda (file) (org-latex-compile file)))))
 883
 884
 885 (provide 'ox-koma-letter)
 886 ;;; ox-koma-letter.el ends here