Doc-SIG

Download

doc-sig@python.org

February 1996

3 participants
2 discussions

Re: [PYTHON DOC-SIG] hello?
by Guido van Rossum Feb. 9, 1996

Feb. 9, 1996

> OK, I'm cc'ing this to Guido, since I'm fairly sure he'll have a better > idea than anyone else as to where the documentation is heading... Mmm... At the moment it's not heading anywhere... It's rather stationary in fact. I've made occasional changes at people's requests but it's still very close to the 1.3 release. > > > 2. If I produce a diff on the LaTeX source for various bits of the Lib > > > doc (for example), who should I give it to so it'll be used? Me. > > I suspect it would be better to spend the time working on an update of > > the documents for release 1.4. I wouldn't mind receiving updates that better document the status quo in 1.3 (e.g. the htmllib fiasco - when I rewrote the module, I forgot to update the docs, and still haven't). Proper latex docs for Tkinter would also be greatly appreciated. > > Perhaps you should send a note directly to Guido and ask him how he > > would like to make use of your offer. A simple approach to submitting > > changes would be to mail Guido the diffs of the Latex files. Just to > > be sure you aren't adding things he's in the process of editing, it > > might be a good idea if the most current version latex files are made > > available to you via ftp. File locking would have to be done by > > sending an email when you start editing a file. I'd say, if you have small changes, just do them and send me the diffs. If you are more ambitious changes, send me a note about your plans. E.g. if you were to write a chapter on Tkinter.py, I'd send you the latest source to work from. > Anyway, I'm going to try to update my docs to 1.3 and then I'll start > producing diffs to that level. I figure that as long as I keep to some > sort of standard format we should be able to convert to whatever doc > format we decide upon... At the moment, latex is the mother of all docs. > > > 3. What's happening wrt. a standard document format? The > > > intro refers to Linuxdoc and a suggestion by Bill Janseen. Where > > > can I obtain information on the latter? > > There has been no discussion to date. My recollection is that the > > Linuxdoc software is an SGML DTD that can be used to generate HTML, > > texinfo, and Latex. Bill Janseen's suggestion is for a tool that does > > something similar that they use at Xerox. I haven't seen either tool > > so I have no opinions at this time. Do you have a comment or suggestion? > > Perhaps Bill can help out on this one. Get the ILU source dist; it contains "tim", the tools that Janssen uses. I've only had a cursory look at it -- as far as I remember it's a perl script that preprocesses a texinfo-like language into texinfo proper (the difference is that the input has a richer set of macros). I'm not too fond of the way texinfo is rendered by tex (latex looks much better -- though it's stull dead ugly, especially with the original tex fonts) but texinfo is pretty easy to process into other formats -- in fact the tim tools may contain a tool that converts to html already. The current latex-to-html conversion tools are very painful to use. > This is probably of interest to the python community as a > whole, and I'd like to run it up the flagpole now &c. How about a > (fairly simple) database that contains info on what people are > working on currently. Not in any great detail, but a general > overview - like I'd say that I'm working on the library doc > (actively), the GD module (inactively), the web project here (very > actively), my PVL module (inactively) and so on. People would be > able to tie into other people's projects simply by selecting the > same project name. > I'm thinking of a very simple form-based interface. You supply your > email address as a minimum, and possibly some meta-data (web address &c) > that could be associated with you as well. > Hmm. I think I might throw something together anyway... my biggest > problem is that I don't have access to a machine outside our firewall > that'll have Python on it. Oh well. If you throw something together that works, we might run it on the www.python.org machine so everyone can use it. I have to admit that I'm somewhat skeptical about such tools, but I wouldn't mind trying the experiment (and I love to be proven wrong -- it's rare enough that I can take it :-). My expectation is that it's hard to get people to submit their plans and that a human scanning comp.lang.python and the sig mailing lists would be able to produce a much higher quality list of ongoing projects -- but we don't seem to have the volunteers to do that either. Paul Everitt (a.k.a. the locator-sig :-) is dreaming of something similar but I haven't heard any progress reports from him lately. Sorry for the rambling (it's late), --Guido van Rossum <guido(a)CNRI.Reston.VA.US> URL: <http://www.python.org/~guido/> ================= 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

[PYTHON DOC-SIG] hello?
by richard.jones＠bom.gov.au Feb. 9, 1996

Feb. 9, 1996

OK, I've been in this SIG for a whole day now! Can I expect any traffic? I guess I'm kinda used to Matrix-SIG :) Questions: 1. Is there any significant difference b/w 1.2 and 1.3 docs? I printed a whole swag of 1.2 docs and am loathe to redo the lot... 2. If I produce a diff on the LaTeX source for various bits of the Lib doc (for example), who should I give it to so it'll be used? 3. What's happening wrt. a standard document format? The intro refers to Linuxdoc and a suggestion by Bill Janseen. Where can I obtain information on the latter? Please, if these are obvious/common questions, then don't hesitate to email directly to me... I'm specifically interested in producing up-to-date doc for some of the Library reference sections -- time for one example (detail is required - this one looks like it was thrown together), and regex another (what exactly _is_ a regular expression - I had to learn through trial & error .. and hassling friends). I'd also like to `finish' anywhere else it refers the reader to the `C function of the same name'. This is mostly for my own use - I'm sick and tired of having to look up C references and manual pages when the information could all be in one place... I have _some_ spare time to devote to this. But I'd like to know that it wouldn't be pointless... Richard Richard Jones, Satellite Section at the Bureau of Meteorology, Australia. MIME and PGP accepted. Work phone: +61-3-9669-4539 ================= 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 2