[Zope-Checkins] SVN: Zope/trunk/src/Products/Five/ More documentation updates

Hanno Schlichting hannosch at hannosch.eu
Fri Jan 1 13:53:56 EST 2010


Log message for revision 107511:
  More documentation updates
  

Changed:
  U   Zope/trunk/src/Products/Five/browser/pagetemplatefile.py
  U   Zope/trunk/src/Products/Five/browser/resource.py
  U   Zope/trunk/src/Products/Five/browser/tests/classes.py
  U   Zope/trunk/src/Products/Five/browser/tests/pages_ftest.txt
  U   Zope/trunk/src/Products/Five/browser/tests/provider.txt
  U   Zope/trunk/src/Products/Five/component/__init__.py
  U   Zope/trunk/src/Products/Five/component/component.txt
  U   Zope/trunk/src/Products/Five/doc/main.txt
  U   Zope/trunk/src/Products/Five/doc/manual.txt
  D   Zope/trunk/src/Products/Five/doc/presentations/
  D   Zope/trunk/src/Products/Five/doc/products/
  U   Zope/trunk/src/Products/Five/fiveconfigure.py

-=-
Modified: Zope/trunk/src/Products/Five/browser/pagetemplatefile.py
===================================================================
--- Zope/trunk/src/Products/Five/browser/pagetemplatefile.py	2010-01-01 18:24:44 UTC (rev 107510)
+++ Zope/trunk/src/Products/Five/browser/pagetemplatefile.py	2010-01-01 18:53:56 UTC (rev 107511)
@@ -47,8 +47,8 @@
 
     def __call__(self, __instance, *args, **keywords):
         # Work around BBB foul. Before Zope 2.12 there was no first argument
-        # but the Zope 3 version has one called instance. Some people used
-        # instance as an additional keyword argument.
+        # but the zope.pagetemplate version has one called instance. Some
+        # people used instance as an additional keyword argument.
         instance = __instance
         namespace = self.pt_getContext(
             request=instance.request,

Modified: Zope/trunk/src/Products/Five/browser/resource.py
===================================================================
--- Zope/trunk/src/Products/Five/browser/resource.py	2010-01-01 18:24:44 UTC (rev 107510)
+++ Zope/trunk/src/Products/Five/browser/resource.py	2010-01-01 18:53:56 UTC (rev 107511)
@@ -35,7 +35,7 @@
 class Resource(object):
     """A mixin that changes the URL-rendering of resources (__call__).
 
-    In Zope 3, resource URLs are of the form
+    In zope.browserresource, resource URLs are of the form
     nearest_site/@@/resource_name.  Since Zope 2 didn't have support
     for sites from the beginning of the Five integration, resource
     URLs in Zope 2 are of the form context/++resource++resource_name.

Modified: Zope/trunk/src/Products/Five/browser/tests/classes.py
===================================================================
--- Zope/trunk/src/Products/Five/browser/tests/classes.py	2010-01-01 18:24:44 UTC (rev 107510)
+++ Zope/trunk/src/Products/Five/browser/tests/classes.py	2010-01-01 18:53:56 UTC (rev 107511)
@@ -19,7 +19,7 @@
 from Products.Five import BrowserView
 
 class IOne(Interface):
-    """This is a Zope 3 interface.
+    """This is an interface.
     """
 
 class One(object):

Modified: Zope/trunk/src/Products/Five/browser/tests/pages_ftest.txt
===================================================================
--- Zope/trunk/src/Products/Five/browser/tests/pages_ftest.txt	2010-01-01 18:24:44 UTC (rev 107510)
+++ Zope/trunk/src/Products/Five/browser/tests/pages_ftest.txt	2010-01-01 18:53:56 UTC (rev 107511)
@@ -19,7 +19,7 @@
 ----------
 
 In Zope 2, objects normally have to have a docstring in order to be
-published.  This crazy requirement luckily isn't true for Zope 3, so
+published.  This crazy requirement luckily isn't true for zope.publisher, so
 it should be possible to write docstring-less view classes that are
 still published through ZPublisher.
 

Modified: Zope/trunk/src/Products/Five/browser/tests/provider.txt
===================================================================
--- Zope/trunk/src/Products/Five/browser/tests/provider.txt	2010-01-01 18:24:44 UTC (rev 107510)
+++ Zope/trunk/src/Products/Five/browser/tests/provider.txt	2010-01-01 18:53:56 UTC (rev 107511)
@@ -18,9 +18,9 @@
 
 Content Provider is a term from the Java world that refers to components that
 can provide HTML content. It means nothing more! How the content is found and
-returned is totally up to the implementation. The Zope 3 touch to the concept
-is that content providers are multi-adapters that are looked up by the
-context, request (and thus the layer/skin), and view they are displayed in.
+returned is totally up to the implementation. The Zope touch to the concept is
+that content providers are multi-adapters that are looked up by the context,
+request (and thus the layer/skin), and view they are displayed in.
 
 So let's create a simple content provider:
 

Modified: Zope/trunk/src/Products/Five/component/__init__.py
===================================================================
--- Zope/trunk/src/Products/Five/component/__init__.py	2010-01-01 18:24:44 UTC (rev 107510)
+++ Zope/trunk/src/Products/Five/component/__init__.py	2010-01-01 18:53:56 UTC (rev 107511)
@@ -43,7 +43,7 @@
 @zope.interface.implementer(IComponentLookup)
 def siteManagerAdapter(ob):
     """Look-up a site manager/component registry for local component
-    lookup.  This is registered in place of the one in Zope 3 so that
+    lookup.  This is registered in place of the one in zope.site so that
     we lookup using acquisition in addition to the ``ILocation`` API.
     """
     site = findSite(ob)

Modified: Zope/trunk/src/Products/Five/component/component.txt
===================================================================
--- Zope/trunk/src/Products/Five/component/component.txt	2010-01-01 18:24:44 UTC (rev 107510)
+++ Zope/trunk/src/Products/Five/component/component.txt	2010-01-01 18:53:56 UTC (rev 107511)
@@ -5,7 +5,7 @@
 -----------------------------
 
 In order to do context-based component look-up, the Component
-Architecture adapts the context to ``IComponentLookup``.  Zope 3's
+Architecture adapts the context to ``IComponentLookup``.  zope.site's
 default adapter uses the ``ILocation`` API to walk up the object tree
 and find a site that way.  Five provides its own adapter that also
 supports acquisitional parents.

Modified: Zope/trunk/src/Products/Five/doc/main.txt
===================================================================
--- Zope/trunk/src/Products/Five/doc/main.txt	2010-01-01 18:24:44 UTC (rev 107510)
+++ Zope/trunk/src/Products/Five/doc/main.txt	2010-01-01 18:53:56 UTC (rev 107511)
@@ -1,79 +1,22 @@
-Five, the Zope 3 in Zope 2 project
-==================================
+Five, a Zope Integration project
+================================
 
 What is Five?
 -------------
 
-Five is a Zope 2 product that allows you to integrate Zope 3
-technologies into Zope 2, today.  Among others, it allows you to use
-Zope 3 interfaces, ZCML-based configuration, adapters, browser pages
-(including skins, layers, and resources), automated add and edit forms
-based on schemas, object events, as well as Zope 3-style i18n message
-catalogs.
+A couple of years back an attempt was made to rewrite Zope 2 from scratch and
+provide an upgrade path from current Zope 2 to the new version. This project
+used the name Zope 3. The attempt of writing a newer version of a full blown
+application server similar to Zope 2 failed. Instead the project generated a
+whole lot of underlying technologies and new concepts packaged up in reusable
+libraries.
 
-We've tried to keep the Five experience as close to Zope 3 as
-possible, so this means that what you learn while using Five should
-also be applicable to Zope 3, and viceversa.  We're in the process of
-evaluating lots more Zope 3 technologies for integration into Zope 2.
-This is the right moment for interested Zope 2 and Zope 3 developers
-to jump in.  We're looking for cooperation between different Zope 2
-projects so that this can be a foundational system for us all.
+Five is the project that integrates those technologies and packages into
+Zope 2. It's name is a pun on the original naming of Zope 2 + Zope 3 = Zope 5.
+Among others, it allows you to use zope.interface, ZCML-based configuration,
+adapters, browser pages (including layers, and resources), zope.schemas,
+object events, as well as zope.i18n message catalogs.
 
-Download
---------
-
-We have released Five 1.2.6 on 13 August 2006.  You may download it
-here:
-
-http://codespeak.net/z3/five/release/Five-1.2.6.tgz
-
-We have released Five 1.3.8 on 4 November 2006.  This is a bugfix
-release for Five 1.3 and will be included in the next Zope 2.9 bugfix
-release.  You may download it here:
-
-http://codespeak.net/z3/five/release/Five-1.3.8.tgz
-
-We have also released Five 1.4.2.  This is a feature release and is
-compatible with Zope 2.9.  You may download it here:
-
-http://codespeak.net/z3/five/release/Five-1.4.2.tgz
-
-We have also released Five 1.5.1.  It will be included with the next
-Zope 2.10 bugfix release.  You may download it here:
-
-http://codespeak.net/z3/five/release/Five-1.5.1.tgz
-
-To check which version of Five is compatible with which version of
-Zope, please refer to the `compatibility matrix
-<http://codespeak.net/z3/five/INSTALL.html>`_.
-
-Joining the project
--------------------
-
-Five is kindly hosted on codespeak.net, and is part of the larger
-*Zope 3 Base* project that offers an approachable area for
-developers of Zope 3 related software.
-
-Five has a mailing list: 
-
-http://codespeak.net/mailman/listinfo/z3-five
-
-We're also active on IRC, at ``#z3-base`` on freenode.
- 
-Five is hosted in a subversion repository on codespeak.net. You can
-browse this on the web here:
-
-http://codespeak.net/svn/z3/Five/
-
-You can check out Five using the following subversion command::
-
-  svn co svn://svn.zope.org/repos/main/Products.Five/trunk Five
-
-There's also a checkins mailing list for the Z3 project, here:
-
-http://codespeak.net/mailman/listinfo/z3-checkins
-
-If you want checkin access, please join the z3-five mailing list or
-the ``#z3-base`` IRC channel, and ask us there.
-
-We hope to hear from you!
+We've tried to keep the Five experience as close to that of the integrated
+Zope packages as possible, so this means that what you learn while using Five
+should also be applicable to the Zope packages directly.

Modified: Zope/trunk/src/Products/Five/doc/manual.txt
===================================================================
--- Zope/trunk/src/Products/Five/doc/manual.txt	2010-01-01 18:24:44 UTC (rev 107510)
+++ Zope/trunk/src/Products/Five/doc/manual.txt	2010-01-01 18:53:56 UTC (rev 107511)
@@ -2,36 +2,9 @@
 Five Manual
 ===========
 
-Introduction
-------------
+Zope interfaces
+---------------
 
-Five's goal is to let you, the Zope 2 developer, use Zope 3 code in
-Zope 2. Our aim is to make as much of Zope 3 code work in Zope 2 as
-possible, while integrating it with Zope 2.
-
-Five can be used inside your current Zope 2 project. The benefits are:
-
-* availability of Zope 3 technologies in Zope 2 like the component
-  architecture and declarative configuration.
-
-* you can gradually evolve your Zope 2 project so it is better
-  positioned for the migration to Zope 3.
-
-* you start learning about Zope 3 right now, preparing yourself better
-  for the future. Since Zope 3 is open to contributions, you could
-  even influence your future for the better.
-
-Five can also be used to develop new Zope 2 products, though depending
-on your deployment requirements it might in that case make more sense
-to develop for Zope 3 directly.
-
-Five is only useful on the Python (Product) level in Zope 2, not from
-within the Zope Management Interface. Five makes no attempt to provide
-a user interface, but is aimed squarely at the Python developer.
-
-Zope 3 interfaces
------------------
-
 Interfaces?
 ===========
 
@@ -95,61 +68,32 @@
   hopefully improving it.
 
 * If an object provides an interface, that object is considered to be
-  a *component*. This means you can use Zope 3's component
+  a *component*. This means you can use Zope's component
   architecture with these objects.
 
-In order to use Five, you'll have to make your objects provide
-interfaces. Sometimes, you cannot change the code of class (as you are
+In order to use the component architecture, you'll have to make your objects
+provide interfaces. Sometimes, you cannot change the code of class (as you are
 not the maintainer), but you still want to make it implement an
-interface. Five provides a ZCML directive to do this::
+interface. Zope provides a ZCML directive to do this::
 
-  <five:implements class="tolkien.Oliphant" 
-      implements="interfaces.IElephant" />
+  <class class="tolkien.Oliphant">
+    <implements interface=".interfaces.IElephant" />
+  </class>
 
-Interfaces in Zope 2 versus Zope 3
-==================================
-
-You may be familiar with Zope 2's way of declaring interfaces. Zope 2
-has used the ``__implements__`` class attribute for interface
-declarations. Zope 2 cannot detect Zope 3 interfaces and the Zope 3
-machinery cannot detect Zope 2 interfaces. This is a good thing, as
-Zope 2 has no way to deal with Zope 3 interfaces, and Zope 3 cannot
-comprehend Zope 2 interfaces. This means you can safely make a class
-declare both a Zope 2 and Zope 3 interface independently from each
-other. It's a rare case where you need this though; you're usually
-better off just switching to ``implements()`` for your application if
-you are using Five.
-
-Switching from Zope 2 interfaces to Zope 3 interfaces is easy -- just
-make your interfaces inherit from ``zope.interface.Interface`` instead
-of ``Interface.Interface`` (or ``Interface.Base``). Next, change all
-``__implements__`` to ``implements()``.
-
-This should get you going and your application may very well still
-work. Later on, you will also have to change calls to
-``isImplementedBy`` and such in your application to ``providedBy``, as
-``isImplementedBy`` has been deprecated (you'll see the
-DeprecationWarnings in your Zope log).
-
-N.B.:  As of Zope 2.12, the old Zope2 interfaces are *removed*.
-
 Adapters
 --------
 
 From a Python programmer's perspective, the immediate thing that Five
 brings to do the table are adapters. This section goes through some
-demo code to explain how everything is tied
-together. ``demo/FiveDemo`` is a demo Product you can install and
-examine that has all the presented here together.
+demo code to explain how everything is tied together.
 
-Zope 3 adapters depend on Zope 3 interfaces. To create a Zope 3
-interface you need to subclass it from
-``zope.interface.Interface``. Here is an example::
+Zope adapters depend on Zope interfaces. To create a Zope interface you need
+to subclass it from ``zope.interface.Interface``. Here is an example::
 
   from zope.interface import Interface
 
   class IMyInterface(Interface):
-      """This is a Zope 3 interface.
+      """This is an interface.
       """
       def someMethod():
           """This method does amazing stuff.
@@ -167,9 +111,6 @@
       def someMethod(self):
            return "I am alive! Alive!"
 
-For an explanation of the relation of Zope 3 interfaces to Zope 2
-interfaces, see below.
-
 Now let's set up the interface that we are adapting to::
 
   class INewInterface(Interface):
@@ -212,7 +153,7 @@
     
   </configure>
 
-Five will automatically pickup ``configure.zcml`` when it's placed in
+Zope will automatically pickup ``configure.zcml`` when it's placed in
 the product's directory.  Any object that provides ``IMyInterface``
 can now be adapted to ``INewInterface``, like this::
 
@@ -223,26 +164,18 @@
   adapted = INewInterface(object)
   print adapted.anotherMethod()
 
-Views in Five
--------------
+Views
+-----
 
-This section will give a brief introduction on how to use the five
-view system. ``demo/FiveViewsDemo`` is a demo Product you can install
-and examine that has all the presented here tied together, please
-consult it for more details. ``tests/products/FiveTest`` actually
-contains a more detailed set of test views, trying a number of
-features. Finally, read up on the way Zope 3 does it. While Five is a
-subset of Zope 3 functionality and has been adapted to work with Zope
-2, much of Zope 3's documentation still works.
+This section will give a brief introduction on how to use the Zope view system.
 
-Five enables you to create views for your own objects, or even built-in
+Zope enables you to create views for your own objects, or even built-in
 Zope objects, as long as two things are the case:
 
-* The object provides an Zope 3 interface, typically through its class.
+* The object provides a Zope interface, typically through its class.
 
-* The object (typically its class) is made Zope 3 traversable. This
-  allows Zope 3 views, resources and other things to be attached to a
-  Zope 2 object.
+* The object (typically its class) is made traversable. This allows Zope
+  views, resources and other things to be attached to a Zope object.
 
 Typically you give your classes an interface using the ``implements``
 directive in the class body::
@@ -256,36 +189,32 @@
 implement ``IFolder`` (an interface you defined), you can do the
 following in ZCML::
 
-  <five:implements class="OFS.Folder.Folder" 
-                   interface=".interfaces.IFolder" />
+  <class class="OFS.Folder.Folder" 
+    <implements interface=".interfaces.IFolder" />
+  </class>
 
-``five`` in this case refers to the XML namespace for Five,
-``http://namespace.zope.org/five``.
+Views in Zope are simple classes. The only requirements for a view class are:
 
-
-Views in Five are simple classes. The only requirements for a Five
-view class are:
-
 * They need an ``__init__()`` that take a context and a request
   attribute. Typically this comes from a base class, such as
   ``BrowserView``.
 
 An example of a simple view::
  
-  from Products.Five import BrowserView
+  from zope.publisher.browser import BrowserView
 
   class SimpleFolderView(BrowserView):
 
       def eagle(self):
           """Test
           """
-          return "The eagle has landed: %s" % self.context.objectIds()
+          return "The eagle has landed: %s" % self.context.keys()
 
 Note that it is not a good idea to give a view class its own
-``index_html``, as this confuses Five's view lookup machinery.
+``index_html``, as this confuses Zope's view lookup machinery.
 
-This view uses methods in Python, but you can also use other Zope 2 mechanisms
-such as ``PageTemplateFile``.
+This view uses methods in Python, but you can also use other mechanisms
+such as ``ViewPageTemplateFile``.
 
 Finally, we need to hook up the pages through ZCML::
 
@@ -297,9 +226,8 @@
     permission="zope2.ViewManagementScreens"
     />
 
-``browser`` in this refers to the XML namespace of Zope 3 for browser
-related things; it's
-``http://namespace.zope.org/browser``. ``permission`` declares the
+``browser`` in this refers to the XML namespace for browser related things;
+it's ``http://namespace.zope.org/browser``. ``permission`` declares the
 Zope 2 permission needs in order to access this view. The file
-``permissions.zcml`` in Five contains a mapping of Zope 2 permissions
-to their Zope 3 names.
+``permissions.zcml`` in AccessControl contains a mapping of Zope 2 permissions
+to their zope.security names.

Modified: Zope/trunk/src/Products/Five/fiveconfigure.py
===================================================================
--- Zope/trunk/src/Products/Five/fiveconfigure.py	2010-01-01 18:24:44 UTC (rev 107510)
+++ Zope/trunk/src/Products/Five/fiveconfigure.py	2010-01-01 18:53:56 UTC (rev 107511)
@@ -13,7 +13,7 @@
 ##############################################################################
 """Five-specific directive handlers
 
-These directives are specific to Five and have no equivalents in Zope 3.
+These directives are specific to Five and have no equivalents outside of it.
 
 $Id$
 """



More information about the Zope-Checkins mailing list