Thursday, 5 April 2012

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.

Sunday, 27 December 2009

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.

Friday, 18 December 2009

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.

Sunday, 13 December 2009

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