Merge branch 'master' into feature.instance-properties

15 files changed, 82 insertions, 63 deletions

diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index 2ef55d15b..d7bd24a53 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -353,7 +353,7 @@ when we're done:
 
 .. literalinclude:: src/authorization/tutorial/views.py
    :linenos:
-   :emphasize-lines: 11,14-18,31,37,58,61,73,76,88,91-117,119-123
+   :emphasize-lines: 11,14-18,25,31,37,58,61,73,76,88,91-117,119-123
    :language: python
 
 (Only the highlighted lines need to be added.)
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index 5f4ea671c..b3184c4fc 100644
--- a/docs/tutorials/wiki2/basiclayout.rst
+++ b/docs/tutorials/wiki2/basiclayout.rst
@@ -100,7 +100,7 @@ used when the URL is ``/``:
       :language: py
 
 Since this route has a ``pattern`` equalling ``/`` it is the route that will
-be matched when the URL ``/`` is visted, e.g. ``http://localhost:6543/``.
+be matched when the URL ``/`` is visited, e.g. ``http://localhost:6543/``.
 
 ``main`` next calls the ``scan`` method of the configurator, which will
 recursively scan our ``tutorial`` package, looking for ``@view_config`` (and
@@ -190,7 +190,7 @@ Next we set up a SQLAlchemy "DBSession" object:
 ``scoped_session`` allows us to access our database connection globally.
 ``sessionmaker`` creates a database session object.  We pass to
 ``sessionmaker`` the ``extension=ZopeTransactionExtension()`` extension
-option in order to allow the system to automatically manage datbase
+option in order to allow the system to automatically manage database
 transactions.  With ``ZopeTransactionExtension`` activated, our application
 will automatically issue a transaction commit after every request unless an
 exception is raised, in which case the transaction will be aborted.
diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst
index ac58e1e46..24ac4338d 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..deaf32ef6 100644
--- a/docs/tutorials/wiki2/design.rst
+++ b/docs/tutorials/wiki2/design.rst
@@ -20,7 +20,7 @@ Models
 We'll be using a SQLite database to hold our wiki data, and we'll be using
 :term:`SQLAlchemy` to access the data in this database.
 
-Within the database, we define a single table named `tables`, whose elements
+Within the database, we define a single table named `pages`, whose elements
 will store the wiki pages.  There are two columns: `name` and `data`.
 
 URLs like ``/PageName`` will try to find an element in 
@@ -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
 -------
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index 4ee2728c2..6589a1557 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -67,10 +67,10 @@ Preparation, Windows
 Making a Project
 ================
 
-Your next step is to create a project.  :app:`Pyramid` supplies a
-variety of scaffolds to generate sample projects.  We will use the
-``alchemy`` scaffold, which generates an application
-that uses :term:`SQLAlchemy` and :term:`URL dispatch`.
+Your next step is to create a project.  For this tutorial, we will use the
+:term:`scaffold` named ``alchemy``, which generates an application
+that uses :term:`SQLAlchemy` and :term:`URL dispatch`.  :app:`Pyramid`
+supplies a variety of scaffolds to generate sample projects.
 
 The below instructions assume your current working directory is the
 "virtualenv" named "pyramidtut".
@@ -254,7 +254,7 @@ The output to your console should be something like this::
   2011-11-26 14:42:25,140 INFO  [sqlalchemy.engine.base.Engine][MainThread] 
                                 COMMIT
 
-Success!  You should now have a ``tutorial.db`` file in your current working
+Success!  You should now have a ``tutorial.sqlite`` file in your current working
 directory.  This will be a SQLite database with a single table defined in it
 (``models``).
 
diff --git a/docs/tutorials/wiki2/src/authorization/development.ini b/docs/tutorials/wiki2/src/authorization/development.ini
index 38738f3c6..eb2f878c5 100644
--- a/docs/tutorials/wiki2/src/authorization/development.ini
+++ b/docs/tutorials/wiki2/src/authorization/development.ini
@@ -10,7 +10,7 @@ pyramid.includes =
     pyramid_debugtoolbar
     pyramid_tm
 
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
 [server:main]
 use = egg:waitress#main
diff --git a/docs/tutorials/wiki2/src/authorization/production.ini b/docs/tutorials/wiki2/src/authorization/production.ini
index c4034abad..4684d2f7a 100644
--- a/docs/tutorials/wiki2/src/authorization/production.ini
+++ b/docs/tutorials/wiki2/src/authorization/production.ini
@@ -9,7 +9,7 @@ pyramid.default_locale_name = en
 pyramid.includes =
     pyramid_tm
 
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
 [server:main]
 use = egg:waitress#main
diff --git a/docs/tutorials/wiki2/src/basiclayout/development.ini b/docs/tutorials/wiki2/src/basiclayout/development.ini
index 38738f3c6..eb2f878c5 100644
--- a/docs/tutorials/wiki2/src/basiclayout/development.ini
+++ b/docs/tutorials/wiki2/src/basiclayout/development.ini
@@ -10,7 +10,7 @@ pyramid.includes =
     pyramid_debugtoolbar
     pyramid_tm
 
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
 [server:main]
 use = egg:waitress#main
diff --git a/docs/tutorials/wiki2/src/basiclayout/production.ini b/docs/tutorials/wiki2/src/basiclayout/production.ini
index c4034abad..4684d2f7a 100644
--- a/docs/tutorials/wiki2/src/basiclayout/production.ini
+++ b/docs/tutorials/wiki2/src/basiclayout/production.ini
@@ -9,7 +9,7 @@ pyramid.default_locale_name = en
 pyramid.includes =
     pyramid_tm
 
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
 [server:main]
 use = egg:waitress#main
diff --git a/docs/tutorials/wiki2/src/models/development.ini b/docs/tutorials/wiki2/src/models/development.ini
index 38738f3c6..eb2f878c5 100644
--- a/docs/tutorials/wiki2/src/models/development.ini
+++ b/docs/tutorials/wiki2/src/models/development.ini
@@ -10,7 +10,7 @@ pyramid.includes =
     pyramid_debugtoolbar
     pyramid_tm
 
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
 [server:main]
 use = egg:waitress#main
diff --git a/docs/tutorials/wiki2/src/models/production.ini b/docs/tutorials/wiki2/src/models/production.ini
index c4034abad..4684d2f7a 100644
--- a/docs/tutorials/wiki2/src/models/production.ini
+++ b/docs/tutorials/wiki2/src/models/production.ini
@@ -9,7 +9,7 @@ pyramid.default_locale_name = en
 pyramid.includes =
     pyramid_tm
 
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
 [server:main]
 use = egg:waitress#main
diff --git a/docs/tutorials/wiki2/src/tests/development.ini b/docs/tutorials/wiki2/src/tests/development.ini
index 38738f3c6..eb2f878c5 100644
--- a/docs/tutorials/wiki2/src/tests/development.ini
+++ b/docs/tutorials/wiki2/src/tests/development.ini
@@ -10,7 +10,7 @@ pyramid.includes =
     pyramid_debugtoolbar
     pyramid_tm
 
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
 [server:main]
 use = egg:waitress#main
diff --git a/docs/tutorials/wiki2/src/tests/production.ini b/docs/tutorials/wiki2/src/tests/production.ini
index c4034abad..4684d2f7a 100644
--- a/docs/tutorials/wiki2/src/tests/production.ini
+++ b/docs/tutorials/wiki2/src/tests/production.ini
@@ -9,7 +9,7 @@ pyramid.default_locale_name = en
 pyramid.includes =
     pyramid_tm
 
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
 [server:main]
 use = egg:waitress#main
diff --git a/docs/tutorials/wiki2/src/views/development.ini b/docs/tutorials/wiki2/src/views/development.ini
index 38738f3c6..eb2f878c5 100644
--- a/docs/tutorials/wiki2/src/views/development.ini
+++ b/docs/tutorials/wiki2/src/views/development.ini
@@ -10,7 +10,7 @@ pyramid.includes =
     pyramid_debugtoolbar
     pyramid_tm
 
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
 [server:main]
 use = egg:waitress#main
diff --git a/docs/tutorials/wiki2/src/views/production.ini b/docs/tutorials/wiki2/src/views/production.ini
index c4034abad..4684d2f7a 100644
--- a/docs/tutorials/wiki2/src/views/production.ini
+++ b/docs/tutorials/wiki2/src/views/production.ini
@@ -9,7 +9,7 @@ pyramid.default_locale_name = en
 pyramid.includes =
     pyramid_tm
 
-sqlalchemy.url = sqlite:///%(here)s/tutorial.db
+sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
 [server:main]
 use = egg:waitress#main