* lib/erb.rb: changes style of the rdoc for suppressing

  warning. [ruby-core:21117]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_9_1@21635 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 243 insertions, 243 deletions

diff --git a/lib/erb.rb b/lib/erb.rb
index 678f082b07..62b59be249 100644
--- a/lib/erb.rb
+++ b/lib/erb.rb
@@ -10,249 +10,249 @@
 #
 # You can redistribute it and/or modify it under the same terms as Ruby.
 
-#
-# = ERB -- Ruby Templating
-#
-# == Introduction
-#
-# ERB provides an easy to use but powerful templating system for Ruby.  Using
-# ERB, actual Ruby code can be added to any plain text document for the
-# purposes of generating document information details and/or flow control.
-#
-# A very simple example is this:
-# 
-#   require 'erb'
-#
-#   x = 42
-#   template = ERB.new <<-EOF
-#     The value of x is: <%= x %>
-#   EOF
-#   puts template.result(binding)
-#
-# <em>Prints:</em> The value of x is: 42
-#
-# More complex examples are given below.
-#
-#
-# == Recognized Tags
-#
-# ERB recognizes certain tags in the provided template and converts them based
-# on the rules below:
-#
-#   <% Ruby code -- inline with output %>
-#   <%= Ruby expression -- replace with result %>
-#   <%# comment -- ignored -- useful in testing %>
-#   % a line of Ruby code -- treated as <% line %> (optional -- see ERB.new)
-#   %% replaced with % if first thing on a line and % processing is used
-#   <%% or %%> -- replace with <% or %> respectively
-#
-# All other text is passed through ERB filtering unchanged.
-#
-#
-# == Options
-#
-# There are several settings you can change when you use ERB:
-# * the nature of the tags that are recognized;
-# * the value of <tt>$SAFE</tt> under which the template is run;
-# * the binding used to resolve local variables in the template.
-#
-# See the ERB.new and ERB#result methods for more detail.
-#
-# == Character encodings
-#
-# ERB (or ruby code generated by ERB) returns a string in the same
-# character encoding as the input string.  When the input string has
-# a magic comment, however, it returns a string in the encoding specified
-# by the magic comment.
-#
-#   # -*- coding: UTF-8 -*-
-#   require 'erb'
-#
-#   template = ERB.new <<EOF
-#   <%#-*- coding: Big5 -*-%>
-#     \_\_ENCODING\_\_ is <%= \_\_ENCODING\_\_ %>.
-#   EOF
-#   puts template.result
-#
-# <em>Prints:</em> \_\_ENCODING\_\_ is Big5.
-#
-#
-# == Examples
-#
-# === Plain Text
-#
-# ERB is useful for any generic templating situation.  Note that in this example, we use the
-# convenient "% at start of line" tag, and we quote the template literally with
-# <tt>%q{...}</tt> to avoid trouble with the backslash.
-#
-#   require "erb"
-#   
-#   # Create template.
-#   template = %q{
-#     From:  James Edward Gray II <james@grayproductions.net>
-#     To:  <%= to %>
-#     Subject:  Addressing Needs
-#   
-#     <%= to[/\w+/] %>:
-#   
-#     Just wanted to send a quick note assuring that your needs are being
-#     addressed.
-#   
-#     I want you to know that my team will keep working on the issues,
-#     especially:
-#   
-#     <%# ignore numerous minor requests -- focus on priorities %>
-#     % priorities.each do |priority|
-#       * <%= priority %>
-#     % end
-#   
-#     Thanks for your patience.
-#   
-#     James Edward Gray II
-#   }.gsub(/^  /, '')
-#   
-#   message = ERB.new(template, 0, "%<>")
-#   
-#   # Set up template data.
-#   to = "Community Spokesman <spokesman@ruby_community.org>"
-#   priorities = [ "Run Ruby Quiz",
-#                  "Document Modules",
-#                  "Answer Questions on Ruby Talk" ]
-#   
-#   # Produce result.
-#   email = message.result
-#   puts email
-#
-# <i>Generates:</i>
-#
-#   From:  James Edward Gray II <james@grayproductions.net>
-#   To:  Community Spokesman <spokesman@ruby_community.org>
-#   Subject:  Addressing Needs
-#   
-#   Community:
-#   
-#   Just wanted to send a quick note assuring that your needs are being addressed.
-#   
-#   I want you to know that my team will keep working on the issues, especially:
-#   
-#       * Run Ruby Quiz
-#       * Document Modules
-#       * Answer Questions on Ruby Talk
-#   
-#   Thanks for your patience.
-#   
-#   James Edward Gray II
-#
-# === Ruby in HTML
-#
-# ERB is often used in <tt>.rhtml</tt> files (HTML with embedded Ruby).  Notice the need in
-# this example to provide a special binding when the template is run, so that the instance
-# variables in the Product object can be resolved.
-#
-#   require "erb"
-#   
-#   # Build template data class.
-#   class Product
-#     def initialize( code, name, desc, cost )
-#       @code = code
-#       @name = name
-#       @desc = desc
-#       @cost = cost
-#        	
-#       @features = [ ]
-#     end
-#   
-#     def add_feature( feature )
-#       @features << feature
-#     end
-#   
-#     # Support templating of member data.
-#     def get_binding
-#       binding
-#     end
-#   
-#     # ...
-#   end
-#   
-#   # Create template.
-#   template = %{
-#     <html>
-#       <head><title>Ruby Toys -- <%= @name %></title></head>
-#       <body>
-#   
-#         <h1><%= @name %> (<%= @code %>)</h1>
-#         <p><%= @desc %></p>
-#   
-#         <ul>
-#           <% @features.each do |f| %>
-#             <li><b><%= f %></b></li>
-#           <% end %>
-#         </ul>
-#   
-#         <p>
-#           <% if @cost < 10 %>
-#             <b>Only <%= @cost %>!!!</b>
-#           <% else %>
-#              Call for a price, today!
-#           <% end %>
-#         </p>
-#    
-#       </body>
-#     </html>
-#   }.gsub(/^  /, '')
-#   
-#   rhtml = ERB.new(template)
-#   
-#   # Set up template data.
-#   toy = Product.new( "TZ-1002",
-#                      "Rubysapien",
-#                      "Geek's Best Friend!  Responds to Ruby commands...",
-#                      999.95 )
-#   toy.add_feature("Listens for verbal commands in the Ruby language!")
-#   toy.add_feature("Ignores Perl, Java, and all C variants.")
-#   toy.add_feature("Karate-Chop Action!!!")
-#   toy.add_feature("Matz signature on left leg.")
-#   toy.add_feature("Gem studded eyes... Rubies, of course!")
-#   
-#   # Produce result.
-#   rhtml.run(toy.get_binding)
-#
-# <i>Generates (some blank lines removed):</i>
-#
-#    <html>
-#      <head><title>Ruby Toys -- Rubysapien</title></head>
-#      <body>
-#    
-#        <h1>Rubysapien (TZ-1002)</h1>
-#        <p>Geek's Best Friend!  Responds to Ruby commands...</p>
-#    
-#        <ul>
-#            <li><b>Listens for verbal commands in the Ruby language!</b></li>
-#            <li><b>Ignores Perl, Java, and all C variants.</b></li>
-#            <li><b>Karate-Chop Action!!!</b></li>
-#            <li><b>Matz signature on left leg.</b></li>
-#            <li><b>Gem studded eyes... Rubies, of course!</b></li>
-#        </ul>
-#    
-#        <p>
-#             Call for a price, today!
-#        </p>
-#    
-#      </body>
-#    </html>
-#
-# 
-# == Notes
-#
-# There are a variety of templating solutions available in various Ruby projects:
-# * ERB's big brother, eRuby, works the same but is written in C for speed;
-# * Amrita (smart at producing HTML/XML);
-# * cs/Template (written in C for speed);
-# * RDoc, distributed with Ruby, uses its own template engine, which can be reused elsewhere;
-# * and others; search the RAA.
-#
-# Rails, the web application framework, uses ERB to create views.
-#
+=begin rdoc
+= ERB -- Ruby Templating
+
+== Introduction
+
+ERB provides an easy to use but powerful templating system for Ruby.  Using
+ERB, actual Ruby code can be added to any plain text document for the
+purposes of generating document information details and/or flow control.
+
+A very simple example is this:
+
+  require 'erb'
+
+  x = 42
+  template = ERB.new <<-EOF
+    The value of x is: <%= x %>
+  EOF
+  puts template.result(binding)
+
+<em>Prints:</em> The value of x is: 42
+
+More complex examples are given below.
+
+
+== Recognized Tags
+
+ERB recognizes certain tags in the provided template and converts them based
+on the rules below:
+
+  <% Ruby code -- inline with output %>
+  <%= Ruby expression -- replace with result %>
+  <%# comment -- ignored -- useful in testing %>
+  % a line of Ruby code -- treated as <% line %> (optional -- see ERB.new)
+  %% replaced with % if first thing on a line and % processing is used
+  <%% or %%> -- replace with <% or %> respectively
+
+All other text is passed through ERB filtering unchanged.
+
+
+== Options
+
+There are several settings you can change when you use ERB:
+* the nature of the tags that are recognized;
+* the value of <tt>$SAFE</tt> under which the template is run;
+* the binding used to resolve local variables in the template.
+
+See the ERB.new and ERB#result methods for more detail.
+
+== Character encodings
+
+ERB (or ruby code generated by ERB) returns a string in the same
+character encoding as the input string.  When the input string has
+a magic comment, however, it returns a string in the encoding specified
+by the magic comment.
+
+  # -*- coding: UTF-8 -*-
+  require 'erb'
+
+  template = ERB.new <<EOF
+  <%#-*- coding: Big5 -*-%>
+    \_\_ENCODING\_\_ is <%= \_\_ENCODING\_\_ %>.
+  EOF
+  puts template.result
+
+<em>Prints:</em> \_\_ENCODING\_\_ is Big5.
+
+
+== Examples
+
+=== Plain Text
+
+ERB is useful for any generic templating situation.  Note that in this example, we use the
+convenient "% at start of line" tag, and we quote the template literally with
+<tt>%q{...}</tt> to avoid trouble with the backslash.
+
+  require "erb"
+  
+  # Create template.
+  template = %q{
+    From:  James Edward Gray II <james@grayproductions.net>
+    To:  <%= to %>
+    Subject:  Addressing Needs
+  
+    <%= to[/\w+/] %>:
+  
+    Just wanted to send a quick note assuring that your needs are being
+    addressed.
+  
+    I want you to know that my team will keep working on the issues,
+    especially:
+  
+    <%# ignore numerous minor requests -- focus on priorities %>
+    % priorities.each do |priority|
+      * <%= priority %>
+    % end
+  
+    Thanks for your patience.
+  
+    James Edward Gray II
+  }.gsub(/^  /, '')
+  
+  message = ERB.new(template, 0, "%<>")
+  
+  # Set up template data.
+  to = "Community Spokesman <spokesman@ruby_community.org>"
+  priorities = [ "Run Ruby Quiz",
+                 "Document Modules",
+                 "Answer Questions on Ruby Talk" ]
+  
+  # Produce result.
+  email = message.result
+  puts email
+
+<i>Generates:</i>
+
+  From:  James Edward Gray II <james@grayproductions.net>
+  To:  Community Spokesman <spokesman@ruby_community.org>
+  Subject:  Addressing Needs
+  
+  Community:
+  
+  Just wanted to send a quick note assuring that your needs are being addressed.
+  
+  I want you to know that my team will keep working on the issues, especially:
+  
+      * Run Ruby Quiz
+      * Document Modules
+      * Answer Questions on Ruby Talk
+  
+  Thanks for your patience.
+  
+  James Edward Gray II
+
+=== Ruby in HTML
+
+ERB is often used in <tt>.rhtml</tt> files (HTML with embedded Ruby).  Notice the need in
+this example to provide a special binding when the template is run, so that the instance
+variables in the Product object can be resolved.
+
+  require "erb"
+  
+  # Build template data class.
+  class Product
+    def initialize( code, name, desc, cost )
+      @code = code
+      @name = name
+      @desc = desc
+      @cost = cost
+       	
+      @features = [ ]
+    end
+  
+    def add_feature( feature )
+      @features << feature
+    end
+  
+    # Support templating of member data.
+    def get_binding
+      binding
+    end
+  
+    # ...
+  end
+  
+  # Create template.
+  template = %{
+    <html>
+      <head><title>Ruby Toys -- <%= @name %></title></head>
+      <body>
+  
+        <h1><%= @name %> (<%= @code %>)</h1>
+        <p><%= @desc %></p>
+  
+        <ul>
+          <% @features.each do |f| %>
+            <li><b><%= f %></b></li>
+          <% end %>
+        </ul>
+  
+        <p>
+          <% if @cost < 10 %>
+            <b>Only <%= @cost %>!!!</b>
+          <% else %>
+             Call for a price, today!
+          <% end %>
+        </p>
+   
+      </body>
+    </html>
+  }.gsub(/^  /, '')
+  
+  rhtml = ERB.new(template)
+  
+  # Set up template data.
+  toy = Product.new( "TZ-1002",
+                     "Rubysapien",
+                     "Geek's Best Friend!  Responds to Ruby commands...",
+                     999.95 )
+  toy.add_feature("Listens for verbal commands in the Ruby language!")
+  toy.add_feature("Ignores Perl, Java, and all C variants.")
+  toy.add_feature("Karate-Chop Action!!!")
+  toy.add_feature("Matz signature on left leg.")
+  toy.add_feature("Gem studded eyes... Rubies, of course!")
+  
+  # Produce result.
+  rhtml.run(toy.get_binding)
+
+<i>Generates (some blank lines removed):</i>
+
+   <html>
+     <head><title>Ruby Toys -- Rubysapien</title></head>
+     <body>
+   
+       <h1>Rubysapien (TZ-1002)</h1>
+       <p>Geek's Best Friend!  Responds to Ruby commands...</p>
+   
+       <ul>
+           <li><b>Listens for verbal commands in the Ruby language!</b></li>
+           <li><b>Ignores Perl, Java, and all C variants.</b></li>
+           <li><b>Karate-Chop Action!!!</b></li>
+           <li><b>Matz signature on left leg.</b></li>
+           <li><b>Gem studded eyes... Rubies, of course!</b></li>
+       </ul>
+   
+       <p>
+            Call for a price, today!
+       </p>
+   
+     </body>
+   </html>
+
+
+== Notes
+
+There are a variety of templating solutions available in various Ruby projects:
+* ERB's big brother, eRuby, works the same but is written in C for speed;
+* Amrita (smart at producing HTML/XML);
+* cs/Template (written in C for speed);
+* RDoc, distributed with Ruby, uses its own template engine, which can be reused elsewhere;
+* and others; search the RAA.
+
+Rails, the web application framework, uses ERB to create views.
+=end
 class ERB
   Revision = '$Date::                           $' 	#'