Wording improvements to wiki2 tutorial for clarity

docs/tutorials/wiki2/definingviews.rst

@@ -26,19 +26,19 @@ Declaring Dependencies in Our ``setup.py`` File
 The view code in our application will depend on a package which is not a
 dependency of the original "tutorial" application.  The original "tutorial"
 application was generated by the ``pcreate`` command; it doesn't know
-about our custom application requirements.  We need to add a dependency on
-the ``docutils`` package to our ``tutorial`` package's ``setup.py`` file by
-assigning this dependency to the ``requires`` parameter in the
-``setup`` function.
+about our custom application requirements.  
+
+We need to add a dependency on the ``docutils`` package to our ``tutorial``
+package's ``setup.py`` file by assigning this dependency to the ``requires`` parameter in ``setup()``.
 
 Open ``tutorial/setup.py`` and edit it to look like the following:
 
 .. literalinclude:: src/views/setup.py
    :linenos:
-   :emphasize-lines: 17
    :language: python
+   :emphasize-lines: 17
 
-(Only the highlighted line needs to be added)
+(Only the highlighted line needs to be added.)
 
 Running ``setup.py develop``
 ============================
@@ -72,22 +72,27 @@ like::
 Changing the ``views.py`` File
 ==============================
 
-We're going to edit our ``views.py`` in a rather major way.  The result of
-all of our edits to ``views.py`` will leave it looking like this:
+It's time for a major change.  Open ``tutorial/tutorial/views.py`` and edit it to look like the following:
 
 .. literalinclude:: src/views/tutorial/views.py
    :linenos:
    :language: python
+   :emphasize-lines: 1-7,12,15-70
+
+(The highlighted lines are the ones that need to be added or edited.)
 
-We've gotten rid of the ``my_view`` view function and its decorator that was
+We got rid of the ``my_view`` view function and its decorator that was
 added when we originally rendered the ``alchemy`` scaffold.  It was only an
 example and isn't relevant to our application.
 
 Then we added four :term:`view callable` functions to our ``views.py``
-module.  One view callable (named ``view_wiki``) will display the wiki itself
-(it will answer on the root URL), another named ``view_page`` will display an
-individual page, another named ``add_page`` will allow a page to be added,
-and a final view callable named ``edit_page`` will allow a page to be edited.
+module: 
+
+* ``view_wiki()`` - Displays the wiki itself. It will answer on the root URL.
+* ``view_page()`` - Displays an individual page.
+* ``add_page()`` - Allows the user to add a page.
+* ``edit_page()`` - Allows the user to edit a page.
+
 We'll describe each one briefly and show the resulting ``views.py`` file
 afterward.
 
@@ -102,27 +107,28 @@ afterward.
 The ``view_wiki`` view function
 -------------------------------
 
-The ``view_wiki`` function is the :term:`default view` that will be called
-when a request is made to the root URL of our wiki.  It always redirects to
+``view_wiki()`` is the :term:`default view` that gets called when a request 
+is made to the root URL of our wiki.  It always redirects to
 a URL which represents the path to our "FrontPage".
 
 .. literalinclude:: src/views/tutorial/views.py
    :lines: 18-21
    :linenos:
    :language: python
 
-The ``view_wiki`` function returns an instance of the
+``view_wiki()`` returns an instance of the
 :class:`pyramid.httpexceptions.HTTPFound` class (instances of which implement
 the :class:`pyramid.interfaces.IResponse` interface like
-:class:`pyramid.response.Response` does), It will use the
-:meth:`pyramid.request.Request.route_url` API to construct a URL to the
-``FrontPage`` page (e.g. ``http://localhost:6543/FrontPage``), and will use
-it as the "location" of the HTTPFound response, forming an HTTP redirect.
+:class:`pyramid.response.Response` does).
+
+It uses the :meth:`pyramid.request.Request.route_url` API to construct a 
+URL to the ``FrontPage`` page (e.g. ``http://localhost:6543/FrontPage``), which 
+is used as the "location" of the HTTPFound response, forming an HTTP redirect.
 
 The ``view_page`` view function
 -------------------------------
 
-The ``view_page`` function will be used to show a single page of our
+``view_page()`` is used to display a single page of our
 wiki.  It renders the :term:`ReStructuredText` body of a page (stored as
 the ``data`` attribute of a Page object) as HTML.  Then it substitutes an
 HTML anchor for each *WikiWord* reference in the rendered HTML using a
@@ -133,12 +139,12 @@ compiled regular expression.
    :linenos:
    :language: python
 
-The curried function named ``check`` is used as the first argument to
+The curried ``check()`` function is used as the first argument to
 ``wikiwords.sub``, indicating that it should be called to provide a value for
 each WikiWord match found in the content.  If the wiki already contains a
-page with the matched WikiWord name, the ``check`` function generates a view
+page with the matched WikiWord name, ``check()`` generates a view
 link to be used as the substitution value and returns it.  If the wiki does
-not already contain a page with with the matched WikiWord name, the function
+not already contain a page with with the matched WikiWord name, ``check()``
 generates an "add" link as the substitution value and returns it.
 
 As a result, the ``content`` variable is now a fully formed bit of HTML
@@ -147,20 +153,20 @@ our current page object.
 
 We then generate an edit URL (because it's easier to do here than in the
 template), and we return a dictionary with a number of arguments.  The fact
-that this view returns a dictionary (as opposed to a :term:`response` object)
-is a cue to :app:`Pyramid` that it should try to use a :term:`renderer`
+that ``view_page()`` returns a dictionary (as opposed to a :term:`response`
+object) is a cue to :app:`Pyramid` that it should try to use a :term:`renderer`
 associated with the view configuration to render a template.  In our case,
 the template which will be rendered will be the ``templates/view.pt``
 template, as per the configuration put into effect in ``__init__.py``.
 
 The ``add_page`` view function
 ------------------------------
 
-The ``add_page`` function will be invoked when a user clicks on a *WikiWord*
-which isn't yet represented as a page in the system.  The ``check`` function
+``add_page()`` is invoked when a user clicks on a *WikiWord* which isn't yet
+represented as a page in the system.  The ``check`` function
 within the ``view_page`` view generates URLs to this view.  It also acts as a
 handler for the form that is generated when we want to add a page object.
-The ``matchdict`` attribute of the request passed to the ``add_page`` view
+The ``matchdict`` attribute of the request passed to the ``add_page()`` view
 will have the values we need to construct URLs and find model objects.
 
 .. literalinclude:: src/views/tutorial/views.py
@@ -193,7 +199,7 @@ newly created page.
 The ``edit_page`` view function
 -------------------------------
 
-The ``edit_page`` function will be invoked when a user clicks the "Edit this
+``edit_page()`` is invoked when a user clicks the "Edit this
 Page" button on the view form.  It renders an edit form but it also acts as
 the handler for the form it renders.  The ``matchdict`` attribute of the
 request passed to the ``edit_page`` view will have a ``'pagename'`` key
@@ -258,7 +264,7 @@ and a submit button that has the name "form.submitted".  The textarea in the
 form should be filled with any existing page data when it is rendered.
 
 Once we're done with the ``edit.pt`` template, it will look a lot like
-the below:
+the following:
 
 .. literalinclude:: src/views/tutorial/templates/edit.pt
    :language: xml