Literate Programming Using OmniMark

Contents

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>.

   external-text-entity #implied
      output "<?code-reference %q>"
   
    

Previous section: Tangling

Next section: Main Loop