1 files changed, 266 insertions, 0 deletions
diff --git a/docs/users_guide_src/gettingStarted.tex b/docs/users_guide_src/gettingStarted.tex
new file mode 100755
index 0000000..69a3136
--- /dev/null
+++ b/docs/users_guide_src/gettingStarted.tex
@@ -0,0 +1,266 @@
+\section{Getting Started}
+\label{gettingStarted}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Requirements}
+\label{gettingStarted.requirements}
+
+Cheetah requires Python release 2.0 or greater, and has been tested with Python
+2.0, 2.1 and 2.2.  It is known to run on Linux, Windows NT/98/XP, FreeBSD and
+Solaris, and should run anywhere Python runs.  
+
+99\% of Cheetah is written in Python.  There is one small C module
+(\code{\_namemapper.so}) for speed, but Cheetah automatically falls back to a
+Python equivalent (\code{NameMapper.py}) if the C module is not available.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Installation}
+\label{gettingStarted.install}
+
+To install Cheetah in your system-wide Python library:
+\begin{enumerate}
+\item Login as a user with privileges to install system-wide Python packages.
+     On POSIX systems (AIX, Solaris, Linux, IRIX, etc.), the command is normally
+     'su root'.  On non-POSIX systems such as Windows NT, login as an
+     administrator.
+
+\item Run \code{python setup.py install} at the command prompt.
+
+\item The setup program will install the wrapper script {\bf cheetah} to 
+     wherever it usually puts Python binaries ("/usr/bin/", "bin/" in the 
+     Python install directory, etc.)
+\end{enumerate}
+
+Cheetah's installation is managed by Python's Distribution Utilities
+('distutils').  There are many options for customization.  Type \code{``python
+  setup.py help''} for more information.
+
+To install Cheetah in an alternate location -- someplace outside Python's
+\code{site-packages/} directory, use one of these options:
+\begin{verbatim}
+    python setup.py install --home /home/tavis 
+    python setup.py install --install-lib /home/tavis/lib/python
+\end{verbatim}
+Either way installs to /home/tavis/lib/python/Cheetah/ .  Of course,
+/home/tavis/lib/python must be in your Python path in order for Python to
+find Cheetah.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Files}
+\label{gettingstarted.files}
+
+If you do the systemwide install, all Cheetah modules are installed in the
+{\bf site-packages/Cheetah/} subdirectory of your standard library
+directory; e.g., /opt/Python2.2/lib/python2.2/site-packages/Cheetah.
+
+Two commands are installed in Python's \code{bin/} directory or a system
+bin directory: \code{cheetah} (section \ref{gettingStarted.cheetah}) and
+\code{cheetah-compile} (section \ref{howWorks.cheetah-compile}).  
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Uninstalling}
+\label{gettingstarted.uninstalling}
+
+% @@MO: When 'python setup.py uninstall' is implemented, mention it here.
+
+To uninstall Cheetah, merely delete the site-packages/Cheetah/ directory.
+Then delete the ``cheetah'' and ``cheetah-compile'' commands from whichever
+bin/ directory they were put in.
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{The 'cheetah' command}
+\label{gettingStarted.cheetah}
+
+Cheetah comes with a utility \code{cheetah} that provides a command-line
+interface to various housekeeping tasks.  The command's first argument is
+the name of the task.  The following commands are currently supported:
+
+\begin{verbatim}
+cheetah compile [options] [FILES ...]     : Compile template definitions
+cheetah fill [options] [FILES ...]        : Fill template definitions
+cheetah help                              : Print this help message
+cheetah options                           : Print options help message
+cheetah test                              : Run Cheetah's regression tests
+cheetah version                           : Print Cheetah version number
+\end{verbatim}
+
+You only have to type the first letter of the command:
+\code{cheetah c} is the same as \code{cheetah compile}.
+
+The test suite is described in the next section.  The \code{compile}
+command will be described in section \ref{howWorks.cheetah-compile}, 
+and the \code{fill} command in section \ref{howWorks.cheetah-fill}.
+
+The depreciated \code{cheetah-compile} program does the same thing as 
+\code{cheetah compile}.
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Testing your installation}
+\label{gettingStarted.test}
+
+After installing Cheetah, you can run its self-test routine to verify it's
+working properly on your system.  Change directory to any directory you have
+write permission in (the tests write temporary files).  Do not run the tests
+in the directory you installed Cheetah from, or you'll get unnecessary errors.
+Type the following at the command prompt:
+\begin{verbatim}
+cheetah test 
+\end{verbatim}
+
+The tests will run for about three minutes and print a success/failure
+message.  If the tests pass, start Python in interactive mode and try the
+example in the next section.
+
+Certain test failures are insignificant:
+\begin{description}
+\item{{\bf AssertionError: Template output mismatch: Expected Output = 0(end)
+Actual Output = False(end)}}  Python 2.3 changed the string representation of
+booleans, and the tests haven't yet been updated to reflect this.  
+\item{{\bf AssertionError: subcommand exit status 127}}  Certain tests run
+``cheetah'' as a subcommand.  The failure may mean the command wasn't found
+in your system path. (What happens if you run ``cheetah'' on the command line?)
+The failure also happens on some Windows systems for unknown reasons.  This
+failure has never been observed outside the test suite.  Long term, we plan to
+rewrite the tests to do a function call rather than a subcommand, which will
+also make the tests run significantly faster.
+\item{{\bf ImportError: No module named SampleBaseClass}}  The test tried to
+write a temporary module in the current directory and \code{import} it.  Reread
+the first paragraph in this section about the current directory.
+\item{{\bf ImportError: No module named tmp}}  May be the same problem as
+SampleBaseClass; let us know if changing the current directory doesn't work.
+\end{description}
+
+If any other tests fail, please send a message to the e-mail list with a copy
+of the test output and the following details about your installation:
+
+\begin{enumerate}
+\item your version of Cheetah
+\item your version of Python
+\item your operating system
+\item whether you have changed anything in the Cheetah installation
+\end{enumerate}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Quickstart tutorial}
+\label{gettingStarted.tutorial}
+
+This tutorial briefly introduces how to use Cheetah from the Python prompt.
+The following chapters will discuss other ways to use templates and more of
+Cheetah's features.
+
+The core of Cheetah is the \code{Template} class in the \code{Cheetah.Template}
+module. The following example shows how to use the \code{Template} class in an
+interactive Python session. \code{t} is the Template instance.  Lines prefixed
+with \code{>>>} and \code{...} are user input.  The remaining lines are Python
+output.
+
+\begin{verbatim}
+>>> from Cheetah.Template import Template
+>>> templateDef = """
+... <HTML>
+... <HEAD><TITLE>$title</TITLE></HEAD>
+... <BODY>
+... $contents
+... ## this is a single-line Cheetah comment and won't appear in the output
+... #* This is a multi-line comment and won't appear in the output
+...    blah, blah, blah 
+... *#
+... </BODY>
+... </HTML>"""
+>>> nameSpace = {'title': 'Hello World Example', 'contents': 'Hello World!'}
+>>> t = Template(templateDef, searchList=[nameSpace])
+>>> print t
+ 
+<HTML>
+<HEAD><TITLE>Hello World Example</TITLE></HEAD>
+<BODY>
+Hello World!
+</BODY>
+</HTML>
+>>> print t    # print it as many times as you want
+      [ ... same output as above ... ]
+>>> nameSpace['title'] = 'Example #2'
+>>> nameSpace['contents'] = 'Hiya Planet Earth!'
+>>> print t   # Now with different plug-in values.
+<HTML>
+<HEAD><TITLE>Example #2</TITLE></HEAD>
+<BODY>
+Hiya Planet Earth!
+</BODY>
+</HTML>
+
+\end{verbatim}
+
+Since Cheetah is extremely flexible, you can achieve the same result this
+way:  
+
+\begin{verbatim}
+>>> t2 = Template(templateDef)
+>>> t2.title = 'Hello World Example!'
+>>> t2.contents = 'Hello World'
+>>> print t2
+      [ ... same output as the first example above ... ]
+>>> t2.title = 'Example #2'
+>>> t2.contents = 'Hello World!'
+>>> print t2
+     [ ... same as Example #2 above ... ]
+\end{verbatim}
+
+Or this way:
+
+\begin{verbatim}
+>>> class Template3(Template):
+>>>     title = 'Hello World Example!'
+>>>     contents = 'Hello World!'
+>>> t3 = Template3(templateDef)
+>>> print t3
+     [ ... you get the picture ... ]
+\end{verbatim}
+
+The template definition can also come from a file instead of a string,
+as we will see in section \ref{howWorks.constructing}.
+
+The above is all fine for short templates, but for long templates or
+for an application that depends on many templates in a hierarchy, it's
+easier to store the templates in separate *.tmpl files and use the
+{\bf cheetah compile} program to convert them into Python classes in
+their own modules.  This will be covered in section
+\ref{howWorks.cheetah-compile}.  
+
+As an appetizer, we'll just briefly mention that you can store constant values
+{\em inside} the template definition, and they will be converted to attributes
+in the generated class.  You can also create methods the same way.
+You can even use inheritance to arrange your templates in a hierarchy,
+with more specific templates overriding certain parts of more general
+templates (e.g., a "page" template overriding a sidebar in a "section"
+template).
+
+For the minimalists out there, here's a template definition,
+instantiation and filling all in one Python statement:
+
+\begin{verbatim}
+>>> print Template("Templates are pretty useless without placeholders.")
+Templates are pretty useless without placeholders.
+\end{verbatim}
+
+You use a precompiled template the same way, except you don't provide
+a template definition since it was already established:
+
+\begin{verbatim}
+from MyPrecompiledTemplate import MyPrecompiledTemplate
+t = MyPrecompiledTemplate()
+t.name = "Fred Flintstone"
+t.city = "Bedrock City"
+print t
+\end{verbatim}
+
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End:      
+