fix merge conflicts

16 files changed, 78 insertions, 50 deletions

diff --git a/docs/api/request.rst b/docs/api/request.rst
index 343d0c022..77d80f6d6 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -319,7 +319,13 @@
 
           def _connect(request):
               conn = request.registry.dbsession()
-              def cleanup(_):
+              def cleanup(request):
+                  # since version 1.5, request.exception is no
+                  # longer eagerly cleared
+                  if request.exception is not None:
+                      conn.rollback()
+                  else:
+                      conn.commit()
                   conn.close()
               request.add_finished_callback(cleanup)
               return conn
diff --git a/docs/conf.py b/docs/conf.py
index eba776628..4bc8e2172 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -57,8 +57,9 @@ extensions = [
 
 # Looks for objects in external projects
 intersphinx_mapping = {
-    'tutorials': ('http://docs.pylonsproject.org/projects/pyramid_tutorials/en/latest/', None),
-    'jinja2': ('http://docs.pylonsproject.org/projects/pyramid_jinja2/en/latest/', None),
+    'tutorials': ('http://docs.pylonsproject.org/projects/pyramid-tutorials/en/latest/', None),
+    'cookbook': ('http://docs.pylonsproject.org/projects/pyramid-cookbook/en/latest/', None),
+    'jinja2': ('http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/', None),
     'tm': (
         'http://docs.pylonsproject.org/projects/pyramid_tm/en/latest/',
         None,
@@ -82,10 +83,10 @@ intersphinx_mapping = {
     'venusian':
         ('http://docs.pylonsproject.org/projects/venusian/en/latest', None),
     'toolbar':
-        ('http://docs.pylonsproject.org/projects/pyramid_debugtoolbar/en/latest',
+        ('http://docs.pylonsproject.org/projects/pyramid-debugtoolbar/en/latest',
          None),
     'zcml':
-        ('http://docs.pylonsproject.org/projects/pyramid_zcml/en/latest',
+        ('http://docs.pylonsproject.org/projects/pyramid-zcml/en/latest',
          None),
 }
 
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 2cc461a77..deb4c1c8b 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -936,7 +936,7 @@ Glossary
      `Akhet <http://docs.pylonsproject.org/projects/akhet/en/latest/>`_ is a 
      Pyramid library and demo application with a Pylons-like feel.
      It's most known for its former application scaffold, which helped 
-     users transition from Pylons and those prefering a more Pylons-like API.
+     users transition from Pylons and those preferring a more Pylons-like API.
      The scaffold has been retired but the demo plays a similar role. 
 
    Pyramid Cookbook
diff --git a/docs/index.rst b/docs/index.rst
index 78a00966d..ac16ff237 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -119,6 +119,8 @@ Narrative documentation in chapter form explaining how to use
    narr/threadlocals
    narr/zca
 
+.. _html_tutorials:
+
 Tutorials
 =========
 
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index f7a69d613..52615533d 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -114,7 +114,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/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/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..6a331e4bf 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -408,6 +408,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 +468,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
diff --git a/docs/quick_tour/views/views.py b/docs/quick_tour/views/views.py
index 9dc795f14..1449cbb38 100644
--- a/docs/quick_tour/views/views.py
+++ b/docs/quick_tour/views/views.py
@@ -1,3 +1,5 @@
+import cgi
+
 from pyramid.httpexceptions import HTTPFound
 from pyramid.response import Response
 from pyramid.view import view_config
@@ -14,7 +16,8 @@ def home_view(request):
 def hello_view(request):
     name = request.params.get('name', 'No Name')
     body = '<p>Hi %s, this <a href="/goto">redirects</a></p>'
-    return Response(body % name)
+    # cgi.escape to prevent Cross-Site Scripting (XSS) [CWE 79]
+    return Response(body % cgi.escape(name))
 
 
 # /goto which issues HTTP redirect to the last view
@@ -23,7 +26,7 @@ def redirect_view(request):
     return HTTPFound(location="/problem")
 
 
-# /problem which causes an site error
+# /problem which causes a site error
 @view_config(route_name='exception')
 def exception_view(request):
     raise Exception()
diff --git a/docs/quick_tutorial/debugtoolbar.rst b/docs/quick_tutorial/debugtoolbar.rst
index 1c540d8a2..90750c633 100644
--- a/docs/quick_tutorial/debugtoolbar.rst
+++ b/docs/quick_tutorial/debugtoolbar.rst
@@ -71,16 +71,17 @@ supports wiring in add-on configuration via our ``development.ini``
 using ``pyramid.includes``. We use this to load the configuration for
 the debugtoolbar.
 
-You'll now see an attractive (and collapsible) menu in the right of
-your browser, providing introspective access to debugging information.
-Even better, if your web application generates an error,
+You'll now see an attractive button on the right side of
+your browser, which you may click to provide introspective access to debugging 
+information in a new browser tab. Even better, if your web application
+generates an error,
 you will see a nice traceback on the screen. When you want to disable
 this toolbar, no need to change code: you can remove it from
 ``pyramid.includes`` in the relevant ``.ini`` configuration file (thus
 showing why configuration files are handy.)
 
-Note that the toolbar mutates the HTML generated by our app and uses jQuery to
-overlay itself.  If you are using the toolbar while you're developing and you
+Note injects a small amount of html/css into your app just before the closing
+``</body>`` tag in order to display itself. If you
 start to experience otherwise inexplicable client-side weirdness, you can shut
 it off by commenting out the ``pyramid_debugtoolbar`` line in
 ``pyramid.includes`` temporarily.
diff --git a/docs/quick_tutorial/jinja2.rst b/docs/quick_tutorial/jinja2.rst
index 44d9f635b..2f1e295dd 100644
--- a/docs/quick_tutorial/jinja2.rst
+++ b/docs/quick_tutorial/jinja2.rst
@@ -88,9 +88,9 @@ Extra Credit
    dependency manually. What is another way we could have made the
    association?
 
-#. We used ``development.ini`` to get the :term:`configurator` to
-   load ``pyramid_jinja2``'s configuration. What is another way could
-   include it into the config?
+#. We used ``config.include`` which is an imperative configuration to get the
+   :term:`Configurator` to load ``pyramid_jinja2``'s configuration. 
+   What is another way could include it into the config?
 
 .. seealso:: `Jinja2 homepage <http://jinja.pocoo.org/>`_,
    and
diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst
index ece8a61c0..aa789d833 100644
--- a/docs/quick_tutorial/json.rst
+++ b/docs/quick_tutorial/json.rst
@@ -40,7 +40,7 @@ Steps
     :linenos:
 
 #. Rather than implement a new view, we will "stack" another decorator
-   on the ``hello`` view:
+   on the ``hello`` view in ``views.py``:
 
    .. literalinclude:: json/tutorial/views.py
     :linenos:
diff --git a/docs/quick_tutorial/more_view_classes.rst b/docs/quick_tutorial/more_view_classes.rst
index 1e5603554..9cc4cc520 100644
--- a/docs/quick_tutorial/more_view_classes.rst
+++ b/docs/quick_tutorial/more_view_classes.rst
@@ -34,7 +34,7 @@ that determine which view is matched to a request, based on factors
 such as the request method, the form parameters, etc. These predicates
 provide many axes of flexibility.
 
-The following shows a simple example with four operations operations:
+The following shows a simple example with four operations:
 view a home page which leads to a form, save a change,
 and press the delete button.
 
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index 72bb4a4f8..b5778ea42 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -187,9 +187,15 @@ pipe it to your environment's version of Python.
     $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python
 
     # Windows
-    # Use your browser to download:
-    #   https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.p
-    # ...into c:\projects\quick_tutorial\ez_setup.py
+    #
+    # Use your web browser to download this file:
+    #   https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py
+    #
+    # ...and save it to:
+    # c:\projects\quick_tutorial\ez_setup.py
+    #
+    # Then run the following command:
+
     c:\> %VENV%\Scripts\python ez_setup.py
 
 If ``wget`` complains with a certificate error, then run this command instead:
diff --git a/docs/quick_tutorial/sessions.rst b/docs/quick_tutorial/sessions.rst
index 0f284e9a7..b4887beb8 100644
--- a/docs/quick_tutorial/sessions.rst
+++ b/docs/quick_tutorial/sessions.rst
@@ -13,10 +13,10 @@ When people use your web application, they frequently perform a task
 that requires semi-permanent data to be saved. For example, a shopping
 cart. This is called a :term:`session`.
 
-Pyramid has basic built-in support for sessions, with add-ons
-or your own custom sessioning engine) that can provide
-richer session support. Let's take a look at the
-:ref:`built-in sessioning support <sessions_chapter>`.
+Pyramid has basic built-in support for sessions.  Third party packages such as
+``pyramid_redis_sessions`` provide richer session support.  Or you can create
+your own custom sessioning engine.  Let's take a look at the
+:doc:`built-in sessioning support <../narr/sessions>`.
 
 Objectives
 ==========
diff --git a/docs/whatsnew-1.5.rst b/docs/whatsnew-1.5.rst
index 65e8393f8..1d863c937 100644
--- a/docs/whatsnew-1.5.rst
+++ b/docs/whatsnew-1.5.rst
@@ -384,9 +384,9 @@ Other Backwards Incompatibilities
   are now "reified" properties that look up a locale name and localizer
   respectively using the machinery described in :ref:`i18n_chapter`.
 
-- If you send an ``X-Vhm-Root`` header with a value that ends with a slash (or
-  any number of slashes), the trailing slash(es) will be removed before a URL
-  is generated when you use use :meth:`~pyramid.request.Request.resource_url`
+- If you send an ``X-Vhm-Root`` header with a value that ends with any number
+  of slashes, the trailing slashes will be removed before the URL
+  is generated when you use :meth:`~pyramid.request.Request.resource_url`
   or :meth:`~pyramid.request.Request.resource_path`.  Previously the virtual
   root path would not have trailing slashes stripped, which would influence URL
   generation.