The process of generating Microsoft HTML Help (CHM) output from DITA content using the DITA Open Toolkit does not provide for storage of Context-Sensitive Help identifiers in the topics or in the DITA map. Context identifiers have to be created and managed outside the DITA authoring environment. The htmlhelp2 plug-in created by Deborah Pickett extends the DITA OT functionality to allow context-identifiers to be generated from values stored in the resourceid attribute of the DITA map's topicref.
To install the plug-in, download the plug-in ZIP file from Yahoo! DITA Users Group, extract the files into the \plugins directory in the DITA-OT directory, and run the integrator task. The htmlhelp2 transtype will then be available as an Ant build output.
The htmlhelp2 functionality is built into the ditaplus plug-in, also created by Deborah Pickett.
The plug-in uses the resourceid element within the topicmeta element in the topicref in the DITA map as the basis for building the map and alias files required for HTML Help Context-Sensitive Help. The resourceid element doesn't contain data, and has two attributes: id and appname. The id attribute can hold only one value, whereas the context-hooks in HTML Help require a string and a numeric identifier. It is expected you will enter a numeric value into the id attribute of the resourceid, and the plug-in will derive from that number a string value.
For example, an id of 3254 will be transformed to a map file entry of:
#define identity_3524 3524
In other words, the resourceid's id attribute is used as the context number, and used to create the context string by prefixing the number with the string identity_ .
In addition to entering a context number in the id attribute, you must also enter an appname attribute of WindowsHelpId in the resourceid element in the topicref in the DITA map. The WindowsHelpId value identifies the particular resourceid as being used for Context-Sensitive Help, thus differentiating it from resourceid elements used for other purposes.
You can have more than one resourceid element if you need several different help IDs to be pointed to the one topic.
In Microsoft HTML Help, map (.h or .map) files correlate context strings to context numbers, and alias (.ali) files correlate context numbers to topic file names.
The htmlhelp2 transformation extracts from all topics in the DITA map any resourceid elements where the appname attribute is WindowsHelpId. The map and alias files generated by htmlhelp2 are named [map_file_name].map and [map_file_name].ali respectively.
The plug-in has another useful feature. When it generates the HTML Help project (.hhp) file, it adds window definitions named default, global_$Standard and $global_Dialog.
The latter window definition will displays as a single pane in the right third of the window.