The DocBook print stylesheet lets you set the overall hyphenation policy with a stylesheet parameter named hyphenate, whose value is either true or false. The print stylesheet uses that parameter to set the XSL-FO property of the same name in each fo:page-sequence. From there, it is inherited by all elements contained in the page sequence, unless it is overridden by a descendant element.

The print stylesheet enables hyphenation but does not actually hyphenate words. That job is handled by your XSL-FO processor, so you need to check your processor's documentation for more information about how it handles hyphenation. If you are using FOP and processing languages other than English, then you need to download an additional file named fop-hyph.jar from http://offo.sourceforge.net/hyphenation/index.html. This file needs to be included in the Java CLASSPATH used for FOP processing. You can just add this file to the FOP distribution's lib subdirectory, and then the fop.bat and fop.sh convenience scripts will use it automatically.

Hyphenation is helpful when lines are short and justification is turned on, because it helps avoid large gaps between words in justified lines. However, you may need to turn off hyphenation if your XSL-FO processor does not have a hyphenation algorithm or dictionary for the language you are processing, or if it does a poor job of hyphenating.

You may want to use hyphenation for the body of your document, but turn it off for the title pages and index, for example. You can override the main hyphenation setting for specific page types by customizing the template named set.flow.properties from fo/pagesetup.xsl. That template adds attributes to each fo:flow element, which is nested inside the fo:page-sequence. You can select different hyphenation values for different parts of the document as the following example shows:

<xsl:template name="set.flow.properties">
  <xsl:param name="element" select="local-name(.)"/>
  <xsl:param name="master-reference" select="''"/>

  <xsl:choose>
    <xsl:when test="starts-with($master-reference, 'index') or
                    starts-with($master-reference, 'titlepage') or
                    starts-with($master-reference, 'lot') or  
                    starts-with($master-reference, 'front')">
      <xsl:attribute name="hyphenate">false</xsl:attribute>
    </xsl:when>
    <xsl:otherwise>
      <xsl:attribute name="hyphenate">
        <xsl:value-of select="$hyphenate"/>
      </xsl:attribute>
    </xsl:otherwise>
  </xsl:choose>
  ...

</xsl:template>

This customization turns hyphenation off for titlepages, front matter, TOCs, and indexes. For other page types it uses the value of the global hyphenate parameter.

The hyphenate property can also be controlled for certain elements using the attribute-set used to format that element. For example, to turn off hyphenation in tables, you could use this attribute-set customization:

<xsl:attribute-set name="table.table.properties">
  <xsl:attribute name="hyphenate">false</xsl:attribute>
</xsl:attribute-set>

See the section “Attribute sets” for more information on customizing attribute-sets. The stylesheets provide separate support for hyphenation in programlisting and other verbatim elements, as described in the section “Breaking long lines”. The stylesheets also support special hyphenation in ulink URLs, as described in the section “Breaking long URLs”.

You can use a short customization to control hyphenation of certain inline elements. The following is an example that turns hyphenation off for code elements. It simply wraps the original template body in an fo:inline, so the hyphenation property will be inherited by the content. However, not all processors may support putting the hyphenation property on an inline, since normally it goes on a block element.

<xsl:template match="code">
  <fo:inline hyphenate="false">
    <xsl:call-template name="inline.monoseq"/>
  </fo:inline>
</xsl:template>

The print stylesheet includes three gentext templates that are used to control hyphenation behavior in different languages. See the section “Generated text” for general information on gentext. The gentext templates listed in the following table correspond in name to three XSL-FO properties:

These properties are set using the gentext mechanism rather than a parameter because they may need to be different for different languages. For example, the hyphenation character for Arabic is the Unicode character ‐ rather than dash. Most of the DocBook gentext files use the ordinary dash character rather than the default XSL-FO value of Unicode ‐ because some fonts do not have a glyph for the latter character.

The process of actually hyphenating words is handled entirely by the XSL-FO processor, not the XSL stylesheet. The XSL-FO processor lays out the words in text lines and makes the decisions about how to fit text when hyphenation is turned on. In general, the hyphenation rules used to insert hyphens are language dependent, so you may need to consult the documentation of the XSL-FO processor if words are not breaking where you expect them to.

In some cases, an XSL-FO processor will hyphenate a word where you do not want it to break. There are three special characters that can help you control breaking of individual words.

Most XSL-FO processors let you add specific problem words or additional languages to the hyphenation configuration of the processor. For example, the XEP processor uses TeX hyphenation files, while Antenna House uses XML files, and both support adding specific words as exceptions. The FOP processor has hyphenation patterns in a file named fop-hyph.jar that must be in the Java CLASSPATH for FOP. That jar file can be downloaded from http://offo.sourceforge.net/hyphenation/index.html.