expand a bit on the purpose and use of requirement files

docs/index.txt

@@ -109,7 +109,8 @@ and you get a dozen packages.  Each of these packages has its own version.
 Maybe you ran that installation and it works.  Great!  Will it keep working? 
 Did you have to provide special options to get it to find everything?  Did you
 have to install a bunch of other optional pieces?  Most of all, will you be able
-to do it again?
+to do it again?  Requirements files give you a way to create an *environment*: 
+a *set* of packages that work together.
 
 If you've ever tried to setup an application on a new system, or with slightly
 updated pieces, and had it fail, pip requirements are for you.  If you
@@ -124,11 +125,15 @@ whatever libraries come along, you can create a requirements file something like
     Framework==0.9.4
     Library>=0.2
 
-Then, regardless of what MyApp lists in ``setup.py``, you'll get a specific
-version of Framework and at least the 0.2 version of Library.  (You might think
-you could list these specific versions in ``setup.py`` -- try it and you'll
-quickly see why that doesn't work.)  You can add optional libraries and support
-tools that MyApp doesn't strictly require.
+Then, regardless of what MyApp lists in ``setup.py``, you'll get a
+specific version of Framework (0.9.4) and at least the 0.2 version of
+Library.  (You might think you could list these specific versions in
+MyApp's ``setup.py`` -- but if you do that you'll have to edit MyApp
+if you want to try a new version of Framework, or release a new
+version of MyApp if you determine that Library 0.3 doesn't work with
+your application.)  You can also add optional libraries and support
+tools that MyApp doesn't strictly require, giving people a set of
+recommended libraries.
 
 You can also include "editable" packages -- packages that are checked out from
 Subversion, Git, Mercurial and Bazaar.  These are just like using the ``-e``
@@ -141,6 +146,19 @@ you have to include ``#egg=Package`` so pip knows what to expect at that URL.
 You can also include ``@rev`` in the URL, e.g., ``@275`` to check out
 revision 275.
 
+Requirement files are mostly *flat*.  Maybe ``MyApp`` requires
+``Framework``, and ``Framework`` requires ``Library``.  I encourage
+you to still list all these in a single requirement file; it is the
+nature of Python programs that there are implicit bindings *directly*
+between MyApp and Library.  For instance, Framework might expose one
+of Library's objects, and so if Library is updated it might directly
+break MyApp.  If that happens you can update the requirements file to
+force an earlier version of Library, and you can do that without
+having to re-release MyApp at all.
+
+Read the `requirements file format <requirement-format.html>`_ to
+learn about other features.
+
 Freezing Requirements
 ---------------------
 
@@ -271,4 +289,4 @@ directly with the eval function of you shell, e.g. by adding::
 
     eval `pip completion --bash`
 
-to your startup file.
+to your startup file.

docs/requirement-format.txt

@@ -1,8 +1,10 @@
 The requirements file format
 ============================
 
-The requirements file is what pip uses to install packages.
-This document describes that format.
+The requirements file is a way to get pip to install specific packages
+to make up an *environment*.  This document describes that format.  To
+read about *when* you should use requirement files, see `Requirements
+Files <./#requirements-files>`_.
 
 Each line of the requirements file indicates something to be
 installed.  For example::
@@ -99,3 +101,38 @@ Tags or revisions can be installed like this::
 
     -e bzr+https://bzr.myproject.org/MyProject/trunk/@2019#egg=MyProject
     -e bzr+http://bzr.myproject.org/MyProject/trunk/@v1.0#egg=MyProject
+
+Recursive Requirements
+----------------------
+
+If you wish, you can also refer to other requirements files, like::
+
+    -r Pylons-requirements.txt
+
+This gives you a way of abstracting out sets of requirements.  This
+isn't, however, very friendly with `frozen requirements
+<./#freezing-requirements>`_, as everything in
+``Pylons-requirements.txt`` will show up in your frozen file.
+
+Indexes, find-links
+-------------------
+
+You can also provide values for the ``--index`` and ``--find-links``
+options in your requirement files, like::
+
+    --index http://example.com/private-pypi/
+
+Note that using ``--index`` removes the use of `PyPI
+<http://pypi.python.org>`_, while using ``--extra-index`` will add
+additional indexes.
+
+``--find-links`` is more ad-hoc; instead of a complete "index", you
+only need an HTML page of links to available packages.  Simply by
+putting all your private packages in a directory and using the Apache
+auto-index, you can publish your packages so pip can find them.
+``--find-links`` is always additive; pip looks at everything it can
+find.  Use it like::
+
+    --find-link http://example.com/private-packages/
+
+Note that all these options must be on a line of their own.