Forum: Ruby Ruby documentation discovery

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
D6c116c4da007cdbbb269e063efb6f76?d=identicon&s=25 John Conrad (Guest)
on 2006-05-10 01:24
(Received via mailing list)
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
12271b6df73fe29930d65586be5a4a70?d=identicon&s=25 Dave Howell (Guest)
on 2006-05-10 02:38
(Received via mailing list)
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. :)

I just have to remember to run it after installing something new.
58479f76374a3ba3c69b9804163f39f4?d=identicon&s=25 Eric Hodel (Guest)
on 2006-05-10 02:53
(Received via mailing list)
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 Hodel - drbrain@segment7.net - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com
D6c116c4da007cdbbb269e063efb6f76?d=identicon&s=25 John Conrad (Guest)
on 2006-05-10 04:15
(Received via mailing list)
On 5/9/06, Dave Howell <groups@grandfenwick.net> 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
D6c116c4da007cdbbb269e063efb6f76?d=identicon&s=25 John Conrad (Guest)
on 2006-05-10 04:24
(Received via mailing list)
On 5/9/06, Eric Hodel <drbrain@segment7.net> 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?
171a9b5755cdb090e0c2b3c20a521fbc?d=identicon&s=25 Phil Hagelberg (Guest)
on 2006-05-10 04:33
(Received via mailing list)
"John Conrad" <john.emerson.conrad@gmail.com> 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
D6c116c4da007cdbbb269e063efb6f76?d=identicon&s=25 John Conrad (Guest)
on 2006-05-10 04:46
(Received via mailing list)
On 5/9/06, Phil Hagelberg <phil@hagelb.org> 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. :)

John Emerson Conrad
Ffcb418e17cac2873d611c2b8d8d891c?d=identicon&s=25 unknown (Guest)
on 2006-05-10 09:23
(Received via mailing list)
*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.
51a34236538906ab994cf9f2e533d14d?d=identicon&s=25 Lou Scoras (ljscoras)
on 2006-05-10 16:25
(Received via mailing list)
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/<package>/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).
58479f76374a3ba3c69b9804163f39f4?d=identicon&s=25 Eric Hodel (Guest)
on 2006-05-10 19:36
(Received via mailing list)
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 Hodel - drbrain@segment7.net - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com
58479f76374a3ba3c69b9804163f39f4?d=identicon&s=25 Eric Hodel (Guest)
on 2006-05-10 19:36
(Received via mailing list)
On May 9, 2006, at 7:31 PM, Phil Hagelberg 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 <name>
                   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 Hodel - drbrain@segment7.net - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com
58479f76374a3ba3c69b9804163f39f4?d=identicon&s=25 Eric Hodel (Guest)
on 2006-05-10 19:39
(Received via mailing list)
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/<package>/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 Hodel - drbrain@segment7.net - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com
Bc6d88907ce09158581fbb9b469a35a3?d=identicon&s=25 James Britt (Guest)
on 2006-05-10 21:44
(Received via mailing list)
Eric Hodel 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 Britt

"People want simple stories."
37ee5fa90f5eaeef62553629382497f7?d=identicon&s=25 Leslie Viljoen (Guest)
on 2006-05-11 00:12
(Received via mailing list)
On 5/10/06, Dave Howell <groups@grandfenwick.net> 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. :)
>
> 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!
D6c116c4da007cdbbb269e063efb6f76?d=identicon&s=25 John Conrad (Guest)
on 2006-05-11 01:46
(Received via mailing list)
On 5/10/06, Eric Hodel <drbrain@segment7.net> wrote:
> $ ri --help
> [...]
>     --format, -f <name>
>                    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
C1bcb559f87f356698cfad9f6d630235?d=identicon&s=25 Hal Fulton (Guest)
on 2006-05-11 01:49
(Received via mailing list)
John Conrad wrote:
> On 5/10/06, Eric Hodel <drbrain@segment7.net> 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
D6c116c4da007cdbbb269e063efb6f76?d=identicon&s=25 John Conrad (Guest)
on 2006-05-11 01:56
(Received via mailing list)
On 5/10/06, benjohn@fysh.org <benjohn@fysh.org> 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.)
58479f76374a3ba3c69b9804163f39f4?d=identicon&s=25 Eric Hodel (Guest)
on 2006-05-11 03:00
(Received via mailing list)
On May 10, 2006, at 4:48 PM, Hal Fulton 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 Hodel - drbrain@segment7.net - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com
0ca6e5c33d7e7ff901d75ff0b13d9e1c?d=identicon&s=25 Sam Roberts (Guest)
on 2006-05-11 06:08
(Received via mailing list)
Quoting phil@hagelb.org, 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
This topic is locked and can not be replied to.