The DocBook XSL stylesheets are capable of generating pages with two or more columns of text. By default, only the index uses two columns. Other XSL-FO page masters can be changed to multiple columns using stylesheet parameters, as described in the section “Multi-column”.
When XSL-FO creates multiple columns on a page, the columns are called snaking columns. That's because the text flows down the first column to the bottom of the page, loops back up to the top of the second column, flows down the second column, and so on. In XSL-FO 1.0, all of the columns are the same width and evenly spaced apart.
Normally all of the content that flows onto such pages is fit into the width of the column. This includes chapter and section titles, figures, tables, code samples, lists, and other content. A narrow column can sometimes produce unwanted results. Here are some potential problem elements for narrow columns.
Code samples with long lines may not fit into a narrow column.
Long URLs displayed from
ulink elements may need to be hyphenated. See the section “Breaking long URLs” for more information.
imagedata elements used for graphics specify a fixed width that is greater than the column width, then the image will simply exceed the column boundary. If it appears in the first column, then text in the second column will overwrite it. If it appears in the second column, then it will intrude into the margin.
Likewise, if your tables specify fixed column widths that total more than the page column width, text will spill out of the column. In general, tables in a narrow page column must have few table columns, or fitting text into table columns becomes a problem.
If full justification is turned on, be sure that hyphenation is also turned on, or you may get wide gaps between some words.
Be sure to set the
body.start.indent parameter to
0pt, because each column will be indented by that amount.
When using multiple columns, the narrow column width often makes it hard to fit some figures, tables, and examples. It would be nice if you could tell the processor to span all columns for particular elements. You can, but there are limitations in the DocBook schema and stylesheets.
The DocBook 4.5 DTD provides a
pgwide attribute on
informaltable. The DocBook 5 schema adds
pgwide attribute in the schema indicates the element is wide and may need special handling. There are two ways to handle a wider element:
In a one-column layout that uses a
body.start.indent to indent the body text relative to the headings, a wide element could intrude into the body indent space. That would be accomplished by setting the XSL-FO property
start-indent="0pt" on just that element. The DocBook attribute-set named
pgwide.properties is the place to do that:
<xsl:attribute-set name="pgwide.properties"> <xsl:attribute name="start-indent">0pt</xsl:attribute> </xsl:attribute-set>
In a multi-column layout, a wide element could span all the columns. That would be accomplished by setting the XSL-FO property
span="all" on just that element. Use the same attribute-set with a different attribute:
<xsl:attribute-set name="pgwide.properties"> <xsl:attribute name="span">all</xsl:attribute> </xsl:attribute-set>
The problem with
span="all" is that the XSL-FO 1.0 standard says that
span="all" can only appear on an
fo:block that is a child of the
fo:flow used for a page sequence. This is an unfortunate limitation for DocBook XSL, because it uses a lot of nested blocks that correspond to nested elements. That means if you have a figure inside a section, the
fo:block for the figure will not meet that requirement because a
section element wraps its content in its own
fo:block to set properties that apply to all sections. A figure inside a chapter but before the first
section element will work.
If you are using the Antenna House XSL-FO processor, you have it easy. That processor supports spans on nested blocks, so a figure with a
pgwide attribute will work anywhere if you set the
span property in
pgwide.properties as shown above.
If you are using another XSL-FO processor, you can try setting the stylesheet parameter
wrapper. This causes each section's output to use an
fo:wrapper instead of
fo:block as the outer element. This avoids the nesting of
fo:block and allows a
pgwide span to work when inside a section. This method is known to work with the XEP XSL-FO processor, but not the Antenna House processor (for which it is not needed), nor with FOP. The
fo:wrapper element can accept the section
id and the section attribute-set. However, the attribute-set only supports properties that are inheritable. That's because there is no
block to apply them to. Properties such as
font-family are inheritable, but properties such as
border are not. The
section.container.element parameter was added in version 1.73 of the stylesheets.
A span in XSL-FO alters the text layout on a page as follows:
Content preceding a spanned element in the XML file is flowed in balanced columns above the spanned element. The content does not flow past the span to the bottom of the page and then back up to the top of the page. It stops at the span and restarts at the top of the page (or the bottom of a preceding span if it is on the same page).
Content following a span is flowed in the columns below the span.
Effectively, the top edge of a span acts as the bottom of a page for the content that precedes it.
The bottom of a span acts as the top of a page for the content that follows it.
Because a span acts like a page boundary, any
space-after properties are ignored. The effect is to push the text above and below a span right next to it. You can relieve such crowding by adding
padding attributes as follows:
<xsl:attribute-set name="pgwide.properties"> <xsl:attribute name="span">all</xsl:attribute> <xsl:attribute name="padding-top">12pt</xsl:attribute> <xsl:attribute name="padding-bottom">12pt</xsl:attribute> </xsl:attribute-set>
Titles in chapters can also span a multiple column layout. Titles are handled as part of the titlepage specification system, described in Chapter 11, Title page customization. The titlepage system includes many nested
fo:block elements, which normally would cause spans to be suppressed. But the stylesheet lets you add a span to the outer
fo:block that handles all the title page information for a chapter. This means
author (if used), and any other title page information will be spanned.
The stylesheets support a global span feature using the attribute-set named
component.titlepage.properties that applies to all chapters. In fact, it applies to all component elements including
colophon in addition to
chapter. Here is how it is used:
<xsl:attribute-set name="component.titlepage.properties"> <xsl:attribute name="span">all</xsl:attribute> </xsl:attribute-set>
With this property set, the title and any other titlepage information output for chapters will span across all columns. If you want the title page information centered, then specify that property in the titlepage spec file as described in Chapter 11, Title page customization. This attribute-set was added in the 1.73 version of the stylesheets.
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises