Re: [patch, ox] Unnumbered headlines

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

Rasmus <rasmus@gmx.us> writes:

> I'm happy to finally be able to send an updated version of this patch
> that touches most backends in lisp/, but not the manual.  I have been
> moving over the summer etc.

Thanks for that work.  Some comments follow.

> You now specify unnumbered headlines with properties.  I think this is
> better since being unnumbered it's a pretty permanent state.  It's
> pretty hard to discover though, other than by looking at the output.
>
> So this works as expected:
>
> * Some headline
>   :PROPERTIES:
>   :UNNUMBERED: t
>   :END:
>
> There's no :NUMBERED property and :UNNUMBERED is hardcoded.

Sounds good.

> I introduce a new function `org-export-get-headline-id` which returns
> the first non-nil from the following list.  There's a caveat:
> CUSTOM_ID is ensured to be unique!  Did I open the famous can of worm?
>
> 1. The CUSTOM_ID property.
> 2. A relative level number if the headline is numbered.
> 3. The ID property
> 4. A new generated unique ID.

I think we should keep separated CUSTOM_ID and ID on the one hand, and
internal reference on the other hand.

There's no guarantee that CUSTOM_ID will be unique, and, even if you
check it out, there's no guarantee either that its value can be used
as-is in the generated docstring (think about ":CUSTOM_ID: 100%" in
LaTeX export).

CUSTOM_ID is a human readable reference to an Org headline. This
headline should be referred to internally with a more specific id. To
a lesser extent, I think this also applied to org-id.

Also `org-export-headline-internal-id' (or some such, to avoid confusion
with other IDs) may return a value simpler than what `org-id-new'
returns (e.g. a dumb counter). If it is possible, the output will be
easier to read.

> Anyhow, `org-export-get-headline-id' ensures that we can refer to
> unnumbered headlines, which was not possible before.

This is untrue.

> Of course, in LaTeX such ref to a \section* will be nonsense, so we
> could introduce a \pageref here.

At the moment, referring to an unnumbered section displays its name.

> I'm unsure about whether this conflicts `org-latex-custom-id-as-label'
> which I had never seen until today (also notes on this in patch).

This variable has its use if custom-id and internal representation are
separated.

> PS: Not knowing or caring much about md, the links generated by it to
> headlines seem wrong.  Referring to headline 1 it only prints "1".
> Should it be something like "[LABEL](1)"?

There is probably something to do here, but that would be in another
patch.

> * ox-odt.el (org-odt-headline, org-odt-link,
> org-odt-link--infer-description): Support unnumbered
> headline.
> * ox-md.el (org-md-headline, org-md-link): Support
> unnumbered headlines.
> * ox-latex.el (org-latex-headline, org.latex-link): Support
> unnumbered headlines.
> * ox-html.el (org-html-headline, org-html-link): Support
> unnumbered headlines.
> * ox-ascii.el (org-ascii-link): Support ununbered headlines.

You can also write "Support unnumbered headlines" just once.

> +		(when (equal 'headline (org-element-type destination))

Comparing symbols with `equal' is a sin beyond redemption. Use `eq'.

> +		  (format "[%s]" (org-export-data (org-export-get-alt-title destination info) info)))))))))

alt title is for table of contents only.

>       (t
>        (if (not (org-string-nw-p desc)) (format "[%s]" raw-link)
>  	(concat (format "[%s]" desc)
> diff --git a/lisp/ox-html.el b/lisp/ox-html.el
> index 1d424cc..94cee20 100644
> --- a/lisp/ox-html.el
> +++ b/lisp/ox-html.el
> @@ -2321,7 +2321,7 @@ holding contextual information."
>    (unless (org-element-property :footnote-section-p headline)
>      (let* ((numberedp (org-export-numbered-headline-p headline info))
>             (numbers (org-export-get-headline-number headline info))
> -           (section-number (mapconcat #'number-to-string numbers "-"))
> +           (section-number (when numbers (mapconcat #'number-to-string numbers "-")))

Nitpick: I suggest `and' instead of `when' since there's no side-effect.

> +                            (when section-number (concat "sec-" section-number))

Ditto.

> +  (unless (org-export-get-node-property :UNNUMBERED headline t)

Actually, this test is fragile. In the following example

  * H1
    :PROPERTIES:
    :UNNUMBERED: t
    :END:
  ** H2
     :PROPERTIES:
     :UNNUMBERED: nil
     :END:
  *** H3

H3 should clearly be unnumbered even though inheritance disagrees. This
is a bit stronger than inheritance: if there is a single non-nil
UNNUMBERED property among ancestors (or the headline itself), it cannot
be numbered.


Regards,

-- 
Nicolas Goaziou