Rendering tweaks.

1 files changed, 45 insertions, 52 deletions

diff --git a/docs/narr/models.rst b/docs/narr/models.rst
index c8bea4939..535aa6ac3 100644
--- a/docs/narr/models.rst
+++ b/docs/narr/models.rst
@@ -160,21 +160,48 @@ works against model instances.
 Location-Aware Model Instances
 ------------------------------
 
+.. sidebar::  Using :mod:`repoze.bfg.traversalwrapper`
+
+  If you'd rather not manage the ``__name__`` and ``__parent__``
+  attributes of your models "by hand", an add on package named
+  :mod:`repoze.bfg.traversalwrapper` can help.
+
+  In order to use this helper feature, you must first install the
+  :mod:`repoze.bfg.traversalwrapper` package (available via `SVN
+  <http://svn.repoze.org/repoze.bfg.traversalwrapper>`_), then
+  register its ``ModelGraphTraverser`` as the traversal policy, rather
+  than the default :mod:`repoze.bfg` traverser. The package contains
+  instructions.
+
+  Once :mod:`repoze.bfg` is configured with this feature, you will no
+  longer need to manage the ``__parent__`` and ``__name__`` attributes
+  on graph objects "by hand".  Instead, as necessary, during traversal
+  :mod:`repoze.bfg` will wrap each object (even the root object) in a
+  ``LocationProxy`` which will dynamically assign a ``__name__`` and a
+  ``__parent__`` to the traversed object (based on the last traversed
+  object and the name supplied to ``__getitem__``).  The root object
+  will have a ``__name__`` attribute of ``None`` and a ``__parent__``
+  attribute of ``None``.
+
 Applications which use :term:`traversal` to locate the :term:`context`
 of a view must ensure that the model instances that make up the model
-graph are "location aware".  In order for :mod:`repoze.bfg` location,
-security, URL-generation, and traversal functions (such as the
-functions exposed in :ref:`location_module`, :ref:`traversal_module`,
-and :ref:`url_module` as well as certain functions in
-:ref:`security_module` ) to work properly against a instances in a
-model graph, all nodes in the graph must be "location-aware".  This
-means they must have two attributes: ``__parent__`` and ``__name__``.
+graph are "location aware".
+
+In order for :mod:`repoze.bfg` location, security, URL-generation, and
+traversal functions (such as the functions exposed in
+:ref:`location_module`, :ref:`traversal_module`, and :ref:`url_module`
+as well as certain functions in :ref:`security_module` ) to work
+properly against a instances in a model graph, all nodes in the graph
+must be "location-aware".  This means they must have two attributes:
+``__parent__`` and ``__name__``.
+
 The ``__parent__`` attribute should be a reference to the node's
 parent model instance in the graph.  The ``__name__`` attribute should
 be the name that a node's parent refers to the node via
-``__getitem__``.  The ``__parent__`` of the root object should be
-``None`` and its ``__name__`` should be the empty string.  For
-instance:
+``__getitem__``.
+
+The ``__parent__`` of the root object should be ``None`` and its
+``__name__`` should be the empty string.  For instance:
 
 .. code-block:: python
 
@@ -182,15 +209,6 @@ instance:
        __name__ = ''
        __parent__ = None
 
-.. warning:: If your root model object has a ``__name__`` argument
-   that is not ``None`` or the empty string, URLs returned by the
-   ``repoze.bfg.url.model_url`` function and paths generated by the
-   ``repoze.bfg.traversal.model_path`` and
-   ``repoze.bfg.traversal.model_path_tuple`` APIs will be generated
-   improperly.  The value of ``__name__`` will be prepended to every
-   path and URL generated (as opposed to a single leading slash or
-   empty tuple element).
-
 A node returned from the root item's ``__getitem__`` method should
 have a ``__parent__`` attribute that is a reference to the root
 object, and its ``__name__`` attribute should match the name by which
@@ -201,40 +219,15 @@ object's ``__getitem__`` should return objects that have a
 that matches the name by which they are retrieved via ``__getitem__``,
 and so on.
 
-.. note::
-
-  If you'd rather not manage the ``__name__`` and ``__parent__``
-  attributes of your models "by hand", an add-on package to
-  :mod:`repoze.bfg`` named :mod:`repoze.bfg.traversalwrapper` can help
-  you do this.
+.. warning:: If your root model object has a ``__name__`` argument
+   that is not ``None`` or the empty string, URLs returned by the
+   ``repoze.bfg.url.model_url`` function and paths generated by the
+   ``repoze.bfg.traversal.model_path`` and
+   ``repoze.bfg.traversal.model_path_tuple`` APIs will be generated
+   improperly.  The value of ``__name__`` will be prepended to every
+   path and URL generated (as opposed to a single leading slash or
+   empty tuple element).
 
-  In order to use this helper feature, you must first install the
-  :mod:`repoze.bfg.traversalwrapper` package (available from
-  `http://svn.repoze.org/repoze.bfg.traversalwrapper
-  <http://svn.repoze.org/repoze.bfg.traversalwrapper>`_), then
-  register its ``ModelGraphTraverser`` as the traversal policy, rather
-  than the default BFG ``ModelGraphTraverser``. To register the
-  :mod:`repoze.bfg.traversalwrapper` ``ModelGraphTraverser`` as the
-  traversal policy, your application will need to have the following
-  in its ``configure.zcml`` file:
-
-  .. code-block:: xml
-
-    <adapter
-        factory="repoze.bfg.traversalwrapper.ModelGraphTraverser"
-        provides="repoze.bfg.interfaces.ITraverser"
-        for="*"
-    />
-
-  If this statement is made in ZCML, you will no longer need to manage
-  the ``__parent__`` and ``__name__`` attributes on graph objects "by
-  hand".  Instead, as necessary, during traversal :mod:`repoze.bfg`
-  will wrap each object (even the root object) in a ``LocationProxy``
-  which will dynamically assign a ``__name__`` and a ``__parent__`` to
-  the traversed object (based on the last traversed object and the
-  name supplied to ``__getitem__``).  The root object will have a
-  ``__name__`` attribute of ``None`` and a ``__parent__`` attribute
-  of ``None``.
 
 :mod:`repoze.bfg` API Functions That Act Against Models
 -------------------------------------------------------