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 [http://www.literateprogramming.com/]): * Donald Knuth. "Literate Programming (1984)" in Literate Programming. CSLI, 1992, pg. 99: 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: * it can easily mix free text and source code * it has a way to cross-reference / hyperlink pages * page titles make natural chapter/section names Would there be value in bringing these things together? I think so: * a single wikit document can be an entire self-documenting project (or package) * think of collaborative work, by altering the wiki through the web * there is a local mode, which may become good enough to edit with ''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.