[software] [catdoc] [tcl] [geography] [old things]

Unixhelp extension

This is pure Tcl extension which allows to create context-sensitive help for Tk apps from same sources as windows help files (.chm).

It is designed to be drop-in replacement for Christian Werner's WinHelp extension.

Goal is to allow authors of cross-platform application to use native help viewer on Windows system and use same on-line documentation source (and quite simular interface) for Unix version of application.

It would be ideal if we would be able to use native help viewer on various MacOS versions as well, but I don't have access to any MacOS machine. Contributions are welcome.

Required Tcl/Tk packages:

  • Tcl/Tk version 8.4 or above.
  • htmlparse (from tcllib) - for compiling help files only. We need version from Tcllib 1.7 and abouve
  • Tkhtml 2.0 and above. Get it from CVS. Note that you can encounter some problems with Tkhtml and recent versions of Tcl, especially if build with --enable-thread.

    I've fixed random segfaults in my debian package for TkHtml. Patches are available in the repository.

  • Tclvfs
  • Trf and memchan - to make zip vfs working.
Debian packages for all these extensions can be found on wagner.pp.ru apt repository

Apart from the packages mentioned above unixhelp uses tree widget, derived from Richard Hipp's code and notebook widget byDonal K. Fellows.

These packages were modified by me, so use included version.



  • Table of contents
  • Keyword index
  • Full text search (uses regular expression, as Unix user expects)
  • Unlimited history
  • Compiler for microsoft html help workshop project files which creates help files, usable with our viewer.
  • tkhhc and unixhelp tcl command are documented in standard man pages.
  • Proper i18n using msgcat package. Although only Russian message catalog is present for now. Contributions are welcome.
  • Image support. If you use Img extension in your application, any types of images are supported. If not, you are limited to gifs.


  • Prototype has print button. Should investigate postscript generation capabilites of recent Tkhtml.
  • Prototype has button to hide/show contents pane
  • It seems to be possible to use chm-files directly rather than rebuild other format from source. Only thing we need - chmlib-based tcl vfs, and some code to parse #SYSTEM file.
  • Add separate application to view help file and control it via send command.

Why doesn't unixhelp read .chm files directly

Just because I cannot now imagine any use for it. It is just easy to write tclvfs using chmlib.

There exists some opensource code to reconstruct neccessary parts of project file from binary metainformation file #SYSTEM (see for instance chmdeco.

All this code is published under GPL. So we have following situation:

  1. If we have closed source application, we cannot link chmlib into it without violate a license. So, better to use something else.

    There exist workaround. You can use external program to extract information from CHM file, and since it is external, it can be GPL.

  2. If we have open source application, it is not a good thing to depend on proprietary tools for the development, because you actually prohibit people without this tool to make changes in your program, since they are unable to document this changes in the help. And opensource hhm compiler is not mature enough to produce .chm files compatible with windows help viewer.
Really only interesting use for direct access to .CHM files under Unix is standalone reader for .chm files. Many proprietary documentation is now supplied in this format, and one might want to read it under *nix system. But not me, I don't have such crap.

Of course there exist xCHM but it has some problems with non-engilsh chm files (it uses not robust enough algorithm to find out text encoding). And since it is written on C++ it is hard to understand and fix.

I've written some code to decode metainformation from CHM #SYSTEM file, which already does more than corresponding xchm code. Code to convert .hhc and .hhk files is already in tkhhc

If you want to help, you are welcome.

Preparing help file

From the sources of Microsoft HTML Help Workshop project

Just run supplied tkhhc script, specifying you help project file name and output file name (which should not be same as output name for .chm file, specified in the project file). It would do following:
  1. Extract following information from the Html help workshop (.hhp) project file:
    • Default topic (Default topic = filename.htm)
    • Name of contents table file (Contents file = filename.hhc)
    • Name of keyword index file (Index file = filename.hhk)
  2. write file props.txt which contain following information:
    encoding tcl name of your locale encoding
    starttopic filename name of default topic
    Note that contents of this file would be passed to tcl array set command.
  3. Convert content table file (.hhc) and keyworkd index (.hhk) into form suitable to unixhelp viewer and write them into contents.lst and index.lst files
  4. collect <META NAME="MS-HAID"> tags from all topics and write meta.lst file.
  5. create zip archive containing all pages listed in [files] section of help project as well as three files created on steps above. Give it any name and extension you like.

From scratch

  1. Write set of interlinked html pages. It is recommended that they should have extension .htm rather than html
  2. Write props.txt file as described above
  3. Write content.lst file This file contain list of tcl list in the format
    page-title filename ?list of subnodes?
    where each element of subnodes lists follow same syntax as toplevel node. Example
    {Introduction intro.htm}
    {"Chapter 1" chap1_preface.htm
    	{"Section 1.1" chap1_1.htm}
    	{"Section 1.2" chap1_2.htm}
    	{"Section 1.3" ""
    		{"Subsection 1.3.1" chap1_3_1.htm}
    		{"Subsection 1.3.2" chap1_3_2.htm}
    {"Chapter 2" chap2_preface.htm
    	{"Section 2.1" chap2_1.htm}
    {"Appendix" appendix.htm}
    It is possible to use anchors in this file.
  4. Write index.lst file. This file has essentially same format, but typically toplevel nodes, named after keywords, have empty filename and second level nodes point to real pages (may be with anchors)
  5. Pack everything into zip archive

Using help from program

package require unixhelp

unixhelp window filename ?topic?
where window is the toplevel window, whose child would be help viewer toplevel (typically .), filename and topic (which can be omitted) is either name of html page inside archive or name of page, accompanied with anchor name, separated by # sign.

Subsequentual calls for unixhelp with same filename wouldn't lead to reloading of the file, so just always call it with full pathna,me


tkunixhelp.tar.gz Unpack this archive somewhere in your tcl_packagePath and you'll get three packages available - unixhelp, noteboook and tree.
Debian package for sarge and all prerequisites are availiable from wagner.pp.ru repository. Note that there are two packages tkunixhelp and tkunixhelp-dev. Later contains tkhhc compiler, which is not needed just for using applications which employ tkunixhtml help system.

Should be installable on both woody and sarge if you take pain of rebuilding my tkhtml package for woody.


  • Make tkhhc support forward slashes as directory separartors.
  • Document format (or provide tools to create) .hhc and .hhk files