From: Eric Wong <normalperson@...>
Date: 2011-08-06T05:32:58+09:00
Subject: Re: Brainstorming ideas how to improve Ruby's documentation

Marc Heiler <shevegen@linuxmail.org> wrote:
> If you do not believe me, click on it:
> 
>   http://www.ruby-doc.org/core/
> 
> There you have it. HTML Frames in all their ugly glory.

I hate frames, too, but I find the non-frame Darkfish layout
in RDoc 2/3.x very usable with lynx and Vimperator (firefox).

Darkfish is even usable without JavaScript[1].  In fact, I don't think
I'd have halfway usable websites for my Ruby projects without
Darkfish.

One (important (to me)) thing I do with my RDoc + Darkfish sites is
remove the default index.html and and replace it with the HTML for
README, leading to an index column on the left.

Contrast the following two, I prefer the latter to be the default
index page:

	http://rdoc.rubyforge.org/index.html
	http://rdoc.rubyforge.org/README_txt.html

While I'm bikeshedding, I do wish RDoc didn't use icons/JS at all.  The
The only useful tags in HTML to me are <a>, <title> and <pre> :)
However, I don't think I'm representative of the Ruby community at
large.


[1] I wrote wrongdoc to strip JS from all the RDoc I upload to
    bogomips.org: http://bogomips.org/wrongdoc/
    I couldn't get alignment to work right w/o icons, though...

-- 
Eric Wong