Some more small fixes in the narrative docu.

Christoph Zwerschke

2011-06-03 2e3f70d96d7d23ad147b7a98ccd001740fa2b90d

Some more small fixes in the narrative docu.

 docs/glossary.rst

@@ -55,7 +55,7 @@
     For example, the asset specification
     ``my.package:static/baz.css`` identifies the file named
     ``baz.css`` in the ``static`` subdirectory of the ``my.package``
     Python :term:`package`.  See :ref:`asset_specifications` for more 
     Python :term:`package`.  See :ref:`asset_specifications` for more
     info.

   package
@@ -65,7 +65,7 @@

   module
     A Python source file; a file on the filesystem that typically ends with
     the extension ``.py`` or ``.pyc``.  Modules often live in a 
     the extension ``.py`` or ``.pyc``.  Modules often live in a
     :term:`package`.

   project
@@ -214,9 +214,9 @@
     a :term:`context` resource.  A permission is associated with a view name
     and a resource type by the developer.  Resources are decorated with
     security declarations (e.g. an :term:`ACL`), which reference these
     tokens also.  Permissions are used by the active to security policy to
     tokens also.  Permissions are used by the active security policy to
     match the view permission against the resources's statements about which
     permissions are granted to which principal in a context in order to to
     permissions are granted to which principal in a context in order to
     answer the question "is this user allowed to do this".  Examples of
     permissions: ``read``, or ``view_blog_entries``.

@@ -356,14 +356,14 @@
   METAL
     `Macro Expansion for TAL <http://wiki.zope.org/ZPT/METAL>`_, a
     part of :term:`ZPT` which makes it possible to share common look
     and feel between templates.  
     and feel between templates.

   Genshi
     An `XML templating language <http://pypi.python.org/pypi/Genshi/>`_
     by Christopher Lenz.

   Jinja2
     A `text templating language <http://jinja.pocoo.org/2/>`_ by Armin 
     A `text templating language <http://jinja.pocoo.org/2/>`_ by Armin
     Ronacher.

   Routes
@@ -401,7 +401,7 @@
   root
     The object at which :term:`traversal` begins when :app:`Pyramid`
     searches for a :term:`context` resource (for :term:`URL Dispatch`, the
     root is *always* the context resource unless the ``traverse=`` argument 
     root is *always* the context resource unless the ``traverse=`` argument
     is used in route configuration).

   subpath
@@ -856,7 +856,7 @@
   ZCML
     `Zope Configuration Markup Language
     <http://www.muthukadan.net/docs/zca.html#zcml>`_, an XML dialect
     used by Zope and :term:`pyramid_zcml` for configuration tasks.  
     used by Zope and :term:`pyramid_zcml` for configuration tasks.

   ZCML directive
     A ZCML "tag" such as ``<view>`` or ``<route>``.
@@ -894,5 +894,5 @@
     http://docs.python.org/distutils/index.html for more information.
     :term:`setuptools` is actually an *extension* of the Distutils.

   



 docs/narr/hybrid.rst

@@ -175,7 +175,7 @@
   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 @@
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 @@
       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 @@
.. 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 @@

.. 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 @@
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 @@
.. 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 @@
.. 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 @@
   :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

 docs/narr/resources.rst

@@ -88,12 +88,12 @@
    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 @@
   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 @@

.. code-block:: python
   :linenos:
    

   list(lineage(thing2))
   [ <Thing object at thing2>, <Thing object at thing1> ]

@@ -437,8 +437,8 @@
``__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 @@
.. code-block:: python
   :linenos:

   import datetime
   from zope.interface import directlyProvides
   from zope.interface import Interface

@@ -587,6 +588,7 @@
.. code-block:: python
   :linenos:

   import datetime
   from zope.interface import alsoProvides
   from zope.interface import directlyProvides
   from zope.interface import Interface

 docs/narr/viewconfig.rst

@@ -77,7 +77,7 @@
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 @@
  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 @@
  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 @@
  ``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 @@
.. 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 @@

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 @@
       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 @@
   URL = /FrontPage

       context: <tutorial.models.Page object at 0xa12536c>
       view name: 
       view name:

       View:
       -----
@@ -791,7 +791,7 @@
       route name: about
       route pattern: /about
       route path: /about
       subpath: 
       subpath:
       route predicates (request method = GET)

           View:
@@ -805,7 +805,7 @@
       route name: about_post
       route pattern: /about
       route path: /about
       subpath: 
       subpath:
       route predicates (request method = POST)

           View: