--- a/carton.py	Sun Jul 10 18:50:49 2011 -0700
+++ b/carton.py	Mon Jul 11 09:09:48 2011 -0700
@@ -1,15 +1,34 @@
 #!/usr/bin/env python
 
 """
-make a self-extracting virtualenv from directories or URLs
-of packages
+make a self-extracting virtualenv from directories or URLs of packages
+
+To package up all files in a virtualenvs source directory (e.g.)::
 
-To package up all files in a virtualenvs source directory (e.g.):
+  python path/to/carton.py myproject project/src/* 
+
+This will create a self-extracting file, `myproject.py`, that will unfold
+a virtualenv with the specified packages setup for development
 
-python path/to/carton.py mozmill mozmill/src/*
+The sources may be directories, local or HTTP-accessible tarballs, or ordinary
+files. The `setup.py`s found in the `src` directory after extraction will be
+run (via `python setup.py develop`) in the order they are provided. This makes
+it possible to have completely local dependencies (without touching the net)
+by correctly specifying the source order.  If a `setup.py` is overwritten from
+a later source, it will not be rerun (known limitation).
 
-This will create a self-extracting file, `mozmill.py`, that will unfold
-a virtualenv with the specified packages setup for development
+The extracted virtualenv will be created in the current directory and will have
+the same name as provided initially (e.g. `myproject`) unless `--env` is
+specified.
+
+Normally, the entire contents of source directories are compressed and
+packaged as-is.  When running with the `--package` flag, a source tarball is
+produced via `python setup.py sdist` if the directory contains a top-level
+`setup.py`.
+
+Since directories are compressed as-is, portable file-based VCS repositories,
+such a mercurial and git, may be cartoned this way (though note that newer
+repositories may not be backwards-compatible with older clients).
 """
 
 # imports
@@ -116,6 +135,7 @@
         subdir = os.path.join(srcdir, i)
         if os.path.exists(os.path.join(srcdir, i, 'setup.py')):
             call([python, 'setup.py', 'develop'], cwd=subdir)
+            # TODO: try `setup.py install` if develop fails for distutils packages
             setup_pys.add(i)
 
 # add virtualenv to the virtualenv (!)