Hi,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Eric Schulte <schulte.eric@gmail.com> writes:
>
>> Why TODO types rather than a tag?  IMO using a TODO type would conflate
>> task management and document structuring.  What do you think about the
>> attached patch which should add this functionality to the core.
>
> Thank you. Unfortunately, in many cases this code will make the parse
> tree invalid. Consider the example below:
>
>   * H1
>     Text1
>   ** H2 :inline:
>     Text2
>
> A simplified version of the parse tree is:
>
>   (headline
>    (section
>     (paragraph "Text1"))
>    (headline
>     (section
>      (paragraph "Text2"))))
>
> With your function, it becomes
>
>   (headline
>    (section
>     (paragraph "Text1"))
>    (section
>     (paragraph "Text2")))
>
> which is invalid, as a given headline is not expected to have more than
> one section.
>
> Of course, it is possible to add code in order to merge both sections
> and get
>
>   (headline
>    (section
>     (paragraph "Text1")
>     (paragraph "Text2")))
>
> which is exactly what you obtain in the first answer of the FAQ, along
> with its limitations (see the :noexport: example in the same question).
>
> Actually, the problem is deeper than that. This :inline: tag is just
> a convoluted way to ask for a positive answer to another FAQ: « Can
> I close an outline section without starting a new section? »
> (http://orgmode.org/worg/org-faq.html#closing-outline-sections). Indeed,
> allowing :include: tags is equivalent to allowing to close sections
> before the next one, at least at the export level:
>
>   * Section one
>
>   Some text
>
>   ** Subsection one
>
>   Some text
>
>   ** Subsection two
>
>   Some text
>
>   ** end Subsection Two                                                     :inline:
>
>   Continue text in section one.
>
> This is not possible and goes against so many assumptions in Org that it
> will always introduce problems, as your function does.
>

Thanks Nicolas.  Point clearly stated.  All of the structural issues
hinge upon the inclusion of the contents of an inlined (ignored)
headline, so the solution is to change the behavior s.t. the non-subtree
contents of ignored headlines are also removed from export.  This is
implemented below.

>
> Since it cannot work in the general case, I do not think it should go in
> core. Fortunately, a simple function in `org-export-before-parsing-hook'
> provides a decent solution already. Users requiring more sophistication
> can always implement their own function and add it to that hook.
>
> OTOH, the situation could be improved wrt :export: and :noexport: tags.
> We could allow nesting :export: tags within :noexport: tags with the
> following rule: the :export: headline with the lowest level within
> the :noexport: tree gets promoted to the root of the tree.
> Other :export: headlines have their level set relatively to this one.
> Thus:
>
>   Text before first headline
>   * H1
>   Body1
>   ** H2 :noexport:
>   Body2
>   *** H3
>   Body3
>   *** H4 :export:
>   Body4
>   **** H5
>   Body5
>
> will be seen as
>
>   Text before first headline
>   * H1
>   Body1
>   ** H4
>   Body4
>   *** H5
>   Body5
>

In my opinion the manual interleaving of "noexport" and "export" tags is
overly cumbersome and is non-obvious.  The obscure nature of this
solution is evidenced by multiple discussions and implementations of
filter functions to handle situations which could be covered by this
noexport/export pattern.

I think the attached patch should be applied to the core.  It includes
the following.

- a single new export function which removes the headlines and contents
  (the "section" element) of headlines tagged "ignoreexport", then
  retains and promotes all sub-headlines contained therein.

- a single new export tag named "ignoreexport" (ignore seems to be the
  crowd favorite, and adding "export" reduces possible conflicts with
  existing personal tags)

- some tests protecting this new functionality

- I'd like to add documentation of this tag to the manual to improve
  visibility beyond the existing FAQ entries (which have failed to
  prevent multiple on list discussions and re-implementations of this
  feature).  It is not clear where to document such a tag.  The "export"
  and "noexport" tags are only documented as a side effect of
  documentation for the SELECT_TAGS keyword.  I think it would be
  beneficial to add a "selective export" section or paragraph (which
  existed in the old manual) to the new manual.

From the included tests, the effect of this patch is to convert a tree
like the following,

,----
| * H1
| Text1
| ** H2                                                          :ignoreexport:
| Text2
| *** H3
| Text3
| **** H4
| Text4
| *** H5
| Text5
| **** H6                                                        :ignoreexport:
| Text6
| ***** H7
| Text7
| ***** H8
| Text8
`----

on export to a tree like the following.

,----
| 1 H1
| ====
| 
|   Text1
| 
| 1.1 H3
| ~~~~~~
| 
|   Text3
| 
| 1.1.1 H4
| --------
| 
|   Text4
| 
| 1.2 H5
| ~~~~~~
| 
|   Text5
| 
| 1.2.1 H7
| --------
| 
|   Text7
| 
| 1.2.2 H8
| --------
| 
|   Text8
`----

I'm sympathetic to arguments about maintaining simplicity of the core,
and even more so to arguments about maintaining structural validity of
trees during export.  I believe that this revised patch fully maintains
valid tree structures, and I'd suggest that the increase in complexity
of a single keyword is justified by the demonstrated user demand for
this functionality.

Thanks,