A Dialogue on Literate Programming

In my tirade, Philonous is a friend and user of the WEB environment. He is arguing with Malevolent who's finally going to join the Literate Programming family. Eventually he'll pick up a better name for himself.

[Malevolent still has a hard time to believe though that CWEB is the "only True Web", and he will start and stay with FWEB] IMO, this socratic dialogue could actually have happened like this.

Malevolent: "What are the advantages of LitProg compared to working with small independent well documented routines?"
Philonous: "One can still work with small, independent routines. They're just better documented now."
Malevolent: "I can do well without TeX for documentation."

Malevolent obviously does not believe in DEK. You wonder who's paying him. Philonous does not really know how to answer to that. He probably does not like troff. Or maybe Malevolent has got an eye problem?

Malevolent: "In fact, I hate to spend to much time thinking about how to explain things to others when I haven't even finished the program."
Philonous: "Before I saw WEB, I wasted lots of time finding the right balance between doc and code. With WEB, it becomes easier to write doc along with the code. And update it."

I have only experiences with FWEB, and I haven't been using it for more than one year. Before that, quite a lot of my time went into trying to improve on the delicate balance between documentation and code. None of my private efforts were really satisfying, though. Maybe also because (like many people outside of Computer Science) I never really learnt how to program. Malevolent knows much more about programming, but he's got other things to do as well:

Malevolent: "But isn't this a hell of a lot of extra effort?"
Philonous: "When I saw FWEB, I wasn't even put off because of the extra effort in learning something new. Though I must confess that I asked people in my field of research how long they had needed to get accustomed to the new tool."

Since then, I freely give away the magic number of "10 days"--- if you know [La]TeX and the language(s) you want to code in.

Malevolent: "Ok,Ok,Ok. Now, if you compare how much time it costs you and how much you gain?"

Malevolent is a tough calculator, it seems. He obviously got the message of the zeitgeist.

Philonous: "I cannot speak for you. Literate Programming also is a matter of taste. It is a useful tool for me. It definitely increased my level of reflection upon what I was doing.
It saves me time because the programs mostly do run in the first place - it costs me time because I now like to treat many otherwise neglectable pieces of code like little diamonds - and cannot be sure that this will pay besides aesthetics."
Malevolent: "Of course I have heard about WEB. But I do not know anyone who is practicing it, really."

Later, Philonous will tell him about the Literate Programming mailing list.

Philonous: "True. The `evangelization' part sometimes is the most painful. There's no company working for WEB's success. No commercials placed. Thus, it definitely costs time because I am trying to convince my colleagues that they should try WEB, too. But I am a born missionary anyway and so this meets my needs as well."

He did not really have to emphasize the last point...

The time for our key-hole listening is running out. It suffices to say that the two are having a lot more to discuss. At the end, Malevolent (overloaded with manuals, introductory texts, FAQs, eager to try WEB) wants some advice how to evangelize others:

Malevolent: "Assuming you meet someone who's more benevolent than I am-- how're you proceeding?"
Philonous: "Upon meeting someone who likewise seems to suffer likewise, and who signalizes a genuine interest in learning something new, I first show him a HUGE woven output [yes, I am carrying such a volume around mainly for that purpose]. Before putting the word "WEB" into my mouth I want to hear a SIGH when he is confronted with something which looks unlike anything he has seen yet. Even better if I have presented some more or less complicated program in a talk before: then people are lost and WEAVE's output comes handy to explain---it has got tables, it has got plots, maybe, an index, a table of contents--- Fine. Then the victim usually asks: `why did you put up all the extra work?'"
Malevolent: "That almost sounds like me, before I had seen the light!"
Philonous: "Yes, that is the moment of truth indeed. I start explaining some things for real [forcing the victim to recur to the BEAUTIFUL output in regular intervals determined by the amount of healthy scepticism he's mobilizing to shield himself]. Eventually I show a not-too-complicated .web file. And I give him the speech which I gave you already, my friend. Of course: If I have a FWEB-FAQ output at hand, I'll pass it to him, too."

You have to judge whether this may happen with your colleagues in the same way. Mine are definitely special in that many of them are used that everything comes to them pre-digested. If that is not the case, they'd rather cut on their needs: for fine documentation, for well-structured code etc. Probably this will not hold for the majority of readers of the LitProg mailing list.

Marcus Speh

marcus@x4u.desy.de