gh-101467: Correct py.exe handling of prefix matches and cases when only one runtime is installed (GH-101468)

(cherry picked from commit eda60916bc88f8af736790ffd52381e8bb83ae83)

Co-authored-by: Steve Dower <steve.dower@python.org>

1 files changed, 30 insertions, 5 deletions

diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst
index 092ce47..50c220d 100644
--- a/Doc/using/windows.rst
+++ b/Doc/using/windows.rst
@@ -730,22 +730,47 @@ command::
 
   py -2
 
-You should find the latest version of Python 3.x starts.
-
 If you see the following error, you do not have the launcher installed::
 
   'py' is not recognized as an internal or external command,
   operable program or batch file.
 
-Per-user installations of Python do not add the launcher to :envvar:`PATH`
-unless the option was selected on installation.
-
 The command::
 
   py --list
 
 displays the currently installed version(s) of Python.
 
+The ``-x.y`` argument is the short form of the ``-V:Company/Tag`` argument,
+which allows selecting a specific Python runtime, including those that may have
+come from somewhere other than python.org. Any runtime registered by following
+:pep:`514` will be discoverable. The ``--list`` command lists all available
+runtimes using the ``-V:`` format.
+
+When using the ``-V:`` argument, specifying the Company will limit selection to
+runtimes from that provider, while specifying only the Tag will select from all
+providers. Note that omitting the slash implies a tag::
+
+  # Select any '3.*' tagged runtime
+  py -V:3
+
+  # Select any 'PythonCore' released runtime
+  py -V:PythonCore/
+
+  # Select PythonCore's latest Python 3 runtime
+  py -V:PythonCore/3
+
+The short form of the argument (``-3``) only ever selects from core Python
+releases, and not other distributions. However, the longer form (``-V:3``) will
+select from any.
+
+The Company is matched on the full string, case-insenitive. The Tag is matched
+oneither the full string, or a prefix, provided the next character is a dot or a
+hyphen. This allows ``-V:3.1`` to match ``3.1-32``, but not ``3.10``. Tags are
+sorted using numerical ordering (``3.10`` is newer than ``3.1``), but are
+compared using text (``-V:3.01`` does not match ``3.1``).
+
+
 Virtual environments
 ^^^^^^^^^^^^^^^^^^^^