first cut at Z3 support docs

doc/ZOPE3.txt

+Using Zope 3 Components in Zope 2 Applications
+
+  Background
+
+    Zope 3 is next major revision of Zope. It is designed to be more 
+    'programmer-centric' and easier to learn, use and extend. Zope 3 
+    introduces an interface-centric component architecture that makes 
+    it easier to develop and deploy components without requiring 
+    developers to learn and understand the entire Zope framework.
+
+    Much more information on Zope 3 is available on the Zope 3 area 
+    of the zope.org Website at http://dev.zope.org/Zope3/.
+
+    As of Zope 2.8, the "Five" project has been integrated into the 
+    Zope 2 core. The "Five" project implements a compatibily layer 
+    that allows many Zope 3 components and patterns to be used in 
+    new and existing Zope 2 applications. This provides a number of 
+    benefits::
+
+      - availability of Zope 3 technologies in Zope 2 like the 
+        component architecture and declarative configuration
+
+      - you can gradually evolve your Zope 2 projects to better plan 
+        for 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 ;)
+
+
+  Features
+
+    The Five integration layer provides support for Zope 3 interfaces, 
+    Zope Configuration Markup Language (ZCML), adapters, views, 
+    utilities, schema-driven content, and Zope 3 add and edit forms.
+
+    Note that the Five layer does *not* attempt provide a ZMI user 
+    interface for Zope 3 components.
+
+    Zope 2.8+ includes the essential Zope 3 packages, so it is not 
+    necessary to install Zope 3.
+
+
+  Zope 3 Interfaces
+
+    Everything in the zope.interface package should work. Zope 3 interfaces 
+    are the foundation of the component architecture, and also the foundation 
+    of schemas.
+
+    Historically, 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
+    work with 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 - you're usually better off 
+    just switching to ``implements()`` for your application possible.
+
+    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()``.
+
+    You will also have to change any calls to ``isImplementedBy`` and such 
+    in your application to ``providedBy``, as ``isImplementedBy`` has been 
+    deprecated (you'll see the DeprecationWarnings in your Zope log).
+
+
+  ZCML
+
+    ZCML is the Zope Configuration Markup Language, an XML application. 
+    Zope 3 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 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 Zope 2 with Five has a special directive, 'five:loadProducts', 
+    to load the ZCML ('meta.zcml', 'configure.zcml') of all installed 
+    Zope 2 products, if available.
+
+    Another special directive, 'five:loadProductsOverrides' is available to 
+    load any overriding ZCML (overrides.zcml) in these products. In the 
+    'overrides.zcml' you can override existing views or adapters, in this 
+    or in other products.
+
+    The Five integration layer tries to use the Zope 3 ZCML directives where 
+    possible, though it does sometimes support only a subset of the possible 
+    attributes. It also introduces a few directives of its own under the 
+    ``five`` namespace. The supported directives are listed per namespace 
+    in alphabetic order below.
+
+    zope ``http://namespaces.zope.org/zope``
+    ========================================
+
+    adapter
+    -------
+    
+    Hook an adapter factory to an interface.
+    
+    content
+    -------
+
+    Declare interface and permissions on content object. Declares Zope 2
+    permissions.
+
+    permission
+    ----------
+
+    Way to make Zope 2 permissions available to Five, ``title`` is
+    permission name.
+
+    redefinePermission
+    ------------------
+
+    Redefine a permission in included ZCML as another one.
+
+    service
+    -------
+
+    Declare a global service
+
+    serviceType
+    -----------
+
+    Declare a type of service.
+    
+    skin
+    ----
+
+    Declare a skin, consisting of layers.
+
+    utility
+    -------
+
+    Declare a global utility.
+
+    browser ``http://namespaces.zope.org/browser``
+    ==============================================
+
+    page
+    ----
+
+    Declare a page view for an interface. Permission is a Zope 2
+    permission.
+
+    pages
+    -----
+
+    Declare multiple page views for an interface. Permissions are Zope 2
+    permissions.
+
+    defaultView
+    -----------
+
+    Declare the name of the view that should be used for the default when 
+    viewing the object; i.e. when the object is traversed to without a view.
+
+    defaultSkin
+    -----------
+
+    Declare the default skin used.
+
+    interface
+    ---------
+    Define an interface in ZCML.
+
+    layer
+    -----
+
+    Declare a layer.
+
+    menu
+    ----
+
+    Declare a menu
+
+    menuItem, menuItems
+    -------------------
+
+    Declare menuItems
+
+    five ``http://namespaces.zope.org/five``
+    ========================================
+
+    implements
+    ----------
+
+    Make a class declare it implements an interface.
+
+    loadProducts
+    ------------
+
+    Loads ZCML in all Zope 2 products. First processes all ``meta.zcml``
+    files, then processes all ``configure.zcml`` files.
+
+    loadProductsOverrides
+    ---------------------
+
+    Loads overriding ZCML in all products (``overrides.zcml``).
+
+    traversable
+    -----------
+
+    Make a Zope 2 content class traversable in the Zope 3 manner using
+    Five. This is used to attached views, resources and other things to
+    Zope 2 objects.
+
+    defaultViewable
+    ---------------
+
+    Make a Zope 2 content class use a Zope 3 default view when looking at
+    it without any paths appended to it. This works then instead of
+    ``index_html`` in Zope 2.
+
+    pagesFromDirectory
+    ------------------
+
+    Load all *.pt files in a directory as pages. Useful when you want to
+    share templates between Five and CMF, so you can declare pages like
+    this is a similar way to setting up skin folders in portal_skins.
+
+    browser:editform
+    ----------------
+
+    Create an edit form based on a schema.
+
+    browser:addform
+    ---------------
+
+    Create an add form based on a schema.
+
+
+  Adapters
+
+    Generally, adapters can now be used in Zope 2 just as they are used in 
+    Zope 3.
+
+
+  Zope 3 Views
+
+    Zope 3 views work in Zope 2 with Five, including layers and skins. To 
+    make them work however, you need to make a Zope 2 class "traversable". 
+    This can be done by using the 'five:traversable' directive in ZCML.
+
+
+  Schemas and Forms
+
+    With the Five layer, it is possible to use schema-based content using 
+    the standard Zope 3 patterns.
+  
+
+  Security declarations
+
+    Five aims to eradicate declareProtected, ClassSecurityInfo and 
+    initializeClass from your Zope 2 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.
+
+    The content directive can also be used to declare permissions on Zope 2 
+    content classes. Note however that these permissions will be ignored by 
+    views anyway, as they are trusted -- it only serves to protect directly 
+    exposed methods on content classes (the python scripts and the ZPublisher).