.. 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 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/ `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 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. - 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. Misc ---- * 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 or later. 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 (unpublished) ========================== * 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`). * 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. .. _input encoding: docs/api/publisher.html#encodings * "html5" writer: Stop setting the "footnote-reference" class value for footnote references. You can use the CSS selector ``[role="doc-noteref"]`` since Docutils 0.18 (see minimal.css for examples). * Use the same CSV format for the ``:header:`` option and the main data of the "csv-table_" directive. * Removed objects: - `nodes.reprunicode` and `nodes.ensure_str()` (not required with Python 3), `utils.Reporter.set_conditions()` (obsolete) `core.Publisher.setup_option_parser()` (internal, obsolete) - File ``install.py``. See README.txt__ for alternatives. .. _csv-table: docs/ref/rst/directives.html#csv-table __ README.html#installation Release 0.20.1 (2023-05-17) =========================== Bugfix release. See HISTORY_ for details. Release 0.20 (2023-05-04) ========================= .. Note:: Docutils 0.20 is the last version supporting Python 3.7 and 3.8. * General - Support Python 3.11 (patch #198 by Hugo van Kemenade). * 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`_ * `utils.find_file_in_dirs()` now returns a POSIX path also on Windows; `utils.get_stylesheet_list()` no longer converts ``\`` to ``/``. * docutils/languages/ docutils/parsers/rst/languages/ - Support Ukrainian. Patch by Dmytro Kazanzhy. * test/coverage.sh - Removed. Use the coverage.py_ project instead, ``coverage run test/alltests.py`` and ``coverage report``. .. _coverage.py: https://pypi.org/project/coverage/ * tools/ - Moved ``quicktest.py`` to ``tools/dev/``. * Bugfixes and improvements (see HISTORY_). .. _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 ``