[Zope-Checkins] SVN: Zope/trunk/src/Products/Five/doc/ Started updating the Five documentation to avoid referencing Zope 3.
Hanno Schlichting
hannosch at hannosch.eu
Fri Jan 1 13:24:45 EST 2010
Log message for revision 107510:
Started updating the Five documentation to avoid referencing Zope 3.
Changed:
U Zope/trunk/src/Products/Five/doc/directives.txt
U Zope/trunk/src/Products/Five/doc/event.txt
U Zope/trunk/src/Products/Five/doc/features.txt
U Zope/trunk/src/Products/Five/doc/i18n.txt
U Zope/trunk/src/Products/Five/doc/main.txt
-=-
Modified: Zope/trunk/src/Products/Five/doc/directives.txt
===================================================================
--- Zope/trunk/src/Products/Five/doc/directives.txt 2010-01-01 17:55:12 UTC (rev 107509)
+++ Zope/trunk/src/Products/Five/doc/directives.txt 2010-01-01 18:24:44 UTC (rev 107510)
@@ -1,9 +1,9 @@
-=================================
-ZCML Directives supported by Five
-=================================
+===================================
+ZCML Directives supported by Zope 2
+===================================
-Five tries to use the Zope 3 ZCML directives where possible, though
-does sometimes subset the possible attributes. It also introduces a
+Zope 2 tries to use the directives from zope.* packages where possible,
+though does sometimes subset the possible attributes. It also introduces a
few directives of its own under the ``five`` namespace.
Directives are listed per namespace, in alphabetic order.
@@ -24,8 +24,7 @@
permission
----------
-Way to make Zope 2 permissions available to Five, ``title`` is
-permission name.
+Way to make Zope 2 permissions available, ``title`` is permission name.
redefinePermission
------------------
@@ -53,8 +52,7 @@
page
----
-Declare a page view for an interface. Permission is a Zope 2
-permission.
+Declare a page view for an interface. Permission is a Zope 2 permission.
pages
-----
@@ -105,7 +103,7 @@
sizable
-------
-Retrieve size information for a Zope 2 content class via a Zope 3
+Retrieve size information for a Zope 2 content class via a zope.size
style ``ISized`` adapter.
deprecatedManageAddDelete
@@ -123,4 +121,4 @@
registerClass
-------------
-Registers Five content with Zope 2.
+Registers Zope 2 content classes with Zope 2.
Modified: Zope/trunk/src/Products/Five/doc/event.txt
===================================================================
--- Zope/trunk/src/Products/Five/doc/event.txt 2010-01-01 17:55:12 UTC (rev 107509)
+++ Zope/trunk/src/Products/Five/doc/event.txt 2010-01-01 18:24:44 UTC (rev 107510)
@@ -1,8 +1,7 @@
-Events in Zope 2.9
-==================
+Events in Zope 2
+================
-Zope 2.9 (and Zope 2.8 when using Five 1.2) introduces a big change:
-Zope 3 style container events.
+Zope 2 supports zope.lifecycleevent style events including container events.
With container events, you finally have the ability to react to things
happening to objects without have to subclass ``manage_afterAdd``,
@@ -39,11 +38,11 @@
super(CoolDocument, self).manage_beforeDelete(item, container)
getToolByName(self, 'portal_cool').unregisterCool(self)
-This would be the best practice in Zope 2.8. Note the use of ``super()``
-to call the base class, which is often omitted because people "know"
-that SimpleItem for instance doesn't do anything in these methods.
+This had been the best practice in old Zope 2 versions. Note the use of
+``super()`` to call the base class, which is often omitted because people
+"know" that SimpleItem for instance doesn't do anything in these methods.
-If you run this code in Zope 2.9, you will get deprecation warnings,
+If you run this code today, you will get deprecation warnings,
telling you that::
Calling Products.CoolProduct.CoolDocument.CoolDocument.manage_afterAdd
@@ -70,7 +69,7 @@
will be sending events when an object is added, for instance, and in
addition call your old ``manage_afterAdd`` method.
-One subtlety here is that you may have to modify you methods to just do
+One subtlety here is that you may have to modify your methods to just do
their work, and not call their super class. This is necessary because
proper events are already dispatched to all relevant classes, and the
work of the super class will be done trough events, you must not redo it
@@ -90,8 +89,7 @@
Using subscribers
-----------------
-In the long run, and before Zope 2.11 where ``manage_afterAdd`` and
-friends will be removed, you will want to use proper subscribers.
+In the long run, you will want to use proper subscribers.
First, you'll have to write a subscriber that "does the work", for
instance::
@@ -157,7 +155,7 @@
instance they wouldn't have any way of doing some cleanup before they
disappear.
-To solve these two problems, Zope 3 has an additional mechanism by which
+To solve these two problems, Zope has an additional mechanism by which
any IObjectEvent is redispatched using multi-adapters of the form ``(ob,
event)``, so that a subscriber can be specific about the type of object
it's interested in. Furthermore, this is done recursively for all
@@ -189,8 +187,7 @@
Five/tests/event.txt).
The first use case is the one where the object has to be aware of its
-path, like in the CoolDocument example above. That's strictly a Zope 2
-concern, as Zope 3 has others ways to deal with this.
+path, like in the CoolDocument example above.
In Zope 2 an object has a new path through creation, copy or move
(rename is a kind of move). The events sent during these three
@@ -200,7 +197,7 @@
So to react to new paths, we have to subscribe to IObjectMovedEvent, but
this will also get us any IObjectRemovedEvent, which we'll have to
-filter out by hand (this is unfortunate, and due to the way the Zope 3
+filter out by hand (this is unfortunate, and due to the way the Zope
interface hierarchy is organized). So to fix the CoolDocument
configuration we have to add::
@@ -282,5 +279,5 @@
multi-subscribers we have registered.)
The ``IObjectWillBe...`` events are specific to Zope 2 (and imported
-from ``OFS.interfaces``). Zope 3 doesn't really need them, as object
-identity is often enough.
+from ``OFS.interfaces``). zope.lifecycleevent doesn't really need them, as
+object identity is often enough.
Modified: Zope/trunk/src/Products/Five/doc/features.txt
===================================================================
--- Zope/trunk/src/Products/Five/doc/features.txt 2010-01-01 17:55:12 UTC (rev 107509)
+++ Zope/trunk/src/Products/Five/doc/features.txt 2010-01-01 18:24:44 UTC (rev 107510)
@@ -1,23 +1,22 @@
=============
-Five features
+Zope features
=============
-Five features are mostly Zope 3 features, though Five has some extras,
-and some limitations.
+Zope features are mostly features from zope.* packages, though it has some
+extras and some limitations.
ZCML
====
-ZCML is the Zope Configuration Markup Language, an XML application.
-Zope 3 (and Five) code consists of a lot of components that can be
-plugged together using ZCML.
+ZCML is the Zope Configuration Markup Language, an XML application. Zope code
+consists of a lot of components that can be plugged together using ZCML.
-If you put a ``site.zcml`` in the home directory of your Zope
+If you put a ``site.zcml`` in the etc directory of your Zope
instance, this is the root of the ZCML tree. An example of
``site.zcml`` is in ``site.zcml.in``. If you don't place a
``site.zcml``, Five falls back on ``fallback.zcml``.
-ZCML in Five has special directive, ``five:loadProducts``, to load the
+ZCML in Zope 2 has a special directive, ``five:loadProducts``, to load the
ZCML (``meta.zcml``, ``configure.zcml``) of all installed Zope 2
products, if available.
@@ -29,16 +28,15 @@
Security declarations
=====================
-Five aims to eradicate ``declareProtected``, ``ClassSecurityInfo`` and
-``initializeClass`` from your Zope 2 code.
+Zope 2 aims to eradicate ``declareProtected``, ``ClassSecurityInfo`` and
+``initializeClass`` from your code.
-In order to do this, Five provides the Zope 3 way of declaring
-permissions from ZCML, but uses the Zope 2 mechanisms to actually set
-them. To declare permissions for methods and templates on views you
-use the ``permission`` attribute on the ``browser:page`` directive,
-and specify a Zope 2 permission (given a Zope 3 name). You can find a
-list of these permissions in ``permissions.zcml`` in Five. The
-permission check takes place before the view is executed.
+In order to do this, Zope 2 provides a way of declaring permissions from ZCML.
+To declare permissions for methods and templates on views you use the
+``permission`` attribute on the ``browser:page`` directive, and specify a
+Zope 2 permission (given a dotted name). You can find a list of these
+permissions in ``permissions.zcml`` in AccessControl's permissions.zcml.
+The permission check takes place before the view is executed.
The ``class`` directive can also be used to declare permissions on
Zope 2 content classes. Note however that these permissions will be
Modified: Zope/trunk/src/Products/Five/doc/i18n.txt
===================================================================
--- Zope/trunk/src/Products/Five/doc/i18n.txt 2010-01-01 17:55:12 UTC (rev 107509)
+++ Zope/trunk/src/Products/Five/doc/i18n.txt 2010-01-01 18:24:44 UTC (rev 107510)
@@ -4,8 +4,7 @@
Translation
-----------
-To register Zope 3 style translation domains, use the following ZCML
-statement::
+To register translation domains, use the following ZCML statement::
<i18n:registerTranslations directory="locales" />
Modified: Zope/trunk/src/Products/Five/doc/main.txt
===================================================================
--- Zope/trunk/src/Products/Five/doc/main.txt 2010-01-01 17:55:12 UTC (rev 107509)
+++ Zope/trunk/src/Products/Five/doc/main.txt 2010-01-01 18:24:44 UTC (rev 107510)
@@ -1,6 +1,6 @@
Five, the Zope 3 in Zope 2 project
==================================
-
+
What is Five?
-------------
More information about the Zope-Checkins
mailing list