Re: [patch] Support CUSTOM_ID property in latex export

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

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

Hi Nicolas and all,

Here's a new patch that adds a variable org-latex-custom-id-as-label to
control whether CUSTOM_ID should be used to generate labels during LaTeX
export.

Let me know what you think.  In particular, I wasn't sure if I should
provide more information in the defcustom statement beyond :group and
:type (like :package-version?).  Also, does the docstring represent the
trade-offs of using this variable well enough?

I wasn't sure how to get git format-patch to generate a single patch for
the changes between my branch and master (since there are now two
commits on my branch), so this was generated with git diff --patch.  If
you want me to send the commit message, etc. can you let me know how to
do this in whatever way is most convenient for you?  


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: custom-id.patch --]
[-- Type: text/x-diff, Size: 3292 bytes --]

diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index 5815874..df22768 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -375,6 +375,47 @@ 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.
+
+If non-nil, Org will use the value of a headline's CUSTOM_ID
+property as the argument to the \label command for the LaTeX
+section corresponding to the headline.
+
+Setting this variable gives you control over how Org generates
+labels for sections during LaTeX export.  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 when a headline defines a value for
+CUSTOM_ID, Org simply passes this value to \label unchanged.  You
+are responsible for ensuring that the value is a valid LaTeX
+\label key, that it is unique throughout the generated document,
+etc.
+ 
+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)
 
 ;;;; Footnotes
 
@@ -1373,10 +1414,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 org-latex-custom-id-as-label
+				     (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 +1890,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 org-latex-custom-id-as-label
+				    (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

[-- Attachment #3: Type: text/plain, Size: 209 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.)