1. Force --inline-source if --one-file given

2. Add new :section: directive which starts a new section in the output.
   The title following :section: is used as the section heading, and the
   remainder of the comment containing the section is used as
   introductory text. Subsequent methods, aliases, attributes,
   and classes will be documented in this section.


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

ChangeLog

@@ -1,3 +1,16 @@
+Sat Nov 20 23:57:33 2004  Dave Thomas  <dave@pragprog.com>
+
+	* lib/rdoc/README (et al): Add a new directive, :section:, and
+	  change the output format to accomodate. :section: allows to to
+	  group together methods, attributes, constants, etc under
+	  headings in the output. If used, a table of contents is
+	  generated.
+
+Sat Nov 20 23:56:54 2004  Dave Thomas  <dave@pragprog.com>
+
+	* lib/rdoc/options.rb (Options::parse): Force --inline-source if
+	  --one-file option given
+
 Sat Nov 20 23:25:12 2004  Minero Aoki  <aamine@loveruby.net>
 
 	* io.c (rb_io_getline): f.gets("") did not work. [ruby-core:03771]

lib/rdoc/README

@@ -422,6 +422,13 @@ this margin are formatted verbatim.
 
 12. Comment blocks can contain other directives:
 
+    [<tt>:section: title</tt>]
+        Starts a new section in the output. The title following
+	<tt>:section:</tt> is used as the section heading, and the
+	remainder of the comment containing the section is used as
+	introductory text. Subsequent methods, aliases, attributes,
+	and classes will be documented in this section.
+
     [<tt>call-seq:</tt>]
         lines up to the next blank line in the comment are treated as
         the method's calling sequence, overriding the

lib/rdoc/code_objects.rb

@@ -23,6 +23,9 @@ module RDoc
 
     attr_accessor :done_documenting
 
+    # Which section are we in
+
+    attr_accessor :section
 
     # do we document ourselves?
 
@@ -112,6 +115,24 @@ module RDoc
     attr_reader   :name, :method_list, :attributes, :aliases, :constants
     attr_reader   :requires, :includes, :in_files, :visibility
 
+    attr_reader   :sections
+
+    class Section
+      attr_reader :title, :comment, :sequence
+
+      @@sequence = "SEC00000"
+
+      def initialize(title, comment)
+        @title = title
+        @@sequence.succ!
+        @sequence = @@sequence.dup
+        if comment
+          @comment = comment.sub(/.*$/, '')
+          @comment = nil if @comment.empty?
+        end
+      end
+    end
+
 
     def initialize
       super()
@@ -123,6 +144,9 @@ module RDoc
       @parent  = nil
       @visibility = :public
 
+      @current_section = Section.new(nil, nil)
+      @sections = [ @current_section ]
+
       initialize_methods_etc
       initialize_classes_and_modules
     end
@@ -236,6 +260,7 @@ module RDoc
 #        collection[name] = cls if @document_self  && !@done_documenting
         collection[name] = cls if !@done_documenting
         cls.parent = self
+        cls.section = @current_section
       end
       cls
     end
@@ -243,6 +268,7 @@ module RDoc
     def add_to(array, thing)
       array <<  thing if @document_self  && !@done_documenting
       thing.parent = self
+      thing.section = @current_section
     end
 
     # If a class's documentation is turned off after we've started
@@ -374,6 +400,13 @@ module RDoc
             find_module_named(symbol) 
     end
 
+    # Handle sections
+
+    def set_current_section(title, comment)
+      @current_section = Section.new(title, comment)
+      @sections << @current_section
+    end
+
     private
 
     # Find a named method, or return nil

lib/rdoc/generators/html_generator.rb

@@ -336,8 +336,10 @@ module Generators
 
     # Build a list of aliases for which we couldn't find a
     # corresponding method
-    def build_alias_summary_list
+    def build_alias_summary_list(section)
-      @context.aliases.map do |al|
+      values = []
+      @context.aliases.each do |al|
+        next unless al.section == section
         res = {
           'old_name' => al.old_name,
           'new_name' => al.new_name,
@@ -345,20 +347,24 @@ module Generators
         if al.comment && !al.comment.empty?
           res['desc'] = markup(al.comment, true)
         end
-        res
+        values << res
       end
+      values
     end
     
     # Build a list of constants
-    def build_constants_summary_list
+    def build_constants_summary_list(section)
-      @context.constants.map do |co|
+      values = []
+      @context.constants.each do |co|
+        next unless co.section == section
         res = {
           'name'  => co.name,
           'value' => CGI.escapeHTML(co.value)
         }
         res['desc'] = markup(co.comment, true) if co.comment && !co.comment.empty?
-        res
+        values << res
       end
+      values
     end
     
     def build_requires_list(context)
@@ -416,7 +422,7 @@ module Generators
     # methods, the other for instance methods. The inner arrays contain
     # a hash for each method
 
-    def build_method_detail_list
+    def build_method_detail_list(section)
       outer = []
 
       methods = @methods.sort
@@ -424,7 +430,10 @@ module Generators
         for vis in [ :public, :protected, :private ] 
           res = []
           methods.each do |m|
-            if m.document_self and m.visibility == vis and m.singleton == singleton
+            if m.section == section and
+                m.document_self and 
+                m.visibility == vis and 
+                m.singleton == singleton
               row = {}
               if m.call_seq
                 row["callseq"] = m.call_seq.gsub(/->/, '&rarr;')
@@ -478,11 +487,12 @@ module Generators
     # Build the structured list of classes and modules contained
     # in this context. 
 
-    def build_class_list(level, from, infile=nil)
+    def build_class_list(level, from, section, infile=nil)
       res = ""
       prefix = "&nbsp;&nbsp;::" * level;
 
       from.modules.sort.each do |mod|
+        next unless mod.section == section
         next if infile && !mod.defined_in?(infile)
         if mod.document_self
           res << 
@@ -490,11 +500,12 @@ module Generators
             "Module " <<
             href(url(mod.viewer.path), "link", mod.full_name) <<
             "<br />\n" <<
-            build_class_list(level + 1, mod, infile)
+            build_class_list(level + 1, mod, section, infile)
         end
       end
 
       from.classes.sort.each do |cls|
+        next unless cls.section == section
         next if infile && !cls.defined_in?(infile)
         if cls.document_self
           res      <<
@@ -502,7 +513,7 @@ module Generators
             "Class " <<
             href(url(cls.viewer.path), "link", cls.full_name) <<
             "<br />\n" <<
-            build_class_list(level + 1, cls, infile)
+            build_class_list(level + 1, cls, section, infile)
         end
       end
 
@@ -541,6 +552,24 @@ module Generators
       end
       res
     end
+
+    # create table of contents if we contain sections
+      
+    def add_table_of_sections
+      toc = []
+      @context.sections.each do |section|
+        if section.title
+          toc << {
+            'secname' => section.title,
+            'href'    => section.sequence
+          }
+        end
+      end
+      
+      @values['toc'] = toc unless toc.empty?
+    end
+
+
   end
 
   #####################################################################
@@ -604,6 +633,7 @@ module Generators
 
     def value_hash
       class_attribute_values
+      add_table_of_sections
 
       @values["charset"] = @options.charset
       @values["style_url"] = style_url(path, @options.css)
@@ -614,30 +644,43 @@ module Generators
       ml = build_method_summary_list
       @values["methods"] = ml unless ml.empty?
 
-      al = build_alias_summary_list
-      @values["aliases"] = al unless al.empty?
-
-      co = build_constants_summary_list
-      @values["constants"] = co unless co.empty?
-
       il = build_include_list(@context)
       @values["includes"] = il unless il.empty?
 
-      al = build_attribute_list
+      @values["sections"] = @context.sections.map do |section|
-      @values["attributes"] = al unless al.empty?
 
-      cl = build_class_list(0, @context)
+        secdata = {
-      @values["classlist"] = cl unless cl.empty?
+          "sectitle" => section.title,
+          "secsequence" => section.sequence,
+          "seccomment" => markup(section.comment)
+        }
+
+        al = build_alias_summary_list(section)
+        secdata["aliases"] = al unless al.empty?
+        
+        co = build_constants_summary_list(section)
+        secdata["constants"] = co unless co.empty?
+        
+        al = build_attribute_list(section)
+        secdata["attributes"] = al unless al.empty?
+        
+        cl = build_class_list(0, @context, section)
+        secdata["classlist"] = cl unless cl.empty?
+        
+        mdl = build_method_detail_list(section)
+        secdata["method_list"] = mdl unless mdl.empty?
+
+        secdata
+      end
 
-      mdl = build_method_detail_list
-      @values["method_list"] = mdl unless mdl.empty?
       @values
     end
 
-    def build_attribute_list
+    def build_attribute_list(section)
       atts = @context.attributes.sort
       res = []
       atts.each do |att|
+        next unless att.section == section
         if att.visibility == :public || @options.show_all
           entry = {
             "name"   => CGI.escapeHTML(att.name), 
@@ -701,7 +744,6 @@ module Generators
       end
 
       @values['infiles'] = files
-
     end
 
     def <=>(other)
@@ -759,6 +801,7 @@ module Generators
 
     def value_hash
       file_attribute_values
+      add_table_of_sections
 
       @values["charset"]   = @options.charset
       @values["href"]      = path
@@ -778,23 +821,36 @@ module Generators
       rl = build_requires_list(@context)
       @values["requires"] = rl unless rl.empty?
 
-      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
         file_context = @context
       end
 
-      cl = build_class_list(0, @context, file_context)
+
+      @values["sections"] = @context.sections.map do |section|
+
+        secdata = {
+          "sectitle" => section.title,
+          "secsequence" => section.sequence,
+          "seccomment" => markup(section.comment)
+        }
+
+        cl = build_class_list(0, @context, section, file_context)
         @values["classlist"] = cl unless cl.empty?
 
-      mdl = build_method_detail_list
+        mdl = build_method_detail_list(section)
-      @values["method_list"] = mdl unless mdl.empty?
+        secdata["method_list"] = mdl unless mdl.empty?
+
+        al = build_alias_summary_list(section)
+        secdata["aliases"] = al unless al.empty?
+        
+        co = build_constants_summary_list(section)
+        @values["constants"] = co unless co.empty?
+
+        secdata
+      end
+      
       @values
     end
     
@@ -885,6 +941,10 @@ module Generators
       @context.name
     end
 
+    def section
+      @context.section
+    end
+
     def index_name
       "#{@context.name} (#{@html_class.name})"
     end

lib/rdoc/generators/template/html/html.rb

@@ -26,13 +26,16 @@ module RDoc
 
 STYLE = %{
 body {
+    font-family: Verdana,Arial,Helvetica,sans-serif;
+    font-size:   90%;
     margin: 0;
+    margin-left: 40px;
     padding: 0;
     background: white;
 }
 
 h1,h2,h3,h4 { margin: 0; color: #efefef; background: transparent; }
-h1 { font-size: 120%; }
+h1 { font-size: 150%; }
 h2,h3,h4 { margin-top: 1em; }
 
 a { background: #eef; color: #039; text-decoration: none; }
@@ -45,56 +48,70 @@ td > a {
   text-decoration: none;
 }
 
+/* and inside a section title */
+.section-title > a {
+  background: transparent;
+  color: #eee;
+  text-decoration: none;
+}
+
 /* === Structural elements =================================== */
 
 div#index {
     margin: 0;
+    margin-left: -40px;
     padding: 0;
-    font-size: 0.9em;
+    font-size: 90%;
 }
 
+
 div#index a {
     margin-left: 0.7em;
 }
 
-div#classHeader {
+div#index .section-bar {
+   margin-left: 0px;
+   padding-left: 0.7em;
+   background: #ccc;
+   font-size: small;
+}
+
+
+div#classHeader, div#fileHeader {
     width: auto;
-    background: #039;
     color: white;
     padding: 0.5em 1.5em 0.5em 1.5em;
     margin: 0;
+    margin-left: -40px;
     border-bottom: 3px solid #006;
 }
 
-div#classHeader a {
+div#classHeader a, div#fileHeader a {
     background: inherit;
     color: white;
 }
 
-div#classHeader td {
+div#classHeader td, div#fileHeader td {
     background: inherit;
     color: white;
 }
 
+
 div#fileHeader {
-    width: auto;
+    background: #057;
-    background: #039;
-    color: white;
-    padding: 0.5em 1.5em 0.5em 1.5em;
-    margin: 0;
-    border-bottom: 3px solid #006;
 }
 
-div#fileHeader a {
+div#classHeader {
-    background: inherit;
+    background: #048;
-    color: white;
 }
 
-div#fileHeader td {
+
-    background: inherit;
+.class-name-in-header {
-    color: white;
+  font-size:  180%;
+  font-weight: bold;
 }
 
+
 div#bodyContent {
     padding: 0 1.5em 0 1.5em;
 }
@@ -105,7 +122,7 @@ div#description {
     border: 1px dotted #999;
 }
 
-div#description h1,h2,h3,h4,h5,h6 {
+div#description h1,h3,h3,h4,h5,h6 {
     color: black;
     background: transparent;
 }
@@ -137,33 +154,49 @@ table.header-table {
     color: #DEDEDE;
 }
 
-.section-bar {
+.xxsection-bar {
     background: #eee;
     color: #333;
     padding: 3px;
+}
+
+.section-bar {
+   color: #333;
+   border-bottom: 1px solid #999;
+    margin-left: -20px;
+}
+
+
+.section-title {
+    background: #79a;
+    color: #eee;
+    padding: 3px;
+    margin-top: 2em;
+    margin-left: -30px;
     border: 1px solid #999;
 }
 
-.top-aligned-row { vertical-align: vertical-align: top }
+.top-aligned-row {  vertical-align: top }
+.bottom-aligned-row { vertical-align: bottom }
 
 /* --- Context section classes ----------------------- */
 
 .context-row { }
 .context-item-name { font-family: monospace; font-weight: bold; color: black; }
-.context-item-value { font-size: x-small; color: #448; }
+.context-item-value { font-size: small; color: #448; }
-.context-item-desc { background: #efefef; }
+.context-item-desc { color: #333; padding-left: 2em; }
 
 /* --- Method classes -------------------------- */
 .method-detail {
-    background: #EFEFEF;
+    background: #efefef;
     padding: 0;
     margin-top: 0.5em;
-    margin-bottom: 0.5em;
+    margin-bottom: 1em;
-    border: 1px dotted #DDD;
+    border: 1px dotted #ccc;
 }
 .method-heading {
   color: black;
-	background: #AAA;
+  background: #ccc;
   border-bottom: 1px solid #666;
   padding: 0.2em 0.5em 0 0.5em;
 }
@@ -261,120 +294,6 @@ HEADER = XHTML_PREAMBLE + %{
 #####################################################################
 
 CONTEXT_CONTENT = %{
-	<div id="contextContent">
-IF:diagram
-		<div id="diagram">
-			%diagram%
-		</div>
-ENDIF:diagram
-
-IF:description
-		<div id="description">
-			%description%
-		</div>
-ENDIF:description
-
-IF:requires
-		<div id="requires-list">
-			<h2 class="section-bar">Required files</h2>
-
-			<div class="name-list">
-START:requires
-			HREF:aref:name:&nbsp;&nbsp;
-END:requires
-			</div>
-		</div>
-ENDIF:requires
-
-IF:methods
-		<div id="method-list">
-			<h2 class="section-bar">Methods</h2>
-
-			<div class="name-list">
-START:methods
-			HREF:aref:name:&nbsp;&nbsp;
-END:methods
-			</div>
-		</div>
-ENDIF:methods
-
-IF:constants
-		<div id="constants-list">
-			<h2 class="section-bar">Constants</h2>
-
-			<div class="name-list">
-				<table summary="Constants">
-START:constants
-				<tr class="top-aligned-row context-row">
-					<td class="context-item-name">%name%</td>
-					<td>=</td>
-					<td class="context-item-value">%value%</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:constants
-				</table>
-			</div>
-		</div>
-ENDIF:constants
-
-IF:aliases
-		<div id="aliases-list">
-			<h2 class="section-bar">External Aliases</h2>
-
-			<div class="name-list">
-                        <table summary="aliases">
-START:aliases
-				<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
-
-
-IF:attributes
-		<div id="attribute-list">
-			<h2 class="section-bar">Attributes</h2>
-
-			<div class="name-list">
-				<table>
-START:attributes
-				<tr class="top-aligned-row context-row">
-					<td class="context-item-name">%name%</td>
-					<td class="context-item-value">&nbsp;[%rw%]&nbsp;</td>
-					<td class="context-item-desc">%a_desc%</td>
-				</tr>
-END:attributes
-				</table>
-			</div>
-		</div>
-ENDIF:attributes
-			
-IF:classlist
-		<div id="class-list">
-			<h2 class="section-bar">Classes and Modules</h2>
-
-			%classlist%
-		</div>
-ENDIF:classlist
-
-	</div>
-
 }
 
 
@@ -422,8 +341,11 @@ ENDIF:cvsurl
 
 CLASS_PAGE = %{
     <div id="classHeader">
-        <h1>%full_name% <sup class="type-note">(%classmod%)</sup></h1>
         <table class="header-table">
+        <tr class="top-aligned-row">
+          <td><strong>%classmod%</strong></td>
+          <td class="class-name-in-header">%full_name%</td>
+        </tr>
         <tr class="top-aligned-row">
             <td><strong>In:</strong></td>
             <td>
@@ -468,10 +390,61 @@ ENDIF:parent
 
 METHOD_LIST = %{
 
+  <div id="contextContent">
+IF:diagram
+    <div id="diagram">
+      %diagram%
+    </div>
+ENDIF:diagram
+
+IF:description
+    <div id="description">
+      %description%
+    </div>
+ENDIF:description
+
+IF:requires
+    <div id="requires-list">
+      <h3 class="section-bar">Required files</h3>
+
+      <div class="name-list">
+START:requires
+      HREF:aref:name:&nbsp;&nbsp;
+END:requires
+      </div>
+    </div>
+ENDIF:requires
+
+IF:toc
+    <div id="contents-list">
+      <h3 class="section-bar">Contents</h3>
+      <ul>
+START:toc
+      <li><a href="#%href%">%secname%</a></li>
+END:toc
+     </ul>
+ENDIF:toc
+   </div>
+
+IF:methods
+    <div id="method-list">
+      <h3 class="section-bar">Methods</h3>
+
+      <div class="name-list">
+START:methods
+      HREF:aref:name:&nbsp;&nbsp;
+END:methods
+      </div>
+    </div>
+ENDIF:methods
+
+  </div>
+
+
     <!-- if includes -->
 IF:includes
     <div id="includes">
-			<h2 class="section-bar">Included Modules</h2>
+      <h3 class="section-bar">Included Modules</h3>
 
       <div id="includes-list">
 START:includes
@@ -481,13 +454,98 @@ END:includes
     </div>
 ENDIF:includes
 
+START:sections
+    <div id="section">
+IF:sectitle
+      <h2 class="section-title"><a name="%secsequence%">%sectitle%</a></h2>
+IF:seccomment
+      <div class="section-comment">
+        %seccomment%
+      </div>      
+ENDIF:seccomment
+ENDIF:sectitle
+
+IF:classlist
+    <div id="class-list">
+      <h3 class="section-bar">Classes and Modules</h3>
+
+      %classlist%
+    </div>
+ENDIF:classlist
+
+IF:constants
+    <div id="constants-list">
+      <h3 class="section-bar">Constants</h3>
+
+      <div class="name-list">
+        <table summary="Constants">
+START:constants
+        <tr class="top-aligned-row context-row">
+          <td class="context-item-name">%name%</td>
+          <td>=</td>
+          <td class="context-item-value">%value%</td>
+IF:desc
+          <td width="3em">&nbsp;</td>
+          <td class="context-item-desc">%desc%</td>
+ENDIF:desc
+        </tr>
+END:constants
+        </table>
+      </div>
+    </div>
+ENDIF:constants
+
+IF:aliases
+    <div id="aliases-list">
+      <h3 class="section-bar">External Aliases</h3>
+
+      <div class="name-list">
+                        <table summary="aliases">
+START:aliases
+        <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
+
+
+IF:attributes
+    <div id="attribute-list">
+      <h3 class="section-bar">Attributes</h3>
+
+      <div class="name-list">
+        <table>
+START:attributes
+        <tr class="top-aligned-row context-row">
+          <td class="context-item-name">%name%</td>
+          <td class="context-item-value">&nbsp;[%rw%]&nbsp;</td>
+          <td class="context-item-desc">%a_desc%</td>
+        </tr>
+END:attributes
+        </table>
+      </div>
+    </div>
+ENDIF:attributes
+      
+
 
     <!-- if method_list -->
 IF:method_list
     <div id="methods">
 START:method_list
 IF:methods
-			<h2 class="section-bar">%type% %category% methods</h2>
+      <h3 class="section-bar">%type% %category% methods</h3>
 
 START:methods
       <div id="method-%aref%" class="method-detail">
@@ -537,6 +595,7 @@ END:method_list
 
     </div>
 ENDIF:method_list
+END:sections
 }
 
 
@@ -550,7 +609,7 @@ BODY = HEADER + %{
 
   <div id="bodyContent">
 
-} + CONTEXT_CONTENT + METHOD_LIST + %{
+} +  METHOD_LIST + %{
 
   </div>
 

lib/rdoc/options.rb

@@ -391,7 +391,7 @@ class Options
         when "--line-numbers"  then @include_line_numbers = true
         when "--main"          then @main_page     = arg
         when "--merge"         then @merge         = true
-        when "--one-file"      then @all_one_file  = true
+        when "--one-file"      then @all_one_file  = @inline_source = true
         when "--op"            then @op_dir        = arg
         when "--opname"        then @op_name       = arg
         when "--promiscuous"   then @promiscuous   = true

lib/rdoc/parsers/parse_rb.rb

@@ -1580,23 +1580,6 @@ module RDoc
         
         non_comment_seen = true unless tk.kind_of?(TkCOMMENT)
         
-#         $stderr.puts "===== #{tk.inspect}"
-#         blank_line_seen = true
-#         while tk.kind_of?(TkNL)
-#           skip_tkspace(false)
-#           if peek_tk.kind_of?(TkCOMMENT)
-#             if blank_line_seen
-#               comment = ''
-#               blank_line_seen = false
-#             end
-#             tk = get_tk
-#             comment << tk.text << "\n"
-#           else
-#             blank_line_seen = true
-#           end
-#           tk = get_tk
-#         end
-
 	case tk
 
         when TkNL
@@ -2326,6 +2309,10 @@ module RDoc
           options.title = param
           ""
 
+        when "section"
+          context.set_current_section(param, comment)
+          comment.clear
+          ""
         else
           warn "Unrecognized directive '#{directive}'"
           break
@@ -2548,7 +2535,7 @@ module RDoc
 	    break
 	  when TkCOMMA
 	  else
-	    warn("unexpected token: '#{tk.inspect}'")
+	    warn("unexpected token: '#{tk2.inspect}'") if $DEBBUG
 	    break
 	  end
 	end