Re: HTML as GNAT source/Knuth's Web

[smize@news.imagin.net (Samuel Mize)]

In article <01bd3364$2c898c80$LocalHost@xhv46.dial.pipex.com>,
Nick Roberts <Nick.Roberts@dial.pipex.com> wrote:
>Who remembers Don Knuth's 'Web'?

I rememeber it.  I read his example program, and found the amount
of text surrounding the simplest items excessive and confusing,
the style of cross-reference harder to follow, and the program
overall harder to read than normal Ada code.  

In all fairness, I was seeing his program presented as a written
document.  The programs I work on are large systems, and I do a
lot of navigation with cross-reference tables, find and grep.
Perhaps his overall tool suite would provide similar help, but
it didn't seem to me a particularly better way to organize code.

Obviously, other people felt differently:

>This was a wonderful idea (IMHO!)

Some of his ideas were certainly worth using.  For instance:

- his format encouraged you to discuss the program and its design;

- (if I recall right) his book-like organization included a table of
  contents and an index;

- his format broke the program into subsections in which, as in a
  well-written technical document, only one subject is covered.

>Knuth coined the deliberately perjorative phrase "literate programming" for
>this techinique.

I assume from your discussion that you mean it was deliberately
perjorative toward OTHER techniques.

I've actually seen some very good examples of literate programming
in Ada.  (I HOPE I've created some of them.)  Not in terms of using
a web/spider tool, but in terms of writing in a literate style.

To take the points listed above in the same order:

- we don't generally put the design document into the code (or
  vice versa), but we do follow the design or amend it to reflect
  the code.  Ada code, well written, is fairly self-documenting
  at the line-of-code level, so my comments tend to be blocks of
  text that explain blocks of code, as opposed to:

        N := N + X; -- increment N by X

- Various tools provide indexing and cross-referencing to a great
  degree in Ada.  Also, packages can be used not only to control
  namespaces, but to provide a fairly clear top-level organization
  (although in all fairness, they too often are not used this way);

- the use of packages, contained and child packages, and textual
  division with formalized comment blocks provides a good way to
  break the program into cohesive subsections.  Ada 95 improves
  this over Ada 83 by allowing declarations to be freely intermixed,
  so you can declare all related items together.

>The best thing about it (and I suppose the worst too) was that it
>practically forced you to properly document your program as you wrote it.

Nah.  I could write a program using his tools that had virtually
no documentation, not even meaningful identifiers.

The point to the tool, as I understood it, was to promote the idea
of literate programming in WHATEVER tool system YOU were using.  It's
kind of like Pascal, which was originally intended purely as a way to
give students good coding habits.  If Mr. Knuth had higher hopes for
the specific tool he developed, they didn't pan out -- but I didn't
observe any concerted effort to market it, either (maybe I missed it).

>In an industry which highly valued the production of good quality software,
>this idea would have been a breakthrough.  Needless to say, in reality it
>never caught on!

I think it had an impact, and that it also reflected some trends that
were already crystallizing in the industry.  Of course, I'm immersed
in the Defense/aerospace part of the industry, where (at least some)
people already consider reliability and maintainability to be worth
paying for, unlike some companies.  Not to name any major PC OS vendors.

I wouldn't claim that his ideas have suffused the industry, but they
haven't gone totally ignored, although the tool he built generally has.

Best,
Sam Mize

-- 
Samuel Mize -- smize@imagin.net -- Team Ada
Fight Spam - see http://www.cauce.org/
Personal net account - die gedanken sind frei