Merge branch 'master' of github.com:Pylons/pyramid

4 files changed, 27 insertions, 41 deletions

diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 4c19982d6..9451f41b1 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -871,18 +871,17 @@ 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``).
+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.
@@ -978,7 +977,7 @@ named ``views`` instead of within a single ``views.py`` file, you might:
 - *Move* the existing ``views.py`` file to a file inside the new ``views``
   directory named, say, ``blog.py``.  Because the ``templates`` directory
   remains in the ``myproject`` package, the template :term:`asset
-  specification`s in ``blog.py`` must now be fully qualified with the
+  specification` values in ``blog.py`` must now be fully qualified with the
   project's package name (``myproject:templates/blog.pt``).
 
 You can then continue to add view callable functions to the ``blog.py``
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
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index f8279b0a5..649d22bd2 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -99,6 +99,11 @@ example:
        else:
            return Response('Fred was not in the session')
 
+The first time this view is invoked produces ``Fred was not in the
+session``.  Subsequent invocations produce ``Fred was in the
+session``, assuming of course that the client side maintains the
+session's identity across multiple requests.
+
 You can use a session much like a Python dictionary.  It supports all
 dictionary methods, along with some extra attributes, and methods.
 
@@ -154,10 +159,10 @@ Some gotchas:
 Using Alternate Session Factories
 ---------------------------------
 
-At the time of this writing, exactly one project-endorsed alternate session 
-factory exists named``pyramid_redis_sessions``.  It can be downloaded from PyPI.
-It uses Redis as a backend.  It is the recommended persistent session solution
-at the time of this writing.
+At the time of this writing, exactly one project-endorsed alternate session
+factory exists named :term:`pyramid_redis_sessions`.  It can be downloaded from
+PyPI.  It uses the Redis database as a backend.  It is the recommended 
+persistent session solution at the time of this writing.
 
 .. index::
    single: session factory (custom)
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index a60c5ba56..454bb5620 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -146,35 +146,15 @@ refer to a root factory defined in a different module.
 
 If no :term:`root factory` is passed to the :app:`Pyramid`
 :term:`Configurator` constructor, or if the ``root_factory`` value
-specified is ``None``, a *default* root factory is used.  The default
+specified is ``None``, a :term:`default root factory` is used.  The default
 root factory always returns a resource that has no child resources; it
 is effectively empty.
 
 Usually a root factory for a traversal-based application will be more
-complicated than the above ``Root`` class; in particular it may be
-associated with a database connection or another persistence mechanism.
-
-.. sidebar:: Emulating the Default Root Factory
-
-   For purposes of understanding the default root factory better, we'll note
-   that you can emulate the default root factory by using this code as an
-   explicit root factory in your application setup:
-
-   .. code-block:: python
-      :linenos:
-
-      class Root(object):
-          def __init__(self, request):
-              pass
-
-      config = Configurator(root_factory=Root)
-
-   The default root factory is just a really stupid object that has no
-   behavior or state.  Using :term:`traversal` against an application that
-   uses the resource tree supplied by the default root resource is not very
-   interesting, because the default root resource has no children.  Its
-   availability is more useful when you're developing an application using
-   :term:`URL dispatch`.
+complicated than the above ``Root`` class; in particular it may be associated
+with a database connection or another persistence mechanism.  The above
+``Root`` class is analogous to the default root factory present in Pyramid. The
+default root factory is very simple and not very useful.
 
 .. note::