Re: [patch, ox] Unnumbered headlines

[Rasmus <rasmus@gmx.us>]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Rasmus <rasmus@gmx.us> writes:
>
>> In a recent thread¹ Tom and Alan mention that authors sometimes need
>> unnumbered headlines, e.g. for prefaces.  This patch (tries to) add
>> this feature via the tag :nonumber: (customizable via Custom or
>> in-file).
>
> Interesting.  Some comments follow.
>
>> I make two assumptions.  First, the tag is recursive, so if the parent
>> is not numbered the child is not numbered.
>
> Indeed.
>
>> Secondly, I depart from the LaTeX tradition of ignoring unnumbered
>> headlines in the TOC (except in the case of ox-latex.el where it
>> depends on org-latex-classes). (See example below).
>
> OK.

The TOC part can easily be added, of course, but it's second order at
the moment. 

>> In my opinion a :nonumber: tag is a natural continuation of :export:
>> and :noexport:
>
> First, maybe a tag is not the best way to specify it. Tags are rather
> obnoxious and their length is somewhat limited by the width of the
> window.

True.  Personally, I find them nicer as you can just C-c C-c on your
headline and write down some keyword that is typically easy to
remember.  For properties I must rely on C-c C-x p — since the syntax
is so awkward — and while it may be memorable to me try to explain it
to co-authors who are not long-time Emacs users.

> Another option is to use properties, e.g. "UNNUMBERED", or "NO_NUMBER"
> with a non-nil value
>
>   * Some headline
>     :PROPERTIES:
>     :UNNUMBERED: t
>     :END:
>
> It is harder to notice an unnumbered headline, but it doesn't add cruft
> to the tag line, and this is far less important than :noexport:. This is
> not perfect either, but I think the trade-off is honest.

I can see you point, and I think I agree, though I personally much,
much prefer tags.

Of course a utility function could be added (like the beamer minor
mode) that adds the tag to give you a visual clue while the properties
are really what matter.

> Another advantage is inheritance is already implemented for node
> properties (see `org-export-get-node-property').

Interesting.  I did not know.

>> and unlike :ignoreheading: the implementation is fairly clean (or
>> maybe I'm cheating myself here).
>
> Do not underestimate it: implementing this feature is a bit tricky, and
> will introduce backward incompatible changes to export back-ends
> (possibly outside the scope of core+contrib).
>
> A major problem comes from `org-export-get-headline-number', which
> always returns a unique non-nil value for headlines in a parse tree.
> Even unnumbered headlines (e.g. with option num:2) get a number.

> Consequently, some back-ends use this number as a unique ID, as this
> excerpt from "ox-html.el"
>
>   (format "<span class=\"section-number-%d\">%s</span> "
>           level
>           (mapconcat #'number-to-string numbers "."))
>
> It is not possible to rely on this mechanism with your patch.
>
> A solution is to create two functions for the two features:
>
>   - `org-export-get-headline-number' :: the same as today, but returns
>        nil if headline is unnumbered.
>
>   - `org-export-get-headline-id' :: returns a unique ID, as an integer,
>        for the current headline, notwithstanding its numbering status.
>
> Then `org-export-get-ordinal' should probably try to call the first one
> and fallback to the second one.

In my local branch (not published; still problems with ox-html) I
"solve" this by retaining a number for unnumbered headlines and having
parallel numbering.  That is, there may exists a numbered section X.y
as well as a unnumbered section X.y when applicable.

Of course there is still an issue in that there is no way of
differentiating the a number list from a numbered section and an
unnumbered one and consequently e.g. ox-html IDs will still be broken.

The most elegant way would perhaps be to introduce in the output of
`org-export-get-headline-number' whether a headline is unnumbered, but
I am not sure how to do this without breaking the expected output of
the function.  A dirty fix might be add an extra 0 to the beginning of
the section number list when dealing with unnumbered headings, but it
is not so nice as the numbers loose their meaning. . .

What I am currently trying to do with ox-html is combining
`org-export-get-headline-number' (which is always a list of numbers)
and `org-export-numbered-headline-p' to determine if the ID should
contain the substring "unnumbered".  Then the first unnumbered section
would be "sec-unnumbered-1" and so forth.

> The previous snippet from "ox-html.el" would become
>
>   (format "<span class=\"section-number-%d\">%d</span> "
>           level
>           (org-export-get-headline-id headline info))

What I was experiment with is something like: 

(format "<span class=\"section-number-%s-%d\">%d</span> "
   (if numberedp "" "unumbered")
   level)



Do you think it would be better to work on
`org-export-get-headline-id' and "solve" the issue in that way is a
better approach than what I describe above?

> Obviously, this implies that every back-end using this construct should
> be updated accordingly.

Thanks,
Rasmus

-- 
Bang bang