restructured library manual accordiung to functional group

Doc/Makefile

@@ -98,7 +98,8 @@ ref.dvi: ref.tex ref1.tex ref2.tex ref3.tex ref4.tex ref5.tex ref6.tex \
 
 # LaTeX source files for the Python Library Reference
 LIBFILES = lib.tex \
-libal.tex libaifc.tex libamoeba.tex libarray.tex libaudio.tex libaudioop.tex \
+libal.tex libaifc.tex liballos.tex \
+	libamoeba.tex libarray.tex libaudio.tex libaudioop.tex \
 libbltin.tex \
 libcd.tex \
 libcgi.tex libcopy.tex libctb.tex libcrypto.tex \
@@ -112,16 +113,17 @@ libjpeg.tex \
 libmac.tex libmacconsole.tex libmacdnr.tex \
 	libmacfs.tex libmactcp.tex libmacspeech.tex \
 	libmain.tex libmarshal.tex libmath.tex \
-	libmd5.tex libmimetools.tex libmm.tex libmods.tex libmpz.tex \
+	libmd5.tex libmimetools.tex libmisc.tex \
+	libmm.tex libmods.tex libmpz.tex \
 libnntplib.tex \
 libobjs.tex libos.tex \
 libpanel.tex libpickle.tex libposix.tex libposixfile.tex \
-	libppath.tex libprofile.tex libpwd.tex \
+	libppath.tex libprofile.tex libpwd.tex libpython.tex \
 librand.tex libregex.tex libregsub.tex \
 	librfc822.tex librgbimg.tex librotor.tex \
 libselect.tex libsgi.tex libsgmllib.tex \
-	libshelve.tex libsocket.tex libstd.tex libstdwin.tex \
-	libstring.tex libstruct.tex libsun.tex libsys.tex \
+	libshelve.tex libsocket.tex libsomeos.tex libstd.tex libstdwin.tex \
+	libstring.tex libstrings.tex libstruct.tex libsun.tex libsys.tex \
 libtempfile.tex libthread.tex libtime.tex \
 	libtraceback.tex libtypes.tex libtypes2.tex \
 libunix.tex liburllib.tex liburlparse.tex \

Doc/lib.tex

@@ -22,8 +22,8 @@
 \begin{abstract}
 
 \noindent
-This document describes the built-in types, exceptions and functions
-and the standard modules that come with the Python system.  It assumes
+This document describes the built-in and standard types, exceptions,
+functions and modules that come with the Python system.  It assumes
 basic knowledge about the Python language.  For an informal
 introduction to the language, see the {\em Python Tutorial}.  The {\em
 Python Reference Manual} gives a more formal definition of the
@@ -51,52 +51,58 @@ language.
 \input{libexcs}
 \input{libfuncs}
 
-\input{libmods}			% Built-in modules
+\input{libpython}		% Python Services
 \input{libsys}
-\input{libbltin}		% really __builtin__
+\input{libtypes2}		% types is already taken :-(
+\input{libtraceback}
+\input{libpickle}
+\input{libshelve}
+\input{libcopy}
+\input{libmarshal}
 \input{libimp}
+\input{libbltin}		% really __builtin__
 \input{libmain}			% really __main__
-\input{libarray}
-\input{libmath}
-\input{libtime}
+
+\input{libstrings}		% String Services
+\input{libstring}
 \input{libregex}
-\input{libmarshal}
+\input{libregsub}
 \input{libstruct}
 
-\input{libstd}			% Standard Modules
-\input{libgetopt}
-\input{libos}
+\input{libmisc}			% Miscellaneous Services
+\input{libmath}
 \input{librand}
-\input{libregsub}
-\input{libstring}
 \input{libwhrandom}
-\input{libaifc}
-\input{libpickle}
-\input{libshelve}
-\input{libcopy}
-\input{libtypes2}		% types is already taken :-(
-\input{libtempfile}
-\input{libtraceback}
+\input{libarray}
 
-\input{libpdb}			% The Python Debugger
+\input{liballos}		% Generic Operating System Services
+\input{libos}
+\input{libtime}
+\input{libgetopt}
+\input{libtempfile}
 
-\input{libprofile}		% The Python Profiler
+\input{libsomeos}		% Optional Operating System Services
+\input{libsignal}
+\input{libsocket}
+\input{libselect}
+\input{libthread}
 
-\input{libunix}			% UNIX ONLY
+\input{libunix}			% UNIX Specific Services
+\input{libposix}
+\input{libppath}		% == posixpath
+\input{libpwd}
+\input{libgrp}
 \input{libdbm}
-\input{libfcntl}
 \input{libgdbm}
-\input{libgrp}
-\input{libposix}
+\input{libtermios}
+\input{libfcntl}
 \input{libposixfile}
-\input{libppath}		% really posixpath
-\input{libpwd}
-\input{libselect}
-\input{libsignal}
-\input{libsocket}
-\input{libthread}
 
-\input{libwww}			% WWW EXTENSIONS
+\input{libpdb}			% The Python Debugger
+
+\input{libprofile}		% The Python Profiler
+
+\input{libwww}			% Internet and WWW Services
 \input{libcgi}
 \input{liburllib}
 \input{libhttplib}
@@ -109,13 +115,14 @@ language.
 \input{librfc822}
 \input{libmimetools}
 
-\input{libmm}			% MULTIMEDIA EXTENSIONS
+\input{libmm}			% Multimedia Services
 \input{libaudioop}
 \input{libimageop}
+\input{libaifc}
 \input{libjpeg}
 \input{librgbimg}
 
-\input{libcrypto}		% CRYPTOGRAPHIC EXTENSIONS
+\input{libcrypto}		% Cryptographic Services
 \input{libmd5}
 \input{libmpz}
 \input{librotor}

Doc/lib/lib.tex

@@ -22,8 +22,8 @@
 \begin{abstract}
 
 \noindent
-This document describes the built-in types, exceptions and functions
-and the standard modules that come with the Python system.  It assumes
+This document describes the built-in and standard types, exceptions,
+functions and modules that come with the Python system.  It assumes
 basic knowledge about the Python language.  For an informal
 introduction to the language, see the {\em Python Tutorial}.  The {\em
 Python Reference Manual} gives a more formal definition of the
@@ -51,52 +51,58 @@ language.
 \input{libexcs}
 \input{libfuncs}
 
-\input{libmods}			% Built-in modules
+\input{libpython}		% Python Services
 \input{libsys}
-\input{libbltin}		% really __builtin__
+\input{libtypes2}		% types is already taken :-(
+\input{libtraceback}
+\input{libpickle}
+\input{libshelve}
+\input{libcopy}
+\input{libmarshal}
 \input{libimp}
+\input{libbltin}		% really __builtin__
 \input{libmain}			% really __main__
-\input{libarray}
-\input{libmath}
-\input{libtime}
+
+\input{libstrings}		% String Services
+\input{libstring}
 \input{libregex}
-\input{libmarshal}
+\input{libregsub}
 \input{libstruct}
 
-\input{libstd}			% Standard Modules
-\input{libgetopt}
-\input{libos}
+\input{libmisc}			% Miscellaneous Services
+\input{libmath}
 \input{librand}
-\input{libregsub}
-\input{libstring}
 \input{libwhrandom}
-\input{libaifc}
-\input{libpickle}
-\input{libshelve}
-\input{libcopy}
-\input{libtypes2}		% types is already taken :-(
-\input{libtempfile}
-\input{libtraceback}
+\input{libarray}
 
-\input{libpdb}			% The Python Debugger
+\input{liballos}		% Generic Operating System Services
+\input{libos}
+\input{libtime}
+\input{libgetopt}
+\input{libtempfile}
 
-\input{libprofile}		% The Python Profiler
+\input{libsomeos}		% Optional Operating System Services
+\input{libsignal}
+\input{libsocket}
+\input{libselect}
+\input{libthread}
 
-\input{libunix}			% UNIX ONLY
+\input{libunix}			% UNIX Specific Services
+\input{libposix}
+\input{libppath}		% == posixpath
+\input{libpwd}
+\input{libgrp}
 \input{libdbm}
-\input{libfcntl}
 \input{libgdbm}
-\input{libgrp}
-\input{libposix}
+\input{libtermios}
+\input{libfcntl}
 \input{libposixfile}
-\input{libppath}		% really posixpath
-\input{libpwd}
-\input{libselect}
-\input{libsignal}
-\input{libsocket}
-\input{libthread}
 
-\input{libwww}			% WWW EXTENSIONS
+\input{libpdb}			% The Python Debugger
+
+\input{libprofile}		% The Python Profiler
+
+\input{libwww}			% Internet and WWW Services
 \input{libcgi}
 \input{liburllib}
 \input{libhttplib}
@@ -109,13 +115,14 @@ language.
 \input{librfc822}
 \input{libmimetools}
 
-\input{libmm}			% MULTIMEDIA EXTENSIONS
+\input{libmm}			% Multimedia Services
 \input{libaudioop}
 \input{libimageop}
+\input{libaifc}
 \input{libjpeg}
 \input{librgbimg}
 
-\input{libcrypto}		% CRYPTOGRAPHIC EXTENSIONS
+\input{libcrypto}		% Cryptographic Services
 \input{libmd5}
 \input{libmpz}
 \input{librotor}

Doc/lib/libaifc.tex

@@ -11,8 +11,14 @@ The sampling rate or frame rate is the number of times per second the
 sound is sampled.  The number of channels indicate if the audio is
 mono, stereo, or quadro.  Each frame consists of one sample per
 channel.  The sample size is the size in bytes of each sample.  Thus a
-frame consists of \var{nchannels}*\var{framesize} bytes, and a second's worth of
-audio consists of \var{nchannels}*\var{framesize}*\var{framerate} bytes.
+frame consists of \var{nchannels}*\var{samplesize} bytes, and a
+second's worth of audio consists of
+\var{nchannels}*\var{samplesize}*\var{framerate} bytes.
+
+For example, CD quality audio has a sample size of two bytes (16
+bits), uses two channels (stereo) and has a frame rate of 44,100
+frames/second.  This gives a frame size of 4 bytes (2*2), and a
+second's worth occupies 2*2*44100 bytes, i.e.\ 176,400 bytes.
 
 Module \code{aifc} defines the following function:
 
@@ -148,7 +154,7 @@ string.  Currently the following compression types are supported:
 NONE, ULAW, ALAW, G722.
 \end{funcdesc}
 
-\begin{funcdesc}{setparams}{(nchannels\, sampwidth\, framerate\, comptype\, compname)}
+\begin{funcdesc}{setparams}{nchannels\, sampwidth\, framerate\, comptype\, compname}
 Set all the above parameters at once.  The argument is a tuple
 consisting of the various parameters.  This means that it is possible
 to use the result of a \code{getparams} call as argument to

Doc/lib/liballos.tex

+\chapter{Generic Operating System Services}
+
+The modules described in this chapter provide interfaces to operating
+system features that are available on (almost) all operating systems,
+such as files and a clock.  The interfaces are generally modelled
+after the \UNIX{} or C interfaces but they are available on most other
+systems as well.  Here's an overview:
+
+\begin{description}
+
+\item[os]
+--- Miscellaneous OS interfaces.
+
+\item[time]
+--- Time access and conversions.
+
+\item[getopt]
+--- Parser for command line options.
+
+\item[tempfile]
+--- Generate temporary file names.
+
+\end{description}

Doc/lib/libamoeba.tex

-\chapter{AMOEBA ONLY}
+\chapter{Amoeba Specific Services}
 
 \section{Built-in Module \sectcode{amoeba}}
 

Doc/lib/libarray.tex

@@ -23,6 +23,9 @@ The actual representation of values is determined by the machine
 architecture (strictly speaking, by the C implementation).  The actual
 size can be accessed through the \var{itemsize} attribute.
 
+See also built-in module \code{struct}.
+\bimodindex{struct}
+
 The module defines the following function:
 
 \renewcommand{\indexsubitem}{(in module array)}

Doc/lib/libcrypto.tex

-\chapter{CRYPTOGRAPHIC EXTENSIONS}
+\chapter{Cryptographic Services}
+\index{cryptography}
 
 The modules described in this chapter implement various algorithms of
 a cryptographic nature.  They are available at the discretion of the
-installation. 
-\index{cryptography}
+installation.  Here's an overview:
+
+\begin{description}
+
+\item[md5]
+--- RSA's MD5 message digest algorithm.
+
+\item[mpz]
+--- Interface to the GNU MP library for arbitrary precision arithmetic.
+
+\item[rotor]
+--- Enigma-like encryption and decryption.
+
+\end{description}
 
 Hardcore cypherpunks will probably find the Python Cryptography Kit of
 further interest; the package adds built-in modules for DES and IDEA

Doc/lib/libfuncs.tex

@@ -197,7 +197,8 @@ removed.
   Convert a number to a plain integer.  The argument may be a plain or
   long integer or a floating point number.  Conversion of floating
   point numbers to integers is defined by the C semantics; normally
-  the conversion truncates towards zero.
+  the conversion truncates towards zero.\footnote{This is ugly --- the
+  language definition should require truncation towards zero.}
 \end{funcdesc}
 
 \begin{funcdesc}{len}{s}

Doc/lib/libhttplib.tex

@@ -46,8 +46,12 @@ file object that it returns.
 
 \end{enumerate}
 
+\subsection{HTTP Objects}
+
 \code{HTTP} instances have the following methods:
 
+\renewcommand{\indexsubitem}{(HTTP method)}
+
 \begin{funcdesc}{set_debuglevel}{level}
 Set the debugging level (the amount of debugging output printed).
 The default debug level is \code{0}, meaning no debugging output is

Doc/lib/libimp.tex

@@ -51,7 +51,7 @@ object.  If the module was already initialized, it will be initialized
 \code{None} is returned.  (Frozen modules are modules written in
 Python whose compiled byte-code object is incorporated into a
 custom-built Python interpreter by Python's \code{freeze} utility.
-See \code{Demo/freeze} for now.)
+See \code{Tools/freeze} for now.)
 \end{funcdesc}
 
 \begin{funcdesc}{is_builtin}{name}

Doc/lib/libmimetools.tex

@@ -45,7 +45,7 @@ file \var{output}.  The block size is currently fixed at 8192.
 \end{funcdesc}
 
 
-\subsection{Additional Methods of \sectcode{Message} objects}
+\subsection{Additional Methods of Message objects}
 \nodename{mimetools.Message Methods}
 
 The \code{mimetools.Message} class defines the following methods in

Doc/lib/libmisc.tex

+\chapter{Miscellaneous Services}
+
+The modules described in this chapter provide miscellaneous services
+that are available in all Python versions.  Here's an overview:
+
+\begin{description}
+
+\item[math]
+--- Mathematical functions (\code{sin()} etc.).
+
+\item[rand]
+--- Integer random number generator.
+
+\item[whrandom]
+--- Floating point random number generator.
+
+\item[array]
+--- Efficient arrays of uniformly typed numeric values.
+
+\end{description}

Doc/lib/libmm.tex

-\chapter{MULTIMEDIA EXTENSIONS}
+\chapter{Multimedia Services}
 
-The modules described in this chapter implement various algorithms
-that are mainly useful for multimedia applications.  They are
-available at the discretion of the installation.
+The modules described in this chapter implement various algorithms or
+interfaces that are mainly useful for multimedia applications.  They
+are available at the discretion of the installation.  Here's an overview:
+
+\begin{description}
+
+\item[audioop]
+--- Manipulate raw audio data.
+
+\item[imageop]
+--- Manipulate raw image data.
+
+\item[aifc]
+--- Read and write audio files in AIFF or AIFC format.
+
+\item[jpeg]
+--- Read and write image files in compressed JPEG format.
+
+\item[rgbimg]
+--- Read and write image files in ``SGI RGB'' format (the module is
+\emph{not} SGI specific though)!
+
+\end{description}

Doc/lib/libobjs.tex

@@ -4,16 +4,21 @@
 
 Names for built-in exceptions and functions are found in a separate
 symbol table.  This table is searched last, so local and global
-user-defined names can override built-in names.  Built-in types have
-no names but are created easily by constructing an object of the
-desired type (e.g., using a literal) and applying the built-in
-function \code{type()} to it.  They are described together here for
-easy reference.%
-\footnote{Some descriptions sorely lack explanations of the exceptions
+user-defined names can override built-in names.  Built-in types are
+described together here for easy reference.  %
+\footnote{Most descriptions sorely lack explanations of the exceptions
 	that may be raised --- this will be fixed in a future version of
-	this document.}
+	this manual.}
 \indexii{built-in}{types}
 \indexii{built-in}{exceptions}
 \indexii{built-in}{functions}
 \index{symbol table}
 \bifuncindex{type}
+
+The tables in this chapter document the priorities of operators by
+listing them in order of ascending priority (within a table) and
+grouping operators that have the same priority in the same box.
+Binary operators of the same priority group from left to right.
+(Unary operators group from right to left, but there you have no real
+choice.)  See Chapter 5 of the Python Reference Manual for the
+complete picture on operator priorities.

Doc/lib/libpickle.tex

@@ -11,7 +11,9 @@
 
 The \code{pickle} module implements a basic but powerful algorithm for
 ``pickling'' (a.k.a.\ serializing, marshalling or flattening) nearly
-arbitrary Python objects.  This is a more primitive notion than
+arbitrary Python objects.  This is the act of converting objects to a
+stream of bytes (and back: ``unpickling'').
+This is a more primitive notion than
 persistency --- although \code{pickle} reads and writes file objects,
 it does not handle the issue of naming persistent objects, nor the
 (even more complicated) area of concurrent access to persistent
@@ -54,7 +56,8 @@ advantage of using printable \ASCII{} (and of some other characteristics
 of \code{pickle}'s representation) is that for debugging or recovery
 purposes it is possible for a human to read the pickled file with a
 standard text editor.  (I could have gone a step further and used a
-notation like S-expressions, but the parser would have been
+notation like S-expressions, but the parser
+(currently written in Python) would have been
 considerably more complicated and slower, and the files would probably
 have become much larger.)
 

Doc/lib/libpython.tex

+\chapter{Python Services}
+
+The modules described in this chapter provide a wide range of services
+related to the Python interpreter and its interaction with its
+environment.  Here's an overview:
+
+\begin{description}
+
+\item[sys]
+--- Access system specific parameters and functions.
+
+\item[types]
+--- Names for all built-in types.
+
+\item[traceback]
+--- Print or retrieve a stack traceback.
+
+\item[pickle]
+--- Convert Python objects to streams of bytes and back.
+
+\item[shelve]
+--- Python object persistency.
+
+\item[copy]
+--- Shallow and deep copy operations.
+
+\item[marshal]
+--- Convert Python objects to streams of bytes and back (with
+different constraints).
+
+\item[imp]
+--- Access the implementation of the \code{import} statement.
+
+\item[__builtin__]
+--- The set of built-in functions.
+
+\item[__main__]
+--- The environment where the top-level script is run.
+
+\end{description}

Doc/lib/librfc822.tex

@@ -21,6 +21,8 @@ All header matching is done independent of upper or lower case;
 e.g. \code{m['From']}, \code{m['from']} and \code{m['FROM']} all yield
 the same result.
 
+\subsection{Message Objects}
+
 A \code{Message} instance has the following methods:
 
 \begin{funcdesc}{rewindbody}{}

Doc/lib/libsgi.tex

-\chapter{SGI IRIX ONLY}
+\chapter{SGI IRIX Specific Services}
 
 The modules described in this chapter provide interfaces to features
 that are unique to SGI's IRIX operating system (versions 4 and 5).

Doc/lib/libsomeos.tex

+\chapter{Optional Operating System Services}
+
+The modules described in this chapter provide interfaces to operating
+system features that are available on selected operating systems only.
+The interfaces are generally modelled after the \UNIX{} or C
+interfaces but they are available on some other systems as well
+(e.g. Windows or NT).  Here's an overview:
+
+\begin{description}
+
+\item[signal]
+--- Set handlers for asynchronous events.
+
+\item[socket]
+--- Low-level networking interface.
+
+\item[select]
+--- Wait for I/O completion on multiple streams.
+
+\item[thread]
+--- Create multiple threads of control within one namespace.
+
+\end{description}

Doc/lib/libstdwin.tex

-\chapter{STDWIN ONLY}
+\chapter{Standard Windowing Interface}
+
+The modules in this chapter are available only on those systems where
+the STDWIN library is available.  STDWIN runs on \UNIX{} under X11 and
+on the Macintosh.  See CWI report CS-R8817.
+
+\strong{Warning:} Using STDWIN is not recommended for new
+applications.  It has never been ported to Microsoft Windows or
+Windows NT, and for X11 or the Macintosh it lacks important
+functionality --- in particular, it has no tools for the construction
+of dialogs.  For most platforms, alternative, native solutions exist
+(though none are currently documented in this manual): Tkinter for
+\UNIX{} under X11, native Xt with Motif or Athena widgets for \UNIX{}
+under X11, Win32 for Windows and Windows NT, and a collection of
+native toolkit interfaces for the Macintosh.
 
 \section{Built-in Module \sectcode{stdwin}}
 \bimodindex{stdwin}
 
 This module defines several new object types and functions that
-provide access to the functionality of the Standard Window System
-Interface, STDWIN [CWI report CR-R8817].
-It is available on systems to which STDWIN has been ported (which is
-most systems).
+provide access to the functionality of STDWIN.
 
 On Unix running X11, it can only be used if the \code{DISPLAY}
 environment variable is set or an explicit \samp{-display

Doc/lib/libstrings.tex

+\chapter{String Services}
+
+The modules described in this chapter provide a wide range of string
+manipulation operations.  Here's an overview:
+
+\begin{description}
+
+\item[string]
+--- Common string operations.
+
+\item[regex]
+--- Regular expression search and match operations.
+
+\item[regsub]
+--- Substitution and splitting operations that use regular expressions.
+
+\item[struct]
+--- Interpret strings as packed binary data.
+
+\end{description}

Doc/lib/libstruct.tex

@@ -7,6 +7,9 @@ structs represented as Python strings.  It uses \dfn{format strings}
 (explained below) as compact descriptions of the lay-out of the C
 structs and the intended conversion to/from Python values.
 
+See also built-in module \code{array}.
+\bimodindex{array}
+
 The module defines the following exception and functions:
 
 \renewcommand{\indexsubitem}{(in module struct)}

Doc/lib/libsun.tex

-\chapter{SUNOS ONLY}
+\chapter{SunOS Specific Services}
 
 The modules described in this chapter provide interfaces to features
 that are unique to the SunOS operating system (versions 4 and 5; the
-latter is also known as SOLARIS version 2).
+latter is also known as Solaris version 2).
 
 \section{Built-in Module \sectcode{sunaudiodev}}
 \bimodindex{sunaudiodev}

Doc/lib/libtermios.tex

+\section{Built-in Module \sectcode{termios}}
+
+To be provided.

Doc/lib/libunix.tex

-\chapter{UNIX ONLY}
+\chapter{UNIX Specific Services}
 
 The modules described in this chapter provide interfaces to features
 that are unique to the \UNIX{} operating system, or in some cases to
-some or many variants of it.
+some or many variants of it.  Here's an overview:
+
+\begin{description}
+
+\item[posix]
+--- The most common Posix system calls (normally used via module \code{os}).
+
+\item[posixpath]
+--- Common Posix pathname manipulations (normally used via \code{os.path}).
+
+\item[pwd]
+--- The password database (\code{getpwnam()} and friends).
+
+\item[grp]
+--- The group database (\code{getgrnam()} and friends).
+
+\item[dbm]
+--- The standard ``database'' interface, based on \code{ndbm}.
+
+\item[gdbm]
+--- GNU's reinterpretation of dbm.
+
+\item[termios]
+--- Posix style tty control.
+
+\item[fcntl]
+--- The \code{fcntl()} and \code{ioctl()} system calls.
+
+\item[posixfile]
+--- A file-like object with support for locking.
+
+\end{description}

Doc/lib/libwww.tex

-\chapter{THE INTERNET AND THE WORLD-WIDE WEB}
+\chapter{Internet and WWW Services}
 \nodename{Internet and WWW}
 \index{WWW}
 \index{Internet}

Doc/libaifc.tex

@@ -11,8 +11,14 @@ The sampling rate or frame rate is the number of times per second the
 sound is sampled.  The number of channels indicate if the audio is
 mono, stereo, or quadro.  Each frame consists of one sample per
 channel.  The sample size is the size in bytes of each sample.  Thus a
-frame consists of \var{nchannels}*\var{framesize} bytes, and a second's worth of
-audio consists of \var{nchannels}*\var{framesize}*\var{framerate} bytes.
+frame consists of \var{nchannels}*\var{samplesize} bytes, and a
+second's worth of audio consists of
+\var{nchannels}*\var{samplesize}*\var{framerate} bytes.
+
+For example, CD quality audio has a sample size of two bytes (16
+bits), uses two channels (stereo) and has a frame rate of 44,100
+frames/second.  This gives a frame size of 4 bytes (2*2), and a
+second's worth occupies 2*2*44100 bytes, i.e.\ 176,400 bytes.
 
 Module \code{aifc} defines the following function:
 
@@ -148,7 +154,7 @@ string.  Currently the following compression types are supported:
 NONE, ULAW, ALAW, G722.
 \end{funcdesc}
 
-\begin{funcdesc}{setparams}{(nchannels\, sampwidth\, framerate\, comptype\, compname)}
+\begin{funcdesc}{setparams}{nchannels\, sampwidth\, framerate\, comptype\, compname}
 Set all the above parameters at once.  The argument is a tuple
 consisting of the various parameters.  This means that it is possible
 to use the result of a \code{getparams} call as argument to

Doc/liballos.tex

+\chapter{Generic Operating System Services}
+
+The modules described in this chapter provide interfaces to operating
+system features that are available on (almost) all operating systems,
+such as files and a clock.  The interfaces are generally modelled
+after the \UNIX{} or C interfaces but they are available on most other
+systems as well.  Here's an overview:
+
+\begin{description}
+
+\item[os]
+--- Miscellaneous OS interfaces.
+
+\item[time]
+--- Time access and conversions.
+
+\item[getopt]
+--- Parser for command line options.
+
+\item[tempfile]
+--- Generate temporary file names.
+
+\end{description}

Doc/libamoeba.tex

-\chapter{AMOEBA ONLY}
+\chapter{Amoeba Specific Services}
 
 \section{Built-in Module \sectcode{amoeba}}
 

Doc/libarray.tex

@@ -23,6 +23,9 @@ The actual representation of values is determined by the machine
 architecture (strictly speaking, by the C implementation).  The actual
 size can be accessed through the \var{itemsize} attribute.
 
+See also built-in module \code{struct}.
+\bimodindex{struct}
+
 The module defines the following function:
 
 \renewcommand{\indexsubitem}{(in module array)}

Doc/libcrypto.tex

-\chapter{CRYPTOGRAPHIC EXTENSIONS}
+\chapter{Cryptographic Services}
+\index{cryptography}
 
 The modules described in this chapter implement various algorithms of
 a cryptographic nature.  They are available at the discretion of the
-installation. 
-\index{cryptography}
+installation.  Here's an overview:
+
+\begin{description}
+
+\item[md5]
+--- RSA's MD5 message digest algorithm.
+
+\item[mpz]
+--- Interface to the GNU MP library for arbitrary precision arithmetic.
+
+\item[rotor]
+--- Enigma-like encryption and decryption.
+
+\end{description}
 
 Hardcore cypherpunks will probably find the Python Cryptography Kit of
 further interest; the package adds built-in modules for DES and IDEA

Doc/libfuncs.tex

@@ -197,7 +197,8 @@ removed.
   Convert a number to a plain integer.  The argument may be a plain or
   long integer or a floating point number.  Conversion of floating
   point numbers to integers is defined by the C semantics; normally
-  the conversion truncates towards zero.
+  the conversion truncates towards zero.\footnote{This is ugly --- the
+  language definition should require truncation towards zero.}
 \end{funcdesc}
 
 \begin{funcdesc}{len}{s}

Doc/libhttplib.tex

@@ -46,8 +46,12 @@ file object that it returns.
 
 \end{enumerate}
 
+\subsection{HTTP Objects}
+
 \code{HTTP} instances have the following methods:
 
+\renewcommand{\indexsubitem}{(HTTP method)}
+
 \begin{funcdesc}{set_debuglevel}{level}
 Set the debugging level (the amount of debugging output printed).
 The default debug level is \code{0}, meaning no debugging output is

Doc/libimp.tex

@@ -51,7 +51,7 @@ object.  If the module was already initialized, it will be initialized
 \code{None} is returned.  (Frozen modules are modules written in
 Python whose compiled byte-code object is incorporated into a
 custom-built Python interpreter by Python's \code{freeze} utility.
-See \code{Demo/freeze} for now.)
+See \code{Tools/freeze} for now.)
 \end{funcdesc}
 
 \begin{funcdesc}{is_builtin}{name}

Doc/libmac.tex

-\chapter{MACINTOSH ONLY}
+\chapter{Macintosh Specific Services}
 
 The modules in this chapter are available on the Apple Macintosh only.
 

Doc/libmimetools.tex

@@ -45,7 +45,7 @@ file \var{output}.  The block size is currently fixed at 8192.
 \end{funcdesc}
 
 
-\subsection{Additional Methods of \sectcode{Message} objects}
+\subsection{Additional Methods of Message objects}
 \nodename{mimetools.Message Methods}
 
 The \code{mimetools.Message} class defines the following methods in

Doc/libmisc.tex

+\chapter{Miscellaneous Services}
+
+The modules described in this chapter provide miscellaneous services
+that are available in all Python versions.  Here's an overview:
+
+\begin{description}
+
+\item[math]
+--- Mathematical functions (\code{sin()} etc.).
+
+\item[rand]
+--- Integer random number generator.
+
+\item[whrandom]
+--- Floating point random number generator.
+
+\item[array]
+--- Efficient arrays of uniformly typed numeric values.
+
+\end{description}

Doc/libmm.tex

-\chapter{MULTIMEDIA EXTENSIONS}
+\chapter{Multimedia Services}
 
-The modules described in this chapter implement various algorithms
-that are mainly useful for multimedia applications.  They are
-available at the discretion of the installation.
+The modules described in this chapter implement various algorithms or
+interfaces that are mainly useful for multimedia applications.  They
+are available at the discretion of the installation.  Here's an overview:
+
+\begin{description}
+
+\item[audioop]
+--- Manipulate raw audio data.
+
+\item[imageop]
+--- Manipulate raw image data.
+
+\item[aifc]
+--- Read and write audio files in AIFF or AIFC format.
+
+\item[jpeg]
+--- Read and write image files in compressed JPEG format.
+
+\item[rgbimg]
+--- Read and write image files in ``SGI RGB'' format (the module is
+\emph{not} SGI specific though)!
+
+\end{description}

Doc/libobjs.tex

@@ -4,16 +4,21 @@
 
 Names for built-in exceptions and functions are found in a separate
 symbol table.  This table is searched last, so local and global
-user-defined names can override built-in names.  Built-in types have
-no names but are created easily by constructing an object of the
-desired type (e.g., using a literal) and applying the built-in
-function \code{type()} to it.  They are described together here for
-easy reference.%
-\footnote{Some descriptions sorely lack explanations of the exceptions
+user-defined names can override built-in names.  Built-in types are
+described together here for easy reference.  %
+\footnote{Most descriptions sorely lack explanations of the exceptions
 	that may be raised --- this will be fixed in a future version of
-	this document.}
+	this manual.}
 \indexii{built-in}{types}
 \indexii{built-in}{exceptions}
 \indexii{built-in}{functions}
 \index{symbol table}
 \bifuncindex{type}
+
+The tables in this chapter document the priorities of operators by
+listing them in order of ascending priority (within a table) and
+grouping operators that have the same priority in the same box.
+Binary operators of the same priority group from left to right.
+(Unary operators group from right to left, but there you have no real
+choice.)  See Chapter 5 of the Python Reference Manual for the
+complete picture on operator priorities.

Doc/libpickle.tex

@@ -11,7 +11,9 @@
 
 The \code{pickle} module implements a basic but powerful algorithm for
 ``pickling'' (a.k.a.\ serializing, marshalling or flattening) nearly
-arbitrary Python objects.  This is a more primitive notion than
+arbitrary Python objects.  This is the act of converting objects to a
+stream of bytes (and back: ``unpickling'').
+This is a more primitive notion than
 persistency --- although \code{pickle} reads and writes file objects,
 it does not handle the issue of naming persistent objects, nor the
 (even more complicated) area of concurrent access to persistent
@@ -54,7 +56,8 @@ advantage of using printable \ASCII{} (and of some other characteristics
 of \code{pickle}'s representation) is that for debugging or recovery
 purposes it is possible for a human to read the pickled file with a
 standard text editor.  (I could have gone a step further and used a
-notation like S-expressions, but the parser would have been
+notation like S-expressions, but the parser
+(currently written in Python) would have been
 considerably more complicated and slower, and the files would probably
 have become much larger.)
 

Doc/libpython.tex

+\chapter{Python Services}
+
+The modules described in this chapter provide a wide range of services
+related to the Python interpreter and its interaction with its
+environment.  Here's an overview:
+
+\begin{description}
+
+\item[sys]
+--- Access system specific parameters and functions.
+
+\item[types]
+--- Names for all built-in types.
+
+\item[traceback]
+--- Print or retrieve a stack traceback.
+
+\item[pickle]
+--- Convert Python objects to streams of bytes and back.
+
+\item[shelve]
+--- Python object persistency.
+
+\item[copy]
+--- Shallow and deep copy operations.
+
+\item[marshal]
+--- Convert Python objects to streams of bytes and back (with
+different constraints).
+
+\item[imp]
+--- Access the implementation of the \code{import} statement.
+
+\item[__builtin__]
+--- The set of built-in functions.
+
+\item[__main__]
+--- The environment where the top-level script is run.
+
+\end{description}

Doc/librfc822.tex

@@ -21,6 +21,8 @@ All header matching is done independent of upper or lower case;
 e.g. \code{m['From']}, \code{m['from']} and \code{m['FROM']} all yield
 the same result.
 
+\subsection{Message Objects}
+
 A \code{Message} instance has the following methods:
 
 \begin{funcdesc}{rewindbody}{}

Doc/libsgi.tex

-\chapter{SGI IRIX ONLY}
+\chapter{SGI IRIX Specific Services}
 
 The modules described in this chapter provide interfaces to features
 that are unique to SGI's IRIX operating system (versions 4 and 5).

Doc/libsomeos.tex

+\chapter{Optional Operating System Services}
+
+The modules described in this chapter provide interfaces to operating
+system features that are available on selected operating systems only.
+The interfaces are generally modelled after the \UNIX{} or C
+interfaces but they are available on some other systems as well
+(e.g. Windows or NT).  Here's an overview:
+
+\begin{description}
+
+\item[signal]
+--- Set handlers for asynchronous events.
+
+\item[socket]
+--- Low-level networking interface.
+
+\item[select]
+--- Wait for I/O completion on multiple streams.
+
+\item[thread]
+--- Create multiple threads of control within one namespace.
+
+\end{description}

Doc/libstdwin.tex

-\chapter{STDWIN ONLY}
+\chapter{Standard Windowing Interface}
+
+The modules in this chapter are available only on those systems where
+the STDWIN library is available.  STDWIN runs on \UNIX{} under X11 and
+on the Macintosh.  See CWI report CS-R8817.
+
+\strong{Warning:} Using STDWIN is not recommended for new
+applications.  It has never been ported to Microsoft Windows or
+Windows NT, and for X11 or the Macintosh it lacks important
+functionality --- in particular, it has no tools for the construction
+of dialogs.  For most platforms, alternative, native solutions exist
+(though none are currently documented in this manual): Tkinter for
+\UNIX{} under X11, native Xt with Motif or Athena widgets for \UNIX{}
+under X11, Win32 for Windows and Windows NT, and a collection of
+native toolkit interfaces for the Macintosh.
 
 \section{Built-in Module \sectcode{stdwin}}
 \bimodindex{stdwin}
 
 This module defines several new object types and functions that
-provide access to the functionality of the Standard Window System
-Interface, STDWIN [CWI report CR-R8817].
-It is available on systems to which STDWIN has been ported (which is
-most systems).
+provide access to the functionality of STDWIN.
 
 On Unix running X11, it can only be used if the \code{DISPLAY}
 environment variable is set or an explicit \samp{-display

Doc/libstrings.tex

+\chapter{String Services}
+
+The modules described in this chapter provide a wide range of string
+manipulation operations.  Here's an overview:
+
+\begin{description}
+
+\item[string]
+--- Common string operations.
+
+\item[regex]
+--- Regular expression search and match operations.
+
+\item[regsub]
+--- Substitution and splitting operations that use regular expressions.
+
+\item[struct]
+--- Interpret strings as packed binary data.
+
+\end{description}

Doc/libstruct.tex

@@ -7,6 +7,9 @@ structs represented as Python strings.  It uses \dfn{format strings}
 (explained below) as compact descriptions of the lay-out of the C
 structs and the intended conversion to/from Python values.
 
+See also built-in module \code{array}.
+\bimodindex{array}
+
 The module defines the following exception and functions:
 
 \renewcommand{\indexsubitem}{(in module struct)}

Doc/libsun.tex

-\chapter{SUNOS ONLY}
+\chapter{SunOS Specific Services}
 
 The modules described in this chapter provide interfaces to features
 that are unique to the SunOS operating system (versions 4 and 5; the
-latter is also known as SOLARIS version 2).
+latter is also known as Solaris version 2).
 
 \section{Built-in Module \sectcode{sunaudiodev}}
 \bimodindex{sunaudiodev}

Doc/libtermios.tex

+\section{Built-in Module \sectcode{termios}}
+
+To be provided.

Doc/libunix.tex

-\chapter{UNIX ONLY}
+\chapter{UNIX Specific Services}
 
 The modules described in this chapter provide interfaces to features
 that are unique to the \UNIX{} operating system, or in some cases to
-some or many variants of it.
+some or many variants of it.  Here's an overview:
+
+\begin{description}
+
+\item[posix]
+--- The most common Posix system calls (normally used via module \code{os}).
+
+\item[posixpath]
+--- Common Posix pathname manipulations (normally used via \code{os.path}).
+
+\item[pwd]
+--- The password database (\code{getpwnam()} and friends).
+
+\item[grp]
+--- The group database (\code{getgrnam()} and friends).
+
+\item[dbm]
+--- The standard ``database'' interface, based on \code{ndbm}.
+
+\item[gdbm]
+--- GNU's reinterpretation of dbm.
+
+\item[termios]
+--- Posix style tty control.
+
+\item[fcntl]
+--- The \code{fcntl()} and \code{ioctl()} system calls.
+
+\item[posixfile]
+--- A file-like object with support for locking.
+
+\end{description}

Doc/libwww.tex

-\chapter{THE INTERNET AND THE WORLD-WIDE WEB}
+\chapter{Internet and WWW Services}
 \nodename{Internet and WWW}
 \index{WWW}
 \index{Internet}

Doc/mac/libmac.tex

-\chapter{MACINTOSH ONLY}
+\chapter{Macintosh Specific Services}
 
 The modules in this chapter are available on the Apple Macintosh only.