To provide compatibility between library
rules, the "-libpath" command-line argument and the external-text-entity
rule, three built-in stream shelves are supported by OmniMark:
#library
, a built-in stream that starts out with one item for each entry in every library
rule in the OmniMark program or in a "-library" file at run time. The key of each item is a public identifier, and the value of each item is the corresponding system identifier.
#libpath
, a built-in stream that starts out with one item for each "-libpath" argument on the command line, in the order in which the "-libpath" arguments appear on the command line.
#libvalue
, a built-in stream that starts out with one item for each public identifier that is built into OmniMark.
Although these shelves are provided chiefly to support compatibility with earlier versions of OmniMark, they are very useful in their own right. If you plan to write your own entity managers, consider carefully how these streams can be used for other purposes.
These streams can be changed by the OmniMark program at any time, in any way, with the following restrictions:
external-text-entity
rules and an external text entity reference is encountered.
external-data-entity
or external-text-entity
rule.
These restrictions are imposed by OmniMark's built-in entity manager, which takes over in these cases. Entity manager designers will usually impose similar restrictions:
#library
, if the built-in entity manager tries to access a system identifier on this shelf, that item must be "attached", either a buffer or a referent stream, and "closed". (If it is a referent, the current value is used.) The item must not be opened for writing, a file, or unattached. This restriction ensures the built-in entity manager always has an immediately accessible value that can be determined without opening a file. On the other hand, there are no restrictions on items of the #library
shelf that do not have keys (because they will never be accessed by the built-in entity manager), or on items that for other, program-specific reasons, are never accessed. Also, there are no restrictions as long as the built-in entity manager is not invoked.
#libpath
, if the built-in entity manager tries to open a file using a system identifier, one found either in an entity declaration or on the #library
stream using a public identifier, because of an external text entity reference, each item of the #libpath
shelf examined must be "attached", either a buffer or a referent stream, and closed (and not opened, a file, or unattached). (If it is a referent, the current value is used.) When trying to find a file matching an external entity reference, the items on the #libpath
shelf are examined one by one, and used as prefixes for the system identifier. As soon as a prefix and system identifier combination is found that is the name of an existing file, it is used, and any following items of #libpath
are ignored. The items of #libpath
can be keyed or not; the built-in entity manager never examines the keys. Because it is used only when trying to open a referenced external text entity, the #libpath
stream is never used by the built-in entity manager if there is any external-text-entity
rule in an OmniMark program.
#libvalue
, if the built-in entity manager tries to access entity text on the #libvalue
stream shelf, that value must be "attached", a buffer or a referent stream, and closed. (If it is a referent, the current value is used.) The item must not be opened for writing, a file, or unattached. This restriction ensures the built-in entity manager always has an immediately accessible value that can be determined without opening a file. On the other hand, there are no restrictions on items of the #libvalue
shelf that don't have keys (because they will never be accessed by the built-in entity manager), or on items that for other, program-specific reasons, are never accessed. Also, there are no restrictions as long as the built-in entity manager is not invoked.
#library
shelf, or the replacement text found as a value in the #libvalue
shelf must conform to the uses made of it. In other words, the replacement text for a public identifier in the SGML Declaration must conform to the requirements of the part of the SGML declaration in which the public identifier is found, and the replacement text of entities referenced in the DTD must contain appropriate declarations, parts of declarations, or string text.
The #library
and #libpath
shelves are initialized from the "-library" and "-libpath" specifications on the command line only if, somewhere in the OmniMark program, there is some action that initiates SGML or XML parsing (i.e. a do sgml-parse
or do xml-parse
action). If there is no such markup parsing action, the "-library" and "-libpath" command-line arguments are ignored.