[Zope3-checkins] CVS: Zope3/src/zope/proxy/context - decorators.txt:1.1.2.3

[Steve Alexander]

Update of /cvs-repository/Zope3/src/zope/proxy/context
In directory cvs.zope.org:/tmp/cvs-serv31078

Modified Files:
      Tag: stevea-decorators-branch
	decorators.txt 
Log Message:
Reformatted docs.


=== Zope3/src/zope/proxy/context/decorators.txt 1.1.2.2 => 1.1.2.3 ===
--- Zope3/src/zope/proxy/context/decorators.txt:1.1.2.2	Sun May 18 16:22:19 2003
+++ Zope3/src/zope/proxy/context/decorators.txt	Sun May 18 16:32:46 2003
@@ -49,18 +49,22 @@
 Defining terms
 ==============
 
-Context-dependent code
-Context-dependent functionality    Code that performs the appropriate wrapping
+  Context-dependent code
+  Context-dependent functionality  Code that performs the appropriate wrapping
                                    and unwrapping
 
-inner                              The object that a decorator is wrapping
-outer                              The context wrapper of the decorator
-inner object                       Unambiguous term for "decorated object"
+  inner                            The object that a decorator is wrapping
+
+  outer                            The context wrapper of the decorator
+
+  inner object                     Unambiguous term for "decorated object"
                                    (Not to be confused with 'inner context',
                                     which is a term used when talking about
                                     nested wrappers.)
-mixin object                       The object that is providing decorations
-mixin factory                      The callable that creates a mixin object
+
+  mixin object                     The object that is providing decorations
+
+  mixin factory                    The callable that creates a mixin object
 
 Diagram
 =======
@@ -91,27 +95,26 @@
 different for other kinds of decorators. A future task will be to separate
 out the functionality of a general purpose decorator into a separate type.)
 
-Question: Why use 'inner' and 'outer' rather than 'context' and something
-          else?
+Q: Why use 'inner' and 'outer' rather than 'context' and something else?
 
-Answer:   The term 'context' is ambiguous when we are talking about
-          decorators. For an adapter, 'context' means two things:
+A: The term 'context' is ambiguous when we are talking about
+   decorators. For an adapter, 'context' means two things:
 
-          * The "place" to use for local services etc.
+   * The "place" to use for local services etc.
 
-          * The thing that is being adapted from.
+   * The thing that is being adapted from.
 
-          Additionally, for a wrapper, 'context' often means 'parent'.
+   Additionally, for a wrapper, 'context' often means 'parent'.
 
-          For context decorators, these things are separate. After much
-          thought and experimentation, we settled on "inner" and "outer" as
-          this avoids any ambiguous reference to "context", and looks
-          fairly obvious in the code of decorator mixin classes.
+   For context decorators, these things are separate. After much
+   thought and experimentation, we settled on "inner" and "outer" as
+   this avoids any ambiguous reference to "context", and looks
+   fairly obvious in the code of decorator mixin classes.
 
-          * 'inner' is the object being decorated.
+   * 'inner' is the object being decorated.
 
-          * 'outer' is the decorator wrapper itself. Use this for 'local
-            context'.
+   * 'outer' is the decorator wrapper itself. Use this for 'local
+     context'.
 
 Context decorators
 ==================
@@ -347,10 +350,12 @@
             result.append(ContextWrapper(value, outer, name=key))
         return result
 
+# More methods that are no longer required.
+#
 #    def keys(self):
 #        '''See interface IReadContainer'''
 #        return self.inner.keys()
-
+#
 #    def __len__(self):
 #        '''See interface IReadContainer'''
 #        return len(self.context)
@@ -363,7 +368,7 @@
             result.append((key, ContextWrapper(value, outer, name=key)))
         return result
 
-# code continues...
+# code continues with more methods...
 
 Here is the decorator directive:
 
@@ -397,7 +402,7 @@
       />
   <require
       permission="zope.View"
-      interface="zope.app.interfaces.container.IReadContainer" 
+      interface="zope.app.interfaces.container.IReadContainer"
       />
   <require
       permission="zope.ManageContent"