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

[Laurence Tratt]

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
start an HTML version, which I did on Saturday; I think it's now complete.
I say "I think", because I haven't really had time (and certainly not the
inclination) to check all the pages that it generates for 100% correctness;
having said that, I'm fairly confident that the conversion has been, at
worst, largely successful.

If you want to get a download URL and skip lots of boring prose, there's a
URL at the middle of the message :)


Due to the original intention of my project, the pages generated are ever
so slightly different from LaTeX2HTML (this is an understatement). For a
start, I rip everything up into subpages (so if you want to should be able
to do something like "netscape string/index.html" to view a particular
page. The reason I've done this is because I can now press F1 on a function
in my text editor, and get whisked straight away to the appropriate page)
and stick things in directories. There are an awful lot of directories, but
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
for some links!

Secondly, my front page is, intentionally, nothing like the page for the
current Library Reference. It's all in a big table in essentially
alphabetical order; I found that finding things with the old page was
generally quicker if I loaded the page into my text editor, found the
position of what I was looking for and then searched in my web browser...

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)
there'll be a nice HTML link so you can click and go there. This has got to
a big boon for novice users and I'm sure even some of you expert users will
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.

Fourthly, the tutorial is bunged in there as well because I know I still
find it useful for looking up syntax bits when I get confused :) Also, for
novice users they probably don't want that differentiation between tutorial
and library reference because it's a pain having lots of web browser
windows up (especially if you're unlucky enough to be using "window at the
front" Windows), so it seemed like a good idea. It also allows there to be
links from some things in the tutorial to the PLR, another novice boon.

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
index like LaTeX2HTML generates.


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
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
it'll stand up to it.


So, here's the URL to download the Python Library Reference (and tutorial)
in a different HTML form:

  http://yi.com/home/TrattLaurence/comp/python/man.html

WARNINGS:

  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
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
for this :)
  2) The filenames contain potentially "funny" characters (noticeabley "!,
;" and hard spaces), so if your OS doesn't like them, tell me so the next
version of the manual won't have them in. I *think* all the filenames are
OK on Windows machines, so I'm guessing they're probably alright on UNIX.
They don't cause me any problems, but my filing system is a little unusual
  3) I'm not promising any support though if, as I've said, there's enough
interest I would like to develop this to an appropriate level


The conversion is almost 100% automatic (I generated the index file and
needed to tidy up the tutorials index (I'd never intended that such files
should work with my project, so was quite happy when with only minimal
mucking about the tutorial worked) but apart from that, this is a genuine
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
the moment, a couple of things are a bit bonkers because I'm running an
early beta of Python 1.5 to my machine, and one or two things like package
support are not functioning correctly yet. Once I've got a platform
independent version ready (and if there's any interest in the project as a
whole) and got some documentation done, I'll put the source up for
download. If it's of any interest (and as a sort of disclaimer), I don't
know LaTeX so the process is based on purely imperical observations; this
may have been an advantage :)

At the moment the manual is, if I remember correctly, based on the 1.5b2
documentation which should be almost entirely up to date. However, could
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
February last time I looked, but I can't find LaTeX of that date on ftp.
python.org :(

Please don't hesitate to contact me if you find this intersting / useless
or if I've trodden on anyones toes. Please don't distribute the manual
outside of the doc-sig; it's not in my opinion ready yet, and certainly is
not before some Python experts have looked at it. e-mail to: tratt@dcs.kcl.
ac.uk

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


Laurie

** If anyones intersted, it's very easy to make outputters for other
     formats, so if you want the PLR in format xyz, give me a shout. SGML
     should be relatively easy if anyone wants that, though presumably
     somebody else is already on that case

_______________
DOC-SIG  - SIG for the Python Documentation Project

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