Documentation update.

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

3 files changed, 150 insertions, 137 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index 48de19fdb..f26450e40 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -28,7 +28,7 @@ Release 0.20 (unpublished)
 
 * docutils/frontend.py
 
-  - New configuration setting output_. Obsoletes the ``<destination>``
+  - New configuration setting "output_". Obsoletes the ``<destination>``
     positional argument (cf. `Future changes` in the RELEASE-NOTES_).
 
 * docutils/languages/
diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt
index 6a5bfc35a..1c076a394 100644
--- a/docutils/RELEASE-NOTES.txt
+++ b/docutils/RELEASE-NOTES.txt
@@ -12,7 +12,7 @@
 :Copyright: This document has been placed in the public domain.
 
 
-This document summarizes the major changes in recent and upcoming releases.
+This document summarizes the major changes in previous and upcoming releases.
 For a more detailed list of changes, please see the Docutils `HISTORY`_.
 
 .. contents::
@@ -22,61 +22,44 @@ Future changes
 
 Drop support for Python 3.7 and 3.8 in Docutils 0.21.
 
-* Usage:
+Command line interface
+----------------------
 
-  - 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. [#]_
+* 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:
+  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/
+  .. code:: diff
 
-  - The `default HTML writer`__  will change in Docutils 2.0:
+     - rst2latex.py --use-latex-abstract FAQ.txt > FAQ.tex
+     + docutils --writer=latex --use-latex-abstract FAQ.txt > FAQ.tex
 
-    The rst2html_ front end and ``get_writer_by_name('html')`` select
-    "html4css1" now and will select "html5" in Docutils 2.0 and later.
+  Exceptions:
+    The auxilliary script ``rst2odt_prepstyles.py`` will become
+    available via ``python -m docutils.writers.odf_odt.prepstyles``.
 
-    * 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.
+    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`).
 
-    __ docs/user/html.html#html
+  .. [#] Some Linux distributions already use the short names.
 
 * The _`command-line usage pattern` will change:
 
   .. code:: diff
 
-       - <toolname> [options] [<source> [<destination>]]
-       + <toolname> [options] source [source2 [source3 [...]]]
+       - 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>``
+  * 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
@@ -84,35 +67,45 @@ Drop support for Python 3.7 and 3.8 in Docutils 0.21.
 
   For the rationale, see https://clig.dev/#arguments-and-flags.
 
-* `Input encoding`_:
+.. _entry points:
+    https://packaging.python.org/en/latest/specifications/entry-points/
 
-  - 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)
+`Input encoding`_
+-----------------
 
-  - 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)
+* 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)
 
-  - Change the default input encoding from ``None`` (auto-detect) to
-    "utf-8" in Docutils 0.22.
+  Raise UnicodeError (instead of falling back to "latin1") if both,
+  default and locale encoding, fail. (Docutils 0.21)
 
-  - Remove the input encoding auto-detection code in Docutils 1.0 or later.
+* 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)
 
-* "csv-table_" directive:
+* Change the default input encoding from ``None`` (auto-detect) to
+  "utf-8" in Docutils 0.22.
 
-  - 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.
+* Remove the input encoding auto-detection code in Docutils 1.0 or later.
 
-  - Move `parsers.rst.directives.Table.process_header_option()` to
-    `parsers.rst.directives.CSVTable` in Docutils 0.21.
+Writers
+-------
 
-  - Remove `parsers.rst.directives.CSVTable.HeaderDialect`
-    in Docutils 0.22.
+* 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:
 
@@ -147,28 +140,49 @@ Drop support for Python 3.7 and 3.8 in Docutils 0.21.
 
 * "null" writer: output will change to the empty string in Docutils 0.22.
 
-* Remove the "rawsource" argument from `nodes.Text.__init__()`
-  (deprecated and ignored since Docutils 0.18) in Docutils 2.0.
+Misc
+----
+
+* "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.
 
 * 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__.
+* Remove the "rawsource" argument from `nodes.Text.__init__()`
+  in Docutils 2.0.
 
-  __ docs/ref/transforms.html
+* 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
+
 .. _front end tools: docs/user/tools.html
 .. _input encoding:
 .. _input_encoding: docs/user/config.html#input-encoding
@@ -187,7 +201,6 @@ Drop support for Python 3.7 and 3.8 in Docutils 0.21.
 .. _buildhtml.py: docs/user/tools.html#buildhtml-py
 .. _csv-table: docs/ref/rst/directives.html#csv-table
 
-
 Release 0.20 (unpublished)
 ==========================
 
diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt
index 99979f242..1e521d1bb 100644
--- a/docutils/docs/user/tools.txt
+++ b/docutils/docs/user/tools.txt
@@ -12,26 +12,12 @@
 
 .. contents::
 
-.. note::
-   Docutils front-end tool names, install details and the set of
-   auto-installed tools will change in Docutils 0.21.
-
-   The command line usage pattern will change over the next releases.
-
-   See `Future changes`__ in the RELEASE-NOTES.
-   
-__ RELEASE-NOTES.html#future-changes
-
-
 --------------
  Introduction
 --------------
 
-Once the Docutils package is unpacked, you will discover a ``tools/``
-directory containing several front ends for common Docutils
-processing.
-In addition to the `generic command line front end`_, Docutils has
-many small front ends, each specialized for a specific "Reader" (which
+In addition to the `generic command line front end`_, Docutils installs
+several small front ends, each specialized for a specific "Reader" (which
 knows how to interpret a file in context), a "Parser" (which
 understands the syntax of the text), and a "Writer" (which knows how
 to generate a specific data format).
@@ -54,6 +40,16 @@ input (stdin) is used for the source.
 
 .. [#] The exceptions are buildhtml.py_ and rst2odt_prepstyles.py_.
 
+.. note::
+   Docutils front-end tool names, install details and the set of
+   auto-installed tools will change in Docutils 0.21.
+
+   The command line usage pattern will change over the next releases.
+
+   See `Future changes`_ in the RELEASE-NOTES.
+
+.. _future changes: ../../RELEASE-NOTES.html#future-changes
+
 
 Getting Help
 ============
@@ -110,47 +106,6 @@ to get the correct list of supported command-line options. Example::
 HTML-Generating Tools
 =====================
 
-buildhtml.py
-------------
-
-:Readers: Standalone, PEP
-:Parser:  reStructuredText
-:Writers: html_, html5_, pep_html_
-:Config_: `[buildhtml application]`_
-
-Use ``buildhtml.py`` to generate ``*.html`` from all the ``*.txt`` files
-(including PEPs) in each <directory> given, and their subdirectories
-too.  (Use the ``--local`` option to skip subdirectories.)
-
-Usage::
-
-    buildhtml.py [options] [<directory> ...]
-
-After unpacking the Docutils package, the following shell commands
-will generate HTML for all included documentation::
-
-    cd docutils/tools
-    buildhtml.py ..
-
-For official releases, the directory may be called "docutils-X.Y",
-where "X.Y" is the release version.  Alternatively::
-
-    cd docutils
-    tools/buildhtml.py --config=tools/docutils.conf
-
-The current directory (and all subdirectories) is chosen by default if
-no directory is named.  Some files may generate system messages
-(docs/user/rst/demo.txt contains intentional errors); use the
-``--quiet`` option to suppress all warnings.  The ``--config`` option
-ensures that the correct settings are in place (a ``docutils.conf``
-`configuration file`_ in the current directory is picked up
-automatically).  Command-line options may be used to override config
-file settings or replace them altogether.
-
-.. _[buildhtml application]: config.html#buildhtml-application
-.. _configuration file: `configuration files`_
-
-
 .. _rst2html:
 
 rst2html.py
@@ -216,11 +171,11 @@ or "`-\-stylesheet-path`_" options.
 To experiment with styles, please see the
 `guide to writing HTML (CSS) stylesheets for Docutils`__.
 
+.. _XHTML 1.0 Transitional: https://www.w3.org/TR/xhtml1/
 .. _html4css1: html.html#html4css1
 .. _link-stylesheet: config.html#embed-stylesheet
 .. _--stylesheet: config.html#stylesheet
 .. _--stylesheet-path: config.html#stylesheet-path
-
 __ ../howto/html-stylesheets.html
 
 
@@ -240,6 +195,8 @@ CSS style sheet. The provided style sheets ``minimal.css`` and ``plain.css``
 define required and optional styling rules respectively.
 
 .. _html5: html.html#html5
+.. _HTML 5: https://www.w3.org/TR/html5/
+
 
 rstpep2html.py
 --------------
@@ -267,7 +224,6 @@ The same result can be achieved with the genric front end::
 The rendering of published PEPs is done by a Sphinx-based build system
 (see :PEP:`676`).
 
-
 .. _pep_html: html.html#pep-html
 
 
@@ -378,10 +334,51 @@ For details, please see `Easy Slide Shows With reStructuredText &
 S5 <slide-shows.html>`_.
 
 
-.. _HTML 5: https://www.w3.org/TR/html5/
-.. _HTML 4.1: https://www.w3.org/TR/html401/
-.. _XHTML 1.0 Transitional: https://www.w3.org/TR/xhtml1/
-.. _XHTML 1.1: https://www.w3.org/TR/xhtml1/
+buildhtml.py
+------------
+
+:Readers: Standalone, PEP
+:Parser:  reStructuredText
+:Writers: html_, html5_, pep_html_
+:Config_: `[buildhtml application]`_
+
+The ``buildhtml.py`` script can be found in the ``/tools`` directory of
+the "docutils" source. It is not included in binary packages. [#]_
+
+Use ``buildhtml.py`` to generate ``*.html`` from all the ``*.txt`` files
+(including PEPs) in each <directory> given, and their subdirectories
+too.  (Use the ``--local`` option to skip subdirectories.)
+
+Usage::
+
+    buildhtml.py [options] [<directory> ...]
+
+After unpacking the Docutils source package, the following shell commands
+will generate HTML for all included documentation::
+
+    cd docutils/tools
+    buildhtml.py ..
+
+For official releases, the directory may be called "docutils-X.Y",
+where "X.Y" is the release version.  Alternatively::
+
+    cd docutils
+    tools/buildhtml.py --config=tools/docutils.conf
+
+The current directory (and all subdirectories) is chosen by default if
+no directory is named.  Some files may generate system messages
+(docs/user/rst/demo.txt contains intentional errors); use the
+``--quiet`` option to suppress all warnings.  The ``--config`` option
+ensures that the correct settings are in place (a ``docutils.conf``
+`configuration file`_ in the current directory is picked up
+automatically).  Command-line options may be used to override config
+file settings or replace them altogether.
+
+.. [#] The Debian package "python3-docutils" includes the script
+   under the name ``rst-builthtml``.
+
+.. _[buildhtml application]: config.html#buildhtml-application
+.. _configuration file: `configuration files`_
 
 
 LaTeX-Generating Tools
@@ -452,8 +449,8 @@ files and produces troff_ sources for Unix man pages.
 .. _troff: https://troff.org/
 
 
-ODF/OpenOffice-Generating Tools
-===============================
+OpenDocument-Generating Tools
+=============================
 
 rst2odt.py
 ----------
@@ -478,13 +475,16 @@ For details, see `Odt Writer for Docutils`_.
 rst2odt_prepstyles.py
 `````````````````````
 
-A helper tool to fix a word-processor-generated STYLE_FILE.odt for
-odtwriter use::
+A helper tool to prepare a word-processor-generated STYLE_FILE.odt for
+use with the "odt" writer: [#]_ ::
 
-  rst2odt_prepstyles STYLE_FILE.odt
+  rst2odt_prepstyles.py STYLE_FILE.odt
 
 See `Odt Writer for Docutils`__ for details.
 
+.. [#] The call pattern will change in Docutils 0.20, see
+       `Future changes`_ in the RELEASE-NOTES.
+
 __ odt.html#page-size