Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
diff --git a/Doc/Makefile b/Doc/Makefile
index fbf62f6..4b04cc3 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -4,14 +4,23 @@
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 @@
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 @@
latex lib
$(DVIPS) lib >lib.ps
-ext:
+ext.dvi: ext.tex
touch ext.ind
latex ext
./fix_hack ext.idx
@@ -35,7 +66,7 @@
latex ext
$(DVIPS) ext >ext.ps
-qua:
+qua.dvi: qua.tex quabib.bib
latex qua
bibtex qua
latex qua
diff --git a/Doc/ext.tex b/Doc/ext.tex
index a7d4221..48cf0d1 100644
--- a/Doc/ext.tex
+++ b/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 @@
\pagenumbering{arabic}
-\chapter{Extending Python with C or C++ code}
+\chapter{Extending Python with C or \Cpp{} code}
\section{Introduction}
@@ -57,12 +57,9 @@
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
-functions. Since the latter is usually the most important reason for
-adding an extension, I'll concentrate on adding `wrappers' around C
-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}.
+classes, by the way), and they can make system calls or call C library
+functions. We'll see how both types of extension are implemented by
+examining the code for a Python curses interface.
Note: unless otherwise mentioned, all file references in this
document are relative to the toplevel directory of the Python
@@ -112,7 +109,7 @@
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 @@
\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 @@
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 @@
\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
-exactly will depend on the details of the C++ system used; in general
-you will need to write the main program in C++, and use the C++
-compiler to compile and link your program. There is no need to
-recompile Python itself with C++.
+It is also possible to embed Python in a \Cpp{} program; precisely how this
+is done will depend on the details of the \Cpp{} system used; in general you
+will need to write the main program in \Cpp{}, and use the \Cpp{} compiler
+to compile and link your program. There is no need to recompile Python
+itself using \Cpp{}.
\chapter{Dynamic Loading}
@@ -860,7 +857,7 @@
\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?).
diff --git a/Doc/ext/ext.tex b/Doc/ext/ext.tex
index a7d4221..48cf0d1 100644
--- a/Doc/ext/ext.tex
+++ b/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 @@
\pagenumbering{arabic}
-\chapter{Extending Python with C or C++ code}
+\chapter{Extending Python with C or \Cpp{} code}
\section{Introduction}
@@ -57,12 +57,9 @@
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
-functions. Since the latter is usually the most important reason for
-adding an extension, I'll concentrate on adding `wrappers' around C
-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}.
+classes, by the way), and they can make system calls or call C library
+functions. We'll see how both types of extension are implemented by
+examining the code for a Python curses interface.
Note: unless otherwise mentioned, all file references in this
document are relative to the toplevel directory of the Python
@@ -112,7 +109,7 @@
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 @@
\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 @@
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 @@
\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
-exactly will depend on the details of the C++ system used; in general
-you will need to write the main program in C++, and use the C++
-compiler to compile and link your program. There is no need to
-recompile Python itself with C++.
+It is also possible to embed Python in a \Cpp{} program; precisely how this
+is done will depend on the details of the \Cpp{} system used; in general you
+will need to write the main program in \Cpp{}, and use the \Cpp{} compiler
+to compile and link your program. There is no need to recompile Python
+itself using \Cpp{}.
\chapter{Dynamic Loading}
@@ -860,7 +857,7 @@
\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?).
diff --git a/Doc/lib.tex b/Doc/lib.tex
index 72d09c4..a0cc009 100644
--- a/Doc/lib.tex
+++ b/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
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 72d09c4..a0cc009 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -9,7 +9,7 @@
E-mail: {\tt guido@cwi.nl}
}
-\date{14 Jul 1994 \\ Release 1.0.3} % XXX update before release!
+\date{14 July 1994 \\ Release 1.0.3} % XXX update before release!
\makeindex % tell \index to actually write the .idx file
diff --git a/Doc/lib/libal.tex b/Doc/lib/libal.tex
index 708c54e..51a0312 100644
--- a/Doc/lib/libal.tex
+++ b/Doc/lib/libal.tex
@@ -23,7 +23,7 @@
Module \code{al} defines the following functions:
\renewcommand{\indexsubitem}{(in module al)}
-\begin{funcdesc}{openport}{name\, direction\, config}
+\begin{funcdesc}{openport}{name\, direction\optional{\, config}}
Equivalent to the C function ALopenport(). The name and direction
arguments are strings. The optional config argument is an opaque
configuration object as returned by \code{al.newconfig()}. The return
diff --git a/Doc/lib/libarray.tex b/Doc/lib/libarray.tex
index 21122f0..034ac32 100644
--- a/Doc/lib/libarray.tex
+++ b/Doc/lib/libarray.tex
@@ -20,14 +20,14 @@
\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 @@
\begin{funcdesc}{byteswap}{x}
``Byteswap'' all items of the array. This is only supported for
-integer values. It is useful when reading data ffrom a file written
+integer values. It is useful when reading data from a file written
on a machine with a different byte order.
\end{funcdesc}
diff --git a/Doc/lib/libaudioop.tex b/Doc/lib/libaudioop.tex
index 734065a..61ab7fc 100644
--- a/Doc/lib/libaudioop.tex
+++ b/Doc/lib/libaudioop.tex
@@ -43,7 +43,7 @@
\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 @@
(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 to 4 bit Intel/DVI ADPCM encoding.
ADPCM coding is an adaptive coding scheme, whereby each 4 bit number
is the difference between one sample and the next, divided by a
-(varying) step. The Intel/DVI ADPCM algorythm has been selected for
-use by the IMA, so may well become a standard.
+(varying) step. The Intel/DVI ADPCM algorithm has been selected for
+use by the IMA, so it may well become a standard.
\code{State} is a tuple containing the state of the coder. The coder
returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the
@@ -120,7 +120,7 @@
\begin{funcdesc}{lin2ulaw}{fragment\, width}
This function converts samples in the audio fragment to U-LAW encoding
-and returns this as a python string. U-LAW is an audio encoding format
+and returns this as a Python string. U-LAW is an audio encoding format
whereby you get a dynamic range of about 14 bits using only 8 bit
samples. It is used by the Sun audio hardware, among others.
\end{funcdesc}
diff --git a/Doc/lib/libcrypto.tex b/Doc/lib/libcrypto.tex
index 467bee4..302b50d 100644
--- a/Doc/lib/libcrypto.tex
+++ b/Doc/lib/libcrypto.tex
@@ -2,4 +2,11 @@
The modules described in this chapter implement various algorithms of
a cryptographic nature. They are available at the discretion of the
-installation.
+installation.
+\index{cryptography}
+
+%Hardcore cypherpunks will probably find the Python Cryptography Kit of
+%further interest; the package adds built-in modules for DES and IDEA
+%encryption, and provides a Python module for reading and decrypting PGP files.
+%\index{PGP}\indexii{DES}{cipher}\indexii{IDEA}{cipher}
+%\index{Python Cryptography Kit}
diff --git a/Doc/lib/libfcntl.tex b/Doc/lib/libfcntl.tex
index dd5212b..e361d5e 100644
--- a/Doc/lib/libfcntl.tex
+++ b/Doc/lib/libfcntl.tex
@@ -13,12 +13,12 @@
\renewcommand{\indexsubitem}{(in module struct)}
-\begin{funcdesc}{fcntl}{fd\, op\, arg}
+\begin{funcdesc}{fcntl}{fd\, op\optional{\, arg}}
Perform the requested operation on file descriptor \code{\var{fd}}.
The operation is defined by \code{\var{op}} and is operating system
dependent. Typically these codes can be retrieved from the library
- module \code{FCNTL}. The argument \code{\var{arg}} is optional. When
- it is missing it is interpreted as the integer value \code{0}. When
+ module \code{FCNTL}. The argument \code{\var{arg}} is optional, and
+ defaults to the integer value \code{0}. When
it is present, it can either be an integer value, or a string. With
the argument missing or an integer value, the return value of this
function is the integer return value of the real \code{fcntl()}
diff --git a/Doc/lib/libfl.tex b/Doc/lib/libfl.tex
index b705a6b..5af1a04 100644
--- a/Doc/lib/libfl.tex
+++ b/Doc/lib/libfl.tex
@@ -78,11 +78,11 @@
It returns \code{1} if the user pressed YES, \code{0} if NO.
\end{funcdesc}
-\begin{funcdesc}{show_choice}{str1\, str2\, str3\, but1\, but2\, but3}
+\begin{funcdesc}{show_choice}{str1\, str2\, str3\, but1\optional{\, but2\,
+but3}}
Show a dialog box with a three-line message and up to three buttons.
It returns the number of the button clicked by the user
(\code{1}, \code{2} or \code{3}).
-The \var{but2} and \var{but3} arguments are optional.
\end{funcdesc}
\begin{funcdesc}{show_input}{prompt\, default}
diff --git a/Doc/lib/libfm.tex b/Doc/lib/libfm.tex
index acbc05d..45d820c 100644
--- a/Doc/lib/libfm.tex
+++ b/Doc/lib/libfm.tex
@@ -77,7 +77,8 @@
Returns a tuple giving some pertinent data about this font.
This is an interface to \code{fmgetfontinfo()}.
The returned tuple contains the following numbers:
-\code{(\var{printermatched}, \var{fixed_width}, \var{xorig}, \var{yorig}, \var{xsize}, \var{ysize}, \var{height}, \var{nglyphs})}.
+{\tt(\var{printermatched}, \var{fixed_width}, \var{xorig}, \var{yorig},
+\var{xsize}, \var{ysize}, \var{height}, \var{nglyphs})}.
\end{funcdesc}
\begin{funcdesc}{getstrwidth}{string}
diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex
index 2c30c14..b37920d 100644
--- a/Doc/lib/libfuncs.tex
+++ b/Doc/lib/libfuncs.tex
@@ -78,7 +78,7 @@
\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 @@
object.)
\end{funcdesc}
-\begin{funcdesc}{input}{prompt}
- Almost equivalent to \code{eval(raw_input(\var{prompt}))}. As for
- \code{raw_input()}, the prompt argument is optional. The difference is
- that a long input expression may be broken over multiple lines using the
- backslash convention.
+\begin{funcdesc}{input}{\optional{prompt}}
+ Almost equivalent to \code{eval(raw_input(\var{prompt}))}. Like
+ \code{raw_input()}, the \var{prompt} argument is optional. The difference
+ is that a long input expression may be broken over multiple lines using
+ the backslash convention.
\end{funcdesc}
\begin{funcdesc}{int}{x}
@@ -206,7 +206,7 @@
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 @@
\code{chr()}.
\end{funcdesc}
-\begin{funcdesc}{pow}{x\, y}
- Return \var{x} to the power \var{y}. The arguments must have
+\begin{funcdesc}{pow}{x\, y\optional{\, z}}
+ Return \var{x} to the power \var{y}; if \var{z} is present, $x^y \bmod z$
+ is returned. The arguments must have
numeric types. With mixed operand types, the rules for binary
arithmetic operators apply. The effective operand type is also the
type of the result; if the result is not expressible in this type, the
- function raises an exception; e.g., \code{pow(2, -1)} is not allowed.
+ function raises an exception; e.g., \code{pow(2, -1)} or \code{pow(2,
+ 35000)} is not allowed.
\end{funcdesc}
-\begin{funcdesc}{range}{start\, end\, step}
+\begin{funcdesc}{range}{\optional{start\,} end\optional{\, step}}
This is a versatile function to create lists containing arithmetic
progressions. It is most often used in \code{for} loops. The
arguments must be plain integers. If the \var{step} argument is
@@ -278,13 +280,11 @@
\end{verbatim}\ecode
\end{funcdesc}
-\begin{funcdesc}{raw_input}{prompt}
- The string argument is optional; if present, it is written to
- standard
- output without a trailing newline. The function then reads a line
- from input, converts it to a string (stripping a trailing newline),
- and returns that. When \EOF{} is read, \code{EOFError} is raised.
- Example:
+\begin{funcdesc}{raw_input}{\optional{prompt}}
+ If the \var{prompt} argument is present, it is written to standard output
+ without a trailing newline. The function then reads a line from input,
+ converts it to a string (stripping a trailing newline), and returns that.
+ When \EOF{} is read, \code{EOFError} is raised. Example:
\bcode\begin{verbatim}
>>> s = raw_input('--> ')
@@ -295,7 +295,7 @@
\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 @@
other scopes can be. This may change.}
\end{funcdesc}
-\begin{funcdesc}{xrange}{start\, end\, step}
+\begin{funcdesc}{xrange}{\optional{start\,} end\optional{\, step}}
This function is very similar to \code{range()}, but returns an
``xrange object'' instead of a list. This is an opaque sequence type
which yields the same values as the corresponding list, without
diff --git a/Doc/lib/libimageop.tex b/Doc/lib/libimageop.tex
index c1cdac4..4481e61 100644
--- a/Doc/lib/libimageop.tex
+++ b/Doc/lib/libimageop.tex
@@ -19,7 +19,7 @@
\begin{funcdesc}{crop}{image\, psize\, width\, height\, x0\, y0\, x1\, y1}
This function takes the image in \code{image}, which should by
\code{width} by \code{height} in size and consist of pixels of
-\code{psize} bytes, and returns the selected part of that image. \code{X0},
+\code{psize} bytes, and returns the selected part of that image. \code{x0},
\code{y0}, \code{x1} and \code{y1} are like the \code{lrectread}
parameters, i.e. the boundary is included in the new image.
The new boundaries need not be inside the picture. Pixels that fall
diff --git a/Doc/lib/libimgfile.tex b/Doc/lib/libimgfile.tex
index 99efaf4..2da8d9d 100644
--- a/Doc/lib/libimgfile.tex
+++ b/Doc/lib/libimgfile.tex
@@ -29,7 +29,7 @@
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 @@
\code{'gaussian'}. If a filter is specified \var{blur} is an optional
parameter specifying the blurriness of the filter. It defaults to \code{1.0}.
-Readscaled makes no
+\code{readscaled} makes no
attempt to keep the aspect ratio correct, so that is the users'
responsibility.
\end{funcdesc}
diff --git a/Doc/lib/libjpeg.tex b/Doc/lib/libjpeg.tex
index d0c1604..a4e931f 100644
--- a/Doc/lib/libjpeg.tex
+++ b/Doc/lib/libjpeg.tex
@@ -4,7 +4,7 @@
The module jpeg provides access to the jpeg compressor and
decompressor written by the Independent JPEG Group. JPEG is a (draft?)
standard for compressing pictures. For details on jpeg or the
-Indepent JPEG Group software refer to the JPEG standard or the
+Independent JPEG Group software refer to the JPEG standard or the
documentation provided with the software.
The jpeg module defines these functions:
@@ -12,10 +12,10 @@
\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 @@
value between \code{0} and \code{100} (default is \code{75}). Compress only.
\item[\code{'optimize'}]
-Perform huffman table optimization. Takes longer, but results in
+Perform Huffman table optimization. Takes longer, but results in
smaller compressed image. Compress only.
\item[\code{'smooth'}]
diff --git a/Doc/lib/libmd5.tex b/Doc/lib/libmd5.tex
index 29e4b31..edaa727 100644
--- a/Doc/lib/libmd5.tex
+++ b/Doc/lib/libmd5.tex
@@ -2,16 +2,17 @@
\bimodindex{md5}
This module implements the interface to RSA's MD5 message digest
-algorithm (see also the file \file{md5.doc}). It's use is very
+algorithm (see also the file \file{md5.doc}). Its use is quite
straightforward: use the function \code{md5} to create an
\dfn{md5}-object. You can now ``feed'' this object with arbitrary
strings.
-At any time you can ask the ``final'' digest of the object. Internally,
-a temorary copy of the object is made and the digest is computed and
-returned. Because of the copy, the digest operation is not desctructive
-for the object. Before a more exact description of the use, a small
-example: to obtain the digest of the string \code{'abc'}, use \ldots
+At any time you can ask for the ``final'' digest of the object. Internally,
+a temporary copy of the object is made and the digest is computed and
+returned. Because of the copy, the digest operation is not destructive
+for the object. Before a more exact description of the module's use, a small
+example will be helpful:
+to obtain the digest of the string \code{'abc'}, use \ldots
\bcode\begin{verbatim}
>>> from md5 import md5
@@ -29,8 +30,8 @@
\end{verbatim}\ecode
\renewcommand{\indexsubitem}{(in module md5)}
-\begin{funcdesc}{md5}{arg}
- Create a new md5-object. \var{arg} is optional: if present, an initial
+\begin{funcdesc}{md5}{\optional{arg}}
+ Create a new md5-object. If \var{arg} is present, an initial
\code{update} method is called with \var{arg} as argument.
\end{funcdesc}
@@ -42,6 +43,7 @@
\end{funcdesc}
\begin{funcdesc}{digest}{}
+% XXX The following is not quite clear; what does MD5Final do?
Return the \dfn{digest} of this md5-object. Internally, a copy is made
and the \C-function \code{MD5Final} is called. Finally the digest is
returned.
diff --git a/Doc/lib/libposixfile.tex b/Doc/lib/libposixfile.tex
index 673ed6f..0d9cb32 100644
--- a/Doc/lib/libposixfile.tex
+++ b/Doc/lib/libposixfile.tex
@@ -47,17 +47,14 @@
The posixfile object defines the following additional methods:
\renewcommand{\indexsubitem}{(posixfile method)}
-\begin{funcdesc}{lock}{fmt\, len\, start\, whence}
+\begin{funcdesc}{lock}{fmt\, \optional{len\optional{\, start
+\optional{\, whence}}}}
Lock the specified section of the file that the file object is
- referring to. The arguments \code{\var{len}}, \code{\var{start}}
- and \code{\var{whence}} are optional with the understanding that
- if \code{\var{start}} is used \code{\var{len}} becomes mandatory,
- and if \code{\var{whence}} is used \code{\var{len}} and
- \code{\var{start}} become mandatory. The format is explained
- below in a table. The length argument specifies the length of the
- section that should be locked. The default is \code{0}. The start
- specifies the starting offset of the section. The default is
- \code{0}. The whence argument specifies where the offset is
+ referring to. The format is explained
+ below in a table. The \var{len} argument specifies the length of the
+ section that should be locked. The default is \code{0}. \var{start}
+ specifies the starting offset of the section, where the default is
+ \code{0}. The \var{whence} argument specifies where the offset is
relative to. It accepts one of the constants \code{SEEK_SET},
\code{SEEK_CUR} or \code{SEEK_END}. The default is \code{SEEK_SET}.
For more information about the arguments refer to the fcntl
@@ -69,7 +66,7 @@
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 @@
\begin{tableiii}{|c|l|c|}{samp}{Modifier}{Meaning}{Notes}
\lineiii{|}{wait until the lock has been granted}{}
- \lineiii{?}{return the first lock conflicting with the requested lock,
- or \code{None} if there is no conflict.}{(1)}
+ \lineiii{?}{return the first lock conflicting with the requested lock,}{(1)}
+ {}&{\hskip0.5cm or \code{None} if there is no conflict.}&{}\\
\end{tableiii}
Note:
@@ -138,7 +135,7 @@
(1) The \code{!} and \code{=} modifiers are mutually exclusive.
-(2) This string represents the flag after they may have been altered
+(2) This string represents the flags after they may have been altered
by the same call.
Examples:
diff --git a/Doc/lib/libregex.tex b/Doc/lib/libregex.tex
index 13b3e20..f3df684 100644
--- a/Doc/lib/libregex.tex
+++ b/Doc/lib/libregex.tex
@@ -41,7 +41,7 @@
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 @@
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 @@
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 @@
is to start.
\end{funcdesc}
-\begin{funcdesc}{search}{string\, pos}
+\begin{funcdesc}{search}{string\optional{\, pos}}
Return the first position in \var{string} that matches the regular
expression \code{pattern}. Return \code{-1} if no position in the
string matches the pattern (this is different from a zero-length
diff --git a/Doc/lib/librotor.tex b/Doc/lib/librotor.tex
index 657d2ac..b931333 100644
--- a/Doc/lib/librotor.tex
+++ b/Doc/lib/librotor.tex
@@ -1,6 +1,105 @@
\section{Built-in module \sectcode{rotor}}
\bimodindex{rotor}
-This module implements a rotor-based encryption algorithm, contributed
-by Lance Ellinghouse. Currently no further documentation is available
---- you are kindly advised to read the source...
+This module implements a rotor-based encryption algorithm, contributed by
+Lance Ellinghouse. The design is derived from the Enigma device, a machine
+used during World War II to encipher messages. A rotor is simply a
+permutation. For example, if the character `A' is the origin of the rotor,
+then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on.
+To encrypt, we choose several different rotors, and set the origins of the
+rotors to known positions; their initial position is the ciphering key. To
+encipher a character, we permute the original character by the first rotor,
+and then apply the second rotor's permutation to the result. We continue
+until we've applied all the rotors; the resulting character is our
+ciphertext. We then change the origin of the final rotor by one position,
+from `A' to `B'; if the final rotor has made a complete revolution, then we
+rotate the next-to-last rotor by one position, and apply the same procedure
+recursively. In other words, after enciphering one character, we advance
+the rotors in the same fashion as a car's odometer. Decoding works in the
+same way, except we reverse the permutations and apply them in the opposite
+order.
+\index{Ellinghouse, Lance}
+\indexii{Enigma}{cipher}
+
+The available functions in this module are:
+
+\renewcommand{\indexsubitem}{(in module rotor)}
+\begin{funcdesc}{newrotor}{key\optional{\, numrotors}}
+Returns a rotor object. \var{key} is a string containing the encryption key
+for the object; it can contain arbitrary binary data. The key will be used
+to randomly generate the rotor permutations and their initial positions.
+\var{numrotors} is the number of rotor permutations in the returned object;
+if it is omitted, a default value of 6 will be used.
+\end{funcdesc}
+
+Rotor objects have the following methods:
+
+\renewcommand{\indexsubitem}{(rotor method)}
+\begin{funcdesc}{setkey}{}
+Resets the rotor to its initial state.
+\end{funcdesc}
+
+\begin{funcdesc}{encrypt}{plaintext}
+Resets the rotor object to its initial state and encrypts \var{plaintext},
+returning a string containing the ciphertext. The ciphertext is always the
+same length as the original plaintext.
+\end{funcdesc}
+
+\begin{funcdesc}{encryptmore}{plaintext}
+Encrypts \var{plaintext} without resetting the rotor object, and returns a
+string containing the ciphertext.
+\end{funcdesc}
+
+\begin{funcdesc}{decrypt}{ciphertext}
+Resets the rotor object to its initial state and decrypts \var{ciphertext},
+returning a string containing the ciphertext. The plaintext string will
+always be the same length as the ciphertext.
+\end{funcdesc}
+
+\begin{funcdesc}{decryptmore}{ciphertext}
+Decrypts \var{ciphertext} without resetting the rotor object, and returns a
+string containing the ciphertext.
+\end{funcdesc}
+
+An example usage:
+\bcode\begin{verbatim}
+>>> import rotor
+>>> rt = rotor.newrotor('key', 12)
+>>> rt.encrypt('bar')
+'\2534\363'
+>>> rt.encryptmore('bar')
+'\357\375$'
+>>> rt.encrypt('bar')
+'\2534\363'
+>>> rt.decrypt('\2534\363')
+'bar'
+>>> rt.decryptmore('\357\375$')
+'bar'
+>>> rt.decrypt('\357\375$')
+'l(\315'
+>>> del rt
+\end{verbatim}\ecode
+
+The module's code is not an exact simulation of the original Enigma device;
+it implements the rotor encryption scheme differently from the original. The
+most important difference is that in the original Enigma, there were only 5
+or 6 different rotors in existence, and they were applied twice to each
+character; the cipher key was the order in which they were placed in the
+machine. The Python rotor module uses the supplied key to initialize a
+random number generator; the rotor permutations and their initial positions
+are then randomly generated. The original device only enciphered the
+letters of the alphabet, while this module can handle any 8-bit binary data;
+it also produces binary output. This module can also operate with an
+arbitrary number of rotors.
+
+The original Enigma cipher was broken in 1944. % XXX: Is this right?
+The version implemented here is probably a good deal more difficult to crack
+(especially if you use many rotors), but it won't be impossible for
+a truly skilful and determined attacker to break the cipher. So if you want
+to keep the NSA out of your files, this rotor cipher may well be unsafe, but
+for discouraging casual snooping through your files, it will probably be
+just fine, and may be somewhat safer than using the Unix \file{crypt}
+command.
+\index{National Security Agency}\index{crypt(1)}
+% XXX How were Unix commands represented in the docs?
+
diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex
index f051be8..244ef67 100644
--- a/Doc/lib/libsocket.tex
+++ b/Doc/lib/libsocket.tex
@@ -76,8 +76,10 @@
\end{funcdesc}
\begin{funcdesc}{gethostname}{}
-Return the current host's canonical name, as a string
-(e.g. \code{'voorn.cwi.nl'}).
+Return a string containing the hostname of the machine where
+the Python interpreter is currently executing. If you want to know the
+current machine's IP address, use
+\code{socket.gethostbyname( socket.gethostname() )} instead.
\end{funcdesc}
\begin{funcdesc}{getservbyname}{servicename\, protocolname}
diff --git a/Doc/lib/libstdwin.tex b/Doc/lib/libstdwin.tex
index 12771c9..df37707 100644
--- a/Doc/lib/libstdwin.tex
+++ b/Doc/lib/libstdwin.tex
@@ -102,7 +102,7 @@
\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 @@
\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 @@
region, the set of pixels drawn is the intersection of the clipping
region and the set of pixels that would be drawn by the same operation
in the absence of a clipping region.
-clipping region
\end{funcdesc}
\begin{funcdesc}{noclip}{}
diff --git a/Doc/lib/libstring.tex b/Doc/lib/libstring.tex
index bf7ad09..7d99a36 100644
--- a/Doc/lib/libstring.tex
+++ b/Doc/lib/libstring.tex
@@ -108,24 +108,24 @@
sequences.
\end{funcdesc}
-\begin{funcdesc}{find}{s\, sub\, i}
-Return the lowest index in \var{s} not smaller than \var{i} where the
+\begin{funcdesc}{find}{s\, sub\optional{\, start}}
+Return the lowest index in \var{s} not smaller than \var{start} where the
substring \var{sub} is found. Return \code{-1} when \var{sub}
-does not occur as a substring of \var{s} with index at least \var{i}.
-If \var{i} is omitted, it defaults to \code{0}. If \var{i} is
+does not occur as a substring of \var{s} with index at least \var{start}.
+If \var{start} is omitted, it defaults to \code{0}. If \var{start} is
negative, \code{len(\var{s})} is added.
\end{funcdesc}
-\begin{funcdesc}{rfind}{s\, sub\, i}
+\begin{funcdesc}{rfind}{s\, sub\optional{\, start}}
Like \code{find} but finds the highest index.
\end{funcdesc}
-\begin{funcdesc}{index}{s\, sub\, i}
+\begin{funcdesc}{index}{s\, sub\optional{\, start}}
Like \code{find} but raise \code{index_error} when the substring is
not found.
\end{funcdesc}
-\begin{funcdesc}{rindex}{s\, sub\, i}
+\begin{funcdesc}{rindex}{s\, sub\optional{\, start}}
Like \code{rfind} but raise \code{index_error} when the substring is
not found.
\end{funcdesc}
diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex
index ba6b896..cd2c646 100644
--- a/Doc/lib/libsys.tex
+++ b/Doc/lib/libsys.tex
@@ -57,7 +57,7 @@
exception is not handled and the interpreter prints an error message
and a stack traceback. Their intended use is to allow an interactive
user to import a debugger module and engage in post-mortem debugging
- without having to re-execute the command that cause the error (which
+ without having to re-execute the command that caused the error (which
may be hard to reproduce). The meaning of the variables is the same
as that of \code{exc_type}, \code{exc_value} and \code{exc_tracaback},
respectively.
diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex
index fe8b7dc..7e83f4e 100644
--- a/Doc/lib/libtime.tex
+++ b/Doc/lib/libtime.tex
@@ -10,7 +10,7 @@
\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)}.
diff --git a/Doc/libal.tex b/Doc/libal.tex
index 708c54e..51a0312 100644
--- a/Doc/libal.tex
+++ b/Doc/libal.tex
@@ -23,7 +23,7 @@
Module \code{al} defines the following functions:
\renewcommand{\indexsubitem}{(in module al)}
-\begin{funcdesc}{openport}{name\, direction\, config}
+\begin{funcdesc}{openport}{name\, direction\optional{\, config}}
Equivalent to the C function ALopenport(). The name and direction
arguments are strings. The optional config argument is an opaque
configuration object as returned by \code{al.newconfig()}. The return
diff --git a/Doc/libarray.tex b/Doc/libarray.tex
index 21122f0..034ac32 100644
--- a/Doc/libarray.tex
+++ b/Doc/libarray.tex
@@ -20,14 +20,14 @@
\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 @@
\begin{funcdesc}{byteswap}{x}
``Byteswap'' all items of the array. This is only supported for
-integer values. It is useful when reading data ffrom a file written
+integer values. It is useful when reading data from a file written
on a machine with a different byte order.
\end{funcdesc}
diff --git a/Doc/libaudioop.tex b/Doc/libaudioop.tex
index 734065a..61ab7fc 100644
--- a/Doc/libaudioop.tex
+++ b/Doc/libaudioop.tex
@@ -43,7 +43,7 @@
\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 @@
(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 to 4 bit Intel/DVI ADPCM encoding.
ADPCM coding is an adaptive coding scheme, whereby each 4 bit number
is the difference between one sample and the next, divided by a
-(varying) step. The Intel/DVI ADPCM algorythm has been selected for
-use by the IMA, so may well become a standard.
+(varying) step. The Intel/DVI ADPCM algorithm has been selected for
+use by the IMA, so it may well become a standard.
\code{State} is a tuple containing the state of the coder. The coder
returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the
@@ -120,7 +120,7 @@
\begin{funcdesc}{lin2ulaw}{fragment\, width}
This function converts samples in the audio fragment to U-LAW encoding
-and returns this as a python string. U-LAW is an audio encoding format
+and returns this as a Python string. U-LAW is an audio encoding format
whereby you get a dynamic range of about 14 bits using only 8 bit
samples. It is used by the Sun audio hardware, among others.
\end{funcdesc}
diff --git a/Doc/libcrypto.tex b/Doc/libcrypto.tex
index 467bee4..302b50d 100644
--- a/Doc/libcrypto.tex
+++ b/Doc/libcrypto.tex
@@ -2,4 +2,11 @@
The modules described in this chapter implement various algorithms of
a cryptographic nature. They are available at the discretion of the
-installation.
+installation.
+\index{cryptography}
+
+%Hardcore cypherpunks will probably find the Python Cryptography Kit of
+%further interest; the package adds built-in modules for DES and IDEA
+%encryption, and provides a Python module for reading and decrypting PGP files.
+%\index{PGP}\indexii{DES}{cipher}\indexii{IDEA}{cipher}
+%\index{Python Cryptography Kit}
diff --git a/Doc/libfcntl.tex b/Doc/libfcntl.tex
index dd5212b..e361d5e 100644
--- a/Doc/libfcntl.tex
+++ b/Doc/libfcntl.tex
@@ -13,12 +13,12 @@
\renewcommand{\indexsubitem}{(in module struct)}
-\begin{funcdesc}{fcntl}{fd\, op\, arg}
+\begin{funcdesc}{fcntl}{fd\, op\optional{\, arg}}
Perform the requested operation on file descriptor \code{\var{fd}}.
The operation is defined by \code{\var{op}} and is operating system
dependent. Typically these codes can be retrieved from the library
- module \code{FCNTL}. The argument \code{\var{arg}} is optional. When
- it is missing it is interpreted as the integer value \code{0}. When
+ module \code{FCNTL}. The argument \code{\var{arg}} is optional, and
+ defaults to the integer value \code{0}. When
it is present, it can either be an integer value, or a string. With
the argument missing or an integer value, the return value of this
function is the integer return value of the real \code{fcntl()}
diff --git a/Doc/libfl.tex b/Doc/libfl.tex
index b705a6b..5af1a04 100644
--- a/Doc/libfl.tex
+++ b/Doc/libfl.tex
@@ -78,11 +78,11 @@
It returns \code{1} if the user pressed YES, \code{0} if NO.
\end{funcdesc}
-\begin{funcdesc}{show_choice}{str1\, str2\, str3\, but1\, but2\, but3}
+\begin{funcdesc}{show_choice}{str1\, str2\, str3\, but1\optional{\, but2\,
+but3}}
Show a dialog box with a three-line message and up to three buttons.
It returns the number of the button clicked by the user
(\code{1}, \code{2} or \code{3}).
-The \var{but2} and \var{but3} arguments are optional.
\end{funcdesc}
\begin{funcdesc}{show_input}{prompt\, default}
diff --git a/Doc/libfm.tex b/Doc/libfm.tex
index acbc05d..45d820c 100644
--- a/Doc/libfm.tex
+++ b/Doc/libfm.tex
@@ -77,7 +77,8 @@
Returns a tuple giving some pertinent data about this font.
This is an interface to \code{fmgetfontinfo()}.
The returned tuple contains the following numbers:
-\code{(\var{printermatched}, \var{fixed_width}, \var{xorig}, \var{yorig}, \var{xsize}, \var{ysize}, \var{height}, \var{nglyphs})}.
+{\tt(\var{printermatched}, \var{fixed_width}, \var{xorig}, \var{yorig},
+\var{xsize}, \var{ysize}, \var{height}, \var{nglyphs})}.
\end{funcdesc}
\begin{funcdesc}{getstrwidth}{string}
diff --git a/Doc/libfuncs.tex b/Doc/libfuncs.tex
index 2c30c14..b37920d 100644
--- a/Doc/libfuncs.tex
+++ b/Doc/libfuncs.tex
@@ -78,7 +78,7 @@
\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 @@
object.)
\end{funcdesc}
-\begin{funcdesc}{input}{prompt}
- Almost equivalent to \code{eval(raw_input(\var{prompt}))}. As for
- \code{raw_input()}, the prompt argument is optional. The difference is
- that a long input expression may be broken over multiple lines using the
- backslash convention.
+\begin{funcdesc}{input}{\optional{prompt}}
+ Almost equivalent to \code{eval(raw_input(\var{prompt}))}. Like
+ \code{raw_input()}, the \var{prompt} argument is optional. The difference
+ is that a long input expression may be broken over multiple lines using
+ the backslash convention.
\end{funcdesc}
\begin{funcdesc}{int}{x}
@@ -206,7 +206,7 @@
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 @@
\code{chr()}.
\end{funcdesc}
-\begin{funcdesc}{pow}{x\, y}
- Return \var{x} to the power \var{y}. The arguments must have
+\begin{funcdesc}{pow}{x\, y\optional{\, z}}
+ Return \var{x} to the power \var{y}; if \var{z} is present, $x^y \bmod z$
+ is returned. The arguments must have
numeric types. With mixed operand types, the rules for binary
arithmetic operators apply. The effective operand type is also the
type of the result; if the result is not expressible in this type, the
- function raises an exception; e.g., \code{pow(2, -1)} is not allowed.
+ function raises an exception; e.g., \code{pow(2, -1)} or \code{pow(2,
+ 35000)} is not allowed.
\end{funcdesc}
-\begin{funcdesc}{range}{start\, end\, step}
+\begin{funcdesc}{range}{\optional{start\,} end\optional{\, step}}
This is a versatile function to create lists containing arithmetic
progressions. It is most often used in \code{for} loops. The
arguments must be plain integers. If the \var{step} argument is
@@ -278,13 +280,11 @@
\end{verbatim}\ecode
\end{funcdesc}
-\begin{funcdesc}{raw_input}{prompt}
- The string argument is optional; if present, it is written to
- standard
- output without a trailing newline. The function then reads a line
- from input, converts it to a string (stripping a trailing newline),
- and returns that. When \EOF{} is read, \code{EOFError} is raised.
- Example:
+\begin{funcdesc}{raw_input}{\optional{prompt}}
+ If the \var{prompt} argument is present, it is written to standard output
+ without a trailing newline. The function then reads a line from input,
+ converts it to a string (stripping a trailing newline), and returns that.
+ When \EOF{} is read, \code{EOFError} is raised. Example:
\bcode\begin{verbatim}
>>> s = raw_input('--> ')
@@ -295,7 +295,7 @@
\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 @@
other scopes can be. This may change.}
\end{funcdesc}
-\begin{funcdesc}{xrange}{start\, end\, step}
+\begin{funcdesc}{xrange}{\optional{start\,} end\optional{\, step}}
This function is very similar to \code{range()}, but returns an
``xrange object'' instead of a list. This is an opaque sequence type
which yields the same values as the corresponding list, without
diff --git a/Doc/libimageop.tex b/Doc/libimageop.tex
index c1cdac4..4481e61 100644
--- a/Doc/libimageop.tex
+++ b/Doc/libimageop.tex
@@ -19,7 +19,7 @@
\begin{funcdesc}{crop}{image\, psize\, width\, height\, x0\, y0\, x1\, y1}
This function takes the image in \code{image}, which should by
\code{width} by \code{height} in size and consist of pixels of
-\code{psize} bytes, and returns the selected part of that image. \code{X0},
+\code{psize} bytes, and returns the selected part of that image. \code{x0},
\code{y0}, \code{x1} and \code{y1} are like the \code{lrectread}
parameters, i.e. the boundary is included in the new image.
The new boundaries need not be inside the picture. Pixels that fall
diff --git a/Doc/libimgfile.tex b/Doc/libimgfile.tex
index 99efaf4..2da8d9d 100644
--- a/Doc/libimgfile.tex
+++ b/Doc/libimgfile.tex
@@ -29,7 +29,7 @@
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 @@
\code{'gaussian'}. If a filter is specified \var{blur} is an optional
parameter specifying the blurriness of the filter. It defaults to \code{1.0}.
-Readscaled makes no
+\code{readscaled} makes no
attempt to keep the aspect ratio correct, so that is the users'
responsibility.
\end{funcdesc}
diff --git a/Doc/libjpeg.tex b/Doc/libjpeg.tex
index d0c1604..a4e931f 100644
--- a/Doc/libjpeg.tex
+++ b/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 @@
\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 @@
value between \code{0} and \code{100} (default is \code{75}). Compress only.
\item[\code{'optimize'}]
-Perform huffman table optimization. Takes longer, but results in
+Perform Huffman table optimization. Takes longer, but results in
smaller compressed image. Compress only.
\item[\code{'smooth'}]
diff --git a/Doc/libmd5.tex b/Doc/libmd5.tex
index 29e4b31..edaa727 100644
--- a/Doc/libmd5.tex
+++ b/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,
-a temorary copy of the object is made and the digest is computed and
-returned. Because of the copy, the digest operation is not desctructive
-for the object. Before a more exact description of the use, a small
-example: to obtain the digest of the string \code{'abc'}, use \ldots
+At any time you can ask for the ``final'' digest of the object. Internally,
+a temporary copy of the object is made and the digest is computed and
+returned. Because of the copy, the digest operation is not destructive
+for the object. Before a more exact description of the module's use, a small
+example will be helpful:
+to obtain the digest of the string \code{'abc'}, use \ldots
\bcode\begin{verbatim}
>>> from md5 import md5
@@ -29,8 +30,8 @@
\end{verbatim}\ecode
\renewcommand{\indexsubitem}{(in module md5)}
-\begin{funcdesc}{md5}{arg}
- Create a new md5-object. \var{arg} is optional: if present, an initial
+\begin{funcdesc}{md5}{\optional{arg}}
+ Create a new md5-object. If \var{arg} is present, an initial
\code{update} method is called with \var{arg} as argument.
\end{funcdesc}
@@ -42,6 +43,7 @@
\end{funcdesc}
\begin{funcdesc}{digest}{}
+% XXX The following is not quite clear; what does MD5Final do?
Return the \dfn{digest} of this md5-object. Internally, a copy is made
and the \C-function \code{MD5Final} is called. Finally the digest is
returned.
diff --git a/Doc/libmods.tex b/Doc/libmods.tex
index 3b902de..5bc6ee2 100755
--- a/Doc/libmods.tex
+++ b/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.}
diff --git a/Doc/libposixfile.tex b/Doc/libposixfile.tex
index 673ed6f..0d9cb32 100644
--- a/Doc/libposixfile.tex
+++ b/Doc/libposixfile.tex
@@ -47,17 +47,14 @@
The posixfile object defines the following additional methods:
\renewcommand{\indexsubitem}{(posixfile method)}
-\begin{funcdesc}{lock}{fmt\, len\, start\, whence}
+\begin{funcdesc}{lock}{fmt\, \optional{len\optional{\, start
+\optional{\, whence}}}}
Lock the specified section of the file that the file object is
- referring to. The arguments \code{\var{len}}, \code{\var{start}}
- and \code{\var{whence}} are optional with the understanding that
- if \code{\var{start}} is used \code{\var{len}} becomes mandatory,
- and if \code{\var{whence}} is used \code{\var{len}} and
- \code{\var{start}} become mandatory. The format is explained
- below in a table. The length argument specifies the length of the
- section that should be locked. The default is \code{0}. The start
- specifies the starting offset of the section. The default is
- \code{0}. The whence argument specifies where the offset is
+ referring to. The format is explained
+ below in a table. The \var{len} argument specifies the length of the
+ section that should be locked. The default is \code{0}. \var{start}
+ specifies the starting offset of the section, where the default is
+ \code{0}. The \var{whence} argument specifies where the offset is
relative to. It accepts one of the constants \code{SEEK_SET},
\code{SEEK_CUR} or \code{SEEK_END}. The default is \code{SEEK_SET}.
For more information about the arguments refer to the fcntl
@@ -69,7 +66,7 @@
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 @@
\begin{tableiii}{|c|l|c|}{samp}{Modifier}{Meaning}{Notes}
\lineiii{|}{wait until the lock has been granted}{}
- \lineiii{?}{return the first lock conflicting with the requested lock,
- or \code{None} if there is no conflict.}{(1)}
+ \lineiii{?}{return the first lock conflicting with the requested lock,}{(1)}
+ {}&{\hskip0.5cm or \code{None} if there is no conflict.}&{}\\
\end{tableiii}
Note:
@@ -138,7 +135,7 @@
(1) The \code{!} and \code{=} modifiers are mutually exclusive.
-(2) This string represents the flag after they may have been altered
+(2) This string represents the flags after they may have been altered
by the same call.
Examples:
diff --git a/Doc/libregex.tex b/Doc/libregex.tex
index 13b3e20..f3df684 100644
--- a/Doc/libregex.tex
+++ b/Doc/libregex.tex
@@ -41,7 +41,7 @@
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 @@
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 @@
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 @@
is to start.
\end{funcdesc}
-\begin{funcdesc}{search}{string\, pos}
+\begin{funcdesc}{search}{string\optional{\, pos}}
Return the first position in \var{string} that matches the regular
expression \code{pattern}. Return \code{-1} if no position in the
string matches the pattern (this is different from a zero-length
diff --git a/Doc/librotor.tex b/Doc/librotor.tex
index 657d2ac..b931333 100644
--- a/Doc/librotor.tex
+++ b/Doc/librotor.tex
@@ -1,6 +1,105 @@
\section{Built-in module \sectcode{rotor}}
\bimodindex{rotor}
-This module implements a rotor-based encryption algorithm, contributed
-by Lance Ellinghouse. Currently no further documentation is available
---- you are kindly advised to read the source...
+This module implements a rotor-based encryption algorithm, contributed by
+Lance Ellinghouse. The design is derived from the Enigma device, a machine
+used during World War II to encipher messages. A rotor is simply a
+permutation. For example, if the character `A' is the origin of the rotor,
+then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on.
+To encrypt, we choose several different rotors, and set the origins of the
+rotors to known positions; their initial position is the ciphering key. To
+encipher a character, we permute the original character by the first rotor,
+and then apply the second rotor's permutation to the result. We continue
+until we've applied all the rotors; the resulting character is our
+ciphertext. We then change the origin of the final rotor by one position,
+from `A' to `B'; if the final rotor has made a complete revolution, then we
+rotate the next-to-last rotor by one position, and apply the same procedure
+recursively. In other words, after enciphering one character, we advance
+the rotors in the same fashion as a car's odometer. Decoding works in the
+same way, except we reverse the permutations and apply them in the opposite
+order.
+\index{Ellinghouse, Lance}
+\indexii{Enigma}{cipher}
+
+The available functions in this module are:
+
+\renewcommand{\indexsubitem}{(in module rotor)}
+\begin{funcdesc}{newrotor}{key\optional{\, numrotors}}
+Returns a rotor object. \var{key} is a string containing the encryption key
+for the object; it can contain arbitrary binary data. The key will be used
+to randomly generate the rotor permutations and their initial positions.
+\var{numrotors} is the number of rotor permutations in the returned object;
+if it is omitted, a default value of 6 will be used.
+\end{funcdesc}
+
+Rotor objects have the following methods:
+
+\renewcommand{\indexsubitem}{(rotor method)}
+\begin{funcdesc}{setkey}{}
+Resets the rotor to its initial state.
+\end{funcdesc}
+
+\begin{funcdesc}{encrypt}{plaintext}
+Resets the rotor object to its initial state and encrypts \var{plaintext},
+returning a string containing the ciphertext. The ciphertext is always the
+same length as the original plaintext.
+\end{funcdesc}
+
+\begin{funcdesc}{encryptmore}{plaintext}
+Encrypts \var{plaintext} without resetting the rotor object, and returns a
+string containing the ciphertext.
+\end{funcdesc}
+
+\begin{funcdesc}{decrypt}{ciphertext}
+Resets the rotor object to its initial state and decrypts \var{ciphertext},
+returning a string containing the ciphertext. The plaintext string will
+always be the same length as the ciphertext.
+\end{funcdesc}
+
+\begin{funcdesc}{decryptmore}{ciphertext}
+Decrypts \var{ciphertext} without resetting the rotor object, and returns a
+string containing the ciphertext.
+\end{funcdesc}
+
+An example usage:
+\bcode\begin{verbatim}
+>>> import rotor
+>>> rt = rotor.newrotor('key', 12)
+>>> rt.encrypt('bar')
+'\2534\363'
+>>> rt.encryptmore('bar')
+'\357\375$'
+>>> rt.encrypt('bar')
+'\2534\363'
+>>> rt.decrypt('\2534\363')
+'bar'
+>>> rt.decryptmore('\357\375$')
+'bar'
+>>> rt.decrypt('\357\375$')
+'l(\315'
+>>> del rt
+\end{verbatim}\ecode
+
+The module's code is not an exact simulation of the original Enigma device;
+it implements the rotor encryption scheme differently from the original. The
+most important difference is that in the original Enigma, there were only 5
+or 6 different rotors in existence, and they were applied twice to each
+character; the cipher key was the order in which they were placed in the
+machine. The Python rotor module uses the supplied key to initialize a
+random number generator; the rotor permutations and their initial positions
+are then randomly generated. The original device only enciphered the
+letters of the alphabet, while this module can handle any 8-bit binary data;
+it also produces binary output. This module can also operate with an
+arbitrary number of rotors.
+
+The original Enigma cipher was broken in 1944. % XXX: Is this right?
+The version implemented here is probably a good deal more difficult to crack
+(especially if you use many rotors), but it won't be impossible for
+a truly skilful and determined attacker to break the cipher. So if you want
+to keep the NSA out of your files, this rotor cipher may well be unsafe, but
+for discouraging casual snooping through your files, it will probably be
+just fine, and may be somewhat safer than using the Unix \file{crypt}
+command.
+\index{National Security Agency}\index{crypt(1)}
+% XXX How were Unix commands represented in the docs?
+
diff --git a/Doc/libsocket.tex b/Doc/libsocket.tex
index f051be8..244ef67 100644
--- a/Doc/libsocket.tex
+++ b/Doc/libsocket.tex
@@ -76,8 +76,10 @@
\end{funcdesc}
\begin{funcdesc}{gethostname}{}
-Return the current host's canonical name, as a string
-(e.g. \code{'voorn.cwi.nl'}).
+Return a string containing the hostname of the machine where
+the Python interpreter is currently executing. If you want to know the
+current machine's IP address, use
+\code{socket.gethostbyname( socket.gethostname() )} instead.
\end{funcdesc}
\begin{funcdesc}{getservbyname}{servicename\, protocolname}
diff --git a/Doc/libstdwin.tex b/Doc/libstdwin.tex
index 12771c9..df37707 100644
--- a/Doc/libstdwin.tex
+++ b/Doc/libstdwin.tex
@@ -102,7 +102,7 @@
\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 @@
\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 @@
region, the set of pixels drawn is the intersection of the clipping
region and the set of pixels that would be drawn by the same operation
in the absence of a clipping region.
-clipping region
\end{funcdesc}
\begin{funcdesc}{noclip}{}
diff --git a/Doc/libstring.tex b/Doc/libstring.tex
index bf7ad09..7d99a36 100644
--- a/Doc/libstring.tex
+++ b/Doc/libstring.tex
@@ -108,24 +108,24 @@
sequences.
\end{funcdesc}
-\begin{funcdesc}{find}{s\, sub\, i}
-Return the lowest index in \var{s} not smaller than \var{i} where the
+\begin{funcdesc}{find}{s\, sub\optional{\, start}}
+Return the lowest index in \var{s} not smaller than \var{start} where the
substring \var{sub} is found. Return \code{-1} when \var{sub}
-does not occur as a substring of \var{s} with index at least \var{i}.
-If \var{i} is omitted, it defaults to \code{0}. If \var{i} is
+does not occur as a substring of \var{s} with index at least \var{start}.
+If \var{start} is omitted, it defaults to \code{0}. If \var{start} is
negative, \code{len(\var{s})} is added.
\end{funcdesc}
-\begin{funcdesc}{rfind}{s\, sub\, i}
+\begin{funcdesc}{rfind}{s\, sub\optional{\, start}}
Like \code{find} but finds the highest index.
\end{funcdesc}
-\begin{funcdesc}{index}{s\, sub\, i}
+\begin{funcdesc}{index}{s\, sub\optional{\, start}}
Like \code{find} but raise \code{index_error} when the substring is
not found.
\end{funcdesc}
-\begin{funcdesc}{rindex}{s\, sub\, i}
+\begin{funcdesc}{rindex}{s\, sub\optional{\, start}}
Like \code{rfind} but raise \code{index_error} when the substring is
not found.
\end{funcdesc}
diff --git a/Doc/libsys.tex b/Doc/libsys.tex
index ba6b896..cd2c646 100644
--- a/Doc/libsys.tex
+++ b/Doc/libsys.tex
@@ -57,7 +57,7 @@
exception is not handled and the interpreter prints an error message
and a stack traceback. Their intended use is to allow an interactive
user to import a debugger module and engage in post-mortem debugging
- without having to re-execute the command that cause the error (which
+ without having to re-execute the command that caused the error (which
may be hard to reproduce). The meaning of the variables is the same
as that of \code{exc_type}, \code{exc_value} and \code{exc_tracaback},
respectively.
diff --git a/Doc/libtime.tex b/Doc/libtime.tex
index fe8b7dc..7e83f4e 100644
--- a/Doc/libtime.tex
+++ b/Doc/libtime.tex
@@ -10,7 +10,7 @@
\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)}.
diff --git a/Doc/myformat.sty b/Doc/myformat.sty
index c4fa2d8..22d7ad4 100644
--- a/Doc/myformat.sty
+++ b/Doc/myformat.sty
@@ -48,17 +48,10 @@
}
% Command to generate two index entries (using subentries)
-\newcommand{\indexii}[2]{
-\index{#1!#2}
-\index{#2!#1}
-}
+\newcommand{\indexii}[2]{\index{#1!#2}\index{#2!#1}}
% And three entries (using only one level of subentries)
-\newcommand{\indexiii}[3]{
-\index{#1!#2 #3}
-\index{#2!#3, #1}
-\index{#3!#1 #2}
-}
+\newcommand{\indexiii}[3]{\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}}
diff --git a/Doc/partparse.py b/Doc/partparse.py
index 757fc02..be9b1c8 100644
--- a/Doc/partparse.py
+++ b/Doc/partparse.py
@@ -854,7 +854,7 @@
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
diff --git a/Doc/qua.tex b/Doc/qua.tex
index 7cca09d..a56905c 100644
--- a/Doc/qua.tex
+++ b/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 @@
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 @@
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 @@
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 @@
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...)
diff --git a/Doc/ref.tex b/Doc/ref.tex
index 11a5d08..9fb37b6 100644
--- a/Doc/ref.tex
+++ b/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
diff --git a/Doc/ref/ref.tex b/Doc/ref/ref.tex
index 11a5d08..9fb37b6 100644
--- a/Doc/ref/ref.tex
+++ b/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
diff --git a/Doc/ref/ref1.tex b/Doc/ref/ref1.tex
index 169c244..0b006ba 100644
--- a/Doc/ref/ref1.tex
+++ b/Doc/ref/ref1.tex
@@ -5,7 +5,7 @@
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
diff --git a/Doc/ref/ref2.tex b/Doc/ref/ref2.tex
index 67f22f8..c08f829 100644
--- a/Doc/ref/ref2.tex
+++ b/Doc/ref/ref2.tex
@@ -354,7 +354,8 @@
\begin{verbatim}
( ) [ ] { }
-; , : . ` =
+, : . " ` '
+= ;
\end{verbatim}
The following printing ASCII characters are not used in Python. Their
@@ -363,7 +364,7 @@
\index{ASCII}
\begin{verbatim}
-@ $ " ?
+@ $ ?
\end{verbatim}
They may be used by future versions of the language though!
diff --git a/Doc/ref/ref4.tex b/Doc/ref/ref4.tex
index c14fada..c4c4abc 100644
--- a/Doc/ref/ref4.tex
+++ b/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 @@
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
diff --git a/Doc/ref/ref5.tex b/Doc/ref/ref5.tex
index 3e60931..a4a7b53 100644
--- a/Doc/ref/ref5.tex
+++ b/Doc/ref/ref5.tex
@@ -133,7 +133,7 @@
(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 @@
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}
diff --git a/Doc/ref1.tex b/Doc/ref1.tex
index 169c244..0b006ba 100644
--- a/Doc/ref1.tex
+++ b/Doc/ref1.tex
@@ -5,7 +5,7 @@
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
diff --git a/Doc/ref2.tex b/Doc/ref2.tex
index 67f22f8..c08f829 100644
--- a/Doc/ref2.tex
+++ b/Doc/ref2.tex
@@ -354,7 +354,8 @@
\begin{verbatim}
( ) [ ] { }
-; , : . ` =
+, : . " ` '
+= ;
\end{verbatim}
The following printing ASCII characters are not used in Python. Their
@@ -363,7 +364,7 @@
\index{ASCII}
\begin{verbatim}
-@ $ " ?
+@ $ ?
\end{verbatim}
They may be used by future versions of the language though!
diff --git a/Doc/ref4.tex b/Doc/ref4.tex
index c14fada..c4c4abc 100644
--- a/Doc/ref4.tex
+++ b/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 @@
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
diff --git a/Doc/ref5.tex b/Doc/ref5.tex
index 3e60931..a4a7b53 100644
--- a/Doc/ref5.tex
+++ b/Doc/ref5.tex
@@ -133,7 +133,7 @@
(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 @@
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}
diff --git a/Doc/tools/partparse.py b/Doc/tools/partparse.py
index 757fc02..be9b1c8 100644
--- a/Doc/tools/partparse.py
+++ b/Doc/tools/partparse.py
@@ -854,7 +854,7 @@
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
diff --git a/Doc/tut.tex b/Doc/tut.tex
index 5353d56..f20d77c 100644
--- a/Doc/tut.tex
+++ b/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 @@
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 @@
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 @@
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 @@
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 @@
\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 @@
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 @@
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 @@
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 @@
\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:
diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex
index 5353d56..f20d77c 100644
--- a/Doc/tut/tut.tex
+++ b/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 @@
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 @@
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 @@
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 @@
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 @@
\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 @@
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 @@
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 @@
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 @@
\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: