5 files changed, 49 insertions, 12 deletions
diff --git a/Doc/ref/ref2.tex b/Doc/ref/ref2.tex
index 2ed8a5d..bad4609 100644
--- a/Doc/ref/ref2.tex
+++ b/Doc/ref/ref2.tex
@@ -56,7 +56,7 @@ by following the explicit or implicit \emph{line joining} rules.
 
 A physical line is a sequence of characters terminated by an end-of-line
 sequence.  In source files, any of the standard platform line
-termination sequences can be used - the \UNIX form using \ASCII{} LF
+termination sequences can be used - the \UNIX{} form using \ASCII{} LF
 (linefeed), the Windows form using the \ASCII{} sequence CR LF (return
 followed by linefeed), or the Macintosh form using the \ASCII{} CR
 (return) character.  All of these forms can be used equally, regardless
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
index d0c8ccf..15fc188 100644
--- a/Doc/ref/ref3.tex
+++ b/Doc/ref/ref3.tex
@@ -1307,6 +1307,11 @@ defines mutable objects and implements a \method{__cmp__()} or
 since the dictionary implementation requires that a key's hash value
 is immutable (if the object's hash value changes, it will be in the
 wrong hash bucket).
+
+\versionchanged[\method{__hash__()} may now also return a long
+integer object; the 32-bit integer is then derived from the hash
+of that object]{2.5}
+
 \withsubitem{(object method)}{\ttindex{__cmp__()}}
 \end{methoddesc}
 
@@ -1886,6 +1891,9 @@ method should be the equivalent to using \method{__floordiv__()} and
 \method{__pow__()} should be defined to accept an optional third
 argument if the ternary version of the built-in
 \function{pow()}\bifuncindex{pow} function is to be supported.
+
+If one of those methods does not support the operation with the
+supplied arguments, it should return \code{NotImplemented}.
 \end{methoddesc}
 
 \begin{methoddesc}[numeric object]{__div__}{self, other}
@@ -1918,13 +1926,28 @@ called to implement the binary arithmetic operations (\code{+},
 \function{pow()}\bifuncindex{pow}, \code{**}, \code{<<},
 \code{>>}, \code{\&}, \code{\^}, \code{|}) with reflected
 (swapped) operands.  These functions are only called if the left
-operand does not support the corresponding operation.  For instance,
-to evaluate the expression \var{x}\code{-}\var{y}, where \var{y} is an
-instance of a class that has an \method{__rsub__()} method,
-\code{\var{y}.__rsub__(\var{x})} is called.  Note that ternary
+operand does not support the corresponding operation and the
+operands are of different types.\footnote{
+    For operands of the same type, it is assumed that if the
+    non-reflected method (such as \method{__add__()}) fails the
+    operation is not supported, which is why the reflected method
+    is not called.} 
+For instance, to evaluate the expression \var{x}\code{-}\var{y},
+where \var{y} is an instance of a class that has an
+\method{__rsub__()} method, \code{\var{y}.__rsub__(\var{x})}
+is called if \code{\var{x}.__sub__(\var{y})} returns
+\var{NotImplemented}.
+
+Note that ternary
 \function{pow()}\bifuncindex{pow} will not try calling
 \method{__rpow__()} (the coercion rules would become too
 complicated).
+
+\note{If the right operand's type is a subclass of the left operand's
+      type and that subclass provides the reflected method for the
+      operation, this method will be called before the left operand's
+      non-reflected method.  This behavior allows subclasses to
+      override their ancestors' operations.}
 \end{methoddesc}
 
 \begin{methoddesc}[numeric object]{__iadd__}{self, other}
diff --git a/Doc/ref/ref4.tex b/Doc/ref/ref4.tex
index dcdc823..12a2b92 100644
--- a/Doc/ref/ref4.tex
+++ b/Doc/ref/ref4.tex
@@ -97,10 +97,20 @@ searched.  The global statement must precede all uses of the name.
 The built-in namespace associated with the execution of a code block
 is actually found by looking up the name \code{__builtins__} in its
 global namespace; this should be a dictionary or a module (in the
-latter case the module's dictionary is used).  Normally, the
-\code{__builtins__} namespace is the dictionary of the built-in module
-\module{__builtin__} (note: no `s').  If it isn't, restricted
-execution\indexii{restricted}{execution} mode is in effect.
+latter case the module's dictionary is used).  By default, when in the
+\module{__main__} module, \code{__builtins__} is the built-in module
+\module{__builtin__} (note: no `s'); when in any other module,
+\code{__builtins__} is an alias for the dictionary of the
+\module{__builtin__} module itself.  \code{__builtins__} can be set
+to a user-created dictionary to create a weak form of restricted
+execution\indexii{restricted}{execution}.
+
+\begin{notice}
+  Users should not touch \code{__builtins__}; it is strictly an
+  implementation detail.  Users wanting to override values in the
+  built-in namespace should \keyword{import} the \module{__builtin__}
+  (no `s') module and modify its attributes appropriately.
+\end{notice}
 
 The namespace for a module is automatically created the first time a
 module is imported.  The main module for a script is always called
diff --git a/Doc/ref/ref5.tex b/Doc/ref/ref5.tex
index 89f9977..909e5bb 100644
--- a/Doc/ref/ref5.tex
+++ b/Doc/ref/ref5.tex
@@ -907,7 +907,10 @@ The operators \code{<}, \code{>}, \code{==}, \code{>=}, \code{<=}, and
 the values of two objects.  The objects need not have the same type.
 If both are numbers, they are converted to a common type.  Otherwise,
 objects of different types \emph{always} compare unequal, and are
-ordered consistently but arbitrarily.
+ordered consistently but arbitrarily.  You can control comparison
+behavior of objects of non-builtin types by defining a \code{__cmp__}
+method or rich comparison methods like \code{__gt__}, described in
+section~\ref{specialnames}.
 
 (This unusual definition of comparison was used to simplify the
 definition of operations like sorting and the \keyword{in} and
@@ -952,7 +955,8 @@ otherwise defined.\footnote{Earlier versions of Python used
   a dictionary for emptiness by comparing it to \code{\{\}}.}
 
 \item
-Most other types compare unequal unless they are the same object;
+Most other objects of builtin types compare unequal unless they are
+the same object;
 the choice whether one object is considered smaller or larger than
 another one is made arbitrarily but consistently within one
 execution of a program.
diff --git a/Doc/ref/ref8.tex b/Doc/ref/ref8.tex
index 801ab58..45be71d 100644
--- a/Doc/ref/ref8.tex
+++ b/Doc/ref/ref8.tex
@@ -34,7 +34,7 @@ in the namespace of \module{__main__}.
 \index{interactive mode}
 \refbimodindex{__main__}
 
-Under {\UNIX}, a complete program can be passed to the interpreter in
+Under \UNIX, a complete program can be passed to the interpreter in
 three forms: with the \programopt{-c} \var{string} command line option, as a
 file passed as the first command line argument, or as standard input.
 If the file or standard input is a tty device, the interpreter enters