diff options
| -rw-r--r-- | docutils/RELEASE-NOTES.txt | 3 | ||||
| -rw-r--r-- | docutils/docs/ref/rst/mathematics.txt | 32 | ||||
| -rw-r--r-- | docutils/docs/user/config.txt | 77 | ||||
| -rw-r--r-- | docutils/docutils.conf | 2 |
4 files changed, 59 insertions, 55 deletions
diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt index d084965bf..d44228b68 100644 --- a/docutils/RELEASE-NOTES.txt +++ b/docutils/RELEASE-NOTES.txt @@ -120,6 +120,8 @@ Drop support for Python 3.7 and 3.8 in Docutils 0.21. - Remove option ``--embed-images`` (obsoleted by "image_loading_") in Docutils 2.0. + - Change the default value for math_output_ to "MathML" in Docutils 0.22. + * "latex2e" writer: - Change default of use_latex_citations_ setting to True @@ -160,6 +162,7 @@ Drop support for Python 3.7 and 3.8 in Docutils 0.21. .. _front end tools: docs/user/tools.html .. _input encoding: .. _input_encoding: docs/user/config.html#input-encoding +.. _math_output: docs/user/config.html#math-output .. _UTF-8 mode: https://docs.python.org/3/library/os.html#utf8-mode .. _image_loading: docs/user/config.html#image-loading .. _old-format configuration files: diff --git a/docutils/docs/ref/rst/mathematics.txt b/docutils/docs/ref/rst/mathematics.txt index 02ca5e532..ed2ea99c6 100644 --- a/docutils/docs/ref/rst/mathematics.txt +++ b/docutils/docs/ref/rst/mathematics.txt @@ -216,10 +216,8 @@ Nonpairing delimiters The use of ``|`` and ``\|`` for pairs of vertical bars may produce incorrect spacing, e.g., ``|k|=|-k|`` produces `|k| = |−k|` and ``|\sin(x)|`` produces `|\sin(x)|`. The pairing delimiters, e.g. -`\lvert -k\rvert` and `\lvert\sin(x)\rvert`, prevent this problem -(in LaTeX and MathJax). +`\lvert -k\rvert` and `\lvert\sin(x)\rvert`, prevent this problem. -.. TODO: fix spacing before unary minus (see also cases example below). Extensible vertical arrows -------------------------- @@ -635,7 +633,7 @@ commands: .. class:: colwidths-auto - ====================== ======== ===================== ================== + ====================== ======== ===================== =================== :m:`3\qquad 4` ``3\qquad 4`` = 2em :m:`3\quad 4` ``3\quad 4`` = 1em :m:`3~4` ``3~4`` ``3\nobreakspace 4`` @@ -644,17 +642,16 @@ commands: :m:`3\:4` ``3\:4`` ``3\medspace 4`` :m:`3\,4` ``3\,4`` ``3\thinspace 4`` :m:`3 4` ``3 4`` regular space [#]_ - :m:`3\!4` ``3\!4`` ``3\negthinspace 4`` + :m:`3\!4` ``3\!4`` ``3\negthinspace 4`` negative space [#]_ :m:`3\negmedspace 4` ``3\negmedspace 4`` :m:`3\negthickspace 4` ``3\negthickspace 4`` `3\hspace{1ex}4` ``3\hspace{1ex}4`` custom length `3\mspace{20mu}4` ``3\mspace{20mu}4`` custom length [#]_ - ====================== ======== ===================== ================== + ====================== ======== ===================== =================== .. [#] Whitespace characters are ignored in LaTeX math mode. -.. [#] In LaTeX, unit must be 'mu' (1 mu = 1/18em). - -Negative spacing does not work with MathML (in Firefox 78). +.. [#] Negative spacing does not work with MathML (last tested in Firefox 102). +.. [#] In LaTeX, the unit must be 'mu' (1 mu = 1/18em). There are also three commands that leave a space equal to the height and width of its argument. For example ``\phantom{XXX}`` results in space as @@ -751,13 +748,15 @@ padding for sub-fractions: 2 + \frac{7^2}{2 + \cdots} }}} -It supports the optional argument ``[l]`` or ``[r]`` for -left or right placement of the numerator: +The optional argument ``[l]`` or ``[r]`` for left or right placement of +the numerator is `not supported by MathML Core`__: .. math:: \cfrac[l]{x}{x-1} \quad \cfrac{x}{x-1} \quad \cfrac[r]{x}{x-1} +__ https://github.com/w3c/mathml/issues/30 + Delimiter sizes =============== @@ -934,9 +933,12 @@ MathML), leaving some symbols unchanged: :mathcal: `\mathcal{abs(x) \pm \alpha \approx 3 \Gamma \quad \forall x \in R}` :mathscr: `\mathscr{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}`. +Without additional packages, LaTeX supports "blackboard-bold" only for +capital Latin letters. +Unicode supports also small Latin letters, some Greek letters, and digits: +`\mathbb{A \ldots Z a \ldots z} +\mathbb\Gamma \mathbb{\Pi} \mathbb {\Sigma} \mathbb\gamma \mathbb \pi +\mathbb{0 \ldots 9}`. Inferred <mrow>s in MathML @@ -956,7 +958,7 @@ inline: :math:`a = \sqrt 2 + x, b = \sqrt{1+x^2}, c = \sqrt\frac{\sin(x)}{23}`. Scripts and Limits ~~~~~~~~~~~~~~~~~~ -Accents should be nearer to the base (in MathML Firefox 78, it's vice versa!): +Accents should be nearer to the base: `\bar a \overline a, \bar l \overline l, \bar i \overline i`, `\vec{r}` `\overrightarrow{r}`. diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt index 624bc5f07..e6e7716e4 100644 --- a/docutils/docs/user/config.txt +++ b/docutils/docs/user/config.txt @@ -1091,6 +1091,40 @@ the output document. Supported values are (case insensitive): stylesheet(s) will only be referenced or embedded if required (i.e. if there is mathematical content in the document). +:MathML: + Embed math content as presentational MathML_. + + Self-contained documents (no JavaScript, no external downloads). + MathML is part of the HTML5 standard [#mathml-in-html4]_ and + `supported by all major browsers`__ (since January 2023 also by Chrome). + + .. [#mathml-in-html4] + With the "html4css1" writer, the resulting HTML document does + not validate, as there is no DTD for `MathML + XHTML Transitional`. + However, MathML-enabled browsers will render it fine. + + Docutil's latex2mathml converter supports a considerable + `subset of LaTeX math syntax`__. + + An external converter can be appended after whitespace, e.g., + ``--math-output="MathML blahtexml"``: + + blahtexml_ + Fast conversion, support for many symbols and environments, but no + "align" (or other equation-aligning) environment. (C++) + + LaTeXML_ + Comprehensive macro support but *very* slow. (Perl) + + TtM_ + No "matrix", "align" and "cases" environments. Support may be removed. + + Pandoc_ + Comprehensive macro support, fast, but a large install size. (Haskell) + + __ https://developer.mozilla.org/en-US/docs/Web/MathML#browser_compatibility + __ ../ref/rst/mathematics.html + :MathJax: Format math for display with MathJax_, a JavaScript-based math rendering engine. @@ -1140,45 +1174,6 @@ the output document. Supported values are (case insensitive): This is the fallback if no URL is specified. -:MathML: - Embed math content as presentational MathML_. - - Pro: - The W3C recommendation for math on the web. - - Self-contained documents (no JavaScript, no external downloads). - - Con: - Limited `browser support`__. - - Docutil's latex2mathml converter supports only a - `subset of LaTeX math syntax`__. - - With the "html4css1" writer, the resulting HTML document does - not validate, as there is no DTD for `MathML + XHTML Transitional`. - However, MathML-enabled browsers will render it fine. - - __ https://developer.mozilla.org/en-US/docs/Web/MathML - #browser_compatibility - __ ../ref/rst/mathematics.html - - - An external converter can be appended after whitespace, e.g., - ``--math-output="MathML latexml"``: - - blahtexml_ - Fast conversion, support for many symbols and environments, but no - "align" (or other equation-aligning) environment. (C++) - - LaTeXML_ - Comprehensive macro support but *very* slow. (Perl) - - TtM_ - No "matrix", "align" and "cases" environments. Support may be removed. - - Pandoc_ - Comprehensive macro support, fast, but a large install size. (Haskell) - :LaTeX: Include literal LaTeX code. @@ -1186,7 +1181,9 @@ the output document. Supported values are (case insensitive): Default: HTML math.css. Option: ``--math-output``. -New in Docutils 0.8. +| New in Docutils 0.8. +| The default for the HTML5 writer will change to + "MathML" in Docutils 0.22. .. _math directive: ../ref/rst/directives.html#math .. _MathJax: http://www.mathjax.org/ diff --git a/docutils/docutils.conf b/docutils/docutils.conf index 723bacc90..7fe115b44 100644 --- a/docutils/docutils.conf +++ b/docutils/docutils.conf @@ -13,6 +13,8 @@ stylesheet-path: docutils/writers/html4css1/html4css1.css field-name-limit: 20 [html5 writer] +math-output: MathML +# MathML will become the default for HTML5 in Docutils 0.22 stylesheet-dirs: docutils/writers/html5_polyglot/ stylesheet-path: minimal.css, responsive.css section-self-link: yes |