ox-extra.el (7733B)
1 ;;; ox-extra.el --- Convenience functions for org export 2 3 ;; Copyright (C) 2014, 2021 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 <https://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_export latex 41 ;; ... 42 ;; #+end_export 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 (require 'cl-lib) 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 (cl-destructuring-bind 76 (beg end &rest ignore) 77 ;; FIXME: `org-edit-src-find-region-and-lang' was 78 ;; removed in 9c06f8cce (2014-11-11). 79 (org-edit-src-find-region-and-lang) 80 (let ((contents-lines (split-string 81 (buffer-substring-no-properties beg end) 82 "\n"))) 83 (delete-region (nth 0 pos) (nth 1 pos)) 84 (dolist (line contents-lines) 85 (insert (concat "#+latex_header: " 86 (replace-regexp-in-string "\\` *" "" line) 87 "\n")))))) 88 ;; go in reverse, to avoid wrecking the numeric positions 89 ;; earlier in the file 90 (reverse positions))))) 91 92 93 ;; During export headlines which have the "ignore" tag are removed 94 ;; from the parse tree. Their contents are retained (leading to a 95 ;; possibly invalid parse tree, which nevertheless appears to function 96 ;; correctly with most export backends) all children headlines are 97 ;; retained and are promoted to the level of the ignored parent 98 ;; headline. 99 ;; 100 ;; This makes it possible to add structure to the original Org-mode 101 ;; document which does not effect the exported version, such as in the 102 ;; following examples. 103 ;; 104 ;; Wrapping an abstract in a headline 105 ;; 106 ;; * Abstract :ignore: 107 ;; #+LaTeX: \begin{abstract} 108 ;; #+HTML: <div id="abstract"> 109 ;; 110 ;; ... 111 ;; 112 ;; #+HTML: </div> 113 ;; #+LaTeX: \end{abstract} 114 ;; 115 ;; Placing References under a headline (using ox-bibtex in contrib) 116 ;; 117 ;; * References :ignore: 118 ;; #+BIBLIOGRAPHY: dissertation plain 119 ;; 120 ;; Inserting an appendix for LaTeX using the appendix package. 121 ;; 122 ;; * Appendix :ignore: 123 ;; #+LaTeX: \begin{appendices} 124 ;; ** Reproduction 125 ;; ... 126 ;; ** Definitions 127 ;; #+LaTeX: \end{appendices} 128 ;; 129 (defun org-export-ignore-headlines (data backend info) 130 "Remove headlines tagged \"ignore\" retaining contents and promoting children. 131 Each headline tagged \"ignore\" will be removed retaining its 132 contents and promoting any children headlines to the level of the 133 parent." 134 (org-element-map data 'headline 135 (lambda (object) 136 (when (member "ignore" (org-element-property :tags object)) 137 (let ((level-top (org-element-property :level object)) 138 level-diff) 139 (mapc (lambda (el) 140 ;; recursively promote all nested headlines 141 (org-element-map el 'headline 142 (lambda (el) 143 (when (equal 'headline (org-element-type el)) 144 (unless level-diff 145 (setq level-diff (- (org-element-property :level el) 146 level-top))) 147 (org-element-put-property el 148 :level (- (org-element-property :level el) 149 level-diff))))) 150 ;; insert back into parse tree 151 (org-element-insert-before el object)) 152 (org-element-contents object))) 153 (org-element-extract-element object))) 154 info nil) 155 (org-extra--merge-sections data backend info) 156 data) 157 158 (defun org-extra--merge-sections (data _backend info) 159 (org-element-map data 'headline 160 (lambda (hl) 161 (let ((sections 162 (cl-loop 163 for el in (org-element-map (org-element-contents hl) 164 '(headline section) #'identity info) 165 until (eq (org-element-type el) 'headline) 166 collect el))) 167 (when (and sections 168 (> (length sections) 1)) 169 (apply #'org-element-adopt-elements 170 (car sections) 171 (cl-mapcan (lambda (s) (org-element-contents s)) 172 (cdr sections))) 173 (mapc #'org-element-extract-element (cdr sections))))) 174 info)) 175 176 (defconst ox-extras 177 '((latex-header-blocks org-latex-header-blocks-filter org-export-before-parsing-hook) 178 (ignore-headlines org-export-ignore-headlines org-export-filter-parse-tree-functions)) 179 "A list of org export extras that can be enabled. 180 181 Should be a list of items of the form (NAME FN HOOK). NAME is a 182 symbol, which can be passed to `ox-extras-activate'. FN is a 183 function which will be added to HOOK.") 184 185 (defun ox-extras-activate (extras) 186 "Activate certain org export extras. 187 188 EXTRAS should be a list of extras (defined in `ox-extras') which 189 should be activated." 190 (dolist (extra extras) 191 (let* ((lst (assq extra ox-extras)) 192 (fn (nth 1 lst)) 193 (hook (nth 2 lst))) 194 (when (and fn hook) 195 (add-hook hook fn))))) 196 197 (defun ox-extras-deactivate (extras) 198 "Deactivate certain org export extras. 199 200 This function is the opposite of `ox-extras-activate'. EXTRAS 201 should be a list of extras (defined in `ox-extras') which should 202 be activated." 203 (dolist (extra extras) 204 (let* ((lst (assq extra ox-extras)) 205 (fn (nth 1 lst)) 206 (hook (nth 2 lst))) 207 (when (and fn hook) 208 (remove-hook hook fn))))) 209 210 (provide 'ox-extra) 211 ;;; ox-extra.el ends here