From: Eric Hodel <drbrain@...7.net>
Date: 2011-08-09T03:18:16+09:00
Subject: Re: Brainstorming ideas how to improve Ruby's documentation

On Aug 7, 2011, at 5:52 PM, Alexey Petrushin wrote:
> Text itself is fine, but I agreed, RDoc output is ugly and unusable
> 
> Why can't it be like this http://railsapi.com/doc/ruby-v1.9.2


It's hard to link into frames.  Here is a link to the documentation of OpenSSL::X509::Name::new:

http://railsapi.com/doc/ruby-v1.9.2/classes/OpenSSL/X509/Name.html#M006274

How do I get to the top-level OpenSSL documentation?  Where is the navigation sidebar?

Links to external sites end up wrapped in nonsensical navigation from the frame.  From the main page go to Net::HTTP then click the link to http://www.ietf.org/rfc/rfc2616.txt.

While both of these problems with frames are solvable, nobody has bothered to.

If you want RDoc to have a different template that is not "ugly" by default then please write and popularize it.  I probably won't accept one using frames, though.  (The same page layout features can be accomplished in modern browsers through CSS.)