ox-latex: Introduce `org-latex-prefer-user-labels' variable
* lisp/ox-latex.el (org-latex-prefer-user-labels): New variable. (org-latex-custom-id-as-label): Remove variable. (org-latex--label): New function. (org-latex--caption/label-string): (org-latex-headline): (org-latex-inlinetask): (org-latex-latex-environment): (org-latex-link): Use new function. * etc/ORG-NEWS: Document new variable. This variable replaces, and generalizes, `org-latex-custom-id-as-label'.
This commit is contained in:
parent
68eb1d0ab0
commit
4bbc054bd2
|
@ -318,6 +318,8 @@ When non-nil, attachments from archived subtrees are removed.
|
||||||
This variable generalizes ~org-latex-table-caption-above~, which is
|
This variable generalizes ~org-latex-table-caption-above~, which is
|
||||||
now deprecated. In addition to tables, it applies to source blocks,
|
now deprecated. In addition to tables, it applies to source blocks,
|
||||||
special blocks and images. See docstring for more information.
|
special blocks and images. See docstring for more information.
|
||||||
|
*** New option: ~org-latex-prefer-user-labels~
|
||||||
|
See docstring for more information.
|
||||||
*** Export unnumbered headlines
|
*** Export unnumbered headlines
|
||||||
Headlines, for which the property ~UNNUMBERED~ is non-nil, are now
|
Headlines, for which the property ~UNNUMBERED~ is non-nil, are now
|
||||||
exported without section numbers irrespective of their levels. The
|
exported without section numbers irrespective of their levels. The
|
||||||
|
|
163
lisp/ox-latex.el
163
lisp/ox-latex.el
|
@ -115,7 +115,6 @@
|
||||||
(:latex-active-timestamp-format nil nil org-latex-active-timestamp-format)
|
(:latex-active-timestamp-format nil nil org-latex-active-timestamp-format)
|
||||||
(:latex-caption-above nil nil org-latex-caption-above)
|
(:latex-caption-above nil nil org-latex-caption-above)
|
||||||
(:latex-classes nil nil org-latex-classes)
|
(:latex-classes nil nil org-latex-classes)
|
||||||
(:latex-custom-id-labels nil nil org-latex-custom-id-as-label)
|
|
||||||
(:latex-default-figure-position nil nil org-latex-default-figure-position)
|
(:latex-default-figure-position nil nil org-latex-default-figure-position)
|
||||||
(:latex-default-table-environment nil nil org-latex-default-table-environment)
|
(:latex-default-table-environment nil nil org-latex-default-table-environment)
|
||||||
(:latex-default-table-mode nil nil org-latex-default-table-mode)
|
(:latex-default-table-mode nil nil org-latex-default-table-mode)
|
||||||
|
@ -136,6 +135,7 @@
|
||||||
(:latex-listings-options nil nil org-latex-listings-options)
|
(:latex-listings-options nil nil org-latex-listings-options)
|
||||||
(:latex-minted-langs nil nil org-latex-minted-langs)
|
(:latex-minted-langs nil nil org-latex-minted-langs)
|
||||||
(:latex-minted-options nil nil org-latex-minted-options)
|
(:latex-minted-options nil nil org-latex-minted-options)
|
||||||
|
(:latex-prefer-user-labels nil nil org-latex-prefer-user-labels)
|
||||||
(:latex-subtitle-format nil nil org-latex-subtitle-format)
|
(:latex-subtitle-format nil nil org-latex-subtitle-format)
|
||||||
(:latex-subtitle-separate nil nil org-latex-subtitle-separate)
|
(:latex-subtitle-separate nil nil org-latex-subtitle-separate)
|
||||||
(:latex-table-scientific-notation nil nil org-latex-table-scientific-notation)
|
(:latex-table-scientific-notation nil nil org-latex-table-scientific-notation)
|
||||||
|
@ -237,6 +237,61 @@ symbols are: `image', `table', `src-block' and `special-block'."
|
||||||
(const :tag "Source code" src-block)
|
(const :tag "Source code" src-block)
|
||||||
(const :tag "Special blocks" special-block))))
|
(const :tag "Special blocks" special-block))))
|
||||||
|
|
||||||
|
(defcustom org-latex-prefer-user-labels nil
|
||||||
|
"Use user-provided labels instead of internal ones when non-nil.
|
||||||
|
|
||||||
|
When this variable is non-nil, Org will use the value of
|
||||||
|
a headline's CUSTOM_ID property and NAME values as the key for
|
||||||
|
the \\label commands generated.
|
||||||
|
|
||||||
|
By default, Org generates its own internal labels 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 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
|
||||||
|
various elements 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 and NAME. When this
|
||||||
|
variable is non-nil, Org passes their 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 and NAME when this variable
|
||||||
|
is nil.
|
||||||
|
|
||||||
|
For headlines that do not define the CUSTOM_ID property or
|
||||||
|
elements without a NAME, Org will continue to use its default
|
||||||
|
labeling scheme to generate labels and resolve links into proper
|
||||||
|
references."
|
||||||
|
:group 'org-export-latex
|
||||||
|
:type 'boolean
|
||||||
|
:version "25.1"
|
||||||
|
:package-version '(Org . "8.3"))
|
||||||
|
|
||||||
;;;; Preamble
|
;;;; Preamble
|
||||||
|
|
||||||
(defcustom org-latex-default-class "article"
|
(defcustom org-latex-default-class "article"
|
||||||
|
@ -477,59 +532,6 @@ The function result will be used in the section format string."
|
||||||
:package-version '(Org . "8.0")
|
:package-version '(Org . "8.0")
|
||||||
:type 'function)
|
: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 "25.1"
|
|
||||||
:package-version '(Org . "8.3"))
|
|
||||||
|
|
||||||
;;;; Footnotes
|
;;;; Footnotes
|
||||||
|
|
||||||
|
@ -1043,6 +1045,30 @@ INFO is a plist holding contextual information."
|
||||||
(let ((type (org-element-type element)))
|
(let ((type (org-element-type element)))
|
||||||
(memq (if (eq type 'link) 'image type) above)))))
|
(memq (if (eq type 'link) 'image type) above)))))
|
||||||
|
|
||||||
|
(defun org-latex--label (element info &optional force full)
|
||||||
|
"Return an appropriate label for ELEMENT.
|
||||||
|
INFO is the current export state, as a plist.
|
||||||
|
|
||||||
|
Return nil if ELEMENT has no NAME affiliated keyword or no
|
||||||
|
CUSTOM_ID property, unless FORCE is non-nil. In this case always
|
||||||
|
return a unique label.
|
||||||
|
|
||||||
|
Eventually, if FULL is non-nil, wrap label within \"\\label{}\"."
|
||||||
|
(let* ((user-label
|
||||||
|
(org-element-property
|
||||||
|
(if (memq (org-element-type element) '(headline inlinetask))
|
||||||
|
:CUSTOM_ID
|
||||||
|
:name)
|
||||||
|
element))
|
||||||
|
(label
|
||||||
|
(and (or user-label force)
|
||||||
|
(if (and user-label (plist-get info :latex-prefer-user-labels))
|
||||||
|
user-label
|
||||||
|
(org-export-get-reference element info)))))
|
||||||
|
(cond ((not full) label)
|
||||||
|
(label (format "\\label{%s}\n" label))
|
||||||
|
(t ""))))
|
||||||
|
|
||||||
(defun org-latex--caption/label-string (element info)
|
(defun org-latex--caption/label-string (element info)
|
||||||
"Return caption and label LaTeX string for ELEMENT.
|
"Return caption and label LaTeX string for ELEMENT.
|
||||||
|
|
||||||
|
@ -1050,9 +1076,7 @@ INFO is a plist holding contextual information. If there's no
|
||||||
caption nor label, return the empty string.
|
caption nor label, return the empty string.
|
||||||
|
|
||||||
For non-floats, see `org-latex--wrap-label'."
|
For non-floats, see `org-latex--wrap-label'."
|
||||||
(let* ((label
|
(let* ((label (org-latex--label element info nil t))
|
||||||
(if (not (org-element-property :name element)) ""
|
|
||||||
(format "\\label{%s}" (org-export-get-reference element info))))
|
|
||||||
(main (org-export-get-caption element))
|
(main (org-export-get-caption element))
|
||||||
(short (org-export-get-caption element t))
|
(short (org-export-get-caption element t))
|
||||||
(caption-from-attr-latex
|
(caption-from-attr-latex
|
||||||
|
@ -1564,13 +1588,9 @@ holding contextual information."
|
||||||
(full-text (funcall (plist-get info :latex-format-headline-function)
|
(full-text (funcall (plist-get info :latex-format-headline-function)
|
||||||
todo todo-type priority text tags info))
|
todo todo-type priority text tags info))
|
||||||
;; Associate \label to the headline for internal links.
|
;; Associate \label to the headline for internal links.
|
||||||
(headline-label
|
(headline-label (org-latex--label headline info t t))
|
||||||
(format "\\label{%s}\n"
|
|
||||||
(or (and (plist-get info :latex-custom-id-labels)
|
|
||||||
(org-element-property :CUSTOM_ID headline))
|
|
||||||
(org-export-get-reference headline info))))
|
|
||||||
(pre-blanks
|
(pre-blanks
|
||||||
(make-string (org-element-property :pre-blank headline) 10)))
|
(make-string (org-element-property :pre-blank headline) ?\n)))
|
||||||
(if (or (not section-fmt) (org-export-low-level-p headline info))
|
(if (or (not section-fmt) (org-export-low-level-p headline info))
|
||||||
;; This is a deep sub-tree: export it as a list item. Also
|
;; This is a deep sub-tree: export it as a list item. Also
|
||||||
;; export as items headlines for which no section format has
|
;; export as items headlines for which no section format has
|
||||||
|
@ -1727,10 +1747,7 @@ holding contextual information."
|
||||||
(org-export-get-tags inlinetask info)))
|
(org-export-get-tags inlinetask info)))
|
||||||
(priority (and (plist-get info :with-priority)
|
(priority (and (plist-get info :with-priority)
|
||||||
(org-element-property :priority inlinetask)))
|
(org-element-property :priority inlinetask)))
|
||||||
(contents (concat
|
(contents (concat (org-latex--label inlinetask info) contents)))
|
||||||
(let ((label (org-element-property :CUSTOM_ID inlinetask)))
|
|
||||||
(and label (format "\\label{%s}\n" label)))
|
|
||||||
contents)))
|
|
||||||
(funcall (plist-get info :latex-format-inlinetask-function)
|
(funcall (plist-get info :latex-format-inlinetask-function)
|
||||||
todo todo-type priority title tags contents info)))
|
todo todo-type priority title tags contents info)))
|
||||||
|
|
||||||
|
@ -1884,9 +1901,7 @@ CONTENTS is nil. INFO is a plist holding contextual information."
|
||||||
(insert value)
|
(insert value)
|
||||||
(goto-char (point-min))
|
(goto-char (point-min))
|
||||||
(forward-line)
|
(forward-line)
|
||||||
(insert
|
(insert (org-latex--label latex-environment info nil t))
|
||||||
(format "\\label{%s}\n"
|
|
||||||
(org-export-get-reference latex-environment info)))
|
|
||||||
(buffer-string))))))
|
(buffer-string))))))
|
||||||
|
|
||||||
|
|
||||||
|
@ -2097,11 +2112,7 @@ INFO is a plist holding contextual information. See
|
||||||
;; number. Otherwise, display description or headline's
|
;; number. Otherwise, display description or headline's
|
||||||
;; title.
|
;; title.
|
||||||
(headline
|
(headline
|
||||||
(let* ((custom-label
|
(let ((label (org-latex--label destination info t)))
|
||||||
(and (plist-get info :latex-custom-id-labels)
|
|
||||||
(org-element-property :CUSTOM_ID destination)))
|
|
||||||
(label (or custom-label
|
|
||||||
(org-export-get-reference destination info))))
|
|
||||||
(if (and (not desc)
|
(if (and (not desc)
|
||||||
(org-export-numbered-headline-p destination info))
|
(org-export-numbered-headline-p destination info))
|
||||||
(format "\\ref{%s}" label)
|
(format "\\ref{%s}" label)
|
||||||
|
@ -2111,7 +2122,7 @@ INFO is a plist holding contextual information. See
|
||||||
(org-element-property :title destination) info))))))
|
(org-element-property :title destination) info))))))
|
||||||
;; Fuzzy link points to a target. Do as above.
|
;; Fuzzy link points to a target. Do as above.
|
||||||
(otherwise
|
(otherwise
|
||||||
(let ((ref (org-export-get-reference destination info)))
|
(let ((ref (org-latex--label destination info t)))
|
||||||
(if (not desc) (format "\\ref{%s}" ref)
|
(if (not desc) (format "\\ref{%s}" ref)
|
||||||
(format "\\hyperref[%s]{%s}" ref desc)))))))
|
(format "\\hyperref[%s]{%s}" ref desc)))))))
|
||||||
;; Coderef: replace link with the reference name or the
|
;; Coderef: replace link with the reference name or the
|
||||||
|
|
Loading…
Reference in New Issue