[PYTHON DOC-SIG] hello?

[Michael McLay]

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
=================