Sync section titles with the summary

1 files changed, 37 insertions, 32 deletions

diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index fb80c3536..aadd5097f 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -18,9 +18,9 @@ We will do the following steps:
 * Add an :term:`authentication policy` and an :term:`authorization policy`
   (``__init__.py``).
 * Add an authentication policy callback (new ``security.py`` module).
+* Add ``login`` and ``logout`` views (``views.py``).
 * Add :term:`permission` declarations to the ``edit_page`` and ``add_page``
   views (``views.py``).
-* Add ``login`` and ``logout`` views (``views.py``).
 * Make the existing views return a ``logged_in`` flag to the renderer (``views.py``).
 * Add a login template (new ``login.pt``).
 * Add a "Logout" link to be shown when logged in and viewing or editing a page
@@ -30,15 +30,16 @@ The source code for this tutorial stage can be browsed at
 `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/authorization/
 <http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/authorization/>`_.
 
-Changing ``__init__.py`` For Authorization
--------------------------------------------
-
-We're going to be making several changes to our ``__init__.py`` file which
-will help us configure an authorization policy.
-
 Adding A Root Factory
 ~~~~~~~~~~~~~~~~~~~~~
 
+Open ``models.py`` and add the following statements:
+
+.. literalinclude:: src/authorization/tutorial/models.py
+   :lines: 1-4,35-39
+   :linenos:
+   :language: python
+
 We're going to start to use a custom :term:`root factory` within our
 ``__init__.py`` file.  The objects generated by the root factory will be used
 as the :term:`context` of each request to our application.  We do this to
@@ -49,14 +50,8 @@ our contexts, we can begin to make use of the declarative security features
 of :app:`Pyramid`.
 
 We'll modify our ``__init__.py``, passing in a :term:`root factory` to our
-:term:`Configurator` constructor.  We'll point it at a new class we create
-inside our ``models.py`` file.  Add the following statements to your
-``models.py`` file:
-
-.. literalinclude:: src/authorization/tutorial/models.py
-   :lines: 1-4,35-39
-   :linenos:
-   :language: python
+:term:`Configurator` constructor.  We'll point it at the new class we created
+inside our ``models.py`` file.
 
 The ``RootFactory`` class we've just added will be used by :app:`Pyramid` to
 construct a ``context`` object.  The context is attached to the request
@@ -78,8 +73,11 @@ information about what an :term:`ACL` represents.
 We'll pass the ``RootFactory`` we created in the step above in as the
 ``root_factory`` argument to a :term:`Configurator`.
 
-Configuring an Authorization Policy
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Add an Authorization Policy and an Authentication Policy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We're going to be making several changes to our ``__init__.py`` file which
+will help us configure an authorization policy.
 
 For any :app:`Pyramid` application to perform authorization, we need to add a
 ``security.py`` module (we'll do that shortly) and we'll need to change our
@@ -87,16 +85,16 @@ For any :app:`Pyramid` application to perform authorization, we need to add a
 :term:`authorization policy` which uses the ``security.py`` file for a
 *callback*.
 
-We'll change our ``__init__.py`` file to enable an
-``AuthTktAuthenticationPolicy`` and an ``ACLAuthorizationPolicy`` to enable
-declarative security checking. We need to import the new policies:
+We'll enable an ``AuthTktAuthenticationPolicy`` and an ``ACLAuthorizationPolicy``
+to implement declarative security checking. Open ``tutorial/__init__.py`` and
+add these import statements:
 
 .. literalinclude:: src/authorization/tutorial/__init__.py
    :lines: 2-3,7
    :linenos:
    :language: python
 
-Then, we'll add those policies to the configuration:
+Now add those policies to the configuration:
 
 .. literalinclude:: src/authorization/tutorial/__init__.py
    :lines: 16-22
@@ -112,7 +110,7 @@ represented by this policy: it is required.  The ``callback`` is a
 haven't added that module yet, but we're about to.
 
 Viewing Your Changes
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 When we're done configuring a root factory, adding a authentication and
 authorization policies, and adding routes for ``/login`` and ``/logout``,
@@ -122,11 +120,12 @@ your application's ``__init__.py`` will look like this:
    :linenos:
    :language: python
 
-Adding ``security.py``
-----------------------
+Adding an authentication policy callback
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Add a ``security.py`` module within your package (in the same directory as
-:file:`__init__.py`, :file:`views.py`, etc.) with the following content:
+Add a ``tutorial/security.py`` module within your package (in the same
+directory as :file:`__init__.py`, :file:`views.py`, etc.) with the
+following content:
 
 .. literalinclude:: src/authorization/tutorial/security.py
    :linenos:
@@ -152,7 +151,7 @@ and the permission associated with the ``add_page`` and ``edit_page``
 views, the ``editor`` user should be able to add and edit pages.
 
 Adding Login and Logout Views
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To our ``views.py`` we'll add a ``login`` view callable which renders a login
 form and processes the post from the login form, checking credentials.
@@ -203,7 +202,10 @@ head of the ``views.py`` file:
    :language: python
 
 Changing Existing Views
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Add permision declarations
+--------------------------
 
 Then we need to change each of our ``view_page``, ``edit_page`` and
 ``add_page`` view callables in ``views.py``.  Within each of these views,
@@ -216,6 +218,9 @@ something like this to each view body:
    from pyramid.security import authenticated_userid
    logged_in = authenticated_userid(request)
 
+Return a logged_in flag to the renderer
+---------------------------------------
+
 We'll then change the return value of these views to pass the `resulting
 `logged_in`` value to the template, e.g.:
 
@@ -250,7 +255,7 @@ a user whom is a member of the group named ``group:editors`` will able to
 invoke the views associated with the ``add_page`` or ``edit_page`` routes.
 
 Adding the ``login.pt`` Template
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Add a ``login.pt`` template to your templates directory.  It's
 referred to within the login view we just added to ``views.py``.
@@ -258,8 +263,8 @@ referred to within the login view we just added to ``views.py``.
 .. literalinclude:: src/authorization/tutorial/templates/login.pt
    :language: xml
 
-Change ``view.pt`` and ``edit.pt``
-----------------------------------
+Add a "Logout" link when logged in
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We'll also need to change our ``edit.pt`` and ``view.pt`` templates to
 display a "Logout" link if someone is logged in.  This link will
@@ -294,7 +299,7 @@ Our ``view.pt`` template will look something like this when we're done:
    :language: xml
 
 Viewing the Application in a Browser
-------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We can finally examine our application in a browser.  The views we'll
 try are as follows: