3 files changed, 63 insertions, 11 deletions
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 7320f5b4c..c9d37101d 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -815,3 +815,7 @@ Glossary
       ``request`` (a :term:`request` object), returns a
       :term:`session` object.
 
+   Mako
+     `Mako <http://www.makotemplates.org/>`_ is a template language language
+     which refines the familiar ideas of componentized layout and inheritance
+     using Python with Python scoping and calling semantics.
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 57d1bc3b9..736e6a185 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -8,10 +8,9 @@ dynamic data provided by a :term:`view`.  :mod:`pyramid` offers a
 number of ways to perform templating tasks out of the box, and
 provides add-on templating support through a set of bindings packages.
 
-Out of the box, :mod:`pyramid` provides templating via the
-:term:`Chameleon` templating library.  :term:`Chameleon` provides
-support for two different types of templates: :term:`ZPT` templates
-and text templates.
+Out of the box, :mod:`pyramid` provides templating via the :term:`Chameleon`
+and :term:`Mako` templating libraries. :term:`Chameleon` provides support for
+two different types of templates: :term:`ZPT` templates and text templates.
 
 Before discussing how built-in templates are used in
 detail, we'll discuss two ways to render templates within
@@ -166,13 +165,11 @@ For example, here's an example of using raw `Mako
        response = Response(result)
        return response
 
-You probably wouldn't use this particular snippet in a project,
-because it's easier to use the Mako renderer bindings which already
-exist for :mod:`pyramid` named ``repoze.bfg.mako`` (available from
-`PyPI <http://pypi.python.org/pypi/repoze.bfg.mako>`_).  But if your
-favorite templating system is not supported as a renderer extension
-for :mod:`pyramid`, you can create your own simple combination as
-shown above.
+You probably wouldn't use this particular snippet in a project, because it's
+easier to use the Mako renderer bindings which already exist in
+:mod:`pyramid`. But if your favorite templating system is not supported as a
+renderer extension for :mod:`pyramid`, you can create your own simple
+combination as shown above.
 
 .. note::
 
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 37fb6562b..84c7e0e25 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -564,6 +564,57 @@ attaching properties to the request.  See
 :ref:`response_request_attrs`.
 
 .. index::
+   pair: renderer; mako
+
+.. _mako_template_renderers:
+
+``*.mak`` or ``*.mako``: Mako Template Renderer
++++++++++++++++++++++++++++++++++++++++++++++++
+
+The ``Mako`` template renderer is a renderer which renders a Mako template.
+When used, the view must return a Response object or a Python *dictionary*.
+The dictionary items will then be used in the global template space. If the
+view callable returns anything but a Response object or a dictionary, an error
+will be raised.
+
+When using the ``renderer`` attribute to specify a Mako template, the template
+can be specified in two ways. First, a relative path can be used to name a
+Mako template relative to the configured Mako template directories. Second, a
+:term:`resource specification` can be used to locate a template to render.
+These two styles of naming a template to render also carry through to Mako
+templates, so that Mako template's can inherit using a :term:`resource
+specification` if desired.
+
+Here's an example view configuration which uses a relative path:
+
+.. code-block:: xml
+   :linenos:
+
+   <view
+       context=".models.Hello"
+       view=".views.hello_world"
+       name="hello"
+       renderer="foo.mak"
+       />
+
+It's important to note that in Mako's case, the 'relative' path name is not
+relative to the package, but is relative the the directory configured for
+Mako.
+
+Here's an example view configuration which uses a :term:`resource
+specification`:
+
+.. code-block:: xml
+   :linenos:
+
+   <view
+       context=".models.Hello"
+       view=".views.hello_world"
+       name="hello"
+       renderer="some.package:templates/foo.mak"
+       />
+
+.. index::
    single: response headers (from a renderer)
    single: renderer response headers