PEP 426: try to clarify the bundle^H^H^Hmerge/fork meaning of Provides-Dist

pep-0426.txt

@@ -94,7 +94,7 @@ Version
 :::::::
 
 A string containing the distribution's version number.  This
-field  must be in the format specified in PEP 386.
+field should be in the format specified in PEP 386.
 
 Example::
 
@@ -283,12 +283,13 @@ Requires-Dist (multiple use)
 Each entry contains a string naming some other distutils
 project required by this distribution.
 
-The format of a requirement string is identical to that of a
-distutils project name (e.g., as found in the ``Name:`` field.
-optionally followed by a version declaration within parentheses.
+The format of a requirement string is identical to that of a distribution
+name (e.g., as found in the ``Name:`` field) optionally followed by a
+version declaration within parentheses.
 
-The distutils project names should correspond to names as found
-on the `Python Package Index`_.
+The distribution names should correspond to names as found on the `Python
+Package Index`_; often the same as, but distinct from, the module names
+as accessed with ``import x``.
 
 Version declarations must follow the rules described in
 `Version Specifiers`_
@@ -305,7 +306,8 @@ Setup-Requires-Dist (multiple use)
 
 Like Requires-Dist, but names dependencies needed while the
 distributions's distutils / packaging `setup.py` / `setup.cfg` is run.
-Commonly used to generate a manifest from version control.
+Commonly used to bring in extra compiler support or a package needed
+to generate a manifest from version control.
 
 Examples::
 
@@ -318,17 +320,19 @@ for setup and are not guaranteed to be available at run time.
 Provides-Dist (multiple use)
 ::::::::::::::::::::::::::::
 
-Each entry contains a string naming a Distutils project which
-is contained within this distribution.  This field *must* include
-the project identified in the ``Name`` field, followed by the
-version : Name (Version).
+Each entry contains a string naming a requirement that is satisfied by
+installing this distribution.  This field *must* include the project
+identified in the ``Name`` field, optionally followed by the version:
+Name (Version).
 
 A distribution may provide additional names, e.g. to indicate that
-multiple projects have been bundled together.  For instance, source
-distributions of the ``ZODB`` project have historically included
-the ``transaction`` project, which is now available as a separate
-distribution.  Installing such a source distribution satisfies
-requirements for both ``ZODB`` and ``transaction``.
+multiple projects have been merged into and replaced by a single
+distribution or to indicate that this project is a substitute for another.
+For instance distribute (a fork of setuptools) could ``Provides-Dist``
+setuptools to prevent the conflicting package from being downloaded and
+installed when distribute is already installed.  A distribution that has
+been merged with another might ``Provides-Dist`` the obsolete name(s)
+to satisfy any projects that require the obsolete distribution's name.
 
 A distribution may also provide a "virtual" project name, which does
 not correspond to any separately-distributed project:  such a name
@@ -359,10 +363,9 @@ should not be installed at the same time.
 Version declarations can be supplied.  Version numbers must be in the
 format specified in `Version Specifiers`_.
 
-The most common use of this field will be in case a project name
-changes, e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0.
-When you install Torqued Python, the Gorgon distribution should be
-removed.
+The most common use of this field will be in case a project name changes,
+e.g. Gorgon 2.3 gets renamed to Torqued Python 1.0.  When you install
+Torqued Python, the Gorgon distribution should be removed.
 
 Examples::