Document lib/English. Add top-level aliases to rdoc html output

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

6 files changed, 172 insertions, 45 deletions

diff --git a/ChangeLog b/ChangeLog
index 7fa2d41a60..8272c2f12e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+Tue Jan 20 13:22:39 2004  Dave Thomas  <dave@pragprog.com>
+
+	* lib/rdoc/generators/html_generator.rb: Document aliases at 
+	  top-most level.
+
+	* lib/English.rb: Document English.rb. 
+
 Tue Jan 20 04:41:58 2004  Nobuyoshi Nakada  <nobu@ruby-lang.org>
 
 	* test/ruby/test_marshal.rb (MarshalTestLib::test_exception): test
diff --git a/lib/English.rb b/lib/English.rb
index 625b035270..4b859d96f6 100644
--- a/lib/English.rb
+++ b/lib/English.rb
@@ -1,27 +1,164 @@
+#  Include the English library file in a Ruby script, and you can
+#  reference the global variables such as \VAR{\$\_} using less
+#  cryptic names, listed in the following table.% \vref{tab:english}.
+#
+#  Without 'English':
+#
+#      $\ = ' -- '
+#      "waterbuffalo" =~ /buff/
+#      print $", $', $$, "\n"
+#
+#  With English:
+#
+#      require "English"
+#      
+#      $OUTPUT_FIELD_SEPARATOR = ' -- '
+#      "waterbuffalo" =~ /buff/
+#      print $LOADED_FEATURES, $POSTMATCH, $PID, "\n"
+
+
+# The exception object passed to +raise+.
 alias $ERROR_INFO              $!
+
+# The stack backtrace generated by the last
+# exception. <tt>See Kernel.caller</tt> for details. Thread local.
 alias $ERROR_POSITION          $@
+
+# An array containing the filenames of modules loaded by +require+.
 alias $LOADED_FEATURES         $"
+
+# The default separator pattern used by <tt>String.split</tt>.  May be
+# set from the command line using the <tt>-F</tt> flag.
 alias $FS                      $;
+
+# The default separator pattern used by <tt>String.split</tt>.  May be
+# set from the command line using the <tt>-F</tt> flag.
 alias $FIELD_SEPARATOR         $;
+
+# The separator string output between the parameters to methods such
+# as <tt>Kernel.print</tt> and <tt>Array.join</tt>. Defaults to +nil+,
+# which adds no text.
 alias $OFS                     $,
+
+# The separator string output between the parameters to methods such
+# as <tt>Kernel.print</tt> and <tt>Array.join</tt>. Defaults to +nil+,
+# which adds no text.
 alias $OUTPUT_FIELD_SEPARATOR  $,
+
+# The input record separator (newline by default). This is the value
+# that routines such as <tt>Kernel.gets</tt> use to determine record
+# boundaries. If set to +nil+, +gets+ will read the entire file.
 alias $RS                      $/
+
+# The input record separator (newline by default). This is the value
+# that routines such as <tt>Kernel.gets</tt> use to determine record
+# boundaries. If set to +nil+, +gets+ will read the entire file.
 alias $INPUT_RECORD_SEPARATOR  $/
+
+# The string appended to the output of every call to methods such as
+# <tt>Kernel.print</tt> and <tt>IO.write</tt>. The default value is
+# +nil+.
 alias $ORS                     $\
+
+# The string appended to the output of every call to methods such as
+# <tt>Kernel.print</tt> and <tt>IO.write</tt>. The default value is
+# +nil+.
 alias $OUTPUT_RECORD_SEPARATOR $\
+
+# The number of the last line read from the current input file.
 alias $INPUT_LINE_NUMBER       $.
+
+# The number of the last line read from the current input file.
 alias $NR                      $.
+
+# The last line read by <tt>Kernel.gets</tt> or
+# <tt>Kernel.readline</tt>. Many string-related functions in the
+# +Kernel+ module operate on <tt>$_</tt> by default. The variable is
+# local to the current scope. Thread local.
 alias $LAST_READ_LINE          $_
+
+# The destination of output for <tt>Kernel.print</tt>
+# and <tt>Kernel.printf</tt>. The default value is
+# <tt>$stdout</tt>.
 alias $DEFAULT_OUTPUT          $>
+
+# An object that provides access to the concatenation
+# of the contents of all the files
+# given as command-line arguments, or <tt>$stdin</tt>
+# (in the case where there are no
+# arguments). <tt>$<</tt> supports methods similar to a 
+# +File+ object:
+# +inmode+, +close+,
+# <tt>closed?</tt>, +each+,
+# <tt>each_byte</tt>, <tt>each_line</tt>,
+# +eof+, <tt>eof?</tt>, +file+,
+# +filename+, +fileno+,
+# +getc+, +gets+, +lineno+,
+# <tt>lineno=</tt>, +path+, 
+# +pos+, <tt>pos=</tt>,
+# +read+, +readchar+,
+# +readline+, +readlines+,
+# +rewind+, +seek+, +skip+,
+# +tell+, <tt>to_a</tt>, <tt>to_i</tt>,
+# <tt>to_io</tt>, <tt>to_s</tt>, along with the
+# methods in +Enumerable+. The method +file+
+# returns a +File+ object for the file currently
+# being read. This may change as <tt>$<</tt> reads
+# through the files on the command line. Read only.
 alias $DEFAULT_INPUT           $<
+
+# The process number of the program being executed. Read only.
 alias $PID                     $$
+
+# The process number of the program being executed. Read only.
 alias $PROCESS_ID              $$
+
+# The exit status of the last child process to terminate. Read
+# only. Thread local.
 alias $CHILD_STATUS            $?
+
+# A +MatchData+ object that encapsulates the results of a successful
+# pattern match. The variables <tt>$&</tt>, <tt>$`</tt>, <tt>$'</tt>,
+# and <tt>$1</tt> to <tt>$9</tt> are all derived from
+# <tt>$~</tt>. Assigning to <tt>$~</tt> changes the values of these
+# derived variables.  This variable is local to the current
+# scope. Thread local.
 alias $LAST_MATCH_INFO         $~
+
+# If set to any value apart from +nil+ or +false+, all pattern matches
+# will be case insensitive, string comparisons will ignore case, and
+# string hash values will be case insensitive. Deprecated
 alias $IGNORECASE              $=
+
+# The name of the top-level Ruby program being executed.  Typically
+# this will be the program's filename. On some operating systems,
+# assigning to this variable will change the name of the process
+# reported (for example) by the <tt>ps(1)</tt> command.
 alias $PROGRAM_NAME            $0
+
+# An array of strings containing the command-line
+# options from the invocation of the program. Options
+# used by the Ruby interpreter will have been
+# removed. Read only. Also known simply as +ARGV+.
 alias $ARGV                    $*
+
+# The string matched by the last successful pattern
+# match. This variable is local to the current
+# scope. Read only. Thread local.
 alias $MATCH                   $&
+
+# The string preceding the match in the last
+# successful pattern match. This variable is local to 
+# the current scope. Read only. Thread local.
 alias $PREMATCH                $`
+
+# The string following the match in the last
+# successful pattern match. This variable is local to 
+# the current scope. Read only. Thread local.
 alias $POSTMATCH               $'
+
+# The contents of the highest-numbered group matched in the last
+# successful pattern match. Thus, in <tt>"cat" =~ /(c|a)(t|z)/</tt>,
+# <tt>$+</tt> will be set to "t".  This variable is local to the
+# current scope. Read only. Thread local.
 alias $LAST_PAREN_MATCH        $+
diff --git a/lib/rdoc/generators/html_generator.rb b/lib/rdoc/generators/html_generator.rb
index b5e8f24e43..994d74b103 100644
--- a/lib/rdoc/generators/html_generator.rb
+++ b/lib/rdoc/generators/html_generator.rb
@@ -326,13 +326,18 @@ module Generators
     end
 
 
-    # Build a list of aliases fo which we couldn't find a corresponding method
+    # Build a list of aliases for which we couldn't find a
+    # corresponding method
     def build_alias_summary_list
       @context.aliases.map do |al|
-        {
+        res = {
           'old_name' => al.old_name,
           'new_name' => al.new_name,
         }
+        if al.comment && !al.comment.empty?
+          res['desc'] = markup(al.comment, true)
+        end
+        res
       end
     end
     
@@ -750,6 +755,9 @@ module Generators
       co = build_constants_summary_list
       @values["constants"] = co unless co.empty?
 
+      al = build_alias_summary_list
+      @values["aliases"] = al unless al.empty?
+
       if @options.promiscuous
         file_context = nil
       else
diff --git a/lib/rdoc/generators/template/html/html.rb b/lib/rdoc/generators/template/html/html.rb
index 8ac631490c..16955f550a 100644
--- a/lib/rdoc/generators/template/html/html.rb
+++ b/lib/rdoc/generators/template/html/html.rb
@@ -324,9 +324,21 @@ IF:aliases
 			<h2 class="section-bar">External Aliases</h2>
 
 			<div class="name-list">
+                        <table summary="aliases">
 START:aliases
-			%old_name% -> %new_name% <br />
+				<tr class="top-aligned-row context-row">
+					<td class="context-item-name">%old_name%</td>
+					<td>-></td>
+					<td class="context-item-value">%new_name%</td>
+				</tr>
+IF:desc
+			<tr class="top-aligned-row context-row">
+				<td>&nbsp;</td>
+				<td colspan="2" class="context-item-desc">%desc%</td>
+			</tr>
+ENDIF:desc
 END:aliases
+                        </table>
 			</div>
 		</div>
 ENDIF:aliases
@@ -630,6 +642,8 @@ INDEX = %{<?xml version="1.0" encoding="%charset%"?>
 }
 
 
+
 	end # module Page
 end # class RDoc
 
+require 'rdoc/generators/template/html/one_page_html'
diff --git a/lib/rdoc/generators/template/html/old_html.rb b/lib/rdoc/generators/template/html/old_html.rb
index 3398dc808f..de19b66967 100644
--- a/lib/rdoc/generators/template/html/old_html.rb
+++ b/lib/rdoc/generators/template/html/old_html.rb
@@ -721,48 +721,8 @@ END:method_list
 ENDIF:method_list
 }
 
-########################################################################
-
-ONE_PAGE = %{
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
-<head>
-  <title>%title%</title>
-  <meta http-equiv="Content-Type" content="text/html; charset=%charset%" />
-</head>
-<body>
-START:files
-<h2>File: %short_name%</h2>
-<table>
-  <tr><td>Path:</td><td>%full_path%</td></tr>
-  <tr><td>Modified:</td><td>%dtm_modified%</td></tr>
-</table>
-} + CONTENTS_XML + %{
-END:files
-
-IF:classes
-<h2>Classes</h2>
-START:classes
-IF:parent
-<h3>%classmod% %full_name% &lt; HREF:par_url:parent:</h3>
-ENDIF:parent
-IFNOT:parent
-<h3>%classmod% %full_name%</h3>
-ENDIF:parent
-
-IF:infiles
-(in files
-START:infiles
-HREF:full_path_url:full_path:
-END:infiles
-)
-ENDIF:infiles
-} + CONTENTS_XML + %{
-END:classes
-ENDIF:classes
-</body>
-</html>
-}
 
 end
 end
+
+require 'rdoc/generators/template/html/one_page_html'
diff --git a/lib/rdoc/parsers/parse_rb.rb b/lib/rdoc/parsers/parse_rb.rb
index d050829915..413167a39a 100644
--- a/lib/rdoc/parsers/parse_rb.rb
+++ b/lib/rdoc/parsers/parse_rb.rb
@@ -2313,6 +2313,7 @@ module RDoc
         skip_tkspace
       end
       old_name = get_symbol_or_name
+
       al = Alias.new(get_tkread, old_name, new_name, comment)
       read_documentation_modifiers(al, ATTR_MODIFIERS)
       if al.document_self