[PATCH] Export: Override headline numbering via properties

[PATCH] Export: Override headline numbering via properties

[Mark Edgington]

* lisp/ox.el (org-export-numbered-headline-p): If the `:NUMBERED' property is
defined for a headline, turn numbering on when the property value is "y"
(otherwise turn numbering off).  Do the same if the `:INHERITED_NUMBERED'
property is defined for a headline, except make this property inherited by
child nodes.  If both properties are nil or not defined, resort to the
default numbering
behavior.

TINYCHANGE
---
 lisp/ox.el | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/lisp/ox.el b/lisp/ox.el
index 06513d2..137db9e 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -3721,8 +3721,14 @@ INFO is a plist holding contextual information."
   "Return a non-nil value if HEADLINE element should be numbered.
 INFO is a plist used as a communication channel."
   (let ((sec-num (plist-get info :section-numbers))
-       (level (org-export-get-relative-level headline info)))
-    (if (wholenump sec-num) (<= level sec-num) sec-num)))
+       (level (org-export-get-relative-level headline info))
+    (numbered (org-export-get-node-property :NUMBERED headline))
+    (inherited-numbered (org-export-get-node-property
:INHERITED_NUMBERED headline t))) ; y, n, or nil
+    (if numbered ; if the numbered property is defined
+        (equal numbered "y") ; anything other than "y" means un-numbered
+        (if inherited-numbered
+            (equal inherited-numbered "y")
+            (if (wholenump sec-num) (<= level sec-num) sec-num))))) ;
default behavior

 (defun org-export-number-to-roman (n)
   "Convert integer N into a roman numeral."
--
1.8.2.2

Re: [PATCH] Export: Override headline numbering via properties

[Nicolas Goaziou]

Hello,

Mark Edgington <edgimar@gmail.com> writes:

> * lisp/ox.el (org-export-numbered-headline-p): If the `:NUMBERED' property is
> defined for a headline, turn numbering on when the property value is "y"
> (otherwise turn numbering off).  Do the same if the `:INHERITED_NUMBERED'
> property is defined for a headline, except make this property inherited by
> child nodes.  If both properties are nil or not defined, resort to the
> default numbering
> behavior.

Thanks for your patch.

Though, I don't get what you are trying to achieve nor what a use case
would be. Have you tested this patch ? It may not behave as you expect
it to.


Regards,

-- 
Nicolas Goaziou

Re: [PATCH] Export: Override headline numbering via properties

[Mark Edgington]

Hello Nicolas,

I'm sorry for not having provided more explanation of the patch's
purpose.  The motivation is basically to permit any kind of "manual"
(in contrast to "automatic") control over the section-numbering
behavior connected with a particular headline.  In LaTeX, for example,
you are able to make any section numbered or un-numbered, however in
org-mode, there is an artificial restriction when using numbering that
sections of a particular depth must be either all numbered, or all
un-numbered.

A couple possible use-cases:

1. a document (or chapter of a document) where the first  headline
contains general "introduction" information explaining what the rest
of the document (chapter) is about (similar to an abstract, but not
identical -- something that might contain sub-headings, lists, tables,
etc.), and the remainder of the document (chapter) is the "real"
content of the document -- the place where you want the numbering to
begin.

2. a document where only one of the headlines and its child-headlines
halfway through the document should be un-numbered (maybe they
represent an "example docoument" embedded within an
instruction-manual).

The reason there are two different properties (a normal, and an
"inherited" version) is because use-case #2 could be painful if you
had to add a ":NUMBERED: n" property to every node of the
sub-document.  There are probably several other use-cases to be
discovered that this allows.  Simply put, the patch makes it possible
to control the numbering for a single headline (one specific headline,
not a headline-level), or to set a manual default numbering behavior
for a sub-tree of headlines.  All other headlines behave according to
the current org-mode numbering rules.

Regards,

Mark

Re: [PATCH] Export: Override headline numbering via properties

[Nicolas Goaziou]

Hello,

Mark Edgington <edgimar@gmail.com> writes:

> A couple possible use-cases:
>
> 1. a document (or chapter of a document) where the first  headline
> contains general "introduction" information explaining what the rest
> of the document (chapter) is about (similar to an abstract, but not
> identical -- something that might contain sub-headings, lists, tables,
> etc.), and the remainder of the document (chapter) is the "real"
> content of the document -- the place where you want the numbering to
> begin.

You can still number these parts manually with, e.g.,

  #+latex: \section*{Introduction}

before the first section in your Org document.

> 2. a document where only one of the headlines and its child-headlines
> halfway through the document should be un-numbered (maybe they
> represent an "example docoument" embedded within an
> instruction-manual).

I may be wrong, but this sounds like a hypothetical use case to me.

Anyway, your patch will not work on back-ends that rely on Org to
compute section numbers (e.g., ascii, html...) because even if you
ignore numbering for a particular headline, it still adds up internally.
IOW, you also need to patch `org-export--collect-headline-numbering'.

But that's not quite it, yet. Some back-ends (e.g., html) use that
internal number as a unique identifier for the headline. Actually, the
"artificial restriction" you are talking about is a way to allow every
headline to be numbered in a unique way, even if that number doesn't
appear in the output.

Therefore, you need to generate a unique identifier for all headlines,
a function to return it, and modify each back-end accordingly. This is
obviously doable, but it cannot fit in a TINYPATCH.

Since I wouldn't use this, I can hardly judge, but I would appreciate
some feedback from other users before we go too far in the
implementation.


Regards,

-- 
Nicolas Goaziou

Re: [PATCH] Export: Override headline numbering via properties

[Mark Edgington]

Hi Nicolas,

On Mon, May 13, 2013 at 6:54 AM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
>
> You can still number these parts manually with, e.g.,
>
>   #+latex: \section*{Introduction}
>
> before the first section in your Org document.
>

While this is possible, wouldn't this break the structure of the
org-document, so that a section no longer corresponds to a headline in
some cases.  Also, when the un-numbered section is at the same level
as the top-level headlines, then there would be no way of cleanly
folding away its content in emacs.  Furthermore, by manually inserting
LaTeX code, you make it non-portable for other exporters.

>> 2. a document where only one of the headlines and its child-headlines
>> halfway through the document should be un-numbered (maybe they
>> represent an "example docoument" embedded within an
>> instruction-manual).
>
> I may be wrong, but this sounds like a hypothetical use case to me.

I have certainly encountered cases like this, where I will resort to
using pure LaTeX, but it would be obviously more convenient to be able
to work on such documents via org-mode.

> Anyway, your patch will not work on back-ends that rely on Org to
> compute section numbers (e.g., ascii, html...) because even if you
> ignore numbering for a particular headline, it still adds up internally.
> IOW, you also need to patch `org-export--collect-headline-numbering'.
>
> But that's not quite it, yet. Some back-ends (e.g., html) use that
> internal number as a unique identifier for the headline. Actually, the
> "artificial restriction" you are talking about is a way to allow every
> headline to be numbered in a unique way, even if that number doesn't
> appear in the output.

I can see what you mean here -- but it doesn't exactly "break"
anything -- it just makes the section-numbering within html, etc.
documents to be non-consecutive *if these properties are used*.  If
the main intent is to use these properties in conjunction with the
LaTeX exporter, then this isn't a big problem (i.e. those who want to
use them will just need to understand that they currently only work
"correctly" with LaTeX, but that this will be fixed in the future).

> Since I wouldn't use this, I can hardly judge, but I would appreciate
> some feedback from other users before we go too far in the
> implementation.

Agreed, but my (obviously biased) opinion is that it makes manual
numbering-control more "natural" within org-mode, and something which
doesn't require as much hacking with embedded LaTeX (or HTML, etc.)
code.

Regards,

Mark

Re: [PATCH] Export: Override headline numbering via properties

[Albert Z. Wang]

Mark Edgington <edgimar@gmail.com> writes:

>> Anyway, your patch will not work on back-ends that rely on Org to
>> compute section numbers (e.g., ascii, html...) because even if you
>> ignore numbering for a particular headline, it still adds up
>> internally.  IOW, you also need to patch
>> `org-export--collect-headline-numbering'.
>>
>> But that's not quite it, yet. Some back-ends (e.g., html) use that
>> internal number as a unique identifier for the headline. Actually,
>> the "artificial restriction" you are talking about is a way to
>> allow every headline to be numbered in a unique way, even if that
>> number doesn't appear in the output.
>
> I can see what you mean here -- but it doesn't exactly "break"
> anything -- it just makes the section-numbering within html, etc.
> documents to be non-consecutive *if these properties are used*.  If
> the main intent is to use these properties in conjunction with the
> LaTeX exporter, then this isn't a big problem (i.e. those who want
> to use them will just need to understand that they currently only
> work "correctly" with LaTeX, but that this will be fixed in the
> future).
>
>> Since I wouldn't use this, I can hardly judge, but I would
>> appreciate some feedback from other users before we go too far in
>> the implementation.
>
> Agreed, but my (obviously biased) opinion is that it makes manual
> numbering-control more "natural" within org-mode, and something
> which doesn't require as much hacking with embedded LaTeX (or HTML,
> etc.)  code.

An alternative would be to stick this into ox-latex.el, which then
wouldn't interfere with other backends.

I also think this functionality is good to have, since longer latex
documents often have unnumbered sections (and there seem to be
periodic questions on various boards on how to achieve this).  While
one can mess around with the latex code, it's often a hassle when the
"master" document is in org and you need to recompile often.

For a recent project I needed a super-simple way to turn off numbering
(for intro and references), so based on the above I made the following
tiny modification to ox-latex.el, which looks up the "LATEX_NUMBERED"
property to decide whether to insert a numbered or unnumbered heading.
Since I didn't need it, inheritance isn't in here, but it should be
simple enough to add.

Since this wouldn't interfere with any other backends, perhaps there
will be fewer reservations about merging something like this into the
repo?

--
diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index 41cf1d0..33a39c7 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -1369,7 +1369,11 @@ holding contextual information."
   (unless (org-element-property :footnote-section-p headline)
     (let* ((class (plist-get info :latex-class))
           (level (org-export-get-relative-level headline info))
-          (numberedp (org-export-numbered-headline-p headline info))
+          (latex-numbered (org-export-get-node-property :LATEX_NUMBERED headline))
+          (numberedp
+           (cond ((equal latex-numbered "n") nil)
+                 ((equal latex-numbered "y") t)
+                 (t (org-export-numbered-headline-p headline info))))
           (class-sectionning (assoc class org-latex-classes))
           ;; Section formatting will set two placeholders: one for
           ;; the title and the other for the contents.
--

Re: [PATCH] Export: Override headline numbering via properties

[Nicolas Goaziou]

Hello,

Thanks for your patch.

> An alternative would be to stick this into ox-latex.el, which then
> wouldn't interfere with other backends.
>
> I also think this functionality is good to have, since longer latex
> documents often have unnumbered sections (and there seem to be
> periodic questions on various boards on how to achieve this).  While
> one can mess around with the latex code, it's often a hassle when the
> "master" document is in org and you need to recompile often.
>
> For a recent project I needed a super-simple way to turn off numbering
> (for intro and references), so based on the above I made the following
> tiny modification to ox-latex.el, which looks up the "LATEX_NUMBERED"
> property to decide whether to insert a numbered or unnumbered heading.
> Since I didn't need it, inheritance isn't in here, but it should be
> simple enough to add.
>
> Since this wouldn't interfere with any other backends, perhaps there
> will be fewer reservations about merging something like this into the
> repo?

If it has to be implemented, I think that's the most reasonable solution
for now. For other back-ends, manual numbering specifications are just
too vague to lead to useful code.

> --
> diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
> index 41cf1d0..33a39c7 100644
> --- a/lisp/ox-latex.el
> +++ b/lisp/ox-latex.el
> @@ -1369,7 +1369,11 @@ holding contextual information."
>    (unless (org-element-property :footnote-section-p headline)
>      (let* ((class (plist-get info :latex-class))
>            (level (org-export-get-relative-level headline info))
> -          (numberedp (org-export-numbered-headline-p headline info))
> +          (latex-numbered (org-export-get-node-property :LATEX_NUMBERED headline))
> +          (numberedp
> +           (cond ((equal latex-numbered "n") nil)
> +                 ((equal latex-numbered "y") t)
> +                 (t (org-export-numbered-headline-p headline info))))

I'd rather have "nil", anything but "nil" and property not set.

It also needs proper documentation in org.texi.


Regards,

-- 
Nicolas Goaziou

Re: [PATCH] Export: Override headline numbering via properties

[Mark Edgington]

Also, I forgot to mention that the patch is tested, and behaves as expected.

On Mon, May 13, 2013 at 2:18 AM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> Thanks for your patch.
>
> Though, I don't get what you are trying to achieve nor what a use case
> would be. Have you tested this patch ? It may not behave as you expect
> it to.

Re: [PATCH] Export: Override headline numbering via properties

[Mark Edgington]

Hi Samuel,

I'd guess it isn't exactly the same as what you did -- I assume you
are making it possible to modify the numbering level threshold via
properties.  Is this modification inherited by child-headlines or not?
 Either way, there would be a lot of "hackery" required to use this to
achieve the kinds of things my patch intends to do  (e.g. you might
have to use different num:x properties in multiple places to cause
just a single-headline's numbering to be changed).

Regards,

Mark


On Mon, May 13, 2013 at 12:39 AM, Samuel Wales <samologist@gmail.com> wrote:
> I just did this, is this related?
>
> :PROPERTIES:
> :EXPORT_OPTIONS: num:1
> :END:
>
> --
> The Kafka Pandemic: http://thekafkapandemic.blogspot.com
>
> The disease DOES progress.  MANY people have died from it.  ANYBODY can get it.