# 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:1997. 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 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.
`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`. 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.
`DTDDECL pubid sysid`
  This specifies that if the document does not contain an SGML declaration and uses a doctype declaration with public identifier `pubid`, 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.
`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. 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.
`SGML name sysid`
  This specifies that the SGML declaration body in `sysid` should be used when the document starts with a reference to an SGML declaration named `name`. This is an OpenSP-specific extension of the SGML Open catalog format. SGML declaration references are defined in Annex K of ISO 8879.

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`, `NOTATION` and `SGML` entries.

For the purpose of implying an SGML declaration, `DTDDECL` entries are more specific than `SGMLDECL` entries.