Added new document

3 files changed, 184 insertions, 9 deletions

diff --git a/docs/rebuild b/docs/rebuild
index 2fd50f8..65e7b9d 100755
--- a/docs/rebuild
+++ b/docs/rebuild
@@ -5,7 +5,8 @@ parent=`dirname $here`
 echo "Adding $parent to \$PYTHONPATH"
 export PYTHONPATH=$parent:$PYTHONPATH
 
-NORMAL="DeveloperGuidelines Paste servers StyleGuide web/index"
+NORMAL="DeveloperGuidelines Paste servers StyleGuide web/index \
+        what-is-paste"
 DOCTEST_BUILD="BlogTutorial TodoTutorial"
 
 for NAME in $NORMAL ; do
diff --git a/docs/web/index.txt b/docs/web/index.txt
index 4665822..bbc6286 100644
--- a/docs/web/index.txt
+++ b/docs/web/index.txt
@@ -69,14 +69,11 @@ Resources
 * `To-do tutorial`_, an introduction to Paste installation and application
   design
 
-* `What is Paste?
-  <http://blog.ianbicking.org/what-is-wsgikit.html>`_: a description
-  of Paste's scope. (Note that Paste was known as "WSGIKit" when this 
-  was written.)
-
-* `What can Paste do for you?
-  <http://blog.ianbicking.org/what-can-wsgikit-do-for-you.html>`_: a
-  description of what Paste offers to Python web framework authors.
+* `What is Paste? <./docs/what-is-paste.html>`_: a description of the
+  project scope (see also the older documents `What is WSGIKit?
+  <http://blog.ianbicking.org/what-is-wsgikit.html>`_ and `What can
+  WSGIKit do for you?
+  <http://blog.ianbicking.org/what-can-wsgikit-do-for-you.html>`_)
 
 * Ian Bicking presented at `PyCon 2005`_ on `WSGI Middleware and
   WSGIKit`_: *Using WSGI Middleware to build a foundation for Python web
diff --git a/docs/what-is-paste.txt b/docs/what-is-paste.txt
new file mode 100644
index 0000000..f4595db
--- /dev/null
+++ b/docs/what-is-paste.txt
@@ -0,0 +1,177 @@
+What Is Paste?
+==============
+
+:author: Ian Bicking
+:revision: $Rev$
+:date: $LastChangedDate$
+
+Introduction
+------------
+
+It has come up several times that people don't understand quite what
+Paste is and what it is intended to be.  This document is an attempt
+to respond to that.  
+
+In part the confusion has been because Paste has is really several
+things.  It is an attempt to fill in some of the gaps in web
+frameworks, and to identify places where things can be shared; as such
+it is a reaction to the current state of frameworks, and a direct
+attempt to be complimentary to those frameworks.  As a result it can
+be somewhat eclectic.
+
+Server/Application Glue
+-----------------------
+
+`WSGI <http://www.python.org/peps/pep-0333.html>`_ defines how servers
+invoke applications, and how application respond.  However, it does
+not define how servers or applications come into existance, or how
+they are passed to each other.
+
+Paste is meant to bridge that, but providing a single entry point that
+can create and configure a server, create an WSGI application, and
+hook the two together.
+
+This generally involves distinct code for each server supported, since
+there isn't any standard.
+
+Also, Paste is expected to create the applications that get served.
+This is typically done through at least somewhat-custom code that
+is driven by the configuration.  Which leads us to...
+
+Configuration
+-------------
+
+In order to set up servers and application, some kind of configuration
+is needed.  Paste loads up configuration files and makes these
+available to all parts of the system.
+
+One goal of Paste is to support small pieces of decoupled code that
+work together.  This is part of its WSGI-driven architecture.
+However, exactly how that code is split up is an implementation detail
+that really shouldn't be exposed to end users.  Because of this, each
+component can't have its own configuration without resulting in a mess
+of configuration files and formats that are fragile and difficult to
+understand.
+
+This configuration is accessible from all portions of the system, so
+your application configuration can go in beside server and middleware
+configuration.
+
+Reusable Middleware
+-------------------
+
+WSGI allows for the idea of "middleware" -- something that is both a
+server and an application.  This is similar to a filter or a wrapper.
+By building these on WSGI, they are neutral with respect to any
+particular framework.
+
+Use of the middleware is generally optional, but they serve as a way
+to share work, and tend to be a fairly good architecture for many
+problems.
+
+Some of the middleware included:
+
+* Adding configuration information to the request
+  (``paste.configmiddleware``)
+
+* Catching and reporting errors (``paste.error_middleware``)
+
+* Catching HTTP-related exceptions and producing HTTP responses
+  (``paste.httpexceptions``)
+
+* Testing for WSGI compliance (``paste.lint``)
+
+* Identifying and authenticating user logins (``paste.login``)
+
+* Facilitating internal redirects and recursive calls
+  (``paste.recursive``)
+
+* Adding sessions to the request (``paste.session``)
+
+* Validating HTML output from applications (``paste.wdg_validate``)
+
+Another kind of middleware is one which finds and constructs
+applications.  At the moment, just one such middleware is in the
+library: ``paste.urlparser``.  This looks on disk for files and Python
+modules, and creates WSGI applications from them.  Other URL resolvers
+are also possible, e.g., one that traverses objects, or uses explicit
+URL->application maps.
+
+Otherwise Homeless Code
+-----------------------
+
+All code has to go somewhere.  Sometimes there's not a good location
+for that code.  So it can go in Paste.
+
+An Implementation Webware
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``paste.webkit`` is a reimplementation of Webware built on the Paste
+middleware.  This is a fairly thin implementation, mostly mapping the
+middleware APIs to Webware APIs.
+
+In this system Webware Servlet instances become WSGI applications
+(``paste.webkit.wkservlet.Servlet.__call__`` implements a WSGI
+application).
+
+Reloader
+~~~~~~~~
+
+This module (``paste.reloader``) checks in the background for modified
+files (typically modules in ``sys.modules``) and restarts the entire
+server when that happens.
+
+This avoids the stale-code issue, where code in memory gets out of
+sync with code on disk.  When that happens confusion can ensue.
+Manually restarting is also somewhat annoying, so this does the
+restarting for you.  It's not really appropriate for a live
+deployment, but it works well in development.
+
+Documentation System
+~~~~~~~~~~~~~~~~~~~~
+
+This is still young and not well defined, but there's some work on
+using `doctest
+<http://python.org/doc/current/lib/module-doctest.html>`_ to generate
+and test documentation.  These can turn into a kind of acceptance
+test.
+
+Application Templates
+---------------------
+
+One facility in Paste is ``paste-setup`` a script to create
+application "templates".  Basically an empty application, with a
+little structure.  For instance, the Webware/Zope Page Template
+(webkit_zpt) application template sets up these files::
+
+    __init__.py
+    server.conf
+    sitepage.py
+    templates/standard_template.pt
+    templates/index.pt
+    web/__init__.py
+    web/index.py
+    web/static/stylesheet.css
+
+This is a kind of a minimal set up for a typical web application using
+these systems.  After the application is set up, ``paste-setup`` can
+provide other commands.  For instance in a webkit_zpt application
+``paste-setup servlet edit`` will create ``web/edit.py`` and
+``web/edit.pt`` files.  Each template has control implement any
+commands how it sees fit, but some convenient functions and classes
+are provided to make implementation easier.
+
+Distribution
+------------
+
+This is still an open issue, but I hope Paste will facilitate
+installation of multiple frameworks quickly.  Some of this is handled
+already: ``paste-server`` starts a server easily and quickly, and
+``paste-setup`` gives a user the basis for an application quickly.
+Actual software installation is a little harder.  Right now the plan
+is to use `Python Eggs
+<http://peak.telecommunity.com/DevCenter/PythonEggs>`_, but it's just
+a plan.  Python Eggs are still in development (though usable), and it
+requires creating packages for each project (which is feasible, but
+requires a fair amount of grunt work).
+