rule
external-text-entity entity-name condition? action*
A rule used to provide OmniMark's SGML parser with the text of an external text entity (that is an external entity that is not cdata
, sdata
, ndata
or subdoc
) whenever such an entity is referenced in an SGML document. Its most important property is that everything written to the #markup-parser
stream within the rule is considered part of the entity's text.
For example, this rule specifies that the text of the entity named "version" is the content of the file named "version.txt":
external-text-entity version output file "version.txt"
If an external-text-entity
outputs no text, the SGML parser treats the entity's replacement text as having zero characters. This is not an error.
It should be noted that, in a context-translation, an external-text-entity
rule can be performed while the find-start
rules are being performed. This will happen if the find-start
rules output the text of an SGML declaration and there are external-text-entity
rules for processing the entities represented by the public identifiers in the SGML declaration.
The output
action is usually used inside an external-text-entity
rule to provide the SGML parser with the entity's replacement text. In an external-text-entity
rule, the default #current-output
stream contains only the #markup-parser
stream. That allows the replacement text of the entity to be fed to the parser using output
actions.
Because anything written to the #markup-parser
stream in an external-text-entity
rule becomes part of the entity's text, the entity's text can be made up of one or more pieces from one or more sources.
If the replacement text of some of the external entities is small, all of the entities can be defined in a single file. This technique can be used to construct a "control file" for configurable documents.
The external-text-entity
rule is invoked by the parser. It then starts up a new process to feed data into the parser. Data output in this process is fed to the parser (unless you explicitly change its destination). The new process consists of the code in the body of the rule, and any code invoked by the code in the body. It runs as a parallel process with the parser until the data it produces has been completely parsed.
Where an external text entity's text does not need processing, it is appropriate that an external-text-entity
rule will use an output
or put
action to provide the file's text to the SGML parser.
Even if some processing is required, it can be done with a do scan
or repeat scan
in the external-text-entity
rule, where each match
emits the processed text using output
or put
.
On the other hand, if substantial processing is required, it will often be the case that it is more appropriate to submit
the text of the file to be processed by find
rules. In this case, any output of the find
rules that process the submitted text is considered part of the text of the entity.
If the find
rules are different from those used to process the main input, it will be necessary to use a using group
prefix on the submit
action to specify which find
rules are used to process the submitted text. For example:
external-text-entity #implied when entity is (public & in-library) using group entity-processing submit file "%pq"
Note that when a category is handled with a condition, all instances failing the condition must be handled using other rules. For example, when using a when #implied
rule, a second rule must be used to handle unless #implied
.
An output-to
action is allowed in an external-text-entity
rule. output-to
in an external-text-entity
rule remains in effect until the end of the rule, unless it is overridden by a further output-to
.
Usually, the only active output stream in an external-text-entity
rule is the #markup-parser
stream, so text written using the output
action becomes part of the replacement text of the external text entity. The output-to
action allows the OmniMark programmer to redirect the output to another destination.
The following code shows how external-text-entity
rules can be used to match named entities. The first rule will match all entities named in the program, except the #dtd
entity and those used in the SGML Declaration (because they don't have names). This allows the #dtd
entity to be processed differently than named entities. The second rule matches all entities in the dtd and the document instance by including both the #dtd
and #implied
entities:
external-text-entity #implied when ... external-text-entity (#implied | #dtd) when ...
Entity replacement text can also be constructed from multiple sources.
The following external-text-entity
rule processes any external text entity that has a system identifier. It treats the system identifier as a sequence of file names, separated by semicolons, and concatenates the text from all of the files together as the entity's replacement text.
external-text-entity #implied when entity is system repeat scan "%eq" match [ \ ";"]+ => file-name output file file-name match ";" ; Ignore any semicolon again
An example of an entity with multiple file names is a case where there is a general entity that represents the chapters that comprise the "advanced" part of a textbook:
<!ENTITY advanced SYSTEM "chapter7.sgm;chapter8.sgm;chapter9.sgm">