From: Richard Lawrence <richard.lawrence@berkeley.edu>
To: Nicolas Goaziou <n.goaziou@gmail.com>
Cc: emacs-orgmode@gnu.org
Subject: Re: [patch] Support CUSTOM_ID property in latex export
Date: Sat, 22 Feb 2014 16:37:05 -0800 [thread overview]
Message-ID: <87d2iek6ku.fsf@aquinas.i-did-not-set--mail-host-address--so-tickle-me> (raw)
In-Reply-To: <878ut31ov6.fsf@gmail.com>
[-- 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.)
next prev parent reply other threads:[~2014-02-23 0:39 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-02-15 20:19 [patch] Support CUSTOM_ID property in latex export Richard Lawrence
2014-02-15 22:44 ` Nicolas Goaziou
2014-02-15 23:43 ` Richard Lawrence
2014-02-16 9:10 ` Nicolas Goaziou
2014-02-16 20:10 ` Richard Lawrence
2014-02-18 21:56 ` Nicolas Goaziou
2014-02-18 22:35 ` Richard Lawrence
2014-02-19 12:43 ` Nicolas Goaziou
2014-02-20 5:04 ` Richard Lawrence
2014-02-21 19:35 ` Richard Lawrence
2014-02-22 9:24 ` Nicolas Goaziou
2014-02-22 20:35 ` Richard Lawrence
2014-02-22 22:31 ` Nicolas Goaziou
2014-02-23 0:37 ` Richard Lawrence [this message]
2014-02-23 8:37 ` Nicolas Goaziou
2014-02-23 8:53 ` Achim Gratz
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87d2iek6ku.fsf@aquinas.i-did-not-set--mail-host-address--so-tickle-me \
--to=richard.lawrence@berkeley.edu \
--cc=emacs-orgmode@gnu.org \
--cc=n.goaziou@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).