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. I don't see where you mention what platform / format you were originally targetting. Could you tell us about it?
Um, it's Acorn RISC OS, and if you've actually heard of it, I'd be very impressed :) The format I converted it to is vaguely similar to HTML, but has several advantages in that it's searchable (and the searching is massively fast. It's virtually instantaneous on 2Mb of data, and it has to load it all from my not too fast hard disk), the program that displays it keeps windows nice and small so you can have them at the side of the screen whilst you're programming. The page splitting thing came from the fact that this was the way I could click "F1" on a function in my text editor, and get help on it straight away.
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. ;-)
I did guess that even if this is of no obvious help, it might give the next HTML generation of documentation some good ideas.
Were you aware of the module index in the last release? A single page with a list of modules alphabetically sorted.
Yes, but I find it's annoying to have to wade through things to get to what I want when really I want a front page where I can click on what I want straight away. Perhaps the order of the current manuals front page is more useful for total novices, but after that I think that most people probably find it a pain unless they know their way around it very well. It seems distinctly un-user-friendly, and slow. This is just my opinion, I could be wrong here :)
I have mixed feelings about extensive links, but a lot of that has to do with the aweful presentation of web browsers.
Well, I've kept to a fairly small subset of HTML. There's tables in there (obviously), but that's as difficult as it gets. There's no font size commands or anything else that makes things look good on one browser and awful on another. I only tested it out on Acorn Browse and ANT Fresco (no, you probably haven't heard of either of them), but I'll try Netscape later today. Hopefully, things will look OK.
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!
I think it is easy to get embroiled in platform specific stuff like this. I'm lucky; RISC OS has had a very good antianialised font manager in since 1988, so there's no problems. I kept things simple because I know that as soon as people start marking around with font size and font faces on most OSs, things start breaking down (Windows is horrendous with text that isn't relatively large, for example, because it doesn't antianialise text).
Future releases will improve the semantic content of the markup, making it a little easier to create links automatically.
Hmmm, you should see the regular expression code I've got to do links. It's not very long, perhaps 3 or 4Kb, but already unmaintainable :)
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.
Fair point. What do other people think of this?
Good idea. And I've been wrestling with LaTeX2HTML indexing a lot lately. ;-(
Never run it. I had to look at it before I could guess what {\rm} meant :)
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.
Could you explain this a little more? I'm guessing that at the moment you're updating the LaTeX docs and once you've got those stable you'll convert them all to SGML, and use those as the base documentation? Sounds very sensible to me. LaTeX is not particularly easy to parse, I've found.
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....
It's an unusual system :)
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!)
I'm afraid the code is about 99.8% based on me looking at LaTeX, guessing what the output would look like if I'd invented the language, then going about doing it. I had to look in the LaTeX2HTML source to guess what {\rm} could be, and every so often I referred to the original HTML documentation to check to see if something that I thought was wrong was intentional or not... This is probably not good programming practice :) Everything is a little fragile, because the parser was only ever intended to work with the PLR.
I plan to make available a documentation release in HTML, LaTeX, PDF, and PostScript next week.
Good. How much has been updated since the last release? Laurie _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________