Tweaks.

1 files changed, 17 insertions, 15 deletions

diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 7adeda3b9..36c0b618a 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -1,10 +1,10 @@
 Security
 ========
 
-``repoze.bfg`` provides an optional declarative security system that
-prevents views that are protected by a :term:`permission` from being
-rendered when the user represented by the request does not have the
-appropriate level of access in a context.
+:mod:`repoze.bfg` provides an optional declarative security system
+that prevents views that are protected by a :term:`permission` from
+being rendered when the user represented by the request does not have
+the appropriate level of access in a context.
 
 Security is enabled by adding configuration to your ``configure.zcml``
 which specifies a :term:`security policy`.
@@ -12,8 +12,8 @@ which specifies a :term:`security policy`.
 Enabling a Security Policy
 --------------------------
 
-By default, ``repoze.bfg`` enables no security policy.  All views are
-accessible by completely anonymous users.
+By default, :mod:`repoze.bfg` enables no security policy.  All views
+are accessible by completely anonymous users.
 
 However, if you add the following bit of code to your application's
 ``configure.zcml``, you will enable a security policy::
@@ -36,10 +36,11 @@ WSGI server.
 Protecting Views with Permissions
 ---------------------------------
 
-You declaratively protected a particular view with a permisson via the
-``configure.zcml`` application registry.  For example, the following
-declaration protects the view named ``add_entry.html`` when invoked
-against an ``IBlog`` context with the ``add`` permission::
+You declaratively protected a particular view with a
+:term:`permission` via the ``configure.zcml`` application registry.
+For example, the following declaration protects the view named
+``add_entry.html`` when invoked against an ``IBlog`` context with the
+``add`` permission::
 
   <bfg:view
       for=".models.IBlog"
@@ -59,7 +60,7 @@ to the system.  You can name permissions whatever you like.
 Assigning ACLs to your Model Objects
 ------------------------------------
 
-When ``repoze.bfg`` determines whether a user possesses a particular
+When :mod:`repoze.bfg` determines whether a user possesses a particular
 permission in a :term:`context`, it examines the :term:`ACL`
 associated with the context.  An ACL is associated with a context by
 virtue of the ``__acl__`` attribute of the model object representing
@@ -86,9 +87,10 @@ class::
           ]
       implements(IBlog, ILocation)
 
-The above ACL indicates that the Everyone principal (a system-defined
-principal) is allowed to view the blog, the ``group:editors``
-principal is allowed to add to and edit the blog.
+The above ACL indicates that the ``Everyone`` principal (a special
+system-defined principal indicating, literally, everyone) is allowed
+to view the blog, the ``group:editors`` principal is allowed to add to
+and edit the blog.
 
 A principal is usually a user id, however it also may be a group id if
 your authentication system provides group information and the security
@@ -119,7 +121,7 @@ which points at their parent object.  The root object's ``__parent__``
 is ``None``.  An object with a ``__parent__`` attribute and a
 ``__name__`` attribute is said to be *location-aware*.
 
-If the root object in a ``repoze.bfg`` application declares that it
+If the root object in a :mod:`repoze.bfg` application declares that it
 implements the ``ILocation`` interface, it is assumed that the objects
 in the rest of the model are location-aware.  Even if they are not
 explictly, if the root object is marked as ``ILocation``, the bfg