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?
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
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.)
