| Contact: | grubert@users.sourceforge.net |
|---|---|
| Maintainer: | docutils-develop@lists.sourceforge.net |
| Date: | 2022-07-05 |
| Revision: | 9103 |
| Web site: | https://docutils.sourceforge.io/ |
| Copyright: | This document has been placed in the public domain. |
This document summarizes the major changes in recent and upcoming releases. For a more detailed list of changes, please see the Docutils HISTORY.
Contents
Setup:
Input encoding:
Reduce chances of unrecognised character mix-ups (mojibake).
Stop using the hard-coded fallback "latin-1" if the input-encoding is not specified and decoding with UTF-8 fails.
Don't use the locale encoding as fallback in UTF-8 mode.
Only remove BOM (U+FEFF ZWNBSP at start of data), no other ZWNBSPs.
html5 writer:
latex2e writer:
xetex writer:
Remove the "rawsource" argument from nodes.Text.__init__() (deprecated and ignored since Docutils 0.18) in Docutils 2.0.
Remove the compatibility hacks nodes.reprunicode and nodes.ensure_str() in Docutils 0.21 or later. They are not required with Python 3.x.
Drop support for old-format configuration files in Docutils 2.0.
Move math format conversion from docutils/utils/math (called from docutils/writers/_html_base.py) to a transform.
The default HTML writer "html" with frontend rst2html.py will change from "html4css1" to "html5" in Docutils 2.0.
Use get_writer_by_name('html') or the rst2html.py front end, if you want the output to be up-to-date automatically.
Use the "html4" writer or rst2html4.py, if you depend on stability of the generated HTML code, e.g. because you use a custom style sheet or post-processing that may break otherwise.
Remove the --html-writer option of the buildhtml.py application (obsoleted by the "writer" option) in Docutils 2.0.
(Release 0.19b1 (2022-06-21))
Drop support for Python 2.7, 3.5, and 3.6.
Output changes:
Wrap groups of footnotes in an <aside> for easier styling.
The CSS rule .footnote-list { display: contents; } can be used to restore the behaviour of custom CSS styles.
After package installation, the CLI commands python -m docutils and docutils start the generic command line front end tool.
Support parsing "Markdown" input with 3rd party parsers myst, pycmark, or recommonmark.
The default values for the "pep-references", "rfc-base-url", and "python-home" configuration settings now use the "https:" scheme. The PEP-writer template's header is updated to fix links and resemble the header of official PEPs.
Various bugfixes and improvements (see HISTORY).
Note
Docutils 0.18.x is the last version supporting Python 2.7, 3.5, and 3.6.
Output changes:
During identifier normalization, leading number and hyphen characters are no longer stripped from a reference name, if the id_prefix setting is non-empty.
with --id-prefix="DU-", a section with title "34. May" currently gets the identifier key DU-may and after the change the identifier key DU-34-may.
The default value for the auto_id_prefix setting changed to %: "use the tag name as prefix for auto-generated IDs". Set auto_id_prefix to id for unchanged auto-IDs.
Use the semantic tag <aside> for footnote text and citations, topics (except abstract and toc), admonitions, and system messages. Use <nav> for the Table of Contents.
Make "auto" table column widths the default: Only specify column widths, if the "widths" option is set and not "auto". The table-style setting "colwidths-grid" restores the current default.
Items of a definition list with class argument "details" are converted to details disclosure elements. Example:
..class:: details Summary This additional information should be hidden.
Do not add "compound-first", "compound-middle", or "compound-last" to elements nested in a compound. Use child selector and ":first-child", ":last-child" pseudo classes instead.
Use class value "backrefs" instead of "fn-backref" for a span of back-references.
Write footnote brackets and field term colons to HTML, so that they are present also without CSS and when copying text.
Move space character between section number and heading into "sectnum" span.
legacy_class_functions setting default changed to "False", admonitions are now environments.
New standard Docutils doctree node: <meta>.
New configuration settings:
Removed files: iepngfix.htc and blank.gif (IE 6 workaround for s5_html).
Removed sub-module: parsers.rst.directives.html (reversed in release 0.18.1).
Removed function: utils.unique_combinations() (obsoleted by itertools.combinations()).
Removed attributes:
Major refactoring and fixes/additions in docutils/utils/math/math2html.py and docutils/utils/math/latex2mathml.py (mathematical notation in HTML, cf. LaTeX syntax for mathematics).
nodes.Node.traverse() returns an iterator instead of a list (reversed in release 0.18.1).
Various bugfixes and improvements (see HISTORY).
Fix spelling errors in documentation and docstrings. Thanks to Dimitri Papadopoulos.
Note
Docutils 0.15.x is the last version supporting Python 2.6, 3.3 and 3.4.
Docutils 0.16.x supports Python 2.7 and Python >= 3.5 natively, without the use of the 2to3 tool.
Note
Docutils 0.14.x is the last version supporting Python 2.4, 2.5, 3.1, and 3.2.
Docutils 0.15.x is compatible with Python versions 2.6, 2.7 and 3.3 to 3.5 (cf. Python 3 compatibility).
Small changes only, release current state
General
docutils/parsers/rst/directives/tables.py
docutils/writers/html4css1/__init__.py - Fix [ 3600051 ] for tables in a list, table cells are not compacted. - New setting stylesheet_dirs (see above).
Now, it is easy to add a custom stylesheet to Docutils' default stylesheet with, e.g., --stylesheet_path='html4css1.css, mystyle.css'
- Changed behaviour of the default settings:
if there is a file html4css1.css in the working directory of the process at launch, it is used instead of the one provided by Docutils in the writer source directory.
docutils/writers/latex2e/__init__.py
docutils/writers/manpage.py
Note
Docutils 0.9.x is the last version supporting Python 2.3.
Docutils 0.10 is compatible with Python versions from 2.4 to 3.2 (cf. Python 3 compatibility).
General:
SmartQuotes transform for typographic quotes and dashes.
docutils/math, docutils/error_reporting.py, and docutils/urischemes.py moved to the utils package. Code importing these modules needs to adapt, e.g.:
try:
import docutils.math as math
except ImportError:
import docutils.utils.math as math
enhanced math and error handling.
docutils/io.py
docutils/writers/html4css1/__init__.py
docutils/writers/latex2e/__init__.py, docutils/writers/xetex/__init__.py
docutils/writers/s5_html/__init__.py
General:
Several fixes for Python 3 usage.
docutils/setup.py
Fix [ 3527842 ]. Under Python 3, converted tests and tools were installed in the PYTHONPATH. Converted tests are now stored in docutils/test3/, tools no longer need conversion.
If you installed one of Docutils versions 0.7 ... 0.9 with setup.py install under Python 3, remove the spurious test/ and tools/ directories in the site library root.
General:
setup.py
docutils/utils.py -> docutils/utils/__init__.py
docutils/writers/html4css1/__init__.py
docutils/writers/latex2e/__init__.py
COPYING:
General:
reStructuredText:
most directives now support a "name" option that attaches a reference name. So you can write
.. figure:: image.png :name: figure name
as a short form of
.. _figure name: .. figure:: image.png
Internationalization:
Components:
HTML writer:
LaTeX2e writer:
XeTeX writer:
New writer generating LaTeX code for compiling with xelatex.
XeTeX uses unicode and modern font technologies.
and fixes and enhancements here and there.
Components:
General:
Note
Docutils 0.5 is the last version supporting Python 2.2.
Docutils 0.6 is compatible with Python versions from 2.3 up to 2.6 and convertible to 3.1 code.
Note
The "newlatex" writer is orphaned.
The recommended way to generate PDF output is to use either the LaTeX2e writer or one of the alternatives listed at https://docutils.sourceforge.io/docs/user/links.html#pdf.
Components:
reStructuredText:
Documentation:
Internationalization:
General:
Note
Docutils 0.4.x is the last version that will support Python 2.1. Docutils 0.5 will not be compatible with Python 2.1; Python 2.2 or later will be required.
Docutils 0.4.x is the last version that will make compromises in its HTML output for Netscape Navigator 4. Docutils 0.5 will require more up-to-date browsers (the exact definition is to be determined).
Components:
reStructuredText:
Internationalization:
Documentation:
General: