Re: Issues with literate programming DSSSL Script

[MARK.WROTH@xxxxxxxxxxx (Wroth, Mark)]

Continuing the conversation on literate programming, Brandon Ibach
asked (on Tue, 28 Dec 1999 17:33:25 -0600):

Quoting Wroth, Mark <MARK.WROTH@xxxxxxxxxxx>:
> If I correctly understand what Javadoc does, LaTeX has a mode like this
also
> (called 'doc'), intended for documenting LaTeX class and style files.  But
> unless I'm missing something, it does not have a mechanism for re-ordering
> the input in the "tangle" phase (which is essentially non-existent with
this
> approach).  With some languages this is not a serious problem (DSSSL, for
> example). But I would have thought that it was an issue for Java.
> 
   I'm not that familiar with the formal details of literate
programming, per se, so what, exactly, is the "tangle" phase all
about?
   I can't imagine why you'd want a literate programming system to
re-order anything in your code, particularly in Java.  *shrug*

- -Brandon :)

and Frank A. Christoph <christo@xxxxxxxxxxxxxxxxxx>
replied:

I don't remember the syntax for it exactly, but for example if you want
abstract out a subroutine, or present a series of datatype declarations when
you would need "forward declarations":

  @<< build a whatsit and foo the bar >>=
  whatsit bar = buildMyWhatsit();
  foo(bar); // foo that bastard!
  @

  @<< main procedure >>=
  int main(void) {
    initialize();
    << build a whatsit and foo the bar >>
    finalize();
  }
  @

Most modern languages don't really need chunk reordering, (each block above
is called a chunk; an ordering of chunks is called a ribbon) but Knuth was
way ahead of his time, and needed to do real work with stone age tools. He
also used WEB to do things like macros and source versioning (via so-called
change files). Don't forget TeX was originally written in Pascal...!

Prompting Brandon Ibach to reply 

   Ah... so the reordering features of WEB have basically been
replaced by a combination of features built into the languages,
preprocessors, and the more elaborate version control systems, among
other things, I suppose.
   It's been interesting to dig into TeX (I've been going through the
TeXbook again) and think about what the state of the art was when
Knuth created it.  For that matter, what other major typesetting
systems are there, nowadays?  And what do they really have over TeX?


Now for my two cents worth (delayed by being out of the office most of last
week).  Frank captured the basic idea (and I refuse to worry about the
syntax :-), but I'm not sure I agree with his conclusion that "Most modern
languages don't really need chunk reordering".  If we accept the idea that
the key element of literate programming is presentation for human
comprehension rather than machine convenience, I think we wind up needing
the ability to present parts of the code "out of order" with respect to the
underlying programming language(s).  I don't know any programming languages
that are that flexible, although I'll readily grant that I'm not current on
"modern languages".

Returning somewhat to the purpose of this list, I put a reasonably complete
version of the problem I was trying to solve and my solution to it onto the
WWW last week.  It can be found at
http://ourworld.compuserve.com/homepages/markwroth/LitProg.htm (or more
precisely, that page has links to both the Nuweb source and the PDF file
that is the eventual produce of the "weave" branch. I did not post the DSSSL
"tangle" file separately; if someone wants it, let me know.  Comments and
suggestions are welcome; I think I learned enough from this to start
thinking about a DocBook extension incorporating these ideas (the basic idea
being to let DocBook handle most of the "weave" branch :-).

Happy new year to all,

Mark


 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist