ox-extra.el 7.5 KB

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