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

Douglas Livingstone wrote:
> On Thu, 20 Jan 2005 11:55:50 +0900, Luke Galea <lgalea@gmmsolutions.com> wrote:
> 
>>As a recent adopter of Ruby I've gone through some of the pain of finding ruby
>>docs for the uninformed.. and I know it seems stupid but the fact that the
>>"Core API" and "Std-Lib" aren't on the "Documentation" page on ruby-doc.org
>>threw me off..
> 
> 
> Are there non-frames versions of these pages?
> 
> The frames always seem to get in the way to me... and all the
> bookmarking problems frames have too...

The code comes from rdoc, using the (standard? default?) framed view.

Those doc pages need, among other things, a more linear format, and a 
way to easily associate comments and annotations with specific paragraphs.

I really do like how PHP.org does its docs. For example,
  http://us2.php.net/manual/hk/function.array-reverse.php

Tells you about the array_revese function, shows user comments that 
(ideally) can clarify or correct the docs, and lists the other Array 
function.

There doesn't seem to be a way to associate a note with a specific 
location on the document (though I can imagine a few ways to do this 
with JavaScript), which would be killer.

Here's a "Please Write My Code For Me" request: an app that knows how to 
render any given (X)HTML doc (local or via URL), along with a comment 
section.  With spam protection (hey, just forbid links).  With the 
option to click anywhere on the main doc and add a virtual post-it or a 
footnote comment.  (Sorry, but that'll likely be JavaScript, not Ruby. 
Well, until the Firefox folks wise up.)

C'mon, you Railers could do this in your sleep.

James