Issue #1717: documentation fixes related to the cmp removal.

6 files changed, 45 insertions, 36 deletions

diff --git a/Doc/includes/sqlite3/collation_reverse.py b/Doc/includes/sqlite3/collation_reverse.py
index bfd7f5b..3504a35 100644
--- a/Doc/includes/sqlite3/collation_reverse.py
+++ b/Doc/includes/sqlite3/collation_reverse.py
@@ -1,7 +1,12 @@
 import sqlite3
 
 def collate_reverse(string1, string2):
-    return -cmp(string1, string2)
+    if string1 == string2:
+        return 0
+    elif string1 < string2:
+        return 1
+    else:
+        return -1
 
 con = sqlite3.connect(":memory:")
 con.create_collation("reverse", collate_reverse)
diff --git a/Doc/library/locale.rst b/Doc/library/locale.rst
index 381107e..da3a843 100644
--- a/Doc/library/locale.rst
+++ b/Doc/library/locale.rst
@@ -225,12 +225,11 @@ The :mod:`locale` module defines the following exception and functions:
 
 .. function:: strxfrm(string)
 
-   .. index:: builtin: cmp
-
-   Transforms a string to one that can be used for the built-in function
-   :func:`cmp`, and still returns locale-aware results.  This function can be used
-   when the same string is compared repeatedly, e.g. when collating a sequence of
-   strings.
+   Transforms a string to one that can be used in locale-aware
+   comparisons.  For example, ``strxfrm(s1) < strxfrm(s2)`` is
+   equivalent to ``strcoll(s1, s2) < 0``.  This function can be used
+   when the same string is compared repeatedly, e.g. when collating a
+   sequence of strings.
 
 
 .. function:: format(format, val[, grouping[, monetary]])
diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst
index 089c7fa..24ace8b 100644
--- a/Doc/library/operator.rst
+++ b/Doc/library/operator.rst
@@ -43,9 +43,9 @@ the rich comparison operators they support:
    equivalent to ``a < b``, ``le(a, b)`` is equivalent to ``a <= b``, ``eq(a,
    b)`` is equivalent to ``a == b``, ``ne(a, b)`` is equivalent to ``a != b``,
    ``gt(a, b)`` is equivalent to ``a > b`` and ``ge(a, b)`` is equivalent to ``a
-   >= b``.  Note that unlike the built-in :func:`cmp`, these functions can
-   return any value, which may or may not be interpretable as a Boolean value.
-   See :ref:`comparisons` for more information about rich comparisons.
+   >= b``.  Note that these functions can return any value, which may
+   or may not be interpretable as a Boolean value.  See
+   :ref:`comparisons` for more information about rich comparisons.
 
 
 The logical operations are also generally applicable to all objects, and support
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index 8c078bc..29a5fd2 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -327,8 +327,9 @@ will create a test suite that will run ``WidgetTestCase.testDefaultSize()`` and
 ``WidgetTestCase.testResize``. :class:`TestLoader` uses the ``'test'`` method
 name prefix to identify test methods automatically.
 
-Note that the order in which the various test cases will be run is determined by
-sorting the test function names with the built-in :func:`cmp` function.
+Note that the order in which the various test cases will be run is
+determined by sorting the test function names with respect to the
+built-in ordering for strings.
 
 Often it is desirable to group suites of test cases together, so as to run tests
 for the whole system at once.  This is easy, since :class:`TestSuite` instances
@@ -921,9 +922,13 @@ subclassing or assignment on an instance:
 .. attribute:: TestLoader.sortTestMethodsUsing
 
    Function to be used to compare method names when sorting them in
-   :meth:`getTestCaseNames` and all the :meth:`loadTestsFrom\*` methods. The
-   default value is the built-in :func:`cmp` function; the attribute can also be
-   set to :const:`None` to disable the sort.
+   :meth:`getTestCaseNames` and all the :meth:`loadTestsFrom\*`
+   methods.  This should be a function that takes two arguments
+   ``self`` and ``other``, and returns ``-1`` if ``self`` precedes
+   ``other`` in the desired ordering, ``1`` if ``other`` precedes
+   ``self``, and ``0`` if ``self`` and ``other`` are equal.  The
+   default ordering is the built-in ordering for strings.  This
+   attribute can also be set to :const:`None` to disable the sort.
 
 
 .. attribute:: TestLoader.suiteClass
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index 100d81c..604a8f0 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -1022,8 +1022,8 @@ Comparison of objects of the same type depends on the type:
   length.
 
   If not equal, the sequences are ordered the same as their first differing
-  elements.  For example, ``cmp([1,2,x], [1,2,y])`` returns the same as
-  ``cmp(x,y)``.  If the corresponding element does not exist, the shorter
+  elements.  For example, ``[1,2,x] <= [1,2,y]`` has the same value as
+  ``x <= y``.  If the corresponding element does not exist, the shorter
   sequence is ordered first (for example, ``[1,2] < [1,2,3]``).
 
 * Mappings (dictionaries) compare equal if and only if their sorted ``(key,
diff --git a/Doc/tutorial/modules.rst b/Doc/tutorial/modules.rst
index 113186e..844eed0 100644
--- a/Doc/tutorial/modules.rst
+++ b/Doc/tutorial/modules.rst
@@ -317,25 +317,25 @@ want a list of those, they are defined in the standard module
    >>> dir(builtins)
 
    ['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException', 'Buffer
-   Error', 'DeprecationWarning', 'EOFError', 'Ellipsis', 'EnvironmentError', 'Excep
-   tion', 'False', 'FloatingPointError', 'FutureWarning', 'GeneratorExit', 'IOError
-   ', 'ImportError', 'ImportWarning', 'IndentationError', 'IndexError', 'KeyError',
-    'KeyboardInterrupt', 'LookupError', 'MemoryError', 'NameError', 'None', 'NotImp
-   lemented', 'NotImplementedError', 'OSError', 'OverflowError', 'PendingDeprecatio
-   nWarning', 'ReferenceError', 'RuntimeError', 'RuntimeWarning', 'StopIteration',
-   'SyntaxError', 'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError', 'True',
-    'TypeError', 'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError', '
-   UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning', 'ValueE
-   rror', 'Warning', 'ZeroDivisionError', '__build_class__', '__debug__', '__doc__'
-   , '__import__', '__name__', 'abs', 'all', 'any', 'basestring', 'bin', 'bool', 'b
-   uffer', 'bytes', 'chr', 'chr8', 'classmethod', 'cmp', 'compile', 'complex', 'cop
-   yright', 'credits', 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'ex
-   ec', 'exit', 'filter', 'float', 'frozenset', 'getattr', 'globals', 'hasattr', 'h
-   ash', 'help', 'hex', 'id', 'input', 'int', 'isinstance', 'issubclass', 'iter', '
-   len', 'license', 'list', 'locals', 'map', 'max', 'memoryview', 'min', 'next', 'o
-   bject', 'oct', 'open', 'ord', 'pow', 'print', 'property', 'quit', 'range', 'repr
-   ', 'reversed', 'round', 'set', 'setattr', 'slice', 'sorted', 'staticmethod', 'st
-   r', 'str8', 'sum', 'super', 'trunc', 'tuple', 'type', 'vars', 'zip']
+   Error', 'BytesWarning', 'DeprecationWarning', 'EOFError', 'Ellipsis', 'Environme
+   ntError', 'Exception', 'False', 'FloatingPointError', 'FutureWarning', 'Generato
+   rExit', 'IOError', 'ImportError', 'ImportWarning', 'IndentationError', 'IndexErr
+   or', 'KeyError', 'KeyboardInterrupt', 'LookupError', 'MemoryError', 'NameError',
+    'None', 'NotImplemented', 'NotImplementedError', 'OSError', 'OverflowError', 'P
+   endingDeprecationWarning', 'ReferenceError', 'RuntimeError', 'RuntimeWarning', '
+   StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError', 'SystemExit', 'Ta
+   bError', 'True', 'TypeError', 'UnboundLocalError', 'UnicodeDecodeError', 'Unicod
+   eEncodeError', 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserW
+   arning', 'ValueError', 'Warning', 'ZeroDivisionError', '__build_class__', '__deb
+   ug__', '__doc__', '__import__', '__name__', '__package__', 'abs', 'all', 'any',
+   'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'chr', 'classmethod', 'compile', '
+   complex', 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod', 'enumerate
+   ', 'eval', 'exec', 'exit', 'filter', 'float', 'format', 'frozenset', 'getattr',
+   'globals', 'hasattr', 'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance',
+    'issubclass', 'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memory
+   view', 'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property'
+   , 'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice', 'sort
+   ed', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars', 'zip']
 
 .. _tut-packages: