[Pythonmac-SIG] "Official" mac python Docs Project: requests for help/comments

[Jack Jansen]

Recently, Chris Barker <cbarker@jps.net> said:

> There are a list of modules in the intro that are interfaces to various
> mac
> toolboxes. They are not documented. Does anyone want to provide some
> documentation
> for any of these?? Also, are there any others that should be on this
> list? I've
> checked to make sure these modules all exist. At the very least, I will
> add the modules to the doc, along with a list of methods, gleaned from
> the modules themselves.

I think for these we should list the modules, refer to Inside Mac for
documentation and explain how argument handling differs. Maybe we
should also list the missing and added calls explicitly: some calls
are missing because they're meaningless in Python, or
unimplementable. Some are added because they're needed in Python but
not in C (the as_Resource() coercion stuff and such).

Once there is a framework I can take it upon myself to do the last bit.

> Waste (Non-Apple TextEdit replacement): exists, but is called waste
> (note case). is
> the is the same thing?

Yes, it's the same. Again, this can be documentated mainly with a
reference to the Waste documentation.

> Module: mac

This is documented as the "os" module. If there is a "mac" module
section in the lib manual it should be no more than a reference to the 
os section, possibly with a few paragraphs explaining which things are 
missing (execl and friends) and which are only placeholders.

> Module: macpath
>         Need to add: 
>         
>         abspath, basename, dirname

This is not a module that is normally used, it is usually imported as
os.path. The only reason to use it directly is if you want to
manipulate Mac pathnames on non-mac systems. Again, documenting it by
referring to os.path should be good enough.

> Module: Macconsole
>         Is this completely dead?? Is there a replacement?

It's dead, and there's no replacement.

> Module: macdnr
>         gone. functionality in standard socket module.

Dead, indeed. Also, no need to keep a pointer in the manual, it's been 
dead for years.

> Module: MacOS
>         Add:
>         AcceptHIghLevelEvent : what does this do?

It was part of AppleEvent handling. I think it is not needed anymore
in newer MacOSes, because this happens under the hood, but I'm not
sure. Unless someone complains I'll just take it out (it's gone in
Carbon anyway).

> Module: macostools
>         What are all the k* types? there are a whole pile of them!!

Don't worry: they're imported (with import *) from MACFS. Ignore them.

> Module: aetools
>         Does someone want to volunteer to docuemnt this??

This is going to be a lot of work. 

> Module: mactcp
>         gone. see socket module
>         
> Module: EasyDialogs
>         Need to add the following:
>         AskPassword
>         
>         Is the text about background operation and non-modal dialogs
> still true?

No, it's not true anymore. Another thing to note here is that most of
the methods have gotten new optional parameters.

> Module: FrameWork
> 
>         What is the status of this? Is anyone useing or developing it?

Yes, I'm using it, and a lot of the examples in Demo use it. It should 
really be merged with W and with my private framework, but I don't
have the time.

> Module: MiniAEFrame
> 
>         What is the status of this?? Has it been developed since the
> docs were
> written? Is anyone still using it??

Yes, this is used more heavily. The CGI examples, for instance, use
it. 
> 
> 
> That's about it. Let's start adding stuff!!!

Okay, here's a first list of things that modules that aren't
documented yet:

buildtools - Helper module for BuildApple, BuildApplication and
	macfreeze. Not that important.
cfmfile - Ditto.
codewarrior_support - Unfinished, shouldn't be in the dsitribution.
dbmac - Never seen it before:-) does it work?
findertools - Should be documented.
findmodulefiles - I think this is outdated. Just, do you know?
icopen - Very handy module, but I've never used it. Should be
	documented.
maccache - Seems silly in this era. I'll remove it unless someone
	complains.
macerrors - can be documented with a one-liner somewhere.
macfsn - Auto-imported to replace StandardFile calls in macfs with
	NavServices calls. one-liner is macfs is probably ok.
mactty - Does this still work? Does ctb still work?
nsremote - Should probably be documented.
PixMapWrapper - Should be documented
preferences - Should be documented
pythonprefs - Should be documented
py_resource - Helper for BuildApplet and friends. Not all that
	important to document.
quietconsole - Should be documented
SoundMgr - Obsolete, use Sound

And all the packages in lib-scriptpackages should be documented
(minimally).
aepack, aetools and aetypes should move to Lib (so lib-scriptpackages and
lib-toolbox contain only generated files). lib-scripting will go.
--
Jack Jansen             | ++++ stop the execution of Mumia Abu-Jamal ++++
Jack.Jansen@oratrix.com | ++++ if you agree copy these lines to your sig ++++
www.oratrix.nl/~jack    | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm