Variable: org-latex-prefer-user-labels

org-latex-prefer-user-labels is a customizable variable defined in ox-latex.el.gz.

Value

nil

Documentation

Use user-provided labels instead of internal ones when non-nil.

When this variable is non-nil, Org will use the value of CUSTOM_ID property, NAME keyword or Org target 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_EXPORT latex
  And this is still section \ref{sec:foo}.
  #+END_EXPORT

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}.

A non-default value of org-latex-reference-command will change the command (\ref by default) used to create label references.

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.

This variable was added, or its default value changed, in Org version
8.3.

Source Code

;; Defined in /usr/src/emacs/lisp/org/ox-latex.el.gz
(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
CUSTOM_ID property, NAME keyword or Org target 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_EXPORT latex
  And this is still section \\ref{sec:foo}.
  #+END_EXPORT

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}.

A non-default value of `org-latex-reference-command' will change the
command (\\ref by default) used to create label references.

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 "26.1"
  :package-version '(Org . "8.3"))