Menu ▾ ▴

Usage

Michiel Hendriks

Using xslthl

xslthl provides an XSLT extension function called highlight which performs syntax highlighting on all text nodes that are passed on as argument. All non-text nodes are included in the resulting node set.

The highlight function has the following signature:

highlight(languageId, nodeSet[, configFile])
  • The languageId is a string that tells what syntax highlighter to use. It has to be registered in the configuration file. Alternatively to an language id which is registered in the used configuration file you can also use define a location to a syntax highlighter configuration. This location can be an url or a location on the file system. Note that if a relative file location is used it will be based on the current directory. It is not relative to the file which is being processed. Support for loading external configurations can be disabled using the xslthl.noexternal system property.
  • The nodeSet argument is the set of nodes on which highlighting should be perform. Only text nodes are highlighted.
  • The optional configFile argument is a string with the location (url) to the configuration file to use. The configuration file tells what syntax highlighters to load. If this argument is omitted the configuration filename is read from the Java system property xslthl.config, if that property is not set it will try to load the file called xslthl-config.xml from the current directory. More information about the configuration file can be found in the xslthl configuration page.

The example directory in the source repository contains an example on how to use this function. Specially inspect the XSLT stylesheet that is used for these example. It contains quite some tricks.

For each of the listed XSLT processors there is a short notation and a compatibility notation. The compatibility notation make sure that the extension does not obstruct with other XSLT processors.

Saxon 6.5

Short notation

To use xslthl with Saxon 6.5 you need to declare include the following xml-namespace declaration:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:s6hl="java:net.sf.xslthl.ConnectorSaxon6"
    xmlns:xslthl="http://xslthl.sf.net"
    extension-element-prefixes="s6hl xslthl"
>

This will register the namespace s6hl which will contain the highlight function. The xslthl namespace is used for the results produced by xslthl.

You can now use the function using the prefix: s6hl:highlight('java', ., '<file:~ myconfig.xml="">')'

Compatibility notation

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:s6hl="http://net.sf.xslthl/ConnectorSaxon6"
    xmlns:saxon6="http://icl.com/saxon"
    xmlns:xslthl="http://xslthl.sf.net"
    extension-element-prefixes="s6hl xslthl"
>
    <saxon6:script implements-prefix="s6hl" language="java"
        src="java:net.sf.xslthl.ConnectorSaxon6" />

This has the same end result, except that that the stylesheet can also be used by Saxon 8.5+ or Xalan without throwing any errors. The uri in xmlns:s6hl is there just to register the namespace in the first place. The content is ignored by XSLT processors.

Saxon 8.5+

These notation appply to Saxon version's 8.5 and later (tested with SaxonB 9.1). They do not work with the recent Saxon PE and EE versions.

Short notation

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:sbhl="java:net.sf.xslthl.ConnectorSaxonB"
    xmlns:xslthl="http://xslthl.sf.net"
    extension-element-prefixes="sbhl xslthl"
>

The connector class is called net.sf.xslthl.ConnectorSaxonB.

Compatibility notation

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:sbhl="http://net.sf.xslthl/ConnectorSaxonB"
    xmlns:saxonb="http://net.sf.saxon/"
    xmlns:xslthl="http://xslthl.sf.net"
    extension-element-prefixes="sbhl xslthl"
>
    <saxonb:script implements-prefix="sbhl" language="java"
        src="java:net.sf.xslthl.ConnectorSaxonB" />

Note the difference in the saxonb namespace declared here and the saxon6 namespace that was previously used.

Saxon 9.4+

These notation apply to Saxon PE/EE versions 9.4 and later (tested with SaxonB 9.5 and 9.6).

Short notation

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:seehl="java:net.sf.xslthl.ConnectorSaxonEE"
    xmlns:xslthl="http://xslthl.sf.net"
    extension-element-prefixes="seehl xslthl"
>

The connector class is called net.sf.xslthl.ConnectorSaxonEE.

Xalan 2.7

Short notation

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xhl="xalan://net.sf.xslthl/XalanConnector"
    xmlns:xslthl="http://xslthl.sf.net"
    extension-element-prefixes="xhl xslthl"
>

This is just like the Saxon method. And makes the highlighting function available as: xhl:highlight(...)

Compatibility notation

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xhl="http://net.sf.xslthl/XalanConnector"
    xmlns:xalan="http://xml.apache.org/xalan"
    xmlns:xslthl="http://xslthl.sf.net"
    extension-element-prefixes="xhl xslthl"
>

    <xalan:component prefix="xhl" functions="highlight">
        <xalan:script lang="javaclass" src="xalan://net.sf.xslthl.XalanConnector" />
    </xalan:component>

XSLT processor safe usage

The following declaration is safe to be used in any stylesheet that needs to be used with either saxon, xalan, or some other processor.

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:s6hl="http://net.sf.xslthl/ConnectorSaxon6"
    xmlns:sbhl="http://net.sf.xslthl/ConnectorSaxonB"
    xmlns:xhl="http://net.sf.xslthl/ConnectorXalan"

    xmlns:saxon6="http://icl.com/saxon"
    xmlns:saxonb="http://saxon.sf.net/"
    xmlns:xalan="http://xml.apache.org/xalan"

    xmlns:xslthl="http://xslthl.sf.net"

    extension-element-prefixes="s6hl sbhl xhl xslthl"
>

    <!-- for Xalan 2.7 -->
    <xalan:component prefix="xhl" functions="highlight">
        <xalan:script lang="javaclass" src="xalan://net.sf.xslthl.ConnectorXalan" />
    </xalan:component>

    <!-- for saxon 6 -->
    <saxon6:script implements-prefix="s6hl" language="java"
        src="java:net.sf.xslthl.ConnectorSaxon6" />

    <!-- for saxon 8.5 and later -->
    <saxonb:script implements-prefix="sbhl" language="java"
        src="java:net.sf.xslthl.ConnectorSaxonB" />

With this declaration the function s6hl:highlight(...) exists when the stylesheet is loaded by Saxon 6.5. When it's used by Xalan the function xhl:highlight(...) exists. And with Saxon 8.5 and later the function sbhl:highlight(...) is available.

The following XSLT template uses the highlighting functionality is an XSLT processor safe way:

    <xsl:template name="syntax-highlight">
        <xsl:param name="language" />
        <xsl:param name="source" />
        <xsl:param name="config"></xsl:param>
        <xsl:choose>
            <xsl:when test="function-available('s6hl:highlight')">
                <xsl:variable name="highlighted" select="s6hl:highlight($language, $source, $config)" />
                <xsl:apply-templates select="$highlighted" />
            </xsl:when>
            <xsl:when test="function-available('sbhl:highlight')">
                <xsl:variable name="highlighted" select="sbhl:highlight($language, $source, $config)" />
                <xsl:apply-templates select="$highlighted" />
            </xsl:when>
            <xsl:when test="function-available('xhl:highlight')">
                <xsl:variable name="highlighted" select="xhl:highlight($language, $source, $config)" />
                <xsl:apply-templates select="$highlighted" />
            </xsl:when>
            <xsl:otherwise>
                <xsl:apply-templates select="$source/*|$source/text()" />
            </xsl:otherwise>
        </xsl:choose>
    </xsl:template>

This template expects to be called with the source parameter set to the parent node who's content should be highlighted. For example if the source document contains the following:

<code language="java">
/*
    this is some java code that should be highlighted
*/
</code>

The template should be called like:

<xsl:template match="code">
    <xsl:call-template name="syntax-highlight">
        <xsl:with-param name="language" select="@language" />
        <xsl:with-param name="source" select="." />
    </xsl:call-template>
</xsl:template>

The syntax-highlight template calls xsl:apply-template so that the nested xml elements in the context node are processed even more.

More information about processing the xslthl results see processing xslthl results.

Related

Wiki: Home
Wiki: Overview
Wiki: Processing xslthl results
Wiki: Xslthl Configuration