[Zope3-checkins] SVN: Zope3/trunk/src/zope/ Merge ReSTification and consistency changes from ZopeX3-3.0 branch.

Fred L. Drake, Jr. fred at zope.com
Fri Jul 16 17:14:43 EDT 2004


Log message for revision 26600:
  Merge ReSTification and consistency changes from ZopeX3-3.0 branch.
  
  This includes changes from revisions 26583 - 26589 (inclusive).
  


Changed:
  U   Zope3/trunk/src/zope/app/README.txt
  U   Zope3/trunk/src/zope/app/apidoc/README.txt
  U   Zope3/trunk/src/zope/app/apidoc/TODO.txt
  U   Zope3/trunk/src/zope/app/form/browser/README.txt
  U   Zope3/trunk/src/zope/app/form/browser/complexsample/README.txt
  U   Zope3/trunk/src/zope/app/form/browser/widgets.txt
  U   Zope3/trunk/src/zope/app/ftp/README.txt
  U   Zope3/trunk/src/zope/app/locales/README.txt
  U   Zope3/trunk/src/zope/app/locales/TRANSLATE.txt
  U   Zope3/trunk/src/zope/app/observable/README.txt
  U   Zope3/trunk/src/zope/app/pluggableauth/README.txt
  U   Zope3/trunk/src/zope/app/registration/README.txt
  U   Zope3/trunk/src/zope/app/sqlscript/README.txt
  U   Zope3/trunk/src/zope/app/tree/CHANGES.txt
  U   Zope3/trunk/src/zope/app/tree/README.txt
  U   Zope3/trunk/src/zope/app/tree/TODO.txt
  U   Zope3/trunk/src/zope/event/README.txt
  U   Zope3/trunk/src/zope/i18n/locales/README.txt
  U   Zope3/trunk/src/zope/interface/README.txt
  U   Zope3/trunk/src/zope/interface/adapter.txt
  U   Zope3/trunk/src/zope/interface/tests/foodforthought.txt
  U   Zope3/trunk/src/zope/schema/fields.txt


-=-
Modified: Zope3/trunk/src/zope/app/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/README.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/README.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,7 +1,8 @@
 Zope application server
+-----------------------
 
-This package, the zope.app package, contains the packages and other
-modules that are specific to the Zope application server. These
-packages and modules are not usable outside of Zope. If there's
-something in zope.app you want to use elsewhere, let us know and we
-can talk about abstracting some of it up out of zope.app.
+This package, the `zope.app` package, contains the packages and other
+modules that are specific to the Zope application server.  These
+packages and modules are not usable outside of Zope.  If there's
+something in `zope.app` you want to use elsewhere, let us know and we
+can talk about abstracting some of it up out of `zope.app`.

Modified: Zope3/trunk/src/zope/app/apidoc/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/README.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/apidoc/README.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -9,25 +9,26 @@
 Developing a Module
 -------------------
 
-  1. Implement a class that realizes the 'IDocumentationModule' interface.
+1. Implement a class that realizes the `IDocumentationModule`
+   interface.
 
-  2. Register this class as a utility using something like this::
+2. Register this class as a utility using something like this::
 
-    <utility
-        provides="zope.app.apidoc.interfaces.IDocumentationModule"
-        factory=".examplemodule.ExampleModule"
-        name="Example" />
+     <utility
+         provides="zope.app.apidoc.interfaces.IDocumentationModule"
+         factory=".examplemodule.ExampleModule"
+         name="Example" />
 
-  3. Take care of security by allowing at least 'IDocumentationModule':
+3. Take care of security by allowing at least `IDocumentationModule`::
 
-    <class class=".ExampleModule">
-      <allow interface="zope.app.apidoc.interfaces.IDocumentationModule" />
-    </class>
+     <class class=".ExampleModule">
+       <allow interface="zope.app.apidoc.interfaces.IDocumentationModule" />
+     </class>
 
-  4. Provide a browser view called 'menu.html'.
+4. Provide a browser view called ``menu.html``.
 
-  5. Provide another view, usually 'index.html', that can show the details for
-     the various menu items.
+5. Provide another view, usually ``index.html``, that can show the
+   details for the various menu items.
 
-  Note: There are several modules that come with the product. Just look in
-  them for some guidance.
+Note:  There are several modules that come with the product. Just look
+in them for some guidance.

Modified: Zope3/trunk/src/zope/app/apidoc/TODO.txt
===================================================================
--- Zope3/trunk/src/zope/app/apidoc/TODO.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/apidoc/TODO.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,6 +1,6 @@
 TO DO
 =====
   
-  - better README.txt
+- better README.txt
 
-  - Refactor some of the views, so that templates can be reused
+- Refactor some of the views, so that templates can be reused

Modified: Zope3/trunk/src/zope/app/form/browser/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/form/browser/README.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/form/browser/README.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -3,10 +3,10 @@
 ===============
 
 This directory contains widgets: views on bound schema fields.  Many of these
-are straightforward.  For instance, see the TextWidget in textwidgets.py, which
-is a subclass of BrowserWidget in widget.py.  It is registered as an
-IBrowserRequest view of an ITextLine schema field, providing the IInputWidget
-interface::
+are straightforward.  For instance, see the `TextWidget` in textwidgets.py,
+which is a subclass of BrowserWidget in widget.py.  It is registered as an
+`IBrowserRequest` view of an `ITextLine` schema field, providing the
+`IInputWidget` interface::
 
   <view
       type="zope.publisher.interfaces.browser.IBrowserRequest"
@@ -17,26 +17,26 @@
       />
 
 The widget then receives the field and the request as arguments to the factory
-(i.e., the TextWidget class).
+(i.e., the `TextWidget` class).
 
 Some widgets in Zope 3 extend this pattern.  This extension is configurable:
 simply do not load the zope/app/form/browser/configure.zcml file if you do not
 wish to participate in the extension.  The widget registration is extended for
-Choice fields and for the collection fields.
+`Choice` fields and for the collection fields.
 
 Default Choice Field Widget Registration and Lookup
 ===================================================
 
 As described above, all field widgets are obtained by looking up a browser
-IInputWidget or IDisplayWidget view for the field object.  For Choice fields,
-the default registered widget defers all of its behavior to the result of
-another lookup: a browser widget view for the field *and* the Choice field's
+`IInputWidget` or `IDisplayWidget` view for the field object.  For `Choice`
+fields, the default registered widget defers all of its behavior to the result
+of another lookup: a browser widget view for the field *and* the Choice field's
 vocabulary.  
 
 This allows registration of Choice widgets that differ on the basis of the
 vocabulary type.  For example, a widget for a vocabulary of images might have
 a significantly different user interface than a widget for a vocabulary of
-words.  A dynamic vocabulary might implement IIterableVocabulary if its
+words.  A dynamic vocabulary might implement `IIterableVocabulary` if its
 contents are below a certain length, but not implement the marker "iterable"
 interface if the number of possible values is above the threshhold.
 
@@ -45,12 +45,12 @@
 arguments, choice widgets receive the field, vocabulary, and request as
 arguments.
 
-Some Choice widgets may also need to provide a query interface, particularly if
-the number of items in the vocabulary are too big to iterate.  The vocabulary
+Some `Choice` widgets may also need to provide a query interface,
+particularly if the vocabulary is too big to iterate over.  The vocabulary
 may provide a query which implements an interface appropriate for that
 vocabulary.  You then can register a query view--a view registered for the
 query interface and the field interface--that implements
-zope.app.forms.browser.interfaces.IVocabularyQueryView.
+`zope.app.forms.browser.interfaces.IVocabularyQueryView`.
 
 Default Collection Field Widget Registration and Lookup
 =======================================================
@@ -58,36 +58,36 @@
 The default configured lookup for collection fields--List, Tuple, and Set, for
 instance--begins with the usual lookup for a browser widget view for the
 field object.  This widget defers its display to the result of another lookup:
-a browser widget view registered for the field and the field's value_type (the
-type of the contained values).  This allows registrations for collection
+a browser widget view registered for the field and the field's `value_type`
+(the type of the contained values).  This allows registrations for collection
 widgets that differ on the basis of the members--a widget for entering a list
 of text strings might differ significantly from a widget for entering a list of
 dates...or even a list of choices, as discussed below.
 
 This registration pattern has three implications that should be highlighted. 
 
- * First, collection fields that do not specify a value_type probably cannot
-   have a reasonable widget.  
+* First, collection fields that do not specify a `value_type` probably cannot
+  have a reasonable widget.
 
- * Second, collection widgets that wish to be the default widget for a
-   collection with any value_type should be registered for the collection
-   field and a generic value_type: the IField interface.  Do  not register the
-   generic widget for the collection field only or you will break the lookup
-   behavior as described here.
- 
- * Third, like choice widget factories, sequence widget factories (classes or
-   functions) take three arguments.  Typical sequence widgets receive the
-   field, the value_type, and the request as arguments.
+* Second, collection widgets that wish to be the default widget for a
+  collection with any `value_type` should be registered for the collection
+  field and a generic value_type: the `IField` interface.  Do  not register the
+  generic widget for the collection field only or you will break the lookup
+  behavior as described here.
 
+* Third, like choice widget factories, sequence widget factories (classes or
+  functions) take three arguments.  Typical sequence widgets receive the
+  field, the `value_type`, and the request as arguments.
+
 Collections of Choices
 ----------------------
 
-If a collection field's value_type is a Choice field, the second widget again
-defers its behavior, this time to a third lookup based on the collection field
-and the choice's vocabulary.  This means that a widget for a list of large
-image choices can be different than a widget for a list of small image choices
-(with a different vocabulary interface), different from a widget for a list of
-keyword choices, and different from a set of keyword choices.
+If a collection field's `value_type` is a `Choice` field, the second widget
+again defers its behavior, this time to a third lookup based on the collection
+field and the choice's vocabulary.  This means that a widget for a list of
+large image choices can be different than a widget for a list of small image
+choices (with a different vocabulary interface), different from a widget for a
+list of keyword choices, and different from a set of keyword choices.
 
 Some advanced applications may wish to do a further lookup on the basis of the
 unique attribute of the collection field--perhaps looking up a named view with
@@ -105,7 +105,7 @@
 
 The only hard requirement is that the developer must register the bag + choice
 widget: the widget is just the factory for the third dispatch as described
-above, so the developer can use the already implemented widgets listed below.
+above, so the developer can use the already implemented widgets listed below::
 
   <view
       type="zope.publisher.interfaces.browser.IBrowserRequest"
@@ -127,7 +127,7 @@
 
 Beyond this, the developer may also have a generic bag widget she wishes to
 register.  This might look something like this, assuming there's a
-BagSequenceWidget available in this package::
+`BagSequenceWidget` available in this package::
 
   <view
       type="zope.publisher.interfaces.browser.IBrowserRequest"
@@ -139,8 +139,8 @@
       />
 
 Then any widgets for the bag and a vocabulary would be registered according to
-this general pattern, in which IIterableVocabulary would be the interface of
-any appropriate vocabulary and BagWidget is some appropriate widget::
+this general pattern, in which `IIterableVocabulary` would be the interface of
+any appropriate vocabulary and `BagWidget` is some appropriate widget::
 
   <view
       type="zope.publisher.interfaces.browser.IBrowserRequest"

Modified: Zope3/trunk/src/zope/app/form/browser/complexsample/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/form/browser/complexsample/README.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/form/browser/complexsample/README.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -20,7 +20,7 @@
     kind of query behaviors the sample widget expects.
 
 widgetapi.py
-    Alternate base implementation of the IBrowserWidget interface.
+    Alternate base implementation of the `IBrowserWidget` interface.
     This completely bypasses the implementation from the
-    zope.app.form.browser.widget module, and is really designed for
+    `zope.app.form.browser.widget` module, and is really designed for
     use with widgets of the sort demonstrated in this package.

Modified: Zope3/trunk/src/zope/app/form/browser/widgets.txt
===================================================================
--- Zope3/trunk/src/zope/app/form/browser/widgets.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/form/browser/widgets.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -5,14 +5,14 @@
 zope/app/demo/poll) which has poll options defined as:
 
 label
-  A TextLine holding the label of the option
+  A `TextLine` holding the label of the option
 description
-  Another TextLine holding the description of the option
+  Another `TextLine` holding the description of the option
 
 Simple stuff.
 
-Our Poll product holds an editable list of the PollOption instances. This
-is shown in the ``poll.py`` source below::
+Our Poll product holds an editable list of the `PollOption` instances.
+This is shown in the ``poll.py`` source below::
 
     from persistent import Persistent
     from interfaces import IPoll, IPollOption
@@ -42,7 +42,7 @@
 
         options = property(get_options, set_options, None, 'fiddle options')
 
-And the Schemas are define in the ``interfaces.py`` file below::
+And the Schemas are defined in the ``interfaces.py`` file below::
 
     from zope.interface import Interface
     from zope.schema import Object, Tuple, TextLine
@@ -63,10 +63,11 @@
 
         def choose(option): 'user chooses an option'
 
-Note the use of the Tuple and Object schema fields above. The Tuple
-could optionally have restrictions on the min or max number of items -
-these will be enforce by the SequenceWidget form handling code. The Object
-must specify the schema that is used to generate its data.
+Note the use of the `Tuple` and `Object` schema fields above.  The
+`Tuple` could optionally have restrictions on the min or max number of
+items - these will be enforced by the `SequenceWidget` form handling
+code. The `Object` must specify the schema that is used to generate its
+data.
 
 Now we have to specify the actual add and edit views. We use the existing
 AddView and EditView, but we pre-define the widget for the sequence because
@@ -107,20 +108,20 @@
 
         options_widget = sw
 
-Note the creation of the widget via a CustomWidgetFactory. So,
+Note the creation of the widget via a `CustomWidgetFactory`.  So,
 whenever the options_widget is used, a new
 ``SequenceWidget(subwidget=CustomWidgetFactory(ObjectWidget,
 PollOption))`` is created. The subwidget argument indicates that each
 item in the sequence should be represented by the indicated widget
 instead of their default. If the contents of the sequence were just
-Text Fields, then the default would be just fine - the only odd cases
+`Text` fields, then the default would be just fine - the only odd cases
 are Sequence and Object Widgets because they need additional arguments
 when they're created.
 
 Each item in the sequence will be represented by a
 ``CustomWidgetFactory(ObjectWidget, PollOption)`` - thus a new
 ``ObjectWidget(context, request, PollOption)`` is created for each
-one. The PollOption class ("factory") is used to create new instances
+one. The `PollOption` class ("factory") is used to create new instances
 when new data is created in add forms (or edit forms when we're adding
 new items to a Sequence).
 
@@ -190,10 +191,10 @@
 
     </configure>
 
-Note the use of the "class" argument to the addform and editform
-directives. Otherwise, nothing much exciting here.
+Note the use of the ``class`` attribute on the ``addform`` and
+``editform`` elements.  Otherwise, nothing much exciting here.
 
-Finally, we have some additiona views...
+Finally, we have some additional views...
 
 ``results.zpt``::
 

Modified: Zope3/trunk/src/zope/app/ftp/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/ftp/README.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/ftp/README.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,26 +1,26 @@
+=====================
+How FTP Works in Zope
+=====================
 
-Here are some notes about the way FTP actually works in zope.
+- The FTP server implementation is in `zope.server.ftp.server`.  See
+  the README.txt file there.
 
-  - The FTP server implementation is in zope.server.ftp.server. See
-    the README.txt file there.
+  The publisher-based ftp server is in `zope.server.ftp.publisher`.
 
-    The publisher-based ftp server is in zope.server.ftp.publisher.
+  The FTP server gets wired up with a request factory that creates
+  ftp requests with ftp publication objects.
 
-    The FTP server gets wired up with a request factory that creates
-    ftp requests with ftp publication objects.
+- The ftp request object is defined in `zope.publisher.ftp`.
 
-  - The ftp request object is defined in zope.publisher.ftp.
+- The ftp publication object is defined in `zope.app.publication.ftp`.
 
-  - The ftp publication object is defined in zope.app.publication.ftp.
+  The publication object gets views to handle ftp requests.  It
+  looks up a separate view for each method defined in
+  `zope.publisher.interfaces.ftp.IFTPPublisher`.
 
-    The publication object gets views to handle ftp requests.  It
-    looks up a separate view for each method defined in
-    zope.publisher.interfaces.ftp.IFTPPublisher.
+  We provide a single class here that implements all of these methods. 
 
-    We provide a single class here that implements all of these
-    methods. 
+  The view, in turn, uses adapters for the `IReadFile`, `IWriteFile`,
+  `IReadDirectory`, `IWriteDirectory`, `IFileFactory`, and
+  `IDirectoryFactory`, defined in `zope.app.filerepresentation.interfaces`.
 
-    The view, in turn, uses adapters for the IReadFile, IWriteFile,
-    IReadDirectory, IWriteDirectory, IFileFactory, and
-    IDirectoryFactory, defined in zope.app.filerepresentation.interfaces.
-

Modified: Zope3/trunk/src/zope/app/locales/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/locales/README.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/locales/README.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,6 +1,6 @@
 Software translation files
 ==========================
 
-This directory containes translation files and utilities for
-translating the software strings for the zope application server
+This directory contains translation files and utilities for
+translating the software strings for the Zope application server
 software.

Modified: Zope3/trunk/src/zope/app/locales/TRANSLATE.txt
===================================================================
--- Zope3/trunk/src/zope/app/locales/TRANSLATE.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/locales/TRANSLATE.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,31 +1,33 @@
+===================================================
 Internationalization (I18n) and Localization (L10n)
-=====================================================
+===================================================
 
-  Creating/Updating Message Catalog Template (POT) Files
-  -----------------------------------------------------
 
-    1. Execute i18nextract.py from ZOPE/utilities directory::
+Creating/Updating Message Catalog Template (POT) Files
+------------------------------------------------------
 
-        python2.3 i18nextract.py
+1. Execute i18nextract.py from Zope's utilities/ directory::
 
+     python2.3 i18nextract.py
 
-  Updating Message Catalog (PO) Files
-  -----------------------------------
 
-    1. For each language do simply::
+Updating Message Catalog (PO) Files
+------------------------------------
 
-        msgmerge -U de/LC_MESSAGES/zope.po zope.pot
+1. For each language do simply::
 
-    2. Translate the updated PO file. 
-       Note: KBabel is a great tool for this task!
+     msgmerge -U de/LC_MESSAGES/zope.po zope.pot
 
+2. Translate the updated PO file. 
+   Note: KBabel is a great tool for this task!
 
-  Compiling Message Catalogs (PO) to binary (MO) Files
-  ----------------------------------------------------
 
-    1. Go to the right directory, such as 
-       'zope/app/locales/de/LC_MESSAGES'.
+Compiling Message Catalogs (PO) to binary (MO) Files
+----------------------------------------------------
 
-    2. Run the following command::
+1. Go to the right directory, such as
+   zope/app/locales/de/LC_MESSAGES.
 
-        msgfmt -o zope.mo zope.po
+2. Run the following command::
+
+     msgfmt -o zope.mo zope.po

Modified: Zope3/trunk/src/zope/app/observable/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/observable/README.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/observable/README.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -8,20 +8,13 @@
 
 The package provides an event channel for dispatching events to the
 appropriate instance as well as an adapter from IAnnotatable to
-IObservable.  This is important because an object must support
-IAnnotatable (and therefore IAnnotations) in order to support
+`IObservable`.  This is important because an object must support
+`IAnnotatable` (and therefore `IAnnotations`) in order to support
 instance-based subscriptions.
 
 Subscriptions for a particular instance are stored in the instance's
-annotations, in a key defined in zope.app.observable.observable.key
+annotations, in a key defined in `zope.app.observable.observable.key`
 (currently 'zope.app.observable').  The annotation stored in the key
 is actually an Observers object, which is a local registry that is not
 aware of the global registry in any way.  More information on the
 Observers object is available in observers.txt.
-
-
-
-
-
-
-$Id$

Modified: Zope3/trunk/src/zope/app/pluggableauth/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/pluggableauth/README.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/pluggableauth/README.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,8 +1,10 @@
-$Id$
+=================================
+New Authentication Service Design
+=================================
 
-The current implementation will be replaced. Following is design
+The current implementation will be replaced. The following is a design
 I came up with together with Jim Fulton.
-   -- itamar
+-- itamar
 
 Note that this design is implemented (in some form) by the pluggable
 auth service. This document needs to be updated to reflect the final
@@ -10,49 +12,56 @@
 
 
 Design notes for new AuthenticationService
-==========================================
+------------------------------------------
 
 The service contains a list of user sources. They implement interfaces,
-starting with:
+starting with::
 
 
  class IUserPassUserSource:
      """Authenticate using username and password."""
+
      def authenticate(username, password):
          "Returns boolean saying if such username/password pair exists"
 
 
  class IDigestSupportingUserSource(IUserPassUserSource):
      """Allow fetching password, which is required by digest auth methods"""
+
      def getPassword(username):
          "Return password for username"
 
 
-etc.. Probably there will be others as well, for dealing with certificate
-authentication and what not. Probably we need to expand above interfaces
+etc.  Probably there will be others as well, for dealing with certificate
+authentication and what not.  Probably we need to expand above interfaces
 to deal with principal titles and descriptions, and so on.
 
-A login method - cookie auth, HTTP basic auth, digest auth, FTP auth,
+A login method (cookie auth, HTTP basic auth, digest auth, FTP auth),
 is registered as a view on one of the above interfaces. 
 
+::
 
   class ILoginMethodView:
+
         def authenticate():
              """Return principal for request, or None."""
+
         def unauthorized():
              """Tell request that a login is required."""
 
 
-The authentication service is then implemented something like this:
+The authentication service is then implemented something like this::
 
 
- class AuthenticationService:
-     def authenticate(self, request):
-         for us in self.userSources:
-              loginView = getView(self, us, "login", request)
-              principal = loginView.authenticate()
-              if principal is not None:
-                  return principal
-     def unauthorized(self, request):
-         loginView = getView(self, self.userSources[0], request)
-         loginView.unauthorized()
+  class AuthenticationService:
+
+      def authenticate(self, request):
+          for us in self.userSources:
+               loginView = getView(self, us, "login", request)
+               principal = loginView.authenticate()
+               if principal is not None:
+                   return principal
+
+      def unauthorized(self, request):
+          loginView = getView(self, self.userSources[0], request)
+          loginView.unauthorized()

Modified: Zope3/trunk/src/zope/app/registration/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/registration/README.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/registration/README.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -76,25 +76,21 @@
 
 There are several major concepts/terms that need to be understood
 
-- Registerables
-
+Registerables
   Registerables are objects that can be registered.  They implement the
   `IRegisterable` interface.
 
-- Registries
-
+Registries
   Registeries are objects that registerables are registered with.
   Typically, these are component-management services like the adapter
   or utility service.
 
-- Registration objects
-
+Registration objects
   Registration objects store data about registrations.  They store
   registration data and represent the relationship between registries
   and registerables.
 
-- Registration managers
-
+Registration managers
   Registration managers are containers for managing registrations.
   Registrations are stored in registration managers.  All of the
   registrations for objects stored in a site-management folder are
@@ -103,8 +99,7 @@
   this so that the registration manager is exposed as a folder tab
   rather than as an item.
 
-- Registration stack
-
+Registration stack
   Registries allow multiple registrations for the same set of
   registration parameters. At most one registration for a set of
   parameters can be active at one time, but multiple registrations are
@@ -125,8 +120,7 @@
   registration object passed need not be in in the stack. It is used
   soley to provide the parameters.  
 
-- Registered
-
+Registered
   The interface `IRegistered` provides storage and access to the
   registrations for a registerable.  When we make a registration, we
   refer to it in a registration stack and in the registered object.

Modified: Zope3/trunk/src/zope/app/sqlscript/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/sqlscript/README.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/sqlscript/README.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,131 +1,137 @@
+=======================================
 Using additional DTML tags in SQLScript
+=======================================
 
-  Inserting optional tests with 'sqlgroup'
+Inserting optional tests with 'sqlgroup'
+----------------------------------------
 
-    It is sometimes useful to make inputs to an SQL statement
-    optinal.  Doing so can be difficult, because not only must the
-    test be inserted conditionally, but SQL boolean operators may or
-    may not need to be inserted depending on whether other, possibly
-    optional, comparisons have been done.  The 'sqlgroup' tag
-    automates the conditional insertion of boolean operators.
+It is sometimes useful to make inputs to an SQL statement optinal.
+Doing so can be difficult, because not only must the test be inserted
+conditionally, but SQL boolean operators may or may not need to be
+inserted depending on whether other, possibly optional, comparisons
+have been done.  The 'sqlgroup' tag automates the conditional
+insertion of boolean operators.
 
-    The 'sqlgroup' tag is a block tag that has no attributes. It can
-    have any number of 'and' and 'or' continuation tags.
+The 'sqlgroup' tag is a block tag that has no attributes. It can have
+any number of 'and' and 'or' continuation tags.
 
-    Suppose we want to find all people with a given first or nick name
-    and optionally constrain the search by city and minimum and
-    maximum age.  Suppose we want all inputs to be optional.  We can
-    use DTML source like the following::
+Suppose we want to find all people with a given first or nick name and
+optionally constrain the search by city and minimum and maximum age.
+Suppose we want all inputs to be optional.  We can use DTML source
+like the following::
 
-      <dtml-sqlgroup>
-        <dtml-sqlgroup>
-          <dtml-sqltest name column=nick_name type=nb multiple optional>
-        <dtml-or>
-          <dtml-sqltest name column=first_name type=nb multiple optional>
-        </dtml-sqlgroup>
-      <dtml-and>
-        <dtml-sqltest home_town type=nb optional>
-      <dtml-and>
-        <dtml-if minimum_age>
-           age >= <dtml-sqlvar minimum_age type=int>
-        </dtml-if>
-      <dtml-and>
-        <dtml-if maximum_age>
-           age <= <dtml-sqlvar maximum_age type=int>
-        </dtml-if>
-      </dtml-sqlgroup>
+  <dtml-sqlgroup>
+    <dtml-sqlgroup>
+      <dtml-sqltest name column=nick_name type=nb multiple optional>
+    <dtml-or>
+      <dtml-sqltest name column=first_name type=nb multiple optional>
+    </dtml-sqlgroup>
+  <dtml-and>
+    <dtml-sqltest home_town type=nb optional>
+  <dtml-and>
+    <dtml-if minimum_age>
+       age >= <dtml-sqlvar minimum_age type=int>
+    </dtml-if>
+  <dtml-and>
+    <dtml-if maximum_age>
+       age <= <dtml-sqlvar maximum_age type=int>
+    </dtml-if>
+  </dtml-sqlgroup>
 
-    This example illustrates how groups can be nested to control
-    boolean evaluation order.  It also illustrates that the grouping
-    facility can also be used with other DTML tags like 'if' tags.
+This example illustrates how groups can be nested to control boolean
+evaluation order.  It also illustrates that the grouping facility can
+also be used with other DTML tags like 'if' tags.
 
-    The 'sqlgroup' tag checks to see if text to be inserted contains
-    other than whitespace characters.  If it does, then it is inserted
-    with the appropriate boolean operator, as indicated by use of an
-    'and' or 'or' tag, otherwise, no text is inserted.
+The 'sqlgroup' tag checks to see if text to be inserted contains other
+than whitespace characters.  If it does, then it is inserted with the
+appropriate boolean operator, as indicated by use of an 'and' or 'or'
+tag, otherwise, no text is inserted.
 
-  Inserting optional tests with 'sqlgroup'
+Inserting optional tests with 'sqlgroup'
+----------------------------------------
 
-    It is sometimes useful to make inputs to an SQL statement
-    optinal.  Doing so can be difficult, because not only must the
-    test be inserted conditionally, but SQL boolean operators may or
-    may not need to be inserted depending on whether other, possibly
-    optional, comparisons have been done.  The 'sqlgroup' tag
-    automates the conditional insertion of boolean operators.
+It is sometimes useful to make inputs to an SQL statement optinal.
+Doing so can be difficult, because not only must the test be inserted
+conditionally, but SQL boolean operators may or may not need to be
+inserted depending on whether other, possibly optional, comparisons
+have been done.  The 'sqlgroup' tag automates the conditional
+insertion of boolean operators.
 
-    The 'sqlgroup' tag is a block tag. It can
-    have any number of 'and' and 'or' continuation tags.
+The 'sqlgroup' tag is a block tag. It can have any number of 'and' and
+'or' continuation tags.
 
-    The 'sqlgroup' tag has an optional attribure, 'required' to
-    specify groups that must include at least one test.  This is
-    useful when you want to make sure that a query is qualified, but
-    want to be very flexible about how it is qualified.
+The 'sqlgroup' tag has an optional attribure, 'required' to specify
+groups that must include at least one test.  This is useful when you
+want to make sure that a query is qualified, but want to be very
+flexible about how it is qualified.
 
-    Suppose we want to find people with a given first or nick name,
-    city or minimum and maximum age.  Suppose we want all inputs to be
-    optional, but want to require *some* input.  We can
-    use DTML source like the following::
+Suppose we want to find people with a given first or nick name, city
+or minimum and maximum age.  Suppose we want all inputs to be
+optional, but want to require *some* input.  We can use DTML source
+like the following::
 
-      <dtml-sqlgroup required>
-        <dtml-sqlgroup>
-          <dtml-sqltest name column=nick_name type=nb multiple optional>
-        <dtml-or>
-          <dtml-sqltest name column=first_name type=nb multiple optional>
-        </dtml-sqlgroup>
-      <dtml-and>
-        <dtml-sqltest home_town type=nb optional>
-      <dtml-and>
-        <dtml-if minimum_age>
-           age >= <dtml-sqlvar minimum_age type=int>
-        </dtml-if>
-      <dtml-and>
-        <dtml-if maximum_age>
-           age <= <dtml-sqlvar maximum_age type=int>
-        </dtml-if>
-      </dtml-sqlgroup>
+  <dtml-sqlgroup required>
+    <dtml-sqlgroup>
+      <dtml-sqltest name column=nick_name type=nb multiple optional>
+    <dtml-or>
+      <dtml-sqltest name column=first_name type=nb multiple optional>
+    </dtml-sqlgroup>
+  <dtml-and>
+    <dtml-sqltest home_town type=nb optional>
+  <dtml-and>
+    <dtml-if minimum_age>
+       age >= <dtml-sqlvar minimum_age type=int>
+    </dtml-if>
+  <dtml-and>
+    <dtml-if maximum_age>
+       age <= <dtml-sqlvar maximum_age type=int>
+    </dtml-if>
+  </dtml-sqlgroup>
 
-    This example illustrates how groups can be nested to control
-    boolean evaluation order.  It also illustrates that the grouping
-    facility can also be used with other DTML tags like 'if' tags.
+This example illustrates how groups can be nested to control boolean
+evaluation order.  It also illustrates that the grouping facility can
+also be used with other DTML tags like 'if' tags.
 
-    The 'sqlgroup' tag checks to see if text to be inserted contains
-    other than whitespace characters.  If it does, then it is inserted
-    with the appropriate boolean operator, as indicated by use of an
-    'and' or 'or' tag, otherwise, no text is inserted.
+The 'sqlgroup' tag checks to see if text to be inserted contains other
+than whitespace characters.  If it does, then it is inserted with the
+appropriate boolean operator, as indicated by use of an 'and' or 'or'
+tag, otherwise, no text is inserted.
 
-  Inserting values with the 'sqlvar' tag
+Inserting values with the 'sqlvar' tag
+--------------------------------------
 
-    The 'sqlvar' tag is used to type-safely insert values into SQL
-    text.  The 'sqlvar' tag is similar to the 'var' tag, except that
-    it replaces text formatting parameters with SQL type information.
+The 'sqlvar' tag is used to type-safely insert values into SQL text.
+The 'sqlvar' tag is similar to the 'var' tag, except that it replaces
+text formatting parameters with SQL type information.
 
-    The sqlvar tag has the following attributes:
+The sqlvar tag has the following attributes:
 
-      name -- The name of the variable to insert. As with other
-              DTML tags, the 'name=' prefix may be, and usually is,
-              ommitted.
+`name`
+  The name of the variable to insert. As with other DTML tags, the
+  'name=' prefix may be, and usually is, ommitted.
 
-      type -- The data type of the value to be inserted.  This
-              attribute is required and may be one of 'string',
-              'int', 'float', or 'nb'.  The 'nb' data type indicates a
-              string that must have a length that is greater than 0.
+`type`
+  The data type of the value to be inserted.  This attribute is
+  required and may be one of 'string', 'int', 'float', or 'nb'.  The
+  'nb' data type indicates a string that must have a length that is
+  greater than 0.
 
-      optional -- A flag indicating that a value is optional.  If a
-                  value is optional and is not provided (or is blank
-                  when a non-blank value is expected), then the string
-                  'null' is inserted.
+`optional`
+  A flag indicating that a value is optional.  If a value is optional
+  and is not provided (or is blank when a non-blank value is
+  expected), then the string 'null' is inserted.
 
-    For example, given the tag::
+For example, given the tag::
 
-      <dtml-sqlvar x type=nb optional>
+  <dtml-sqlvar x type=nb optional>
 
-    if the value of 'x' is::
+if the value of 'x' is::
 
-      Let\'s do it
+  Let\'s do it
 
-    then the text inserted is:
+then the text inserted is:
 
-      'Let''s do it'
+  'Let''s do it'
 
-    however, if x is ommitted or an empty string, then the value
-    inserted is 'null'.
+however, if x is ommitted or an empty string, then the value inserted
+is 'null'.

Modified: Zope3/trunk/src/zope/app/tree/CHANGES.txt
===================================================================
--- Zope3/trunk/src/zope/app/tree/CHANGES.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/tree/CHANGES.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,3 +1,4 @@
+=======
 CHANGES
 =======
 
@@ -2,46 +3,50 @@
 v1.2 (2004-02-19) -- 'Scruffy'
+------------------------------
 
-  - Moved to zope.app.tree
+- Moved to `zope.app.tree`
 
-  - It is now called 'ZopeTree' again. Hoorray!
+- It is now called 'ZopeTree' again.  Hoorray!
 
-  - Refactored browser stuff into its own browser subpackage.
+- Refactored browser stuff into its own browser subpackage.
 
-  - Separated the handling of tree state from the cookie functionality
-    to provide a base class for views based on other tree state sources.
+- Separated the handling of tree state from the cookie functionality
+  to provide a base class for views based on other tree state sources.
 
 v1.1 (2004-02-16) -- 'Zapp'
+---------------------------
 
-  - Added support for displaying lines in a tree (Stephan Richter)
+- Added support for displaying lines in a tree (Stephan Richter)
 
-    + Changes in Node.getFlatDict() to provide more data. Removed
-     'depth' from node info, but added 'row-state' and
-     'last-level-node'. Changed interface and test accordingly.
+  - Changes in `Node.getFlatDict()` to provide more data.  Removed
+    'depth' from node info, but added 'row-state' and
+    'last-level-node'.  Changed interface and test accordingly.
 
-    + Updated templates for StaticTree skin and example. Note that
-      third party templates from 1.0.x will not work anymore and must be
-      updated as well!
+  - Updated templates for `StaticTree` skin and example.  Note that
+    third party templates from 1.0.x will not work anymore and must be
+    updated as well!
 
 v1.0.1 (2004-01-16) -- 'Nibbler'
+--------------------------------
 
-  - Added last remaining pieces for unit tests
+- Added last remaining pieces for unit tests
 
-  - Updated documentation
+- Updated documentation
 
-  - Rounded some rough edges in the skin
+- Rounded some rough edges in the skin
 
-  - Integrated it into the Zope3 distribution below the zope.products
-    package
+- Integrated it into the Zope3 distribution below the `zope.products`
+  package
 
 v1.0 (2003-11-24) -- 'Lur'
+--------------------------
 
-  - Ported to Zope 3
+- Ported to Zope 3
 
-  - Renamed it to 'statictree'
+- Renamed it to 'statictree'
 
-  - Much more unit tests
+- Much more unit tests
 
-  - Added filter functionality
+- Added filter functionality
 
-  - Provided sample implementations as well as an alternate
-    rotterdam-like skin using the static tree
+- Provided sample implementations as well as an alternate
+  rotterdam-like skin using the static tree

Modified: Zope3/trunk/src/zope/app/tree/README.txt
===================================================================
--- Zope3/trunk/src/zope/app/tree/README.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/tree/README.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -8,9 +8,9 @@
 ZopeTree is a port of Philipp's Zope2 product ZopeTree. ZopeTree was
 meant to be a light-weight and easy-to-use static tree implementation,
 mainly designed for use in ZPTs. It was originally written because
-Zope2's ZTUtils.Tree was found to be too complicated and inflexible.
+Zope2's `ZTUtils.Tree` was found to be too complicated and inflexible.
 
-The ZTUtils package has not been ported to Zope3. Parts of it, like
+The `ZTUtils` package has not been ported to Zope3. Parts of it, like
 batching, have found their way into Zope3, though. Only support for
 static tree generation is not in the core.
 
@@ -19,7 +19,7 @@
 -------------
 
 Using the skin
---------------
+~~~~~~~~~~~~~~
 
 ZopeTree comes with a pre-defined skin, StaticTree. It looks just
 like Zope3's default skin, Rotterdam, except that it displays a static
@@ -27,18 +27,21 @@
 tree.
 
 Using predefined views on objects
----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ZopeTree comes with several predefined views:
 
-- cookie_tree: simple view using cookies for tree state storage.
+`cookie_tree`
+  simple view using cookies for tree state storage.
 
-- folder_cookie_tree: same as above, however only showing folders.
+`folder_cookie_tree`
+  same as above, however only showing folders.
 
-- site_cookie_tree: same as above, with the nearest site as root node.
+`site_cookie_tree`
+  same as above, with the nearest site as root node.
 
-- root_cookie_tree: same as above, with the root container as root
-  node.
+`root_cookie_tree`
+  same as above, with the root container as root node.
 
 The example page template(s) in the browser package give an idea how
 to use these views for HTML templating.
@@ -47,7 +50,7 @@
 -------------
 
 The best way to customize ZopeTree is to define your own view for
-objects (usually *). If you want to use the cookie functionality,
+objects (usually '*'). If you want to use the cookie functionality,
 simply extend the cookie browser view::
 
   from zope.app.tree.filters import OnlyInterfacesFilter
@@ -78,14 +81,16 @@
 License and Copyright
 ---------------------
 
-This product is released under the terms of the Zope Public License
-(ZPL) v2.0. See the 'ZopePublicLicense.txt' file at the root of your
+This product is released under the terms of the `Zope Public License
+(ZPL) v2.1`__. See the `ZopePublicLicense.txt` file at the root of your
 Zope distribution.
 
 Copyright (c) 2003 Philipp "philiKON" von Weitershausen
 Copyright (c) 2004 Zope Corporation and Contributors
 
+.. __: http://www.zope.org/Resources/ZPL/ZPL-2.1
 
+
 Credits
 -------
 

Modified: Zope3/trunk/src/zope/app/tree/TODO.txt
===================================================================
--- Zope3/trunk/src/zope/app/tree/TODO.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/app/tree/TODO.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,5 +1,6 @@
-
+====
 TODO
+====
 
 for v1.3
 

Modified: Zope3/trunk/src/zope/event/README.txt
===================================================================
--- Zope3/trunk/src/zope/event/README.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/event/README.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -14,14 +14,16 @@
 The package has a list of subscribers.  Application code can manage
 subscriptions by manipulating this list.  For the examples here, we'll
 save the current contents away and empty the list. We'll restore the
-contents when we're done with out examples.
+contents when we're done with our examples.
 
+::
+
   >>> import zope.event
   >>> old_subscribers = zope.event.subscribers[:]
   >>> del zope.event.subscribers[:]
 
 The package provides a `notify` function, which is used to
-notify subscribers that something has happened:
+notify subscribers that something has happened::
 
   >>> class MyEvent:
   ...     pass
@@ -30,18 +32,18 @@
   >>> zope.event.notify(event)
 
 The notify function is called with a single object, which we call an
-event.  Any object will do:
+event.  Any object will do::
 
   >>> zope.event.notify(None)
   >>> zope.event.notify(42)
 
 An extremely trivial subscription mechanism is provided. Subscribers
-are simply callback functions:
+are simply callback functions::
 
   >>> def f(event):
   ...     print 'got:', event
 
-that are put into the subscriptions list:
+that are put into the subscriptions list::
 
   >>> zope.event.subscribers.append(f)
 
@@ -57,7 +59,7 @@
   got: 42
   also got: 42
 
-To unsubscribe, simply remove a subscriber from the list:
+To unsubscribe, simply remove a subscriber from the list::
 
   >>> zope.event.subscribers.remove(f)
   >>> zope.event.notify(42)
@@ -68,6 +70,6 @@
 frameworks will install subscribers that then dispatch to other
 subscribers based on event types or data.
 
-We're done, so we'll restore the subscribers:
+We're done, so we'll restore the subscribers::
 
   >>> zope.event.subscribers[:] = old_subscribers

Modified: Zope3/trunk/src/zope/i18n/locales/README.txt
===================================================================
--- Zope3/trunk/src/zope/i18n/locales/README.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/i18n/locales/README.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -1,33 +1,35 @@
+=================
 Locales XML Files
+=================
 
-  The XML locale files were produced as part of the ICU I18n and L10n
-  framework. They are provided here under the original ICU License - ICU 1.8.1
-  and later license. 
+The XML locale files were produced as part of the ICU I18n and L10n
+framework. They are provided here under the original ICU License - ICU 1.8.1
+and later license. 
 
 
-  ICU Web site
+ICU Web site
+------------
 
-    http://oss.software.ibm.com/icu/
+  http://oss.software.ibm.com/icu/
 
 
-  Locale Data Markup Language
+Locale Data Markup Language
+---------------------------
 
-    The XML files follow the now public and completed LDML format. 
+The XML files follow the now public and completed LDML format. 
 
-    The DTD can be found at
+The DTD can be found at
 
-      http://www.openi18n.org/spec/ldml/1.0/ldml-spec.htm
+  http://www.openi18n.org/spec/ldml/1.0/ldml-spec.htm
 
-    The specification is at
+The specification is at
 
-      http://www.openi18n.org/spec/ldml/1.0/ldml.dtd
+  http://www.openi18n.org/spec/ldml/1.0/ldml.dtd
 
-  
-  Download
 
-    ::
+Download::
 
-      $ cvs -d :pserver:anoncvs at oss.software.ibm.com:/usr/cvs/icu login
-      Password: anoncvs
-      $ cvs -d :pserver:anoncvs at oss.software.ibm.com:/usr/cvs/icu co \
-        -d new_locales locale/common/main -d data
+  $ cvs -d :pserver:anoncvs at oss.software.ibm.com:/usr/cvs/icu login
+  Password: anoncvs
+  $ cvs -d :pserver:anoncvs at oss.software.ibm.com:/usr/cvs/icu co \
+    -d new_locales locale/common/main -d data

Modified: Zope3/trunk/src/zope/interface/README.txt
===================================================================
--- Zope3/trunk/src/zope/interface/README.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/interface/README.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -37,23 +37,23 @@
 In the example above, we've created an interface, `IFoo`.  We
 subclassed `zope.interface.Interface`, which is an ancestor interface for
 all interfaces, much as `object` is an ancestor of all new-style
-classes [#create]_.   The interface is not a class, It's an Interface,
-an instance of `InterfaceClass`:
+classes [#create]_.   The interface is not a class, it's an Interface,
+an instance of `InterfaceClass`::
 
   >>> type(IFoo)
   <class 'zope.interface.interface.InterfaceClass'>
   
-We can ask for the interfaces documentation:
+We can ask for the interfaces documentation::
 
   >>> IFoo.__doc__
   'Foo blah blah'
 
-and it's name:
+and it's name::
 
   >>> IFoo.__name__
   'IFoo'
 
-and even it's module:
+and even it's module::
 
   >>> IFoo.__module__
   '__main__'
@@ -80,7 +80,7 @@
   methods that are not instance methods.
 
 You can access the attributes defined by an interface using mapping
-syntax:
+syntax::
 
   >>> x = IFoo['x']
   >>> type(x)
@@ -90,12 +90,12 @@
   >>> x.__doc__
   'X blah blah'
 
-You can use `in` to determine if an interface defines a name:
+You can use `in` to determine if an interface defines a name::
 
   >>> 'x' in IFoo
   True
 
-You can iterate over interfaces to get the names they define:
+You can iterate over interfaces to get the names they define::
 
   >>> names = list(IFoo)
   >>> names.sort()
@@ -103,14 +103,14 @@
   ['bar', 'x']
 
 Remember that interfaces aren't classes. You can't access attribute
-definitions as attributes of interfaces:
+definitions as attributes of interfaces::
 
   >>> IFoo.x
   Traceback (most recent call last):
     File "<stdin>", line 1, in ?
   AttributeError: 'InterfaceClass' object has no attribute 'x'
 
-Methods provide access to the method signature:
+Methods provide access to the method signature::
 
   >>> bar = IFoo['bar']
   >>> bar.getSignatureString()
@@ -146,7 +146,7 @@
 declaring interfaces.
 
 The most common way to declare interfaces is using the implements
-function in a class statement:
+function in a class statement::
 
   >>> class Foo:
   ...     zope.interface.implements(IFoo)
@@ -164,28 +164,28 @@
 In this example, we declared that `Foo` implements `IFoo`. This means
 that instances of `Foo` provide `IFoo`.  Having made this declaration,
 there are several ways we can introspect the declarations.  First, we
-can ask an interface whether it is implemented by a class:
+can ask an interface whether it is implemented by a class::
 
   >>> IFoo.implementedBy(Foo)
   True
   
-And we can ask whether an interface is provided by an object:
+And we can ask whether an interface is provided by an object::
 
   >>> foo = Foo()
   >>> IFoo.providedBy(foo)
   True
 
-Of course, `Foo` doesn't provide `IFoo`, it implements it.
+Of course, `Foo` doesn't provide `IFoo`, it implements it::
 
   >>> IFoo.providedBy(Foo)
   False
 
-We can also ask what interfaces are implemented by an object:
+We can also ask what interfaces are implemented by an object::
 
   >>> list(zope.interface.implementedBy(Foo))
   [<InterfaceClass __main__.IFoo>]
 
-It's an error to ask for interfaces implemented by a non-class:
+It's an error to ask for interfaces implemented by a non-class::
 
   >>> IFoo.implementedBy(foo)
   Traceback (most recent call last):
@@ -197,7 +197,7 @@
   ...
   TypeError: ('ImplementedBy called for non-type', Foo(None))
 
-Similarly, we can ask what interfaces are provided by an object:
+Similarly, we can ask what interfaces are provided by an object::
 
   >>> list(zope.interface.providedBy(foo))
   [<InterfaceClass __main__.IFoo>]
@@ -208,7 +208,7 @@
 we want to document what the `__init__` method of the `Foo` class
 does.  It's not *really* part of `IFoo`.  You wouldn't normally call
 the `__init__` method on Foo instances.  Rather, the `__init__` method
-is part of the `Foo`'s `__call__` method:
+is part of the `Foo`'s `__call__` method::
 
   >>> class IFooFactory(zope.interface.Interface):
   ...     """Create foos"""
@@ -220,11 +220,11 @@
   ...         """
 
 It's the class that provides this interface, so we declare the
-interface on the class:
+interface on the class::
 
   >>> zope.interface.directlyProvides(Foo, IFooFactory)
 
-And then, we'll see that Foo provides some interfaces:
+And then, we'll see that Foo provides some interfaces::
 
   >>> list(zope.interface.providedBy(Foo))
   [<InterfaceClass __main__.IFooFactory>]
@@ -233,7 +233,7 @@
 
 Declaring class interfaces is common enough that there's a special
 declaration function for it, `classProvides`, that allows the
-declaration from within a class statement:
+declaration from within a class statement::
 
   >>> class Foo2:
   ...     zope.interface.implements(IFoo)
@@ -260,7 +260,7 @@
 
 Sometimes, we want to declare interfaces on instances, even though
 those instances get interfaces from their classes.  Suppose we create
-a new interface, `ISpecial`:
+a new interface, `ISpecial`::
 
   >>> class ISpecial(zope.interface.Interface):
   ...     reason = zope.interface.Attribute("Reason why we're special")
@@ -268,7 +268,7 @@
   ...         "Brag about being special"
 
 We can make a an existing foo instance special by providing `reason`
-and `brag` attributes:
+and `brag` attributes::
 
   >>> foo.reason = 'I just am'
   >>> def brag():
@@ -279,18 +279,18 @@
   >>> foo.brag()
   "I'm special!"
 
-and by declaring the interface:
+and by declaring the interface::
 
   >>> zope.interface.directlyProvides(foo, ISpecial)
 
-then the new interface is included in the provided interfaces:
+then the new interface is included in the provided interfaces::
 
   >>> ISpecial.providedBy(foo)
   True
   >>> list(zope.interface.providedBy(foo))
   [<InterfaceClass __main__.ISpecial>, <InterfaceClass __main__.IFoo>]
 
-We can find out what interfaces are directly provided by an object:
+We can find out what interfaces are directly provided by an object::
 
   >>> list(zope.interface.directlyProvidedBy(foo))
   [<InterfaceClass __main__.ISpecial>]
@@ -302,7 +302,7 @@
 Inherited declarations
 ----------------------
 
-Normally, declarations are inherited:
+Normally, declarations are inherited::
 
   >>> class SpecialFoo(Foo):
   ...     zope.interface.implements(ISpecial)
@@ -317,7 +317,7 @@
   [<InterfaceClass __main__.ISpecial>, <InterfaceClass __main__.IFoo>]
 
 Sometimes, you don't want to inherit declarations.  In that case, you
-can use `implementsOnly`, instead of `implements`:
+can use `implementsOnly`, instead of `implements`::
 
   >>> class Special(Foo):
   ...     zope.interface.implementsOnly(ISpecial)
@@ -338,7 +338,7 @@
 definition. Sometimes, we may want to make declarations from outside
 the class definition. For example, we might want to declare interfaces
 for classes that we didn't write.  The function `classImplements` can
-be used for this purpose:
+be used for this purpose::
 
   >>> class C:
   ...     pass
@@ -347,7 +347,7 @@
   >>> list(zope.interface.implementedBy(C))
   [<InterfaceClass __main__.IFoo>]
 
-We can use `classImplementsOnly` to exclude inherited interfaces:
+We can use `classImplementsOnly` to exclude inherited interfaces::
 
   >>> class C(Foo):
   ...     pass
@@ -362,7 +362,7 @@
 -------------------
 
 When we declare interfaces, we create *declaration* objects.  When we
-query declarations, declaration objects are returned:
+query declarations, declaration objects are returned::
 
   >>> type(zope.interface.implementedBy(Special))
   <class 'zope.interface.declarations.Implements'>
@@ -370,7 +370,7 @@
 Declaration objects and interface objects are similar in many ways. In
 fact, they share a common base class.  The important thing to realize
 about them is that they can be used where interfaces are expected in
-declarations. Here's a silly example:
+declarations. Here's a silly example::
 
   >>> class Special2(Foo):
   ...     zope.interface.implementsOnly(
@@ -383,7 +383,7 @@
 
 The declaration here is almost the same as
 ``zope.interface.implements(ISpecial)``, except that the order of
-interfaces in the resulting declaration is different:
+interfaces in the resulting declaration is different::
 
   >>> list(zope.interface.implementedBy(Special2))
   [<InterfaceClass __main__.IFoo>, <InterfaceClass __main__.ISpecial>]
@@ -395,7 +395,7 @@
 =====================
 
 Interfaces can extend other interfaces. They do this simply by listing
-the other interfaces as base interfaces:
+the other interfaces as base interfaces::
 
   >>> class IBlat(zope.interface.Interface):
   ...     """Blat blah blah"""
@@ -421,7 +421,7 @@
   >>> names
   ['bar', 'eek', 'x', 'y']
 
-Note that `IBaz` overrides eek:
+Note that `IBaz` overrides eek::
 
   >>> IBlat['eek'].__doc__
   'eek blah blah'
@@ -432,19 +432,19 @@
 extending an interface, the extending interface should be compatible
 [#compat]_ with the extended interfaces.
 
-We can ask whether one interface extends another:
+We can ask whether one interface extends another::
 
   >>> IBaz.extends(IFoo)
   True
   >>> IBlat.extends(IFoo)
   False
 
-Note that interfaces don't extend themselves:
+Note that interfaces don't extend themselves::
 
   >>> IBaz.extends(IBaz)
   False
 
-Sometimes we wish they did, but we can, instead use `isOrExtends`:
+Sometimes we wish they did, but we can, instead use `isOrExtends`::
 
   >>> IBaz.isOrExtends(IBaz)
   True
@@ -456,7 +456,7 @@
 When we iterate over an interface, we get all of the names it defines,
 including names defined by base interfaces. Sometimes, we want *just*
 the names defined by the interface directly. We bane use the `names`
-method for that:
+method for that::
 
   >>> list(IBaz.names())
   ['eek']
@@ -467,7 +467,7 @@
 
 Interfaces and attribute descriptions support an extension mechanism,
 borrowed from UML, called "tagged values" that lets us store extra
-data:
+data::
 
   >>> IFoo.setTaggedValue('date-modified', '2004-04-01')
   >>> IFoo.setTaggedValue('author', 'Jim Fulton')
@@ -482,7 +482,7 @@
   ['author', 'date-modified']
 
 Function attributes are converted to tagged values when method
-attribute definitions are created:
+attribute definitions are created::
 
   >>> class IBazFactory(zope.interface.Interface):
   ...     def __call__():
@@ -500,7 +500,7 @@
 provide them. These conditions are expressed using one or more
 invariants.  Invariants are callable objects that will be called with
 an object that provides an interface. An invariant raises an `Invalid`
-exception if the condition doesn't hold.  Here's an example:
+exception if the condition doesn't hold.  Here's an example::
 
   >>> class RangeError(zope.interface.Invalid):
   ...     """A range has invalid limits"""
@@ -511,7 +511,7 @@
   ...     if ob.max < ob.min:
   ...         raise RangeError(ob)
 
-Given this invariant, we can use it in an interface definition:
+Given this invariant, we can use it in an interface definition::
 
   >>> class IRange(zope.interface.Interface):
   ...     min = zope.interface.Attribute("Lower bound")
@@ -519,7 +519,7 @@
   ...
   ...     zope.interface.invariant(range_invariant)
 
-Interfaces have a method for checking their invariants:
+Interfaces have a method for checking their invariants::
 
   >>> class Range(object):
   ...     zope.interface.implements(IRange)
@@ -540,7 +540,7 @@
 If you have multiple invariants, you may not want to stop checking
 after the first error.  If you pass a list to `validateInvariants`,
 then a single `Invalid` exception will be raised with the list of
-exceptions as it's argument:
+exceptions as it's argument::
 
   >>> errors = []
   >>> IRange.validateInvariants(Range(2,1), errors)
@@ -548,7 +548,7 @@
   ...
   Invalid: [RangeError(Range(2, 1))]
 
-And the list will be filled with the individual exceptions:
+And the list will be filled with the individual exceptions::
   
   >>> errors
   [RangeError(Range(2, 1))]

Modified: Zope3/trunk/src/zope/interface/adapter.txt
===================================================================
--- Zope3/trunk/src/zope/interface/adapter.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/interface/adapter.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -94,7 +94,7 @@
   >>> registry.lookup([IR1], IP1, 'bob')
   "Bob's 12"
 
-You can leave the name off when doing a lookup:
+You can leave the name off when doing a lookup::
 
   >>> registry.lookup([IR1], IP1)
   12
@@ -118,8 +118,8 @@
 lookup1
 -------
 
-Lookup of single adapters is common enough that there is a
-specialized version of lookup that takes a single required interface:
+Lookup of single adapters is common enough that there is a specialized
+version of lookup that takes a single required interface::
 
   >>> registry.lookup1(IR2, IP1, '')
   21
@@ -133,7 +133,7 @@
 object that implements an interface is adapted to another object that
 supports a different interface.  The adapter registry supports the
 computation of adapters. In this case, we have to register adapter
-factories: 
+factories::
 
    >>> class IR(zope.interface.Interface):
    ...     pass
@@ -149,7 +149,7 @@
   >>> registry.register([IR], IP1, '', Y)
 
 In this case, we registered a class as the factory. Now we can call
-`queryAdapter` to get the adapted object:
+`queryAdapter` to get the adapted object::
 
   >>> x = X()
   >>> y = registry.queryAdapter(x, IP1)
@@ -158,7 +158,7 @@
   >>> y.context is x
   True
 
-We can register and lookup by name too:
+We can register and lookup by name too::
 
   >>> class Y2(Y):
   ...     pass
@@ -170,8 +170,8 @@
   >>> y.context is x
   True
 
-An alternate method that provides the same function as `queryAdapter` is
-`adapter_hook`:
+An alternate method that provides the same function as `queryAdapter()` is
+`adapter_hook()`::
 
   >>> y = registry.adapter_hook(IP1, x)
   >>> y.__class__.__name__
@@ -184,7 +184,7 @@
   >>> y.context is x
   True
 
-The `adapter_hook` simply switches the order of the object and
+The `adapter_hook()` simply switches the order of the object and
 interface arguments.  It is used to hook into the interface call
 mechanism.
 
@@ -223,7 +223,7 @@
 Unregistering
 -------------
 
-You can unregister by registering None, rather than an object:;
+You can unregister by registering None, rather than an object::
 
   >>> registry.register([zope.interface.implementedBy(C2)], IP1, '', None)
   >>> registry.lookup([zope.interface.implementedBy(C2)], IP1, '')
@@ -261,12 +261,12 @@
 Multi-adaptation
 ----------------
 
-You can adapt multiple objects:
+You can adapt multiple objects::
 
   >>> class Q:
   ...     zope.interface.implements(IQ)
 
-As with single adapters, we register a factory, which is often a class:
+As with single adapters, we register a factory, which is often a class::
 
   >>> class IM(zope.interface.Interface):
   ...     pass
@@ -276,7 +276,7 @@
   ...         self.x, self.q = x, q
   >>> registry.register([IR, IQ], IM, '', M)
 
-And then we can call `queryMultiAdapter` to compute an adapter:
+And then we can call `queryMultiAdapter` to compute an adapter::
 
   >>> q = Q()
   >>> m = registry.queryMultiAdapter((x, q), IM)
@@ -285,7 +285,7 @@
   >>> m.x is x and m.q is q
   True
 
-and, of course, we can use names:
+and, of course, we can use names::
 
   >>> class M2(M):
   ...     pass
@@ -300,7 +300,7 @@
 ----------------
 
 As with single adapters, you can define default adapters by specifying
-None for the *first* specification:
+None for the *first* specification::
 
   >>> registry.register([None, IQ], IP2, '', 'q2')
   >>> registry.lookup([IS, IQ], IP2, '')
@@ -309,7 +309,7 @@
 Null Adapters
 =============
 
-You can also adapt no specification:
+You can also adapt no specification::
 
   >>> registry.register([], IP2, '', 2)
   >>> registry.lookup([], IP2, '')
@@ -321,14 +321,14 @@
 ----------------------
 
 Adapters are named. Sometimes, it's useful to get all of the named
-adapters for given interfaces.
+adapters for given interfaces::
 
   >>> adapters = list(registry.lookupAll([IR1], IP1))
   >>> adapters.sort()
   >>> adapters
   [(u'', 11), (u'bob', "Bob's 12")]
 
-This works for multi-adapters too:
+This works for multi-adapters too::
 
   >>> registry.register([IR1, IQ2], IP2, 'bob', '1q2 for bob')
   >>> adapters = list(registry.lookupAll([IR2, IQ2], IP1))
@@ -336,7 +336,7 @@
   >>> adapters
   [(u'', '1q22'), (u'bob', '1q2 for bob')]
 
-And even null adapters:
+And even null adapters::
 
   >>> registry.register([], IP2, 'bob', 3)
   >>> adapters = list(registry.lookupAll([], IP1))
@@ -437,7 +437,7 @@
 
 We normally register adapter factories, which then allow us to compute
 adapters, but with subscriptions, we get multiple adapters.  Here's an
-example of multiple-object subscribers:
+example of multiple-object subscribers::
 
   >>> registry.subscribe([IR, IQ], IM, M)
   >>> registry.subscribe([IR, IQ], IM, M2)
@@ -460,7 +460,7 @@
 output.  It returns None.  A handler is unlike adapters in that it does
 all of it's work when the factory is called.
 
-To register a handler, simply provide None as the provided interface:
+To register a handler, simply provide None as the provided interface::
 
   >>> def handler(event):
   ...     print 'handler', event

Modified: Zope3/trunk/src/zope/interface/tests/foodforthought.txt
===================================================================
--- Zope3/trunk/src/zope/interface/tests/foodforthought.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/interface/tests/foodforthought.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -3,7 +3,7 @@
 ================================
 
 
-This file gives more subscription examples using a cooking-based examples
+This file gives more subscription examples using a cooking-based example::
 
     >>> from zope.interface.adapter import AdapterRegistry
     >>> registry = AdapterRegistry()
@@ -19,7 +19,7 @@
     ...     pass
 
 Adapting to some other interface for which there is no
-subscription adapter returns an empty sequence:
+subscription adapter returns an empty sequence::
 
     >>> class IRecipe(zope.interface.Interface):
     ...     pass
@@ -30,32 +30,32 @@
     >>> class IKFC(IRecipe):
     ...     pass
 
->>> list(registry.subscriptions([IPoultry], IRecipe))
-[]
+    >>> list(registry.subscriptions([IPoultry], IRecipe))
+    []
 
 unless we define a subscription::
 
->>> registry.subscribe([IAnimal], ISausages, 'sausages')
->>> list(registry.subscriptions([IPoultry], ISausages))
-['sausages']
+    >>> registry.subscribe([IAnimal], ISausages, 'sausages')
+    >>> list(registry.subscriptions([IPoultry], ISausages))
+    ['sausages']
 
-And define another subscription adapter:
+And define another subscription adapter::
 
->>> registry.subscribe([IPoultry], INoodles, 'noodles')
->>> meals = list(registry.subscriptions([IPoultry], IRecipe))
->>> meals.sort()
->>> meals
-['noodles', 'sausages']
+    >>> registry.subscribe([IPoultry], INoodles, 'noodles')
+    >>> meals = list(registry.subscriptions([IPoultry], IRecipe))
+    >>> meals.sort()
+    >>> meals
+    ['noodles', 'sausages']
 
->>> registry.subscribe([IChicken], IKFC, 'kfc')
->>> meals = list(registry.subscriptions([IChicken], IRecipe))
->>> meals.sort()
->>> meals
-['kfc', 'noodles', 'sausages']
+    >>> registry.subscribe([IChicken], IKFC, 'kfc')
+    >>> meals = list(registry.subscriptions([IChicken], IRecipe))
+    >>> meals.sort()
+    >>> meals
+    ['kfc', 'noodles', 'sausages']
 
-And the answer for poultry hasn't changed:
+And the answer for poultry hasn't changed::
 
->>> meals = list(registry.subscriptions([IPoultry], IRecipe))
->>> meals.sort()
->>> meals
-['noodles', 'sausages']
+    >>> meals = list(registry.subscriptions([IPoultry], IRecipe))
+    >>> meals.sort()
+    >>> meals
+    ['noodles', 'sausages']

Modified: Zope3/trunk/src/zope/schema/fields.txt
===================================================================
--- Zope3/trunk/src/zope/schema/fields.txt	2004-07-16 21:10:53 UTC (rev 26599)
+++ Zope3/trunk/src/zope/schema/fields.txt	2004-07-16 21:14:43 UTC (rev 26600)
@@ -152,4 +152,4 @@
 on the basis of uniqueness and other constraints.
 
 This level of indirection may be unnecessary for some applications, and can be
-disabled with simple zcml changes within zope.app.
+disabled with simple ZCML changes within `zope.app`.



More information about the Zope3-Checkins mailing list