* lib/erb.rb (ERB): m17n of ERB. adds rdoc.

fixes #712. c.f. [ruby-dev:37516].

* lib/erb.rb (ERB::Compiler#compile): recognizes magic comments.
  returns a pair of compiled script and its script encoding.

* lib/erb.rb (ERB#set_eoutvar): make generated scripts return a
  string in correct encoding.

* lib/erb.rb (ERB#def_method): use Kernel#eval for encoding-awareness
  of the evaluated string.

* bin/erb.rb (ERB::Main.run): adds -E and -U options.
  String is no longer Enumerable.

* man/erb.1: new manapage.

* test/erb/test_erb_m17n.rb: new test case for m17n features.

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

man/erb.1

@@ -0,0 +1,158 @@
+.\"Ruby is copyrighted by Yukihiro Matsumoto <matz@netlab.jp>.
+.Dd December 27, 2008
+.Dt ERB(1) "" "Ruby Programmers Reference Guide"
+.Os UNIX
+.Sh NAME
+.Nm erb
+.Nd Ruby Templating
+.Sh SYNOPSIS
+.Nm
+.Op Fl -version
+.Op Fl UPdnvx
+.Op Fl E Ar ext Ns Op Ns : Ns int
+.Op Fl S Ar level
+.Op Fl T Ar mode
+.Op Fl r Ar library
+.Op Fl -
+.Op file ...
+.Pp
+.Sh DESCRIPTION
+.Nm
+is a command line front-end for 
+.Li "ERB"
+library, which is an implementation of eRuby.
+
+eRuby provdes an easy to use but powerful templating system for Ruby. 
+Using eRuby, actual Ruby code can be added to any plain text document for the
+purposes of generating document information details and/or flow control.
+
+.Nm
+is a part of
+.Nm Ruby .
+.Pp
+.Sh OPTIONS
+.Bl -tag -width "1234567890123" -compact
+.Pp
+.It Fl -version
+Prints the version of 
+.Nm .
+.Pp
+.It Fl E Ar external Ns Op : Ns Ar internal
+.It Fl -encoding Ar external Ns Op : Ns Ar internal
+Specifies the default value(s) for external encodings and internal encoding. Values should be separated with colon (:).
+
+You can ommit the one for internal encodings, then the value
+.Pf ( Li "Encoding.default_internal" ) will be nil.
+.Pp
+.It Fl P
+Evaluates lines starting with 
+.Li "%"
+as Ruby code and removes the tailing EOLs.
+.Pp
+.It Fl S Ar level
+Specifies the safe level in which eRuby script will run.
+.Pp
+.It Fl T Ar mode
+Specifies trim mode (default 0). 
+.Ar mode
+can be one of
+.Bl -hang -offset indent
+.It Sy 0
+EOL remains after the embedded ruby script is evaluated.
+.Pp
+.It Sy 1
+EOL is removed if the line ends with
+.Li "%>" .
+.Pp
+.It Sy 2
+EOL is removed if the line starts with
+.Li "<%"
+and ends with
+.Li "%>" .
+.Pp
+.It Sy -
+EOL is removed if the line ends with
+.Li "-%>" .
+And leading whitespaces are removed if the erb directive starts with
+.Li "<%-" .
+.Pp
+.El
+.Pp
+.It Fl U
+can be one of
+Sets the defalut value for internal encodings
+.Pf ( Li "Encoding.default_internal" ) to UTF-8.
+.Pp
+.It Fl d
+.It Fl -debug
+Turns on debug mode.
+.Li "$DEBUG"
+will be set to true.
+.Pp
+.It Fl h
+.It Fl -help
+Prints a summry of the options.
+.Pp
+.It Fl n
+Used with
+.Fl x .
+Prepends the line number to each line in the output. 
+.Pp
+.It Fl v
+Enables verbose mode.  
+.Li "$VERBOSE"
+will be set to true.
+.Pp
+.It Fl x
+Converts the eRuby script into Ruby script and prints it without line numbers.
+.Pp
+.El
+.Pp
+.Sh EXAMPLES
+Here is an eRuby script
+.Bd -literal -offset indent
+<?xml version="1.0" ?>
+<% require 'prime' -%>
+<erb-example>
+  <calc><%= 1+1 %></calc>
+  <var><%= __FILE__ %></var>
+  <library><%= Prime.each(10).to_a.join(", ") %></library>
+</erb-example>
+.Ed
+
+Command
+.Dl "% erb -T - example.erb"
+prints
+.Bd -literal -offset indent
+<?xml version="1.0" ?>
+<erb-example>
+  <calc>2</calc>
+  <var>example.erb</var>
+  <library>2, 3, 5, 7</library>
+</erb-example>
+.Ed
+.Pp
+.Sh SEE ALSO
+.Xr ruby 1 .
+
+And see 
+.Xr ri 1
+documentation for 
+.Li "ERB"
+class.
+.El
+.Pp
+.Sh REPORTING BUGS
+.Bl -bullet
+.Li Security vulnerabilities should be reported via an email to 
+.Aq security@ruby-lang.org Ns
+.Li .
+Reported problems will be published after fixed.
+.Pp
+.Li And you can report other bugs and feature requests via the
+Ruby Issue Tracking System (http://redmine.ruby-lang.org).
+Do not report security vulnerabilities
+via the system because it publishes the vulnerabilities immedately.
+.El
+.Sh AUTHORS
+Written by Masatoshi SEKI.