ONIX for Books 3.0 tagname converter

The ONIX tagname converters switch-onix-3.0-tagnames-1.1.xsl and switch-onix-3.0-tagnames-2.0.xsl are XSLT scripts that replace reference tagnames with short tagnames and vice versa. They work for all ONIX files that are valid according to either the reference tag or short tag versions of the ONIX 3.0 DTD or XSD, available from the EDItEUR website.

These two scripts are functionally equivalent, but use different versions of the XSLT scripting language to achieve the same results.

WARNING It is essential that the correct script is used! Please check which XSLT engine you are going to use and which version of XSLT that this engine uses before installing the correct version of the ONIX tagname converter.

Care should also be taken to use the correct tagname converter for a given ONIX release. Separate tagname converters are available for conversion of ONIX files that conform to ONIX Release 2.1: these can be obtained from the ‘Previous Releases’ page in the 'ONIX for Books' section of the EDItEUR website.

Preparation and installation

You must first decide which of the two versions of the ONIX tagname converter script you need to use. This will depend upon which version of XSLT is supported by your chosen XSLT engine.

To run the script it is necessary first to choose and install an XSLT ‘engine’. Suitable engines include Saxon and Xalan. Saxon is obtainable from http://saxon.sourceforge.net/. Xalan is obtainable from http://xml.apache.org/. Various versions are available – if in doubt, choose an engine that is described as ‘stable’, such as Saxon version 6.5.5, Saxon-B version or Saxon version 9.2 HE (later stable versions may be available).

For relatively 'old' XSLT engines, the script switch-onix-3.0-tagnames-1.1_v1.3.xsl relies upon some Saxon XSLT 1.1 extensions. There is a stand-alone executable version of Saxon for pre-XP versions of Microsoft Windows, called Instant Saxon, but this requires the Microsoft Java Virtual Machine, which is no longer available for Windows XP. The best solution is to install the Sun Java 2 Virtual Machine (available from http://java.sun.com/) and run the version of Saxon (preferably version 6.5.5) or Xalan that is available for the Java 2 platform.

For 'relatively' modern XSLT engines, the alternative version of the script, switch-onix-3.0-tagnames-2.0_v1.3.xsl, relies upon some XSLT 2.0 functionality, and this can be used with Saxon version 8.7.1 or later.

The script will only work if the ONIX file that is to be converted is DTD or XSD VALID, ie a) it either contains a DTD declaration that links to a copy of the ONIX DTD stored locally on your PC or server, or it has been normalised to include all fixed attributes explicitly by pre-processing by a suitable XML parser, and in addition, it doesn’t contain any tag errors; or b) it contains an XML namespace declaration and xsi:schemaLocation attribute that links to a copy of the ONIX XSD stored locally on your PC or server, and in addition it doesn't contain any tag errors.

Note that it is not currently possible to convert ONIX files that link to the ONIX 3.0 RNG Schema and there are no current plans to make this possible.

Download the relevant XSLT script here (latest v1.3 versions):

The script should be placed in a convenient directory/folder.

Running the script

The method of running the script is the same in each case, and involves the use of at least one parameter. The parameter result-document must always be included, and this specifies the file to which the output is written. The parameter dtd-path is optional, and is used to specify the system path to be specified in a DTD declaration in the output file; if omitted, the transformation will proceed using the XSD file specified in the xsi:schemaLocation attribute in the original ONIX file and no DTD declaration will be included in the output file.

If run from the command line, a typical invocation using Saxon 6.5.5 to convert from short to reference tags and include a DTD declaration would be:

java -jar {path-to-saxon-6.6.5} original-onix-file.xml switch-onix-3.0-tag-names-1.1_v1.3.xsl input-path="%CD%" result-document="converted-onix-file" [dtd-path="ONIX_BookProduct_3.0_xxxxx.dtd"]

Similarly, a typical invocation using Saxon 9.x to convert from reference to short tags and include a DTD declaration would be:

java -jar {path-to-saxon-9.x} original-onix-file.xml switch-onix-3.0-tag-names-2.0_v1.3.xsl input-path="%CD%" result-document="converted-onix-file" [dtd-path="ONIX_BookProduct_3.0_reference.dtd"]

Note that compared with earlier versions of the converter scripts, there is an extra required parameter input-path, which has to be fed the path to the current folder containing original-onix.xml. This is required to enable the XSLT engine to work out the absolute path to the XSD schema, because the schema location URI in the ONIX file may be a relative reference.

Either XSLT script can also be used within an XML editing tool such as oXygen.

The XSLT tagname converters are provided ‘as is’ and are not warranted in any way by EDItEUR. EDItEUR provides no technical support for these tools other than this document. EDItEUR disclaims all responsibility for any errors and for all consequential inconvenience or cost associated with their use. Bug reports and other enquiries may be sent to EDItEUR (info@editeur.org) or to the original author Francis Cave (francis@franciscave.com).