- [bufix] XmlEruby outs <%=== expr %> to $stdout, it changed to $stderr

- [change] rename var name 'kind' to 'indicator' in Eruby#compile()
- [enhance] add doc/users-guide.txt
- [enhance] add command-line option '-I lib'

6 files changed, 1441 insertions, 63 deletions

diff --git a/doc/Rookbook b/doc/Rookbook
index 0f969ff..4f33ad7 100644
--- a/doc/Rookbook
+++ b/doc/Rookbook
@@ -17,9 +17,24 @@ grecipe '*.html'	, '{1}.txt'		do |r|
 	rm "{1}.toc.html"
     end
 
+
+u = 'users-guide'
+tagfile = 'html-css'
+grecipe "#{u}.html"	, "#{u}.txt"		do |r|
+	rm_rf "guide.d"
+	mkdir_p "guide.d"
+	cmd "retrieve -d guide.d #{u}.txt"
+	cmd "kwaser -t #{tagfile} -T #{u}.txt > #{u}.toc.html"
+	cmd "kwaser -t #{tagfile}    #{u}.txt > #{u}.html"
+	rm "#{u}.toc.html"
+    end
+
+
 recipe :html,	textfile.sub(/\.txt/, '.html')
 
 recipe :clean	do |r|
 	list = `retrieve -l #{textfile}`
 	rm_rf list.split
     end
+
+
diff --git a/doc/docstyle.css b/doc/docstyle.css
new file mode 100644
index 0000000..837d96e
--- /dev/null
+++ b/doc/docstyle.css
@@ -0,0 +1,188 @@
+body {
+	background-color:#FFFFFF;
+}
+
+.mainbody {
+	color:#333333;
+	line-height:150%;
+	margin: 5px 30px 5px 30px;
+}
+
+a:link, a:active, a:hover {
+	color:#CC6600;
+}
+
+a:visited {
+	color:#DD9900;
+}
+
+p {
+	color:#333333;
+	line-height:150%;
+}
+
+pre {
+	width: 100%;
+	line-height:130%;
+	white-space:pre;
+}
+
+.program {
+	border-style:solid;
+	border-width:1px;
+	border-color:#6699FF;
+	color:#333333;
+	background-color:#DDEEFF;
+	padding:8px 9px 8px 9px;
+	margin:0px;
+	word-break:break-all;
+}
+
+.terminal {
+	border-style:solid;
+	border-width:1;
+	border-color:#999999;
+	color:#333333;
+	background-color:#E0E0E0;
+	padding:9px 10px 9px 10px;
+	margin:0px;
+	word-break:break-all;
+}
+
+.output {
+	border-style:solid;
+	border-width:1px;
+	border-color:#CCCCCC;
+	color:#333333;
+	background-color:#FFFFFF;
+	padding:8px 9px 8px 9px;
+	margin:0px;
+	word-break:break-all;
+}
+
+
+.program_caption {
+        margin-top: 20px;
+}
+
+.terminal_caption {
+        margin-top: 20px;
+}
+
+.output_caption {
+        margin-top: 20px;
+}
+
+
+ul,ol,dl {
+	/* margin:0px; */
+	/* padding:0px; */
+	color:#333333;
+	line-height:140%;
+}
+
+.dt2, .dt3 {
+	font-weight:bold;
+}
+
+.table1 {
+	padding:2px;
+	color:#333333;
+	background-color:#DDDDCC;
+	line-height:130%;
+	/*
+	border-width:1px;
+	border-style:solid;
+	border-color:#FFFFFF;
+	*/
+	margin:5;
+}
+
+.th1, .th2 {
+	padding:1px;
+	color:#333333;
+	/* background-color:#DDDDCC; */
+	background-color:#CCCCBB;
+	line-height:130%;
+}
+
+.td1, .th2 {
+	padding:1px;
+	color:#333333;
+	background-color:#EEEEDD;
+	line-height:130%;
+}
+
+.caption1, .caption2 {
+	/* font-size:x-small; */
+	color:#333333;
+}
+
+.table2 {
+	padding:1px;
+	color:#333333;
+	background-color:#DDDDCC;
+	line-height:130%;
+	/*
+	border-width:1px;
+	border-style:solid;
+	border-color:#FFFFFF;
+	*/
+	margin:5;
+}
+
+h1, .chapter, .doctitle {
+	color:#333333;
+	font-weight:bold;
+	padding:30px 0px 10px 0px;
+}
+
+h2, .section {
+	color:#333333;
+	font-weight:bold;
+	border-style:solid;
+	border-color:#6699FF;
+	border-width:0px 0px 2px 30px;
+	padding:10px 20px 0px 5px;
+}
+
+h3, .subsection {
+	color:#333333;
+	font-weight:bold;
+	border-style:solid;
+	border-color:#6699FF;
+	border-width: 0px 0px 0px 15px;
+	padding: 10px 20px 0px 5px;
+}
+
+.em {
+	font-weight:bold;
+}
+
+.toc {
+	/* font-size:small; */
+	/* line-height:100%; */
+}
+
+.footnote {
+	font-size:small;
+}
+
+.note {
+	background-color:#FFFFDD;
+	border-style:solid;
+	border-width:0px 1px 0px 1px;
+	border-color:#DDDD66;
+	color:#333300;
+	/* font-size:small; */
+	line-height:120%;
+	padding: 5px 20px 5px 20px;
+}
+
+.figure {
+	/*
+	border-width:1px;
+	border-color:#DDDD66;
+	white-space:pre;
+	*/
+}
diff --git a/doc/eruby.html b/doc/eruby.html
index 60ae764..bf4b963 100644
--- a/doc/eruby.html
+++ b/doc/eruby.html
@@ -216,16 +216,16 @@ class Eruby
   def compile(input=@input)
     src = "_out = ''; "
     regexp = /(.*?)<%(=?)(.*?)%>/m
-    input.scan(regexp) do |text, kind, code|
+    input.scan(regexp) do |text, indicator, code|
       ## テキストを処理
       text.each_line do |line|
         src << "_out << #{line.dump}" << (line[-1] == ?\n ? "\n" : "; ")
       end
 
       ## 埋め込み Ruby コードを処理
-      if kind == '='  # <%= %> の場合
+      if indicator == '='  # <%= %> の場合
         src << "_out << (#{code}).to_s; "
-      else            # <%  %> の場合
+      else                 # <%  %> の場合
         code.each_line { |line| src << line }
         src << "; " unless code[-1] == ?\n
       end
@@ -316,14 +316,14 @@ class Eruby
     <strong>src = ""</strong>
     <strong>initialize_src(src)</strong>
     regexp = /(.*?)&lt;%(=?)(.*?)%&gt;/m
-    input.scan(regexp) do |text, kind, code|
+    input.scan(regexp) do |text, indicator, code|
       ## テキストを処理
       <strong>add_src_text(src, text)</strong>
 
       ## 埋め込み Ruby コードを処理
-      if kind == '='  # &lt;%= %&gt; の場合
+      if indicator == '='  # &lt;%= %&gt; の場合
         <strong>add_src_expr(src, code)</strong>
-      else            # &lt;%  %&gt; の場合
+      else                 # &lt;%  %&gt; の場合
         <strong>add_src_code(src, code)</strong>
       end
     end
@@ -369,7 +369,7 @@ end
 stdout-eruby.rb : 標準出力を使う Eruby</div>
 <pre class="program">##
 ## 文字列ではなく標準出力を使う Eruby
-## (「&lt;% print var %&gt;」が問題なく使えるようになる)
+## (「&lt;% print expr %&gt;」が使えるようになる)
 ##
 class StdoutEruby &lt; Eruby
 
@@ -478,12 +478,12 @@ class Eruby
     src = ""
     initialize_src(src)
     regexp = /(.*?)<strong>(^[ \t]*)?</strong>&lt;%(=?)(.*?)%&gt;<strong>([ \t]*\r?\n)?</strong>/m
-    input.scan(regexp) do |text, <strong>head_space,</strong> kind, code<strong>, tail_space</strong>|
+    input.scan(regexp) do |text, <strong>head_space,</strong> indicator, code<strong>, tail_space</strong>|
       <strong>## * &lt;%= %&gt; のときは、何もしない</strong>
       <strong>## * &lt;% %&gt; のときは、</strong>
       <strong>##    * 前後が空白だけのときは、その空白を削除</strong>
       <strong>##    * そうでないときは、何もしない（空白を残す）</strong>
-      <strong>flag_trim = kind != '=' &amp;&amp; head_space &amp;&amp; tail_space</strong>
+      <strong>flag_trim = indicator != '=' &amp;&amp; head_space &amp;&amp; tail_space</strong>
 
       ## テキストを処理
       add_src_text(src, text)
@@ -494,9 +494,9 @@ class Eruby
       <strong>end</strong>
 
       ## 埋め込み Ruby コードを処理
-      if kind == '='  # &lt;%= %&gt; の場合
+      if indicator == '='  # &lt;%= %&gt; の場合
         add_src_expr(src, code)
-      else            # &lt;%  %&gt; の場合
+      else                 # &lt;%  %&gt; の場合
         <strong>## 改行を含めた前後の空白をコードに足す</strong>
         <strong>code = "#{head_space}#{code}#{tail_space}" if flag_trim</strong>
         add_src_code(src, code)
@@ -623,12 +623,12 @@ class Eruby
     src = ""
     initialize_src(src)
     regexp = /(.*?)(^[ \t]*)?&lt;%(<strong>=*</strong>)(.*?)%&gt;([ \t]*\r?\n)?/m
-    input.scan(regexp) do |text, head_space, kind, code, tail_space|
+    input.scan(regexp) do |text, head_space, indicator, code, tail_space|
       ## * &lt;%= %&gt; のときは、何もしない
       ## * &lt;% %&gt; のときは、
       ##    * 前後が空白だけのときは、その空白を削除
       ##    * そうでないときは、何もしない（空白を残す）
-      flag_trim = <strong>kind.empty?</strong> &amp;&amp; head_space &amp;&amp; tail_space
+      flag_trim = <strong>indicator.empty?</strong> &amp;&amp; head_space &amp;&amp; tail_space
 
       ## テキストを処理
       add_src_text(src, text)
@@ -639,9 +639,9 @@ class Eruby
       end
 
       ## 埋め込み Ruby コードを処理
-      if <strong>!kind.empty?</strong>  # &lt;%= %&gt; の場合
-        add_src_expr(src, code<strong>, kind.length</strong>)
-      else             # &lt;%  %&gt; の場合
+      if <strong>!indicator.empty?</strong>  # &lt;%= %&gt; の場合
+        add_src_expr(src, code<strong>, indicator</strong>)
+      else                  # &lt;%  %&gt; の場合
         ## 改行を含めた前後の空白をコードに足す
         code = "#{head_space}#{code}#{tail_space}" if flag_trim
         add_src_code(src, code)
@@ -674,7 +674,7 @@ class Eruby
     end
   end
 
-  def add_src_expr(src, code, length)
+  def add_src_expr(src, code, indicator)
     src &lt;&lt; "_out &lt;&lt; (#{code}).to_s; "
   end
 
@@ -710,8 +710,8 @@ class XmlEruby &lt; Eruby
     return str
   end
 
-  <strong>def add_src_expr(src, code, length)</strong>
-    <strong>if length == 1</strong>
+  <strong>def add_src_expr(src, code, indicator)</strong>
+    <strong>if indicator == '='</strong>
       <strong>src &lt;&lt; "_out &lt;&lt; XmlEruby.escape(#{code}); "</strong>
     <strong>else</strong>
       <strong>super</strong>
@@ -798,12 +798,12 @@ class Eruby
     initialize_src(src)
     <strong>prefix, postfix = @pattern.split()   # 埋め込みパターン</strong>
     regexp = /(.*?)(^[ \t]*)?<strong>#{prefix}</strong>(=*)(.*?)<strong>#{postfix}</strong>([ \t]*\r?\n)?/m
-    input.scan(regexp) do |text, head_space, kind, code, tail_space|
+    input.scan(regexp) do |text, head_space, indicator, code, tail_space|
       ## * &lt;%= %&gt; のときは、何もしない
       ## * &lt;% %&gt; のときは、
       ##    * 前後が空白だけのときは、その空白を削除
       ##    * そうでないときは、何もしない（空白を残す）
-      flag_trim = kind.empty? &amp;&amp; head_space &amp;&amp; tail_space
+      flag_trim = indicator.empty? &amp;&amp; head_space &amp;&amp; tail_space
 
       ## テキストを処理
       add_src_text(src, text)
@@ -814,9 +814,9 @@ class Eruby
       end
 
       ## 埋め込み Ruby コードを処理
-      if !kind.empty?  # &lt;%= %&gt; の場合
-        add_src_expr(src, code, kind.length)
-      else             # &lt;%  %&gt; の場合
+      if !indicator.empty?  # &lt;%= %&gt; の場合
+        add_src_expr(src, code, indicator)
+      else                  # &lt;%  %&gt; の場合
         ## 改行を含めた前後の空白をコードに足す
         code = "#{head_space}#{code}#{tail_space}" if flag_trim
         add_src_code(src, code)
@@ -849,7 +849,7 @@ class Eruby
     end
   end
 
-  def add_src_expr(src, code, length)
+  def add_src_expr(src, code, indicator)
     src &lt;&lt; "_out &lt;&lt; (#{code}).to_s; "
   end
 
@@ -947,12 +947,12 @@ class Eruby
     initialize_src(src)
     prefix, postfix = @pattern.split()   # 埋め込みパターン
     regexp = /(.*?)(^[ \t]*)?#{prefix}(=*)(.*?)#{postfix}([ \t]*\r?\n)?/m
-    input.scan(regexp) do |text, head_space, kind, code, tail_space|
+    input.scan(regexp) do |text, head_space, indicator, code, tail_space|
       ## * &lt;%= %&gt; のときは、何もしない
       ## * &lt;% %&gt; のときは、
       ##    * 前後が空白だけのときは、その空白を削除
       ##    * そうでないときは、何もしない（空白を残す）
-      flag_trim = kind.empty? &amp;&amp; head_space &amp;&amp; tail_space
+      flag_trim = indicator.empty? &amp;&amp; head_space &amp;&amp; tail_space
 
       ## テキストを処理
       add_src_text(src, text)
@@ -963,9 +963,9 @@ class Eruby
       end
 
       ## 埋め込み Ruby コードを処理
-      if !kind.empty?  # &lt;%= %&gt; の場合
-        add_src_expr(src, code, kind.length)
-      else             # &lt;%  %&gt; の場合
+      if !indicator.empty?  # &lt;%= %&gt; の場合
+        add_src_expr(src, code, indicator)
+      else                  # &lt;%  %&gt; の場合
         ## 改行を含めた前後の空白をコードに足す
         code = "#{head_space}#{code}#{tail_space}" if flag_trim
         add_src_code(src, code)
@@ -998,7 +998,7 @@ class Eruby
     end
   end
 
-  def add_src_expr(src, code, length)
+  def add_src_expr(src, code, indicator)
     src &lt;&lt; "_out &lt;&lt; (#{code}).to_s; "
   end
 
@@ -1012,7 +1012,6 @@ class Eruby
   end
 
 end
-
 </pre>
 <a name="example6.rb"></a>
 <div class="program_caption">
diff --git a/doc/eruby.txt b/doc/eruby.txt
index d5098e3..85f8057 100644
--- a/doc/eruby.txt
+++ b/doc/eruby.txt
@@ -32,16 +32,16 @@ class Eruby
   def compile(input=@input)
     src = "_out = ''; "
     regexp = /(.*?)<%(=?)(.*?)%>/m
-    input.scan(regexp) do |text, kind, code|
+    input.scan(regexp) do |text, indicator, code|
       ## テキストを処理
       text.each_line do |line|
         src << "_out << #{line.dump}" << (line[-1] == ?\n ? "\n" : "; ")
       end
 
       ## 埋め込み Ruby コードを処理
-      if kind == '='  # <%= %> の場合
+      if indicator == '='  # <%= %> の場合
         src << "_out << (#{code}).to_s; "
-      else            # <%  %> の場合
+      else                 # <%  %> の場合
         code.each_line { |line| src << line }
         src << "; " unless code[-1] == ?\n
       end
@@ -126,14 +126,14 @@ class Eruby
     {{*src = ""*}}
     {{*initialize_src(src)*}}
     regexp = /(.*?)<%(=?)(.*?)%>/m
-    input.scan(regexp) do |text, kind, code|
+    input.scan(regexp) do |text, indicator, code|
       ## テキストを処理
       {{*add_src_text(src, text)*}}
 
       ## 埋め込み Ruby コードを処理
-      if kind == '='  # <%= %> の場合
+      if indicator == '='  # <%= %> の場合
         {{*add_src_expr(src, code)*}}
-      else            # <%  %> の場合
+      else                 # <%  %> の場合
         {{*add_src_code(src, code)*}}
       end
     end
@@ -280,12 +280,12 @@ class Eruby
     src = ""
     initialize_src(src)
     regexp = /(.*?){{*(^[ \t]*)?*}}<%(=?)(.*?)%>{{*([ \t]*\r?\n)?*}}/m
-    input.scan(regexp) do |text, {{*head_space,*}} kind, code{{*, tail_space*}}|
+    input.scan(regexp) do |text, {{*head_space,*}} indicator, code{{*, tail_space*}}|
       {{*## * <%= %> のときは、何もしない*}}
       {{*## * <% %> のときは、*}}
       {{*##    * 前後が空白だけのときは、その空白を削除*}}
       {{*##    * そうでないときは、何もしない（空白を残す）*}}
-      {{*flag_trim = kind != '=' && head_space && tail_space*}}
+      {{*flag_trim = indicator != '=' && head_space && tail_space*}}
 
       ## テキストを処理
       add_src_text(src, text)
@@ -296,9 +296,9 @@ class Eruby
       {{*end*}}
 
       ## 埋め込み Ruby コードを処理
-      if kind == '='  # <%= %> の場合
+      if indicator == '='  # <%= %> の場合
         add_src_expr(src, code)
-      else            # <%  %> の場合
+      else                 # <%  %> の場合
         {{*## 改行を含めた前後の空白をコードに足す*}}
         {{*code = "#{head_space}#{code}#{tail_space}" if flag_trim*}}
         add_src_code(src, code)
@@ -416,12 +416,12 @@ class Eruby
     src = ""
     initialize_src(src)
     regexp = /(.*?)(^[ \t]*)?<%({{*=**}})(.*?)%>([ \t]*\r?\n)?/m
-    input.scan(regexp) do |text, head_space, kind, code, tail_space|
+    input.scan(regexp) do |text, head_space, indicator, code, tail_space|
       ## * <%= %> のときは、何もしない
       ## * <% %> のときは、
       ##    * 前後が空白だけのときは、その空白を削除
       ##    * そうでないときは、何もしない（空白を残す）
-      flag_trim = {{*kind.empty?*}} && head_space && tail_space
+      flag_trim = {{*indicator.empty?*}} && head_space && tail_space
 
       ## テキストを処理
       add_src_text(src, text)
@@ -432,9 +432,9 @@ class Eruby
       end
 
       ## 埋め込み Ruby コードを処理
-      if {{*!kind.empty?*}}  # <%= %> の場合
-        add_src_expr(src, code{{*, kind.length*}})
-      else             # <%  %> の場合
+      if {{*!indicator.empty?*}}  # <%= %> の場合
+        add_src_expr(src, code{{*, indicator*}})
+      else                  # <%  %> の場合
         ## 改行を含めた前後の空白をコードに足す
         code = "#{head_space}#{code}#{tail_space}" if flag_trim
         add_src_code(src, code)
@@ -467,7 +467,7 @@ class Eruby
     end
   end
 
-  def add_src_expr(src, code, length)
+  def add_src_expr(src, code, indicator)
     src << "_out << (#{code}).to_s; "
   end
 
@@ -504,8 +504,8 @@ class XmlEruby < Eruby
     return str
   end
 
-  {{*def add_src_expr(src, code, length)*}}
-    {{*if length == 1*}}
+  {{*def add_src_expr(src, code, indicator)*}}
+    {{*if indicator == '='*}}
       {{*src << "_out << XmlEruby.escape(#{code}); "*}}
     {{*else*}}
       {{*super*}}
@@ -588,12 +588,12 @@ class Eruby
     initialize_src(src)
     {{*prefix, postfix = @pattern.split()   # 埋め込みパターン*}}
     regexp = /(.*?)(^[ \t]*)?{{*#{prefix}*}}(=*)(.*?){{*#{postfix}*}}([ \t]*\r?\n)?/m
-    input.scan(regexp) do |text, head_space, kind, code, tail_space|
+    input.scan(regexp) do |text, head_space, indicator, code, tail_space|
       ## * <%= %> のときは、何もしない
       ## * <% %> のときは、
       ##    * 前後が空白だけのときは、その空白を削除
       ##    * そうでないときは、何もしない（空白を残す）
-      flag_trim = kind.empty? && head_space && tail_space
+      flag_trim = indicator.empty? && head_space && tail_space
 
       ## テキストを処理
       add_src_text(src, text)
@@ -604,9 +604,9 @@ class Eruby
       end
 
       ## 埋め込み Ruby コードを処理
-      if !kind.empty?  # <%= %> の場合
-        add_src_expr(src, code, kind.length)
-      else             # <%  %> の場合
+      if !indicator.empty?  # <%= %> の場合
+        add_src_expr(src, code, indicator)
+      else                  # <%  %> の場合
         ## 改行を含めた前後の空白をコードに足す
         code = "#{head_space}#{code}#{tail_space}" if flag_trim
         add_src_code(src, code)
@@ -639,7 +639,7 @@ class Eruby
     end
   end
 
-  def add_src_expr(src, code, length)
+  def add_src_expr(src, code, indicator)
     src << "_out << (#{code}).to_s; "
   end
 
@@ -735,12 +735,12 @@ class Eruby
     initialize_src(src)
     prefix, postfix = @pattern.split()   # 埋め込みパターン
     regexp = /(.*?)(^[ \t]*)?#{prefix}(=*)(.*?)#{postfix}([ \t]*\r?\n)?/m
-    input.scan(regexp) do |text, head_space, kind, code, tail_space|
+    input.scan(regexp) do |text, head_space, indicator, code, tail_space|
       ## * <%= %> のときは、何もしない
       ## * <% %> のときは、
       ##    * 前後が空白だけのときは、その空白を削除
       ##    * そうでないときは、何もしない（空白を残す）
-      flag_trim = kind.empty? && head_space && tail_space
+      flag_trim = indicator.empty? && head_space && tail_space
 
       ## テキストを処理
       add_src_text(src, text)
@@ -751,9 +751,9 @@ class Eruby
       end
 
       ## 埋め込み Ruby コードを処理
-      if !kind.empty?  # <%= %> の場合
-        add_src_expr(src, code, kind.length)
-      else             # <%  %> の場合
+      if !indicator.empty?  # <%= %> の場合
+        add_src_expr(src, code, indicator)
+      else                  # <%  %> の場合
         ## 改行を含めた前後の空白をコードに足す
         code = "#{head_space}#{code}#{tail_space}" if flag_trim
         add_src_code(src, code)
@@ -786,7 +786,7 @@ class Eruby
     end
   end
 
-  def add_src_expr(src, code, length)
+  def add_src_expr(src, code, indicator)
     src << "_out << (#{code}).to_s; "
   end
 
@@ -800,7 +800,6 @@ class Eruby
   end
 
 end
-
 .--------------------
 
 
diff --git a/doc/users-guide.html b/doc/users-guide.html
new file mode 100644
index 0000000..4df57b3
--- /dev/null
+++ b/doc/users-guide.html
@@ -0,0 +1,676 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html">
+  <title>Erubis Users' 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>
+
+  <blockquote>
+   <div class="mainbody">
+
+    <div align="left"><h1>Erubis Users' Guide</h1></div>
+    <div align="left">
+      last update: $Date$<br>
+    </div>
+
+<a name="preface"></a>
+<h2 class="section1">Preface</h2>
+<p>Erubis is an implementation of eRuby.
+It has the following features.
+</p>
+<ul type="disc">
+<li>Auto trimming spaces around '&lt;% %&gt;'
+</li>
+<li>Auto sanitizing
+</li>
+<li>Change embedded pattern (default '&lt;% %&gt;')
+</li>
+<li>Context object available
+</li>
+<li>Easy to expand in subclass
+</li>
+</ul>
+<p>Erubis is implemented in pure Ruby.  It requires Ruby 1.8 or higher.
+</p>
+<a name="toc"></a>
+<h3 class="section2">Table of Contents</h3>
+<ul>
+  <li><a href="#preface">Preface</a>
+  <ul>
+    <li><a href="#toc">Table of Contents</a>
+    </li>
+  </ul>
+  </li>
+  <li><a href="#install">Installation</a>
+  </li>
+  <li><a href="#tutorial">Tutorial</a>
+  <ul>
+    <li><a href="#tut-basic">Basic Example</a>
+    </li>
+    <li><a href="#tut-trim">Trimming Spaces</a>
+    </li>
+    <li><a href="#tut-xml">Auto Sanitizing</a>
+    </li>
+    <li><a href="#tut-pattern">Embedded Pattern</a>
+    </li>
+    <li><a href="#tut-context">Context Object</a>
+    </li>
+    <li><a href="#tut-fast">Faster Eruby</a>
+    </li>
+    <li><a href="#tut-stdout">Stdout Eruby</a>
+    </li>
+  </ul>
+  </li>
+  <li><a href="#command">Command Reference</a>
+  <ul>
+    <li><a href="#command-usage">Usage</a>
+    </li>
+    <li><a href="#command-options">Options</a>
+    </li>
+  </ul>
+  </li>
+</ul>
+<br>
+
+
+<br>
+
+
+<a name="install"></a>
+<h2 class="section1">Installation</h2>
+<ul type="disc">
+<li>If you have installed RubyGems, just type <code>gem install --remote erubis</code>.
+<pre class="terminal">$ sudo gem install --remote erubis
+</pre>
+</li>
+</ul>
+<ul type="disc">
+<li>Or if you can be root user, download erubis-X.X.X.tar.bz2 and install by setup.rb.
+<pre class="terminal">$ tar xjf erubis-X.X.X.tar.bz2
+$ cd erubis-X.X.X/
+$ ruby setup.rb config
+$ ruby setup.rb setup
+$ sudo ruby setup.rb install
+</pre>
+</li>
+</ul>
+<ul type="disc">
+<li>Else you should copy 'lib/erubis.rb' and 'bin/erubis' into proper directory manually.
+<pre class="terminal">$ tar xjf erubis-X.X.X.tar.bz2
+$ cd erubis-X.X.X/
+$ cp lib/erubis.rb /usr/local/lib/ruby/site_ruby/1.8
+$ cp bin/erubis /usr/local/bin
+</pre>
+</li>
+</ul>
+<br>
+
+
+<a name="tutorial"></a>
+<h2 class="section1">Tutorial</h2>
+<a name="tut-basic"></a>
+<h3 class="section2">Basic Example</h3>
+<p>Here is a most basic example of Erubis.
+</p>
+<a name="example1.eruby"></a>
+<div class="program_caption">
+example1.eruby</div>
+<pre class="program">&lt;ul&gt;
+  <strong>&lt;% for item in list %&gt;</strong>
+  &lt;li&gt;
+    <strong>&lt;%= item %&gt;</strong>
+  &lt;/li&gt;
+  <strong>&lt;% end %&gt;</strong>
+&lt;/ul&gt;
+</pre>
+<a name="example1.rb"></a>
+<div class="program_caption">
+example1.rb</div>
+<pre class="program">## create Eruby object
+require 'erubis'
+input = File.read('example1.eruby')
+eruby = <strong>Erubis::Eruby.new(input)</strong>
+
+## print script source
+puts "--- script source ---"
+puts <strong>eruby.src</strong>
+
+## get result
+puts "--- result ---"
+list = ['aaa', 'bbb', 'ccc']
+puts <strong>eruby.result(binding())</strong>
+</pre>
+<div class="terminal_caption">
+output</div>
+<pre class="terminal">$ ruby example1.rb
+--- script source ---
+_out = ''; _out &lt;&lt; "&lt;ul&gt;\n"
+   for item in list 
+_out &lt;&lt; "  &lt;li&gt;\n"
+_out &lt;&lt; "    "; _out &lt;&lt; ( item ).to_s; _out &lt;&lt; "\n"
+_out &lt;&lt; "  &lt;/li&gt;\n"
+   end 
+_out &lt;&lt; "&lt;/ul&gt;\n"
+_out
+--- result ---
+&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="tut-trim"></a>
+<h3 class="section2">Trimming Spaces</h3>
+<p>Erubis deletes spaces around '&lt;% %&gt;' automatically, while it leaves spaces around '&lt;%= %&gt;'.
+If you want leave spaces around '&lt;% %&gt;', add <code>:trim=&gt;false</code> option to Erubis::Eruby.new().
+</p>
+<a name="example2.eruby"></a>
+<div class="program_caption">
+example2.eruby</div>
+<pre class="program">&lt;ul&gt;
+  &lt;% for item in list %&gt;
+  &lt;li&gt;
+    &lt;%= item %&gt;
+  &lt;/li&gt;
+  &lt;% end %&gt;
+&lt;/ul&gt;
+</pre>
+<a name="example2.rb"></a>
+<div class="program_caption">
+example2.rb</div>
+<pre class="program">## create Eruby object
+require 'erubis'
+input = File.read('example2.eruby')
+eruby = Erubis::Eruby.new(input<strong>, :trim=&gt;false</strong>)
+
+## print script source
+puts "--- script source ---"
+puts eruby.src
+
+## get result
+puts "--- result ---"
+list = ['aaa', 'bbb', 'ccc']
+puts eruby.result(binding())
+</pre>
+<div class="terminal_caption">
+output</div>
+<pre class="terminal">$ ruby example2.rb
+--- script source ---
+_out = ''; _out &lt;&lt; "&lt;ul&gt;\n"
+<strong>_out &lt;&lt; "  ";</strong>  for item in list <strong>; _out &lt;&lt; "\n"</strong>
+_out &lt;&lt; "  &lt;li&gt;\n"
+_out &lt;&lt; "    "; _out &lt;&lt; ( item ).to_s; _out &lt;&lt; "\n"
+_out &lt;&lt; "  &lt;/li&gt;\n"
+<strong>_out &lt;&lt; "  ";</strong>  end <strong>; _out &lt;&lt; "\n"</strong>
+_out &lt;&lt; "&lt;/ul&gt;\n"
+_out
+--- result ---
+&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="tut-xml"></a>
+<h3 class="section2">Auto Sanitizing</h3>
+<p>If you use Erubis::XmlEruby instead of Erubis::Eruby, output is sanitized automatically.
+</p>
+<p>Erubis::XmlEruby acts the following:
+</p>
+<ul type="disc">
+<li><code>&lt;%= <em>expr</em> %&gt;</code> will be sanitized.
+</li>
+<li><code>&lt;%== <em>expr</em> %&gt;</code> will be out as it is.
+</li>
+<li><code>&lt;%=== <em>expr</em> %&gt;</code> will be out to $stderr.
+</li>
+<li><code>&lt;%==== <em>expr</em> %&gt;</code> will be ignored.
+</li>
+</ul>
+<a name="example3.eruby"></a>
+<div class="program_caption">
+example3.eruby</div>
+<pre class="program">&lt;ul&gt;
+  &lt;% for item in list %&gt;
+  &lt;li&gt;<strong>&lt;%=</strong> item <strong>%&gt;</strong>&lt;/li&gt;
+  &lt;li&gt;<strong>&lt;%==</strong> item <strong>%&gt;</strong>&lt;/li&gt;
+  &lt;li&gt;<strong>&lt;%===</strong> item <strong>%&gt;</strong>&lt;/li&gt;
+
+  &lt;% end %&gt;
+&lt;/ul&gt;
+</pre>
+<a name="example3.rb"></a>
+<div class="program_caption">
+example3.rb</div>
+<pre class="program">## create Eruby object
+require 'erubis'
+input = File.read('example3.eruby')
+eruby = Erubis::<strong>XmlEruby</strong>.new(input)
+
+## print script source
+puts "--- script source ---"
+puts eruby.src
+
+## get result
+puts "--- result ---"
+<strong>list = ['&lt;aaa&gt;', 'b&amp;b', '"ccc"']</strong>
+puts eruby.result(binding())
+</pre>
+<div class="terminal_caption">
+output</div>
+<pre class="terminal">$ ruby example3.rb 2&gt; stderr.log
+--- script source ---
+_out = ''; _out &lt;&lt; "&lt;ul&gt;\n"
+   for item in list 
+_out &lt;&lt; "  &lt;li&gt;"; <strong>_out &lt;&lt; Erubis::XmlEruby.escape( item )</strong>; _out &lt;&lt; "&lt;/li&gt;\n"
+_out &lt;&lt; "  &lt;li&gt;"; _out &lt;&lt; ( item ).to_s; _out &lt;&lt; "&lt;/li&gt;\n"
+_out &lt;&lt; "  &lt;li&gt;"; <strong>$stderr.puts("** erubis: item = #{(item).inspect}")</strong>; _out &lt;&lt; "&lt;/li&gt;\n"
+_out &lt;&lt; "\n"
+   end 
+_out &lt;&lt; "&lt;/ul&gt;\n"
+_out
+--- result ---
+&lt;ul&gt;
+  &lt;li&gt;<strong>&amp;lt;aaa&amp;gt;</strong>&lt;/li&gt;
+  &lt;li&gt;&lt;aaa&gt;&lt;/li&gt;
+  &lt;li&gt;&lt;/li&gt;
+
+  &lt;li&gt;<strong>b&amp;amp;b</strong>&lt;/li&gt;
+  &lt;li&gt;b&amp;b&lt;/li&gt;
+  &lt;li&gt;&lt;/li&gt;
+
+  &lt;li&gt;<strong>&amp;quot;ccc&amp;quot;</strong>&lt;/li&gt;
+  &lt;li&gt;"ccc"&lt;/li&gt;
+  &lt;li&gt;&lt;/li&gt;
+
+&lt;/ul&gt;
+$ cat stderr.log
+** erubis: item = "&lt;aaa&gt;"
+** erubis: item = "b&amp;b"
+** erubis: item = "\"ccc\""
+</pre>
+<br>
+
+
+<a name="tut-pattern"></a>
+<h3 class="section2">Embedded Pattern</h3>
+<p>You can change embedded pattern '<code>&lt;% %&gt;</code>' to another.
+</p>
+<a name="example4.eruby"></a>
+<div class="program_caption">
+example4.eruby</div>
+<pre class="program">&lt;ul&gt;
+ <strong>&lt;!--%</strong> for item in list <strong>%--&gt;</strong>
+  &lt;li&gt;<strong>&lt;!--%=</strong> item <strong>%--&gt;</strong>&lt;/li&gt;
+ <strong>&lt;!--%</strong> end <strong>%--&gt;</strong>
+&lt;/ul&gt;
+</pre>
+<a name="example4.rb"></a>
+<div class="program_caption">
+example4.rb</div>
+<pre class="program">## create Eruby object
+require 'erubis'
+input = File.read('example4.eruby')
+eruby = Erubis::Eruby.new(input<strong>, :pattern=&gt;'&lt;!--% %--&gt;'</strong>)
+                                      # or '&lt;(?:!--)?% %(?:--)?&gt;'
+
+## print script source
+puts "--- script source ---"
+puts eruby.src
+
+## get result
+puts "--- result ---"
+list = ['aaa', 'bbb', 'ccc']
+puts eruby.result(binding())
+</pre>
+<div class="terminal_caption">
+output</div>
+<pre class="terminal">$ ruby example4.rb
+--- script source ---
+_out = ''; _out &lt;&lt; "&lt;ul&gt;\n"
+  for item in list 
+_out &lt;&lt; "  &lt;li&gt;"; _out &lt;&lt; ( item ).to_s; _out &lt;&lt; "&lt;/li&gt;\n"
+  end 
+_out &lt;&lt; "&lt;/ul&gt;\n"
+_out
+--- result ---
+&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>
+<p>It is able to specify regular expression with :pattern option.
+Notice that you must use '<code>(?: )</code>' instead of '<code>( )</code>' for grouping.
+For example, '<code>&lt;(!--)?% %(--)?&gt;</code>' will not work and '<code>&lt;(?:!--)?% %(?:--)?&gt;</code>' will work.
+</p>
+<br>
+
+
+<a name="tut-context"></a>
+<h3 class="section2">Context Object</h3>
+<p>Context object is a set of data which are used in eRuby script.
+Using context object makes clear which data to be used.
+</p>
+<p>In Erubis, Hash object is used as context object.
+Hash key means variable name and it can be string or symbol.
+</p>
+<a name="example5.eruby"></a>
+<div class="program_caption">
+example5.eruby</div>
+<pre class="program">&lt;span&gt;&lt;%= val %&gt;&lt;/span&gt;
+&lt;ul&gt;
+ &lt;% for item in list %&gt;
+  &lt;li&gt;&lt;%= item %&gt;&lt;/li&gt;
+ &lt;% end %&gt;
+&lt;/ul&gt;
+</pre>
+<a name="example5.rb"></a>
+<div class="program_caption">
+example5.rb</div>
+<pre class="program">## create Eruby object
+require 'erubis'
+input = File.read('example5.eruby')
+eruby = Erubis::Eruby.new(input)
+
+## create context object
+## (key means var name, which may be string or symbol.)
+<strong>context = {}</strong>
+<strong>context[:val]   = 'Erubis Example'</strong>
+<strong>context['list'] = ['aaa', 'bbb', 'ccc']</strong>
+
+## get result
+puts "--- result ---"
+puts <strong>eruby.evaluate(context)</strong>
+</pre>
+<div class="terminal_caption">
+output</div>
+<pre class="terminal">$ ruby example5.rb
+--- result ---
+&lt;span&gt;Erubis Example&lt;/span&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;
+</pre>
+<p>It is very useful to import YAML document data into context object.
+</p>
+<a name="example6.yaml"></a>
+<div class="program_caption">
+example6.yaml</div>
+<pre class="program">title: Users List
+users:
+  - name:  foo
+    mail:  foo@mail.com
+  - name:  bar
+    mail:  bar@mail.net
+  - name:  baz
+    mail:  baz@mail.org
+</pre>
+<a name="example6.eruby"></a>
+<div class="program_caption">
+example6.eruby</div>
+<pre class="program">&lt;h1&gt;&lt;%= title %&gt;&lt;/h1&gt;
+&lt;ul&gt;
+ &lt;% for user in users %&gt;
+  &lt;li&gt;
+    &lt;a href="mailto:&lt;%= user['mail']%&gt;"&gt;&lt;%= user['name'] %&gt;&lt;/a&gt;
+  &lt;/li&gt;
+ &lt;% end %&gt;
+&lt;/ul&gt;
+</pre>
+<a name="example6.rb"></a>
+<div class="program_caption">
+example6.rb</div>
+<pre class="program">## create Eruby object
+require 'erubis'
+input = File.read('example6.eruby')
+eruby = Erubis::Eruby.new(input)
+
+## load YAML document as context object
+<strong>require 'yaml'</strong>
+<strong>context = YAML.load_file('example6.yaml')</strong>
+
+## get result
+puts <strong>eruby.evaluate(context)</strong>
+</pre>
+<div class="terminal_caption">
+output</div>
+<pre class="terminal">$ ruby example6.rb
+&lt;h1&gt;Users List&lt;/h1&gt;
+&lt;ul&gt;
+  &lt;li&gt;
+    &lt;a href="mailto:foo@mail.com"&gt;foo&lt;/a&gt;
+  &lt;/li&gt;
+  &lt;li&gt;
+    &lt;a href="mailto:bar@mail.net"&gt;bar&lt;/a&gt;
+  &lt;/li&gt;
+  &lt;li&gt;
+    &lt;a href="mailto:baz@mail.org"&gt;baz&lt;/a&gt;
+  &lt;/li&gt;
+&lt;/ul&gt;
+</pre>
+<br>
+
+
+<a name="tut-fast"></a>
+<h3 class="section2">Faster Eruby</h3>
+<p>Erubis::FastEruby and Erubis::FastXmlEruby make faster Erubis::Eruby and Erubis::XmlEruby
+to combine several strings into a string.
+</p>
+<a name="example7.eruby"></a>
+<div class="program_caption">
+example7.eruby</div>
+<pre class="program">&lt;table&gt;
+  &lt;tbody&gt;
+   &lt;% for item in list %&gt;
+    &lt;tr&gt;
+      &lt;td&gt;&lt;%= item %&gt;&lt;/td&gt;
+    &lt;/tr&gt;
+   &lt;% end %&gt;
+  &lt;/tbody&gt;
+&lt;/table&gt;
+</pre>
+<a name="example7.rb"></a>
+<div class="program_caption">
+example7.rb</div>
+<pre class="program">## print script source with Eruby
+require 'erubis'
+input = File.read('example7.eruby')
+eruby = Erubis::Eruby.new(input)
+puts "--- script source (Eruby) ---"
+puts eruby.src
+
+## print script source with FastEruby
+eruby = Erubis::<strong>FastEruby</strong>.new(input)
+puts "--- script source (FastEruby) ---"
+puts eruby.src
+</pre>
+<div class="terminal_caption">
+output</div>
+<pre class="terminal">$ ruby example7.rb
+--- script source (Eruby) ---
+_out = ''; _out &lt;&lt; "&lt;table&gt;\n"
+_out &lt;&lt; "  &lt;tbody&gt;\n"
+    for item in list 
+_out &lt;&lt; "    &lt;tr&gt;\n"
+_out &lt;&lt; "      &lt;td&gt;"; _out &lt;&lt; ( item ).to_s; _out &lt;&lt; "&lt;/td&gt;\n"
+_out &lt;&lt; "    &lt;/tr&gt;\n"
+    end 
+_out &lt;&lt; "  &lt;/tbody&gt;\n"
+_out &lt;&lt; "&lt;/table&gt;\n"
+_out
+--- script source (FastEruby) ---
+_out = ''; _out &lt;&lt; "&lt;table&gt;\n  &lt;tbody&gt;\n"
+
+    for item in list 
+_out &lt;&lt; "    &lt;tr&gt;\n      &lt;td&gt;"
+_out &lt;&lt; ( item ).to_s; _out &lt;&lt; "&lt;/td&gt;\n    &lt;/tr&gt;\n"
+
+    end 
+_out &lt;&lt; "  &lt;/tbody&gt;\n&lt;/table&gt;\n"
+
+_out
+</pre>
+<br>
+
+
+<a name="tut-stdout"></a>
+<h3 class="section2">Stdout Eruby</h3>
+<p>Erubis::StdoutEruby and Erubis::StdoutXmlEruby use $stdout instead of string object.
+Therefore, you can use 'print' statement in embedded ruby code.
+</p>
+<a name="example8.eruby"></a>
+<div class="program_caption">
+example8.eruby</div>
+<pre class="program">&lt;ul&gt;
+ &lt;% for item in list %&gt;
+  &lt;li&gt;<strong>&lt;% print item %&gt;</strong>&lt;/li&gt;
+ &lt;% end %&gt;
+&lt;/ul&gt;
+</pre>
+<a name="example8.rb"></a>
+<div class="program_caption">
+example8.rb</div>
+<pre class="program">## create Eruby object
+require 'erubis'
+input = File.read('example8.eruby')
+eruby = Erubis::<strong>StdoutEruby</strong>.new(input)
+
+## print script source
+puts "--- script source ---"
+puts eruby.src
+
+## get result
+puts "--- result ---"
+list = ['aaa', 'bbb', 'ccc']
+#puts eruby.result(binding())
+<strong>eruby.result(binding())</strong>  # returns nil
+</pre>
+<div class="terminal_caption">
+output</div>
+<pre class="terminal">$ ruby example8.rb
+--- script source ---
+<strong>_out = $stdout</strong>; _out &lt;&lt; "&lt;ul&gt;\n"
+  for item in list 
+_out &lt;&lt; "  &lt;li&gt;";  <strong>print item</strong> ; _out &lt;&lt; "&lt;/li&gt;\n"
+  end 
+_out &lt;&lt; "&lt;/ul&gt;\n"
+nil
+--- result ---
+&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>
+
+
+<br>
+
+
+<a name="command"></a>
+<h2 class="section1">Command Reference</h2>
+<a name="command-usage"></a>
+<h3 class="section2">Usage</h3>
+<p>erubis [-hvsT] [-p <em>pattern</em>] [-c <em>class</em>] [-K <em>kanji</em>] [-f <em>file.yaml</em>] [<em>file</em> ...]
+</p>
+<br>
+
+
+<a name="command-options"></a>
+<h3 class="section2">Options</h3>
+  <dl class="dl3" compact>
+  <dt class="dt3"><b>
+-h, --help    </b></dt>
+  <dd class="dd3">
+  	Help.
+  </dd>
+  <dt class="dt3"><b>
+-v            </b></dt>
+  <dd class="dd3">
+  	Release version.
+  </dd>
+  <dt class="dt3"><b>
+-s            </b></dt>
+  <dd class="dd3">
+  	Show script source.
+  </dd>
+  <dt class="dt3"><b>
+-T            </b></dt>
+  <dd class="dd3">
+  	No trimming spaces around '&lt;% %&gt;'.
+  </dd>
+  <dt class="dt3"><b>
+-p pattern    </b></dt>
+  <dd class="dd3">
+  	Embedded pattern (default '&lt;% %&gt;').
+  </dd>
+  <dt class="dt3"><b>
+-c class      </b></dt>
+  <dd class="dd3">
+  	Class name (Eruby, XmlEruby, FastEruby, ...) (default Eruby).
+  </dd>
+  <dt class="dt3"><b>
+-I path       </b></dt>
+  <dd class="dd3">
+  	Require library path ($:).
+			It is able to specify several paths separating with ',' (ex. -f path1,path2,path3).
+  </dd>
+  <dt class="dt3"><b>
+-K kanji      </b></dt>
+  <dd class="dd3">
+  	Kanji code (euc, sjis, utf8, or none) (default none).
+  </dd>
+  <dt class="dt3"><b>
+-f file.yaml  </b></dt>
+  <dd class="dd3">
+  	YAML file for context values (read stdin if filename is '-').
+			It is able to specify several filenames separating with ',' (ex. -f file1,file2,file3).
+  </dd>
+  <dt class="dt3"><b>
+--name=value  </b></dt>
+  <dd class="dd3">
+  	Variable name and value
+  </dd>
+  </dl>
+<br>
+
+
+<br>
+
+
+
+   </div>
+  </blockquote>
+
+ </body>
+</html>
diff --git a/doc/users-guide.txt b/doc/users-guide.txt
new file mode 100644
index 0000000..b38a7e3
--- /dev/null
+++ b/doc/users-guide.txt
@@ -0,0 +1,501 @@
+.=title:	Erubis Users' Guide
+.?version:	$Release$
+.?lastupdate:	$Date$
+.?stylesheet:	docstyle.css
+
+
+
+.$ Preface		| preface*
+
+Erubis is an implementation of eRuby.
+It has the following features.
+.* Auto trimming spaces around '<% %>'
+.* Auto sanitizing
+.* Change embedded pattern (default '<% %>')
+.* Context object available
+.* Easy to expand in subclass
+
+Erubis is implemented in pure Ruby.  It requires Ruby 1.8 or higher.
+
+
+
+.$$ Table of Contents	| toc*
+
+.<<< users-guide.toc
+
+
+
+.$ Installation		| install
+
+.* If you have installed RubyGems, just type {{,gem install --remote erubis,}}.
+	.====================
+	$ sudo gem install --remote erubis
+	.====================
+
+.* Or if you can be root user, download erubis-X.X.X.tar.bz2 and install by setup.rb.
+	.====================
+	$ tar xjf erubis-X.X.X.tar.bz2
+	$ cd erubis_X.X.X/
+	$ ruby setup.rb
+	.#$ ruby setup.rb config
+	.#$ ruby setup.rb setup
+	.#$ sudo ruby setup.rb install
+	.====================
+
+.* Else you should copy 'lib/erubis.rb' and 'bin/erubis' into proper directory manually.
+	.====================
+	$ tar xjf erubis-X.X.X.tar.bz2
+	$ cd erubis_X.X.X/
+	$ cp lib/erubis.rb /usr/local/lib/ruby/site_ruby/1.8
+	$ cp bin/erubis /usr/local/bin
+	.====================
+
+.* (Optional) 'contrib/inline-require' enables you to merge 'lib/erubis.rb' into 'bin/erubis'.
+	.====================
+	$ tar xjf erubis-X.X.X.tar.bz2
+	$ cd erubis_X.X.X/
+	$ unset RUBYLIB
+	$ contrib/inline-require -I lib bin/erubis > contrib/erubis
+	.====================
+
+
+
+.$ Tutorial		| tutorial
+
+
+
+.$$ Basic Example	| tut-basic
+
+Here is a most basic example of Erubis.
+
+.? example1.eruby
+.-------------------- example1.eruby
+<ul>
+  {{*<% for item in list %>*}}
+  <li>
+    {{*<%= item %>*}}
+  </li>
+  {{*<% end %>*}}
+</ul>
+.--------------------
+
+.? example1.rb
+.-------------------- example1.rb
+## create Eruby object
+require 'erubis'
+input = File.read('example1.eruby')
+eruby = {{*Erubis::Eruby.new(input)*}}
+
+## print script source
+puts "--- script source ---"
+puts {{*eruby.src*}}
+
+## get result
+puts "--- result ---"
+list = ['aaa', 'bbb', 'ccc']
+puts {{*eruby.result(binding())*}}
+.--------------------
+
+.? output
+.====================
+$ ruby example1.rb
+.<<<:! (cd guide.d; ruby example1.rb)
+.====================
+
+
+
+.$$ Trimming Spaces	| tut-trim
+
+Erubis deletes spaces around '<% %>' automatically, while it leaves spaces around '<%= %>'.
+If you want leave spaces around '<% %>', add {{,:trim=>false,}} option to Erubis::Eruby.new().
+
+.? example2.eruby
+.-------------------- example2.eruby
+<ul>
+  <% for item in list %>
+  <li>
+    <%= item %>
+  </li>
+  <% end %>
+</ul>
+.--------------------
+
+.? example2.rb
+.-------------------- example2.rb
+## create Eruby object
+require 'erubis'
+input = File.read('example2.eruby')
+eruby = Erubis::Eruby.new(input{{*, :trim=>false*}})
+
+## print script source
+puts "--- script source ---"
+puts eruby.src
+
+## get result
+puts "--- result ---"
+list = ['aaa', 'bbb', 'ccc']
+puts eruby.result(binding())
+.--------------------
+
+.? output
+.====================
+$ ruby example2.rb
+.#.<<<:! (cd guide.d; ruby example2.rb)
+--- script source ---
+_out = ''; _out << "<ul>\n"
+{{*_out << "  ";*}}  for item in list {{*; _out << "\n"*}}
+_out << "  <li>\n"
+_out << "    "; _out << ( item ).to_s; _out << "\n"
+_out << "  </li>\n"
+{{*_out << "  ";*}}  end {{*; _out << "\n"*}}
+_out << "</ul>\n"
+_out
+--- result ---
+<ul>
+  
+  <li>
+    aaa
+  </li>
+  
+  <li>
+    bbb
+  </li>
+  
+  <li>
+    ccc
+  </li>
+  
+</ul>
+.====================
+
+
+
+.$$ Auto Sanitizing	| tut-xml
+
+If you use Erubis::XmlEruby instead of Erubis::Eruby, output is sanitized automatically.
+
+Erubis::XmlEruby acts the following:
+.* {{,<%= {{/expr/}} %>,}} will be sanitized.
+.* {{,<%== {{/expr/}} %>,}} will be out as it is.
+.* {{,<%=== {{/expr/}} %>,}} will be out to $stderr.
+.* {{,<%==== {{/expr/}} %>,}} will be ignored.
+
+.? example3.eruby
+.-------------------- example3.eruby
+<ul>
+  <% for item in list %>
+  <li>{{*<%=*}} item {{*%>*}}</li>
+  <li>{{*<%==*}} item {{*%>*}}</li>
+  <li>{{*<%===*}} item {{*%>*}}</li>
+
+  <% end %>
+</ul>
+.--------------------
+
+.? example3.rb
+.-------------------- example3.rb
+## create Eruby object
+require 'erubis'
+input = File.read('example3.eruby')
+eruby = Erubis::{{*XmlEruby*}}.new(input)
+
+## print script source
+puts "--- script source ---"
+puts eruby.src
+
+## get result
+puts "--- result ---"
+{{*list = ['<aaa>', 'b&b', '"ccc"']*}}
+puts eruby.result(binding())
+.--------------------
+
+.? output
+.====================
+$ ruby example3.rb 2> stderr.log
+.#.<<<:! (cd guide.d; ruby example3.rb  2> stderr.log)
+--- script source ---
+_out = ''; _out << "<ul>\n"
+   for item in list 
+_out << "  <li>"; {{*_out << Erubis::XmlEruby.escape( item )*}}; _out << "</li>\n"
+_out << "  <li>"; _out << ( item ).to_s; _out << "</li>\n"
+_out << "  <li>"; {{*$stderr.puts("** erubis: item = #{(item).inspect}")*}}; _out << "</li>\n"
+_out << "\n"
+   end 
+_out << "</ul>\n"
+_out
+--- result ---
+<ul>
+  <li>{{*&lt;aaa&gt;*}}</li>
+  <li><aaa></li>
+  <li></li>
+
+  <li>{{*b&amp;b*}}</li>
+  <li>b&b</li>
+  <li></li>
+
+  <li>{{*&quot;ccc&quot;*}}</li>
+  <li>"ccc"</li>
+  <li></li>
+
+</ul>
+$ cat stderr.log
+.#.<<<! guide.d/stderr.log
+** erubis: item = "<aaa>"
+** erubis: item = "b&b"
+** erubis: item = "\"ccc\""
+.====================
+
+
+
+.$$ Embedded Pattern	| tut-pattern
+
+You can change embedded pattern '{{,<% %>,}}' to another.
+
+.? example4.eruby
+.-------------------- example4.eruby
+<ul>
+ {{*<!--%*}} for item in list {{*%-->*}}
+  <li>{{*<!--%=*}} item {{*%-->*}}</li>
+ {{*<!--%*}} end {{*%-->*}}
+</ul>
+.--------------------
+
+.? example4.rb
+.-------------------- example4.rb
+## create Eruby object
+require 'erubis'
+input = File.read('example4.eruby')
+eruby = Erubis::Eruby.new(input{{*, :pattern=>'<!--% %-->'*}})
+                                      # or '<(?:!--)?% %(?:--)?>'
+
+## print script source
+puts "--- script source ---"
+puts eruby.src
+
+## get result
+puts "--- result ---"
+list = ['aaa', 'bbb', 'ccc']
+puts eruby.result(binding())
+.--------------------
+
+.? output
+.====================
+$ ruby example4.rb
+.<<<:! (cd guide.d; ruby example4.rb)
+.====================
+
+It is able to specify regular expression with :pattern option.
+Notice that you must use '{{,(?: ),}}' instead of '{{,( ),}}' for grouping.
+For example, '{{,<(!--)?% %(--)?>,}}' will not work and '{{,<(?:!--)?% %(?:--)?>,}}' will work.
+
+
+
+.$$ Context Object	| tut-context
+
+Context object is a set of data which are used in eRuby script.
+Using context object makes clear which data to be used.
+
+In Erubis, Hash object is used as context object.
+Hash key means variable name and it can be string or symbol.
+
+.? example5.eruby
+.-------------------- example5.eruby
+<span><%= val %></span>
+<ul>
+ <% for item in list %>
+  <li><%= item %></li>
+ <% end %>
+</ul>
+.--------------------
+
+.? example5.rb
+.-------------------- example5.rb
+## create Eruby object
+require 'erubis'
+input = File.read('example5.eruby')
+eruby = Erubis::Eruby.new(input)
+
+## create context object
+## (key means var name, which may be string or symbol.)
+{{*context = {}*}}
+{{*context[:val]   = 'Erubis Example'*}}
+{{*context['list'] = ['aaa', 'bbb', 'ccc']*}}
+
+## get result
+puts "--- result ---"
+puts {{*eruby.evaluate(context)*}}
+.--------------------
+
+.? output
+.====================
+$ ruby example5.rb
+.<<<:! (cd guide.d; ruby example5.rb)
+.====================
+
+It is very useful to import YAML document data into context object.
+
+.? example6.yaml
+.-------------------- example6.yaml
+title: Users List
+users:
+  - name:  foo
+    mail:  foo@mail.com
+  - name:  bar
+    mail:  bar@mail.net
+  - name:  baz
+    mail:  baz@mail.org
+.--------------------
+
+.? example6.eruby
+.-------------------- example6.eruby
+<h1><%= title %></h1>
+<ul>
+ <% for user in users %>
+  <li>
+    <a href="mailto:<%= user['mail']%>"><%= user['name'] %></a>
+  </li>
+ <% end %>
+</ul>
+.--------------------
+
+.? example6.rb
+.-------------------- example6.rb
+## create Eruby object
+require 'erubis'
+input = File.read('example6.eruby')
+eruby = Erubis::Eruby.new(input)
+
+## load YAML document as context object
+{{*require 'yaml'*}}
+{{*context = YAML.load_file('example6.yaml')*}}
+
+## get result
+puts {{*eruby.evaluate(context)*}}
+.--------------------
+
+.? output
+.====================
+$ ruby example6.rb
+.<<<:! (cd guide.d; ruby example6.rb)
+.====================
+
+
+
+.$$ Faster Eruby	| tut-fast
+
+Erubis::FastEruby and Erubis::FastXmlEruby make faster Erubis::Eruby and Erubis::XmlEruby
+to combine several strings into a string.
+
+.? example7.eruby
+.-------------------- example7.eruby
+<table>
+  <tbody>
+   <% for item in list %>
+    <tr>
+      <td><%= item %></td>
+    </tr>
+   <% end %>
+  </tbody>
+</table>
+.--------------------
+
+.? example7.rb
+.-------------------- example7.rb
+## print script source with Eruby
+require 'erubis'
+input = File.read('example7.eruby')
+eruby = Erubis::Eruby.new(input)
+puts "--- script source (Eruby) ---"
+puts eruby.src
+
+## print script source with FastEruby
+eruby = Erubis::{{*FastEruby*}}.new(input)
+puts "--- script source (FastEruby) ---"
+puts eruby.src
+.--------------------
+
+.? output
+.====================
+$ ruby example7.rb
+.<<<:! (cd guide.d; ruby example7.rb)
+.====================
+
+
+
+.$$ Stdout Eruby	| tut-stdout
+
+Erubis::StdoutEruby and Erubis::StdoutXmlEruby use $stdout instead of string object.
+Therefore, you can use 'print' statement in embedded ruby code.
+
+.? example8.eruby
+.-------------------- example8.eruby
+<ul>
+ <% for item in list %>
+  <li>{{*<% print item %>*}}</li>
+ <% end %>
+</ul>
+.--------------------
+
+.? example8.rb
+.-------------------- example8.rb
+## create Eruby object
+require 'erubis'
+input = File.read('example8.eruby')
+eruby = Erubis::{{*StdoutEruby*}}.new(input)
+
+## print script source
+puts "--- script source ---"
+puts eruby.src
+
+## get result
+puts "--- result ---"
+list = ['aaa', 'bbb', 'ccc']
+#puts eruby.result(binding())
+{{*eruby.result(binding())*}}  # returns nil
+.--------------------
+
+.? output
+.====================
+$ ruby example8.rb
+.#.<<<:! (cd guide.d; ruby example8.rb)
+--- script source ---
+{{*_out = $stdout*}}; _out << "<ul>\n"
+  for item in list 
+_out << "  <li>";  {{*print item*}} ; _out << "</li>\n"
+  end 
+_out << "</ul>\n"
+nil
+--- result ---
+<ul>
+  <li>aaa</li>
+  <li>bbb</li>
+  <li>ccc</li>
+</ul>
+.====================
+
+
+
+
+.$ Command Reference	| command
+
+
+.$$ Usage		| command-usage
+
+erubis [-hvsT] [-p {{/pattern/}}] [-c {{/class/}}] [-K {{/kanji/}}] [-f {{/file.yaml/}}] [{{/file/}} ...]
+
+
+.$$ Options		| command-options
+
+  .[ -h, --help    ]	Help.
+  .[ -v            ]	Release version.
+  .[ -s            ]	Show script source.
+  .[ -T            ]	No trimming spaces around '<% %>'.
+  .[ -p pattern    ]	Embedded pattern (default '<% %>').
+  .[ -c class      ]	Class name (Eruby, XmlEruby, FastEruby, ...) (default Eruby).
+  .[ -I path       ]	Require library path ($:).
+			It is able to specify several paths separating with ',' (ex. -f path1,path2,path3).
+  .[ -K kanji      ]	Kanji code (euc, sjis, utf8, or none) (default none).
+  .[ -f file.yaml  ]	YAML file for context values (read stdin if filename is '-').
+			It is able to specify several filenames separating with ',' (ex. -f file1,file2,file3).
+  .[ --name=value  ]	Variable name and value
+