Roles.

1 files changed, 20 insertions, 18 deletions

diff --git a/docs/narr/models.rst b/docs/narr/models.rst
index e1d2fd635..5002101d5 100644
--- a/docs/narr/models.rst
+++ b/docs/narr/models.rst
@@ -70,15 +70,16 @@ sole argument).
 An interface simply tags the model object with a "type" that can be
 referred to within the :term:`application registry`.  A model object
 can implement zero or more interfaces.  The interface must be an
-instance of a class that inherits from ``zope.interface.Interface``.
+instance of a class that inherits from
+:class:`zope.interface.Interface`.
 
 You specify that a model *implements* an interface by using the
-``zope.interface.implements`` function at class scope.  The above
+:func:`zope.interface.implements` function at class scope.  The above
 ``BlogEntry`` model implements the ``IBlogEntry`` interface.
 
 You can also specify that a *particular* model instance provides an
 interface (as opposed to its class).  To do so, use the
-``zope.interface.directlyProvides`` API:
+:func:`zope.interface.directlyProvides` function:
 
 .. code-block:: python
    :linenos:
@@ -101,7 +102,7 @@ interface (as opposed to its class).  To do so, use the
 
 If a model object already has instance-level interface declarations
 that you don't want to disturb, use the
-``zope.interface.alsoProvides`` API:
+:func:`zope.interface.alsoProvides` function:
 
 .. code-block:: python
    :linenos:
@@ -144,13 +145,13 @@ policy on model instance nodes in the graph:
 - Nodes which contain other nodes (aka "container" nodes) must supply
   a ``__getitem__`` method which is willing to resolve a unicode name
   to a subobject.  If a subobject by that name does not exist in the
-  container, ``__getitem__`` must raise a ``KeyError``.  If a
+  container, ``__getitem__`` must raise a :exc:`KeyError`.  If a
   subobject by that name *does* exist, the container should return the
   subobject (another model instance).
 
 - Nodes which do not contain other nodes (aka "leaf" nodes) must not
   implement a ``__getitem__``, or if they do, their ``__getitem__``
-  method must raise a ``KeyError``.
+  method must raise a :exc:`KeyError`.
 
 See :ref:`traversal_chapter` for more information about how traversal
 works against model instances.
@@ -192,7 +193,7 @@ 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 an object graph, all nodes in the
-graph must be "location-aware".  This means they must have two
+graph must be :term:`location` -aware.  This means they must have two
 attributes: ``__parent__`` and ``__name__``.
 
 The ``__parent__`` attribute should be a reference to the node's
@@ -221,12 +222,12 @@ and so on.
 
 .. 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).
+   :func:`repoze.bfg.url.model_url` function and paths generated by
+   the :func:`repoze.bfg.traversal.model_path` and
+   :func:`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).
 
 
 :mod:`repoze.bfg` API Functions That Act Against Models
@@ -245,8 +246,9 @@ instances.  These can be used to walk down an object graph, or
 conveniently locate one object "inside" another.
 
 Some APIs in :ref:`security_module` accept a model object as a
-parameter.  For example, the ``has_permission`` API accepts a
-"context" (a model object) as one of its arguments; the ACL is
-obtained from this model or one of its ancestors.  Other APIs in the
-same module also accept :term:`context` as an argument, and a context
-is always a model.
+parameter.  For example, the
+:func:`repoze.bfg.security.has_permission` API accepts a "context" (a
+model object) as one of its arguments; the ACL is obtained from this
+model or one of its ancestors.  Other APIs in the
+:mod:`repoze.bfg.security` module also accept :term:`context` as an
+argument, and a context is always a model.