Here's a first crack at documentation for the new HTML template type
that will be available in the next Quixote release.  I've left out that
part that explains the new, prefered plain text template syntax. E.g.:

    def foo [plain] (request):
        'Hello, this is a plain text template named foo.'

I would like to get a new Quixote release out and documentation is the
major piece missing.


HTML templates
--------------

Since PTL is usually used to generate HTML documents, a ``[html]``
template type has been provided to make generating HTML easier.  When
generating HTML, it is extremely difficult to correctly escape special
characters.  The PTL solution to this problem is to use a separate data
type for data that does not need to be escaped.  Any data that is not of
this type will be converted to this type after escaping any special
characters.

In PTL, the separate data type is ``htmltext``.  The function
``htmlescape()`` is used to escape data and it returns a ``htmltext``
instance.   It does nothing if the argument is already ``htmltext``.
Both ``htmltext`` and ``htmlescape`` are available in the global
namespace of PTL modules.

If a template function is declared ``[html]`` instead of ``[text]`` then
two things happen.  First, all literal strings in the function become
instances of ``htmltext`` instead of ``str``.  Second, the values of
expressions are passed through ``htmlescape()`` instead of ``str()``.

``htmltext`` type is like the ``str`` type except that operations
combining strings and ``htmltext`` instances will result in the string
being passed through ``htmlescape()``.  For example::

    >>> from quixote.html import htmltext
    >>> htmltext('a') + 'b'
    
    >>> 'a' + htmltext('b')
    
    >>> htmltext('a%s') % 'b'
    
    >>> response = 'green eggs & ham'
    >>> htmltext('The response was: ') + response
    
    >>> htmltext('The response was: %s') % response
    

Note that calling ``str()`` strips the ``htmltext`` type and should be
avoided since it usually results in characters being escaped more than
once.  While ``htmltext`` behaves much like a regular string, it is
sometimes necessary to insert a ``str()`` inside a template in order to
obtain a genuine string.  For example, the ``re`` module requires
genuine strings.  We have found that explict calls to ``str()`` can
often be avoided by splitting some code out of the template into a
helper function.

It is also recommended that the ``htmltext`` constructor be used as
sparingly as possible.  The reason is that when using the htmltext
feature of PTL, explict calls to `htmltext`` become the most likely
source of cross-site scripting holes.  Calling ``htmltext`` is like
saying "I am absolutely sure this piece of data cannot contain malicious
HTML code injected by a user.  Don't escape HTML special characters
because I want them."