# HG changeset patch
# User cmlenz
# Date 1174582809 0
# Node ID 691dd56c0dd0017760e6c4caa185811b591ec885
# Parent  dcba5b97b4207ad79c6855ce31af1b5a10e4405c
Updated docs for code blocks and changed error handling.

diff --git a/doc/text-templates.txt b/doc/text-templates.txt
--- a/doc/text-templates.txt
+++ b/doc/text-templates.txt
@@ -92,23 +92,38 @@
   >>> print tmpl.generate(dict={'foo': 'bar'})
   bar
 
-Another difference is that you can access variables that are not defined, and
-won't get a ``NameError`` exception::
-
-  >>> from genshi.template import TextTemplate
-  >>> tmpl = TextTemplate('${doh}')
-  >>> print tmpl.generate()
-  <BLANKLINE>
+Because there are two ways to access either attributes or items, expressions
+do not raise the standard ``AttributeError`` or ``IndexError`` exceptions, but
+rather an exception of the type ``UndefinedError``. The same kind of error is
+raised when you try to access a top-level variable that is not in the context
+data.
 
-You **will** however get a ``NameError`` if you try to call an undefined 
-variable, or do anything else with it, such as accessing its attributes. If you
-need to know whether a variable is defined, you can check its type against the
-``Undefined`` class, for example in an `#if`_ directive::
+Built-in Functions & Types
+==========================
 
-  >>> from genshi.template import TextTemplate
-  >>> tmpl = TextTemplate('${type(doh) is Undefined}')
-  >>> print tmpl.generate()
-  True
+The following functions and types are available by default in template code, in
+addition to the standard built-ins that are available to all Python code.
+
+``defined(name)``
+-----------------
+ 
+This function determines whether a variable of the specified name exists in
+the context data, and returns ``True`` if it does.
+ 
+``value_of(name, default=None)``
+--------------------------------
+
+This function returns the value of the variable with the specified name if
+such a variable is defined, and returns the value of the ``default``
+parameter if no such variable is defined.
+
+``Markup(text)``
+----------------
+
+The ``Markup`` type marks a given string as being safe for inclusion in markup,
+meaning it will *not* be escaped in the serialization stage. Use this with care,
+as not escaping a user-provided string may allow malicious users to open your
+web site to cross-site scripting attacks.
 
 
 .. _`directives`:
diff --git a/doc/xml-templates.txt b/doc/xml-templates.txt
--- a/doc/xml-templates.txt
+++ b/doc/xml-templates.txt
@@ -65,9 +65,9 @@
 
 .. _`expressions`:
 
---------------------
-Template Expressions
---------------------
+------------------------------------
+Template Expressions and Code Blocks
+------------------------------------
 
 Python_ expressions can be used in text and attribute values. An expression is
 substituted with the result of its evaluation against the template data.
@@ -94,23 +94,74 @@
   >>> print tmpl.generate(dict={'foo': 'bar'})
   <em>bar</em>
 
-Another difference is that you can access variables that are not defined, and
-won't get a ``NameError`` exception::
-
-  >>> from genshi.template import TextTemplate
-  >>> tmpl = TextTemplate('${doh}')
-  >>> print tmpl.generate()
-  <BLANKLINE>
+Because there are two ways to access either attributes or items, expressions
+do not raise the standard ``AttributeError`` or ``IndexError`` exceptions, but
+rather an exception of the type ``UndefinedError``. The same kind of error is
+raised when you try to access a top-level variable that is not in the context
+data.
 
-You **will** however get a ``NameError`` if you try to call an undefined 
-variable, or do anything else with it, such as accessing its attributes. If you
-need to know whether a variable is defined, you can check its type against the
-``Undefined`` class, for example in a `py:if`_ directive::
 
-  >>> from genshi.template import TextTemplate
-  >>> tmpl = TextTemplate('${type(doh) is Undefined}')
-  >>> print tmpl.generate()
-  True
+.. _`code blocks`:
+
+Code Blocks
+===========
+
+XML templates also support full Python code blocks using the ``<?python ?>``
+processing instruction::
+
+  <div>
+    <?python
+        from genshi.builder import tag
+        def greeting(name):
+            return tag.b('Hello, %s!' % name') ?>
+    ${greeting('world')}
+  </div>
+
+This will produce the following output::
+
+  <div>
+    <b>Hello, world!</b>
+  </div>
+
+Code blocks can import modules, define classes and functions, and basically do
+anything you can do in normal Python code. What code blocks can *not* do is to
+produce content that is included directly in the generated page.
+
+.. note:: Using the ``print`` statement will print to the standard output
+          stream, just as it does for other Python code in your application.
+
+This feature is not supposed to encourage mixing application code into
+templates, which is generally considered bad design. If you're using many code
+blocks, that me be a sign that you should move such code into separate Python
+modules.
+
+
+Built-in Functions & Types
+==========================
+
+The following functions and types are available by default in template code, in
+addition to the standard built-ins that are available to all Python code.
+
+``defined(name)``
+-----------------
+ 
+This function determines whether a variable of the specified name exists in
+the context data, and returns ``True`` if it does.
+ 
+``value_of(name, default=None)``
+--------------------------------
+
+This function returns the value of the variable with the specified name if
+such a variable is defined, and returns the value of the ``default``
+parameter if no such variable is defined.
+
+``Markup(text)``
+----------------
+
+The ``Markup`` type marks a given string as being safe for inclusion in markup,
+meaning it will *not* be escaped in the serialization stage. Use this with care,
+as not escaping a user-provided string may allow malicious users to open your
+web site to cross-site scripting attacks.
 
 
 .. _`directives`: