Merge remote branch 'source/master'

Conflicts:
	docs/narr/hooks.rst

1 files changed, 17 insertions, 13 deletions

diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst
index 8e6e89e57..c0faf30de 100644
--- a/docs/tutorials/wiki/basiclayout.rst
+++ b/docs/tutorials/wiki/basiclayout.rst
@@ -2,10 +2,9 @@
 Basic Layout
 ============
 
-The starter files generated by the ``pyramid_zodb`` template are basic,
-but they provide a good orientation for the high-level patterns common
-to most :term:`traversal` -based :app:`Pyramid` (and :term:`ZODB`
-based) projects.
+The starter files generated by the ``pyramid_zodb`` template are basic, but
+they provide a good orientation for the high-level patterns common to most
+:term:`traversal` -based :app:`Pyramid` (and :term:`ZODB` based) projects.
 
 The source code for this tutorial stage can be browsed via
 `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/basiclayout/
@@ -21,7 +20,7 @@ well as to contain application configuration code.
 
 When you run the application using the ``paster`` command using the
 ``development.ini`` generated config file, the application configuration
-points at an Setuptools *entry point* described as ``egg:tutorial``.  In our
+points at a Setuptools *entry point* described as ``egg:tutorial``.  In our
 application, because the application's ``setup.py`` file says so, this entry
 point happens to be the ``main`` function within the file named
 ``__init__.py``:
@@ -78,11 +77,10 @@ Resources and Models with ``models.py``
 hierarchically in a :term:`resource tree`.  This tree is consulted by
 :term:`traversal` to map URLs to code.  In this application, the resource
 tree represents the site structure, but it *also* represents the
-:term:`domain model` of the application, because eeach resource is a node
+:term:`domain model` of the application, because each resource is a node
 stored persistently in a :term:`ZODB` database.  The ``models.py`` file is
 where the ``pyramid_zodb`` Paster template put the classes that implement our
-resource objects, each of which happens also to be a domain model
-object.
+resource objects, each of which happens also to be a domain model object.
 
 Here is the source for ``models.py``:
 
@@ -171,7 +169,6 @@ The ``development.ini`` (in the tutorial :term:`project` directory, as
 opposed to the tutorial :term:`package` directory) looks like this:
 
 .. literalinclude:: src/views/development.ini
-   :linenos:
    :language: ini
 
 
@@ -184,15 +181,22 @@ composed of :term:`middleware`.
 
 The ``egg:WebError#evalerror`` middleware is at the "top" of the pipeline.
 This is middleware which displays debuggable errors in the browser while
-you're developing (not recommended for deployment).
+you're developing (not recommended for a production system).
 
 The ``egg:repoze.zodbconn#closer`` middleware is in the middle of the
 pipeline.  This is a piece of middleware which closes the ZODB connection
 opened by the ``PersistentApplicationFinder`` at the end of the request.
 
-The ``egg:repoze.tm#tm`` middleware is the last piece of middleware in the
-pipeline.  This commits a transaction near the end of the request unless
-there's an exception raised.
+The ``egg:repoze.retry#retry`` middleware catches ``ConflictError``
+exceptions from ZODB and retries the request up to three times (ZODB is an
+optimistic concurrency database that relies on application-level transaction
+retries when a conflict occurs).
+
+The ``tm`` middleware is the last piece of middleware in the pipeline.  This
+commits a transaction near the end of the request unless there's an exception
+raised or the HTTP response code is an error code.  The ``tm`` refers to the
+``[filter:tm]`` section beneath the pipeline declaration, which configures
+the transaction manager.
 
 The final line in the ``[pipeline:main]`` section is ``tutorial``, which
 refers to the ``[app:tutorial]`` section above it.  The ``[app:tutorial]``