Next / Previous / Contents / NM Tech homepage

11.6.2. programlisting and other verbatim elements

By “verbatim element,” we mean the elements that are rendered with all line breaks and whitespace untouched: programlisting, screen, and literallayout.

Such elements are heavily used in TCC documentation. To make them stand out from narrative, we set the shade.verbatim option to show them with a light gray background.

<!--Use a gray screen behind verbatim sections-->
<xsl:param name="shade.verbatim" select="1"/>

Program listings will look best when lines are limited to 75 characters. However, in those cases where someone has a longer line, we don't want to chop it off.

Chapter 26 of Stayton, in the chapter on program listings, has a section entitled “Breaking long lines.” Assuming that the line has some spaces in it somewhere, the following change to the attribute set will wrap long lines on a space and insert a right angle quote (») character at the end of all but the last.

We also use a tiny margin (half a point) around all verbatim displays. If we don't do this, programlisting elements inside table entry elements will overlap adjacent cells.

<! Verbatim blocks-->
<xsl:attribute-set name="">
  <xsl:attribute name="wrap-option">wrap</xsl:attribute>
  <xsl:attribute name="hyphenation-character">&#x00bb;</xsl:attribute>
  <xsl:attribute name="margin">0.5pt</xsl:attribute>

For the display of literate code fragments, we define an additional attribute set named that specifies a pale green background.

  <xsl:attribute-set name="">
    <xsl:attribute name="background-color">#eef8e8</xsl:attribute>

The template below changes the formatting of the programlisting element when it is a literate block, that is, when it has a role attribute that starts with "outFile:".

  <xsl:template match="d:programlisting">
      <xsl:when test="@role and starts-with(@role, 'outFile:')">

First we extract the output file name from the role attribute and store it in variable fileName.

        <xsl:variable name='fileName'

This fo:block displays the file name, right-justified, in tiny type, just above the literate block.

        <fo:block keep-with-next.within-page="always"
            text-align="right" margin-top="3pt" margin-bottom="0pt"
            line-height="6pt" font-family="monospace" font-size="6pt" >
          <xsl:value-of select="$fileName"/>

Formatting of the contents of the literate block are handled by Section 11.6.3, “The fo-lit-block template: Format a literate block”.

        <xsl:call-template name="fo-lit-block">
          <xsl:with-param name="file-name" select="$fileName"/>

If the programlisting element is not a literate block, the apply-imports step punts to the default rendering.