[PYTHON DOC-SIG] hello?

[Richard Jones]

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