WinANT Options Supporting Microsoft HTML Help

This topic describes how some features within the WinANT software tool can make Microsoft HTML Help generation from DITA content easier.

The DITA Open Toolkit provides a method for nominating context-sensitive Help header (or map) and alias files to be compiled into the CHM file when a Microsoft HTML Help output is being generated. The method is difficult to use from a command line or terminal window invocation of the Apache Ant build processor. The HyperWrite WinANT software tool, which acts as a Windows interface to Ant, makes this otherwise difficult method extremely simple.

Overview

WinANT is a Windows program, build with Microsoft Visual Studio .NET 2003 using VB.NET. It serves as an interface to the Ant build utility, for the sole purpose of processing DITA documents.

WinANT allows a user to select build characteristics using normal Windows interface devices such as dropdown lists, radio buttons, tabs and browse buttons. When all the required settings are in place, the program creates the Ant build file, creates a ditaval file (if required), creates a batch file, and then executes the batch file to trigger the Ant build. When Ant has finished the processing, WinANT displays the generated output file. The settings can be saved (as a build file) and later recalled.

Figure 1. WinANT 1.4 - Main tab

Setup and configuration

WinANT can be downloaded without charge on a "take it as it comes" basis from http://www.helpml.com/winant_setup.exe. It installs using a standard Windows installer.

To enable the incorporation of map and alias files in HTML Help output, you have to manually change the following lines in the standard build_dita2htmlhelp.xml DITA OT file from:
<param name="HELPMAP" />
<param name="HELPALIAS" />
to
<param name="HELPMAP" expression="${dita.map.filename.root}.h" />
<param name="HELPALIAS" expression="${dita.map.filename.root}.ali" />

Authoring

Nominating the map and alias files in the HTML Help project file effectively externalises the context hooks; the context ids and strings are not incorporated into the DITA source files at all. The map and alias files therefore need to be separately authored outside DITA.

Selecting the map and alias files

The map and alias files are selected in the Context-Sensitive Help panel of the Advanced tab. These fields are only active if the Output Type field on the Main tab is set to HTML Help.

Figure 2. WinANT 1.4 - Advanced tab

Summary

Provided you have the capacity to create the HTML Help map and alias files outside your DITA authoring environment, this technique is a simple way to produce context-sensitive HTML Help. It only requires very minor (and simple) changes to the standard DITA Open Toolkit files.

It is possible that this technique can be combined and integrated with other methods of generating map and alias files from DITA source.