I agree that the using a "human oriented syntax" for program information
would fit very well with Matz' description of Ruby as a "human oriented
language". The important thing about it is that it act in a understandable
way so that you don't wonder: why did it do that? 

One time I ran across a formatter that would take plain text and convert it
to HTML. I couldn't seem to get back to this original link but I did find
two programs: AscToHTM: http://www.jafsoft.com/asctohtm/, and txtxhtml:
http://www.aigeek.com/txt2html/ by looking on DMOZ:
http://dmoz.org/Computers/Software/Internet/Authoring/Converters/. These
converters take regular ASCII style conventions for lists, tables, sections,
etc and convert them into their HTML equivalents. By their examples, they
both look quite "smart", but maybe not predictable as I'd like (I don't know
as I haven't actually tried them).

If we wrote a parser that did this smart, predictable ASCII parsing, then
both our generated documentation and source documentation could be
beautiful.

Below I have enhanced the example given by Dave Thomas to include things
that could be converted into HTML lists and tables.

#
# A class all about books
#
# Author:  Jason Voegele
# Version: 1.0
#
# This class organizes books by
# 1. Author
# 2. Title
# 3. Subject
#
# Its performance characteristics are as below:
#
# Num Books		Processing Time (in secs)
# 10			.001
# 100			.01
# 1000		100.5
# 10000		234,330,440.34
#

Steve Tuckner 

-----Original Message-----
From: jweirich / one.net [mailto:jweirich / one.net]
Sent: Wednesday, November 07, 2001 9:27 PM
To: ruby-talk / ruby-lang.org
Subject: [ruby-talk:24629] Re: kill rdtool?


>>>>> "Dave" == Dave Thomas <Dave / PragmaticProgrammer.com> writes:

    Dave> In the 90% complete things I'm writing (it's been 90% complete for
    Dave> months) you'd write

    Dave> #
    Dave> # A class all about books
    Dave> #
    Dave> # Author:  Jason Voegele
    Dave> # Version: 1.0
    Dave> #

    Dave> class ...

I really like this.  It is lightweight and non-intrusive.  I find many
doc systems tend to obscure the source code in favor of making the
docs easy to generate.  This and the Wiki formatting suggested later
in this thread sound good to me.

-- 
-- Jim Weirich     jweirich / one.net    http://w3.one.net/~jweirich
---------------------------------------------------------------------
"Beware of bugs in the above code; I have only proved it correct, 
not tried it." -- Donald Knuth (in a memo to Peter van Emde Boas)