Add a rough list of undocumented stuff at the end.

5 files changed, 445 insertions, 1 deletions

diff --git a/Doc/Makefile b/Doc/Makefile
index a244f9e..e1b2c36 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -113,7 +113,7 @@ LIBFILES = lib.tex \
     libxdrlib.tex libimghdr.tex \
     librestricted.tex librexec.tex libbastion.tex \
     libformatter.tex liboperator.tex libsoundex.tex libresource.tex \
-    libstat.tex libstrio.tex
+    libstat.tex libstrio.tex libundoc.tex
 
 # Library document
 lib.dvi: $(LIBFILES)
diff --git a/Doc/lib.tex b/Doc/lib.tex
index 66c6b0c..1de9386 100644
--- a/Doc/lib.tex
+++ b/Doc/lib.tex
@@ -194,6 +194,8 @@ to Python and how to embed it in other applications.
 
 \input{libsun}			% SUNOS ONLY
 
+\input{libundoc}
+
 \input{lib.ind}			% Index
 
 \end{document}
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 66c6b0c..1de9386 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -194,6 +194,8 @@ to Python and how to embed it in other applications.
 
 \input{libsun}			% SUNOS ONLY
 
+\input{libundoc}
+
 \input{lib.ind}			% Index
 
 \end{document}
diff --git a/Doc/lib/libundoc.tex b/Doc/lib/libundoc.tex
new file mode 100644
index 0000000..8e2e5db
--- /dev/null
+++ b/Doc/lib/libundoc.tex
@@ -0,0 +1,220 @@
+\chapter{Undocumented Modules}
+
+Here's a quick listing of modules that are currently undocumented, but
+that should be documented.  Feel free to contribute documentation for
+them!  (The idea and most contents for this chapter were taken from a
+posting by Fredrik Lundh; I have revised some modules' status.)
+
+
+\section{Fundamental, and pretty straightforward to document}
+
+UserDict.py -- user-defined wrapper around dictionary objects
+
+UserList.py -- user-defined wrapper around list objects
+
+ni.py -- New import scheme with package support
+
+site.py -- easy access to site-specific modules
+
+
+\section{Frameworks; somewhat harder to document, but
+well worth the effort}
+
+Tkinter.py -- Interface to Tcl/Tk for graphical user interfaces;
+Fredrik is working on this one!
+
+BaseHTTPServer.py -- HTTP server base class
+
+CGIHTTPServer.py -- CGI-savvy HTTP Server
+
+SimpleHTTPServer.py -- Simple HTTP Server
+
+SocketServer.py -- Generic socket server classes
+
+anydbm.py -- Generic interface to all dbm clones
+
+
+\section{Stuff useful to a lot of people, including the CGI crowd}
+
+MimeWriter.py -- Generic MIME writer
+
+mimify.py -- Mimification and unmimification of mail messages
+
+multifile.py -- make each part of a multipart message ``feel'' like
+
+base64.py -- Conversions to/from base64 transport encoding
+
+mailcap.py -- Mailcap file handling
+
+mailbox.py -- handle Unix style, MMDF style, and MH style mailboxes
+
+quopri.py -- Conversions to/from quoted-printable transport encoding
+
+
+\section{Miscellaneous useful utilities}
+
+Some of these are very old and/or not very robust; marked with ``hmm''.
+
+glob.py -- filename globbing (high level interface)
+
+fnmatch.py -- filename globbing (low level interface)
+
+calendar.py -- Calendar printing functions
+
+cmp.py -- Efficiently compare files
+
+cmpcache.py -- Efficiently compare files (uses statcache)
+
+dircache.py -- like os.listdir, but caches results
+
+dircmp.py -- class to build directory diff tools on
+
+linecache.py -- Cache lines from files (used by pdb)
+
+pipes.py -- Conversion pipeline templates (hmm)
+
+popen2.py -- improved popen? (read AND write simultaneously) (hmm)
+
+random.py -- random numbers, layered on top of whrandom.py
+
+statcache.py -- Maintain a cache of file stats
+
+colorsys.py -- Conversion between RGB and other color systems
+
+commands.py -- executing commands and looking at their output and
+status
+
+dumbdbm.py -- A dumb and slow but simple dbm clone (anydbm's last
+resort)
+
+mhlib.py -- MH interface
+
+pty.py -- Pseudo terminal utilities
+
+tty.py -- Terminal utilities
+
+cmd.py -- build line-oriented command interpreters (used by pdb)
+
+whichdb.py -- Guess which db package to use to open a db file
+
+bdb.py -- A generic Python debugger base class (used by pdb)
+
+ihooks.py -- Import hook support (for ni and rexec)
+
+
+\section{Parsing Python}
+
+(One could argue that these should all be documented together with the
+parser module; in fact the parser module section already references
+the token and symbol modules.)
+
+token.py -- Tokens (from ``token.h'')
+
+symbol.py -- Symbols (from ``graminit.h'')
+
+tokenize.py -- regular expression that recognizes Python tokens
+
+AST.py -- see parser module documentation
+
+pyclbr.py -- Parse a Python file and retrieve classes and methods
+
+
+\section{Platform specific modules}
+
+ntpath.py -- equivalent of posixpath on 32-bit Windows
+
+dospath.py -- equivalent of posixpath on MS-DOS
+
+macpath.py -- equivalent of posixpath on Mac
+
+
+\section{Code objects and files, debugger etc.}
+
+compileall.py -- force "compilation" of all .py files in a directory
+
+py_compile.py -- "compile" a .py file to a .pyc file
+
+codehack.py -- extract a function name from a code object
+
+dis.py -- Disassembler for Python bytecode objects
+
+repr.py -- Redo the `...` (representation) but with limits on most
+sizes (used by pdb)
+
+newdir.py -- New dir() function
+
+
+\section{Multimedia}
+
+audiodev.py -- Plays audio files
+
+sunau.py -- parse Sun and NeXT audio files
+
+sunaudio.py -- interpret sun audio headers
+
+toaiff.py -- Convert "arbitrary" sound files to AIFF files
+
+sndhdr.py -- recognizing sound files
+
+wave.py -- parse WAVE files
+
+whatsound.py -- recognizing sound files
+
+
+\section{Oddities}
+
+These modules are probably also obsolete, or just not very useful.
+
+Queue.py -- A multi-producer, multi-consumer queue
+
+bisect.py -- Bisection algorithms
+
+dump.py -- Print python code that reconstructs a variable
+
+emacs.py -- Execute Emacs code from a Python interpreter
+
+find.py -- find files matching pattern in directory tree
+
+fpformat.py -- General floating point formatting functions
+
+grep.py -- grep
+
+mutex.py -- Mutual exclusion -- for use with module sched
+
+packmail.py -- create a self-unpacking shell archive
+
+poly.py -- Polynomials
+
+sched.py -- event scheduler class
+
+shutil.py -- utility functions usable in a shell-like program
+
+util.py -- useful functions that don't fit elsewhere
+
+zmod.py -- Compute properties of mathematical "fields"
+
+tzparse.py -- Parse a timezone specification (unfinished)
+
+
+\section{Obsolete}
+
+addpack.py -- standard support for "packages" (use ni instead)
+
+dbhash.py -- (g)dbm-compatible interface to bsdhash.hashopen (use
+bsddb instead)
+
+fmt.py -- obsolete text formatting abstractions
+
+Para.py -- helper for fmt.py
+
+lockfile.py -- wrapper around FCNTL file locking (use
+fcntl.lockf/flock intead)
+
+tb.py -- Print tracebacks, with a dump of local variables (use
+pdb.pm() or traceback.py instead)
+
+
+\section{Extension modules}
+
+There are some undocumented goodies here, too.  Someone should make a
+list.
diff --git a/Doc/libundoc.tex b/Doc/libundoc.tex
new file mode 100644
index 0000000..8e2e5db
--- /dev/null
+++ b/Doc/libundoc.tex
@@ -0,0 +1,220 @@
+\chapter{Undocumented Modules}
+
+Here's a quick listing of modules that are currently undocumented, but
+that should be documented.  Feel free to contribute documentation for
+them!  (The idea and most contents for this chapter were taken from a
+posting by Fredrik Lundh; I have revised some modules' status.)
+
+
+\section{Fundamental, and pretty straightforward to document}
+
+UserDict.py -- user-defined wrapper around dictionary objects
+
+UserList.py -- user-defined wrapper around list objects
+
+ni.py -- New import scheme with package support
+
+site.py -- easy access to site-specific modules
+
+
+\section{Frameworks; somewhat harder to document, but
+well worth the effort}
+
+Tkinter.py -- Interface to Tcl/Tk for graphical user interfaces;
+Fredrik is working on this one!
+
+BaseHTTPServer.py -- HTTP server base class
+
+CGIHTTPServer.py -- CGI-savvy HTTP Server
+
+SimpleHTTPServer.py -- Simple HTTP Server
+
+SocketServer.py -- Generic socket server classes
+
+anydbm.py -- Generic interface to all dbm clones
+
+
+\section{Stuff useful to a lot of people, including the CGI crowd}
+
+MimeWriter.py -- Generic MIME writer
+
+mimify.py -- Mimification and unmimification of mail messages
+
+multifile.py -- make each part of a multipart message ``feel'' like
+
+base64.py -- Conversions to/from base64 transport encoding
+
+mailcap.py -- Mailcap file handling
+
+mailbox.py -- handle Unix style, MMDF style, and MH style mailboxes
+
+quopri.py -- Conversions to/from quoted-printable transport encoding
+
+
+\section{Miscellaneous useful utilities}
+
+Some of these are very old and/or not very robust; marked with ``hmm''.
+
+glob.py -- filename globbing (high level interface)
+
+fnmatch.py -- filename globbing (low level interface)
+
+calendar.py -- Calendar printing functions
+
+cmp.py -- Efficiently compare files
+
+cmpcache.py -- Efficiently compare files (uses statcache)
+
+dircache.py -- like os.listdir, but caches results
+
+dircmp.py -- class to build directory diff tools on
+
+linecache.py -- Cache lines from files (used by pdb)
+
+pipes.py -- Conversion pipeline templates (hmm)
+
+popen2.py -- improved popen? (read AND write simultaneously) (hmm)
+
+random.py -- random numbers, layered on top of whrandom.py
+
+statcache.py -- Maintain a cache of file stats
+
+colorsys.py -- Conversion between RGB and other color systems
+
+commands.py -- executing commands and looking at their output and
+status
+
+dumbdbm.py -- A dumb and slow but simple dbm clone (anydbm's last
+resort)
+
+mhlib.py -- MH interface
+
+pty.py -- Pseudo terminal utilities
+
+tty.py -- Terminal utilities
+
+cmd.py -- build line-oriented command interpreters (used by pdb)
+
+whichdb.py -- Guess which db package to use to open a db file
+
+bdb.py -- A generic Python debugger base class (used by pdb)
+
+ihooks.py -- Import hook support (for ni and rexec)
+
+
+\section{Parsing Python}
+
+(One could argue that these should all be documented together with the
+parser module; in fact the parser module section already references
+the token and symbol modules.)
+
+token.py -- Tokens (from ``token.h'')
+
+symbol.py -- Symbols (from ``graminit.h'')
+
+tokenize.py -- regular expression that recognizes Python tokens
+
+AST.py -- see parser module documentation
+
+pyclbr.py -- Parse a Python file and retrieve classes and methods
+
+
+\section{Platform specific modules}
+
+ntpath.py -- equivalent of posixpath on 32-bit Windows
+
+dospath.py -- equivalent of posixpath on MS-DOS
+
+macpath.py -- equivalent of posixpath on Mac
+
+
+\section{Code objects and files, debugger etc.}
+
+compileall.py -- force "compilation" of all .py files in a directory
+
+py_compile.py -- "compile" a .py file to a .pyc file
+
+codehack.py -- extract a function name from a code object
+
+dis.py -- Disassembler for Python bytecode objects
+
+repr.py -- Redo the `...` (representation) but with limits on most
+sizes (used by pdb)
+
+newdir.py -- New dir() function
+
+
+\section{Multimedia}
+
+audiodev.py -- Plays audio files
+
+sunau.py -- parse Sun and NeXT audio files
+
+sunaudio.py -- interpret sun audio headers
+
+toaiff.py -- Convert "arbitrary" sound files to AIFF files
+
+sndhdr.py -- recognizing sound files
+
+wave.py -- parse WAVE files
+
+whatsound.py -- recognizing sound files
+
+
+\section{Oddities}
+
+These modules are probably also obsolete, or just not very useful.
+
+Queue.py -- A multi-producer, multi-consumer queue
+
+bisect.py -- Bisection algorithms
+
+dump.py -- Print python code that reconstructs a variable
+
+emacs.py -- Execute Emacs code from a Python interpreter
+
+find.py -- find files matching pattern in directory tree
+
+fpformat.py -- General floating point formatting functions
+
+grep.py -- grep
+
+mutex.py -- Mutual exclusion -- for use with module sched
+
+packmail.py -- create a self-unpacking shell archive
+
+poly.py -- Polynomials
+
+sched.py -- event scheduler class
+
+shutil.py -- utility functions usable in a shell-like program
+
+util.py -- useful functions that don't fit elsewhere
+
+zmod.py -- Compute properties of mathematical "fields"
+
+tzparse.py -- Parse a timezone specification (unfinished)
+
+
+\section{Obsolete}
+
+addpack.py -- standard support for "packages" (use ni instead)
+
+dbhash.py -- (g)dbm-compatible interface to bsdhash.hashopen (use
+bsddb instead)
+
+fmt.py -- obsolete text formatting abstractions
+
+Para.py -- helper for fmt.py
+
+lockfile.py -- wrapper around FCNTL file locking (use
+fcntl.lockf/flock intead)
+
+tb.py -- Print tracebacks, with a dump of local variables (use
+pdb.pm() or traceback.py instead)
+
+
+\section{Extension modules}
+
+There are some undocumented goodies here, too.  Someone should make a
+list.