Equation numbering in Documenter.jl

Tooling
1

Equation numbering was discussed in this issue (see also this message). The solution proposed above by @mortenpi indeed works with the
MathJax3 engine, but not with the… LaTeXWriter!

Description of the problem

The following markdown input

```math
\begin{equation}
  \label{foo}
  E = mc^2
\end{equation}
```

Equation \eqref{foo} means that ...

delivers the following LaTeX output

\begin{equation*}
\begin{split}\begin{equation}
  \label{foo}
  E = mc^2
\end{equation}\end{split}\end{equation*}


Equation {\textbackslash}eqref\{foo\} means that ...

The problems are

  1. the nested equation*/equation environments,
  2. \eqref{\foo} which is automatically replaced with {\textbackslash}eqref\{foo\}.

Fix for problem 1

In function latex(io::IO, math::Markdown.LaTeX), the following regexp

r"^\\begin\{align\*?\}"

should be replaced with

r"^\\begin\{((equation)|(align)|(gather)|(flalign)|(multline)|(alignat)|(split))\*?\}"

Note that the above regexp would accept a \begin{split*}...\end{split*} construct, which is not valid LaTeX/AMSMath. In my view, this is not an issue: the LaTeX writer is not a parser, and should not be doing the work of the latex engine itself.

I will submit a PR for this minor correction.

Fix for problem 2

A temporary fix would be to enclose the \eqref statement in double
back-ticks (inline math), like so

```math
\begin{equation}
  \label{foo}
  E = mc^2
\end{equation}
```

Equation ``\eqref{foo}`` means that ...

I personally dislike this solution. Clearly, the problem lies with the function latexesc(io, ch::AbstractChar), where '\\' gets replaced with {\\textbackslash}. Frankly, I hardly see the point of this substitution. This kills the possibility of using LaTeX macros in the markdown file (in case we would be mostly interested in the LaTeX output, for example).

Maybe a more appropriate rule would be

  • backslashes occuring outside code blocks (single or triple backticks) → do not perform the substitution,
  • backslashes occuring inside code blocks → perform the substitution.

Alternatively, we could look at how pandoc handles such cases.

Any thoughts?