Viewing XML in Oxygen's browser

I had a problem viewing XML files in the browser configured within Oxygen 9: IE7 wouldn't launch at all.
I fixed is by running:

regsvr32 msxml3.dll

I was then able to open the XML files with IE.

Translating HTML Files with DITA

We've just completed our first translation test with LionBridge.

Overall, very successful, but just a few things to remember:

- The xml-lang attribute must be set in EVERY topic file. It's not enough to set it on the map and expect it to filter down. So for the French files we have for example:

http://dita.oasis-open.org/architecture/2005/">

This causes the DITA-OT to use translated versions of "Related concepts", "Related reference" etc. for link titles.

- Open the HHC, HHK and HHP files in a good text editor (I used Ultraedit) and save them as ASCII/ANSI. This is necessary because the HTMLHelp compiler does not support Unicode. In particular, before converting my HHK file, accented characters in the Index appeared incorrectly.

- I don't know what effect it had specifically, but I set the Language option in the HHP file to French :

Language=0x40c French (France)

You can set this with the Help Workshop:

1. Double-click the Language setting in the [OPTIONS] list.

2. In International Settings, choose the language.

3. Recompile.

Switching Frame book applications with DITA+FMx

DITA+FMx does not (yet) include the Build FM DITABook menu option to build a FrameMaker book from a DITAMap. This is apparently due to licensing problems between Abobe and Leximation, the author of DITA+FMx.
However, you can still use the option provided you keep your old DITA+FM plugin installed and follow the instructions described in the DITA+FMx documentation at http://docs.leximation.com/dita-fmx/0.01/

When you generate a Book, an option in the ditafm/DITAfm.ini file controls which structured application FrameMaker calls to perform the generation of FrameMaker files. To switch between different applications, you have to comment out the lines that don't apply. For example:

;DITABOOK-StructApp=DITA-FMx-Book
;DITABOOK-StructApp=DITA-Book-FM
DITABOOK-StructApp=Gemalto-DITA-Book-FM

In this example, the semicolon (;) comments out the first two entries, so the third one is used. If you forget to comment out an application, the first entry is used by FrameMaker. The names of the structured applications are as defined in the structapps.fm file (File > Structure Tools > Edit Application Definitions, then look at the XMLApplication/ApplicationName tag in the structure view).

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.