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

[Laurence Tratt]

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

Yes, I did think of that just after I'd released it :) The problem 
is, there's no real way to put things in a table (which is good, 
because you want to fit as much stuff on screen as possible), whilst 
making sure it doesn't place unreasonable limitations on the user. 
Would putting it down to 4 or 3 columns be better?
 
> 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?

Hmm... On my browser, H5 is relatively large. This is a problem; this 
sort of things is *so* browser dependent, I'm not too sure what the 
best things to do is. Perhaps H4?

> 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

I'm not too sure if this is possible. There is the fact that you can 
access, say, "Macintosh Specific Services" from the front page; I'll 
see if I can get the code to do a reliable conversion of such an 
index at the weekend but it might not be as easy as it seems.

> 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 =).

Ah, yes, I did think there might be some problems here. Windows '95 
(and presumably NT 4) manages OK here but I guess that's because they 
use that awful DOS name mangling thing with tildas flying around 
everywhere. I'm not averse to using "_" although I think hard spaces 
are a little easier on the eye if your OS supports them. Perhaps two 
different versions, one with hard spaces and one with "_" should be 
included, or would people prefer just a dashed version?

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

This is, I think, one of the few (UserDict and UserLib are basically 
the same page) places where this happens. The only solution is to 
change these links after the conversion process. If it's any 
consolation, I'm not aware of any other mistakes in linking, although 
there are obviously lots of places where there's no linking where one 
might think there ought to be. cf:

    w = re.compile(r"woo")
    m = w.match("woo woo")

re.compile will get matched, but w.match won't. If anyone wants full 
Python parser support, they're quite welcome to write it, I may add 
;)

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

But I can't be sure where they will be stored on the users computer 
:( When I release the source, it should be easy to quickly alter it 
to do this sort of individual-dependent thing if you so wish, but I 
can't see any flexible way to do it. If anyone can, it is a good 
idea.

> 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 =):

Fair enough :) This is a good point, I wasn't happy with the current 
look of the tutorial index, and you have come up with a better way of 
doing things. I'll change it at the weekend.

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

I think they already do, don't they? Or do you mean if you click on a 
link which takes you into the PLR, the link now points to the parent 
of the function? Ah, the catch is that "parent" is not analgous to 
"back" or "previous" in this manual :) Parent is literally the parent 
of the function/data whatever, not necessarily the page you have just 
come from.

Thanks for the help,


Laurie

_______________
DOC-SIG  - SIG for the Python Documentation Project

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