19feb03 jcw - Here's a thought... Could we extend/use the wiki model to do Literate Programming?
The idea of Literate Programming is by Donald Knuth (see also [L1 ]):
Let us change our traditional attitude to the construction of
programs: Instead of imagining that our main task is to instruct
a computer what to do, let us concentrate rather on explaining
to human beings what we want a computer to do.Wikit (any wiki in fact) has some striking similarities:
Would there be value in bringing these things together? I think so:
Just rattling the cage a bit...
RS joins in rattling - you've been reading my mail!
KBK comes to the cage door to see who's been rattling it. I think that a number of us have been approaching literate programming on the Wiki obliquely for some time. There are pages (credit RS with the idea) that are both Wiki pages and fully functional Tcl scripts; my own Solving cryptograms is a good example. You can simply cut and paste such a page (or, more often, a portion of the page between rules) out of the Wiki into your Tcl interpreter and go. Yet the page looks like a typical Wiki page, not like a mass of source code.
KBK Clearly, others have been thinking along the same lines as well. Michael Cleverly's wiki-reaper goes in a different direction - assuming that all preformatted text in the page is code, and discarding the rest. It's convenient, in that people editing a page don't need to insert # at the start of paragraphs or set off lengthy discourse with if 0 { ... }. That's also convenient to the reader of the page. While I use # at start of paragraph as the best of the available options, we probably need some sort of postprocessor, perhaps a modified source command.
KBK We also need a better way to maintain the use-mention distinction. Commentary needs a way of talking about the code - perhaps with examples - without those examples getting executed. I've seen Richard accomplish this task by putting if 0 { ... } in places, but that's a pretty dreadful approach. Perhaps we could identify "code to be executed" in another way from "other preformatted text?"
KBK As we develop the scheme, we'll also need supporting tools (starting with an Emacs mode, but continuing to integrate our new notation into the development environment). One of the problems I always had with Knuth's web system was the amount of time a developer had to spend running utilities like weave and tangle to produce documentation and code, and the difficulty of tying the generated code back to the literate source. Surely with the glue that Tcl provides, we can do better.
KBK In short, jcw, you've once again put your finger on the pulse of the community.
RS replies: Yes, the dual-use files (valid Tcl; valid WikiML) make developing, testing, documenting terribly easy - and look much better than long # Courier comments... or carry images etc. No wonder I'm talking of "fun projects" ;-) But if 0 {...} does not appear dreadful to me - it is the recommended way for block comments, and even supported by the byte-code compiler. With auto-wrapping or non-wrapping editors, overlong # lines are less attractive - and the Wiki pages I write mostly start as text files that can fully be Tcl-sourced, so I can test and document on a single file. Only after I put them on the Wiki, they sometimes get edited to lose that dual-use capability.
KBK speaks for CL. JCW innovates beyond the latter's ability to keep up.
AM has some experience using Will Duquette's "expand" for the purpose of intermixing test code with explanatory descriptions. The idea was elegant (IMHO), but requires more elaboration. (Wondering if this will turn into pet project #53 or not ;)