You can also the old-style xmltangle-like method that uses <programlisting> elements with role tags, like so:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "/usr/local/share/sgml/docbook/docbookx.dtd">
<article>
  <articleinfo>
    <title>Gnomovision Version 69: Making Passes at Compilers</title>
    <author>
      <firstname>James</firstname>
      <surname>Hacker</surname>
    </author>
    <date>1989-4-1</date>
  </articleinfo>
  <para>Here's a brief code snippet</para>
  <programlisting role="gnomovision.c">
/* Code goes in here */
    ...
  </programlisting>
</article>

      

You have to tangle your XML document using the -X switch if you do it this way though, and this usage is deprecated. This method makes it easier to weave the document though, because the document is still perfectly legal DocBook.

The accepted way to do it would be to use the xml-lit namespace, as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                  "/usr/local/share/sgml/docbook/docbookx.dtd">
<article xmlns:xml-lit="http://dido.engr.internet.org.ph/projects/xml-lit/">
  <articleinfo>
    <title>Gnomovision Version 69: Making Passes at Compilers</title>
    <author>
      <firstname>James</firstname>
      <surname>Hacker</surname>
    </author>
    <date>1989-4-1</date>
  </articleinfo>
  <para>Here's a brief code snippet</para>
  <programlisting>
    <xml-lit:code xml-lit:filename="gnomovision.c">
/* Code goes in here */
    ...
    </xml-lit:code>
  </programlisting>
</article>

      

This no longer ties you to DocBook, but now you need to specify the -w switch to xml-lit in order to create a document suitable for weaving, which simply strips out the <xml-lit:code/> elements. If this is not done, these stray tags may produce errors when you try to weave the document.

This new usage is encouraged, because it allows you to use the much more powerful <xml-lit:fragmap/> and <xml-lit:fragment/> elements, which define code fragment maps and code fragments, allowing you to reorder code fragments in a logical manner. For instance:

<programlisting>
  <xml-lit:code xml-lit:filename="gnomovision.c">
int
main(void)
{
    <xml-lit:fragmap xml-lit:name="localvars">
      Local variables
    </xml-lit:fragmap>
    <xml-lit:fragmap xml-lit:name="maincode">
      Main code
    </xml-lit:fragmap>
}
  </xml-lit:code>
</programlisting>

<!-- some explanation goes here -->

<programlisting>
  <xml-lit:code xml-lit:filename="gnomovision.c">
    <xml-lit:fragment xml-lit:name="localvars">
  int foo, bar;
    </xml-lit:fragment>
  </xml-lit:code>
</programlisting>

<!-- some more explanation goes here -->

<programlisting>
  <xml-lit:code xml-lit:filename="gnomovision.c">
    <xml-lit:fragment xml-lit:name="maincode">
/* the real main code comes in here */
    </xml-lit:fragment>
  </xml-lit:code>
</programlisting>

      

would tangle into a file gnomovision.c that would probably look something like this:

int
main(void)
{
  int foo, bar;

  /* the real main code comes in here */
}

      

Here is a summary of the elements (local names) in the xml-lit namespace: