Further documentation update and cleanup of comments

doc/tutorial.txt

@@ -863,8 +863,8 @@ Installing scripts
 
    If a distribution doesn't use setuptools, it may not declare it's entry
    points. In that case, you can specify entry points in the recipe data.
-   Buildout *does attempt* to detect distutils-style scripts without an entry
-   point and will generate a script for them when found.
+   Buildout *does* detect distutils-style scripts without an entry point in
+   case the egg is unzipped and will generate a script for them when found.
   
 Script initialization
 =====================

src/zc/buildout/easy_install.py

@@ -932,16 +932,20 @@ def scripts(reqs, working_set, executable, dest,
         if isinstance(req, str):
             req = pkg_resources.Requirement.parse(req)
             dist = working_set.find(req)
-            # entry points
+            # regular console_scripts entry points
             for name in pkg_resources.get_entry_map(dist, 'console_scripts'):
                 entry_point = dist.get_entry_info('console_scripts', name)
                 entry_points.append(
                     (name, entry_point.module_name,
                      '.'.join(entry_point.attrs))
                     )
-            # distutils scripts
+            # "old-style" distutils scripts
             if os.path.isdir(dist.location):
-                # TODO: what about zipped eggs?
+                # The metadata on scripts is not retained by
+                # distutils/setuptools, except by placing the original scripts
+                # in /EGG-INFO/scripts/. os.listdir() is used to detect them.
+                # Zipped eggs would need unpacking for this to work, which is
+                # too resource intensive, so zipped eggs are not supported.
                 scripts_dir = os.path.join(dist.location, 'EGG-INFO', 'scripts')
                 if os.path.exists(scripts_dir):
                     for name in os.listdir(scripts_dir):
@@ -1075,7 +1079,6 @@ def _distutils_script(path, dest, original_file, executable, initialization, rse
         # The script doesn't follow distutil's rules.  Ignore it.
         return []
     original_content = ''.join(lines[1:])
-    # TODO: does this work OK with non-ascii characters?
     contents = distutils_script_template % dict(
         python = _safe_arg(executable),
         path = path,

src/zc/buildout/easy_install.txt

@@ -929,10 +929,10 @@ Buildout also installs those:
     >>> ls(distbin)
     -  distutilsscript
 
-Distutils copies the specified script files verbatim, apart from a line at the
-top that looks like ``#!/usr/bin/python``, which gets replaced by the actual
-python interpreter.  Buildout does the same, but additionally also adds the
-sys.path like for the console_scripts:
+Distutils copies the script files verbatim, apart from a line at the top that
+looks like ``#!/usr/bin/python``, which gets replaced by the actual python
+interpreter.  Buildout does the same, but additionally also adds the sys.path
+like for the console_scripts:
 
     >>> cat(distbin, 'distutilsscript')
     #!/usr/local/bin/python2.4
@@ -948,6 +948,9 @@ sys.path like for the console_scripts:
 Due to the nature of distutils scripts, buildout cannot pass arguments as
 there's no specific method to pass them to.
 
+A second restriction is that scripts are only detected if the eggs are
+unzipped.  Unzipping all zipped eggs for detecting old-style distutils scripts
+is a bit wasteful.
 
 Handling custom build options for extensions provided in source distributions
 -----------------------------------------------------------------------------