Merge pull request #1954 from stevepiercy/master

wrap 79 cols

2 files changed, 291 insertions, 309 deletions

diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index b85c1f3d1..6a952dec9 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -190,7 +190,7 @@ WSGI Application Creation
 
 After configuring views and ending configuration, the script creates a WSGI
 *application* via the :meth:`pyramid.config.Configurator.make_wsgi_app` method.
- A call to ``make_wsgi_app`` implies that all configuration is finished
+A call to ``make_wsgi_app`` implies that all configuration is finished
 (meaning all method calls to the configurator, which sets up views and various
 other configuration settings, have been performed).  The ``make_wsgi_app``
 method returns a :term:`WSGI` application object that can be used by any WSGI
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index c9e89aff4..25f3931e9 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -3,25 +3,24 @@
 Creating a :app:`Pyramid` Project
 =================================
 
-As we saw in :ref:`firstapp_chapter`, it's possible to create a
-:app:`Pyramid` application completely manually.  However, it's usually more
-convenient to use a :term:`scaffold` to generate a basic :app:`Pyramid`
-:term:`project`.
+As we saw in :ref:`firstapp_chapter`, it's possible to create a :app:`Pyramid`
+application completely manually.  However, it's usually more convenient to use
+a :term:`scaffold` to generate a basic :app:`Pyramid` :term:`project`.
 
 A project is a directory that contains at least one Python :term:`package`.
 You'll use a scaffold to create a project, and you'll create your application
-logic within a package that lives inside the project.  Even if your
-application is extremely simple, it is useful to place code that drives the
-application within a package, because (1) a package is more easily extended
-with new code, and (2) an application that lives inside a package can also be
-distributed more easily than one which does not live within a package.
+logic within a package that lives inside the project.  Even if your application
+is extremely simple, it is useful to place code that drives the application
+within a package, because (1) a package is more easily extended with new code,
+and (2) an application that lives inside a package can also be distributed more
+easily than one which does not live within a package.
 
-:app:`Pyramid` comes with a variety of scaffolds that you can use to generate
-a project.  Each scaffold makes different configuration assumptions about
-what type of application you're trying to construct.
+:app:`Pyramid` comes with a variety of scaffolds that you can use to generate a
+project.  Each scaffold makes different configuration assumptions about what
+type of application you're trying to construct.
 
-These scaffolds are rendered using the ``pcreate`` command that is installed
-as part of Pyramid.
+These scaffolds are rendered using the ``pcreate`` command that is installed as
+part of Pyramid.
 
 .. index::
    single: scaffolds
@@ -34,11 +33,11 @@ as part of Pyramid.
 Scaffolds Included with :app:`Pyramid`
 --------------------------------------
 
-The convenience scaffolds included with :app:`Pyramid` differ from
-each other on a number of axes:
+The convenience scaffolds included with :app:`Pyramid` differ from each other
+on a number of axes:
 
-- the persistence mechanism they offer (no persistence mechanism,
-  :term:`ZODB`, or :term:`SQLAlchemy`)
+- the persistence mechanism they offer (no persistence mechanism, :term:`ZODB`,
+  or :term:`SQLAlchemy`)
 
 - the mechanism they use to map URLs to code (:term:`traversal` or :term:`URL
   dispatch`)
@@ -52,8 +51,7 @@ The included scaffolds are these:
   URL mapping via :term:`traversal` and persistence via :term:`ZODB`
 
 ``alchemy``
-  URL mapping via :term:`URL dispatch` and persistence via
-  :term:`SQLAlchemy`
+  URL mapping via :term:`URL dispatch` and persistence via :term:`SQLAlchemy`
 
 .. index::
    single: creating a project
@@ -64,9 +62,9 @@ The included scaffolds are these:
 Creating the Project
 --------------------
 
-In :ref:`installing_chapter`, you created a virtual Python environment via
-the ``virtualenv`` command.  To start a :app:`Pyramid` :term:`project`, use
-the ``pcreate`` command installed within the virtualenv.  We'll choose the
+In :ref:`installing_chapter`, you created a virtual Python environment via the
+``virtualenv`` command.  To start a :app:`Pyramid` :term:`project`, use the
+``pcreate`` command installed within the virtualenv.  We'll choose the
 ``starter`` scaffold for this purpose.  When we invoke ``pcreate``, it will
 create a directory that represents our project.
 
@@ -101,14 +99,14 @@ Here's sample output from a run of ``pcreate`` on UNIX for a project we name
    Running /Users/chrism/projects/pyramid/bin/python setup.py egg_info
 
 As a result of invoking the ``pcreate`` command, a directory named
-``MyProject`` is created.  That directory is a :term:`project` directory.
-The ``setup.py`` file in that directory can be used to distribute your
-application, or install your application for deployment or development.
+``MyProject`` is created.  That directory is a :term:`project` directory. The
+``setup.py`` file in that directory can be used to distribute your application,
+or install your application for deployment or development.
 
 A ``.ini`` file named ``development.ini`` will be created in the project
-directory.  You will use this ``.ini`` file to configure a server, to run
-your application, and to debug your application.  It contains configuration
-that enables an interactive debugger and settings optimized for development.
+directory.  You will use this ``.ini`` file to configure a server, to run your
+application, and to debug your application.  It contains configuration that
+enables an interactive debugger and settings optimized for development.
 
 Another ``.ini`` file named ``production.ini`` will also be created in the
 project directory.  It contains configuration that disables any interactive
@@ -117,28 +115,28 @@ number of debugging settings.  You can use this file to put your application
 into production.
 
 The ``MyProject`` project directory contains an additional subdirectory named
-``myproject`` (note the case difference) representing a Python
-:term:`package` which holds very simple :app:`Pyramid` sample code.  This is
-where you'll edit your application's Python code and templates.
-
-We created this project within an ``env`` virtualenv directory.  However,
-note that this is not mandatory.  The project directory can go more or less
-anywhere on your filesystem.  You don't need to put it in a special "web
-server" directory, and you don't need to put it within a virtualenv
-directory.  The author uses Linux mainly, and tends to put project
-directories which he creates within his ``~/projects`` directory.  On
-Windows, it's a good idea to put project directories within a directory that
-contains no space characters, so it's wise to *avoid* a path that contains,
-i.e., ``My Documents``.  As a result, the author, when he uses Windows, just
-puts his projects in ``C:\projects``.
+``myproject`` (note the case difference) representing a Python :term:`package`
+which holds very simple :app:`Pyramid` sample code.  This is where you'll edit
+your application's Python code and templates.
+
+We created this project within an ``env`` virtualenv directory.  However, note
+that this is not mandatory.  The project directory can go more or less anywhere
+on your filesystem.  You don't need to put it in a special "web server"
+directory, and you don't need to put it within a virtualenv directory.  The
+author uses Linux mainly, and tends to put project directories which he creates
+within his ``~/projects`` directory.  On Windows, it's a good idea to put
+project directories within a directory that contains no space characters, so
+it's wise to *avoid* a path that contains, i.e., ``My Documents``.  As a
+result, the author, when he uses Windows, just puts his projects in
+``C:\projects``.
 
 .. warning::
 
    You'll need to avoid using ``pcreate`` to create a project with the same
    name as a Python standard library component. In particular, this means you
-   should avoid using the names ``site`` or ``test``, both of which
-   conflict with Python standard library packages.  You should also avoid
-   using the name ``pyramid``, which will conflict with Pyramid itself.
+   should avoid using the names ``site`` or ``test``, both of which conflict
+   with Python standard library packages.  You should also avoid using the name
+   ``pyramid``, which will conflict with Pyramid itself.
 
 .. index::
    single: setup.py develop
@@ -153,10 +151,10 @@ newly created project directory and use the Python interpreter from the
 command ``python setup.py develop``
 
 The file named ``setup.py`` will be in the root of the pcreate-generated
-project directory.  The ``python`` you're invoking should be the one that
-lives in the ``bin`` (or ``Scripts`` on Windows) directory of your virtual
-Python environment.  Your terminal's current working directory *must* be the
-newly created project directory.
+project directory.  The ``python`` you're invoking should be the one that lives
+in the ``bin`` (or ``Scripts`` on Windows) directory of your virtual Python
+environment.  Your terminal's current working directory *must* be the newly
+created project directory.
 
 On UNIX:
 
@@ -181,10 +179,10 @@ Elided output from a run of this command on UNIX is shown below:
    ...
    Finished processing dependencies for MyProject==0.0
 
-This will install a :term:`distribution` representing your project
-into the virtual environment interpreter's library set so it can be
-found by ``import`` statements and by other console scripts such as
-``pserve``, ``pshell``, ``proutes``, and ``pviews``.
+This will install a :term:`distribution` representing your project into the
+virtual environment interpreter's library set so it can be found by ``import``
+statements and by other console scripts such as ``pserve``, ``pshell``,
+``proutes``, and ``pviews``.
 
 .. index::
    single: running tests
@@ -193,8 +191,8 @@ found by ``import`` statements and by other console scripts such as
 Running the Tests for Your Application
 --------------------------------------
 
-To run unit tests for your application, you should invoke them using the
-Python interpreter from the :term:`virtualenv` you created during
+To run unit tests for your application, you should invoke them using the Python
+interpreter from the :term:`virtualenv` you created during
 :ref:`installing_chapter` (the ``python`` command that lives in the ``bin``
 directory of your virtualenv).
 
@@ -278,12 +276,12 @@ Here's sample output from a run of ``pserve`` on UNIX:
 
 When you use ``pserve`` to start the application implied by the default
 rendering of a scaffold, it will respond to requests on *all* IP addresses
-possessed by your system, not just requests to ``localhost``.  This is what
-the ``0.0.0.0`` in ``serving on http://0.0.0.0:6543`` means.  The server will
-respond to requests made to ``127.0.0.1`` and on any external IP address.
-For example, your system might be configured to have an external IP address
-``192.168.1.50``.  If that's the case, if you use a browser running on the
-same system as Pyramid, it will be able to access the application via
+possessed by your system, not just requests to ``localhost``.  This is what the
+``0.0.0.0`` in ``serving on http://0.0.0.0:6543`` means.  The server will
+respond to requests made to ``127.0.0.1`` and on any external IP address. For
+example, your system might be configured to have an external IP address
+``192.168.1.50``.  If that's the case, if you use a browser running on the same
+system as Pyramid, it will be able to access the application via
 ``http://127.0.0.1:6543/`` as well as via ``http://192.168.1.50:6543/``.
 However, *other people* on other computers on the same network will also be
 able to visit your Pyramid application in their browser by visiting
@@ -305,28 +303,26 @@ example:
 You can change the port on which the server runs on by changing the same
 portion of the ``development.ini`` file.  For example, you can change the
 ``port = 6543`` line in the ``development.ini`` file's ``[server:main]``
-section to ``port = 8080`` to run the server on port 8080 instead of
-port 6543.
+section to ``port = 8080`` to run the server on port 8080 instead of port 6543.
 
 You can shut down a server started this way by pressing ``Ctrl-C`` (or
 ``Ctrl-Break`` on Windows).
 
 The default server used to run your Pyramid application when a project is
-created from a scaffold is named :term:`Waitress`.  This server is what
-prints the ``serving on...`` line when you run ``pserve``.  It's a good idea
-to use this server during development because it's very simple.  It can also
-be used for light production.  Setting your application up under a different
-server is not advised until you've done some development work under the
-default server, particularly if you're not yet experienced with Python web
-development.  Python web server setup can be complex, and you should get some
-confidence that your application works in a default environment before trying
-to optimize it or make it "more like production".  It's awfully easy to get
-sidetracked trying to set up a non-default server for hours without actually
-starting to do any development.  One of the nice things about Python web
-servers is that they're largely interchangeable, so if your application works
-under the default server, it will almost certainly work under any other
-server in production if you eventually choose to use a different one.  Don't
-worry about it right now.
+created from a scaffold is named :term:`Waitress`.  This server is what prints
+the ``serving on...`` line when you run ``pserve``.  It's a good idea to use
+this server during development because it's very simple.  It can also be used
+for light production.  Setting your application up under a different server is
+not advised until you've done some development work under the default server,
+particularly if you're not yet experienced with Python web development.  Python
+web server setup can be complex, and you should get some confidence that your
+application works in a default environment before trying to optimize it or make
+it "more like production".  It's awfully easy to get sidetracked trying to set
+up a non-default server for hours without actually starting to do any
+development.  One of the nice things about Python web servers is that they're
+largely interchangeable, so if your application works under the default server,
+it will almost certainly work under any other server in production if you
+eventually choose to use a different one.  Don't worry about it right now.
 
 For more detailed information about the startup process, see
 :ref:`startup_chapter`.  For more information about environment variables and
@@ -338,10 +334,10 @@ configuration file settings that influence startup and runtime behavior, see
 Reloading Code
 ~~~~~~~~~~~~~~
 
-During development, it's often useful to run ``pserve`` using its
-``--reload`` option.  When ``--reload`` is passed to ``pserve``, changes to
-any Python module your project uses will cause the server to restart.  This
-typically makes development easier, as changes to Python code made within a
+During development, it's often useful to run ``pserve`` using its ``--reload``
+option.  When ``--reload`` is passed to ``pserve``, changes to any Python
+module your project uses will cause the server to restart.  This typically
+makes development easier, as changes to Python code made within a
 :app:`Pyramid` application is not put into effect until the server restarts.
 
 For example, on UNIX:
@@ -364,10 +360,10 @@ files, you'll see the server restart automatically:
    serving on http://0.0.0.0:6543
 
 Changes to template files (such as ``.pt`` or ``.mak`` files) won't cause the
-server to restart.  Changes to template files don't require a server restart
-as long as the ``pyramid.reload_templates`` setting in the
-``development.ini`` file is ``true``.  Changes made to template files when
-this setting is true will take effect immediately without a server restart.
+server to restart.  Changes to template files don't require a server restart as
+long as the ``pyramid.reload_templates`` setting in the ``development.ini``
+file is ``true``.  Changes made to template files when this setting is true
+will take effect immediately without a server restart.
 
 .. index::
    single: WSGI
@@ -396,22 +392,21 @@ The Debug Toolbar
 
 If you click on the :app:`Pyramid` logo at the top right of the page, a new
 target window will open to present a debug toolbar that provides various
-niceties while you're developing.  This logo will float above every HTML
-page served by :app:`Pyramid` while you develop an application, and allows
-you to show the toolbar as necessary.
+niceties while you're developing.  This logo will float above every HTML page
+served by :app:`Pyramid` while you develop an application, and allows you to
+show the toolbar as necessary.
 
 .. image:: project-debug.png
 
-If you don't see the Pyramid logo on the top right of the page, it means
-you're browsing from a system that does not have debugging access.  By
-default, for security reasons, only a browser originating from ``localhost``
-(``127.0.0.1``) can see the debug toolbar.  To allow your browser on a
-remote system to access the server, add a line within the ``[app:main]``
-section of the ``development.ini`` file in the form ``debugtoolbar.hosts = X
-.X.X.X``.  For example, if your Pyramid application is running on a remote
-system, and you're browsing from a host with the IP address ``192.168.1.1``,
-you'd add something like this to enable the toolbar when your system
-contacts Pyramid:
+If you don't see the Pyramid logo on the top right of the page, it means you're
+browsing from a system that does not have debugging access.  By default, for
+security reasons, only a browser originating from ``localhost`` (``127.0.0.1``)
+can see the debug toolbar.  To allow your browser on a remote system to access
+the server, add a line within the ``[app:main]`` section of the
+``development.ini`` file in the form ``debugtoolbar.hosts = X .X.X.X``.  For
+example, if your Pyramid application is running on a remote system, and you're
+browsing from a host with the IP address ``192.168.1.1``, you'd add something
+like this to enable the toolbar when your system contacts Pyramid:
 
 .. code-block:: ini
 
@@ -423,9 +418,9 @@ For more information about what the debug toolbar allows you to do, see `the
 documentation for pyramid_debugtoolbar
 <http://docs.pylonsproject.org/projects/pyramid_debugtoolbar/en/latest/>`_.
 
-The debug toolbar will not be shown (and all debugging will be turned off)
-when you use the ``production.ini`` file instead of the ``development.ini``
-ini file to run the application.
+The debug toolbar will not be shown (and all debugging will be turned off) when
+you use the ``production.ini`` file instead of the ``development.ini`` ini file
+to run the application.
 
 You can also turn the debug toolbar off by editing ``development.ini`` and
 commenting out a line.  For example, instead of:
@@ -451,9 +446,9 @@ Put a hash mark at the beginning of the ``pyramid_debugtoolbar`` line:
 Then restart the application to see that the toolbar has been turned off.
 
 Note that if you comment out the ``pyramid_debugtoolbar`` line, the ``#``
-*must* be in the first column.  If you put it anywhere else, and then
-attempt to restart the application, you'll receive an error that ends
-something like this:
+*must* be in the first column.  If you put it anywhere else, and then attempt
+to restart the application, you'll receive an error that ends something like
+this:
 
 .. code-block:: text
 
@@ -471,8 +466,7 @@ which contains a Python :term:`package`.  The package is *also* named
 contains a package that shares its name except for case.
 
 All :app:`Pyramid` ``pcreate``-generated projects share a similar structure.
-The ``MyProject`` project we've generated has the following directory
-structure:
+The ``MyProject`` project we've generated has the following directory structure:
 
 .. code-block:: text
 
@@ -498,29 +492,29 @@ structure:
 The ``MyProject`` :term:`Project`
 ---------------------------------
 
-The ``MyProject`` :term:`project` directory is the distribution and
-deployment wrapper for your application.  It contains both the ``myproject``
+The ``MyProject`` :term:`project` directory is the distribution and deployment
+wrapper for your application.  It contains both the ``myproject``
 :term:`package` representing your application as well as files used to
 describe, run, and test your application.
 
-#. ``CHANGES.txt`` describes the changes you've made to the application.  It
-   is conventionally written in :term:`ReStructuredText` format.
+#. ``CHANGES.txt`` describes the changes you've made to the application.  It is
+   conventionally written in :term:`ReStructuredText` format.
 
 #. ``README.txt`` describes the application in general.  It is conventionally
    written in :term:`ReStructuredText` format.
 
-#. ``development.ini`` is a :term:`PasteDeploy` configuration file that can
-   be used to execute your application during development.
+#. ``development.ini`` is a :term:`PasteDeploy` configuration file that can be
+   used to execute your application during development.
 
-#. ``production.ini`` is a :term:`PasteDeploy` configuration file that can
-   be used to execute your application in a production configuration.
+#. ``production.ini`` is a :term:`PasteDeploy` configuration file that can be
+   used to execute your application in a production configuration.
 
 #. ``MANIFEST.in`` is a :term:`distutils` "manifest" file, naming which files
    should be included in a source distribution of the package when ``python
    setup.py sdist`` is run.
 
-#. ``setup.py`` is the file you'll use to test and distribute your
-   application.  It is a standard :term:`setuptools` ``setup.py`` file.
+#. ``setup.py`` is the file you'll use to test and distribute your application.
+   It is a standard :term:`setuptools` ``setup.py`` file.
 
 .. index::
    single: PasteDeploy
@@ -531,9 +525,9 @@ describe, run, and test your application.
 ``development.ini``
 ~~~~~~~~~~~~~~~~~~~
 
-The ``development.ini`` file is a :term:`PasteDeploy` configuration file.
-Its purpose is to specify an application to run when you invoke ``pserve``,
-as well as the deployment settings provided to that application.
+The ``development.ini`` file is a :term:`PasteDeploy` configuration file. Its
+purpose is to specify an application to run when you invoke ``pserve``, as well
+as the deployment settings provided to that application.
 
 The generated ``development.ini`` file looks like so:
 
@@ -542,33 +536,32 @@ The generated ``development.ini`` file looks like so:
    :linenos:
 
 This file contains several sections including ``[app:main]``,
-``[server:main]``, and several other sections related to logging
-configuration.
+``[server:main]``, and several other sections related to logging configuration.
 
 The ``[app:main]`` section represents configuration for your :app:`Pyramid`
-application.  The ``use`` setting is the only setting required to be present
-in the ``[app:main]`` section.  Its default value, ``egg:MyProject``,
-indicates that our MyProject project contains the application that should be
-served.  Other settings added to this section are passed as keyword arguments
-to the function named ``main`` in our package's ``__init__.py`` module.  You
-can provide startup-time configuration parameters to your application by
-adding more settings to this section.
+application.  The ``use`` setting is the only setting required to be present in
+the ``[app:main]`` section.  Its default value, ``egg:MyProject``, indicates
+that our MyProject project contains the application that should be served. 
+Other settings added to this section are passed as keyword arguments to the
+function named ``main`` in our package's ``__init__.py`` module.  You can
+provide startup-time configuration parameters to your application by adding
+more settings to this section.
 
 .. seealso:: See :ref:`pastedeploy_entry_points` for more information about the
    meaning of the ``use = egg:MyProject`` value in this section.
 
 The ``pyramid.reload_templates`` setting in the ``[app:main]`` section is a
 :app:`Pyramid`-specific setting which is passed into the framework.  If it
-exists, and its value is ``true``, supported template changes will not
-require an application restart to be detected.  See
-:ref:`reload_templates_section` for more information.
+exists, and its value is ``true``, supported template changes will not require
+an application restart to be detected.  See :ref:`reload_templates_section` for
+more information.
 
 .. warning:: The ``pyramid.reload_templates`` option should be turned off for
    production applications, as template rendering is slowed when it is turned
    on.
 
-The ``pyramid.includes`` setting in the ``[app:main]`` section tells Pyramid
-to "include" configuration from another package.  In this case, the line
+The ``pyramid.includes`` setting in the ``[app:main]`` section tells Pyramid to
+"include" configuration from another package.  In this case, the line
 ``pyramid.includes = pyramid_debugtoolbar`` tells Pyramid to include
 configuration from the ``pyramid_debugtoolbar`` package.  This turns on a
 debugging panel in development mode which can be opened by clicking on the
@@ -576,14 +569,14 @@ debugging panel in development mode which can be opened by clicking on the
 toolbar will also make it possible to interactively debug exceptions when an
 error occurs.
 
-Various other settings may exist in this section having to do with debugging
-or influencing runtime behavior of a :app:`Pyramid` application.  See
+Various other settings may exist in this section having to do with debugging or
+influencing runtime behavior of a :app:`Pyramid` application.  See
 :ref:`environment_chapter` for more information about these settings.
 
 The name ``main`` in ``[app:main]`` signifies that this is the default
 application run by ``pserve`` when it is invoked against this configuration
-file.  The name ``main`` is a convention used by PasteDeploy signifying that
-it is the default application.
+file.  The name ``main`` is a convention used by PasteDeploy signifying that it
+is the default application.
 
 The ``[server:main]`` section of the configuration file configures a WSGI
 server which listens on TCP port 6543.  It is configured to listen on all
@@ -594,14 +587,12 @@ access to your system can see your Pyramid application.
 
 The sections that live between the markers ``# Begin logging configuration``
 and ``# End logging configuration`` represent Python's standard library
-:mod:`logging` module configuration for your application.  The sections
-between these two markers are passed to the `logging module's config file
-configuration engine
-<http://docs.python.org/howto/logging.html#configuring-logging>`_ when the
-``pserve`` or ``pshell`` commands are executed.  The default configuration
-sends application logging output to the standard error output of your
-terminal.  For more information about logging configuration, see
-:ref:`logging_chapter`.
+:mod:`logging` module configuration for your application.  The sections between
+these two markers are passed to the `logging module's config file configuration
+engine <http://docs.python.org/howto/logging.html#configuring-logging>`_ when
+the ``pserve`` or ``pshell`` commands are executed.  The default configuration
+sends application logging output to the standard error output of your terminal.
+For more information about logging configuration, see :ref:`logging_chapter`.
 
 See the :term:`PasteDeploy` documentation for more information about other
 types of things you can put into this ``.ini`` file, such as other
@@ -614,20 +605,20 @@ implementations.
 ``production.ini``
 ~~~~~~~~~~~~~~~~~~
 
-The ``production.ini`` file is a :term:`PasteDeploy` configuration file with
-a purpose much like that of ``development.ini``.  However, it disables the
-debug toolbar, and filters all log messages except those above the WARN
-level.  It also turns off template development options such that templates
-are not automatically reloaded when changed, and turns off all debugging
-options.  This file is appropriate to use instead of ``development.ini`` when
-you put your application into production.
+The ``production.ini`` file is a :term:`PasteDeploy` configuration file with a
+purpose much like that of ``development.ini``.  However, it disables the debug
+toolbar, and filters all log messages except those above the WARN level.  It
+also turns off template development options such that templates are not
+automatically reloaded when changed, and turns off all debugging options.  This
+file is appropriate to use instead of ``development.ini`` when you put your
+application into production.
 
 It's important to use ``production.ini`` (and *not* ``development.ini``) to
 benchmark your application and put it into production.  ``development.ini``
 configures your system with a debug toolbar that helps development, but the
 inclusion of this toolbar slows down page rendering times by over an order of
-magnitude.  The debug toolbar is also a potential security risk if you have
-it configured incorrectly.
+magnitude.  The debug toolbar is also a potential security risk if you have it
+configured incorrectly.
 
 .. index::
    single: MANIFEST.in
@@ -639,42 +630,40 @@ The ``MANIFEST.in`` file is a :term:`distutils` configuration file which
 specifies the non-Python files that should be included when a
 :term:`distribution` of your Pyramid project is created when you run ``python
 setup.py sdist``.  Due to the information contained in the default
-``MANIFEST.in``, an sdist of your Pyramid project will include ``.txt``
-files, ``.ini`` files, ``.rst`` files, graphics files, and template files, as
-well as ``.py`` files.  See
+``MANIFEST.in``, an sdist of your Pyramid project will include ``.txt`` files,
+``.ini`` files, ``.rst`` files, graphics files, and template files, as well as
+``.py`` files.  See
 http://docs.python.org/distutils/sourcedist.html#the-manifest-in-template for
 more information about the syntax and usage of ``MANIFEST.in``.
 
-Without the presence of a ``MANIFEST.in`` file or without checking your
-source code into a version control repository, ``setup.py sdist`` places only
-*Python source files* (files ending with a ``.py`` extension) into tarballs
-generated by ``python setup.py sdist``.  This means, for example, if your
-project was not checked into a setuptools-compatible source control system,
-and your project directory didn't contain a ``MANIFEST.in`` file that told
-the ``sdist`` machinery to include ``*.pt`` files, the
-``myproject/templates/mytemplate.pt`` file would not be included in the
-generated tarball.
-
-Projects generated by Pyramid scaffolds include a default ``MANIFEST.in``
-file.  The ``MANIFEST.in`` file contains declarations which tell it to
-include files like ``*.pt``, ``*.css`` and ``*.js`` in the generated tarball.
-If you include files with extensions other than the files named in the
-project's ``MANIFEST.in`` and you don't make use of a setuptools-compatible
-version control system, you'll need to edit the ``MANIFEST.in`` file and
-include the statements necessary to include your new files.  See
-http://docs.python.org/distutils/sourcedist.html#principle for more
-information about how to do this.
-
-You can also delete ``MANIFEST.in`` from your project and rely on a
-setuptools feature which simply causes all files checked into a version
-control system to be put into the generated tarball.  To allow this to
-happen, check all the files that you'd like to be distributed along with your
-application's Python files into Subversion.  After you do this, when you
-rerun ``setup.py sdist``, all files checked into the version control system
-will be included in the tarball.  If you don't use Subversion, and instead
-use a different version control system, you may need to install a setuptools
-add-on such as ``setuptools-git`` or ``setuptools-hg`` for this behavior to
-work properly.
+Without the presence of a ``MANIFEST.in`` file or without checking your source
+code into a version control repository, ``setup.py sdist`` places only *Python
+source files* (files ending with a ``.py`` extension) into tarballs generated
+by ``python setup.py sdist``.  This means, for example, if your project was not
+checked into a setuptools-compatible source control system, and your project
+directory didn't contain a ``MANIFEST.in`` file that told the ``sdist``
+machinery to include ``*.pt`` files, the ``myproject/templates/mytemplate.pt``
+file would not be included in the generated tarball.
+
+Projects generated by Pyramid scaffolds include a default ``MANIFEST.in`` file.
+The ``MANIFEST.in`` file contains declarations which tell it to include files
+like ``*.pt``, ``*.css`` and ``*.js`` in the generated tarball. If you include
+files with extensions other than the files named in the project's
+``MANIFEST.in`` and you don't make use of a setuptools-compatible version
+control system, you'll need to edit the ``MANIFEST.in`` file and include the
+statements necessary to include your new files.  See
+http://docs.python.org/distutils/sourcedist.html#principle for more information
+about how to do this.
+
+You can also delete ``MANIFEST.in`` from your project and rely on a setuptools
+feature which simply causes all files checked into a version control system to
+be put into the generated tarball.  To allow this to happen, check all the
+files that you'd like to be distributed along with your application's Python
+files into Subversion.  After you do this, when you rerun ``setup.py sdist``,
+all files checked into the version control system will be included in the
+tarball.  If you don't use Subversion, and instead use a different version
+control system, you may need to install a setuptools add-on such as
+``setuptools-git`` or ``setuptools-hg`` for this behavior to work properly.
 
 .. index::
    single: setup.py
@@ -688,11 +677,11 @@ testing, packaging, and distributing your application.
 
 .. note::
 
-    ``setup.py`` is the de facto standard which Python developers use to
-    distribute their reusable code.  You can read more about ``setup.py`` files
-    and their usage in the `Setuptools documentation
-    <http://peak.telecommunity.com/DevCenter/setuptools>`_ and `The
-    Hitchhiker's Guide to Packaging <http://guide.python-distribute.org/>`_.
+   ``setup.py`` is the de facto standard which Python developers use to
+   distribute their reusable code.  You can read more about ``setup.py`` files
+   and their usage in the `Setuptools documentation
+   <http://peak.telecommunity.com/DevCenter/setuptools>`_ and `The Hitchhiker's
+   Guide to Packaging <http://guide.python-distribute.org/>`_.
 
 Our generated ``setup.py`` looks like this:
 
@@ -701,47 +690,47 @@ Our generated ``setup.py`` looks like this:
    :linenos:
 
 The ``setup.py`` file calls the setuptools ``setup`` function, which does
-various things depending on the arguments passed to ``setup.py`` on the
-command line.
+various things depending on the arguments passed to ``setup.py`` on the command
+line.
 
-Within the arguments to this function call, information about your
-application is kept.  While it's beyond the scope of this documentation to
-explain everything about setuptools setup files, we'll provide a whirlwind
-tour of what exists in this file in this section.
+Within the arguments to this function call, information about your application
+is kept.  While it's beyond the scope of this documentation to explain
+everything about setuptools setup files, we'll provide a whirlwind tour of what
+exists in this file in this section.
 
 Your application's name can be any string; it is specified in the ``name``
 field.  The version number is specified in the ``version`` value.  A short
-description is provided in the ``description`` field.  The
-``long_description`` is conventionally the content of the README and CHANGES
-file appended together.  The ``classifiers`` field is a list of `Trove
+description is provided in the ``description`` field.  The ``long_description``
+is conventionally the content of the README and CHANGES file appended together.
+The ``classifiers`` field is a list of `Trove
 <http://pypi.python.org/pypi?%3Aaction=list_classifiers>`_ classifiers
 describing your application.  ``author`` and ``author_email`` are text fields
 which probably don't need any description.  ``url`` is a field that should
-point at your application project's URL (if any).
-``packages=find_packages()`` causes all packages within the project to be
-found when packaging the application.  ``include_package_data`` will include
-non-Python files when the application is packaged if those files are checked
-into version control.  ``zip_safe`` indicates that this package is not safe
-to use as a zipped egg; instead it will always unpack as a directory, which
-is more convenient.  ``install_requires`` and ``tests_require`` indicate that
-this package depends on the ``pyramid`` package.  ``test_suite`` points at
-the package for our application, which means all tests found in the package
-will be run when ``setup.py test`` is invoked.  We examined ``entry_points``
-in our discussion of the ``development.ini`` file; this file defines the
-``main`` entry point that represents our project's application.
-
-Usually you only need to think about the contents of the ``setup.py`` file
-when distributing your application to other people, when adding Python
-package dependencies, or when versioning your application for your own use.
-For fun, you can try this command now:
+point at your application project's URL (if any). ``packages=find_packages()``
+causes all packages within the project to be found when packaging the
+application.  ``include_package_data`` will include non-Python files when the
+application is packaged if those files are checked into version control. 
+``zip_safe`` indicates that this package is not safe to use as a zipped egg;
+instead it will always unpack as a directory, which is more convenient. 
+``install_requires`` and ``tests_require`` indicate that this package depends
+on the ``pyramid`` package.  ``test_suite`` points at the package for our
+application, which means all tests found in the package will be run when
+``setup.py test`` is invoked.  We examined ``entry_points`` in our discussion
+of the ``development.ini`` file; this file defines the ``main`` entry point
+that represents our project's application.
+
+Usually you only need to think about the contents of the ``setup.py`` file when
+distributing your application to other people, when adding Python package
+dependencies, or when versioning your application for your own use. For fun,
+you can try this command now:
 
 .. code-block:: text
 
    $ $VENV/bin/python setup.py sdist
 
-This will create a tarball of your application in a ``dist`` subdirectory
-named ``MyProject-0.1.tar.gz``.  You can send this tarball to other people
-who want to install and use your application.
+This will create a tarball of your application in a ``dist`` subdirectory named
+``MyProject-0.1.tar.gz``.  You can send this tarball to other people who want
+to install and use your application.
 
 .. index::
    single: package
@@ -752,19 +741,17 @@ The ``myproject`` :term:`Package`
 The ``myproject`` :term:`package` lives inside the ``MyProject``
 :term:`project`.  It contains:
 
-#. An ``__init__.py`` file signifies that this is a Python :term:`package`.
-   It also contains code that helps users run the application, including a
+#. An ``__init__.py`` file signifies that this is a Python :term:`package`. It
+   also contains code that helps users run the application, including a
    ``main`` function which is used as a entry point for commands such as
    ``pserve``, ``pshell``, ``pviews``, and others.
 
-#. A ``templates`` directory, which contains :term:`Chameleon` (or
-   other types of) templates.
+#. A ``templates`` directory, which contains :term:`Chameleon` (or other types
+   of) templates.
 
-#. A ``tests.py`` module, which contains unit test code for the
-   application.
+#. A ``tests.py`` module, which contains unit test code for the application.
 
-#. A ``views.py`` module, which contains view code for the
-   application.
+#. A ``views.py`` module, which contains view code for the application.
 
 These are purely conventions established by the scaffold. :app:`Pyramid`
 doesn't insist that you name things in any particular way. However, it's
@@ -803,11 +790,11 @@ also informs Python that the directory which contains it is a *package*.
    specify renderers with the ``.pt`` extension.
 
    Line 9 registers a static view, which will serve up the files from the
-   ``myproject:static`` :term:`asset specification` (the ``static``
-   directory of the ``myproject`` package).
+   ``myproject:static`` :term:`asset specification` (the ``static`` directory
+   of the ``myproject`` package).
 
-   Line 10 adds a :term:`route` to the configuration.  This route is later
-   used by a view in the ``views`` module.
+   Line 10 adds a :term:`route` to the configuration.  This route is later used
+   by a view in the ``views`` module.
 
    Line 11 calls ``config.scan()``, which picks up view registrations declared
    elsewhere in the package (in this case, in the ``views.py`` module).
@@ -823,38 +810,37 @@ also informs Python that the directory which contains it is a *package*.
 
 Much of the heavy lifting in a :app:`Pyramid` application is done by *view
 callables*.  A :term:`view callable` is the main tool of a :app:`Pyramid` web
-application developer; it is a bit of code which accepts a :term:`request`
-and which returns a :term:`response`.
+application developer; it is a bit of code which accepts a :term:`request` and
+which returns a :term:`response`.
 
 .. literalinclude:: MyProject/myproject/views.py
    :language: python
    :linenos:
 
 Lines 4-6 define and register a :term:`view callable` named ``my_view``.  The
-function named ``my_view`` is decorated with a ``view_config`` decorator
-(which is processed by the ``config.scan()`` line in our ``__init__.py``).
-The view_config decorator asserts that this view be found when a
-:term:`route` named ``home`` is matched.  In our case, because our
-``__init__.py`` maps the route named ``home`` to the URL pattern ``/``, this
-route will match when a visitor visits the root URL.  The view_config
-decorator also names a ``renderer``, which in this case is a template that
-will be used to render the result of the view callable.  This particular view
-declaration points at ``templates/mytemplate.pt``, which is an :term:`asset
-specification` that specifies the ``mytemplate.pt`` file within the
-``templates`` directory of the ``myproject`` package.  The asset
-specification could have also been specified as
-``myproject:templates/mytemplate.pt``; the leading package name and colon is
+function named ``my_view`` is decorated with a ``view_config`` decorator (which
+is processed by the ``config.scan()`` line in our ``__init__.py``). The
+view_config decorator asserts that this view be found when a :term:`route`
+named ``home`` is matched.  In our case, because our ``__init__.py`` maps the
+route named ``home`` to the URL pattern ``/``, this route will match when a
+visitor visits the root URL.  The view_config decorator also names a
+``renderer``, which in this case is a template that will be used to render the
+result of the view callable.  This particular view declaration points at
+``templates/mytemplate.pt``, which is an :term:`asset specification` that
+specifies the ``mytemplate.pt`` file within the ``templates`` directory of the
+``myproject`` package.  The asset specification could have also been specified
+as ``myproject:templates/mytemplate.pt``; the leading package name and colon is
 optional.  The template file pointed to is a :term:`Chameleon` ZPT template
 file (``templates/my_template.pt``).
 
 This view callable function is handed a single piece of information: the
-:term:`request`.  The *request* is an instance of the :term:`WebOb`
-``Request`` class representing the browser's request to our server.
+:term:`request`.  The *request* is an instance of the :term:`WebOb` ``Request``
+class representing the browser's request to our server.
 
 This view is configured to invoke a :term:`renderer` on a template.  The
 dictionary the view returns (on line 6) provides the value the renderer
-substitutes into the template when generating HTML.  The renderer then
-returns the HTML in a :term:`response`.
+substitutes into the template when generating HTML.  The renderer then returns
+the HTML in a :term:`response`.
 
 .. note:: Dictionaries provide values to :term:`template`\s.
 
@@ -863,8 +849,8 @@ returns the HTML in a :term:`response`.
    <MyProject_ini_logging>` to aid debugging.  If an exception is raised,
    uncaught tracebacks are displayed after the startup messages on :ref:`the
    console running the server <running_the_project_application>`. Also
-   ``print()`` statements may be inserted into the application for debugging
-   to send output to this console.
+   ``print()`` statements may be inserted into the application for debugging to
+   send output to this console.
 
 .. note:: ``development.ini`` has a setting that controls how templates are
    reloaded, ``pyramid.reload_templates``.
@@ -873,14 +859,14 @@ returns the HTML in a :term:`response`.
      templates automatically reload without a server restart.  This is
      convenient while developing, but slows template rendering speed.
 
-   - When set to ``False`` (the default value), changing templates requires
-     a server restart to reload them.  Production applications should use
+   - When set to ``False`` (the default value), changing templates requires a
+     server restart to reload them.  Production applications should use
      ``pyramid.reload_templates = False``.
 
 .. seealso::
 
-    See also :ref:`views_which_use_a_renderer` for more information
-    about how views, renderers, and templates relate and cooperate.
+    See also :ref:`views_which_use_a_renderer` for more information about how
+    views, renderers, and templates relate and cooperate.
 
 .. seealso::
 
@@ -908,8 +894,8 @@ template.  It includes CSS and images.
 
 This is the single :term:`Chameleon` template that exists in the project.  Its
 contents are too long to show here, but it displays a default page when
-rendered.  It is referenced by the call to ``@view_config`` as the
-``renderer`` of the ``my_view`` view callable in the ``views.py`` file.  See
+rendered.  It is referenced by the call to ``@view_config`` as the ``renderer``
+of the ``my_view`` view callable in the ``views.py`` file.  See
 :ref:`views_which_use_a_renderer` for more information about renderers.
 
 Templates are accessed and used by view configurations and sometimes by view
@@ -930,10 +916,9 @@ The ``tests.py`` module includes unit tests for your application.
    :linenos:
 
 This sample ``tests.py`` file has a single unit test defined within it.  This
-test is executed when you run ``python setup.py test``.  You may add more
-tests here as you build your application.  You are not required to write
-tests to use :app:`Pyramid`. This file is simply provided for convenience and
-example.
+test is executed when you run ``python setup.py test``.  You may add more tests
+here as you build your application.  You are not required to write tests to use
+:app:`Pyramid`. This file is simply provided for convenience and example.
 
 See :ref:`testing_chapter` for more information about writing :app:`Pyramid`
 unit tests.
@@ -947,28 +932,27 @@ Modifying Package Structure
 ---------------------------
 
 It is best practice for your application's code layout to not stray too much
-from accepted Pyramid scaffold defaults.  If you refrain from changing
-things very much, other Pyramid coders will be able to more quickly
-understand your application.  However, the code layout choices made for you
-by a scaffold are in no way magical or required.  Despite the choices
-made for you by any scaffold, you can decide to lay your code out any
-way you see fit.
+from accepted Pyramid scaffold defaults.  If you refrain from changing things
+very much, other Pyramid coders will be able to more quickly understand your
+application.  However, the code layout choices made for you by a scaffold are
+in no way magical or required.  Despite the choices made for you by any
+scaffold, you can decide to lay your code out any way you see fit.
 
 For example, the configuration method named
 :meth:`~pyramid.config.Configurator.add_view` requires you to pass a
 :term:`dotted Python name` or a direct object reference as the class or
-function to be used as a view.  By default, the ``starter`` scaffold would
-have you add view functions to the ``views.py`` module in your package.
-However, you might be more comfortable creating a ``views`` *directory*, and
-adding a single file for each view.
+function to be used as a view.  By default, the ``starter`` scaffold would have
+you add view functions to the ``views.py`` module in your package. However, you
+might be more comfortable creating a ``views`` *directory*, and adding a single
+file for each view.
 
 If your project package name was ``myproject`` and you wanted to arrange all
 your views in a Python subpackage within the ``myproject`` :term:`package`
 named ``views`` instead of within a single ``views.py`` file, you might do the
 following.
 
-- Create a ``views`` directory inside your ``myproject`` package directory
-  (the same directory which holds ``views.py``).
+- Create a ``views`` directory inside your ``myproject`` package directory (the
+  same directory which holds ``views.py``).
 
 - Create a file within the new ``views`` directory named ``__init__.py``.  (It
   can be empty.  This just tells Python that the ``views`` directory is a
@@ -980,20 +964,19 @@ following.
   specification` values in ``blog.py`` must now be fully qualified with the
   project's package name (``myproject:templates/blog.pt``).
 
-You can then continue to add view callable functions to the ``blog.py``
-module, but you can also add other ``.py`` files which contain view callable
-functions to the ``views`` directory.  As long as you use the
-``@view_config`` directive to register views in conjunction with
-``config.scan()``, they will be picked up automatically when the application is
-restarted.
+You can then continue to add view callable functions to the ``blog.py`` module,
+but you can also add other ``.py`` files which contain view callable functions
+to the ``views`` directory.  As long as you use the ``@view_config`` directive
+to register views in conjunction with ``config.scan()``, they will be picked up
+automatically when the application is restarted.
 
 Using the Interactive Shell
 ---------------------------
 
 It is possible to use the ``pshell`` command to load a Python interpreter
-prompt with a similar configuration as would be loaded if you were running
-your Pyramid application via ``pserve``.  This can be a useful debugging tool.
-See :ref:`interactive_shell` for more details.
+prompt with a similar configuration as would be loaded if you were running your
+Pyramid application via ``pserve``.  This can be a useful debugging tool. See
+:ref:`interactive_shell` for more details.
 
 .. _what_is_this_pserve_thing:
 
@@ -1022,30 +1005,29 @@ restarting of the server when code changes.
 Using an Alternate WSGI Server
 ------------------------------
 
-Pyramid scaffolds generate projects which use the :term:`Waitress` WSGI
-server.  Waitress is a server that is suited for development and light
-production usage.  It's not the fastest nor the most featureful WSGI server.
-Instead, its main feature is that it works on all platforms that Pyramid
-needs to run on, making it a good choice as a default server from the
-perspective of Pyramid's developers.
+Pyramid scaffolds generate projects which use the :term:`Waitress` WSGI server.
+Waitress is a server that is suited for development and light production
+usage.  It's not the fastest nor the most featureful WSGI server. Instead, its
+main feature is that it works on all platforms that Pyramid needs to run on,
+making it a good choice as a default server from the perspective of Pyramid's
+developers.
 
 Any WSGI server is capable of running a :app:`Pyramid` application.  But we
-suggest you stick with the default server for development, and that you wait
-to investigate other server options until you're ready to deploy your
-application to production.  Unless for some reason you need to develop on a
-non-local system, investigating alternate server options is usually a
-distraction until you're ready to deploy.  But we recommend developing using
-the default configuration on a local system that you have complete control
-over; it will provide the best development experience.
+suggest you stick with the default server for development, and that you wait to
+investigate other server options until you're ready to deploy your application
+to production.  Unless for some reason you need to develop on a non-local
+system, investigating alternate server options is usually a distraction until
+you're ready to deploy.  But we recommend developing using the default
+configuration on a local system that you have complete control over; it will
+provide the best development experience.
 
 One popular production alternative to the default Waitress server is
-:term:`mod_wsgi`. You can use mod_wsgi to serve your :app:`Pyramid`
-application using the Apache web server rather than any "pure-Python" server
-like Waitress.  It is fast and featureful.  See :ref:`modwsgi_tutorial` for
-details.
+:term:`mod_wsgi`. You can use mod_wsgi to serve your :app:`Pyramid` application
+using the Apache web server rather than any "pure-Python" server like Waitress.
+It is fast and featureful.  See :ref:`modwsgi_tutorial` for details.
 
 Another good production alternative is :term:`Green Unicorn` (aka
-``gunicorn``).  It's faster than Waitress and slightly easier to configure
-than mod_wsgi, although it depends, in its default configuration, on having a
-buffering HTTP proxy in front of it.  It does not, as of this writing, work
-on Windows.
+``gunicorn``).  It's faster than Waitress and slightly easier to configure than
+mod_wsgi, although it depends, in its default configuration, on having a
+buffering HTTP proxy in front of it.  It does not, as of this writing, work on
+Windows.