On Sep 24, 2004, at 15:28, Alexey Verkhovsky wrote:

> Can someone suggest a nice way to organize and maintain both ri and 
> HTML
> documentation for a Ruby installation, that includes built-in classes,
> standard library, thrd party libraries and a number of RubyGems?

Alexy:

Let's start with the 'ri' side of things.

As you're installing from source, then you can arrange for the ri 
documentation for everything in the standard Ruby distribution to be 
generated at the time you build Ruby. There's some variance here, 
because the default of whether or not to generate this documentation 
changed between version of Ruby. So, in your Ruby source tree, you'd do 
a standard

   ./configure
   make
   make install

If you don't see that generating the ri documentation at the end, add 
one more step

   make install-doc

Then there's the libraries.  If you use Gems, then I believe the latest 
will automatically manage installing the ri documentation. If you use 
rpa, I think it comes with a hacked version of ri that does the same 
thing.

For libraries that you install manually, you can add ri documentation 
to your local tree using

    rdoc --ri    <filelist>
or
   rdoc --ri-site  <filelist>

The first form installs the documentation for your personal use, the 
second installs them site wide.

When it comes to HTML documentation, the story is slightly different.  
ri keeps its documentation in a kind of database format. This allows me 
to add to it incrementally. For example, if a newly installed library 
adds a method to the String class, I can add that method in, and the 
next time you ask ri for a list of String's methods, that new method 
will appear.

I can't easily do that with the HTML versions of the documentation. As 
a result, its hard to maintain a merged set of HTML documentation for 
things that you add over time.

I'm thinking of a fix to this, which would involve generating a site 
HTML documentation tree from the ri database. This would give you what 
you want (I believe). Until then, I'd stick with ri for unified 
documentation and use RDoc for documentating individual modules.


Cheers

Dave