** Reply to message from "Jobling C.P." <c.p.jobling@...> on Thu, 28
Nov 2002 13:53:59 -0000

> One of the papers cited in that paper is to a
> technique called "Reverse Literate Programming" proposed by Markus
> Knasmüller (http://www.ssw.uni-linz.ac.at/Research/Projects/RevLitProg/)
> which appears to have a lot in common with Charlie McDowell's proposal.

I don't think it is that close. I wasn't previously aware of any formal
discussion of "reverse LP", but it has come to mind in the past when people
have asked whether it wouldn't be better to leave sources intact and instead
hyperlink external documentation to them. My answer is that this sounds like a
good way to analyse a body of poorly documented code that you have been tasked
to understand, but I don't see it working well for documenting code as it is
being written. It doesn't encourage you to write documentation as you code,
and you would need to continually check what the code coverage of the
documentation was. Also, as you edited the sources, I wonder if the links to
the documentation wouldn't turn out to be fragile & easily broken.

As I understand Charlie's work, it simply changes the LP metaphor a bit.
Normally, where a macro is called within another macro, you just see a
reference to the macro being called. The code which is inserted when tangling
is not inlined into the woven version of the macro (although this is a feature
request for a future version of xmLP). Charlie's proposal takes an interactive
view, where the default is to display a link to the macro being called, but a
user can interactively choose to see what the inlined (tangled) code would look
like. This is a very good idea.

My thoughts as to what an ideal XML LP IDE would be like revolve around what
good WYSIWYG XML editors do. An editor like XMetaL can make most XML document
formats look like a word processor page (note that the next version of Word
also promises this, which could be very interesting indeed). This means that
the documentation can be edited in a WYSIWYG fashion, making weaving
unnecessary unless you need an alternative output format for others to read.
The key addition I would also like to see is "live" tangling, so that as well
as your documentation window, you could have several source windows open
showing how the tangled sources will look. As you edit the macros in the
literate document, you would see live updating of the tangler output in the
source windows, hopefully with the colour coding and incorrect syntax detection
that mainstream programming IDEs now provide. Live tangling would overcome the
(very real) problem of programmers not being sure if they have assembled their
macros correctly or not.

Charlie's solution addresses the same problem, but does so by progressively
displaying tangled output in the middle of the documentation view, while my
thoughts have tended more towards having the tangled code in separate windows.
I think these are complementary approaches, and having both available would not
be a bad thing at all.

Cheers,
Tony.
====
Anthony B. Coates, Information & Software Architect
mailto:abcoates@...
MDDL Editor (Market Data Definition Language)
http://www.mddl.org/