Unixhelp extension

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.

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.

Features

Present

• 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.

Missing

• 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

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.

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

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?

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

Download

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

Todo

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