removed docs dir

1 files changed, 0 insertions, 383 deletions

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:      
-