updated with latest feedback + PEP 345 changes

pep-0386.txt

@@ -19,22 +19,29 @@ Distutils.
 Motivation
 ==========
 
-Distutils will soon extend the metadata standard, by including the 
+Distutils will soon extend the metadata standard, by including an
-`install_requires` field from Setuptools [#requires]_ among other changes.
+``install_requires``-like field from Setuptools [#requires]_ among
+other changes. This field will be called ``Requires-Dist``.
 
-These changes are a work in progress in PEP 345 [#pep345]_, but validating
+These changes are located in PEP 345 [#pep345]_.
-the current PEP is mandatory to continue the work.
 
-The `install_requires` field will allow a package to define a dependency on 
+The ``Requires-Dist`` field will allow a package to define a dependency on 
-another package and optionally restrict this dependency to a set of 
+another package and optionally restrict this dependency to a set of
-compatible versions.
+compatible versions, so one may write::
+
+    Requires-Dist: zope.interface (>3.5.0)
+
+This means that the distribution requires ``zope.interface``, as long as its
+version is superior to ``3.5.0``.
 
 That's why Distutils needs to provide a robust standard and reference
-implementation to compare versions numbers.
+version scheme, and an API to provide version comparisons.
 
-This will also provide to the community a convention for their package 
+This PEP describes a new version scheme that will be added in Distutils.
-versioning needs.
 
+Of course developers are  **not** required to conform to this scheme, but
+it is suggested to use it as a standard for interoperability between the
+existing Python distributions installers.
 
 Current status
 ==============
@@ -246,12 +253,11 @@ The new versioning algorithm
 During Pycon, members of the Python, Ubuntu and Fedora community worked on
 a version standard that would be acceptable for everyone.
 
-It's currently called `verlib` and a prototype lives here :
+It's currently called `verlib` and a prototype lives at [#prototype]_.
-http://bitbucket.org/tarek/distutilsversion/src/
 
 The pseudo-format supported is::
 
-    N.N[.N]+[abc]N[.N]+[.postN+][.devN+] 
+    N.N[.N]+[abc]N[.N]+[.postN+][.devN+]
 
 Some examples probably make it clearer::
 
@@ -267,16 +273,19 @@ Some examples probably make it clearer::
     ...  < V('1.0c1')
     ...  < V('1.0.dev456')
     ...  < V('1.0')
-    ...  < V('1.0.post623.dev456')
+    ...  < V('1.0.post456.dev34')
     ...  < V('1.0.post456'))
     True
 
-The trailing ".dev123" is for pre-releases. The ".post123" is for
+The trailing ``.dev123`` is for pre-releases. The ``.post123`` is for
 post-releases -- which apparently is used by a number of projects out there
-(e.g. Twisted [#twisted]_). For example *after* a "1.2.0" release there might
+(e.g. Twisted [#twisted]_). For example *after* a ``1.2.0`` release there might
-be a "1.2.0-r678" release. We used "post" instead of "r" because the "r" is
+be a ``1.2.0-r678`` release. We used ``post`` instead of ``r`` because the 
-ambiguous as to whether it indicates a pre- or post-release.
+``r`` is ambiguous as to whether it indicates a pre- or post-release.
-Last ".post623.dev456" is a development version of a post-release.
+
+Last, ``.post456.dev34`` indicates a dev parker for a post release, that sorts
+before a ``.post345`` marker. This can be used to do development versions
+of post releases.
 
 ``verlib`` provides a ``RationalVersion`` class and a
 ``suggest_rational_version`` function.
@@ -310,7 +319,6 @@ Each part is a tuple and there are three parts:
 
 - the main version part
 - the pre-release part
-- the `postdev` marker part
 
 Examples ::
 
@@ -326,10 +334,22 @@ Examples ::
     >>> str(version)
     '1.0c4.dev34'
 
+
 suggest_rational_version
 ------------------------
 
-XXX explain here suggest_rational_version
+``suggest_rational_version`` is a function that suggests a rational version
+close to the given version string. If you have a version string that isn't
+rational (i.e. ``RationalVersion`` doesn't like it) then you might be able
+to get an equivalent (or close) rational version from this function.
+
+This does a number of simple normalizations to the given string, based
+on observation of versions currently in use on PyPI. Given a dump of those 
+version during PyCon 2009, 4287 of them:
+
+- 2312 (53.93%) match RationalVersion without change with the automatic 
+  suggestion
+- 3474 (81.04%) match when using this suggestion method
 
 
 References
@@ -365,8 +385,11 @@ References
 .. [#pep345]
    http://svn.python.org/projects/peps/branches/jim-update-345/pep-0345.txt
 
-Aknowledgments
+.. [#prototype]
-==============
+   http://bitbucket.org/tarek/distutilsversion/
+
+Acknowledgments
+===============
 
 Trent Mick, Matthias Klose, Phillip Eby, and many people at Pycon and 
 Distutils-SIG.