[PYTHON DOC-SIG] hello?

[Guido van Rossum]

> 	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@CNRI.Reston.VA.US>
URL: <http://www.python.org/~guido/>




=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================