doc fixes per review.

CHANGES.txt

@@ -11,19 +11,17 @@ New Features:
   than zc.recipe.egg (which is still a fully supported, and simpler, way of
   generating scripts and interpreters if you are using a "clean" Python).
 
-  A hopefully slight limitation: in no cases are distributions in your
-  site-packages used to satisfy buildout dependencies.  The
-  site-packages can be used in addition to the dependencies specified in
-  your buildout, and buildout dependencies can override code in your
-  site-packages, but even if your Python's site-packages has the same
-  exact version as specified in your buildout configuration, buildout
-  will still use its own copy.
+  (Note that this branch is incomplete in its implementation of this feature:
+  if eggs are in installed in site-packages but you do not want to use
+  site-packages, the eggs will drag in site-packages even if you try to
+  exclude it.  This is addressed in subsequent branches in the series of
+  which this one is a part.)
 
 - Added new function, ``zc.buildout.easy_install.sitepackage_safe_scripts``,
   to generate scripts and interpreter.  It produces a full-featured
   interpreter (all command-line options supported) and the ability to
-  safely let scripts include site packages.  The ``z3c.recipe.scripts``
-  recipe uses this new function.
+  safely let scripts include site packages, such as with a system
+  Python.  The ``z3c.recipe.scripts`` recipe uses this new function.
 
 - Improve bootstrap.
 

README.txt

@@ -35,12 +35,15 @@ Existing recipes include:
 `zc.recipe.egg <http://pypi.python.org/pypi/zc.recipe.egg>`_
    The egg recipe installes one or more eggs, with their
    dependencies.  It installs their console-script entry points with
-   the needed eggs included in their paths.
+   the needed eggs included in their paths.  It is suitable for use with
+   a "clean" Python: one without packages installed in site-packages.
 
 `z3c.recipe.scripts <http://pypi.python.org/pypi/z3c.recipe.scripts>`_
-  This scripts recipe builds interpreter scripts and entry point scripts
-  based on eggs.  These scripts have more features and flexibility than the
-  ones offered by zc.recipe.egg.
+  Like zc.recipe.egg, this recipe builds interpreter scripts and entry
+  point scripts based on eggs.  It can be used with a Python that has
+  packages installed in site-packages, such as a system Python.  The
+  interpreter also has more features than the one offered by
+  zc.recipe.egg.
 
 `zc.recipe.testrunner <http://pypi.python.org/pypi/zc.recipe.testrunner>`_
    The testrunner egg creates a test runner script for one or

src/zc/buildout/easy_install.py

@@ -1018,7 +1018,7 @@ def sitepackage_safe_scripts(
         site_py_dest, working_set, executable, extra_paths,
         add_site_packages, relative_paths))
     script_initialization = (
-        '\nimport site # imports custom buildbot-generated site.py\n%s' % (
+        '\nimport site # imports custom buildout-generated site.py\n%s' % (
             script_initialization,))
     if not script_initialization.endswith('\n'):
         script_initialization += '\n'
@@ -1302,7 +1302,7 @@ if _interactive:
 # These are used only by the newer ``sitepackage_safe_scripts`` function.
 
 def _get_system_paths(executable):
-    """return lists of standard lib and site paths for executable.
+    """Return lists of standard lib and site paths for executable.
     """
     # We want to get a list of the site packages, which is not easy.
     # The canonical way to do this is to use

src/zc/buildout/easy_install.txt

@@ -1171,7 +1171,7 @@ packages.  This has some advantages and some serious dangers.
 
 A typical reason to include site-packages is that it is easier to
 install one or more dependencies in your Python than it is with
-buildbot.  Some packages, such as lxml or Python PostgreSQL integration,
+buildout.  Some packages, such as lxml or Python PostgreSQL integration,
 have dependencies that can be much easier to build and/or install using
 other mechanisms, such as your operating system's package manager.  By
 installing some core packages into your Python's site-packages, this can
@@ -1428,7 +1428,7 @@ The demo script runs the entry point defined in the demo egg:
         ]
     <BLANKLINE>
     <BLANKLINE>
-    import site # imports custom buildbot-generated site.py
+    import site # imports custom buildout-generated site.py
     <BLANKLINE>
     import eggrecipedemo
     <BLANKLINE>
@@ -1467,7 +1467,7 @@ Let's see ``script_arguments`` and ``script_initialization`` in action.
       '/interpreter/parts/interpreter',
       ]
     <BLANKLINE>
-    import site # imports custom buildbot-generated site.py
+    import site # imports custom buildout-generated site.py
     import os
     os.chdir("foo")
     <BLANKLINE>

z3c.recipe.scripts_/src/z3c/recipe/scripts/README.txt

@@ -47,7 +47,7 @@ extends
 exec-sitecustomize
     Normally the Python's real sitecustomize module is not processed.
     If you want it to be processed, set this value to 'true'.  This will
-    be honored irrespective of the setting for include-site-paths.
+    be honored irrespective of the setting for add-site-packages.
 
 script-initialization
     The standard initialization code affects both an interpreter and scripts.
@@ -181,7 +181,7 @@ some advantages and some serious dangers.
 
 A typical reason to include site-packages is that it is easier to
 install one or more dependencies in your Python than it is with
-buildbot.  Some packages, such as lxml or Python PostgreSQL integration,
+buildout.  Some packages, such as lxml or Python PostgreSQL integration,
 have dependencies that can be much easier to build and/or install using
 other mechanisms, such as your operating system's package manager.  By
 installing some core packages into your Python's site-packages, this can
@@ -399,5 +399,4 @@ interpreter, so that you are not forced to use the name of the section.
     42
     <BLANKLINE>
 
-The other options all identical to the zc.recipe.egg script.  Here are some
-quick demos and discussions.
+The other options all identical to zc.recipe.egg.

z3c.recipe.scripts_/src/z3c/recipe/scripts/tests.py

@@ -25,7 +25,7 @@ from zope.testing import doctest, renormalizing
 # all of the examples.  The README tests ``extends``,
 # ``include-site-customization`` and ``name``.  That leaves ``python``,
 # ``extra-paths``, ``initialization``, ``relative-paths``, and
-# ``include-site-packages``.
+# ``add-site-packages``.
 
 def supports_python_option():
     """