Chapter 13. Print customizations

Table of Contents

Document level properties
Hyphenation
Title fonts and sizes
Book titles
Chapter titles
Other component titles
Section titles
Figure, table, and other titles
Print title pages
Title page attribute-sets
Title page spec file
Title page element templates
Custom title page layout
Template sequence for book title pages
Additional front or back matter
Book covers
Custom page design
Default page masters
Declaring custom page masters
Using custom page masters
Landscape pages
Custom page sequences
Print TOC control
TOC Page margins
TOC title
Styling print TOC entries
TOC page numbering
Part TOC on part titlepage
Editable table of contents
Running headers and footers
Default headers and footers
Changing the header or footer text
Running section titles
Graphic in header or footer
Multi-line header or footer
Changing header or footer styles
Allocating widths in the headers and footers
Allocating height for headers and footers
Page numbering style
Borders and background shading
Customizing inline text
Subscripts and superscripts
Underline and strike-through
Customizing admonitions
Side-by-side formatting
Side floats
A sidebar as side float
Margin notes
Custom margin notes
Custom side float
Clearing a side float
Multi-columns and spans
Page column spans
Adding a font
Locate the font file
Configuring fonts in XSL-FO
Adding a new font to FO output
Numbering paragraphs
Adding line breaks

Getting your printed output to look the way you want may require more DocBook customization than for HTML output. HTML output can be styled using a separate CSS stylesheet applied to the generated HTML files. For print output, you need to specify style properties in the DocBook XSL stylesheet for FO output. In Chapter 8, Printed output options you saw how to set parameters on the command line to change some formatting features. Given the number and type of parameters that need to be set, a customization layer makes more sense for print customization.

The basic framework for a print customization is an XSL stylesheet that imports the standard DocBook FO stylesheet and then adds your changes. Here is a simple example that just sets some page parameters.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
                xmlns:fo="http://www.w3.org/1999/XSL/Format"   
                version="1.0">

<xsl:import href="../../docbook-xsl-1.73.1/fo/docbook.xsl"/>

<xsl:param name="page.height.portrait">9in</xsl:param>
<xsl:param name="page.width.portrait">7in</xsl:param>
<xsl:param name="page.margin.inner">0.75in</xsl:param>
<xsl:param name="page.margin.outer">0.50in</xsl:param>
<xsl:param name="page.margin.top">0.17in</xsl:param>
<xsl:param name="page.margin.bottom">0.50in</xsl:param>

</xsl:stylesheet>

In addition to letting you set parameters, such a customization layer lets you add properties to attribute sets and customize individual stylesheet templates.

Document level properties

The root.properties attribute-set lets you assign XSL-FO properties that apply to the whole document. For example, you might want to globally turn off hyphenation, or print everything in blue type. By default, the stylesheet puts several important properties in this attribute set. Most of the property values can be changed with stylesheet parameters.

Table 13.1. root.properties attribute-set

FO propertyFrom stylesheet parameterDefault value
font-familybody.font.familyserif
font-sizebody.font.size10pt
text-alignalignmentjustify
line-heightline-heightnormal
font-selection-strategyNo parametercharacter-by-character

Generally you should use the appropriate parameter to reset any of these properties. But if you want to add new properties, you can do that by putting an attribute-set of the same name in your customization layer. Since attribute-sets of the same name are merged, your new properties will be added to the default properties. The following is an example that sets the font color to blue:

<xsl:attribute-set name="root.properties">
  <xsl:attribute name="color">blue</xsl:attribute>
</xsl:attribute-set>

When processed, the attributes in this attribute-set are placed in the fo:root element in the XSL-FO output:

<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format" font-family="serif" 
font-size="10pt" text-align="justify" line-height="normal" 
color="blue" font-selection-strategy="character-by-character"  
language="en">

The resulting PDF file will have all blue type. Keep in mind that only properties that are inheritable can be set this way. For example, the widows and orphans properties are inheritable and can be changed from their default values of 2. See a good XSL-FO reference to see which properties are inheritable. The root.properties attribute-set first appeared in version 1.61 of the stylesheets.

Hyphenation

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:

Table 13.2. Hyphenation gentext templates

Gentext template nameEnglish valueDescription
hyphenation-character-The hyphenation character output by the XSL-FO processor when a word is hyphenated.
hyphenation-push-character-count2The minimum length of the word fragment after a hyphen when a word is hyphenated.
hyphenation-remain-character-count2The minimum length of the word fragment before a hyphen when a word is hyphenated.

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 &#x2010; rather than dash. Most of the DocBook gentext files use the ordinary dash character rather than the default XSL-FO value of Unicode &#x2010; 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.

  • You can insert soft hyphen characters at potential hyphenation points in a word. A soft hyphen does not normally print unless the word has to be hyphenated. You can use the Unicode character &#xAD; or the DocBook character entity &shy; as in print&shy;able. If your XSL-FO processor supports soft hyphens, it should break at that point if it has to break at all.

  • You can prevent an already hyphenated word (such as a person's name or product name) from breaking by replacing the ordinary hyphen with a non-breaking hyphen character &#x2011;.

  • If your XSL-FO processor does not support that character, then you can try following the ordinary hyphen with a zero-width no-break space character &#xFEFF;. That should prevent the word from breaking at that point if your XSL-FO processor supports that character. It may, however, still hyphenate the word in other places.

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.