From mboxrd@z Thu Jan 1 00:00:00 1970 From: Rasmus Subject: Re: [patch, ox] Unnumbered headlines Date: Mon, 11 Aug 2014 17:37:23 +0200 Message-ID: <87r40n6nrg.fsf@gmx.us> References: <87lhqzyubg.fsf@gmx.us> <87bnrrp0tb.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:59227) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XGrfC-0002lD-Mb for emacs-orgmode@gnu.org; Mon, 11 Aug 2014 11:37:40 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XGrf7-0000w7-60 for emacs-orgmode@gnu.org; Mon, 11 Aug 2014 11:37:34 -0400 Received: from mout.gmx.net ([212.227.17.22]:50632) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XGrf6-0000tX-Rw for emacs-orgmode@gnu.org; Mon, 11 Aug 2014 11:37:29 -0400 In-Reply-To: <87bnrrp0tb.fsf@nicolasgoaziou.fr> (Nicolas Goaziou's message of "Mon, 11 Aug 2014 16:18:08 +0200") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org Cc: alantyree@gmail.com, tsd@tsdye.com Nicolas Goaziou writes: > Hello, > > Rasmus writes: > >> In a recent thread=EF=BB=BF=C2=B9 Tom and Alan mention that authors some= times 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.=20 >> 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 =E2=80=94 since the synt= ax is so awkward =E2=80=94 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 "%s " > 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 "%d " > level > (org-export-get-headline-id headline info)) What I was experiment with is something like:=20 (format "%d " (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 --=20 Bang bang