copy editing + more details (python-dev feedback)

pep-0386.txt

@@ -18,7 +18,7 @@ This PEP proposes a new version comparison schema system in Distutils.
 Motivation
 ==========
 
-In Python there are no real restriction yet on how a project should manage its
+In Python there are no real restrictions yet on how a project should manage its
 versions, and how they should be incremented.
 
 Distutils provides a `version` distribution meta-data field but it is freeform and
@@ -47,18 +47,18 @@ versions.
 That is why this PEP proposes, for the sake of interoperability, a standard
 schema to express version information and its comparison semantics.
 
-Furthermore, this will make OS packagers work easier when repackaging standards
+Furthermore, this will make OS packagers' work easier when repackaging standards
-compliant distributions, as of now it can be difficult to decide how two
+compliant distributions, because as of now it can be difficult to decide how two
 distribution versions compare.
 
 
 Requisites and current status
 =============================
 
-It is not in the scope of this PEP to provide a universal versioning schema intended
+It is not in the scope of this PEP to provide a universal versioning schema
-to support many or all existing versioning schemas. There will always be competing
+intended to support all or even most of existing versioning schemas. There
-grammars, either mandated by distro or project policies or by historical
+will always be competing grammars, either mandated by distro or project
-reasons and we cannot expect that to change.
+policies or by historical reasons that we cannot expect to change.
 
 The proposed schema should be able to express the usual versioning semantics,
 so it's possible to parse any alternative versioning schema and transform it
@@ -73,7 +73,7 @@ purity, sometimes.
 Projects have very different versioning needs, but the following are widely
 considered important semantics:
 
-1. there should be possible to express more than one versioning level
+1. it should be possible to express more than one versioning level
    (usually this is expressed as major and minor revision and, sometimes,
    also a micro revision).
 2. most projects need special meaning versions for "pre-releases" (such as
@@ -138,8 +138,8 @@ your project::
     >>> v1 > v2
     False
 
-The problem with this is that while it allows expressing requisite any
+The problem with this is that while it allows expressing any
-nesting level it doesn't allow to express special meaning versions
+nesting level it doesn't allow giving special meaning to versions
 (pre and post-releases as well as development versions), as expressed in
 requisites 2, 3 and 4.
 
@@ -193,14 +193,15 @@ It adds pre-release versions, and some structure, but lacks a few semantic
 elements to make it usable, such as development releases or post-release tags,
 as expressed in requisites 3 and 4.
 
-Also, notice that Distutils version classes are not really used in the community.
+Also, note that Distutils version classes have beed present since years
+but are not really used in the community.
 
 
 Setuptools
 ----------
 
 Setuptools provides another version comparison tool [#setuptools-version]_
-which does not enforce any rule for the version, but try to provide a better
+which does not enforce any rules for the version, but try to provide a better
 algorithm to convert the strings to sortable keys, with a ``parse_version``
 function.
 
@@ -262,7 +263,7 @@ useful versions, which makes it difficult for users to grok the versioning that
 a particular package was using and to provide tools on top of PyPI.
 
 Distutils classes are not really used in Python projects, but the
-Setuptools function is quite spread because it's used by tools like
+Setuptools function is quite widespread because it's used by tools like
 `easy_install` [#ezinstall]_, `pip` [#pip]_ or `zc.buildout` [#zc.buildout]_
 to install dependencies of a given project.
 
@@ -288,7 +289,19 @@ It's currently called `verlib` and a prototype lives at [#prototype]_.
 
 The pseudo-format supported is::
 
-    N.N[.N]+[abc]N[.N]+[.postN+][.devN+]
+    N.N[.N]+[{abc}N[.N]+][.postN][.devN]
+
+The real regular expression is::
+
+    expr = r"""^
+    (?P<version>\d+\.\d+)         # minimum 'N.N'
+    (?P<extraversion>(?:\.\d+)*)  # any number of extra '.N' segments
+    (?:
+        (?P<prerel>[abc])         # 'a'=alpha, 'b'=beta, 'c'=release candidate
+        (?P<prerelversion>\d+(?:\.\d+)*)
+    )?
+    (?P<postdev>(\.post(?P<post>\d+))?(\.dev(?P<dev>\d+))?)?
+    $"""
 
 Some examples probably make it clearer::
 
@@ -310,13 +323,13 @@ Some examples probably make it clearer::
     True
 
 The trailing ``.dev123`` is for pre-releases. The ``.post123`` is for
-post-releases -- which apparently is used by a number of projects out there
+post-releases -- which apparently are used by a number of projects out there
 (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 ambiguous as to whether it indicates a pre- or post-release.
 
 Last, ``.post456.dev34`` indicates a dev marker for a post release, that sorts
-before a ``.post345`` marker. This can be used to do development versions
+before a ``.post456`` marker. This can be used to do development versions
 of post releases.
 
 ``verlib`` provides a ``RationalVersion`` class and a