Formatting Figure Titles in HTML and CHM

All DITA elements have an outputclass attribute. Set this attribute to a CSS class name that exists in your CSS stylesheet and you have a very simple technique for formatting your HTML-based output. At least, that's what I thought....

I have been inserting a figgroup element after each of my image elements, in order to get the figure title to appear below the image, instead of above it as DITA intends it. Problem was, when I set the outputclass on the title element that is a child element of figgroup, the class attribute wasn't appearing in the HTML output.

After much experimentation, I discovered that the solution is to set the outputclass attribute on the figgroup element itself:

<fig>
<image height="103" width="226" align="center"
placement="break"  href = "images/DAEditLayoutwindow.gif" />
<figgroup outputclass = "figtitle">
<title>The Edit Window Layout
Window
</title>
</figgroup>
</fig>

This produces the following HTML output:

<span class="figtitle">The Edit Window Layout
Window</span>

then, in my CSS stylesheet, I added :

.figtitle {
   font-weight: bold;
   font-style: italic;
   font-size: 8pt;
   }

Using a DITAVAL file with FM+DITA

For some reason, the conditional processing parameter dita.input.valfile is not recognized by the DITA Open Toolkit when you're using the FM+DITA plugin.
There's a workaround: add the value to the ditafm.ini file in the ditafm folder of your root FrameMaker installation.
The procedure is quite straightforward:

1. Define the attributes in your topic files that you wish to make conditional (for example, set audience to "internal", product to "XMS Version 1" or platform to "Unix").


2. Open the ditafm.ini file in a text editor. Find the AntCommand line (in the [BuildFile] section) and add -Ddita.input.valfile="path_to_ditaval_file". For example:
   

   AntCommand=ant -Ddita.input.valfile="C:/WORK/VMXMSRepository/en-GB/XMS Help System/Common/common.ditaval"
   

3. Create a .ditaval file in the specified location. The content is described in the DITA OT documentation. For example:
   

   <?xml version="1.0"?>
   <val>
   <prop att="product" val="m3" action="exclude" />
   </val>
   

4. Restart FrameMaker to take the changes to the ditafm.ini file into account.
   

Note that this approach has one serious disadvantage: the ditafm.ini file controls all conditional processing, so you can't have several different .ditaval files active simultaneously. Let's hope they address this problem soon.

It's also not yet clear how this works in FrameMaker 8.0, as the aforementioned [BuildFile] section is missing from the ditafm.ini file supplied with FrameMaker 8.0 altogether (btw, it's now in the fminit/ditafm folder).

Customizing the index.html generated by DITA OT

By default, the index.html file generated by the DITA Open Toolkit is pretty basic: there's no CSS referenced at all and all topicref elements are turned into bullets. I wanted to use the same CSS as for the topic files, and have header levels indented to look like a proper table of contents. I also find it strange that topicheader elements defined in your ditamap don't appear at all in the output.
Here's what I did:

1. Edit the map2htmltoc.xsl file in the "xsl" folder of the DITA Open Toolkit.


2. Find the line containing </head> that ends the HTML header in the generated file, and add the following line just above it:
   

      <link rel="stylesheet" href="myCSS.css"></link>

3. Edit any other of the HTML tags you find spread about the place: I removed the OL tags and changed all LIs to Ps.


4. At the bottom of the file, I added the following template to output any text in TOPICHEAD elements of the DITAMAP (navtitle attribute):
   

    <xsl:template match="//topichead">
     <xsl:element name="h2">
     <xsl:attribute name="class">topichead</xsl:attribute>
     <xsl:value-of select="@navtitle" />
   </xsl:element><xsl:value-of select="$newline"/>
   

   
   

Using your Own CSS with FM-DITA

I have been using my own CSS to format my DITA help topics for a while now. However, it was never a very "clean" solution because I was just manually copying my CSS into the html output folder, where it sat alongside the default CSS files common.css, commonltr.css and commonrtl.css. My developers have rightly been bugging me to clean up my act.

Here's my solution:

1. Copy the CSS file into the resource folder of the DITA open toolkit.
   


2. Edit the ditafm-ant.xml file in the open toolkit root folder.


3. Scroll down until you find the HTML target section (<target name="html" ...>).


4. Add the following lines to the bottom of the section, just before the </antcall> line:
   

       <param name="args.css" value="${dita.dir}${file.separator}resource${file.separator}myCSS.css""/>
       <param name="args.csspath" value="."/>
       <param name="args.copycss" value="yes"/>
   

   These parameters are:
   
   
   
   • args.css. The location of the custom CSS file.
   • args.csspath. The path to copy it to, relative to the folder containing generated HTML files
   • args.copycss. Whether to copy the file to the output folder.
   
   
5. Optionally, delete any other CSS files that you don't need from the resource folder.


6. Regenerate your files as usual within FrameMaker and you should find your CSS file in the output folder.