contrib/lisp/ox-extra.el

   1 ;;; ox-extra.el --- Convenience functions for org export
   2
   3 ;; Copyright (C) 2014  Aaron Ecay
   4
   5 ;; Author: Aaron Ecay <aaronecay@gmail.com>
   6
   7 ;; This program is free software; you can redistribute it and/or modify
   8 ;; it under the terms of the GNU General Public License as published by
   9 ;; the Free Software Foundation, either version 3 of the License, or
  10 ;; (at your option) any later version.
  11
  12 ;; This program is distributed in the hope that it will be useful,
  13 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 ;; GNU General Public License for more details.
  16
  17 ;; You should have received a copy of the GNU General Public License
  18 ;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
  19
  20 ;;; Commentary:
  21
  22 ;; This file contains some convenience functions for org export, which
  23 ;; are not part of org's core.  Call `ox-extras-activate' passing a
  24 ;; list of symbols naming extras, which will be installed globally in
  25 ;; your org session.
  26 ;;
  27 ;; For example, you could include the following in your .emacs file:
  28 ;;
  29 ;;    (require 'ox-extra)
  30 ;;    (ox-extras-activate '(latex-header-blocks ignore-headlines))
  31 ;;
  32
  33 ;; Currently available extras:
  34
  35 ;; - `latex-header-blocks' -- allow the use of latex blocks, the
  36 ;; contents of which which will be interpreted as #+latex_header lines
  37 ;; for export.  These blocks should be tagged with #+header: :header
  38 ;; yes.  For example:
  39 ;; #+header: :header yes
  40 ;; #+begin_latex
  41 ;;   ...
  42 ;; #+end_latex
  43
  44 ;; - `ignore-headlines' -- allow a headline (but not its children) to
  45 ;; be ignored.  Any headline tagged with the 'ignore' tag will be
  46 ;; ignored (i.e. will not be included in the export), but any child
  47 ;; headlines will not be ignored (unless explicitly tagged to be
  48 ;; ignored), and will instead have their levels promoted by one.
  49
  50 ;; TODO:
  51 ;; - add a function to org-mode-hook that looks for a ox-extras local
  52 ;;   variable and activates the specified extras buffer-locally
  53 ;; - allow specification of desired extras to be activated via
  54 ;;   customize
  55
  56 ;;; Code:
  57
  58 (require 'ox)
  59 (eval-when-compile (require 'cl))
  60
  61 (defun org-latex-header-blocks-filter (backend)
  62   (when (org-export-derived-backend-p backend 'latex)
  63     (let ((positions
  64            (org-element-map (org-element-parse-buffer 'greater-element nil) 'export-block
  65              (lambda (block)
  66                (when (and (string= (org-element-property :type block) "LATEX")
  67                           (string= (org-export-read-attribute
  68                                     :header block :header)
  69                                    "yes"))
  70                  (list (org-element-property :begin block)
  71                        (org-element-property :end block)
  72                        (org-element-property :post-affiliated block)))))))
  73       (mapc (lambda (pos)
  74               (goto-char (nth 2 pos))
  75               (destructuring-bind
  76                   (beg end &rest ignore)
  77                   (org-edit-src-find-region-and-lang)
  78                 (let ((contents-lines (split-string
  79                                        (buffer-substring-no-properties beg end)
  80                                        "\n")))
  81                   (delete-region (nth 0 pos) (nth 1 pos))
  82                   (dolist (line contents-lines)
  83                     (insert (concat "#+latex_header: "
  84                                     (replace-regexp-in-string "\\` *" "" line)
  85                                     "\n"))))))
  86             ;; go in reverse, to avoid wrecking the numeric positions
  87             ;; earlier in the file
  88             (reverse positions)))))
  89
  90
  91 ;; During export headlines which have the "ignore" tag are removed
  92 ;; from the parse tree.  Their contents are retained (leading to a
  93 ;; possibly invalid parse tree, which nevertheless appears to function
  94 ;; correctly with most export backends) all children headlines are
  95 ;; retained and are promoted to the level of the ignored parent
  96 ;; headline.
  97 ;;
  98 ;; This makes it possible to add structure to the original Org-mode
  99 ;; document which does not effect the exported version, such as in the
 100 ;; following examples.
 101 ;;
 102 ;; Wrapping an abstract in a headline
 103 ;;
 104 ;;     * Abstract                        :ignore:
 105 ;;     #+LaTeX: \begin{abstract}
 106 ;;     #+HTML: <div id="abstract">
 107 ;;
 108 ;;     ...
 109 ;;
 110 ;;     #+HTML: </div>
 111 ;;     #+LaTeX: \end{abstract}
 112 ;;
 113 ;; Placing References under a headline (using ox-bibtex in contrib)
 114 ;;
 115 ;;     * References                     :ignore:
 116 ;;     #+BIBLIOGRAPHY: dissertation plain
 117 ;;
 118 ;; Inserting an appendix for LaTeX using the appendix package.
 119 ;;
 120 ;;     * Appendix                       :ignore:
 121 ;;     #+LaTeX: \begin{appendices}
 122 ;;     ** Reproduction
 123 ;;     ...
 124 ;;     ** Definitions
 125 ;;     #+LaTeX: \end{appendices}
 126 ;;
 127 (defun org-export-ignore-headlines (data backend info)
 128   "Remove headlines tagged \"ignore\" retaining contents and promoting children.
 129 Each headline tagged \"ignore\" will be removed retaining its
 130 contents and promoting any children headlines to the level of the
 131 parent."
 132   (org-element-map data 'headline
 133     (lambda (object)
 134       (when (member "ignore" (org-element-property :tags object))
 135         (let ((level-top (org-element-property :level object))
 136               level-diff)
 137           (mapc (lambda (el)
 138                   ;; recursively promote all nested headlines
 139                   (org-element-map el 'headline
 140                     (lambda (el)
 141                       (when (equal 'headline (org-element-type el))
 142                         (unless level-diff
 143                           (setq level-diff (- (org-element-property :level el)
 144                                               level-top)))
 145                         (org-element-put-property el
 146                           :level (- (org-element-property :level el)
 147                                     level-diff)))))
 148                   ;; insert back into parse tree
 149                   (org-element-insert-before el object))
 150                 (org-element-contents object)))
 151         (org-element-extract-element object)))
 152     info nil)
 153   data)
 154
 155 (defconst ox-extras
 156   '((latex-header-blocks org-latex-header-blocks-filter org-export-before-parsing-hook)
 157     (ignore-headlines org-export-ignore-headlines org-export-filter-parse-tree-functions))
 158   "A list of org export extras that can be enabled.
 159
 160 Should be a list of items of the form (NAME FN HOOK).  NAME is a
 161 symbol, which can be passed to `ox-extras-activate'.  FN is a
 162 function which will be added to HOOK.")
 163
 164 (defun ox-extras-activate (extras)
 165   "Activate certain org export extras.
 166
 167 EXTRAS should be a list of extras (defined in `ox-extras') which
 168 should be activated."
 169   (dolist (extra extras)
 170     (let* ((lst (assq extra ox-extras))
 171            (fn (nth 1 lst))
 172            (hook (nth 2 lst)))
 173       (when (and fn hook)
 174         (add-hook hook fn)))))
 175
 176 (defun ox-extras-deactivate (extras)
 177   "Deactivate certain org export extras.
 178
 179 This function is the opposite of `ox-extras-activate'.  EXTRAS
 180 should be a list of extras (defined in `ox-extras') which should
 181 be activated."
 182   (dolist (extra extras)
 183     (let* ((lst (assq extra ox-extras))
 184            (fn (nth 1 lst))
 185            (hook (nth 2 lst)))
 186       (when (and fn hook)
 187         (remove-hook hook fn)))))
 188
 189 (provide 'ox-extra)
 190 ;;; ox-extra.el ends here