>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:SAT / MULTITECH.com] 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: 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)