Documentation update.

* Small clarification in the rST spec.

* Move detailled description of alternative ways to install for
  development from the "Docutils policies" to the "repository"
  documentation.

  We don't need to go into details in the "policies" document
  and "edible installs" are also useful for casual contributors
  or power-users.

* Update links and optional dependencies in the README,
  use terminology from PEP 621.
  Move the sandbox snapshot download doc to the sandbox README.

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

5 files changed, 191 insertions, 155 deletions

diff --git a/docutils/README.txt b/docutils/README.txt
index 5945c9832..422e8f2b3 100644
--- a/docutils/README.txt
+++ b/docutils/README.txt
@@ -16,18 +16,15 @@ Quick-Start
 
 This is for those who want to get up & running quickly.
 
-1. Docutils requires Python, available from
+1. Docutils requires **Python**, available from
    http://www.python.org/.
-
-   See Requirements_ below for details.
+   See Dependencies_ below for details.
 
 2. Install the latest stable release from PyPi with pip_::
 
-       python -m pip install docutils
+       python3 -m pip install docutils
 
-   To install a pre-relase, append the option ``--pre``.
-   To install a `development version`_, follow the instructions in
-   section `Installation`_ below.
+   For alternatives and details, see section `Installation`_ below.
 
 3. Use the `front-end scripts`_ to convert reStructuredText documents.
    Try for example::
@@ -37,8 +34,6 @@ This is for those who want to get up & running quickly.
 
    See Usage_ below for details.
 
-.. _pip: https://pypi.org/project/pip/
-
 
 Purpose
 =======
@@ -70,24 +65,21 @@ Support for the following sources is planned:
    http://www.python.org/peps/pep-0012.html
 
 
-Requirements
+Dependencies
 ============
 
 To run the code, Python_ must be installed.
+(Python is pre-installed with most Linux distributions.)
 
 * Docutils 0.19 requires Python 3.7 or later.
 * Docutils 0.16 to 0.18 require Python 2.7 or 3.5+.
 * Docutils 0.14 dropped Python 2.4, 2.5, 3.1 and 3.2 support.
-* Docutils 0.10 dropped Python 2.3 support.
-* From version 0.6, Docutils is compatible with Python 3. [#2to3]_
-* For Docutils 0.5, Python 2.2.1+ is required.
-* Up to Docutils 0.4, Python 2.1 is required.
 
-.. [#2to3] Up to version 0.15, the Docutils codebase was translated
-   "on-demand" using the 2to3 tool.
+.. _Python: http://www.python.org/.
+
 
-Recommendations
----------------
+Optional Dependencies
+---------------------
 
 Docutils uses the following packages for enhanced functionality, if they
 are installed:
@@ -100,15 +92,17 @@ are installed:
 * The `Pygments`_ package provides syntax highlight of "code" directives
   and roles.
 
-* The `recommonmark`_ parser is used to parse input in Markdown format.
+* The `myst`_ or `recommonmark`_ parsers can be used to parse input in
+  Markdown format.
 
 The `Docutils Link List <docs/user/links.html>`__ records projects that
 users of Docutils and reStructuredText may find useful.
 
-.. _Python: http://www.python.org/.
+.. _pip: https://pypi.org/project/pip/
+.. _setuptools: https://pypi.org/project/setuptools/
 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
 .. _Pygments: https://pypi.org/project/Pygments/
-.. _setuptools: https://pypi.org/project/setuptools/
+.. _myst: https://pypi.org/project/myst-docutils/
 .. _recommonmark: https://github.com/rtfd/recommonmark
 
 
@@ -116,53 +110,59 @@ Development version
 ===================
 
 While we are trying to follow a "release early & often" policy,
-features are added frequently.  Since the code in the repository_
-is usually in a bug-free state, we recommend using a current snapshot
-or a working copy.
+features are added frequently.
+Since the code in the `Docutils version repository`_ is usually in a
+bug-free state, we recommend using a current snapshot or a working copy.
 
-To get a _`snapshot`, go to the code page and click the download snapshot
-button:
-
-* Docutils code, documentation, front-end tools, and tests:
+Snapshots:
+  To get a repository _`snapshot`, go to
   https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
+  and click the download snapshot button.
 
-* Sandbox (experimental, contributed code):
-  https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/
-
-To keep up to date on the latest developments, download fresh copies of the
-snapshots regularly or use a `working copy of the Docutils code repository`__.
+Repository check-out:
+  To keep up to date on the latest developments,
+  use a `working copy`__ of the `Docutils version repository`_.
 
 Continue with the `Installation`_ instructions below.
 
-.. _repository: docs/dev/repository.html
+.. _Docutils version repository: docs/dev/repository.html
+.. _sandbox: https://docutils.sourceforge.io/sandbox/README.html
+
 __ docs/dev/repository.html#checking-out-the-repository
 
+
 Installation
 ============
 
-Steps to install Docutils from source:
+* The simplest way is to install the latest stable release from PyPi with
+  pip_::
 
-* Go to the directory containing the file ``setup.py``.
+    python3 -m pip install docutils
 
-  A snapshot_ must be unpacked in a temporary directory (**not** directly in
-  Python's ``site-packages``) first.
+  To install a pre-relase, append the option ``--pre``.
 
-* Run ``setup.py install``. [#setup-requires-setuptools]_
-  On Windows systems it may be sufficient to double-click ``install.py``.
+* For a *manual install* see the options in
+  `Setting up for Docutils development`__.
 
-.. [#setup-requires-setuptools] ``setup.py`` requires the `setuptools`_
-   package. For a manual install see the options in `Setting up for Docutils
-   development`__.
+  __ docs/dev/policies.html#setting-up-for-docutils-development
 
-   __ docs/dev/policies.html#setting-up-for-docutils-development
+* To install a `development version`_ from source with `setuptools`_:
 
-Optional steps:
+  * Go to the directory containing the file ``setup.py``.
 
-* `running the test suite`_
+    A snapshot_ must be unpacked in a temporary directory
+    (**not** directly in Python's ``site-packages``) first.
+
+  * Run ``setup.py install``.
+    On Windows systems it may be sufficient to double-click ``install.py``.
+
+  OS-specific installation instructions follow below.
+
+Optional steps:
 
-* `converting the documentation`_
+* `Running the test suite`_
 
-OS-specific installation instructions follow.
+* `Converting the documentation`_
 
 
 GNU/Linux, BSDs, Unix, Mac OS X, etc.
@@ -179,7 +179,7 @@ GNU/Linux, BSDs, Unix, Mac OS X, etc.
 
        su
        (enter admin password)
-       python setup.py install
+       python3 setup.py install
 
    If the python executable isn't on your path, you'll have to specify
    the complete path, such as ``/usr/local/bin/python``.
@@ -191,7 +191,7 @@ GNU/Linux, BSDs, Unix, Mac OS X, etc.
 
    To install for different Python versions, repeat step 3 for every
    required version. The last installed version will be used in the
-   `shebang line`_ of the ``rst2*.py`` wrapper scripts.
+   `shebang line`_ of the `front-end scripts`_.
 
    .. _shebang line: http://en.wikipedia.org/wiki/Shebang_%28Unix%29
 
diff --git a/docutils/docs/dev/policies.txt b/docutils/docs/dev/policies.txt
index 46362158f..2d2309749 100644
--- a/docutils/docs/dev/policies.txt
+++ b/docutils/docs/dev/policies.txt
@@ -225,7 +225,7 @@ developers to decide which mechanism to use for each case.
 
 Feature additions and API changes will be done in **feature
 branches**.  Feature branches will not be managed in any way.
-Frequent small checkins are encouraged here.  Feature branches must be
+Frequent small check-ins are encouraged here.  Feature branches must be
 discussed on the `docutils-develop mailing list`_ and reviewed before
 being merged into the core.
 
@@ -494,7 +494,7 @@ Docutils' backwards compatibility policy follows the rules for Python in
 
 * The scope of the public API is laid out at the start of the `backwards
   compatibility rules`_.
-  
+
 * The rules for `making incompatible changes`_ apply.
 
 A majority of projects depends on Docutils indirectly, via the Sphinx_
@@ -553,86 +553,15 @@ snapshot" button in the head of the code listing table).
 Setting Up For Docutils Development
 ===================================
 
-When making changes to the code, testing is a must.  The code should
+When making changes to the code, testing_ is a must.  The code should
 be run to verify that it produces the expected results, and the entire
 test suite should be run too.  The modified Docutils code has to be
-accessible to Python for the tests to have any meaning.  There are several
-ways to keep the Docutils code accessible during development:
-
-1. Update your ``PYTHONPATH`` environment variable so that Python
-   picks up your local working copy of the code.
-
-   We'll assume that the `Docutils trunk`__ is checked out under your
-   ``~/projects/`` directory.
-
-   For the bash shell, add this to your ``~/.profile``::
-
-       PYTHONPATH=$HOME/projects/docutils/docutils
-       export PYTHONPATH
-
-   The first line points to the directory containing the ``docutils``
-   package.  The second line exports this environment variable.
-
-   You many also want to add the ``tools`` directory to your binary ``PATH``::
-
-       PATH=$PATH:$HOME/projects/docutils/docutils/tools
-       export PATH
-
-   __ repository.html
-
-2. Create a symlink to the docutils package directory somewhere in the
-   module search path (``sys.path``), e.g., ::
-
-     ln -s ~/projects/docutils/docutils \
-          /usr/local/lib/python2.7/site-packages/
-
-   Alternatively, use a `path configuration file`__.
-
-   __ https://docs.python.org/library/site.html
-
-   You may also want to copy or link the front-end tools in
-   ``docutils/tools`` to a suitable place in your binary PATH, e.g., ::
-
-     ln -s ~/projects/docutils/docutils/tools/rst2html.py \
-           /usr/local/bin/rst2html
-
-3. Do an `editable install`__ with pip.
-
-   __ https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs
-
-4. Install in `development mode`__ with setuptools.
-
-   __ https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode
-
-5. Before you run anything, every time you make a change, reinstall
-   Docutils::
-
-       python setup.py install
-
-   .. CAUTION::
-
-      This method is **not** recommended for day-to-day development;
-      it's too easy to forget.  Confusion inevitably ensues.
-
-      If you install Docutils this way, Python will always pick up the
-      last-installed copy of the code.  If you ever forget to
-      reinstall the "docutils" package, Python won't see your latest
-      changes.
-
-A useful addition to the ``docutils`` top-level directory in branches
-and alternate copies of the code is a ``set-PATHS`` file
-containing the following lines::
-
-    # source this file
-    export PYTHONPATH=$PWD:$PWD
-    export PATH=$PWD/tools:$PATH
-
-Open a shell for this branch, ``cd`` to the ``docutils`` top-level
-directory, and "source" this file.  For example, using the bash
-shell::
+accessible to Python for the tests to have any meaning.
+See `editable installs`_ for ways to keep the Docutils code
+accessible during development.
 
-    $ cd some-branch/docutils
-    $ . set-PATHS
+.. _testing: tested_
+.. _editable installs: repository.html#editable-installs
 
 
 Mailing Lists
diff --git a/docutils/docs/dev/repository.txt b/docutils/docs/dev/repository.txt
index 2e3ca921e..be278938e 100644
--- a/docutils/docs/dev/repository.txt
+++ b/docutils/docs/dev/repository.txt
@@ -98,7 +98,7 @@ Developer access (read and write) is possible with `git svn`_.
 .. _git svn: https://git.wiki.kernel.org/index.php/Git-svn
 
 Subversion_ users can use the following commands
-(substitute your preferred repository root for ROOT):  
+(substitute your preferred repository root for ROOT):
 
 * To check out only the current main source tree of Docutils, type ::
 
@@ -130,6 +130,106 @@ If you changed your mind and want to use a different repository root,
     svn switch --relocate OLDROOT NEWROOT
 
 
+Editable installs
+=================
+
+The `Docutils project policies`_ require that any modifications must be
+tested_ before check-in_.
+There are several ways to ensure that edits to the Docutils code are
+picked up by Python.
+
+We'll assume that the Docutils "trunk" is checked out under the
+``~/projects/`` directory.
+
+1. Do an `editable install`__ with pip_::
+
+     python3 -m pip install -e ~/projects/docutils/docutils
+
+   __ https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs
+
+2. Install in `development mode`__ with setuptools_.
+
+   __ https://setuptools.pypa.io/en/latest/userguide/development_mode.html
+      #development-mode
+
+3. Install "manually".
+
+   To ensure the "docutils" package is in ``sys.path``, do one of the
+   following:
+
+   * Set the ``PYTHONPATH`` environment variable so that Python
+     picks up your local working copy of the code.
+
+     For the bash shell, add this to your ``~/.profile``::
+
+         PYTHONPATH=$HOME/projects/docutils/docutils
+         export PYTHONPATH
+
+     The first line points to the directory containing the ``docutils``
+     package.  The second line exports this environment variable.
+
+   * Create a symlink to the docutils package directory somewhere in the
+     module search path (``sys.path``), e.g., ::
+
+         ln -s ~/projects/docutils/docutils \
+               /usr/local/lib/python3.9/dist-packages/
+
+   * Use a `path configuration file`__.
+
+     __ https://docs.python.org/library/site.html
+
+   Optionally, add some or all `front-end tools`_ from ``docutils/tools``
+   to the binary search path, e.g.,
+
+   * add the ``tools`` directory to the ``PATH`` variable::
+
+         PATH=$PATH:$HOME/projects/docutils/docutils/tools
+         export PATH
+
+   * copy or link idividual front-end tools
+     to a suitable place in your binary path::
+
+         ln -s ~/projects/docutils/docutils/tools/docutils-cli.py \
+               /usr/local/bin/docutils
+
+5. Before you run anything, every time you make a change, reinstall
+   Docutils::
+
+       python3 setup.py install
+
+   .. CAUTION::
+
+      This method is **not** recommended for day-to-day development;
+      it's too easy to forget.  Confusion inevitably ensues.
+
+      If you install Docutils this way, Python will always pick up the
+      last-installed copy of the code.  If you ever forget to
+      reinstall the "docutils" package, Python won't see your latest
+      changes.
+
+A useful addition to the ``docutils`` top-level directory in branches
+and alternate copies of the code is a ``set-PATHS`` file
+containing the following lines::
+
+    # source this file
+    export PYTHONPATH=$PWD:$PWD
+    export PATH=$PWD/tools:$PATH
+
+Open a shell for this branch, ``cd`` to the ``docutils`` top-level
+directory, and "source" this file.  For example, using the bash
+shell::
+
+    $ cd some-branch/docutils
+    $ . set-PATHS
+
+.. _Docutils Project Policies: policies.html
+.. _check-in: policies.html#check-ins
+.. _tested: policies.html#tested
+.. _pip: https://pypi.org/project/pip/
+.. _setuptools: https://pypi.org/project/setuptools/
+.. _front-end tools: ../user/tools.html
+
+
 .. _developer access:
 
 Information for Developers
diff --git a/docutils/docs/ref/rst/restructuredtext.txt b/docutils/docs/ref/rst/restructuredtext.txt
index 276f4f0ec..83aa3894b 100644
--- a/docutils/docs/ref/rst/restructuredtext.txt
+++ b/docutils/docs/ref/rst/restructuredtext.txt
@@ -2762,9 +2762,10 @@ backquotes in an end-string context (according to the recognition
 rules above).  No markup interpretation (including backslash-escape
 interpretation) is done within inline literals.
 
-Line breaks are *not* preserved in inline literals.  Although a
-reStructuredText parser will preserve runs of spaces in its output,
-the final representation of the processed document is dependent on the
+Line breaks and sequences of whitespace characters
+are *not* protected in inline literals.
+Although a reStructuredText parser will preserve them in its output,
+the final representation of the processed document depends on the
 output formatter, thus the preservation of whitespace cannot be
 guaranteed.  If the preservation of line breaks and/or other
 whitespace is important, `literal blocks`_ should be used.
diff --git a/sandbox/README.txt b/sandbox/README.txt
index 94257a0ce..645de177c 100644
--- a/sandbox/README.txt
+++ b/sandbox/README.txt
@@ -4,9 +4,13 @@
  README: The Sandbox
 =====================
 
-The Sandbox_ is a place to play around, to try out and share ideas. The
-`sandbox/`_ directory is a part of the Subversion repository but it isn't
-distributed as part of Docutils_ releases.
+The Sandbox_ is a place to play around, to try out and share ideas.
+The `sandbox/`_ directory is a part of the `Docutils Subversion repository`_
+but it isn't distributed as part of Docutils_ releases.
+To get a snapshot of the sandbox/ directory, go to
+https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/
+and click the "Download Snapshot" button.
+
 
 It's OK to make a mess in the Sandbox! But please, play nice.
 
@@ -25,10 +29,12 @@ documentation applies as well.
 .. _sandbox:
 .. _sandbox/: ./
 
-.. _Docutils: http://docutils.sourceforge.net/
+.. _Docutils: https://docutils.sourceforge.io/
+.. _Docutils Subversion repository:
+   https://docutils.sourceforge.io/docs/dev/repository.html
 .. _Docutils Project Policies:
-   http://docutils.sourceforge.net/docs/dev/policies.html#the-sandbox
-.. _Docutils Web Site: http://docutils.sourceforge.net/docs/dev/website.html
+   https://docutils.sourceforge.io/docs/dev/policies.html#the-sandbox
+.. _Docutils Web Site: https://docutils.sourceforge.io/docs/dev/website.html
 
 
 Sandbox Projects
@@ -38,7 +44,7 @@ See the `sandbox/`_ directory for a complete list.
 
 Some Sandbox projects, are also sorted into the `Docutils Link List`_.
 
-.. _Docutils Link List: http://docutils.sf.net/docs/user/links.html
+.. _Docutils Link List: https://docutils.sourceforge.io/docs/user/links.html
 
 .. TODO: update the list of important sandbox projects (here or in the link
    list?)
@@ -49,54 +55,54 @@ Some Sandbox projects, are also sorted into the `Docutils Link List`_.
 
   Projects that are now implemented in Docutils
   ---------------------------------------------
-  
+
   * `<code-block-directive>`_ contains documentation, reasoning and
     experimental code for support of syntax highlight in Docutils.
     Preparational work for the `code`_ directive available since version 0.9.
-  
+
   * `LaTeX math for reST`_ by Jens J. Mortensen writes Math to
     LaTeX or MathML. This is the base of math_ support since version 0.8.
-  
+
   .. _code: docutils/docs/ref/rst/directives.txt#code
   .. _math: docutils/docs/ref/rst/directives.txt#math
   .. _LaTeX math for reST:
-     http://docutils.sourceforge.net/sandbox/jensj/latex_math/
-  
+     http://docutils.sf.net/sandbox/jensj/latex_math/
+
   Documenting Python
   ------------------
-  
+
   Since Python 2.6, the markup used for the official `Python documentation`_
   is `reStructuredText`_, amended by custom directives. The Sphinx_ toolset is
   used to generate the HTML and LaTeX versions.
-  
+
   The sandbox contains some of the pervious work done on enabling Docutils to
   write the `"Documenting Python"`__ using rST.
-  
+
   __ http://docs.python.org/doc/doc.html
-  
+
   * `Edward Loper's sandbox
     <http://docutils.sf.net/sandbox/edloper/docpy/>`__.  The example
     "asyncore.rst" file was originally adapted by Steve Holden and Bill
     Sconce.
-  
+
   * `Dave Kuhlman's sandbox
     <http://docutils.sf.net/sandbox/dkuhlman/>`__ and `his homepage
     <http://www.rexx.com/~dkuhlman/rstpythonlatex_intro.html>`__.
-  
+
   * `docpy-writer <http://docutils.sf.net/sandbox/docpy-writer/>`__ was
     used for ctypes documentation.
-  
+
   .. _Python documentation: http://docs.python.org/
   .. _reStructuredText: http://docutils.sf.net/rst.html
   .. _Sphinx: http://sphinx.pocoo.org/
-  
+
   Project Infrastructure
   ----------------------
-  
+
   `docutils-update <infrastructure/docutils-update>`_ is a script that
   was installed as a cron job on BerliOS.de to automatically update the
   Docutils `web site`_ whenever the SVN files change.  Any .html
   document with a corresponding .txt file is regenerated whenever the
   .txt file changes.
-  
+
   .. _web site: http://docutils.sf.net/docs/dev/website.html