[Repoze-checkins] r859 - repoze.obob/trunk/doc

[Chris McDonough]

Author: Chris McDonough <chrism at agendaless.com>
Date: Sun Mar 23 22:09:37 2008
New Revision: 859

Log:
Freshen intro docs.


Modified:
   repoze.obob/trunk/doc/intro.txt

Modified: repoze.obob/trunk/doc/intro.txt
==============================================================================
--- repoze.obob/trunk/doc/intro.txt	(original)
+++ repoze.obob/trunk/doc/intro.txt	Sun Mar 23 22:09:37 2008
@@ -22,17 +22,16 @@
       calling the published object, into appropriate WSGI output.
 
   The publisher is *not* responsible for the following tasks, which
-  belong to WSGI / repoze "middleware" components:
+  belong to WSGI "middleware" components:
 
     - setting up any transaction;
 
-    - opening any database connections;
+    - committing or aborting a transaction;
 
     - retrying failed / conflicting requests;
 
     - converting Python exceptions into HTTP response codes.
 
-
 Configuring obob
 
   The obob instance can be configured either through paste or through
@@ -50,7 +49,9 @@
       for graph traversal.
 
       The default implementation returns an instance of
-      'repoze.obob.publisher.DefaultHelper'.
+      'repoze.obob.publisher.DefaultHelper'.  It is presumed that
+      specific applications will use their own helper implementations
+      (e.g. repoze.zope2's Zope2ObobHelper).
 
     'get_root' -- optional; called at the beginning of processing.
 
@@ -58,22 +59,20 @@
 
         get_root(helper) -> root
 
-      E.g., in the Zope2 stack, return the root ZODB object, wrapped in
-      the request.
+      E.g., in the Zope2 stack, return the ZODB root object.
 
       'helper' is the traversal policy helper object, which will normally
       wrap the environment.
 
-      The default implementation returns a mapping objecct containing 
-      keys defined in the configuration using an 'obob.' prefix.  If called,
-      this object returns a simple HTML list of links to the dispatchable
-      names.
+      The default implementation returns a mapping object containing
+      keys defined in the configuration using an 'obob.' prefix.  If
+      called, this object returns a simple HTML list of links to the
+      dispatchable names.
 
       The returned object will be used as the root of the traversal graph.
       If needed, create / check out database connections, etc., based on
       request, as well as initializing any per-request policy settings.
 
-
 Supplying a different publication helper
 
   The default helper (repoze.obob.publisher.DefaultHelper) provides
@@ -88,22 +87,23 @@
 
         setup()
 
-      E.g. in the Zope2 stack, call 'newInteraction'??
+      E.g. in the Zope2 stack, call 'newInteraction',
+      'setDefaultSkin', create a request, create a stack of names from
+      'PATH_INFO', etc.
 
       The default implementation is a no-op.
 
-    'path_elements' -- computes the list of path elements to be
-      traversed
+    'next_name' -- returns the next name in the stack of path elements
+      to be traversed
       
       Contract::
 
-        path_elements() -> [elements]
+        next_name() -> name
 
-      E.g., in the Zope2`stack, break the 'PATH_INFO' environment value
-      into elements.
-      
-      The default implementaition splits that key on '/', and returns all
-      non-empty elements.
+      E.g., in the Zope2`stack, use the stack of names from the
+      'PATH_INFO' environment value into elements, and form a stack.
+      Each call to next_name() pops a path element from the stack and
+      returns it.
 
     'before_traverse' -- called before traversing each edge.
       
@@ -111,8 +111,7 @@
 
         before_traverse(current, name) # raise to veto
 
-      E.g. in the Zope2 stack, note location of most-recently-seen
-      '__allow_groups__' user folder.
+      E.g. in the Zope2 stack, call '__before_publishing_traverse__'.
 
       The default implementation is a no-op.
 
@@ -132,7 +131,7 @@
      
       Contract::
 
-        before_traverse(published) # raise to veto
+        before_invoke(published) # raise to veto
 
       E.g., in the Zope2 stack, ask the security machinery to authorize
       access to the published object.
@@ -168,7 +167,8 @@
 
         teardown()
 
-      E.g., in the Zope2 stack, call 'endInteraction?
+      E.g., in the Zope2 stack, call 'endInteraction' and close the
+      request.
 
       The default implementation is a no-op.