Technical documentation often requires presentation of examples of program code. The examples must preserve the line breaks and indents in order to be understood. The preferred element to contain such examples is programlisting, although screen or literallayout may also be used. If you use literallayout, you should set its class attribute to the value of monospaced to ensure presentation in a monospaced font by the stylesheets. The programlisting and screen elements are always presented in a monospaced font. Any of these elements can also be wrapped in example or figure elements if you want to add a title. This chapter focuses on programlisting, but most of the features apply to the other display elements as well.

You can type your text directly in a programlisting element, and its indents and line breaks will be preserved. Use multiple spaces instead of tab characters for indents. Tab characters are not defined in the XSL-FO spec, so they will likely be converted to single spaces and ruin your indent alignments. See the section “Tab expansion” for solutions if you need to use tab characters.

A programlisting element permits some child elements that you can use to highlight certain text, including replaceable, emphasis, and parameter among others. You can also use character entities such as ™ or math symbols. In fact, you must use character entities <, >, and & for the XML special characters <, >, and &, which would otherwise be interpreted as XML markup. Keep in mind that element tags and entities take up more space in the raw XML than in the output, so you have to take that into account while editing for alignment.

You can turn off interpretation of characters that would be recognized as XML markup by enclosing the text in a CDATA section, as in the following example:

<programlisting><![CDATA[                     Start of CDATA section
# Shell redirection and background processing
sort -o sorted  < unsorted  &
]]>                                           End of CDATA section
</programlisting>

Without the CDATA markup, the < and & characters would be interpreted as start-of-element and start-of-entity characters, respectively. Within the CDATA markup, they are treated as ordinary characters. In fact, the only markup recognized within CDATA is the sequence ]]> to terminate the CDATA section. That means you cannot use DocBook elements like <emphasis> or entities like ™ within a CDATA section.

<xsl:attribute-set name="monospace.verbatim.properties">
  <xsl:attribute name="font-family">Lucida Sans Typewriter</xsl:attribute>
  <xsl:attribute name="font-size">9pt</xsl:attribute>
  <xsl:attribute name="keep-together.within-column">always</xsl:attribute>
</xsl:attribute-set>

<xsl:param name="shade.verbatim" select="1"/>

<xsl:attribute-set name="shade.verbatim.style">
  <xsl:attribute name="background-color">#E0E0E0</xsl:attribute>
  <xsl:attribute name="border-width">0.5pt</xsl:attribute>
  <xsl:attribute name="border-style">solid</xsl:attribute>
  <xsl:attribute name="border-color">#575757</xsl:attribute>
  <xsl:attribute name="padding">3pt</xsl:attribute>
</xsl:attribute-set>