convert remainder of docs to use pyramid instead of repoze.bfg

1 files changed, 0 insertions, 771 deletions

diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
deleted file mode 100644
index 8447f8e38..000000000
--- a/docs/whatsnew-1.3.rst
+++ /dev/null
@@ -1,771 +0,0 @@
-What's New In :mod:`repoze.bfg` 1.3
-===================================
-
-This article explains the new features in :mod:`repoze.bfg` version
-1.3 as compared to the previous 1.2 release.  It also documents
-backwards incompatibilities between the two versions and deprecations
-added to 1.3, as well as software dependency changes and notable
-documentation additions.
-
-Major Feature Additions
------------------------
-
-The major feature additions in 1.3 are:
-
-- *Internationalization* (i18n) and *localization* (l10n) services
-
-- *Exception views*
-
-Internationalization and Localization
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-:mod:`repoze.bfg` 1.3 offers internationalization (i18n) and
-localization (l10n) subsystems that can be used to translate the text
-of buttons, the text of error messages and other software- and
-template-defined values into the native language of a user of your
-application.
-
-:mod:`repoze.bfg` i18n / l10n framework includes:
-
-- Support for :term:`translation string` specifications.
-
-- Tools allowing you to specify and work with :term:`gettext`
-  :term:`message catalog` files to allow for text translation.
-
-- :term:`Locale name` negotiation features.
-
-- Translation and pluralization services.
-
-For detailed documentation about :mod:`repoze.bfg`
-internationalization and localization features, see
-:ref:`i18n_chapter`.
-
-Exception Views
-~~~~~~~~~~~~~~~~
-
-In :mod:`repoze.bfg` 1.3+, when you use an exception (anything that
-inherits from the Python :exc:`Exception` builtin) as view context
-argument, e.g.:
-
-.. code-block:: python
-   :linenos:
-
-      from repoze.bfg.view import bfg_view
-      from repoze.bfg.exceptions import NotFound
-      from webob.exc import HTTPNotFound
-
-      @bfg_view(context=NotFound)
-      def notfound_view(request):
-          return HTTPNotFound()
-
-For the above example, when the :exc:`repoze.bfg.exceptions.NotFound`
-exception is raised by any view or any root factory, the
-``notfound_view`` view callable will be invoked and its response
-returned.
-
-Other normal view predicates can also be used in combination with an
-exception view registration:
-
-.. code-block:: python
-   :linenos:
-
-      from repoze.bfg.view import bfg_view
-      from repoze.bfg.exceptions import NotFound
-      from webob.exc import HTTPNotFound
-
-      @bfg_view(context=NotFound, route_name='home')
-      def notfound_view(request):
-          return HTTPNotFound()
-
-The above exception view names the ``route_name`` of ``home``, meaning
-that it will only be called when the route matched has a name of
-``home``.  You can therefore have more than one exception view for any
-given exception in the system: the "most specific" one will be called
-when the set of request circumstances match the view registration.
-The only predicate that cannot be not be used successfully is
-``name``.  The name used to look up an exception view is always the
-empty string.
-
-Existing (pre-1.3) normal views registered against objects inheriting
-from :class:`Exception` will continue to work.  Exception views used
-for user-defined exceptions and system exceptions used as contexts
-will also work.
-
-The feature can be used with any view registration mechanism
-(``@bfg_view`` decorator, ZCML, or imperative
-:meth:`repoze.bfg.configuration.Configurator.add_view` styles).
-
-This feature was kindly contributed by Andrey Popp.
-
-Minor Feature Additions
------------------------
-
-- Use :term:`Venusian` to perform ``@bfg_view`` decorator scanning
-  rather than relying on a BFG-internal decorator scanner.  This means
-  that user-defined decorators can be defined and found during
-  :mod:`repoze.bfg` scanning.  See
-  :ref:`registering_configuration_decorators` for more information.
-
-- It is now possible to turn on Chameleon template "debugging mode"
-  for all Chameleon BFG templates by setting a BFG-related Paster
-  ``.ini`` file setting named ``debug_templates``. The exceptions
-  raised by Chameleon templates when a rendering fails are sometimes
-  less than helpful.  ``debug_templates`` allows you to configure your
-  application development environment so that exceptions generated by
-  Chameleon during template compilation and execution will contain
-  more helpful debugging information.  This mode is on by default in
-  newly generated projects.  See also :ref:`debug_templates_section`.
-
-- A new API method named
-  :meth:`repoze.bfg.configuration.Configurator.derive_view` was
-  added. This API can be used to generate a BFG view callable from a
-  user-supplied function, instance, or class. This useful for external
-  framework and plugin authors wishing to wrap callables supplied by
-  their users which follow the same calling conventions and response
-  conventions as objects that can be supplied directly to BFG as a
-  view callable.
-
-- Prior to 1.3, a *route predicate* had no access to route pattern
-  matching information and had no way to know which route was matched.
-  As of 1.3a4, each of the predicate callables fed to the
-  ``custom_predicates`` argument of
-  :meth:`repoze.bfg.configuration.Configurator.add_route` or the
-  ``custom_predicates`` ZCML attribute can be a callable accepting two
-  arguments.  The first argument passed to a custom predicate is a
-  dictionary conventionally named ``info``.  The second argument is
-  the current :term:`request` object.  The ``info`` dictionary has a
-  number of contained values: ``match`` is a dictionary: it represents
-  the arguments matched in the URL by the route.  ``route`` is an
-  object representing the route which was matched.  See also
-  :ref:`custom_route_predicates`.  In prior versions, the ``info``
-  argument was always ``None``.
-
-- The :func:`repoze.bfg.url.route_url` API has changed.  If a keyword
-  ``_app_url`` is present in the arguments passed to ``route_url``,
-  this value will be used as the protocol/hostname/port/leading path
-  prefix of the generated URL.  For example, using an ``_app_url`` of
-  ``http://example.com:8080/foo`` would cause the URL
-  ``http://example.com:8080/foo/fleeb/flub`` to be returned from this
-  function if the expansion of the route pattern associated with the
-  ``route_name`` expanded to ``/fleeb/flub``.
-
-- It is now possible to use a URL as the ``name`` argument fed to
-  :meth:`repoze.bfg.configuration.Configurator.add_static_view`.  When
-  the name argument is a URL, the :func:`repoze.bfg.url.static_url`
-  API will generate join this URL (as a prefix) to a path including
-  the static file name.  This makes it more possible to put static
-  media on a separate webserver for production, while keeping static
-  media package-internal and served by the development webserver
-  during development.
-
-- New argument to
-  :class:`repoze.bfg.configuration.Configurator.add_route` and the
-  ZCML ``route`` directive: ``traverse``.  If you would like to cause
-  the :term:`context` to be something other than the :term:`root`
-  object when this route matches, you can spell a traversal pattern as
-  the ``traverse`` argument.  This traversal pattern will be used as
-  the traversal path: traversal will begin at the root object implied
-  by this route (either the global root, or the object returned by the
-  ``factory`` associated with this route).  See
-  :class:`repoze.bfg.configuration.Configurator.add_route` for more
-  information (the ``traverse`` argument).
-
-- A new method exists:
-  :meth:`repoze.bfg.configuration.Configurator.set_request_factory`.
-  If used, this method will set the factory used by the
-  :mod:`repoze.bfg` router to create all request objects.
-
-- The :class:`repoze.bfg.configuration.Configurator` constructor takes
-  an additional argument: ``request_factory``.  If used, this argument
-  will set the factory used by the :mod:`repoze.bfg` router to create
-  all request objects.
-
-- A new method exists
-  :meth:`repoze.bfg.configuration.Configurator.set_renderer_globals_factory`.
-  If used, this method will set the factory used by the
-  :mod:`repoze.bfg` router to create renderer globals.
-
-- A new method exists:
-  :meth:`repoze.bfg.configuration.Configurator.get_settings`.  If
-  used, this method will return the current settings object (performs
-  the same job as the :func:`repoze.bfg.settings.get_settings` API).
-
-- The :class:`repoze.bfg.configuration.Configurator` constructor takes
-  an additional argument: ``renderer_globals_factory``.  If used, this
-  argument will set the factory used by the :mod:`repoze.bfg` router
-  to create renderer globals.
-
-- Add :func:`repoze.bfg.renderers.render`,
-  :func:`repoze.bfg.renderers.render_to_response` and
-  :func:`repoze.bfg.renderers.get_renderer` functions.  These are
-  imperative APIs which will use the same rendering machinery used by
-  view configurations with a ``renderer=`` attribute/argument to
-  produce a rendering or renderer.  Because these APIs provide a
-  central API for all rendering, they now form the preferred way to
-  perform imperative template rendering.  Using functions named
-  ``render_*`` from modules such as :mod:`repoze.bfg.chameleon_zpt`
-  and :mod:`repoze.bfg.chameleon_text` is now discouraged (although
-  not deprecated).  The code the backing older
-  templating-system-specific APIs now calls into the newer
-  :mod:`repoze.bfg.renderer` code.
-
-- The
-  :meth:`repoze.bfg.configuration.Configurator.testing_add_template`
-  method has been renamed to
-  :meth:`repoze.bfg.configuration.Configurator.testing_add_renderer`.
-  A backwards compatibility alias is present using the old name.
-
-- When decoding a URL segment to Unicode fails, the exception raised
-  is now :exc:`repoze.bfg.exceptions.URLDecodeError` instead of
-  :exc:`UnicodeDecodeError`.  This makes it possible to register an
-  exception view invoked specifically when :mod:`repoze.bfg` cannot
-  decode a URL.
-
-- A :func:`repoze.bfg.events.subscriber` decorator was added.  This
-  decorator can be used to decorates module-scope functions, which are
-  then treated as event listeners after a scan() is performed.  See
-  the :ref:`events_chapter` documentation chapter and the
-  :mod:`repoze.bfg.events` module documentation for more information.
-
-- The :func:`repoze.bfg.configuration.Configurator.add_route` API now
-  returns the route object that was added.
-
-- New API class:
-  :class:`repoze.bfg.view.AppendSlashNotFoundViewFactory`.
-
-  There can only be one :term:`Not Found view` in any
-  :mod:`repoze.bfg` application.  Even if you use
-  :func:`repoze.bfg.view.append_slash_notfound_view` as the Not Found
-  view, :mod:`repoze.bfg` still must generate a ``404 Not Found``
-  response when it cannot redirect to a slash-appended URL; this not
-  found response will be visible to site users.
-
-  If you don't care what this 404 response looks like, and only you
-  need redirections to slash-appended route URLs, you may use the
-  :func:`repoze.bfg.view.append_slash_notfound_view` object as the Not
-  Found view.  However, if you wish to use a *custom* notfound view
-  callable when a URL cannot be redirected to a slash-appended URL,
-  you may wish to use an instance of the
-  :class:`repoze.bfg.view.AppendSlashNotFoundViewFactory` class as the
-  Not Found view, supplying a :term:`view callable` to be used as the
-  custom notfound view as the first argument to its constructor.  For
-  instance:
-
-  .. code-block:: python
-
-       from repoze.bfg.exceptions import NotFound
-       from repoze.bfg.view import AppendSlashNotFoundViewFactory
-
-       def notfound_view(context, request):
-           return HTTPNotFound('It aint there, stop trying!')
-
-       custom_append_slash = AppendSlashNotFoundViewFactory(notfound_view)
-       config.add_view(custom_append_slash, context=NotFound)
-
-  The ``notfound_view`` supplied must adhere to the two-argument view
-  callable calling convention of ``(context, request)`` (``context``
-  will be the exception object).
-
-- The :class:`repoze.bfg.configuration.Configurator` constructor now
-  accepts a dotted name *string* to a package as a ``package``
-  argument. The ``package`` argument was previously required to be a
-  package *object* (not a dotted name string).
-
-- The :meth:`repoze.bfg.configuration.Configurator.with_package`
-  method was added.  This method returns a new Configurator using the
-  same application registry as the configurator object it is called
-  upon. The new configurator is created afresh with its ``package``
-  constructor argument set to the value passed to ``with_package``.
-
-- The :meth:`repoze.bfg.configuration.Configurator.maybe_dotted`
-  method resolves a Python dotted name string supplied as its
-  ``dotted`` argument to a global Python object.  If the value cannot
-  be resolved, a :exc:`repoze.bfg.configuration.ConfigurationError` is
-  raised.  If the value supplied as ``dotted`` is not a string, the
-  value is returned unconditionally without any resolution attempted.
-
-- The new
-  :meth:`repoze.bfg.configuration.Configurator.absolute_resource_spec`
-  method resolves a potentially relative :term:`resource
-  specification` string into an absolute version.
-
-- A new :meth:`repoze.bfg.request.Request.add_response_callback` API
-  has been added.  It can be used to influence response values before
-  a concrete response object has been created.  See the
-  :ref:`using_response_callbacks` for more information.
-
-- The :class:`repoze.bfg.interfaces.INewResponse` interface now
-  includes a ``request`` attribute; as a result, a handler for
-  INewResponse now has access to the request which caused the
-  response.
-
-- Each of the follow methods of the
-  :class:`repoze.bfg.configuration.Configurator` now allow the
-  below-named arguments to be passed as "dotted name strings"
-  (e.g. "foo.bar.baz") rather than as actual implementation objects
-  that must be imported:
-
-  setup_registry
-     root_factory, authentication_policy, authorization_policy,
-     debug_logger, locale_negotiator, request_factory,
-     renderer_globals_factory
-
-  add_subscriber
-     subscriber, iface
-
-  derive_view
-     view
-
-  add_view
-     view, ``for_``, context, request_type, containment
-
-  add_route()
-     view, view_for, factory, ``for_``, view_context
-
-  scan
-     package
-
-  add_renderer
-     factory
-
-  set_forbidden_view
-     view
-
-  set_notfound_view
-     view
-
-  set_request_factory
-     factory
-
-  set_renderer_globals_factory()
-     factory
-
-  set_locale_negotiator
-     negotiator
-
-  testing_add_subscriber
-     event_iface
-
-- The argument to
-  :meth:`repoze.bfg.configuration.Configurator.add_route` which was
-  previously called ``path`` is now called ``pattern`` for better
-  explicability.  For backwards compatibility purposes, passing a
-  keyword argument named ``path`` to ``add_route`` will still work
-  indefinitely.
-
-- The ``path`` attribute to the ZCML ``route`` directive (see
-  :ref:`route_directive`) is now named ``pattern`` for better
-  explicability.  The older ``path`` attribute will continue to work
-  indefinitely.
-
-- The ``routesalchemy`` paster template has been updated to use
-  ``pattern`` in its route declarations rather than ``path``.
-
-- In support of making it easier to configure applications which are
-  "secure by default", a default permission feature was added.  If
-  supplied, the default permission is used as the permission string to
-  all view registrations which don't otherwise name a permission.
-  These APIs are in support of that:
-
-  - A new constructor argument was added to
-    :class:`repoze.bfg.configuration.Configurator`:
-    ``default_permission``.
-
-  - A new method was added:
-    :meth:`repoze.bfg.configuration.Configurator.set_default_permission`.
-
-  - A new ZCML directive was added: :ref:`default_permission_directive`.
-
-- Add a new request API:
-  :meth:`repoze.bfg.request.Request.add_finished_callback`.  Finished
-  callbacks are called by the router unconditionally near the very end
-  of request processing.  See the :ref:`using_finished_callbacks` for
-  more information.
-
-- A ``matched_route`` attribute is now added to the :term:`request`
-  object when a route has matched.  Its value is the :term:`route`
-  object that matched (see :class:`repoze.bfg.interfaces.IRoute` for
-  the API of a route object).
-
-- The ``exception`` attribute of the :term:`request` is now set
-  slightly earlier and in a slightly different set of scenarios by the
-  router, for benefit of "finished callbacks" and "response
-  callbacks".  In previous versions, the ``exception`` attribute of
-  the request was not set at all if an exception view was not found.
-  In this version, the ``request.exception`` attribute is set
-  immediately when an exception is caught by the router, even if an
-  exception view could not be found.
-
-- The :meth:`repoze.bfg.configuration.Configurator.add_route` method
-  now accepts a ``pregenerator`` argument.  The pregenerator for the
-  resulting route is called by :func:`repoze.bfg.url.route_url` in
-  order to adjust the set of arguments passed to it by the user for
-  special purposes, such as Pylons 'subdomain' support.  It will
-  influence the URL returned by ``route_url``.  See
-  :class:`repoze.bfg.interfaces.IRoutePregenerator` for more
-  information.
-
-- Compatibility with WebOb 1.0 (now requires WebOb >= 1.0).
-
-- The :meth:`repoze.bfg.traversal.traversal_path` API now eagerly
-  attempts to encode a Unicode ``path`` into ASCII before attempting
-  to split it and decode its segments.  This is for convenience,
-  effectively to allow a (stored-as-Unicode-in-a-database, or
-  retrieved-as-Unicode-from-a-request-parameter) Unicode path to be
-  passed to :meth:`repoze.bfg.traversal.find_model`, which eventually
-  internally uses the ``traversal_path`` function under the hood.  In
-  version 1.2 and prior, if the ``path`` was Unicode, that Unicode was
-  split on slashes and each resulting segment value was Unicode.  An
-  inappropriate call to the ``decode()`` method of a resulting Unicode
-  path segment could cause a ``UnicodeDecodeError`` to occur even if
-  the Unicode representation of the path contained no 'high order'
-  characters (it effectively did a "double decode").  By converting
-  the Unicode path argument to ASCII before we attempt to decode and
-  split, genuine errors will occur in a more obvious place while also
-  allowing us to handle (for convenience) the case that it's a Unicode
-  representation formed entirely from ASCII-compatible characters.
-
-Backwards Incompatibilities
----------------------------
-
-- In previous releases, when a URL could not be decoded from UTF-8
-  during traversal, a :exc:`TypeError` was raised.  Now the error
-  which is raised is :exc:`repoze.bfg.exceptions.URLDecodeError`.
-
-- A new internal exception class (*not* an API) named
-  ``repoze.bfg.exceptions.PredicateMismatch`` now exists.  This
-  exception is currently raised when no constituent view of a
-  multiview can be called (due to no predicate match).  Previously, in
-  this situation, a :exc:`repoze.bfg.exceptions.NotFound` exception
-  was raised.  We provide backwards compatibility for code that
-  expected a ``NotFound`` to be raised when no predicates match by
-  causing ``repoze.bfg.exceptions.PredicateMismatch`` to inherit from
-  ``NotFound``.  This will cause any exception view registered for
-  ``NotFound`` to be called when a predicate mismatch occurs, as was
-  the previous behavior.
-
-  There is however, one perverse case that will expose a backwards
-  incompatibility.  If 1) you had a view that was registered as a
-  member of a multiview 2) this view explicitly raised a ``NotFound``
-  exception *in order to* proceed to the next predicate check in the
-  multiview, that code will now behave differently: rather than
-  skipping to the next view match, a NotFound will be raised to the
-  top-level exception handling machinery instead.  For code to be
-  depending upon the behavior of a view raising ``NotFound`` to
-  proceed to the next predicate match, would be tragic, but not
-  impossible, given that ``NotFound`` is a public interface.
-  ``repoze.bfg.exceptions.PredicateMismatch`` is not a public API and
-  cannot be depended upon by application code, so you should not
-  change your view code to raise ``PredicateMismatch``.  Instead, move
-  the logic which raised the ``NotFound`` exception in the view out
-  into a custom view predicate.
-
-- If, when you run your application's unit test suite under BFG 1.3, a
-  ``KeyError`` naming a template or a ``ValueError`` indicating that a
-  'renderer factory' is not registered may is raised
-  (e.g. ``ValueError: No factory for renderer named '.pt' when looking
-  up karl.views:templates/snippets.pt``), you may need to perform some
-  extra setup in your test code.
-
-  The best solution is to use the
-  :meth:`repoze.bfg.configuration.Configurator.testing_add_renderer`
-  (or, alternately the deprecated
-  :func:`repoze.bfg.testing.registerTemplateRenderer` or
-  `repoze.bfg.testing.registerDummyRenderer`) API within the code
-  comprising each individual unit test suite to register a "dummy"
-  renderer for each of the templates and renderers used by code under
-  test.  For example:
-
-  .. code-block:: python
-
-    config = Configurator()
-    config.testing_add_renderer('karl.views:templates/snippets.pt')
-
-  This will register a basic dummy renderer for this particular
-  missing template.  The
-  :meth:`repoze.bfg.configuration.Configurator.testing_add_renderer`
-  API actually *returns* the renderer, but if you don't care about how
-  the render is used, you don't care about having a reference to it
-  either.
-
-  A more rough way to solve the issue exists.  It causes the "real"
-  template implementations to be used while the system is under test,
-  which is suboptimal, because tests will run slower, and unit tests
-  won't actually *be* unit tests, but it is easier.  Always ensure you
-  call the
-  :meth:`repoze.bfg.configuration.Configurator.setup_registry`
-  method.  For example:
-
-  .. code-block:: python
-
-    reg = MyRegistry()
-    config = Configurator(registry=reg)
-    config.setup_registry()
-
-  Calling :meth:`repoze.bfg.configuration.Configurator.setup_registry`
-  only has an effect if you're *passing in* a ``registry`` argument to
-  the Configurator constructor.  ``setup_registry`` is called by the
-  course of normal operations anyway if you do not pass in a
-  ``registry``.
-
-  If your test suite isn't using a Configurator yet, and is still
-  using the older :mod:`repoze.bfg.testing` APIs name
-  :func:`repoze.bfg.testng.setUp` or
-  :func:`repoze.bfg.testng.cleanUp`, these will register the renderers
-  on your behalf.
-
-  A variant on the symptom for this theme exists: you may already be
-  dutifully registering a dummy template or renderer for a template
-  used by the code you're testing using
-  :meth:`repoze.bfg.configuration.Configurator.testing_register_renderer`
-  or :func:`repoze.bfg.testing.registerTemplateRenderer`, but (perhaps
-  unbeknownst to you) the code under test expects to be able to use a
-  "real" template renderer implementation to retrieve or render
-  *another* template that you forgot was being rendered as a side
-  effect of calling the code you're testing.  This happened to work
-  because it found the *real* template while the system was under test
-  previously, and now it cannot.  The solution is the same.
-
-  It may also help reduce confusion to use a :term:`resource
-  specification` to specify the template path in the test suite and
-  code rather than a relative path in either.  A resource
-  specification is unambiguous, while a relative path needs to be
-  relative to "here", where "here" isn't always well-defined ("here"
-  in a test suite may or may not be the same as "here" in the code
-  under test).
-
-- A bug existed in the regular expression to do URL matching.  As an
-  example, the URL matching machinery would cause the pattern
-  ``/{foo}`` to match the root URL ``/`` resulting in a match
-  dictionary of ``{'foo':u''}`` or the pattern ``/{fud}/edit might
-  match the URL ``//edit`` resulting in a match dictionary of
-  ``{'fud':u''}``.  It was always the intent that ``:segment`` markers
-  in the pattern would need to match *at least one* character, and
-  never match the empty string.  This, however, means that in certain
-  circumstances, a routing match which your application inadvertently
-  depended upon may no longer happen.
-
-- The router no longer sets the value ``wsgiorg.routing_args`` into
-  the environ when a route matches. The value used to be something
-  like ``((), matchdict)``.  This functionality was only ever
-  obliquely referred to in change logs; it was never documented as an
-  API.
-
-- The ``exception`` attribute of the request now defaults to ``None``.
-  In prior versions, the ``request.exception`` attribute did not exist
-  if an exception was not raised by user code during request
-  processing; it only began existence once an exception view was
-  found.
-
-- Due to changes introduced WebOb 1.0, the
-  ``repoze.bfg.request.make_request_ascii`` event subscriber no longer
-  worked, so it has been removed.  This subscriber was meant to be used
-  in a deployment so that code written before BFG 0.7.0 could run
-  unchanged.  At this point, such code will need to be rewritten to
-  expect Unicode from ``request.GET``, ``request.POST`` and
-  ``request.params`` or it will need to be changed to use
-  ``request.str_POST``, ``request.str_GET`` and/or
-  ``request.str_params`` instead of the non-``str`` versions of same,
-  as the non-``str`` versions of the same APIs always now perform
-  decoding to Unicode.
-
-Deprecations and Behavior Differences
--------------------------------------
-
-- The exception views feature replaces the need for the
-  ``set_notfound_view`` and ``set_forbidden_view`` methods of the
-  :class:`repoze.bfg.configuration.Configurator` as well as the
-  :ref:`notfound_directive` and :ref:`forbidden_directive` ZCML
-  directives.  Those methods and directives will continue to work for
-  the foreseeable future, but they are deprecated in the
-  documentation.
-
-- The ``repoze.bfg.renderers.rendered_response`` function was never an
-  official API, but may have been imported by extensions in the wild.
-  It is officially deprecated in this release.  Use
-  :func:`repoze.bfg.renderers.render_to_response` instead.
-
-- The following APIs are *documentation* deprecated (meaning they are
-  officially deprecated in documentation but do not raise a
-  deprecation error upon their usage, and may continue to work for an
-  indefinite period of time):
-
-  In the :mod:`repoze.bfg.chameleon_zpt` module: ``get_renderer``,
-  ``get_template``, ``render_template``,
-  ``render_template_to_response``.  The suggested alternatives are
-  documented within the docstrings of those methods (which are still
-  present in the documentation).
-
-  In the :mod:`repoze.bfg.chameleon_text` module: ``get_renderer``,
-  ``get_template``, ``render_template``,
-  ``render_template_to_response``.  The suggested alternatives are
-  documented within the docstrings of those methods (which are still
-  present in the documentation).
-
-  In general, to perform template-related functions, one should now
-  use the various methods in the :mod:`repoze.bfg.renderers` module.
-
-- The ``repoze.bfg.interfaces.IWSGIApplicationCreatedEvent`` event
-  interface was renamed to
-  :class:`repoze.bfg.interfaces.IApplicationCreated`.  Likewise, the
-  ``repoze.bfg.events.WSGIApplicationCreatedEvent`` class was renamed
-  to :class:`repoze.bfg.events.ApplicationCreated`.  The older aliases
-  will continue to work indefinitely.
-
-- The ``repoze.bfg.interfaces.IAfterTraversal`` event interface was
-  renamed to :class:`repoze.bfg.interfaces.IContextFound`.  Likewise,
-  the ``repoze.bfg.events.AfterTraversal`` class was renamed to
-  :class:`repoze.bfg.events.ContextFound`.  The older aliases will
-  continue to work indefinitely.
-
-- References to the WSGI environment values ``bfg.routes.matchdict``
-  and ``bfg.routes.route`` were removed from documentation.  These
-  will stick around internally for several more releases, but it is
-  ``request.matchdict`` and ``request.matched_route`` are now the
-  "official" way to obtain the matchdict and the route object which
-  resulted in the match.
-
-Dependency Changes
-------------------
-
-- A new install-time dependency on the ``venusian`` distribution was
-  added.
-
-- A new install-time dependency on the ``translationstring``
-  distribution was added (internationalization).
-
-- Chameleon 1.2.3 or better is now required (internationalization and
-  per-template debug settings).
-
-- :mod:`repoze.bfg` ``tests_require`` now includes
-  ``repoze.sphinx.autointerface`` as a dependency.
-
-Documentation Enhancements
---------------------------
-
-- Exception view documentation was added to the :ref:`hooks_chapter`
-  narrative chapter.
-
-- A new narrative chapter entitled :ref:`i18n_chapter` was added.
-
-- The :ref:`environment_chapter` chapter was changed: documentation
-  about the ``default_locale_name`` setting was added.
-
-- A new API chapter for the :ref:`i18n_module` module was added.
-
-- Documentation for the new :ref:`translationdir_directive` and
-  :ref:`localenegotiator_directive` ZCML directives were added.
-
-- A section :ref:`custom_route_predicates` was added to the URL
-  Dispatch narrative chapter.
-
-- The :ref:`static_resources_section` and
-  :ref:`generating_static_resource_urls` sections of the Static
-  Resources chapter have been updated to mention using
-  :func:`repoze.bfg.url.static_url` to generate URLs to external
-  webservers.
-
-- Documentation for registering a new configuration decorator was
-  added in :ref:`registering_configuration_decorators`.
-
-- The authorization chapter of the :ref:`bfg_wiki_tutorial` was
-  changed to demonstrate authorization via a group rather than via a
-  direct username.
-
-- The authorization chapter of the :ref:`bfg_sql_wiki_tutorial` was
-  changed to demonstrate authorization via a group rather than via a
-  direct username.
-
-- The :ref:`hooks_chapter` chapter now contains a section about
-  changing the request factory.
-
-- The :ref:`hooks_chapter` chapter now contains sections about
-  changing the request factory and adding a renderer globals factory.
-
-- The :ref:`hybrid_chapter` chapter now contains a description of the
-  ``traverse`` route argument.
-
-- The API documentation includes a new module:
-  :mod:`repoze.bfg.renderers`.
-
-- The :ref:`templates` chapter was updated; all narrative that used
-  templating-specific APIs within examples to perform rendering (such
-  as the :func:`repoze.bfg.chameleon_zpt.render_template_to_response`
-  method) was changed to use :mod:`repoze.bfg.renderers` ``render_*``
-  functions.
-
-- Added description of the :class:`repoze.bfg.events.subscriber`
-  decorator to the :ref:`events_chapter` narrative documentation
-  chapter.
-
-- Added :class:`repoze.bfg.events.subscriber` API documentation to
-  :mod:`repoze.bfg.events` API docs.
-
-- Added a section named "Zope 3 Enforces 'TTW' Authorization Checks By
-  Default; BFG Does Not" to the :ref:`design_defense` chapter.
-
-- Expanded the :ref:`cleaning_up_after_a_request` section of the URL
-  Dispatch narrative chapter.
-
-- Expanded the :ref:`redirecting_to_slash_appended_routes` section of
-  the URL Dispatch narrative chapter.
-
-- Add an API chapter for the :mod:`repoze.bfg.request` module, which
-  includes documentation for the :class:`repoze.bfg.request.Request`
-  class (the "request object").
-
-- Modify the :ref:`webob_chapter` narrative chapter to reference the
-  new :mod:`repoze.bfg.request` API chapter.  Some content was moved
-  from this chapter into the API documentation itself.
-
-- Various changes to denote that Python dotted names are now allowed
-  as input to Configurator methods.
-
-- All narrative, API, and tutorial docs which referred to a route
-  pattern as a ``path`` have now been updated to refer to them as a
-  ``pattern``.
-
-- The :mod:`repoze.bfg.interfaces` API documentation page is now
-  rendered via ``repoze.sphinx.autointerface``.
-
-- The :ref:`urldispatch_chapter` chapter now refers to the
-  :mod:`repoze.bfg.interfaces` chapter to explain the API of an
-  :class:`repoze.bfg.interfaces.IRoute` object.
-
-- Added documentation for the :ref:`default_permission_directive` ZCML
-  directive.
-
-- Added documentation for the ``default_permission`` parameter of the
-  :class:`repoze.bfg.configuration.Configurator` constructor and the
-  :meth:`repoze.bfg.configuration.Configurator.set_default_permission``
-  method.
-
-- Added a new section to the :ref:`security_chapter` named
-  :ref:`setting_a_default_permission`.
-
-- Document ``renderer_globals_factory`` and ``request_factory``
-  arguments to the :class:`repoze.bfg.configuration.Configurator`
-  constructor.
-
-- Added two sections to the "Hooks" chapter of the documentation:
-  :ref:`using_response_callbacks` and :ref:`using_finished_callbacks`.
-
-- Added documentation of the ``request.exception`` attribute to the
-  :class:`repoze.bfg.request.Request` API documentation.
-
-- The :ref:`router_chapter` narrative chapter has been updated to note
-  finished and response callback steps.
-
-- New interface in interfaces API documentation:
-  :class:`repoze.bfg.interfaces.IRoutePregenerator`.
-
-- Added a "The Matched Route" section to the
-  :ref:`urldispatch_chapter` narrative docs chapter, detailing the
-  ``matched_route`` attribute.
-
-Licensing Changes
------------------
-
-- The Edgewall (BSD) license was added to the LICENSES.txt file, as
-  some code in the :mod:`repoze.bfg.i18n` module derives from
-  :term:`Babel` source.