Recommend installation into virtual environment

And other assorted formatting/language tweaks.

README.rst

@@ -22,17 +22,25 @@ even when you've pinned them.  `You do pin them, right?`_
 Installation
 ============
 
+As part of a Python project's environment tooling (similar to ``pip``), it's
+recommended to install ``pip-tools`` in each project's `virtual environment`_:
+
 .. code-block:: bash
 
-    $ pip install --upgrade pip  # pip-tools needs pip==8.0 or higher (!)
-    $ pip install pip-tools
+    $ source /path/to/venv/bin/activate
+    (venv)$ pip install --upgrade pip  # pip-tools needs pip==8.0 or higher (!)
+    (venv)$ pip install pip-tools
+
+**Note**: all of the remaining example commands assume you've activated your
+project's virtual environment.
 
+.. _virtual environment: https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments
 
 Example usage for ``pip-compile``
 =================================
 
-Requirements from setup.py
---------------------------
+Requirements from ``setup.py``
+------------------------------
 
 Suppose you have a Flask project, and want to pin it for production.
 If you have a ``setup.py`` with ``install_requires=['Flask']``, then run
@@ -55,21 +63,21 @@ If you have a ``setup.py`` with ``install_requires=['Flask']``, then run
     werkzeug==0.12.2          # via flask
 
 ``pip-compile`` will produce your ``requirements.txt``, with all the Flask
-dependencies (and all underlying dependencies) pinned.  You should put your
-requirements file under version control.
+dependencies (and all underlying dependencies) pinned.  You should put
+``requirements.txt`` under version control.
 
-Without setup.py
-----------------
+Without ``setup.py``
+--------------------
 
-If you don't use ``setup.py`` (`it's easy to write one`_), you can instead
-write the following line to a file:
+If you don't use ``setup.py`` (`it's easy to write one`_), you can create a
+``requirements.in`` file to declare the Flask dependency:
 
 .. code-block:: ini
 
     # requirements.in
     Flask
 
-This time, run ``pip-compile requirements.in``:
+Now, run ``pip-compile requirements.in``:
 
 .. code-block:: bash
 
@@ -88,16 +96,16 @@ This time, run ``pip-compile requirements.in``:
     werkzeug==0.12.2          # via flask
 
 And it will produce your ``requirements.txt``, with all the Flask dependencies
-(and all underlying dependencies) pinned.  Don't forget to put this file under
-version control as well.
+(and all underlying dependencies) pinned.  You should put both
+``requirements.in`` and ``requirements.txt`` under version control.
 
 .. _it's easy to write one: https://packaging.python.org/distributing/#configuring-your-project
 
 Using hashes
 ------------
 
-If you would like to use *Hash-Checking Mode* available in *pip* since version
-8.0, ``pip-compile`` offers ``--generate-hashes`` flag:
+If you would like to use *Hash-Checking Mode* available in ``pip`` since
+version 8.0, ``pip-compile`` offers ``--generate-hashes`` flag:
 
 .. code-block:: bash
 
@@ -151,7 +159,7 @@ If you use multiple Python versions, you can run ``pip-compile`` as
 Configuration
 -------------
 
-You might be wrapping the pip-compile command in another script. To avoid
+You might be wrapping the ``pip-compile`` command in another script. To avoid
 confusing consumers of your custom script you can override the update command
 generated at the top of requirements files by setting the
 ``CUSTOM_COMPILE_COMMAND`` environment variable.
@@ -175,11 +183,12 @@ Example usage for ``pip-sync``
 ==============================
 
 Now that you have a ``requirements.txt``, you can use ``pip-sync`` to update
-your virtual env to reflect exactly what's in there.  Note: this will
-install/upgrade/uninstall everything necessary to match the ``requirements.txt``
-contents.
+your virtual environment to reflect exactly what's in there. This will
+install/upgrade/uninstall everything necessary to match the
+``requirements.txt`` contents.
 
-*Be careful: pip-sync is meant to be used only with a pip-compile'd requirements.txt.*
+**Be careful**: ``pip-sync`` is meant to be used only with a
+``requirements.txt`` generated by ``pip-compile``.
 
 .. code-block:: bash
 
@@ -207,6 +216,9 @@ If you use multiple Python versions, you can run ``pip-sync`` as
 ``py -X.Y -m piptools sync ...`` on Windows and
 ``pythonX.Y -m piptools sync ...`` on other systems.
 
+**Note**: ``pip-sync`` will not upgrade or uninstall packaging tools like
+``setuptools``, ``pip``, or ``pip-tools`` itself. Use ``pip install --upgrade``
+to upgrade those packages.
 
 Other useful tools
 ==================