Context-Sensitive HTML Help Using the The DITA Open Toolkit

Overview

Output from the DITA Open Toolkit HTML Help plug-in serves as input to the Microsoft HTML Help Compiler. If you choose to build your DITA sources on the same Windows system on which you have installed a copy of the Microsoft HTML Help Software Development Kit, you will be able to generate a ready-to-deploy MS HTML Help .chm library from your DITA-OT ant script. Otherwise, you an copy output from the DITA Open Toolkit HTML Help transform on your DITA-OT build system to some other Windows system on which the HTML Help SDK has been installed.

Setup and configuration

Once you have installed and configured the DITA Open Toolkit, you have the HTML Help transform installed by default and ready to use. See the DITA Open Toolkit User's Guide for detailed information about working with transforms and about specifying the HTML Help transform specifically as a processing target (dita2htmlhelp).

To download the latest Microsoft HTML Help 1.4 SDK, go to the following MSDN web site. It is a free download.

http://msdn.microsoft.com/en-us/library/ms669985.aspx

Authoring

To generate ready-to-deploy .chm libraries from most any DITA source collection, you do not really have to customize or rework your DITA source files.

Integration

Truth be known, there are also limitations to both this DITA-OT transform and to the MS HTML Help run-time environment. Factor these into your planning.

• Context-sensitive mapping: The DITA-OT HTML Help transform is not designed to process context-sensitive mappings between DITA source topics and the context IDs associated with those target topics. To feed the MS HTML Help compiler with the appropriate context-sensitive ID maps and/or alias files, consider developing a custom shell for the Open Toolkit or building your HTML Help output with WinANT. See WinANT Options Supporting Microsoft HTML Help for more information about the latter.
• HTML support in MS HTML Help: The Microsoft HTML Help application displays HTML topics in a captive HTML viewer. This viewer supports most, but not all, of the HTML output that you can generate from the DITA-OT XHTML transform. If, for example, you are working with SVG images or some interactive JavaScript libraries, test them with output from the HTML Help transform before deploying them.

Output

The .chm library produced by the combination of the DITA-OT HTML Help transform and the MS HTML Help compiler is very functional.

Here's what output from the DITA-OT test collection looks like.

Figure 1. Garage Tasks Contents Tab in HTML Help

Figure 2. Garage Tasks Search Tab in HTML Help

Summary

If you have requirements to deploy a general-purpose Help collection to Windows customers without context-sensitive integration, consider using the DITA-OT HTML Help transform. It is functional, reliable and fast. Once all your content in is .chm format, you can convert it to other distribution formats with second-tier conversion tools such as chm2web. If you have requirements to integrate .chm output with Windows applications as Context-sensitive Help, you'll need to invest some time managing maps and alias files outside the DITA environment and then integrating them with .chm output using WinAnt or other custom processing environments.