[PATCH]Extend export hook example for removing headlines with tag ignore_heading

[PATCH]Extend export hook example for removing headlines with tag ignore_heading

[Ondřej Grover]

[-- Attachment #1.1: Type: text/plain, Size: 1675 bytes --]

Hello,

I've attached a patch for the Advanced configuration (for exporting)
chapter of the Org mode manual that extends the hook example there to
provide the commonly requested ignoreheading-like functionality found in
the Beamer backend. The example is very simple and adds just one line of
code to the function thanks to the MATCH argument of the `org-map-entries`
function.
The commit message contains the TINYCOMMIT cookie as I'm not a FSF member.

Originally I only intended this solution to be an answer to questions on
StackOverflow that did not help me much (
http://stackoverflow.com/a/29588450/4779220), but I think it is something
very commonly requested and should be documented and easily accessible.

How I discovered this solution:
I've always liked the `ignoreheading` tag functionality in Beamer export. I
wanted to have something like it for all export backends.
The solutions I found on the Internet either didn't work or were filter
based which did not remove the headline nodes in the parsed structure.
So I decided to make my own solution. I found the hook example for removing
all headlines before processing in the Org manual. That was almost what I
wanted, but I needed to limit it to headlines with a tag. I had a look at
the documentation of the `org-map-entries` function and discovered the
MATCH argument that can match tags like in agenda views. So in the end I
added just 1 line of code to the example.

This experience once again showed me that Emacs truly is an extensible
self-documenting editor. I'd like to express my gratitude to all the
contributors of Emacs and Org mode.

Kind regards,
Ondřej Grover

[-- Attachment #1.2: Type: text/html, Size: 1922 bytes --]

[-- Attachment #2: 0001-org.texi-Extend-export-hook-example-with-ignore_head.patch --]
[-- Type: text/x-diff, Size: 2731 bytes --]

From 1e19e5174e21e8ddfd96ed5da5c2cbbb444e9d16 Mon Sep 17 00:00:00 2001
From: Ondrej Grover <ondrej.grover@gmail.com>
Date: Sun, 12 Apr 2015 13:43:31 +0200
Subject: [PATCH] org.texi: Extend export hook example with ignore_heading tag
 support

* doc/org.texi (Advanced configuration): Extend the pre-processing
export hook example to support similar (but simpler and more general)
functionality like that provided by the ignoreheading tag in the
Beamer export backend.  This is a commonly requested snippet and the
Internet is full of much worse and broken solutions, so the manual
should show the recommended solution.

TINYCHANGE
---
 doc/org.texi | 23 ++++++++++++++---------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index c400f77..8dc0a92 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -13811,24 +13811,29 @@ one, @code{org-export-before-processing-hook} is called before expanding
 macros, Babel code and include keywords in the buffer.  The second one,
 @code{org-export-before-parsing-hook}, as its name suggests, happens just
 before parsing the buffer.  Their main use is for heavy duties, that is
-duties involving structural modifications of the document.  For example, one
-may want to remove every headline in the buffer during export.  The following
-code can achieve this:
+duties involving structural modifications of the document. For example, one
+may want to remove every headline with the @samp{ignore_heading} tag in the
+buffer during export.  The following code can achieve this:
 
 @lisp
 @group
-(defun my-headline-removal (backend)
-  "Remove all headlines in the current buffer.
+(defun ignored-headlines-removal (backend)
+  "Remove all headlines with the ignore_headline tag in the current buffer.
 BACKEND is the export back-end being used, as a symbol."
   (org-map-entries
-   (lambda () (delete-region (point) (progn (forward-line) (point))))))
+   (lambda () (delete-region (point) (progn (forward-line) (point))))
+   "ignore_heading"))
 
-(add-hook 'org-export-before-parsing-hook 'my-headline-removal)
+(add-hook 'org-export-before-parsing-hook 'ignored-headlines-removal)
 @end group
 @end lisp
 
-Note that functions used in these hooks require a mandatory argument,
-a symbol representing the back-end used.
+The second argument to the @code{org-map-entries} function is an agenda-style
+match query string. Note the underscore in the tag, it is not recommended to
+use the @samp{ignoreheading} tag because the Beamer export backend treates it
+in a similar, yet more complicated way.  Also note that functions used in
+these hooks require a mandatory argument, a symbol representing the back-end
+used.
 
 @subheading Filters
 
-- 
2.1.4

Re: [PATCH]Extend export hook example for removing headlines with tagignore_heading

[Rasmus]

Hi,

Thanks for the patch. I have not read it as I'm on the mobile.

What is the difference between your patch and org-export-ignore-headlines in
ox-extra?

If you want the functionality in ox.el you should write a solution that uses
a property like UNNUMBERED. It's however a non-trivial problem as discussed
on the org-hacks worg page. This is, IMO, the right way to tackle this
issue, if it is an issue.

Skimming the so answer you link to your suggestion is not robust for ignored
headlines following a no export headline.


Rasmus