reorder chapter

1 files changed, 161 insertions, 143 deletions

diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 381da0d39..238ac8328 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -142,149 +142,7 @@ For information about how to configure a forbidden view via :term:`ZCML`, see
 :ref:`forbidden_zcml`.
 
 .. index::
-   single: traverser
-
-.. _changing_the_traverser:
-
-Changing the Traverser
-----------------------
-
-The default :term:`traversal` algorithm that :app:`Pyramid` uses is explained
-in :ref:`traversal_algorithm`.  Though it is rarely necessary, this default
-algorithm can be swapped out selectively for a different traversal pattern
-via configuration.
-
-.. code-block:: python
-   :linenos:
-
-   from pyramid.interfaces import ITraverser
-   from zope.interface import Interface
-   from myapp.traversal import Traverser
-
-   config.registry.registerAdapter(Traverser, (Interface,), ITraverser)
-
-In the example above, ``myapp.traversal.Traverser`` is assumed to be a class
-that implements the following interface:
-
-.. code-block:: python
-   :linenos:
-
-   class Traverser(object):
-       def __init__(self, root):
-           """ Accept the root object returned from the root factory """
-
-       def __call__(self, request):
-           """ Return a dictionary with (at least) the keys ``root``,
-           ``context``, ``view_name``, ``subpath``, ``traversed``,
-           ``virtual_root``, and ``virtual_root_path``.  These values are
-           typically the result of a resource tree traversal.  ``root``
-           is the physical root object, ``context`` will be a resource
-           object, ``view_name`` will be the view name used (a Unicode
-           name), ``subpath`` will be a sequence of Unicode names that
-           followed the view name but were not traversed, ``traversed``
-           will be a sequence of Unicode names that were traversed
-           (including the virtual root path, if any) ``virtual_root``
-           will be a resource object representing the virtual root (or the
-           physical root if traversal was not performed), and
-           ``virtual_root_path`` will be a sequence representing the
-           virtual root path (a sequence of Unicode names) or None if
-           traversal was not performed.
-
-           Extra keys for special purpose functionality can be added as
-           necessary.
-
-           All values returned in the dictionary will be made available
-           as attributes of the ``request`` object.
-           """
-
-More than one traversal algorithm can be active at the same time.  For
-instance, if your :term:`root factory` returns more than one type of object
-conditionally, you could claim that an alternate traverser adapter is ``for``
-only one particular class or interface.  When the root factory returned an
-object that implemented that class or interface, a custom traverser would be
-used.  Otherwise, the default traverser would be used.  For example:
-
-.. code-block:: python
-   :linenos:
-
-   from pyramid.interfaces import ITraverser
-   from zope.interface import Interface
-   from myapp.traversal import Traverser
-   from myapp.resources import MyRoot
-
-   config.registry.registerAdapter(Traverser, (MyRoot,), ITraverser)
-
-If the above stanza was added to a Pyramid ``__init__.py`` file's ``main``
-function, :app:`Pyramid` would use the ``myapp.traversal.Traverser`` only
-when the application :term:`root factory` returned an instance of the
-``myapp.resources.MyRoot`` object.  Otherwise it would use the default
-:app:`Pyramid` traverser to do traversal.
-
-For information about how to configure an alternate traverser via
-:term:`ZCML`, see :ref:`changing_traverser_zcml`.
-
-.. index::
-   single: url generator
-
-.. _changing_resource_url:
-
-Changing How :mod:`pyramid.url.resource_url` Generates a URL
-------------------------------------------------------------
-
-When you add a traverser as described in :ref:`changing_the_traverser`, it's
-often convenient to continue to use the :func:`pyramid.url.resource_url` API.
-However, since the way traversal is done will have been modified, the URLs it
-generates by default may be incorrect.
-
-If you've added a traverser, you can change how
-:func:`pyramid.url.resource_url` generates a URL for a specific type of
-resource by adding a registerAdapter call for
-:class:`pyramid.interfaces.IContextURL` to your application:
-
-.. code-block:: python
-   :linenos:
-
-   from pyramid.interfaces import ITraverser
-   from zope.interface import Interface
-   from myapp.traversal import URLGenerator
-   from myapp.resources import MyRoot
-
-   config.registry.registerAdapter(URLGenerator, (MyRoot, Interface), 
-                                   IContextURL)
-
-In the above example, the ``myapp.traversal.URLGenerator`` class will be used
-to provide services to :func:`pyramid.url.resource_url` any time the
-:term:`context` passed to ``resource_url`` is of class
-``myapp.resources.MyRoot``.  The second argument in the ``(MyRoot,
-Interface)`` tuple represents the type of interface that must be possessed by
-the :term:`request` (in this case, any interface, represented by
-``zope.interface.Interface``).
-
-The API that must be implemented by a class that provides
-:class:`pyramid.interfaces.IContextURL` is as follows:
-
-.. code-block:: python
-  :linenos:
-
-  from zope.interface import Interface
-
-  class IContextURL(Interface):
-      """ An adapter which deals with URLs related to a context.
-      """
-      def __init__(self, context, request):
-          """ Accept the context and request """
-
-      def virtual_root(self):
-          """ Return the virtual root object related to a request and the
-          current context"""
-
-      def __call__(self):
-          """ Return a URL that points to the context """
-
-The default context URL generator is available for perusal as the class
-:class:`pyramid.traversal.TraversalContextURL` in the `traversal module
-<http://github.com/Pylons/pyramid/blob/master/pyramid/traversal.py>`_ of the
-:term:`Pylons` GitHub Pyramid repository.
+   single: request factory
 
 .. _changing_the_request_factory:
 
@@ -329,6 +187,9 @@ already constructed a :term:`configurator` it can also be registered via the
 
 To use ZCML for the same purpose, see :ref:`changing_request_factory_zcml`.
 
+.. index::
+   single: renderer globals
+
 .. _adding_renderer_globals:
 
 Adding Renderer Globals
@@ -384,6 +245,9 @@ exists in :ref:`beforerender_event`.
 If you'd rather ZCML to register a renderer globals factory, see
 :ref:`adding_renderer_globals_zcml`.
 
+.. index::
+   single: before render event
+
 .. _beforerender_event:
 
 Using The Before Render Event
@@ -422,6 +286,9 @@ interface at :class:`pyramid.interfaces.IBeforeRender`.
 Another mechanism which allows event subscribers more control when adding
 renderer global values exists in :ref:`adding_renderer_globals`.
 
+.. index::
+   single: response callback
+
 .. _using_response_callbacks:
 
 Using Response Callbacks
@@ -466,6 +333,9 @@ response callback to happen as the result of *every* request, you must
 re-register the callback into every new request (perhaps within a subscriber
 of a :class:`pyramid.events.NewRequest` event).
 
+.. index::
+   single: finished callback
+
 .. _using_finished_callbacks:
 
 Using Finished Callbacks
@@ -525,6 +395,154 @@ finished callback to happen as the result of *every* request, you must
 re-register the callback into every new request (perhaps within a subscriber
 of a :class:`pyramid.events.NewRequest` event).
 
+.. index::
+   single: traverser
+
+.. _changing_the_traverser:
+
+Changing the Traverser
+----------------------
+
+The default :term:`traversal` algorithm that :app:`Pyramid` uses is explained
+in :ref:`traversal_algorithm`.  Though it is rarely necessary, this default
+algorithm can be swapped out selectively for a different traversal pattern
+via configuration.
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.interfaces import ITraverser
+   from zope.interface import Interface
+   from myapp.traversal import Traverser
+
+   config.registry.registerAdapter(Traverser, (Interface,), ITraverser)
+
+In the example above, ``myapp.traversal.Traverser`` is assumed to be a class
+that implements the following interface:
+
+.. code-block:: python
+   :linenos:
+
+   class Traverser(object):
+       def __init__(self, root):
+           """ Accept the root object returned from the root factory """
+
+       def __call__(self, request):
+           """ Return a dictionary with (at least) the keys ``root``,
+           ``context``, ``view_name``, ``subpath``, ``traversed``,
+           ``virtual_root``, and ``virtual_root_path``.  These values are
+           typically the result of a resource tree traversal.  ``root``
+           is the physical root object, ``context`` will be a resource
+           object, ``view_name`` will be the view name used (a Unicode
+           name), ``subpath`` will be a sequence of Unicode names that
+           followed the view name but were not traversed, ``traversed``
+           will be a sequence of Unicode names that were traversed
+           (including the virtual root path, if any) ``virtual_root``
+           will be a resource object representing the virtual root (or the
+           physical root if traversal was not performed), and
+           ``virtual_root_path`` will be a sequence representing the
+           virtual root path (a sequence of Unicode names) or None if
+           traversal was not performed.
+
+           Extra keys for special purpose functionality can be added as
+           necessary.
+
+           All values returned in the dictionary will be made available
+           as attributes of the ``request`` object.
+           """
+
+More than one traversal algorithm can be active at the same time.  For
+instance, if your :term:`root factory` returns more than one type of object
+conditionally, you could claim that an alternate traverser adapter is ``for``
+only one particular class or interface.  When the root factory returned an
+object that implemented that class or interface, a custom traverser would be
+used.  Otherwise, the default traverser would be used.  For example:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.interfaces import ITraverser
+   from zope.interface import Interface
+   from myapp.traversal import Traverser
+   from myapp.resources import MyRoot
+
+   config.registry.registerAdapter(Traverser, (MyRoot,), ITraverser)
+
+If the above stanza was added to a Pyramid ``__init__.py`` file's ``main``
+function, :app:`Pyramid` would use the ``myapp.traversal.Traverser`` only
+when the application :term:`root factory` returned an instance of the
+``myapp.resources.MyRoot`` object.  Otherwise it would use the default
+:app:`Pyramid` traverser to do traversal.
+
+For information about how to configure an alternate traverser via
+:term:`ZCML`, see :ref:`changing_traverser_zcml`.
+
+.. index::
+   single: url generator
+
+.. _changing_resource_url:
+
+Changing How :mod:`pyramid.url.resource_url` Generates a URL
+------------------------------------------------------------
+
+When you add a traverser as described in :ref:`changing_the_traverser`, it's
+often convenient to continue to use the :func:`pyramid.url.resource_url` API.
+However, since the way traversal is done will have been modified, the URLs it
+generates by default may be incorrect.
+
+If you've added a traverser, you can change how
+:func:`pyramid.url.resource_url` generates a URL for a specific type of
+resource by adding a registerAdapter call for
+:class:`pyramid.interfaces.IContextURL` to your application:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.interfaces import ITraverser
+   from zope.interface import Interface
+   from myapp.traversal import URLGenerator
+   from myapp.resources import MyRoot
+
+   config.registry.registerAdapter(URLGenerator, (MyRoot, Interface), 
+                                   IContextURL)
+
+In the above example, the ``myapp.traversal.URLGenerator`` class will be used
+to provide services to :func:`pyramid.url.resource_url` any time the
+:term:`context` passed to ``resource_url`` is of class
+``myapp.resources.MyRoot``.  The second argument in the ``(MyRoot,
+Interface)`` tuple represents the type of interface that must be possessed by
+the :term:`request` (in this case, any interface, represented by
+``zope.interface.Interface``).
+
+The API that must be implemented by a class that provides
+:class:`pyramid.interfaces.IContextURL` is as follows:
+
+.. code-block:: python
+  :linenos:
+
+  from zope.interface import Interface
+
+  class IContextURL(Interface):
+      """ An adapter which deals with URLs related to a context.
+      """
+      def __init__(self, context, request):
+          """ Accept the context and request """
+
+      def virtual_root(self):
+          """ Return the virtual root object related to a request and the
+          current context"""
+
+      def __call__(self):
+          """ Return a URL that points to the context """
+
+The default context URL generator is available for perusal as the class
+:class:`pyramid.traversal.TraversalContextURL` in the `traversal module
+<http://github.com/Pylons/pyramid/blob/master/pyramid/traversal.py>`_ of the
+:term:`Pylons` GitHub Pyramid repository.
+
+.. index::
+   single: configuration decorator
+
 .. _registering_configuration_decorators:
 
 Registering Configuration Decorators