emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Rasmus <rasmus@gmx.us>
To: emacs-orgmode@gnu.org
Cc: alantyree@gmail.com, tsd@tsdye.com
Subject: Re: [patch, ox] Unnumbered headlines
Date: Mon, 11 Aug 2014 17:37:23 +0200	[thread overview]
Message-ID: <87r40n6nrg.fsf@gmx.us> (raw)
In-Reply-To: <87bnrrp0tb.fsf@nicolasgoaziou.fr> (Nicolas Goaziou's message of "Mon, 11 Aug 2014 16:18:08 +0200")

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

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.


Bang bang

  reply	other threads:[~2014-08-11 15:37 UTC|newest]

Thread overview: 27+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2014-08-08 13:39 [patch, ox] Unnumbered headlines Rasmus
2014-08-08 22:35 ` Alan L Tyree
2014-08-09  1:04 ` [patch, ox] Unnumbered headlines - early test Alan L Tyree
2014-08-09  7:47 ` [patch, ox] Unnumbered headlines Detlef Steuer
2014-08-11 14:18 ` Nicolas Goaziou
2014-08-11 15:37   ` Rasmus [this message]
2014-08-12  8:58     ` Nicolas Goaziou
2014-09-20 16:02       ` Rasmus
2014-09-20 20:34         ` Alan L Tyree
2014-09-21 13:12         ` Nicolas Goaziou
2014-09-21 14:37           ` Rasmus
2014-09-21 19:40             ` Nicolas Goaziou
2014-09-21 20:13               ` Rasmus
2014-09-22 15:53                 ` Nicolas Goaziou
2014-09-23  0:35                   ` Rasmus
2014-09-23  1:10                     ` Thomas S. Dye
2014-09-26  7:51                     ` Nicolas Goaziou
2014-09-26 13:48                       ` Rasmus
2014-09-27  8:19                         ` Nicolas Goaziou
2014-09-30 22:54                       ` Rasmus
2014-10-02  0:35                         ` Rasmus
2014-10-03  7:56                         ` Nicolas Goaziou
2014-10-03  8:49                           ` Sebastien Vauban
2014-10-03 10:26                           ` Rasmus
2014-10-03 20:14                             ` Nicolas Goaziou
2014-10-03 20:31                               ` Rasmus
2014-10-05  8:06                                 ` Nicolas Goaziou

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87r40n6nrg.fsf@gmx.us \
    --to=rasmus@gmx.us \
    --cc=alantyree@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    --cc=tsd@tsdye.com \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox


This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).