Python evolution: Unease

[Paul Rubin]

Skip Montanaro <skip at pobox.com> writes:
> Start writing (or reorganizing).  Folks, this is open source.  I'm
> sure by the traffic on the list most people here know how to write.

Irrelevant, the issue isn't what docs can be written if someone
wants to do it, it's what docs are actually already there.  I mean
every shortcoming anyone could raise about Python or anything else
could have the same answer, "it's open source, go fix it".  The
question is what does the existing stuff do.

> In the case of Tkinter, you should probably get the okay of the
> authors of various external docs before incorporating them into the
> Python docs, 

If such permission is available then the external docs should just
be dropped into the distro.  

> but note that several Tkinter-related documents are referenced
> directly from the Tkinter module docs:

Irrelevant, the Python docs mean the ones that are included, not the
ones that are merely referenced.

> This being the Internet and all, it's not clear that referencing external
> documentation is somehow worse than incorporating it directly into the
> distribution.

The same thing could be said for software.  So why not eliminate the
Python library and let everyone download each module separately?
Because it's bogus is why.  It really does matter whether something is
included or just referenced.  That's what "batteries included" is
supposed to be about--you get ONE package and it's supposed to have
everything you need without having to go forage for additional
components.  It matters because most users shouldn't need to care
about the Python distro at all, since they got Python through its
inclusion in some bigger distro.  E.g., I'm now running the Python
that was included in Fedora Core 3 GNU/Linux, a complete OS distro on
a DVD-ROM, containing about 3 gigabytes not including sources.  And
when a user installs 3 gigabytes of software from a DVD, they can
reasonably expect that they've installed a complete system and
shouldn't need to download anything additional to use all the features
of the programs on the DVD.  Now the Fedora maintainers aren't Python
gurus--people ask for Python so they did the obvious thing: downloaded
it, ran its installer, put the output into their distro, and said "ok,
Fedora has Python".  That's all they should need to do to incorporate
Python into Fedora.  So it's up to the Python maintainers, not the
Fedora maintainers or the user, to make sure that the Python distro
has everything that users need, without further downloading.

And that was just about Tkinter, for which good docs exist but just
don't happen to be in the distro.  How about something like
SocketServer, for which no reasonable docs exist at all?  There's no
way to figure out how to use it without reading the source.  Or the
socket library, whose docs say to go buy a book by W. Richard Stevens.
The book is very good, but having to go buy a proprietary book is the
opposite of what self-contained free software documentation is
supposed to mean.

I'm not trying to bash Python, which is excellent in many ways, or I
wouldn't be using it.  I just see various other free software projects
as trying to live up to higher standards and I think Python should
aspire to the same thing.

> As for stuff that exists in PEPs and release notes, they should
> already all have the necessary copyright (either they were placed in
> the public domain or they are already part of the Python
> distribution) to allow you do just check out a CVS tree, make the
> necessary edits and either check the files back in or submit a patch
> to SourceForge.

And about that full featured Python web browser and native-code Python
compiler, all you have to do is go write it.  Come on.

Having to piece together info from a dozen obscure and inconsistent
PEP's and stuff in the CVS tree and source comments is not what most
people think of as "documentation".  Documentation means I can look in
the manual and the info is right there, properly referenced in the
table of contents and in the proper section for that type of language
feature, unified with the rest of the docs.

> In the documentation arena, I think more thought should probably be
> given to producing online docs that can be directly annotated, thus
> further reducing the barrier to more complete documentation (and
> more updates).  Take a look at latex2html, propose or implement
> changes, or just rewrite the damn thing in Python.  I think
> latex2html is probably a recurring nightmare for Fred Drake.

I've personally been happy with Texinfo for other kinds of docs and
would consider it easier to deal with than latex2html.  It might even
be feasible to edit it in a wiki, so anyone could improve it easily.
Another idea is web-based doc comments like PHP and MySQL have, so the
doc editors can incorporate the info from the comments in subsequent
doc releases.