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

2013-05-23 Thread 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: [O] [PATCH] Export: Override headline numbering via properties

2013-05-16 Thread Albert Z. Wang
Mark Edgington edgi...@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: [O] [PATCH] Export: Override headline numbering via properties

2013-05-13 Thread Nicolas Goaziou
Hello,

Mark Edgington edgi...@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: [O] [PATCH] Export: Override headline numbering via properties

2013-05-13 Thread 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: [O] [PATCH] Export: Override headline numbering via properties

2013-05-13 Thread 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 samolog...@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.



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

2013-05-13 Thread 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.goaz...@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: [O] [PATCH] Export: Override headline numbering via properties

2013-05-13 Thread Nicolas Goaziou
Hello,

Mark Edgington edgi...@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: [O] [PATCH] Export: Override headline numbering via properties

2013-05-13 Thread Mark Edgington
Hi Nicolas,

On Mon, May 13, 2013 at 6:54 AM, Nicolas Goaziou n.goaz...@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



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

2013-05-12 Thread 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