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

Doc/Makefile

@@ -4,14 +4,23 @@ LIBDEST=$LIBDESTDIR/python
 DOCDESTDIR=$LIBDEST/doc
 DVIPS=	dvips -f
 
-all:	tut lib ref ext
+all:	tut.dvi lib.dvi ref.dvi ext.dvi
 
-tut:
+ext:	ext.dvi
+tut:	tut.dvi
+qua:	qua.dvi
+ref:	ref.dvi
+lib:	lib.dvi
+
+tut.dvi lib.dvi ref.dvi ext.dvi: myformat.sty fix_hack
+
+tut.dvi: tut.tex 
 	latex tut
 	latex tut
 	$(DVIPS) tut >tut.ps
 
-ref:
+ref.dvi: ref.tex ref1.tex ref2.tex ref3.tex ref4.tex ref5.tex ref6.tex \
+						     ref7.tex ref8.tex 
 	touch ref.ind
 	latex ref
 	./fix_hack ref.idx
@@ -19,7 +28,29 @@ ref:
 	latex ref
 	$(DVIPS) ref >ref.ps
 
-lib:
+# LaTeX source files for the Python Library Reference
+LIBFILES = lib.tex \
+libal.tex libamoeba.tex libarray.tex libaudio.tex libaudioop.tex \
+libbltin.tex \
+libcrypto.tex \
+libdbm.tex \
+libexcs.tex \
+libfcntl.tex libfl.tex libfm.tex libfuncs.tex \
+libgdbm.tex libgetopt.tex libgl.tex libgrp.tex \
+libimageop.tex libimgfile.tex libintro.tex \
+libjpeg.tex \
+libmac.tex libmain.tex libmarshal.tex libmath.tex \
+	libmd5.tex libmm.tex libmods.tex libmpz.tex \
+libobjs.tex libos.tex \
+libpanel.tex libposix.tex libposixfile.tex libppath.tex libpwd.tex \
+librand.tex libregex.tex libregsub.tex librgbimg.tex librotor.tex \
+libselect.tex libsgi.tex libsocket.tex libstd.tex libstdwin.tex \
+	libstring.tex libstruct.tex libsun.tex libsys.tex \
+libthread.tex libtime.tex libtypes.tex \
+libunix.tex \
+libwhrandom.tex
+
+lib.dvi: $(LIBFILES)
 	touch lib.ind
 	latex lib
 	./fix_hack lib.idx
@@ -27,7 +58,7 @@ lib:
 	latex lib
 	$(DVIPS) lib >lib.ps
 
-ext:
+ext.dvi: ext.tex 
 	touch ext.ind
 	latex ext
 	./fix_hack ext.idx
@@ -35,7 +66,7 @@ ext:
 	latex ext
 	$(DVIPS) ext >ext.ps
 
-qua:
+qua.dvi: qua.tex quabib.bib
 	latex qua
 	bibtex qua
 	latex qua

Doc/ext.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!
 
 % Tell \index to actually write the .idx file
 \makeindex
@@ -23,7 +23,7 @@
 \begin{abstract}
 
 \noindent
-This document describes how to write modules in C or C++ to extend the
+This document describes how to write modules in C or \Cpp{} to extend the
 Python interpreter.  It also describes how to use Python as an
 `embedded' language, and how extension modules can be loaded
 dynamically (at run time) into the interpreter, if the operating
@@ -43,7 +43,7 @@ system supports this feature.
 \pagenumbering{arabic}
 
 
-\chapter{Extending Python with C or C++ code}
+\chapter{Extending Python with C or \Cpp{} code}
 
 
 \section{Introduction}
@@ -57,12 +57,9 @@ excellent examples of how to create an extension.
 
 Extension modules can do two things that can't be done directly in
 Python: they can implement new data types (which are different from
-classes by the way), and they can make system calls or call C library
+classes, by the way), and they can make system calls or call C library
-functions.  Since the latter is usually the most important reason for
+functions.   We'll see how both types of extension are implemented by
-adding an extension, I'll concentrate on adding `wrappers' around C
+examining the code for a Python curses interface.
-library functions; the concrete example uses the wrapper for
-\code{system()} in module \code{posix}, found in (of course) the file
-\file{Modules/posixmodule.c}.
 
 Note: unless otherwise mentioned, all file references in this
 document are relative to the toplevel directory of the Python
@@ -112,7 +109,7 @@ in Python (here the single expression \code{'ls -l'}) to the arguments that
 are passed to the C function.  The C function always has two
 parameters, conventionally named \var{self} and \var{args}.  The
 \var{self} argument is used when the C function implements a builtin
-method --- this is advanced material and not covered in this document.
+method---this will be discussed later.
 In the example, \var{self} will always be a \code{NULL} pointer, since
 we are defining a function, not a method (this is done so that the
 interpreter doesn't have to understand two different types of C
@@ -780,9 +777,9 @@ which you keep references in your object, but you should not use
 \code{DECREF()} on your object.  You should use \code{DEL()} instead.
 
 
-\section{Writing extensions in C++}
+\section{Writing extensions in \Cpp{}}
 
-It is possible to write extension modules in C++.  Some restrictions
+It is possible to write extension modules in \Cpp{}.  Some restrictions
 apply: since the main program (the Python interpreter) is compiled and
 linked by the C compiler, global or static objects with constructors
 cannot be used.  All functions that will be called directly or
@@ -797,7 +794,7 @@ It is unnecessary to enclose the Python header files in
 
 Embedding Python is similar to extending it, but not quite.  The
 difference is that when you extend Python, the main program of the
-application is still the Python interpreter, while of you embed
+application is still the Python interpreter, while if you embed
 Python, the main program may have nothing to do with Python ---
 instead, some parts of the application occasionally call the Python
 interpreter to run some Python code.
@@ -820,13 +817,13 @@ A simple demo of embedding Python can be found in the directory
 \file{Demo/embed}.
 
 
-\section{Embedding Python in C++}
+\section{Embedding Python in \Cpp{}}
 
-It is also possible to embed Python in a C++ program; how this is done
+It is also possible to embed Python in a \Cpp{} program; precisely how this
-exactly will depend on the details of the C++ system used; in general
+is done will depend on the details of the \Cpp{} system used; in general you
-you will need to write the main program in C++, and use the C++
+will need to write the main program in \Cpp{}, and use the \Cpp{} compiler
-compiler to compile and link your program.  There is no need to
+to compile and link your program.  There is no need to recompile Python
-recompile Python itself with C++.
+itself using \Cpp{}.
 
 
 \chapter{Dynamic Loading}
@@ -860,7 +857,7 @@ loading.
 
 \subsection{Shared libraries}
 
-The following systems supports dynamic loading using shared libraries:
+The following systems support dynamic loading using shared libraries:
 SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!); and probably all
 systems derived from SVR4, or at least those SVR4 derivatives that
 support shared libraries (are there any that don't?).

Doc/ext/ext.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!
 
 % Tell \index to actually write the .idx file
 \makeindex
@@ -23,7 +23,7 @@
 \begin{abstract}
 
 \noindent
-This document describes how to write modules in C or C++ to extend the
+This document describes how to write modules in C or \Cpp{} to extend the
 Python interpreter.  It also describes how to use Python as an
 `embedded' language, and how extension modules can be loaded
 dynamically (at run time) into the interpreter, if the operating
@@ -43,7 +43,7 @@ system supports this feature.
 \pagenumbering{arabic}
 
 
-\chapter{Extending Python with C or C++ code}
+\chapter{Extending Python with C or \Cpp{} code}
 
 
 \section{Introduction}
@@ -57,12 +57,9 @@ excellent examples of how to create an extension.
 
 Extension modules can do two things that can't be done directly in
 Python: they can implement new data types (which are different from
-classes by the way), and they can make system calls or call C library
+classes, by the way), and they can make system calls or call C library
-functions.  Since the latter is usually the most important reason for
+functions.   We'll see how both types of extension are implemented by
-adding an extension, I'll concentrate on adding `wrappers' around C
+examining the code for a Python curses interface.
-library functions; the concrete example uses the wrapper for
-\code{system()} in module \code{posix}, found in (of course) the file
-\file{Modules/posixmodule.c}.
 
 Note: unless otherwise mentioned, all file references in this
 document are relative to the toplevel directory of the Python
@@ -112,7 +109,7 @@ in Python (here the single expression \code{'ls -l'}) to the arguments that
 are passed to the C function.  The C function always has two
 parameters, conventionally named \var{self} and \var{args}.  The
 \var{self} argument is used when the C function implements a builtin
-method --- this is advanced material and not covered in this document.
+method---this will be discussed later.
 In the example, \var{self} will always be a \code{NULL} pointer, since
 we are defining a function, not a method (this is done so that the
 interpreter doesn't have to understand two different types of C
@@ -780,9 +777,9 @@ which you keep references in your object, but you should not use
 \code{DECREF()} on your object.  You should use \code{DEL()} instead.
 
 
-\section{Writing extensions in C++}
+\section{Writing extensions in \Cpp{}}
 
-It is possible to write extension modules in C++.  Some restrictions
+It is possible to write extension modules in \Cpp{}.  Some restrictions
 apply: since the main program (the Python interpreter) is compiled and
 linked by the C compiler, global or static objects with constructors
 cannot be used.  All functions that will be called directly or
@@ -797,7 +794,7 @@ It is unnecessary to enclose the Python header files in
 
 Embedding Python is similar to extending it, but not quite.  The
 difference is that when you extend Python, the main program of the
-application is still the Python interpreter, while of you embed
+application is still the Python interpreter, while if you embed
 Python, the main program may have nothing to do with Python ---
 instead, some parts of the application occasionally call the Python
 interpreter to run some Python code.
@@ -820,13 +817,13 @@ A simple demo of embedding Python can be found in the directory
 \file{Demo/embed}.
 
 
-\section{Embedding Python in C++}
+\section{Embedding Python in \Cpp{}}
 
-It is also possible to embed Python in a C++ program; how this is done
+It is also possible to embed Python in a \Cpp{} program; precisely how this
-exactly will depend on the details of the C++ system used; in general
+is done will depend on the details of the \Cpp{} system used; in general you
-you will need to write the main program in C++, and use the C++
+will need to write the main program in \Cpp{}, and use the \Cpp{} compiler
-compiler to compile and link your program.  There is no need to
+to compile and link your program.  There is no need to recompile Python
-recompile Python itself with C++.
+itself using \Cpp{}.
 
 
 \chapter{Dynamic Loading}
@@ -860,7 +857,7 @@ loading.
 
 \subsection{Shared libraries}
 
-The following systems supports dynamic loading using shared libraries:
+The following systems support dynamic loading using shared libraries:
 SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!); and probably all
 systems derived from SVR4, or at least those SVR4 derivatives that
 support shared libraries (are there any that don't?).

Doc/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
 

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
 

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

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}
 

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
+(varying) step. The Intel/DVI ADPCM algorithm has been selected for
-use by the IMA, so may well become a standard.
+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}

Doc/lib/libcrypto.tex

@@ -3,3 +3,10 @@
 The modules described in this chapter implement various algorithms of
 a cryptographic nature.  They are available at the discretion of the
 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}

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
+  module \code{FCNTL}. The argument \code{\var{arg}} is optional, and
-  it is missing it is interpreted as the integer value \code{0}. When
+  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()}

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}

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}

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}
+\begin{funcdesc}{input}{\optional{prompt}}
-  Almost equivalent to \code{eval(raw_input(\var{prompt}))}.  As for
+  Almost equivalent to \code{eval(raw_input(\var{prompt}))}.  Like
-  \code{raw_input()}, the prompt argument is optional.  The difference is
+  \code{raw_input()}, the \var{prompt} argument is optional.  The difference
-  that a long input expression may be broken over multiple lines using the
+  is that a long input expression may be broken over multiple lines using
-  backslash convention.
+  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}
+\begin{funcdesc}{pow}{x\, y\optional{\, z}}
-  Return \var{x} to the power \var{y}.  The arguments must have
+  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}
+\begin{funcdesc}{raw_input}{\optional{prompt}}
-  The string argument is optional; if present, it is written to
+  If the \var{prompt} argument is present, it is written to standard output
-  standard
+  without a trailing newline.  The function then reads a line from input,
-  output without a trailing newline.  The function then reads a line
+  converts it to a string (stripping a trailing newline), and returns that.
-  from input, converts it to a string (stripping a trailing newline),
+  When \EOF{} is read, \code{EOFError} is raised. Example:
-  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

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

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}

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'}]

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,
+At any time you can ask for the ``final'' digest of the object. Internally,
-a temorary copy of the object is made and the digest is computed and
+a temporary copy of the object is made and the digest is computed and
-returned. Because of the copy, the digest operation is not desctructive
+returned. Because of the copy, the digest operation is not destructive
-for the object. Before a more exact description of the use, a small
+for the object. Before a more exact description of the module's use, a small
-example: to obtain the digest of the string \code{'abc'}, use \ldots
+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}
+\begin{funcdesc}{md5}{\optional{arg}}
-  Create a new md5-object. \var{arg} is optional: if present, an initial
+  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.

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}}
+ referring to.  The format is explained
- and \code{\var{whence}} are optional with the understanding that
+ below in a table.  The \var{len} argument specifies the length of the
- if \code{\var{start}} is used \code{\var{len}} becomes mandatory,
+ section that should be locked. The default is \code{0}. \var{start}
- and if \code{\var{whence}} is used \code{\var{len}} and
+ specifies the starting offset of the section, where the default is
- \code{\var{start}} become mandatory.  The format is explained
+ \code{0}.  The \var{whence} argument specifies where the offset is
- 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
  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,
+  \lineiii{?}{return the first lock conflicting with the requested lock,}{(1)}
-  or \code{None} if there is no conflict.}{(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:

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

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
+This module implements a rotor-based encryption algorithm, contributed by
-by Lance Ellinghouse.  Currently no further documentation is available
+Lance Ellinghouse.  The design is derived from the Enigma device, a machine
---- you are kindly advised to read the source...
+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?
+

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
+Return a string containing the hostname of the machine where 
-(e.g. \code{'voorn.cwi.nl'}).
+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}

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}{}

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}
+\begin{funcdesc}{find}{s\, sub\optional{\, start}}
-Return the lowest index in \var{s} not smaller than \var{i} where the
+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}.
+does not occur as a substring of \var{s} with index at least \var{start}.
-If \var{i} is omitted, it defaults to \code{0}.  If \var{i} is
+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}

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.

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)}.

Doc/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

Doc/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}
 

Doc/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
+(varying) step. The Intel/DVI ADPCM algorithm has been selected for
-use by the IMA, so may well become a standard.
+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}

Doc/libcrypto.tex

@@ -3,3 +3,10 @@
 The modules described in this chapter implement various algorithms of
 a cryptographic nature.  They are available at the discretion of the
 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}

Doc/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
+  module \code{FCNTL}. The argument \code{\var{arg}} is optional, and
-  it is missing it is interpreted as the integer value \code{0}. When
+  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()}

Doc/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}

Doc/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}

Doc/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}
+\begin{funcdesc}{input}{\optional{prompt}}
-  Almost equivalent to \code{eval(raw_input(\var{prompt}))}.  As for
+  Almost equivalent to \code{eval(raw_input(\var{prompt}))}.  Like
-  \code{raw_input()}, the prompt argument is optional.  The difference is
+  \code{raw_input()}, the \var{prompt} argument is optional.  The difference
-  that a long input expression may be broken over multiple lines using the
+  is that a long input expression may be broken over multiple lines using
-  backslash convention.
+  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}
+\begin{funcdesc}{pow}{x\, y\optional{\, z}}
-  Return \var{x} to the power \var{y}.  The arguments must have
+  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}
+\begin{funcdesc}{raw_input}{\optional{prompt}}
-  The string argument is optional; if present, it is written to
+  If the \var{prompt} argument is present, it is written to standard output
-  standard
+  without a trailing newline.  The function then reads a line from input,
-  output without a trailing newline.  The function then reads a line
+  converts it to a string (stripping a trailing newline), and returns that.
-  from input, converts it to a string (stripping a trailing newline),
+  When \EOF{} is read, \code{EOFError} is raised. Example:
-  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

Doc/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

Doc/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}

Doc/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'}]

Doc/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,
+At any time you can ask for the ``final'' digest of the object. Internally,
-a temorary copy of the object is made and the digest is computed and
+a temporary copy of the object is made and the digest is computed and
-returned. Because of the copy, the digest operation is not desctructive
+returned. Because of the copy, the digest operation is not destructive
-for the object. Before a more exact description of the use, a small
+for the object. Before a more exact description of the module's use, a small
-example: to obtain the digest of the string \code{'abc'}, use \ldots
+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}
+\begin{funcdesc}{md5}{\optional{arg}}
-  Create a new md5-object. \var{arg} is optional: if present, an initial
+  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.

Doc/libmods.tex

@@ -2,6 +2,6 @@
 
 The modules described in this chapter are built into the interpreter
 and considered part of Python's standard environment: they are always
-avaialble.\footnote{at least in theory --- it is possible to specify
+available.\footnote{at least in theory --- it is possible to specify
 at build time that one or more of these modules should be excluded,
 but it would be antisocial to do so.}

Doc/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}}
+ referring to.  The format is explained
- and \code{\var{whence}} are optional with the understanding that
+ below in a table.  The \var{len} argument specifies the length of the
- if \code{\var{start}} is used \code{\var{len}} becomes mandatory,
+ section that should be locked. The default is \code{0}. \var{start}
- and if \code{\var{whence}} is used \code{\var{len}} and
+ specifies the starting offset of the section, where the default is
- \code{\var{start}} become mandatory.  The format is explained
+ \code{0}.  The \var{whence} argument specifies where the offset is
- 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
  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,
+  \lineiii{?}{return the first lock conflicting with the requested lock,}{(1)}
-  or \code{None} if there is no conflict.}{(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:

Doc/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

Doc/librotor.tex

@@ -1,6 +1,105 @@
 \section{Built-in module \sectcode{rotor}}
 \bimodindex{rotor}
 
-This module implements a rotor-based encryption algorithm, contributed
+This module implements a rotor-based encryption algorithm, contributed by
-by Lance Ellinghouse.  Currently no further documentation is available
+Lance Ellinghouse.  The design is derived from the Enigma device, a machine
---- you are kindly advised to read the source...
+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?
+

Doc/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
+Return a string containing the hostname of the machine where 
-(e.g. \code{'voorn.cwi.nl'}).
+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}

Doc/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}{}

Doc/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}
+\begin{funcdesc}{find}{s\, sub\optional{\, start}}
-Return the lowest index in \var{s} not smaller than \var{i} where the
+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}.
+does not occur as a substring of \var{s} with index at least \var{start}.
-If \var{i} is omitted, it defaults to \code{0}.  If \var{i} is
+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}

Doc/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.

Doc/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)}.

Doc/myformat.sty

@@ -48,17 +48,10 @@
 }
 
 % Command to generate two index entries (using subentries)
-\newcommand{\indexii}[2]{
+\newcommand{\indexii}[2]{\index{#1!#2}\index{#2!#1}}
-\index{#1!#2}
-\index{#2!#1}
-}
 
 % And three entries (using only one level of subentries)
-\newcommand{\indexiii}[3]{
+\newcommand{\indexiii}[3]{\index{#1!#2 #3}\index{#2!#3, #1}\index{#3!#1 #2}}
-\index{#1!#2 #3}
-\index{#2!#3, #1}
-\index{#3!#1 #2}
-}
 
 % And four (again, using only one level of subentries)
 \newcommand{\indexiv}[4]{
@@ -113,6 +106,8 @@
 \newcommand{\funcline}[2]{\item[\code{#1(\varvars{#2})}]\ttindex{#1}}
 \newcommand{\funcdesc}[2]{\fulllineitems\funcline{#1}{#2}}
 \let\endfuncdesc\endfulllineitems
+\newcommand{\optional}[1]{{\ \Large[}{#1}\hspace{0.5mm}{\Large]}\ }
+
 
 % same for excdesc
 \newcommand{\excline}[1]{\item[\code{#1}]\ttindex{#1}}
@@ -145,6 +140,7 @@
 \newcommand{\UNIX}{{\sc Unix}}
 \newcommand{\ASCII}{{\sc ascii}}
 %\newcommand{\C}{{\bf C}}
+\newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}}
 \newcommand{\C}{C}
 \newcommand{\EOF}{{\sc eof}}
 

Doc/partparse.py

@@ -854,7 +854,7 @@ class Wobj:
 		self.data = self.data + data
 		
 # ignore these commands
-ignoredcommands = ('bcode', 'ecode')
+ignoredcommands = ('bcode', 'ecode', 'optional')
 # map commands like these to themselves as plaintext
 wordsselves = ('UNIX', 'ABC', 'C', 'ASCII', 'EOF')
 # \{ --> {,  \} --> }, etc

Doc/qua.tex

@@ -1,4 +1,5 @@
 \documentstyle[11pt]{article}
+\newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}}
 
 \title{
 Interactively Testing Remote Servers Using the Python Programming Language
@@ -550,7 +551,7 @@ x = Foo().init('Dr. Strangelove')
 
 Any user-defined class can be used as a base class to derive other
 classes.  However, built-in types like lists cannot be used as base
-classes.  (Incidentally, the same is true in C++ and Modula-3.)  A
+classes.  (Incidentally, the same is true in \Cpp{} and Modula-3.)  A
 class may override any method of its base classes.  Instance methods
 are first searched in the method list of their class, and then,
 recursively, in the method lists of their base class.  Initialization
@@ -668,7 +669,7 @@ C preprocessor, so we get macros, include files and conditional
 compilation for free.  AIL's type declaration syntax is a superset of
 C's, so the user can include C header files to use the types declared
 there as function parameter types --- which are declared using
-function prototypes as in C++ or Standard C\@.  It should be clear by
+function prototypes as in \Cpp{} or Standard C\@.  It should be clear by
 now that AIL's lexical conventions are also identical to C's.  The
 same is true for its expression syntax.
 
@@ -768,7 +769,7 @@ Since AIL class inheritance only means interface sharing, not
 implementation sharing, inheriting the same class multiple times is
 never a problem and has the same effect as inheriting it once.
 
-Note that the power of AIL classes doesn't go as far as C++.
+Note that the power of AIL classes doesn't go as far as \Cpp{}.
 AIL classes cannot have data members, and there is
 no mechanism for a server that implements a derived class
 to inherit the implementation of the base
@@ -1007,7 +1008,7 @@ value passed together with the exception is used to relay the error
 code returned by the server to the handler.  Since in general RPC
 failures are rare, Python test programs can usually ignore exceptions
 --- making the program simpler --- without the risk of occasional
-errors going undetected.  (I still remember the embarrassment a
+errors going undetected.  (I still remember the embarrassment of a
 hundredfold speed improvement reported, long, long, ago, about a new
 version of a certain program, which later had to be attributed to a
 benchmark that silently dumped core...)

Doc/ref.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!
 
 % Tell \index to actually write the .idx file
 \makeindex

Doc/ref/ref.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!
 
 % Tell \index to actually write the .idx file
 \makeindex

Doc/ref/ref1.tex

@@ -5,7 +5,7 @@ It is not intended as a tutorial.
 
 While I am trying to be as precise as possible, I chose to use English
 rather than formal specifications for everything except syntax and
-lexical analysis.  This should make the document better understandable
+lexical analysis.  This should make the document more understandable
 to the average reader, but will leave room for ambiguities.
 Consequently, if you were coming from Mars and tried to re-implement
 Python from this document alone, you might have to guess things and in

Doc/ref/ref2.tex

@@ -354,7 +354,8 @@ meaning:
 
 \begin{verbatim}
 (       )       [       ]       {       }
-;       ,       :       .       `       =
+,       :       .       "       `       '
+=	;
 \end{verbatim}
 
 The following printing ASCII characters are not used in Python.  Their
@@ -363,7 +364,7 @@ error:
 \index{ASCII}
 
 \begin{verbatim}
-@       $       "       ?
+@       $       ?
 \end{verbatim}
 
 They may be used by future versions of the language though!

Doc/ref/ref4.tex

@@ -9,7 +9,7 @@
 A {\em code block} is a piece of Python program text that can be
 executed as a unit, such as a module, a class definition or a function
 body.  Some code blocks (like modules) are executed only once, others
-(like function bodies) may be executed many times.  Code block may
+(like function bodies) may be executed many times.  Code blocks may
 textually contain other code blocks.  Code blocks may invoke other
 code blocks (that may or may not be textually contained in them) as
 part of their execution, e.g. by invoking (calling) a function.
@@ -72,7 +72,7 @@ When a global name is not found in the global name space, it is
 searched in the list of ``built-in'' names (which is actually the
 global name space of the module \verb@__builtin__@).  When a name is not
 found at all, the \verb@NameError@ exception is raised.%
-\footnote{If the code block contains \verb@exec@ statement or the
+\footnote{If the code block contains \verb@exec@ statements or the
 construct \verb@from ... import *@, the semantics of names not
 explicitly mentioned in a \verb@global@ statement change subtly: name
 lookup first searches the local name space, then the global one, then

Doc/ref/ref5.tex

@@ -133,7 +133,7 @@ tuples are immutable, the rules for literals apply here.
 (Note that tuples are not formed by the parentheses, but rather by use
 of the comma operator.  The exception is the empty tuple, for which
 parentheses {\em are} required --- allowing unparenthesized ``nothing''
-in expressions would causes ambiguities and allow common typos to
+in expressions would cause ambiguities and allow common typos to
 pass uncaught.)
 \index{comma}
 \indexii{tuple}{display}
@@ -677,7 +677,7 @@ comma-separated values is required.
 An expression (condition) list containing at least one comma yields a
 tuple.  The length of the tuple is the number of expressions
 (conditions) in the list.  The expressions (conditions) are evaluated
-from left to right.  (Conditions lists are used syntactically is a few
+from left to right.  (Condition lists are used syntactically is a few
 places where no tuple is constructed but a list of values is needed
 nevertheless.)
 \obindex{tuple}

Doc/ref1.tex

@@ -5,7 +5,7 @@ It is not intended as a tutorial.
 
 While I am trying to be as precise as possible, I chose to use English
 rather than formal specifications for everything except syntax and
-lexical analysis.  This should make the document better understandable
+lexical analysis.  This should make the document more understandable
 to the average reader, but will leave room for ambiguities.
 Consequently, if you were coming from Mars and tried to re-implement
 Python from this document alone, you might have to guess things and in

Doc/ref2.tex

@@ -354,7 +354,8 @@ meaning:
 
 \begin{verbatim}
 (       )       [       ]       {       }
-;       ,       :       .       `       =
+,       :       .       "       `       '
+=	;
 \end{verbatim}
 
 The following printing ASCII characters are not used in Python.  Their
@@ -363,7 +364,7 @@ error:
 \index{ASCII}
 
 \begin{verbatim}
-@       $       "       ?
+@       $       ?
 \end{verbatim}
 
 They may be used by future versions of the language though!

Doc/ref4.tex

@@ -9,7 +9,7 @@
 A {\em code block} is a piece of Python program text that can be
 executed as a unit, such as a module, a class definition or a function
 body.  Some code blocks (like modules) are executed only once, others
-(like function bodies) may be executed many times.  Code block may
+(like function bodies) may be executed many times.  Code blocks may
 textually contain other code blocks.  Code blocks may invoke other
 code blocks (that may or may not be textually contained in them) as
 part of their execution, e.g. by invoking (calling) a function.
@@ -72,7 +72,7 @@ When a global name is not found in the global name space, it is
 searched in the list of ``built-in'' names (which is actually the
 global name space of the module \verb@__builtin__@).  When a name is not
 found at all, the \verb@NameError@ exception is raised.%
-\footnote{If the code block contains \verb@exec@ statement or the
+\footnote{If the code block contains \verb@exec@ statements or the
 construct \verb@from ... import *@, the semantics of names not
 explicitly mentioned in a \verb@global@ statement change subtly: name
 lookup first searches the local name space, then the global one, then

Doc/ref5.tex

@@ -133,7 +133,7 @@ tuples are immutable, the rules for literals apply here.
 (Note that tuples are not formed by the parentheses, but rather by use
 of the comma operator.  The exception is the empty tuple, for which
 parentheses {\em are} required --- allowing unparenthesized ``nothing''
-in expressions would causes ambiguities and allow common typos to
+in expressions would cause ambiguities and allow common typos to
 pass uncaught.)
 \index{comma}
 \indexii{tuple}{display}
@@ -677,7 +677,7 @@ comma-separated values is required.
 An expression (condition) list containing at least one comma yields a
 tuple.  The length of the tuple is the number of expressions
 (conditions) in the list.  The expressions (conditions) are evaluated
-from left to right.  (Conditions lists are used syntactically is a few
+from left to right.  (Condition lists are used syntactically is a few
 places where no tuple is constructed but a list of values is needed
 nevertheless.)
 \obindex{tuple}

Doc/tools/partparse.py

@@ -854,7 +854,7 @@ class Wobj:
 		self.data = self.data + data
 		
 # ignore these commands
-ignoredcommands = ('bcode', 'ecode')
+ignoredcommands = ('bcode', 'ecode', 'optional')
 # map commands like these to themselves as plaintext
 wordsselves = ('UNIX', 'ABC', 'C', 'ASCII', 'EOF')
 # \{ --> {,  \} --> }, etc

Doc/tut.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!
 
 \begin{document}
 
@@ -1434,7 +1434,7 @@ If you quit from the Python interpreter and enter it again, the
 definitions you have made (functions and variables) are lost.
 Therefore, if you want to write a somewhat longer program, you are
 better off using a text editor to prepare the input for the interpreter
-and run it with that file as input instead.  This is known as creating a
+and running it with that file as input instead.  This is known as creating a
 {\em script}.  As your program gets longer, you may want to split it
 into several files for easier maintenance.  You may also want to use a
 handy function that you've written in several programs without copying
@@ -2028,7 +2028,7 @@ clauses or one {\tt finally} clause, but not both.
 
 Python's class mechanism adds classes to the language with a minimum
 of new syntax and semantics.  It is a mixture of the class mechanisms
-found in C++ and Modula-3.  As is true for modules, classes in Python
+found in \Cpp{} and Modula-3.  As is true for modules, classes in Python
 do not put an absolute barrier between definition and user, but rather
 rely on the politeness of the user not to ``break into the
 definition.''  The most important features of classes are retained
@@ -2037,7 +2037,7 @@ multiple base classes, a derived class can override any methods of its
 base class(es), a method can call the method of a base class with the
 same name.  Objects can contain an arbitrary amount of private data.
 
-In C++ terminology, all class members (including the data members) are
+In \Cpp{} terminology, all class members (including the data members) are
 {\em public}, and all member functions are {\em virtual}.  There are
 no special constructors or destructors.  As in Modula-3, there are no
 shorthands for referencing the object's members from its methods: the
@@ -2045,9 +2045,9 @@ method function is declared with an explicit first argument
 representing the object, which is provided implicitly by the call.  As
 in Smalltalk, classes themselves are objects, albeit in the wider
 sense of the word: in Python, all data types are objects.  This
-provides semantics for importing and renaming.  But, just like in C++
+provides semantics for importing and renaming.  But, just like in \Cpp{}
 or Modula-3, built-in types cannot be used as base classes for
-extension by the user.  Also, like in C++ but unlike in Modula-3, most
+extension by the user.  Also, like in \Cpp{} but unlike in Modula-3, most
 built-in operators with special syntax (arithmetic operators,
 subscripting etc.) can be redefined for class members.
 
@@ -2055,13 +2055,13 @@ subscripting etc.) can be redefined for class members.
 \section{A word about terminology}
 
 Lacking universally accepted terminology to talk about classes, I'll
-make occasional use of Smalltalk and C++ terms.  (I'd use Modula-3
+make occasional use of Smalltalk and \Cpp{} terms.  (I'd use Modula-3
 terms, since its object-oriented semantics are closer to those of
-Python than C++, but I expect that few readers have heard of it...)
+Python than \Cpp{}, but I expect that few readers have heard of it...)
 
 I also have to warn you that there's a terminological pitfall for
 object-oriented readers: the word ``object'' in Python does not
-necessarily mean a class instance.  Like C++ and Modula-3, and unlike
+necessarily mean a class instance.  Like \Cpp{} and Modula-3, and unlike
 Smalltalk, not all types in Python are classes: the basic built-in
 types like integers and lists aren't, and even somewhat more exotic
 types like files aren't.  However, {\em all} Python types share a little
@@ -2273,7 +2273,7 @@ understood by instance objects are attribute references.  There are
 two kinds of valid attribute names.
 
 The first I'll call {\em data attributes}.  These correspond to
-``instance variables'' in Smalltalk, and to ``data members'' in C++.
+``instance variables'' in Smalltalk, and to ``data members'' in \Cpp{}.
 Data attributes need not be declared; like local variables, they
 spring into existence when they are first assigned to.  For example,
 if \verb\x\ in the instance of \verb\MyClass\ created above, the
@@ -2549,7 +2549,7 @@ Derived classes may override methods of their base classes.  Because
 methods have no special privileges when calling other methods of the
 same object, a method of a base class that calls another method
 defined in the same base class, may in fact end up calling a method of
-a derived class that overrides it.  (For C++ programmers: all methods
+a derived class that overrides it.  (For \Cpp{} programmers: all methods
 in Python are ``virtual functions''.)
 
 An overriding method in a derived class may in fact want to extend
@@ -2643,14 +2643,14 @@ Python is an evolving language.  Since this tutorial was last
 thoroughly revised, several new features have been added to the
 language.  While ideally I should revise the tutorial to incorporate
 them in the mainline of the text, lack of time currently requires me
-to a more modest approach.  In this chapter I will briefly list the
+to follow a more modest approach.  In this chapter I will briefly list the
 most important improvements to the language and how you can use them
 to your benefit.
 
 \section{The Last Printed Expression}
 
 In interactive mode, the last printed expression is assigned to the
-variable \code\_\.  This means that when you are using Python as a
+variable \code\_.  This means that when you are using Python as a
 desk calculator, it is somewhat easier to continue calculations, for
 example:
 
@@ -2851,7 +2851,7 @@ This feature may be combined with the previous, e.g.
 
 \subsection{Lambda Forms}
 
-On popular demand, a few features commonly found in functional
+By popular demand, a few features commonly found in functional
 programming languages and Lisp have been added to Python.  With the
 \verb\lambda\ keyword, small anonymous functions can be created.
 Here's a function that returns the sum of its two arguments:

Doc/tut/tut.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!
 
 \begin{document}
 
@@ -1434,7 +1434,7 @@ If you quit from the Python interpreter and enter it again, the
 definitions you have made (functions and variables) are lost.
 Therefore, if you want to write a somewhat longer program, you are
 better off using a text editor to prepare the input for the interpreter
-and run it with that file as input instead.  This is known as creating a
+and running it with that file as input instead.  This is known as creating a
 {\em script}.  As your program gets longer, you may want to split it
 into several files for easier maintenance.  You may also want to use a
 handy function that you've written in several programs without copying
@@ -2028,7 +2028,7 @@ clauses or one {\tt finally} clause, but not both.
 
 Python's class mechanism adds classes to the language with a minimum
 of new syntax and semantics.  It is a mixture of the class mechanisms
-found in C++ and Modula-3.  As is true for modules, classes in Python
+found in \Cpp{} and Modula-3.  As is true for modules, classes in Python
 do not put an absolute barrier between definition and user, but rather
 rely on the politeness of the user not to ``break into the
 definition.''  The most important features of classes are retained
@@ -2037,7 +2037,7 @@ multiple base classes, a derived class can override any methods of its
 base class(es), a method can call the method of a base class with the
 same name.  Objects can contain an arbitrary amount of private data.
 
-In C++ terminology, all class members (including the data members) are
+In \Cpp{} terminology, all class members (including the data members) are
 {\em public}, and all member functions are {\em virtual}.  There are
 no special constructors or destructors.  As in Modula-3, there are no
 shorthands for referencing the object's members from its methods: the
@@ -2045,9 +2045,9 @@ method function is declared with an explicit first argument
 representing the object, which is provided implicitly by the call.  As
 in Smalltalk, classes themselves are objects, albeit in the wider
 sense of the word: in Python, all data types are objects.  This
-provides semantics for importing and renaming.  But, just like in C++
+provides semantics for importing and renaming.  But, just like in \Cpp{}
 or Modula-3, built-in types cannot be used as base classes for
-extension by the user.  Also, like in C++ but unlike in Modula-3, most
+extension by the user.  Also, like in \Cpp{} but unlike in Modula-3, most
 built-in operators with special syntax (arithmetic operators,
 subscripting etc.) can be redefined for class members.
 
@@ -2055,13 +2055,13 @@ subscripting etc.) can be redefined for class members.
 \section{A word about terminology}
 
 Lacking universally accepted terminology to talk about classes, I'll
-make occasional use of Smalltalk and C++ terms.  (I'd use Modula-3
+make occasional use of Smalltalk and \Cpp{} terms.  (I'd use Modula-3
 terms, since its object-oriented semantics are closer to those of
-Python than C++, but I expect that few readers have heard of it...)
+Python than \Cpp{}, but I expect that few readers have heard of it...)
 
 I also have to warn you that there's a terminological pitfall for
 object-oriented readers: the word ``object'' in Python does not
-necessarily mean a class instance.  Like C++ and Modula-3, and unlike
+necessarily mean a class instance.  Like \Cpp{} and Modula-3, and unlike
 Smalltalk, not all types in Python are classes: the basic built-in
 types like integers and lists aren't, and even somewhat more exotic
 types like files aren't.  However, {\em all} Python types share a little
@@ -2273,7 +2273,7 @@ understood by instance objects are attribute references.  There are
 two kinds of valid attribute names.
 
 The first I'll call {\em data attributes}.  These correspond to
-``instance variables'' in Smalltalk, and to ``data members'' in C++.
+``instance variables'' in Smalltalk, and to ``data members'' in \Cpp{}.
 Data attributes need not be declared; like local variables, they
 spring into existence when they are first assigned to.  For example,
 if \verb\x\ in the instance of \verb\MyClass\ created above, the
@@ -2549,7 +2549,7 @@ Derived classes may override methods of their base classes.  Because
 methods have no special privileges when calling other methods of the
 same object, a method of a base class that calls another method
 defined in the same base class, may in fact end up calling a method of
-a derived class that overrides it.  (For C++ programmers: all methods
+a derived class that overrides it.  (For \Cpp{} programmers: all methods
 in Python are ``virtual functions''.)
 
 An overriding method in a derived class may in fact want to extend
@@ -2643,14 +2643,14 @@ Python is an evolving language.  Since this tutorial was last
 thoroughly revised, several new features have been added to the
 language.  While ideally I should revise the tutorial to incorporate
 them in the mainline of the text, lack of time currently requires me
-to a more modest approach.  In this chapter I will briefly list the
+to follow a more modest approach.  In this chapter I will briefly list the
 most important improvements to the language and how you can use them
 to your benefit.
 
 \section{The Last Printed Expression}
 
 In interactive mode, the last printed expression is assigned to the
-variable \code\_\.  This means that when you are using Python as a
+variable \code\_.  This means that when you are using Python as a
 desk calculator, it is somewhat easier to continue calculations, for
 example:
 
@@ -2851,7 +2851,7 @@ This feature may be combined with the previous, e.g.
 
 \subsection{Lambda Forms}
 
-On popular demand, a few features commonly found in functional
+By popular demand, a few features commonly found in functional
 programming languages and Lisp have been added to Python.  With the
 \verb\lambda\ keyword, small anonymous functions can be created.
 Here's a function that returns the sum of its two arguments: