[Distutils] Setuptools documentation

[Phillip J. Eby]

At 06:33 PM 7/9/2008 +0200, Florian Mayer wrote:
>Hello!
>I have read the setuptools documentation and have tried out the
>parse_version comparison, and it turns out that the documentation says
>is just wrong. I am using version 0.6c8 of setuptools.
>
>The documentation says, quoting:
>"Don't use - or any other character than . as a separator, unless you
>really want a post-release. Remember that 2.1-rc2 means you've already
>released 2.1, whereas 2.1rc2 and 2.1.c2 are candidates you're putting
>out before 2.1".
>It also shows a little example for that:
> >>> parse_version('2.1-rc2') < parse_version('2.1')
>False
>
>While this sounds pretty weird(how can a rc be after the release?) but
>also logical if you just consider any character but "." to be
>post-release, which you can do, but do not have to.
>Still if they say this is the rule it is okay, although I would not
>quite agree with that, as many people use underscores or dashes as a
>separation.
>
>So what the real problem is, is that the documentation says things that
>are untrue with at least the latest version. As said before I have
>setuptools 0.6c8 and the behaviour is not like the documentation says in
>any way. Here is a little example:
> >>> parse_version("2.1-rc2") < parse_version("2.1")
>True
>
>Notice the difference? It's exactly the *opposite* of what the
>documentation says. I really ask you to correct this issue as it might
>confuse new users.

The code is apparently correct here; the choice of example in the 
text is bad.  Patches welcome.