copy from UPGRADE.txt
copy to doc/upgrade.txt
--- a/UPGRADE.txt
+++ b/doc/upgrade.txt
@@ -1,19 +1,35 @@
 Upgrading Genshi
 ================
 
+
+.. contents:: Contents
+   :depth: 2
+.. sectnum::
+
+
 Upgrading from Genshi 0.4.x to 0.5.x
 ------------------------------------
 
-Genshi 0.5 introduces a new, alternative syntax for text templates, which is
-more flexible and powerful compared to the old syntax. For backwards
-compatibility, this new syntax is not used by default, though it will be in
-a future version. It is recommended that you migrate to using this new syntax.
-To do so, simply rename any references in your code to `TextTemplate` to
-`NewTextTemplate`. To explicitly use the old syntax, use `OldTextTemplate`
-instead, so that you can be sure you'll be using the same language when the
+Genshi 0.5 introduces a new, alternative syntax for text templates,
+which is more flexible and powerful compared to the old syntax. For
+backwards compatibility, this new syntax is not used by default,
+though it will be in a future version. It is recommended that you
+migrate to using this new syntax. To do so, simply rename any
+references in your code to ``TextTemplate`` to ``NewTextTemplate``. To
+explicitly use the old syntax, use ``OldTextTemplate`` instead, so
+that you can be sure you'll be using the same language when the
 default in Genshi is changed (at least until the old implementation is
 completely removed).
 
+The default error handling mode has been changed to "strict". This
+means that accessing variables not defined in the template data will
+now generate an immediate exception, as will accessing object
+attributes or dictionary keys that don't exist. If your templates rely
+on the old lenient behavior, you can configure Genshi to use that
+instead. See the documentation for details on how to do that. But be
+warned that lenient error handling may be removed completely in a
+future release.
+
 
 Upgrading from Genshi 0.3.x to 0.4.x
 ------------------------------------
@@ -21,19 +37,20 @@
 The modules ``genshi.filters`` and ``genshi.template`` have been
 refactored into packages containing multiple modules. While code using
 the regular APIs should continue to work without problems, you should
-make sure to remove any leftover traces of the ``template.py`` file on
-the installation path. This is not necessary when Genshi was installed
-as a Python egg.
+make sure to remove any leftover traces of the files ``filters.py``
+and ``template.py`` in the ``genshi`` package on the installation
+path (including the corresponding ``.pyc`` files). This is not
+necessary when Genshi was installed as a Python egg.
 
 Results of evaluating template expressions are no longer implicitly
 called if they are callable. If you have been using that feature, you
 will need to add the parenthesis to actually call the function.
 
-Instances of `genshi.core.Attrs` are now immutable. Filters
+Instances of ``genshi.core.Attrs`` are now immutable. Filters
 manipulating the attributes in a stream may need to be updated. Also,
-the `Attrs` class no longer automatically wraps all attribute names
-in `QName` objects, so users of the `Attrs` class need to do this
-themselves. See the documentation of the `Attrs` class for more
+the ``Attrs`` class no longer automatically wraps all attribute names
+in ``QName`` objects, so users of the ``Attrs`` class need to do this
+themselves. See the documentation of the ``Attrs`` class for more
 information.
 
 
@@ -44,22 +61,22 @@
 name change means that you will have to adjust your import statements
 and the namespace URI of XML templates, among other things:
 
- * The package name was changed from "markup" to "genshi". Please
-   adjust any import statements referring to the old package name.
- * The namespace URI for directives in Genshi XML templates has changed
-   from http://markup.edgewall.org/ to http://genshi.edgewall.org/.
-   Please update the xmlns:py declaration in your template files
-   accordingly.
+* The package name was changed from "markup" to "genshi". Please
+  adjust any import statements referring to the old package name.
+* The namespace URI for directives in Genshi XML templates has changed
+  from ``http://markup.edgewall.org/`` to
+  ``http://genshi.edgewall.org/``. Please update the ``xmlns:py``
+  declaration in your template files accordingly.
 
 Furthermore, due to the inclusion of a text-based template language,
-the class:
+the class::
 
-  `markup.template.Template`
+  markup.template.Template
 
-has been renamed to:
+has been renamed to::
 
-  `genshi.template.MarkupTemplate`
+  genshi.template.MarkupTemplate
 
 If you've been using the Template class directly, you'll need to
-update your code (a simple find/replace should do--the API itself
+update your code (a simple find/replace should do—the API itself
 did not change).