Merge branch 'master' of github.com:Pylons/pyramid

7 files changed, 58 insertions, 23 deletions

diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 52615533d..f7fa94daf 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -17,6 +17,10 @@ plugging application code that you've written into :app:`Pyramid` is also
 referred to within this documentation as "configuration"; you are configuring
 :app:`Pyramid` to call the code that makes up your application.
 
+.. seealso::
+   For information on ``.ini`` files for Pyramid applications see the
+   :ref:`startup_chapter` chapter.
+
 There are two ways to configure a :app:`Pyramid` application:
 :term:`imperative configuration` and :term:`declarative configuration`.  Both
 are described below.
diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst
index 71029bb33..c16673ae6 100644
--- a/docs/narr/logging.rst
+++ b/docs/narr/logging.rst
@@ -16,6 +16,11 @@ how to send log messages to loggers that you've configured.
    a third-party scaffold which does not create these files, the
    configuration information in this chapter may not be applicable.
 
+.. index:
+   pair: settings; logging
+   pair: .ini; logging
+   pair: logging; configuration
+
 .. _logging_config:
 
 Logging Configuration
@@ -242,7 +247,7 @@ level is set to ``INFO``, whereas the application's log level is set to
     [logger_myapp] 
     level = DEBUG 
     handlers = 
-    qualname = helloworld 
+    qualname = myapp 
 
 All of the child loggers of the ``myapp`` logger will inherit the ``DEBUG``
 level unless they're explicitly set differently. Meaning the ``myapp.views``,
@@ -294,15 +299,26 @@ use the :term:`pyramid_exclog` package.  Details about its configuration are
 in its `documentation
 <http://docs.pylonsproject.org/projects/pyramid_exclog/dev/>`_.
 
+.. index::
+   single: TransLogger
+   single: middleware; TransLogger
+   pair: configuration; middleware
+   single: settings; middleware
+   pair: .ini; middleware
+
+.. _request_logging_with_pastes_translogger:
+
 Request Logging with Paste's TransLogger 
 ----------------------------------------
 
-Paste provides the `TransLogger 
-<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. 
+The term:`WSGI` design is modular.  Waitress logs error conditions, debugging
+output, etc., but not web traffic.  For web traffic logging Paste provides the
+`TransLogger <http://pythonpaste.org/modules/translogger.html>`_
+:term:`middleware`.  TransLogger produces logs in the `Apache Combined Log
+Format <http://httpd.apache.org/docs/2.2/logs.html#combined>`_.  But
+TransLogger does not write to files, the Python logging system must be
+configured to do this.  The Python FileHandler_ logging handler can be used
+alongside TransLogger to create an ``access.log`` file similar to Apache's.
 
 Like any standard :term:`middleware` with a Paste entry point, TransLogger can
 be configured to wrap your application using ``.ini`` file syntax.  First,
@@ -343,10 +359,12 @@ function of your project's ``__init__`` file:
     app = TransLogger(app, setup_console_handler=False) 
     return app 
 
-TransLogger will automatically setup a logging handler to the console when
-called with no arguments, so it 'just works' in environments that don't
-configure logging. Since we've configured our own logging handlers, we need
-to disable that option via ``setup_console_handler = False``.
+
+.. note::
+    TransLogger will automatically setup a logging handler to the console when
+    called with no arguments, so it 'just works' in environments that don't
+    configure logging. Since our logging handlers are configured we disable
+    the automation via ``setup_console_handler = False``.
 
 With the filter in place, TransLogger's logger (named the ``wsgi`` logger) will
 propagate its log messages to the parent logger (the root logger), sending
@@ -361,9 +379,9 @@ its output to the console when we request a page:
     "Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko/20070725
     Firefox/2.0.0.6" 
 
-To direct TransLogger to an ``access.log`` FileHandler, we need to add that
-FileHandler to the list of handlers (named ``accesslog``), and ensure that the 
-``wsgi`` logger is configured and uses this handler accordingly:
+To direct TransLogger to an ``access.log`` FileHandler, we need the following
+to add a FileHandler (named ``accesslog``) to the list of handlers, and ensure
+that the ``wsgi`` logger is configured and uses this handler accordingly:
 
 .. code-block:: ini 
 
@@ -395,7 +413,7 @@ directs its records only to the ``accesslog`` handler.
 Finally, there's no need to use the ``generic`` formatter with TransLogger as
 TransLogger itself provides all the information we need. We'll use a
 formatter that passes-through the log messages as is. Add a new formatter
-called ``accesslog`` by include the following in your configuration file:
+called ``accesslog`` by including the following in your configuration file:
 
 .. code-block:: ini 
 
@@ -405,7 +423,9 @@ called ``accesslog`` by include the following in your configuration file:
     [formatter_accesslog] 
     format = %(message)s 
 
-Then wire this new ``accesslog`` formatter into the FileHandler: 
+
+Finally alter the existing configuration to wire this new
+``accesslog`` formatter into the FileHandler:
 
 .. code-block:: ini 
 
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index 7b4a7ea08..a1a23ed52 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -19,6 +19,7 @@ console.
 
 .. index::
    single: startup process
+   pair: settings; .ini
 
 The Startup Process
 -------------------
@@ -139,6 +140,13 @@ Here's a high-level time-ordered overview of what happens when you press
    The server serves the application, and the application is running, waiting
    to receive requests.
 
+.. seealso::
+   Logging configuration is described in the :ref:`logging_chapter`
+   chapter.  There, in :ref:`request_logging_with_pastes_translogger`,
+   you will also find an example of how to configure
+   :term:`middleware` to add pre-packaged functionality to your
+   application.
+
 .. index::
    pair: settings; deployment
    single: custom settings
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index 4ab39bb11..41a0dc8c0 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -700,7 +700,7 @@ we might need to detect situations when other people use the site. We
 need *logging*.
 
 Fortunately Pyramid uses the normal Python approach to logging. The
-scaffold generated in your ``development.ini`` a number of lines that
+scaffold generated in your ``development.ini`` has a number of lines that
 configure the logging for you to some reasonable defaults. You then see
 messages sent by Pyramid (for example, when a new request comes in).
 
diff --git a/docs/quick_tutorial/functional_testing.rst b/docs/quick_tutorial/functional_testing.rst
index 205ddf5cb..09b05b0bc 100644
--- a/docs/quick_tutorial/functional_testing.rst
+++ b/docs/quick_tutorial/functional_testing.rst
@@ -37,12 +37,15 @@ Steps
     $ $VENV/bin/python setup.py develop
     $ $VENV/bin/easy_install webtest
 
-#. Let's extend ``unit_testing/tutorial/tests.py`` to include a
+#. Let's extend ``functional_testing/tutorial/tests.py`` to include a
    functional test:
 
    .. literalinclude:: functional_testing/tutorial/tests.py
     :linenos:
 
+   Be sure this file is not executable, or ``nosetests`` may not 
+   include your tests.
+   
 #. Now run the tests:
 
    .. code-block:: bash
@@ -67,4 +70,4 @@ execution time of our tests.
 Extra Credit
 ============
 
-#. Why do our functional tests use ``b''``?
\ No newline at end of file
+#. Why do our functional tests use ``b''``?
diff --git a/docs/quick_tutorial/hello_world.rst b/docs/quick_tutorial/hello_world.rst
index 1a9ba4c9d..4ae80ca87 100644
--- a/docs/quick_tutorial/hello_world.rst
+++ b/docs/quick_tutorial/hello_world.rst
@@ -77,7 +77,7 @@ explanation:
 #. *Lines 12-14*. Use Pyramid's :term:`configurator` to connect
    :term:`view` code to a particular URL :term:`route`.
 
-#. *Lines 6-7*. Implement the view code that generates the
+#. *Lines 6-8*. Implement the view code that generates the
    :term:`response`.
 
 #. *Lines 15-17*. Publish a :term:`WSGI` app using an HTTP
diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst
index 3402c50e8..b8720711b 100644
--- a/docs/quick_tutorial/ini.rst
+++ b/docs/quick_tutorial/ini.rst
@@ -14,9 +14,9 @@ Pyramid has a first-class concept of
 :ref:`configuration <configuration_narr>` distinct from code.
 This approach is optional, but its presence makes it distinct from
 other Python web frameworks. It taps into Python's ``setuptools``
-library, which establishes conventions for how Python projects can be
-installed and provide "entry points". Pyramid uses an entry point to
-let a Pyramid application it where to find the WSGI app.
+library, which establishes conventions for installing and providing
+"entry points" for Python projects. Pyramid uses an entry point to
+let a Pyramid application know where to find the WSGI app.
 
 Objectives
 ==========