From: Conrad Schneiker <schneik@...>
Date: 2000-06-12T13:46:41-05:00
Subject: [ruby-talk:03330] Re: about documentation



Dave Thomas wrote:

> Hugh Sasse Staff Elec Eng <hgs@dmu.ac.uk> writes:
>
> > Also, it is important that from the outset these formats consist of
> > printable characters only.  The bi-lingual nature of Ruby development
> > makes this an interesting definition, but what I don't want to see is
> > embedded Word documents, and other such binary stuff!  Do people agree
> > that this is a sensible constraint?
>
> Before we go reinventing too many wheels here, <continued below>

You took the words right off my keyboard. ... Except I had a different
question: What does the Python community use? Does it already adaquately
deal with the issues raised here?

Also to widen the scope of these considerations a bit, I want to draw your
attention to an interesting article,

    "POD is Not Literate Programming"

(where POD is Perl-eeze for "Plain Old Documentation") at

    http://www.perl.com/pub/tchrist/litprog.html


> <continued from above> why don't we all just
> try rdtool? It has a big following, and much of the RAA is already
> documented using it. Let's try it for 6 months before deciding to use
> something different.

This is probably a good idea.


> At that time, rd2xml wouldn't be too hard to
> write (I hacked up rd2latex for the book in about 15 minutes).

Why wait (if someone is willing to do this now)?

--
Conrad Schneiker
(This note is unofficial and subject to improvement without notice.)