[ruby-talk:24670] Re: kill rdtool?

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

The more I think about this approach the more I like it. We could also
do automatic hyperlinking for recognized names (class, method, constant,
etc.). To prevent unintended linking on short names (like the class
"Book"), we could only look at styled text for such links (line _Book_
or *Book*). So if I extend this example, we might get something like
this:

#
# A class all about books
#
# Author:  Jason Voegele
# Version: 1.0
#
# This class organizes books by
# 1. Author
# 2. Title
# 3. Subject
#
# A collection of books is organized into
# a _Library_. Both libraries and books were
# designed to be specialized. An example of
# this is the _MedicalLibrary_ which only
# contains instances of _MedicalBook_s.
#
# Its performance characteristics are as below:
#
# Num Books		Processing Time (in secs)
# 10			.001
# 100			.01
# 1000		100.5
# 10000		234,330,440.34
#


Curt Hibbs
Coyote Software


-----Original Message-----
From: Steve Tuckner [mailto:[e-mail]] 
Sent: Thursday, November 08, 2001 7:02 AM
To: ruby-talk ML
Subject: [ruby-talk:24660] Re: kill rdtool?


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: [e-mail] [mailto:[e-mail]]
Sent: Wednesday, November 07, 2001 9:27 PM
To: [e-mail]
Subject: [ruby-talk:24629] Re: kill rdtool?


>>>>> "Dave" == Dave Thomas <[e-mail]> 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     [e-mail]    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)