Docutils: Documentation Utilities Files

=============================
 Docutils Release Notes 0.21
=============================

:Contact: grubert@users.sourceforge.net
:Maintainer: docutils-develop@lists.sourceforge.net
:Date: $Date: 2024-04-09 20:03:15 +0200 (Di, 09. Apr 2024) $
:Revision: $Revision: 9621 $
:Web site: https://docutils.sourceforge.io/
:Copyright: This document has been placed in the public domain.


This document summarizes the major changes in previous and upcoming releases.
For a more detailed list of changes, please see the Docutils `HISTORY`_.

.. contents::

Future changes
==============

Command line interface
----------------------

* The _`command-line usage pattern` will change:

  .. code:: diff

       - COMMAND [OPTIONS] [SOURCE [DESTINATION]]
       + COMMAND [OPTIONS] [SOURCE [SOURCE2 [...]]] [>DESTINATION]

  * Remove short options ``-i`` and ``-o`` in Docutils 0.22.
    Use the long equivalents ``--input-encoding`` and ``--output-encoding``.

  * Stop accepting the DESTINATION positional argument in Docutils 1.0.
    Use output redirection or the option ``--output=DESTINATION``
    (available since Docutils 0.20).

  * Accept more than one source document and the short option
    ``-o`` for ``--output`` in Docutils 2.0

  For the rationale, see https://clig.dev/#arguments-and-flags.

.. _entry points:
    https://packaging.python.org/en/latest/specifications/entry-points/


Document Tree / Docutils DTD
----------------------------

* Do not lowercase reference names in the `refname attribute`_
  (matching hyperlinks, footnotes, and citations remains case insensitive),
  and drop the ``name`` attribute from <reference> nodes
  in Docutils 1.0.

.. _refname attribute: docs/ref/doctree.html#refname

`Input encoding`_
-----------------

* Change the default input encoding from ``None`` (auto-detect) to
  "utf-8" in Docutils 0.22.

* Remove the input encoding auto-detection code in Docutils 1.0 or later.

Writers
-------

* The `default HTML writer`__  will change in Docutils 2.0:

  The rst2html_ front end and ``get_writer_by_name('html')`` select
  "html4css1" now and will select "html5" in Docutils 2.0 and later.

  - Use rst2html4_, ``docutils --writer=html4``, or
    ``get_writer_by_name('html4')`` 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.
  - Use rst2html5_, ``docutils`` or ``get_writer_by_name('html5')``
    if you want a HTML5 document.

  __ docs/user/html.html#html

* "html5" writer:

  - Move attribution behind the blockquote to comply with the `"living
    standard"`__. (HTML5__ allows <cite> elements inside a blockquote.)

    __ https://html.spec.whatwg.org/#the-blockquote-element
    __ 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
    specification of the aspect ratio to `prevent jank when loading
    images`__ without overwriting an image size set in a CSS stylesheet
    in Docutils 0.22 (cf.  `feature-requests:102`__).
    The current behaviour is kept for dimensions with value, so
    users may specify, e.g. ``:width: 50px`` instead of ``:width: 50``
    to override CSS stylesheet rules.

    __ https://developer.mozilla.org/en-US/docs/Learn/Performance/Multimedia
       #rendering_strategy_preventing_jank_when_loading_images
    __ https://sourceforge.net/p/docutils/feature-requests/102/

  - Change the default value of the initial_header_level_ setting to None
    (<h2> if there is a document title, else <h1>) in Docutils 1.0.

  - Remove option ``--embed-images`` (obsoleted by "image_loading_")
    in Docutils 2.0.

* "latex2e" writer:

  - Change default of use_latex_citations_ setting to True
    in Docutils 1.0.

  - Change default of legacy_column_widths_ setting to False
    in Docutils 1.0.

  - Remove ``use_verbatim_when_possible`` setting
    (use literal_block_env_: verbatim) in Docutils 2.0.

  - Don't wrap references with custom reference-label_ in
    a ``\hyperref`` command in Docutils 0.22.
    Specify, e.g., "ref" instead of "ref*" to keep generating hyperlinks.

    .. _reference-label: docs/user/config.html#reference-label

* "null" writer: output will change to the empty string
  in Docutils 0.22.

* "manpage" writer:

  - No more changing case in to uppercase, leave it to the source.


Misc
----

* Document tree:
  Allow multiple <term> elements in a <definition_list_item>
  in Docutils 0.22 (cf. `feature-requests:60`__).
  Third-party writers may need adaption.

  __ https://sourceforge.net/p/docutils/feature-requests/60/

* Remove `parsers.rst.directives.CSVTable.HeaderDialect`
  in Docutils 0.22.

* Remove the "rawsource" argument from `nodes.Text.__init__()`
  in Docutils 2.0.

* Drop support for `old-format configuration files`_ in Docutils 2.0.

* Remove the ``--html-writer`` option of the `buildhtml.py`_ application
  (obsoleted by the `"writer" setting`_ since Docutils 0.18)
  in Docutils 2.0.

* Revise the `String I/O`__ interface used by the `publish_string()`
  and `publish_from_doctree()` publisher convenience functions.
  (In Python 3, name and behaviour no longer match.)

  __ docs/api/publisher.html#string-i-o

* Move math format conversion from docutils/utils/math (called from
  docutils/writers/_html_base.py) to a transform__.

  __ docs/ref/transforms.html

* Remove mistranslated localizations of the "admonition" directive name in
  Docutils 0.22.

  Use the English term, matching translations introduced in Docutils 0.21,
  or specific admonitions instead of "aanmaning" (nl),
  "admonition" (fr), "ammonizione" (it), "ermahnung" (de),
  "exhortación" (es), "formaning" (da), "sciigo" (eo),
  "upomnienie" (pl), "vermaning" (af),
  to avoid errors in future conversions.

.. _front end tools: docs/user/tools.html
.. _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:
   docs/user/config.html#old-format-configuration-files
.. _rst2html.py:
.. _rst2html: docs/user/tools.html#rst2html
.. _rst2html4: docs/user/tools.html#rst2html4
.. _rst2html5: docs/user/tools.html#rst2html5
.. _reference name: docs/ref/rst/restructuredtext.html#reference-names
.. _literal_block_env: docs/user/config.html#literal-block-env
.. _use_latex_citations: docs/user/config.html#use-latex-citations
.. _buildhtml.py: docs/user/tools.html#buildhtml-py


Release 0.21 (2024-04-09)
=========================

* General:

  - Drop support for Python 3.7 and 3.8.

  - Provide ``rst2*`` "console_scripts" `entry points`_
    (without the ``.py`` extension) instead of installing the
    ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_

    Exceptions: ``rstpep2html.py`` and ``rst2odt_prepstyles.py``:

    - Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview. [#]_
    - Use ``python -m docutils.writers.odf_odt.prepstyles``
      to `strip the page size`__ from an ODT writer stylesheet.

    __ docs/user/odt.html#page-size

  .. [#] Some Linux distributions already use the short names.
  .. [#] The final rendering is done by a Sphinx-based build system
         (cf. :PEP:`676`).

* reStructuredText:

  - Use the same CSV format for the ``:header:`` option and the main data
    of the "csv-table_" directive.

  - New option "loading" for the `"image" directive`_.
    Sets the new attribute loading__ of the <image> doctree element.

  __ docs/ref/doctree.html#loading

* Configuration changes:

  - New configuration setting root_prefix_.
    Configurable root directory for included files.

  - New configuration setting sources_ for the "buildhtml.py" application.

  - Simpler and more secure `input encoding`_ default behaviour:

    Do not use the locale encoding as fallback if Python is started in
    `UTF-8 mode`_. Stop using "latin1" as second fallback.

    Remove BOM (U+FEFF ZWNBSP at start of data) only if the `input_encoding`_
    configuration setting is None, '', 'utf-8-sig', 'utf-16', or 'utf-32'.
    Do not remove other ZWNBSPs.

* Output changes:

  HTML5:
    Stop setting the "footnote-reference" class value for footnote
    references. Use the CSS selector ``[role="doc-noteref"]``
    (works since Docutils 0.18, see minimal.css for examples).

    Fix MathML rendering problems in Chrome/Chromium based browsers.

    Embed SVG images as ``<svg>`` instead of data-URI.

  manpage:
    Use .EE/.EX macros for literal blocks.

    Render URI references (do not use .UR/.UE).

    Use box option for tables.

* Removed objects:

  `docutils.nodes.reprunicode`, `docutils.nodes.ensure_str()`
    Python 2 compatibility hacks
  `docutils.utils.Reporter.set_conditions()`
    obsolete
  `docutils.core.Publisher.setup_option_parser()`
    internal, obsolete

* New files:

  ``docutils/writers/html5_polyglot/italic-field-names.css``
    Alternative style for Docutils field-lists.

* Removed files:

  ``install.py``, ``setup.py``
    Metadata is now stored in ``pyproject.toml``,
    supported by pip_ since version 19.0 (2019-01-22).
    See README__ for installation alternatives.

  __ README.html#installation

* Bugfixes and improvements (see HISTORY_).

.. _input encoding: docs/api/publisher.html#encodings
.. _csv-table: docs/ref/rst/directives.html#csv-table
.. _"image" directive: docs/ref/rst/directives.html#image
.. _root_prefix: docs/user/config.html#root-prefix
.. _sources: docs/user/config.html#sources