ri now merges the documentation if it finds the same class in multiple places

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

ChangeLog

@@ -1,3 +1,8 @@
+Mon Aug 30 23:11:06 2004  Dave Thomas  <dave@pragprog.com>
+
+	* lib/rdoc/ri/ri_driver.rb (and others): ri now merges documentation
+	  if it finds the same class in multiple places.
+
 Mon Aug 30 22:40:30 2004  Hidetoshi NAGAI  <nagai@ai.kyutech.ac.jp>
 
 	* ext/tk/lib/multi-tk.rb: 'restart' method accepts arguments

bin/ri

@@ -12,6 +12,33 @@
 #
 # The form '.' method matches either class or instance methods, while 
 # #method matches only instance and ::method matches only class methods.
+#
+#
+# == Installing Documentation
+#
+# 'ri' uses a database of documentation built by the RDoc utility.
+# 
+# So, how do you install this documentation on your system?
+# It depends on how you installed Ruby.
+#
+# <em>If you installed Ruby from source files</em> (that is, if it some point
+# you typed 'make' during the process :), you can install the RDoc
+# documentation yourself. Just go back to the place where you have 
+# your Ruby source and type
+#
+#    make install-doc
+#
+# You'll probably need to do this as a superuser, as the documentation
+# is installed in the Ruby target tree (normally somewhere under 
+# <tt>/usr/local</tt>.
+#
+# <em>If you installed Ruby from a binary distribution</em> (perhaps
+# using a one-click installer, or using some other packaging system),
+# then the team that produced the package probably forgot to package
+# the documentation as well. Contact them, and see if they can add
+# it to the next release.
+#
+
 
 require 'rdoc/ri/ri_driver'
 

lib/rdoc/markup/simple_markup/fragments.rb

@@ -1,5 +1,5 @@
 require 'rdoc/markup/simple_markup/lines.rb'
-require 'rdoc/markup/simple_markup/inline.rb'
+#require 'rdoc/markup/simple_markup/to_flow.rb'
 
 module SM
 

lib/rdoc/markup/simple_markup/to_flow.rb

@@ -23,14 +23,13 @@ module SM
   end
 
   class ToFlow
-
     LIST_TYPE_TO_HTML = {
-      ListBase::BULLET =>  [ "<ul>", "</ul>" ],
+      SM::ListBase::BULLET     =>  [ "<ul>", "</ul>" ],
-      ListBase::NUMBER =>  [ "<ol>", "</ol>" ],
+      SM::ListBase::NUMBER     =>  [ "<ol>", "</ol>" ],
-      ListBase::UPPERALPHA =>  [ "<ol>", "</ol>" ],
+      SM::ListBase::UPPERALPHA =>  [ "<ol>", "</ol>" ],
-      ListBase::LOWERALPHA =>  [ "<ol>", "</ol>" ],
+      SM::ListBase::LOWERALPHA =>  [ "<ol>", "</ol>" ],
-      ListBase::LABELED => [ "<dl>", "</dl>" ],
+      SM::ListBase::LABELED    =>  [ "<dl>", "</dl>" ],
-      ListBase::NOTE    => [ "<table>", "</table>" ],
+      SM::ListBase::NOTE       =>  [ "<table>", "</table>" ],
     }
 
     InlineTag = Struct.new(:bit, :on, :off)

lib/rdoc/ri/ri_cache.rb

@@ -3,10 +3,10 @@ module RI
   class ClassEntry
 
     attr_reader :name
-    attr_reader :path_name
+    attr_reader :path_names
     
     def initialize(path_name, name, in_class)
-      @path_name = path_name
+      @path_names = [ path_name ]
       @name = name
       @in_class = in_class
       @class_methods    = []
@@ -14,6 +14,12 @@ module RI
       @inferior_classes = []
     end
 
+    # We found this class in more tha one place, so add
+    # in the name from there.
+    def add_path(path)
+      @path_names << path
+    end
+
     # read in our methods and any classes
     # and modules in our namespace. Methods are
     # stored in files called name-c|i.yaml,
@@ -38,10 +44,15 @@ module RI
         else
           full_name = File.join(dir, name)
           if File.directory?(full_name)
+            inf_class = @inferior_classes.find {|c| c.name == name }
+            if inf_class
+              inf_class.add_path(full_name)
+            else
               inf_class = ClassEntry.new(full_name, name, self)
-            inf_class.load_from(full_name)
               @inferior_classes << inf_class
             end
+            inf_class.load_from(full_name)
+          end
         end
       end
     end

lib/rdoc/ri/ri_descriptions.rb

@@ -1,4 +1,5 @@
 require 'yaml'
+require 'rdoc/markup/simple_markup/fragments'
 
 # Descriptions are created by RDoc (in ri_generator) and
 # written out in serialized form into the documentation
@@ -93,6 +94,9 @@ module RI
       merge(@includes, old.includes)
       if @comment.nil? || @comment.empty?
         @comment = old.comment
+      else
+        @comment << SM::Flow::RULE.new
+        @comment.concat old.comment
       end
     end
 

lib/rdoc/ri/ri_driver.rb

@@ -1,3 +1,4 @@
+require 'rdoc/usage'
 require 'rdoc/ri/ri_paths'
 require 'rdoc/ri/ri_cache'
 require 'rdoc/ri/ri_util'
@@ -22,18 +23,23 @@ class  RiDriver
 
     paths = @options.paths || RI::Paths::PATH
     if paths.empty?
-      $stderr.puts "No ri documentation found in:"
+      report_missing_documentation(paths)
-      [ RI::Paths::SYSDIR, RI::Paths::SITEDIR, RI::Paths::HOMEDIR].each do |d|
-        $stderr.puts "     #{d}"
-      end
-      $stderr.puts "\nWas rdoc run to create documentation?"
-      exit 1                   
     end
     @ri_reader = RI::RiReader.new(RI::RiCache.new(paths))
     @display   = @options.displayer
   end    
   
+  # Couldn't find documentation in paths, so tell the user
+  # what to do
 
+  def report_missing_documentation(paths)
+    STDERR.puts "No ri documentation found in:"
+    paths.each do |d|
+      STDERR.puts "     #{d}"
+    end
+    STDERR.puts "\nWas rdoc run to create documentation?\n\n"
+    RDoc::usage("Installing Documentation")
+  end
   
   ######################################################################
   
@@ -129,7 +135,7 @@ class  RiDriver
             get_info_for(arg)
           end
         rescue RiError => e
-          $stderr.puts(e.message)
+          STDERR.puts(e.message)
           exit(1)
         end
       end

lib/rdoc/ri/ri_options.rb

@@ -208,7 +208,13 @@ module RI
           when "--list-names" then @list_names = true
           when "--no-pager"   then @use_stdout = true
           when "--classes"    then @list_classes = true
-          when "--doc-dir"    then @doc_dir = arg
+          when "--doc-dir"
+            if File.directory?(arg)
+              @doc_dir = arg
+            else
+              $stderr.puts "Invalid directory: #{arg}"
+              exit 1
+            end
 
           when "--format"
             @formatter = RI::TextFormatter.for(arg)

lib/rdoc/ri/ri_reader.rb

@@ -48,8 +48,17 @@ module RI
 
     # Return a class description
     def get_class(class_entry)
-      path = RiWriter.class_desc_path(class_entry.path_name, class_entry)
+      result = nil
-      File.open(path) {|f| RI::Description.deserialize(f) }
+      for path in class_entry.path_names
+        path = RiWriter.class_desc_path(path, class_entry)
+        desc = File.open(path) {|f| RI::Description.deserialize(f) }
+        if result
+          result.merge_in(desc)
+        else
+          result = desc
+        end
+      end
+      result
     end
 
     # return the names of all classes and modules