update docs

1 files changed, 42 insertions, 8 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 34f3ed4..6b4b188 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,12 +11,13 @@ Usage
 The current version of wheel can be used to speed up repeated
 installations by reducing the number of times you have to compile your
 software. When you are creating a virtualenv for each revision of your
-software, the savings can be dramatic. This example packages pyramid
+software the savings can be dramatic. This example packages pyramid
 and all its dependencies as wheels, and then installs pyramid from the
 built packages::
 
-        # Install a version of pip that supports wheel
-        pip install -e git+https://github.com/pypa/pip#egg=pip
+        # Make sure you have the latest pip that supports wheel
+        pip install --upgrade pip
+
         # Install wheel
         pip install wheel
 
@@ -29,6 +30,11 @@ built packages::
 For lxml, an up to 3-minute "search for the newest version and compile"
 can become a less-than-1 second "unpack from wheel".
 
+As a side effect the wheel directory, "/tmp/wheelhouse" in the example,
+contains installable copies of the exact versions of your application's
+dependencies. the dependencies.  By installing from those cached wheels
+you can recreate that environment quickly and with no surprises.
+
 To build an individual wheel, run ``python setup.py bdist_wheel``.  Note that
 ``bdist_wheel`` only works with distribute (``import setuptools``); plain
 ``distutils`` does not support pluggable commands like ``bdist_wheel``.  On
@@ -40,24 +46,52 @@ even when distribute or pip has not been installed.
 
 Wheel's builtin utility can be invoked directly from wheel's own wheel::
 
-    $ python wheel-0.14.0-py2.py3-none-any.whl/wheel -h
-    usage: wheel [-h] {keygen,sign,verify,unpack,install,convert,help} ...
+    $ python wheel-0.21.0-py2.py3-none-any.whl/wheel -h
+    usage: wheel [-h]
+                 
+                 {keygen,sign,unsign,verify,unpack,install,install-scripts,convert,help}
+                 ...
 
     positional arguments:
-      {keygen,sign,verify,unpack,install,convert,help}
+      {keygen,sign,unsign,verify,unpack,install,install-scripts,convert,help}
                             commands
         keygen              Generate signing key
         sign                Sign wheel
-        unsign              Remove signature from wheel
-        verify              Verify signed wheel
+        unsign              Remove RECORD.jws from a wheel by truncating the zip
+                            file. RECORD.jws must be at the end of the archive.
+                            The zip file must be an ordinary archive, with the
+                            compressed files and the directory in the same order,
+                            and without any non-zip content after the truncation
+                            point.
+        verify              Verify a wheel. The signature will be verified for
+                            internal consistency ONLY and printed. Wheel's own
+                            unpack/install commands verify the manifest against
+                            the signature and file contents.
         unpack              Unpack wheel
         install             Install wheels
+        install-scripts     Install console_scripts
         convert             Convert egg or wininst to wheel
         help                Show this help
 
     optional arguments:
       -h, --help            show this help message and exit
 
+Setuptools scripts handling
+---------------------------
+
+Setuptools' popular `console_scripts` and `gui_scripts` entry points can
+be used to generate platform-specific scripts wrappers.  Most usefully
+these wrappers include `.exe` launchers if they are generated on a
+Windows machine.
+
+By default `bdist_wheel` puts pre-generated versions of these wrappers
+into the `*.data/scripts/` directory of the archive.  This means a
+Windows user may have trouble running scripts from a wheel generated
+on Unix and vice-versa.  As of version 0.21.0 `python setup.py
+bdist_wheel --skip-scripts` is available to create wheels that do not
+contain the setuptools script wrappers. The wheel tool `python -m wheel
+install-scripts packagename` calls setuptools to write the appropriate
+scripts wrappers after an install.
 
 Automatically sign wheel files
 ------------------------------