xmlcanon

Usage

xmlcanon --validate foo.xml

Contents

Description

xmlcanon is a command-line utility for transforming XML files into canonical form. It is produced and maintained by ElCel Technology.

For each URL, xmlcanon transforms the contents into canonical form using either the algorithm recommended and published by the W3C Canonical XML Version 1.0 or James Clark's original canonical xml algorithm.

By default, the canonical results are written to the standard output. The --out option may be used to redirect the output to a file of your choice.

The canonical form of an xml document is a normalization of the input file together with any information required from the DTD, such as attribute defaults and entities. For this reason xmlcanon can be used to transform xml documents containing DTDs into standalone documents without DTDs. (The James Clark algorithm does use a limited DTD in some circumstances, but this DTD is comprised of only an internal subset).

Each filename passed on the command line is treated as a Uniform Resource Locator (URL). If no protocol is present in the URL, it is assumed to refer to a local file. For example 'c:\test.xml' is treated as being equivalent to the URL 'file:///c:\test.xml'. To read from the standard input specify a URL of '-'.

xmlcanon can be configured to route HTTP network requests via a proxy server. See Network Access Options for further details.

On Microsoft Windows platforms, to compensate for the lack of shell file name expansion, xmlcanon automatically expands file names containing wild-card characters ('*' and '?') into a list of matching files. This expansion only occurs when the URL(s) look like file names, i.e. they do not contain a protocol such as "file:". Beware that even though xmlcanon will happily process multiple input files, the results will be concatenated into a single (badly formed) output file.

Messages produced by xmlcanon can be translated into your native language. This is described in the section titled Native Language Support.

General Options

Single character option names may be concatenated together. POSIX-style option names (those beginning with --) must be specified separately, but may be abbreviated.

Network Access Options

xmlcanon uses the capabilities of the ElCel Technology library to access files from the Internet. In some organizations access to the Internet is provided via a proxy server, sometimes requiring authentication.

The following options can be used to control how xmlcanon accesses network resources.

XML Catalog Options

The DTD and other external entities referenced within the input file(s) can be resolved using an XML Catalog. This is further described in the section titled Entity Resolution.

Return Code

0 - Success, 1 - Failure

Entity Resolution

xmlcanon can use a XML catalog to look up and resolve public and system identifiers. This important feature is present in SGML systems but was originally absent from most XML tools. The XML catalog file is specified with the --catalog option, the ET_XMLCAT_CATALOG environment variable or the <?oasis-xml-catalog?> processing instruction imbedded in the prolog (before the DOCTYPE declaration) of your XML document.

The format and semantics of the XML catalog entries follow the OASIS XML Catalog specification.

Control over whether public or system identifiers are preferred is provided by means of the --prefer option or the ET_XMLCAT_PREFER environment variable.

The OASIS XML Catalog specification. describes a powerful set of features which cannot adequately be described here. However a brief example of a valid catalog entry file is shown below:-

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
 <public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
         uri="docbookx.dtd"/>
 <system systemId="docbookx.dtd" uri="docbookx.dtd"/>
 <delegateSystem systemIdStartString="doc" 
                 catalog="http://www.acme.org/DocBook/catalog"/>
 <delegatePublic publicIdStartString="-//OASIS" 
                 catalog="file:///usr/doc/oasis/catalog.xml"/>
</catalog>

If no catalog is specified (either using the --catalog option, the ET_XMLCAT_CATALOG environment variable or the <?oasis-xml-catalog?> processing instruction) or a catalog match fails to occur, then xmlcanon will read external entities by dereferencing the system identifiers. The <?oasis-xml-catalog?> processing instruction can be disabled by specifying the --nocatalogpis option.

Native Language Support

By default, xmlcanon produces error messages in the English language but these can be replaced with messages written in a native language of your choice.

The ElCel Technology Native Language Authoring Kit contains message catalogs translated into other languages. You may be lucky and find that messages for your native language have already been translated. More likely, if you wish to use native language messages you will need to undertake the translation work yourself. The Kit contains pro-forma message catalogs written in English which form the basis for the native language versions. It is not necessary to translate all messages for the exercise to be useful, translating just the common messages is feasible.

Once you have the necessary message catalogs, it is quite straight forward to configure xmlcanon to use them. This is achieved by setting two environment variables: LANG and ET_MSG_DIR.

When searching for message catalogs, xmlcanon concatenates the environment variables like this: $ET_MSG_DIR/elcel/$LANG/. Within the message directory, the message catalog files have a suffix of .msg and are named in accordance with the library or application to which they refer.

For example, if ET_MSG_DIR=/usr/share and LANG=fr_FR the message catalog file containing XML validation messages (in the French language) would be /usr/share/elcel/fr_FR/xml.msg. These messages may be shared by other tools built with . The catalog file containing messages specific to xmlcanon would be named /usr/share/elcel/fr_FR/xmlcanon.msg.

Feedback

We welcome feedback about our products. If you have a bug report, a suggested enhancement or simply enjoy using xmlcanon please let us know. support@elcel.com.

xmlcanon version 1.2, March 2003