Re: [O] [patch, ox] Unnumbered headlines

[Nicolas Goaziou]

Hello,

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

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

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.

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

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

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

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

WDYT?


Regards,

-- 
Nicolas Goaziou