Re: an interesting perspective on documentation

[simpson@minotaur.uucp (Scott Simpson)]

In article <8902271704.AA12256@ajpo.sei.cmu.edu> cyclops@TAMUNIX.BITNET (Glenn Vanderburg) writes:
>The thing about WEB that has had the biggest impact on me is something
>that Knuth just hints at, and never explicitly states (so far as I
>know).  The title of the WEB manual is "The WEB system of structured
>documentation," and while that's the only mention of the phrase
>"structured documentation," I think that it's the pivotal phrase of
>the entire document.  It really makes a difference to see the central
>task of programming as documentation.  Now, the main audience is
>readers, not the machine.  And, with a little discipline, you can
>structure the documentation so that the machine can understand and act
>on the same document.  And you don't even have to use WEB to do it!
>
>Thoughts?  Not a panacea, certainly, but it's a very intriguing idea.

I like WEB and I think mixing program and documentation is a good
idea.  I wish there was an Ada version so I could experiment with it.
I don't ever use Pascal any more.  I imagine an Ada version would have
slightly different WEB control sequences though since the semantics of
the two languages differ.
	I have some problems with it though.  First, WEB utilities
(i.e., tangle, weave) act as preprocessors.  I usually don't
like preprocessors because you lose semantic information that debuggers
and other tools need.  This is one reason I thank God Ada does not use
a preprocessor and Stroustrup added constants to C++.  With WEB, you
can get errors at 3 levels: from WEB control sequences, from TeX
control sequences and from Pascal code.  Trying to find where the
errors are coming from can be somewhat confusing.
	I have another granularity problem with the way Knuth divided
up the code in TeX.  The code is divided up into so many small
chunks that it is hard to keep track of what goes where.  He has
devised an indexing scheme (i.e., the <...> notation) for keeping track
of all these divisions but I still think the level of "exploding" code
needs further investigation.  I like just putting comments at the
beginning of procedures/functions.  Other people differ.  I think the
name WEB for the TeX code is an accurate description though!

[[ Perhaps this discussion should move.  I leave it to someone else to
do this.]]
	Scott Simpson
	TRW Space and Defense Sector
	oberon!trwarcadia!simpson  		(UUCP)
	trwarcadia!simpson@oberon.usc.edu	(Internet)