Often we want to include examples of source code, commands, or GUI actions in our documentation. DocBook has many tags to support these needs. Some of the relevant element are listed below.

<example>
<title>A BASIC Example</title>
<programlisting linenumbering='numbered'>
10 PRINT "HELLO WORLD"
20 GOTO 10
</programlisting>
</example>

In this first example, we have a listing of a simple BASIC program. The code contained in the programlisting element is displayed with the spacing and line breaks intact which is very useful for code examples and similar situations where you must preserve the literal formatting. The literallayout and screen elements work similarly, but they are used to indicate different types of content, in particular screen elements contain output that would appear on the screen, while literallayout elements are used for any other text that must be rendered with line breaks and tabs.

The example would look something like this when converted:

  1 
  2 10 PRINT "HELLO WORLD"
  3 20 GOTO 10
  4 

One problem with the screen , literallayout , and programlisting elements is that all text is rendered literally, but DocBook tags are still interpreted as tags and not text. If you do not want tags and entity references interpreted, you can use a <![ CDATA [ ]]> section, which labels the text contained within the inner brackets as character data that should not be interpreted by the XML parser. Any text within the brackets will remain as-is after the conversion, so the example above will successfully reproduce its tags.

<example>
<title>CDATA sections and markup</title>
<screen> 
<![CDATA[
<para>This is a DocBook example.</para>
]]>
</screen>
</example>

This is what the markup example would look like when converted:

<para>This is a DocBook example.</para>