DITA Map CHM (Compiled HTML Help) Transformation
To perform a Compiled HTML Help (CHM) transformation, Oxygen XML Developer Eclipse plugin needs
Microsoft HTML Help Workshop
to be installed on your computer. Oxygen XML Developer 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 Developer 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 Developer 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 thehtmlhelp.locale
parameter isLL-CC
, whereLL
represents the language code (en
, for example) andCC
represents the country code (US
, for example). The language codes are contained in theISO 639-1
standard and the country codes are contained in theISO 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:
- Create the custom CSS.
- Select the DITA Map CHM transformation scenario and click the Edit button.
- In the Parameter tab, set the
args.css
parameter to point to the location of your custom CSS and make sure theargs.copy.css
parameter is set to yes to instruct the transformation to copy the custom CSS to the output folder. - 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.