Merge pull request #370 from alex-morega/docs

Docs reorganization - thanks Alex Morega

4 files changed, 78 insertions, 41 deletions

diff --git a/docs/glossary.txt b/docs/glossary.txt
new file mode 100644
index 000000000..c9decea5d
--- /dev/null
+++ b/docs/glossary.txt
@@ -0,0 +1,12 @@
+========
+Glossary
+========
+
+.. glossary::
+
+    PyPI
+        The `Python Package Index`_, formerly known as the Cheese Shop,
+        is a central catalog of Python packages. By default, when
+        installing packages,`pip` searches for them in PyPI.
+
+        .. _`Python Package Index`: http://pypi.python.org/pypi
diff --git a/docs/index.txt b/docs/index.txt
index 87ded968c..3f117c0ce 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -1,21 +1,32 @@
 pip
 ===
 
-pip is a tool for installing and managing Python packages, such as those
-found in the `Python Package Index <http://pypi.python.org/pypi>`_.
-
-pip is a replacement for `easy_install
-<http://peak.telecommunity.com/DevCenter/EasyInstall>`_.  It mostly
-uses the same techniques for finding packages, so packages that are
-easy_installable should be pip-installable as well.  This means that
-you can use ``pip install SomePackage`` instead of ``easy_install
-SomePackage``.
-
-In order to use pip, you must first install `setuptools
-<http://pypi.python.org/pypi/setuptools>`_ or `distribute
-<http://pypi.python.org/pypi/distribute>`_.  If you use `virtualenv
-<http://www.virtualenv.org>`_, a copy of pip will be automatically be
-installed in each virtual environment you create.
+`pip` is a tool for installing and managing Python packages, such as
+those found in the `Python Package Index`_. It's a replacement for
+easy_install_.
+::
+
+    $ pip install simplejson
+    [... progress report ...]
+    Successfully installed simplejson
+
+.. _`Python Package Index`: http://pypi.python.org/pypi
+.. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
+
+Upgrading a package::
+
+    $ pip install --upgrade simplejson
+    [... progress report ...]
+    Successfully installed simplejson
+
+Removing a package::
+
+    $ pip uninstall simplejson
+    Uninstalling simplejson:
+      /home/me/env/lib/python2.7/site-packages/simplejson
+      /home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info
+    Proceed (y/n)? y
+      Successfully uninstalled simplejson
 
 .. comment: split here
 
@@ -29,6 +40,7 @@ installed in each virtual environment you create.
    other-tools
    contributing
    news
+   glossary
 
 .. comment: split here
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
index ff8dac3b0..7324b9109 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,4 +1,4 @@
-.. _`requirements file`:
+.. _`requirements-files`:
 
 ==================
 Requirements files
diff --git a/docs/usage.txt b/docs/usage.txt
index 08f125cfd..a0421fcee 100644
--- a/docs/usage.txt
+++ b/docs/usage.txt
@@ -5,24 +5,22 @@ Usage
 Install packages
 ----------------
 
-Once you have pip, you can use it like this::
+The simplest way to install a package is by specifying its name::
 
     $ pip install SomePackage
 
-`SomePackage` is some package you'll find on `PyPI
-<http://pypi.python.org/pypi/>`_.  This installs the package and all
-its dependencies.
+`SomePackage` is downloaded from :term:`PyPI`, along with its
+dependencies, and installed.
 
-You can also install from a URL (that points to a tar or zip file),
-install from some version control system (use URLs like
-``hg+http://domain/repo`` -- or prefix ``git+``, ``svn+`` etc).  pip
-knows a bunch of stuff about revisions and stuff, so if you need to do
-things like install a very specific revision from a repository pip can
-do that too.
+If `SomePackage` is already installed, and you need a newer version, use
+``pip install --upgrade SomePackage``. You can also request a specific
+version: ``pip install SomePackage==1.0.4``.
 
-You can use ``pip install --upgrade SomePackage`` to upgrade to a
-newer version, or ``pip install SomePackage==1.0.4`` to install a very
-specific version.
+You can also install from a particular source distribution file, either
+local or remote::
+
+    $ pip install ./downloads/SomePackage-1.0.4.tar.gz
+    $ pip install http://my.package.repo/SomePackage-1.0.4.zip
 
 Edit mode
 *********
@@ -40,9 +38,9 @@ package::
 Version control systems
 ***********************
 
-Pip knows how to check out a package from version control. The
-repository will be checked out in a temporary folder, installed, and
-cleaned up::
+Pip knows how to check out a package from version control. `Subversion`,
+`Git`, `Mercurial` and `Bazaar` are supported. The repository will be
+checked out in a temporary folder, installed, and cleaned up::
 
     $ pip install git+https://github.com/simplejson/simplejson.git
     $ pip install svn+svn://svn.zope.org/repos/main/zope.interface/trunk/
@@ -53,6 +51,23 @@ folder by appending a hash to the repository URL::
 
     $ pip install -e git+https://github.com/lakshmivyas/hyde.git#egg=hyde
 
+Alternate package repositories
+******************************
+
+pip searches in :term:`PyPI` by default, but this can be overridden,
+using the ``--index-url`` option::
+
+    $ pip install --index-url http://d.pypi.python.org/simple/ SomePackage
+
+If some package is not in PyPI, but in a private repository, it makes
+sense to specify additional search URLs (see `Your own python egg
+baskets / package repositories`_ for a guide on creating simple
+repositories)::
+
+    $ pip install --extra-index-url http://my.package.repo/ SomePackage
+
+.. _`Your own python egg baskets / package repositories`: http://labs.creativecommons.org/2011/02/14/your-own-python-egg-baskets-package-repositories/
+
 
 Uninstall packages
 ------------------
@@ -74,16 +89,14 @@ fails to download or install.
 Searching for packages
 ----------------------
 
-pip can search the `Python Package Index <http://pypi.python.org/pypi>`_ (PyPI)
-for packages using the ``pip search`` command. To search, run::
+pip can search :term:`PyPI` for packages using the ``pip search``
+command::
 
     $ pip search "query"
 
-The query will be used to search the names and summaries of all packages
-indexed.
-
-pip searches http://pypi.python.org/pypi by default but alternative indexes
-can be searched by using the ``--index`` flag.
+The query will be used to search the names and summaries of all
+packages. With the ``--index`` option you can search in a different
+repository.
 
 Bundles
 -------
@@ -97,8 +110,8 @@ build a bundle file, do::
 
     $ pip bundle MyApp.pybundle MyApp
 
-(Using a `requirements file`_ would be wise.)  Then someone else can get the
-file ``MyApp.pybundle`` and run::
+(Using a :ref:`requirements file <requirements-files>` would be wise.)  Then
+someone else can get the file ``MyApp.pybundle`` and run::
 
     $ pip install MyApp.pybundle