Using xmlcatalog


This article provides several example command lines as a quick reference for xmlcatalog.

Table of Contents

Creating a New Catalog
Adding URI Resolution Entries to a Catalog
Testing Catalog Resolution
Not Everything

I was browsing through the man page and --help for xmlcatalog when I realized that I always struggle with intuitively understanding the options for this simple but useful utility. For your benefit, dear reader (an entity which as often as not resolves to me), I wanted to provide some everyday examples of using xmlcatalog that can be referenced, recipe-style, when manipulating an XML Catalog.

So what is xmlcatalog? It is a utility, distributed as part of libxml2 , for managing the entries in an XML Catalog. Well, what is an XML Catalog? The XML Catalog language describes how particular URIs should be resolved. It's pretty cool, is what it is. It's pretty handy to be able to give something a global name (for example, a style sheet for a web page that you want to share with others) and be able to resolve it locally even when you are offline (or if you simply do not want to hammer your server). XML Catalogs are commonly used to resolve the venerable DocBook XSL suite (which can, of course, be used by retrieving the individual XSL files from the network at runtime) to its local installation location. My favorite XML front-end, the XMLmind XML Editor, supports XML Catalogs for resolving URIs in many cases.


Of course, XML Catalogs are pointless without two things. First, your software needs to actually use your XML Catalogs to resolve identifiers. Second, you need to tell such software where to find appropriate XML Catalogs.

The first trick is to realize that xmlcatalog will only save to a file when you use --noout. Otherwise it will output the results of its manipulations to stdout, which of course can be redirected to a file. Not using --noout can be useful for double checking your catalog changes before saving them. In order to be direct I will generally use --noout in these examples.

As with many XML languages, the initialization syntax (including such components as XML namespaces) can be a bit hairy. Templates or a syntax-aware tool can help a user get started. xmlcatalog will generate a bare-bones XML Catalog with no entries for you to develop further:

$ xmlcatalog --noout --create filename-of-catalog.xml

XML Catalogs can be used to resolve XML Public and System identifiers as well as URIs. In day-to-day use of XML Catalogs, I find myself most interested in specifying resolution for URIs, so I will concentrate on that activity here.

First, xmlcatalog can be used to directly resolve a single URI. For example, to resolve to the locally cached copy found at file:///home/user/cache/xml/XML-catalogs-2001-08-06.html, you could use the following command:

$ xmlcatalog --noout --add uri \
    '' \
    'file:///home/john/cache/xml/XML-catalogs-2001-08-06.html' \

Next, xmlcatalog can be used to translate a URI prefix, which is useful for resolving any URIs that start with that prefix to a common base location. For example, to resolve any URI that begins with by substituting that URI prefix with file:///usr/share/xml/docbook-xsl-current/, you could use the following command:

$ xmlcatalog --noout --add rewriteURI \
    '' \
    'file:///usr/share/xml/docbook-xsl-current/' \

Generally, the xmlcatalog man page talks about adding 'type' 'orig' 'replace' to a catalog. First, 'type' can be any of the XML Catalog resolution types. This is one of "public", "system", "rewriteSystem", "delegatePublic", "delegateSystem", "uri", "rewriteURI", or "delegateURI". Next, 'orig' is the URI, prefix, or other identifier that you want to resolve. Finally, 'replace' is the desired resolution location (or delegation) for the first value.

xmlcatalog can also test the resolution of a given URI against the rules in an XML Catalog. To query an XML Catalog, you could use a command like the third one in the sequence below, giving xmlcatalog the filename of the XML Catalog and the URI to resolve:

$ xmlcatalog --noout --create catalog.xml
$ xmlcatalog --noout --add rewriteURI \
    '' \
    'file:///home/john/' \
$ xmlcatalog catalog.xml ''
No entry for SYSTEM

xmlcatalog tells us that there is no SYSTEM identifier entry that matches our input, but there is a resolution for that input as a general URI, and it resolves the URI correctly to the file URL.

It is important to note that xmlcatalog cannot edit everything that can be put in an XML Catalog. For more complex XML Catalog setups - including such features as grouping, xml:base management, and rule reordering - a more general XML Catalog editor or even an XML editor should be used.