Revert "Delete the "old" docs directory to make way for fancy smancy sphinx"docs

This reverts commit 5dc95cfcd015628665d3672e56d0551943b5db6b.

33 files changed, 6349 insertions, 0 deletions

diff --git a/docs/users_guide_2_src/01_introduction.txt b/docs/users_guide_2_src/01_introduction.txt
new file mode 100755
index 0000000..34beeb6
--- /dev/null
+++ b/docs/users_guide_2_src/01_introduction.txt
@@ -0,0 +1,291 @@
+Introduction
+============
+
+..
+    :label: intro
+
+Who should read this Guide?
+---------------------------
+
+..
+    :label: intro.whoShouldRead
+
+This Users' Guide is for Python programmers.  Part I is a tutorial/reference
+and should be read by everybody.  Part II is a cookbook of of techniques for
+using Cheetah with various web frameworks and various non-HTML output formats,
+plus some technical appendices.  The PDF version of this Guide is distributed
+as two files so you can print Part I to read offline without having to print a
+lot of pages from Part II that don't apply to you.
+
+What is Cheetah?
+----------------
+
+..
+    :label: intro.whatIs
+
+Cheetah is a template engine for Python.  A template engine is like Python's
+``%`` operator for strings: it has fixed parts which are output verbatim, and
+*placeholders* which are replaced by their values::
+
+    # Python's "%" operator (not Cheetah)
+    >>> "The king is a %(noun)s!" % {"noun": "fink"}
+    'The king is a fink!"
+
+Templates are useful for form letters, dynamic web pages, customized source
+code or SQL, and innumerable other tasks.  Cheetah is like a super-powered
+``%`` operator, but it also has many other features needed in real-world
+templating situations.
+
+Viewed another way, Cheetah is an alternate source format for Python modules,
+one that's friendlier for large chunks of text.  Compiled templates are
+ordinary Python modules which can be imported.  Cheetah is one of Python's
+oldest template engines and perhaps the most widely used.  This is mainly due
+to its speed (hence the name Cheetah), stability, and suitability for many
+output formats.  Cheetah has been used in production environments since 2001
+(0.9.9a1), and changes are committed conservatively, so even the CVS version is
+usually more bug-free than the previous release.
+
+Cheetah's syntax uses ``$`` before placeholders and a ``#``
+before control structures (directives), although these characters can be
+changed.  This differs from Python's other template systems which generally use
+XML tags (Kid and Tal) or a function syntax (PTL and QPY).  The difference
+allows Cheetah to be more suitable for a variety of output formats, and even
+users of the other systems often use Cheetah for non-HTML output such as
+text, Python source code, or SQL.  Cheetah's syntax and behavior was
+inspired most directly by Velocity, a Java template engine.  In PHP, Smarty is
+Cheetah's closest equivalent.  Cheetah templates tend to be function-driven:
+define a method with ``#def``, and call it via a placeholder with arguments.
+Cheetah also has PSP-style tags (``<% %>``) and ``#include``, which will be
+familiar to people coming from ASP/JSP/PHP.  However, we'll argue that these
+should be used sparingly, since there are other constructs which are more
+readable.
+
+
+Cheetah:
+
+* generates HTML, SGML, XML, SQL, Postscript, form email, LaTeX, or any
+  other text-based format.  It has also been used to produce Python, Java
+  and PHP source code.
+    
+* cleanly separates content, graphic design, and program code.  This leads
+  to highly modular, flexible, and reusable site architectures; faster
+  development time; and HTML and program code that is easier to understand
+  and maintain. It is particularly well suited for team efforts.
+    
+* blends the power and flexibility of Python with a simple template language
+  that non*programmers can understand.
+    
+* gives template writers full access in their templates to any Python data
+  structure, module, function, object, or method.
+    
+* makes code reuse easy by providing an object-oriented interface to
+  templates that is accessible from Python code or other Cheetah templates.
+  One template can subclass another and selectively reimplement sections of
+  it.  A compiled template {\em is} a Python class, so it can subclass a
+  pure Python class and vice*versa.
+    
+* provides a simple yet powerful caching mechanism 
+
+Here's a simple example of a Cheetah template::
+
+    <HTML>
+    <HEAD><TITLE>$title</TITLE></HEAD>
+    <BODY>
+
+    <TABLE>
+    #for client in clients
+    <TR>
+    <TD>$client.surname, $client.firstname</TD>
+    <TD><A HREF="mailto:$client.email">$client.email</A></TD>
+    </TR>
+    #end for
+    </TABLE>
+
+    </BODY>
+    </HTML>
+
+* has a lot of features but most of them are optional.  Cheetah is easy to use
+  in simple cases, and scales well to complex cases.  Most of Cheetah's
+  features were added due to demonstrated needs in production environments
+  where Cheetah was already runing.  
+
+Cheetah is distributed under a BSD-style open-source license.  See appendix E
+(E_license.txt) for details.  Cheetah exists thanks to the help of many
+open-source volunteers (http://cheetahtemplate.sourceforge.net/credits.html).
+
+
+
+What is the philosophy behind Cheetah?
+--------------------------------------
+
+..
+    :label: intro.philosophy
+
+Cheetah's design was guided by these principles:
+
+* Python for the back end (business logic), Cheetah for the front end
+  (presentation format).  Cheetah was designed to complement Python, not
+  replace it.
+    
+* Cheetah's core syntax should be easy for non-programmers to learn.
+         
+* Cheetah should make code reuse easy by providing an object-oriented
+  interface to templates that is accessible from Python code or other
+  Cheetah templates.
+    
+* Python objects, functions, and other data structures should be fully
+  accessible in Cheetah.
+      
+* Cheetah should provide flow control and error handling.  Logic
+  that belongs in the front end shouldn't be relegated to the 
+  back end simply because it's complex.
+
+* It should be easy to {\bf separate} content, graphic design, and program
+  code, but also easy to {\bf integrate} them.
+
+  A clean separation makes it easier for a team of content writers,
+  HTML/graphic designers, and programmers to work together without stepping
+  on each other's toes and polluting each other's work.  The HTML framework
+  and the content it contains are two separate things, and analytical
+  calculations (program code) is a third thing.  Each team member should be
+  able to concentrate on their specialty and to implement their changes
+  without having to go through one of the others (i.e., the dreaded
+  "webmaster bottleneck").
+  
+  While it should be easy to develop content, graphics and program
+  code separately, it should be easy to integrate them together into a 
+  website.  In particular, it should be easy:
+
+  - for {\bf programmers} to create reusable components and functions
+    that are accessible and understandable to designers.
+  - for {\bf designers} to mark out placeholders for content and 
+    dynamic components in their templates.
+  - for {\bf designers} to soft-code aspects of their design that are
+    either repeated in several places or are subject to change.
+  - for {\bf designers} to reuse and extend existing templates and thus
+    minimize duplication of effort and code.
+  - and, of course, for {\bf content writers} to use the templates that
+    designers have created.
+
+* Features are added only to support a demonstrated need in production
+  applications, and generally only if the feature is useful for a wide variety
+  of situations and output formats.  This prevents Cheetah from accumulating
+  lots of esoteric features which are used only rarely.  
+
+
+Why Cheetah doesn't use HTML-style tags
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+..
+    :label: intro.htmlStyleTags
+
+Cheetah does not use HTML/XML-style tags for flow control, unlike some other
+Python template engines, for the following reasons:
+
+* Cheetah is not limited to HTML,
+* HTML-style tags are hard to distinguish from real HTML tags,
+* HTML-style tags are not visible in rendered HTML when something goes wrong,
+* HTML-style tags often lead to invalid HTML (e.g., 
+  \code{<img src="<template*directive>">}),
+
+Cheetah tags are less verbose and easier to understand than HTML-style tags, 
+and HTML-style tags aren't compatible with most WYSIWYG editors.  In a WSYWIG
+editor, Cheetah tags appear to be literal text.
+
+Besides being much more compact, Cheetah also has some advantages over
+languages that put information inside the HTML tags, such as Zope Page
+Templates or PHP:
+
+* HTML or XML-bound languages do not work well with other languages,
+* While ZPT-like syntaxes work well in many ways with WYSIWYG HTML editors,
+  they also give up a significant advantage of those editors -- concrete
+  editing of the document.  When logic is hidden away in (largely
+  inaccessible) tags it is hard to understand a page simply by viewing it,
+  and it is hard to confirm or modify that logic.
+
+
+How stable is Cheetah?  How do I upgrade?
+-----------------------------------------
+
+..
+    :label: intro.stable
+
+Cheetah 2.0 was released [MONTH] [YEAR] with internal restructuring,
+easier-to-understand usage, updated documentation, and many other improvements.
+Cheetah 1.0 was released December 2005 after a three-year stable beta.
+Production sites have been using Cheetah since 2001.  Most changes since then
+have been based on requests from production sites: things they need that we
+hadn't considered.  
+
+Templates and calling code from Cheetah 1.0 remain 100% compatible.  Those from
+pre-1.0 versions since December 2001 (0.9.9) remain compatible except in rare
+cases.  
+
+.. important:: 
+    You must recompile all precompiled templates when upgrading
+    to Cheetah 2.0.
+
+Upgrades from 2.0 to a future version may or may not require
+recompilation.  Try filling a single precompiled template and see if you get a
+version exception.  If you do, recompile them all.  Or to be safe on a
+production site, just recompile them all anyway.
+
+Cheetah's development version is normally as stable as the last release if not
+better.  All CVS checkins are installed and run through the test suite before
+being checked in.
+
+Additional information is in these files in the Cheetah source distribution:
+
+CHANGES: 
+    All changes in each version.
+BUGS: 
+    Known bugs we haven't fixed yet.
+TODO: 
+    Enhancements we're planning, thing's like to do someday, and user requests
+    we haven't committed to.
+
+
+Web site and mailing list
+-------------------------
+
+..
+    :label: intro.news
+
+Cheetah releases and other stuff can be obtained from the the Cheetah 
+{\bf Web site}:
+\url{http://CheetahTemplate.sourceforge.net}
+
+Cheetah discussions take place on the {\bf mailing list}
+\email{cheetahtemplate-discuss@lists.sourceforge.net}.  This is where to hear
+the latest news first.
+
+If you encounter difficulties, or are unsure about how to do something,
+please post a detailed message to the list.  Also please share your
+experiences, tricks, customizations, and frustrations.  And if you have a
+success story for the "Who Is Using Cheetah" 
+(http://cheetahtemplate.sourceforge.net/whouses.html) or
+"Testimonials" (http://cheetahtemplate.sourceforge.net/praise.html)
+page on the website, send it to the mailing list.
+
+
+Bug reports, patches, and the test suite
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+If you think there is a bug in Cheetah, send a message to the mailing list
+with the following information:
+
+* a description of what you were trying to do and what happened
+* all tracebacks and error output
+* your version of Cheetah
+* your version of Python
+* your operating system
+* whether you have changed anything in the Cheetah installation
+
+Cheetah is packaged with a regression testing suite that is run with each
+new release to ensure that everything is working as expected and that recent
+changes haven't broken anything.  The test cases are in the Cheetah.Tests
+module.  If you find a reproduceable bug please consider writing a test case
+that will pass only when the bug is fixed.  Send any new test cases to the email
+list with the subject-line "new test case for Cheetah".  (@@MO Shorten
+paragraph, link to testing section.)
+
diff --git a/docs/users_guide_2_src/02_glossary.txt b/docs/users_guide_2_src/02_glossary.txt
new file mode 100644
index 0000000..49988fd
--- /dev/null
+++ b/docs/users_guide_2_src/02_glossary.txt
@@ -0,0 +1,66 @@
+Glossary
+========
+
+..
+    :label: glossary
+
+**Template** is an informal term meaning a template definition, a template
+class or a template instance.  A **template definition** is what the human
+maintainer writes: a file or string consisting of text, placeholders and
+directives.  **Placeholders** are variables that will be looked up when the
+template is filled.  **Directives** are commands to be executed when the
+template is filled, or instructions to the Cheetah compiler.  Placeholders
+normally start with "$"; directives with "#".  The conventional suffix for a
+file containing a template definition is **.tmpl**.
+
+To use a template, you first **compile** the template definition into
+**template class**.  Then you instantiate the class and **fill** it by calling
+one of its instance methods.  Filling does all the placeholder lookups and
+returns the finished result.  Templates can be compiled in memory or written to
+a Python module, called a **precompiled template**.
+
+Every template has a **main** method that fills the entire template.  The main
+method is usually ``.respond()``.  Calling ``str()`` or ``unicode()`` on a
+template instance is the same as calling the main method.  Templates can also
+contain **#def methods** (via ``#def`` or ``#block``), which can be called
+directly.
+
+A **placeholder** consists of one or more **identifiers** separated by periods.
+Identifiers must follow the same rules as Python variable names, and may be
+followed by the usual ``[]`` and ``()`` as in Python.  Example with three
+identifiers: ``a.b[2].c("arg")``.  The value discovered at fill time is the
+**placeholder value**.
+
+The first (or only) identifier of a placeholder name represents a **variable**
+to be looked up.  If Cheetah's **NameMapper** is turned on (the default), it
+looks in various **namespaces** including the template instance's ``self``,
+Python variables local/global to the template method, and an arbitrary list of
+**user-defined namespaces** you may have passed to the template constructor.
+A user-defined namespace is any Python object; Cheetah searches its attributes
+and keys for a matching name.  ``#set`` and ``#for`` create local
+variables.  ``#import`` and ``#set module global`` create global variables.
+``#attr``, ``#def``, and ``#block`` create ``self`` variables.  When the
+NameMapper is turned off, only local/global variables are accessible.
+
+The NameMapper also handles universal dotted notation and autocalling.
+**Universal dotted notation** means that keys may be written as if they were
+attributes: ``a.b`` instead of ``a['b']``.  **Autocalling** means that
+if any identifier's value is found to be a function or method, Cheetah will
+call it without arguments if there is no ``()`` following.  More about the
+NameMapper is in section \ref{language.namemapper}.
+
+Cheetah 1 used the term "searchList" for user-defined namespaces.  However,
+Cheetah has another **search list** internally: the actual list of namespaces
+it consults.  This is almost the same thing but not quite.  To avoid confusion,
+this Guide uses the term "search list" only for the internal list.
+
+Some directives are multi-line, meaning they have a matching **\#end** tag.
+The lines of text between the start and end tags is the **body** of the
+directive.  Arguments on the same line as the start tag, in contrast, are
+considered part of the directive tag.
+
+A **template-servlet** is a Webware_-specific construct.  Any .py template
+module in a Webware servlet directory can be filled directly through the web by
+requesting the URL. 
+
+.. _Webware: http://www.webwareforpython.org/
diff --git a/docs/users_guide_2_src/03_gettingStarted.txt b/docs/users_guide_2_src/03_gettingStarted.txt
new file mode 100755
index 0000000..6e447c2
--- /dev/null
+++ b/docs/users_guide_2_src/03_gettingStarted.txt
@@ -0,0 +1,262 @@
+Getting Started
+========================================
+
+..
+    :label: gettingStarted
+
+
+Requirements
+----------------------------------------
+
+..
+    :label: gettingStarted.requirements
+
+Cheetah requires Python release 2.2 or newer, and has been tested with all
+versions through 2.4.2.  It should run everywhere Python runs, and has been
+tested on Linux, Windows NT/98/XP, FreeBSD, Solaris, and Mac OS X.
+
+99% of Cheetah is written in Python.  There is one small C module
+(``_namemapper.so``) for speed, but Cheetah automatically falls back to a
+Python equivalent (``NameMapper.py``) if the C module is not available.
+
+
+Installation
+----------------------------------------
+
+..
+    :label: gettingStarted.install
+
+If you have ``easy_install``
+(http://peak.telecommunity.com/DevCenter/EasyInstall) set up, this command will
+download and install the latest version of Cheetah as a Python Egg
+(http://peak.telecommunity.com/DevCenter/PythonEggs)::
+
+    # easy_install Cheetah
+
+Or from an already-downloaded tarball::
+
+    # easy_install Cheetah-2.0.tar.gz
+
+Or from an unpacked source directory or CVS sandbox::
+
+    # easy_install .
+
+If you don't have ``easy_install``, you'll have to install Cheetah manually::
+
+    # tar xzvf Cheetah-2.0.tar.gz
+    # cd Cheetah-2.0
+    # python setup.py install
+
+You can also specify non-default locations::
+
+    # python setup.py install --install-lib=/home/tavis/python
+    # python setup.py install --home=/home/tavis
+    # python setup.py install --help
+
+.. tip::
+
+    If you install Cheetah manually and then install an egg that depends on
+    Cheetah (like TurboCheetah_), ``easy_install`` may *reinstall*
+    Cheetah as an egg.  This leaves two copies of Cheetah on your system,
+    possibly different versions.  Python will use whichever version comes
+    first in the Python path.  To avoid this, use ``easy_install``'s
+    **--no-deps** option or delete the copy you don't wish to use.
+
+
+Uninstalling
+----------------------------------------
+
+..
+    :label: gettingstarted.uninstalling
+
+To uninstall Cheetah: 
+
+1. Delete the "cheetah" program
+from whichever bin/ directory it was put in (perhaps /usr/local/bin/).  
+
+2. If Cheetah was installed as an egg, delete the egg directory
+(e.g., /usr/local/lib/python2.4/site-packages/Cheetah-2.0-py2.4.egg/), and
+remove the "Cheetah" line in **easy-install.pth** in the same directory.  
+
+3. If Cheetah was not installed as an egg, delete the package directory
+(e.g., /usr/local/lib/python2.4/site-packages/Cheetah/).
+
+
+The 'cheetah' command
+----------------------------------------
+
+..
+    :label: gettingStarted.cheetah
+
+Cheetah comes with a utility "cheetah" that provides a command-line
+interface to various housekeeping tasks.  The command's first argument is
+the name of the task.  The following commands are currently supported::
+
+    cheetah compile [options] [FILES ...]     : Compile template definitions
+    cheetah fill [options] [FILES ...]        : Fill template definitions
+    cheetah help                              : Print this help message
+    cheetah options                           : Print options help message
+    cheetah test                              : Run Cheetah's regression tests
+    cheetah version                           : Print Cheetah version number
+
+You only have to type the first letter of the command:
+``cheetah c`` is the same as ``cheetah compile``.
+
+The test suite is described in the next section.  The ``compile``
+command in section \ref{howWorks.cheetah-compile}, 
+and the ``fill`` command in section \ref{howWorks.cheetah-fill}.
+
+
+Testing your installation
+----------------------------------------
+
+..
+    :label: gettingStarted.test
+
+After installing Cheetah, you can run its self-test routine to verify it's
+working properly on your system.  First cd to to any directory you have write
+permission in (the tests write temporary files) *except* the unpacked Cheetah
+source directory (it might produce spurious errors).  Type the following at the
+command prompt::
+
+    $ cheetah test 
+
+The tests will run for about three minutes and print a success/failure
+message.  If the tests pass, start Python in interactive mode and try the
+example in the next section.
+
+Sometimes the CheetahWrapper tests fail on Windows because they can't execute 
+"cheetah" via ``os.system()``.  Ignore these; you won't be doing this when
+you use Cheetah.
+
+If any other tests fail, please send a message to the e-mail list with a copy
+of the test output and the following details about your installation:
+
+* your version of Cheetah
+* your version of Python
+* your operating system
+* whether you have changed anything in the Cheetah installation
+
+
+
+Quickstart tutorial
+----------------------------------------
+
+..
+    :label: gettingStarted.tutorial
+
+This tutorial briefly introduces how to use Cheetah from the Python prompt.
+The following chapters will discuss other ways to use templates and more of
+Cheetah's features.
+
+The core of Cheetah is the ``Template`` class in the ``Cheetah.Template``
+module. The following example shows how to use the ``Template`` class in an
+interactive Python session. ``t`` is the Template instance.  Lines prefixed
+with ``>>>`` and ``...`` are user input.  The remaining lines are Python
+output. ::
+
+    >>> from Cheetah.Template import Template
+    >>> templateDef = """
+    ... <HTML>
+    ... <HEAD><TITLE>$title</TITLE></HEAD>
+    ... <BODY>
+    ... $contents
+    ... ## this is a single-line Cheetah comment and won't appear in the output
+    ... #* This is a multi-line comment and won't appear in the output
+    ...    blah, blah, blah 
+    ... *#
+    ... </BODY>
+    ... </HTML>"""
+    >>> namespace = {'title': 'Hello World Example', 'contents': 'Hello World!'}
+    >>> t = Template(templateDef, namespaces=[namespace])
+    >>> print t
+     
+    <HTML>
+    <HEAD><TITLE>Hello World Example</TITLE></HEAD>
+    <BODY>
+    Hello World!
+    </BODY>
+    </HTML>
+    >>> print t    # print it as many times as you want
+          [ ... same output as above ... ]
+    >>> namespace['title'] = 'Example #2'
+    >>> namespace['contents'] = 'Hiya Planet Earth!'
+    >>> print t   # Now with different plug-in values.
+    <HTML>
+    <HEAD><TITLE>Example #2</TITLE></HEAD>
+    <BODY>
+    Hiya Planet Earth!
+    </BODY>
+    </HTML>
+
+Because Cheetah is extremely flexible, you can achieve the same result this
+way::  
+
+    >>> t2 = Template(templateDef)
+    >>> t2.title = 'Hello World Example!'
+    >>> t2.contents = 'Hello World'
+    >>> print t2
+          [ ... same output as the first example above ... ]
+    >>> t2.title = 'Example #2'
+    >>> t2.contents = 'Hello World!'
+    >>> print t2
+         [ ... same as Example #2 above ... ]
+
+Or the values can be extracted from an object's attributes.
+
+    >>> myInstance.title
+    'Hello World Example!'
+    >>> myInstance.contents = 'Hello World!'
+    >>> t2 = Template(templateDef, namespaces=[myInstance])
+
+The template will search your namespaces in order, then its own ``self``
+attributes, until it finds a match.  The template definition can also 
+come from a file rather than a string.
+
+Let's look at the ``Template`` constructor again::
+
+    t = Template(templateDef, namespaces=[namespace])
+
+This does more than it appears.  It compiles the template definition into a
+template class, a subclass of ``Template``, and instantiates it.  Sometimes
+it's desirable to separate these operations, and the ``.compile`` class method
+does this::
+
+    tclass = Template.compile(templateDef)
+    t = tclass(namespaces=[namespace])
+
+The first line compiles the template class; the second line instantiates it.
+You can also do this on one line::
+
+    t = Template.compile(templateDef)(namespaces=[namespace])
+
+You can use either ``Template()`` or ``Template.compile()`` in your programs,
+but you should learn both styles so you'll recognize them in other people's
+code.
+
+This is all fine for short templates, but for long templates or for an
+application that depends on many templates, it's easier to store the templates
+in separate \*.tmpl files and use the **cheetah** program to compile
+them into Python modules.  This will be covered in section
+\ref{howWorks.cheetah-compile}.  Here's how you use a precompiled template::
+
+    >>> from MyPrecompiledTemplate import MyPrecompiledTemplate
+    >>> t = MyPrecompiledTemplate()
+    >>> t.name = "Fred Flintstone"
+    >>> t.city = "Bedrock City"
+    >>> print t
+
+Or::
+
+    >>> from MyPrecompiledTemplate import MyPrecompiledTemplate
+    >>> namespace = {"name": "Fred Flintstone", "city": "Bedrock City"}
+    >>> t = MyPrecompiledTemplate(namespaces=[namespace])
+    >>> print t
+
+For the minimalists out there, here's a template compilation,
+instantiation and filling all in one Python statement::
+
+    >>> print Template("Templates are pretty useless without placeholders.")
+    Templates are useless without placeholders.
+
+.. _TurboCheetah:  http://python.org/pypi/TurboCheetah/
diff --git a/docs/users_guide_2_src/04_howItWorks.txt b/docs/users_guide_2_src/04_howItWorks.txt
new file mode 100755
index 0000000..17ee3d5
--- /dev/null
+++ b/docs/users_guide_2_src/04_howItWorks.txt
@@ -0,0 +1,369 @@
+How Cheetah Works
+=================
+
+..
+    :label: howWorks
+
+
+
+Constructing Template Objects
+-----------------------------
+
+..
+    :label: howWorks.templateClass
+
+..
+    :label: howWorks.constructing
+
+The heart of Cheetah is the ``Template`` class in the
+``Cheetah.Template`` module.  There are several ways to construct templates,
+each with slightly different arguments.  Where *source* is shown, it's always
+the first argument and may be specified positionally.  The order of the 
+other arguments may change, so always specify them as keyword arguments.
+
+``Template()`` accepts the following arguments:
+
+    source
+         The template definition as a string.  The source can be a string
+         literal in your module, or perhaps a string you read from a database
+         or other data structure.
+
+    file
+         A filename or file object containing the template definition.  A
+         filename must be a string, and a file object must be open for reading.
+         By convention, template definition files have the extension **.tmpl**.
+
+    namespaces, searchList
+        A list of objects which Cheetah will search for placeholder values.
+        (Cheetah also searches certain other objects automatically; see the
+        "Placeholders" chapter for details.)  Use either argument; they both
+        mean the same thing.
+
+    filter
+        Equivalent to putting ``#filter`` at the top of the template.  The
+        argument may be a subclass of ``Cheetah.Filters.Filter``, or a string
+        naming a class in filtersLib (the next argument below).  See
+        ``#filter`` for details.
+
+    filtersLib
+         A module containing the filters Cheetah should look up by name.  The
+         default is ``Cheetah.Filters``.  All classes in this module that are
+         subclasses of ``Cheetah.Filters.Filter`` are considered filters.
+
+    errorCatcher
+        Equivalent to putting ``#errorCatcher`` at the top of the template.
+        The object may be a subclass of ``Cheetah.ErrorCatchers.ErrorCatcher``,
+        or a string naming a class in ``Cheetah.ErrorCatchers``.  See
+        ``#errorCatcher`` for details.
+
+    compilerSettings
+        Equivalent to putting ``#compiler-settings`` at the top of the
+        template.  The argument is a dictionary or nesting of dictionaries.
+        See ``#compiler-settings`` for details.
+
+A template class returned by ``Cheetah.compile`` or precompiled via "cheetah
+compile" takes the same constructor arguments as above, except "source" and
+"file" which are not allowed.  Use keyword arguments for all arguments
+because their order may change.
+
+The class method ``Template.compile()`` takes the following
+arguments:
+
+    source, file, compilerSettings
+        Same as above.  *These are the only arguments most users will ever
+        use.*  The other args below are for specialized advanced uses.
+
+    returnAClass
+        If true (default), return a subclass of ``Template`` specific to this
+        template definition.  If false, return the Python source of a module
+        containing this class; i.e., what "cheetah compile" would write to a
+        file.
+
+    moduleName, className, mainMethodName
+        Override the default names.  For instance, TurboCheetah (a third-party
+        library) requires its templates to have a fixed class name, so it uses
+        *className*.
+
+    compilerClass
+        Use an You'll probably never need this.
+
+    baseclass
+        Equivalent to putting ``#extends`` at the top of the template.
+        ``#extends`` overrides this, unlike other arguments.
+
+    moduleGlobals
+        In case you want to sneak in some extra variables that don't require
+        the NameMapper.
+
+    preprocessors
+        A list of filter functions which will modify the template definition
+        before Cheetah's compiler sees it.  See chapter @@MO for details.
+
+    compilerClass, cacheCompilationResults, useCache, cacheModuleFilesForTracebacks, cacheDirForModuleFiles, keepRefToGeneratedCode
+        You'll probably never need these.  They are used to provide an
+        alternate compiler, disable Cheetah's template caching (*not* related
+        to ``#cache``), or modify Cheetah's enhanced traceback reporting.  See
+        the ``Template.compile()`` docstring for details.
+
+Here are typical ways to create a template instance:
+
+``t = Template("The king is a \$placeholder1.")``
+     Pass the template definition as a string.
+``t = Template(file="fink.tmpl")``
+     Read the template definition from a file named "fink.tmpl".  
+``t = Template(file=f)``
+     Read the template definition from file-like object 'f'.
+``t = Template("The king is a \$placeholder1.", namespaces=[dict, obj])``
+     Pass the template definition as a string.  Also pass two namespaces for
+     the namespaces: a dictionary 'dict' and an instance 'obj'.
+``t = Template(file="fink.txt", namespaces=[dict, obj])``
+     Same, but pass a filename instead of a string.
+``t = Template(file=f, namespaces=[dict, obj])``
+     Same with a file object.
+
+Filling templates and extracting data
+-------------------------------------
+
+There are several ways to fill a template.  Assume ``t`` is a template
+instance::
+
+    1 output = t.respond()
+    2 output = str(t)            # Shortcut for "str(t.respond())".
+    3 output = unicode(t)        # Shortcut for "unicode(t.respond())".
+    4 print t                    # Shortcut for "print str(t.respond())".
+    4 sys.stderr.write( unicode(t).encode('latin1') )
+    5 result = t.my_def_method(arg1, arg2)
+
+These all assume the template's main method is ``.respond``, which is true
+in the normal case.  [#]_  ``str()`` and
+``unicode()`` will always call the main method whatever it's named.
+
+If the output contains non-ASCII characters, examples 2 and 4 will raise
+an exception.  Use one of the other examples instead.
+
+Example 5 calls a ``#def`` method with arguments.  Only that method's output
+is returned.
+
+If the template contains ``#attr`` attributes, you can access those directly::
+
+    title = t.title
+    author = t.author
+
+
+.. [#] See the Inheritance chapter... (#implements, mainMethodName, 
+   inheritance).
+
+"cheetah compile" and precompiled templates
+-------------------------------------------
+
+..
+    :label: howWorks.cheetah-compile
+
+To create a precompiled template module, do either of these::
+
+    cheetah compile [options] [FILES ...]
+    cheetah c [options] [FILES ...]
+
+There are several advantages of precompiled templates:
+
+- Precompiled templates are easier to debug because you can see the generated
+  Python code, and the line numbers in error messages will correspond to the
+  actual line in the template definition file.  (If the template definition is
+  embedded in a string literal inside a module, you'll have to count down from
+  the first line in the string to find the error line.)
+
+- Data analysis programs can import the template classes and query their
+  attributes, which can be set via ``#attr``.  Example: a directory of 
+  templates can each contain ``.title`` and ``.author`` attributes, and 
+  another program can read them all and make an index page.
+
+- Slightly faster performance since the compilation is done before
+  the user runs your application, and Python will optimize this further
+  with .pyc or .pyo files.  The actual speed difference is minimal --
+  Cheetah appears to compile templates instantaneously anyway, and it caches
+  templates in memory if possible, but precompiling templates will make
+  some developers feel better for conserving electrons.
+  
+- ``#extends`` requires that the base template be precompiled, or the
+  child template cannot be instantiated.  (@@MO: The *baseclass* constructor
+  arg can be used to set the parent class for a dynamically-compiled 
+  template.)
+
+- Only precompiled templates may be used as Webware servlets.
+
+Some of Cheetah's developers use only precompiled templates and recommend the
+same.  However, it's your choice whether to do this.
+
+The following options are supported::
+
+  --idir DIR, --odir DIR : input/output directories (default: current dir)
+  --iext EXT, --oext EXT : input/output filename extensions
+    (default input: tmpl,  default output:  py)
+  -R : recurse subdirectories looking for input files
+  --debug : print lots of diagnostic output to standard error
+  --flat : no destination subdirectories
+  --nobackup : don't make backups
+  --stdout, -p : output to standard output (pipe)
+  --settings         : a string representing the compiler settings to use
+                       e.g. --settings='useNameMapper=False,useFilters=False'
+                       This string is eval'd in Python so it should contain
+                       valid Python syntax.
+  --templateAPIClass : a string representing a subclass of
+                       Cheetah.Template:Template to use for compilation
+
+.. tip::
+    If Cheetah can't find your input files, or if it puts output files
+    in the wrong place, use the ``--debug`` option to see how Cheetah
+    interpreted your command line.
+
+The most basic usage is::
+
+    cheetah compile a.tmpl           : writes a.py
+    cheetah compile a.tmpl b.tmpl    : writes a.py and b.py
+
+
+Cheetah will automatically add the default input extension (.tmpl) if the exact
+file is not found.  So the following two examples are the same as above if
+"a" and "b" don't exist::
+
+    cheetah compile a                : writes a.py (from a.tmpl)
+    cheetah compile a b              : writes a.py and b.py
+
+
+Use the ``-R`` option to recurse subdirectories::
+
+    cheetah compile dir1             : error, file is a directory
+    cheetah compile -R dir1          : look under `dir1' for files to compile
+    cheetah compile                  : error, no file specified
+    cheetah compile -R               : compile all templates under current
+                                       directory and subdirectories
+    cheetah compile -R a b dir1      : compile files and recurse
+
+When recursing, only regular files that end in the input extension (.tmpl) are
+considered source files.  All other filenames are ignored.
+
+The options ``--idir`` and ``--odir`` allow you to specify that
+the source (and/or destination) paths are relative to a certain directory
+rather than to the current directory.  This is useful if you keep your
+\*.tmpl and \*.py files in separate directory hierarchies.  After editing a 
+source file, just run one of these (or put the command in a script or 
+Makefile)::
+
+    cheetah compile --odir /var/webware a.tmpl
+    cheetah compile -R --odir /var/webware
+    cheetah c --odir /var/webware sub/a.tmpl
+                                     : writes /var/webware/sub/a.py
+
+
+"cheetah compile" overwrites any existing ``.py`` file it finds, after
+backing it up to FILENAME.py_bak (unless you specify ``--nobackup``).  For
+this reason, you should make changes to the ``.tmpl`` version of the
+template rather than to the ``.py`` version.
+
+For the same reason, if your template requires custom Python methods or
+other Python code, don't put it in the ``FILENAME.py`` file or it will be
+overwritten!  Instead, put it in a separate base class and use
+``#extends`` to inherit from it.
+
+Because FILENAME will be used as a class and module name, it must be a valid
+Python identifier.  For instance, ``cheetah compile spam-eggs.tmpl`` is 
+illegal because of the hyphen ("-").  This is sometimes inconvenient when
+converting a site of HTML files into Webware servlets.  Fortunately, the
+*directory* it's in does not have to be an identifier.  (*Hint:* for
+date-specific files, try converting 2002/04/12.html to 2002/04/12/index.tmpl.
+This also gives you a directory to store images or supplemental files.)
+
+Occasionally you may want output files put directly into the output directory
+(or current directory), rather than into subdirectories parallel to the input
+file.  The ``--flat`` option does this.  This may cause several input files
+might map to the same output file.  Cheetah checks for output file collisions
+before writing any files, and aborts if there are any collisions. ::
+
+    cheetah c sub/a.py            : writes sub/a.py
+    cheetah c --flat sub/a.py     : writes a.py
+    cheetah c --odir DEST sub/a.tmpl
+                                  : writes DEST/sub/a.py
+    cheetah c --flat --odir DEST sub/a.tmpl
+                                  : writes DEST/a.py
+    cheetah c --idir /home/henry sub/rollins.tmpl
+                                  : writes sub/rollins.py
+    cheetah c --flat --idir /home/henry sub/rollins.tmpl
+                                  : writes rollins.py
+    cheetah c --idir /home/henry --odir /home/henry sub/rollins.tmpl
+                                  : writes /home/henry/sub/rollins.py
+    cheetah c --flat --idir /home/henry --odir /home/henry sub/rollins.tmpl
+                                  : writes /home/henry/rollins.py
+
+
+Whenever "cheetah compile" has to create an output directory or subdirectory,
+it also creates an __init__.py file in it.  This file is necessary in order
+to make Python treat the directory as a Python package.
+
+Chapter @@MO has a look inside a precompiled template module.
+
+"cheetah fill"
+--------------
+
+..
+    :label: howWorks.cheetah-fill
+
+You can fill templates from the command line with "cheetah fill".  The most
+common example is static HTML files which are generated from templates.  The
+output extension is .html by default.  The compiled template modules are not
+written to disk.  All the options to "cheetah compile" are allowed.  
+
+Examples::
+
+    cheetah fill a.tmpl              : writes a.html
+    cheetah fill a.tmpl b.tmpl       : writes a.html and b.html
+    cheetah f --oext txt a           : writes a.txt (from a.tmpl)
+
+You can't specify user-defined namespaces the normal way, so the templates must
+be written to have default values for all variables.  However, there is limited
+support for gathering placeholder values from operating-system resources::
+
+  --env : make the environment variables a user-defined namespace
+  --pickle FILE : unpickle FILE and make that object a user-defined namespace
+
+Using ``--env`` may have security or reliability implications because the
+environment normally contains lots of variables you inherited rather than
+defining yourself.  If any of these variables override any of yours (say a
+``#def``), you will get incorrect output, may reveal private information,
+and may get an exception due to the variable being an unexpected type
+(environment variables are always strings).  Your calling program may wish
+to clear out the environment before setting environment variables for the
+template.
+
+There are two other differences between "cheetah compile" and "cheetah fill".
+Cheetah doesn't create __init__.py files when creating directories in
+fill mode.  Also, the source filenames don't have to be identifiers.  This
+allows you to create any .html filename even if it contains characters like "-"
+that are illegal in identifiers.
+
+
+Running a .py template module as a standalone program
+-----------------------------------------------------
+
+..
+    :label: howWorks.standalone
+
+In addition to importing your .py template module file into a Python
+script or using it as a Webware servlet, you can also run it from the
+command line as a standalone program.  The program will print the filled
+template on standard output.  This is useful while debugging the template,
+and for producing formatted output in shell scripts.
+
+When running the template as a program, you cannot provide a searchList or
+set ``self.`` attributes in the normal way, so you must take
+alternative measures to ensure that every placeholder has a value.
+Otherwise, you will get the usual ``NameMapper.NotFound`` exception at
+the first missing value.  You can either set default values in the template
+itself (via the ``\#attr`` or ``\#def`` directives) or in a Python
+superclass, or use the ``--env`` or ``--pickle`` command-line options,
+which work just like their "cheetah fill" counterparts.
+
+Run ``python FILENAME.py --help`` to see all the command-line
+options your .py template module accepts.
+
+
+
diff --git a/docs/users_guide_2_src/05_language.txt b/docs/users_guide_2_src/05_language.txt
new file mode 100755
index 0000000..673abca
--- /dev/null
+++ b/docs/users_guide_2_src/05_language.txt
@@ -0,0 +1,651 @@
+\section{Language Overview}
+\label{language}
+
+Cheetah's basic syntax was inspired by the Java-based template engines Velocity
+and WebMacro. It has two types of tags: {\bf \$placeholders} and {\bf
+\#directives}.  Both types are case-sensitive.  
+
+Placeholder tags begin with a dollar sign (\code{\$varName}) and are similar to
+data fields in a form letter or to the \code{\%(key)s} fields on the left side
+of Python's \code{\%} operator. When the template is filled, the placeholders
+are replaced with the values they refer to.
+
+Directive tags begin with a hash character (\#) and are used for comments,
+loops, conditional blocks, includes, and all other advanced features.  
+({\em Note:} you can customize the start and end delimeters for placeholder 
+and directive tags, but in this Guide we'll assume you're using the default.)
+
+Placeholders and directives can be escaped by putting a backslash before them.
+\verb+\$var+ and \verb+\#if+ will be output as literal text.
+
+A placeholder or directive can span multiple physical lines, following the same
+rules as Python source code: put a backslash (\verb+\+) at the end of all
+lines except the last line.  However, if there's an unclosed parenthesis,
+bracket or brace pending, you don't need the backslash.
+
+\begin{verbatim}
+#if $this_is_a_very_long_line and $has_lots_of_conditions \
+    and $more_conditions:
+<H1>bla</H1>
+#end if
+
+#if $country in ('Argentina', 'Uruguay', 'Peru', 'Colombia',
+    'Costa Rica', 'Venezuela', 'Mexico')
+<H1>Hola, senorita!</H1>
+#else
+<H1>Hey, baby!</H1>
+#end if
+\end{verbatim}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Language Constructs -- Summary}
+\label{language.constructs}
+
+\begin{enumerate}
+\item Comments and documentation strings
+     \begin{enumerate}
+     \item \code{\#\# single line}
+     \item \code{\#* multi line *\#}
+     \end{enumerate}
+
+\item Generation, caching and filtering of output
+     \begin{enumerate}
+     \item plain text
+     \item look up a value: \code{\$placeholder}
+     \item evaluate an expression: \code{\#echo} \ldots
+     \item same but discard the output: \code{\#silent} \ldots
+     \item one-line if: \code{\#if EXPR then EXPR else EXPR}
+     \item gobble the EOL: \code{\#slurp}
+     \item parsed file includes: \code{\#include} \ldots
+     \item raw file includes: \code{\#include raw} \ldots
+     \item verbatim output of Cheetah code: \code{\#raw} \ldots \code{\#end raw}
+     \item cached placeholders: \code{\$*var}, \code{\$*<interval>*var}
+     \item cached regions: \code{\#cache} \ldots \code{\#end cache}
+     \item set the output filter: \code{\#filter} \ldots
+     \item control output indentation: \code{\#indent} \ldots ({\em not
+implemented yet})
+     \end{enumerate}
+          
+\item Importing Python modules and objects: \code{\#import} \ldots,
+     \code{\#from} \ldots
+
+\item Inheritance 
+     \begin{enumerate}
+     \item set the base class to inherit from: \code{\#extends}
+     \item set the name of the main method to implement: \code{\#implements}
+\ldots
+     \end{enumerate}
+
+\item Compile-time declaration
+     \begin{enumerate}
+     \item define class attributes: \code{\#attr} \ldots
+     \item define class methods: \code{\#def} \ldots \code{\#end def}
+     \item \code{\#block} \ldots \code{\#end block} provides a simplified
+          interface to \code{\#def} \ldots \code{\#end def}
+     \end{enumerate}
+
+\item Run-time assignment
+     \begin{enumerate}
+     \item local vars: \code{\#set} \ldots
+     \item global vars: \code{\#set global} \ldots
+     \item deleting local vars: \code{\#del} \ldots
+     \end{enumerate}
+
+\item Flow control
+     \begin{enumerate}
+     \item \code{\#if} \ldots \code{\#else} \ldots \code{\#else if} (aka
+          \code{\#elif}) \ldots \code{\#end if}
+     \item \code{\#unless} \ldots \code{\#end unless}
+     \item \code{\#for} \ldots \code{\#end for}
+     \item \code{\#repeat} \ldots \code{\#end repeat}
+     \item \code{\#while} \ldots \code{\#end while}
+     \item \code{\#break}
+     \item \code{\#continue}
+     \item \code{\#pass}
+     \item \code{\#stop}
+     \end{enumerate}
+
+\item error/exception handling
+     \begin{enumerate}
+     \item \code{\#assert}
+     \item \code{\#raise}
+     \item \code{\#try} \ldots \code{\#except} \ldots \code{\#else} \ldots
+          \code{\#end try} 
+     \item \code{\#try} \ldots \code{\#finally} \ldots \code{\#end try}
+     \item \code{\#errorCatcher} \ldots set a handler for exceptions raised by
+\$placeholder calls.
+     \end{enumerate}
+
+\item Instructions to the parser/compiler
+     \begin{enumerate}
+     \item \code{\#breakpoint}
+     \item \code{\#compiler-settings} \ldots \code{\#end compiler-settings}
+     \end{enumerate}
+
+\item Escape to pure Python code
+    \begin{enumerate}
+    \item evalute expression and print the output: \code{<\%=} \ldots
+      \code{\%>} 
+    \item execute code and discard output: \code{<\%} \ldots \code{\%>}
+    \end{enumerate}
+
+\item Fine control over Cheetah-generated Python modules
+     \begin{enumerate}
+     \item set the source code encoding of compiled template modules: \code{\#encoding}
+     \item set the sh-bang line of compiled template modules: \code{\#shBang}
+     \end{enumerate}
+
+\end{enumerate}
+
+The use of all these constructs will be covered in the next several chapters.
+
+%% @@MO: TODO: reconcile the order of this summary with the order in the
+%% detail sections.
+
+% @@MO: PSP chapter with examples.  What does write() do?  Print?
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Placeholder Syntax Rules}
+\label{language.placeholders.syntax}
+
+\begin{itemize} 
+
+\item Placeholders follow the same syntax rules as Python variables except
+     that they are preceded by \code{\$} (the short form) or enclosed in
+     \code{\$\{\}} (the long form).
+     Examples:
+\begin{verbatim}
+$var                                        
+${var}                                      
+$var2.abc['def']('gh', $subplaceholder, 2)  
+${var2.abc['def']('gh', $subplaceholder, 2)}
+\end{verbatim}
+     We recommend \code{\$} in simple cases, and \code{\$\{\}} when followed
+     directly by a letter or when Cheetah or a human template maintainer might
+     get confused about where the placeholder ends.  You may alternately use
+     \verb+$()+ or \verb+$[]+, although this may confuse the (human) template
+     maintainer:
+\begin{verbatim}
+$(var)                                      
+$[var]                                      
+$(var2.abc['def']('gh', $subplaceholder, 2))
+$[var2.abc['def']('gh', $subplaceholder, 2)]
+\end{verbatim}
+     {\em Note:} Advanced users can change the delimiters to anything they
+     want via the \code{\#compiler} directive.
+
+     {\em Note 2:} The long form can be used only with top-level placeholders,
+     not in expressions.  See section \ref{language.placeholders.positions}
+     for an elaboration on this.
+
+\item To reiterate Python's rules, placeholders consist of one or more
+     identifiers separated by periods.  Each identifier must start with a letter
+     or an underscore, and the subsequent characters must be letters, digits or
+     underscores.  Any identifier may be followed by arguments enclosed in
+     \verb+()+ and/or keys/subscripts in \verb+[]+.
+
+\item Identifiers are case sensitive. \code{\$var} does not equal \code{\$Var}
+     or \code{\$vAr} or \code{\$VAR}.     
+     
+\item Arguments inside \verb+()+ or \verb+[]+ are just like in Python.
+    Strings may be quoted using any Python quoting style.  Each argument is an
+    expression and may use any of Python's expression operators.  Variables
+    used in argument expressions are placeholders and should be prefixed with
+    \code{\$}.  This also applies to the *arg and **kw forms.  However, you do
+    {\em not} need the \code{\$} with the special Python constants \code{None},
+    \code{True} and \code{False}.
+     Examples:
+\begin{verbatim}
+$hex($myVar)
+$func($arg=1234)
+$func2($*args, $**kw)
+$func3(3.14159, $arg2, None, True)
+$myList[$mySubscript]
+\end{verbatim}
+    
+\item Trailing periods are ignored.  Cheetah will recognize that the placeholder
+     name in \code{\$varName.} is \code{varName}, and the period will be left
+     alone in the template output.
+     
+\item The syntax \code{\$\{placeholderName, arg1="val1"\}} passes arguments to
+     the output filter (see \code{\#filter}, section \ref{output.filter}.
+     The braces and comma are required in this case.  It's conventional to 
+     omit the \code{\$} before the keyword arguments (i.e. \code{arg1}) in this
+     case.
+
+\item Cheetah ignores all dollar signs (\code{\$}) that are not followed by a
+     letter or an underscore.
+     
+\end{itemize} 
+
+The following are valid \$placeholders:
+\begin{verbatim}
+$a $_ $var $_var $var1 $_1var $var2_ $dict.key $list[3]
+$object.method $object.method() $object.method
+$nest($nest($var))
+\end{verbatim}
+
+These are not \$placeholders but are treated as literal text:
+\begin{verbatim}
+$@var $^var $15.50 $$
+\end{verbatim}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Where can you use placeholders?}
+\label{language.placeholders.positions}
+
+There are three places you can use placeholders: top-level position, 
+expression position and LVALUE position.  Each has slightly different
+syntax rules.
+
+Top-level position means interspersed in text.  This is the only place
+you can use the placeholder long form: \code{\$\{var\}}.
+
+{\em Expression position} means inside a Cheetah expression, which is the same
+as a Python expression.  The placeholder names a searchList or other variable
+to be read.  Expression position occurs inside () and $[]$ arguments within
+placeholder tags (i.e., a placeholder inside a placeholder), and in several
+directive tags.
+
+{\em LVALUE position} means naming a variable that will be written to.  LVALUE
+is a computer science term meaning ``the left side of an assignment 
+statement''.  The first argument of directives \code{\#set}, \code{\#for},
+\code{\#def}, \code{\#block} and \code{\#attr} is an LVALUE.
+
+This stupid example shows the three positions.  Top-level position is shown
+in \code{courier}, expression position is {\em italic}, and LVALUE position is
+{\bf bold}.
+
+\begin{quote}
+\#for {\bf \$count} in {\em \$range}({\em \$ninetyNine}, 0, -1)\\
+\#set {\bf \$after} = {\em \$count} - 1\\
+\code{\$count} bottles of beer on the wall.  \code{\$count} bottles of beer!\\
+~~~~Take one down, pass it around.  \code{\$after} bottles of beer on the wall.\\
+\#end for\\
+\code{\$hex}({\em \$myVar}, {\bf \$default}={\em None})
+\end{quote}
+
+The output of course is:
+\begin{verbatim}
+99 bottles of beer on the wall.  99 bottles of beer!
+    Take one down, pass it around.  98 bottles of beer on the wall.
+98 bottles of beer on the wall.  98 bottles of beer!
+    Take one down, pass it around.  97 bottles of beer on the wall.
+...
+\end{verbatim}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Are all those dollar signs really necessary?}
+\label{language.placeholders.dollar-signs}
+
+\code{\$} is a ``smart variable prefix''.  When Cheetah sees \code{\$}, it
+determines both the variable's position and whether it's a searchList value or
+a non-searchList value, and generates the appropriate Python code.  
+
+In top-level position, the \code{\$} is {\em required}.  Otherwise there's
+nothing to distinguish the variable from ordinary text, and the variable name
+is output verbatim.
+
+In expression position, the \code{\$} is {\em required} if the value comes from
+the searchList or a ``\#set global'' variable, {\em recommended} for
+local/global/builtin variables, and {\em not necessary} for the special
+constants \code{None}, \code{True} and \code{False}.  This works because
+Cheetah generates a function call for a searchList placeholder, but a bare
+variable name for a local/global/builtin variable.  
+
+In LVALUE position, the \code{\$} is {\em recommended}.  Cheetah knows where
+an LVALUE is expected, so it can handle your variable name whether it has
+\code{\$} or not.
+
+EXCEPTION: Do {\em not} use the \code{\$} prefix for intermediate variables in
+a Python list comprehensions.  This is a limitation of Cheetah's parser; it
+can't tell which variables in a list comprehension are the intermediate
+variables, so you have to help it.  For example:
+\begin{verbatim}
+#set $theRange = [x ** 2 for x in $range(10)]
+\end{verbatim}
+\code{\$theRange} is a regular \code{\#set} variable.  \code{\$range} is a
+Python built-in function.  But \code{x} is a scratch variable internal to
+the list comprehension: if you type \code{\$x}, Cheetah will miscompile
+it.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{NameMapper Syntax}
+\label{language.namemapper}
+
+One of our core aims for Cheetah was to make it easy for non-programmers to
+use. Therefore, Cheetah uses a simplified syntax for mapping placeholders
+in Cheetah to values in Python. It's known as the {\bf NameMapper syntax}
+and allows for non-programmers to use Cheetah without knowing (a) the
+difference between an instance and a dictionary, (b) what functions and methods
+are, and (c) what 'self' is. A side benefit is that you can change the 
+underlying data structure (e.g., instance to dictionary or vice-versa) without
+having to modify the templates.
+
+NameMapper syntax is used for all variables in Cheetah placeholders and
+directives. If desired, it can be turned off via the \code{Template} class'
+\code{'useNameMapper'} compiler setting.  But it's doubtful you'd ever want to
+turn it off.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{Example}
+\label{language.namemapper.example}
+
+Consider this scenario:
+
+You are building a customer information system. The designers with you want to
+use information from your system on the client's website --AND-- they want to
+understand the display code and so they can maintian it themselves.
+
+You write a UI class with a 'customers' method that returns a dictionary of all
+the customer objects.  Each customer object has an 'address' method that returns
+the a dictionary with information about the customer's address.  The designers
+want to be able to access that information.
+
+Using PSP, the display code for the website would look something like the
+following, assuming your servlet subclasses the class you created for managing
+customer information:
+
+\begin{verbatim}
+  <%= self.customer()[ID].address()['city'] %>   (42 chars)
+\end{verbatim}
+
+With Cheetah's NameMapper syntax, you can use any of the following:
+
+\begin{verbatim}
+   $self.customers()[$ID].address()['city']       (39 chars)
+   --OR--                                         
+   $customers()[$ID].address()['city']           
+   --OR--                                         
+   $customers()[$ID].address().city              
+   --OR--                                         
+   $customers()[$ID].address.city                
+   --OR--                                         
+   $customers[$ID].address.city                   (27 chars)                     
+\end{verbatim}   
+
+Which of these would you prefer to explain to the designers, who have no
+programming experience?  The last form is 15 characters shorter than the PSP
+version and -- conceptually -- far more accessible. With PHP or ASP, the
+code would be even messier than with PSP.
+
+This is a rather extreme example and, of course, you could also just implement
+\code{\$getCustomer(\$ID).city} and obey the Law of Demeter (search Google for more
+on that).  But good object orientated design isn't the point of this example.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{Dictionary Access}
+\label{language.namemapper.dict}
+
+NameMapper syntax allows access to dictionary items with the same dotted
+notation used to access object attributes in Python.  This aspect of NameMapper
+syntax is known as 'Unified Dotted Notation'.
+For example, with Cheetah it is possible to write:
+\begin{verbatim}
+   $customers()['kerr'].address()  --OR--  $customers().kerr.address()
+\end{verbatim}
+where the second form is in NameMapper syntax.
+
+This works only with dictionary keys that also happen to be valid Python
+identifiers.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{Autocalling}
+\label{language.namemapper.autocalling}
+
+Cheetah automatically detects functions and methods in Cheetah \$variables and
+calls them if the parentheses have been left off.  Our previous example can be
+further simplified to:
+\begin{verbatim}
+  $customers.kerr.address
+\end{verbatim}
+
+As another example, if 'a' is an object, 'b' is a method
+\begin{verbatim}
+  $a.b
+\end{verbatim}
+
+is equivalent to
+
+\begin{verbatim}
+  $a.b()
+\end{verbatim}
+
+If b returns a dictionary, then following variations are possible
+\begin{verbatim}
+  $a.b.c  --OR--  $a.b().c  --OR--  $a.b()['c']
+\end{verbatim}
+where 'c' is a key in the dictionary that a.b() returns.
+
+Further notes:
+\begin{itemize}
+\item When Cheetah autocalls a function/method, it calls it without any
+arguments.  Thus, the function/method must have been declared without arguments
+(except \code{self} for methods) or to provide default values for all arguments.
+If the function requires arguments, you must use the \code{()}.
+
+\item Cheetah autocalls only functions and methods.  Classes and other callable
+objects are not autocalled.  The reason is that the primary purpose of a
+function/method is to call it, whereas the primary purpose of an instance is to
+look up its attributes or call its methods, not to call the instance itself.
+And calling a class may allocate large sums of memory uselessly or have other
+side effects, depending on the class.  For instance, consider
+\code{\$myInstance.fname}.  Do we want to look up \code{fname} in the namespace
+of \code{myInstance} or in the namespace of whatever \code{myinstance} returns?
+It could go either way, so Cheetah follows the principle of least surprise.  If
+you {\em do} want to call the instance, put the \code{()} on, or rename the
+\code{.\_\_call\_\_()} method to \code{.\_\_str\_\_}.
+
+\item Autocalling can be disabled via Cheetah's 'useAutocalling' compiler
+setting.  You can also disable it for one placeholder by using the syntax
+\code{\$getVar('varName', 'default value', False)}.  (\code{.getVar()} works
+only with searchList values.)
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Namespace cascading and the searchList}
+\label{language.searchList}
+
+When Cheetah maps a variable name in a template to a Python value, it searches
+several namespaces in order:
+
+\begin{enumerate}
+\item {\bf Local variables:} created by \code{\#set},
+    \code{\#for}, or predefined by Cheetah.
+\item The {\bf searchList}, consisting of:
+    \begin{enumerate}
+    \item \code{\#set\ global} variables.
+    \item The {\bf searchList} containers you passed to the \code{Template} 
+        constructor, if any.
+    \item The {\bf Template instance} (``self'').  This contains any attributes
+        you assigned, \code{\#def} methods and \code{\#block methods},
+        attributes/methods inherited via \code{\#extends}, and other
+        attributes/methods built into \code{Template} or inherited by it
+        (there's a list of all these methods in section
+        \ref{tips.allMethods}).
+    \end{enumerate}
+\item {\bf Python globals:} created by \code{\#import},
+    \code{\#from\ ...\ import}, or otherwise predefined by Cheetah.
+\item {\bf Python builtins:}  \code{None}, \code{max}, etc.
+\end{enumerate}
+
+The first matching name found is used.  
+
+Remember, these namespaces apply only to the {\em first} identifier after the
+\code{\$}.  In a placeholder like \code{\$a.b}, only `a' is looked up in the
+searchList and other namespaces.  `b' is looked up only inside `a'.
+
+A searchList container can be any Python object with attributes or keys:
+dictionaries, instances, classes or modules.  If an instance contains both
+attributes and keys, its attributes are searched first, then its keys.
+
+Because the \code{Template} instance is part of the searchList, you can
+access its attributes/methods without `self': \code{\$myAttr}.  However, use
+the `self' if you want to make sure you're getting the \code{Template}
+attribute and not a same-name variable defined in a higher namespace:
+\code{\$self.myAttr}.  This works because ``self'' itself is a local variable.
+
+The final resulting value, after all lookups and function calls (but before the
+filter is applied) is called the {\em placeholder value}, no matter which 
+namespace it was found in.
+
+{\em {\bf Note carefully:}} if you put an object `myObject' in the searchList,
+you {\em cannot} look up \code{\$myObject}!  You can look up only the 
+attributes/keys {\em inside} `myObject'.
+
+Earlier versions of Cheetah did not allow you to override Python builtin
+names, but this was fixed in Cheetah 0.9.15.  
+
+If your template will be used as a Webware servlet, do not override methods
+'name' and 'log' in the \code{Template} instance or it will interfere with
+Webware's logging.  However, it {\em is} OK to use those variables in a higher
+namespace, since Webware doesn't know about Cheetah namespaces.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Missing Values}
+\label{language.namemapper.missing}
+
+If NameMapper can not find a Python value for a Cheetah variable name, it will
+raise the NameMapper.NotFound exception.  You can use the \code{\#errorCatcher}
+directive (section \ref{errorHandling.errorCatcher}) or {\bf errorCatcher}
+Template constructor argument (section \ref{howWorks.constructing}) to specify
+an alternate behaviour. BUT BE AWARE THAT errorCatcher IS ONLY INTENDED FOR
+DEBUGGING!
+
+To provide a default value for a placeholder, write it like this:
+\code{\$getVar('varName', 'default value')}.  If you don't specify a default
+and the variable is missing, \code{NameMapper.NotFound} will be raised.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Directive Syntax Rules}
+\label{language.directives.syntax}
+
+
+Directive tags begin with a hash character (\#) and are used for comments,
+loops, conditional blocks, includes, and all other advanced features. Cheetah
+uses a Python-like syntax inside directive tags and understands any valid
+Python expression.  {\bf However, unlike Python, Cheetah does not use colons
+(:) and indentation to mark off multi-line directives.}  That doesn't work in
+an environment where whitespace is significant as part of the text.  Instead,
+multi-line directives like \code{\#for} have  corresponding closing tags
+(\code{\#end for}).  Most directives are direct mirrors of Python statements.
+
+Many directives have arguments after the opening tag, which must be in the
+specified syntax for the tag.  All end tags have the following syntax:
+\begin{verbatim}
+#end TAG_NAME [EXPR]
+\end{verbatim}
+The expression is ignored, so it's essentially a comment.  
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{Directive closures and whitespace handling}
+\label{language.directives.closures}
+Directive tags can be closed explicitly with \code{\#}, or implicitly with the
+end of the line if you're feeling lazy.
+
+\begin{verbatim}
+#block testBlock #
+Text in the body of the
+block directive
+#end block testBlock #
+\end{verbatim}
+is identical to:
+\begin{verbatim}
+#block testBlock
+Text in the body of the
+block directive
+#end block testBlock
+\end{verbatim}
+
+When a directive tag is closed explicitly, it can be followed with other text on
+the same line:
+
+\begin{verbatim}
+bah, bah, #if $sheep.color == 'black'# black#end if # sheep.
+\end{verbatim}
+
+When a directive tag is closed implicitly with the end of the line, all trailing
+whitespace is gobbled, including the newline character:
+\begin{verbatim}
+"""
+foo #set $x = 2 
+bar
+"""
+outputs 
+"""
+foo bar
+"""
+
+while 
+"""
+foo #set $x = 2 #
+bar
+"""
+outputs 
+"""
+foo 
+bar
+"""
+\end{verbatim}
+
+When a directive tag is closed implicitly AND there is no other text on the
+line, the ENTIRE line is gobbled up including any preceeding whitespace:
+\begin{verbatim}
+"""
+foo 
+   #set $x = 2 
+bar
+"""
+outputs 
+"""
+foo
+bar
+"""
+
+while 
+"""
+foo 
+ - #set $x = 2
+bar
+"""
+outputs 
+"""
+foo 
+ - bar
+"""
+\end{verbatim}
+
+The \code{\#slurp} directive (section \ref{output.slurp}) also gobbles up
+whitespace.
+
+Spaces outside directives are output {\em exactly} as written.  In the 
+black sheep example, there's a space before ``black'' and another before
+``sheep''.  So although it's legal to put multiple directives on one line,
+it can be hard to read.
+
+\begin{verbatim}
+#if $a# #echo $a + 1# #end if
+      - There's a space between each directive, 
+        or two extra spaces total.
+#if $a##echo $a + 1##end if
+      - No spaces, but you have to look closely
+        to verify none of the ``##'' are comment markers.
+#if $a##echo $a + 1##end if     ### A comment.
+      - In ``###'', the first ``#'' ends the directive, 
+        the other two begin the comment.  (This also shows
+	how you can add extra whitespace in the directive
+	tag without affecting the output.)
+#if $a##echo $a + 1##end if     # ## A comment.
+      - More readable, but now there's a space before the
+        comment.
+\end{verbatim}
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
+
+% # vim: sw=4 ts=4 expandtab
diff --git a/docs/users_guide_2_src/05_placeholders_and_the_namemapper.txt b/docs/users_guide_2_src/05_placeholders_and_the_namemapper.txt
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/users_guide_2_src/05_placeholders_and_the_namemapper.txt
diff --git a/docs/users_guide_2_src/06_comments.txt b/docs/users_guide_2_src/06_comments.txt
new file mode 100755
index 0000000..36323cf
--- /dev/null
+++ b/docs/users_guide_2_src/06_comments.txt
@@ -0,0 +1,99 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Comments}
+\label{comments}
+
+Comments are used to mark notes, explanations, and decorative text that should
+not appear in the output.  Cheetah maintains the comments in the Python module
+it generates from the Cheetah source code. There are two forms of the comment
+directive: single-line and multi-line.
+
+All text in a template definition that lies between two hash characters
+(\code{\#\#}) and the end of the line is treated as a single-line comment and
+will not show up in the output, unless the two hash characters are escaped with
+a backslash.
+\begin{verbatim}
+##=============================  this is a decorative comment-bar
+$var    ## this is an end-of-line comment
+##=============================
+\end{verbatim}
+
+Any text between \code{\#*} and \code{*\#} will be treated as a multi-line
+comment.
+\begin{verbatim}
+#*
+   Here is some multiline
+   comment text
+*#
+\end{verbatim}
+
+If you put blank lines around method definitions or loops to separate them,
+be aware that the blank lines will be output as is.  To avoid this, make sure
+the blank lines are enclosed in a comment.  Since you normally have a
+comment before the next method definition (right?), you can just extend that
+comment to include the blank lines after the previous method definition, like
+so:
+\begin{verbatim}
+#def method1
+... lines ...
+#end def
+#*
+
+
+   Description of method2.
+   $arg1, string, a phrase.
+*#
+#def method2($arg1)
+... lines ...
+#end def
+\end{verbatim}
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Docstring Comments}
+\label{comments.docstring}
+
+Python modules, classes, and methods can be documented with inline
+'documentation strings' (aka 'docstrings').  Docstrings, unlike comments, are
+accesible at run-time. Thus, they provide a useful hook for interactive help
+utilities.  
+
+Cheetah comments can be transformed into doctrings by adding one of the
+following prefixes:
+
+\begin{verbatim}
+##doc: This text will be added to the method docstring
+#*doc: If your template file is MyTemplate.tmpl, running "cheetah compile"
+       on it will produce MyTemplate.py, with a class MyTemplate in it,
+       containing a method .respond().  This text will be in the .respond()
+       method's docstring. *#
+
+##doc-method: This text will also be added to .respond()'s docstring
+#*doc-method: This text will also be added to .respond()'s docstring *#
+
+##doc-class: This text will be added to the MyTemplate class docstring
+#*doc-class: This text will be added to the MyTemplate class docstring *#
+
+##doc-module: This text will be added to the module docstring MyTemplate.py
+#*doc-module: This text will be added to the module docstring MyTemplate.py*#
+\end{verbatim}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Header Comments}
+\label{comments.headers}
+Cheetah comments can also be transformed into module header comments using the
+following syntax:
+
+\begin{verbatim}
+##header: This text will be added to the module header comment
+#*header: This text will be added to the module header comment *#
+\end{verbatim}
+
+Note the difference between \code{\#\#doc-module: } and \code{header: }:
+``cheetah-compile'' puts \code{\#\#doc-module: } text inside the module
+docstring.  \code{header: } makes the text go {\em above} the docstring, as a
+set of \#-prefixed comment lines.
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
diff --git a/docs/users_guide_2_src/07_output.txt b/docs/users_guide_2_src/07_output.txt
new file mode 100755
index 0000000..742291e
--- /dev/null
+++ b/docs/users_guide_2_src/07_output.txt
@@ -0,0 +1,548 @@
+\section{Generating, Caching and Filtering Output}
+\label{output}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Output from complex expressions: \#echo}
+\label{output.echo}
+
+Syntax:
+\begin{verbatim}
+#echo EXPR
+\end{verbatim}
+
+The \code{\#echo} directive is used to echo the output from expressions that
+can't be written as simple \$placeholders.  
+
+\begin{verbatim}
+Here is my #echo ', '.join(['silly']*5) # example 
+\end{verbatim}
+
+This produces:
+
+\begin{verbatim}
+Here is my silly, silly, silly, silly, silly example.
+\end{verbatim}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Executing expressions without output: \#silent}
+\label{output.silent}
+
+Syntax:
+\begin{verbatim}
+#silent EXPR
+\end{verbatim}
+
+\code{\#silent} is the opposite of \code{\#echo}.  It executes an expression
+but discards the output.
+
+\begin{verbatim}
+#silent $myList.reverse()
+#silent $myList.sort()
+Here is #silent $covertOperation() # nothing
+\end{verbatim}
+
+If your template requires some Python code to be executed at the beginning;
+(e.g., to calculate placeholder values, access a database, etc), you can put
+it in a "doEverything" method you inherit, and call this method using
+\code{\#silent} at the top of the template.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{One-line \#if}
+\label{output.oneLineIf}
+
+Syntax:
+\begin{verbatim}
+#if EXPR1 then EXPR2 else EXPR3#
+\end{verbatim}
+
+The \code{\#if} flow-control directive (section \ref{flowControl.if}) has a
+one-line counterpart akin to Perl's and C's \code{?:} operator.
+If \code{EXPR1} is true, it evaluates \code{EXPR2} and outputs the result (just
+like \code{\#echo\ EXPR2\#}).  Otherwise it evaluates \code{EXPR3} and outputs
+that result.  This directive is short-circuiting, meaning the expression that
+isn't needed isn't evaluated.
+
+You MUST include both 'then' and 'else'.  If this doesn't work for you or you
+don't like the style use multi-line \code{\#if} directives (section
+\ref{flowControl.if}).
+
+The trailing \code{\#} is the normal end-of-directive character.  As usual
+it may be omitted if there's nothing after the directive on the same line.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Caching Output}
+\label{output.caching}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{Caching individual placeholders}
+\label{output.caching.placeholders}
+
+By default, the values of each \$placeholder is retrieved and
+interpolated for every request. However, it's possible to cache the values
+of individual placeholders if they don't change very often, in order to 
+speed up the template filling.
+                         
+To cache the value of a single \code{\$placeholder}, add an asterisk after the
+\$; e.g.,  \code{\$*var}.  The first time the template is
+filled, \code{\$var} is looked up.  Then whenever the template is filled again,
+the cached value is used instead of doing another lookup.  
+
+The \code{\$*} format caches ``forever''; that is, as long as the template
+instance remains in memory.  It's also possible to cache for a certain time
+period using the form \code{\$*<interval>*variable}, where \code{<interval>} is
+the interval.  The time interval can be specified in seconds (5s), minutes
+(15m), hours (3h), days (2d) or weeks (1.5w). The default is minutes.
+
+\begin{verbatim}
+<HTML>
+<HEAD><TITLE>$title</TITLE></HEAD>
+<BODY>
+
+$var ${var}           ## dynamic - will be reinterpolated for each request
+$*var2 $*{var2}       ## static - will be interpolated only once at start-up
+$*5*var3 $*5*{var3}   ## timed refresh - will be updated every five minutes.
+
+</BODY>
+</HTML>
+\end{verbatim}
+
+Note that ``every five minutes'' in the example really means every five
+minutes: the variable is looked up again when the time limit is reached,
+whether the template is being filled that frequently or not.  Keep this in
+mind when setting refresh times for CPU-intensive or I/O intensive 
+operations.
+
+If you're using the long placeholder syntax, \verb+${}+, the braces go only
+around the placeholder name: \verb+$*.5h*{var.func('arg')}+.
+
+Sometimes it's preferable to explicitly invalidate a cached item whenever
+you say so rather than at certain time intervals.  You can't do this with
+individual placeholders, but you can do it with cached regions, which will
+be described next.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{Caching entire regions}
+\label{output.caching.regions}
+
+Syntax:
+\begin{verbatim}
+#cache [id=EXPR] [timer=EXPR] [test=EXPR]
+#end cache
+\end{verbatim}
+
+The \code{\#cache} directive is used to cache a region of
+content in a template.  The region is cached as a single unit, after 
+placeholders and directives inside the region have been evaluated.  If there
+are any \code{\$*<interval>*var} placholders inside the cache
+region, they are refreshed only when {\em both} the cache region {\em and} the 
+placeholder are simultaneously due for a refresh.
+
+Caching regions offers more flexibility than caching individual placeholders.
+You can specify the refresh interval using a placeholder or
+expression, or refresh according to other criteria rather than a certain
+time interval.
+
+\code{\#cache} without arguments caches the region statically, the same
+way as \code{\$*var}.  The region will not be automatically refreshed.
+
+To refresh the region at an interval, use the \code{timer=EXPRESSION} argument,
+equivalent to \code{\$*<interval>*}.  The expression should evaluate to a
+number or string that is a valid interval (e.g., 0.5, '3m', etc).
+
+To refresh whenever an expression is true, use \code{test=EXPRESSION}.
+The expression can be a method/function returning true or false, a boolean
+placeholder, several of these joined by \code{and} and/or \code{or}, or any
+other expression.  If the expression contains spaces, it's easier to
+read if you enclose it in \code{()}, but this is not required.
+
+To refresh whenever you say so, use \code{id=EXPRESSION}.  Your program can
+then call \code{.refreshCache(ID)} whenever it wishes.  This is useful if the
+cache depends on some external condition that changes infrequently but has just
+changed now.
+
+You can combine arguments by separating them with commas.  For instance, you can
+specify both \code{id=} and \code{interval=}, or \code{id=} and \code{test=}.
+(You can also combine interval and test although it's not very useful.)
+However, repeating an argument is undefined.
+
+\begin{verbatim}
+#cache
+This is a static cache.  It will not be refreshed.
+$a $b $c
+#end cache
+
+#cache timer='30m', id='cache1'
+#for $cust in $customers
+$cust.name:
+$cust.street - $cust.city
+#end for
+#end cache
+
+#cache id='sidebar', test=$isDBUpdated
+... left sidebar HTML ...
+#end cache
+
+#cache id='sidebar2', test=($isDBUpdated or $someOtherCondition)
+... right sidebar HTML ...
+#end cache
+\end{verbatim}
+
+
+The \code{\#cache} directive cannot be nested.
+
+We are planning to add a \code{'varyBy'} keyword argument in the future that
+will allow a separate cache instances to be created for a variety of conditions,
+such as different query string parameters or browser types. This is inspired by
+ASP.net's varyByParam and varyByBrowser output caching keywords.
+
+% @@MO: Can we cache by Webware sessions?  What about sessions where the
+% session ID is encoded as a path prefix in the URI?  Need examples.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#raw}
+\label{output.raw}
+
+Syntax:
+\begin{verbatim}
+#raw
+#end raw
+\end{verbatim}
+
+Any section of a template definition that is inside a \code{\#raw \ldots
+\#end raw} tag pair will be printed verbatim without any parsing of
+\$placeholders or other directives. This can be very useful for debugging, or
+for Cheetah examples and tutorials.
+
+\code{\#raw} is conceptually similar to HTML's \code{<PRE>} tag and LaTeX's
+\code{\\verbatim\{\}} tag, but unlike those tags, \code{\#raw} does not cause
+the body to appear in a special font or typeface.  It can't, because Cheetah
+doesn't know what a font is.  
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#include}
+\label{output.include}
+
+Syntax:
+\begin{verbatim}
+#include [raw] FILENAME_EXPR
+#include [raw] source=STRING_EXPR
+\end{verbatim}
+
+The \code{\#include} directive is  used to include text from outside the
+template definition.  The text can come from an external file or from a
+\code{\$placeholder} variable.  When working with external files, Cheetah will
+monitor for changes to the included file and update as necessary.  
+
+This example demonstrates its use with external files:
+\begin{verbatim}
+#include "includeFileName.txt"
+\end{verbatim}
+The content of "includeFileName.txt" will be parsed for Cheetah syntax.
+
+And this example demonstrates use with \code{\$placeholder} variables:
+\begin{verbatim}
+#include source=$myParseText
+\end{verbatim}
+The value of \code{\$myParseText} will be parsed for Cheetah syntax. This is not
+the same as simply placing the \$placeholder tag ``\code{\$myParseText}'' in
+the template definition.  In the latter case, the value of \$myParseText would
+not be parsed.
+
+By default, included text will be parsed for Cheetah tags.  The argument
+``\code{raw}'' can be used to suppress the parsing.
+
+\begin{verbatim}
+#include raw "includeFileName.txt"
+#include raw source=$myParseText
+\end{verbatim}
+
+Cheetah wraps each chunk of \code{\#include} text inside a nested
+\code{Template} object.  Each nested template has a copy of the main
+template's searchList.  However, \code{\#set} variables are visible
+across includes only if the defined using the \code{\#set global} keyword.
+
+All directives must be balanced in the include file.  That is, if you start
+a \code{\#for} or \code{\#if} block inside the include, you must end it in
+the same include.  (This is unlike PHP, which allows unbalanced constructs
+in include files.)
+
+% @@MO: What did we decide about #include and the searchList?  Does it really
+% use a copy of the searchList, or does it share the searchList with the
+% parent?
+
+% @@MO: deleted
+%These nested templates share the same \code{searchList}
+%as the top-level template. 
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#slurp}
+\label{output.slurp}
+
+Syntax:
+\begin{verbatim}
+#slurp
+\end{verbatim}
+
+The \code{\#slurp} directive eats up the trailing newline on the line it
+appears in, joining the following line onto the current line.
+
+
+It is particularly useful in \code{\#for} loops:
+\begin{verbatim}
+#for $i in range(5)
+$i #slurp
+#end for
+\end{verbatim}
+outputs:
+\begin{verbatim}
+0 1 2 3 4
+\end{verbatim}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#indent}
+\label{output.indent}
+
+This directive is not implemented yet.  When/if it's completed, it will allow
+you to 
+\begin{enumerate}
+\item indent your template definition in a natural way (e.g., the bodies
+    of \code{\#if} blocks) without affecting the output
+\item add indentation to output lines without encoding it literally in the
+    template definition.  This will make it easier to use Cheetah to produce
+    indented source code programmatically (e.g., Java or Python source code).  
+\end{enumerate}
+
+There is some experimental code that recognizes the \code{\#indent}
+directive with options, but the options are purposely undocumented at this
+time.  So pretend it doesn't exist.  If you have a use for this feature
+and would like to see it implemented sooner rather than later, let us know
+on the mailing list.
+
+The latest specification for the future \code{\#indent} directive is in the
+TODO file in the Cheetah source distribution.
+
+% @@MO: disabled because it's not implemented and the spec is changing
+% \code{\#indent} decouples the indentation in the template definition from the
+% indentation in the output.  Normally, Cheetah outputs indentation exactly as
+% it sees it, no matter whether the indentation is on the first line of a 
+% paragraph, in front of a directive, or wherever.  \code{\#indent} has two main
+% uses:
+% \begin{enumerate}
+% \item To strip all indentation from source lines.  This lets you indent
+%     multiline directives (e.g., \code{\#if}, \code{\#for}) in a natural way
+%     without having that indentation appear in the output.
+% \item To indent every text line in the output according to a user-specified
+%     ``indentation level'', independent of whatever indentation the source lines
+%     may have.  This is useful for producing Python output, or any language that
+%     requires strict indentation levels at certain places.  To accomplish this,
+%     Cheetah adds a call to an indentation method at the beginning of every
+%     affected source line.
+% \end{enumerate}
+% 
+% To accomplish the first part, Cheetah removes leading whitespace from the
+% affected source lines before the compiler see them.  To accomplish the second
+% part, Cheetah keeps track of the current indentation level, a value you have
+% full control over.  At the beginning of every affected text line, Cheetah calls
+% a method that outputs the appropriate indentation string.  This affects only
+% lines in the template definition itself, not multiline placeholder values.  
+% See the \code{Indent} filter below to indent multiline placeholder values.
+% 
+% All \code{\#indent} commands operate on the lines physically below them in
+% the template definition until the next \code{\#indent}, regardless of scope.
+% This means they work thorugh all other directives (\code{\#def}, \code{\#for},
+% \code{\#if}, etc) -- so that if you turn on indentation inside a \code{\#def},
+% it remains in effect past the \code{\#end def}.
+% 
+% The following commands turn indentation on and off:
+% \begin{description}
+% \item{\code{\#indent on}}  Strip leading whitespace and add indentation to the
+%     following lines.  This fulfills use \#2 above.
+% \item{\code{\#indent off}} Do not strip leading whitespace or add indentation.
+%     This is Cheetah's default behavior.
+% \item{\code{\#indent strip}}  Strip leading whitespace but do {\em not} add
+%     indentation.  This fulfills use \#1 above.
+% \end{description}
+% 
+% Indentation by default uses real tabs.  But you can change the indentation
+% string thus:
+% \begin{verbatim}
+% ## Output four spaces for each indentation level.
+% #indent chars '    '
+% ## Output the mail reply prefix for each indentation level.
+% #indent chars '> '
+% ## Use a placeholder.
+% #indent chars $indentChars
+% ## Return to the default behavior.
+% #indent chars '\t'
+% \end{verbatim}
+% 
+% 
+% The following commands change the indentation level, which is a non-negative
+% integer initially at zero.  All of these commands implicitly do an 
+% \code{\#indent on}:
+% \begin{description}
+% \item{\code{\#indent ++}}  Increment the current indentation level.
+% \item{\code{\#indent --}}  Decrement the current indentation level.
+% \item{\code{\#indent +3}}  Add three indentation levels (or any number).
+% \item{\code{\#indent -3}}  Subtract three indentation levels (or any number).
+% \item{\code{\#indent =3}}   Set the indentation level to 3.
+% \item{\code{\#indent push +2}}  Save the current indentation level on a stack
+%     and add two.  
+% \item{\code{\#indent pop}}  Return to the most recently pushed level.  Raise
+%     \code{IndentationStackEmptyError} if there is no previous level.
+% \end{description}
+% 
+% The expressions after \code{+}/\code{-}/\code{=} may be numeric literals or
+% Cheetah expressions.  The effect is undefined if the value is negative.  There
+% may be whitespace after the \code{+}/\code{-}/\code{=} symbol.
+% The initial implementation uses a simple preprocessor that doesn't understand
+% newline characters in expressions.  \code{\\n} is fine, but not a real newline.
+% 
+% To indent multiline placeholder values using the current indentation level,
+% use the \code{Indent} filter:
+% \begin{verbatim}
+% #filter Indent
+% \end{verbatim}
+% It works like the default filter but adds indentation after every newline.  It
+% does not strip any leading whitespace.  It hooks into \code{\$self.\_indenter},
+% defined in \code{Cheetah.Utils.Indenter}.  This object keeps track of the
+% current indentation level.  Specifically, the filter calls
+% \code{\$self.\_indent()}, which is a shortcut to the indenter's
+% \code{.indent()} method.  This is the same thing \code{\#indent} does.
+% However, the filter is usable even when indentation is in
+% \code{off} or \code{strip} mode.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Ouput Filtering and \#filter}
+\label{output.filter}
+
+Syntax:
+\begin{verbatim}
+#filter FILTER_CLASS_NAME
+#filter $PLACEHOLDER_TO_A_FILTER_INSTANCE
+#filter None
+\end{verbatim}
+
+
+Output from \$placeholders is passed through an ouput filter.  The default
+filter merely returns a string representation of the placeholder value,
+unless the value is \code{None}, in which case the filter returns an empty
+string.  Only top-level placeholders invoke the filter; placeholders inside
+expressions do not.
+
+Certain filters take optional arguments to modify their behaviour.  To pass
+arguments, use the long placeholder syntax and precede each filter argument by
+a comma.  By convention, filter arguments don't take a \code{\$} prefix, to
+avoid clutter in the placeholder tag which already has plenty of dollar signs.
+For instance, the MaxLen filter takes an argument 'maxlen':
+
+\begin{verbatim}
+${placeholderName, maxlen=20}
+${functionCall($functionArg), maxlen=$myMaxLen}
+\end{verbatim}
+
+To change the output filter, use the \code{'filter'} keyword to the
+\code{Template} class constructor, or the \code{\#filter}
+directive at runtime (details below).  You may use \code{\#filter} as often as
+you wish to switch between several filters, if certain \code{\$placeholders}
+need one filter and other \code{\$placeholders} need another.
+
+The standard filters are in the module \code{Cheetah.Filters}.  Cheetah
+currently provides:
+
+\begin{description}
+\item{\code{Filter}}
+     \\ The default filter, which converts None to '' and everything else to
+     \code{str(whateverItIs)}.  This is the base class for all other filters,
+     and the minimum behaviour for all filters distributed with Cheetah.
+\item{\code{ReplaceNone}}
+     \\ Same.
+\item{\code{MaxLen}}
+     \\ Same, but truncate the value if it's longer than a certain length.
+     Use the 'maxlen' filter argument to specify the length, as in the
+     examples above.  If you don't specify 'maxlen', the value will not be
+     truncated.
+\item{\code{Pager}}
+     \\ Output a "pageful" of a long string.  After the page, output HTML
+     hyperlinks to the previous and next pages.  This filter uses several
+     filter arguments and environmental variables, which have not been 
+     documented yet.
+\item{\code{WebSafe}}
+     \\ Same as default, but convert HTML-sensitive characters ('$<$', '\&',
+     '$>$')
+     to HTML entities so that the browser will display them literally rather
+     than interpreting them as HTML tags.  This is useful with database values
+     or user input that may contain sensitive characters.  But if your values
+     contain embedded HTML tags you want to preserve, you do not want this 
+     filter.
+     
+     The filter argument 'also' may be used to specify additional characters to
+     escape.  For instance, say you want to ensure a value displays all on one
+     line.  Escape all spaces in the value with '\&nbsp', the non-breaking
+     space:
+\begin{verbatim}
+${$country, also=' '}}
+\end{verbatim}
+\end{description}
+
+To switch filters using a class object, pass the class using the
+{\bf filter} argument to the Template constructor, or via a placeholder to the
+\code{\#filter} directive: \code{\#filter \$myFilterClass}.  The class must be
+a subclass of \code{Cheetah.Filters.Filter}.  When passing a class object, the
+value of {\bf filtersLib} does not matter, and it does not matter where the
+class was defined.
+
+To switch filters by name, pass the name of the class as a string using the
+{\bf filter} argument to the Template constructor, or as a bare word (without
+quotes) to the \code{\#filter} directive: \code{\#filter TheFilter}.  The
+class will be looked up in the {\bf filtersLib}.
+
+The filtersLib is a module containing filter classes, by default
+\code{Cheetah.Filters}.  All classes in the module that are subclasses of
+\code{Cheetah.Filters.Filter} are considered filters.  If your filters are in
+another module, pass the module object as the {\bf filtersLib} argument to the
+Template constructor.  
+
+Writing a custom filter is easy: just override the \code{.filter} method.
+\begin{verbatim}
+    def filter(self, val, **kw):     # Returns a string.
+\end{verbatim}
+Return the {\em string} that should be output for `val'.  `val' may be any
+type.  Most filters return `' for \code{None}.  Cheetah passes one keyword
+argument: \verb+kw['rawExpr']+ is the placeholder name as it appears in
+the template definition, including all subscripts and arguments.  If you use
+the long placeholder syntax, any options you pass appear as keyword
+arguments.  Again, the return value must be a string.
+
+You can always switch back to the default filter this way:
+\code{\#filter None}.  This is easy to remember because "no filter" means the
+default filter, and because None happens to be the only object the default
+filter treats specially.
+
+We are considering additional filters; see
+\url{http://webware.colorstudy.net/twiki/bin/view/Cheetah/MoreFilters}
+for the latest ideas.
+
+%% @@MO: Is '#end filter' implemented?  Will it be?  Can filters nest?
+%% Will '#end filter' and '#filter None' be equivalent?
+
+%% @@MO: Tavis TODO: fix the description of the Pager filter.  It needs a howto.
+
+%% @@MO: How about using settings to provide default arguments for filters?
+%% Each filter could look up FilterName (or FilterNameDefaults) setting,
+%% whose value would be a dictionary containing keyword/value pairs.  These
+%% would be overridden by same-name keys passed by the placeholder.
+
+%% @@MO: If sed-filters (#sed) get added to Cheetah, give them a section here.
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
+
+% vim: shiftwidth=4 tabstop=4 expandtab
diff --git a/docs/users_guide_2_src/08_inheritanceEtc.txt b/docs/users_guide_2_src/08_inheritanceEtc.txt
new file mode 100755
index 0000000..3e76ce2
--- /dev/null
+++ b/docs/users_guide_2_src/08_inheritanceEtc.txt
@@ -0,0 +1,564 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Import, Inheritance, Declaration and Assignment}
+\label{inheritanceEtc}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#import and \#from directives}
+\label{inheritanceEtc.import}
+
+Syntax:
+\begin{verbatim}
+#import MODULE_OR_OBJECT [as NAME] [, ...]
+#from MODULE import MODULE_OR_OBJECT [as NAME] [, ...]
+\end{verbatim}
+
+
+The \code{\#import} and \code{\#from} directives are used to make external
+Python modules or objects available to placeholders.  The syntax is identical
+to the import syntax in Python.  Imported modules are visible globally to all
+methods in the generated Python class.
+
+\begin{verbatim}
+#import math
+#import math as mathModule
+#from math import sin, cos
+#from math import sin as _sin
+#import random, re
+#from mx import DateTime         # ## Part of Egenix's mx package.
+\end{verbatim}
+
+After the above imports, \code{\$math}, \code{\$mathModule}, 
+\code{\$sin}, \code{\$cos} and \code{\$\_sin}, \code{\$random}, \code{\$re} 
+and \code{\$DateTime} may be used in \code{\$placeholders} and expressions.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#extends}
+\label{inheritanceEtc.extends}
+
+Syntax:
+\begin{verbatim}
+#extends CLASS
+\end{verbatim}
+
+
+All templates are subclasses of \code{Cheetah.Template.Template}.  However,
+it's possible for a template to subclass another template or a pure Python
+class.  This is where \code{\#extends} steps in: it
+specifies the parent class.  It's equivalent to PSP's \code{``@page extends=''}
+directive. 
+
+Cheetah imports the class mentioned in an \code{\#extends} directive
+automatically if you haven't imported it yet.  The implicit importing works
+like this:
+
+\begin{verbatim}
+#extends Superclass   
+## Implicitly does '#from Superclass import Superclass'.
+
+#extends Cheetah.Templates.SkeletonPage
+## Implicitly does '#from Cheetah.Templates.SkeletonPage import SkeletonPage'.
+\end{verbatim}
+
+If your superclass is in an unusual location or in a module named 
+differently than the class, you must import it explicitly.  There is no
+support for extending from a class that is not imported; e.g., from a template
+dynamically created from a string.  Since the most practical way to
+get a parent template into a module is to precompile it, all parent templates
+essentially have to be precompiled.  
+
+There can be only one \code{\#extends} directive in a template and it
+may list only one class.  In other words, templates don't do multiple
+inheritance.  This is intentional: it's too hard to initialize multiple
+base classes correctly from inside a template.  However, you can do
+multiple inheritance in your pure Python classes.
+
+If your pure Python class overrides any of the standard \code{Template}
+methods such as \code{.\_\_init\_\_} or \code{.awake}, be sure to call
+the superclass method in your method or things will break.  Examples of calling
+the superclass method are in section \ref{tips.callingSuperclassMethods}.
+A list of all superclass methods is in section 
+\ref{tips.allMethods}.
+
+In all cases, the root superclass must be \code{Template}.  If your
+bottommost class is a template, simply omit the \code{\#extends} in it and it
+will automatically inherit from \code{Template}.  {\em If your bottommost class
+is a pure Python class, it must inherit from \code{Template} explicitly: }
+\begin{verbatim}
+from Cheetah.Template import Template
+class MyPurePythonClass(Template):
+\end{verbatim}
+
+If you're not keen about having your Python classes inherit from
+\code{Template}, create a tiny glue class that inherits both from your
+class and from \code{Template}.
+
+Before giving any examples we'll stress that Cheetah does {\em not}
+dictate how you should structure your inheritance tree.  As long as
+you follow the rules above, many structures are possible.
+
+Here's an example for a large web site that has not only a general site
+template, but also a template for this section of the site, and then a
+specific template-servlet for each URL.  (This is the ``inheritance
+approach'' discussed in the Webware chapter.)  Each template inherits from a
+pure Python class that contains methods/attributes used by the template.  We'll
+begin with the bottommost superclass and end with the specific
+template-servlet:
+
+\begin{verbatim}
+1.  SiteLogic.py (pure Python class containing methods for the site)
+        from Cheetah.Template import Template
+        class SiteLogic(Template):
+
+2.  Site.tmpl/py  (template containing the general site framework;
+                   this is the template that controls the output,
+                   the one that contains "<HTML><HEAD>...", the one
+                   that contains text outside any #def/#block.)
+        #from SiteLogic import SiteLogic
+        #extends SiteLogic
+        #implements respond
+
+3.  SectionLogic.py  (pure Python class with helper code for the section)
+        from Site import Site
+        class SectionLogic(Site)
+
+4.  Section.tmpl/py  (template with '#def' overrides etc. for the section)
+        #from SectionLogic import SectionLogic
+        #extends SectionLogic
+
+5.  page1Logic.py  (pure Python class with helper code for the template-servlet)
+        from Section import Section
+        class indexLogic(Section):
+
+6.  page1.tmpl/py  (template-servlet for a certain page on the site)
+        #from page1Logic import page1Logic
+        #extends page1Logic
+\end{verbatim}
+
+A pure Python classes might also contain methods/attributes that aren't used by
+their immediate child template, but are available for any descendant
+template to use if it wishes.  For instance, the site template might have
+attributes for the name and e-mail address of the site administrator, 
+ready to use as \$placeholders in any template that wants it.
+
+{\em Whenever you use \code{\#extends}, you often need \code{\#implements}
+too,} as in step 2 above.  Read the next section to understand what
+\code{\#implements} is and when to use it.
+
+% @@MO: Edmund suggests making some diagrams of inheritance chains.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#implements}
+\label{inheritanceEtc.implements}
+
+Syntax:
+\begin{verbatim}
+#implements METHOD
+\end{verbatim}
+
+You can call any \code{\#def} or \code{\#block} method directly and get its
+outpt.  The top-level content -- all the text/placeholders/directives outside any
+\code{\#def}/\code{\#block} -- gets concatenated and wrapped in a ``main
+method'', by default \code{.respond()}.  So if you call \code{.respond()}, you
+get the ``whole template output''.  When Webware calls \code{.respond()},
+that's what it's doing.  And when you do 'print t' or 'str(t)' on a template
+instance, you're taking advantage of the fact that Cheetah makes
+\code{.\_\_str\_\_()} an alias for the main method.
+
+That's all fine and dandy, but what if your application prefers to call another
+method name rather than \code{.respond()}?  What if it wants to call, say,
+\code{.send\_output()} instead?  That's where \code{\#implements} steps in.  It
+lets you choose the name for the main method.  Just put this in your template
+definition:
+\begin{verbatim}
+#implements send_output
+\end{verbatim}
+
+When one template extends another, every template in the inheritance chain
+has its own main method.  To fill the template, you invoke exactly one of
+these methods and the others are ignored.  The method you call may be in any of
+the templates in the inheritance chain: the base template, the leaf template,
+or any in between, depending on how you structure your application.  So you
+have two problems: (1) calling the right method name, and (2) preventing an
+undesired same-name subclass method from overriding the one you want to call.  
+
+Cheetah assumes the method you will call is \code{.respond()} because
+that's what Webware calls.  It further assumes the desired main method is the
+one in the lowest-level base template, because that works well with
+\code{\#block} as described in the Inheritance Approach for building Webware
+servlets (section \ref{webware.inheritance}), which was originally the
+principal use for Cheetah.  So when you use \code{\#extends}, Cheetah changes
+that template's main method to \code{.writeBody()} to get it out of the way and
+prevent it from overriding the base template's \code{.respond()}.  
+
+Unfortunately this assumption breaks down if the template is used in other
+ways.  For instance, you may want to use the main method in the highest-level
+leaf template, and treat the base template(s) as merely a library of
+methods/attributes.  In that case, the leaf template needs \code{\#implements
+respond} to change its main method name back to \code{.respond()} (or whatever
+your application desires to call).  Likewise, if your main method is in one of the
+intermediate templates in an inheritance chain, that template needs
+\code{\#implements respond}.
+
+The other way the assumption breaks down is if the main method {\em is} in
+the base template but that template extends a pure Python class.  Cheetah sees
+the \code{\#extends} and dutifully but incorrectly renames the method to
+\code{.writeBody()}, so you have to use \code{\#implements respond} to change
+it back.  Otherwise the dummy \code{.respond()} in \code{Cheetah.Template}
+is found, which outputs...  nothing.  {\bf So if you're using \code{\#extends}
+and get no output, the {\em first} thing you should think is, ``Do I need to
+add \code{\#implements respond} somewhere?'' }
+
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#set}
+\label{inheritanceEtc.set}
+
+Syntax:
+\begin{verbatim}
+#set [global] $var = EXPR
+\end{verbatim}
+
+\code{\#set} is used to create and update local variables at run time.
+The expression may be any Python expression.
+Remember to preface variable names with \$ unless they're part of an
+intermediate result in a list comprehension.
+
+Here are some examples:
+\begin{verbatim}
+#set $size = $length * 1096
+#set $buffer = $size + 1096
+#set $area = $length * $width
+#set $namesList = ['Moe','Larry','Curly']
+#set $prettyCountry = $country.replace(' ', '&nbsp;')
+\end{verbatim}
+
+\code{\#set} variables are useful to assign a short name to a
+\code{\$deeply.nested.value}, to a calculation, or to a printable version of
+a value.  The last example above converts any spaces in the 'country' value
+into HTML non-breakable-space entities, to ensure the entire value appears on
+one line in the browser.
+
+\code{\#set} variables are also useful in \code{\#if} expressions, but
+remember that complex logical routines should be coded in Python, not in
+Cheetah!
+\begin{verbatim}
+#if $size > 1500
+  #set $adj = 'large'
+#else
+  #set $adj = 'small'
+#end if
+\end{verbatim}
+Or Python's one-line equivalent, "A and B or C".  Remember that in this case,
+B must be a true value (not None, '', 0, [] or {}).  
+\begin{verbatim}
+#set $adj = $size > 1500 and 'large' or 'small'
+\end{verbatim}
+(Note: Cheetah's one-line \code{\#if} will not work for this, since it
+produces output rather than setting a variable.
+
+You can also use the augmented assignment operators:
+\begin{verbatim}
+## Increment $a by 5.
+#set $a += 5      
+\end{verbatim}
+
+By default, \code{\#set} variables are not visible in method calls or include
+files unless you use the \code{global} attribute: \code{\#set global \$var =
+EXPRESSION}.  Global variables are visible in all methods, nested templates and
+included files.  Use this feature with care to prevent surprises.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#del}
+\label{inheritanceEtc.del}
+
+Syntax:
+\begin{verbatim}
+#del $var
+\end{verbatim}
+
+\code{\#del} is the opposite of \code{\#set}.  It deletes a {\em local}
+variable.  Its usage is just like Python's \code{del} statement:
+\begin{verbatim}
+#del $myVar
+#del $myVar, $myArray[5]
+\end{verbatim}
+
+Only local variables can be deleted.  There is no directive to delete a
+\code{\#set global} variable, a searchList variable, or any other type of
+variable.  
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#attr}
+\label{inheritanceEtc.attr}
+
+Syntax:
+\begin{verbatim}
+#attr $var = EXPR
+\end{verbatim}
+
+The \code{\#attr} directive creates class attributes in the generated Python
+class.  It should be used to assign simple Python literals such as numbers or
+strings.  In particular, the expression must {\em not} depend on searchList
+values or \code{\#set} variables since those are not known at compile time.
+
+\begin{verbatim}
+#attr $title = "Rob Roy"
+#attr $author = "Sir Walter Scott"
+#attr $version = 123.4
+\end{verbatim}
+
+This template or any child template can output the value thus:
+\begin{verbatim}
+$title, by $author, version $version
+\end{verbatim}
+
+If you have a library of templates derived from etexts
+(\url{http://www.gutenberg.org/}), you can extract the titles and authors
+and put them in a database (assuming the templates have been compiled into
+.py template modules):
+
+%\begin{verbatim}
+%import glob
+%
+%\end{verbatim}
+%
+% @@MO: Finish this example.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#def}
+\label{inheritanceEtc.def}
+
+Syntax:
+\begin{verbatim}
+#def METHOD[(ARGUMENTS)]
+#end def
+\end{verbatim}
+
+Or the one-line variation:
+\begin{verbatim}
+#def METHOD[(ARGUMENTS)] : TEXT_AND_PLACEHOLDERS
+\end{verbatim}
+
+
+The \code{\#def} directive is used to define new methods in the generated
+Python class, or to override superclass methods.  It is analogous to Python's
+\code{def} statement.  The directive is silent, meaning it does not itself
+produce any output.  However, the content of the method will be inserted into
+the output (and the directives executed) whenever the method is later called by
+a \$placeholder.
+
+\begin{verbatim}
+#def myMeth()
+This is the text in my method 
+$a $b $c(123)  ## these placeholder names have been defined elsewhere
+#end def
+
+## and now use it...
+$myMeth()
+\end{verbatim}
+
+The arglist and parentheses can be omitted:
+\begin{verbatim}
+#def myMeth
+This is the text in my method 
+$a $b $c(123)
+#end def
+
+## and now use it...
+$myMeth
+\end{verbatim}
+
+Methods can have arguments and have defaults for those arguments, just like
+in Python.  Remember the \code{\$} before variable names:
+\begin{verbatim}
+#def myMeth($a, $b=1234)
+This is the text in my method 
+$a - $b
+#end def
+
+## and now use it...
+$myMeth(1)
+\end{verbatim}
+
+The output from this last example will be:
+
+\begin{verbatim}
+This is the text in my method 
+1 - 1234
+\end{verbatim}
+
+There is also a single line version of the \code{\#def} directive.  
+{\bf Unlike the multi-line directives, it uses a colon (:) to delimit the method
+signature and body}:
+\begin{verbatim}
+#attr $adj = 'trivial'
+#def myMeth: This is the $adj method 
+$myMeth
+\end{verbatim}
+Leading and trailing whitespace is stripped from the method.  This is in
+contrast to:
+\begin{verbatim}
+#def myMeth2
+This is the $adj method
+#end def
+\end{verbatim}
+where the method includes a newline after "method".  If you don't want the
+newline, add \code{\#slurp}:
+\begin{verbatim}
+#def myMeth3
+This is the $adj method#slurp
+#end def
+\end{verbatim}
+
+Because \code{\#def} is handled at compile time, it can appear above or
+below the placeholders that call it.  And if a superclass placeholder
+calls a method that's overridden in a subclass, it's the subclass method
+that will be called.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#block ... \#end block}
+\label{inheritanceEtc.block}
+
+
+The \code{\#block} directive allows you to mark a section of your template that
+can be selectively reimplemented in a subclass.  It is very useful for
+changing part of a template without having to copy-paste-and-edit
+the entire thing.  The output from a template definition that uses blocks will
+be identical to the output from the same template with the \code{\#block \ldots
+\#end block} tags removed. 
+
+({\em Note:} don't be confused by the generic word `block'' in this Guide,
+which means a section of code inside {\em any} \code{\#TAG \ldots \#end TAG}
+pair.  Thus, an if-block, for-block, def-block, block-block etc.  In this
+section we are talking only of block-blocks.)
+
+To reimplement the block, use the \code{\#def} directive.  The magical effect
+is that it appears to go back and change the output text {\em at the point the
+original block was defined} rather than at the location of the
+reimplementation.
+
+\begin{verbatim}
+#block testBlock
+Text in the contents 
+area of the block directive
+#if $testIt
+$getFoo() 
+#end if
+#end block testBlock
+\end{verbatim}
+
+You can repeat the block name in the \code{\#end block} directive or not, as
+you wish.
+
+\code{\#block} directives can be nested to any depth.
+
+\begin{verbatim}
+#block outerBlock
+Outer block contents 
+
+#block innerBlock1
+inner block1 contents 
+#end block innerBlock1
+
+#block innerBlock2
+inner block2 contents 
+#end block innerBlock2
+
+#end block outerBlock
+\end{verbatim}
+
+Note that the name of the block is optional for the \code{\#end block} tag.
+
+Technically, \code{\#block} directive is equivalent to a \code{\#def} directive
+followed immediately by a \code{\#placeholder} for the same name.  In fact,
+that's what Cheetah does.  Which means you can use \code{\$theBlockName}
+elsewhere in the template to output the block content again.
+
+There is a one-line \code{\#block} syntax analagous to the one-line 
+\code{\#def}.  
+
+The block must not require arguments because the implicit placeholder that's
+generated will call the block without arguments.
+
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
+
+
+Object-Oriented Documents
+-------------------------
+
+..
+    :label: howWorks.objoriented
+
+Because Cheetah documents are actually class definitions, templates may inherit
+from one another in a natural way, using regular Python semantics. For
+instance, consider this template, FrogBase.tmpl::
+
+    #def title
+    This document has not defined its title
+    #end def
+    #def htTitle
+    $title
+    #end def
+    <HTML><HEAD>
+    <TITLE>$title</TITLE>
+    </HEAD><BODY>
+    <H1>$htTitle</H1>
+    $body
+    </BODY></HTML>
+
+And its subclassed document, Frog1.tmpl::
+
+    #from FrogBase import FrogBase
+    #extends FrogBase
+    #def title
+    The Frog Page
+    #end def
+    #def htTitle
+    The <IMG SRC="Frog.png"> page
+    #end def
+    #def body
+    ... lots of info about frogs ...
+    #end def
+
+
+This is a classic use of inheritance. The parent "template" is simply an
+abstract superclass.  Each document specializes the output of its parent.
+For instance, here the parent defines
+``\$htTitle`` so that by default it's identical to whatever the 
+``\$title`` is, but it can also be customized.  
+
+In many other templating systems, you'd have to use case statements or
+if-elseif blocks of some sort, repeated in many different sections of code.
+
+While we show another Cheetah document inheriting from this parent, a Python
+class can inherit from it just as easily. This Python class could define its
+programmatically-driven value for ``\$body`` and ``\$title``, simply by
+defining body() and title() methods that return a string.  (Actually they
+can return anything, but we'll get into that later.)  ::
+
+    from FrogBase import FrogBase
+    class Frog2(FrogBase):
+        def title(self):
+            return "Frog 2 Page"
+        # We don't override .htTitle, so it defaults to "Frog 2 Page" too.
+        def body(self):
+            return " ... more info about frogs ..."
+
+Similarly, the Cheetah document can inherit from an arbitrary class. That's
+how Cheetah makes templates usable as Webware servlets, by subclassing
+``Servlet``.  This technique should be possible for non-Webware systems
+too.
+
+(*Note:*\ ``FrogBase.tmpl`` could be improved by using the
+``\#block`` directive, section \ref{inheritanceEtc.block}.)
+
+
diff --git a/docs/users_guide_2_src/09_flowControl.txt b/docs/users_guide_2_src/09_flowControl.txt
new file mode 100755
index 0000000..75a5845
--- /dev/null
+++ b/docs/users_guide_2_src/09_flowControl.txt
@@ -0,0 +1,414 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Flow Control}
+\label{flowControl}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#for ... \#end for}
+\label{flowControl.for}
+
+Syntax:
+\begin{verbatim}
+#for $var in EXPR
+#end for
+\end{verbatim}
+
+
+The \code{\#for} directive iterates through a sequence.  The syntax is the same
+as Python,  but remember the \code{\$} before variables.
+
+Here's a simple client listing:
+\begin{verbatim}
+<TABLE>
+#for $client in $service.clients
+<TR>
+<TD>$client.surname, $client.firstname</TD>
+<TD><A HREF="mailto:$client.email" >$client.email</A></TD>
+</TR>
+#end for
+</TABLE>
+\end{verbatim}
+
+Here's how to loop through the  keys and values of a dictionary:
+\begin{verbatim}
+<PRE>
+#for $key, $value in $dict.items()
+$key: $value
+#end for
+</PRE>
+\end{verbatim}
+
+Here's how to create list of numbers separated by hyphens. This ``\#end for''
+tag shares the last line to avoid introducing a newline character after each
+hyphen.  
+\begin{verbatim}
+#for $i in range(15)
+$i - #end for
+\end{verbatim}
+
+If the location of the \code{\#end for} offends your sense of indentational
+propriety, you can do this instead:
+\begin{verbatim}
+#for $i in $range(15)
+$i - #slurp
+#end for
+\end{verbatim}
+
+The previous two examples will put an extra hyphen after last number.  Here's
+how to get around that problem, using the \code{\#set} directive, which will be
+dealt with in more detail below.
+\begin{verbatim}
+#set $sep = '' 
+#for $name in $names 
+$sep$name 
+#set $sep = ', ' 
+#end for 
+\end{verbatim}
+
+Although to just put a separator between strings, you don't need a for loop:
+\begin{verbatim}
+#echo ', '.join($names)
+\end{verbatim}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#repeat ... \#end repeat}
+\label{flowControl.repeat}
+
+Syntax:
+\begin{verbatim}
+#repeat EXPR
+#end repeat
+\end{verbatim}
+
+
+Do something a certain number of times.
+The argument may be any numeric expression.
+If it's zero or negative, the loop will execute zero times.
+\begin{verbatim}
+#repeat $times + 3
+She loves me, she loves me not.
+#repeat
+She loves me.
+\end{verbatim}
+
+
+Inside the loop, there's no way to tell which iteration you're on.  If you
+need a counter variable, use \code{\#for} instead with Python's \code{range}
+function.  Since Python's ranges are base 0 by default, there are two ways
+to start counting at 1.  Say we want to count from 1 to 5, and that
+\code{\$count} is 5.
+\begin{verbatim}
+#for $i in $range($count)
+#set $step = $i + 1
+$step.  Counting from 1 to $count.
+#end for
+
+
+#for $i in $range(1, $count + 1)
+$i.  Counting from 1 to $count.
+#end for
+\end{verbatim}
+
+
+A previous implementation used a local variable \code{\$i} as the repeat
+counter.  However, this prevented instances of \code{\#repeat} from
+being nested.  The current implementation does not have this problem as it
+uses a new local variable for every instance of \code{\#repeat}.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#while ... \#end while}
+\label{flowControl.while}
+
+Syntax:
+\begin{verbatim}
+#while EXPR
+#end while
+\end{verbatim}
+
+
+\code{\#while} is the same as Python's \code{while} statement.  It may be
+followed by any boolean expression:
+\begin{verbatim}
+#while $someCondition('arg1', $arg2)
+The condition is true.
+#end while
+\end{verbatim}
+
+Be careful not to create an infinite loop.  \code{\#while 1} will loop until
+the computer runs out of memory.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#if ... \#else if ... \#else ... \#end if}
+\label{flowControl.if}
+
+Syntax:
+\begin{verbatim}
+#if EXPR
+#else if EXPR
+#elif EXPR
+#else
+#end if
+\end{verbatim}
+
+
+The \code{\#if} directive and its kin are used to display a portion of text
+conditionally. \code{\#if} and \code{\#else if} should be followed by a
+true/false expression, while \code{\#else} should not.  Any valid Python 
+expression is allowed.  As in Python, the expression is true unless it evaluates
+to 0, '', None, an empty list, or an empty dictionary.  In deference to Python,
+\code{\#elif} is accepted as a synonym for \code{\#else if}.
+
+Here are some examples:
+\begin{verbatim}
+#if $size >= 1500
+It's big
+#else if $size < 1500 and $size > 0 
+It's small
+#else
+It's not there
+#end if
+\end{verbatim}
+
+\begin{verbatim}
+#if $testItem($item)
+The item $item.name is OK.
+#end if
+\end{verbatim}
+ 
+Here's an example that combines an \code{\#if} tag with a \code{\#for} tag.
+\begin{verbatim}
+#if $people
+<table>
+<tr>
+<th>Name</th>
+<th>Address</th>
+<th>Phone</th>
+</tr>
+#for $p in $people
+<tr>
+<td>$p.name</td>
+<td>$p.address</td>
+<td>$p.phone</td>
+</tr>
+#end for
+</table>
+#else
+<p> Sorry, the search did not find any people. </p>
+#end if
+\end{verbatim}
+
+See section \ref{output.oneLineIf} for the one-line \code{\#if} directive,
+which is equivalent to Perl's and C's \code{?:} operator.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#unless ... \#end unless}
+\label{flowControl.unless}
+
+Syntax:
+\begin{verbatim}
+#unless EXPR
+#end unless
+\end{verbatim}
+
+
+\code{\#unless} is the opposite of \code{\#if}: the text is executed if the
+condition is {\bf false}.  Sometimes this is more convenient.
+\code{\#unless EXPR} is equivalent to \code{\#if not (EXPR)}.
+
+\begin{verbatim}
+#unless $alive
+This parrot is no more!  He has ceased to be!
+'E's expired and gone to meet 'is maker! ...
+THIS IS AN EX-PARROT!!
+#end unless
+\end{verbatim}
+
+You cannot use \code{\#else if} or \code{\#else} inside an \code{\#unless}
+construct.  If you need those, use \code{\#if} instead.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#break and \#continue}
+\label{flowControl.break}
+
+Syntax:
+\begin{verbatim}
+#break
+#continue
+\end{verbatim}
+
+
+These directives are used as in Python. \code{\#break} will
+exit a \code{\#for} loop prematurely, while \code{\#continue} will immediately
+jump to the next iteration in the \code{\#for} loop.
+
+In this example the output list will not contain ``10 - ''. 
+\begin{verbatim}
+#for $i in range(15)
+#if $i == 10
+  #continue
+#end if
+$i - #slurp
+#end for
+\end{verbatim}
+
+In this example the loop will exit if it finds a name that equals 'Joe':
+\begin{verbatim}
+#for $name in $names
+#if $name == 'Joe'
+  #break
+#end if
+$name - #slurp
+#end for
+\end{verbatim}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#pass}
+\label{flowControl.pass}
+
+Syntax:
+\begin{verbatim}
+#pass
+\end{verbatim}
+
+
+The \code{\#pass} directive is identical to Python \code{pass} statement: it
+does nothing. It can be used when a statement is required syntactically but the
+program requires no action.
+
+The following example does nothing if only \$A is true
+\begin{verbatim}
+#if $A and $B
+   do something
+#elif $A
+  #pass
+#elif $B
+  do something
+#else
+  do something
+#end if
+\end{verbatim}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#stop}
+\label{flowControl.stop}
+
+Syntax:
+\begin{verbatim}
+#stop
+\end{verbatim}
+
+
+The \code{\#stop} directive is used to stop processing of a template at a
+certain point.  The output will show {\em only} what has been processed up to
+that point.  
+
+When \code{\#stop} is called inside an \code{\#include} it skips the rest of
+the included code and continues on from after the \code{\#include} directive.
+stop the processing of the included code.  Likewise, when \code{\#stop} is
+called inside a \code{\#def} or \code{\#block}, it stops only the \code{\#def}
+or \code{\#block}.
+
+\begin{verbatim}
+A cat
+#if 1
+  sat on a mat
+  #stop
+  watching a rat
+#end if
+in a flat.
+\end{verbatim}
+
+will print 
+\begin{verbatim}
+A cat
+  sat on a mat
+\end{verbatim}
+
+And
+\begin{verbatim}
+A cat
+#block action
+  sat on a mat
+  #stop
+  watching a rat
+#end block
+in a flat.
+\end{verbatim}
+
+will print
+
+\begin{verbatim}
+A cat
+  sat on a mat
+in a flat.
+\end{verbatim}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#return}
+\label{flowControl.return}
+
+Syntax:
+\begin{verbatim}
+#return
+\end{verbatim}
+
+
+This is used as in Python. \code{\#return} will exit the current method with a
+default return value of \code{None} or the value specified.  It may be used 
+only inside a \code{\#def} or a \code{\#block}.  
+
+Note that \code{\#return} is different from the \code{\#stop} directive,
+which returns the sum of all text output from the method in which it is called.
+The following examples illustrate this point:
+
+\begin{verbatim}
+1
+$test[1]
+3
+#def test
+1.5
+#if 1
+#return '123'
+#else
+99999
+#end if
+#end def
+\end{verbatim}
+
+will produce
+\begin{verbatim}
+1
+2
+3
+\end{verbatim}
+
+while
+\begin{verbatim}
+1
+$test
+3
+#def test
+1.5
+#if 1
+#stop
+#else
+99999
+#end if
+#end def
+\end{verbatim}
+
+will produce
+\begin{verbatim}
+1
+1.5
+3
+\end{verbatim}
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
diff --git a/docs/users_guide_2_src/10_errorHandling.txt b/docs/users_guide_2_src/10_errorHandling.txt
new file mode 100755
index 0000000..28eee3a
--- /dev/null
+++ b/docs/users_guide_2_src/10_errorHandling.txt
@@ -0,0 +1,145 @@
+\section{Error Handling}
+\label{errorHandling}
+
+There are two ways to handle runtime errors (exceptions) in Cheetah.  The first
+is with the Cheetah directives that mirror Python's structured exception
+handling statements. The second is with Cheetah's \code{ErrorCatcher}
+framework. These are described below.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#try ... \#except ... \#end try, \#finally, and \#assert}
+\label{errorHandling.directives}
+
+Cheetah's exception-handling directives are exact mirrors Python's 
+exception-handling statements.  See Python's documentation for details.  The
+following Cheetah code demonstrates their use:
+
+
+\begin{verbatim}
+#try
+  $mightFail()
+#except
+  It failed
+#end try
+
+#try
+  #assert $x == $y
+#except AssertionError
+  They're not the same!
+#end try
+
+#try
+  #raise ValueError
+#except ValueError
+  #pass
+#end try
+
+
+#try
+  $mightFail()
+#except ValueError
+  Hey, it raised a ValueError!
+#except NameMapper.NotFound
+  Hey, it raised a NameMapper.NotFound!
+#else
+  It didn't raise anything!
+#end try
+
+#try
+  $mightFail()
+#finally
+  $cleanup()
+#end try
+\end{verbatim}    
+
+Like Python, \code{\#except} and \code{\#finally} cannot appear in the same
+try-block, but can appear in nested try-blocks.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#errorCatcher and ErrorCatcher objects}
+\label{errorHandling.errorCatcher}
+
+Syntax:
+\begin{verbatim}
+#errorCatcher CLASS
+#errorCatcher $PLACEHOLDER_TO_AN_ERROR_CATCHER_INSTANCE
+\end{verbatim}
+
+
+\code{ErrorCatcher} is a debugging tool that catches exceptions that occur
+inside \code{\$placeholder} tags and provides a customizable warning to the
+developer.  Normally, the first missing namespace value raises a
+\code{NameMapper.NotFound} error and halts the filling of the template. This
+requires the developer to resolve the exceptions in order without seeing the
+subsequent output. When an \code{ErrorCatcher} is enabled, the developer can
+see all the exceptions at once as well as the template output around them.
+
+The \code{Cheetah.ErrorCatchers} module defines the base class for
+ErrorCatchers:
+
+\begin{verbatim}
+class ErrorCatcher:
+    _exceptionsToCatch = (NameMapper.NotFound,)
+    
+    def __init__(self, templateObj):
+        pass
+    
+    def exceptions(self):
+        return self._exceptionsToCatch
+    
+    def warn(self, exc_val, code, rawCode, lineCol):
+        return rawCode
+\end{verbatim}    
+
+This ErrorCatcher catches \code{NameMapper.NotFound} exceptions and leaves the
+offending placeholder visible in its raw form in the template output.  If the
+following template is executed:
+\begin{verbatim}
+#errorCatcher Echo
+#set $iExist = 'Here I am!'
+Here's a good placeholder: $iExist
+Here's bad placeholder: $iDontExist
+\end{verbatim}    
+
+the output will be:
+\begin{verbatim}
+Here's a good placeholder: Here I am!
+Here's bad placeholder: $iDontExist
+\end{verbatim}
+
+The base class shown above is also accessible under the alias
+\code{Cheetah.ErrorCatchers.Echo}.  \code{Cheetah.ErrorCatchers} also provides a
+number of specialized subclasses that warn about exceptions in different ways.
+\code{Cheetah.ErrorCatchers.BigEcho} will output
+
+\begin{verbatim}
+Here's a good placeholder: Here I am!
+Here's bad placeholder: ===============&lt;$iDontExist could not be found&gt;===============
+\end{verbatim}
+
+ErrorCatcher has a significant performance impact and is turned off by default.
+It can also be turned on with the \code{Template} class' \code{'errorCatcher'}
+keyword argument.  The value of this argument should either be a string
+specifying which of the classes in \code{Cheetah.ErrorCatchers} to use, or a
+class that subclasses \code{Cheetah.ErrorCatchers.ErrorCatcher}. The
+\code{\#errorCatcher} directive can also be used to change the errorCatcher part
+way through a template.
+
+\code{Cheetah.ErrorCatchers.ListErrors} will produce the same ouput as
+\code{Echo} while maintaining a list of the errors that can be retrieved later.
+To retrieve the list, use the \code{Template} class' \code{'errorCatcher'}
+method to retrieve the errorCatcher and then call its \code{listErrors} method.
+
+ErrorCatcher doesn't catch exceptions raised inside directives. 
+
+% @@MO: How do you turn ErrorCatcher off after turn it on.
+% '#ErrorCatcher None'?
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
+
+
+
+
diff --git a/docs/users_guide_2_src/11_parserInstructions.txt b/docs/users_guide_2_src/11_parserInstructions.txt
new file mode 100755
index 0000000..bfd6bc2
--- /dev/null
+++ b/docs/users_guide_2_src/11_parserInstructions.txt
@@ -0,0 +1,116 @@
+\section{Instructions to the Parser/Compiler}
+\label{parserInstructions}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#breakpoint}
+\label{parserInstructions.breakpoint}
+
+Syntax:
+\begin{verbatim}
+#breakpoint
+\end{verbatim}
+
+
+\code{\#breakpoint} is a debugging tool that tells the parser to stop
+parsing at a specific point. All source code from that point on will be ignored.
+
+The difference between \code{\#breakpoint} and \code{\#stop} is that
+\code{\#stop} occurs in normal templates (e.g., inside an \code{\#if}) but
+\code{\#breakpoint} is used only when debugging Cheetah.  Another difference is
+that \code{\#breakpoint} operates at compile time, while \code{\#stop} is
+executed at run time while filling the template.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\#compiler-settings}
+\label{parserInstructions.compiler-settings}
+
+Syntax:
+\begin{verbatim}
+#compiler-settings
+key = value    (no quotes)
+#end compiler-settings
+
+#compiler-settings reset
+\end{verbatim}
+
+
+The \code{\#compiler-settings} directive overrides Cheetah's standard settings,
+changing how it parses source code and generates Python code.  This
+makes it possible to change the behaviour of Cheetah's parser/compiler for a
+certain template, or within a portion of the template.
+
+The \code{reset} argument reverts to the default settings.  With \code{reset},
+there's no end tag.
+
+Here are some examples of what you can do:
+\begin{verbatim}
+$myVar
+#compiler-settings
+cheetahVarStartToken = @
+#end compiler-settings
+@myVar
+#compiler-settings reset
+$myVar
+\end{verbatim}
+
+
+\begin{verbatim}
+## normal comment
+#compiler-settings
+commentStartToken = //
+#end compiler-settings
+
+// new style of comment
+
+#compiler-settings reset
+
+## back to normal comments
+\end{verbatim}
+
+\begin{verbatim}
+#slurp
+#compiler-settings
+directiveStartToken = %
+#end compiler-settings
+
+%slurp
+%compiler-settings reset
+
+#slurp
+\end{verbatim}
+
+Here's a partial list of the settings you can change:
+\begin{enumerate}
+\item syntax settings
+     \begin{enumerate}
+     \item cheetahVarStartToken
+     \item commentStartToken
+     \item multilineCommentStartToken
+     \item multilineCommentEndToken
+     \item directiveStartToken
+     \item directiveEndToken
+     \end{enumerate}
+\item code generation settings
+     \begin{enumerate}
+     \item commentOffset
+     \item outputRowColComments
+     \item defDocStrMsg
+     \item useNameMapper
+     \item useAutocalling
+     \item reprShortStrConstants
+     \item reprNewlineThreshold
+     \end{enumerate}
+\end{enumerate}
+The meaning of these settings and their default values will be documented in
+the future.
+
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
+
+
+
+
diff --git a/docs/users_guide_2_src/12_moduleFormatting.txt b/docs/users_guide_2_src/12_moduleFormatting.txt
new file mode 100644
index 0000000..9c558e3
--- /dev/null
+++ b/docs/users_guide_2_src/12_moduleFormatting.txt
@@ -0,0 +1 @@
+.
diff --git a/docs/users_guide_2_src/13_tipsAndTroubleshooting.txt b/docs/users_guide_2_src/13_tipsAndTroubleshooting.txt
new file mode 100755
index 0000000..a7b58e5
--- /dev/null
+++ b/docs/users_guide_2_src/13_tipsAndTroubleshooting.txt
@@ -0,0 +1,549 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Tips, Tricks and Troubleshooting}
+\label{tips}
+
+Troubleshooting: make a precomiled template with "cheetah compile" and inspect
+the Python code.  Put $_CHEETAH__searchList in the template.  (Caveat about
+"<value>" results.)  Make a tiny template containing only the suspicious code
+and precompile it.  
+
+This chapter contains short stuff that doesn't fit anywhere else.
+
+See the Cheetah FAQ for more specialized issues and for troubleshooting tips.
+Check the wiki periodically for recent tips contributed by users.  If you
+get stuck and none of these resources help, ask on the mailing list.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Placeholder Tips}
+\label{tips.placeholder}
+
+Here's how to do certain important lookups that may not be obvious.
+For each, we show first the Cheetah expression and then the Python equivalent,
+because you can use these either in templates or in pure Python subclasses.
+The Cheetah examples use NameMapper shortcuts (uniform dotted notation, 
+autocalling) as much as possible.
+
+To verify whether a variable exists in the searchList:
+\begin{verbatim}
+$varExists('theVariable')
+self.varExists('theVariable')
+\end{verbatim}
+This is useful in \code{\#if} or \code{\#unless} constructs to avoid a
+\code{\#NameMapper.NotFound} error if the variable doesn't exist.  For instance,
+a CGI GET parameter that is normally supplied but in this case the user typed
+the URL by hand and forgot the parameter (or didn't know about it).
+(\code{.hasVar} is a synonym for \code{.varExists}.)
+
+To look up a variable in the searchList from a Python method:
+\begin{verbatim}
+self.getVar('theVariable')
+self.getVar('theVariable', myDefault)
+\end{verbatim}
+This is the equivalent to \code{\$theVariable} in the template.  If the 
+variable is missing, it returns the second argument, \code{myDefault}, if 
+present, or raises \code{NameMapper.NotFound} if there is no second argument.
+However, it usually easier to write your method so that all needed searchList
+values come in as method arguments.  That way the caller can just use a
+\code{\$placeholder} to specify the argument, which is less verbose than you
+writing a getVar call.
+
+To do a ``safe'' placeholder lookup that returns a default value if the
+variable is missing:
+\begin{verbatim}
+$getVar('theVariable', None)
+$getVar('theVariable', $myDefault)
+\end{verbatim}
+
+To get an environmental variable, put \code{os.environ} on the searchList as a
+container.  Or read the envvar in Python code and set a placeholder variable
+for it.
+
+Remember that variables found earlier in the searchList override same-name
+variables located in a later searchList object.  Be careful when adding objects
+containing other variables besides the ones you want (e.g., \code{os.environ},
+CGI parameters).  The "other" variables may override variables your application
+depends on, leading to hard-to-find bugs.  Also, users can inadvertently or
+maliciously set an environmental variable or CGI parameter you didn't expect,
+screwing up your program.  To avoid all this, know what your namespaces
+contain, and place the namespaces you have the most control over first.  For
+namespaces that could contain user-supplied "other" variables, don't put the
+namespace itself in the searchList; instead, copy the needed variables into
+your own "safe" namespace.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Diagnostic Output}
+\label{tips.diagnostic}
+
+If you need send yourself some debugging output, you can use \code{\#silent} to
+output it to standard error:
+\begin{verbatim}
+#silent $sys.stderr.write("Incorrigible var is '$incorrigible'.\n")
+#silent $sys.stderr.write("Is 'unknown' in the searchList? " +
+    $getVar("unknown", "No.") + "\n" )
+\end{verbatim}
+(Tip contributed by Greg Czajkowski.)
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{When to use Python methods}
+\label{tips.pythonMethods}
+
+You always have a choice whether to code your methods as Cheetah \code{\#def}
+methods or Python methods (the Python methods being located in a class your
+template inherits).  So how do you choose?
+
+Generally, if the method consists mostly of text and placeholders, use a 
+Cheetah method (a \code{\#def} method).  That's why \code{\#def} exists, to
+take the tedium out of writing those kinds of methods.  And if you have a
+couple \code{\#if} stanzas to \code{\#set} some variables, followed by a
+\code{\#for} loop, no big deal.  But if your method consists mostly of
+directives and only a little text, you're better off writing it in Python.
+Especially be on the watch for extensive use of \code{\#set}, \code{\#echo} and
+\code{\#silent} in a Cheetah method--it's a sure sign you're probably using the
+wrong language.  Of course, though, you are free to do so if you wish.  
+
+Another thing that's harder to do in Cheetah is adjacent or nested
+multiline stanzas (all those directives with an accompanying \code{\#end}
+directive).  Python uses indentation to show the beginning and end of nested
+stanzas, but Cheetah can't do that because any indentation shows up in the
+output, which may not be desired.  So unless all those extra spaces and tabs
+in the output are acceptable, you have to keep directives flush with the left
+margin or the preceding text.  
+
+The most difficult decisions come when you have conflicting goals.  What if
+a method generates its output in parts (i.e., output concatenation), contains
+many searchList placeholders and lots of text, {\em and} requires lots of
+\code{\#if \ldots \#set \ldots \#else \#set \ldots \#end if} stanzas.  A Cheetah
+method would be more advantageous in some ways, but a Python method in others.
+You'll just have to choose, perhaps coding groups of methods all the same
+way.  Or maybe you can split your method into two, one Cheetah and one Python,
+and have one method call the other.  Usually this means the Cheetah method
+calling the Python method to calculate the needed values, then the Cheetah
+method produces the output.  One snag you might run into though is that
+\code{\#set} currently can set only one variable per statement, so if your
+Python method needs to return multiple values to your Cheetah method, you'll
+have to do it another way.
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Calling superclass methods, and why you have to}
+\label{tips.callingSuperclassMethods}
+
+If your template or pure Python class overrides a standard method or attribute
+of \code{Template} or one of its base classes, you should call the superclass
+method in your method to prevent various things from breaking.  The most common
+methods to override are \code{.awake} and \code{.\_\_init\_\_}.  \code{.awake}
+is called automatically by Webware early during the web transaction, so it makes
+a convenient place to put Python initialization code your template needs.
+You'll definitely want to call the superclass \code{.awake} because it sets up
+many wonderful attributes and methods, such as those to access the CGI input
+fields.
+
+There's nothing Cheetah-specific to calling superclass methods, but
+because it's vital, we'll recap the standard Python techniques
+here. We mention only the solution for old-style classes because
+Cheetah classes are old-style (in other Python documentation, you will
+find the technique for new-style classes, but they are not listed here
+because they cannot be used with Cheetah if you use
+dynamically-compiled templates).
+
+\begin{verbatim}
+from Cheetah.Template import Template
+class MyClass(Template):
+	def awake(self, trans):
+		Template.awake(self, trans)
+		... great and exciting features written by me ...
+\end{verbatim}
+
+[ @@MO: Need to test this.  .awake is in Servlet, which is a superclass
+of Template.  Do we really need both imports?  Can we call
+Template.awake? ]
+
+To avoid hardcoding the superclass name, you can use this
+function \code{callbase()}, which emulates \code{super()} for older versions of
+Python.  It also works even \code{super()} does exist, so you don't have to
+change your servlets immediately when upgrading.  Note that the argument
+sequence is different than \code{super} uses.
+
+\begin{verbatim}
+===========================================================================
+# Place this in a module SOMEWHERE.py .  Contributed by Edmund Lian.
+class CallbaseError(AttributeError):
+    pass
+
+def callbase(obj, base, methodname='__init__', args=(), kw={},
+    raiseIfMissing=None):
+    try: method = getattr(base, methodname)
+    except AttributeError:
+        if raiseIfMissing:
+            raise CallbaseError, methodname
+        return None
+    if args is None: args = ()
+    return method(obj, *args, **kw)
+===========================================================================
+# Place this in your class that's overriding .awake (or any method).
+from SOMEWHERE import callbase
+class MyMixin:
+        def awake(self, trans):
+                args = (trans,)
+                callbase(self, MyMixin, 'awake', args)
+                ... everything else you want to do ...
+===========================================================================
+\end{verbatim}
+
+% @@MO: Edmund wants us to mention delegation too, as an alternative to
+% inheritance.  Contact elian@inbrief.net for details.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{All methods}
+\label{tips.allMethods}
+
+Here is a list of all the standard methods and attributes that can be accessed
+from a placeholder.  Some of them exist for you to call, others are mainly used
+by Cheetah internally but you can call them if you wish, and others are only
+for internal use by Cheetah or Webware.  Do not use these method names in mixin
+classes (\code{\#extends}, section \ref{inheritanceEtc.extends}) unless you
+intend to override the standard method.  
+
+Variables with a star prefix ({\bf *}) are frequently used in templates or in
+pure Python classes.
+
+\paragraph*{Inherited from Cheetah.Template}
+
+\begin{description}
+\item{{\bf compile(source=None, file=None, moduleName=None, 
+    mainMethodName='respond')}}  Compile the template.  Automatically called
+    by \code{.\_\_init\_\_}.
+\item{{\bf generatedModuleCode()}}  Return the module code the compiler
+    generated, or \code{None} if no compilation took place.
+\item{{\bf generatedClassCode()}}   Return the class code the compiler
+    generated, or \code{None} if no compilation took place.
+\item{{\bf * searchList()}}  Return a reference to the underlying search list.
+    (a list of objects).  Use this to print out your searchList for debugging.
+    Modifying the returned list will affect your placeholder searches!
+\item{{\bf * errorCatcher()}}  Return a reference to the current error
+    catcher.
+\item{{\bf * refreshCache(cacheKey=None)}}  If 'cacheKey' is not \code{None},
+    refresh that item in the cache.  If \code{None}, delete all items in the
+    cache so they will be recalculated the next time they are encountered.
+\item{{\bf * shutdown()}}  Break reference cycles before discarding a servlet.
+\item{{\bf * getVar(varName, default=NoDefault, autoCall=True)}}  Look up a
+    variable in the searchList.  Same as \code{\$varName} but allows you to
+    specify a default value and control whether autocalling occurs.
+\item{{\bf * varExists(varName, autoCall=True)}}
+\item{{\bf * getFileContents(path)}}  Read the named file.  If used as a
+    placeholder, inserts the file's contents in the output without
+    interpretation, like \code{\#include\ raw}.  If used in an expression,
+    returns the file's content (e.g., to assign it to a variable).
+\item{{\bf runAsMainProgram()}}  This is what happens if you run a
+    .py template module as a standalone program.
+\end{description}
+
+%Private methods: {\bf \_bindCompiledMethod}, {\bf \_bindFunctionAsMethod},
+%{\bf \_includeCheetahSource}, {\bf \_genTmpFilename}, 
+%{\bf \_importAsDummyModule}, {\bf \_makeDummyPackageForDir},
+%{\bf \_importFromDummyPackage}, {\bf \_importModuleFromDirectory}.
+%
+%Other private attributes:
+%\begin{description}
+%\item{{\bf * \_fileMtime}}  Time the template definition was modified, in
+%    Unix ticks.  \code{None} if the template definition came from a string or
+%    file handle rather than a named file, same for the next three variables.
+%\item{{\bf * \_fileDirName}}  The directory containing the template definition.
+%\item{{\bf * \_fileBaseName}}  The basename of the template definition  file.
+%\item{{\bf * \_filePath}}  The directory+filename of the template definition.
+%\end{description}
+
+\paragraph*{Inherited from Cheetah.Utils.WebInputMixin}
+
+\begin{description}
+\item{{\bf nonNumericInputError}}  Exception raised by \code{.webInput}.
+\item{{\bf * webInput(...)}}  Convenience method to access GET/POST variables
+    from a Webware servlet or CGI script, or Webware cookie or session
+    variables.  See section \ref{webware.webInput} for usage information.
+\end{description}
+
+\paragraph*{Inherited from Cheetah.SettingsManager}
+
+\begin{description}
+\item{{\bf setting(name, default=NoDefault)}}  Get a compiler setting.
+\item{{\bf hasSetting(name)}}  Does this compiler setting exist?
+\item{{\bf setSetting(name, value)}}  Set setting 'name' to 'value'.
+    See \code{\#compiler-settings}, section 
+    \ref{parserInstructions.compiler-settings}.
+\item{{\bf settings()}}  Return the underlying settings dictionary.  (Warning:
+    modifying this dictionary will change Cheetah's behavior.)
+\item{{\bf copySettings()}}  Return a copy of the underlying settings
+    dictionary.
+\item{{\bf deepcopySettings()}}  Return a deep copy of the underlying settings
+    dictionary.  See Python's \code{copy} module.
+\item{{\bf updateSettings(newSettings, merge=True)}}  Update Cheetah's 
+    compiler settings from the 'newSettings' dictionary.  If 'merge' is true,
+    update only the names in newSettings and leave the other names alone.
+    (The SettingsManager is smart enough to update nested dictionaries one
+    key at a time rather than overwriting the entire old dictionary.)
+    If 'merge' is false, delete all existing settings so that the new ones are
+    the only settings.
+\item{{\bf updateSettingsFromPySrcStr(theString, merge=True)}}  Same, 
+    but pass a string of \code{name=value} pairs rather
+    than a dictionary, the same as you would provide in a
+    \code{\#compiler-settings} directive, section
+    \ref{parserInstructions.compiler-settings}.
+\item{{\bf updateSettingsFromPySrcFile(path, merge=True)}}  Same, but
+    exec a Python source file and use the variables it contains as the new
+    settings.  (e.g., \code{cheetahVarStartToken\ =\ "@"}).
+\item{{\bf updateSettingsFromConfigFile(path, **kw)}}  Same, but get the new
+    settings from a text file in ConfigParser format (similar to Windows'
+    *.ini file format).  See Python's \code{ConfigParser} module.
+\item{{\bf updateSettingsFromConfigFileObj}}  Same, but read the open file
+    object 'inFile' for the new settings.  
+\item{{\bf updateSettingsFromConfigStr(configStr, convert=True, merge=True}}
+    Same, but read the new settings from a string in ConfigParser format.
+\item{{\bf writeConfigFile(path)}}  Write the current compiler settings to
+    a file named 'path' in *.ini format.
+\item{{\bf getConfigString()}}  Return a string containing the current
+    compiler settings in *.ini format.
+\end{description}
+
+\paragraph*{Inherited from Cheetah.Servlet}
+
+{\em Do not override these in a subclass or assign to them as attributes
+if your template will be used as a servlet,} otherwise Webware will behave
+unpredictably.  However, it {\em is} OK to put same-name variables in the
+searchList, because Webware does not use the searchList.
+
+EXCEPTION: It's OK to override {\bf awake} and {\bf sleep} as long as you
+call the superclass methods.  (See section
+\ref{tips.callingSuperclassMethods}.)
+
+\begin{description}
+\item{{\bf * isControlledByWebKit}}  True if this template instance is
+    part of a live transaction in a running WebKit servlet.
+\item{{\bf * isWebwareInstalled}}  True if Webware is installed and the
+    template instance inherits from WebKit.Servlet.  If not, it inherits
+    from Cheetah.Servlet.DummyServlet.
+\item{{\bf * awake(transaction)}}  Called by WebKit at the beginning of
+    the web transaction.
+\item{{\bf * sleep(transaction)}}  Called by WebKit at the end of the
+    web transaction.
+\item{{\bf * respond(transaction)}}  Called by WebKit to produce the 
+    web transaction content.  For a template-servlet, this means
+    filling the template.
+\item{{\bf shutdown()}}  Break reference cycles before deleting instance.
+\item{{\bf * serverSidePath()}}  The filesystem pathname of the 
+    template-servlet (as opposed to the URL path).
+\item{{\bf transaction}}  The current Webware transaction.
+\item{{\bf application}}  The current Webware application.
+\item{{\bf response}}  The current Webware response.
+\item{{\bf request}}  The current Webware request.
+\item{{\bf session}}  The current Webware session.
+\item{{\bf write}}  Call this method to insert text in the filled template
+    output.
+\end{description}
+
+Several other goodies are available to template-servlets under the 
+\code{request} attribute, see section \ref{webware.input}.
+
+\code{transaction}, \code{response}, \code{request} and \code{session} are
+created from the current transaction when WebKit calls \code{awake}, and don't
+exist otherwise.  Calling \code{awake} yourself (rather than letting WebKit
+call it) will raise an exception because the \code{transaction} argument won't
+have the right attributes.  
+
+\paragraph*{Inherited from WebKit.Servlet}
+These are accessible only if Cheetah knows Webware is installed.  This 
+listing is based on a CVS snapshot of Webware dated 22 September 2002, and
+may not include more recent changes.
+
+The same caveats about overriding these methods apply.
+
+\begin{description}
+\item{name()}  The simple name of the class.  Used by Webware's logging and
+    debugging routines.
+\item{log()}  Used by Webware's logging and debugging routines.
+\item{canBeThreaded()}  True if the servlet can be multithreaded.
+\item{canBeReused()}  True if the servlet can be used for another transaction
+    after the current transaction is finished.
+\item{serverSideDir()}  Depreciated by \code{.serverSidePath()}.
+\end{description}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Optimizing templates}
+\label{tips.optimizing}
+
+Here are some things you can do to make your templates fill faster and user
+fewer CPU cycles.  Before you put a lot of energy into this, however, make
+sure you really need to.  In many situations, templates appear to initialize
+and fill instantaneously, so no optimization is necessary.  If you do find a
+situation where your templates are filling slowly or taking too much memory or
+too many CPU cycles, we'd like to hear about it on the mailing list.
+
+Cache \$placeholders whose values don't change frequently.  (Section
+\ref{output.caching}).
+
+Use \code{\#set} for values that are very frequently used, especially if they
+come out of an expensive operation like a deeply.nested.structure or a database
+lookup.  \code{\#set} variables are set to Python local variables, which have a
+faster lookup time than Python globals or values from Cheetah's searchList.
+
+Moving variable lookups into Python code may provide a speedup in certain
+circumstances.  If you're just reading \code{self} attributes, there's no
+reason to use NameMapper lookup (\$placeholders) for them.  NameMapper does
+a lot more work than simply looking up a \code{self} attribute.  
+
+On the other hand, if you don't know exactly where the value will come from
+(maybe from \code{self}, maybe from the searchList, maybe from a CGI input
+variable, etc), it's easier to just make that an argument to your method, and
+then the template can handle all the NameMapper lookups for you:
+\begin{verbatim}
+#silent $myMethod($arg1, $arg2, $arg3)
+\end{verbatim}
+Otherwise you'd have to call \code{self.getVar('arg1')} etc in your
+method, which is more wordy, and tedious.
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{PSP-style tags}
+\label{tips.PSP}
+
+\code{<\%= \ldots \%>} and \code{<\% \ldots \%>} allow an escape
+to Python syntax inside the template.  You do not need it to use Cheetah
+effectively, and we're hard pressed to think of a case to recommend it.
+Nevertheless, it's there in case you encounter a situation you can't
+express adequately in Cheetah syntax.  For instance, to set a local
+variable to an elaborate initializer.  
+
+\code{<\%= \ldots \%>} encloses a Python expression whose result will
+be printed in the output.  
+
+\code{<\% \ldots \%>} encloses a Python statement or expression (or set of
+statements or expressions) that will be included as-is into the generated
+method.  The statements themselves won't produce any output, but you can use
+the local function \code{write(EXPRESSION)} to produce your own output.
+(Actually, it's a method of a file-like object, but it looks like a local
+function.) This syntax also may be used to set a local variable with a
+complicated initializer.
+
+To access Cheetah services, you must use Python code like you would in an
+inherited Python class.  For instance, use \code{self.getVar()} to look up
+something in the searchList.
+
+{\em Warning:} {\bf No error checking is done!}  If you write:
+\begin{verbatim}
+<% break %>      ## Wrong!
+\end{verbatim}
+you'll get a \code{SyntaxError} when you fill the template, but that's what you
+deserve.
+
+Note that these are PSP-{\em style} tags, not PSP tags.  A Cheetah template
+is not a PSP document, and you can't use PSP commands in it.
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Makefiles}
+\label{tips.Makefile}
+
+If your project has several templates and you get sick of typing
+``cheetah compile FILENAME.tmpl'' all the time--much less remembering which
+commands to type when--and your system has the \code{make}
+command available, consider building a Makefile to make your life easier.
+
+Here's a simple Makefile that controls two templates, ErrorsTemplate and
+InquiryTemplate.  Two external commands, \code{inquiry} and \code{receive},
+depend on ErrorsTemplate.py.  Aditionally, InquiryTemplate
+itself depends on ErrorsTemplate.
+
+\begin{verbatim}
+all:  inquiry  receive
+
+.PHONY:  all  receive  inquiry  printsource
+
+printsource:
+        a2ps InquiryTemplate.tmpl ErrorsTemplate.tmpl
+
+ErrorsTemplate.py:  ErrorsTemplate.tmpl
+        cheetah compile ErrorsTemplate.tmpl
+
+InquiryTemplate.py:  InquiryTemplate.tmpl ErrorsTemplate.py
+        cheetah compile InquiryTemplate.tmpl
+
+inquiry: InquiryTemplate.py  ErrorsTemplate.py
+
+receive: ErrorsTemplate.py
+\end{verbatim}
+
+Now you can type \code{make} anytime and it will recompile all the templates
+that have changed, while ignoring the ones that haven't.  Or you can
+recompile all the templates \code{receive} needs by typing \code{make receive}.
+Or you can recompile only ErrorsTemplate by typing
+\code{make ErrorsTemplate}.  There's also another target, ``printsource'':
+this sends a Postscript version of the project's source files to the printer.
+The .PHONY target is explained in the \code{make} documentation; essentially,
+you have it depend on every target that doesn't produce an output file with
+the same name as the target.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Using Cheetah in a Multi-Threaded Application}
+\label{tips.threads}
+
+Template classes may be shared freely between threads.  However, template
+instances should not be shared unless you either:
+\begin{itemize}
+\item Use a lock (mutex) to serialize template fills, to prevent two threads
+from filling the template at the same time.
+\item Avoid thread-unsafe features:
+    \begin{itemize}
+    \item Modifying searchList values or instance variables.
+    \item Caching (\code{\$*var}, \code{\#cache}, etc).
+    \item \code{\#set global}, \code{\#filter}, \code{\#errorCatcher}.
+    \end{itemize}
+    Any changes to these in one thread will be visible in other threads,
+    causing them to give inconsistent output.
+\end{itemize}
+
+About the only advantage in sharing a template instance is building up the
+placeholder cache.  But template instances are so low overhead that it
+probably wouldn't take perceptibly longer to let each thread instantiate its
+own template instance.  Only if you're filling templates several times a
+second would the time difference be significant, or if some of the placeholders
+trigger extremely slow calculations (e.g., parsing a long text file each time).
+The biggest overhead in Cheetah is importing the \code{Template} module in
+the first place, but that has to be done only once in a long-running
+application.
+
+You can use Python's \code{mutex} module for the lock, or any similar
+mutex.  If you have to change searchList values or instance variables
+before each fill (which is usually the case), lock the mutex before 
+doing this, and unlock it only after the fill is complete.
+
+For Webware servlets, you're probably better off using Webware's servlet
+caching rather than Cheetah's caching.  Don't override the servlet's
+\code{.canBeThreaded()} method unless you avoid the unsafe operations
+listed above.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Using Cheetah with gettext}
+\label{tips.gettext}
+
+{\bf gettext} is a project for creating internationalized applications.  For 
+more details, visit \url{http://docs.python.org/lib/module-gettext.html}.
+gettext can be used with Cheetah to create internationalized applications, even
+for CJK character sets, but you must keep a couple things in mind:
+\begin{itemize}
+\item xgettext is used on compiled templates, not on the templates themselves.
+\item The way the NameMapper syntax gets compiled to Python gets in the way of 
+the syntax that xgettext recognizes.  Hence, a special case exists for the
+functions \code{_}, \code{N_}, and \code{ngettext}.  If you need to use a
+different set of functions for marking strings for translation, you must set
+the Cheetah setting \code{gettextTokens} to a list of strings representing the
+names of the functions you are using to mark strings for translation.
+\end{itemize}
+
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
diff --git a/docs/users_guide_2_src/13a_precompiledTemplateModules.txt b/docs/users_guide_2_src/13a_precompiledTemplateModules.txt
new file mode 100644
index 0000000..5b0f978
--- /dev/null
+++ b/docs/users_guide_2_src/13a_precompiledTemplateModules.txt
@@ -0,0 +1,109 @@
+A look inside precompiled template modules
+==========================================
+
+..
+    :label: howWorks.pyTrivia
+
+When debugging a template, it's useful to compile it with "cheetah compile"
+and then inspect the resulting Python module.  This will often clear up whether
+Cheetah misinterpreted your intent.  You can do this even if you don't intend to
+use the precompiled templates in production.  It's also a good way to learn how
+Cheetah works.  Simply make a throwaway template definition containing only one
+placeholder or directive, compile it with "cheetah compile", and see what
+Python code Cheetah generated.
+
+However, precompiled template modules can be a bit cryptic to read unless you
+have a bit of background information.  Let's look at an example.  Put the
+following into /tmp/x.tmpl (or any other file) and run "cheetah compile" on
+it::
+
+    The number is $Test.unittest.main.
+    #set mood = "lucky"
+    I'm feeling $lucky.
+
+Open the resulting /tmp/x.py in your favorite text editor.  You'll see a class
+with the same name as the module::
+
+    class x(Template):
+
+This template class contains a method ``.respond()``::
+
+    def respond(self, trans=None):
+        ## CHEETAH: main method generated for this template
+        if (not trans and not self._CHEETAH__isBuffering and 
+            not callable(self.transaction)):
+            trans = self.transaction # is None unless self.awake() was called
+        if not trans:
+            trans = DummyTransaction()
+            _dummyTrans = True
+        else: _dummyTrans = False
+        write = trans.response().write
+        SL = self._CHEETAH__searchList
+        _filter = self._CHEETAH__currentFilter
+        
+        ########################################
+        ## START - generated method body
+
+        
+        write('The number is ')
+        _v = VFFSL(SL,"Test.unittest.main",True) 
+        # '$Test.unittest.main' on line 1, col 15
+        if _v is not None: write(_filter(_v, rawExpr='$Test.unittest.main')) 
+        # from line 1, col 15.
+        write('.\n')
+        mood = "lucky"
+        write("I'm feeling ")
+        _v = VFFSL(SL,"lucky",True) # '$lucky' on line 3, col 13
+        if _v is not None: write(_filter(_v, rawExpr='$lucky')) 
+        # from line 3, col 13.
+        write('.\n') 
+        
+        ########################################
+        ## END - generated method body
+        
+        return _dummyTrans and trans.response().getvalue() or ""
+
+This becomes clearer when we scroll up to see some important imports and
+global variables::
+
+    from Cheetah.Template import Template
+    from Cheetah.DummyTransaction import DummyTransaction
+    from Cheetah.NameMapper import NotFound, valueFromFrameOrSearchList
+    VFFSL=valueFromFrameOrSearchList
+    __CHEETAH_version__ = '2.0rc6'
+    __CHEETAH_src__ = 'x.tmpl'
+
+The actual code will differ slightly depending on your Cheetah version.  Also,
+we've split some long lines to make this page printer-friendly.  
+
+Placeholder lookup is handled by ``VFFSL``, which is really the
+``Cheetah.NameMapper.valueFromFrameOrSearchList`` function or its equivalent
+in Cheetah/_namemapper.c.  
+
+``trans`` and ``write()`` are Webware compatibility features.  Normally 
+``trans`` is not specified and Cheetah creates a ``DummyTransaction``
+instance.  ``write()`` is a shortcut for ``trans.response().write()``,
+which concatenates the output to an internal buffer.  The method returns
+the result: ``trans.response().getvalue()``.  You might assume from 
+``.getvalue()`` that Cheetah uses ``StringIO`` internally, but you'd be wrong.
+Cheetah *used* to use ``StringIO`` but now it uses a list and ``str.join()``.
+The ``.getvalue()`` name is retained for backward compatibility.
+
+If this template is part of a Webware site and the user enters its URL, Webware
+calls ``.respond()`` with a live Webware transaction.  In this case,
+``write()`` writes the output directly to Webware's output stream.  (Or to
+a Webware buffer, but that's not our concern.)  There's nothing to return
+because the output has already been written, so the method returns the empty
+string.  That way if it accidentally gets concatenated to the output, no harm
+will be done.
+
+You can write your own transaction class to support non-Webware output 
+streaming, but Cheetah currently comes with no examples of this.  Ask on
+the mailing list if you need help with it.
+
+Global variables and class attributes defined by Cheetah have a 
+``_CHEETAH_`` prefix.  Instance attributes defined by Cheetah have a
+``__CHEETAH__`` prefix (two trailing underscores).  You should normally
+never write to these but you can read them if desired; many are
+self-explanatory.  One such attribute is ``._CHEETAH__searchList``.  This
+is the actual search List ``VFFSL()`` will consult for placeholder lookups.
diff --git a/docs/users_guide_2_src/14_webware.txt b/docs/users_guide_2_src/14_webware.txt
new file mode 100755
index 0000000..8c47e90
--- /dev/null
+++ b/docs/users_guide_2_src/14_webware.txt
@@ -0,0 +1,582 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Using Cheetah with Webware}
+\label{webware}
+
+{\bf Webware for Python} is a 'Python-Powered Internet Platform' that runs
+servlets in a manner similar to Java servlets.  {\bf WebKit} is the name of
+Webware's application server.  For more details, please visit
+\url{http://webware.sourceforge.net/}.
+
+All comments below refer to the official version of Webware, the DamnSimple!
+offshoot at ?, and the now-abandoned WebwareExperimental implementation at
+\url{http://sourceforge.net/projects/expwebware/}, except where noted.  All the
+implementations are 95\% identical to the servlet writer: their differences lie
+in their internal structure and configuration files.  One difference is that
+the executable you run to launch standard Webware is called \code{AppServer},
+whereas in WebwareExperimental it's called \code{webkit}. But to servlets
+they're both "WebKit, Webware's application server", so it's one half dozen to
+the other.  In this document, we generally use the term {\bf WebKit} to refer
+to the currently-running application server.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Installing Cheetah on a Webware system}
+\label{webware.installing}
+
+Install Cheetah after you have installed Webware, following the instructions in
+chapter \ref{gettingStarted}.
+
+The standard Cheetah test suite ('cheetah test') does not test Webware features.
+We plan to build a test suite that can run as a Webware servlet, containing
+Webware-specific tests, but that has not been built yet.  In the meantime, you
+can make a simple template containing something like "This is a very small
+template.", compile it, put the *.py template module in a servlet
+directory, and see if Webware serves it up OK.  
+
+{\em You must not have a Webware context called "Cheetah".}  If you do, Webware
+will mistake that directory for the Cheetah module directory, and all 
+template-servlets will bomb out with a "ImportError: no module named Template".
+(This applies only to the standard Webware; WebwareExperimental does not have
+contexts.)
+
+If Webware complains that it cannot find your servlet, make sure
+'.tmpl' is listed in 'ExtensionsToIgnore' in your 'Application.config' file.
+
+% @@MO: Should explain extension cascading and how without it, standard
+% Webware pretends a file doesn't exist if it finds two or more servable files
+% that match the URL.
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Containment vs Inheritance}
+\label{webware.background}
+
+Because Cheetah's core is flexible, there are many ways to integrate it with
+Webware servlets.  There are two broad strategies: the {\bf Inheritance
+approach} and the {\bf Containment approach}.  The difference is
+that in the Inheritance approach, your template object \code{\em is} the
+servlet, whereas in the Containment approach, the servlet is not a template but
+merely {\em uses} template(s) for portion(s) of its work.
+
+The Inheritance approach is recommended for new sites because it's simpler, and
+because it scales well for large sites with a
+site->section->subsection->servlet hierarchy.  The Containment approach is
+better for existing servlets that you don't want to restructure.  For instance,
+you can use the Containment approach to embed a discussion-forum table at the
+bottom of a web page.  
+
+However, most people who use Cheetah extensively seem
+to prefer the Inheritance approach because even the most analytical servlet
+needs to produce {\em some} output, and it has to fit the site's look and feel
+{\em anyway}, so you may as well use a template-servlet as the place to put the
+output.  Especially since it's so easy to add a template-servlet to a site once
+the framework is established.  So we recommend you at least evaluate the
+effort that would be required to convert your site framework to template
+superclasses as described below, vs the greater flexibility and manageability
+it might give the site over the long term.  You don't necessarily have to
+convert all your existing servlets right away: just build common site templates
+that are visually and behaviorally compatible with your specification, and use
+them for new servlets.  Existing servlets can be converted later, if at all.
+
+Edmund Liam is preparing a section on a hybrid approach, in which the 
+servlet is not a template, but still calls template(s) in an inheritance
+chain to produce the output.  The advantage of this approach is that you
+aren't dealing with \code{Template} methods and Webware methods in the
+same object.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{The Containment Approach}
+\label{webware.containment}
+
+In the Containment approach, your servlet is not a template.  Instead, it 
+it makes its own arrangements to create and use template object(s) for whatever
+it needs.  The servlet must explicitly call the template objects'
+\code{.respond()} (or \code{.\_\_str\_\_()}) method each time it needs to fill
+the template.  This does not present the output to the user; it merely gives
+the output to the servlet.  The servlet then calls its
+\code{\#self.response().write()} method to send the output to the user.
+
+The developer has several choices for managing her templates.  She can store the
+template definition in a string, file or database and call
+\code{Cheetah.Template.Template} manually on it.  Or she can put the
+template definition in a *.tmpl file and use {\bf cheetah compile} (section
+\ref{howWorks.cheetah-compile}) to convert it to a Python class in a *.py
+module, and then import it into her servlet.
+
+Because template objects are not thread safe, you should not store one
+in a module variable and allow multiple servlets to fill it simultaneously.
+Instead, each servlet should instantiate its own template object.  Template
+{\em classes}, however, are thread safe, since they don't change once created.
+So it's safe to store a template class in a module global variable.
+
+% @@MO: Example of containment.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{The Inheritance Approach}
+\label{webware.inheritance}
+
+In the Inheritance approach, your template object doubles as as Webware 
+servlet, thus these are sometimes called {\bf template-servlets}.  {\bf cheetah
+compile} (section \ref{howWorks.cheetah-compile}) automatically creates modules
+containing valid Webware servlets.  A servlet is a subclass of Webware's
+\code{WebKit.HTTPServlet} class, contained in a module with the same name as
+the servlet.  WebKit uses the request URL to find the module, and then
+instantiates the servlet/template.  The servlet must have a \code{.respond()}
+method (or \code{.respondToGet()}, \code{.respondToPut()}, etc., but the
+Cheetah default is \code{.respond()}).  Servlets created by \code{cheetah
+compile} meet all these requirements.
+
+(Cheetah has a Webware plugin that automatically converts a \code{.tmpl servlet
+file} into a \code{.py servlet file} when the \code{.tmpl servlet file} is
+requested by a browser.  However, that plugin is currently unavailable because
+it's being redesigned.  For now, use \code{cheetah compile} instead.)
+
+What about logic code?  Cheetah promises to keep content (the placeholder
+values), graphic design (the template definition and is display logic), and
+algorithmic logic (complex calculations and side effects) separate.  How?
+Where do you do form processing?
+
+The answer is that your template class can inherit from a pure Python class
+containing the analytical logic.  You can either use the \code{\#extends}
+directive in Cheetah to indicate the superclass(es), or write a Python
+\code{class} statement to do the same thing.  See the template
+\code{Cheetah.Templates.SkeletonPage.tmpl} and its pure Python class
+\code{Cheetah.Templates.\_SkeletonPage.py} for an example of a template
+inheriting logic code.  (See sections \ref{inheritanceEtc.extends} and
+\ref{inheritanceEtc.implements} for more information about \code{\#extends} and
+\code{\#implements}.  They have to be used a certain right way.)
+
+If \code{\#WebKit.HTTPServlet} is not available, Cheetah fakes it with a
+dummy class to satisfy the dependency.  This allows servlets to be tested on
+the command line even on systems where Webware is not installed.  This works
+only with servlets that don't call back into WebKit for information about the
+current web transaction, since there is no web transaction.  Trying to access
+form input, for instance, will raise an exception because it depends on a
+live web request object, and in the dummy class the request object is
+\code{None}.
+
+Because Webware servlets must be valid Python modules, and ``cheetah compile''
+can produce only valid module names, if you're converting an existing site that
+has .html filenames with hyphens (-), extra dots (.), etc, you'll have to
+rename them (and possibly use redirects).
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Site frameworks}
+\label{webware.siteFrameworks}
+
+Web sites are normally arranged hierarchically, with certain features common 
+to every page on the site, other features common to certain sections or
+subsections, and others unique to each page.  You can model this easily with
+a hierarchy of classes, with specific servlets inheriting from their more
+general superclasses.  Again, you can do this two ways, using Cheetah's
+{\bf Containment} approach or {\bf Inheritance} approach.
+
+In the Inheritance approach, parents provide \code{\#block}s and children
+override them using \code{\#def}.  Each child \code{\#extend}s its immediate
+parent.  Only the leaf servlets need to be under WebKit's document root
+directory.  The superclass servlets can live anywhere in the filesystem
+that's in the Python path.  (You may want to modify your WebKit startup 
+script to add that library directory to your \code{PYTHONPATH} before starting
+WebKit.)
+
+% @@MO Examples: simple, IronSite, SkeletonPage.
+
+Section \ref{libraries.templates.skeletonPage} contains information on a stock
+template that simplifies defining the basic HTML structure of your web
+page templates.  
+
+In the Containment approach, your hierarchy of servlets are not templates, but
+each uses one or more templates as it wishes.  Children provide callback
+methods to to produce the various portions of the page that are their
+responsibility, and parents call those methods.  Webware's \code{WebKit.Page}
+and \code{WebKit.SidebarPage} classes operate like this.
+
+% @@MO Show examples of WebKit.Page and WebKit.SidebarPage.
+
+Note that the two approaches are not compatible!  \code{WebKit.Page} was not
+designed to intermix with \code{Cheetah.Templates.SkeletonPage}.  Choose either
+one or the other, or expect to do some integration work.  
+
+If you come up with a different strategy you think is worth noting in this
+chapter, let us know.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Directory structure}
+\label{webware.directoryStructure}
+
+Here's one way to organize your files for Webware+Cheetah.
+
+\begin{verbatim}
+www/                         # Web root directory.
+    site1.example.com/       # Site subdirectory.
+        apache/              # Web server document root (for non-servlets).
+        www/                 # WebKit document root. 
+           index.py          # http://site1.example.com/
+           index.tmpl        # Source for above.
+           servlet2.py       # http://site1.example.com/servlet2
+           servlet2.tmpl     # Source for above.
+        lib/                 # Directory for helper classes.
+           Site.py           # Site superclass ("#extends Site").
+           Site.tmpl         # Source for above.
+           Logic.py          # Logic class inherited by some template.
+        webkit.config        # Configuration file (for WebwareExperimental).
+        Webware/             # Standard Webware's MakeAppWorkDir directory.
+           AppServer         # Startup program (for standard Webware).
+           Configs/          # Configuration directory (for standard Webware).
+               Application.config
+                             # Configuration file (for standard Webware). 
+    site2.example.org/       # Another virtual host on this computer....
+\end{verbatim}
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Initializing your template-servlet with Python code}
+\label{webware.calculations}
+
+If you need a place to initialize variables or do calculations for your
+template-servlet, you can put it in an \code{.awake()} method because WebKit
+automatically calls that early when processing the web transaction.  If you
+do override \code{.awake()}, be sure to call the superclass \code{.awake}
+method.  You probably want to do that first so that you have access to the
+web transaction data \code{Servlet.awake} provides.  You don't have to worry
+about whether your parent class has its own \code{.awake} method, just call
+it anyway, and somebody up the inheritance chain will respond, or at minimum
+\code{Servlet.awake} will respond.  Section
+\ref{tips.callingSuperclassMethods} gives examples of how to call a
+superclass method.
+
+As an alternative, you can put all your calculations in your own method and
+call it near the top of your template.  (\code{\#silent}, section
+\ref{output.silent}).
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Form processing}
+\label{webware.form}
+
+There are many ways to display and process HTML forms with Cheetah.
+But basically, all form processing involves two steps.
+\begin{enumerate}
+\item{} Display the form.  
+\item{} In the next web request, read the parameters the user submitted,
+check for user errors, perform any side effects (e.g., reading/writing a
+database or session data) and present the user an HTML response or another
+form.  
+\end{enumerate}
+
+The second step may involve choosing between several templates to fill (or
+several servlets to redirect to), or a big if-elif-elif-else construct to
+display a different portion of the template depending on the situation.
+
+In the oldest web applications, step 1 and step 2 were handled by separate
+objects.  Step 1 was a static HTML file, and step 2 was a CGI script.
+Frequently, a better strategy is to have a single servlet handle both steps.
+That way, the servlet has better control over the entire situation, and if
+the user submits unacceptable data, the servlet can redisplay the form with a
+"try again" error message at the top and and all the previous input filled in.
+The servlet can use the presence or absence of certain CGI parameters (e.g.,
+the submit button, or a hidden mode field) to determine which step to take.
+
+One neat way to build a servlet that can handle both the form displaying and
+form processing is like this:
+
+\begin{enumerate}
+\item Put your form HTML into an ordinary template-servlet.  In each input 
+    field, use a placeholder for the value of the \code{VALUE=} attribue.
+    Place another placeholder next to each field, for that field's error
+    message.
+\item Above the form, put a \code{\$processFormData} method call.
+\item Define that method in a Python class your template \code{\#extend}s.  (Or
+    if it's a simple method, you can define it in a \code{\#def}.)  The method
+    should:
+    \begin{enumerate}
+    \item Get the form input if any.
+    \item If the input variable corresponding to the submit field is empty,
+        there is no form input, so we're showing the form for the first time.
+        Initialize all VALUE= variables to their default value (usually ""),
+        and all error variables to "".  Return "", which will be the value for
+        \code{\$processFormData}.
+    \item If the submit variable is not empty, fill the VALUE= variables with
+        the input data the user just submitted.
+    \item Now check the input for errors and put error messages in the error
+        placeholders.  
+    \item If there were any user errors, return a general error message
+        string; this will be the value for \code{\$processFormData}.
+    \item If there were no errors, do whatever the form's job is (e.g., update
+        a database) and return a success message; this will be the value for
+        \code{\$processFormData}.
+    \end{enumerate}
+\item The top of the page will show your success/failure message (or nothing
+the first time around), with the form below.  If there are errors, the user
+will have a chance to correct them.  After a successful submit, the form will
+appear again, so the user can either review their entry, or change it and
+submit it again.  Depending on the application, this may make the servlet
+update the same database record again, or it may generate a new record.
+\end{enumerate}
+
+% @@MO: Example of a template that shows a form and then processes the input.
+
+\code{FunFormKit} is a third-party Webware package that makes it easier to
+produce forms and handle their logic.  It has been successfully been used with
+Cheetah.  You can download FunFormKit from
+\url{http://colorstudy.net/software/funformkit/} and try it out for yourself.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Form input, cookies, session variables and web server variables}
+\label{webware.input}
+
+General variable tips that also apply to servlets are in section
+\ref{tips.placeholder}.
+
+To look up a CGI GET or POST parameter (with POST overriding):
+\begin{verbatim}
+$request.field('myField')     
+self.request().field('myField')
+\end{verbatim}
+These will fail if Webware is not available, because \code{\$request}
+(aka \code{self.request()} will be \code{None} rather than a Webware
+\code{WebKit.Request} object.  If you plan to read a lot of CGI parameters,
+you may want to put the \code{.fields} method into a local variable for
+convenience:
+\begin{verbatim}
+#set $fields = $request.fields
+$fields.myField
+\end{verbatim}
+But remember to do complicated calculations in Python, and assign the results
+to simple variables in the searchList for display.  These \code{\$request}
+forms are useful only for occasions where you just need one or two simple
+request items that going to Python for would be overkill.
+
+To get a cookie or session parameter, subsitute ``cookie'' or ``session'' for
+``field'' above.  To get a dictionary of all CGI parameters, substitute
+``fields'' (ditto for ``cookies'').  To verify a field exists,
+substitute ``hasField'' (ditto for ``hasCookie'').  
+
+Other useful request goodies:
+\begin{verbatim}
+## Defined in WebKit.Request
+$request.field('myField', 'default value')
+$request.time              ## Time this request began in Unix ticks.
+$request.timeStamp         ## Time in human-readable format ('asctime' format).
+## Defined in WebKit.HTTPRequest
+$request.hasField.myField  ## Is a CGI parameter defined?
+$request.fields            ## Dictionary of all CGI parameters.
+$request.cookie.myCookie   ## A cookie parameter (also .hasCookie, .cookies).
+$request.value.myValue     ## A field or cookie variable (field overrides)
+                           ## (also .hasValue).
+$request.session.mySessionVar  # A session variable.
+$request.extraURLPath      ## URL path components to right of servlet, if any.
+$request.serverDictionary  ## Dict of environmental vars from web server.
+$request.remoteUser        ## Authenticated username.  HTTPRequest.py source
+                           ## suggests this is broken and always returns None.
+$request.remoteAddress  ## User's IP address (string).
+$request.remoteName     ## User's domain name, or IP address if none.
+$request.urlPath        ## URI of this servlet.
+$request.urlPathDir     ## URI of the directory containing this servlet.
+$request.serverSidePath ## Absolute path of this servlet on local filesystem.
+$request.serverURL      ## URL of this servlet, without "http://" prefix,
+                        ## extra path info or query string.
+$request.serverURLDir   ## URL of this servlet's directory, without "http://".
+$log("message")         ## Put a message in the Webware server log.  (If you
+                        ## define your own 'log' variable, it will override
+                        ## this; use $self.log("message") in that case.
+\end{verbatim}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{.webInput()}
+\label{webware.webInput}
+
+From the method docstring:
+
+\begin{verbatim}
+    def webInput(self, names, namesMulti=(), default='', src='f',
+        defaultInt=0, defaultFloat=0.00, badInt=0, badFloat=0.00, debug=False):
+
+This method places the specified GET/POST fields, cookies or session variables
+into a dictionary, which is both returned and put at the beginning of the
+searchList.  It handles:
+    * single vs multiple values
+    * conversion to integer or float for specified names
+    * default values/exceptions for missing or bad values
+    * printing a snapshot of all values retrieved for debugging
+All the 'default*' and 'bad*' arguments have "use or raise" behavior, meaning 
+that if they're a subclass of Exception, they're raised.  If they're anything
+else, that value is substituted for the missing/bad value.  
+
+The simplest usage is:
+
+    #silent $webInput(['choice'])
+    $choice
+
+    dic = self.webInput(['choice'])
+    write(dic['choice'])
+
+Both these examples retrieves the GET/POST field 'choice' and print it.  If you
+leave off the "#silent", all the values would be printed too.  But a better way
+to preview the values is
+
+    #silent $webInput(['name'], $debug=1)
+
+because this pretty-prints all the values inside HTML <PRE> tags.
+
+Since we didn't specify any coversions, the value is a string.  It's a "single"
+value because we specified it in 'names' rather than 'namesMulti'.  Single
+values work like this:
+    * If one value is found, take it.
+    * If several values are found, choose one arbitrarily and ignore the rest.
+    * If no values are found, use or raise the appropriate 'default*' value.
+
+Multi values work like this:
+    * If one value is found, put it in a list.
+    * If several values are found, leave them in a list.
+    * If no values are found, use the empty list ([]).  The 'default*' 
+      arguments are *not* consulted in this case.
+
+Example: assume 'days' came from a set of checkboxes or a multiple combo box
+on a form, and the user chose "Monday", "Tuesday" and "Thursday".
+
+    #silent $webInput([], ['days'])
+    The days you chose are: #slurp
+    #for $day in $days
+    $day #slurp
+    #end for
+
+    dic = self.webInput([], ['days'])
+    write("The days you chose are: ")
+    for day in dic['days']:
+        write(day + " ")
+
+Both these examples print:  "The days you chose are: Monday Tuesday Thursday".
+
+By default, missing strings are replaced by "" and missing/bad numbers by zero.
+(A "bad number" means the converter raised an exception for it, usually because
+of non-numeric characters in the value.)  This mimics Perl/PHP behavior, and
+simplifies coding for many applications where missing/bad values *should* be
+blank/zero.  In those relatively few cases where you must distinguish between
+""/zero on the one hand and missing/bad on the other, change the appropriate
+'default*' and 'bad*' arguments to something like: 
+    * None
+    * another constant value
+    * $NonNumericInputError/self.NonNumericInputError
+    * $ValueError/ValueError
+(NonNumericInputError is defined in this class and is useful for
+distinguishing between bad input vs a TypeError/ValueError
+thrown for some other reason.)
+
+Here's an example using multiple values to schedule newspaper deliveries.
+'checkboxes' comes from a form with checkboxes for all the days of the week.
+The days the user previously chose are preselected.  The user checks/unchecks
+boxes as desired and presses Submit.  The value of 'checkboxes' is a list of
+checkboxes that were checked when Submit was pressed.  Our task now is to
+turn on the days the user checked, turn off the days he unchecked, and leave
+on or off the days he didn't change.
+
+    dic = self.webInput([], ['dayCheckboxes'])
+    wantedDays = dic['dayCheckboxes'] # The days the user checked.
+    for day, on in self.getAllValues():
+        if   not on and wantedDays.has_key(day):
+            self.TurnOn(day)
+            # ... Set a flag or insert a database record ...
+        elif on and not wantedDays.has_key(day):
+            self.TurnOff(day)
+            # ... Unset a flag or delete a database record ...
+
+'source' allows you to look up the variables from a number of different
+sources:
+    'f'   fields (CGI GET/POST parameters)
+    'c'   cookies
+    's'   session variables
+    'v'   "values", meaning fields or cookies
+
+In many forms, you're dealing only with strings, which is why the
+'default' argument is third and the numeric arguments are banished to
+the end.  But sometimes you want automatic number conversion, so that
+you can do numeric comparisons in your templates without having to
+write a bunch of conversion/exception handling code.  Example:
+
+    #silent $webInput(['name', 'height:int'])
+    $name is $height cm tall.
+    #if $height >= 300
+    Wow, you're tall!
+    #else
+    Pshaw, you're short.
+    #end if
+
+    dic = self.webInput(['name', 'height:int'])
+    name = dic[name]
+    height = dic[height]
+    write("%s is %s cm tall." % (name, height))
+    if height > 300:
+        write("Wow, you're tall!")
+    else:
+        write("Pshaw, you're short.")
+
+To convert a value to a number, suffix ":int" or ":float" to the name.  The
+method will search first for a "height:int" variable and then for a "height"
+variable.  (It will be called "height" in the final dictionary.)  If a numeric
+conversion fails, use or raise 'badInt' or 'badFloat'.  Missing values work
+the same way as for strings, except the default is 'defaultInt' or
+'defaultFloat' instead of 'default'.
+
+If a name represents an uploaded file, the entire file will be read into 
+memory.  For more sophisticated file-upload handling, leave that name out of
+the list and do your own handling, or wait for Cheetah.Utils.UploadFileMixin.
+
+This mixin class works only in a subclass that also inherits from 
+Webware's Servlet or HTTPServlet.  Otherwise you'll get an AttributeError
+on 'self.request'.
+
+EXCEPTIONS: ValueError if 'source' is not one of the stated characters.
+TypeError if a conversion suffix is not ":int" or ":float".
+\end{verbatim}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{More examples}
+\label{webware.examples}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection*{Example A -- a standalone servlet}
+%\label{}
+
+% @@MO:
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection*{Example B -- a servlet under a site framework}
+%\label{}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection*{Example C -- several servlets with a common template}
+%\label{}
+
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Other Tips}
+\label{webware.otherTips}
+
+If your servlet accesses external files (e.g., via an \code{\#include}
+directive), remember that the current directory is not necessarily directory
+the servlet is in.  It's probably some other directory WebKit chose.  To find a
+file relative to the servlet's directory, prefix the path with whatever
+\code{self.serverSidePath()} returns (from \code{Servlet.serverSidePath()}.
+
+If you don't understand how \code{\#extends} and \code{\#implements} work, and
+about a template's main method, read the chapter on inheritance (sections
+\ref{inheritanceEtc.extends} and \ref{inheritanceEtc.implements}).  This may
+help you avoid buggy servlets.
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
+%# vim: sw=4 ts=4 expandtab
+
+
+
+``Template`` subclasses Webware's ``Servlet`` class when available,
+so the generated class can be used as a Webware servlet.  This is practical
+only with precompiled templates.
+
diff --git a/docs/users_guide_2_src/15_otherHtml.txt b/docs/users_guide_2_src/15_otherHtml.txt
new file mode 100755
index 0000000..89fd58a
--- /dev/null
+++ b/docs/users_guide_2_src/15_otherHtml.txt
@@ -0,0 +1,95 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{non-Webware HTML output}
+\label{otherHTML}
+
+Cheetah can be used with all types of HTML output, not just with Webware.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Static HTML Pages}
+\label{otherHTML.static}
+
+Some sites like Linux Gazette (\url{http://www.linuxgazette.com/}) require
+completely static pages because they are mirrored on servers running completely
+different software from the main site.  Even dynamic sites may have one or
+two pages that are static for whatever reason, and the site administrator may
+wish to generate those pages from Cheetah templates.
+
+There's nothing special here.  Just create your templates as usual.  Then
+compile and fill them whenever the template definition changes, and fill them
+again whenever the placeholder values change.  You may need an extra step to
+copy the .html files to their final location.  A Makefile (chapter
+\ref{tips.Makefile}) can help encapsulate these steps.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{CGI scripts}
+\label{otherHTML}
+
+Unlike Webware servlets, which don't have to worry about the HTTP headers,
+CGI scripts must emit their own headers.  To make a template CGI aware, add
+this at the top:
+\begin{verbatim}
+#extends Cheetah.Tools.CGITemplate
+#implements respond
+$cgiHeaders#slurp
+\end{verbatim}
+
+Or if your template is inheriting from a Python class:
+\begin{verbatim}
+#extends MyPythonClass
+#implements respond
+$cgiHeaders#slurp
+\end{verbatim}
+
+A sample Python class:
+\begin{verbatim}
+from Cheetah.Tools import CGITemplate
+class MyPythonClass(CGITemplate):
+    def cgiHeadersHook(self):
+        return "Content-Type: text/html; charset=koi8-r\n\n"
+\end{verbatim}
+
+
+Compile the template as usual, put the .py template module in your
+cgi-bin directory and give it execute permission.  \code{.cgiHeaders()} is
+a ``smart'' method that outputs the headers if the module is called as a
+CGI script, or outputs nothing if not.  Being ``called as a CGI script''
+means the environmental variable \code{REQUEST\_METHOD} exists and
+\code{self.isControlledByWebKit} is false.  If you don't agree with that
+definition, override \code{.isCgi()} and provide your own.  
+
+The default header is a simple \verb+Content-type: text/html\n\n+, which works
+with all CGI scripts.  If you want to customize the headers (e.g., to 
+specify the character set), override \code{.cgiHeadersHook()} and return
+a string containing all the headers.  Don't forget to include the extra
+newline at the end of the string: the HTTP protocol requires this empty
+line to mark the end of the headers.
+
+To read GET/POST variables from form input, use the \code{.webInput()} method
+(section \ref{webware.webInput}), or extract them yourself using Python's
+\code{cgi} module or your own function.  Although \code{.webInput()} was
+originally written for Webware servlets, it now handles CGI scripts too.  There
+are a couple behavioral differences between CGI scripts and Webware servlets
+regarding input variables:
+
+\begin{enumerate}
+\item CGI scripts, using Python's \code{cgi} module, believe
+    \code{REQUEST\_METHOD} and recognize {\em either} GET variables {\em or}
+    POST variables, not both.  Webware servlets, doing additional processing,
+    ignore \code{REQUEST\_METHOD} and recognize both, like PHP does.
+\item Webware servlets can ask for cookies or session variables instead of
+    GET/POST variables, by passing the argument \code{src='c'} or
+    \code{src='s'}.  CGI scripts get a \code{RuntimeError} if they try to do
+    this.  
+\end{enumerate}
+
+If you keep your .tmpl files in the same directory as your CGI scripts, make
+sure they don't have execute permission.  Apache at least refuses to serve
+files in a \code{ScriptAlias} directory that don't have execute permission.
+
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
+%# vim: sw=4 ts=4 expandtab
diff --git a/docs/users_guide_2_src/16_nonHtml.txt b/docs/users_guide_2_src/16_nonHtml.txt
new file mode 100755
index 0000000..b618ab0
--- /dev/null
+++ b/docs/users_guide_2_src/16_nonHtml.txt
@@ -0,0 +1,17 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Non-HTML Output}
+\label{nonHTML}
+
+Cheetah can also output any other text format besides HTML.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Python source code}
+\label{nonHTML.python}
+
+To be written.  We're in the middle of working on an autoindenter to
+make it easier to encode Python indentation in a Cheetah template.
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
+%# vim: sw=4 ts=4 expandtab
diff --git a/docs/users_guide_2_src/17_libraries.txt b/docs/users_guide_2_src/17_libraries.txt
new file mode 100755
index 0000000..dc9231a
--- /dev/null
+++ b/docs/users_guide_2_src/17_libraries.txt
@@ -0,0 +1,306 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Batteries included: templates and other libraries}
+\label{libraries}
+
+Cheetah comes ``batteries included'' with libraries of templates, functions,
+classes and other objects you can use in your own programs.  The different
+types are listed alphabetically below, followed by a longer description of
+the SkeletonPage framework.  Some of the objects are classes for specific
+purposes (e.g., filters or error catchers), while others are standalone and
+can be used without Cheetah.
+
+If you develop any objects which are generally useful for Cheetah sites,
+please consider posting them on the wiki with an announcement on the mailing
+list so we can incorporate them into the standard library.  That way, all
+Cheetah users will benefit, and it will encourage others to contribute their
+objects, which might include something you want.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{ErrorCatchers}
+\label{libraries.ErrorCatchers}
+
+Module \code{Cheetah.ErrorCatchers} contains error-handling classes suitable for
+the \code{\#errorCatcher} directive.  These are debugging tools that are not
+intended for use in production systems. See section
+\ref{errorHandling.errorCatcher} for a description of the error catchers bundled
+with Cheetah.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{FileUtils}
+\label{libraries.FileUtils}
+
+Module \code{Cheetah.FileUtils} contains generic functions and classes for 
+doing bulk search-and-replace on several files, and for finding all the files
+in a directory hierarchy whose names match a glob pattern.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Filters}
+\label{libraries.Filters}
+
+Module \code{Filters} contains filters suitable for the \code{\#Filter}
+directive.  See section \ref{output.filter} for a description of the
+filters bundled with Cheetah.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{SettingsManager}
+\label{libraries.SettingsManager}
+
+The \code{SettingsManager} class in the \code{Cheetah.SettingsManager} module is
+a baseclass that provides facilities for managing application settings.  It
+facilitates the use of user-supplied configuration files to fine tune an
+application.  A setting is a key/value pair that an application or component
+(e.g., a filter, or your own servlets) looks up and treats as a configuration
+value to modify its (the component's) behaviour.
+
+SettingsManager is designed to:
+\begin{itemize}
+\item work well with nested settings dictionaries of any depth
+\item read/write \code{.ini style config files} (or strings)
+\item read settings from Python source files (or strings) so that
+     complex Python objects can be stored in the application's settings
+     dictionary.  For example, you might want to store references to various
+     classes that are used by the application, and plugins to the application
+     might want to substitute one class for another.
+\item allow sections in \code{.ini config files} to be extended by settings in
+     Python src files.  If a section contains a setting like
+     ``\code{importSettings=mySettings.py}'', \code{SettingsManager} will merge
+     all the settings defined in ``\code{mySettings.py}'' with the settings for
+     that section that are defined in the \code{.ini config file}.
+\item maintain the case of setting names, unlike the ConfigParser module
+\end{itemize}
+
+Cheetah uses \code{SettingsManager} to manage its configuration settings.
+\code{SettingsManager} might also be useful in your own applications. See the
+source code and docstrings in the file \code{src/SettingsManager.py} for more
+information. 
+
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Templates}
+\label{libraries.templates}
+
+Package \code{Cheetah.Templates} contains stock templates that you can
+either use as is, or extend by using the \code{\#def} directive to redefine
+specific {\bf blocks}.  Currently, the only template in here is SkeletonPage,
+which is described in detail below in section 
+\ref{libraries.templates.skeletonPage}.  (Contributed by Tavis Rudd.)
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Tools}
+\label{libraries.Tools}
+
+Package \code{Cheetah.Tools} contains functions and classes contributed by third
+parties.  Some are Cheetah-specific but others are generic and can be used
+standalone.  None of them are imported by any other Cheetah component; you can 
+delete the Tools/ directory and Cheetah will function fine.  
+
+Some of the items in Tools/ are experimental and have been placed there just to
+see how useful they will be, and whether they attract enough users to make 
+refining them worthwhile (the tools, not the users :).
+
+Nothing in Tools/ is guaranteed to be: (A) tested, (B) reliable, (C) immune
+from being deleted in a future Cheetah version, or (D) immune from
+backwards-incompatable changes.  If you depend on something in Tools/ on a
+production system, consider making a copy of it outside the Cheetah/ directory
+so that this version won't be lost when you upgrade Cheetah.  Also, learn
+enough about Python and about the Tool so that you can maintain it and bugfix
+it if necessary.
+
+If anything in Tools/ is found to be necessary to Cheetah's operation (i.e., if
+another Cheetah component starts importing it), it will be moved to the
+\code{Cheetah.Utils} package.
+
+Current Tools include:
+\begin{description}
+\item{Cheetah.Tools.MondoReport} an ambitious class useful when
+     iterating over records of data (\code{\#for} loops), displaying one
+     pageful of records at a time (with previous/next links), and printing
+     summary statistics about the records or the current page.  See
+     \code{MondoReportDoc.txt} in the same directory as the module.  Some
+     features are not implemented yet.  \code{MondoReportTest.py} is a test
+     suite (and it shows there are currently some errors in MondoReport, hmm).
+     Contributed by Mike Orr.
+
+\item{Cheetah.Tools.RecursiveNull} Nothing, but in a friendly way.  Good
+     for filling in for objects you want to hide.  If \code{\$form.f1} is a
+     RecursiveNull object, then \code{\$form.f1.anything["you"].might("use")}
+     will resolve to the empty string.  You can also put a \code{RecursiveNull}
+     instance at the end of the searchList to convert missing values to ''
+     rather than raising a \code{NotFound} error or having a (less efficient)
+     errorCatcher handle it.  Of course, maybe you prefer to get a
+     \code{NotFound} error...  Contributed by Ian Bicking.
+
+\item{Cheetah.Tools.SiteHierarchy} Provides navigational links to this
+     page's parents and children.  The constructor takes a recursive list of
+     (url,description) pairs representing a tree of hyperlinks to every page in
+     the site (or section, or application...), and also a string containing the
+     current URL.  Two methods 'menuList' and 'crumbs' return output-ready HTML
+     showing an indented menu (hierarchy tree) or crumbs list (Yahoo-style bar:
+     home > grandparent > parent > currentURL).  Contributed by Ian Bicking.
+
+\item 
+\end{description}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Utils}
+\label{libraries.Utils}
+
+Package \code{Cheetah.Utils} contains non-Cheetah-specific functions and
+classes that are imported by other Cheetah components.  Many of these utils can
+be used standalone in other applications too.  
+
+Current Utils include:
+\begin{description}
+\item{Cheetah.Utils.CGIImportMixin} This is inherited by \code{Template}
+     objects, and provides the method, \code{.cgiImport} method
+     (section \ref{webware.cgiImport}).
+
+\item{Cheetah.Utils.Misc} A catch-all module for small functions.
+     \begin{description}
+     \item{\code{UseOrRaise(thing, errmsg='')}}  Raise 'thing' if it's a 
+          subclass of Exception, otherwise return it.  Useful when one
+	  argument does double duty as a default value or an exception to
+	  throw.  Contribyted by Mike Orr.
+
+     \item{\code{checkKeywords(dic, legalKeywords, what='argument'}}  
+          Verifies the dictionary does not contain any keys not listed in
+	  'legalKeywords'.  If it does, raise TypeError.  Useful for
+	  checking the keyword arguments to a function.  Contributed by
+	  Mike Orr.
+     \end{description}
+
+\item{Cheetah.Utils.UploadFileMixin} Not implemented yet, but will contain
+     the \code{.uploadFile} method (or three methods) to ``safely'' copy a
+     form-uploaded file to a local file, to a searchList variable, or return
+     it.  When finished, this will be inherited by \code{Template}, allowing 
+     all templates to do this.  If you want this feature, read the docstring
+     in the source and let us know on the mailing list what you'd like this
+     method to do.  Contributed by Mike Orr.
+
+\item{Cheetah.Utils.VerifyType} Functions to verify the type of a
+     user-supplied function argument.  Contributed by Mike Orr.
+\end{description}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{Cheetah.Templates.SkeletonPage}
+\label{libraries.templates.skeletonPage}
+
+A stock template class that may be useful for web developers is defined in
+the \code{Cheetah.Templates.SkeletonPage} module.  The \code{SkeletonPage}
+template class is generated from the following Cheetah source code:
+
+\begin{verbatim}
+##doc-module: A Skeleton HTML page template, that provides basic structure and utility methods.
+################################################################################
+#extends Cheetah.Templates._SkeletonPage
+#implements respond
+################################################################################
+#cache id='header'
+$docType
+$htmlTag
+<!-- This document was autogenerated by Cheetah(http://CheetahTemplate.org). 
+Do not edit it directly!
+
+Copyright $currentYr - $siteCopyrightName - All Rights Reserved.
+Feel free to copy any javascript or html you like on this site,
+provided you remove all links and/or references to $siteDomainName
+However, please do not copy any content or images without permission.
+
+$siteCredits
+
+-->
+
+
+#block writeHeadTag
+<head>
+<title>$title</title>
+$metaTags 
+$stylesheetTags 
+$javascriptTags
+</head>
+#end block writeHeadTag
+
+#end cache header
+#################
+
+$bodyTag
+
+#block writeBody
+This skeleton page has no flesh. Its body needs to be implemented.
+#end block writeBody
+
+</body>
+</html>
+\end{verbatim}
+
+You can redefine any of the blocks defined in this template by writing a new
+template that \code{\#extends} SkeletonPage.  (As you remember, using 
+\code{\#extends} makes your template implement the \code{.writeBody()}
+method instead of \code{.respond()} -- which happens to be the same method
+SkeletonPage expects the page content to be (note the writeBody block in
+SkeletonPage).)
+
+\begin{verbatim}
+#def bodyContents
+Here's my new body. I've got some flesh on my bones now.
+#end def bodyContents
+\end{verbatim}
+
+%% @@MO: Is this still accurate?  Does the child template really need to put a
+%% #def around its whole content?  Or by implementing .writeBody() does it
+%% automatically insert itself as the writeBody portion of
+%% SkeletonPage?  @@TR 2005-01-06: it happens automatically at the moment.
+
+All of the \$placeholders used in the \code{SkeletonPage} template definition
+are attributes or methods of the \code{SkeletonPage} class.  You can reimplement
+them as you wish in your subclass.  Please read the source code of the file
+\code{src/Templates/\_SkeletonPage.py} before doing so.  
+
+You'll need to understand how to use the following methods of the
+\code{SkeletonPage} class: \code{\$metaTags()}, \code{\$stylesheetTags()},
+\code{\$javascriptTags()}, and \code{\$bodyTag()}.  They take the data you
+define in various attributes and renders them into HTML tags.
+
+\begin{itemize}
+\item {\bf metaTags()} -- Returns a formatted vesion of the self.\_metaTags
+     dictionary, using the formatMetaTags function from
+     \code{\_SkeletonPage.py}.
+\item {\bf stylesheetTags()} -- Returns a formatted version of the
+     \code{self.\_stylesheetLibs} and \code{self.\_stylesheets} dictionaries.
+     The keys in \code{self.\_stylesheets} must be listed in the order that
+     they should appear in the list \code{self.\_stylesheetsOrder}, to ensure
+     that the style rules are defined in the correct order.
+\item {\bf javascriptTags()} -- Returns a formatted version of the
+     \code{self.\_javascriptTags} and \code{self.\_javascriptLibs} dictionaries.
+     Each value in \code{self.\_javascriptTags} should be a either a code string
+     to include, or a list containing the JavaScript version number and the code
+     string. The keys can be anything.  The same applies for
+     \code{self.\_javascriptLibs}, but the string should be the SRC filename
+     rather than a code string.
+\item {\bf bodyTag()} -- Returns an HTML body tag from the entries in the dict
+     \code{self.\_bodyTagAttribs}.
+\end{itemize}
+
+The class also provides some convenience methods that can be used as
+\$placeholders in your template definitions:
+
+\begin{itemize}
+\item {\bf imgTag(self, src, alt='', width=None, height=None, border=0)} --
+     Dynamically generate an image tag.  Cheetah will try to convert the
+     ``\code{src}'' argument to a WebKit serverSidePath relative to the
+     servlet's location. If width and height aren't specified they are
+     calculated using PIL or ImageMagick if either of these tools are available.
+     If all your images are stored in a certain directory you can reimplement
+     this method to append that directory's path to the ``\code{src}'' argument.
+     Doing so would also insulate your template definitions from changes in your
+     directory structure.
+\end{itemize}
+
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
diff --git a/docs/users_guide_2_src/18_editors.txt b/docs/users_guide_2_src/18_editors.txt
new file mode 100755
index 0000000..84c8f03
--- /dev/null
+++ b/docs/users_guide_2_src/18_editors.txt
@@ -0,0 +1,39 @@
+\section{Visual Editors}
+\label{visualEditors}
+
+This chapter is about maintaining Cheetah templates with visual editors,
+and the tradeoffs between making it friendly to both text editors and visual
+editors.
+
+Cheetah's main developers do not use visual editors.  Tavis uses \code{emacs};
+Mike uses \code{vim}.  So our first priority is to make templates easy to
+maintain in text editors.  In particular, we don't want to add features
+like Zope Page Template's 
+placeholder-value-with-mock-text-for-visual-editors-all-in-an-XML-tag.
+The syntax is so verbose it makes for a whole lotta typing just to insert a
+simple placeholder, for the benefit of editors we never use.  However, as users
+identify features which would help their visual editing without making it
+harder to maintain templates in a text editor, we're all for it.  
+
+As it said in the introduction, Cheetah purposely does not use HTML/XML
+tags for \$placeholders or \#directives.  That way, when you preview the
+template in an editor that interprets HTML tags, you'll still see the
+placeholder and directive source definitions, which provides some ``mock text''
+even if it's not the size the final values will be, and allows you to use
+your imagination to translate how the directive output will look visually in
+the final.
+
+If your editor has syntax highlighting, turn it on.  That makes a big 
+difference in terms of making the template easier to edit.  Since no
+``Cheetah mode'' has been invented yet, set your highlighting to Perl
+mode, and at least the directives/placeholders will show up in different
+colors, although the editor won't reliably guess where the 
+directive/placeholder ends and normal text begins.
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
+
+
+
+
diff --git a/docs/users_guide_2_src/A_links.txt b/docs/users_guide_2_src/A_links.txt
new file mode 100755
index 0000000..1ec2f6c
--- /dev/null
+++ b/docs/users_guide_2_src/A_links.txt
@@ -0,0 +1,112 @@
+\section{Useful Web Links}
+\label{links}
+
+See the wiki for more links.  (The wiki is also updated more often than this
+chapter is.)
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Cheetah Links}
+\label{links.cheetah}
+
+\begin{description}
+\item[Home Page] -- \url{http:www.CheetahTemplate.org/}
+     
+\item[On-line Documentation] -- \url{http:www.CheetahTemplate.org/learn.html}
+     
+\item[SourceForge Project Page] -- \url{http:sf.net/projects/cheetahtemplate/}
+     
+\item[Mailing List Subscription Page] --
+     \url{http://lists.sourceforge.net/lists/listinfo/cheetahtemplate-discuss}
+     
+\item[Mailing List Archive @ Geocrawler] --
+     \url{http://www.geocrawler.com/lists/3/SourceForge/12986/0/}
+
+\item[Mailing List Archive @ Yahoo] --
+     \url{http://groups.yahoo.com/group/cheetah-archive/}
+    
+\item[CVS Repository] -- \url{http://sourceforge.net/cvs/?group\_id=28961}
+     
+\item[CVS-commits archive] --
+     \url{http://www.geocrawler.com/lists/3/SourceForge/13091/0/}
+
+\end{description}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Third-party Cheetah Stuff}
+\label{links.thirdParty}
+
+\begin{itemize}
+\item Steve Howell has written a photo viewer using Python.
+     \url{http://mountainwebtools.com/PicViewer/install.htm}
+\end{itemize}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Webware Links}
+\label{links.webware}
+
+\begin{description}
+\item[Home Page] -- \url{http://webware.sf.net/}
+     
+\item[On-line Documentation] -- \url{http://webware.sf.net/Webware/Docs/}
+     
+\item[SourceForge Project Page] -- \url{http://sf.net/projects/webware/}
+     
+\item[Mailing List Subscription Page] --
+     \url{http://lists.sourceforge.net/lists/listinfo/webware-discuss}
+
+\end{description}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Python Links}
+\label{links.python}
+
+\begin{description}
+\item[Home Page] -- \url{http://www.python.org/}
+\item[On-line Documentation] -- \url{http://www.python.org/doc/}
+\item[SourceForge Project Page] -- \url{http://sf.net/projects/python/}
+\item[The Vaults of Parnassus: Python Resources] --
+     \url{http://www.vex.net/parnassus/}
+\item[Python Cookbook] -- \url{http://aspn.activestate.com/ASPN/Cookbook/Python}
+\end{description}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Other Useful Links}
+\label{links.other}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{Python Database Modules and Open Source Databases}
+\label{links.database}
+
+\begin{description}
+\item[Python Database Topic Guide] -- \url{http://python.org/topics/database/}
+\item[PostgreSQL Database] -- \url{http://www.postgresql.org/index.html}
+\item[MySQL Database] -- \url{http://www.mysql.com/}
+\item[A comparison of PostgreSQL and MySQL] --
+     \url{http://phpbuilder.com/columns/tim20001112.php3}
+\end{description}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{Other Template Systems}
+\label{links.other.templateSystems}
+
+\begin{description}
+\item[Chuck's ``Templates'' Summary Page] -- \url{http://webware.sf.net/Papers/Templates/}
+\end{description}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsubsection{Other Internet development frameworks}
+\label{links.internet}
+
+\begin{description}
+\item[ZOPE (Z Object Publishing Environment)] -- \url{http://zope.org/}
+\item[Server Side Java] -- \url{http://jakarta.apache.org/}
+\item[PHP] -- \url{http://php.net/}
+\item[IBM Websphere] -- \url{http://www.ibm.com/websphere/}
+\item[Coldfusion and Spectra] -- \url{http://www.macromedia.com/}
+\end{description}
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
diff --git a/docs/users_guide_2_src/B_examples.txt b/docs/users_guide_2_src/B_examples.txt
new file mode 100755
index 0000000..6c394fb
--- /dev/null
+++ b/docs/users_guide_2_src/B_examples.txt
@@ -0,0 +1,24 @@
+\section{Examples}
+\label{examples}
+
+The Cheetah distribution comes with an 'examples' directory.  Browse the
+files in this directory and its subdirectories for examples of how
+Cheetah can be used.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Syntax examples}
+The \code{Cheetah.Tests} module contains a large number of test cases that can
+double as examples of how the Cheetah Language works.  To view these cases go
+to the base directory of your Cheetah distribution and open the file
+\code{Cheetah/Tests/SyntaxAndOutput.py} in a text editor.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Webware Examples}
+For examples of Cheetah in use with Webware visit the Cheetah and Webware wikis
+or use google.  We used to have more examples in the cheetah source tarball, but
+they were out of date and confused people.
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
diff --git a/docs/users_guide_2_src/C_comparisions.txt b/docs/users_guide_2_src/C_comparisions.txt
new file mode 100755
index 0000000..56a0fb3
--- /dev/null
+++ b/docs/users_guide_2_src/C_comparisions.txt
@@ -0,0 +1,451 @@
+\section{Cheetah vs. Other Template Engines}
+\label{comparisons}
+
+This appendix compares Cheetah with various other template/emdedded scripting
+languages and Internet development frameworks.  As Cheetah is similar to
+Velocity at a superficial level, you may also wish to read comparisons between
+Velocity and other languages at
+\url{http://jakarta.apache.org/velocity/ymtd/ymtd.html}.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Which features are unique to Cheetah}
+\label{comparisons.unique}
+
+\begin{itemize}
+\item The {\bf block framework} (section \ref{inheritanceEtc.block})
+\item Cheetah's powerful yet simple {\bf caching framework} (section
+     \ref{output.caching})
+\item Cheetah's {\bf Unified Dotted Notation} and {\bf autocalling}
+     (sections \ref{language.namemapper.dict} and
+     \ref{language.namemapper.autocalling})
+\item Cheetah's searchList (section \ref{language.searchList})
+     information.
+\item Cheetah's \code{\#raw} directive (section \ref{output.raw})
+\item Cheetah's \code{\#slurp} directive (section \ref{output.slurp})
+\item Cheetah's tight integration with Webware for Python (section
+     \ref{webware})
+\item Cheetah's {\bf SkeletonPage framework} (section
+     \ref{libraries.templates.skeletonPage})
+\item Cheetah's ability to mix PSP-style code with Cheetah
+     Language syntax (section \ref{tips.PSP}) 
+     Because of Cheetah's design and Python's flexibility it is
+     relatively easy to extend Cheetah's syntax with syntax elements from almost
+     any other template or embedded scripting language.
+\end{itemize}
+
+%% @@MO: What about the new features we've been adding?
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Cheetah vs. Velocity}
+\label{comparisons.velocity}
+
+For a basic introduction to Velocity, visit
+\url{http://jakarta.apache.org/velocity}.
+
+Velocity is a Java template engine.  It's older than Cheetah, has a larger user
+base, and has better examples and docs at the moment. Cheetah, however, has a
+number of advantages over Velocity:
+\begin{itemize}
+\item Cheetah is written in Python. Thus, it's easier to use and extend.
+\item Cheetah's syntax is closer to Python's syntax than Velocity's is to
+Java's.
+\item Cheetah has a powerful caching mechanism.  Velocity has no equivalent.
+\item It's far easier to add data/objects into the namespace where \$placeholder
+     values are extracted from in Cheetah.  Velocity calls this namespace a 'context'.
+     Contexts are dictionaries/hashtables. You can put anything you want into a
+     context, BUT you have to use the .put() method to populate the context; 
+     e.g.,
+
+\begin{verbatim}
+VelocityContext context1 = new VelocityContext();
+context1.put("name","Velocity");
+context1.put("project", "Jakarta");
+context1.put("duplicate", "I am in context1");
+\end{verbatim}
+     
+     Cheetah takes a different approach. Rather than require you to manually
+     populate the 'namespace' like Velocity, Cheetah will accept any existing
+     Python object or dictionary AS the 'namespace'.  Furthermore, Cheetah
+     allows you to specify a list namespaces that will be searched in sequence
+     to find a varname-to-value mapping.  This searchList can be extended at
+     run-time.
+     
+    If you add a `foo' object to the searchList and the `foo' has an attribute
+    called 'bar', you can simply type \code{\$bar} in the template.  If the
+    second item in the searchList is dictionary 'foofoo' containing
+    \code{\{'spam':1234, 'parrot':666\}}, Cheetah will first look in the `foo'
+    object for a `spam' attribute.  Not finding it, Cheetah will then go to
+    `foofoo' (the second element in the searchList) and look among its
+    dictionary keys for `spam'.  Finding it, Cheetah will select
+    \code{foofoo['spam']} as \code{\$spam}'s value.
+
+\item In Cheetah, the tokens that are used to signal the start of
+     \$placeholders and \#directives are configurable. You can set them to any
+     character sequences, not just \$ and \#.
+\end{itemize}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Cheetah vs. WebMacro}
+\label{comparisons.webmacro}
+
+For a basic introduction to WebMacro, visit
+\url{http://webmacro.org}.
+
+The points discussed in section \ref{comparisons.velocity} also apply to the
+comparison between Cheetah and WebMacro.  For further differences please refer
+to \url{http://jakarta.apache.org/velocity/differences.html}.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Cheetah vs. Zope's DTML}
+\label{comparisons.dtml}
+
+For a basic introduction to DTML, visit
+\url{http://www.zope.org/Members/michel/ZB/DTML.dtml}.
+
+\begin{itemize}
+\item Cheetah is faster than DTML.
+\item Cheetah does not use HTML-style tags; DTML does.  Thus, Cheetah tags are
+     visible in rendered HTML output if something goes wrong.
+\item DTML can only be used with ZOPE for web development; Cheetah can be
+     used as a standalone tool for any purpose.
+\item Cheetah's documentation is more complete than DTML's.
+\item Cheetah's learning curve is shorter than DTML's.
+\item DTML has no equivalent of Cheetah's blocks, caching framework, 
+     unified dotted notation, and \code{\#raw} directive.
+\end{itemize}
+
+Here are some examples of syntax differences between DTML and Cheetah:
+\begin{verbatim}
+<ul>
+<dtml-in frogQuery>
+ <li><dtml-var animal_name></li>
+</dtml-in>
+</ul>
+\end{verbatim}
+
+\begin{verbatim}
+<ul>
+#for $animal_name in $frogQuery
+ <li>$animal_name</li>
+#end for
+</ul>
+\end{verbatim}
+
+\begin{verbatim}
+<dtml-if expr="monkeys > monkey_limit">
+  <p>There are too many monkeys!</p>
+<dtml-elif expr="monkeys < minimum_monkeys">
+  <p>There aren't enough monkeys!</p>
+<dtml-else>
+  <p>There are just enough monkeys.</p>
+</dtml-if>
+\end{verbatim}
+
+\begin{verbatim}
+#if $monkeys > $monkey_limit
+  <p>There are too many monkeys!</p>
+#else if $monkeys < $minimum_monkeys
+  <p>There aren't enough monkeys!</p>
+#else
+  <p>There are just enough monkeys.</p>
+#end if
+\end{verbatim}
+
+\begin{verbatim}
+<table>
+<dtml-in expr="objectValues('File')">
+  <dtml-if sequence-even>
+    <tr bgcolor="grey">
+  <dtml-else>
+    <tr>
+  </dtml-if>    
+  <td>
+  <a href="&dtml-absolute_url;"><dtml-var title_or_id></a>
+  </td></tr>
+</dtml-in>
+</table>
+\end{verbatim}
+
+\begin{verbatim}
+<table>
+#set $evenRow = 0
+#for $file in $files('File')
+  #if $evenRow
+    <tr bgcolor="grey">
+    #set $evenRow = 0
+  #else
+    <tr>
+    #set $evenRow = 1
+  #end if
+  <td>
+  <a href="$file.absolute_url">$file.title_or_id</a>
+  </td></tr>
+#end for
+</table>
+\end{verbatim}
+
+The last example changed the name of \code{\$objectValues} to 
+\code{\$files} because that's what a Cheetah developer would write.
+The developer would be responsible for ensuring \code{\$files} returned a 
+list (or tuple) of objects (or dictionaries) containing the attributes (or
+methods or dictionary keys) `absolute\_url' and `title\_or\_id'.  All these
+names (`objectValues', `absolute\_url' and `title\_or\_id') are standard parts
+of Zope, but in Cheetah the developer is in charge of writing them and giving
+them a reasonable behaviour.
+
+Some of DTML's features are being ported to Cheetah, such as
+\code{Cheetah.Tools.MondoReport}, which is based on the
+\code{<dtml-in>} tag.  We are also planning an output filter as flexible as
+the \code{<dtml-var>} formatting options.  However, neither of these are
+complete yet.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Cheetah vs. Zope Page Templates}
+\label{comparisons.zpt}
+
+For a basic introduction to Zope Page Templates, please visit
+\url{http://www.zope.org/Documentation/Articles/ZPT2}.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Cheetah vs. PHP's Smarty templates}
+\label{comparisons.smarty}
+
+PHP (\url{http://www.php.net/}) is one of the few scripting languages
+expressly designed for web servlets.  However, it's also a full-fledged
+programming language with libraries similar to Python's and Perl's.  The
+syntax and functions are like a cross between Perl and C plus some original
+ideas (e.g.; a single array type serves as both a list and a dictionary,
+\verb+$arr[]="value";+ appends to an array).
+
+Smarty (\url{http://smarty.php.net/}) is an advanced template engine for
+PHP.  ({\em Note:} this comparision is based on Smarty's on-line documentation.
+The author has not used Smarty.  Please send corrections or ommissions to the
+Cheetah mailing list.)  Like Cheetah, Smarty:
+
+\begin{itemize}
+\item compiles to the target programming language (PHP).
+\item has configurable delimeters.
+\item passes if-blocks directly to PHP, so you can use any PHP expression in
+them.
+\item allows you to embed PHP code in a template.
+\item has a caching framework (although it works quite differently).
+\item can read the template definition from any arbitrary source.
+\end{itemize}
+
+Features Smarty has that Cheetah lacks:
+\begin{itemize}
+\item Preprocessors, postprocessors and output filters.  You can emulate a
+preprocessor in Cheetah by running your template definition through a filter
+program or function before Cheetah sees it.  To emulate a postprocessor, run a
+.py template module through a filter program/function.  To emulate a Smarty
+output filter, run the template output through a filter program/function.  If
+you want to use ``cheetah compile'' or ``cheetah fill'' in a pipeline, use
+\code{-} as the input file name and \code{--stdout} to send the result to
+standard output.  Note that Cheetah uses the term ``output filter'' differently
+than Smarty: Cheetah output filters (\code{\#filter}) operate on placeholders,
+while Smarty output filters operate on the entire template output.  There has
+been a proposed \code{\#sed} directive that would operate on the entire output
+line by line, but it has not been implemented.
+\item Variable modifiers.  In some cases, Python has equivalent string
+methods (\code{.strip}, \code{.capitalize}, \code{.replace(SEARCH, REPL)}),
+but in other cases you must wrap the result in a function call or write
+a custom output filter (\code{\#filter}).
+\item Certain web-specific functions, which can be emulated with 
+third-party functions.
+\item The ability to ``plug in'' new directives in a modular way.  Cheetah
+directives are tightly bound to the compiler.  However, third-party
+{\em functions} can be freely imported and called from placeholders, and
+{\em methods} can be mixed in via \code{\#extends}.  Part of this is 
+because Cheetah distinguishes between functions and directives, while
+Smarty treats them all as ``functions''.  Cheetah's design does not
+allow functions to have flow control effect outside the function 
+(e.g., \code{\#if} and \code{\#for}, which operate on template body lines),
+so directives like these cannot be encoded as functions.
+\item Configuration variables read from an .ini-style file.  The 
+\code{Cheetah.SettingsManager} module can parse such a file, but you'd
+have to invoke it manually.  (See the docstrings in the module for
+details.)  In Smarty, this feature is used for 
+multilingual applications.  In Cheetah, the developers maintain that everybody
+has their own preferred way to do this (such as using Python's \code{gettext}
+module), and it's not worth blessing one particular strategy in Cheetah since
+it's easy enough to integrate third-party code around the template, or to add
+the resulting values to the searchList.
+\end{itemize}
+
+Features Cheetah has that Smarty lacks:
+\begin{itemize}
+\item Saving the compilation result in a Python (PHP) module for quick
+reading later.
+\item Caching individual placeholders or portions of a template.  Smarty
+caches only the entire template output as a unit.
+\end{itemize}
+
+Comparisions of various Smarty constructs:
+\begin{verbatim}
+{assign var="name" value="Bob"} (#set has better syntax in the author's opinion)
+counter   (looks like equivalent to #for)
+eval      (same as #include with variable)
+fetch: insert file content into output   (#include raw)
+fetch: insert URL content into output    (no euqivalent, user can write
+     function calling urllib, call as $fetchURL('URL') )
+fetch: read file into variable  (no equivalent, user can write function
+     based on the 'open/file' builtin, or on .getFileContents() in
+     Template.)
+fetch: read URL content into variable  (no equivalent, use above
+     function and call as:  #set $var = $fetchURL('URL')
+html_options: output an HTML option list  (no equivalent, user can
+     write custom function.  Maybe FunFormKit can help.)
+html_select_date: output three dropdown controls to specify a date
+     (no equivalent, user can write custom function)
+html_select_time: output four dropdown controls to specify a time
+     (no equvalent, user can write custom function)
+math: eval calculation and output result   (same as #echo)
+math: eval calculation and assign to variable  (same as #set)
+popup_init: library for popup windows  (no equivalent, user can write
+     custom method outputting Javascript)
+
+
+Other commands:
+capture   (no equivalent, collects output into variable.  A Python
+     program would create a StringIO instance, set sys.stdout to
+     it temporarily, print the output, set sys.stdout back, then use
+     .getvalue() to get the result.)
+config_load   (roughly analagous to #settings, which was removed
+     from Cheetah.  Use Cheetah.SettingsManager manually or write
+     a custom function.)
+include   (same as #include, but can include into variable.
+     Variables are apparently shared between parent and child.)
+include_php: include a PHP script (e.g., functions)
+     (use #extends or #import instead)
+insert   (same as #include not in a #cache region)
+{ldelim}{rdelim}   (escape literal $ and # with a backslash,
+     use #compiler-settings to change the delimeters)
+literal  (#raw)
+php    (``<% %>'' tags)
+section  (#for $i in $range(...) )
+foreach  (#for)
+strip   (like the #sed tag which was never implemented.  Strips
+     leading/trailing whitespace from lines, joins several lines
+     together.)
+
+
+Variable modifiers:
+capitalize    ( $STRING.capitalize() )
+count_characters    (   $len(STRING)  )
+count_paragraphs/sentances/words   (no equivalent, user can write function)
+date_format    (use 'time' module or download Egenix's mx.DateTime)
+default    ($getVar('varName', 'default value') )
+escape: html encode    ($cgi.escape(VALUE) )
+escape: url encode    ($urllib.quote_plus(VALUE) )
+escape: hex encode   (no equivalent?  user can write function)
+escape: hex entity encode  (no equivalent?  user can write function)
+indent: indent all lines of a var's output  (may be part of future
+     #indent directive)
+lower    ($STRING.lower() )
+regex_replace   ('re' module)
+replace    ($STRING.replace(OLD, NEW, MAXSPLIT) )
+spacify   (#echo "SEPARATOR".join(SEQUENCE) )
+string_format   (#echo "%.2f" % FLOAT , etc.)
+strip_tags  (no equivalent, user can write function to strip HTML tags,
+     or customize the WebSafe filter)
+truncate   (no equivalent, user can write function)
+upper   ($STRING.upper() )
+wordwrap  ('writer' module, or a new module coming in Python 2.3)
+\end{verbatim}
+
+Some of these modifiers could be added to the super output filter we
+want to write someday.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Cheetah vs. PHPLib's Template class}
+\label{comparisons.php}
+
+PHPLib (\url(http://phplib.netuse.de/) is a collection of classes for various
+web objects (authentication, shopping cart, sessions, etc), but what we're
+interested in is the \code{Template} object.  It's much more primitive than
+Smarty, and was based on an old Perl template class.  In fact, one of the
+precursors to Cheetah was based on it too.  Differences from Cheetah:
+
+\begin{itemize}
+\item Templates consist of text with \code{\{placeholders\}} in braces.
+\item Instead of a searchList, there is one flat namespace.  Every variable
+     must be assigned via the \code{set\_var} method.  However, you can pass
+     this method an array (dictionary) of several variables at once.
+\item You cannot embed lookups or calculations into the template.  Every
+     placeholder must be an exact variable name.
+\item There are no directives.  You must do all display logic (if, for, etc)
+     in the calling routine.  
+\item There is, however, a ``block'' construct.  A block is a portion of text
+     between the comment markers \code{<!-- BEGIN blockName --> \ldots
+     <!-- END blockName>}.  The \code{set\_block} method extracts this text
+     into a namespace variable and puts a placeholder referring to it in the
+     template.  This has a few parallels with Cheetah's \code{\#block}
+     directive but is overall quite different.  
+\item To do the equivalent of \code{\#if}, extract the block. Then if true, do
+     nothing.  If false, assign the empty string to the namespace variable.
+\item To do the equivalent of \code{\#for}, extract the block.  Set any
+     namespace variables needed inside the loop.  To parse one iteration, use
+     the \code{parse} method to fill the block variable (a mini-template) into
+     another namespace variable, appending to it.  Refresh the namespace
+     variables needed inside the loop and parse again; repeat for each
+     iteration.  You'll end up with a mini-result that will be plugged into the
+     main template's placeholder.
+\item To read a template definition from a file, use the \code{set\_file}
+     method.  This places the file's content in a namespace variable.
+     To read a template definition from a string, assign it to a namespace
+     variable.
+\item Thus, for complicated templates, you are doing a lot of recursive block
+     filling and file reading and parsing mini-templates all into one flat
+     namespace as you finally build up values for the main template.  In
+     Cheetah, all this display logic can be embedded into the template using
+     directives, calling out to Python methods for the more complicated tasks.
+\item Although you can nest blocks in the template, it becomes tedious and
+     arguably hard to read, because all blocks have identical syntax.  Unless
+     you choose your block names carefully and put comments around them, it's
+     hard to tell which blocks are if-blocks and which are for-blocks, or what
+     their nesting order is.
+\item PHPLib templates do not have caching, output filters, etc.
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Cheetah vs. PSP, PHP, ASP, JSP, Embperl, etc.}
+\label{comparisons.pspEtc}
+
+\begin{description}
+\item[Webware's PSP Component] -- \url{http://webware.sourceforge.net/Webware/PSP/Docs/}
+\item[Tomcat JSP Information] -- \url{http://jakarta.apache.org/tomcat/index.html}
+\item[ASP Information at ASP101] -- \url{http://www.asp101.com/}
+\item[Embperl] -- \url{http://perl.apache.org/embperl/}
+\end{description}
+
+
+Here's a basic Cheetah example:
+\begin{verbatim}
+<TABLE>
+#for $client in $service.clients
+<TR>
+<TD>$client.surname, $client.firstname</TD>
+<TD><A HREF="mailto:$client.email" >$client.email</A></TD>
+</TR>
+#end for
+</TABLE>
+\end{verbatim}
+
+Compare this with PSP:
+
+\begin{verbatim}
+<TABLE>
+<% for client in service.clients(): %>
+<TR>
+<TD><%=client.surname()%>, <%=client.firstname()%></TD>
+<TD><A HREF="mailto:<%=client.email()%>"><%=client.email()%></A></TD>
+</TR>
+<%end%>
+</TABLE>
+\end{verbatim}
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
diff --git a/docs/users_guide_2_src/E_license.txt b/docs/users_guide_2_src/E_license.txt
new file mode 100644
index 0000000..8a5a73f
--- /dev/null
+++ b/docs/users_guide_2_src/E_license.txt
@@ -0,0 +1,32 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{License}
+\label{intro.license}
+
+\paragraph*{The gist}
+Cheetah is open source, but products developed with Cheetah or derived
+from Cheetah may be open source or closed source.
+
+(@@MO If this licence is identical to the MIT license, let's say so.  That will
+make it easier for distributors/aggregators to classify the product.)
+
+\paragraph*{Legal terms}
+Copyright \copyright 2001-2006, The Cheetah Development Team: Tavis Rudd, Mike
+Orr, Ian Bicking, Chuck Esterbrook, JJ Behrens.
+
+(@@MO Who is the current development team?  Chuck and Ian have not been major
+contributors for years.  However, some of their code may remain in Cheetah.)
+
+Permission to use, copy, modify, and distribute this software for any purpose
+and without fee is hereby granted, provided that the above copyright notice
+appear in all copies and that both that copyright notice and this permission
+notice appear in supporting documentation, and that the names of the authors not
+be used in advertising or publicity pertaining to distribution of the software
+without specific, written prior permission.
+
+THE AUTHORS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS
+BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
+CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
+WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
diff --git a/docs/users_guide_2_src/Makefile b/docs/users_guide_2_src/Makefile
new file mode 100644
index 0000000..ad0b786
--- /dev/null
+++ b/docs/users_guide_2_src/Makefile
@@ -0,0 +1,16 @@
+RST = rst2html.py --stylesheet=default.css --link-stylesheet  --initial-header-level=2
+
+#%.html: %.txt
+#	${RST} $< $@
+
+all:
+	#${RST} --warnings=/dev/null index.txt index.html
+	${RST} 01_introduction.txt 01_introduction.html
+	${RST} 02_glossary.txt 02_glossary.html
+	${RST} 03_gettingStarted.txt 03_gettingStarted.html
+	${RST} 04_howItWorks.txt 04_howItWorks.html
+	${RST} 04_howItWorks.txt 04_howItWorks.html
+	${RST} 13a_precompiledTemplateModules.txt 13a_precompiledTemplateModules.html
+
+
+# vim: sw=8 ts=8 noexpandtab ai
diff --git a/docs/users_guide_2_src/default.css b/docs/users_guide_2_src/default.css
new file mode 100644
index 0000000..fa715d6
--- /dev/null
+++ b/docs/users_guide_2_src/default.css
@@ -0,0 +1,293 @@
+/* BEGIN Cheetah additions. *********************************** */
+
+body {
+	/* font-size: 10pt; */
+}
+
+blockquote {
+	font-family: sans-serif;
+}
+
+li {
+    margin-bottom: 1em;
+}
+
+/* END Cheetah additions.  ************************************ */
+
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:Date: $Date: 2006/02/20 07:38:08 $
+:Revision: $Revision: 1.1 $
+:Copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+
+See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
+customize this style sheet.
+*/
+
+/* "! important" is used here to override other ``margin-top`` and
+   ``margin-bottom`` styles that are later in the stylesheet or 
+   more specific.  See http://www.w3.org/TR/CSS1#the-cascade */
+.first {
+  margin-top: 0 ! important }
+
+.last, .with-subtitle {
+  margin-bottom: 0 ! important }
+
+.hidden {
+  display: none }
+
+a.toc-backref {
+  text-decoration: none ;
+  color: black }
+
+blockquote.epigraph {
+  margin: 2em 5em ; }
+
+dl.docutils dd {
+  margin-bottom: 0.5em }
+
+dl.docutils dt {
+  font-weight: bold }
+
+div.abstract {
+  margin: 2em 5em }
+
+div.abstract p.topic-title {
+  font-weight: bold ;
+  text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+  margin: 2em ;
+  border: medium outset ;
+  padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+  color: red ;
+  font-weight: bold ;
+  font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+   compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+  margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+  margin-top: 0.5em }
+*/
+
+div.dedication {
+  margin: 2em 5em ;
+  text-align: center ;
+  font-style: italic }
+
+div.dedication p.topic-title {
+  font-weight: bold ;
+  font-style: normal }
+
+div.figure {
+  margin-left: 2em }
+
+div.footer, div.header {
+  clear: both;
+  font-size: smaller }
+
+div.line-block {
+  display: block ;
+  margin-top: 1em ;
+  margin-bottom: 1em }
+
+div.line-block div.line-block {
+  margin-top: 0 ;
+  margin-bottom: 0 ;
+  margin-left: 1.5em }
+
+div.sidebar {
+  margin-left: 1em ;
+  border: medium outset ;
+  padding: 1em ;
+  background-color: #ffffee ;
+  width: 40% ;
+  float: right ;
+  clear: right }
+
+div.sidebar p.rubric {
+  font-family: sans-serif ;
+  font-size: medium }
+
+div.system-messages {
+  margin: 5em }
+
+div.system-messages h1 {
+  color: red }
+
+div.system-message {
+  border: medium outset ;
+  padding: 1em }
+
+div.system-message p.system-message-title {
+  color: red ;
+  font-weight: bold }
+
+div.topic {
+  margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+  margin-top: 0.4em }
+
+h1.title {
+  text-align: center }
+
+h2.subtitle {
+  text-align: center }
+
+hr.docutils {
+  width: 75% }
+
+img.align-left {
+  clear: left }
+
+img.align-right {
+  clear: right }
+
+img.borderless {
+  border: 0 }
+
+ol.simple, ul.simple {
+  margin-bottom: 1em }
+
+ol.arabic {
+  list-style: decimal }
+
+ol.loweralpha {
+  list-style: lower-alpha }
+
+ol.upperalpha {
+  list-style: upper-alpha }
+
+ol.lowerroman {
+  list-style: lower-roman }
+
+ol.upperroman {
+  list-style: upper-roman }
+
+p.attribution {
+  text-align: right ;
+  margin-left: 50% }
+
+p.caption {
+  font-style: italic }
+
+p.credits {
+  font-style: italic ;
+  font-size: smaller }
+
+p.label {
+  white-space: nowrap }
+
+p.rubric {
+  font-weight: bold ;
+  font-size: larger ;
+  color: maroon ;
+  text-align: center }
+
+p.sidebar-title {
+  font-family: sans-serif ;
+  font-weight: bold ;
+  font-size: larger }
+
+p.sidebar-subtitle {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+p.topic-title {
+  font-weight: bold }
+
+pre.address {
+  margin-bottom: 0 ;
+  margin-top: 0 ;
+  font-family: serif ;
+  font-size: 100% }
+
+pre.line-block {
+  font-family: serif ;
+  font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+  margin-left: 2em ;
+  margin-right: 2em ;
+  background-color: #eeeeee }
+
+span.classifier {
+  font-family: sans-serif ;
+  font-style: oblique }
+
+span.classifier-delimiter {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+span.interpreted {
+  font-family: sans-serif }
+
+span.option {
+  white-space: nowrap }
+
+span.pre {
+  white-space: pre }
+
+span.problematic {
+  color: red }
+
+span.section-subtitle {
+  /* font-size relative to parent (h1..h6 element) */
+  font-size: 80% }
+
+table.citation {
+  border-left: solid thin gray }
+
+table.docinfo {
+  margin: 2em 4em }
+
+table.docutils {
+  margin-top: 0.5em ;
+  margin-bottom: 0.5em }
+
+table.footnote {
+  border-left: solid thin black }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+  padding-left: 0.5em ;
+  padding-right: 0.5em ;
+  vertical-align: top }
+
+table.docutils th.field-name, table.docinfo th.docinfo-name {
+  font-weight: bold ;
+  text-align: left ;
+  white-space: nowrap ;
+  padding-left: 0 }
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+  font-size: 100% }
+
+tt.docutils {
+  background-color: #eeeeee }
+
+ul.auto-toc {
+  list-style-type: none }
+
+
+/* vim: sw=4 ts=4 expandtab ai */
diff --git a/docs/users_guide_2_src/eg_1.py b/docs/users_guide_2_src/eg_1.py
new file mode 100644
index 0000000..8098e6b
--- /dev/null
+++ b/docs/users_guide_2_src/eg_1.py
@@ -0,0 +1,11 @@
+#eg_1
+#
+#Looking up values held in dictionaries. 
+#No need to use all values in searchlist. 
+
+from Cheetah.Template import Template
+tmpl = "$value1 $value2 $value3"
+NS = [{'value1':1, 'value2':2}, {'value3':3},{'value4':4}]
+T = Template.compile(source=tmpl)
+t = T(namespaces=NS)
+print t.respond() #1,2,3
diff --git a/docs/users_guide_2_src/eg_2.py b/docs/users_guide_2_src/eg_2.py
new file mode 100644
index 0000000..ee0f7a7
--- /dev/null
+++ b/docs/users_guide_2_src/eg_2.py
@@ -0,0 +1,10 @@
+from Cheetah.Template import Template
+
+#A retrieved value can be any Python object and can be used _exactly_
+#as it would be in Python code
+
+tmpl = "$value1, $value2, $value3[0], $value3[1], $value4[0]['this'][0]"
+NS = [{'value1':1, 'value2':2, 'value3':[3,4], 'value4': [ {'this':[5]}]} ]
+#Compile and fill template in one step
+t = Template.compile(source=tmpl)(namespaces=NS)
+print t.respond() #1, 2, 3, 4, 5
diff --git a/docs/users_guide_2_src/eg_3.py b/docs/users_guide_2_src/eg_3.py
new file mode 100644
index 0000000..5c89a65
--- /dev/null
+++ b/docs/users_guide_2_src/eg_3.py
@@ -0,0 +1,18 @@
+from Cheetah.Template import Template
+
+#The namespaces list is a list of dictionaries and/or 
+#class instances. Search is for dictionary key or object
+#attributes in this list
+class X:
+    pass
+
+
+x = X()
+x.value3 = 3
+x.value4 = 4
+
+tmpl = "$value1, $value2, $value3, $value4"
+NS = [{'value1':1},{'value2':2}, x]
+
+t = Template.compile(source=tmpl)(namespaces=NS)
+print t.respond() #1,2,3,4
diff --git a/docs/users_guide_2_src/eg_4.py b/docs/users_guide_2_src/eg_4.py
new file mode 100644
index 0000000..8fab657
--- /dev/null
+++ b/docs/users_guide_2_src/eg_4.py
@@ -0,0 +1,22 @@
+from Cheetah.Template import Template
+from Cheetah import NameMapper
+
+#Error. Cheetah cannot find 'x' because
+#it is not dictionary key or instance member:
+
+
+class X:
+    pass
+
+x = X()
+x.value3 = 3
+    
+tmpl = "$x.value3"
+NS = [x]
+t = Template.compile(source=tmpl)(namespaces=NS)
+try:
+    t.respond()  #Here substitution is attempted
+except NameMapper.NotFound, e: 
+    print 'NameMapper.NotFound: %s' % e
+    #NameMapper.NotFound: cannot find 'x'
+    
diff --git a/docs/users_guide_2_src/eg_5.py b/docs/users_guide_2_src/eg_5.py
new file mode 100644
index 0000000..551f9c0
--- /dev/null
+++ b/docs/users_guide_2_src/eg_5.py
@@ -0,0 +1,25 @@
+from Cheetah.Template import Template
+
+# ways of using Python to process values after
+#retrieval. 1. Sets a new variable then uses it, 
+#2. Uses pure Python function to set new variable 
+#3. Cheetah calls function directly 
+#4. Extended ${} syntax without function call 
+
+tmpl = """
+
+#set $value1 = $value.replace(' ','-') 
+1. $value1
+<% def change(x):
+  return x.replace(' ','-') 
+%>
+#set $value1 = change($value)
+2. $value1
+3. $change($value)
+4. ${value.replace(' ','-')}
+"""
+NS = [ {'value':'this and that'}]
+
+#compile and fill the template
+t = Template(source=tmpl, namespaces=NS)
+print t.respond()
diff --git a/docs/users_guide_2_src/latex2rst.py b/docs/users_guide_2_src/latex2rst.py
new file mode 100755
index 0000000..80f9a1d
--- /dev/null
+++ b/docs/users_guide_2_src/latex2rst.py
@@ -0,0 +1,45 @@
+#!/usr/bin/env python
+"""Convert files from LaTeX format to ReStructured Text.
+
+   This converter is meant only for saving keystrokes.  It won't catch
+   everything and it may misformat stuff, so proofread the file after
+   processing.
+
+   "Verbatim" blocks are not converted due to the difficulty in placing the
+   preceding colon(s) and indenting every line.
+"""
+import os, re, shutil, sys
+
+def convert(filename):
+    print "Processing file", filename
+    backup = filename + ".bak"
+    shutil.copy2(filename, backup)
+    f = open(filename, 'r+')
+    text = f.read()
+    text = re.sub( R"%%%+", R"", text)
+    text = re.sub( R"\\section\{(.*?)\}",    R"\1\n" + ("=" * 40), text)
+    text = re.sub( R"\\subsection\{(.*?)\}", R"\1\n" + ("-" * 40), text)
+    text = re.sub( R"\\label\{(.*?)\}",      R"\n..\n    :label: \1", text)
+    text = re.sub( R"``|''",                 R'"',      text)
+    text = re.sub( R"(?s)\{\\em (.*?)\}",    R"*\1*", text)
+    text = re.sub( R"(?s)\{\\bf (.*?)\}",    R"**\1**", text)
+    text = re.sub( R"(?s)\\code\{(.*?)\}",   R"``\1``", text)
+    text = re.sub( R"\\(begin|end)\{(itemize|enumerate)\}\n", R"", text)
+    text = re.sub( R"\\item ",                R"* ", text)
+    #text = re.sub( 
+    #    R"(?sm)(\w):\n\s*^\\begin\{verbatim\}\s*(.*?)\\end\{verbatim\}", 
+    #    R"\1::\n\n\2", text)
+    f.seek(0)
+    f.write(text)
+    f.truncate()
+    f.close()
+
+
+def main():
+    if len(sys.argv) < 2:
+        prog = os.path.basename(sys.argv[0])
+        raise SystemExit("usage: %s FILENAMES ..." % prog)
+    for filename in sys.argv[1:]:
+        convert(filename)
+
+if __name__ == "__main__":  main()
diff --git a/docs/users_guide_2_src/unused.txt b/docs/users_guide_2_src/unused.txt
new file mode 100644
index 0000000..3b78fc9
--- /dev/null
+++ b/docs/users_guide_2_src/unused.txt
@@ -0,0 +1,67 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Give me an example of a Webware servlet!}
+\label{intro.example.servlet}
+
+This example uses an HTML form to ask the user's name, then invokes itself
+again to display a {\em personalized} friendly greeting.  
+
+\begin{verbatim}
+<HTML><HEAD><TITLE>My Template-Servlet</TITLE></HEAD><BODY>   
+#set $name = $request.field('name', None)
+#if $name  
+Hello $name
+#else
+<FORM ACTION="" METHOD="GET">
+Name: <INPUT TYPE="text" NAME="name"><BR>
+<INPUT TYPE="submit">
+</FORM>
+#end if
+</BODY></HTML>
+\end{verbatim}
+
+To try it out for yourself on a Webware system:
+\begin{enumerate}
+\item copy the template definition to a file {\bf test.tmpl} in your
+    Webware servlet directory.
+\item Run ``\code{cheetah compile test.tmpl}''.  This produces
+    {\bf test.py} (a .py template module) in the same directory.
+\item In your web browser, go to {\bf test.py}, using whatever site and
+    directory is appropriate.  Depending on your Webware configuration, you may
+    also be able to go to {\bf test}.
+\end{enumerate}
+
+At the first request, field `name' will be blank (false) so the ``\#else''
+portion will execute and present a form.  You type your name and press submit.
+The form invokes the same page.  Now `name' is true so the ``\#if'' portion
+executes, which displays the greeting.  The ``\#set'' directive creates a
+local variable that lasts while the template is being filled.
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+To install Cheetah in your system-wide Python library:
+* Login as a user with privileges to install system-wide Python packages.
+  On POSIX systems (AIX, Solaris, Linux, IRIX, etc.), the command is
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+Certain test failures are insignificant:
+\begin{description}
+\item{**AssertionError: Template output mismatch: Expected Output = 0(end)
+Actual Output = False(end)**}  Python 2.3 changed the string representation of
+booleans, and the tests haven't yet been updated to reflect this.  
+\item{**AssertionError: subcommand exit status 127**}  Certain tests run
+"cheetah" as a subcommand.  The failure may mean the command wasn't found
+in your system path. (What happens if you run "cheetah" on the command line?)
+The failure also happens on some Windows systems for unknown reasons.  This
+failure has never been observed outside the test suite.  Long term, we plan to
+rewrite the tests to do a function call rather than a subcommand, which will
+also make the tests run significantly faster.
+\item{**ImportError: No module named SampleBaseClass**}  The test tried to
+write a temporary module in the current directory and ``import`` it.  Reread
+the first paragraph in this section about the current directory.
+\item{**ImportError: No module named tmp**}  May be the same problem as
+SampleBaseClass; let us know if changing the current directory doesn't work.
+\end{description}
+
+  normally 'su root'.  On non-POSIX systems such as Windows NT, login as an
+  administrator.