Merge pull request #1137 from kpinc/doc_render

Doc render

2 files changed, 14 insertions, 11 deletions

diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 4c19982d6..2acc81e17 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -871,18 +871,19 @@ specification` that specifies the ``mytemplate.pt`` file within the
 ``templates`` directory of the ``myproject`` package.  The asset
 specification could have also been specified as
 ``myproject:templates/mytemplate.pt``; the leading package name and colon is
-optional.  The template file it actually points to is a :term:`Chameleon` ZPT
-template file.
+optional.  The template file pointed to is a :term:`Chameleon` ZPT
+template file (``templates/my_template.pt``).
 
 This view callable function is handed a single piece of information: the
 :term:`request`.  The *request* is an instance of the :term:`WebOb`
 ``Request`` class representing the browser's request to our server.
 
-This view returns a dictionary.  When this view is invoked, a
-:term:`renderer` converts the dictionary returned by the view into HTML, and
-returns the result as the :term:`response`.  This view is configured to
-invoke a renderer which uses a :term:`Chameleon` ZPT template
-(``templates/my_template.pt``).
+.. note:: Dictionaries provide values to :term:`template`s.
+
+This view is configured to invoke a :term:`renderer` on a template.  The
+dictionary the view returns (on line 6) provides the value the renderer
+substitutes into the template when generating HTML.  The renderer then
+returns the HTML in a :term:`response`.
 
 See :ref:`views_which_use_a_renderer` for more information about how views,
 renderers, and templates relate and cooperate.
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 3059aef35..4046c67fa 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -49,10 +49,12 @@ Writing View Callables Which Use a Renderer
 -------------------------------------------
 
 As we've seen, a view callable needn't always return a Response object.
-Instead, it may return an arbitrary Python object, with the expectation
-that a :term:`renderer` will convert that object into a response instance on
-your behalf.  Some renderers use a templating system; other renderers use
-object serialization techniques.
+Instead, it may return an arbitrary Python object, with the expectation that
+a :term:`renderer` will convert that object into a response instance on your
+behalf.  Some renderers use a templating system; other renderers use object
+serialization techniques.  In practice, renderers obtain application data
+values from Python dictionaries so, in practice, view callables which use
+renderers return Python dictionaries.
 
 View configuration can vary the renderer associated with a view callable via
 the ``renderer`` attribute.  For example, this call to