Merge branch 'master' of github.com:Pylons/pyramid

4 files changed, 125 insertions, 93 deletions

diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst
index 12bfa8b84..28cecb787 100644
--- a/docs/tutorials/wiki/definingviews.rst
+++ b/docs/tutorials/wiki/definingviews.rst
@@ -229,60 +229,63 @@ this:
 Adding Templates
 ================
 
-Most view callables we've added expected to be rendered via a
-:term:`template`.  The default templating systems in :app:`Pyramid` are
-:term:`Chameleon` and :term:`Mako`.  Chameleon is a variant of :term:`ZPT`,
-which is an XML-based templating language.  Mako is a non-XML-based
-templating language.  Because we had to pick one, we chose Chameleon for this
-tutorial.
-
-The templates we create will live in the ``templates`` directory of our
+The ``view_page``, ``add_page`` and ``edit_page`` views that we've added
+reference a :term:`template`.  Each template is a :term:`Chameleon` :term:`ZPT`
+template.  These templates will live in the ``templates`` directory of our
 tutorial package.  Chameleon templates must have a ``.pt`` extension to be
 recognized as such.
 
 The ``view.pt`` Template
 ------------------------
 
-The ``view.pt`` template is used for viewing a single Page.  It is used by
-the ``view_page`` view function.  It should have a div that is "structure
-replaced" with the ``content`` value provided by the view.  It should also
-have a link on the rendered page that points at the "edit" URL (the URL which
-invokes the ``edit_page`` view for the page being viewed).
-
-Once we're done with the ``view.pt`` template, it will look a lot like
-the below:
+Create ``tutorial/tutorial/templates/view.pt`` and add the following
+content:
 
 .. literalinclude:: src/views/tutorial/templates/view.pt
+   :linenos:
    :language: xml
 
-.. note::
+This template is used by ``view_page()`` for displaying a single
+wiki page. It includes:
 
-   The names available for our use in a template are always those that
-   are present in the dictionary returned by the view callable.  But our
-   templates make use of a ``request`` object that none of our tutorial views
-   return in their dictionary.  This value appears as if "by magic".
-   However, ``request`` is one of several names that are available "by
-   default" in a template when a template renderer is used.  See
-   :ref:`chameleon_template_renderers` for more information about other names
-   that are available by default in a template when a template is used as a
-   renderer.
+- A ``div`` element that is replaced with the ``content``
+  value provided by the view (rows 45-47).  ``content``
+  contains HTML, so the ``structure`` keyword is used
+  to prevent escaping it (i.e. changing ">" to >, etc.)
+- A link that points
+  at the "edit" URL which invokes the ``edit_page`` view for
+  the page being viewed (rows 49-51).
 
 The ``edit.pt`` Template
 ------------------------
 
-The ``edit.pt`` template is used for adding and editing a Page.  It is used
-by the ``add_page`` and ``edit_page`` view functions.  It should display a
-page containing a form that POSTs back to the "save_url" argument supplied by
-the view.  The form should have a "body" textarea field (the page data), 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:
+Create ``tutorial/tutorial/templates/edit.pt`` and add the following
+content:
 
 .. literalinclude:: src/views/tutorial/templates/edit.pt
+   :linenos:
    :language: xml
 
+This template is used by ``add_page()`` and ``edit_page()`` for adding
+and editing a wiki page.  It displays
+a page containing a form that includes:
+
+- A 10 row by 60 column ``textarea`` field named ``body`` that is filled
+  with any existing page data when it is rendered (rows 46-47).
+- A submit button that has the name ``form.submitted`` (row 48).
+
+The form POSTs back to the "save_url" argument supplied
+by the view (row 45).  The view will use the ``body`` and
+``form.submitted`` values.
+
+.. note:: Our templates use a ``request`` object that
+   none of our tutorial views return in their dictionary.
+   ``request`` is one of several
+   names that are available "by default" in a template when a template
+   renderer is used.  See :ref:`chameleon_template_renderers` for
+   information about other names that are available by default
+   when a Chameleon template is used as a renderer.
+
 Static Assets
 -------------
 
@@ -302,24 +305,25 @@ Viewing the Application in a Browser
 ====================================
 
 We can finally examine our application in a browser (See
-:ref:`wiki-start-the-application`).  The views we'll try are as follows:
+:ref:`wiki-start-the-application`).  Launch a browser and visit
+each of the following URLs, check that the result is as expected:
 
-- Visiting ``http://localhost:6543/`` in a browser invokes the ``view_wiki``
+- ``http://localhost:6543/`` invokes the ``view_wiki``
   view.  This always redirects to the ``view_page`` view of the ``FrontPage``
   Page resource.
 
-- Visiting ``http://localhost:6543/FrontPage/`` in a browser invokes
+- ``http://localhost:6543/FrontPage/`` invokes
   the ``view_page`` view of the front page resource.  This is
-  because it's the *default view* (a view without a ``name``) for Page
+  because it's the :term:`default view` (a view without a ``name``) for Page
   resources.
 
-- Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser
+- ``http://localhost:6543/FrontPage/edit_page``
   invokes the edit view for the ``FrontPage`` Page resource.
 
-- Visiting ``http://localhost:6543/add_page/SomePageName`` in a
-  browser invokes the add view for a Page.
+- ``http://localhost:6543/add_page/SomePageName``
+  invokes the add view for a Page.
 
 - To generate an error, visit ``http://localhost:6543/add_page`` which
-  will generate an ``IndexError`` for the expression
-  ``request.subpath[0]``.  You'll see an interactive traceback
+  will generate an ``IndexErrorr: tuple index out of range`` error.
+  You'll see an interactive traceback
   facility provided by :term:`pyramid_debugtoolbar`.
diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst
index 2b613377a..c94612fb1 100644
--- a/docs/tutorials/wiki/design.rst
+++ b/docs/tutorials/wiki/design.rst
@@ -36,9 +36,16 @@ be used as the wiki home page.
 Views
 -----
 
-There will be four views to handle the normal operations of
-viewing, editing and adding wiki pages.  Two additional views
-will handle the login and logout tasks related to security.
+There will be three views to handle the normal operations of adding,
+editing and viewing wiki pages, plus one view for the wiki front page.
+Two templates will be used, one for viewing, and one for both for adding
+and editing wiki pages.
+
+The default templating systems in :app:`Pyramid` are
+:term:`Chameleon` and :term:`Mako`.  Chameleon is a variant of
+:term:`ZPT`, which is an XML-based templating language.  Mako is a
+non-XML-based templating language.  Because we had to pick one,
+we chose Chameleon for this tutorial.
 
 Security
 --------
@@ -52,11 +59,11 @@ use to do this are below.
 - GROUPS, a dictionary mapping user names to a 
   list of groups they belong to.
 
-- *groupfinder*, an *authorization callback* that looks up
+- ``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 resource.  Each
+- An :term:`ACL` is attached to the root :term:`resource`.  Each
   row below details an :term:`ACE`:
 
   +----------+----------------+----------------+
@@ -70,6 +77,8 @@ use to do this are below.
 - Permission declarations are added to the views to assert the security
   policies as each request is handled.
 
+Two additional views and one template will handle the login and
+logout tasks.
 
 Summary
 -------
diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst
index ac58e1e46..efb72230e 100644
--- a/docs/tutorials/wiki2/definingviews.rst
+++ b/docs/tutorials/wiki2/definingviews.rst
@@ -226,52 +226,63 @@ of the wiki page.
 Adding Templates
 ================
 
-The views we've added all reference a :term:`template`.  Each template is a
-:term:`Chameleon` :term:`ZPT` template.  These templates will live in the
-``templates`` directory of our tutorial package.
+The ``view_page``, ``add_page`` and ``edit_page`` views that we've added
+reference a :term:`template`.  Each template is a :term:`Chameleon` :term:`ZPT`
+template.  These templates will live in the ``templates`` directory of our
+tutorial package.  Chameleon templates must have a ``.pt`` extension to be
+recognized as such.
 
 The ``view.pt`` Template
 ------------------------
 
-The ``view.pt`` template is used for viewing a single wiki page.  It
-is used by the ``view_page`` view function.  It should have a ``div``
-that is "structure replaced" with the ``content`` value provided by
-the view.  It should also have a link on the rendered page that points
-at the "edit" URL (the URL which invokes the ``edit_page`` view for
-the page being viewed).
-
-Once we're done with the ``view.pt`` template, it will look a lot like the
-below:
+Create ``tutorial/tutorial/templates/view.pt`` and add the following
+content:
 
 .. literalinclude:: src/views/tutorial/templates/view.pt
+   :linenos:
    :language: xml
 
-.. note:: The names available for our use in a template are always
-   those that are present in the dictionary returned by the view
-   callable.  But our templates make use of a ``request`` object that
-   none of our tutorial views return in their dictionary.  This value
-   appears as if "by magic".  However, ``request`` is one of several
-   names that are available "by default" in a template when a template
-   renderer is used.  See :ref:`chameleon_template_renderers` for more
-   information about other names that are available by default in a
-   template when a Chameleon template is used as a renderer.
+This template is used by ``view_page()`` for displaying a single
+wiki page. It includes:
+
+- A ``div`` element that is replaced with the ``content``
+  value provided by the view (rows 45-47).  ``content``
+  contains HTML, so the ``structure`` keyword is used
+  to prevent escaping it (i.e. changing ">" to >, etc.)
+- A link that points
+  at the "edit" URL which invokes the ``edit_page`` view for
+  the page being viewed (rows 49-51).
 
 The ``edit.pt`` Template
 ------------------------
 
-The ``edit.pt`` template is used for adding and editing a wiki page.  It is
-used by the ``add_page`` and ``edit_page`` view functions.  It should display
-a page containing a form that POSTs back to the "save_url" argument supplied
-by the view.  The form should have a "body" textarea field (the page data),
-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 following:
+Create ``tutorial/tutorial/templates/edit.pt`` and add the following
+content:
 
 .. literalinclude:: src/views/tutorial/templates/edit.pt
+   :linenos:
    :language: xml
 
+This template is used by ``add_page()`` and ``edit_page()`` for adding
+and editing a wiki page.  It displays
+a page containing a form that includes:
+
+- A 10 row by 60 column ``textarea`` field named ``body`` that is filled
+  with any existing page data when it is rendered (rows 46-47).
+- A submit button that has the name ``form.submitted`` (row 48).
+
+The form POSTs back to the "save_url" argument supplied
+by the view (row 45).  The view will use the ``body`` and
+``form.submitted`` values.
+
+.. note:: Our templates use a ``request`` object that
+   none of our tutorial views return in their dictionary.
+   ``request`` is one of several
+   names that are available "by default" in a template when a template
+   renderer is used.  See :ref:`chameleon_template_renderers` for
+   information about other names that are available by default
+   when a Chameleon template is used as a renderer.
+
 Static Assets
 -------------
 
@@ -339,25 +350,24 @@ Viewing the Application in a Browser
 ====================================
 
 We can finally examine our application in a browser (See
-:ref:`wiki2-start-the-application`).  The views we'll try are
-as follows:
+:ref:`wiki2-start-the-application`).  Launch a browser and visit
+each of the following URLs, check that the result is as expected:
 
-- Visiting ``http://localhost:6543`` in a browser invokes the
+- ``http://localhost:6543`` in a browser invokes the
   ``view_wiki`` view.  This always redirects to the ``view_page`` view
   of the FrontPage page object.
 
-- Visiting ``http://localhost:6543/FrontPage`` in a browser invokes
+- ``http://localhost:6543/FrontPage`` in a browser invokes
   the ``view_page`` view of the front page page object.
 
-- Visiting ``http://localhost:6543/FrontPage/edit_page`` in a browser
+- ``http://localhost:6543/FrontPage/edit_page`` in a browser
   invokes the edit view for the front page object.
 
-- Visiting ``http://localhost:6543/add_page/SomePageName`` in a
+- ``http://localhost:6543/add_page/SomePageName`` in a
   browser invokes the add view for a page.
 
-Try generating an error within the body of a view by adding code to
-the top of it that generates an exception (e.g. ``raise
-Exception('Forced Exception')``).  Then visit the error-raising view
-in a browser.  You should see an interactive exception handler in the
-browser which allows you to examine values in a post-mortem mode.
+- To generate an error, visit ``http://localhost:6543/add_page`` which
+  will generate a ``NoResultFound: No row was found for one()`` error.
+  You'll see an interactive traceback facility provided 
+  by :term:`pyramid_debugtoolbar`.
 
diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst
index 4481153a3..2e6fc0e77 100644
--- a/docs/tutorials/wiki2/design.rst
+++ b/docs/tutorials/wiki2/design.rst
@@ -36,9 +36,16 @@ page.
 Views
 -----
 
-There will be four views to handle the normal operations of adding and
-editing wiki pages, and viewing pages and the wiki front page.  Two
-additional views will handle the login and logout tasks related to security.
+There will be three views to handle the normal operations of adding,
+editing and viewing wiki pages, plus one view for the wiki front page.
+Two templates will be used, one for viewing, and one for both for adding
+and editing wiki pages.
+
+The default templating systems in :app:`Pyramid` are
+:term:`Chameleon` and :term:`Mako`.  Chameleon is a variant of
+:term:`ZPT`, which is an XML-based templating language.  Mako is a
+non-XML-based templating language.  Because we had to pick one,
+we chose Chameleon for this tutorial.
 
 Security
 --------
@@ -67,6 +74,8 @@ use to do this are below.
 - Permission declarations are added to the views to assert the security
   policies as each request is handled.
 
+Two additional views and one template will handle the login and
+logout tasks.
 
 Summary
 -------