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.