Docutils

=========================

* Drop support for Python 2.7, 3.5, and 3.6.

* Output changes:

HTML5:
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_).

.. _generic command line front end tool:
docs/user/tools.htmlgeneric-command-line-front-end
.. _myst: https://pypi.org/project/myst-docutils
.. _pycmark: https://pypi.org/project/pycmark/
.. _recommonmark: https://pypi.org/project/recommonmark/
.. _configuration settings: docs/user/config.html

===========================

.. Note::

Docutils 0.18.1 is the last version supporting Python 2.7, 3.5, and 3.6.

* ``nodes.Node.traverse()`` returns a list again to restore backwards
compatibility (fixes bug 431).
Use ``nodes.Node.findall()`` to get an iterator.

* re-add module ``parsers.rst.directives.html``
(stub, emits deprecation warning and loads
"Meta" directive from its new place at ``parsers.rst.directives.misc``.)

* Small bugfixes (see HISTORY_).

=========================

* Output changes:

Identifiers:
- During `identifier normalization`_, leading number and hyphen
characters are no longer stripped from a `reference name`_, if the
id_prefix_ setting is non-empty.

Example:
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.

HTML5:
- 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.

__ docs/user/config.htmltable-style

- 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.

`math-output`_: html
- Support more commands, fix mapping of commands to Unicode characters.
- Scale variable sized operators and big delimiters with CSS.
- Don't use <tt> element (deprecated in HTML5).
- Use STIX fonts if available.

LaTeX:
`legacy_class_functions`_ setting default changed to "False",
admonitions are now environments.

* New standard Docutils doctree node: <meta__>.

__ docs/ref/doctree.htmlmeta

* New configuration settings:

- [latex writers] legacy_column_widths_ and
- [html5 writer] image_loading_.

* 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:

- ``HTMLTranslator.topic_classes``: check ``node.parent.classes`` instead.
- ``nodes.Text.rawsource``: we store the null-escaped text in Text
nodes since 0.16 so there is no additional information in the
rawsource.

* 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.

.. _"widths" option: __ docs/ref/rst/directives.htmltable
.. _identifier normalization:
docs/ref/rst/directives.htmlidentifier-normalization
.. _id_prefix: docs/user/config.htmlid-prefix
.. _auto_id_prefix: docs/user/config.htmlauto-id-prefix
.. _details disclosure elements:
https://www.w3.org/TR/html52/interactive-elements.html#the-details-element
.. _LaTeX syntax for mathematics: docs/ref/rst/mathematics.html
.. _legacy_column_widths: docs/user/config.htmllegacy-column-widths

===========================

* Bug fixes (for details see the Docutils `HISTORY`_).

=========================

* Numerous bug fixes and improvements
(for details see the Docutils `HISTORY`_).

* Installing with ``setup.py`` now requires setuptools_.
Alternatively, install with pip_.

* The generic command line front end tool docutils-cli.py_ allows
the free selection of reader, parser, and writer components.

* Support Arabic language.

* New, **experimental** wrapper to integrate the `recommonmark`__
Markdown parser for use with Docutils.
Currently only tested with recommonmark version 0.4.0.

__ https://pypi.org/project/recommonmark/

* HTML5 writer:

- New option embed_images_.

- Use semantic tags (for details see the Docutils `HISTORY`_).

- Change the `initial_header_level`_ setting's default to "2", as browsers
use the `same style for <h1> and <h2> when nested in a section`__.

- New optional style ``responsive.css``, adapts to different screen
sizes.

- Move non-essential styling from ``minimal.css`` to ``plain.css``
rsp. ``responsive.css``.

- Show code line numbers as pseudo-elements so they are skipped when
copying the code block from the page.

.. _initial_header_level: docs/user/config.htmlinitial-header-level
__ https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article
.. _embed_images: docs/user/config.htmlembed-images

* LaTeX writer:

- New configuration setting `legacy_class_functions`_.

- The special value "auto" for the `graphicx_option`_ setting
is no longer supported (it never worked for xetex/luatex).

- `Styling commands`__ using the legacy ``\docutilsrole`` prefix are
now ignored. Use ``\DUrole``.

__ docs/user/latex.htmlclasses

- Most helper commands and element definitions are now defined in the
LaTeX package `docutils.sty`_ and only inserted in the document
preamble if the stylesheet__ setting does not lists "docutils".

__ docs/user/config.htmlstylesheet-latex-writers

- Remove legacy LaTeX stylesheet ``docutils-05-compat.sty``.

.. _setuptools: https://pypi.org/project/setuptools/
.. _pip: https://pypi.org/project/pip/
.. _docutils-cli.py: docs/user/tools.htmldocutils-cli-py
.. _legacy_class_functions: docs/user/config.htmllegacy-class-functions
.. _graphicx_option: docs/user/config.htmlgraphicx-option
.. _docutils.sty: https://ctan.org/pkg/docutils