[Doc-SIG] Comments on the DPS texts: __version__

[Garth T Kidd]

Lots of good stuff, which I'll respond to later, but one thing jumped
out at me:

>      * __author__
>      * __version__
>      * __history__ (this is less common)
>      * __copyright__ (I've just made this one up)

I like __copyright__ a lot. I'm sick of using pydoc.help in the
interpreter and having to page through screens of licenses to be able to
find out what a module does. Putting it in a separate attribute makes a
LOT of sense.

I'd also like to see the use of $Revision$ in __version__ deprecated. It
just bugs me, for some reason. In particular, I think __version__ in a
module's __init__.py should be reserved for the explicitly defined
version of the *module* (and thus directly useful for programmatic "if
__version__>blah then I can assume certain functionality" tests), not
for the revision of __init__.py itself. People who love CVSisms and
RCSisms in their code should instead use::

	__id__ = "$Id$"

We could encourage this usage by providing as part of dps a mechanism
which automatically parses __id__ and breaks it out::

	$Id: setup.py,v 1.1.1.1 2001/07/21 22:14:04 goodger Exp $

might become (with a little validation from ppdi.dtd):

	<rcsid>
	  <filename>setup.py</filename>
	  <revision>1.1.1.1</revision>
	  <date>2001/07/21</date>
	  <time>22:14:04</time>
	  <userid>goodger</userid>
	  <whatisthis>Exp</whatisthis>
	</rcsid>

Better yet, we could patch the Python inspection mechanism to provide
the break-out for us. :)

Regards,
Garth.