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

[Fred L. Drake]

Laurence Tratt writes:
 > I've (hopefully) just about completed a project for my platform to conver
 > the Python Library Reference and Tutorial to a format specific to the
 > platform. However I realised I'd left the code openended enough for me to

Laurence,
  I don't see where you mention what platform / format you were
originally targetting.  Could you tell us about it?

 > Due to the original intention of my project, the pages generated are ever
 > so slightly different from LaTeX2HTML (this is an understatement). For a

  I will definately be taking a look at your version, but I'm a little 
swamped right now.  I'll stash a copy aside and take sneak peeks.  ;-)

 > it does mean you can put the mouse over a link and not get a horrendous
 > "node198374836495763452" type number, which I've found especially useful

  The next release of the Python documentation that I'm coordinating
will be "bookmarkable" and avoid most of that nastiness.

 > Secondly, my front page is, intentionally, nothing like the page for the
 > current Library Reference. It's all in a big table in essentially

  Were you aware of the module index in the last release?  A single
page with a list of modules alphabetically sorted.

 > Thirdly, there are a quite lot of inter-manual links; if one page refers to
 > another then generally (working out foolproof rules is not trivial)

  I have mixed feelings about extensive links, but a lot of that has
to do with the aweful presentation of web browsers.  CSS can help, but 
there does't appear to be a common understanding among the browsers as 
to what "getting it right" means.  Oh, the font problems on
Netscape/UNIX drive me bonkers!
  Future releases will improve the semantic content of the markup,
making it a little easier to create links automatically.

 > find it useful. It also tries very hard to get web and e-mail links working
 > properly, so you can click on them as per normal.

  The version I'll be releasing shortly makes URLs "hot", but leaves
email addresses alone (though they are marked and could easily be
turned into hyperlinks).  I do this to avoid swamping people with
mail.

 > Lastly there are two indices included; one is a traditional "book" (ish)
 > index, and the other is a coders "method/data" type index. Both of them
 > have their uses to my way of thinking, so they're both included. They're
 > also split up into alphabetically named files, so it's not one monolithic

  Good idea.  And I've been wrestling with LaTeX2HTML indexing a lot
lately.  ;-(

 > At the moment, I'm not convinced that there is actually any use for this
 > product. I believe somebody is working on SGML versions of the PLR so

  I guess my name is "somebody", then.  ;-) I've been working on them
a bit, but I've been spending a fair amount of time lately on Q/A for
the LaTeX documents.  My expectation is that I'll be able to generate
more usable SGML from them.  The intention of the SGML conversion
project is to move toward SGML for the official documentation sources.
There's still a lot to do, though, mostly due to my schedule
constraints.

 > presumably there'll be *another* HTML version of the manuals coming along
 > sometime soon**; it's in a rather different format to what people are used
 > to, and computer people (and I speak from experience here) are often
 > reluctant to change to something different...; I wouldn't be entirely sure
 > the conversion process has been 100% accurate so there may be some goofs in
 > there. However, I like it quite a lot over the original and find it aids
 > productivity, so I'm releasing a sort of test version to the doc-sig to see
 > if there's actually any use for this. If there isn't, I'll wrap it up and
 > it won't budge off my machine; if people do think it's useful, and perhaps
 > it'll be some time before another lot of HTML documentation will come
 > along, then I will consider releasing it to a wider community if I think

 >   1) There's a .tar.gz file to download, it contains lots (nearly 2300
 > files if I'm being honest) files with 150ish directories at the top level

  That is a lot of files....

 > which contain the HTML, so you probably want to decompress this in a
 > directory on its own. If you're wondering, you do get meaningful filenames

  See my note above; the next version I release will have usable file
names that should survive across releases.

 > build from "this morning"), very slow but entirely in Python. I will
 > release the source in the near future (hopefully within a month), but at

  I look forward to this.  I hope you had the good sense to ignore
partparse.py from the current distribution!  ;-)  (The LaTeX scanning
isn't really that bad, but the code is unmaintainable!)

 > anyone point me to a downloadable directory with the very latest PLR (and
 > tutorial?) in LaTeX format? The HTML on www.python.org had a date of

  I plan to make available a documentation release in HTML, LaTeX,
PDF, and PostScript next week.

 > Hope this is of use to someone and sorry for this huge message,

  Thanks for the efforts!  And please don't apologize for reporting on 
your work!  That's what this SIG is for!


  -Fred

--
Fred L. Drake, Jr.
fdrake@cnri.reston.va.us
Corporation for National Research Initiatives
1895 Preston White Drive    Reston, VA  20191

_______________
DOC-SIG  - SIG for the Python Documentation Project

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