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

["Ondřej Grover" <ondrej.grover@gmail.com>]

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

Hi Rasmus,

Thanks.  Your snippet doesn't work on these two examples.
>
> Can't promote from level 1:
>
>     * h1
>  :noexport:
>       no export
>     * h2
> :ignore_heading:
>       export
>
I've added a simple (when (> (outline-level) 1) (org-promote)) safety check
to make sure indentation does not fail on level 1 headlines.

> "export" becomes part of the noexport heading.
>
>     * h0
>     ** h1
> :noexport:
>        no export
>     ** h2
> :ignore_heading:
>        export
>
I have no idea how to get around this. It stems from the basic problem in
Org mode that there are no entry closures AFAIK: To export the "export" it
would have to be under a heading that does not have the :noexport: tag.
This is actually one of the reasons why ignoreheading is used in many
cases, to separate entries without creating a real headline.

>
> If this is often needed feature, ox.el and potentially backends should be
> patched to support it.  I think it would be great if ox did support it.
> Of course, Nicolas would have the final say in such a matter.
>
I'm ok with that too, but it should be easily accessible so that people
don't end up using broken snippets from the Internet.
Therefore, such exporting functionality (I think it's mostly backend
agnostic) would have to be well documented in the manual.

> But I'm not sure so difficult hacks should be promoted in the manual.
>
It would indeed be better if the user only enabled some option documented
in the manual instead of using code snippets.

> Improving the example is fine, though.
>
Many of your comments actually touch on the already present sentences and
code, I mostly added just several words to those.

> It's great with better documentation for how to use org-map-entries!  But
> the example is not very robust.  I think another, less complicated example
> would be better.
>
I think it's still reasonably simple and clear for an example. It shows
many useful things.
With the when check it's a bit more robust, but it might get uglier if we
try to somehow deal with the noexport stuff.

Kind regards,
Ondřej Grover

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

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

From 3dabae1cf482f2008b282411468e4b810ec2e19c 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 | 38 +++++++++++++++++++++++++-------------
 1 file changed, 25 insertions(+), 13 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index c400f77..5009361 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -13806,29 +13806,41 @@ with @code{M-x org-html-convert-region-to-html RET}.
 
 @vindex org-export-before-processing-hook
 @vindex org-export-before-parsing-hook
-Two hooks are run during the first steps of the export process.  The first
-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
+Two hooks are run during the first steps of the export process.  The
+first 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 with the
+@samp{ignore_heading} tag (excluding those with the @samp{noexport} tag)
+in the buffer and promote their children 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
+and promote all child headlines underneath them.
 BACKEND is the export back-end being used, as a symbol."
   (org-map-entries
-   (lambda () (delete-region (point) (progn (forward-line) (point))))))
+   (lambda () (progn (org-map-tree (lambda () (when (> (outline-level) 1)
+						(org-promote))))
+		     (delete-region (point) (point-at-eol))))
+   "+ignore_heading-noexport"))
 
-(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 (@pxref{Matching tags and properties}).
+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.  It may also be useful to exclude
+the @samp{ignore_heading} tag from inheritance (@pxref{Tag
+inheritance}).  Also note that functions used in these hooks require a
+mandatory argument, a symbol representing the back-end used.
 
 @subheading Filters
 
-- 
2.1.4