Next / Previous / Contents / Shipman's homepage

2. Encoding the literate program

One limitation of Stavely's approach was that it assembled all the executable code fragments into a single file for execution. But the literate exposition of a C program, for example, might require the discussion of two source files, a header file named foo.h and a code file named foo.c. We get around this problem by using the role attribute of the programlisting element in a more flexible way.

The general form of a literate program source is a valid DocBook-XML file, except that each fragment of executable code is wrapped in a programlisting element with this general format:

<programlisting role='outFile:F'>
  (source text)

where F is the name of the output file to which that source text should be written.

We can then handle the above example by using a role='outFile:foo.h' attribute on fragments of the header file and a role='outFile:foo.c' attribute on fragments of the code file. For example:

<programlisting role='outFile:foo.h'>
  (stuff to be written to foo.h)
<programlisting role='outFile:foo.c'>
  (stuff to be written to foo.c)

Of course, either of those files can be broken into many fragments spread throughout the document. They can even be intermingled.

There are two important refinements to mention:

Here's an example of the use of callouts, as it would be encoded in the DocBook source. This is from the exposition of a schema using Relax NG Compact Syntax (RNC).

      <programlisting role='outFile:trails.rnc'>
park = element park
{ attribute name { text }?,   <co id=''>
  trail*                      <co id='park.trail'>
        <callout arearefs=''>
            This optional attribute contains the name of the park.
        <callout arearefs='park.trail'>
            The content of a <code>park</code> element
            consists of one or more <code>trail</code>