From: Hugh Sasse Staff Elec Eng <hgs@...>
Date: 2000-06-13T10:17:55+01:00
Subject: [ruby-talk:03352] Re: about documentation

On Mon, 12 Jun 2000, Conrad Schneiker wrote:

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

This is why I wrote:

"[...]keywords and formats that have been accepted by the Ruby community.  
This is so work is not duplicated, and the multiplicity of formats does
not get out of hand."


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

The article says:

"Knuth's other idea was that the best order to explain the parts of the
program in a journal article is not going to be the same as the order that
the computer needs to see the code."

A few months back I asked for an enhancement to RDtool for this purpose,
saying that POD did not have this feature.  I was told that RD docs were
to be kept simple, so that my request to have things appear in a different
order from that in the code would not be implememnted.  I should have
known that Knuth got there first!  Citing him might have strengthened
my argument. :-)   This is why I have been looking for other formats
after examining the otherwise splendid RDtool.

I would like to generate manual pages from the code, for one thing, 
and possibly internal documentation separately, from the same code, as
well.   This is applying the "Don't Repeat Yourself" principle.

I would like to see RDtool become to POD what Ruby is to Perl :-)
"There's A Better Way To Do It" and all that.

> --
> Conrad Schneiker
> (This note is unofficial and subject to improvement without notice.)
> 
> 
	Hugh
	hgs@dmu.ac.uk