Safely Rebuild Debian's SGML Super Catalogue with update-catalog

You will finish with a checked way to add or remove an ordinary SGML catalogue from a Debian centralized catalogue, then regenerate the system super catalogue when the directory contents change. The examples use update-catalog from sgml-base 1.31, installed here as /usr/sbin/update-catalog.

Allow about fifteen minutes. 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 examples are ordinary, unprivileged commands unless your file permissions say otherwise.

1. Confirm the installed command

Check the binary and package version before copying an example. This prevents a manpage for a different installation being mistaken for 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 in addition to the options documented by the local manpage. Its --version branch currently prints the usage text rather than a version number, so use the package query above for version reporting.

2. Understand the three catalogue roles

An ordinary catalogue is the catalogue a package provides. A centralized catalogue is an entry point under /etc/sgml that can reference ordinary catalogues. The super catalogue is the generated aggregate, normally exposed as /etc/sgml/catalog and stored by this Debian implementation at /var/lib/sgml-base/supercatalog.

For example, inspect the directory without changing it:

$ 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 are considered when the super catalogue is regenerated. A file ending in .old or .disabled is not included.

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 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

Check the printed result. If it contains an unexpected line, stop and fix the path or catalogue contents before using sudo. The command matches the entry text, so an imprecise value can remove more than the line you intended.

4. Apply the centralized-catalog change

Once the test output is correct, 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 and 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 useful recovery copy, but the next update replaces it, so do not treat it as 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-catalog 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. 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 that points at a missing file, is ignored rather than copied into the aggregate.

If the preview is correct, 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, then run --update-super again. Do not edit the generated file directly.

6. Avoid the common failure modes

• Nothing appears 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 complete centralized catalogue ineligible for the generated aggregate.
• You expected a version string: on sgml-base 1.31, --version follows the usage path. Report the package version with dpkg-query.
• You want to edit /etc/sgml/catalog: stop. It is generated state. Change the directory inputs and regenerate it.
• A package operation changed the directory: preview --update-super after the package operation, then rebuild if required. Keep the command unprivileged for the preview and use sudo only for the write.