RE: [Axiom-developer] Re: noweb

[Page, Bill]

On Friday, May 05, 2006 12:02 PM I wrote:
> ... 
> Unfortunately developers still often use editing tools that
> do not properly hide the internal representation of the
> literate document so that on input the escape syntax can
> sometimes seem quite inconvenient. I think the problem
> really lies with these input tools and not with the internal
> representation at all. As a minimum it would be nice to
> have an "import tool" that coerces the external source code
> syntax into the proper internal representation, i.e. something
> that automatically adds the required escape codes. Even better
> might be to have an editing "mode" (in emacs for example)
> which recognizes and appropriately hides this coding for
> the sake of convenience.
> ...

I forgot to add that there is in fact another tool called
'untangle' in the literate programming toolkit. 'untangle'
(perhaps poorly named) is sort of a cross between 'tangle'
and 'weave'. Norman has written:

  "nountangle converts a literate program into an ordinary
  program by turning interleaved documentation into comments."

  noweb man page:

  "'notangle' produces a program with proper spacing and
  indentation. 'nountangle' does that while also transforming
  documentation chunks to block comments."

  http://www.literateprogramming.com/best/anoweb.html

  "To be able to share programs with colleagues who don't enjoy
  literate programming, I modified notangle by adding to its
  pipeline a stage that places each line of documentation in
  a comment and moves it to the succeeding code chunk. The
  resulting script, nountangle, transforms a literate program
  into a traditional commented program, without loss of
  information and with only a modest penalty in readability."

In order to perform 'untangle' in a manner that would be
compatible with a given target source language it would be
necessary for 'untangle' to generate the comments in a syntax
compatible with the target language. This might get pretty
complicated if there are multiple target languages in the
original literate program document or if it contains multiple
top-level root chunks. But this is not really necessary if
we are interested only in reading and editability

In principle 'untangle' could provide a kind of transparent
editing of the source code (including the documentation as
presented in the comments). The non-source code document
structure could be represented exactly by additional "sentinel
lines" added to the comments that relate these comments back
to the original literate program document so that in principle
'untangling' is completely reversible (re-tangle?). But as
you can imagine implementing this inverse operator to 'untangle'
(Note: 'tangle' is not the inverse of 'untangle'!) might not
be so easy. However I think, for example that Leo does exactly
this sort of thing.

Unfortunately 'retangle' is not currently implemented as part
of noweb. But there might someday be a "noweb 3"! See:

http://www.eecs.harvard.edu/~nr/noweb/todo3.html

If 'retangle' was available this would allow relatively
transparent editing of the "untangled" version of the
document and "re-tangling" it back into literate program
format - provided of course that the editor is careful not
to corrupt the structure of the embedded sentinel lines.

Regards,
Bill Page.