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