Finished this round of updating.

16 files changed, 658 insertions, 392 deletions

diff --git a/docs/users_guide_src/comments.tex b/docs/users_guide_src/comments.tex
index 5a73531..725a656 100644
--- a/docs/users_guide_src/comments.tex
+++ b/docs/users_guide_src/comments.tex
@@ -103,6 +103,9 @@ 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}
diff --git a/docs/users_guide_src/comparisons.tex b/docs/users_guide_src/comparisons.tex
index f2c4f88..3a4d302 100644
--- a/docs/users_guide_src/comparisons.tex
+++ b/docs/users_guide_src/comparisons.tex
@@ -1,9 +1,9 @@
-\section{Cheetah vs. [fill in the blank]}
+\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
+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}.
 
@@ -12,22 +12,22 @@ Velocity and other languages at
 \label{comparisons.unique}
 
 \begin{itemize}
-\item The {\bf block framework} (section {inheritanceEtc.block})
+\item The {\bf block framework} (section \ref{inheritanceEtc.block})
 \item Cheetah's powerful yet simple {\bf caching framework} (section
-     \ref{TDL.placeholders.caching})
+     \ref{output.caching})
 \item Cheetah's {\bf Unified Dotted Notation} and {\bf autocalling}
-     (sections \ref{TDL.placeholders.unifiedDottedNotation} and
-     \ref{TDL.placeholders.autocalling})
-\item Cheetah's searchList (section \ref{TDL.placeholders.searchList})
+     (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{directives.raw})
-\item Cheetah's \code{\#slurp} directive (section \ref{directives.slurp})
-\item Cheetah's tight integration with {\bf Webware for Python} (section
+\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{webware.inheritance.skeletonPage})
+     \ref{libraries.templates.skeletonPage})
 \item Cheetah's ability to mix PSP-style code with Cheetah
-     Language syntax (section \ref{customizing.plugins}) 
+     Language syntax (section \ref{tips.ASP}) 
      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.
@@ -44,10 +44,9 @@ Velocity and other languages at
 For a basic introduction to Velocity, visit
 \url{http://jakarta.apache.org/velocity}.
 
-
-Velocity is older, has a larger user base, and has better examples and
-docs at the moment. Cheetah, however, has a number of advantages over
-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
@@ -190,29 +189,88 @@ Here are some examples of syntax differences between DTML and Cheetah:
 
 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 resposible for ensuring \code{\$files} returned a 
+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
+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}
 
-[This section is under construction.]
-
 \begin{description}
 \item[Webware's PSP Component] -- \url{http://webware.sourceforge.net/Webware/PSP/Docs/}
-\item[PHP Home Page] -- \url{http://www.php.net/}
 \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/}
@@ -244,7 +302,6 @@ Compare this with PSP:
 </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
index 30ca7b7..84c8f03 100644
--- a/docs/users_guide_src/editors.tex
+++ b/docs/users_guide_src/editors.tex
@@ -1,9 +1,34 @@
 \section{Visual Editors}
 \label{visualEditors}
 
-This chapter will be about maintaining Cheetah templates with visual editors,
-and the tradeoffs between making it text-editor friendly and visual-editor
-friendly.
+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"
diff --git a/docs/users_guide_src/errorHandling.tex b/docs/users_guide_src/errorHandling.tex
index b3d05af..c88f477 100644
--- a/docs/users_guide_src/errorHandling.tex
+++ b/docs/users_guide_src/errorHandling.tex
@@ -1,8 +1,8 @@
 \section{Error Handling}
 \label{errorHandling}
 
-There are two ways to handle run-time errors (aka exceptions) in Cheetah.  The
-first is with the Cheetah directives that mirror Python's structured exception
+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.
 
@@ -50,26 +50,23 @@ following Cheetah code demonstrates their use:
 #finally
   $cleanup()
 #end try
-
 \end{verbatim}    
 
-The indentation in these examples is for clarity purposes only.  In a
-production template, you wouldn't indent unless you wanted the indentation to
-show up in the output.
+Like Python, \code{\#except} and \code{\#finally} cannot appear in the same
+try-block, but can appear in nested try-blocks.
 
-%% @@MSO: If we add #sed or #slurp, mention it here.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{ErrorCatcher}
 \label{errorHandling.errorCatcher}
 
-\code{ErrorCatcher} is a debugging tool that catchs 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.
+\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:
@@ -103,7 +100,7 @@ Here's a good placeholder: Here I am!
 Here's bad placeholder: $iDontExist
 \end{verbatim}
 
-The baseclass shown above is also accessible under the alias
+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
@@ -121,14 +118,16 @@ 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.
+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
index b539c38..75fa78a 100644
--- a/docs/users_guide_src/examples.tex
+++ b/docs/users_guide_src/examples.tex
@@ -7,9 +7,9 @@ Cheetah can be used.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Syntax examples}
-Cheetah's \code{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
+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.
 
 
diff --git a/docs/users_guide_src/flowControl.tex b/docs/users_guide_src/flowControl.tex
index e7bd5a0..52f60ee 100644
--- a/docs/users_guide_src/flowControl.tex
+++ b/docs/users_guide_src/flowControl.tex
@@ -7,8 +7,8 @@
 \subsection{\#for ... \#end for}
 \label{flowControl.for}
 
-The \code{\#for} directive iterates through a sequence.  The syntax is very
-similar to Python.  Remember the \code{\$} before variables.
+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}
@@ -25,7 +25,7 @@ Here's a simple client listing:
 Here's how to loop through the  keys and values of a dictionary:
 \begin{verbatim}
 <PRE>
-#for $key, $value in $dict.items()
+#for $key, $value in $dict.items() # ## Or $dict.iteritems() in Python >= 2.2.
 $key: $value
 #end for
 </PRE>
@@ -42,13 +42,11 @@ $i - #end for
 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)
+#for $i in $range(15)
 $i - #slurp
 #end for
 \end{verbatim}
 
-%% @@MSO: I thought builtins require a preceding $ but it only worked without it
-
 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.
@@ -60,9 +58,10 @@ $sep$name
 #end for 
 \end{verbatim}
 
-(If you don't like that \code{\#set} variable, you can replace the
-\code{\#for} loop with this Python trick:
+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}
@@ -125,7 +124,7 @@ the computer runs out of memory.
 
 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 
+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}.
@@ -220,7 +219,7 @@ $name - #slurp
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{\#pass}
-\label{flowControl.break}
+\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
@@ -228,20 +227,17 @@ program requires no action.
 
 In this example the output list will not contain ``10 - ''. 
 \begin{verbatim}
-#if $A and $B:
+#if $A and $B
    do something
-#elif $A:
+#elif $A
   #pass
-#elif $B: 
+#elif $B
   do something
-#else:
+#else
   do something
 #end if
 \end{verbatim}
 
-%% @@ MSO: Are the colons really allowed?  We've been telling people not to use
-%% @@ colons.  In any case, Greg Czajkowski <gregczajkowski@yahoo.com> tried to
-%% @@ use colons and got an error on the #else directive but not on the others.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{\#stop}
@@ -258,27 +254,39 @@ called inside a \code{\#def} or \code{\#block}, it stops only the \code{\#def}
 or \code{\#block}.
 
 \begin{verbatim}
-the beginning
+A cat
 #if 1
-  inside the if block
+  sat on a mat
   #stop
+  watching a rat
 #end if
-the end
+in a flat.
 \end{verbatim}
 
 will print 
 \begin{verbatim}
-the beginning
-  inside the if block
+A cat
+  sat on a mat
 \end{verbatim}
 
-instead of 
+And
 \begin{verbatim}
-the beginning
-  inside the if block
-the end
+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:
diff --git a/docs/users_guide_src/gettingStarted.tex b/docs/users_guide_src/gettingStarted.tex
index 9e255a6..b79a4e0 100644
--- a/docs/users_guide_src/gettingStarted.tex
+++ b/docs/users_guide_src/gettingStarted.tex
@@ -63,11 +63,11 @@ 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 WebwareExperimentalRefactoring 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.
+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
diff --git a/docs/users_guide_src/howItWorks.tex b/docs/users_guide_src/howItWorks.tex
index e04da40..ab2c55e 100644
--- a/docs/users_guide_src/howItWorks.tex
+++ b/docs/users_guide_src/howItWorks.tex
@@ -84,7 +84,7 @@ The constructor accepts the following keyword arguments:
      must be the name of one of the filters in filtersLib module (see next 
      item).
      (You may also use the \code{\#filter} directive (section
-     \label{output.filter}) to switch filters at runtime.)
+     \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
diff --git a/docs/users_guide_src/inheritanceEtc.tex b/docs/users_guide_src/inheritanceEtc.tex
index ea0fd04..c081358 100644
--- a/docs/users_guide_src/inheritanceEtc.tex
+++ b/docs/users_guide_src/inheritanceEtc.tex
@@ -1,5 +1,5 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Imports, Inheritance, Declarations and Assignments}
+\section{Import, Inheritance, Declaration and Assignment}
 \label{inheritanceEtc}
 
 
@@ -17,11 +17,13 @@ generated Python class.
 #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} may be used in 
-\code{\$placeholders} and expressions.
+\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}
@@ -33,33 +35,62 @@ $sin(8)                       ## Raises NameMapper.NotFound error at fill time.
 \subsection{\#extends}
 \label{inheritanceEtc.extends}
 
-Normally, the generated template class is a subclass of
-\code{Cheetah.Template.Template}.  This gives it standard \code{Template}
-functionality as well as making it usable as a Webware servlet.  However,
-sometimes you want to inherit from a more general template (e.g., one
-containing your generic site framework), or from a pure Python class (so you
-can call its methods and attributes as placeholders.  The \code{\#extends}
-directive allows you to specify which parent class to inherit from.  It is
-equivalent to PSP's \code{``@page extends=''} directive. 
+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. 
 
 \begin{verbatim}
 #from Cheetah.Templates.SkeletonPage import SkeletonPage
 #extends SkeletonPage
 \end{verbatim}
 
-In the very near future, you won't need those \code{\#from ... import}
-directives because \code{\#extends} will implicitly import whatever 
-classes it needs, but for now the explicit imports are necessary.
+In the very near future, you won't need that \code{\#from ... import}
+because \code{\#extends} will implicitly import whatever 
+class it needs, but for now the explicit import is necessary.
+
+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}
 
-Three rules: (A) you may inherit from only one superclass (no multiple
-inheritance), (B) there may be at most one \code{\#extends} directive per
-template, and (C) the highest-level superclass in the chain must be
-\code{Cheetah.Template.Template}.  
+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 several pure
-Python classes too.  We'll begin with the highest-level superclass and
-end with the specific page template:
+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)
@@ -78,90 +109,54 @@ end with the specific page template:
 	#from SectionLogic import SectionLogic
 	#extends SectionLogic
 
-5.  page1Logic.py  (pure Python class with helper code for the page)
+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 for a certain page on the site)
+6.  page1.tmpl/py  (template-servlet for a certain page on the site)
         #from page1Logic import page1Logic
 	#extends page1Logic
 \end{verbatim}
 
-You may omit any files you don't need, or insert extra files as necessary, and
-of course you may name the classes anything you want.  If your highest-level
-site template (Site.tmpl/py) doesn't need a pure Python class (Site.py), it's
-even easier: just omit the \code{\#from ...  import} and \code{\#extends} lines
-in \code{Site.tmpl}, and it will automatically inherit from \code{Template}.
+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.
 
-Pure Python classes with \code{.\_\_init\_\_()} methods should call their
-parent's \code{.\_\_init\_\_()} method before doing anything else.  In Python
->= 2.2, it's easier:
-\begin{verbatim}
-# SiteLogic.py
-from Cheetah.Template import Template
-class SiteLogic(Template):
-	def __init__(self):
-		super(SiteLogic, self).__init__()
-		... everything else you want to do ...
-\end{verbatim}
-
-In older versions of Python you must do this:
-\begin{verbatim}
-# SiteLogic.py
-from Cheetah.Template import Template
-class SiteLogic(Template):
-	def __init__(self):
-		Template.__init__(self)
-		... everything else you want to do ...
-\end{verbatim}
-
-Section ?? has a function you can use to avoid hardcoding the name of the
-superclass into your \code{.\_\_init\_\_()} method.
-
-In older versions of Cheetah (until 0.9.12), you could list multiple classes
-in the \code{\#extends} directive, thus doing multiple inheritance.  This 
-feature was removed because it caused too much confusion, user errors and
-Cheetah bugs.  However, your pure Python classes {\em may} do multiple
-inheritance, as long as they properly initialize the template superclass 
-(the one leading up toward \code{Template}) if they have an
-\code{.\_\_init\_\_()} method.
-
-For Webware servlets, it's easier to omit the \code{.\_\_init\_\_()} method
-and override \code{.awake()} instead, since Webware automatically calls
-\code{.awake()} at the beginning of the request.  But you'd have to call
-the parent's \code{.awake()} in that case.  See section ??.
-
-See the next section, \code{\#implements}, for an important issue to be aware
-of when using \code{\#extends}, namely how it affects the generated class's
-main method.
+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}
 
-% @@MO: Fully describe the main methods.
-
 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
-called \code{.respond()}.  However, you can use the \code{\#implements}
-directive to change the name of that method.  You have to do this if you're
-integrating Cheetah with an existing system, and the calling routine wants to
-call another method name rather than \code{.respond()}.
+\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.
 
-EXCEPTION: if your template contains an \code{\#extends} directive but no
-\code{\#implements}, the main method is \code{.writeBody()} instead of
-\code{.respond()}.  Why?  Because that helps templates that are Webware
-servlets function correctly.
+% @@MO: "Compatibility with Webware servlets" is a lame explanation.  Elaborate.
 
-So you must think about what your main method should be called and set
-\code{\#implements} accordingly if necessary.
+\begin{verbatim}
+#implements send_output
+\end{verbatim}
 
-In any case, \code{.\/\_\_str\_\_()} is always an alias for the main method, no
+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.  But of course, in
-a Webware servlet you never use the \code{print} statement directly except for
-debugging.
+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.
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -170,7 +165,7 @@ debugging.
 
 \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 it is part of an
+Remember to preface variable names with \$ unless they're part of an
 intermediate result in a list comprehension.
 
 Here are some examples:
@@ -186,7 +181,7 @@ Here are some examples:
 \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 web browser.
+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
@@ -198,6 +193,11 @@ Cheetah!
   #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 =
@@ -209,23 +209,43 @@ included files.  Use this feature with care to prevent surprises.
 \subsection{\#attr}
 \label{inheritanceEtc.attr}
 
-The \code{\#attr} directive is used to declare new attributes of the generated Python
+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.  
+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 myAttr = 1234
-#attr myAttr2 = 'a string'
+#attr title = "Rob Roy"
+#attr author = "Sir Walter Scott"
+#attr version = 123.4
 \end{verbatim}
 
+This template or any child template can output the value thus:
+\begin{verbatim}
+$title, by $author, version $version
+\end{verbatim}
+
+If you have a library of templates derived from etexts
+(\url{http://www.gutenberg.org/}), you can extract the titles and authors
+and put them in a database (assuming the templates have been compiled into
+.py template modules):
+
+\begin{verbatim}
+import glob
+
+\end{verbatim}
+
+% @@MO: Finish this example.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{\#def}
 \label{inheritanceEtc.def}
 
-The \code{\#def} directive is used to declare new methods of the generated Python
-class.  It is roughly analogous to Python's \code{def} statement.  Any Cheetah
-code in the body of the \code{\#def} will be processed.  
+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()
@@ -248,8 +268,8 @@ $a $b $c(123)
 $myMeth
 \end{verbatim}
 
-Methods can accept arguments, and have defaults for those arguments.  Always use the 
-\code{\$} before variable names:
+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 
@@ -267,34 +287,48 @@ 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.
+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'
+#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 sections of your template
-that can be selectively reimplemented by subclasses of the template.  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 and \#end block} tags removed. 
 
-To reimplement the block, use the \code{\#def} directive.  The magical effect is that it
-goes back and changes the output text {\em at the point the original block was
-defined} rather than at the location of the reimplementation.
+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] 
@@ -310,6 +344,8 @@ $getFoo()
 #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}
@@ -331,17 +367,9 @@ 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.  So \code{\#block} creates a method as well as
-defining a block, and you may call this method using a placeholder if you want
-its output to appear in other locations too.
+that's what Cheetah does.  Which means you can use \code{\$theBlockName}
+later in the template to output the block content again.
 
-Sometimes Cheetahites use the term "block" to refer to any multiline directive
-(e.g., \code{\#for ... \#end for}).  Thus, the terms "for-blocks", "if-blocks",
-etc.  These have nothing to do with the blocks described in this section, which
-are methods created by the \code{\#block} directive.  It's just a coincidence
-that the English language uses the same term for both things.  (Did you know 
-that "run" has over fifty meanings in the dictionary?  And "take" has
-seventy-three.  That's not counting phrases like "take off" and "run-in".)
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -349,9 +377,34 @@ seventy-three.  That's not counting phrases like "take off" and "run-in".)
 \label{inheritanceEtc.settings}
 
 The \code{\#settings} directive works in tandem with Cheetah's
-\code{SettingsManager} system to provide yet another way to set values for
-\code{\#placeholders} to find.  It is best understood by reading the comments in
-\code{\#SettingsManager.py} in conjunction with this documentation.
+{\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
@@ -368,7 +421,7 @@ automatically converts numeric values to numbers, 'None' to None, and 'true' and
 
 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
-\code{\$placeholders}, the (\code{\#settings} directive can be convenient
+\$placeholders, the (\code{\#settings} directive can be convenient
 alternative to \code{\#attr} and \code{\#def}:
 
 \begin{verbatim}
@@ -423,6 +476,10 @@ SubSection2 = {
 $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
index 4328715..29c0ddf 100644
--- a/docs/users_guide_src/introduction.tex
+++ b/docs/users_guide_src/introduction.tex
@@ -26,7 +26,7 @@ Cheetah:
 \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-orientated interface to
+\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.
@@ -111,7 +111,7 @@ Cheetah's design was guided by these principles:
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Give me an example!}
-\label{intro.whatIs}
+\label{intro.example}
 
 Here's a very simple example that illustrates some of Cheetah's basic syntax:
 
diff --git a/docs/users_guide_src/language.tex b/docs/users_guide_src/language.tex
index 41d2187..163e468 100644
--- a/docs/users_guide_src/language.tex
+++ b/docs/users_guide_src/language.tex
@@ -44,6 +44,25 @@ Templates or PHP:
 Placeholders and directives can be escaped by putting a backslash before them.
 \code{\\\$var} and \code{\\\#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 (\code{\\}) 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.
+
+% @@MO: I don't know how to put a literal [ inside \code{} without making
+% LaTeX puke.  
+%However, if there's an unclosed \code{\\(},
+%\code{\\[} or \code{\{} 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}
@@ -185,10 +204,10 @@ The use of all these directives will be covered in the next few chapters.
      method arguments, and omiting the \code{\$} reminds you of this fact.
      However, you may use \code{\$} anyway if you wish.
 
-\item The special Python name \code{None} does not require a
-     \code{\$} prefix.  (This applies only in expressions; e.g., as a method
-     argument.  The word None in regular text is treated as regular text.)
-     But you can use \code{\$None} if you want.
+\item The special Python names \code{None}, \code{True} and \code{False} in
+     expressions do not require a \code{\$} prefix (but you can use \code{\$}
+     if you want).  \code{True} and \code{False} were added to Python 2.2.1, and
+     are simulated in Cheetah for earlier versions of Python.
 
 \item EXCEPTION: You must {\em not} use the \code{\$} prefix for intermediate
      variables in a Python list comprehensions.  This is a limitation of
@@ -218,7 +237,7 @@ These are not \$placeholders but are treated as literal text:
 $@var $^var $15.50 $$
 \end{verbatim}
 
-You can use compiler settings to change the placeholder delimeters if
+You can use compiler settings to change the placeholder delimiters if
 \code{\$}, \code{\{} and \code{\}} are not suitable.  This will be documented
 in the future.  None of the examples in this Guide use this feature.
 
@@ -325,7 +344,7 @@ foo
 """
 \end{verbatim}
 
-The \code{\#slurp} directive (section \ref{directives.slurp}) also gobbles up
+The \code{\#slurp} directive (section \ref{output.slurp}) also gobbles up
 whitespace.
 
 Whitespace handling around comment directives is discussed in section
@@ -564,7 +583,7 @@ a local variable lookup followed by universal dotted notation.  But for
 {\em last} element in the searchList, any other 'attrib1' in the searchList
 will override that one.
 
-Note that you cannot override builtin variables and functions; that is, you
+{\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 
diff --git a/docs/users_guide_src/libraries.tex b/docs/users_guide_src/libraries.tex
index 823be5d..1fd1a78 100644
--- a/docs/users_guide_src/libraries.tex
+++ b/docs/users_guide_src/libraries.tex
@@ -1,5 +1,5 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\section{Template and other libraries}
+\section{Batteries included: templates and other libraries}
 \label{libraries}
 
 Cheetah comes ``batteries included'' with libraries of templates, functions,
@@ -7,15 +7,13 @@ 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
-often can be used without Cheetah.
+can be used without Cheetah.
 
 If you develop any objects which are generally useful for Cheetah sites,
-please consider posting them on the mailing list so that 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.
-
-%% @@MSO: If sed-filters get added to Cheetah, mention them here.
+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}
@@ -43,35 +41,18 @@ 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.
 
-As of Cheetah 0.9.9a6, the set of filters is rapidly changing.  While this is
-mostly a case of more filters and more features, it is possible that some 
-filers may be removed in the future or be changed in backward-incompatible ways.
-If you are depending on a filter besides the default filter, and you can not
-risk it changing in the next version of Cheetah, make yourself a separate copy
-of it outside the Cheetah directory and use that.
-
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \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.  
-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}
+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
@@ -79,24 +60,28 @@ 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.
 
-Note that there are two Cheetah directives that deal with settings:
-\code{\#compiler-settings} affects the behaviour of Cheetah's parser and 
-compiler.  \code{\#settings} affects the behaviour of certain filters and
-error catchers (see \code{\#filter} and \code{\#errorCatcher}, and may also be
-used in your own template applications and and templates.
+Both the \code{\#settings} and \code{\#compiler-settings} directives use
+\code{SettingsManager}, although they maintain two separate lists of settings.
+
 
-By default, both kinds of settings are also visible in the searchList, so they
-may be referred to by \code{\$placeholders}.  They are at the very end of the
-searchList, so any same-name anywhere else in the searchList will override
-what the \code{\$placeholder} sees.
+% @@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}
 
-%% @@MSO: Alternate wording:
-%% 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.
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -106,7 +91,8 @@ what the \code{\$placeholder} sees.
 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.
+which is described in detail below in section 
+\ref{libraries.templates.skeletonPage}.  (Contributed by Tavis Rudd.)
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Tools}
@@ -115,55 +101,54 @@ which is described in detail below.
 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 normally.  
+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 having 
-backwards-incompatable changes made to it.  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.
+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{itemize}
-\item {\bf 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.  Contributed
-     by Mike Orr.
-\item {\bf Cheetah.Tools.RecursiveNull} -- Nothing, but in a friendly way.  Good
+\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 {\bf Cheetah.Tools.SiteHierarchy} -- Provides navigational links to this
+     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:
+     (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{\bf Cheetah.Tools.WebwareMixin} -- Additional methods for your Template object.
-     Currently there is one method, \code{.cgiImport}.  It imports the specified CGI
-     fields, cookies or session variables into a new object on the searchList, so that
-     they can be accessed by name in \$placeholders (e.g., \code{\$myField}).  This
-     method may be renamed in the next version of Cheetah, and will likely be split 
-     into two methods to handle single vs multiple values for a field.  Contributed
-     by Mike Orr.
-\end{itemize}
+
+\item 
+\end{description}
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -175,10 +160,36 @@ classes that are imported by other Cheetah components.  Many of these utils can
 be used standalone in other applications too.  
 
 Current Utils include:
-\begin{itemize}
-\item {\bf Cheetah.Utils.VerifyType} -- Functions to verify the type of a
-     user-supplied function argument.
-\end{itemize}
+\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}
@@ -186,7 +197,7 @@ Current Utils include:
 
 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 Cheetha source code:
+template class is generated from the following Cheetah source code:
 
 \begin{verbatim}
 $*docType
@@ -264,7 +275,7 @@ 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{Cheetah.Macros.HTML}.
+     \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
@@ -281,8 +292,6 @@ define in various attributes and renders them into HTML tags.
      \code{self.\_bodyTagAttribs}.
 \end{itemize}
 
-%% @@MO: (item 1 above) Macros don't exist any more.  What should this say?
-
 The class also provides some convenience methods that can be used as
 \$placeholders in your template definitions:
 
diff --git a/docs/users_guide_src/links.tex b/docs/users_guide_src/links.tex
index d0480f0..1ec2f6c 100644
--- a/docs/users_guide_src/links.tex
+++ b/docs/users_guide_src/links.tex
@@ -1,10 +1,8 @@
 \section{Useful Web Links}
 \label{links}
 
-Some of this information is moving to the wiki
-\url{http://cheetah.colorstudy.net/twiki/bin/view/Cheetah/WebHome}
-
-%% @@MO: http://www.cheetahtemplate.org/wiki
+See the wiki for more links.  (The wiki is also updated more often than this
+chapter is.)
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Cheetah Links}
@@ -26,7 +24,7 @@ Some of this information is moving to the wiki
 \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 Repository] -- \url{http://sourceforge.net/cvs/?group\_id=28961}
      
 \item[CVS-commits archive] --
      \url{http://www.geocrawler.com/lists/3/SourceForge/13091/0/}
@@ -35,11 +33,7 @@ Some of this information is moving to the wiki
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Third-party Cheetah Stuff}
-\label{links.cheetah}
-
-This is NOT a definitive listing of sites and products using Cheetah. If you
-have something to add to the list please send an email to
-\email{cheetahtemplate-discuss@lists.sf.net}.
+\label{links.thirdParty}
 
 \begin{itemize}
 \item Steve Howell has written a photo viewer using Python.
@@ -83,7 +77,7 @@ have something to add to the list please send an email to
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsubsection{Python Database Modules and Open Source Databases}
-\label{links.other}
+\label{links.database}
 
 \begin{description}
 \item[Python Database Topic Guide] -- \url{http://python.org/topics/database/}
@@ -103,7 +97,7 @@ have something to add to the list please send an email to
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsubsection{Other Internet development frameworks}
-\label{links.other}
+\label{links.internet}
 
 \begin{description}
 \item[ZOPE (Z Object Publishing Environment)] -- \url{http://zope.org/}
diff --git a/docs/users_guide_src/parserInstructions.tex b/docs/users_guide_src/parserInstructions.tex
index bde6b28..3a0e2ac 100644
--- a/docs/users_guide_src/parserInstructions.tex
+++ b/docs/users_guide_src/parserInstructions.tex
@@ -6,7 +6,7 @@
 \subsection{\#breakpoint}
 \label{parserInstructions.breakpoint}
 
-The \code{\#breakpoint} is a debugging tool that tells the parser to stop
+\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
@@ -18,7 +18,7 @@ executed at run time while filling the template.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{\#compiler-settings}
-\label{parserInstructions.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
diff --git a/docs/users_guide_src/tipsAndTricks.tex b/docs/users_guide_src/tipsAndTricks.tex
index 30fc401..43d10f8 100644
--- a/docs/users_guide_src/tipsAndTricks.tex
+++ b/docs/users_guide_src/tipsAndTricks.tex
@@ -2,6 +2,12 @@
 \section{Miscellaneous Placeholder and Directive Tips}
 \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{ASP-style tags}
 \label{tips.ASP}
@@ -55,7 +61,7 @@ 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 inadvertantly or
+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
@@ -66,43 +72,118 @@ your own "safe" namespace.
 % @@ MO: If getVar() is called from Python, does errorCatcher apply?
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{All Template methods}
-\label{tips.allMethods}
+\subsection{Calling superclass methods, and why you have to}
+\label{tips.callingSuperclassMethods}
 
-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.  
+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.
 
-If you do override the standard method, remember to call the
-superclass method when/if appropriate.  The most common method to override is
-\code{.awake()}.  It's a convenient place to put any initialization needed 
-by your template because Webware automatically calls \code{.awake()} when it
-begins processing the request.  You'll definitely want to call the superclass
-\code{.awake()} method as your first statement, because the superclass method
-sets up many wonderful features like access to the CGI fields.  For 
-Python >= 2.2, you simply do:
+In Python >= 2.2, you can simply do:
 \begin{verbatim}
-class MyMixin:
+from Cheetah.Template import Template
+class MyClass(Template):
 	def awake(self, trans):
-		super(MyMixin, self).awake(trans)
-		... great and exciting features written by me ...
+		super(MyClass, self).awake(trans)
+		... add your own great and exciting features here ...
 \end{verbatim}
-For Python < 2.2, you have to know which class \code{.awake()} is inherited
-from (it's \code{Servlet}, which \code{Template} inherits) and call that method
-directly as an unbound method:
+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 MyMixin:
+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.
+
+% @@MO: Tavis had a section here "Moving Code into Python".  What did he
+% mean?  Is that a relic from an older version of Cheetah?
+
+
+
 
 % Local Variables:
 % TeX-master: "users_guide"
diff --git a/docs/users_guide_src/webware.tex b/docs/users_guide_src/webware.tex
index 06940b8..85d2dcd 100644
--- a/docs/users_guide_src/webware.tex
+++ b/docs/users_guide_src/webware.tex
@@ -2,10 +2,6 @@
 \section{Using Cheetah with Webware}
 \label{webware}
 
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Background}
-\label{webware.background}
-
 {\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
@@ -23,6 +19,39 @@ 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
@@ -52,7 +81,7 @@ them for new servlets.  Existing servlets can be converted later, if at all.
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{The Containment Approach}
+\subsubsection{The Containment Approach}
 \label{webware.containment}
 
 In the Containment approach, your servlet is not a template.  Instead, it 
@@ -76,20 +105,23 @@ 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.
+
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{The Inheritance Approach}
+\subsubsection{The Inheritance Approach}
 \label{webware.inheritance}
 
 In the Inheritance approach, your template object doubles as as Webware 
-servlet.  {\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
-having 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.
+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
@@ -101,25 +133,15 @@ 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 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 logic class
+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 you write inherit from a mixin class containing \code{.awake()} and 
-\code{.sleep()} methods, Webware will automatically call those methods before
-and after it calls \code{.respond()} to fill the template.  So 
-\code{.awake()} is a good place to put calculations, side effects and 
-form processing that must be done before the template is filled.
-\code{.awake()} can even redirect to another servlet if you discover that this
-isn't the appropriate servlet for the situation (e.g., in case of user errors
-on a form).  
+\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
@@ -130,6 +152,11 @@ 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}
@@ -202,7 +229,7 @@ www/                         # Web root directory.
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Doing calculations}
+\subsection{Initializing your template-servlet with Python code}
 \label{webware.calculations}
 
 If you need a place to initialize variables or do calculations for your
@@ -213,26 +240,13 @@ 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.
+\code{Servlet.awake} will respond.  Section
+\ref{tips.callingSuperclassMethods} gives examples of how to call a
+superclass method.
 
-\begin{verbatim}
-from MyParentTemplate import MyParentTemplate
-class MyMixin(MyParentTemplate):
-        def awake(self, transaction):
-                super(MyMixin, self).awake(transaction)
-                # In Python < 2.2, you have to do instead:
-                # MyParentTemplate.awake(self, transaction)
-                self.attribute1 = SomeCalculation
-                self.attribute2 = AnotherCalculation
-\end{verbatim}
-
-You can also put all your calculations in your own method, which I 
-conventionally call \code{doEverything}, and call it near the top of your
-template:
-\begin{verbatim}
-#silent $doEveryting
-\end{verbatim}
-This works well, but it does mean one ugly extra line in your template.
+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}
@@ -298,7 +312,7 @@ 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 form-showing-and-processing servlet template.
+% @@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
@@ -446,7 +460,7 @@ blank/zero.  In those relatively few cases where you must distinguish between
     * $ValueError/ValueError
 (NonNumericInputError is defined in this class and is useful for
 distinguishing between bad input vs a TypeError/ValueError
-thrown for some other rason.)
+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.
@@ -476,7 +490,7 @@ sources:
 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 comparisions in your templates without having to
+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'])
@@ -504,7 +518,7 @@ 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 sophistocated file-upload handling, leave that name out of
+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