Announce change of "math-output" setting default for HTML5 to "MathML".

MathML is supported by Chrome since January 2023.

Use MathML in documentation pages generated with the HTML5 writer already now.

Update "LaTeX syntax for mathematics" documentation.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@9347 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

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