From: James Britt <jamesUNDERBARb@...>
Date: 2005-01-20T22:34:18+09:00
Subject: Re: Best ways to accelerate Ruby's popularity

Ilmari Heikkinen wrote:
> Re: ruby-doc.org
> 
> Is there a way to access a class documentation at a certain method 
> anchor with an url?
> I'm not very clear, maybe this example will be clearer:
> 
> http://www.ruby-doc.org/find/Enumerable%23map
> would go to Enumerable#map anchor on the Enumerable page. And it would 
> have all the navigation frames there, so it's not a place to get 
> stranded in.


Not at the moment.  Those doc pages are generated from rdoc, and the 
anchors to method names a re abstract strings, not the method names 
themselves.  So you get this:

http://www.ruby-doc.org/core/classes/Enumerable.html#M001864

You need to know that M001864 is the 'map' method.


Now, there is an alternative:

http://www.ruby-doc.org/find/pickaxe/Enumerable#map

though this is calling into an HTML version of the first edition of 
Programming Ruby, by Dave Thomas and Andy Hunt.  It is not the most 
current documentation.

(There was a similar URL look-up system for ri, but it relied on the XML 
  formatting option that apparently has been removed from the current 
ri, and I haven't managed to fix this yet.)


> 
> Reason I'm asking is that I'd like to open the ruby-doc doc page in a 
> webbrowser with Enumerable.help:map. That is with the IHelp 
> irb-ri-access library. Is this okay btw, or does it put too much burden 
> on the site?

Depends.  How often would there be requests, and by how many people? 
Put another way, how does this differ from people viewing the pages 
directly in a browser to help them while coding?

I don't see a problem.  In general, I like the idea of serving up data 
services for remote applications, though in practice I would have to see 
how the bandwidth goes if ruby-doc had a more direct Web API for 
accessing documentation.  (Though the data format should be something 
other than HTML 4.)


> 
> If it'd be php.net like docs then it'd be even greater: access docs 
> _with comments by people who have used it_ from irb, and maybe 
> contribute your own notes.

I would like that, and have taken some stabs at writing a wrapper that 
would allow comments on arbitrary HTML pages, but have gotten 
sidetracked by numerous other projects.

> 
> If this reads very badly (does), ask and I'll try to explain

No, I think I understand. It is a problem that one cannot easily locate 
and/or bookmark specific methods and classes.  The framed view of the 
docs is handy for certain things, but not others.  And allowing comments 
on the docs would be sweet.

It is yet another item on my "This has been taking forever" ruby-doc 
rewrite.


James