Summary. The purpose of this document is to test LaTeX math in DocOnce with various output formats. Most LaTeX math constructions are renedered correctly by MathJax in plain HTML, but some combinations of constructions may fail. Unfortunately, only a subset of what works in html MathJax also works in sphinx MathJax. The same is true for markdown MathJax expresions (e.g., Jupyter notebooks). Tests and examples are provided to illustrate what may go wrong.
The recommendation for writing math that translates to MathJax in
html, sphinx, and markdown is to stick to the environments \[
... \]
, equation
, equation*
, align
, align*
, alignat
, and
alignat*
only. Test the math with sphinx output; if it works in that
format, it should work elsewhere too.
The current version of the document is translated from DocOnce source to the format html.
We can get an inline equation
$u(t)=e^{-at}$
rendered as \( u(t)=e^{-at} \).
An equation with number,
!bt
\begin{equation} u(t)=e^{-at} label{eq1a}\end{equation}
!et
looks like
$$ \begin{equation} u(t)=e^{-at} \label{_eq1a}\end{equation} $$Maybe this multi-line version is what we actually prefer to write:
!bt
\begin{equation}
u(t)=e^{-at}
label{eq1b}
\end{equation}
!et
The result is the same:
$$ \begin{equation} u(t)=e^{-at} \label{_eq1b} \end{equation} $$We can refer to this equation through its label eq1b
: \eqref{_eq1b}.
MathJax has historically had some problems with rendering many LaTeX
math environments, but the align*
and align
environments have
always worked.
!bt
\begin{align*}
u(t)&=e^{-at}\\
v(t) - 1 &= \frac{du}{dt}
\end{align*}
!et
Result:
$$ \begin{align*} u(t)&=e^{-at}\\ v(t) - 1 &= \frac{du}{dt} \end{align*} $$Here, we use align
with user-prescribed labels:
!bt
\begin{align}
u(t)&=e^{-at}
label{eq2b}\\
v(t) - 1 &= \frac{du}{dt}
label{eq3b}
\end{align}
!et
Result:
$$ \begin{align} u(t)&=e^{-at} \label{_eq2b}\\ v(t) - 1 &= \frac{du}{dt} \label{_eq3b} \end{align} $$We can refer to the last equations as the system \eqref{_eq2b}-\eqref{_eq3b}.
In LaTeX, equations within an align
environment is automatically
given numbers. To ensure that an html document with MathJax gets the
same equation numbers as its latex/pdflatex companion, DocOnce
generates labels in equations where there is no label prescribed. For
example,
!bt
\begin{align}
u(t)&=e^{-at}
\\
v(t) - 1 &= \frac{du}{dt}
\end{align}
!et
is edited to something like
!bt
\begin{align}
u(t)&=e^{-at}
label{_auto5}\\
v(t) - 1 &= \frac{du}{dt}
label{_auto6}
\end{align}
!et
and the output gets the two equation numbered.
$$ \begin{align} u(t)&=e^{-at} \label{_auto1}\\ v(t) - 1 &= \frac{du}{dt} \label{_auto2} \end{align} $$The align
environment can be used with two &
alignment characters, e.g.,
!bt
\begin{align}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\
u(0,t) &= u_0(x), & x\in [0,L]
\end{align}
!et
The result in html becomes
$$ \begin{align} \frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L), \ t\in (0,T] \label{_auto3}\\ u(0,t) &= u_0(x), & x\in [0,L] \label{_auto4} \end{align} $$A better solution is usually to use an alignat
environment:
!bt
\begin{alignat}{2}
\frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L),
\ t\in (0,T]\\
u(0,t) &= u_0(x), & x\in [0,L]
\end{alignat}
!et
with the rendered result
$$ \begin{alignat}{2} \frac{\partial u}{\partial t} &= \nabla^2 u, & x\in (0,L), \ t\in (0,T]\\ u(0,t) &= u_0(x), & x\in [0,L] \end{alignat} $$Let us try the old eqnarray*
environment.
!bt
\begin{eqnarray*}
u(t)&=& e^{-at}\\
v(t) - 1 &=& \frac{du}{dt}
\end{eqnarray*}
!et
which results in
$$ \begin{eqnarray*} u(t)&=& e^{-at}\\ v(t) - 1 &=& \frac{du}{dt} \end{eqnarray*} $$Here we use eqnarray
with labels:
!bt
\begin{eqnarray}
u(t)&=& e^{-at}
label{eq2c}\\
v(t) - 1 &=& \frac{du}{dt}
label{eq3c}
\end{eqnarray}
!et
which results in
$$ \begin{eqnarray} u(t)&=& e^{-at} \label{_eq2c}\\ v(t) - 1 &=& \frac{du}{dt} \label{_eq3c} \end{eqnarray} $$Can we refer to the last equations as the system \eqref{_eq2c}-\eqref{_eq3c} in the html format?
multiline
environment with label and number The LaTeX code
!bt
\begin{multline}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
label{multiline:eq1}
\end{multline}
!et
gets rendered as
$$ \begin{multline} \int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) + f(a+(j+1)h)) \\ =\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh) \label{_multiline:eq1} \end{multline} $$and we can hopefully refer to the Trapezoidal rule as the formula \eqref{_multiline:eq1}.
Although align
can be used to split too long equations, a more obvious
command is split
:
!bt
\begin{equation}
\begin{split}
\int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) +
f(a+(j+1)h)) \\
=\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh)
\end{split}
\end{equation}
!et
The result becomes
$$ \begin{equation} \begin{split} \int_a^b f(x)dx = \sum_{j=0}^{n} \frac{1}{2} h(f(a+jh) + f(a+(j+1)h)) \\ =\frac{h}{2}f(a) + \frac{h}{2}f(b) + \sum_{j=1}^n f(a+jh) \end{split} \label{_auto5} \end{equation} $$First we use the plain old pmb package for bold math. The formula
!bt
\[ \frac{\partial\u}{\partial t} +
\u\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
!et
and the inline expression $\nabla\u (\pmb{x})\cdot\pmb{n}$
(with suitable newcommands using pmb)
get rendered as
and \( \nabla\u (\pmb{x})\cdot\pmb{n} \).
Somewhat nicer fonts may appear with the more modern \bm
command:
!bt
\[ \frac{\partial\ubm}{\partial t} +
\ubm\cdot\nabla\ubm = \nu\nabla^2\ubm -
\frac{1}{\varrho}\nabla p,\]
!et
(backslash ubm
is a newcommand for bold math \( u \)), for which we get
Moreover,
$\nabla\boldsymbol{u}(\boldsymbol{x})\cdot\boldsymbol{n}$
becomes \( \nabla\boldsymbol{u}(\boldsymbol{x})\cdot\boldsymbol{n} \).
Note: for the html format, \bm
was substituted by DocOnce
to \boldsymbol
.
Finally, we collect some problematic formulas in MathJax. They all work fine in LaTeX. Most of them look fine in html too, but some fail in sphinx, ipynb, or markdown.
The LaTeX code
!bt
\[ {\color{blue}\frac{\partial\u}{\partial t}} +
\nabla\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
!et
results in
$$ {\color{blue}\frac{\partial\u}{\partial t}} + \nabla\cdot\nabla\u = \nu\nabla^2\u - \frac{1}{\varrho}\nabla p,$$Sometimes one must be extra careful with the LaTeX syntax to get sphinx MathJax to render a formula correctly. Consider the combination of a bar over a bold math symbol:
!bt
\[ \bar\f = f_c^{-1}\f,\]
!et
which for html output results in
$$ \bar\f = f_c^{-1}\f.$$With sphinx, this formula is not rendered. However, using curly braces for the bar,
!bt
\[ \bar{\f} = f_c^{-1}\f,\]
!et
makes the output correct also for sphinx:
$$ \bar{\f} = f_c^{-1}\f,$$Here is an align
environment with a label and the pmatrix
environment for matrices and vectors in LaTeX.
!bt
\begin{align}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\
-G_3 & G_3 + G_4 & 0 & -G_4 \\
-G_2 & 0 & G_1 + G_2 & 0 \\
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\
v_2 \\
v_3 \\
v_4
\end{pmatrix}
+ \cdots
label{mymatrixeq}\\
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\
-C_6 & C_6 & 0 & 0 \\
0 & 0 & 0 & 0 \\
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\
v_2 \\
v_3 \\
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\
0 \\
0 \\
-i_0
\end{pmatrix}
\end{align}
!et
which becomes
$$ \begin{align} \begin{pmatrix} G_2 + G_3 & -G_3 & -G_2 & 0 \\ -G_3 & G_3 + G_4 & 0 & -G_4 \\ -G_2 & 0 & G_1 + G_2 & 0 \\ 0 & -G_4 & 0 & G_4 \end{pmatrix} &= \begin{pmatrix} v_1 \\ v_2 \\ v_3 \\ v_4 \end{pmatrix} + \cdots \label{_mymatrixeq}\\ \begin{pmatrix} C_5 + C_6 & -C_6 & 0 & 0 \\ -C_6 & C_6 & 0 & 0 \\ 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 \end{pmatrix} \frac{d}{dt} &= \begin{pmatrix} v_1 \\ v_2 \\ v_3 \\ v_4 \end{pmatrix} = \begin{pmatrix} 0 \\ 0 \\ 0 \\ -i_0 \end{pmatrix} \end{align}$$The same matrices without labels in an align*
environment:
!bt
\begin{align*}
\begin{pmatrix}
G_2 + G_3 & -G_3 & -G_2 & 0 \\
-G_3 & G_3 + G_4 & 0 & -G_4 \\
-G_2 & 0 & G_1 + G_2 & 0 \\
0 & -G_4 & 0 & G_4
\end{pmatrix}
&=
\begin{pmatrix}
v_1 \\
v_2 \\
v_3 \\
v_4
\end{pmatrix}
+ \cdots \\
\begin{pmatrix}
C_5 + C_6 & -C_6 & 0 & 0 \\
-C_6 & C_6 & 0 & 0 \\
0 & 0 & 0 & 0 \\
0 & 0 & 0 & 0
\end{pmatrix}
\frac{d}{dt} &=
\begin{pmatrix}
v_1 \\
v_2 \\
v_3 \\
v_4
\end{pmatrix} =
\begin{pmatrix}
0 \\
0 \\
0 \\
-i_0
\end{pmatrix}
\end{align*}
!et
The rendered result becomes
$$ \begin{align*} \begin{pmatrix} G_2 + G_3 & -G_3 & -G_2 & 0 \\ -G_3 & G_3 + G_4 & 0 & -G_4 \\ -G_2 & 0 & G_1 + G_2 & 0 \\ 0 & -G_4 & 0 & G_4 \end{pmatrix} &= \begin{pmatrix} v_1 \\ v_2 \\ v_3 \\ v_4 \end{pmatrix} + \cdots \\ \begin{pmatrix} C_5 + C_6 & -C_6 & 0 & 0 \\ -C_6 & C_6 & 0 & 0 \\ 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 \end{pmatrix} \frac{d}{dt} &= \begin{pmatrix} v_1 \\ v_2 \\ v_3 \\ v_4 \end{pmatrix} = \begin{pmatrix} 0 \\ 0 \\ 0 \\ -i_0 \end{pmatrix} \end{align*} $$