rdoc 2.1.0 → 2.2.0

data/History.txt

@@ -1,4 +1,85 @@
-=== 2.1.0 / ??
+=== 2.2.0 / 2008-09-19
+This version includes some significant enhancements to ri.  See RI.txt for
+documentation about ri.
+
+* 5 Major Enhancements
+  * More extensive unit tests (special thanks to Chris Lowis for contributing
+    a test).
+  * Made ri twice as fast for the most common use case of displaying
+    information for a class or a fully-qualified method
+    (i.e., ri Array#flatten, after ri has created a cache the first time that
+    it runs).
+  * Made ri many times faster when searching for an unqualified method (i.e.,
+    ri read, again after the first such search has populated ri's cache)
+  * Changed ri to do regular expression searches for unqualified methods;
+    now, a regular expression for a method can be passed to ri on the
+    command-line.
+  * Added an interactive mode to ri (patch by Daniel Choi).  Now, when ri
+    is given a -i argument, it will allow the user to disambiguate
+    unqualified methods if more than one is present and also will allow a
+    user to get information for a class' method.
+
+* 8 Minor Enhancements
+  * RDoc now adds the package title to the web pages that it generates
+    for files and classes/modules, which helps them appear better in
+    search engine results.
+  * RDoc now automatically generates cross-reference links for classes and
+    methods specified relative to the global namespace (i.e., ::A::B::C#method).
+  * All built-in templates now output valid, strict XHTML.
+  * The documentation is slightly better organized (the markup details were
+    merged into the RDoc module's documentation).
+  * Improved rdoc's HTML generation speed by about 20% (on Windows, the
+    boost seems larger).
+  * Provided an ri command-line option to control its caching behavior.
+  * Improved RDoc's documentation.  Added RI.txt to document ri.
+  * Allow HTML templates distributed as gems to be loaded with the -T option,
+    just like the standard templates in rdoc/generator/html (so an HTML
+    template lib/new_template.rb in a gem can be used with rdoc -T new_template)
+
+* 25 Bug fixes:
+  * Fixed prototype detection in C parser.  Can process ruby 1.8 C files
+    again.
+  * Fixed the main page for frameless template.  Patch by Marcin Raczkowski.
+  * Fixed the main page for frame templates.  Now, if no main page is
+    specified, RDoc will default to the README.
+  * Fixed missing stylesheet in generated chm.  Patch by Gordon Thiesfeld.
+  * Fixed the parsing of module names starting with '::'.  Patch by
+    Giuseppe Bilotta.
+  * Fixed a case where RDoc first would encounter Foo::Bar and then would
+    encounter class Foo.  Previously, RDoc erroneously would have considered
+    that both a Foo class and a Foo module existed.
+  * Fix a clase where RDoc would not generate correct cross-reference links
+    to a class contained within a module of the same name (i.e. RDoc::RDoc)
+  * Prevented RDoc from trying to parse binary files, which would produce
+    garbage output.
+  * RDoc now correctly converts ' characters to apostrophes, opening single
+    quotes, and closing single quotes in most cases (smart single quotes).
+  * RDoc now correctly converts " characters to opening double quotes and
+    and closing double quotes in most cases (smart double quotes).
+  * (c) correctly is converted into the copyright symbol.
+  * '&' characters in text now correctly are translated to HTML character codes.
+  * Fixed missing stylesheet in generated chm.  Patch by Gordon Thiesfeld.
+  * Fixed broken method links in the built-in templates.
+  * RDoc properly links to files and classes in the one page HTML template.
+  * The kilmer and hefss templates properly syntax highlight when inlining
+    source code.
+  * The kilmer and hefss template class pages properly display methods again.
+  * Fixed broken class, file, and method links in the frameless template.
+  * Fixed the clipping of source code in the html and frameless templates when
+    the source code cannot fit into the window; a scrollbar now will allow
+    all of the source code to be viewed.
+  * Fixed the missing constant descriptions in the html and frameless
+    templates.
+  * Fixed the ri command-line options that customize the directories to be
+    searched for documentation.
+  * Fixed the XML generator.  Patch by Anthony Durity.
+  * Stopped the XML template from generating invalid XML due to malformed
+    embedded ruby.
+  * Adding missing information about a class' constants to the XML template.
+  * Fixed the horizontal rule markup (---) so that it correctly adds a
+    horizontal rule rather than suppressing all text that follows.
+
+=== 2.1.0 / 2008-07-20
 
 * 3 Major Enhancements:
   * RDoc now knows about meta-programmed methods, see RDoc::Parser::Ruby

data/Manifest.txt

@@ -2,6 +2,7 @@ History.txt
 Manifest.txt
 README.txt
 Rakefile
+RI.txt
 bin/rdoc
 bin/ri
 lib/rdoc.rb
@@ -12,10 +13,12 @@ lib/rdoc/generator.rb
 lib/rdoc/generator/chm.rb
 lib/rdoc/generator/chm/chm.rb
 lib/rdoc/generator/html.rb
+lib/rdoc/generator/html/common.rb
 lib/rdoc/generator/html/frameless.rb
 lib/rdoc/generator/html/hefss.rb
 lib/rdoc/generator/html/html.rb
 lib/rdoc/generator/html/kilmer.rb
+lib/rdoc/generator/html/kilmerfactory.rb
 lib/rdoc/generator/html/one_page_html.rb
 lib/rdoc/generator/ri.rb
 lib/rdoc/generator/texinfo.rb
@@ -60,10 +63,15 @@ lib/rdoc/ri/writer.rb
 lib/rdoc/stats.rb
 lib/rdoc/template.rb
 lib/rdoc/tokenstream.rb
+test/binary.dat
+test/rdoc_markup_to_html_crossref_reference.rb
 test/test_rdoc_info_formatting.rb
 test/test_rdoc_info_sections.rb
 test/test_rdoc_markup.rb
 test/test_rdoc_markup_attribute_manager.rb
+test/test_rdoc_markup_to_html.rb
+test/test_rdoc_markup_to_html_crossref.rb
+test/test_rdoc_parser.rb
 test/test_rdoc_parser_c.rb
 test/test_rdoc_parser_ruby.rb
 test/test_rdoc_ri_attribute_formatter.rb

data/README.txt

@@ -1,17 +1,30 @@
-= RDoc
+= \RDoc
 
-* http://rubyforge.org/projects/rdoc/
+* Project Page: http://rubyforge.org/projects/rdoc/
+* Documentation: http://rdoc.rubyforge.org/
 
 == DESCRIPTION:
 
 RDoc is an application that produces documentation for one or more Ruby source
-files.  RDoc includes the `rdoc` and `ri` tools for generating and displaying
+files.  RDoc includes the +rdoc+ and +ri+ tools for generating and displaying
 online documentation.
 
 At this point in time, RDoc 2.x is a work in progress and may incur further
 API changes beyond what has been made to the RDoc 1.0.1.  Command-line tools
 are largely unaffected, but internal APIs may shift rapidly.
 
+See RDoc for a description of RDoc's markup and basic use.
+
+== TEMPLATE NOTE:
+
+RDoc comes with five built-in HTML templates.  We use a 3rd party template,
+however, for RDoc's own documentation site[http://rdoc.rubyforge.org].  This
+template is Hanna[http://github.com/mislav/hanna/tree/master].
+
+We strongly are considering making Hanna as RDoc's default template
+in a future release, but for now this template can be downloaded separately
+and used with the +-T+ option.
+
 == SYNOPSIS:
 
   gem 'rdoc'
@@ -19,11 +32,23 @@ are largely unaffected, but internal APIs may shift rapidly.
   # ... see RDoc
 
 == BUGS:
-
-If you found a bug, please report it at the RDoc project's tracker on
-RubyForge:
-
-http://rubyforge.org/tracker/?group_id=627
+---
+RDoc's Fortran 95 support is pretty broken right now.
+The rdoc-f95[http://www.gfd-dennou.org/library/dcmodel/rdoc-f95/] project has
+patches for RDoc 1.x that provide excellent Fortran 95 support.  Properly
+supporting Fortran 95 requires a rewrite of RDoc's markup engine, which
+is high on our list of goals.  The Fortran 95 issue can be tracked
+here[http://rubyforge.org/tracker/index.php?func=detail&aid=21542&group_id=627&atid=2475].
+---
+The markup engine has lots of little bugs.  In particular:
+* Escaping does not work for all markup.
+* Typesetting is not always correct.
+* Some output formats (ri, for example) do not correctly handle all of the
+  markup.
+The markup engine needs a rewrite, which can be tracked here[http://rubyforge.org/tracker/index.php?func=detail&aid=21540&group_id=627&atid=2475].
+-------
+If you find a bug, please report it at the RDoc project's
+tracker[http://rubyforge.org/tracker/?group_id=627] on RubyForge:
 
 == LICENSE:
 
@@ -31,4 +56,3 @@ RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers,
 portions (c) 2007-2008 Eric Hodel.  It is free software, and may be
 redistributed under the terms specified in the README file of the Ruby
 distribution.
-

data/RI.txt

@@ -0,0 +1,58 @@
+= RI
+== Background
++ri+ is a tool that allows Ruby documentation to be viewed on the command-line.
+It is part of RDoc and is expected to work on any platform supported by Ruby.
+
++ri+ will be a bit slow the first time that it runs (or any time that the
+underlying documentation changes) because it builds a cache in the +.ri+
+directory within the user's home directory in order to make future accesses
+faster.
+
+== Usage
+To see information for a class, do:
+  ri class_name
+
+For example, for the +Array+ class, do
+  ri Array
+
+To see information for an instance method, do:
+  ri class_name#method_name
+
+For example, for Array's +join+ method, do:
+  ri Array#join
+
+To see information for a class method, do:
+  ri class_name.method_name
+
+For example, for Module's +private+ method, do:
+  ri Module.private
+
+To search for all methods containing +read+, do:
+  ri read
+
+To search for all methods starting with +read+, do:
+  ri '^read'
+
+To search for all +read+ methods, do:
+  ri '^read$'
+
+== Options
++ri+ supports a variety of options, all of which can be viewed via +--help+.
+Of particular interest, are:
+[-d directory]
+  List of directories from which to source documentation in addition to
+  the standard directories.  May be repeated.  This can be used to specify
+  the location of site-specific documentation (which can be generated with
+  RDoc).
+[-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.
+[-T]
+  Send output to stdout, rather than to a pager.
+
+All options also can be specified through the +RI+ environment variable.
+Command-line options always override those specified in the +RI+ environment
+variable.

data/Rakefile

@@ -7,6 +7,8 @@ Hoe.new "rdoc", RDoc::VERSION do |rdoc|
   rdoc.developer 'Eric Hodel', 'drbrain@segment7.net'
   rdoc.developer 'Dave Thomas', ''
   rdoc.developer 'Phil Hagelberg', 'technomancy@gmail.com'
+  rdoc.developer 'Tony Strauss', 'tony.strauss@designingpatterns.com'
+  rdoc.remote_rdoc_dir = ''
 end
 
 # These tasks expect to have the following directory structure:

data/bin/ri

@@ -1,6 +1,5 @@
-#!/usr//bin/env ruby
+#!/usr/bin/env ruby
 
 require 'rdoc/ri/driver'
 
 RDoc::RI::Driver.run ARGV
-

data/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 <tt>.rbw</tt> 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 "<digit>.", 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.
+#
+#   [\<b>text...</b>]    displays word in a *bold* font
+#   [\<em>text...</em>]  displays word in an _emphasized_ font
+#   [\\<i>text...</i>]    displays word in an <i>italicized</i> font
+#   [\<tt>text...</tt>]  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 <IMG..>.  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 <tt>label</tt>[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: <em>{multi word label}[</em>url<em>]</em>.
+#
 # == 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 <tt>MyModule::Input</tt> 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 <drbrain@segment7.net>
 #
@@ -254,7 +372,7 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = "2.1.0"
+  VERSION = "2.2.0"
 
   ##
   # Name of the dotfile that contains the description of files to be processed