[DOC-SIG] Python Library Reference in new HTML form

[David Ascher]

First impressions are very good.  I have a few quibbles, which are only
intended to help make a good product very good.

1) On my screen, I had to make the netscape window very big to see the
   four columns of the index.html page.  I'm not sure what the right
   solution to that is.

2) It's too bad that when looking at a given function, I have to look at
   the "Parent" link which is in a small font to find out what module it's in.  
   Is the Parent link always the containing module?  Would it be possible
   to make that relationship a bit more salient?

3) Since you seem able to generate a lot of indices, I do think that
   a lot could be done there:

   - a Table of Modules - Alphabetical [sort of like your traditional
     index but without the contents of the module, just the links]

   - a Table of Platform-Specific Modules, Alphabetical by platform, with
     redundancy for 'os':

     - Mac
     - Unix
       * posix
       * os

       - SGI
       - Sun
     - Windows

4) Filename problems: on Windows NT SP3, using gnuwin's tar or WinZip, the 
   directories with spaces in them get written with a \240 as the space
   character. At least some HTML links have spaces in them. In other
   words, I can't get to the "Built-in Exceptions" or "Python
   Tutorial" pages. I suggest using _ as the space-replacing character,
   both on disk and in HTML =).

5) Some slight mistakes in linking:

   UserList/index.html, the first link to UserDict points to the class,
   whereas it should point to the module.

6) Wacky idea, and not for the novice, but still potentially useful: allow
   hyperlinks to the source of the modules.  It might even be a nice way
   to allow semi-novices to learn more about Python.  Something to keep on
   the back burner.
 

7) Typesetting comments:
   - overall, I like the clean look.
   - I don't think the christmas-tree table of contents for the tutorial
     is very readable -- I'd make it look more like Python code =):

Whetting Your Appetite:
    Disclaimer
    Introduction
    Where from Here

Using the Python Interpreter:
    Invoking the Interpreter
    The Interpreter and its Environment

etc.

8) Pages which are within the tutorial should have backlinks to the TOC of
   the tutorial.

Cheers,

--da


_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________