Here’s how I was able to substitute my own CSS (Cascading Style Sheet) file when using the DITA transforms to make compiled help files (CHM). I did several Google and Yahoo Group searches in the dita-users group for phrases like “switch css chm” and “substitute css chm” but didn’t find quite what I was looking for, so I decided to try a few things and write it up. After figuring it out, I did find the topic covered for XHTML in the DITA Open ToolKit User Guide and it contains all the information I needed to make it work for CHM. I just needed to leave that “CHM” keyword out of the search phrases I was using! Go figure.
Here’s an overview of what I did to get it to work in my environment on Windows. This process should work for other platforms as well.
First, create a CSS file that contains the modifications you want for styling your output. I basically took the generated CSS commonltr.css and made modifications to that file, then saved it as a new CSS file called bmc_dita_chm.css.
Second, make sure you can build using Ant and create your own Ant script using the ant/template_htmlhelp.xml file provided with the DITA Open Toolkit. Basically, you take the ant/template_htmlhelp.xml file and substitute your project names in the file, then save the file with a new name such as build_htmlhelp.xml. Then you go to a command prompt and type ant -f build_htmlhelp.xml. You should get output with the default CSS styling.
Next, modify your Ant build script with the following parameters: args.copycss, args.css, and args.csspath. All these parameters are documented in the Open Toolkit but I still wanted a code example that put it all together. So here it is, and you can copy and paste this into your Ant build file for HTML Help (CHM).
<property name="args.copycss" value="yes"/>
<property name="args.css"
value="${dita.dir}${file.separator}css${file.separator}
bmc_dita_chm.css"/>
<property name="args.csspath" value="css"/>
Now your CSS file will be substituted before the compile command occurs, which was like magic to me. I had originally thought I’d have to do a command-line method with quick file copies at the right times, but these Ant builds are da bomb. The more I learn about using Ant to build DITA output the more excited I am about the possibilities. Put your DTD specialization files anywhere! And then point to them using the catalog-dita_template.xml file! And then build output from anywhere! And substitute your own CSS!
Recently there has been a discussion on the dita-users Yahoo Group about styling the CSS for the Table of Contents (TOC) for the XHTML output, and there’s now a patch that enables the substitution of your own CSS for the Table of Contents. The .patch file is for use with a GNU utility called patch (Windows version is downloadable from http://unxutils.sourceforge.net/), but you can also read the .patch file to figure out which modifications to make where.
Have fun with your own customizations. Let us know if you have any other tips and tricks with customizing the DITA output.