add label to equation in math align block that works with KaTeX engine (vscode interactive session)

[kompre]

Description

Hello,

I have some difficulties while adding label to each equation inside the ams math environment align, but only in the vscode interactive session.

Let me explain.

I like to use python code to generate valid Markdown object (sympy equations) that can be rendered by quarto as equation object. I also like to label each equation so that I can reference them if needed.

The latex output (keep-tex = true) that I want to render looks like this:

\begin{align}
  a &= b \label{eq-a} \\
  c &= 0 \label{eq-c}
\end{align}

The code chunk that generates the equation look like this:

from IPython.display import Markdown, display

string = "\\begin{align} \n a &= b \\label{eq-a} \\\\ \n c &= 0 \\label{eq-c} \\end{align}"

display(Markdown(string))

The above code chunk get rendered correctly in the pdf output, so so in the html (see #4136, but I'm focusing on the pdf).

My issue is with the vscode interactive session, which uses KaTeX as rendering engine and return a ParseError caused by the presence of the \label{} command. (ParseError: KaTeX parse error: Undefined control sequence: \label ...)

This way I cannot see the results of a code chunk while coding, and I would need to render the whole document, which takes a fair bit of time, to see the output of the chunk.

It is a minor issue that really lower my quality of life when working on a document.

So basically, in the final document I want the \label{...} to be present, but I don't want it in the intermediate step. It would be possibile to apply a regex replace only when rendering the pdf output? I was thinking to pass something like the following to the Markdown() fucntion:

\begin{align}
  a &= b %\label{eq-a}
  \\ c &= 0 %\label{eq-c}
\end{align}

So that \label is comment out. Then before rendering the pdf, I would need to find the regular expression %\labe{eq- with just \label{eq- to have working labels in the pdf output.

Is it possible to do such thing?

[mcanouil]

Why do you want to comment/uncomment?

How does this differ from your previous question/answer?

• how to label an equation generated by code using sympy #3232

vscode interactive session

What is that? Are you talking about the Visual Editor from Quarto extension?
(Note that any VSCode instances are "interactive session" which is completely independent of Quarto or anything)

[kompre]

How does this differ from your previous question/answer?

That workaround works well for single equation, i.e. just one equation per environment, so just one label is needed. What I'm trying to do now is to label the equation inside an align environment from the ams package for latex.

The interactive session I'm talking about is the one where start when you run the code cell and print the output. The markdown render engine there is powered by katex, and that engine doesn't like the \label command.

The comment thing is a trick: if I can have that part of the line commented out, I can use the interactive session for previewing the code output, while if can run a filter that uncomment when actually rendering the full document, I can have working labels

[mcanouil]

I still don't know what the "interactive session" is as it definitely is not the "right" term.
Could you share a complete Quarto document and possibly the steps needed to reproduce what you are seeing?

[mcanouil]

Also it seems your question is related to:

• referencing equations inside $$ \begin{align} environment #2275

[kompre]

I've created a "minimal" working example to show my issue, but first I want to stress out that quarto does not really have any issue, because it can render the pdf output as intended. My issue is instead with vscode and its native IPython interpreter (?) that uses KaTeX as rendering engine for Markdown objects, which cannot handle the latex \label command.

here the qmd file:

---
title: "VScode interactive session with *align* environment"
format: pdf
keep-tex: true
keep-md: true
---

# VScode interactive session

While developing a quarto document with vscode, it's possible to run code cell into interactive session (`run cell`)

```{python}
print('hello world')
```

Using `sympy` I can generate valid markdown mathematical expression that are also valid code:


```{python}
from IPython.display import Markdown, display
from sympy import latex, Eq, symbols

# define function that will generate valid markdown to be interpreted by quarto a display equation 

def show(expr, label='default', **kwargs):
    if not 'mul_symbol' in kwargs:
        kwargs['mul_symbol'] = '\,'        
    return display(Markdown(
fr"""
$$
    {latex(expr, **kwargs)}
$${{#eq-{label}}}
"""))


```

The above code let me generate expression that look nice in a pdf.

- here a single equation, which is referenceable (see @eq-1)

```{python}
x, y = symbols('x y')

show(Eq(x,y), label='1')

```

- If I generate a few equation in a row, there is kind of a lot a white space between the rendered equations:


```{python}
a, b, c, d = symbols('a b c d')

show(Eq(x+1,y), label='2')
show(Eq(a,b), label='3')
show(Eq(c,d), label='4')

```

It would be nice then to be able to use the environment from the `ams` latex package such as `gather` or `align`^[I can align expression this way]; I define then a new function:


```{python}
def show_dict(eqn_dict, comment_label=False, environment='align', debug=False, **kwargs):
    if not 'mul_symbol' in kwargs:
        kwargs['mul_symbol'] = '\,'
    
    template = f"\\begin{{{environment}}}\n$body$\n\\end{{{environment}}}"

    eqn_list = []
    for l, e in eqn_dict.items():
        label = ('%' if comment_label else '') + f"\label{{eq-{l}}}"
        eqn_list.append(fr"{latex(e, **kwargs)} {label}")
    
    body = '\n\\\\'.join(eqn_list)    
    
    body = body.replace("=", "&=")
    template = template.replace('$body$', body)
    
    if debug:
        print(template)
    
    return display(Markdown(template))
```

- the same equation as above appear as follows:


```{python}
eqs = {
    5: Eq(x+1, y),
    6: Eq(a, b),
    7: Eq(c, d),
}

print('\label is not commented')
show_dict(eqs)
```

The equations are more compact and nicely align at the $=$ sign. They are also referenceable, albeit I have to use latex syntax:

- `\ref{eq-5}` \rightarrow \ref{eq-5}
- `\eqref{eq-6}` \rightarrow \eqref{eq-6}
- `@eq-7` \rightarrow @eq-7 (quarto citation style does not work with `\label` environment)

If I render the same code passing the flag `comment_label = True`, then the rendered equation are still numbererd in the pdf, but they are not referenceable:

```{python}
# label updated to be unique
eqs = {
    8: Eq(x+1, y),
    9: Eq(a, b),
    10: Eq(c, d),
}

print('\label is commented')
show_dict(eqs, comment_label=True)
```

- `\ref{eq-8}` \rightarrow \ref{eq-8}
- `\eqref{eq-9}` \rightarrow \eqref{eq-9}
- `@eq-10` \rightarrow @eq-10 (quarto citation style *still* does not work with `\label` environment)

which render correctly as pdf: vscode-interactive-session.pdf

The issue I have is when I try to run the cell (quarto: run all cell):

1. when \label is not commented out, I get a ParseError
2. when \label is commented, the Markdown object is rendered correctly.

Since I haven't found a way to change settings for the vscode interactive IPython session, then I was wondering if can do this with quarto capability to do stuff at the rendering step:

• Could be a lua filter that after the python code cell are rendered find and replace istance of %\label with \label, before feeding it to tex engine?
• Or I could define the comment_label as an environment variable that is True by default while I work on the document and run the code cell in the vscode interactive session, but get set to False when I render the comment with quarto proper (I thought of this while writing this post)

Also it seems your question is related to:

• referencing equations inside $$ \begin{align} environment #2275

Kinda related, but not really. The issue there is related to the html output, which I'm not playing with it yet.

[mcanouil]

This has basically nothing to do with Quarto. It's the Jupyter extension for VSCode and the lack of support for label in KaTeX (KaTeX/KaTeX#2003).

There is nothing that can be done on Quarto side, so, I suggest you go report this on the Jupyter extension for VSCode: https://github.com/microsoft/vscode-jupyter/issues

[kompre]

So I was able to solve this with an {{< include _settings.qmd >}} at the start of the document. In the _settings.qmd I would define the flag to add the \label command to my generated equation, while in the main qmd file I would instead have defaults that works well with the KaTeX extension.

This way when I render the quarto project the to produce the pdf output the code cell inside the _settings.qmd get executed, while when I'm just running code cell inside vscode to quickly preview the results, that code cell does not get executed leaving with the sensible defaults that KaTeX like.

I have my cake and can eat it too.