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/ _______________________________________________ Pythonmac-SIG maillist - Pythonmac-SIG@python.org http://mail.python.org/mailman/listinfo/pythonmac-sig
