Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[9347] trunk/docutils
|
From: <mi...@us...> - 2023-04-14 00:11:59
|
Revision: 9347
http://sourceforge.net/p/docutils/code/9347
Author: milde
Date: 2023-04-14 00:11:56 +0000 (Fri, 14 Apr 2023)
Log Message:
-----------
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.
Modified Paths:
--------------
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/ref/rst/mathematics.txt
trunk/docutils/docs/user/config.txt
trunk/docutils/docutils.conf
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2023-04-13 18:48:20 UTC (rev 9346)
+++ trunk/docutils/RELEASE-NOTES.txt 2023-04-14 00:11:56 UTC (rev 9347)
@@ -120,6 +120,8 @@
- 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 @@
.. _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:
Modified: trunk/docutils/docs/ref/rst/mathematics.txt
===================================================================
--- trunk/docutils/docs/ref/rst/mathematics.txt 2023-04-13 18:48:20 UTC (rev 9346)
+++ trunk/docutils/docs/ref/rst/mathematics.txt 2023-04-14 00:11:56 UTC (rev 9347)
@@ -216,10 +216,8 @@
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 @@
.. 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,18 +642,17 @@
: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 (last tested in Firefox 102).
+.. [#] In LaTeX, the unit must be 'mu' (1 mu = 1/18em).
-Negative spacing does not work with MathML (in Firefox 78).
-
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
wide and high as three X’s:
@@ -751,14 +748,16 @@
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 @@
: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 @@
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}`.
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2023-04-13 18:48:20 UTC (rev 9346)
+++ trunk/docutils/docs/user/config.txt 2023-04-14 00:11:56 UTC (rev 9347)
@@ -1091,6 +1091,40 @@
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 @@
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 @@
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/
Modified: trunk/docutils/docutils.conf
===================================================================
--- trunk/docutils/docutils.conf 2023-04-13 18:48:20 UTC (rev 9346)
+++ trunk/docutils/docutils.conf 2023-04-14 00:11:56 UTC (rev 9347)
@@ -13,6 +13,8 @@
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
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
