From: Tom Gilbert <tom@...>
Date: 2002-07-23T19:31:06+09:00
Subject: Re: rdtool and rdoc

* David Douthitt (DDouthitt@cuna.coop) wrote:
> I took a look at your comparison page.  I've not used either, but some things stood out to me...
> 
> What stands out to me is that the RDTool result is simple, single-paged, and presumably easy to print or to convert to other forms via printing.  It also is likely to be easy to read in lynx and other similar browsers (including speech-enabled browsers for the blind).
> 
> The RDoc result is heavily frames-based and seems specifically designed for Web-access.  It's cute and quite usable in the Web context, but likely not as easily accessible outside of the Web.
> 
> For me, seems like RDTool is more generally usable.  Also, programmers SHOULD write documentation - and keep it up to date.

RDtool doco is a pain to maintain and keep up to date, and it doesn't
"fit" with the language that surrounds it.

I would always vote for RDoc here - it's effortless to use, and easy to
maintain. (http://linuxbrit.co.uk/rbot/doc/ -> better API documentation
than I've ever produced before)

However, there are some issues that need to be fixed. Frames are horrid,
and RDoc shouldn't produce them. And rdoc needs to have a commandline
interface so it's not quite so HTTP biased. I need to be able to query
api documentation from the commandline -> man/perldoc style output would
be a great feature.

Tom.
-- 
   .^.    .-------------------------------------------------------.
   /V\    | Tom Gilbert, London, England | http://linuxbrit.co.uk |
 /(   )\  | Open Source/UNIX consultant  | tom@linuxbrit.co.uk    |
  ^^-^^   `-------------------------------------------------------'