[Pythonmac-SIG] "Official" MacPython docs: HELP!!!!

[Chris Barker]

Hi all,

I just got a message from Fred Drake, the maintainer of the Python
documentation, about the MacPython doc. Some of you may recall that I
took on the project of updating the docs before the 2.0 release. I got
contributions from a number of folks, and some progress was made, but we
have a long way to go. Fred would really like to see doc filled in,
there are a lot of gaps.

I am willing to take on the job of coordinating everyone's efforts, and
putting it all together into the source LaTeX document. I do not,
however, have enough time to also do all the writing, and frankly, I am
unqualified to do a lot of it anyway.

Please, Please, Please, try to find a few hours to help out with this
project. A lot of information is already available in various READMEs
and html docs scattered about the MacPython distrobution, but it would
be great if those coule be updated and incorporated into the Offical
docs.

I think it would be a major benifit to the MacPython community to
improve this document. People coming to Python on the Mac for the first
time will see this doc first, and it could really help to get them
started, rather than give them the impression that the Mac is a second
class citizen in the Python world.

Please take a look at the doc at:

http://www.python.org/doc/current/mac/mac.html

The "Using Python on the Macintosh" Section really needs some beefing up
an filling in. Also the "Undocumented Modules" section needs to be
addressed. Another section I'd love to see is one on using Apple Events,
and OSA. I know there is some of this in the html docs with the distro,
could someone update that and contribute it? There are a whole lot of
other holes in the doc as well. If you have recently figured out how to
do something, please consider writing it up and sending it to me.

If everyone that has some MacPython expertise spent a few hours on this,
we could really improve it a lot.

Please send a note to this list if you intend to work on a section, so
that we can avoid duplication.

Another doc that really needs help (from a Mac perspective) is the
Extending and Embedding doc:

http://www.python.org/doc/current/ext/ext.html

It has, as it's primary example, a simple function that calls the
"system" C function. this is obviously useless on the Mac. There are
also specific sections on how to set up and compile an extension in Unix
and Windows. We really need a section like that for the Mac. I hope
someone can find some time to write that up. It really only needs be a
couple of pages. 

The Doc is written in LaTeX, with a very specific style, so that it can
be easily converted into PDF and HTML form. If you are writing a small
section, you might as well just write it in plain text, and I'll put it
into the LaTeX doc. If you want to work on a larger section, you can get
the LaTeX source from the sourceforge CVS server, or I'll send it to you
if you like. Info about the LaTeX format can be found in:

http://python.sourceforge.net/devel-docs/doc/doc.html


Thanks to any of you who have helped out in the past, and any that will
help out now.

-Chris

-- 
Christopher Barker,
Ph.D.                                                           
cbarker@jps.net                      ---           ---           ---
http://www.jps.net/cbarker          -----@@       -----@@       -----@@
                                   ------@@@     ------@@@     ------@@@
Water Resources Engineering       ------   @    ------   @   ------   @
Coastal and Fluvial Hydrodynamics -------      ---------     --------    
------------------------------------------------------------------------
------------------------------------------------------------------------