improve the readability of one section

pep-0396.txt

@@ -102,15 +102,13 @@ Specification
    module version number when included in the standard library, and
    SHOULD include a version number when packaged separately.
 
-#. When a module includes a version number, it SHOULD be available in
+#. When a module (or package) includes a version number, the version
-   the ``__version__`` attribute on that module.
+   SHOULD be available in the ``__version__`` attribute.
 
-#. For modules which are also packages, the module's namespace SHOULD
+#. For modules which live inside a namespace package, the module
-   include the ``__version__`` attribute.
+   SHOULD include the ``__version__`` attribute.  The namespace
-
+   package itself SHOULD NOT include its own ``__version__``
-#. For modules which live inside a namespace package, the sub-package
+   attribute.
-   name SHOULD include the ``__version__`` attribute.  The namespace
-   module itself SHOULD NOT include its own ``__version__`` attribute.
 
 #. The ``__version__`` attribute's value SHOULD be a string.
 
@@ -218,9 +216,20 @@ Distutils2
 
 Because the distutils2 style ``setup.cfg`` is declarative, we can't
 run any code to extract the ``__version__`` attribute, either via
-import or via parsing.  This PEP suggests a special key be added to
+import or via parsing.
-the ``[metadata]`` section of the ``setup.cfg`` file to indicate "get
+
-the version from this file".  Something like this might work::
+In consultation with the distutils-sig [9]_, two options are
+proposed.  Both entail containing the version number in a file, and
+declaring that file in the ``setup.cfg``.  When the entire contents of
+the file contains the version number, the ``version-file`` key will be
+used::
+
+    [metadata]
+    version-file: version.txt
+
+When the version number is contained within a larger file, e.g. of
+Python code, such that the file must be parsed to extract the version,
+the key ``version-from-file`` will be used::
 
     [metadata]
     version-from-file: elle.py
@@ -240,7 +249,7 @@ programmatically.  E.g. in ``elle.py``::
 PEP 376 metadata
 ================
 
-PEP 376 [9]_ defines a standard for static metadata, but doesn't
+PEP 376 [10]_ defines a standard for static metadata, but doesn't
 describe the process by which this metadata gets created.  It is
 highly desirable for the derived version information to be placed into
 the PEP 376 ``.dist-info`` metadata at build-time rather than
@@ -274,7 +283,9 @@ References
 .. [8] pkgutil - Package utilities
    (http://distutils2.notmyidea.org/library/pkgutil.html)
 
-.. [9] PEP 376, Database of Installed Python Distributions
+.. [9] http://mail.python.org/pipermail/distutils-sig/2011-June/017862.html
+
+.. [10] PEP 376, Database of Installed Python Distributions
    (http://www.python.org/dev/peps/pep-0376/)
 
 

pep-0420.txt

@@ -174,7 +174,7 @@ not contain a trailing path separator.
 There is no impact on PEP 302 "loaders".
 
 If an existing finder is not updated to support returning a string
-from ``find_module``, the only impact is that such a loader will be
+from ``find_module``, the only impact is that such a finder will be
 unable to provide portions of a namespace package.
 
 Packaging Implications