contrib/lisp/ox-extra.el: Add ignore-headlines filter.

* contrib/lisp/ox-extra.el: Add ignore-headlines filter.

Thanks to Eric Schulte for the code.

Signed-off-by: Aaron Ecay <aaronecay@gmail.com>

contrib/lisp/ox-extra.el

@@ -23,6 +23,12 @@
 ;; are not part of org's core.  Call `ox-extras-activate' passing a
 ;; list of symbols naming extras, which will be installed globally in
 ;; your org session.
+;;
+;; For example, you could include the following in your .emacs file:
+;;
+;;    (require 'ox-extra)
+;;    (ox-extras-activate '(latex-header-blocks ignore-headlines))
+;;
 
 ;; Currently available extras:
 
@@ -35,6 +41,12 @@
 ;;   ...
 ;; #+end_latex
 
+;; - `ignore-headlines' -- allow a headline (but not its children) to
+;; be ignored.  Any headline tagged with the 'ignore' tag will be
+;; ignored (i.e. will not be included in the export), but any child
+;; headlines will not be ignored (unless explicitly tagged to be
+;; ignored), and will instead have their levels promoted by one.
+
 ;; TODO:
 ;; - add a function to org-mode-hook that looks for a ox-extras local
 ;;   variable and activates the specified extras buffer-locally
@@ -75,8 +87,74 @@
 	    ;; earlier in the file
 	    (reverse positions)))))
 
+
+;; During export headlines which have the "ignore" tag are removed
+;; from the parse tree.  Their contents are retained (leading to a
+;; possibly invalid parse tree, which nevertheless appears to function
+;; correctly with most export backends) all children headlines are
+;; retained and are promoted to the level of the ignored parent
+;; headline.
+;;
+;; This makes it possible to add structure to the original Org-mode
+;; document which does not effect the exported version, such as in the
+;; following examples.
+;;
+;; Wrapping an abstract in a headline
+;;
+;;     * Abstract                        :ignore:
+;;     #+LaTeX: \begin{abstract}
+;;     #+HTML: <div id="abstract">
+;;
+;;     ...
+;;
+;;     #+HTML: </div>
+;;     #+LaTeX: \end{abstract}
+;;
+;; Placing References under a headline (using ox-bibtex in contrib)
+;;
+;;     * References                     :ignore:
+;;     #+BIBLIOGRAPHY: dissertation plain
+;;
+;; Inserting an appendix for LaTeX using the appendix package.
+;;
+;;     * Appendix                       :ignore:
+;;     #+LaTeX: \begin{appendices}
+;;     ** Reproduction
+;;     ...
+;;     ** Definitions
+;;     #+LaTeX: \end{appendices}
+;;
+(defun org-export-ignore-headlines (data backend info)
+  "Remove headlines tagged \"ignore\" retaining contents and promoting children.
+Each headline tagged \"ignore\" will be removed retaining its
+contents and promoting any children headlines to the level of the
+parent."
+  (org-element-map data 'headline
+    (lambda (object)
+      (when (member "ignore" (org-element-property :tags object))
+        (let ((level-top (org-element-property :level object))
+              level-diff)
+          (mapc (lambda (el)
+                  ;; recursively promote all nested headlines
+                  (org-element-map el 'headline
+                    (lambda (el)
+                      (when (equal 'headline (org-element-type el))
+                        (unless level-diff
+                          (setq level-diff (- (org-element-property :level el)
+                                              level-top)))
+                        (org-element-put-property el
+                          :level (- (org-element-property :level el)
+                                    level-diff)))))
+                  ;; insert back into parse tree
+                  (org-element-insert-before el object))
+                (org-element-contents object)))
+        (org-element-extract-element object)))
+    info nil)
+  data)
+
 (defconst ox-extras
-  '((latex-header-blocks org-latex-header-blocks-filter org-export-before-parsing-hook))
+  '((latex-header-blocks org-latex-header-blocks-filter org-export-before-parsing-hook)
+    (ignore-headlines org-export-ignore-headlines org-export-filter-parse-tree-functions))
   "A list of org export extras that can be enabled.
 
 Should be a list of items of the form (NAME FN HOOK).  NAME is a