Syntax Highlighting with DITA

Syntax highlighting is something that I like in user documentation because I feel that it helps make source listings easier for people to understand.

When I first examined the possibilities several months back there did not appear to be a ready solution that worked with Ditac by XMLmind. Additionally the DITA specification does not seem to specify a standard technique for identifying the syntax used in code blocks. I had planned to integrate XSLTHL into my XHTML and XSL:FO stylesheets but I couldn’t really spare the time.

Fortunately it seems that XMLmind have themselves implemented syntax highlighting using XSLTHL. As a bonus they have implemented this for each of the supported deliverables and customizing the output styles and colours is super easy.

A good selection of syntaxes are supported which can be activated using the outputclass attribute.

<codeblock outputclass="language-csharp"><![CDATA[
public class SomeCoolClass {

    public void DoSomething() {
        Debug.WriteLine("Hello World!");
    }

}
]]></codeblock>

Here is an example from the Rotorz Tile System user guide:
http://rotorz.com/tilesystem/guide?ref=25d80dd4-f917-424a-a390-b95e5588f69c

Working with DITA Topic Identifiers

When writing my new user documentation using DITA I have found myself attempting to maintain a consistent naming convention for my unique topic IDs. The problem with this approach (to me at least) is that it would be fairly easy to inadvertently reuse the same “unique” identifier for two separate topics.

So I pondered on a better solution and did some searching through online user documentation that uses DITA (or something very similar). One of the things that I noticed about these various websites is that they use a GUID instead of a carefully named identifier. A much easier solution! All I needed was an easy way to generate GUIDs in my XML documentation.

Unfortunately the XML software that I use (OxygenXML) doesn’t appear to have a GUID generator built-in as standard. Instead of wasting too much time trying to figure out how to write a Java plugin for Oxygen I decided to write a simple application using C# which registers a system-wide hotkey Ctrl+Shift+V which generates a new GUID (with a custom prefix “guid-“) and pastes that into the application that I am working with (Oxygen and NotePad++). Another nice touch is that because this uses the clipboard Ctrl+V can be used to re-paste the same GUID over and over until a new GUID is generated (or until something else is copied to the clipboard!)

I added a few extra options which others might benefit from and uploaded the source (BSD) and a compiled executable to GitHub for those who might find this of use!

https://github.com/kruncher/guid-generator-hotkey

Choosing an Extensible Documentation Solution

For a while I have been using Microsoft Word to author user guides and to be fair this has been a good solution up until now. Since beginning work on Rotorz Tile System there have been a number of product updates which have required multiple updates of the user documentation. Despite using style presets the process of maintaining consistent formatting and updating illustrations is extremely time consuming. I also feel that there is a need for a web based version of the documentation to make it easier for some people to find their way around.

So… ultimately I required a solution that takes a number of document fragments that can be composed in a variety of ways to provide at least two deliverables (PDF plus web based documentation). After some careful thought I also decided that I would like to avoid directly formatting the documentation that I write to save valuable time; this should be handled automatically by the documentation solution.

Continue reading

XPointer Framework for XSLT 2.0

In a recent project I found myself needing more flexibility when cross-referencing XML content during XSLT transformations. The XSLT 2.0 specification (as implemented by Michael Kay) only includes shorthand XPointers. So this seemed a good opportunity to write a more complete implementation of the XPointer Framework for Michael Kay’s fantastic Saxon processor.

Essentially, XPointer allows one to reference a fragment of a resource (as opposed to the entire resource):

<!-- Shorthand XPointer: Locate a customer using the @xml:id attribute. -->
<order customer="customers.xml#cust001"/>
<!-- Element Scheme: First customer in an element where @xml:id="customers". -->
<order customer="customers.xml#element(customers/1)"/>

My implementation of this includes support for the standard xmlns() and element() schemes, and additionally the xmlns-local(), xpath1() and xpath2() schemes. This implementation, however, does not yet include the xpointer() scheme.

Additional schemes can be implemented by providing a custom template. The template will be invoked automatically by the XPointer framework stylesheet when the scheme is detected in a URI upon lookup. Custom schemes should be qualified with a namespace so as to avoid conflicts unless implementing a standardized scheme.

I have made the stylesheet (and some examples) freely available under the BSD license.

Check out http://www.rotorz.com/xml/2009/XPointer for more information and downloads.