* [PATCH] Export: Override headline numbering via properties
@ 2013-05-13 3:07 Mark Edgington
2013-05-13 6:18 ` Nicolas Goaziou
[not found] ` <CAJcAo8u+pAqwuPtRDpDaLc7QE_1BvR7MXchgZRQDLRAv_iQ2Wg@mail.gmail.com>
0 siblings, 2 replies; 9+ messages in thread
From: Mark Edgington @ 2013-05-13 3:07 UTC (permalink / raw)
To: emacs-orgmode
* 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
^ permalink raw reply related [flat|nested] 9+ messages in thread* Re: [PATCH] Export: Override headline numbering via properties 2013-05-13 3:07 [PATCH] Export: Override headline numbering via properties Mark Edgington @ 2013-05-13 6:18 ` Nicolas Goaziou 2013-05-13 9:42 ` Mark Edgington 2013-05-13 10:11 ` Mark Edgington [not found] ` <CAJcAo8u+pAqwuPtRDpDaLc7QE_1BvR7MXchgZRQDLRAv_iQ2Wg@mail.gmail.com> 1 sibling, 2 replies; 9+ messages in thread From: Nicolas Goaziou @ 2013-05-13 6:18 UTC (permalink / raw) To: Mark Edgington; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Export: Override headline numbering via properties 2013-05-13 6:18 ` Nicolas Goaziou @ 2013-05-13 9:42 ` Mark Edgington 2013-05-13 10:54 ` Nicolas Goaziou 2013-05-13 10:11 ` Mark Edgington 1 sibling, 1 reply; 9+ messages in thread From: Mark Edgington @ 2013-05-13 9:42 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Export: Override headline numbering via properties 2013-05-13 9:42 ` Mark Edgington @ 2013-05-13 10:54 ` Nicolas Goaziou 2013-05-14 4:39 ` Mark Edgington 0 siblings, 1 reply; 9+ messages in thread From: Nicolas Goaziou @ 2013-05-13 10:54 UTC (permalink / raw) To: Mark Edgington; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Export: Override headline numbering via properties 2013-05-13 10:54 ` Nicolas Goaziou @ 2013-05-14 4:39 ` Mark Edgington 2013-05-17 3:19 ` Albert Z. Wang 0 siblings, 1 reply; 9+ messages in thread From: Mark Edgington @ 2013-05-14 4:39 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Export: Override headline numbering via properties 2013-05-14 4:39 ` Mark Edgington @ 2013-05-17 3:19 ` Albert Z. Wang 2013-05-23 19:03 ` Nicolas Goaziou 0 siblings, 1 reply; 9+ messages in thread From: Albert Z. Wang @ 2013-05-17 3:19 UTC (permalink / raw) To: emacs-orgmode 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. -- ^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH] Export: Override headline numbering via properties 2013-05-17 3:19 ` Albert Z. Wang @ 2013-05-23 19:03 ` Nicolas Goaziou 0 siblings, 0 replies; 9+ messages in thread From: Nicolas Goaziou @ 2013-05-23 19:03 UTC (permalink / raw) To: Albert Z. Wang; +Cc: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Export: Override headline numbering via properties 2013-05-13 6:18 ` Nicolas Goaziou 2013-05-13 9:42 ` Mark Edgington @ 2013-05-13 10:11 ` Mark Edgington 1 sibling, 0 replies; 9+ messages in thread From: Mark Edgington @ 2013-05-13 10:11 UTC (permalink / raw) To: Nicolas Goaziou; +Cc: emacs-orgmode 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. ^ permalink raw reply [flat|nested] 9+ messages in thread
[parent not found: <CAJcAo8u+pAqwuPtRDpDaLc7QE_1BvR7MXchgZRQDLRAv_iQ2Wg@mail.gmail.com>]
* Re: [PATCH] Export: Override headline numbering via properties [not found] ` <CAJcAo8u+pAqwuPtRDpDaLc7QE_1BvR7MXchgZRQDLRAv_iQ2Wg@mail.gmail.com> @ 2013-05-13 10:08 ` Mark Edgington 0 siblings, 0 replies; 9+ messages in thread From: Mark Edgington @ 2013-05-13 10:08 UTC (permalink / raw) To: Samuel Wales; +Cc: emacs-orgmode 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. ^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2013-05-23 19:03 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-05-13 3:07 [PATCH] Export: Override headline numbering via properties Mark Edgington
2013-05-13 6:18 ` Nicolas Goaziou
2013-05-13 9:42 ` Mark Edgington
2013-05-13 10:54 ` Nicolas Goaziou
2013-05-14 4:39 ` Mark Edgington
2013-05-17 3:19 ` Albert Z. Wang
2013-05-23 19:03 ` Nicolas Goaziou
2013-05-13 10:11 ` Mark Edgington
[not found] ` <CAJcAo8u+pAqwuPtRDpDaLc7QE_1BvR7MXchgZRQDLRAv_iQ2Wg@mail.gmail.com>
2013-05-13 10:08 ` Mark Edgington
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs/org-mode.git 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).