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
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 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.
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
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.
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.
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.
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
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
Entity replacement text can also be constructed from multiple sources.
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">