[Pythonmac-SIG] Fixing the documentation...

[has]

Bill Janssen wrote:

>Thanks, Has.
>
>I was hoping someone would go through that list bit-by-bit.

See also NR's post and my reply to it; anything Internet Config-related looks reasonable to add to the 'deprecate' list. Hopefully there'll be a few more yeas/nays on it from other folks; like I say there's still a few I'm not sure about.


>I'm still in favor of simply removing outdated and dangerous docs, but
>perhaps there's some effective way of thoroughly marking them as bad,
>instead.

I dunno if there's anything actually "dangerous" in there; it's more just a case of "bloody awful-looking", "a complete waste of readers' time to trawl through" and "a rotten first impression for newcomers". Which still matters, of course; it just takes longer to drum up the motivation to deal with it. :)

I'd agree that chapter 1's content should all be deleted as the stuff it refers to no longer exists. Replace it with a placeholder page (for now) that describes what's currently available: python/pythonw in Terminal.app, IDLE, PythonLauncher and BuildApplet (BA should probably be marked deprecated). Could also mention that OS X's system-wide scripts menu can - permissions willing - be used to run .py (and other) shell scripts.

For deprecating individual modules, best to follow the standard procedure though. For documentation it seems to mean adding a bold "Deprecated since release 2.x" line at the top of the page for a whole module, or to the end of a individual function's description. (Pretty weak, if you ask me, but if that's the official policy then that's the official policy.) But you really need to check with the proper sources before doing anything.

HTH

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