Remove incorrect docs from hybrid chapter.

Organize changelog of 1.1a1 into categories.

2 files changed, 174 insertions, 146 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index d4bb55f4b..281b3e4cb 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,3 +1,14 @@
+Next release
+============
+
+Documentation
+-------------
+
+- Fix "Hybrid" narrative chapter: stop claiming that ``<view>``
+  statements that mention a route_name need to come afer (in XML
+  order) the ``<route>`` statement which creates the route.  This
+  hasn't been true since 1.1a1.
+
 1.1b1 (2009-11-01)
 ==================
 
@@ -713,6 +724,9 @@ Backwards Incompatibilities
 1.1a2 (2009-09-14)
 ==================
 
+Features
+--------
+
 - A ZCML ``view`` directive (and the associated ``bfg_view``
   decorator) can now accept an "attr" value.  If an "attr" value is
   supplied, it is considered a method named of the view object to be
@@ -731,65 +745,52 @@ Backwards Incompatibilities
 1.1a1 (2009-09-06)
 ==================
 
-- The ``registry_manager`` backwards compatibility alias importable
-  from "repoze.bfg.registry", deprecated since repoze.bfg 0.9 has been
-  removed.  If you are tring 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 ``IViewPermissionFactory`` interface has been removed.  This was
-  never an API.
-
-- 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.
+Bug Fixes
+---------
 
-- ``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::
+- "tests" module removed from the bfg_alchemy paster template; these
+  tests didn't work.
 
-   <utility
-     provides="repoze.bfg.interfaces.ISecurityPolicy"
-     factory="repoze.bfg.security.RemoteUserInheritingACLSecurityPolicy"
-     />
+- Bugfix: the ``discriminator`` for the ZCML "route" directive was
+  incorrect.  It was possible to register two routes that collided
+  without the system spitting out a ConfigurationConflictError at
+  startup time.
 
-   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::
+Features
+--------
 
-     <remoteuserauthenticationpolicy/>
-     <aclauthorizationpolicy/>
+- Feature addition: view predicates.  These are exposed as the
+  ``request_method``, ``request_param``, and ``containment``
+  attributes of a ZCML ``view`` declaration, or the respective
+  arguments to a ``@bfg_view`` decorator.  View predicates can be used
+  to register a view for a more precise set of environment parameters
+  than was previously possible.  For example, you can register two
+  views with the same ``name`` with different ``request_param``
+  attributes.  If the ``request.params`` dict contains 'foo'
+  (request_param="foo"), one view might be called; if it contains
+  'bar' (request_param="bar"), another view might be called.
+  ``request_param`` can also name a key/value pair ala ``foo=123``.
+  This will match only when the ``foo`` key is in the request.params
+  dict and it has the value '123'.  This particular example makes it
+  possible to write separate view functions for different form
+  submissions.  The other predicates, ``containment`` and
+  ``request_method`` work similarly.  ``containment`` is a view
+  predicate that will match only when the context's graph lineage has
+  an object possessing a particular class or interface, for example.
+  ``request_method`` is a view predicate that will match when the HTTP
+  ``REQUEST_METHOD`` equals some string (eg. 'POST').
 
-   This is just an example.  See the "Security" chapter of the
-   repoze.bfg documentation for more information about configuring
-   security policies.
+- The ``@bfg_view`` decorator now accepts three additional arguments:
+  ``request_method``, ``request_param``, and ``containment``.
+  ``request_method`` is used when you'd like the view to match only a
+  request with a particular HTTP ``REQUEST_METHOD``; a string naming
+  the ``REQUEST_METHOD`` can also be supplied as ``request_type`` for
+  backwards compatibility.  ``request_param`` is used when you'd like
+  a view to match only a request that contains a particular
+  ``request.params`` key (with or without a value).  ``containment``
+  is used when you'd like to match a request that has a context that
+  has some class or interface in its graph lineage.  These are
+  collectively known as "view predicates".
 
 - The ``route`` ZCML directive now honors ``view_request_method``,
   ``view_request_param`` and ``view_containment`` attributes, which
@@ -806,13 +807,28 @@ Backwards Incompatibilities
   value.  For example, ``request_param="foo=123"`` means that the foo
   key must have a value of ``123`` for the view to "match".
 
-- Bugfix: the ``discriminator`` for the ZCML "route" directive was
-  incorrect.  It was possible to register two routes that collided
-  without the system spitting out a ConfigurationConflictError at
-  startup time.
+- 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 ``static`` ZCML directive now uses a custom root factory when
-  constructing a route.
+- Added ``static`` ZCML directive which registers a route for a view
+  that serves up files in a directory.  See the "Views" narrative
+  documentation chapter's "Serving Static Resources Using a ZCML
+  Directive" section for more information.
+
+- The ``repoze.bfg.view.static`` class now accepts a string as its
+  first argument ("root_dir") that represents a package-relative name
+  e.g. ``somepackage:foo/bar/static``.  This is now the preferred
+  mechanism for spelling package-relative static paths using this
+  class.  A ``package_name`` keyword argument has been left around for
+  backwards compatibility.  If it is supplied, it will be honored.
+
+- The API ``repoze.bfg.testing.registerView`` now takes a
+  ``permission`` argument.  Use this instead of using
+  ``repoze.bfg.testing.registerViewPermission``.
 
 - The ordering of route declarations vs. the ordering of view
   declarations that use a "route_name" in ZCML no longer matters.
@@ -820,17 +836,42 @@ Backwards Incompatibilities
   that had not yet been defined in ZCML (order-wise) within a "view"
   declaration.
 
-- The ``@bfg_view`` decorator now accepts three additional arguments:
-  ``request_method``, ``request_param``, and ``containment``.
-  ``request_method`` is used when you'd like the view to match only a
-  request with a particular HTTP ``REQUEST_METHOD``; a string naming
-  the ``REQUEST_METHOD`` can also be supplied as ``request_type`` for
-  backwards compatibility.  ``request_param`` is used when you'd like
-  a view to match only a request that contains a particular
-  ``request.params`` key (with or without a value).  ``containment``
-  is used when you'd like to match a request that has a context that
-  has some class or interface in its graph lineage.  These are
-  collectively known as "view predicates".
+- The repoze.bfg router now catches both
+  ``repoze.bfg.security.Unauthorized`` and
+  ``repoze.bfg.view.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.
+
+Internal
+--------
+
+- Change urldispatch internals: Route object is now constructed using
+  a path, a name, and a factory instead of a name, a matcher, a
+  generator, and a factory.
+
+- Move (non-API) default_view, default_forbidden_view, and
+  default_notfound_view functions into the ``repoze.bfg.view`` module
+  (moved from ``repoze.bfg.router``).
+
+- Removed ViewPermissionFactory from ``repoze.bfg.security``.  View
+  permission checking is now done by registering and looking up an
+  ISecuredView.
+
+- The ``static`` ZCML directive now uses a custom root factory when
+  constructing a route.
+
+Documentation
+-------------
+
+- Request-only-convention examples in the "Views" narrative
+  documentation were broken.
+
+- Fixed documentation bugs related to forget and remember in security API
+  docs.
+
+- Fixed documentation for ``repoze.bfg.view.static`` (in narrative
+  ``Views`` chapter).
 
 - The interface ``IRequestFactories`` was removed from the
   repoze.bfg.interfaces module.  This interface was never an API.
@@ -852,94 +893,85 @@ Backwards Incompatibilities
   structure named ``DEFAULT_REQUEST_FACTORIES`` have been removed from
   the ``repoze.bfg.request`` module.  These were never APIs.
 
-- Feature addition: view predicates.  These are exposed as the
-  ``request_method``, ``request_param``, and ``containment``
-  attributes of a ZCML ``view`` declaration, or the respective
-  arguments to a ``@bfg_view`` decorator.  View predicates can be used
-  to register a view for a more precise set of environment parameters
-  than was previously possible.  For example, you can register two
-  views with the same ``name`` with different ``request_param``
-  attributes.  If the ``request.params`` dict contains 'foo'
-  (request_param="foo"), one view might be called; if it contains
-  'bar' (request_param="bar"), another view might be called.
-  ``request_param`` can also name a key/value pair ala ``foo=123``.
-  This will match only when the ``foo`` key is in the request.params
-  dict and it has the value '123'.  This particular example makes it
-  possible to write separate view functions for different form
-  submissions.  The other predicates, ``containment`` and
-  ``request_method`` work similarly.  ``containment`` is a view
-  predicate that will match only when the context's graph lineage has
-  an object possessing a particular class or interface, for example.
-  ``request_method`` is a view predicate that will match when the HTTP
-  ``REQUEST_METHOD`` equals some string (eg. 'POST').
-
-- The repoze.bfg router now catches both
-  ``repoze.bfg.security.Unauthorized`` and
-  ``repoze.bfg.view.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.
+- The ``IViewPermissionFactory`` interface has been removed.  This was
+  never an API.
 
-- 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.
+Deprecations
+------------
 
 - The API ``repoze.bfg.testing.registerViewPermission`` has been
   deprecated.
 
-- The API ``repoze.bfg.testing.registerView`` now takes a
-  ``permission`` argument.  Use this instead of using
-  ``repoze.bfg.testing.registerViewPermission``.
-
-- Removed ViewPermissionFactory from ``repoze.bfg.security``.  View
-  permission checking is now done by registering and looking up an
-  ISecuredView.
+Backwards Incompatibilities
+---------------------------
 
 - Views registered without the help of the ZCML ``view`` directive are
   now responsible for performing their own authorization checking.
 
-- The ``repoze.bfg.view.static`` class now accepts a string as its
-  first argument ("root_dir") that represents a package-relative name
-  e.g. ``somepackage:foo/bar/static``.  This is now the preferred
-  mechanism for spelling package-relative static paths using this
-  class.  A ``package_name`` keyword argument has been left around for
-  backwards compatibility.  If it is supplied, it will be honored.
+- The ``registry_manager`` backwards compatibility alias importable
+  from "repoze.bfg.registry", deprecated since repoze.bfg 0.9 has been
+  removed.  If you are tring 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.
 
-- Fixed documentation for ``repoze.bfg.view.static`` (in narrative
-  ``Views`` chapter).
+- 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``::
 
-- Added ``static`` ZCML directive which registers a route for a view
-  that serves up files in a directory.  See the "Views" narrative
-  documentation chapter's "Serving Static Resources Using a ZCML
-  Directive" section for more information.
+   <utility provides="repoze.bfg.interfaces.INotFoundAppFactory"
+            component="helloworld.factories.notfound_app_factory"/>
 
-- "tests" module removed from the bfg_alchemy paster template; these
-  tests didn't work.
+  Replace it with something like::
 
-- Move (non-API) default_view, default_forbidden_view, and
-  default_notfound_view functions into the ``repoze.bfg.view`` module
-  (moved from ``repoze.bfg.router``).
+   <notfound 
+       view="helloworld.views.notfound_view"/>
 
-- Request-only-convention examples in the "Views" narrative
-  documentation were broken.
+  See "Changing the Not Found View" in the "Hooks" chapter of the
+  documentation for more information.
 
-- Change urldispatch internals: Route object is now constructed using
-  a path, a name, and a factory instead of a name, a matcher, a
-  generator, and a factory.
+- 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``::
 
-- 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.
+   <utility provides="repoze.bfg.interfaces.IUnauthorizedAppFactory"
+            component="helloworld.factories.unauthorized_app_factory"/>
 
-- Fixed documentation bugs related to forget and remember in security API
-  docs.
+  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.
+
+- 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.
 
 1.0.1 (2009-07-22)
 ==================
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index 4ff5df493..8a83cd94e 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -197,10 +197,6 @@ It's :term:`view name` will be looked for during traversal.  So if our
 URL is "http://example.com/one/two/a/another", the ``.views.another``
 view will be called.
 
-A ``<route>`` declaration *must* precede (in XML order) any ``<view>``
-declaration which names it as a ``route_name``.  If it does not, at
-application startup time a ``ConfigurationError`` will be raised.
-
 Route Factories
 ---------------