Next / Previous / Contents / Shipman's homepage

2. Encoding the literate program

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.

For example, suppose that a given document contains both a C header file named foo.h and a source file named foo.c. A fragment destined for the header file would be encoded like this:

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

A code fragment to be written to foo.c would look like this:

<programlisting role='outFile:foo.c'>
  (lines 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 three 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 Format (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>