Mailman 3 March 1998 - Doc-SIG

Re: [DOC-SIG] Python Library Reference in new HTML form
by Laurence Tratt March 18, 1998

March 18, 1998

> 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(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 1

Python Library Reference in new HTML form
by tratt＠dcs.kcl.ac.uk March 17, 1998

March 17, 1998

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(a)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(a)python.org administrivia to: doc-sig-request(a)python.org _______________

4 3

XML SIG created
by Andrew Kuchling March 16, 1998

March 16, 1998

An XML-SIG has been created for discussing XML and Python, and for developing a set of Python tools for processing XML documents. See below for the mission statement. To join the discussion, you can use the Mailman Web interface at <http://www.python.org/mailman/listinfo/xml-sig>. Alternatively, you can send an email with the word "subscribe" in either the subject line or the body of the message, to xml-sig-request(a)python.org . This SIG was inspired by recent XML discussions on the Doc-SIG and String-SIG; coincidentally, a few people have posted XML-related messages to the newsgroup. There seems to be a lot of community interest in this topic, and development will probably be fast; prototype implementations of the Document Object Model (DOM) and Simple API for XML (SAX) have appeared with startling speed. ================= XML-SIG: A Special Interest Group for XML Processing in Python This list has been created to provide a forum for discussion and implementation of tools to make Python an excellent choice for XML processing. XML is the 'Extensible Markup Language', a data format for structured document interchange. It seems to have considerable momentum behind it, and will probably become very important over the next few years. Consult http://www.w3.org/XML/ for more information. With appropriate software packages, documentation, and a bit of publicity, Python could become the premier language for XML processing. The goal of this SIG is to decide what software is required for this purpose, and coordinate its implementation and documentation. Concrete goals of the first mandate should include: * The glue code required to use existing C/Java XML parsers from CPython/JPython, and the appropriate documentation. * An XML-HOWTO which provides an overview of Python and XML processing. * Implementations of the DOM (Document Object Model) and SAX (Simple API for XML) * As work progresses, the SIG community may realize that other deliverables are required, and add them to the SIG's goals. Wrap-up date: September 1998. This date may be extended if the SIG community decides that more work is required. A.M. Kuchling http://starship.skyport.net/crew/amk/ Whatever you do, stamp out abuses, and love those who love you. -- Voltaire _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0

More saxlib
by Lars Marius Garshol March 15, 1998

March 15, 1998

I've now updated saxlib with - a driver for David Scheres parser - a demo SAX application for parser benchmarking - saxdemo.py can now output canonical XML as well, which is nice for comparing parser output with James Clarks XP for testing. - some other minor changes The web page has also been updated with some links to the different packages that have been announced and a page with benchmark results. The URL is still <URL:http://www.stud.ifi.uio.no/~larsga/download/python/xml/> BTW: I've looked at the xmltok package and from the Python demo it looks nice and simple. However, to be able to make and test a driver I'll have to find out how to load C modules into Python and to be frank I haven't a clue as to how I to do that. So since there is so much else to do I'm putting the SAX driver on hold. If someone else can pick it up, that would be nice. If not I'll get round to it myself eventually. And as I'll have to start using the C module eventually: pointers to clues on how to do it would be appreciated. :) -- "These are, as I began, cumbersome ways / to kill a man. Simpler, direct, and much more neat / is to see that he is living somewhere in the middle / of the twentieth century, and leave him there." -- Edwin Brock http://www.stud.ifi.uio.no/~larsga/ http://birk105.studby.uio.no/ _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 1

xmlproc
by Lars Marius Garshol March 14, 1998

March 14, 1998

I've now put out an early version of xmlproc. There are a couple of obscure bugs and the well-formedness checking that requires parsing the internal DTD subset is not implemented yet. Other than that it is complete and I'm pretty pleased with it so far. Hopefully I'll have full well-formedness checking tomorrow and most of the validation on Monday. (I have the code for all this, but it needs redesigning.) Also: since no-one seems to have any complaints about the SAX interface, perhaps we should start building tools on top of it? Stephane, can you change your DOM package to build on SAX instead of Dan Connolly's parser? That would give the SAX interface a real test and would also mean that your package could be used with all Python parsers. (I've had a glance at your source, but will need to look more closely before I can comment on it.) And should we announce it on the xml-dev list so that the Java people there know about it? I feel a bit uneasy about this, since so far only Jack Jansen has commented on the interface and if it is to be of any use everyone needs to support it. -- "These are, as I began, cumbersome ways / to kill a man. Simpler, direct, and much more neat / is to see that he is living somewhere in the middle / of the twentieth century, and leave him there." -- Edwin Brock http://www.stud.ifi.uio.no/~larsga/ http://birk105.studby.uio.no/ _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0

Re: [DOC-SIG] What does this mean for Python?
by Fredrik Lundh March 14, 1998

March 14, 1998

>1) SAX driver for xmllib >2) xmlproc uses SAX natively instead of using a driver, although it > will probably need to add some things beyond SAX later > >That gives us well-formedness-checking and a simple standardized >event-based API. > >Building on that I'd planned on making: > >1) A simple ESIS outputter, for demo/testing purposes. >2) A grove builder, eventually with DOM support, although there are > things I dislike about DOM. >3) A validator. > >I also wanted to be able to have groves, validation or both. > What say ye, good people? Ouch, my head hurts. Does anyone have a good reference (website, book, whatever) to recommend that covers all important aspects of XML and stuff like groves, validations, and all the related acronyms? Cheers /F _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

5 8

Re: [DOC-SIG] Re: What does this mean for Python?
by Jack Jansen March 13, 1998

March 13, 1998

> Okay, I'll put my fingers where my mouth is: I'm creating a Python interface > to xmltok. Expect (untested) code later today. I've put the module (plus the XMLTok sources it needs, plus a very tiny test program) in ftp://ftp.cwi.nl/pub/jack/pyxmltop.tar.gz . So far the only test I've done is to parse the Hamlet document, which it does in 2 seconds on my O2. I think I've exported all the XMLTok functionality we need, let me know if this isn't so. If someone else is willing to put a SAX wrapper around this: be my guest. I don't really have more time to spend on this at the moment (but I thought that creating this module will at least allow me to be vocal in further discussions:-). -- Jack Jansen | ++++ stop the execution of Mumia Abu-Jamal ++++ Jack.Jansen(a)cwi.nl | ++++ if you agree copy these lines to your sig ++++ http://www.cwi.nl/~jack | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 1

Re: [DOC-SIG] Re: What does this mean for Python?
by Jack Jansen March 13, 1998

March 13, 1998

> I'm still waiting for reactions to my SAX proposal. What do you people > out there think? Does it look usable? Should we make it the standard > Python API or should we scrap it? Or should we modify it? Should we > change the method names to be more Python-like? And can it be used with > JPython to interoperate with things like Don Parks SAXDOM? All > comments/thoughts on this would be very welcome. It looks good to me... -- Jack Jansen | ++++ stop the execution of Mumia Abu-Jamal ++++ Jack.Jansen(a)cwi.nl | ++++ if you agree copy these lines to your sig ++++ http://www.cwi.nl/~jack | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0

Re: [DOC-SIG] Re: What does this mean for Python?
by Jack Jansen March 13, 1998

March 13, 1998

Okay, I'll put my fingers where my mouth is: I'm creating a Python interface to xmltok. Expect (untested) code later today. -- Jack Jansen | ++++ stop the execution of Mumia Abu-Jamal ++++ Jack.Jansen(a)cwi.nl | ++++ if you agree copy these lines to your sig ++++ http://www.cwi.nl/~jack | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0

Re: [DOC-SIG] Re: What does this mean for Python?
by Jack Jansen March 13, 1998

March 13, 1998

> Time to run hamlet.xml through validation and grove building via SAX: > > Parser 1st 2nd 3rd Avg > xmllib.py 50.1 48.4 49.8 49.4 > xmlproc.py 40.8 39.4 39.5 39.9 > xp.java 1.49 1.43 1.43 1.45 > dxpcl.java 14 - - 14 Lars, could you make your timing scripts available? Just for fun I ran hamlet.xml through James Clark's xmltok (or, actually, through the xmlwf program that comes with it), and it clocks at 0.07 seconds on my SGI O2 (180 Mhz R5000). Since the API appears pretty pythonizeable this appears to be a nice groundwork to start getting better performance for python/xml... -- Jack Jansen | ++++ stop the execution of Mumia Abu-Jamal ++++ Jack.Jansen(a)cwi.nl | ++++ if you agree copy these lines to your sig ++++ http://www.cwi.nl/~jack | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0