================================== Using LaTeX syntax for mathematics ================================== .. role:: m(math) .. default-role:: math .. |latex| replace:: L\ :sup:`A`\ T\ :sub:`E`\ X .. contents:: Introduction ============ Since version 0.8, Docutils supports mathematical content with a `"math" directive`__ and `role`__. The input format is *LaTeX math syntax*\ [#math-syntax]_ with support for Unicode symbols. .. [#math-syntax] The supported LaTeX commands include AMS extensions (see, e.g., the `Short Math Guide`_). The support is limited to a subset of *LaTeX math* by the conversion required for many output formats. For HTML, the `math_output`_ configuration setting (or the corresponding ``--math-output`` command line option) select between alternative output formats with different subsets of supported elements. If a writer does not support math typesetting at all, the content is inserted verbatim. __ https://docutils.sourceforge.io/docs/ref/rst/directives.html#math __ https://docutils.sourceforge.io/docs/ref/rst/roles.html#math .. _Short Math Guide: http://mirrors.ctan.org/info/short-math-guide/short-math-guide.pdf .. _math_output: https://docutils.sourceforge.io/docs/user/config.html#math-output Role and directive ================== The ``math`` role can be used for inline mathematical expressions: ``:math:`\psi(r) = \exp(-2r)``` will produce :m:`\psi(r)=\exp(-2r)`. Inside the backtics you can write anything you would write between dollar signs in a LaTeX document. For producing displayed math (like an ``equation*`` environment in a LaTeX document) there is a ``math`` directive. If you write:: .. math:: \psi(r) = e^{-2r} you will get: .. math:: \psi(r) = e^{-2r} A more complex example is the definition of the Fourier transform .. math:: (\mathcal{F}f)(y) = \frac{1}{\sqrt{2\pi}^{\ n}} \int_{\mathbb{R}^n} f(x)\,e^{-\mathrm{i} y \cdot x} \,\mathrm{d} x. .. tip:: If you put ``.. default-role:: math`` at the top of your document, then you can write ```x^2``` instead of the longer version: ``:math:`x^2```. You can also introduce an abreviation like this ``.. role:: m(math)``. That will allow you to write ``:m:`x^2``` or ```x^2`:m:``. Not *all* math syntax constructs work with every output format, but basic everyday-math should work. If a command or a special symbol is not desribed in this document, then it is probably not implemented in the internal LaTeX -> MathML converter. Commands ======== .. class:: colwidths-auto ===================== ============================== ============================ command example result ===================== ============================== ============================ ``\sqrt`` ``\sqrt{x^2-1}`` `\sqrt{x^2-1}` ``\frac`` ``\frac{1}{2}`` `\frac{1}{2}` ``\left``, ``\right`` ``\left(\frac{1}{2}\right)^n`` `\left(\frac{1}{2}\right)^n` ===================== ============================== ============================ Environments ============ Displayed math can use ``\\`` and ``&`` for line shifts and alignments:: .. math:: a & = (x + y)^2 \\ & = x^2 + 2xy + y^2 LaTeX output will wrap it in an ``align*`` environment. The result is: .. math:: a & = (x + y)^2 \\ & = x^2 + 2xy + y^2 The ``matrix`` and ``cases`` environments can also contain ``\\`` and ``&``:: .. math:: \left(\begin{matrix} a & b \\ c & d \end{matrix}\right) Result: .. math:: \left(\begin{matrix} a & b \\ c & d \end{matrix}\right) Mathematical symbols ==================== The following tables are adapted from the first edition of "The LaTeX Companion" (Goossens, Mittelbach, Samarin). Accents ------- .. class:: colwidths-auto =========== ============= =========== ============= ============== ================ `\acute{x}` ``\acute{x}`` `\dot{t}` ``\dot{t}`` `\hat{H}` ``\hat{H}`` `\bar{v}` ``\bar{v}`` `\ddot{t}` ``\ddot{t}`` `\mathring{x}` ``\mathring{x}`` `\breve{x}` ``\breve{x}`` `\dddot{t}` ``\dddot{t}`` `\tilde{n}` ``\tilde{n}`` `\check{x}` ``\check{x}`` `\grave{x}` ``\grave{x}`` `\vec{x}` ``\vec{x}`` =========== ============= =========== ============= ============== ================ When adding an accent to an i or j in math, dotless variants can be obtained with ``\imath`` and ``\jmath``: `\bar \imath`, `\hat{\jmath}` (MathML drops the dot automatically). For adornment that span multiple symbols, see `top and bottom embellishments`_. Font switches ------------- TeX’s *math alphabets* correspond to the :t:`mathematical alphanumeric symbols` block in Unicode and the "mathvariant" `style attribute`__ in MathML. They are “to be used for mathematical variables where style variations are important semantically”. __ https://developer.mozilla.org/en-US/docs/Web/MathML/Attribute .. class:: colwidths-auto =============== ============================ ========================== command example result =============== ============================ ========================== ``\mathbf`` ``\mathbf{r}^2=x^2+y^2+z^2`` `\mathbf{r}^2=x^2+y^2+z^2` ``\mathbb`` ``\mathbb{R \subset C}`` `\mathbb{R \subset C}` ``\mathcal`` ``\mathcal{F}f(x)`` `\mathcal{F}f(x)` ``\mathfrak`` ``\mathfrak{a}`` `\mathfrak{a}` ``\mathit`` ``\mathit{\Gamma}`` `\mathit{\Gamma}` ``\mathrm`` ``s_\mathrm{out}`` `s_\mathrm{out}` ``\mathsf`` ``\mathsf x`` `\mathsf x` ``\mathtt`` ``\mathtt{0.12}`` `\mathtt{0.12}` =============== ============================ ========================== Additional alphabets are defined in LaTeX packages, e.g. .. class:: colwidths-auto =========== ============= ====================== TeX command LaTeX package MathML "mathvariant" =========== ============= ====================== mathbfit isomath_ bold-italic mathsfit isomath_ sans-serif-italic mathsfbfit isomath_ sans-serif-bold-italic mathscr mathrsfs_ script =========== ============= ====================== .. _isomath: https://www.ctan.org/pkg/isomath .. _mathrsfs: https://www.ctan.org/pkg/mathrsfs This can be used to typeset vector symbols in **bold** *italic* in line with the International Standard [ISO-80000-2]. ``\mathbfit{r}^2=x^2+y^2+z^2`` becomes .. math:: \mathbfit{r}^2=x^2+y^2+z^2. In contrast to the math alphabet selectors, ``\boldsymbol`` only changes the *font weight*. In LaTeX, it can be used to get a bold version of any mathematical symbol (for other output formats, results are mixed): .. math:: \boldsymbol{abs(x) \pm \alpha \approx 3 \Gamma \quad \forall x \in R} Arrows ------ .. class:: colwidths-auto ===================== ======================= ===================== ======================= `\leftarrow` ``\leftarrow`` `\Leftarrow` ``\Leftarrow`` `\rightarrow` ``\rightarrow`` `\Rightarrow` ``\Rightarrow`` `\leftrightarrow` ``\leftrightarrow`` `\Leftrightarrow` ``\Leftrightarrow`` `\uparrow` ``\uparrow`` `\Uparrow` ``\Uparrow`` `\downarrow` ``\downarrow`` `\Downarrow` ``\Downarrow`` `\updownarrow` ``\updownarrow`` `\Updownarrow` ``\Updownarrow`` `\longleftarrow` ``\longleftarrow`` `\Longleftarrow` ``\Longleftarrow`` `\longrightarrow` ``\longrightarrow`` `\Longrightarrow` ``\Longrightarrow`` `\longleftrightarrow` ``\longleftrightarrow`` `\Longleftrightarrow` ``\Longleftrightarrow`` `\nearrow` ``\nearrow`` `\leftharpoonup` ``\leftharpoonup`` `\searrow` ``\searrow`` `\rightharpoonup` ``\rightharpoonup`` `\swarrow` ``\swarrow`` `\leftharpoondown` ``\leftharpoondown`` `\nwarrow` ``\nwarrow`` `\rightharpoondown` ``\rightharpoondown`` `\mapsto` ``\mapsto`` `\hookleftarrow` ``\hookleftarrow`` `\longmapsto` ``\longmapsto`` `\hookrightarrow` ``\hookrightarrow`` ===================== ======================= ===================== ======================= Binary operators ---------------- .. class:: colwidths-auto ================== ==================== ================= =================== ================== ==================== `*` ``*`` `\circledast` ``\circledast`` `\ominus` ``\ominus`` `+` ``+`` `\circledcirc` ``\circledcirc`` `\oplus` ``\oplus`` `-` ``-`` `\circleddash` ``\circleddash`` `\oslash` ``\oslash`` `:` ``:`` `\cup` ``\cup`` `\otimes` ``\otimes`` `\Cap` ``\Cap`` `\curlyvee` ``\curlyvee`` `\pm` ``\pm`` `\Cup` ``\Cup`` `\curlywedge` ``\curlywedge`` `\rightthreetimes` ``\rightthreetimes`` `\amalg` ``\amalg`` `\dagger` ``\dagger`` `\rtimes` ``\rtimes`` `\ast` ``\ast`` `\ddagger` ``\ddagger`` `\setminus` ``\setminus`` `\bigcirc` ``\bigcirc`` `\diamond` ``\diamond`` `\smallsetminus` ``\smallsetminus`` `\bigtriangledown` ``\bigtriangledown`` `\div` ``\div`` `\sqcap` ``\sqcap`` `\bigtriangleup` ``\bigtriangleup`` `\divideontimes` ``\divideontimes`` `\sqcup` ``\sqcup`` `\boxdot` ``\boxdot`` `\dotplus` ``\dotplus`` `\star` ``\star`` `\boxminus` ``\boxminus`` `\doublebarwedge` ``\doublebarwedge`` `\times` ``\times`` `\boxplus` ``\boxplus`` `\gtrdot` ``\gtrdot`` `\triangleleft` ``\triangleleft`` `\boxtimes` ``\boxtimes`` `\intercal` ``\intercal`` `\triangleright` ``\triangleright`` `\bullet` ``\bullet`` `\leftthreetimes` ``\leftthreetimes`` `\uplus` ``\uplus`` `\cap` ``\cap`` `\lessdot` ``\lessdot`` `\vee` ``\vee`` `\cdot` ``\cdot`` `\ltimes` ``\ltimes`` `\veebar` ``\veebar`` `\centerdot` ``\centerdot`` `\mp` ``\mp`` `\wedge` ``\wedge`` `\circ` ``\circ`` `\odot` ``\odot`` `\wr` ``\wr`` ================== ==================== ================= =================== ================== ==================== Braces ------ .. class:: colwidths-auto ============ ============ ============ ============== ======================== `(` ``(`` `[` ``[`` `|` ``|`` `\{` ``\{`` `\langle` ``\langle`` `)` ``)`` `]` ``]`` `|` ``|`` `\}` ``\}`` `\rangle` ``\rangle`` ============ ============ ============ ============== ======================== Greek letters ------------- .. class:: colwidths-auto ========== ============ ========== ============ ========== ============ ============== =============== `\Gamma` ``\Gamma`` `\alpha` ``\alpha`` `\mu` ``\mu`` `\omega` ``\omega`` `\Delta` ``\Delta`` `\beta` ``\beta`` `\nu` ``\nu`` `\backepsilon` ``\backepsilon`` `\Lambda` ``\Lambda`` `\gamma` ``\gamma`` `\xi` ``\xi`` `\digamma` ``\digamma`` `\Omega` ``\Omega`` `\delta` ``\delta`` `\pi` ``\pi`` `\varepsilon` ``\varepsilon`` `\Phi` ``\Phi`` `\epsilon` ``\epsilon`` `\rho` ``\rho`` `\varkappa` ``\varkappa`` `\Pi` ``\Pi`` `\zeta` ``\zeta`` `\sigma` ``\sigma`` `\varphi` ``\varphi`` `\Psi` ``\Psi`` `\eta` ``\eta`` `\tau` ``\tau`` `\varpi` ``\varpi`` `\Sigma` ``\Sigma`` `\theta` ``\theta`` `\upsilon` ``\upsilon`` `\varrho` ``\varrho`` `\Theta` ``\Theta`` `\iota` ``\iota`` `\phi` ``\phi`` `\varsigma` ``\varsigma`` `\Upsilon` ``\Upsilon`` `\kappa` ``\kappa`` `\chi` ``\chi`` `\vartheta` ``\vartheta`` `\Xi` ``\Xi`` `\lambda` ``\lambda`` `\psi` ``\psi`` ========== ============ ========== ============ ========== ============ ============== =============== Letterlike symbols ------------------ .. class:: colwidths-auto ======= ========== ============= =============== ========= =========== ========== ============ `\Im` ``\Im`` `\forall` ``\forall`` `\aleph` ``\aleph`` `\eth` ``\eth`` `\Re` ``\Re`` `\exists` ``\exists`` `\beth` ``\beth`` `\hbar` ``\hbar`` `\mho` ``\mho`` `\complement` ``\complement`` `\gimel` ``\gimel`` `\hslash` ``\hslash`` `\Bbbk` ``\Bbbk`` `\Finv` ``\Finv`` `\daleth` ``\daleth`` `\imath` ``\imath`` `\ell` ``\ell`` `\Game` ``\Game`` `\nabla` ``\nabla`` `\partial` ``\partial`` `\wp` ``\wp`` ======= ========== ============= =============== ========= =========== ========== ============ Miscellaneous symbols --------------------- .. class:: colwidths-auto ======== =============== =========== ============= ============== ================ ========== ============ `\angle` ``\angle`` `\emptyset` ``\emptyset`` `\clubsuit` ``\clubsuit`` `\flat` ``\flat`` `\colon` ``\colon`` [#]_ `\infty` ``\infty`` `\diamondsuit` ``\diamondsuit`` `\natural` ``\natural`` `\cdots` ``\cdots`` `\neg` ``\neg`` `\heartsuit` ``\heartsuit`` `\sharp` ``\sharp`` `\ddots` ``\ddots`` `\bot` ``\bot`` `\spadesuit` ``\spadesuit`` `\ddots` ``\ddots`` `\top` ``\top`` ======== =============== =========== ============= ============== ================ ========== ============ .. [#] Punctuation (not ratio): Compare spacing in `a\colon b\to c` and `a:b = c`. Named operators --------------- .. class:: colwidths-auto ========= =========== ====== ======== ====== ======== ======= ========= `\arccos` ``\arccos`` `\csc` ``\csc`` `\ker` ``\ker`` `\sec` ``\sec`` `\arcsin` ``\arcsin`` `\deg` ``\deg`` `\lg` ``\lg`` `\sin` ``\sin`` `\arctan` ``\arctan`` `\det` ``\det`` `\lim` ``\lim`` `\sinh` ``\sinh`` `\arg` ``\arg`` `\dim` ``\dim`` `\ln` ``\ln`` `\sup` ``\sup`` `\cos` ``\cos`` `\exp` ``\exp`` `\log` ``\log`` `\tan` ``\tan`` `\cosh` ``\cosh`` `\gcd` ``\gcd`` `\max` ``\max`` `\tanh` ``\tanh`` `\cot` ``\cot`` `\hom` ``\hom`` `\min` ``\min`` `\coth` ``\coth`` `\inf` ``\inf`` `\Pr` ``\Pr`` ========= =========== ====== ======== ====== ======== ======= ========= Named operators outside the above list can be typeset with ``\operatorname{name}``, e.g. `\operatorname{sgn}(-3) = -1`. Relation symbols ---------------- .. class:: colwidths-auto ================================ ================================ ================================ ================================ `\Join` ``\Join`` `\approx` ``\approx`` `\asymp` ``\asymp`` `\bowtie` ``\bowtie`` `\cong` ``\cong`` `\dashv` ``\dashv`` `\doteq` ``\doteq`` `\equiv` ``\equiv`` `\frown` ``\frown`` `\ge` ``\ge`` `\geq` ``\geq`` `\gg` ``\gg`` `\in` ``\in`` `\le` ``\le`` `\leq` ``\leq`` `\ll` ``\ll`` `\mid` ``\mid`` `\models` ``\models`` `\neq` ``\neq`` `\ni` ``\ni`` `\parallel` ``\parallel`` `\perp` ``\perp`` `\prec` ``\prec`` `\precsim` ``\precsim`` `\propto` ``\propto`` `\sim` ``\sim`` `\simeq` ``\simeq`` `\smile` ``\smile`` `\sqsubset` ``\sqsubset`` `\sqsubseteq` ``\sqsubseteq`` `\sqsupset` ``\sqsupset`` `\sqsupseteq` ``\sqsupseteq`` `\subset` ``\subset`` `\subseteq` ``\subseteq`` `\succ` ``\succ`` `\succsim` ``\succsim`` `\supset` ``\supset`` `\supseteq` ``\supseteq`` `\vdash` ``\vdash`` ================================ ================================ ================================ ================================ negated relations .. class:: colwidths-auto ============================= =================== `\not\in` ``\not\in`` `\not =` ``\not =`` `\not \equiv` ``\not \equiv`` ============================= =================== Variable-sized symbols ---------------------- .. class:: colwidths-auto ================= =========================== ========================= ========================= ===================== `\sum` ``\sum`` `\bigodot` ``\bigodot`` `\bigcap` ``\bigcap`` `\bigwedge` ``\bigwedge`` `\prod` ``\prod`` `\int` ``\int`` `\bigoplus` ``\bigoplus`` `\bigcup` ``\bigcup`` `\bigvee` ``\bigvee`` `\coprod` ``\coprod`` `\oint` ``\oint`` `\bigotimes` ``\bigotimes`` `\biguplus` ``\biguplus`` ================= =========================== ========================= ========================= ===================== Larger symbols are used in displayed formulas: .. math:: \sum\ \int\ \oint \bigcap \prod \ldots Extensible delimiters --------------------- Unless you indicate otherwise, delimiters in math formulas remain at the standard size regardless of the height of the enclosed material. To get adaptable sizes, use ``\left`` and ``\right`` prefixes. .. math:: g(A,B,Y) = f \left(A,B,X=h^{[X]}(Y)\right) Use ``.`` for "empty" delimiters: .. math:: A = \left . \frac{1}{1-n}\, \right |_{n=0}^\infty Top and bottom embellishments ----------------------------- Visually similar to accents_ but generally applied to multiple symbols. .. class:: colwidths-auto ========================== ============================ =========================== ============================= `\widetilde{abi}` ``\widetilde{abi}`` `\widehat{abi}` ``\widehat{abi}`` `\overline{abi}` ``\overline{abi}`` `\underline{abi}` ``\underline{abi}`` `\overbrace{abi}` ``\overbrace{abi}`` `\underbrace{abi}` ``\underbrace{abi}`` `\overleftarrow{abi}` ``\overleftarrow{abi}`` `\underleftarrow{abi}` ``\underleftarrow{abi}`` `\overrightarrow{abi}` ``\overrightarrow{abi}`` `\underrightarrow{abi}` ``\underrightarrow{abi}`` `\overleftrightarrow{abi}` ``\overleftrightarrow{abi}`` `\underleftrightarrow{abi}` ``\underleftrightarrow{abi}`` ========================== ============================ =========================== ============================= Extensible arrows ----------------- TODO Text ==== The main use of the command ``\text`` is for words or phrases in a display. It is similar to ``\mbox`` in its effects but, unlike ``\mbox``, automatically produces subscript-size text if used in a subscript, ``k_{\text{B}}T`` becomes `k_{\text{B}}T`. Whitespace is kept inside the argument: .. Math:: f_{[x_{i-1},x_i]} \text{ is monotonic for } i = 1,\,…,\,c+1 Currently, math in text is not supported by LaTeX2MathML. Horizontal space ================ .. class:: colwidths-auto ================= ================== ============= :m:`|\qquad|` ``|\qquad|`` 2 em :m:`|\quad|` ``|\quad|`` 1 em :m:`|\;|` ``|\;|`` thick :m:`|\ |` ``|\ |`` standard :m:`|\:|` ``|\:|`` medium :m:`|\,|` ``|\,|`` thin :m:`| |` ``| |`` none :m:`|\!|` ``|\!|`` thin negative `|\hspace{1ex}|` ``|\hspace{1ex}|`` custom ================= ================== ============= ToDo ==== internal LaTeX2MathML * Math inside text: ``n - 1 \text{if $n$ is odd}``. * Remove circular refs. * Decimal numbers. * Shorthands for combined named operators ========== ============ ============= =============== ================== `\liminf` ``\liminf`` `\varliminf` ``\varliminf`` `\underline{\lim}` `\limsup` ``\limsup`` `\varlimsup` ``\varlimsup`` `\overline{\lim}` `\injlim` ``\injlim`` `varinjlim` ``\varinjlim`` `\projlim` ``\projlim`` `varprojlim` ``\varprojlim`` ========== ============ ============= =============== ================== * Implement ``\circledS``? (in short-math-guide.pdf but not in mathematical Unicode characters) Tests ========== Font changes ------------ Math alphabet macros change the default alphabet ("mathvariant" in MathML), leaving some symbols unchanged: :normal: `abs(x) \pm \alpha \approx 3 \Gamma \quad \forall x \in R` :mathrm: `\mathrm{abs(x) \pm \alpha \approx 3 \Gamma \quad \forall x \in R}` :mathit: `\mathit{abs(x) \pm \alpha \approx 3 \Gamma \quad \forall x \in R}` :mathsf: `\mathsf{abs(x) \pm \alpha \approx 3 \Gamma \quad \forall x \in R}` :mathbb: `\mathbb{abs(x) \pm \alpha \approx 3 \Gamma \quad \forall x \in R}` :mathbf: `\mathbf{abs(x) \pm \alpha \approx 3 \Gamma \quad \forall x \in R` Unicode supports the following blackboard-bold characters: `\mathbb{a \ldots z A \ldots Z 0 \ldots 9 \mathbb\Gamma \mathbb{\Pi} \mathbb {\Sigma}\mathbb\gamma \mathbb\pi}`. The package mathrsfs_ (and some drop-in replacements) define the ``\mathscr`` macro that selects a differently shaped "script" alphabet. Compare `\mathscr{A, B, …, Z, a, b, …, z}` with `\mathcal{A, B, …, Z, a, b, …, z}`. .. _rsfs: https://ctan.org/pkg/mathrsfs Inferred s in MathML ~~~~~~~~~~~~~~~~~~~~~~~~~~ The elements , , , , , , , and treat their contents as a single inferred mrow formed from all their children. .. math:: a = \sqrt 2, b = \sqrt{1+x^2}, c = \sqrt\frac{sin(x)}{23} inline: :math:`a = \sqrt 2, b = \sqrt{1+x^2}, c = \sqrt\frac{sin(x)}{23}`. Accents vs. embellishments -------------------------- MathML drops dots on "i" and "j" with accents: .. math:: \vec i \ne \overrightarrow i \text{ and } \vec\lim \ne \overrightarrow\lim. Accents should be nearer to the base (in Firefox 78, it's vice versa!): .. math:: \vec a \vec l \ne \overrightarrow a \overrightarrow l \bar a \bar l \ne \overline a \overline l