[docs] Improve doc for str(bytesobject) (issue 13538)

[ezio.melotti at gmail.com]

http://bugs.python.org/review/13538/diff/6626/Doc/library/functions.rst
File Doc/library/functions.rst (right):

http://bugs.python.org/review/13538/diff/6626/Doc/library/functions.rst#newcode1277
Doc/library/functions.rst:1277: :class:`bytes` (or :class:`bytearray`)
object in this case, then
On 2012/11/19 11:32:39, cjerdonek wrote:
> The latter was intended.  This may be clearer if "In this case" is at
the
> beginning of the sentence.  Without the phrase, it has an ambiguous
feeling to
> me.  The second sentence could be interpreted to be an additional
implication
> rather than a refinement of the previous implication.  For example,
the first
> sentence says that *object* needs to be a bytes object.  The second
sentence
> could then be saying what happens for bytes objects, but in all cases.
 That
> also seems like a natural way of explaining something.
> 
> I also feel the extra clarity is deserved here because this point
about bytes is
> a source of confusion -- so much so that we added an extra paragraph
and example
> to clarify.  I realize that if the reader reads the next paragraph, it
will
> dispel the ambiguity we're discussing here, but I think it's worth
having the
> paragraph be unambiguous when read alone.

Putting it at the beginning of the sentence sounds better.

http://bugs.python.org/review/13538/diff/6626/Doc/library/functions.rst#newcode1285
Doc/library/functions.rst:1285: or *errors* arguments uses the first
mode of returning the informal string
On 2012/11/19 11:32:39, cjerdonek wrote:
> I don't especially like the word "mode" either. :)  I was just keeping
with what
> was originally used in the first sentence of the str() docs.  Why
didn't you
> object to it there? :)
> 

I don't like it there either, but here it has the additional problem
that you have to go back to find which one is the first mode.

> Can you suggest a rephrasing of the first sentence ("... using one of
the
> following two modes.") that allows us to use parallel phrasing in the
subsequent
> paragraphs?  I like telling the reader in advance that there are two
of
> "something" and because it parallels the two signatures.  Also, saying
first or
> second helps because then the reader knows whether to look in the
first or
> second of the two paragraphs (without having to interpret the text and
then map
> it to the corresponding paragraph themselves).  Both may be best
(number and
> description).

Maybe something similar to
"""
The behavior of str() depends on whether the encoding and errors args
are provided::
 * if they are not provided ...
 * if they are provided ...
"""

Then you can use "in the first case" instead of "the first mode". 
Another option is to put this in the first case directly, and say
something like "This is also valid for bytes, however the behavior is
different if encoding and errors are passed.
* if they are provided ..."

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