[Checkins] SVN: z3c.dobbin/trunk/src/z3c/dobbin/README.txt Documentation update.

[Malthe Borch]

Log message for revision 87786:
  Documentation update.

Changed:
  U   z3c.dobbin/trunk/src/z3c/dobbin/README.txt

-=-
Modified: z3c.dobbin/trunk/src/z3c/dobbin/README.txt
===================================================================
--- z3c.dobbin/trunk/src/z3c/dobbin/README.txt	2008-06-26 08:20:55 UTC (rev 87785)
+++ z3c.dobbin/trunk/src/z3c/dobbin/README.txt	2008-06-26 08:42:53 UTC (rev 87786)
@@ -1,28 +1,23 @@
-Developer walk-through
-======================
+Walk-through of the framework
+=============================
 
 This section demonstrates the main functionality of the package using
-the doctest format.
+the doctest format. 
 
-Mapping
--------
+We begin with a new database session.
 
-Dobbin creates SQLAlchemy ORM mappers from Python classes based on
-class specification (class or interface):
-
-  * Columns are infered from interface schema fields and attributes
-  * Specification is kept as dotted name in a special column
-
-Interface specification
------------------------
-
-We begin with a database session.
-
     >>> import ore.alchemist
     >>> session = ore.alchemist.Session()
 
-Define a schema interface:
+Mappers from interface specification
+------------------------------------
 
+We'll start out creating mappers directly from an interface
+specification. The instances will only afford access to the declared
+attributes and have no methods.
+
+We start out with an interface decribing a recorded album.
+
     >>> class IAlbum(interface.Interface):
     ...     artist = schema.TextLine(
     ...         title=u"Artist",
@@ -32,8 +27,9 @@
     ...         title=u"Title",
     ...         default=u"")
 
-We can then fabricate an instance that implements this interface by
-using the ``create`` method.
+We can now fabricate instances that implement this interface by using
+the ``create`` method. This is a shorthand for setting up the mapper
+and creating an instance using its factory.
 
     >>> from z3c.dobbin.factory import create
     >>> album = create(IAlbum)