14 files changed, 170 insertions, 69 deletions
diff --git a/docs/api/request.rst b/docs/api/request.rst
index 9f1f71b31..7b843f86e 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -245,7 +245,7 @@
       influence response values from a view that uses a renderer (such as the
       status code, a header, the content type, etc) you would set these
       attributes.  See :ref:`response_prefixed_attrs` for further discussion.
-      As of Pyramid 1.1, assignment to ``response_*`` attrs are deprecated.
+      As of Pyramid 1.1, assignment to ``response_*`` attrs is deprecated.
       Assigning to one is still supported but will cause a deprecation
       warning to be emitted, and eventually the feature will be removed.  For
       new code, instead of assigning ``response_*`` attributes to the
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 0036d045b..9220e6b5f 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -1015,8 +1015,7 @@ Glossary
 
    Green Unicorn
       Aka ``gunicorn``, a fast :term:`WSGI` server that runs on UNIX under
-      Python 2.5+ (although at the time of this writing does not support
-      Python 3).  See http://gunicorn.org/ for detailed information.
+      Python 2.6+ or Python 3.1+.  See http://gunicorn.org/ for detailed information.
 
    predicate factory
       A callable which is used by a third party during the registration of a
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index cd3dab099..6f82baf32 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -101,27 +101,25 @@ for decorations happens when the :meth:`pyramid.config.Configurator.scan`
 method is invoked: scanning implies searching for configuration declarations
 in a package and its subpackages.  For example:
 
-.. topic:: Starting A Scan
-
-   .. code-block:: python
-      :linenos:
-
-      from wsgiref.simple_server import make_server
-      from pyramid.config import Configurator
-      from pyramid.response import Response
-      from pyramid.view import view_config
-     
-      @view_config()
-      def hello(request):
-          return Response('Hello')
-
-      if __name__ == '__main__':
-          from pyramid.config import Configurator
-          config = Configurator()
-          config.scan()
-          app = config.make_wsgi_app()
-          server = make_server('0.0.0.0', 8080, app)
-          server.serve_forever()
+.. code-block:: python
+   :linenos:
+
+   from wsgiref.simple_server import make_server
+   from pyramid.config import Configurator
+   from pyramid.response import Response
+   from pyramid.view import view_config
+
+   @view_config()
+   def hello(request):
+       return Response('Hello')
+
+   if __name__ == '__main__':
+       from pyramid.config import Configurator
+       config = Configurator()
+       config.scan()
+       app = config.make_wsgi_app()
+       server = make_server('0.0.0.0', 8080, app)
+       server.serve_forever()
 
 The scanning machinery imports each module and subpackage in a package or
 module recursively, looking for special attributes attached to objects
@@ -144,7 +142,6 @@ In the example above, the scanner translates the arguments to
 
 .. ignore-next-block
 .. code-block:: python
-   :linenos:
 
    config.add_view(hello)
 
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index def5e12a4..281bb6919 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -203,7 +203,7 @@ Using the setting is equivalent to using the
 |                                 |
 +---------------------------------+
 
-The value supplied as ``pyramid.includes`` should be a sequence.  The
+The value assigned to ``pyramid.includes`` should be a sequence.  The
 sequence can take several different forms.
 
 1) It can be a string.
@@ -323,7 +323,7 @@ the behest of an add-on author.
 |                                 |
 +---------------------------------+
 
-The value supplied as ``pyramid.tweens`` should be a sequence.  The
+The value assigned to ``pyramid.tweens`` should be a sequence.  The
 sequence can take several different forms.
 
 1) It can be a string.
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index fc5c0ff23..43bf48289 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -257,6 +257,95 @@ already constructed a :term:`configurator` it can also be registered via the
    config.set_request_factory(MyRequest)
 
 .. index::
+   single: request method
+
+.. _adding_request_method:
+
+Adding Methods or Properties to Request Object
+----------------------------------------------
+
+.. versionadded:: 1.4.
+
+Since each Pyramid application can only have one :term:`request` factory,
+:ref:`changing the request factory <changing_the_request_factory>`
+is not that extensible, especially if you want to build composable features
+(e.g., Pyramid add-ons and plugins).
+
+A lazy property can be registered to the request object via the
+:meth:`pyramid.config.Configurator.add_request_method` API. This allows you
+to specify a callable that will be available on the request object, but will not
+actually execute the function until accessed.
+
+.. warning:: This will silently override methods and properties from
+   :term:`request factory` that have the same name.
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.config import Configurator
+
+   def total(request, *args):
+       return sum(args)
+
+   def prop(request):
+       print "getting the property"
+       return "the property"
+
+   config = Configurator()
+   config.add_request_method(total)
+   config.add_request_method(prop, reify=True)
+
+In the above example, ``total`` is added as a method. However, ``prop`` is added
+as a property and its result is cached per-request by setting ``reify=True``.
+This way, we eliminate the overhead of running the function multiple times.
+
+   >>> request.total(1, 2, 3)
+   6
+   >>> request.prop
+   getting the property
+   the property
+   >>> request.prop
+   the property
+
+To not cache the result of ``request.prop``, set ``property=True`` instead of
+``reify=True``.
+
+Here is an example of passing a class to ``Configurator.add_request_method``:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.config import Configurator
+   from pyramid.decorator import reify
+
+   class ExtraStuff(object):
+
+       def __init__(self, request):
+           self.request = request
+
+       def total(self, *args):
+           return sum(args)
+
+       # use @property if you don't want to cache the result
+       @reify
+       def prop(self):
+           print "getting the property"
+           return "the property"
+
+   config = Configurator()
+   config.add_request_method(ExtraStuff, 'extra', reify=True)
+
+We attach and cache an object named ``extra`` to the ``request`` object.
+
+   >>> request.extra.total(1, 2, 3)
+   6
+   >>> request.extra.prop
+   getting the property
+   the property
+   >>> request.extra.prop
+   the property
+
+.. index::
    single: before render event
    single: adding renderer globals
 
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index c467779f4..85dfd5bf4 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -14,8 +14,8 @@ run :app:`Pyramid`.
 
 .. sidebar:: Python Versions
 
-    As of this writing, :app:`Pyramid` has been tested under Python 2.6.8,
-    Python 2.7.3, Python 3.2.3, and Python 3.3b1.  :app:`Pyramid` does not
+    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.
 
 :app:`Pyramid` is known to run on all popular UNIX-like systems such as
@@ -88,17 +88,15 @@ using the following commands:
 
 .. code-block:: text
 
-   [chrism@vitaminf ~]$ cd ~
-   [chrism@vitaminf ~]$ mkdir tmp
-   [chrism@vitaminf ~]$ mkdir opt
-   [chrism@vitaminf ~]$ cd tmp
-   [chrism@vitaminf tmp]$ wget \
-          http://www.python.org/ftp/python/2.7.3/Python-2.7.3.tgz
-   [chrism@vitaminf tmp]$ tar xvzf Python-2.7.3.tgz
-   [chrism@vitaminf tmp]$ cd Python-2.7.3
-   [chrism@vitaminf Python-2.7.3]$ ./configure \
-           --prefix=$HOME/opt/Python-2.7.3
-   [chrism@vitaminf Python-2.7.3]$ make; make install
+   $ cd ~
+   $ mkdir tmp
+   $ mkdir opt
+   $ cd tmp
+   $ wget http://www.python.org/ftp/python/2.7.3/Python-2.7.3.tgz
+   $ tar xvzf Python-2.7.3.tgz
+   $ cd Python-2.7.3
+   $ ./configure --prefix=$HOME/opt/Python-2.7.3
+   $ make && make install
 
 Once these steps are performed, the Python interpreter will be
 invokable via ``$HOME/opt/Python-2.7.3/bin/python`` from a shell
@@ -205,7 +203,7 @@ Installing Distribute On Python 3
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``setuptools`` doesn't work under Python 3.  Instead, you can use
-``distribute``, which is a fork of setuptools that does work on Python 3.  To
+``distribute``, which is a fork of setuptools.  To
 install it, first download `distribute_setup.py
 <http://python-distribute.org/distribute_setup.py>`_ then invoke it using the
 Python interpreter into which you want to install setuptools.
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index c4f2ea512..3540ee5c4 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -749,7 +749,7 @@ that we change Pyramid?  You can extend Pyramid's :term:`Configurator` with
 your own directives.  For example, let's say you find yourself calling
 :meth:`pyramid.config.Configurator.add_view` repetitively.  Usually you can
 take the boring away by using existing shortcuts, but let's say that this is
-a case such a way that no existing shortcut works to take the boring away:
+a case where there is no such shortcut:
 
 .. code-block:: python
    :linenos:
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index fb62f4bd2..5a8ea0ecf 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -297,7 +297,7 @@ 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://129.168.1.50:6543/``. However, *other people* on other computers on
+``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 ``http://192.168.1.50:6543/``.
 
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 863932e83..34b9ad00c 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -565,9 +565,6 @@ in :ref:`request_module`.  For more information on the API of
 Deprecated Mechanism to Vary Attributes of Rendered Responses
 -------------------------------------------------------------
 
-.. deprecated:: 1.1
-   The behavior described in this entire section.
-
 In previous releases of Pyramid (1.0 and before), the ``request.response``
 attribute did not exist.  Instead, Pyramid required users to set special
 ``response_`` -prefixed attributes of the request to influence response
diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst
index efcc7bf21..4dedf4320 100644
--- a/docs/tutorials/wiki/definingviews.rst
+++ b/docs/tutorials/wiki/definingviews.rst
@@ -71,6 +71,13 @@ and a final view named ``edit_page`` will allow a page to be edited.
 The ``view_wiki`` view function
 -------------------------------
 
+Here is the code for the ``view_wiki`` view function and its decorator, which
+will be added to ``views.py``:
+
+.. literalinclude:: src/views/tutorial/views.py
+   :lines: 12-14
+   :language: python
+
 The ``view_wiki`` function will be configured to respond as the default view
 callable for a Wiki resource.  We'll provide it with a ``@view_config``
 decorator which names the class ``tutorial.models.Wiki`` as its context.
@@ -84,16 +91,22 @@ The ``view_wiki`` view callable always redirects to the URL of a Page
 resource named "FrontPage".  To do so, it returns an instance of the
 :class:`pyramid.httpexceptions.HTTPFound` class (instances of which implement
 the :class:`pyramid.interfaces.IResponse` interface like
-:class:`pyramid.response.Response` does).  The
-:meth:`pyramid.request.Request.resource_url` API.
+:class:`pyramid.response.Response` does).
 :meth:`pyramid.request.Request.resource_url` constructs a URL to the
-``FrontPage`` page resource (e.g. ``http://localhost:6543/FrontPage``), and
+``FrontPage`` page resource (i.e., ``http://localhost:6543/FrontPage``), and
 uses it as the "location" of the HTTPFound response, forming an HTTP
 redirect.
 
 The ``view_page`` view function
 -------------------------------
 
+Here is the code for the ``view_page`` view function and its decorator, which
+will be added to ``views.py``:
+
+.. literalinclude:: src/views/tutorial/views.py
+   :lines: 16-33
+   :language: python
+
 The ``view_page`` function will be configured to respond as the default view
 of a Page resource.  We'll provide it with a ``@view_config`` decorator which
 names the class ``tutorial.models.Page`` as its context.  This means that
@@ -101,7 +114,7 @@ when a Page resource is the context, and no :term:`view name` exists in the
 request, this view will be used.  We inform :app:`Pyramid` this view will use
 the ``templates/view.pt`` template file as a ``renderer``.
 
-The ``view_page`` function generates the :term:`ReStructuredText` body of a
+The ``view_page`` function generates the :term:`reStructuredText` body of a
 page (stored as the ``data`` attribute of the context passed to the view; the
 context will be a Page resource) as HTML.  Then it substitutes an HTML anchor
 for each *WikiWord* reference in the rendered HTML using a compiled regular
@@ -140,6 +153,13 @@ callable.  In the ``view_wiki`` view callable, we unconditionally return a
 The ``add_page`` view function
 ------------------------------
 
+Here is the code for the ``add_page`` view function and its decorator, which
+will be added to ``views.py``:
+
+.. literalinclude:: src/views/tutorial/views.py
+   :lines: 35-50
+   :language: python
+
 The ``add_page`` function will be configured to respond when the context
 resource is a Wiki and the :term:`view name` is ``add_page``.  We'll provide
 it with a ``@view_config`` decorator which names the string ``add_page`` as
@@ -171,7 +191,7 @@ we're trying to add.
 If the view rendering is *not* a result of a form submission (if the
 expression ``'form.submitted' in request.params`` is ``False``), the view
 renders a template.  To do so, it generates a "save url" which the template
-use as the form post URL during rendering.  We're lazy here, so we're trying
+uses as the form post URL during rendering.  We're lazy here, so we're trying
 to use the same template (``templates/edit.pt``) for the add view as well as
 the page edit view.  To do so, we create a dummy Page resource object in
 order to satisfy the edit form's desire to have *some* page object exposed as
@@ -187,6 +207,13 @@ the page body, and save it into "our context" (the Wiki) using the
 The ``edit_page`` view function
 -------------------------------
 
+Here is the code for the ``edit_page`` view function and its decorator, which
+will be added to ``views.py``:
+
+.. literalinclude:: src/views/tutorial/views.py
+   :lines: 52-60
+   :language: python
+
 The ``edit_page`` function will be configured to respond when the context is
 a Page resource and the :term:`view name` is ``edit_page``.  We'll provide it
 with a ``@view_config`` decorator which names the string ``edit_page`` as its
diff --git a/pyramid/config/__init__.py b/pyramid/config/__init__.py
index d662c7d3a..e1320a55f 100644
--- a/pyramid/config/__init__.py
+++ b/pyramid/config/__init__.py
@@ -821,10 +821,8 @@ class Configurator(
 
     def with_package(self, package):
         """ Return a new Configurator instance with the same registry
-        as this configurator using the package supplied as the
-        ``package`` argument to the new configurator.  ``package`` may
-        be an actual Python package object or a :term:`dotted Python name`
-        representing a package."""
+        as this configurator. ``package`` may be an actual Python package
+        object or a :term:`dotted Python name` representing a package."""
         configurator = self.__class__(
             registry=self.registry,
             package=package,
diff --git a/pyramid/config/factories.py b/pyramid/config/factories.py
index ef7975d92..d30df3b74 100644
--- a/pyramid/config/factories.py
+++ b/pyramid/config/factories.py
@@ -182,9 +182,7 @@ class FactoriesConfiguratorMixin(object):
     def set_request_property(self, callable, name=None, reify=False):
         """ Add a property to the request object.
 
-        .. warning::
-
-           This method has been docs-deprecated as of Pyramid 1.4.
+        .. deprecated:: 1.4
            :meth:`pyramid.config.Configurator.add_request_method` should be
            used instead.
 
diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index 54bce6fd2..0a5ec9588 100644
--- a/pyramid/interfaces.py
+++ b/pyramid/interfaces.py
@@ -744,10 +744,8 @@ class IResourceURL(Interface):
 class IContextURL(IResourceURL):
     """ An adapter which deals with URLs related to a context.
 
-    ..warning::
-
-      This interface is deprecated as of Pyramid 1.3 with the introduction of
-      IResourceURL.
+    .. deprecated:: 1.3
+       use IResourceURL instead.
     """
     # this class subclasses IResourceURL because request.resource_url looks
     # for IResourceURL via queryAdapter.  queryAdapter will find a deprecated
@@ -792,7 +790,7 @@ deprecated(
     'scheduled to be removed.   Use the '
     '"pyramid.config.Configurator.add_resource_url_adapter" method to register '
     'a class that implements "pyramid.interfaces.IResourceURL" instead. '
-    'See the "What\'s new In Pyramid 1.3" document for a further description.'
+    'See the "What\'s new In Pyramid 1.3" document for more details.'
     )
 
 class IPackageOverrides(Interface):
diff --git a/pyramid/response.py b/pyramid/response.py
index 1dccb7ae8..0f61af472 100644
--- a/pyramid/response.py
+++ b/pyramid/response.py
@@ -35,20 +35,20 @@ class FileResponse(Response):
 
     ``path`` is a file path on disk.
 
-    ``request`` must be a Pyramid :term:`request` object if passed.  Note
+    ``request`` must be a Pyramid :term:`request` object.  Note
     that a request *must* be passed if the response is meant to attempt to
     use the ``wsgi.file_wrapper`` feature of the web server that you're using
     to serve your Pyramid application.
 
-    ``cache_max_age`` if passed, is the number of seconds that should be used
+    ``cache_max_age`` is the number of seconds that should be used
     to HTTP cache this response.
 
-    ``content_type``, if passed, is the content_type of the response.
+    ``content_type`` is the content_type of the response.
 
-    ``content_encoding``, if passed is the content_encoding of the response.
+    ``content_encoding`` is the content_encoding of the response.
     It's generally safe to leave this set to ``None`` if you're serving a
-    binary file.  This argument will be ignored if you don't also pass
-    ``content-type``.
+    binary file.  This argument will be ignored if you also leave
+    ``content-type`` as ``None``.
     """
     def __init__(self, path, request=None, cache_max_age=None,
                  content_type=None, content_encoding=None):