[Zope3-checkins] SVN: Zope3/trunk/src/zope/app/session/ reSTification and removal of obsolete doc

[Stuart Bishop]

Log message for revision 26425:
reSTification and removal of obsolete doc


-=-
Modified: Zope3/trunk/src/zope/app/session/api.txt
===================================================================
--- Zope3/trunk/src/zope/app/session/api.txt	2004-07-12 10:11:22 UTC (rev 26424)
+++ Zope3/trunk/src/zope/app/session/api.txt	2004-07-12 13:59:48 UTC (rev 26425)
@@ -8,14 +8,14 @@
 by having a unique identifier stored across multiple HTTP requests, be it
 a cookie or some id mangled into the URL.
 
-The IClientIdManager Utility provides this unique id. It is responsible
+The `IClientIdManager` Utility provides this unique id. It is responsible
 for propagating this id so that future requests from the client get
 the same id (eg. by setting an HTTP cookie). This utility is used 
 when we adapt the request to the unique client id:
 
     >>> client_id = IClientId(request)
 
-The ISession adapter gives us a mapping that can be used to store 
+The `ISession` adapter gives us a mapping that can be used to store 
 and retrieve session data. A unique key (the package id) is used
 to avoid namespace clashes:
 
@@ -35,11 +35,11 @@
 Data Storage
 ------------
    
-The actual data is stored in an ISessionDataContainer utility.
-ISession chooses which ISessionDataContainer should be used by
+The actual data is stored in an `ISessionDataContainer` utility.
+`ISession` chooses which `ISessionDataContainer` should be used by
 looking up as a named utility using the package id. This allows
 the site administrator to configure where the session data is actually
-stored by adding a registration for desired ISessionDataContainer
+stored by adding a registration for desired `ISessionDataContainer`
 with the correct name.
 
     >>> sdc = zapi.getUtility(ISessionDataContainer, pkg_id)
@@ -48,27 +48,27 @@
     >>> sdc[client_id][pkg_id]['color']
     'red'
 
-If no ISessionDataContainer utility can be located by name using the
-package id, then the unnamed ISessionDataContainer utility is used as
-a fallback. An unnamed ISessionDataContainer is automatically created
+If no `ISessionDataContainer` utility can be located by name using the
+package id, then the unnamed `ISessionDataContainer` utility is used as
+a fallback. An unnamed `ISessionDataContainer` is automatically created
 for you, which may replaced with a different implementation if desired.
 
     >>> ISession(request)['unknown'] \
     ...     is zapi.getUtility(ISessionDataContainer)[client_id]['unknown']
     True
 
-The ISessionDataContainer contains ISessionData objects, and ISessionData
-objects in turn contain ISessionPkgData objects. You should never need
-to know this unless you are writing administrative views for the session
-machinery.
+The `ISessionDataContainer` contains `ISessionData` objects, and
+`ISessionData` objects in turn contain `ISessionPkgData` objects. You 
+should never need to know this unless you are writing administrative 
+views for the session machinery.
 
     >>> ISessionData.providedBy(sdc[client_id])
     True
     >>> ISessionPkgData.providedBy(sdc[client_id][pkg_id])
     True
 
-The ISessionDataContainer is responsible for expiring session data.
-The expiry time can be configured by settings its 'timeout' attribute.
+The `ISessionDataContainer` is responsible for expiring session data.
+The expiry time can be configured by settings its `timeout` attribute.
 
     >>> sdc.timeout = 1200 # 1200 seconds or 20 minutes
 
@@ -89,6 +89,9 @@
 Page Templates
 --------------
 
+    TODO: Confirm these examples work, preferably by somehow having them
+    unit tested along with the rest of this document
+
     Session data may be accessed in page template documents using the
     TALES adaptor syntax::
 

Deleted: Zope3/trunk/src/zope/app/session/session.txt
===================================================================
--- Zope3/trunk/src/zope/app/session/session.txt	2004-07-12 10:11:22 UTC (rev 26424)
+++ Zope3/trunk/src/zope/app/session/session.txt	2004-07-12 13:59:48 UTC (rev 26425)
@@ -1,57 +0,0 @@
-Session Support
----------------
-
-Sessions allow us to fake state over a stateless protocol - HTTP. We
-do this by having a unique identifier stored across multiple HTTP
-requests, be it a cookie or some id mangled into the URL.
-
-The `IBrowserIdManager` utility provides this unique id. It is
-responsible for propagating this id so that future requests from the
-browser get the same id (such as by setting an HTTP cookie)
-
-`ISessionDataContainer` utilities store session data. The
-`ISessionDataContainer` is responsible for expiring data.
-
-``ISessionDataContainer[product_id]`` returns `ISessionProductData`
-
-``ISessionDataContainer[product_id][browser_id]`` returns
-`ISessionData`
-
-``ISession(request)[product_id]`` returns `ISessionData`
-
-An `ISession` determines what `ISessionDataContainer` to use by
-looking up an `ISessionDataContainer` using the product_id as the
-name, and falling back to the unnamed `ISessionDataContainer` utility.
-This allows site administrators to select which
-`ISessionDataContainer` a particular product stores its session data
-in by registering the utility with the relevant name(s).
-
-Python example::
-
-    >>> browser_id = IBrowserId(request)
-
-    >>> session_data = ISession(request)['zopeproducts.fooprod']
-    >>> session_data['color'] = 'red'
-
-    or for the adventurous....
-
-    >>> explicit_dc = getUtility(ISessionDataContainer, 'zopeproducts.fooprod')
-    >>> session_data = explicit_dc['zopeproducts.fooprod'][str(browser_id)]
-    >>> session_data = Session(explicit_dc, browser_id)['zopeproducts.fooprod']
-    >>> session_data['color'] = 'red'
-
-
-Page Template example::
-
-    XXX: Needs update when TALES adapter syntax decided
-
-    <tal:x condition="exists:session/zopeproducts.fooprod/count">
-       <tal:x condition="python:
-        session['zopeproducts.fooprod']['count'] += 1" />
-    </tal:x>
-    <tal:x condition="not:exists:session/zopeprodicts.fooprod/count">
-        <tal:x condition="python:
-            session['zopeproducts.fooprod']['count'] = 1 />
-    </tal:x>
-    <span content="session/zopeproducts.fooprod/count">6</span>
-