emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [PATCH]Extend export hook example for removing headlines with tag ignore_heading
@ 2015-04-12 11:59 Ondřej Grover
  0 siblings, 0 replies; 7+ messages in thread
From: Ondřej Grover @ 2015-04-12 11:59 UTC (permalink / raw)
  To: emacs-orgmode


[-- 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


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: [PATCH]Extend export hook example for removing headlines with tag ignore_heading
@ 2015-04-13 15:23 Ondřej Grover
  2015-04-13 16:09 ` Rasmus
  0 siblings, 1 reply; 7+ messages in thread
From: Ondřej Grover @ 2015-04-13 15:23 UTC (permalink / raw)
  To: emacs-orgmode


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

Hi Rasmus,

I wasn't aware of this functionality being added to ox-extra, thank you for
pointing it out.
I've revised my patch to accommodate your suggestions and attached the new
version. Now it excludes noexport tagged headlines from removal and
promotes child headlines.
Using properties for this is also possible because the match string can
match properties too. I just find tags simpler for this case.
I'm trying to point out that something like this is often needed and a
definitive solution should be listed somewhere, preferably in the manual.
Otherwise someone looking for a solution to this common problem will end up
finding only half-baked, possibly broken examples.

Kind regards,
Ondřej Grover

On Sun, Apr 12, 2015 at 3:32 PM, Rasmus <rasmus@gmx.us> wrote:

> 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
>
>
>

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

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

From 9c75f9796a0fe4d270b72b503b318ddb6e4e3954 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 | 37 ++++++++++++++++++++++++-------------
 1 file changed, 24 insertions(+), 13 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index c400f77..cc75a79 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -13806,29 +13806,40 @@ 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 '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


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: [PATCH]Extend export hook example for removing headlines with tag ignore_heading
  2015-04-13 15:23 [PATCH]Extend export hook example for removing headlines with tag ignore_heading Ondřej Grover
@ 2015-04-13 16:09 ` Rasmus
  2015-04-13 18:13   ` Ondřej Grover
  0 siblings, 1 reply; 7+ messages in thread
From: Rasmus @ 2015-04-13 16:09 UTC (permalink / raw)
  To: emacs-orgmode

Hi Ondřej,

Ondřej Grover <ondrej.grover@gmail.com> writes:

> I've revised my patch to accommodate your suggestions and attached the new
> version. Now it excludes noexport tagged headlines from removal and
> promotes child headlines.

Thanks.  Your snippet doesn't work on these two examples.

Can't promote from level 1:

    * h1							   :noexport:
      no export
    * h2  						      :ignore_heading:
      export

"export" becomes part of the noexport heading.

    * h0
    ** h1 								   :noexport:
       no export
    ** h2 							     :ignore_heading:
       export

> I'm trying to point out that something like this is often needed and a
> definitive solution should be listed somewhere, preferably in the manual.
> Otherwise someone looking for a solution to this common problem will end up
> finding only half-baked, possibly broken examples.

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.

But I'm not sure so difficult hacks should be promoted in the manual.

Improving the example is fine, though.

> From 9c75f9796a0fe4d270b72b503b318ddb6e4e3954 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 | 37 ++++++++++++++++++++++++-------------
>  1 file changed, 24 insertions(+), 13 deletions(-)
>
> diff --git a/doc/org.texi b/doc/org.texi
> index c400f77..cc75a79 100644
> --- a/doc/org.texi
> +++ b/doc/org.texi
> @@ -13806,29 +13806,40 @@ with @code{M-x org-html-convert-region-to-html RET}.
>  
>  @vindex org-export-before-processing-hook
>  @vindex org-export-before-parsing-hook

Why do you delete these indexes?

> -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
                                                      ,  (I think)
> +expanding macros, Babel code and include keywords in the buffer.  The
> +second one, @code{org-export-before-parsing-hook}, as its name suggests,
                                                    ^^^^^^^^^^^^^^^^^^^^^^^
                                                    I'd just kill that one. 
> +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 '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
Maybe: The second argument to @code{org-map-entries} 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.
   ^^^^^^^^^

This function is fine as well: (λ (&optional ignored) (· ⋯)).

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.

Also, perhaps it would make sense to also show how to use org-element-map
to solve the same problem.  Of course that's a separate patch.

Thanks,
Rasmus

-- 
I hear there's rumors on the, uh, Internets. . .

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH]Extend export hook example for removing headlines with tag ignore_heading
  2015-04-13 16:09 ` Rasmus
@ 2015-04-13 18:13   ` Ondřej Grover
  2015-04-13 19:42     ` Nicolas Goaziou
  2015-04-13 19:59     ` Rasmus
  0 siblings, 2 replies; 7+ messages in thread
From: Ondřej Grover @ 2015-04-13 18:13 UTC (permalink / raw)
  To: emacs-orgmode


[-- 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


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: [PATCH]Extend export hook example for removing headlines with tag ignore_heading
  2015-04-13 18:13   ` Ondřej Grover
@ 2015-04-13 19:42     ` Nicolas Goaziou
  2015-04-13 22:40       ` Suvayu Ali
  2015-04-13 19:59     ` Rasmus
  1 sibling, 1 reply; 7+ messages in thread
From: Nicolas Goaziou @ 2015-04-13 19:42 UTC (permalink / raw)
  To: Ondřej Grover; +Cc: emacs-orgmode

Hello,

Ondřej Grover <ondrej.grover@gmail.com> writes:

Thanks for the patch. Some comments follow.

>> "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 why it shouldn't be included in "ox.el". It may be useful, but
it is broken.

It might be fixable with proper specifications and by working at the
parse tree level, tho.

> +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
          ^^^^
       missing space

> +@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."

First sentence in docstrings should fit in a single line.

>    (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))))

Nitpick : `point-at-eol' -> `line-end-position'

> +   "+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.

This is really out of the example scope. Also, `org-map-entries' is
already extensively documented in the manual.

> It may also be useful to exclude +the @samp{ignore_heading} tag from
> inheritance (@pxref{Tag +inheritance}).

Also off-topic.

Please keep in mind this is an example to illustrate
`org-export-before-parsing-hook', not really a place to document some
hack.


Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH]Extend export hook example for removing headlines with tag ignore_heading
  2015-04-13 18:13   ` Ondřej Grover
  2015-04-13 19:42     ` Nicolas Goaziou
@ 2015-04-13 19:59     ` Rasmus
  1 sibling, 0 replies; 7+ messages in thread
From: Rasmus @ 2015-04-13 19:59 UTC (permalink / raw)
  To: emacs-orgmode

Ondřej Grover <ondrej.grover@gmail.com> writes:

> 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.

This is the format.  Comparing to org-inlinetasks, I prefer the standard
way.  I put my noexport headings in the end of the document.

>> 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.

Patches welcome.  Note it's a difficult tasks and you should read up on
previous discussions of this topic beforehand.

>> 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.

It's perfectly fine to use filters and hooks.  I have 12 in my latex
configuration alone.  But it's hacks.  The manual should not promote
hacks.

Org-hacks on Worg already has a section on ignoreheading, though it should
be updated to mention the solution in ox-extra.el.

> I think it's still reasonably simple and clear for an example. It shows
> many useful things.

But it lacks correctness.  Why not solve a simpler problem that can be
solved correctly?

> +Two hooks are run during the first steps of the export process.  The
> +first one, @code{org-export-before-processing-hook} is called before
Missing comma:                                        ,

> +expanding macros, Babel code and include keywords in the buffer.  The
> +second one, @code{org-export-before-parsing-hook}, as its name suggests,
"as its name suggests," is unnecessary.
> +happens just before parsing the buffer.  Their main use is for heavy
> +duties, that is duties involving structural modifications of the
> +document.

The first part of the sentence is unnecessary. 

> 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

See above.

>  @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

The first line should be a complete sentence, and it's too long here.

> +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"))
>

progn is unneeded.

> +The second argument to the @code{org-map-entries} function is an
> +agenda-style match query string (@pxref{Matching tags and properties}).

Fine.

> +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.

This promotes poor usage patterns IMO cf. above.

—Rasmus

-- 
This is the kind of tedious nonsense up with which I will not put

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH]Extend export hook example for removing headlines with tag ignore_heading
  2015-04-13 19:42     ` Nicolas Goaziou
@ 2015-04-13 22:40       ` Suvayu Ali
  0 siblings, 0 replies; 7+ messages in thread
From: Suvayu Ali @ 2015-04-13 22:40 UTC (permalink / raw)
  To: emacs-orgmode; +Cc: Ondřej Grover

Hi,

I would like to chime in here.

On Mon, Apr 13, 2015 at 09:42:58PM +0200, Nicolas Goaziou wrote:
> 
> Please keep in mind this is an example to illustrate
> `org-export-before-parsing-hook', not really a place to document some
> hack.

Is it a good idea to promote org-export-before-parsing-hook in the
manual?  As shown by this example, most solutions would be case specific
with unforeseen consequences.  I believe this was one of the reasons the
original ignoreheading hack from pre-8.0 days was converted to filter.

I think Worg is a more appropriate place for such content.  In-fact,
exactly this particular use is already being documented by someone in
exporters/ox-overview.org.  At the moment it is under noexport, so only
visible on the git repo.

http://orgmode.org/w/worg.git?p=worg.git;a=blob;f=exporters/ox-overview.org;h=98976fc65e3c4d2a55650651091d2e12e194a581;hb=HEAD#l294

WDYT?

-- 
Suvayu

Open source is the future. It sets us free.

^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2015-04-13 22:40 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2015-04-13 15:23 [PATCH]Extend export hook example for removing headlines with tag ignore_heading Ondřej Grover
2015-04-13 16:09 ` Rasmus
2015-04-13 18:13   ` Ondřej Grover
2015-04-13 19:42     ` Nicolas Goaziou
2015-04-13 22:40       ` Suvayu Ali
2015-04-13 19:59     ` Rasmus
  -- strict thread matches above, loose matches on Subject: below --
2015-04-12 11:59 Ondřej Grover

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).