[Doc-SIG] Undocumented modules

[Christopher G. Petrilli]

I've kinda gone through this and figured out what probably SHOULD be
documented, what shouldn't be documented (i.e. it's not exposed to the
outside world) and what might just be totally deprecated.

<standard>  CGIHTTPServer	DOCUMENT
            SimpleHTTPServer	DOCUMENT
            asynchat		DOCUMENT (I'm writing this right now)
            asyncore		DOCUMENT (same)
            audiodev		DOCUMENT (platform specific SGI/Sun)
            bdb			DOCUMENT (though not overly exposed)
            cmp			DEPRECATE (seems to be duplicate of cmpcache)
            cmpcache		DOCUMENT
            codeop		DOCUMENT
            colorsys		DEPRECATE (very incomplete and possible
	    			inacurate, use PIL)
            dbhash		DOCUMENT
            dircache		DOCUMENT
            dircmp		DOCUMENT
            dospath		DOCUMENT (platform specific Wintel)
            dump		DEPRECATE (seems to be half-implemented)
            find		DEPRECATE (move to scripts?)
            fpformat		DOCUMENT
            grep		DEPRECATE (move to scripts?)
            htmlentitydefs	DOCUMENT
            ihooks		DOCUMENT (see comment below)
            knee		DOCUMENT (not really usable, example)
            linecache		DOCUMENT (potentially useful with
	    			fileinput)
            macpath		DOCUMENT (platform specific Mac)
            macurl2path		DOCUMENT (platform specific Mac)
            mhlib		DOCUMENT (has anyone tested this?)
            mutex		DOCUMENT
            ntpath		DOCUMENT (platform specific NT)
            nturl2path		DOCUMENT (platform specific NT)
            packmail		DEPRECATE (move to scripts?)
            pipes		DOCUMENT
            posixpath		DOCUMENT (platform specific POSIX)
            pty			DEPRECATE (VERY VERY platform specific)
            reconvert		DEPRECATE (incomplete, move to scripts?)
            regex_syntax	DEPRECATE (regex no longer preffered)
            rlcompleter		INTERNAL (don't document)
            sched		DOCUMENT
            statcache		DOCUMENT (see notes about cache things)
            statvfs		DOCUMENT (used with os.statvfs())
            sunau		DOCUMENT (platform specific Sun)
            sunaudio		DOCUMENT (platform specific Sun)
            telnetlib		DOCUMENT
            threading_api	WHAT IS THIS?! (looks like docs for
	    			threading.py)
            toaiff		DEPRECATE (move to scripts?)
            tty			DEPRECATE (move to termios?)
            turtle		DOCUMENT (Tkinter though)
            tzparse		DOCUMENT
            util		DEPRECATE (hold over from 1.4)
            wave		DEPRECATE (not sure honestly! :-)
            whatsound		DEPRECATE (same as sndhdr)

ihooks - should this be in with the new module, it seems to be of the
same class of "shoot yourself in the foot" modules :-)  Perhaps we
should have a "WARNING" label for modules that are especially dangerous
to use?

caching things - has anyone actually tested these for performance?  A
quick check on my FreeBSD 3.0 box says they're slower than not caching
because of (I assume) file system caching effeciency...  Maybe that was
a fluke, at least with statcache ;-)

lib-tk is a royal pain :-) Maybe Frederick will finish soon! :-)

plat-*      AWARE	DOCUMENT? (is this viable on new IRIX?)
            CD		INTERNAL
            CL		DEPRECATE (seems ot be deprecated)
            CL_old	DEPRECATE (same)
            ERRNO	DOCUMENT (I'd just reference the errno.h file)
            FCNTL	DOCUMENT (same here, maybe some BASICS that are
	    		common on all platforms?)
            FILE	DOCUMENT (reference external source)
            GET		DOCUMENT (woah, major platform specific IRIX)
            GLWS	DOCUMENT (more major IRIX stuff)
            IN		DOCUMENT (reference)
            IOCTL	DOCUMENT (reference)
            SOCKET	DOCUMENT (reference)
            STROPTS	INTERNAL (dear god, who uses THIS?!?!?!)
            SUNAUDIODEV DOCUEMNT (platform specific)
            SV		DOCUMENT (more major platform IRIX stuff)
            WAIT	DOCUMENT (very useful stuff here)
            cddb	DOCUMENT (note overlap with Internet CDDB)
            cdplayer	DOCUMENT (platform specific IRIX)
            panel	DOCUMENT (same)
            panelparser DOCUMENT (same)
            readcd	DOCUMENT (same)
            torgb	DEPRECATE (use PIL I think)

As you've no doubt noticed, not much I don't say to document, BUT... I'm
worried about all this HYPER specific IRIX stuff... perhaps it should
be moved into it's own seperate documentation area, or even a seperate
distribution of sorts (a'la Mac)... there's a ton of junk that just
isn't useful for 99% of the users.

Just ideas... shoot at me at will :-)

Chris
-- 
| Christopher Petrilli                      ``Television is bubble-gum for
| petrilli@amber.org                          the mind.''-Frank Lloyd Wright