Literate Programming Using OmniMark
5. Handling Cross-References
The simplicity of this literate programming tool rests on its
use of external text entities to refer to code blocks.
Typically, an entity must be defined in the DTD (either the
external or the internal subset) before it can be used in the
document. However, if the DTD defines a default entity (i.e., an entity named #default), then undefined
entities can appear in the document; they are simply replaced by
the default entity.
Whether tangling or weaving, the processing of
cross-references involves writing a referent to the output, to
be resolved later by OmniMark. However, an external-text-entity rule is used to feed data into the
markup parser, and referents cannot be written to the markup
parser: it needs data, not a promise of data. The way around
this is to use the external-text-entity rule to emit a
processing instruction, which will then trigger a processing-instruction rule on the output of the markup
parser. We can then safely emit a referent to the output; see
<29 tangling a code reference> and <19 weaving a code reference>.<33 handling a cross-reference> =
output "<?code-reference %q>"
Previous section: Tangling
Next section: Main Loop