1 files changed, 57 insertions, 24 deletions
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 9db0b1c4d..ba72ebfbf 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -46,20 +46,6 @@ within the body of a view callable like so:
                                  {'foo':1, 'bar':2}, 
                                  request=request)
 
-.. warning::
-
-   Earlier iterations of this documentation
-   (pre-version-1.3) encouraged the application developer to use
-   ZPT-specific APIs such as
-   :func:`pyramid.chameleon_zpt.render_template_to_response` and
-   :func:`pyramid.chameleon_zpt.render_template` to render templates
-   directly.  This style of rendering still works, but at least for
-   purposes of this documentation, those functions are deprecated.
-   Application developers are encouraged instead to use the functions
-   available in the :mod:`pyramid.renderers` module to perform
-   rendering tasks.  This set of functions works to render templates
-   for all renderer extensions registered with :app:`Pyramid`.
-
 The ``sample_view`` :term:`view callable` function above returns a
 :term:`response` object which contains the body of the
 ``templates/foo.pt`` template.  In this case, the ``templates``
@@ -79,12 +65,12 @@ prefix on Windows.
 .. warning::
 
    Only :term:`Chameleon` templates support defining a renderer for a
-   template relative to the location of the module where the view
-   callable is defined.  Mako templates, and other templating system
-   bindings work differently.  In particular, Mako templates use a
-   "lookup path" as defined by the ``mako.directories`` configuration
-   file instead of treating relative paths as relative to the current
-   view module.  See :ref:`mako_templates`.
+   template relative to the location of the module where the view callable is
+   defined.  Mako templates, and other templating system bindings work
+   differently.  In particular, Mako templates use a "lookup path" as defined
+   by the ``mako.directories`` configuration file instead of treating
+   relative paths as relative to the current view module.  See
+   :ref:`mako_templates`.
 
 The path can alternately be a :term:`asset specification` in the form
 ``some.dotted.package_name:relative/path``. This makes it possible to
@@ -534,6 +520,33 @@ And ``templates/mytemplate.pt`` might look like so:
       </span>
     </html>
 
+
+Using A Chameleon Macro Name Within a Renderer Name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sommetime you'd like to render a macro inside of a Chameleon ZPT template
+instead of the full Chameleon ZPT template. To render the content of a
+``define-macro`` field inside a Chameleon ZPT template, given a Chameleon
+template file named ``foo.pt`` and a macro named ``bar`` defined within it
+(e.g. ``<div metal:define-macro="bar">...</div>``), you can configure the
+template as a :term:`renderer` like so:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.view import view_config
+
+   @view_config(renderer='foo#bar.pt')
+   def my_view(request):
+       return {'project':'my project'}
+
+The above will render only the ``bar`` macro defined within the ``foo.pt``
+template instead of the entire template.
+
+.. note::
+
+   This feature is new in Pyramid 1.4.
+
 .. index::
    single: Chameleon text templates
 
@@ -573,10 +586,6 @@ When the template is rendered, it will show:
 
    Hello, world!
 
-If you'd rather use templates directly within a view callable (without
-the indirection of using a renderer), see :ref:`chameleon_text_module`
-for the API description.
-
 See also :ref:`built_in_renderers` for more general information about
 renderers, including Chameleon text renderers.
 
@@ -714,6 +723,30 @@ This template doesn't use any advanced features of Mako, only the
 :term:`renderer globals`.  See the `the Mako documentation
 <http://www.makotemplates.org/>`_ to use more advanced features.
 
+Using A Mako def name Within a Renderer Name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sommetime you'd like to render a ``def`` inside of a Mako template instead of
+the full Mako template. To render a def inside a Mako template, given a
+:term:`Mako` template file named ``foo.mak`` and a def named ``bar``, you can
+configure the template as a :term:`renderer` like so:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.view import view_config
+
+   @view_config(renderer='foo#bar.mak')
+   def my_view(request):
+       return {'project':'my project'}
+
+The above will render the ``bar`` def from within the ``foo.mak`` template
+instead of the entire template.
+
+.. note::
+
+   This feature is new in Pyramid 1.4.
+
 .. index::
    single: automatic reloading of templates
    single: template automatic reload