[Pythonmac-SIG] Fixing the documentation...

[has]

Bill Janssen wrote:

>1) We should no longer point people to Jack's site, we point them to
>   the python.org Mac download page instead.

Agree. Having links to the old MacPython site in places where folk expect to find up-to-date information doesn't help.

Also, if there's somewhere to provide a list of highly respected Python contributors, make sure Jack's name is up there accompanied by his site link for posterity. Wouldn't want the removal of obsolete links from the main body of documentation to look like a writing out of history of the Jack and his terrific contribution to Mac Python over the years.


>Just looking at the docs, I'm trying to figure out what's good and
>what's bad.
>
>2) references to PythonIDE and PackageManager should go.

Sounds fine to me. They're related products, not part of the core Python distribution, so shouldn't be any problem eliminating mention of those from the documentation. Might need to put in a short page about IDLE to replace the old Python IDE section.

In addition, all mentions of OS 9 should either be expunged (e.g. the 'using Python on Mac OS 9' chapter) or changed to 'not supported' (should they still need to be documented for any reason).


>3) What about the following:
>
>   2. MacPython Modules

Well, it feels tempting at times just do a straight delete on this too. <g>

However: these modules are all part of the official distribution, so I would imagine that any to be dropped needs to go through the full deprecation procedure first.


>        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.


>        2.2 macfs -- Various file system services

Already deprecated as of 2.3.  Delete yet?


>        2.3 ic -- Access to Internet Config

No idea about this. Anyone else know if this is still working/relevant?


>        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.


>        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?


>        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>


>        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.


>        4.2 Carbon.AH -- Apple Help

Do nothing.


>        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.


>        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.


>        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.


>        4.18 Carbon.Qdoffs -- QuickDraw Offscreen

Deprecate. QD is already deprecated in OS X 10.4.


>        4.19 Carbon.Qt -- QuickTime

Do nothing.


>        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?


>        5.4 icopen -- Internet Config replacement for open()

Presumably in the same boat as '2.3 ic'. Anyone?


>        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?


>        5.10 W -- Widgets built on FrameWork

Deprecate.

>        5.11 waste -- non-Apple TextEdit replacement

Deprecate? (ISTR it's not in the universal build.)


>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.


HTH

has
-- 
http://freespace.virgin.net/hamish.sanderson/