Table of Contents
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>
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
Table 13.1. root.properties attribute-set
|FO property||From stylesheet parameter||Default value|
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
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
The DocBook print stylesheet lets you set the overall hyphenation policy with a stylesheet parameter named
hyphenate, whose value is either
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.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
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 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 name||English value||Description|
|The hyphenation character output by the XSL-FO processor when a word is hyphenated.|
|The minimum length of the word fragment after a hyphen when a word is hyphenated.|
|The 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
‐ 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.
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
­ or the DocBook character entity
­ as in
print­able. If your XSL-FO processor supports soft hyphens, it should break at that point if it has to break at all.
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
﻿. 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.
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises