Exporting user labels to non-latex backends

Exporting user labels to non-latex backends

[Stefano Ghirlanda]

Hi everyone,

There may be an issue with using #+name: labels when exporting to
non-latex backends. For example:

---
\begin{equation}
  \label{eq:x}
   x = 1
\end{equation}

cref:eq:x
---

Exports correctly to markdown, but:

---
#+name: eq:x
\begin{equation}
   x = 1
\end{equation}

cref:eq:x
---

exports with a mix of org labels and user labels:

---
\begin{equation}
  \label{orgf29908c}
  x = 1
\end{equation}

equation \ref{eq:x}
---

This does not affect latex export because one can set
org-latex-prefer-user-labels, but most other backends do not seem to
have this setting. I think there is one for HTML but I could not find
one for markdown. Would it be useful to have a global setting for all
backends? Or, is there a way to fix this with the current code base?

Best,
Stefano



-- 
Stefano Ghirlanda
CTO, DataWorks - https://dataworks.consulting
Guest Professor - Stockholm University Centre for Cultural Evolution

Re: Exporting user labels to non-latex backends

[Ihor Radchenko]

Stefano Ghirlanda <dr.ghirlanda@gmail.com> writes:

> There may be an issue with using #+name: labels when exporting to
> non-latex backends. For example:
> ...
> #+name: eq:x
> \begin{equation}
>    x = 1
> \end{equation}
>
> cref:eq:x
> ---
>
> exports with a mix of org labels and user labels:
>
> ---
> \begin{equation}
>   \label{orgf29908c}
>   x = 1
> \end{equation}
>
> equation \ref{eq:x}
> ---
>
> This does not affect latex export because one can set
> org-latex-prefer-user-labels, but most other backends do not seem to
> have this setting. I think there is one for HTML but I could not find
> one for markdown. Would it be useful to have a global setting for all
> backends? Or, is there a way to fix this with the current code base?

AFAIK, there is nothing to fix - the current behavior is intentional:

Commit 981f25031dd17
* lisp/ox-md.el (org-md-latex-environment, org-md-latex-fragment):
These two new filters wrap LaTeX maths in $ / $$ TeX-style notation.
While ox-md endeavours to adhere to the original Markdown specification,
and not any particular variant, the original specification does not deal
with LaTeX fragments at all, and so this change does not reduce how
faithfully the original specification is followed.
There is a major upside to this though. Of the many Markdown variants
that have emerged, those that support LaTeX very often exclusively
support TeX style notation.  This change thus improves the utility of
the Markdown export for many use cases, and deviates no more from the
original specification that the current method.

Please, provide more context about the problem you are trying to solve.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Exporting user labels to non-latex backends

[Stefano Ghirlanda]

Thanks! I was just under the impression that #+name: was the preferred
way of labeling things and I was surprised it did not work as I
expected on some backends. I was surprised to see that

#+name: eq:x

gives a different result from

\label{eq:x}

as I understood the two things to be equivalent.

Thanks for the clarification,
Stefano

On Fri, May 17, 2024 at 6:43 AM Ihor Radchenko <yantar92@posteo.net> wrote:
>
> Stefano Ghirlanda <dr.ghirlanda@gmail.com> writes:
>
> > There may be an issue with using #+name: labels when exporting to
> > non-latex backends. For example:
> > ...
> > #+name: eq:x
> > \begin{equation}
> >    x = 1
> > \end{equation}
> >
> > cref:eq:x
> > ---
> >
> > exports with a mix of org labels and user labels:
> >
> > ---
> > \begin{equation}
> >   \label{orgf29908c}
> >   x = 1
> > \end{equation}
> >
> > equation \ref{eq:x}
> > ---
> >
> > This does not affect latex export because one can set
> > org-latex-prefer-user-labels, but most other backends do not seem to
> > have this setting. I think there is one for HTML but I could not find
> > one for markdown. Would it be useful to have a global setting for all
> > backends? Or, is there a way to fix this with the current code base?
>
> AFAIK, there is nothing to fix - the current behavior is intentional:
>
> Commit 981f25031dd17
> * lisp/ox-md.el (org-md-latex-environment, org-md-latex-fragment):
> These two new filters wrap LaTeX maths in $ / $$ TeX-style notation.
> While ox-md endeavours to adhere to the original Markdown specification,
> and not any particular variant, the original specification does not deal
> with LaTeX fragments at all, and so this change does not reduce how
> faithfully the original specification is followed.
> There is a major upside to this though. Of the many Markdown variants
> that have emerged, those that support LaTeX very often exclusively
> support TeX style notation.  This change thus improves the utility of
> the Markdown export for many use cases, and deviates no more from the
> original specification that the current method.
>
> Please, provide more context about the problem you are trying to solve.
>
> --
> Ihor Radchenko // yantar92,
> Org mode contributor,
> Learn more about Org mode at <https://orgmode.org/>.
> Support Org development at <https://liberapay.com/org-mode>,
> or support my work at <https://liberapay.com/yantar92>



-- 
Stefano Ghirlanda
CTO, DataWorks - https://dataworks.consulting
Guest Professor - Stockholm University Centre for Cultural Evolution