Merge branch 'master' into feature.instance-properties

13 files changed, 277 insertions, 69 deletions

diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index 9cb4db325..2949dc808 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -282,7 +282,7 @@ Pyramid application, and they want to customize the configuration of this
 application without hacking its code "from outside", they can "include" a
 configuration function from the package and override only some of its
 configuration statements within the code that does the include.  No conflicts
-will be generated by configuration statements within the code which does the
+will be generated by configuration statements within the code that does the
 including, even if configuration statements in the included code would
 conflict if it was moved "up" to the calling code.
 
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 886e075e3..3bdf8c5cd 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -349,7 +349,7 @@ setting) orderings using the ``ptweens`` command.  Tween factories
 will show up represented by their standard Python dotted name in the
 ``ptweens`` output.
 
-For example, here's the ``pwteens`` command run against a system
+For example, here's the ``ptweens`` command run against a system
 configured without any explicit tweens:
 
 .. code-block:: text
@@ -367,7 +367,7 @@ configured without any explicit tweens:
    1           pyramid.tweens.excview_tween_factory                excview
    -           -                                                   MAIN
 
-Here's the ``pwteens`` command run against a system configured *with*
+Here's the ``ptweens`` command run against a system configured *with*
 explicit tweens defined in its ``development.ini`` file:
 
 .. code-block:: text
@@ -460,7 +460,7 @@ to the console.
 
 You can add request header values by using the ``--header`` option::
 
-   $ bin/prequest --header=Host=example.com development.ini /
+   $ bin/prequest --header=Host:example.com development.ini /
 
 Headers are added to the WSGI environment by converting them to their
 CGI/WSGI equivalents (e.g. ``Host=example.com`` will insert the ``HTTP_HOST``
@@ -654,8 +654,11 @@ use the following command:
 
 .. code-block:: python
 
-   import logging.config
-   logging.config.fileConfig('/path/to/my/development.ini')
+   import pyramid.paster
+   pyramid.paster.setup_logging('/path/to/my/development.ini')
+
+See :ref:`logging_chapter` for more information on logging within
+:app:`Pyramid`.
 
 .. index::
    single: console script
@@ -718,7 +721,7 @@ we'll pretend you have a distribution with a package in it named
    def settings_show():
        description = """\
        Print the deployment settings for a Pyramid application.  Example:
-       'psettings deployment.ini'
+       'show_settings deployment.ini'
        """
        usage = "usage: %prog config_uri"
        parser = optparse.OptionParser(
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index 1ca188d7e..a86826d86 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -8,7 +8,8 @@ Creating Your First :app:`Pyramid` Application
 
 In this chapter, we will walk through the creation of a tiny :app:`Pyramid`
 application.  After we're finished creating the application, we'll explain in
-more detail how it works.
+more detail how it works. It assumes you already have :app:`Pyramid` installed.
+If you do not, head over to the :ref:`installing_chapter` section.
 
 .. _helloworld_imperative:
 
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index b6e3dd163..2c15cd690 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -145,7 +145,7 @@ the view which generates it can be overridden as necessary.
 
 The :term:`forbidden view` callable is a view callable like any other.  The
 :term:`view configuration` which causes it to be a "forbidden" view consists
-of using the meth:`pyramid.config.Configurator.add_forbidden_view` API or the
+of using the :meth:`pyramid.config.Configurator.add_forbidden_view` API or the
 :class:`pyramid.view.forbidden_view_config` decorator.
 
 For example, you can add a forbidden view by using the
@@ -171,7 +171,7 @@ as a forbidden view:
 
    from pyramid.view import forbidden_view_config
 
-   forbidden_view_config()
+   @forbidden_view_config()
    def forbidden(request):
        return Response('forbidden')
 
@@ -289,6 +289,36 @@ keys added to the renderer globals dictionary by all
 :class:`pyramid.events.BeforeRender` subscribers and renderer globals
 factories must be unique.
 
+The dictionary returned from the view is accessible through the
+:attr:`rendering_val` attribute of a :class:`~pyramid.events.BeforeRender`
+event.
+
+Suppose you return ``{'mykey': 'somevalue', 'mykey2': 'somevalue2'}`` from
+your view callable, like so:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.view import view_config
+
+   @view_config(renderer='some_renderer')
+   def myview(request):
+       return {'mykey': 'somevalue', 'mykey2': 'somevalue2'}
+
+:attr:`rendering_val` can be used to access these values from the
+:class:`~pyramid.events.BeforeRender` object:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.events import subscriber
+   from pyramid.events import BeforeRender
+
+   @subscriber(BeforeRender)
+   def read_return(event):
+       # {'mykey': 'somevalue'} is returned from the view
+       print(event.rendering_val['mykey'])
+
 See the API documentation for the :class:`~pyramid.events.BeforeRender` event
 interface at :class:`pyramid.interfaces.IBeforeRender`.
 
@@ -625,7 +655,7 @@ converts the arbitrary return value into something that implements
 :class:`~pyramid.interfaces.IResponse`.
 
 For example, if you'd like to allow view callables to return bare string
-objects (without requiring a a :term:`renderer` to convert a string to a
+objects (without requiring a :term:`renderer` to convert a string to a
 response object), you can register an adapter which converts the string to a
 Response:
 
@@ -1202,3 +1232,101 @@ Displaying Tween Ordering
 The ``ptweens`` command-line utility can be used to report the current
 implict and explicit tween chains used by an application.  See
 :ref:`displaying_tweens`.
+
+.. _registering_thirdparty_predicates:
+
+Adding A Third Party View or Route Predicate
+--------------------------------------------
+
+.. note::
+
+   Third-party predicates are a feature new as of Pyramid 1.4.
+
+View and route predicates used during view configuration allow you to narrow
+the set of circumstances under which a view or route will match.  For
+example, the ``request_method`` view predicate can be used to ensure a view
+callable is only invoked when the request's method is ``POST``:
+
+.. code-block:: python
+
+    @view_config(request_method='POST')
+    def someview(request):
+        ...
+
+Likewise, a similar predicate can be used as a *route* predicate:
+
+.. code-block:: python
+
+    config.add_route('name', '/foo', request_method='POST')
+
+Many other built-in predicates exists (``request_param``, and others).  You
+can add third-party predicates to the list of available predicates by using
+one of :meth:`pyramid.config.Configurator.add_view_predicate` or
+:meth:`pyramid.config.Configurator.add_route_predicate`.  The former adds a
+view predicate, the latter a route predicate.
+
+When using one of those APIs, you pass a *name* and a *factory* to add a
+predicate during Pyramid's configuration stage.  For example:
+
+.. code-block:: python
+
+    config.add_view_predicate('content_type', ContentTypePredicate)
+
+The above example adds a new predicate named ``content_type`` to the list of
+available predicates for views.  This will allow the following view
+configuration statement to work:
+
+.. code-block:: python
+   :linenos:
+
+   @view_config(content_type='File')
+   def aview(request): ...
+
+The first argument to :meth:`pyramid.config.Configurator.add_view_predicate`,
+the name, is a string representing the name that is expected to be passed to
+``view_config`` (or its imperative analogue ``add_view``).
+
+The second argument is a predicate factory.  A predicate factory is most
+often a class with a constructor (``__init__``), a ``text`` method, a
+``phash`` method and a ``__call__`` method.  For example:
+
+.. code-block:: python
+   :linenos:
+
+    class ContentTypePredicate(object):
+        def __init__(self, val, config):
+            self.val = val
+
+        def text(self):
+            return 'content_type = %s' % (self.val,)
+
+        phash = text
+
+        def __call__(self, context, request):
+            return getattr(context, 'content_type', None) == self.val
+
+The constructor of a predicate factory takes two arguments: ``val`` and
+``config``.  The ``val`` argument will be the argument passed to
+``view_config`` (or ``add_view``).  In the example above, it will be the
+string ``File``.  The second arg, ``config`` will be the Configurator
+instance at the time of configuration.
+
+The ``text`` method must return a string.  It should be useful to describe
+the behavior of the predicate in error messages.
+
+The ``phash`` method must return a string or a sequence of strings.  It's
+most often the same as ``text``, as long as ``text`` uniquely describes the
+predicate's name and the value passed to the constructor.  If ``text`` is
+more general, or doesn't describe things that way, ``phash`` should return a
+string with the name and the value serialized.  The result of ``phash`` is
+not seen in output anywhere, it just informs the uniqueness constraints for
+view configuration.
+
+The ``__call__`` method of a predicate factory must accept a resource
+(``context``) and a request, and must return ``True`` or ``False``.  It is
+the "meat" of the predicate.
+
+You can use the same predicate factory as both a view predicate and as a
+route predicate, but you'll need to call ``add_view_predicate`` and
+``add_route_predicate`` separately with the same factory.
+
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 8f7b17dc3..7c0f9223f 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -534,14 +534,14 @@ Configuration extensibility
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Unlike other systems, Pyramid provides a structured "include" mechanism (see
-:meth:`~pyramid.config.Configurator.include`) that allows you to compose
+:meth:`~pyramid.config.Configurator.include`) that allows you to combine
 applications from multiple Python packages.  All the configuration statements
 that can be performed in your "main" Pyramid application can also be
 performed by included packages including the addition of views, routes,
 subscribers, and even authentication and authorization policies. You can even
 extend or override an existing application by including another application's
 configuration in your own, overriding or adding new views and routes to
-it.  This has the potential to allow you to compose a big application out of
+it.  This has the potential to allow you to create a big application out of
 many other smaller ones.  For example, if you want to reuse an existing
 application that already has a bunch of routes, you can just use the
 ``include`` statement with a ``route_prefix``; the new application will live
@@ -593,11 +593,12 @@ it is to shoehorn a route into an ordered list of other routes, or to create
 another entire instance of an application to service a department and glue
 code to allow disparate apps to share data.  It's a great fit for sites that
 naturally lend themselves to changing departmental hierarchies, such as
-content management systems and document management systems.  Traversal also lends itself well to
-systems that require very granular security ("Bob can edit *this* document"
-as opposed to "Bob can edit documents").
+content management systems and document management systems.  Traversal also
+lends itself well to systems that require very granular security ("Bob can
+edit *this* document" as opposed to "Bob can edit documents").
 
-Example: :ref:`hello_traversal_chapter` and :ref:`much_ado_about_traversal_chapter`.
+Examples: :ref:`hello_traversal_chapter` and
+:ref:`much_ado_about_traversal_chapter`.
 
 Tweens
 ~~~~~~
@@ -801,6 +802,42 @@ within a function called when another user uses the
 
 See also :ref:`add_directive`.
 
+Programmatic Introspection
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're building a large system that other users may plug code into, it's
+useful to be able to get an enumeration of what code they plugged in *at
+application runtime*.  For example, you might want to show them a set of tabs
+at the top of the screen based on an enumeration of views they registered.
+
+This is possible using Pyramid's :term:`introspector`.
+
+Here's an example of using Pyramid's introspector from within a view
+callable:
+
+.. code-block:: python
+   :linenos:
+
+    from pyramid.view import view_config
+    from pyramid.response import Response
+
+    @view_config(route_name='bar')
+    def show_current_route_pattern(request):
+        introspector = request.registry.introspector
+        route_name = request.matched_route.name
+        route_intr = introspector.get('routes', route_name)
+        return Response(str(route_intr['pattern']))
+
+See also :ref:`using_introspection`.
+
+Python 3 Compatibility
+~~~~~~~~~~~~~~~~~~~~~~
+
+Pyramid and most of its add-ons are Python 3 compatible.  If you develop a
+Pyramid application today, you won't need to worry that five years from now
+you'll be backwatered because there are language features you'd like to use
+but your framework doesn't support newer Python versions.
+
 Testing
 ~~~~~~~
 
diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst
index 74595cac8..6bfaf11c0 100644
--- a/docs/narr/introspector.rst
+++ b/docs/narr/introspector.rst
@@ -32,7 +32,7 @@ callable:
     from pyramid.response import Response
 
     @view_config(route_name='bar')
-    def route_accepts(request):
+    def show_current_route_pattern(request):
         introspector = request.registry.introspector
         route_name = request.matched_route.name
         route_intr = introspector.get('routes', route_name)
diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst
index 044655c1f..f4c38abb6 100644
--- a/docs/narr/logging.rst
+++ b/docs/narr/logging.rst
@@ -14,7 +14,7 @@ how to send log messages to loggers that you've configured.
    which help configure logging.  All of the scaffolds which ship along with
    :app:`Pyramid` do this.  If you're not using a scaffold, or if you've used
    a third-party scaffold which does not create these files, the
-   configuration information in this chapter will not be applicable.
+   configuration information in this chapter may not be applicable.
 
 .. _logging_config:
 
@@ -36,10 +36,11 @@ application-related and logging-related sections in the configuration file
 can coexist peacefully, and the logging-related sections in the file are used
 from when you run ``pserve``.
 
-The ``pserve`` command calls the `logging.fileConfig function
+The ``pserve`` command calls the :func:`pyramid.paster.setup_logging`
+function, a thin wrapper around the `logging.fileConfig
 <http://docs.python.org/lib/logging-config-api.html>`_ using the specified
 ini file if it contains a ``[loggers]`` section (all of the
-scaffold-generated ``.ini`` files do). ``logging.fileConfig`` reads the
+scaffold-generated ``.ini`` files do). ``setup_logging`` reads the
 logging configuration from the ini file upon which ``pserve`` was
 invoked.
 
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 57073900f..1e2c225d2 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -144,13 +144,13 @@ directories which he creates within his ``~/projects`` directory.  On
 Windows, it's a good idea to put project directories within a directory that
 contains no space characters, so it's wise to *avoid* a path that contains
 i.e. ``My Documents``.  As a result, the author, when he uses Windows, just
-puts his projects in ``C:\\projects``.
+puts his projects in ``C:\projects``.
 
 .. warning:: 
 
    You’ll need to avoid using ``pcreate`` to create a project with the same
-   as a Python standard library component. In particular, this means you
-   should avoid using names the names ``site`` or ``test``, both of which
+   name as a Python standard library component. In particular, this means you
+   should avoid using the names ``site`` or ``test``, both of which
    conflict with Python standard library packages.  You should also avoid
    using the name ``pyramid``, which will conflict with Pyramid itself.
 
@@ -447,7 +447,7 @@ first column instead, for example like this:
    pyramid.includes =
        #pyramid_debugtoolbar
 
-When you attempt to restart the application with a section like the abvoe
+When you attempt to restart the application with a section like the above
 you'll receive an error that ends something like this, and the application
 will not start:
 
@@ -684,7 +684,7 @@ testing your application, packaging, and distributing your application.
 
 .. note::
 
-  ``setup.py`` is the defacto standard which Python developers use to
+  ``setup.py`` is the de facto standard which Python developers use to
   distribute their reusable code.  You can read more about ``setup.py`` files
   and their usage in the `Setuptools documentation
   <http://peak.telecommunity.com/DevCenter/setuptools>`_ and `The
@@ -966,7 +966,7 @@ named ``views`` instead of within a single ``views.py`` file, you might:
 You can then continue to add view callable functions to the ``blog.py``
 module, but you can also add other ``.py`` files which contain view callable
 functions to the ``views`` directory.  As long as you use the
-``@view_config`` directive to register views in conjuction with
+``@view_config`` directive to register views in conjunction with
 ``config.scan()`` they will be picked up automatically when the application
 is restarted.
 
@@ -994,7 +994,7 @@ run a :app:`Pyramid` application is purely conventional based on the output
 of its scaffolding.  But we strongly recommend using while developing your
 application, because many other convenience introspection commands (such as
 ``pviews``, ``prequest``, ``proutes`` and others) are also implemented in
-terms of configuration availaibility of this ``.ini`` file format.  It also
+terms of configuration availability of this ``.ini`` file format.  It also
 configures Pyramid logging and provides the ``--reload`` switch for
 convenient restarting of the server when code changes.
 
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 34bee3c7f..57b5bc65b 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -177,13 +177,15 @@ using the API of the ``request.response`` attribute.  See
 .. index::
    pair: renderer; JSON
 
+.. _json_renderer:
+
 JSON Renderer
 ~~~~~~~~~~~~~
 
-The ``json`` renderer renders view callable results to :term:`JSON`.  It
-passes the return value through the ``json.dumps`` standard library function,
-and wraps the result in a response object.  It also sets the response
-content-type to ``application/json``.
+The ``json`` renderer renders view callable results to :term:`JSON`.  By
+default, it passes the return value through the ``json.dumps`` standard
+library function, and wraps the result in a response object.  It also sets
+the response content-type to ``application/json``.
 
 Here's an example of a view that returns a dictionary.  Since the ``json``
 renderer is specified in the configuration for this view, the view will
@@ -207,11 +209,11 @@ representing the JSON serialization of the return value:
    '{"content": "Hello!"}'
 
 The return value needn't be a dictionary, but the return value must contain
-values serializable by ``json.dumps``.
+values serializable by the configured serializer (by default ``json.dumps``).
 
 .. note::
 
-   Extra arguments can be passed to ``json.dumps`` by overriding the default
+   Extra arguments can be passed to the serializer by overriding the default
    ``json`` renderer. See :class:`pyramid.renderers.JSON` and
    :ref:`adding_and_overriding_renderers` for more information.
 
@@ -223,9 +225,9 @@ You can configure a view to use the JSON renderer by naming ``json`` as the
    :linenos:
 
    config.add_view('myproject.views.hello_world',
-                    name='hello',
-                    context='myproject.resources.Hello',
-                    renderer='json')
+                   name='hello',
+                   context='myproject.resources.Hello',
+                   renderer='json')
 
 Views which use the JSON renderer can vary non-body response attributes by
 using the api of the ``request.response`` attribute.  See
@@ -238,8 +240,9 @@ Serializing Custom Objects
 
 Custom objects can be made easily JSON-serializable in Pyramid by defining a
 ``__json__`` method on the object's class. This method should return values
-natively serializable by ``json.dumps`` (such as ints, lists, dictionaries,
-strings, and so forth).
+natively JSON-serializable (such as ints, lists, dictionaries, strings, and
+so forth).  It should accept a single additional argument, ``request``, which
+will be the active request object at render time.
 
 .. code-block:: python
    :linenos:
@@ -250,7 +253,7 @@ strings, and so forth).
        def __init__(self, x):
            self.x = x
 
-       def __json__(self):
+       def __json__(self, request):
            return {'x':self.x}
 
    @view_config(renderer='json')
@@ -260,20 +263,40 @@ strings, and so forth).
    # the JSON value returned by ``objects`` will be:
    #    [{"x": 1}, {"x": 2}]
 
-.. note::
+If you aren't the author of the objects being serialized, it won't be
+possible (or at least not reasonable) to add a custom ``__json__`` method to
+to their classes in order to influence serialization.  If the object passed
+to the renderer is not a serializable type, and has no ``__json__`` method,
+usually a :exc:`TypeError` will be raised during serialization.  You can
+change this behavior by creating a custom JSON renderer and adding adapters
+to handle custom types. The renderer will attempt to adapt non-serializable
+objects using the registered adapters. A short example follows:
+
+.. code-block:: python
+   :linenos:
 
-   Honoring the ``__json__`` method of custom objects is a feature new in
-   Pyramid 1.4.
+   from pyramid.renderers import JSON
 
-.. warning::
+   json_renderer = JSON()
+   def datetime_adapter(obj, request):
+       return obj.isoformat()
+   json_renderer.add_adapter(datetime.datetime, datetime_adapter)
+
+   # then during configuration ....
+   config = Configurator()
+   config.add_renderer('json', json_renderer)
+
+The adapter should accept two arguments: the object needing to be serialized
+and ``request``, which will be the current request object at render time.
+The adapter should raise a :exc:`TypeError` if it can't determine what to do
+with the object.
+
+See :class:`pyramid.renderers.JSON` and
+:ref:`adding_and_overriding_renderers` for more information.
+
+.. note::
 
-   The machinery which performs the ``__json__`` method-calling magic is in
-   the :class:`pyramid.renderers.ObjectJSONEncoder` class.  This class will
-   be used for encoding any non-basic Python object when you use the default
-   ```json`` or ``jsonp`` renderers.  But if you later define your own custom
-   JSON renderer and pass it a "cls" argument signifying a different encoder,
-   the encoder you pass will override Pyramid's use of
-   :class:`pyramid.renderers.ObjectJSONEncoder`.
+   Serializing custom objects is a feature new in Pyramid 1.4.
 
 .. index::
    pair: renderer; JSONP
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index 6ff9e3dea..1aa1b6341 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -151,13 +151,12 @@ Using Alternate Session Factories
 ---------------------------------
 
 At the time of this writing, exactly one alternate session factory
-implementation exists, named ``pyramid_beaker``. This is a session
-factory that uses the `Beaker <http://beaker.groovie.org/>`_ library
-as a backend.  Beaker has support for file-based sessions, database
-based sessions, and encrypted cookie-based sessions.  See
-`http://github.com/Pylons/pyramid_beaker
-<http://github.com/Pylons/pyramid_beaker>`_ for more information about
-``pyramid_beaker``.
+implementation exists, named ``pyramid_beaker``. This is a session factory
+that uses the `Beaker <http://beaker.groovie.org/>`_ library as a backend.
+Beaker has support for file-based sessions, database based sessions, and
+encrypted cookie-based sessions.  See `the pyramid_beaker documentation
+<http://docs.pylonsproject.org/projects/pyramid_beaker/en/latest/>`_ for more
+information about ``pyramid_beaker``.
 
 .. index::
    single: session factory (custom)
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index 8e28835af..f5c741f52 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -42,8 +42,8 @@ Here's a high-level time-ordered overview of what happens when you press
    ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file.  This
    section represents the configuration of a :term:`WSGI` application that
    will be served.  If you're using a simple application (e.g.
-   ``[app:main]``), the application :term:`entry point` or :term:`dotted
-   Python name` will be named on the ``use=`` line within the section's
+   ``[app:main]``), the application's ``paste.app_factory`` :term:`entry
+   point` will be named on the ``use=`` line within the section's
    configuration.  If, instead of a simple application, you're using a WSGI
    :term:`pipeline` (e.g. a ``[pipeline:main]`` section), the application
    named on the "last" element will refer to your :app:`Pyramid` application.
@@ -59,11 +59,11 @@ Here's a high-level time-ordered overview of what happens when you press
    system for this application.  See :ref:`logging_config` for more
    information.
 
-#. The application's *constructor* named by the entry point reference or
-   dotted Python name on the ``use=`` line of the section representing your
-   :app:`Pyramid` application is passed the key/value parameters mentioned
-   within the section in which it's defined.  The constructor is meant to
-   return a :term:`router` instance, which is a :term:`WSGI` application.
+#. The application's *constructor* named by the entry point reference on the
+   ``use=`` line of the section representing your :app:`Pyramid` application
+   is passed the key/value parameters mentioned within the section in which
+   it's defined.  The constructor is meant to return a :term:`router`
+   instance, which is a :term:`WSGI` application.
 
    For :app:`Pyramid` applications, the constructor will be a function named
    ``main`` in the ``__init__.py`` file within the :term:`package` in which
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 9db0b1c4d..860010a1a 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -714,6 +714,22 @@ This template doesn't use any advanced features of Mako, only the
 :term:`renderer globals`.  See the `the Mako documentation
 <http://www.makotemplates.org/>`_ to use more advanced features.
 
+Using def inside Mako Templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use a def inside a Mako template, given a :term:`Mako` template file named 
+``foo.mak`` and a def named ``bar``, you can configure the template as a 
+:term:`renderer` like so:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.view import view_config
+
+   @view_config(renderer='foo#bar.mak')
+   def my_view(request):
+       return {'project':'my project'}
+
 .. index::
    single: automatic reloading of templates
    single: template automatic reload
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index f036ce94e..ecf3d026a 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -547,7 +547,7 @@ add to your application:
 
    config.add_route('idea', 'ideas/{idea}')
    config.add_route('user', 'users/{user}')
-   config.add_route('tag', 'tags/{tags}')
+   config.add_route('tag', 'tags/{tag}')
 
    config.add_view('mypackage.views.idea_view', route_name='idea')
    config.add_view('mypackage.views.user_view', route_name='user')
@@ -954,7 +954,7 @@ will be prepended with the first:
    from pyramid.config import Configurator
 
    def timing_include(config):
-       config.add_route('show_times', /times')
+       config.add_route('show_times', '/times')
 
    def users_include(config):
        config.add_route('show_users', '/show')
@@ -966,7 +966,7 @@ will be prepended with the first:
 
 In the above configuration, the ``show_users`` route will still have an
 effective route pattern of ``/users/show``.  The ``show_times`` route
-however, will have an effective pattern of ``/users/timing/show_times``.
+however, will have an effective pattern of ``/users/timing/times``.
 
 Route prefixes have no impact on the requirement that the set of route
 *names* in any given Pyramid configuration must be entirely unique.  If you
@@ -981,7 +981,7 @@ that may be added in the future.  For example:
    from pyramid.config import Configurator
 
    def timing_include(config):
-       config.add_route('timing.show_times', /times')
+       config.add_route('timing.show_times', '/times')
 
    def users_include(config):
        config.add_route('users.show_users', '/show')