From: Dave Thomas <Dave@...>
Date: 2000-06-12T09:37:49-05:00
Subject: [ruby-talk:03300] Re: about documentation

Aleksi Niemel� <aleksi.niemela@cinnober.com> writes:

> I, for one, have some doubts the rdtool is the way to go. I might
> make an overkill suggestion, but I feel we should be heading into
> XML-world and maybe make a converter to rd-notation. This said, I've
> not looked rdtool carefully, so I might be way off here.

I have to admit that I think that rd documentation can be
ugly. However, it does have one major advantage--it's in the source.

I guess one of the questions we need to answer is: do we want a single 
master format for all documentation, or is it acceptable to have (say) 
rd for the in-source library documentation and xml for the external
stuff (such as how-to's).

FWIW, I used Linuxdoc for the FAQ, and now regret it. I used XML for
the library reference and found the XSL tools to be
wonderful. However, XSL is limited an producing documentation in
formats other than HTML.

Whatever scheme we use, I've got a tool that filters an XML/SGML
source for Ruby code fragments, executes the code, and substitutes the 
values of expressions back in: we use it in the FAQ and the reference
manual to do all those


   a = 1
   b = 2
   a + b    # =>  3

comments.


Regards


Dave