DITA Map CHM (Compiled HTML Help) Transformation

To perform a Compiled HTML Help (CHM) transformation, Oxygen XML Author Eclipse plugin needs Microsoft HTML Help Workshop to be installed on your computer. Oxygen XML Author Eclipse plugin automatically detects if HTML Help Workshop is installed and uses it.

Note: HTML Help Workshop might fail if the files used for transformation contain accents in their names, due to different encodings used when writing the .hhp and .hhc files. If the transformation fails to produce the CHM output but the .hhp (HTML Help Project) file is already generated, you can manually try to build the CHM output using HTML Help Workshop.

Changing the Output Encoding

Oxygen XML Author Eclipse plugin uses the htmlhelp.locale parameter to correctly display specific characters of different languages in the output of the Compiled HTML Help (CHM) transformation. By default, the DITA Map CHM transformation scenario that comes bundled with Oxygen XML Author Eclipse plugin has the htmlhelp.locale parameter set to en-US.

To customize this parameter, follow this procedure:

Use the Configure Transformation Scenario(s) (Alt + Shift + T, C (Command + Option + T, C on macOS)) action from the toolbar or the XML menu.
Select the DITA Map CHM transformation scenario and click the Edit button.
In the Parameter tab, search for the htmlhelp.locale parameter and change its value to the desired language tag.
Note: The format of the htmlhelp.locale parameter is LL-CC, where LL represents the language code (en, for example) and CC represents the country code (US, for example). The language codes are contained in the ISO 639-1 standard and the country codes are contained in the ISO 3166-1 standard. For further details about language tags, go to http://www.rfc-editor.org/rfc/rfc5646.txt.

Customizing the CHM Output

There are several possibilities available for customizing the CHM output:

You can use a custom CSS stylesheet to customize how the HTML content is rendered in the output:
1. Create the custom CSS.
2. Select the DITA Map CHM transformation scenario and click the Edit button.
3. In the Parameter tab, set the args.css parameter to point to the location of your custom CSS and make sure the args.copy.css parameter is set to yes to instruct the transformation to copy the custom CSS to the output folder.
4. Run the transformation.
If you are familiar with XSLT, there are two XSLT stylesheets that are used in the transformation to compile various settings and components in the CHM output. They are found in the following directory: OXYGEN_INSTALL_DIR/frameworks/dita/DITA-OT/plugins/org.dita.htmlhelp/xsl/map2htmlhelp. The files are as follows:
- map2hhcImpl.xsl - This file is used to compile the table of contents.
- map2hhpImpl.xsl - This file contains information for compiling the CHM and various settings that are read by the HTML Help Workshop when creating the output.