3.3. Registering/Deregistering Resources

Note

Most XML DTDs should be registered in both XML and SGML catalog systems.

Registration in the XML catalog system is covered in detail in this section.

Methods for registering resources in the SGML catalog system are only briefly sketched out in this section. Please see the Debian SGML Policy document for more detailed information on registering resources in the SGML catalog system.

The low-level script update-xmlcatalog registers and deregisters entries in the XML catalog system, but its use in packaging resources is not recommended.

In practice, the tool dh_installxmlcatalogs is used to produce the correct snippets to be inserted into the appropriate maintainer script. This tool is provided by the xml-core package.

Typically, dh_installxmlcatalogs is called from debian/rules for building packages containing XML resources, and adds the appropriate maintainer script snippets during the package build process.

When used properly, dh_installxmlcatalogs will

  1. install the local catalog(s) in the correct location(s), and

  2. create the package catalog and register the local catalogs in it by adding appropriate entries to it, and

  3. register the package catalog in the Root Catalog

3.3.1. Using dh_installxmlcatalogs with XML Catalogs

This section is intended for package maintainers and explains how to use dh_installxmlcatalogs as part of the package build process.

The file debian/package.xmlcatalogs lists the local XML catalogs as well as the XML entities in those local XML catalog files that are to be registered in the XML catalog system. It also serves as an input file for dh_installxmlcatalogs. One need not include the package name in the input file: debian/xmlcatalogs will work just as well.

The file debian/package.xmlcatalogs (or simply debian/xmlcatalogs) can have four types of entries, all of which may be repeated as necessary:

local
package
root
root-and-package

The local entry is used to install the local catalog in the installation directory and is of the general form:

local;source;destination

where source denotes the location of the XML catalog file with respect to the source tree, and destination refers to the install destination under the package build area. A semi-colon ";" is used as a separator. Note that the destination path is is given as an absolute (not relative) path in the *.xmlcatalogs file.

A concrete example of a local entry for the tei-xlite package looks like this:

local;debian/catalog.xml;/usr/share/xml/tei/custom/lite/catalog.xml

The entries for the XML entities to be registered in the package catalog file should be of the form

package;type;id;catalog

where the verbatim package indicates this is an entry for an XML entity to be registered in the package catalog file, type indicates the XML entity type (public, system, uri), id indicates the XML entity id (an FPI or URI), and catalog indicates the local XML catalog file.

Note that public and system are to be used for PUBLIC and SYSTEM identifiers, or more generally, any External Identifier as defined in Production 75 of the W3C XML specification. External Identifiers identify the external subset, entities, and notations of an XML document. The uri type is used for non-External Identifier URIs, such as URLs that point to stylesheets, or namespace names.

Example package entries for tei-xlite look like:

package;system;http://www.tei-c.org/Lite/DTD/teixlite.dtd;/usr/share/xml/tei/custom/lite/catalog.xml
package;public;-//TEI//DTD TEI Lite P4 XML 2002-05//EN;/usr/share/xml/tei/custom/lite/catalog.xml

The entries for the XML entities to be registered in the root catalog file should be of the form

root;type;id

where the verbatim root indicates this is an entry for an XML entity to be registered in the Root Catalog file, /etc/xml/catalog, type indicates the XML entity type (public, system, uri), and id indicates the XML entity id. For the tei-xlite package, the root entries look like:

root;system;http://www.tei-c.org/Lite/DTD/teixlite.dtd
root;public;-//TEI//DTD TEI Lite P4 XML 2002-05//EN

root and package entries may be combined into a single entry by using the root-and-package entry. This entry is of the form:

root-and-package;type;id;catalog

where the keywords have the same meaning as in previous cases. Such an entry for the tei-xlitepackage would look like:

root-and-package;public;-//TEI//DTD TEI Lite P4 XML 2002-05//EN;/usr/share/xml/tei/custom/lite/catalog.xml
root-and-package;system;http://www.tei-c.org/Lite/DTD/teixlite.dtd;/usr/share/xml/tei/custom/lite/catalog.xml

Example 3.8. debian/tei-xlite.xmlcatalogs

Putting all this together, the debian/tei-xlite.xmlcatalogs file would be of the form:

local;debian/catalog.xml;/usr/share/xml/tei/custom/lite/catalog.xml
root-and-package;public;-//TEI//DTD TEI Lite P4 XML 2002-05//EN;/usr/share/xml/tei/custom/lite/catalog.xml
root-and-package;system;http://www.tei-c.org/Lite/DTD/teixlite.dtd;/usr/share/xml/tei/custom/lite/catalog.xml

or, using separate package and root entries, would be of the form:

local;debian/catalog.xml;/usr/share/xml/tei/custom/lite/catalog.xml
package;system;http://www.tei-c.org/Lite/DTD/teixlite.dtd;/usr/share/xml/tei/custom/lite/catalog.xml
package;public;-//TEI//DTD TEI Lite P4 XML 2002-05//EN;/usr/share/xml/tei/custom/lite/catalog.xml
root;system;http://www.tei-c.org/Lite/DTD/teixlite.dtd
root;public;-//TEI//DTD TEI Lite P4 XML 2002-05//EN

Either form will work properly, but the root-and-catalog form is slightly more compact.

3.3.2. Using dh_installcatalogs with SGML Catalogs

Most XML DTDs can, and should, also be registered in the SGML catalog system. This section provides basic information developers will need to use the debhelper tool dh_installcatalogs to register these resources in the SGML catalog system.

The file debian/package.sgmlcatalogs (or simply debian/sgmlcatalogs) lists the local SGML catalog files to be installed per package and registered in the SGML catalog system.

Each line in the *.sgmlcatalogs file should be of the form "source dest", where source indicates where the local SGML catalog resides in the source tree, and dest indicates the destination location for the local SGML catalog under the package build area. dest should start with /usr/share/sgml.

The local SGML catalog files listed in the file will be registered in the SGML package catalog file /etc/sgml/package.cat. Furthermore, this package catalog file will be registered in the SGML root catalog file /etc/sgml/catalog. Perhaps an example will clarify the format of debian/package.sgmlcatalogs.

Example 3.9. debian/tei-xlite.sgmlcatalogs

The tei-xlite is a single-catalog package, so the debian/tei-xlite.sgmlcatalogs file is quite simple:

debian/catalog  /usr/share/xml/tei/custom/lite/catalog

The content of this file is sufficient to properly register the catalog in both the root and the package catalogs.