Purpose: Discuss what one needs to do to create a starkit for a script only extension.
The idea is to end up with a single file which contains all the information needed for an extension. Ideally, at some point in the future, a Tcl application might say
package require FunnyStuff
and Tcl would find FunnyStuff-1.7/funnystuff.kit , mount the starkit, and automatically load the package into the interpreter so the enclosed commands might be used by the program.
Well, right now, people distribute extensions via a tar or zip file. Typically, one must at least extract the files from the archive, and, in some/many cases, then one must do some kind of install process to copy the files over to the destination, install the documentation and demos, and so forth.
[Someone want to address the second question of this point?]
Well, that's the part of the idea I've not quite figured out. I mean, sure, one could create the .kit so that if you ran it from the command line, you would get a demo program and hyperlink documentation set. But that format, at least for doc, is less useful than having the docs all in one place, capable of being searched when you don't know what extension holds the functionality you seek.
Then there's the general frustration of having to look all over the place for demo/examples of the extensions. Some extensions install the demos, some don't, and some don't even have extensions. It would be so lovely if tcl came with a framework where an extension, when installed, could install demos of its commands, widgets, etc. so that the user might invoke a single demo top level program and all the registered demos were available.
I currently doubt there's a single good solution to address all of these problems.
One approach to solving the doc problem would be to have a command line command which copied .man format files into the appropriate directory. Below, jcw mentions using a wikit as an embedded help system. The difficulty there is discovery - if someone knows they want help with a command, then that works okay. But if they are looking to see what tcl commands provide pop3 support, then they won't necessarily know the name of the .kit to run to find the docs.
extension command?
I don't know if anyone has done the entire thing. Certainly the starkit distribution archive has things like critcl, oomk, kitten, tdom, tls. However, none of these are pure tcl - kitten has some tcl extensions in it.
Kroc 07 Oct 2004 - I've already done some starkits with pure tcl packages in (tcllib 1.6.1 [L1 ] and tklib 0.2 [L2 ] for example). Once you've sourced them, you can [package require] every wanted packages they provide. According to me, that's actually (with tclkit) the most convinient way to install and develop with tcl without root/admin rights.
But you're right, it misses something to provide documentation with starkits. That's why I'm actually looking for a way to store and display help and/or manuals inside a starkit. I think this could be done by adding a global [man] proc in starkit's main.tcl. This proc must be able to return documentation to stdout in Tk wasn't loaded, or in a text widget. It must be pure tcl of course, and last (but not least) the documentation format have to be easy to produce from actual tcl and packages formats (i.e. manpages, html, etc..). I've not find yet how I'll do that but as I'm still looking for, any advice will be welcome.
Kroc 11 Oct 2004 - I've done a little starkit to demonstrate this idea.
This starkit provides cksum 1.0.1, crc16 1.1, crc32 1.1.1 and sum 1.1.0 from tcllib 1.6.1. I add builtin documentation, which can be displayed with a custom version of a little hypertext system. Actually, built-in documentation is a .dok file saved in package directory using part of wikit syntax. You can call it with man ?command? or from tclsh, wish console, or tkcon command line, ex:
% man crc32
Of course, this has to be improved (a lot) to fit requirements given above.
jcw There's a page on adding wikit as embedded help system, see [L3 ], for example. I think there are other pages too.
Kroc 12 Oct 2004 - I've already read them Jean-Claude, but noone fits all my requirements. I updated crc.kit today: now man returns documentation to stdout if Tk is not loaded or use the text widget if Tk was loaded before crc.kit was sourced.
If I go further, I'll wikify a dedicated page for this.
LES Hmmm... interesting idea: all extensions in a single starkit. You get the core, the extensions.kit and this is it.