= RDOC - Ruby Documentation System

'rdoc' is a JavaDoc-like documentation system for Ruby. As well as
extracting and formatting comment blocks, it attempts to parse the
Ruby code itself and document its structure.


= Installation

This distribution contains two packages, rdoc itself and a text markup
library, 'markup'. You can install them both using the single command

  % ruby install.rb

in this directory. If you just want to install 'markup', change to the
markup directory and run the install.rb script there.


= Usage

Once installed, you can create documentation using the 'rdoc' command
(the command is 'rdoc.rb' under Windows)

  % rdoc [options]  [names...]

Type "rdoc --help" for an up-to-date option summary.

A typical use might be to generate documentation for a package of Ruby
source (such as rdoc itself). 

  % rdoc

This command generates documentation for all the Ruby source files in
and below the current directory. These will be stored in a
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
case, we could type

  % rdoc --main rdoc/rdoc.rb

You'll find information on the various formatting tricks you can use
in comment blocks in the documentation this generates.


= Credits

The Ruby parser in rdoc/parse.rb is based heavily on the outstanding
work of Keiju ISHITSUKA of Nippon Rational Inc, who produced the Ruby
parser for irb and the rtags package.


= Copying

RDoc is Copyright (c) 2002 Dave Thomas, The Pragmatic Programmers.  It
is free software, and may be redistributed under the terms specified
in the README file of the Ruby distribution.

= Support

Please contact me at dave@pragmaticprogrammer.com with bug reports,
suggestions, and other comments. If you send patches, it would help if
they were inline (not attachments) and generated using "diff -u".
I don't have access to a wide variety of browsers, so reports that
output looks funny under Browser XYZ aren't too helpful: far better
are suggested changes to the generated HTML that fix the problem.


= Warranty

This software is provided "as is" and without any express or
implied warranties, including, without limitation, the implied
warranties of merchantibility and fitness for a particular
purpose.
