Docs: update overview

edschofield · edschofield · commit 03d0425bbfe1 · 2014-01-25T17:51:09.000+11:00
diff --git a/docs/overview.rst b/docs/overview.rst
@@ -8,11 +8,11 @@ Overview
 Python 2. It allows you to maintain a single, clean Python 3.x-compatible
 codebase with minimal cruft and run it easily on Python 2 mostly unchanged.
 
-It provides ``future`` and ``past`` packages with backports and forward ports
-of features from Python 3 and 2. It also comes with ``futurize``, a customized
-2to3-based script that helps you to convert code easily to supporting
-both Python 2 and 3 in a single codebase, module by module, from either
-Python 2 or Python 3.
+It provides ``future`` and ``past`` packages with backports and forward ports of
+features from Python 3 and 2. It also comes with ``futurize`` and
+``pasteurize``, customized 2to3-based scripts that helps you to convert either
+Py2 or Py3 code easily to support both Python 2 and 3 in a single clean
+Py3-style codebase, module by module.
 
 
 .. _features:
@@ -26,20 +26,21 @@ Features
 -   ``future`` package provides backports and remappings from the Py3 standard
     library
 
+-   ``future.translation`` package supports transparent translation of
+    Python 2 modules to Python 3 upon import. [This feature is currently in
+    alpha.] 
+
 -   330+ unit tests
 
--   ``futurize`` script based on ``2to3`` and parts of ``3to2`` and
-    ``python-modernize``, for automatic conversion from either Py2 or Py3
-    to a clean single-source codebase compatible with Python 2.6+ and
+-   ``futurize`` and ``pasteurize`` scripts based on ``2to3`` and parts of
+    ``3to2`` and ``python-modernize``, for automatic conversion from either Py2
+    or Py3 to a clean single-source codebase compatible with Python 2.6+ and
     Python 3.3+.
 
--   a comprehensive set of utility functions and decorators selected from
+-   a curated set of utility functions and decorators selected from
     Py2/3 compatibility interfaces from projects like ``six``, ``IPython``,
     ``Jinja2``, ``Django``, and ``Pandas``.
 
--   ``future.translation`` package supports transparent translation of
-    Python 2 modules to Python 3 upon import. [Experimental] 
-
 -   ``past`` package provides forward-ports of Python 2 types and resurrects
     some Python 2 builtins (to aid with per-module code migrations)
 
@@ -154,9 +155,17 @@ Example::
     >>> autotranslate('plotrique')
     >>> import plotrique
 
-Note: this feature is still in alpha and needs more testing and
-development to support a full range of real-world Python 2 modules.
+This transparently translates and runs the ``plotrique`` module and any
+submodules in the ``plotrique`` package that ``plotrique`` imports.
+
+This is intended to help you migrate to Python 3 without the need for all
+your code's dependencies to support Python 3 yet. It should be used as a
+last resort; ideally Python 2-only dependencies should be ported
+properly to a Python 2/3 compatible codebase using a tool like
+``futurize`` and the changes should be pushed to the upstream project.
 
+Note: the translation feature is still in alpha and needs more testing and
+development to support a full range of real-world Python 2 modules.
 
 
 Next steps
