Chapter 27. Program listings

Table of Contents

Formatting listings
Tab expansion
Fitting text
Full-width examples
Reducing font size
Breaking long lines
External code files
Missing text
Using XInclude for text inclusions
Annotating program listings
Line annotations
Line numbering
Callouts
Callouts on imported text
Callouts on graphics
Syntax highlighting

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 &trade; or math symbols. In fact, you must use character entities &lt;, &gt;, and &amp; 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:

Example 27.1. CDATA 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 &trade; within a CDATA section.

Formatting listings

Formatting a program listing for HTML output is best handled by CSS. Read the class attributes generated by the HTML stylesheet and write CSS selectors to apply styles. See the section “Styling displays with CSS” for an example.

For print output, there are a few parameters and attribute sets that can alter the style of displays. The monospace.verbatim.properties attribute-set applies attributes to the fo:block that contains the listing. In it you can set the font-family, font-size, line-height, and other formatting properties to match your design. For example:

<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>

The keep-together property will try to keep each listing together on a page. That works well if your listings are short. If they are long, though, you may get large white spaces in your output, if a long listing that might start in the middle of a page is instead bumped to start on the next page. If you have a mix of lengths, see the section “Keep-together processing instruction” for how to use a processing instruction for some of them.

You can add background shading to listings by setting the shade.verbatim stylesheet parameter to 1. When you do that, another attribute-set named shade.verbatim.style is applied to the block. The following example customization sets a background color and draws a border (with a little padding) around each listing.

<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>

Tip

When you turn on shading, and especially if you turn on borders, you will find that extra blank lines at the beginning or end of a programlisting element become quite obvious. You will want to edit those out.