.. include:: docs/header0.txt ======================== Docutils Release Notes ======================== :Contact: grubert@users.sourceforge.net :Maintainer: docutils-develop@lists.sourceforge.net :Date: $Date$ :Revision: $Revision$ :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:: Future changes ============== Drop support for Python 3.7 and 3.8 in Docutils 0.21. * Usage: - Docutils 0.21 will provide ``rst2*`` `"console_scripts" entry points`_ (without the ``.py`` extension) instead of installing the ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_ You may use the ``docutils`` `generic command line front end tool`_ as a future-proof command, for example: .. code:: diff - rst2latex.py --use-latex-abstract FAQ.txt > FAQ.tex + docutils --writer=latex --use-latex-abstract FAQ.txt > FAQ.tex Exceptions: The auxilliary script ``rst2odt_prepstyles.py`` will become available via ``python -m docutils.writers.odf_odt.prepstyles``. The ``rstpep2html.py`` script will be retired. Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview (the final rendering is done by a Sphinx-based build system, cf. :PEP:`676`). .. [#] Some Linux distributions already use the short names. .. _"console_scripts" entry points: https://packaging.python.org/en/latest/specifications/entry-points/ - 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 * The _`command-line usage pattern` will change: .. code:: diff - [options] [ []] + [options] source [source2 [source3 [...]]] * Remove short options ``-i`` and ``-o`` in Docutils 0.22. Use the long equivalents ``--input-encoding`` and ``--output-encoding``. * Stop accepting the `` positional argument in Docutils 1.0. Use output redirection ``>`` or the option ``--output=`` (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. * `Input encoding`_: - Raise UnicodeError (instead of falling back to the locale encoding) if decoding the source with the default encoding (UTF-8) fails and Python is started in `UTF-8 mode`_. (Docutils 0.21) Raise UnicodeError (instead of falling back to "latin1") if both, default and locale encoding, fail. (Docutils 0.21) - Only remove BOM (U+FEFF ZWNBSP at start of data), no other ZWNBSPs. Only remove BOM with `input_encoding`_ values None, '', 'utf-8-sig', 'utf-16', and 'utf-32'. (Docutils 0.21) - 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. * "csv-table_" directive: - Use the same CSV format for the main CSV data and the :header: option (as specified in the documentation since addition of "csv-table_") in Docutils 0.21. - Move `parsers.rst.directives.Table.process_header_option()` to `parsers.rst.directives.CSVTable` in Docutils 0.21. - Remove `parsers.rst.directives.CSVTable.HeaderDialect` in Docutils 0.22. * "html5" writer: - Stop setting the "footnote-reference" class value for footnote references in Docutils 0.21. Since 0.18, you can use the CSS selector ``[role="doc-noteref"]`` instead of ``.footnote-reference`` (see minimal.css for examples). - Move attribution behind the blockquote to comply with the `"living standard"`__. (HTML5__ allows 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. - 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. * "null" writer: output will change to the empty string in Docutils 0.22. * The default value of the `auto_encode` argument of `core.publish_str()`, `core.publish_from_doctree()`, and `core.publish_programmatically()` will change to ``False`` in Docutils 0.22. The functions will then return a `str` object by default. * 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. * Remove file ``install.py`` in Docutils 0.21. See README.txt__ for alternatives. __ README.html#installation * Move math format conversion from docutils/utils/math (called from docutils/writers/_html_base.py) to a transform__. __ docs/ref/transforms.html * Remove the ``--html-writer`` option of the `buildhtml.py`_ application (obsoleted by the `"writer" setting`_ since Docutils 0.18) in Docutils 2.0. .. _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: 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 .. _csv-table: docs/ref/rst/directives.html#csv-table Release 0.20 (unpublished) ========================== .. Note:: Docutils 0.20 is the last version supporting Python 3.7 and 3.8. * Output changes: HTML5: Use dpub-ARIA role "doc-footnote" (instead of ARIA role "note") for footnotes. LaTeX: Do not load the `inputenc` package in UTF-8 encoded LaTeX sources. (UTF-8 is the default encoding for LaTeX2e since 2018). * Configuration changes: - Settings in the [latex2e writer] configuration file section are now ignored by the "xetex" writer. Place common settings in section `[latex writers]`_. .. _[latex writers]: docs/user/config.html#latex-writers - New command line setting output_. Obsoletes the ```` positional argument (cf. `future changes`__). __ `command-line usage pattern`_ * The new function argument `auto_encode` for Publisher convenience functions with `String I/O`_ selects whether the output document is encoded and returned as `bytes` instance. The default is ``True`` (for backwards compatibility) and will change to ``False`` in Docutils 0.22. * `utils.find_file_in_dirs()` now returns a POSIX path also on Windows; `utils.get_stylesheet_list()` no longer converts ``\`` to ``/``. * Bugfixes and improvements (see HISTORY_). .. _String I/O: docs/api/publisher.html#string-i-o .. _output: docs/user/config.html#output Release 0.19 (2022-07-05) ========================= (Release 0.19b1 (2022-06-21)) * Drop support for Python 2.7, 3.5, and 3.6. * Output changes: HTML5: Wrap groups of footnotes in an ``