Re: [patch, ox] Unnumbered headlines

[Rasmus <rasmus@gmx.us>]

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

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 <mail@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!

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-Support-unnumbered-headlines-via-property.patch --]
[-- Type: text/x-diff, Size: 16271 bytes --]

From b6debf17314973b1feb5e7da0d7cc788d4920f50 Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@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 1d424cc..2dfcd21 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 (and 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)
+                            (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))
            (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))
 		 ;; What description to use?
 		 (desc
 		  ;; Case 1: Headline is numbered and LINK has no
diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index 218c69f..8e08213 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -1476,15 +1476,7 @@ holding contextual information."
 			       todo todo-type priority text tags info))
 	   ;; Associate \label to the headline for internal links.
 	   (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)))
 	   (pre-blanks
 	    (make-string (org-element-property :pre-blank headline) 10)))
       (if (or (not section-fmt) (org-export-low-level-p headline info))
@@ -1974,14 +1966,8 @@ INFO is a plist holding contextual information.  See
 	   (let* ((custom-label
 		   (and (plist-get info :latex-custom-id-labels)
 			(org-element-property :CUSTOM_ID destination)))
-		  (label
-		   (or
-		    custom-label
-		    (format "sec-%s"
-			    (mapconcat
-			     #'number-to-string
-			     (org-export-get-headline-number destination info)
-			     "-")))))
+		  (label (or custom-label
+			     (org-export-get-headline-id destination info))))
 	     (if (and (not desc)
 		      (org-export-numbered-headline-p destination info))
 		 (format "\\ref{%s}" label)
diff --git a/lisp/ox-md.el b/lisp/ox-md.el
index 695fb61..9e7984d 100644
--- a/lisp/ox-md.el
+++ b/lisp/ox-md.el
@@ -202,12 +202,7 @@ a communication channel."
 		   (and char (format "[#%c] " char)))))
 	   (anchor
 	    (when (plist-get info :with-toc)
-	      (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 (org-export-get-headline-id headline info)
 	       nil nil info)))
 	   ;; Headline text without tags.
 	   (heading (concat todo priority title))
@@ -330,10 +325,12 @@ a communication channel."
 	   (and contents (concat contents " "))
 	   (format "(%s)"
 		   (format (org-export-translate "See section %s" :html info)
-			   (mapconcat 'number-to-string
-				      (org-export-get-headline-number
-				       destination info)
-				      ".")))))))
+			   (if (org-export-numbered-headline-p destination info)
+			       (mapconcat 'number-to-string
+					  (org-export-get-headline-number
+					   destination info)
+					  ".")
+			     (org-export-get-alt-title headline info))))))))
      ((org-export-inline-image-p link org-html-inline-image-rules)
       (let ((path (let ((raw-path (org-element-property :path link)))
 		    (if (not (file-name-absolute-p raw-path)) raw-path
@@ -354,9 +351,13 @@ a communication channel."
 	(if (org-string-nw-p contents) contents
 	  (when destination
 	    (let ((number (org-export-get-ordinal destination info)))
-	      (when number
+	      (if number
 		(if (atom number) (number-to-string number)
-		  (mapconcat 'number-to-string number "."))))))))
+		  (mapconcat 'number-to-string number "."))
+		;; unnumbered headline
+		(and (eq 'headline (org-element-type destination))
+		  ;; BUG: shouldn't headlines have a form like [ref](name) in md
+		  (org-export-data (org-export-get-alt-title destination info) info))))))))
      ;; Link type is handled by a special function.
      ((let ((protocol (nth 2 (assoc type org-link-protocols))))
 	(and (functionp protocol)
diff --git a/lisp/ox-odt.el b/lisp/ox-odt.el
index 96a3b83..372d157 100644
--- a/lisp/ox-odt.el
+++ b/lisp/ox-odt.el
@@ -1122,7 +1122,7 @@ See `org-odt--build-date-styles' for implementation details."
   (setq text
 	(concat
 	 ;; Section number.
-	 (when section-number (concat section-number ". "))
+	 (and section-number (concat section-number ". "))
 	 ;; Todo.
 	 (when todo
 	   (let ((style (if (member todo org-done-keywords)
@@ -1816,9 +1816,7 @@ holding contextual information."
 	   ;; Get level relative to current parsed data.
 	   (level (org-export-get-relative-level headline info))
 	   ;; Get canonical label for the headline.
-	   (id (concat "sec-" (mapconcat 'number-to-string
-					 (org-export-get-headline-number
-					  headline info) "-")))
+	   (id (org-export-get-headline-id headline info))
 	   ;; Get user-specified labels for the headline.
 	   (extra-ids (list (org-element-property :CUSTOM_ID headline)
 			    (org-element-property :ID headline)))
@@ -1870,9 +1868,13 @@ holding contextual information."
        (t
 	(concat
 	 (format
-	  "\n<text:h text:style-name=\"%s\" text:outline-level=\"%s\">%s</text:h>"
+	  "\n<text:h text:style-name=\"%s\" text:outline-level=\"%s\" text:is-list-header=\"%s\">%s</text:h>"
 	  (format "Heading_20_%s" level)
 	  level
+	  ;; text:is-list-header is how LO calls an unnumbered headline
+	  ;; however, the definition here sounds weird:
+	  ;; http://docs.oasis-open.org/office/v1.2/cs01/OpenDocument-v1.2-cs01-part1.html#__RefHeading__1415152_253892949
+	  (if (org-export-numbered-headline-p headline info) "false" "true")
 	  (concat extra-targets anchored-title))
 	 contents))))))
 
@@ -2643,10 +2645,7 @@ Return nil, otherwise."
   (let* ((genealogy (org-export-get-genealogy destination))
 	 (data (reverse genealogy))
 	 (label (case (org-element-type destination)
-		  (headline
-		   (format "sec-%s" (mapconcat 'number-to-string
-					       (org-export-get-headline-number
-						destination info) "-")))
+		  (headline (org-export-get-headline-id destination info))
 		  (target
 		   (org-element-property :value destination))
 		  (t (error "FIXME: Resolve %S" destination)))))
@@ -2777,10 +2776,10 @@ INFO is a plist holding contextual information.  See
 	   ;; Otherwise, try to provide a meaningful description.
 	   (if (not desc) (org-odt-link--infer-description destination info)
 	     (let* ((headline-no
-		     (org-export-get-headline-number destination info))
-		    (label
-		     (format "sec-%s"
-			     (mapconcat 'number-to-string headline-no "-"))))
+		     (if (org-export-numbered-headline-p destination info)
+			 (org-export-get-headline-number destination info)
+		       (org-element-property :title destination)))
+		    (label (org-export-get-headline-id destination info)))
 	       (format
 		"<text:a xlink:type=\"simple\" xlink:href=\"#%s\">%s</text:a>"
 		label desc))))
diff --git a/lisp/ox.el b/lisp/ox.el
index f01f951..5168382 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -1970,6 +1970,7 @@ Return updated plist."
   ;; properties.
   (nconc
    `(:headline-numbering ,(org-export--collect-headline-numbering data info)
+     :unnumbered-headline-id ,(org-export--collect-unnumbered-headline-id data info)
      :exported-data ,(make-hash-table :test 'eq :size 4001))
    info))
 
@@ -1992,7 +1993,7 @@ OPTIONS is a plist holding export options."
       (if (= min-level 10000) 1 min-level))))
 
 (defun org-export--collect-headline-numbering (data options)
-  "Return numbering of all exportable headlines in a parse tree.
+  "Return numbering of all exportable numbered headlines in a parse tree.
 
 DATA is the parse tree.  OPTIONS is the plist holding export
 options.
@@ -2003,7 +2004,8 @@ for a footnotes section."
   (let ((numbering (make-vector org-export-max-depth 0)))
     (org-element-map data 'headline
       (lambda (headline)
-	(unless (org-element-property :footnote-section-p headline)
+	(unless (or (not (org-export-numbered-headline-p headline options))
+		    (org-element-property :footnote-section-p headline))
 	  (let ((relative-level
 		 (1- (org-export-get-relative-level headline options))))
 	    (cons
@@ -2011,10 +2013,21 @@ for a footnotes section."
 	     (loop for n across numbering
 		   for idx from 0 to org-export-max-depth
 		   when (< idx relative-level) collect n
-		   when (= idx relative-level) collect (aset numbering idx (1+ n))
+		   when (= idx relative-level) collect (aset numbering
+							     idx (1+ n))
 		   when (> idx relative-level) do (aset numbering idx 0))))))
       options)))
 
+(defun org-export--collect-unnumbered-headline-id (data options)
+  "Return a numbering of all unnumbered headlines.
+
+Unnumbered headlines are given numbered after occurrence."
+  (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)))))))))
+
 (defun org-export--populate-ignore-list (data options)
   "Return list of elements and objects to ignore during export.
 DATA is the parse tree to traverse.  OPTIONS is the plist holding
@@ -3772,7 +3785,12 @@ INFO is the plist used as a communication channel."
 ;;
 ;; `org-export-get-headline-number' returns the section number of an
 ;; headline, while `org-export-number-to-roman' allows to convert it
-;; to roman numbers.
+;; to roman numbers.  With an optional argument,
+;; `org-export-get-headline-number' returns a number to unnumbered
+;; headlines (used for internal id).
+;;
+;; `org-export-get-headline-id' returns the unique internal id of a
+;; headline.
 ;;
 ;; `org-export-low-level-p', `org-export-first-sibling-p' and
 ;; `org-export-last-sibling-p' are three useful predicates when it
@@ -3807,17 +3825,40 @@ and the last level being considered as high enough, or nil."
       (let ((level (org-export-get-relative-level headline info)))
         (and (> level limit) (- level limit))))))
 
+(defun org-export-get-headline-id (headline info)
+  "Return a unique ID for HEADLINE.
+INFO is a plist holding contextual information."
+  (concat
+   (if (org-export-numbered-headline-p headline info)
+       "sec-" "unnumbered-")
+   (mapconcat #'number-to-string
+	      (if (org-export-numbered-headline-p headline info)
+		  (org-export-get-headline-number headline info)
+		(org-export-get-unnumberd-headline-id headline info)) "-")))
+
 (defun org-export-get-headline-number (headline info)
-  "Return HEADLINE numbering as a list of numbers.
+  "Return numbered HEADLINE numbering as a list of numbers.
+INFO is a plist holding contextual information."
+  (and (org-export-numbered-headline-p headline info)
+       (cdr (assoc headline (plist-get info :headline-numbering)))))
+
+(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)))))
 
 (defun org-export-numbered-headline-p (headline info)
   "Return a non-nil value if HEADLINE element should be numbered.
 INFO is a plist used as a communication channel."
-  (let ((sec-num (plist-get info :section-numbers))
-	(level (org-export-get-relative-level headline info)))
-    (if (wholenump sec-num) (<= level sec-num) sec-num)))
+  (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))
+    (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))))
 
 (defun org-export-number-to-roman (n)
   "Convert integer N into a roman numeral."
-- 
2.1.0