Merge "c-free" branch to trunk.

4 files changed, 139 insertions, 185 deletions

diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 8eb0ae978..81294e896 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -13,31 +13,26 @@ done primarily under Python 2.4.  :mod:`repoze.bfg` does *not* run
 under any version of Python before 2.4, and does *not* run under
 Python 3.X.
 
-.. warning:: To succesfully install :mod:`repoze.bfg`, you will need
-   an environment capable of compiling C code (e.g. ``XCode Tools``
-   will need to be installed if you're using MacOS X, and ``gcc`` and
-   other build tools will need to be installed if you're using other
-   UNIXlike systems).  See the system's documentation about installing
-   this software.  Additionally, the Python development libraries for
-   your Python version will need to be installed and the ``lixbml2``
-   and ``libxslt`` development libraries will need to be installed.
-   These requirements are often satisfied by installing the
-   ``python-devel``, ``libxml2-devel`` and ``libxslt-devel`` packages
-   into your system.  You will also need :term:`setuptools` installed
+.. note:: You will need :term:`setuptools` installed
    on within your Python system in order to run the ``easy_install``
    command.
 
-At the time of this writing, ``repoze.bfg`` will not install on
-Windows systems unless you have development tools (e.g. *Visual C++*)
-installed.
+.. note:: As of version 0.8.0, installation of :mod:`repoze.bfg` does
+   not require the compilation of any C code, so you do not need to
+   have development tools installed on the target machine.
 
-.. note:: If you'd like to help produce and maintain a version of
-   :mod:`repoze.bfg` that works on Windows, we'd love to hear from
-   you.  There's nothing intrinsic about :mod:`repoze.bfg` that would
-   prevent it from running on Windows, but none of the current
-   developers use the platform.  Please contact us via the `repoze.dev
-   maillist <http://lists.repoze.org/listinfo/repoze-dev>`_ if you'd
-   like to try to tackle the job of compilation and maintenance.
+Although BFG is known to run properly on all Unix-like systems, at the
+time of this writing, ``repoze.bfg`` is not tested on Windows systems.
+It might run; it might not.  There's nothing intrinsic about
+:mod:`repoze.bfg` that would prevent it from running on Windows, but
+none of the current developers use the platform.  Likewise for
+platforms like Jython, and Google App Engine; it may run, it may not.
+
+.. note:: If you'd like to help make sure :mod:`repoze.bfg` keeps
+.. running on your favorite alternate platform, we'd love to hear from
+   you.  Please contact us via the `repoze.dev maillist
+   <http://lists.repoze.org/listinfo/repoze-dev>`_ if you'd like to
+   contribute.
 
 Installing :mod:`repoze.bfg`
 ----------------------------
@@ -70,7 +65,7 @@ can usually install a setuptools package using your system's package
 manager.  If you cannot do this, or if you're using a self-installed
 version of Python, you will need to install setuptools "by hand".
 Installing setuptools "by hand" is always a reasonable thing to do,
-even if your package manager already has a prechewed version of
+even if your package manager already has a pre-chewed version of
 setuptools for installation.
 
 To install setuptools by hand, first download `ez_setup.py
@@ -146,46 +141,18 @@ virtualenv (``bfgenv``) directory:
    :mod:`repoze.bfg` cannot be installed from PyPI.
 
 This command will take longer than the previous ones to complete, as it
-compiles a number of dependencies.
+downloads and installs a number of dependencies.
 
 What Gets Installed
 ~~~~~~~~~~~~~~~~~~~
 
 When you ``easy_install`` :mod:`repoze.bfg`, various Zope libraries,
-WebOb, Paste, PasteScript, and PasteDeploy libraries are installed.
+various Chameleon libraries, WebOb, Paste, PasteScript, and
+PasteDeploy libraries are installed.
 
 Additionally, as shown in the next section, PasteScript (aka *paster*)
 templates will be registered that make it easy to start a new
 :mod:`repoze.bfg` project.
 
-Troubleshooting
----------------
-
-If ``lxml`` Fails to Compile During ``easy_install``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If the installation of :mod:`repoze.bfg` fails due to problems
-compiling ``lxml``, you should try installing ``lxml`` before
-installing :mod:`repoze.bfg`.  To do so, invoke ``easy_install``,
-instructing ``lxml`` to download its own copy of ``libxml2``::
-
-  $ STATIC_DEPS=true bin/easy_install lxml
-
-Once that completes, you can start a subsequent ``easy_install`` of
-:mod:`repoze.bfg` as per the instructions above; it should then work.
-
-If You Can't Install Via ``easy_install`` (Alternate Installation)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you can't get :mod:`repoze.bfg` installed using ``easy_install``
-because ``lxml`` fails to compile on your system, you can try the
-`repoze.bfg buildout
-<http://svn.repoze.org/buildouts/repoze.bfg/trunk/README.txt>`_.  This
-installation mechanism builds known-compatible ``libxml2`` and
-``libxslt`` from source and causes ``lxml`` to link against these
-instead of your system packages, as version incompatibilities between
-system packages and ``lxml`` versions are typically to blame for
-compilation problems.
-
 
 
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 83159dc45..072c6d8bf 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -147,90 +147,89 @@ It's Tested
 *If it ain't tested, it's broke.* We strive to test :mod:`repoze.bfg`
 completely.  Below a run of the ``nosetests`` command configured to
 show code coverage information (run against the :mod:`repoze.bfg`
-trunk just before the 0.6.8 release).
+trunk sometime before the 0.8.0 release).
 
 .. code-block:: bash
 
-   [chrism@vitaminf trunk]$ python setup.py nosetests
-   running nosetests
-   running egg_info
-   writing requirements to repoze.bfg.egg-info/requires.txt
-   writing repoze.bfg.egg-info/PKG-INFO
-   writing namespace_packages to repoze.bfg.egg-info/namespace_packages.txt
-   writing top-level names to repoze.bfg.egg-info/top_level.txt
-   writing dependency_links to repoze.bfg.egg-info/dependency_links.txt
-   writing entry points to repoze.bfg.egg-info/entry_points.txt
-   writing manifest file 'repoze.bfg.egg-info/SOURCES.txt'
-   running build_ext
-   ............................................................................
-   ............................................................................
-   ............................................................................
-   ............................................................................
-   ..........................................................................
-   Name                                     Stmts   Exec  Cover   Missing
-   ----------------------------------------------------------------------
-   repoze.bfg                                   1      1   100%   
-   repoze.bfg.chameleon_genshi                 44     44   100%   
-   repoze.bfg.chameleon_text                   48     48   100%   
-   repoze.bfg.chameleon_zpt                    44     44   100%   
-   repoze.bfg.events                           18     18   100%   
-   repoze.bfg.functional                       14     14   100%   
-   repoze.bfg.includes                          0      0   100%   
-   repoze.bfg.interfaces                       71     71   100%   
-   repoze.bfg.location                         42     42   100%   
-   repoze.bfg.log                               9      9   100%   
-   repoze.bfg.lru                              77     77   100%   
-   repoze.bfg.path                             12     12   100%   
-   repoze.bfg.push                             16     16   100%   
-   repoze.bfg.registry                         65     65   100%   
-   repoze.bfg.request                          16     16   100%   
-   repoze.bfg.router                          137    137   100%   
-   repoze.bfg.security                        150    150   100%   
-   repoze.bfg.settings                         24     24   100%   
-   repoze.bfg.template                         10     10   100%   
-   repoze.bfg.templating                       17     17   100%   
-   repoze.bfg.testing                         209    209   100%   
-   repoze.bfg.tests                             0      0   100%   
-   repoze.bfg.tests.fixtureapp                  0      0   100%   
-   repoze.bfg.tests.fixtureapp.models           3      3   100%   
-   repoze.bfg.tests.fixtureapp.views            4      4   100%   
-   repoze.bfg.tests.grokkedapp                  5      5   100%   
-   repoze.bfg.tests.routesapp                   0      0   100%   
-   repoze.bfg.tests.routesapp.models            3      3   100%   
-   repoze.bfg.tests.routesapp.views             4      4   100%   
-   repoze.bfg.tests.test_chameleon_genshi     157    157   100%   
-   repoze.bfg.tests.test_chameleon_text       172    172   100%   
-   repoze.bfg.tests.test_chameleon_zpt        161    161   100%   
-   repoze.bfg.tests.test_events                59     59   100%   
-   repoze.bfg.tests.test_integration          127    127   100%   
-   repoze.bfg.tests.test_location              83     83   100%   
-   repoze.bfg.tests.test_log                   11     11   100%   
-   repoze.bfg.tests.test_lru                   74     74   100%   
-   repoze.bfg.tests.test_push                  29     29   100%   
-   repoze.bfg.tests.test_registry             112    112   100%   
-   repoze.bfg.tests.test_router               668    668   100%   
-   repoze.bfg.tests.test_security             464    464   100%   
-   repoze.bfg.tests.test_settings              83     83   100%   
-   repoze.bfg.tests.test_template              73     73   100%   
-   repoze.bfg.tests.test_templating            45     45   100%   
-   repoze.bfg.tests.test_testing              375    375   100%   
-   repoze.bfg.tests.test_traversal            579    579   100%   
-   repoze.bfg.tests.test_url                   95     95   100%   
-   repoze.bfg.tests.test_urldispatch          298    298   100%   
-   repoze.bfg.tests.test_view                 418    418   100%   
-   repoze.bfg.tests.test_wsgi                  75     75   100%   
-   repoze.bfg.tests.test_xslt                 191    191   100%   
-   repoze.bfg.tests.test_zcml                 608    608   100%   
-   repoze.bfg.traversal                       167    167   100%   
-   repoze.bfg.url                              35     35   100%   
-   repoze.bfg.urldispatch                     146    146   100%   
-   repoze.bfg.view                             76     76   100%   
-   repoze.bfg.wsgi                             23     23   100%   
-   repoze.bfg.xslt                             57     57   100%   
-   repoze.bfg.zcml                            246    244    99%   168-169
-   ----------------------------------------------------------------------
-   TOTAL                                     6750   6748    99%   
-   ----------------------------------------------------------------------
-   Ran 378 tests in 10.784s
-
-   OK
+    [chrism@vitaminf c-less]$ env/bin/python setup.py nosetests
+    running nosetests
+    running egg_info
+    writing requirements to repoze.bfg.egg-info/requires.txt
+    writing repoze.bfg.egg-info/PKG-INFO
+    writing namespace_packages to repoze.bfg.egg-info/namespace_packages.txt
+    writing top-level names to repoze.bfg.egg-info/top_level.txt
+    writing dependency_links to repoze.bfg.egg-info/dependency_links.txt
+    writing entry points to repoze.bfg.egg-info/entry_points.txt
+    writing manifest file 'repoze.bfg.egg-info/SOURCES.txt'
+    running build_ext
+    ...........................................................................
+    ...........................................................................
+    ...........................................................................
+    ...........................................................................
+    ...........................................................................
+    .........
+    Name                                   Stmts   Exec  Cover   Missing
+    --------------------------------------------------------------------
+    repoze.bfg                                 0      0   100%   
+    repoze.bfg.chameleon_text                 48     48   100%   
+    repoze.bfg.chameleon_zpt                  44     44   100%   
+    repoze.bfg.events                         18     18   100%   
+    repoze.bfg.functional                     14     14   100%   
+    repoze.bfg.includes                        0      0   100%   
+    repoze.bfg.interfaces                     67     67   100%   
+    repoze.bfg.location                       42     42   100%   
+    repoze.bfg.log                             9      9   100%   
+    repoze.bfg.lru                            75     75   100%   
+    repoze.bfg.path                           12     12   100%   
+    repoze.bfg.push                           14     14   100%   
+    repoze.bfg.registry                       65     65   100%   
+    repoze.bfg.request                        25     25   100%   
+    repoze.bfg.router                        154    154   100%   
+    repoze.bfg.security                      150    150   100%   
+    repoze.bfg.settings                       24     24   100%   
+    repoze.bfg.template                        6      6   100%   
+    repoze.bfg.templating                     17     17   100%   
+    repoze.bfg.testing                       213    213   100%   
+    repoze.bfg.tests                           0      0   100%   
+    repoze.bfg.tests.fixtureapp                0      0   100%   
+    repoze.bfg.tests.fixtureapp.models         3      3   100%   
+    repoze.bfg.tests.fixtureapp.views          4      4   100%   
+    repoze.bfg.tests.grokkedapp                5      5   100%   
+    repoze.bfg.tests.routesapp                 0      0   100%   
+    repoze.bfg.tests.routesapp.models          3      3   100%   
+    repoze.bfg.tests.routesapp.views           4      4   100%   
+    repoze.bfg.tests.test_chameleon_text     172    172   100%   
+    repoze.bfg.tests.test_chameleon_zpt      161    161   100%   
+    repoze.bfg.tests.test_events              59     59   100%   
+    repoze.bfg.tests.test_integration        127    127   100%   
+    repoze.bfg.tests.test_location            83     83   100%   
+    repoze.bfg.tests.test_log                 11     11   100%   
+    repoze.bfg.tests.test_lru                 74     74   100%   
+    repoze.bfg.tests.test_push                29     29   100%   
+    repoze.bfg.tests.test_registry           112    112   100%   
+    repoze.bfg.tests.test_request             31     31   100%   
+    repoze.bfg.tests.test_router             697    697   100%   
+    repoze.bfg.tests.test_security           464    464   100%   
+    repoze.bfg.tests.test_settings            83     83   100%   
+    repoze.bfg.tests.test_template            73     73   100%   
+    repoze.bfg.tests.test_templating          45     45   100%   
+    repoze.bfg.tests.test_testing            379    379   100%   
+    repoze.bfg.tests.test_traversal          616    616   100%   
+    repoze.bfg.tests.test_url                126    126   100%   
+    repoze.bfg.tests.test_urldispatch        338    338   100%   
+    repoze.bfg.tests.test_view               418    418   100%   
+    repoze.bfg.tests.test_wsgi               164    164   100%   
+    repoze.bfg.tests.test_zcml               620    620   100%   
+    repoze.bfg.traversal                     215    215   100%   
+    repoze.bfg.url                            43     43   100%   
+    repoze.bfg.urldispatch                   157    157   100%   
+    repoze.bfg.view                           76     76   100%   
+    repoze.bfg.wsgi                           43     43   100%   
+    repoze.bfg.zcml                          246    246   100%   
+    --------------------------------------------------------------------
+    TOTAL                                   6678   6678   100%   
+    ----------------------------------------------------------------------
+    Ran 384 tests in 10.025s
+
+    OK
+
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index d18cfb7fd..66ce467f9 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -342,8 +342,8 @@ 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:`Chameleon` and XSLT template
-changes will not require an application restart to be detected.  See
+If it exists, and is ``true``, :term:`Chameleon` template changes will
+not require an application restart to be detected.  See
 :ref:`reload_templates_section` for more information.
 
 .. warning:: The ``reload_templates`` option should be turned off for
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index f1839cfed..985e1e237 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -17,14 +17,21 @@ complies largely with the `Zope Page Template
 <http://wiki.zope.org/ZPT/FrontPage>`_ template specification and is
 significantly faster.
 
-.. 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`.
+.. note:: The language definition documentation for Chameleon
+   ZPT-style templates is available from `the Chameleon website
+   <http://chameleon.repoze.org>`_.
+
+.. note:: As of version 0.8.0, :mod:`repoze.bfg` no longer supports
+   XSL templates "out of the box".  The :mod:`repoze.bfg.xslt` package
+   is an add-on which provides XSL template bindings.
+
+.. note:: As of version 0.8.0, :mod:`repoze.bfg` no longer supports
+   Genshi-style Chameleon bindings "out of the box".  The
+   :mod:`repoze.bfg.chameleon_genshi` package is an add-on which
+   provides Chameleon Genshi-style template support.
+
+.. note:: Jinja2 template bindings are available for :mod:`repoze.bfg`
+   in the :mod:`repoze.bfg.jinja2` package.
 
 Given that there is a :term:`chameleon.zpt` template named
 ``foo.pt`` in a directory in your application named ``templates``,
@@ -118,50 +125,13 @@ And ``templates/mytemplate.pt`` might look like so:
     <html xmlns="http://www.w3.org/1999/xhtml" 
           xmlns:tal="http://xml.zope.org/namespaces/tal"
           xmlns:metal="http://xml.zope.org/namespaces/metal">
-       <span tal:use-macro="main['hello']">
+       <span tal:use-macro="main.macros['hello']">
           <span metal:use-macro="name">
              <span metal:fill-slot="name">Chris</span>
           </span>
        </span>
     </html>
 
-
-Templating with XSLT
-------------------------
-
-:mod:`repoze.bfg` also supports XSLT as an optional templating
-language.  Like ZPT, an XSLT template is loaded once and re-used
-between requests.
-
-Given a template ``foo.xsl`` in the templates directory, you can render
-an XSLT as follows:
-
-.. code-block:: python
-   :linenos:
-
-   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)
-
-As shown, the second argument to ``render_transform_to_response`` is
-the element (and children) that you want as the top of the data for
-the XSLT.
-
-You can also pass XSLT parameters in as keyword arguments:
-
-.. code-block:: python
-   :linenos:
-
-   from repoze.bfg.xslt import render_transform_to_response
-   from lxml import etree
-   node = etree.Element("root")
-   value1 = "'app1'"
-   return render_transform_to_response('templates/foo.xsl', node, param1=value1)
-
-This would then assign 'app1' as the value of an ``<xsl:param
-name="param1"/>`` parameter in the XSLT template.
-
 .. _reload_templates_section:
 
 Automatically Reloading Templates
@@ -241,3 +211,21 @@ installed, here's an example of using Mako from within a
 Note that if you use third-party templating languages, the
 auto-template-reload strategy explained in
 :ref:`reload_templates_section` will not be available.
+
+Available Add-On Template System Bindings
+-----------------------------------------
+
+:mod:`repoze.bfg.xslt` is an add-on which provides XSL template
+bindings.  It lives in the Repoze Subversion repository at
+`http://svn.repoze.org/repoze.bfg.xslt
+<http://svn.repoze.org/repoze.bfg.xslt>`_.
+
+:mod:`repoze.bfg.chameleon_genshi` package is an add-on which provides
+Chameleon Genshi-style template support.  It lives in the Repoze
+Subversion repository at `http://svn.repoze.org/repoze.bfg.chameleon_genshi
+<http://svn.repoze.org/repoze.bfg.chameleon_genshi>`_.
+
+Jinja2 template bindings are available for :mod:`repoze.bfg` in the
+:mod:`repoze.bfg.jinja2` package.  It lives in the Repoze Subversion
+repository at `http://svn.repoze.org/repoze.bfg.jinja2
+<http://svn.repoze.org/repoze.bfg.jinja2>`_.