Some more small fixes in the narrative docu.

3 files changed, 40 insertions, 38 deletions

diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index f8ed743fb..24845ae93 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -175,7 +175,7 @@ match is straightforward.  When a route is matched:
    Root factories related to a route were explained previously within
    :ref:`route_factories`.  Both the global root factory and default
    root factory were explained previously within
-   :ref:`the_resource_tree`.  
+   :ref:`the_resource_tree`.
 
 .. _using_traverse_in_a_route_pattern:
 
@@ -216,7 +216,7 @@ root factory.  Once :term:`traversal` has found a :term:`context` resource,
 have been invoked in a "pure" traversal-based application.
 
 Let's assume there is no *global* :term:`root factory` configured in
-this application. The *default* :term:`root factory` cannot be traversed: 
+this application. The *default* :term:`root factory` cannot be traversed:
 it has no useful ``__getitem__`` method.  So we'll need to associate
 this route configuration with a custom root factory in order to
 create a useful hybrid application.  To that end, let's imagine that
@@ -233,8 +233,8 @@ we've created a root factory that looks like so in a module named
        def __getitem__(self, name):
           return self.subobjects[name]
 
-   root = Traversable(
-           {'a':Resource({'b':Resource({'c':Resource({})})})}
+   root = Resource(
+           {'a': Resource({'b': Resource({'c': Resource({})})})}
           )
 
    def root_factory(request):
@@ -247,12 +247,12 @@ configuration statement:
 .. code-block:: python
    :linenos:
 
-   config.add_route('home', '{foo}/{bar}/*traverse', 
+   config.add_route('home', '{foo}/{bar}/*traverse',
                     factory='mypackage.routes.root_factory')
 
 The ``factory`` above points at the function we've defined.  It will return
 an instance of the ``Traversable`` class as a root object whenever this route
-is matched.  Instances of the``Resource`` class can be used for tree
+is matched.  Instances of the ``Resource`` class can be used for tree
 traversal because they have a ``__getitem__`` method that does something
 nominally useful. Since traversal uses ``__getitem__`` to walk the resources
 of a resource tree, using traversal against the root resource implied by our
@@ -260,7 +260,7 @@ route statement is a reasonable thing to do.
 
 .. note::
 
-  We could have also used our ``root_factory`` callable as the
+  We could have also used our ``root_factory`` function as the
   ``root_factory`` argument of the
   :class:`~pyramid.config.Configurator` constructor, instead
   of associating it with a particular route inside the route's
@@ -279,12 +279,12 @@ instance named ``root`` in ``routes.py``.
 If the URL that matched a route with the pattern ``{foo}/{bar}/*traverse``,
 is ``http://example.com/one/two/a/b/c``, the traversal path used
 against the root object will be ``a/b/c``.  As a result,
-:app:`Pyramid` will attempt to traverse through the edges ``a``,
-``b``, and ``c``, beginning at the root object.
+:app:`Pyramid` will attempt to traverse through the edges ``'a'``,
+``'b'``, and ``'c'``, beginning at the root object.
 
 In our above example, this particular set of traversal steps will mean that
-the :term:`context` resource of the view would be the ``Traversable`` object
-we've named ``c`` in our bogus resource tree and the :term:`view name`
+the :term:`context` resource of the view would be the ``Resource`` object
+we've named ``'c'`` in our bogus resource tree and the :term:`view name`
 resulting from traversal will be the empty string; if you need a refresher
 about why this outcome is presumed, see :ref:`traversal_algorithm`.
 
@@ -297,7 +297,7 @@ invoked after a route matches:
 .. code-block:: python
    :linenos:
 
-   config.add_route('home', '{foo}/{bar}/*traverse', 
+   config.add_route('home', '{foo}/{bar}/*traverse',
                     factory='mypackage.routes.root_factory')
    config.add_view('mypackage.views.myview', route_name='home')
 
@@ -327,11 +327,11 @@ when a hybrid route is matched:
 .. code-block:: python
    :linenos:
 
-   config.add_route('home', '{foo}/{bar}/*traverse', 
+   config.add_route('home', '{foo}/{bar}/*traverse',
                     factory='mypackage.routes.root_factory')
-   config.add_view('mypackage.views.myview', name='home')
-   config.add_view('mypackage.views.another_view', name='another', 
-                   route_name='home')
+   config.add_view('mypackage.views.myview', route_name='home')
+   config.add_view('mypackage.views.another_view', route_name='home',
+                   name='another')
 
 The ``add_view`` call for ``mypackage.views.another_view`` above names a
 different view and, more importantly, a different :term:`view name`.  The
@@ -373,12 +373,12 @@ Here's a use of the ``traverse`` pattern in a call to
    :linenos:
 
    config.add_route('abc', '/articles/{article}/edit',
-                    traverse='/articles/{article}')
+                    traverse='/{article}')
 
 The syntax of the ``traverse`` argument is the same as it is for
 ``pattern``.
 
-If, as above, the ``pattern`` provided is ``articles/{article}/edit``,
+If, as above, the ``pattern`` provided is ``/articles/{article}/edit``,
 and the ``traverse`` argument provided is ``/{article}``, when a
 request comes in that causes the route to match in such a way that the
 ``article`` match value is ``1`` (when the request URI is
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index a11466a87..ec5eaa4a7 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -88,12 +88,12 @@ Here's a sample resource tree, represented by a variable named ``root``:
     class Resource(dict):
         pass
 
-    root = Resource({'a':Resource({'b':Resource({'c':Resource()})})})
+    root = Resource({'a': Resource({'b': Resource({'c': Resource()})})})
 
 The resource tree we've created above is represented by a dictionary-like
-root object which has a single child named ``a``.  ``a`` has a single child
-named ``b``, and ``b`` has a single child named ``c``, which has no children.
-It is therefore possible to access ``c`` like so:
+root object which has a single child named ``'a'``.  ``'a'`` has a single child
+named ``'b'``, and ``'b'`` has a single child named ``'c'``, which has no
+children. It is therefore possible to access the ``'c'`` leaf resource like so:
 
 .. code-block:: python
    :linenos:
@@ -101,7 +101,7 @@ It is therefore possible to access ``c`` like so:
    root['a']['b']['c']
 
 If you returned the above ``root`` object from a :term:`root factory`, the
-path ``/a/b/c`` would find the ``c`` object in the resource tree as the
+path ``/a/b/c`` would find the ``'c'`` object in the resource tree as the
 result of :term:`traversal`.
 
 In this example, each of the resources in the tree is of the same class.
@@ -428,7 +428,7 @@ list, we will get:
 
 .. code-block:: python
    :linenos:
-    
+
    list(lineage(thing2))
    [ <Thing object at thing2>, <Thing object at thing1> ]
 
@@ -437,8 +437,8 @@ resource it was passed unconditionally.  Then, if the resource supplied a
 ``__parent__`` attribute, it returns the resource represented by
 ``resource.__parent__``.  If *that* resource has a ``__parent__`` attribute,
 return that resource's parent, and so on, until the resource being inspected
-either has no ``__parent__`` attribute or which has a ``__parent__``
-attribute of ``None``.
+either has no ``__parent__`` attribute or has a ``__parent__`` attribute of
+``None``.
 
 See the documentation for :func:`pyramid.location.lineage` for more
 information.
@@ -563,6 +563,7 @@ To do so, use the :func:`zope.interface.directlyProvides` function:
 .. code-block:: python
    :linenos:
 
+   import datetime
    from zope.interface import directlyProvides
    from zope.interface import Interface
 
@@ -587,6 +588,7 @@ the :func:`zope.interface.alsoProvides` function:
 .. code-block:: python
    :linenos:
 
+   import datetime
    from zope.interface import alsoProvides
    from zope.interface import directlyProvides
    from zope.interface import Interface
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index d99e5bed5..5640800a2 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -77,7 +77,7 @@ All forms of view configuration accept the same general types of arguments.
 Many arguments supplied during view configuration are :term:`view predicate`
 arguments.  View predicate arguments used during view configuration are used
 to narrow the set of circumstances in which :term:`view lookup` will find a
-particular view callable.  
+particular view callable.
 
 In general, the fewer number of predicates which are supplied to a
 particular view configuration, the more likely it is that the associated
@@ -112,7 +112,7 @@ Non-Predicate Arguments
   The name of a :term:`permission` that the user must possess in order to
   invoke the :term:`view callable`.  See :ref:`view_security_section` for
   more information about view security and permissions.
-  
+
   If ``permission`` is not supplied, no permission is registered for this
   view (it's accessible by any caller).
 
@@ -183,7 +183,7 @@ Non-Predicate Arguments
   argument.  The view callable it is passed will accept ``(context,
   request)``.  The decorator must return a replacement view callable which
   also accepts ``(context, request)``.
-          
+
 ``mapper``
   A Python object or :term:`dotted Python name` which refers to a :term:`view
   mapper`, or ``None``.  By default it is ``None``, which indicates that the
@@ -228,7 +228,7 @@ configured view.
   ``pattern``, representing a part of the path that will be used by
   :term:`traversal` against the result of the route's :term:`root factory`.
 
-  If ``route_name`` is not supplied, the view callable will be have a chance
+  If ``route_name`` is not supplied, the view callable will only have a chance
   of being invoked if no other route was matched. This is when the
   request/context pair found via :term:`resource location` does not indicate
   it matched any configured route.
@@ -400,7 +400,7 @@ configuration stanza:
 .. code-block:: python
    :linenos:
 
-   config.add_view('mypackage.views.my_view', name='my_view', request_method='POST', 
+   config.add_view('mypackage.views.my_view', name='my_view', request_method='POST',
                    context=MyResource, permission='read')
 
 All arguments to ``view_config`` may be omitted.  For example:
@@ -517,7 +517,7 @@ registration.  For example:
 
 This registers the same view under two different names.
 
-The decorator can also be used against class methods:
+The decorator can also be used against a method of a class:
 
 .. code-block:: python
    :linenos:
@@ -533,9 +533,9 @@ The decorator can also be used against class methods:
        def amethod(self):
            return Response('hello')
 
-When the decorator is used against a class method, a view is registered for
-the *class*, so the class constructor must accept an argument list in one of
-two forms: either it must accept a single argument ``request`` or it must
+When the decorator is used against a method of a class, a view is registered
+for the *class*, so the class constructor must accept an argument list in one
+of two forms: either it must accept a single argument ``request`` or it must
 accept two arguments, ``context, request``.
 
 The method which is decorated must return a :term:`response`.
@@ -760,7 +760,7 @@ Here is an example for a simple view configuration using :term:`traversal`:
    URL = /FrontPage
 
        context: <tutorial.models.Page object at 0xa12536c>
-       view name: 
+       view name:
 
        View:
        -----
@@ -791,7 +791,7 @@ A more complex configuration might generate something like this:
        route name: about
        route pattern: /about
        route path: /about
-       subpath: 
+       subpath:
        route predicates (request method = GET)
 
            View:
@@ -805,7 +805,7 @@ A more complex configuration might generate something like this:
        route name: about_post
        route pattern: /about
        route path: /about
-       subpath: 
+       subpath:
        route predicates (request method = POST)
 
            View: