Chapter 3. SGML Catalogs

Table of Contents

3.1. The SGML Catalog Hierarchy
3.1.1. The Root Catalog: /etc/sgml/catalog
3.1.2. Package Catalogs: /etc/sgml/package.cat
3.1.3. Local Catalogs: /usr/share/sgml/.../package-dir/catalog
3.2. Registering/Deregistering Resources
3.2.1. Using dh_installcatalogs with SGML Catalogs

This updated policy does not introduce any changes concerning SGML Catalogs.

3.1. The SGML Catalog Hierarchy

The following catalog entry files are of fundamental importance:

Root Catalog

/etc/sgml/catalog

Package Catalogs

/etc/sgml/package.cat

Local Catalogs

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

The Root Catalog references indirectly all the available catalog files. Specifically, it contains only CATALOG entries for the Package Catalogs. (This catalog file is also known as the Super Catalog on some systems.)

The Package Catalogs are the central source of information specific to a given package. They contain only CATALOG entries for the Local Catalogs in the package installation directories. (These catalog files are also known as the Centralized Catalogs on some systems.)

The Local Catalogs are the individual catalogs provided with the DTDs, stylesheets or entities.

3.1.1. The Root Catalog: /etc/sgml/catalog

/etc/sgml/catalog is the Root Catalog. It contains CATALOG pointers to all the Package Catalogs:

-- sample contents of /etc/sgml/catalog -- 

CATALOG  /etc/sgml/docbook.cat 
CATALOG  /etc/sgml/debiandoc.cat
CATALOG  /etc/sgml/jade.cat

3.1.2. Package Catalogs: /etc/sgml/package.cat

The Package Catalog filenames must end in .cat and reside in /etc/sgml/. They can only contain comments and CATALOG directives pointing to the Local Catalogs. For example,

-- sample contents of /etc/sgml/docbook-xml.cat -- 

CATALOG   /usr/share/sgml/docbook/dtd/xml/3.1.7/catalog 
CATALOG   /usr/share/sgml/docbook/dtd/xml/4.0/catalog
CATALOG   /usr/share/sgml/docbook/dtd/xml/4.1.2/catalog 
CATALOG   /usr/share/sgml/docbook/dtd/xml/4.2/catalog

The Package Catalogs are package-specific and are not version-numbered.

Users should be able to define their own package catalogs and their own root catalog in their home directories:

$HOME/.foo-dtd.cat
$HOME/.catalog

The SGML/XML toolchains are not required to use Package Catalogs, although their use is strongly encouraged: if other mechanisms allow one to locate the local catalogs, they can be used as well.

3.1.3. Local Catalogs: /usr/share/sgml/.../package-dir/catalog

The Local Catalogs are often provided by the upstream developer. If not, they are easily constructed by hand. The first non-comment line in a local catalog should contain the directive "OVERRIDE YES". This directive ensures that public identifiers override system identifiers, if both are supplied. A very readable reference on SGML catalogs can be found at James Clark's site: http://www.jclark.com/sp/catalog.htm If the DTD does not have a formal public identifier, then the catalog should contain SYSTEM directives that map the URLs for the DTD to local files.

Example 3.1. SGML Catalog for the DocBook XML DTD

Below is an example SGML catalog for the DocBook XML DTD. Note that any text between double hyphens is treated as a comment. (In the interest of brevity, some of the comments have been removed from the original catalog.)

  -- ...................................................................... --
  -- Catalog data for DocBook XML V4.2 .................................... --

  -- public identifiers override system identifiers, if both are supplied   --

OVERRIDE YES

  -- ...................................................................... --
  -- DocBook driver file .................................................. --

PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
       "docbookx.dtd"
DTDDECL "-//OASIS//DTD DocBook XML V4.2//EN"
       "declaration/xml.dcl"

  -- ...................................................................... --
  -- Other ways to refer to DocBook XML v4.2 .............................. --

PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
        "docbookx.dtd"
DTDDECL "-//OASIS//DTD DocBook XML V4//EN"
        "declaration/xml.dcl"
PUBLIC "-//OASIS//DTD DocBook XML//EN"
        "docbookx.dtd"
DTDDECL "-//OASIS//DTD DocBook XML//EN"
        "declaration/xml.dcl"

  -- ...................................................................... --
  -- DocBook modules ...................................................... --

PUBLIC "-//OASIS//DTD DocBook CALS Table Model V4.2//EN"
       "calstblx.dtd"

PUBLIC "-//OASIS//DTD XML Exchange Table Model 19990315//EN"
       "soextblx.dtd"

PUBLIC "-//OASIS//ELEMENTS DocBook Information Pool V4.2//EN"
       "dbpoolx.mod"
                                                                           
PUBLIC "-//OASIS//ELEMENTS DocBook Document Hierarchy V4.2//EN"
       "dbhierx.mod"

PUBLIC "-//OASIS//ENTITIES DocBook Additional General Entities V4.2//EN"
       "dbgenent.mod"

PUBLIC "-//OASIS//ENTITIES DocBook Notations V4.2//EN"
       "dbnotnx.mod"

PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.2//EN"
       "dbcentx.mod"

  -- End of catalog data for DocBook XML V4.2 ............................. --
  -- ...................................................................... --