[Pythonmac-SIG] Fixing the documentation...

[Ronald Oussoren]

On 19-apr-2006, at 15:38, has wrote:

>
>
>>        2.1 macpath -- MacOS path manipulation functions
>
> Deprecate. Also note that the 2.4.3 documentation now says "It can  
> be used to manipulate old-style Macintosh pathnames on Mac OS X (or  
> any other platform)." which is incorrect (it uses POSIX-style  
> paths), so delete that sentence.

I'm not a native english speaker, but I read this as "you can use  
this to manipulate OS9 style paths on any platform". Just like you  
can use ntpath to manipulate windows-style paths (c:\foo\bar.txt) on  
any platform. That's actually a useful feature.

As I mentioned in another message this module might be useful to work  
with OS9-style paths as used by some Carbon API's.
>
>>        2.4 MacOS -- Access to Mac OS interpreter features
>
> Get/SetCreatorAndType should really be fixed or deprecated as they  
> don't appear to work for bundle-based files.

They should be fixed. Why does everyone want to remove what they  
don't quite understand? One of the strong points of python on the mac  
is that it is one of the *very* few languages that provides bindings  
to most parts of the system APIs. IMHO the bindings to Carbon suck,  
but that doesn't mean we should scrap or completely hide them.

Stuff should be deprecated and removed only if we are absolutely sure  
it is useless, and preferably only if we have a replacement. An  
example of this is application scripting support, everybody seems to  
agree that appscript is miles better than the stuff in the stdlib.

I'd love to deprecate Carbon.CF as well, but we can't do that until  
we have another way to access those APIs. PyObjC is about this > <  
close to doing that, I just haven't gotten around finishing the final  
bits yet.

>
>
>>        2.5 macostools -- Convenience routines for file manipulation
>
> Not sure about this. It's pretty ancient and crusty though, so I'd  
> be inclined to deprecate.
>
>
>>        2.6 findertools -- The finder's Apple Events interface
>
> Deprecate.
>
>
>>        2.7 EasyDialogs -- Basic Macintosh dialogs
>
> It's ancient and very crusty, but until there's an up-to-date  
> replacement I guess it has to stay as-is for now, alas. Might be a  
> good idea to check functions for unicode compatibility, long string  
> support, etc. and add notes on any limitations found.
>
>
>>        2.8 FrameWork -- Interactive application framework
>
> Deprecate.
>
>
>>        2.9 autoGIL -- Global Interpreter Lock handling in event loops
>
> No idea. Anyone?

I think this can be deprecated. This is a pretty neat trick to give  
up the GIL while an eventloop is waiting for events. That way you can  
easily use multithreaded programs in a GUI. That was useful when  
PyObjC didn't do GIL management itself (in the days when Python 2.3b1  
was bleeding edge), but I don't think we still need this.

>
>
>>        3. MacPython OSA Modules
>
> Deprecate.
>
>
>>        4. MacOS Toolbox Modules
>
> These are just wrappers around the existing Carbon APIs. So as long  
> as those APIs are themselves relevant, so are the wrappers. You can  
> get background info, including a list of which APIs are legacy-only  
> at:
>
> <http://developer.apple.com/documentation/Carbon/Conceptual/ 
> newtocarbon/chapter_1_section_1.html>

Right. As I mentioned in another message it would be nice if someone  
described the way API's are mapped from C to Python. That makes it  
easier to use examples and documentation for the C API.

>
>
>>        4.1 Carbon.AE -- Apple Events
>
> Ronald's been thinking it might be best to deprecate both Carbon.AE  
> and Carbon.OSA and keep all the AE/OSA/appscript stuff together.  
> Dunno if he's got any further on that yet; you could ask.

I'm slowly moving forwards, like most people these days I'm too busy  
to spend much time on this.  I think it would be better to move all  
application scripting related code to an external package (and  
preferably one such package instead of the bundle of packages you  
need to install right now to get appscript). The rationale for this  
is that has is currently the only person that is working on  
application scripting support for python and that his work doesn't  
seem to be finished enough to freeze it by includeing it in the stdlib.

>
>
>>        4.2 Carbon.AH -- Apple Help
>
> Do nothing.

Documentation would be nice :-)

>
>
>>        4.3 Carbon.App -- Appearance Manager
>
> Apple's docs describe AM as 'the older QuickDraw-centric version of  
> HITheme', but don't note it as being superceded/deprecated so I  
> guess it should stay as-is.
>
>
>>        4.4 Carbon.CF -- Core Foundation
>>        4.5 Carbon.CG -- Core Graphics
>>        4.6 Carbon.CarbonEvt -- Carbon Event Manager
>
> Do nothing.
>
>
>>        4.7 Carbon.Cm -- Component Manager
>
> According to Apple's docs CM is largely historical; modern apps  
> should use Core Foundation's Plug-in Services. Other Carbon APIs  
> still rely on it though, so do nothing.
>
>
>>        4.8 Carbon.Ctl -- Control Manager
>
> According to Apple's docs, HIView is superseding the older Control  
> Manager. For now though, do nothing.
>
>
>>        4.9 Carbon.Dlg -- Dialog Manager
>
> According to Apple's docs, Interface Builder and Carbon event  
> handlers mostly supersede the Dialog Manager, except in the cases  
> where you want to put up a standard alert dialog box or sheet. For  
> now though, do nothing.
>
>
>>        4.10 Carbon.Evt -- Event Manager
>
> Deprecate, or at least add note to use modern alternative.  
> Superceded by CarbonEvt.

Don't deprecate but not that you should CarbonEvt and that Apple has  
deprecated the Event Manager API.


>
>
>>        4.11 Carbon.Fm -- Font Manager
>>        4.12 Carbon.Folder -- Folder Manager
>>        4.13 Carbon.Help -- Help Manager
>
> Do nothing.
>
>
>>        4.14 Carbon.List -- List Manager
>
> Deprecate, or at least add note to use modern alternative.  
> Superceded by Control Manager.

Same as Carbon.Evt.
>
>
>>        4.15 Carbon.Menu -- Menu Manager
>>        4.16 Carbon.Mlte -- MultiLingual Text Editor
>
> Do nothing.
>
>
>>        4.17 Carbon.Qd -- QuickDraw
>
> Deprecate. QD is already deprecated in OS X 10.4.
Likewise

>
>
>>        4.18 Carbon.Qdoffs -- QuickDraw Offscreen
>
> Deprecate. QD is already deprecated in OS X 10.4.
Likewise.

>
>
>>        4.19 Carbon.Qt -- QuickTime
>
> Do nothing.

Yet another piece of code to hunt down. Doesn't Bob have an enhanced  
version of this module? If so I think we should merge this into  
Python 2.5.

>
>
>>        4.20 Carbon.Res -- Resource Manager and Handles
>
> According to Apple's docs, RM is historical, but I'm not sure about  
> alternatives; need to check out Bundle Services. For now, probably  
> do nothing.
>
>
>>        4.21 Carbon.Scrap -- Scrap Manager
>
> According to Apple's docs, Scrap Manager is superceded by  
> Pasteboard Manager in OS X. We don't have a wrapper for that  
> though, so probably do nothing.
>
>
>>        4.22 Carbon.Snd -- Sound Manager
>
> Do nothing.
>
>
>>        4.23 Carbon.TE -- TextEdit
>
> Deprecate/add note. Superceded by Mlte, which has unicode support,  
> etc..
>
>
>>        4.24 Carbon.Win -- Window Manager
>>        4.25 ColorPicker -- Color selection dialog
>
> Do nothing.
>
>
>>        5. Undocumented Modules
>>        5.1 applesingle -- AppleSingle decoder
>
> No idea. Anyone?
>
>
>>        5.2 buildtools -- Helper module for BuildApplet and Friends
>
> Deprecate, or at least add a note that py2app is the modern  
> alternative and strongly recommended.
>
>
>>        5.3 cfmfile -- Code Fragment Resource module
>
> Probably deprecate. Anyone?

CFM is still used on OSX. However given the docstring for this module  
I'd guess that it can be deprecated.
>
>
>>        5.4 icopen -- Internet Config replacement for open()
>
> Presumably in the same boat as '2.3 ic'. Anyone?

I think this can be deprecated. This module replaces __builtin__.open  
by a function that sets the right type/creator codes using data from  
ic. That was useful in OS9, but I don't think is is very useful in  
today.

>
>
>>        5.5 macerrors -- Mac OS Errors
>
> Do nothing.
>
>
>>        5.6 macresource -- Locate script resources
>
> Presumably in same boat as '4.20 Carbon.Res'. Anyone?
>
>
>>        5.7 Nav -- NavServices calls
>
> Do nothing.
>
>
>>        5.8 PixMapWrapper -- Wrapper for PixMap objects
>
> Deprecate. (Since QD is deprecated on OS 10.4.)
>
>
>>        5.9 videoreader -- Read QuickTime movies
>
> No idea. Anyone?

This seems to be more of an example that a useful module.

>
>
>>        5.10 W -- Widgets built on FrameWork
>
> Deprecate.
>
>>        5.11 waste -- non-Apple TextEdit replacement
>
> Deprecate? (ISTR it's not in the universal build.)

I'm tempted to remove it altogether in 2.5. This depends on a 3th- 
party libary that isn't available for Intel.

>
>
>> 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.
>
> Your inclination is understandable, but I don't think it'd be  
> wisest. :)
>
> Personally I really dislike the 'deprecate in-place' approach that  
> seems to be used in the Python docs. It'd be much clearer and  
> easier on readers if all the crud were moved into a 'Deprecated  
> modules' chapter. That way it wouldn't force readers to wade  
> through piles of irrelevant cruft and junk each time that want to  
> look up current info, but it could still be found when needed.  
> Perhaps you could negotiate to do something like that?
>
>
>> 4)  Should we document some of the newer stuff?
>
> Carbon.LaunchServices, which is part of the standard library as of  
> 2.4. It should be added to the 'Carbon' section as another  
> placeholder page.
>
> There's also Carbon.OSA, which is part of the standard library as  
> of 2.4 (though it's buggy and incomplete), which can be added to  
> the 'Carbon' section as another placeholder page. It may or may not  
> be deprecated, depending on what happens with the Carbon.AE module.
>
> plistlib probably ought to be mentioned. I suspect it's evil, as  
> it's not using the Property List Services API, but am not familiar  
> enough with it to really say anything more with confidence.
>
>
>> py2app comes to mind.
>
> For external projects I'd suggest adding placeholder pages that  
> simply link to external sites (i.e. quick and simple for now;  
> anyone with an urge to expand them can do so in their own time).  
> PyObjC, py2app and appscript are the three obvious ones that I can  
> think of.
>
> The PyObjC link is obvious <pyobjc.sourceforge.net>. I imagine  
> you'd link to Bob's site for py2app. At some poing I'd like to  
> shift appscript off my personal webspace to a proper permanent home  
> (sourceforge??), so maybe point to the wiki page for that for now.

I think it is better to keep not add references to PyObjC, py2app and  
appscript to the module reference other than in deprecation messages.  
That is, anyone that looks for the documentation for OSA modules  
should be told that those are deprecated and should be pointed to  
appscript.  I really hate manuals that deprecate stuff without  
telling me what I should do instead.

Ronald