Fix up templates chapter.

2 files changed, 58 insertions, 21 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index a3c377f49..4e88b51d2 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -169,11 +169,20 @@ Glossary
     for transforming XML documents into other XML documents.
   z3c.pt
     `z3c.pt <http://pypi.python.org/pypi/z3c.pt>`_ is an
-    implementation of the `Zope Page Template
-    <http://wiki.zope.org/ZPT/FrontPage>`_ templating language 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.
+    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.
+  ZPT
+    The `Zope Page Template <http://wiki.zope.org/ZPT/FrontPage>`_
+    templating language.
+  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.
   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/templates.rst b/docs/narr/templates.rst
index 9ead3789f..16ab27473 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -1,24 +1,25 @@
 Templates
 =========
 
-A :term:`template` is a file on disk which can be used to render data
-provided by a :term:`view`.
-
-Default Templating With z3c.pt Page Templates
-------------------------------------------------
-
-Like Zope, :mod:`repoze.bfg` uses Zope Page Templates (ZPT) as its
-default templating language. However, :mod:`repoze.bfg` uses a
-different implementation of the ZPT specification: the :term:`z3c.pt`
-templating engine. This templating engine complies with the `Zope Page
-Template <http://wiki.zope.org/ZPT/FrontPage>`_ template
-specification. While :term:`z3c.pt` doesn't implement the *METAL*
-specification (feature or drawback, depending on your viewpoint), it
+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
+---------------------------------------------------
+
+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
+complies with the `Zope Page Template
+<http://wiki.zope.org/ZPT/FrontPage>`_ template specification. While
+:term:`z3c.pt` doesn't implement the :term:`METAL` specification, it
 is significantly faster.
 
-Given that there is a template named ``foo.html`` in a directory in
-your application named ``templates``, you can render the template from
-a view like so:
+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:
 
 .. code-block:: python
    :linenos:
@@ -93,3 +94,30 @@ You can also pass XSLT parameters in as keyword arguments:
 
 This would then assign 'app1' as the value of an ``<xsl:param
 name="param1"/>`` parameter in the XSLT template.
+
+Templating with other Templating Languages
+------------------------------------------
+
+Because :term:`view` functions are typically the only code in
+:mod:`repoze.bfg` that need to know anything about templates, and
+because view functions are very simple Python, you can use whatever
+templating system you're most comfortable with within
+:mod:`repoze.bfg`.  Install the templating system, import its API
+functions into your views module, use those APIs to generate a string,
+then return that string as the body of a :term:`WebOb` ``Response``
+object.  Assuming you have `Mako <http://www.makotemplates.org/>`_
+installed, here's an example of using Mako from within a
+:mod:`repoze.bfg` :term:`view`:
+
+.. code-block:: python
+   :linenos:
+
+   from mako.template import Template
+   from webob import Response
+
+   def make_view(context, request):
+       template = Template(filename='/templates/template.mak')
+       result = template.render(name=context.name)
+       response = Response(result)
+       return response
+