Re: [patch] Support CUSTOM_ID property in latex export

[Richard Lawrence <richard.lawrence@berkeley.edu>]

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

Hi Nicolas and all,

OK, I think I've got a patch now that addresses everything you asked
for.  It is attached.  This has been quite a learning experience!  Let
me know if other changes are necessary.  


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Support using CUSTOM_ID to generate section labels --]
[-- Type: text/x-diff, Size: 5855 bytes --]

From 07bfc34a48858aa386c0416e592082610c913ef3 Mon Sep 17 00:00:00 2001
From: Richard Lawrence <richard.lawrence@berkeley.edu>
Date: Fri, 21 Feb 2014 11:22:08 -0800
Subject: [PATCH] Support using CUSTOM_ID property to generate section labels
 during LaTeX export
To: emacs-orgmode@gnu.org
Cc: n.goaziou@gmail.com

This allows the user to control how Org generates label keys for
headlines during LaTeX export, and thus to know their keys in advance.
This is useful for e.g. using \ref commands inside of embedded LaTeX
blocks.

* lisp/ox-latex.el:
  (defcustom org-latex-custom-id-as-label): Variable to control using
    CUSTOM_ID values as labels during export

  Backend definition: Add :latex-custom-id-labels option to backend's
    :options-alist, using value of org-latex-custom-id-as-label to
    define its behavior

  (org-latex-headline): Optionally generate label keys based on CUSTOM_ID,
    depending on value of :latex-custom-id-labels option

  (org-latex-link): Optionally generate refs based on CUSTOM_ID,
    depending on value of :latex-custom-id-labels option

This change was discussed in the following thread:
http://thread.gmane.org/gmane.emacs.orgmode/82392
---
 lisp/ox-latex.el |   84 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 73 insertions(+), 11 deletions(-)

diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index 5815874..4ae4bf4 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -106,7 +106,8 @@
 		   (:latex-class-options "LATEX_CLASS_OPTIONS" nil nil t)
 		   (:latex-header "LATEX_HEADER" nil nil newline)
 		   (:latex-header-extra "LATEX_HEADER_EXTRA" nil nil newline)
-		   (:latex-hyperref-p nil "texht" org-latex-with-hyperref t))
+		   (:latex-hyperref-p nil "texht" org-latex-with-hyperref t)
+		   (:latex-custom-id-labels nil nil org-latex-custom-id-as-label))
   :filters-alist '((:filter-options . org-latex-math-block-options-filter)
 		   (:filter-parse-tree . org-latex-math-block-tree-filter)))
 
@@ -375,6 +376,59 @@ which format headlines like for Org version prior to 8.0."
   :package-version '(Org . "8.0")
   :type 'function)
 
+(defcustom org-latex-custom-id-as-label nil
+   "Toggle use of CUSTOM_ID properties for generating section labels.
+
+When this variable is non-nil, Org will use the value of a
+headline's CUSTOM_ID property as the key for the \\label command
+for the LaTeX section corresponding to the headline.
+
+By default, Org generates its own internal section labels for all
+headlines during LaTeX export.  This process ensures that the
+\\label keys are unique and valid, but it means the keys are not
+available in advance of the export process.
+
+Setting this variable gives you control over how Org generates
+labels for sections during LaTeX export, so that you may know
+their keys in advance.  One reason to do this is that it allows
+you to refer to headlines using a single label both in Org's link
+syntax and in embedded LaTeX code.
+
+For example, when this variable is non-nil, a headline like this:
+
+  ** Some section
+     :PROPERTIES:
+     :CUSTOM_ID: sec:foo
+     :END:
+  This is section [[#sec:foo]].
+  #+BEGIN_LATEX
+  And this is still section \\ref{sec:foo}.
+  #+END_LATEX
+
+will be exported to LaTeX as:
+
+  \\subsection{Some section}
+  \\label{sec:foo}
+  This is section \\ref{sec:foo}.
+  And this is still section \\ref{sec:foo}.
+
+Note, however, that setting this variable introduces a limitation
+on the possible values for CUSTOM_ID.  When this variable is
+non-nil and a headline defines a CUSTOM_ID value, Org simply
+passes this value to \\label unchanged.  You are responsible for
+ensuring that the value is a valid LaTeX \\label key, and that no
+other \\label commands with the same key appear elsewhere in your
+document.  (Keys may contain letters, numbers, and the following
+punctuation: '_' '.' '-' ':'.)  There are no such limitations on
+CUSTOM_ID when this variable is nil.
+ 
+For headlines that do not define the CUSTOM_ID property, Org will
+continue to use its default labeling scheme to generate labels
+and resolve links into section references."
+  :group 'org-export-latex
+  :type 'boolean
+  :version "24.5"
+  :package-version '(Org . "8.3"))
 
 ;;;; Footnotes
 
@@ -1373,10 +1427,14 @@ holding contextual information."
 			       todo todo-type priority text tags))
 	   ;; Associate \label to the headline for internal links.
 	   (headline-label
-	    (format "\\label{sec-%s}\n"
-		    (mapconcat 'number-to-string
-			       (org-export-get-headline-number headline info)
-			       "-")))
+	    (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)
+				   "-")))))
 	   (pre-blanks
 	    (make-string (org-element-property :pre-blank headline) 10)))
       (if (or (not section-fmt) (org-export-low-level-p headline info))
@@ -1845,12 +1903,16 @@ INFO is a plist holding contextual information.  See
 	  ;; number.  Otherwise, display description or headline's
 	  ;; title.
 	  (headline
-	   (let ((label
-		  (format "sec-%s"
-			  (mapconcat
-			   'number-to-string
-			   (org-export-get-headline-number destination info)
-			   "-"))))
+	   (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)
+			     "-")))))
 	     (if (and (plist-get info :section-numbers) (not desc))
 		 (format "\\ref{%s}" label)
 	       (format "\\hyperref[%s]{%s}" label
-- 
1.7.10.4


[-- Attachment #3: Type: text/plain, Size: 208 bytes --]


Best,
Richard


(If possible, please encrypt your reply to me using my PGP key:
Key ID: CF6FA646
Fingerprint: 9969 43E1 CF6F A646.
See http://www.ocf.berkeley.edu/~rwl/encryption.html for more information.)