SP - Catalogs

# Catalogs

The entity manager generates a system identifier for every external entity using catalog entry files in the format defined by SGML Open Technical Resolution TR9401:1995. The entity manager will give an error if it is unable to generate a system identifier for an external entity. Normally if the external identifier for an entity includes a system identifier then the entity manager will use that as the effective system identifier for the entity; this behaviour can be changed using `OVERRIDE` or `SYSTEM` entries in a catalog entry file.

A catalog entry file contains a sequence of entries in one of the following forms:

`PUBLIC pubid sysid`
  This specifies that `sysid` should be used as the effective system identifier if the public identifier is `pubid`. `Sysid` is a system identifier as defined in ISO 8879 and `pubid` is a public identifier as defined in ISO 8879.
`ENTITY name sysid`
  This specifies that sysid should be used as the effective system identifier if the entity is a general entity whose name is name.
`ENTITY %name sysid`
  This specifies that `sysid` should be used as the effective system identifier if the entity is a parameter entity whose name is name. Note that there is no space between the `%` and the `name`.
`DOCTYPE name sysid`
  This specifies that `sysid` should be used as the effective system identifier if the entity is an entity declared in a document type declaration whose document type name is name.
`LINKTYPE name sysid`
  This specifies that `sysid` should be used as the effective system identifier if the entity is an entity declared in a link type declaration whose link type name is name.
`NOTATION name sysid`
  This specifies that `sysid` should be used as the effective system identifier for a notation whose name is `name`. This is an extension to the SGML Open format. This is relevant only with the `-n` option.
`OVERRIDE bool`
  `bool` may be `YES` or `NO`. This sets the overriding mode for entries up to the next occurrence of OVERRIDE or the end of the catalog entry file. At the beginning of a catalog entry file the overriding mode will be NO. A PUBLIC, ENTITY, DOCTYPE, LINKTYPE or NOTATION entry with an overriding mode of YES will be used whether or not the external identifier has an explicit system identifier; those with an overriding mode of NO will be ignored if external identifier has an explicit system identifier. This is an extension to the SGML Open format.
`SYSTEM sysid1 sysid2`
  This specifies that sysid2 should be used as the effective system identifier if the system identifier specified in the external identifier was `sysid1`. This is an extension to the SGML Open format. sysid2 should always be quoted to ensure that it is not misinterpreted when parsed by a system that does not support this extension.
`SGMLDECL sysid`
  This specifies that if the document does not contain an SGML declaration, the SGML declaration in `sysid` should be implied.
`DOCUMENT sysid`
  This specifies that the document entity is `sysid`. This entry is used only with the `-C` option.
`CATALOG sysid`
  This specifies that `sysid` is the system identifier of an additional catalog entry file to be read after this one. Multiple `CATALOG` entries are allowed and will be read in order. This is an extension to the SGML Open format.
`BASE sysid`
  This specifies that relative storage object identifiers in system identifiers in the catalog entry file following this entry should be resolved using first storage object identifier in `sysid` as the base, instead of the storage object identifiers of the storage objects comprising the catalog entry file. This is an extension to the SGML Open format. This extension is proposed in Using SGML Open Catalogs and MIME to Exchange SGML Documents. Note that the `sysid` must exist.
`DELEGATE pubid-prefix sysid`
  This specifies that entities with a public identifier that has `pubid-prefix` as a prefix should be resolved using a catalog whose system identfier is `sysid`. For more details, see A Proposal for Delegating SGML Open Catalogs. This is an extension to the SGML Open format.

The delimiters can be omitted from the `sysid` provided it does not contain any white space. Comments are allowed between parameters delimited by `--` as in SGML.

The entity manager will look for catalog entry files as follows:

1. a file called `catalog` in the same directory as the document entity, unless the environment variable `SP_USE_DOCUMENT_CATALOG` has the value `NO` or `0`;
2. any catalog entry files specified using the `-c` option;
3. a list of files specified by the environment variable `SGML_CATALOG_FILES`; the list is separated by colons under Unix and by semi-colons under MS-DOS and Windows; if this environment variable is not set, then a system dependent list of catalog entry files will be used.

In fact catalog entry files are not restricted to being files: the name of a catalog entry file is interpreted as a system identifier.

A match in one catalog entry file will take precedence over any match in a later catalog entry file. A more specific matching entry in one catalog entry file will take priority over a less specific matching entry in the same catalog entry file. For this purpose, the order of specificity is (most specific first):

- `SYSTEM` entries;
- `PUBLIC` entries;
- `DELEGATE` entries ordered by the length of the prefix, longest first;
- `ENTITY`, `DOCTYPE`, `LINKTYPE` and `NOTATION` entries.