rule
external-data-entity entity-name condition? action*
Used to process external data and subdocument entities. It is triggered when a reference to the named entity occurs in the data content, and any specified condition is met. It is never selected when the entity occurs in the value of "entity" or "entities" attributes, because use of an entity name in an attribute value is not considered to be an entity reference.
Internal data entity references and all text entity references simply result in the substitution of the entity's replacement text for the reference. The SGML parser automatically processes the replacement text and no special rules are needed in the OmniMark program.
When the same actions apply to more than one entity, the names of all the entities can be listed in the rule header, enclosed in parentheses, and separated by the or operator ("|"). The entity name can be output using the format item "%q".
For example, the following external-data-entity rule will fire for external data entities named "picture1" or "picture2":
external-data-entity (picture1 | picture2) output "\picture{%uq.PIC}"
Specific entity names need not be listed in the rule header. #implied can be used instead to indicate that the rule should be selected whenever the condition is met and a reference to an external data or subdocument entity occurs.
For example, the following rule can be used to define actions to be performed whenever a reference to an entity declared with notation "TBL" occurs:
external-data-entity #implied when notation = "TBL"
If multiple external-data-entity rules can be selected for one entity reference, an error is generated. If the same name is used in more than one rule, each rule must have a condition which ensures that only one will be selected.
It is also an error to have no external-data-entity rule when a reference occurs to an external data or subdocument entity.
In the condition on an external-data-entity rule, a test of an attribute value refers to a data attribute. In other rules, an unqualified attribute name refers to attributes of the current element, and data attributes must be accessed explicitly.
external-data-entity rules are not permitted in cross-translations.