Rebuild Debian's SGML Super Catalogue with update-catalog

Install an SGML-using package and its catalogue never shows up, and update-catalog is the tool that stitches it into the system.

You will add or remove an ordinary SGML catalogue from a centralized one, then regenerate the aggregate super catalogue so tools can find it. Allow about fifteen minutes. The examples use update-catalog from sgml-base 1.31, installed here as /usr/sbin/update-catalog.

• You need: a shell, an SGML catalogue supplied by a package, and root access for any command that writes under /etc/sgml or /var/lib/sgml-base. The inspection and test commands below are ordinary and unprivileged.

1. Confirm the installed command

Check the binary and package version before copying an example from this page. A manpage for a different install is not the command on your host:

$ command -v update-catalog
/usr/sbin/update-catalog
$ dpkg-query -W -f='${Package} ${Version}\n' sgml-base
sgml-base 1.31
$ update-catalog --help
Usage:
    update-catalog <options> --add --super <centralized_catalog>
    update-catalog <options> --add <centralized_catalog> <ordinary_catalog>
or
    update-catalog <options> --remove --super <centralized_catalog>
    update-catalog <options> --remove <centralized_catalog> <ordinary_catalog>

The installed script accepts --super alongside what the local manpage documents. Its --version branch currently prints the usage text instead of a version number, so use the dpkg-query line above when you need version reporting.

2. Learn the three catalogue roles

• Ordinary catalogue. The catalogue a package provides.
• Centralized catalogue. An entry point under /etc/sgml that references ordinary catalogues.
• Super catalogue. The generated aggregate, normally exposed as /etc/sgml/catalog and stored on this Debian install at /var/lib/sgml-base/supercatalog.

Inspect the directory without changing anything:

$ find /etc/sgml -maxdepth 1 -type f -name '*.cat' -print
/etc/sgml/xml-core.cat
$ sed -n '1,20p' /etc/sgml/xml-core.cat
CATALOG /usr/share/sgml/dtd/xml-core/catalog
$ readlink -f /etc/sgml/catalog
/var/lib/sgml-base/supercatalog

Only names ending in .cat count when the super catalogue is regenerated. A file ending in .old or .disabled is skipped.

3. Preview an add or remove

Use --test first. It reads the selected centralized catalogue, removes any existing matching entry, and prints the resulting catalogue instead of writing a file. Replace the two paths with the real values from the package you are repairing:

$ update-catalog --test --add \
    /etc/sgml/central-example.cat \
    /usr/share/sgml/example/catalog
Adding entry /usr/share/sgml/example/catalog to catalog /etc/sgml/central-example.cat...
Reading catalog /etc/sgml/central-example.cat and removing entry /usr/share/sgml/example/catalog...
Appending entry /usr/share/sgml/example/catalog...
Writing new entry to /etc/sgml/central-example.cat...
CATALOG /usr/share/sgml/example/catalog
update-catalog: test mode - catalog file will not be updated

For a removal, change only the operation:

$ update-catalog --test --remove \
    /etc/sgml/central-example.cat \
    /usr/share/sgml/example/catalog

Read the printed result carefully. If it has an unexpected line, stop and fix the path or the catalogue contents before touching sudo. The command matches on entry text, so an imprecise value can remove more than the line you meant.

4. Apply the centralized-catalog change

Once the test output looks right, repeat the command without --test:

$ sudo update-catalog --add \
    /etc/sgml/central-example.cat \
    /usr/share/sgml/example/catalog
Adding entry /usr/share/sgml/example/catalog to catalog /etc/sgml/central-example.cat...

For --remove, use the same two paths with the opposite operation. The installed script first renames the existing centralized catalogue to a sibling file ending in .old, then writes the new version. That is a handy recovery copy, but the next update overwrites it, so it is not permanent history.

$ sudo cp --preserve=all \
    /etc/sgml/central-example.cat.old \
    /etc/sgml/central-example.cat

After restoring a centralized catalogue, preview the super-catalogue rebuild again. Do not restore a backup blindly if another package has legitimately changed the current file.

5. Preview and rebuild the super catalogue

Changing which .cat files exist in /etc/sgml changes the inputs to the super catalogue, so preview the aggregate before committing it:

$ update-catalog --test --update-super
Updating the super catalog...
The new super catalog would contain the following entries.
CATALOG /etc/sgml/xml-core.cat
update-catalog: test mode - catalog file will not be updated

Before writing, check each listed centralized catalogue. The implementation parses it and verifies every referenced catalogue exists. An unreadable catalogue, or one pointing at a missing file, is ignored rather than copied into the aggregate.

If the preview looks right, rebuild with elevated privileges:

$ sudo update-catalog --update-super
Updating the super catalog...

Verify the generated link and content:

$ readlink -f /etc/sgml/catalog
/var/lib/sgml-base/supercatalog
$ sed -n '1,20p' /etc/sgml/catalog
--
## This file is created by update-catalog with update-super.
## Please see update-catalog(8) for how to modify this file.
--
CATALOG /etc/sgml/xml-core.cat

The generated file is disposable output. To change it, change the .cat files in /etc/sgml and run --update-super again. Never edit the generated file by hand.

6. Common traps

• Nothing shows up in the super catalogue. Confirm the centralized file name ends in .cat, then check that its referenced catalogues exist and are readable.
• The command says a catalogue is ignored. Read the warning literally: a missing referenced catalogue makes the whole centralized catalogue ineligible for the generated aggregate.
• You expected a version string. On sgml-base 1.31, --version just prints the usage text. Get the package version from dpkg-query instead.
• You want to edit /etc/sgml/catalog. Stop: it is generated state. Change the directory inputs and regenerate it instead.
• A package operation changed the directory. Preview --update-super afterwards, then rebuild if required. Keep the preview unprivileged and reserve sudo for the write.