[Pythonmac-SIG] Fixing the documentation...

[Ronald Oussoren]

On 19-apr-2006, at 2:23, Bill Janssen wrote:

> Just looking at the docs, I'm trying to figure out what's good and
> what's bad.
>
> 1) We should no longer point people to Jack's site, we point them to
>    the python.org Mac download page instead.

Right.

>
> 2) references to PythonIDE and PackageManager should go.

Right again. I want to remove those from python2.5 if I can, or at least
move them somewhere where they cannot do harm.

>
> 3) What about the following:
>
>         2. MacPython Modules
>         2.1 macpath -- MacOS path manipulation functions
>         2.2 macfs -- Various file system services
>         2.2.1 FSSpec Objects
>         2.2.2 Alias Objects
>         2.2.3 FInfo Objects
>         2.3 ic -- Access to Internet Config
>         2.3.1 IC Objects
>         2.4 MacOS -- Access to Mac OS interpreter features
>         2.5 macostools -- Convenience routines for file manipulation
>         2.6 findertools -- The finder's Apple Events interface
>         2.7 EasyDialogs -- Basic Macintosh dialogs
>         2.7.1 ProgressBar Objects
>         2.8 FrameWork -- Interactive application framework
>         2.8.1 Application Objects
>         2.8.2 Window Objects
>         2.8.3 ControlsWindow Object
>         2.8.4 ScrolledWindow Object
>         2.8.5 DialogWindow Objects
>         2.9 autoGIL -- Global Interpreter Lock handling in event loops
>         3. MacPython OSA Modules
>         3.1 gensuitemodule -- Generate OSA stub packages
>         3.2 aetools -- OSA client support
>         3.3 aepack -- Conversion between Python variables and  
> AppleEvent data containers
>         3.4 aetypes -- AppleEvent objects
>         3.5 MiniAEFrame -- Open Scripting Architecture server support
>         3.5.1 AEServer Objects
>         4. MacOS Toolbox Modules
>         4.1 Carbon.AE -- Apple Events
>         4.2 Carbon.AH -- Apple Help
>         4.3 Carbon.App -- Appearance Manager
>         4.4 Carbon.CF -- Core Foundation
>         4.5 Carbon.CG -- Core Graphics
>         4.6 Carbon.CarbonEvt -- Carbon Event Manager
>         4.7 Carbon.Cm -- Component Manager
>         4.8 Carbon.Ctl -- Control Manager
>         4.9 Carbon.Dlg -- Dialog Manager
>         4.10 Carbon.Evt -- Event Manager
>         4.11 Carbon.Fm -- Font Manager
>         4.12 Carbon.Folder -- Folder Manager
>         4.13 Carbon.Help -- Help Manager
>         4.14 Carbon.List -- List Manager
>         4.15 Carbon.Menu -- Menu Manager
>         4.16 Carbon.Mlte -- MultiLingual Text Editor
>         4.17 Carbon.Qd -- QuickDraw
>         4.18 Carbon.Qdoffs -- QuickDraw Offscreen
>         4.19 Carbon.Qt -- QuickTime
>         4.20 Carbon.Res -- Resource Manager and Handles
>         4.21 Carbon.Scrap -- Scrap Manager
>         4.22 Carbon.Snd -- Sound Manager
>         4.23 Carbon.TE -- TextEdit
>         4.24 Carbon.Win -- Window Manager
>         4.25 ColorPicker -- Color selection dialog
>         5. Undocumented Modules
>         5.1 applesingle -- AppleSingle decoder
>         5.2 buildtools -- Helper module for BuildApplet and Friends
>         5.3 cfmfile -- Code Fragment Resource module
>         5.4 icopen -- Internet Config replacement for open()
>         5.5 macerrors -- Mac OS Errors
>         5.6 macresource -- Locate script resources
>         5.7 Nav -- NavServices calls
>         5.8 PixMapWrapper -- Wrapper for PixMap objects
>         5.9 videoreader -- Read QuickTime movies
>         5.10 W -- Widgets built on FrameWork
>         5.11 waste -- non-Apple TextEdit replacement
>
> My inclination is to delete them all :-).  Except for ones where
> someone pipes up and tells me it still works.  Let folks use the Wiki
> to find modules.

I don't think you can remove them. IIRC some of this is generated  
somehow (although I don't know how).

Macpath deals with OS9/Carbon style paths (Volume:directory:file  
instead of /Volume/directory/file). This might be usefull when using  
Carbon API's. The documentation for this module (and several others)  
does need to mention this instead of confusing users by mentioning it  
is for the mac.

Section 4 (MacOS Toolbox Modules) definitely needs some text. At the  
very least it needs a general explanation about how to translate  
between the C interface as described in Apple's documentation and the  
Python interface.

W (5.10) and waste (5.11) should probably go, waste won't work on  
intel systems anyway and W is ancient and not update for Carbon Events.

Gensuitemodule should be deprecated, at the very least in the  
documentation. I don't know if we can point users to software that's  
not in the stdlib, but if we can I'd add a reference to appscript in  
the deprecation message in the documentation. Has can probably  
comment on the usefulness of the rest of section 3.

I don't know enough about the rest to make useful comments about  
them. I do think however that we shouldn't remove all documentation,  
but should instead work on improving both the documentation and  
actual code.

>
> 4)  Should we document some of the newer stuff?  py2app comes to mind.

Not in the official python documentation. You can't add documentation  
for stuff that is not part of the stdlib. More documentation for  
py2app is of course welcome, and I'm sure Bob is willing to add it to  
the py2app package when you write it :-)

Ronald