Help.kit is a starkit that can display html help using the tkhtml widget.
How to use it with embedded html :
To replace the sample HTML pages with your own documentation you should first unwrap this starkit with the following command:
sdx unwrap Help.kit
Then delete all the files in Help.vfs/html/ and replace them with your own html files. The first file that Help.kit will try to read is composed of the first 2 letters of users internationnal country code (en, fr, de, etc..) with a .htm or .html extension. Then it will attempt to read index.htm(l). For example, for a french user it will try fr.htm then fr.html then index.htm then index.html. So, if you want to provide localized help (as in this kit) save the start page with country code name. For non-localized help, just create the index.html file. You should always provide an index.html file to provide default support for unsupported user locales. For instance, if you do not provide a russian translation, then a user with russian locale will be presented with the index.html page.
Rewrap the starkit with the following command:
sdx wrap Help.kit
That's all, your Help.kit is ready.
How to use it with external html :
Unwrap this starkit:
sdx unwrap Help.kit
Delete all files in Help.vfs/html/
Rewrap the starkit:
sdx wrap Help.kit
When you run Help.kit, it will display any html files that exist in the same directory. The files selected are as described above. For example, for a german user it will try de.htm then de.html then index.htm then index.html. So, if you want to provide translated help (like this kit) save the start page with country code name. If you don't, call it index.htm or index.html. If you use this i18n feature, you should also copy en.htm(l) to index.htm(l) if you want it to work even with unsupported languages. You can have a look at the content of this starkit for an example.
How to embed this help viewer in your starkit :
Help.kit could also be embedded in your own starkit to display help for another application like this:
Unwrap this starkit:
sdx unwrap Help.kit
Delete all files in Help.vfs/html/ and replace them with your own html files as described above. Copy the html sub-directory into your application's VFS tree and also copy the contents of Help.vfs/lib/ into your applications app.vfs/lib/ directory.
To invoke Help, add this line in your Tk script :
bind . <F1> { source [file join $starkit::topdir lib helpviewer hv.tcl] }Then, when the user press F1 key, it will display the filename you set in $help_called global var if it exist.
Some rules to follow for html files :
Even if you're free to decide how to write your help, it would be a good idea if every Tcler used the same design. This way, users will feel more comfortable with a well-known design, and your help file could be updated easily by another Tcler. That's why I propose that you use the following model. The easiest way to use it is to replace each part with your own help text.
This model follows these few rules :
If you follow these rules, or the sample files provided in this starkit, you can be sure your html help will be displayed correctly with any browser or with Help.kit on any supported platform.
Some example dok kits
Download it on sdarchive: [L4 ]
NEM - tkhtml is a binary extension. Which platforms are supported by Help.kit? Is there a Tcl-only fallback if there is no tkhtml for a particular platform? I seem to remember there being a few, such as the one in iwidgets (useful, as Tclkit already comes with itcl/itk).
kroc - Actually binaries for Windows, Linux and Solaris are provided in the starkit. Others would be welcome, Tcl-only fallback too.
SEH - I was reading about htmllib.tcl [L5 ] (pure-Tcl html widget) and it sounded pretty promising. Has anyone had any experience with it (good/bad)?
Kevin Walzer - Tkhtml's hv.tcl file can also be used as a standalone viewer. See Help Widget using hv.tcl.