Ruby documentation discovery

Ruby
1

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

2

On May 9, 2006, at 16:23, John Conrad wrote:

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 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.

Huh. I got so tired of trying to play “guess the spelling and
capitalization” with ri, along with the bonus “oh, did rdoc even get
run for that?”, that I wiped the entire directory. I vastly prefer
being able to scroll through an HTML list, and use hyperlinks.
Hyperlinks! Bliss! And multiple windows to compare, say, Process and
Thread, or have Enumerate open along with String! Yay!

Unfortunately, RDoc has quite poor support for HTML. It overwrites
existing files, so to update, you have to re-run it from scratch on
everything. That takes hours.

Fortunately, I have Ruby. I wrote a program (RDC) that generates HTML
documentation via Rdoc for, well, whatever it can find. Gems mostly
arrived with HTML documentation already built for them. RDC doesn’t
regenerate existing documentation. It checks the Ruby core, the gem
dir, and the site dir. Each component gets its documentation stored in
its own subtree, following the gem structure, more or less. Then RDC
builds (or rebuilds, as needed) a master index page that links to all
the other documents, thus providing the critical missing “Home Page”
for Ruby HTML documentation.

A search function would be nice, but that’d involve actually having a
mini-web server or something running, instead of just the static file
structure I have now. This has been working for me more than well
enough to not provoke further tinkering. Which means it’s working very
well indeed. :slight_smile:

I just have to remember to run it after installing something new.

3

On May 9, 2006, at 4:23 PM, John Conrad wrote:

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.

The next release of Ruby and Rubygems will build ri for installed gems.

–
Eric H. - [email protected] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com

4

On 5/9/06, Dave H. [email protected] wrote:

Huh. I got so tired of trying to play “guess the spelling and
capitalization” with ri, along with the bonus “oh, did rdoc even get
run for that?”, that I wiped the entire directory. I vastly prefer
being able to scroll through an HTML list, and use hyperlinks.
Hyperlinks! Bliss!

It’s not that I don’t like hyperlinks - I love them! That’s what I meant
when I said I was spoiled by the emacs style of self-documentation.
However,
hyperlinks are most useful, IMO, if you are able to initally jump to a
specific starting point. Rather than always starting at the root and
clicking down from there.

Fortunately, I have Ruby. I wrote a program (RDC) that generates HTML
documentation via Rdoc for, well, whatever it can find. Gems mostly
arrived with HTML documentation already built for them. RDC doesn’t
regenerate existing documentation. It checks the Ruby core, the gem
dir, and the site dir. Each component gets its documentation stored in
its own subtree, following the gem structure, more or less. Then RDC
builds (or rebuilds, as needed) a master index page that links to all
the other documents, thus providing the critical missing “Home Page”
for Ruby HTML documentation.

Have you released RDC to the public? If so, could you provide a link? It
sounds useful.

Regards,
John Emerson Conrad

5

“John Conrad” [email protected] writes:

It’s not that I don’t like hyperlinks - I love them! That’s what I meant
when I said I was spoiled by the emacs style of self-documentation. However,
hyperlinks are most useful, IMO, if you are able to initally jump to a
specific starting point. Rather than always starting at the root and
clicking down from there.

On a related note, is it possible to get RDoc in GNU Info format? IMHO
that really gives you the best of both worlds in terms of it being
hyperlinked, searchable, and not making you switch out of the editor.

If no such thing exists, could someone comment on how difficult such a
thing would be to implement? (I may smell a challenge here.)

-Phil

6

On 5/9/06, Phil H. [email protected] wrote:

On a related note, is it possible to get RDoc in GNU Info format? IMHO
that really gives you the best of both worlds in terms of it being
hyperlinked, searchable, and not making you switch out of the editor.

If no such thing exists, could someone comment on how difficult such a
thing would be to implement? (I may smell a challenge here.)

-Phil

I guess that’s exactly what I was getting at, Phil, without being clever
enough to say so explicitly. :slight_smile:

John Emerson Conrad

7

snip

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.

I believe your post is about documentation, rather than callbacks.
However: a “callback” is a general term. It’s a function / method that
you register with some entity, so that when that entity encounters a
particular type of event, it will call the registered function. An
example: A widget library may have a button entity. The button entity
may have an “on click” handler that you can register a call back with.
You may register a function that pops up another window, or fires a
space ship’s gun.

There may not be an actual call back class. In Ruby, a call back can be
extremely well modled with a Method object.

snip

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?

You’re not alone. I’ve found that the thing I love about Ruby is how
well it works out of the box (that, and its simplicity, power and
consistency). It is easy to start playing and discovering. The
documentation doesn’t seem to have this property so strongly though. I
think I must be missing some important knowledge of the tools in this
arena, but I’ve not yet found the answer.

8

On 5/9/06, Eric H. [email protected] wrote:

The next release of Ruby and Rubygems will build ri for installed gems.

That will certainly help. But I am more concerned about having ri built
for
all of those classes that are included with the ruby distribution, but
nevertheless must be require’ed before use in programs, such as the
‘open-uri’ library. Do you know if there are future plans to have these
classes also built for ri?

9

On May 9, 2006, at 7:23 PM, John Conrad wrote:

these
classes also built for ri?

ri is rather twisty inside, so I haven’t figured out how to make “you
need to require ‘x’” work well.

There are many methods in both the core and standard library that
aren’t RDoc’d yet. RDocing them isn’t hard, it just needs people
with both the time and the will to do it and submit patches to ruby-
core.

–
Eric H. - [email protected] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com

10

You can always generate the documentation from the source. Whenever I
download a rubygem, the first thing I do is:

$ rdoc -r /usr/lib/ruby/gems/1.8/gems/<package_name>

That sets up the documentation for ri. If you like the linking
functionality (html versions), you can always use a console based
browser. Sometimes I do that too:

$ rdoc -o ~/rdoc/<package> /path/to/source
$ export BROWSER="/usr/bin/links2" # or whatever, might need

frames support, I’m not sure.
$ ${BROWSER} ~/rdoc//index.html

I usually head straight for the ri, but I’m sure you could put
together a nice little system organizing the html locally (Although
you could also run the gem_server for the docs).

11

On May 9, 2006, at 7:31 PM, Phil H. wrote:

On a related note, is it possible to get RDoc in GNU Info format? IMHO
that really gives you the best of both worlds in terms of it being
hyperlinked, searchable, and not making you switch out of the editor.

If no such thing exists, could someone comment on how difficult such a
thing would be to implement? (I may smell a challenge here.)

$ ri --help
[…]
–format, -f
Format to use when displaying output:
ansi, bs, html, plain, simple
Use ‘bs’ (backspace) with most pager programs.
To use ANSI, either also use the -T option, or
tell your pager to allow control characters
(for example using the -R option to less)

–
Eric H. - [email protected] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com

12

Eric H. wrote:

ri is rather twisty inside, so I haven’t figured out how to make “you
need to require ‘x’” work well.

There are many methods in both the core and standard library that
aren’t RDoc’d yet. RDocing them isn’t hard, it just needs people with
both the time and the will to do it and submit patches to ruby- core.

You can get an idea of what libs are in most need of documentation here:

http://ruby-doc.org/stdlib/status.html

–
James B.

“People want simple stories.”

13

On May 10, 2006, at 7:23 AM, Louis J Scoras wrote:

$ export BROWSER=“/usr/bin/links2” # or whatever, might need
frames support, I’m not sure.
$ ${BROWSER} ~/rdoc//index.html

I usually head straight for the ri, but I’m sure you could put
together a nice little system organizing the html locally (Although
you could also run the gem_server for the docs).

Why not just run gem_server? Most packages build their own RDoc anyhow.

–
Eric H. - [email protected] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com

14

On 5/10/06, Eric H. [email protected] wrote:

$ ri --help
[…]
–format, -f
Format to use when displaying output:
ansi, bs, html, plain, simple
Use ‘bs’ (backspace) with most pager programs.
To use ANSI, either also use the -T option, or
tell your pager to allow control characters
(for example using the -R option to less)

I’m not sure what you mean. GNU Info format (more specifically texinfo)
does
not appear to be one of the format options for ri in the --help output.
(Or
is that exactly what you’re getting at? That no such thing exists?)

John Emerson Conrad

15

John Conrad wrote:

On 5/10/06, Eric H. [email protected] wrote:

I’m not sure what you mean. GNU Info format (more specifically texinfo)
does
not appear to be one of the format options for ri in the --help output. (Or
is that exactly what you’re getting at? That no such thing exists?)

I can’t speak for Eric, but I would say: There’s no such
format option, but at least the design allows for creating
new formats, so perhaps that will make implementation a
little easier.

Hal

16

On 5/10/06, Dave H. [email protected] wrote:

A search function would be nice, but that’d involve actually having a
mini-web server or something running, instead of just the static file
structure I have now. This has been working for me more than well
enough to not provoke further tinkering. Which means it’s working very
well indeed. :slight_smile:

I just have to remember to run it after installing something new.

Well come on! Don’t just say “it does this and that and makes coffee
and repairs your NTFS filesystem and launches space stations” and then
not tell us where we can get it!

17

On 5/10/06, [email protected] [email protected] wrote:

However: a “callback” is a general term. It’s a function / method that
you register with some entity, so that when that entity encounters a
particular type of event, it will call the registered function.

Callback might not have been the best example for me to use; it just
happened to be the most recent experience. I knew what a callback
function
does, generally speaking, but when I saw the line “require ‘callbacks’”,
I
started to suspect that perhaps ruby has some sort of “official”
callback
library that I ought to be aware of. It turns out that xmpp4r has its
own
little callbacks library which I didn’t notice at first because the
callbacks.rb file gets installed separately from the rest of the xmpp4r
files. (Not sure why.)

18

Quoting [email protected], on Wed, May 10, 2006 at 11:31:53AM +0900:

hyperlinked, searchable, and not making you switch out of the editor.

If no such thing exists, could someone comment on how difficult such a
thing would be to implement? (I may smell a challenge here.)

Rdoc has a pretty flexible framework to output ‘stuff’. I’d like gnu
info, too, might not be too hard, IF you know the .info format.

Sam

19

On May 10, 2006, at 4:48 PM, Hal F. wrote:

new formats, so perhaps that will make implementation a
little easier.

Yup. You could even go a step further and add an option to RDoc
itself. Right now it knows how to build ri or HTML.

–
Eric H. - [email protected] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com