%%
%% Automatically generated file from DocOnce source
%% (https://github.com/doconce/doconce/)
%%
%%
% #ifdef PTEX2TEX_EXPLANATION
%%
%% The file follows the ptex2tex extended LaTeX format, see
%% ptex2tex: https://code.google.com/p/ptex2tex/
%%
%% Run
%%      ptex2tex myfile
%% or
%%      doconce ptex2tex myfile
%%
%% to turn myfile.p.tex into an ordinary LaTeX file myfile.tex.
%% (The ptex2tex program: https://code.google.com/p/ptex2tex)
%% Many preprocess options can be added to ptex2tex or doconce ptex2tex
%%
%%      ptex2tex -DMINTED myfile
%%      doconce ptex2tex myfile envir=minted
%%
%% ptex2tex will typeset code environments according to a global or local
%% .ptex2tex.cfg configure file. doconce ptex2tex will typeset code
%% according to options on the command line (just type doconce ptex2tex to
%% see examples). If doconce ptex2tex has envir=minted, it enables the
%% minted style without needing -DMINTED.
% #endif

% #define PREAMBLE

% #ifdef PREAMBLE
%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage{ptex2tex}
% #ifdef MINTED
\usepackage{minted}
\usemintedstyle{default}
% #endif
\usepackage{fancyvrb}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---


% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE
% #endif

\newcommand{\exercisesection}[1]{\subsection*{#1}}

\input{newcommands_bfmath}
\input{newcommands_replace}

% ------------------- main content ----------------------



% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
How various formats can deal with {\LaTeX} math
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf Hans Petter Langtangen${}^{1, 2}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\centerline{{\small ${}^1$Simula Research Laboratory}}
\centerline{{\small ${}^2$University of Oslo}}
\end{center}
    
% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Mar 1, 2021
\end{center}
% --- end date ---

\vspace{1cm}

\begin{abstract}
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 \Verb!\[ ... \]!, \texttt{equation}, \texttt{equation*}, \texttt{align}, \texttt{align*}, \texttt{alignat}, and
\texttt{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 \textbf{pdflatex}.
\end{abstract}

\section{Test of equation environments}

\subsection{Test 1: Inline math}

We can get an inline equation
\Verb!$u(t)=e^{-at}$! rendered as $u(t)=e^{-at}$.

\subsection{Test 2: A single equation with label}

An equation with number,

\blatexcod
!bt
\begin{equation} u(t)=e^{-at} label{eq1a}\end{equation}
!et
\elatexcod
looks like

\begin{equation} u(t)=e^{-at} \label{_eq1a}\end{equation}
Maybe this multi-line version is what we actually prefer to write:

\blatexcod
!bt
\begin{equation}
u(t)=e^{-at}
label{eq1b}
\end{equation}
!et
\elatexcod
The result is the same:

\begin{equation}
u(t)=e^{-at} \label{_eq1b}
\end{equation}
We can refer to this equation through its label \texttt{eq1b}: (\ref{_eq1b}).

\subsection{Test 3: Multiple, aligned equations without label and number}

MathJax has historically had some problems with rendering many {\LaTeX}
math environments, but the \texttt{align*} and \texttt{align} environments have
always worked.

\blatexcod
!bt
\begin{align*}
u(t)&=e^{-at}\\ 
v(t) - 1 &= \frac{du}{dt}
\end{align*}
!et
\elatexcod
Result:

\begin{align*}
u(t)&=e^{-at}\\ 
v(t) - 1 &= \frac{du}{dt}
\end{align*}

\subsection{Test 4: Multiple, aligned equations with label}

Here, we use \texttt{align} with user-prescribed labels:

\blatexcod
!bt
\begin{align}
u(t)&=e^{-at}
label{eq2b}\\ 
v(t) - 1 &= \frac{du}{dt}
label{eq3b}
\end{align}
!et
\elatexcod
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 (\ref{_eq2b})-(\ref{_eq3b}).

\subsection{Test 5: Multiple, aligned equations without label}

In {\LaTeX}, equations within an \texttt{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,

\blatexcod
!bt
\begin{align}
u(t)&=e^{-at}
\\ 
v(t) - 1 &= \frac{du}{dt}
\end{align}
!et
\elatexcod
is edited to something like

\blatexcod
!bt
\begin{align}
u(t)&=e^{-at}
label{_auto5}\\ 
v(t) - 1 &= \frac{du}{dt}
label{_auto6}
\end{align}
!et
\elatexcod
and the output gets the two equation numbered.

\begin{align}
u(t)&=e^{-at}\\ 
v(t) - 1 &= \frac{du}{dt}
\end{align}

\subsection{Test 6: Multiple, aligned equations with multiple alignments}

The \texttt{align} environment can be used with two \Verb!&! alignment characters, e.g.,

\blatexcod
!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
\elatexcod
The result in pdflatex becomes

\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}

A better solution is usually to use an \texttt{alignat} environment:

\blatexcod
!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
\elatexcod
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}

\subsection{Test 7: Multiple, aligned eqnarray equations without label}

Let us try the old \texttt{eqnarray*} environment.

\blatexcod
!bt
\begin{eqnarray*}
u(t)&=& e^{-at}\\ 
v(t) - 1 &=& \frac{du}{dt}
\end{eqnarray*}
!et
\elatexcod
which results in

\begin{eqnarray*}
u(t)&=& e^{-at}\\ 
v(t) - 1 &=& \frac{du}{dt}
\end{eqnarray*}

\subsection{Test 8: Multiple, eqnarrayed equations with label}

Here we use \texttt{eqnarray} with labels:

\blatexcod
!bt
\begin{eqnarray}
u(t)&=& e^{-at}
label{eq2c}\\ 
v(t) - 1 &=& \frac{du}{dt}
label{eq3c}
\end{eqnarray}
!et
\elatexcod
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 (\ref{_eq2c})-(\ref{_eq3c})
in the pdflatex format?

\subsection{Test 9: The \texttt{multiline} environment with label and number}

The {\LaTeX} code

\blatexcod
!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
\elatexcod
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 (\ref{_multiline:eq1}).

\subsection{Test 10: Splitting equations using a split environment}

Although \texttt{align} can be used to split too long equations, a more obvious
command is \texttt{split}:

\blatexcod
!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
\elatexcod

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}
\end{equation}

\subsection{Test 11: Newcommands and boldface bm vs pmb}

First we use the plain old pmb package for bold math. The formula

\blatexcod
!bt
\[ \frac{\partial\u}{\partial t} +
\u\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
!et
\elatexcod
and the inline expression \Verb!$\nabla\u (\x)\cdot\normalvec$!
(with suitable newcommands using pmb)
get rendered as

\[ \frac{\partial\u}{\partial t} +
\u\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
and $\nabla\u (\x)\cdot\normalvec$.

Somewhat nicer fonts may appear with the more modern \Verb!\bm! command:

\blatexcod
!bt
\[ \frac{\partial\ubm}{\partial t} +
\ubm\cdot\nabla\ubm = \nu\nabla^2\ubm -
\frac{1}{\varrho}\nabla p,\]
!et
\elatexcod
(backslash \texttt{ubm} is a newcommand for bold math $u$), for which we get

\[ \frac{\partial\ubm}{\partial t} +
\ubm\cdot\nabla\ubm = \nu\nabla^2\ubm -
\frac{1}{\varrho}\nabla p.\]
Moreover,

\bccq
$\nabla\bm{u}(\bm{x})\cdot\bm{n}$
\eccq
becomes $\nabla\bm{u}(\bm{x})\cdot\bm{n}$.

\section{Problematic equations}

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.

\subsection{Colored terms in equations}

The {\LaTeX} code

\blatexcod
!bt
\[ {\color{blue}\frac{\partial\u}{\partial t}} +
\nabla\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]
!et
\elatexcod

results in

\[ {\color{blue}\frac{\partial\u}{\partial t}} +
\nabla\cdot\nabla\u = \nu\nabla^2\u -
\frac{1}{\varrho}\nabla p,\]

\subsection{Bar over symbols}

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:

\blatexcod
!bt
\[ \bar\f = f_c^{-1}\f,\]
!et
\elatexcod

which for pdflatex output results in

\[ \bar\f = f_c^{-1}\f.\]

With sphinx, this formula is not rendered. However, using curly braces for the bar,

\blatexcod
!bt
\[ \bar{\f} = f_c^{-1}\f,\]
!et
\elatexcod

makes the output correct also for sphinx:

\[ \bar{\f} = f_c^{-1}\f,\]

\subsection{Matrix formulas}

Here is an \texttt{align} environment with a label and the \texttt{pmatrix}
environment for matrices and vectors in {\LaTeX}.

\blatexcod
!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
\elatexcod

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 \texttt{align*} environment:

\blatexcod
!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
\elatexcod

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*}

% ------------------- end of main content ---------------

% #ifdef PREAMBLE
\end{document}
% #endif

