9

In the org-mode example below, I would like to be able to specify the label name to be used by the latex export back-end. Is there such a way?

I have two reasons:

  1. To be able to mix org-style references [[fig:label]] and latex-style references \ref{fig:label} in the same document. This is not necessary (in fact, probably bad practice) if I have everything in the org document. However, sometimes I \input{} an external latex block with a \ref{} somewhere, so I need to control the named reference.

  2. Whenever I export my document, I will get a different latex label (here: orgee8497f). This will have my git back-end think that the document has changed, when in fact it hasn't.

Org source:

This is some text. Here I can refer to Figure [[fig:label]]. However, if I try to refer to \ref{fig:label}, I get an undefined reference. #+CAPTION: This is a caption to the figure. #+NAME: fig:label \begin{figure} figure stuff goes here \end{figure}

Latex export:

This is some text. Here I can refer to Figure \ref{orgee8497f}. However, if I try to refer to \ref{fig:label}, I get an undefined reference. \begin{figure} figure stuff goes here \caption{\label{orgee8497f} This is a caption to the figure.} \end{figure}
Improve this question

1 Answer 1

Reset to default
9

Set the variable org-latex-prefer-user-labels to something non-nil (you can use customize to do it). The doc string of the variable says:

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

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.

You can customize this variable.

Improve this answer

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.