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."
 208   :group 'org-export-koma-letter
 209   :type 'string)
 210
 211 (defcustom org-koma-letter-signature ""
 212   "Signature, as a string.
 213 This option can also be set with the SIGNATURE keyword."
 214   :group 'org-export-koma-letter
 215   :type 'string)
 216
 217 (defcustom org-koma-letter-prefer-special-headings nil
 218   "Non-nil means prefer headlines over keywords for TO and FROM.
 219 This option can also be set with the OPTIONS keyword, e.g.:
 220 \"special-headings:t\"."
 221   :group 'org-export-koma-letter
 222   :type 'boolean)
 223
 224 (defcustom org-koma-letter-subject-format t
 225   "Non-nil means include the subject.
 226
 227 Support formatting options.
 228
 229 When t, insert a subject using default options.  When nil, do not
 230 insert a subject at all.  It can also be a list of symbols among
 231 the following ones:
 232
 233  `afteropening'  Subject after opening
 234  `beforeopening' Subject before opening
 235  `centered'      Subject centered
 236  `left'          Subject left-justified
 237  `right'         Subject right-justified
 238  `titled'        Add title/description to subject
 239  `underlined'    Set subject underlined
 240  `untitled'      Do not add title/description to subject
 241
 242 Please refer to the KOMA-script manual (Table 4.16. in the
 243 English manual of 2012-07-22).
 244
 245 This option can also be set with the OPTIONS keyword, e.g.:
 246 \"subject:(underlined centered)\"."
 247   :type
 248   '(choice
 249     (const :tag "No export" nil)
 250     (const :tag "Default options" t)
 251     (set :tag "Configure options"
 252          (const :tag "Subject after opening" afteropening)
 253          (const :tag "Subject before opening" beforeopening)
 254          (const :tag "Subject centered" centered)
 255          (const :tag "Subject left-justified" left)
 256          (const :tag "Subject right-justified" right)
 257          (const :tag "Add title or description to subject" underlined)
 258          (const :tag "Set subject underlined" titled)
 259          (const :tag "Do not add title or description to subject" untitled)))
 260   :group 'org-export-koma-letter)
 261
 262 (defcustom org-koma-letter-use-backaddress nil
 263   "Non-nil prints return address in line above to address.
 264 This option can also be set with the OPTIONS keyword, e.g.:
 265 \"backaddress:t\"."
 266   :group 'org-export-koma-letter
 267   :type 'boolean)
 268
 269 (defcustom org-koma-letter-use-foldmarks t
 270   "Configure appearance of folding marks.
 271
 272 When t, activate default folding marks.  When nil, do not insert
 273 folding marks at all.  It can also be a list of symbols among the
 274 following ones:
 275
 276   `B'  Activate upper horizontal mark on left paper edge
 277   `b'  Deactivate upper horizontal mark on left paper edge
 278
 279   `H'  Activate all horizontal marks on left paper edge
 280   `h'  Deactivate all horizontal marks on left paper edge
 281
 282   `L'  Activate left vertical mark on upper paper edge
 283   `l'  Deactivate left vertical mark on upper paper edge
 284
 285   `M'  Activate middle horizontal mark on left paper edge
 286   `m'  Deactivate middle horizontal mark on left paper edge
 287
 288   `P'  Activate punch or center mark on left paper edge
 289   `p'  Deactivate punch or center mark on left paper edge
 290
 291   `T'  Activate lower horizontal mark on left paper edge
 292   `t'  Deactivate lower horizontal mark on left paper edge
 293
 294   `V'  Activate all vertical marks on upper paper edge
 295   `v'  Deactivate all vertical marks on upper paper edge
 296
 297 This option can also be set with the OPTIONS keyword, e.g.:
 298 \"foldmarks:(b l m t)\"."
 299   :group 'org-export-koma-letter
 300   :type '(choice
 301           (const :tag "Activate default folding marks" t)
 302           (const :tag "Deactivate folding marks" nil)
 303           (set
 304            :tag "Configure folding marks"
 305            (const :tag "Activate upper horizontal mark on left paper edge" B)
 306            (const :tag "Deactivate upper horizontal mark on left paper edge" b)
 307            (const :tag "Activate all horizontal marks on left paper edge" H)
 308            (const :tag "Deactivate all horizontal marks on left paper edge" h)
 309            (const :tag "Activate left vertical mark on upper paper edge" L)
 310            (const :tag "Deactivate left vertical mark on upper paper edge" l)
 311            (const :tag "Activate middle horizontal mark on left paper edge" M)
 312            (const :tag "Deactivate middle horizontal mark on left paper edge" m)
 313            (const :tag "Activate punch or center mark on left paper edge" P)
 314            (const :tag "Deactivate punch or center mark on left paper edge" p)
 315            (const :tag "Activate lower horizontal mark on left paper edge" T)
 316            (const :tag "Deactivate lower horizontal mark on left paper edge" t)
 317            (const :tag "Activate all vertical marks on upper paper edge" V)
 318            (const :tag "Deactivate all vertical marks on upper paper edge" v))))
 319
 320 (defcustom org-koma-letter-use-phone nil
 321   "Non-nil prints sender's phone number.
 322 This option can also be set with the OPTIONS keyword, e.g.:
 323 \"phone:t\"."
 324   :group 'org-export-koma-letter
 325   :type 'boolean)
 326
 327 (defcustom org-koma-letter-use-email nil
 328   "Non-nil prints sender's email address.
 329 This option can also be set with the OPTIONS keyword, e.g.:
 330 \"email:t\"."
 331   :group 'org-export-koma-letter
 332   :type 'boolean)
 333
 334 (defcustom org-koma-letter-use-place t
 335   "Non-nil prints the letter's place next to the date.
 336 This option can also be set with the OPTIONS keyword, e.g.:
 337 \"place:nil\"."
 338   :group 'org-export-koma-letter
 339   :type 'boolean)
 340
 341 (defcustom org-koma-letter-default-class "default-koma-letter"
 342   "Default class for `org-koma-letter'.
 343 The value must be a member of `org-latex-classes'."
 344   :group 'org-export-koma-letter
 345   :type 'string)
 346
 347 (defcustom org-koma-letter-headline-is-opening-maybe t
 348   "Non-nil means a headline may be used as an opening.
 349 A headline is only used if #+OPENING is not set.  See also
 350 `org-koma-letter-opening'."
 351   :group 'org-export-koma-letter
 352   :type 'boolean)
 353
 354 (defcustom org-koma-letter-prefer-subject nil
 355   "Non-nil means title should be interpret as subject if subject is missing.
 356 This option can also be set with the OPTIONS keyword,
 357 e.g. \"title-subject:t\".
 358
 359 This may be useful for older documents where the SUBJECT keyword
 360 was not present."
 361     :group 'org-export-koma-letter
 362     :type 'boolean)
 363
 364 (defconst org-koma-letter-special-tags-in-letter '(to from)
 365   "Header tags related to the letter itself.")
 366
 367 (defconst org-koma-letter-special-tags-after-closing '(ps encl cc)
 368   "Header tags to be inserted after closing.")
 369
 370 (defconst org-koma-letter-special-tags-after-letter '(after_letter)
 371   "Header tags to be inserted after closing.")
 372
 373 (defvar org-koma-letter-special-contents nil
 374   "Holds special content temporarily.")
 375
 376 (make-obsolete-variable 'org-koma-letter-use-title
 377                         'org-export-with-title
 378                         "25.1" 'set)
 379
 380 \f
 381 ;;; Define Back-End
 382
 383 (org-export-define-derived-backend 'koma-letter 'latex
 384   :options-alist
 385   '((:latex-class "LATEX_CLASS" nil org-koma-letter-default-class t)
 386     (:lco "LCO" nil org-koma-letter-class-option-file)
 387     (:author "AUTHOR" nil (org-koma-letter--get-value org-koma-letter-author) t)
 388     (:author-changed-in-buffer-p "AUTHOR" nil nil t)
 389     (:from-address "FROM_ADDRESS" nil org-koma-letter-from-address newline)
 390     (:phone-number "PHONE_NUMBER" nil org-koma-letter-phone-number)
 391     (:email "EMAIL" nil (org-koma-letter--get-value org-koma-letter-email) t)
 392     (:to-address "TO_ADDRESS" nil nil newline)
 393     (:place "PLACE" nil org-koma-letter-place)
 394     (:subject "SUBJECT" nil nil parse)
 395     (:opening "OPENING" nil org-koma-letter-opening)
 396     (:closing "CLOSING" nil org-koma-letter-closing)
 397     (:signature "SIGNATURE" nil org-koma-letter-signature newline)
 398     (:special-headings nil "special-headings"
 399                        org-koma-letter-prefer-special-headings)
 400     (:special-tags nil nil (append
 401                             org-koma-letter-special-tags-in-letter
 402                             org-koma-letter-special-tags-after-closing
 403                             org-koma-letter-special-tags-after-letter))
 404     (:with-after-closing nil "after-closing-order"
 405                          org-koma-letter-special-tags-after-closing)
 406     (:with-after-letter nil "after-letter-order"
 407                         org-koma-letter-special-tags-after-letter)
 408     (:with-backaddress nil "backaddress" org-koma-letter-use-backaddress)
 409     (:with-email nil "email" org-koma-letter-use-email)
 410     (:with-foldmarks nil "foldmarks" org-koma-letter-use-foldmarks)
 411     (:with-phone nil "phone" org-koma-letter-use-phone)
 412     (:with-place nil "place" org-koma-letter-use-place)
 413     (:with-subject nil "subject" org-koma-letter-subject-format)
 414     (:with-title-as-subject nil "title-subject" org-koma-letter-prefer-subject)
 415     (:with-headline-opening nil nil org-koma-letter-headline-is-opening-maybe)
 416     ;; Special properties non-nil when a setting happened in buffer.
 417     ;; They are used to prioritize in-buffer settings over "lco"
 418     ;; files.  See `org-koma-letter-template'.
 419     (:inbuffer-author "AUTHOR" nil 'koma-letter:empty)
 420     (:inbuffer-email "EMAIL" nil 'koma-letter:empty)
 421     (:inbuffer-phone-number "PHONE_NUMBER" nil 'koma-letter:empty)
 422     (:inbuffer-place "PLACE" nil 'koma-letter:empty)
 423     (:inbuffer-signature "SIGNATURE" nil 'koma-letter:empty)
 424     (:inbuffer-with-backaddress nil "backaddress" 'koma-letter:empty)
 425     (:inbuffer-with-email nil "email" 'koma-letter:empty)
 426     (:inbuffer-with-foldmarks nil "foldmarks" 'koma-letter:empty)
 427     (:inbuffer-with-phone nil "phone" 'koma-letter:empty))
 428   :translate-alist '((export-block . org-koma-letter-export-block)
 429                      (export-snippet . org-koma-letter-export-snippet)
 430                      (headline . org-koma-letter-headline)
 431                      (keyword . org-koma-letter-keyword)
 432                      (template . org-koma-letter-template))
 433   :menu-entry
 434   '(?k "Export with KOMA Scrlttr2"
 435        ((?L "As LaTeX buffer" org-koma-letter-export-as-latex)
 436         (?l "As LaTeX file" org-koma-letter-export-to-latex)
 437         (?p "As PDF file" org-koma-letter-export-to-pdf)
 438         (?o "As PDF file and open"
 439             (lambda (a s v b)
 440               (if a (org-koma-letter-export-to-pdf t s v b)
 441                 (org-open-file (org-koma-letter-export-to-pdf nil s v b))))))))
 442
 443
 444 \f
 445 ;;; Helper functions
 446
 447 (defun org-koma-letter-email ()
 448   "Return the current `user-mail-address'."
 449   user-mail-address)
 450
 451 ;; The following is taken from/inspired by ox-grof.el
 452 ;; Thanks, Luis!
 453
 454 (defun org-koma-letter--get-tagged-contents (key)
 455   "Get contents from a headline tagged with KEY.
 456 The contents is stored in `org-koma-letter-special-contents'."
 457   (cdr (assoc-string (org-koma-letter--get-value key)
 458                      org-koma-letter-special-contents)))
 459
 460 (defun org-koma-letter--get-value (value)
 461   "Turn value into a string whenever possible.
 462 Determines if VALUE is nil, a string, a function or a symbol and
 463 return a string or nil."
 464   (when value
 465     (cond ((stringp value) value)
 466           ((functionp value) (funcall value))
 467           ((symbolp value) (symbol-name value))
 468           (t value))))
 469
 470 (defun org-koma-letter--special-contents-as-macro
 471   (keywords &optional keep-newlines no-tag)
 472   "Process KEYWORDS  members of `org-koma-letter-special-contents'.
 473 KEYWORDS is a list of symbols.  Return them as a string to be
 474 formatted.
 475
 476 The function is used for inserting content of special headings
 477 such as PS.
 478
 479 If KEEP-NEWLINES is t newlines will not be removed.  If NO-TAG is
 480 t the content in `org-koma-letter-special-contents' will not be
 481 wrapped in a macro named whatever the members of KEYWORDS are
 482 called."
 483   (mapconcat
 484    #'(lambda (keyword)
 485        (let* ((name (org-koma-letter--get-value keyword))
 486               (value (org-koma-letter--get-tagged-contents name)))
 487          (when value
 488            (if no-tag (if keep-newlines value (org-trim value))
 489              (format "\\%s{%s}\n"
 490                      name
 491                      (if keep-newlines value (org-trim value)))))))
 492    keywords
 493    ""))
 494
 495 (defun org-koma-letter--determine-to-and-from (info key)
 496   "Given INFO determine KEY for the letter.
 497 KEY should be `to' or `from'.
 498
 499 `ox-koma-letter' allows two ways to specify TO and FROM.  If both
 500 are present return the preferred one as determined by
 501 `org-koma-letter-prefer-special-headings'."
 502   (let ((option (org-string-nw-p
 503                  (plist-get info (if (eq key 'to) :to-address :from-address))))
 504         (headline (org-koma-letter--get-tagged-contents key)))
 505     (replace-regexp-in-string
 506      "\n" "\\\\\\\\\n"
 507      (org-trim
 508       (if (plist-get info :special-headings) (or headline option "")
 509         (or option headline ""))))))
 510
 511
 512 \f
 513 ;;; Transcode Functions
 514
 515 ;;;; Export Block
 516
 517 (defun org-koma-letter-export-block (export-block contents info)
 518   "Transcode an EXPORT-BLOCK element into KOMA Scrlttr2 code.
 519 CONTENTS is nil.  INFO is a plist used as a communication
 520 channel."
 521   (when (member (org-element-property :type export-block) '("KOMA-LETTER" "LATEX"))
 522     (org-remove-indentation (org-element-property :value export-block))))
 523
 524 ;;;; Export Snippet
 525
 526 (defun org-koma-letter-export-snippet (export-snippet contents info)
 527   "Transcode an EXPORT-SNIPPET object into KOMA Scrlttr2 code.
 528 CONTENTS is nil.  INFO is a plist used as a communication
 529 channel."
 530   (when (memq (org-export-snippet-backend export-snippet) '(latex koma-letter))
 531     (org-element-property :value export-snippet)))
 532
 533 ;;;; Keyword
 534
 535 (defun org-koma-letter-keyword (keyword contents info)
 536   "Transcode a KEYWORD element into KOMA Scrlttr2 code.
 537 CONTENTS is nil.  INFO is a plist used as a communication
 538 channel."
 539   (let ((key (org-element-property :key keyword))
 540         (value (org-element-property :value keyword)))
 541     ;; Handle specifically KOMA-LETTER keywords.  Otherwise, fallback
 542     ;; to `latex' back-end.
 543     (if (equal key "KOMA-LETTER") value
 544       (org-export-with-backend 'latex keyword contents info))))
 545
 546 ;; Headline
 547
 548 (defun org-koma-letter-headline (headline contents info)
 549   "Transcode a HEADLINE element from Org to LaTeX.
 550 CONTENTS holds the contents of the headline.  INFO is a plist
 551 holding contextual information.
 552
 553 Note that if a headline is tagged with a tag from
 554 `org-koma-letter-special-tags' it will not be exported, but
 555 stored in `org-koma-letter-special-contents' and included at the
 556 appropriate place."
 557   (let ((special-tag (org-koma-letter--special-tag headline info)))
 558     (if (not special-tag)
 559         contents
 560       (push (cons special-tag contents) org-koma-letter-special-contents)
 561       "")))
 562
 563 (defun org-koma-letter--special-tag (headline info)
 564   "Non-nil if HEADLINE is a special headline.
 565 INFO is a plist holding contextual information.  Return first
 566 special tag headline."
 567   (let ((special-tags (plist-get info :special-tags)))
 568     (catch 'exit
 569       (dolist (tag (org-export-get-tags headline info))
 570         (let ((tag (assoc-string tag special-tags)))
 571           (when tag (throw 'exit tag)))))))
 572
 573 ;;;; Template
 574
 575 (defun org-koma-letter-template (contents info)
 576   "Return complete document string after KOMA Scrlttr2 conversion.
 577 CONTENTS is the transcoded contents string.  INFO is a plist
 578 holding export options."
 579   (concat
 580    ;; Time-stamp.
 581    (and (plist-get info :time-stamp-file)
 582         (format-time-string "%% Created %Y-%m-%d %a %H:%M\n"))
 583    ;; Document class and packages.
 584    (let* ((class (plist-get info :latex-class))
 585           (class-options (plist-get info :latex-class-options))
 586           (header (nth 1 (assoc class org-latex-classes)))
 587           (document-class-string
 588            (and (stringp header)
 589                 (if (not class-options) header
 590                   (replace-regexp-in-string
 591                    "^[ \t]*\\\\documentclass\\(\\(\\[[^]]*\\]\\)?\\)"
 592                    class-options header t nil 1)))))
 593      (if (not document-class-string)
 594          (user-error "Unknown LaTeX class `%s'" class)
 595        (org-latex-guess-babel-language
 596         (org-latex-guess-inputenc
 597          (org-element-normalize-string
 598           (org-splice-latex-header
 599            document-class-string
 600            org-latex-default-packages-alist ; Defined in org.el.
 601            org-latex-packages-alist nil     ; Defined in org.el.
 602            (concat (org-element-normalize-string (plist-get info :latex-header))
 603                    (plist-get info :latex-header-extra)))))
 604         info)))
 605    ;; Settings.  They can come from three locations, in increasing
 606    ;; order of precedence: global variables, LCO files and in-buffer
 607    ;; settings.  Thus, we first insert settings coming from global
 608    ;; variables, then we insert LCO files, and, eventually, we insert
 609    ;; settings coming from buffer keywords.
 610    (org-koma-letter--build-settings 'global info)
 611    (mapconcat #'(lambda (file) (format "\\LoadLetterOption{%s}\n" file))
 612               (org-split-string (or (plist-get info :lco) "") " ")
 613               "")
 614    (org-koma-letter--build-settings 'buffer info)
 615    ;; From address.
 616    (let ((from-address (org-koma-letter--determine-to-and-from info 'from)))
 617      (when (org-string-nw-p from-address)
 618        (format "\\setkomavar{fromaddress}{%s}\n" from-address)))
 619    ;; Date.
 620    (format "\\date{%s}\n" (org-export-data (org-export-get-date info) info))
 621    ;; Hyperref, document start, and subject and title.
 622    (let ((with-subject (plist-get info :with-subject)))
 623      (when (and with-subject (plist-get info :with-title))
 624        (concat
 625         (unless (eq with-subject t)
 626           (format "\\KOMAoption{subject}{%s}\n"
 627                   (if (symbolp with-subject) with-subject
 628                     (mapconcat #'symbol-name with-subject ","))))
 629         (let* ((title-as-subject (plist-get info :with-title-as-subject))
 630                (subject* (org-string-nw-p
 631                           (org-export-data (plist-get info :subject) info)))
 632                (title* (and (plist-get info :with-title)
 633                             (org-string-nw-p
 634                              (org-export-data (plist-get info :title) info))))
 635                (subject (if title-as-subject (or subject* title*) subject*))
 636                (title (if title-as-subject (and subject* title*) title*))
 637                (hyperref-template (plist-get info :latex-hyperref-template))
 638                (spec (append (list (cons ?t (or title subject "")))
 639                              (org-latex--format-spec info))))
 640           (concat
 641            ;; Hyperref.
 642            (format-spec hyperref-template spec)
 643            ;; Document start.
 644            "\\begin{document}\n\n"
 645            ;; Subject and title.
 646            (when subject (format "\\setkomavar{subject}{%s}\n" subject))
 647            (when title (format "\\setkomavar{title}{%s}\n" title))
 648            (when (or (org-string-nw-p title) (org-string-nw-p subject)) "\n"))))))
 649    ;; Letter start.
 650    (format "\\begin{letter}{%%\n%s}\n\n"
 651            (org-koma-letter--determine-to-and-from info 'to))
 652    ;; Opening.
 653    (format "\\opening{%s}\n\n"
 654            (org-export-data
 655             (or (org-string-nw-p (plist-get info :opening))
 656                 (when (plist-get info :with-headline-opening)
 657                   (org-element-map (plist-get info :parse-tree) 'headline
 658                     (lambda (head)
 659                       (unless (org-koma-letter--special-tag head info)
 660                         (org-element-property :title head)))
 661                     info t))
 662                 "")
 663             info))
 664    ;; Letter body.
 665    contents
 666    ;; Closing.
 667    (format "\n\\closing{%s}\n" (plist-get info :closing))
 668    (org-koma-letter--special-contents-as-macro
 669     (plist-get info :with-after-closing))
 670    ;; Letter end.
 671    "\n\\end{letter}\n"
 672    (org-koma-letter--special-contents-as-macro
 673     (plist-get info :with-after-letter) t t)
 674    ;; Document end.
 675    "\n\\end{document}"))
 676
 677 (defun org-koma-letter--build-settings (scope info)
 678   "Build settings string according to type.
 679 SCOPE is either `global' or `buffer'.  INFO is a plist used as
 680 a communication channel."
 681   (let ((check-scope
 682          (function
 683           ;; Non-nil value when SETTING was defined in SCOPE.
 684           (lambda (setting)
 685             (let ((property (intern (format ":inbuffer-%s" setting))))
 686               (if (eq scope 'global)
 687                   (eq (plist-get info property) 'koma-letter:empty)
 688                 (not (eq (plist-get info property) 'koma-letter:empty))))))))
 689     (concat
 690      ;; Name.
 691      (let ((author (plist-get info :author)))
 692        (and author
 693             (funcall check-scope 'author)
 694             (format "\\setkomavar{fromname}{%s}\n"
 695                     (org-export-data author info))))
 696      ;; Email.
 697      (let ((email (plist-get info :email)))
 698        (and email
 699             (funcall check-scope 'email)
 700             (format "\\setkomavar{fromemail}{%s}\n" email)))
 701      (and (funcall check-scope 'with-email)
 702           (format "\\KOMAoption{fromemail}{%s}\n"
 703                   (if (plist-get info :with-email) "true" "false")))
 704      ;; Phone number.
 705      (let ((phone-number (plist-get info :phone-number)))
 706        (and (org-string-nw-p phone-number)
 707             (funcall check-scope 'phone-number)
 708             (format "\\setkomavar{fromphone}{%s}\n" phone-number)))
 709      (and (funcall check-scope 'with-phone)
 710           (format "\\KOMAoption{fromphone}{%s}\n"
 711                   (if (plist-get info :with-phone) "true" "false")))
 712      ;; Signature.
 713      (let ((signature (plist-get info :signature)))
 714        (and (org-string-nw-p signature)
 715             (funcall check-scope 'signature)
 716             (format "\\setkomavar{signature}{%s}\n" signature)))
 717      ;; Back address.
 718      (and (funcall check-scope 'with-backaddress)
 719           (format "\\KOMAoption{backaddress}{%s}\n"
 720                   (if (plist-get info :with-backaddress) "true" "false")))
 721      ;; Place.
 722      (and (funcall check-scope 'place)
 723           (format "\\setkomavar{place}{%s}\n"
 724                   (if (plist-get info :with-place) (plist-get info :place) "")))
 725      ;; Folding marks.
 726      (and (funcall check-scope 'with-foldmarks)
 727           (let ((foldmarks (plist-get info :with-foldmarks)))
 728             (cond ((consp foldmarks)
 729                    (format "\\KOMAoptions{foldmarks=true,foldmarks=%s}\n"
 730                            (mapconcat #'symbol-name foldmarks "")))
 731                   (foldmarks "\\KOMAoptions{foldmarks=true}\n")
 732                   (t "\\KOMAoptions{foldmarks=false}\n")))))))
 733
 734
 735 \f
 736 ;;; Commands
 737
 738 ;;;###autoload
 739 (defun org-koma-letter-export-as-latex
 740   (&optional async subtreep visible-only body-only ext-plist)
 741   "Export current buffer as a KOMA Scrlttr2 letter.
 742
 743 If narrowing is active in the current buffer, only export its
 744 narrowed part.
 745
 746 If a region is active, export that region.
 747
 748 A non-nil optional argument ASYNC means the process should happen
 749 asynchronously.  The resulting buffer should be accessible
 750 through the `org-export-stack' interface.
 751
 752 When optional argument SUBTREEP is non-nil, export the sub-tree
 753 at point, extracting information from the headline properties
 754 first.
 755
 756 When optional argument VISIBLE-ONLY is non-nil, don't export
 757 contents of hidden elements.
 758
 759 When optional argument BODY-ONLY is non-nil, only write code
 760 between \"\\begin{letter}\" and \"\\end{letter}\".
 761
 762 EXT-PLIST, when provided, is a proeprty list with external
 763 parameters overriding Org default settings, but still inferior to
 764 file-local settings.
 765
 766 Export is done in a buffer named \"*Org KOMA-LETTER Export*\".  It
 767 will be displayed if `org-export-show-temporary-export-buffer' is
 768 non-nil."
 769   (interactive)
 770   (let (org-koma-letter-special-contents)
 771     (org-export-to-buffer 'koma-letter "*Org KOMA-LETTER Export*"
 772       async subtreep visible-only body-only ext-plist
 773       (lambda () (LaTeX-mode)))))
 774
 775 ;;;###autoload
 776 (defun org-koma-letter-export-to-latex
 777   (&optional async subtreep visible-only body-only ext-plist)
 778   "Export current buffer as a KOMA Scrlttr2 letter (tex).
 779
 780 If narrowing is active in the current buffer, only export its
 781 narrowed part.
 782
 783 If a region is active, export that region.
 784
 785 A non-nil optional argument ASYNC means the process should happen
 786 asynchronously.  The resulting file should be accessible through
 787 the `org-export-stack' interface.
 788
 789 When optional argument SUBTREEP is non-nil, export the sub-tree
 790 at point, extracting information from the headline properties
 791 first.
 792
 793 When optional argument VISIBLE-ONLY is non-nil, don't export
 794 contents of hidden elements.
 795
 796 When optional argument BODY-ONLY is non-nil, only write code
 797 between \"\\begin{letter}\" and \"\\end{letter}\".
 798
 799 EXT-PLIST, when provided, is a property list with external
 800 parameters overriding Org default settings, but still inferior to
 801 file-local settings.
 802
 803 When optional argument PUB-DIR is set, use it as the publishing
 804 directory.
 805
 806 Return output file's name."
 807   (interactive)
 808   (let ((outfile (org-export-output-file-name ".tex" subtreep))
 809         (org-koma-letter-special-contents))
 810     (org-export-to-file 'koma-letter outfile
 811       async subtreep visible-only body-only ext-plist)))
 812
 813 ;;;###autoload
 814 (defun org-koma-letter-export-to-pdf
 815   (&optional async subtreep visible-only body-only ext-plist)
 816   "Export current buffer as a KOMA Scrlttr2 letter (pdf).
 817
 818 If narrowing is active in the current buffer, only export its
 819 narrowed part.
 820
 821 If a region is active, export that region.
 822
 823 A non-nil optional argument ASYNC means the process should happen
 824 asynchronously.  The resulting file should be accessible through
 825 the `org-export-stack' interface.
 826
 827 When optional argument SUBTREEP is non-nil, export the sub-tree
 828 at point, extracting information from the headline properties
 829 first.
 830
 831 When optional argument VISIBLE-ONLY is non-nil, don't export
 832 contents of hidden elements.
 833
 834 When optional argument BODY-ONLY is non-nil, only write code
 835 between \"\\begin{letter}\" and \"\\end{letter}\".
 836
 837 EXT-PLIST, when provided, is a property list with external
 838 parameters overriding Org default settings, but still inferior to
 839 file-local settings.
 840
 841 Return PDF file's name."
 842   (interactive)
 843   (let ((file (org-export-output-file-name ".tex" subtreep))
 844         (org-koma-letter-special-contents))
 845     (org-export-to-file 'koma-letter file
 846       async subtreep visible-only body-only ext-plist
 847       (lambda (file) (org-latex-compile file)))))
 848
 849
 850 (provide 'ox-koma-letter)
 851 ;;; ox-koma-letter.el ends here