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

ncoghlan · ncoghlan · commit 273069cf7d79 · 2012-08-20T17:14:07.000+10:00
diff --git a/Doc/library/binary.rst b/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
+
diff --git a/Doc/library/index.rst b/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
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
diff --git a/Doc/library/strings.rst b/Doc/library/strings.rst
diff --git a/Doc/library/text.rst b/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
+
diff --git a/Doc/whatsnew/3.3.rst b/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
 ===========
diff --git a/Misc/NEWS b/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
