Table of Contents
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
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
screen elements are always presented in a monospaced font. Any of these elements can also be wrapped in
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.
programlisting element permits some child elements that you can use to highlight certain text, including
parameter among others. You can also use character entities such as
™ or math symbols. In fact, you must use character entities
& for the XML special characters
&, 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.
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
™ within a CDATA section.
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
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>
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>
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.
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises