My DITA to HTML5 plugin makes progress but...

I'm developing an HTML5 plugin for the DITA Open Toolkit. I've managed to get most things working now, especially the new HTML5 tags and a new homepage that isn't based on FRAMESET. Yesterday I got SVG and MathML working. However, I've still got a long way to go, with outstanding issues including :

• Performance issues in the pre-processing stage. Since specializing the DITA OT to include the SVG and MathML domains, performance is rotten. Maps that used to take 3 to 5 seconds to build now take over a minute! To be investigated.
• Images referenced in DITA topics are not getting copied correctly to the HTML5 output folder. This is not a new issue: all existing HTML-based transformations do the same, but I'd like to fix it.
• SVG images in DITA render best in PDF when their width is specified as "13cm" and the height attribute is not given a value. The current HTML5 standard, however, only supports widths in pixels. It's going to be hard to get a single sourcing solution that works for both.
• SVG images appear in the HTML5 output, but there's something up with the fonts. It looks like they're not getting embedded properly, or that the fonts they use need to be declared somewhere in the CSS.
• MathML support in modern browsers (June 2012) is not good. Only Firefox renders them correctly. IE9 and Chrome don't complain about MathML markup, but don't render it correctly.

Restructure DITA Plugin Released

Finally released my new FrameMaker plugin today! Restructure DITA allows you to quickly and easily change one DITA list type for another, as well as convert paragraphs to lists and restructure existing lists as paragraphs. There's a link on the home page.
I've also been busy rewriting the source code for the CleanImport plugin. It has been a few years since I'd worked on it and looking at the code I realised I couldn't figure it out! So I decided to simplify and harmonize the code and, of course, document it better. I haven't added any new features yet, but at least I feel like I could now if I wanted to.
So now back to other projects, including finally finishing my HTML5 export filter for the DITA Open Toolkit.

Transforming Plain Text with XSLT

XSLT is a programming language for transforming XML into plain text, HTML, XML, and other formats. At least, that's how I saw it until the other day, when a potential client asked me how I would go about using XSLT to transform a plain text document into XML.

After a bit of googling, it turns out that I would have been wrong to say it wasn't possible, because XSLT can do almost everything to plain text files that Perl or other text-processing languages can. In particular, you can apply regular expressions to the plain text to do things like removing whitespace or substituting characters.

I don't think I'm the only one who was unaware of this capability: Wikipedia says that XSLT is used for the transformation of XML documents, while OxygenXML's XSLT debugger doesn't even work if you select a text file as input; you have to pass the name of the text file to the XSLT file as an input parameter. More on this later.

To process plain text with XSLT, you need to use a couple of functions that were new with XSLT 2.0, so you must use an XSLT 2.0 processor such as Saxon 9. For the examples that follow, I used the Saxon EE-9.3.0.5 that comes with OxygenXML 13.2.

The following example is based on an FAQ page maintained by Dave Pawson:

1. Start OxygenXML and create a new XSL 2.0 file.
2. Specify XML as the output method and declare a parameter called input that will hold the name of the input file (because we need to pass the name of the text file as an input parameter, remember?):
   

   <xsl:stylesheet xmlns:xsl=
   http://www.w3.org/1999/XSL/Transform xmlns:xs="http://www.w3.org/2001/XMLSchema" 
   exclude-result-prefixes="xs" version="2.0">
     <xsl:output method="xml" indent="yes" encoding="utf-8" />    
     <xsl:param name="input" as="xs:string" required="yes"/>
   
   

3. Next, declare a variable that will contain the entire contents of the text file as a single string. I've wrapped everything in <doc> tags:
   

   <xsl:variable name="src">
    <doc>
     <xsl:for-each select="tokenize(unparsed-text($input, 'iso-8859-1'),
    '\r\n')">
       <line><xsl:value-of select="."/></line>
     </xsl:for-each>
    </doc>
   </xsl:variable>
   

   Several XSLT functions are used here:
   
   1. unparsed-text reads the contents of the text file (identified by the variable $input) into a string
   2. tokenize then splits this string up into a series of strings at each CRLF character, that is, at the end of each line.
   3. Finally, the <xsl:for-each.. /> instruction processes each string in turn and wraps it in <line> tags to make the XML output a bit more legible.
4. The only template necessary generates the XML output file and copyies the modified contents of the $src variable to it:
   

   <xsl:template match="/">         
    <xsl:result-document href = "src1.xml">
     <xsl:copy-of select="$src"/>
    </xsl:result-document>
   </xsl:template> 
   

5. Before running this script through OxygenXML's debugger, you need to define the input parameter:
   
   1. Switch to the XSLT Debugger (Window < Open Perspective < XSLT Debugger)
      
   2. Click the Configure parameters button on the toolbar.
      
   3. Click New
      
   4. Type input for the Name and the name of a text file as the Value, for example regex.txt
      
   5. Click OK twice.
      
6. Now select the XSL file in the XSL box, select any XSL file in the XML box (OxygenXML ignores it), and run the debugger. The output appears in the results window, for example:
   

   <doc>
      <line>27/09/2003  12:36                4,500 andAndOr.xml</line>
      <line>27/09/2003  12:36                2,565 apply-imports.xml</line>
      <line>27/09/2003  12:36                2,054 applytemplates.xml</line>
      <line>22/03/2004  15:53               16,141 approaches.xml</line>
      ...
   </doc>  
   

In subsequent posts, I'll show how to apply regular expressions to the plain text to get better formatted output.

Going back to Google Blogger...

I was using Wordpress for my blog, but I've had enough of the endless spam so I'm back with Google now. I've copied some entries across, so they're not new.

Exporting DITA to HTML5

I've been somewhat surprised at the lack of any real discussion on this topic so far apart from a few posts on the DITA-USERS forum about video codec compatibility and a good article by Don Day. The current explosive growth in the number of smart devices deployed will inevitably lead to a strong demand for technical documentation on mobile platforms. PDF- and HTML-based documents as well as eBooks can, of course, already be used on smart devices by means of native viewers, mobile browsers and eBook readers. The PDF and HTML user experience is generally poor, involving a lot of tapping, pinching, scrolling and rotating to get content to display correctly. Although the eBook user experience is much better, especially on tablets, eBook readers are proprietary native applications and mobile platform owners have imposed all sorts of restrictions on content. HTML5 promises to offer a superior user experience for mobile users. Mobile browsers already do a good job of automatically resizing and reformatting HTML5-based content to match devices' screen sizes and resolutions. HTML5 content can be rich, dynamic, and interactive so is well suited to eLearning applications, for example. So I've decided to try and create an HTML5 plugin for DITA! I hope this plugin will provide support for:

• HTML's new semantic elements such as <nav>, <header>, and <footer>
• Inline SVG graphics
• MathML equations
• Offline storage

The latest generation of browsers, including Firefox, Chrome, Safari, and Webkit-based mobile browsers, already support all these features. Internet Explorer is lagging behind as usual, but Microsoft has promised that IE10 will fully support the HTML5 standard. HTML5 is still evolving, so it looks like definitive support for things like metadata and the many Javascript APIs will have to wait for a while yet. But the core functionality is remarkably stable and well-supported, so there's already enough to be getting on with...

Adding Inline SVG and MathML to DITA

One interesting feature of HTML5 is its ability to render inline SVG and mathML markup to display 2D graphics, syntax diagrams, and equations. For example:

<html>
<body>
<h1>My first SVG</h1>
<svg xmlns="http://www.w3.org/2000/svg" version="1.1">
stroke-width="2" fill="red" />
</svg>
</body>
</html>

This sort of markup works in most modern browsers. It's called inline SVG because the SVG tags are embedded directly within the HTML code, in contrast to external SVG in which an SVG file is referenced in exactly the same way as you would a GIF or JPEG:

<img src="images/myDiagram.svg" alt="An external SVG graphic"/>

My plan for the DITA to HTML5 plugin is to pass inline SVG or mathML markup directly through from DITA topics to HTML5. Unfortunately, getting inline SVG and mathML to work in DITA is not straightforward. In fact, I've just spent the last two days doing some specialization, the mysterious science of customizing the set of tags that authors can use in DITA, in order to get it to work. The reason that native SVG and mathML support has never been included in the DITA Open Toolkit seems to be that there simply hasn't been much demand for it (and it was difficult to display in older browsers). SVG is still the only vectorial graphics format supported by DITA and hopefully one day it'll be fully integrated into the DITA Open Toolkit. My main sources of information about specialization have been Eliot Kimber's excellent DITA Configuration and Specialization tutorial and Introduction to DITA by Jennifer Linton and Kylene Bruski. Specialization can be used to modify DITA's original set of elements and attributes in several ways:

• If you don't need a particular domain (a related set of tags, for example, the User Interface domain), removing it completely so that authors no longer see any of the domain's tags in the list of available elements.
• Modifying the properties of particular tags, for example, so that <p> must contain plain text only and none of the inline formatting tags like <b> or <i> that are normally available.
• Creating new attributes for existing tags.
• Adding new custom domains.

In DITA parlance, these techniques are called respectively "Document Type Shell", "Topic Constraint", "Attribute Specialization", and "Element Domain Specialization". Conclusion: you don't have to be a geek to specialize, but it certainly helps! We're going to be doing Element Domain Specialization. To be honest, though, following Eliot's tutorial was a lot easier than I anticipated. Using oXygenXML, DITA Open Toolkit 1.5.3 and a few articles I found on Google, I got inline SVG and mathML working without too much trouble. I suspect I'll have more problems packaging it as a plugin so that others can use it, but that's for later. And there are still a lot of things I don't understand. For now, I'm going to switch to technical author mode to describe how to implement the specializations.  

Preparing a Test Environment

1. Copy the entire {dita-ot-root}/dtd/technicalContent folder (where {dita-ot-root} is the root folder of your DITA Open Toolkit installation) to a temporary folder.
2. Create a new DITA concept topic and change the DOCTYPE line to point to the concept.dtd in your temporary folder, for example:

   <!DOCTYPE concept SYSTEM "C:/temp/technicalContent/dtd/concept.dtd">

   Note: If your editor adds a PUBLIC identifier as well as or instead of a SYSTEM identifier when it creates a new topic, I would recommend removing it, as a PUBLIC identifier takes precedence over the SYSTEM one and your topic will validate even if the SYSTEM identifier is wrong or a problem occurs in the specialization files.
3. Validate the topic to check that the DTDs in your working folder are being used.
4. Save the topic with a .dita or .xml extension to any folder.

Adding Inline mathML support to DITA

Domain specialization requires you to create two files, a .mod (module) and a .ent (entity), then  update the DTD to reference them. This example only shows the concept DTD, but you'd need to do it to the other topic types' DTDs too (there must be a way of doing it to the base DTD, ditabase.dtd, so that it works for all topic types, but I couldn't figure that out).

1. Copy and paste this .mod file (which I've taken from a specialization article I found) and save it in your temporary technicalContent/dtd folder as mathmlDomain2.mod.
2. Copy and paste this .ent file and save it in the technicalContent/dtd folder as mathmlDomain2.ent.
3. Edit the concept.dtd file in your temporary folder and make the following changes:
   • Add these lines to the bottom of the DOMAIN ENTITY DECLARATIONS section:

     <!ENTITY % math-d-dec SYSTEM "mathmlDomain2.ent">
     %math-d-dec;

   • In the DOMAIN EXTENSIONS section, add the lines:

     <!ENTITY % foreign "foreign | %math-d-foreign;">
     <!ENTITY % unknown "unknown | %math-d-unknown;">

   • In the DOMAINS ATTRIBUTE OVERRIDE section, add the line:

     &math-d-att;

   • In the DOMAIN ELEMENT INTEGRATION section, add the following lines:

     <!ENTITY % math-d-def SYSTEM "mathmlDomain2.mod">
     %math-d-def;

   Save the changes and validate your concept topic to check that you haven't messed things up.

That's it! Position the cursor within a <p> element in your concept topic and you should now see new elements like <equation> and <math> in the list of available elements. To test it on something meaningful, you can use the following sample code:

<math type="presentation">
   <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"
    display="block">
    <mml:semantics>
     <mml:mrow>
      <mml:mrow>
       <mml:mi mathvariant="bold">a</mml:mi>
       <mml:mo>=</mml:mo>
       <mml:mfrac>
        <mml:mrow>
         <mml:mi mathvariant="bold">F</mml:mi>
        </mml:mrow>
        <mml:mi>m</mml:mi>
       </mml:mfrac>
       <mml:mo>=</mml:mo>
       <mml:mfrac>
        <mml:mrow>
         <mml:mi>q</mml:mi>
         <mml:mo>[</mml:mo>
         <mml:mi mathvariant="bold">E</mml:mi>
         <mml:mo>+</mml:mo>
         <mml:mfenced>
          <mml:mrow>
           <mml:mi mathvariant="bold">v</mml:mi>
           <mml:mi>X</mml:mi>
           <mml:mi mathvariant="bold">B</mml:mi>
          </mml:mrow>
         </mml:mfenced>
         <mml:mo>]</mml:mo>
        </mml:mrow>
        <mml:mi>m</mml:mi>
       </mml:mfrac>
      </mml:mrow>
     </mml:mrow>
    </mml:semantics>
   </mml:math>
  </math>

Note:  In my original post, I had wrapped <equation> tags around the above example. This was wrong. The equation element is meant to be used as the top-level element in a separate file and as a container for MathML markup. You would then include the markup in a topic using something like <xref type="eq" href="equation1.dita"/>. I have not been able to get this to work and it isn't even documented anywhere as far as I can tell.

Adding Inline SVG support

SVG integration follows the same basic procedure as MathML: create .mod (module) and .ent (entity) files, then update the DTD file.

1. Copy and paste this .mod file and save it in the technicalContent/dtd folder as svgDomain.mod.
2. Copy and paste this .ent file and save it in the technicalContent/dtd folder as svgDomain.ent.
3. If you don't already have it, do a Google search for the svg11.dtd file and copy it into the technicalContent/dtd folder.
4. Edit the concept.dtd file in your temporary folder and make the following changes:
   • In the DOMAIN ENTITY DECLARATIONS section, add the lines:

     <!ENTITY % svg-d-dec SYSTEM "svgDomain.ent">
     %svg-d-dec;

   • In the DOMAIN EXTENSIONS section, modify the line that you previously edited for mathML to:

     <!ENTITY % foreign "foreign | %math-d-foreign; | %svg-d-foreign;">

   • In the DOMAINS ATTRIBUTE OVERRIDE section, add the line:

     &svg-d-att;

   • In the DOMAIN ELEMENT INTEGRATION section, add the following lines:

     <!ENTITY % svg-d-def SYSTEM "svgDomain.mod">
     %svg-d-def;

   Save the changes and validate your concept topic again to check that everything works.

That's it! Position the cursor within a <p> element in your concept topic and you should now see the new <svg> element in the list of available elements. To test it on something meaningful, you can use the following sample code:

<svg>
   <svg:svg xmlns:svg="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
      <svg:ellipse cx="300" cy="150" rx="200" ry="80" style="fill:rgb(200,100,50);
            stroke:rgb(0,0,100);stroke-width:2"/>
    </svg:svg>
</svg>

When you've finished testing, remember to;

• Repeat the procedure for the Task and Reference topic types
• Copy the contents of your temporary /dtd/technicalContent folder to your DITA Open Toolkit folder, replacing the original contents.

Conclusions and Next Steps

Just to prove it does work, here's a screenshot from oXygenXML showing a bit of inline SVG and mathML:



The next steps are:

1. To package this as a plugin so that anyone can add it to their DITA Open Toolkit
2. To update my DITA to HTML5 transformation so that the inline mathML and SVG appear in my HTML5 topics.

More on that at a later date...

Mapping DITA Elements to HTML5

I've been wondering how best to map DITA elements to HTML5's new semantic tags.

<header> and <footer>

These two tags are straightforward. I'll wrap them around the contents of any custom HTML specified with the arg.hdr and arg.ftr DITA parameters.

<article>

The HTML5 specification describes an article as being "a self-contained composition in a document, page, application, or site that is, in principle, independently distributable or reusable". That seems to closely match the DITA concept of a topic. So there are two possibilities:

1. Don't use <article> at all in the generated HTML5, except if topics are being chunked together in a single physical file.
2. Start the body of each topic with <article>, for example: <body> <article> ... <article> </body>

<section>

In HTML5, a section is used to logically subdivide a document or article:

This clearly corresponds to a DITA section, which "represents an organizational division in a topic".

<nav>

The HTML5 spec says that nav is "a section of a page that links to other pages or to parts within the page". The purpose of introducing such tags to HTML5 is to indicate to search engines that they don't need to index the content in them, so speeding up searches. Although it doesn't quite match because the links are not internal, I think this is a good match for the related links section of a DITA topic.

<aside>

This new HTML element represents "a section of a page that consists of content that is tangentially related to the content around the aside element, and which could be considered separate from that content". It's plainly important that content in the aside is distinctly styled: for example, as a right-aligned sidebar in printed material, or as a floating box with a distinctive background color or border in a web page. So perhaps the best match in DITA terms is the abstract element.

<hgroup>

This element is supposed to group consecutive headers together, for example: <hgroup> <h1>Main Title</h1> <h2>Secondary Title</h2> </hgroup> Stacked headings with no intervening text are considered bad practise in technical document, and DITA's DTDs reinforce that by not allowing them. The only time it could happen in DITA is when the titlealt element is used to provide an alternative header (for example, one that appears in search results or in a table of contents). But only one of the titles appears in the document at any one time. So I'm inclined not to use hgroup at all.

Fonts in PDFs

This seems like an odd choice for default behaviour...

To get any other font than the default (Helvetica) to appear in your PDFs, you have to copy the font-mappings.xml.orig file to font-mappings.xml in the folder dita-ot_homedir\demo\fo\Customization\fo. Until you do, the i18n-postprocess.xsl file in the demo\fo\xsl\fo folder adds a font-family="Helvetica" attribute to elements' FO code, overwriting any other fonts you may have specified for the element.

Adding a chapter to a DITABOOK

There are many ways to add a new chapter to a DITABOOK. Not all work...

When the chapter's content is in a single topic file, it is straightforward:
<chapter navtitle="Introduction" href="cIntroduction.xml"/>

A chapter may have an introductory paragraph or two before the first level one heading (typically "This chapter describes..."). In this case, just use the previous example and add topicref tags pointing to the chapter's sections. The topicrefs must be child elements of the chapter tag, for example:
<chapter href="TaskHelp/cIntroduction.xml">
<topicref navtitle="Updating a Module" href="FieldHelp/rModule_Update.xml"/>
</chapter>

If the chapter's content is more complex, you might prefer to put the chapter's content in a DITAMAP and reference this DITAMAP in the chapter tag:
<chapter href="chapter1.ditamap" format="ditamap"/>

There are some pitfalls too:

• If you do reference a DITAMAP, it must only contain a single top-level topicref tag. Otherwise, all the top-level topicref tags appear in the generated PDF at the chapter level but are not numbered as chapters.


• You must have an href attribute on the chapter tag, otherwise the topicref's titles appear at the chapter level and there's no chapter title. So neither of the following examples work:
  <chapter>
  <topicref ...>
  </chapter>
  <chapter navtitle="Introduction">
  <topicref ...>
  </chapter>

Visio and SVG still don't work together

Unfortunately, Microsoft don't seem interested in fixing the bug in Visio's SVG export filter that leaves arrowheads off lines. The bug survived the SP2 and SP3 updates for Visio, and apparently is even present in Visio 2007!
There are several workarounds:

• Don't use arrowheads in diagrams!
• Fix the SVG file before using it
• Use a different tool altogether.

To draw arrows in Visio, just draw one long and two short lines (or a line and a filled triangle), then group them together. Not pretty, but it works.

I found a small XSLT script that fixes the problem. Because SVG files are XML, you can run the script against the SVG, then save the resulting XML as a new SVG file. Here's the script:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xsl:stylesheet>
<!-- Workaround for:
http://issues.apache.org/bugzilla/show_bug.cgi?id=38831 -->
<!-- Adds overflow="visible" to all <marker> elements. -->
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg" exclude-result-prefixes="svg">
<xsl:output method="xml" indent="no"/>
<xsl:template match="svg:marker">
<xsl:element name="marker" xmlns="http://www.w3.org/2000/svg">
<xsl:copy-of select="@*"/>
<xsl:attribute name="overflow">visible</xsl:attribute>
<xsl:copy-of select="node()"/>
</xsl:element>
</xsl:template>
<xsl:template match="@*¦node()">
<xsl:copy>
<xsl:apply-templates select="@*¦node()"/>
</xsl:copy>
</xsl:template>
</xsl:stylesheet>

I use oXygen to perform the transformation using the XSLT Debugger.

As far as alternative tools are concerned, I'm testing an Open Source tool called Inkscape. First impressions are that its interface is a bit quirky, but it seems perfectly adequate.

Migrating to a newer version of DITA-OT

Migrated to the latest "M24" milestone of the DITA-OT toolkit yesterday to hopefully benefit from some of the bug fixes.
The only things to do to migrate were:

• Copy my custom CSS files in the /css folder across.
• Copy the /common folder across (contains toolbar graphics for XHTML).
• Copy the /demo/fo/myCustomization folder across (customization layer for PDF generation).
• Edit the /demo/fo/build.xml file and edit the line <property name="customization.dir ... > to point to the customization folder.

oXygen stalls creating PDF file

This one has got me a couple of times recently, so it's probably more for my benefit than anyone else's.

When generating PDFs using oXygen, the PDFs are created correctly when using oXygen's internal DITA-OT. However, when I switch to using my own DITA-OT, the transform stalls when creating the .PDF from the .FO. As usual, oXygen's tech support came to the rescue...

Seems that "with Windows XP, Apache FOP blocks the console before the PDF is generated", whatever that means.

oXygen have introduced a patch into their internal DITA-OT to get around this. So you need to copy this patch across to your external DITA-OT version to benefit from the patch:

1. In the build.xml file, search for the "transform.fo2pdf.fop" target.
2. Comment out the target template and replace it with the following one:

<target name="transform.fo2pdf.fop" if="use.fop.pdf.formatter">
<java classname="org.apache.fop.cli.Main" fork="yes" classpath="${java.class.path}" dir="${dita.map.output.dir}" failonerror="true">
  <arg line="-fo "${inputfile}" -pdf "${outputFile}" -c "${fop.home}/conf/fop.xconf"/>
<java>
<target>

Migrating to oXygen 11

DITA-OT transformation scenarios created for version 10.3 do not work with oXygen 11. The 10.3 scenarios contain references to Saxon libraries that no longer exist in oXygen 11 because they have migrated to the enterprise edition of Saxon.
There are two easy workarounds:
1) Create new transformation scenarios and manually recreate the settings.
2) Edit the old transformation scenarios. Go to the Advanced tab and click the Libraries button.
In the Custom Libraries list, remove saxon9sa.jar and saxon9-dom.jar, then add ${oxygenHome}/lib/saxon9ee.jar

Figure sizes for DITA output to PDF

We will be having some people using FOP and others using XEP to generate PDF files. It's actually quite difficult to set the width and height attributes of figures so that graphics look good in both formats. Here are some recommendations:
- FOP and XEP only have a very limited number of supported formats in common: GIF, JPEG and PNG for bitmaps and SVG for vectorials.
- Only specify the width. The DITA-OT will then calculate the height automatically so as to preserve the original aspect ratio.
- Specify the width in "real" width units, for example "10mm" or "3in".
- For vectorial graphics, specify the same width value for all graphics to obtain a cleaner output. In the old FrameMaker template, the main text column was 135mm wide, so this is a good value to use.

So, for example:
<fig>
<img align="right" width="135mm" placement="break" href="architecture.svg"/>
</fig>

Another DITA project...

Been a while since my last blog. How do all those twitters find the time to do it every single day?

I've been pushing DITA at my Marseille client for a couple of years now. Initially, they had agreed to trial it on some online help for a new project. Turns out a couple of customers had been complaining that information was only available online, whereas they'd like it in a User Guide format as well. So DITA was an easy sell. I did some templates in FrameMaker and used Leximation's DITA-FMx plug to produce a set of help files that looked pretty similar to the current lot, as well as a PDF containing pretty much the same information.

Throughout 2008, I did all the new product helps in DITA, and systematically produced a User Guide. It became known as the "new" help format (as opposed to the "old" help format). However, I remained the only writer using it: everyone else was still merrily tapping away in FrameMaker 7.2 (!)

Then in May 2009 I was summoned to a meeting at which they were going to decide between DocBook and DITA as the next Corporate documentation standard. One guy had gone so far as to convert an entire Word document into DocBook. I managed to get in a quick DITA demo, and fortunately the guy accepted that DITA was the better option. Within an hour, they had ditched FrameMaker in favour of DITA for all new documentation.

The only downside was that they want nothing to do with the FrameMaker/DITA-FMx solution. The problem they have had with FrameMaker is that developers and other engineers want to create official documents, and there's no way they were going to buy licenses and train everyone in FrameMaker.

So I was to do a customization of the DITA-OT PDF2 transform, which uses XSL:FO and FOP or XEP to generate PDF files. They gave me a mere 10 days to do this, which seems a little tight at the time and once I'd looked at the customization procedure seemed very tight indeed! A pilot project was selected and everyone seemed happy. Selling DITA really is easy.

Fast forward to early August and the template is done. Last week I sent it to a fellow tech writer and we got here to produce her first DITA-based PDF file within a day (spent almost entirely trying to generate a .BAT file that set up the DITA enviroment correctly).

The next step is to get all the writers and developers using DITA... but that will have to wait for the rentrée (a curiously French thing the rentrée... I used to think it was simply when the kids went back to school, but it's a much border cultural event. People lie on the beach all summer dreaming up schemes to get themselves promoted when they go back to work: the rentrée is when all these ideas are thrown at us poor contractors to implement. Strangelyl, it's also traditional in France to go on strike at this time... any minor complaint will do. I have arranged my holidays for the end of August/beginning of September specifically to avoid it).

Anyway, to conclude, I learnt a lot during those 10 days, and will try to document some of them here. While it may appear that this is to inform you, in fact it's just so that I don't forget these things the next time I do such a project (and I'm probably the only person that ever reads this stuff anyway...)

DITA-FMx: Different title/bookmark in PDF output

DITA-FMx always uses the <title> element in a topic file to generate title text in both XHTML and PDF outputs (regardless, for example, of the value of the navtitle attribute on the corresponding <topicref> element in the ditamap, and regardless of the value of the locktitle attribute).

I wanted a way to have one title on my HTML help pages and optionally a different one in the PDF file I generated using DITA-FMx's Generate Book from Map command.

I decided to use the <navtitle> element under <titlealts> ("alternative titles") in topic files to specify an alternative title for PDF output. I'm not too sure that this is DITA-compliant, but it works a charm. There's no support for this element in the default structured applications supplied with DITA-FMx, so I needed to make some modifications.

1. I edited the EDD of the DITA-Topic-FM structured application (which is just used to format text while you are authoring a topic), and added some formatting for the <titlealts> element, for example, 12pt, Red, and Bold. I also added a Prefix to remind me what it was for!

2. I edited the ditamap2fmbook.xsl file of the DITA-Book-FM structured application (which is used to format text for the FrameMaker book generated using the Generate Book from Map command). As its title suggests, this file translates a ditamap into a FrameMaker book. In fact, it only accomplishes the first stage of the conversion process, namely to generate a single XML file that includes all the ditamap and topic file content. This file is then further processed by FrameMaker's Read/Write Rules and converted to FM files.

Editing this XSL file is unfortunately not too straightforward. I needed to make sure that whenever a <navtitle> element is found in a topic file, its text is to be written into the generated XML file as the <title> element in place of the default, top-level <title> element. Here is the key part of the modified XSL:

<xsl:template match="title">
<title>
<xsl:choose>
<xsl:when test="following-sibling::titlealts/navtitle">
<xsl:copy-of select="@*">
<xsl:value-of select="following-sibling::titlealts/navtitle/text()">
</xsl:when>
<xsl:otherwise>
<xsl:copy-of select="@*node()">
</xsl:otherwise>
</xsl:choose>
</title>
</xsl:template>

So when the <title> element is followed by a sibling <titlealts> element that has a child <navtitle> element, write that element's text into the <title> element instead. Otherwise, just use the <title> element's text as usual.

Now when I want a different bookmark and heading in my PDF, I just add a <navtitle> element to my topic file, and set the locktitle attribute to "yes" in the <topicref> element of the ditamap that references the topic file. If I set the locktitle attribute back to "no", the <navtitle> is ignored and the default title text is used instead.

Automatically applying master pages

I use DITA-FMx's Generate Book from Map command to generate a FrameMaker book from a DITAMAP. I have tried to streamline the process as much to possible, with the result that I can now generate a full-featured PDF file from a DITAMAP in just a few minutes.

One of the things that saves a bit of time is automatically applying master pages to the generated FrameMaker documents.

To do this, I set up the following table on the MasterPageMaps reference page of my DITA-FMx-Book template file:



The last line, beginning with E:title, instructs FrameMaker to test the value of the outputclass attribute on the title element of a DITA topic file and assign the NonChapterPage1 master page if the attribute value is "NonChapterName".

I assign the master pages by either:

- Selecting the chapter files in the Book window and choosing Format > Page Layout > Assign Master Pages

- Selecting the Apply Master Pages checkbox on the Update window when I first regenerate the table of contents for my book.

Compiling FDK clients for FrameMaker 8.0

My FrameMaker Development Kit (FDK) clients were originally developed for FrameMaker 7 using Microsoft Visual C++. They always seemed to work fine on FrameMaker 8 too, but I baulked at upgrading Visual C++ because it was so expensive. However, I do get a lot of requests for FM8-specific versions of the EZVars clients, so over the Christmas holidays I finally got round to the upgrade.

Upgrading was actually a lot easier, and cheaper, than I imagined.

The first nice surprise was that Microsoft have released a free version of Visual C++, "Microsoft Visual C++ 2008 Express Edition". Bit of a mouthful, but it has all the functionality you need to create and compile FDK clients, and is compatible with FrameMaker 8.0.

The second nice surprise was that I needed to make just a couple of minor modifications to get the clients working in the new environment:

- In Tools > Options > Projects and Solutions > VC++ Directories, add the FDK8\include and FDK8\lib directories.

- In the versioninfo.rc resource file, change all references to "afxres.h" to "windows.h". (This file is only needed if your client displays dialog boxes or you want the client to auto-install itself in the fminit\Plugins folder without needing be registered in the maker.ini file).

Recompile, and away you go...

Weird problem with Type 1 fonts

Choosing and moving to a new laptop is always a big challenge. My latest move, from a Dell Inspiron to a Dell Latitude E6500, had been going quite well. I had installed all my applications, and managed to locate all the corresponding registration codes and licenses (thank goodness for Gmail). The next step was to get my FrameMaker and Acrobat setup working. I copied some old Type 1 fonts that I use from the old laptop, went into the Fonts applet in the Control panel and imported them, only to receive a bunch of "font corrupted" messages. Assuming the Zip file had somehow gotten messed up, I copied the fonts across again, but the same messages appeared.
Googling for a while, I discovered that the Dell Latitude E6500 has a problem with Type 1 fonts. Various forum messages suggested upgrading the NVidia video drivers, which sounded like a lot of hassle. Then I found the following entry on a Dell forum:

Just wanted to let any one know with the type 1 font installation issue - the issue is with the NVIDIA driver. This is only on systems with XP and does not effect Vista. Windows expects the NVIDIA device driver to be a certain size (maximum). The NVIDIA driver is slightly larger than expected. A simple registry entry resolves the type 1 font issue in XP. To resolve the issue, complete the following:

Open the registry editor (START, RUN and type regedit and click OK)

Navigate to the following key - HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\
Control\SessionManager\MemoryManagement

Add a new REG_DWORD Value - Change the name of the value to SessionImageSize with a value (decimal) of 20 and then reboot the machine.

You will now be able to install your type 1 fonts and have the latest proper video driver as well


Worked perfectly, and now I have all my Type 1 fonts installed. How weird is that?

Generating PDF output with DITA-FMx

(FrameMaker 8, DITA-FMx v1.00.26, DITA 1.0)

The following is a procedure that I have tested and almost perfected over the past couple of months to make a FrameMaker User Guide (and hence a PDF file) from a set of DITA topics originally targeted as online help.

1. I want my User Guide to have a classic "book" structure rather than the Task/Reference/Concept structure of the online help, so I create a separate DITAMAP file specifically for the User Guide. Bear in mind that only top-level topic references in the DITAMAP file will map to chapters in the FrameMaker book.

2. Create a DITAVAL file. Create or register this DITAVAL file with DITA-FMx using the DITA-FMx > Ditaval manager menu option. Create two entries in the DITAVAL file; "print" and "online". For the User Guide, you'll need to set the print action to "include" and the online action to "exclude". For example:

<val>
<prop att="audience" val="print" action="exclude" />
<prop att="audience" val="online" action="include" />
</val>

3. Add any User Guide-specific content to your DITA topic files. For example, I want screen captures to appear in the User Guide but not in the online help, so I add <fig> elements wherever appropriate. Set the audience attribute on the element to "print". Similarly, if you have content specific to the online help that you don't want to appear in the User Guide, set the audience attribute to "online".

4. In the DITA-Fmx options window, set the DITA book application to the appropriate "book generation" application. Your application developer should have set this up for you: basically the Book application is a Structured application registered with FrameMaker that points to all the Template, EDD, and DTD files necessary to generate the book. You can review the available applications with StructureTools > Edit Application Definitions. The value of the ApplicationName element is the name that appears in DITA-Fmx's list of available applications.

5. Choose DITA-FMx > Generate Book from Map. You will probably get a "Validation of XML file failed" message box with a bunch of errors. Ignore these for now.

6. Choose the book name. You will be using a "dummy" book originally, so I generally call it something like "DUMMY.book".

7. When the Book window appears, save it immediately with the "real" name (File > Save book as).

8. Working now with the "real" book, add title page, front matter, and back matter files as necessary. I typically have Titlepage, Preface, TOC, and Index files, for example. Add these in a "nonstructured" way as you would with unstructured FrameMaker.

9. I generally use the Titlepage document to contain all the universal variables that I use in the unstructured files and in the headers and footers of the structured files. For example, I set up ProductName and BookTitle variables. This way, I can easily import the variables into all the unstructured and structured files. More of this later.

At this stage, you'll probably want to do a bout of debugging to set up the "real" book exactly as you want it. For fixes to the structured files, obviously do them in the original DITA topic files and DITAMAP, or they'll get overwritten the next time you re-generate the "dummy" book.

When everything is set up as I want, I proceed as follows whenever I need to re-generate my User Guide:

1. Make the User Guide DITAMAP file the current document.

2. Check that the DITAVAL file is set up with "print=include" and "online="exclude".

3. Choose DITA-FMx > Generate Book From Map. Overwrite the "dummy" book file and confirm overwriting all files.

4. Close the "dummy" book file and open the "real" book file.

5. Open the Title page and import its variables into all other files in the book (File > Import > Formats).

6. Apply the correct Master pages to the generated files in the book (Format > Page Layout > Apply Master Pages).

7. Run DITA-FMx > Apply Ditaval as conditions. This sets all text that is marked as "exclude" in the DITAVAL file as conditional text and hides it.

8. Optionally, turn off Conditional text indicators in each of the generated files (by default, text tagged with the "print" action appears in red).

9. Generate the book (Edit > Update book).

10. When it's what you want, File > Save as PDF and create your PDF file.

I have this second procedure down to about 5 minutes per book now!

The only caveat is that if ever you update your DITAMAP with a new top-level entry that causes a new FrameMaker chapter file to be created, you'll need to remember to manually add the new file to the "real" book.

One other "bug" I have noticed is that if you use the locktitle attribute in your DITAMAP to specify Title text specifically for the User Guide, the navtitle text doesn't get copied to the PDF bookmarks when you generate a PDF file. Hopefully this will get fixed in a future release.