From mboxrd@z Thu Jan 1 00:00:00 1970 From: Richard Lawrence Subject: Re: [patch] Support CUSTOM_ID property in latex export Date: Sat, 22 Feb 2014 16:37:05 -0800 Message-ID: <87d2iek6ku.fsf@aquinas.i-did-not-set--mail-host-address--so-tickle-me> References: <87y51cgmc5.fsf@aquinas.i-did-not-set--mail-host-address--so-tickle-me> <87mwhsro6c.fsf@gmail.com> <87vbwggcwb.fsf@berkeley.edu> <87iosfs9sb.fsf@gmail.com> <871tz24y4q.fsf@aquinas.i-did-not-set--mail-host-address--so-tickle-me> <87lhx82igv.fsf@gmail.com> <87mwho9hij.fsf@aquinas.i-did-not-set--mail-host-address--so-tickle-me> <87d2ij2ryp.fsf@gmail.com> <87ob20gsxv.fsf@aquinas.i-did-not-set--mail-host-address--so-tickle-me> <878ut31ov6.fsf@gmail.com> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:46565) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WHN5s-0007ZY-1H for emacs-orgmode@gnu.org; Sat, 22 Feb 2014 19:39:00 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WHN5n-0006nJ-7Y for emacs-orgmode@gnu.org; Sat, 22 Feb 2014 19:38:55 -0500 Received: from mail-pd0-f179.google.com ([209.85.192.179]:48102) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WHN5m-0006n5-Uw for emacs-orgmode@gnu.org; Sat, 22 Feb 2014 19:38:51 -0500 Received: by mail-pd0-f179.google.com with SMTP id fp1so4766760pdb.24 for ; Sat, 22 Feb 2014 16:38:50 -0800 (PST) In-Reply-To: <878ut31ov6.fsf@gmail.com> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Nicolas Goaziou Cc: emacs-orgmode@gnu.org --=-=-= 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. --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-Support-using-CUSTOM_ID-property-to-generate-section.patch Content-Description: Support using CUSTOM_ID to generate section labels >From 07bfc34a48858aa386c0416e592082610c913ef3 Mon Sep 17 00:00:00 2001 From: Richard Lawrence 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 --=-=-= 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.) --=-=-=--