Explain the semantics of OverflowWarning, for the benefit of the

documenter.  Clarify a few other issues (some brought up by Martin von
Loewis in private email).

pep-0237.txt

@@ -121,6 +121,24 @@ Incompatibilities
       short int.  This *may* change, since it allows some
       optimization.
 
+    - The expression type(x).__name__ depends on whether x is a short
+      or a long int.  Since implementation alternative 2 is chosen,
+      this difference will remain.
+
+    - Long and short ints are handled different by the marshal module,
+      and by the pickle and cPickle modules.  This difference will
+      remain.
+
+    - Short ints with small values (typically between -1 and 99
+      inclusive) are "interned" -- whenever a result has such a value,
+      an existing short int with the same value is returned.  This is
+      not done for long ints with the same values.  This difference
+      will remain.  (Since there is no guarantee of this interning, is
+      is debatable whether this is a semantic difference -- but code
+      may exist that uses 'is' for comparisons of short ints and
+      happens to work because of this interning.  Such code may fail
+      if used with long ints.)
+
 
 Literals
 
@@ -163,8 +181,9 @@ Transition
        assumed that this won't break existing code.  (Code that
        depends on this exception would have to be too convoluted to be
        concerned about it.)  For those concerned about extreme
-       backwards compatibility, a command line option will allow a
-       warning to be issued at this point, but this is off by default.
+       backwards compatibility, a command line option (or a call to
+       the warnings module) will allow a warning or an error to be
+       issued at this point, but this is off by default.
 
     B. The remaining semantic differences are addressed.  In most
        cases the long int semantics will prevail; however, the
@@ -205,6 +224,54 @@ Transition
     B4. Python 3.0 (at least two years in the future).
 
 
+OverflowWarning
+
+    Here are the rules that guide warnings generated in situations
+    that currently raise OverflowError.  This applies to transition
+    phase A.
+
+    - A new warning category is introduced, OverflowWarning.  This is
+      a built-in name.
+
+    - If an int result overflows, an OverflowWarning warning is
+      issued, with a message argument indicating the operation,
+      e.g. "integer addition".  This may or may not cause a warning
+      message to be displayed on sys.stderr, or may cause an exception
+      to be raised, all under control of the -W command line and the
+      warnings module.
+
+    - The OverflowWarning warning is ignored by default.
+
+    - The OverflowWarning warning can be controlled like all warnings,
+      via the -W command line option or via the
+      warnings.filterwarnings() call.  For example:
+
+        python -Wdefault::OverflowWarning
+
+      cause the OverflowWarning to be displayed the first time it
+      occurs at a particular source line, and
+
+        python -Werror::OverflowWarning
+
+      cause the OverflowWarning to be turned into an exception
+      whenever it happens.  The following code enables the warning
+      from inside the program:
+
+        import warnings
+        warnings.filterwarnings("default", "", OverflowWarning)
+
+      See the python man page for the -W option and the the warnings
+      module documentation for filterwarnings().
+
+    - If the OverflowWarning warning is turned into an error,
+      OverflowError is substituted.  This is needed for backwards
+      compatibility.
+
+    - Unless the warning is turned into an exceptions, the result of
+      the operation (e.g., x+y) is recomputed after converting the
+      arguments to long ints.
+
+
 Example
 
     If you pass a long int to a C function or built-in operation that
@@ -229,11 +296,9 @@ Example
     calculated as a long int, but its value will be in range.
 
 
-Open Issues
+Resolved Issues
 
-    We expect that these issues will be resolved over time, as more
-    feedback is received or we gather more experience with the initial
-    implementation.
+    These issues, previously open, have been resolved.
 
     - What to do about sys.maxint?  Leave it in, since it is still
       relevant whenever the distinction between short and long ints is