fixup! Add the licensing examples and user scenarios

Author: befeleme

source/guides/licensing-examples-and-user-scenarios.rst

@@ -28,9 +28,9 @@ does not use the ``License`` field in its own project source metadata.
 Further, it no longer explicitly specifies ``license_file``/``license_files``
 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.
+such as the :file:`LICENSE` file it uses.
 
-It includes the following license-related metadata in its ``setup.cfg``:
+It includes the following license-related metadata in its :file:`setup.cfg`:
 
 .. code-block:: ini
 
@@ -45,7 +45,7 @@ The simplest migration to PEP 639 would consist of using this instead:
     [metadata]
     license_expression = MIT
 
-Or, in the ``[project]`` table of ``pyproject.toml``:
+Or, in the ``[project]`` table of :file:`pyproject.toml`:
 
 .. code-block:: toml
 
@@ -59,11 +59,11 @@ The output Core Metadata for the distribution packages would then be:
     License-Expression: MIT
     License-File: LICENSE
 
-The ``LICENSE`` file would be stored at ``/setuptools-${VERSION}/LICENSE``
-in the sdist and ``/setuptools-${VERSION}.dist-info/licenses/LICENSE``
+The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/LICENSE`
+in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/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.
+:file:`site-packages`) on installation; :file:`/` is the root of the respective archive
+and ``{VERSION}`` the version of the Setuptools release in the Core Metadata.
 
 
 .. _licensing-example-advanced:
@@ -72,7 +72,7 @@ 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``
+that are vendored in the :file:`setuptools/_vendor/` and :file:`pkg_resources/_vendor/`
 directories; specifically:
 
 .. code-block:: text
@@ -100,16 +100,16 @@ combining all the license expressions into one. Such an expression might be:
     MIT AND (Apache-2.0 OR BSD-2-Clause)
 
 In addition, per the requirements of the licenses, the relevant license files
-must be included in the package. Suppose the ``LICENSE`` file contains the text
+must be included in the package. Suppose the :file:`LICENSE` file contains the text
 of the MIT license and the copyrights used by Setuptools, ``pyparsing``,
-``more_itertools`` and ``ordered-set``; and the ``LICENSE*`` files in the
-``setuptools/_vendor/packaging/`` directory contain the Apache 2.0 and
+``more_itertools`` and ``ordered-set``; and the :file:`LICENSE*` files in the
+:file:`setuptools/_vendor/packaging/` directory contain the Apache 2.0 and
 2-clause BSD license text, and the Packaging copyright statement and
 `license choice notice <packaginglicense_>`__.
 
 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``):
+:file:`pyproject.toml`):
 
 .. code-block:: ini
 
@@ -118,7 +118,7 @@ paths in the project source tree (relative to the project root and
     setuptools/_vendor/packaging/LICENSE.APACHE
     setuptools/_vendor/packaging/LICENSE.BSD
 
-Putting it all together, our ``setup.cfg`` would be:
+Putting it all together, our :file:`setup.cfg` would be:
 
 .. code-block:: ini
 
@@ -130,7 +130,7 @@ Putting it all together, our ``setup.cfg`` would be:
         setuptools/_vendor/packaging/LICENSE.APACHE
         setuptools/_vendor/packaging/LICENSE.BSD
 
-In the ``[project]`` table of ``pyproject.toml``, license files
+In the ``[project]`` table of :file:`pyproject.toml`, license files
 can be specified via glob patterns:
 
 .. code-block:: toml
@@ -167,36 +167,36 @@ would be:
     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 :file:`/` 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:
 
 .. 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:
+In the built wheel, with :file:`/` being the root of the archive and
+``{VERSION}`` as the previous, the license files would be stored at:
 
 .. code-block:: shell
 
-    /setuptools-${VERSION}.dist-info/licenses/LICENSE
-    /setuptools-${VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE
-    /setuptools-${VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.APACHE
-    /setuptools-${VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.BSD
+    /setuptools-{VERSION}.dist-info/licenses/LICENSE
+    /setuptools-{VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE
+    /setuptools-{VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.APACHE
+    /setuptools-{VERSION}.dist-info/licenses/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:
+Finally, in the installed project, with :file:`site-packages` being the site dir
+and ``{VERSION}`` as the previous, the license files would be installed to:
 
 .. code-block:: shell
 
-    site-packages/setuptools-${VERSION}.dist-info/licenses/LICENSE
-    site-packages/setuptools-${VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE
-    site-packages/setuptools-${VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.APACHE
-    site-packages/setuptools-${VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.BSD
+    site-packages/setuptools-{VERSION}.dist-info/licenses/LICENSE
+    site-packages/setuptools-{VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE
+    site-packages/setuptools-{VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.APACHE
+    site-packages/setuptools-{VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.BSD
 
 
 Expression examples
@@ -238,7 +238,7 @@ a formal license, so you wouldn't necessarily have to do anything extra here.
 
 However, it is still a good idea to include ``LicenseRef-Proprietary``
 as a license expression in your package configuration, and/or a
-copyright statement and any legal notices in a ``LICENSE.txt`` file
+copyright statement and any legal notices in a :file:`LICENSE.txt` file
 in the root of your project directory, which will be automatically
 included by packaging tools.
 
@@ -254,20 +254,20 @@ widely used and allows anyone to do whatever they want with your work
 (other than sue you, which you probably also don't want).
 
 To apply it, just paste `the text <chooseamitlicense_>`__ into a file named
-``LICENSE.txt`` at the root of your repo, and add the year and your name to
+:file:`LICENSE.txt` at the root of your repo, and add the year and your name to
 the copyright line. Then, just add ``license = "MIT"`` under
-``[project]`` in your ``pyproject.toml`` if your packaging tool supports it,
+``[project]`` in your :file:`pyproject.toml` if your packaging tool supports it,
 or in its config file/section. You're done!
 
 
 I want to distribute my project under a specific license
 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
-To use a particular license, simply paste its text into a ``LICENSE.txt``
+To use a particular license, simply paste its text into a :file:`LICENSE.txt`
 file at the root of your repo, if you don't have it in a file starting with
-``LICENSE`` or ``COPYING`` already, and add
+:file:`LICENSE` or :file:`COPYING` already, and add
 ``license = "LICENSE-ID"`` under ``[project]`` in your
-``pyproject.toml`` if your packaging tool supports it, or else in its
+:file:`pyproject.toml` if your packaging tool supports it, or else in its
 config file. You can find the ``LICENSE-ID``
 and copyable license text on sites like
 `ChooseALicense <choosealicenselist_>`__ or `SPDX <spdxlist_>`__.
@@ -284,7 +284,7 @@ should only need to make a couple of tweaks to take advantage of the new
 functionality.
 
 In your project config file, enter your license expression under
-``license`` (``[project]`` table in ``pyproject.toml``),
+``license`` (``[project]`` table in :file:`pyproject.toml`),
 or the equivalent for your packaging tool,
 and make sure to remove any legacy ``license`` table subkeys or
 ``License ::`` classifiers. Your existing ``license`` value may already
@@ -293,7 +293,7 @@ otherwise, check the `SPDX license list <spdxlist_>`__ for the identifier
 that matches the license used in your project.
 
 Make sure to list your license files under ``license-files``
-under ``[project]`` in ``pyproject.toml``
+under ``[project]`` in :file:`pyproject.toml`
 or else in your tool's configuration file.
 
 See the :ref:`licensing-example-basic` for a simple but complete real-world demo
@@ -320,23 +320,23 @@ parenthesis (``()``) for grouping to form expressions that cover even the most
 complex situations.
 
 In your project config file, enter your license expression under
-``license`` (``[project]`` table of ``pyproject.toml``),
+``license`` (``[project]`` table of :file:`pyproject.toml`),
 or the equivalent for your packaging tool,
 and make sure to remove any legacy ``license`` table subkeys
 or ``License ::`` classifiers.
 
 Also, make sure you add the full license text of all the licenses as files
 somewhere in your project repository. List the
 relative path or glob patterns to each of them under ``license-files``
-under ``[project]`` in ``pyproject.toml``
+under ``[project]`` in :file:`pyproject.toml`
 (if your tool supports it), or else in your tool's configuration file.
 
 As an example, if your project was licensed MIT but incorporated
 a vendored dependency (say, ``packaging``) that was licensed under
 either Apache 2.0 or the 2-clause BSD, your license expression would
 be ``MIT AND (Apache-2.0 OR BSD-2-Clause)``. You might have a
-``LICENSE.txt`` in your repo root, and a ``LICENSE-APACHE.txt`` and
-``LICENSE-BSD.txt`` in the ``_vendor`` subdirectory, so to include
+:file:`LICENSE.txt` in your repo root, and a :file:`LICENSE-APACHE.txt` and
+:file:`LICENSE-BSD.txt` in the ``_vendor`` subdirectory, so to include
 all of them, you'd specify ``["LICENSE.txt", "_vendor/packaging/LICENSE*"]``
 as glob patterns, or
 ``["LICENSE.txt", "_vendor/LICENSE-APACHE.txt", "_vendor/LICENSE-BSD.txt"]``