rdoc 2.0.0 → 2.1.0

data/lib/rdoc/generator/html/one_page_html.rb

@@ -17,7 +17,7 @@ module RDoc::Generator::HTML::ONE_PAGE_HTML
 <% unless requires["aref"] then %>
 <li><%= requires["name"] %></li>
 <% end %>
-<% end # files["requires"] %>
+<% end %><%# files["requires"] %>
 </ul>
 <% end %>
 
@@ -31,7 +31,7 @@ module RDoc::Generator::HTML::ONE_PAGE_HTML
 <% unless includes["aref"] then %>
 <li><%= includes["name"] %></li>
 <% end %>
-<% end # classes["includes"] %>
+<% end %><%# classes["includes"] %>
 </ul>
 <% end %>
 
@@ -42,7 +42,7 @@ module RDoc::Generator::HTML::ONE_PAGE_HTML
 <table>
 <% sections["attributes"].each do |attributes| %>
 <tr><td><%= attributes["name"] %></td><td><%= attributes["rw"] %></td><td><%= attributes["a_desc"] %></td></tr>
-<% end # sections["attributes"] %>
+<% end %><%# sections["attributes"] %>
 </table>
 <% end %>
 
@@ -68,11 +68,11 @@ module RDoc::Generator::HTML::ONE_PAGE_HTML
 <%= methods["sourcecode"] %>
 </pre></blockquote>
 <% end %>
-<% end # method_list["methods"] %>
+<% end %><%# method_list["methods"] %>
 <% end %>
-<% end # sections["method_list"] %>
+<% end %><%# sections["method_list"] %>
 <% end %>
-<% end # classes["sections"] %>
+<% end %><%# classes["sections"] %>
 <% end %>
   EOF
 
@@ -91,7 +91,7 @@ module RDoc::Generator::HTML::ONE_PAGE_HTML
   <tr><td>Modified:</td><td><%= files["dtm_modified"] %></td></tr>
 </table>
 } + CONTENTS_XML + %{
-<% end # values["files"] %>
+<% end %><%# values["files"] %>
 
 <% if values["classes"] then %>
 <h2>Classes</h2>
@@ -107,11 +107,11 @@ module RDoc::Generator::HTML::ONE_PAGE_HTML
 (in files
 <% classes["infiles"].each do |infiles| %>
 <%= href infiles["full_path_url"], infiles["full_path"] %>
-<% end # classes["infiles"] %>
+<% end %><%# classes["infiles"] %>
 )
 <% end %>
 } + CONTENTS_XML + %{
-<% end # values["classes"] %>
+<% end %><%# values["classes"] %>
 <% end %>
 </body>
 </html>

data/lib/rdoc/generator/ri.rb

@@ -16,12 +16,8 @@ class RDoc::Generator::RI
     new(options)
   end
 
-  class << self
-    protected :new
-  end
-
   ##
-  # Set up a new RDoc::Generator::RI.
+  # Set up a new ri generator
 
   def initialize(options) #:not-new:
     @options   = options
@@ -45,18 +41,19 @@ class RDoc::Generator::RI
   def process_class(from_class)
     generate_class_info(from_class)
 
-    # now recure into this classes constituent classess
+    # now recurse into this class' constituent classes
     from_class.each_classmodule do |mod|
       process_class(mod)
     end
   end
 
   def generate_class_info(cls)
-    if cls === RDoc::NormalModule
+    case cls
+    when RDoc::NormalModule then
       cls_desc = RDoc::RI::ModuleDescription.new
     else
       cls_desc = RDoc::RI::ClassDescription.new
-      cls_desc.superclass  = cls.superclass
+      cls_desc.superclass = cls.superclass
     end
 
     cls_desc.name        = cls.name

data/lib/rdoc/generator/texinfo.rb

@@ -0,0 +1,84 @@
+require 'rdoc/rdoc'
+require 'rdoc/generator'
+require 'rdoc/markup/to_texinfo'
+
+module RDoc
+  RDoc::GENERATORS['texinfo'] = RDoc::Generator.new("rdoc/generator/texinfo",
+                                                    :Texinfo,
+                                                    'texinfo')
+  module Generator
+    # This generates Texinfo files for viewing with GNU Info or Emacs
+    # from RDoc extracted from Ruby source files.
+    class Texinfo
+      # What should the .info file be named by default?
+      DEFAULT_INFO_FILENAME = 'rdoc.info'
+
+      include Generator::MarkUp
+
+      # Accept some options
+      def initialize(options)
+        @options = options
+        @options.inline_source = true
+        @options.op_name ||= 'rdoc.texinfo'
+        @options.formatter = ::RDoc::Markup::ToTexInfo.new
+      end
+
+      # Generate the +texinfo+ files
+      def generate(toplevels)
+        @toplevels = toplevels
+        @files, @classes = ::RDoc::Generator::Context.build_indicies(@toplevels,
+                                                                     @options)
+
+        (@files + @classes).each { |x| x.value_hash }
+
+        open(@options.op_name, 'w') do |f|
+          f.puts TexinfoTemplate.new('files' => @files,
+                                     'classes' => @classes,
+                                     'filename' => @options.op_name.gsub(/texinfo/, 'info'),
+                                     'title' => @options.title).render
+        end
+        # TODO: create info files and install?
+      end
+
+      class << self
+        # Factory? We don't need no stinkin' factory!
+        alias_method :for, :new
+      end
+    end
+
+    # Basically just a wrapper around ERB.
+    # Should probably use RDoc::TemplatePage instead
+    class TexinfoTemplate
+      BASE_DIR = ::File.expand_path(::File.dirname(__FILE__)) # have to calculate this when the file's loaded.
+
+      def initialize(values, file = 'texinfo.erb')
+        @v, @file = [values, file]
+      end
+     
+      def template
+        ::File.read(::File.join(BASE_DIR, 'texinfo', @file))
+      end
+
+      # Go!
+      def render
+        ERB.new(template).result binding
+      end
+
+      def href(location, text)
+        text # TODO: how does texinfo do hyperlinks?
+      end
+
+      def target(name, text)
+        text # TODO: how do hyperlink targets work?
+      end
+
+      # TODO: this is probably implemented elsewhere?
+      def method_prefix(section)
+        { 'Class' => '.',
+          'Module' => '::',
+          'Instance' => '#',
+        }[section['category']]
+      end
+    end
+  end
+end

data/lib/rdoc/generator/texinfo/class.texinfo.erb

@@ -0,0 +1,44 @@
+@node <%= @v['class']['full_name'].gsub(/::/, '-') %>
+@chapter <%= @v['class']["classmod"] %> <%= @v['class']['full_name'] %>
+
+<% if @v['class']["parent"] and @v['class']['par_url'] %>
+Inherits <%= href @v['class']["par_url"], @v['class']["parent"] %><% end %>
+
+<%= @v['class']["description"] %>
+
+<% if @v['class']["includes"] %>
+Includes
+<%   @v['class']["includes"].each do |include| %>
+* <%=  href include["aref"], include["name"] %>
+<%   end # @v['class']["includes"] %>
+<% end %>
+
+<% if @v['class']["sections"] %>
+<%   @v['class']["sections"].each do |section| %>
+<%     if section["attributes"] %>
+Attributes
+<%       section["attributes"].each do |attributes| %>
+* <%=      attributes["name"] %> <%= attributes["rw"] %> <%= attributes["a_desc"] %>
+<%       end # section["attributes"] %>
+<%     end %>
+<%   end %>
+
+<%   @v['class']["sections"].each do |section| %>
+<%     if section["method_list"] %>
+Methods
+@menu
+<%     section["method_list"].each_with_index do |method_list, i| %>
+<%= i %>
+<%       (method_list["methods"] || []).each do |method| %>
+* <%= @v['class']['full_name'].gsub(/::/, '-') %><%= method_prefix method_list %><%= method['name'] %>::<% end %>
+<% end %>
+@end menu
+
+<%     section["method_list"].each do |method_list| %>
+<%       (method_list["methods"] || []).uniq.each do |method| %>
+<%=        TexinfoTemplate.new(@v.merge({'method' => method, 'list' => method_list}),
+                               'method.texinfo.erb').render %><% end %>
+<%     end # section["method_list"] %>
+<%   end %>
+<% end # @v['class']["sections"] %>
+<% end %>

data/lib/rdoc/generator/texinfo/file.texinfo.erb

@@ -0,0 +1,6 @@
+<% if false %>
+<h2>File: <%= @v['file']["short_name"] %></h2>
+Path: <%= @v['file']["full_path"] %>
+
+<%= TexinfoTemplate.new(@v, 'content.texinfo.erb').render %>
+<% end %>

data/lib/rdoc/generator/texinfo/method.texinfo.erb

@@ -0,0 +1,6 @@
+@node <%= @v['class']['full_name'].gsub(/::/, '-') %><%= method_prefix @v['list'] %><%= @v['method']['name'] %>
+@section <%= @v['class']["classmod"] %> <%= @v['class']['full_name'] %><%= method_prefix @v['list'] %><%= @v['method']['name'] %>
+<%= @v['method']["type"] %> <%= @v['method']["category"] %> method:
+<%= target @v['method']["aref"], @v['method']['callseq'] ||
+                                 @v['method']["name"] + @v['method']["params"] %>
+<%= @v['method']["m_desc"] %>

data/lib/rdoc/generator/texinfo/texinfo.erb

@@ -0,0 +1,28 @@
+\input texinfo   @c -*-texinfo-*-
+@c %**start of header
+@setfilename <%= @v['filename'] %>
+@settitle <%= @v['title'] %>
+@c %**end of header
+
+@contents @c TODO: whitespace is a mess... =\
+
+@ifnottex
+@node Top
+
+@top <%= @v['title'] %>
+@end ifnottex
+
+<% if @f = @v['files'].detect { |f| f.name =~ /Readme/i }  %>
+<%= @f.values['description'] %><% end %>
+
+@menu
+<% @v['classes'].each do |klass| %>
+* <%= klass.name.gsub(/::/, '-') %>::<% end %>
+@c TODO: add files
+@end menu
+
+<% (@v['classes'] || []).each_with_index do |klass, i| %>
+<%= TexinfoTemplate.new(@v.merge('class' => klass.values), 
+                        'class.texinfo.erb').render %><% end %>
+
+@bye

data/lib/rdoc/known_classes.rb

@@ -0,0 +1,69 @@
+module RDoc
+
+  ##
+  # Ruby's built-in classes, modules and exceptions
+
+  KNOWN_CLASSES = {
+    "rb_cArray"            => "Array",
+    "rb_cBignum"           => "Bignum",
+    "rb_cClass"            => "Class",
+    "rb_cData"             => "Data",
+    "rb_cDir"              => "Dir",
+    "rb_cFalseClass"       => "FalseClass",
+    "rb_cFile"             => "File",
+    "rb_cFixnum"           => "Fixnum",
+    "rb_cFloat"            => "Float",
+    "rb_cHash"             => "Hash",
+    "rb_cIO"               => "IO",
+    "rb_cInteger"          => "Integer",
+    "rb_cModule"           => "Module",
+    "rb_cNilClass"         => "NilClass",
+    "rb_cNumeric"          => "Numeric",
+    "rb_cObject"           => "Object",
+    "rb_cProc"             => "Proc",
+    "rb_cRange"            => "Range",
+    "rb_cRegexp"           => "Regexp",
+    "rb_cRubyVM"           => "RubyVM",
+    "rb_cString"           => "String",
+    "rb_cStruct"           => "Struct",
+    "rb_cSymbol"           => "Symbol",
+    "rb_cThread"           => "Thread",
+    "rb_cTime"             => "Time",
+    "rb_cTrueClass"        => "TrueClass",
+
+    "rb_eArgError"         => "ArgError",
+    "rb_eEOFError"         => "EOFError",
+    "rb_eException"        => "Exception",
+    "rb_eFatal"            => "Fatal",
+    "rb_eFloatDomainError" => "FloatDomainError",
+    "rb_eIOError"          => "IOError",
+    "rb_eIndexError"       => "IndexError",
+    "rb_eInterrupt"        => "Interrupt",
+    "rb_eLoadError"        => "LoadError",
+    "rb_eNameError"        => "NameError",
+    "rb_eNoMemError"       => "NoMemError",
+    "rb_eNotImpError"      => "NotImpError",
+    "rb_eRangeError"       => "RangeError",
+    "rb_eRuntimeError"     => "RuntimeError",
+    "rb_eScriptError"      => "ScriptError",
+    "rb_eSecurityError"    => "SecurityError",
+    "rb_eSignal"           => "Signal",
+    "rb_eStandardError"    => "StandardError",
+    "rb_eSyntaxError"      => "SyntaxError",
+    "rb_eSystemCallError"  => "SystemCallError",
+    "rb_eSystemExit"       => "SystemExit",
+    "rb_eTypeError"        => "TypeError",
+    "rb_eZeroDivError"     => "ZeroDivError",
+
+    "rb_mComparable"       => "Comparable",
+    "rb_mEnumerable"       => "Enumerable",
+    "rb_mErrno"            => "Errno",
+    "rb_mFileTest"         => "FileTest",
+    "rb_mGC"               => "GC",
+    "rb_mKernel"           => "Kernel",
+    "rb_mMath"             => "Math",
+    "rb_mPrecision"        => "Precision",
+    "rb_mProcess"          => "Process"
+  }
+
+end

data/lib/rdoc/markup.rb

@@ -17,7 +17,7 @@ require 'rdoc'
 # RDoc::Markup is intended to be the basis for a family of tools which share
 # the common requirement that simple, plain-text should be rendered in a
 # variety of different output formats and media.  It is envisaged that
-# RDoc::Markup could be the basis for formating RDoc style comment blocks,
+# RDoc::Markup could be the basis for formatting RDoc style comment blocks,
 # Wiki entries, and online FAQs.
 #
 # = Basic Formatting
@@ -129,7 +129,7 @@ require 'rdoc'
 #
 # You can extend the RDoc::Markup parser to recognise new markup
 # sequences, and to add special processing for text that matches a
-# regular epxression.  Here we make WikiWords significant to the parser,
+# regular expression.  Here we make WikiWords significant to the parser,
 # and also make the sequences {word} and \<no>text...</no> signify
 # strike-through text.  When then subclass the HTML output class to deal
 # with these:
@@ -197,7 +197,7 @@ class RDoc::Markup
 
   ##
   # Add to the sequences used to add formatting to an individual word (such
-  # as *bold*).  Matching entries will generate attibutes that the output
+  # as *bold*).  Matching entries will generate attributes that the output
   # formatters can recognize by their +name+.
 
   def add_word_pair(start, stop, name)

data/lib/rdoc/markup/attribute_manager.rb

@@ -144,8 +144,6 @@ class RDoc::Markup::AttributeManager
     add_html("b",  :BOLD)
     add_html("tt",   :TT)
     add_html("code", :TT)
-
-    add_special(/<!--(.*?)-->/, :COMMENT)
   end
 
   def add_word_pair(start, stop, name)
@@ -176,21 +174,16 @@ class RDoc::Markup::AttributeManager
   def flow(str)
     @str = str
 
-    puts("Before flow, str='#{@str.dump}'") if $DEBUG_RDOC
     mask_protected_sequences
 
     @attrs = RDoc::Markup::AttrSpan.new @str.length
 
-    puts("After protecting, str='#{@str.dump}'") if $DEBUG_RDOC
-
     convert_attrs(@str, @attrs)
     convert_html(@str, @attrs)
     convert_specials(str, @attrs)
 
     unmask_protected_sequences
 
-    puts("After flow, str='#{@str.dump}'") if $DEBUG_RDOC
-
     return split_into_flow
   end
 
@@ -217,8 +210,6 @@ class RDoc::Markup::AttributeManager
   end
 
   def split_into_flow
-    display_attributes if $DEBUG_RDOC
-
     res = []
     current_attr = 0
     str = ""

data/lib/rdoc/markup/fragments.rb

@@ -11,7 +11,7 @@ class RDoc::Markup
     attr_reader   :level, :param, :txt
     attr_accessor :type
 
-    ######
+    ##
     # This is a simple factory system that lets us associate fragement
     # types (a string) with a subclass of fragment
 

data/lib/rdoc/markup/preprocess.rb

@@ -14,21 +14,25 @@ class RDoc::Markup::PreProcess
 
   ##
   # Look for common options in a chunk of text. Options that we don't handle
-  # are passed back to our caller as |directive, param|
+  # are yielded to the caller.
 
   def handle(text)
-    text.gsub!(/^([ \t#]*):(\w+):\s*(.+)?\n/) do
+    text.gsub!(/^([ \t]*#?[ \t]*):(\w+):([ \t]*)(.+)?\n/) do
+      next $& if $3.empty? and $4 and $4[0, 1] == ':'
+
       prefix    = $1
       directive = $2.downcase
-      param     = $3
+      param     = $4
 
       case directive
-      when "include"
+      when 'include' then
         filename = param.split[0]
-        include_file(filename, prefix)
+        include_file filename, prefix
 
       else
-        yield(directive, param)
+        result = yield directive, param
+        result = "#{prefix}:#{directive}: #{param}\n" unless result
+        result
       end
     end
   end