PEP 773: Textual tweaks and clarifications (#4249)

Author: zooba

peps/pep-0773.rst

@@ -31,6 +31,12 @@ having global ``python3.x`` commands by adding an extra entry to their ``PATH``
 environment variable. We recommend starting with the "How to teach this" section
 for the most concise high-level overview of the features.
 
+The existing ``.exe`` installer and ``py`` launcher will be deprecated and no
+longer released from two years after this PEP is accepted. The existing
+embeddable distro will no longer be listed as a download, but will be available
+through the install manager. The Windows Store app will be immediately replaced
+with the install manager.
+
 Reader's Note
 -------------
 
@@ -532,12 +538,8 @@ prefixes, preferring a full match over a prefix, and tags use case-insensitive,
 number-aware matches, with dotted numbers treated as versions. Tags must match
 one of the listed "install for" tags, and entries list multiple such tags to
 handle abbreviated requests. The special tag ``default`` resolves to the user's
-configured default (typically ``3``).
-
-For example, the ``3.10.5`` entry would list all of ``3``, ``3.10`` and
-``3.10.5`` as tags to be installed for. A request for ``3.10`` would match one
-of these and so the entry is selected. Due to the number-aware matches, a
-request for ``03.0010`` would also match, and ``3.10.50`` would not.
+configured default (typically ``3``; see Configuration later for details on
+configuring settings).
 
 Tags may also be specified as a constraint, using ``>``, ``>=``, ``<``, ``<=``
 or ``!=`` followed by the ``Company\\Tag`` or ``Tag`` value. When matching a
@@ -553,12 +555,14 @@ Users are expected to use shorter tags for convenience, rather than ranges.
 
 The default index file is hosted on python.org, and contains install information
 including package URLs and hashes for all installable versions. An alternate
-index may be specified by the user or their administrator (see Configuration
-below). Entries in the index file list the full set of tags they should be
-installed for, and if an exact match is found the package will be selected. In
-the case of no exact match, a prefix match will be used. In both cases, numbers
-in the tag are treated logically - that is, ``3.1`` is a prefix of ``3.1.2`` but
-not of ``3.10``.
+index may be specified by the user using a configuration file or the
+``--source`` command line option, or their administrator through a configuration
+file. The requested tag is matched against the index file, and if an exact match
+is found the package will be selected. In the case of no exact match, a prefix
+match will be used. In both cases, numbers in the tag are treated logically -
+that is, ``3.1`` is a prefix of ``3.1.2`` but not of ``3.10``. See Index Schema
+below for information on exactly how install tags are specified in the index
+file.
 
 If a tag is already satisfied by an existing install, nothing will be installed.
 The user must pass an ``--upgrade`` or ``--force`` option to replace the
@@ -581,10 +585,11 @@ install (or generating aliases or shortcuts). This is intended to cover
 embedding cases, or downloading the files for incompatible platforms. Passing
 multiple tags with ``--target`` is an error.
 
-If the ``--download <DIR>`` option is passed, runtimes will be downloaded to the
-specified directory as their source packages, and an ``index.json`` will be
-created referencing these files. This index can be referenced later to perform
-offline installs with ``python install --source <index.json> [tag ...]``.
+If the ``--download <DIR>`` option is passed, runtime packages are downloaded
+but not installed. They are stored in the specified directory as their source
+packages, and an ``index.json`` is created that references these files. This
+index can be used later to perform offline installs with ``python install
+--source <index.json> [tag ...]``.
 
 
 Uninstall subcommand
@@ -600,14 +605,15 @@ inspect existing installs. Unless the ``--yes`` option is passed, the user will
 be prompted before uninstalling each runtime.
 
 If the ``--purge`` option is passed with no tags, then (after confirmation) all
-runtimes will be removed, along with shortcuts and any cached files.
+runtimes will be removed, along with shortcuts and any cached files. Passing any
+tags with ``--purge`` will produce an error.
 
 Uninstalling PyManager does not uninstall any runtimes that were installed. For
 technical reasons, this would not be reliably possible (we cannot run arbitrary
 code at uninstall time), and so instead we deliberately ensure that anything
 that has been installed will continue to work. Reinstalling PyManager allows
-management of these installs to resume. Running ``py uninstall --purge`` before uninstalling
-PyManager will perform a complete uninstall.
+management of these installs to resume. Running ``py uninstall --purge`` before
+uninstalling PyManager will perform a complete uninstall.
 
 
 List subcommand
@@ -625,7 +631,7 @@ PyManager (including an active virtual environment) may be listed separately.
 
 The default format is user-friendly. Other formats will include machine-readable
 and single string formats (e.g. ``--format=prefix`` simply prints ``sys.prefix``
-on a line by itself). The exact list of formats is left to implementation.
+on a line by itself). The exact list of formats is left to the implementation.
 
 If ``--one`` is provided, only the best result is listed. This is to assist
 shell scripts that want to locate the default (or a suitable) runtime without
@@ -815,7 +821,7 @@ The initial schema is shown below:
                "id": str,
 
                # Name to display in the UI
-               "displayName": str,
+               "display-name": str,
 
                # Version used to sort packages. Also determines prerelease status.
                # Should follow Python's format, but is only compared among releases
@@ -837,6 +843,9 @@ The initial schema is shown below:
 
                # List of tags to install this package for. This does not have to be
                # unique across all installs; the first match will be selected.
+               # For example, the 3.10.5 package may list '3', '3.10' and
+               # '3.10.5' so that any of those may be specified to install it.
+               # Matches are number aware, so that 3.1 is not a prefix of 3.10.
                "install-for": [str],
 
                # List of tags to run this package for. Does not have to be unique
@@ -877,7 +886,7 @@ The initial schema is shown below:
            }
        ],
 
-       # Full or partial URL to the next index file
+       # URL (or relative path) to the next index file
        "next": str,
    }
 
@@ -1309,8 +1318,8 @@ We suggest an explanation like this:
    This will remove all installs and any shortcuts that would otherwise be left
    behind. If you already removed the manager, you can reinstall it and run the
    above uninstall command again to clean up. Individual runtimes can be
-   uninstalled by replacing the ``--purge`` option with the tag, found by looking
-   at ``python list``.
+   uninstalled by specifying the tag instead of ``--purge``. Tags can be found
+   by looking at ``python list``.
 
 
 Configuration