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 2008 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 drop-down 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.
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, and requires .Net Framework 2.0.
<param name="OUTEXT" expression="${out.ext}" if="out.ext" />
the two lines:<param name="HELPMAP" expression="${dita.map.filename.root}.map" />
<param name="HELPALIAS" expression="${dita.map.filename.root}.ali" />
Authoring
Nominating the map and alias files in the HTML Help project file effectively externalizes 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 Help Systems tab. These fields are only active if the Output Type field on the Main tab is set to HTML Help or HTML Help 2.
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.
Tony Self
HyperWrite Pty. Ltd.
Chairperson, OASIS DITA Help Subcommittee