Support Saxon version 9 [sf#94]

[tomschr]

Reported by tom_schr on 2012-08-13 12:53 UTC

Background

Currently, DAPS contains hard-coded xsltproc calls which is fine in most cases. However, it would be nice to support a different XSLT processor like Saxon6. As XSLT2 can be an option as well, we should consider Saxon9 as well.

This has some benefits:

• Saxon is more strict than xsltproc. That means, our stylesheets can be developed in a more safer way. That exposes problems, warnings, or errors earlier.
• With Saxon we can use the DocBook extension JAR
• It's more flexible :)

Wrapper Script

To distinguish, which XSLT processor is used actually, we should write a wrapper script which delegates the call to the corresponding program. The DAPS configuration file can hold a variable which uses the default XSLT processor.

An example of wrapper scripts can be found in the DocBook SVN (buildtools). The different XSLT processors are needed to build the DocBook schema and stylesheets.

Syntax of Different XSLT Processors

The syntax of each XSLT processor is shown in the following table:

XSLT Processor	Syntax
xsltproc	xsltproc [options] stylesheet file [file ...]
Saxon 6	saxon [options] source-doc style-doc {param=value}
Saxon 9	saxon9 [-xi] -s:XMLFILE -xsl:stylesheet -o:OUTPUT
	Order doesn't matter

Comparison

The following table contains a comparison of available options which are equivalent in xsltproc and Saxon:

xsltproc	Saxon 6	Saxon 9
-o / --output	-o	-o
--xinclude	Use Xerces XNI Parser	-xi
--stringparam PARAM=VALUE	param=value	param=value
--nonet	n/a	n/a
--novalid	n/a	-dtd:off

XML Catalogs and Saxon

The Java XML parser needs a CatalogManager.properties file to set some options. The original file is stored in /etc/java/resolver/CatalogManager.properties.

To use this file, the CLASSPATH needs to include the directory where this file is stored.

For debugging purposes, you can use the org.apache.xml.resolver.apps.resolver class. It is similar to the xmlcatalog tool: you pass a catalog name, the things you want to resolve and the program returns the resolved path.

$ CP=$(build-classpath xml-commons-resolver)
$ java -cp $CP -Dxml.catalog.ignoreMissing=yes org.apache.xml.resolver.apps.resolver -h
Usage: resolver [options] keyword

Where:

-c catalogfile  Loads a particular catalog file.
-n name         Sets the name.
-p publicId     Sets the public identifier.
-s systemId     Sets the system identifier.
-a              Makes the system URI absolute before resolution
-u uri          Sets the URI.
-d integer      Set the debug level.
keyword         Identifies the type of resolution to perform:
                doctype, document, entity, notation, public, system,
                or uri.

Resolving the URI http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl gives you the following output:

java -cp $CP -Dxml.catalog.ignoreMissing=yes org.apache.xml.resolver.apps.resolver -c /etc/xml/catalog -s "http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" system
Resolve SYSTEM (systemid):
  system id: http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl
Result: file:/usr/share/xml/docbook/stylesheet/nwalsh/1.77.1_svn9608/xhtml/docbook.xsl

Saxon 6 Additions

Recommended addition for Saxon 6:

# Used to enable XIncludes
XINCLUDEFLAG="-Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration"
# Used to enable XML Catalog configuration
CATALOGPROP="CatalogManager.properties"
# The DocBook JAR file for extension functions
SAXON_JAR="${DBXSLT}/extensions/saxon65.jar"
# We need additional JAR files (mostly due to XInclude resolution)
export ADDITIONAL_JARS="xerces-j2.jar xerces-j2-xml-apis.jar"
# Use special options to switch XML parser to Xerces:
export ADDITIONAL_FLAGS="-Djavax.xml.parsers.DocumentBuilderFactory=\
org.apache.xerces.jaxp.DocumentBuilderFactoryImpl \
    -Djavax.xml.parsers.SAXParserFactory=\
org.apache.xerces.jaxp.SAXParserFactoryImpl ${XINCLUDEFLAG}"
# Extend CLASSPATH variable
export CLASSPATH="${CATALOGPROP}:${SAXON_JAR}"

# Run original saxon script:
saxon $@

Some Useful Links

• https://sourceforge.net/apps/mediawiki/saxon/index.php?title=XML_Catalogs
• http://www.sagehill.net/docbookxsl/UseCatalog.html
• http://xerces.apache.org/xml-commons/components/resolver/resolver-article.html

[tomschr]

*Commented by anonymous on 2012-11-08 10:32 Additional note: naming change from openSUSE 12.1 to 12.2: version 6.5 of Saxon will be in package "saxon6" with the script "saxon6". Packages for Saxon 9 won't change.

That needs taken into account for a wrapper script.

[tomschr]

Updated by fsundermeyer on 2012-11-30 20:20

• summary: Support Saxon version 6 and 9 --> Support Saxon version 9
• assigned_to: Thomas Schraitle --> Frank Sundermeyer
• info_provider: Frank Sundermeyer --> nobody
• milestone: 2.0 --> Future

[tomschr]

Commented by fsundermeyer on 2012-11-30 20:20 saxon6 is now fully supported (SVN commit 2309).

saxon9 support is not required until we have XSLT 2.0 stylesheets, therefore adjusting Ticket title and postponing it to "Future".

[fsundermeyer]

Su perseeded by #702