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

[Nicolas Goaziou]

Hello,

Ondřej Grover <address@hidden> 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

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