rdoc 7.2.0 → 8.1.0

data/lib/rdoc/options.rb

@@ -2,735 +2,731 @@
 require 'optparse'
 require 'pathname'
 
-##
-# RDoc::Options handles the parsing and storage of options
-#
-# == Saved Options
-#
-# You can save some options like the markup format in the
-# <tt>.rdoc_options</tt> file in your gem.  The easiest way to do this is:
-#
-#   rdoc --markup tomdoc --write-options
-#
-# Which will automatically create the file and fill it with the options you
-# specified.
-#
-# The following options will not be saved since they interfere with the user's
-# preferences or with the normal operation of RDoc:
-#
-# * +--coverage-report+
-# * +--dry-run+
-# * +--encoding+
-# * +--force-update+
-# * +--format+
-# * +--pipe+
-# * +--quiet+
-# * +--template+
-# * +--verbose+
-#
-# == Custom Options
-#
-# Generators can hook into RDoc::Options to add generator-specific command
-# line options.
-#
-# When <tt>--format</tt> is encountered in ARGV, RDoc calls ::setup_options on
-# the generator class to add extra options to the option parser.  Options for
-# custom generators must occur after <tt>--format</tt>.  <tt>rdoc --help</tt>
-# will list options for all installed generators.
-#
-# Example:
-#
-#   class RDoc::Generator::Spellcheck
-#     RDoc::RDoc.add_generator self
-#
-#     def self.setup_options rdoc_options
-#       op = rdoc_options.option_parser
-#
-#       op.on('--spell-dictionary DICTIONARY',
-#             RDoc::Options::Path) do |dictionary|
-#         rdoc_options.spell_dictionary = dictionary
-#       end
-#     end
-#   end
-#
-# Of course, RDoc::Options does not respond to +spell_dictionary+ by default
-# so you will need to add it:
-#
-#   class RDoc::Options
-#
-#     ##
-#     # The spell dictionary used by the spell-checking plugin.
-#
-#     attr_accessor :spell_dictionary
-#
-#   end
-#
-# == Option Validators
-#
-# OptionParser validators will validate and cast user input values.  In
-# addition to the validators that ship with OptionParser (String, Integer,
-# Float, TrueClass, FalseClass, Array, Regexp, Date, Time, URI, etc.),
-# RDoc::Options adds Path, PathArray and Template.
-
-class RDoc::Options
-
+module RDoc
   ##
-  # 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',
-  }
+  # RDoc::Options handles the parsing and storage of options
+  #
+  # == Saved Options
+  #
+  # You can save some options like the markup format in the
+  # <tt>.rdoc_options</tt> file in your gem.  The easiest way to do this is:
+  #
+  #   rdoc --markup tomdoc --write-options
+  #
+  # Which will automatically create the file and fill it with the options you
+  # specified.
+  #
+  # The following options will not be saved since they interfere with the user's
+  # preferences or with the normal operation of RDoc:
+  #
+  # * +--coverage-report+
+  # * +--dry-run+
+  # * +--encoding+
+  # * +--force-update+
+  # * +--format+
+  # * +--pipe+
+  # * +--quiet+
+  # * +--template+
+  # * +--verbose+
+  #
+  # == Custom Options
+  #
+  # Generators can hook into RDoc::Options to add generator-specific command
+  # line options.
+  #
+  # When <tt>--format</tt> is encountered in ARGV, RDoc calls ::setup_options on
+  # the generator class to add extra options to the option parser.  Options for
+  # custom generators must occur after <tt>--format</tt>.  <tt>rdoc --help</tt>
+  # will list options for all installed generators.
+  #
+  # Example:
+  #
+  #   class RDoc::Generator::Spellcheck
+  #     RDoc::RDoc.add_generator self
+  #
+  #     def self.setup_options rdoc_options
+  #       op = rdoc_options.option_parser
+  #
+  #       op.on('--spell-dictionary DICTIONARY',
+  #             RDoc::Options::Path) do |dictionary|
+  #         rdoc_options.spell_dictionary = dictionary
+  #       end
+  #     end
+  #   end
+  #
+  # Of course, RDoc::Options does not respond to +spell_dictionary+ by default
+  # so you will need to add it:
+  #
+  #   class RDoc::Options
+  #
+  #     ##
+  #     # The spell dictionary used by the spell-checking plugin.
+  #
+  #     attr_accessor :spell_dictionary
+  #
+  #   end
+  #
+  # == Option Validators
+  #
+  # OptionParser validators will validate and cast user input values.  In
+  # addition to the validators that ship with OptionParser (String, Integer,
+  # Float, TrueClass, FalseClass, Array, Regexp, Date, Time, URI, etc.),
+  # RDoc::Options adds Path, PathArray and Template.
+
+  class Options
+
+    ##
+    # RDoc options ignored (or handled specially) by --write-options
+
+    SPECIAL = %w[
+      coverage_report
+      dry_run
+      encoding
+      files
+      force_output
+      force_update
+      generator
+      generator_name
+      generator_options
+      generators
+      locale
+      op_dir
+      page_dir
+      option_parser
+      pipe
+      rdoc_include
+      root
+      server_port
+      static_path
+      template
+      template_dir
+      update_output_dir
+      verbosity
+      write_options
+    ]
 
-  ##
-  # RDoc options ignored (or handled specially) by --write-options
-
-  SPECIAL = %w[
-    coverage_report
-    dry_run
-    encoding
-    files
-    force_output
-    force_update
-    generator
-    generator_name
-    generator_options
-    generators
-    locale
-    op_dir
-    page_dir
-    option_parser
-    pipe
-    rdoc_include
-    root
-    static_path
-    stylesheet_url
-    template
-    template_dir
-    update_output_dir
-    verbosity
-    write_options
-  ]
+    ##
+    # Option validator for OptionParser that matches a directory that exists on
+    # the filesystem.
 
-  ##
-  # Option validator for OptionParser that matches a directory that exists on
-  # the filesystem.
+    Directory = Object.new
 
-  Directory = Object.new
+    ##
+    # Option validator for OptionParser that matches a file or directory that
+    # exists on the filesystem.
 
-  ##
-  # Option validator for OptionParser that matches a file or directory that
-  # exists on the filesystem.
+    Path = Object.new
 
-  Path = Object.new
+    ##
+    # Option validator for OptionParser that matches a comma-separated list of
+    # files or directories that exist on the filesystem.
 
-  ##
-  # Option validator for OptionParser that matches a comma-separated list of
-  # files or directories that exist on the filesystem.
+    PathArray = Object.new
 
-  PathArray = Object.new
+    ##
+    # Option validator for OptionParser that matches a template directory for an
+    # installed generator that lives in
+    # <tt>"rdoc/generator/template/#{template_name}"</tt>
 
-  ##
-  # Option validator for OptionParser that matches a template directory for an
-  # installed generator that lives in
-  # <tt>"rdoc/generator/template/#{template_name}"</tt>
+    Template = Object.new
 
-  Template = Object.new
+    ##
+    # Character-set for HTML output.  #encoding is preferred over #charset
 
-  ##
-  # Character-set for HTML output.  #encoding is preferred over #charset
+    attr_accessor :charset
 
-  attr_accessor :charset
+    ##
+    # If true, RDoc will not write any files.
 
-  ##
-  # If true, RDoc will not write any files.
+    attr_accessor :dry_run
 
-  attr_accessor :dry_run
+    ##
+    # The output encoding.  All input files will be transcoded to this encoding.
+    #
+    # The default encoding is UTF-8.  This is set via --encoding.
 
-  ##
-  # The output encoding.  All input files will be transcoded to this encoding.
-  #
-  # The default encoding is UTF-8.  This is set via --encoding.
+    attr_accessor :encoding
 
-  attr_accessor :encoding
+    ##
+    # Files matching this pattern will be excluded
 
-  ##
-  # Files matching this pattern will be excluded
+    attr_writer :exclude
 
-  attr_writer :exclude
+    ##
+    # The list of files to be processed
 
-  ##
-  # The list of files to be processed
+    attr_accessor :files
 
-  attr_accessor :files
+    ##
+    # Create the output even if the output directory does not look
+    # like an rdoc output directory
 
-  ##
-  # Create the output even if the output directory does not look
-  # like an rdoc output directory
+    attr_accessor :force_output
 
-  attr_accessor :force_output
+    ##
+    # Scan newer sources than the flag file if true.
 
-  ##
-  # Scan newer sources than the flag file if true.
+    attr_accessor :force_update
 
-  attr_accessor :force_update
+    ##
+    # Formatter to mark up text with
 
-  ##
-  # Formatter to mark up text with
+    attr_accessor :formatter
 
-  attr_accessor :formatter
+    ##
+    # Description of the output generator (set with the <tt>--format</tt> option)
 
-  ##
-  # Description of the output generator (set with the <tt>--format</tt> option)
+    attr_accessor :generator
 
-  attr_accessor :generator
+    ##
+    # For #==
 
-  ##
-  # For #==
+    attr_reader :generator_name # :nodoc:
 
-  attr_reader :generator_name # :nodoc:
+    ##
+    # Loaded generator options.  Used to prevent --help from loading the same
+    # options multiple times.
 
-  ##
-  # Loaded generator options.  Used to prevent --help from loading the same
-  # options multiple times.
+    attr_accessor :generator_options
 
-  attr_accessor :generator_options
+    ##
+    # Old rdoc behavior: hyperlink all words that match a method name,
+    # even if not preceded by '#' or '::'
 
-  ##
-  # Old rdoc behavior: hyperlink all words that match a method name,
-  # even if not preceded by '#' or '::'
+    attr_accessor :hyperlink_all
 
-  attr_accessor :hyperlink_all
+    ##
+    # Include line numbers in the source code
 
-  ##
-  # Include line numbers in the source code
+    attr_accessor :line_numbers
 
-  attr_accessor :line_numbers
+    ##
+    # The output locale.
 
-  ##
-  # The output locale.
+    attr_accessor :locale
 
-  attr_accessor :locale
+    ##
+    # The directory where locale data live.
 
-  ##
-  # The directory where locale data live.
+    attr_accessor :locale_dir
 
-  attr_accessor :locale_dir
+    ##
+    # Name of the file, class or module to display in the initial index page (if
+    # not specified the first file we encounter is used)
 
-  ##
-  # Name of the file, class or module to display in the initial index page (if
-  # not specified the first file we encounter is used)
+    attr_accessor :main_page
 
-  attr_accessor :main_page
+    ##
+    # The markup format.
+    # One of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+.
+    # See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats].
+    attr_accessor :markup
 
-  ##
-  # The markup format.
-  # One of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+.
-  # See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats].
-  attr_accessor :markup
+    ##
+    # If true, only report on undocumented files
 
-  ##
-  # If true, only report on undocumented files
+    attr_accessor :coverage_report
 
-  attr_accessor :coverage_report
+    ##
+    # The name of the output directory
 
-  ##
-  # The name of the output directory
+    attr_accessor :op_dir
 
-  attr_accessor :op_dir
+    ##
+    # The OptionParser for this instance
 
-  ##
-  # The OptionParser for this instance
+    attr_accessor :option_parser
 
-  attr_accessor :option_parser
+    ##
+    # Output heading decorations?
+    attr_accessor :output_decoration
 
-  ##
-  # Output heading decorations?
-  attr_accessor :output_decoration
+    ##
+    # Directory where guides, FAQ, and other pages not associated with a class
+    # live.  You may leave this unset if these are at the root of your project.
 
-  ##
-  # Directory where guides, FAQ, and other pages not associated with a class
-  # live.  You may leave this unset if these are at the root of your project.
+    attr_accessor :page_dir
 
-  attr_accessor :page_dir
+    ##
+    # Is RDoc in pipe mode?
 
-  ##
-  # Is RDoc in pipe mode?
+    attr_accessor :pipe
 
-  attr_accessor :pipe
+    ##
+    # Array of directories to search for files to satisfy an :include:
 
-  ##
-  # Array of directories to search for files to satisfy an :include:
+    attr_accessor :rdoc_include
 
-  attr_accessor :rdoc_include
+    ##
+    # Root of the source documentation will be generated for.  Set this when
+    # building documentation outside the source directory.  Defaults to the
+    # current directory.
 
-  ##
-  # Root of the source documentation will be generated for.  Set this when
-  # building documentation outside the source directory.  Defaults to the
-  # current directory.
+    attr_accessor :root
 
-  attr_accessor :root
+    ##
+    # Include the '#' at the front of hyperlinked instance method names
 
-  ##
-  # Include the '#' at the front of hyperlinked instance method names
+    attr_accessor :show_hash
 
-  attr_accessor :show_hash
+    ##
+    # Directory to copy static files from
 
-  ##
-  # Directory to copy static files from
+    attr_accessor :static_path
 
-  attr_accessor :static_path
+    ##
+    # The number of columns in a tab
 
-  ##
-  # The number of columns in a tab
+    attr_accessor :tab_width
 
-  attr_accessor :tab_width
+    ##
+    # Template to be used when generating output
 
-  ##
-  # Template to be used when generating output
+    attr_accessor :template
 
-  attr_accessor :template
+    ##
+    # Directory the template lives in
 
-  ##
-  # Directory the template lives in
+    attr_accessor :template_dir
 
-  attr_accessor :template_dir
+    ##
+    # Additional template stylesheets
 
-  ##
-  # Additional template stylesheets
+    attr_accessor :template_stylesheets
 
-  attr_accessor :template_stylesheets
+    ##
+    # Documentation title
 
-  ##
-  # Documentation title
+    attr_accessor :title
 
-  attr_accessor :title
+    ##
+    # Should RDoc update the timestamps in the output dir?
 
-  ##
-  # Should RDoc update the timestamps in the output dir?
+    attr_accessor :update_output_dir
 
-  attr_accessor :update_output_dir
+    ##
+    # Verbosity, zero means quiet
 
-  ##
-  # Verbosity, zero means quiet
+    attr_accessor :verbosity
 
-  attr_accessor :verbosity
+    ##
+    # Warn if rdoc-ref links can't be resolved
+    # Default is +true+
 
-  ##
-  # Warn if rdoc-ref links can't be resolved
-  # Default is +true+
+    attr_accessor :warn_missing_rdoc_ref
 
-  attr_accessor :warn_missing_rdoc_ref
+    ##
+    # URL of web cvs frontend
 
-  ##
-  # URL of web cvs frontend
+    attr_accessor :webcvs
 
-  attr_accessor :webcvs
+    ##
+    # Minimum visibility of a documented method. One of +:public+, +:protected+,
+    # +:private+ or +:nodoc+.
+    #
+    # The +:nodoc+ visibility ignores all directives related to visibility.  The
+    # other visibilities may be overridden on a per-method basis with the :doc:
+    # directive.
 
-  ##
-  # Minimum visibility of a documented method. One of +:public+, +:protected+,
-  # +:private+ or +:nodoc+.
-  #
-  # The +:nodoc+ visibility ignores all directives related to visibility.  The
-  # other visibilities may be overridden on a per-method basis with the :doc:
-  # directive.
+    attr_reader :visibility
 
-  attr_reader :visibility
+    ##
+    # When set to a port number, starts a live-reloading server instead of
+    # writing files.  Defaults to +false+ (no server).  Set via
+    # <tt>--server[=PORT]</tt>.
 
-  ##
-  # Indicates if files of test suites should be skipped
-  attr_accessor :skip_tests
+    attr_reader :server_port
 
-  ##
-  # Embed mixin methods, attributes, and constants into class documentation. Set via
-  # +--[no-]embed-mixins+ (Default is +false+.)
-  attr_accessor :embed_mixins
+    ##
+    # Indicates if files of test suites should be skipped
+    attr_accessor :skip_tests
 
-  ##
-  # Exclude the default patterns as well if true.
-  attr_reader :apply_default_exclude
+    ##
+    # Embed mixin methods, attributes, and constants into class documentation. Set via
+    # +--[no-]embed-mixins+ (Default is +false+.)
+    attr_accessor :embed_mixins
 
-  ##
-  # Words to be ignored in autolink cross-references
-  attr_accessor :autolink_excluded_words
+    ##
+    # Exclude the default patterns as well if true.
+    attr_reader :apply_default_exclude
 
-  ##
-  # The prefix to use for class and module page paths
+    ##
+    # Words to be ignored in autolink cross-references
+    attr_accessor :autolink_excluded_words
 
-  attr_accessor :class_module_path_prefix
+    ##
+    # The prefix to use for class and module page paths
 
-  ##
-  # The prefix to use for file page paths
+    attr_accessor :class_module_path_prefix
 
-  attr_accessor :file_path_prefix
+    ##
+    # The prefix to use for file page paths
 
-  ##
-  # The preferred root URL for the documentation
+    attr_accessor :file_path_prefix
 
-  attr_accessor :canonical_root
+    ##
+    # The preferred root URL for the documentation
 
-  ##
-  # Custom footer content configuration for themes that support it.
-  # Currently only supported by the Aliki theme.
-  #
-  # A hash where keys are column titles and values are hashes of link text => URL pairs.
-  # Each column will be displayed in the upper footer section.
-  #
-  # Example:
-  #   {
-  #     "DOCUMENTATION" => {"Home" => "/index.html", "Guide" => "/guide.html"},
-  #     "RESOURCES" => {"RDoc" => "https://ruby.github.io/rdoc/", "GitHub" => "https://github.com/ruby/rdoc"}
-  #   }
+    attr_accessor :canonical_root
 
-  attr_accessor :footer_content
+    ##
+    # Custom footer content configuration for themes that support it.
+    # Currently only supported by the Aliki theme.
+    #
+    # A hash where keys are column titles and values are hashes of link text => URL pairs.
+    # Each column will be displayed in the upper footer section.
+    #
+    # Example:
+    #   {
+    #     "DOCUMENTATION" => {"Home" => "/index.html", "Guide" => "/guide.html"},
+    #     "RESOURCES" => {"RDoc" => "https://ruby.github.io/rdoc/", "GitHub" => "https://github.com/ruby/rdoc"}
+    #   }
 
-  def initialize(loaded_options = nil) # :nodoc:
-    init_ivars
-    override loaded_options if loaded_options
-  end
+    attr_accessor :footer_content
 
-  DEFAULT_EXCLUDE = %w[
-    ~\z \.orig\z \.rej\z \.bak\z
-    \.gemspec\z
-  ]
-
-  def init_ivars # :nodoc:
-    @autolink_excluded_words = []
-    @dry_run = false
-    @embed_mixins = false
-    @exclude = []
-    @files = nil
-    @force_output = false
-    @force_update = true
-    @generator_name = "aliki"
-    @generators = RDoc::RDoc::GENERATORS
-    @generator_options = []
-    @hyperlink_all = false
-    @line_numbers = false
-    @locale = nil
-    @locale_name = nil
-    @locale_dir = 'locale'
-    @main_page = nil
-    @markup = 'rdoc'
-    @coverage_report = false
-    @op_dir = nil
-    @page_dir = nil
-    @pipe = false
-    @output_decoration = true
-    @rdoc_include = []
-    @root = Pathname(Dir.pwd)
-    @show_hash = false
-    @static_path = []
-    @stylesheet_url = nil # TODO remove in RDoc 4
-    @tab_width = 8
-    @template = nil
-    @template_dir = nil
-    @template_stylesheets = []
-    @title = nil
-    @update_output_dir = true
-    @verbosity = 1
-    @visibility = :protected
-    @warn_missing_rdoc_ref = true
-    @webcvs = nil
-    @write_options = false
-    @encoding = Encoding::UTF_8
-    @charset = @encoding.name
-    @skip_tests = true
-    @apply_default_exclude = true
-    @class_module_path_prefix = nil
-    @file_path_prefix = nil
-    @canonical_root = nil
-    @footer_content = nil
-  end
+    def initialize(loaded_options = nil) # :nodoc:
+      init_ivars
+      override loaded_options if loaded_options
+    end
 
-  def init_with(map) # :nodoc:
-    init_ivars
-
-    encoding = map['encoding']
-    @encoding = encoding ? Encoding.find(encoding) : encoding
-
-    @charset        = map['charset']
-    @embed_mixins   = map['embed_mixins']
-    @exclude        = map['exclude']
-    @generator_name = map['generator_name']
-    @hyperlink_all  = map['hyperlink_all']
-    @line_numbers   = map['line_numbers']
-    @locale_name    = map['locale_name']
-    @locale_dir     = map['locale_dir']
-    @main_page      = map['main_page']
-    @markup         = map['markup']
-    @op_dir         = map['op_dir']
-    @show_hash      = map['show_hash']
-    @tab_width      = map['tab_width']
-    @template_dir   = map['template_dir']
-    @title          = map['title']
-    @visibility     = map['visibility']
-    @webcvs         = map['webcvs']
-
-    @apply_default_exclude   = map['apply_default_exclude']
-    @autolink_excluded_words = map['autolink_excluded_words']
-    @footer_content          = map['footer_content']
-
-    @rdoc_include = sanitize_path map['rdoc_include']
-    @static_path  = sanitize_path map['static_path']
-  end
+    DEFAULT_EXCLUDE = %w[
+      ~\z \.orig\z \.rej\z \.bak\z
+      \.gemspec\z
+    ]
+
+    def init_ivars # :nodoc:
+      @autolink_excluded_words = []
+      @dry_run = false
+      @embed_mixins = false
+      @exclude = []
+      @files = nil
+      @force_output = false
+      @force_update = true
+      @generator_name = "aliki"
+      @generators = RDoc::GENERATORS
+      @generator_options = []
+      @hyperlink_all = false
+      @line_numbers = false
+      @locale = nil
+      @locale_name = nil
+      @locale_dir = 'locale'
+      @main_page = nil
+      @markup = 'rdoc'
+      @coverage_report = false
+      @op_dir = nil
+      @page_dir = nil
+      @pipe = false
+      @output_decoration = true
+      @rdoc_include = []
+      @root = Pathname(Dir.pwd)
+      @server_port = false
+      @show_hash = false
+      @static_path = []
+      @tab_width = 8
+      @template = nil
+      @template_dir = nil
+      @template_stylesheets = []
+      @title = nil
+      @update_output_dir = true
+      @verbosity = 1
+      @visibility = :protected
+      @warn_missing_rdoc_ref = true
+      @webcvs = nil
+      @write_options = false
+      @encoding = ::Encoding::UTF_8
+      @charset = @encoding.name
+      @skip_tests = true
+      @apply_default_exclude = true
+      @class_module_path_prefix = nil
+      @file_path_prefix = nil
+      @canonical_root = nil
+      @footer_content = nil
+    end
 
-  def yaml_initialize(tag, map) # :nodoc:
-    init_with map
-  end
+    def init_with(map) # :nodoc:
+      init_ivars
 
-  def override(map) # :nodoc:
-    if map.has_key?('encoding')
       encoding = map['encoding']
-      @encoding = encoding ? Encoding.find(encoding) : encoding
-    end
+      @encoding = encoding ? ::Encoding.find(encoding) : encoding
+
+      @charset        = map['charset']
+      @embed_mixins   = map['embed_mixins']
+      @exclude        = map['exclude']
+      @generator_name = map['generator_name']
+      @hyperlink_all  = map['hyperlink_all']
+      @line_numbers   = map['line_numbers']
+      @locale_name    = map['locale_name']
+      @locale_dir     = map['locale_dir']
+      @main_page      = map['main_page']
+      @markup         = map['markup']
+      @op_dir         = map['op_dir']
+      @show_hash      = map['show_hash']
+      @tab_width      = map['tab_width']
+      @template_dir   = map['template_dir']
+      @title          = map['title']
+      @visibility     = map['visibility']
+      @webcvs         = map['webcvs']
+
+      @apply_default_exclude   = map['apply_default_exclude']
+      @autolink_excluded_words = map['autolink_excluded_words']
+      @footer_content          = map['footer_content']
 
-    @charset        = map['charset']        if map.has_key?('charset')
-    @embed_mixins   = map['embed_mixins']   if map.has_key?('embed_mixins')
-    @exclude        = map['exclude']        if map.has_key?('exclude')
-    @generator_name = map['generator_name'] if map.has_key?('generator_name')
-    @hyperlink_all  = map['hyperlink_all']  if map.has_key?('hyperlink_all')
-    @line_numbers   = map['line_numbers']   if map.has_key?('line_numbers')
-    @locale_name    = map['locale_name']    if map.has_key?('locale_name')
-    @locale_dir     = map['locale_dir']     if map.has_key?('locale_dir')
-    @main_page      = map['main_page']      if map.has_key?('main_page')
-    @markup         = map['markup']         if map.has_key?('markup')
-    @op_dir         = map['op_dir']         if map.has_key?('op_dir')
-    @page_dir       = map['page_dir']       if map.has_key?('page_dir')
-    @show_hash      = map['show_hash']      if map.has_key?('show_hash')
-    @tab_width      = map['tab_width']      if map.has_key?('tab_width')
-    @template_dir   = map['template_dir']   if map.has_key?('template_dir')
-    @title          = map['title']          if map.has_key?('title')
-    @visibility     = map['visibility']     if map.has_key?('visibility')
-    @webcvs         = map['webcvs']         if map.has_key?('webcvs')
-    @autolink_excluded_words = map['autolink_excluded_words'] if map.has_key?('autolink_excluded_words')
-    @apply_default_exclude = map['apply_default_exclude'] if map.has_key?('apply_default_exclude')
-    @canonical_root = map['canonical_root'] if map.has_key?('canonical_root')
-    @footer_content = map['footer_content'] if map.has_key?('footer_content')
-
-    @warn_missing_rdoc_ref = map['warn_missing_rdoc_ref'] if map.has_key?('warn_missing_rdoc_ref')
-
-    if map.has_key?('rdoc_include')
       @rdoc_include = sanitize_path map['rdoc_include']
-    end
-    if map.has_key?('static_path')
       @static_path  = sanitize_path map['static_path']
     end
-  end
 
-  def ==(other) # :nodoc:
-    self.class === other and
-      @encoding       == other.encoding       and
-      @embed_mixins   == other.embed_mixins   and
-      @generator_name == other.generator_name and
-      @hyperlink_all  == other.hyperlink_all  and
-      @line_numbers   == other.line_numbers   and
-      @locale         == other.locale         and
-      @locale_dir     == other.locale_dir     and
-      @main_page      == other.main_page      and
-      @markup         == other.markup         and
-      @op_dir         == other.op_dir         and
-      @rdoc_include   == other.rdoc_include   and
-      @show_hash      == other.show_hash      and
-      @static_path    == other.static_path    and
-      @tab_width      == other.tab_width      and
-      @template       == other.template       and
-      @title          == other.title          and
-      @visibility     == other.visibility     and
-      @webcvs         == other.webcvs         and
-      @apply_default_exclude == other.apply_default_exclude and
-      @autolink_excluded_words == other.autolink_excluded_words
-  end
+    def yaml_initialize(tag, map) # :nodoc:
+      init_with map
+    end
 
-  ##
-  # Check that the files on the command line exist
+    def override(map) # :nodoc:
+      if map.has_key?('encoding')
+        encoding = map['encoding']
+        @encoding = encoding ? ::Encoding.find(encoding) : encoding
+      end
+
+      @charset        = map['charset']        if map.has_key?('charset')
+      @embed_mixins   = map['embed_mixins']   if map.has_key?('embed_mixins')
+      @exclude        = map['exclude']        if map.has_key?('exclude')
+      @generator_name = map['generator_name'] if map.has_key?('generator_name')
+      @hyperlink_all  = map['hyperlink_all']  if map.has_key?('hyperlink_all')
+      @line_numbers   = map['line_numbers']   if map.has_key?('line_numbers')
+      @locale_name    = map['locale_name']    if map.has_key?('locale_name')
+      @locale_dir     = map['locale_dir']     if map.has_key?('locale_dir')
+      @main_page      = map['main_page']      if map.has_key?('main_page')
+      @markup         = map['markup']         if map.has_key?('markup')
+      @op_dir         = map['op_dir']         if map.has_key?('op_dir')
+      @page_dir       = map['page_dir']       if map.has_key?('page_dir')
+      @show_hash      = map['show_hash']      if map.has_key?('show_hash')
+      @tab_width      = map['tab_width']      if map.has_key?('tab_width')
+      @template_dir   = map['template_dir']   if map.has_key?('template_dir')
+      @title          = map['title']          if map.has_key?('title')
+      @visibility     = map['visibility']     if map.has_key?('visibility')
+      @webcvs         = map['webcvs']         if map.has_key?('webcvs')
+      @autolink_excluded_words = map['autolink_excluded_words'] if map.has_key?('autolink_excluded_words')
+      @apply_default_exclude = map['apply_default_exclude'] if map.has_key?('apply_default_exclude')
+      @canonical_root = map['canonical_root'] if map.has_key?('canonical_root')
+      @footer_content = map['footer_content'] if map.has_key?('footer_content')
+
+      @warn_missing_rdoc_ref = map['warn_missing_rdoc_ref'] if map.has_key?('warn_missing_rdoc_ref')
+
+      if map.has_key?('rdoc_include')
+        @rdoc_include = sanitize_path map['rdoc_include']
+      end
+      if map.has_key?('static_path')
+        @static_path  = sanitize_path map['static_path']
+      end
+    end
 
-  def check_files
-    @files.delete_if do |file|
-      if File.exist? file then
-        if File.readable? file then
-          false
+    def ==(other) # :nodoc:
+      self.class === other and
+        @encoding       == other.encoding       and
+        @embed_mixins   == other.embed_mixins   and
+        @generator_name == other.generator_name and
+        @hyperlink_all  == other.hyperlink_all  and
+        @line_numbers   == other.line_numbers   and
+        @locale         == other.locale         and
+        @locale_dir     == other.locale_dir     and
+        @main_page      == other.main_page      and
+        @markup         == other.markup         and
+        @op_dir         == other.op_dir         and
+        @rdoc_include   == other.rdoc_include   and
+        @show_hash      == other.show_hash      and
+        @static_path    == other.static_path    and
+        @tab_width      == other.tab_width      and
+        @template       == other.template       and
+        @title          == other.title          and
+        @visibility     == other.visibility     and
+        @webcvs         == other.webcvs         and
+        @apply_default_exclude == other.apply_default_exclude and
+        @autolink_excluded_words == other.autolink_excluded_words
+    end
+
+    ##
+    # Check that the files on the command line exist
+
+    def check_files
+      @files.delete_if do |file|
+        if File.exist? file
+          if File.readable? file
+            false
+          else
+            warn "file '#{file}' not readable"
+
+            true
+          end
         else
-          warn "file '#{file}' not readable"
+          warn "file '#{file}' not found"
 
           true
         end
-      else
-        warn "file '#{file}' not found"
-
-        true
       end
     end
-  end
 
-  ##
-  # Ensure only one generator is loaded
+    ##
+    # Ensure only one generator is loaded
 
-  def check_generator
-    if @generator then
-      raise OptionParser::InvalidOption,
-        "generator already set to #{@generator_name}"
+    def check_generator
+      if @generator
+        raise OptionParser::InvalidOption,
+          "generator already set to #{@generator_name}"
+      end
     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.
+    ##
+    # 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
+    def default_title=(string)
+      @title ||= string
+    end
 
-  ##
-  # For dumping YAML
+    ##
+    # For dumping YAML
 
-  def to_yaml(*options) # :nodoc:
-    encoding = @encoding ? @encoding.name : nil
+    def to_yaml(*options) # :nodoc:
+      encoding = @encoding ? @encoding.name : nil
 
-    yaml = {}
-    yaml['encoding'] = encoding
-    yaml['static_path'] = sanitize_path(@static_path)
-    yaml['rdoc_include'] = sanitize_path(@rdoc_include)
-    yaml['page_dir'] = (sanitize_path([@page_dir]).first if @page_dir)
+      yaml = {}
+      yaml['encoding'] = encoding
+      yaml['static_path'] = sanitize_path(@static_path)
+      yaml['rdoc_include'] = sanitize_path(@rdoc_include)
+      yaml['page_dir'] = (sanitize_path([@page_dir]).first if @page_dir)
 
-    ivars = instance_variables.map { |ivar| ivar.to_s[1..-1] }
-    ivars -= SPECIAL
+      ivars = instance_variables.map { |ivar| ivar.to_s[1..-1] }
+      ivars -= SPECIAL
 
-    ivars.sort.each do |ivar|
-      yaml[ivar] = instance_variable_get("@#{ivar}")
-    end
-    yaml.to_yaml
-  end
+      ivars.sort.each do |ivar|
+        yaml[ivar] = instance_variable_get("@#{ivar}")
+      end
 
-  ##
-  # Create a regexp for #exclude
-
-  def exclude
-    if @exclude.nil? or Regexp === @exclude then
-      # done, #finish is being re-run
-      @exclude
-    elsif !@apply_default_exclude and @exclude.empty? then
-      nil
-    else
-      exclude = @exclude
-      exclude |= DEFAULT_EXCLUDE if @apply_default_exclude
-      Regexp.new(exclude.join("|"))
+      if yaml.respond_to?(:to_yaml)
+        yaml.to_yaml
+      else
+        ::RDoc.yaml_serializer.dump(yaml)
+      end
     end
-  end
 
-  ##
-  # Completes any unfinished option setup business such as filtering for
-  # existent files, creating a regexp for #exclude and setting a default
-  # #template.
+    ##
+    # Create a regexp for #exclude
 
-  def finish
-    if @write_options then
-      write_options
-      exit
+    def exclude
+      if @exclude.nil? or Regexp === @exclude
+        # done, #finish is being re-run
+        @exclude
+      elsif !@apply_default_exclude and @exclude.empty?
+        nil
+      else
+        exclude = @exclude
+        exclude |= DEFAULT_EXCLUDE if @apply_default_exclude
+        Regexp.new(exclude.join("|"))
+      end
     end
 
-    @op_dir ||= 'doc'
+    ##
+    # Completes any unfinished option setup business such as filtering for
+    # existent files, creating a regexp for #exclude and setting a default
+    # #template.
 
-    root = @root.to_s
-    if @rdoc_include.empty? || !@rdoc_include.include?(root)
-      @rdoc_include << root
-    end
+    def finish
+      if @write_options
+        write_options
+        exit
+      end
 
-    @exclude = self.exclude
+      @op_dir ||= 'doc'
 
-    finish_page_dir
+      root = @root.to_s
+      if @rdoc_include.empty? || !@rdoc_include.include?(root)
+        @rdoc_include << root
+      end
 
-    check_files
+      @exclude = self.exclude
 
-    # If no template was specified, use the default template for the output
-    # formatter
+      finish_page_dir
 
-    unless @template then
-      @template     = @generator_name
-      @template_dir = template_dir_for @template
-    end
+      check_files
 
-    if @locale_name
-      @locale = RDoc::I18n::Locale[@locale_name]
-      @locale.load(@locale_dir)
-    else
-      @locale = nil
-    end
+      # If no template was specified, use the default template for the output
+      # formatter
 
-    self
-  end
+      unless @template
+        @template     = @generator_name
+        @template_dir = template_dir_for @template
+      end
 
-  ##
-  # Fixes the page_dir to be relative to the root_dir and adds the page_dir to
-  # the files list.
+      if @locale_name
+        @locale = I18n::Locale[@locale_name]
+        @locale.load(@locale_dir)
+      else
+        @locale = nil
+      end
 
-  def finish_page_dir
-    return unless @page_dir
+      self
+    end
 
-    @files << @page_dir
+    ##
+    # Fixes the page_dir to be relative to the root_dir and adds the page_dir to
+    # the files list.
 
-    page_dir = Pathname(@page_dir)
-    begin
-      page_dir = page_dir.expand_path.relative_path_from @root
-    rescue ArgumentError
-      # On Windows, sometimes crosses different drive letters.
-      page_dir = page_dir.expand_path
-    end
+    def finish_page_dir
+      return unless @page_dir
 
-    @page_dir = page_dir
-  end
+      @files << @page_dir
 
-  ##
-  # Returns a properly-space list of generators and their descriptions.
+      page_dir = Pathname(@page_dir)
+      begin
+        page_dir = page_dir.expand_path.relative_path_from @root
+      rescue ArgumentError
+        # On Windows, sometimes crosses different drive letters.
+        page_dir = page_dir.expand_path
+      end
 
-  def generator_descriptions
-    lengths = []
+      @page_dir = page_dir
+    end
 
-    generators = RDoc::RDoc::GENERATORS.map do |name, generator|
-      lengths << name.length
+    ##
+    # Returns a properly-space list of generators and their descriptions.
 
-      description = generator::DESCRIPTION if
-        generator.const_defined? :DESCRIPTION
+    def generator_descriptions
+      lengths = []
 
-      [name, description]
-    end
+      generators = RDoc::GENERATORS.map do |name, generator|
+        lengths << name.length
 
-    longest = lengths.max
+        description = generator::DESCRIPTION if
+          generator.const_defined? :DESCRIPTION
 
-    generators.sort.map do |name, description|
-      if description then
-        "  %-*s - %s" % [longest, name, description]
-      else
-        "  #{name}"
+        [name, description]
       end
-    end.join "\n"
-  end
 
-  ##
-  # Parses command line options.
+      longest = lengths.max
+
+      generators.sort.map do |name, description|
+        if description
+          "  %-*s - %s" % [longest, name, description]
+        else
+          "  #{name}"
+        end
+      end.join "\n"
+    end
+
+    ##
+    # Parses command line options.
 
-  def parse(argv)
-    ignore_invalid = true
+    def parse(argv)
+      ignore_invalid = true
 
-    argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT']
+      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
-      opt.summary_indent = ' ' * 4
-      opt.banner = <<-EOF
+      opts = OptionParser.new do |opt|
+        @option_parser = opt
+        opt.program_name = File.basename $0
+        opt.version = VERSION
+        opt.release = nil
+        opt.summary_indent = ' ' * 4
+        opt.banner = <<-EOF
 Usage: #{opt.program_name} [options] [names...]
 
   Files are parsed, and the information they contain collected, before any
@@ -758,670 +754,661 @@ Usage: #{opt.program_name} [options] [names...]
 
       EOF
 
-      parsers = Hash.new { |h, parser| h[parser] = [] }
+        parsers = Hash.new { |h, parser| h[parser] = [] }
 
-      RDoc::Parser.parsers.each do |regexp, parser|
-        parsers[parser.name.sub('RDoc::Parser::', '')] << regexp.source
-      end
+        Parser.parsers.each do |regexp, parser|
+          parsers[parser.name.sub('RDoc::Parser::', '')] << regexp.source
+        end
 
-      parsers.sort.each do |parser, regexp|
-        opt.banner += "  - #{parser}: #{regexp.join ', '}\n"
-      end
-      opt.banner += "  - TomDoc:  Only in ruby files\n"
+        parsers.sort.each do |parser, regexp|
+          opt.banner += "  - #{parser}: #{regexp.join ', '}\n"
+        end
+        opt.banner += "  - TomDoc:  Only in ruby files\n"
 
-      opt.banner += "\n  The following options are deprecated:\n\n"
+        opt.accept Template do |template|
+          template_dir = template_dir_for template
 
-      name_length = DEPRECATED.keys.sort_by { |k| k.length }.last.length
+          unless template_dir
+            $stderr.puts "could not find template #{template}"
+            nil
+          else
+            [template, template_dir]
+          end
+        end
 
-      DEPRECATED.sort_by { |k,| k }.each do |name, reason|
-        opt.banner += "    %*1$2$s  %3$s\n" % [-name_length, name, reason]
-      end
+        opt.accept Directory do |directory|
+          directory = File.expand_path directory
 
-      opt.accept Template do |template|
-        template_dir = template_dir_for template
+          raise OptionParser::InvalidArgument unless File.directory? directory
 
-        unless template_dir then
-          $stderr.puts "could not find template #{template}"
-          nil
-        else
-          [template, template_dir]
+          directory
         end
-      end
 
-      opt.accept Directory do |directory|
-        directory = File.expand_path directory
+        opt.accept Path do |path|
+          path = File.expand_path path
 
-        raise OptionParser::InvalidArgument unless File.directory? directory
+          raise OptionParser::InvalidArgument unless File.exist? path
 
-        directory
-      end
+          path
+        end
 
-      opt.accept Path do |path|
-        path = File.expand_path path
+        opt.accept PathArray do |paths,|
+          paths = if paths
+                    paths.split(',').map { |d| d unless d.empty? }
+                  end
 
-        raise OptionParser::InvalidArgument unless File.exist? path
+          paths.map do |path|
+            path = File.expand_path path
 
-        path
-      end
+            raise OptionParser::InvalidArgument unless File.exist? path
 
-      opt.accept PathArray do |paths,|
-        paths = if paths then
-                  paths.split(',').map { |d| d unless d.empty? }
-                end
+            path
+          end
+        end
 
-        paths.map do |path|
-          path = File.expand_path path
+        opt.separator nil
+        opt.separator "Parsing options:"
+        opt.separator nil
 
-          raise OptionParser::InvalidArgument unless File.exist? path
+        opt.on("--encoding=ENCODING", "-e", ::Encoding.list.map { |e| e.name },
+               "Specifies the output encoding.  All files",
+               "read will be converted to this encoding.",
+               "The default encoding is UTF-8.",
+               "--encoding is preferred over --charset") do |value|
+                 @encoding = ::Encoding.find value
+                 @charset = @encoding.name # may not be valid value
+               end
 
-          path
+        opt.separator nil
+
+        opt.on("--locale=NAME",
+               "Specifies the output locale.") do |value|
+          @locale_name = value
         end
-      end
 
-      opt.separator nil
-      opt.separator "Parsing options:"
-      opt.separator nil
+        opt.on("--locale-data-dir=DIR",
+               "Specifies the directory where locale data live.") do |value|
+          @locale_dir = value
+        end
 
-      opt.on("--encoding=ENCODING", "-e", Encoding.list.map { |e| e.name },
-             "Specifies the output encoding.  All files",
-             "read will be converted to this encoding.",
-             "The default encoding is UTF-8.",
-             "--encoding is preferred over --charset") do |value|
-               @encoding = Encoding.find value
-               @charset = @encoding.name # may not be valid value
-             end
+        opt.separator nil
 
-      opt.separator nil
+        opt.on("--all", "-a",
+               "Synonym for --visibility=private.") do |value|
+          @visibility = :private
+        end
 
-      opt.on("--locale=NAME",
-             "Specifies the output locale.") do |value|
-        @locale_name = value
-      end
+        opt.separator nil
 
-      opt.on("--locale-data-dir=DIR",
-             "Specifies the directory where locale data live.") do |value|
-        @locale_dir = value
-      end
+        opt.on("--exclude=PATTERN", "-x", Regexp,
+               "Do not process files or directories",
+               "matching PATTERN.") do |value|
+          @exclude << value
+        end
 
-      opt.separator nil
+        opt.on("--[no-]apply-default-exclude",
+               "Use default PATTERN to exclude.") do |value|
+          @apply_default_exclude = value
+        end
 
-      opt.on("--all", "-a",
-             "Synonym for --visibility=private.") do |value|
-        @visibility = :private
-      end
+        opt.separator nil
 
-      opt.separator nil
+        opt.on("--no-skipping-tests", nil,
+               "Don't skip generating documentation for test and spec files") do |value|
+          @skip_tests = false
+        end
 
-      opt.on("--exclude=PATTERN", "-x", Regexp,
-             "Do not process files or directories",
-             "matching PATTERN.") do |value|
-        @exclude << value
-      end
+        opt.separator nil
 
-      opt.on("--[no-]apply-default-exclude",
-             "Use default PATTERN to exclude.") do |value|
-        @apply_default_exclude = value
-      end
+        opt.on("--extension=NEW=OLD", "-E",
+               "Treat files ending with .new as if they",
+               "ended with .old. Using '-E cgi=rb' will",
+               "cause xxx.cgi to be parsed as a Ruby file.") do |value|
+          new, old = value.split(/=/, 2)
 
-      opt.separator nil
+          unless new and old
+            raise OptionParser::InvalidArgument, "Invalid parameter to '-E'"
+          end
 
-      opt.on("--no-skipping-tests", nil,
-             "Don't skip generating documentation for test and spec files") do |value|
-        @skip_tests = false
-      end
-
-      opt.separator nil
+          unless Parser.alias_extension old, new
+            raise OptionParser::InvalidArgument, "Unknown extension .#{old} to -E"
+          end
+        end
 
-      opt.on("--extension=NEW=OLD", "-E",
-             "Treat files ending with .new as if they",
-             "ended with .old. Using '-E cgi=rb' will",
-             "cause xxx.cgi to be parsed as a Ruby file.") do |value|
-        new, old = value.split(/=/, 2)
+        opt.separator nil
 
-        unless new and old then
-          raise OptionParser::InvalidArgument, "Invalid parameter to '-E'"
+        opt.on("--[no-]force-update", "-U",
+               "Forces rdoc to scan all sources even if",
+               "no files are newer than the flag file.") do |value|
+          @force_update = value
         end
 
-        unless RDoc::Parser.alias_extension old, new then
-          raise OptionParser::InvalidArgument, "Unknown extension .#{old} to -E"
+        opt.separator nil
+
+        opt.on("--pipe", "-p",
+               "Convert RDoc on stdin to HTML") do
+          @pipe = true
         end
-      end
 
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("--[no-]force-update", "-U",
-             "Forces rdoc to scan all sources even if",
-             "no files are newer than the flag file.") do |value|
-        @force_update = value
-      end
+        opt.on("--tab-width=WIDTH", "-w", Integer,
+               "Set the width of tab characters.") do |value|
+          raise OptionParser::InvalidArgument,
+                "#{value} is an invalid tab width" if value <= 0
+          @tab_width = value
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("--pipe", "-p",
-             "Convert RDoc on stdin to HTML") do
-        @pipe = true
-      end
+        opt.on("--visibility=VISIBILITY", VISIBILITIES + [:nodoc],
+               "Minimum visibility to document a method.",
+               "One of 'public', 'protected' (the default),",
+               "'private' or 'nodoc' (show everything)") do |value|
+          @visibility = value
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("--tab-width=WIDTH", "-w", Integer,
-             "Set the width of tab characters.") do |value|
-        raise OptionParser::InvalidArgument,
-              "#{value} is an invalid tab width" if value <= 0
-        @tab_width = value
-      end
+        opt.on("--[no-]embed-mixins",
+               "Embed mixin methods, attributes, and constants",
+               "into class documentation. (default false)") do |value|
+          @embed_mixins = value
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("--visibility=VISIBILITY", "-V", RDoc::VISIBILITIES + [:nodoc],
-             "Minimum visibility to document a method.",
-             "One of 'public', 'protected' (the default),",
-             "'private' or 'nodoc' (show everything)") do |value|
-        @visibility = value
-      end
+        markup_formats = Text::MARKUP_FORMAT.keys.sort
 
-      opt.separator nil
+        opt.on("--markup=MARKUP", markup_formats,
+               "The markup format for the named files.",
+               "The default is rdoc.  Valid values are:",
+               markup_formats.join(', ')) do |value|
+          @markup = value
+        end
 
-      opt.on("--[no-]embed-mixins",
-             "Embed mixin methods, attributes, and constants",
-             "into class documentation. (default false)") do |value|
-        @embed_mixins = value
-      end
+        opt.separator nil
 
-      opt.separator nil
+        opt.on("--root=ROOT", Directory,
+               "Root of the source tree documentation",
+               "will be generated for.  Set this when",
+               "building documentation outside the",
+               "source directory.  Default is the",
+               "current directory.") do |root|
+          @root = Pathname(root)
+        end
 
-      markup_formats = RDoc::Text::MARKUP_FORMAT.keys.sort
+        opt.separator nil
 
-      opt.on("--markup=MARKUP", markup_formats,
-             "The markup format for the named files.",
-             "The default is rdoc.  Valid values are:",
-             markup_formats.join(', ')) do |value|
-        @markup = value
-      end
+        opt.on("--page-dir=DIR", Directory,
+               "Directory where guides, your FAQ or",
+               "other pages not associated with a class",
+               "live.  Set this when you don't store",
+               "such files at your project root.",
+               "NOTE: Do not use the same file name in",
+               "the page dir and the root of your project") do |page_dir|
+          @page_dir = page_dir
+        end
 
-      opt.separator nil
+        opt.separator nil
+        opt.separator "Common generator options:"
+        opt.separator nil
 
-      opt.on("--root=ROOT", Directory,
-             "Root of the source tree documentation",
-             "will be generated for.  Set this when",
-             "building documentation outside the",
-             "source directory.  Default is the",
-             "current directory.") do |root|
-        @root = Pathname(root)
-      end
+        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
+        opt.separator nil
 
-      opt.on("--page-dir=DIR", Directory,
-             "Directory where guides, your FAQ or",
-             "other pages not associated with a class",
-             "live.  Set this when you don't store",
-             "such files at your project root.",
-             "NOTE: Do not use the same file name in",
-             "the page dir and the root of your project") do |page_dir|
-        @page_dir = page_dir
-      end
+        generator_text = @generators.keys.map { |name| "  #{name}" }.sort
 
-      opt.separator nil
-      opt.separator "Common generator options:"
-      opt.separator nil
+        opt.on("-f", "--fmt=FORMAT", "--format=FORMAT", @generators.keys,
+               "Set the output formatter.  One of:", *generator_text) do |value|
+          check_generator
 
-      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
+          @generator_name = value.downcase
+          setup_generator
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      generator_text = @generators.keys.map { |name| "  #{name}" }.sort
+        opt.on("--include=DIRECTORIES", "-i", PathArray,
+               "Set (or add to) the list of directories to",
+               "be searched when satisfying :include:",
+               "requests. Can be used more than once.") do |value|
+          @rdoc_include.concat value.map { |dir| dir.strip }
+        end
 
-      opt.on("-f", "--fmt=FORMAT", "--format=FORMAT", @generators.keys,
-             "Set the output formatter.  One of:", *generator_text) do |value|
-        check_generator
+        opt.separator nil
 
-        @generator_name = value.downcase
-        setup_generator
-      end
+        opt.on("--[no-]coverage-report=[LEVEL]", "--[no-]dcov", "-C", Integer,
+               "Prints a report on undocumented items.",
+               "Does not generate files.") do |value|
+          value = 0 if value.nil? # Integer converts -C to nil
 
-      opt.separator nil
+          @coverage_report = value
+          @force_update = true if value
+        end
 
-      opt.on("--include=DIRECTORIES", "-i", PathArray,
-             "Set (or add to) the list of directories to",
-             "be searched when satisfying :include:",
-             "requests. Can be used more than once.") do |value|
-        @rdoc_include.concat value.map { |dir| dir.strip }
-      end
+        opt.separator nil
 
-      opt.separator nil
+        opt.on("--output=DIR", "--op", "-o",
+               "Set the output directory.") do |value|
+          @op_dir = value
+        end
 
-      opt.on("--[no-]coverage-report=[LEVEL]", "--[no-]dcov", "-C", Integer,
-             "Prints a report on undocumented items.",
-             "Does not generate files.") do |value|
-        value = 0 if value.nil? # Integer converts -C to nil
+        opt.separator nil
+        opt.separator 'HTML generator options:'
+        opt.separator nil
 
-        @coverage_report = value
-        @force_update = true if value
-      end
+        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.separator nil
 
-      opt.on("--output=DIR", "--op", "-o",
-             "Set the output directory.") do |value|
-        @op_dir = value
-      end
+        opt.on("--autolink-excluded-words=WORDS", Array,
+               "Words to be ignored in autolink cross-references") do |value|
+          @autolink_excluded_words.concat value
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("-d",
-             "Deprecated --diagram option.",
-             "Prevents firing debug mode",
-             "with legacy invocation.") do |value|
-      end
+        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.separator 'HTML generator options:'
-      opt.separator nil
+        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.on("--main=NAME", "-m",
+               "NAME will be the initial page displayed.") do |value|
+          @main_page = value
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("--autolink-excluded-words=WORDS", Array,
-             "Words to be ignored in autolink cross-references") do |value|
-        @autolink_excluded_words.concat value
-      end
+        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.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.on("--show-hash", "-H",
+               "A name of the form #name in a comment is a",
+               "possible hyperlink to an instance method",
+               "name. When displayed, the '#' is removed",
+               "unless this option is specified.") do |value|
+          @show_hash = value
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("--main=NAME", "-m",
-             "NAME will be the initial page displayed.") do |value|
-        @main_page = value
-      end
+        opt.on("--template=NAME", "-T", Template,
+               "Set the template used when generating",
+               "output. The default depends on the",
+               "formatter used.") do |(template, template_dir)|
+          @template     = template
+          @template_dir = template_dir
+        end
 
-      opt.separator nil
+        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.on("--template-stylesheets=FILES", PathArray,
+               "Set (or add to) the list of files to",
+               "include with the html template.") do |value|
+          @template_stylesheets.concat value
+        end
 
-      opt.separator nil
+        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",
-             "name. When displayed, the '#' is removed",
-             "unless this option is specified.") do |value|
-        @show_hash = value
-      end
+        opt.on("--title=TITLE", "-t",
+               "Set TITLE as the title for HTML output.") do |value|
+          @title = value
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("--template=NAME", "-T", Template,
-             "Set the template used when generating",
-             "output. The default depends on the",
-             "formatter used.") do |(template, template_dir)|
-        @template     = template
-        @template_dir = template_dir
-      end
+        opt.on("--copy-files=PATH", Path,
+               "Specify a file or directory to copy static",
+               "files from.",
+               "If a file is given it will be copied into",
+               "the output dir.  If a directory is given the",
+               "entire directory will be copied.",
+               "You can use this multiple times") do |value|
+          @static_path << value
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("--template-stylesheets=FILES", PathArray,
-             "Set (or add to) the list of files to",
-             "include with the html template.") do |value|
-        @template_stylesheets.concat value
-      end
+        opt.on("--webcvs=URL", "-W",
+               "Specify a URL for linking to a web frontend",
+               "to CVS. If the URL contains a '\%s', the",
+               "name of the current file will be",
+               "substituted; if the URL doesn't contain a",
+               "'\%s', the filename will be appended to it.") do |value|
+          @webcvs = value
+        end
 
-      opt.separator nil
+        opt.separator nil
+        opt.separator "ri generator options:"
+        opt.separator nil
+
+        opt.on("--ri", "-r",
+               "Generate output for use by `ri`. The files",
+               "are stored in the '.rdoc' directory under",
+               "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 ||= RI::Paths::HOMEDIR
+          setup_generator
+        end
 
-      opt.on("--title=TITLE", "-t",
-             "Set TITLE as the title for HTML output.") do |value|
-        @title = value
-      end
+        opt.separator nil
 
-      opt.separator nil
+        opt.on("--ri-site", "-R",
+               "Generate output for use by `ri`. The files",
+               "are stored in a site-wide directory,",
+               "making them accessible to others, so",
+               "special privileges are needed.") do |value|
+          check_generator
 
-      opt.on("--copy-files=PATH", Path,
-             "Specify a file or directory to copy static",
-             "files from.",
-             "If a file is given it will be copied into",
-             "the output dir.  If a directory is given the",
-             "entire directory will be copied.",
-             "You can use this multiple times") do |value|
-        @static_path << value
-      end
+          @generator_name = "ri"
+          @op_dir = RI::Paths.site_dir
+          setup_generator
+        end
 
-      opt.separator nil
+        opt.separator nil
+        opt.separator "Generic options:"
+        opt.separator nil
 
-      opt.on("--webcvs=URL", "-W",
-             "Specify a URL for linking to a web frontend",
-             "to CVS. If the URL contains a '\%s', the",
-             "name of the current file will be",
-             "substituted; if the URL doesn't contain a",
-             "'\%s', the filename will be appended to it.") do |value|
-        @webcvs = value
-      end
+        opt.on("--server[=PORT]", Integer,
+               "Start a web server to preview",
+               "documentation with live reload.",
+               "Defaults to port 4000.") do |port|
+          @server_port = port || 4000
+        end
 
-      opt.separator nil
-      opt.separator "ri generator options:"
-      opt.separator nil
-
-      opt.on("--ri", "-r",
-             "Generate output for use by `ri`. The files",
-             "are stored in the '.rdoc' directory under",
-             "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
-      end
+        opt.separator nil
 
-      opt.separator nil
+        opt.on("--write-options",
+               "Write .rdoc_options to the current",
+               "directory with the given options.  Not all",
+               "options will be used.  See RDoc::Options",
+               "for details.") do |value|
+          @write_options = true
+        end
 
-      opt.on("--ri-site", "-R",
-             "Generate output for use by `ri`. The files",
-             "are stored in a site-wide directory,",
-             "making them accessible to others, so",
-             "special privileges are needed.") do |value|
-        check_generator
+        opt.separator nil
 
-        @generator_name = "ri"
-        @op_dir = RDoc::RI::Paths.site_dir
-        setup_generator
-      end
+        opt.on("--[no-]dry-run",
+               "Don't write any files") do |value|
+          @dry_run = value
+        end
 
-      opt.separator nil
-      opt.separator "Generic options:"
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("--write-options",
-             "Write .rdoc_options to the current",
-             "directory with the given options.  Not all",
-             "options will be used.  See RDoc::Options",
-             "for details.") do |value|
-        @write_options = true
-      end
+        opt.on("-D", "--[no-]debug",
+               "Displays lots on internal stuff.") do |value|
+          $DEBUG_RDOC = value
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("--[no-]dry-run",
-             "Don't write any files") do |value|
-        @dry_run = value
-      end
+        opt.on("--warn-missing-rdoc-ref",
+               "Warn if rdoc-ref links can't be resolved") do |value|
+          @warn_missing_rdoc_ref = value
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      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",
+               "(default true).") do |value|
+          ignore_invalid = value
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("--warn-missing-rdoc-ref",
-             "Warn if rdoc-ref links can't be resolved") do |value|
-        @warn_missing_rdoc_ref = value
-      end
+        opt.on("--quiet", "-q",
+               "Don't show progress as we parse.") do |value|
+          @verbosity = 0
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("--[no-]ignore-invalid",
-             "Ignore invalid options and continue",
-             "(default true).") do |value|
-        ignore_invalid = value
-      end
+        opt.on("--verbose", "-V",
+               "Display extra progress as RDoc parses") do |value|
+          @verbosity = 2
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("--quiet", "-q",
-             "Don't show progress as we parse.") do |value|
-        @verbosity = 0
-      end
+        opt.on("--version", "-v", "print the version") do
+          puts opt.version
+          exit
+        end
 
-      opt.separator nil
+        opt.separator nil
 
-      opt.on("--verbose", "-V",
-             "Display extra progress as RDoc parses") do |value|
-        @verbosity = 2
-      end
+        opt.on("--help", "-h", "Display this help") do
+          RDoc::GENERATORS.each_key do |generator|
+            setup_generator generator
+          end
 
-      opt.separator nil
+          puts opt.help
+          exit
+        end
 
-      opt.on("--version", "-v", "print the version") do
-        puts opt.version
-        exit
+        opt.separator nil
       end
 
-      opt.separator nil
+      invalid = []
 
-      opt.on("--help", "-h", "Display this help") do
-        RDoc::RDoc::GENERATORS.each_key do |generator|
-          setup_generator generator
+      begin
+        opts.parse! argv
+      rescue OptionParser::ParseError => e
+        if %w[--format --ri -r --ri-site -R].include? e.args.first
+          raise
+        else
+          invalid << e.args.join(' ')
         end
 
-        puts opt.help
-        exit
+        retry
       end
 
-      opt.separator nil
-    end
+      setup_generator unless @generator
+
+      if @pipe and not argv.empty?
+        @pipe = false
+        invalid << '-p (with files)'
+      end
 
-    deprecated = []
-    invalid = []
+      unless invalid.empty?
+        invalid = "invalid options: #{invalid.join ', '}"
 
-    begin
-      opts.parse! argv
-    rescue OptionParser::ParseError => e
-      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
-        invalid << e.args.join(' ')
+        if ignore_invalid
+          unless quiet
+            $stderr.puts invalid
+            $stderr.puts '(invalid options are ignored)'
+          end
+        else
+          unless quiet
+            $stderr.puts opts
+          end
+          $stderr.puts invalid
+          exit 1
+        end
       end
 
-      retry
+      @files = argv.dup
+
+      self
     end
 
-    setup_generator unless @generator
+    ##
+    # Don't display progress as we process the files
 
-    if @pipe and not argv.empty? then
-      @pipe = false
-      invalid << '-p (with files)'
+    def quiet
+      @verbosity.zero?
     end
 
-    unless quiet then
-      deprecated.each do |opt|
-        $stderr.puts 'option ' + opt + ' is deprecated: ' + DEPRECATED[opt]
-      end
-    end
+    ##
+    # Set quietness to +bool+
 
-    unless invalid.empty? then
-      invalid = "invalid options: #{invalid.join ', '}"
+    def quiet=(bool)
+      @verbosity = bool ? 0 : 1
+    end
 
-      if ignore_invalid then
-        unless quiet then
-          $stderr.puts invalid
-          $stderr.puts '(invalid options are ignored)'
-        end
-      else
-        unless quiet then
-          $stderr.puts opts
+    ##
+    # Removes directories from +path+ that are outside the current directory
+
+    def sanitize_path(path)
+      require 'pathname'
+      dot = Pathname.new('.').expand_path
+
+      path.reject do |item|
+        path = Pathname.new(item).expand_path
+        is_reject = nil
+        relative = nil
+        begin
+          relative = path.relative_path_from(dot).to_s
+        rescue ArgumentError
+          # On Windows, sometimes crosses different drive letters.
+          is_reject = true
+        else
+          is_reject = relative.start_with? '..'
         end
-        $stderr.puts invalid
-        exit 1
+        is_reject
       end
     end
 
-    @files = argv.dup
-
-    self
-  end
-
-  ##
-  # Don't display progress as we process the files
-
-  def quiet
-    @verbosity.zero?
-  end
+    ##
+    # 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.
 
-  ##
-  # Set quietness to +bool+
+    def setup_generator(generator_name = @generator_name)
+      @generator = @generators[generator_name]
 
-  def quiet=(bool)
-    @verbosity = bool ? 0 : 1
-  end
+      unless @generator
+        raise OptionParser::InvalidArgument,
+              "Invalid output formatter #{generator_name}"
+      end
 
-  ##
-  # Removes directories from +path+ that are outside the current directory
+      return if @generator_options.include? @generator
 
-  def sanitize_path(path)
-    require 'pathname'
-    dot = Pathname.new('.').expand_path
+      @generator_name = generator_name
+      @generator_options << @generator
 
-    path.reject do |item|
-      path = Pathname.new(item).expand_path
-      is_reject = nil
-      relative = nil
-      begin
-        relative = path.relative_path_from(dot).to_s
-      rescue ArgumentError
-        # On Windows, sometimes crosses different drive letters.
-        is_reject = true
-      else
-        is_reject = relative.start_with? '..'
+      if @generator.respond_to? :setup_options
+        @option_parser ||= OptionParser.new
+        @generator.setup_options self
       end
-      is_reject
     end
-  end
 
-  ##
-  # 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.
+    ##
+    # Finds the template dir for +template+
 
-  def setup_generator(generator_name = @generator_name)
-    @generator = @generators[generator_name]
+    def template_dir_for(template)
+      template_path = File.join 'rdoc', 'generator', 'template', template
 
-    unless @generator then
-      raise OptionParser::InvalidArgument,
-            "Invalid output formatter #{generator_name}"
+      $LOAD_PATH.map do |path|
+        File.join File.expand_path(path), template_path
+      end.find do |dir|
+        File.directory? dir
+      end
     end
 
-    return if @generator_options.include? @generator
+    # Sets the minimum visibility of a documented method.
+    #
+    # Accepts +:public+, +:protected+, +:private+, +:nodoc+, or +:all+.
+    #
+    # When +:all+ is passed, visibility is set to +:private+, similarly to
+    # RDOCOPT="--all", see #visibility for more information.
 
-    @generator_name = generator_name
-    @generator_options << @generator
-
-    if @generator.respond_to? :setup_options then
-      @option_parser ||= OptionParser.new
-      @generator.setup_options self
+    def visibility=(visibility)
+      case visibility
+      when :all
+        @visibility = :private
+      else
+        @visibility = visibility
+      end
     end
-  end
-
-  ##
-  # Finds the template dir for +template+
 
-  def template_dir_for(template)
-    template_path = File.join 'rdoc', 'generator', 'template', template
+    ##
+    # Displays a warning using Kernel#warn if we're being verbose
 
-    $LOAD_PATH.map do |path|
-      File.join File.expand_path(path), template_path
-    end.find do |dir|
-      File.directory? dir
+    def warn(message)
+      super message if @verbosity > 1
     end
-  end
-
-  # Sets the minimum visibility of a documented method.
-  #
-  # Accepts +:public+, +:protected+, +:private+, +:nodoc+, or +:all+.
-  #
-  # When +:all+ is passed, visibility is set to +:private+, similarly to
-  # RDOCOPT="--all", see #visibility for more information.
-
-  def visibility=(visibility)
-    case visibility
-    when :all
-      @visibility = :private
-    else
-      @visibility = visibility
-    end
-  end
 
-  ##
-  # Displays a warning using Kernel#warn if we're being verbose
+    ##
+    # Writes the YAML file .rdoc_options to the current directory containing the
+    # parsed options.
 
-  def warn(message)
-    super message if @verbosity > 1
-  end
+    def write_options
+      ::RDoc.load_yaml
 
-  ##
-  # Writes the YAML file .rdoc_options to the current directory containing the
-  # parsed options.
+      File.open '.rdoc_options', 'w' do |io|
+        io.set_encoding ::Encoding::UTF_8
 
-  def write_options
-    RDoc.load_yaml
+        io.print to_yaml
+      end
+    end
 
-    File.open '.rdoc_options', 'w' do |io|
-      io.set_encoding Encoding::UTF_8
+    ##
+    # Loads options from .rdoc_options if the file exists, otherwise creates a
+    # new RDoc::Options instance.
 
-      io.print to_yaml
-    end
-  end
+    def self.load_options
+      options_file = File.expand_path '.rdoc_options'
+      return Options.new unless File.exist? options_file
 
-  ##
-  # Loads options from .rdoc_options if the file exists, otherwise creates a
-  # new RDoc::Options instance.
+      ::RDoc.load_yaml
 
-  def self.load_options
-    options_file = File.expand_path '.rdoc_options'
-    return RDoc::Options.new unless File.exist? options_file
+      content = File.read('.rdoc_options')
 
-    RDoc.load_yaml
+      if defined?(Psych)
+        begin
+          options = Psych.safe_load content, permitted_classes: [Options, Symbol]
+        rescue Psych::SyntaxError
+          raise Error, "#{options_file} is not a valid rdoc options file"
+        end
+      else
+        options = ::RDoc.yaml_serializer.load(content)
+      end
 
-    begin
-      options = YAML.safe_load File.read('.rdoc_options'), permitted_classes: [RDoc::Options, Symbol]
-    rescue Psych::SyntaxError
-      raise RDoc::Error, "#{options_file} is not a valid rdoc options file"
-    end
+      return Options.new unless options # Allow empty file.
 
-    return RDoc::Options.new unless options # Allow empty file.
+      raise Error, "#{options_file} is not a valid rdoc options file" unless
+        Options === options or Hash === options
 
-    raise RDoc::Error, "#{options_file} is not a valid rdoc options file" unless
-      RDoc::Options === options or Hash === options
+      if Hash === options
+        # Override the default values with the contents of YAML file.
+        options = Options.new options
+      end
 
-    if Hash === options
-      # Override the default values with the contents of YAML file.
-      options = RDoc::Options.new options
+      options
     end
 
-    options
   end
-
 end