Refactored and culled documentation

1 files changed, 121 insertions, 25 deletions

diff --git a/docs/index.txt b/docs/index.txt
index 039202f..64b640b 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -1,35 +1,131 @@
 Documentation
 =============
 
-Reference
----------
-
-* `Paste Reference Documentation 
-  <http://pythonpaste.org/docs/reference.html>`_
-* `paste.deploy <http://pythonpaste.org/deploy/paste-deploy.html>`_
-* `Configuration <configuration.html>`_
-* `Integrating Frameworks Info Paste <integration.html>`_
-* `Roadmap for Paste <roadmap.html>`_
-* `Testing Applications With Paste <testing-applications.html>`_
-* `URL Parsing with WSGI and Paste <url-parsing-with-wsgi.html>`_
-
 Tutorials and Introduction
---------------------------
+==========================
+
+* `To-Do Tutorial <http://pythonpaste.org/todo/TodoTutorial.html>`_
+
+The core Paste package is a set of tools that use `WSGI
+<http://www.python.org/peps/pep-0333.html>`_ heavily as the means of
+communication.  WSGI is an in-process CGI-like communication protocol.
+
+Right now the best way to see the various tools available in Paste is
+to `look through the source <module-index.html>`_.
 
-* `To-Do Tutorial <TodoTutorial.html>`_
-* `What Is Paste? <what-is-paste.html>`_; older related documents:
+Related Projects
+================
 
-  * `What is WSGIKit <http://blog.ianbicking.org/what-is-wsgikit.html>`_
-  * `What can WSGIKit do for you?
-    <http://blog.ianbicking.org/what-can-wsgikit-do-for-you.html>`_
-  * Ian Bicking presented at `PyCon 2005 <http://pycon.org/dc2005>`_ on 
-    `WSGI Middleware and WSGIKit
-    <http://www.imagescape.com/software/docs/wsgikit-pycon2005/>`_: 
-    *Using WSGI Middleware to build a foundation for Python web
-    programming*
+Closely related packages:
 
-Developers
-----------
+* `Paste Deploy <http://pythonpaste.org/deploy/>`_
+* `Paste Script <http://pythonpaste.org/script/>`_
+* `Paste WebKit <http://pythonpaste.org/webkit/>`_
+* `Wareweb <http://pythonpaste.org/wareweb/>`_
+
+Developer Documentation
+=======================
 
 * `Developer Guidelines <DeveloperGuidelines.html>`_
 * `Style Guide <StyleGuide.html>`_
+
+Reference Documentation
+=======================
+
+* `Testing Applications With Paste <testing-applications.html>`_
+* `URL Parsing with WSGI and Paste <url-parsing-with-wsgi.html>`_
+
+
+License
+=======
+
+Paste is distributed under the `Python Software Foundation`__
+license.  This is a BSD/MIT-style license.
+
+.. __: http://www.python.org/psf/license.html
+
+Overview
+========
+
+If you don't want to look through source, here's a quick overview of
+what there is here:
+
+Testing
+-------
+
+* A fixture for testing WSGI applications conveniently and in-process,
+  in ``paste.fixture``
+
+* A fixture for testing command-line applications, also in
+  ``paste.fixture``
+
+* Check components for WSGI-compliance in ``paste.lint``
+
+Dispatching
+-----------
+
+* Chain and cascade WSGI applications (returning the first non-error
+  response) in ``paste.cascade``
+
+* Dispatch to several WSGI applications based on URL prefixes, in
+  ``paste.urlmap``
+
+* Allow applications to make subrequests and forward requests
+  internally, in ``paste.recursive``
+
+Web Application
+---------------
+
+* Run CGI programs as WSGI applications in ``paste.cgiapp`` (and
+  Python-sepcific CGI programs with ``paste.pycgiwrapper``)
+
+* Traverse files and load WSGI applications from ``.py`` files (or
+  static files), in ``paste.urlparser``
+
+* Serve static directories of files, also in ``paste.urlparser``
+
+Tools
+-----
+
+* Catch HTTP-related exceptions (e.g., ``HTTPNotFound``) and turn them
+  into proper responses in ``paste.httpexceptions``
+
+* Check for signed cookies for authentication, setting ``REMOTE_USER``
+  in ``paste.login``
+
+* Create sessions in ``paste.session`` and ``paste.flup_session``
+
+* Gzip responses in ``paste.gzip``
+
+* A wide variety of routines for manipulating WSGI requests and
+  producing responses, in ``paste.wsgilib``
+
+Debugging Filters
+-----------------
+
+* Catch (optionally email) errors with extended tracebacks (using
+  Zope/ZPT conventions) in ``paste.exceptions``
+
+* Catch errors presenting a `cgitb
+  <http://python.org/doc/current/lib/module-cgitb.html>`_-based
+  output, in ``paste.cgitb_catcher``.
+
+* Profile each request and append profiling information to the HTML,
+  in ``paste.profilemiddleware``
+
+* Capture ``print`` output and present it in the browser for
+  debugging, in ``paste.printdebug``
+
+* Validate all HTML output from applications using the ``WDG Validator
+  <http://www.htmlhelp.com/tools/validator/>`_, appending any errors
+  or warnings to the page, in ``paste.wdg_validator``
+
+Other Tools
+-----------
+
+* A file monitor to allow restarting the server when files have been
+  updated (for automatic restarting when editing code) in
+  ``paste.reloader``
+
+* A class for generating and traversing URLs, and creating associated
+  HTML code, in ``paste.url``