From: Gavin Sinclair <gsinclair@...>
Date: 2004-05-19T07:20:33+09:00
Subject: Re: RI for distribution

On Wednesday, May 19, 2004, 4:59:58 AM, why wrote:

> Hi, everyone.

> I'd like to start checking in some RDoc for a bunch of YAML modules.  Am
> I okay to add these files into the lib/.document file listing?  I'd like
> to document every class in my set.  Is that overkill?

In a sense it's overkill, but it doesn't matter; the more the merrier.
Just make sure you provide a good introduction in the obvious place
(or introduce a README file) so casual users can get the information
they need quickly.

Problems with the above:

* there's no way to stop ri from gathering all the available
  documentation, even though you might want different results
  in HTML and in ri

* ri will ignore a README file

So, even if you document every class, perhaps you should only put a
few filenames in .document.

I'm sure Dave will have a suggestion.

> Also, I'd like my other projects (RedCloth, Hobix, Okay) to install ri
> docs when they are installed (or updated) from either RubyGems or 
> install.rb.  Is there a suggested means for doing so?  Do I use:

>   rdoc --all --ri --op "#{ RI_DATA_DIR }" doc/

RubyGems currently creates RDoc HTML output (when asked) but not ri
data.  Your wish is noted, and will speed the process of getting it
done.

Generating ri data on an old-fashioned install is no problem.  You can
run

  rdoc --ri-site --all doc/

Check 'rdoc --help' for details.

Now why would you want to include protected and private methods in an
ri dump?  And what's in the doc/ directory?

Cheers,
Gavin