tenjin 0.6.2 → 0.7.0

data/CHANGES.txt

@@ -2,6 +2,169 @@
 = CHANGES
 
 
+== Release 0.7.0
+
+* [enhance] Support Ruby 1.9.
+
+* [enhance] Add 'HtmlHelper#escape_html()' which escapes '\'' into '''.
+
+* [change] Change 'HtmlHelper#escape()' to be alias of '#escape_html()', not '#escape_xml()'
+
+* [change] '${}' is changed to escape "'" into '&#039'.
+
+* [enhance] Fragment cache support
+
+	## fragment cache with key ('items/1') and lifetime (60sec)
+	<?rb cache_with('items/1', 60) do ?>
+	<ul>
+	  <?rb for item in @get_items.call() ?>
+	  <li>${item}</li>
+	  <?rb end ?>
+	</ul>
+	<?rb end ?>
+
+	## use file-base cache store
+	Dir.mkdir('cache.d') unless File.exist?('cache.d')
+	kv_store = Tenjin::FileBaseStore.new('cache.d')
+	Tenjin::Engine.data_cache = kv_store
+
+  See: http://www.kuwata-lab.com/tenjin/rbtenjin-users-guide.html#fragment-cache
+
+* [enhance] (EXPERIMENTAL) Add 'SafeTemplate' and 'SafeEngine' classes which escapes HTML characters automatically.
+  * SafeTemplate and SafeEngine escapes context data except SafeString object.
+  * Using these classes, only '${...}' is available. '#{...}' is inhibited.
+
+	##
+	include Tenjin::HtmlHelper
+	include Tenjin::SafeHelper
+	context = {
+	  :text1=>"<AAA>",             # will be escaped
+	  :text2=>safe_str("<AAA>"),   # not escaped because marked as 'already escaped'
+	}
+	engine = Template::SafeEngine.new()
+	html = engine.render('example.rbhtml', context)
+	## example.rbhtml:
+	#<p>text1 = ${@text1}<p>
+	#<p>text2 = ${@text2}<p>
+	## Output:
+	#<p>text1 = &lt;AAA&gt;</p>
+	#<p>text2 = <AAA></p>
+
+  See: http://www.kuwata-lab.com/tenjin/rbtenjin-users-guide.html#auto-escaping
+
+* [enhance] Add new option ':lang' to 'Template.new()'
+  which will be helpful to create M17N page.
+  This feature should be used with preprocessing.
+
+	## creates 'example.rbhtml.en.cache' file
+	lang = "en"
+	engine = Tenjin::Engine.new(:preprocess=>true, :lang=>lang)
+	engine.render("example.rbhtml", {})
+
+	## creates 'example.rbhtml.fr.cache' file
+	lang = "fr"
+	engine = Tenjin::Engine.new(:preprocess=>true, :lang=>lang)
+	engine.render("example.rbhtml", {})
+
+  See: http://www.kuwata-lab.com/tenjin/rbtenjin-users-guide.html#m17n
+
+* [enhance] 'Template' class now supports ':trace' option which prints template filename as HTML comment when importing other template file.
+
+	## print '<!-- **** begin: partial.rhtml **** -->'
+	## and '<!-- **** end: partial.rhtml **** -->'
+	## when importing other template.
+	engine = Tenjin::Engine.new(:trace=>true)
+
+  See: http://www.kuwata-lab.com/tenjin/rbtenjin-users-guide.html#trace
+
+* [enhance] 'Tenjin::Template' class now accepts ':input' option which represents template file content.
+
+	input = <<END
+	<p>Hello ${@name}!
+	END
+	t = Tenjin::Template.new(:input=>input)
+	puts t.render({:name=>"Guest"})
+
+* [enhance] Support logger.
+
+	require 'logger'
+	Tenjin.logger = Logger.new($stderr)
+
+  See: http://www.kuwata-lab.com/tenjin/rbtenjin-users-guide.html#logging
+
+* [enhance] Add new module 'Tenjin::SafeHelper' which includes 'safe_str()', 'safe_escape()', and 'safe_str?()'.
+
+	include Tenjin::HtmlHelper
+	include Tenjin::SafeHelper
+	#
+	s = "<AAA>"
+	puts safe_str?(s)     #=> false
+	s = safe_escape(s)    # same as SafeString.new(escape(s))
+	puts safe_str?(s)     #=> true
+	puts s                #=> &lt;AAA&gt;
+	puts safe_escape(s)   #=> &lt;AAA&gt;
+	#
+	s = "<AAA>"
+	s = safe_str(s)       # same as SafeString.new(s)
+	puts safe_str?(s)     #=> true
+	puts s                #=> <AAA>
+	puts safe_escape(s)   #=> <AAA>
+
+  See: http://www.kuwata-lab.com/tenjin/rbtenjin-users-guide.html#auto-escaping
+
+* [change] Html tag helpers (such as 'checked()') now returns 'SafeString' object to support both 'Tenjin::Template' and 'Tenjin::SafeTemplate'.
+
+* [change] Html tag helpers (such as 'checked()') are moved from 'Tenjin::HtmlHelper' into new module 'Tenjin::HtmlTagHelper'.
+
+* [enhance] Add 'new_cycle()' helper which returns values cyclic.
+
+	## template
+	<?rb cycle = new_cycle('odd', 'even') ?>
+	<?rb 5.times do ?>
+	  class="${cycle}"
+	<?rb end ?>
+	## output
+	  class="odd"
+	  class="even"
+	  class="odd"
+	  class="even"
+	  class="odd"
+
+* [enhance] Add new html tag 'js_link()'.
+
+	js_link('Show', '$().show()')
+	   #=> '<a href="javascript:undefined" onclick="$().show();return false">Show</a>
+
+* [enhance] Add new html tag 'nv()' which generates 'name' and 'value' attributes.
+
+	nv('gender', 'F')       #=> ' name="gender" value="F"
+	nv('gender', 'F', '-')  #=> ' name="gender" value="F" id="gender-F"
+
+* [enhance] Add 'public_html/rbtenjin.cgi' which is a sample script to use tenjin in CGI script.
+
+  See: http://www.kuwata-lab.com/tenjin/rbtenjin-users-guide.html#cgi-script
+
+* [bugfix] import() now works well with preprocessing enabled.
+
+* [change][internal] change test scripts to use 'oktset.rb' instead of test::unit.
+
+* [change][internal] add 'FileFinder' class
+
+* [change][internal] rewrite 'Engine' class to use 'FileFinder' class
+
+* [change][internal] change 'TemplateCache#load()' to make 'timestamp' arg as optional
+
+* [change][internal] change a lot of methods of 'Engine' class to be private
+
+* [change][internal] rename 'Engine.datastore()' to 'Engine.data_store()'
+
+* [change][internal] eliminate timestamp checking of template files
+
+* [change][internal] Changed to use File.rename() instead of File.open() + File#flock()
+  when creating template cache file.
+
+
+
 == Release 0.6.2 (2008-02-24)
 
 * Rubinius supported.

data/MIT-LICENSE

@@ -1,20 +1,19 @@
-copyright(c) 2007-2008 kuwata-lab.com all rights reserved.
+copyright(c) 2007-2011 kuwata-lab.com all rights reserved
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.txt

@@ -1,7 +1,7 @@
 = README
 
-release::	0.6.2
-copyright::	copyright(c) 2007-2008 kuwata-lab.com all rights reserved.
+release::	0.7.0
+copyright::	copyright(c) 2007-2011 kuwata-lab.com all rights reserved
 
 
 == About
@@ -34,11 +34,11 @@ See doc/*.html for details.
 
     $ sudo gem install tenjin
 
-* Else download rbtenjin-0.6.2.tar.bz2 and just copy 'lib/tenjin.rb' and
+* Else download rbtenjin-0.7.0.tar.bz2 and just copy 'lib/tenjin.rb' and
   'bin/rbtenjin' into proper directory.
 
-    $ tar xjf rbtenjin-0.6.2.tar.bz2
-    $ cd rbtenjin-0.6.2/
+    $ tar xjf rbtenjin-0.7.0.tar.bz2
+    $ cd rbtenjin-0.7.0/
     $ sudo copy lib/tenjin.rb /usr/local/lib/ruby/1.8/site_ruby/1.8/
     $ sudo copy bin/rbtenjin /usr/local/bin/
 

data/benchmark/Makefile

@@ -0,0 +1,9 @@
+ntimes = 1000
+
+all:
+	ruby bench.rb -n $(ntimes)
+
+clean:
+	rm -rf *.cache bench_*.rhtml bench_*.rbhtml* *.result
+
+

data/benchmark/bench.rb

@@ -375,7 +375,8 @@ Benchmark.bm(20) do |job|
     when 'tenjin'
       job.report(target) do
         ntimes.times do
-          engine = Tenjin::Engine.new(:cache=>true)
+          #engine = Tenjin::Engine.new(:cache=>true)
+          engine = Tenjin::Engine.new(:cache=>Tenjin::FileBaseTemplateCache.new)
           output = engine.render(tmpl_tenjin, context)
           print output
         end
@@ -422,7 +423,7 @@ Benchmark.bm(20) do |job|
     when 'tenjin-defun-reuse'
       job.report(target) do
         template = Tenjin::Template.new(tmpl_tenjin)
-        defun = defun_code(template.rbcode)
+        defun = defun_code(template.script)
         context.instance_eval(defun)
         ntimes.times do
           output = context.tmpl_tenjin_view()

data/bin/rbtenjin

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 ##
-## copyright(c) 2007-2008 kuwata-lab.com all rights reserved.
+## copyright(c) 2007-2011 kuwata-lab.com all rights reserved
 ##
 ## Permission is hereby granted, free of charge, to any person obtaining
 ## a copy of this software and associated documentation files (the
@@ -23,8 +23,11 @@
 ## WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ##
 
-## $Rev: 70 $
-## $Release: 0.6.2 $
+##
+## $Release: 0.7.0 $
+## copyright(c) 2007-2011 kuwata-lab.com all rights reserved
+## $License: MIT License $
+##
 
 require 'tenjin'
 

data/doc/docstyle.css

@@ -27,7 +27,7 @@ pre {
 	white-space:pre;
 }
 
-.program {
+pre.program {
 	border-style:solid;
 	border-width:1px;
 	border-color:#6699FF;
@@ -38,7 +38,7 @@ pre {
 	word-break:break-all;
 }
 
-.terminal {
+pre.terminal {
 	border-style:solid;
 	border-width:1;
 	border-color:#999999;
@@ -49,7 +49,7 @@ pre {
 	word-break:break-all;
 }
 
-.output {
+pre.output {
 	border-style:solid;
 	border-width:1px;
 	border-color:#CCCCCC;
@@ -61,6 +61,12 @@ pre {
 }
 
 
+pre strong {
+	color: #990000;
+	font-weight: bold;
+}
+
+
 .program_caption {
         margin-top: 20px;
 }
@@ -168,7 +174,7 @@ h3, .subsection {
 	font-size:small;
 }
 
-.note {
+div.note, div.tips {
 	background-color:#FFFFDD;
 	border-style:solid;
 	border-width:0px 1px 0px 1px;
@@ -176,9 +182,14 @@ h3, .subsection {
 	color:#333300;
 	/* font-size:small; */
 	line-height:120%;
+	margin-top: 10px;
 	padding: 5px 20px 5px 20px;
 }
 
+div.note span.caption, div.tips span.caption {
+	color: #C60;
+}
+
 .figure {
 	/*
 	border-width:1px;
@@ -186,3 +197,13 @@ h3, .subsection {
 	white-space:pre;
 	*/
 }
+
+strong {
+	color: #630;
+	font-weight; bold;
+}
+
+
+em {
+	font-style: italic;
+}

data/doc/users-guide.html

@@ -1,1734 +1,2259 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
 <html>
 <head>
-  <meta http-equiv="Content-Type" content="text/html">
+  <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
   <title>rbTenjin User's Guide</title>
   <meta name="generator" content="kwaser">
   <meta http-equiv="Content-Style-Type" content="text/css">
   <link rel="stylesheet" href="docstyle.css" type="text/css">
- </head>
- <body>
+</head>
 
+<body>
   <blockquote>
-   <div class="mainbody">
+    <div class="mainbody">
+      <div align="left">
+        <h1>rbTenjin User's Guide</h1>
+      </div>
 
-    <div align="left"><h1>rbTenjin User's Guide</h1></div>
-    <div align="left">
-      last update: $Date: 2008-02-24 11:43:28 +0900 (Sun, 24 Feb 2008) $<br>
-    </div>
+      <div align="left">
+        release: 0.7.0<br>
+      </div>
 
-<p>Release: 0.6.2
-</p>
-<p>Table of Contents:
-<ul>
-  <li><a href="#intro">Introduction</a>
-  <ul>
-    <li><a href="#overview">Overview</a>
-    </li>
-    <li><a href="#features">Features</a>
-    </li>
-    <li><a href="#benchmark">Benchmark</a>
-    </li>
-  </ul>
-  </li>
-  <li><a href="#installation">Installation</a>
-  </li>
-  <li><a href="#desguide">Designer's Guide</a>
-  <ul>
-    <li><a href="#des-notation">Notation</a>
-    </li>
-    <li><a href="#des-convert">Convert into Ruby Code</a>
-    </li>
-    <li><a href="#des-syntaxchk">Syntax Checking</a>
-    </li>
-    <li><a href="#des-contextdata">Context Data File</a>
-    </li>
-    <li><a href="#des-cmlinecontext">Command-line Context Data</a>
-    </li>
-    <li><a href="#des-nested-template">Nested Template</a>
-    </li>
-    <li><a href="#des-layout">Layout Template</a>
-    </li>
-    <li><a href="#des-capturing">Capturing</a>
-    </li>
-    <li><a href="#des-args">Template Arguments</a>
-    </li>
-    <li><a href="#des-preprocess">Preprocessing</a>
-    </li>
-    <li><a href="#des-otheropts">Other Options</a>
-    </li>
-  </ul>
-  </li>
-  <li><a href="#devguide">Developer's Guide</a>
-  <ul>
-    <li><a href="#dev-example">An Example</a>
-    </li>
-    <li><a href="#dev-classes">Classes and Functions in rbTenjin</a>
-    </li>
-    <li><a href="#dev-templateclass">Class Tenjin::Template</a>
-    </li>
-    <li><a href="#dev-engineclass">Class Tenjin::Engine</a>
-    </li>
-    <li><a href="#dev-initopts">Template Initialize Options</a>
-    </li>
-    <li><a href="#dev-helpers">Add Your Helper Functions</a>
-    </li>
-    <li><a href="#dev-othertopics">Other Topics</a>
-    </li>
-  </ul>
-  </li>
-</ul>
-</p>
-<a name="intro"></a>
-<h2 class="section1">Introduction</h2>
-<a name="overview"></a>
-<h3 class="section2">Overview</h3>
-<p>rbTenjin is a very fast and lightweight template engine based on embedded Ruby.
-You can embed Ruby statements and expressions into your text file.
-rbTenjin converts it into Ruby script and evaluate it.
-</p>
-<p>The following is an example of rbTenjin.
-</p>
-<a name="ex.rbhtml"></a>
-<div class="program_caption">
-File 'ex.rbhtml':</div>
-<pre class="program">Hello <strong>#{@name}</strong>!
-&lt;ul&gt;
-<strong>&lt;?rb for item in @items ?&gt;</strong>
- &lt;li&gt;<strong>${item}</strong>&lt;/li&gt;
-<strong>&lt;?rb end ?&gt;</strong>
-&lt;/ul&gt;
-</pre>
-<p>Here is the notation:
-</p>
-<ul type="disc">
-<li><code>&lt;?rb ... ?&gt;</code> represents embedded Ruby statements.
-</li>
-<li><code>#{...}</code> represents embedded Ruby expression.
-</li>
-<li><code>${...}</code> represents embedded escaped (sanitized) Ruby expression.
-</li>
-</ul>
-<a name="ex_source.result"></a>
-<div class="terminal_caption">
-Result of covertion into Ruby script:</div>
-<pre class="terminal">$ rbtenjin -s ex.rbhtml
-_buf = '';  _buf &lt;&lt; %Q`Hello <strong>#{@name}</strong>!
-&lt;ul&gt;\n`
-<strong>for item in @items</strong>
- _buf &lt;&lt; %Q` &lt;li&gt;<strong>#{escape((item).to_s)}</strong>&lt;/li&gt;\n`
-<strong>end</strong>
- _buf &lt;&lt; %Q`&lt;/ul&gt;\n`
-_buf.to_s
-</pre>
-<a name="ex.result"></a>
-<div class="terminal_caption">
-Output of execution with context data:</div>
-<pre class="terminal">$ rbtenjin -c "@name='World'; @items=['&lt;AAA&gt;','B&amp;B','\"CCC\"']" ex.rbhtml
-Hello World!
-&lt;ul&gt;
- &lt;li&gt;&amp;lt;AAA&amp;gt;&lt;/li&gt;
- &lt;li&gt;B&amp;amp;B&lt;/li&gt;
- &lt;li&gt;&amp;quot;CCC&amp;quot;&lt;/li&gt;
-&lt;/ul&gt;
-</pre>
-<a name="ex.script"></a>
-<div class="program_caption">
-Example of Ruby script</div>
-<pre class="program">require 'tenjin'
-engine = Tenjin::Engine.new()
-context = { :name=&gt;'World', :items=&gt;['&lt;AAA&gt;', 'B&amp;B', '"CCC"'] }
-output = engine.render('ex.rbhtml', context)
-print output
+      <div class="toc"><span class="caption">Table of Contents:</span>
+
+      <ul>
+        <li>
+          <a href="#overview">Overview</a>
+
+          <ul>
+            <li><a href="#features">Features</a></li>
+
+            <li><a href="#install">Install</a></li>
+
+            <li><a href="#benchmark">Benchmark</a></li>
+          </ul>
+        </li>
+
+        <li>
+          <a href="#basic-examples">Basic Examples</a>
+
+          <ul>
+            <li><a href="#template-syntax">Template Syntax</a></li>
+
+            <li><a href="#render-template">Render Template</a></li>
+
+            <li><a href="#source-code">Show Converted Source Code</a></li>
+
+            <li><a href="#layout-template">Layout Template</a></li>
+
+            <li><a href="#context-variables">Context Variables</a></li>
+
+            <li><a href="#template-arguments">Template Arguments</a></li>
+
+            <li><a href="#partial-template">Include Partial Template</a></li>
+
+            <li><a href="#template-short-name">Template Short Name</a></li>
+
+            <li>
+              <a href="#helper-functions">Helper Function</a>
+
+              <ul>
+                <li><a href="#Tenjin::ContextHelper">Tenjin::ContextHelper</a></li>
+
+                <li><a href="#Tenjin::HtmlHelper">Tenjin::HtmlHelper</a></li>
+
+                <li><a href="#Tenjin::SafeHelper">Tenjin::SafeHelper</a></li>
+
+                <li><a href="#Tenjin::HtmlTagHelper">Tenjin::HtmlTagHelper</a></li>
+              </ul>
+            </li>
+          </ul>
+        </li>
+
+        <li>
+          <a href="#advanced-features">Advanced Features</a>
+
+          <ul>
+            <li><a href="#safe-template">Safe Template</a></li>
+
+            <li><a href="#nested-layout-template">Nested Layout Template</a></li>
+
+            <li><a href="#trace">Trace Templates</a></li>
+
+            <li><a href="#capturing">Capturing</a></li>
+
+            <li><a href="#templace-cache">Template Cache</a></li>
+
+            <li><a href="#fragment-cache">Fragment Cache</a></li>
+
+            <li><a href="#logging">Logging</a></li>
+
+            <li>
+              <a href="#preprocessing">Preprocessing</a>
+
+              <ul>
+                <li><a href="#preprocessing-basics">Basics of Preprocessing</a></li>
+
+                <li><a href="#preprocessing-loop-expantion">Loop Expantion</a></li>
+
+                <li><a href="#preprocessing-parameters">Parameters</a></li>
+              </ul>
+            </li>
+
+            <li><a href="#m17n">M17N Page</a></li>
+
+            <li><a href="#cgi-script">Make Tenjin as PHP-like Tool</a></li>
+          </ul>
+        </li>
+
+        <li>
+          <a href="#tips">Tips</a>
+
+          <ul>
+            <li><a href="#function-names">Specify Function Names of escape() and to_str()</a></li>
+
+            <li><a href="#tips-template-inheritance">Template Inheritance</a></li>
+          </ul>
+        </li>
+
+        <li>
+          <a href="#command"><code>rbtenjin</code> Command</a>
+
+          <ul>
+            <li><a href="#command-syntax-check">Syntax Check</a></li>
+
+            <li><a href="#command-convert-script">Convert Template into Ruby Script</a></li>
+
+            <li><a href="#command-retrieve">Retrieve Embedded Code</a></li>
+
+            <li><a href="#command-execute-template">Execute Template File</a></li>
+
+            <li><a href="#command-context-data">Context Data</a></li>
+          </ul>
+        </li>
+
+        <li><a href="#shooting">Trouble shooting</a></li>
+
+        <li><a href="#customize">Customization Examples</a></li>
+      </ul>
+
+      </div><a name="overview" id="overview"></a>
+
+      <h2 class="section1">Overview</h2>
+
+      <p>Tenjin is a very fast and full-featured template engine implemented in pure Ruby.</p><a name="features" id="features"></a>
+
+      <h3 class="section2">Features</h3>
+
+      <ul type="disc">
+        <li>
+          <a href="#benchmark">Very fast</a>
+
+          <ul type="circle">
+            <li>Same as fast as Erubis</li>
+
+            <li><a href="#safe-template">Safe Template</a></li>
+          </ul>
+        </li>
+
+        <li>Full featured
+
+          <ul type="circle">
+            <li><a href="#layout-template">Layout template</a></li>
+
+            <li><a href="#partial-template">Partial template</a></li>
+
+            <li><a href="#fragment-cache">Fragment cache</a></li>
+
+            <li><a href="#capturing">Capturing</a></li>
+
+            <li><a href="#preprocessing">Preprocessing</a></li>
+
+            <li><a href="#m17n">M17N Support</a></li>
+          </ul>
+        </li>
+
+        <li>Easy to learn
+
+          <ul type="circle">
+            <li>Because you can embed any ruby statements or expression in your template files</li>
+
+            <li>You don't have to study template-specific language</li>
+          </ul>
+        </li>
+
+        <li>Compact
+
+          <ul type="circle">
+            <li>Less than 2000 lines of code</li>
+          </ul>
+        </li>
+      </ul><br>
+      <a name="install" id="install"></a>
+
+      <h3 class="section2">Install</h3>
+      <pre class="terminal">
+$ gem install tenjin
 </pre>
-<br>
-
-
-<a name="features"></a>
-<h3 class="section2">Features</h3>
-<p>rbTenjin has the following features:
-</p>
-<ul type="disc">
-<li>rbTenjin runs very fast. It works about three times as fast as ERB.
-</li>
-<li>rbTenjin doesn't break HTML design because it uses XML Processing
-  Instructions (PI) as embedded notation for Ruby statements.
-</li>
-<li>rbTenjin is secure because it supports escaping expression value by default.
-</li>
-<li>rbTenjin is small and lightweight. It is very easy to include rbTenjin
-  into your application.
-</li>
-<li>rbTenjin supports auto caching of converted Ruby code.
-</li>
-<li>rbTenjin supports partial template and layout template.
-  These are very useful especially for web application.
-</li>
-<li>rbTenjin supports partial capturing of template.
-</li>
-<li>rbTenjin can load YAML file as context data. Using rbTenjin, it is able to
-  separate template file and data file.
-</li>
-</ul>
-<br>
-
-
-<a name="benchmark"></a>
-<h3 class="section2">Benchmark</h3>
-<p>Benchmark script is contained in rbTenjin archive.
-The following is an example of benchmark.
-</p>
-<div class="terminal_caption">
-MacOS X 10.4 Tiger, Intel CoreDuo 1.83GHz, Memory 2GB</div>
-<pre class="terminal">$ cd rbtenjin-X.X.X/benchmark
+
+      <p>or</p>
+      <pre class="terminal">
+$ tar xzf rbtenjin-X.X.X.tar.gz
+$ cd rbtenjin-X.X.X/
+$ mkdir -p $HOME/bin
+$ mkdir -p $HOME/lib/ruby
+$ cp bin/rbtenjin $HOME/bin
+$ cp lib/tenjin.rb $HOME/lib/ruby
+$ export PATH=$HOME/bin:$PATH
+$ export RUBYLIB=$HOME/lib/ruby
+</pre><br>
+      <a name="benchmark" id="benchmark"></a>
+
+      <h3 class="section2">Benchmark</h3>
+
+      <div class="terminal_caption">
+        MacOS X 10.6 Snow Leopard, Intel CoreDuo2 2GHz, Memory 2GB
+      </div>
+      <pre class="terminal">
 $ ruby -v
-ruby 1.8.6 (2007-03-13 patchlevel 0) [i686-darwin8.9.1]
-$ ruby bench.rb -n 10000
+ruby 1.8.7 (2011-02-18 patchlevel 334) [i686-darwin10.7.0]
+$ cd benchmark
+$ ruby bench.rb -n 1000
                           user     system      total        real
-eruby                 12.02000    0.27000   12.29000 (  12.34855)
-eruby-cache           11.09000    0.43000   11.53000 (  11.58262)
-erb                   36.32000    0.41000   36.73000 (  36.89404)
-erb-cache             11.13000    0.45000   11.57000 (  11.62259)
-erb-reuse             10.78000    0.03000   10.81000 (  10.85908)
-erb-defmethod          5.82000    0.02000    5.84000 (   5.86168)
-erubis                10.31000    0.32000   10.64000 (  10.68644)
-erubis-cache           7.02000    0.43000    7.45000 (   7.50923)
-erubis-reuse           4.43000    0.01000    4.44000 (   4.45338)
-tenjin                 6.87000    0.47000    7.34000 (   7.37263)
-tenjin-nocache         8.73000    0.36000    9.10000 (   9.14337)
-tenjin-reuse           4.45000    0.07000    4.52000 (   4.53931)
-</pre>
-<p>This shows that rbTenjin is much faster than any other eRuby implementations.
-</p>
-<br>
-
-
-<br>
-
-
-<a name="installation"></a>
-<h2 class="section1">Installation</h2>
-<p>rbTenjin requires Ruby 1.8 or later.
-</p>
-<ul type="disc">
-<li>If you have installed RubyGems, just type '<code>gem install rbtenjin</code>'.
-</li>
-<li>Or if you have administrator privilegde, install with setup.rb.
-<pre class="terminal">$ tar xjf rbtenjin_X.X.X.tar.bz
-$ cd rbtenjin_X.X.X/
-$ ruby setup.rb --help | more
-$ ruby setup.rb config
-$ ruby setup.rb setup
-$ sudo ruby setup.rb install
-</pre>
-</li>
-<li>Or copy 'lib/tenjin.rb' and 'bin/rbtenjin' to proper directories.
-<pre class="terminal">$ tar xjf rbtenjin_X.X.X.tar.bz
-$ cd rbtenjin_X.X.X/
-$ cp lib/tenjin.rb $HOME/lib/ruby/
-$ cp bin/rbtenjin $HOME/bin/
-</pre>
-</li>
-</ul>
-<br>
-
-
-<a name="desguide"></a>
-<h2 class="section1">Designer's Guide</h2>
-<p>This section shows how to use rbTenjin for designer.
-</p>
-<p>If you want to know how to use rbTenjin in your program, see <a href="#devguide">Developer's Guide</a> section.
-</p>
-<a name="des-notation"></a>
-<h3 class="section2">Notation</h3>
-<p>The following is the notation of rbTenjin.
-</p>
-<ul type="disc">
-<li>'<code>&lt;?rb ... ?&gt;</code>' represents embedded Ruby statement.
-</li>
-<li>'<code>#{...}</code>' represents embedded Ruby expression.
-</li>
-<li>'<code>${...}</code>' represents embedded Ruby expression which is to be escaped (for example, '<code>&amp; &lt; &gt; "</code>' is escaped to '<code>&amp;amp; &amp;lt; &amp;gt; &amp;quot;</code>').
-</li>
-</ul>
-<a name="example1.rbhtml"></a>
-<div class="program_caption">
-File 'example1.rbhtml':</div>
-<pre class="program">&lt;table&gt;
-  &lt;tbody&gt;
-<strong>&lt;?rb i = 0 ?&gt;</strong>
-<strong>&lt;?rb for item in ['&lt;foo&gt;', 'bar&amp;bar', '"baz"'] ?&gt;</strong>
-<strong>&lt;?rb     i += 1 ?&gt;</strong>
-    &lt;tr&gt;
-      &lt;td&gt;<strong>#{item}</strong>&lt;/td&gt;
-      &lt;td&gt;<strong>${item}</strong>&lt;/td&gt;
-    &lt;/tr&gt;
-<strong>&lt;?rb end ?&gt;</strong>
-  &lt;tbody&gt;
-&lt;/table&gt;
-</pre>
-<p>The following is the result of executing 'example1.rbhtml'.
-</p>
-<a name="example1.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ rbtenjin example1.rbhtml
+erb                   1.510000   0.030000   1.540000 (  1.555130)
+erb-cache             0.570000   0.030000   0.600000 (  0.606775)
+erb-reuse             0.550000   0.000000   0.550000 (  0.548511)
+erb-defmethod         0.380000   0.000000   0.380000 (  0.398116)
+erubis                0.950000   0.030000   0.980000 (  0.979889)
+erubis-cache          0.580000   0.030000   0.610000 (  0.614893)
+erubis-reuse          0.390000   0.000000   0.390000 (  0.432674)
+tenjin                0.560000   0.040000   0.600000 (  0.606353)
+tenjin-nocache        0.850000   0.040000   0.890000 (  0.890926)
+tenjin-reuse          0.370000   0.010000   0.380000 (  0.393109)
+</pre><br>
+      <br>
+      <a name="basic-examples" id="basic-examples"></a>
+
+      <h2 class="section1">Basic Examples</h2>
+
+      <p>This section describes basics of Tenjin.</p><a name="template-syntax" id="template-syntax"></a>
+
+      <h3 class="section2">Template Syntax</h3>
+
+      <p>Notation:</p>
+
+      <dl class="dl1">
+        <dt class="dt1"><code>&lt;?rb ... ?&gt;</code></dt>
+
+        <dd class="dd1">Ruby statements</dd>
+
+        <dt class="dt1"><code>${...}</code></dt>
+
+        <dd class="dd1">Ruby expression (with HTML escape)</dd>
+
+        <dt class="dt1"><code>#{...}</code></dt>
+
+        <dd class="dd1">Ruby expression (without HTML escape)</dd>
+      </dl><a name="test_010/views/page.rbhtml"></a>
+
+      <div class="program_caption">
+        views/page.rbhtml: html template
+      </div>
+      <pre class="program">
+&lt;h2&gt;<strong>${@title}</strong>&lt;/h2&gt;
 &lt;table&gt;
-  &lt;tbody&gt;
-    &lt;tr&gt;
-      &lt;td&gt;<strong>&lt;foo&gt;</strong>&lt;/td&gt;
-      &lt;td&gt;<strong>&amp;lt;foo&amp;gt;</strong>&lt;/td&gt;
-    &lt;/tr&gt;
-    &lt;tr&gt;
-      &lt;td&gt;<strong>bar&amp;bar</strong>&lt;/td&gt;
-      &lt;td&gt;<strong>bar&amp;amp;bar</strong>&lt;/td&gt;
-    &lt;/tr&gt;
-    &lt;tr&gt;
-      &lt;td&gt;<strong>"baz"</strong>&lt;/td&gt;
-      &lt;td&gt;<strong>&amp;quot;baz&amp;quot;</strong>&lt;/td&gt;
-    &lt;/tr&gt;
-  &lt;tbody&gt;
+  <strong>&lt;?rb i = 0 ?&gt;</strong>
+  <strong>&lt;?rb for item in @items ?&gt;</strong>
+  <strong>&lt;?rb   i += 1 ?&gt;</strong>
+  <strong>&lt;?rb   klass = i % 2 == 1 ? 'odd' : 'even' ?&gt;</strong>
+  &lt;tr class="<strong>#{klass}</strong>"&gt;
+    &lt;td&gt;<strong>${item}</strong>&lt;/td&gt;
+  &lt;/tr&gt;
+  <strong>&lt;?rb end ?&gt;</strong>
 &lt;/table&gt;
 </pre>
-<br>
-
-
-<a name="des-convert"></a>
-<h3 class="section2">Convert into Ruby Code</h3>
-<p>Command-line option '-s' converts embedded files into Ruby code.
-</p>
-<a name="example1_source.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ rbtenjin <strong>-s</strong> example1.rbhtml
-_buf = '';  _buf &lt;&lt; %Q`&lt;table&gt;
-  &lt;tbody&gt;\n`
-<strong>i = 0</strong>
-<strong>for item in ['&lt;foo&gt;', 'bar&amp;bar', '"baz"']</strong>
-    <strong>i += 1</strong>
- _buf &lt;&lt; %Q`    &lt;tr&gt;
-      &lt;td&gt;<strong>#{item}</strong>&lt;/td&gt;
-      &lt;td&gt;<strong>#{escape((item).to_s)}</strong>&lt;/td&gt;
-    &lt;/tr&gt;\n`
-<strong>end</strong>
- _buf &lt;&lt; %Q`  &lt;tbody&gt;
-&lt;/table&gt;\n`
-_buf.to_s
+
+      <div class="tips"><span class="caption">TIPS:</span>
+
+      <p>You can check template syntax by 'rbtenjin -z'.</p><a name="test_011/result.output"></a>
+
+      <div class="terminal_caption">
+        Syntax check of template files
+      </div>
+      <pre class="terminal">
+$ rbtenjin <strong>-z</strong> views/*.rbhtml
+views/page.rbhtml: Syntax OK
 </pre>
-<ul type="disc">
-<li>Variable <code>@_buf</code> is a String.
-</li>
-<li>Function <code>escape()</code> (= <code>Tenjin::Context.escape()</code>) escapes <code>'&amp; &lt; &gt; "'</code> into <code>'&amp;amp; &amp;lt; &amp;gt; &amp;quot;'</code>.
-  Command-line option <code>--escapefunc=func</code> makes rbtenjin to use <code>func()</code> instead of <code>escape()</code>.
-</li>
-<li>Newline character ("\n" or "\r\n") is automatically detected by rbTenjin.
-</li>
-</ul>
-<p>'<code>_buf = '';</code>' is called as preamble and '<code>_buf.to_s</code>' is called as postamble.
-Command-line option '<code>-b</code>' removes preamble and postamble.
-</p>
-<a name="example2.rbhtml"></a>
-<div class="program_caption">
-File 'example2.rbhtml'</div>
-<pre class="program">&lt;?rb for i in [1, 2, 3] ?&gt;
-&lt;p&gt;#{item}&lt;/p&gt;
-&lt;?rb end ?&gt;
+
+      </div><br>
+      <a name="render-template" id="render-template"></a>
+
+      <h3 class="section2">Render Template</h3>
+
+      <p>This is an example code to render template file.</p><a name="test_010/main.rb"></a>
+
+      <div class="program_caption">
+        main.rb: main program
+      </div>
+      <pre class="program">
+<strong>require 'tenjin'</strong>
+
+## context data
+context = {
+  :title =&gt; 'Tenjin Example',
+  :items =&gt; ['&lt;AAA&gt;', 'B&amp;B', '"CCC"'],
+}
+
+## create engine object
+<strong>engine = Tenjin::Engine.new(:path=&gt;['views'])</strong>
+
+## render template with context data
+html = <strong>engine.render('page.rbhtml', context)</strong>
+print html
+</pre><a name="test_010/result.output"></a>
+
+      <div class="terminal_caption">
+        result
+      </div>
+      <pre class="terminal">
+$ ruby main.rb
+&lt;h2&gt;Tenjin Example&lt;/h2&gt;
+&lt;table&gt;
+  &lt;tr class="odd"&gt;
+    &lt;td&gt;&amp;lt;AAA&amp;gt;&lt;/td&gt;
+  &lt;/tr&gt;
+  &lt;tr class="even"&gt;
+    &lt;td&gt;B&amp;amp;B&lt;/td&gt;
+  &lt;/tr&gt;
+  &lt;tr class="odd"&gt;
+    &lt;td&gt;&amp;quot;CCC&amp;quot;&lt;/td&gt;
+  &lt;/tr&gt;
+&lt;/table&gt;
 </pre>
-<a name="example2_sb.result2"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ rbtenjin -s example2.rbhtml
-<strong>_buf = '';</strong> for i in [1, 2, 3]
- _buf &lt;&lt; %Q`&lt;p&gt;#{item}&lt;/p&gt;\n`
-end
-<strong>_buf.to_s</strong>
-$ rbtenjin -s<strong>b</strong> example2.rbhtml
-for i in [1, 2, 3]
- _buf &lt;&lt; %Q`&lt;p&gt;#{item}&lt;/p&gt;\n`
+
+      <div class="tips"><span class="caption">TIPS:</span>
+
+      <p>Hash context data is converted into Tenjin::Context object. It is possible to use your own class as context data object instead of Tenjin::Context.</p>
+      <pre class="program">
+require 'tenjin'
+class FooController &lt; Controller
+  include Tenjin::ContextHelper
+  include Tenjin::HtmlHelper
+  #include Tenjin::SafeHelper      # optional
+  #include Tenjin::HtmlTagHelper   # optional
+  @@engine = Tenjin::Engine.new(:path=&gt;['views'])
+
+  def index
+    @items = ['AAA', 'BBB', 'CCC']
+    html = @@engine.render('foo/index.rbhtml', <strong>self</strong>)
+    return html
+  end
 end
 </pre>
-<p>Command-line option '-S' also show converted Ruby code but it doesn't print text part.
-This is useful to check Ruby code for debugging.
-</p>
-<a name="example1_S.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ rbtenjin <strong>-S</strong> example1.rbhtml
-_buf = ''; 
 
-i = 0
-for item in ['&lt;foo&gt;', 'bar&amp;bar', '"baz"']
-    i += 1
+      </div><br>
+      <a name="source-code" id="source-code"></a>
 
+      <h3 class="section2">Show Converted Source Code</h3>
 
-          escape((item).to_s); 
+      <p>rbTenjin converts template files into Ruby script and executes it. Compiled Ruby script is saved into cache file automatically.</p>
 
-end
+      <div class="terminal_caption">
+        Show cached file
+      </div>
+      <pre class="terminal">
+$ ls views/page.rbhtml*
+views/page.rbhtml       views/page.rbhtml.cache
+$ file views/page.rbhtml.cache
+views/page.rbhtml.cache: text
+</pre>
 
+      <p>You can get converted script by '<code>rbtenjin -s</code>'.</p><a name="test_020/result.output"></a>
 
+      <div class="terminal_caption">
+        Show Ruby code
+      </div>
+      <pre class="terminal">
+$ rbtenjin <strong>-s</strong> views/page.rbhtml
+_buf = '';  _buf &lt;&lt; %Q`&lt;h2&gt;#{escape((@title).to_s)}&lt;/h2&gt;
+&lt;table&gt;\n`
+  i = 0
+  for item in @items
+    i += 1
+    klass = i % 2 == 1 ? 'odd' : 'even'
+ _buf &lt;&lt; %Q`  &lt;tr class="#{klass}"&gt;
+    &lt;td&gt;#{escape((item).to_s)}&lt;/td&gt;
+  &lt;/tr&gt;\n`
+  end
+ _buf &lt;&lt; %Q`&lt;/table&gt;\n`
 _buf.to_s
 </pre>
-<p>In addition, the following command-line options are available.
-</p>
-<dl class="dl3" compact>
-<dt class="dt3"><b>
--N </b></dt>
-<dd class="dd3">
-	     Add line number.
-</dd>
-<dt class="dt3"><b>
--X </b></dt>
-<dd class="dd3">
-	     Delete expressions.
-</dd>
-<dt class="dt3"><b>
--C </b></dt>
-<dd class="dd3">
-	     Remove empty lines (compact-mode).
-</dd>
-<dt class="dt3"><b>
--U </b></dt>
-<dd class="dd3">
-	     Compress empty lines to a line (uniq-mode).
-</dd>
-</dl>
-<a name="example1_SXNC.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ rbtenjin <strong>-SUNX</strong> example1.rbhtml
-    1:  _buf = ''; 
-
-    3:  i = 0
-    4:  for item in ['&lt;foo&gt;', 'bar&amp;bar', '"baz"']
-    5:      i += 1
-
-   10:  end
-
-   13:  _buf.to_s
-</pre>
-<br>
-
-
-<a name="des-syntaxchk"></a>
-<h3 class="section2">Syntax Checking</h3>
-<p>Command-line option '<code>-z</code>' checks syntax error in embedded Ruby code
-and command-line option '<code>-w</code>' sets warning level to 2.
-It is recommended to use '-w' when you specify '-z'.
-</p>
-<a name="example3.rbhtml"></a>
-<div class="program_caption">
-File example3.rbhtml:</div>
-<pre class="program">&lt;ul&gt;
-&lt;?rb for item in items ?&gt;
-  &lt;li&gt;${item}&lt;/li&gt;
-&lt;?rb <strong>ende</strong> ?&gt;
-&lt;/ul&gt;
+
+      <p>If you specify '<code>-sb</code>' instead of '<code>-s</code>', neither preamble (= '<code>@_buf = _buf = "";</code>') nor postamble (= '<code>_buf.to_s</code>') are printed. See <a href="#command-retrieve">Retrieve Embedded Code</a> section for more information.</p>
+
+      <p>Or:</p><a name="test_021/main.rb"></a>
+
+      <div class="program_caption">
+        How to convert template file into Ruby script
+      </div>
+      <pre class="program">
+require 'tenjin'
+template = Tenjin::Template.new('views/page.rbhtml')
+puts template.script
+
+### or:
+#template = Tenjin::Template.new
+#filename = 'views/page.rbhtml'
+#print(template.convert(File.read(filename), filename))
+
+### or:
+#engine = Tenjin::Engine.new(:path=&gt;['views'])
+#print(engine.get_template('page.rbhtml').script)
+</pre><br>
+      <a name="layout-template" id="layout-template"></a>
+
+      <h3 class="section2">Layout Template</h3>
+
+      <p>Layout template will help you to use common HTML design for all pages.</p><a name="test_030/views/_layout.rbhtml"></a>
+
+      <div class="program_caption">
+        views/_layout.rbhtml
+      </div>
+      <pre class="program">
+&lt;!DOCTYPE&gt;
+&lt;html&gt;
+  &lt;head&gt;
+    &lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /&gt;
+    &lt;title&gt;${@title}&lt;/title&gt;
+  &lt;/head&gt;
+  &lt;body&gt;
+<strong>#{@_content}</strong>
+  &lt;/body&gt;
+&lt;/html&gt;
+</pre><a name="test_030/main.rb"></a>
+
+      <div class="program_caption">
+        main.rb
+      </div>
+      <pre class="program">
+require 'tenjin'
+
+## context data
+context = {
+  :title =&gt; 'Tenjin Example',
+  :items =&gt; ['&lt;AAA&gt;', 'B&amp;B', '"CCC"'],
+}
+
+## cleate engine object
+engine = Tenjin::Engine.new(:path=&gt;['views']<strong>, :layout=&gt;'_layout.rbhtml'</strong>)
+
+## render template with context data
+html = engine.render('page.rbhtml', context)
+print html
+</pre><a name="test_030/result.output"></a>
+
+      <div class="terminal_caption">
+        Result
+      </div>
+      <pre class="terminal">
+$ ruby main.rb
+&lt;!DOCTYPE&gt;
+&lt;html&gt;
+  &lt;head&gt;
+    &lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /&gt;
+    &lt;title&gt;Tenjin Example&lt;/title&gt;
+  &lt;/head&gt;
+  &lt;body&gt;
+&lt;h2&gt;Tenjin Example&lt;/h2&gt;
+&lt;table&gt;
+  &lt;tr class="odd"&gt;
+    &lt;td&gt;&amp;lt;AAA&amp;gt;&lt;/td&gt;
+  &lt;/tr&gt;
+  &lt;tr class="even"&gt;
+    &lt;td&gt;B&amp;amp;B&lt;/td&gt;
+  &lt;/tr&gt;
+  &lt;tr class="odd"&gt;
+    &lt;td&gt;&amp;quot;CCC&amp;quot;&lt;/td&gt;
+  &lt;/tr&gt;
+&lt;/table&gt;
+
+  &lt;/body&gt;
+&lt;/html&gt;
 </pre>
-<a name="example3_syntaxcheck.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ rbtenjin <strong>-wz</strong> example3.rbhtml
-example3.rbhtml:5: syntax error, unexpected $end, expecting kEND
+
+      <p>You can specify other layout template file with <code>render()</code> method.</p>
+      <pre class="program">
+## use other layout template file
+engine.render('page.rbhtml', context, <strong>'_other_layout.jshtml'</strong>)
+
+## don't use layout template file
+engine.render('page.pyhtml', context, <strong>false</strong>)
 </pre>
-<p>Command-line option '-wz' is more convenient than '<code>rbtenjin -s file | ruby -wc</code>'
-because the former can take several filenames.
-</p>
-<p>Command-line option '-q' (quiet-mode) prints nothing if it has no errors.
-</p>
-<br>
-
-
-<a name="des-contextdata"></a>
-<h3 class="section2">Context Data File</h3>
-<p>rbTenjin allows you to specify context data by YAML file or Ruby script.
-</p>
-<a name="example4.rbhtml"></a>
-<div class="program_caption">
-File 'example4.rbhtml':</div>
-<pre class="program">&lt;p&gt;
-  ${@text}
-  #{@num}
-  #{@flag}
-&lt;/p&gt;
 
+      <p>Tenjin supports nested layout template. See <a href="#nested-layout-template">Nested Layout Template</a> section for details.</p><br>
+      <a name="context-variables" id="context-variables"></a>
+
+      <h3 class="section2">Context Variables</h3>
+
+      <p>In Tenjin, Instance variables are shared between template files. If you set instance variables in a template, it is available in layout template.</p><a name="test_040/views/_layout.rbhtml"></a>
+
+      <div class="program_caption">
+        views/_layout.rbhtml
+      </div>
+      <pre class="program">
+&lt;!DOCTYPE&gt;
+&lt;html&gt;
+  &lt;head&gt;
+    &lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /&gt;
+    &lt;title&gt;<strong>${@page_title}</strong>&lt;/title&gt;
+  &lt;/head&gt;
+  &lt;body&gt;
+#{@_content}
+  &lt;/body&gt;
+&lt;/html&gt;
+</pre><a name="test_040/views/page.rbhtml"></a>
+
+      <div class="program_caption">
+        views/page.rbhtml: pass page title date from template to layout template
+      </div>
+      <pre class="program">
+<strong>&lt;?rb @page_title = 'Tenjin: Layout Template Example' ?&gt;</strong>
+&lt;h2&gt;${@title}&lt;/h2&gt;
+&lt;table&gt;
+&lt;?rb i = 0 ?&gt;
 &lt;?rb for item in @items ?&gt;
-&lt;p&gt;${item}&lt;/p&gt;
+&lt;?rb   i += 1 ?&gt;
+&lt;?rb   klass = i % 2 == 1 ? 'odd' : 'even' ?&gt;
+  &lt;tr class="#{klass}"&gt;
+    &lt;td&gt;${item}&lt;/td&gt;
+  &lt;/tr&gt;
 &lt;?rb end ?&gt;
+&lt;/table&gt;
+</pre><a name="test_040/result.output"></a>
+
+      <div class="terminal_caption">
+        Result
+      </div>
+      <pre class="terminal">
+$ ruby main.rb
+&lt;!DOCTYPE&gt;
+&lt;html&gt;
+  &lt;head&gt;
+    &lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /&gt;
+    &lt;title&gt;<strong>Tenjin: Layout Template Example</strong>&lt;/title&gt;
+  &lt;/head&gt;
+  &lt;body&gt;
+&lt;h2&gt;Tenjin Example&lt;/h2&gt;
+&lt;table&gt;
+  &lt;tr class="odd"&gt;
+    &lt;td&gt;&amp;lt;AAA&amp;gt;&lt;/td&gt;
+  &lt;/tr&gt;
+  &lt;tr class="even"&gt;
+    &lt;td&gt;B&amp;amp;B&lt;/td&gt;
+  &lt;/tr&gt;
+  &lt;tr class="odd"&gt;
+    &lt;td&gt;&amp;quot;CCC&amp;quot;&lt;/td&gt;
+  &lt;/tr&gt;
+&lt;/table&gt;
 
-&lt;?rb for key, value in @hash ?&gt;
-&lt;p&gt;#{key} = ${value}&lt;/p&gt;
+  &lt;/body&gt;
+&lt;/html&gt;
+</pre><br>
+      <a name="template-arguments" id="template-arguments"></a>
+
+      <h3 class="section2">Template Arguments</h3>
+
+      <p>For readability, it is recommended to declare context variables in your template files.</p><a name="test_050/views/page.rbhtml"></a>
+
+      <div class="program_caption">
+        views/page.rbhtml
+      </div>
+      <pre class="program">
+<strong>&lt;?rb #@ARGS title, items ?&gt;</strong>
+&lt;?rb @page_title = 'Tenjin: Layout Template Example' ?&gt;
+&lt;h2&gt;<strong>${title}</strong>&lt;/h2&gt;
+&lt;table&gt;
+&lt;?rb i = 0 ?&gt;
+&lt;?rb for item in <strong>items</strong> ?&gt;
+&lt;?rb   i += 1 ?&gt;
+&lt;?rb   klass = i % 2 == 1 ? 'odd' : 'even' ?&gt;
+  &lt;tr class="#{klass}"&gt;
+    &lt;td&gt;${item}&lt;/td&gt;
+  &lt;/tr&gt;
 &lt;?rb end ?&gt;
+&lt;/table&gt;
+</pre><a name="test_050/result.output"></a>
+
+      <div class="terminal_caption">
+        Converted Ruby script
+      </div>
+      <pre class="terminal">
+$ rbtenjin -sb views/page.rbhtml
+<strong> title = @title; items = @items;</strong>
+@page_title = 'Tenjin: Layout Template Example'
+ _buf &lt;&lt; %Q`&lt;h2&gt;#{escape((<strong>title</strong>).to_s)}&lt;/h2&gt;
+&lt;table&gt;\n`
+i = 0
+for item in <strong>items</strong>
+  i += 1
+  klass = i % 2 == 1 ? 'odd' : 'even'
+ _buf &lt;&lt; %Q`  &lt;tr class="#{klass}"&gt;
+    &lt;td&gt;#{escape((item).to_s)}&lt;/td&gt;
+  &lt;/tr&gt;\n`
+end
+ _buf &lt;&lt; %Q`&lt;/table&gt;\n`
+</pre><a name="test_051/views/_layout.rbhtml"></a>
+
+      <div class="program_caption">
+        views/_layout.rbhtml
+      </div>
+      <pre class="program">
+<strong>&lt;?rb #@ARGS _content, page_title ?&gt;</strong>
+&lt;!DOCTYPE&gt;
+&lt;html&gt;
+  &lt;head&gt;
+    &lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /&gt;
+    &lt;title&gt;${@page_title}&lt;/title&gt;
+  &lt;/head&gt;
+  &lt;body&gt;
+#{@_content}
+  &lt;/body&gt;
+&lt;/html&gt;
+</pre><a name="test_051/result.output"></a>
+
+      <div class="terminal_caption">
+        Converted Ruby script
+      </div>
+      <pre class="terminal">
+$ rbtenjin -sb views/_layout.rbhtml
+<strong> _content = @_content; page_title = @page_title;</strong>
+ _buf &lt;&lt; %Q`&lt;!DOCTYPE&gt;
+&lt;html&gt;
+  &lt;head&gt;
+    &lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /&gt;
+    &lt;title&gt;#{escape((@page_title).to_s)}&lt;/title&gt;
+  &lt;/head&gt;
+  &lt;body&gt;
+#{@_content}
+  &lt;/body&gt;
+&lt;/html&gt;\n`
+</pre><br>
+      <a name="partial-template" id="partial-template"></a>
+
+      <h3 class="section2">Include Partial Template</h3>
+
+      <p>You can include other template files by <code>import()</code> helper method.</p>
+
+      <dl class="dl1">
+        <dt class="dt1">import(<em>template-name</em>)</dt>
+
+        <dd class="dd1">Import other template. <em>template-name</em> can be file name or template short name.</dd>
+      </dl>
+
+      <p>In the following example, layout template includes header and footer templates into it.</p><a name="test_060/views/_layout.rbhtml"></a>
+
+      <div class="program_caption">
+        views/_layout.rbhtml
+      </div>
+      <pre class="program">
+&lt;?rb #@ARGS _content, page_title ?&gt;
+&lt;!DOCTYPE&gt;
+&lt;html&gt;
+  &lt;head&gt;
+    &lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /&gt;
+    &lt;title&gt;${@page_title}&lt;/title&gt;
+  &lt;/head&gt;
+  &lt;body&gt;
+<strong>&lt;?rb import('_header.rbhtml') ?&gt;</strong>
+#{@_content}
+<strong>&lt;?rb import('_footer.rbhtml') ?&gt;</strong>
+  &lt;/body&gt;
+&lt;/html&gt;
+</pre><a name="test_060/views/_header.rbhtml"></a>
+
+      <div class="program_caption">
+        views/_header.rbhtml
+      </div>
+      <pre class="program">
+<strong>&lt;div class="header"&gt;</strong>
+  <strong>&lt;h1&gt;${@page_title}&lt;/h1&gt;</strong>
+<strong>&lt;/div&gt;</strong>
+</pre><a name="test_060/views/_footer.rbhtml"></a>
+
+      <div class="program_caption">
+        views/_footer.rbhtml
+      </div>
+      <pre class="program">
+<strong>&lt;address&gt;</strong>
+  <strong>copyright(c) 2010 kuwata-lab.com all rights reserved</strong>
+<strong>&lt;/address&gt;</strong>
 </pre>
-<a name="datafile.yaml"></a>
-<div class="program_caption">
-File 'datafile.yaml':</div>
-<pre class="program">text:   foo
-num:    3.14
-flag:   yes
-items:
-  - foo
-  - bar
-  - baz
-hash:
-  x: 1
-  y: 2
+
+      <p>Output result shows that header and footer templates are included as you expect.</p><a name="test_060/result.output"></a>
+
+      <div class="terminal_caption">
+        Result
+      </div>
+      <pre class="terminal">
+$ ruby main.rb
+&lt;!DOCTYPE&gt;
+&lt;html&gt;
+  &lt;head&gt;
+    &lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /&gt;
+    &lt;title&gt;Tenjin: Layout Template Example&lt;/title&gt;
+  &lt;/head&gt;
+  &lt;body&gt;
+<strong>&lt;div class="header"&gt;</strong>
+  <strong>&lt;h1&gt;Tenjin: Layout Template Example&lt;/h1&gt;</strong>
+<strong>&lt;/div&gt;</strong>
+&lt;h2&gt;Tenjin Example&lt;/h2&gt;
+&lt;table&gt;
+  &lt;tr class="odd"&gt;
+    &lt;td&gt;&amp;lt;AAA&amp;gt;&lt;/td&gt;
+  &lt;/tr&gt;
+  &lt;tr class="even"&gt;
+    &lt;td&gt;B&amp;amp;B&lt;/td&gt;
+  &lt;/tr&gt;
+  &lt;tr class="odd"&gt;
+    &lt;td&gt;&amp;quot;CCC&amp;quot;&lt;/td&gt;
+  &lt;/tr&gt;
+&lt;/table&gt;
+
+<strong>&lt;address&gt;</strong>
+  <strong>copyright(c) 2010 kuwata-lab.com all rights reserved</strong>
+<strong>&lt;/address&gt;</strong>
+  &lt;/body&gt;
+&lt;/html&gt;
+</pre><br>
+      <a name="template-short-name" id="template-short-name"></a>
+
+      <h3 class="section2">Template Short Name</h3>
+
+      <p>If you set template postfix, you can specify template by short name such as '<code>:page</code>' instead of '<code>page.rbhtml</code>'. Notice that template short name should be Symbol.</p><a name="test_070/main.rb"></a>
+
+      <div class="program_caption">
+        main.rb
+      </div>
+      <pre class="program">
+require 'tenjin'
+
+## context data
+context = {
+  :title =&gt; 'Tenjin Example',
+  :items =&gt; ['&lt;AAA&gt;', 'B&amp;B', '"CCC"'],
+}
+
+## cleate engine object
+engine = Tenjin::Engine.new(:path=&gt;['views'], <strong>:postfix=&gt;'.rbhtml'</strong>, :layout=&gt;<strong>:_layout</strong>)
+
+## render template with context data
+html = engine.render(<strong>:page</strong>, context)
+puts html
+</pre><a name="test_070/views/_layout.rbhtml"></a>
+
+      <div class="program_caption">
+        views/_layout.rbhtml
+      </div>
+      <pre class="program">
+&lt;?rb #@ARGS _content, page_title ?&gt;
+&lt;!DOCTYPE&gt;
+&lt;html&gt;
+  &lt;head&gt;
+    &lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /&gt;
+    &lt;title&gt;${@page_title}&lt;/title&gt;
+  &lt;/head&gt;
+  &lt;body&gt;
+&lt;?rb import(<strong>:_header</strong>) ?&gt;
+#{@_content}
+&lt;?rb import(<strong>:_footer</strong>) ?&gt;
+  &lt;/body&gt;
+&lt;/html&gt;
+</pre><br>
+      <a name="helper-functions" id="helper-functions"></a>
+
+      <h3 class="section2">Helper Function</h3>
+
+      <p>Tenjin provides some helper methods.</p>
+
+      <div class="tips"><span class="caption">TIPS:</span>
+
+      <p>These are defined in helper modules. If you want use them in your class, just include them.</p>
+      <pre class="program">
+class FooController &lt; Controller
+  <strong>include Tenjin::ContextHelper</strong>
+  <strong>include Tenjin::HtmlHelper</strong>
+  <strong>include Tenjin::HtmlTagHelper</strong>
+  <strong>include Tenjin::SafeHelper</strong>
+
+  @@engine = Tenjin::Engine.new(:path=&gt;'views', :postfix=&gt;'.rbhtml', :layout=&gt;:_layout)
+
+  def index()
+    @title = "Tenjin Example"
+    @items = ["AAA", "BBB", "CCC"]
+    html = @@engine.render(:index, <strong>self</strong>)
+    return html
+  end
+
+end
 </pre>
-<a name="example4_yaml.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ rbtenjin <strong>-f datafile.yaml</strong> example4.rbhtml
-&lt;p&gt;
-  foo
-  3.14
-  true
-&lt;/p&gt;
 
-&lt;p&gt;foo&lt;/p&gt;
-&lt;p&gt;bar&lt;/p&gt;
-&lt;p&gt;baz&lt;/p&gt;
+      </div><a name="Tenjin::ContextHelper" id="Tenjin::ContextHelper"></a>
+
+      <h4 class="section3">Tenjin::ContextHelper</h4>
+
+      <dl class="dl1">
+        <dt class="dt1">import(template_name, _append_to_buf=true)</dt>
+
+        <dd class="dd1">Include other template. 'template_name' can be filename or short name. See <a href="#partial-template">Include Partial Template</a> section for details.</dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">echo(value)</dt>
+
+        <dd class="dd1">Add value into _buf. This is equivarent to '#{value}'.</dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">start_capture(name=nil, &amp;block)</dt>
+
+        <dd class="dd1">
+          start capturing. returns captured string if block given, else return nil. if block is not given, calling stop_capture() is required. See <a href="#capturing">Capturing</a> section for details.
+
+          <div class="program_caption">
+            ex. list.rbhtml
+          </div>
+          <pre class="program">
+&lt;html&gt;&lt;body&gt;
+  &lt;h1&gt;<strong>&lt;?rb start_capture(:title) do ?&gt;</strong>Document Title<strong>&lt;?rb end ?&gt;</strong>&lt;/h1&gt;
+  <strong>&lt;?rb start_capture(:content) ?&gt;</strong>
+  &lt;ul&gt;
+   &lt;?rb for item in list do ?&gt;
+    &lt;li&gt;${item}&lt;/li&gt;
+   &lt;?rb end ?&gt;
+  &lt;/ul&gt;
+  <strong>&lt;?rb stop_capture() ?&gt;</strong>
+&lt;/body&gt;&lt;/html&gt;
+</pre>
+
+          <div class="program_caption">
+            ex. layout.rbhtml
+          </div>
+          <pre class="program">
+&lt;?xml version="1.0" ?&gt;
+&lt;html xml:lang="en"&gt;
+ &lt;head&gt;
+  &lt;title&gt;${<strong>@title</strong>}&lt;/title&gt;
+ &lt;/head&gt;
+ &lt;body&gt;
+  &lt;h1&gt;${<strong>@title</strong>}&lt;/h1&gt;
+  &lt;div id="content"&gt;
+   &lt;?rb echo(<strong>@content</strong>) ?&gt;
+  &lt;/div&gt;
+ &lt;/body&gt;
+&lt;/html&gt;
+</pre>
+        </dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">stop_capture(store_to_context=true)</dt>
+
+        <dd class="dd1">Stop capturing. Returns captured string. Necessary only when start_capture() doesn't take a block.</dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">captured_as(name)</dt>
 
-&lt;p&gt;x = 1&lt;/p&gt;
-&lt;p&gt;y = 2&lt;/p&gt;
+        <dd class="dd1">
+          If captured string is found then add it to _buf and return true, else return false. This is a helper method for layout template. See <a href="#capturing">Capturing</a> section for details.
+          <pre class="program">
+&lt;?py ## layout template example ?&gt;
+&lt;html&gt;
+&lt;body&gt;
+  &lt;div id="main"&gt;
+  &lt;?rb ## if captured by 'start_capture(:main)', use it. ?&gt;
+  &lt;?rb ## if not captured, use this block. ?&gt;
+  &lt;?rb if not captured_as(:main) ?&gt;
+    &lt;p&gt;content not found&lt;/p&gt;
+  &lt;?rb end ?&gt;
+  &lt;/div&gt;
+&lt;/body&gt;
+&lt;/html
 </pre>
-<a name="datafile.rb"></a>
-<div class="program_caption">
-File 'datafile.rb':</div>
-<pre class="program">@text  = "foo"
-@num   = 3.14
-@flag  = true
-@items = ["foo", "bar", "baz"]
-@hash  = {:x=&gt;1, :y=&gt;2}
+        </dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">_p(str)</dt>
+
+        <dd class="dd1">See <a href="#preprocessing">Preprocessing</a> section.</dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">_P(str)</dt>
+
+        <dd class="dd1">See <a href="#preprocessing">Preprocessing</a> section.</dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">cache_with(key, lifetime=nil)</dt>
+
+        <dd class="dd1">Cache html fragment. See <a href="#fragment-cache">Fragment Cache</a> section for details.</dd>
+      </dl><br>
+      <a name="Tenjin::HtmlHelper" id="Tenjin::HtmlHelper"></a>
+
+      <h4 class="section3">Tenjin::HtmlHelper</h4>
+
+      <dl class="dl1">
+        <dt class="dt1">escape_html(str)</dt>
+
+        <dd class="dd1">Alias to escape_html().</dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">escape_xml(str)</dt>
+
+        <dd class="dd1">Escape '&amp;', '&lt;', '&gt;', and '"' into '&amp;amp;', '&amp;lt;', '&amp;gt;', and '&amp;quot;' respectively.</dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">escape_html(str)</dt>
+
+        <dd class="dd1">Similar to escape_xml(), but much faster when str contains a lot of '&amp;&lt;&gt;"' characters.</dd>
+      </dl><br>
+      <a name="Tenjin::SafeHelper" id="Tenjin::SafeHelper"></a>
+
+      <h4 class="section3">Tenjin::SafeHelper</h4>
+
+      <dl class="dl1">
+        <dt class="dt1">safe_str(str)</dt>
+
+        <dd class="dd1">Return SafeString object. See <a href="#safe-template">Safe Template</a> section for details.</dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">safe_str?(str)</dt>
+
+        <dd class="dd1">Return true if s is SafeString object. See <a href="#safe-template">Safe Template</a> section for details.</dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">safe_escape(str)</dt>
+
+        <dd class="dd1">Escape str only if val str not SafeString object, and return SafeString object. See <a href="#safe-template">Safe Template</a> section for details.</dd>
+      </dl><br>
+      <a name="Tenjin::HtmlTagHelper" id="Tenjin::HtmlTagHelper"></a>
+
+      <h4 class="section3">Tenjin::HtmlTagHelper</h4>
+
+      <dl class="dl1">
+        <dt class="dt1">checked(value)</dt>
+
+        <dd class="dd1">
+          Return ' checked="checked" if value is true.
+          <pre class="program">
+value = "1"
+checked(value=="1")  #=&gt; ' checked="checked"'
+checked(value=="0")  #=&gt; ''
 </pre>
-<a name="example4_datafile_rb.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ rbtenjin <strong>-f datafile.rb</strong> example4.rbhtml
-&lt;p&gt;
-  foo
-  3.14
-  true
-&lt;/p&gt;
+        </dd>
+      </dl>
 
-&lt;p&gt;foo&lt;/p&gt;
-&lt;p&gt;bar&lt;/p&gt;
-&lt;p&gt;baz&lt;/p&gt;
+      <dl class="dl1">
+        <dt class="dt1">selected(value)</dt>
 
-&lt;p&gt;x = 1&lt;/p&gt;
-&lt;p&gt;y = 2&lt;/p&gt;
+        <dd class="dd1">
+          Return ' selected="selected" if value is true.
+          <pre class="program">
+value = "1"
+selected(value=="1")  #=&gt; ' selected="selected"'
+selected(value=="0")  #=&gt; ''
 </pre>
-<br>
+        </dd>
+      </dl>
 
+      <dl class="dl1">
+        <dt class="dt1">disabled(value)</dt>
 
-<a name="des-cmlinecontext"></a>
-<h3 class="section2">Command-line Context Data</h3>
-<p>Command-line option '<code>-c</code>' specifies context data in YAML format or Ruby code.
-</p>
-<a name="example5.rbhtml"></a>
-<div class="program_caption">
-File 'example5.rbhtml':</div>
-<pre class="program">text:  #{@text}
-items:
-&lt;?rb for item in @items ?&gt;
-  - #{item}
-&lt;?rb end ?&gt;
-hash:
-&lt;?rb for key, val in @hash ?&gt;
-  #{key}: #{val}
-&lt;?rb end ?&gt;
+        <dd class="dd1">
+          Return ' disabled="disabled"' if value is true.
+          <pre class="program">
+value = "1"
+disabled(value=="1")  #=&gt; ' disabled="disabled"'
+disabled(value=="0")  #=&gt; ''
 </pre>
-<a name="example5_datastr_rb.result"></a>
-<div class="terminal_caption">
-Result of context data in ruby code:</div>
-<pre class="terminal">$ rbtenjin <strong>-c '@text="foo"; @items=%w[a b c]; @hash={"x"=&gt;1,"y"=&gt;2}'</strong> example5.rbhtml
-text:  foo
-items:
-  - a
-  - b
-  - c
-hash:
-  x: 1
-  y: 2
+        </dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">tagattr(name, expr, value=nil, escape=true)</dt>
+
+        <dd class="dd1">
+          (experimental) Return ' name="value"' if expr is not false nor nil. If value is nil or false then expr is used as value.
+          <pre class="program">
+tagattr('name', 'val')  #=&gt; ' name="val"'
+tagattr('name', nil)    #=&gt; ''
+urlpath = "/blog/"
+tagattr('class', urlpath=='/blog/', 'current')  #=&gt; ' class="current"'
+tagattr('class', urlpath=='/',      'current')  #=&gt; ''
 </pre>
-<a name="example5_datastr_yaml.result"></a>
-<div class="terminal_caption">
-Result of context data in yaml format:</div>
-<pre class="terminal">$ rbtenjin <strong>-c '{text: foo, items: [a, b, c], hash: {x: 1, y: 2} }'</strong> example5.rbhtml
-text:  foo
-items:
-  - a
-  - b
-  - c
-hash:
-  x: 1
-  y: 2
+        </dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">nv(name, value, separator=nil):</dt>
+
+        <dd class="dd1">
+          Return 'name="name" value="value"' string. If separator is specfied, id attribute is added.
+          <pre class="program">
+nv('user', 'guest');       #=&gt; ' name="user" value="guest"'
+nv('user', 'guest', '-');  #=&gt; ' name="user" value="guest" id="user-guest"'
 </pre>
-<br>
-
-
-<a name="des-nested-template"></a>
-<h3 class="section2">Nested Template</h3>
-<p>Template can include other templates.
-Included templates can also include other templates.
-</p>
-<p>The following function is available to include other templates.
-</p>
-<dl class="dl3">
-<dt class="dt3"><b>
-import(template_name) </b></dt>
-<dd class="dd3">
-    Include other template.
-</dd>
-</dl>
-<a name="example6.rbhtml"></a>
-<div class="program_caption">
-File 'example6.rbhtml':</div>
-<pre class="program">&lt;html&gt;
-  &lt;body&gt;
+        </dd>
+      </dl>
 
-    &lt;div id="sidemenu"&gt;
-<strong>&lt;?rb import 'sidemenu.rbhtml' ?&gt;</strong>
-    &lt;/div&gt;
+      <dl class="dl1">
+        <dt class="dt1">js_link(label, onclick, tags={}):</dt>
 
-    &lt;div id="main-content"&gt;
-&lt;?rb for item in @items ?&gt;
-      &lt;p&gt;${item}&lt;/p&gt;
-&lt;?rb end ?&gt;
-    &lt;/div&gt;
+        <dd class="dd1">
+          Return '&lt;a href="" onclick="onclick"&gt;label&lt;/a&gt;' string.
+          <pre class="program">
+js_link('Show', '$().show()')
+    #=&gt; '&lt;a href="javascript:undefined" onclick="$().show();return false"&gt;Show&lt;/a&gt;'
+js_link('Show', '$().show()', :class=&gt;"link")
+    #=&gt; '&lt;a href="javascript:undefined" onclick="$().show();return false" class="link"&gt;Show&lt;/a&gt;'
+</pre>
+        </dd>
+      </dl>
 
-    &lt;div id="footer"&gt;
-<strong>#{import 'footer.rbhtml', false}</strong>
-    &lt;/div&gt;
+      <dl class="dl1">
+        <dt class="dt1">nl2br(text)</dt>
 
-  &lt;/body&gt;
-&lt;/table&gt;
+        <dd class="dd1">
+          Convert "\n" into "&lt;br /&gt;\n".
+          <pre class="program">
+nl2br("foo\nbar\n")  #=&gt; "foo&lt;br /&gt;\nbar&lt;br /&gt;\n"
 </pre>
-<a name="sidemenu.rbhtml"></a>
-<div class="program_caption">
-File 'sidemenu.rbhtml':</div>
-<pre class="program">&lt;ul&gt;
-&lt;?rb for item in @menu ?&gt;
-  &lt;li&gt;&lt;a href="${item['url']}"&gt;${item['name']}&lt;/a&gt;&lt;/li&gt;
-&lt;?rb end ?&gt;
-&lt;/ul&gt;
+        </dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">text2html(text)</dt>
+
+        <dd class="dd1">
+          Convert "\n" and " " into "&lt;br /&gt;\n" and " &amp;nbsp;".
+          <pre class="program">
+text2html("  foo\n  bar\n")  #=&gt; " &amp;nbsp;foo&lt;br /&gt;\n &amp;nbsp;bar&lt;br /&gt;\n"
 </pre>
-<a name="footer.rbhtml"></a>
-<div class="program_caption">
-File 'footer.rbhtml':</div>
-<pre class="program">&lt;hr /&gt;
-&lt;address&gt;
-  &lt;a href="mailto:${@webmaster_email}"&gt;${@webmaster_email}&lt;/a&gt;
-&lt;/address&gt;
+        </dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">new_cycle(*values)</dt>
+
+        <dd class="dd1">
+          Return Cycle object.
+          <pre class="program">
+cycle = new_cycle('odd', 'even')
+"#{cycle}"   #=&gt; 'odd'
+"#{cycle}"   #=&gt; 'even'
+"#{cycle}"   #=&gt; 'odd'
 </pre>
-<a name="contextdata.rb"></a>
-<div class="program_caption">
-File 'contextdata.rb':</div>
-<pre class="program">@items = [ '&lt;FOO&gt;', '&amp;BAR', '"BAZ"' ]
-@webmaster_email = 'webmaster@example.com'
-@menu  = [
-    {'name'=&gt; 'Top',      'url'=&gt; '/' },
-    {'name'=&gt; 'Products', 'url'=&gt; '/prod' },
-    {'name'=&gt; 'Support',  'url'=&gt; '/support' },
-]
+        </dd>
+      </dl><br>
+      <br>
+      <br>
+      <a name="advanced-features" id="advanced-features"></a>
+
+      <h2 class="section1">Advanced Features</h2><a name="safe-template" id="safe-template"></a>
+
+      <h3 class="section2">Safe Template</h3>
+
+      <p><span style="color:#FF0000">(EXPERIMENTAL)</span></p>
+
+      <p>Tenjin provides <code>SafeTemplate</code> and <code>SafeEngine</code> class which enforces HTML escape. These are similar to Django's feature or Jinja2's autoescape feature.</p>
+
+      <p>The point of these classes is that <strong>you can control whether escape html or not by data type, not by embedded notation</strong>.</p>
+
+      <p>See the following example.</p><a name="test_safe/safe-test.rb"></a>
+
+      <div class="program_caption">
+        safe-test.rb
+      </div>
+      <pre class="program">
+require 'tenjin'
+<strong>include Tenjin::HtmlHelper</strong>   # defines escape()
+<strong>include Tenjin::SafeHelper</strong>   # defines safe_escape(), safe_str(), safe_str?()
+
+## both are same notation
+input = &lt;&lt;END
+s1 = <strong>${@s1}</strong>
+s2 = <strong>${@s2}</strong>
+END
+
+## but passed different data type
+context = {
+  :s1 =&gt; "&lt;b&gt;SOS&lt;/b&gt;",
+  :s2 =&gt; <strong>safe_str</strong>("&lt;b&gt;SOS&lt;/b&gt;"),
+}
+
+## SafeTemplate will escape 's1' but not 's2'
+template = <strong>Tenjin::SafeTemplate</strong>.new(:input=&gt;input)
+print(template.script)
+print("---------------------\n")
+print(template.render(context))
 </pre>
-<a name="example6_nested.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ rbtenjin -f contextdata.rb example6.rbhtml
-&lt;html&gt;
-  &lt;body&gt;
 
-    &lt;div id="sidemenu"&gt;
-<strong>&lt;ul&gt;</strong>
-  <strong>&lt;li&gt;&lt;a href="/"&gt;Top&lt;/a&gt;&lt;/li&gt;</strong>
-  <strong>&lt;li&gt;&lt;a href="/prod"&gt;Products&lt;/a&gt;&lt;/li&gt;</strong>
-  <strong>&lt;li&gt;&lt;a href="/support"&gt;Support&lt;/a&gt;&lt;/li&gt;</strong>
-<strong>&lt;/ul&gt;</strong>
-    &lt;/div&gt;
+      <p>The follwoing output shows that:</p>
 
-    &lt;div id="main-content"&gt;
-      &lt;p&gt;&amp;lt;FOO&amp;gt;&lt;/p&gt;
-      &lt;p&gt;&amp;amp;BAR&lt;/p&gt;
-      &lt;p&gt;&amp;quot;BAZ&amp;quot;&lt;/p&gt;
-    &lt;/div&gt;
+      <ul type="disc">
+        <li><code>SafeTemplate</code> and <code>SafeEngine</code> classes uses <code>safe_escape()</code> instead of <code>escape()</code> to escape value.</li>
 
-    &lt;div id="footer"&gt;
-<strong>&lt;hr /&gt;</strong>
-<strong>&lt;address&gt;</strong>
-<strong>  &lt;a href="mailto:webmaster@example.com"&gt;webmaster@example.com&lt;/a&gt;</strong>
-<strong>&lt;/address&gt;</strong>
+        <li>Normal string (= <code>"&lt;b&gt;SOS&lt;/b&gt;"</code>) is escaped automatically, but the other string which is marked as escaped (= <code>safe_str("&lt;b&gt;SOS&lt;/b&gt;")</code>) is not escaped. This means that you can controll escape by data type, not embedded notation.</li>
+      </ul><a name="test_safe/result.output"></a>
 
-    &lt;/div&gt;
+      <div class="terminal_caption">
+        Output example
+      </div>
+      <pre class="terminal">
+$ ruby safe-test.rb
+ _buf &lt;&lt; %Q`s1 = #{<strong>safe_escape</strong>((@s1).to_s)}
+s2 = #{<strong>safe_escape</strong>((@s2).to_s)}\n`
+---------------------
+s1 = &amp;lt;b&amp;gt;SOS&amp;lt;/b&amp;gt;
+s2 = <strong>&lt;b&gt;SOS&lt;/b&gt;</strong>
+</pre>
+
+      <p>In addition, <code>SafeTemplate</code>/<code>SafeEngine</code> classes inhibits <code>#{...}</code> because some people mistake it with <code>${...}</code> and it can be XSS security hole in the result. Use <code>${...}</code> in each case.</p>
+      <pre class="program">
+#{@value}    # Not available with SafeTemplate/SafeEngine!
+${@value}    # Use this in each case.
+</pre>
+
+      <div class="tips"><span class="caption">TIPS:</span>
+
+      <p>Implementation of SafeTemplate and SafeEngine is very small. In other words, it is easy to implement your own SafeTemplate/SafeEngine class. See source code of Tenjin for details.</p>
+
+      </div>
+
+      <p>There are three helper methods defined in Tenjin::SafeHelper.</p>
+
+      <dl class="dl1">
+        <dt class="dt1">safe_escape(str)</dt>
+
+        <dd class="dd1">
+          <ul type="circle">
+            <li>If str is normal String, escape it and return SafeString object.</li>
+
+            <li>If str is SafeString object, just return it.</li>
+          </ul>
+        </dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">safe_str(str)</dt>
 
+        <dd class="dd1">
+          <ul type="circle">
+            <li>If str is normal String, return SafeString object WITHOUT escaping.</li>
+
+            <li>If str is SafeString object, just return it.</li>
+          </ul>
+        </dd>
+      </dl>
+
+      <dl class="dl1">
+        <dt class="dt1">safe_str?(str)</dt>
+
+        <dd class="dd1">
+          <ul type="circle">
+            <li>If str is normla String, return false.</li>
+
+            <li>If str is SafeString object, return true.</li>
+          </ul>
+        </dd>
+      </dl><a name="test_safehelper/main.rb"></a>
+
+      <div class="program_caption">
+        Example of safe helpers
+      </div>
+      <pre class="program">
+require 'tenjin'
+include Tenjin::HtmlHelper
+include Tenjin::SafeHelper
+#
+s = "&lt;AAA&gt;"
+puts safe_str?(s)     #=&gt; false
+s = safe_escape(s)    # same as SafeString.new(escape(s))
+puts safe_str?(s)     #=&gt; true
+puts s                #=&gt; &amp;lt;AAA&amp;gt;
+puts safe_escape(s)   #=&gt; &amp;lt;AAA&amp;gt;
+#
+s = "&lt;AAA&gt;"
+s = safe_str(s)       # same as SafeString.new(s)
+puts safe_str?(s)     #=&gt; true
+puts s                #=&gt; &lt;AAA&gt;
+puts safe_escape(s)   #=&gt; &lt;AAA&gt;
+</pre><br>
+      <a name="nested-layout-template" id="nested-layout-template"></a>
+
+      <h3 class="section2">Nested Layout Template</h3>
+
+      <p>It is able to nest several layout template files.</p><a name="test_nested/views/_site_layout.rbhtml"></a>
+
+      <div class="program_caption">
+        views/_site_layout.rbhtml
+      </div>
+      <pre class="program">
+&lt;html&gt;
+  &lt;body&gt;
+<strong>#{@_content}</strong>
   &lt;/body&gt;
-&lt;/table&gt;
+&lt;/html&gt;
+</pre><a name="test_nested/views/_blog_layout.rbhtml"></a>
+
+      <div class="program_caption">
+        views/_blog_layout.rbhtml
+      </div>
+      <pre class="program">
+<strong>&lt;?rb @_layout = '_site_layout.rbhtml' ?&gt;</strong>
+&lt;h2&gt;${@title}&lt;/h2&gt;
+&lt;!-- content --&gt;
+<strong>#{@_content}</strong>
+&lt;!-- /content --&gt;
+</pre><a name="test_nested/views/blog_post.rbhtml"></a>
+
+      <div class="program_caption">
+        views/blog_post.rbhtml
+      </div>
+      <pre class="program">
+<strong>&lt;?rb @_layout = '_blog_layout.rbhtml' ?&gt;</strong>
+&lt;div class="article"&gt;
+#{text2html(@post_content)}
+&lt;/div&gt;
+</pre><a name="test_nested/main.rb"></a>
+
+      <div class="program_caption">
+        main.rb
+      </div>
+      <pre class="program">
+require 'tenjin'
+engine = Tenjin::Engine.new(:path=&gt;['views'])
+context = {
+  :title =&gt; 'Blog Post Test',
+  :post_content =&gt; "Foo\nBar\nBaz",
+}
+html = engine.render('blog_post.rbhtml', context)
+print(html)
+</pre><a name="test_nested/result.output"></a>
+
+      <div class="terminal_caption">
+        Result
+      </div>
+      <pre class="terminal">
+$ ruby main.rb
+&lt;html&gt;                        # by _layout.rbhtml
+  &lt;body&gt;                      #       :
+&lt;h2&gt;Blog Post Test&lt;/h2&gt;       #   by _blog_layout.rbhtml
+&lt;!-- content --&gt;              #         :
+&lt;div class="article"&gt;         #     by blog_post.rbhtml
+Foo&lt;br /&gt;                     #           :
+Bar&lt;br /&gt;                     #           :
+Baz                           #           :
+&lt;/div&gt;                        #           :
+                              #           :
+&lt;!-- /content --&gt;             #   by _blog_layout.rbhtml
+                              #         :
+  &lt;/body&gt;                     # by _layout.rbhtml
+&lt;/html&gt;                       #       :
+</pre><br>
+      <a name="trace" id="trace"></a>
+
+      <h3 class="section2">Trace Templates</h3>
+
+      <p>If you pass '<code>:trace=&gt;true</code>' to Tenjin::Template class or Tenjin::Engine class, Template class will print template file name at the beginning and end of output.</p>
+
+      <p>For example:</p><a name="test_trace/trace-example.rb"></a>
+
+      <div class="program_caption">
+        trace-example.rb
+      </div>
+      <pre class="program">
+require 'tenjin'
+engine = Tenjin::Engine.new(:layout=&gt;'layout.rbhtml', <strong>:trace=&gt;true</strong>)
+output = engine.render('main.rbhtml', {'items'=&gt;['A','B','C']})
+puts output
 </pre>
-<p>Function '<code>import()</code>' can take template filename
-(ex. 'user_main.rbhtml') or template short name (ex. :main).
-Template short name is a Symbol.
-</p>
-<p>To make template short name available, command-line option '<code>--prefix</code>' and
-'<code>--postfix</code>' are required.
-For example, '<code>include("user_main.rbhtml")</code>' can be described as '<code>include(:main)</code>'
-when '<code>--prefix="user_"</code>' and '<code>--postfix=".rbhtml"</code>' are specified in command-line.
-</p>
-<br>
-
-
-<a name="des-layout"></a>
-<h3 class="section2">Layout Template</h3>
-<p>Command-line option '<code>--layout=templatename</code>' specifies layout template name.
-</p>
-<p>For example, 'exmample6.rbhtml' template in the previous section can be divided
-into layout file 'layout6.rbhtml' and content file 'content6.rbhtml'.
-Variable '<code>@_content</code>' in layout template represents the result of content file.
-</p>
-<a name="layout6.rbhtml"></a>
-<div class="program_caption">
-File 'layout6.rbhtml':</div>
-<pre class="program">&lt;html&gt;
+
+      <p>Will print:</p><a name="test_trace/result.output"></a>
+      <pre class="terminal">
+$ ruby trace-example.rb
+<strong>&lt;!-- ***** begin: layout.rbhtml ***** --&gt;</strong>
+&lt;html&gt;
   &lt;body&gt;
+    &lt;div class="content"&gt;
+<strong>&lt;!-- ***** begin: main.rbhtml ***** --&gt;</strong>
+&lt;ul&gt;
+  &lt;li&gt;A&lt;/li&gt;
+  &lt;li&gt;B&lt;/li&gt;
+  &lt;li&gt;C&lt;/li&gt;
+&lt;/ul&gt;
+<strong>&lt;!-- ***** end: main.rbhtml ***** --&gt;</strong>
+    &lt;/div&gt;
+  &lt;/body&gt;
+&lt;/html&gt;
+<strong>&lt;!-- ***** end: layout.rbhtml ***** --&gt;</strong>
+</pre>
+
+      <p>This feature is very useful when debugging to detect template file name from HTML output.</p>
 
-    &lt;div id="sidemenu"&gt;
-&lt;?rb import 'sidemenu.rbhtml' ?&gt;
+      <p>If you like it, you can make it always enabled.</p>
+      <pre class="program">
+## trace is always enabled
+Tenjin::Engine.TRACE = true
+</pre><br>
+      <a name="capturing" id="capturing"></a>
+
+      <h3 class="section2">Capturing</h3>
+
+      <p>It is able to capture parital of output. You can use this feature as an alternative of Django's template-inheritance.</p><a name="test_capturing/views/blog-post.rbhtml"></a>
+
+      <div class="program_caption">
+        views/blog-post.rbhtml : one partial capture ('sidebar')
+      </div>
+      <pre class="program">
+&lt;h2&gt;#{@blog_post[:title]}&lt;/h2&gt;
+&lt;div class="blog-post"&gt;
+#{text2html(@blog_post[:content])}
+&lt;/div&gt;
+
+<strong>&lt;?rb start_capture('sidebar') do ?&gt;</strong>
+&lt;h3&gt;Recent Posts&lt;/h3&gt;
+&lt;ul&gt;
+&lt;?rb for post in @recent_posts ?&gt;
+  &lt;a href="/blog/#{post[:id]}"&gt;${post[:title]}&lt;/a&gt;
+&lt;?rb end ?&gt;
+&lt;/ul&gt;
+<strong>&lt;?rb end ?&gt;</strong>
+</pre><a name="test_capturing/views/_layout.rbhtml"></a>
+
+      <div class="program_caption">
+        views/_layout.rbhtml : two placeholders ('header' and 'sidebar')
+      </div>
+      <pre class="program">
+&lt;html&gt;
+  &lt;body&gt;
+    &lt;div id="header-part"&gt;
+    <strong>&lt;?rb if ! captured_as(:header) ?&gt;</strong>
+      &lt;h1&gt;My Great Blog&lt;/h1&gt;
+    <strong>&lt;?rb end ?&gt;</strong>
     &lt;/div&gt;
-
     &lt;div id="main-content"&gt;
-<strong>#{@_content}</strong>
+#{@_content}
     &lt;/div&gt;
-
-    &lt;div id="footer"&gt;
-#{import 'footer.rbhtml', false}
+    &lt;div id="sidebar-part"&gt;
+    <strong>&lt;?rb if ! captured_as(:sidebar) ?&gt;</strong>
+      &lt;h3&gt;Links&lt;/h3&gt;
+      &lt;ul&gt;
+        &lt;a href="http://google.com/"&gt;Google&lt;/a&gt;
+        &lt;a href="http://yahoo.com/"&gt;Yahoo!&lt;/a&gt;
+      &lt;/ul&gt;
+    <strong>&lt;?rb end ?&gt;</strong>
     &lt;/div&gt;
-
   &lt;/body&gt;
-&lt;/table&gt;
-</pre>
-<a name="content6.rbhtml"></a>
-<div class="program_caption">
-File 'content6.rbhtml':</div>
-<pre class="program">&lt;?rb for item in @items ?&gt;
-  &lt;p&gt;${item}&lt;/p&gt;
-&lt;?rb end ?&gt;
+&lt;/html&gt;
+</pre><a name="test_capturing/main.rb"></a>
+
+      <div class="program_caption">
+        main.rb
+      </div>
+      <pre class="program">
+## context data
+post_content = &lt;&lt;END
+Tenjin has great features.
+- Very Fast
+- Full Featured
+- Easy to Use
+END
+context = {
+  :blog_post =&gt; {
+    :title   =&gt; 'Tenjin is Great',
+    :content =&gt; post_content,
+  },
+  :recent_posts =&gt; [
+    {:id=&gt;1, :title=&gt;'Tenjin is Fast' },
+    {:id=&gt;2, :title=&gt;'Tenjin is Full-Featured' },
+    {:id=&gt;3, :title=&gt;'Tenjin is Easy-to-Use' },
+  ]
+}
+
+## render template
+require 'tenjin'
+engine = Tenjin::Engine.new(:path=&gt;['views'], :layout=&gt;'_layout.rbhtml')
+html = engine.render('blog-post.rbhtml', context)
+puts html
 </pre>
-<a name="example6_layout.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ rbtenjin -f contextdata.rb <strong>--layout=layout6.rbhtml</strong> content6.rbhtml
+
+      <p>The result shows that captured string (with name 'sidebar') overwrites layout template content.</p><a name="test_capturing/result.output"></a>
+
+      <div class="program_caption">
+        Result : only 'sidebar' placeholder is overwritten by capturing.
+      </div>
+      <pre class="program">
+$ ruby main.rb
 &lt;html&gt;
   &lt;body&gt;
-
-    &lt;div id="sidemenu"&gt;
-&lt;ul&gt;
-  &lt;li&gt;&lt;a href="/"&gt;Top&lt;/a&gt;&lt;/li&gt;
-  &lt;li&gt;&lt;a href="/prod"&gt;Products&lt;/a&gt;&lt;/li&gt;
-  &lt;li&gt;&lt;a href="/support"&gt;Support&lt;/a&gt;&lt;/li&gt;
-&lt;/ul&gt;
+    &lt;div id="header-part"&gt;
+      &lt;h1&gt;My Great Blog&lt;/h1&gt;
     &lt;/div&gt;
-
     &lt;div id="main-content"&gt;
-<strong>  &lt;p&gt;&amp;lt;FOO&amp;gt;&lt;/p&gt;</strong>
-<strong>  &lt;p&gt;&amp;amp;BAR&lt;/p&gt;</strong>
-<strong>  &lt;p&gt;&amp;quot;BAZ&amp;quot;&lt;/p&gt;</strong>
+&lt;h2&gt;Tenjin is Great&lt;/h2&gt;
+&lt;div class="blog-post"&gt;
+Tenjin has great features.&lt;br /&gt;
+- Very Fast&lt;br /&gt;
+- Full Featured&lt;br /&gt;
+- Easy to Use&lt;br /&gt;
 
-    &lt;/div&gt;
+&lt;/div&gt;
 
-    &lt;div id="footer"&gt;
-&lt;hr /&gt;
-&lt;address&gt;
-  &lt;a href="mailto:webmaster@example.com"&gt;webmaster@example.com&lt;/a&gt;
-&lt;/address&gt;
 
     &lt;/div&gt;
-
+    &lt;div id="sidebar-part"&gt;
+<strong>&lt;h3&gt;Recent Posts&lt;/h3&gt;</strong>
+<strong>&lt;ul&gt;</strong>
+  <strong>&lt;a href="/blog/1"&gt;Tenjin is Fast&lt;/a&gt;</strong>
+  <strong>&lt;a href="/blog/2"&gt;Tenjin is Full-Featured&lt;/a&gt;</strong>
+  <strong>&lt;a href="/blog/3"&gt;Tenjin is Easy-to-Use&lt;/a&gt;</strong>
+<strong>&lt;/ul&gt;</strong>
+    &lt;/div&gt;
   &lt;/body&gt;
-&lt;/table&gt;
-</pre>
-<p>Target template and layout template don't share local variables.
-It means that local variables set in a template are not available in layout template.
-</p>
-<p>If you want variables set in a temlate to be available in layout template,
-use instance variables instead of local variables.
-</p>
-<a name="layout7.rbhtml"></a>
-<div class="program_caption">
-File 'layout7.rbhtml':</div>
-<pre class="program">...
-&lt;h1&gt;<strong>${@title}</strong>&lt;/h1&gt;
-
-&lt;div id="main-content"&gt;
-#{@_content}
-&lt;div&gt;
+&lt;/html&gt;
+</pre><br>
+      <a name="templace-cache" id="templace-cache"></a>
 
-&lt;a href="<strong>${@url}</strong>"&gt;Next page&lt;/a&gt;
-...
-</pre>
-<a name="content7.rbhtml"></a>
-<div class="program_caption">
-File 'content7.rbhtml':</div>
-<pre class="program"><strong>&lt;?rb @title = 'Document Title' ?&gt;</strong>
-<strong>&lt;?rb @url = '/next/page' ?&gt;</strong>
-&lt;table&gt;
-  ...content...
-&lt;/table&gt;
-</pre>
-<a name="example7_layout2.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ rbtenjin --layout=layout7.rbhtml content7.rbhtml
-...
-&lt;h1&gt;<strong>Document Title</strong>&lt;/h1&gt;
-
-&lt;div id="main-content"&gt;
-&lt;table&gt;
-  ...content...
-&lt;/table&gt;
+      <h3 class="section2">Template Cache</h3>
 
+      <p>Tenjin converts template file into Ruby script and save it as cache file. By default, it is saved as template-filename + '.cache' in bytecode format. You can change this behaviour by setting <code>Tenjin::Engine.template_cache</code> or passing cache object to <code>Tenjin::Engine.new()</code>.</p>
+
+      <div class="program_caption">
+        example to change template caching
+      </div>
+      <pre class="program">
+## assume that you implimented MemcachedTemplateCache package
+class MemcachedTemplaceCache &lt; Tenjin::TemplateCache
+  def save(cachepath, template) ... end
+  def load(cachepath, timestamp=nil) ... end
+  end
+end
+
+## change to store template cache into memcached
+<strong>Tenjin::Engine.template_cache = MemcachedTemplateCache.new();</strong>
+my $engine = Tenjin::Engine.new();
+
+## or
+my $engine = Tenjin::Engine.new(<strong>:cache=&gt;MemcachedTemplateCache.new()</strong>);
+
+</pre><br>
+      <a name="fragment-cache" id="fragment-cache"></a>
+
+      <h3 class="section2">Fragment Cache</h3>
+
+      <p>You can cache a certain part of HTML to improve performance. This is called as Fragment Cache.</p><a name="test_fragmentcache/views/items.rbhtml"></a>
+
+      <div class="program_caption">
+        views/items.rbhtml
+      </div>
+      <pre class="program">
 &lt;div&gt;
+  <strong>&lt;?rb # fragment cache with key ('items/1') and lifetime (60sec) ?&gt;</strong>
+  <strong>&lt;?rb cache_with('items/1', 60) do ?&gt;</strong>
+  &lt;ul&gt;
+    &lt;?rb for item in @get_items.call() ?&gt;
+    &lt;li&gt;${item}&lt;/li&gt;
+    &lt;?rb end ?&gt;
+  &lt;/ul&gt;
+  <strong>&lt;?rb end ?&gt;</strong>
+&lt;/div&gt;
+</pre>
+
+      <p>Tenjin stores fragments caches into memory by default. If you want to change or customize cache store, see the following example.</p><a name="test_fragmentcache/main.rb"></a>
+
+      <div class="program_caption">
+        main.rb
+      </div>
+      <pre class="program">
+require 'tenjin'
 
-&lt;a href="<strong>/next/page</strong>"&gt;Next page&lt;/a&gt;
-...
-</pre>
-<p>Using '@_layout' variable, it is able to specify layout template name in each template file.
-If you assigned false to '@_layout' variable, no layout template is used.
-</p>
-<a name="content8.rbhtml"></a>
-<div class="program_caption">
-File 'content8.rbhtml':</div>
-<pre class="program"><strong>&lt;?rb @_layout = :layout8_xhtml ?&gt;</strong>
-&lt;h1&gt;Hello World!&lt;/h1&gt;
-</pre>
-<a name="layout8_html.rbhtml"></a>
-<div class="program_caption">
-File 'layout8_html.rbhtml':</div>
-<pre class="program">&lt;html&gt;
-  &lt;body&gt;
-#{@_content}
-  &lt;/body&gt;
-&lt;/html&gt;
-</pre>
-<a name="layout8_xhtml.rbhtml"></a>
-<div class="program_caption">
-File 'layout8_xhtml.rbhtml':</div>
-<pre class="program">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
-&lt;html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"&gt;
-  &lt;body&gt;
-#{@_content}
-  &lt;/body&gt;
-&lt;/html&gt;
+## create key-value store object
+Dir.mkdir('cache.d') unless File.exist?('cache.d')
+<strong>kv_store = Tenjin::FileBaseStore.new('cache.d')      # file based</strong>
+
+## set key-value store into tenjin.helpers.fagment_cache object
+<strong>Tenjin::Engine.data_cache = kv_store</strong>
+
+## context data
+## (it is strongly recommended to create Proc object
+##  to provide pull-style context data)
+get_items = proc {    # called only when cache is expired
+  ['AAA', 'BBB', 'CCC']
+}
+context = {:get_items =&gt; get_items}
+
+## render html
+engine = Tenjin::Engine.new(:path=&gt;['views'])
+html = engine.render('items.rbhtml', context)
+puts html
+</pre><a name="test_fragmentcache/result.output"></a>
+
+      <div class="terminal_caption">
+        Result
+      </div>
+      <pre class="terminal">
+$ ruby main.rb
+&lt;div&gt;
+  &lt;ul&gt;
+    &lt;li&gt;AAA&lt;/li&gt;
+    &lt;li&gt;BBB&lt;/li&gt;
+    &lt;li&gt;CCC&lt;/li&gt;
+  &lt;/ul&gt;
+&lt;/div&gt;
+</pre>
+
+      <p>You'll find that HTML fragment is cached into cache directory. This cache data will be expired at 60 seconds after.</p><a name="test_fragmentcache/result2.output"></a>
+      <pre class="terminal">
+$ cat cache.d/items/1
+  &lt;ul&gt;
+    &lt;li&gt;AAA&lt;/li&gt;
+    &lt;li&gt;BBB&lt;/li&gt;
+    &lt;li&gt;CCC&lt;/li&gt;
+  &lt;/ul&gt;
+</pre><br>
+      <a name="logging" id="logging"></a>
+
+      <h3 class="section2">Logging</h3>
+
+      <p>If you set logging object to <code>Tenjin.logger</code>, rbTenjin will report loading template files.</p>
+
+      <p>For example:</p><a name="test_logging/ex-logger.rb"></a>
+
+      <div class="program_caption">
+        ex-logger.rb
+      </div>
+      <pre class="program">
+require 'tenjin'
+
+## set logger object
+<strong>require 'logger'</strong>
+<strong>Tenjin.logger = Logger.new($stdout)</strong>
+Tenjin.logger.datetime_format = ""
+
+engine = Tenjin::Engine.new()
+context = {:name =&gt; 'World'}
+html = engine.render('example.rbhtml', context)
+#print html
 </pre>
-<a name="example8_layout3.result"></a>
-<div class="terminal_caption">
-Result: ':layout8_html' is specified in command-line option but ':layout8_xhtml' is used</div>
-<pre class="terminal">$ rbtenjin --postfix='.rbhtml' <strong>--layout=':layout8_html'</strong> content8.rbhtml
-&lt;?xml version="1.0" encoding="UTF-8"?&gt;
-&lt;html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"&gt;
-  &lt;body&gt;
-&lt;h1&gt;Hello World!&lt;/h1&gt;
 
-  &lt;/body&gt;
-&lt;/html&gt;
+      <p>If you run it first time, Tenjin will report that template object is stored into cache file.</p><a name="test_logging/result1.output"></a>
+      <pre class="terminal">
+$ ruby ex-logger.rb
+D, [#3700] DEBUG -- : [tenjin.rb:1022] cache not found (cachefile="example.rbhtml.cache").
+D, [#3700] DEBUG -- : [tenjin.rb:1005] cache saved (cachefile="example.rbhtml.cache").
 </pre>
-<br>
 
+      <p>And if you run it again, Tenjin will report that template object is loaded from cache file.</p><a name="test_logging/result2.output"></a>
+      <pre class="terminal">
+$ ruby ex-logger.rb
+D, [#3730] DEBUG -- : [tenjin.rb:1028] cache found (cachefile="example.rbhtml.cache").
+</pre><br>
+      <a name="preprocessing" id="preprocessing"></a>
 
-<a name="des-capturing"></a>
-<h3 class="section2">Capturing</h3>
-<p>It is able to capture any part of template.
-</p>
-<a name="example9.rbhtml"></a>
-<div class="program_caption">
-File 'example9.rbhtml':</div>
-<pre class="program">&lt;?rb @title = 'Capture Test' ?&gt;
-&lt;html&gt;
-  &lt;body&gt;
+      <h3 class="section2">Preprocessing</h3>
 
-<strong>&lt;?rb start_capture(:content_part) ?&gt;</strong>
-    &lt;ul&gt;
-&lt;?rb for i in [0, 1, 2] ?&gt;
-      &lt;li&gt;i = #{i}&lt;/li&gt;
-&lt;?rb end ?&gt;
-    &lt;/ul&gt;
-<strong>&lt;?rb stop_capture() ?&gt;</strong>
+      <p>Tenjin supports preprocessing of template. Preprocessing executes some logics when templates are loaded and that logics are not executed when rendering. Preprocessing makes your application much faster.</p><a name="preprocessing-basics" id="preprocessing-basics"></a>
 
-<strong>&lt;?rb start_capture('footer_part') ?&gt;</strong>
-    &lt;div class="footer"&gt;copyright&amp;copy; 2007 kuwata-lab.com&lt;/div&gt;
-<strong>&lt;?rb stop_capture() ?&gt;</strong>
+      <h4 class="section3">Basics of Preprocessing</h4>
 
-  &lt;/body&gt;
-&lt;/html&gt;
-</pre>
-<p>Captured strings are accessable as local variables.
-For example, you can get captured string as a variable '<code>content_part</code>' in the above example.
-</p>
-<p>A template can contain several capturing.
-It is not able to nest capturing.
-</p>
-<p>In layout file, it is able to use strings captured in templates.
-</p>
-<a name="layout9.rbhtml"></a>
-<div class="program_caption">
-File 'layout9.rbhtml':</div>
-<pre class="program">&lt;html lang="en"&gt;
-  &lt;head&gt;
-    &lt;title&gt;${@title}&lt;/title&gt;
-  &lt;/head&gt;
-  &lt;body&gt;
+      <p>Notation of preprocessing:</p>
 
-    &lt;!-- HEADER --&gt;
-<strong>&lt;?rb unless captured_as('header_part') ?&gt;</strong>
-    &lt;h1&gt;${@title}&lt;/h1&gt;
-<strong>&lt;?rb end ?&gt;</strong>
-    &lt;!-- /HEADER --&gt;
+      <dl class="dl1">
+        <dt class="dt1"><code>&lt;?RB ... ?&gt;</code></dt>
 
-    &lt;!-- CONTENT --&gt;
-<strong>#{@content_part}</strong>
-    &lt;!-- /CONTENT --&gt;
+        <dd class="dd1">Preprocessing statement.</dd>
 
-    &lt;!-- FOOTER --&gt;
-<strong>&lt;?rb unless captured_as('footer_part') ?&gt;</strong>
-    &lt;hr /&gt;
-    &lt;address&gt;webmaster@localhost&lt;/address&gt;
-<strong>&lt;?rb end ?&gt;</strong>
-    &lt;!-- /FOOTER --&gt;
+        <dt class="dt1"><code>#{{...}}</code></dt>
 
-  &lt;/body&gt;
-&lt;/html&gt;
-</pre>
-<p>'<code>unless captured_as("name") ... end</code>' is equivarent to the following.
-</p>
-<pre class="program">&lt;?rb if @name ?&gt;
-&lt;?rb   _buf &lt;&lt; @name ?&gt;
-&lt;?rb else ?&gt;
-       ...
-&lt;?rb end ?&gt;
-</pre>
-<p>The following result shows that content part and footer part are overrided by capturing in content template but header part is not.
-</p>
-<a name="example9_capture.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ rbtenjin --layout=layout9.rbhtml example9.rbhtml
-&lt;html lang="en"&gt;
-  &lt;head&gt;
-    &lt;title&gt;Capture Test&lt;/title&gt;
-  &lt;/head&gt;
-  &lt;body&gt;
+        <dd class="dd1">Preprocessing expression (without HTML escape)</dd>
 
-    &lt;!-- HEADER --&gt;
-    &lt;h1&gt;Capture Test&lt;/h1&gt;
-    &lt;!-- /HEADER --&gt;
+        <dt class="dt1"><code>${{...}}</code></dt>
 
-    &lt;!-- CONTENT --&gt;
-    <strong>&lt;ul&gt;</strong>
-      <strong>&lt;li&gt;i = 0&lt;/li&gt;</strong>
-      <strong>&lt;li&gt;i = 1&lt;/li&gt;</strong>
-      <strong>&lt;li&gt;i = 2&lt;/li&gt;</strong>
-    <strong>&lt;/ul&gt;</strong>
+        <dd class="dd1">Preprocessing expression (with HTML escape)</dd>
+      </dl>
 
-    &lt;!-- /CONTENT --&gt;
+      <p>The following shows difference between <code>${...}</code> and <code>${{...}}</code>.</p><a name="test_preprocessing/views/pp-example1.rbhtml"></a>
 
-    &lt;!-- FOOTER --&gt;
-    <strong>&lt;div class="footer"&gt;copyright&amp;copy; 2007 kuwata-lab.com&lt;/div&gt;</strong>
-    &lt;!-- /FOOTER --&gt;
+      <div class="program_caption">
+        views/pp-example1.rbhtml
+      </div>
+      <pre class="program">
+## normal expression
+value = <strong>${$VALUE}</strong>
+## with preprocessing
+value = <strong>${{$VALUE}}</strong>
+</pre><a name="test_preprocessing/pp-example1.rb"></a>
 
-  &lt;/body&gt;
-&lt;/html&gt;
-</pre>
-<br>
-
-
-<a name="des-args"></a>
-<h3 class="section2">Template Arguments</h3>
-<p>It is able to specify template arguments in template files.
-Template arguments are variables which are passed by main program via context object.
-In the following example, '<code>title</code>' and '<code>name</code>' are template arguments.
-</p>
-<a name="example10.rbhtml"></a>
-<div class="program_caption">
-File 'example10.rbhtml':</div>
-<pre class="program">&lt;?xml version="1.0"?&gt;
-<strong>&lt;?rb #@ARGS title, name ?&gt;</strong>
-&lt;h1&gt;${title}&lt;/h1&gt;
-&lt;p&gt;Hello ${name}!&lt;/p&gt;
-</pre>
-<p>Template arguments line is converted into assignment statements of local variables.
-</p>
-<a name="example10_template_args.result"></a>
-<pre class="terminal">$ rbtenjin -s example10.rbhtml
-_buf = '';  _buf &lt;&lt; %Q`&lt;?xml version="1.0"?&gt;\n`
-<strong> title = @title; name = @name;</strong>
- _buf &lt;&lt; %Q`&lt;h1&gt;#{escape((title).to_s)}&lt;/h1&gt;
-&lt;p&gt;Hello #{escape((name).to_s)}!&lt;/p&gt;\n`
+      <div class="program_caption">
+        pp-example1.rb
+      </div>
+      <pre class="program">
+$VALUE = 'My Great Example'
+
+## create engine object with preprocessing enabled
+require 'tenjin'
+engine = Tenjin::Engine.new(:path=&gt;['views'], <strong>:preprocess=&gt;true</strong>)
+
+## print Python script code
+puts "------ converted script ------"
+puts engine.get_template('pp-example1.rbhtml').script
+
+## render html
+html = engine.render('pp-example1.rbhtml', {})
+puts "------ rendered html ------"
+puts html
+</pre><a name="test_preprocessing/result1a.output"></a>
+
+      <div class="terminal_caption">
+        Result: notice that <code>${{...}}</code> is evaluated at template converting stage.
+      </div>
+      <pre class="terminal">
+$ ruby pp-example1.rb
+------ converted script ------
+ _buf &lt;&lt; %Q`## normal expression
+value = <strong>#{escape(($VALUE).to_s)}</strong>
+## with preprocessing
+value = <strong>My Great Example</strong>\n`
+------ rendered html ------
+## normal expression
+value = My Great Example
+## with preprocessing
+value = My Great Example
+</pre>
+
+      <p>You can confirm preprocessed template by '<code>rbtenjin -P</code>' command.</p><a name="test_preprocessing/result1b.output"></a>
+
+      <div class="terminal_caption">
+        Preprocessed template
+      </div>
+      <pre class="terminal">
+$ rbtenjin <strong>-P</strong> -c '$VALUE="My Great Example"' views/pp-example1.rbhtml
+## normal expression
+value = ${$VALUE}
+## with preprocessing
+value = My Great Example
+</pre>
+
+      <p>If you want to see preprocessing script (not preprocessed script), use '<code>rbtenjin -sP</code>' command.</p><a name="test_preprocessing/result1c.output"></a>
+      <pre class="terminal">
+$ rbtenjin <strong>-sP</strong> -c '$VALUE="My Great Example"' views/pp-example1.rbhtml
+_buf = '';  _buf &lt;&lt; %Q`\#\# normal expression
+value = ${$VALUE}
+\#\# with preprocessing
+value = #{escape((_decode_params(($VALUE))).to_s)}\n`
 _buf.to_s
-</pre>
-<p>If template arguments are specified, other variables passed by context object are not set.
-</p>
-<a name="example11.rbhtml"></a>
-<div class="program_caption">
-File 'example11.rbhtml':</div>
-<pre class="program">&lt;p&gt;
-<strong>&lt;?rb #@ARGS x ?&gt;</strong>
-x = #{x}
-y = #{y}   # NameError
-&lt;/p&gt;
-</pre>
-<a name="example11_template_args_result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ rbtenjin <strong>-c '@x=10;@y=20'</strong> example11.rbhtml
-example12.rbhtml:4:in `_render': undefined local variable or method `y' (NameError)
-</pre>
-<br>
-
-
-<a name="des-preprocess"></a>
-<h3 class="section2">Preprocessing</h3>
-<p>rbTenjin supports preprocessing of template.
-Preprocessing executes some logics when templates are loaded and that logics are not executed when rendering.
-Preprocessing makes your application much faster.
-</p>
-<p>Notation of preprocessing is the following.
-</p>
-<ul type="disc">
-<li><code>&lt;?RB ... ?&gt;</code> represents preprocessing statement.
-</li>
-<li><code>#{{...}}</code> represents preprocessing expression (without HTML escape).
-</li>
-<li><code>${{...}}</code> represents preprocessing expression (with HTML escape).
-</li>
-</ul>
-<p>For example, assume the following template.
-</p>
-<a name="example12.rbhtml"></a>
-<div class="program_caption">
-File 'example12.rbhtml':</div>
-<pre class="program"><strong>&lt;?RB states = { "CA" =&gt; "California", ?&gt;</strong>
+</pre><br>
+      <a name="preprocessing-loop-expantion" id="preprocessing-loop-expantion"></a>
+
+      <h4 class="section3">Loop Expantion</h4>
+
+      <p>It is possible to evaluate some logics by '<code>&lt;?RB ... ?&gt;</code>' when convert template into Ruby script code. For example, you can expand loop in advance to improve performance.</p><a name="test_preprocessing/views/pp-example2.rbhtml"></a>
+
+      <div class="program_caption">
+        views/pp-example2.rbhtml
+      </div>
+      <pre class="program">
+<strong>&lt;?RB states = { "CA" =&gt; "California", ?&gt;</strong>
 <strong>&lt;?RB            "NY" =&gt; "New York", ?&gt;</strong>
 <strong>&lt;?RB            "FL" =&gt; "Florida",  ?&gt;</strong>
 <strong>&lt;?RB            "TX" =&gt; "Texas",  ?&gt;</strong>
 <strong>&lt;?RB            "HI" =&gt; "Hawaii", } ?&gt;</strong>
-&lt;?rb chk = { @params['state'] =&gt; ' selected="selected"' } ?&gt;
+&lt;?rb chk = { params['state'] =&gt; ' selected="selected"' } ?&gt;
 &lt;select name="state"&gt;
   &lt;option value=""&gt;-&lt;/option&gt;
-<strong>&lt;?RB for code in states.keys.sort ?&gt;</strong>
-  &lt;option value="<strong>#{{code}}</strong>"#{chk[<strong>#{{code.inspect}}</strong>]}&gt;<strong>${{states[code]}}</strong>&lt;/option&gt;
-<strong>&lt;?RB end ?&gt;</strong>
+  <strong>&lt;?RB for code in states.keys.sort ?&gt;</strong>
+  &lt;option value="<strong>#{{code}}</strong>"#{chk['<strong>#{{code}}</strong>']}&gt;<strong>${{states[code]}}</strong>&lt;/option&gt;
+  <strong>&lt;?RB end ?&gt;</strong>
 &lt;/select&gt;
 </pre>
-<p>If preprocessing is activated, the above will be converted into the following when template is loaded.
-(Command-line option <code>-P</code> shows the result of preprocessing.)
-</p>
-<a name="example12_preprocessed.result"></a>
-<div class="terminal_caption">
-Result of preprocessing:</div>
-<pre class="terminal">$ rbtenjin <strong>-P</strong> example12.rbhtml
-&lt;?rb chk = { @params['state'] =&gt; ' selected="selected"' } ?&gt;
+
+      <p>Preprocessed script code shows that loop is expanded in advance. It means that loop is not executed when rendering template.</p><a name="test_preprocessing/result2a.output"></a>
+
+      <div class="terminal_caption">
+        Preprocessed template
+      </div>
+      <pre class="terminal">
+$ rbtenjin -P views/pp-example2.rbhtml
+&lt;?rb chk = { params['state'] =&gt; ' selected="selected"' } ?&gt;
 &lt;select name="state"&gt;
   &lt;option value=""&gt;-&lt;/option&gt;
-  &lt;option value="CA"#{chk["CA"]}&gt;California&lt;/option&gt;
-  &lt;option value="FL"#{chk["FL"]}&gt;Florida&lt;/option&gt;
-  &lt;option value="HI"#{chk["HI"]}&gt;Hawaii&lt;/option&gt;
-  &lt;option value="NY"#{chk["NY"]}&gt;New York&lt;/option&gt;
-  &lt;option value="TX"#{chk["TX"]}&gt;Texas&lt;/option&gt;
+  &lt;option value="CA"#{chk['CA']}&gt;California&lt;/option&gt;
+  &lt;option value="FL"#{chk['FL']}&gt;Florida&lt;/option&gt;
+  &lt;option value="HI"#{chk['HI']}&gt;Hawaii&lt;/option&gt;
+  &lt;option value="NY"#{chk['NY']}&gt;New York&lt;/option&gt;
+  &lt;option value="TX"#{chk['TX']}&gt;Texas&lt;/option&gt;
 &lt;/select&gt;
+</pre><br>
+      <a name="preprocessing-parameters" id="preprocessing-parameters"></a>
+
+      <h4 class="section3">Parameters</h4>
+
+      <p>Assume that link_to() is a helper method which takes label and url and generate &lt;a&gt;&lt;/a&gt; tag. In this case, label and url can be parameterized by <code>_p("...")</code> and <code>_P("...")</code>. The former is converted into #{...} and the latter converted into ${...} by preprocessor.</p><a name="test_preprocessing/views/pp-example3.rbhtml"></a>
+
+      <div class="program_caption">
+        views/pp-example3.rbhtml
+      </div>
+      <pre class="program">
+<strong>&lt;?RB</strong>
+## ex. link_to('Show', '/show/1')  =&gt; &lt;a href="/show/1"&gt;Show&lt;/a&gt;
+def link_to(label, url)
+    return "&lt;a href=\"#{url}\"&gt;#{label}&lt;/a&gt;"
+end
+<strong>?&gt;</strong>
+<strong>#{{</strong>link_to('Show '+<strong>_P(</strong>'params["name"]'<strong>)</strong>, '/items/show/'+<strong>_p(</strong>'params["id"]'<strong>)</strong>)<strong>}}</strong>
 </pre>
-<p>This means that for-loop is executed only once when template is loaded and is not executed when rendering.
-In the result, rendering speed becomes to be much faster.
-</p>
-<p>And the Ruby code is here. This shows that there is no for-loop.
-</p>
-<a name="example12_preprocessed_source.result"></a>
-<div class="terminal_caption">
-Translated script code:</div>
-<pre class="terminal">$ rbtenjin <strong>--preprocess</strong> -sb example12.rbhtml
-chk = { @params['state'] =&gt; ' selected="selected"' }
- _buf &lt;&lt; %Q`&lt;select name="state"&gt;
-  &lt;option value=""&gt;-&lt;/option&gt;
-  &lt;option value="CA"#{chk["CA"]}&gt;California&lt;/option&gt;
-  &lt;option value="FL"#{chk["FL"]}&gt;Florida&lt;/option&gt;
-  &lt;option value="HI"#{chk["HI"]}&gt;Hawaii&lt;/option&gt;
-  &lt;option value="NY"#{chk["NY"]}&gt;New York&lt;/option&gt;
-  &lt;option value="TX"#{chk["TX"]}&gt;Texas&lt;/option&gt;
-&lt;/select&gt;\n`
-</pre>
-<p>If you have errors on preprocessing, you should check source script by <code>-Ps</code> option<sup>(<a href="#fnref:1" name="fnlink:1">*1</a>)</sup>.
-</p>
-<p>The following is an another example.
-Assume that <code>link_to()</code> is a helper method which takes label and url and generate
-<code>&lt;a&gt;&lt;/a&gt;</code> tag.
-In this case, label and url can be parameterized by <code>_p("...")</code> and <code>_P("...")</code>.
-The former is converted into <code>#{...}</code> and the latter converted into <code>${...}</code>
-by preprocessor.
-</p>
-<a name="example13.rbhtml"></a>
-<div class="program_caption">
-File 'example13.rbhtml':</div>
-<pre class="program">&lt;?RB require 'cgi' ?&gt;
-&lt;?RB ## ex. link_to('Show', '/show/1')  =&gt; &lt;a href="/show/1"&gt;Show&lt;/a&gt; ?&gt;
-&lt;?RB def link_to(label, url) ?&gt;
-&lt;?RB     return "&lt;a href=\"#{CGI.unescape(url)}\"&gt;#{label}&lt;/a&gt;" ?&gt;
-&lt;?RB end ?&gt;
-#{{link_to 'Show '+<strong>_P('@params["name"]')</strong>, '/items/show/'+<strong>_p('@params["id"]')</strong>}}
-</pre>
-<a name="example13_preprocessed.result"></a>
-<div class="terminal_caption">
-Preprocessed template:</div>
-<pre class="terminal">$ rbtenjin <strong>-P</strong> example13.rbhtml
-&lt;a href="/items/show/<strong>#{@params["id"]}"</strong>&gt;Show <strong>${@params["name"]}</strong>&lt;/a&gt;
-</pre>
-<a name="example13_preprocessed_source.result"></a>
-<div class="terminal_caption">
-Translated script code:</div>
-<pre class="terminal">$ rbtenjin <strong>--preprocess</strong> -sb example13.rbhtml
- _buf &lt;&lt; %Q`&lt;a href="/items/show/<strong>#{@params["id"]}</strong>"&gt;Show <strong>#{escape((@params["name"]).to_s)}</strong>&lt;/a&gt;\n`
-</pre>
-<p>There are many web-application framework and they provides helper functions.
-These helper functions are divided into two groups.
-</p>
-<ul type="disc">
-<li><code>link_to()</code> or <code>_()</code> (function for M17N) return the same result
-   when the same arguments are passed.
-   These functions can be expanded by preprocessor.
-</li>
-<li>Some functions return the different result even if the same arguments are passed.
-   These functions can't be expaned by preprocessor.
-</li>
-</ul>
-<p>Preprocessor has the power to make your application much faster,
-but it may make the debugging difficult.
-You should use it carefully.
-</p>
-<div class="footnote">
- <dl compact>
-  <dt>(<a name="fnref:1" href="#fnlink:1">*1</a>)</dt>
-  <dd>Command-line option '-Ps' is available but '-PS' is not availabe. This is a current restriction of rbtenjin. </dd>
- </dl>
-</div>
-<br>
-
-
-<a name="des-otheropts"></a>
-<h3 class="section2">Other Options</h3>
-<ul type="disc">
-<li>Command-line option '<code>--escapefunc=func1</code>' changes <code>escape()</code> function name to <code>func1</code>.
-   For example, '<code>--escapefunc=h</code>' changes escape function from <code>escape()</code> to <code>h()</code>.
-</li>
-<li>It is not able to contain '<code>}</code>' character in '<code>${...}</code>'.
-   For example, '<code>${hash["}"]}</code>' will be converted into '<code>_buf &lt;&lt; %Q`#{escape((hash[").to_s)}"]}</code>` and not '<code>_buf &lt;&lt; %Q`#{escape((hash["}"]).to_s)}`</code>'.
-   There is no such restriction about '<code>#{...}</code>'.
-</li>
-<li>It is not able to contain '<code>\</code>' and '<code>`</code>' characters in '<code>#{...}</code>'
-   because these characters are escaped.
-   For example, '<code>#{hash["\n"]}</code>' will be converted into '<code>_buf &lt;&lt; %Q`hash["\n"]`</code>'.
-   There is no such restriction about '<code>${...}</code>'.
-</li>
-<li>Command-line option '<code>--path=dir1,dir2,...</code>' sepcifies template directory path.
-</li>
-</ul>
-<br>
-
-
-<br>
-
-
-<a name="devguide"></a>
-<h2 class="section1">Developer's Guide</h2>
-<p>This section shows how to use rbTenjin in your Ruby script.
-</p>
-<p>If you want to know the notation or features of rbTenjin, see <a href="#desguide">Designer's Guide</a> section.
-</p>
-<a name="dev-example"></a>
-<h3 class="section2">An Example</h3>
-<p>The following is an example to use rbTenjin in Ruby.
-</p>
-<div class="program_caption">
-Example:</div>
-<pre class="program">require 'tenjin'
-engine = Tenjin::Engine.new()
-context = { :title=&gt;'rbTenjin Example', :items=&gt;['AAA', 'BBB', 'CCC'] }
-filename = 'file.rbhtml'
-output = engine.render(filename, context)
-print output
-</pre>
-<p>If you want to define helper functions for template, see <a href="#dev-helpers">Add Your Helper Functions</a> section.
-</p>
-<br>
-
-
-<a name="dev-classes"></a>
-<h3 class="section2">Classes and Functions in rbTenjin</h3>
-<p>rbTenjin has the follwoing classes.
-</p>
-<dl class="dl3">
-<dt class="dt3"><b>
-Tenjin::Template </b></dt>
-<dd class="dd3">
-    This class represents a template file.
-    An object of Tenjin::Template correspond to a template file.
-</dd>
-</dl>
-<dl class="dl3">
-<dt class="dt3"><b>
-Tenjin::Engine </b></dt>
-<dd class="dd3">
-    This class represents some template objects.
-    It can handle nested template and layout template.
-    Using Tenjin::Engine class, you can use rbTenjin as a template engine for web application.
-</dd>
-</dl>
-<dl class="dl3">
-<dt class="dt3"><b>
-Tenjin::Context </b></dt>
-<dd class="dd3">
-    This class represents context data.
-</dd>
-</dl>
-<p>rbTenjin has the following utility functions.
-These are defined at Tenjin::HtmlHelper module and Tenjin::Context class includes it.
-</p>
-<br>
-
-
-<a name="dev-templateclass"></a>
-<h3 class="section2">Class Tenjin::Template</h3>
-<p>Tenjin::Template class represents a template file.
-An object of Tenjin::Template corresponds to a template file.
-It doesn't support nested template nor layout template (use Tenjin::Engine class instead).
-</p>
-<p>This class has the following methods and attributes.
-</p>
-<dl class="dl3">
-<dt class="dt3"><b>
-Tenjin::Template.new(filename=nil, :escapefunc=&gt;'escape') </b></dt>
-<dd class="dd3">
-    Create template object. If filename is given, read and convert it to Ruby code.
-</dd>
-</dl>
-<dl class="dl3">
-<dt class="dt3"><b>
-Tenjin::Template#convert(input, filename=None) </b></dt>
-<dd class="dd3">
-    Convert input text into Ruby code and return it.
-</dd>
-</dl>
-<dl class="dl3">
-<dt class="dt3"><b>
-Tenjin::Template#convert_file(filename) </b></dt>
-<dd class="dd3">
-    Convert file into Ruby code and return it.
-    This is equivarent to <code>Tenjin::Template#convert(File.read(filename), filename)</code>
-</dd>
-</dl>
-<dl class="dl3">
-<dt class="dt3"><b>
-Tenjin::Template#render(context=nil) </b></dt>
-<dd class="dd3">
-    Compile Ruby code, evaluate it with context data, and return the result of evaluation.
-</dd>
-</dl>
-<dl class="dl3">
-<dt class="dt3"><b>
-Tenjin::Template#script </b></dt>
-<dd class="dd3">
-    Converted Ruby code
-</dd>
-</dl>
-<p>The followings are examples to use Tenjin::Template in Ruby script.
-</p>
-<a name="example14.rbhtml"></a>
-<div class="program_caption">
-File 'example14.rbhtml':</div>
-<pre class="program">&lt;h1&gt;#{@title}&lt;/h1&gt;
-&lt;ul&gt;
-&lt;?rb for item in @items ?&gt;
- &lt;li&gt;${item}&lt;/li&gt;
-&lt;?rb end ?&gt;
-&lt;/ul&gt;
+
+      <p>The following shows that <code>_P('...')</code> and <code>_p('...')</code> are converted into <code>${...}</code> and <code>#{...}</code> respectively.</p><a name="test_preprocessing/result3a.output"></a>
+
+      <div class="terminal_caption">
+        Preprocessed template:
+      </div>
+      <pre class="terminal">
+$ rbtenjin -P views/pp-example3.rbhtml
+&lt;a href="/items/show/<strong>#{</strong>params["id"]<strong>}</strong>"&gt;Show <strong>${</strong>params["name"]<strong>}</strong>&lt;/a&gt;
 </pre>
-<a name="example14.rb"></a>
-<div class="program_caption">
-File 'example14.rb':</div>
-<pre class="program">## template file
-filename = 'example14.rbhtml'
 
-## convert into ruby code
+      <p>There are many web-application framework and they provides helper functions. These helper functions are divided into two groups. link_to() or _() (function for M17N) return the same result when the same arguments are passed. These functions can be expanded by preprocessor. Some functions return the different result even if the same arguments are passed. These functions can't be expaned by preprocessor.</p>
+
+      <p>Preprocessor has the power to make view-layer much faster, but it may make the debugging difficult. You should use it carefully.</p><br>
+      <br>
+      <a name="m17n" id="m17n"></a>
+
+      <h3 class="section2">M17N Page</h3>
+
+      <p>If you have M17N site, you can make your site faster by Tenjin.</p>
+
+      <p>In M17N-ed site, message translation function (such as <code>_('message-key')</code>) is called many times. Therefore if you can eliminate calling that function, your site can be faster. And Tenjin can do it by preprocessing.</p>
+
+      <p>The points are:</p>
+
+      <ul type="disc">
+        <li>Change cache filename according to language. For example, create cache file 'file.rbhtml.en.cache', 'file.rbhtml.fr.cache', 'file.rbhtml.it.cache', and so on from a template file 'file.rbhtml'. This is done by Tenjin automatically if you pass '<code>:lang=&gt;"en"</code>' or '<code>lang="fr"</code>' option to Engine class.</li>
+
+        <li>Create Engine object for each language and pass <code>:lang</code> option respectively.</li>
+
+        <li>Enable preprocessing to create different cache content for each language.</li>
+      </ul>
+
+      <p>The following is an example to generate M17N pages from a template file.</p><a name="test_m17n/m17n.rbhtml"></a>
+
+      <div class="program_caption">
+        m17n.rbhtml:
+      </div>
+      <pre class="program">
+&lt;div&gt;
+&lt;?RB ## '_()' represents translator method ?&gt;
+&lt;?RB _ = @_ ?&gt;
+ &lt;p&gt;<strong>${{_['Hello']}}</strong> ${@username}!&lt;/p&gt;
+&lt;/div&gt;
+</pre><a name="test_m17n/m17n.rb"></a>
+
+      <div class="program_caption">
+        m17n.rb:
+      </div>
+      <pre class="program">
+# -*- coding: utf-8 -*-
 require 'tenjin'
-template = <strong>Tenjin::Template.new(filename)</strong>
-## or
-# template = Tenjin::Template.new()
-# script = <strong>template.convert_file(filename)</strong>
-## or
-# template = Tenjin::Template.new()
-# input = File.read(filename)
-# script = <strong>template.convert(input, filename)</strong>  # filename is optional
-
-## show converted ruby code
-puts "---- ruby code ----"
-puts <strong>template.script</strong>
-
-## evaluate ruby code
-hash = {:title=&gt;'rbTenjin Example', :items=&gt;['&lt;AAA&gt;','B&amp;B','"CCC"']}
-output = <strong>template.render(hash)</strong>
-puts "---- output ----"
-puts output
-## or
-#hash = {:title=&gt;'rbTenjin Example', :items=&gt;['&lt;AAA&gt;','B&amp;B','"CCC"']}
-#context = <strong>Tenjin::Context.new(hash)</strong>
-#output = <strong>template.render(context)</strong>
-## or
-# context = Tenjin::Context.new
-# context[:title] = 'rbTenjin Example'
-# context[:items] = ['&lt;AAA&gt;','B&amp;B','"CCC"']
-# output = template.render(context)
-</pre>
-<a name="example14_tmplclass.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ ruby example14.rb
----- ruby code ----
- _buf &lt;&lt; %Q`&lt;h1&gt;#{@title}&lt;/h1&gt;
-&lt;ul&gt;\n`
-for item in @items
- _buf &lt;&lt; %Q` &lt;li&gt;#{escape((item).to_s)}&lt;/li&gt;\n`
+
+##
+## message catalog to translate message
+##
+MESSAGE_CATALOG = {
+  'en' =&gt; { 'Hello'=&gt;"Hello",   'Good bye'=&gt;"Good bye" },
+  'fr' =&gt; { 'Hello'=&gt;"Bonjour", 'Good bye'=&gt;"Au revoir" },
+}
+
+##
+## create translation function and return it.
+## ex.
+##    _ = create_m17n_obj('fr')
+##    print _['Hello']   #=&gt; 'Bonjour'
+##
+def create_m17n_obj(lang)
+  hash = MESSAGE_CATALOG[lang]  or
+    raise Error.new("#{lang}: unknown lang.")
+  _ = proc {|message_key| hash[message_key] }
+  return _
 end
- _buf &lt;&lt; %Q`&lt;/ul&gt;\n`
----- output ----
-&lt;h1&gt;rbTenjin Example&lt;/h1&gt;
-&lt;ul&gt;
- &lt;li&gt;&amp;lt;AAA&amp;gt;&lt;/li&gt;
- &lt;li&gt;B&amp;amp;B&lt;/li&gt;
- &lt;li&gt;&amp;quot;CCC&amp;quot;&lt;/li&gt;
-&lt;/ul&gt;
-</pre>
-<br>
-
-
-<a name="dev-engineclass"></a>
-<h3 class="section2">Class Tenjin::Engine</h3>
-<p>Tenjin::Engine class contains some template objects.
-It can handle nested template and layout template.
-Using Tenjin::Engine class, you can use rbTenjin as a template engine for web application.
-</p>
-<p>This class has the following methods.
-</p>
-<dl class="dl3">
-<dt class="dt3"><b>
-Tenjin::Engine.new(:prefix=&gt;'', :postfix=&gt;'', :layout=&gt;nil, :path=nil, :cache=&gt;true, :preprocess=&gt;false, :templateclass=&gt;Tenjin::Template) </b></dt>
-<dd class="dd3">
-    Create Engine object.
-    <code>:path</code> represents template search path and it should be an Array of directory name.
-    Other arguments are passed to Tenjin::Template.new() internally.
-</dd>
-</dl>
-<dl class="dl3">
-<dt class="dt3"><b>
-Tenjin::Engine#render(template_name, context=nil, layout=nil) </b></dt>
-<dd class="dd3">
-    Convert template into Ruby code, evaluate it with context data, and return the result of it.
-    If <code>layout</code> is true or nil then layout template name specified by constructor option is
-    used as layout template, else if false then layout template is not used,
-    else if string then it is regarded as layout template name.
-</dd>
-</dl>
-<p>Argument <code>template_name</code> in render() methods is filename or short name of template.
-Template short name is a Symbol.
-For example, '<code>render(:list, context)</code>' is equivarent to '<code>render("user_list.rbhtml", context)</code>' if prefix option is '<code>user_</code>' and postfix option is '<code>.rbhtml</code>'.
-</p>
-<p>In template file, the followings are available.
-</p>
-<dl class="dl3">
-<dt class="dt3"><b>
-@_content </b></dt>
-<dd class="dd3">
-    This variable represents the result of evaluation of other template.
-    This is available only in layout template file.
-</dd>
-</dl>
-<dl class="dl3">
-<dt class="dt3"><b>
-import(template_name) </b></dt>
-<dd class="dd3">
-    Include and evaluate other template.
-    This method is an instance method of Tenjin::Context class.
-</dd>
-</dl>
-<dl class="dl3">
-<dt class="dt3"><b>
-start_capture(name) </b></dt>
-<dd class="dd3">
-    Start capturing. Result will be stored into <code>@<em>name</em></code>.
-</dd>
-</dl>
-<dl class="dl3">
-<dt class="dt3"><b>
-stop_capture() </b></dt>
-<dd class="dd3">
-    Stop capturing.
-</dd>
-</dl>
-<dl class="dl3">
-<dt class="dt3"><b>
-captured_as(varname) </b></dt>
-<dd class="dd3">
-    If captured string as <em>varname</em> is exist then append it into
-    <code>@_buf</code> and return true, else return false.
-    This is a helper function for layout template.
-</dd>
-</dl>
-<p>The followings are example of Tenjin::Engine class.
-</p>
-<a name="user_form.rbhtml"></a>
-<div class="program_caption">
-File 'user_form.rbhtml':</div>
-<pre class="program">&lt;?rb #@ARGS params ?&gt;
+
+##
+## test program
+##
+if __FILE__ == $0
+  ## render html for English
+  engine_en = Tenjin::Engine.new(:preprocess=&gt;true, <strong>:lang=&gt;'en'</strong>)
+  context = { :username =&gt; 'World' }
+  <strong>context[:_] = create_m17n_obj('en')</strong>
+  html = engine_en.render('m17n.rbhtml', context)
+  puts "--- lang: en ---"
+  puts html
+
+  ## render html for French
+  engine_fr = Tenjin::Engine.new(:preprocess=&gt;true, <strong>:lang=&gt;'fr'</strong>)
+  context = { :username =&gt; 'World' }
+  <strong>context[:_] = create_m17n_obj('fr')</strong>
+  html = engine_fr.render('m17n.rbhtml', context)
+  puts "--- lang: fr ---"
+  puts html
+end
+</pre><a name="test_m17n/result.output"></a>
+
+      <div class="terminal_caption">
+        Result:
+      </div>
+      <pre class="terminal">
+$ ruby m17n.rb
+--- lang: en ---
+&lt;div&gt;
+ &lt;p&gt;<strong>Hello</strong> World!&lt;/p&gt;
+&lt;/div&gt;
+--- lang: fr ---
+&lt;div&gt;
+ &lt;p&gt;<strong>Bonjour</strong> World!&lt;/p&gt;
+&lt;/div&gt;
+</pre>
+
+      <p>After that, you can find two cache files are created.</p>
+      <pre class="terminal">
+$ ls m17n.rbhtml*
+m17n.rbhtml    m17n.rbhtml.<strong>en</strong>.cache    m17n.rbhtml.<strong>fr</strong>.cache
+</pre>
+
+      <p>And each cache files have different content.</p><a name="test_m17n/result_en.output"></a>
+
+      <div class="terminal_caption">
+        <code>_('Hello')</code> is translated into "Hello" in Engilish cache file
+      </div>
+      <pre class="terminal">
+$ cat m17n.rbhtml.en.cache
+ _buf &lt;&lt; %Q`&lt;div&gt;
+ &lt;p&gt;<strong>Hello</strong> #{escape((@username).to_s)}!&lt;/p&gt;
+&lt;/div&gt;\n`
+</pre><a name="test_m17n/result_fr.output"></a>
+
+      <div class="terminal_caption">
+        <code>_('Hello')</code> is translated into "Bonjour" in French cache file
+      </div>
+      <pre class="terminal">
+$ cat m17n.rbhtml.fr.cache
+ _buf &lt;&lt; %Q`&lt;div&gt;
+ &lt;p&gt;<strong>Bonjour</strong> #{escape((@username).to_s)}!&lt;/p&gt;
+&lt;/div&gt;\n`
+</pre><br>
+      <a name="cgi-script" id="cgi-script"></a>
+
+      <h3 class="section2">Make Tenjin as PHP-like Tool</h3>
+
+      <p>Tenjin provides 'rbtenjin.cgi' CGI script which makes Tenjin as PHP-like tool.</p>
+
+      <div class="terminal_caption">
+        Setup
+      </div>
+      <pre class="terminal">
+$ htdocs=/usr/local/apache2/htdocs   # or $HOME/public_html
+$ tar xzf rbtenjin-X.X.X.tar.gz
+$ cd rbtenjin-X.X.X/
+$ cp lib/tenjin.rb            $htdocs
+$ cp public_html/rbtenjin.cgi $htdocs
+$ cp public_html/.htaccess    $htdocs
+$ cd public_html/*.rbhtml     $htdocs
+$ chmod a+x $htdocs/rbtenjin.cgi
+</pre>
+
+      <p>After that, access to http://localhost/ (or http://localhost/~yourname/) and you'll see example page.</p><br>
+      <br>
+      <a name="tips" id="tips"></a>
+
+      <h2 class="section1">Tips</h2><a name="function-names" id="function-names"></a>
+
+      <h3 class="section2">Specify Function Names of escape() and to_str()</h3>
+
+      <p>It is able to specify function names of html escape.</p><a name="test_escape/main.rb"></a>
+
+      <div class="program_caption">
+        main.rb
+      </div>
+      <pre class="program">
+require 'tenjin'
+require 'erb'
+engine = Tenjin::Engine.new(:path=&gt;['views'], <strong>:escapefunc=&gt;'ERB::Util.h'</strong>)
+puts engine.get_template('page.rbhtml').script
+</pre><a name="test_escape/views/page.rbhtml"></a>
+
+      <div class="program_caption">
+        views/page.rbhtml
+      </div>
+      <pre class="program">
 &lt;p&gt;
-  Name:  &lt;input type="text" name="name"  value="${params['name']}" /&gt;&lt;br /&gt;
-  Email: &lt;input type="text" name="email" value="${params['email']}" /&gt;&lt;br /&gt;
-  Gender:
-&lt;?rb gender = @params['gender'] ?&gt;
-&lt;?rb chk = { true=&gt;' checked="checked"', false=&gt;'' } ?&gt;
-  &lt;input type="radio" name="gender" value="m" #{chk[gender=='m']} /&gt;Male
-  &lt;input type="radio" name="gender" value="f" #{chk[gender=='f']} /&gt;Female
+  escaped:     ${@value}
+  not escaped: #{@value}
 &lt;/p&gt;
+</pre><a name="test_escape/result.output"></a>
+
+      <div class="program_caption">
+        Result
+      </div>
+      <pre class="program">
+$ ruby main.rb
+ _buf &lt;&lt; %Q`&lt;p&gt;
+  escaped:     #{<strong>ERB::Util.h</strong>((@value).to_s)}
+  not escaped: #{@value}
+&lt;/p&gt;\n`
+</pre><br>
+      <a name="tips-template-inheritance" id="tips-template-inheritance"></a>
+
+      <h3 class="section2">Template Inheritance</h3>
+
+      <p>Tenjin doesn't support Template Inheritance which Django template engine does. But you can emulate it by capturing<sup>(<a href="#fnref:1" name="fnlink:1" id="fnlink:1">*1</a>)</sup>. See <a href="#capturing">this section</a> for details.</p>
+
+      <div class="footnote">
+        <dl compact>
+          <dt>(<a name="fnref:1" href="#fnlink:1" id="fnref:1">*1</a>)</dt>
+
+          <dd>Notice that capturing is useful but not so powerful than template inheritance.</dd>
+        </dl>
+      </div><br>
+      <br>
+      <a name="command" id="command"></a>
+
+      <h2 class="section1"><code>rbtenjin</code> Command</h2>
+
+      <p>See '<code>rbtenjin -h</code>' for details.</p><a name="command-syntax-check" id="command-syntax-check"></a>
+
+      <h3 class="section2">Syntax Check</h3>
+
+      <p>Command-line option '<code>-z</code>' checks syntax of template files. In addition '<code>-w</code>' option sets warning level to 2. It is recommended to use '-w' when you specify '-z' option.</p><a name="test_syntax_check/example.rbhtml"></a>
+
+      <div class="program_caption">
+        example.rbhtml
+      </div>
+      <pre class="program">
+&lt;ul&gt;
+&lt;?rb for item in items ?&gt;
+  &lt;li&gt;${item}&lt;/li&gt;
+&lt;?rb <strong>ende</strong> ?&gt;
+&lt;/ul&gt;
+</pre><a name="test_syntax_check/result.output"></a>
+
+      <div class="terminal_caption">
+        Result:
+      </div>
+      <pre class="terminal">
+$ rbtenjin <strong>-wz</strong> example.rbhtml
+example.rbhtml:5: syntax error, unexpected $end, expecting kEND
 </pre>
-<a name="user_create.rbhtml"></a>
-<div class="program_caption">
-File 'user_create.rbhtml':</div>
-<pre class="program">&lt;?rb #@ARGS ?&gt;
-&lt;form action="user_app.cgi" method="post"&gt;
-  &lt;input type="hidden" name="action" value="create" /&gt;
-<strong>&lt;?rb import :form ?&gt;</strong>
-  &lt;input type="submit" value="Create" /&gt;
-&lt;/form&gt;
-</pre>
-<a name="user_edit.rbhtml"></a>
-<div class="program_caption">
-File 'user_edit.rbhtml':</div>
-<pre class="program">&lt;?rb #@ARGS params ?&gt;
-&lt;form action="user_app.cgi" method="post"&gt;
-  &lt;input type="hidden" name="action" value="edit" /&gt;
-  &lt;input type="hidden" name="id" value="${params['id']}" /&gt;
-<strong>&lt;?rb import :form ?&gt;</strong>
-  &lt;input type="submit" value="Edit" /&gt;
-&lt;/form&gt;
-</pre>
-<a name="user_layout.rbhtml"></a>
-<div class="program_caption">
-File 'user_layout.rbhtml':</div>
-<pre class="program">&lt;?rb #@ARGS _content, title ?&gt;
-&lt;html&gt;
-  &lt;body&gt;
 
-    &lt;h1&gt;${title}&lt;/h1&gt;
+      <p>Command-line option '-wz' is more convenient than '<code>rbtenjin -s file | ruby -wc</code>' because the former can take several filenames.</p>
 
-    &lt;div id="main-content"&gt;
-<strong>#{_content}</strong>
-    &lt;/div&gt;
+      <p>Command-line option '-q' (quiet-mode) prints nothing if there are no syntax errors.</p><br>
+      <a name="command-convert-script" id="command-convert-script"></a>
 
-    &lt;div id="footer"&gt;
-<strong>&lt;?rb import 'footer.html' ?&gt;</strong>
-    &lt;/div&gt;
+      <h3 class="section2">Convert Template into Ruby Script</h3>
 
-  &lt;/body&gt;
-&lt;/html&gt;
+      <p>Command-line option '-s' converts template file into Ruby script code.</p><a name="test_convert/example.rbhtml"></a>
+
+      <div class="program_caption">
+        example.rbhtml
+      </div>
+      <pre class="program">
+&lt;ul&gt;
+  &lt;?rb for item in @items ?&gt;
+  &lt;li&gt;${item}&lt;/li&gt;
+  &lt;?rb end ?&gt;
+&lt;/ul&gt;
+</pre><a name="test_convert/result1.output"></a>
+
+      <div class="terminal_caption">
+        Result (-s)
+      </div>
+      <pre class="terminal">
+$ rbtenjin <strong>-s</strong> example.rbhtml
+_buf = '';  _buf &lt;&lt; %Q`&lt;ul&gt;\n`
+  for item in @items
+ _buf &lt;&lt; %Q`  &lt;li&gt;#{escape((item).to_s)}&lt;/li&gt;\n`
+  end
+ _buf &lt;&lt; %Q`&lt;/ul&gt;\n`
+_buf.to_s
 </pre>
-<a name="footer.html"></a>
-<div class="program_caption">
-File 'footer.html':</div>
-<pre class="program">&lt;?rb #@ARGS ?&gt;
-&lt;hr /&gt;
-&lt;address&gt;
-  &lt;a href="mailto:webmaster@example.com"&gt;webmaster@example.com&lt;/a&gt;
-&lt;/address&gt;
+
+      <p>Option '-b' removes preamble ('<code>_buf = ''</code>') and postamble ('<code>_buf.to_s)</code>').</p><a name="test_convert/result2.output"></a>
+
+      <div class="terminal_caption">
+        Result (-sb)
+      </div>
+      <pre class="terminal">
+$ rbtenjin -s<strong>b</strong> example.rbhtml
+ _buf &lt;&lt; %Q`&lt;ul&gt;\n`
+  for item in @items
+ _buf &lt;&lt; %Q`  &lt;li&gt;#{escape((item).to_s)}&lt;/li&gt;\n`
+  end
+ _buf &lt;&lt; %Q`&lt;/ul&gt;\n`
+</pre><br>
+      <a name="command-retrieve" id="command-retrieve"></a>
+
+      <h3 class="section2">Retrieve Embedded Code</h3>
+
+      <p>Tenjin allows you to retrieve embedded code from template files in order to help template debugging.</p>
+
+      <p>It is hard to debug large template files because HTML and embedded code are mixed in a file. Retrieving embedded code from template files will help you to debug large template files.</p>
+
+      <p>Assume the following template file.</p><a name="test_retrieve/example.rbhtml"></a>
+
+      <div class="program_caption">
+        example.rbhtml
+      </div>
+      <pre class="program">
+&lt;table&gt;
+  &lt;?rb i = 0 ?&gt;
+  &lt;?rb for item in @items ?&gt;
+  &lt;?rb   i += 1 ?&gt;
+  &lt;tr&gt;
+    &lt;td&gt;#{i}&lt;/td&gt;
+    &lt;td&gt;${item}&lt;/td&gt;
+  &lt;/tr&gt;
+  &lt;?rb end ?&gt;
+&lt;/table&gt;
 </pre>
-<a name="user_app.cgi"></a>
-<div class="program_caption">
-File 'user_app.cgi':</div>
-<pre class="program">#!/usr/bin/env ruby
 
-require 'cgi'
-<strong>require 'tenjin'</strong>
+      <p>Option '-S' (or '-a retrieve') retrieves embedded codes.</p><a name="test_retrieve/result1.output"></a>
 
-## set action ('create' or 'edit')
-action = nil
-cgi = nil
-if ENV['REQUEST_METHOD']
-  cgi = CGI.new
-  action = cgi['action']
-elsif ARGV[0]
-  action = ARGV[0]
-end
-action = 'create' unless ['create', 'edit'].include?(action)
-
-## set context data
-if action == 'create'
-  title = 'Create User'
-  params = {}
-else
-  title = 'Edit User'
-  params = {:name=&gt;'Margalette',
-            :email=&gt;'meg@example.com',
-	    :gender=&gt;'f',
-	    :id=&gt;123 }
-end
-<strong>context = { :title=&gt;title, :params=&gt;params }</strong>
-<strong># or context = Tenjin::Context.new(:title=&gt;title, :params=&gt;params)</strong>
+      <div class="terminal_caption">
+        Result (-Sb)
+      </div>
+      <pre class="terminal">
+$ rbtenjin -<strong>S</strong>b example.rbhtml
+
+  i = 0
+  for item in @items
+    i += 1
+
+
+        escape((item).to_s); 
+
+  end
 
-## create engine object
-layout = :layout   # or 'user_layout.rbhtml'
-<strong>engine = Tenjin::Engine.new(:prefix=&gt;'user_', :postfix=&gt;'.rbhtml', :layout=&gt;layout)</strong>
-
-## evaluate template
-template_name = action.intern   # :create or :edit
-<strong>output = engine.render(template_name, context)</strong>
-print cgi.header() if cgi
-print output
 </pre>
-<a name="user_app.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ ruby user_app.cgi create
-&lt;html&gt;
-  &lt;body&gt;
 
-    &lt;h1&gt;Create User&lt;/h1&gt;
+      <p>Option '-X' (or '-a statements') retrieves only statements.</p><a name="test_retrieve/result2.output"></a>
 
-    &lt;div id="main-content"&gt;
-<strong>&lt;form action="user_app.cgi" method="post"&gt;</strong>
-<strong>  &lt;input type="hidden" name="action" value="create" /&gt;</strong>
-<strong>&lt;p&gt;</strong>
-<strong>  Name:  &lt;input type="text" name="name"  value="" /&gt;&lt;br /&gt;</strong>
-<strong>  Email: &lt;input type="text" name="email" value="" /&gt;&lt;br /&gt;</strong>
-<strong>  Gender:</strong>
-<strong>  &lt;input type="radio" name="gender" value="m"  /&gt;Male</strong>
-<strong>  &lt;input type="radio" name="gender" value="f"  /&gt;Female</strong>
-<strong>&lt;/p&gt;</strong>
-<strong>  &lt;input type="submit" value="Create" /&gt;</strong>
-<strong>&lt;/form&gt;</strong>
+      <div class="terminal_caption">
+        Result (-Xb)
+      </div>
+      <pre class="terminal">
+$ rbtenjin -<strong>X</strong>b example.rbhtml
 
-    &lt;/div&gt;
+  i = 0
+  for item in @items
+    i += 1
 
-    &lt;div id="footer"&gt;
-<strong>&lt;hr /&gt;</strong>
-<strong>&lt;address&gt;</strong>
-<strong>  &lt;a href="mailto:webmaster@example.com"&gt;webmaster@example.com&lt;/a&gt;</strong>
-<strong>&lt;/address&gt;</strong>
-    &lt;/div&gt;
 
-  &lt;/body&gt;
-&lt;/html&gt;
+        
+
+  end
+
 </pre>
-<br>
-
-
-<a name="dev-initopts"></a>
-<h3 class="section2">Template Initialize Options</h3>
-<p>Tenjin::Template() can take the follwoing options.
-</p>
-<ul type="disc">
-<li>'<code>escapefunc</code>' (string) specifies function name to escape string.
-  Default is '<code>escape</code>' (= <code>Tenjin::Context#escape</code>).
-</li>
-</ul>
-<p>Constructor of Tenjin::Engine can also take the same options as above.
-These options given to constructor of Tenjin::Engine are passed to constructor of Tenjin::Template internally.
-</p>
-<a name="example15.rb"></a>
-<div class="program_caption">
-File 'example15.rb':</div>
-<pre class="program">require 'tenjin'
-filename = 'example14.rbhtml'
-template = Tenjin::Template.new(filename, <strong>:escapefunc=&gt;'CGI.escapeHTML'</strong>)
-print template.script, "\n"
-
-require 'cgi'
-title = 'rbTenjin Example'
-items = ['&lt;foo&gt;', '&amp;bar', '"baz"']
-output = template.render(:title=&gt;title, :items=&gt;items)
-print output
+
+      <p>Option '-N' adds line numbers.</p><a name="test_retrieve/result3.output"></a>
+
+      <div class="terminal_caption">
+        Result (-NXb)
+      </div>
+      <pre class="terminal">
+$ rbtenjin -<strong>N</strong>Xb example.rbhtml
+    1:  
+    2:    i = 0
+    3:    for item in @items
+    4:      i += 1
+    5:  
+    6:  
+    7:          
+    8:  
+    9:    end
+   10:  
 </pre>
-<a name="example15_escapefunc.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ ruby example15.rb
- _buf &lt;&lt; %Q`&lt;h1&gt;#{@title}&lt;/h1&gt;
-&lt;ul&gt;\n`
-for item in @items
- _buf &lt;&lt; %Q` &lt;li&gt;#{<strong>CGI.escapeHTML</strong>((item).to_s)}&lt;/li&gt;\n`
-end
- _buf &lt;&lt; %Q`&lt;/ul&gt;\n`
 
-&lt;h1&gt;rbTenjin Example&lt;/h1&gt;
+      <p>Option '-U' (unique) compress empty lines.</p><a name="test_retrieve/result4.output"></a>
+
+      <div class="terminal_caption">
+        Result (-UNXb)
+      </div>
+      <pre class="terminal">
+$ rbtenjin -<strong>U</strong>NXb example.rbhtml
+
+    2:    i = 0
+    3:    for item in @items
+    4:      i += 1
+
+    9:    end
+
+</pre>
+
+      <p>Option '-C' (compact) removes empty lines.</p><a name="test_retrieve/result5.output"></a>
+
+      <div class="terminal_caption">
+        Result (-CNXb)
+      </div>
+      <pre class="terminal">
+$ rbtenjin -<strong>C</strong>NXb example.rbhtml
+    2:    i = 0
+    3:    for item in @items
+    4:      i += 1
+    9:    end
+</pre><br>
+      <a name="command-execute-template" id="command-execute-template"></a>
+
+      <h3 class="section2">Execute Template File</h3>
+
+      <p>You can execute template file in command-line.</p><a name="test_execute/example.rbhtml"></a>
+
+      <div class="program_caption">
+        example.rbhtml
+      </div>
+      <pre class="program">
+&lt;?rb @items = ['&lt;AAA&gt;', 'B&amp;B', '"CCC"'] ?&gt;
 &lt;ul&gt;
- &lt;li&gt;&amp;lt;foo&amp;gt;&lt;/li&gt;
- &lt;li&gt;&amp;amp;bar&lt;/li&gt;
- &lt;li&gt;&amp;quot;baz&amp;quot;&lt;/li&gt;
+  &lt;?rb for item in @items ?&gt;
+  &lt;li&gt;${item}&lt;/li&gt;
+  &lt;?rb end ?&gt;
 &lt;/ul&gt;
-</pre>
-<br>
-
-
-<a name="dev-helpers"></a>
-<h3 class="section2">Add Your Helper Functions</h3>
-<p>There are several ways to use helper functions.
-</p>
-<p>Assume the following template.
-</p>
-<a name="example16.rbhtml"></a>
-<div class="program_caption">
-File 'example16.rbhtml':</div>
-<pre class="program">&lt;?rb #@ARGS label, url ?&gt;
+</pre><a name="test_execute/result.output"></a>
+
+      <div class="terminal_caption">
+        Result
+      </div>
+      <pre class="terminal">
+$ rbtenjin example.rbhtml
 &lt;ul&gt;
-  &lt;li&gt;#{<strong>link_to(label, url)</strong>}&lt;/li&gt;
+  &lt;li&gt;&amp;lt;AAA&amp;gt;&lt;/li&gt;
+  &lt;li&gt;B&amp;amp;B&lt;/li&gt;
+  &lt;li&gt;&amp;quot;CCC&amp;quot;&lt;/li&gt;
 &lt;/ul&gt;
-</pre>
-<p>(A) Define helper functions as global function.
-</p>
-<a name="example16a.rb"></a>
-<div class="program_caption">
-File 'example16a.rb':</div>
-<pre class="program">require 'tenjin'
+</pre><br>
+      <a name="command-context-data" id="command-context-data"></a>
 
-def link_to(label, url)
-  return "&lt;a href=\"#{escape_xml(url)}\"&gt;#{escape_xml(label)}&lt;/a&gt;"
-end
+      <h3 class="section2">Context Data</h3>
 
-engine = Tenjin::Engine.new()
-context = { :label=&gt;'Top', :url=&gt;'/' }
-output = engine.render('example16.rbhtml', context)
-print output
-</pre>
-<a name="example16a.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ ruby example16a.rb
+      <p>You can specify context data with command-line option '<code>-c</code>'.</p><a name="test_context/example.rbhtml"></a>
+
+      <div class="program_caption">
+        example.rbhtml
+      </div>
+      <pre class="program">
 &lt;ul&gt;
-  &lt;li&gt;&lt;a href="/"&gt;Top&lt;/a&gt;&lt;/li&gt;
+  &lt;?rb for item in @items ?&gt;
+  &lt;li&gt;${item}&lt;/li&gt;
+  &lt;?rb end ?&gt;
 &lt;/ul&gt;
-</pre>
-<p>(B) Define helper functions as module function of Tenjin::ContextHelper module.
-</p>
-<a name="example16b.rb"></a>
-<div class="program_caption">
-File 'example16b.rb':</div>
-<pre class="program">require 'tenjin'
-
-<strong>module Tenjin::ContextHelper</strong>
-  module_function
-  def link_to(label, url)
-    return "&lt;a href=\"#{escape_xml(url)}\"&gt;#{escape_xml(label)}&lt;/a&gt;"
-  end
-<strong>end</strong>
+</pre><a name="test_context/result1.output"></a>
 
-engine = Tenjin::Engine.new()
-context = { :label=&gt;'Top', :url=&gt;'/' }
-output = engine.render('example16.rbhtml', context)
-print output
-</pre>
-<a name="example16b.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ ruby example16b.rb
+      <div class="terminal_caption">
+        Result
+      </div>
+      <pre class="terminal">
+$ rbtenjin <strong>-c '@items=["A","B","C"]'</strong> example.rbhtml
 &lt;ul&gt;
-  &lt;li&gt;&lt;a href="/"&gt;Top&lt;/a&gt;&lt;/li&gt;
+  &lt;li&gt;A&lt;/li&gt;
+  &lt;li&gt;B&lt;/li&gt;
+  &lt;li&gt;C&lt;/li&gt;
 &lt;/ul&gt;
 </pre>
-<p>(C) Define subclass of Tenjin::Context and define helper functions as instance method.
-</p>
-<a name="example16c.rb"></a>
-<div class="program_caption">
-File 'example16c.rb':</div>
-<pre class="program">require 'tenjin'
-
-<strong>class MyContext &lt; Tenjin::Context</strong>
-  def link_to(label, url)
-    return "&lt;a href=\"#{escape_xml(url)}\"&gt;#{escape_xml(label)}&lt;/a&gt;"
-  end
-<strong>end</strong>
 
-engine = Tenjin::Engine.new()
-<strong>context = MyContext.new(:label=&gt;'Top', :url=&gt;'/')</strong>
-output = engine.render('example16.rbhtml', context)
-print output
-</pre>
-<a name="example16c.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ ruby example16c.rb
+      <p>If you want to specify several values, separate them by ';' such as '-c "@x=10;@y=20"'.</p>
+
+      <p>If you installed yaml library, you can specify context data in YAML format. Tenjin regards context data string as YAML format if it starts with '{'.</p><a name="test_context/result2.output"></a>
+
+      <div class="terminal_caption">
+        Result
+      </div>
+      <pre class="terminal">
+$ rbtenjin <strong>-c '{items: [A, B, C]}'</strong> example.rbhtml
 &lt;ul&gt;
-  &lt;li&gt;&lt;a href="/"&gt;Top&lt;/a&gt;&lt;/li&gt;
+  &lt;li&gt;A&lt;/li&gt;
+  &lt;li&gt;B&lt;/li&gt;
+  &lt;li&gt;C&lt;/li&gt;
 &lt;/ul&gt;
 </pre>
-<p>(D) Define helper functions in current class, set context data as instance variables, and pass self as context object
-</p>
-<a name="example16d.rb"></a>
-<div class="program_caption">
-File 'example16d.rb':</div>
-<pre class="program">require 'tenjin'
-
-class MyClass
-  <strong>include Tenjin::ContextHelper</strong>
-  <strong>#include Tenjin::HtmlHelper</strong>  # optional
-
-  def link_to(label, url)    # define helper functions in current class
-    return "&lt;a href=\"#{escape(url)}\"&gt;#{escape(label)}&lt;/a&gt;"
-  end
 
-  def render_template(template_name)
-    engine = Tenjin::Engine.new()
-    output = engine.render(template_name, <strong>self</strong>)  # pass self as context object
-    return output
-  end
-
-  def main
-    ## set context data as instance variables
-    <strong>@label = 'Top'</strong>
-    <strong>@url = '/'</strong>
-    output = render_template('example16.rbhtml')
-    print output
-  end
+      <p>In addition, Tenjin supports context data file in Ruby format or YAML format.</p><a name="test_context/context.rb"></a>
 
-end
+      <div class="program_caption">
+        context.rb
+      </div>
+      <pre class="program">
+@items = [
+   "AAA",
+   123,
+   true,
+]
+</pre><a name="test_context/result3.output"></a>
 
-MyClass.new.main()
-</pre>
-<a name="example16d.result"></a>
-<div class="terminal_caption">
-Result:</div>
-<pre class="terminal">$ ruby example16d.rb
+      <div class="terminal_caption">
+        Result
+      </div>
+      <pre class="terminal">
+$ rbtenjin <strong>-f context.rb</strong> example.rbhtml
 &lt;ul&gt;
-  &lt;li&gt;&lt;a href="/"&gt;Top&lt;/a&gt;&lt;/li&gt;
+  &lt;li&gt;AAA&lt;/li&gt;
+  &lt;li&gt;123&lt;/li&gt;
+  &lt;li&gt;true&lt;/li&gt;
 &lt;/ul&gt;
-</pre>
-<br>
+</pre><a name="test_context/context.yaml"></a>
 
+      <div class="program_caption">
+        context.yaml
+      </div>
+      <pre class="program">
+items:
+  - AAA
+  - 123
+  - true
+</pre><a name="test_context/result4.output"></a>
+
+      <div class="terminal_caption">
+        Result
+      </div>
+      <pre class="terminal">
+$ rbtenjin <strong>-f context.yaml</strong> example.rbhtml
+&lt;ul&gt;
+  &lt;li&gt;AAA&lt;/li&gt;
+  &lt;li&gt;123&lt;/li&gt;
+  &lt;li&gt;true&lt;/li&gt;
+&lt;/ul&gt;
+</pre><br>
+      <br>
+      <a name="shooting" id="shooting"></a>
 
-<a name="dev-othertopics"></a>
-<h3 class="section2">Other Topics</h3>
-<ul type="disc">
-<li>Tenjin::Template detects newline character ("\n" or "\r\n") automatically.
-   If input file contains "\r\n", rbTenjin generates output which contains "\r\n".
-</li>
-</ul>
-<ul type="disc">
-<li>Tenjin::Template#render() can be called many times.
-   If you create a Tenjin::Template object, you can call render() method many times.
-</li>
-</ul>
-<ul type="disc">
-<li>Tenjin::Template#convert() also can be called many times.
-  If you create a Tenjin::Template object, you can call convert() (and also render()) method many times.
-</li>
-</ul>
-<br>
+      <h2 class="section1">Trouble shooting</h2>
 
+      <p>(not documented yet)</p><br>
+      <a name="customize" id="customize"></a>
 
-<br>
+      <h2 class="section1">Customization Examples</h2>
 
+      <p>This section shows how to customize rbTenjin.</p>
 
+      <p><strong>Notice that these customization may be changed in the future release.</strong></p>
 
-   </div>
+      <p>(not documented yet)</p><br>
+    </div>
   </blockquote>
-
- </body>
+</body>
 </html>