removed docs dir

21 files changed, 0 insertions, 5028 deletions

diff --git a/docs/users_guide_src/Makefile b/docs/users_guide_src/Makefile
deleted file mode 100644
index c62b25e..0000000
--- a/docs/users_guide_src/Makefile
+++ /dev/null
@@ -1,38 +0,0 @@
-# You must change PYTHONSRC to the path of your Python source distributon.
-PYTHONSRC=/home/iron/nobackup/PYTHON/Python-2.2
-DOCNAME=users_guide
-MKHOWTO=$(PYTHONSRC)/Doc/tools/mkhowto
-MAIN_TEX_FILE= users_guide.tex
-
-all: ps pdf html htmlMultiPage text
-
-almost-all: ps html htmlMultiPage text
-
-pdf:
-	$(MKHOWTO) --pdf $(MAIN_TEX_FILE)
-	mv $(DOCNAME).pdf ../
-
-ps:
-	$(MKHOWTO) --ps $(MAIN_TEX_FILE)
-	mv $(DOCNAME).ps ../
-html:
-	-rm -rf $(DOCNAME)
-	$(MKHOWTO) --html --split 1 --iconserver . $(MAIN_TEX_FILE)
-	-rm -rf ../$(DOCNAME)_html
-	mv $(DOCNAME) ../$(DOCNAME)_html
-
-htmlMultiPage:
-	-rm -rf $(DOCNAME)
-	$(MKHOWTO) --html --iconserver . $(MAIN_TEX_FILE)
-	-rm -rf ../$(DOCNAME)_html_multipage
-	mv $(DOCNAME) ../$(DOCNAME)_html_multipage
-
-text:
-	$(MKHOWTO) --text $(MAIN_TEX_FILE)
-	mv $(DOCNAME).txt ../
-
-clean:
-	-rm -rf $(DOCNAME)
-	-rm -f *.aux *.l2h *~ *.log *.ind *.bkm *.how *.toc
-	-rm -rf ../html
-
diff --git a/docs/users_guide_src/README b/docs/users_guide_src/README
deleted file mode 100644
index 3b45564..0000000
--- a/docs/users_guide_src/README
+++ /dev/null
@@ -1,9 +0,0 @@
-To build the Cheetah documentation, you need the 'mkhowto' program from
-the Python source distribution.  So:
-
-1) Get the Python source distribution and unpack it in some directory.
-
-2) Edit the Cheetah documentation's Makefile and change PYTHONSRC to
-point to the top-level directory of your Python source distribution.
-
-3) Run 'make'.
diff --git a/docs/users_guide_src/comments.tex b/docs/users_guide_src/comments.tex
deleted file mode 100644
index 4389160..0000000
--- a/docs/users_guide_src/comments.tex
+++ /dev/null
@@ -1,176 +0,0 @@
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\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 has 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{Whitespace around comments}
-\label{comments.whitespace}
-
-Putting a comment on the same line as a directives may cause more whitespace in
-the output than you intend because the whitespace before the comment is not
-squeezed out.  To avoid this problem, put comments on separate lines with no
-whitespace before them, and you can skip this section.  If you still want to
-put comments on the same line as directives, read on.
-
-After a directive on the same line, you need an extra \code{\#} to end the
-directive:
-\begin{verbatim}
-#if $count == 0 # ## if the records are missing
-\end{verbatim}
-
-However, this will insert an extra space in the output (the space before the
-comment), appearing on its own line.  You can eliminate the space by eliminating
-the space (!): 
-\begin{verbatim}
-#if $count == 0 ### if the records are missing
-\end{verbatim}
-but then you'll get an empty line in the output.  To put a comment on that
-line {\em and} make the line not show up on the output, you need to use
-\code{\#slurp} with no spaces around it, as in example 3 below:
-
-\begin{verbatim}
-#attr $animals = ('horse', 'donkey')
-Example 1:
-#for $animal in $animals ### La la!
-The zoo contains $animal.
-#end for# ## $animal.
-******************************************
-Example 2:
-#for $animal in $animals
-The zoo contains $animal.
-#end for
-******************************************
-Example 3:
-#for $animal in $animals##slurp### La la!
-The zoo contains $animal.
-#end for##slurp### $animal.
-*****************************************
-\end{verbatim}
-
-And the output:
-
-\begin{verbatim}
-Example 1:
-
-The zoo contains horse.
-
-The zoo contains donkey.
- 
-******************************************
-Example 2:
-The zoo contains horse.
-The zoo contains donkey.
-******************************************
-Example 3:
-The zoo contains horse.
-The zoo contains donkey.
-*****************************************
-
-\end{verbatim}
-
-But obviously, a line like
-\begin{verbatim}
-#for $animal in $animals##slurp### La la!
-\end{verbatim}
-can be confusing to read.  You have to count hash characters to tell that the
-\code{\#\#} before \code{slurp} is not the beginning of a comment but instead
-is two directives next to each other.  Likewise, you have to remember
-that the first hash in \code{\#\#\#} ends the \code{slurp} directive, and the
-next two begin the comment.  Again, you can avoid all this confusion by putting
-your comments on separate lines.
-
-Modifying Cheetah to remove whitespace before comments and to remove lines
-that consist only of directives, whitespace and comments is on the TODO list.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\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: }:
-\code{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_src/comparisons.tex b/docs/users_guide_src/comparisons.tex
deleted file mode 100644
index 92d3fbe..0000000
--- a/docs/users_guide_src/comparisons.tex
+++ /dev/null
@@ -1,307 +0,0 @@
-\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: Is #extend unique too?
-
-%% @@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. PHPLib's Template class}
-\label{comparisons.php}
-
-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 of their
-own ideas (e.g.; a single array type serves as both a list and a dictionary,
-'\$arr[]="value";' appends to an array).
-
-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.  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_src/editors.tex b/docs/users_guide_src/editors.tex
deleted file mode 100644
index 84c8f03..0000000
--- a/docs/users_guide_src/editors.tex
+++ /dev/null
@@ -1,39 +0,0 @@
-\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_src/errorHandling.tex b/docs/users_guide_src/errorHandling.tex
deleted file mode 100644
index c88f477..0000000
--- a/docs/users_guide_src/errorHandling.tex
+++ /dev/null
@@ -1,137 +0,0 @@
-\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}
-\label{errorHandling.errorCatcher}
-
-\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}
-#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 be turned of 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_src/examples.tex b/docs/users_guide_src/examples.tex
deleted file mode 100644
index 75fa78a..0000000
--- a/docs/users_guide_src/examples.tex
+++ /dev/null
@@ -1,37 +0,0 @@
-\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}
-The 'examples' directory has a subdirectory called 'webware\_examples'.  It
-contains example servlets that use Webware.  
-
-A subdirectory titled 'cheetahSite' contains a complete website example. It
-is in fact the Cheetah web site
-(\url{http://www.cheetahtemplate.org/}), although the content has not been kept
-up to date.  The site demonstrates many advanced Cheetah features.  It also
-demonstrates how the \code{cheetah-compile} program can be used to generate
-Webware .py servlet files from .tmpl Template Definition files.
-
-%% MO: Removed because Tavis deleted the directory:
-% A subdirectory titled 'webwareSite' contains a complete website example. This
-% site is my proposal for the new Webware website.  The site demonstrates the
-% advanced Cheetah features.  It also demonstrates how the 
-% \code{cheetah-compile} program can be used to generate Webware .py servlet
-% files from .tmpl Template Definition files.
-
-% Local Variables:
-% TeX-master: "users_guide"
-% End:      
diff --git a/docs/users_guide_src/flowControl.tex b/docs/users_guide_src/flowControl.tex
deleted file mode 100644
index fab5056..0000000
--- a/docs/users_guide_src/flowControl.tex
+++ /dev/null
@@ -1,295 +0,0 @@
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Flow Control}
-\label{flowControl}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{\#for ... \#end for}
-\label{flowControl.for}
-
-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() # ## Or $dict.iteritems() in Python >= 2.2.
-$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}
-\code{\#echo ', '.join(\$names)}).
-\end{verbatim}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{\#repeat ... \#end repeat}
-\label{flowControl.repeat}
-
-Do something a certain number of times.
-\begin{verbatim}
-#repeat 3
-My bonnie lies over the ocean
-#end repeat
-O, bring back my bonnie to me!
-\end{verbatim}
-(OK, so the second line should be ``sea'' instead of ``ocean''.)
-
-The argument may be any numeric expression:
-\begin{verbatim}
-#repeat $times + 3
-She loves me, she loves me not.
-#repeat
-She loves me.
-\end{verbatim}
-
-If the argument is zero or negative, the loop will execute zero times.
-
-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}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{\#while ... \#end while}
-\label{flowControl.while}
-
-\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}
-
-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 {\#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}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{\#unless ... \#end unless}
-\label{flowControl.unless}
-
-\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}
-
-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 step 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 == 10
-  #break
-#end if
-$name - #slurp
-#end for
-\end{verbatim}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{\#pass}
-\label{flowControl.pass}
-
-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.
-
-In this example the output list will not contain ``10 - ''. 
-\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}
-
-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}
-
-
-% Local Variables:
-% TeX-master: "users_guide"
-% End:      
diff --git a/docs/users_guide_src/gettingStarted.tex b/docs/users_guide_src/gettingStarted.tex
deleted file mode 100644
index b79a4e0..0000000
--- a/docs/users_guide_src/gettingStarted.tex
+++ /dev/null
@@ -1,243 +0,0 @@
-\section{Getting Started}
-\label{gettingStarted}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Requirements}
-\label{gettingStarted.requirements}
-
-Cheetah requires Python release 2.0 or greater.  , and should run anywhere
-Python runs.  It has been tested with Python 2.0, 2.1 and 2.2.  It is known to
-run on Linux, Windows NT/98/XP, FreeBSD and Solaris, and should run anywhere
-Python runs.  
-
-99\% of Cheetah is written in Python.  There is one small C module
-(\code{\_namemapper.so}) for speed, but Cheetah automatically falls back to a
-Python equivalent if the C module is not available.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Installation}
-\label{gettingStarted.install}
-
-To install Cheetah to your system-wide Python library:
-\begin{enumerate}
-\item Login as a user with privileges to install system-wide Python packages.
-     On POSIX systems (AIX, Solaris, Linux, IRIX, etc.), the command is normally
-     'su root'.  On non-POSIX systems such as Windows NT, login as an
-     administrator.
-
-\item Run \code{python setup.py install} at the command prompt.
-
-\item The setup program will install the wrapper script {\bf cheetah} to 
-     wherever it usually puts Python binaries ("/usr/bin/", "bin/" in the 
-     Python install directory, etc.)
-\end{enumerate}
-
-%% @@MO: What about cheetah-compile on non-POSIX systems? 
-
-To install Cheetah to an alternate location use the options to setup.py's
-\code{install} command:
-\begin{verbatim}
-    python setup.py install --home /home/tavis 
-\end{verbatim}
-and
-\begin{verbatim}
-    python setup.py install --install-lib /home/tavis/lib/python
-both install to /home/tavis/lib/python/Cheetah
-\end{verbatim}
-
-Cheetah's installation is managed by Python's Distribution Utilities
-('distutils').  There are many options for customization.  Type \code{``python
-  setup.py help''} for more information.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Files}
-\label{gettingstarted.files}
-
-If you do the systemwide install, all Cheetah modules are installed in the
-{\bf site-packages/Webware/Cheetah/} subdirectory of your standard library
-directory; e.g., /opt/Python2.2/lib/python2.2/site-packages/Webware/Cheetah.
-
-A file site-packages/Webware.pth causes Python to put 
-site-packages/Webware in the standard Python path, so that when you or a
-script executes \code{from Cheetah.Template import Template}, it works as
-expected.
-
-This site-packages/Webware/ directory is otherwise empty unless you've 
-installed the WebwareExperimental package (not the standard Webware--unless
-perhaps Webware switches to distutils in the future).  You may be surprised to
-have a site-packages/Webware/ directory when you're not using Webware, but
-don't worry: Cheetah's author just chose to package Cheetah that way, and
-Cheetah works the same whether Webware is installed or not.
-
-Two commands are installed in Python's \code{bin/} directory or a system
-bin directory: \code{cheetah} (section \ref{gettingStarted.cheetah}) and
-\code{cheetah-compile} (section \ref{howWorks.cheetah-compile}).  
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Uninstalling}
-\label{gettingstarted.uninstalling}
-
-% @@MO: When 'python setup.py uninstall' is implemented, mention it here.
-
-If you play with Cheetah a while and decide not to use it, it's easy to
-uninstall.  Merely delete the site-packages/Webware/Cheetah/ directory
-(or site-packages/Webware/ if it's otherwise empty) and the
-site-packages/Webware.pth file.
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{The 'cheetah' command}
-\label{gettingStarted.cheetah}
-
-Cheetah comes with a utility \code{cheetah} that provides a command-line
-interface to various housekeeping tasks.  The command's first argument is
-the name of the task.  The following tasks are currently supported:
-
-\begin{verbatim}
-cheetah --help|-h            
-          - Print this usage information
-cheetah compile|-c [compiler options]
-          - Run Cheetah's compiler ('cheetah compile --help' for more)
-cheetah test|-t [test options]
-          - Run Cheetah's test suite ('cheetah test --help' for more)
-cheetah --version|-v
-          - Print Cheetah's version number
-cheetah fill|-f
-          - Fill template(s) [not implemented yet]
-\end{verbatim}
-
-The test suite is described in the next section.  The compiler will be
-described in section \ref{howWorks.cheetah-compile}, along with the
-separate \code{cheetah-compile} command which does the same thing.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{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.  Type the following at the command prompt:
-\begin{verbatim}
-cheetah test 
-\end{verbatim}
-
-The tests will run for a minute or so and then print a success/failure message.
-If the tests pass, start Python in interactive mode and try the example in the
-next section.
-
-If any of the 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:
-
-\begin{enumerate}
-\item your version of Cheetah
-\item your version of Python
-\item your operating system
-\item whether you have changed anything in the Cheetah installation
-\end{enumerate}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Quickstart tutorial}
-\label{gettingStarted.tutorial}
-
-This tutorial briefly introduces the basic usage of Cheetah.  See the
-following chapters for more features and more detailed explanations.  
-
-The core of Cheetah is the \code{Template} class in the \code{Cheetah.Template}
-module. The following example shows how to use the \code{Template} class in an
-interactive Python session. Lines prefixed with \code{>>>} and \code{...} are
-user input.  The remaining lines are Python output.
-
-\begin{verbatim}
->>> 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
-...    blah, blah, blah 
-... *#
-... </BODY>
-... </HTML>"""
->>> nameSpace = {'title': 'Hello World Example', 'contents': 'Hello World!'}
->>> templateObj = Template(templateDef, searchList=[nameSpace])
->>> print templateObj
- 
-<HTML>
-<HEAD><TITLE>Hello World Example</TITLE></HEAD>
-<BODY>
-Hello World!
-</BODY>
-</HTML>
->>> print templateObj    # print it as many times as you want
-      [ ... same output as above ... ]
->>> nameSpace['title'] = 'Example #2'
->>> nameSpace['contents'] = 'Hiya Planet Earth!'
->>> print templateObj   # Now with different plug-in values.
-<HTML>
-<HEAD><TITLE>Example #2</TITLE></HEAD>
-<BODY>
-Hiya Planet Earth!
-</BODY>
-</HTML>
-
-\end{verbatim}
-
-Since Cheetah is extremely flexible, you can achieve the same result this
-way:  
-
-\begin{verbatim}
->>> templateObj2 = Template(templateDef)
->>> templateObj2.title = 'Hello World Example!'
->>> templateObj2.contents = 'Hello World'
->>> print templateObj2
-      [ ... same output as the first example above ... ]
->>> templateObj2.title = 'Example #2'
->>> templateObj2.contents = 'Hello World!'
->>> print templateObj2
-     [ ... same as Example #2 above ... ]
-\end{verbatim}
-
-Or this way:
-
-\begin{verbatim}
->>> class Template3(Template):
->>>     title = 'Hello World Example!'
->>>     contents = 'Hello World!'
->>> templateObj3 = Template3(templateDef)
->>> print templateObj3
-     [ ... you get the picture ... ]
-\end{verbatim}
-
-The template definition can also come from a file instead of a string,
-as we will see in section \ref{howWorks.constructing}.
-
-The above is all fine for short templates, but for long templates or
-for an application that depends on many templates in a hierarchy, it's
-easier to store the templates in separate *.tmpl files and use the
-{\bf cheetah compile} program to convert them into Python classes in
-their own modules.  This will be covered in section
-\ref{howWorks.cheetah-compile}.  
-
-As an appetizer, we'll just briefly mention that you can store constant values
-{\em inside} the template definition, and they will be converted to attributes
-in the generated class.  You can also create methods the same way.
-You can even use inheritance to arrange your templates in a hierarchy,
-with more specific templates overriding certain parts of more general
-templates (e.g., a "page" template overriding a sidebar in a "section"
-template).
-
-For the minimalists out there, here's a template definition,
-instantiation and filling all in one Python statement:
-
-\begin{verbatim}
->>> print Template("Templates are pretty useless without placeholders.")
-Templates are pretty useless without placeholders.
-\end{verbatim}
-
-
-% Local Variables:
-% TeX-master: "users_guide"
-% End:      
-
diff --git a/docs/users_guide_src/howItWorks.tex b/docs/users_guide_src/howItWorks.tex
deleted file mode 100644
index ab2c55e..0000000
--- a/docs/users_guide_src/howItWorks.tex
+++ /dev/null
@@ -1,333 +0,0 @@
-\section{How Cheetah Works}
-\label{howWorks}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{The Template Class}
-\label{howWorks.templateClass}
-
-The heart of Cheetah is the \code{Template} class in the
-\code{Cheetah.Template} module. It serves two purposes. First, its constructor
-accepts a {\bf template definition} in a string or a file (filename or file
-object).  Cheetah compiles the template definition into a Python class (the
-{\bf generated class}). Second, \code{Template} itself serves as the base class
-for the generated class.  \code{Template} subclasses Webware's
-\code{HTTPServlet} class when available, so the generated class can be used
-as a Webware servlet.
-
-A template is compiled automatically the first time it's {\bf filled}.
-(Filling is what you do when you make a finished string from the template,
-with all the placeholder values substituted in.) If you use a \code{Template}
-object as in the previous two examples (sections \ref{intro.whatIs} and
-\ref{gettingStarted.tutorial}), the generated class is overlaid into the
-template object itself.  That is, the generated class is a dynamic superclass
-that affects only that \code{Template} instance, not any other other
-\code{Template} instances.  Don't worry if you don't understand this; 
-it does the ``right thing'' behind the scenes.
-
-If you instead precompile the template by running the \code{cheetah-compile}
-program below, the hidden generated class is exposed.  It's written to a
-file, with some boilerplate code around it to make a bona fide Python module
-(called a {\bf .py template module}).  This ``freezes'' the class.  Anytime
-later you can ``unfreeze'' it by importing and instantiating the class.  The 
-advantage of this is speed: compile once, use many times.  Plus, if Python
-has made a .pyc or .pyo file, you can skip Python's compilation step too.
-The speed difference is negligable if you templates just occasionally,
-because every template operation seems to be instantaneous, but it may make a
-difference for applications such as Webware that use many templates a second.
-
-To fill a template, you call its {\bf main method}.  This is normally 
-\code{.respond()}, but under certain circumstances it's \code{.writeBody()} or
-a user-defined name.  (Section \ref{inheritanceEtc.implements} explains why
-the method name is not always the same.)  However, \code{.\/\_\_str\_\_()} is
-always an alias for the main method, so you can always use
-\code{print\ myTemplateInstance} or \code{str(myTempateInstance)} to fill it.
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Constructing Template Objects}
-\label{howWorks.constructing}
-
-Here are typical ways to create a template object:
-\begin{description}
-\item{\code{templateObj = Template("The king is a \$placeholder1.")}}
-     \\ Pass the Template Definition as a string.
-\item{\code{templateObj = Template(file="fink.tmpl")}}
-     \\ Read the Template Definition from a file named "fink.tmpl".  
-\item{\code{templateObj = Template(file=f)}}
-     \\ Read the Template Definition from file-like object 'f'.
-\item{\code{templateObj = Template("The king is a \$placeholder1.", searchList=[dict, obj])}}
-     \\ Pass the Template Definition as a string.  Also pass two Namespaces for
-     the searchList: a dictionary 'dict' and an instance 'obj'.
-\item{\code{templateObj = Template(file="fink.txt", searchList=[dict, obj])}}
-     \\ Same, but pass a filename instead of a string.
-\item{\code{templateObj = Template(file=f, searchList=[dict, obj])}}
-     \\ Same with a file object.
-\end{description}
-
-The constructor accepts the following keyword arguments:
-
-\begin{description}
-\item{{\bf source}}
-     The template definition as a string.  You may omit the \code{source=}
-     prefix {\em if it is the first argument}, as in all the examples above.
-     The source can be a string literal in your module, or read from a database
-     or other data structure.
-\item{{\bf 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.
-\item{{\bf searchList}}
-     A list of objects to search for \code{\$placeholder} values.
-\item{{\bf filter}}
-     A class that will format every \code{\$placeholder} value.  You may
-     specify a class object or string.  If a class object,
-     it must be a subclass of \code{Cheetah.Filters.Filter}.  If a string, it
-     must be the name of one of the filters in filtersLib module (see next 
-     item).
-     (You may also use the \code{\#filter} directive (section
-     \ref{output.filter}) to switch filters at runtime.)
-\item{{\bf filtersLib}}
-     A module containing the filters Cheetah should look up by name.  The
-     default is \code{Cheetah.Filters}.  All classes in this module that are
-     subclasses of \code{Cheetah.Filters.Filter} are considered filters.
-\item{{\bf errorCatcher}}
-     A class to handle \code{\$placeholder} errors.  You may
-     specify a class object or string.  If a class object,
-     it must be a subclass of \code{Cheetah.ErrorCatchers.ErrorCatcher}.  
-     If a string, it must be the name of one of the error catchers in
-     \code{Cheetah.ErrorCatchers}.  This is similar to the 
-     \code{\#errorCatcher} directive 
-     (section \ref{errorHandling.errorCatcher}).
-\item{{\bf compilerSettings}}
-     A dictionary (or dictionary hierarchy) of settings that change Cheetah's
-     behavior.  Not yet documented.
-\end{description}
-
-You {\em must} specify either {\bf source} or {\bf file}, but not both.  
-EXCEPTION: When using a precompiled template class created by
-\code{cheetah compile}, you do {\em not} specify a {\bf source} or {\bf
-file} argument, since the source is built into the class.  You may, however,
-use the other arguments if you wish.
-
-\begin{verbatim}
-from MyPrecompiledTemplate import MyPrecompiledTemplate
-t = MyPrecompiledTemplate()
-t.name = "Fred Flintstone"
-t.city = "Bedrock City"
-print t
-\end{verbatim}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{cheetah-compile and .py template modules}
-\label{howWorks.cheetah-compile}
-
-% @@MO: Talk about cheetah-compile vs 'cheetah compile'.
-
-If your application requires only a few short template definitions, you can
-just put them in your modules as strings.  But if your application has large
-templates or many templates, it's more convenient to put each in a separate
-*.tmpl file and use Cheetah's compiler to convert it into a *.py template
-module.  A {\bf .py template module} is a Python module with the same name as
-the template, containing the generated class which is also named after the
-template.  
-
-Run ``\code{cheetah compile --help}'' from the command line after installing
-Cheetah to get usage information.  The most common usage is
-``\code{cheetah compile -R}'', which will convert all the *.tmpl files in the
-current directory and its subdirectories.
-
-
-There are actually three ways to invoke the compiler:
-\begin{verbatim}
-cheetah compile ...
-cheetah -c ...
-cheetah-compile ...
-\end{verbatim}
-All three ways are identical and accept the same command-line arguments.
-(The separate program \code{cheetah-compile} exists for backward compatibility.
-This Guide also uses the term cheetah-compile extensively because it stands out
-without requiring quotes.)
-
-When cheetah-compile converts {\bf FILENAME.tmpl} in some directory, it
-overwrites {\bf FILENAME.py} in the same directory if it exists, after backing
-it up to FILENAME.py\_bak.  For this reason, you should make changes to the
-\code{.tmpl} version of the template rather than to the \code{.py} version.
-
-For the same reason, if your template requires custom Python methods or
-other Python code, don't put it in the \code{FILENAME.py} file.  Instead, put
-it in a separate base class and use the \code{\#extends} directive to
-inherit from it.
-
-Because FILENAME will be used as a class and module name, it must be a valid
-Python identifier.  For instance, \code{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.
-
-One of the advantages of cheetah compile is that you don't lose any
-flexibility.  The generated class contains all \code{\#attr} values and
-\code{\#def}/\code{\#block} values as ordinary attributes and methods, so you
-can read the values individually from other Python tools for any kind of custom
-processing you want.  For instance, you can extract the titles of all
-your templates into a database, or find all the servlets with a certaion
-\code{\$author} value.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Some trivia about .py template modules}
-\label{howWorks.pyTrivia}
-
-We won't look inside .py template modules in this Guide except to note that
-they are very different from template definitions.  The following template
-definition fragment:
-
-\begin{verbatim}
-The number is $Test.unittest.main.
-\end{verbatim}
-
-compiles to this:
-
-\begin{verbatim}
-write("The number is ")  
-write(filter(VFN(VFS(SL,"Test.unittest",1),"main",0)
-write(".")
-\end{verbatim}
-
-In the upcoming Cheetah Developers' Guide, we'll look at .py template
-modules in depth, and see what the various directives compile to.
-But you are welcome to take a peek at some .py template modules yourself
-if you're curious about what Cheetah does under the hood.  It's all
-regular Python code: writing strings and function calls to a file-like
-object.
-
-Looking at a .py template module may also help you see why something
-doesn't work, by seeing what Cheetah thought you meant.  It also helps 
-discourage you from modifying the .py file yourself, because who wants to
-keep all those function calls and arguments straight?  Let the computer
-do the drudgery work.
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Running your .py template module as a standalone script}
-\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 \code{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 \code{NameMapper.NotFound} exception at
-the first missing value.
-
-Fortunately, there are three ways to supply values to .py template modules
-run as standalone programs:
-
-\begin{description}
-\item{{\bf Default values}}  You can set default values in the template itself
-     (via the \code{\#attr} or \code{\#def} directives) or in a Python
-     superclass.
-\item{{\bf Environment variables}} If you use the \code{--env} command-line
-option, Cheetah will look in the environment for values.  This is the easiest
-way to pass values from a shell script.
-\item{{\bf A pickle file}}  If you use the \code{--pickle PICKLE\_FILE} option, 
-     Cheetah will unpickle the file and place the resulting data structure in
-     the searchList.    See the standard Python modules \code{pickle} and
-     \code{cPickle} for more information.  (The truly masochistic who love
-     filters can even use \code{--pickle -} to read the pickle data from
-     standard input.)
-\end{description}
-
-You can always run \code{python FILENAME.py --help} to see all the command-line
-options your template program accepts.  (That's a double hyphen before the
-``help'', even if LaTeX misformats it as single hyphen.)
-
-Cheetah .py templates that will be used as Webware servlets can also be 
-debugged this way.  The only caveat is that if they do any processing that
-tries to call back into a live web transaction (such as looking for form
-input data), they will raise an exception since there is no web transaction
-in progress.  Those servlets must be debugged by calling them through the
-web.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{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:
-
-\begin{verbatim}
-#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>
-\end{verbatim}
-
-And its subclassed document, Frog1.tmpl:
-\begin{verbatim}
-#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
-\end{verbatim}
-
-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
-\code{\$htTitle} so that by default it's identical to whatever the 
-\code{\$title} is, but it can also be customized.  This is because HTML's
-\code{<TITLE>} tag cannot contain embedded tags, but we may want to use
-embedded tags in the \code{H1} title for special effect.  Yet for simple
-cases where the two are identical, we don't want to bother with
-\code{\$htTitle} at all: we just want to set \code{\$title} and forget about
-it.
-
-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 \code{\$body} and \code{\$title}, simply by
-defining body() and title() methods that return a string.  (Actually they
-can return anything, but we'll get into that later.)  
-
-\begin{verbatim}
-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 ..."
-\end{verbatim}
-
-Similarly, the Cheetah document can inherit from an arbitrary class. This
-technique is used when combining Cheetah with Webware for Python
-(chapter \ref{webware}): the base template for your site inherits (indirectly)
-from the Webware HTTPServlet class.  The classes are sufficiently generic that
-similar techniques should be possible for other systems.
-
-({\em Note:}\ \code{FrogBase.tmpl} could be improved by using the
-\code{\#block} directive, section \ref{inheritanceEtc.block}.)
-
-% Local Variables:
-% TeX-master: "users_guide"
-% End:      
-
diff --git a/docs/users_guide_src/inheritanceEtc.tex b/docs/users_guide_src/inheritanceEtc.tex
deleted file mode 100644
index c17cd8a..0000000
--- a/docs/users_guide_src/inheritanceEtc.tex
+++ /dev/null
@@ -1,495 +0,0 @@
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Import, Inheritance, Declaration and Assignment}
-\label{inheritanceEtc}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{\#import and \#from directives}
-\label{inheritanceEtc.import}
-
-The \code{\#import} and \code{\#from} directives are used to import Python
-modules or stuff from inside modules.  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.
-
-The wildcard form \code{from MODULE import *} is not supported:
-\begin{verbatim}
-#from math import *         # ## No!  
-$sin(8)                       ## Raises NameMapper.NotFound error at fill time.
-\end{verbatim}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{\#extends}
-\label{inheritanceEtc.extends}
-
-All templates are subclasses of \code{Cheetah.Template.Template}.  This is what
-gives them template functionality and allows them to be used as Webware
-servlets.  By default they are direct subclasses, meaning \code{Template} is
-the immediate parent of the generated class.  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 if you haven't imported it yet, so you can skip the
-\code{\#import} or \code{\#from} directive and save some clutter in your
-template.  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 is in a module named 
-differently than the class, you must import it explicitly.
-
-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 still 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}.
-
-You may make an inheritance chain as long as you wish, containing templates and
-pure Python classes, provided the top of the chain (the most general
-superclass) is \code{Template}.  If your topmost class is a template, simply
-omit the \code{\#extends} in that template and it will automatically inherit
-\code{Template}.  If your topmost class is a pure Python class, you 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
-\code{Template} is at the top, and overriding methods call their
-superclass methods, 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 at the bottom.  Each template inherits from a
-pure Python class that contains methods/attributes used by the template.
-We'll begin with the highest-level 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)
-        #from SiteLogic import SiteLogic
-	#extends SiteLogic
-
-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.
-
-The presence of \code{\#extends} influences what the generated class's main
-method is named--the method you call to fill the template.  The next section,
-\code{\#implements}, explains this.
-
-% @@MO: Edmund suggests making some diagrams of inheritance chains.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{\#implements}
-\label{inheritanceEtc.implements}
-
-A template object has several methods, but there is always one {\bf main
-method}, the one you call to fill the template.  By default, this method is
-\code{.respond()}.  However, if your template contains an \code{\#extends}
-directive, the main method's name changes to \code{.writeBody()}.  It does
-this for compatibility with Webware servlets.  You can also use the
-\code{\#implements} directive to specify the name of the method yourself.
-You may need to do this if you're integrating Cheetah into a legacy
-application, and that application wants to call a method called
-\code{.send\_output}, for instance.
-
-% @@MO: "Compatibility with Webware servlets" is a lame explanation.  Elaborate.
-
-\begin{verbatim}
-#implements send_output
-\end{verbatim}
-
-In any case, \code{.\/\_\_str\_\_} is always an alias for the main method, no
-matter what the main method is called.  So you can always call \code{str(t)} to
-fill your template, or \code{print t} to fill and print it.  
-
-% @@MO: deleted, unnecessary
-% But of course, in a Webware servlet you never use the \code{print} statement
-% directly except for debugging.
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{\#set}
-\label{inheritanceEtc.set}
-
-\code{\#set} is used to create and update local variables at run time.
-\code{\#set \$var = EXPRESSION}. 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}
-$adj = $size > 1500 and 'large' or 'small'
-\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{\#attr}
-\label{inheritanceEtc.attr}
-
-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):
-
-(Example to be written later.)
-%\begin{verbatim}
-%import glob
-%
-%\end{verbatim}
-%
-% @@MO: Finish this example.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{\#def}
-\label{inheritanceEtc.def}
-
-The \code{\#def} directive is used to declare new methods in the generated
-Python class.  It is roughly 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 accept arguments and have defaults for those arguments, just like
-in Python.  Always use 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}
-
-If a method already exists with the same name as the \code{\#def}, it will be
-replaced with the new definition.  If the new \code{\#def} occurs in a
-subclass, it overrides the parent's definition.  See the \code{\#extends}
-directive above for information about subclasses.  Overriding is frequently
-used for blocks, which will be described next.
-
-There is also a single line version of the \code{\#def} directive:
-
-\begin{verbatim}
-#attr $adj = 'trivial'
-#def myMeth: This is the $adj method 
-$myMeth
-\end{verbatim}
-
-Because of the difference between compile time and run time, you can place
-your \code{\#def}s anywhere in the template.  However, human readers of your
-template definition won't necessarily expect this.  To make the template
-definition easier for future maintainers to read, define your methods above
-the point you call them.
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\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
-selectively 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 [blockName] 
-[block contents] 
-#end block [blockName]
-
-#block testBlock
-Text in the contents 
-area of the block directive
-#if $testIt
-$getFoo() 
-#end if
-#end block testBlock
-\end{verbatim}
-
-% @@MO: The [] imply the block name is optional.  Is it?
-
-\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}
-later in the template to output the block content again.
-
-The block must not require arguments because the implicit placeholder that's
-generated will call the block without arguments.
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{\#settings ... \#endSettings}
-\label{inheritanceEtc.settings}
-
-The \code{\#settings} directive works in tandem with Cheetah's
-{\bf SettingsManager} system to provide yet another way to set values for
-\code{\#placeholders} to find, or for Python methods to read and modify their
-behaviour accordingly.  It is best understood by reading the comments in
-\code{SettingsManager.py} in conjunction with this section.  All 
-template objects inherit \code{Cheetah.SettingsManager.SettingsManager}.
-
-Settings are syntactically similar to compiler settings (the
-\code{\#compiler-settings} directive, section
-\ref{parserInstructions.compiler-settings}), but while compiler settings
-influence Cheetah's core behaviour, regular settings exist solely for the
-convenience of user code.
-
-{\em Settings are not visible to placeholders by default.}  To make settings
-visible to placeholders, put the settings object in the searchList:  
-
-\begin{verbatim}
-#silent $addToSearchList($settings)  # ## Autocalls the method.
-
-self.addToSearchList(self.settings())
-\end{verbatim}
-
-% @@MO: Is it possible to add the settings to the searchList at template
-% .__init__ time?
-
-To read a setting in a method, you don't just read self.setting\_name.  Instead
-you use the \code{.setting(name, default=NoDefault)} method to read a setting,
-\code{.setSetting(name, value)} to set it, and \code{.hasSetting(name)} to
-check whether a setting exists.  
-
-\code{SettingsManager} is a system for managing application settings.  An
-Application may subclass \code{SettingsManager.SettingsManager} and gain access
-to some sophisticated methods for getting and setting key/value pairs
-("settings") individually, or in bulk from a dictionary or a hierarchy of
-dictionaries.  You can pass in a dictionary of dictionaries (of dictionaries,
-etc...) containing only the keys and subkeys (and subkeys, etc...) that have
-changed, and SettingsManager will merge all the changes in.  SettingsManager can
-also read settings in from modules, exec'able Python strings/files, and
-strings/files in Python's standard \code{ConfigParser} format (aka Windows .ini
-format).  Unlike ConfigParser, however, because it parses case-sensitively, and
-automatically converts numeric values to numbers, 'None' to None, and 'true' and
-'false' to Boolean true and false.
-
-What does this have to do with Cheetah templates? When you have large sets of
-hierarchically structured data that you want to make available to
-\$placeholders, the (\code{\#settings} directive can be convenient
-alternative to \code{\#attr} and \code{\#def}:
-
-\begin{verbatim}
-#settings
-[SubSection1]
-test = blarg
-
-[SubSection2]
-test = foo
-#end settings
-$settings.SubSection1.test
-
-#settings python
-SubSection1 = {
-  'test':'blarg',
-  }
-SubSection2 = {
-  'test':'foo',
-  }
-#end settings
-$settings.SubSection1.test
-\end{verbatim}
-
-in your template and get the following output:
-
-\begin{verbatim}
-blarg
-
-blarg
-\end{verbatim}
-
-The first stanza is in ConfigParser format (aka Windows .ini format)--note the
-lack of \code{\$} before the key, and the lack of quotes around the value.  The
-second stanza is in Python format, as if it were a Python module, with quotes,
-but no \code{\$}.
-
-You can also place your template object's settings dictionary in \code{the
-searchList} so you can type \code{\$mySetting} instead of
-\code{\$settings.mySetting}.
-
-Dictionary merging can be turned off with the 'nomerge' keyword:
-
-\begin{verbatim}
-#settings python nomerge
-SubSection1 = {
-  'test':'blarg',
-  }
-SubSection2 = {
-  'test':'foo',
-  }
-#end settings
-$settings.SubSection1.test
-\end{verbatim}
-
-Output filters (\code{\#filter} directive, section \ref{output.filter}),
-for instance, can use settings to customize their behaviour, although none
-do at present.
-
-% Local Variables:
-% TeX-master: "users_guide"
-% End:      
diff --git a/docs/users_guide_src/introduction.tex b/docs/users_guide_src/introduction.tex
deleted file mode 100644
index 246cba8..0000000
--- a/docs/users_guide_src/introduction.tex
+++ /dev/null
@@ -1,316 +0,0 @@
-\section{Introduction}
-\label{intro}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Who should read this Guide?}
-\label{intro.whoShouldRead}
-
-This Users' Guide provides a complete technical overview and reference for the
-Cheetah template system.  Knowledge of Python and object-orientated programming
-is assumed.  A gentler introduction for template maintainers who don't know
-Python will be written later, along with a Developers' Guide explaining
-Cheetah's internals.
-
-This Guide also contains examples of integrating Cheetah with Webware for
-Python.  You will have to learn Webware from its own documentation in order to
-build a Webware + Cheetah site.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{What is Cheetah?}
-\label{intro.whatIs}
-
-Cheetah is a Python-powered template engine and code generator.  It may be used
-as a standalone utility or combined with other tools.  Cheetah has
-many potential uses, but web developers looking for a viable alternative to ASP,
-JSP, PHP and PSP are expected to be its principle user group.
-
-Cheetah:
-\begin{itemize}        
-\item generates HTML, SGML, XML, SQL, Postscript, form email, LaTeX, or any
-     other text-based format.
-     
-\item 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.
-     
-\item blends the power and flexibility of Python with a simple template language
-     that non-programmers can understand.
-     
-\item gives template writers full access in their templates to any Python data
-     structure, module, function, object, or method.
-     
-\item 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.
-     
-\item provides a simple, yet powerful, caching mechanism that can dramatically
-     improve the performance of a dynamic website.
-     
-\item compiles templates into optimized, yet readable, Python code.
-\end{itemize}   
-
-Cheetah integrates tightly with {\bf Webware for Python}
-(\url{http://webware.sourceforge.net/}): a Python-powered application server and
-persistent servlet framework. Webware provides automatic session, cookie, and
-user management and can be used with almost any operating-system, web server, or
-database. Through Python, it works with XML, SOAP, XML-RPC, CORBA, COM, DCOM,
-LDAP, IMAP, POP3, FTP, SSL, etc.. Python supports structured exception handling,
-threading, object serialization, unicode, string internationalization, advanced
-cryptography and more. It can also be extended with code and libraries written
-in C, C++, Java and other languages.
-
-Like Python, Cheetah and Webware are Open Source software and are supported by
-active user communities.  Together, they are a powerful and elegant framework
-for building dynamic web sites. 
-
-Like its namesake, Cheetah is fast, flexible and powerful.
-
-% @@MO: Repeat picture of cheetah.
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{What is the philosophy behind Cheetah?}
-\label{intro.philosophy}
-
-Cheetah's design was guided by these principles:
-\begin{itemize}
-\item Python for the back end, Cheetah for the front end.  Cheetah was
-     designed to complement Python, not replace it.
-     
-\item Cheetah's core syntax should be easy for non-programmers to learn.
-          
-\item Cheetah should make code reuse easy by providing an object-oriented
-     interface to templates that is accessible from Python code or other
-     Cheetah templates.
-     
-\item Python objects, functions, and other data structures should be fully
-     accessible in Cheetah.
-       
-\item 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.
-
-\item 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:
-
-     \begin{itemize}
-     \item for {\bf programmers} to create reusable components and functions
-          that are accessible and understandable to designers.
-     \item for {\bf designers} to mark out placeholders for content and 
-          dynamic components in their templates.
-     \item for {\bf designers} to soft-code aspects of their design that are
-          either repeated in several places or are subject to change.
-     \item for {\bf designers} to reuse and extend existing templates and thus
-          minimize duplication of effort and code.
-     \item and, of course, for {\bf content writers} to use the templates that
-          designers have created.
-     \end{itemize}
-
-\end{itemize}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Give me an example!}
-\label{intro.example}
-
-Here's a very simple example that illustrates some of Cheetah's basic syntax:
-
-\begin{verbatim}
-
-<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>
-\end{verbatim}
-
-Compare this with PSP:
-
-\begin{verbatim}
-<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%>
-</TABLE>
-
-</BODY>
-</HTML>
-\end{verbatim}
-
-Section \ref{gettingStarted.tutorial} has a more typical example, and section
-\ref{howWorks.cheetah-compile} explains how to turn your template definition
-into an object-oriented Python module.
-
-%% @@TR: I'm going to extend this and briefly introduce: 
-%% - Template objects vs. .tmpl files.
-%% - how to get data into it 
-%% @@MO: If you do this, reconcile this example and the one in gettingStarted.
-%%   Keep two examples or collapse into one?
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{How mature is Cheetah?}
-\label{intro.mature}
-
-Cheetah is in alpha state, but the syntax, semantics and performance have been
-generally stable since an overhaul in mid 2001.  Most development since
-October 2001 has been in response to specific requests by production sites,
-things they need that we hadn't considered.  We are delaying a 1.0 release to
-give more time for these requests to trickle in.  We want to see Cheetah running
-a couple high-traffic public sites before releasing 1.0, preferably sites that
-are willing to make public the details of "how I built this thing using
-Cheetah".
-
-The {\bf TODO file} in the Cheetah distribution and the {\bf ToDo page} on the
-wiki (see below) show what we're working on now or planning to work on.  Look
-both places for a complete picture.  The {\bf WishList page} on the wiki shows
-requested features we're considering but haven't commited to.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Where can I get news?}
-\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.
-
-The Cheetah {\bf wiki} is becoming an increasingly popular place to list
-examples of Cheetah in use, provide cookbook tips for solving various problems,
-and brainstorm ideas for future versions of Cheetah.
-\url{http://www.cheetahtemplate.org/wiki}
-(The wiki is actually hosted at
-\url{http://cheetah.colorstudy.net/twiki/bin/view/Cheetah/WebHome}, but the 
-other URL is easier to remember.)
-For those unfamiliar with a wiki, it's a type of Web site that readers can edit
-themselves to make additions or corrections to.  Try it.  Examples and tips 
-from the wiki will also be considered for inclusion in future versions of this
-Users' Guide.
-
-If you encounter difficulties, or are unsure about how to do something,
-please post a detailed message to the list.  
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{How can I contribute?}
-\label{intro.contribute}
-
-Cheetah is the work of many volunteers.  If you use Cheetah please share your
-experiences, tricks, customizations, and frustrations.
-
-\subsubsection{Bug reports and patches}
-
-If you think there is a bug in Cheetah, send a message to the e-mail list
-with the following information:
-
-\begin{enumerate}
-\item a description of what you were trying to do and what happened
-\item all tracebacks and error output
-\item your version of Cheetah
-\item your version of Python
-\item your operating system
-\item whether you have changed anything in the Cheetah installation
-\end{enumerate}
-
-\subsubsection{Example sites and tutorials}
-If you're developing a website with Cheetah, please put a link on the wiki on
-the {\bf WhoIsUsingCheetah} page, and mention it on the list.  Also, if you
-discover new and interesting ways to use Cheetah, please put a quick tutorial
-(HOWTO) about your technique on the {\bf CheetahRecipies} page on the wiki.
-
-\subsubsection{Template libraries and function libraries}
-We hope to build up a framework of Template libraries (see section
-\ref{libraries.templates}) to distribute with Cheetah and would appreciate any
-contributions.
-
-\subsubsection{Test cases}
-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.''
-
-\subsubsection{Publicity}
-Help spread the word ... recommend it to others, write articles about it, etc.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Acknowledgements}
-\label{intro.acknowledgments}
-    
-Cheetah is one of several templating frameworks that grew out of a `templates'
-thread on the Webware For Python email list.  Tavis Rudd, Mike Orr, Chuck
-Esterbrook and Ian Bicking are the core developers.
-
-We'd like to thank the following people for contributing valuable advice, code
-and encouragement: Geoff Talvola, Jeff Johnson, Graham Dumpleton, Clark C.
-Evans, Craig Kattner, Franz Geiger, Geir Magnusson, Tom Schwaller, Rober Kuzelj,
-Jay Love, Terrel Shumway, Sasa Zivkov, Arkaitz Bitorika, Jeremiah Bellomy,
-Baruch Even, Paul Boddie, Stephan Diehl, Chui Tey, Michael Halle, Edmund Lian
-and Aaron Held.
-    
-The Velocity, WebMacro and Smarty projects provided inspiration and design
-ideas.  Cheetah has benefitted from the creativity and energy of their
-developers. Thank you.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{License}
-\label{intro.license}
-
-\subsubsection{The gist}
-Cheetah is open source, but products developed with Cheetah or derived
-from Cheetah may be open source or closed source.
-
-\subsubsection{Legal terms}
-Copyright \copyright 2001, The Cheetah Development Team: Tavis Rudd, Mike Orr,
-Ian Bicking, Chuck Esterbrook.
-
-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.
-
-% Local Variables:
-% TeX-master: "users_guide"
-% End:      
diff --git a/docs/users_guide_src/language.tex b/docs/users_guide_src/language.tex
deleted file mode 100644
index 4c7aea6..0000000
--- a/docs/users_guide_src/language.tex
+++ /dev/null
@@ -1,667 +0,0 @@
-\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. Cheetah
-uses a Python-like syntax inside directive tags and understands any valid
-Python expression.  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.
-
-Cheetah does not use HTML/XML-style tags like some other template languages 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
-
-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.
-
-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>
-#elif $country in ('Argentina', 'Uruguay', 'Brazil', 'Peru', 'Colombia',
-    'Costa Rica', 'Venezuela', 'Mexico')
-<h1>hola, senorita!</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 output from simple expressions: \code{\$placeholders}
-     \item output from more complex expressions: \code{\#echo} \ldots
-     \item silencing output from expressions: \code{\#silent} \ldots
-     \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{\#cache}
-     \item set the output filter: \code{\#filter} \ldots
-     \end{enumerate}
-          
-\item Importing Python modules and objects: \code{\#import} \ldots,
-     \code{\#from} \ldots
-
-\item Inheritance 
-     \begin{enumerate}
-     \item set the base classes 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}
-     \item define class 'settings': \code{\#settings} \ldots \code{\#end settings}
-     \end{enumerate}
-
-\item Run-time assignment
-     \begin{enumerate}
-     \item local vars: \code{\#set} \ldots
-     \item global vars: \code{\#set global} \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 sets a default exception
-          catcher/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}
-\end{enumerate}
-
-Cheetah also supports two PSP (Python Server Pages) style tags as escapes to
-pure Python code. These are not part of Cheetah's core language, but are
-included to facilitate migration from PSP-style markup languages to Cheetah.
-These tags may not be used inside other Cheetah tags.
-\begin{enumerate}
-\item evalute expression and print the output: \code{<\%=} \ldots \code{\%>} 
-\item execute code and discard output: \code{<\%} \ldots \code{\%>}
-\end{enumerate}
-
-The use of all these directives will be covered in the next few 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{\$} or enclosed in \code{\$\{\}}.
-     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.  Cheetah also allows you
-     to enclose the placeholder in \verb+$()+ or \verb+$[]+, although this may
-     make it harder for the maintainer to see where the placeholder begins and
-     ends:
-\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 delimeters to anything they
-     want via the \code{\#compiler} directive.
-
-\item To reiterate Python's rules, placeholders consist of one or more
-     components separated by periods.  Each component must start with a letter
-     or an underCheetah Developers' Guidescore, and the subsequent characters must be letters, digits or
-     underscores.  Any component may be followed by argument sets enclosed in
-     \verb+()+ and/or key/subscript arguments in \verb+[]$+.
-
-\item Components 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.  Note that you don't need
-     the \code{\$} prefix in this case since filter arguments are not ordinary
-     method arguments, and omiting the \code{\$} reminds you of this fact.
-     However, you may use \code{\$} anyway if you wish.
-
-\item EXCEPTION: You must {\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.
-
-\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.  One is {\em placeholder
-position}, which means interspersed in ordinary text.  The others are expression
-position and LVALUE position.
-
-{\em Expression position} means inside a Cheetah expression, which is the same
-as a Python expression.  The placeholder names a searchList or other variable
-which is 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 which 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.  Placeholder 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}
-
-If you value simplicity, just follow the \code{\$} rules above and skip this
-section.  If you don't like that many dollar signs, read on.
-
-\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 placeholder 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, {\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.  The bare variable name happens to be what you get if you remove the
-delimeters from the placeholder, so this works.
-
-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.
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\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 variable
-names 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 object and a dictionary, (b) what functions
-and methods are, and (c) what 'self' is. A side benefit is that NameMapper
-syntax insulates the code in Cheetah templates from changes in the implementation
-of the Python data structures behind them.
-
-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've been hired as a consultant to design and implement a customer information
-system for your client. The class you create has 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 working for your client want to use information from your system
-on the client's website --AND-- they want to maintain the display code
-themselves.
-
-Using PSP, the display code for the website would look something like this,
-assuming your servlet is a subclass of your customer class:
-
-
-\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
-   --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{\$customer(\$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 using 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 are also valid Python components.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\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,
-and Cheetah can't tell.  So Cheetah follows the principle of least surprise and
-doesn't autocall instances.  If you {\em do} want to call the instance, do
-{\em \$myInstance.\_\_call\_\_}.  If that's too inconvenient/ugly for you,
-rename the method to \code{.\_\_str\_\_}, and it will be invoked any time 
-\code{\$myInstance} is used as a placeholder.  Note, however, that if
-\code{\$myInstance} is in an expression rather than being a placeholder,
-\code{.\_\_str\_\_} will not be invoked.  Of course, you can always use
-\code{()} to force the calling in any case: \code{\$myInstance()}.
-
-\item Autocalling can be disabled via Cheetah's 'useAutocalling' compiler
-setting.
-\end{itemize}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsubsection{Underscored attributes}
-\label{language.namemapper.underscore}
-
-If a 'name' in Cheetah doesn't correspond to a valid object attribute name in
-Python, but there is an attribute in the form '\_name', NameMapper will return
-the underscored attribute.
-
-This removes the need to change all placeholders like \code{\$clients.list} to
-\code{\$clients.\_list} when the 'list' attribute of 'clients' is changed to or
-from an underscored attribute.
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Namespace cascading and the searchList}
-\label{language.searchList}
-
-When Cheetah maps a variable name in a template to a Python value, it searches
-through a list of namespaces known as the Template object's \code{searchList}.
-By default, the only namespace in the \code{searchList} is the template object
-itself. This means that its attributes or methods can be accessed in templates
-via \code{\$placeholders} without needing to include 'self' in the reference as
-you do in Python. 
-
-The looked-up values are called {\bf placeholder values}, because they are what
-a placeholder evaluates to.  If the value comes from the searchList, it's called
-a \code{searchList} variable.
-
-The \code{searchList} can be used to override or supplement the variables in the
-template object's namespace without needing to create a subclass.  When Cheetah
-fills in \code{\$myVar} it searches sequentially through the searchList until it
-finds a value for \code{myVar}.  Thus, if three namespaces are loaded and two of
-them contain a value for \code{\$myVar}, the value for \code{myVar} from the
-namespace that is closest to the start of the searchList will be returned.
-
-If you add a Python object to the searchList, its attributes and methods will
-be accessible as \$placeholder names.  If the object is a dictionary, its keys
-are accessible as if they were attributes.  For example, \code{myObject}
-contains \code{myAttrib} and \code{myMethod}.  If \code{myObject} is added to
-the searchList, \code{\$myAttrib} and \code{\$myMethod} can be used as
-placeholder names.
-
-The\code{\_\_init\_\_} method of the \code{Template} class, and the subclasses
-generated by the Cheetah compiler, accept a list of namespaces that will be
-added to the start of the \code{searchList}.  Extra namespaces can be added to
-the end of the searchList at at any time using the
-\code{.addToSearchList()} method, and to the beginning by
-\code{.prependToSearchList()}, both defined in \code{Template}.
-
-Note that if you place an object on the searchList, you cannot look up that
-object itself by name.  You can only look up the attributes/keys {\em inside}
-that object.
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Local variables}
-\label{language.localVariables}
-
-The following names are accessible by \code{\$placeholders}, even though they
-are not in the searchList:  
-
-\begin{enumerate}
-\item \code{\#set} variables and \code{\#set global} variables.
-\item \code{\#for} loop counters.
-\item the template object's \code{self} (i.e., \code{\$self.attrib1}).
-\item Python's built-in functions and objects (everything in module
-     \code{\_\_builtin\_\_}, \code{None}, etc).
-\end{enumerate}
-
-These are in fact local variables in the generated class method.  The compiler
-can tell by context which \code{\$placeholders} should be looked up in the
-searchList and which are local variables, so it generates the appropriate
-Python lookup code for either case.  The compiler can also tell when to do
-NameMapper lookup on a local variable; e.g.:
-\begin{verbatim}
-#for $client in $clients 
-$client.name
-#end for
-\end{verbatim}
-The compiler knows that \code{\$client} is a local variable because it's a
-\code{\#for} loop counter.  The compiler also knows it has to do NameMapper
-lookup on the \code{.name} suffix in case it's a dictionary key or 
-autocallable.  So the compiler generates the appropriate Python code.
-
-If you want to make absolutely sure that you are accessing an attribute or
-method of the template object, include 'self' in the reference:
-\code{\$self.attrib1} instead of \code{\$attrib1}.  (\code{\$self.attrib1}, it's
-a local variable lookup followed by universal dotted notation.  But for
-\code{\$attrib1}, Cheetah consults the searchList.  Since \code{self} is the
-{\em last} element in the searchList, any other 'attrib1' in the searchList
-will override that one.
-
-{\em Note:} you cannot override builtin variables and functions; that is, you
-cannot access a searchList value of the same name.  This sometimes causes
-surprises when Python adds a new builtin to the language.  For instance, Python
-2.2 added a new builtin \code{property}.  This tripped up a user with a 
-\code{\$property} variable in his application.  Not only did Cheetah look up
-the wrong variable, but it raised an error because the \code{property} function
-requires arguments.  Since we do not know what builtins might be added to future
-versions of Python, the best one can do is to be aware of the situation and to
-be on the lookout for new builtins that might cause a name conflict in your
-templates.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\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.
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{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.
-
-Whitespace handling around comment directives is discussed in the next
-chapter.
-
-
-
-% Local Variables:
-% TeX-master: "users_guide"
-% End:      
-
-% # vim: expandtab
diff --git a/docs/users_guide_src/libraries.tex b/docs/users_guide_src/libraries.tex
deleted file mode 100644
index 1fd1a78..0000000
--- a/docs/users_guide_src/libraries.tex
+++ /dev/null
@@ -1,317 +0,0 @@
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\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.
-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 mixin class that provides facilities for managing application settings.  
-Class \code{Cheetah.SettingsManager.SettingsManager} 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.  For more information, see section
-\ref{inheritanceEtc.settings} and the class source.
-
-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. If there is sufficient interest in \code{SettingsManager}, we will
-release it as a standalone module.
-
-Both the \code{\#settings} and \code{\#compiler-settings} directives use
-\code{SettingsManager}, although they maintain two separate lists of settings.
-
-
-% @@MO: deleted, redundant.
-%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}
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\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 will be very 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}
-$*docType
-<HTML>
-####################
-#block headerComment
-<!-- This document was autogenerated by Cheetah. Don't 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
-
--->
-
-#end block 
-#####################
-
-#################
-#block headTag
-<HEAD>
-<TITLE>$*title</TITLE>
-$*metaTags()
-$*stylesheetTags()
-$*javascriptTags()
-</HEAD>
-#end block 
-#################
-
-
-#################
-#block bodyTag
-$bodyTag()
-#end block 
-#################
-
-#block writeBody
-This skeleton page has no flesh. Its body needs to be implemented.
-#end block 
-
-</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?
-
-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}
-
-See the file \code{examples/webware\_examples/cheetahSite/SiteTemplate.tmpl}
-for an extended example of how \code{SkeletonPage} can be used.
-
-
-
-% Local Variables:
-% TeX-master: "users_guide"
-% End:      
diff --git a/docs/users_guide_src/links.tex b/docs/users_guide_src/links.tex
deleted file mode 100644
index 1ec2f6c..0000000
--- a/docs/users_guide_src/links.tex
+++ /dev/null
@@ -1,112 +0,0 @@
-\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_src/moreverb.sty b/docs/users_guide_src/moreverb.sty
deleted file mode 100755
index 92e34bb..0000000
--- a/docs/users_guide_src/moreverb.sty
+++ /dev/null
@@ -1,197 +0,0 @@
-%%% moreverb.sty

-%%% AJCD 20 Sep 91

-%%% adds various verbatim environments using Rainer Sch\"opf's new verbatim

-%%% environment.

-

-

-%%% Marginal hacks (RF) to work `properly' with 2e

-\def\filedate{1994/12/13}

-\def\fileversion{v2.0}

-%

-\NeedsTeXFormat{LaTeX2e}

-\ProvidesPackage{moreverb}

-     [\filedate\space \fileversion\space

-           LaTeX2e package for `more' verbatim enhancements]

-\typeout{Package: `moreverb'

-   \fileversion \space <\filedate>  (RF, after AJCD and RmS)}

-%\typeout{English Documentation \@spaces <\docdate>} % oh no there isn't

-

-%%% load verbatim style if not already loaded.

-\@ifundefined{verbatim@processline}{\RequirePackage{verbatim}}{}

-

-%%% verbatimwrite writes all text in its body to a file, the name of which it

-%%% is given as an argument. Written by RmS.

-\newwrite \verbatim@out

-\def\verbatimwrite#1{%

-  \@bsphack

-  \immediate\openout \verbatim@out #1

-  \let\do\@makeother\dospecials

-  \catcode`\^^M\active \catcode`\^^I=12

-  \def\verbatim@processline{%

-    \immediate\write\verbatim@out

-      {\the\verbatim@line}}%

-  \verbatim@start}

-

-\def\endverbatimwrite{%

-  \immediate\closeout\verbatim@out

-  \@esphack}

-

-%%% Auxiliary macros and counters for expanding tabs. Use by listing and

-%%% verbatimtab environments.

-\newcount\tab@position \newcount\tab@size

-\newcount\verbatimtabsize \verbatimtabsize=8

-\def\@xobeytab{\leavevmode\penalty\@M

-   {\loop\ \global\advance\tab@position-1 \ifnum\tab@position>0 \repeat}}

-\begingroup

-  \catcode`\^^I=\active

-  \gdef\@vobeytabs{\catcode`\^^I\active\let^^I\@xobeytab}%

-\endgroup

-\def\verbatim@tabexpand#1{%

-  \ifx#1\@nil \let\next\par \else

-    \ifx#1\@xobeysp \@xobeysp\advance\tab@position-1 \else

-    \ifx#1\@xobeytab \@xobeytab\else

-       #1\advance\tab@position-1

-    \fi\fi

-    \ifnum\tab@position=0 \tab@position\tab@size \fi

-    \let\next\verbatim@tabexpand

-  \fi\next

-}

-

-%%% listing defines a verbatim environment with numbered lines; it takes an

-%%% optional argument specifying the number of lines between numbered

-%%% lines, and a mandatory argument specifying the starting line. listingcont

-%%% continues from the place where listing left off.

-%%% The style in which the label is set can be altered by re-defining

-%%% \listinglabel. * versions are provided.

-\newcount\listing@line \listing@line=1 \newcount\listing@step \listing@step=1

-% Adding an \hbox in front of the line causes a line break, so I go

-% through this rigmarole to get the lines aligned nicely. I probably

-% missed some obvious reason why \hboxes don't work.

-\def\listinglabel#1{\rlap{\small\rm\the#1}\hskip2.5em}

-\def\thelisting@line{%

-  \setbox0\hbox{\listinglabel\listing@line}%

-  \@tempcnta=\listing@line

-  \divide\@tempcnta\listing@step \multiply\@tempcnta\listing@step

-  \ifnum\listing@line=1 \unhbox0

-  \else \ifnum\@tempcnta=\listing@line \unhbox0

-  \else \hskip\wd0

-  \fi\fi}

-\def\listing{\@ifnextchar[{\@listing}{\@listing[1]}}

-\def\@listing[#1]#2{%

-  \global\listing@line=#2\global\listing@step=#1\listingcont}

-\def\listingcont{%

-  \tab@size=\verbatimtabsize

-  \def\verbatim@processline{\tab@position\tab@size

-    \thelisting@line \global\advance\listing@line1

-    \expandafter\verbatim@tabexpand\the\verbatim@line\@nil}%

-  \@verbatim\frenchspacing\@vobeyspaces\@vobeytabs\verbatim@start}

-\let\endlisting=\endtrivlist

-\let\endlistingcont=\endtrivlist

-\@namedef{listing*}{\@ifnextchar[{\@listingstar}{\@listingstar[1]}}

-\def\@listingstar[#1]#2{%

-  \global\listing@line=#2\global\listing@step=#1\relax

-  \csname listingcont*\endcsname}

-\@namedef{listingcont*}{%

-  \def\verbatim@processline{%

-    \thelisting@line \global\advance\listing@line1

-    \the\verbatim@line\par}%

-  \@verbatim\verbatim@start}

-\expandafter\let\csname endlisting*\endcsname =\endtrivlist

-\expandafter\let\csname endlistingcont*\endcsname =\endtrivlist

-

-%%% file input version of listing

-\def\listinginput{%

-   \@ifnextchar[{\@listinginput}{\@listinginput[1]}}

-{\catcode`\~=\active \lccode`\~=`\^^M \lccode`\N=`\N

- \lowercase{%

-  \gdef\@listinginput[#1]#2#3{\begingroup

-     \global\listing@line=#2\global\listing@step=#1

-     \tab@size=\verbatimtabsize

-     \def\verbatim@processline{\tab@position\tab@size

-        \thelisting@line \global\advance\listing@line1

-        \expandafter\verbatim@tabexpand\the\verbatim@line\@nil}%

-     \@verbatim\frenchspacing\@vobeyspaces\@vobeytabs

-     \def\verbatim@addtoline##1~{%

-        \verbatim@line\expandafter{\the\verbatim@line##1}}%

-     \openin\verbtab@in=#3

-     \ifeof\verbtab@in\typeout{No file #3.}\else

-       \verbtab@oktrue

-       \loop

-          \read\verbtab@in to \verbtab@line

-          \ifeof\verbtab@in\verbtab@okfalse\else

-             \expandafter\verbatim@addtoline\verbtab@line

-             \verbatim@processline

-             \verbatim@startline

-          \fi

-       \ifverbtab@ok\repeat

-       \closein\verbtab@in\fi

-     \endtrivlist\endgroup\@doendpe}}}

-

-%%% verbatimcmd is a verbatim environment with the exception of the escape and

-%%% grouping characters \, {, }.

-\def\verbatimcmd{%

-  \@verbatim \catcode`\\=0 \catcode`\{=1 \catcode`\}=2

-  \frenchspacing\@vobeyspaces\verbatim@start

-}

-\def\endverbatimcmd{%

-  \let\par\relax

-  \def\verbatim@{\endtrivlist\endgroup}%

-  \begingroup}

-

-%%% boxedverbatim produces a verbatim environment in a framed box.

-%%% written by Victor Eijkhout

-\def\boxedverbatim{%

-  % redefine `processline' to produce only a line as wide

-  % as the natural width of the line

-  \def\verbatim@processline{%

-    {\setbox0=\hbox{\the\verbatim@line}%

-    \hsize=\wd0 \the\verbatim@line\par}}%

-  % save the verbatim code in a box

-  \setbox0=\vbox\bgroup \verbatim

-}

-\def\endboxedverbatim{%

-  \endverbatim

-  \egroup % close the box and `fbox' it

-  \fbox{\box0}% <<<=== change here for centering,...

-}

-

-%%% verbatimtab is a verbatim environment which expands tab characters; it

-%%% takes an optional argument specifying the width of tab stops

-\def\verbatimtab{\futurelet\next\@verbatimtab}

-\def\@verbatimtab{\if\next[ \let\next\@@verbatimtab\else

-                     \def\next{\@@verbatimtab[\the\verbatimtabsize]}\fi\next}

-\def\@@verbatimtab[#1]{%

-  \do@verbatimtab{#1}{%

-     \@verbatim\frenchspacing\@vobeyspaces\@vobeytabs\verbatim@start}%

-}

-\def\do@verbatimtab#1#2{%

-  \tab@size=#1

-  \def\verbatim@processline{\tab@position\tab@size

-     \expandafter\verbatim@tabexpand\the\verbatim@line\@nil}#2

-}

-\let\endverbatimtab=\endtrivlist

-

-%%% file input version of verbatimtab

-\newread\verbtab@in \newif\ifverbtab@ok

-\def\verbatimtabinput{%

-   \@ifnextchar[{\@verbatimtabinput}{\@verbatimtabinput[\the\verbatimtabsize]}}

-{\catcode`\~=\active \lccode`\~=`\^^M \lccode`\N=`\N

- \lowercase{%

-  \gdef\@verbatimtabinput[#1]#2{\begingroup

-     \do@verbatimtab{#1}{%

-       \@verbatim\frenchspacing\@vobeyspaces\@vobeytabs}%

-     \def\verbatim@addtoline##1~{%

-        \verbatim@line\expandafter{\the\verbatim@line##1}}%

-     \openin\verbtab@in=#2

-     \ifeof\verbtab@in\typeout{No file #2.}\else

-       \verbtab@oktrue

-       \loop

-          \read\verbtab@in to \verbtab@line

-          \ifeof\verbtab@in\verbtab@okfalse\else

-             \expandafter\verbatim@addtoline\verbtab@line

-             \verbatim@processline

-             \verbatim@startline

-          \fi

-       \ifverbtab@ok\repeat

-       \closein\verbtab@in\fi

-     \endtrivlist\endgroup\@doendpe}}}

diff --git a/docs/users_guide_src/output.tex b/docs/users_guide_src/output.tex
deleted file mode 100644
index a645c00..0000000
--- a/docs/users_guide_src/output.tex
+++ /dev/null
@@ -1,383 +0,0 @@
-\section{Generating, Caching and Filtering Output}
-\label{output}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Output from simple expressions: placeholders}
-\label{output.placeholders}
-
-Placeholders are like 'primaries' in Python (see section 5.3 of Python's
-Language Reference for more). If you don't know what a 'primary' is, think of
-them as variables. They may refer to any Python value: strings, numbers, None,
-tuples, tuple items, tuple slices, lists, list items, list slices, dictionaries,
-dictionary values, objects, and the return values of function and method calls.
-When a template is processed each placeholder will be replaced with the string
-representation of its value.  These string representations are identical to
-those returned by Python's str() function, with the exception of \code{None}.
-\code{None} is replaced with an empty string, or in other words nothing.
-(This is with the default output filter.  You can customize the string
-representation via the \code{\#filter} directive, section \ref{output.filter}.)
-
-Cheetah finds the values for placeholders in several places.  The most obvious
-place is in the searchList.  But placeholders can also refer to local variables
-(created by \code{\#set}), global variables (created by \code{\#set global}, 
-\code{\#import}, methods of the generated class (created by 
-\code{\#def} and \code{\#block} or inherited from the \code{Template} class),
-attributes of the generated class (created by \code{\#attr} or inherited), or
-Python builtins like \code{\$range} or \code{\$len}.  
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Output from complex expressions: \#echo}
-\label{output.echo}
-
-The \code{\#echo} directive is used to echo the output from expressions that
-can't be written as simple \$placeholders.  It serves the same purpose as ASP's
-$<$\%=EXPR\%$>$ tag.
-
-\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}
-
-In this example, the second \code{\#} serves to end the \code{\#echo} directive,
-allowing plain text to follow it.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Executing expressions without output: \#silent}
-\label{output.silent}
-
-\code{\#silent} is the opposite of \code{\#echo}.  It executes an expression
-but discards the output.  It's similar to ASP's $<$\% EXPR \%$>$ tag.
-
-\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{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}
-
-The \code{\#cache \ldots \#end 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.  
-Placeholders inside the region lose their identity and are not reevaluated
-until the cache item is refreshed.  As a corollary, placeholders inside a
-\code{\#cache} region cannot use the \code{\$*var} or \code{\$*<interval>*var}
-form because they cannot be cached under a different policy than the region
-they're in.
-
-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 not supported.  It may work, but it may not.
-
-\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}
-
-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 what a font is.  
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{\#include}
-\label{output.include}
-
-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 simple 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}
-
-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{Ouput Filtering and \#filter}
-\label{output.filter}
-
-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. 
-
-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.  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.
-
-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:      
-
diff --git a/docs/users_guide_src/parserInstructions.tex b/docs/users_guide_src/parserInstructions.tex
deleted file mode 100644
index 3a0e2ac..0000000
--- a/docs/users_guide_src/parserInstructions.tex
+++ /dev/null
@@ -1,97 +0,0 @@
-\section{Instructions to the Parser/Compiler}
-\label{parserInstructions}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{\#breakpoint}
-\label{parserInstructions.breakpoint}
-
-\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}
-
-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.
-
-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_src/tipsAndTricks.tex b/docs/users_guide_src/tipsAndTricks.tex
deleted file mode 100644
index 3d4562f..0000000
--- a/docs/users_guide_src/tipsAndTricks.tex
+++ /dev/null
@@ -1,226 +0,0 @@
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Tips, Tricks and Troubleshooting}
-\label{tips}
-
-This chapter contains short stuff that doesn't fit anywhere else.
-
-Remember to look at the wiki periodically for the most recent tips contributed
-by users.  The mailing list also reveals tips as somebody posts a problem
-they're having and others troubleshoot it.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\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 mixin classes.
-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).
-
-To look up a variable in the searchList from a Python method:
-\begin{verbatim}
-self.getVar('theVariable')
-self.getVar('theVariable', None)
-self.getVar('theVariable', myDefault)
-\end{verbatim}
-This is the equivalent to \code{\$theVariable} in the template.  \code{getVar}
-returns the second argument (\code{None} or \code{myDefault} if the variable is
-missing; or, if there is no second argument, it raises raises
-\code{NameMapper.NotFound}.  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 \$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} as one of the
-elements in the searchList.  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.
-
-% @@ MO: If getVar() is called from Python, does errorCatcher apply?
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\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.
-
-In Python >= 2.2, you can simply do:
-\begin{verbatim}
-from Cheetah.Template import Template
-class MyClass(Template):
-	def awake(self, trans):
-		super(MyClass, self).awake(trans)
-		... add your own great and exciting features here ...
-\end{verbatim}
-For Python < 2.2, you have to explicitly name the superclass and call the
-method as an unbound method:
-\begin{verbatim}
-from Cheetah.Template import Template
-from Cheetah.Servlet import Servlet
-class MyClass(Template):
-	def awake(self, trans):
-		Servlet.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 in older Python, 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 inherited by \code{Template} objects
-and attributes.  Some of them exist for you to call, others are mainly used by
-Cheetah but you can call them if you wish, and others are only for internal use
-by Cheetah.  Do not use these method names in mixin classes (\code{\#extends},
-section \ref{inheritanceEtc.extends}) unless you intend to override the
-standard method.  
-
-[Method list not written yet.]
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\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 compiled into Python local
-variables, which have by far the fastest lookup time f any Python or Cheetah
-variables.
-
-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 ecape
-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.
-
-\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.
-
-{\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.
-
-
-% Local Variables:
-% TeX-master: "users_guide"
-% End:      
diff --git a/docs/users_guide_src/users_guide.tex b/docs/users_guide_src/users_guide.tex
deleted file mode 100644
index 030bee0..0000000
--- a/docs/users_guide_src/users_guide.tex
+++ /dev/null
@@ -1,48 +0,0 @@
-\documentclass{howto}
-\usepackage{moreverb}                   %% Verbatim Code Listings
-
-\title{Cheetah Users' Guide}
-\release{0.9.14b1}
-
-\author{Edited by Mike Orr with assistance from Tavis Rudd}
-\authoraddress{\email{cheetahtemplate-discuss@lists.sourceforge.net}}
-
-\begin{document}
-\maketitle
-
-% @@MO: Picture of cheetah from web site.
-
-\tableofcontents
-
-\copyright{Copyright 2001, The Cheetah Development Team.
-      This document may be copied and modified under the terms of the
-      {\bf Open Publication License} \url{http://www.opencontent.org/openpub/} }
-
-    %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-    \include{introduction}
-    \include{gettingStarted}
-    \include{howItWorks}
-    \include{language}
-    \include{comments}
-    \include{output}
-    \include{inheritanceEtc}
-    \include{flowControl}
-    \include{errorHandling}
-    \include{parserInstructions}
-    \include{tipsAndTricks}
-    \include{webware}
-    \include{nonHTML}
-    \include{libraries}
-    \include{editors}
-
-    %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-    \appendix
-    \include{links}
-    \include{examples}
-    \include{comparisons}
-
-\end{document}
-
-% Local Variables:
-% TeX-master: "users_guide"
-% End:      
diff --git a/docs/users_guide_src/webware.tex b/docs/users_guide_src/webware.tex
deleted file mode 100644
index 85d2dcd..0000000
--- a/docs/users_guide_src/webware.tex
+++ /dev/null
@@ -1,556 +0,0 @@
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\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 both to the official version of Webware and the
-WebwareExperimental implementation at 
-\url{http://sourceforge.net/projects/expwebware/}, except where noted.  The
-differences between the two are mainly in their internal structure and
-configuration file, not in the API they present to servlets.  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.", cheetah-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.
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\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 greatly 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{.field} method into a local variable for
-convenience:
-\begin{verbatim}
-#set $field = $request.field
-$field.myField
-$field('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.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{.cgiImport()}
-\label{webware.cgiImport}
-
-From the method docstring:
-
-\begin{verbatim}
-    def cgiImport(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 $cgiImport(['choice'])
-    $choice
-
-    dic = self.cgiImport(['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 $cgiImport(['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 $cgiImport([], ['days'])
-    The days you chose are: #slurp
-    #for $day in $days
-    $day #slurp
-    #end for
-
-    dic = self.cgiImport([], ['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.cgiImport([], ['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 $cgiImport(['name', 'height:int'])
-    $name is $height cm tall.
-    #if $height >= 300
-    Wow, you're tall!
-    #else
-    Pshaw, you're short.
-    #end if
-
-    dic = self.cgiImport(['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{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.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{HTML without Webware}
-\label{webware.not}
-
-%% @@MSO: LG Mirrors example.
-
-% Local Variables:
-% TeX-master: "users_guide"
-% End:      
-%# vim: sw=4 ts=4 expandtab