Merge pull request #1775 from stevepiercy/master

cherry pick from 1.5-branch

docs/tutorials/wiki/design.rst

@@ -2,22 +2,22 @@
 Design
 ==========
 
-Following is a quick overview of our wiki application, to help
-us understand the changes that we will be doing next in our
-default files generated by the ``zodb`` scaffold.
+Following is a quick overview of the design of our wiki application, to help
+us understand the changes that we will be making as we work through the
+tutorial.
 
 Overall
 -------
 
-We choose to use ``reStructuredText`` markup in the wiki text.
-Translation from reStructuredText to HTML is provided by the
-widely used ``docutils`` Python module.  We will add this module
-in the dependency list on the project ``setup.py`` file.
+We choose to use :term:`reStructuredText` markup in the wiki text. Translation
+from reStructuredText to HTML is provided by the widely used ``docutils``
+Python module.  We will add this module in the dependency list on the project
+``setup.py`` file.
 
 Models
 ------
 
-The root resource, named *Wiki*, will be a mapping of wiki page
+The root resource named ``Wiki`` will be a mapping of wiki page
 names to page resources.  The page resources will be instances
 of a *Page* class and they store the text content.
 
@@ -29,9 +29,9 @@ To add a page to the wiki, a new instance of the page resource
 is created and its name and reference are added to the Wiki
 mapping.
 
-A page named *FrontPage* containing the text *This is the front
-page*, will be created when the storage is initialized, and will
-be used as the wiki home page.
+A page named ``FrontPage`` containing the text *This is the front page*, will
+be created when the storage is initialized, and will be used as the wiki home
+page.
 
 Views
 -----
@@ -57,14 +57,13 @@ use to do this are below.
   corresponding passwords.
 
 - GROUPS, a dictionary mapping :term:`userids <userid>` to a
-  list of groups to which they belong to.
+  list of groups to which they belong.
 
-- ``groupfinder``, an *authorization callback* that looks up
-  USERS and GROUPS.  It will be provided in a new
-  *security.py* file.
+- ``groupfinder``, an *authorization callback* that looks up USERS and
+  GROUPS.  It will be provided in a new ``security.py`` file.
 
-- An :term:`ACL` is attached to the root :term:`resource`.  Each
-  row below details an :term:`ACE`:
+- An :term:`ACL` is attached to the root :term:`resource`.  Each row below
+  details an :term:`ACE`:
 
   +----------+----------------+----------------+
   | Action   | Principal      | Permission     |
@@ -125,7 +124,7 @@ listed in the following table:
 |                      |             |                 |  authenticate.        |            |            |
 |                      |             |                 |                       |            |            |
 |                      |             |                 |  - If authentication  |            |            |
-|                      |             |                 |    successful,        |            |            |
+|                      |             |                 |    succeeds,          |            |            |
 |                      |             |                 |    redirect to the    |            |            |
 |                      |             |                 |    page that we       |            |            |
 |                      |             |                 |    came from.         |            |            |
@@ -145,6 +144,6 @@ listed in the following table:
        when there is no view name.
 .. [2] Pyramid will return a default 404 Not Found page
        if the page *PageName* does not exist yet.
-.. [3] pyramid.exceptions.Forbidden is reached when a
+.. [3] ``pyramid.exceptions.Forbidden`` is reached when a
        user tries to invoke a view that is
        not authorized by the authorization policy.