Python Documentation (should be better?)

[Terry Hancock]

On Wednesday 11 May 2005 02:54 pm, Christopher J. Bottaro wrote:
> I guess what I'm trying to say is that there is no manual (for the language
> itself, not the modules).  There is just the tutorial that serves as the
> manual.  I think it should evolve into a manual that is more comprehensive
> and organized more like other programming manuals (chapter on control
> structures, functions, classes, inheritance, etc).

That's probably because

1) The language itself is extremely simple.  What you really need is in the
tutorial (or in several books including "Learning Python" from O'Reilly which
I learned from).  If you need more than that, then you must be looking for
something fairly picky (like "magic methods" perhaps), so you really do want
to be reading the "Language Reference".  Don't overthink it.

2) About 90% of what you want to do in Python is done by using a library
module.  Furthermore, it's the 90% you are likely to forget, thus needing
a manual for reference.  That's why I regard the "Library Reference" as
"the manual".  Don't forget that many "built-ins" are documented here as
well (e.g. the methods of strings*).

There are, of course, numerous introductions to Python which can be freely
downloaded, and several commercial books on the subject.  IMHO, the
"manual" is to be the ultimate, most up-to-date, most accurate, and most
detailed source on the language (you go there to check details if something
doesn't work the way your tutorial says it does).  Readability is secondary --- 
use a third party source for the "friendly" version (not that the Language
or Library References are unfriendly --- they're just concise, IMHO).

Also, Python gives you something most languages don't --- the interactive
interpreter allows you to play around with Python constructs and find out
how any picky details work by trying it out. This is clearly the most
guaranteed accurate way to find out the answer to a syntax or semantic
problem, and it's so easy it's hard to justify the wasted time perusing a
manual for such details.  That's why people are frequently recommended
to "ask the interpreter" about such details.  This saves a HUGE amount
of time for me --- I'm surprised that you dislike this approach, it seems
extremely practical to me.

*But you do have to remember that strings are documented under "sequences"
this is probably my biggest complaint about the Library Reference --- something
as important as string methods should have its own heading in the top-level
outline.  But that's a nitpick, of course.

--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks  http://www.anansispaceworks.com