Merge from HEAD.

Add --system, --site, --home, --gems to ri.
Allow --doc-dir to be specified multiple times.


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

ChangeLog

@@ -1,3 +1,8 @@
+Mon Jun 26 13:37:27 2006  Eric Hodel  <drbrain@segment7.net>
+
+	* lib/rdoc: Merge from HEAD.
+	  Add options to limit the ri search path.
+
 Tue Jun 27 00:54:08 2006  Nobuyoshi Nakada  <nobu@ruby-lang.org>
 
 	* util.c (powersOf10): constified.

lib/rdoc/diagram.rb

@@ -295,7 +295,7 @@ module RDoc
         f << graph.to_s << "\n"
       end
       
-      system "dot -T#{op_type} #{src} -o #{dot}"
+      system "dot", "-T#{op_type}", src, "-o", dot
 
       # Now construct the imagemap wrapper around
       # that png

lib/rdoc/generators/chm_generator.rb

@@ -4,7 +4,7 @@ module Generators
 
   class CHMGenerator < HTMLGenerator
 
-    HHC_PATH = "c:\\Program Files\\HTML Help Workshop\\hhc.exe"
+    HHC_PATH = "c:/Program Files/HTML Help Workshop/hhc.exe"
 
     # Standard generator factory
     def CHMGenerator.for(options)
@@ -103,7 +103,7 @@ module Generators
 
     # Invoke the windows help compiler to compiler the project
     def compile_project
-      system("\"#{HHC_PATH}\" #@project_name")
+      system(HHC_PATH, @project_name)
     end
 
   end

lib/rdoc/markup/simple_markup/inline.rb

@@ -183,7 +183,7 @@ module SM
       unless SPECIAL.empty?
         SPECIAL.each do |regexp, attr|
           str.scan(regexp) do
-            attrs.set_attrs($`.length, $1.length, attr | Attribute::SPECIAL)
+            attrs.set_attrs($`.length, $&.length, attr | Attribute::SPECIAL)
           end
         end
       end
@@ -215,6 +215,8 @@ module SM
       add_html("b",  :BOLD)
       add_html("tt",   :TT)
       add_html("code", :TT)
+
+      add_special(/<!--(.*?)-->/, :COMMENT)
     end
 
     def add_word_pair(start, stop, name)

lib/rdoc/markup/simple_markup/preprocess.rb

@@ -43,7 +43,12 @@ module SM
     def include_file(name, indent)
       if (full_name = find_include_file(name))
         content = File.open(full_name) {|f| f.read}
-        res = content.gsub(/^#?/, indent)
+        # strip leading '#'s, but only if all lines start with them
+        if content =~ /^[^#]/
+          content.gsub(/^/, indent)
+        else
+          content.gsub(/^#?/, indent)
+        end
       else
         $stderr.puts "Couldn't find file to include: '#{name}'"
         ''

lib/rdoc/parsers/parse_c.rb

@@ -262,7 +262,7 @@ module RDoc
     def find_class_comment(class_name, class_meth)
       comment = nil
       if @body =~ %r{((?>/\*.*?\*/\s+))
-                     (static\s+)?void\s+Init_#{class_name}\s*\(\)}xmi
+                     (static\s+)?void\s+Init_#{class_name}\s*(?:_\(\s*)?\(\s*(?:void\s*)\)}xmi
         comment = $1
       elsif @body =~ %r{Document-(class|module):\s#{class_name}\s*?\n((?>.*?\*/))}m
         comment = $2

lib/rdoc/ri/ri_display.rb

@@ -194,12 +194,15 @@ class  DefaultDisplay
   ######################################################################
 
   def page
-    setup_pager
+    return yield unless pager = setup_pager
     begin
+      save_stdout = STDOUT.clone
+      STDOUT.reopen(pager)
       yield
-      page_output
     ensure
-      STDOUT.reopen(@save_stdout) if @save_stdout
+      STDOUT.reopen(save_stdout)
+      save_stdout.close
+      pager.close
     end
   end
 
@@ -207,31 +210,11 @@ class  DefaultDisplay
 
   def setup_pager
     unless @options.use_stdout
-      require 'tempfile'
+      for pager in [ ENV['PAGER'], "less", "more", 'pager' ].compact.uniq
-
+        return IO.popen(pager, "w") rescue nil
-      @save_stdout = STDOUT.clone
-      STDOUT.reopen(Tempfile.new("ri_"))
-    end
-  end
-
-  ######################################################################
-
-  def page_output
-    unless @options.use_stdout
-      path = STDOUT.path
-      STDOUT.reopen(@save_stdout)
-      @save_stdout = nil
-      paged = false
-      for pager in [ ENV['PAGER'], "less", "more <", 'pager' ].compact.uniq
-        if system("#{pager} #{path}")
-          paged = true
-          break
-        end
-      end
-      if !paged
-        @options.use_stdout = true
-        puts File.read(path)
       end
+      @options.use_stdout = true
+      nil
     end
   end
 
@@ -255,12 +238,6 @@ class  DefaultDisplay
   end
   ######################################################################
   
-  def warn_no_database
-    puts "Before using ri, you need to generate documentation"
-    puts "using 'rdoc' with the --ri option"
-  end
-  ######################################################################
-  
   def display_flow(flow)
     if !flow || flow.empty?
       @formatter.wrap("(no description...)")
@@ -269,5 +246,10 @@ class  DefaultDisplay
     end
   end
 
-
+  ######################################################################
+  
+  def warn_no_database
+    puts "Before using ri, you need to generate documentation"
+    puts "using 'rdoc' with the --ri option"
+  end
 end  # class RiDisplay

lib/rdoc/ri/ri_driver.rb

@@ -1,5 +1,6 @@
 require 'rdoc/usage'
 require 'rdoc/ri/ri_paths'
+require 'rdoc/usage'
 require 'rdoc/ri/ri_cache'
 require 'rdoc/ri/ri_util'
 require 'rdoc/ri/ri_reader'
@@ -21,20 +22,18 @@ class  RiDriver
 
     @options.parse(args)
 
-    paths = @options.paths || RI::Paths::PATH
+    path = @options.path
-    if paths.empty?
+    report_missing_documentation @options.raw_path if path.empty?
-      report_missing_documentation(paths)
-    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)
+    @ri_reader = RI::RiReader.new(RI::RiCache.new(path))
+    @display   = @options.displayer
+  end
+  
+  # Couldn't find documentation in +path+, so tell the user what to do
+
+  def report_missing_documentation(path)
     STDERR.puts "No ri documentation found in:"
-    paths.each do |d|
+    path.each do |d|
       STDERR.puts "     #{d}"
     end
     STDERR.puts "\nWas rdoc run to create documentation?\n\n"

lib/rdoc/ri/ri_formatter.rb

@@ -43,7 +43,7 @@ module RI
         end
       end
       res << work if work.length.nonzero?
-      puts(prefix +  res.join("\n" + next_prefix))
+      puts(prefix + res.join("\n" + next_prefix))
     end
 
     ######################################################################

lib/rdoc/ri/ri_options.rb

@@ -37,23 +37,41 @@ module RI
       
       OPTION_LIST = [
         [ "--help",          "-h",   nil,
-         "you're looking at it" ],
+          "you're looking at it" ],
 
         [ "--classes",      "-c",   nil,
           "Display the names of classes and modules we\n" +
           "know about"],
 
         [ "--doc-dir",      "-d",   "<dirname>",
-          "A directory to search for documentation. If not\n"+
+          "A directory to search for documentation. If not\n" +
-          "specified, we search the standard rdoc/ri directories."],
+          "specified, we search the standard rdoc/ri directories.\n" +
+          "May be repeated."],
+
+        [ "--system",       nil,    nil,
+          "Include documentation from Ruby's standard library:\n  " +
+          RI::Paths::SYSDIR ],
+
+        [ "--site",         nil,    nil,
+          "Include documentation from libraries installed in site_lib:\n  " +
+          RI::Paths::SITEDIR ],
+
+        [ "--home",         nil,    nil,
+          "Include documentation stored in ~/.rdoc:\n  " +
+          (RI::Paths::HOMEDIR || "No ~/.rdoc found") ],
+
+        [ "--gems",         nil,    nil,
+          "Include documentation from Rubygems:\n  " +
+          (RI::Paths::GEMDIRS ? "#{Gem.path}/doc/*/ri" :
+                                "No Rubygems ri found.") ],
                                                            
         [ "--format",       "-f",   "<name>",
-         "Format to use when displaying output:\n" +
+          "Format to use when displaying output:\n" +
-         "   " + RI::TextFormatter.list + "\n" +
+          "   " + RI::TextFormatter.list + "\n" +
-         "Use 'bs' (backspace) with most pager programs.\n" +
+          "Use 'bs' (backspace) with most pager programs.\n" +
-         "To use ANSI, either also use the -T option, or\n" +
+          "To use ANSI, either also use the -T option, or\n" +
-         "tell your pager to allow control characters\n" +
+          "tell your pager to allow control characters\n" +
-         "(for example using the -R option to less)"],
+          "(for example using the -R option to less)"],
 
         [ "--list-names",    "-l",   nil,
           "List all the names known to RDoc, one per line"
@@ -74,10 +92,12 @@ module RI
 
       def OptionList.options
         OPTION_LIST.map do |long, short, arg,|
-          [ long, 
+          option = []
-           short, 
+          option << long
-           arg ? GetoptLong::REQUIRED_ARGUMENT : GetoptLong::NO_ARGUMENT 
+          option << short unless short.nil?
-          ]
+          option << (arg ? GetoptLong::REQUIRED_ARGUMENT :
+                           GetoptLong::NO_ARGUMENT)
+          option
         end
       end
 
@@ -108,6 +128,17 @@ module RI
         puts
         
         name = File.basename($0)
+
+        directories = [
+          RI::Paths::SYSDIR,
+          RI::Paths::SITEDIR,
+          RI::Paths::HOMEDIR
+        ]
+
+        directories << "#{Gem.path}/doc/*/ri" if RI::Paths::GEMDIRS
+
+        directories = directories.join("\n    ")
+
         OptionList.strip_output(<<-EOT)
           Usage:
 
@@ -136,6 +167,15 @@ module RI
               ri 'Array.[]'
               ri compact\\!
 
+          By default ri searches for documentation in the following
+          directories:
+
+              #{directories}
+
+          Specifying the --system, --site, --home, --gems or --doc-dir
+          options will limit ri to searching only the specified
+          directories.
+
         EOT
 
         if short_form
@@ -144,7 +184,9 @@ module RI
         else
           puts "Options:\n\n"
           OPTION_LIST.each do|long, short, arg, desc|
-            opt = sprintf("%15s", "#{long}, #{short}")
+            opt = ''
+            opt << (short ? sprintf("%15s", "#{long}, #{short}") :
+                            sprintf("%15s", long))
             if arg
               opt << " " << arg
             end
@@ -173,26 +215,29 @@ module RI
       exit(0)
     end
 
-
     def initialize
       @use_stdout   = !STDOUT.tty?
       @width        = 72
       @formatter    = RI::TextFormatter.for("plain") 
       @list_classes = false
       @list_names   = false
-    end
 
+      # By default all paths are used.  If any of these are true, only those
+      # directories are used.
+      @use_system = false
+      @use_site = false
+      @use_home = false
+      @use_gems = false
+      @doc_dirs = []
+    end
 
     # Parse command line options.
 
     def parse(args)
     
       old_argv = ARGV.dup
-#      if ENV["RI"]
-#        ARGV.replace(ENV["RI"].split.concat(ARGV))
-#      end
 
-     ARGV.replace(args)
+      ARGV.replace(args)
 
       begin
 
@@ -206,9 +251,15 @@ module RI
           when "--list-names" then @list_names = true
           when "--no-pager"   then @use_stdout = true
           when "--classes"    then @list_classes = true
+
+          when "--system"     then @use_system = true
+          when "--site"       then @use_site = true
+          when "--home"       then @use_home = true
+          when "--gems"       then @use_gems = true
+
           when "--doc-dir"
             if File.directory?(arg)
-              @doc_dir = arg
+              @doc_dirs << arg
             else
               $stderr.puts "Invalid directory: #{arg}"
               exit 1
@@ -237,9 +288,15 @@ module RI
       end
     end
 
-    # Return the doc_dir as an array, or nil if no overriding doc dir was given
+    # Return the selected documentation directories.
-    def paths
+
-      defined?(@doc_dir) ? [ @doc_dir ] : nil
+    def path
+      RI::Paths.path(@use_system, @use_site, @use_home, @use_gems, *@doc_dirs)
+    end
+
+    def raw_path
+      RI::Paths.raw_path(@use_system, @use_site, @use_home, @use_gems,
+                         *@doc_dirs)
     end
 
     # Return an instance of the displayer (the thing that actually writes

lib/rdoc/ri/ri_paths.rb

@@ -29,13 +29,7 @@ module RI
     version = Config::CONFIG['ruby_version']
 
     base    = File.join(Config::CONFIG['datadir'], "ri", version)
-
+    SYSDIR  = File.join(base, "system")
-    if ENV["DESTDIR"]
-      SYSDIR = File.join(ENV["DESTDIR"], base, "system")
-    else
-      SYSDIR  = File.join(base, "system")
-    end
-
     SITEDIR = File.join(base, "site")
     homedir = ENV['HOME'] || ENV['USERPROFILE'] || ENV['HOMEPATH']
 
@@ -50,8 +44,37 @@ module RI
 
     begin
       require 'rubygems'
-      Dir["#{Gem.path}/doc/*/ri"].each { |path| RI::Paths::PATH << path }
+      GEMDIRS = Dir["#{Gem.path}/doc/*/ri"]
+      GEMDIRS.each { |path| RI::Paths::PATH << path }
     rescue LoadError
+      GEMDIRS = nil
     end
+
+    # Returns the selected documentation directories as an Array, or PATH if no
+    # overriding directories were given.
+
+    def self.path(use_system, use_site, use_home, use_gems, *extra_dirs)
+      path = raw_path(use_system, use_site, use_home, use_gems, *extra_dirs)
+      return path.select { |path| File.directory? path }
+    end
+
+    # Returns the selected documentation directories including nonexistent
+    # directories.  Used to print out what paths were searched if no ri was
+    # found.
+
+    def self.raw_path(use_system, use_site, use_home, use_gems, *extra_dirs)
+      return PATH unless use_system or use_site or use_home or use_gems or
+                         not extra_dirs.empty?
+
+      path = []
+      path << extra_dirs unless extra_dirs.empty?
+      path << RI::Paths::SYSDIR if use_system
+      path << RI::Paths::SITEDIR if use_site
+      path << RI::Paths::HOMEDIR if use_home
+      path << RI::Paths::GEMDIRS if use_gems
+
+      return path.flatten.compact
+    end
+
   end
 end