RImport: The ri data-file import tool

Overview

RImport is a Ruby command-line tool that takes RDoc-generated XML files and import them into the ri data set.

Most of the real documentation is in the RDoc stuff, but it should be enough information to get you started.

Dave Thomas, co-author (with Andy Hunt) of Programming Ruby, wrote a program called ri that gives quick command-line help for the Ruby programming language. By default, though, ri only knows about the core classes and modules, not all the members of the standard library. So, you can get help on String or Array, but not Matrix or REXML. Nor does ri offer any simple way to add these or other data files.

RImport works with RDoc and ri to help you add new data files. To add a new data file to ri, you simply need to run rdoc on the source file of choice, specifying single-file XML output; pass the resulting XML file to rimport, which will generate a new Ruby script responsible for creating a new ri data file; execute this new script. (RImport has an option to auto-execute this resulting script, so you can go straight from rdoc XML to ri data file).

To install Rimport, download and extract the archive file, change to the rimport directory, and run

ruby install.rb

This should install the base lib files under your site_ruby directory, as well as a command-line script callable via your PATH. You may need to be root, depending on your Ruby installation and permissions.

To run the unit tests, such that they are, run the script run_tests.rb.

To see an example of calling rimport via the command line, look at the script demo.rb. Running demo.rb should generate the RDoc XML for rimport.rb, then pass it to rimport for processing. The generated source will be written to a file in the same directory. Running that file will create ri data objects in the 'descriptions' subdirectory.

demo.rb also serves as the source for the text XML embedded in the test script, tc_rimport.rb

Caveats

RImport works off of ri, and uses some calls into the ri code. As ri does not have any real notion of data file classification (i.e., it was originally intended for a single set of files, so it assumes all files live in the same directory and are all part of the core distribution), adding a new file has the risk of clobbering an existing file. Further, ri ships with a method index file that stores the names of all methods and the classes and modules that implement them. RImport does not currently update this index.

Also note that the quality of a data file added to ri depends, of course, on the quality of the RDoc comments in the source.

James Britt