Confused abour 'ri' in 1.8.1?

[Frank Mitchell]

Sorry if this has been asked before, but ...

While 1.8.1 contains the 'ri' main program and runtime (and RDoc
extensions), it doesn't seem to include the documentation for builtin
classes (i.e. the *.c files). Furthermore, my laptop is a Machine of
Very Little Brain, and running 'rdoc --ri lib/*' takes a very long time,
and a few randomly sampled files didn't seem to have any RDoc comments
in them.

The last version of 'ri' that actually provides documentation is
ri-1.8b.tgz, which claims to be a test version and produces the warning
"don't put space before argument parentheses". So, my questions are:

1. Where do I find the latest/final documentation for 1.8.1 builtins in
'ri' format, or suitable for processing by the 1.8.1 rdoc/ri?

2. How much of the 1.8 library (including extensions) has RDoc comments
and/or pregenerated 'ri' files?

3. *Can* I run rdoc on *.c files, and expect a meaningful result?

I'm still getting used to Ruby, and I depend on 'ri' to find the Ruby
Way. Pointers to an earlier discussion, or direct answers, would be
appreciated.

Thanks in advance.

 

[jbritt]

1. Where do I find the latest/final documentation for 1.8.1 builtins in
'ri' format, or suitable for processing by the 1.8.1 rdoc/ri?

I believe that there is, as yet, no actual repository for this. Since
these files can be generated from the Ruby source, the ideal place to
get the ri data files is from the source code you're actually using.

However, for those with slugish machines, having a separate download
might be a good thing. As far as I know, ri data files created on one
machine should be viewable on another, so long as ri knows where to find
them.

If it seems worthwhile, I can generate the ri files for 1.8.1 and host
them on ruby-doc.org.



James Britt

 

[Harry Ohlsen]

If it seems worthwhile, I can generate the ri files for 1.8.1 and host
them on ruby-doc.org.

That would be excellent.

H.

 

[Gavin Sinclair]

[James:]

If it seems worthwhile, I can generate the ri files for 1.8.1 and host
them on ruby-doc.org.

To me, that's a good idea anyway, as any clutter from the output can be
removed (e.g. ExceptionForMatrix).

A simple program can be written that:
- defines the input files for 'rdoc'
- decides which files actually need to be generated, based on
input and output timestamps
- run 'rdoc'
- post-process the output to remove the aforementioned "clutter"
- generates a tarball of the 'ri' data
- uploads it to ruby-doc.org

Sounds like a job for Rake. I actually implemented most of the above for
"rjay" at some stage.

Gavin

 

[Dave Thomas]

If it seems worthwhile, I can generate the ri files for 1.8.1 and host
them on ruby-doc.org.

Please don't, yet: things are changing.

For now, everyone can generate their own RDoc documentation which is
equivalent to (actually better than) the original 'ri' by doing

rdoc --all --ri *.c

in the main Ruby source directory of the CVS distribution. As of
tonight, it documents every single built-in class, module, and method.
On my fairly pokey laptop, this doesn't take too long:

dave[ruby/ruby 23:32:01] rdoc --all --ri *.c

array.c:
bignum.c:
....
variable.c:
version.c:

Generating RI...

Files: 39
Classes: 61
Modules: 16
Methods: 1094
Elapsed: 55.074s

Pretty soon this will all be transparent: the ri documentation will be
available out of the box.

As for the lib/ and ext/ stuff: rdoc runs OK on it all (see below), but
to be honest the quality of the documentation in there is very patchy.
I frankly wouldn't bother with the lib/ documentation for a while.

In the meantime, I'm more than happy to answer questions about the
documentation stuff.


Cheers

Dave


ps.

Running the latest RDoc on the interpreter and lib/ yields:

Files: 114
Classes: 328
Modules: 76
Methods: 2681
Elapsed: 349.075s

 

[Dave Thomas]

[James:]

If it seems worthwhile, I can generate the ri files for 1.8.1 and host
them on ruby-doc.org.

To me, that's a good idea anyway, as any clutter from the output can be
removed (e.g. ExceptionForMatrix).

Why wouldn't you just use :nodoc: and the new .document files?

Cheers

Dave

 

[Gavin Sinclair]

[James:]

If it seems worthwhile, I can generate the ri files for 1.8.1 and
host them on ruby-doc.org.

To me, that's a good idea anyway, as any clutter from the output can
be removed (e.g. ExceptionForMatrix).

Why wouldn't you just use :nodoc: and the new .document files?

Ah, good thinking. I don't know what the new .document files are, though.

Gavin

 

[Gavin Sinclair]

As for the lib/ and ext/ stuff: rdoc runs OK on it all (see below), but
to be honest the quality of the documentation in there is very patchy.
I frankly wouldn't bother with the lib/ documentation for a while.

At http://www.ruby-doc.org/stdlib, you can see which lib/ files have
mature documentation, both as a visual cue in the TOC, and via the status
report.

Gavin

 

[Harry Ohlsen]

Hi David,

I successfully built the ri documentation from last night's snapshot on
my Linux box at home. Looks excellent!

If I wanted to transport the output to my Windows 2000 box at work, what
files should I copy, and to where?

It looks like all of the actual documentation ended up in the
/root/.rdoc directory. I'll work out how to make that accessible to
other users on my Linux box later (I'm assuming ri will check somewhere
under /usr/local in addition to the ~/.rdoc directory).

Where should those files go on a Windows system in order for ri to be
able to find them? Can they be used with the ri in 1.8.1 stable, or
only with the CVS version? I guess potentially some of the
documentation may only be valid for the CVS version, of course.

Cheers,

H.

 

[Dave Thomas]

It looks like all of the actual documentation ended up in the
/root/.rdoc directory. I'll work out how to make that accessible to
other users on my Linux box later (I'm assuming ri will check
somewhere under /usr/local in addition to the ~/.rdoc directory).

Just run 'rdoc --ri-site and it'll put it in a site-wide directory

Where should those files go on a Windows system in order for ri to be
able to find them? Can they be used with the ri in 1.8.1 stable, or
only with the CVS version? I guess potentially some of the
documentation may only be valid for the CVS version, of course.

To find the location of the site-wide documentation directory, you can
use the command

ruby -r rdoc/ri/ri_paths -e 'p RI:aths::SITEDIR'


The 'ri' in the released 1.8.1 is old and has some bugs. The one in the
1.8.1 branch of CVS is identical to the 1.9 one.

Cheers

Dave