[z3-checkins] r5576 - z3/sqlos/trunk

[faassen at codespeak.net]

Author: faassen
Date: Wed Jul 14 19:52:42 2004
New Revision: 5576

Modified:
   z3/sqlos/trunk/README.txt
Log:
Tweaks to make it better ReST.


Modified: z3/sqlos/trunk/README.txt
==============================================================================
--- z3/sqlos/trunk/README.txt	(original)
+++ z3/sqlos/trunk/README.txt	Wed Jul 14 19:52:42 2004
@@ -46,7 +46,7 @@
 Setting up a connection for SQLObject
 -------------------------------------
 
-XXX This is not complete yet, but should give you an idea.
+This example is not complete yet (XXX), but should give you an idea::
 
  <configure
     xmlns='http://namespaces.zope.org/zope'
@@ -147,25 +147,25 @@
 There are a few things that you need to know about this piece of
 ZCML:
 
-First, the <browser:editform /> part is what does generate the
+First, the ``<browser:editform />`` part is what does generate the
 automatic editform for the Person class. As you can see, we don't
 reference the class explicitly, but instead, we are saying that for
 the ``IPerson`` schema (a schema is just a flavor of interface), there
 will be an auto-generated editform called ``edit.html`` and it will be
-registered with the menu ``zmi_views``. <browser:editform /> is a
+registered with the menu ``zmi_views``. ``<browser:editform />`` is a
 ``directive``, which is also registered using ZCML and is created as
 part of the ``metaconfiguration`` of Zope 3. I'll not enter this into
 detail now. All you need to know is that this is a ``special view``
 that spits out an edit form in HTML based on the schema you defined.
 
-Second, the <content class="...."> directive is used to register some
-information about the class, like what factory will be using for
+Second, the ``<content class="....">`` directive is used to register
+some information about the class, like what factory will be using for
 creating instances of it and what are the permissions needed to do
 stuff with this class. The <sqlos:factory> directive register the
 class as a IFactory utility and also registers the class as a
 IISQLObject utility.
 
-Let's take a look at the <require> directive:
+Let's take a look at the ``<require>`` directive:
 
 As you can see, there are 3 attributes on the directive. The
 ``permission`` attribute specifies the permission that is
@@ -173,11 +173,11 @@
 that is protected by this permission. All the methods and properties
 defined on this interface are protected for reading by this
 permission. And last, the ``set_schema`` attribute specifies what is
-the interface which is going to be protected for **setting**
-attributes on the instances of this class. This is needed for the
-auto-generated form to work. If you don't specify a permission to
-protect ``set_schema`` on the interface, you won`t be able to modify
-the instance.
+the interface which is going to be protected for *setting* attributes
+on the instances of this class. This is needed for the auto-generated
+form to work. If you don't specify a permission to protect
+``set_schema`` on the interface, you won`t be able to modify the
+instance.
 
 XXX Write about SQLObjectAuthSource.
 
@@ -227,23 +227,26 @@
 
 Our solution consists of:
 
-  - Create a SQLObjectTransactionManager that implements
-    IDataManager. This object will keep track of the dirty objects for
-    a transaction.
-  - Anytime a SQLObject-based object gets its ``dirty``
-    bit set, the object is registered with the current
-    SQLObjectTransactionManager.
-  - If an object gets it's dirty bit set to ``False``, it may mean
-    that this object's ``sync()`` method has been called. We *could*
-    call ``sync()`` on all the dirty objects registered before, but
-    this would increase complexity a lot. For now, we just recommend
-    *not* calling ``sync()`` or ``syncUpdate()`` manually inside
-    transactions.
-  - SQLObjectTransactionManager needs to have a ``sortKey()`` that
-    returns a value smaller than ZopeDBTransactionManager's (which
-    currently doesn't implement this method, so
-    ``id(<ZopeDBTransactionManager>)`` is used). This is so that the
-    ``UPDATE`` queries get sent before the RDB cursor's ``commit()``
-    is called.
-  - Create a SQLOS class that subclasses SQLObject to override
-    ``dirty`` and enable lazy updates by default.
+ - Create a SQLObjectTransactionManager that implements
+   IDataManager. This object will keep track of the dirty objects for
+   a transaction.
+
+ - Anytime a SQLObject-based object gets its ``dirty`` bit set, the
+   object is registered with the current SQLObjectTransactionManager.
+
+ - If an object gets it's dirty bit set to ``False``, it may mean that
+   this object's ``sync()`` method has been called. We *could* call
+   ``sync()`` on all the dirty objects registered before, but this
+   would increase complexity a lot. For now, we just recommend *not*
+   calling ``sync()`` or ``syncUpdate()`` manually inside
+   transactions.
+
+ - SQLObjectTransactionManager needs to have a ``sortKey()`` that
+   returns a value smaller than ZopeDBTransactionManager's (which
+   currently doesn't implement this method, so
+   ``id(<ZopeDBTransactionManager>)`` is used). This is so that the
+   ``UPDATE`` queries get sent before the RDB cursor's ``commit()`` is
+   called.
+
+ - Create a SQLOS class that subclasses SQLObject to override
+   ``dirty`` and enable lazy updates by default.