Kchmviewer is free software which provides a flexible, unique and cross-platform way to integrate the context help into your application. While Windows-only applications can use WinHelp facilities, the kchmviewer offers the following advantages over WinHelp starting from version 7.2:

• It supports Microsoft Windows, Linux, Mac OS X and other platforms such as FreeBSD;
• It is independent of WinHelp; even if Microsoft stops supporting legacy WinHelp formats in future Windows versions, kchmviewer will keep supporting it;
• Its user interface is the same on all platforms, making it easier for your support to explain the user where to look, and which buttons to click;
• It has superior support for non-English help files comparing to WinHelp;
• It uses Webkit browser which provides modern HTML facilities, improving the look of your help;
• Its integration is binary-independent, you will not need to change your application each time a new Kchmviewer version is released;
• It is very easy to integrate into your application – easier than integrating WinHelp, and should not take more than an hour of your time;
• It supports EPUB format and hence allows distributing your help file in the popular EPUB ebook format, which is much easier to edit and produce than CHM;
• It can be used as a portable application, and will not store anything in the user directory;
• It is free (both as free beer and as freedom) software, licensed under GPLv3, which could be used commercially with no payments or royalty — as long as you agree to satisfy the terms of the GPL. Commercial licensing is also available in case you are unable or unwilling to satisfy the GPLv3 requirements.

Hints on preparing your help file

To use the context help in your application, your help file needs some preparation. Make sure that each topic which your application would want to open in the context help would be on a separate page (which both for CHM and EPUB means a dedicated HTML file), or has an <a name> anchor.

I suggest using only the ASCII English letters and numbers for the help file names and anchor names, no spaces and no special symbols. While kchmviewer fully supports and has no issues with file names and anchors in Unicode, your operating system exec() facility might not. Since neither file names nor anchors are visible to the user, it has no effect on the visible documentation.

An example help file:

/using_shared_libs.html:

<a name=”windows”>Using Windows DLL</a>
  … some relevant text …
<a name=”linux”>Using Linux shared libraries</a>
  … some relevant text …
<a name=”macosx”>Using Mac OS X shared libraries</a>
  … some relevant text …

/supported_options.html:
  … general description of supported options …

Then when you want kchmviewer to show the supported options, you ask it to open the page /supported_options.html, and when you want it to show the help for using Linux shared libraries, you ask it to open /using_shared_libs.html#linux

Integration

Kchmviewer is integrated with your application as a separate application which is invoked from your application with the command-line parameters. This allows a very simple integration which could be performed in less than an hour, even by junior developers. It also allows to use the same code across all operating systems, as the facilities invoking external applications are universally available, and much more similar in usage than other IPC technologies such as COM or DBUS. And, last but not least, any bugs in kchmviewer will not affect your application since it is a separate process.

Only the first invocation actually starts kchmviewer, all subsequent invocations change the state of the invoked instance, so there are no extra applications or windows. However you may start multiple instances if you wish, which may make sense if you believe user would benefit from having two help files opened at different pages simultaneously.

Token

To uniquely identify the kchmviewer instance used by your application you must use a token. Token is a text string which would uniquely identify your product, and could be anything as long as it is unique and the same string is used across your product. The purpose of the token is dual: to reuse a single kchmviewer instance (and thus be able to locate the existing instance), and to avoid messing up with other instances of kchmviewer, which may be launched by other applications.

Of course if you want more than one instance of kchmviewer to appear, you would use two or more tokens in your application as needed.

Token is passed to kchmviewer as the parameter to the command-line option “-token”

An example token: “com.example.myapplication”. You can also use the help file name as a token; please use the absolute path in this case, since a token such as “help.chm” would hardly be unique to your application.

If no token is used, each invocation of kchmviewer will start a new instance.

Supported command-line options

The kchmviewer supports the following command-line options which are useful for the integration:

showPage

This option tells kchmviewer to open the specific page in the CHM or EPUB file.

Example:

kchmviewer -token “com.example.myapp” -showPage “/windows.html#win8” help.chm

Kchmviewer will start (if not running already), and open the help file at the requested page, scrolling down to the anchor if necessary.

index

This option tells kchmviewer to find a specific entry in the CHM file index.

Example:

kchmviewer -token “com.example.myapplication” -index “shared libraries” help.chm

Kchmviewer will start (if not running already), and open the index tab, entering the “shared libraries” into the search text box and showing the index entries available for this input.

Please note that for this feature to work the CHM file must be built with index support. EPUB files do not have index support at all, and therefore this option should not be used for EPUB.

search

This option tells kchmviewer to search for specific terms in the CHM or EPUB file.

Example:

kchmviewer -token “com.example.myapplication” -search “code example” help.chm

Kchmviewer will start (if not running already), and open the search tab with the search results finding the specified terms. It will also generate the search index if search is used the first time.

background

This option tells kchmviewer not to activate its window, and start minimized. It may be useful in the scenarios when the user is clicking on UI elements where each element has a separate help; if the user keeps the kchmviewer help window open tiled on the desktop, the user might not to have it activated each time he or she clicks on help. In this case this command-line option should be used.

Example:

kchmviewer -background -token “com.example.myapp” -search “code example” help.chm

novcheck

This option tells kchmviewer to disable built-in online check for the new version when it is first started. If you provide kcmviewer as part of your package, a user is likely unable to update it anyway, so there is no need to bother the user with unnecessary notifications, and hence this option is recommended.

Example:

kchmviewer -novcheck -token “com.example.myapp” -search “code example” help.chm

Pre-configuration

By default kchmviewer stores its settings and search index in the subdirectories which are created in the user home or Documents directory. However it is possible to tell kchmviewer to keep those files in a predefined location so it would not write anything into the user directories.

This functionality is enabled by creating a directory named “portable” (without quotes) in the same directory where the kchmviewer binary is stored. If this directory exists:

• A “data” subdirectory will be created under “portable” and will be used to store the search index and per-help file preferences;
• The application settings will be stored in the subdirectory “Ulduzsoft” created in “portable”
• Qt-specific settings will be stored in “portable” directory
• Nothing will be written into any other location on disk.

You can distribute the kchmviewer with the “portable” directory already created. This would allow you to pre-configure kchmviewer such as disable automatic check for updates, and generate the search index so the search functionality works out-of-the-box.

Distribution

You are allowed to distribute kchmviewer as part of your application, either as a portable binary or as the separate package, including the official releases. You can also make it part of your software installation. You can distribute it in any form, including the CDROM, USB or electronic distribution. No prior permission is required for distribution as long as you adhere to the terms of GPLv3, including but not limited to distributing or making available the kchmviewer source code together with the binary.

While you are allowed to distribute the modified binaries (with certain restrictions), please consider submitting your modifications for inclusion into the official release. This way you would not have to apply your modifications again and again each time a new version is released.

Since kchmviewer is released under GPL version 3 please remember to follow the license terms described here.