Move to Chameleon.

9 files changed, 144 insertions, 62 deletions

diff --git a/docs/api/template.rst b/docs/api/template.rst
index 64e25a37c..8cf63c91b 100644
--- a/docs/api/template.rst
+++ b/docs/api/template.rst
@@ -1,9 +1,56 @@
 .. _template_module:
 
-:mod:`repoze.bfg.template`
---------------------------
+:mod:`repoze.bfg` Built-in Templating Facilties
+===============================================
 
-.. automodule:: repoze.bfg.template
+Three templating facilities are provided by :mod:`repoze.bfg` "out of
+the box": :term:`ZPT` -style, :term:`Genshi` -style, and :term:`XSLT`
+templating.
+
+ZPT-style and Genshi-style templates are in :mod:`repoze.bfg` are
+supported by the :term:`Chameleon` (nee :term:`z3c.pt`) templating
+engine, which contains alternate implementations of both the ZPT and
+Genshi language specifications.
+
+XSLT templating is supported by the use of :term:`lxml`.
+
+Below is API documentation for each of those facilities.  Each
+facility is similar to the other, but to use a particular facility,
+you must import the API function from a specific module.  For
+instance, to render a ZPT-style template to a response, you would
+import the ``render_template_to_response`` function from
+``repoze.bfg.chameleon_zpt`` while you would import
+``render_template_to_response`` from ``repoze.bfg.chameleon_genshi``
+in order to render a Genshi-style template to a response.  While these
+functions have the same name, each will only operate on template files
+that match the style in which the template file itself is written.  If
+you need to import API functions from two templating facilities within
+the same module, use the ``as`` feature of the Python import
+statement, e.g.:
+
+.. code-block:: python
+
+  from repoze.chameleon_zpt import render_template as zpt_render
+  from repoze.chameleon_genshi import render_template as genshi_render
+
+:mod:`repoze.bfg.chameleon_zpt`
+-------------------------------
+
+.. automodule:: repoze.bfg.chameleon_zpt
+
+  .. autofunction:: get_template
+
+  .. autofunction:: render_template
+
+  .. autofunction:: render_template_to_response
+
+.. note:: For backwards compatibility purposes, these functions may
+          also be imported from ``repoze.bfg.template``.
+
+:mod:`repoze.bfg.chameleon_genshi`
+----------------------------------
+
+.. automodule:: repoze.bfg.chameleon_genshi
 
   .. autofunction:: get_template
 
@@ -11,7 +58,17 @@
 
   .. autofunction:: render_template_to_response
 
+:mod:`repoze.bfg.xslt`
+----------------------
+
+.. automodule:: repoze.bfg.xslt
+
+  .. autofunction:: get_transform
+
   .. autofunction:: render_transform
 
   .. autofunction:: render_transform_to_response
 
+.. note:: For backwards compatibility purposes, these functions may
+          also be imported from ``repoze.bfg.template``.
+
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 51eb8c2fa..6d335ec51 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -199,22 +199,36 @@ Glossary
   XSLT
     `XSL Transformations <http://www.w3.org/TR/xslt>`_.  A language
     for transforming XML documents into other XML documents.
+  Chameleon
+    `chameleon <http://pypi.python.org/pypi/chameleon.core>`_ is an
+    attribute language template compiler which supports both the
+    :term:`ZPT` and :term:`Genshi` templating specifications.  It is
+    written and maintained by Malthe Borch.  It has serveral
+    extensions, such as the ability to use bracketed (Genshi-style)
+    ``${name}`` syntax, even within ZPT.  It is also much faster than
+    the reference implementations of both ZPT and Genshi.
+    :mod:`repoze.bfg` offers Chameleon templating out of the box in
+    both ZPT and Genshi "flavors".
+  chameleon.zpt
+    ``chameleon.zpt`` is the package which provides :term:`ZPT`
+    templating support under the :term:`Chameleon` templating engine.
+  chameleon.genshi
+    ``chameleon.genshi`` is the package which provides :term:`Genshi`
+    templating support under the :term:`Chameleon` templating engine.
   z3c.pt
-    `z3c.pt <http://pypi.python.org/pypi/z3c.pt>`_ is an
-    implementation of :term:`ZPT` by Malthe Borch.  It has serveral
-    extensions, such as the ability to use bracketed- ``${name}``
-    syntax.  It is also much faster than the reference implementation
-    of ZPT.  :mod:`repoze.bfg` offers z3c.pt templating out of the
-    box.
+    This was the previous name for :term:`Chameleon`, and is now a
+    Zope 3 compatibility package for Chameleon.
   ZPT
     The `Zope Page Template <http://wiki.zope.org/ZPT/FrontPage>`_
     templating language.
+  Genshi
+    `Genshi <http://genshi.edgewall.org/>`_ is an attribute-based XML
+    templating language similar to ZPT.  Its syntax is supported
+    within :mod:`repoze.bfg` via :term:`Chameleon`.
   METAL
     `Macro Expansion for TAL <http://wiki.zope.org/ZPT/METAL>`_, a
     part of :term:`ZPT` which makes it possible to share common look
-    and feel between templates.  :term:`z3c.pt`, the implementation of
-    ZPT that :mod:`repoze.bfg` ships with does not implement the METAL
-    specification.
+    and feel between templates.  
   Routes
     A `system by Ben Bangert <http://routes.groovie.org/>`_ which
     parses URLs and compares them against a number of user defined
diff --git a/docs/narr/MyProject/myproject/views.py b/docs/narr/MyProject/myproject/views.py
index 6e1be6190..67dbd00b6 100644
--- a/docs/narr/MyProject/myproject/views.py
+++ b/docs/narr/MyProject/myproject/views.py
@@ -1,4 +1,4 @@
-from repoze.bfg.template import render_template_to_response
+from repoze.bfg.chameleon_zpt import render_template_to_response
 
 def my_view(context, request):
     return render_template_to_response('templates/mytemplate.pt',
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 7360053dd..3bca363e8 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -299,7 +299,7 @@ your application by requiring more settings in this section.
 
 The ``reload_templates`` setting in the ``[app:main]`` section is a
 :mod:`repoze.bfg`-specific setting which is passed into the framework.
-If it exists, and is ``true``, :term:`z3c.pt` and XSLT template
+If it exists, and is ``true``, :term:`Chameleon` and XSLT template
 changes will not require an application restart to be detected.
 
 .. warning:: The ``reload_templates`` option should be turned off for
@@ -418,8 +418,8 @@ The ``myproject`` :term:`package` lives inside the ``MyProject``
 #. A ``run.py`` module, which contains code that helps users run the
    application.
 
-#. A ``templates`` directory, which is full of :term:`z3c.pt` and/or
-   :term:`XSLT` templates.
+#. A ``templates`` directory, which contains :term:`Chameleon` (or
+   other types of) templates.
 
 #. A ``tests.py`` module, which contains unit test code for the
    application.
@@ -485,16 +485,17 @@ in the model, and the HTML given back to the browser.
    dispatch`).  The *request* is an instance of the :term:`WebOb`
    ``Request`` class representing the browser's request to our server.
 
-#. The view renders a :term:`template` and returns the result as the
-   :term:`response`.  Note that because our ``MyProject.ini`` has a
-   ``reload_templates = true`` directive indicating that templates
-   should be reloaded when they change, you won't need to restart the
-   application server to see changes you make to templates.  During
-   development, this is handy.  If this directive had been ``false``
-   (or if the directive did not exist), you would need to restart the
-   application server for each template change.  For production
-   applications, you should set your project's ``reload_templates`` to
-   ``false`` to increase the speed at which templates may be rendered.
+#. The view renders a :term:`Chameleon` template and returns the
+   result as the :term:`response`.  Note that because our
+   ``MyProject.ini`` has a ``reload_templates = true`` directive
+   indicating that templates should be reloaded when they change, you
+   won't need to restart the application server to see changes you
+   make to templates.  During development, this is handy.  If this
+   directive had been ``false`` (or if the directive did not exist),
+   you would need to restart the application server for each template
+   change.  For production applications, you should set your project's
+   ``reload_templates`` to ``false`` to increase the speed at which
+   templates may be rendered.
 
 .. note::
 
@@ -569,16 +570,15 @@ without the PasteDeploy configuration file:
 ``templates/mytemplate.pt``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The single :term:`template` in the project looks like so:
+The single :term:`Chameleon` template in the project looks like so:
 
 .. literalinclude:: MyProject/myproject/templates/mytemplate.pt
    :linenos:
    :language: xml
 
-This is a :term:`z3c.pt` template.  It displays the current project
-name when it is rendered.  It is referenced by the ``my_view``
-function in the ``views.py`` module.  Templates are accessed and used
-by view functions.
+It displays the current project name when it is rendered.  It is
+referenced by the ``my_view`` function in the ``views.py`` module.
+Templates are accessed and used by view functions.
 
 ``tests.py``
 ~~~~~~~~~~~~
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 80b530a8c..dce66ae3d 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -5,25 +5,35 @@ A :term:`template` is a usually file on disk which can be used to
 render data provided by a :term:`view`, surrounded by more static
 information.
 
-Templating With :term:`z3c.pt` (ZPT) Page Templates
----------------------------------------------------
+Templating With :term:`Chameleon` (:term:`chameleon.zpt`) Page Templates
+------------------------------------------------------------------------
 
 Like Zope, :mod:`repoze.bfg` uses Zope Page Templates (:term:`ZPT`) as
-its default templating language. However, :mod:`repoze.bfg` uses a
-different implementation of the :term:`ZPT` specification than Zope
-does: the :term:`z3c.pt` templating engine. This templating engine
+its default and best-supported templating language. However,
+:mod:`repoze.bfg` uses a different implementation of the :term:`ZPT`
+specification than Zope does: the :term:`Chameleon`
+:term:`chameleon.zpt` templating engine. This templating engine
 complies with the `Zope Page Template
 <http://wiki.zope.org/ZPT/FrontPage>`_ template specification and is
 significantly faster.
 
-Given that there is a :term:`z3c.pt` template named ``foo.html`` in a
-directory in your application named ``templates``, you can render the
-template from a view like so:
+.. note:: :mod:`repoze.bfg` can also allow for the use of Genshi-style
+   templates via the ``chameleon.genshi`` package, support for which
+   is built-in to :mod:`repoze.bfg`.  The :mod:`repoze.bfg` API
+   functions for getting and rendering Chameleon Genshi-style
+   templates mirrors the Chameleon ZPT-style API completely; only the
+   template files themselves must differ.  See :ref:`template_module`
+   for more information about using Genshi-style templates within
+   :mod:`repoze.bfg`.
+
+Given that there is a :term:`chameleon.zpt` template named
+``foo.html`` in a directory in your application named ``templates``,
+you can render the template from a view like so:
 
 .. code-block:: python
    :linenos:
 
-   from repoze.bfg.template import render_template_to_response
+   from repoze.bfg.chameleon_zpt import render_template_to_response
    def sample_view(context, request):
        return render_template_to_response('templates/foo.html', foo=1, bar=2)
 
@@ -35,18 +45,18 @@ Relative to the directory in which the ``views.py`` file which names
 it lives, which is usually the :mod:`repoze.bfg` application's
 :term:`package` directory.
 
-``render_template_to_response`` always renders a :term:`z3c.pt`
+``render_template_to_response`` always renders a :term:`chameleon.zpt`
 template, and always returns a Response object which has a *status
 code* of ``200 OK`` and a *content-type* of ``text-html``.  If you
 need more control over the status code and content-type, use the
-``render_template`` function instead, which also renders a z3c.pt
-template but returns a string instead of a Response.  You can use
-the string manually as a response body:
+``render_template`` function instead, which also renders a ZPT
+template but returns a string instead of a Response.  You can use the
+string manually as a response body:
 
 .. code-block:: python
    :linenos:
 
-   from repoze.bfg.template import render_template
+   from repoze.bfg.chameleon_zpt import render_template
    from webob import Response
    def sample_view(context, request):
        result = render_template('templates/foo.html', foo=1, bar=2)
@@ -71,7 +81,7 @@ an XSLT as follows:
 .. code-block:: python
    :linenos:
 
-   from repoze.bfg.template import render_transform_to_response
+   from repoze.bfg.xslt import render_transform_to_response
    from lxml import etree
    node = etree.Element("root")  
    return render_transform_to_response('templates/foo.xsl', node)
@@ -85,7 +95,7 @@ You can also pass XSLT parameters in as keyword arguments:
 .. code-block:: python
    :linenos:
 
-   from repoze.bfg.template import render_transform_to_response
+   from repoze.bfg.xslt import render_transform_to_response
    from lxml import etree
    node = etree.Element("root")
    value1 = "'app1'"
diff --git a/docs/tutorials/cmf/skins.rst b/docs/tutorials/cmf/skins.rst
index 2e444c4db..cbc28bfb5 100644
--- a/docs/tutorials/cmf/skins.rst
+++ b/docs/tutorials/cmf/skins.rst
@@ -14,9 +14,9 @@ particular skin to provide the site with additional features.
 :mod:`repoze.bfg` itself has no such concept, and no package provides
 a direct replacement, but bfg :term:`view` code combined with
 differing :term:`request type` attributes can provide a good deal of
-the same sort of behavior.  The `vudo.bfg <http://docs.vudo.me/>`_
-package is an attempt to allow directories on disk to represent
-collections of templates, each of which can be thought of as a minimal
-skin.
+the same sort of behavior.  The `repoze.skins
+<http://svn.repoze.org/repoze.skins/>`_ package is an attempt to allow
+directories on disk to represent collections of templates, each of
+which can be thought of as a minimal skin.
 
 
diff --git a/docs/tutorials/lxmlgraph/step03.rst b/docs/tutorials/lxmlgraph/step03.rst
index 9edc77af3..0f54f8761 100644
--- a/docs/tutorials/lxmlgraph/step03.rst
+++ b/docs/tutorials/lxmlgraph/step03.rst
@@ -52,7 +52,7 @@ Also add a function in ``views.py`` that looks like the following:
 .. code-block:: python
    :linenos:
 
-   from repoze.bfg.template import render_template_to_response
+   from repoze.bfg.chameleon_zpt import render_template_to_response
    def zpt_view(context, request):
       return render_template_to_response('templates/default.pt', 
                                          name=context.__name__, 
@@ -61,8 +61,8 @@ Also add a function in ``views.py`` that looks like the following:
 This function is relatively simple:
 
 #. Line 1 imports a :mod:`repoze.bfg` function that renders ZPT
-   templates to a response.  :mod:`repoze.bfg` uses the ``z3c.pt`` ZPT
-   engine.
+   templates to a response.  :mod:`repoze.bfg` uses the
+   :term:`chameleon.zpt` ZPT engine.
 
 #. Line 2, like our other view functions, gets passed a ``context``
    (the current hop in the URL) and WebOb ``request`` object.
@@ -92,10 +92,11 @@ Life is better with templating:
    ``render_template_to_response``.
 
 #. Line 6 looks interesting.  It uses the ``node`` that we passed in
-   via ``render_template_to_response``.  Since ``z3c.pt`` uses Python
-   as its expession language, we can put anything Python-legal between
-   the braces.  And since ``node`` is an ``lxml`` ``Element`` object,
-   we just ask for its ``.tag``, like regular Python ``lxml`` code.
+   via ``render_template_to_response``.  Since :term:`chameleon.zpt`
+   uses Python as its expession language, we can put anything
+   Python-legal between the braces.  And since ``node`` is an ``lxml``
+   ``Element`` object, we just ask for its ``.tag``, like regular
+   Python ``lxml`` code.
 
 Viewing the ZPT
 ------------------
@@ -119,7 +120,7 @@ model using the ZPT templating language.
 
 
 XSLT Templates
-====================
+==============
 
 So that's the ZPT way of rendering HTML for an XML document.  We can
 additonally use XSLT to do templating.  How might XSLT look?
diff --git a/docs/tutorials/lxmlgraph/step03/myapp/views.py b/docs/tutorials/lxmlgraph/step03/myapp/views.py
index 0ac33ba83..6eb4e376c 100644
--- a/docs/tutorials/lxmlgraph/step03/myapp/views.py
+++ b/docs/tutorials/lxmlgraph/step03/myapp/views.py
@@ -1,5 +1,5 @@
-from repoze.bfg.template import render_template_to_response
-from repoze.bfg.template import render_transform_to_response
+from repoze.bfg.chameleon_zpt import render_template_to_response
+from repoze.bfg.chameleon_zpt import render_transform_to_response
 
 def zpt_view(context, request):
     return render_template_to_response("templates/default.pt", 
diff --git a/docs/tutorials/lxmlgraph/step04/myapp/views.py b/docs/tutorials/lxmlgraph/step04/myapp/views.py
index fd8650e14..f079cea8c 100644
--- a/docs/tutorials/lxmlgraph/step04/myapp/views.py
+++ b/docs/tutorials/lxmlgraph/step04/myapp/views.py
@@ -1,4 +1,4 @@
-from repoze.bfg.template import render_transform_to_response
+from repoze.bfg.xslt import render_transform_to_response
 
 # Some constants
 XML_NAMESPACE='http://www.w3.org/XML/1998/namespace'