The pseudo-format supported is::
Some examples probably make it clearer::
-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
-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 ".post456dev623" is a development version of a post-release.
+The trailing ``.post123`` or ``.dev123`` is to allow post- or
+pre-releases. In the pre-release case one usually "counts up" to the
+release, an example of this is the Python project itself. E.g. after a
+``2.6`` release the development snapshot of the next release would be
+In the post-release schema, used for example by Twisted [#twisted]_,
+you count away from a release. So after a ``2.6`` release the
+development snapshot of the next release would be ``2.6.post123``.
+Lastly it is possible to have a development snapshot for a
+post-release. This is a special case mostly provided to allow
+meaningful transitions from some edge cases in Setuptools versioning.
+XXX Check the actual requirement for this.
``verlib`` provides a ``RationalVersion`` class and a