Archive for the ‘Tools’ Category

Docbook 5.1 and topic-based authoring

June 4, 2011

Docbook 5.1 adds support for topic-based authoring. It’s studiedly neutral in its approach to topic-based authoring, in contrast with DITA’s almost religious zeal for the historical inevitability of the Topicalypse.

Without naming any names, the Docbook Definitive Guide V1.3 states:

One modern school of thought on technical documentation stresses the development of independent units of documentation, often called topics, rather than a single narrative.

It’s clear from this that the Docbook Technical Committee did not arrive at the topic epiphany by contemplating their navel in isolation, or by a blinding flash of light on the road to Damascus. And while no names are mentioned in this introduction to a pragmatic concession to topic-based authoring, Docbook 5.1 incorporates most, if not all of DITA’s features, while maintaining Docbook’s core strength of static linear narrative targeting a book-like output medium.

One thing that really screams: “Come to the mountain!” is the ability to build Docbook 5.1 topic-based output incorporating DITA topics. Just-in-time xsl processing (<transform>) is used to incorporate existing DITA topics in Docbook 5.1 topic assemblies, allowing you to come back to the fold without an expensive conversion of existing content.

Docbook 5.1 lacks the topic-based purity of DITA, implementing a dual (but isolated) static linear narrative / modular topic model, in contrast to DITA’s focus on topics uber alles, and adopting a pragmatic, descriptive approach (“hey, looks like people want to do this“), rather than a religious, prescriptive approach (“this is the one true way!“).

However, it looks to have learned from DITA, including DITA’s shortcomings, and brings its rich semantic model to the table, as well as its installed base of expertise and tooling.

A pragmatic approach is the approach that organisations need to take when moving from a pure static linear narrative approach to a modular topic-based one, so Docbook’s pragmatic compromise, along with its tooling maturity, may sit well with many organisations moving in that direction.

Syntext Serna 4.2 and DITA support

May 26, 2010

Oh, one more thing while I’m at it:

There seems to be a problem with the DITA 1.1 templates included with Syntext Serna 4.2 (the Open Source version, of course). The xml generated by the template contains both xsd and dtd declarations.

For example:

<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd" []>
<concept xmlns:xsi="" id="concept-1" xsi:noNamespaceSchemaLocation="urnasis:names:tc: dita:xsd:concept.xsd:1.1">

You can see there a Doctype declaration, which invokes the DTD for validation, followed by an xsd declaration as an xmlns attribute of the concept element.

The problem with this is that either xsd or dtd should be used as the xml schema, not both. If both are present Xerces will attempt to do both types of validation. When it does DTD validation it will fail, because an xsd declaration is not part of the DTD.

Putting both types of validation into the template looks like a bug. If you create a new DITA 1.1 Concept from the template, and then Publish > HTML, it produces the error:

[pipeline] Using XERCES.
[pipeline] [Error] :4:155: Attribute "xmlns:xsi" must be declared for element type "concept".
[pipeline] [Error] :4:155: Attribute "xsi:noNamespaceSchemaLocation" must be declared for element type "concept".

My workaround has been to edit the template files in


and remove the xsd declaration. DITA topics created with the templates then validate fine using DTD validation.

DITA-OT 1.5 and Java version

May 26, 2010

I’ve been doing some work with the DITA Open Toolkit 1.5 lately, and got no love from Google on this issue, so here’s my contribution to anyone else who finds it:

If you are trying to build and get an error like:

DITA-OT1.5/build_preprocess.xml:80: java.lang.StringIndexOutOfBoundsException

Then check the version of your Java. I got this error with Java 1.5, and resolved it by switching to Java 1.6.

I’ll have something more to post about DITA soon, but I just thought I’d get that out there for anyone else who is scouring Google in vain.