Make internal module references hyperlinks wherever it makes sense.

Doc/lib/libal.tex

@@ -17,8 +17,8 @@ All functions and methods defined in this module are equivalent to
 the C functions with \samp{AL} prefixed to their name.
 
 Symbolic constants from the C header file \code{<audio.h>} are
-defined in the standard module \module{AL}\refstmodindex{AL}, see
+defined in the standard module
-below.
+\refmodule[al-constants]{AL}\refstmodindex{AL}, see below.
 
 \strong{Warning:} the current version of the audio library may dump core
 when bad argument values are passed rather than returning an error
@@ -170,7 +170,7 @@ Get status information on last error.
 
 
 This module defines symbolic constants needed to use the built-in
-module \module{al} (see above); they are equivalent to those defined
+module \refmodule{al} (see above); they are equivalent to those defined
 in the C header file \code{<audio.h>} except that the name prefix
 \samp{AL_} is omitted.  Read the module source for a complete list of
 the defined names.  Suggested use:

Doc/lib/libaudioop.tex

@@ -1,14 +1,14 @@
 \section{\module{audioop} ---
-         Manipulate raw audio data.}
+         Manipulate raw audio data}
-\declaremodule{builtin}{audioop}
 
+\declaremodule{builtin}{audioop}
 \modulesynopsis{Manipulate raw audio data.}
 
 
 The \module{audioop} module contains some useful operations on sound
 fragments.  It operates on sound fragments consisting of signed
 integer samples 8, 16 or 32 bits wide, stored in Python strings.  This
-is the same format as used by the \module{al} and \module{sunaudiodev}
+is the same format as used by the \refmodule{al} and \refmodule{sunaudiodev}
 modules.  All scalar items are integers, unless specified otherwise.
 
 % This para is mostly here to provide an excuse for the index entries...

Doc/lib/libbinascii.tex

@@ -1,15 +1,15 @@
 \section{\module{binascii} ---
-         Convert between binary and various ascii-encoded representations.}
+         Convert between binary \ASCII{}-encoded formats}
-\declaremodule{builtin}{binascii}
 
+\declaremodule{builtin}{binascii}
 \modulesynopsis{Tools for converting between binary and various
-ascii-encoded binary representations.}
+                \ASCII{}-encoded binary representations.}
 
 
 The \module{binascii} module contains a number of methods to convert
 between binary and various \ASCII{}-encoded binary
-representations. Normally, you will not use these modules directly but
+representations. Normally, you will not use these functions directly
-use wrapper modules like \module{uu}\refstmodindex{uu} or
+but use wrapper modules like \refmodule{uu}\refstmodindex{uu} or
 \module{hexbin}\refstmodindex{hexbin} instead, this module solely
 exists because bit-manipuation of large amounts of data is slow in
 Python.

Doc/lib/libcopyreg.tex

@@ -1,14 +1,14 @@
 \section{\module{copy_reg} ---
-         Register \module{pickle} support functions.}
+         Register \module{pickle} support functions}
-\declaremodule[copyreg]{standard}{copy_reg}
 
+\declaremodule[copyreg]{standard}{copy_reg}
 \modulesynopsis{Register \module{pickle} support functions.}
 
 
 The \module{copy_reg} module provides support for the
-\module{pickle}\refstmodindex{pickle} and
+\refmodule{pickle}\refstmodindex{pickle} and
-\module{cPickle}\refbimodindex{cPickle} modules.  The
+\refmodule{cPickle}\refbimodindex{cPickle} modules.  The
-\module{copy}\refstmodindex{copy} module is likely to use this in the
+\refmodule{copy}\refstmodindex{copy} module is likely to use this in the
 future as well.  It provides configuration information about object
 constructors which are not classes.  Such constructors may be factory
 functions or class instances.

Doc/lib/libexcs.tex

@@ -1,6 +1,6 @@
 \section{Built-in Exceptions}
-\declaremodule{standard}{exceptions}
 
+\declaremodule{standard}{exceptions}
 \modulesynopsis{Standard exceptions classes.}
 
 
@@ -224,7 +224,7 @@ Raised when an \keyword{assert} statement fails.
 \begin{excdesc}{OSError}
   %xref for os module
   This class is derived from \exception{EnvironmentError} and is used
-  primarily as the \module{os} module's \code{os.error} exception.
+  primarily as the \refmodule{os} module's \code{os.error} exception.
   See \exception{EnvironmentError} above for a description of the
   possible associated values.
   \versionadded{1.5.2}

Doc/lib/libformatter.tex

@@ -8,7 +8,7 @@
 
 This module supports two interface definitions, each with mulitple
 implementations.  The \emph{formatter} interface is used by the
-\class{HTMLParser} class of the \module{htmllib} module, and the
+\class{HTMLParser} class of the \refmodule{htmllib} module, and the
 \emph{writer} interface is required by the formatter interface.
 \withsubitem{(class in htmllib)}{\ttindex{HTMLParser}}
 

Doc/lib/libgetpass.tex

@@ -27,6 +27,6 @@ The \module{getpass} module provides two functions:
   \envvar{USER}, \envvar{LNAME} and \envvar{USERNAME}, in order, and
   returns the value of the first one which is set to a non-empty
   string.  If none are set, the login name from the password database
-  is returned on systems which support the \module{pwd} module,
+  is returned on systems which support the \refmodule{pwd} module,
   otherwise, an exception is raised.
 \end{funcdesc}

Doc/lib/libimageop.tex

@@ -1,14 +1,14 @@
 \section{\module{imageop} ---
-         Manipulate raw image data.}
+         Manipulate raw image data}
-\declaremodule{builtin}{imageop}
 
+\declaremodule{builtin}{imageop}
 \modulesynopsis{Manipulate raw image data.}
 
 
 The \module{imageop} module contains some useful operations on images.
 It operates on images consisting of 8 or 32 bit pixels stored in
 Python strings.  This is the same format as used by
-\function{gl.lrectwrite()} and the \module{imgfile} module.
+\function{gl.lrectwrite()} and the \refmodule{imgfile} module.
 
 The module defines the following variables and functions:
 

Doc/lib/libmarshal.tex

@@ -1,7 +1,7 @@
 \section{\module{marshal} ---
          Alternate Python object serialization}
-\declaremodule{builtin}{marshal}
 
+\declaremodule{builtin}{marshal}
 \modulesynopsis{Convert Python objects to streams of bytes and back
                 (with different constraints).}
 
@@ -21,7 +21,7 @@ does).\footnote{The name of this module stems from a bit of
 
 This is not a general ``persistency'' module.  For general persistency
 and transfer of Python objects through RPC calls, see the modules
-\module{pickle} and \module{shelve}.  The \module{marshal} module exists
+\refmodule{pickle} and \refmodule{shelve}.  The \module{marshal} module exists
 mainly to support reading and writing the ``pseudo-compiled'' code for
 Python modules of \file{.pyc} files.
 \refstmodindex{pickle}

Doc/lib/libparser.tex

@@ -59,7 +59,7 @@ non-terminal elements in the grammar always have a length greater than
 one.  The first element is an integer which identifies a production in
 the grammar.  These integers are given symbolic names in the C header
 file \file{Include/graminit.h} and the Python module
-\module{symbol}.  Each additional element of the sequence represents
+\refmodule{symbol}.  Each additional element of the sequence represents
 a component of the production as recognized in the input string: these
 are always sequences which have the same form as the parent.  An
 important aspect of this structure which should be noted is that
@@ -78,7 +78,7 @@ any child elements and the addition of the source text which was
 identified.  The example of the \keyword{if} keyword above is
 representative.  The various types of terminal symbols are defined in
 the C header file \file{Include/token.h} and the Python module
-\module{token}.
+\refmodule{token}.
 
 The AST objects are not required to support the functionality of this
 module, but are provided for three purposes: to allow an application
@@ -275,7 +275,7 @@ AST objects returned by \function{expr()}, \function{suite()} and
 \function{sequence2ast()} have no methods of their own.
 
 Ordered and equality comparisons are supported between AST objects.
-Pickling of AST objects (using the \module{pickle} module) is also
+Pickling of AST objects (using the \refmodule{pickle} module) is also
 supported.
 
 \begin{datadesc}{ASTType}
@@ -447,7 +447,7 @@ The numbers at the first element of each node in the tree are the node
 types; they map directly to terminal and non-terminal symbols in the
 grammar.  Unfortunately, they are represented as integers in the
 internal representation, and the Python structures generated do not
-change that.  However, the \module{symbol} and \module{token} modules
+change that.  However, the \refmodule{symbol} and \refmodule{token} modules
 provide symbolic names for the node types and dictionaries which map
 from the integers to the symbolic names for the node types.
 

Doc/lib/libpickle.tex

@@ -1,7 +1,7 @@
 \section{\module{pickle} ---
-         Python object serialization.}
+         Python object serialization}
-\declaremodule{standard}{pickle}
 
+\declaremodule{standard}{pickle}
 \modulesynopsis{Convert Python objects to streams of bytes and back.}
 
 \index{persistency}
@@ -25,20 +25,20 @@ a byte stream and it can transform the byte stream into an object with
 the same internal structure.  The most obvious thing to do with these
 byte streams is to write them onto a file, but it is also conceivable
 to send them across a network or store them in a database.  The module
-\module{shelve} provides a simple interface to pickle and unpickle
+\refmodule{shelve}\refstmodindex{shelve} provides a simple interface
-objects on ``dbm''-style database files.
+to pickle and unpickle objects on DBM-style database files.
-\refstmodindex{shelve}
+
 
 \strong{Note:} The \module{pickle} module is rather slow.  A
-reimplementation of the same algorithm in \C{}, which is up to 1000 times
+reimplementation of the same algorithm in C, which is up to 1000 times
-faster, is available as the \module{cPickle}\refbimodindex{cPickle}
+faster, is available as the \refmodule{cPickle}\refbimodindex{cPickle}
 module.  This has the same interface except that \code{Pickler} and
 \code{Unpickler} are factory functions, not classes (so they cannot be
 used as base classes for inheritance).
 
-Unlike the built-in module \module{marshal}, \module{pickle} handles
+Unlike the built-in module \refmodule{marshal}\refbimodindex{marshal},
-the following correctly:
+\module{pickle} handles the following correctly:
-\refbimodindex{marshal}
+
 
 \begin{itemize}
 
@@ -52,12 +52,10 @@ the following correctly:
 
 The data format used by \module{pickle} is Python-specific.  This has
 the advantage that there are no restrictions imposed by external
-standards such as XDR%
+standards such as
-\index{XDR}
+XDR\index{XDR}\index{External Data Representation} (which can't
-\index{External Data Representation}
+represent pointer sharing); however it means that non-Python programs
-(which can't represent pointer sharing); however
+may not be able to reconstruct pickled Python objects.
-it means that non-Python programs may not be able to reconstruct
-pickled Python objects.
 
 By default, the \module{pickle} data format uses a printable \ASCII{}
 representation.  This is slightly more voluminous than a binary
@@ -74,9 +72,9 @@ compatibility with the Python 1.4 pickle module.  In a future version,
 the default may change to binary.
 
 The \module{pickle} module doesn't handle code objects, which the
-\module{marshal} module does.  I suppose \module{pickle} could, and maybe
+\refmodule{marshal} module does.  I suppose \module{pickle} could, and maybe
 it should, but there's probably no great need for it right now (as
-long as \module{marshal} continues to be used for reading and writing
+long as \refmodule{marshal} continues to be used for reading and writing
 code objects), and at least this avoids the possibility of smuggling
 Trojan horses into a program.
 \refbimodindex{marshal}
@@ -126,8 +124,8 @@ object must be a dictionary and its items are assigned to the new
 instance's dictionary.  (If a class defines both \method{__getstate__()}
 and \method{__setstate__()}, the state object needn't be a dictionary
 --- these methods can do what they want.)  This protocol is also used
-by the shallow and deep copying operations defined in the \module{copy}
+by the shallow and deep copying operations defined in the
-module.\refstmodindex{copy}
+\refmodule{copy}\refstmodindex{copy} module.
 \ttindex{__getstate__()}
 \ttindex{__setstate__()}
 \ttindex{__dict__}
@@ -276,23 +274,23 @@ registration}
 
 
 \section{\module{cPickle} ---
-         Alternate implementation of \module{pickle}.}
+         Alternate implementation of \module{pickle}}
+
 \declaremodule{builtin}{cPickle}
-
 \modulesynopsis{Faster version of \module{pickle}, but not subclassable.}
+\moduleauthor{Jim Fulton}{jfulton@digicool.com}
+\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
 
 
-% This section was written by Fred L. Drake, Jr. <fdrake@acm.org>
-
 The \module{cPickle} module provides a similar interface and identical
-functionality as the \module{pickle} module, but can be up to 1000
+functionality as the \refmodule{pickle} module, but can be up to 1000
-times faster since it is implemented in \C{}.  The only other
+times faster since it is implemented in C.  The only other
 important difference to note is that \function{Pickler()} and
 \function{Unpickler()} are functions and not classes, and so cannot be
 subclassed.  This should not be an issue in most cases.
 
 The format of the pickle data is identical to that produced using the
-\module{pickle} module, so it is possible to use \module{pickle} and
+\refmodule{pickle} module, so it is possible to use \refmodule{pickle} and
 \module{cPickle} interchangably with existing pickles.
 
 (Since the pickle data format is actually a tiny stack-oriented

Doc/lib/libprofile.tex

@@ -459,7 +459,7 @@ integer (to select a count of lines), or a decimal fraction between
 0.0 and 1.0 inclusive (to select a percentage of lines), or a regular
 expression (to pattern match the standard name that is printed; as of
 Python 1.5b1, this uses the Perl-style regular expression syntax
-defined by the \module{re} module).  If several restrictions are
+defined by the \refmodule{re} module).  If several restrictions are
 provided, then they are applied sequentially.  For example:
 
 \begin{verbatim}

Doc/lib/libquopri.tex

@@ -10,7 +10,7 @@ This module performs quoted-printable transport encoding and decoding,
 as defined in \rfc{1521}: ``MIME (Multipurpose Internet Mail Extensions)
 Part One''.  The quoted-printable encoding is designed for data where
 there are relatively few nonprintable characters; the base64 encoding
-scheme available via the \module{base64} module is more compact if there
+scheme available via the \refmodule{base64} module is more compact if there
 are many such characters, as when sending a graphics file.
 \indexii{quoted-printable}{encoding}
 \index{MIME!quoted-printable encoding}

Doc/lib/libregsub.tex

@@ -1,23 +1,24 @@
 \section{\module{regsub} ---
-         Substitution and splitting operations that use regular expressions.}
+         String operations using regular expressions}
-\declaremodule{standard}{regsub}
 
-\modulesynopsis{Substitution and splitting operations that use regular expressions.}
+\declaremodule{standard}{regsub}
+\modulesynopsis{Substitution and splitting operations that use
+                regular expressions.}
 
 
 This module defines a number of functions useful for working with
-regular expressions (see built-in module \code{regex}).
+regular expressions (see built-in module \refmodule{regex}).
 
 Warning: these functions are not thread-safe.
 
 \strong{Obsolescence note:}
 This module is obsolete as of Python version 1.5; it is still being
 maintained because much existing code still uses it.  All new code in
-need of regular expressions should use the new \module{re} module, which
+need of regular expressions should use the new \refmodule{re} module, which
 supports the more powerful and regular Perl-style regular expressions.
 Existing code should be converted.  The standard library module
-\module{reconvert} helps in converting \code{regex} style regular
+\module{reconvert} helps in converting \refmodule{regex} style regular
-expressions to \module{re} style regular expressions.  (For more
+expressions to \refmodule{re} style regular expressions.  (For more
 conversion help, see Andrew Kuchling's\index{Kuchling, Andrew}
 ``regex-to-re HOWTO'' at
 \url{http://www.python.org/doc/howto/regex-to-re/}.)

Doc/lib/librexec.tex

@@ -1,7 +1,7 @@
 \section{\module{rexec} ---
-         Basic restricted execution framework.}
+         Restricted execution framework}
-\declaremodule{standard}{rexec}
 
+\declaremodule{standard}{rexec}
 \modulesynopsis{Basic restricted execution framework.}
 
 
@@ -26,7 +26,7 @@ Returns an instance of the \class{RExec} class.
 \var{hooks} is an instance of the \class{RHooks} class or a subclass of it.
 If it is omitted or \code{None}, the default \class{RHooks} class is
 instantiated.
-Whenever the \module{RExec} module searches for a module (even a
+Whenever the \module{rexec} module searches for a module (even a
 built-in one) or reads a module's code, it doesn't actually go out to
 the file system itself.  Rather, it calls methods of an \class{RHooks}
 instance that was passed to or created by its constructor.  (Actually,
@@ -85,7 +85,7 @@ the module is loaded) for unrestricted code.
 
 \begin{memberdesc}{ok_posix_names}
 % Should this be called ok_os_names?
-Contains the names of the functions in the \module{os} module which will be
+Contains the names of the functions in the \refmodule{os} module which will be
 available to programs running in the restricted environment.  The
 value for \class{RExec} is \code{('error',} \code{'fstat',}
 \code{'listdir',} \code{'lstat',} \code{'readlink',} \code{'stat',}
@@ -95,7 +95,7 @@ value for \class{RExec} is \code{('error',} \code{'fstat',}
 \end{memberdesc}
 
 \begin{memberdesc}{ok_sys_names}
-Contains the names of the functions and variables in the \module{sys}
+Contains the names of the functions and variables in the \refmodule{sys}
 module which will be available to programs running in the restricted
 environment.  The value for \class{RExec} is \code{('ps1',}
 \code{'ps2',} \code{'copyright',} \code{'version',} \code{'platform',}

Doc/lib/librfc822.tex

@@ -1,7 +1,7 @@
 \section{\module{rfc822} ---
-         Parse RFC 822 mail headers.}
+         Parse RFC 822 mail headers}
-\declaremodule{standard}{rfc822}
 
+\declaremodule{standard}{rfc822}
 \modulesynopsis{Parse \rfc{822} style mail headers.}
 
 This module defines a class, \class{Message}, which represents a
@@ -11,7 +11,7 @@ headers from a file.  This module also defines a helper class
 \class{AddressList} for parsing RFC822 addresses.
 
 Note that there's a separate module to read \UNIX{}, MH, and MMDF
-style mailbox files: \module{mailbox}\refstmodindex{mailbox}.
+style mailbox files: \refmodule{mailbox}\refstmodindex{mailbox}.
 
 \begin{classdesc}{Message}{file\optional{, seekable}}
 A \class{Message} instance is instantiated with an input object as

Doc/lib/libshelve.tex

@@ -1,7 +1,7 @@
 \section{\module{shelve} ---
          Python object persistency}
-\declaremodule{standard}{shelve}
 
+\declaremodule{standard}{shelve}
 \modulesynopsis{Python object persistency.}
 
 
@@ -71,5 +71,5 @@ requires knowledge about the database implementation used.
   \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}
   \seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.}
   \seemodule{pickle}{Object serialization used by \module{shelve}.}
-  \seemodule{cPickle}{High-performance version of \module{pickle}.}
+  \seemodule{cPickle}{High-performance version of \refmodule{pickle}.}
 \end{seealso}

Doc/lib/libstdwin.tex

@@ -14,11 +14,12 @@ of dialogs.  For most platforms, alternative, native solutions exist
 under X11, Win32 for Windows and Windows NT, and a collection of
 native toolkit interfaces for the Macintosh.
 
+
 \section{\module{stdwin} ---
          Platform-independent GUI System}
-\declaremodule{builtin}{stdwin}
 
-\modulesynopsis{Older GUI system for X11 and Macintosh}
+\declaremodule{builtin}{stdwin}
+\modulesynopsis{Older GUI system for X11 and Macintosh.}
 
 
 This module defines several new object types and functions that
@@ -57,7 +58,7 @@ the event applies, or
 if it applies to no window in particular;
 the third element is type-dependent.
 Names for event types and command codes are defined in the standard
-module \module{stdwinevent}.
+module \refmodule{stdwinevents}.
 \end{funcdesc}
 
 \begin{funcdesc}{pollevent}{}
@@ -232,7 +233,7 @@ Macintosh.
 
 \begin{funcdesc}{getselection}{i}
 Return X11 selection number \var{i.}  Selections are not cut buffers.
-Selection numbers are defined in module \module{stdwinevents}.
+Selection numbers are defined in module \refmodule{stdwinevents}.
 Selection \constant{WS_PRIMARY} is the \dfn{primary} selection (used
 by \program{xterm}, for instance); selection \constant{WS_SECONDARY}
 is the \dfn{secondary} selection; selection \constant{WS_CLIPBOARD} is
@@ -624,7 +625,7 @@ The following methods exist:
 Pass an arrow event to the text-edit block.
 The \var{code} must be one of \constant{WC_LEFT}, \constant{WC_RIGHT}, 
 \constant{WC_UP} or \constant{WC_DOWN} (see module
-\module{stdwinevents}).
+\refmodule{stdwinevents}).
 \end{methoddesc}
 
 \begin{methoddesc}[text-edit]{draw}{rect}
@@ -717,10 +718,11 @@ def main():
 main()
 \end{verbatim}
 
+
 \section{\module{stdwinevents} ---
          Constants for use with \module{stdwin}}
-\declaremodule{standard}{stdwinevents}
 
+\declaremodule{standard}{stdwinevents}
 \modulesynopsis{Constant definitions for use with \module{stdwin}}
 
 
@@ -735,15 +737,17 @@ Suggested usage is
 >>> 
 \end{verbatim}
 
+
 \section{\module{rect} ---
          Functions for use with \module{stdwin}}
-\declaremodule{standard}{rect}
 
-\modulesynopsis{Geometry-related utility function for use with \module{stdwin}}
+\declaremodule{standard}{rect}
+\modulesynopsis{Geometry-related utility function for use with
+                \module{stdwin}.}
 
 
 This module contains useful operations on rectangles.
-A rectangle is defined as in module \module{stdwin}:
+A rectangle is defined as in module \refmodule{stdwin}:
 a pair of points, where a point is a pair of integers.
 For example, the rectangle
 
@@ -753,7 +757,7 @@ For example, the rectangle
 
 is a rectangle whose left, top, right and bottom edges are 10, 20, 90
 and 80, respectively.  Note that the positive vertical axis points
-down (as in \module{stdwin}).
+down (as in \refmodule{stdwin}).
 
 The module defines the following objects:
 

Doc/lib/libstring.tex

@@ -1,13 +1,13 @@
 \section{\module{string} ---
-         Common string operations.}
+         Common string operations}
-\declaremodule{standard}{string}
 
+\declaremodule{standard}{string}
 \modulesynopsis{Common string operations.}
 
 
 This module defines some constants useful for checking character
 classes and some useful string functions.  See the module
-\module{re}\refstmodindex{re} for string functions based on regular
+\refmodule{re}\refstmodindex{re} for string functions based on regular
 expressions.
 
 The constants defined in this module are are:

Doc/lib/libsys.tex

@@ -1,7 +1,7 @@
 \section{\module{sys} ---
-         System-specific parameters and functions.}
+         System-specific parameters and functions}
-\declaremodule{builtin}{sys}
 
+\declaremodule{builtin}{sys}
 \modulesynopsis{Access system-specific parameters and functions.}
 
 This module provides access to some variables used or maintained by the
@@ -262,7 +262,7 @@ maximizing responsiveness as well as overhead.
   a \method{write()} method that takes a string argument.  (Changing these
   objects doesn't affect the standard I/O streams of processes
   executed by \function{os.popen()}, \function{os.system()} or the
-  \function{exec*()} family of functions in the \module{os} module.)
+  \function{exec*()} family of functions in the \refmodule{os} module.)
 \refstmodindex{os}
 \end{datadesc}
 

Doc/lib/libthreading.tex

@@ -6,7 +6,7 @@
 
 
 This module constructs higher-level threading interfaces on top of the 
-lower level \module{thread} module.
+lower level \refmodule{thread} module.
 
 This module is safe for use with \samp{from threading import *}.  It
 defines the following functions and objects:
@@ -91,7 +91,7 @@ All of the methods described below are executed atomically.
 A primitive lock is a synchronization primitive that is not owned
 by a particular thread when locked.  In Python, it is currently
 the lowest level synchronization primitive available, implemented
-directly by the \module{thread} extension module.
+directly by the \refmodule{thread} extension module.
 
 A primitive lock is in one of two states, ``locked'' or ``unlocked''.
 It is created in the unlocked state.  It has two basic methods,