Lots of small corrections by Andrew Kuchling (plus all new rotor docs)

21 files changed, 195 insertions, 88 deletions

diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 72d09c4..a0cc009 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -9,7 +9,7 @@
 	E-mail: {\tt guido@cwi.nl}
 }
 
-\date{14 Jul 1994 \\ Release 1.0.3} % XXX update before release!
+\date{14 July 1994 \\ Release 1.0.3} % XXX update before release!
 
 \makeindex			% tell \index to actually write the .idx file
 
diff --git a/Doc/lib/libal.tex b/Doc/lib/libal.tex
index 708c54e..51a0312 100644
--- a/Doc/lib/libal.tex
+++ b/Doc/lib/libal.tex
@@ -23,7 +23,7 @@ documented upper limit.)
 Module \code{al} defines the following functions:
 
 \renewcommand{\indexsubitem}{(in module al)}
-\begin{funcdesc}{openport}{name\, direction\, config}
+\begin{funcdesc}{openport}{name\, direction\optional{\, config}}
 Equivalent to the C function ALopenport().  The name and direction
 arguments are strings.  The optional config argument is an opaque
 configuration object as returned by \code{al.newconfig()}.  The return
diff --git a/Doc/lib/libarray.tex b/Doc/lib/libarray.tex
index 21122f0..034ac32 100644
--- a/Doc/lib/libarray.tex
+++ b/Doc/lib/libarray.tex
@@ -20,14 +20,14 @@ which is a single character.  The following type codes are defined:
 \end{tableiii}
 
 The actual representation of values is determined by the machine
-architecture (strictly spoken, by the C implementation).  The actual
+architecture (strictly speaking, by the C implementation).  The actual
 size can be accessed through the \var{typecode} attribute.
 
 The module defines the following function:
 
 \renewcommand{\indexsubitem}{(in module array)}
 
-\begin{funcdesc}{array}{typecode\, initializer}
+\begin{funcdesc}{array}{typecode\optional{\, initializer}}
 Return a new array whose items are restricted by \var{typecode}, and
 initialized from the optional \var{initializer} value, which must be a
 list or a string.  The list or string is passed to the new array's
@@ -51,7 +51,7 @@ Append a new item with value \var{x} to the end of the array.
 
 \begin{funcdesc}{byteswap}{x}
 ``Byteswap'' all items of the array.  This is only supported for
-integer values.  It is useful when reading data ffrom a file written
+integer values.  It is useful when reading data from a file written
 on a machine with a different byte order.
 \end{funcdesc}
 
diff --git a/Doc/lib/libaudioop.tex b/Doc/lib/libaudioop.tex
index 734065a..61ab7fc 100644
--- a/Doc/lib/libaudioop.tex
+++ b/Doc/lib/libaudioop.tex
@@ -43,7 +43,7 @@ This function returns the average over all samples in the fragment.
 
 \begin{funcdesc}{avgpp}{fragment\, width}
 This function returns the average peak-peak value over all samples in
-the fragment. No filtering is done, so the useability of this routine
+the fragment. No filtering is done, so the usefulness of this routine
 is questionable.
 \end{funcdesc}
 
@@ -74,9 +74,9 @@ match \var{reference} as good as possible to a portion of
 (conceptually) does this by taking slices out of \var{fragment}, using
 \code{findfactor} to compute the best match, and minimizing the
 result.
-It returns a tuple \code{(\var{offset}, \var{factor})} with offset the
+It returns a tuple \code{(\var{offset}, \var{factor})} with \var{offset} the
 (integer) offset into \var{fragment} where the optimal match started
-and \var{factor} the floating-point factor as per findfactor.
+and \var{factor} the floating-point factor as per \code{findfactor}.
 \end{funcdesc}
 
 \begin{funcdesc}{findmax}{fragment\, length}
@@ -101,8 +101,8 @@ This function converts samples between 1-, 2- and 4-byte formats.
 This function converts samples to 4 bit Intel/DVI ADPCM encoding.
 ADPCM coding is an adaptive coding scheme, whereby each 4 bit number
 is the difference between one sample and the next, divided by a
-(varying) step. The Intel/DVI ADPCM algorythm has been selected for
-use by the IMA, so may well become a standard.
+(varying) step. The Intel/DVI ADPCM algorithm has been selected for
+use by the IMA, so it may well become a standard.
 
 \code{State} is a tuple containing the state of the coder. The coder
 returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the
@@ -120,7 +120,7 @@ discouraged.
 
 \begin{funcdesc}{lin2ulaw}{fragment\, width}
 This function converts samples in the audio fragment to U-LAW encoding
-and returns this as a python string. U-LAW is an audio encoding format
+and returns this as a Python string. U-LAW is an audio encoding format
 whereby you get a dynamic range of about 14 bits using only 8 bit
 samples. It is used by the Sun audio hardware, among others.
 \end{funcdesc}
diff --git a/Doc/lib/libcrypto.tex b/Doc/lib/libcrypto.tex
index 467bee4..302b50d 100644
--- a/Doc/lib/libcrypto.tex
+++ b/Doc/lib/libcrypto.tex
@@ -2,4 +2,11 @@
 
 The modules described in this chapter implement various algorithms of
 a cryptographic nature.  They are available at the discretion of the
-installation.
+installation. 
+\index{cryptography}
+
+%Hardcore cypherpunks will probably find the Python Cryptography Kit of
+%further interest; the package adds built-in modules for DES and IDEA
+%encryption, and provides a Python module for reading and decrypting PGP files.
+%\index{PGP}\indexii{DES}{cipher}\indexii{IDEA}{cipher}
+%\index{Python Cryptography Kit}
diff --git a/Doc/lib/libfcntl.tex b/Doc/lib/libfcntl.tex
index dd5212b..e361d5e 100644
--- a/Doc/lib/libfcntl.tex
+++ b/Doc/lib/libfcntl.tex
@@ -13,12 +13,12 @@ The module defines the following functions:
 
 \renewcommand{\indexsubitem}{(in module struct)}
 
-\begin{funcdesc}{fcntl}{fd\, op\, arg}
+\begin{funcdesc}{fcntl}{fd\, op\optional{\, arg}}
   Perform the requested operation on file descriptor \code{\var{fd}}.
   The operation is defined by \code{\var{op}} and is operating system
   dependent.  Typically these codes can be retrieved from the library
-  module \code{FCNTL}. The argument \code{\var{arg}} is optional.  When
-  it is missing it is interpreted as the integer value \code{0}. When
+  module \code{FCNTL}. The argument \code{\var{arg}} is optional, and
+  defaults to the integer value \code{0}.  When
   it is present, it can either be an integer value, or a string.  With
   the argument missing or an integer value, the return value of this
   function is the integer return value of the real \code{fcntl()}
diff --git a/Doc/lib/libfl.tex b/Doc/lib/libfl.tex
index b705a6b..5af1a04 100644
--- a/Doc/lib/libfl.tex
+++ b/Doc/lib/libfl.tex
@@ -78,11 +78,11 @@ Show a dialog box with a three-line message and YES and NO buttons.
 It returns \code{1} if the user pressed YES, \code{0} if NO.
 \end{funcdesc}
 
-\begin{funcdesc}{show_choice}{str1\, str2\, str3\, but1\, but2\, but3}
+\begin{funcdesc}{show_choice}{str1\, str2\, str3\, but1\optional{\, but2\,
+but3}}
 Show a dialog box with a three-line message and up to three buttons.
 It returns the number of the button clicked by the user
 (\code{1}, \code{2} or \code{3}).
-The \var{but2} and \var{but3} arguments are optional.
 \end{funcdesc}
 
 \begin{funcdesc}{show_input}{prompt\, default}
diff --git a/Doc/lib/libfm.tex b/Doc/lib/libfm.tex
index acbc05d..45d820c 100644
--- a/Doc/lib/libfm.tex
+++ b/Doc/lib/libfm.tex
@@ -77,7 +77,8 @@ Calls \code{fmgetcomment(\var{fh})}.
 Returns a tuple giving some pertinent data about this font.
 This is an interface to \code{fmgetfontinfo()}.
 The returned tuple contains the following numbers:
-\code{(\var{printermatched}, \var{fixed_width}, \var{xorig}, \var{yorig}, \var{xsize}, \var{ysize}, \var{height}, \var{nglyphs})}.
+{\tt(\var{printermatched}, \var{fixed_width}, \var{xorig}, \var{yorig},
+\var{xsize}, \var{ysize}, \var{height}, \var{nglyphs})}.
 \end{funcdesc}
 
 \begin{funcdesc}{getstrwidth}{string}
diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex
index 2c30c14..b37920d 100644
--- a/Doc/lib/libfuncs.tex
+++ b/Doc/lib/libfuncs.tex
@@ -78,7 +78,7 @@ exactly one argument.)
   \code{(math.floor(\var{a} / \var{b}), \var{a} \%{} \var{b})}.
 \end{funcdesc}
 
-\begin{funcdesc}{eval}{s\, globals\, locals}
+\begin{funcdesc}{eval}{s\optional{\, globals\optional{\, locals}}}
   The arguments are a string and two optional dictionaries.  The
   string argument is parsed and evaluated as a Python expression
   (technically speaking, a condition list) using the dictionaries as
@@ -156,11 +156,11 @@ removed.
   object.)
 \end{funcdesc}
 
-\begin{funcdesc}{input}{prompt}
-  Almost equivalent to \code{eval(raw_input(\var{prompt}))}.  As for
-  \code{raw_input()}, the prompt argument is optional.  The difference is
-  that a long input expression may be broken over multiple lines using the
-  backslash convention.
+\begin{funcdesc}{input}{\optional{prompt}}
+  Almost equivalent to \code{eval(raw_input(\var{prompt}))}.  Like
+  \code{raw_input()}, the \var{prompt} argument is optional.  The difference
+  is that a long input expression may be broken over multiple lines using
+  the backslash convention.
 \end{funcdesc}
 
 \begin{funcdesc}{int}{x}
@@ -206,7 +206,7 @@ any kind of sequence; the result is always a list.
   expression.
 \end{funcdesc}
 
-\begin{funcdesc}{open}{filename\, mode\, bufsize}
+\begin{funcdesc}{open}{filename\, \optional{mode\optional{\, bufsize}}}
   Return a new file object (described earlier under Built-in Types).
   The first two arguments are the same as for \code{stdio}'s
   \code{fopen()}: \var{filename} is the file name to be opened,
@@ -238,15 +238,17 @@ there's no reliable way to determine whether this is the case.}
   \code{chr()}.
 \end{funcdesc}
 
-\begin{funcdesc}{pow}{x\, y}
-  Return \var{x} to the power \var{y}.  The arguments must have
+\begin{funcdesc}{pow}{x\, y\optional{\, z}}
+  Return \var{x} to the power \var{y}; if \var{z} is present, $x^y \bmod z$
+  is returned.  The arguments must have
   numeric types.  With mixed operand types, the rules for binary
   arithmetic operators apply.  The effective operand type is also the
   type of the result; if the result is not expressible in this type, the
-  function raises an exception; e.g., \code{pow(2, -1)} is not allowed.
+  function raises an exception; e.g., \code{pow(2, -1)} or \code{pow(2,
+  35000)} is not allowed.
 \end{funcdesc}
 
-\begin{funcdesc}{range}{start\, end\, step}
+\begin{funcdesc}{range}{\optional{start\,} end\optional{\, step}}
   This is a versatile function to create lists containing arithmetic
   progressions.  It is most often used in \code{for} loops.  The
   arguments must be plain integers.  If the \var{step} argument is
@@ -278,13 +280,11 @@ there's no reliable way to determine whether this is the case.}
 \end{verbatim}\ecode
 \end{funcdesc}
 
-\begin{funcdesc}{raw_input}{prompt}
-  The string argument is optional; if present, it is written to
-  standard
-  output without a trailing newline.  The function then reads a line
-  from input, converts it to a string (stripping a trailing newline),
-  and returns that.  When \EOF{} is read, \code{EOFError} is raised.
-  Example:
+\begin{funcdesc}{raw_input}{\optional{prompt}}
+  If the \var{prompt} argument is present, it is written to standard output
+  without a trailing newline.  The function then reads a line from input,
+  converts it to a string (stripping a trailing newline), and returns that.
+  When \EOF{} is read, \code{EOFError} is raised. Example:
 
 \bcode\begin{verbatim}
 >>> s = raw_input('--> ')
@@ -295,7 +295,7 @@ there's no reliable way to determine whether this is the case.}
 \end{verbatim}\ecode
 \end{funcdesc}
 
-\begin{funcdesc}{reduce}{function\, list\, initializer}
+\begin{funcdesc}{reduce}{function\, list\optional{\, initializer}}
 Apply the binary \var{function} to the items of \var{list} so as to
 reduce the list to a single value.  E.g.,
 \code{reduce(lambda x, y: x*y, \var{list}, 1)} returns the product of
@@ -378,7 +378,7 @@ cannot normally be affected this way, but variables retrieved from
 other scopes can be.  This may change.}
 \end{funcdesc}
 
-\begin{funcdesc}{xrange}{start\, end\, step}
+\begin{funcdesc}{xrange}{\optional{start\,} end\optional{\, step}}
 This function is very similar to \code{range()}, but returns an
 ``xrange object'' instead of a list.  This is an opaque sequence type
 which yields the same values as the corresponding list, without
diff --git a/Doc/lib/libimageop.tex b/Doc/lib/libimageop.tex
index c1cdac4..4481e61 100644
--- a/Doc/lib/libimageop.tex
+++ b/Doc/lib/libimageop.tex
@@ -19,7 +19,7 @@ per pixel, etc.
 \begin{funcdesc}{crop}{image\, psize\, width\, height\, x0\, y0\, x1\, y1}
 This function takes the image in \code{image}, which should by
 \code{width} by \code{height} in size and consist of pixels of
-\code{psize} bytes, and returns the selected part of that image. \code{X0},
+\code{psize} bytes, and returns the selected part of that image. \code{x0},
 \code{y0}, \code{x1} and \code{y1} are like the \code{lrectread}
 parameters, i.e. the boundary is included in the new image.
 The new boundaries need not be inside the picture. Pixels that fall
diff --git a/Doc/lib/libimgfile.tex b/Doc/lib/libimgfile.tex
index 99efaf4..2da8d9d 100644
--- a/Doc/lib/libimgfile.tex
+++ b/Doc/lib/libimgfile.tex
@@ -29,7 +29,7 @@ the string. This format is suitable to pass to \code{gl.lrectwrite},
 for instance.
 \end{funcdesc}
 
-\begin{funcdesc}{readscaled}{file\, x\, y\, filter\, blur}
+\begin{funcdesc}{readscaled}{file\, x\, y\, filter\optional{\, blur}}
 This function is identical to read but it returns an image that is
 scaled to the given \var{x} and \var{y} sizes. If the \var{filter} and
 \var{blur} parameters are omitted scaling is done by
@@ -42,7 +42,7 @@ after scaling. The filter forms supported are \code{'impulse'},
 \code{'gaussian'}. If a filter is specified \var{blur} is an optional
 parameter specifying the blurriness of the filter. It defaults to \code{1.0}.
 
-Readscaled makes no
+\code{readscaled} makes no
 attempt to keep the aspect ratio correct, so that is the users'
 responsibility.
 \end{funcdesc}
diff --git a/Doc/lib/libjpeg.tex b/Doc/lib/libjpeg.tex
index d0c1604..a4e931f 100644
--- a/Doc/lib/libjpeg.tex
+++ b/Doc/lib/libjpeg.tex
@@ -4,7 +4,7 @@
 The module jpeg provides access to the jpeg compressor and
 decompressor written by the Independent JPEG Group. JPEG is a (draft?)
 standard for compressing pictures.  For details on jpeg or the
-Indepent JPEG Group software refer to the JPEG standard or the
+Independent JPEG Group software refer to the JPEG standard or the
 documentation provided with the software.
 
 The jpeg module defines these functions:
@@ -12,10 +12,10 @@ The jpeg module defines these functions:
 \renewcommand{\indexsubitem}{(in module jpeg)}
 \begin{funcdesc}{compress}{data\, w\, h\, b}
 Treat data as a pixmap of width w and height h, with b bytes per
-pixel.  The data is in sgi gl order, so the first pixel is in the
+pixel.  The data is in SGI GL order, so the first pixel is in the
 lower-left corner. This means that lrectread return data can
 immedeately be passed to compress.  Currently only 1 byte and 4 byte
-pixels are allowed, the former being treaded as greyscale and the
+pixels are allowed, the former being treated as greyscale and the
 latter as RGB color.  Compress returns a string that contains the
 compressed picture, in JFIF format.
 \end{funcdesc}
@@ -39,7 +39,7 @@ Set the quality of the compressed image to a
 value between \code{0} and \code{100} (default is \code{75}).  Compress only.
 
 \item[\code{'optimize'}]
-Perform huffman table optimization.  Takes longer, but results in
+Perform Huffman table optimization.  Takes longer, but results in
 smaller compressed image.  Compress only.
 
 \item[\code{'smooth'}]
diff --git a/Doc/lib/libmd5.tex b/Doc/lib/libmd5.tex
index 29e4b31..edaa727 100644
--- a/Doc/lib/libmd5.tex
+++ b/Doc/lib/libmd5.tex
@@ -2,16 +2,17 @@
 \bimodindex{md5}
 
 This module implements the interface to RSA's MD5 message digest
-algorithm (see also the file \file{md5.doc}). It's use is very
+algorithm (see also the file \file{md5.doc}). Its use is quite
 straightforward: use the function \code{md5} to create an
 \dfn{md5}-object. You can now ``feed'' this object with arbitrary
 strings.
 
-At any time you can ask the ``final'' digest of the object. Internally,
-a temorary copy of the object is made and the digest is computed and
-returned. Because of the copy, the digest operation is not desctructive
-for the object. Before a more exact description of the use, a small
-example: to obtain the digest of the string \code{'abc'}, use \ldots
+At any time you can ask for the ``final'' digest of the object. Internally,
+a temporary copy of the object is made and the digest is computed and
+returned. Because of the copy, the digest operation is not destructive
+for the object. Before a more exact description of the module's use, a small
+example will be helpful: 
+to obtain the digest of the string \code{'abc'}, use \ldots
 
 \bcode\begin{verbatim}
 >>> from md5 import md5
@@ -29,8 +30,8 @@ More condensed:
 \end{verbatim}\ecode
 
 \renewcommand{\indexsubitem}{(in module md5)}
-\begin{funcdesc}{md5}{arg}
-  Create a new md5-object. \var{arg} is optional: if present, an initial
+\begin{funcdesc}{md5}{\optional{arg}}
+  Create a new md5-object. If \var{arg} is present, an initial
   \code{update} method is called with \var{arg} as argument.
 \end{funcdesc}
 
@@ -42,6 +43,7 @@ An md5-object has the following methods:
 \end{funcdesc}
 
 \begin{funcdesc}{digest}{}
+% XXX The following is not quite clear; what does MD5Final do?
   Return the \dfn{digest} of this md5-object. Internally, a copy is made
   and the \C-function \code{MD5Final} is called. Finally the digest is
   returned.
diff --git a/Doc/lib/libposixfile.tex b/Doc/lib/libposixfile.tex
index 673ed6f..0d9cb32 100644
--- a/Doc/lib/libposixfile.tex
+++ b/Doc/lib/libposixfile.tex
@@ -47,17 +47,14 @@ The posixfile module defines the following functions:
 The posixfile object defines the following additional methods:
 
 \renewcommand{\indexsubitem}{(posixfile method)}
-\begin{funcdesc}{lock}{fmt\, len\, start\, whence}
+\begin{funcdesc}{lock}{fmt\, \optional{len\optional{\, start
+\optional{\, whence}}}}
  Lock the specified section of the file that the file object is
- referring to.  The arguments \code{\var{len}}, \code{\var{start}}
- and \code{\var{whence}} are optional with the understanding that
- if \code{\var{start}} is used \code{\var{len}} becomes mandatory,
- and if \code{\var{whence}} is used \code{\var{len}} and
- \code{\var{start}} become mandatory.  The format is explained
- below in a table. The length argument specifies the length of the
- section that should be locked. The default is \code{0}. The start
- specifies the starting offset of the section. The default is
- \code{0}.  The whence argument specifies where the offset is
+ referring to.  The format is explained
+ below in a table.  The \var{len} argument specifies the length of the
+ section that should be locked. The default is \code{0}. \var{start}
+ specifies the starting offset of the section, where the default is
+ \code{0}.  The \var{whence} argument specifies where the offset is
  relative to. It accepts one of the constants \code{SEEK_SET},
  \code{SEEK_CUR} or \code{SEEK_END}.  The default is \code{SEEK_SET}.
  For more information about the arguments refer to the fcntl
@@ -69,7 +66,7 @@ The posixfile object defines the following additional methods:
  to.  The new flags are ORed with the old flags, unless specified
  otherwise.  The format is explained below in a table.  Without
  arguments a string indicating the current flags is returned (this is
- the same as the '?'modifier).  For more information about the flags
+ the same as the '?' modifier).  For more information about the flags
  refer to the fcntl manual page on your system.
 \end{funcdesc}
 
@@ -105,8 +102,8 @@ In addition the following modifiers can be added to the format:
 
 \begin{tableiii}{|c|l|c|}{samp}{Modifier}{Meaning}{Notes}
   \lineiii{|}{wait until the lock has been granted}{}
-  \lineiii{?}{return the first lock conflicting with the requested lock,
-  or \code{None} if there is no conflict.}{(1)}
+  \lineiii{?}{return the first lock conflicting with the requested lock,}{(1)}
+  {}&{\hskip0.5cm or \code{None} if there is no conflict.}&{}\\
 \end{tableiii}
 
 Note:
@@ -138,7 +135,7 @@ Note:
 
 (1) The \code{!} and \code{=} modifiers are mutually exclusive.
 
-(2) This string represents the flag after they may have been altered
+(2) This string represents the flags after they may have been altered
 by the same call.
 
 Examples:
diff --git a/Doc/lib/libregex.tex b/Doc/lib/libregex.tex
index 13b3e20..f3df684 100644
--- a/Doc/lib/libregex.tex
+++ b/Doc/lib/libregex.tex
@@ -41,7 +41,7 @@ The module defines these functions, and an exception:
   anywhere!).
 \end{funcdesc}
 
-\begin{funcdesc}{compile}{pattern\, translate}
+\begin{funcdesc}{compile}{pattern\optional{\, translate}}
   Compile a regular expression pattern into a regular expression
   object, which can be used for matching using its \code{match} and
   \code{search} methods, described below.  The optional
@@ -82,7 +82,7 @@ expressions.)
   more information.
 \end{funcdesc}
 
-\begin{funcdesc}{symcomp}{pattern\, translate}
+\begin{funcdesc}{symcomp}{pattern\optional{\, translate}}
 This is like \code{compile}, but supports symbolic group names: if a
 parentheses-enclosed group begins with a group name in angular
 brackets, e.g. \code{'\e(<id>[a-z][a-z0-9]*\e)'}, the group can
@@ -108,7 +108,7 @@ equivalents.
 Compiled regular expression objects support these methods:
 
 \renewcommand{\indexsubitem}{(regex method)}
-\begin{funcdesc}{match}{string\, pos}
+\begin{funcdesc}{match}{string\optional{\, pos}}
   Return how many characters at the beginning of \var{string} match
   the compiled regular expression.  Return \code{-1} if the string
   does not match the pattern (this is different from a zero-length
@@ -122,7 +122,7 @@ Compiled regular expression objects support these methods:
   is to start.
 \end{funcdesc}
 
-\begin{funcdesc}{search}{string\, pos}
+\begin{funcdesc}{search}{string\optional{\, pos}}
   Return the first position in \var{string} that matches the regular
   expression \code{pattern}.  Return \code{-1} if no position in the
   string matches the pattern (this is different from a zero-length
diff --git a/Doc/lib/librotor.tex b/Doc/lib/librotor.tex
index 657d2ac..b931333 100644
--- a/Doc/lib/librotor.tex
+++ b/Doc/lib/librotor.tex
@@ -1,6 +1,105 @@
 \section{Built-in module \sectcode{rotor}}
 \bimodindex{rotor}
 
-This module implements a rotor-based encryption algorithm, contributed
-by Lance Ellinghouse.  Currently no further documentation is available
---- you are kindly advised to read the source...
+This module implements a rotor-based encryption algorithm, contributed by
+Lance Ellinghouse.  The design is derived from the Enigma device, a machine
+used during World War II to encipher messages.  A rotor is simply a
+permutation.  For example, if the character `A' is the origin of the rotor,
+then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on.
+To encrypt, we choose several different rotors, and set the origins of the
+rotors to known positions; their initial position is the ciphering key.  To
+encipher a character, we permute the original character by the first rotor,
+and then apply the second rotor's permutation to the result. We continue
+until we've applied all the rotors; the resulting character is our
+ciphertext.  We then change the origin of the final rotor by one position,
+from `A' to `B'; if the final rotor has made a complete revolution, then we
+rotate the next-to-last rotor by one position, and apply the same procedure
+recursively.  In other words, after enciphering one character, we advance
+the rotors in the same fashion as a car's odometer. Decoding works in the
+same way, except we reverse the permutations and apply them in the opposite
+order.
+\index{Ellinghouse, Lance}
+\indexii{Enigma}{cipher}
+
+The available functions in this module are:
+
+\renewcommand{\indexsubitem}{(in module rotor)}
+\begin{funcdesc}{newrotor}{key\optional{\, numrotors}}
+Returns a rotor object. \var{key} is a string containing the encryption key
+for the object; it can contain arbitrary binary data. The key will be used
+to randomly generate the rotor permutations and their initial positions.
+\var{numrotors} is the number of rotor permutations in the returned object;
+if it is omitted, a default value of 6 will be used.
+\end{funcdesc}
+
+Rotor objects have the following methods:
+
+\renewcommand{\indexsubitem}{(rotor method)}
+\begin{funcdesc}{setkey}{}
+Resets the rotor to its initial state.
+\end{funcdesc}
+
+\begin{funcdesc}{encrypt}{plaintext}
+Resets the rotor object to its initial state and encrypts \var{plaintext},
+returning a string containing the ciphertext.  The ciphertext is always the
+same length as the original plaintext.
+\end{funcdesc}
+
+\begin{funcdesc}{encryptmore}{plaintext}
+Encrypts \var{plaintext} without resetting the rotor object, and returns a
+string containing the ciphertext.
+\end{funcdesc}
+
+\begin{funcdesc}{decrypt}{ciphertext}
+Resets the rotor object to its initial state and decrypts \var{ciphertext},
+returning a string containing the ciphertext.  The plaintext string will
+always be the same length as the ciphertext.
+\end{funcdesc}
+
+\begin{funcdesc}{decryptmore}{ciphertext}
+Decrypts \var{ciphertext} without resetting the rotor object, and returns a
+string containing the ciphertext.
+\end{funcdesc}
+
+An example usage:
+\bcode\begin{verbatim}
+>>> import rotor
+>>> rt = rotor.newrotor('key', 12)
+>>> rt.encrypt('bar')
+'\2534\363'
+>>> rt.encryptmore('bar')
+'\357\375$'
+>>> rt.encrypt('bar')
+'\2534\363'
+>>> rt.decrypt('\2534\363')
+'bar'
+>>> rt.decryptmore('\357\375$')
+'bar'
+>>> rt.decrypt('\357\375$')
+'l(\315'
+>>> del rt
+\end{verbatim}\ecode
+
+The module's code is not an exact simulation of the original Enigma device;
+it implements the rotor encryption scheme differently from the original. The
+most important difference is that in the original Enigma, there were only 5
+or 6 different rotors in existence, and they were applied twice to each
+character; the cipher key was the order in which they were placed in the
+machine.  The Python rotor module uses the supplied key to initialize a
+random number generator; the rotor permutations and their initial positions
+are then randomly generated.  The original device only enciphered the
+letters of the alphabet, while this module can handle any 8-bit binary data;
+it also produces binary output.  This module can also operate with an
+arbitrary number of rotors.
+
+The original Enigma cipher was broken in 1944. % XXX: Is this right?
+The version implemented here is probably a good deal more difficult to crack
+(especially if you use many rotors), but it won't be impossible for
+a truly skilful and determined attacker to break the cipher.  So if you want
+to keep the NSA out of your files, this rotor cipher may well be unsafe, but
+for discouraging casual snooping through your files, it will probably be
+just fine, and may be somewhat safer than using the Unix \file{crypt}
+command.
+\index{National Security Agency}\index{crypt(1)}
+% XXX How were Unix commands represented in the docs?
+
diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex
index f051be8..244ef67 100644
--- a/Doc/lib/libsocket.tex
+++ b/Doc/lib/libsocket.tex
@@ -76,8 +76,10 @@ is an IP address itself it is returned unchanged.
 \end{funcdesc}
 
 \begin{funcdesc}{gethostname}{}
-Return the current host's canonical name, as a string
-(e.g. \code{'voorn.cwi.nl'}).
+Return a string containing the hostname of the machine where 
+the Python interpreter is currently executing.  If you want to know the
+current machine's IP address, use
+\code{socket.gethostbyname( socket.gethostname() )} instead.
 \end{funcdesc}
 
 \begin{funcdesc}{getservbyname}{servicename\, protocolname}
diff --git a/Doc/lib/libstdwin.tex b/Doc/lib/libstdwin.tex
index 12771c9..df37707 100644
--- a/Doc/lib/libstdwin.tex
+++ b/Doc/lib/libstdwin.tex
@@ -102,7 +102,7 @@ Return the screen size in millimeters.
 \begin{funcdesc}{fetchcolor}{colorname}
 Return the pixel value corresponding to the given color name.
 Return the default foreground color for unknown color names.
-Hint: the following code tests wheter you are on a machine that
+Hint: the following code tests whether you are on a machine that
 supports more than two colors:
 \bcode\begin{verbatim}
 if stdwin.fetchcolor('black') <> \
@@ -372,7 +372,7 @@ for the meaning of
 \var{i}.)
 Return true if it succeeds.
 If  succeeds, the window ``owns'' the selection until
-(a) another applications takes ownership of the selection; or
+(a) another application takes ownership of the selection; or
 (b) the window is deleted; or
 (c) the application clears ownership by calling
 \code{stdwin.resetselection(\var{i})}.
@@ -571,7 +571,6 @@ window.  When an object to be drawn falls partly outside the clipping
 region, the set of pixels drawn is the intersection of the clipping
 region and the set of pixels that would be drawn by the same operation
 in the absence of a clipping region.
-clipping region 
 \end{funcdesc}
 
 \begin{funcdesc}{noclip}{}
diff --git a/Doc/lib/libstring.tex b/Doc/lib/libstring.tex
index bf7ad09..7d99a36 100644
--- a/Doc/lib/libstring.tex
+++ b/Doc/lib/libstring.tex
@@ -108,24 +108,24 @@ This doesn't understand other non-printing characters or escape
 sequences.
 \end{funcdesc}
 
-\begin{funcdesc}{find}{s\, sub\, i}
-Return the lowest index in \var{s} not smaller than \var{i} where the
+\begin{funcdesc}{find}{s\, sub\optional{\, start}}
+Return the lowest index in \var{s} not smaller than \var{start} where the
 substring \var{sub} is found.  Return \code{-1} when \var{sub}
-does not occur as a substring of \var{s} with index at least \var{i}.
-If \var{i} is omitted, it defaults to \code{0}.  If \var{i} is
+does not occur as a substring of \var{s} with index at least \var{start}.
+If \var{start} is omitted, it defaults to \code{0}.  If \var{start} is
 negative, \code{len(\var{s})} is added.
 \end{funcdesc}
 
-\begin{funcdesc}{rfind}{s\, sub\, i}
+\begin{funcdesc}{rfind}{s\, sub\optional{\, start}}
 Like \code{find} but finds the highest index.
 \end{funcdesc}
 
-\begin{funcdesc}{index}{s\, sub\, i}
+\begin{funcdesc}{index}{s\, sub\optional{\, start}}
 Like \code{find} but raise \code{index_error} when the substring is
 not found.
 \end{funcdesc}
 
-\begin{funcdesc}{rindex}{s\, sub\, i}
+\begin{funcdesc}{rindex}{s\, sub\optional{\, start}}
 Like \code{rfind} but raise \code{index_error} when the substring is
 not found.
 \end{funcdesc}
diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex
index ba6b896..cd2c646 100644
--- a/Doc/lib/libsys.tex
+++ b/Doc/lib/libsys.tex
@@ -57,7 +57,7 @@ It is always available.
   exception is not handled and the interpreter prints an error message
   and a stack traceback.  Their intended use is to allow an interactive
   user to import a debugger module and engage in post-mortem debugging
-  without having to re-execute the command that cause the error (which
+  without having to re-execute the command that caused the error (which
   may be hard to reproduce).  The meaning of the variables is the same
   as that of \code{exc_type}, \code{exc_value} and \code{exc_tracaback},
   respectively.
diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex
index fe8b7dc..7e83f4e 100644
--- a/Doc/lib/libtime.tex
+++ b/Doc/lib/libtime.tex
@@ -10,7 +10,7 @@ An explanation of some terminology and conventions is in order.
 \begin{itemize}
 
 \item
-The ``epoch'' is the point where the time starts.  On January 1st that
+The ``epoch'' is the point where the time starts.  On January 1st of that
 year, at 0 hours, the ``time since the epoch'' is zero.  For UNIX, the
 epoch is 1970.  To find out what the epoch is, look at the first
 element of \code{gmtime(0)}.