Issue #20208: Clarify some things in the Python porting HOWTO.

Thanks to Rodrigo Bernardo Pimentel, Ondřej Čertík, and Dmitry
Shachnev for the feedback leading to the changes.

diff --git a/Doc/howto/pyporting.rst b/Doc/howto/pyporting.rst
index ebee60fddb973f7ca7c587f924d403326e8bbb95..d6ad40161d5c93fe2b04408de2cde9cefd296e0f 100644 (file)
--- a/Doc/howto/pyporting.rst
+++ b/Doc/howto/pyporting.rst
@@ -151,15 +151,17 @@ older).
 ``from __future__ import unicode_literals``
 '''''''''''''''''''''''''''''''''''''''''''
 
-If you choose not to use this future statement you should then mark all of your
+If you choose to use this future statement then all string literals in
+Python 2 will be assumed to be Unicode (as is already the case in Python 3).
+If you choose not to use this future statement then you should mark all of your
 text strings with a ``u`` prefix and only support Python 3.3 or newer. But you
 are **strongly** advised to do one or the other (six_ provides a function in
 case you don't want to use the future statement **and** you want to support
 Python 3.2 or older).
 
 
-Bytes literals
-''''''''''''''
+Bytes/string literals
+'''''''''''''''''''''
 
 This is a **very** important one. Prefix Python 2 strings that
 are meant to contain bytes with a ``b`` prefix to very clearly delineate
@@ -504,12 +506,13 @@ your time and effort to port your tests to :mod:`unittest`.
 Update ``map`` for imbalanced input sequences
 '''''''''''''''''''''''''''''''''''''''''''''
 
-With Python 2, ``map`` would pad input sequences of unequal length with
-`None` values, returning a sequence as long as the longest input sequence.
+With Python 2, when ``map`` was given more than one input sequence it would pad
+the shorter sequences with `None` values, returning a sequence as long as the
+longest input sequence.
 
 With Python 3, if the input sequences to ``map`` are of unequal length, ``map``
 will stop at the termination of the shortest of the sequences. For full
-compatibility with ``map`` from Python 2.x, also wrap the sequences in
+compatibility with ``map`` from Python 2.x, wrap the sequence arguments in
 :func:`itertools.zip_longest`, e.g. ``map(func, *sequences)`` becomes
 ``list(map(func, itertools.zip_longest(*sequences)))``.
 
@@ -518,9 +521,8 @@ Eliminate ``-3`` Warnings
 
 When you run your application's test suite, run it using the ``-3`` flag passed
 to Python. This will cause various warnings to be raised during execution about
-things that 2to3 cannot handle automatically (e.g., modules that have been
-removed). Try to eliminate those warnings to make your code even more portable
-to Python 3.
+things that are semantic changes between Python 2 and 3. Try to eliminate those
+warnings to make your code even more portable to Python 3.
 
 
 Alternative Approaches