Fitting text

Some code examples may have lines that are too long or too deeply indented to fit on a printed page. Long lines are not a problem in HTML output, because a browser window can be scrolled to view long lines. But printed text should not exceed the established margins. Three possible solutions are full-page width, reducing the font size, or breaking long lines.

Full-width examples

If your body text is normally indented on the printed page, you might want to take advantage of the extra space for wide listings and other wide examples.

If you put your programlisting element inside an example (with title) or informalexample (no title), then you can add a processing instruction to force full-page width. The following is an example:

<informalexample>
  <?dbfo pgwide="1"?>
  <programlisting>Wide listing that needs full-page width ...
  ...

This processing instruction will cause the stylesheet to apply the attribute-set named pgwide.properties, which sets the start-indent property to 0pt. You can customize that attribute-set to change the properties.

Reducing font size

One solution is to reduce the font size for such listings. You can set the font size for all listings by adding a font-size attribute to the monospace.verbatim.properties attribute-set.

But you may only want to reduce the font size for certain programlisting elements that have this problem. If so, you can use a combination of a processing instruction and a conditional attribute value. The processing instruction could look like the following:

<programlisting><?db-font-size 75% ?># A long line listing
  ...

The name of the PI is your choice. Then make the attribute value conditional on this PI by adding the following to your print customization layer:

<xsl:attribute-set name="monospace.verbatim.properties">
  <xsl:attribute name="font-size">
    <xsl:choose>
      <xsl:when test="processing-instruction('db-font-size')"><xsl:value-of
           select="processing-instruction('db-font-size')"/></xsl:when>
      <xsl:otherwise>inherit</xsl:otherwise>
    </xsl:choose>
  </xsl:attribute>
</xsl:attribute-set>

The xsl:attribute element will be evaluated for each programlisting. If it contains a PI with matching name, it takes its value to be the font-size. The value can be a percentage as in this example, or a fixed value such as 7pt. Be sure to include the xsl:otherwise clause to avoid generating an empty attribute value.

Reducing font size will work when the lines are close to fitting. But when lines are very long, you would have to reduce the font size so much that the text becomes hard to read. Those lines require some means of breaking the lines.

Breaking long lines

Another solution for fitting text in a programlisting is to break each long line into two lines. The best results will be had from manually breaking any long lines after you see which ones do not fit on a page. Manual line breaking permits you to match the appropriate indent level of the text, or break at appropriate points in the syntax. But this manual solution may not be practical for documents with many listings.

You can create automatic line breaks by permitting the lines to wrap inside the program listing. You can do that by setting the wrap-option attribute in the monospace.verbatim.properties attribute-set:

<xsl:attribute-set name="monospace.verbatim.properties">
    <xsl:attribute name="wrap-option">wrap</xsl:attribute>
</xsl:attribute-set>

This will break a long line on a space between words, but it leaves no indication that the first line should logically be continued with the second line. It would be better if the line break inserted a character at the end of the first line that indicated the line break. You can do that by setting the hyphenate.verbatim parameter to 1. You also need to add another attribute to the attribute set:

<xsl:attribute-set name="monospace.verbatim.properties">
    <xsl:attribute name="wrap-option">wrap</xsl:attribute>
    <xsl:attribute name="hyphenation-character">\</xsl:attribute>
</xsl:attribute-set>

The second attribute hyphenation-character identifies the character to use when the line is broken, in this case a backslash. You could use any Unicode character you like, but the character has to be available to the XSL-FO processor at that point. Note that FOP does not support the hyphenate.verbatim feature at all.