Re: [O] [patch, ox] Unnumbered headlines

2014-10-05 Thread Nicolas Goaziou 
Hello,

Rasmus ras...@gmx.us writes:

 Then there's 12. Exporting, where I guess the closest fitting section
 is 12.3 Export settings.

 Any opinions? 

I think section 12.3 is fine, as an additional paragraph within the num:
entry.


Regards,

-- 
Nicolas Goaziou

Re: [O] [patch, ox] Unnumbered headlines

2014-10-03 Thread Nicolas Goaziou 
Hello,

Rasmus ras...@gmx.us writes:

 Alan did some testing on a slightly older version of this patch and he
 managed to publish his book without errors and with working links.  So
 let's give it another shot.

 I briefly tested the output of LaTeX, html, texinfo, odt, md, and
 plaintext and made sure links work and that the right text is shown in
 the output.

Thanks. It looks mostly good. Some minor comments follow.

 I think the following is more in the spirit of the code (you don't
 ignore :custom-id property):

   (ids (delq nil
  (list (org-element-property :CUSTOM_ID headline)
(org-export-get-headline-id headline info)
(org-element-property :ID headline
   (preferred-id (car ids))

 But we are not checking that :CUSTOM_ID is unique.

This is not our problem, but user's.

 In ox-latex you're required to turn on a variable on to get this
 behavior (I could be mistaken here). For now I have done as you
 suggest. But I don't understand why we are favoring CUSTOM_ID here
 over the nice, unique label we've generated?

We could do the same as ox-latex, default to generated label, and
optionally allow users to use raw custom-id instead (with usual caveat).

Meanwhile, I think it is reasonable to stick to the current behaviour.

 Last line:

   (list headline (incf num))

 Oh incf is quite handy.  Didn't know that one.

 I leave it as (cons headline (list (incf num))).  Why?  'Cause that's
 the format used by `org-export--collect-headline-numbering'.  While
 simpler is nicer, I think it's better not to have to consider
 different data structures depending on whether data is from
 `org-export--collect-headline-numbering' or
 `org-export--collect-unnumbered-headline-id'.

I don't get your point. (cons 'a (list 'b)) is equivalent to (list 'a
'b). Why do you think this changes the data structure?

   (unless (org-some
(lambda (h) (org-not-nil (org-element-property :UNNUMBERED h)))
(org-export-get-genealogy headline))
 ...)

 Handy.  AFAIK BLOB is not a member of (org-export-get-genealogy BLOB)
 (or so the output suggests), so (or · ·) is still needed.

I think

  (org-some (lambda (h) ...)
(cons headline (org-export-get-genealogy headline)))

is more elegant.

 +   ;; headline linked via CUSTOM_ID

  ;; Headline linked via CUSTOM_ID.

 +   (or (and (string= type custom-id)
 +(org-element-property :CUSTOM_ID destination))
 +   (org-export-get-headline-id destination info)
 +   (t (error Shouldn't reach here
;; What description to use?
(desc
 ;; Case 1: Headline is numbered and LINK has no
 @@ -3073,13 +3063,16 @@ holding contextual information.
(let* ((class-num (+ (org-export-get-relative-level parent info)
  (1- (plist-get info :html-toplevel-hlevel
(section-number
 -   (mapconcat
 -'number-to-string
 -(org-export-get-headline-number parent info) -)))
 +   (and (org-export-numbered-headline-p parent info)
 +(mapconcat
 + 'number-to-string

Nitpick: #'number-to-string

 +  ;; Test if destination is a numbered headline

Missing full stop.

 +  (let ((num 0))
 +(org-element-map data 'headline
 + (lambda (headline)
 +   (unless (org-export-numbered-headline-p headline options)
 + (cons headline (list (incf num

See above.

 +  (unless
 +  (or (org-element-property :UNNUMBERED headline)
 +   (org-some (lambda (head) (org-not-nil (org-element-property 
 :UNNUMBERED head)))
 + (org-export-get-genealogy headline)))
 +(let ((sec-num (plist-get info :section-numbers))
 +   (level (org-export-get-relative-level headline info)))
 +  (if (wholenump sec-num) (= level sec-num) sec-num

Per above

  (unless (org-some
   (lambda (h) (org-not-nil (org-element-property :UNNUMBERED h)))
   (cons headline (org-export-get-genealogy headline)))
...)

 +(ert-deftest test-org-export/org-export-get-headline-id ()
 +  Test `org-export-get-headline-id' specifications.
 +  (should
 +   (equal sec-1
 +   (org-test-with-parsed-data * Headline
 + (org-export-get-headline-id
 +  (org-element-map tree 'headline 'identity info t)
 +  info
 +  (should
 +   (equal unnumbered-1
 +   (org-test-with-parsed-data * Headline\n:PROPERTIES:\n:UNNUMBERED: 
 t\n:END:
 + (org-export-get-headline-id
 +  (org-element-map tree 'headline 'identity info t)
 +  info
 +  (should
 +   (equal unnumbered-1
 +   (org-test-with-parsed-data * Headline\n#+OPTIONS: num:nil
 + (org-export-get-headline-id
 +  (org-element-map tree 'headline 'identity info t)
 +  info)

I suggest to also test tricky inherited UNNUMBERED properties

  * H

Re: [O] [patch, ox] Unnumbered headlines

2014-10-03 Thread Sebastien Vauban 
Nicolas Goaziou wrote:
 +  ;; Test if destination is a numbered headline

 Missing full stop.

Small question about conventions for writing comments... Can I consider
the following to be the rule?

- If it's a *sentence* (like the above example, in the imperative form),
  begin with a capital and end with a dot.
  
- Otherwise (like ;; pattern found), begin with a small letter and
  don't end with a dot.

?

Tips on writing comments found on
https://www.gnu.org/software/emacs/manual/html_node/elisp/Comment-Tips.html
aren't very helpful IMHO, as you see things such as:

- ; there was there was a base version to which this looks like
  a subversion, that is a sentence with no capital nor dot...

- ;; Update mode line., that is a sentence with both beginning capital
  and to.

-  The kill ring, an expression with a capital...

That page seems to be more on the usage of ;, ;;, ;;; and 
than on the usage of capitals and dots.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [O] [patch, ox] Unnumbered headlines

2014-10-03 Thread Rasmus 
Hi,

Now odt output doesn't look ugly.  I fixed the other things you
mentioned.  Make test passes.


Nicolas Goaziou m...@nicolasgoaziou.fr writes:

 But we are not checking that :CUSTOM_ID is unique.

 This is not our problem, but user's.

 In ox-latex you're required to turn on a variable on to get this
 behavior (I could be mistaken here). For now I have done as you
 suggest. But I don't understand why we are favoring CUSTOM_ID here
 over the nice, unique label we've generated?

 We could do the same as ox-latex, default to generated label, and
 optionally allow users to use raw custom-id instead (with usual caveat).

 Meanwhile, I think it is reasonable to stick to the current behaviour.


Fine with me.  Maybe some other day. . .

 I don't get your point. (cons 'a (list 'b)) is equivalent to (list 'a
 'b). Why do you think this changes the data structure?

Right.  No point. 

   (org-some (lambda (h) ...)
 (cons headline (org-export-get-genealogy headline)))

 is more elegant.

That's true.


 I suggest to also test tricky inherited UNNUMBERED properties

Added.

—Rasmus

-- 
Vote for proprietary math!
From 75309757d30c9920077d1ec82a61713830cb4888 Mon Sep 17 00:00:00 2001
From: Rasmus ras...@gmx.us
Date: Sun, 21 Sep 2014 16:17:55 +0200
Subject: [PATCH] ox: Support unnumbered headlines via property.

* ox.el (org-export--collect-headline-numbering): Ignore unnumbered headline.
(org-export-get-headline-id,
org-export--collect-unnumbered-headline-id): New functions.
(org-export-numbered-headline-p): Further tests for unnumbered headline.
* ox-odt.el (org-odt-headline, org-odt-link,
org-odt-link--infer-description)
ox-md.el (org-md-headline, org-md-link),
ox-latex.el (org-latex-headline, org.latex-link),
ox-html.el (org-html-headline, org-html-link),
ox-ascii.el (org-ascii-link): Support ununbered headlines.
* test-ox.el (test-org-export/org-export-get-headline-id): New test.
* OrgOdtStyles.xml: Add styles for unnumbered headings.
---
 etc/styles/OrgOdtStyles.xml | 19 ++
 lisp/org.el |  2 +-
 lisp/ox-ascii.el|  8 --
 lisp/ox-html.el | 40 +
 lisp/ox-latex.el| 23 +
 lisp/ox-md.el   | 24 ++
 lisp/ox-odt.el  | 46 -
 lisp/ox.el  | 52 +++--
 testing/lisp/test-ox.el | 62 +
 9 files changed, 191 insertions(+), 85 deletions(-)

diff --git a/etc/styles/OrgOdtStyles.xml b/etc/styles/OrgOdtStyles.xml
index f41d984..a164335 100644
--- a/etc/styles/OrgOdtStyles.xml
+++ b/etc/styles/OrgOdtStyles.xml
@@ -109,34 +109,53 @@
   /style:style
   style:style style:name=Heading_20_1 style:display-name=Heading 1 style:family=paragraph style:parent-style-name=Heading style:next-style-name=Text_20_body style:default-outline-level=1 style:class=text
style:text-properties fo:font-size=115% fo:font-weight=bold style:font-size-asian=115% style:font-weight-asian=bold style:font-size-complex=115% style:font-weight-complex=bold/
+   style:style style:name=Heading_20_1_unnumbered style:family=paragraph style:parent-style-name=Heading_20_1 style:list-style-name=
   /style:style
   style:style style:name=Heading_20_2 style:display-name=Heading 2 style:family=paragraph style:parent-style-name=Heading style:next-style-name=Text_20_body style:default-outline-level=2 style:class=text
style:text-properties fo:font-size=14pt fo:font-style=italic fo:font-weight=bold style:font-size-asian=14pt style:font-style-asian=italic style:font-weight-asian=bold style:font-size-complex=14pt style:font-style-complex=italic style:font-weight-complex=bold/
   /style:style
+style:style style:name=Heading_20_2_unnumbered style:family=paragraph style:parent-style-name=Heading_20_2 style:list-style-name=
+  /style:style
   style:style style:name=Heading_20_3 style:display-name=Heading 3 style:family=paragraph style:parent-style-name=Heading style:next-style-name=Text_20_body style:default-outline-level=3 style:class=text
style:text-properties fo:font-size=14pt fo:font-weight=bold style:font-size-asian=14pt style:font-weight-asian=bold style:font-size-complex=14pt style:font-weight-complex=bold/
   /style:style
+style:style style:name=Heading_20_3_unnumbered style:family=paragraph style:parent-style-name=Heading_20_3 style:list-style-name=
+  /style:style
   style:style style:name=Heading_20_4 style:display-name=Heading 4 style:family=paragraph style:parent-style-name=Heading style:next-style-name=Text_20_body style:default-outline-level=4 style:class=text
style:text-properties fo:font-size=85% fo:font-style=italic fo:font-weight=bold style:font-size-asian=85% style:font-style-asian=italic style:font-weight-asian=bold style:font-size-complex=85% style:font-style-complex=italic style:font-weight-complex=bold/
   /style:style
+style:style

Re: [O] [patch, ox] Unnumbered headlines

2014-10-03 Thread Nicolas Goaziou 
Hello,

Rasmus ras...@gmx.us writes:

 Now odt output doesn't look ugly.  I fixed the other things you
 mentioned.  Make test passes.

Applied. Thank you very much.

Now, some documentation would be nice.


Regards,

-- 
Nicolas Goaziou

Re: [O] [patch, ox] Unnumbered headlines

2014-10-03 Thread Rasmus 
Nicolas Goaziou m...@nicolasgoaziou.fr writes:

 Hello,

 Rasmus ras...@gmx.us writes:

 Now odt output doesn't look ugly.  I fixed the other things you
 mentioned.  Make test passes.

 Applied. Thank you very much.

Thanks.  Bastien added my key to org-git today, so hopefully you'll be
spared of this in the future.

 Now, some documentation would be nice.

Yeah.  I wans't sure where to put it.

There's

7. Properties and Columns: Storing information about an entry

But this doesn't seem export specific.  E.g.  CUSTOMID is not in the
sec. 7.2 table.

Then there's 12. Exporting, where I guess the closest fitting section
is 12.3 Export settings.

Any opinions? 

—Rasmus

-- 
Lasciate ogni speranza o voi che entrate: siete nella mani di'machellaio

Re: [O] [patch, ox] Unnumbered headlines

2014-10-01 Thread Rasmus 
[Cloud-note to self (probably) or, preferably, someone else]

One deficit of unnumbered headlines in odt is that they are
indented.  This looks dumb!  Here's some notes on how I think is the
best way to get rid of the indention in ox-odt.

If this bothers someone, please go ahead and fix it!  Otherwise I
might look at it eventually. . .

Alan L Tyree alanty...@gmail.com writes:

 Also interesting [to note on unnumbered headlines in LO]: right
 click on the unnumbered headline. Go to Bullets and Numbering. Click
 on 'Remove' at the bottom and the headline jumps back into proper
 alignment.

Arh, so indention for unnumbered headlines can be removed!

Studying the xml files of LO it seems the mechanism is something like
this.  Basically, to get an unnumbered headline you have to specify it
as a list header.  This is what the current patch does and how LO does
it.  But the indention is caused by the fact that it's a list
header. To get rid of the indention one has to specify the list style
to be the empty style  (empty quote). . .

So, for unnumbered headlines, append text:is-list-header=true to the
text:h specification.  Example: 

text:h text:style-name=Heading_20_1 text:outline-level=1 
text:is-list-header=trueheadline/text:h

To get it unindented we need to add

style:list-style-name=

To the style.  LO does this by generating PN, N is an int, styles on
the fly that are derived from Heading styles:

style:style style:name=P2 style:family=paragraph 
style:parent-style-name=Heading_20_1 style:list-style-name=/

In Org, I think the easiest thing to do would be to add these styles
to the styles.xml file and choose the right style based on whether
headline is numbered or not numbered. . .  Unfortunately, it seems we
cannot just add style:list-style-name= to the end of the style
definition of Heading_20_N as this kills the number.

—Rasmus

-- 
Dobbelt-A

Re: [O] [patch, ox] Unnumbered headlines

2014-09-30 Thread Rasmus 
Hi,

Alan did some testing on a slightly older version of this patch and he
managed to publish his book without errors and with working links.  So
let's give it another shot.

I briefly tested the output of LaTeX, html, texinfo, odt, md, and
plaintext and made sure links work and that the right text is shown in
the output.

Nicolas Goaziou m...@nicolasgoaziou.fr writes:

 Should I write tests for the new behavior?  If so, tests for each
 backend or only for vanilla-ox functions?

 Tests for ox.el are mandatory. See test-ox.el

I have added some.  I don't know if it's comprehensive enough.  It was
not obvious to me what to test.


 (ids (delq nil
(list (org-element-property :CUSTOM_ID headline)
 -(concat sec- section-number)
 +(and section-number (concat sec- 
 section-number))
  (org-element-property :ID headline
 -   (preferred-id (car ids))
 +   (preferred-id (org-export-get-headline-id headline info))

 I think the following is more in the spirit of the code (you don't
 ignore :custom-id property):

   (ids (delq nil
  (list (org-element-property :CUSTOM_ID headline)
(org-export-get-headline-id headline info)
(org-element-property :ID headline
   (preferred-id (car ids))

But we are not checking that :CUSTOM_ID is unique.  In ox-latex you're
required to turn on a variable on to get this behavior (I could be
mistaken here).  For now I have done as you suggest.  But I don't
understand why we are favoring CUSTOM_ID here over the nice, unique
label we've generated?

 -   (let ((href ..
 (headline-label ...
 -  (org-html--anchor ...

I reintroduced the CUSTOM_ID in these.


 +  (let ((num 0))
 +(org-element-map data 'headline
 +(lambda (headline)
 +  (unless (org-export-numbered-headline-p headline options)
 +(cons headline (list (setq num (1+ num)

 Last line:

   (list headline (incf num))

Oh incf is quite handy.  Didn't know that one.

I leave it as (cons headline (list (incf num))).  Why?  'Cause that's
the format used by `org-export--collect-headline-numbering'.  While
simpler is nicer, I think it's better not to have to consider
different data structures depending on whether data is from
`org-export--collect-headline-numbering' or
`org-export--collect-unnumbered-headline-id'.

If you feel the simpler structure is better we can also use that.

 Use `assq' instead of `assoc'.

Right, no need for equal here.

 +(defun org-export-get-unnumberd-headline-id (headline info)
 +  Return unnumbered HEADLINE id as list of numbers.
  INFO is a plist holding contextual information.
 -  (cdr (assoc headline (plist-get info :headline-numbering
 +  (and (not (org-export-numbered-headline-p headline info))
 +   (cdr (assoc headline (plist-get info :unnumbered-headline-id)

 I don't think it is worth to make this function standalone. I don't see
 any use case outside `org-export-get-headline-id'. I suggest to move it
 there.

Yeah, seems fair.

 +  (unless
 +  (or (org-export-get-node-property :UNNUMBERED headline)
 +  (loop for parent in (org-export-get-genealogy headline)
 +when (org-export-get-node-property :UNNUMBERED parent)
 +return t))

   (unless (org-some
(lambda (h) (org-not-nil (org-element-property :UNNUMBERED h)))
(org-export-get-genealogy headline))
 ...)

Handy.  AFAIK BLOB is not a member of (org-export-get-genealogy BLOB)
(or so the output suggests), so (or · ·) is still needed.


Thanks again,
Rasmus

--
There are known knowns; there are things we know that we know
From e25b297d285b31fd8a842356aa5818d303b4dec9 Mon Sep 17 00:00:00 2001
From: Rasmus ras...@gmx.us
Date: Sun, 21 Sep 2014 16:17:55 +0200
Subject: [PATCH] ox: Support unnumbered headlines via property.

* ox.el (org-export--collect-headline-numbering): Ignore unnumbered headline.
(org-export-get-headline-id,
org-export--collect-unnumbered-headline-id): New functions.
(org-export-numbered-headline-p): Further tests for unnumbered headline.
* ox-odt.el (org-odt-headline, org-odt-link,
org-odt-link--infer-description)
ox-md.el (org-md-headline, org-md-link),
ox-latex.el (org-latex-headline, org.latex-link),
ox-html.el (org-html-headline, org-html-link),
ox-ascii.el (org-ascii-link): Support ununbered headlines.
* test-ox.el (test-org-export/org-export-get-headline-id): New test.
---
 lisp/org.el |  2 +-
 lisp/ox-ascii.el|  8 ++--
 lisp/ox-html.el | 39 +++--
 lisp/ox-latex.el| 23 ++
 lisp/ox-md.el   | 24 +--
 lisp/ox-odt.el  | 39 +
 lisp/ox.el  | 52 +
 testing/lisp/test-ox.el | 21 
 8 files

Re: [O] [patch, ox] Unnumbered headlines

2014-09-27 Thread Nicolas Goaziou 
Hello,

Rasmus ras...@gmx.us writes:

 Thanks for all time you've put into the comments.  I appreciate it,
 and I will try to revise the patches over the weekend.

Thanks. Again, there's no rush.

 I worry about this approach based on some observations Alan sent
 off-list.  When you export the quoted document with num:nil all labels
 will be of the form unnumbered-N, loosing all structure in labels.

I don't think how that would be a problem. A label is expected to refer
uniquely to a headline. Reflecting structure of the document is not
a requisite. sec-NUM is but a bonus. As far as labels go, we could
also use headline-X for all headlines, numbered or not.

 Also, some labels are still unassigned in html for unnumbered
 headlines, e.g. the text- (which is a function of parents' section
 numbers) and outline-container-sec-.

Couldn't they be turned into text-unnumbered-X and
outline-container-unnumbered-X instead?

 Do you think it's better to solve the remaining issues, and accept
 that when num:nil exported documents will be quite altered compared to
 previously, or should I try to introduce a more informative ID for
 numbered an unnumbered headlines alike?

The former.

 If following the latter path, the most obvious approach (to me) would
 be to have a separate :headline-id
 and :headline-numbering.  :headline-id could be collected using
 something like `org-export--collect-headline-numbering', but labels
 would not necessarily reflect the printed section numbers,
 though :headline-numbering would still be correct.

I think we don't need this added complexity.


Regards,

-- 
Nicolas Goaziou

Re: [O] [patch, ox] Unnumbered headlines

2014-09-26 Thread Nicolas Goaziou 
Hello,

Rasmus ras...@gmx.us writes:

 Another couple of small changes.

Thank you.

 Using this file:

 * h1
 :PROPERTIES:
 :CUSTOM_ID: h1
 :END:
 ** h2
 :PROPERTIES:
 :unnumbered: t
 :CUSTOM_ID: h2
 :END:
 *** h3
 *** h4
 * h5
 :PROPERTIES:
 :CUSTOM_ID: h5
 :END:
 [[*h1]] [[#h2]] [[*h4]] [[#h5]]
 ** h6

 The output is now

 \section{h1}
 \label{sec-1}
 \subsection*{h2}
 \label{unnumbered-1}
 \subsubsection*{h3}
 \label{unnumbered-2}
 \subsubsection*{h4}
 \label{unnumbered-3}
 \section{h5}
 \label{sec-2}
 \ref{sec-1} \hyperref[unnumbered-1]{h2} \hyperref[unnumbered-3]{h4} 
 \ref{sec-2}
 \subsection{h6}
 \label{sec-2-1}

 Which I think is quite good.

I agree.

 I don't know if the global unnumbered counter is made in the best way.
 I add another plist to info with the number.  This approach is cleaner
 than before since it's the numbering of unnumbered headlines is not in
 `org-export--collect-headline-numbering' which is complicated enough
 as it is.

14 locs long functions do not play in the complicated enough league.
Anyway, your implementation is fine, too.

 Should I write tests for the new behavior?  If so, tests for each
 backend or only for vanilla-ox functions?

Tests for ox.el are mandatory. See test-ox.el

 * ox.el (org-export--collect-headline-numbering): Return nil
 if unnumbered headline.

This is not exactly true: Ignore unnumbered headlines. would be more
appropriate.

 (org-export-get-headline-id): New defun that returns a unique
 ID to a headline.

New function. is enough.

 +   (if number
   (if (atom number) (number-to-string number)
 -   (mapconcat 'number-to-string number .
 +   (mapconcat 'number-to-string number .))
 + ;; unnumbered headline
 + (when (eq 'headline (org-element-type destination))
 +   (format [%s] (org-export-data (org-element-property :title 
 destination) info)

While you're at it: #'number-to-string.

 (ids (delq nil
(list (org-element-property :CUSTOM_ID headline)
 -(concat sec- section-number)
 +(and section-number (concat sec- 
 section-number))
  (org-element-property :ID headline
 -   (preferred-id (car ids))
 +   (preferred-id (org-export-get-headline-id headline info))

I think the following is more in the spirit of the code (you don't
ignore :custom-id property):

  (ids (delq nil
 (list (org-element-property :CUSTOM_ID headline)
   (org-export-get-headline-id headline info)
   (org-element-property :ID headline
  (preferred-id (car ids))

 (extra-ids (mapconcat
 (lambda (id)
   (org-html--anchor
 @@ -2807,21 +2807,7 @@ INFO is a plist holding contextual information.  See
   (org-element-property :raw-link link) info
 ;; Link points to a headline.
 (headline
 -(let ((href
 -   ;; What href to use?
 -   (cond
 -;; Case 1: Headline is linked via it's CUSTOM_ID
 -;; property.  Use CUSTOM_ID.
 -((string= type custom-id)
 - (org-element-property :CUSTOM_ID destination))
 -;; Case 2: Headline is linked via it's ID property
 -;; or through other means.  Use the default href.
 -((member type '(id fuzzy))
 - (format sec-%s
 - (mapconcat 'number-to-string
 -(org-export-get-headline-number
 - destination info) -)))
 -(t (error Shouldn't reach here
 +(let ((href (org-export-get-headline-id destination info))

This chuck needs to be updated since headline-id doesn't
replace :custom-id or :id properties.

  (headline-label
 - (let ((custom-label
 -(and (plist-get info :latex-custom-id-labels)
 - (org-element-property :CUSTOM_ID headline
 -   (if custom-label (format \\label{%s}\n custom-label)
 - (format \\label{sec-%s}\n
 - (mapconcat
 -  #'number-to-string
 -  (org-export-get-headline-number headline info)
 -  -)
 + (format \\label{%s}\n (org-export-get-headline-id headline info)))

Ditto.

 -   (org-html--anchor
 -(or (org-element-property :CUSTOM_ID headline)
 -(concat sec-
 -(mapconcat 'number-to-string
 -   (org-export-get-headline-number
 -headline info) -)))
 +   (org-html--anchor

Re: [O] [patch, ox] Unnumbered headlines

2014-09-26 Thread Rasmus 
Hi Nicolas,

Thanks for all time you've put into the comments.  I appreciate it,
and I will try to revise the patches over the weekend.

Nicolas Goaziou m...@nicolasgoaziou.fr writes:

 Using this file:

 * h1
 :PROPERTIES:
 :CUSTOM_ID: h1
 :END:
 ** h2
 :PROPERTIES:
 :unnumbered: t
 :CUSTOM_ID: h2
 :END:
 *** h3
 *** h4
 * h5
 :PROPERTIES:
 :CUSTOM_ID: h5
 :END:
 [[*h1]] [[#h2]] [[*h4]] [[#h5]]
 ** h6

 The output is now

 \section{h1}
 \label{sec-1}
 \subsection*{h2}
 \label{unnumbered-1}
 \subsubsection*{h3}
 \label{unnumbered-2}
 \subsubsection*{h4}
 \label{unnumbered-3}
 \section{h5}
 \label{sec-2}
 \ref{sec-1} \hyperref[unnumbered-1]{h2}
 \hyperref[unnumbered-3]{h4} \ref{sec-2}
 \subsection{h6}
 \label{sec-2-1}

 Which I think is quite good.

 I agree.

I worry about this approach based on some observations Alan sent
off-list.  When you export the quoted document with num:nil all labels
will be of the form unnumbered-N, loosing all structure in labels.

Also, some labels are still unassigned in html for unnumbered
headlines, e.g. the text- (which is a function of parents' section
numbers) and outline-container-sec-.

Do you think it's better to solve the remaining issues, and accept
that when num:nil exported documents will be quite altered compared to
previously, or should I try to introduce a more informative ID for
numbered an unnumbered headlines alike?

If following the latter path, the most obvious approach (to me) would
be to have a separate :headline-id
and :headline-numbering.  :headline-id could be collected using
something like `org-export--collect-headline-numbering', but labels
would not necessarily reflect the printed section numbers,
though :headline-numbering would still be correct.

What do you think?

—Rasmus

-- 
. . . It begins of course with The Internet.  A Net of Peers

Re: [O] [patch, ox] Unnumbered headlines

2014-09-22 Thread Nicolas Goaziou 
Hello,

Rasmus ras...@gmx.us writes:

 With the last patch it gets weird when you have mixed trees, like this:

 * numbered
 ** unnumbered 
 :PROPERTIES:
 :UNNUMBERED: t
 :END:

 The LaTeX output is:

 \section{numbered}
 \label{sec-1}
 \subsection*{unnumbered}
 \label{unnumbered-sec-0-1}

 Perhaps it would be nicer to use a single counter rather than two?
 Right now, this

 * numbered1
 * unnumbered2 
 :PROPERTIES:
 :UNNUMBERED: t
 :END:
 * numbered2
 * unnumbered2
 :PROPERTIES:
 :UNNUMBERED: t
 :END:

 produces

 \section{numbered1}
 \label{sec-1}
 \section*{unnumbered2}
 \label{unnumbered-sec-1}
 \section{numbered2}
 \label{sec-2}
 \section*{unnumbered2}
 \label{unnumbered-sec-2}

 But perhaps this is nicer?

 \label{sec-1}
 \label{unnumbered-sec-2}
 \label{sec-3}
 \label{unnumbered-sec-4}

 In particular for mixed, nested trees. 

I think it would be nice to keep sec-NUM, with NUM matching current
numbering, for numbered headlines. I'm not against a simple global
counter for unnumbered headlines:

  \label{sec-1}
  \label{unnumbered-1}
  \label{sec-2}
  \label{unnumbered-2}

or in the following example

  * H1
  ** H2
 :PROPERTIES:
 :UNNUMBERED: t
 :END:
  *** H3
  *** H4
  * H5
  ** H6

the labelling scheme

 \label{sec-1}
 \label{unnumbered-1}
 \label{unnumbered-2}
 \label{unnumbered-3}
 \label{sec-2}
 \label{sec-2-1}

 This is incorrect.

   #+options: num:nil

   * Headline
 :PROPERTIES:
 :CUSTOM_ID: test
 :END:
 This is a link to [[#test]].

 will produce

   \section*{Headline}
   \label{sec-1}
   This is a link to \hyperref[sec-1]{Headline}.

 Is *my statement* incorrect or is the current *output* incorrect?

The former, but see below.

 On my PC, when I refer to an unnumbered headline I get
 \ref{UNNUMBERED}, but since it's after a \section* it will produce
 nothing or a subsequent element.  But I *did* forget to try the patch
 with emacs -q and maybe that's why I'm not seeing \hyperref's. . .

Actually, there was a small bug in the code, now fixed. `latex' back-end
is expected to use hyperref when headline in unnumbered.

 To be clear: you are happy if it uses the \hyperref[·]{·} in LaTeX,
 but not \ref{·} for unnumbered?

You are the LaTeX expert. Isn't it reasonable?


Regards,

-- 
Nicolas Goaziou

Re: [O] [patch, ox] Unnumbered headlines

2014-09-22 Thread Rasmus 
Hi,

Another couple of small changes.

Random observation: the patch is almost neutral due to the
headline-id function:

88 insertions(+), 72 deletions(-)

Nicolas Goaziou m...@nicolasgoaziou.fr writes:

 I think it would be nice to keep sec-NUM, with NUM matching current
 numbering, for numbered headlines. I'm not against a simple global
 counter for unnumbered headlines:

   \label{sec-1}
   \label{unnumbered-1}
   \label{sec-2}
   \label{unnumbered-2}

 or in the following example

   * H1
   ** H2
  :PROPERTIES:
  :UNNUMBERED: t
  :END:
   *** H3
   *** H4
   * H5
   ** H6

 the labelling scheme

  \label{sec-1}
  \label{unnumbered-1}
  \label{unnumbered-2}
  \label{unnumbered-3}
  \label{sec-2}
  \label{sec-2-1}

Using this file:

* h1
:PROPERTIES:
:CUSTOM_ID: h1
:END:
** h2
:PROPERTIES:
:unnumbered: t
:CUSTOM_ID: h2
:END:
*** h3
*** h4
* h5
:PROPERTIES:
:CUSTOM_ID: h5
:END:
[[*h1]] [[#h2]] [[*h4]] [[#h5]]
** h6

The output is now

\section{h1}
\label{sec-1}
\subsection*{h2}
\label{unnumbered-1}
\subsubsection*{h3}
\label{unnumbered-2}
\subsubsection*{h4}
\label{unnumbered-3}
\section{h5}
\label{sec-2}
\ref{sec-1} \hyperref[unnumbered-1]{h2} \hyperref[unnumbered-3]{h4} 
\ref{sec-2}
\subsection{h6}
\label{sec-2-1}


Which I think is quite good.

I don't know if the global unnumbered counter is made in the best way.
I add another plist to info with the number.  This approach is cleaner
than before since it's the numbering of unnumbered headlines is not in
`org-export--collect-headline-numbering' which is complicated enough
as it is.

An alternative approach could be to just count the unnumbered
headlines place in the tree every time.

 Actually, there was a small bug in the code, now fixed. `latex' back-end
 is expected to use hyperref when headline in unnumbered.

Right I see.  The attached patch should merge against master.

 To be clear: you are happy if it uses the \hyperref[·]{·} in LaTeX,
 but not \ref{·} for unnumbered?

 You are the LaTeX expert. Isn't it reasonable?

It seems to work well, yes.

So I guess we should let the patch hang for a while and see if someone
cares to test it.  

Of course I'd appreciate more comments/bug reports.

Should I write tests for the new behavior?  If so, tests for each
backend or only for vanilla-ox functions?

Cheers,
Rasmus

--
If you can mix business and politics wonderful things can happen!
From b6debf17314973b1feb5e7da0d7cc788d4920f50 Mon Sep 17 00:00:00 2001
From: Rasmus ras...@gmx.us
Date: Sun, 21 Sep 2014 16:17:55 +0200
Subject: [PATCH] ox: Support unnumbered headlines via property.

* ox.el (org-export--collect-headline-numbering): Return nil
if unnumbered headline.
(org-export-get-headline-id): New defun that returns a unique
ID to a headline.
(org-export-numbered-headline-p): Also tests for unnumbered
headline.
* ox-odt.el (org-odt-headline, org-odt-link,
org-odt-link--infer-description)
ox-md.el (org-md-headline, org-md-link),
ox-latex.el (org-latex-headline, org.latex-link),
ox-html.el (org-html-headline, org-html-link),
ox-ascii.el (org-ascii-link): Support ununbered headlines.
---
 lisp/org.el  |  2 +-
 lisp/ox-ascii.el |  7 +--
 lisp/ox-html.el  | 22 -
 lisp/ox-latex.el | 20 +++
 lisp/ox-md.el| 25 
 lisp/ox-odt.el   | 25 
 lisp/ox.el   | 59 +++-
 7 files changed, 88 insertions(+), 72 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 4ffe1e8..7565b14 100755
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -15337,7 +15337,7 @@ but in some other way.)
 LOCATION LOGGING COLUMNS VISIBILITY
 TABLE_EXPORT_FORMAT TABLE_EXPORT_FILE
 EXPORT_OPTIONS EXPORT_TEXT EXPORT_FILE_NAME
-EXPORT_TITLE EXPORT_AUTHOR EXPORT_DATE
+EXPORT_TITLE EXPORT_AUTHOR EXPORT_DATE UNNUMBERED
 ORDERED NOBLOCKING COOKIE_DATA LOG_INTO_DRAWER REPEAT_TO_STATE
 CLOCK_MODELINE_TOTAL STYLE HTML_CONTAINER_CLASS)
   Some properties that are used by Org-mode for various purposes.
diff --git a/lisp/ox-ascii.el b/lisp/ox-ascii.el
index 6f2b43a..5e8d479 100644
--- a/lisp/ox-ascii.el
+++ b/lisp/ox-ascii.el
@@ -1530,9 +1530,12 @@ INFO is a plist holding contextual information.
 	(let ((number
 		   (org-export-get-ordinal
 		destination info nil 'org-ascii--has-caption-p)))
-	  (when number
+	  (if number
 		(if (atom number) (number-to-string number)
-		  (mapconcat 'number-to-string number .
+		  (mapconcat 'number-to-string number .))
+		;; unnumbered headline
+		(when (eq 'headline (org-element-type destination))
+		  (format [%s] (org-export-data (org-element-property :title destination) info)
  (t
   (if (not (org-string-nw-p desc)) (format [%s] raw-link)
 	(concat (format [%s] desc)
diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index

Re: [O] [patch, ox] Unnumbered headlines

2014-09-22 Thread Thomas S. Dye 
Aloha Rasmus,

Rasmus ras...@gmx.us writes:

 So I guess we should let the patch hang for a while and see if someone
 cares to test it.  

 Of course I'd appreciate more comments/bug reports.

I'm looking forward to this functionality and will test out the patch
now that you're happy with its performance.  

I have a busy week ahead and two looming deadlines, but I'll get to it
as soon as I find time.

Thanks for taking on this difficult project.

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: [O] [patch, ox] Unnumbered headlines

2014-09-21 Thread Nicolas Goaziou 
Hello,

Rasmus ras...@gmx.us writes:

 I'm happy to finally be able to send an updated version of this patch
 that touches most backends in lisp/, but not the manual.  I have been
 moving over the summer etc.

Thanks for that work.  Some comments follow.

 You now specify unnumbered headlines with properties.  I think this is
 better since being unnumbered it's a pretty permanent state.  It's
 pretty hard to discover though, other than by looking at the output.

 So this works as expected:

 * Some headline
   :PROPERTIES:
   :UNNUMBERED: t
   :END:

 There's no :NUMBERED property and :UNNUMBERED is hardcoded.

Sounds good.

 I introduce a new function `org-export-get-headline-id` which returns
 the first non-nil from the following list.  There's a caveat:
 CUSTOM_ID is ensured to be unique!  Did I open the famous can of worm?

 1. The CUSTOM_ID property.
 2. A relative level number if the headline is numbered.
 3. The ID property
 4. A new generated unique ID.

I think we should keep separated CUSTOM_ID and ID on the one hand, and
internal reference on the other hand.

There's no guarantee that CUSTOM_ID will be unique, and, even if you
check it out, there's no guarantee either that its value can be used
as-is in the generated docstring (think about :CUSTOM_ID: 100% in
LaTeX export).

CUSTOM_ID is a human readable reference to an Org headline. This
headline should be referred to internally with a more specific id. To
a lesser extent, I think this also applied to org-id.

Also `org-export-headline-internal-id' (or some such, to avoid confusion
with other IDs) may return a value simpler than what `org-id-new'
returns (e.g. a dumb counter). If it is possible, the output will be
easier to read.

 Anyhow, `org-export-get-headline-id' ensures that we can refer to
 unnumbered headlines, which was not possible before.

This is untrue.

 Of course, in LaTeX such ref to a \section* will be nonsense, so we
 could introduce a \pageref here.

At the moment, referring to an unnumbered section displays its name.

 I'm unsure about whether this conflicts `org-latex-custom-id-as-label'
 which I had never seen until today (also notes on this in patch).

This variable has its use if custom-id and internal representation are
separated.

 PS: Not knowing or caring much about md, the links generated by it to
 headlines seem wrong.  Referring to headline 1 it only prints 1.
 Should it be something like [LABEL](1)?

There is probably something to do here, but that would be in another
patch.

 * ox-odt.el (org-odt-headline, org-odt-link,
 org-odt-link--infer-description): Support unnumbered
 headline.
 * ox-md.el (org-md-headline, org-md-link): Support
 unnumbered headlines.
 * ox-latex.el (org-latex-headline, org.latex-link): Support
 unnumbered headlines.
 * ox-html.el (org-html-headline, org-html-link): Support
 unnumbered headlines.
 * ox-ascii.el (org-ascii-link): Support ununbered headlines.

You can also write Support unnumbered headlines just once.

 + (when (equal 'headline (org-element-type destination))

Comparing symbols with `equal' is a sin beyond redemption. Use `eq'.

 +   (format [%s] (org-export-data (org-export-get-alt-title 
 destination info) info)

alt title is for table of contents only.

   (t
(if (not (org-string-nw-p desc)) (format [%s] raw-link)
   (concat (format [%s] desc)
 diff --git a/lisp/ox-html.el b/lisp/ox-html.el
 index 1d424cc..94cee20 100644
 --- a/lisp/ox-html.el
 +++ b/lisp/ox-html.el
 @@ -2321,7 +2321,7 @@ holding contextual information.
(unless (org-element-property :footnote-section-p headline)
  (let* ((numberedp (org-export-numbered-headline-p headline info))
 (numbers (org-export-get-headline-number headline info))
 -   (section-number (mapconcat #'number-to-string numbers -))
 +   (section-number (when numbers (mapconcat #'number-to-string 
 numbers -)))

Nitpick: I suggest `and' instead of `when' since there's no side-effect.

 +(when section-number (concat sec- 
 section-number))

Ditto.

 +  (unless (org-export-get-node-property :UNNUMBERED headline t)

Actually, this test is fragile. In the following example

  * H1
:PROPERTIES:
:UNNUMBERED: t
:END:
  ** H2
 :PROPERTIES:
 :UNNUMBERED: nil
 :END:
  *** H3

H3 should clearly be unnumbered even though inheritance disagrees. This
is a bit stronger than inheritance: if there is a single non-nil
UNNUMBERED property among ancestors (or the headline itself), it cannot
be numbered.


Regards,

-- 
Nicolas Goaziou

Re: [O] [patch, ox] Unnumbered headlines

2014-09-21 Thread Rasmus 
Hi,

Thanks for the comments.  Let's give it another try, shand't we.

Nicolas Goaziou m...@nicolasgoaziou.fr writes:

 I introduce a new function `org-export-get-headline-id` which returns
 the first non-nil from the following list.  There's a caveat:
 CUSTOM_ID is ensured to be unique!  Did I open the famous can of worm?

 1. The CUSTOM_ID property.
 2. A relative level number if the headline is numbered.
 3. The ID property
 4. A new generated unique ID.

 I think we should keep separated CUSTOM_ID and ID on the one hand, and
 internal reference on the other hand.

 There's no guarantee that CUSTOM_ID will be unique, and, even if you
 check it out, there's no guarantee either that its value can be used
 as-is in the generated docstring (think about :CUSTOM_ID: 100% in
 LaTeX export).

 CUSTOM_ID is a human readable reference to an Org headline. This
 headline should be referred to internally with a more specific id. To
 a lesser extent, I think this also applied to org-id.

 Also `org-export-headline-internal-id' (or some such, to avoid confusion
 with other IDs) may return a value simpler than what `org-id-new'
 returns (e.g. a dumb counter). If it is possible, the output will be
 easier to read.

Okay, I returned to my first hack (which never made it to this list).
Basically, I ID everything.  Unnumbered sections get the id
unnumbered-sec-COUNTER and numbered sections get the id
sec-COUNTER.

Perhaps you will find it too much of a hack.

The other easy alternative, which I find less pleasing, would have on
incremental counter, but it makes it harder to read.

A third alternative is give the numbers like in this patch, but store
the numbers for unnumbered section somewhere else
than :headline-numbering.

 Anyhow, `org-export-get-headline-id' ensures that we can refer to
 unnumbered headlines, which was not possible before.

 This is untrue.

 Of course, in LaTeX such ref to a \section* will be nonsense, so we
 could introduce a \pageref here.

 At the moment, referring to an unnumbered section displays its name.

In some modes, yes.  In LaTeX it produces a \ref{·} that LaTeX will
laugh at.

If you have a better idea than using the title I'm all ears!

 +(when (equal 'headline (org-element-type destination))

 Comparing symbols with `equal' is a sin beyond redemption. Use `eq'.

Shiiit. . .

Why, out of curiosity?  I though equal was like the meaner, tougher
eq, that gets shit right, but is a bit more expensive.

 + (format [%s] (org-export-data (org-export-get-alt-title
 destination info) info)

 alt title is for table of contents only.

Yeah, but I though, conditional on using title for ref when nothing
better exists, it would be nicer to have something shorter.  Anyway, I
changed it to plain title now.

 Nitpick: I suggest `and' instead of `when' since there's no side-effect.

OK, I think I got 'em all. 

 +  (unless (org-export-get-node-property :UNNUMBERED headline t)

 Actually, this test is fragile. In the following example

   * H1
 :PROPERTIES:
 :UNNUMBERED: t
 :END:
   ** H2
  :PROPERTIES:
  :UNNUMBERED: nil
  :END:
   *** H3

Fixed.

Thanks,
Rasmus

-- 
Don't panic!!!

Re: [O] [patch, ox] Unnumbered headlines

2014-09-21 Thread Nicolas Goaziou 
Rasmus ras...@gmx.us writes:

 Thanks for the comments.  Let's give it another try, shand't we.

There we go.

 Okay, I returned to my first hack (which never made it to this list).
 Basically, I ID everything.  Unnumbered sections get the id
 unnumbered-sec-COUNTER and numbered sections get the id
 sec-COUNTER.

 Perhaps you will find it too much of a hack.

I don't think it is a hack. I am just pointing out that how we refer
internally to headlines has an effect on output clarity. I let you
strike a balance between clarity and easiness of implementation. Note
that the internal reference can be a bit cryptic (e.g. num-1-1 and
nonum-2).

 At the moment, referring to an unnumbered section displays its name.

 In some modes, yes.  In LaTeX it produces a \ref{·} that LaTeX will
 laugh at.

This is incorrect.

  #+options: num:nil

  * Headline
:PROPERTIES:
:CUSTOM_ID: test
:END:
This is a link to [[#test]].

will produce

  \section*{Headline}
  \label{sec-1}
  This is a link to \hyperref[sec-1]{Headline}.

 If you have a better idea than using the title I'm all ears!

On the contrary, using the title is what is usually done. I'm all for
it.

 Comparing symbols with `equal' is a sin beyond redemption. Use `eq'.

 Why, out of curiosity?  I though equal was like the meaner, tougher
 eq, that gets shit right, but is a bit more expensive.

This is about using the right tool for the job. Unless you mess with the
obarray, two symbols with the same name are guaranteed to be `eq'.
There's really no reason to use anything else.


Regards,

-- 
Nicolas Goaziou

Re: [O] [patch, ox] Unnumbered headlines

2014-09-21 Thread Rasmus 
Hi Nicolas,

Thanks for the comments.

Nicolas Goaziou m...@nicolasgoaziou.fr writes:

 Okay, I returned to my first hack (which never made it to this list).
 Basically, I ID everything.  Unnumbered sections get the id
 unnumbered-sec-COUNTER and numbered sections get the id
 sec-COUNTER.

 Perhaps you will find it too much of a hack.

 I don't think it is a hack. I am just pointing out that how we refer
 internally to headlines has an effect on output clarity. I let you
 strike a balance between clarity and easiness of implementation. Note
 that the internal reference can be a bit cryptic (e.g. num-1-1 and
 nonum-2).

With the last patch it gets weird when you have mixed trees, like this:

* numbered
** unnumbered 
:PROPERTIES:
:UNNUMBERED: t
:END:

The LaTeX output is:

\section{numbered}
\label{sec-1}
\subsection*{unnumbered}
\label{unnumbered-sec-0-1}

Perhaps it would be nicer to use a single counter rather than two?
Right now, this

* numbered1
* unnumbered2 
:PROPERTIES:
:UNNUMBERED: t
:END:
* numbered2
* unnumbered2
:PROPERTIES:
:UNNUMBERED: t
:END:

produces

\section{numbered1}
\label{sec-1}
\section*{unnumbered2}
\label{unnumbered-sec-1}
\section{numbered2}
\label{sec-2}
\section*{unnumbered2}
\label{unnumbered-sec-2}

But perhaps this is nicer?

\label{sec-1}
\label{unnumbered-sec-2}
\label{sec-3}
\label{unnumbered-sec-4}

In particular for mixed, nested trees. 

 At the moment, referring to an unnumbered section displays its name.

 In some modes, yes.  In LaTeX it produces a \ref{·} that LaTeX will
 laugh at.

 This is incorrect.

   #+options: num:nil

   * Headline
 :PROPERTIES:
 :CUSTOM_ID: test
 :END:
 This is a link to [[#test]].

 will produce

   \section*{Headline}
   \label{sec-1}
   This is a link to \hyperref[sec-1]{Headline}.

Is *my statement* incorrect or is the current *output* incorrect?

On my PC, when I refer to an unnumbered headline I get
\ref{UNNUMBERED}, but since it's after a \section* it will produce
nothing or a subsequent element.  But I *did* forget to try the patch
with emacs -q and maybe that's why I'm not seeing \hyperref's. . .

 If you have a better idea than using the title I'm all ears!

 On the contrary, using the title is what is usually done. I'm all for
 it.

To be clear: you are happy if it uses the \hyperref[·]{·} in LaTeX,
but not \ref{·} for unnumbered?

 Comparing symbols with `equal' is a sin beyond redemption. Use `eq'.

 Why, out of curiosity?  I though equal was like the meaner, tougher
 eq, that gets shit right, but is a bit more expensive.

 This is about using the right tool for the job. Unless you mess with the
 obarray, two symbols with the same name are guaranteed to be `eq'.
 There's really no reason to use anything else.

OK.

Thanks,
Rasmus

-- 
And I faced endless streams of vendor-approved Ikea furniture. . .

Re: [O] [patch, ox] Unnumbered headlines

2014-09-20 Thread Rasmus 
Hi,

I'm happy to finally be able to send an updated version of this patch
that touches most backends in lisp/, but not the manual.  I have been
moving over the summer etc.

You now specify unnumbered headlines with properties.  I think this is
better since being unnumbered it's a pretty permanent state.  It's
pretty hard to discover though, other than by looking at the output.

So this works as expected:

* Some headline
  :PROPERTIES:
  :UNNUMBERED: t
  :END:

There's no :NUMBERED property and :UNNUMBERED is hardcoded.

I introduce a new function `org-export-get-headline-id` which returns
the first non-nil from the following list.  There's a caveat:
CUSTOM_ID is ensured to be unique!  Did I open the famous can of worm?

1. The CUSTOM_ID property.
2. A relative level number if the headline is numbered.
3. The ID property
4. A new generated unique ID.

Anyhow, `org-export-get-headline-id' ensures that we can refer to
unnumbered headlines, which was not possible before.  Of course, in
LaTeX such ref to a \section* will be nonsense, so we could introduce
a \pageref here.  I'm unsure about whether this conflicts
`org-latex-custom-id-as-label' which I had never seen until today
(also notes on this in patch).

I have updated backends in lisp/, but I'm at most(!) an expert on
LaTeX.  However, I have tested all backends to the best of my ability.

Please feel free to test and let me know about any discrepancies!

Cheers,
Rasmus

PS: Not knowing or caring much about md, the links generated by it to
headlines seem wrong.  Referring to headline 1 it only prints 1.
Should it be something like [LABEL](1)?


-- 
This is the kind of tedious nonsense up with which I will not put
From fb44a552a151025513b645527498325febb6118f Mon Sep 17 00:00:00 2001
From: Rasmus ras...@gmx.us
Date: Fri, 8 Aug 2014 14:53:01 +0200
Subject: [PATCH] ox: Support unnumbered headlines via property.

* ox.el (org-export--collect-headline-numbering): Return nil
if unnumbered headline.
(org-export-get-headline-id): New defun that returns a unique
ID to a headline.
(org-export-numbered-headline-p): Also tests for unnumbered
headline.
* ox-odt.el (org-odt-headline, org-odt-link,
org-odt-link--infer-description): Support unnumbered
headline.
* ox-md.el (org-md-headline, org-md-link): Support
unnumbered headlines.
* ox-latex.el (org-latex-headline, org.latex-link): Support
unnumbered headlines.
* ox-html.el (org-html-headline, org-html-link): Support
unnumbered headlines.
* ox-ascii.el (org-ascii-link): Support ununbered headlines.

Headlines can now be specified as unnumbered by assigning the property :UNUMBERED.
---
 lisp/ox-ascii.el |  7 +--
 lisp/ox-html.el  | 22 --
 lisp/ox-latex.el | 22 ++
 lisp/ox-md.el| 25 +
 lisp/ox-odt.el   | 32 ++--
 lisp/ox.el   | 44 
 6 files changed, 82 insertions(+), 70 deletions(-)

diff --git a/lisp/ox-ascii.el b/lisp/ox-ascii.el
index 047b74e..8a5ad89 100644
--- a/lisp/ox-ascii.el
+++ b/lisp/ox-ascii.el
@@ -1511,9 +1511,12 @@ INFO is a plist holding contextual information.
 	(let ((number
 		   (org-export-get-ordinal
 		destination info nil 'org-ascii--has-caption-p)))
-	  (when number
+	  (if number
 		(if (atom number) (number-to-string number)
-		  (mapconcat 'number-to-string number .
+		  (mapconcat 'number-to-string number .))
+		;; unnumbered headline
+		(when (equal 'headline (org-element-type destination))
+		  (format [%s] (org-export-data (org-export-get-alt-title destination info) info)
  (t
   (if (not (org-string-nw-p desc)) (format [%s] raw-link)
 	(concat (format [%s] desc)
diff --git a/lisp/ox-html.el b/lisp/ox-html.el
index 1d424cc..94cee20 100644
--- a/lisp/ox-html.el
+++ b/lisp/ox-html.el
@@ -2321,7 +2321,7 @@ holding contextual information.
   (unless (org-element-property :footnote-section-p headline)
 (let* ((numberedp (org-export-numbered-headline-p headline info))
(numbers (org-export-get-headline-number headline info))
-   (section-number (mapconcat #'number-to-string numbers -))
+   (section-number (when numbers (mapconcat #'number-to-string numbers -)))
(level (+ (org-export-get-relative-level headline info)
  (1- (plist-get info :html-toplevel-hlevel
(todo (and (plist-get info :with-todo-keywords)
@@ -2338,9 +2338,9 @@ holding contextual information.
(contents (or contents ))
(ids (delq nil
   (list (org-element-property :CUSTOM_ID headline)
-(concat sec- section-number)
+(when section-number (concat sec- section-number))
 (org-element-property :ID headline
-   (preferred-id (car ids))
+   (preferred-id (org-export-get-headline-id headline info))
(extra-ids (mapconcat

Re: [O] [patch, ox] Unnumbered headlines

2014-09-20 Thread Alan L Tyree 
Thanks very much for working on this, Rasmus. I'll try to test it out 
over the next couple of days. It really will make book production much 
nicer!


Cheers,
Alan

On 21/09/14 02:02, Rasmus wrote:

Hi,

I'm happy to finally be able to send an updated version of this patch
that touches most backends in lisp/, but not the manual.  I have been
moving over the summer etc.

You now specify unnumbered headlines with properties.  I think this is
better since being unnumbered it's a pretty permanent state.  It's
pretty hard to discover though, other than by looking at the output.

So this works as expected:

* Some headline
   :PROPERTIES:
   :UNNUMBERED: t
   :END:

There's no :NUMBERED property and :UNNUMBERED is hardcoded.

I introduce a new function `org-export-get-headline-id` which returns
the first non-nil from the following list.  There's a caveat:
CUSTOM_ID is ensured to be unique!  Did I open the famous can of worm?

1. The CUSTOM_ID property.
2. A relative level number if the headline is numbered.
3. The ID property
4. A new generated unique ID.

Anyhow, `org-export-get-headline-id' ensures that we can refer to
unnumbered headlines, which was not possible before.  Of course, in
LaTeX such ref to a \section* will be nonsense, so we could introduce
a \pageref here.  I'm unsure about whether this conflicts
`org-latex-custom-id-as-label' which I had never seen until today
(also notes on this in patch).

I have updated backends in lisp/, but I'm at most(!) an expert on
LaTeX.  However, I have tested all backends to the best of my ability.

Please feel free to test and let me know about any discrepancies!

Cheers,
Rasmus

PS: Not knowing or caring much about md, the links generated by it to
headlines seem wrong.  Referring to headline 1 it only prints 1.
Should it be something like [LABEL](1)?




--
Alan L Tyreehttp://www2.austlii.edu.au/~alan
Tel:  04 2748 6206  sip:typh...@iptel.org

Re: [O] [patch, ox] Unnumbered headlines

2014-08-12 Thread Nicolas Goaziou 
Hello,

Rasmus ras...@gmx.us writes:

 True.  Personally, I find them nicer as you can just C-c C-c on your
 headline and write down some keyword that is typically easy to
 remember.  For properties I must rely on C-c C-x p — since the syntax
 is so awkward — and while it may be memorable to me try to explain it
 to co-authors who are not long-time Emacs users.

 Another option is to use properties, e.g. UNNUMBERED, or NO_NUMBER
 with a non-nil value

   * Some headline
 :PROPERTIES:
 :UNNUMBERED: t
 :END:

 It is harder to notice an unnumbered headline, but it doesn't add cruft
 to the tag line, and this is far less important than :noexport:. This is
 not perfect either, but I think the trade-off is honest.

 I can see you point, and I think I agree, though I personally much,
 much prefer tags.

Of course, tags are easier to use than properties, hence their
popularity. But they have some limitations, too.

I'm not saying that we must use a property, but this is definitely
something to ponder.

 Of course a utility function could be added (like the beamer minor
 mode) that adds the tag to give you a visual clue while the properties
 are really what matter.

Which would defeat the choice of using a property (i.e. avoid visual
clutter).

 Another advantage is inheritance is already implemented for node
 properties (see `org-export-get-node-property').

 Interesting.  I did not know.

Actually, it's not an advantage per se, since `org-export-get-tags'
does it too.

 The most elegant way would perhaps be to introduce in the output of
 `org-export-get-headline-number' whether a headline is unnumbered, but
 I am not sure how to do this without breaking the expected output of
 the function.

 A dirty fix might be add an extra 0 to the beginning of the section
 number list when dealing with unnumbered headings, but it is not so
 nice as the numbers loose their meaning. . .

Also, headline numbers can start with 0:

  ** H0.1
  * H1
  ** H1.1

You could add a 0 at the end instead, or begin with a negative number,
which cannot happen otherwise, but that would be hackish, for sure.

Since ox-html.el, and possibly other back-ends, rely on
`number-to-string', there not much else to do down this road.

 What I am currently trying to do with ox-html is combining
 `org-export-get-headline-number' (which is always a list of numbers)
 and `org-export-numbered-headline-p' to determine if the ID should
 contain the substring unnumbered.  Then the first unnumbered section
 would be sec-unnumbered-1 and so forth.

 The previous snippet from ox-html.el would become

   (format span class=\section-number-%d\%d/span 
   level
   (org-export-get-headline-id headline info))

 What I was experiment with is something like: 

 (format span class=\section-number-%s-%d\%d/span 
(if numberedp  unumbered)
level)

 Do you think it would be better to work on
 `org-export-get-headline-id' and solve the issue in that way is a
 better approach than what I describe above?

Roughly, both approaches require the same amount of changes and imply
the same incompatibilities.

Nevertheless, I think it is cleaner for `org-export-get-headline-number'
to return nil when a headline is not numbered and to separate both
intents, i.e, provide a number and a unique internal id.

Anyway, feel free to experiment, there's no hurry.

Thanks for your work.


Regards,

-- 
Nicolas Goaziou

Re: [O] [patch, ox] Unnumbered headlines

2014-08-11 Thread Nicolas Goaziou 
Hello,

Rasmus ras...@gmx.us writes:

 In a recent thread¹ Tom and Alan mention that authors sometimes need
 unnumbered headlines, e.g. for prefaces.  This patch (tries to) add
 this feature via the tag :nonumber: (customizable via Custom or
 in-file).

Interesting.  Some comments follow.

 I make two assumptions.  First, the tag is recursive, so if the parent
 is not numbered the child is not numbered.

Indeed.

 Secondly, I depart from the LaTeX tradition of ignoring unnumbered
 headlines in the TOC (except in the case of ox-latex.el where it
 depends on org-latex-classes). (See example below).

OK.

 In my opinion a :nonumber: tag is a natural continuation of :export:
 and :noexport:

First, maybe a tag is not the best way to specify it. Tags are rather
obnoxious and their length is somewhat limited by the width of the
window.

Another option is to use properties, e.g. UNNUMBERED, or NO_NUMBER
with a non-nil value

  * Some headline
:PROPERTIES:
:UNNUMBERED: t
:END:

It is harder to notice an unnumbered headline, but it doesn't add cruft
to the tag line, and this is far less important than :noexport:. This is
not perfect either, but I think the trade-off is honest.

Another advantage is inheritance is already implemented for node
properties (see `org-export-get-node-property').

 and unlike :ignoreheading: the implementation is fairly clean (or
 maybe I'm cheating myself here).

Do not underestimate it: implementing this feature is a bit tricky, and
will introduce backward incompatible changes to export back-ends
(possibly outside the scope of core+contrib).

A major problem comes from `org-export-get-headline-number', which
always returns a unique non-nil value for headlines in a parse tree.
Even unnumbered headlines (e.g. with option num:2) get a number.

Consequently, some back-ends use this number as a unique ID, as this
excerpt from ox-html.el

  (format span class=\section-number-%d\%s/span 
  level
  (mapconcat #'number-to-string numbers .))

It is not possible to rely on this mechanism with your patch.

A solution is to create two functions for the two features:

  - `org-export-get-headline-number' :: the same as today, but returns
   nil if headline is unnumbered.

  - `org-export-get-headline-id' :: returns a unique ID, as an integer,
   for the current headline, notwithstanding its numbering status.

Then `org-export-get-ordinal' should probably try to call the first one
and fallback to the second one.

The previous snippet from ox-html.el would become

  (format span class=\section-number-%d\%d/span 
  level
  (org-export-get-headline-id headline info))

Obviously, this implies that every back-end using this construct should
be updated accordingly.

WDYT?


Regards,

-- 
Nicolas Goaziou

Re: [O] [patch, ox] Unnumbered headlines

2014-08-11 Thread Rasmus 
Nicolas Goaziou m...@nicolasgoaziou.fr writes:

 Hello,

 Rasmus ras...@gmx.us writes:

 In a recent thread¹ Tom and Alan mention that authors sometimes need
 unnumbered headlines, e.g. for prefaces.  This patch (tries to) add
 this feature via the tag :nonumber: (customizable via Custom or
 in-file).

 Interesting.  Some comments follow.

 I make two assumptions.  First, the tag is recursive, so if the parent
 is not numbered the child is not numbered.

 Indeed.

 Secondly, I depart from the LaTeX tradition of ignoring unnumbered
 headlines in the TOC (except in the case of ox-latex.el where it
 depends on org-latex-classes). (See example below).

 OK.

The TOC part can easily be added, of course, but it's second order at
the moment. 

 In my opinion a :nonumber: tag is a natural continuation of :export:
 and :noexport:

 First, maybe a tag is not the best way to specify it. Tags are rather
 obnoxious and their length is somewhat limited by the width of the
 window.

True.  Personally, I find them nicer as you can just C-c C-c on your
headline and write down some keyword that is typically easy to
remember.  For properties I must rely on C-c C-x p — since the syntax
is so awkward — and while it may be memorable to me try to explain it
to co-authors who are not long-time Emacs users.

 Another option is to use properties, e.g. UNNUMBERED, or NO_NUMBER
 with a non-nil value

   * Some headline
 :PROPERTIES:
 :UNNUMBERED: t
 :END:

 It is harder to notice an unnumbered headline, but it doesn't add cruft
 to the tag line, and this is far less important than :noexport:. This is
 not perfect either, but I think the trade-off is honest.

I can see you point, and I think I agree, though I personally much,
much prefer tags.

Of course a utility function could be added (like the beamer minor
mode) that adds the tag to give you a visual clue while the properties
are really what matter.

 Another advantage is inheritance is already implemented for node
 properties (see `org-export-get-node-property').

Interesting.  I did not know.

 and unlike :ignoreheading: the implementation is fairly clean (or
 maybe I'm cheating myself here).

 Do not underestimate it: implementing this feature is a bit tricky, and
 will introduce backward incompatible changes to export back-ends
 (possibly outside the scope of core+contrib).

 A major problem comes from `org-export-get-headline-number', which
 always returns a unique non-nil value for headlines in a parse tree.
 Even unnumbered headlines (e.g. with option num:2) get a number.

 Consequently, some back-ends use this number as a unique ID, as this
 excerpt from ox-html.el

   (format span class=\section-number-%d\%s/span 
   level
   (mapconcat #'number-to-string numbers .))

 It is not possible to rely on this mechanism with your patch.

 A solution is to create two functions for the two features:

   - `org-export-get-headline-number' :: the same as today, but returns
nil if headline is unnumbered.

   - `org-export-get-headline-id' :: returns a unique ID, as an integer,
for the current headline, notwithstanding its numbering status.

 Then `org-export-get-ordinal' should probably try to call the first one
 and fallback to the second one.

In my local branch (not published; still problems with ox-html) I
solve this by retaining a number for unnumbered headlines and having
parallel numbering.  That is, there may exists a numbered section X.y
as well as a unnumbered section X.y when applicable.

Of course there is still an issue in that there is no way of
differentiating the a number list from a numbered section and an
unnumbered one and consequently e.g. ox-html IDs will still be broken.

The most elegant way would perhaps be to introduce in the output of
`org-export-get-headline-number' whether a headline is unnumbered, but
I am not sure how to do this without breaking the expected output of
the function.  A dirty fix might be add an extra 0 to the beginning of
the section number list when dealing with unnumbered headings, but it
is not so nice as the numbers loose their meaning. . .

What I am currently trying to do with ox-html is combining
`org-export-get-headline-number' (which is always a list of numbers)
and `org-export-numbered-headline-p' to determine if the ID should
contain the substring unnumbered.  Then the first unnumbered section
would be sec-unnumbered-1 and so forth.

 The previous snippet from ox-html.el would become

   (format span class=\section-number-%d\%d/span 
   level
   (org-export-get-headline-id headline info))

What I was experiment with is something like: 

(format span class=\section-number-%s-%d\%d/span 
   (if numberedp  unumbered)
   level)



Do you think it would be better to work on
`org-export-get-headline-id' and solve the issue in that way is a
better approach than what I describe above?

 Obviously, this implies that every back-end using this construct should
 be updated

Re: [O] [patch, ox] Unnumbered headlines

2014-08-09 Thread Detlef Steuer 
Am Fri, 08 Aug 2014 15:39:15 +0200
schrieb Rasmus ras...@gmx.us:

 Needless to say such a feature needs to be discussed and I not sure
 whether the greater Org community finds it useful or needless clutter.


Definitly a candidate for inclusion in org-mode.
Thx for the patch!

Detlef

Re: [O] [patch, ox] Unnumbered headlines

2014-08-08 Thread Alan L Tyree 


On 08/08/14 23:39, Rasmus wrote:

Hi,

In a recent thread¹ Tom and Alan mention that authors sometimes need
unnumbered headlines, e.g. for prefaces.  This patch (tries to) add
this feature via the tag :nonumber: (customizable via Custom or
in-file).

I make two assumptions.  First, the tag is recursive, so if the parent
is not numbered the child is not numbered.  Secondly, I depart from
the LaTeX tradition of ignoring unnumbered headlines in the TOC
(except in the case of ox-latex.el where it depends on
org-latex-classes).  (See example below).

Needless to say such a feature needs to be discussed and I not sure
whether the greater Org community finds it useful or needless clutter.

In my opinion a :nonumber: tag is a natural continuation of :export:
and :noexport: and unlike :ignoreheading: the implementation is fairly
clean (or maybe I'm cheating myself here).  A reason for why to
include it is that it seems relatively easy to do *during* export, but
it's hard to consistently get it right on in both headlines and the
TOC via filters.

The patch is messing with ox.el, and thus I would appreciate a review
and potentially testing, in the case that it is agreed that such a
feature would be OK to add to ox.

It seems to work well with ox-latex.el, ox-ascii.el and ox-html.el.
It doesn't play well with ox-odt.el (headlines are still numbered).  I
will fix this as well as adding documentation if a consensus of the
worthwhileness of the patch can be reached.

Finally, here's an example output using ox-ascii

#+begin_src org
 * a (not numbered)   :nonum:
 ** aa (not numbert)
 * b (1)
 ** ba (not numbered) :nonum:
 *** baa (not numbered)
 ** bb (1.1)

#+end_src

#+RESULTS: (TOC only, but the rest is as expected)
 a (not numbered)
 .. aa (not numbert)
 1 b (1)
 .. ba (not numbered)
 . baa (not numbered)
 .. 1.1 bb (1.1)


Thanks,
Rasmus

Footnotes:
¹   http://permalink.gmane.org/gmane.emacs.orgmode/89515

--
Vote for proprietary math!

Rasmus, you're my hero!

Regarding the two assumptions:

- Recursive tags: I think this is correct. I don't think it matters too 
much for my use case since things like the Preface will ordinarily be 
top level headlines and unlikely to have children. If there are child 
headlines, then I don't see why numbering would be required.


- Table of contents: I'm sure this is correct. I always ended up adding 
to the TOC when using LaTeX anyway.


The frontmatter of a book has two distinct types of pages:
  - title pages, copyright pages and so forth. If these pages are 
headlined at all, then the :ignore: tag and Eric's filter takes care of 
them;


  - things like the Preface, Forward and (in my case) Table of Statutes 
and Table of cases. This type wants to be referenced in the TOC but they 
definitely do not want to be sequentially numbered as chapters.


The Wikipedia entry on Book Design lists 12 types of frontmatter pages: 
http://en.wikipedia.org/wiki/Book_design. It's easy to see which ones 
fit into which category.


I think this facility will *greatly* enhance org-mode for book 
authors/publishers. It will certainly make the conversion to ePub go 
more smoothly.


Cheers,
Alan


--
Alan L Tyreehttp://www2.austlii.edu.au/~alan
Tel:  04 2748 6206  sip:typh...@iptel.org

Re: [O] [patch, ox] Unnumbered headlines - early test

2014-08-08 Thread Alan L Tyree 

I have a book length MS that I tested the patch on.

* Copyright page   :nonumber:

* Preface:nonumber:

* Law relating to sale of goods

... etc

Export looked good and as expected, that is, no numbers on the first two 
headlines and the third headline numbered 1. as it should be. Table of 
contents was as expected. LaTeX and ascii exports also looked great.


However, running tidy -m sog.html on the resulting file threw up the 
following warnings:


line 222 column 1 - Warning: div anchor outline-container-sec- 
already defined

line 223 column 1 - Warning: h2 anchor sec- already defined
line 224 column 1 - Warning: div anchor text- already defined
Info: Doctype given is -//W3C//DTD XHTML 1.0 Strict//EN
Info: Document content looks like XHTML 1.0 Strict
3 warnings, 0 errors were found!

Line 222, 223 and 224 relate to the Preface heading. The offending items 
were, of course, copies of the corresponding items in Copyright page. To 
avoid these, I think you need to give unique id and sec markers to the 
unnumbered headlines.


It matters because the resulting ePub will not validate unless the html 
passes the tidy test.


Cheers,
Alan



--
Alan L Tyreehttp://www2.austlii.edu.au/~alan
Tel:  04 2748 6206  sip:typh...@iptel.org