still tryin to clarify....

diff --git a/doc/build/content/unitofwork.myt b/doc/build/content/unitofwork.myt
index 97778849ed328fe7663fccdc550859a65e286263..fd7c781e627f840863bab55c02ddeb5249f5a601 100644 (file)
--- a/doc/build/content/unitofwork.myt
+++ b/doc/build/content/unitofwork.myt
@@ -200,7 +200,10 @@
     <p>This second form of commit should be used more carefully as it will not necessarily locate other dependent objects within the session, whose database representation may have foreign constraint relationships with the objects being operated upon.</p>
     
         <&|doclib.myt:item, name="whatis", description="What Commit is, and Isn't" &>
-        <p>The purpose of the Commit operation is to instruct the Unit of Work to analyze its lists of modified objects, assemble them into a dependency graph, fire off the appopriate INSERT, UPDATE, and DELETE statements via the mappers related to those objects, and to synchronize column-based object attributes that correspond directly to updated/inserted database columns.  <b>And thats it.</b>  It does not affect any <code>relation</code>-based object attributes, that is attributes that reference other objects or lists of other objects, in any way.  A brief list of what will <b>not</b> happen includes:</p>
+        <p>The purpose of the Commit operation, as defined by the <code>objectstore</code> package, is to instruct the Unit of Work to analyze its lists of modified objects, assemble them into a dependency graph, fire off the appopriate INSERT, UPDATE, and DELETE statements via the mappers related to those objects, and to synchronize column-based object attributes that correspond directly to updated/inserted database columns.</p>
+        <p>Its important to note that the <b>objectstore.get_session().commit() operation is not the same as the commit() operation on SQLEngine.</b>  A <code>SQLEngine</code>, described in <&formatting.myt:link, path="database"&>, has its own <code>begin</code> and <code>commit</code> statements which deal directly with transactions opened on DBAPI connections.  While the <code>session.commit()</code> makes use of these calls in order to issue its own SQL within a database transaction, it is only dealing with "committing" its own in-memory changes and only has an indirect relationship with database connection objects.
+        </p>
+         <p>The <code>session.commit()</code> operation also does not affect any <code>relation</code>-based object attributes, that is attributes that reference other objects or lists of other objects, in any way.  A brief list of what will <b>not</b> happen includes:</p>
             <ul>
                 <li>It will not append or delete any object instances to/from any list-based object attributes.  Any objects that have been created or marked as deleted will be updated as such in the database, but if a newly deleted object instance is still attached to a parent object's list, the object itself will remain in that list.</li>
                 <li>It will not set or remove any scalar references to other objects, even if the corresponding database identifier columns have been committed.</li>