From 858362e761a41e7d96efbcb9b38ae815b1e388d7 Mon Sep 17 00:00:00 2001 From: drbrain Date: Thu, 25 Sep 2008 02:43:03 +0000 Subject: Import RDoc 2.2.1 r185 git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@19537 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- lib/rdoc.rb | 190 +++++-- lib/rdoc/code_objects.rb | 86 ++- lib/rdoc/diagram.rb | 32 +- lib/rdoc/generator.rb | 36 +- lib/rdoc/generator/chm/chm.rb | 2 + lib/rdoc/generator/html.rb | 226 ++++---- lib/rdoc/generator/html/common.rb | 24 + lib/rdoc/generator/html/frameless.rb | 759 +-------------------------- lib/rdoc/generator/html/hefss.rb | 358 ++----------- lib/rdoc/generator/html/html.rb | 383 ++++++++------ lib/rdoc/generator/html/kilmer.rb | 329 ++---------- lib/rdoc/generator/html/kilmerfactory.rb | 427 +++++++++++++++ lib/rdoc/generator/html/one_page_html.rb | 11 +- lib/rdoc/generator/texinfo.rb | 9 +- lib/rdoc/generator/texinfo/class.texinfo.erb | 4 +- lib/rdoc/generator/xml.rb | 11 +- lib/rdoc/generator/xml/xml.rb | 30 +- lib/rdoc/markup.rb | 95 ---- lib/rdoc/markup/inline.rb | 2 +- lib/rdoc/markup/to_html.rb | 15 +- lib/rdoc/markup/to_html_crossref.rb | 88 +++- lib/rdoc/markup/to_texinfo.rb | 2 +- lib/rdoc/options.rb | 9 +- lib/rdoc/parser.rb | 23 +- lib/rdoc/parser/c.rb | 64 +-- lib/rdoc/parser/perl.rb | 165 ++++++ lib/rdoc/parser/ruby.rb | 12 +- lib/rdoc/parser/simple.rb | 2 +- lib/rdoc/rdoc.rb | 6 +- lib/rdoc/ri/cache.rb | 11 +- lib/rdoc/ri/descriptions.rb | 3 + lib/rdoc/ri/display.rb | 201 +++++-- lib/rdoc/ri/driver.rb | 522 +++++++++++------- lib/rdoc/ri/formatter.rb | 2 +- lib/rdoc/ri/paths.rb | 13 +- lib/rdoc/ri/reader.rb | 6 +- lib/rdoc/ri/util.rb | 2 - 37 files changed, 2034 insertions(+), 2126 deletions(-) create mode 100644 lib/rdoc/generator/html/common.rb create mode 100644 lib/rdoc/generator/html/kilmerfactory.rb create mode 100644 lib/rdoc/parser/perl.rb (limited to 'lib') diff --git a/lib/rdoc.rb b/lib/rdoc.rb index 53b72241f8..797b119fbf 100644 --- a/lib/rdoc.rb +++ b/lib/rdoc.rb @@ -1,14 +1,14 @@ $DEBUG_RDOC = nil ## -# RDoc - Ruby Documentation System +# = \RDoc - Ruby Documentation System # # This package contains RDoc and RDoc::Markup. RDoc is an application that -# produces documentation for one or more Ruby source files. We work similarly +# produces documentation for one or more Ruby source files. It works similarly # to JavaDoc, parsing the source, and extracting the definition for classes, -# modules, and methods (along with includes and requires). We associate with +# modules, and methods (along with includes and requires). It associates with # these optional documentation contained in the immediately preceding comment -# block, and then render the result using a pluggable output formatter. +# block, and then renders the result using a pluggable output formatter. # RDoc::Markup is a library that converts plain text into various output # formats. The markup library is used to interpret the comment blocks that # RDoc uses to document methods, classes, and so on. @@ -18,8 +18,6 @@ $DEBUG_RDOC = nil # * If you want to use RDoc to create documentation for your Ruby source files, # read on. # * If you want to include extensions written in C, see RDoc::Parser::C -# * For information on the various markups available in comment blocks, see -# RDoc::Markup. # * If you want to drive RDoc programmatically, see RDoc::RDoc. # * If you want to use the library to format text blocks into HTML, have a look # at RDoc::Markup. @@ -28,21 +26,21 @@ $DEBUG_RDOC = nil # # == Summary # -# Once installed, you can create documentation using the 'rdoc' command -# (the command is 'rdoc.bat' under Windows) +# Once installed, you can create documentation using the +rdoc+ command # # % rdoc [options] [names...] # -# Type "rdoc --help" for an up-to-date option summary. +# For an up-to-date option summary, type +# % rdoc --help # # A typical use might be to generate documentation for a package of Ruby -# source (such as rdoc itself). +# source (such as RDoc itself). # # % rdoc # # This command generates documentation for all the Ruby and C source # files in and below the current directory. These will be stored in a -# documentation tree starting in the subdirectory 'doc'. +# documentation tree starting in the subdirectory +doc+. # # You can make this slightly more useful for your readers by having the # index page contain the documentation for the primary file. In our @@ -54,20 +52,46 @@ $DEBUG_RDOC = nil # in comment blocks in the documentation this generates. # # RDoc uses file extensions to determine how to process each file. File names -# ending +.rb+ and .rbw are assumed to be Ruby source. Files +# ending +.rb+ and +.rbw+ are assumed to be Ruby source. Files # ending +.c+ are parsed as C files. All other files are assumed to # contain just Markup-style markup (with or without leading '#' comment # markers). If directory names are passed to RDoc, they are scanned # recursively for C and Ruby source files only. # -# = Markup +# == \Options +# rdoc can be passed a variety of command-line options. In addition, +# options can be specified via the +RDOCOPT+ environment variable, which +# functions similarly to the +RUBYOPT+ environment variable. # -# For information on how to make lists, hyperlinks, etc. with RDoc, see -# RDoc::Markup. +# % export RDOCOPT="-S" # -# Comment blocks can be written fairly naturally, either using '#' on +# will make rdoc default to inline method source code. Command-line options +# always will override those in +RDOCOPT+. +# +# Run +# +# % rdoc --help +# +# for full details on rdoc's options. +# +# Here are some of the most commonly used options. +# [-d, --diagram] +# Generate diagrams showing modules and +# classes. You need dot V1.8.6 or later to +# use the --diagram option correctly. Dot is +# available from http://graphviz.org +# +# [-S, --inline-source] +# Show method source code inline, rather than via a popup link. +# +# [-T, --template=NAME] +# Set the template used when generating output. +# +# == Documenting Source Code +# +# Comment blocks can be written fairly naturally, either using +#+ on # successive lines of the comment, or by including the comment in -# an =begin/=end block. If you use the latter form, the =begin line must be +# a =begin/=end block. If you use the latter form, the =begin line must be # flagged with an RDoc tag: # # =begin rdoc @@ -93,7 +117,7 @@ $DEBUG_RDOC = nil # # ... # end # -# Names of classes, source files, and any method names containing an +# Names of classes, files, and any method names containing an # underscore or preceded by a hash character are automatically hyperlinked # from comment text to their description. # @@ -124,15 +148,109 @@ $DEBUG_RDOC = nil # +:yields:+ is an example of a documentation directive. These appear # immediately after the start of the document element they are modifying. # +# == \Markup +# +# * The markup engine looks for a document's natural left margin. This is +# used as the initial margin for the document. +# +# * Consecutive lines starting at this margin are considered to be a +# paragraph. +# +# * If a paragraph starts with a "*", "-", or with ".", then it is +# taken to be the start of a list. The margin in increased to be the first +# non-space following the list start flag. Subsequent lines should be +# indented to this new margin until the list ends. For example: +# +# * this is a list with three paragraphs in +# the first item. This is the first paragraph. +# +# And this is the second paragraph. +# +# 1. This is an indented, numbered list. +# 2. This is the second item in that list +# +# This is the third conventional paragraph in the +# first list item. +# +# * This is the second item in the original list +# +# * You can also construct labeled lists, sometimes called description +# or definition lists. Do this by putting the label in square brackets +# and indenting the list body: +# +# [cat] a small furry mammal +# that seems to sleep a lot +# +# [ant] a little insect that is known +# to enjoy picnics +# +# A minor variation on labeled lists uses two colons to separate the +# label from the list body: +# +# cat:: a small furry mammal +# that seems to sleep a lot +# +# ant:: a little insect that is known +# to enjoy picnics +# +# This latter style guarantees that the list bodies' left margins are +# aligned: think of them as a two column table. +# +# * Any line that starts to the right of the current margin is treated +# as verbatim text. This is useful for code listings. The example of a +# list above is also verbatim text. +# +# * A line starting with an equals sign (=) is treated as a +# heading. Level one headings have one equals sign, level two headings +# have two,and so on. +# +# * A line starting with three or more hyphens (at the current indent) +# generates a horizontal rule. The more hyphens, the thicker the rule +# (within reason, and if supported by the output device) +# +# * You can use markup within text (except verbatim) to change the +# appearance of parts of that text. Out of the box, RDoc::Markup +# supports word-based and general markup. +# +# Word-based markup uses flag characters around individual words: +# +# [\*word*] displays word in a *bold* font +# [\_word_] displays word in an _emphasized_ font +# [\+word+] displays word in a +code+ font +# +# General markup affects text between a start delimiter and and end +# delimiter. Not surprisingly, these delimiters look like HTML markup. +# +# [\text...] displays word in a *bold* font +# [\text...] displays word in an _emphasized_ font +# [\\text...] displays word in an italicized font +# [\text...] displays word in a +code+ font +# +# Unlike conventional Wiki markup, general markup can cross line +# boundaries. You can turn off the interpretation of markup by +# preceding the first character with a backslash. This only works for +# simple markup, not HTML-style markup. +# +# * Hyperlinks to the web starting http:, mailto:, ftp:, or www. are +# recognized. An HTTP url that references an external image file is +# converted into an inline . Hyperlinks starting 'link:' are +# assumed to refer to local files whose path is relative to the --op +# directory. +# +# Hyperlinks can also be of the form label[url], in which +# case the label is used in the displayed text, and +url+ is +# used as the target. If +label+ contains multiple words, +# put it in braces: {multi word label}[url]. +# # == Directives # # [+:nodoc:+ / +:nodoc:+ all] -# Don't include this element in the documentation. For classes -# and modules, the methods, aliases, constants, and attributes -# directly within the affected class or module will also be -# omitted. By default, though, modules and classes within that -# class of module _will_ be documented. This is turned off by -# adding the +all+ modifier. +# This directive prevents documentation for the element from +# being generated. For classes and modules, the methods, aliases, +# constants, and attributes directly within the affected class or +# module also will be omitted. By default, though, modules and +# classes within that class of module _will_ be documented. This is +# turned off by adding the +all+ modifier. # # module MyModule # :nodoc: # class Input @@ -144,22 +262,22 @@ $DEBUG_RDOC = nil # end # end # -# In the above code, only class +MyModule::Input+ will be documented.The -# The :nodoc: directive is global across all files the class or module -# appears in, so use :stopdoc:/:startdoc: to only omit documentation for a -# particular set of methods, etc. +# In the above code, only class MyModule::Input will be documented. +# The +:nodoc:+ directive is global across all files for the class or module +# to which it applies, so use +:stopdoc:+/+:startdoc:+ to suppress +# documentation only for a particular set of methods, etc. # # [+:doc:+] -# Force a method or attribute to be documented even if it wouldn't otherwise -# be. Useful if, for example, you want to include documentation of a +# Forces a method or attribute to be documented even if it wouldn't be +# otherwise. Useful if, for example, you want to include documentation of a # particular private method. # # [+:notnew:+] # Only applicable to the +initialize+ instance method. Normally RDoc -# assumes that the documentation and parameters for #initialize are -# actually for the ::new method, and so fakes out a ::new for the class. -# The :notnew: modifier stops this. Remember that #initialize is protected, -# so you won't see the documentation unless you use the -a command line +# assumes that the documentation and parameters for +initialize+ are +# actually for the +new+ method, and so fakes out a +new+ for the class. +# The +:notnew:+ modifier stops this. Remember that +initialize+ is private, +# so you won't see the documentation unless you use the +-a+ command line # option. # # Comment blocks can contain other directives: @@ -209,7 +327,7 @@ $DEBUG_RDOC = nil # last. If you don't specify a +:startdoc:+ by the end of the container, # disables documentation for the entire class or module. # -# = Other stuff +# == Other stuff # # RDoc is currently being maintained by Eric Hodel # @@ -254,7 +372,7 @@ module RDoc ## # RDoc version you are using - VERSION = "2.1.0" + VERSION = "2.2.1" ## # Name of the dotfile that contains the description of files to be processed diff --git a/lib/rdoc/code_objects.rb b/lib/rdoc/code_objects.rb index fbdb612b92..0916b03398 100644 --- a/lib/rdoc/code_objects.rb +++ b/lib/rdoc/code_objects.rb @@ -219,6 +219,22 @@ module RDoc @modules.values end + ## + # return the classes Hash (only to be used internally) + + def classes_hash + @classes + end + protected :classes_hash + + ## + # return the modules Hash (only to be used internally) + + def modules_hash + @modules + end + protected :modules_hash + ## # Change the default visibility for new methods @@ -272,7 +288,24 @@ module RDoc end def add_class(class_type, name, superclass) - add_class_or_module @classes, class_type, name, superclass + klass = add_class_or_module @classes, class_type, name, superclass + + # + # If the parser encounters Container::Item before encountering + # Container, then it assumes that Container is a module. This + # may not be the case, so remove Container from the module list + # if present and transfer any contained classes and modules to + # the new class. + # + mod = @modules.delete(name) + + if mod then + klass.classes_hash.update(mod.classes_hash) + klass.modules_hash.update(mod.modules_hash) + klass.method_list.concat(mod.method_list) + end + + return klass end def add_module(class_type, name) @@ -282,25 +315,41 @@ module RDoc def add_method(a_method) a_method.visibility = @visibility add_to(@method_list, a_method) + + unmatched_alias_list = @unmatched_alias_lists[a_method.name] + if unmatched_alias_list then + unmatched_alias_list.each do |unmatched_alias| + add_alias_impl unmatched_alias, a_method + @aliases.delete unmatched_alias + end + + @unmatched_alias_lists.delete a_method.name + end end def add_attribute(an_attribute) add_to(@attributes, an_attribute) end + def add_alias_impl(an_alias, meth) + new_meth = AnyMethod.new(an_alias.text, an_alias.new_name) + new_meth.is_alias_for = meth + new_meth.singleton = meth.singleton + new_meth.params = meth.params + new_meth.comment = "Alias for \##{meth.name}" + meth.add_alias(new_meth) + add_method(new_meth) + end + def add_alias(an_alias) meth = find_instance_method_named(an_alias.old_name) if meth then - new_meth = AnyMethod.new(an_alias.text, an_alias.new_name) - new_meth.is_alias_for = meth - new_meth.singleton = meth.singleton - new_meth.params = meth.params - new_meth.comment = "Alias for \##{meth.name}" - meth.add_alias(new_meth) - add_method(new_meth) + add_alias_impl(an_alias, meth) else add_to(@aliases, an_alias) + unmatched_alias_list = @unmatched_alias_lists[an_alias.old_name] ||= [] + unmatched_alias_list.push(an_alias) end an_alias @@ -360,6 +409,10 @@ module RDoc @requires = [] @includes = [] @constants = [] + + # This Hash maps a method name to a list of unmatched + # aliases (aliases of a method not yet encountered). + @unmatched_alias_lists = {} end # and remove classes and modules when we see a :nodoc: all @@ -374,9 +427,12 @@ module RDoc # Find a named module def find_module_named(name) - return self if self.name == name + # First check the enclosed modules, then check the module itself, + # then check the enclosing modules (this mirrors the check done by + # the Ruby parser) res = @modules[name] || @classes[name] return res if res + return self if self.name == name find_enclosing_module_named(name) end @@ -435,6 +491,7 @@ module RDoc unless modules.empty? then module_name = modules.shift result = find_module_named(module_name) + if result then modules.each do |name| result = result.find_module_named(name) @@ -573,9 +630,18 @@ module RDoc cls = all[name] - unless cls then + if !cls then cls = class_type.new name, superclass all[name] = cls unless @done_documenting + else + # If the class has been encountered already, check that its + # superclass has been set (it may not have been, depending on + # the context in which it was encountered). + if class_type == NormalClass + if !cls.superclass then + cls.superclass = superclass + end + end end collection[name] = cls unless @done_documenting diff --git a/lib/rdoc/diagram.rb b/lib/rdoc/diagram.rb index e235e043dc..4aa2ec5656 100644 --- a/lib/rdoc/diagram.rb +++ b/lib/rdoc/diagram.rb @@ -311,28 +311,30 @@ module RDoc # inclusion on the page def wrap_in_image_map(src, dot) - res = %{\n} + res = "" dot_map = `dot -Tismap #{src}` - dot_map.split($/).each do |area| - unless area =~ /^rectangle \((\d+),(\d+)\) \((\d+),(\d+)\) ([\/\w.]+)\s*(.*)/ - $stderr.puts "Unexpected output from dot:\n#{area}" - return nil - end + + if(!dot_map.empty?) + res << %{\n} + dot_map.split($/).each do |area| + unless area =~ /^rectangle \((\d+),(\d+)\) \((\d+),(\d+)\) ([\/\w.]+)\s*(.*)/ + $stderr.puts "Unexpected output from dot:\n#{area}" + return nil + end - xs, ys = [$1.to_i, $3.to_i], [$2.to_i, $4.to_i] - url, area_name = $5, $6 + xs, ys = [$1.to_i, $3.to_i], [$2.to_i, $4.to_i] + url, area_name = $5, $6 - res << %{ #{area_name}\n} + res << %{ #{area_name}\n} + end + res << "\n" end - res << "\n" -# map_file = src.sub(/.dot/, '.map') -# system("dot -Timap #{src} -o #{map_file}") - res << %{#{dot}} + + res << %{#{dot}} return res end end end - diff --git a/lib/rdoc/generator.rb b/lib/rdoc/generator.rb index fbc08c4e20..d695e661d1 100644 --- a/lib/rdoc/generator.rb +++ b/lib/rdoc/generator.rb @@ -127,7 +127,7 @@ module RDoc::Generator # * a complete list of all hyperlinkable terms (file, class, module, and # method names) - def self.build_indicies(toplevels, options) + def self.build_indices(toplevels, options) files = [] classes = [] @@ -215,7 +215,7 @@ module RDoc::Generator @methods.sort.map do |meth| { "name" => CGI.escapeHTML(meth.name), - "aref" => "#{path_prefix}\##{meth.aref}" + "aref" => "##{meth.aref}" } end end @@ -614,9 +614,9 @@ module RDoc::Generator def class_attribute_values h_name = CGI.escapeHTML(name) - @values["path"] = @path + @values["href"] = @path @values["classmod"] = @is_module ? "Module" : "Class" - @values["title"] = "#{@values['classmod']}: #{h_name}" + @values["title"] = "#{@values['classmod']}: #{h_name} [#{@options.title}]" c = @context c = c.parent while c and not c.diagram @@ -704,7 +704,7 @@ module RDoc::Generator def filename_to_label @context.file_relative_name.gsub(/%|\/|\?|\#/) do - '%%%x' % $&[0].unpack('C') + ('%%%x' % $&[0]).unpack('C') end end @@ -791,7 +791,7 @@ module RDoc::Generator full_path = @context.file_absolute_name short_name = ::File.basename full_path - @values["title"] = CGI.escapeHTML("File: #{short_name}") + @values["title"] = CGI.escapeHTML("File: #{short_name} [#{@options.title}]") if @context.diagram then @values["diagram"] = diagram_reference(@context.diagram) @@ -821,18 +821,18 @@ module RDoc::Generator attr_reader :img_url attr_reader :source_code - @@seq = "M000000" - - @@all_methods = [] - def self.all_methods @@all_methods end def self.reset @@all_methods = [] + @@seq = "M000000" end + # Initialize the class variables. + self.reset + def initialize(context, html_class, options) # TODO: rethink the class hierarchy here... @context = context @@ -1043,12 +1043,18 @@ module RDoc::Generator first = $1.to_i - 1 last = first + src.count("\n") size = last.to_s.length - real_fmt = "%#{size}d: " - fmt = " " * (size+2) + fmt = "%#{size}d: " + is_first_line = true + line_num = first src.gsub!(/^/) do - res = sprintf(fmt, first) - first += 1 - fmt = real_fmt + if is_first_line then + is_first_line = false + res = " " * (size+2) + else + res = sprintf(fmt, line_num) + end + + line_num += 1 res end end diff --git a/lib/rdoc/generator/chm/chm.rb b/lib/rdoc/generator/chm/chm.rb index 0a17a9e1ea..cceeca5dfc 100644 --- a/lib/rdoc/generator/chm/chm.rb +++ b/lib/rdoc/generator/chm/chm.rb @@ -6,6 +6,8 @@ module RDoc::Generator::CHM::CHM HTML = RDoc::Generator::HTML::HTML INDEX = HTML::INDEX + + STYLE = HTML::STYLE CLASS_INDEX = HTML::CLASS_INDEX CLASS_PAGE = HTML::CLASS_PAGE diff --git a/lib/rdoc/generator/html.rb b/lib/rdoc/generator/html.rb index a9e030a896..d136de7b00 100644 --- a/lib/rdoc/generator/html.rb +++ b/lib/rdoc/generator/html.rb @@ -68,7 +68,6 @@ class RDoc::Generator::HTML def initialize(options) #:not-new: @options = options load_html_template - @main_page_path = nil end ## @@ -94,6 +93,15 @@ class RDoc::Generator::HTML # If the template name contains a slash, use it literally def load_html_template + # + # If the template is not a path, first look for it + # in rdoc's HTML template directory. Perhaps this behavior should + # be reversed (first try to include the template and, only if that + # fails, try to include it in the default template directory). + # One danger with reversing the behavior, however, is that + # if something like require 'html' could load up an + # unrelated file in the standard library or in a gem. + # template = @options.template unless template =~ %r{/|\\} then @@ -101,14 +109,25 @@ class RDoc::Generator::HTML template) end - require template - - @template = self.class.const_get @options.template.upcase - @options.template_class = @template + begin + require template + + @template = self.class.const_get @options.template.upcase + @options.template_class = @template + rescue LoadError => e + # + # The template did not exist in the default template directory, so + # see if require can find the template elsewhere (in a gem, for + # instance). + # + if(e.message[template] && template != @options.template) + template = @options.template + retry + end - rescue LoadError - $stderr.puts "Could not find HTML template '#{template}'" - exit 99 + $stderr.puts "Could not find HTML template '#{template}': #{e.message}" + exit 99 + end end ## @@ -146,14 +165,16 @@ class RDoc::Generator::HTML end def build_indices - @files, @classes = RDoc::Generator::Context.build_indicies(@toplevels, - @options) + @files, @classes = RDoc::Generator::Context.build_indices(@toplevels, + @options) end ## # Generate all the HTML def generate_html + @main_url = main_url + # the individual descriptions for files and classes gen_into(@files) gen_into(@classes) @@ -165,23 +186,50 @@ class RDoc::Generator::HTML gen_main_index # this method is defined in the template file - write_extra_pages if defined? write_extra_pages + values = { + 'title_suffix' => CGI.escapeHTML("[#{@options.title}]"), + 'charset' => @options.charset, + 'style_url' => style_url('', @options.css), + } + + @template.write_extra_pages(values) if @template.respond_to?(:write_extra_pages) end def gen_into(list) - @file_list ||= index_to_links @files - @class_list ||= index_to_links @classes - @method_list ||= index_to_links RDoc::Generator::Method.all_methods + # + # The file, class, and method lists technically should be regenerated + # for every output file, in order that the relative links be correct + # (we are worried here about frameless templates, which need this + # information for every generated page). Doing this is a bit slow, + # however. For a medium-sized gem, this increased rdoc's runtime by + # about 5% (using the 'time' command-line utility). While this is not + # necessarily a problem, I do not want to pessimize rdoc for large + # projects, however, and so we only regenerate the lists when the + # directory of the output file changes, which seems like a reasonable + # optimization. + # + file_list = {} + class_list = {} + method_list = {} + prev_op_dir = nil list.each do |item| next unless item.document_self op_file = item.path + op_dir = File.dirname(op_file) + + if(op_dir != prev_op_dir) + file_list = index_to_links op_file, @files + class_list = index_to_links op_file, @classes + method_list = index_to_links op_file, RDoc::Generator::Method.all_methods + end + prev_op_dir = op_dir - FileUtils.mkdir_p File.dirname(op_file) + FileUtils.mkdir_p op_dir open op_file, 'w' do |io| - item.write_on io, @file_list, @class_list, @method_list + item.write_on io, file_list, class_list, method_list end end end @@ -211,8 +259,9 @@ class RDoc::Generator::HTML values = { "entries" => res, + 'title' => CGI.escapeHTML("#{title} [#{@options.title}]"), 'list_title' => CGI.escapeHTML(title), - 'index_url' => main_url, + 'index_url' => @main_url, 'charset' => @options.charset, 'style_url' => style_url('', @options.css), } @@ -230,47 +279,55 @@ class RDoc::Generator::HTML def gen_main_index if @template.const_defined? :FRAMELESS then - main = @files.find do |file| - @main_page == file.name - end - - if main.nil? then - main = @classes.find do |klass| - main_page == klass.context.full_name - end + # + # If we're using a template without frames, then just redirect + # to it from index.html. + # + # One alternative to this, expanding the main page's template into + # index.html, is tricky because the relative URLs will be different + # (since index.html is located in at the site's root, + # rather than within a files or a classes subdirectory). + # + open 'index.html', 'w' do |f| + f.puts(%{}) + f.puts(%{}) + f.puts(%{}) + f.puts(%{#{CGI.escapeHTML(@options.title)}}) + f.puts(%{}) + f.puts(%{}) + f.puts(%{}) + f.puts(%{}) end else main = RDoc::TemplatePage.new @template::INDEX - end - open 'index.html', 'w' do |f| - style_url = style_url '', @options.css + open 'index.html', 'w' do |f| + style_url = style_url '', @options.css + + classes = @classes.sort.map { |klass| klass.value_hash } + + values = { + 'initial_page' => @main_url, + 'style_url' => style_url('', @options.css), + 'title' => CGI.escapeHTML(@options.title), + 'charset' => @options.charset, + 'classes' => classes, + } + + values['inline_source'] = @options.inline_source - classes = @classes.sort.map { |klass| klass.value_hash } - - values = { - 'main_page' => @main_page, - 'initial_page' => main_url, - 'style_url' => style_url('', @options.css), - 'title' => CGI.escapeHTML(@options.title), - 'charset' => @options.charset, - 'classes' => classes, - } - - values['inline_source'] = @options.inline_source - - if main.respond_to? :write_on then - main.write_on f, @file_list, @class_list, @method_list, values - else main.write_html_on f, values end end end - def index_to_links(collection) + def index_to_links(output_path, collection) collection.sort.map do |f| next unless f.document_self - { "href" => f.path, "name" => f.index_name } + { "href" => RDoc::Markup::ToHtml.gen_relative_url(output_path, f.path), + "name" => f.index_name } end.compact end @@ -278,32 +335,48 @@ class RDoc::Generator::HTML # Returns the url of the main page def main_url - @main_page = @options.main_page - @main_page_ref = nil - - if @main_page then - @main_page_ref = RDoc::Generator::AllReferences[@main_page] - - if @main_page_ref then - @main_page_path = @main_page_ref.path + main_page = @options.main_page + + # + # If a main page has been specified (--main), then search for it + # in the AllReferences array. This allows either files or classes + # to be used for the main page. + # + if main_page then + main_page_ref = RDoc::Generator::AllReferences[main_page] + + if main_page_ref then + return main_page_ref.path else - $stderr.puts "Could not find main page #{@main_page}" + $stderr.puts "Could not find main page #{main_page}" end end - unless @main_page_path then - file = @files.find { |context| context.document_self } - @main_page_path = file.path if file + # + # No main page has been specified, so just use the README. + # + @files.each do |file| + if file.name =~ /^README/ then + return file.path + end end - unless @main_page_path then - $stderr.puts "Couldn't find anything to document" - $stderr.puts "Perhaps you've used :stopdoc: in all classes" - exit 1 + # + # There's no README (shame! shame!). Just use the first file + # that will be documented. + # + @files.each do |file| + if file.document_self then + return file.path + end end - @main_page_path + # + # There are no files to be documented... Something seems very wrong. + # + raise RDoc::Error, "Couldn't find anything to document (perhaps :stopdoc: has been used in all classes)!" end + private :main_url end @@ -349,12 +422,9 @@ class RDoc::Generator::HTMLInOne < RDoc::Generator::HTML 'charset' => @options.charset, 'files' => gen_into(@files), 'classes' => gen_into(@classes), - 'title' => CGI.escapeHTML(@options.title), + 'title' => CGI.escapeHTML(@options.title), } - # this method is defined in the template file - write_extra_pages if defined? write_extra_pages - template = RDoc::TemplatePage.new @template::ONE_PAGE if @options.op_name @@ -372,26 +442,4 @@ class RDoc::Generator::HTMLInOne < RDoc::Generator::HTML end res end - - def gen_file_index - gen_an_index(@files, 'Files') - end - - def gen_class_index - gen_an_index(@classes, 'Classes') - end - - def gen_method_index - gen_an_index(RDoc::Generator::Method.all_methods, 'Methods') - end - - def gen_an_index(collection, title) - return { - "entries" => index_to_links(collection), - 'list_title' => title, - 'index_url' => main_url, - } - end - end - diff --git a/lib/rdoc/generator/html/common.rb b/lib/rdoc/generator/html/common.rb new file mode 100644 index 0000000000..b25f009a72 --- /dev/null +++ b/lib/rdoc/generator/html/common.rb @@ -0,0 +1,24 @@ +# +# The templates require further refactoring. In particular, +# * Some kind of HTML generation library should be used. +# +# Also, all of the templates require some TLC from a designer. +# +# Right now, this file contains some constants that are used by all +# of the templates. +# +module RDoc::Generator::HTML::Common + XHTML_STRICT_PREAMBLE = <<-EOF + +EOF + + XHTML_FRAME_PREAMBLE = <<-EOF + +EOF + + HTML_ELEMENT = <<-EOF + +EOF +end diff --git a/lib/rdoc/generator/html/frameless.rb b/lib/rdoc/generator/html/frameless.rb index 2af890ce04..0375fee313 100644 --- a/lib/rdoc/generator/html/frameless.rb +++ b/lib/rdoc/generator/html/frameless.rb @@ -1,15 +1,16 @@ -require 'rdoc/generator/html' -require 'rdoc/generator/html/one_page_html' +require 'rdoc/generator/html/html' ## # = CSS2 RDoc HTML template # -# This is a template for RDoc that uses XHTML 1.0 Transitional and dictates a +# This is a template for RDoc that uses XHTML 1.0 Strict and dictates a # bit more of the appearance of the output to cascading stylesheets than the # default. It was designed for clean inline code display, and uses DHTMl to # toggle the visbility of each method's source with each click on the '[source]' # link. # +# Frameless basically is the html template without frames. +# # == Authors # # * Michael Granger @@ -25,692 +26,47 @@ module RDoc::Generator::HTML::FRAMELESS FRAMELESS = true - FONTS = "Verdana,Arial,Helvetica,sans-serif" - - STYLE = <<-EOF -body { - font-family: #{FONTS}; - font-size: 90%; - margin: 0; - margin-left: 40px; - padding: 0; - background: white; -} - -h1, h2, h3, h4 { - margin: 0; - color: #efefef; - background: transparent; -} - -h1 { - font-size: 150%; -} - -h2,h3,h4 { - margin-top: 1em; -} - -:link, :visited { - background: #eef; - color: #039; - text-decoration: none; -} - -:link:hover, :visited:hover { - background: #039; - color: #eef; -} - -/* Override the base stylesheet's Anchor inside a table cell */ -td > :link, td > :visited { - background: transparent; - color: #039; - text-decoration: none; -} - -/* and inside a section title */ -.section-title > :link, .section-title > :visited { - background: transparent; - color: #eee; - text-decoration: none; -} - -/* === Structural elements =================================== */ - -.index { - margin: 0; - margin-left: -40px; - padding: 0; - font-size: 90%; -} - -.index :link, .index :visited { - margin-left: 0.7em; -} - -.index .section-bar { - margin-left: 0px; - padding-left: 0.7em; - background: #ccc; - font-size: small; -} - -#classHeader, #fileHeader { - width: auto; - color: white; - padding: 0.5em 1.5em 0.5em 1.5em; - margin: 0; - margin-left: -40px; - border-bottom: 3px solid #006; -} - -#classHeader :link, #fileHeader :link, -#classHeader :visited, #fileHeader :visited { - background: inherit; - color: white; -} - -#classHeader td, #fileHeader td { - background: inherit; - color: white; -} - -#fileHeader { - background: #057; -} - -#classHeader { - background: #048; -} - -.class-name-in-header { - font-size: 180%; - font-weight: bold; -} - -#bodyContent { - padding: 0 1.5em 0 1.5em; -} - -#description { - padding: 0.5em 1.5em; - background: #efefef; - border: 1px dotted #999; -} - -#description h1, #description h2, #description h3, -#description h4, #description h5, #description h6 { - color: #125; - background: transparent; -} - -#copyright { - color: #333; - background: #efefef; - font: 0.75em sans-serif; - margin-top: 5em; - margin-bottom: 0; - padding: 0.5em 2em; -} - -/* === Classes =================================== */ - -table.header-table { - color: white; - font-size: small; -} - -.type-note { - font-size: small; - color: #dedede; -} - -.xxsection-bar { - background: #eee; - color: #333; - padding: 3px; -} - -.section-bar { - color: #333; - border-bottom: 1px solid #999; - margin-left: -20px; -} - -.section-title { - background: #79a; - color: #eee; - padding: 3px; - margin-top: 2em; - margin-left: -30px; - border: 1px solid #999; -} - -.top-aligned-row { - vertical-align: top -} - -.bottom-aligned-row { - vertical-align: bottom -} - -/* --- Context section classes ----------------------- */ - -.context-row { } - -.context-item-name { - font-family: monospace; - font-weight: bold; - color: black; -} - -.context-item-value { - font-size: small; - color: #448; -} - -.context-item-desc { - color: #333; - padding-left: 2em; -} - -/* --- Method classes -------------------------- */ - -.method-detail { - background: #efefef; - padding: 0; - margin-top: 0.5em; - margin-bottom: 1em; - border: 1px dotted #ccc; -} - -.method-heading { - color: black; - background: #ccc; - border-bottom: 1px solid #666; - padding: 0.2em 0.5em 0 0.5em; -} - -.method-signature { - color: black; - background: inherit; -} - -.method-name { - font-weight: bold; -} - -.method-args { - font-style: italic; -} + FONTS = RDoc::Generator::HTML::HTML::FONTS -.method-description { - padding: 0 0.5em 0 0.5em; -} + STYLE = RDoc::Generator::HTML::HTML::STYLE -/* --- Source code sections -------------------- */ - -:link.source-toggle, :visited.source-toggle { - font-size: 90%; -} - -div.method-source-code { - background: #262626; - color: #ffdead; - margin: 1em; - padding: 0.5em; - border: 1px dashed #999; - overflow: hidden; -} - -div.method-source-code pre { - color: #ffdead; - overflow: hidden; -} - -/* --- Ruby keyword styles --------------------- */ - -.standalone-code { - background: #221111; - color: #ffdead; - overflow: hidden; -} - -.ruby-constant { - color: #7fffd4; - background: transparent; -} - -.ruby-keyword { - color: #00ffff; - background: transparent; -} - -.ruby-ivar { - color: #eedd82; - background: transparent; -} - -.ruby-operator { - color: #00ffee; - background: transparent; -} - -.ruby-identifier { - color: #ffdead; - background: transparent; -} - -.ruby-node { - color: #ffa07a; - background: transparent; -} - -.ruby-comment { - color: #b22222; - font-weight: bold; - background: transparent; -} - -.ruby-regexp { - color: #ffa07a; - background: transparent; -} - -.ruby-value { - color: #7fffd4; - background: transparent; -} - -EOF - - ## - # Header template - - XHTML_PREAMBLE = <<-EOF -"?> - - EOF - - HEADER = XHTML_PREAMBLE + <<-EOF - - - <%= values["title"] %> - " /> - - " type="text/css" media="screen" /> - - - - -EOF - - ## - # Context content template - - CONTEXT_CONTENT = %{ -} - - ## - # Footer template + HEADER = RDoc::Generator::HTML::HTML::HEADER FOOTER = <<-EOF
- - - +
EOF - ## - # File page header template - - FILE_PAGE = <<-EOF -
-

<%= values["short_name"] %>

- - - - - - - - - - - -
Path:<%= values["full_path"] %> -<% if values["cvsurl"] then %> -  (">CVS) -<% end %> -
Last Update:<%= values["dtm_modified"] %>
-
- EOF - - ## - # Class page header template - - CLASS_PAGE = <<-EOF -
- - - - - - - - - - - -<% if values["parent"] then %> - - - - -<% end %> -
<%= values["classmod"] %><%= values["full_name"] %>
In: -<% values["infiles"].each do |infiles| %> -<% if infiles["full_path_url"] then %> - "> -<% end %> - <%= infiles["full_path"] %> -<% if infiles["full_path_url"] then %> - -<% end %> -<% if infiles["cvsurl"] then %> -  (">CVS) -<% end %> -
-<% end %><%# values["infiles"] %> -
Parent: -<% if values["par_url"] then %> - "> -<% end %> - <%= values["parent"] %> -<% if values["par_url"] then %> - -<% end %> -
-
- EOF - - ## - # Method list template - - METHOD_LIST = <<-EOF - -
-<% if values["diagram"] then %> -
- <%= values["diagram"] %> -
-<% end %> - -<% if values["description"] then %> -
- <%= values["description"] %> -
-<% end %> - -<% if values["requires"] then %> -
-

Required files

- -
-<% values["requires"].each do |requires| %> - <%= href requires["aref"], requires["name"] %>   -<% end %><%# values["requires"] %> -
-
-<% end %> - -<% if values["toc"] then %> -
-

Contents

- -<% end %> -
- -<% if values["methods"] then %> -
-

Methods

+ FILE_PAGE = RDoc::Generator::HTML::HTML::FILE_PAGE -
-<% values["methods"].each do |methods| %> - <%= href methods["aref"], methods["name"] %>   -<% end %><%# values["methods"] %> -
-
-<% end %> + CLASS_PAGE = RDoc::Generator::HTML::HTML::CLASS_PAGE -
- - - -<% if values["includes"] then %> -
-

Included Modules

- -
-<% values["includes"].each do |includes| %> - <%= href includes["aref"], includes["name"] %> -<% end %><%# values["includes"] %> -
-
-<% end %> - -<% values["sections"].each do |sections| %> -
-<% if sections["sectitle"] then %> -

"><%= sections["sectitle"] %>

-<% if sections["seccomment"] then %> -
- <%= sections["seccomment"] %> -
-<% end %> -<% end %> - -<% if values["classlist"] then %> -
-

Classes and Modules

- - <%= values["classlist"] %> -
-<% end %> - -<% if values["constants"] then %> -
-

Constants

- -
- -<% values["constants"].each do |constants| %> - - - - -<% if values["desc"] then %> - - -<% end %> - -<% end %><%# values["constants"] %> -
<%= constants["name"] %>=<%= constants["value"] %> <%= constants["desc"] %>
-
-
-<% end %> - -<% if values["aliases"] then %> -
-

External Aliases

- -
- -<% values["aliases"].each do |aliases| $stderr.puts({ :aliases => aliases }.inspect) %> - - - - - -<% if values["desc"] then %> - - - - -<% end %> -<% end %><%# values["aliases"] %> -
<%= values["old_name"] %>-><%= values["new_name"] %>
 <%= values["desc"] %>
-
-
-<% end %> - - -<% if values["attributes"] then %> -
-

Attributes

- -
- -<% values["attributes"].each do |attributes| $stderr.puts({ :attributes => attributes }.inspect) %> - - -<% if values["rw"] then %> - -<% end %> -<% unless values["rw"] then %> - -<% end %> - - -<% end %><%# values["attributes"] %> -
<%= values["name"] %> [<%= values["rw"] %>]   <%= values["a_desc"] %>
-
-
-<% end %> - - -<% if sections["method_list"] then %> -
-<% sections["method_list"].each do |method_list| %> -<% if method_list["methods"] then %> -

<%= method_list["type"] %> <%= method_list["category"] %> methods

- -<% method_list["methods"].each do |methods| %> -
" class="method-detail"> - "> - -
-<% if methods["codeurl"] then %> - " target="Code" class="method-signature" - onclick="popupCode('<%= methods["codeurl"] %>');return false;"> -<% end %> -<% if methods["sourcecode"] then %> - " class="method-signature"> -<% end %> -<% if methods["callseq"] then %> - <%= methods["callseq"] %> -<% end %> -<% unless methods["callseq"] then %> - <%= methods["name"] %><%= methods["params"] %> -<% end %> -<% if methods["codeurl"] then %> - -<% end %> -<% if methods["sourcecode"] then %> - -<% end %> -
- -
-<% if methods["m_desc"] then %> - <%= methods["m_desc"] %> -<% end %> -<% if methods["sourcecode"] then %> -

-source');return false;">[Source]

-
-source"> -
-<%= methods["sourcecode"] %>
-
-
-<% end %> -
-
- -<% end %><%# method_list["methods"] %> -<% end %> -<% end %><%# sections["method_list"] %> - -
-<% end %> -<% end %><%# values["sections"] %> - EOF - - ## - # Body template + METHOD_LIST = RDoc::Generator::HTML::HTML::METHOD_LIST BODY = HEADER + %{ @@ -724,72 +80,13 @@ EOF } + FOOTER - ## - # Source code template - - SRC_PAGE = XHTML_PREAMBLE + <<-EOF - - - <%= values["title"] %> - " /> - " type="text/css" media="screen" /> - - - 
<%= values["code"] %>
- - - EOF - - ## - # Index file templates - - FR_INDEX_BODY = %{ -<%= template_include %> -} + SRC_PAGE = RDoc::Generator::HTML::HTML::SRC_PAGE - FILE_INDEX = XHTML_PREAMBLE + <<-EOF - - - <%= values["list_title"] %> - " /> - " type="text/css" /> - - - -
-

<%= values["list_title"] %>

-
-<% values["entries"].each do |entries| %> - "><%= entries["name"] %>
-<% end %><%# values["entries"] %> -
-
- - - EOF + FR_INDEX_BODY = RDoc::Generator::HTML::HTML::FR_INDEX_BODY - CLASS_INDEX = FILE_INDEX - METHOD_INDEX = FILE_INDEX + FILE_INDEX = RDoc::Generator::HTML::HTML::FILE_INDEX - INDEX = <<-EOF -"?> - - - - <%= values["title"] %> - " /> - - - - - - - " name="docwin" /> - - - EOF + CLASS_INDEX = RDoc::Generator::HTML::HTML::CLASS_INDEX + METHOD_INDEX = RDoc::Generator::HTML::HTML::METHOD_INDEX end - diff --git a/lib/rdoc/generator/html/hefss.rb b/lib/rdoc/generator/html/hefss.rb index e186a40384..540c23d869 100644 --- a/lib/rdoc/generator/html/hefss.rb +++ b/lib/rdoc/generator/html/hefss.rb @@ -1,16 +1,16 @@ require 'rdoc/generator/html' -require 'rdoc/generator/html/html' +require 'rdoc/generator/html/kilmerfactory' module RDoc::Generator::HTML::HEFSS FONTS = "Verdana, Arial, Helvetica, sans-serif" -STYLE = <<-EOF -body,p { font-family: Verdana, Arial, Helvetica, sans-serif; + CENTRAL_STYLE = <<-EOF +body,p { font-family: <%= values["fonts"] %>; color: #000040; background: #BBBBBB; } -td { font-family: Verdana, Arial, Helvetica, sans-serif; +td { font-family: <%= values["fonts"] %>; color: #000040; } @@ -21,16 +21,20 @@ td { font-family: Verdana, Arial, Helvetica, sans-serif; } .big-title-font { color: white; - font-family: Verdana, Arial, Helvetica, sans-serif; + font-family: <%= values["fonts"] %>; font-size: large; height: 50px} .small-title-font { color: purple; - font-family: Verdana, Arial, Helvetica, sans-serif; + font-family: <%= values["fonts"] %>; font-size: small; } .aqua { color: purple } +#diagram img { + border: 0; +} + .method-name, attr-name { font-family: monospace; font-weight: bold; } @@ -75,241 +79,6 @@ td { font-family: Verdana, Arial, Helvetica, sans-serif; color: #0000AA; } -.column-title { - font-size: medium; - font-weight: bold; - text_decoration: none; - padding: 3px 3px 3px 20px; - color: #3333CC; - } - -.variable-name { - font-family: monospace; - font-size: medium; - text_decoration: none; - padding: 3px 3px 3px 20px; - color: #0000AA; -} - -.row-name { - font-size: medium; - font-weight: medium; - font-family: monospace; - text_decoration: none; - padding: 3px 3px 3px 20px; -} - -.paramsig { - font-size: small; -} - -.srcbut { float: right } - - EOF - - BODY = <<-EOF - - <%= values["title"] %> - "> - " type="text/css" media="screen" /> - - - - -<%= template_include %> - -<% if values["diagram"] then %> -
-<%= values["diagram"] %> -
-<% end %> - -<% if values["description"] then %> -
<%= values["description"] %>
-<% end %> - -<% if values["requires"] then %> - - -
Required files

-
-<% values["requires"].each do |requires| %> -<%= href requires["aref"], requires["name"] %> -<% end %><%# values["requires"] %> -<% end %> -
- -<% if values["sections"] then %> -<% values["sections"].each do |sections| %> -<% if sections["method_list"] then %> -<% sections["method_list"].each do |method_list| %> -<% if method_list["methods"] then %> - - -
Subroutines and Functions

-
-<% method_list["methods"].each do |methods| %> -" target="source"><%= methods["name"] %> -<% end %><%# values["methods"] %> -
-<% end %> -<% end %><%# values["method_list"] %> -<% end %> - -<% if sections["attributes"] then %> - - -
Arguments

- -<% sections["attributes"].each do |attributes| %> - -<% if attributes["rw"] then %> - -<% end %> -<% unless attributes["rw"] then %> - -<% end %> - - - -<% end %><%# values["attributes"] %> -
 [<%= attributes["rw"] %>] <%= attributes["name"] %><%= attributes["a_desc"] %>
-<% end %> -<% end %><%# values["sections"] %> -<% end %> - -<% if values["classlist"] then %> - - -
Modules

-<%= values["classlist"] %>
-<% end %> - - <%= template_include %> - - - - EOF - - FILE_PAGE = <<-EOF - - - - -
- -
File
<%= values["short_name"] %>		 - - - - - - - - -
Path:<%= values["full_path"] %> -<% if values["cvsurl"] then %> -  (">CVS) -<% end %> -
Modified:<%= values["dtm_modified"] %>
-

- EOF - - CLASS_PAGE = <<-EOF - - - - - -
- <%= values["classmod"] %>
<%= values["full_name"] %> - 		- - - - - -<% if values["parent"] then %> - - - - -<% end %> -
In: -<% values["infiles"].each do |infiles| %> -<%= href infiles["full_path_url"], infiles["full_path"] %> -<% if infiles["cvsurl"] then %> - (">CVS) -<% end %> -<% end %><%# values["infiles"] %> -
Parent: -<% if values["par_url"] then %> - " class="cyan"> -<% end %> -<%= values["parent"] %> -<% if values["par_url"] then %> - -<% end %> -
-

- EOF - - METHOD_LIST = <<-EOF -<% if values["includes"] then %> -
Uses

-
-<% values["includes"].each do |includes| %> - <%= href includes["aref"], includes["name"] %> -<% end %><%# values["includes"] %> -
-<% end %> - -<% if values["sections"] then %> -<% values["sections"].each do |sections| %> -<% if sections["method_list"] then %> -<% sections["method_list"].each do |method_list| %> -<% if method_list["methods"] then %> - - -
<%= method_list["type"] %> <%= method_list["category"] %> methods
-<% method_list["methods"].each do |methods| %> - - -
-"> -<%= methods["name"] %><%= methods["params"] %> -<% if methods["codeurl"] then %> -" target="source" class="srclink">src -<% end %> -
-<% if method_list["m_desc"] then %> -
-<%= method_list["m_desc"] %> -
-<% end %> -<% end %><%# method_list["methods"] %> -<% end %> -<% end %><%# sections["method_list"] %> -<% end %> -<% end %><%# values["sections"] %> -<% end %> - EOF - - SRC_PAGE = <<-EOF - -<%= values["title"] %> -"> - - - -
<%= values["code"] %>
- - + +.srcbut { float: right } EOF - FR_INDEX_BODY = %{ -<%= template_include %> + INDEX_STYLE = <<-EOF +body { + background-color: #bbbbbb; + font-family: #{FONTS}; + font-size: 11px; + font-style: normal; + line-height: 14px; + color: #000040; } - FILE_INDEX = <<-EOF - - -"> - - - - - -<% values["entries"].each do |entries| %> -"><%= entries["name"] %>
-<% end %><%# values["entries"] %> - - EOF + FACTORY = RDoc::Generator::HTML:: + KilmerFactory.new(:central_css => CENTRAL_STYLE, + :index_css => INDEX_STYLE, + :method_list_heading => "Subroutines and Functions", + :class_and_module_list_heading => "Classes and Modules", + :attribute_list_heading => "Arguments") - CLASS_INDEX = FILE_INDEX - METHOD_INDEX = FILE_INDEX + STYLE = FACTORY.get_STYLE() - INDEX = <<-EOF - - - <%= values["title"] %> - "> - + METHOD_LIST = FACTORY.get_METHOD_LIST() + + BODY = FACTORY.get_BODY() + + FILE_PAGE = FACTORY.get_FILE_PAGE() - - - - - - - - " name="docwin"> - - - - <body bgcolor="#BBBBBB"> - Click <a href="html/index.html">here</a> for a non-frames - version of this page. - </body> - - + CLASS_PAGE = FACTORY.get_CLASS_PAGE() - - EOF + SRC_PAGE = FACTORY.get_SRC_PAGE() - # Blank page to use as a target - BLANK = %{ - -} + FR_INDEX_BODY = FACTORY.get_FR_INDEX_BODY() - def write_extra_pages - template = TemplatePage.new(BLANK) - File.open("blank.html", "w") { |f| template.write_html_on(f, {}) } - end + FILE_INDEX = FACTORY.get_FILE_INDEX() -end + CLASS_INDEX = FACTORY.get_CLASS_INDEX() + + METHOD_INDEX = FACTORY.get_METHOD_INDEX() + INDEX = FACTORY.get_INDEX() + + def self.write_extra_pages(values) + FACTORY.write_extra_pages(values) + end +end diff --git a/lib/rdoc/generator/html/html.rb b/lib/rdoc/generator/html/html.rb index 1ab90c6264..823d8056e7 100644 --- a/lib/rdoc/generator/html/html.rb +++ b/lib/rdoc/generator/html/html.rb @@ -1,15 +1,17 @@ require 'rdoc/generator/html' -require 'rdoc/generator/html/one_page_html' +require 'rdoc/generator/html/common' ## # = CSS2 RDoc HTML template # -# This is a template for RDoc that uses XHTML 1.0 Transitional and dictates a +# This is a template for RDoc that uses XHTML 1.0 Strict and dictates a # bit more of the appearance of the output to cascading stylesheets than the # default. It was designed for clean inline code display, and uses DHTMl to # toggle the visibility of each method's source with each click on the # '[source]' link. # +# This template *also* forms the basis of the frameless template. +# # == Authors # # * Michael Granger @@ -23,34 +25,54 @@ require 'rdoc/generator/html/one_page_html' module RDoc::Generator::HTML::HTML + include RDoc::Generator::HTML::Common + FONTS = "Verdana,Arial,Helvetica,sans-serif" STYLE = <<-EOF body { - font-family: Verdana,Arial,Helvetica,sans-serif; - font-size: 90%; - margin: 0; - margin-left: 40px; - padding: 0; - background: white; + font-family: #{FONTS}; + font-size: 90%; + margin: 0; + margin-left: 40px; + padding: 0; + background: white; + color: black; +} + +h1, h2, h3, h4 { + margin: 0; + background: transparent; +} + +h1 { + font-size: 150%; } -h1,h2,h3,h4 { margin: 0; color: #efefef; background: transparent; } -h1 { font-size: 150%; } -h2,h3,h4 { margin-top: 1em; } +h2,h3,h4 { + margin-top: 1em; +} -a { background: #eef; color: #039; text-decoration: none; } -a:hover { background: #039; color: #eef; } +:link, :visited { + background: #eef; + color: #039; + text-decoration: none; +} + +:link:hover, :visited:hover { + background: #039; + color: #eef; +} /* Override the base stylesheet's Anchor inside a table cell */ -td > a { +td > :link, td > :visited { background: transparent; color: #039; text-decoration: none; } /* and inside a section title */ -.section-title > a { +.section-title > :link, .section-title > :visited { background: transparent; color: #eee; text-decoration: none; @@ -58,181 +80,255 @@ td > a { /* === Structural elements =================================== */ -div#index { - margin: 0; - margin-left: -40px; - padding: 0; - font-size: 90%; +.index { + margin: 0; + margin-left: -40px; + padding: 0; + font-size: 90%; } - -div#index a { - margin-left: 0.7em; +.index :link, .index :visited { + margin-left: 0.7em; } -div#index .section-bar { - margin-left: 0px; - padding-left: 0.7em; - background: #ccc; - font-size: small; +.index .section-bar { + margin-left: 0px; + padding-left: 0.7em; + background: #ccc; + font-size: small; } - -div#classHeader, div#fileHeader { - width: auto; - color: white; - padding: 0.5em 1.5em 0.5em 1.5em; - margin: 0; - margin-left: -40px; - border-bottom: 3px solid #006; +#classHeader, #fileHeader { + width: auto; + color: white; + padding: 0.5em 1.5em 0.5em 1.5em; + margin: 0; + margin-left: -40px; + border-bottom: 3px solid #006; } -div#classHeader a, div#fileHeader a { - background: inherit; - color: white; +#classHeader :link, #fileHeader :link, +#classHeader :visited, #fileHeader :visited { + background: inherit; + color: white; } -div#classHeader td, div#fileHeader td { - background: inherit; - color: white; +#classHeader td, #fileHeader td { + background: inherit; + color: white; } - -div#fileHeader { - background: #057; +#fileHeader { + background: #057; } -div#classHeader { - background: #048; +#classHeader { + background: #048; } - .class-name-in-header { font-size: 180%; font-weight: bold; } - -div#bodyContent { - padding: 0 1.5em 0 1.5em; +#bodyContent { + padding: 0 1.5em 0 1.5em; } -div#description { - padding: 0.5em 1.5em; - background: #efefef; - border: 1px dotted #999; +#description { + padding: 0.5em 1.5em; + background: #efefef; + border: 1px dotted #999; } -div#description h1,h2,h3,h4,h5,h6 { - color: #125;; - background: transparent; +#description h1, #description h2, #description h3, +#description h4, #description h5, #description h6 { + color: #125; + background: transparent; } -div#validator-badges { - text-align: center; +#validator-badges { + text-align: center; } -div#validator-badges img { border: 0; } -div#copyright { - color: #333; - background: #efefef; - font: 0.75em sans-serif; - margin-top: 5em; - margin-bottom: 0; - padding: 0.5em 2em; +#validator-badges img { + border: 0; } +#copyright { + color: #333; + background: #efefef; + font: 0.75em sans-serif; + margin-top: 5em; + margin-bottom: 0; + padding: 0.5em 2em; +} /* === Classes =================================== */ table.header-table { - color: white; - font-size: small; + color: white; + font-size: small; } .type-note { - font-size: small; - color: #DEDEDE; + font-size: small; + color: #dedede; } -.xxsection-bar { - background: #eee; - color: #333; - padding: 3px; +.section-bar { + color: #333; + border-bottom: 1px solid #999; + margin-left: -20px; } -.section-bar { - color: #333; - border-bottom: 1px solid #999; - margin-left: -20px; +.section-title { + background: #79a; + color: #eee; + padding: 3px; + margin-top: 2em; + margin-left: -30px; + border: 1px solid #999; } +.top-aligned-row { + vertical-align: top +} -.section-title { - background: #79a; - color: #eee; - padding: 3px; - margin-top: 2em; - margin-left: -30px; - border: 1px solid #999; +.bottom-aligned-row { + vertical-align: bottom } -.top-aligned-row { vertical-align: top } -.bottom-aligned-row { vertical-align: bottom } +#diagram img { + border: 0; +} /* --- Context section classes ----------------------- */ .context-row { } -.context-item-name { font-family: monospace; font-weight: bold; color: black; } -.context-item-value { font-size: small; color: #448; } -.context-item-desc { color: #333; padding-left: 2em; } + +.context-item-name { + font-family: monospace; + font-weight: bold; + color: black; +} + +.context-item-value { + font-size: small; + color: #448; +} + +.context-item-desc { + color: #333; + padding-left: 2em; +} /* --- Method classes -------------------------- */ + .method-detail { - background: #efefef; - padding: 0; - margin-top: 0.5em; - margin-bottom: 1em; - border: 1px dotted #ccc; + background: #efefef; + padding: 0; + margin-top: 0.5em; + margin-bottom: 1em; + border: 1px dotted #ccc; } + .method-heading { color: black; background: #ccc; border-bottom: 1px solid #666; padding: 0.2em 0.5em 0 0.5em; } -.method-signature { color: black; background: inherit; } -.method-name { font-weight: bold; } -.method-args { font-style: italic; } -.method-description { padding: 0 0.5em 0 0.5em; } + +.method-signature { + color: black; + background: inherit; +} + +.method-name { + font-weight: bold; +} + +.method-args { + font-style: italic; +} + +.method-description { + padding: 0 0.5em 0 0.5em; +} /* --- Source code sections -------------------- */ -a.source-toggle { font-size: 90%; } +:link.source-toggle, :visited.source-toggle { + font-size: 90%; +} + div.method-source-code { - background: #262626; - color: #ffdead; - margin: 1em; - padding: 0.5em; - border: 1px dashed #999; - overflow: hidden; + background: #262626; + color: #ffdead; + margin: 1em; + padding: 0.5em; + border: 1px dashed #999; + overflow: auto; } -div.method-source-code pre { color: #ffdead; overflow: hidden; } +div.method-source-code pre { + color: #ffdead; +} /* --- Ruby keyword styles --------------------- */ -.standalone-code { background: #221111; color: #ffdead; overflow: hidden; } - -.ruby-constant { color: #7fffd4; background: transparent; } -.ruby-keyword { color: #00ffff; background: transparent; } -.ruby-ivar { color: #eedd82; background: transparent; } -.ruby-operator { color: #00ffee; background: transparent; } -.ruby-identifier { color: #ffdead; background: transparent; } -.ruby-node { color: #ffa07a; background: transparent; } -.ruby-comment { color: #b22222; font-weight: bold; background: transparent; } -.ruby-regexp { color: #ffa07a; background: transparent; } -.ruby-value { color: #7fffd4; background: transparent; } +.standalone-code { + background: #221111; + color: #ffdead; + overflow: auto; +} + +.ruby-constant { + color: #7fffd4; + background: transparent; +} + +.ruby-keyword { + color: #00ffff; + background: transparent; +} + +.ruby-ivar { + color: #eedd82; + background: transparent; +} + +.ruby-operator { + color: #00ffee; + background: transparent; +} + +.ruby-identifier { + color: #ffdead; + background: transparent; +} + +.ruby-node { + color: #ffa07a; + background: transparent; +} + +.ruby-comment { + color: #b22222; + font-weight: bold; + background: transparent; +} + +.ruby-regexp { + color: #ffa07a; + background: transparent; +} + +.ruby-value { + color: #7fffd4; + background: transparent; +} EOF @@ -240,15 +336,7 @@ EOF ### H E A D E R T E M P L A T E ##################################################################### - XHTML_PREAMBLE = <<-EOF -"?> - - EOF - - HEADER = XHTML_PREAMBLE + <<-EOF - + HEADER = XHTML_STRICT_PREAMBLE + HTML_ELEMENT + <<-EOF <%= values["title"] %> " /> @@ -281,7 +369,7 @@ EOF } // Make codeblocks hidden by default - document.writeln( "" ) + document.writeln( " - - -
<%= values["code"] %>
- - EOF - FR_INDEX_BODY = %{ -<%= template_include %> -} - - FILE_INDEX = <<-EOF - - -"> - - - - - -<% values["entries"].each do |entries| %> -"><%= entries["name"] %>
-<% end %><%# values["entries"] %> - - EOF + FACTORY = RDoc::Generator::HTML:: + KilmerFactory.new(:central_css => CENTRAL_STYLE, + :index_css => INDEX_STYLE) - CLASS_INDEX = FILE_INDEX - METHOD_INDEX = FILE_INDEX + STYLE = FACTORY.get_STYLE() - INDEX = <<-EOF - - - <%= values["title"] %> - "> - + METHOD_LIST = FACTORY.get_METHOD_LIST() + + BODY = FACTORY.get_BODY() + + FILE_PAGE = FACTORY.get_FILE_PAGE() - - - - - - -<% if values["inline_source"] then %> - " name="docwin"> -<% end %> -<% unless values["inline_source"] then %> - - " name="docwin"> - - -<% end %> - - <body bgcolor="white"> - Click <a href="html/index.html">here</a> for a non-frames - version of this page. - </body> - - + CLASS_PAGE = FACTORY.get_CLASS_PAGE() - - EOF + SRC_PAGE = FACTORY.get_SRC_PAGE() - # A blank page to use as a target - BLANK = %{ - -} + FR_INDEX_BODY = FACTORY.get_FR_INDEX_BODY() - def write_extra_pages - template = TemplatePage.new(BLANK) - File.open("blank.html", "w") { |f| template.write_html_on(f, {}) } - end + FILE_INDEX = FACTORY.get_FILE_INDEX() -end + CLASS_INDEX = FACTORY.get_CLASS_INDEX() + METHOD_INDEX = FACTORY.get_METHOD_INDEX() + + INDEX = FACTORY.get_INDEX() + + def self.write_extra_pages(values) + FACTORY.write_extra_pages(values) + end +end diff --git a/lib/rdoc/generator/html/kilmerfactory.rb b/lib/rdoc/generator/html/kilmerfactory.rb new file mode 100644 index 0000000000..ef6f3f3b4d --- /dev/null +++ b/lib/rdoc/generator/html/kilmerfactory.rb @@ -0,0 +1,427 @@ +require 'rdoc/generator/html' +require 'rdoc/generator/html/common' + +# +# This class generates Kilmer-style templates. Right now, +# rdoc is shipped with two such templates: +# * kilmer +# * hefss +# +# Kilmer-style templates use frames. The left side of the page has +# three frames stacked on top of each other: one lists +# files, one lists classes, and one lists methods. If source code +# is not inlined, an additional frame runs across the bottom of +# the page and will be used to display method source code. +# The central (and largest frame) display class and file +# pages. +# +# The constructor of this class accepts a Hash containing stylistic +# attributes. Then, a get_BLAH instance method of this class returns a +# value for the template's BLAH constant. get_BODY, for instance, returns +# the value of the template's BODY constant. +# +class RDoc::Generator::HTML::KilmerFactory + + include RDoc::Generator::HTML::Common + + # + # The contents of the stylesheet that should be used for the + # central frame (for the class and file pages). + # + # This must be specified in the Hash passed to the constructor. + # + attr_reader :central_css + + # + # The contents of the stylesheet that should be used for the + # index pages. + # + # This must be specified in the Hash passed to the constructor. + # + attr_reader :index_css + + # + # The heading that should be displayed before listing methods. + # + # If not supplied, this defaults to "Methods". + # + attr_reader :method_list_heading + + # + # The heading that should be displayed before listing classes and + # modules. + # + # If not supplied, this defaults to "Classes and Modules". + # + attr_reader :class_and_module_list_heading + + # + # The heading that should be displayed before listing attributes. + # + # If not supplied, this defaults to "Attributes". + # + attr_reader :attribute_list_heading + + # + # ====Description: + # This method constructs a KilmerFactory instance, which + # can be used to build Kilmer-style template classes. + # The +style_attributes+ argument is a Hash that contains the + # values of the classes attributes (Symbols mapped to Strings). + # + # ====Parameters: + # [style_attributes] + # A Hash describing the appearance of the Kilmer-style. + # + def initialize(style_attributes) + @central_css = style_attributes[:central_css] + if(!@central_css) + raise ArgumentError, "did not specify a value for :central_css" + end + + @index_css = style_attributes[:index_css] + if(!@index_css) + raise ArgumentError, "did not specify a value for :index_css" + end + + @method_list_heading = style_attributes[:method_list_heading] + if(!@method_list_heading) + @method_list_heading = "Methods" + end + + @class_and_module_list_heading = style_attributes[:class_and_module_list_heading] + if(!@class_and_module_list_heading) + @class_and_module_list_heading = "Classes and Modules" + end + + @attribute_list_heading = style_attributes[:attribute_list_heading] + if(!@attribute_list_heading) + @attribute_list_heading = "Attributes" + end + end + + def get_STYLE + return @central_css + end + + def get_METHOD_LIST + return %{ +<% if values["diagram"] then %> +
+
+<%= values["diagram"] %> +
+
+<% end %> + +<% if values["description"] then %> +
<%= values["description"] %>
+<% end %> + +<% if values["requires"] then %> + + +
Required files

+
+<% values["requires"].each do |requires| %> +<%= href requires["aref"], requires["name"] %> +<% end %><%# values["requires"] %> +
+<% end %> + +<% if values["methods"] then %> + + +
#{@method_list_heading}

+
+<% values["methods"].each do |methods| %> +<%= href methods["aref"], methods["name"] %>, +<% end %><%# values["methods"] %> +
+<% end %> + +<% if values["includes"] then %> +
Included modules

+
+<% values["includes"].each do |includes| %> + <%= href includes["aref"], includes["name"] %> +<% end %><%# values["includes"] %> +
+<% end %> + +<% values["sections"].each do |sections| %> +
+<% if sections["sectitle"] then %> +

"><%= sections["sectitle"] %>

+<% if sections["seccomment"] then %> +
+ <%= sections["seccomment"] %> +
+<% end %> +<% end %> +<% if sections["attributes"] then %> + + +
#{@attribute_list_heading}

+ +<% sections["attributes"].each do |attributes| %> + +<% if attributes["rw"] then %> + +<% end %> +<% unless attributes["rw"] then %> + +<% end %> + + + +<% end %><%# sections["attributes"] %> +
 [<%= attributes["rw"] %>] <%= attributes["name"] %><%= attributes["a_desc"] %>
+<% end %> + +<% if sections["classlist"] then %> + + +
#{@class_and_module_list_heading}

+<%= sections["classlist"] %>
+<% end %> + +<% if sections["method_list"] then %> +<% sections["method_list"].each do |method_list| %> +<% if method_list["methods"] then %> + + +
<%= method_list["type"] %> <%= method_list["category"] %> methods
+<% method_list["methods"].each do |methods| %> + + +
+"> +<% if methods["callseq"] then %> +<%= methods["callseq"] %> +<% end %> +<% unless methods["callseq"] then %> + <%= methods["name"] %><%= methods["params"] %> +<% end %> + +<% if methods["codeurl"] then %> +" target="source" class="srclink">src +<% end %> +
+<% if methods["m_desc"] then %> +
+<%= methods["m_desc"] %> +
+<% end %> +<% if methods["aka"] then %> +
+This method is also aliased as +<% methods["aka"].each do |aka| %> +"><%= methods["name"] %> +<% end %><%# methods["aka"] %> +
+<% end %> +<% if methods["sourcecode"] then %> +
+<%= methods["sourcecode"] %>
+
+<% end %> +<% end %><%# method_list["methods"] %> +<% end %> +<% end %><%# sections["method_list"] %> +<% end %> + +<% end %><%# values["sections"] %> +
+} + end + + def get_BODY + return XHTML_STRICT_PREAMBLE + HTML_ELEMENT + %{ + + <%= values["title"] %> + " /> + " type="text/css" media="screen" /> + + + +
+<%= template_include %> + +#{get_METHOD_LIST()} +
+ + +} + end + +def get_FILE_PAGE + return %{ + + + + +
+ +
File
<%= values["short_name"] %>		 + + + + + + + + +
Path:<%= values["full_path"] %> +<% if values["cvsurl"] then %> +  (">CVS) +<% end %> +
Modified:<%= values["dtm_modified"] %>
+

+} +end + +def get_CLASS_PAGE + return %{ + + + + + +
+ <%= values["classmod"] %>
<%= values["full_name"] %> + 		+ + + + + +<% if values["parent"] then %> + + + + +<% end %> +
In: +<% values["infiles"].each do |infiles| %> +<%= href infiles["full_path_url"], infiles["full_path"] %> +<% if infiles["cvsurl"] then %> + (">CVS) +<% end %> +<% end %><%# values["infiles"] %> +
Parent: +<% if values["par_url"] then %> + " class="cyan"> +<% end %> +<%= values["parent"] %> +<% if values["par_url"] then %> + +<% end %> +
+

+} +end + +def get_SRC_PAGE + return XHTML_STRICT_PREAMBLE + HTML_ELEMENT + %{ +<%= values["title"] %> +" /> +" type="text/css" media="screen" /> + + +
<%= values["code"] %>
+ + +} +end + +def get_FR_INDEX_BODY + return %{<%= template_include %>} +end + +def get_FILE_INDEX + return XHTML_STRICT_PREAMBLE + HTML_ELEMENT + %{ + +<%= values["title"] %> +" /> + + + + +
+ +<% values["entries"].each do |entries| %> +"><%= entries["name"] %>
+<% end %><%# values["entries"] %> +
+ +} +end + +def get_CLASS_INDEX + return get_FILE_INDEX +end + +def get_METHOD_INDEX + return get_FILE_INDEX +end + +def get_INDEX + return XHTML_FRAME_PREAMBLE + HTML_ELEMENT + %{ + + <%= values["title"] %> + " /> + + + + + + + + +<% if values["inline_source"] then %> + " name="docwin" /> +<% end %> +<% unless values["inline_source"] then %> + + " name="docwin" /> + + +<% end %> + + + +} +end + +def get_BLANK + # This will be displayed in the source code frame before + # any source code has been selected. + return XHTML_STRICT_PREAMBLE + HTML_ELEMENT + %{ + + Source Code Frame <%= values["title_suffix"] %> + " /> + " type="text/css" media="screen" /> + + + + +} +end + +def write_extra_pages(values) + template = RDoc::TemplatePage.new(get_BLANK()) + File.open("blank.html", "w") { |f| template.write_html_on(f, values) } +end + +end diff --git a/lib/rdoc/generator/html/one_page_html.rb b/lib/rdoc/generator/html/one_page_html.rb index c4dd95529d..51ae32351a 100644 --- a/lib/rdoc/generator/html/one_page_html.rb +++ b/lib/rdoc/generator/html/one_page_html.rb @@ -1,7 +1,10 @@ require 'rdoc/generator/html' +require 'rdoc/generator/html/common' module RDoc::Generator::HTML::ONE_PAGE_HTML + include RDoc::Generator::HTML::Common + CONTENTS_XML = <<-EOF <% if defined? classes and classes["description"] then %> <%= classes["description"] %> @@ -76,16 +79,14 @@ module RDoc::Generator::HTML::ONE_PAGE_HTML <% end %> EOF - ONE_PAGE = %{ - - + ONE_PAGE = XHTML_STRICT_PREAMBLE + HTML_ELEMENT + %{ <%= values["title"] %> " /> <% values["files"].each do |files| %> -

File: <%= files["short_name"] %>

+

File: "><%= files["short_name"] %>

@@ -97,7 +98,7 @@ module RDoc::Generator::HTML::ONE_PAGE_HTML

Classes

<% values["classes"].each do |classes| %> <% if classes["parent"] then %> -

<%= classes["classmod"] %> <%= classes["full_name"] %> < <%= href classes["par_url"], classes["parent"] %>

+

<%= classes["classmod"] %> "><%= classes["full_name"] %> < <%= href classes["par_url"], classes["parent"] %>

<% end %> <% unless classes["parent"] then %>

<%= classes["classmod"] %> <%= classes["full_name"] %>

diff --git a/lib/rdoc/generator/texinfo.rb b/lib/rdoc/generator/texinfo.rb index 0b79820228..70db875af9 100644 --- a/lib/rdoc/generator/texinfo.rb +++ b/lib/rdoc/generator/texinfo.rb @@ -3,13 +3,10 @@ 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 + class TEXINFO # What should the .info file be named by default? DEFAULT_INFO_FILENAME = 'rdoc.info' @@ -26,8 +23,8 @@ module RDoc # Generate the +texinfo+ files def generate(toplevels) @toplevels = toplevels - @files, @classes = ::RDoc::Generator::Context.build_indicies(@toplevels, - @options) + @files, @classes = ::RDoc::Generator::Context.build_indices(@toplevels, + @options) (@files + @classes).each { |x| x.value_hash } diff --git a/lib/rdoc/generator/texinfo/class.texinfo.erb b/lib/rdoc/generator/texinfo/class.texinfo.erb index 07f17eaef2..74ecc59f7d 100644 --- a/lib/rdoc/generator/texinfo/class.texinfo.erb +++ b/lib/rdoc/generator/texinfo/class.texinfo.erb @@ -38,7 +38,7 @@ Methods <% (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 %> +<% end # if section["method_list"] %> <% end # @v['class']["sections"] %> <% end %> diff --git a/lib/rdoc/generator/xml.rb b/lib/rdoc/generator/xml.rb index 3335f2ce7c..0d4c5a7ea1 100644 --- a/lib/rdoc/generator/xml.rb +++ b/lib/rdoc/generator/xml.rb @@ -34,15 +34,15 @@ class RDoc::Generator::XML < RDoc::Generator::HTML ## # Generate: # - # * a list of HtmlFile objects for each TopLevel object. - # * a list of HtmlClass objects for each first level + # * a list of File objects for each TopLevel object. + # * a list of Class objects for each first level # class or module in the TopLevel objects # * a complete list of all hyperlinkable terms (file, # class, module, and method names) def build_indices @info.each do |toplevel| - @files << RDoc::Generator::HtmlFile.new(toplevel, @options, RDoc::Generator::FILE_DIR) + @files << RDoc::Generator::File.new(toplevel, @options, RDoc::Generator::FILE_DIR) end RDoc::TopLevel.all_classes_and_modules.each do |cls| @@ -51,7 +51,7 @@ class RDoc::Generator::XML < RDoc::Generator::HTML end def build_class_list(from, html_file, class_dir) - @classes << RDoc::Generator::HtmlClass.new(from, html_file, class_dir, @options) + @classes << RDoc::Generator::Class.new(from, html_file, class_dir, @options) from.each_classmodule do |mod| build_class_list(mod, html_file, class_dir) end @@ -68,9 +68,6 @@ class RDoc::Generator::XML < RDoc::Generator::HTML 'classes' => gen_into(@classes) } - # this method is defined in the template file - write_extra_pages if defined? write_extra_pages - template = RDoc::TemplatePage.new @template::ONE_PAGE if @options.op_name diff --git a/lib/rdoc/generator/xml/xml.rb b/lib/rdoc/generator/xml/xml.rb index ffb1329c4e..4b54e7350f 100644 --- a/lib/rdoc/generator/xml/xml.rb +++ b/lib/rdoc/generator/xml/xml.rb @@ -17,11 +17,23 @@ module RDoc::Generator::XML::XML href="<%= requires["aref"] %>" <% end %> /> -<% end # files["requires"] %> +<% end %><%# files["requires"] %> <% end %> <% if defined? classes and classes["sections"] then %> <% classes["sections"].each do |sections| %> +<% if sections["constants"] then %> + +<% sections["constants"].each do |constant| %> + "> +<% if constant["value"] then %> + <%= constant["value"] %> +<% end %> + <%= constant["a_desc"] %> + +<% end %><%# sections["constants"] %> + +<% end %> <% if sections["attributes"] then %> <% sections["attributes"].each do |attributes| %> @@ -31,7 +43,7 @@ module RDoc::Generator::XML::XML <% end %> <%= attributes["a_desc"] %> -<% end # sections["attributes"] %> +<% end %><%# sections["attributes"] %> <% end %> <% if sections["method_list"] then %> @@ -52,12 +64,12 @@ module RDoc::Generator::XML::XML <% 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 %> <% if defined? classes and classes["includes"] then %> @@ -67,7 +79,7 @@ module RDoc::Generator::XML::XML href="<%= includes["aref"] %>" <% end %> /> -<% end # classes["includes"] %> +<% end %><%# classes["includes"] %> <% end %> @@ -84,7 +96,7 @@ module RDoc::Generator::XML::XML } + CONTENTS_XML + %{ -<% end # values["files"] %> +<% end %><%# values["files"] %> <% values["classes"].each do |classes| %> @@ -94,7 +106,7 @@ module RDoc::Generator::XML::XML <% classes["infiles"].each do |infiles| %> <%= href infiles["full_path_url"], infiles["full_path"] %> -<% end # classes["infiles"] %> +<% end %><%# classes["infiles"] %> <% end %> <% if classes["parent"] then %> @@ -103,7 +115,7 @@ module RDoc::Generator::XML::XML } + CONTENTS_XML + %{ > -<% end # values["classes"] %> +<% end %><%# values["classes"] %> } diff --git a/lib/rdoc/markup.rb b/lib/rdoc/markup.rb index 0e1b596255..9d22b38946 100644 --- a/lib/rdoc/markup.rb +++ b/lib/rdoc/markup.rb @@ -20,101 +20,6 @@ require 'rdoc' # RDoc::Markup could be the basis for formatting RDoc style comment blocks, # Wiki entries, and online FAQs. # -# = Basic Formatting -# -# * RDoc::Markup looks for a document's natural left margin. This is -# used as the initial margin for the document. -# -# * Consecutive lines starting at this margin are considered to be a -# paragraph. -# -# * If a paragraph starts with a "*", "-", or with ".", then it is -# taken to be the start of a list. The margin in increased to be the first -# non-space following the list start flag. Subsequent lines should be -# indented to this \new margin until the list ends. For example: -# -# * this is a list with three paragraphs in -# the first item. This is the first paragraph. -# -# And this is the second paragraph. -# -# 1. This is an indented, numbered list. -# 2. This is the second item in that list -# -# This is the third conventional paragraph in the -# first list item. -# -# * This is the second item in the original list -# -# * You can also construct labeled lists, sometimes called description -# or definition lists. Do this by putting the label in square brackets -# and indenting the list body: -# -# [cat] a small furry mammal -# that seems to sleep a lot -# -# [ant] a little insect that is known -# to enjoy picnics -# -# A minor variation on labeled lists uses two colons to separate the -# label from the list body: -# -# cat:: a small furry mammal -# that seems to sleep a lot -# -# ant:: a little insect that is known -# to enjoy picnics -# -# This latter style guarantees that the list bodies' left margins are -# aligned: think of them as a two column table. -# -# * Any line that starts to the right of the current margin is treated -# as verbatim text. This is useful for code listings. The example of a -# list above is also verbatim text. -# -# * A line starting with an equals sign (=) is treated as a -# heading. Level one headings have one equals sign, level two headings -# have two,and so on. -# -# * A line starting with three or more hyphens (at the current indent) -# generates a horizontal rule. The more hyphens, the thicker the rule -# (within reason, and if supported by the output device) -# -# * You can use markup within text (except verbatim) to change the -# appearance of parts of that text. Out of the box, RDoc::Markup -# supports word-based and general markup. -# -# Word-based markup uses flag characters around individual words: -# -# [\*word*] displays word in a *bold* font -# [\_word_] displays word in an _emphasized_ font -# [\+word+] displays word in a +code+ font -# -# General markup affects text between a start delimiter and and end -# delimiter. Not surprisingly, these delimiters look like HTML markup. -# -# [\text...] displays word in a *bold* font -# [\text...] displays word in an _emphasized_ font -# [\text...] displays word in an _emphasized_ font -# [\text...] displays word in a +code+ font -# -# Unlike conventional Wiki markup, general markup can cross line -# boundaries. You can turn off the interpretation of markup by -# preceding the first character with a backslash, so \\\bold -# text and \\\*bold* produce \bold text and \*bold* -# respectively. -# -# * Hyperlinks to the web starting http:, mailto:, ftp:, or www. are -# recognized. An HTTP url that references an external image file is -# converted into an inline . Hyperlinks starting 'link:' are -# assumed to refer to local files whose path is relative to the --op -# directory. -# -# Hyperlinks can also be of the form label[url], in which -# case the label is used in the displayed text, and url is -# used as the target. If label contains multiple words, -# put it in braces: {multi word label}[url]. -# # == Synopsis # # This code converts +input_string+ to HTML. The conversion takes place in diff --git a/lib/rdoc/markup/inline.rb b/lib/rdoc/markup/inline.rb index ee77679a11..46c9b5822c 100644 --- a/lib/rdoc/markup/inline.rb +++ b/lib/rdoc/markup/inline.rb @@ -47,7 +47,7 @@ class RDoc::Markup class AttrChanger def to_s - "Attr: +#{Attribute.as_string(@turn_on)}/-#{Attribute.as_string(@turn_on)}" + "Attr: +#{Attribute.as_string(turn_on)}/-#{Attribute.as_string(turn_on)}" end end diff --git a/lib/rdoc/markup/to_html.rb b/lib/rdoc/markup/to_html.rb index ca29373db1..dce7a69b12 100644 --- a/lib/rdoc/markup/to_html.rb +++ b/lib/rdoc/markup/to_html.rb @@ -57,7 +57,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter ## # Generate a hyperlink for url, labeled with text. Handle the - # special cases for img: and link: described under handle_special_HYPEDLINK + # special cases for img: and link: described under handle_special_HYPERLINK def gen_url(url, text) if url =~ /([A-Za-z]+):(.*)/ then @@ -304,9 +304,12 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter # some of these patterns are taken from SmartyPants... def convert_string_fancy(item) - # convert -- to em-dash, (-- to en-dash) - item.gsub(/---?/, '—'). #gsub(/--/, '–'). + # convert ampersand before doing anything else + item.gsub(/&/, '&'). + # convert -- to em-dash, (-- to en-dash) + gsub(/---?/, '—'). #gsub(/--/, '–'). + # convert ... to elipsis (and make sure .... becomes .) gsub(/\.\.\.\./, '.…').gsub(/\.\.\./, '…'). @@ -318,15 +321,15 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter gsub(/'/, '‘'). # convert double closing quote - gsub(%r{([^ \t\r\n\[\{\(])\'(?=\W)}, '\1”'). # } + gsub(%r{([^ \t\r\n\[\{\(])\"(?=\W)}, '\1”'). # } # convert double opening quote - gsub(/'/, '“'). + gsub(/"/, '“'). # convert copyright gsub(/\(c\)/, '©'). - # convert and registered trademark + # convert registered trademark gsub(/\(r\)/, '®') end diff --git a/lib/rdoc/markup/to_html_crossref.rb b/lib/rdoc/markup/to_html_crossref.rb index a6f29c5c2c..dc64b30da1 100644 --- a/lib/rdoc/markup/to_html_crossref.rb +++ b/lib/rdoc/markup/to_html_crossref.rb @@ -9,6 +9,68 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml attr_accessor :context + # Regular expressions to match class and method references. + # + # 1.) There can be a '\' in front of text to suppress + # any cross-references (note, however, that the single '\' + # is written as '\\\\' in order to escape it twice, once + # in the Ruby String literal and once in the regexp). + # 2.) There can be a '::' in front of class names to reference + # from the top-level namespace. + # 3.) The method can be followed by parenthesis, + # which may or may not have things inside (this + # apparently is allowed for Fortran 95, but I also think that this + # is a good idea for Ruby, as it is very reasonable to want to + # reference a call with arguments). + # + # NOTE: In order to support Fortran 95 properly, the [A-Z] below + # should be changed to [A-Za-z]. This slows down rdoc significantly, + # however, and the Fortran 95 support is broken in any case due to + # the return in handle_special_CROSSREF if the token consists + # entirely of lowercase letters. + # + # The markup/cross-referencing engine needs a rewrite for + # Fortran 95 to be supported properly. + CLASS_REGEXP_STR = '\\\\?((?:\:{2})?[A-Z]\w*(?:\:\:\w+)*)' + METHOD_REGEXP_STR = '(\w+[!?=]?)(?:\([\.\w+\*\/\+\-\=\<\>]*\))?' + + # Regular expressions matching text that should potentially have + # cross-reference links generated are passed to add_special. + # Note that these expressions are meant to pick up text for which + # cross-references have been suppressed, since the suppression + # characters are removed by the code that is triggered. + CROSSREF_REGEXP = /( + # A::B::C.meth + #{CLASS_REGEXP_STR}[\.\#]#{METHOD_REGEXP_STR} + + # Stand-alone method (proceeded by a #) + | \\?\##{METHOD_REGEXP_STR} + + # A::B::C + # The stuff after CLASS_REGEXP_STR is a + # nasty hack. CLASS_REGEXP_STR unfortunately matches + # words like dog and cat (these are legal "class" + # names in Fortran 95). When a word is flagged as a + # potential cross-reference, limitations in the markup + # engine suppress other processing, such as typesetting. + # This is particularly noticeable for contractions. + # In order that words like "can't" not + # be flagged as potential cross-references, only + # flag potential class cross-references if the character + # after the cross-referece is a space or sentence + # punctuation. + | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;]|\z) + + # Things that look like filenames + # The key thing is that there must be at least + # one special character (period, slash, or + # underscore). + | [\/\w]+[_\/\.][\w\/\.]+ + + # Things that have markup suppressed + | \\[^\s] + )/x + ## # We need to record the html path of our caller so we can generate # correct relative paths for any hyperlinks that we find @@ -17,18 +79,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml raise ArgumentError, 'from_path cannot be nil' if from_path.nil? super() - # class names, variable names, or instance variables - @markup.add_special(/( - # A::B.meth(**) (for operator in Fortran95) - \w+(::\w+)*[.\#]\w+(\([\.\w+\*\/\+\-\=\<\>]+\))? - # meth(**) (for operator in Fortran95) - | \#\w+(\([.\w\*\/\+\-\=\<\>]+\))? - | \b([A-Z]\w*(::\w+)*[.\#]\w+) # A::B.meth - | \b([A-Z]\w+(::\w+)*) # A::B - | \#\w+[!?=]? # #meth_name - | \\?\b\w+([_\/\.]+\w+)*[!?=]? # meth_name - )/x, - :CROSSREF) + @markup.add_special(CROSSREF_REGEXP, :CROSSREF) @from_path = from_path @context = context @@ -48,6 +99,9 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml def handle_special_CROSSREF(special) name = special.text + # This ensures that words entirely consisting of lowercase letters will + # not have cross-references generated (to suppress lots of + # erroneous cross-references to "new" in text, for instance) return name if name =~ /\A[a-z]*\z/ return @seen[name] if @seen.include? name @@ -70,14 +124,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml # (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 - end - - if !ref and - /([A-Za-z][\w:]*)[.\#](\w+(\([\.\w+\*\/\+\-\=\<\>]+\))?)/ =~ lookup then + if /#{CLASS_REGEXP_STR}[\.\#]#{METHOD_REGEXP_STR}/ =~ lookup then container = $1 method = $2 ref = @context.find_symbol container, method @@ -99,4 +146,3 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml end end - diff --git a/lib/rdoc/markup/to_texinfo.rb b/lib/rdoc/markup/to_texinfo.rb index 533d3e34a0..65a1608c4d 100644 --- a/lib/rdoc/markup/to_texinfo.rb +++ b/lib/rdoc/markup/to_texinfo.rb @@ -30,7 +30,7 @@ class RDoc::Markup::ToTexInfo < RDoc::Markup::Formatter def accept_heading(attributes, text) heading = ['@majorheading', '@chapheading'][text.head_level - 1] || '@heading' - @text << "#{heading}{#{format(text)}}" + @text << "#{heading} #{format(text)}" end def accept_list_start(attributes, text) diff --git a/lib/rdoc/options.rb b/lib/rdoc/options.rb index d683a14022..1d92bd4748 100644 --- a/lib/rdoc/options.rb +++ b/lib/rdoc/options.rb @@ -184,7 +184,7 @@ class RDoc::Options @css = nil @webcvs = nil - @charset = 'iso-8859-1' + @charset = 'utf-8' end ## @@ -196,6 +196,7 @@ class RDoc::Options opts = OptionParser.new do |opt| opt.program_name = File.basename $0 opt.version = RDoc::VERSION + opt.release = nil opt.summary_indent = ' ' * 4 opt.banner = <<-EOF Usage: #{opt.program_name} [options] [names...] @@ -257,7 +258,7 @@ Usage: #{opt.program_name} [options] [names...] opt.separator nil opt.on("--charset=CHARSET", "-c", - "Specifies the HTML character-set.") do |value| + "Specifies the output HTML character-set.") do |value| @charset = value end @@ -283,9 +284,7 @@ Usage: #{opt.program_name} [options] [names...] opt.on("--exclude=PATTERN", "-x", Regexp, "Do not process files or directories", - "matching PATTERN. Files given explicitly", - "on the command line will never be", - "excluded.") do |value| + "matching PATTERN.") do |value| @exclude << value end diff --git a/lib/rdoc/parser.rb b/lib/rdoc/parser.rb index 794fad00e9..6855cfcfc5 100644 --- a/lib/rdoc/parser.rb +++ b/lib/rdoc/parser.rb @@ -62,11 +62,32 @@ class RDoc::Parser true end + ## + # Shamelessly stolen from the ptools gem (since RDoc cannot depend on + # the gem). + + def self.binary?(file) + s = (File.read(file, File.stat(file).blksize) || "").split(//) + ((s.size - s.grep(" ".."~").size) / s.size.to_f) > 0.30 + end + private_class_method :binary? + ## # 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 + parser = RDoc::Parser.parsers.find { |regexp,| regexp =~ file_name }.last + + # + # The default parser should *NOT* parse binary files. + # + if parser == RDoc::Parser::Simple then + if binary? file_name then + return nil + end + end + + return parser end ## diff --git a/lib/rdoc/parser/c.rb b/lib/rdoc/parser/c.rb index 43bb767da9..a5b06c2b04 100644 --- a/lib/rdoc/parser/c.rb +++ b/lib/rdoc/parser/c.rb @@ -120,7 +120,7 @@ class RDoc::Parser::C < RDoc::Parser @stats.add_alias as end - end + end def do_classes @content.scan(/(\w+)\s* = \s*rb_define_module\s*\(\s*"(\w+)"\s*\)/mx) do @@ -155,7 +155,7 @@ class RDoc::Parser::C < RDoc::Parser \( \s*(\w+), \s*"(\w+)", - \s*(\w+)\s* + \s*([\w\*\s\(\)\.\->]+)\s* # for SWIG \s*\)/mx) do |var_name, in_module, class_name, parent| handle_class_module(var_name, "class", class_name, parent, in_module) end @@ -251,7 +251,7 @@ class RDoc::Parser::C < RDoc::Parser handle_method("method", "rb_mFileTest", meth_name, meth_body, param_count) handle_method("singleton_method", "rb_cFile", meth_name, meth_body, param_count) end - end + end def find_attr_comment(attr_name) if @content =~ %r{((?>/\*.*?\*/\s+)) @@ -267,10 +267,10 @@ class RDoc::Parser::C < RDoc::Parser ## # Find the C code corresponding to a Ruby method - def find_body(meth_name, meth_obj, body, quiet = false) + def find_body(class_name, meth_name, meth_obj, body, quiet = false) case body - when %r"((?>/\*.*?\*/\s*))(?:static\s+)?VALUE\s+#{meth_name} - \s*(\([^)]*\))\s*\{.*?^\}"xm + when %r"((?>/\*.*?\*/\s*)*)(?:(?:static|SWIGINTERN)\s+)?(?:intern\s+)?VALUE\s+#{meth_name} + \s*(\([^)]*\))([^;]|$)"xm comment, params = $1, $2 body_text = $& @@ -279,9 +279,7 @@ class RDoc::Parser::C < RDoc::Parser # see if we can find the whole body re = Regexp.escape(body_text) + '[^(]*^\{.*?^\}' - if Regexp.new(re, Regexp::MULTILINE).match(body) - body_text = $& - end + body_text = $& if /#{re}/m =~ body # The comment block may have been overridden with a 'Document-method' # block. This happens in the interpreter when multiple methods are @@ -289,7 +287,7 @@ class RDoc::Parser::C < RDoc::Parser # distinct (for example Kernel.hash and Kernel.object_id share the same # implementation - override_comment = find_override_comment(meth_obj.name) + override_comment = find_override_comment(class_name, meth_obj.name) comment = override_comment if override_comment find_modifiers(comment, meth_obj) if comment @@ -300,18 +298,18 @@ class RDoc::Parser::C < RDoc::Parser meth_obj.comment = mangle_comment(comment) when %r{((?>/\*.*?\*/\s*))^\s*\#\s*define\s+#{meth_name}\s+(\w+)}m comment = $1 - find_body($2, meth_obj, body, true) + find_body(class_name, $2, meth_obj, body, true) find_modifiers(comment, meth_obj) meth_obj.comment = mangle_comment(comment) + meth_obj.comment when %r{^\s*\#\s*define\s+#{meth_name}\s+(\w+)}m - unless find_body($1, meth_obj, body, true) + unless find_body(class_name, $1, meth_obj, body, true) warn "No definition for #{meth_name}" unless @options.quiet return false end else # No body, but might still have an override comment - comment = find_override_comment(meth_obj.name) + comment = find_override_comment(class_name, meth_obj.name) if comment find_modifiers(comment, meth_obj) @@ -367,10 +365,10 @@ class RDoc::Parser::C < RDoc::Parser def find_class_comment(class_name, class_meth) comment = nil if @content =~ %r{((?>/\*.*?\*/\s+)) - (static\s+)?void\s+Init_#{class_name}\s*(?:_\(\s*)?\(\s*(?:void\s*)\)}xmi + (static\s+)?void\s+Init_#{class_name}\s*(?:_\(\s*)?\(\s*(?:void\s*)\)}xmi then + comment = $1 + elsif @content =~ %r{Document-(?:class|module):\s#{class_name}\s*?(?:<\s+[:,\w]+)?\n((?>.*?\*/))}m comment = $1 - elsif @content =~ %r{Document-(class|module):\s#{class_name}\s*?\n((?>.*?\*/))}m - comment = $2 else if @content =~ /rb_define_(class|module)/m then class_name = class_name.split("::").last @@ -424,9 +422,11 @@ class RDoc::Parser::C < RDoc::Parser end end - def find_override_comment(meth_name) + def find_override_comment(class_name, meth_name) name = Regexp.escape(meth_name) - if @content =~ %r{Document-method:\s#{name}\s*?\n((?>.*?\*/))}m + if @content =~ %r{Document-method:\s+#{class_name}(?:\.|::)#{name}\s*?\n((?>.*?\*/))}m then + $1 + elsif @content =~ %r{Document-method:\s#{name}\s*?\n((?>.*?\*/))}m then $1 end end @@ -480,6 +480,10 @@ class RDoc::Parser::C < RDoc::Parser end if class_mod == "class" then + full_name = enclosure.full_name.to_s + "::#{class_name}" + if @content =~ %r{Document-class:\s+#{full_name}\s*<\s+([:,\w]+)} then + parent_name = $1 + end cm = enclosure.add_class RDoc::NormalClass, class_name, parent_name @stats.add_class cm else @@ -562,18 +566,16 @@ class RDoc::Parser::C < RDoc::Parser return unless class_name - class_obj = find_class(var_name, class_name) + class_obj = find_class var_name, class_name - if class_obj - if meth_name == "initialize" + if class_obj then + if meth_name == "initialize" then meth_name = "new" type = "singleton_method" end - meth_obj = RDoc::AnyMethod.new("", meth_name) - meth_obj.singleton = - %w{singleton_method module_function}.include?(type) - @stats.add_method meth_obj + meth_obj = RDoc::AnyMethod.new '', meth_name + meth_obj.singleton = %w[singleton_method module_function].include? type p_count = (Integer(param_count) rescue -1) @@ -585,14 +587,16 @@ class RDoc::Parser::C < RDoc::Parser meth_obj.params = "(" + (1..p_count).map{|i| "p#{i}"}.join(", ") + ")" end - if source_file + if source_file then file_name = File.join(@file_dir, source_file) body = (@@known_bodies[source_file] ||= File.read(file_name)) else body = @content end - if find_body(meth_body, meth_obj, body) and meth_obj.document_self - class_obj.add_method(meth_obj) + + if find_body(class_name, meth_body, meth_obj, body) and meth_obj.document_self then + class_obj.add_method meth_obj + @stats.add_method meth_obj end end end @@ -628,8 +632,8 @@ class RDoc::Parser::C < RDoc::Parser end def remove_private_comments(comment) - comment.gsub!(/\/?\*--(.*?)\/?\*\+\+/m, '') - comment.sub!(/\/?\*--.*/m, '') + comment.gsub!(/\/?\*--\n(.*?)\/?\*\+\+/m, '') + comment.sub!(/\/?\*--\n.*/m, '') end ## diff --git a/lib/rdoc/parser/perl.rb b/lib/rdoc/parser/perl.rb new file mode 100644 index 0000000000..43d1e9ff69 --- /dev/null +++ b/lib/rdoc/parser/perl.rb @@ -0,0 +1,165 @@ +require 'rdoc/parser' + +## +# +# This is an attamept to write a basic parser for Perl's +# POD (Plain old Documentation) format. Ruby code must +# co-exist with Perl, and some tasks are easier in Perl +# than Ruby because of existing libraries. +# +# One difficult is that Perl POD has no means of identifying +# the classes (packages) and methods (subs) with which it +# is associated, it is more like literate programming in so +# far as it just happens to be in the same place as the code, +# but need not be. +# +# We would like to support all the markup the POD provides +# so that it will convert happily to HTML. At the moment +# I don't think I can do that: time constraints. +# + +class RDoc::Parser::PerlPOD < RDoc::Parser + + parse_files_matching(/.p[lm]$/) + + ## + # Prepare to parse a perl file + + def initialize(top_level, file_name, content, options, stats) + super + + preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include + + preprocess.handle @content do |directive, param| + warn "Unrecognized directive '#{directive}' in #{@file_name}" + end + end + + ## + # Extract the Pod(-like) comments from the code. + # At its most basic there will ne no need to distinguish + # between the different types of header, etc. + # + # This uses a simple finite state machine, in a very + # procedural pattern. I could "replace case with polymorphism" + # but I think it would obscure the intent, scatter the + # code all over tha place. This machine is necessary + # because POD requires that directives be preceded by + # blank lines, so reading line by line is necessary, + # and preserving state about what is seen is necesary. + + def scan + + @top_level.comment ||= "" + state=:code_blank + line_number = 0 + line = nil + + # This started out as a really long nested case statement, + # which also led to repetitive code. I'd like to avoid that + # so I'm using a "table" instead. + + # Firstly we need some procs to do the transition and processing + # work. Because these are procs they are closures, and they can + # use variables in the local scope. + # + # First, the "nothing to see here" stuff. + code_noop = lambda do + if line =~ /^\s+$/ + state = :code_blank + end + end + + pod_noop = lambda do + if line =~ /^\s+$/ + state = :pod_blank + end + @top_level.comment += filter(line) + end + + begin_noop = lambda do + if line =~ /^\s+$/ + state = :begin_blank + end + @top_level.comment += filter(line) + end + + # Now for the blocks that process code and comments... + + transit_to_pod = lambda do + case line + when /^=(?:pod|head\d+)/ + state = :pod_no_blank + @top_level.comment += filter(line) + when /^=over/ + state = :over_no_blank + @top_level.comment += filter(line) + when /^=(?:begin|for)/ + state = :begin_no_blank + end + end + + process_pod = lambda do + case line + when /^\s*$/ + state = :pod_blank + @top_level.comment += filter(line) + when /^=cut/ + state = :code_no_blank + when /^=end/ + $stderr.puts "'=end' unexpected at #{line_number} in #{@file_name}" + else + @top_level.comment += filter(line) + end + end + + + process_begin = lambda do + case line + when /^\s*$/ + state = :begin_blank + @top_level.comment += filter(line) + when /^=end/ + state = :code_no_blank + when /^=cut/ + $stderr.puts "'=cut' unexpected at #{line_number} in #{@file_name}" + else + @top_level.comment += filter(line) + end + + end + + + transitions = { :code_no_blank => code_noop, + :code_blank => transit_to_pod, + :pod_no_blank => pod_noop, + :pod_blank => process_pod, + :begin_no_blank => begin_noop, + :begin_blank => process_begin} + @content.each_line do |l| + line = l + line_number += 1 + transitions[state].call + end # each line + + @top_level + end + + # Filter the perl markup that does the same as the rdoc + # filtering. Only basic for now. Will probably need a + # proper parser to cope with C<<...>> etc + def filter(comment) + return '' if comment =~ /^=pod\s*$/ + comment.gsub!(/^=pod/, '==') + comment.gsub!(/^=head(\d+)/) do + "=" * $1.to_i + end + comment.gsub!(/=item/, ''); + comment.gsub!(/C<(.*?)>/, '\1'); + comment.gsub!(/I<(.*?)>/, '\1'); + comment.gsub!(/B<(.*?)>/, '\1'); + comment + end + +end + diff --git a/lib/rdoc/parser/ruby.rb b/lib/rdoc/parser/ruby.rb index abbc85bde7..865cb79d39 100644 --- a/lib/rdoc/parser/ruby.rb +++ b/lib/rdoc/parser/ruby.rb @@ -134,7 +134,7 @@ module RDoc::RubyToken TokenDefinitions = [ [:TkCLASS, TkKW, "class", EXPR_CLASS], - [:TkMODULE, TkKW, "module", EXPR_BEG], + [:TkMODULE, TkKW, "module", EXPR_CLASS], [:TkDEF, TkKW, "def", EXPR_FNAME], [:TkUNDEF, TkKW, "undef", EXPR_FNAME], [:TkBEGIN, TkKW, "begin", EXPR_BEG], @@ -1945,9 +1945,9 @@ class RDoc::Parser::Ruby < RDoc::Parser case tk when TkSEMICOLON break - when TkLPAREN, TkfLPAREN + when TkLPAREN, TkfLPAREN, TkLBRACE, TkLBRACK, TkDO nest += 1 - when TkRPAREN + when TkRPAREN, TkRBRACE, TkRBRACK, TkEND nest -= 1 when TkCOMMENT if nest <= 0 && @scanner.lex_state == EXPR_END @@ -1955,7 +1955,7 @@ class RDoc::Parser::Ruby < RDoc::Parser break end when TkNL - if (@scanner.lex_state == EXPR_END and nest <= 0) || !@scanner.continue + if (nest <= 0) && ((@scanner.lex_state == EXPR_END) || (!@scanner.continue)) unget_tk(tk) break end @@ -2683,8 +2683,8 @@ class RDoc::Parser::Ruby < RDoc::Parser end def remove_private_comments(comment) - comment.gsub!(/^#--.*?^#\+\+/m, '') - comment.sub!(/^#--.*/m, '') + comment.gsub!(/^#--\n.*?^#\+\+/m, '') + comment.sub!(/^#--\n.*/m, '') end def remove_token_listener(obj) diff --git a/lib/rdoc/parser/simple.rb b/lib/rdoc/parser/simple.rb index 6e123a4655..cdfe686718 100644 --- a/lib/rdoc/parser/simple.rb +++ b/lib/rdoc/parser/simple.rb @@ -31,7 +31,7 @@ class RDoc::Parser::Simple < RDoc::Parser end def remove_private_comments(comment) - comment.gsub(/^--[^-].*?^\+\+/m, '').sub(/^--.*/m, '') + comment.gsub(/^--\n.*?^\+\+/m, '').sub(/^--\n.*/m, '') end end diff --git a/lib/rdoc/rdoc.rb b/lib/rdoc/rdoc.rb index bc0a32f407..ce1cb1a93f 100644 --- a/lib/rdoc/rdoc.rb +++ b/lib/rdoc/rdoc.rb @@ -7,6 +7,7 @@ require 'rdoc/parser/simple' require 'rdoc/parser/ruby' require 'rdoc/parser/c' require 'rdoc/parser/f95' +require 'rdoc/parser/perl' require 'rdoc/stats' require 'rdoc/options' @@ -189,11 +190,11 @@ module RDoc def parse_files(options) @stats = Stats.new options.verbosity - + files = options.files files = ["."] if files.empty? - file_list = normalized_file_list(options, files, true) + file_list = normalized_file_list(options, files, true, options.exclude) return [] if file_list.empty? @@ -288,6 +289,5 @@ module RDoc end end end - end diff --git a/lib/rdoc/ri/cache.rb b/lib/rdoc/ri/cache.rb index 2e267d95fb..06177a00de 100644 --- a/lib/rdoc/ri/cache.rb +++ b/lib/rdoc/ri/cache.rb @@ -14,7 +14,7 @@ class RDoc::RI::ClassEntry @inferior_classes = [] end - # We found this class in more tha one place, so add + # We found this class in more than one place, so add # in the name from there. def add_path(path) @path_names << path @@ -37,10 +37,10 @@ class RDoc::RI::ClassEntry if name =~ /^(.*?)-(c|i).yaml$/ external_name = $1 is_class_method = $2 == "c" - internal_name = RiWriter.external_to_internal(external_name) + internal_name = RDoc::RI::Writer.external_to_internal(external_name) list = is_class_method ? @class_methods : @instance_methods path = File.join(dir, name) - list << MethodEntry.new(path, internal_name, is_class_method, self) + list << RDoc::RI::MethodEntry.new(path, internal_name, is_class_method, self) else full_name = File.join(dir, name) if File.directory?(full_name) @@ -48,7 +48,7 @@ class RDoc::RI::ClassEntry if inf_class inf_class.add_path(full_name) else - inf_class = ClassEntry.new(full_name, name, self) + inf_class = RDoc::RI::ClassEntry.new(full_name, name, self) @inferior_classes << inf_class end inf_class.load_from(full_name) @@ -168,7 +168,7 @@ class RDoc::RI::MethodEntry end ## -# We represent everything know about all 'ri' files accessible to this program +# We represent everything known about all 'ri' files accessible to this program class RDoc::RI::Cache @@ -185,4 +185,3 @@ class RDoc::RI::Cache end end - diff --git a/lib/rdoc/ri/descriptions.rb b/lib/rdoc/ri/descriptions.rb index 0d8560323a..467b7de2a9 100644 --- a/lib/rdoc/ri/descriptions.rb +++ b/lib/rdoc/ri/descriptions.rb @@ -77,7 +77,9 @@ end class RDoc::RI::ModuleDescription < RDoc::RI::Description attr_accessor :class_methods + attr_accessor :class_method_extensions attr_accessor :instance_methods + attr_accessor :instance_method_extensions attr_accessor :attributes attr_accessor :constants attr_accessor :includes @@ -148,6 +150,7 @@ class RDoc::RI::MethodDescription < RDoc::RI::Description attr_accessor :aliases attr_accessor :is_alias_for attr_accessor :params + attr_accessor :source_path end diff --git a/lib/rdoc/ri/display.rb b/lib/rdoc/ri/display.rb index 379cef11b3..05a7cf253d 100644 --- a/lib/rdoc/ri/display.rb +++ b/lib/rdoc/ri/display.rb @@ -1,5 +1,15 @@ require 'rdoc/ri' +# readline support might not be present, so be careful +# when requiring it. +begin + require('readline') + require('abbrev') + CAN_USE_READLINE = true +rescue + CAN_USE_READLINE = false +end + ## # This is a kind of 'flag' module. If you want to write your own 'ri' display # module (perhaps because you're writing an IDE), you write a class which @@ -41,7 +51,7 @@ class RDoc::RI::DefaultDisplay # Display information about +klass+. Fetches additional information from # +ri_reader+ as necessary. - def display_class_info(klass, ri_reader) + def display_class_info(klass) page do superclass = klass.superclass_string @@ -61,17 +71,11 @@ class RDoc::RI::DefaultDisplay @formatter.blankline @formatter.display_heading("Includes:", 2, "") incs = [] + klass.includes.each do |inc| - inc_desc = ri_reader.find_class_by_name(inc.name) - if inc_desc - str = inc.name + "(" - str << inc_desc.instance_methods.map{|m| m.name}.join(", ") - str << ")" - incs << str - else - incs << inc.name - end - end + incs << inc.name + end + @formatter.wrap(incs.sort.join(', ')) end @@ -82,42 +86,19 @@ class RDoc::RI::DefaultDisplay constants = klass.constants.sort_by { |constant| constant.name } constants.each do |constant| + @formatter.wrap "#{constant.name} = #{constant.value}" if constant.comment then - @formatter.wrap "#{constant.name}:" - @formatter.indent do @formatter.display_flow constant.comment end else - @formatter.wrap constant.name + @formatter.break_to_newline end end end - class_data = [ - :class_methods, - :class_method_extensions, - :instance_methods, - :instance_method_extensions, - ] - - class_data.each do |data_type| - data = klass.send data_type - - unless data.empty? then - @formatter.blankline - - heading = data_type.to_s.split('_').join(' ').capitalize << ':' - @formatter.display_heading heading, 2, '' - - data = data.map { |item| item.name }.sort.join ', ' - @formatter.wrap data - end - end - unless klass.attributes.empty? then @formatter.blankline - @formatter.display_heading 'Attributes:', 2, '' attributes = klass.attributes.sort_by { |attribute| attribute.name } @@ -130,11 +111,119 @@ class RDoc::RI::DefaultDisplay end else @formatter.wrap "#{attribute.name} (#{attribute.rw})" + @formatter.break_to_newline end end end + + return display_class_method_list(klass) end end + + ## + # Given a Hash mapping a class' methods to method types (returned by + # display_class_method_list), this method allows the user to + # choose one of the methods. + + def get_class_method_choice(method_map) + if CAN_USE_READLINE + # prepare abbreviations for tab completion + abbreviations = method_map.keys.abbrev + Readline.completion_proc = proc do |string| + abbreviations.values.uniq.grep(/^#{string}/) + end + end + + @formatter.raw_print_line "\nEnter the method name you want.\n" + @formatter.raw_print_line "Class methods can be preceeded by '::' and instance methods by '#'.\n" + + if CAN_USE_READLINE + @formatter.raw_print_line "You can use tab to autocomplete.\n" + @formatter.raw_print_line "Enter a blank line to exit.\n" + + choice_string = Readline.readline(">> ").strip + else + @formatter.raw_print_line "Enter a blank line to exit.\n" + @formatter.raw_print_line ">> " + choice_string = $stdin.gets.strip + end + + if choice_string == '' + return nil + else + class_or_instance = method_map[choice_string] + + if class_or_instance + # If the user's choice is not preceeded by a '::' or a '#', figure + # out whether they want a class or an instance method and decorate + # the choice appropriately. + if(choice_string =~ /^[a-zA-Z]/) + if(class_or_instance == :class) + choice_string = "::#{choice_string}" + else + choice_string = "##{choice_string}" + end + end + + return choice_string + else + @formatter.raw_print_line "No method matched '#{choice_string}'.\n" + return nil + end + end + end + + + ## + # Display methods on +klass+ + # Returns a hash mapping method name to method contents (HACK?) + + def display_class_method_list(klass) + method_map = {} + + class_data = [ + :class_methods, + :class_method_extensions, + :instance_methods, + :instance_method_extensions, + ] + + class_data.each do |data_type| + data = klass.send data_type + + unless data.nil? or data.empty? then + @formatter.blankline + + heading = data_type.to_s.split('_').join(' ').capitalize << ':' + @formatter.display_heading heading, 2, '' + + method_names = [] + data.each do |item| + method_names << item.name + + if(data_type == :class_methods || + data_type == :class_method_extensions) then + method_map["::#{item.name}"] = :class + method_map[item.name] = :class + else + # + # Since we iterate over instance methods after class methods, + # an instance method always will overwrite the unqualified + # class method entry for a class method of the same name. + # + method_map["##{item.name}"] = :instance + method_map[item.name] = :instance + end + end + method_names.sort! + + @formatter.wrap method_names.join(',') + end + end + + method_map + end + private :display_class_method_list ## # Display an Array of RDoc::Markup::Flow objects, +flow+. @@ -172,10 +261,42 @@ class RDoc::RI::DefaultDisplay def display_method_list(methods) page do @formatter.wrap "More than one method matched your request. You can refine your search by asking for information on one of:" + @formatter.blankline + methods.each do |method| + @formatter.raw_print_line "#{method.full_name} [#{method.source_path}]\n" + end + end + end + + ## + # Display a list of +methods+ and allow the user to select one of them. + + def display_method_list_choice(methods) + page do + @formatter.wrap "More than one method matched your request. Please choose one of the possible matches." @formatter.blankline - @formatter.wrap methods.map { |m| m.full_name }.join(", ") + methods.each_with_index do |method, index| + @formatter.raw_print_line "%3d %s [%s]\n" % [index + 1, method.full_name, method.source_path] + end + + @formatter.raw_print_line ">> " + + choice = $stdin.gets.strip! + + if(choice == '') + return + end + + choice = choice.to_i + + if ((choice == 0) || (choice > methods.size)) then + @formatter.raw_print_line "Invalid choice!\n" + else + method = methods[choice - 1] + display_method_info(method) + end end end @@ -198,10 +319,8 @@ class RDoc::RI::DefaultDisplay @formatter.break_to_newline end - if method.source_path then - @formatter.blankline - @formatter.wrap("Extension from #{method.source_path}") - end + @formatter.blankline + @formatter.wrap("From #{method.source_path}") end ## diff --git a/lib/rdoc/ri/driver.rb b/lib/rdoc/ri/driver.rb index dfc5f2f98a..0c91232b70 100644 --- a/lib/rdoc/ri/driver.rb +++ b/lib/rdoc/ri/driver.rb @@ -11,29 +11,33 @@ require 'rdoc/markup/to_flow' class RDoc::RI::Driver - class Hash < ::Hash - def self.convert(hash) - hash = new.update hash - - hash.each do |key, value| - hash[key] = case value - when ::Hash then - convert value - when Array then - value = value.map do |v| - ::Hash === v ? convert(v) : v - end - value - else - value - end - end - - hash - end + # + # This class offers both Hash and OpenStruct functionality. + # We convert from the Core Hash to this before calling any of + # the display methods, in order to give the display methods + # a cleaner API for accessing the data. + # + class OpenStructHash < Hash + # + # This method converts from a Hash to an OpenStructHash. + # + def self.convert(object) + case object + when Hash then + new_hash = new # Convert Hash -> OpenStructHash + + object.each do |key, value| + new_hash[key] = convert(value) + end - def method_missing method, *args - self[method.to_s] + new_hash + when Array then + object.map do |element| + convert(element) + end + else + object + end end def merge_enums(other) @@ -57,6 +61,10 @@ class RDoc::RI::Driver end end end + + def method_missing method, *args + self[method.to_s] + end end class Error < RDoc::RI::Error; end @@ -69,25 +77,31 @@ class RDoc::RI::Driver attr_accessor :homepath # :nodoc: - def self.process_args(argv) + def self.default_options options = {} options[:use_stdout] = !$stdout.tty? options[:width] = 72 options[:formatter] = RDoc::RI::Formatter.for 'plain' - options[:list_classes] = false - options[:list_names] = false + options[:interactive] = false + options[:use_cache] = true + + # By default all standard paths are used. + options[:use_system] = true + options[:use_site] = true + options[:use_home] = true + options[:use_gems] = true + options[:extra_doc_dirs] = [] + + return options + end - # By default all paths are used. If any of these are true, only those - # directories are used. - use_system = false - use_site = false - use_home = false - use_gems = false - doc_dirs = [] + def self.process_args(argv) + options = default_options opts = OptionParser.new do |opt| opt.program_name = File.basename $0 opt.version = RDoc::VERSION + opt.release = nil opt.summary_indent = ' ' * 4 directories = [ @@ -142,86 +156,114 @@ Options may also be set in the 'RI' environment variable. opt.separator "Options:" opt.separator nil - opt.on("--classes", "-c", - "Display the names of classes and modules we", - "know about.") do |value| - options[:list_classes] = value + opt.on("--fmt=FORMAT", "--format=FORMAT", "-f", + RDoc::RI::Formatter::FORMATTERS.keys, + "Format to use when displaying output:", + " #{RDoc::RI::Formatter.list}", + "Use 'bs' (backspace) with most pager", + "programs. To use ANSI, either disable the", + "pager or tell the pager to allow control", + "characters.") do |value| + options[:formatter] = RDoc::RI::Formatter.for value end opt.separator nil opt.on("--doc-dir=DIRNAME", "-d", Array, - "List of directories to search for", - "documentation. If not specified, we search", - "the standard rdoc/ri directories. May be", - "repeated.") do |value| + "List of directories from which to source", + "documentation in addition to the standard", + "directories. May be repeated.") do |value| value.each do |dir| unless File.directory? dir then raise OptionParser::InvalidArgument, "#{dir} is not a directory" end + + options[:extra_doc_dirs] << File.expand_path(dir) end + end + + opt.separator nil - doc_dirs.concat value + opt.on("--[no-]use-cache", + "Whether or not to use ri's cache.", + "True by default.") do |value| + options[:use_cache] = value end opt.separator nil - opt.on("--fmt=FORMAT", "--format=FORMAT", "-f", - RDoc::RI::Formatter::FORMATTERS.keys, - "Format to use when displaying output:", - " #{RDoc::RI::Formatter.list}", - "Use 'bs' (backspace) with most pager", - "programs. To use ANSI, either disable the", - "pager or tell the pager to allow control", - "characters.") do |value| - options[:formatter] = RDoc::RI::Formatter.for value + opt.on("--no-standard-docs", + "Do not include documentation from", + "the Ruby standard library, site_lib,", + "installed gems, or ~/.rdoc.", + "Equivalent to specifying", + "the options --no-system, --no-site, --no-gems,", + "and --no-home") do + options[:use_system] = false + options[:use_site] = false + options[:use_gems] = false + options[:use_home] = false end opt.separator nil - unless RDoc::RI::Paths::GEMDIRS.empty? then - opt.on("--[no-]gems", - "Include documentation from RubyGems.") do |value| - use_gems = value - end + opt.on("--[no-]system", + "Include documentation from Ruby's standard", + "library. Defaults to true.") do |value| + options[:use_system] = value end opt.separator nil - opt.on("--[no-]home", - "Include documentation stored in ~/.rdoc.") do |value| - use_home = value + opt.on("--[no-]site", + "Include documentation from libraries", + "installed in site_lib.", + "Defaults to true.") do |value| + options[:use_site] = value end opt.separator nil - opt.on("--[no-]list-names", "-l", - "List all the names known to RDoc, one per", - "line.") do |value| - options[:list_names] = value + opt.on("--[no-]gems", + "Include documentation from RubyGems.", + "Defaults to true.") do |value| + options[:use_gems] = value end opt.separator nil - opt.on("--no-pager", "-T", - "Send output directly to stdout.") do |value| - options[:use_stdout] = !value + opt.on("--[no-]home", + "Include documentation stored in ~/.rdoc.", + "Defaults to true.") do |value| + options[:use_home] = value end opt.separator nil - opt.on("--[no-]site", - "Include documentation from libraries", - "installed in site_lib.") do |value| - use_site = value + opt.on("--list-doc-dirs", + "List the directories from which ri will", + "source documentation on stdout and exit.") do + options[:list_doc_dirs] = true end opt.separator nil - opt.on("--[no-]system", - "Include documentation from Ruby's standard", - "library.") do |value| - use_system = value + opt.on("--no-pager", "-T", + "Send output directly to stdout,", + "rather than to a pager.") do + options[:use_stdout] = true + end + + opt.on("--interactive", "-i", + "This makes ri go into interactive mode.", + "When ri is in interactive mode it will", + "allow the user to disambiguate lists of", + "methods in case multiple methods match", + "against a method search string. It also", + "will allow the user to enter in a method", + "name (with auto-completion, if readline", + "is supported) when viewing a class.") do + options[:interactive] = true end opt.separator nil @@ -238,10 +280,10 @@ Options may also be set in the 'RI' environment variable. options[:names] = argv - options[:path] = RDoc::RI::Paths.path(use_system, use_site, use_home, - use_gems, *doc_dirs) - options[:raw_path] = RDoc::RI::Paths.raw_path(use_system, use_site, - use_home, use_gems, *doc_dirs) + options[:formatter] ||= RDoc::RI::Formatter.for('plain') + options[:use_stdout] ||= !$stdout.tty? + options[:use_stdout] ||= options[:interactive] + options[:width] ||= 72 options @@ -258,22 +300,30 @@ Options may also be set in the 'RI' environment variable. ri.run end - def initialize(options={}) - options[:formatter] ||= RDoc::RI::Formatter.for('plain') - options[:use_stdout] ||= !$stdout.tty? - options[:width] ||= 72 - @names = options[:names] + def initialize(initial_options={}) + options = self.class.default_options.update(initial_options) + @names = options[:names] @class_cache_name = 'classes' - @all_dirs = RDoc::RI::Paths.path(true, true, true, true) + + @doc_dirs = RDoc::RI::Paths.path(options[:use_system], + options[:use_site], + options[:use_home], + options[:use_gems], + options[:extra_doc_dirs]) + @homepath = RDoc::RI::Paths.raw_path(false, false, true, false).first @homepath = @homepath.sub(/\.rdoc/, '.ri') - @sys_dirs = RDoc::RI::Paths.raw_path(true, false, false, false) + @sys_dir = RDoc::RI::Paths.raw_path(true, false, false, false).first + @list_doc_dirs = options[:list_doc_dirs] FileUtils.mkdir_p cache_file_path unless File.directory? cache_file_path + @cache_doc_dirs_path = File.join cache_file_path, ".doc_dirs" + @use_cache = options[:use_cache] @class_cache = nil + @interactive = options[:interactive] @display = RDoc::RI::DefaultDisplay.new(options[:formatter], options[:width], options[:use_stdout]) @@ -282,30 +332,92 @@ Options may also be set in the 'RI' environment variable. def class_cache return @class_cache if @class_cache - newest = map_dirs('created.rid', :all) do |f| + # Get the documentation directories used to make the cache in order to see + # whether the cache is valid for the current ri instantiation. + if(File.readable?(@cache_doc_dirs_path)) + cache_doc_dirs = IO.read(@cache_doc_dirs_path).split("\n") + else + cache_doc_dirs = [] + end + + newest = map_dirs('created.rid') do |f| File.mtime f if test ?f, f end.max + # An up to date cache file must have been created more recently than + # the last modification of any of the documentation directories. It also + # must have been created with the same documentation directories + # as those from which ri currently is sourcing documentation. up_to_date = (File.exist?(class_cache_file_path) and - newest and newest < File.mtime(class_cache_file_path)) + newest and newest < File.mtime(class_cache_file_path) and + (cache_doc_dirs == @doc_dirs)) + + if up_to_date and @use_cache then + open class_cache_file_path, 'rb' do |fp| + begin + @class_cache = Marshal.load fp.read + rescue + # + # This shouldn't be necessary, since the up_to_date logic above + # should force the cache to be recreated when a new version of + # rdoc is installed. This seems like a worthwhile enhancement + # to ri's robustness, however. + # + $stderr.puts "Error reading the class cache; recreating the class cache!" + @class_cache = create_class_cache + end + end + else + @class_cache = create_class_cache + end + + @class_cache + end - @class_cache = if up_to_date then - load_cache_for @class_cache_name - else - class_cache = RDoc::RI::Driver::Hash.new + def create_class_cache + class_cache = OpenStructHash.new - classes = map_dirs('**/cdesc*.yaml', :sys) { |f| Dir[f] } - populate_class_cache class_cache, classes + if(@use_cache) + # Dump the documentation directories to a file in the cache, so that + # we only will use the cache for future instantiations with identical + # documentation directories. + File.open @cache_doc_dirs_path, "wb" do |fp| + fp << @doc_dirs.join("\n") + end + end - classes = map_dirs('**/cdesc*.yaml') { |f| Dir[f] } - warn "Updating class cache with #{classes.size} classes..." + classes = map_dirs('**/cdesc*.yaml') { |f| Dir[f] } + warn "Updating class cache with #{classes.size} classes..." + populate_class_cache class_cache, classes - populate_class_cache class_cache, classes, true - write_cache class_cache, class_cache_file_path - end + write_cache class_cache, class_cache_file_path - @class_cache = RDoc::RI::Driver::Hash.convert @class_cache - @class_cache + class_cache + end + + def populate_class_cache(class_cache, classes, extension = false) + classes.each do |cdesc| + desc = read_yaml cdesc + klassname = desc["full_name"] + + unless class_cache.has_key? klassname then + desc["display_name"] = "Class" + desc["sources"] = [cdesc] + desc["instance_method_extensions"] = [] + desc["class_method_extensions"] = [] + class_cache[klassname] = desc + else + klass = class_cache[klassname] + + if extension then + desc["instance_method_extensions"] = desc.delete "instance_methods" + desc["class_method_extensions"] = desc.delete "class_methods" + end + + klass.merge_enums desc + klass["sources"] << cdesc + end + end end def class_cache_file_path @@ -322,8 +434,11 @@ Options may also be set in the 'RI' environment variable. def display_class(name) klass = class_cache[name] - klass = RDoc::RI::Driver::Hash.convert klass - @display.display_class_info klass, class_cache + @display.display_class_info klass + end + + def display_method(method) + @display.display_method_info method end def get_info_for(arg) @@ -337,48 +452,74 @@ Options may also be set in the 'RI' environment variable. cache = nil if File.exist? path and - File.mtime(path) >= File.mtime(class_cache_file_path) then + File.mtime(path) >= File.mtime(class_cache_file_path) and + @use_cache then open path, 'rb' do |fp| - cache = Marshal.load fp.read + begin + cache = Marshal.load fp.read + rescue + # + # The cache somehow is bad. Recreate the cache. + # + $stderr.puts "Error reading the cache for #{klassname}; recreating the cache!" + cache = create_cache_for klassname, path + end end else - class_cache = nil + cache = create_cache_for klassname, path + end - open class_cache_file_path, 'rb' do |fp| - class_cache = Marshal.load fp.read - end + cache + end - klass = class_cache[klassname] - return nil unless klass - - method_files = klass["sources"] - cache = RDoc::RI::Driver::Hash.new - - sys_dir = @sys_dirs.first - method_files.each do |f| - system_file = f.index(sys_dir) == 0 - Dir[File.join(File.dirname(f), "*")].each do |yaml| - next unless yaml =~ /yaml$/ - next if yaml =~ /cdesc-[^\/]+yaml$/ - method = read_yaml yaml - name = method["full_name"] - ext_path = f - ext_path = "gem #{$1}" if f =~ %r%gems/[\d.]+/doc/([^/]+)% - method["source_path"] = ext_path unless system_file - cache[name] = RDoc::RI::Driver::Hash.convert method + def create_cache_for(klassname, path) + klass = class_cache[klassname] + return nil unless klass + + method_files = klass["sources"] + cache = OpenStructHash.new + + method_files.each do |f| + system_file = f.index(@sys_dir) == 0 + Dir[File.join(File.dirname(f), "*")].each do |yaml| + next unless yaml =~ /yaml$/ + next if yaml =~ /cdesc-[^\/]+yaml$/ + + method = read_yaml yaml + + if system_file then + method["source_path"] = "Ruby #{RDoc::RI::Paths::VERSION}" + else + if(f =~ %r%gems/[\d.]+/doc/([^/]+)%) then + ext_path = "gem #{$1}" + else + ext_path = f + end + + method["source_path"] = ext_path end - end - write_cache cache, path + name = method["full_name"] + cache[name] = method + end end - RDoc::RI::Driver::Hash.convert cache + write_cache cache, path end ## # Finds the next ancestor of +orig_klass+ after +klass+. def lookup_ancestor(klass, orig_klass) + # This is a bit hacky, but ri will go into an infinite + # loop otherwise, since Object has an Object ancestor + # for some reason. Depending on the documentation state, I've seen + # Kernel as an ancestor of Object and not as an ancestor of Object. + if ((orig_klass == "Object") && + ((klass == "Kernel") || (klass == "Object"))) + return nil + end + cache = class_cache[orig_klass] return nil unless cache @@ -386,10 +527,13 @@ Options may also be set in the 'RI' environment variable. ancestors = [orig_klass] ancestors.push(*cache.includes.map { |inc| inc['name'] }) ancestors << cache.superclass + + ancestor_index = ancestors.index(klass) - ancestor = ancestors[ancestors.index(klass) + 1] - - return ancestor if ancestor + if ancestor_index + ancestor = ancestors[ancestors.index(klass) + 1] + return ancestor if ancestor + end lookup_ancestor klass, cache.superclass end @@ -406,18 +550,8 @@ Options may also be set in the 'RI' environment variable. method end - def map_dirs(file_name, system=false) - dirs = if system == :all then - @all_dirs - else - if system then - @sys_dirs - else - @all_dirs - @sys_dirs - end - end - - dirs.map { |dir| yield File.join(dir, file_name) }.flatten.compact + def map_dirs(file_name) + @doc_dirs.map { |dir| yield File.join(dir, file_name) }.flatten.compact end ## @@ -436,83 +570,66 @@ Options may also be set in the 'RI' environment variable. [klass, meth] end - def populate_class_cache(class_cache, classes, extension = false) - classes.each do |cdesc| - desc = read_yaml cdesc - klassname = desc["full_name"] - - unless class_cache.has_key? klassname then - desc["display_name"] = "Class" - desc["sources"] = [cdesc] - desc["instance_method_extensions"] = [] - desc["class_method_extensions"] = [] - class_cache[klassname] = desc - else - klass = class_cache[klassname] - - if extension then - desc["instance_method_extensions"] = desc.delete "instance_methods" - desc["class_method_extensions"] = desc.delete "class_methods" - end - - klass = RDoc::RI::Driver::Hash.convert klass - - klass.merge_enums desc - klass["sources"] << cdesc - end - end - end - def read_yaml(path) data = File.read path + + # Necessary to be backward-compatible with documentation generated + # by earliar RDoc versions. data = data.gsub(/ \!ruby\/(object|struct):(RDoc::RI|RI).*/, '') data = data.gsub(/ \!ruby\/(object|struct):SM::(\S+)/, ' !ruby/\1:RDoc::Markup::\2') - YAML.load data + OpenStructHash.convert(YAML.load(data)) end def run - if @names.empty? then + if(@list_doc_dirs) + puts @doc_dirs.join("\n") + elsif @names.empty? then @display.list_known_classes class_cache.keys.sort else @names.each do |name| - case name - when /::|\#|\./ then - if class_cache.key? name then - display_class name - else - klass, = parse_name name + if class_cache.key? name then + method_map = display_class name + if(@interactive) + method_name = @display.get_class_method_choice(method_map) + + if(method_name != nil) + method = lookup_method "#{name}#{method_name}", name + display_method method + end + end + elsif name =~ /::|\#|\./ then + klass, = parse_name name - orig_klass = klass - orig_name = name + orig_klass = klass + orig_name = name - until klass == 'Kernel' do - method = lookup_method name, klass + loop do + method = lookup_method name, klass - break method if method + break method if method - ancestor = lookup_ancestor klass, orig_klass + ancestor = lookup_ancestor klass, orig_klass - break unless ancestor + break unless ancestor - name = name.sub klass, ancestor - klass = ancestor - end + name = name.sub klass, ancestor + klass = ancestor + end - raise NotFoundError, orig_name unless method + raise NotFoundError, orig_name unless method - @display.display_method_info method - end + display_method method else - if class_cache.key? name then - display_class name - else - methods = select_methods(/^#{name}/) + methods = select_methods(/#{name}/) - if methods.size == 0 - raise NotFoundError, name - elsif methods.size == 1 - @display.display_method_info methods.first + if methods.size == 0 + raise NotFoundError, name + elsif methods.size == 1 + display_method methods[0] + else + if(@interactive) + @display.display_method_list_choice methods else @display.display_method_list methods end @@ -540,12 +657,13 @@ Options may also be set in the 'RI' environment variable. end def write_cache(cache, path) - File.open path, "wb" do |cache_file| - Marshal.dump cache, cache_file + if(@use_cache) + File.open path, "wb" do |cache_file| + Marshal.dump cache, cache_file + end end cache end end - diff --git a/lib/rdoc/ri/formatter.rb b/lib/rdoc/ri/formatter.rb index 0a0c3f7380..933882abc4 100644 --- a/lib/rdoc/ri/formatter.rb +++ b/lib/rdoc/ri/formatter.rb @@ -93,7 +93,7 @@ class RDoc::RI::Formatter end def raw_print_line(txt) - @output.puts txt + @output.print txt end ## diff --git a/lib/rdoc/ri/paths.rb b/lib/rdoc/ri/paths.rb index b4b6c64925..2f72b9dfd5 100644 --- a/lib/rdoc/ri/paths.rb +++ b/lib/rdoc/ri/paths.rb @@ -26,9 +26,9 @@ module RDoc::RI::Paths DOC_DIR = "doc/rdoc" - version = RbConfig::CONFIG['ruby_version'] + VERSION = RbConfig::CONFIG['ruby_version'] - base = File.join(RbConfig::CONFIG['datadir'], "ri", version) + base = File.join(RbConfig::CONFIG['datadir'], "ri", VERSION) SYSDIR = File.join(base, "system") SITEDIR = File.join(base, "site") homedir = ENV['HOME'] || ENV['USERPROFILE'] || ENV['HOMEPATH'] @@ -39,9 +39,6 @@ module RDoc::RI::Paths HOMEDIR = nil end - # This is the search path for 'ri' - PATH = [ SYSDIR, SITEDIR, HOMEDIR ].find_all {|p| p && File.directory?(p)} - begin require 'rubygems' unless defined?(Gem) and defined?(Gem::Enable) and Gem::Enable @@ -67,7 +64,6 @@ module RDoc::RI::Paths end GEMDIRS = ri_paths.map { |k,v| v.last }.sort - GEMDIRS.each { |dir| PATH << dir } rescue LoadError GEMDIRS = [] end @@ -85,9 +81,6 @@ module RDoc::RI::Paths # found. def self.raw_path(use_system, use_site, use_home, use_gems, *extra_dirs) - return PATH unless use_system or use_site or use_home or use_gems or - not extra_dirs.empty? - path = [] path << extra_dirs unless extra_dirs.empty? path << SYSDIR if use_system @@ -97,6 +90,4 @@ module RDoc::RI::Paths return path.flatten.compact end - end - diff --git a/lib/rdoc/ri/reader.rb b/lib/rdoc/ri/reader.rb index 986bb75954..de3c8d9afa 100644 --- a/lib/rdoc/ri/reader.rb +++ b/lib/rdoc/ri/reader.rb @@ -45,7 +45,7 @@ class RDoc::RI::Reader def get_method(method_entry) path = method_entry.path_name - File.open(path) { |f| RI::Description.deserialize(f) } + File.open(path) { |f| RDoc::RI::Description.deserialize(f) } end ## @@ -54,8 +54,8 @@ class RDoc::RI::Reader def get_class(class_entry) result = nil for path in class_entry.path_names - path = RiWriter.class_desc_path(path, class_entry) - desc = File.open(path) {|f| RI::Description.deserialize(f) } + path = RDoc::RI::Writer.class_desc_path(path, class_entry) + desc = File.open(path) {|f| RDoc::RI::Description.deserialize(f) } if result result.merge_in(desc) else diff --git a/lib/rdoc/ri/util.rb b/lib/rdoc/ri/util.rb index 34277f2594..4e91eb978d 100644 --- a/lib/rdoc/ri/util.rb +++ b/lib/rdoc/ri/util.rb @@ -1,7 +1,5 @@ require 'rdoc/ri' -class RDoc::RI::Error < RuntimeError; end - ## # Break argument into its constituent class or module names, an # optional method type, and a method name -- cgit v1.2.3
Path:<%= files["full_path"] %>
Modified:<%= files["dtm_modified"] %>