21 files changed, 186 insertions, 107 deletions
diff --git a/docs/narr/events.rst b/docs/narr/events.rst
index 2accb3dbe..50484761d 100644
--- a/docs/narr/events.rst
+++ b/docs/narr/events.rst
@@ -172,7 +172,7 @@ track of the information that subscribers will need. Here are some
 example custom event classes:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     class DocCreated(object):
         def __init__(self, doc, request):
@@ -196,7 +196,7 @@ also use custom events with :ref:`subscriber predicates
 event with a decorator:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.events import subscriber
     from .events import DocCreated
@@ -215,7 +215,7 @@ To fire your custom events use the
 accessed as ``request.registry.notify``. For example:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from .events import DocCreated
 
diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst
index a60a49fea..8462a9da7 100644
--- a/docs/narr/extending.rst
+++ b/docs/narr/extending.rst
@@ -234,7 +234,7 @@ For example, if the original application has the following
 ``configure_views`` configuration method:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     def configure_views(config):
         config.add_view('theoriginalapp.views.theview', name='theview')
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 0c450fad7..f2542f1d7 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -363,7 +363,7 @@ and modify the set of :term:`renderer globals` before they are passed to a
 that can be used for this purpose.  For example:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.events import subscriber
     from pyramid.events import BeforeRender
@@ -963,8 +963,8 @@ For full details, please read the `Venusian documentation
 
 .. _registering_tweens:
 
-Registering "Tweens"
---------------------
+Registering Tweens
+------------------
 
 .. versionadded:: 1.2
    Tweens
@@ -976,26 +976,80 @@ feature that may be used by Pyramid framework extensions, to provide, for
 example, Pyramid-specific view timing support bookkeeping code that examines
 exceptions before they are returned to the upstream WSGI application.  Tweens
 behave a bit like :term:`WSGI` :term:`middleware` but they have the benefit of
-running in a context in which they have access to the Pyramid
-:term:`application registry` as well as the Pyramid rendering machinery.
+running in a context in which they have access to the Pyramid :term:`request`,
+:term:`response` and :term:`application registry` as well as the Pyramid
+rendering machinery.
 
-Creating a Tween Factory
-~~~~~~~~~~~~~~~~~~~~~~~~
+Creating a Tween
+~~~~~~~~~~~~~~~~
 
-To make use of tweens, you must construct a "tween factory".  A tween factory
+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
 Pyramid request handling function or another tween.  ``registry`` will be the
 Pyramid :term:`application registry` represented by this Configurator.  A
-tween factory must return a tween when it is called.
+tween factory must return the tween (a callable object) when it is called.
 
-A tween is a callable which accepts a :term:`request` object and returns
-a :term:`response` object.
+A tween is called with a single argument, ``request``, which is the
+:term:`request` created by Pyramid's router when it receives a WSGI request.
+A tween should return a :term:`response`, usually the one generated by the
+downstream Pyramid application.
 
-Here's an example of a tween factory:
+You can write the tween factory as a simple closure-returning function:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
+
+    def simple_tween_factory(handler, registry):
+        # one-time configuration code goes here
+
+        def simple_tween(request):
+            # code to be executed for each request before
+            # the actual application code goes here
+
+            response = handler(request)
+
+            # code to be executed for each request after
+            # the actual application code goes here
+
+            return response
+
+        return simple_tween
+
+Alternatively, the tween factory can be a class with the ``__call__`` magic
+method:
+
+.. code-block:: python
+    :linenos:
+
+    class simple_tween_factory(object):
+        def __init__(handler, registry):
+            self.handler = handler
+            self.registry = registry
+
+            # one-time configuration code goes here
+
+        def __call__(self, request):
+            # code to be executed for each request before
+            # the actual application code goes here
+
+            response = self.handler(request)
+
+            # code to be executed for each request after
+            # the actual application code goes here
+
+            return response
+
+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
+state, and it allows subclassing.
+
+Here's a complete example of a tween that logs the time spent processing each
+request:
+
+.. code-block:: python
+    :linenos:
 
     # in a module named myapp.tweens
 
@@ -1022,12 +1076,6 @@ Here's an example of a tween factory:
         # handler
         return handler
 
-If you remember, a tween is an object which accepts a :term:`request` object
-and which returns a :term:`response` argument.  The ``request`` argument to a
-tween will be the request created by Pyramid's router when it receives a WSGI
-request.  The response object will be generated by the downstream Pyramid
-application and it should be returned by the tween.
-
 In the above example, the tween factory defines a ``timing_tween`` tween and
 returns it if ``asbool(registry.settings.get('do_timing'))`` is true.  It
 otherwise simply returns the handler it was given.  The ``registry.settings``
@@ -1053,7 +1101,7 @@ Here's an example of registering a tween factory as an "implicit" tween in a
 Pyramid application:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.config import Configurator
     config = Configurator()
@@ -1087,7 +1135,7 @@ chain (the tween generated by the very last tween factory added) as its
 request handler function.  For example:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.config import Configurator
 
@@ -1132,8 +1180,10 @@ Allowable values for ``under`` or ``over`` (or both) are:
   fallbacks if the desired tween is not included, as well as compatibility
   with multiple other tweens.
 
-Effectively, ``under`` means "closer to the main Pyramid application than",
-``over`` means "closer to the request ingress than".
+Effectively, ``over`` means "closer to the request ingress than" and
+``under`` means "closer to the main Pyramid application than".
+You can think of an onion with outer layers over the inner layers,
+the application being under all the layers at the center.
 
 For example, the following call to
 :meth:`~pyramid.config.Configurator.add_tween` will attempt to place the
@@ -1329,7 +1379,7 @@ route predicate factory is most often a class with a constructor
 method. For example:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     class ContentTypePredicate(object):
         def __init__(self, val, config):
@@ -1392,7 +1442,7 @@ with a subscriber that subscribes to the :class:`pyramid.events.NewRequest`
 event type.
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     class RequestPathStartsWith(object):
         def __init__(self, val, config):
@@ -1421,7 +1471,7 @@ previously registered ``request_path_startswith`` predicate in a call to
 :meth:`~pyramid.config.Configurator.add_subscriber`:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     # define a subscriber in your code
 
@@ -1437,7 +1487,7 @@ Here's the same subscriber/predicate/event-type combination used via
 :class:`~pyramid.events.subscriber`.
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.events import subscriber
 
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index a29ccb2ac..4a3258d35 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -63,7 +63,7 @@ An application that uses only traversal will have view configuration
 declarations that look like this:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     # config is an instance of pyramid.config.Configurator
 
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index b62c16ff0..c9b782c08 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -309,7 +309,7 @@ In particular, add the ``Babel`` and ``lingua`` distributions to the
 application's ``setup.py`` file:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     setup(name="mypackage",
           # ...
@@ -370,7 +370,7 @@ file of a ``pcreate`` -generated :app:`Pyramid` application has stanzas in it
 that look something like the following:
 
 .. code-block:: ini
-   :linenos:
+    :linenos:
 
     [compile_catalog]
     directory = myproject/locale
@@ -398,7 +398,7 @@ that you'd like the domain of your translations to be ``mydomain``
 instead, change the ``setup.cfg`` file stanzas to look like so:
 
 .. code-block:: ini
-   :linenos:
+    :linenos:
 
     [compile_catalog]
     directory = myproject/locale
@@ -1041,7 +1041,7 @@ if no locale can be determined.
 Here's an implementation of a simple locale negotiator:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     def my_locale_negotiator(request):
         locale_name = request.params.get('my_locale')
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index a9c5fdfbd..8acbab3a0 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -336,7 +336,7 @@ For example, instead of returning a ``Response`` object from a
 ``render_to_response`` call:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.renderers import render_to_response
 
@@ -347,7 +347,7 @@ For example, instead of returning a ``Response`` object from a
 You can return a Python dictionary:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.view import view_config
 
@@ -827,7 +827,7 @@ Here's an example of using Pyramid's introspector from within a view
 callable:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.view import view_config
     from pyramid.response import Response
diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst
index 3c0a6744f..a7bde4cf7 100644
--- a/docs/narr/introspector.rst
+++ b/docs/narr/introspector.rst
@@ -24,7 +24,7 @@ Here's an example of using Pyramid's introspector from within a view
 callable:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.view import view_config
     from pyramid.response import Response
@@ -100,7 +100,7 @@ its ``__getitem__``, ``get``, ``keys``, ``values``, or ``items`` methods.
 For example:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     route_intr = introspector.get('routes', 'edit_user')
     pattern = route_intr['pattern']
diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst
index b3bfb8a1e..75428d513 100644
--- a/docs/narr/logging.rst
+++ b/docs/narr/logging.rst
@@ -179,7 +179,7 @@ file, simply create a logger object using the ``__name__`` builtin and call
 methods on it.
 
 .. code-block:: python 
-   :linenos:
+    :linenos:
 
     import logging 
     log = logging.getLogger(__name__) 
diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst
index 3427b6d53..f1fb70869 100644
--- a/docs/narr/paste.rst
+++ b/docs/narr/paste.rst
@@ -87,7 +87,7 @@ configuration object and *returns* an instance of our application.
 
 .. _defaults_section_of_pastedeploy_file:
 
-``[DEFAULTS]`` Section of a PasteDeploy ``.ini`` File
+``[DEFAULT]`` Section of a PasteDeploy ``.ini`` File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can add a ``[DEFAULT]`` section to your PasteDeploy ``.ini`` file.  Such
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 740c81555..4f8c4bf77 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -480,8 +480,11 @@ Adding a New Renderer
 You may add a new renderer by creating and registering a :term:`renderer
 factory`.
 
-A renderer factory implementation is typically a class with the
-following interface:
+A renderer factory implementation should conform to the
+:class:`pyramid.interfaces.IRendererFactory` interface. It should be capable
+of creating an object that conforms to the
+:class:`pyramid.interfaces.IRenderer` interface. A typical class that follows
+this setup is as follows:
 
 .. code-block:: python
    :linenos:
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index b1bb611e5..f3ff1dc4c 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -83,7 +83,7 @@ works against resource instances.
 Here's a sample resource tree, represented by a variable named ``root``:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     class Resource(dict):
         pass
@@ -201,7 +201,7 @@ location-aware resources.  These APIs include (but are not limited to)
 :func:`~pyramid.traversal.resource_path`,
 :func:`~pyramid.traversal.resource_path_tuple`, or
 :func:`~pyramid.traversal.traverse`, :func:`~pyramid.traversal.virtual_root`,
-and (usually) :func:`~pyramid.security.has_permission` and
+and (usually) :meth:`~pyramid.request.Request.has_permission` and
 :func:`~pyramid.security.principals_allowed_by_permission`.
 
 In general, since so much :app:`Pyramid` infrastructure depends on
@@ -695,10 +695,10 @@ The APIs provided by :ref:`location_module` are used against resources.
 These can be used to walk down a resource tree, or conveniently locate one
 resource "inside" another.
 
-Some APIs in :ref:`security_module` accept a resource object as a parameter.
-For example, the :func:`~pyramid.security.has_permission` API accepts a
+Some APIs on the :class:`pyramid.request.Request` accept a resource object as a parameter.
+For example, the :meth:`~pyramid.request.Request.has_permission` API accepts a
 resource object as one of its arguments; the ACL is obtained from this
-resource or one of its ancestors.  Other APIs in the :mod:`pyramid.security`
-module also accept :term:`context` as an argument, and a context is always a
-resource.
+resource or one of its ancestors.  Other security related APIs on the 
+:class:`pyramid.request.Request` class also accept :term:`context` as an argument, 
+and a context is always a resource.
 
diff --git a/docs/narr/scaffolding.rst b/docs/narr/scaffolding.rst
index 534b2caf4..f924d0d62 100644
--- a/docs/narr/scaffolding.rst
+++ b/docs/narr/scaffolding.rst
@@ -39,9 +39,9 @@ named ``__init__.py`` with something like the following:
 
    from pyramid.scaffolds import PyramidTemplate
 
-     class CoolExtensionTemplate(PyramidTemplate):
-         _template_dir = 'coolextension_scaffold'
-         summary = 'My cool extension'
+   class CoolExtensionTemplate(PyramidTemplate):
+       _template_dir = 'coolextension_scaffold'
+       summary = 'My cool extension'
 
 Once this is done, within the ``scaffolds`` directory, create a template
 directory.  Our example used a template directory named
@@ -89,7 +89,7 @@ For example:
             [pyramid.scaffold]
             coolextension=coolextension.scaffolds:CoolExtensionTemplate
           """
-         )
+        )
 
 Run your distribution's ``setup.py develop`` or ``setup.py install``
 command. After that, you should be able to see your scaffolding template
@@ -112,7 +112,7 @@ want to have extension scaffolds that can work across Pyramid 1.0.X, 1.1.X,
 defining your scaffold template:
 
 .. code-block:: python
-   :linenos:
+     :linenos:
 
      try: # pyramid 1.0.X
          # "pyramid.paster.paste_script..." doesn't exist past 1.0.X
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 6517fedf8..9e6fb6c82 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -550,7 +550,7 @@ also contain security debugging information in its body.
 Debugging Imperative Authorization Failures
 -------------------------------------------
 
-The :func:`pyramid.security.has_permission` API is used to check
+The :meth:`pyramid.request.Request.has_permission` API is used to check
 security within view functions imperatively.  It returns instances of
 objects that are effectively booleans.  But these objects are not raw
 ``True`` or ``False`` objects, and have information attached to them
@@ -563,7 +563,7 @@ one of :data:`pyramid.security.ACLAllowed`,
 ``msg`` attribute, which is a string indicating why the permission was
 denied or allowed.  Introspecting this information in the debugger or
 via print statements when a call to
-:func:`~pyramid.security.has_permission` fails is often useful.
+:meth:`~pyramid.request.Request.has_permission` fails is often useful.
 
 .. index::
    single: authentication policy (creating)
@@ -669,3 +669,31 @@ following interface:
 After you do so, you can pass an instance of such a class into the
 :class:`~pyramid.config.Configurator.set_authorization_policy` method at
 configuration time to use it.
+
+.. _admonishment_against_secret_sharing:
+
+Admonishment Against Secret-Sharing
+-----------------------------------
+
+A "secret" is required by various components of Pyramid.  For example, the
+:term:`authentication policy` below uses a secret value ``seekrit``::
+
+  authn_policy = AuthTktAuthenticationPolicy('seekrit', hashalg='sha512')
+
+A :term:`session factory` also requires a secret::
+
+  my_session_factory = SignedCookieSessionFactory('itsaseekreet')
+
+It is tempting to use the same secret for multiple Pyramid subsystems.  For
+example, you might be tempted to use the value ``seekrit`` as the secret for
+both the authentication policy and the session factory defined above.  This is
+a bad idea, because in both cases, these secrets are used to sign the payload
+of the data.
+
+If you use the same secret for two different parts of your application for
+signing purposes, it may allow an attacker to get his chosen plaintext signed,
+which would allow the attacker to control the content of the payload.  Re-using
+a secret across two different subsystems might drop the security of signing to
+zero. Keys should not be re-used across different contexts where an attacker
+has the possibility of providing a chosen plaintext.
+
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index f33bc6132..fb5035373 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -43,24 +43,23 @@ limitations:
 It is digitally signed, however, and thus its data cannot easily be
 tampered with.
 
-You can configure this session factory in your :app:`Pyramid`
-application by using the ``session_factory`` argument to the
-:class:`~pyramid.config.Configurator` class:
+You can configure this session factory in your :app:`Pyramid` application
+by using the :meth:`pyramid.config.Configurator.set_session_factory`` method.
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.session import UnencryptedCookieSessionFactoryConfig
-   my_session_factory = UnencryptedCookieSessionFactoryConfig('itsaseekreet')
-   
+   from pyramid.session import SignedCookieSessionFactory
+   my_session_factory = SignedCookieSessionFactory('itsaseekreet')
+
    from pyramid.config import Configurator
-   config = Configurator(session_factory = my_session_factory)
+   config = Configurator()
+   config.set_session_factory(my_session_factory)
 
 .. warning:: 
 
-   Note the very long, very explicit name for
-   ``UnencryptedCookieSessionFactoryConfig``.  It's trying to tell you that
-   this implementation is, by default, *unencrypted*.  You should not use it
+   By default the :func:`~pyramid.session.SignedCookieSessionFactory`
+   implementation is *unencrypted*.  You should not use it
    when you keep sensitive information in the session object, as the
    information can be easily read by both users of your application and third
    parties who have access to your users' network traffic.  And if you use this
diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst
index 88d6904c7..5a5bf8fad 100644
--- a/docs/narr/testing.rst
+++ b/docs/narr/testing.rst
@@ -214,11 +214,10 @@ function.
 .. code-block:: python
    :linenos:
 
-   from pyramid.security import has_permission
    from pyramid.httpexceptions import HTTPForbidden
 
    def view_fn(request):
-       if not has_permission('edit', request.context, request):
+       if request.has_permission('edit'):
            raise HTTPForbidden
        return {'greeting':'hello'}
 
@@ -229,15 +228,16 @@ function.
    otherwise it would fail when run normally.
 
 Without doing anything special during a unit test, the call to
-:func:`~pyramid.security.has_permission` in this view function will always
-return a ``True`` value.  When a :app:`Pyramid` application starts normally,
-it will populate a :term:`application registry` using :term:`configuration
-declaration` calls made against a :term:`Configurator`.  But if this
-application registry is not created and populated (e.g. by initializing the
-configurator with an authorization policy), like when you invoke application
-code via a unit test, :app:`Pyramid` API functions will tend to either fail
-or return default results.  So how do you test the branch of the code in this
-view function that raises :exc:`~pyramid.httpexceptions.HTTPForbidden`?
+:meth:`~pyramid.request.Request.has_permission` in this view function will
+always return a ``True`` value.  When a :app:`Pyramid` application starts
+normally, it will populate a :term:`application registry` using
+:term:`configuration declaration` calls made against a :term:`Configurator`.
+But if this application registry is not created and populated (e.g. by
+initializing the configurator with an authorization policy), like when you
+invoke application code via a unit test, :app:`Pyramid` API functions will tend
+to either fail or return default results.  So how do you test the branch of the
+code in this view function that raises
+:exc:`~pyramid.httpexceptions.HTTPForbidden`?
 
 The testing API provided by :app:`Pyramid` allows you to simulate various
 application registry registrations for use under a unit testing framework
@@ -287,12 +287,12 @@ Its third line registers a "dummy" "non-permissive" authorization policy
 using the :meth:`~pyramid.config.Configurator.testing_securitypolicy` method,
 which is a special helper method for unit testing.
 
-We then create a :class:`pyramid.testing.DummyRequest` object which simulates
-a WebOb request object API.  A :class:`pyramid.testing.DummyRequest` is a
-request object that requires less setup than a "real" :app:`Pyramid` request.
-We call the function being tested with the manufactured request.  When the
-function is called, :func:`pyramid.security.has_permission` will call the
-"dummy" authentication policy we've registered through
+We then create a :class:`pyramid.testing.DummyRequest` object which simulates a
+WebOb request object API.  A :class:`pyramid.testing.DummyRequest` is a request
+object that requires less setup than a "real" :app:`Pyramid` request.  We call
+the function being tested with the manufactured request.  When the function is
+called, :meth:`pyramid.request.Request.has_permission` will call the "dummy"
+authentication policy we've registered through
 :meth:`~pyramid.config.Configurator.testing_securitypolicy`, which denies
 access.  We check that the view function raises a
 :exc:`~pyramid.httpexceptions.HTTPForbidden` error.
diff --git a/docs/narr/threadlocals.rst b/docs/narr/threadlocals.rst
index a90ee4905..afe56de3e 100644
--- a/docs/narr/threadlocals.rst
+++ b/docs/narr/threadlocals.rst
@@ -29,17 +29,16 @@ of a thread local or a global is usually just a way to avoid passing
 some value around between functions, which is itself usually a very
 bad idea, at least if code readability counts as an important concern.
 
-For historical reasons, however, thread local variables are indeed
-consulted by various :app:`Pyramid` API functions.  For example,
-the implementation of the :mod:`pyramid.security` function named
-:func:`~pyramid.security.authenticated_userid` retrieves the thread
-local :term:`application registry` as a matter of course to find an
+For historical reasons, however, thread local variables are indeed consulted by
+various :app:`Pyramid` API functions.  For example, the implementation of the
+:mod:`pyramid.security` function named
+:func:`~pyramid.security.authenticated_userid` (deprecated as of 1.5) retrieves
+the thread local :term:`application registry` as a matter of course to find an
 :term:`authentication policy`.  It uses the
-:func:`pyramid.threadlocal.get_current_registry` function to
-retrieve the application registry, from which it looks up the
-authentication policy; it then uses the authentication policy to
-retrieve the authenticated user id.  This is how :app:`Pyramid`
-allows arbitrary authentication policies to be "plugged in".
+:func:`pyramid.threadlocal.get_current_registry` function to retrieve the
+application registry, from which it looks up the authentication policy; it then
+uses the authentication policy to retrieve the authenticated user id.  This is
+how :app:`Pyramid` allows arbitrary authentication policies to be "plugged in".
 
 When they need to do so, :app:`Pyramid` internals use two API
 functions to retrieve the :term:`request` and :term:`application
diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst
index 64343ca3e..eb3194a65 100644
--- a/docs/narr/upgrading.rst
+++ b/docs/narr/upgrading.rst
@@ -137,7 +137,7 @@ In the above case, it's line #3 in the ``myproj.views`` module (``from
 pyramid.view import static``) that is causing the problem:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.view import view_config
 
@@ -148,7 +148,7 @@ The deprecation warning tells me how to fix it, so I can change the code to
 do things the newer way:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     from pyramid.view import view_config
 
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 61849c3c0..96ee5758e 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -492,7 +492,7 @@ The simplest route declaration which configures a route match to *directly*
 result in a particular view callable being invoked:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     config.add_route('idea', 'site/{id}')
     config.add_view('mypackage.views.site_view', route_name='idea')
@@ -901,7 +901,7 @@ Details of the route matching decision for a particular request to the
 which you started the application from.  For example:
 
 .. code-block:: text
-   :linenos:
+    :linenos:
 
     $ PYRAMID_DEBUG_ROUTEMATCH=true $VENV/bin/pserve development.ini
     Starting server in PID 13586.
@@ -1060,7 +1060,7 @@ A custom route predicate may also *modify* the ``match`` dictionary.  For
 instance, a predicate might do some type conversion of values:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     def integers(*segment_names):
         def predicate(info, request):
@@ -1086,7 +1086,7 @@ To avoid the try/except uncertainty, the route pattern can contain regular
 expressions specifying requirements for that marker. For instance:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     def integers(*segment_names):
         def predicate(info, request):
@@ -1128,7 +1128,7 @@ name.  The ``pattern`` attribute is the route pattern.  An example of using
 the route in a set of route predicates:
 
 .. code-block:: python
-   :linenos:
+    :linenos:
 
     def twenty_ten(info, request):
         if info['route'].name in ('ymd', 'ym', 'y'):
diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst
index d37518052..53f6888b3 100644
--- a/docs/narr/vhosting.rst
+++ b/docs/narr/vhosting.rst
@@ -109,7 +109,7 @@ An example of an Apache ``mod_proxy`` configuration that will host the
 is below:
 
 .. code-block:: apache
-   :linenos:
+    :linenos:
 
     NameVirtualHost *:80
 
@@ -130,7 +130,7 @@ For a :app:`Pyramid` application running under :term:`mod_wsgi`,
 the same can be achieved using ``SetEnv``:
 
 .. code-block:: apache
-   :linenos:
+    :linenos:
 
     <Location />
       SetEnv HTTP_X_VHM_ROOT /cms
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 7c76116f7..e5a2c1ade 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -435,7 +435,7 @@ configured view.
 
   If specified, this value should be a :term:`principal` identifier or a
   sequence of principal identifiers.  If the
-  :func:`pyramid.security.effective_principals` method indicates that every
+  :meth:`pyramid.request.Request.effective_principals` method indicates that every
   principal named in the argument list is present in the current request, this
   predicate will return True; otherwise it will return False.  For example:
   ``effective_principals=pyramid.security.Authenticated`` or
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index b2dd549ce..a746eb043 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -536,7 +536,7 @@ The following types work as view callables in this style:
    e.g.:
 
    .. code-block:: python
-      :linenos:
+       :linenos:
 
        from pyramid.response import Response