Lightweight literate programming using DocBook

Lightweight literate programming is a technique for integrating code with its technical documentation. The main idea is to embed the code in the documentation, in such a way that the code can be extracted from the document source file and processed to create a running program; please see this explanation for details. I am currently using the DocBook notation to write most of my lightweight literate programs.

DocBook has a <programlisting> element that is normally used to include sections of code as figures or displays in a document. This is the obvious element to use for the code sections that will be extracted from the document. However, we do not want to usurp the <programlisting> element for this purpose alone, because the author of a literate program might want to use it for its original purpose as well.

The trick is to use the role atttribute of the <programlisting> element. Most DocBook elements have a role atttribute, which in most cases has no predefined use and can be any string that the user desires. We can mark the <programlisting> elements that are meant to be executable code by giving them the role atttribute "executable".

Here is an example of code in a <programlisting> element:

main()
{
  printf("Hello, world!\n");
}

If this piece of code is marked as executable, the DocBook source looks like this:

<programlisting role="executable">main()
{
  printf("Hello, world!\n");
}
</programlisting>

Notice that there is no line break after the closing bracket of the programlisting tag: the content of the <programlisting> element begins immediately after that bracket.