------art_56763_13596852.1147216991024
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline

I spent the day trying to grok the examples in xmpp4r (xmpp/jabber library
for ruby; http://home.gna.org/xmpp4r/), and I ran up against a problem that
I've had many times before, but haven't found a good solution to yet.

Here's the gist of it: I'm not aware of a good, solid, universal method for
discovering the documentation of various libraries, classes, and methods in
Ruby.

I saw some code that said "require callbacks". I saw that it referenced a
Callback class. So I went to the terminal and typed ri Callback, but ri said
nothing was known about Callback.

Just for fun, I fired up irb and tried require-ing 'callbacks', but that did
not work either, irb said there was no such file to load.

Maybe callbacks is not the best example; I don't know - I'm still in the
dark about what they are (though I can imagine what they probably do,
generally).

Anyway, I've had this problem plenty of times before. And eventually, if
Google is unable to help (which has been the case so far with class
Callback), then of course it isn't a big deal to grep the Ruby library
and/or sources and figure it out once and for all. But I like ruby so much
and I feel that it deserves a better, more integrated solution for allowing
users, especially newbies, to *discover* documentation - even if something
has been left undocumented, at the very least I should be able to discover
where the source file resides (if it is available).

I realize that ruby might already be head and shoulders above the average
competition in this department - I don't want to sound like ruby is uniquely
lacking in this regard (because I honestly don't know how the other similar
languages handle documentation discovery). Perhaps I'm spoiled by emacs,
where it's always a simple matter to jump to the documentation of a loaded
emacs function or library - and, from the documentation, to jump to the
actual source file from whence it was loaded.

I love ri, when it knows about what I'm asking it, but too often it is
unaware of the class or method I'm referring to. I think gem_server is
nifty, but I prefer ri in most cases because it takes a specific argument
rather than making me browse through web pages with my mouse.

I realize (I think!) that I could finesse ri's database into something that
is closer to what I want by making some rdoc incantations - and I'm happy to
hear from anybody who does this and is satisfied with the results.

I'd also love to hear from anybody who shares my frustration (am I alone?)
as well as any ideas for going forward. Are there any efforts afoot where I
could lend a hand?

Thanks for any input,
John Emerson Conrad

------art_56763_13596852.1147216991024--