Catalog files provide a method for locating external information referenced from a DTD or document.
In this section, you'll learn about
catalog files
mapping to filenames
mapping to WordPerfect template files
catalog entries not supported by WordPerfect
performing a catalog lookup
how the WordPerfect DTD Compiler uses catalog files
how WordPerfect uses catalog files
external entities and catalog entries
What is a catalog file?
A catalog file is a text file that links an entity's name or external identifier to a filename on a particular system. When an SGML or XML processor encounters an external entity reference in a DTD or document instance, it must have a way to locate the entity's content. The catalog file provides an application-independent way to map a public or system identifier to the actual file containing an entity's content.
The most common catalog file entries map a public or system identifier to a file on your system. WordPerfect uses the proprietary keywords WPT_PUBLIC, WPT_SYSTEM and WPT_ROOT to locate the appropriate WordPerfect template file using the information from a document's DOCTYPE declaration.
The format of a catalog file is defined by the Organization for the Advancement of Structured Information Standards (OASIS), an industry consortium formerly known as SGML Open. For more information, see the OASIS Technical Resolution on Entity Management at www.oasis-open.org/html/a401.htm.
Mapping to filenames
A catalog file consists of one or more catalog entries. You can map public identifiers, entity names, system identifiers and document type names to filenames.
To map a public identifier to a filename
You can map a public identifier to a filename using the PUBLIC catalog entry. The PUBLIC catalog entry type is the most common of entry types.
Example
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN"
"isolat1.ent"
This catalog entry would match an entity declared and referenced in the catalog file in the following manner:
<!ENTITY % ISOlat1 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN">
%ISOlat1
Tip
You can also use the PUBLIC catalog entry type to match the public identifier associated with the BASESET, CAPACITY, and SYNTAX portions of an SGML declaration, and with the public identifier (if any) specified in a DOCTYPE declaration.
To map an entity name to a filename
You can map an entity name to a filename using the ENTITY catalog entry type. The ENTITY catalog entry type is used for entities that are declared in the catalog file as "external" by virtue of the SYSTEM keyword, but for which no explicit system identifier is provided.
Example
ENTITY "%WPtable"
"wptable.dtd"
This catalog entry would match an entity declared and referenced in the catalog file in the following manner:
<!ENTITY % WPtable SYSTEM>
%WPtable
The entity name present in the catalog entry begins with the '%' character. In the preceding example, this catalog entry will only match a parameter entity with the name "WPtable". The corresponding catalog entry for a general entity with the same name would omit the leading '%' character:
ENTITY "WPtable"
"wptable.dtd"
To map a system identifier to a filename
You can map a system identifier to a filename using the SYSTEM catalog entry. A catalog entry of type SYSTEM may also be used to match the system identifier (if any) specified in a DOCTYPE declaration in the catalog file.
Example
SYSTEM "mychars.ent"
"c:\MyFiles\mychars.ent"
This catalog entry would match an entity declared and referenced in the catalog file in the following manner:
<!ENTITY % FunChars SYSTEM "mychars.ent">
%FunChars
Note
A matching SYSTEM catalog entry takes precedence over a matching PUBLIC or ENTITY catalog entry. For example, an external entity is declared and referenced in the catalog file as follows:
<!ENTITY % ISOlat1 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN" "junk.ent">
%ISOlat1
And, the following catalog entries existed in the catalog file:
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN"
"isolat1.ent"
ENTITY "%ISOlat1"
"isolat1.txt"
SYSTEM "junk.ent"
"c:\autoexec.bat"
Although all three catalog entries match the information from the entity declaration, the SYSTEM catalog entry has the highest priority. Thus, the application will try to process the "autoexec.bat" file in place of the %ISOlat1; reference.
To map the document type name to a filename
You can map the document type name found in a document type declaration to a filename using the DOCTYPE catalog entry.
Example
DOCTYPE "book"
"book.dtd"
This catalog entry would match the external subset referenced in the catalog file in the following manner:
<!DOCTYPE book SYSTEM>
Note
The external identifier may also include explicit public and/or system identifiers, in which case the DOCTYPE entry would only be tested after searching for a matching SYSTEM entry and PUBLIC entry.
Mapping to WordPerfect template files
The OASIS catalog file specification allows for non-standard catalog entry types. WordPerfect makes use of 3 proprietary catalog entry types to streamline the opening of XML and SGML documents. You can map public identifers, system identifiers and document type names to WordPerfect template files.
To map the public identifier to a WordPerfect template file
You can map the public identifier from a document's DOCTYPE declaration to the filename of a WordPerfect template (WPT) file using the WPT_PUBLIC catalog entry type.
Example
WPT_PUBLIC "-//Corel//DTD Book Model//EN"
"book.wpt"
This catalog entry would match the public identifier in the catalog file in situations similar to one of the following:
<!DOCTYPE book PUBLIC "-//Corel//DTD Book Model//EN">
<book>[...]</book>
<!DOCTYPE book PUBLIC "-//Corel//DTD Book Model//EN" [
[Local markup declarations]
]>
<book>[...]</book>
Note
This catalog entry type is used when opening an XML or SGML document in the WordPerfect editor, and not when parsing a DTD.
To map the system identifier to a WordPerfect template file
You can map the system identifier from a document's DOCTYPE declaration to the filename of a WordPerfect template (WPT) file using the WPT_PUBLIC catalog entry type.
Example
WPT_SYSTEM "book.dtd"
"book.wpt"
This catalog entry would match the system identifier in the catalog file in situations similar to one of the following:
<!DOCTYPE book SYSTEM "book.dtd">
<book>[...]</book>
<!DOCTYPE book SYSTEM "book.dtd" [
[Local markup declarations]
]>
<book>[...]</book>
Note
This catalog entry type is used when opening an XML or SGML document in the WordPerfect editor, and not when parsing a DTD.
To map the document type name to a WordPerfect file
You can map the document type name (the name of the "root" element) from a document's DOCTYPE declaration to the filename of a WordPerfect template (WPT) file using the WPT_ROOT catalog entry type.
Example
WPT_ROOT "book"
"book.wpt"
This catalog entry would match the document type name in the catalog file in situations similar to one of the following:
<!DOCTYPE book PUBLIC "-//Corel//DTD Book Model//EN">
<book>[...]</book>
<!DOCTYPE book SYSTEM "book.dtd">
<book>[...]</book>
<!DOCTYPE book [
...local markup declarations...
]>
<book>[...]</book>
Note
This catalog entry type is used when opening an XML or SGML document in the WordPerfect editor, and not when parsing a DTD.
Catalog entries not supported by WordPerfect
The following catalog entry types are not currently used in WordPerfect:
NOTATION
LINKTYPE
SGMLDECL
DTDDECL
DOCUMENT
DELEGATE
CATALOG
OVERRIDE
BASE
Although these types are considered valid, and are preserved, they are not otherwise acted upon.
For more information on these catalog entry types, see the OASIS Technical Resolution on Entity Management at www.oasis-open.org/html/a401.htm.
Performing a catalog lookup
When you perform a catalog lookup, the first catalog file in the list of "active" catalogs is searched for a matching catalog entry. If more than one catalog entry type can be considered to match, the same catalog file is searched multiple times before the lookup moves to the next active catalog file. The lookup process stops as soon as a match is found.
Example of a catalog lookup
The following declaration and reference are encountered in a DTD being processed by the WordPerfect DTD Compiler:
<!ENTITY % test PUBLIC "-//Corel//ENTITIES Entity test set//EN" "testenty.ent">
%test
When the parameter entity reference "%test; " is encountered, the WordPerfect DTD Compiler performs a catalog lookup to determine the name of the file containing the replacement text of the "test" entity.
Assuming that no match is found in the first active catalog file, the catalog file will be searched three times:
once for a SYSTEM catalog entry with the system identifier "testenty.ent",
once for a PUBLIC catalog entry with the public identifier "-//Corel//ENTITIES Entity test set//EN", and
once for an ENTITY catalog entry with the entity name "%test".
Then the catalog lookup proceeds to the subsequent active catalog files (if any) and performs the same three searches in each one until a match is found or the list is exhausted.
Note
If a matching ENTITY catalog entry is found in the first catalog file, the lookup will stop without searching any other catalog files. This is true even if a subsequent catalog contains a higher-priority entry that would match the public or system identifier.
How the WordPerfect DTD Compiler uses catalog files
As installed, the WordPerfect DTD Compiler has only one active catalog file in its list: COMPILE.CAT. The COMPILE.CAT file contains entries matching each of the installed files that can be used while compiling a DTD.
A catalog lookup is performed by the WordPerfect DTD Compiler in the following situations:
For each BASESET in the SGML declaration, except the first one. The WordPerfect DTD Compiler assumes the public identifier of the first BASESET to be either:
"ISO 646-1983//CHARSET International Reference Version (IRV)//ESC 2/5 4/0", or
"ISO 646:1983//CHARSET International Reference Version (IRV)//ESC 2/5 4/0".
No catalog lookup is performed for these public identifiers because they represent the default character set used by the WordPerfect DTD Compiler.
For the public identifier (if any) associated with the CAPACITY clause in the SGML declaration, unless the public identifier is either:
"ISO 8879-1986//CAPACITY Reference//EN", or
"ISO 8879:1986//CAPACITY Reference//EN".
No catalog lookup is performed for these public identifiers because they represent the default capacity set used by the DTD Compiler.
For the public identifier (if any) associated with the SYNTAX clause in the SGML declaration, unless the public identifier is one of the following:
"ISO 8879-1986//SYNTAX Reference//EN"
"ISO 8879:1986//SYNTAX Reference//EN"
"ISO 8879-1986//SYNTAX Core//EN"
"ISO 8879:1986//SYNTAX Core//EN"
No catalog lookup is performed for these public identifiers because they represent the default concrete syntax used by the WordPerfect DTD Compiler.
For the system identifier, public identifier, and/or entity name associated with an external parameter entity. Searches will be done for matching catalog entries of type SYSTEM, then PUBLIC, then ENTITY.
For an external declaration subset. An external declaration subset is assumed to exist when the DOCTYPE declaration specifies a public and/or system identifier, for example:
<!DOCTYPE book PUBLIC "-//Corel//DTD Book Model//EN" "book.dtd" [local markup declarations]>, or
<!DOCTYPE book PUBLIC "-//Corel//DTD Book Model//EN" [local markup declarations]>, or
<!DOCTYPE book SYSTEM "book.dtd" [local markup declarations]>
Searches will be done for matching entries of type SYSTEM, then PUBLIC, then DOCTYPE. Catalog entries of type ENTITY are not considered in this situation.
If a match is found, the WordPerfect DTD Compiler will attempt to open the file specified in the matching entry. If the filename has a relative path, or no path, the file will be assumed to be relative to the path containing the catalog file. If the file cannot be found or opened, an error is displayed and the compile process halts.
If no matching entry is found during the catalog lookup process, the WordPerfect DTD Compiler will attempt to use the system identifier from the entity declaration as a filename. If the system identifier is a full path, it will be used as-is. Since "testenty.ent" has no specified path, the WordPerfect DTD Compiler will determine the location of the file containing the entity reference and try to open a file named "testenty.ent" in the same folder.
Note
If the only information available is a public identifier, the catalog lookup will only examine PUBLIC catalog entries.
How WordPerfect uses catalog files
WordPerfect only performs catalog lookups when opening an XML or SGML file. As installed, WordPerfect has only one active catalog file in its list: IMPORT.CAT. The IMPORT.CAT file contains entries matching each of the installed XML/SGML documents that can be opened in WordPerfect.
WordPerfect performs a catalog lookup to determine which WordPerfect template file should be used for the XML/SGML document instance being opened. For example, suppose the file being opened begins like this:
<!DOCTYPE book PUBLIC "-//Corel//DTD Book Model//EN" "book.dtd" [local markup declarations]>
<book>[...]</book>
In this case, the catalog lookup will perform searches for matching entries of type WPT_PUBLIC, then WPT_SYSTEM, then WPT_ROOT. The public identifier is given a higher priority than the system identifier. This is because the system identifier in this situation should identify a file containing an actual DTD markup declaration subset. Since WordPerfect is using the document type information to find a WordPerfect template file, and not an actual DTD subset, the public identifier is given priority as a more indirect reference to the DTD subset.
If no DOCTYPE declaration appears at the beginning of the XML/SGML document instance, an attempt is made to locate the first start tag in the document. If one is found, a catalog lookup will be performed to search for a matching WPT_ROOT entry.
If a match is found, WordPerfect will attempt to use the file specified in the matching entry as the base template for the imported document instance. If the filename includes a full path, it will be used as-is. If the filename has a relative path, or no path, the file will be assumed to be relative to XML template folder.
If no matching entry is found during the catalog lookup process, WordPerfect will not attempt to use the system identifier from the entity declaration as a filename. This is because the system identifier refers to a file containing part of an actual DTD, and not to a WordPerfect template.
External entities and catalog entries
The following external entities and catalog entries that could be used to locate matching files on a system:
entity declaration with PUBLIC identifier
entity declaration with SYSTEM identifier
entity declaration with both PUBLIC and SYSTEM identifiers
entity declaration with SYSTEM keyword but no SYSTEM identifier
BASESET section in the SGML declaration
CAPACITY section in the SGML declaration
DOCTYPE statement with a PUBLIC identifier
DOCTYPE statement with a SYSTEM identifier
DOCTYPE statement with neither a PUBLIC nor a SYSTEM identifier
no DOCTYPE statement, but first start tag represents the root element
Entity Declaration with PUBLIC identifier
<!ENTITY % ISOlat1 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN">
Catalog Entry
PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN"
"ISOlat1.ent"
Entity Declaration with SYSTEM identifier
<!ENTITY graph1 SYSTEM "windmill.bmp">
Catalog Entry
SYSTEM "windmill.bmp"
"c:\myfiles\graphics\windmill.bmp"
Entity Declaration with both PUBLIC and SYSTEM identifiers
