Mar 18

DocBook in NAnt

Tag: UncategorizedSymon Rottem @ 10:10 am

Over the weekend I changed the way I’ve been building the new DocBook based documentation for Castle so that it’s more in line with normal automated build processes.

The process is somewhat new to me – I’ve never written an NAnt script in my life, so there’s been a bit of a learning curve involved…especially when trying to get do DocBook XSL transformations with syntax highlighting!

For example, take the following:

<exec program="xsltproc">
	<arg value="--output" />
	<arg file="${build.single.dir}/index.html" /><!-- file to output transform results to -->
	<arg file="customizations/html_chunked.xsl" /><!-- xsl to do the transforming -->
	<arg file="${source.dir}/book.xml" /><!-- xml file to transform -->
</exec>

This is a pretty straight forward NAnt exec task that’s running xsltproc.exe from the Win32 build of libxslt – an XSL transformation engine. Seems easy enough, right?

Ok, I chose this particular engine because I’ve chosen to make my DocBook files modular so I don’t have one giant XML file containing all the content. To do that I’ve used XIncludes and to make the engine support them all I need to do is add one argument:

<exec program="xsltproc">
	<arg value="--xinclude" />
	<arg value="--output" />
	<arg file="${build.single.dir}/index.html" /><!-- file to output transform results to -->
	<arg file="customizations/html_chunked.xsl" /><!-- xsl to do the transforming -->
	<arg file="${source.dir}/book.xml" /><!-- xml file to transform -->
</exec>

So good so far.

Where I ran into trouble was that I want to use the syntax highlighting in DocBook XSL – now things turn ugly. I can’t use my nice simple transformation engine anymore because the xslthl syntax highlighting library used by DocBook XSL is in Java and that means I need to use a Java based XSL transformation engine – I’ve chosen Saxon…but Saxon doesn’t support XIncludes out of the box. Aargh! Ok, there’s a way out of this, right? You betcha. You need to hook in Xerces so Saxon can use it for resolving XIncludes.

So, in summary, if I use Saxon, hook in the xslhtl package for syntax highlighting, then Xerces for XInlcude pre-processing to do what is otherwise the same as the task above the resulting NAnt task looks like this:

<exec program="java" useruntimeengine="true">
	<arg value="-cp"/>
	<arg>
		<path>
			<pathelement file="toolchain/saxon/saxon.jar"/>
			<pathelement file="toolchain/xslthl/xslthl.jar"></pathelement/>
			<pathelement file="toolchain/xerces-2_9_1/xercesImpl.jar"></pathelement/>
		</path>
	</arg>
	<arg value="-Dxslthl.config=file:///${project::get-base-directory()}/customizations/highlighters/xslthl-config.xml"/>
	<arg value="-Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl"/>
	<arg value="-Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl"/>
	<arg value="-Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration"/>
	<arg value="com.icl.saxon.StyleSheet"/>
	<arg value="-o"/>
	<arg value="${build.single.dir}/index.html"/>
	<arg value="${source.dir}/book.xml"/>
	<arg value="customizations/html_single.xsl"/>
</exec>

Personally I think this is scary – there must be an easier way to do DocBook transformations that won’t cost you. Does anyone have any suggestions?

As a side note, if you want to do all of the above without installing Java the above task can be executed using IKVM.NET as described in my last post.

Related Posts