Close #4966: revamp the sequence docs in order to better explain the state of modern Python

Doc/library/binary.rst

@@ -0,0 +1,23 @@
+.. _binaryservices:
+
+********************
+Binary Data Services
+********************
+
+The modules described in this chapter provide some basic services operations
+for manipulation of binary data. Other operations on binary data, specifically
+in relation to file formats and network protocols, are described in the
+relevant sections.
+
+Some libraries described under :ref:`textservices` also work with either
+ASCII-compatible binary formats (for example, :mod:`re`) or all binary data
+(for example, :mod:`difflib`).
+
+In addition, see the documentation for Python's built-in binary data types in
+:ref:`binaryseq`.
+
+.. toctree::
+
+   struct.rst
+   codecs.rst
+

Doc/library/index.rst

@@ -46,7 +46,8 @@ the `Python Package Index <http://pypi.python.org/pypi>`_.
    stdtypes.rst
    exceptions.rst
 
-   strings.rst
+   text.rst
+   binary.rst
    datatypes.rst
    numeric.rst
    functional.rst

Doc/library/strings.rst

@@ -1,27 +0,0 @@
-.. _stringservices:
-
-***************
-String Services
-***************
-
-The modules described in this chapter provide a wide range of string
-manipulation operations.
-
-In addition, Python's built-in string classes support the sequence type methods
-described in the :ref:`typesseq` section, and also the string-specific methods
-described in the :ref:`string-methods` section.  To output formatted strings,
-see the :ref:`string-formatting` section. Also, see the :mod:`re` module for
-string functions based on regular expressions.
-
-
-.. toctree::
-
-   string.rst
-   re.rst
-   struct.rst
-   difflib.rst
-   textwrap.rst
-   codecs.rst
-   unicodedata.rst
-   stringprep.rst
-

Doc/library/text.rst

@@ -0,0 +1,24 @@
+.. _stringservices:
+.. _textservices:
+
+************************
+Text Processing Services
+************************
+
+The modules described in this chapter provide a wide range of string
+manipulation operations and other text processing services.
+
+The :mod:`codecs` module described under :ref:`binaryservices` is also
+highly relevant to text processing. In addition, see the documentation for
+Python's built-in string type in :ref:`textseq`.
+
+
+.. toctree::
+
+   string.rst
+   re.rst
+   difflib.rst
+   textwrap.rst
+   unicodedata.rst
+   stringprep.rst
+

Doc/whatsnew/3.3.rst

@@ -830,7 +830,10 @@ Builtin functions and types
 * The :class:`str` type gets a new :meth:`~str.casefold` method: return a
   casefolded copy of the string, casefolded strings may be used for caseless
   matching. For example, ``'ß'.casefold()`` returns ``'ss'``.
-
+* The sequence documentation has been substantially rewritten to better
+  explain the binary/text sequence distinction and to provide specific
+  documentation sections for the individual builtin sequence types
+  (:issue:`4966`)
 
 New Modules
 ===========

Misc/NEWS

@@ -55,6 +55,9 @@ Tools/Demos
 Documentation
 -------------
 
+- Issue #4966: Bring the sequence docs up to date for the Py3k transition
+  and the many language enhancements since they were original written
+
 - The "path importer" misnomer has been replaced with Eric Snow's
   more-awkward-but-at-least-not-wrong suggestion of "path based finder" in
   the import system reference docs