[Doc-SIG] Undocumented modules update.

[Guido van Rossum]

Fred asked me to comment on his list of undocumented modules.
Here are my brief comments.

> <builtin>    pcre
			Internal for the "re" module, may go away

>              strop
			Internal for the "string" module, will go away

> <extension>  _locale
			Internal for the "_locale" module

>              cl
			SGI compression library;
			may be out of touch with reality

>              curses
			Important, deserves to be documented

>              dl
			A bit dangerous and platform specific,
			but worth documenting for those that need it

>              fpectl
>              fpetest
			Very specialized for those that want better
			error control over floating point operations;
			a few people at LLNL are probably the only
			who know (or care!) about this.  Only they
			know enough to document it

>              nis
			Useful, but incomplete (doesn't do NIS+).

>              pure
			Useful when you are using Purify.
			Twist Barry Warsaw's arm (he wrote it).

>              sgi
			SGI specific miscellanea (nap(), _getpty());
			worth documenting

>              stdwin
			I won't support this in Python 1.6,
			so not worth documenting.  Don't write new
			code that uses this (but don't remove it
			from the distribution just yet; there are
			some users out there)

>              sv
			SGI Indigo video;
			may be out of touch with reality

>              timing
			Hmm...  I think there's nothing this module
			does that you can't do by calling
			time.time(), plus this module is Unix
			specific.  There are probably some users
			but it ought to disappear in 1.6 and doesn't
			deserve documentation

> <standard>   asynchat
>              asyncore
			Someone should dig up the documentation that
			I hope Sam Rushing has sitting somewhere on
			noghtmare.com

>              audiodev
			This deserves to be documented, it implements
			a platform-independent API for playing audio
			(the platform-specific code it contains should
			*not* be documented, only the portable API)

>              bdb
			Important building block for creating your
			own Python debugger; deserves docs

>              chunk
			Building block for aifc, could also be used
			(perhaps) in other iff-like file format
			readers; deserves docs

>              codeop
			Deserves docs (separated out from code
			because JPython has a different implementation)

>              dircmp
			Very old, should probably become obsolete
			or be turned into an application or demo

>              dospath
			Internal name for os.path on DOS platforms;
			could also be used to manipulate DOS pathnames
			on a non-DOS platform so might be documented
			as such, but it's important to note that
			typically you should use os.path

>              dump
			We just made this obsolete; use pickle or
			marshal instead (it would make a nice demo
			though)

>              find
			This is more deserving of a Demo or Tool;
			perhaps it should become obsolete

>              grep
			Useful enough, but more deserving of being
			a Demo or Tool

>              htmlentitydefs
			Deserves documentation (is it up-to-date?)

>              ihooks
			Used by rexec, so could be documented;
			this is very hairy!
			(Also I can't promise not to change it
			or to make it obsolete later; the plans
			for improving import in Python 1.6 will
			probably make it obsolete.)

>              knee
			This is sample code only; perhaps it
			should become a demo.

>              macurl2path
			Internal for urllib, no need to document
			(but urllib needs to grow another case for
			Win/CE if that has sockets)

>              mutex
			Very weird -- obsolete it?

>              ntpath
			See dospath

>              nturl2path
			See macurl2path

>              packmail
			A simple "shar archive" creator
			which probably should become a tool or demo

>              pipes
			A framework used by toaiff (read the comments)

>              posixpath
			See dospath

>              pty
			Useful at times

>              reconvert
			Should become a tool

>              regex_syntax
			Helper for the old regex module;
			will become obsolete in 1.6 so no need to
			document

>              rlcompleter
			Very cool code that ought to be documented
			(and cross-referenced with the readline
			module)

>              sched
			See mutex

>              statvfs
			To be documented; this is the counterpart
			of the "stat" module for the os.statvfs() call
			present in Linux and some other systems

>              sunau
			To be documented; read/write Sun style
			audio files

>              sunaudio
			Huh?  This seems to be duplicating 5% of
			the functionality of sunau.  Probably
			ought to be obsolete or become a tool

>              toaiff
			This ought to become a tool; it requires
			the external program "sox"

>              tty
			Like pty, this is useful

>              tzparse
			Someone ought to finish this;
			perhaps it is too specific to be a standard
			module and should become a tool or demo

> lib-tk       Canvas
			To be documented; on the other hand one
			could argue that it's better to use the
			Tkinter.Canvas class directly and plan
			for this module's obsolescence

>              Dialog
			To be documented (it interfaces to tk_dialog)

>              FileDialog
			This should probably become obsolete,
			but I think it still has plenty of users.
			It's better to use tkFileDialog,
			which interfaces to tk_getOpenFile and
			tk_getSaveFile

>              FixTk
			Internal for Tkinter on Windows

>              ScrolledText
			Hmm...  This is incomplete and not very
			robust; but people use it.  It should
			eventually be phased out in favor of
			something more like Pmw

>              SimpleDialog
			Like FileDialog, it's better to use
			tkSimpleDialog

>              Tkconstants
			Internal for Tkinter

>              Tkdnd
			To be documented

>              Tkinter
			To be documented (can you say "albatross"? :-)

>              tkColorChooser
			To be documented

>              tkCommonDialog
			To be documented

>              tkFileDialog
			To be documented

>              tkFont
			To be documented

>              tkMessageBox
			To be documented

>              tkSimpleDialog
			To be documented

>              turtle
			To be documented
> 
> plat-*       CD
>              CDIO
>              CDROM
>              CL
>              CL_old
>              FCNTL
>              FILE
>              GET
>              GLWS
>              IN
>              IOCTL
>              SOCKET
>              STROPTS
>              SUNAUDIODEV
>              SV
>              WAIT

These all define platform-specific constants needed for using certain
interfaces (e.g. ioctl).  They probably need to be documented in a
sense, but not every constant in them needs to be documented; instead,
the modules that they belong to should mention "the constants are over
there"

>              ERRNO

			Obsolete!  Use builtin module errno
			(SGI only)

>              cddb
>              cdplayer
			Should become a tool or demo
			(SGI only)

>              panel
>              panelparser
			For the *very* old SGI panel library
			probably not usable any more

>              readcd
			SGI specific CD-ROM player control;
			documentation exists in readcd.doc!
			But probably should become a demo or tool

>              torgb
			Another client of the pipes module;
			SGI specific, probably not used any more

--Guido van Rossum (home page: http://www.python.org/~guido/)