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:

• When there are no external-text-entity rules and an external text entity reference is encountered.
• When the "p" or "ep" modifiers are used with a "%q" format item in an external-data-entity or external-text-entity rule.
• When the "p" or "ep" modifiers are used with the "%v" format item.

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:

• for #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.
• for #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.
• for #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.
• The replacement text of an entity identified using a system identifier in an entity declaration or in the #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.

Related Syntax    #libpath    #library    #libvalue

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACYLIBRARIES ] [ ERRORS ]