18 files changed, 621 insertions, 350 deletions

diff --git a/docs/narr/MyProject/myproject/templates/mytemplate.pt b/docs/narr/MyProject/myproject/templates/mytemplate.pt
index d1af4f42c..e6b00a145 100644
--- a/docs/narr/MyProject/myproject/templates/mytemplate.pt
+++ b/docs/narr/MyProject/myproject/templates/mytemplate.pt
@@ -50,7 +50,7 @@
         </div>
         <div class="row">
           <div class="copyright">
-            Copyright © Pylons Project
+            Copyright &copy; Pylons Project
           </div>
         </div>
       </div>
diff --git a/docs/narr/MyProject/myproject/tests.py b/docs/narr/MyProject/myproject/tests.py
index 64dcab1d5..8c60407e5 100644
--- a/docs/narr/MyProject/myproject/tests.py
+++ b/docs/narr/MyProject/myproject/tests.py
@@ -15,3 +15,40 @@ class ViewTests(unittest.TestCase):
         request = testing.DummyRequest()
         info = my_view(request)
         self.assertEqual(info['project'], 'MyProject')
+
+class ViewIntegrationTests(unittest.TestCase):
+    def setUp(self):
+        """ This sets up the application registry with the
+        registrations your application declares in its ``includeme``
+        function.
+        """
+        self.config = testing.setUp()
+        self.config.include('myproject')
+
+    def tearDown(self):
+        """ Clear out the application registry """
+        testing.tearDown()
+
+    def test_my_view(self):
+        from myproject.views import my_view
+        request = testing.DummyRequest()
+        result = my_view(request)
+        self.assertEqual(result.status, '200 OK')
+        body = result.app_iter[0]
+        self.assertTrue('Welcome to' in body)
+        self.assertEqual(len(result.headerlist), 2)
+        self.assertEqual(result.headerlist[0],
+                         ('Content-Type', 'text/html; charset=UTF-8'))
+        self.assertEqual(result.headerlist[1], ('Content-Length',
+                                                str(len(body))))
+
+class FunctionalTests(unittest.TestCase):
+    def setUp(self):
+        from myproject import main
+        app = main({})
+        from webtest import TestApp
+        self.testapp = TestApp(app)
+
+    def test_root(self):
+        res = self.testapp.get('/', status=200)
+        self.assertTrue('Pyramid' in res.body)
diff --git a/docs/narr/MyProject/setup.py b/docs/narr/MyProject/setup.py
index 8c019af51..9f34540a7 100644
--- a/docs/narr/MyProject/setup.py
+++ b/docs/narr/MyProject/setup.py
@@ -1,30 +1,42 @@
-import os
+"""Setup for the MyProject package.
 
+"""
+import os
 from setuptools import setup, find_packages
 
-here = os.path.abspath(os.path.dirname(__file__))
-with open(os.path.join(here, 'README.txt')) as f:
-    README = f.read()
-with open(os.path.join(here, 'CHANGES.txt')) as f:
-    CHANGES = f.read()
 
-requires = [
+HERE = os.path.abspath(os.path.dirname(__file__))
+
+
+with open(os.path.join(HERE, 'README.txt')) as fp:
+    README = fp.read()
+
+
+with open(os.path.join(HERE, 'CHANGES.txt')) as fp:
+    CHANGES = fp.read()
+
+
+REQUIRES = [
     'pyramid',
     'pyramid_chameleon',
     'pyramid_debugtoolbar',
     'waitress',
     ]
 
+TESTS_REQUIRE = [
+    'webtest'
+    ]
+
 setup(name='MyProject',
       version='0.0',
       description='MyProject',
       long_description=README + '\n\n' + CHANGES,
       classifiers=[
-        "Programming Language :: Python",
-        "Framework :: Pyramid",
-        "Topic :: Internet :: WWW/HTTP",
-        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
-        ],
+          'Programming Language :: Python',
+          'Framework :: Pyramid',
+          'Topic :: Internet :: WWW/HTTP',
+          'Topic :: Internet :: WWW/HTTP :: WSGI :: Application',
+      ],
       author='',
       author_email='',
       url='',
@@ -32,11 +44,10 @@ setup(name='MyProject',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
-      install_requires=requires,
-      tests_require=requires,
-      test_suite="myproject",
+      install_requires=REQUIRES,
+      tests_require=TESTS_REQUIRE,
+      test_suite='myproject',
       entry_points="""\
       [paste.app_factory]
       main = myproject:main
-      """,
-      )
+      """)
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index b0a8d18b0..fc908c2b4 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -276,15 +276,237 @@ to put static media on a separate webserver during production (if the
 ``name`` argument to :meth:`~pyramid.config.Configurator.add_static_view` is
 a URL), while keeping static media package-internal and served by the
 development webserver during development (if the ``name`` argument to
-:meth:`~pyramid.config.Configurator.add_static_view` is a URL prefix).  To
-create such a circumstance, we suggest using the
-:attr:`pyramid.registry.Registry.settings` API in conjunction with a setting
-in the application ``.ini`` file named ``media_location``.  Then set the
-value of ``media_location`` to either a prefix or a URL depending on whether
-the application is being run in development or in production (use a different
-``.ini`` file for production than you do for development).  This is just a
-suggestion for a pattern; any setting name other than ``media_location``
-could be used.
+:meth:`~pyramid.config.Configurator.add_static_view` is a URL prefix).
+
+For example, we may define a :ref:`custom setting <adding_a_custom_setting>`
+named ``media_location`` which we can set to an external URL in production
+when our assets are hosted on a CDN.
+
+.. code-block:: python
+   :linenos:
+
+   media_location = settings.get('media_location', 'static')
+
+   config = Configurator(settings=settings)
+   config.add_static_view(path='myapp:static', name=media_location)
+
+Now we can optionally define the setting in our ini file:
+
+.. code-block:: ini
+   :linenos:
+
+   # production.ini
+   [app:main]
+   use = egg:myapp#main
+
+   media_location = http://static.example.com/
+
+It is also possible to serve assets that live outside of the source by
+referring to an absolute path on the filesystem. There are two ways to
+accomplish this.
+
+First, :meth:`~pyramid.config.Configurator.add_static_view`
+supports taking an absolute path directly instead of an asset spec. This works
+as expected, looking in the file or folder of files and serving them up at
+some URL within your application or externally. Unfortunately, this technique
+has a drawback that it is not possible to use the
+:meth:`~pyramid.request.Request.static_url` method to generate URLs, since it
+works based on an asset spec.
+
+The second approach, available in Pyramid 1.6+, uses the asset overriding
+APIs described in the :ref:`overriding_assets_section` section. It is then
+possible to configure a "dummy" package which then serves its file or folder
+from an absolute path.
+
+.. code-block:: python
+
+   config.add_static_view(path='myapp:static_images', name='static')
+   config.override_asset(to_override='myapp:static_images/',
+                         override_with='/abs/path/to/images/')
+
+From this configuration it is now possible to use
+:meth:`~pyramid.request.Request.static_url` to generate URLs to the data
+in the folder by doing something like
+``request.static_url('myapp:static_images/foo.png')``. While it is not
+necessary that the ``static_images`` file or folder actually exist in the
+``myapp`` package, it is important that the ``myapp`` portion points to a
+valid package. If the folder does exist then the overriden folder is given
+priority if the file's name exists in both locations.
+
+.. index::
+   single: Cache Busting
+
+.. _cache_busting:
+
+Cache Busting
+-------------
+
+.. versionadded:: 1.6
+
+In order to maximize performance of a web application, you generally want to 
+limit the number of times a particular client requests the same static asset.
+Ideally a client would cache a particular static asset "forever", requiring 
+it to be sent to the client a single time.  The HTTP protocol allows you to 
+send headers with an HTTP response that can instruct a client to cache a 
+particular asset for an amount of time.  As long as the client has a copy of 
+the asset in its cache and that cache hasn't expired, the client will use the
+cached copy rather than request a new copy from the server.  The drawback to 
+sending cache headers to the client for a static asset is that at some point
+the static asset may change, and then you'll want the client to load a new copy
+of the asset.  Under normal circumstances you'd just need to wait for the 
+client's cached copy to expire before they get the new version of the static 
+resource.
+
+A commonly used workaround to this problem is a technique known as "cache 
+busting".  Cache busting schemes generally involve generating a URL for a 
+static asset that changes when the static asset changes.  This way headers can
+be sent along with the static asset instructing the client to cache the asset
+for a very long time.  When a static asset is changed, the URL used to refer to
+it in a web page also changes, so the client sees it as a new resource and 
+requests a copy, regardless of any caching policy set for the resource's old 
+URL.
+
+:app:`Pyramid` can be configured to produce cache busting URLs for static 
+assets by passing the optional argument, ``cachebust`` to 
+:meth:`~pyramid.config.Configurator.add_static_view`:
+
+.. code-block:: python
+   :linenos:
+
+   # config is an instance of pyramid.config.Configurator
+   config.add_static_view(name='static', path='mypackage:folder/static',
+                          cachebust=True)
+
+Setting the ``cachebust`` argument instructs :app:`Pyramid` to use a cache 
+busting scheme which adds the md5 checksum for a static asset as a path segment
+in the asset's URL:
+
+.. code-block:: python
+   :linenos:
+
+   js_url = request.static_url('mypackage:folder/static/js/myapp.js')
+   # Returns: 'http://www.example.com/static/c9658b3c0a314a1ca21e5988e662a09e/js/myapp.js`
+
+When the asset changes, so will its md5 checksum, and therefore so will its
+URL.  Supplying the ``cachebust`` argument also causes the static view to set
+headers instructing clients to cache the asset for ten years, unless the
+``max_cache_age`` argument is also passed, in which case that value is used.
+
+.. note:: 
+
+   md5 checksums are cached in RAM so if you change a static resource without
+   restarting your application, you may still generate URLs with a stale md5
+   checksum. 
+
+Disabling the Cache Buster
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It can be useful in some situations (e.g. development) to globally disable all
+configured cache busters without changing calls to
+:meth:`~pyramid.config.Configurator.add_static_view`.  To do this set the 
+``PYRAMID_PREVENT_CACHEBUST`` environment variable or the 
+``pyramid.prevent_cachebust`` configuration value to a true value.
+
+Customizing the Cache Buster
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Revisiting from the previous section:
+
+.. code-block:: python
+   :linenos:
+
+   # config is an instance of pyramid.config.Configurator
+   config.add_static_view(name='static', path='mypackage:folder/static',
+                          cachebust=True)
+
+Setting ``cachebust`` to ``True`` instructs :app:`Pyramid` to use a default
+cache busting implementation that should work for many situations.  The 
+``cachebust`` may be set to any object that implements the interface,
+:class:`~pyramid.interfaces.ICacheBuster`.  The above configuration is exactly
+equivalent to:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.static import PathSegmentMd5CacheBuster
+
+   # config is an instance of pyramid.config.Configurator
+   config.add_static_view(name='static', path='mypackage:folder/static',
+                          cachebust=PathSegmentMd5CacheBuster())
+
+:app:`Pyramid` includes a handful of ready to use cache buster implementations:
+:class:`~pyramid.static.PathSegmentMd5CacheBuster`, which inserts an md5
+checksum token in the path portion of the asset's URL,
+:class:`~pyramid.static.QueryStringMd5CacheBuster`, which adds an md5 checksum
+token to the query string of the asset's URL, and
+:class:`~pyramid.static.QueryStringConstantCacheBuster`, which adds an
+arbitrary token you provide to the query string of the asset's URL.  
+
+In order to implement your own cache buster, you can write your own class from
+scratch which implements the :class:`~pyramid.interfaces.ICacheBuster`
+interface.  Alternatively you may choose to subclass one of the existing
+implementations.  One of the most likely scenarios is you'd want to change the
+way the asset token is generated.  To do this just subclass an existing
+implementation and replace the :meth:`~pyramid.interfaces.ICacheBuster.token`
+method.  Here is an example which just uses Git to get the hash of the 
+currently checked out code:
+
+.. code-block:: python
+   :linenos:
+
+   import os
+   import subprocess
+   from pyramid.static import PathSegmentMd5CacheBuster
+
+   class GitCacheBuster(PathSegmentMd5CacheBuster):
+       """
+       Assuming your code is installed as a Git checkout, as opposed to as an
+       egg from an egg repository like PYPI, you can use this cachebuster to
+       get the current commit's SHA1 to use as the cache bust token.
+       """
+       def __init__(self):
+           here = os.path.dirname(os.path.abspath(__file__))
+           self.sha1 = subprocess.check_output(
+               ['git', 'rev-parse', 'HEAD'],
+               cwd=here).strip()
+
+       def token(self, pathspec):
+           return self.sha1
+   
+Choosing a Cache Buster
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The default cache buster implementation, 
+:class:`~pyramid.static.PathSegmentMd5CacheBuster`, works very well assuming 
+that you're using :app:`Pyramid` to serve your static assets.  The md5 checksum
+is fine grained enough that browsers should only request new versions of 
+specific assets that have changed.  Many caching HTTP proxies will fail to 
+cache a resource if the URL contains a query string.  In general, therefore, 
+you should prefer a cache busting strategy which modifies the path segment to
+a strategy which adds a query string.  
+
+It is possible, however, that your static assets are being served by another
+web server or externally on a CDN.  In these cases modifying the path segment
+for a static asset URL would cause the external service to fail to find the
+asset, causing your customer to get a 404.  In these cases you would need to 
+fall back to a cache buster which adds a query string.  It is even possible 
+that there isn't a copy of your static assets available to the :app:`Pyramid`
+application, so a cache busting implementation that generates md5 checksums
+would fail since it can't access the assets.  In such a case, 
+:class:`~pyramid.static.QueryStringConstantCacheBuster` is a reasonable 
+fallback.  The following code would set up a cachebuster that just uses the 
+time at start up as a cachebust token:
+
+.. code-block:: python
+   :linenos:
+
+   import time
+   from pyramid.static import QueryStringConstantCacheBuster
+
+   config.add_static_view(
+       name='http://mycdn.example.com/', 
+       path='mypackage:static',
+       cachebust=QueryStringConstantCacheBuster(str(time.time())))
 
 .. index::
    single: static assets view
@@ -526,3 +748,6 @@ files.  Any software which uses the
 :func:`pkg_resources.get_resource_string` APIs will obtain an overridden file
 when an override is used.
 
+As of Pyramid 1.6, it is also possible to override an asset by supplying an
+absolute path to a file or directory. This may be useful if the assets are
+not distributed as part of a Python package.
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 3cabbd8f4..4f16617c4 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -146,7 +146,7 @@ name ``main`` as a section name:
 
 .. code-block:: text
 
-    $ $VENV/bin starter/development.ini#main
+    $ $VENV/bin/pshell starter/development.ini#main
     Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) 
     [GCC 4.4.3] on linux2
     Type "help" for more information.
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index f7a69d613..f7fa94daf 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -17,6 +17,10 @@ plugging application code that you've written into :app:`Pyramid` is also
 referred to within this documentation as "configuration"; you are configuring
 :app:`Pyramid` to call the code that makes up your application.
 
+.. seealso::
+   For information on ``.ini`` files for Pyramid applications see the
+   :ref:`startup_chapter` chapter.
+
 There are two ways to configure a :app:`Pyramid` application:
 :term:`imperative configuration` and :term:`declarative configuration`.  Both
 are described below.
@@ -114,7 +118,6 @@ in a package and its subpackages.  For example:
        return Response('Hello')
 
    if __name__ == '__main__':
-       from pyramid.config import Configurator
        config = Configurator()
        config.scan()
        app = config.make_wsgi_app()
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 412635f08..0b06fb80b 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -13,7 +13,6 @@
    single: reload settings
    single: default_locale_name
    single: environment variables
-   single: Mako environment settings
    single: ini file settings
    single: PasteDeploy settings
 
@@ -158,6 +157,28 @@ feature when this is true.
 |                                 |                                  |
 +---------------------------------+----------------------------------+
 
+Preventing Cache Busting
+------------------------
+
+Prevent the ``cachebust`` static view configuration argument from having any
+effect globally in this process when this value is true.  No cache buster will
+be configured or used when this is true.  
+
+.. versionadded:: 1.6
+
+.. seealso::
+
+    See also :ref:`cache_busting`.
+
++---------------------------------+----------------------------------+
+| Environment Variable Name       | Config File Setting Name         |
++=================================+==================================+
+| ``PYRAMID_PREVENT_CACHEBUST``   |  ``pyramid.prevent_cachebust``   |
+|                                 |  or ``prevent_cachebust``        |
+|                                 |                                  |
+|                                 |                                  |
++---------------------------------+----------------------------------+
+
 Debugging All
 -------------
 
@@ -396,153 +417,6 @@ Is equivalent to using the following statements in your configuration code:
 
 It is fine to use both or either form.
 
-.. _mako_template_renderer_settings:
-
-Mako Template Render Settings
------------------------------
-
-Mako derives additional settings to configure its template renderer that
-should be set when using it. Many of these settings are optional and only need
-to be set if they should be different from the default. The Mako Template
-Renderer uses a subclass of Mako's `template lookup
-<http://www.makotemplates.org/docs/usage.html#usage_lookup>`_ and accepts
-several arguments to configure it.
-
-Mako Directories
-~~~~~~~~~~~~~~~~
-
-The value(s) supplied here are passed in as the template directories. They
-should be in :term:`asset specification` format, for example:
-``my.package:templates``.
-
-+-----------------------------+
-| Config File Setting Name    |
-+=============================+
-|  ``mako.directories``       |
-|                             |
-|                             |
-|                             |
-+-----------------------------+
-
-Mako Module Directory
-~~~~~~~~~~~~~~~~~~~~~
-
-The value supplied here tells Mako where to store compiled Mako templates. If
-omitted, compiled templates will be stored in memory. This value should be an
-absolute path, for example: ``%(here)s/data/templates`` would use a directory
-called ``data/templates`` in the same parent directory as the INI file.
-
-+-----------------------------+
-| Config File Setting Name    |
-+=============================+
-|  ``mako.module_directory``  |
-|                             |
-|                             |
-|                             |
-+-----------------------------+
-
-Mako Input Encoding
-~~~~~~~~~~~~~~~~~~~
-
-The encoding that Mako templates are assumed to have. By default this is set
-to ``utf-8``. If you wish to use a different template encoding, this value
-should be changed accordingly.
-
-+-----------------------------+
-| Config File Setting Name    |
-+=============================+
-|  ``mako.input_encoding``    |
-|                             |
-|                             |
-|                             |
-+-----------------------------+
-
-Mako Error Handler
-~~~~~~~~~~~~~~~~~~
-
-A callable (or a :term:`dotted Python name` which names a callable) which is
-called whenever Mako compile or runtime exceptions occur. The callable is
-passed the current context as well as the exception. If the callable returns
-True, the exception is considered to be handled, else it is re-raised after
-the function completes. Is used to provide custom error-rendering functions.
-
-+-----------------------------+
-| Config File Setting Name    |
-+=============================+
-|  ``mako.error_handler``     |
-|                             |
-|                             |
-|                             |
-+-----------------------------+
-
-Mako Default Filters
-~~~~~~~~~~~~~~~~~~~~
-
-List of string filter names that will be applied to all Mako expressions.
-
-+-----------------------------+
-| Config File Setting Name    |
-+=============================+
-|  ``mako.default_filters``   |
-|                             |
-|                             |
-|                             |
-+-----------------------------+
-
-Mako Import
-~~~~~~~~~~~
-
-String list of Python statements, typically individual "import" lines, which
-will be placed into the module level preamble of all generated Python modules.
-
-
-+-----------------------------+
-| Config File Setting Name    |
-+=============================+
-|  ``mako.imports``           |
-|                             |
-|                             |
-|                             |
-+-----------------------------+
-
-
-Mako Strict Undefined
-~~~~~~~~~~~~~~~~~~~~~
-
-``true`` or ``false``, representing the "strict undefined" behavior of Mako
-(see `Mako Context Variables
-<http://www.makotemplates.org/docs/runtime.html#context-variables>`_).  By
-default, this is ``false``.
-
-+-----------------------------+
-| Config File Setting Name    |
-+=============================+
-|  ``mako.strict_undefined``  |
-|                             |
-|                             |
-|                             |
-+-----------------------------+
-
-Mako Preprocessor
-~~~~~~~~~~~~~~~~~
-
-.. versionadded:: 1.1
-
-A callable (or a :term:`dotted Python name` which names a callable) which is
-called to preprocess the source before the template is called.  The callable
-will be passed the full template source before it is parsed. The return
-result of the callable will be used as the template source code.
-
-
-+-----------------------------+
-| Config File Setting Name    |
-+=============================+
-|  ``mako.preprocessor``      |
-|                             |
-|                             |
-|                             |
-+-----------------------------+
-
 Examples
 --------
 
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index f2542f1d7..e250c2d7e 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -354,6 +354,53 @@ We attach and cache an object named ``extra`` to the ``request`` object.
 
 .. _beforerender_event:
 
+.. index::
+   single: response factory
+
+.. _changing_the_response_factory:
+
+Changing the Response Factory
+-------------------------------
+
+.. versionadded:: 1.6
+
+Whenever :app:`Pyramid` returns a response from a view it creates a
+:term:`response` object.  By default, an instance of the
+:class:`pyramid.response.Response` class is created to represent the response
+object.
+
+The factory that :app:`Pyramid` uses to create a response object instance can be
+changed by passing a ``response_factory`` argument to the constructor of the
+:term:`configurator`.  This argument can be either a callable or a
+:term:`dotted Python name` representing a callable.
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.response import Response
+
+   class MyResponse(Response):
+       pass
+
+   config = Configurator(response_factory=lambda r: MyResponse())
+
+If you're doing imperative configuration, and you'd rather do it after you've
+already constructed a :term:`configurator` it can also be registered via the
+:meth:`pyramid.config.Configurator.set_response_factory` method:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.config import Configurator
+   from pyramid.response import Response
+
+   class MyResponse(Response):
+       pass
+
+   config = Configurator()
+   config.set_response_factory(lambda r: MyResponse())
+
+
 Using The Before Render Event
 -----------------------------
 
@@ -985,7 +1032,7 @@ Creating a Tween
 
 To create a tween, you must write a "tween factory".  A tween factory
 must be a globally importable callable which accepts two arguments:
-``handler`` and ``registry``.  ``handler`` will be the either the main
+``handler`` and ``registry``.  ``handler`` will be either the main
 Pyramid request handling function or another tween.  ``registry`` will be the
 Pyramid :term:`application registry` represented by this Configurator.  A
 tween factory must return the tween (a callable object) when it is called.
@@ -1023,7 +1070,7 @@ method:
     :linenos:
 
     class simple_tween_factory(object):
-        def __init__(handler, registry):
+        def __init__(self, handler, registry):
             self.handler = handler
             self.registry = registry
 
@@ -1040,6 +1087,10 @@ method:
 
             return response
 
+You should avoid mutating any state on the tween instance. The tween is
+invoked once per request and any shared mutable state needs to be carefully
+handled to avoid any race conditions.
+
 The closure style performs slightly better and enables you to conditionally
 omit the tween from the request processing pipeline (see the following timing
 tween example), whereas the class style makes it easier to have shared mutable
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index 1de2c8941..3c804a158 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -326,7 +326,7 @@ application.  You run a ``pot-create`` command to extract the messages:
 
    $ cd /place/where/myapplication/setup.py/lives
    $ mkdir -p myapplication/locale
-   $ $VENV/bin/pot-create src > myapplication/locale/myapplication.pot
+   $ $VENV/bin/pot-create -o myapplication/locale/myapplication.pot src
 
 The message catalog ``.pot`` template will end up in:
 
@@ -352,9 +352,9 @@ command from Gettext:
    $ cd /place/where/myapplication/setup.py/lives
    $ cd myapplication/locale
    $ mkdir -p es/LC_MESSAGES
-   $ msginit -l es es/LC_MESSAGES/myapplication.po
+   $ msginit -l es -o es/LC_MESSAGES/myapplication.po
 
-This will create a new the message catalog ``.po`` file will in:
+This will create a new message catalog ``.po`` file in:
 
 ``myapplication/locale/es/LC_MESSAGES/myapplication.po``.
 
@@ -402,11 +402,11 @@ command from Gettext:
 .. code-block:: text
 
    $ cd /place/where/myapplication/setup.py/lives
-   $ msgfmt myapplication/locale/*/LC_MESSAGES/*.po
+   $ msgfmt -o myapplication/locale/es/LC_MESSAGES/myapplication.mo myapplication/locale/es/LC_MESSAGES/myapplication.po
 
 This will create a ``.mo`` file for each ``.po`` file in your
 application.  As long as the :term:`translation directory` in which
-the ``.mo`` file ends up in is configured into your application, these
+the ``.mo`` file ends up in is configured into your application (see :ref:`adding_a_translation_directory`), these
 translations will be available to :app:`Pyramid`.
 
 .. index::
@@ -792,9 +792,11 @@ Then as a part of the code of a custom :term:`locale negotiator`:
 .. code-block:: python
    :linenos:
 
-   from pyramid.threadlocal import get_current_registry
-   settings = get_current_registry().settings
-   languages = settings['available_languages'].split()
+   from pyramid.settings import aslist
+
+   def my_locale_negotiator(request):
+       languages = aslist(request.registry.settings['available_languages'])
+       # ...
 
 This is only a suggestion.  You can create your own "available
 languages" configuration scheme as necessary.
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index e419a8b20..a825b61b9 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -15,8 +15,8 @@ You will need `Python <http://python.org>`_ version 2.6 or better to run
 .. sidebar:: Python Versions
 
     As of this writing, :app:`Pyramid` has been tested under Python 2.6, Python
-    2.7, Python 3.2, and Python 3.3.  :app:`Pyramid` does not run under any
-    version of Python before 2.6.
+    2.7, Python 3.2, Python 3.3, Python 3.4 and PyPy 2.2. :app:`Pyramid` does
+    not run under any version of Python before 2.6.
 
 :app:`Pyramid` is known to run on all popular UNIX-like systems such as Linux,
 Mac OS X, and FreeBSD as well as on Windows platforms.  It is also known to run
@@ -32,20 +32,22 @@ dependency will fall back to using pure Python instead.
 For Mac OS X Users
 ~~~~~~~~~~~~~~~~~~
 
-From `Python.org <http://python.org/download/mac/>`_:
+Python comes pre-installed on Mac OS X, but due to Apple's release cycle,
+it is often out of date. Unless you have a need for a specific earlier version,
+it is recommended to install the latest 2.x or 3.x version of Python.
 
-    Python comes pre-installed on Mac OS X, but due to Apple's release cycle,
-    it's often one or even two years old. The overwhelming recommendation of
-    the "MacPython" community is to upgrade your Python by downloading and
-    installing a newer version from `the Python standard release page
-    <http://python.org/download/releases/>`_.
+You can install the latest verion of Python for Mac OS X from the binaries on
+`python.org <https://www.python.org/download/mac/>`_.
 
-It is recommended to download one of the *installer* versions, unless you
-prefer to install your Python through a packgage manager (e.g., macports or
-homebrew) or to build your Python from source.
+Alternatively, you can use the `homebrew <http://brew.sh/>`_ package manager.
 
-Unless you have a need for a specific earlier version, it is recommended to
-install the latest 2.x or 3.x version of Python.
+.. code-block:: text
+
+   # for python 2.7
+   $ brew install python
+
+   # for python 3.4
+   $ brew install python3
 
 If you use an installer for your Python, then you can skip to the section
 :ref:`installing_unix`.
diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst
index 75428d513..c16673ae6 100644
--- a/docs/narr/logging.rst
+++ b/docs/narr/logging.rst
@@ -16,6 +16,11 @@ how to send log messages to loggers that you've configured.
    a third-party scaffold which does not create these files, the
    configuration information in this chapter may not be applicable.
 
+.. index:
+   pair: settings; logging
+   pair: .ini; logging
+   pair: logging; configuration
+
 .. _logging_config:
 
 Logging Configuration
@@ -242,7 +247,7 @@ level is set to ``INFO``, whereas the application's log level is set to
     [logger_myapp] 
     level = DEBUG 
     handlers = 
-    qualname = helloworld 
+    qualname = myapp 
 
 All of the child loggers of the ``myapp`` logger will inherit the ``DEBUG``
 level unless they're explicitly set differently. Meaning the ``myapp.views``,
@@ -294,15 +299,26 @@ use the :term:`pyramid_exclog` package.  Details about its configuration are
 in its `documentation
 <http://docs.pylonsproject.org/projects/pyramid_exclog/dev/>`_.
 
+.. index::
+   single: TransLogger
+   single: middleware; TransLogger
+   pair: configuration; middleware
+   single: settings; middleware
+   pair: .ini; middleware
+
+.. _request_logging_with_pastes_translogger:
+
 Request Logging with Paste's TransLogger 
 ----------------------------------------
 
-Paste provides the `TransLogger 
-<http://pythonpaste.org/modules/translogger.html>`_ :term:`middleware` for
-logging requests using the `Apache Combined Log Format
-<http://httpd.apache.org/docs/2.2/logs.html#combined>`_. TransLogger combined 
-with a FileHandler can be used to create an ``access.log`` file similar to 
-Apache's. 
+The term:`WSGI` design is modular.  Waitress logs error conditions, debugging
+output, etc., but not web traffic.  For web traffic logging Paste provides the
+`TransLogger <http://pythonpaste.org/modules/translogger.html>`_
+:term:`middleware`.  TransLogger produces logs in the `Apache Combined Log
+Format <http://httpd.apache.org/docs/2.2/logs.html#combined>`_.  But
+TransLogger does not write to files, the Python logging system must be
+configured to do this.  The Python FileHandler_ logging handler can be used
+alongside TransLogger to create an ``access.log`` file similar to Apache's.
 
 Like any standard :term:`middleware` with a Paste entry point, TransLogger can
 be configured to wrap your application using ``.ini`` file syntax.  First,
@@ -343,10 +359,12 @@ function of your project's ``__init__`` file:
     app = TransLogger(app, setup_console_handler=False) 
     return app 
 
-TransLogger will automatically setup a logging handler to the console when
-called with no arguments, so it 'just works' in environments that don't
-configure logging. Since we've configured our own logging handlers, we need
-to disable that option via ``setup_console_handler = False``.
+
+.. note::
+    TransLogger will automatically setup a logging handler to the console when
+    called with no arguments, so it 'just works' in environments that don't
+    configure logging. Since our logging handlers are configured we disable
+    the automation via ``setup_console_handler = False``.
 
 With the filter in place, TransLogger's logger (named the ``wsgi`` logger) will
 propagate its log messages to the parent logger (the root logger), sending
@@ -361,9 +379,9 @@ its output to the console when we request a page:
     "Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko/20070725
     Firefox/2.0.0.6" 
 
-To direct TransLogger to an ``access.log`` FileHandler, we need to add that
-FileHandler to the list of handlers (named ``accesslog``), and ensure that the 
-``wsgi`` logger is configured and uses this handler accordingly:
+To direct TransLogger to an ``access.log`` FileHandler, we need the following
+to add a FileHandler (named ``accesslog``) to the list of handlers, and ensure
+that the ``wsgi`` logger is configured and uses this handler accordingly:
 
 .. code-block:: ini 
 
@@ -377,7 +395,7 @@ FileHandler to the list of handlers (named ``accesslog``), and ensure that the
 
     [logger_wsgi] 
     level = INFO 
-    handlers = handler_accesslog
+    handlers = accesslog
     qualname = wsgi 
     propagate = 0 
 
@@ -395,7 +413,7 @@ directs its records only to the ``accesslog`` handler.
 Finally, there's no need to use the ``generic`` formatter with TransLogger as
 TransLogger itself provides all the information we need. We'll use a
 formatter that passes-through the log messages as is. Add a new formatter
-called ``accesslog`` by include the following in your configuration file:
+called ``accesslog`` by including the following in your configuration file:
 
 .. code-block:: ini 
 
@@ -405,7 +423,9 @@ called ``accesslog`` by include the following in your configuration file:
     [formatter_accesslog] 
     format = %(message)s 
 
-Then wire this new ``accesslog`` formatter into the FileHandler: 
+
+Finally alter the existing configuration to wire this new
+``accesslog`` formatter into the FileHandler:
 
 .. code-block:: ini 
 
diff --git a/docs/narr/router.rst b/docs/narr/router.rst
index ac3deefdc..6f90c70cc 100644
--- a/docs/narr/router.rst
+++ b/docs/narr/router.rst
@@ -9,6 +9,9 @@
 Request Processing
 ==================
 
+.. image:: ../_static/pyramid_request_processing.*
+   :alt: Request Processing
+
 Once a :app:`Pyramid` application is up and running, it is ready to accept
 requests and return responses.  What happens from the time a :term:`WSGI`
 request enters a :app:`Pyramid` application through to the point that
@@ -116,7 +119,8 @@ request enters a :app:`Pyramid` application through to the point that
 
 #. The :term:`thread local` stack is popped.
 
-.. image:: router.png
+.. image:: ../_static/pyramid_router.*
+   :alt: Pyramid Router
 
 This is a very high-level overview that leaves out various details.  For more
 detail about subsystems invoked by the :app:`Pyramid` router such as
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 8db23a33b..2dc0c76af 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -6,13 +6,28 @@
 Security
 ========
 
-:app:`Pyramid` provides an optional declarative authorization system
-that can prevent a :term:`view` from being invoked based on an
+:app:`Pyramid` provides an optional, declarative, security system.
+Security in :app:`Pyramid` is separated into authentication and
+authorization. The two systems communicate via :term:`principal`
+identifiers. Authentication is merely the mechanism by which credentials
+provided in the :term:`request` are resolved to one or more
+:term:`principal` identifiers. These identifiers represent the users and
+groups that are in effect during the request. Authorization then determines
+access based on the :term:`principal` identifiers, the requested
+:term:`permission`, and a :term:`context`.
+
+The :app:`Pyramid` authorization system
+can prevent a :term:`view` from being invoked based on an
 :term:`authorization policy`. Before a view is invoked, the
 authorization system can use the credentials in the :term:`request`
 along with the :term:`context` resource to determine if access will be
 allowed.  Here's how it works at a high level:
 
+- A user may or may not have previously visited the application and
+  supplied authentication credentials, including a :term:`userid`.  If
+  so, the application may have called
+  :func:`pyramid.security.remember` to remember these.
+
 - A :term:`request` is generated when a user visits the application.
 
 - Based on the request, a :term:`context` resource is located through
@@ -25,7 +40,9 @@ allowed.  Here's how it works at a high level:
   context as well as other attributes of the request.
 
 - If an :term:`authentication policy` is in effect, it is passed the
-  request; it returns some number of :term:`principal` identifiers.
+  request. It will return some number of :term:`principal` identifiers.
+  To do this, the policy would need to determine the authenticated
+  :term:`userid` present in the request.
 
 - If an :term:`authorization policy` is in effect and the :term:`view
   configuration` associated with the view callable that was found has
@@ -41,15 +58,6 @@ allowed.  Here's how it works at a high level:
 - If the authorization policy denies access, the view callable is not
   invoked; instead the :term:`forbidden view` is invoked.
 
-Security in :app:`Pyramid`, unlike many systems, cleanly and explicitly
-separates authentication and authorization. Authentication is merely the
-mechanism by which credentials provided in the :term:`request` are
-resolved to one or more :term:`principal` identifiers. These identifiers
-represent the users and groups in effect during the request.
-Authorization then determines access based on the :term:`principal`
-identifiers, the :term:`view callable` being invoked, and the
-:term:`context` resource.
-
 Authorization is enabled by modifying your application to include an
 :term:`authentication policy` and :term:`authorization policy`.
 :app:`Pyramid` comes with a variety of implementations of these
@@ -104,7 +112,8 @@ For example:
 
 The above configuration enables a policy which compares the value of an "auth
 ticket" cookie passed in the request's environment which contains a reference
-to a single :term:`principal` against the principals present in any
+to a single :term:`userid` and matches that userid's
+:term:`principals <principal>` against the principals present in any
 :term:`ACL` found in the resource tree when attempting to call some
 :term:`view`.
 
@@ -595,36 +604,53 @@ that implements the following interface:
        """ An object representing a Pyramid authentication policy. """
 
        def authenticated_userid(self, request):
-           """ Return the authenticated userid or ``None`` if no
-           authenticated userid can be found. This method of the policy 
-           should ensure that a record exists in whatever persistent store is 
-           used related to the user (the user should not have been deleted); 
-           if a record associated with the current id does not exist in a 
-           persistent store, it should return ``None``."""
+           """ Return the authenticated :term:`userid` or ``None`` if
+           no authenticated userid can be found. This method of the
+           policy should ensure that a record exists in whatever
+           persistent store is used related to the user (the user
+           should not have been deleted); if a record associated with
+           the current id does not exist in a persistent store, it
+           should return ``None``.
+
+           """
 
        def unauthenticated_userid(self, request):
-           """ Return the *unauthenticated* userid.  This method performs the
-           same duty as ``authenticated_userid`` but is permitted to return the
-           userid based only on data present in the request; it needn't (and
-           shouldn't) check any persistent store to ensure that the user record
-           related to the request userid exists."""
+           """ Return the *unauthenticated* userid.  This method
+           performs the same duty as ``authenticated_userid`` but is
+           permitted to return the userid based only on data present
+           in the request; it needn't (and shouldn't) check any
+           persistent store to ensure that the user record related to
+           the request userid exists.
+
+           This method is intended primarily a helper to assist the
+           ``authenticated_userid`` method in pulling credentials out
+           of the request data, abstracting away the specific headers,
+           query strings, etc that are used to authenticate the request.
+
+           """
 
        def effective_principals(self, request):
            """ Return a sequence representing the effective principals
-           including the userid and any groups belonged to by the current
-           user, including 'system' groups such as
-           ``pyramid.security.Everyone`` and
-           ``pyramid.security.Authenticated``. """
+           typically including the :term:`userid` and any groups belonged
+           to by the current user, always including 'system' groups such
+           as ``pyramid.security.Everyone`` and
+           ``pyramid.security.Authenticated``.
 
-       def remember(self, request, principal, **kw):
+           """
+
+       def remember(self, request, userid, **kw):
            """ Return a set of headers suitable for 'remembering' the
-           principal named ``principal`` when set in a response.  An
-           individual authentication policy and its consumers can decide
-           on the composition and meaning of **kw. """
-       
+           :term:`userid` named ``userid`` when set in a response.  An
+           individual authentication policy and its consumers can
+           decide on the composition and meaning of **kw.
+
+           """
+
        def forget(self, request):
            """ Return a set of headers suitable for 'forgetting' the
-           current user on subsequent requests. """
+           current user on subsequent requests.
+
+           """
 
 After you do so, you can pass an instance of such a class into the
 :class:`~pyramid.config.Configurator.set_authentication_policy` method
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index 7b4a7ea08..a1a23ed52 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -19,6 +19,7 @@ console.
 
 .. index::
    single: startup process
+   pair: settings; .ini
 
 The Startup Process
 -------------------
@@ -139,6 +140,13 @@ Here's a high-level time-ordered overview of what happens when you press
    The server serves the application, and the application is running, waiting
    to receive requests.
 
+.. seealso::
+   Logging configuration is described in the :ref:`logging_chapter`
+   chapter.  There, in :ref:`request_logging_with_pastes_translogger`,
+   you will also find an example of how to configure
+   :term:`middleware` to add pre-packaged functionality to your
+   application.
+
 .. index::
    pair: settings; deployment
    single: custom settings
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 038dd2594..4c1364493 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -316,8 +316,7 @@ template renderer:
    we're using a Chameleon renderer, it means "relative to the directory in
    which the file which defines the view configuration lives".  In this case,
    this is the directory containing the file that defines the ``my_view``
-   function.  View-configuration-relative asset specifications work only
-   in Chameleon, not in Mako templates.
+   function.
 
 Similar renderer configuration can be done imperatively.  See
 :ref:`views_which_use_a_renderer`.
@@ -450,21 +449,24 @@ Available Add-On Template System Bindings
 The Pylons Project maintains several packages providing bindings to different
 templating languages including the following:
 
-+------------------------------+------------------------------+
-| Template Language            | Pyramid Bindings             |
-+==============================+==============================+
-| Chameleon_                   | pyramid_chameleon_           |
-+------------------------------+------------------------------+
-| Jinja2_                      | pyramid_jinja2_              |
-+------------------------------+------------------------------+
-| Mako_                        | pyramid_mako_                |
-+------------------------------+------------------------------+
++---------------------------+----------------------------+--------------------+
+| Template Language         | Pyramid Bindings           | Default Extensions |
++===========================+============================+====================+
+| Chameleon_                | pyramid_chameleon_         | .pt, .txt          |
++---------------------------+----------------------------+--------------------+
+| Jinja2_                   | pyramid_jinja2_            | .jinja2            |
++---------------------------+----------------------------+--------------------+
+| Mako_                     | pyramid_mako_              | .mak, .mako        |
++---------------------------+----------------------------+--------------------+
 
 .. _Chameleon: http://chameleon.readthedocs.org/en/latest/
-.. _pyramid_chameleon: https://pypi.python.org/pypi/pyramid_chameleon
+.. _pyramid_chameleon:
+   http://docs.pylonsproject.org/projects/pyramid-chameleon/en/latest/
 
 .. _Jinja2: http://jinja.pocoo.org/docs/
-.. _pyramid_jinja2: https://pypi.python.org/pypi/pyramid_jinja2
+.. _pyramid_jinja2:
+   http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/
 
 .. _Mako: http://www.makotemplates.org/
-.. _pyramid_mako: https://pypi.python.org/pypi/pyramid_mako
+.. _pyramid_mako:
+   http://docs.pylonsproject.org/projects/pyramid-mako/en/latest/
diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst
index e001ad81c..ecda57489 100644
--- a/docs/narr/testing.rst
+++ b/docs/narr/testing.rst
@@ -128,8 +128,9 @@ functions accepts various arguments that influence the environment of the
 test.  See the :ref:`testing_module` API for information about the extra
 arguments supported by these functions.
 
-If you also want to make :func:`~pyramid.threadlocal.get_current_request` return something
-other than ``None`` during the course of a single test, you can pass a
+If you also want to make :func:`~pyramid.threadlocal.get_current_request`
+return something other than ``None`` during the course of a single test, you
+can pass a
 :term:`request` object into the :func:`pyramid.testing.setUp` within the
 ``setUp`` method of your test:
 
@@ -333,66 +334,49 @@ Creating Integration Tests
 --------------------------
 
 In :app:`Pyramid`, a *unit test* typically relies on "mock" or "dummy"
-implementations to give the code under test only enough context to run.
+implementations to give the code under test enough context to run.
 
 "Integration testing" implies another sort of testing.  In the context of a
-:app:`Pyramid` integration test, the test logic tests the functionality of
-some code *and* its integration with the rest of the :app:`Pyramid`
+:app:`Pyramid` integration test, the test logic exercises the functionality of
+the code under test *and* its integration with the rest of the :app:`Pyramid`
 framework.
 
-In :app:`Pyramid` applications that are plugins to Pyramid, you can create an
-integration test by including its ``includeme`` function via
-:meth:`pyramid.config.Configurator.include` in the test's setup code.  This
-causes the entire :app:`Pyramid` environment to be set up and torn down as if
-your application was running "for real".  This is a heavy-hammer way of
-making sure that your tests have enough context to run properly, and it tests
-your code's integration with the rest of :app:`Pyramid`.
+Creating an integration test for a :app:`Pyramid` application usually means
+invoking the application's ``includeme`` function via
+:meth:`pyramid.config.Configurator.include` within the test's setup code.  This
+causes the entire :app:`Pyramid` environment to be set up, simulating what
+happens when your application is run "for real".  This is a heavy-hammer way of
+making sure that your tests have enough context to run properly, and tests your
+code's integration with the rest of :app:`Pyramid`.
 
-Let's demonstrate this by showing an integration test for a view.  The below
-test assumes that your application's package name is ``myapp``, and that
-there is a ``views`` module in the app with a function with the name
-``my_view`` in it that returns the response 'Welcome to this application'
-after accessing some values that require a fully set up environment.
+.. seealso::
 
-.. code-block:: python
-   :linenos:
+   See also :ref:`including_configuration`
 
-   import unittest
+Let's demonstrate this by showing an integration test for a view.
 
-   from pyramid import testing
+Given the following view definition, which assumes that your application's
+:term:`package` name is ``myproject``, and within that :term:`package` there
+exists a module ``views``, which in turn contains a :term:`view` function named
+``my_view``:
 
-   class ViewIntegrationTests(unittest.TestCase):
-       def setUp(self):
-           """ This sets up the application registry with the
-           registrations your application declares in its ``includeme`` 
-           function.
-           """
-           import myapp
-           self.config = testing.setUp()
-           self.config.include('myapp')
+   .. literalinclude:: MyProject/myproject/views.py
+      :linenos:
+      :lines: 1-6
+      :language: python
 
-       def tearDown(self):
-           """ Clear out the application registry """
-           testing.tearDown()
+You'd then create a ``tests`` module within your ``myproject`` package,
+containing the following test code:
 
-       def test_my_view(self):
-           from myapp.views import my_view
-           request = testing.DummyRequest()
-           result = my_view(request)
-           self.assertEqual(result.status, '200 OK')
-           body = result.app_iter[0]
-           self.assertTrue('Welcome to' in body)
-           self.assertEqual(len(result.headerlist), 2)
-           self.assertEqual(result.headerlist[0],
-                            ('Content-Type', 'text/html; charset=UTF-8'))
-           self.assertEqual(result.headerlist[1], ('Content-Length',
-                                                   str(len(body))))
-
-Unless you cannot avoid it, you should prefer writing unit tests that use the
-:class:`~pyramid.config.Configurator` API to set up the right "mock"
-registrations rather than creating an integration test.  Unit tests will run
-faster (because they do less for each test) and the result of a unit test is
-usually easier to make assertions about.
+   .. literalinclude:: MyProject/myproject/tests.py
+      :linenos:
+      :pyobject: ViewIntegrationTests
+      :language: python
+
+Writing unit tests that use the :class:`~pyramid.config.Configurator` API to
+set up the right "mock" registrations is often preferred to creating
+integration tests.  Unit tests will run faster (because they do less for each
+test) and are usually easier to reason about.
 
 .. index::
    single: functional tests
@@ -404,34 +388,40 @@ Creating Functional Tests
 
 Functional tests test your literal application.
 
-The below test assumes that your application's package name is ``myapp``, and
-that there is a view that returns an HTML body when the root URL is invoked.
-It further assumes that you've added a ``tests_require`` dependency on the
-``WebTest`` package within your ``setup.py`` file.  :term:`WebTest` is a
-functional testing package written by Ian Bicking.
+In Pyramid, functional tests are typically written using the :term:`WebTest`
+package, which provides APIs for invoking HTTP(S) requests to your application.
 
-.. code-block:: python
-   :linenos:
+Regardless of which testing :term:`package` you use, ensure to add a
+``tests_require`` dependency on that package to to your application's
+``setup.py`` file:
 
-   import unittest
+   .. literalinclude:: MyProject/setup.py
+      :linenos:
+      :emphasize-lines: 26-28,48
+      :language: python
 
-   class FunctionalTests(unittest.TestCase):
-       def setUp(self):
-           from myapp import main
-           app = main({})
-           from webtest import TestApp
-           self.testapp = TestApp(app)
-
-       def test_root(self):
-           res = self.testapp.get('/', status=200)
-           self.assertTrue('Pyramid' in res.body)
-
-When this test is run, each test creates a "real" WSGI application using the
-``main`` function in your ``myapp.__init__`` module and uses :term:`WebTest`
-to wrap that WSGI application.  It assigns the result to ``self.testapp``.
-In the test named ``test_root``, we use the testapp's ``get`` method to
-invoke the root URL.  We then assert that the returned HTML has the string
-``Pyramid`` in it.
+Assuming your :term:`package` is named ``myproject``, which contains a
+``views`` module, which in turn contains a :term:`view` function ``my_view``
+that returns a HTML body when the root URL is invoked:
+
+   .. literalinclude:: MyProject/myproject/views.py
+      :linenos:
+      :language: python
+
+Then the following example functional test (shown below) demonstrates invoking
+the :term:`view` shown above:
+
+   .. literalinclude:: MyProject/myproject/tests.py
+      :linenos:
+      :pyobject: FunctionalTests
+      :language: python
+
+When this test is run, each test method creates a "real" :term:`WSGI`
+application using the ``main`` function in your ``myproject.__init__`` module,
+using :term:`WebTest` to wrap that WSGI application.  It assigns the result to
+``self.testapp``.  In the test named ``test_root``. The ``TestApp``'s ``get``
+method is used to invoke the root URL.  Finally, an assertion is made that the
+returned HTML contains the text ``MyProject``.
 
 See the :term:`WebTest` documentation for further information about the
 methods available to a :class:`webtest.app.TestApp` instance.
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index adc53bd11..a0feef8d7 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -295,11 +295,14 @@ configured view.
   *This is an advanced feature, not often used by "civilians"*.
 
 ``request_method``
-  This value can be a string (typically ``"GET"``, ``"POST"``, ``"PUT"``,
-  ``"DELETE"``, or ``"HEAD"``) representing an HTTP ``REQUEST_METHOD``.  A view
-  declaration with this argument ensures that the view will only be called
-  when the request's ``method`` attribute (aka the ``REQUEST_METHOD`` of the
-  WSGI environment) string matches the supplied value.
+  This value can be either a string (such as ``"GET"``, ``"POST"``,
+  ``"PUT"``, ``"DELETE"``, ``"HEAD"`` or ``"OPTIONS"``) representing an
+  HTTP ``REQUEST_METHOD``, or a tuple containing one or more of these
+  strings.  A view declaration with this argument ensures that the
+  view will only be called when the ``method`` attribute of the
+  request (aka the ``REQUEST_METHOD`` of the WSGI environment) matches
+  a supplied value.  Note that use of ``"GET"`` also implies that the
+  view will respond to ``"HEAD"`` as of Pyramid 1.4.
 
   If ``request_method`` is not supplied, the view will be invoked regardless
   of the ``REQUEST_METHOD`` of the :term:`WSGI` environment.
diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst
index f0a4b5a0b..0eb070b06 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -310,6 +310,14 @@ Python's ``urllib2`` instead of a Javascript AJAX request:
     req = urllib2.Request('http://localhost:6543/', json_payload, headers)
     resp = urllib2.urlopen(req)
 
+If you are doing Cross-origin resource sharing (CORS), then the standard
+requires the browser to do a pre-flight HTTP OPTIONS request. The easiest way
+to handling this is adding an extra ``view_config`` for the same route, with
+``request_method`` set to ``OPTIONS``, and setting the desired response header
+before returning. You can find examples of response headers here_.
+
+.. _here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Preflighted_requests
+
 .. index::
    single: cleaning up after request
 
@@ -408,6 +416,8 @@ Here are some highlights:
     The content type *not* including the ``charset`` parameter.
     Typical use: ``response.content_type = 'text/html'``.
 
+    Default value: ``response.content_type = 'text/html'``.
+
 ``response.charset``:
     The ``charset`` parameter of the content-type, it also informs
     encoding in ``response.unicode_body``.
@@ -466,9 +476,12 @@ argument to the class; e.g.:
   from pyramid.response import Response
   response = Response(body='hello world!', content_type='text/plain')
 
-The status defaults to ``'200 OK'``.  The content_type does not default to
-anything, though if you subclass :class:`pyramid.response.Response` and set
-``default_content_type`` you can override this behavior.
+The status defaults to ``'200 OK'``.
+
+The value of content_type defaults to
+``webob.response.Response.default_content_type``; which is `text/html`.
+You can subclass :class:`pyramid.response.Response` and set
+``default_content_type`` to override this behavior.
 
 .. index::
    single: exception responses