Use `\tag{}` info for eq cross referencing in the HTML book output

[AlbertLei]

In writing papers one sometimes needs to give an equation a special name, using the \tag{} command. A minimal example is as follows:

$$
a \ge b \tag{IC}
$${#eq-ic}

[Equation (-@eq-ic)] is nice.

The generated HTML book output made two 'mistakes'

• it uses both (1) and (IC) as equation tags
• More importantly, it uses 1 rather than IC for cross referencing.

Meanwhile, the PDF output is normal:

I wish to achieve the same output as in the PDF output. Is there any workaround?

I am using quarto 0.3.18 (I also have pandoc 2.17.0.1 installed, not sure whether this matters). Currently I work around by defining Pandoc metadata eq.ic: IC and then Equation {{< meta eq.ic >}}. It works well for me, both HTML and PDF. But I hope there is a more direct way to do this.

[AlbertLei]

Oops! I just (accidentally) found that raw LaTeX works in HTML by coping&pasting my LaTeX code.

\begin{equation}
a \ge b \tag{IC}
\label{eq:ic}
\end{equation}

Equation \eqref{eq:ic} is nice.

Even \eqref{} works. How many keystrokes can be saved!
I find the raw LaTeX method way better than the {#eq-name} syntax in the official document. May I be informed where this is documented? So I do not need to depend on my serendipity or use the pandoc metadata workaround.

[jjallaire]

Re-opening to investigate if there are additional things we should be doing for equation references.

[jjallaire]

It seems likely that we can read the tags out of the LaTeX when indexing the equation and then include that in the reference.

[AlbertLei]

Hi jjallaire, thanks for your response. Yes it would be great if the {#eq-name} syntax can work well with \tag{} in the HTML output. But if the raw LaTeX method works here, why bother inventing a new syntax? After all, I guess most people who are using both \tag{} and \ref{} are already familiar with the basic LaTeX syntax. Am I missing sth here?

[jjallaire]

While Pandoc happens to make \tag{} and \ref() work for HTML, they don't work for docx, epub, odt, etc. We want a syntax that works across all formats. We also want consistency, so when teaching people how to tag and reference things we don't there to be special rules and syntax for equations.

We could certainly make both work across all formats. My concern here would be that then people would by trying to use \ref and \label for other things like figures and tables, and we'd be into supporting two parallel syntaxes for crossrefs.

[AlbertLei]

Thanks for your clarification. I was not aware that the quarto referencing syntax also supported word and epub.

I guess it is mathjax that supports \label{}, \tag{} and \eqref{} here. So these commands probably not work when the output is word or epub.

I have no idea how to make \tag{} and referencing work in word. But for HTML it suffices to leverage the power of mathjax here. Currently, quarto seems not utilize the \tag{} syntax. The documentation writes that "the equation number is included via \qquad", where it makes more sense to use \tag{}.

The newest KaTeX and mathjax both support \tag{}. KaTeX seems still not support \ref and eqref though.