[z3-checkins] r24078 - z3/sqlos/trunk/src/sqlos

[jinty at codespeak.net]

Author: jinty
Date: Tue Mar  7 17:36:22 2006
New Revision: 24078

Modified:
   z3/sqlos/trunk/src/sqlos/README.txt
Log:
Add in a little introduction of what were about and move things round a bit.

Modified: z3/sqlos/trunk/src/sqlos/README.txt
==============================================================================
--- z3/sqlos/trunk/src/sqlos/README.txt	(original)
+++ z3/sqlos/trunk/src/sqlos/README.txt	Tue Mar  7 17:36:22 2006
@@ -6,12 +6,66 @@
 :Date: $Date$
 :Version: $Rev$
 
+
+Introduction
+------------
+
+``sqlos`` is a toolkit for using SQLObject_ (an Object Relational
+Mapper) inside Zope 3 or Zope 2. It tries to take care of many of the
+fiddly details that always seem to take a lot of time. The major ways
+it helps are::
+
+  * Integrates the Zope transaction system and SQLObject, allowing
+    SQLObject to be used in lazyUpdate mode.
+
+  * Uses Zope Database adapters in SQLObject.
+
+  * Provide zcml configuration directives.
+
+  * Provide ZODB persistent objects that can act as a "window" into
+    the database.
+
+  * A testing infrastructure for testing SQLObject based applications.
+
+  * Caches SQLObjects and database connections to improve performance.
+
+.. _SQLObject: http://sqlobject.org
+
+This file describes how to use the ``sqlos`` package to use SQLObject
+together with Zope.
+
+
+Zope 3 or Zope 2??
+------------------
+
+For a quite few reasons, it is better and easier to use sqlos in Zope 3,
+but it can be used with Zope 2. Heavily leveraging the work by the Five
+project, a Zope 2 product (FiveSQLOS) was created to enable this.
+
+.. _FiveSQLOS: http://codespeak.net/svn/z3/sqlos/trunk/Zope2/FiveSQLOS/
+
+
+Dependencies
+------------
+
+    + SQLObject >= 0.7
+
+        Place the sqlobject package somewhere in python's sys.path
+        ($ZOPEHOME/lib/python is a good location).
+
+    + Zope Database Adapter
+
+        Install the adapter appropriate for your database backend.  For
+        example, install the ``psycopgda`` package to connect to PostgreSQL.
+        The ``pyscopgda`` package is located in the zopeproducts_ CVS
+        repository.
+
+.. _zopeproducts: http://cvs.zope.org/zopeproducts/
+
+
 Background
 ----------
 
-This file describes how to use the ``sqlos`` package to use
-SQLObject together with Zope 3.
-
 ``sqlos`` was originally developed for the ``SIP`` project. You can
 find more information about SIP, including some screencasts on the
 `SIP project homepage`_.
@@ -52,23 +106,6 @@
 its flexible enough that you can make their objects come from any
 connection and any registered class you wish.
 
-Dependencies
-------------
-
-    + SQLObject >= 0.7
-
-        Place the sqlobject package somewhere in python's sys.path
-        ($ZOPEHOME/lib/python is a good location).
-
-    + Zope Database Adapter
-
-        Install the adapter appropriate for your database backend.  For
-        example, install the ``psycopgda`` package to connect to PostgreSQL.
-        The ``pyscopgda`` package is located in the zopeproducts_ CVS
-        repository.
-
-.. _zopeproducts: http://cvs.zope.org/zopeproducts/
-
 
 Setting up a connection for SQLObject
 -------------------------------------