From: ES <ruby-ml@...>
Date: 2005-06-18T04:59:04+09:00
Subject: [ANN] Frameless RDoc template ('technology preview')

Hi!

 From a slight frustration with the current RDoc templates and general
boredom I decided to try my hand in implementing one; the main goal was
to get rid of frames in a graceful manner.

The template works and produces (apparently) correct output, but before
I release the actual thing to the wild, I wanted to gather some input.
Folks on #ruby-lang have been kind enough to start on that, and no
showstoppers have been found yet. Please take a moment to view the
site and let me know your thoughts (read Issues and so on below before
mailing, though).

The two issues that will probably come up despite being listed below:
no, the colour scheme is not going to be that (it may in fact end up
customizable) and no, I have not given any thought to Explorer support
yet.


http://www.magical-cat.org/rdoc/rue-functional-1.html



== Issues
- The colour scheme is not final! Will probably go with less... red.
- When generating the docs, one _must_ select +--one-file+
   and +--inline-source+.
- +--one-file+ requires the output file exists or it dumps to stdout.
- The ordering of classes and 'main' file is positionally sensitive
   when invoking +rdoc<+. Essentially, whichever file is processed
   first becomes the 'main' file (displayed initially) and classes are
   displayed in the order their files are read in.
- It is all on one page and there is a bit of JavaScript magick involved
   so the document tends to be large and the initial load is a bit slow
   and choppy; however, once the file has loaded, it works very fast.
- The JavaScript works but is absolutely atrocious.
- Some minor CSS issues.
- Probably will not render right in IE nor possibly Opera. Only actually
   tested on recent Mozilla-stemmed browsers.

== Known bugs
- RDoc stats get inserted into the document (outside the HTML, no less)!
   Would probably have to mess with RDoc internals to correct that. I
   have the distinct feeling that the +--one-file+ option was something
   of an afterthought or side-project.
- Internal links (#) to classes on the pages do _not_ work. All other
   links should be fine. Again, a RDoc-internal issue.

== ToDo / ToFindOut
- Refactor the JavaScript
- Work out CSS bugs
- IE support
- onLoad() will the header and content be paired correctly?
- Adjust colour scheme?
- Make colours overridable?
- Are all RDoc output cases taken into account?


Thanks!

E

-- 
template<typename duck>
void quack(duck& d) { d.quack(); }