improve changes docs

1 files changed, 29 insertions, 57 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index c94ecb800..b6f33715e 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -12,63 +12,19 @@ Features
   ``rendering_val``.  This can be used to introspect the value returned by a
   view in a BeforeRender subscriber.
 
-- New configurator directive:
-  ``pyramid.config.Configurator.add_request_handler``.  This directive adds
-  a request handler factory.
-
-  A request handler factory is used to wrap the Pyramid router's primary
-  request handling function.  This is a feature may be used by framework
-  extensions, to provide, for example, view timing support and as a
-  convenient place to hang bookkeeping code that examines exceptions before
-  they are returned to the server.
-
-  A request handler factory (passed as ``handler_factory``) must be a
-  callable which accepts two arguments: ``handler`` and ``registry``.
-  ``handler`` will be the request handler being wrapped.  ``registry`` will
-  be the Pyramid application registry represented by this Configurator.  A
-  request handler factory must return a request handler when it is called.
-
-  A request handler accepts a request object and returns a response object.
-
-  Here's an example of creating both a handler factory and a handler, and
-  registering the handler factory:
-
-  .. code-block:: python
-
-       import time
-
-       def timing_handler_factory(handler, registry):
-           if registry.settings['do_timing']:
-               # if timing support is enabled, return a wrapper
-               def timing_handler(request):
-                   start = time.time()
-                   try:
-                       response = handler(request)
-                   finally:
-                       end = time.time()
-                       print: 'The request took %s seconds' % (end - start)
-                   return response
-               return timing_handler
-           # if timing support is not enabled, return the original handler
-           return handler
-
-       config.add_request_handler(timing_handler_factory, 'timing')
-
-  The ``request`` argument to the handler will be the request created by
-  Pyramid's router when it receives a WSGI request.
-
-  If more than one request handler factory is registered into a single
-  configuration, the request handlers will be chained together.  The first
-  request handler factory added (in code execution order) will be called with
-  the default Pyramid request handler, the second handler factory added will
-  be called with the result of the first handler factory, ad infinitum. The
-  Pyramid router will use the outermost wrapper in this chain (which is a bit
-  like a WSGI middleware "pipeline") as its handler function.
-
-  The ``name`` argument to this function is required.  The name is used as a
-  key for conflict detection.  No two request handler factories may share the
-  same name in the same configuration (unless automatic_conflict_resolution
-  is able to resolve the conflict or this is an autocommitting configurator).
+- New configurator directive: ``pyramid.config.Configurator.add_tween``.
+  This directive adds a "tween".  A "tween" is used to wrap the Pyramid
+  router's primary request handling function.  This is a feature may be used
+  by Pyramid framework extensions, to provide, for example, view timing
+  support and as a convenient place to hang bookkeeping code.
+
+  Tweens are further described in the narrative docs section in the Hooks
+  chapter, named "Registering Tweens".
+
+- New paster command ``paster ptweens``, which prints the current "tween"
+  configuration for an application.  See the section entitled "Displaying
+  Tweens" in the Command-Line Pyramid chapter of the narrative documentation
+  for more info.
 
 - The Pyramid debug logger now uses the standard logging configuration
   (usually set up by Paste as part of startup).  This means that output from
@@ -80,6 +36,12 @@ Features
   will be ``None`` until an exception is caught by the Pyramid router, after
   which it will be the result of ``sys.exc_info()``.
 
+Internal
+--------
+
+- The Pyramid "exception view" machinery is now implemented as a "tween"
+  (``pyramid.tweens.excview_tween_factory``).
+
 Deprecations
 ------------
 
@@ -97,6 +59,16 @@ Backwards Incompatibilities
   that string is considered to be the name of a global Python logger rather
   than a dotted name to an instance of a logger.
 
+Documentation
+-------------
+
+- Added a new module to the API docs: ``pyramid.tweens``.
+
+- Added a "Registering Tweens" section to the "Hooks" narrative chapter.
+
+- Added a "Displaying Tweens" section to the "Command-Line Pyramid" narrative
+  chapter.
+
 1.1 (2011-07-22)
 ================