3.2. The XML Catalog Hierarchy

This section defines some basic terminology and describes the Debian hierarchical XML Catalog implementation.

The Debian system uses three distinct catalog file types:

Root Catalog

/etc/xml/catalog

Package Catalogs

/etc/xml/package.xml

Local Catalogs

/usr/share/xml/.../package-dir/.../catalog.xml

The root catalog only knows about packages and their Package Catalogs. It knows nothing whatsoever about files, directories and such. It delegates all lookups to the appropriate Package Catalog, but never to any of the Local Catalogs.

A package catalog has knowledge about directories and their catalogs but doesn't know about the files in those directories. A package catalog delegates all lookups to the appropriate local catalog(s), which are located in the package installation directories.

The local catalogs are the only catalogs that know about files in package installation directories. They resolve lookups directly to the appropriate file(s) in the package installation directories.

3.2.1. The Root Catalog: /etc/xml/catalog

The root catalog is, by default, the first catalog entry file parsed while performing a lookup.

The primary role of the root catalog is to delegate entity searches to the appropriate package catalog (/etc/xml/package.xml). As such, it should only contain delegate elements:

  • delegatePublic

  • delegateSystem

  • delegateURI

Example 3.1. Root Catalog Fragment

The following is a fictitious sample fragment of a root catalog entry file /etc/xml/catalog with entries for the XML Catalog DTD, various DocBook DTDs, and the DocBook XSL stylesheets.

<?xml version="1.0"?> 
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD XML Catalogs V1.0//EN"
          "file:///usr/share/xml/schema/xml-core/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> 

<!-- ===== BEGIN xml-core entries ===== --> 

  <delegatePublic 
     publicIdStartString="-//OASIS//DTD XML Catalogs"
     catalog="xml-core.xml"/> 
  <delegateSystem
     systemIdStartString="http://www.oasis-open.org/committees/entity/" 
     catalog="xml-core.xml"/> 

<!-- ===== END xml-core entries ===== --> 

<!-- ===== BEGIN docbook-xml entries ===== -->

<!--  docbook-xml V4.x  --> 
  <delegatePublic 
     publicIdStartString="-//OASIS//DTD DocBook XML"
     catalog="docbook-xml.xml"/> 

  <delegateSystem 
     systemIdStartString="http://www.oasis-open.org/docbook/xml/4" 
     catalog="docbook-xml.xml"/> 

<!-- docbook-xml V3.x  -->
  <delegatePublic 
     publicIdStartString="-//Norman Walsh//DTD DocBk XML V3"
     catalog="docbook-xml.cat"/> 

  <delegateSystem 
     systemIdStartString="http://www.nwalsh.com/docbook/xml/3"
     catalog="docbook-xml.xml"/> 

<!-- ===== END docbook-xml entries ===== --> 

<!-- ===== BEGIN docbook-xsl entries ===== --> 

  <delegateURI 
     uriStartString="http://docbook.sourceforge.net/release/xsl/"
     catalog="docbook-xsl.xml"/> 

  <delegateURI 
     uriStartString="http://docbook.sf.net/release/xsl/"
     catalog="docbook-xsl.xml"/> 

<!-- ===== END docbook-xsl entries ===== -->

</catalog>

3.2.2. Package Catalogs: /etc/xml/package.xml

The primary role of the package catalogs is

  1. to delegate entity searches to the appropriate local catalogs, (/usr/share/xml/.../package-dir/.../catalog.xml), based on Formal Public Identifier (FPI), System Identifier (SYSID), or URI fragments.

As such, package catalogs, too, should only contain delegate elements:

  • delegatePublic

  • delegateSystem

  • delegateURI

Example 3.2. Package Catalog: xml-core

The following is a sample package catalog entry file, /etc/xml/xml-core.xml, for the xml-core package. It is used to locate the OASIS XML Catalog DTD.

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD XML Catalogs V1.0//EN" 
      "file:///usr/share/xml/schema/xml-core/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

  <delegatePublic 
    publicIdStartString="-//OASIS//DTD XML Catalogs V1.0//EN" 
    catalog="file:///usr/share/xml/schema/xml-core/catalog.xml"/>

  <delegateSystem 
    systemIdStartString="http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd" 
    catalog="file:///usr/share/xml/schema/xml-core/catalog.xml"/>

</catalog>

Example 3.3. Package Catalog: docbook-xml

The following is a fictitious sample package catalog entry file for the docbook-xml package. It is used to locate various versions of the DocBook DTD. The real version is too complex for the purposes of demonstration.

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD XML Catalogs V1.0//EN" 
  "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd";>        

<!-- ==== package catalog for docbook-xml ==== -->
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <!-- docbook-xml V4.x  -->

  <!-- This works because the LONGEST match wins -->
  <!-- 'ls -l /usr/share/sgml/docbook/dtd/xml/' will clarify this catalog -->

  <!-- For versions 4, 4.1, and 4.1.2 --> 
  <delegatePublic publicIdStartString="-//OASIS//DTD DocBook XML V4"
    catalog="file:///usr/share/xml/docbook/dtd/4.1.2/catalog.xml"/>

  <delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4" 
    catalog="file:///usr/share/xml/docbook/dtd/4.1.2/catalog.xml"/>

  <!-- For version 4.0 only --> 
  <delegatePublic publicIdStartString="-//OASIS//DTD DocBook XML V4.0"
    catalog="file:///usr/share/xml/docbook/dtd/4.0/catalog.xml"/>

  <delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4.0" 
    catalog="file:///usr/share/xml/docbook/dtd/4.0/catalog.xml"/>

  <!-- For version 4.2 only --> 
  <delegatePublic publicIdStartString="-//OASIS//DTD DocBook XML V4.2/"
    catalog="file:///usr/share/xml/docbook/dtd/4.2/catalog.xml"/>

  <delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4.2/"; 
    catalog="file:///usr/share/xml/docbook/dtd/4.2/catalog.xml"/>

  <!-- docbook-xml V3.x  -->  
  <delegatePublic publicIdStartString="-//Norman Walsh//DTD DocBk XML V3"
    catalog="file:///usr/share/xml/docbook/dtd/3.1.7/catalog.xml"/>

  <delegatePublic publicIdStartString="-//Norman Walsh//DTD DocBook XML V3"
    catalog="file:///usr/share/xml/docbook/dtd/3.1.7/catalog.xml"/>

  <delegateSystem systemIdStartString="http://www.nwalsh.com/docbook/xml/3"
    catalog="file:///usr/share/xml/docbook/dtd/3.1.7/catalog.xml"/>

</catalog>

Example 3.4. Package Catalog: docbook-xsl

The following is a sample package catalog entry file for the docbook-xsl package. It is used to locate various files within the DocBook XSL stylesheet distribution.

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD XML Catalogs V1.0//EN" 
  "file:///usr/share/xml/schema/xml-core/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

  <delegateURI
    uriStartString="http://docbook.sourceforge.net/release/xsl/"
    catalog="file:///usr/share/xml/docbook/stylesheet/nwalsh/catalog.xml"/>

</catalog>

3.2.3. Local Catalogs: /usr/share/xml/.../package-dir/.../catalog.xml

The primary roles of the local catalogs are

  1. to map External Identifiers[2] and URIs to local filenames, and,

  2. to rewrite URI prefixes so that, say, web-based URLs are mapped to local filenames.

As such, local catalogs should only contain the following elements:

  • public

  • system

  • uri

  • rewriteURI

The rewriteURI element is intended for use in catalogs for stylesheets and other resources that don't have External Identifiers. It shouldn't be used for DTDs or any other resource that has a valid system identifier.

Local Catalog File Names

All local XML catalog files should be named catalog.xml.

Upstream catalog files placed in these directories may need to be renamed catalog.xml. Catalog files created by the maintainer should always be named catalog.xml

Example 3.5. Local Catalog: xml-core

The following is a sample local catalog entry file for the xml-core package. It is used to resolve SYSTEM and PUBLIC identifiers that reference the OASIS XML Catalog DTD and an extended version (tr9401.dtd) that adds support for additional semantics supported by SGML (i.e. TR9401:1997) catalogs.

<?xml version="1.0"?>
<!DOCTYPE catalog SYSTEM catalog.dtd>    
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> 

  <public publicId="-//OASIS//DTD XML Catalogs V1.0//EN" uri="catalog.dtd"/>
   
  <system
    systemId="http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"
    uri="catalog.dtd"/>
 
  <!-- ====== Customization that adds tr9401 support ====== -->
 
  <public 
    publicId="-//Debian//DTD XML Catalogs V1.0-Based Extension V1.0/EN"
    uri="tr9401.dtd"/>
 
  <system 
    systemId="http://people.debian.org/~mrj/oasis/catalog/xml/tr9401.dtd"
    uri="tr9401.dtd"/>

</catalog>

Example 3.6. Local Catalog: DocBook XML, V4.2 DTD

Note that this is the catalog that ships with the DocBook DTD.

<?xml version='1.0'?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" 
    "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd";>

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

<!-- ...................................................................... -->
<!-- XML Catalog data for DocBook XML V4.2 ................................ -->
<!-- File catalog.xml ..................................................... -->

<!-- Please direct all questions, bug reports, or suggestions for
     changes to the docbook@lists.oasis-open.org mailing list. For more
     information, see http://www.oasis-open.org/.
  -->

<!-- This is the catalog data file for DocBook V4.2. It is provided as
     a convenience in building your own catalog files. You need not use
     the filenames listed here, and need not use the filename method of
     identifying storage objects at all.  See the documentation for
     detailed information on the files associated with the DocBook DTD.
     See XML Catalogs at http://www.oasis-open.org/committees/entity/ for
     detailed information on supplying and using catalog data.
  -->

<!-- ...................................................................... -->
<!-- DocBook driver file .................................................. -->

<public publicId="-//OASIS//DTD DocBook XML V4.2//EN"
        uri="docbookx.dtd"/>

<!-- ...................................................................... -->
<!-- DocBook modules ...................................................... -->

<public publicId="-//OASIS//DTD DocBook CALS Table Model V4.2//EN"
        uri="calstblx.dtd"/>

<public publicId="-//OASIS//DTD XML Exchange Table Model 19990315//EN"
        uri="soextblx.dtd"/>

<public publicId="-//OASIS//ELEMENTS DocBook Information Pool V4.2//EN"
        uri="dbpoolx.mod"/>

<public publicId="-//OASIS//ELEMENTS DocBook Document Hierarchy V4.2//EN"
        uri="dbhierx.mod"/>

<public publicId="-//OASIS//ENTITIES DocBook Additional General Entities V4.2//EN"
        uri="dbgenent.mod"/>

<public publicId="-//OASIS//ENTITIES DocBook Notations V4.2//EN"
        uri="dbnotnx.mod"/>

<public publicId="-//OASIS//ENTITIES DocBook Character Entities V4.2//EN"
        uri="dbcentx.mod"/>


<!-- End of catalog data for DocBook XML V4.2 ............................. -->
<!-- ...................................................................... -->

</catalog>

Example 3.7. Local Catalog: docbook-xsl

The following is a sample local catalog entry file /usr/share/xml/docbook/stylesheet/nwalsh/catalog.xml for the docbook-xsl package. It is used to locate various files within the DocBook XSL stylesheet distribution by rewriting the web-based URI fragments where the distribution is located to a directory on the local filesystem where the stylesheets are installed.

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD XML Catalogs V1.0//EN" 
  "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd";>    
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

<!-- ==== local catalog for docbook-xsl ==== -->

  <rewriteURI
    uriStartString="http://docbook.sourceforge.net/release/xsl/1.64.1/"
    rewritePrefix="file:///usr/share/xml/docbook/stylesheet/nwalsh/"/>

  <rewriteURI
    uriStartString="http://docbook.sourceforge.net/release/xsl/current/"
    rewritePrefix="file:///usr/share/xml/docbook/stylesheet/nwalsh/"/>

</catalog>


[2] Examples of External Identifiers are SYSTEM and PUBLIC identifiers, and are covered in the OASIS XML Catalogs specification. They are defined in Production 75 of the W3C XML specification. Note: a URL that points to a set of stylesheets is NOT an External Identifier, it is simply a URI. Practically speaking, the only structural difference between a system identifier (a SystemLiteral, to be precise) and a URI, is that a URI may have a fragment identifier appended to it, whereas a system identifier may not. A fragment identifier is distinguished by the '#' symbol: http://www.example.org/doc/snacks.html#gorp contains a 'gorp' fragment identifier. See IETF RFC 2396 for more information.