Version 1 of Help.kit

Updated 2003-12-15 18:12:49

Help.kit is a starkit that can display html help, based on tkhtml.

How to use it with embeded html :

Unwrap this starkit:

 sdx unwrap Help.kit

Delete all files in Help.vfs/html/ and replace them with your own html files. The first file Help.kit will try to read will be the 2 first letters of user internationnal country code (en, fr, de, etc..) + .htm(l) or 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 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.

Rewrap the starkit:

 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 html files in the same directory. The first file Help.kit will try to read will be the 2 first letters of user internationnal country code (en, fr, de, etc..) + .htm(l) or index + .htm(l). 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. The first file Help.kit will try to read will be the 2 first letters of user internationnal country code (en, fr, de, etc..) + .htm(l) or index + .htm(l). For example, for a dutch user it will try nl.htm then nl.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. Copy html sub-directory in your_app.vfs and also copy the content of Help.vfs/lib/ in your_app.vfs/lib/

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 you to use this model. The easiest way to use it is to replace each parts with your own help text.

This model follows these few rules :

  • Very light html head with only required tags.
  • Page title in bold upper case letters between <hr> tags.
  • Chapter title in bold.
  • Chapter text between <blockquote> tags.
  • Important text in bold.
  • Quoted tcl code in black monospaced font.
  • Use bold for command name when quoting a tcl command line.
  • Use italic for optional args when quoting a tcl command line.
  • Only use gif images (so Help.kit could display them).

If you follow these rules, or any other example you could read in html files shared in this starkit, you could be sure your html help will be seen corectly with any browser or Help.kit on any supported platform.


So, where is it?