Add str_object.rst to "What Else" chapter

edschofield · edschofield · commit 82ae4812965f · 2013-10-02T10:46:05.000+10:00
diff --git a/docs/source/str_object.rst b/docs/source/str_object.rst
@@ -4,12 +4,15 @@ str
 -----
 
 The :class:`str` object in Python 3 is quite similar but not identical to the
-Python 2 :class:`unicode` object. The major differences are:
+Python 2 :class:`unicode` object.
 
-- repr of unicode strings in Py2 is "u'...'" versus "'...'"
-- stricter type-checking in Py3 to enforce the distinction between unicode
-  strings and byte-strings, such as when comparing, concatenating, joining, or
-  replacing parts of strings.
+The major difference is the stricter type-checking with Py3 ``str`` to enforce
+the distinction between unicode strings and byte-strings, such as when
+comparing, concatenating, joining, or replacing parts of strings.
+
+There are also minor differences, such as the ``repr`` of unicode strings in
+Py2 having a ``"u'...'"`` prefix, versus simply ``"'...'"``, and the removal of
+the :func:`str.decode` method in Py3.
 
 ``future`` contains a backport of the :mod:`str` object from Python 3 which
 inherits from the Python 2 :class:`unicode` class but has customizations to
@@ -46,8 +49,9 @@ behaviours to Python 3's :class:`str`::
     >>> assert list(s) == ['A', 'B', 'C', 'D']
     >>> assert s.split('B') == ['A', 'CD']
 
-Currently the easiest way to ensure identical use of strings in a Py3/2
-codebase is to wrap string literals in a :func:`~str` call, as follows::
+Currently the easiest way to ensure identical use of (unicode) strings across
+Py3 and Py2 in a single-source codebase is to wrap string literals in a
+:func:`~str` call, as follows::
     
     from __future__ import unicode_literals
     from future.builtins import *
@@ -59,7 +63,7 @@ codebase is to wrap string literals in a :func:`~str` call, as follows::
     # ...
 
 Most of the time this is unnecessary, but the stricter type-checking of the
-``future.builtins.str`` object, in particular, may be useful while ensuring
-that Py2's unicode strings are not mixed up with implicit coercions from
-byte-strings.
+``future.builtins.str`` object, in particular, may be useful for ensuring
+the same consistent separation between unicode and byte strings on Py2 as on
+Py3.
 
diff --git a/docs/source/what_else.rst b/docs/source/what_else.rst
@@ -13,6 +13,7 @@ Essentials
 ==========
 
 .. include:: bytes_object.rst
+.. include:: str_object.rst
 .. include:: dict_methods.rst
 .. include:: custom_str_methods.rst
 .. include:: custom_iterators.rst
