From richard.jones@bom.gov.au Thu Feb 8 04:44:16 1996 From: richard.jones@bom.gov.au (Richard Jones) Date: Thu, 08 Feb 1996 04:44:16 GMT Subject: [PYTHON DOC-SIG] hello? Message-ID: <199602080445.XAA22989@python.org> 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@python.org administrivia to: doc-sig-request@python.org ================= From mclay@eeel.nist.gov Thu Feb 8 16:01:51 1996 From: mclay@eeel.nist.gov (Michael McLay) Date: Thu, 8 Feb 96 11:01:51 EST Subject: [PYTHON DOC-SIG] hello? In-Reply-To: <199602080445.XAA22989@python.org> References: <199602080445.XAA22989@python.org> Message-ID: <9602081601.AA17469@acdc.eeel.nist.gov> Richard Jones writes: > > 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 :) No. It's been really quiet here. I suppose that's because documentation isn't as much fun as coding. > 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... Just print the tutorial. Almost all the changes are documented in the "What's New in 1.3 " section that was tacked on at the end. If you use Ghostview you can just print out the last five pages and save printing the whole thing. I don't have my old 1.2 manuals, and I don't recall if changes were made to the library reference manual. There may have been some additions to the section on WWW tools. > 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? I suspect it would be better to spend the time working on an update of the documents for release 1.4. > 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. > Please, if these are obvious/common questions, then don't hesitate to > email directly to me... To the contrary, It's good to finally have someone speak up. > 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). Great, a volunteer. I suspect Guido would like the help. > 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... Excellent. Having to search through other documentation is always a pain. Please be sure to check for any system dependent names and values. > > I have _some_ spare time to devote to this. But I'd like to > know that it wouldn't be pointless... 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. Michael ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From richard.jones@bom.gov.au Fri Feb 9 03:04:46 1996 From: richard.jones@bom.gov.au (Richard Jones) Date: Fri, 09 Feb 1996 03:04:46 GMT Subject: [PYTHON DOC-SIG] hello? In-Reply-To: Message from Michael McLay of 1996-Feb-8 11:1:51, <9602081601.AA17469@acdc.eeel.nist.gov> Message-ID: <199602090306.WAA30779@python.org> 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... I've also munged the order of my followup here so that it's a little more sane. Michael McLay wrote: > Richard Jones writes: > > 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? > I suspect it would be better to spend the time working on an update of > the documents for release 1.4. > 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. Guido, anyone, can I get a more concrete answer on this one? I don't particuarly like the idea of file locking via email, but I can't really think of any other sane method to do it. Anything else that I think of is far more complex in terms of setup. Hmm. That gives me another idea that I will mention at the end of the mail. 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... > > 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. OK, well, if I have the time, I'll look through the docs for Linuxdoc, but I won't promise anything. As I said in the previous paragraph, I'll keep working on the LaTeX - we should be able to auto-convert the docs over to the doc standard. Richard *The message at the end* 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. 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@python.org administrivia to: doc-sig-request@python.org ================= From guido@CNRI.Reston.VA.US Fri Feb 9 05:02:39 1996 From: guido@CNRI.Reston.VA.US (Guido van Rossum) Date: Fri, 09 Feb 1996 00:02:39 -0500 Subject: [PYTHON DOC-SIG] hello? In-Reply-To: Your message of "Fri, 09 Feb 1996 03:04:46 GMT." <9602082208.aa17994@CNRI.Reston.VA.US> References: <9602082208.aa17994@CNRI.Reston.VA.US> Message-ID: <199602090502.AAA24863@monty.cnri.reston.va.us> > 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 URL: ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org =================