From: James Britt <james_b@...>
Date: 2005-06-08T01:51:55+09:00
Subject: Re: Could Ruby-doc be better? -- Proposal for a better system.

Andrew Thompson wrote:
> So, basically the consensus is that Rdoc is in need of some work, 
> especially as regards the .c files, that online editing of the docs 
> directly isn't required, but that the current ruby-doc doc browser is a 
> bit crufty and could be done better and preferably without frames.

The 'ruby-doc browser' is just basically what rdoc emits.  The available 
Rdoc templates leave something to be desired.  There has been talk here 
in the past on writing a better set of templates to avoid using frames 
(or use them in such a way that at least one can bookmark or easily link 
to pages for specific classes/modules/methods).

(Of course, while there is room from improvement for presentation, the 
real work is in updating the docs themselves.  Coding, however, always 
has more appeal.)
...
> James, could you fill me in on what you're working on as regards this 
> whole thing, maybe we can pool our efforts on this...

There are few ways to approach this.  The first one I've looked at, and 
done some work on, is altering the rdoc template so that each page shown 
in the lower frame has a link for adding comments.

The idea would be to also dynamically include existing comments into 
that frame as well.

But it occurred to me that a fairly simple alternative is to have each 
main page just link to a corresponding wiki page.  It is perhaps not as 
slick as having the comments appear on the same page as the docs, though 
it has the advantage that if you open the wiki link in  new window it is 
easier to browse both the docs and the comments at the same time.

This seems like such appealing, low-hanging fruit that I may just do 
this anyway; if it turns out to be insufficient then it can be changed 
later.

(Ruwiki seems a good choice of wiki for this, with a sub-wiki project 
for each class or module)

The usual caveats on wiki spam apply.

Another approach might be to integrate the doc pages with the comments 
system directly a la php.net

(Some ways of doing that: dynamic template parsing that merges the API 
docs with comments fetched from some storage system, which is where my 
recent efforts have been;  using DHTML and remote scripting to post and 
fetch content from some service.  I sort of prefer this latter idea, 
using XMlHttpReqquest to fetch the content from a wiki's RSS feed.)


> 
> Oh, it looks like I'm getting replies from ruby-talk and ruby-doc, 
> anyone have any objections on moving this discussion to ruby-doc only 
> now that there's a discussion going? The only problem is that ruby-doc 
> doesn't seem to be publically archived anywhere like all the other ruby 
> mailing lists are...

There was , once upon a time, an specific archive. The list is carried 
by gmane and they have an archive or something like that:

http://news.gmane.org/gmane.comp.lang.ruby.documentation

James
-- 

http://www.ruby-doc.org - The Ruby Documentation Site
http://www.rubyxml.com  - News, Articles, and Listings for Ruby & XML
http://www.rubystuff.com - The Ruby Store for Ruby Stuff
http://www.jamesbritt.com  - Playing with Better Toys