[Python-checkins] gh-95913: Move py.exe to appropriate What's New section & refine text (GH-97718)

[miss-islington]

https://github.com/python/cpython/commit/a685cc0a5e74106a671841caf27b8d729e695053
commit: a685cc0a5e74106a671841caf27b8d729e695053
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-10-04T15:58:59-07:00
summary:

gh-95913: Move py.exe to appropriate What's New section & refine text (GH-97718)


* Move Windows py.exe improvements from Typing section to New Features

* Add ref target label and use literal for py.exe

* Be clearer/explict about what legacy version arg components reprisent

* Apply other minor clarity and textual fixes to py.exe launcher text

* Refine phrasing of legacy sentence of py.exe desc

Co-authored-by: Ezio Melotti <ezio.melotti at gmail.com>

Co-authored-by: Ezio Melotti <ezio.melotti at gmail.com>
(cherry picked from commit 985958187d578cfa311e404588950b29fda95db7)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach at Gerlach.CAM>

files:
M Doc/whatsnew/3.11.rst

diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index fe36f99f5382..f3202f0c6d79 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -207,6 +207,32 @@ See :pep:`678` for more details.
 PEP written by Zac Hatfield-Dodds.)
 
 
+.. _whatsnew311-windows-launcher:
+
+Windows ``py.exe`` launcher improvements
+----------------------------------------
+
+The copy of the :ref:`launcher` included with Python 3.11 has been significantly
+updated. It now supports company/tag syntax as defined in :pep:`514` using the
+``-V:<company>/<tag>`` argument instead of the limited ``-<major>.<minor>``.
+This allows launching distributions other than ``PythonCore``,
+the one hosted on `python.org <https://python.org>`_.
+
+When using ``-V:`` selectors, either company or tag can be omitted, but all
+installs will be searched. For example, ``-V:OtherPython/`` will select the
+"best" tag registered for ``OtherPython``, while ``-V:3.11`` or ``-V:/3.11``
+will select the "best" distribution with tag ``3.11``.
+
+When using the legacy ``-<major>``, ``-<major>.<minor>``,
+``-<major>-<bitness>`` or ``-<major>.<minor>-<bitness>`` arguments,
+all existing behaviour should be preserved from past versions,
+and only releases from ``PythonCore`` will be selected.
+However, the ``-64`` suffix now implies "not 32-bit" (not necessarily x86-64),
+as there are multiple supported 64-bit platforms.
+32-bit runtimes are detected by checking the runtime's tag for a ``-32`` suffix.
+All releases of Python since 3.5 have included this in their 32-bit builds.
+
+
 .. _new-feat-related-type-hints-311:
 .. _whatsnew311-typing-features:
 
@@ -401,28 +427,6 @@ See `this message from the Steering Council <https://mail.python.org/archives/li
 for more information.
 
 
-Windows py.exe launcher improvements
-------------------------------------
-
-The copy of :ref:`launcher` included with Python 3.11 has been significantly
-updated. It now supports company/tag syntax as defined in :pep:`514` using the
-``-V:<company>/<tag>`` argument instead of the limited ``-x.y`` argument. This
-allows launching distributions other than ``PythonCore``, which is the one
-obtained from `python.org <https://python.org>`_.
-
-When using ``-V:`` selectors, either company or tag can be omitted, but all
-installs will be searched. For example, ``-V:OtherPython/`` will select the
-"best" tag registered for ``OtherPython``, while ``-V:3.11`` or ``-V:/3.11``
-will select the "best" distribution with tag ``3.11``.
-
-When using legacy ``-x``, ``-x.y``, ``-x-ZZ`` or ``-x.y-ZZ`` arguments, all
-existing behaviour should be preserved from past versions. Only releases from
-``PythonCore`` will be selected. However, the ``-64`` suffix now implies "not
-32-bit", as there are multiple supported 64-bit platforms. 32-bit runtimes are
-detected by checking its tag for a ``-32`` suffix. All releases of Python
-since 3.5 have included this in their 32-bit builds.
-
-
 Other Language Changes
 ======================