* Tom Gilbert (tom / linuxbrit.co.uk) wrote:
> * 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.

Agreed.

> 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)

I'd like to chip in and mention my support for RDoc as well (and not
just because Dave used my Imlib2 bindings as an example ;)).

> 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.

I'm not sure about the stable version, but the CVS version of RDoc does
have a command-line interface (ie, you can output to HTML, XML, and
Windows help files).  I have no idea if the XML and Windows help
templates work properly, though. 

What would be really nice is if ri could do arbitrary API queries,
instead of having hard-coded documentation for the built-in classes,
and if RDoc had an output template for said format.  Because then
you'd have the command-line documentation interface in addition to a
web-based interface, and said documentation would be easily accessible
from the existing ri wrapper interfaces (eg, the emacs, irb, and vim ri
wrappers).

My biggest problems with RDoc at the moment would have to be (ironically)
a lack of documentation for the templates, and less than
spectacular C prototype handling (I'd like an override to explicitly
specify static and variadic method prototypes in the comments, javadoc
or gtk-doc-style).  I've talked to Dave on IRC about the latter; I have
no idea if it's available in RDoc yet (a brief glance over the CVS RDoc
says no).

I agree with Tom about the frames in the default HTML template.  I
realize that RDoc is already template-based, and that the XSL-FO in
contrib can generate a number of output formats, but it would be nice
if those output options were more conveniently available from the
RDoc command-line and Ruby interfaces. 

That said, I still prefer RDoc over any other documentation generators
I've used. 

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

Damn your penguin! :)

-- 
Paul Duncan <pabs / pablotron.org>        pabs in #gah (OPN IRC)
http://www.pablotron.org/               OpenPGP Key ID: 0x82C29562