1 files changed, 109 insertions, 0 deletions
diff --git a/docs/users_guide_2_src/13a_precompiledTemplateModules.txt b/docs/users_guide_2_src/13a_precompiledTemplateModules.txt
new file mode 100644
index 0000000..5b0f978
--- /dev/null
+++ b/docs/users_guide_2_src/13a_precompiledTemplateModules.txt
@@ -0,0 +1,109 @@
+A look inside precompiled template modules
+==========================================
+
+..
+    :label: howWorks.pyTrivia
+
+When debugging a template, it's useful to compile it with "cheetah compile"
+and then inspect the resulting Python module.  This will often clear up whether
+Cheetah misinterpreted your intent.  You can do this even if you don't intend to
+use the precompiled templates in production.  It's also a good way to learn how
+Cheetah works.  Simply make a throwaway template definition containing only one
+placeholder or directive, compile it with "cheetah compile", and see what
+Python code Cheetah generated.
+
+However, precompiled template modules can be a bit cryptic to read unless you
+have a bit of background information.  Let's look at an example.  Put the
+following into /tmp/x.tmpl (or any other file) and run "cheetah compile" on
+it::
+
+    The number is $Test.unittest.main.
+    #set mood = "lucky"
+    I'm feeling $lucky.
+
+Open the resulting /tmp/x.py in your favorite text editor.  You'll see a class
+with the same name as the module::
+
+    class x(Template):
+
+This template class contains a method ``.respond()``::
+
+    def respond(self, trans=None):
+        ## CHEETAH: main method generated for this template
+        if (not trans and not self._CHEETAH__isBuffering and 
+            not callable(self.transaction)):
+            trans = self.transaction # is None unless self.awake() was called
+        if not trans:
+            trans = DummyTransaction()
+            _dummyTrans = True
+        else: _dummyTrans = False
+        write = trans.response().write
+        SL = self._CHEETAH__searchList
+        _filter = self._CHEETAH__currentFilter
+        
+        ########################################
+        ## START - generated method body
+
+        
+        write('The number is ')
+        _v = VFFSL(SL,"Test.unittest.main",True) 
+        # '$Test.unittest.main' on line 1, col 15
+        if _v is not None: write(_filter(_v, rawExpr='$Test.unittest.main')) 
+        # from line 1, col 15.
+        write('.\n')
+        mood = "lucky"
+        write("I'm feeling ")
+        _v = VFFSL(SL,"lucky",True) # '$lucky' on line 3, col 13
+        if _v is not None: write(_filter(_v, rawExpr='$lucky')) 
+        # from line 3, col 13.
+        write('.\n') 
+        
+        ########################################
+        ## END - generated method body
+        
+        return _dummyTrans and trans.response().getvalue() or ""
+
+This becomes clearer when we scroll up to see some important imports and
+global variables::
+
+    from Cheetah.Template import Template
+    from Cheetah.DummyTransaction import DummyTransaction
+    from Cheetah.NameMapper import NotFound, valueFromFrameOrSearchList
+    VFFSL=valueFromFrameOrSearchList
+    __CHEETAH_version__ = '2.0rc6'
+    __CHEETAH_src__ = 'x.tmpl'
+
+The actual code will differ slightly depending on your Cheetah version.  Also,
+we've split some long lines to make this page printer-friendly.  
+
+Placeholder lookup is handled by ``VFFSL``, which is really the
+``Cheetah.NameMapper.valueFromFrameOrSearchList`` function or its equivalent
+in Cheetah/_namemapper.c.  
+
+``trans`` and ``write()`` are Webware compatibility features.  Normally 
+``trans`` is not specified and Cheetah creates a ``DummyTransaction``
+instance.  ``write()`` is a shortcut for ``trans.response().write()``,
+which concatenates the output to an internal buffer.  The method returns
+the result: ``trans.response().getvalue()``.  You might assume from 
+``.getvalue()`` that Cheetah uses ``StringIO`` internally, but you'd be wrong.
+Cheetah *used* to use ``StringIO`` but now it uses a list and ``str.join()``.
+The ``.getvalue()`` name is retained for backward compatibility.
+
+If this template is part of a Webware site and the user enters its URL, Webware
+calls ``.respond()`` with a live Webware transaction.  In this case,
+``write()`` writes the output directly to Webware's output stream.  (Or to
+a Webware buffer, but that's not our concern.)  There's nothing to return
+because the output has already been written, so the method returns the empty
+string.  That way if it accidentally gets concatenated to the output, no harm
+will be done.
+
+You can write your own transaction class to support non-Webware output 
+streaming, but Cheetah currently comes with no examples of this.  Ask on
+the mailing list if you need help with it.
+
+Global variables and class attributes defined by Cheetah have a 
+``_CHEETAH_`` prefix.  Instance attributes defined by Cheetah have a
+``__CHEETAH__`` prefix (two trailing underscores).  You should normally
+never write to these but you can read them if desired; many are
+self-explanatory.  One such attribute is ``._CHEETAH__searchList``.  This
+is the actual search List ``VFFSL()`` will consult for placeholder lookups.