More doc updates

edschofield · edschofield · commit e72a3d0021e4 · 2014-01-28T23:32:53.000+11:00
diff --git a/README.rst b/README.rst
@@ -32,7 +32,7 @@ Features
 -   ``past.translation`` package supports transparent translation of Python 2
     modules to Python 3 upon import. [This feature is currently in alpha.] 
 
--   330+ unit tests
+-   470+ unit tests
 
 -   ``futurize`` and ``pasteurize`` scripts based on ``2to3`` and parts of
     ``3to2`` and ``python-modernize``, for automatic conversion from either Py2
@@ -139,9 +139,9 @@ the block::
 Automatic translation
 ---------------------
 
-The ``past`` package can now automatically and transparently translate some
-Python 2 modules to Python 3 upon import. For example, here is how to use a
-Python 2-only package called ``plotrique`` on Python 3. First install it::
+The ``past`` package can now automatically translate some simple Python 2
+modules to Python 3 upon import. For example, here is how to use a Python 2-only
+package called ``plotrique`` on Python 3. First install it::
 
     $ pip3 install plotrique==0.2.5-7 --no-compile   # to ignore SyntaxErrors
     
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -119,10 +119,10 @@ Is it tested?
 -------------
 
 ``future`` is used by ``mezzanine``, among other projects. Currently
-``future`` has 330+ unit tests.  In general, the ``future`` package
-itself is in good shape, whereas the ``futurize`` script for automatic
-porting is incomplete and imperfect. (Chances are it will require some
-manual cleanup afterwards.)
+``future`` has 470+ unit tests. Many of these are straight from the Python 3.3
+test suite. In general, the ``future`` package itself is in good shape, whereas
+the ``futurize`` script for automatic porting is incomplete and imperfect.
+(Chances are it will require some manual cleanup afterwards.)
     
 Is the API stable?
 ------------------
diff --git a/docs/overview_new.rst b/docs/overview_new.rst
diff --git a/docs/translation.rst b/docs/translation.rst
@@ -88,10 +88,21 @@ This is a standard Python 3 data type, so, when called from Python 3 code,
 Known limitations of ``past.translation``
 *******************************************
 
-- The source translation feature offered by the ``past.translation``
-package has some of the same limitations as the ``futurize`` script (see
-:ref:`futurize-limitations`). Help developing and testing this feature further
-would be particularly welcome.
+- This only works with pure-Python modules. C extension modules and Cython code
+  are not supported.
+
+- The biggest hurdle to automatic translation is likely to be ambiguity
+  about byte-strings and text (unicode strings) in the Python 2 code. If the
+  ``past.autotranslate`` feature fails because of this, you could try
+  running ``futurize`` over the code and adding a ``b''`` or ``u''`` prefix to
+  the relevant string literals. To convert between byte-strings and text (unicode
+  strings), add an ``.encode`` or ``.decode`` method call. If this succeeds,
+  please push your patches upstream to the package maintainers.
+
+- Otherwise, the source translation feature offered by the ``past.translation``
+  package has similar limitations to the ``futurize`` script (see
+  :ref:`futurize-limitations`). Help developing and testing this feature further
+  would be particularly welcome.
 
 Please report any bugs you find on the ``python-future`` `bug tracker
 <https://github.com/PythonCharmers/python-future/>`_.
