1 files changed, 104 insertions, 0 deletions
diff --git a/www/dev_guide/design.rst b/www/dev_guide/design.rst
new file mode 100644
index 0000000..1ffabbd
--- /dev/null
+++ b/www/dev_guide/design.rst
@@ -0,0 +1,104 @@
+Design Decisions and Tradeoffs
+==============================
+
+(design)
+
+Delimiters
+----------
+
+(design.Delimiters)
+
+One of the first decisions we encountered was which delimiter
+syntax to use. We decided to follow Velocity's {$placeholder} and
+{#directive} syntax because the former is widely used in other
+languages for the same purpose, and the latter stands out in an
+HTML or text document. We also implemented the
+``${longPlaceholder}`` syntax like the shells for cases where
+Cheetah or you might be confused where a placeholder ends. Tavis
+went ahead and made ``${longPlaceholder}`` and
+``$[longPlaceholder]`` interchangeable with it since it was trivial
+to implement. Finally, the {#compiler} directive allows you to
+change the delimiters if you don't like them or if they conflict
+with the text in your document. (Obviously, if your document
+contains a Perl program listing, you don't necessarily want to
+backslash each and every {$} and {#}, do you?)
+
+The choice of comment delimiters was more arbitrary. {##} and {#\*
+... \*#} doesn't match any language, but it's reminiscent of Python
+and C while also being consistent with our "{#} is for directives"
+convention.
+
+We specifically chose { not} to use pseudo HTML tags for
+placeholders and directives, as described more thoroughly in the
+Cheetah Users' Guide introduction. Pseudo HTML tags may be easier
+to see in a visual editor (supposedly), but in text editors they're
+hard to distinguish from "real" HTML tags unless you look closely,
+and they're many more keystrokes to type. Also, if you make a
+mistake, the tag will show up as literal text in the rendered HTML
+page where it will be easy to notice and eradicate, rather than
+disappearing as bogus HTML tags do in browsers.
+
+Late binding
+------------
+
+(design.lateBinding)
+
+One of Cheetah's unique features is the name mapper, which lets you
+write {$a.b} without worrying much about the type of {a} or {b}.
+Prior to version 0.9.7, Cheetah did the entire NameMapper lookup at
+runtime. This provided maximum flexibility at the expense of speed.
+Doing a NameMapper lookup is intrinsically more expensive than an
+ordinary Python expression because Cheetah has to decide what type
+of container {a} is, whether the the value is a function (autocall
+it), issue the appropriate Python incantation to look up {b} in it,
+autocall again if necessary, and then convert the result to a
+string.
+
+To maximize run-time (filling-time) performance, Cheetah 0.9.7
+pushed much of this work back into the compiler. The compiler
+looked up {a} in the searchList at compile time, noted its type,
+and generated an eval'able Python expression based on that.
+
+This approach had two significant drawbacks. What if {a} later
+changes type before a template filling? Answer: unpredictable
+exceptions occur. What if {a} does not exist in the searchList at
+compile time? Answer: the template can't compile.
+
+To prevent these catastrophes, users were required to prepopulate
+the searchList before instantiating the template instance, and then
+not to change {a}'s type. Static typing is repugnant in a dynamic
+language like Python, and having to prepopulate the searchList made
+certain usages impossible. For example, you couldn't instantiate
+the template object without a searchList and then set {self}
+attributes to specify the values.
+
+After significant user complaints about the fragility of this
+system, Tavis rewrote placeholder handling, and in version 0.9.8a3
+(August 2001), Tavis moved the name mapper lookup back into
+runtime. Performance wasn't crippled because he discovered that
+writing a C version of the name mapper was easier than anticipated,
+and the C version completed the lookup quickly. Now Cheetah had
+"late binding", meaning the compiler does not look up {a} or care
+whether it exists. This allows users to create {a} or change its
+type anytime before a template filling.
+
+The lesson we learned is that it's better to decide what you want
+and then figure out how to do it, rather than assuming that certain
+goals are unattainable due to performance considerations.
+
+Caching framework
+-----------------
+
+(design.cache)
+
+Webware compatibility and the transaction framework
+---------------------------------------------------
+
+(design.webware)
+
+Single inheritance
+------------------
+
+(design.singleInheritance)
+
+