Adding a DOCTYPE declaration on XSL output

In a posting a few weeks ago I discussed how to ignore the DOCTYPE declaration when processing XML through XSL. What I left unaddressed was how to add the DOCTYPE declaration back to the files. Several people have told me they’re tired of waiting for the other shoe to drop, so here’s how to add a DOCTYPE declaration.

First off: the easy solution. If the documents you are transforming always use the same DOCTYPE, you can use the doctype-public and doctype-system attributes in the <xsl:output> directive. When you specify these attributes, XSL inserts the DOCTYPE automatically.

However, if the DOCTYPE varies from file to file, you’ll have to insert the DOCTYPE declaration from your XSL stylesheet. In DITA files (and in many other XML architectures), the DOCTYPE is directly related to the root element of the document being processed. This means you can detect the name of the root element and use standard XSL to insert a new DOCTYPE declaration.

Before you charge ahead and drop a DOCTYPE declaration into your files, understand that the DOCTYPE declaration is not valid XML. If you try to emit it literally, your XSL processor will complain. Instead, you’ll have to:

• Use entities for the less-than (“<” – “&lt;”) and greater-than (“>” – “&gt;”) signs, and
• Disable output escaping so that the entities are actually emitted as less-than or greater-than signs (output escaping will convert them back to entities, which is precisely what you don’t want).

There are at least two possible approaches for adding DOCTYPE to your documents: use an <xsl:choose> statement to select a DOCTYPE, or construct the DOCTYPE using the XSL concat() function.

To insert the DOCTYPE declaration with an <xsl:choose> statement, use the document’s root element to select which DOCTYPE declaration to insert. Note that the entities “&gt;” and “&lt;” aren’t HTML errors in this post, they are what you need to use. Also note that the DOCTYPE statement text in this template is left-aligned so that the output DOCTYPE declarations will be left aligned. Most parsers seem to tolerate whitespace before the DOCTYPE declaration, but I prefer to err on the side of caution:

 <xsl:template match="/">

 <xsl:choose>

 <xsl:when test="name(node()[1]) = 'topic'">

 <xsl:text disable-output-escaping="yes">

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">

</xsl:text>

 </xsl:when>

 <xsl:when test="name(node()[1]) = 'concept'">

 <xsl:text disable-output-escaping="yes">

<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

</xsl:text>

 </xsl:when>

 <xsl:when test="name(node()[1]) = 'task'">

 <xsl:text disable-output-escaping="yes">

<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

</xsl:text>

 </xsl:when>

 <xsl:when test="name(node()[1]) = 'reference'">

 <xsl:text disable-output-escaping="yes">

<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">

</xsl:text>

 </xsl:when>

 </xsl:choose>

 <xsl:apply-templates select="node()"/>

 </xsl:template>

The preceding example contains statements for the topic, concept, task, and reference topic types; if you use other topic types, you’ll need to add additional statements. Rather than write a statement for each DOCTYPE, a more general approach is to process the name of the root element and construct the DOCTYPE declaration using the XSL concat() function.

<xsl:variable name="ALPHA_UC" select="'ABCDEFGHIJKLMNOPQRSTUVWXYZ'"/>

 <xsl:variable name="ALPHA_LC" select="'abcdefghijklmnopqrstuvwxyz'"/>

 <xsl:variable name="NEWLINE" select="'
'"/>



 <xsl:template match="/">

 <xsl:call-template name="add-doctype">

 <xsl:with-param name="root" select="name(node()[1])"/>

 </xsl:call-template>

 <xsl:apply-templates select="node()"/>

 </xsl:template>



 <span style="color: green;">&lt;-- Create a doctype based on the root element --&gt;</span>

 &lt;xsl:template name="add-doctype"&gt;

 &lt;xsl:param name="root"/&gt;

 <span style="color: green;">&lt;-- Create an init-cap version of the root element name. --&gt;</span>

 &lt;xsl:variable name="initcap_root"&gt;

 &lt;xsl:value-of

 select="concat(translate(substring($root,1,1),$ALPHA_LC,$ALPHA_UC),

 translate(substring($root,2 ),$ALPHA_UC,$ALPHA_LC))"

 /&gt;

 &lt;/xsl:variable&gt;

 <span style="color: green;">&lt;-- Build the DOCTYPE by concatenating pieces.</span>

 <span style="color: green;">Note that XSL syntax requires you to use the &amp;quot; entities for</span>

 <span style="color: green;">quotation marks ("). --&gt;</span>



 &lt;xsl:variable name="doctype"

 select="concat('!DOCTYPE ',

 $root,

 ' PUBLIC &amp;quot;-//OASIS//DTD DITA ',

 $initcap_root,

 '//EN&amp;quot; &amp;quot;',

 $root,

 '.dtd&amp;quot;') "/&gt;

 &lt;xsl:value-of select="$NEWLINE"/&gt;

 <span style="color: green;">&lt;-- Output the DOCTYPE surrounded by &lt; and &gt;. --&gt;</span>

&lt;xsl:text disable-output-escaping="yes"&gt;&lt;

&lt;xsl:value-of select="$doctype"/&gt;

&lt;xsl:text disable-output-escaping="yes"&gt;&gt;

 &lt;xsl:value-of select="$NEWLINE"/&gt;

 &lt;/xsl:template&gt;

The one caveat about this approach is that it depends on a consistent portion of the public ID form (“-//OASIS//DTD DITA “). If there are differences in the public ID for your various DOCTYPE declarations, those differences may complicate the template.

So there you have it: DOCTYPEs in a flash. Just remember to use disable-output-escaping=”yes” and use entities where appropriate and you’ll be fine.

Simon Bate

December 1, 2009

Read More

Would you use just a gardening trowel to plant a tree?

As technical communicators, our ultimate goal is to create accessible content that helps users solve problems. Focusing on developing quality content is the priority, but you can take that viewpoint to an extreme by saying that content-creation tools are just a convenience for technical writers:

The tools we use in our wacky profession are a convenience for us, as are the techniques we use. Users don’t care if we use FrameMaker, AuthorIt, Flare, Word, AsciiDoc, OpenOffice.org Writer, DITA or DocBook to create the content. They don’t give a hoot if the content is single sourced or topic based.

Sure, end users probably don’t know or care about the tools used to develop content. However, users do have eagle eyes for spotting inconsistencies in content, and they will call you out for conflicting information in a heartbeat (or worse, just abandon the official user docs altogether for being “unreliable”). If your department has implemented reuse and single-sourcing techniques that eliminate those inconsistencies, your end users are going to have a lot more faith in the validity of the content you provide.

Also, a structured authoring process that removes the burden of formatting content from the authoring process gives tech writers more time to focus on providing quality content to the end user. Yep, the end user doesn’t give a fig that the PDF or HTML file they are reading was generated from DITA-based content, but because the tech writers creating that content focused on just writing instead of writing, formatting, and converting the content, the information is probably better written and more useful.

Dogwood // flickr: hlkljgk

All this talk about tools makes me think about the implements I use for gardening. A few years ago, I planted a young dogwood tree in my back yard. I could have used a small gardening trowel to dig the hole, but instead, I chose a standard-size shovel. Even though the tree had no opinion on the tool I used (at least I don’t think it did!), it certainly benefited from my tool selection. Because I was able to dig the hole and plant the tree in a shorter amount of time, the tree was able to develop a new root system in its new home more quickly. Today, that tree is flourishing and is about four feet taller than it was when I planted it.

The same applies to technical content. If a tool or process improves the consistency of content, gives authors more time to focus on the content, and shortens the time it takes to distribute that content, then the choice and application of a tool are much more than mere “conveniences.”

Alan Pringle

November 25, 2009

Read More