184 lines
7.4 KiB
HTML
184 lines
7.4 KiB
HTML
|
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN">
|
||
|
|
<HTML>
|
||
|
|
<HEAD>
|
||
|
|
<TITLE>OpenSP - Catalogs</TITLE>
|
||
|
|
</HEAD>
|
||
|
|
<BODY>
|
||
|
|
<H1>Catalogs</H1>
|
||
|
|
<P>
|
||
|
|
The entity manager generates a system identifier for every external
|
||
|
|
entity using catalog entry files in the format defined by <A
|
||
|
|
HREF="http://www.oasis-open.org/a401.htm">SGML Open
|
||
|
|
Technical Resolution TR9401:1997</A>. 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 <CODE>OVERRIDE</CODE> or <CODE>SYSTEM</CODE> entries in
|
||
|
|
a catalog entry file.
|
||
|
|
<P>
|
||
|
|
A catalog entry file contains a sequence of entries in one of the
|
||
|
|
following forms:
|
||
|
|
<DL>
|
||
|
|
<DT>
|
||
|
|
<SAMP>PUBLIC <VAR>pubid</VAR> <VAR>sysid</VAR></SAMP>
|
||
|
|
<DD>
|
||
|
|
This specifies that <SAMP><VAR>sysid</VAR></SAMP> should be used as
|
||
|
|
the effective system identifier if the public identifier is
|
||
|
|
<SAMP><VAR>pubid</VAR></SAMP>. <SAMP><VAR>Sysid</VAR></SAMP> is a
|
||
|
|
system identifier as defined in ISO 8879 and
|
||
|
|
<SAMP><VAR>pubid</VAR></SAMP> is a public identifier as defined in ISO
|
||
|
|
8879.
|
||
|
|
<DT>
|
||
|
|
<SAMP>ENTITY <VAR>name</VAR> <VAR>sysid</VAR></SAMP>
|
||
|
|
<DD>
|
||
|
|
This specifies that <VAR>sysid</VAR> should be used as the effective
|
||
|
|
system identifier if the entity is a general entity whose name is
|
||
|
|
<VAR>name</VAR>.
|
||
|
|
<DT>
|
||
|
|
<SAMP>ENTITY %<VAR>name</VAR> <VAR>sysid</VAR></SAMP>
|
||
|
|
<DD>
|
||
|
|
This specifies that <SAMP><VAR>sysid</VAR></SAMP> should be used as
|
||
|
|
the effective system identifier if the entity is a parameter entity
|
||
|
|
whose name is <VAR>name</VAR>. Note that there is no space between
|
||
|
|
the <SAMP>%</SAMP> and the <SAMP><VAR>name</VAR></SAMP>.
|
||
|
|
<DT>
|
||
|
|
<SAMP>DOCTYPE <VAR>name</VAR> <VAR>sysid</VAR></SAMP>
|
||
|
|
<DD>
|
||
|
|
This specifies that <SAMP><VAR>sysid</VAR></SAMP> 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 <VAR>name</VAR>.
|
||
|
|
<DT>
|
||
|
|
<SAMP>LINKTYPE <VAR>name</VAR> <VAR>sysid</VAR></SAMP>
|
||
|
|
<DD>
|
||
|
|
This specifies that <SAMP><VAR>sysid</VAR></SAMP> 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 <VAR>name</VAR>.
|
||
|
|
<DT>
|
||
|
|
<SAMP>NOTATION <VAR>name</VAR> <VAR>sysid</VAR></SAMP>
|
||
|
|
<DD>
|
||
|
|
This specifies that <SAMP><VAR>sysid</VAR></SAMP> should be used as
|
||
|
|
the effective system identifier for a notation whose name is
|
||
|
|
<SAMP><VAR>name</VAR></SAMP>.
|
||
|
|
This is relevant only with the <SAMP>-n</SAMP> option.
|
||
|
|
<DT>
|
||
|
|
<SAMP>OVERRIDE <VAR>bool</VAR></SAMP>
|
||
|
|
<DD>
|
||
|
|
<SAMP><VAR>bool</VAR></SAMP> may be <SAMP>YES</SAMP> or
|
||
|
|
<SAMP>NO</SAMP>. 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.
|
||
|
|
<DT>
|
||
|
|
<SAMP>SYSTEM <VAR>sysid1</VAR> <VAR>sysid2</VAR></SAMP>
|
||
|
|
<DD>
|
||
|
|
This specifies that <VAR>sysid2</VAR> should be used as the effective
|
||
|
|
system identifier if the system identifier specified in the external
|
||
|
|
identifier was <SAMP><VAR>sysid1</VAR></SAMP>.
|
||
|
|
<VAR>sysid2</VAR> should always be quoted to
|
||
|
|
ensure that it is not misinterpreted when parsed by a system that does
|
||
|
|
not support this extension.
|
||
|
|
<DT>
|
||
|
|
<A NAME="sgmldecl"><SAMP>SGMLDECL <VAR>sysid</VAR></SAMP></A>
|
||
|
|
<DD>
|
||
|
|
This specifies that if the document does not contain an SGML declaration,
|
||
|
|
the SGML declaration in <SAMP><VAR>sysid</VAR></SAMP> should be implied.
|
||
|
|
<DT>
|
||
|
|
<A NAME="dtddecl"><SAMP>DTDDECL <VAR>pubid</VAR> <VAR>sysid</VAR></SAMP></A>
|
||
|
|
<DD>
|
||
|
|
This specifies that if the document does not contain an SGML declaration
|
||
|
|
and uses a doctype declaration with public identifier
|
||
|
|
<SAMP><VAR>pubid</VAR></SAMP>, the SGML declaration in
|
||
|
|
<SAMP><VAR>sysid</VAR></SAMP> should be implied.
|
||
|
|
<DT>
|
||
|
|
<SAMP>DOCUMENT <VAR>sysid</VAR></SAMP>
|
||
|
|
<DD>
|
||
|
|
This specifies that the document entity is <SAMP><VAR>sysid</VAR></SAMP>.
|
||
|
|
This entry is used only with the <SAMP>-C</SAMP> option.
|
||
|
|
<DT>
|
||
|
|
<SAMP>CATALOG <VAR>sysid</VAR></SAMP>
|
||
|
|
<DD>
|
||
|
|
This specifies that <SAMP><VAR>sysid</VAR></SAMP> is the system
|
||
|
|
identifier of an additional catalog entry file to be read after this
|
||
|
|
one. Multiple <SAMP>CATALOG</SAMP> entries are allowed and will be
|
||
|
|
read in order.
|
||
|
|
<DT>
|
||
|
|
<SAMP>BASE <VAR>sysid</VAR></SAMP>
|
||
|
|
<DD>
|
||
|
|
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
|
||
|
|
<SAMP><VAR>sysid</VAR></SAMP> as the base, instead of the storage
|
||
|
|
object identifiers of the storage objects comprising the catalog entry
|
||
|
|
file.
|
||
|
|
Note that the <CODE><VAR>sysid</VAR></CODE> must exist.
|
||
|
|
<DT>
|
||
|
|
<SAMP>DELEGATE <VAR>pubid-prefix</VAR> <VAR>sysid</VAR></SAMP>
|
||
|
|
<DD>
|
||
|
|
This specifies that entities with a public identifier that has
|
||
|
|
<SAMP><VAR>pubid-prefix</VAR></SAMP> as a prefix should be resolved
|
||
|
|
using a catalog whose system identfier is
|
||
|
|
<SAMP><VAR>sysid</VAR></SAMP>. For more details, see <A
|
||
|
|
HREF="http://www.entmp.org/fpi-urn/delegate.html">A Proposal for
|
||
|
|
Delegating SGML Open Catalogs</A>.
|
||
|
|
<DT>
|
||
|
|
<SAMP>SGML <VAR>name</VAR> <VAR>sysid</VAR></SAMP>
|
||
|
|
<DD>
|
||
|
|
This specifies that the SGML declaration body in <SAMP><VAR>sysid</VAR></SAMP>
|
||
|
|
should be used when the document starts with a reference to an SGML
|
||
|
|
declaration named <SAMP><VAR>name</VAR></SAMP>. This is an OpenSP-specific
|
||
|
|
extension of the SGML Open catalog format. SGML declaration references
|
||
|
|
are defined in
|
||
|
|
<A HREF="http://www.ornl.gov/sgml/sc34/document/0029.htm">Annex K of ISO 8879</A>.
|
||
|
|
</DL>
|
||
|
|
<P>
|
||
|
|
The delimiters can be omitted from the <SAMP><VAR>sysid</VAR></SAMP>
|
||
|
|
provided it does not contain any white space. Comments are allowed
|
||
|
|
between parameters delimited by <SAMP>--</SAMP> as in SGML.
|
||
|
|
<P>
|
||
|
|
The entity manager will look for catalog entry files as follows:
|
||
|
|
<OL>
|
||
|
|
<LI>
|
||
|
|
a file called <SAMP>catalog</SAMP> in the same directory as the
|
||
|
|
document entity, unless the environment variable
|
||
|
|
<SAMP>SP_USE_DOCUMENT_CATALOG</SAMP> has the value <SAMP>NO</SAMP> or
|
||
|
|
<SAMP>0</SAMP>;
|
||
|
|
<LI>
|
||
|
|
any catalog entry files specified using the <SAMP>-c</SAMP> option;
|
||
|
|
<LI>
|
||
|
|
a list of files specified by the environment variable
|
||
|
|
<SAMP>SGML_CATALOG_FILES</SAMP>; 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.
|
||
|
|
</OL>
|
||
|
|
<P>
|
||
|
|
In fact catalog entry files are not restricted to being files: the
|
||
|
|
name of a catalog entry file is interpreted as a system identifier.
|
||
|
|
<P>
|
||
|
|
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):
|
||
|
|
<UL>
|
||
|
|
<LI>
|
||
|
|
<SAMP>SYSTEM</SAMP> entries;
|
||
|
|
<LI>
|
||
|
|
<SAMP>PUBLIC</SAMP> entries;
|
||
|
|
<LI>
|
||
|
|
<SAMP>DELEGATE</SAMP> entries ordered by the length of the prefix,
|
||
|
|
longest first;
|
||
|
|
<LI>
|
||
|
|
<SAMP>ENTITY</SAMP>, <SAMP>DOCTYPE</SAMP>, <SAMP>LINKTYPE</SAMP>,
|
||
|
|
<SAMP>NOTATION</SAMP> and <SAMP>SGML</SAMP> entries.
|
||
|
|
</UL>
|
||
|
|
<P>For the purpose of implying an SGML declaration, <SAMP>DTDDECL</SAMP>
|
||
|
|
entries are more specific than <SAMP>SGMLDECL</SAMP> entries.
|
||
|
|
</BODY>
|
||
|
|
</HTML>
|