[docs] 'codecs' module docs improvements (issue 19548)

[zuo at chopin.edu.pl]

A few remarks from a perspective of a person who still does not
understand all nooks and crannies of the Python codecs system and the
*codecs* module.


http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst
File Doc/library/codecs.rst (right):

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode24
Doc/library/codecs.rst:24: but there are also codecs that encode text to
text, and bytes to bytes.
Shouldn't be a note about arbitrary-types codecs added *here*?

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode164
Doc/library/codecs.rst:164: .. function:: register_error(name,
error_handler)
For this function and the functions described below, the above sentence
"To simplify access to the various codecs, the module provides these
additional functions which use :func:`lookup` for the codec lookup:"
(line 112) is not appropriate.  Some other sentence should be placed
here (introducing error-handling-related functions.

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode182
Doc/library/codecs.rst:182: Decoding and translating works similarly,
except :exc:`UnicodeDecodeError` or
Possible beginner's questions: What is "translating"? When it is
performed? How can it be differentiated from subsequent encoding +
decoding?

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode250
Doc/library/codecs.rst:250: :func:`open` function; the ``'b'`` is
automatically added.
I would add something like: "Please note that when you need to use just
an ordinary :term:`text encoding` the built-in :func:`open` function is
the recommended (and, typically, more efficient) way to operate on text
files".

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode325
Doc/library/codecs.rst:325: .. _surrogateescape:
Should be moved to the place above the ".. _error-handlers:" line (341).

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode335
Doc/library/codecs.rst:335: Each codec has to define four interfaces to
make it usable as codec in Python:
Possible beginner's questions: is a codec an instance of :class:`Codec`?
Or of :class:`CodecInfo`? What does it mean that it define those *four*
intefraces? How is it related to the
stateless/incremental/decoder/encoder and stream writer/reader classes
described below? Why here only *four* interfaces and not *six*
interfaces are mentioned? (i.e., what about *incremental encoder* and
*incremental decoder?*)

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode687
Doc/library/codecs.rst:687: providing the *errors* keyword argument.
These parameters are defined:
The "parameters" word does not seem to be the correct term here...

http://bugs.python.org/review/19548/diff/13486/Doc/library/codecs.rst#newcode689
Doc/library/codecs.rst:689: * ``'strict'`` Raise :exc:`ValueError` (or a
subclass); this is the default.
Only these three and not, e.g. 'surrogateescape'?
Shouldn't be a reference to ".. _error-handlers:" be used here instead
of this enumeration? (with a caution that the "only for encoding"
handlers are disallowed)

http://bugs.python.org/review/19548/