There are a lot of "roll-your-own" approaches to providing user help with Tcl/Tk applications; many of these involve hard-coding blocks of text within the main Tcl script and then inserting that material into a text widget for display. However, a richer and more elegant approach is to use the hv.tcl (HTML Viewer) script that comes bundled with the tkhtml extension. This approach is particularly well-suited for documentation that is authored in a single-source mode, such as DocBook or LaTeX, and then converted to HTML.
I've used hv.tcl in this fashion with DocBook-generated documentation:
1. HTML files generated by DocBook have navigation links built-in, so there's no need to add a navigation toolbar to hv.tcl, or to use the menu buttons. I comment out the "pack" lines for the menu buttons, whcih means they are not generated as widgets.
2. There is an older version of hv.tcl that comes with many distributions of tkhtml; this version has a bug that prevents text anchors from displaying correctly. A more recent version was distributed to the tkhtml mailing list at http://groups.yahoo.com/group/tkhtml/message/164 ; this version fixes the bug so that text anchors display. You must be registered for the mailing list to access the file at Yahoo. 3. The simplest way to use hv.tcl as a help widget is to run it as a separate application from your main script, rather than trying to source it into a separate top-level window. Here's a sample:
proc ShowHelp{} {
exec wish ~/hv.tcl
}4. To ensure that the correct documentation is displayed in the help widget, it is helpful to add a command like this to the end of hv.tcl, using the LoadFile procedure: LoadFile /path/to/index.html
I'd be curious to see how others use help widgets. Hv.tcl is the simplest that I've found.
Kevin Walzer -- October 4, 2004