get README up to date with reality

1 files changed, 37 insertions, 19 deletions

diff --git a/README b/README
index f59bf7f..b559883 100644
--- a/README
+++ b/README
@@ -6,14 +6,14 @@ setup instructions
 
 required software:
 
-(for now) source-highlight
 (for now) patchutils
 python
 python-cheetah
-(eventually) python-pygments
+python-pygments
 python-debian
 (optional) reprepro
-something providing an httpd
+something providing an httpd with wsgi support
+(for testing outside of an httpd) python-wsgiref
 
 first, you need a partial source archive, with the .dsc, diff.gz, Release,
 and Sources.gz files available.  there's a sample config in the subdir 
@@ -23,27 +23,45 @@ fetching the rest of the debs/tarballs, which should keep the archive size
 down a bit (though it should also work just fine on a normal archive too).
 
 so, you have your source archive available, and installed somewhere.
-next set up a web server, and configure it to serve up the "application" from
-wherever, using standard Alias or VirtualHost/DocumentRoot stuff.
+next set up a web server, and configure it to serve up the application from
+wherever, using the file sample-apache2.conf as a basis.
 
 next, take a look at the Conf module in the patchtracker directory, which
-contains all the configuration stuff that you will need to
-modify to get the script to run and generate pages as it should.
+contains all the configuration items that you might need to modify to
+get the script to run and generate pages as it should.  Instead of
+modifying this file directly (which is tracked by git), you have the option
+of placing your site config in a file "localconfig.py" in the top level
+directory (the one containing this README).  The Conf module will override
+its built in settings with settings in this location.
 
 --------------------
 overall design/scheme
 --------------------
 
-currently the plan is to generate static information based on the info
-available in a standard source archive (thus hopefully eliminating the need for 
-some kind of complicated tracking infrastructure).  The in-between stage
-may involve a lightweight database (i.e. sqlite) for quick/efficient handling
-of source package metadata, but in the current scheme it is all handled
-on the fs directly or within classes.  the database shouldn't be necessary
-in the "final output", which is currently static.  of course the right is
-reserved for later additions that include dynamic content and/or
-interaction (posting comments to a patch, fetching other data from external 
-sources)
-
-the webpages are generated from cheetah based templates in ./templates.  if the content is later dynamically generated the templates may still be useful.
+the whole system is loosely a read-only REST-flavoured MVC webapp (being
+read-only, the "M" "C" get mixed up a bit in places).
+
+the ultimate backing datastore is a partial source archive containing the
+required source control files and debian diffs.  for efficiency and sanity
+reasons much of the meta-data derived from the source archive is kept in
+an updated sqlite cache, which is what is used by the rest of the system.
+
+both the source archive and the sqlite cache are updated with the
+gen-patch-info.py script.  by deafult you probably want to run:
+
+	gen-patch-info.py -a
+
+though during development phases you might find some of the options
+of this script helpful (UTSL)
+
+the individual patches and files are still currently taken directly
+from the source archives and mangled via utlities in the diffstat
+and patchutils package.
+
+the primary port-of-call for all requests of dynamic data go through
+pagehandler.py, which then delegates the request to a CmdHandler, which
+in turn resolves the request to a specific Cmd subclass, which usually
+corresponds to a specific view.
+
+the webpages are generated from cheetah based templates in ./templates.