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

6 files changed, 52 insertions, 55 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 7dc69c7c4..406b81778 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -505,15 +505,20 @@ Glossary
      available as its ``__parent__`` attribute.
 
    root factory
-     The "root factory" of a :app:`Pyramid` application is called
-     on every request sent to the application.  The root factory
-     returns the traversal root of an application.  It is
-     conventionally named ``get_root``.  An application may supply a
-     root factory to :app:`Pyramid` during the construction of a
-     :term:`Configurator`.  If a root factory is not supplied, the
-     application uses a default root object.  Use of the default root
-     object is useful in application which use :term:`URL dispatch` for
-     all URL-to-view code mappings.
+     The "root factory" of a :app:`Pyramid` application is called on every
+     request sent to the application.  The root factory returns the traversal
+     root of an application.  It is conventionally named ``get_root``.  An
+     application may supply a root factory to :app:`Pyramid` during the
+     construction of a :term:`Configurator`.  If a root factory is not
+     supplied, the application creates a default root object using the
+     :term:`default root factory`.  
+
+   default root factory
+     If an application does not register a :term:`root factory` at Pyramid
+     configuration time, a *default* root factory is used to created the
+     default root object.  Use of the default root object is useful in
+     application which use :term:`URL dispatch` for all URL-to-view code
+     mappings, and does not (knowingly) use traversal otherwise.
 
    SQLAlchemy
      `SQLAlchemy <http://www.sqlalchemy.org/>`_ is an object
@@ -1009,7 +1014,8 @@ Glossary
 
    Green Unicorn
       Aka ``gunicorn``, a fast :term:`WSGI` server that runs on UNIX under
-      Python 2.6+ or Python 3.1+.  See http://gunicorn.org/ for detailed information.
+      Python 2.6+ or Python 3.1+.  See http://gunicorn.org/ for detailed 
+      information.
 
    predicate factory
       A callable which is used by a third party during the registration of a
@@ -1021,3 +1027,9 @@ Glossary
       A Python :term:`distribution` that uses Pyramid's extensibility
       to plug into a Pyramid application and provide extra,
       configurable services.
+
+   pyramid_redis_sessions
+      A package by Eric Rasmussen which allows you to store Pyramid session 
+      data in a Redis database.  See 
+      https://pypi.python.org/pypi/pyramid_redis_sessions for more information.
+
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::
 
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index 98584e608..2db18c8a7 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -729,8 +729,8 @@ that requires semi-permanent data to be saved. For example, a shopping
 cart. This is called a :term:`session`.
 
 Pyramid has basic built-in support for sessions, with add-ons such as
-*Beaker* (or your own custom sessioning engine) that provide richer
-session support. Let's take a look at the
+``pyramid_redis_sessions`` (or your own custom sessioning engine) that provide 
+richer session support. Let's take a look at the
 :doc:`built-in sessioning support <../narr/sessions>`. In our
 ``__init__.py`` we first import the kind of sessioning we want:
 
@@ -768,8 +768,7 @@ Jinja2 template:
 .. seealso:: See Also:
     :ref:`Quick Tutorial Sessions <qtut_sessions>`,
     :ref:`sessions_chapter`, :ref:`flash_messages`,
-    :ref:`session_module`, and
-    :ref:`Beaker sessioning middleware <beaker:overview>`
+    :ref:`session_module`, and :term:`pyramid_redis_sessions`.
 
 Databases
 =========