unnumbered subsections in latex export

unnumbered subsections in latex export

[Suvayu Ali]

[-- Attachment #1: Type: text/plain, Size: 437 bytes --]

Hi Orgers,

I was wondering whether there is some way to export the attached org
file to latex such that headlines beyond level 2 (3 and onwards) can
be exported as unnumbered subsections or subsubsections like this,
\subsection*{}, instead of enclosing them within itemize.

The file uses the following options header:

#+OPTIONS:   H:2 num:t toc:t ::t |:t ^:t -:t f:t *:t <:nil

-- 
Suvayu

Open source is the future. It sets us free.

[-- Attachment #2: test.org --]
[-- Type: text/plain, Size: 464 bytes --]

#+TITLE:     A path breaking discovery
#+AUTHOR:    Suvayu Ali
#+DATE:      <2011-03-22 Tue>
#+OPTIONS:   H:2 num:t toc:t ::t |:t ^:t -:t f:t *:t <:nil
#+OPTIONS:   TeX:t LaTeX:t skip:nil d:nil todo:nil pri:nil tags:nil


* Chapter One

** Background

*** The Standard Model

    Its a thing of beauty!

*** Symmetry gauge group

    The SM symmetry gauge group is $SU(3) \times SU(2) \times U(1)$.

** Some section

   With some discoveries

Re: unnumbered subsections in latex export

[Sébastien Vauban]

Hi Suvayu,

Suvayu Ali wrote:
> Hi Orgers,
>
> I was wondering whether there is some way to export the attached org
> file to latex such that headlines beyond level 2 (3 and onwards) can
> be exported as unnumbered subsections or subsubsections like this,
> \subsection*{}, instead of enclosing them within itemize.
>
> The file uses the following options header:
>
> #+OPTIONS:   H:2 num:t toc:t ::t |:t ^:t -:t f:t *:t <:nil

Using H:3 num:2?  Untested... But that should do the work.

Best regards,
  Seb

-- 
Sébastien Vauban

Re: Re: unnumbered subsections in latex export

[Suvayu Ali]

Hi Sébastien,

On Tue, 22 Mar 2011 13:20:29 +0100
Sébastien Vauban <wxhgmqzgwmuf@spammotel.com> wrote:
> >
> > I was wondering whether there is some way to export the attached org
> > file to latex such that headlines beyond level 2 (3 and onwards) can
> > be exported as unnumbered subsections or subsubsections like this,
> > \subsection*{}, instead of enclosing them within itemize.
> >
> > The file uses the following options header:
> >
> > #+OPTIONS:   H:2 num:t toc:t ::t |:t ^:t -:t f:t *:t <:nil
> 
> Using H:3 num:2?  Untested... But that should do the work.
> 

That didn't work. It exports the same as the following options

#+OPTIONS:   H:3 num:t toc:t ::t |:t ^:t -:t f:t *:t <:nil

I think the num option is a boolean. The manual says the following:

     num:       turn on/off section-numbers

Would it be a worthwhile feature request to allow numbers for that
option? Then one could have finer control on the numbering.

> Best regards,
>   Seb
> 

Thanks,

-- 
Suvayu

Open source is the future. It sets us free.

Re: unnumbered subsections in latex export

[Sébastien Vauban]

Hi Suvayu,

Suvayu Ali wrote:
> On Tue, 22 Mar 2011 13:20:29 +0100
> Sébastien Vauban <wxhgmqzgwmuf-geNee64TY+gS+FvcfC7Uqw@public.gmane.org> wrote:
>> >
>> > I was wondering whether there is some way to export the attached org file
>> > to latex such that headlines beyond level 2 (3 and onwards) can be
>> > exported as unnumbered subsections or subsubsections like this,
>> > \subsection*{}, instead of enclosing them within itemize.
>> >
>> > The file uses the following options header:
>> >
>> > #+OPTIONS:   H:2 num:t toc:t ::t |:t ^:t -:t f:t *:t <:nil
>> 
>> Using H:3 num:2? Untested... But that should do the work.
>
> That didn't work. It exports the same as the following options
>
> #+OPTIONS:   H:3 num:t toc:t ::t |:t ^:t -:t f:t *:t <:nil
>
> I think the num option is a boolean. The manual says the following:
>
>      num:       turn on/off section-numbers

You're right. I mixed that usage with what's possible for `toc':

--8<---------------cut here---------------start------------->8---
 H:         set the number of headline levels for export
 num:       turn on/off section-numbers
 toc:       turn on/off table of contents, or set level limit (integer)
--8<---------------cut here---------------end--------------->8---

> Would it be a worthwhile feature request to allow numbers for that
> option? Then one could have finer control on the numbering.

I think that'd be a good addition.

Best regards,
  Seb

-- 
Sébastien Vauban

[PATCH] Allow mixed export of numbered and unnumbered sections in LaTeX

[Lawrence Mitchell]

* lisp/org-latex.el (org-export-latex-subcontent): Deal specially with
the case that NUM is an integer.

We would sometimes like to have numbered \sections in LaTeX export but
unnumbered \subsections and so forth.  That is, use the starred
equivalents for all sectioning commands below a certain level.
Previously, the num: option specification could only specify whether
sections should be numbered or unnumbered at all levels.  We now treat
an integer value specially, if num:N is supplied then the highest N
levels are numbered, and lower levels are exported without numbering.
---
 lisp/org-latex.el |    7 ++++++-
 1 files changed, 6 insertions(+), 1 deletions(-)

[...]
Wouldn't it be nice if #+OPTIONS: num:2 exported
\section{foo}
\subsection{bar}
\subsubsection*{baz}

It turns out the patch is relatively straightforward.  I haven't
included a doc update, but could do so if required.


diff --git a/lisp/org-latex.el b/lisp/org-latex.el
index fbdeb5e..7a3c629 100644
--- a/lisp/org-latex.el
+++ b/lisp/org-latex.el
@@ -1151,7 +1151,9 @@ and its content."
 
 (defun org-export-latex-subcontent (subcontent num)
   "Export each cell of SUBCONTENT to LaTeX.
-If NUM, export sections as numerical sections."
+If NUM is non-nil export numbered sections, otherwise use unnumbered
+sections.  If NUM is an integer, export the highest NUM levels as
+numbered sections and lower levels as unnumbered sections."
   (let* ((heading (cdr (assoc 'heading subcontent)))
 	 (level (- (cdr (assoc 'level subcontent))
 		   org-export-latex-add-level))
@@ -1187,6 +1189,9 @@ If NUM, export sections as numerical sections."
      ;; Normal conversion
      ((<= level depth)
       (let* ((sec (nth (1- level) sectioning))
+	     (num (if (integerp num)
+		      (>= num level)
+		    num))
 	     start end)
 	(if (consp (cdr sec))
 	    (setq start (nth (if num 0 2) sec)
-- 
1.7.4.rc2.18.gb20e9

Re: Re: unnumbered subsections in latex export

[Nick Dokos]

Suvayu Ali <fatkasuvayu+linux@gmail.com> wrote:

> Hi S=C3=A9bastien,
> 
> On Tue, 22 Mar 2011 13:20:29 +0100
> S=C3=A9bastien Vauban <wxhgmqzgwmuf@spammotel.com> wrote:
> > >
> > > I was wondering whether there is some way to export the attached org
> > > file to latex such that headlines beyond level 2 (3 and onwards) can
> > > be exported as unnumbered subsections or subsubsections like this,
> > > \subsection*{}, instead of enclosing them within itemize.
> > >
> > > The file uses the following options header:
> > >
> > > #+OPTIONS:   H:2 num:t toc:t ::t |:t ^:t -:t f:t *:t <:nil
> >=20
> > Using H:3 num:2?  Untested... But that should do the work.
> >=20
> 
> That didn't work. It exports the same as the following options
> 
> #+OPTIONS:   H:3 num:t toc:t ::t |:t ^:t -:t f:t *:t <:nil
> 
> I think the num option is a boolean. The manual says the following:
> 
>      num:       turn on/off section-numbers
> 
> Would it be a worthwhile feature request to allow numbers for that
> option? Then one could have finer control on the numbering.
> 


You can do it (I think - but have not tried it) by changing H:3 to
H:5 or so:

,----
| (defcustom org-export-latex-low-levels 'itemize
|   "How to convert sections below the current level of sectioning.
| This is specified by the `org-export-headline-levels' option or the
| value of \"H:\" in Org's #+OPTION line.
`----

and then asking LaTeX to omit the numbering appropriately:

\setcounter{secnumdepth}{2}

Adjust the 2 to taste.

Nick

Re: [PATCH] Allow mixed export of numbered and unnumbered sections in LaTeX

[Suvayu Ali]

On Tue, 22 Mar 2011 14:26:14 +0000
Lawrence Mitchell <wence@gmx.li> wrote:

> * lisp/org-latex.el (org-export-latex-subcontent): Deal specially with
> the case that NUM is an integer.
> 
> We would sometimes like to have numbered \sections in LaTeX export but
> unnumbered \subsections and so forth.  That is, use the starred
> equivalents for all sectioning commands below a certain level.
> Previously, the num: option specification could only specify whether
> sections should be numbered or unnumbered at all levels.  We now treat
> an integer value specially, if num:N is supplied then the highest N
> levels are numbered, and lower levels are exported without numbering.
> ---
>  lisp/org-latex.el |    7 ++++++-
>  1 files changed, 6 insertions(+), 1 deletions(-)
> 
> [...]
> Wouldn't it be nice if #+OPTIONS: num:2 exported
> \section{foo}
> \subsection{bar}
> \subsubsection*{baz}
> 
> It turns out the patch is relatively straightforward.  I haven't
> included a doc update, but could do so if required.
> 

This works perfectly. Thanks a lot Lawrence. :) 

-- 
Suvayu

Open source is the future. It sets us free.

Re: Re: unnumbered subsections in latex export

[Suvayu Ali]

On Tue, 22 Mar 2011 10:35:10 -0400
Nick Dokos <nicholas.dokos@hp.com> wrote:

> Suvayu Ali <fatkasuvayu+linux@gmail.com> wrote:
> 
> > Hi S=C3=A9bastien,
> > 
> > On Tue, 22 Mar 2011 13:20:29 +0100
> > S=C3=A9bastien Vauban <wxhgmqzgwmuf@spammotel.com> wrote:
> > > >
> > > > I was wondering whether there is some way to export the
> > > > attached org file to latex such that headlines beyond level 2
> > > > (3 and onwards) can be exported as unnumbered subsections or
> > > > subsubsections like this, \subsection*{}, instead of enclosing
> > > > them within itemize.
> > > >
> > > > The file uses the following options header:
> > > >
> > > > #+OPTIONS:   H:2 num:t toc:t ::t |:t ^:t -:t f:t *:t <:nil
> > >=20
> > > Using H:3 num:2?  Untested... But that should do the work.
> > >=20
> > 
> > That didn't work. It exports the same as the following options
> > 
> > #+OPTIONS:   H:3 num:t toc:t ::t |:t ^:t -:t f:t *:t <:nil
> > 
> > I think the num option is a boolean. The manual says the following:
> > 
> >      num:       turn on/off section-numbers
> > 
> > Would it be a worthwhile feature request to allow numbers for that
> > option? Then one could have finer control on the numbering.
> > 
> 
> 
> You can do it (I think - but have not tried it) by changing H:3 to
> H:5 or so:
> 
> ,----
> | (defcustom org-export-latex-low-levels 'itemize
> |   "How to convert sections below the current level of sectioning.
> | This is specified by the `org-export-headline-levels' option or the
> | value of \"H:\" in Org's #+OPTION line.
> `----
> 
> and then asking LaTeX to omit the numbering appropriately:
> 
> \setcounter{secnumdepth}{2}
> 
> Adjust the 2 to taste.
> 

This works too, but Lawrence's patch makes it much easier and
probably works for other export formats too. Thanks a lot. :)

> Nick

-- 
Suvayu

Open source is the future. It sets us free.

Re: Re: unnumbered subsections in latex export

[Nick Dokos]

Suvayu Ali <fatkasuvayu+linux@gmail.com> wrote:

> This works too, but Lawrence's patch makes it much easier and
> probably works for other export formats too. Thanks a lot. :)
> 

No doubt Lawrence's patch can be extended to work for other exports, but
it's not there yet: each exporter would need a change similar to the one
that he made to the LaTeX exporter.

Nick

[PATCH] Allow mixed export of numbered and unnumbered sections in HTML

[Lawrence Mitchell]

* lisp/org-html.el (org-export-as-html): Get local value of
org-export-with-section-numbers from the buffer's plist.  Deal
specially with the case the resulting value is an integer.
(org-html-level-start): New optional argument of the option plist used
instead of `org-export-with-section-numbers'.  Also deal specially
with the case that the value is an integer.

When `org-export-with-section-numbers' (or the buffer-local
:section-numbers option) is an integer, we now export the first NUM
levels of headings with numbers and lower-level headings without.
---
 lisp/org-html.el |   24 ++++++++++++++++++------
 1 files changed, 18 insertions(+), 6 deletions(-)

Nick Dokos wrote:
> Suvayu Ali <fatkasuvayu+linux@gmail.com> wrote:

>> This works too, but Lawrence's patch makes it much easier and
>> probably works for other export formats too. Thanks a lot. :)

As Nick points out, each exporter backend needs a similar change.

> No doubt Lawrence's patch can be extended to work for other exports, but
> it's not there yet: each exporter would need a change similar to the one
> that he made to the LaTeX exporter.

Here's the matching change to the HTML exporter, which is the
only other one I'm familiar with.  Maintainers, if you don't want
the special-casing on integerp, the change to move from
`org-export-with-section-numbers' to (plist-get opt-plist
:section-numbers) is the correct one anyway.  I can split the
patches if required.

diff --git a/lisp/org-html.el b/lisp/org-html.el
index b13fb93..06305f6 100644
--- a/lisp/org-html.el
+++ b/lisp/org-html.el
@@ -1150,6 +1150,7 @@ PUB-DIR is set, use this as the publishing directory."
 	 (language    (plist-get opt-plist :language))
 	 (keywords    (plist-get opt-plist :keywords))
 	 (description (plist-get opt-plist :description))
+	 (num         (plist-get opt-plist :section-numbers))
 	 (lang-words  nil)
 	 (head-count  0) cnt
 	 (start       0)
@@ -1355,7 +1356,7 @@ lang=\"%s\" xml:lang=\"%s\">
 				   (if (string-match quote-re0 txt)
 				       (setq txt (replace-match "" t t txt)))
 				   (setq snumber (org-section-number level))
-				   (if org-export-with-section-numbers
+				   (if (and num (integerp num) (>= num level))
 				       (setq txt (concat snumber " " txt)))
 				   (if (<= level (max umax umax-toc))
 				       (setq head-count (+ head-count 1)))
@@ -1591,7 +1592,7 @@ lang=\"%s\" xml:lang=\"%s\">
 	    (setq first-heading-pos (or first-heading-pos (point)))
 	    (org-html-level-start level txt umax
 				  (and org-export-with-toc (<= level umax))
-				  head-count)
+				  head-count opt-plist)
 
 	    ;; QUOTES
 	    (when (string-match quote-re line)
@@ -1684,7 +1685,7 @@ lang=\"%s\" xml:lang=\"%s\">
 
       (org-html-level-start 1 nil umax
 			    (and org-export-with-toc (<= level umax))
-			    head-count)
+			    head-count opt-plist)
       ;; the </div> to close the last text-... div.
       (when (and (> umax 0) first-heading-pos) (insert "</div>\n"))
 
@@ -2330,7 +2331,7 @@ If there are links in the string, don't modify these."
   (insert (if (equal type "d") "</dd>\n" "</li>\n")))
 
 (defvar body-only) ; dynamically scoped into this.
-(defun org-html-level-start (level title umax with-toc head-count)
+(defun org-html-level-start (level title umax with-toc head-count &optional opt-plist)
   "Insert a new level in HTML export.
 When TITLE is nil, just close all open levels."
   (org-close-par-maybe)
@@ -2341,6 +2342,7 @@ When TITLE is nil, just close all open levels."
 	 (preferred (and target
 			 (cdr (assoc target org-export-preferred-target-alist))))
 	 (l org-level-max)
+	 (num (plist-get opt-plist :section-numbers))
 	 snumber snu href suffix)
     (setq extra-targets (remove (or preferred target) extra-targets))
     (setq extra-targets
@@ -2395,10 +2397,20 @@ When TITLE is nil, just close all open levels."
 	(setq snumber (org-section-number level)
 	      snu (replace-regexp-in-string "\\." "_" snumber))
 	(setq level (+ level org-export-html-toplevel-hlevel -1))
-	(if (and org-export-with-section-numbers (not body-only))
+	(if (and num (not body-only))
 	    (setq title (concat
 			 (format "<span class=\"section-number-%d\">%s</span>"
-				 level snumber)
+				 level
+				 (if (and (integerp num)
+					  ;; fix up num to take into
+					  ;; account the top-level
+					  ;; heading value
+					  (>= (+ num
+						 org-export-html-toplevel-hlevel
+						 -1)
+					      level))
+					   snumber
+					 ""))
 			 " " title)))
 	(unless (= head-count 1) (insert "\n</div>\n"))
 	(setq href (cdr (assoc (concat "sec-" snu) org-export-preferred-target-alist)))
-- 
1.7.4.rc2.18.gb20e9

[Accepted] Allow mixed export of numbered and unnumbered sections in LaTeX

[Bastien Guerry]

Patch 710 (http://patchwork.newartisans.com/patch/710/) is now "Accepted".

Maintainer comment: none

This relates to the following submission:

http://mid.gmane.org/%3Cm3aagn2pi7.fsf_-_%40e4300lm.epcc.ed.ac.uk%3E

Here is the original message containing the patch:

> Content-Type: text/plain; charset="utf-8"
> MIME-Version: 1.0
> Content-Transfer-Encoding: 7bit
> Subject: [O] Allow mixed export of numbered and unnumbered sections in LaTeX
> Date: Tue, 22 Mar 2011 19:26:14 -0000
> From: Lawrence Mitchell <wence@gmx.li>
> X-Patchwork-Id: 710
> Message-Id: <m3aagn2pi7.fsf_-_@e4300lm.epcc.ed.ac.uk>
> To: emacs-orgmode@gnu.org
> 
> * lisp/org-latex.el (org-export-latex-subcontent): Deal specially with
> the case that NUM is an integer.
> 
> We would sometimes like to have numbered \sections in LaTeX export but
> unnumbered \subsections and so forth.  That is, use the starred
> equivalents for all sectioning commands below a certain level.
> Previously, the num: option specification could only specify whether
> sections should be numbered or unnumbered at all levels.  We now treat
> an integer value specially, if num:N is supplied then the highest N
> levels are numbered, and lower levels are exported without numbering.
> 
> ---
> lisp/org-latex.el |    7 ++++++-
>  1 files changed, 6 insertions(+), 1 deletions(-)
> 
> [...]
> Wouldn't it be nice if #+OPTIONS: num:2 exported
> \section{foo}
> \subsection{bar}
> \subsubsection*{baz}
> 
> It turns out the patch is relatively straightforward.  I haven't
> included a doc update, but could do so if required.
> 
> diff --git a/lisp/org-latex.el b/lisp/org-latex.el
> index fbdeb5e..7a3c629 100644
> --- a/lisp/org-latex.el
> +++ b/lisp/org-latex.el
> @@ -1151,7 +1151,9 @@ and its content."
>  
>  (defun org-export-latex-subcontent (subcontent num)
>    "Export each cell of SUBCONTENT to LaTeX.
> -If NUM, export sections as numerical sections."
> +If NUM is non-nil export numbered sections, otherwise use unnumbered
> +sections.  If NUM is an integer, export the highest NUM levels as
> +numbered sections and lower levels as unnumbered sections."
>    (let* ((heading (cdr (assoc 'heading subcontent)))
>  	 (level (- (cdr (assoc 'level subcontent))
>  		   org-export-latex-add-level))
> @@ -1187,6 +1189,9 @@ If NUM, export sections as numerical sections."
>       ;; Normal conversion
>       ((<= level depth)
>        (let* ((sec (nth (1- level) sectioning))
> +	     (num (if (integerp num)
> +		      (>= num level)
> +		    num))
>  	     start end)
>  	(if (consp (cdr sec))
>  	    (setq start (nth (if num 0 2) sec)
> 

[Accepted] Allow mixed export of numbered and unnumbered sections in HTML

[Bastien Guerry]

Patch 711 (http://patchwork.newartisans.com/patch/711/) is now "Accepted".

Maintainer comment: none

This relates to the following submission:

http://mid.gmane.org/%3Cm34o6u2mwf.fsf_-_%40e4300lm.epcc.ed.ac.uk%3E

Here is the original message containing the patch:

> Content-Type: text/plain; charset="utf-8"
> MIME-Version: 1.0
> Content-Transfer-Encoding: 7bit
> Subject: [O] Allow mixed export of numbered and unnumbered sections in HTML
> Date: Wed, 23 Mar 2011 14:38:18 -0000
> From: Lawrence Mitchell <wence@gmx.li>
> X-Patchwork-Id: 711
> Message-Id: <m34o6u2mwf.fsf_-_@e4300lm.epcc.ed.ac.uk>
> To: emacs-orgmode@gnu.org
> 
> * lisp/org-html.el (org-export-as-html): Get local value of
> org-export-with-section-numbers from the buffer's plist.  Deal
> specially with the case the resulting value is an integer.
> (org-html-level-start): New optional argument of the option plist used
> instead of `org-export-with-section-numbers'.  Also deal specially
> with the case that the value is an integer.
> 
> When `org-export-with-section-numbers' (or the buffer-local
> :section-numbers option) is an integer, we now export the first NUM
> levels of headings with numbers and lower-level headings without.
> 
> ---
> lisp/org-html.el |   24 ++++++++++++++++++------
>  1 files changed, 18 insertions(+), 6 deletions(-)
> 
> Nick Dokos wrote:
> > Suvayu Ali <fatkasuvayu+linux@gmail.com> wrote:
> 
> >> This works too, but Lawrence's patch makes it much easier and
> >> probably works for other export formats too. Thanks a lot. :)
> 
> As Nick points out, each exporter backend needs a similar change.
> 
> > No doubt Lawrence's patch can be extended to work for other exports, but
> > it's not there yet: each exporter would need a change similar to the one
> > that he made to the LaTeX exporter.
> 
> Here's the matching change to the HTML exporter, which is the
> only other one I'm familiar with.  Maintainers, if you don't want
> the special-casing on integerp, the change to move from
> `org-export-with-section-numbers' to (plist-get opt-plist
> :section-numbers) is the correct one anyway.  I can split the
> patches if required.
> 
> diff --git a/lisp/org-html.el b/lisp/org-html.el
> index b13fb93..06305f6 100644
> --- a/lisp/org-html.el
> +++ b/lisp/org-html.el
> @@ -1150,6 +1150,7 @@ PUB-DIR is set, use this as the publishing directory."
>  	 (language    (plist-get opt-plist :language))
>  	 (keywords    (plist-get opt-plist :keywords))
>  	 (description (plist-get opt-plist :description))
> +	 (num         (plist-get opt-plist :section-numbers))
>  	 (lang-words  nil)
>  	 (head-count  0) cnt
>  	 (start       0)
> @@ -1355,7 +1356,7 @@ lang=\"%s\" xml:lang=\"%s\">
>  				   (if (string-match quote-re0 txt)
>  				       (setq txt (replace-match "" t t txt)))
>  				   (setq snumber (org-section-number level))
> -				   (if org-export-with-section-numbers
> +				   (if (and num (integerp num) (>= num level))
>  				       (setq txt (concat snumber " " txt)))
>  				   (if (<= level (max umax umax-toc))
>  				       (setq head-count (+ head-count 1)))
> @@ -1591,7 +1592,7 @@ lang=\"%s\" xml:lang=\"%s\">
>  	    (setq first-heading-pos (or first-heading-pos (point)))
>  	    (org-html-level-start level txt umax
>  				  (and org-export-with-toc (<= level umax))
> -				  head-count)
> +				  head-count opt-plist)
>  
>  	    ;; QUOTES
>  	    (when (string-match quote-re line)
> @@ -1684,7 +1685,7 @@ lang=\"%s\" xml:lang=\"%s\">
>  
>        (org-html-level-start 1 nil umax
>  			    (and org-export-with-toc (<= level umax))
> -			    head-count)
> +			    head-count opt-plist)
>        ;; the </div> to close the last text-... div.
>        (when (and (> umax 0) first-heading-pos) (insert "</div>\n"))
>  
> @@ -2330,7 +2331,7 @@ If there are links in the string, don't modify these."
>    (insert (if (equal type "d") "</dd>\n" "</li>\n")))
>  
>  (defvar body-only) ; dynamically scoped into this.
> -(defun org-html-level-start (level title umax with-toc head-count)
> +(defun org-html-level-start (level title umax with-toc head-count &optional opt-plist)
>    "Insert a new level in HTML export.
>  When TITLE is nil, just close all open levels."
>    (org-close-par-maybe)
> @@ -2341,6 +2342,7 @@ When TITLE is nil, just close all open levels."
>  	 (preferred (and target
>  			 (cdr (assoc target org-export-preferred-target-alist))))
>  	 (l org-level-max)
> +	 (num (plist-get opt-plist :section-numbers))
>  	 snumber snu href suffix)
>      (setq extra-targets (remove (or preferred target) extra-targets))
>      (setq extra-targets
> @@ -2395,10 +2397,20 @@ When TITLE is nil, just close all open levels."
>  	(setq snumber (org-section-number level)
>  	      snu (replace-regexp-in-string "\\." "_" snumber))
>  	(setq level (+ level org-export-html-toplevel-hlevel -1))
> -	(if (and org-export-with-section-numbers (not body-only))
> +	(if (and num (not body-only))
>  	    (setq title (concat
>  			 (format "<span class=\"section-number-%d\">%s</span>"
> -				 level snumber)
> +				 level
> +				 (if (and (integerp num)
> +					  ;; fix up num to take into
> +					  ;; account the top-level
> +					  ;; heading value
> +					  (>= (+ num
> +						 org-export-html-toplevel-hlevel
> +						 -1)
> +					      level))
> +					   snumber
> +					 ""))
>  			 " " title)))
>  	(unless (= head-count 1) (insert "\n</div>\n"))
>  	(setq href (cdr (assoc (concat "sec-" snu) org-export-preferred-target-alist)))
> 

Re: [PATCH] Allow mixed export of numbered and unnumbered sections in LaTeX

[Bastien]

Lawrence Mitchell <wence@gmx.li> writes:

> * lisp/org-latex.el (org-export-latex-subcontent): Deal specially with
> the case that NUM is an integer.

... and thanks for this one too!  Applied.

-- 
 Bastien

Re: Re: unnumbered subsections in latex export

[Bastien]

Hi Nick,

Nick Dokos <nicholas.dokos@hp.com> writes:

> Suvayu Ali <fatkasuvayu+linux@gmail.com> wrote:
>
>> This works too, but Lawrence's patch makes it much easier and
>> probably works for other export formats too. Thanks a lot. :)
>
> No doubt Lawrence's patch can be extended to work for other exports, but
> it's not there yet: each exporter would need a change similar to the one
> that he made to the LaTeX exporter.

Let's handle this change exporter by exporter.  The longest trip starts
with the first step :)

-- 
 Bastien

Re: [Accepted] Allow mixed export of numbered and unnumbered sections in HTML

[Nick Dokos]

Bastien Guerry <bzg@altern.org> wrote:

> Patch 711 (http://patchwork.newartisans.com/patch/711/) is now "Accepted".
> 
> Maintainer comment: none
> 

This is probably obvious but I thought I'd make it explicit, both for
future wanderers and for further discussion: application of these
patches makes the behavior of different exporters potentially
inconsistent with each other.

IMO, it would be better to accumulate the patches and once all of the
exporters (or perhaps a critical mass: ascii, odt, docbook are the ones
I would like to see get patches, but opinions will vary) have patches,
then apply the whole thing in one commit (together with a documentation
patch). In the meantime, if anybody needs one of them (hi, Suvayu :-)),
they could carry it in their local branch.

Of course, there is no perfect consistency in any case between the exporters,
but I think at least making the effort to keep them consistent is better
than letting them diverge and possibly never converge again.

Comments?

Nick

Re: Re: unnumbered subsections in latex export

[Nick Dokos]

Bastien <bzg@altern.org> wrote:

> Hi Nick,
> 
> Nick Dokos <nicholas.dokos@hp.com> writes:
> 
> > Suvayu Ali <fatkasuvayu+linux@gmail.com> wrote:
> >
> >> This works too, but Lawrence's patch makes it much easier and
> >> probably works for other export formats too. Thanks a lot. :)
> >
> > No doubt Lawrence's patch can be extended to work for other exports, but
> > it's not there yet: each exporter would need a change similar to the one
> > that he made to the LaTeX exporter.
> 
> Let's handle this change exporter by exporter.  The longest trip starts
> with the first step :)
> 

Sorry, I sent my previous comment without reading ahead for this. I still
would like to see some discussion on this, though.

Thanks,
Nick

Re: [Accepted] Allow mixed export of numbered and unnumbered sections in HTML

[Suvayu Ali]

On Wed, 23 Mar 2011 10:57:03 -0400
Nick Dokos <nicholas.dokos@hp.com> wrote:

> IMO, it would be better to accumulate the patches and once all of the
> exporters (or perhaps a critical mass: ascii, odt, docbook are the
> ones I would like to see get patches, but opinions will vary) have
> patches, then apply the whole thing in one commit (together with a
> documentation patch). In the meantime, if anybody needs one of them
> (hi, Suvayu :-)), they could carry it in their local branch.

Yes, I understand and agree to your argument. I am already using the
patch on my local branch. :)

-- 
Suvayu

Open source is the future. It sets us free.

Re: unnumbered subsections in latex export

[Lawrence Mitchell]

Nick Dokos wrote:
> Bastien <bzg@altern.org> wrote:

>> Hi Nick,

>> Nick Dokos <nicholas.dokos@hp.com> writes:

>>> Suvayu Ali <fatkasuvayu+linux@gmail.com> wrote:

>>>> This works too, but Lawrence's patch makes it much easier and
>>>> probably works for other export formats too. Thanks a lot. :)

>>> No doubt Lawrence's patch can be extended to work for other exports, but
>>> it's not there yet: each exporter would need a change similar to the one
>>> that he made to the LaTeX exporter.

>> Let's handle this change exporter by exporter.  The longest trip starts
>> with the first step :)

> Sorry, I sent my previous comment without reading ahead for this. I still
> would like to see some discussion on this, though.

Here it is again:

> This is probably obvious but I thought I'd make it explicit, both for
> future wanderers and for further discussion: application of these
> patches makes the behavior of different exporters potentially
> inconsistent with each other.

You can drop the potentially here!

> IMO, it would be better to accumulate the patches and once all of the
> exporters (or perhaps a critical mass: ascii, odt, docbook are the ones
> I would like to see get patches, but opinions will vary) have patches,
> then apply the whole thing in one commit (together with a documentation
> patch). In the meantime, if anybody needs one of them (hi, Suvayu :-)),
> they could carry it in their local branch.

> Of course, there is no perfect consistency in any case between the exporters,
> but I think at least making the effort to keep them consistent is better
> than letting them diverge and possibly never converge again.

I would agree whole-heartedly with these thoughts.  I hadn't
necessarily expected my patches to go in straight away, but
offered them for perusal.  However, this requirement may make it
difficult to get new changes into the export system.  For
example, I'm uninterested in export to backends other than latex
and html, so I'm only likely to implement a change for those
targets.  If no-one else is sufficiently interested in the change
to pick up the ball for other backends, it may never get in.
This is possibly a good thing (divergence of export functionality
and all), but may slow the acceptance of new (useful?) features.

For example, I don't know if the docbook backend explicitly
writes section numbers in, or if the sectioning is left to the
stylesheet.  If the latter, can I mark sections as ones that
should be numbered and ones that shouldn't?


On a somewhat tangential note, while grovelling around in the
latex and html backends, it seems to me that the export backends
in general could do with some loving.  It seems authors of the
backends are unclear when to use option variables, when to get
the data from the buffer-local options plist and so.  This data
is therefore treated inconsistently across backends, sometimes
(plist-get opt-plist :option) is used, sometimes the default
variable org-export-with-option is, sometimes neither are
consulted.  I'm not sufficiently excited by the grunt work to do
anything about it, but maybe I should!

Lawrence
-- 
Lawrence Mitchell <wence@gmx.li>

Re: Re: unnumbered subsections in latex export

[Thomas S. Dye]

On Mar 23, 2011, at 5:02 AM, Nick Dokos wrote:

> Bastien <bzg@altern.org> wrote:
>
>> Hi Nick,
>>
>> Nick Dokos <nicholas.dokos@hp.com> writes:
>>
>>> Suvayu Ali <fatkasuvayu+linux@gmail.com> wrote:
>>>
>>>> This works too, but Lawrence's patch makes it much easier and
>>>> probably works for other export formats too. Thanks a lot. :)
>>>
>>> No doubt Lawrence's patch can be extended to work for other  
>>> exports, but
>>> it's not there yet: each exporter would need a change similar to  
>>> the one
>>> that he made to the LaTeX exporter.
>>
>> Let's handle this change exporter by exporter.  The longest trip  
>> starts
>> with the first step :)
>>
>
> Sorry, I sent my previous comment without reading ahead for this. I  
> still
> would like to see some discussion on this, though.
>
> Thanks,
> Nick
>

Aloha Nick,

A non-programmer user's perspective.

I'm pleased that the goal of having one source file export well to  
various formats is widely held.  I'm also pleased that "exports well"  
is frequently redefined to a higher standard.  It is impressive to  
watch something as complex as Org-mode created in this way.

I agree with you that it would be more convenient for users if  
features were introduced fully formed.  I guess users get something  
like that by sticking to releases, rather than following along on  
git.  It used to perturb me that Org-mode files that I had worked hard  
to create would suddenly break, especially when these were intended to  
replace LaTeX files, which are rarely if ever broken in that stable  
environment.  I weighed that inconvenience against the good things  
that Org-mode has brought me and decided to live with the occasional  
inconvenience/catastrophe.

All the best,
Tom

Re: Re: unnumbered subsections in latex export

[Nick Dokos]

Lawrence Mitchell <wence@gmx.li> wrote:

> > patches makes the behavior of different exporters potentially
> > inconsistent with each other.
> 
> You can drop the potentially here!
> 

Well, some people might not use the feature...

> > IMO, it would be better to accumulate the patches and once all of the
> > exporters (or perhaps a critical mass: ascii, odt, docbook are the ones
> > I would like to see get patches, but opinions will vary) have patches,
> > then apply the whole thing in one commit (together with a documentation
> > patch). In the meantime, if anybody needs one of them (hi, Suvayu :-)),
> > they could carry it in their local branch.
> 
> > Of course, there is no perfect consistency in any case between the exporters,
> > but I think at least making the effort to keep them consistent is better
> > than letting them diverge and possibly never converge again.
> 
> I would agree whole-heartedly with these thoughts.  I hadn't
> necessarily expected my patches to go in straight away, but
> offered them for perusal.  However, this requirement may make it
> difficult to get new changes into the export system.  For
> example, I'm uninterested in export to backends other than latex
> and html, so I'm only likely to implement a change for those
> targets.  If no-one else is sufficiently interested in the change
> to pick up the ball for other backends, it may never get in.
> This is possibly a good thing (divergence of export functionality
> and all), but may slow the acceptance of new (useful?) features.
> 

Yes, the equivalent of a DoS attack on org's progress: nobody wants
that. One thing that might work for things like this is a git feature
branch that contains the patches for the feature. That would allow
people to pull from it and try it out. Once the feature is "complete" in
some sense, the branch could be merged to the release branch. I'm not
sure how much more work that would be for Bastien, but it seems to be a
fairly widespread workflow in git circles (see e.g.

   http://nvie.com/posts/a-successful-git-branching-model/

for a pretty nice description.)

> For example, I don't know if the docbook backend explicitly
> writes section numbers in, or if the sectioning is left to the
> stylesheet.  If the latter, can I mark sections as ones that
> should be numbered and ones that shouldn't?
> 

I don't know either - but I'll take a look at ascii and docbook at some
point (although I hope somebody will beat me to it :-) ) And I'm sure
Jambunathan will take care of the odt exporter.

> 
> On a somewhat tangential note, while grovelling around in the
> latex and html backends, it seems to me that the export backends
> in general could do with some loving.  It seems authors of the
> backends are unclear when to use option variables, when to get
> the data from the buffer-local options plist and so.  This data
> is therefore treated inconsistently across backends, sometimes
> (plist-get opt-plist :option) is used, sometimes the default
> variable org-export-with-option is, sometimes neither are
> consulted. 

+10 on that.

> I'm not sufficiently excited by the grunt work to do
> anything about it, but maybe I should!
> 

You would have the undying gratitude of all of us.  Isn't that
motivation enough? :-)

Thanks,
Nick

Re: unnumbered subsections in latex export

[Jambunathan K]

Nick Dokos <nicholas.dokos@hp.com> writes:

> Suvayu Ali <fatkasuvayu+linux@gmail.com> wrote:
>
>> This works too, but Lawrence's patch makes it much easier and
>> probably works for other export formats too. Thanks a lot. :)
>> 
>
> No doubt Lawrence's patch can be extended to work for other exports, but
> it's not there yet: each exporter would need a change similar to the one
> that he made to the LaTeX exporter.

Nick is arguing for consistency and completeness. Others are arguing for
convenience. Bastien is siding with hope :-).

I am with Nick on this debate. Nick has made his position stronger by
offering suitable alternatives.

Considering the patch has aleready been accepted I would recommend that
this feature (a quirk?) be not documented at all.

I wish we could emulate the example of Nicolas Goaziou here. Every time
he makes changes to docbook or html or latex exporters due to some
changes in the lists, I cannot stop admiring him ...

Jambunathan K.

Re: unnumbered subsections in latex export

[Jambunathan K]

>> For example, I don't know if the docbook backend explicitly
>> writes section numbers in, or if the sectioning is left to the
>> stylesheet.  If the latter, can I mark sections as ones that
>> should be numbered and ones that shouldn't?
>> 
>
> And I'm sure Jambunathan will take care of the odt exporter.

I think from odt side of things users are very likely to turn off
numbering and toc altogether and be more than happy to give finishing
touches with automatic outline numbering facility and automatic toc
generation facility offered by the viewers.

Currently the TOC and section-numbering generated by the odt exporter is
artificial. i.e., It looks like section numbers and TOC but the
underlying xml elements are not spitted out by the odt exporter.

Considering that the odt exporter is new I believe there is some
flexibility on my side to reject certain features as too niche for a
first level release :-).

Jambunathan K.

Re: Re: unnumbered subsections in latex export

[Nick Dokos]

Jambunathan K <kjambunathan@gmail.com> wrote:

> 
> >> For example, I don't know if the docbook backend explicitly
> >> writes section numbers in, or if the sectioning is left to the
> >> stylesheet.  If the latter, can I mark sections as ones that
> >> should be numbered and ones that shouldn't?
> >> 
> >
> > And I'm sure Jambunathan will take care of the odt exporter.
> 
> I think from odt side of things users are very likely to turn off
> numbering and toc altogether and be more than happy to give finishing
> touches with automatic outline numbering facility and automatic toc
> generation facility offered by the viewers.
> 
> Currently the TOC and section-numbering generated by the odt exporter is
> artificial. i.e., It looks like section numbers and TOC but the
> underlying xml elements are not spitted out by the odt exporter.
> 
> Considering that the odt exporter is new I believe there is some
> flexibility on my side to reject certain features as too niche for a
> first level release :-).
> 

Of course: if somebody needs the functionality, they implement it and
submit it - that's open source in a nutshell.

OTOH, it is important to document such limitations, so that innocent
users don't end up spending hours trying to do something that cannot
be done. 

Nick

Re: unnumbered subsections in latex export

[Jambunathan K]

> OTOH, it is important to document such limitations, so that innocent
> users don't end up spending hours trying to do something that cannot
> be done. 

Point taken.

>
> Nick
>
>

-- 

Re: Re: unnumbered subsections in latex export

[Bastien]

Dear all,

I applied the patches too hastily, disregarding some inconsistency they
could introduce between exporters -- sorry for that.

I fully agree with Nick and Thomas (and others who also agreed): Org's
export facilities need some real love and new export features need to be
introduced as complete and as consistent accross exporters as possible.

I hope we'll make progress on this for 7.6.

Here is a list of difficulties:

1. the syntax of the backends vary, and this means that all Org options
   are not meaningful in all target formats;

   *Example*: #+XSLT is only meaninful for the Docbook export.  The
   variable `org-export-html-postamble' is only meaningful for the HTML
   export.  Etc.

2. exporters use various methods to export the file (e.g. the HTML
   exporter goes line by line, the LaTeX exporter parses the file and
   render each section);

   *Example*: users often ask why the LaTeX exporter cannot export a
   headline of level 3 right after a headline of level 1: they ask that
   because the HTML exporter can do this, while the LaTeX one cannot.
   And the LaTeX one cannot because parsing an ill-structured Org buffer
   is tricky for it.

3. exporters are maintained by various people: I know the HTML exporter
   and the LaTeX one, others know the other exporters, etc.

I need your help do deal with these issues.

The first thing to do is to have a list of annoying inconsistencies that
need to be addressed in priority.

The second thing would be to build a table (somewhere on Worg?) with the
list of options and the way they are taken care by each exporter.  Such
a "synoptic view" would help developers know what they can work on, and
users know what they have to expect from options.  On the long term, it
would also help make the documentation clearer about all these aspects.

This will at least help with the first difficulty -- and motivate all
people working on the exporters to address the second one.  The third
one can be turned into a *chance*: that of having several people working
in the same direction.

So, bare with me on this :)

PS: Also note that I couldn't be as available as I wanted the 10 last
days due to personal problems, but things look better now.

-- 
 Bastien

Re: unnumbered subsections in latex export

[Achim Gratz]

Bastien <bzg@altern.org> writes:
> I fully agree with Nick and Thomas (and others who also agreed): Org's
> export facilities need some real love and new export features need to be
> introduced as complete and as consistent accross exporters as possible.
>
> I hope we'll make progress on this for 7.6.

That would be very welcome news.  I'm not sure at what level you want to
tackle that problem -- just cleaning up some glaring inconsistencies or
a full tear-down and re-build?  I suspect that a (formal) document model
for orgmode documents would be required.  This ties neatly into a formal
syntax for orgmode documents that Dominik has been asked for at FOSDEM.

> Here is a list of difficulties:
>
> 1. the syntax of the backends vary, and this means that all Org options
>    are not meaningful in all target formats;

This actually is meta-data for the export process.  It would be neat if
it were the same for each backend, but that probably doesn't make much
sense.  But at least the various backends shouldn't require different
metadata for the same purpose as long as the capabilities are the same.

> 2. exporters use various methods to export the file (e.g. the HTML
>    exporter goes line by line, the LaTeX exporter parses the file and
>    render each section);

This is a question of the supported document model(s).  Formally HTML
doesn't support a lot of what the exporter may spit out, even if it
renders as intended on many browsers.

> 3. exporters are maintained by various people: I know the HTML exporter
>    and the LaTeX one, others know the other exporters, etc.

This wouldn't be much of a problem (I think...) if there was a way to
specify which parts of the org document model are supported by the
exporter and have a generic exporter hook into the export backend with
just the parts that the backend supports.  Or the other way around,
although I suppose it would be more efficient if the generic exporter
didn't need to build structures that the backend doesn't then export due
to lack of support anyway.



Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Factory and User Sound Singles for Waldorf Blofeld:
http://Synth.Stromeko.net/Downloads.html#WaldorfSounds

Re: Re: unnumbered subsections in latex export

[Nick Dokos]

Bastien <bzg@altern.org> wrote:

> Here is a list of difficulties:
> 
> 1. the syntax of the backends vary, and this means that all Org options
>    are not meaningful in all target formats;
> 
>    *Example*: #+XSLT is only meaninful for the Docbook export.  The
>    variable `org-export-html-postamble' is only meaningful for the HTML
>    export.  Etc.
> 
> 2. exporters use various methods to export the file (e.g. the HTML
>    exporter goes line by line, the LaTeX exporter parses the file and
>    render each section);
> 
>    *Example*: users often ask why the LaTeX exporter cannot export a
>    headline of level 3 right after a headline of level 1: they ask that
>    because the HTML exporter can do this, while the LaTeX one cannot.
>    And the LaTeX one cannot because parsing an ill-structured Org buffer
>    is tricky for it.
> 
> 3. exporters are maintained by various people: I know the HTML exporter
>    and the LaTeX one, others know the other exporters, etc.
> 
> I need your help do deal with these issues.
> 
> The first thing to do is to have a list of annoying inconsistencies that
> need to be addressed in priority.
> 
> The second thing would be to build a table (somewhere on Worg?) with the
> list of options and the way they are taken care by each exporter.  Such
> a "synoptic view" would help developers know what they can work on, and
> users know what they have to expect from options.  On the long term, it
> would also help make the documentation clearer about all these aspects.
> 
> This will at least help with the first difficulty -- and motivate all
> people working on the exporters to address the second one.  The third
> one can be turned into a *chance*: that of having several people working
> in the same direction.
> 

Excellent plan!

If nobody beats me to it, I'll send out an initial draft of such a table
to the list for comment over the weekend: not a complete thing, mind
you - just something partially covering one or two exporters. We can modify
it as necessary and then proceed to populate it over the next few weeks.

Nick

PS:

> So, bare with me on this :)
> 
I'm sorry to be so sophomoric about this, but the image that popped into
my mind was a bunch of org developers dropping their pants and mooning
the world. Bastien, I will have to undergo years of therapy for this:
I'll send you the bill :-)

> PS: Also note that I couldn't be as available as I wanted the 10 last
> days due to personal problems, but things look better now.
> 

I think I'm speaking for all of us: Nothing here is so urgent that it
cannot wait for a few days or a few weeks or a few months. If something
absolutely *needs* to be done *today* (I can't think of anything that
would be this urgent, but let us say that there is something), and you
cannot get to it, let the list know: we'll either know to wait or
somebody will up and do it.

So you do what you need to do when you need to do it: org can take care
of itself for a while without much supervision. And you are not alone.

Re: Re: unnumbered subsections in latex export

[Suvayu Ali]

On Thu, 24 Mar 2011 15:25:02 -0400
Nick Dokos <nicholas.dokos@hp.com> wrote:

> > PS: Also note that I couldn't be as available as I wanted the 10
> > last days due to personal problems, but things look better now.
> >   
> 
> I think I'm speaking for all of us: Nothing here is so urgent that it
> cannot wait for a few days or a few weeks or a few months. If
> something absolutely *needs* to be done *today* (I can't think of
> anything that would be this urgent, but let us say that there is
> something), and you cannot get to it, let the list know: we'll either
> know to wait or somebody will up and do it.

To put it in org languange,

* WInP [#A] Real life

* TODO [#B] Org tasks

* TODO [#C] Other things

Wishing you the best of luck in dealing with the problems Bastien.

-- 
Suvayu

Open source is the future. It sets us free.

Re: unnumbered subsections in latex export

[Jambunathan K]

This is slightly out of thread.

I pulled the master branch with an intention to "re-baseline" my branch
and I saw some 37 lines were changed since I "branched" out my odt
branch. My heart just sinked.

A request from my side. Would it be possible to delay adding of new
capabilities and features to org-html.el till a decision on my proposed
patch is made. This would considerably reduce merging effort on my side.

ps: Hope I am not making a mountain out of a molehill.

Jambunathan K.

Re: unnumbered subsections in latex export

[Bastien]

Hi Jambunathan,

Jambunathan K <kjambunathan@gmail.com> writes:

> I pulled the master branch with an intention to "re-baseline" my branch
> and I saw some 37 lines were changed since I "branched" out my odt
> branch. My heart just sinked.
>
> A request from my side. Would it be possible to delay adding of new
> capabilities and features to org-html.el till a decision on my proposed
> patch is made. This would considerably reduce merging effort on my side.

I hear you.

I suggest me (and possibly others) stop adding changes to org-html.el
until sunday 3th of april.  Be reassured I will help fixing possible 
conflicts.

I have been in a similar situation with Julien's big changes about
org-agenda-format-item (just before 7.5): he had a complicate patch that
required a lot of attention/testing from my side and any change I wanted
to commit to org-agenda.el for other reasons would make his life harder.

I can think of two solutions:

1. freezing changes till I can spend enough time merging the big patch;

2. breaking down the big change into small meaningful changes that I (or
   others) can review *easily*.

I know you've been working very hard to find a solution as close as
possible to solution (2) -- thanks a lot for that.  Let's switch to the
(1) solution right now.

Best,

PS: As I said in a previous email, I wasn't available as much as I
wanted the last two weeks for personal reasons, and I'm working on
arranging my schedule right now.

-- 
 Bastien

Re: unnumbered subsections in latex export

[Nicolas]

Hello,

Bastien <bzg@altern.org> writes:

> 2. exporters use various methods to export the file (e.g. the HTML
>    exporter goes line by line, the LaTeX exporter parses the file and
>    render each section);
>
>    *Example*: users often ask why the LaTeX exporter cannot export a
>    headline of level 3 right after a headline of level 1: they ask that
>    because the HTML exporter can do this, while the LaTeX one cannot.
>    And the LaTeX one cannot because parsing an ill-structured Org buffer
>    is tricky for it.
>
> 3. exporters are maintained by various people: I know the HTML exporter
>    and the LaTeX one, others know the other exporters, etc.
>
> I need your help do deal with these issues.
>
> The first thing to do is to have a list of annoying inconsistencies that
> need to be addressed in priority.

I have been thinking about exporters for a while now, and I'd like to
share my point of view. Be warned, I will be a bit verbose.

Honestly, I wouldn't talk about just "annoying inconsistencies". I think
we may be running into a serious problem with exporters if some work
isn't done about them. Indeed, It seems to me that it is too much
difficult to create new exporters and managing them could become
unwieldy soon. I have my opinion on how we could anticipate and solve
that.

At the moment, the export process is done in two parts. At first, the
buffer is parsed and changed into a quite complex, and not documented
enough, format: this is the job of org-exp.el. It is complex because the
new format mixes new string markers ("ORG-CENTER-END\n") and text
properties (original-indentation). It isn't documented enough because
some of those properties are not exactly defined, and their meaning, or
their differences, aren't always explicit (org-protected, org-example,
org-verbatim-emph are coming to my mind).

It isn't a problem per se, after all Org is also rich and complex, and
a simpler way to handle this may not be sufficient. But any person
planning to create a new exporter these days has to know all of those
subtleties, and pay attention to both visible and invisible markers when
parsing the new format.

The second part of the export process is backend specific. I'm talking
about org-latex.el org-html.el, etc. As Bastien pointed out, they often
parse the buffer their own way (line-wise or section-wise), adding one
layer of complexity for anyone trying to understand them, and creating
inconsistencies at the same time.

This is why I think exporting should take a slightly different approach.
In essence, org-exp.el should parse itself the format it creates and
call functions from backend specific exporters for each environment or
object it encounters during the parsing. In other words, specific
exporters should only consist in a sum of independent functions, named
uniformly (org-html-export-list, org-latex-export-center), and acting
recursively on parts of the buffer, in a format precisely documented.

Thus, Org documentation should provide an exhaustive list of
environments and objects it offers with their associated format during
export. Then, creating an exporter should be as simple as providing
functions to change every one of them into meaningful strings, which
would then be collected by org-exp.el. The immediate benefit is that
only those among us patching org-exp.el will have to know the
intermediate format it creates, and those creating or patching backends
will work on a well-defined format.

I'll show two examples to illustrate my point: lists and tables. Taken
from a docstring, 

1. first item
   + sub-item one
   + [X] sub-item two
   more text in first item
2. [@3] last item

will be parsed as:

(ordered (nil \"first item\"
              (unordered (nil "sub-item one")
                         (nil "[CBON] sub-item two"))
              "more text in first item"")
         (3 "last item"))

This allows to easily (see org-list-to-latex, org-list-to-html,
org-list-to-texinfo, and so on) transform an Org list in many different
formats. Alas, it cannot be used in org-html.el and org-docbook.el, as
those, again, parse buffer line-wise.

The same could be said about tables:

| Row 1 | 1 | 2 |
|-------+---+---|
| Row 2 | 3 | 4 |

can be parsed as:

(("Row 1" "1" "2")
 'hline
 ("Row 2" "3" "4"))

and from that, such functions as orgtbl-to-html, or orgtbl-to-latex were
easy to create.

So, basically, what I suggest here is:

1. list all possible environments and objects offered by the Org format
   (table, lists, inlinetasks, center, verbatim, paragraph, headlines,
   time-stamps, LaTeX snippets, footnotes, links, source);
2. define an explicit export format for each of them;
3. determine options that should be know by org-exp, by the backend;
4. create a parser, in org-exp, that will output Org buffer in the
   chosen format;
5. create (many are readily available) functions for each backend to
   interpret them.


Now about that explicit format. Taking this buffer,

--8<---------------cut here---------------start------------->8---
#+title: Example buffer

Some text before first headline.

* First section

  First paragraph $\alpha = 1$.

  Second paragraph.

  - item 1
  - item 2
    #+begin_center
    Text
    #+end_center

  | Row 1 | 1 | 2 |
  | Row 2 | 3 | 4 |

* Second section

  Text with footnote[fn:1].
*************** Inline task
                Some text and
                a [[http://www.gnu.org/software/emacs/][link]]
                :DRAWER:
                - I like
                - lists.
                :END:
*************** END

* Footnotes
[fn:1] Footnote definition.
--8<---------------cut here---------------end--------------->8---

It could be parsed as the following:

'((:title "Example buffer")
  (paragraph "Some text before first headline.")
  (headline "First section" 
            (paragraph "First paragraph " 
                       (latex "$\alpha = 1") 
                       ".")
            (paragraph "Second paragraph")
            (list unordered (nil "item 1") 
                            (nil "item 2")
                            (center (paragraph "Text")))
            (table ("Row 1" "1" "2")
                   hline
                   ("Row 2" "3" "4")))
  (headline "Second section"
            (paragraph "Text with footnote"
                       (footnote "Footnote definition")
                       ".")
            (inlinetask "Inline task"
                        (paragraph "Some text and\na "
                                   (link "link" "http://www.gnu.org/"))
                        (drawer (list unordered (nil "I like")
                                                (nil "lists."))))))

Note that such a parsing will need a decent forward-paragraph function.
It's also a very simplified example: headlines would need more than the
title string (todo keyword, priority, tags) before starting the body.

I have no code to offer at the moment, and, as we all know, Devil is in
the details. But if the output from org-exp.el is clear, exporters will
be more coherent. It is even provide tools to help exporters doing their
task (a function to extract footnotes from the output, for example).

Again, it may be a big task to undertake, but I think it will be
necessary at some point.

Regards,

-- 
Nicolas

Re: unnumbered subsections in latex export

[Jambunathan K]

Backward compatibility is a real issue. 

The real challenge is how to move forward while also not breaking
anything that the users have come to rely on.

> Thus, Org documentation should provide an exhaustive list of
> environments and objects it offers with their associated format during
> export. Then, creating an exporter should be as simple as providing
> functions to change every one of them into meaningful strings, which
> would then be collected by org-exp.el. The immediate benefit is that
> only those among us patching org-exp.el will have to know the
> intermediate format it creates, and those creating or patching backends
> will work on a well-defined format.
>
> I'll show two examples to illustrate my point: lists and tables. Taken
> from a docstring, 
>
> 1. first item
>    + sub-item one
>    + [X] sub-item two
>    more text in first item
> 2. [@3] last item
>
> will be parsed as:
>
> (ordered (nil \"first item\"
>               (unordered (nil "sub-item one")
>                          (nil "[CBON] sub-item two"))
>               "more text in first item"")
>          (3 "last item"))
>
> This allows to easily (see org-list-to-latex, org-list-to-html,
> org-list-to-texinfo, and so on) transform an Org list in many different
> formats. Alas, it cannot be used in org-html.el and org-docbook.el, as
> those, again, parse buffer line-wise.

From a refactoring perspective, it is not necessary that a XML-like list
structure be offered to the html backend. In principle, it would suffice
as long as the html exporter is provided with enough information so that
it can "deduce" the above structure while still continuing to be
line-oriented.

>
> The same could be said about tables:
>
> | Row 1 | 1 | 2 |
> |-------+---+---|
> | Row 2 | 3 | 4 |
>
> can be parsed as:
>
> (("Row 1" "1" "2")
>  'hline
>  ("Row 2" "3" "4"))
>
> and from that, such functions as orgtbl-to-html, or orgtbl-to-latex were
> easy to create.
>
> So, basically, what I suggest here is:
>
> 1. list all possible environments and objects offered by the Org format
>    (table, lists, inlinetasks, center, verbatim, paragraph, headlines,
>    time-stamps, LaTeX snippets, footnotes, links, source);
> 2. define an explicit export format for each of them;
> 3. determine options that should be know by org-exp, by the backend;
> 4. create a parser, in org-exp, that will output Org buffer in the
>    chosen format;
> 5. create (many are readily available) functions for each backend to
>    interpret them.

Do look at my new html exporter. I have been very conservative in making
the changes.

Some observations from my side ...

>  It isn't documented enough because some of those properties are not
> exactly defined, and their meaning, or their differences, aren't
> always explicit (org-protected, org-example, org-verbatim-emph are
> coming to my mind).

I agree that text properties are problematic. I see that they are also
used inconsistently.

Consider org-example.

A source block is transformed by org-exp.el in to a html block and is
enclosed in #+begin_html...#+end_html. On the otherhand the #+begin_html
and #+end_html given by the user isn't marked up with this property.

[Context Switch]

Protection this seems to me to happen at three levels. Protection at
block level happens in example/source blocks, Protection at phrase level
happens in verbatim LaTeX equations (fragments?) and Protection at tag
level as implied in @<tag> @<tag/> convention.

[Context Switch]
When I see backend specific code in org-exp.el something in my gut says
that it is not OK.

For example, source blocks are transformed in org-exp.el to
html-specific markup and get inserted between #+begin_html and
#+end_html with org-indentation, org-protected properties. org-html.el
just inserts it.

I believe, it would be all the more better if the above "transform &
propertize in org-exp.el and just insert in org-html.el" is done as
"propertize in org-exp.el and transform & insert in org-html.el".

[Context Switch]
Html exporter is not only line-oriented it is also a transformation
pipeline. The latter part means that if lines are slightly arranged
(that is the order of the transformation is changed) then things will
break in unexpected ways.

This is the root cause of all the recent regressions concerning images
and timestamps in the HTML exporter.

[Context Switch] 
org-html.el opens paragraph in anticipation rather than when it is
actually needed. As a result previous context just diffuses in to a
latter context. If this were not so deleting of empty paragraphs
wouldn't be necessary. 

[Context Switch]
HTML exporter occasionally emit things temporarily and goes back and
fixes it. Table's colalign and colgroup markers come to mind here. In
some sense convenience features like "right align if a column is
predominantly numeric" also complicated things.

I think one of the reasons Org is so popular it is that it is a
common-man's swiss army knife and not a elitist samurai sword.

Jambunathan K.

Re: unnumbered subsections in latex export

[Jambunathan K]

One more thing to the list.

Use htmlfontify instead of htmlize. Former is part of standard Emacs
while the latter is not.

Jambunathan K.

Re: unnumbered subsections in latex export

[Nick Dokos]

Jambunathan K <kjambunathan@gmail.com> wrote:

> Do look at my new html exporter. I have been very conservative in making
> the changes.
> 
Well, Nicolas's proposal is more radical, but there is no inherent
backward compatibility disadvantage to it that I can see.

> Some observations from my side ...
> 
> >  It isn't documented enough because some of those properties are not
> > exactly defined, and their meaning, or their differences, aren't
> > always explicit (org-protected, org-example, org-verbatim-emph are
> > coming to my mind).
> 
> I agree that text properties are problematic. I see that they are also
> used inconsistently.
> 
> When I see backend specific code in org-exp.el something in my gut says
> that it is not OK.
> 

Absolutely. It is the price that one has to pay when trying to add new
features to a system that has become successful and you don't dare break
backward compatibility: sometimes you have to resort to ugly hacks.
Think Windows e.g. which by now is riddled with ugly hacks, partly
because they don't want to give up backward compatibility.

Lest I give the wrong impression, let me say that even though org has
dark and ugly corners here and there, overall it is a thing of
beauty. Windows, not so much :-)

> For example, source blocks are transformed in org-exp.el to
> html-specific markup and get inserted between #+begin_html and
> #+end_html with org-indentation, org-protected properties. org-html.el
> just inserts it.
> 
> I believe, it would be all the more better if the above "transform &
> propertize in org-exp.el and just insert in org-html.el" is done as
> "propertize in org-exp.el and transform & insert in org-html.el".
> 

IIUC, Nicolas proposes to make the exporters behave more like a modern
compiler: there is an intermediate representation (an attributed tree)
that the org document is transformed to. Then there is a standard tree
walker that walks the tree and does callbacks to backend-specific
functions. Each backend is responsible for providing this well-defined
set of functions. If a new syntactic or semantic element is introduced
that necessitates a new type of node in the tree, then the
walker would call a new function to handle the new node type: each
backend would have to implement this new function. As compiler writers
have found out, this makes it much easier to support a new backend.

> [Context Switch]
> Html exporter is not only line-oriented it is also a transformation
> pipeline. The latter part means that if lines are slightly arranged
> (that is the order of the transformation is changed) then things will
> break in unexpected ways.
> 
> This is the root cause of all the recent regressions concerning images
> and timestamps in the HTML exporter.
> 
> [Context Switch] 
> org-html.el opens paragraph in anticipation rather than when it is
> actually needed. As a result previous context just diffuses in to a
> latter context. If this were not so deleting of empty paragraphs
> wouldn't be necessary. 
> 
> [Context Switch]
> HTML exporter occasionally emit things temporarily and goes back and
> fixes it. Table's colalign and colgroup markers come to mind here. In
> some sense convenience features like "right align if a column is
> predominantly numeric" also complicated things.
> 
> I think one of the reasons Org is so popular it is that it is a
> common-man's swiss army knife and not a elitist samurai sword.
> 

To continue your analogy: sometimes the cut is a bit rough. It might
be a good idea to use some of that elitist samurai sword metallurgy
know-how in order to provide better blades for the swiss army knife.

> Jambunathan K.
> 

Nick

Re: unnumbered subsections in latex export

[Jambunathan K]

> I'll show two examples to illustrate my point: lists and tables. Taken
> from a docstring, 
>
> 1. first item
>    + sub-item one
>    + [X] sub-item two
>    more text in first item
> 2. [@3] last item
>
> will be parsed as:
>
> (ordered (nil \"first item\"
>               (unordered (nil "sub-item one")
>                          (nil "[CBON] sub-item two"))
>               "more text in first item"")
>          (3 "last item"))
>
> This allows to easily (see org-list-to-latex, org-list-to-html,
> org-list-to-texinfo, and so on) transform an Org list in many different
> formats. Alas, it cannot be used in org-html.el and org-docbook.el, as
> those, again, parse buffer line-wise.
>
> The same could be said about tables:
>
> | Row 1 | 1 | 2 |
> |-------+---+---|
> | Row 2 | 3 | 4 |
>
> can be parsed as:
>
> (("Row 1" "1" "2")
>  'hline
>  ("Row 2" "3" "4"))
>
> and from that, such functions as orgtbl-to-html, or orgtbl-to-latex were
> easy to create.
>
> So, basically, what I suggest here is:
>
> 1. list all possible environments and objects offered by the Org format
>    (table, lists, inlinetasks, center, verbatim, paragraph, headlines,
>    time-stamps, LaTeX snippets, footnotes, links, source);
> 2. define an explicit export format for each of them;
> 3. determine options that should be know by org-exp, by the backend;
> 4. create a parser, in org-exp, that will output Org buffer in the
>    chosen format;
> 5. create (many are readily available) functions for each backend to
>    interpret them.
>
>
> Now about that explicit format. Taking this buffer,
>
> #+title: Example buffer
>
> Some text before first headline.
>
> * First section
>
>   First paragraph $\alpha = 1$.
>
>   Second paragraph.
>
>   - item 1
>   - item 2
>     #+begin_center
>     Text
>     #+end_center
>
>   | Row 1 | 1 | 2 |
>   | Row 2 | 3 | 4 |
>
> * Second section
>
>   Text with footnote[fn:1].
> *************** Inline task
>                 Some text and
>                 a [[http://www.gnu.org/software/emacs/][link]]
>                 :DRAWER:
>                 - I like
>                 - lists.
>                 :END:
> *************** END
>
> * Footnotes
> [fn:1] Footnote definition.
>
> It could be parsed as the following:
>
> '((:title "Example buffer")
>   (paragraph "Some text before first headline.")
>   (headline "First section" 
>             (paragraph "First paragraph " 
>                        (latex "$\alpha = 1") 
>                        ".")
>             (paragraph "Second paragraph")
>             (list unordered (nil "item 1") 
>                             (nil "item 2")
>                             (center (paragraph "Text")))
>             (table ("Row 1" "1" "2")
>                    hline
>                    ("Row 2" "3" "4")))
>   (headline "Second section"
>             (paragraph "Text with footnote"
>                        (footnote "Footnote definition")
>                        ".")
>             (inlinetask "Inline task"
>                         (paragraph "Some text and\na "
>                                    (link "link" "http://www.gnu.org/"))
>                         (drawer (list unordered (nil "I like")
>                                                 (nil "lists."))))))
>
> Note that such a parsing will need a decent forward-paragraph function.
> It's also a very simplified example: headlines would need more than the
> title string (todo keyword, priority, tags) before starting the body.
>
> I have no code to offer at the moment, and, as we all know, Devil is in
> the details. But if the output from org-exp.el is clear, exporters will
> be more coherent. It is even provide tools to help exporters doing their
> task (a function to extract footnotes from the output, for example).
>
> Again, it may be a big task to undertake, but I think it will be
> necessary at some point.

Such an exporter (or similar in spirit to what you say) exists already.

For the sake of record, I am copying Bastien's notes on his
./EXPERIMENTAL/org-export.el (with some non-relevant content stripped)

Jambunathan K.


Attachment:

From: Bastien <bastien.guerry@wikimedia.fr>
Subject: Re: OpenDocumentText/OpenOffice exporter
To: Lennart Borgman <lennart.borgman@gmail.com>
Cc: Jambunathan K <kjambunathan@gmail.com>,  Carsten Dominik <carsten.dominik@gmail.com>
Date: Sun, 13 Feb 2011 11:00:34 +0100 (6 weeks, 4 days, 21 hours ago)
Message-ID: <87tyg8ntj1.fsf@gnu.org>

Hi Lennart,

Lennart Borgman <lennart.borgman@gmail.com> writes:

> Perhaps we have done something very similar then, I do not know.

My bad.  I should have advertize EXPERIMENTAL/org-export.el sooner.

> So maybe your approach of parsing the org buffer to a list makes
> things more easy to handle. On what level is the list? (From your
> description I guess it is a "parse tree" or whatever it is called. Not
> a list of tokens.)

It's a parse tree.  

See attached example of a test.org file and the result of the function
(org-export-parse) : this list will go through the exporter, which takes
care of every subtree recursively.

Of course, having such a parse tree does not solve everything, and the
content of :content remains to be handled...  but at least it makes
things quite clear.

[2. text/x-org; test.org]

#+TITLE: Test parse file
#+AUTHOR: Bastien

* A first heading

Some text here.

* WAITING A heading with metadata				   :Write:

The parse tree contains information about the current subtree.

** A subtree

Hello.
[3. text/plain; test_parsed.txt]

((:level 1 :heading
	 #("A first heading" 0 15
	   (fontified t font-lock-fontified t face org-level-1))
	 :properties
	 (("FILE" . "/home/guerry/test.org")
	  ("BLOCKED" . "")
	  ("CATEGORY" . "test"))
	 :content
	 #("\nSome text here.\n\n" 0 1
	   (fontified t font-lock-fontified t org-category "test")
	   1 17
	   (fontified t font-lock-fontified t org-category "test")
	   17 18
	   (fontified t font-lock-fontified t org-category "test"))
	 :subtree nil)
 (:level 1 :heading
	 #("A heading with metadata" 0 23
	   (fontified t font-lock-fontified t org-todo-head "NEXT" face org-level-1 org-category "test"))
	 :properties
	 (("TODO" . "WAITING")
	  ("FILE" . "/home/guerry/test.org")
	  ("TAGS" . ":Write:")
	  ("ALLTAGS" . ":Write:")
	  ("BLOCKED" . "")
	  ("CATEGORY" . "test"))
	 :content
	 #("\nThe parse tree contains information about the current subtree.\n\n" 0 1
	   (org-todo-head "NEXT" fontified t org-category "test")
	   1 64
	   (org-todo-head "NEXT" fontified t org-category "test")
	   64 65
	   (org-todo-head "NEXT" fontified t org-category "test"))
	 :subtree
	 ((:level 2 :heading
		  #("A subtree" 0 9
		    (org-todo-head "NEXT" fontified t face org-level-2 org-category "test"))
		  :properties
		  (("FILE" . "/home/guerry/test.org")
		   ("ALLTAGS" .
		    #(":Write:" 1 6
		      (inherited t)))
		   ("BLOCKED" . "")
		   ("CATEGORY" . "test"))
		  :content
		  #("\nHello.\n" 0 1
		    (org-todo-head "NEXT" fontified t org-category "test")
		    1 7
		    (org-todo-head "NEXT" fontified t org-category "test")
		    7 8
		    (fontified t font-lock-fontified t org-category "test"))
		  :subtree nil))))

Re: Re: unnumbered subsections in latex export

[Eric S Fraga]

Jambunathan K <kjambunathan@gmail.com> writes:

[...]

> I think one of the reasons Org is so popular it is that it is a
> common-man's swiss army knife and not a elitist samurai sword.

And I think this is a very important analogy.  Org does a good job for
many (very different) tasks.  The price is that it does not necessarily
do some of those tasks as well as could be.

I am happy to put with the rough edges exposed by the exporters because
of what the whole package provides.  Case in point: I submitted a paper
yesterday which I wrote in org.  However, for the submission, once I was
happy with all the content, I had to tweak the latex to meet the
journal's format because they provide a style file which requires title,
author, etc. to come *after* the \begin{document}.  

I could have fooled org into doing the "right thing" but it was simply
easier to worry about this at the end and not get hung up with the minor
exporting issues involved.  By using org for writing (days, weeks) and
latex (5-10 minutes) for the final tweaking, my productivity was
probably as high as it will ever get for this type of task.

This is *not* an argument against an improved export engine in org,
simply a comment on perspective and relative importance!

-- 
: Eric S Fraga (GnuPG: 0xC89193D8FFFCF67D) in Emacs 24.0.50.1
: using Org-mode version 7.5 (release_7.5.126.g0e3a8)

Re: unnumbered subsections in latex export

[Achim Gratz]

Nicolas <n.goaziou@gmail.com> writes:
> I have been thinking about exporters for a while now, and I'd like to
> share my point of view. Be warned, I will be a bit verbose.
[...]

+1

A remark about backwards compatibility:

I personally don't have a huge investment in documents that I export,
but I guess that backwards compatibility and/or a converter that points
out and possibly fixes any incompatibility between old and new exporters
would be required to make the transition smoothly.  Again, the changes
envisioned by Nicholas would require that the orgg documents in question
are well-formed (or at least fixable for the purposes of the export with
trivial and stable changes).  The situation today is that some export
backends require different levels of conformance while this new solution
would require the same quality for all of them.


Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Factory and User Sound Singles for Waldorf rackAttack:
http://Synth.Stromeko.net/Downloads.html#WaldorfSounds

Re: unnumbered subsections in latex export

[Matt Lundin]

Eric S Fraga <e.fraga@ucl.ac.uk> writes:

> Jambunathan K <kjambunathan@gmail.com> writes:
>
> [...]
>
>> I think one of the reasons Org is so popular it is that it is a
>> common-man's swiss army knife and not a elitist samurai sword.
>
> And I think this is a very important analogy.  Org does a good job for
> many (very different) tasks.  The price is that it does not necessarily
> do some of those tasks as well as could be.
>
> I am happy to put with the rough edges exposed by the exporters because
> of what the whole package provides.  Case in point: I submitted a paper
> yesterday which I wrote in org.  However, for the submission, once I was
> happy with all the content, I had to tweak the latex to meet the
> journal's format because they provide a style file which requires title,
> author, etc. to come *after* the \begin{document}.  

I agree that the org-exporter currently does its job very well. The
astounding utility of org-mode is ample proof of the value of releasing
early; even if the exporter is not as elegant as a modern compiler, it
works. :)

That said, I very much support Nicolas' proposal. Right now, the issue
is not so much the end user's experience as it is the ease of
maintaining and developing the backends. We obviously don't want org to
be as strict as xml --- i.e., the a new export parser should be somewhat
forgiving. But a more abstract approach would make it easier to build
new backends or fix bugs that effect all of the backends. One might even
develop an org backend -- i.e., export functions that take the data
produced by the parser and spit out an Org-mode syntax. One might then
write importers that parse other types of files (mediawiki, markdown,
latex, etc.) and return the data structure expected by org-exp.el. Of
course, this latter possibility may not be necessary, given that pandoc
can already convert to org files. :)

Best,
Matt

Re: unnumbered subsections in latex export

[Jambunathan K]

Matt Lundin <mdl@imapmail.org> writes:

> Eric S Fraga <e.fraga@ucl.ac.uk> writes:
>
>> Jambunathan K <kjambunathan@gmail.com> writes:
>>
>> [...]
>>
>>> I think one of the reasons Org is so popular it is that it is a
>>> common-man's swiss army knife and not a elitist samurai sword.
>>
>> And I think this is a very important analogy.  Org does a good job for
>> many (very different) tasks.  The price is that it does not necessarily
>> do some of those tasks as well as could be.
>>
>> I am happy to put with the rough edges exposed by the exporters because
>> of what the whole package provides.  Case in point: I submitted a paper
>> yesterday which I wrote in org.  However, for the submission, once I was
>> happy with all the content, I had to tweak the latex to meet the
>> journal's format because they provide a style file which requires title,
>> author, etc. to come *after* the \begin{document}.  
>
> I agree that the org-exporter currently does its job very well. The
> astounding utility of org-mode is ample proof of the value of releasing
> early; even if the exporter is not as elegant as a modern compiler, it
> works. :)
>
> That said, I very much support Nicolas' proposal. 

A quick (prototype) exporter demoing Nicolas's proposal could be
developed by using my new org-html.el in under few hours.

Think of it this way: If something could be XML-ified it could be
lispified. My exporter already has a common core that emits html and odt
and it is a matter of altering few callbacks so that it generates a
lispy list instead of XML.


> Best,
> Matt

Re: unnumbered subsections in latex export

[Sébastien Vauban]

Hi Nick and al.,

Nick Dokos wrote:
>> This will at least help with the first difficulty -- and motivate all
>> people working on the exporters to address the second one. The third one
>> can be turned into a *chance*: that of having several people working in the
>> same direction.
>
> Excellent plan!
>
> If nobody beats me to it, I'll send out an initial draft of such a table to
> the list for comment over the weekend: not a complete thing, mind you - just
> something partially covering one or two exporters. We can modify it as
> necessary and then proceed to populate it over the next few weeks.

When discussing exporters and features, two things that come up to my mind as
missing as a "general Org feature":

- bibliography :: works for LaTeX[1], not for HTML export.
- acronyms :: idem.

Maybe those should be made available for general Org usage by making them
somehow part of the preprocessing?

Best regards,
  Seb

Footnotes:

[1] ... but "uglyfies" a bit (too much) the *visible* text. Ideally, such
features should be hidden behind things like links or so.
-- 
Sébastien Vauban

Re: unnumbered subsections in latex export

[Matt Lundin]

Hi Jambunathan,

Jambunathan K <kjambunathan@gmail.com> writes:

> Matt Lundin <mdl@imapmail.org> writes:
>
>> I agree that the org-exporter currently does its job very well. The
>> astounding utility of org-mode is ample proof of the value of releasing
>> early; even if the exporter is not as elegant as a modern compiler, it
>> works. :)
>>
>> That said, I very much support Nicolas' proposal. 
>
> A quick (prototype) exporter demoing Nicolas's proposal could be
> developed by using my new org-html.el in under few hours.
>
> Think of it this way: If something could be XML-ified it could be
> lispified. My exporter already has a common core that emits html and odt
> and it is a matter of altering few callbacks so that it generates a
> lispy list instead of XML.

Thanks for all the hard work on your exporter and the rewrite! I look
forward to looking at it more closely very soon.

In the meantime, does anyone have advice on how to start creating a
formal syntax definition for org-mode? Any good links or resources we
might check out?

I'm guessing that writing a formal definition is more complex than
simply defining org-mode syntax in prose---that we are after something a
little more formal and symbolic than "a headline is demarcated by one or
more asterisks beginning at column 0 of a new line...." Is that correct?

Best,
Matt

Re: Re: unnumbered subsections in latex export

[Nick Dokos]

Sébastien Vauban <wxhgmqzgwmuf@spammotel.com> wrote:

> Hi Nick and al.,
> 
> Nick Dokos wrote:
> >> This will at least help with the first difficulty -- and motivate all
> >> people working on the exporters to address the second one. The third one
> >> can be turned into a *chance*: that of having several people working in the
> >> same direction.
> >
> > Excellent plan!
> >
> > If nobody beats me to it, I'll send out an initial draft of such a table to
> > the list for comment over the weekend: not a complete thing, mind you - just
> > something partially covering one or two exporters. We can modify it as
> > necessary and then proceed to populate it over the next few weeks.
> 

BTW, I got buried last week and at least through this one, so not much
progress. It might go faster if somebody does beat me to it.

Thanks,
Nick

> When discussing exporters and features, two things that come up to my mind as
> missing as a "general Org feature":
> 
> - bibliography :: works for LaTeX[1], not for HTML export.
> - acronyms :: idem.
> 
> Maybe those should be made available for general Org usage by making them
> somehow part of the preprocessing?
> 
> Best regards,
>   Seb
> 
> Footnotes:
> 
> [1] ... but "uglyfies" a bit (too much) the *visible* text. Ideally, such
> features should be hidden behind things like links or so.
> -- 
> Sébastien Vauban
> 
> 

Re: Re: unnumbered subsections in latex export

[Nick Dokos]

Matt Lundin <mdl@imapmail.org> wrote:

> Hi Jambunathan,
> 
> Jambunathan K <kjambunathan@gmail.com> writes:
> 
> > Matt Lundin <mdl@imapmail.org> writes:
> >
> >> I agree that the org-exporter currently does its job very well. The
> >> astounding utility of org-mode is ample proof of the value of releasing
> >> early; even if the exporter is not as elegant as a modern compiler, it
> >> works. :)
> >>
> >> That said, I very much support Nicolas' proposal. 
> >
> > A quick (prototype) exporter demoing Nicolas's proposal could be
> > developed by using my new org-html.el in under few hours.
> >
> > Think of it this way: If something could be XML-ified it could be
> > lispified. My exporter already has a common core that emits html and odt
> > and it is a matter of altering few callbacks so that it generates a
> > lispy list instead of XML.
> 
> Thanks for all the hard work on your exporter and the rewrite! I look
> forward to looking at it more closely very soon.
> 
> In the meantime, does anyone have advice on how to start creating a
> formal syntax definition for org-mode? Any good links or resources we
> might check out?

EBNF is pretty much the standard metasyntax for context-free grammars (check Wikipedia).
However, I doubt org is context-free, so EBNF might need extensions to deal with it.
Or it can do the context-free part and any context-dependent stuff is superimposed on
that.

Nick

> 
> I'm guessing that writing a formal definition is more complex than
> simply defining org-mode syntax in prose---that we are after something a
> little more formal and symbolic than "a headline is demarcated by one or
> more asterisks beginning at column 0 of a new line...." Is that correct?
> 
> Best,
> Matt
> 

Re: Re: unnumbered subsections in latex export

[Aankhen]

Hullo,

2011/4/4 Sébastien Vauban <wxhgmqzgwmuf@spammotel.com>:
> [snip]
>
> When discussing exporters and features, two things that come up to my mind as
> missing as a "general Org feature":
>
> - bibliography :: works for LaTeX[1], not for HTML export.
> - acronyms :: idem.
>
> Maybe those should be made available for general Org usage by making them
> somehow part of the preprocessing?

FWIW, acronyms wouldn’t need any preprocessing for HTML export.  Or
maybe they would: HTML has both ‘acronym’ and ‘abbr’ (abbreviation)
elements, the distinction between them being a little hard to make.
Could go the other way and provide both in Org and combine them where
there’s no distinction, I suppose.

Uhm, anyway.  Acronyms are natively supported in HTML.  That is all.

Aankhen

Re: unnumbered subsections in latex export

[Sébastien Vauban]

Hi Aankhen,

Aankhen wrote:
> 2011/4/4 Sébastien Vauban <wxhgmqzgwmuf-geNee64TY+gS+FvcfC7Uqw@public.gmane.org>:
>> [snip]
>>
>> When discussing exporters and features, two things that come up to my mind
>> as missing as a "general Org feature":
>>
>> - bibliography :: works for LaTeX[1], not for HTML export.
>> - acronyms :: idem.
>>
>> Maybe those should be made available for general Org usage by making them
>> somehow part of the preprocessing?
>
> FWIW, acronyms wouldn’t need any preprocessing for HTML export. Or maybe
> they would: HTML has both ‘acronym’ and ‘abbr’ (abbreviation) elements, the
> distinction between them being a little hard to make. Could go the other way
> and provide both in Org and combine them where there’s no distinction, I
> suppose.
>
> Uhm, anyway. Acronyms are natively supported in HTML. That is all.

Thanks for reporting this. Wasn't aware of it. Though, that does not alter the
need (at least, what I consider so) for acronyms handling in/from Org.

Let's clarify what I'm talking about -- I know, I should have done it earlier.

I want to be able to say, in my Org file, that DNS is an acronym, for example.
I'm thinking -- brainstorming! -- at a solution _such as_ adding accolades
around the acronyms:

--8<---------------cut here---------------start------------->8---
This paper talks about {DNS} clients and {DNS} servers...
--8<---------------cut here---------------end--------------->8---

In LaTeX, this should have to be translated to:

--8<---------------cut here---------------start------------->8---
This paper talks about \acro{DNS} clients and \acro{DNS} servers...
--8<---------------cut here---------------end--------------->8---

And the effects would be that:

1. the first occurrence of the acronym would be expanded in the PDF, while
   others not -- this is customizable!

2. every occurrence would be a link to the list of acronyms, at the end of the
   document.

In HTML, I would expect internal links to a list of acronyms at the end of the
document.

I was thinking at preprocessing, because some smart things need to be done:

- expanding the first occurrence of the acronym (if wished) with its
  definition, not the following;

- in the list, at the end of the document, only list acronym definitions for
  the acronyms that have been used in the document.

For the readability of the Org buffer, and for the behavior that we could
expect, maybe a new link type would make it?

I would expect a similar treatment for the bibliography: having some built-in
representation for that in Org, and have the exporters make it to both LaTeX
and HTML (and ...).

Comments welcome!

Best regards,
  Seb

-- 
Sébastien Vauban

Re: Re: unnumbered subsections in latex export

[Aankhen]

Hi Sébastien,

2011/4/5 Sébastien Vauban <wxhgmqzgwmuf@spammotel.com>:
> Aankhen wrote:
>> [snip]
>> Acronyms are natively supported in HTML. That is all.
>
> Thanks for reporting this. Wasn't aware of it. Though, that does not alter the
> need (at least, what I consider so) for acronyms handling in/from Org.
>
> Let's clarify what I'm talking about -- I know, I should have done it earlier.
>
> I want to be able to say, in my Org file, that DNS is an acronym, for example.
> I'm thinking -- brainstorming! -- at a solution _such as_ adding accolades
> around the acronyms:
>
> --8<---------------cut here---------------start------------->8---
> This paper talks about {DNS} clients and {DNS} servers...
> --8<---------------cut here---------------end--------------->8---
>
> In LaTeX, this should have to be translated to:
>
> --8<---------------cut here---------------start------------->8---
> This paper talks about \acro{DNS} clients and \acro{DNS} servers...
> --8<---------------cut here---------------end--------------->8---
>
> And the effects would be that:
>
> 1. the first occurrence of the acronym would be expanded in the PDF, while
>   others not -- this is customizable!
>
> 2. every occurrence would be a link to the list of acronyms, at the end of the
>   document.
>
> In HTML, I would expect internal links to a list of acronyms at the end of the
> document.
>
> I was thinking at preprocessing, because some smart things need to be done:
>
> - expanding the first occurrence of the acronym (if wished) with its
>  definition, not the following;
>
> - in the list, at the end of the document, only list acronym definitions for
>  the acronyms that have been used in the document.

Thank you for the clarifications.  I’m going to talk a bit more about
HTML as that’s where I have the most experience.  I am in agreement
with you when you say that builtin support for acronyms would be
useful (although I feel it would be good to generalize it to
abbreviations, if that can also be supported in other backends).  When
you have the following markup:

,----
| <acronym title="Hypertext Markup Language">HTML</acronym> is a
| language for marking up documents.  The most current version
| of <acronym title="Hypertext Markup Language">HTML</acronym> is 4.01.
| The successor to <acronym title="Hypertext Markup
| Language">HTML</acronym>, HTML5, is currently under development.
`----

The expansion is invisible by default; it shows up in a tooltip when
you hover over the text.  You can try a live example to see for
yourself.[1] In this way, the expansion is always there when you need
it (and you can distinguish between multiple terms sharing the same
acronym, should the need ever arise), but it takes up no space if you
don’t.

I would suggest that, were Org to gain support for acronyms and/or
abbreviations, they be exported in HTML using ‘abbr’ (‘acronym’ is
deprecated thanks to HTML5) with the ‘title’ defined for each
occurrence, and with CSS to ensure consistent rendering, along these
lines:

,----
| abbr { font-variant: small-caps; border-bottom: 1px dashed; cursor: help; }
`----

I can see the argument for having a list at the end and linking each
definition instead.  I feel that’s less convenient, however, as (a) it
means temporarily losing your place in the document and (b) bunched-up
anchors at the end of a document are a pain.  Of course,
alternatively, each acronym/abbreviation could be marked up only at
the first occurrence; that seems like it would be easy to implement as
a configuration option.

> For the readability of the Org buffer, and for the behavior that we could
> expect, maybe a new link type would make it?

The only thing is, links can’t be nested, can they?  I’m thinking of a
situation like ‘read the HTML 4.01 specification online’, where the
entire text is a link and ‘HTML’ is an abbreviation.  I suppose this
might not be a particularly important use case.

> I would expect a similar treatment for the bibliography: having some built-in
> representation for that in Org, and have the exporters make it to both LaTeX
> and HTML (and ...).

I have no experience or opinions when it comes to bibliographies, so
I’ll abstain from commenting beyond saying that it seems logical to
have a centralized database at least within an Org file. :-)

Aankhen

[1]: https://developer.mozilla.org/en/HTML/Element/acronym

Re: Re: unnumbered subsections in latex export

[Eric S Fraga]

Aankhen <aankhen@gmail.com> writes:

[...]

> Thank you for the clarifications.  I’m going to talk a bit more about
> HTML as that’s where I have the most experience.  I am in agreement
> with you when you say that builtin support for acronyms would be
> useful (although I feel it would be good to generalize it to
> abbreviations, if that can also be supported in other backends).  When
> you have the following markup:
>
> ,----
> | <acronym title="Hypertext Markup Language">HTML</acronym> is a
> | language for marking up documents.  The most current version
> | of <acronym title="Hypertext Markup Language">HTML</acronym> is 4.01.
> | The successor to <acronym title="Hypertext Markup
> | Language">HTML</acronym>, HTML5, is currently under development.
> `----
>
> The expansion is invisible by default; it shows up in a tooltip when
> you hover over the text.  You can try a live example to see for
> yourself.[1] In this way, the expansion is always there when you need
> it (and you can distinguish between multiple terms sharing the same
> acronym, should the need ever arise), but it takes up no space if you
> don’t.

There are those of us that, for one reason or another, do *not* use a
mouse or any other graphical pointer.  Tooltips do not appear ever in
those cases.  I would like a solution that does not rely on any
particular graphical interface paradigm, basically!

Of course, I know that I am in the minority here... but accessibility is
always an important factor and one that should not be ignored, IMO.

> I would suggest that, were Org to gain support for acronyms and/or
> abbreviations, they be exported in HTML using ‘abbr’ (‘acronym’ is
> deprecated thanks to HTML5) with the ‘title’ defined for each
> occurrence, and with CSS to ensure consistent rendering, along these
> lines:
>
> ,----
> | abbr { font-variant: small-caps; border-bottom: 1px dashed; cursor: help; }
> `----

Does this still rely on tooltips?

> I can see the argument for having a list at the end and linking each
> definition instead.  I feel that’s less convenient, however, as (a) it
> means temporarily losing your place in the document and (b) bunched-up
> anchors at the end of a document are a pain.  Of course,
> alternatively, each acronym/abbreviation could be marked up only at
> the first occurrence; that seems like it would be easy to implement as
> a configuration option.

I would like a combination of both, whenever possible: fully expanded
def'n in the text at the first occurrence and links to the list of
abbreviations/acronyms at the end for subsequent occurrences (modulo the
problems with double-links etc, for which I cannot propose a solution
unfortunately).

Thanks,
eric

-- 
: Eric S Fraga (GnuPG: 0xC89193D8FFFCF67D) in Emacs 24.0.50.1
: using Org-mode version 7.5 (release_7.5.134.gb869b)

New features for the exporters?

[Sébastien Vauban]

Hi Eric, Aankhen and al.,

Just answering very quickly on one sole idea of the exchanged ones in this
thread:

Eric S Fraga wrote:
> Aankhen <aankhen-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>> The expansion is invisible by default; it shows up in a tooltip when you
>> hover over the text. You can try a live example to see for yourself.[1] In
>> this way, the expansion is always there when you need it (and you can
>> distinguish between multiple terms sharing the same acronym, should the
>> need ever arise), but it takes up no space if you don’t.
>
> There are those of us that, for one reason or another, do *not* use a mouse
> or any other graphical pointer. Tooltips do not appear ever in those cases.
> I would like a solution that does not rely on any particular graphical
> interface paradigm, basically!
>
> Of course, I know that I am in the minority here... but accessibility is
> always an important factor and one that should not be ignored, IMO.

I don't think you're part of the minority. Anyway, there are good reasons to
have tooltips (on a wish-basis), but other good reasons to have the list of
acronyms at the end of the document (on a wish-basis): to get a readable and
very accessible document when printed!

Best regards,
  Seb

-- 
Sébastien Vauban

Re: Re: unnumbered subsections in latex export

[Aankhen]

On Wed, Apr 6, 2011 at 00:57, Eric S Fraga <e.fraga@ucl.ac.uk> wrote:
> Aankhen <aankhen@gmail.com> writes:
>
> [...]
>
>> Thank you for the clarifications.  I’m going to talk a bit more about
>> HTML as that’s where I have the most experience.  I am in agreement
>> with you when you say that builtin support for acronyms would be
>> useful (although I feel it would be good to generalize it to
>> abbreviations, if that can also be supported in other backends).  When
>> you have the following markup:
>>
>> ,----
>> | <acronym title="Hypertext Markup Language">HTML</acronym> is a
>> | language for marking up documents.  The most current version
>> | of <acronym title="Hypertext Markup Language">HTML</acronym> is 4.01.
>> | The successor to <acronym title="Hypertext Markup
>> | Language">HTML</acronym>, HTML5, is currently under development.
>> `----
>>
>> The expansion is invisible by default; it shows up in a tooltip when
>> you hover over the text.  You can try a live example to see for
>> yourself.[1] In this way, the expansion is always there when you need
>> it (and you can distinguish between multiple terms sharing the same
>> acronym, should the need ever arise), but it takes up no space if you
>> don’t.
>
> There are those of us that, for one reason or another, do *not* use a
> mouse or any other graphical pointer.  Tooltips do not appear ever in
> those cases.  I would like a solution that does not rely on any
> particular graphical interface paradigm, basically!
>
> Of course, I know that I am in the minority here... but accessibility is
> always an important factor and one that should not be ignored, IMO.

Yes, I absolutely understand the concern, and I must confess I had
overlooked it.  I’m not certain how text-based browsers deal with
‘title’ attributes in general.  I see that Lynx, for one, can make use
of them on links.[1] Unfortunately, I can’t find any material on other
text mode browsers.  Everything I read points at them mostly ignoring
‘title’.  Ideally, text mode browsers would provide a way to get at
it, as there is nothing tying the attribute to a graphical interface;
in practice, it would seem that they took the easy way out.
Understandable, given the rampant abuse of the tag.

>
>> I would suggest that, were Org to gain support for acronyms and/or
>> abbreviations, they be exported in HTML using ‘abbr’ (‘acronym’ is
>> deprecated thanks to HTML5) with the ‘title’ defined for each
>> occurrence, and with CSS to ensure consistent rendering, along these
>> lines:
>>
>> ,----
>> | abbr { font-variant: small-caps; border-bottom: 1px dashed; cursor: help; }
>> `----
>
> Does this still rely on tooltips?

Yes.  This CSS is only meant to standardize the presentation across
graphical browsers.  It is entirely possible to use CSS to display the
expansion, I’m just not sure of the utility (and it relies on the
browser not throwing away CSS):

,----
| abbr[title]:after, acronym[title]:after { content: " [" attr(title) "]"; }
`----

It defeats the purpose of the exercise in any case.

>> I can see the argument for having a list at the end and linking each
>> definition instead.  I feel that’s less convenient, however, as (a) it
>> means temporarily losing your place in the document and (b) bunched-up
>> anchors at the end of a document are a pain.  Of course,
>> alternatively, each acronym/abbreviation could be marked up only at
>> the first occurrence; that seems like it would be easy to implement as
>> a configuration option.
>
> I would like a combination of both, whenever possible: fully expanded
> def'n in the text at the first occurrence and links to the list of
> abbreviations/acronyms at the end for subsequent occurrences (modulo the
> problems with double-links etc, for which I cannot propose a solution
> unfortunately).

Taking into consideration the fact that text-based browsers seem to
ignore ‘title’, I can only agree with you.  How about something like
this:

,----
| <p>I’m going to introduce a new <abbr>TLA</abbr> (Three-Letter
| Acronym).  This <a href="#abbr-TLA">TLA</a> is a very
| special <a href="#abbr-TLA">TLA</a> as it comes straight from my
| heart.
| ⋮
| <h2>Acronyms &amp; abbreviations</h2>
| <dl>
|   <dt id="abbr-TLA">TLA
|   <dd>Three-Letter Acronym
|   <dt id="abbr-YAAA">YAAA
|   <dd>Yet Another Alliterative Acronym
|   <dt id="abbr-Dr">Dr.
|   <dd>Doctor
| </dl>
`----

In case of a nested link, maybe a break in the outer link could solve it:

,----
| Let us read <a href="http://www.w3.org/TR/html401/">the
| HTML</a><sup><a href="#abbr-HTML">[def]</a></sup><a
href="http://www.w3.org/TR/html401/">
| specification</a> together.
`----

Not particularly pretty, but it seems to get the job done.  Just one option.

At any rate, thanks for pointing this out.

Aankhen

[1]: http://diveintoaccessibility.org/day_14_adding_titles_to_links.html

Re: unnumbered subsections in latex export

[Matt Lundin]

Sébastien Vauban <wxhgmqzgwmuf-geNee64TY+gS+FvcfC7Uqw@public.gmane.org>
writes:
>
> When discussing exporters and features, two things that come up to my
> mind as missing as a "general Org feature":
>
> - bibliography :: works for LaTeX[1], not for HTML export.

Have you tried the contributed module org-exp-bibtex.el? It is not a
self-contained org-mode module, in that it relies on bibtex2html and an
external bibtex file, but it does enable bibliographical export to html.

> - acronyms :: idem.

> I want to be able to say, in my Org file, that DNS is an acronym, for
> example. I'm thinking -- brainstorming! -- at a solution _such as_
> adding accolades around the acronyms:

> This paper talks about {DNS} clients and {DNS} servers...

> In LaTeX, this should have to be translated to:

> This paper talks about \acro{DNS} clients and \acro{DNS} servers...

One way to accommodate acronyms would be to create a new link type:

(org-add-link-type
 "acro" nil
 (lambda (path desc format)
   (cond 
    ((eq format 'latex)
     (format "\\acro{%s}{%s}" path desc))
    ((eq format 'html)
     (format "<acronym title=\"%s\">%s</acronym>" desc path)))))

A link such as...

[[acro:DNS][Domain Name System]]

...would then export to latex as...

\acro{DNS}{Domain Name System}

...and to html as...

<acronym title="Domain Name System">DNS</acronym>

Having never used acronyms in LaTeX or html before, I have no idea
whether the above syntax is correct. The point is simply to offer a
proof of concept.

Best,
Matt

Re: unnumbered subsections in latex export

[Sébastien Vauban]

Hi Matt,

Matt Lundin wrote:
> Sébastien Vauban writes:
>>
>> When discussing exporters and features, two things that come up to my mind
>> as missing as a "general Org feature":
>>
>> - bibliography :: works for LaTeX[1], not for HTML export.
>
> Have you tried the contributed module org-exp-bibtex.el? It is not a
> self-contained org-mode module, in that it relies on bibtex2html and an
> external bibtex file, but it does enable bibliographical export to html.

Did not know about it. Will give it a try. Thanks.

>> - acronyms :: idem.
>
>> I want to be able to say, in my Org file, that DNS is an acronym, for
>> example. I'm thinking -- brainstorming! -- at a solution _such as_ adding
>> accolades around the acronyms:
>
>> This paper talks about {DNS} clients and {DNS} servers...
>
>> In LaTeX, this should have to be translated to:
>
>> This paper talks about \acro{DNS} clients and \acro{DNS} servers...
>
> One way to accommodate acronyms would be to create a new link type:
>
> (org-add-link-type
>  "acro" nil
>  (lambda (path desc format)
>    (cond 
>     ((eq format 'latex)
>      (format "\\acro{%s}{%s}" path desc))
>     ((eq format 'html)
>      (format "<acronym title=\"%s\">%s</acronym>" desc path)))))
>
> A link such as...
>
> [[acro:DNS][Domain Name System]]
>
> ...would then export to latex as...
>
> \acro{DNS}{Domain Name System}
>
> ...and to html as...
>
> <acronym title="Domain Name System">DNS</acronym>
>
> Having never used acronyms in LaTeX or html before, I have no idea
> whether the above syntax is correct. The point is simply to offer a
> proof of concept.

This is clearly interesting, and maybe part of the final solution. However,
one of the point is that we should be able to:

- define once that DNS = Domain Name System
- have all occurrences of DNS automagically pointing to its definition
- (optionnally) have the first occurrence of DNS automagically expanded.

(I guess that) the above does not meet this, and that's what made my spirit go
in the direction of pre-processing.

But maybe alternatives do exist to meet those "requirements".

Best regards,
  Seb

-- 
Sébastien Vauban