1 files changed, 99 insertions, 0 deletions
diff --git a/docs/users_guide_src/comments.tex b/docs/users_guide_src/comments.tex
new file mode 100755
index 0000000..36323cf
--- /dev/null
+++ b/docs/users_guide_src/comments.tex
@@ -0,0 +1,99 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Comments}
+\label{comments}
+
+Comments are used to mark notes, explanations, and decorative text that should
+not appear in the output.  Cheetah maintains the comments in the Python module
+it generates from the Cheetah source code. There are two forms of the comment
+directive: single-line and multi-line.
+
+All text in a template definition that lies between two hash characters
+(\code{\#\#}) and the end of the line is treated as a single-line comment and
+will not show up in the output, unless the two hash characters are escaped with
+a backslash.
+\begin{verbatim}
+##=============================  this is a decorative comment-bar
+$var    ## this is an end-of-line comment
+##=============================
+\end{verbatim}
+
+Any text between \code{\#*} and \code{*\#} will be treated as a multi-line
+comment.
+\begin{verbatim}
+#*
+   Here is some multiline
+   comment text
+*#
+\end{verbatim}
+
+If you put blank lines around method definitions or loops to separate them,
+be aware that the blank lines will be output as is.  To avoid this, make sure
+the blank lines are enclosed in a comment.  Since you normally have a
+comment before the next method definition (right?), you can just extend that
+comment to include the blank lines after the previous method definition, like
+so:
+\begin{verbatim}
+#def method1
+... lines ...
+#end def
+#*
+
+
+   Description of method2.
+   $arg1, string, a phrase.
+*#
+#def method2($arg1)
+... lines ...
+#end def
+\end{verbatim}
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Docstring Comments}
+\label{comments.docstring}
+
+Python modules, classes, and methods can be documented with inline
+'documentation strings' (aka 'docstrings').  Docstrings, unlike comments, are
+accesible at run-time. Thus, they provide a useful hook for interactive help
+utilities.  
+
+Cheetah comments can be transformed into doctrings by adding one of the
+following prefixes:
+
+\begin{verbatim}
+##doc: This text will be added to the method docstring
+#*doc: If your template file is MyTemplate.tmpl, running "cheetah compile"
+       on it will produce MyTemplate.py, with a class MyTemplate in it,
+       containing a method .respond().  This text will be in the .respond()
+       method's docstring. *#
+
+##doc-method: This text will also be added to .respond()'s docstring
+#*doc-method: This text will also be added to .respond()'s docstring *#
+
+##doc-class: This text will be added to the MyTemplate class docstring
+#*doc-class: This text will be added to the MyTemplate class docstring *#
+
+##doc-module: This text will be added to the module docstring MyTemplate.py
+#*doc-module: This text will be added to the module docstring MyTemplate.py*#
+\end{verbatim}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Header Comments}
+\label{comments.headers}
+Cheetah comments can also be transformed into module header comments using the
+following syntax:
+
+\begin{verbatim}
+##header: This text will be added to the module header comment
+#*header: This text will be added to the module header comment *#
+\end{verbatim}
+
+Note the difference between \code{\#\#doc-module: } and \code{header: }:
+``cheetah-compile'' puts \code{\#\#doc-module: } text inside the module
+docstring.  \code{header: } makes the text go {\em above} the docstring, as a
+set of \#-prefixed comment lines.
+
+% Local Variables:
+% TeX-master: "users_guide"
+% End: