SF.net SVN: docutils:[9750] trunk/docutils
milde--- via Docutils-checkins <[email protected]>
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 9750
http://sourceforge.net/p/docutils/code/9750
Author: milde
Date: 2024-06-11 08:55:31 +0000 (Tue, 11 Jun 2024)
Log Message:
-----------
Make MathML the default math_output_ for the "html5" writer.
Update tests, docs and TODO list and remove dead links.
Modified Paths:
--------------
trunk/docutils/HISTORY.txt
trunk/docutils/RELEASE-NOTES.txt
trunk/docutils/docs/dev/todo.txt
trunk/docutils/docs/user/config.txt
trunk/docutils/docs/user/html.txt
trunk/docutils/docutils/writers/_html_base.py
trunk/docutils/docutils/writers/html4css1/__init__.py
trunk/docutils/test/data/help/docutils.txt
trunk/docutils/test/functional/expected/misc_rst_html5.html
trunk/docutils/test/functional/expected/standalone_rst_html5.html
trunk/docutils/test/test_writers/test_html5_polyglot_misc.py
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2024-06-10 14:24:00 UTC (rev 9749)
+++ trunk/docutils/HISTORY.txt 2024-06-11 08:55:31 UTC (rev 9750)
@@ -80,6 +80,14 @@
- `Messages` also handles "loose" system messages generated by the parser.
+* docutils/writers/_html_base.py
+
+ - Make MathML the default math_output_.
+
+* docutils/writers/html4css1/__init__.py
+
+ - Keep default math_output_ value "HTML math.css".
+
* docutils/writers/manpage.py
- Remove code for unused emdash bullets.
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2024-06-10 14:24:00 UTC (rev 9749)
+++ trunk/docutils/RELEASE-NOTES.txt 2024-06-11 08:55:31 UTC (rev 9750)
@@ -81,9 +81,6 @@
__ https://www.w3.org/TR/2014/REC-html5-20141028/grouping-content.html
#the-blockquote-element
- - Change the default value for math_output_ to "MathML"
- in Docutils 0.22.
-
- Unitless image_ :width: and :hight: values and dimensions
read from the image due to a :scale: option will be written as
"width" and "hight" attributes instead of "style" rules to allow
@@ -199,21 +196,21 @@
* Document Tree / Docutils DTD
- - Allow multiple <term> elements in a <definition_list_item__>.
- (Third-party writers may need adaption.)
+ - Allow multiple <term> elements in a `\<definition_list_item>`__
+ (third-party writers may need adaption).
- - New method `Element.validate()`: Raise `nodes.ValidationError` if the
- element does not comply with the `Docutils Document Model`_.
- Provisional.
-
__ docs/ref/doctree.html#definition-list-item
-* Drop short options ``-i`` and ``-o``.
- Use the long equivalents ``--input-encoding`` and ``--output-encoding``.
- (See `command line interface`_ for the rationale.)
+* Configuration changes:
-* Change the default input encoding from ``None`` (auto-detect) to "utf-8".
+ - Make MathML the default math_output_ for the "html5" writer.
+ - Change the default input encoding from ``None`` (auto-detect) to "utf-8".
+
+ - Drop short options ``-i`` and ``-o``.
+ Use the long equivalents ``--input-encoding`` and ``--output-encoding``.
+ (See `command line interface`_ for the rationale.)
+
* New parser for `Docutils XML`_ (e.g., the output of the "xml" writer).
Provisional.
@@ -221,6 +218,10 @@
or use the :parser: option of the `"include" directive`_ to include
an XML file in a rST document.
+* New method `Element.validate()`: Raise `nodes.ValidationError` if the
+ element does not comply with the `Docutils Document Model`_.
+ Provisional.
+
* Bugfixes and improvements (see HISTORY_).
.. _Docutils Document Model:
@@ -243,17 +244,10 @@
Release 0.21.1 (2024-04-10)
===========================
-The sdist in 0.21 was incomplete
+Add missing metadata files to sdist.
+No changes to the code.
-- pypi allows no file replacing
-- adding a postrelease suffix "post1": docutils-0.21.post1.tar.gz
- works on pypi, but fails with pip because the metadata differs.
- But if the metadata is 0.21.post1 pypi makes it a new release.
-
- 0.21.1 is the same code except for the version number.
-
-
Release 0.21 (2024-04-09)
=========================
Modified: trunk/docutils/docs/dev/todo.txt
===================================================================
--- trunk/docutils/docs/dev/todo.txt 2024-06-10 14:24:00 UTC (rev 9749)
+++ trunk/docutils/docs/dev/todo.txt 2024-06-11 08:55:31 UTC (rev 9750)
@@ -1498,80 +1498,39 @@
HTML output
```````````
-There is no native math support in HTML.
+There is no native math support in HTML4. HTML5 has built-in support for
+MathML. MathML is supported by all major browsers since 2023.
+
For supported math output variants see the `math-output setting`_.
-Add more/better alternatives?
MathML_
- Converters from LaTeX to MathML include
+ Additional converters from LaTeX to MathML
- * TtM_ (C), ``--math-output=MathML ttm``, undocumented, may be removed.
-
- No "matrix", "align" and "cases" environments.
-
- * MathToWeb_ (Java)
* TeX4ht_ (TeX based)
- * itex_ (also `used in Abiword`__)
- * `Steve’s LATEX-to-MathML translator`_
- ('mini-language', javascript, Python)
* `MathJax for Node`_
- * Write a new converter? E.g. based on:
-
- * a generic tokenizer (see e.g. a `latex-codec recipe`_,
- `updated latex-codec`_, )
- * the Unicode-Char <-> LaTeX mappings database unimathsymbols_
-
- __ http://msevior.livejournal.com/26377.html
.. _MathML: https://www.w3.org/TR/MathML2/
- .. _ttm: http://hutchinson.belmont.ma.us/tth/mml/
.. _TeX4ht: http://www.tug.org/applications/tex4ht/mn.html
- .. _MathToWeb: http://www.mathtoweb.com/
- .. _itex: http://golem.ph.utexas.edu/~distler/blog/itex2MMLcommands.html
- .. _Steve’s LATEX-to-MathML translator:
- http://www.gold-saucer.org/mathml/greasemonkey/dist/display-latex
- .. _latex-codec recipe:
- http://code.activestate.com/recipes/252124-latex-codec/
- .. _updated latex-codec:
- http://mirror.ctan.org/biblio/bibtex/utils/mab2bib/latex.py
- .. _unimathsymbols: http://milde.users.sourceforge.net/LUCR/Math/
.. _MathJax for Node: https://github.com/mathjax/MathJax-node
-.. URL seems down:
- .. _itex: http://pear.math.pitt.edu/mathzilla/itex2mmlItex.html
-
HTML/CSS
format math in standard HTML enhanced by CSS rules
- (Overview__, `Examples and experiments`__).
+ (`Examples and experiments`__).
The ``math-output=html`` option uses the converter from eLyXer_
(included with Docutils).
Alternatives: LaTeX-math to HTML/CSS converters include
- * TtH_ (C)
* Hevea_ (Objective Caml)
* `MathJax for Node`_
* KaTeX_
- __ http://www.cs.tut.fi/~jkorpela/math/
__ http://www.zipcon.net/~swhite/docs/math/math.html
.. _elyxer: http://elyxer.nongnu.org/
- .. _TtH: ttp://hutchinson.belmont.ma.us/tth/index.html
.. _Hevea: http://para.inria.fr/~maranget/hevea/
.. _KaTeX: https://katex.org
-images
- (PNG or SVG) like e.g. Wikipedia.
-
- * dvisvgm_
- * the pure-python MathML->SVG converter SVGMath_)
- * `MathJax for Node`_
-
- .. _dvisvgm: http://dvisvgm.sourceforge.net/
- .. _SVGMath: http://www.grigoriev.ru/svgmath/
-
-
client side JavaScript conversion
Use TeX notation in the web page and JavaScript in the displaying browser.
(implemented as `math-output setting`_ "mathjax").
Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt 2024-06-10 14:24:00 UTC (rev 9749)
+++ trunk/docutils/docs/user/config.txt 2024-06-11 08:55:31 UTC (rev 9750)
@@ -1264,8 +1264,7 @@
The failsafe fallback.
-:Default: "HTML math.css". The default for the HTML5 writer will change
- to "MathML" in Docutils 0.22.
+:Default: writer dependent (see `[html4css1 writer]`_, `[html5 writer]`_).
:Option: ``--math-output``.
.. _MathJax: http://www.mathjax.org/
@@ -1406,6 +1405,7 @@
.. class:: run-in narrow
:`initial_header_level`_: 1 (for "<h1>").
+:`math_output`_: "HTML math.css".
:`stylesheet_path <stylesheet_path [html writers]_>`__: "html4css1.css".
:`xml_declaration <xml_declaration [html writers]_>`__: True.
@@ -1449,6 +1449,7 @@
.. class:: run-in narrow
:initial_header_level_: 2 (reserve <h1> for the `document title`_). [#]_
+:`math_output`_: "MathML" (changed in Docutils 0.22).
:`stylesheet_path <stylesheet_path [html writers]_>`__:
"minimal.css, plain.css".
:`xml_declaration <xml_declaration [html writers]_>`__: False.
Modified: trunk/docutils/docs/user/html.txt
===================================================================
--- trunk/docutils/docs/user/html.txt 2024-06-10 14:24:00 UTC (rev 9749)
+++ trunk/docutils/docs/user/html.txt 2024-06-11 08:55:31 UTC (rev 9750)
@@ -98,7 +98,7 @@
:front-end: rst2html5_
:config: `[html5 writer]`_
-The ``html5_polyglot`` writer generates `polyglot HTML`_ [#]_ output, valid
+The ``html5`` writer generates `polyglot HTML`_ output, valid
XML [#safetext]_ that is compatible with `HTML5`_. New features and elements
are used if they are widely supported.
See the `HTML5 test page`_ (and the sources `html5-features.txt`_ and
@@ -114,7 +114,6 @@
New in Docutils 0.13
-.. [#] see also `Benefits of polyglot XHTML5`_
.. [#safetext] The validity of raw HTML and custom stylesheets must be
ensured by the author.
.. _HTML5 test page: https://docutils.sourceforge.io/test/functional/
Modified: trunk/docutils/docutils/writers/_html_base.py
===================================================================
--- trunk/docutils/docutils/writers/_html_base.py 2024-06-10 14:24:00 UTC (rev 9749)
+++ trunk/docutils/docutils/writers/_html_base.py 2024-06-11 08:55:31 UTC (rev 9750)
@@ -115,10 +115,9 @@
['--table-style'],
{'default': ''}),
('Math output format (one of "MathML", "HTML", "MathJax", '
- 'or "LaTeX") and option(s). '
- '(default: "HTML math.css")',
+ 'or "LaTeX") and option(s). (default: "MathML")',
['--math-output'],
- {'default': 'HTML math.css',
+ {'default': 'MathML',
'validator': frontend.validate_math_output}),
('Prepend an XML declaration. ',
['--xml-declaration'],
@@ -238,7 +237,6 @@
"""
doctype = '<!DOCTYPE html>\n'
- doctype_mathml = doctype
head_prefix_template = ('<html xmlns="http://www.w3.org/1999/xhtml"'
' xml:lang="%(lang)s" lang="%(lang)s">\n<head>\n')
@@ -1363,7 +1361,6 @@
math_code = self.encode(math_code)
elif format == 'mathml':
if 'XHTML 1' in self.doctype:
- self.doctype = self.doctype_mathml
self.content_type = self.content_type_mathml
if self.math_options:
converter = getattr(tex2mathml_extern, self.math_options)
Modified: trunk/docutils/docutils/writers/html4css1/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html4css1/__init__.py 2024-06-10 14:24:00 UTC (rev 9749)
+++ trunk/docutils/docutils/writers/html4css1/__init__.py 2024-06-11 08:55:31 UTC (rev 9750)
@@ -68,6 +68,12 @@
['--initial-header-level'],
{'choices': '1 2 3 4 5 6'.split(), 'default': '1',
'metavar': '<level>'}),
+ math_output=(
+ 'Math output format (one of "MathML", "HTML", "MathJax", or '
+ '"LaTeX") and option(s). (default: "HTML math.css")',
+ ['--math-output'],
+ {'default': 'HTML math.css',
+ 'validator': frontend.validate_math_output}),
xml_declaration=(
'Prepend an XML declaration (default). ',
['--xml-declaration'],
Modified: trunk/docutils/test/data/help/docutils.txt
===================================================================
--- trunk/docutils/test/data/help/docutils.txt 2024-06-10 14:24:00 UTC (rev 9749)
+++ trunk/docutils/test/data/help/docutils.txt 2024-06-11 08:55:31 UTC (rev 9750)
@@ -194,8 +194,8 @@
right, colwidths-auto, colwidths-grid.
--math-output=MATH_OUTPUT
Math output format (one of "MathML", "HTML",
- "MathJax", or "LaTeX") and option(s). (default: "HTML
- math.css")
+ "MathJax", or "LaTeX") and option(s). (default:
+ "MathML")
--xml-declaration Prepend an XML declaration.
--no-xml-declaration Omit the XML declaration (default).
--cloak-email-addresses
Modified: trunk/docutils/test/functional/expected/misc_rst_html5.html
===================================================================
--- trunk/docutils/test/functional/expected/misc_rst_html5.html 2024-06-10 14:24:00 UTC (rev 9749)
+++ trunk/docutils/test/functional/expected/misc_rst_html5.html 2024-06-11 08:55:31 UTC (rev 9750)
@@ -7,7 +7,6 @@
<title>Additional tests with HTML 5</title>
<link rel="stylesheet" href="../input/data/minimal.css" type="text/css" />
<link rel="stylesheet" href="../input/data/responsive.css" type="text/css" />
-<link rel="stylesheet" href="../input/data/math.css" type="text/css" />
</head>
<body class="with-toc">
<main id="additional-tests-with-html-5">
@@ -48,7 +47,12 @@
</li>
<li><p><a class="reference internal" href="#section-titles-with-inline-markup" id="toc-entry-10">Section titles with inline markup</a></p>
<ul>
-<li><p><a class="reference internal" href="#emphasized-h2o-x-2-and-references" id="toc-entry-11"><em>emphasized</em>, H<sub>2</sub>O, <span class="formula"><i>x</i><sup>2</sup></span>, and references</a></p></li>
+<li><p><a class="reference internal" href="#emphasized-h2o-x-2-and-references" id="toc-entry-11"><em>emphasized</em>, H<sub>2</sub>O, <math xmlns="http://www.w3.org/1998/Math/MathML">
+ <msup>
+ <mi>x</mi>
+ <mn>2</mn>
+ </msup>
+</math>, and references</a></p></li>
<li><p><a class="reference internal" href="#substitutions-fail" id="toc-entry-12">Substitutions work</a></p></li>
</ul>
</li>
@@ -95,7 +99,12 @@
<section id="section-titles-with-inline-markup">
<span id="references"></span><h2><a class="toc-backref" href="#contents" role="doc-backlink">Section titles with inline markup</a><a class="self-link" title="link to this section" href="#section-titles-with-inline-markup"></a></h2>
<section id="emphasized-h2o-x-2-and-references">
-<h3><em>emphasized</em>, H<sub>2</sub>O, <span class="formula"><i>x</i><sup>2</sup></span>, and <a class="reference internal" href="#references">references</a><a class="self-link" title="link to this section" href="#emphasized-h2o-x-2-and-references"></a></h3>
+<h3><em>emphasized</em>, H<sub>2</sub>O, <math xmlns="http://www.w3.org/1998/Math/MathML">
+ <msup>
+ <mi>x</mi>
+ <mn>2</mn>
+ </msup>
+</math>, and <a class="reference internal" href="#references">references</a><a class="self-link" title="link to this section" href="#emphasized-h2o-x-2-and-references"></a></h3>
</section>
<section id="substitutions-fail">
<h3><a class="toc-backref" href="#contents" role="doc-backlink">Substitutions work</a><a class="self-link" title="link to this section" href="#substitutions-fail"></a></h3>
Modified: trunk/docutils/test/functional/expected/standalone_rst_html5.html
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_html5.html 2024-06-10 14:24:00 UTC (rev 9749)
+++ trunk/docutils/test/functional/expected/standalone_rst_html5.html 2024-06-11 08:55:31 UTC (rev 9750)
@@ -16,7 +16,6 @@
<link rel="schema.dcterms" href="http://purl.org/dc/terms/"/>
<link rel="stylesheet" href="../input/data/minimal.css" type="text/css" />
<link rel="stylesheet" href="../input/data/plain.css" type="text/css" />
-<link rel="stylesheet" href="../input/data/math.css" type="text/css" />
</head>
<body class="with-toc">
<header>
@@ -1012,7 +1011,16 @@
Inline markup is supported, e.g. <em>emphasis</em>, <strong>strong</strong>, <span class="docutils literal">literal
text</span>, <sub>sub-</sub> and <sup>super</sup>scripts,
-inline formulas: <span class="formula"><i>A</i> = 2<i>π</i><i>r</i><sup>2</sup></span>,
+inline formulas: <math xmlns="http://www.w3.org/1998/Math/MathML">
+ <mi>A</mi>
+ <mo>=</mo>
+ <mn>2</mn>
+ <mi>π</mi>
+ <msup>
+ <mi>r</mi>
+ <mn>2</mn>
+ </msup>
+</math>,
footnotes <a class="brackets" href="#footnote-1" id="footnote-reference-9" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>, <span class="target" id="hyperlink-targets">hyperlink targets</span>, and <a class="reference external" href="http://www.python.org/">references</a>.</pre>
</section>
<section id="code">
@@ -1034,7 +1042,14 @@
or as base for special code roles, e.g. the LaTeX code in the next
paragraph.</p>
<p>Docutils uses LaTeX syntax for math directives and roles:
-<code class="tex">\alpha = f(x)</code> prints <span class="formula"><i>α</i> = <i>f</i>(<i>x</i>)</span>.</p>
+<code class="tex">\alpha = f(x)</code> prints <math xmlns="http://www.w3.org/1998/Math/MathML">
+ <mi>α</mi>
+ <mo>=</mo>
+ <mi>f</mi>
+ <mo stretchy="false">(</mo>
+ <mi>x</mi>
+ <mo stretchy="false">)</mo>
+</math>.</p>
<p>The <span class="docutils literal">:code:</span> option of the <cite>include</cite> directive sets the included content
as a code block, here the rst file <span class="docutils literal">header_footer.txt</span> with line numbers:</p>
<pre class="code rst literal-block"><small class="ln">1 </small><code data-lineno="1 ">.. header:: Document header
Modified: trunk/docutils/test/test_writers/test_html5_polyglot_misc.py
===================================================================
--- trunk/docutils/test/test_writers/test_html5_polyglot_misc.py 2024-06-10 14:24:00 UTC (rev 9749)
+++ trunk/docutils/test/test_writers/test_html5_polyglot_misc.py 2024-06-11 08:55:31 UTC (rev 9750)
@@ -184,11 +184,11 @@
data = ':math:`42`'
def test_math_output_default(self):
- # HTML with math.css stylesheet (since 0.11)
+ # default math output is MathML (since 0.22)
mys = {'_disable_config': True}
- styles = core.publish_parts(self.data, writer_name='html5_polyglot',
- settings_overrides=mys)['stylesheet']
- self.assertIn('convert LaTeX equations to HTML output.', styles)
+ fragment = core.publish_parts(self.data, writer_name='html5_polyglot',
+ settings_overrides=mys)['fragment']
+ self.assertIn('<mn>42</mn>', fragment)
def test_math_output_mathjax(self):
# Explicitly specifying math_output=MathJax, case insensitively
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins