25 files changed, 130 insertions, 133 deletions
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index deaf0ce08..09a2b83f2 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -50,7 +50,6 @@ application might address the asset using the :term:`asset specification`
 ``myapp:templates/some_template.pt`` using that API within a ``views.py``
 file inside a ``myapp`` package:
 
-.. ignore-next-block
 .. code-block:: python
    :linenos:
 
@@ -120,7 +119,7 @@ from the ``/var/www/static`` directory of the computer which runs the
    # config is an instance of pyramid.config.Configurator
    config.add_static_view(name='static', path='/var/www/static')
 
-The ``name`` prepresents a URL *prefix*.  In order for files that live in the
+The ``name`` represents a URL *prefix*.  In order for files that live in the
 ``path`` directory to be served, a URL that requests one of them must begin
 with that prefix.  In the example above, ``name`` is ``static``, and ``path``
 is ``/var/www/static``.  In English, this means that you wish to serve the
@@ -331,7 +330,6 @@ root that exists at the end of your routing table, create an instance of the
 :class:`~pyramid.static.static_view` class inside a ``static.py`` file in
 your application root as below.
 
-.. ignore-next-block
 .. code-block:: python
    :linenos:
 
@@ -458,7 +456,6 @@ The ``override_asset`` API
 An individual call to :meth:`~pyramid.config.Configurator.override_asset`
 can override a single asset.  For example:
 
-.. ignore-next-block
 .. code-block:: python
    :linenos:
 
@@ -473,7 +470,6 @@ colon separator in a specification separates the *package name* from the
 are not specified, the override attempts to resolve every lookup into a
 package from the directory of another package.  For example:
 
-.. ignore-next-block
 .. code-block:: python
    :linenos:
 
@@ -482,7 +478,6 @@ package from the directory of another package.  For example:
 
 Individual subdirectories within a package can also be overridden:
 
-.. ignore-next-block
 .. code-block:: python
    :linenos:
 
@@ -511,7 +506,6 @@ construction file resides (or the ``package`` argument to the
 :class:`~pyramid.config.Configurator` class construction).
 For example:
 
-.. ignore-next-block
 .. code-block:: python
    :linenos:
 
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 07c892439..e1347f3ca 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -172,8 +172,8 @@ name ``main`` as a section name:
 
 The WSGI application that is loaded will be available in the shell as the
 ``app`` global. Also, if the application that is loaded is the :app:`Pyramid`
-app with no surrounding middleware, the ``root`` object returned by the
-default :term:`root factory`, ``registry``, and ``request`` will be
+app with no surrounding :term:`middleware`, the ``root`` object returned by
+the default :term:`root factory`, ``registry``, and ``request`` will be
 available.
 
 You can also simply rely on the ``main`` default section name by omitting any
@@ -572,8 +572,8 @@ configuration implied by the ``[pipeline:main]`` section of your
 configuration file by default.  Specifying ``/path/to/my/development.ini`` is
 logically equivalent to specifying ``/path/to/my/development.ini#main``.  In
 this case, we'll be using a configuration that includes an ``app`` object
-which is wrapped in the Paste "translogger" middleware (which logs requests
-to the console).
+which is wrapped in the Paste "translogger" :term:`middleware` (which logs
+requests to the console).
 
 You can also specify a particular *section* of the PasteDeploy ``.ini`` file
 to load instead of ``main``:
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 6f82baf32..f7a69d613 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -140,7 +140,6 @@ In the example above, the scanner translates the arguments to
 :class:`~pyramid.view.view_config` into a call to the
 :meth:`pyramid.config.Configurator.add_view` method, effectively:
 
-.. ignore-next-block
 .. code-block:: python
 
    config.add_view(hello)
diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst
index beece7640..a60a49fea 100644
--- a/docs/narr/extending.rst
+++ b/docs/narr/extending.rst
@@ -50,7 +50,7 @@ layers are apt to provide the necessary "opinions" (such as mandating a
 storage layer, a templating system, and a structured, well-documented pattern
 of registering that certain URLs map to certain bits of code) which makes the
 concept of a "pluggable application" possible.  "Pluggable applications",
-thus, should not plug in to Pyramid itself but should instead plug into a
+thus, should not plug into Pyramid itself but should instead plug into a
 system written atop Pyramid.
 
 Although it does not provide for "pluggable applications", Pyramid *does*
@@ -209,7 +209,7 @@ like this:
 
 - Wire the new views and assets created in the new package up using
   imperative registrations within the ``main`` function of the
-  ``__init__.py`` file of the new application.  These wiring should happen
+  ``__init__.py`` file of the new application.  This wiring should happen
   *after* including the configuration functions of the old application.
   These registrations will extend or override any registrations performed by
   the original application.  See :ref:`overriding_views`,
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index 6d3786d8e..e73ef66ac 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -166,7 +166,6 @@ the application.
 Adding Configuration
 ~~~~~~~~~~~~~~~~~~~~
 
-.. ignore-next-block
 .. literalinclude:: helloworld.py
    :linenos:
    :lines: 11-12
@@ -186,7 +185,6 @@ The second line registers the ``hello_world`` function as a
 WSGI Application Creation
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ignore-next-block
 .. literalinclude:: helloworld.py
    :linenos:
    :lines: 13
@@ -215,7 +213,6 @@ to its ``add_view`` and ``add_route`` methods.
 WSGI Application Serving
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. ignore-next-block
 .. literalinclude:: helloworld.py
    :linenos:
    :lines: 14-15
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 330eb0cd3..a3de23baa 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -109,9 +109,8 @@ callable:
    instance of the :exc:`~pyramid.httpexceptions.HTTPNotFound` exception that
    caused the Not Found View to be called.  The value of
    ``request.exception.message`` will be a value explaining why the Not Found
-   error was raised.  This message will be different when the
-   ``pyramid.debug_notfound`` environment setting is true than it is when it
-   is false.
+   error was raised.  This message has different values depending whether the
+   ``pyramid.debug_notfound`` environment setting is true or false.
 
 .. note::
 
@@ -208,9 +207,9 @@ Here's some sample code that implements a minimal forbidden view:
    that caused the forbidden view to be called.  The value of
    ``request.exception.message`` will be a value explaining why the forbidden
    was raised and ``request.exception.result`` will be extended information
-   about the forbidden exception.  These messages will be different when the
-   ``pyramid.debug_authorization`` environment setting is true than it is when
-   it is false.
+   about the forbidden exception.  These messages have different values
+   depending whether the ``pyramid.debug_authorization`` environment setting
+   is true or false.
 
 .. index::
    single: request factory
@@ -694,7 +693,7 @@ represents the type of interface that must be possessed by the resource for
 this resource url factory to be found.  If the ``resource_iface`` argument is
 omitted, this resource url adapter will be used for *all* resources.
 
-The API that must be implemented by your a class that provides
+The API that must be implemented by a class that provides
 :class:`~pyramid.interfaces.IResourceURL` is as follows:
 
 .. code-block:: python
@@ -1036,7 +1035,7 @@ upstream WSGI component that uses :app:`Pyramid` as its "app".  This is a
 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` middleware but they have the benefit of
+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.
 
@@ -1110,8 +1109,8 @@ Once you've created a tween factory, you can register it into the implicit
 tween chain using the :meth:`pyramid.config.Configurator.add_tween` method
 using its :term:`dotted Python name`.
 
-Here's an example of registering the a tween factory as an "implicit"
-tween in a Pyramid application:
+Here's an example of registering a tween factory as an "implicit" tween in a
+Pyramid application:
 
 .. code-block:: python
    :linenos:
@@ -1447,7 +1446,7 @@ view/route predicate:
   subscriber predicates will assume a certain event type.
 
 Here's an example of a subscriber predicate that can be used in conjunction
-with a subscriber that subscribes to the :class:`pyramid.events.NewReqest`
+with a subscriber that subscribes to the :class:`pyramid.events.NewRequest`
 event type.
 
 .. code-block:: python
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 9bc62dc62..8fc63f3a4 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -19,13 +19,32 @@ run :app:`Pyramid`.
     run under any version of Python before 2.6.
 
 :app:`Pyramid` is known to run on all popular UNIX-like systems such as
-Linux, MacOS X, and FreeBSD as well as on Windows platforms.  It is also
-known to run on :term:`PyPy` (1.9+).
+Linux, Mac OS X, and FreeBSD as well as on Windows platforms.  It is
+also known to run on :term:`PyPy` (1.9+).
 
 :app:`Pyramid` installation does not require the compilation of any
 C code, so you need only a Python interpreter that meets the
 requirements mentioned.
 
+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'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/>`_.
+
+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.
+
+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.
+
+If you use an installer for your Python, then you can skip to the
+section :ref:`installing_unix`.
+
 If You Don't Yet Have A Python Interpreter (UNIX)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -322,8 +341,8 @@ for both versions are included below.
 Windows Using Python 2
 ~~~~~~~~~~~~~~~~~~~~~~
 
-#. Install, or find `Python 2.7
-   <http://www.python.org/download/releases/2.7.3/>`_ for your system.
+#. Install the most recent `Python 2.7.x version
+   <http://www.python.org/download/>`_ for your system.
 
 #. Install the `Python for Windows extensions
    <http://sourceforge.net/projects/pywin32/files/>`_.  Make sure to
@@ -371,36 +390,47 @@ Windows Using Python 2
 Windows Using Python 3
 ~~~~~~~~~~~~~~~~~~~~~~
 
-#. Install, or find `Python 3.2
-   <http://www.python.org/download/releases/3.2.3/>`_ for your system.
+#. Install, or find the latest version of `Python 3.x
+   <http://www.python.org/download/>`_ for your system and which is
+   supported by Pyramid.
 
 #. Install the `Python for Windows extensions
    <http://sourceforge.net/projects/pywin32/files/>`_.  Make sure to
-   pick the right download for Python 3.2 and install it using the
+   pick the right download for Python 3.x and install it using the
    same Python installation from the previous step.
 
 #. Install latest :term:`distribute` distribution into the Python you
    obtained/installed/found in the step above: download `distribute_setup.py
    <http://python-distribute.org/distribute_setup.py>`_ and run it using the
-   ``python`` interpreter of your Python 3.2 installation using a command
+   ``python`` interpreter of your Python 3.x installation using a command
    prompt:
 
    .. code-block:: text
 
+      # modify the command according to the python version, e.g.:
+      # for Python 3.2.x:
       c:\> c:\Python32\python distribute_setup.py
+      # for Python 3.3.x:
+      c:\> c:\Python33\python distribute_setup.py
 
 #. Install :term:`virtualenv`:
 
    .. code-block:: text
 
+      # for Python 3.2.x:
       c:\> c:\Python32\Scripts\easy_install virtualenv
+      # for Python 3.3.x:
+      c:\> c:\Python33\Scripts\easy_install virtualenv
 
 #. Make a :term:`virtualenv` workspace:
 
    .. code-block:: text
 
       c:\> set VENV=c:\env
+      # for Python 3.2.x:
       c:\> c:\Python32\Scripts\virtualenv --no-site-packages %VENV%
+      # for Python 3.3.x:
+      c:\> c:\Python33\Scripts\virtualenv --no-site-packages %VENV%
 
    You can either follow the use of the environment variable, ``%VENV%``,
    or replace it with the root directory of the :term:`virtualenv`.
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index f9c25c69c..48164d323 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -600,10 +600,10 @@ Examples: :ref:`hello_traversal_chapter` and
 Tweens
 ~~~~~~
 
-Pyramid has a sort of internal WSGI-middleware-ish pipeline that can be
-hooked by arbitrary add-ons named "tweens".  The debug toolbar is a "tween",
-and the ``pyramid_tm`` transaction manager is also.  Tweens are more useful
-than WSGI middleware in some circumstances because they run in the context of
+Pyramid has a sort of internal WSGI-middleware-ish pipeline that can be hooked
+by arbitrary add-ons named "tweens".  The debug toolbar is a "tween", and the
+``pyramid_tm`` transaction manager is also.  Tweens are more useful than WSGI
+:term:`middleware` in some circumstances because they run in the context of
 Pyramid itself, meaning you have access to templates and other renderers, a
 "real" request object, and other niceties.
 
diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst
index 3b903be4d..b3bfb8a1e 100644
--- a/docs/narr/logging.rst
+++ b/docs/narr/logging.rst
@@ -298,14 +298,14 @@ Request Logging with Paste's TransLogger
 ----------------------------------------
 
 Paste provides the `TransLogger 
-<http://pythonpaste.org/modules/translogger.html>`_ middleware for logging 
-requests using the `Apache Combined Log Format 
+<http://pythonpaste.org/modules/translogger.html>`_ :term:`middleware` for
+logging requests using the `Apache Combined Log Format
 <http://httpd.apache.org/docs/2.2/logs.html#combined>`_. TransLogger combined 
 with a FileHandler can be used to create an ``access.log`` file similar to 
 Apache's. 
 
-Like any standard middleware with a Paste entry point, TransLogger can be
-configured to wrap your application using ``.ini`` file syntax.  First,
+Like any standard :term:`middleware` with a Paste entry point, TransLogger can
+be configured to wrap your application using ``.ini`` file syntax.  First,
 rename your Pyramid ``.ini`` file's ``[app:main]`` section to
 ``[app:mypyramidapp]``, then add a ``[filter:translogger]`` section, then use
 a ``[pipeline:main]`` section file to form a WSGI pipeline with both the
diff --git a/docs/narr/muchadoabouttraversal.rst b/docs/narr/muchadoabouttraversal.rst
index 40d498391..483b1bb16 100644
--- a/docs/narr/muchadoabouttraversal.rst
+++ b/docs/narr/muchadoabouttraversal.rst
@@ -168,18 +168,12 @@ hood, when ``adict`` is a dictionary-like object, Python translates
 ``adict['a']`` to ``adict.__getitem__('a')``.  Try doing this in a Python
 interpreter prompt if you don't believe us:
 
-.. code-block:: text
-   :linenos:
-
-   Python 2.4.6 (#2, Apr 29 2010, 00:31:48) 
-   [GCC 4.4.3] on linux2
-   Type "help", "copyright", "credits" or "license" for more information.
-   >>> adict = {}
-   >>> adict['a'] = 1
-   >>> adict['a']
-   1
-   >>> adict.__getitem__('a')
-   1
+>>> adict = {}
+>>> adict['a'] = 1
+>>> adict['a']
+1
+>>> adict.__getitem__('a')
+1
 
 
 The dictionary-like root object stores the ids of all of its subresources as
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index a168c24eb..9d69a65a5 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -416,7 +416,7 @@ If you don't see the debug toolbar image on the right hand top of the page,
 it means you're browsing from a system that does not have debugging access.
 By default, for security reasons, only a browser originating from
 ``localhost`` (``127.0.0.1``) can see the debug toolbar.  To allow your
-browser on a remote system to access the server, add the a line within the
+browser on a remote system to access the server, add a line within the
 ``[app:main]`` section of the ``development.ini`` file in the form
 ``debugtoolbar.hosts = X.X.X.X``.  For example, if your Pyramid application
 is running on a remote system, and you're browsing from a host with the IP
diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst
index 08ebd881e..b4eb95186 100644
--- a/docs/narr/renderers.rst
+++ b/docs/narr/renderers.rst
@@ -362,7 +362,7 @@ For example (Javascript):
    jqhxr = $.getJSON(api_url);
 
 The string ``callback=?`` above in the ``url`` param to the JQuery
-``getAjax`` function indicates to jQuery that the query should be made as
+``getJSON`` function indicates to jQuery that the query should be made as
 a JSONP request; the ``callback`` parameter will be automatically filled
 in for you and used.
 
@@ -720,7 +720,7 @@ factory, which expects to be passed a filesystem path:
 
 Adding the above code to your application startup will allow you to use the
 ``my.package.MyJinja2Renderer`` renderer factory implementation in view
-configurations by referring to any ``renderer`` which *ends in* ``.jinja`` in
+configurations by referring to any ``renderer`` which *ends in* ``.jinja2`` in
 the ``renderer`` attribute of a :term:`view configuration`:
 
 .. code-block:: python
diff --git a/docs/narr/router.rst b/docs/narr/router.rst
index b78362066..ac3deefdc 100644
--- a/docs/narr/router.rst
+++ b/docs/narr/router.rst
@@ -46,7 +46,7 @@ request enters a :app:`Pyramid` application through to the point that
    :class:`~pyramid.interfaces.IRoute` object representing the route which
    matched.  The root object associated with the route found is also
    generated: if the :term:`route configuration` which matched has an
-   associated a ``factory`` argument, this factory is used to generate the
+   associated ``factory`` argument, this factory is used to generate the
    root object, otherwise a default :term:`root factory` is used.
 
 #. If a route match was *not* found, and a ``root_factory`` argument was
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 203aa2404..e91e8c542 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -85,7 +85,6 @@ during application setup to specify the authentication policy.
 
 For example:
 
-.. ignore-next-block
 .. code-block:: python
    :linenos:
 
@@ -151,7 +150,6 @@ API:
 The equivalent view registration including the ``add`` permission name
 may be performed via the ``@view_config`` decorator:
 
-.. ignore-next-block
 .. code-block:: python
    :linenos:
 
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index fa4affd8a..c4f4b5f07 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -252,25 +252,19 @@ that were added to the flash queue, and empties the queue.
 
 .. method:: pop_flash(queue='')
 
-.. code-block:: python
-   :linenos:
-
-   >>> request.session.flash('info message')
-   >>> request.session.pop_flash()
-   ['info message']
+>>> request.session.flash('info message')
+>>> request.session.pop_flash()
+['info message']
 
 Calling ``session.pop_flash()`` again like above without a corresponding call
 to ``session.flash()`` will return an empty list, because the queue has already
 been popped.
 
-.. code-block:: python
-   :linenos:
-
-   >>> request.session.flash('info message')
-   >>> request.session.pop_flash()
-   ['info message']
-   >>> request.session.pop_flash()
-   []
+>>> request.session.flash('info message')
+>>> request.session.pop_flash()
+['info message']
+>>> request.session.pop_flash()
+[]
 
 .. index::
    single: session.peek_flash
@@ -285,18 +279,15 @@ popped from flash storage.
 
 .. method:: peek_flash(queue='')
 
-.. code-block:: python
-   :linenos:
-
-   >>> request.session.flash('info message')
-   >>> request.session.peek_flash()
-   ['info message']
-   >>> request.session.peek_flash()
-   ['info message']
-   >>> request.session.pop_flash()
-   ['info message']
-   >>> request.session.peek_flash()
-   []
+>>> request.session.flash('info message')
+>>> request.session.peek_flash()
+['info message']
+>>> request.session.peek_flash()
+['info message']
+>>> request.session.pop_flash()
+['info message']
+>>> request.session.peek_flash()
+[]
 
 .. index::
    single: preventing cross-site request forgery attacks
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index 3a9225032..1affa1758 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -8,12 +8,12 @@ you'll see something much like this show up on the console:
 
 .. code-block:: text
 
-  $ pserve myproject/MyProject.ini
+  $ pserve development.ini
   Starting server in PID 16601.
   serving on 0.0.0.0:6543 view at http://127.0.0.1:6543
 
 This chapter explains what happens between the time you press the "Return"
-key on your keyboard after typing ``pserve myproject/MyProject.ini``
+key on your keyboard after typing ``pserve development.ini``
 and the time the line ``serving on 0.0.0.0:6543 ...`` is output to your
 console.
 
diff --git a/docs/narr/subrequest.rst b/docs/narr/subrequest.rst
index 033f045a6..93ce747ee 100644
--- a/docs/narr/subrequest.rst
+++ b/docs/narr/subrequest.rst
@@ -155,7 +155,7 @@ In the example above, the call to
 exception.  This is because it's using the default value for ``use_tweens``,
 which is ``False``.  You can pass ``use_tweens=True`` instead to ensure that
 it will convert an exception to a Response if an :term:`exception view` is
-configured instead of raising the exception.  This because exception views
+configured instead of raising the exception.  This is because exception views
 are called by the exception view :term:`tween` as described in
 :ref:`exception_views` when any view raises an exception.
 
@@ -250,7 +250,7 @@ It's a poor idea to use the original ``request`` object as an argument to
 :meth:`~pyramid.request.Request.invoke_subrequest`.  You should construct a
 new request instead as demonstrated in the above example, using
 :meth:`pyramid.request.Request.blank`.  Once you've constructed a request
-object, you'll need to massage the it to match the view callable you'd like
+object, you'll need to massage it to match the view callable you'd like
 to be executed during the subrequest.  This can be done by adjusting the
 subrequest's URL, its headers, its request method, and other attributes.  The
 documentation for :class:`pyramid.request.Request` exposes the methods you
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 1f1c07027..d4cf20b93 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -150,7 +150,6 @@ string, then return that string as the body of a :app:`Pyramid`
 For example, here's an example of using "raw" `Mako
 <http://www.makotemplates.org/>`_ from within a :app:`Pyramid` :term:`view`:
 
-.. ignore-next-block
 .. code-block:: python
    :linenos:
 
diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst
index 0801a8eae..bfb1287d9 100644
--- a/docs/narr/testing.rst
+++ b/docs/narr/testing.rst
@@ -128,7 +128,7 @@ functions accepts various arguments that influence the environment of the
 test.  See the :ref:`testing_module` chapter for information about the extra
 arguments supported by these functions.
 
-If you also want to make :func:`~pyramid.get_current_request` return something
+If you also want to make :func:`~pyramid.threadlocal.get_current_request` return something
 other than ``None`` during the course of a single test, you can pass a
 :term:`request` object into the :func:`pyramid.testing.setUp` within the
 ``setUp`` method of your test:
@@ -231,7 +231,7 @@ 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:`HTTPForbidden`?
+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
@@ -272,7 +272,7 @@ without needing to invoke the actual application configuration implied by its
            self.assertEqual(response, {'greeting':'hello'})
            
 In the above example, we create a ``MyTest`` test case that inherits from
-:mod:`unittest.TestCase`.  If it's in our :app:`Pyramid` application, it will
+:class:`unittest.TestCase`.  If it's in our :app:`Pyramid` application, it will
 be found when ``setup.py test`` is run.  It has two test methods.
 
 The first test method, ``test_view_fn_forbidden`` tests the ``view_fn`` when
@@ -287,8 +287,9 @@ 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
-:meth:`~pyramid.config.Configuration.testing_securitypolicy`, which denies
-access.  We check that the view function raises a :exc:`HTTPForbidden` error.
+:meth:`~pyramid.config.Configurator.testing_securitypolicy`, which denies
+access.  We check that the view function raises a
+:exc:`~pyramid.httpexceptions.HTTPForbidden` error.
 
 The second test method, named ``test_view_fn_allowed`` tests the alternate
 case, where the authentication policy allows access.  Notice that we pass
@@ -425,4 +426,4 @@ invoke the root URL.  We then assert that the returned HTML has the string
 ``Pyramid`` in it.
 
 See the :term:`WebTest` documentation for further information about the
-methods available to a :class:`webtest.TestApp` instance.
+methods available to a :class:`webtest.app.TestApp` instance.
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index 1234620c2..2eb6ece13 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -22,10 +22,13 @@ resource found as the result of a traversal becomes the
 subsystem is used to find some view code willing to "publish" this
 resource by generating a :term:`response`.
 
-Using :term:`Traversal` to map a URL to code is optional.  It is often
-less easy to understand than :term:`URL dispatch`, so if you're a rank
-beginner, it probably makes sense to use URL dispatch to map URLs to
-code instead of traversal.  In that case, you can skip this chapter.
+.. note::
+
+  Using :term:`Traversal` to map a URL to code is optional.  If you're creating
+  your first Pyramid application it probably makes more sense to use :term:`URL
+  dispatch` to map URLs to code instead of traversal, as new Pyramid developers
+  tend to find URL dispatch slightly easier to understand.  If you use URL
+  dispatch, you needn't read this chapter.
 
 .. index::
    single: traversal details
@@ -356,13 +359,13 @@ when this request comes in that we're traversing the following resource tree:
 
 Here's what happens:
 
-- :mod:`traversal` traverses the root, and attempts to find "foo", which it
+- :term:`traversal` traverses the root, and attempts to find "foo", which it
   finds.
 
-- :mod:`traversal` traverses "foo", and attempts to find "bar", which it
+- :term:`traversal` traverses "foo", and attempts to find "bar", which it
   finds.
 
-- :mod:`traversal` traverses "bar", and attempts to find "baz", which it does
+- :term:`traversal` traverses "bar", and attempts to find "baz", which it does
   not find (the "bar" resource raises a :exc:`KeyError` when asked for
   "baz").
 
@@ -407,16 +410,16 @@ However, for this tree:
 
 The user asks for ``http://example.com/foo/bar/baz/biz/buz.txt``
 
-- :mod:`traversal` traverses "foo", and attempts to find "bar", which it
+- :term:`traversal` traverses "foo", and attempts to find "bar", which it
   finds.
 
-- :mod:`traversal` traverses "bar", and attempts to find "baz", which it
+- :term:`traversal` traverses "bar", and attempts to find "baz", which it
   finds.
 
-- :mod:`traversal` traverses "baz", and attempts to find "biz", which it
+- :term:`traversal` traverses "baz", and attempts to find "biz", which it
   finds.
 
-- :mod:`traversal` traverses "biz", and attempts to find "buz.txt" which it
+- :term:`traversal` traverses "biz", and attempts to find "buz.txt" which it
   does not find.
 
 The fact that it does not find a resource related to "buz.txt" at this point
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 181b07259..18cb3e4db 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -16,12 +16,13 @@ receives the :term:`request` and returns a :term:`response` object.
 High-Level Operational Overview
 -------------------------------
 
-If route configuration is present in an application, the :app:`Pyramid`
+If any route configuration is present in an application, the :app:`Pyramid`
 :term:`Router` checks every incoming request against an ordered set of URL
 matching patterns present in a *route map*.
 
 If any route pattern matches the information in the :term:`request`,
-:app:`Pyramid` will invoke :term:`view lookup` to find a matching view.
+:app:`Pyramid` will invoke the :term:`view lookup` process to find a
+matching view.
 
 If no route pattern in the route map matches the information in the
 :term:`request` provided in your application, :app:`Pyramid` will fail over
@@ -54,7 +55,6 @@ The :meth:`pyramid.config.Configurator.add_route` method adds a single
 :term:`route configuration` to the :term:`application registry`.  Here's an
 example:
 
-.. ignore-next-block
 .. code-block:: python
 
    # "config" below is presumed to be an instance of the
@@ -81,7 +81,7 @@ this is a portion of your project's ``__init__.py``:
 
 Note that we don't call :meth:`~pyramid.config.Configurator.add_view` in this
 setup code.  However, the above :term:`scan` execution
-``config.scan('mypackage')`` will pick up all :term:`configuration
+``config.scan('mypackage')`` will pick up each :term:`configuration
 decoration`, including any objects decorated with the
 :class:`pyramid.view.view_config` decorator in the ``mypackage`` Python
 package.  For example, if you have a ``views.py`` in your package, a scan will
@@ -1263,7 +1263,7 @@ invoked with the request that caused the invocation.
 
 For most usage, you needn't understand more than this; how it works is an
 implementation detail.  In the interest of completeness, however, we'll
-explain how it *does* work in the this section.  You can skip it if you're
+explain how it *does* work in this section.  You can skip it if you're
 uninterested.
 
 When a view is associated with a route configuration, :app:`Pyramid` ensures
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index d3221db3c..6f0001f61 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -62,9 +62,9 @@ particular view callable.
 
 :term:`View predicate` attributes are an important part of view configuration
 that enables the :term:`view lookup` subsystem to find and invoke the
-appropriate view.  The greater number of predicate attributes possessed by a
+appropriate view.  The greater the number of predicate attributes possessed by a
 view's configuration, the more specific the circumstances need to be before
-the registered view callable will be invoked.  The fewer number of predicates
+the registered view callable will be invoked.  The fewer the number of predicates
 which are supplied to a particular view configuration, the more likely it is
 that the associated view callable will be invoked.  A view with five
 predicates will always be found and evaluated before a view with two, for
@@ -313,9 +313,9 @@ configured view.
 
   This argument ensures that the view will only be called when the
   :term:`request` has key/value pairs in its :term:`matchdict` that equal
-  those supplied in the predicate.  e.g. ``match_param="action=edit" would
+  those supplied in the predicate.  e.g. ``match_param="action=edit"`` would
   require the ``action`` parameter in the :term:`matchdict` match the right
-  hande side of the expression (``edit``) for the view to "match" the current
+  hand side of the expression (``edit``) for the view to "match" the current
   request.
 
   If the ``match_param`` is a dict, every key/value pair must match for the
@@ -488,7 +488,6 @@ acts as a :app:`Pyramid` view callable.
 Here's an example of the :class:`~pyramid.view.view_config` decorator that
 lives within a :app:`Pyramid` application module ``views.py``:
 
-.. ignore-next-block
 .. code-block:: python
    :linenos:
 
@@ -503,7 +502,6 @@ lives within a :app:`Pyramid` application module ``views.py``:
 Using this decorator as above replaces the need to add this imperative
 configuration stanza:
 
-.. ignore-next-block
 .. code-block:: python
    :linenos:
 
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 5a7be15b0..b2dd549ce 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -39,7 +39,7 @@ object.  A request object represents a :term:`WSGI` environment provided to
 object contains everything your application needs to know about the specific
 HTTP request being made.
 
-A view callable's ultimate responsibility is to create a :mod:`Pyramid`
+A view callable's ultimate responsibility is to create a :app:`Pyramid`
 :term:`Response` object. This can be done by creating a :term:`Response`
 object in the view callable code and returning it directly or by raising
 special kinds of exceptions from within the body of a view callable.
diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst
index 44940f9e6..02c03c8db 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -326,7 +326,6 @@ package that uses SQLAlchemy, and you'd like the current SQLAlchemy database
 session to be removed after each request.  Put the following in the
 ``mypackage.__init__`` module:
 
-.. ignore-next-block
 .. code-block:: python
    :linenos:
 
@@ -355,7 +354,7 @@ initialization.
    cause ``DBSession.remove`` to be called in an application generated from
    any :app:`Pyramid` scaffold, because these all use the ``pyramid_tm``
    package.  The cleanup done by ``DBSession.remove`` is unnecessary when
-   ``pyramid_tm`` middleware is configured into the application.
+   ``pyramid_tm`` :term:`middleware` is configured into the application.
 
 More Details
 ++++++++++++
@@ -491,7 +490,6 @@ reason for the error.  For instance,
 :class:`pyramid.Response`, so you can manipulate the instances in the same
 way.  A typical example is:
 
-.. ignore-next-block
 .. code-block:: python
     :linenos:
 
diff --git a/docs/narr/zca.rst b/docs/narr/zca.rst
index f7707ea29..b0e9b1709 100644
--- a/docs/narr/zca.rst
+++ b/docs/narr/zca.rst
@@ -21,7 +21,6 @@ application can be opaque.  For example, here is a typical "unnamed
 utility" lookup using the :func:`zope.component.getUtility` global API
 as it might appear in a traditional Zope application:
 
-.. ignore-next-block
 .. code-block:: python
    :linenos:
 
@@ -45,7 +44,7 @@ framework implementation detail.
 
 However, developers who are already used to writing :term:`Zope`
 applications often still wish to use the ZCA while building a
-:app:`Pyramid` application; :mod:`pyramid` makes this possible.
+:app:`Pyramid` application; :app:`Pyramid` makes this possible.
 
 .. index::
    single: get_current_registry
@@ -84,7 +83,7 @@ While this services a reasonable goal, it causes some issues when
 trying to use patterns which you might use to build a typical
 :term:`Zope` application to build a :app:`Pyramid` application.
 Without special help, ZCA "global" APIs such as
-``zope.component.getUtility`` and ``zope.component.getSiteManager``
+:func:`zope.component.getUtility` and :func:`zope.component.getSiteManager`
 will use the ZCA "global" registry.  Therefore, these APIs
 will appear to fail when used in a :app:`Pyramid` application,
 because they'll be consulting the ZCA global registry rather than the
@@ -105,8 +104,8 @@ Disusing the Global ZCA API
 +++++++++++++++++++++++++++
 
 ZCA "global" API functions such as ``zope.component.getSiteManager``,
-``zope.component.getUtility``, ``zope.component.getAdapter``, and
-``zope.component.getMultiAdapter`` aren't strictly necessary.  Every
+``zope.component.getUtility``, :func:`zope.component.getAdapter`, and
+:func:`zope.component.getMultiAdapter` aren't strictly necessary.  Every
 component registry has a method API that offers the same
 functionality; it can be used instead.  For example, presuming the
 ``registry`` value below is a Zope Component Architecture component
@@ -114,7 +113,6 @@ registry, the following bit of code is equivalent to
 ``zope.component.getUtility(IFoo)``:
 
 .. code-block:: python
-   :linenos:
 
    registry.getUtility(IFoo)
 
@@ -152,7 +150,6 @@ Consider the following bit of idiomatic :app:`Pyramid` startup code:
 .. code-block:: python
    :linenos:
 
-   from zope.component import getGlobalSiteManager
    from pyramid.config import Configurator
 
    def app(global_settings, **settings):
@@ -189,7 +186,6 @@ For example:
 .. code-block:: python
    :linenos:
 
-   from zope.component import getGlobalSiteManager
    from pyramid.config import Configurator
 
    def app(global_settings, **settings):