In the Tcl chatroom, Steve Landers and RS discussed the possibility to hook Tk demo scripts into Tcl Tutor or a similar UI, which would display a button to run the demo.

Thinking slightly further, RS would like to write demo scripts that can run standalone (valid, self-contained Tcl scripts), but also be rendered as Wiki pages, and finally match the planned demo framework, so they could be loaded into that.

The Wiki display (which could be reused for the explanation field) is currently done by enclosing the whole comment in an if 0 {...} command.

The demo framework could first be conceived as a parser that untangles the source script's explanation and code portions. The Run button is trivially done, and should of course catch execution errors (as the code might have been misedited). Maybe a safe interpreter should be considered too.

15 Oct 2002 escargo: In what sense do you mean, "untangle"? As in the sense of tangle [1] from literate programming [2]? It would be really cool if there were a general way to combine the program and documentation into a single file.

AM (17 october 2002) For Tcl scripts, there is such a way. We have to thank RS for bringing this idea to the attention of Wiki readers and contributors, but here is the principle:

   if { 0 } {
 This text is not seen by Tcl (well, unless you use braces in it) and you can format it according to the Wiki rules (or anything you want to try yourself)
   }

RS created the Wiki page DOS BAT magic that says it all.

escargo: How would we distinguish between the script's explanation and other text that an author (or developer) decides should be ignored? Perhaps a convention about a token that would flag the contents as explanation.

---

For standalone scripts, it is natural that the toplevel "." belongs to them, so the framework would make its own toplevel, and clear "." before running the code.

Thinking even further, perhaps incorporating from TclPro or Tuba to animate/step thru the code will enhance the value of the framework as a teaching tool (anyone remember the original Java example demonstrating various sorting algorithms?) --- stevel

LV Take a look at the demo frameworks used in tk, itcl, BWidgets, and the source for Effective Tcl/Tk - these give you some currently existing frameworks from which you might be able to work. Most, if not all, of these provide the explain/source/execute model. Or grab http://www.tcl.tk/starkits/tcldemo.kit and get them all in one SD - stevel

---

bryan oakley sez... Perhaps a simple API is called for. Tk could create a namespace named Demo, with child namespaces named after the packages. So, tk's demo would be in ::Demo::Tk, BLT's in ::Demo::BLT, etc. That, or reverse it so that every package has a Demo namespace below it (::tk::Demo, ::BLT::demo, etc).

Once done, the namespace could make available two or three commands, such as:

    ::Demo::tk::show pathName

    builds a demo rooted in path$name

    ::Demo::tk::info description

    returns the description of the demo

    ::Demo::tk::info code

    returns the code (trivially implemented as ::info
    body ::Demo::tk::show, perhaps)

    ::Demo::tk::info title

    returns the demo "title", suitable for use as a frame title
    or item in a hierarchical listbox or popup or whatever.

The demo application, then, would be fairly trivial. It could gather up all namespaces under ::Demo, create a listbox based on the results of ::Demo::$whatever::info title, and put in a mechanism so that when an item is selected, the contents of another window are updated to include the rendered demonstration and/or the code.

Thus, any package that conforms to the official demo API will automagically be made available by the demo application without any extra demonstration steps.

This API could be put in a separate package so that it doesn't get loaded unless necessary. So a package index file might have two entries per package:

    package ifneeded myCleverPackage 1.0 ...
    package ifneeded myCleverPackage-demo 1.0 ...

---