Spreading the XML paradigm around
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
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.
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
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.
Download core of XSLTHL library
(xslthl.jar) from http://prdownloads.sourceforge.net/xslthl/xslthl.jar?download and save it somewhere.
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.
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.
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.
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, '<?php')">php</xsl:when> <!-- Files containing </ are considered to be XML files --> <xsl:when test="contains($content, '</')">xml</xsl:when> </xsl:choose> </xsl:template>
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
<docbook-apps@lists.oasis-open.org>.