PEP 639: Format code blocks with appropriate syntax highlighting

Author: CAM-Gerlach

pep-0639.rst

@@ -655,7 +655,9 @@ license files and MUST NOT raise an error.
 .. _639-default-patterns:
 
 If the ``license-files`` key is not present and not explicitly marked as
-``dynamic``, tools MUST assume a default value of the following::
+``dynamic``, tools MUST assume a default value of the following:
+
+.. code-block:: toml
 
     license-files.globs = ["LICEN[CS]E*", "COPYING*", "NOTICE*", "AUTHORS*"]
 
@@ -2005,32 +2007,40 @@ as it did previously, since Setuptools relies on its own automatic
 inclusion of license-related files matching common patterns,
 such as the ``LICENSE`` file it uses.
 
-It includes the following license-related metadata in its ``setup.cfg``::
+It includes the following license-related metadata in its ``setup.cfg``:
+
+.. code-block:: ini
 
     [metadata]
     classifiers =
         License :: OSI Approved :: MIT License
 
-The simplest migration to this PEP would consist of using this instead::
+The simplest migration to this PEP would consist of using this instead:
+
+.. code-block:: ini
 
     [metadata]
     license_expression = MIT
 
-Or, in a :pep:`621` ``pyproject.toml``::
+Or, in a :pep:`621` ``pyproject.toml``:
+
+.. code-block:: toml
 
     [project]
     license-expression = "MIT"
 
-The output core metadata for the distribution packages would then be::
+The output core metadata for the distribution packages would then be:
+
+.. code-block:: email
 
     License-Expression: MIT
     License-File: LICENSE
 
-The ``LICENSE`` file would be stored at ``/setuptools-{version}/LICENSE``
-in the sdist and ``/setuptools-{version}.dist-info/license_files/LICENSE``
+The ``LICENSE`` file would be stored at ``/setuptools-${VERSION}/LICENSE``
+in the sdist and ``/setuptools-${VERSION}.dist-info/license_files/LICENSE``
 in the wheel, and unpacked from there into the site directory (e.g.
 ``site-packages``) on installation; ``/`` is the root of the respective archive
-and ``{version}`` the version of the Setuptools release in the core metadata.
+and ``${VERSION}`` the version of the Setuptools release in the core metadata.
 
 
 .. _639-example-advanced:
@@ -2040,14 +2050,18 @@ Advanced example
 
 Suppose Setuptools were to include the licenses of the third-party projects
 that are vendored in the ``setuptools/_vendor/`` and ``pkg_resources/_vendor``
-directories; specifically::
+directories; specifically:
+
+.. code-block:: text
 
     packaging==21.2
     pyparsing==2.2.1
     ordered-set==3.1.1
     more_itertools==8.8.0
 
-The license expressions for these projects are::
+The license expressions for these projects are:
+
+.. code-block:: text
 
     packaging: Apache-2.0 OR BSD-2-Clause
     pyparsing: MIT
@@ -2056,7 +2070,9 @@ The license expressions for these projects are::
 
 A comprehensive license expression covering both Setuptools
 proper and its vendored dependencies would contain these metadata,
-combining all the license expressions into one. Such an expression might be::
+combining all the license expressions into one. Such an expression might be:
+
+.. code-block:: text
 
     MIT AND (Apache-2.0 OR BSD-2-Clause)
 
@@ -2070,14 +2086,18 @@ of the MIT license and the copyrights used by Setuptools, ``pyparsing``,
 
 Specifically, we assume the license files are located at the following
 paths in the project source tree (relative to the project root and
-``pyproject.toml``)::
+``pyproject.toml``):
+
+.. code-block:: ini
 
     LICENSE
     setuptools/_vendor/packaging/LICENSE
     setuptools/_vendor/packaging/LICENSE.APACHE
     setuptools/_vendor/packaging/LICENSE.BSD
 
-Putting it all together, our ``setup.cfg`` would be::
+Putting it all together, our ``setup.cfg`` would be:
+
+.. code-block:: ini
 
     [metadata]
     license_expression = MIT AND (Apache-2.0 OR BSD-2-Clause)
@@ -2088,7 +2108,9 @@ Putting it all together, our ``setup.cfg`` would be::
         setuptools/_vendor/packaging/LICENSE.BSD
 
 In a :pep:`621` ``pyproject.toml``, with license files specified explicitly
-via the ``paths`` subkey, this would look like::
+via the ``paths`` subkey, this would look like:
+
+.. code-block:: toml
 
     [project]
     license-expression = "MIT AND (Apache-2.0 OR BSD-2-Clause)"
@@ -2099,7 +2121,9 @@ via the ``paths`` subkey, this would look like::
         "setuptools/_vendor/LICENSE.BSD",
     ]
 
-Or alternatively, matched via glob patterns, this could be::
+Or alternatively, matched via glob patterns, this could be:
+
+.. code-block:: toml
 
     [project]
     license-expression = "MIT AND (Apache-2.0 OR BSD-2-Clause)"
@@ -2109,38 +2133,46 @@ Or alternatively, matched via glob patterns, this could be::
     ]
 
 With either approach, the output core metadata in the distribution
-would be::
+would be:
+
+.. code-block:: email
 
     License-Expression: MIT AND (Apache-2.0 OR BSD-2-Clause)
     License-File: LICENSE
     License-File: setuptools/_vendor/packaging/LICENSE
     License-File: setuptools/_vendor/packaging/LICENSE.APACHE
     License-File: setuptools/_vendor/packaging/LICENSE.BSD
 
-In the resulting sdist, with ``/`` as the root of the archive and ``{version}``
+In the resulting sdist, with ``/`` as the root of the archive and ``${VERSION}``
 the version of the Setuptools release specified in the core metadata,
-the license files would be located at the paths::
+the license files would be located at the paths:
+
+.. code-block:: shell
 
-    /setuptools-{version}/LICENSE
-    /setuptools-{version}/setuptools/_vendor/packaging/LICENSE
-    /setuptools-{version}/setuptools/_vendor/packaging/LICENSE.APACHE
-    /setuptools-{version}/setuptools/_vendor/packaging/LICENSE.BSD
+    /setuptools-${VERSION}/LICENSE
+    /setuptools-${VERSION}/setuptools/_vendor/packaging/LICENSE
+    /setuptools-${VERSION}/setuptools/_vendor/packaging/LICENSE.APACHE
+    /setuptools-${VERSION}/setuptools/_vendor/packaging/LICENSE.BSD
 
 In the built wheel, with ``/`` being the root of the archive and
-``{version}`` as the previous, the license files would be stored at::
+``{version}`` as the previous, the license files would be stored at:
 
-    /setuptools-{version}.dist-info/license_files/LICENSE
-    /setuptools-{version}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE
-    /setuptools-{version}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.APACHE
-    /setuptools-{version}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.BSD
+.. code-block:: shell
+
+    /setuptools-${VERSION}.dist-info/license_files/LICENSE
+    /setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE
+    /setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.APACHE
+    /setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.BSD
 
 Finally, in the installed project, with ``site-packages`` being the site dir
-and ``{version}`` as the previous, the license files would be installed to::
+and ``{version}`` as the previous, the license files would be installed to:
+
+.. code-block:: shell
 
-    site-packages/setuptools-{version}.dist-info/license_files/LICENSE
-    site-packages/setuptools-{version}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE
-    site-packages/setuptools-{version}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.APACHE
-    site-packages/setuptools-{version}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.BSD
+    site-packages/setuptools-${VERSION}.dist-info/license_files/LICENSE
+    site-packages/setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE
+    site-packages/setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.APACHE
+    site-packages/setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.BSD
 
 
 .. _639-example-conversion:
@@ -2149,16 +2181,22 @@ Conversion example
 ------------------
 
 Suppose we were to return to our simple Setuptools case.
-Per the specification, given it only has the following license classifier::
+Per the specification, given it only has the following license classifier:
+
+.. code-block:: email
 
     Classifier: License :: OSI Approved :: MIT License
 
 And no value for the ``License`` field, or equivalently, if it had a
-value of::
+value of:
+
+.. code-block:: email
 
     License: MIT
 
-Then the suggested value for the ``License-Expression`` field would be::
+Then the suggested value for the ``License-Expression`` field would be:
+
+.. code-block:: email
 
     License-Expression: MIT
 
@@ -2173,20 +2211,16 @@ situation themselves.
 Expression examples
 -------------------
 
-Some additional examples of valid ``License-Expression`` values::
+Some additional examples of valid ``License-Expression`` values:
 
-    License-Expression: MIT
+.. code-block:: email
 
+    License-Expression: MIT
     License-Expression: BSD-3-Clause
-
     License-Expression: MIT AND (Apache-2.0 OR BSD-2-clause)
-
     License-Expression: MIT OR GPL-2.0-or-later OR (FSFUL AND BSD-2-Clause)
-
     License-Expression: GPL-3.0-only WITH Classpath-Exception-2.0 OR BSD-3-Clause
-
     License-Expression: LicenseRef-Public-Domain OR CC0-1.0 OR Unlicense
-
     License-Expression: LicenseRef-Proprietary
 
 
@@ -2348,7 +2382,9 @@ There are two overlapping core metadata fields to document a license: the
 license ``Classifier`` `strings <classifiers_>`__ prefixed with ``License ::``
 and the ``License`` `field <licensefield_>`__ as free text.
 
-The core metadata ``License`` field documentation is currently::
+The core metadata ``License`` field documentation is currently:
+
+.. code-block:: rst
 
     License
     =======