xmlguru.cz

Spreading the XML paradigm around

Show me your highlighted code

2006-07-22

Recently I have integrated XSLTHL source code highlighting library into the DocBook XSL stylesheets. This means that from now you can make your DocBook programlistings even more appealing to readers.


Table of Contents

Installation
Styling your code
Adding support for a new language
Choosing the right highlighter
Summary and future directions

Let's start with a small demonstration.

Example 1. Java source with syntax highlighting

import java.awt.Graphics;

// This class implements really great applet
public class Hello1 extends java.applet.Applet
{
    public void paint(Graphics g)
    {
        g.drawString("Hello, World!", 50, 25 );
    }
}

In order to get this nicely highlighted output you must set highlight.source parameter to 1 and use the following markup:

<programlisting language="java">import java.awt.Graphics;

// This class implements really great applet
public class Hello1 extends java.applet.Applet
{
    public void paint(Graphics g)
    {
        g.drawString("Hello, World!", 50, 25 );
    }
}</programlisting>

Note language attribute which is used to specify language of the programlisting. The stylesheets will automatically pick corresponding highlighting rules according to a language used.

Installation

OK, it is not that easy, at least without some initial setup. You need a quite recent version of the DocBook stylesheets, you must have highlighting library on your classpath and you must specify location of highlighting configuration.

Procedure 1. Installing highlighting prerequisites

  1. Download the stylesheets release 1.71 or newer. Until 1.71 is out, you can download snapshot build from http://docbook.sourceforge.net/snapshots/.

    Unpack the stylesheets somewhere, I will assume location c:\docbook-xsl in the following steps.

  2. Download core of XSLTHL library (xslthl.jar) from http://prdownloads.sourceforge.net/xslthl/xslthl.jar?download and save it somewhere.

  3. Modify script used to invoke Saxon[1] to include xslthl.jar on classpath and also to point to configuration of highlighting (using xslthl.config Java property):

    java -cp …;c:\path\to\xslthl.jar -Dxslthl.config=file:///c:/docbook-xsl/highlighting/xslthl-config.xml … com.icl.saxon.StyleSheet …

After this setup you can turn on highlighting by using highlight.source parameter.

Styling your code

XSLTHL analyzes source code and assigns different categories like comment, keyword or string to particular pieces of text. Those categories are captured by elements from namespace http://xslthl.sf.net and are further processed. You can create your own templates to specify different styling of various syntax constructs. For example to show keywords in bold green you can use the following customization layer.

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:xslthl="http://xslthl.sf.net"
                exclude-result-prefixes="xslthl"
                version="1.0">

<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>

<xsl:param name="highlight.source" select="1"/>

<xsl:template match='xslthl:keyword'>
  <b class="color: green"><xsl:apply-templates/></b>
</xsl:template>

</xsl:stylesheet>

You can study default handling of highlighting categories in stylesheets fo/highlight.xsl and html/highlight.xsl in the DocBook XSL stylesheets distribution.

Adding support for a new language

Currently XSLTHL supports highlighting of XML, Java, PHP, Delphi, Modula-2 sources and INI files. List of supported syntaxes is defined in highlighting/xslthl-config.xml configuration file. Each supported syntax has its own identifier which is mapped to a file with highlighter definition. For example the following line in the configuration file defines that Java syntax highlighting is defined in the file java-hl.xml.

<highlighter id='java'   file='./java-hl.xml'  />

Of course, you can create your own highlighting definition files and register them in the configuration file. You can study definitions of existing highlighters to see how to define your own.

Choosing the right highlighter

Usually you will specify highlighter to use by using language attribute on programlisting. The stylesheets will try to use highlighter with the same name as a content of this attribute.

If there is no language attribute on your programlisting, the stylesheets will use highlighter specified by highlight.default.language parameter (which is blank by default).

All this logic is present in language.to.xslthl template which should return a name of highlighter to use. You can override this template to do various magic things. For example, the following template will try to guess which highlighter to use based on the content of programlisting. When language is not set explicitly decision is made between XML and PHP.

<xsl:template name="language.to.xslthl">
  <xsl:param name="context"/>

  <!-- Expand content (to handle e.g. <textdata fileref="..."/>) -->
  <xsl:variable name="content">
    <xsl:apply-templates select="$context/node()"/>
  </xsl:variable>

  <xsl:choose>
    <xsl:when test="$context/@language != ''">
      <xsl:value-of select="$context/@language"/>
    </xsl:when>
    <!-- Files containing <?php are considered as PHP scripts -->
    <xsl:when test="contains($content, '&lt;?php')">php</xsl:when>
    <!-- Files containing </ are considered to be XML files -->
    <xsl:when test="contains($content, '&lt;/')">xml</xsl:when>
  </xsl:choose>
</xsl:template>

Summary and future directions

The new syntax highlighting feature of the DocBook stylesheets is very useful, easy to use, works for both HTML and FO outputs and can be customized in a few minutes. This is mainly thanks to XSLTHL library created by Michal Molhanec.

The list of supported languages is quite small for now. If you create configuration file for your favorite language, please send it to me, so it can be included into a future releases.

The only problem of the current solution is that it ignores markup inside highlighted source code—if you have some additional markup in your programlisting (like callouts) it will be lost during highlighting. This limitation could be solved in the future versions of XSLTHL.

If you have any questions regarding highlighting of DocBook files please direct them to .



[1] XSLTHL library currently supports only Saxon 6.5.x.

blog comments powered by Disqus
Copyright © Jiří Kosek, 2006–2014