- In the past, during traversal, the ModelGraphTraverser (the

    default traverser) always passed each URL path segment to any
    ``__getitem__`` method of a model object as a byte string (a
    ``str`` object).  Now, by default the ModelGraphTraverser attempts
    to decode the path segment to Unicode (a ``unicode`` object) using
    the UTF-8 encoding before passing it to the ``__getitem__`` method
    of a model object.  This makes it possible for model objects to be
    dumber in ``__getitem__`` when trying to resolve a subobject, as
    model objects themselves no longer need to try to divine whether
    or not to try to decode the path segment passed by the
    traverser.

    Note that since 0.5.4, URLs generated by repoze.bfg's
    ``model_url`` API will contain UTF-8 encoded path segments as
    necessary, so any URL generated by BFG itself will be decodeable
    by the traverser.  If another application generates URLs to a BFG
    application, to be resolved successully, it should generate the
    URL with UTF-8 encoded path segments to be successfully resolved.
    The decoder is not at all magical: if a non-UTF-8-decodeable path
    segment (e.g. one encoded using UTF-16 or some other insanity) is
    passed in the URL, BFG will raise a ``TypeError`` with a message
    indicating it could not decode the path segment.

    To turn on the older behavior, where path segments were not
    decoded to Unicode before being passed to model object
    ``__getitem__`` by the traverser, and were passed as a raw byte
    string, set the ``unicode_path_segments`` configuration setting to
    a false value in your BFG application's section of the paste .ini
    file, for example::

      unicode_path_segments = False

    Or start the application using the ``BFG_UNICODE_PATH_SEGMENT``
    envvar set to a false value::

      BFG_UNICODE_PATH_SEGMENTS=0

1 files changed, 30 insertions, 20 deletions

diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 3fe3457c0..69dc98e25 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -19,26 +19,36 @@ setting names documented in this chapter are reserved for
 :mod:`repoze.bfg` use.  You should not use them to indicate
 application-specific configuration settings.
 
-+-----------------------------+--------------------------+-------------------------------------+
-| Environment Variable Name   | Config File Setting Name |       Further Information           |
-+=============================+==========================+=====================================+
-| ``BFG_RELOAD_TEMPLATES``    |  ``reload_templates``    |  Reload templates without restart   |
-|                             |                          |  when true                          |
-|                             |                          |  See also:                          |
-|                             |                          |  :ref:`reload_templates_section`    |
-+-----------------------------+--------------------------+-------------------------------------+
-| ``BFG_DEBUG_AUTHORIZATION`` |  ``debug_authorization`` |  Print view authorization failure & |
-|                             |                          |  success info to stderr when true   |
-|                             |                          |  See also:                          |
-|                             |                          |  :ref:`debug_authorization_section` |
-+-----------------------------+--------------------------+-------------------------------------+
-| ``BFG_DEBUG_NOTFOUND``      |  ``debug_notfound``      |  Print view-related NotFound debug  |
-|                             |                          |  messages to stderr when true       |
-|                             |                          |  See also:                          |
-|                             |                          |  :ref:`debug_notfound_section`      |
-+-----------------------------+--------------------------+-------------------------------------+
-| ``BFG_DEBUG_ALL``           |  ``debug_all``           |  Turns all debug_* settings on.     |
-+-----------------------------+--------------------------+-------------------------------------+
++---------------------------------+-----------------------------+----------------------------------------+
+| Environment Variable Name       | Config File Setting Name    |       Further Information              |
++=================================+=============================+========================================+
+| ``BFG_RELOAD_TEMPLATES``        |  ``reload_templates``       |  Reload templates without restart      |
+|                                 |                             |  when true                             |
+|                                 |                             |  See also:                             |
+|                                 |                             |  :ref:`reload_templates_section`       |
++---------------------------------+-----------------------------+----------------------------------------+
+| ``BFG_DEBUG_AUTHORIZATION``     |  ``debug_authorization``    |  Print view authorization failure &    |
+|                                 |                             |  success info to stderr when true      |
+|                                 |                             |  See also:                             |
+|                                 |                             |  :ref:`debug_authorization_section`    | 
++---------------------------------+-----------------------------+----------------------------------------+
+| ``BFG_DEBUG_NOTFOUND``          |  ``debug_notfound``         |  Print view-related NotFound debug     |
+|                                 |                             |  messages to stderr when true          |
+|                                 |                             |  See also:                             |
+|                                 |                             |  :ref:`debug_notfound_section`         |
++---------------------------------+-----------------------------+----------------------------------------+
+| ``BFG_DEBUG_ALL``               |  ``debug_all``              |  Turns all debug_* settings on.        |
++---------------------------------+-----------------------------+----------------------------------------+
+| ``BFG_UNICODE_PATH_SEGMENTS``   |  ``unicode_path_segments``  |  Defaults to ``true``.  When ``true``, |
+|                                 |                             |  URL path segment names will be passed |
+|                                 |                             |  to model object ``__getitem__``       |
+|                                 |                             |  methods by the BFG model graph        |
+|                                 |                             |  traverser as ``unicode`` types rather |
+|                                 |                             |  than as ``str`` types; path segments  |
+|                                 |                             |  will be assumed to be UTF-8 encoded.  |
+|                                 |                             |  When ``false``, pass path segments    |
+|                                 |                             |  as undecoded ``str`` types.           |
++---------------------------------+-----------------------------+----------------------------------------+
 
 Examples
 --------