From: John Gabriele <jmg3000@...>
Date: 2006-06-02T16:52:05+09:00
Subject: ri, rdoc, gems, and the ruby_site directory

I'm on Debian GNU/Linux, but installed from source to my /opt
directory (--prefix=/opt/ruby-1.8.4).

* If I write some modules and want everyone at the site to be able to
access them, should I copy them to
/opt/ruby-1.8.4/lib/ruby/site_ruby/1.8 ?

* After I've got those site-wide modules in-place, I want to make
their docs available to everyone via the ri command. Can I then just
do:

cd /opt/ruby-1.8.4/lib/ruby/site_ruby/1.8
rdoc --ri-site

?

* My guess is, rdoc will ripple down through everything in that dir
and below (including the rubygems directory I figure) looking for .rb
(or .c) files and creating .yaml files from them. If that's the case,
where do the resulting .yaml files end up?

* Now, as for using RubyGems, it looks like when I install gems, some
docs for them get installed automatically (so, I don't need to
manually run "gem rdoc" I suppose). For rake, for example, these docs
are all html files in
/opt/ruby-1.8.4/lib/ruby/gems/1.8/doc/rake-0.7.1. But I'm guessing
that many gems have docs in them that I'd like to read using ri. For
those:

** How do I generate the yaml files for those gems' files? (maybe cd
to /opt/ruby-1.8.4/lib/ruby/gems/1.8/gems and run "rdoc --ri-foo"?)

** Where would the yaml files (corresponding to the gems' source
files) end up? (maybe in some new
/opt/ruby-1.8.4/lib/ruby/site_ruby/ri directory? Hm...)

I'm trying to write up a doc on this whole affair that might be useful
to others. Tonight's very rough first cut is here:
http://www.simisen.com/jmg/temp/ri_rdoc.html

Thanks,
---John