[Zope-CVS] CVS: Products/VerboseSecurity - README.txt:1.2

[Shane Hathaway]

Update of /cvs-repository/Products/VerboseSecurity
In directory cvs.zope.org:/tmp/cvs-serv13861

Modified Files:
	README.txt 
Log Message:
Fixed speling and gramer


=== Products/VerboseSecurity/README.txt 1.1 => 1.2 ===
--- Products/VerboseSecurity/README.txt:1.1	Wed Aug 21 11:58:18 2002
+++ Products/VerboseSecurity/README.txt	Thu Aug 22 13:26:31 2002
@@ -10,24 +10,24 @@
 VerboseSecurity Product
 =======================
 
-Zope has a fine-grained security model.  Zope lets you configure
-context-dependent mappings from users to roles and from roles to
-permissions.  The model fits most organizations' needs and has been
-used all over the world, but the flexibility sometimes comes at a
-price of complexity.
+Zope has a flexible, fine-grained security model that lets you
+configure context-dependent mappings from users to roles and from
+roles to permissions.  The model fits most organizations' needs and
+has been used all over the world, but the flexibility sometimes comes
+at a price of complexity.
 
 One major difficulty in using the Zope security model is its lack of
-clarity when access is denied.  Production sites should not reveal too
-much about the site to those who are denied access, so the Zope
-security policy's lack of verbosity is appropriate for such sites.
-But site developers require complete details.
+clarity when access is denied.  Because production sites should not
+reveal too much about the site to those who are denied access, the
+lack of verbosity in the default Zope security policy is appropriate
+for such sites.  But site developers need more details.
 
 This product attempts to explain the complete reasoning for failed
-access.  It shows what was being accessed, what permission is required
-to access it, what roles map to that permission in that context, the
-executable object and its owner, the effective proxy roles, and other
-pertinent information.  All of this information appears in the
-exception message.
+access.  It shows what object was being accessed, what permission is
+required to access it, what roles map to that permission in that
+context, the executable object and its owner, the effective proxy
+roles, and other pertinent information.  All of this information
+appears in the exception message when access is denied.
 
 This product is designed for Zope 2.6.  However, it should work with
 Zope 2.4 and Zope 2.5 as well.  It is currently in development.
@@ -36,18 +36,21 @@
 Installation
 ============
 
-Unpack the product in your Zope Products folder.
+Unpack the product in your Zope Products folder.  The VerboseSecurity
+product replaces the Zope security policy with the
+"VerboseSecurityPolicy".
 
 This product can only show permission names if it is able to
 dynamically patch (or "monkey-patch") the Python version of the Zope
 PermissionRole module.  Everything else works without the patch, but
 the required permission name is probably the most useful piece of
-information that VerboseSecurity exposes.  Zope 2.5 and 2.6 include a
-C version of the PermissionRole module, which this product is not able
-to patch at runtime.  So to enable the disable of permission names,
-you need to get Zope to switch back to the Python version of the
-PermissionRole module.  Do this by putting the following in your
-environment before starting Zope::
+information that VerboseSecurity exposes.
+
+Zope 2.5 and 2.6 include a C version of the PermissionRole module.
+This product can not dynamically patch the C version.  So to enable
+the display of permission names, you need to get Zope to use the
+Python version of the PermissionRole module.  Do this by putting the
+following in your environment before starting Zope::
 
     ZOPE_SECURITY_POLICY=PYTHON
 
@@ -55,10 +58,10 @@
 the C version of PermissionRole, VerboseSecurity will issue a warning in
 the Zope log file.
 
-The next time an Unauthorized exception occurs, you'll see a complete
+The next time an Unauthorized exception occurs, you'll get a complete
 explanation for the failed access.  If you're using Zope 2.6, you can
-also see recent exceptions through the web using the error_log
-object.  In the default configuration, however, error_log will not
+also see recent exceptions through the web using the error_log object.
+Note, however, that in the default configuration, error_log will not
 display Unauthorized exceptions.  Just remove "Unauthorized" from the
 list of ignored exceptions.
 
@@ -74,20 +77,21 @@
 unlikely to be noticeable during site development, however.
 
 - The product reveals a lot of information about the structure of your
-site, so it may not be appropriate for some production sites.  It does not
-reveal passwords, however.
+site, so it may not be appropriate for some production sites.  It is
+unlikely to inadvertently reveal passwords, though.
 
 - The product may sometimes append information about a previous
 Unauthorized exception to a new, unrelated Unauthorized exception.
 Zope makes it difficult to do the right thing here, but possible
 solutions exist.
 
-- The PermissionRole patch internally adds an imaginary role to the
-roles computed for a permission.  The imaginary role is a munged
-version of the permission name.  Consequently, it is possible to
-assign users to this imaginary role.  This is an interesting feature
-to have, since it potentially lets you bypass role assignment and
-assign users directly to permissions.  But this feature should not be
-regarded as standard, and it is not officially supported.
+- The PermissionRole patch included in the product internally adds an
+imaginary role to the roles computed for a permission.  The imaginary
+role is a munged version of the permission name.  Consequently, it is
+possible to assign users to this imaginary role.  This is an
+interesting feature to have, since it potentially lets you bypass role
+assignment and assign users directly to permissions.  But this feature
+should not be regarded as standard, and it is not officially
+supported.