Revert "Delete the "old" docs directory to make way for fancy smancy sphinx"docs

This reverts commit 5dc95cfcd015628665d3672e56d0551943b5db6b.

1 files changed, 246 insertions, 0 deletions

diff --git a/docs/devel_guide_src/pyModules.tex b/docs/devel_guide_src/pyModules.tex
new file mode 100755
index 0000000..2aa3236
--- /dev/null
+++ b/docs/devel_guide_src/pyModules.tex
@@ -0,0 +1,246 @@
+\section{.py Template Modules}
+\label{pyModules}
+
+This chapter examines the structure of a .py template module.  The following
+few chapters will then show how each placeholder and directive affects the
+generated Python code.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{An example}
+\label{pyModules.example}
+
+Our first template follows a long noble tradition in computer tutorials.
+It produces a familiar, friendly greeting.  Here's the template:
+
+\begin{verbatim}
+Hello, world!
+\end{verbatim}
+
+... the output:
+
+\begin{verbatim}
+Hello, world!
+\end{verbatim}
+
+... and the .py template module cheetah-compile produced, with line
+numbers added:
+
+% @@MO: Is it possible to print the line numbers gray instead of black?
+
+\begin{verbatim}
+  1	#!/usr/bin/env python
+    
+  2	"""
+  3	Autogenerated by CHEETAH: The Python-Powered Template Engine
+  4	 CHEETAH VERSION: 0.9.12
+  5	 Generation time: Sat Apr 20 14:27:47 2002
+  6	   Source file: x.tmpl
+  7	   Source file last modified: Wed Apr 17 22:10:59 2002
+  8	"""
+    
+  9	__CHEETAH_genTime__ = 'Sat Apr 20 14:27:47 2002'
+ 10	__CHEETAH_src__ = 'x.tmpl'
+ 11	__CHEETAH_version__ = '0.9.12'
+    
+ 12	##################################################
+ 13	## DEPENDENCIES
+    
+ 14	import sys
+ 15	import os
+ 16	import os.path
+ 17	from os.path import getmtime, exists
+ 18	import time
+ 19	import types
+ 20	from Cheetah.Template import Template
+ 21	from Cheetah.DummyTransaction import DummyTransaction
+ 22	from Cheetah.NameMapper import NotFound, valueForName, 
+           valueFromSearchList
+ 23	import Cheetah.Filters as Filters
+ 24	import Cheetah.ErrorCatchers as ErrorCatchers
+    
+ 25	##################################################
+ 26	## MODULE CONSTANTS
+    
+ 27	try:
+ 28	    True, False
+ 29	except NameError:
+ 30	    True, False = (1==1), (1==0)
+    
+ 31	##################################################
+ 32	## CLASSES
+    
+ 33	class x(Template):
+ 34	    """
+ 35	    
+ 36	    Autogenerated by CHEETAH: The Python-Powered Template Engine
+ 37	    """
+\end{verbatim}
+\begin{verbatim}
+ 38	    ##################################################
+ 39	    ## GENERATED METHODS
+    
+    
+ 40	    def __init__(self, *args, **KWs):
+ 41	        """
+ 42	        
+ 43	        """
+    
+ 44	        Template.__init__(self, *args, **KWs)
+ 45	        self._filePath = 'x.tmpl'
+ 46	        self._fileMtime = 1019106659
+    
+ 47	    def respond(self,
+ 48	            trans=None,
+ 49	            dummyTrans=False,
+ 50	            VFS=valueFromSearchList,
+ 51	            VFN=valueForName,
+ 52	            getmtime=getmtime,
+ 53	            currentTime=time.time):
+    
+    
+ 54	        """
+ 55	        This is the main method generated by Cheetah
+ 56	        """
+    
+ 57	        if not trans:
+ 58	            trans = DummyTransaction()
+ 59	            dummyTrans = True
+ 60	        write = trans.response().write
+ 61	        SL = self._searchList
+ 62	        filter = self._currentFilter
+ 63	        globalSetVars = self._globalSetVars
+ 64	        
+ 65	        ########################################
+ 66	        ## START - generated method body
+ 67	        
+ 68	        if exists(self._filePath) and getmtime(self._filePath) > \
+                    self._fileMtime:
+ 69	            self.compile(file=self._filePath)
+ 70	            write(getattr(self, self._mainCheetahMethod_for_x)
+                        (trans=trans))
+ 71	            if dummyTrans:
+ 72	                return trans.response().getvalue()
+ 73	            else:
+ 74	                return ""
+ 75	        write('Hello, world!\n')
+ 76	        
+ 77	        ########################################
+ 78	        ## END - generated method body
+ 79	        
+ 80	        if dummyTrans:
+ 81	            return trans.response().getvalue()
+ 82	        else:
+ 83	            return ""
+\end{verbatim}
+\begin{verbatim}
+ 84	        
+ 85	    ##################################################
+ 86	    ## GENERATED ATTRIBUTES
+    
+    
+ 87	    __str__ = respond
+    
+ 88	    _mainCheetahMethod_for_x= 'respond'
+    
+    
+ 89	# CHEETAH was developed by Tavis Rudd, Chuck Esterbrook, Ian Bicking 
+        #     and Mike Orr;
+ 90	# with code, advice and input from many other volunteers.
+ 91	# For more information visit http://www.CheetahTemplate.org
+    
+ 92	##################################################
+ 93	## if run from command line:
+ 94	if __name__ == '__main__':
+ 95	    x().runAsMainProgram()
+    
+\end{verbatim}
+
+(I added the line numbers for this Guide, and split a few lines to fit the
+page width.  The continuation lines don't have line numbers, and I added
+indentation, backslashes and '\#' as necessary to make the result a valid
+Python program.)
+
+The examples were generated from CVS versions of Cheetah between 0.9.12 and
+0.9.14.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{A walk through the example}
+\label{pyModules.walk}
+
+Lines 20-24 are the Cheetah-specific imports.  Line 33 introduces our generated
+class, \code{x}, a subclass of \code{Template}.  It's called x because the
+source file was x.tmpl.
+
+Lines 40-46 are the \code{.\_\_init\_\_} method called when the template is
+instantiated or used as a Webware servlet, or when the module is run as a
+standalone program.  We can see it calling its superclass constructor and
+setting \code{.\_filePath} and \code{.\_fileMtime} to the filename and
+modification time (in Unix ticks) of the source .tmpl file.
+
+Lines 47-84 are the main method \code{.respond}, the one that fills the
+template.  Normally you call it without arguments, but Webware calls it with a
+Webware \code{Transaction} object representing the current request.  Lines
+57-59 set up the \code{trans} variable.  If a real or dummy transaction is
+passed in, the method uses it.  Otherwise (if the \code{trans} argument is
+\code{None}), the method creates a \code{DummyTransaction} instance.
+\code{dummyTrans} is a flag that just tells whether a dummy transaction is in
+effect; it'll be used at the end of the method.  
+
+The other four \code{.respond} arguments aren't anything you'd ever want to
+pass in; they exist solely to speed up access to these frequently-used
+global functions.  This is a standard Python trick described in question 4.7
+of the Python FAQ (\url{http://www.python.org/cgi-bin/faqw.py}).
+\code{VFS} and \code{VFN} are the functions that give your template the
+benefits of NameMapper lookup, such as the ability to use the searchList.  
+
+Line 60 initializes the \code{write} variable.  This important variable is
+discussed below.  
+
+Lines 60-63 initialize a few more local variables.  \code{SL} is the 
+searchList.  \code{filter} is the current output filter.  \code{globalSetVars}
+are the variables that have been defined with \code{\#set global}.
+
+The comments at lines 65 and 78 delimit the start and end of the code that
+varies with each template.  The code outside this region is identical in all
+template modules.  That's not quite true -- \code{\#import} for instance
+generates additional \code{import} statements at the top of the module --
+but it's true enough for the most part.
+
+Lines 68-74 exist only if the template source was a named file rather than
+a string or file object.  The stanza recompiles the template if the source
+file has changed.  Lines 70-74 seem to be redundant with 75-83: both 
+fill the template and send the output.  The reason the first set of lines
+exists is because the second set may become invalid when the template is
+recompiled.  (This is for {\em re}\ compilation only.  The initial compilation
+happened in the \code{.\_\_init\_\_} method if the template wasn't 
+precompiled.)
+
+Line 75 is the most interesting line in this module.  It's a direct
+translation of what we put in the template definition, ``Hello, world!'' Here
+the content is a single string literal.  \code{write} looks like an ordinary
+function call, but remember that line 60 made it an alias to
+\code{trans.response().write}, a method in the transaction.  The next few
+chapters describe how the different placeholders and directives influence this
+portion of the generated class.
+
+Lines 80-83 finish the template filling.  If \code{trans} is a real Webware
+transaction, \code{write} has already sent the output to Webware for handling,
+so we return \code{""}.  If \code{trans} is a dummy transaction, 
+\code{write} has been accumulating the output in a Python \code{StringIO}
+object rather than sending it anywhere, so we have to return it.
+
+Line 83 is the end of the \code{.respond} method.
+
+Line 87 makes code{.\_\_str\_\_} an alias for the main method, so that you
+can \code{print} it or apply \code{str} to it and it will fill the template.
+Line 88 gives the name of the main method, because sometimes it's not
+\code{.respond}.  
+
+Lines 94-95 allow the module to be run directly as a script.  Essentially,
+they process the command-line arguments and them make the template fill
+itself.
+
+
+% Local Variables:
+% TeX-master: "devel_guide"
+% End: