rdoc 2.5.11 → 3.0

data/lib/rdoc/markup/verbatim.rb

@@ -3,6 +3,9 @@
 
 class RDoc::Markup::Verbatim < RDoc::Markup::Raw
 
+  ##
+  # Calls #accept_verbatim on +visitor+
+
   def accept visitor
     visitor.accept_verbatim self
   end
@@ -17,16 +20,16 @@ class RDoc::Markup::Verbatim < RDoc::Markup::Raw
 
     @parts.each do |part|
       case part
-      when /\n/ then
+      when /^\s*\n/ then
         newlines += 1
-        parts << part if newlines <= 2
+        parts << part if newlines == 1
       else
         newlines = 0
         parts << part
       end
     end
 
-    parts.slice!(-1) if parts[-2..-1] == ["\n", "\n"]
+    parts.pop if parts.last =~ /\A\r?\n\z/
 
     @parts = parts
   end

data/lib/rdoc/method_attr.rb

@@ -0,0 +1,353 @@
+require 'rdoc/code_object'
+
+##
+# Abstract class representing either a method or an attribute.
+
+class RDoc::MethodAttr < RDoc::CodeObject
+
+  include Comparable
+
+  ##
+  # Name of this method/attribute.
+
+  attr_accessor :name
+
+  ##
+  # public, protected, private
+
+  attr_accessor :visibility
+
+  ##
+  # Is this a singleton method/attribute?
+
+  attr_accessor :singleton
+
+  ##
+  # Source file token stream
+
+  attr_reader :text
+
+  ##
+  # Array of other names for this method/attribute
+
+  attr_reader :aliases
+
+  ##
+  # The method/attribute we're aliasing
+
+  attr_accessor :is_alias_for
+
+  #--
+  # The attributes below are for AnyMethod only.
+  # They are left here for the time being to
+  # allow ri to operate.
+  # TODO modify ri to avoid calling these on attributes.
+  #++
+
+  ##
+  # Parameters yielded by the called block
+
+  attr_reader :block_params
+
+  ##
+  # Parameters for this method
+
+  attr_accessor :params
+
+  ##
+  # Different ways to call this method
+
+  attr_accessor :call_seq
+
+  ##
+  # The call_seq or the param_seq with method name, if there is no call_seq.
+
+  attr_reader :arglists
+
+  ##
+  # Pretty parameter list for this method
+
+  attr_reader :param_seq
+
+
+  ##
+  # Creates a new MethodAttr from token stream +text+ and method or attribute
+  # name +name+.
+  #
+  # Usually this is called by super from a subclass.
+
+  def initialize text, name
+    super()
+
+    @text = text
+    @name = name
+
+    @aliases      = []
+    @is_alias_for = nil
+    @parent_name  = nil
+    @singleton    = nil
+    @visibility   = :public
+    @see = false
+
+    @arglists     = nil
+    @block_params = nil
+    @call_seq     = nil
+    @param_seq    = nil
+    @params       = nil
+  end
+
+  ##
+  # Order by #singleton then #name
+
+  def <=>(other)
+    [@singleton ? 0 : 1, name] <=> [other.singleton ? 0 : 1, other.name]
+  end
+
+  ##
+  # A method/attribute is documented if any of the following is true:
+  # - it was marked with :nodoc:;
+  # - it has a comment;
+  # - it is an alias for a documented method;
+  # - it has a +#see+ method that is documented.
+
+  def documented?
+    super or
+      (is_alias_for and is_alias_for.documented?) or
+      (see and see.documented?)
+  end
+
+  ##
+  # A method/attribute to look at,
+  # in particular if this method/attribute has no documentation.
+  #
+  # It can be a method/attribute of the superclass or of an included module,
+  # including the Kernel module, which is always appended to the included
+  # modules.
+  #
+  # Returns +nil+ if there is no such method/attribute.
+  # The +#is_alias_for+ method/attribute, if any, is not included.
+  #
+  # Templates may generate a "see also ..." if this method/attribute
+  # has documentation, and "see ..." if it does not.
+
+  def see
+    @see = find_see if @see == false
+    @see
+  end
+
+  def find_see # :nodoc:
+    return nil if singleton || is_alias_for
+
+    # look for the method
+    other = find_method_or_attribute name
+    return other if other
+
+    # if it is a setter, look for a getter
+    return nil unless name =~ /[a-z_]=$/i   # avoid == or ===
+    return find_method_or_attribute name[0..-2]
+  end
+
+  def find_method_or_attribute name # :nodoc:
+    return nil unless parent.respond_to? :ancestors
+
+    searched = parent.ancestors
+    kernel = RDoc::TopLevel.all_modules_hash['Kernel']
+
+    searched << kernel if kernel &&
+      parent != kernel && !searched.include?(kernel)
+
+    searched.each do |ancestor|
+      next if parent == ancestor
+      next if String === ancestor
+
+      other = ancestor.find_method_named('#' << name) ||
+              ancestor.find_attribute_named(name)
+
+      return other if other
+    end
+
+    nil
+  end
+
+  ##
+  # Abstract method. Contexts in their building phase call this
+  # to register a new alias for this known method/attribute.
+  #
+  # - creates a new AnyMethod/Attribute +newa+ named an_alias.new_name;
+  # - adds +self+ as +newa.is_alias_for+;
+  # - adds +newa+ to #aliases
+  # - adds +newa+ to the methods/attributes of +context+.
+
+  def add_alias(an_alias, context)
+    raise NotImplementedError
+  end
+
+  ##
+  # HTML fragment reference for this method
+
+  def aref
+    type = singleton ? 'c' : 'i'
+    # % characters are not allowed in html names => dash instead
+    "#{aref_prefix}-#{type}-#{html_name}"
+  end
+
+  ##
+  # Prefix for +aref+, defined by subclasses.
+
+  def aref_prefix
+    raise NotImplementedError
+  end
+
+  ##
+  # Attempts to sanitize the content passed by the ruby parser:
+  # remove outer parentheses, etc.
+
+  def block_params=(value)
+    # 'yield.to_s' or 'assert yield, msg'
+    return @block_params = '' if value =~ /^[\.,]/
+
+    # remove trailing 'if/unless ...'
+    return @block_params = '' if value =~ /^(if|unless)\s/
+
+    value = $1.strip if value =~ /^(.+)\s(if|unless)\s/
+
+    # outer parentheses
+    value = $1 if value =~ /^\s*\((.*)\)\s*$/
+    value = value.strip
+
+    # proc/lambda
+    return @block_params = $1 if value =~ /^(proc|lambda)(\s*\{|\sdo)/
+
+    # surrounding +...+ or [...]
+    value = $1.strip if value =~ /^\+(.*)\+$/
+    value = $1.strip if value =~ /^\[(.*)\]$/
+
+    return @block_params = '' if value.empty?
+
+    # global variable
+    return @block_params = 'str' if value =~ /^\$[&0-9]$/
+
+    # wipe out array/hash indices
+    value.gsub!(/(\w)\[[^\[]+\]/, '\1')
+
+    # remove @ from class/instance variables
+    value.gsub!(/@@?([a-z0-9_]+)/, '\1')
+
+    # method calls => method name
+    value.gsub!(/([A-Z:a-z0-9_]+)\.([a-z0-9_]+)(\s*\(\s*[a-z0-9_.,\s]*\s*\)\s*)?/) do
+      case $2
+      when 'to_s'      then $1
+      when 'const_get' then 'const'
+      when 'new' then
+        $1.split('::').last.  # ClassName => class_name
+          gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+          gsub(/([a-z\d])([A-Z])/,'\1_\2').
+          downcase
+      else
+        $2
+      end
+    end
+
+    # class prefixes
+    value.gsub!(/[A-Za-z0-9_:]+::/, '')
+
+    # simple expressions
+    value = $1 if value =~ /^([a-z0-9_]+)\s*[-*+\/]/
+
+    @block_params = value.strip
+  end
+
+  ##
+  # HTML id-friendly method/attribute name
+
+  def html_name
+    CGI.escape(@name.gsub('-', '-2D')).gsub('%','-').sub(/^-/, '')
+  end
+
+  ##
+  # Full method/attribute name including namespace
+
+  def full_name
+    @full_name || "#{parent_name}#{pretty_name}"
+  end
+
+  ##
+  # '::' for a class method/attribute, '#' for an instance method.
+
+  def name_prefix
+    singleton ? '::' : '#'
+  end
+
+  ##
+  # Method/attribute name with class/instance indicator
+
+  def pretty_name
+    "#{name_prefix}#{@name}"
+  end
+
+  ##
+  # Type of method/attribute (class or instance)
+
+  def type
+    singleton ? 'class' : 'instance'
+  end
+
+  ##
+  # Path to this method
+
+  def path
+    "#{@parent.path}##{aref}"
+  end
+
+  ##
+  # Name of our parent with special handling for un-marshaled methods
+
+  def parent_name
+    @parent_name || super
+  end
+
+  def pretty_print q # :nodoc:
+    alias_for = @is_alias_for ? "alias for #{@is_alias_for.name}" : nil
+
+    q.group 2, "[#{self.class.name} #{full_name} #{visibility}", "]" do
+      if alias_for then
+        q.breakable
+        q.text alias_for
+      end
+
+      if text then
+        q.breakable
+        q.text "text:"
+        q.breakable
+        q.pp @text
+      end
+
+      unless comment.empty? then
+        q.breakable
+        q.text "comment:"
+        q.breakable
+        q.pp @comment
+      end
+    end
+  end
+
+  def inspect # :nodoc:
+    alias_for = @is_alias_for ? " (alias for #{@is_alias_for.name})" : nil
+    "#<%s:0x%x %s (%s)%s>" % [
+      self.class, object_id,
+      full_name,
+      visibility,
+      alias_for,
+    ]
+  end
+
+  def to_s # :nodoc:
+    if @is_alias_for
+      "#{self.class.name}: #{full_name} -> #{is_alias_for}"
+    else
+      "#{self.class.name}: #{full_name}"
+    end
+  end
+
+end
+

data/lib/rdoc/normal_class.rb

@@ -6,10 +6,10 @@ require 'rdoc/class_module'
 class RDoc::NormalClass < RDoc::ClassModule
 
   ##
-  # Ancestor ClassModules
+  # Appends the superclass, if any, to the included modules.
 
   def ancestors
-    includes + [superclass]
+    superclass ? super + [superclass] : super
   end
 
   def inspect # :nodoc:
@@ -20,6 +20,15 @@ class RDoc::NormalClass < RDoc::ClassModule
     ]
   end
 
+  def to_s # :nodoc:
+    display = "#{self.class.name} #{self.full_name}"
+    if superclass
+      display << ' < ' << (superclass.is_a?(String) ? superclass : superclass.full_name)
+    end
+    display << ' -> ' << is_alias_for.to_s if is_alias_for
+    display
+  end
+
   def pretty_print q # :nodoc:
     superclass = @superclass ? " < #{@superclass}" : nil
 

data/lib/rdoc/normal_module.rb

@@ -5,11 +5,6 @@ require 'rdoc/class_module'
 
 class RDoc::NormalModule < RDoc::ClassModule
 
-  ##
-  # Included NormalModules
-
-  alias ancestors includes
-
   def inspect # :nodoc:
     "#<%s:0x%x module %s includes: %p attributes: %p methods: %p aliases: %p>" % [
       self.class, object_id,

data/lib/rdoc/options.rb

@@ -8,9 +8,41 @@ require 'rdoc/ri/paths'
 class RDoc::Options
 
   ##
-  # Character-set
+  # The deprecated options.
+
+  DEPRECATED = {
+    '--accessor'      => 'support discontinued',
+    '--diagram'       => 'support discontinued',
+    '--help-output'   => 'support discontinued',
+    '--image-format'  => 'was an option for --diagram',
+    '--inline-source' => 'source code is now always inlined',
+    '--merge'         => 'ri now always merges class information',
+    '--one-file'      => 'support discontinued',
+    '--op-name'       => 'support discontinued',
+    '--opname'        => 'support discontinued',
+    '--promiscuous'   => 'files always only document their content',
+    '--ri-system'     => 'Ruby installers use other techniques',
+  }
 
-  attr_reader :charset
+  ##
+  # Template option validator for OptionParser
+
+  Template = nil
+
+  ##
+  # Character-set for HTML output.  #encoding is preferred over #charset
+
+  attr_accessor :charset
+
+  ##
+  # If true, RDoc will not write any files.
+
+  attr_accessor :dry_run
+
+  ##
+  # Encoding of output where.  This is set via --encoding.
+
+  attr_accessor :encoding if Object.const_defined? :Encoding
 
   ##
   # Files matching this pattern will be excluded
@@ -22,10 +54,21 @@ class RDoc::Options
 
   attr_accessor :files
 
+  ##
+  # Create the output even if the output directory does not look
+  # like an rdoc output directory
+
+  attr_accessor :force_output
+
   ##
   # Scan newer sources than the flag file if true.
 
-  attr_reader :force_update
+  attr_accessor :force_update
+
+  ##
+  # Formatter to mark up text with
+
+  attr_accessor :formatter
 
   ##
   # Description of the output generator (set with the <tt>-fmt</tt> option)
@@ -33,9 +76,21 @@ class RDoc::Options
   attr_accessor :generator
 
   ##
-  # Formatter to mark up text with
+  # Loaded generator options.  Used to prevent --help from loading the same
+  # options multiple times.
 
-  attr_accessor :formatter
+  attr_accessor :generator_options
+
+  ##
+  # Old rdoc behavior: hyperlink all words that match a method name,
+  # even if not preceded by '#' or '::'
+
+  attr_accessor :hyperlink_all
+
+  ##
+  # Include line numbers in the source code
+
+  attr_accessor :line_numbers
 
   ##
   # Name of the file, class or module to display in the initial index page (if
@@ -43,11 +98,21 @@ class RDoc::Options
 
   attr_accessor :main_page
 
+  ##
+  # If true, only report on undocumented files
+
+  attr_accessor :coverage_report
+
   ##
   # The name of the output directory
 
   attr_accessor :op_dir
 
+  ##
+  # The OptionParser for this instance
+
+  attr_accessor :option_parser
+
   ##
   # Is RDoc in pipe mode?
 
@@ -56,27 +121,32 @@ class RDoc::Options
   ##
   # Array of directories to search for files to satisfy an :include:
 
-  attr_reader :rdoc_include
+  attr_accessor :rdoc_include
 
   ##
   # Include the '#' at the front of hyperlinked instance method names
 
-  attr_reader :show_hash
+  attr_accessor :show_hash
 
   ##
   # The number of columns in a tab
 
-  attr_reader :tab_width
+  attr_accessor :tab_width
 
   ##
   # Template to be used when generating output
 
-  attr_reader :template
+  attr_accessor :template
+
+  ##
+  # Directory the template lives in
+
+  attr_accessor :template_dir
 
   ##
   # Documentation title
 
-  attr_reader :title
+  attr_accessor :title
 
   ##
   # Verbosity, zero means quiet
@@ -86,28 +156,88 @@ class RDoc::Options
   ##
   # URL of web cvs frontend
 
-  attr_reader :webcvs
+  attr_accessor :webcvs
+
+  ##
+  # Minimum visibility of a documented method. One of +:public+,
+  # +:protected+, +:private+. May be overridden on a per-method
+  # basis with the :doc: directive.
+
+  attr_accessor :visibility
 
   def initialize # :nodoc:
     require 'rdoc/rdoc'
-    @op_dir = nil
-    @main_page = nil
+    @dry_run = false
     @exclude = []
-    @generators = RDoc::RDoc::GENERATORS
-    @generator = RDoc::Generator::Darkfish
+    @force_output = false
+    @force_update = true
+    @generator = nil
     @generator_name = nil
+    @generator_options = []
+    @generators = RDoc::RDoc::GENERATORS
+    @hyperlink_all = false
+    @line_numbers = false
+    @main_page = nil
+    @coverage_report = false
+    @op_dir = nil
+    @pipe = false
     @rdoc_include = []
-    @title = nil
-    @template = nil
     @show_hash = false
+    @stylesheet_url = nil
     @tab_width = 8
-    @force_update = true
+    @template = nil
+    @template_dir = nil
+    @title = nil
     @verbosity = 1
-    @pipe = false
-
+    @visibility = :protected
     @webcvs = nil
 
-    @charset = 'utf-8'
+    if Object.const_defined? :Encoding then
+      @encoding = Encoding.default_external
+      @charset = @encoding.to_s
+    else
+      @charset = 'UTF-8'
+    end
+  end
+
+  ##
+  # Check that the files on the command line exist
+
+  def check_files
+    @files.delete_if do |file|
+      if File.exist? file then
+        if File.readable? file then
+          false
+        else
+          warn "file '#{file}' not readable"
+
+          true
+        end
+      else
+        warn "file '#{file}' not found"
+
+        true
+      end
+    end
+  end
+
+  ##
+  # Ensure only one generator is loaded
+
+  def check_generator
+    if @generator then
+      raise OptionParser::InvalidOption,
+        "generator already set to #{@generator_name}"
+    end
+  end
+
+  ##
+  # Set the title, but only if not already set. Used to set the title
+  # from a source file, so that a title set from the command line
+  # will have the priority.
+
+  def default_title=(string)
+    @title ||= string
   end
 
   ##
@@ -116,7 +246,10 @@ class RDoc::Options
   def parse(argv)
     ignore_invalid = true
 
+    argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT']
+
     opts = OptionParser.new do |opt|
+      @option_parser = opt
       opt.program_name = File.basename $0
       opt.version = RDoc::VERSION
       opt.release = nil
@@ -133,6 +266,14 @@ Usage: #{opt.program_name} [options] [names...]
   How RDoc generates output depends on the output formatter being used, and on
   the options you give.
 
+  Options can be specified via the RDOCOPT environment variable, which
+  functions similar to the RUBYOPT environment variable for ruby.
+
+    $ export RDOCOPT="--show-hash"
+
+  will make rdoc show hashes in method links by default.  Command-line options
+  always will override those in RDOCOPT.
+
   - Darkfish creates frameless HTML output by Michael Granger.
   - ri creates ri data files
 
@@ -150,8 +291,46 @@ Usage: #{opt.program_name} [options] [names...]
         opt.banner << "  - #{parser}: #{regexp.join ', '}\n"
       end
 
+      opt.banner << "\n  The following options are deprecated:\n\n"
+
+      name_length = DEPRECATED.keys.sort_by { |k| k.length }.last.length
+
+      DEPRECATED.sort_by { |k,| k }.each do |name, reason|
+        opt.banner << "    %*1$2$s  %3$s\n" % [-name_length, name, reason]
+      end
+
+      opt.accept Template do |template|
+        template_dir = template_dir_for template
+
+        unless template_dir then
+          warn "could not find template #{template}"
+          nil
+        else
+          [template, template_dir]
+        end
+      end
+
       opt.separator nil
-      opt.separator "Parsing Options:"
+      opt.separator "Parsing options:"
+      opt.separator nil
+
+      if Object.const_defined? :Encoding then
+        opt.on("--encoding=ENCODING", "-e", Encoding.list.map { |e| e.name },
+               "Specifies the output encoding.  All files",
+               "read will be converted to this encoding.",
+               "Preferred over --charset") do |value|
+                 @encoding = Encoding.find value
+                 @charset = @encoding.to_s # may not be valid value
+               end
+
+        opt.separator nil
+      end
+
+      opt.on("--all", "-a",
+             "Synonym for --visibility=private.") do |value|
+        @visibility = :private
+      end
+
       opt.separator nil
 
       opt.on("--exclude=PATTERN", "-x", Regexp,
@@ -193,20 +372,41 @@ Usage: #{opt.program_name} [options] [names...]
       end
 
       opt.separator nil
-      opt.separator "Generator Options:"
+
+      opt.on("--tab-width=WIDTH", "-w", OptionParser::DecimalInteger,
+             "Set the width of tab characters.") do |value|
+        @tab_width = value
+      end
+
       opt.separator nil
 
-      opt.on("--charset=CHARSET", "-c",
-             "Specifies the output HTML character-set.") do |value|
-        @charset = value
+      opt.on("--visibility=VISIBILITY", "-V", RDoc::VISIBILITIES,
+             "Minimum visibility to document a method.",
+             "One of 'public', 'protected' (the default)",
+             "or 'private'. Can be abbreviated.") do |value|
+        @visibility = value
+      end
+
+      opt.separator nil
+      opt.separator "Common generator options:"
+      opt.separator nil
+
+      opt.on("--force-output", "-O",
+             "Forces rdoc to write the output files,",
+             "even if the output directory exists",
+             "and does not seem to have been created",
+             "by rdoc.") do |value|
+        @force_output = value
       end
 
       opt.separator nil
 
       generator_text = @generators.keys.map { |name| "  #{name}" }.sort
 
-      opt.on("--fmt=FORMAT", "--format=FORMAT", "-f", @generators.keys,
+      opt.on("-f", "--fmt=FORMAT", "--format=FORMAT", @generators.keys,
              "Set the output formatter.  One of:", *generator_text) do |value|
+        check_generator
+
         @generator_name = value.downcase
         setup_generator
       end
@@ -222,9 +422,11 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
-      opt.on("--main=NAME", "-m",
-             "NAME will be the initial page displayed.") do |value|
-        @main_page = value
+      opt.on("--[no-]coverage-report", "--[no-]dcov", "-C",
+             "Prints a report on undocumented items.",
+             "Does not generate files.") do |value|
+        @coverage_report = value
+        @force_update = true if value
       end
 
       opt.separator nil
@@ -236,6 +438,51 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
+      opt.on("-d",
+             "Deprecated --diagram option.",
+             "Prevents firing debug mode",
+             "with legacy invocation.") do |value|
+      end
+
+      opt.separator nil
+      opt.separator 'HTML generator options:'
+      opt.separator nil
+
+      opt.on("--charset=CHARSET", "-c",
+             "Specifies the output HTML character-set.",
+             "Use --encoding instead of --charset if",
+             "available.") do |value|
+        @charset = value
+      end
+
+      opt.separator nil
+
+      opt.on("--hyperlink-all", "-A",
+             "Generate hyperlinks for all words that",
+             "correspond to known methods, even if they",
+             "do not start with '#' or '::' (legacy",
+             "behavior).") do |value|
+        @hyperlink_all = value
+      end
+
+      opt.separator nil
+
+      opt.on("--main=NAME", "-m",
+             "NAME will be the initial page displayed.") do |value|
+        @main_page = value
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]line-numbers", "-N",
+             "Include line numbers in the source code.",
+             "By default, only the number of the first",
+             "line is displayed, in a leading comment.") do |value|
+        @line_numbers = value
+      end
+
+      opt.separator nil
+
       opt.on("--show-hash", "-H",
              "A name of the form #name in a comment is a",
              "possible hyperlink to an instance method",
@@ -246,17 +493,12 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
-      opt.on("--tab-width=WIDTH", "-w", OptionParser::DecimalInteger,
-             "Set the width of tab characters.") do |value|
-        @tab_width = value
-      end
-
-      opt.separator nil
-
-      opt.on("--template=NAME", "-T",
+      opt.on("--template=NAME", "-T", Template,
              "Set the template used when generating",
-             "output.") do |value|
-        @template = value
+             "output. The default depends on the",
+             "formatter used.") do |(template, template_dir)|
+        @template     = template
+        @template_dir = template_dir
       end
 
       opt.separator nil
@@ -278,11 +520,7 @@ Usage: #{opt.program_name} [options] [names...]
       end
 
       opt.separator nil
-
-      opt.on("-d", "--diagram", "Prevents -d from tripping --debug")
-
-      opt.separator nil
-      opt.separator "ri Generator Options:"
+      opt.separator "ri generator options:"
       opt.separator nil
 
       opt.on("--ri", "-r",
@@ -291,6 +529,8 @@ Usage: #{opt.program_name} [options] [names...]
              "your home directory unless overridden by a",
              "subsequent --op parameter, so no special",
              "privileges are needed.") do |value|
+        check_generator
+
         @generator_name = "ri"
         @op_dir ||= RDoc::RI::Paths::HOMEDIR
         setup_generator
@@ -303,22 +543,30 @@ Usage: #{opt.program_name} [options] [names...]
              "are stored in a site-wide directory,",
              "making them accessible to others, so",
              "special privileges are needed.") do |value|
+        check_generator
+
         @generator_name = "ri"
         @op_dir = RDoc::RI::Paths::SITEDIR
         setup_generator
       end
 
       opt.separator nil
-      opt.separator "Generic Options:"
+      opt.separator "Generic options:"
       opt.separator nil
 
+      opt.on("--[no-]dry-run",
+             "Don't write any files") do |value|
+        @dry_run = value
+      end
+
       opt.on("-D", "--[no-]debug",
              "Displays lots on internal stuff.") do |value|
         $DEBUG_RDOC = value
       end
 
       opt.on("--[no-]ignore-invalid",
-             "Ignore invalid options and continue.") do |value|
+             "Ignore invalid options and continue",
+             "(default true).") do |value|
         ignore_invalid = value
       end
 
@@ -328,38 +576,70 @@ Usage: #{opt.program_name} [options] [names...]
       end
 
       opt.on("--verbose", "-v",
-             "Display extra progress as we parse.") do |value|
+             "Display extra progress as RDoc parses") do |value|
         @verbosity = 2
       end
 
+      opt.on("--help",
+             "Display this help") do
+        RDoc::RDoc::GENERATORS.each_key do |generator|
+          setup_generator generator
+        end
+
+        puts opt.help
+        exit
+      end
+
       opt.separator nil
     end
 
-    argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT']
-    ignored = []
+    setup_generator 'darkfish' if
+      argv.grep(/\A(-f|--fmt|--format|-r|-R|--ri|--ri-site)\b/).empty?
+
+    deprecated = []
+    invalid = []
 
     begin
       opts.parse! argv
     rescue OptionParser::InvalidArgument, OptionParser::InvalidOption => e
-      if ignore_invalid then
-        ignored << e.args.join(' ')
-        retry
+      if DEPRECATED[e.args.first] then
+        deprecated << e.args.first
+      elsif %w[--format --ri -r --ri-site -R].include? e.args.first then
+        raise
       else
-        $stderr.puts opts
-        $stderr.puts
-        $stderr.puts e
-        exit 1
+        invalid << e.args.join(' ')
       end
+
+      retry
+    end
+
+    unless @generator then
+      @generator = RDoc::Generator::Darkfish
+      @generator_name = 'darkfish'
     end
 
     if @pipe and not argv.empty? then
       @pipe = false
-      ignored << '-p (with files)'
+      invalid << '-p (with files)'
     end
 
-    unless ignored.empty? or quiet then
-      $stderr.puts "invalid options: #{ignored.join ', '}"
-      $stderr.puts '(invalid options are ignored)'
+    unless quiet then
+      deprecated.each do |opt|
+        $stderr.puts 'option ' << opt << ' is deprecated: ' << DEPRECATED[opt]
+      end
+
+      unless invalid.empty? then
+        invalid = "invalid options: #{invalid.join ', '}"
+
+        if ignore_invalid then
+          $stderr.puts invalid
+          $stderr.puts '(invalid options are ignored)'
+        else
+          $stderr.puts opts
+          $stderr.puts invalid
+          exit 1
+        end
+      end
     end
 
     @op_dir ||= 'doc'
@@ -378,15 +658,10 @@ Usage: #{opt.program_name} [options] [names...]
     # If no template was specified, use the default template for the output
     # formatter
 
-    @template ||= @generator_name
-  end
-
-  ##
-  # Set the title, but only if not already set. This means that a title set
-  # from the command line trumps one set in a source file
-
-  def title=(string)
-    @title ||= string
+    unless @template then
+      @template     = @generator_name
+      @template_dir = template_dir_for @template
+    end
   end
 
   ##
@@ -396,30 +671,46 @@ Usage: #{opt.program_name} [options] [names...]
     @verbosity.zero?
   end
 
-  def quiet=(bool)
+  ##
+  # Set quietness to +bool+
+
+  def quiet= bool
     @verbosity = bool ? 0 : 1
   end
 
-  private
-
   ##
-  # Set up an output generator for the format in @generator_name
+  # Set up an output generator for the named +generator_name+.
+  #
+  # If the found generator responds to :setup_options it will be called with
+  # the options instance.  This allows generators to add custom options or set
+  # default options.
 
-  def setup_generator
-    @generator = @generators[@generator_name]
+  def setup_generator generator_name = @generator_name
+    @generator = @generators[generator_name]
 
     unless @generator then
-      raise OptionParser::InvalidArgument, "Invalid output formatter"
+      raise OptionParser::InvalidArgument,
+            "Invalid output formatter #{generator_name}"
     end
+
+    return if @generator_options.include? @generator
+
+    @generator_name = generator_name
+    @generator_options << @generator
+
+    @generator.setup_options self if @generator.respond_to? :setup_options
   end
 
   ##
-  # Check that the files on the command line exist
+  # Finds the template dir for +template+
 
-  def check_files
-    @files.each do |f|
-      stat = File.stat f rescue next
-      raise RDoc::Error, "file '#{f}' not readable" unless stat.readable?
+  def template_dir_for template
+    template_path = File.join 'rdoc', 'generator', 'template', template
+
+    $LOAD_PATH.map do |path|
+      File.join File.expand_path(path), template_path
+    end.find do |dir|
+      File.directory? dir
     end
   end