[Python-Dev] Python Library Reference top page too long

[Russell E. Owen]

In article <4419A633.6010607 at comcast.net>,
 "Edward C. Jones" <edcjones at comcast.net> wrote:

> The contents page for the Python Library Reference 
> ("http://docs.python.org/dev/lib/lib.html") has become much too long. I 
> suggest that it should be designed like the top page for portal web 
> sites. For example see "http://www.dmoz.org/". I suggest that "lib.html" 
> be replaced by "lib_index.html" and "lib_contents.html". The latter is 
> the current "lib.html". "lib_index.html" should look something like:
> 
> Front Matter
> Full Contents
> 1. Introduction
> 2. Built-in Objects
>      functions, types, exceptions, constants
> 3. File and Directory Access
>      open, file objects, os, os.path, ...
> 4. Generic Operating System Services
>      os, time, optparse, ...
> 5. Python Runtime Services
>      sys, __main__, __future__, ...
> 6. String Services
>      type str, string, re, ...
> 7. Numeric and Mathematical Modules
>      math, random, decimal, ...

I agree it needs work and your suggestion sounds promising.

With the manual as it stands, I find it *very* difficult to find what I 
want. Here are two typical queries I find painful:

1) Look up a string method.
- I usually think "OK, a string is a sequence type, so jump there".
- Jump to that link and you get a page that is completely irrelevant 
*except* that at the *bottom* (if one gets down that far) is a nice list 
of subtopics, one of which is the "right" link.

The real problem here is that if one jumps too deeply on the first go, 
the page doesn't list sub-topics and related topics at the beginning. 
Instead maybe there's a "subtopics" section at the end, but that's a 
lousy place for it.

(Thus if I was less clever and just jumped to "Built-in Classes" I'd get 
a nicely detailed TOC that has exactly the link I want.)

2) Look up the special methods for a sequence object (the __xxx___ 
methods that make one's own class look like a sequence). I've found them 
before but every time I want them it's another @#$%@#$-laden wade 
through the manual (I just tried to find them again--no luck). Thank god 
for Python Essential Reference, dated as it is.

Fundamentally I think what's wanted is:
- Another level of sub-TOCs, e.g. one for "Sequence Types", "Mapping 
Types", etc. Every page that has sub-topics or intimately related should 
have a list of them at the beginning.
- The special methods for a given type of class would make a really good 
"intimately related" topic for "Sequence Types" and "Mapping Types".

Another thing that would be *really* useful is to list the actual 
built-in types with the category. For example:
Sequence Types (str, unicode, list, tuple, buffer, xrange)
Mapping Types (dict)

-- Russell