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

15 files changed, 283 insertions, 2368 deletions

diff --git a/docs/api/testing.rst b/docs/api/testing.rst
index 2fdea6cd7..fc4b76cc7 100644
--- a/docs/api/testing.rst
+++ b/docs/api/testing.rst
@@ -15,8 +15,6 @@
 
   .. autofunction:: registerView
 
-  .. autofunction:: registerViewPermission
-
   .. autofunction:: registerUtility
 
   .. autofunction:: registerAdapter
@@ -25,8 +23,6 @@
 
   .. autofunction:: registerRoute
 
-  .. autofunction:: registerRoutesMapper
-
   .. autofunction:: registerSettings
 
   .. autofunction:: setUp
diff --git a/docs/authorintro.rst b/docs/authorintro.rst
index 8a5387199..c97fbd00d 100644
--- a/docs/authorintro.rst
+++ b/docs/authorintro.rst
@@ -2,10 +2,10 @@
  Author Introduction
 =====================
 
-Welcome to "The :mod:`repoze.bfg` Web Application Framework".  In this
+Welcome to "The :mod:`pyramid` Web Application Framework".  In this
 introduction, I'll describe the audience for this book, I'll describe
 the book content, I'll provide some context regarding the genesis of
-:mod:`repoze.bfg`, and I'll thank some important people.
+:mod:`pyramid`, and I'll thank some important people.
 
 I hope you enjoy both this book and the software it documents.  I've
 had a blast writing both.
@@ -42,7 +42,7 @@ book.  For example, the book doesn't try to define common web-related
 concepts like "URL" or "query string."  Likewise, the book describes
 various interactions in terms of the HTTP protocol, but it does not
 describe how the HTTP protocol works in detail.  Like any good web
-framework, though, :mod:`repoze.bfg` shields you from needing to know
+framework, though, :mod:`pyramid` shields you from needing to know
 most of the gory details of web protocols and low-level data
 structures. As a result, you can usually avoid becoming "blocked"
 while you read this book even if you don't yet deeply understand web
@@ -58,10 +58,10 @@ This book is divided into four major parts:
 
 :ref:`narrative_documentation`
 
-  This is documentation which describes :mod:`repoze.bfg` concepts in
+  This is documentation which describes :mod:`pyramid` concepts in
   narrative form, written in a largely conversational tone.  Each
   narrative documentation chapter describes an isolated
-  :mod:`repoze.bfg` concept.  You should be able to get useful
+  :mod:`pyramid` concept.  You should be able to get useful
   information out of the narrative chapters if you read them
   out-of-order, or when you need only a reminder about a particular
   topic while you're developing an application.
@@ -71,18 +71,18 @@ This book is divided into four major parts:
   Each tutorial builds a sample application or implements a set of
   concepts with a sample; it then describes the application or
   concepts in terms of the sample.  You should read the tutorials if
-  you want a guided tour of :mod:`repoze.bfg`.
+  you want a guided tour of :mod:`pyramid`.
 
 :ref:`api_reference`
 
   Comprehensive reference material for every public API exposed by
-  :mod:`repoze.bfg`.  The API documentation is organized
+  :mod:`pyramid`.  The API documentation is organized
   alphabetically by module name.
 
 :ref:`zcml_reference`
 
   Comprehensive reference material for every :term:`ZCML directive`
-  provided by :mod:`repoze.bfg`.  The ZCML directive documentation is
+  provided by :mod:`pyramid`.  The ZCML directive documentation is
   organized alphabetically by directive name.
 
 .. index::
@@ -90,10 +90,13 @@ This book is divided into four major parts:
    single: Zope 3
    single: Zope 2
    single: repoze.bfg genesis
+   single: pyramid genesis
 
 The Genesis of :mod:`repoze.bfg`
 ================================
 
+Before the end of 2010, :mod:`pyramid` was known as :mod:`repoze.bfg`.
+
 I wrote :mod:`repoze.bfg` after many years of writing applications
 using :term:`Zope`.  Zope provided me with a lot of mileage: it wasn't
 until almost a decade of successfully creating applications using it
@@ -130,13 +133,16 @@ I decided that in the long term, creating a simpler framework that
 retained features I had become accustomed to when developing Zope
 applications was a more reasonable idea than continuing to use any
 Zope publisher or living with the limitations and unfamiliarities of a
-different framework.  The result is what is now :mod:`repoze.bfg`.
+different framework.  The result is what is now :mod:`pyramid`.
+
+The Genesis of :mod:`pyramid`
+=============================
 
-It is immodest to say so, but I believe :mod:`repoze.bfg` has turned
-out to be the very best Python web framework available today, bar
-none.  It combines all the "good parts" from other web frameworks into
-a cohesive whole that is reliable, down-to-earth, flexible, speedy,
-and well-documented.
+What was :mod:`repoze.bfg` has become :mod:`pyramid` as the result of
+a coalition built between the :term:`Repoze` and :term:`Pylons`
+community throughout the year 2010.  By merging technology, we're able
+to reduce duplication of effort, and take advantage of more of each
+others' technology.
 
 .. index::
    single: Bicking, Ian
diff --git a/docs/changes.rst b/docs/changes.rst
index c95a3d72a..a623f0b3f 100644
--- a/docs/changes.rst
+++ b/docs/changes.rst
@@ -1,4 +1,4 @@
-:mod:`repoze.bfg` Change History
+:mod:`pyramid` Change History
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. include:: ../CHANGES.txt
diff --git a/docs/conf.py b/docs/conf.py
index e8924f73e..eb236826b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# repoze.bfg documentation build configuration file, created by
+# pyramid documentation build configuration file, created by
 # sphinx-quickstart on Wed Jul 16 13:18:14 2008.
 #
 # This file is execfile()d with the current directory set to its containing dir.
@@ -54,14 +54,14 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General substitutions.
-project = 'The repoze.bfg Web Application Framework'
+project = 'The Pyramid Web Application Development Framework'
 copyright = '2008-2010, Agendaless Consulting'
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
 #
 # The short X.Y version.
-version = '1.3a15'
+version = '1.0a1'
 # The full version, including alpha/beta/rc tags.
 release = version
 
@@ -105,7 +105,7 @@ html_style = 'repoze.css'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-#html_title = 'The repoze.bfg Web Application Framework v%release%'
+#html_title = 'The Pyramid Web Application Development Framework v%release%'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None
@@ -174,7 +174,8 @@ latex_font_size = '10pt'
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
 latex_documents = [
-  ('latexindex', 'repozebfg.tex', 'The repoze.bfg Web Application Framework',
+  ('latexindex', 'repozebfg.tex',
+   'The Pyramid Web Application Development Framework',
    'Chris McDonough', 'manual'),
     ]
 
@@ -309,7 +310,7 @@ latex_elements = {
     'wrapperclass':'book',
     'date':'',
     'releasename':'Version',
-    'title':r'The repoze.bfg Web Application \newline Framework',
+    'title':r'The Pyramid Web Application \newline Development Framework',
 #    'pointsize':'12pt', # uncomment for 12pt version
 }
 
@@ -373,28 +374,6 @@ def setup(app):
     app.add_directive('mainmatter', mainmatter, 1, (0, 0, 0))
     app.add_directive('backmatter', backmatter, 1, (0, 0, 0))
 
-# strip "repoze.bfg." from all inline literals
-
-from sphinx.writers.latex import LaTeXTranslator
-
-def visit_literal(self, node):
-        self.no_contractions += 1
-        content = self.encode(node.astext().strip())
-        self.no_contractions -= 1
-        if self.in_title:
-            self.body.append(r'\texttt{%s}' % content)
-        elif node.has_key('role') and node['role'] == 'samp':
-            self.body.append(r'\samp{%s}' % content)
-        else:
-            # XXX special treatment of overlong ``repoze.bfg.foo``
-            # literals.
-            if 'repoze.bfg.' in content:
-                content = content.replace('repoze.bfg.', '')
-            self.body.append(r'\code{%s}' % content)
-        raise nodes.SkipNode
-    
-LaTeXTranslator.visit_literal = visit_literal
-
 # turn off all line numbers in latex formatting
 
 ## from pygments.formatters import LatexFormatter
@@ -410,7 +389,7 @@ LaTeXTranslator.visit_literal = visit_literal
 # -- Options for Epub output ---------------------------------------------------
 
 # Bibliographic Dublin Core info.
-epub_title = 'The repoze.bfg Web Application Framework, Version 1.3'
+epub_title = 'The Pyramid Web Application Development Framework, Version 1.0'
 epub_author = 'Chris McDonough'
 epub_publisher = 'Agendaless Consulting'
 epub_copyright = '2008-2010'
@@ -427,7 +406,7 @@ epub_scheme = 'ISBN'
 epub_identifier = '0615345379'
 
 # A unique identification for the text.
-epub_uid = 'The repoze.bfg Web Application Framework, Version 1.3-v0'
+epub_uid = 'The Pyramid Web Application Development Framework, Version 1.0'
 
 # HTML files that should be inserted before the pages created by sphinx.
 # The format is a list of tuples containing the path and title.
diff --git a/docs/conventions.rst b/docs/conventions.rst
index 020ed6dac..aaa4e8d09 100644
--- a/docs/conventions.rst
+++ b/docs/conventions.rst
@@ -75,19 +75,3 @@ discussed on a page, is rendered like so:
 
    Sidebar information.
 
-In printed versions of this book, Python modules classes, methods,
-functions, and attributes that are part of the :mod:`repoze.bfg`
-module are referenced in paragraph text.  These are contracted to omit
-the ``repoze.bfg`` prefix to reduce redundancy and increase
-readability.  Therefore, where you might expect:
-
-  .. code-block:: text
-
-     repoze.bfg.configuration.Configurator.add_view (pp. XXX)
-
-Instead a contracted version will be rendered:
-
-  .. code-block:: text
-
-     configuration.Configurator.add_view (pp. XXX)
-
diff --git a/docs/copyright.rst b/docs/copyright.rst
index 791d69f81..30a544cc4 100644
--- a/docs/copyright.rst
+++ b/docs/copyright.rst
@@ -1,7 +1,7 @@
 Copyright, Trademarks, and Attributions
 =======================================
 
-*The repoze.bfg Web Application Framework, Version 1.2*
+*The Pyramid Web Application Development Framework, Version 1.0*
 
 by Chris McDonough
 
@@ -26,9 +26,9 @@ similar license to this one.
 
 .. note::
 
-   While the :mod:`repoze.bfg` documentation is offered under the
+   While the :mod:`pyramid` documentation is offered under the
    Creative Commons Attribution-Nonconmmercial-Share Alike 3.0 United
-   States License, the :mod:`repoze.bfg` *software* is offered under a
+   States License, the :mod:`pyramid` *software* is offered under a
    `less restrictive (BSD-like) license
    <http://repoze.org/license.html>`_ .
 
@@ -74,21 +74,16 @@ Contacting The Publisher
 Please send documentation licensing inquiries, translation inquiries,
 and other business communications to `Agendaless Consulting
 <mailto:webmaster@agendaless.com>`_.  Please send software and other
-technical queries to the `repoze-dev maillist
-<http://lists.repoze.org/listinfo/repoze-dev>`_.
+technical queries to the `Pylons-discuss maillist
+<http://groups.google.com/group/pylons-discuss>`_.
 
 HTML Version and Source Code
 ----------------------------
 
 An HTML version of this book is freely available via
-http://bfg.repoze.org.
+http://pylonshq.com/pyramid.
 
 The source code for the examples used in this book are available
-within the :mod:`repoze.bfg` software distribution, always available
-via http://bfg.repoze.org.
-
-Errata
-------
-
-Errata for this book will be placed at `http://bfg.repoze.org/book_errata`.
+within the :mod:`pyramid` software distribution, always available
+via http://pylonshq.com/pyramid.
 
diff --git a/docs/designdefense.rst b/docs/designdefense.rst
index 9ae7c50d6..0e4784c66 100644
--- a/docs/designdefense.rst
+++ b/docs/designdefense.rst
@@ -1,9 +1,9 @@
 .. _design_defense:
 
-Defending BFG's Design
-======================
+Defending Pyramid's Design
+==========================
 
-From time to time, challenges to various aspects of :mod:`repoze.bfg`
+From time to time, challenges to various aspects of :mod:`pyramid`
 design are lodged.  To give context to discussions that follow, we
 detail some of the design decisions and trade-offs here.  In some
 cases, we acknowledge that the framework can be made better and we
@@ -11,17 +11,17 @@ describe future steps which will be taken to improve it; in some cases
 we just file the challenge as "noted", as obviously you can't please
 everyone all of the time.
 
-BFG Uses A Zope Component Architecture ("ZCA") Registry
--------------------------------------------------------
+Pyramid Uses A Zope Component Architecture ("ZCA") Registry
+-----------------------------------------------------------
 
-:mod:`repoze.bfg` uses a :term:`Zope Component Architecture` (ZCA)
+:mod:`pyramid` uses a :term:`Zope Component Architecture` (ZCA)
 "component registry" as its :term:`application registry` under the
-hood.  This is a point of some contention.  :mod:`repoze.bfg` is of a
+hood.  This is a point of some contention.  :mod:`pyramid` is of a
 :term:`Zope` pedigree, so it was natural for its developers to use a
 ZCA registry at its inception.  However, we understand that using a
 ZCA registry has issues and consequences, which we've attempted to
 address as best we can.  Here's an introspection about
-:mod:`repoze.bfg` use of a ZCA registry, and the trade-offs its usage
+:mod:`pyramid` use of a ZCA registry, and the trade-offs its usage
 involves.
 
 Problems
@@ -39,7 +39,7 @@ global API:
 .. code-block:: python
    :linenos:
 
-   from repoze.bfg.interfaces import ISettings
+   from pyramid.interfaces import ISettings
    from zope.component import getUtility
    settings = getUtility(ISettings)
 
@@ -78,7 +78,7 @@ That's sort of the best answer in this context (a more specific answer
 would require knowledge of internals).  Can there be more than one
 registry?  Yes.  So *which* registry does it find the registration in?
 Well, the "current" registry of course.  In terms of
-:mod:`repoze.bfg`, the current registry is a thread local variable.
+:mod:`pyramid`, the current registry is a thread local variable.
 Using an API that consults a thread local makes understanding how it
 works non-local.
 
@@ -91,7 +91,7 @@ nor was it performed imperatively.  This is extremely hard to
 comprehend.  Problem number six.
 
 Clearly there's some amount of cognitive load here that needs to be
-borne by a reader of code that extends the :mod:`repoze.bfg` framework
+borne by a reader of code that extends the :mod:`pyramid` framework
 due to its use of the ZCA, even if he or she is already an expert
 Python programmer and whom is an expert in the domain of web
 applications.  This is suboptimal.
@@ -99,15 +99,15 @@ applications.  This is suboptimal.
 Ameliorations
 +++++++++++++
 
-First, the primary amelioration: :mod:`repoze.bfg` *does not expect
+First, the primary amelioration: :mod:`pyramid` *does not expect
 application developers to understand ZCA concepts or any of its APIs*.
 If an *application* developer needs to understand a ZCA concept or API
-during the creation of a :mod:`repoze.bfg` application, we've failed
+during the creation of a :mod:`pyramid` application, we've failed
 on some axis.
 
 Instead, the framework hides the presence of the ZCA registry behind
 special-purpose API functions that *do* use ZCA APIs.  Take for
-example the ``repoze.bfg.security.authenticated_userid`` function,
+example the ``pyramid.security.authenticated_userid`` function,
 which returns the userid present in the current request or ``None`` if
 no userid is present in the current request.  The application
 developer calls it like so:
@@ -116,7 +116,7 @@ developer calls it like so:
 .. code-block:: python
    :linenos:
 
-   from repoze.bfg.security import authenticated_userid
+   from pyramid.security import authenticated_userid
    userid = authenticated_userid(request)
 
 He now has the current user id.
@@ -143,7 +143,7 @@ application developers.  Application developers should just never know
 about the ZCA API: they should call a Python function with some object
 germane to the domain as an argument, and it should returns a result.
 A corollary that follows is that any reader of an application that has
-been written using :mod:`repoze.bfg` needn't understand the ZCA API
+been written using :mod:`pyramid` needn't understand the ZCA API
 either.
 
 Hiding the ZCA API from application developers and code readers is a
@@ -151,24 +151,24 @@ form of enhancing "domain specificity".  No application developer
 wants to need to understand the minutiae of the mechanics of how a web
 framework does its thing.  People want to deal in concepts that are
 closer to the domain they're working in: for example, web developers
-want to know about *users*, not *utilities*.  :mod:`repoze.bfg` uses
+want to know about *users*, not *utilities*.  :mod:`pyramid` uses
 the ZCA as an implementation detail, not as a feature which is exposed
 to end users.
 
 However, unlike application developers, *framework developers*,
-including people who want to override :mod:`repoze.bfg` functionality
+including people who want to override :mod:`pyramid` functionality
 via preordained framework plugpoints like traversal or view lookup
 *must* understand the ZCA registry API.
 
-:mod:`repoze.bfg` framework developers were so concerned about
+:mod:`pyramid` framework developers were so concerned about
 conceptual load issues of the ZCA registry API for framework
 developers that a `replacement registry implementation
 <http://svn.repoze.org/repoze.component/trunk>`_ named
 :mod:`repoze.component` was actually developed.  Though this package
 has a registry implementation which is fully functional and
 well-tested, and its API is much nicer than the ZCA registry API, work
-on it was largely abandoned and it is not used in :mod:`repoze.bfg`.
-We continued to use a ZCA registry within :mod:`repoze.bfg` because it
+on it was largely abandoned and it is not used in :mod:`pyramid`.
+We continued to use a ZCA registry within :mod:`pyramid` because it
 ultimately proved a better fit.
 
 .. note:: We continued using ZCA registry rather than disusing it in
@@ -181,16 +181,16 @@ ultimately proved a better fit.
    reinventing the wheel.
 
 Making framework developers and extenders understand the ZCA registry
-API is a trade-off.  We (the :mod:`repoze.bfg` developers) like the
+API is a trade-off.  We (the :mod:`pyramid` developers) like the
 features that the ZCA registry gives us, and we have long-ago borne
 the weight of understanding what it does and how it works.  The
-authors of :mod:`repoze.bfg` understand the ZCA deeply and can read
+authors of :mod:`pyramid` understand the ZCA deeply and can read
 code that uses it as easily as any other code.
 
 But we recognize that developers who my want to extend the framework
 are not as comfortable with the ZCA registry API as the original
 developers are with it.  So, for the purposes of being kind to
-third-party :mod:`repoze.bfg` framework developers in, we've drawn
+third-party :mod:`pyramid` framework developers in, we've drawn
 some lines in the sand.
 
 #) In all "core" code, We've made use of ZCA global API functions such
@@ -200,25 +200,25 @@ some lines in the sand.
    .. code-block:: python
       :linenos:
 
-      from repoze.bfg.interfaces import IAuthenticationPolicy
+      from pyramid.interfaces import IAuthenticationPolicy
       from zope.component import getUtility
       policy = getUtility(IAuthenticationPolicy)
 
-   :mod:`repoze.bfg` code will usually do:
+   :mod:`pyramid` code will usually do:
 
    .. code-block:: python
       :linenos:
 
-      from repoze.bfg.interfaces import IAuthenticationPolicy
-      from repoze.bfg.threadlocal import get_current_registry
+      from pyramid.interfaces import IAuthenticationPolicy
+      from pyramid.threadlocal import get_current_registry
       registry = get_current_registry()
       policy = registry.getUtility(IAuthenticationPolicy)
 
    While the latter is more verbose, it also arguably makes it more
-   obvious what's going on.  All of the :mod:`repoze.bfg` core code uses
+   obvious what's going on.  All of the :mod:`pyramid` core code uses
    this pattern rather than the ZCA global API.
 
-#) We've turned the component registry used by :mod:`repoze.bfg` into
+#) We've turned the component registry used by :mod:`pyramid` into
    something that is accessible using the plain old dictionary API
    (like the :mod:`repoze.component` API).  For example, the snippet
    of code in the problem section above was:
@@ -226,7 +226,7 @@ some lines in the sand.
    .. code-block:: python
       :linenos:
 
-      from repoze.bfg.interfaces import ISettings
+      from pyramid.interfaces import ISettings
       from zope.component import getUtility
       settings = getUtility(ISettings)
 
@@ -235,7 +235,7 @@ some lines in the sand.
    .. code-block:: python
       :linenos:
 
-      from repoze.bfg.threadlocal import get_current_registry
+      from pyramid.threadlocal import get_current_registry
 
       registry = get_current_registry()
       settings = registry['settings']
@@ -258,7 +258,7 @@ some lines in the sand.
    attributes and the dictionary API.  Every Python programmer knows
    these things, even framework programmers.
 
-While :mod:`repoze.bfg` still uses some suboptimal unnamed utility
+While :mod:`pyramid` still uses some suboptimal unnamed utility
 registrations, future versions of it will where possible disuse these
 things in favor of straight dictionary assignments and lookups, as
 demonstrated above, to be kinder to new framework developers.  We'll
@@ -267,16 +267,16 @@ continue to seek ways to reduce framework developer cognitive load.
 Rationale
 +++++++++
 
-Here are the main rationales involved in the :mod:`repoze.bfg`
+Here are the main rationales involved in the :mod:`pyramid`
 decision to use the ZCA registry:
 
 - Pedigree.  A nontrivial part of the answer to this question is
-  "pedigree".  Much of the design of :mod:`repoze.bfg` is stolen
+  "pedigree".  Much of the design of :mod:`pyramid` is stolen
   directly from :term:`Zope`.  Zope uses the ZCA registry to do a
-  number of tricks.  :mod:`repoze.bfg` mimics these tricks, and,
+  number of tricks.  :mod:`pyramid` mimics these tricks, and,
   because the ZCA registry works well for that set of tricks,
-  :mod:`repoze.bfg` uses it for the same purposes.  For example, the
-  way that :mod:`repoze.bfg` maps a :term:`request` to a :term:`view
+  :mod:`pyramid` uses it for the same purposes.  For example, the
+  way that :mod:`pyramid` maps a :term:`request` to a :term:`view
   callable` is lifted almost entirely from Zope.  The ZCA registry
   plays an important role in the particulars of how this request to
   view mapping is done.
@@ -290,12 +290,12 @@ decision to use the ZCA registry:
   :term:`interface`.
 
 - Singularity.  There's only one "place" where "application
-  configuration" lives in a :mod:`repoze.bfg` application: in a
+  configuration" lives in a :mod:`pyramid` application: in a
   component registry.  The component registry answers questions made
   to it by the framework at runtime based on the configuration of *an
   application*.  Note: "an application" is not the same as "a
   process", multiple independently configured copies of the same
-  :mod:`repoze.bfg` application are capable of running in the same
+  :mod:`pyramid` application are capable of running in the same
   process space.
 
 - Composability.  A ZCA component registry can be populated
@@ -308,7 +308,7 @@ decision to use the ZCA registry:
   extensibility via a well-defined and widely understood plugin
   architecture.  As long as framework developers and extenders
   understand the ZCA registry, it's possible to extend
-  :mod:`repoze.bfg` almost arbitrarily.  For example, it's relatively
+  :mod:`pyramid` almost arbitrarily.  For example, it's relatively
   easy to build a ZCML directive that registers several views "all at
   once", allowing app developers to use that ZCML directive as a
   "macro" in code that they write.  This is somewhat of a
@@ -321,26 +321,26 @@ decision to use the ZCA registry:
   lookups in the code find our mock objects.
 
 - Speed.  The ZCA registry is very fast for a specific set of complex
-  lookup scenarios that :mod:`repoze.bfg` uses, having been optimized
+  lookup scenarios that :mod:`pyramid` uses, having been optimized
   through the years for just these purposes.  The ZCA registry
   contains optional C code for this purpose which demonstrably has no
   (or very few) bugs.
 
 - Ecosystem.  Many existing Zope packages can be used in
-  :mod:`repoze.bfg` with few (or no) changes due to our use of the ZCA
+  :mod:`pyramid` with few (or no) changes due to our use of the ZCA
   registry and :term:`ZCML`.
 
 Conclusion
 ++++++++++
 
-If you only *develop applications* using :mod:`repoze.bfg`, there's
+If you only *develop applications* using :mod:`pyramid`, there's
 not much to complain about here.  You just should never need to
 understand the ZCA registry or even know about its presence: use
-documented :mod:`repoze.bfg` APIs instead.  However, you may be an
+documented :mod:`pyramid` APIs instead.  However, you may be an
 application developer who doesn't read API documentation because it's
 unmanly. Instead you read the raw source code, and because you haven't
 read the documentation, you don't know what functions, classes, and
-methods even *form* the :mod:`repoze.bfg` API.  As a result, you've
+methods even *form* the :mod:`pyramid` API.  As a result, you've
 now written code that uses internals and you've pained yourself into a
 conceptual corner as a result of needing to wrestle with some
 ZCA-using implementation detail.  If this is you, it's extremely hard
@@ -348,9 +348,9 @@ to have a lot of sympathy for you.  You'll either need to get familiar
 with how we're using the ZCA registry or you'll need to use only the
 documented APIs; that's why we document them as APIs.
 
-If you *extend* or *develop* :mod:`repoze.bfg` (create new ZCML
+If you *extend* or *develop* :mod:`pyramid` (create new ZCML
 directives, use some of the more obscure "ZCML hooks" as described in
-:ref:`hooks_chapter`, or work on the :mod:`repoze.bfg` core code), you
+:ref:`hooks_chapter`, or work on the :mod:`pyramid` core code), you
 will be faced with needing to understand at least some ZCA concepts.
 The ZCA registry API is quirky: we've tried to make it at least
 slightly nicer by disusing it for common registrations and lookups
@@ -359,15 +359,15 @@ will be forever.  We know it's quirky, but it's also useful and
 fundamentally understandable if you take the time to do some reading
 about it.
 
-BFG Uses Interfaces Too Liberally
----------------------------------
+Pyramid Uses Interfaces Too Liberally
+-------------------------------------
 
 In this `TOPP Engineering blog entry
 <http://www.coactivate.org/projects/topp-engineering/blog/2008/10/20/what-bothers-me-about-the-component-architecture/>`_,
-Ian Bicking asserts that the way :mod:`repoze.bfg` uses a Zope
+Ian Bicking asserts that the way :mod:`pyramid` uses a Zope
 interface to represent an HTTP request method adds too much
 indirection for not enough gain.  We agreed in general, and for this
-reason, :mod:`repoze.bfg` version 1.1 added :term:`view predicate` and
+reason, :mod:`pyramid` version 1.1 added :term:`view predicate` and
 :term:`route predicate` modifiers to view configuration.  Predicates
 are request-specific (or :term:`context` -specific) matching narrowers
 which don't use interfaces.  Instead, each predicate uses a
@@ -380,7 +380,7 @@ decorator which mentioned the ``request_method`` predicate:
 .. code-block:: python
    :linenos:
 
-   from repoze.bfg.view import bfg_view
+   from pyramid.view import bfg_view
    @bfg_view(name='post_view', request_method='POST', renderer='json')
    def post_view(request):
        return 'POSTed'
@@ -392,7 +392,7 @@ response:
 .. code-block:: python
    :linenos:
 
-   from repoze.bfg.view import bfg_view
+   from pyramid.view import bfg_view
    @bfg_view(name='post_view', request_method='POST', accept='application/json',
              renderer='json')
    def post_view(request):
@@ -417,7 +417,7 @@ acommodate this by allowing people to define "custom" view predicates:
 .. code-block:: python
    :linenos:
 
-   from repoze.bfg.view import bfg_view
+   from pyramid.view import bfg_view
    from webob import Response
 
    def subpath(context, request):
@@ -432,27 +432,27 @@ The above view will only match when the first element of the request's
 
 .. _zcml_encouragement:
 
-BFG "Encourages Use of ZCML"
-----------------------------
+Pyramid "Encourages Use of ZCML"
+--------------------------------
 
 :term:`ZCML` is a configuration language that can be used to configure
 the :term:`Zope Component Architecture` registry that
-:mod:`repoze.bfg` uses as its application configuration.
+:mod:`pyramid` uses as its application configuration.
 
 Quick answer: well, it doesn't *really* encourage the use of ZCML.  In
-:mod:`repoze.bfg` 1.0 and 1.1, application developers could use
+:mod:`pyramid` 1.0 and 1.1, application developers could use
 decorators for the most common form of configuration.  But, yes, a
-:mod:`repoze.bfg` 1.0/1.1 application needed to possess a ZCML file
+:mod:`pyramid` 1.0/1.1 application needed to possess a ZCML file
 for it to begin executing successfully even if its only contents were
 a ``<scan>`` directive that kicked off a scan to find decorated view
 callables.
 
 In the interest of completeness and in the spirit of providing a
-lowest common denominator, :mod:`repoze.bfg` 1.2 includes a completely
+lowest common denominator, :mod:`pyramid` 1.2 includes a completely
 imperative mode for all configuration.  You will be able to make
 "single file" apps in this mode, which should help people who need to
 see everything done completely imperatively.  For example, the very
-most basic :mod:`repoze.bfg` "helloworld" program has become
+most basic :mod:`pyramid` "helloworld" program has become
 something like:
 
 .. code-block:: python
@@ -460,7 +460,7 @@ something like:
 
    from webob import Response
    from paste.httpserver import serve
-   from repoze.bfg.configuration import Configurator
+   from pyramid.configuration import Configurator
 
    def hello_world(request):
        return Response('Hello world!')
@@ -477,11 +477,11 @@ In this mode, no ZCML is required for end users.  Hopefully this mode
 will allow people who are used to doing everything imperatively feel
 more comfortable.
 
-BFG Uses ZCML; ZCML is XML and I Don't Like XML
------------------------------------------------
+Pyramid Uses ZCML; ZCML is XML and I Don't Like XML
+---------------------------------------------------
 
 :term:`ZCML` is a configuration language in the XML syntax.  Due to
-the "imperative configuration" feature (new in :mod:`repoze.bfg` 1.2),
+the "imperative configuration" feature (new in :mod:`pyramid` 1.2),
 you don't need to use ZCML at all if you start a project from scratch.
 But if you really do want to perform declarative configuration,
 perhaps because you want to build an extensible application, you will
@@ -501,20 +501,20 @@ called *declarations*.  For an example:
 
 This declaration associates a :term:`view` with a route pattern. 
 
-All :mod:`repoze.bfg` declarations are singleton tags, unlike many
+All :mod:`pyramid` declarations are singleton tags, unlike many
 other XML configuration systems.  No XML *values* in ZCML are
 meaningful; it's always just XML tags and attributes.  So in the very
 common case it's not really very much different than an otherwise
 "flat" configuration format like ``.ini``, except a developer can
 *create* a directive that requires nesting (none of these exist in
-:mod:`repoze.bfg` itself), and multiple "sections" can exist with the
+:mod:`pyramid` itself), and multiple "sections" can exist with the
 same "name" (e.g. two ``<route>`` declarations) must be able to exist
 simultaneously.
 
 You might think some other configuration file format would be better.
 But all configuration formats suck in one way or another.  I
 personally don't think any of our lives would be markedly better if
-the declarative configuration format used by :mod:`repoze.bfg` were
+the declarative configuration format used by :mod:`pyramid` were
 YAML, JSON, or INI.  It's all just plumbing that you mostly cut and
 paste once you've progressed 30 minutes into your first project.
 Folks who tend to agitate for another configuration file format are
@@ -522,13 +522,13 @@ folks that haven't yet spent that 30 minutes.
 
 .. _model_traversal_confusion:
 
-BFG Uses "Model" To Represent A Node In The Graph of Objects Traversed
-----------------------------------------------------------------------
+Pyramid Uses "Model" To Represent A Node In The Graph of Objects Traversed
+--------------------------------------------------------------------------
 
-The :mod:`repoze.bfg` documentation refers to the graph being
+The :mod:`pyramid` documentation refers to the graph being
 traversed when :term:`traversal` is used as a "model graph".  Some of
-the :mod:`repoze.bfg` APIs also use the word "model" in them when
-referring to a node in this graph (e.g. ``repoze.bfg.url.model_url``).
+the :mod:`pyramid` APIs also use the word "model" in them when
+referring to a node in this graph (e.g. ``pyramid.url.model_url``).
 
 A terminology overlap confuses people who write applications that
 always use ORM packages such as SQLAlchemy, which has a different
@@ -539,62 +539,30 @@ Often model objects must be explicitly manufactured by an ORM as a
 result of some query performed by a :term:`view`.  As a result, it can
 be unnatural to think of the nodes traversed as "model" objects if you
 develop your application using traversal and a relational database.
-When you develop such applications, the things that :mod:`repoze.bfg`
+When you develop such applications, the things that :mod:`pyramid`
 refers to as "models" in such an application may just be stand-ins
 that perform a query and generate some wrapper *for* an ORM "model"
 (or set of ORM models).  The graph *might* be composed completely of
 "model" objects (as defined by the ORM) but it also might not be.
 
 The naming impedance mismatch between the way the term "model" is used
-to refer to a node in a graph in :mod:`repoze.bfg` and the way the
+to refer to a node in a graph in :mod:`pyramid` and the way the
 term "model" is used by packages like SQLAlchemy is unfortunate.  For
 the purpose of avoiding confusion, if we had it to do all over again,
-we might refer to the graph that :mod:`repoze.bfg` traverses a "node
+we might refer to the graph that :mod:`pyramid` traverses a "node
 graph" or "object graph" rather than a "model graph", but since we've
 baked the name into the API, it's a little late.  Sorry.
 
-In our defense, many :mod:`repoze.bfg` applications (especially ones
+In our defense, many :mod:`pyramid` applications (especially ones
 which use :term:`ZODB`) do indeed traverse a graph full of model
 nodes.  Each node in the graph is a separate persistent object that is
 stored within a database.  This was the use case considered when
 coming up with the "model" terminology.
 
-I Can't Figure Out How "BFG" Is Related to "Repoze"
----------------------------------------------------
+Pyramid Does Traversal, And I Don't Like Traversal
+--------------------------------------------------
 
-When the `Repoze project <http://repoze.org>`_ was first started,
-:mod:`repoze.bfg` did not exist.  The `website <http://repoze.org>`_
-for the project had (and still has, of this writing) a tag line of
-"Plumbing Zope into the WSGI Pipeline", and contained descriptions of
-:term:`WSGI` middleware that were inspired by Zope features, and
-applications that help :term:`Zope` to run within a WSGI environment.
-The original intent was to create a "namespace" of packages
-("repoze.*") that contained software that formed a decomposition of
-Zope features into more WSGI-friendly components.  It was never the
-intention of the Repoze project to actually create another web
-framework.
-
-However, as time progressed, the folks who ran the Repoze project
-decided to create :mod:`repoze.bfg`, which *is* a web framework.  Due
-to an early naming mistake, the software composing the framework was
-named :mod:`repoze.bfg`.  This mistake was not corrected before the
-software garnered a significant user base, and in the interest of
-backwards compatibility, most likely never will be.  While
-:mod:`repoze.bfg` uses Zope technology, it is otherwise unrelated to
-the original goals of "Repoze" as stated on the repoze.org website.
-If we had it to do all over again, the :mod:`repoze.bfg` package would
-be named simply :mod:`bfg`.  But we don't have it to do all over
-again.
-
-At this point, therefore, the name "Repoze" should be considered
-basically just a "brand".  Its presence in the name of a package means
-nothing except that it has an origin as a piece of software developed
-by a member of the Repoze community.
-
-BFG Does Traversal, And I Don't Like Traversal
-----------------------------------------------
-
-In :mod:`repoze.bfg`, :term:`traversal` is the act of resolving a URL
+In :mod:`pyramid`, :term:`traversal` is the act of resolving a URL
 path to a :term:`model` object in an object graph.  Some people are
 uncomfortable with this notion, and believe it is wrong.
 
@@ -624,15 +592,15 @@ excellent way to model this, even if the backend is a relational
 database.  In this situation, the graph being traversed is actually
 less a "model graph" than a site structure.
 
-But the point is ultimately moot.  If you use :mod:`repoze.bfg`, and
+But the point is ultimately moot.  If you use :mod:`pyramid`, and
 you don't want to model your application in terms of traversal, you
 needn't use it at all.  Instead, use :term:`URL dispatch` to map URL
 paths to views.
 
-BFG Does URL Dispatch, And I Don't Like URL Dispatch
-----------------------------------------------------
+Pyramid Does URL Dispatch, And I Don't Like URL Dispatch
+--------------------------------------------------------
 
-In :mod:`repoze.bfg`, :term:`url dispatch` is the act of resolving a
+In :mod:`pyramid`, :term:`url dispatch` is the act of resolving a
 URL path to a :term:`view` callable by performing pattern matching
 against some set of ordered route definitions.  The route definitions
 are examined in order: the first pattern which matches is used to
@@ -650,7 +618,7 @@ object graph), and traversal is required to reach this code.
 
 I'll argue that URL dispatch is ultimately useful, even if you want to
 use traversal as well.  You can actually *combine* URL dispatch and
-traversal in :mod:`repoze.bfg` (see :ref:`hybrid_chapter`).  One
+traversal in :mod:`pyramid` (see :ref:`hybrid_chapter`).  One
 example of such a usage: if you want to emulate something like Zope
 2's "Zope Management Interface" UI on top of your object graph (or any
 administrative interface), you can register a route like ``<route
@@ -671,16 +639,16 @@ one-off associations between views and URL paths.  Sometimes it's just
 pointless to add a node to the object graph that effectively
 represents the entry point for some bit of code.  You can just use a
 route and be done with it.  If a route matches, a view associated with
-the route will be called; if no route matches, :mod:`repoze.bfg` falls
+the route will be called; if no route matches, :mod:`pyramid` falls
 back to using traversal.
 
-But the point is ultimately moot.  If you use :mod:`repoze.bfg`, and
+But the point is ultimately moot.  If you use :mod:`pyramid`, and
 you really don't want to use URL dispatch, you needn't use it at all.
 Instead, use :term:`traversal` exclusively to map URL paths to views,
 just like you do in :term:`Zope`.
 
-BFG Views Do Not Accept Arbitrary Keyword Arguments
----------------------------------------------------
+Pyramid Views Do Not Accept Arbitrary Keyword Arguments
+-------------------------------------------------------
 
 Many web frameworks (Zope, TurboGears, Pylons, Django) allow for their
 variant of a :term:`view callable` to accept arbitrary keyword or
@@ -716,11 +684,11 @@ arguments in the request, and the method is called (if possible) with
 its argument list filled with values mentioned therein.  TurboGears
 and Pylons operate similarly.
 
-:mod:`repoze.bfg` has neither of these features.  :mod:`repoze.bfg`
+:mod:`pyramid` has neither of these features.  :mod:`pyramid`
 view callables always accept only ``context`` and ``request`` (or just
 ``request``), and no other arguments.  The rationale: this argument
 specification matching done aggressively can be costly, and
-:mod:`repoze.bfg` has performance as one of its main goals, so we've
+:mod:`pyramid` has performance as one of its main goals, so we've
 decided to make people obtain information by interrogating the request
 object for it in the view body instead of providing magic to do
 unpacking into the view argument list.  The feature itself also just
@@ -739,15 +707,15 @@ A similar feature could be implemented to provide the Django-like
 behavior as a decorator by wrapping the view with a decorator that
 looks in ``request.matchdict``.
 
-It's possible at some point that :mod:`repoze.bfg` will grow some form
+It's possible at some point that :mod:`pyramid` will grow some form
 of argument matching feature (it would be simple to make it an
 always-on optional feature that has no cost unless you actually use
 it) for, but currently it has none.
 
-BFG Provides Too Few "Rails"
-----------------------------
+Pyramid Provides Too Few "Rails"
+--------------------------------
 
-By design, :mod:`repoze.bfg` is not a particularly "opinionated" web
+By design, :mod:`pyramid` is not a particularly "opinionated" web
 framework.  It has a relatively parsimonious feature set.  It contains
 no built in ORM nor any particular database bindings.  It contains no
 form generation framework.  It does not contain a sessioning library.
@@ -755,14 +723,14 @@ It has no administrative web user interface.  It has no built in text
 indexing.  It does not dictate how you arrange your code.
 
 Such opinionated functionality exists in applications and frameworks
-built *on top* of :mod:`repoze.bfg`.  It's intended that higher-level
-systems emerge built using :mod:`repoze.bfg` as a base.  See also
+built *on top* of :mod:`pyramid`.  It's intended that higher-level
+systems emerge built using :mod:`pyramid` as a base.  See also
 :ref:`apps_are_extensible`.
 
-BFG Provides Too Many "Rails"
------------------------------
+Pyramid Provides Too Many "Rails"
+---------------------------------
 
-:mod:`repoze.bfg` provides some features that other web frameworks do
+:mod:`pyramid` provides some features that other web frameworks do
 not.  Most notably it has machinery which resolves a URL first to a
 :term:`context` before calling a view (which has the capability to
 accept the context in its argument list), and a declarative
@@ -779,20 +747,20 @@ declarations as :term:`ACL` objects.
 Having context-sensitive declarative security for individual objects
 in the object graph is simply required for this class of application.
 Other frameworks save for Zope just do not have this feature.  This is
-one of the primary reasons that :mod:`repoze.bfg` was actually
+one of the primary reasons that :mod:`pyramid` was actually
 written.
 
 If you don't like this, it doesn't mean you can't use
-:mod:`repoze.bfg`.  Just ignore this feature and avoid configuring an
+:mod:`pyramid`.  Just ignore this feature and avoid configuring an
 authorization or authentication policy and using ACLs.  You can build
-"Pylons-style" applications using :mod:`repoze.bfg` that use their own
+"Pylons-style" applications using :mod:`pyramid` that use their own
 security model via decorators or plain-old-imperative logic in view
 code.
 
-BFG Is Too Big
---------------
+Pyramid Is Too Big
+------------------
 
-"The :mod:`repoze.bfg` compressed tarball is 1MB.  It must be
+"The :mod:`pyramid` compressed tarball is 1MB.  It must be
 enormous!"
 
 No.  We just ship it with test code and helper templates.  Here's a
@@ -814,7 +782,7 @@ repoze/bfg (except for ``repoze/bfg/tests and repoze/bfg/paster_templates``)
 
   316K
 
-The actual :mod:`repoze.bfg` runtime code is about 10% of the total
+The actual :mod:`pyramid` runtime code is about 10% of the total
 size of the tarball omitting docs, helper templates used for package
 generation, and test code.  Of the approximately 13K lines of Python
 code in the package, the code that actually has a chance of executing
@@ -823,17 +791,17 @@ files, accounts for approximately 3K lines of Python code.  This is
 comparable to Pylons, which ships with a little over 2K lines of
 Python code, excluding tests.
 
-BFG Has Too Many Dependencies
------------------------------
+Pyramid Has Too Many Dependencies
+---------------------------------
 
 This is true.  At the time of this writing, the total number of Python
-package distributions that :mod:`repoze.bfg` depends upon transitively
+package distributions that :mod:`pyramid` depends upon transitively
 is 14 if you use Python 2.6 or 2.7, or 16 if you use Python 2.4 or
 2.5.  This is a lot more than zero package distribution dependencies:
 a metric which various Python microframeworks and Django boast.
 
 The :mod:`zope.component` and :mod:`zope.configuration` packages on
-which :mod:`repoze.bfg` depends have transitive dependencies on
+which :mod:`pyramid` depends have transitive dependencies on
 several other packages (:mod:`zope.schema`, :mod:`zope.i18n`,
 :mod:`zope.event`, :mod:`zope.interface`, :mod:`zope.deprecation`,
 :mod:`zope.i18nmessageid`).  We've been working with the Zope
@@ -842,16 +810,16 @@ We'd prefer that these packages have fewer packages as transitive
 dependencies, and that much of the functionality of these packages was
 moved into a smaller *number* of packages.
 
-:mod:`repoze.bfg` also has its own direct dependencies, such as
+:mod:`pyramid` also has its own direct dependencies, such as
 :term:`Paste`, :term:`Chameleon`, and :term:`WebOb`, and some of these
 in turn have their own transitive dependencies.
 
-It should be noted that :mod:`repoze.bfg` is positively lithe compared
+It should be noted that :mod:`pyramid` is positively lithe compared
 to :term:`Grok`, a different Zope-based framework.  As of this
 writing, in its default configuration, Grok has 126 package
 distribution dependencies. The number of dependencies required by
-:mod:`repoze.bfg` is many times fewer than Grok (or Zope itself, upon
-which Grok is based).  :mod:`repoze.bfg` has a number of package
+:mod:`pyramid` is many times fewer than Grok (or Zope itself, upon
+which Grok is based).  :mod:`pyramid` has a number of package
 distribution dependencies comparable to similarly-targeted frameworks
 such as Pylons.
 
@@ -859,31 +827,31 @@ We try not to reinvent too many wheels (at least the ones that don't
 need reinventing), and this comes at the cost of some number of
 dependencies.  However, "number of package distributions" is just not
 a terribly great metric to measure complexity.  For example, the
-:mod:`zope.event` distribution on which :mod:`repoze.bfg` depends has
+:mod:`zope.event` distribution on which :mod:`pyramid` depends has
 a grand total of four lines of runtime code.  As noted above, we're
 continually trying to agitate for a collapsing of these sorts of
 packages into fewer distribution files.
 
-BFG "Cheats" To Obtain Speed
-----------------------------
+Pyramid "Cheats" To Obtain Speed
+--------------------------------
 
 Complaints have been lodged by other web framework authors at various
-times that :mod:`repoze.bfg` "cheats" to gain performance.  One
+times that :mod:`pyramid` "cheats" to gain performance.  One
 claimed cheating mechanism is our use (transitively) of the C
 extensions provided by :mod:`zope.interface` to do fast lookups.
 Another claimed cheating mechanism is the religious avoidance of
 extraneous function calls.
 
 If there's such a thing as cheating to get better performance, we want
-to cheat as much as possible.  We optimize :mod:`repoze.bfg`
+to cheat as much as possible.  We optimize :mod:`pyramid`
 aggressively.  This comes at a cost: the core code has sections that
 could be expressed more readably.  As an amelioration, we've commented
 these sections liberally.
 
-BFG Gets Its Terminology Wrong ("MVC")
---------------------------------------
+Pyramid Gets Its Terminology Wrong ("MVC")
+------------------------------------------
 
-"I'm a MVC web framework user, and I'm confused.  :mod:`repoze.bfg`
+"I'm a MVC web framework user, and I'm confused.  :mod:`pyramid`
 calls the controller a view!  And it doesn't have any controllers."
 
 People very much want to give web applications the same properties as
@@ -949,14 +917,14 @@ reasonable model, given the current constraints of the web.
 
 .. _apps_are_extensible:
 
-BFG Applications are Extensible; I Don't Believe In Application Extensibility
------------------------------------------------------------------------------
+Pyramid Applications are Extensible; I Don't Believe In Application Extensibility
+---------------------------------------------------------------------------------
 
-Any :mod:`repoze.bfg` application written obeying certain constraints
-is *extensible*. This feature is discussed in the :mod:`repoze.bfg`
+Any :mod:`pyramid` application written obeying certain constraints
+is *extensible*. This feature is discussed in the :mod:`pyramid`
 documentation chapter named :ref:`extending_chapter`.  It is made
 possible by the use of the :term:`Zope Component Architecture` and
-:term:`ZCML` within :mod:`repoze.bfg`.
+:term:`ZCML` within :mod:`pyramid`.
 
 "Extensible", in this context, means:
 
@@ -998,7 +966,7 @@ lifetime of a deployment can be difficult and time consuming, and it's
 often useful to be able to modify an application for a particular
 deployment in a less invasive way.
 
-If you don't want to think about :mod:`repoze.bfg` application
+If you don't want to think about :mod:`pyramid` application
 extensibility at all, you needn't.  You can ignore extensibility
 entirely.  However, if you follow the set of rules defined in
 :ref:`extending_chapter`, you don't need to *make* your application
@@ -1043,23 +1011,23 @@ worth, be contained in one, canonical, well-defined place.
 
 Branching an application and continually merging in order to get new
 features and bugfixes is clearly useful.  You can do that with a
-:mod:`repoze.bfg` application just as usefully as you can do it with
+:mod:`pyramid` application just as usefully as you can do it with
 any application.  But deployment of an application written in
-:mod:`repoze.bfg` makes it possible to avoid the need for this even if
+:mod:`pyramid` makes it possible to avoid the need for this even if
 the application doesn't define any plugpoints ahead of time.  It's
 possible that promoters of competing web frameworks dismiss this
 feature in favor of branching and merging because applications written
 in their framework of choice aren't extensible out of the box in a
 comparably fundamental way.
 
-While :mod:`repoze.bfg` application are fundamentally extensible even
+While :mod:`pyramid` application are fundamentally extensible even
 if you don't write them with specific extensibility in mind, if you're
 moderately adventurous, you can also take it a step further.  If you
 learn more about the :term:`Zope Component Architecture`, you can
 optionally use it to expose other more domain-specific configuration
 plugpoints while developing an application.  The plugpoints you expose
 needn't be as coarse as the ones provided automatically by
-:mod:`repoze.bfg` itself.  For example, you might compose your own
+:mod:`pyramid` itself.  For example, you might compose your own
 :term:`ZCML` directive that configures a set of views for a prebaked
 purpose (e.g. ``restview`` or somesuch) , allowing other people to
 refer to that directive when they make declarations in the
@@ -1069,85 +1037,22 @@ plugpoints for its deployers will need to understand the ZCA or he
 will need to develop his own similar extensibility system.
 
 Ultimately, any argument about whether the extensibility features lent
-to applications by :mod:`repoze.bfg` are "good" or "bad" is somewhat
+to applications by :mod:`pyramid` are "good" or "bad" is somewhat
 pointless. You needn't take advantage of the extensibility features
-provided by a particular :mod:`repoze.bfg` application in order to
+provided by a particular :mod:`pyramid` application in order to
 affect a modification for a particular set of its deployments.  You
 can ignore the application's extensibility plugpoints entirely, and
 instead use version control branching and merging to manage
 application deployment modifications instead, as if you were deploying
 an application written using any other web framework.
 
-The Name BFG Is Not Safe For Work
----------------------------------
-
-"Big Friendly Giant" is not safe for your work?  Where do you work? ;-)
-
-The BFG API Isn't "Flat"
-------------------------
-
-The :mod:`repoze.bfg` API is organized in such a way that API imports
-must come from submodules of the ``repoze.bfg`` namespace.  For
-instance:
-
-.. code-block:: python
-   :linenos:
-
-   from repoze.bfg.settings import get_settings
-   from repoze.bfg.url import model_url
-
-Some folks understandably don't want to think about the submodule
-organization, and would rather be able to do:
-
-.. ignore-next-block
-.. code-block:: python
-   :linenos:
-
-   from repoze.bfg import get_settings
-   from repoze.bfg import model_url
-
-This would indeed be nice.  However, the ``repoze.bfg`` Python package
-is a `namespace package <http://www.python.org/dev/peps/pep-0382/>`_.
-The ``__init__.py`` of a namespace package cannot contain any
-meaningful code such as imports from submodules which would let us
-form a flatter API.  Sorry.
-
-Though it makes the API slightly "thinkier", making the ``repoze.bfg``
-package into a namespace package was an early design decision, which
-we believe has paid off.  The primary goal is to make it possible to
-move features *out* of the core ``repoze.bfg`` distribution and into
-add-on distributions without breaking existing imports.  The
-``repoze.bfg.lxml`` distribution is an example of such a package: this
-functionality used to live in the core distribution, but we later
-decided that a core dependency on ``lxml`` was unacceptable.  Because
-``repoze.bfg`` is a namespace package, we were able to remove the
-``repoze.bfg.lxml`` module from the core and create a distribution
-named ``repoze.bfg.lxml`` which contains an eponymous package.  We
-were then able, via our changelog, to inform people that might have
-been depending on the feature that although it no longer shipped in
-the core distribution, they could get it back *without changing any
-code* by adding an ``install_requires`` line to their application
-package's ``setup.py``.
-
-Often new :mod:`repoze.bfg` features are released as add-on packages
-in the ``repoze.bfg`` namespace.  Because ``repoze.bfg`` is a
-namespace package, if we want to move one of these features *in* to
-the core distribition at some point, we can do so without breaking
-code which imports from the older package namespace.  This is
-currently less useful than the ability to move features *out* of the
-core distribution, as :mod:`setuptools` does not yet have any concept
-of "obsoletes" metadata which we could add to the core distribution.
-This means it's not yet possible to declaratively deprecate the older
-non-core package in the eyes of tools like ``easy_install``, ``pip``
-and ``buildout``.
-
-Zope 3 Enforces "TTW" Authorization Checks By Default; BFG Does Not
--------------------------------------------------------------------
+Zope 3 Enforces "TTW" Authorization Checks By Default; Pyramid Does Not
+-----------------------------------------------------------------------
 
 Challenge
 +++++++++
 
-:mod:`repoze.bfg` performs automatic authorization checks only at
+:mod:`pyramid` performs automatic authorization checks only at
 :term:`view` execution time.  Zope 3 wraps context objects with a
 `security proxy <http://wiki.zope.org/zope3/WhatAreSecurityProxies>`,
 which causes Zope 3 to do also security checks during attribute
@@ -1160,17 +1065,17 @@ access.  I like this, because it means:
    respect to a context object.
 
 #) I want to also expose my model via a REST API using Twisted Web. If
-   If BFG perform authorization based on attribute access via Zope3's
+   If Pyramid performed authorization based on attribute access via Zope3's
    security proies, I could enforce my authorization policy in both
-   :mod:`repoze.bfg` and in the Twisted-based system the same way.
+   :mod:`pyramid` and in the Twisted-based system the same way.
 
 Defense
 +++++++
 
-:mod:`repoze.bfg` was developed by folks familiar with Zope 2, which
+:mod:`pyramid` was developed by folks familiar with Zope 2, which
 has a "through the web" security model.  This "TTW" security model was
 the precursor to Zope 3's security proxies.  Over time, as the
-:mod:`repoze.bfg` developers (working in Zope 2) created such sites,
+:mod:`pyramid` developers (working in Zope 2) created such sites,
 we found authorization checks during code interpretation extremely
 useful in a minority of projects.  But much of the time, TTW
 authorization checks usually slowed down the development velocity of
@@ -1191,7 +1096,7 @@ notwithstanding, given that Zope 3 security proxies are "viral" by
 nature, the only requirement to use one is to make sure you wrap a
 single object in a security proxy and make sure to access that object
 normally when you want proxy security checks to happen.  It is
-possible to override the :mod:`repoze.bfg` "traverser" for a given
+possible to override the :mod:`pyramid` "traverser" for a given
 application (see :ref:`changing_the_traverser`).  To get Zope3-like
 behavior, it is possible to plug in a different traverser which
 returns Zope3-security-proxy-wrapped objects for each traversed object
@@ -1210,24 +1115,24 @@ two that are becoming popular.  `Bobo <http://bobo.digicool.com/>`_
 doesn't describe itself as a microframework, but its intended userbase
 is much the same.  Many others exist.  We've actually even (only as a
 teaching tool, not as any sort of official project) `created one using
-BFG <http://bfg.repoze.org/videos#groundhog1>`_. Microframeworks are
-small frameworks with one common feature: each allows its users to
-create a fully functional application that lives in a single Python
-file.
-
-Some developers and microframework authors point out that BFG's "hello
-world" single-file program is longer (by about five lines) than the
-equivalent program in their favorite microframework.  Guilty as
-charged; in a contest of "whose is shortest", BFG indeed loses.
-
-This loss isn't for lack of trying. BFG aims to be useful in the same
-circumstance in which microframeworks claim dominance: single-file
-applications.  But BFG doesn't sacrifice its ability to credibly
-support larger applications in order to achieve hello-world LoC parity
-with the current crop of microframeworks.  BFG's design instead tries
-to avoid some common pitfalls associated with naive declarative
-configuration schemes.  The subsections which follow explain the
-rationale.
+BFG <http://bfg.repoze.org/videos#groundhog1>`_ (the precursor to
+Pyramid). Microframeworks are small frameworks with one common
+feature: each allows its users to create a fully functional
+application that lives in a single Python file.
+
+Some developers and microframework authors point out that Pyramid's
+"hello world" single-file program is longer (by about five lines) than
+the equivalent program in their favorite microframework.  Guilty as
+charged; in a contest of "whose is shortest", Pyramid indeed loses.
+
+This loss isn't for lack of trying. Pyramid aims to be useful in the
+same circumstance in which microframeworks claim dominance:
+single-file applications.  But Pyramid doesn't sacrifice its ability
+to credibly support larger applications in order to achieve
+hello-world LoC parity with the current crop of microframeworks.
+Pyramid's design instead tries to avoid some common pitfalls
+associated with naive declarative configuration schemes.  The
+subsections which follow explain the rationale.
 
 .. _you_dont_own_modulescope:
 
@@ -1459,29 +1364,29 @@ almost-all-imperative:
         gh.add_route(foo, '/foo/')
         gh.run()
 
-This is a generic mode of operation that is encouraged in the BFG
+This is a generic mode of operation that is encouraged in the Pyramid
 documentation. Some existing microframeworks (Flask, in particular)
-allow for it as well.  None (other than BFG) *encourage* it.  If you
-never expect your application to grow beyond two or three or four or
-ten modules, it probably doesn't matter very much which mode you use.
-If your application grows large, however, imperative configuration can
-provide better predictability.
+allow for it as well.  None (other than Pyramid) *encourage* it.  If
+you never expect your application to grow beyond two or three or four
+or ten modules, it probably doesn't matter very much which mode you
+use.  If your application grows large, however, imperative
+configuration can provide better predictability.
 
 .. note::
 
-  Astute readers may notice that BFG has configuration decorators too.
-  Aha!  Don't these decorators have the same problems?  No.  These
-  decorators do not populate an external Python module when they are
-  executed.  They only mutate the functions (and classes and methods)
-  they're attached to.  These mutations must later be found during a
-  "scan" process that has a predictable and structured import phase.
-  Module-localized mutation is actually the best-case circumstance for
-  double-imports; if a module only mutates itself and its contents at
-  import time, if it is imported twice, that's OK, because each
-  decorator invocation will always be mutating an independent copy of
-  the object its attached to, not a shared resource like a registry in
-  another module.  This has the effect that double-registrations will
-  never be performed.
+  Astute readers may notice that Pyramid has configuration decorators
+  too.  Aha!  Don't these decorators have the same problems?  No.
+  These decorators do not populate an external Python module when they
+  are executed.  They only mutate the functions (and classes and
+  methods) they're attached to.  These mutations must later be found
+  during a "scan" process that has a predictable and structured import
+  phase.  Module-localized mutation is actually the best-case
+  circumstance for double-imports; if a module only mutates itself and
+  its contents at import time, if it is imported twice, that's OK,
+  because each decorator invocation will always be mutating an
+  independent copy of the object its attached to, not a shared
+  resource like a registry in another module.  This has the effect
+  that double-registrations will never be performed.
 
 Routes (Usually) Need Relative Ordering
 +++++++++++++++++++++++++++++++++++++++
@@ -1637,15 +1542,16 @@ myframework.threadlocals import get_request; request = get_request()``
 even though the latter is more explicit.
 
 It would be *most* explicit if the microframeworks did not use thread
-local variables at all.  BFG view functions are passed a request
-object; many of BFG's APIs require that an explicit request object be
-passed to them.  It is *possible* to retrieve the current BFG request
-as a threadlocal variable but it is a "in case of emergency, break
-glass" type of activity.  This explicitness makes BFG view functions
-more easily unit testable, as you don't need to rely on the framework
-to manufacture suitable "dummy" request (and other similarly-scoped)
-objects during test setup.  It also makes them more likely to work on
-arbitrary systems, such as async servers that do no monkeypatching.
+local variables at all.  Pyramid view functions are passed a request
+object; many of Pyramid's APIs require that an explicit request object
+be passed to them.  It is *possible* to retrieve the current Pyramid
+request as a threadlocal variable but it is a "in case of emergency,
+break glass" type of activity.  This explicitness makes Pyramid view
+functions more easily unit testable, as you don't need to rely on the
+framework to manufacture suitable "dummy" request (and other
+similarly-scoped) objects during test setup.  It also makes them more
+likely to work on arbitrary systems, such as async servers that do no
+monkeypatching.
 
 Explicitly WSGI
 +++++++++++++++
@@ -1653,10 +1559,10 @@ Explicitly WSGI
 Some microframeworks offer a ``run()`` method of an application object
 that executes a default server configuration for easy execution.
 
-BFG doesn't currently try to hide the fact that its router is a WSGI
-application behind a convenience ``run()`` API.  It just tells people
-to import a WSGI server and use it to serve up their BFG application
-as per the documentation of that WSGI server.
+Pyramid doesn't currently try to hide the fact that its router is a
+WSGI application behind a convenience ``run()`` API.  It just tells
+people to import a WSGI server and use it to serve up their Pyramid
+application as per the documentation of that WSGI server.
 
 The extra lines saved by abstracting away the serving step behind
 ``run()`` seem to have driven dubious second-order decisions related
@@ -1686,20 +1592,12 @@ can interface with a WSGI application is placed on the server
 developer, not the web framework developer, making it more likely to
 be timely and correct.
 
-All of the above said, BFG version 1.3 may offer a ``run()`` - like
-shortcut serving API which executes a WSGI server.  But I might also
-chicken out and not add it: I'd rather not deal with needing to supply
-support answers like `this one
-<http://twitter.com/bottlepy/status/20451760706>`_.  If I add such a
-method, it will likely be named less attractively to indicate it is
-only a shortcut.
-
-:meth:`repoze.bfg.configuration.Configurator.begin` and :meth:`repoze.bfg.configuration.Configurator.end` methods
+:meth:`pyramid.configuration.Configurator.begin` and :meth:`pyramid.configuration.Configurator.end` methods
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-The methods :meth:`repoze.bfg.configuration.Configurator.begin` and
-:meth:`repoze.bfg.configuration.Configurator.end` are used to bracket
-the configuration phase of a :mod:`repoze.bfg` application.
+The methods :meth:`pyramid.configuration.Configurator.begin` and
+:meth:`pyramid.configuration.Configurator.end` are used to bracket
+the configuration phase of a :mod:`pyramid` application.
 
 These exist because existing legacy third party *configuration* (not
 runtime) code relies on a threadlocal stack being populated. The
@@ -1707,13 +1605,13 @@ runtime) code relies on a threadlocal stack being populated. The
 method pops it back off.
 
 For the simplest applications, these lines are actually not required.
-I *could* omit them from every BFG hello world app without ill effect.
-However, when users use certain configuration methods (ones not
-represented in the hello world app), calling code will begin to fail
-when it is not bracketed between a ``begin()`` and an ``end()``.  It
-is just easier to tell users that this bracketing is required than to
-try to explain to them which circumstances it is actually required and
-which it is not, because the explanation is often torturous.
+I *could* omit them from every Pyramid hello world app without ill
+effect.  However, when users use certain configuration methods (ones
+not represented in the hello world app), calling code will begin to
+fail when it is not bracketed between a ``begin()`` and an ``end()``.
+It is just easier to tell users that this bracketing is required than
+to try to explain to them which circumstances it is actually required
+and which it is not, because the explanation is often torturous.
 
 The effectively-required execution of these two methods is a wholly
 bogus artifact of an early bad design decision which encouraged
@@ -1728,7 +1626,7 @@ removed from the documenation.
 Wrapping Up
 +++++++++++
 
-Here's a diagrammed version of the simplest repoze.bfg application,
+Here's a diagrammed version of the simplest pyramid application,
 where comments take into account what we've discussed in the
 :ref:`microframeworks_smaller_hello_world` section.
 
@@ -1742,7 +1640,7 @@ where comments take into account what we've discussed in the
        return Response('Hello world!') 
 
    if __name__ == '__main__':
-       from repoze.bfg.configuration import Configurator
+       from pyramid.configuration import Configurator
        config = Configurator()       # no global application object.
        config.begin()                # bogus, but required.
        config.add_view(hello_world)  # explicit non-decorator registration
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 5aa6c15de..dfc40c407 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -400,7 +400,7 @@ Glossary
      A list of element "left over" after the :term:`router` has
      performed a successful traversal to a view.  The subpath is a
      sequence of strings, e.g. ``['left', 'over', 'names']``.  Within
-     BFG applications that use URL dispatch rather than traversal, you
+     Pyramid applications that use URL dispatch rather than traversal, you
      can use ``*subpath`` in the route pattern to influence the
      subpath.  See :ref:`star_subpath` for more information.
 
diff --git a/docs/index.rst b/docs/index.rst
index 5aa2e8b99..3b5d204cc 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,14 +1,13 @@
 .. _index:
 
-========================================
-The repoze.bfg Web Application Framework
-========================================
+=================================================
+The pyramid Web Application Development Framework
+=================================================
 
-:mod:`repoze.bfg` is a small, fast, down-to-earth Python web
-application framework.  It is developed as part of the `Repoze
-<http://repoze.org>`_ project by `Agendaless Consulting
-<http://agendaless.com>`_ and other contributors.  It is licensed
-under a `BSD-like license <http://repoze.org/license.html>`_.
+:mod:`pyramid` is a small, fast, down-to-earth Python web application
+development framework.  It is developed as part of the `Pylons
+<http://pylonshq.com>`_ project.  It is licensed under a `BSD-like
+license <http://repoze.org/license.html>`_.
 
 Front Matter
 ============
@@ -19,21 +18,11 @@ Front Matter
    copyright.rst
    conventions.rst
 
-"What's New" Documents
-======================
-
-.. toctree::
-   :maxdepth: 2
-
-   whatsnew-1.3
-   whatsnew-1.2
-   whatsnew-1.1
-
 Narrative documentation
 =======================
 
 Narrative documentation in chapter form explaining how to use
-:mod:`repoze.bfg`.
+:mod:`pyramid`.
 
 .. toctree::
    :maxdepth: 2
@@ -69,15 +58,15 @@ Narrative documentation in chapter form explaining how to use
 Tutorials
 =========
 
-Detailed tutorials explaining how to use :mod:`repoze.bfg` to build
-various types of applications and how to deploy :mod:`repoze.bfg`
+Detailed tutorials explaining how to use :mod:`pyramid` to build
+various types of applications and how to deploy :mod:`pyramid`
 applications to various platforms.
 
 .. toctree::
    :maxdepth: 2
 
-   tutorials/bfgwiki/index.rst
-   tutorials/bfgwiki2/index.rst
+   tutorials/wiki/index.rst
+   tutorials/wiki2/index.rst
    tutorials/cmf/index.rst
    tutorials/gae/index.rst
    tutorials/modwsgi/index.rst
@@ -89,7 +78,7 @@ Reference Material
 ==================
 
 Reference material includes API documentation and documentation of
-every :mod:`repoze.bfg` :term:`ZCML directive`.
+every :mod:`pyramid` :term:`ZCML directive`.
 
 .. toctree::
    :maxdepth: 2
@@ -116,6 +105,12 @@ Design Documentation
 Sample Applications
 ===================
 
+.. warning::
+
+   These applications are for an older version of :mod:`pyramid`,
+   which was named :mod:`repoze.bfg`.  We'll be updating them soon to
+   use :mod:`pyramid`.
+
 `repoze.cluegun <http://svn.repoze.org/repoze.cluegun/trunk/>`_ is a
 simple pastebin application based on Rocky Burt's `ClueBin
 <http://pypi.python.org/pypi/ClueBin/0.2.3>`_.  It demonstrates form
@@ -162,25 +157,25 @@ commenting, and file uploads.  See the `KARL site
 Support and Development
 =======================
 
-The `BFG web site <http://bfg.repoze.org>`_ is the main online source
-of :mod:`repoze.bfg` support and development information.
+The `Pyramid web site <http://pylonshq.com/pyramid>`_ is the main
+online source of :mod:`pyramid` support and development information.
 
-To report bugs, use the `bug tracker <http://bfg.repoze.org/trac>`_.
+To report bugs, use the `issue tracker
+<http://github.com/Pylons/pyramid/issues>`_.
 
 If you've got questions that aren't answered by this documentation,
-contact the `Repoze-dev maillist
-<http://lists.repoze.org/listinfo/repoze-dev>`_ or join the `#repoze
-IRC channel <irc://irc.freenode.net/#repoze>`_.
+contact the `Pylons-discuss maillist
+<http://groups.google.com/group/pylons-discuss>`_ or join the `#pylons
+IRC channel <irc://irc.freenode.net/#pylons>`_.
 
-Browse and check out tagged and trunk versions of :mod:`repoze.bfg`
-via the `Repoze Subversion repository
-<http://svn.repoze.org/repoze.bfg/>`_.  To check out the trunk
-via Subversion, use this command::
+Browse and check out tagged and trunk versions of :mod:`pyramid` via
+the `Pyramid GitHub repository <http://github.com/Pylons/pyramid/>`_.
+To check out the trunk via ``git``, use this command::
 
-  svn co http://svn.repoze.org/repoze.bfg/trunk repoze.bfg
+  git clone git@github.com:Pylons/pyramid.git
 
-To find out how to become a contributor to :mod:`repoze.bfg`, please
-see the `contributor's page <http://repoze.org/contributing.html>`_.
+To find out how to become a contributor to :mod:`pyramid`, please see
+the `contributor's page <http://repoze.org/contributing.html>`_.
 
 Index and Glossary
 ==================
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
index 917e09bba..2bc052e7e 100644
--- a/docs/latexindex.rst
+++ b/docs/latexindex.rst
@@ -1,7 +1,7 @@
 .. _latexindex:
 
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-The :mod:`repoze.bfg` Web Application Framework
+The :mod:`pyramid` Web Application Framework
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 
 .. frontmatter::
@@ -63,8 +63,8 @@ Tutorials
 .. toctree::
    :maxdepth: 1
 
-   tutorials/bfgwiki/index.rst
-   tutorials/bfgwiki2/index.rst
+   tutorials/wiki/index.rst
+   tutorials/wiki2/index.rst
    tutorials/gae/index.rst
    tutorials/modwsgi/index.rst
    tutorials/zeo/index.rst
diff --git a/docs/tutorials/wiki/background.rst b/docs/tutorials/wiki/background.rst
index e81cf8192..a7f9d1e82 100644
--- a/docs/tutorials/wiki/background.rst
+++ b/docs/tutorials/wiki/background.rst
@@ -13,6 +13,6 @@ To code along with this tutorial, the developer will need a UNIX
 machine with development tools (Mac OS X with XCode, any Linux or BSD
 variant, etc) *or* he will need a Windows system of any kind.
 
-This tutorial targets :mod:`pyramid` version 1.3.
+This tutorial targets :mod:`pyramid` version 1.0.
 
 Have fun!
diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst
deleted file mode 100644
index e9f975373..000000000
--- a/docs/whatsnew-1.1.rst
+++ /dev/null
@@ -1,802 +0,0 @@
-What's New In :mod:`repoze.bfg` 1.1
-===================================
-
-This article explains the new features in :mod:`repoze.bfg` version
-1.1 as compared to the previous 1.0 release.  It also documents
-backwards incompatibilities between the two versions and deprecations
-added to 1.1, as well as software dependency changes and notable
-documentation additions.
-
-Major Feature Additions
------------------------
-
-The major feature additions of 1.1 are:
-
-- Allow the use of additional :term:`view predicate` parameters to
-  more finely control view matching.
-
-- Allow the use of :term:`route predicate` parameters to more finely
-  control route matching.
-
-- Make it possible to write views that use a :term:`renderer`.
-
-- Make it possible to write views that use a "wrapper view".
-
-- Added ``<static>`` ZCML directive which registers a view which
-  serves up files in a package directory.
-
-- A new API function: ``repoze.bfg.url.static_url`` is available to
-  compute the path of static resources.
-
-- View configurations can now name an ``attr`` representing the method
-  or attribute of the view callable that should be called to return a
-  response.
-
-- ``@bfg_view`` decorators may now be stacked, allowing for the same
-  view callable to be associated with multiple different view
-  configurations without resorting to ZCML for view configuration.
-
-- ``@bfg_view`` decorators may now be placed on a class method.
-
-- ``paster bfgshell`` now supports IPython if it is found in the
-  Python environment invoking Paster.
-
-- Commonly executed codepaths have been accelerated.
-
-.. _view_predicates_in_1dot1:
-
-View Predicates
-~~~~~~~~~~~~~~~
-
-:mod:`repoze.bfg` 1.0, :term:`view configuration` allowed relatively
-coarse matching of a :term:`request` to a :term:`view callable`.
-Individual view configurations could match the same URL depending on
-the :term:`context` and the URL path, as well as a limited number of
-other request values.
-
-For example, two view configurations mentioning the same :term:`view
-name` could be spelled via a ``@bfg_view`` decorator with a different
-``for_`` parameter.  The view ultimately chosen would be based on the
-:term:`context` type based on the ``for_`` attribute like so:
-
-.. ignore-next-block
-.. code-block:: python
-
-   from webob import Response
-   from repoze.bfg.view import bfg_view
-   from myapp.models import Document
-   from myapp.models import Folder
-
-   @bfg_view(name='index.html', for_=Document)
-   def document_view(context, request):
-       return Response('document view')
-
-   @bfg_view(name='index.html', for_=Folder)
-   def folder_view(context, request):
-       return Response('folder view')
-
-In the above configuration, the ``document_view`` :term:`view
-callable` will be chosen when the :term:`context` is of the class
-``myapp.models.Document``, while the ``folder_view`` view callable
-will be chosen when the context is of class ``myapp.models.Folder``.
-
-There were a number of other attributes that could influence the
-choosing of view callables, such as ``request_type``, and others.
-However, the matching algorithm was rather limited.
-
-In :mod:`repoze.bfg` 1.1, this facility has been enhanced via the
-availability of additional :term:`view predicate` attributes.  For
-example, one view predicate new to 1.1 is ``containment``, which
-implies that the view will be called when the class or interface
-mentioned as ``containment`` is present with respect to any instance
-in the :term:`lineage` of the context:
-
-.. ignore-next-block
-.. code-block:: python
-
-   from webob import Response
-   from repoze.bfg.view import bfg_view
-   from myapp.models import Document
-   from myapp.models import Folder
-   from myapp.models import Blog
-   from myapp.models import Calendar
-
-   @bfg_view(name='index.html', for_=Document, containment=Blog)
-   def blog_document_view(context, request):
-       return Response('blog document view')
-
-   @bfg_view(name='index.html', for_=Folder, containment=Blog)
-   def blog_folder_view(context, request):
-       return Response('blog folder view')
-
-   @bfg_view(name='index.html', for_=Document, containment=Calendar)
-   def calendar_document_view(context, request):
-       return Response('calendar document view')
-
-   @bfg_view(name='index.html', for_=Folder, containment=Calendar)
-   def calendar_folder_view(context, request):
-       return Response('calendar folder view')
-
-As might be evident in the above example, you can use the
-``containment`` predicate to arrange for different view callables to
-be called based on the lineage of the context.  In the above example,
-the ``blog_document_view`` will be called when the context is of the
-class ``myapp.models.Document`` and the containment has an instance of
-the class ``myapp.models.Blog`` in it.  But when all else is equal,
-except the containment has an instance of the class
-``myapp.models.Calendar`` in it instead of ``myapp.models.Blog``, the
-``calendar_document_view`` will be called instead.
-
-All view predicates configurable via the ``@bfg_view`` decorator are
-available via :term:`ZCML` :term:`view configuration` as well.
-
-Additional new 1.1 view predicates besides ``containment`` are:
-
-``request_method``
-
-  True if the specified value (e.g. GET/POST/HEAD/PUT/DELETE) is the
-  request.method value.
-
-``request_param``
-
-  True if the specified value is present in the request.GET or
-  request.POST multidicts.
-
-``xhr``
-
-  True if the request.is_xhr attribute is ``True``, meaning that the
-  request has an ``X-Requested-With`` header with the value
-  ``XMLHttpRequest``
-
-``accept``
-
-  True if the value of this attribute represents matches one or more
-  mimetypes in the ``Accept`` HTTP request header.
-
-``header`` 
-
-  True if the value of this attribute represents an HTTP header name
-  or a header name/value pair present in the request.
-
-``path_info``
-
-  True if the value of this attribute (a regular expression pattern)
-  matches the ``PATH_INFO`` WSGI environment variable.
-
-All other existing view configuration parameters from 1.0 still exist.
-
-Any number of view predicates can be specified in a view
-configuration.  All view predicates in a view configuration must be
-True for a view callable to be invoked.  If one does not evaluate to
-True, the view will not be invoked, and view matching will continue,
-until all potential matches are exhausted (and the Not Found view is
-invoked).
-
-.. _route_predicates_in_1dot1:
-
-Route Predicates
-~~~~~~~~~~~~~~~~
-
-In :mod:`repoze.bfg` 1.0, a :term:`route` would match or not match
-based on only one value: the ``PATH_INFO`` value of the WSGI
-environment, as specified by the ``path`` parameter of the ``<route>``
-ZCML directive.
-
-In 1.1, matching can be more finely controlled via the use of one or
-more :term:`route predicate` attributes.
-
-The additional route predicates in 1.1 are:
-
-``xhr``
-
-  True if the request.is_xhr attribute is ``True``, meaning that the
-  request has an ``X-Requested-With`` header with the value
-  ``XMLHttpRequest``.
-
-``request_method``
-
-  True if the specified value (e.g. GET/POST/HEAD/PUT/DELETE) is the
-  request.method value.
-
-``path_info``
-
-  True if the value of this attribute (a regular expression pattern)
-  matches the ``PATH_INFO`` WSGI environment variable.
-
-``request_param``
-
-  True if the specified value is present in either of the
-  ``request.GET`` or ``request.POST`` multidicts.
-
-``header`` 
-
-  True if the value of this attribute represents an HTTP header name
-  or a header name/value pair present in the request.
-
-``accept``
-
-  True if the value of this attribute represents matches one or more
-  mimetypes in the ``Accept`` HTTP request header.
-
-All other existing route configuration parameters from 1.0 still exist.
-
-Any number of route predicates can be specified in a route
-configuration.  All route predicates in a route configuration must be
-True for a route to match a request.  If one does not evaluate to
-True, the route will not be invoked, and route matching will continue,
-until all potential routes are exhausted (at which point, traversal is
-attempted).
-
-View Renderers
-~~~~~~~~~~~~~~
-
-In :mod:`repoze.bfg` 1.0 and prior, views were required to return a
-:term:`response` object unconditionally.
-
-In :mod:`repoze.bfg` 1.1, a :term:`view configuration` can name a
-:term:`renderer`.  A renderer can either be a template or a token that
-is associated with a serialization technique (e.g. ``json``).  When a
-view configuration names a renderer, the view can return a data
-structure understood by the renderer (such as a dictionary), and the
-renderer will convert the data structure to a response on the behalf
-of the developer.
-
-View configuration can vary the renderer associated with a view via
-the ``renderer`` attribute to the configuration.  For example, this
-ZCML associates the ``json`` renderer with a view:
-
-.. code-block:: xml
-   :linenos:
-
-   <view
-     view=".views.my_view"
-     renderer="json"
-     />
-
-The ``@bfg_view`` decorator can also associate a view callable with a
-renderer:
-
-.. code-block:: python
-   :linenos:
-
-   from repoze.bfg.view import bfg_view
-
-   @bfg_view(renderer='json')
-   def my_view(context, request):
-       return {'abc':123}
-
-The ``json`` renderer renders view return values to a :term:`JSON`
-serialization.
-
-Another built-in renderer uses the :term:`Chameleon` templating
-language to render a dictionary to a response.  For example:
-
-.. code-block:: python
-   :linenos:
-
-   from repoze.bfg.view import bfg_view
-
-   @bfg_view(renderer='templates/my_template.pt')
-   def my_view(context, request):
-       return {'abc':123}
-
-See :ref:`built_in_renderers` for the available built-in renderers.
-
-If the ``view`` callable associated with a ``view`` directive returns
-a Response object (an object with the attributes ``status``,
-``headerlist`` and ``app_iter``), any renderer associated with the
-``view`` declaration is ignored, and the response is passed back to
-BFG unmolested.  For example, if your view callable returns an
-``HTTPFound`` response, no renderer will be employed.
-
-.. code-block:: python
-   :linenos:
-
-   from webob.exc import HTTPFound
-   from repoze.bfg.view import bfg_view
-
-   @bfg_view(renderer='templates/my_template.pt')
-   def my_view(context, request):
-       return HTTPFound(location='http://example.com') # renderer avoided
-
-Additional renderers can be added to the system as necessary via a
-ZCML directive (see :ref:`adding_and_overriding_renderers`).
-
-If you do not define a ``renderer`` attribute in view configuration
-for a view, no renderer is associated with the view.  In such a
-configuration, an error is raised when a view does not return an
-object which implements :term:`Response` interface, as was the case
-under BFG 1.0.
-
-Views Which Use Wrappers
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-In :mod:`repoze.bfg` 1.1, view configuration may specify a ``wrapper``
-attribute.  For example:
-
-.. code-block:: xml
-   :linenos:
-
-   <view
-     name="one"
-     view=".views.wrapper_view"
-     />
-
-   <view
-     name="two"
-     view=".views.my_view"
-     wrapper="one"
-     />
-
-The ``wrapper`` attribute of a view configuration is a :term:`view
-name` (*not* an object dotted name).  It specifies *another* view
-callable declared elsewhere in :term:`view configuration`.  In the
-above example, the wrapper of the ``two`` view is the ``one`` view.
-
-The wrapper view will be called when after the wrapped view is
-invoked; it will receive the response body of the wrapped view as the
-``wrapped_body`` attribute of its own request, and the response
-returned by this view as the ``wrapped_response`` attribute of its own
-request.
-
-Using a wrapper makes it possible to "chain" views together to form a
-composite response.  The response of the outermost wrapper view will
-be returned to the user.
-
-The wrapper view will be found as any view is found: see
-:ref:`view_lookup`.  The "best" wrapper view will be found based on
-the lookup ordering: "under the hood" this wrapper view is looked up
-via ``repoze.bfg.view.render_view_to_response(context, request,
-'wrapper_viewname')``. The context and request of a wrapper view is
-the same context and request of the inner view.
-
-If the ``wrapper`` attribute is unspecified in a view configuration,
-no view wrapping is done.
-
-The ``@bfg_view`` decorator accepts a ``wrapper`` parameter, mirroring
-its ZCML view configuration counterpart.
-
-``<static>`` ZCML Directive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A new ZCML directive named ``static`` has been added.  Inserting a
-``static`` declaration in a ZCML file will cause static resources to
-be served at a configurable URL.
-
-Here's an example of a ``static`` directive that will serve files up
-from the ``templates/static`` directory of the :mod:`repoze.bfg`
-application containing the following configuration at the URL
-``/static``.
-
-.. code-block:: xml
-   :linenos:
-
-   <static
-      name="static"
-      path="templates/static"
-      />
-
-Using the ``static`` ZCML directive is now the preferred way to serve
-static resources (such as JavaScript and CSS files) within a
-:mod:`repoze.bfg` application.  Previous strategies for serving static
-resources will still work, however.
-
-New ``static_url`` API
-~~~~~~~~~~~~~~~~~~~~~~
-
-The new ``repoze.bfg.url.static_url`` API generates a fully qualified
-URL to a static resource available via a path exposed via the
-``<static>`` ZCML directive (see :ref:`static_resources_section`).
-For example, if a ``<static>`` directive is in ZCML configuration like
-so:
-
-.. code-block:: xml
-   :linenos:
-
-   <static
-      name="static"
-      path="templates/static"
-      />
-
-You can generate a URL to a resource which lives within the
-``templates/static`` subdirectory using the ``static_url`` API like
-so:
-
-.. ignore-next-block
-.. code-block:: python
-   :linenos:
-
-   from repoze.bfg.url import static_url
-   url = static_url('templates/static/example.css', request)
-
-Use of the ``static_url`` API prevents the developer from needing to
-hardcode path values in template URLs.
-
-``attr`` View Configuration Value
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The view machinery defaults to using the ``__call__`` method of the
-view callable (or the function itself, if the view callable is a
-function) to obtain a response.
-
-In :mod:`repoze.bfg` 1.1, the ``attr`` view configuration value allows
-you to vary the attribute of a view callable used to obtain the
-response.
-
-For example, if your view is a class, and the class has a method named
-``index`` and you want to use this method instead of the class'
-``__call__`` method to return the response, you'd say ``attr="index"``
-in the view configuration for the view.
-
-Specifying ``attr`` is most useful when the view definition is a
-class.  For example:
-
-.. code-block:: xml
-   :linenos:
-
-   <view
-      view=".views.MyViewClass"
-      attr="index"
-      />
-
-The referenced ``MyViewClass`` might look like so:
-
-.. code-block:: python
-   :linenos:
-
-   from webob import Response
-
-   class MyViewClass(object):
-       def __init__(context, request):
-           self.context = context
-           self.request = request
-
-       def index(self):
-           return Response('OK')
-
-The ``index`` method of the class will be used to obtain a response.
-
-``@bfg_view`` Decorators May Now Be Stacked
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-More than one ``@bfg_view`` decorator may now be stacked on top of any
-number of others.  Each invocation of the decorator registers a single
-view configuration.  For instance, the following combination of
-decorators and a function will register two view configurations for
-the same view callable:
-
-.. code-block:: python
-   :linenos:
-
-   from repoze.bfg.view import bfg_view
-
-   @bfg_view(name='edit')
-   @bfg_view(name='change')
-   def edit(context, request):
-       pass
-
-This makes it possible to associate more than one view configuration
-with a single callable without requiring any ZCML.
-
-Stacking ``@bfg_view`` decorators was not possible in
-:mod:`repoze.bfg` 1.0.
-
-``@bfg_view`` Decorators May Now Be Applied to A Class Method
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In :mod:`repoze.bfg` 1.0, the ``@bfg_view`` decorator could not be
-used on class methods.  In 1.1, the ``@bfg_view`` decorator can be
-used against a class method:
-
-.. code-block:: python
-   :linenos:
-
-   from webob import Response
-   from repoze.bfg.view import bfg_view
-
-   class MyView(object):
-       def __init__(self, context, request):
-           self.context = context
-           self.request = request
-
-       @bfg_view(name='hello')
-       def amethod(self):
-           return Response('hello from %s!' % self.context)
-
-When the bfg_view decorator is used against a class method, a view is
-registered for the *class* (it's a "class view" where the "attr"
-happens to be the name of the method it is attached to), so the class
-it's defined within must have a suitable constructor: one that accepts
-``context, request`` or just ``request``.
-
-IPython Support
-~~~~~~~~~~~~~~~
-
-If it is installed in the environment used to run :mod:`repoze.bfg`,
-an `IPython <http://ipython.scipy.org/moin/>`_ shell will be opened
-when the ``paster bfgshell`` command is invoked.
-
-Common Codepaths Have Been Accelerated
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-:mod:`repoze.bfg` 1.1 is roughly 10% - 20% faster in commonly executed
-codepaths than :mod:`repoze.bfg` 1.0 was on average.  Accelerated APIs
-include ``repoze.bfg.location.lineage``, ``repoze.bfg.url.model_url``,
-and ``repoze.bfg.url.route_url``.  Other internal (non-API) functions
-were similarly accelerated.
-
-Minor Miscellaneous Feature Additions
--------------------------------------
-
-- For behavior like Django's ``APPEND_SLASH=True``, use the
-  ``repoze.bfg.view.append_slash_notfound_view`` view as the Not Found
-  view in your application.  When this view is the Not Found view
-  (indicating that no view was found), and any routes have been
-  defined in the configuration of your application, if the value of
-  ``PATH_INFO`` does not already end in a slash, and if the value of
-  ``PATH_INFO`` *plus* a slash matches any route's path, do an HTTP
-  redirect to the slash-appended PATH_INFO.  Note that this will
-  *lose* ``POST`` data information (turning it into a GET), so you
-  shouldn't rely on this to redirect POST requests.
-
-- Add ``repoze.bfg.testing.registerSettings`` API, which is documented
-  in the "repoze.bfg.testing" API chapter.  This allows for
-  registration of "settings" values obtained via
-  ``repoze.bfg.settings.get_settings()`` for use in unit tests.
-
-- Added ``max_age`` parameter to ``authtktauthenticationpolicy`` ZCML
-  directive.  If this value is set, it must be an integer representing
-  the number of seconds which the auth tkt cookie will survive.
-  Mainly, its existence allows the auth_tkt cookie to survive across
-  browser sessions.
-
-- The ``reissue_time`` argument to the ``authtktauthenticationpolicy``
-  ZCML directive now actually works.  When it is set to an integer
-  value, an authticket set-cookie header is appended to the response
-  whenever a request requires authentication and 'now' minus the
-  authticket's timestamp is greater than ``reissue_time`` seconds.
-
-- Expose and document ``repoze.bfg.testing.zcml_configure`` API.  This
-  function populates a component registry from a ZCML file for testing
-  purposes.  It is documented in the "Unit and Integration Testing"
-  chapter.
-
-- Virtual hosting narrative docs chapter updated with info about
-  ``mod_wsgi``.
-
-- Added "Creating Integration Tests" section to unit testing narrative
-  documentation chapter.  As a result, the name of the unittesting
-  chapter is now "Unit and Integration Testing".
-
-- Add a new ``repoze.bfg.testing`` API: ``registerRoute``, for
-  registering routes to satisfy calls to
-  e.g. ``repoze.bfg.url.route_url`` in unit tests.
-
-- Added a tutorial which explains how to use ``repoze.session``
-  (ZODB-based sessions) in a ZODB-based repoze.bfg app.
-
-- Added a tutorial which explains how to add ZEO to a ZODB-based
-  ``repoze.bfg`` application.
-
-- Added a tutorial which explains how to run a ``repoze.bfg``
-  application under `mod_wsgi <http://code.google.com/p/modwsgi/>`_.
-  See "Running a repoze.bfg Application under mod_wsgi" in the
-  tutorials section of the documentation.
-
-- Allow ``repoze.bfg.traversal.find_interface`` API to use a class
-  object as the argument to compare against the ``model`` passed in.
-  This means you can now do ``find_interface(model, SomeClass)`` and
-  the first object which is found in the lineage which has
-  ``SomeClass`` as its class (or the first object found which has
-  ``SomeClass`` as any of its superclasses) will be returned.
-
-- The ordering of route declarations vs. the ordering of view
-  declarations that use a "route_name" in ZCML no longer matters.
-  Previously it had been impossible to use a route_name from a route
-  that had not yet been defined in ZCML (order-wise) within a "view"
-  declaration.
-
-- The repoze.bfg router now catches both
-  ``repoze.bfg.exceptions.Unauthorized`` and
-  ``repoze.bfg.exceptions.NotFound`` exceptions while rendering a view.
-  When the router catches an ``Unauthorized``, it returns the
-  registered forbidden view.  When the router catches a ``NotFound``,
-  it returns the registered notfound view.
-
-- Add a new event type: ``repoze.bfg.events.AfterTraversal``.  Events
-  of this type will be sent after traversal is completed, but before
-  any view code is invoked.  Like ``repoze.bfg.events.NewRequest``,
-  This event will have a single attribute: ``request`` representing
-  the current request.  Unlike the request attribute of
-  ``repoze.bfg.events.NewRequest`` however, during an AfterTraversal
-  event, the request object will possess attributes set by the
-  traverser, most notably ``context``, which will be the context used
-  when a view is found and invoked.  The interface
-  ``repoze.bfg.events.IAfterTraversal`` can be used to subscribe to
-  the event.  For example::
-
-    <subscriber for="repoze.bfg.interfaces.IAfterTraversal"
-                handler="my.app.handle_after_traverse"/>
-
-  Like any framework event, a subscriber function should expect one
-  parameter: ``event``.
-
-- A ``repoze.bfg.testing.registerRoutesMapper`` testing facility has
-  been added.  This testing function registers a routes "mapper"
-  object in the registry, for tests which require its presence.  This
-  function is documented in the ``repoze.bfg.testing`` API
-  documentation.
-
-Backwards Incompatibilities
----------------------------
-
-- The ``authtkt`` authentication policy ``remember`` method now no
-  longer honors ``token`` or ``userdata`` keyword arguments.
-
-- Importing ``getSiteManager`` and ``get_registry`` from
-  ``repoze.bfg.registry`` is no longer supported.  These imports were
-  deprecated in repoze.bfg 1.0.  Import of ``getSiteManager`` should
-  be done as ``from zope.component import getSiteManager``.  Import of
-  ``get_registry`` should be done as ``from repoze.bfg.threadlocal
-  import get_current_registry``.  This was done to prevent a circular
-  import dependency.
-
-- Code bases which alternately invoke both
-  ``zope.testing.cleanup.cleanUp`` and ``repoze.bfg.testing.cleanUp``
-  (treating them equivalently, using them interchangeably) in the
-  setUp/tearDown of unit tests will begin to experience test failures
-  due to lack of test isolation.  The "right" mechanism is
-  ``repoze.bfg.testing.cleanUp`` (or the combination of
-  ``repoze.bfg.testing.setUp`` and
-  ``repoze.bfg.testing.tearDown``). but a good number of legacy
-  codebases will use ``zope.testing.cleanup.cleanUp`` instead.  We
-  support ``zope.testing.cleanup.cleanUp`` but not in combination with
-  ``repoze.bfg.testing.cleanUp`` in the same codebase.  You should use
-  one or the other test cleanup function in a single codebase, but not
-  both.
-
-- In 0.8a7, the return value expected from an object implementing
-  ``ITraverserFactory`` was changed from a sequence of values to a
-  dictionary containing the keys ``context``, ``view_name``,
-  ``subpath``, ``traversed``, ``virtual_root``, ``virtual_root_path``,
-  and ``root``.  Until now, old-style traversers which returned a
-  sequence have continued to work but have generated a deprecation
-  warning.  In this release, traversers which return a sequence
-  instead of a dictionary will no longer work.
-
-- The interfaces ``IPOSTRequest``, ``IGETRequest``, ``IPUTRequest``,
-  ``IDELETERequest``, and ``IHEADRequest`` have been removed from the
-  ``repoze.bfg.interfaces`` module.  These were not documented as APIs
-  post-1.0.  Instead of using one of these, use a ``request_method``
-  ZCML attribute or ``request_method`` bfg_view decorator parameter
-  containing an HTTP method name (one of ``GET``, ``POST``, ``HEAD``,
-  ``PUT``, ``DELETE``) instead of one of these interfaces if you were
-  using one explicitly.  Passing a string in the set (``GET``,
-  ``HEAD``, ``PUT``, ``POST``, ``DELETE``) as a ``request_type``
-  argument will work too.  Rationale: instead of relying on interfaces
-  attached to the request object, BFG now uses a "view predicate" to
-  determine the request type.
-
-- Views registered without the help of the ZCML ``view`` directive are
-  now responsible for performing their own authorization checking.
-
-- The ``registry_manager`` backwards compatibility alias importable
-  from "repoze.bfg.registry", deprecated since repoze.bfg 0.9 has been
-  removed.  If you are trying to use the registry manager within a
-  debug script of your own, use a combination of the
-  "repoze.bfg.paster.get_app" and "repoze.bfg.scripting.get_root" APIs
-  instead.
-
-- The ``INotFoundAppFactory`` interface has been removed; it has
-  been deprecated since repoze.bfg 0.9.  If you have something like
-  the following in your ``configure.zcml``::
-
-   <utility provides="repoze.bfg.interfaces.INotFoundAppFactory"
-            component="helloworld.factories.notfound_app_factory"/>
-
-  Replace it with something like::
-
-   <notfound 
-       view="helloworld.views.notfound_view"/>
-
-  See "Changing the Not Found View" in the "Hooks" chapter of the
-  documentation for more information.
-
-- The ``IUnauthorizedAppFactory`` interface has been removed; it has
-  been deprecated since repoze.bfg 0.9.  If you have something like
-  the following in your ``configure.zcml``::
-
-   <utility provides="repoze.bfg.interfaces.IUnauthorizedAppFactory"
-            component="helloworld.factories.unauthorized_app_factory"/>
-
-  Replace it with something like::
-
-   <forbidden
-       view="helloworld.views.forbidden_view"/>
-
-  See "Changing the Forbidden View" in the "Hooks" chapter of the
-  documentation for more information.
-
-- ``ISecurityPolicy``-based security policies, deprecated since
-  repoze.bfg 0.9, have been removed.  If you have something like this
-  in your ``configure.zcml``, it will no longer work::
-
-   <utility
-     provides="repoze.bfg.interfaces.ISecurityPolicy"
-     factory="repoze.bfg.security.RemoteUserInheritingACLSecurityPolicy"
-     />
-
-   If ZCML like the above exists in your application, you will receive
-   an error at startup time.  Instead of the above, you'll need
-   something like::
-
-     <remoteuserauthenticationpolicy/>
-     <aclauthorizationpolicy/>
-
-   This is just an example.  See the "Security" chapter of the
-   repoze.bfg documentation for more information about configuring
-   security policies.
-
-- The ``repoze.bfg.scripting.get_root`` function now expects a
-  ``request`` object as its second argument rather than an
-  ``environ``.
-
-Deprecations and Behavior Differences
--------------------------------------
-
-- In previous versions of BFG, the "root factory" (the ``get_root``
-  callable passed to ``make_app`` or a function pointed to by the
-  ``factory`` attribute of a route) was called with a "bare" WSGI
-  environment.  In this version, and going forward, it will be called
-  with a ``request`` object.  The request object passed to the factory
-  implements dictionary-like methods in such a way that existing root
-  factory code which expects to be passed an environ will continue to
-  work.
-
-- The ``__call__`` of a plugin "traverser" implementation (registered
-  as an adapter for ``ITraverser`` or ``ITraverserFactory``) will now
-  receive a *request* as the single argument to its ``__call__``
-  method.  In previous versions it was passed a WSGI ``environ``
-  object.  The request object passed to the factory implements
-  dictionary-like methods in such a way that existing traverser code
-  which expects to be passed an environ will continue to work.
-
-- The request implements dictionary-like methods that mutate and query
-  the WSGI environ.  This is only for the purpose of backwards
-  compatibility with root factories which expect an ``environ`` rather
-  than a request.
-
-- The order in which the router calls the request factory and the root
-  factory has been reversed.  The request factory is now called first;
-  the resulting request is passed to the root factory.
-
-- Add ``setUp`` and ``tearDown`` functions to the
-  ``repoze.bfg.testing`` module.  Using ``setUp`` in a test setup and
-  ``tearDown`` in a test teardown is now the recommended way to do
-  component registry setup and teardown.  Previously, it was
-  recommended that a single function named
-  ``repoze.bfg.testing.cleanUp`` be called in both the test setup and
-  tear down.  ``repoze.bfg.testing.cleanUp`` still exists (and will
-  exist "forever" due to its widespread use); it is now just an alias
-  for ``repoze.bfg.testing.setUp`` and is nominally deprecated.
-
-- The import of ``repoze.bfg.security.Unauthorized`` is deprecated in
-  favor of ``repoze.bfg.exceptions.Forbidden``.  The old location
-  still functions but emits a deprecation warning.  The rename from
-  ``Unauthorized`` to ``Forbidden`` brings parity to the name of the
-  exception and the system view it invokes when raised.
-
-- Custom ZCML directives which register an authentication or
-  authorization policy (ala "authtktauthenticationpolicy" or
-  "aclauthorizationpolicy") should register the policy "eagerly" in
-  the ZCML directive instead of from within a ZCML action.  If an
-  authentication or authorization policy is not found in the component
-  registry by the view machinery during deferred ZCML processing, view
-  security will not work as expected.
-
-Dependency Changes
-------------------
-
-- When used under Python < 2.6, BFG now has an installation time
-  dependency on the ``simplejson`` package.
-
diff --git a/docs/whatsnew-1.2.rst b/docs/whatsnew-1.2.rst
deleted file mode 100644
index 9b446f4b8..000000000
--- a/docs/whatsnew-1.2.rst
+++ /dev/null
@@ -1,364 +0,0 @@
-What's New In :mod:`repoze.bfg` 1.2
-===================================
-
-This article explains the new features in :mod:`repoze.bfg` version
-1.2 as compared to the previous 1.1 release.  It also documents
-backwards incompatibilities between the two versions and deprecations
-added to 1.2, as well as software dependency changes and notable
-documentation additions.
-
-Major Feature Additions
------------------------
-
-The major feature addition in 1.2 is an :term:`imperative
-configuration` mode. This implies:
-
-- A :mod:`repoze.bfg` application can now be contained within a single
-  Python file.
-
-- Developers are no longer required to use or understand :term:`ZCML`
-  to create a :mod:`repoze.bfg` application (ZCML is, however still
-  supported).
-
-The simplest possible :mod:`repoze.bfg` 1.2 application is:
-
-  .. code-block:: python
-     :linenos:
-
-     from webob import Response
-     from paste.httpserver import serve
-     from repoze.bfg.configuration import Configurator
-
-     def hello_world(request):
-         return Response('Hello world!')
-
-     if __name__ == '__main__':
-         config = Configurator()
-         config.begin()
-         config.add_view(hello_world)
-         config.end()
-         app = config.make_wsgi_app()
-         serve(app)
-
-This feature tends to make :mod:`repoze.bfg` competitive with
-"microframeworks" such as `Bottle <http://bottle.paws.de/>`_ and
-`Tornado <http://www.tornadoweb.org/>`_.  :mod:`repoze.bfg` has a good
-deal of functionality that most microframeworks lack, so this is
-hopefully a "best of both worlds" feature.
-
-Imperative configuration is also useful while writing tests.
-
-For an introduction to imperative configuration mode, see
-:ref:`configuration_narr`.
-
-Minor Feature Additions
------------------------
-
-- Jython compatibility (at least when ``repoze.bfg.jinja2`` is used as
-  the templating engine; Chameleon does not work under Jython).
-
-- Read logging configuration from PasteDeploy config file ``loggers``
-  section (and related) when ``paster bfgshell`` is invoked.
-
-- The ``AuthTktAuthenticationPolicy`` now accepts two additional
-  constructor arguments: ``path`` and ``http_only``.
-
-- The :func:`repoze.bfg.testing.setUp` function now accepts three
-  extra optional keyword arguments: ``registry``, ``request`` and
-  ``hook_zca``.
-
-  If the ``registry`` argument is not ``None``, the argument will be
-  treated as the registry that is set as the "current registry" (it
-  will be returned by
-  :func:`repoze.bfg.threadlocal.get_current_registry`) for the
-  duration of the test.  If the ``registry`` argument is ``None`` (the
-  default), a new registry is created and used for the duration of the
-  test.
-
-  The value of the ``request`` argument is used as the "current
-  request" (it will be returned by
-  :func:`repoze.bfg.threadlocal.get_current_request`) for the duration
-  of the test; it defaults to ``None``.
-
-  If ``hook_zca`` is ``True`` (the default), the
-  :func:`zope.component.getSiteManager` function will be hooked with a
-  function that returns the value of ``registry`` (or the
-  default-created registry if ``registry`` is ``None``) instead of the
-  registry returned by :func:`zope.component.getGlobalSiteManager`,
-  causing the Zope Component Architecture API (``getSiteManager``,
-  ``getAdapter``, ``getUtility``, and so on) to use the testing
-  registry instead of the global ZCA registry.
-
-- The :func:`repoze.bfg.testing.tearDown` function now accepts an
-  ``unhook_zca`` argument.  If this argument is ``True`` (the
-  default), :func:`zope.component.getSiteManager.reset` will be
-  called.  This will cause the result of the
-  :func:`zope.component.getSiteManager` function to be the global ZCA
-  registry (the result of :func:`zope.component.getGlobalSiteManager`)
-  once again.
-
-- When the :exc:`repoze.bfg.exceptions.NotFound` or
-  :exc:`repoze.bfg.exceptions.Forbidden` error is raised from within a
-  custom :term:`root factory` or the factory of a :term:`route`, the
-  appropriate response is sent to the requesting user agent (the
-  result of the notfound view or the forbidden view, respectively).
-  When these errors are raised from within a root factory, the
-  :term:`context` passed to the notfound or forbidden view will be
-  ``None``.  Also, the request will not be decorated with
-  ``view_name``, ``subpath``, ``context``, etc. as would normally be
-  the case if traversal had been allowed to take place.
-
-- :class:`repoze.bfg.testing.DummyModel` now accepts a new constructor
-  keyword argument: ``__provides__``.  If this constructor argument is
-  provided, it should be an interface or a tuple of interfaces.  The
-  resulting model will then provide these interfaces (they will be
-  attached to the constructed model via
-  :func:`zope.interface.alsoProvides`).
-
-- Read logging configuration from PasteDeploy config file ``loggers``
-  section (and related) when ``paster bfgshell`` is invoked.
-
-- View registration via ZCML now accepts an attribute named
-  ``context``.  This is an alias for the older argument named ``for``;
-  it is preferred over ``for``, but ``for`` will continue to be
-  supported "forever".
-
-Backwards Incompatibilites
---------------------------
-
-- Unit tests which use :func:`zope.testing.cleanup.cleanUp` for the
-  purpose of isolating tests from one another may now begin to fail
-  due to lack of isolation between tests.
-
-  Here's why: In repoze.bfg 1.1 and prior, the registry returned by
-  :func:`repoze.bfg.threadlocal.get_current_registry` when no other
-  registry had been pushed on to the threadlocal stack was the
-  :data:`zope.component.globalregistry.base` global registry (aka the
-  result of :func:`zope.component.getGlobalSiteManager()`).  In
-  :mod:`repoze.bfg` 1.2+, however, the registry returned in this
-  situation is the new module-scope
-  :data:`repoze.bfg.registry.global_registry` object.  The
-  :func:`zope.testing.cleanup.cleanUp` function clears the
-  :data:`zope.component.globalregistry.base` global registry
-  unconditionally.  However, it does not know about the
-  :data:`repoze.bfg.registry.global_registry` object, so it does not
-  clear it.
-
-  If you use the :func:`zope.testing.cleanup.cleanUp` function in the
-  ``setUp`` of test cases in your unit test suite instead of using the
-  (more correct as of 1.1) :func:`repoze.bfg.testing.setUp`, you will
-  need to replace all calls to :func:`zope.testing.cleanup.cleanUp`
-  with a call to :func:`repoze.bfg.testing.setUp`.
-
-  If replacing all calls to :func:`zope.testing.cleanup.cleanUp` with
-  a call to :func:`repoze.bfg.testing.setUp` is infeasible, you can
-  put the below-mentioned bit of code somewhere that is executed
-  exactly **once** (*not* for each test in a test suite).  Placing
-  this in the ``__init__.py`` of your package or the ``__init__.py``
-  of a ``tests`` subpackage would be a reasonable place)::
-
-    import zope.testing.cleanup
-    from repoze.bfg.testing import setUp
-    zope.testing.cleanup.addCleanUp(setUp)
-
-- When there is no "current registry" in the
-  :data:`repoze.bfg.threadlocal.manager` threadlocal data structure
-  (this is the case when there is no "current request" or we're not in
-  the midst of a :func:`repoze.bfg.testing.setUp` or
-  :meth:`repoze.bfg.configuration.Configurator.begin` bounded unit
-  test), the ``.get`` method of the manager returns a data structure
-  containing a *global* registry.  In previous releases, this function
-  returned the global Zope "base" registry: the result of
-  :func:`zope.component.getGlobalSiteManager`, which is an instance of
-  the :class:`zope.component.registry.Component` class.  In this
-  release, however, the global registry returns a globally importable
-  instance of the :class:`repoze.bfg.registry.Registry` class.  This
-  registry instance can always be imported as
-  :data:`repoze.bfg.registry.global_registry`.
-
-  Effectively, this means that when you call
-  :func:`repoze.bfg.threadlocal.get_current_registry` when no "real"
-  request or bounded unit test is in effect, you will always get back
-  the global registry that lives in
-  :data:`repoze.bfg.registry.global_registry`.  It also means that
-  :mod:`repoze.bfg` APIs that *call*
-  :func:`repoze.bfg.threadlocal.get_current_registry` will use this
-  registry.
-
-  This change was made because :mod:`repoze.bfg` now expects the
-  registry it uses to have a slightly different API than a bare
-  instance of :class:`zope.component.registry.Components`.
-
-- View registration no longer registers a
-  :class:`repoze.bfg.interfaces.IViewPermission` adapter (it is no
-  longer checked by the framework; since 1.1, views have been
-  responsible for providing their own security).
-
-- The :func:`repoze.bfg.router.make_app` callable no longer accepts an
-  ``authentication_policy`` nor an ``authorization_policy`` argument.
-  These features were deprecated in version 1.0 and have been removed.
-
-- The ``route`` ZCML directive now no longer accepts the
-  ``request_type``, ``view_request_type``, ``view_header``,
-  ``view_accept``, ``view_xhr``, ``view_path_info``,
-  ``view_request_method``, ``view_request_param``, or
-  ``view_containment`` attributes.  If you need the features exposed
-  by these attributes, add a view associated with a route using the
-  ``route_name`` attribute of the ``view`` ZCML directive instead.
-
-- Because the ``repoze.bfg`` package now includes implementations of
-  the ``adapter``, ``subscriber`` and ``utility`` ZCML directives, it
-  is now an error to have ``<include package="repoze.zcml"
-  file="meta.zcml"/>`` in the ZCML of a ``repoze.bfg`` application.  A
-  ZCML conflict error will be raised if your ZCML does so.  This
-  shouldn't be an issue for "normal" installations; it has always been
-  the responsibility of the :mod:`repoze.bfg.includes` ZCML to include
-  this file in the past; it now just doesn't.
-
-- The :func:`repoze.bfg.testing.zcml_configure` API was removed.  Use
-  the :meth:`repoze.bfg.configuration.Configurator.load_zcml` API
-  instead.
-
-- The :mod:`repoze.bfg.templating` module has been removed; it had
-  been deprecated in 1.1 and hasn't possessed any APIs since before
-  1.0.
-
-- Remove magical feature of :meth:`repoze.bfg.url.model_url` which
-  prepended a fully-expanded urldispatch route URL before a the
-  model's path if it was noticed that the request had matched a route.
-  This feature was ill-conceived, and didn't work in all scenarios.
-
-- When "hybrid mode" (both traversal and urldispatch) is in use,
-  default to finding route-related views even if a non-route-related
-  view registration has been made with a more specific context.  The
-  default used to be to find views with a more specific context first.
-  Use the new ``use_global_views`` argument to the route definition to
-  get back the older behavior.
-
-Deprecations and Behavior Differences
--------------------------------------
-
-- If you disuse the legacy :func:`repoze.bfg.router.make_app` function
-  in favor of
-  :meth:`repoze.bfg.configuration.Configurator.make_wsgi_app`, and you
-  also want to use the "global" ZCA API (``getUtility``,
-  ``getAdapter``, ``getSiteManager``, etc), you will need to "hook"
-  the ZCA before calling methods of the configurator using the
-  ``sethook`` method of the ``getSiteManager`` API, e.g.::
-
-    from zope.component import getSiteManager
-    from repoze.bfg.configuration import Configurator
-    from repoze.bfg.threadlocal import get_current_registry
-    from mypackage.models import get_root
-
-    def app(global_config, **settings):
-        config = Configurator(root_factory=get_root, settings=settings)
-        getSiteManager.sethook(get_current_registry)
-        zcml_file = settings.get('configure_zcml', 'configure.zcml')
-        config.load_zcml(zcml_file)
-        return config.make_wsgi_app()
-
-  The :func:`repoze.bfg.router.make_app` function does this on your
-  behalf for backward compatibility purposes.
-
-- The :func:`repoze.bfg.router.make_app` function is now nominally
-  deprecated.  Its import and usage does not throw a warning, nor will
-  it probably ever disappear.  However, using a
-  :class:`repoze.bfg.configuration.Configurator` class is now the
-  preferred way to generate a WSGI application.
-
-  Note that :func:`repoze.bfg.router.make_app` calls
-  ``zope.component.getSiteManager.sethook(
-  repoze.bfg.threadlocal.get_current_registry)`` on the caller's
-  behalf, hooking ZCA global API lookups, for backwards compatibility
-  purposes.  If you disuse ``make_app``, your calling code will need
-  to perform this call itself, at least if your application uses the
-  ZCA global API (``getSiteManager``, ``getAdapter``, etc).
-
-Dependency Changes
-------------------
-
-- A dependency on the ``martian`` package has been removed (its
-  functionality is replaced internally).
-
-- A dependency on the ``repoze.zcml`` package has been removed (its
-  functionality is replaced internally).
-
-- A dependency on the ``sourcecodegen`` package has been removed.
-
-- :mod:`repoze.bfg` now depends on :term:`WebOb` 0.9.7 or better.
-
-- Doc-deprecated most helper functions in the ``repoze.bfg.testing``
-  module.  These helper functions likely won't be removed any time
-  soon, nor will they generate a warning any time soon, due to their
-  heavy use in the wild, but equivalent behavior exists in methods of
-  a :class:`repoze.bfg.configuration.Configurator`.
-
-Documentation Enhancements
---------------------------
-
-- This documentation has been published in `printed form
-  <http://bfg.repoze.org/book>`_ under the title *The repoze.bfg Web
-  Application Framework, Version 1.2*.  It was reworked and
-  restructured extensively for this publication.  `Show your support
-  for BFG by buying a copy! <http://bfg.repoze.org/book>`_.
-
-- The documentation now uses the "request-only" view calling
-  convention in most examples (as opposed to the ``context, request``
-  convention).  This is a documentation-only change; the ``context,
-  request`` convention is also supported and documented, and will be
-  "forever".
-
-- :mod:`repoze.bfg.configuration` API documentation has been added.
-
-- A narrative documentation chapter entitled "Creating Your First
-  ``repoze.bfg`` Application" has been added.  This chapter details
-  usage of the new :class:`repoze.bfg.configuration.Configurator`
-  class, and demonstrates a simplified "imperative-mode"
-  configuration; doing :mod:`repoze.bfg` application configuration
-  imperatively was previously much more difficult.
-
-- The "ZCML Hooks" chapter has been renamed to "Hooks"
-  (:ref:`hooks_chapter`); it documents how to override hooks now via
-  imperative configuration and ZCML.
-
-- The explanation about how to supply an alternate "response factory"
-  has been removed from the "Hooks" chapter.  This feature may be
-  removed in a later release (it still works now, it's just not
-  documented).
-
-- Add a section entitled "Test Set Up and Tear Down" to the
-  unittesting chapter (:ref:`unittesting_chapter`).
-
-- Remove explanation of changing the request type in a new request
-  event subscriber in the "Events" narrative documentation chapter, as
-  other predicates are now usually an easier way to get this done.
-
-- Added "Thread Locals" narrative chapter to documentation, and added
-  a API chapter documenting the :mod:`repoze.bfg.threadlocals` module.
-
-- Added a "Special Exceptions" section to the "Views" narrative
-  documentation chapter explaining the effect of raising
-  :exc:`repoze.bfg.exceptions.NotFound` and
-  :exc:`repoze.bfg.exceptions.Forbidden` from within view code.
-
-- Add a narrative documentation chapter named :ref:`zca_chapter`.
-
-- Created new top-level documentation section named
-  :ref:`zcml_directives`.  This section contains detailed ZCML
-  directive information, some of which was removed from various
-  narrative chapters.
-
-Licensing Changes
------------------
-
-- The publication of the documentation as a printed book required an
-  explicit documentation licensing change: the documentation (the
-  content in the "docs" directory) is now offered under the `Creative
-  Commons Attribution-Noncommercial-Share Alike 3.0 United States
-  License <http://creativecommons.org/licenses/by-nc-sa/3.0/us/>`_.
-  This is only a documentation licensing change: the :mod:`repoze.bfg`
-  software itself (everything except the contents of the "docs"
-  directory) is still offered under `a BSD-like license
-  <http://repoze.org/license.html>`_.
-
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.
diff --git a/docs/zcml/.#include.rst b/docs/zcml/.#include.rst
deleted file mode 120000
index 0e27a9e93..000000000
--- a/docs/zcml/.#include.rst
+++ /dev/null
@@ -1 +0,0 @@
-chrism@thinko.17096:1287927276
\ No newline at end of file