Update HISTORY and RELEASE-NOTES for the 0.20 release.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@9349 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

2 files changed, 96 insertions, 85 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index 57709edd3..6093e3710 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -13,8 +13,8 @@
 
 .. contents::
 
-Release 0.20b (unpublished)
-===========================
+Release 0.20 (unpublished)
+==========================
 
 * General
 
@@ -25,12 +25,12 @@ Release 0.20b (unpublished)
 
   - New argument "auto_encode" for `publish_string()`,
     `publish_from_docstring()` and `publish_programmatically()`.
-  - New functions `rst2…()` for use as "console_scripts" `entry point`_.
+  - New functions `rst2…()` for use as "console_scripts" `entry points`_.
 
 * docutils/frontend.py
 
-  - New setting ``output``. Obsoletes the ``<destination>`` positional
-    argument (cf. "Future changes" in the RELEASE-NOTES).
+  - New configuration setting output_. Obsoletes the ``<destination>``
+    positional argument (cf. `Future changes` in the RELEASE-NOTES_).
 
 * docutils/io.py
 
@@ -59,17 +59,19 @@ Release 0.20b (unpublished)
 
 * docutils/transforms/frontmatter.py
 
-  - `DocInfo` now accepts author names with initial like "A. Einstein"
-    (that are `parsed as enumerated list`__) in "author" fields
-    instead of rising an error.
+  - Accept author names with initials like ``A. Einstein`` in the "author"
+    `bibliographic field`_ instead of rising an error
+    (generally, such names are `parsed as enumerated list`__).
 
+    .. _bibliographic field:
+        docs/ref/rst/restructuredtext.html#bibliographic-fields
     __ docs/ref/rst/restructuredtext.html#enumerated-lists
 
 * docutils/transforms/references.py
 
-  - Ignore `citation_reference` nodes if the "use_bibex" setting is
-    active. In this case, citations are provided by LaTeX/BibTeX.
-    Fixes bug #384.
+  - `DanglingReferences` ignores `citation_reference` nodes if the
+    "use_bibex" setting is active. (In this case, citations are provided
+    by LaTeX/BibTeX.) Fixes bug #384.
 
 * docutils/utils/__init__.py
 
@@ -84,7 +86,8 @@ Release 0.20b (unpublished)
 
 * docutils/utils/math/tex2mathml_extern.py
 
-  - Support `pandoc` as LaTeX to MathML converter. Patch by Ximin Luo.
+  - Support `Pandoc` as alternative LaTeX to MathML converter.
+    Patch by Ximin Luo.
 
 * docutils/writers/_html_base.py
 
@@ -98,30 +101,33 @@ Release 0.20b (unpublished)
   - Wrap definition lists with "details" class argument in a <div>
     with the "id" and "class" values of the list node.
 
-  - Use dpub-ARIA role "doc-footnote" (instead of ARIA role "note")
+  - Use dpub-ARIA role "doc-footnote__" (instead of ARIA role "note")
     for footnotes.
 
+    __ https://www.w3.org/TR/dpub-aria-1.1/#doc-footnote
+
 * docutils/writers/latex2e/__init__.py
 
-  - Do not insert ``\usepackage[utf8]{inputenc}`` into UTF-8 encoded
-    LaTeX sources. UTF-8 is the default encoding for LaTeX2e since 2018.
-  - Fix handling of the "use_bibtex" setting.
+  - Do not load the `inputenc` package in UTF-8 encoded LaTeX sources.
+    (UTF-8 is the default encoding for LaTeX2e since 2018).
+  - Fix behaviour of the use_bibtex_ setting.
   - Outsource parts of `depart_document()` to new auxiliary methods
     `make_title()` and `append_bibliography()`.
   - Ensure POSIX paths in stylesheet loading macros.
 
 * docutils/writers/latex2e/titlepage.tex
 
-  - Drop ``\usepackage{fixltx2e}`` from template. (Obsolete since 2015
-    and dropped from other templates in Docutils 0.14.)
+  - Drop ``\usepackage{fixltx2e}`` from template.
+    (Obsolete since 2015 and dropped from other templates in Docutils 0.14.)
 
 * docutils/writers/manpage.py
 
-  - Do not output empty "manual" in ``.TH``
+  - Do not output empty "manual" in ``.TH``.
 
 * docutils/writers/xetex/__init__.py
 
-  - Ignore settings in the [latex2e writer] configuration file section.
+  - Ignore settings in the [latex2e writer] configuration file section
+    (users can place common settings in section [latex writers]).
 
 * setup.py
 
@@ -156,6 +162,7 @@ Release 0.20b (unpublished)
   - Moved ``quicktest.py`` to ``tools/dev/``.
 
 
+
 Release 0.19 (2022-07-05)
 =========================
 
@@ -258,9 +265,6 @@ Release 0.19 (2022-07-05)
 
   - New ``docutils``" console script `entry point`_. Fixes bug #447.
 
-    .. _entry point:
-        https://packaging.python.org/en/latest/specifications/entry-points/
-
 * test/alltests.py
 
   - Always encode the log file ``alltests.out`` using "utf-8".
@@ -284,6 +288,10 @@ Release 0.19 (2022-07-05)
 
   - Options ``-h`` and ``--help`` print short usage message.
 
+.. _entry point:
+.. _entry points:
+    https://packaging.python.org/en/latest/specifications/entry-points/
+
 
 Release 0.18.1 (2021-11-23)
 ===========================
@@ -355,8 +363,6 @@ Release 0.18 (2021-10-26)
   - New option `image_loading`_. Support "lazy" loading of images.
     Obsoletes `embed_images`_.
 
-    .. _image_loading: docs/user/config.html#image-loading
-
 * docutils/writers/pseudoxml.py
 
   - Fix spelling of setting `detailed`_.
@@ -1415,12 +1421,6 @@ __ https://mail.python.org/pipermail/image-sig/2011-January/006650.html
 
   - docutils.utils is now a package (providing a place for sub-modules)
 
-  .. note:: docutils/math, docutils/error_reporting.py, and
-     docutils/urischemes.py will move to the utils package in the next
-     release, too. See RELEASE-NOTES__
-
-     __ RELEASE-NOTES.html
-
   - DependencyList uses io.FileOutput and 'utf-8' encoding to prevent
     errors recording non-ASCII filenames (fixes [ 3434355 ]).
 
@@ -1819,8 +1819,7 @@ Release 0.5 (2008-06-25)
   - Configuration files are now assumed and required to be
     UTF-8-encoded.
   - Paths of applied configuration files are now recorded in the
-    runtime setting `_config_files`_ (accessible via
-    `dump_settings`_).
+    runtime setting `_config_files`_ (accessible via `dump_settings`_).
   - Added `strip_elements_with_classes`_ and `strip_classes`_ settings.
 
 * docutils/io.py:
@@ -4140,6 +4139,7 @@ test/test_rst); and all modifications required to make it all work.
 .. References
    ==========
 
+.. _RELEASE-NOTES: RELEASE-NOTES.html
 .. _`_config_files`: docs/user/config.html#config-files
 .. _auto_id_prefix: docs/user/config.html#auto-id-prefix
 .. _detailled:
@@ -4167,6 +4167,7 @@ test/test_rst); and all modifications required to make it all work.
 .. _legacy_column_widths: docs/user/config.html#legacy-column-widths
 .. _literal_block_env: docs/user/config.html#literal-block-env
 .. _math_output: docs/user/config.html#math-output
+.. _output: docs/user/config.html#output
 .. _output_encoding: docs/user/config.html#output-encoding
 .. _raw_enabled: docs/user/config.html#raw-enabled
 .. _reference_label: docs/user/config.html#reference-label
@@ -4186,7 +4187,6 @@ test/test_rst); and all modifications required to make it all work.
 .. _view_mode: docs/user/config.html#view-mode
 
 
-
 ..
    Local Variables:
    mode: indented-text
diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt
index d44228b68..c4b09106d 100644
--- a/docutils/RELEASE-NOTES.txt
+++ b/docutils/RELEASE-NOTES.txt
@@ -20,7 +20,7 @@ For a more detailed list of changes, please see the Docutils `HISTORY`_.
 Future changes
 ==============
 
-Drop support for Python 3.7 and 3.8 in Docutils 0.21.
+Drop support for Python 3.7 and 3.8 in Docutils 0.21.
 
 * Usage:
 
@@ -28,8 +28,8 @@ Drop support for Python 3.7 and 3.8 in Docutils 0.21.
     points`_ (without the ``.py`` extension) instead of installing the
     ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_
 
-    You may use the `generic command line front end tool`_ as a
-    future-proof command, for example:
+    You may use the ``docutils`` `generic command line front end tool`_
+    as a future-proof command, for example:
 
     .. code:: diff
 
@@ -65,7 +65,7 @@ Drop support for Python 3.7 and 3.8 in Docutils 0.21.
 
     __ docs/user/html.html#html
 
-* The command-line usage pattern will change:
+* The _`command-line usage pattern` will change:
 
   .. code:: diff
 
@@ -105,7 +105,7 @@ Drop support for Python 3.7 and 3.8 in Docutils 0.21.
 * "html5" writer:
 
   - Stop setting the "footnote-reference" class value for footnote
-    references in Docutils 0.21.
+    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).
@@ -117,33 +117,34 @@ Drop support for Python 3.7 and 3.8 in Docutils 0.21.
     __ https://www.w3.org/TR/2014/REC-html5-20141028/grouping-content.html
        #the-blockquote-element
 
-  - Remove option ``--embed-images`` (obsoleted by "image_loading_")
-    in Docutils 2.0.
+  - Change the default value for math_output_ to "MathML" in Docutils 0.22.
 
-  - 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.
+    in Docutils 1.0.
 
   - Change default of legacy_column_widths_ setting to False
-    in Docutils 1.0.
+    in Docutils 1.0.
 
   - Remove ``use_verbatim_when_possible`` setting
-    (use literal_block_env_: verbatim) in Docutils 2.0.
+    (use literal_block_env_: verbatim) in Docutils 2.0.
 
-* The default value of the `auto_encode` argument of
-  `core.publish_str()` and `core.publish_programmatically()`
-  will change to ``False`` 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.
+  (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.
+  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.
+* Drop support for `old-format configuration files`_ in Docutils 2.0.
 
 * Remove file ``install.py`` in Docutils 0.21.
   See README.txt__ for alternatives.
@@ -180,6 +181,10 @@ Drop support for Python 3.7 and 3.8 in Docutils 0.21.
 Release 0.20 (unpublished)
 ==========================
 
+.. Note::
+
+   Docutils 0.20 is the last version supporting Python 3.7 and 3.8.
+
 * Output changes:
 
   HTML5:
@@ -190,18 +195,28 @@ Release 0.20 (unpublished)
 
   - Settings in the [latex2e writer] configuration file section
     are now ignored by the "xetex" writer.
-    Move settings intended for both, "xetex" and "latex2e" writers
-    to section `[latex writers]`_.
+    Users can place common settings in section `[latex writers]`_.
 
     .. _[latex writers]: docs/user/config.html#latex-writers
 
-* The new function argument `auto_encode` for `core.publish_string()` and
-  `core.publish_programmatically()` selects whether the output document is
+  - New command line setting output_. Obsoletes the ``<destination>``
+    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.
+  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)
 =========================
@@ -245,7 +260,7 @@ Release 0.18.1 (2021-12-23)
 
 .. Note::
 
-   Docutils 0.18.x is the last version supporting Python 2.7, 3.5, and 3.6.
+   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).
@@ -446,12 +461,8 @@ Release 0.17 (2021-04-03)
 Release 0.16 (2020-01-12)
 =========================
 
-.. 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.
+Docutils 0.16.x supports Python 2.7 and Python >= 3.5 natively,
+without the use of the ``2to3`` tool.
 
 * reStructuredText:
 
@@ -496,13 +507,11 @@ Release 0.16 (2020-01-12)
 Release 0.15 (2019-07-20)
 =========================
 
-.. Note::
+Docutils 0.15.x is compatible with Python versions 2.6, 2.7 and 3.3 to 3.5.
 
-   Docutils 0.14.x is the last version supporting Python 2.4, 2.5,
-   3.1, and 3.2.
+.. Note::
 
-   Docutils 0.15.x is compatible with Python versions 2.6, 2.7 and 3.3 to 3.5
-   (cf. `Python 3 compatibility`_).
+   Docutils 0.15.x is the last version supporting Python 2.6, 3.3 and 3.4.
 
 * reStructuredText:
 
@@ -517,6 +526,11 @@ Release 0.15 (2019-07-20)
 Release 0.14 (2017-08-03)
 =========================
 
+.. Note::
+
+   Docutils 0.14.x is the last version supporting Python 2.4, 2.5,
+   3.1, and 3.2.
+
 * docutils/docs/ref/docutils.dtd:
 
   - Enable validation of Docutils XML documents against the DTD:
@@ -645,12 +659,7 @@ Release 0.11 (2013-07-22)
 Release 0.10 (2012-12-16)
 =========================
 
-.. 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`_).
+Docutils 0.10 is compatible with Python versions from 2.4 to 3.2.
 
 * General:
 
@@ -691,6 +700,10 @@ Release 0.10 (2012-12-16)
 Release 0.9.1 (2012-06-17)
 ==========================
 
+.. Note::
+
+   Docutils 0.9.1 is the last version supporting Python 2.3.
+
 * General:
 
   Several fixes for Python 3 usage.
@@ -862,12 +875,8 @@ General:
 Release 0.6 (2009-10-11)
 ========================
 
-.. 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.
+Docutils 0.6 is compatible with Python versions from 2.3 up to 2.6
+and convertible to 3.1 code.
 
 .. note::
 
@@ -931,6 +940,10 @@ Release 0.6 (2009-10-11)
 Release 0.5 (2008-06-25)
 ========================
 
+.. Note::
+
+   Docutils 0.5 is the last version supporting Python 2.2.
+
 Components:
 
 * HTML writer.
@@ -984,12 +997,10 @@ Release 0.4 (2006-01-09)
 
 .. 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 is the last version supporting Python 2.1.
 
-   Docutils 0.4.x is the last version that will make compromises in
-   its HTML output for Netscape Navigator 4.  Docutils 0.5 will
+   It is also 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).