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