16 files changed, 70 insertions, 79 deletions

diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index ba43f3ea6..434e2bd6c 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -417,7 +417,7 @@ added in configuration execution order.
 More Information
 ----------------
 
-For more information, see the article,`"A Whirlwind Tour of Advanced
+For more information, see the article, `"A Whirlwind Tour of Advanced
 Configuration Tactics"
 <http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/configuration/whirlwind_tour.html>`_,
 in the Pyramid Cookbook.
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 5c4d58548..3c922d0c3 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -146,7 +146,7 @@ name ``main`` as a section name:
 
 .. code-block:: text
 
-    chrism@thinko env26]$ bin/pshell starter/development.ini#main
+    $ bin/pshell starter/development.ini#main
     Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) 
     [GCC 4.4.3] on linux2
     Type "help" for more information.
@@ -181,7 +181,7 @@ hash after the filename:
 
 .. code-block:: text
 
-    chrism@thinko env26]$ bin/pshell starter/development.ini
+    $ bin/pshell starter/development.ini
 
 Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows).
 
@@ -244,7 +244,7 @@ exposed, and the request is configured to generate urls from the host
 
 .. code-block:: text
 
-    chrism@thinko env26]$ bin/pshell starter/development.ini
+    $ bin/pshell starter/development.ini
     Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) 
     [GCC 4.4.3] on linux2
     Type "help" for more information.
@@ -286,8 +286,7 @@ specifically invoke one of your choice with the ``-p choice`` or
 
 .. code-block:: text
 
-   [chrism@vitaminf shellenv]$ ../bin/pshell -p ipython | bpython | python \
-                                development.ini#MyProject
+   $ ../bin/pshell -p ipython | bpython | python development.ini#MyProject
 
 .. index::
    pair: routes; printing
@@ -312,7 +311,7 @@ For example:
 .. code-block:: text
    :linenos:
 
-   [chrism@thinko MyProject]$ ../bin/proutes development.ini
+   $ ../bin/proutes development.ini
    Name            Pattern                        View
    ----            -------                        ----                     
    home            /                              <function my_view>
@@ -321,8 +320,8 @@ For example:
    static/         static/*subpath                <static_view object>
    catchall        /*subpath                      <function static_view>
 
-``proutes`` generates a table.  The table has three columns: a Name
-column, a Pattern column, and a View column.  The items listed in the
+``proutes`` generates a table with three columns: *Name*, *Pattern*,
+and *View*.  The items listed in the
 Name column are route names, the items listed in the Pattern column are route
 patterns, and the items listed in the View column are representations of the
 view callable that will be invoked when a request matches the associated
@@ -355,7 +354,7 @@ configured without any explicit tweens:
 .. code-block:: text
    :linenos:
 
-   [chrism@thinko pyramid]$ myenv/bin/ptweens development.ini 
+   $ myenv/bin/ptweens development.ini
    "pyramid.tweens" config value NOT set (implicitly ordered tweens used)
 
    Implicit Tween Chain
@@ -373,7 +372,7 @@ explicit tweens defined in its ``development.ini`` file:
 .. code-block:: text
    :linenos:
 
-   [chrism@thinko pyramid]$ ptweens development.ini  
+   $ ptweens development.ini
    "pyramid.tweens" config value set (explicitly ordered tweens used)
 
    Explicit Tween Chain (used)
@@ -399,7 +398,7 @@ Here's the application configuration section of the ``development.ini`` used
 by the above ``ptweens`` command which reports that the explicit tween chain
 is used:
 
-.. code-block:: text
+.. code-block:: ini
    :linenos:
 
    [app:main]
@@ -878,9 +877,7 @@ with ``foo``.  Running it with two "omit" options (e.g. ``--omit=foo
 --omit=bar``) will omit all settings that have keys that start with either
 ``foo`` or ``bar``::
 
-  [chrism@thinko somevenv]$ bin/show_settings development.ini \
-                            --omit=pyramid \
-                            --omit=debugtoolbar
+  $ bin/show_settings development.ini --omit=pyramid --omit=debugtoolbar
   debug_routematch                             False               
   debug_templates                              True                
   reload_templates                             True                
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index fb3c3d7e3..35bfddb8d 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -212,7 +212,7 @@ sequence can take several different forms.
 
       package1 package2 package3
 
-    The package names can also be separated by carriage returns::
+   The package names can also be separated by carriage returns::
 
        package1
        package2
@@ -666,9 +666,9 @@ Here's how:
      def includeme(config):
          settings = config.registry.settings
          debug_frobnosticator = settings['debug_frobnosticator']
-     
-- In the runtime code that you need to access the new settings value, find
-  the value in the ``registry.settings`` dictionary and use it.  In
+
+- In the runtime code from where you need to access the new settings value,
+  find the value in the ``registry.settings`` dictionary and use it.  In
   :term:`view` code (or any other code that has access to the request), the
   easiest way to do this is via ``request.registry.settings``.  For example:
 
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index d103ca1cd..330eb0cd3 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -712,7 +712,7 @@ The API that must be implemented by your a class that provides
 
 The default context URL generator is available for perusal as the class
 :class:`pyramid.traversal.ResourceURL` in the `traversal module
-<http://github.com/Pylons/pyramid/blob/master/pyramid/traversal.py>`_ of the
+<https://github.com/Pylons/pyramid/blob/master/pyramid/traversal.py>`_ of the
 :term:`Pylons` GitHub Pyramid repository.
 
 See :meth:`pyramid.config.add_resource_url_adapter` for more information.
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index 511464322..24cd3ff54 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -736,9 +736,7 @@ through translation before being rendered:
 
 The features represented by attributes of the ``i18n`` namespace of
 Chameleon will also consult the :app:`Pyramid` translations.
-See
-`http://chameleon.repoze.org/docs/latest/i18n.html#the-i18n-namespace
-<http://chameleon.repoze.org/docs/latest/i18n.html#the-i18n-namespace>`_.
+See http://chameleon.readthedocs.org/en/latest/reference.html#id50.
 
 .. note::
 
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 3540ee5c4..47c32b0ba 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -219,7 +219,6 @@ that the Pyramid core doesn't.  Add-on packages already exist which let you
 easily send email, let you use the Jinja2 templating system, let you use
 XML-RPC or JSON-RPC, let you integrate with jQuery Mobile, etc.
 
-Examples: http://docs.pylonsproject.org/docs/pyramid.html#pyramid-add-on-documentation
 
 Class-based and function-based views
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst
index 7784e8960..dec22c5b1 100644
--- a/docs/narr/introspector.rst
+++ b/docs/narr/introspector.rst
@@ -7,6 +7,8 @@
 Pyramid Configuration Introspection
 ===================================
 
+.. versionadded:: 1.3
+
 When Pyramid starts up, each call to a :term:`configuration directive` causes
 one or more :term:`introspectable` objects to be registered with an
 :term:`introspector`.  The introspector can be queried by application code to
@@ -15,10 +17,6 @@ feature is useful for debug toolbars, command-line scripts which show some
 aspect of configuration, and for runtime reporting of startup-time
 configuration settings.
 
-.. warning::
-
-   Introspection is new in Pyramid 1.3.
-
 Using the Introspector
 ----------------------
 
diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst
index f4d1d051d..3b903be4d 100644
--- a/docs/narr/logging.rst
+++ b/docs/narr/logging.rst
@@ -22,25 +22,23 @@ Logging Configuration
 ---------------------
 
 A :app:`Pyramid` project created from a :term:`scaffold` is configured to
-allow you to send messages to `Python standard library logging package
-<http://docs.python.org/library/logging.html>`_ loggers from within your
+allow you to send messages to :mod:`Python standard library logging package
+<logging>` loggers from within your
 application.  In particular, the :term:`PasteDeploy` ``development.ini`` and
 ``production.ini`` files created when you use a scaffold include a basic
 configuration for the Python :mod:`logging` package.
 
-PasteDeploy ``.ini`` files use the Python standard library `ConfigParser
-format <http://docs.python.org/lib/module-ConfigParser.html>`_; this the same
-format used as the Python `logging module's Configuration file format
-<http://docs.python.org/lib/logging-config-fileformat.html>`_.  The
-application-related and logging-related sections in the configuration file
+PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser
+format <ConfigParser>`; this is the same format used as the Python
+:ref:`logging module's Configuration file format <logging-config-fileformat>`.
+The 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 :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). ``setup_logging`` reads the
+function, a thin wrapper around the :func:`logging.config.fileConfig`
+using the specified ``.ini`` file if it contains a ``[loggers]`` section
+(all of the scaffold-generated ``.ini`` files do). ``setup_logging`` reads the
 logging configuration from the ini file upon which ``pserve`` was
 invoked.
 
@@ -334,7 +332,7 @@ To this:
                mypyramidapp
 
 Using PasteDeploy this way to form and serve a pipeline is equivalent to
-wrapping your app in a TransLogger instance via the bottom the ``main``
+wrapping your app in a TransLogger instance via the bottom of the ``main``
 function of your project's ``__init__`` file:
 
 .. code-block:: python 
diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst
index aee5f9069..3427b6d53 100644
--- a/docs/narr/paste.rst
+++ b/docs/narr/paste.rst
@@ -21,7 +21,7 @@ of starting, stopping, and debugging an application.
 
 This chapter is not a replacement for documentation about PasteDeploy; it
 only contextualizes the use of PasteDeploy within Pyramid.  For detailed
-documentation, see http://pythonpaste.org.
+documentation, see http://pythonpaste.org/deploy/.
 
 PasteDeploy
 -----------
@@ -85,6 +85,8 @@ function.  This is the function called by :term:`PasteDeploy` when the
 ``pserve`` command is invoked against our application.  It accepts a global
 configuration object and *returns* an instance of our application.
 
+.. _defaults_section_of_pastedeploy_file:
+
 ``[DEFAULTS]`` Section of a PasteDeploy ``.ini`` File
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 214440328..a9072e3bf 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -305,7 +305,9 @@ If you want to restrict access such that only a browser running on the same
 machine as Pyramid will be able to access your Pyramid application, edit the
 ``development.ini`` file, and replace the ``host`` value in the
 ``[server:main]`` section.  Change it from ``0.0.0.0`` to ``127.0.0.1``.  For
-example::
+example:
+
+.. code-block:: ini
 
    [server:main]
    use = egg:waitress#main
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 3a94b4f7d..5a1a92e08 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -65,7 +65,7 @@ policies.
 Enabling an Authorization Policy
 --------------------------------
 
-By default, :app:`Pyramid` enables no authorization policy.  All
+:app:`Pyramid` does not enable any authorization policy by default.  All
 views are accessible by completely anonymous users.  In order to begin
 protecting views from execution based on security settings, you need
 to enable an authorization policy.
@@ -80,7 +80,7 @@ policy.
 You must also enable an :term:`authentication policy` in order to enable the
 authorization policy.  This is because authorization, in general, depends
 upon authentication.  Use the
-:meth:`~pyramid.config.Configurator.set_authentication_policy` and method
+:meth:`~pyramid.config.Configurator.set_authentication_policy` method
 during application setup to specify the authentication policy.
 
 For example:
@@ -98,7 +98,7 @@ For example:
    config.set_authentication_policy(authn_policy)
    config.set_authorization_policy(authz_policy)
 
-.. note:: the ``authentication_policy`` and ``authorization_policy``
+.. note:: The ``authentication_policy`` and ``authorization_policy``
    arguments may also be passed to their respective methods mentioned above
    as :term:`dotted Python name` values, each representing the dotted name
    path to a suitable implementation global defined at Python module scope.
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index f5c741f52..3a9225032 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -77,9 +77,9 @@ Here's a high-level time-ordered overview of what happens when you press
 
    Note that the constructor function accepts a ``global_config`` argument,
    which is a dictionary of key/value pairs mentioned in the ``[DEFAULT]``
-   section of an ``.ini`` file (if `[DEFAULT]
-   <http://docs.pylonsproject.org/projects/pyramid/dev/narr/paste.html#defaults-section-of-a-pastedeploy-ini-file>`__
-   is present).  It also accepts a ``**settings`` argument, which collects
+   section of an ``.ini`` file
+   (if :ref:`[DEFAULT] <defaults_section_of_pastedeploy_file>` is present).
+   It also accepts a ``**settings`` argument, which collects
    another set of arbitrary key/value pairs.  The arbitrary key/value pairs
    received by this function in ``**settings`` will be composed of all the
    key/value pairs that are present in the ``[app:main]`` section (except for
diff --git a/docs/narr/threadlocals.rst b/docs/narr/threadlocals.rst
index 909f643a0..5ff70565c 100644
--- a/docs/narr/threadlocals.rst
+++ b/docs/narr/threadlocals.rst
@@ -62,8 +62,7 @@ Because one :app:`Pyramid` application is permitted to call
 (perhaps as a :term:`WSGI` app with help from the
 :func:`pyramid.wsgi.wsgiapp2` decorator), these variables are
 managed in a *stack* during normal system operations.  The stack
-instance itself is a `threading.local
-<http://docs.python.org/library/threading.html#threading.local>`_.
+instance itself is a :class:`threading.local`.
 
 During normal operations, the thread locals stack is managed by a
 :term:`Router` object.  At the beginning of a request, the Router
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 16af4d088..a327e937b 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -70,8 +70,8 @@ via its ``route_name`` predicate, that view callable will always be found and
 invoked when the associated route pattern matches during a request.
 
 More commonly, you will not use any ``add_view`` statements in your project's
-"setup" code, instead only using ``add_route`` statements using a
-:term:`scan` for to associate view callables with routes.  For example, if
+"setup" code. You will instead use ``add_route`` statements, and use a
+:term:`scan` to associate view callables with routes.  For example, if
 this is a portion of your project's ``__init__.py``:
 
 .. code-block:: python
@@ -875,8 +875,7 @@ which you started the application from.  For example:
 .. code-block:: text
    :linenos:
 
-    [chrism@thinko pylonsbasic]$ PYRAMID_DEBUG_ROUTEMATCH=true \
-                                 bin/pserve development.ini
+    $ PYRAMID_DEBUG_ROUTEMATCH=true bin/pserve development.ini
     Starting server in PID 13586.
     serving on 0.0.0.0:6543 view at http://127.0.0.1:6543
     2010-12-16 14:45:19,956 no route matched for url \
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 96c0b88cf..ed01a1061 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -38,11 +38,11 @@ A view configuration statement is made about information present in the
 
 View configuration is performed in one of two ways:
 
-- by running a :term:`scan` against application source code which has a
+- By running a :term:`scan` against application source code which has a
   :class:`pyramid.view.view_config` decorator attached to a Python object as
   per :ref:`mapping_views_using_a_decorator_section`.
 
-- by using the :meth:`pyramid.config.Configurator.add_view` method as per
+- By using the :meth:`pyramid.config.Configurator.add_view` method as per
   :ref:`mapping_views_using_imperative_config_section`.
 
 .. index::
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 8ebdfe219..5a7be15b0 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -264,9 +264,9 @@ also be used by application developers to convert arbitrary exceptions to
 responses.
 
 To register a view that should be called whenever a particular exception is
-raised from with :app:`Pyramid` view code, use the exception class or one of
-its superclasses as the ``context`` of a view configuration which points at a
-view callable you'd like to generate a response.
+raised from within :app:`Pyramid` view code, use the exception class (or one of
+its superclasses) as the :term:`context` of a view configuration which points
+at a view callable you'd like to generate a response for.
 
 For example, given the following exception class in a module named
 ``helloworld.exceptions``:
@@ -353,7 +353,7 @@ Exception views can be configured with any view registration mechanism:
 
 .. _http_redirect:
 
-Using a View Callable to Do an HTTP Redirect
+Using a View Callable to do an HTTP Redirect
 --------------------------------------------
 
 You can issue an HTTP redirect by using the
@@ -524,7 +524,6 @@ The :term:`context` and :term:`request` arguments passed to a view function
 defined in this style can be defined as follows:
 
 context
-
   The :term:`resource` object found via tree :term:`traversal` or :term:`URL
   dispatch`.
 
@@ -537,41 +536,41 @@ The following types work as view callables in this style:
    e.g.:
 
    .. code-block:: python
-	  :linenos:
+      :linenos:
 
-	  from pyramid.response import Response
+       from pyramid.response import Response
 
-	  def view(context, request):
-		  return Response('OK')
+       def view(context, request):
+           return Response('OK')
 
 #. Classes that have an ``__init__`` method that accepts ``context,
    request`` and a ``__call__`` method which accepts no arguments, e.g.:
 
    .. code-block:: python
-	  :linenos:
+      :linenos:
 
-	  from pyramid.response import Response
+      from pyramid.response import Response
 
-	  class view(object):
-		  def __init__(self, context, request):
-			  self.context = context
-			  self.request = request
+      class view(object):
+         def __init__(self, context, request):
+             self.context = context
+             self.request = request
 
-		  def __call__(self):
-			  return Response('OK')
+         def __call__(self):
+             return Response('OK')
 
 #. Arbitrary callables that have a ``__call__`` method that accepts
    ``context, request``, e.g.:
 
    .. code-block:: python
-	  :linenos:
+      :linenos:
 
-	  from pyramid.response import Response
+      from pyramid.response import Response
 
-	  class View(object):
-		  def __call__(self, context, request):
-			  return Response('OK')
-	  view = View() # this is the view callable
+      class View(object):
+          def __call__(self, context, request):
+              return Response('OK')
+      view = View() # this is the view callable
 
 This style of calling convention is most useful for :term:`traversal` based
 applications, where the context object is frequently used within the view