rdoc 2.0.0 → 2.1.0

data/lib/rdoc/markup/to_html.rb

@@ -20,6 +20,11 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   def initialize
     super
 
+    # @in_tt - tt nested levels count
+    # @tt_bit - cache
+    @in_tt = 0
+    @tt_bit = RDoc::Markup::Attribute.bitmap_for :TT
+
     # external hyperlinks
     @markup.add_special(/((link:|https?:|mailto:|ftp:|www\.)\S+\w)/, :HYPERLINK)
 
@@ -29,6 +34,27 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     init_tags
   end
 
+  ##
+  # Converts a target url to one that is relative to a given path
+
+  def self.gen_relative_url(path, target)
+    from        = File.dirname path
+    to, to_file = File.split target
+
+    from = from.split "/"
+    to   = to.split "/"
+
+    while from.size > 0 and to.size > 0 and from[0] == to[0] do
+      from.shift
+      to.shift
+    end
+
+    from.fill ".."
+    from.concat to
+    from << to_file
+    File.join(*from)
+  end
+
   ##
   # Generate a hyperlink for url, labeled with text. Handle the
   # special cases for img: and link: described under handle_special_HYPEDLINK
@@ -47,7 +73,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
       url = if path[0, 1] == '#' then # is this meaningful?
               path
             else
-              HTML.gen_url @from_path, path
+              self.class.gen_relative_url @from_path, path
             end
     end
 
@@ -86,6 +112,20 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     gen_url url, label
   end
 
+  ##
+  # are we currently inside <tt> tags?
+
+  def in_tt?
+    @in_tt > 0
+  end
+
+  ##
+  # is +tag+ a <tt> tag?
+
+  def tt?(tag)
+    tag.bit == @tt_bit
+  end
+
   ##
   # Set up the standard mapping of attributes to HTML tags
 
@@ -215,6 +255,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     @attr_tags.each do |tag|
       if attr_mask & tag.bit != 0
         res << annotate(tag.on)
+        @in_tt += 1 if tt?(tag)
       end
     end
   end
@@ -225,6 +266,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
     @attr_tags.reverse_each do |tag|
       if attr_mask & tag.bit != 0
+        @in_tt -= 1 if tt?(tag)
         res << annotate(tag.off)
       end
     end
@@ -250,27 +292,33 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     res
   end
 
+  def convert_string(item)
+    in_tt? ? convert_string_simple(item) : convert_string_fancy(item)
+  end
+
+  def convert_string_simple(item)
+    CGI.escapeHTML item
+  end
+
   ##
   # some of these patterns are taken from SmartyPants...
 
-  def convert_string(item)
-    CGI.escapeHTML(item).
-
+  def convert_string_fancy(item)
     # convert -- to em-dash, (-- to en-dash)
-      gsub(/---?/, '&#8212;'). #gsub(/--/, '&#8211;').
+    item.gsub(/---?/, '&#8212;'). #gsub(/--/, '&#8211;').
 
     # convert ... to elipsis (and make sure .... becomes .<elipsis>)
       gsub(/\.\.\.\./, '.&#8230;').gsub(/\.\.\./, '&#8230;').
 
     # convert single closing quote
-      gsub(%r{([^ \t\r\n\[\{\(])\'}, '\1&#8217;').
+      gsub(%r{([^ \t\r\n\[\{\(])\'}, '\1&#8217;'). # }
       gsub(%r{\'(?=\W|s\b)}, '&#8217;').
 
     # convert single opening quote
       gsub(/'/, '&#8216;').
 
     # convert double closing quote
-      gsub(%r{([^ \t\r\n\[\{\(])\'(?=\W)}, '\1&#8221;').
+      gsub(%r{([^ \t\r\n\[\{\(])\'(?=\W)}, '\1&#8221;'). # }
 
     # convert double opening quote
       gsub(/'/, '&#8220;').
@@ -280,7 +328,6 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
     # convert and registered trademark
       gsub(/\(r\)/, '&#174;')
-
   end
 
   def convert_special(special)

data/lib/rdoc/markup/to_html_crossref.rb

@@ -14,6 +14,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # correct relative paths for any hyperlinks that we find
 
   def initialize(from_path, context, show_hash)
+    raise ArgumentError, 'from_path cannot be nil' if from_path.nil?
     super()
 
     # class names, variable names, or instance variables
@@ -47,28 +48,43 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   def handle_special_CROSSREF(special)
     name = special.text
 
+    return name if name =~ /\A[a-z]*\z/
+
     return @seen[name] if @seen.include? name
 
-    if name[0,1] == '#' then
+    if name[0, 1] == '#' then
       lookup = name[1..-1]
       name = lookup unless @show_hash
     else
       lookup = name
     end
 
+
     # Find class, module, or method in class or module.
-    if /([A-Z]\w*)[.\#](\w+[!?=]?)/ =~ lookup then
+    #
+    # Do not, however, use an if/elsif/else chain to do so.  Instead, test
+    # each possible pattern until one matches.  The reason for this is that a
+    # string like "YAML.txt" could be the txt() class method of class YAML (in
+    # which case it would match the first pattern, which splits the string
+    # into container and method components and looks up both) or a filename
+    # (in which case it would match the last pattern, which just checks
+    # whether the string as a whole is a known symbol).
+
+    if /([A-Z][\w:]*)[.\#](\w+[!?=]?)/ =~ lookup then
       container = $1
       method = $2
       ref = @context.find_symbol container, method
-    elsif /([A-Za-z]\w*)[.\#](\w+(\([\.\w+\*\/\+\-\=\<\>]+\))?)/ =~ lookup then
+    end
+
+    if !ref and
+       /([A-Za-z][\w:]*)[.\#](\w+(\([\.\w+\*\/\+\-\=\<\>]+\))?)/ =~ lookup then
       container = $1
       method = $2
       ref = @context.find_symbol container, method
-    else
-      ref = @context.find_symbol lookup
     end
 
+    ref = @context.find_symbol lookup unless ref
+
     out = if lookup =~ /^\\/ then
             $'
           elsif ref and ref.document_self then

data/lib/rdoc/markup/to_texinfo.rb

@@ -0,0 +1,69 @@
+require 'rdoc/markup/formatter'
+require 'rdoc/markup/fragments'
+require 'rdoc/markup/inline'
+
+require 'rdoc/markup'
+require 'rdoc/markup/formatter'
+
+##
+# Convert SimpleMarkup to basic TexInfo format
+#
+# TODO: WTF is AttributeManager for?
+#
+class RDoc::Markup::ToTexInfo < RDoc::Markup::Formatter
+
+  def start_accepting
+    @text = []
+  end
+
+  def end_accepting
+    @text.join("\n")
+  end
+
+  def accept_paragraph(attributes, text)
+    @text << format(text)
+  end
+
+  def accept_verbatim(attributes, text)
+    @text << "@verb{|#{format(text)}|}"
+  end
+
+  def accept_heading(attributes, text)
+    heading = ['@majorheading', '@chapheading'][text.head_level - 1] || '@heading'
+    @text << "#{heading}{#{format(text)}}"
+  end
+
+  def accept_list_start(attributes, text)
+    @text << '@itemize @bullet'
+  end
+
+  def accept_list_end(attributes, text)
+    @text << '@end itemize'
+  end
+
+  def accept_list_item(attributes, text)
+    @text << "@item\n#{format(text)}"
+  end
+
+  def accept_blank_line(attributes, text)
+    @text << "\n"
+  end
+
+  def accept_rule(attributes, text)
+    @text << '-----'
+  end
+
+  def format(text)
+    text.txt.
+      gsub(/@/, "@@").
+      gsub(/\{/, "@{").
+      gsub(/\}/, "@}").
+      # gsub(/,/, "@,"). # technically only required in cross-refs
+      gsub(/\+([\w]+)\+/, "@code{\\1}").
+      gsub(/\<tt\>([^<]+)\<\/tt\>/, "@code{\\1}").
+      gsub(/\*([\w]+)\*/, "@strong{\\1}").
+      gsub(/\<b\>([^<]+)\<\/b\>/, "@strong{\\1}").
+      gsub(/_([\w]+)_/, "@emph{\\1}").
+      gsub(/\<em\>([^<]+)\<\/em\>/, "@emph{\\1}")
+  end
+end

data/lib/rdoc/options.rb

@@ -39,7 +39,7 @@ class RDoc::Options
   ##
   # Pattern for additional attr_... style methods
 
-  attr_reader :extra_accessors
+  attr_accessor :extra_accessors
 
   ##
   # Should we draw fileboxes in diagrams
@@ -61,6 +61,11 @@ class RDoc::Options
 
   attr_accessor :generator
 
+  ##
+  # Formatter to mark up text with
+
+  attr_accessor :formatter
+  
   ##
   # image format for diagrams
 
@@ -95,18 +100,13 @@ class RDoc::Options
   ##
   # The name to use for the output
 
-  attr_reader :op_name
+  attr_accessor :op_name
 
   ##
   # Are we promiscuous about showing module contents across multiple files
 
   attr_reader :promiscuous
 
-  ##
-  # Don't display progress as we process the files
-
-  attr_reader :quiet
-
   ##
   # Array of directories to search for files to satisfy an :include:
 
@@ -144,19 +144,23 @@ class RDoc::Options
 
   attr_reader :title
 
+  ##
+  # Verbosity, zero means quiet
+
+  attr_accessor :verbosity
+
   ##
   # URL of web cvs frontend
 
   attr_reader :webcvs
 
-  def initialize(generators) # :nodoc:
+  def initialize(generators = {}) # :nodoc:
     @op_dir = "doc"
     @op_name = nil
     @show_all = false
     @main_page = nil
     @merge = false
     @exclude = []
-    @quiet = false
     @generators = generators
     @generator_name = 'html'
     @generator = @generators[@generator_name]
@@ -175,7 +179,7 @@ class RDoc::Options
     @extra_accessor_flags = {}
     @promiscuous = false
     @force_update = false
-    @title = "RDoc Documentation"
+    @verbosity = 1
 
     @css = nil
     @webcvs = nil
@@ -420,9 +424,15 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.on("--quiet", "-q",
              "Don't show progress as we parse.") do |value|
-        @quiet = value
+        @verbosity = 0
+      end
+
+      opt.on("--verbose", "-v",
+             "Display extra progress as we parse.") do |value|
+        @verbosity = 2
       end
 
+
       opt.separator nil
 
       opt.on("--ri", "-r",
@@ -513,6 +523,8 @@ Usage: #{opt.program_name} [options] [names...]
       end
     end
 
+    argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT']
+
     opts.parse! argv
 
     @files = argv.dup
@@ -553,6 +565,17 @@ Usage: #{opt.program_name} [options] [names...]
     @title ||= string
   end
 
+  ##
+  # Don't display progress as we process the files
+
+  def quiet
+    @verbosity.zero?
+  end
+
+  def quiet=(bool)
+    @verbosity = bool ? 0 : 1
+  end
+
   private
 
   ##
@@ -571,7 +594,7 @@ Usage: #{opt.program_name} [options] [names...]
     end
   end
 
-  # Check that the right version of 'dot' is available.  Unfortuately this
+  # Check that the right version of 'dot' is available.  Unfortunately this
   # doesn't work correctly under Windows NT, so we'll bypass the test under
   # Windows.
 
@@ -607,8 +630,8 @@ Usage: #{opt.program_name} [options] [names...]
 
   def check_files
     @files.each do |f|
-      stat = File.stat f rescue abort("File not found: #{f}")
-      abort("File '#{f}' not readable") unless stat.readable?
+      stat = File.stat f
+      raise RDoc::Error, "file '#{f}' not readable" unless stat.readable?
     end
   end
 

data/lib/rdoc/parser.rb

@@ -0,0 +1,109 @@
+require 'rdoc'
+require 'rdoc/code_objects'
+require 'rdoc/markup/preprocess'
+require 'rdoc/stats'
+
+##
+# A parser is simple a class that implements
+#
+#   #initialize(file_name, body, options)
+#
+# and
+#
+#   #scan
+#
+# The initialize method takes a file name to be used, the body of the file,
+# and an RDoc::Options object. The scan method is then called to return an
+# appropriately parsed TopLevel code object.
+#
+# The ParseFactory is used to redirect to the correct parser given a
+# filename extension. This magic works because individual parsers have to
+# register themselves with us as they are loaded in. The do this using the
+# following incantation
+#
+#   require "rdoc/parser"
+#   
+#   class RDoc::Parser::Xyz < RDoc::Parser
+#     parse_files_matching /\.xyz$/ # <<<<
+#   
+#     def initialize(file_name, body, options)
+#       ...
+#     end
+#   
+#     def scan
+#       ...
+#     end
+#   end
+#
+# Just to make life interesting, if we suspect a plain text file, we also
+# look for a shebang line just in case it's a potential shell script
+
+class RDoc::Parser
+
+  @parsers = []
+
+  class << self
+    attr_reader :parsers
+  end
+
+  ##
+  # Alias an extension to another extension. After this call, files ending
+  # "new_ext" will be parsed using the same parser as "old_ext"
+
+  def self.alias_extension(old_ext, new_ext)
+    old_ext = old_ext.sub(/^\.(.*)/, '\1')
+    new_ext = new_ext.sub(/^\.(.*)/, '\1')
+
+    parser = can_parse "xxx.#{old_ext}"
+    return false unless parser
+
+    RDoc::Parser.parsers.unshift [/\.#{new_ext}$/, parser]
+
+    true
+  end
+
+  ##
+  # Return a parser that can handle a particular extension
+
+  def self.can_parse(file_name)
+    RDoc::Parser.parsers.find { |regexp, parser| regexp =~ file_name }.last
+  end
+
+  ##
+  # Find the correct parser for a particular file name. Return a SimpleParser
+  # for ones that we don't know
+
+  def self.for(top_level, file_name, body, options, stats)
+    # If no extension, look for shebang
+    if file_name !~ /\.\w+$/ && body =~ %r{\A#!(.+)} then
+      shebang = $1
+      case shebang
+      when %r{env\s+ruby}, %r{/ruby}
+        file_name = "dummy.rb"
+      end
+    end
+
+    parser = can_parse file_name
+
+    parser.new top_level, file_name, body, options, stats
+  end
+
+  ##
+  # Record which file types this parser can understand.
+
+  def self.parse_files_matching(regexp)
+    RDoc::Parser.parsers.unshift [regexp, self]
+  end
+
+  def initialize(top_level, file_name, content, options, stats)
+    @top_level = top_level
+    @file_name = file_name
+    @content = content
+    @options = options
+    @stats = stats
+  end
+
+end
+
+require 'rdoc/parser/simple'
+