contrib/lisp/ox-koma-letter.el

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