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