Literate Programming Using OmniMark

Contents

8. Epilogue

It's likely to be obvious at this point that this article is in fact the weaved form of the literate programming tool described. This article was generated by running this literate programming tool on itself. The resulting well-formed XML files were then formatted using a straightforward conversion program. This leads to an apparent circularity: how can a literate programming tool be written in a literate programming fashion? Initially, a rudimentary program was written using standard non-literate (illiterate?) programming techniques. This program was used to bootstrap the development. Eventually, this rudimentary tool was thrown away, and the tangled version of this article was used to process itself. An alternative is to write the initial program entirely in a literate fashion, and then piece the first tangled iteration together by hand.

The literate programming tool described in this article is far from perfect. For instance, it would be nice if the code segments were pretty-printed; this could be handled easily by the formatter. Also, it would be nice if the second and subsequent occurrences of a code block were linked to the first occurrence. These problems are minor usability issues, and are easily addressed with a little more work. However, a more serious problem is that <33 handling a cross-reference> actually high jacks external text entities, effectively forbidding their use in the document. This severe limitation is one that we can accept for the purposes of exposition. However, for a production system, this would have to be addressed. One approach would be to modify <33 handling a cross-reference> to read

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

that way, the external-text-entity rule will only fire when it encounters a defaulted entity. This is a partial solution. We would also need to pass other entities through to the XML output, and find some way of giving their definitions to the formatting program.

In the end, the tangled output of this article (i.e., the executable literate programming tool) is about 300 lines long. And this, despite being a fairly functional literate programming tool, apart from the limitations discussed above. This brevity is achieved by making use of SGML as the input format (eliminating the need to write a parser), of the default entity feature of SGML (providing a mechanism for entering cross-references in a way that blends well with the rest of the SGML input), and of OmniMark's referent capability (which resolves cross-references with little work on our behalf).

Previous section: Generating Output Filenames