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

[Edward C. Jones]

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, ...
...

Both "lib_index.html" and "lib_contents.html" should be accessible from 
the top Python Documentation page.

Here are two principles I feel would be useful to follow. References are 
to the Python 2.5 documentation at 
"http://docs.python.org/dev/lib/lib.html".

1. Important, commonly used, or confusing modules should be near the 
top. The things I look up the most are os.path, os (files and 
directories), and string attributes. "sys" should also be near the top 
because of "sys.argv", "sys.stderr", and "sys.exit". Etc, etc.

2. Put cross-links everywhere. For example the documentation for built 
in function "file" has a link to "File Objects". There should also be a 
link to "open()" and to sections 13.1.2, 13.1.3, 13.1.4, and chapter 10. 
(What became of the often proposed and long overdue reorganization of "os"?)