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 [http://www.cs.virginia.edu/cgi-bin/manpage?section=1&topic=tangle] from literate programming [http://vasc.ri.cmu.edu/old_help/Programming/Literate/literate.html]? 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 a 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://mini.net/sdarchive/tcldemo.bin 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 ...