Customization of the 4.3 DocBook-XSL Stylesheets for the TCC

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.

<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 monospace.verbatim.properties 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.

<xsl:attribute-set name="monospace.verbatim.properties">
  <xsl:attribute name="wrap-option">wrap</xsl:attribute>
  <xsl:attribute name="hyphenation-character">&#x00bb;</xsl:attribute>
  <xsl:attribute name="margin">0.5pt</xsl:attribute>
</xsl:attribute-set>

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

  <xsl:attribute-set name="lit.shading.style">
    <xsl:attribute name="background-color">#eef8e8</xsl:attribute>
  </xsl:attribute-set>

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="programlisting">
    <xsl:choose>
      <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'
            select="substring(@role,9)"/>

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"/>
        </fo:block>

Formatting of the contents of the literate block are handled by Section 10.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"/>
        </xsl:call-template>
      </xsl:when>

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

      <xsl:otherwise>
        <xsl:apply-imports/>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>