Chapter 7. Printed output options

Table of Contents

Page layout
Paper size
Finished page size
Left and right margins
Top and bottom margins
Indenting body text
Landscape
Double sided
Two column
Double spacing
Draft mode
Typography
Body and title font families
Font sizes
Using renderas to style section titles
Chapter and section numbering
Depth of section numbering
Numbering book parts
Page breaking
Keep-together processing instruction
Soft page breaks
Hard page breaks
PDF bookmarks
Extra blank lines
Cross reference page numbers
Docbook icon graphics
Admonition graphics
Callout icons
Printing one chapter

This section describes some common options for printed output. These options can all be specified on the command line and do not require a customization file for the XSL stylesheets. A much larger set of options that include stylesheet customizations is described in Chapter 12, Print customizations.

Printed output is generated by processing your DocBook XML files with the DocBook XSL stylesheets (fo version), and then processing the resulting .fo file with an XSL-FO processor such as FOP or XEP. Most of the options that affect output are applied in the first step using DocBook stylesheet parameters. See Chapter 5, Using stylesheet parameters to learn how to set parameters. See FO Parameter Reference for the standard documentation of the parameters.

Units of measure

When specifying a page dimension or font size in a parameter, you need to supply a number and a unit of measure. The syntax for such expressions is a number followed by a unit abbreviation, without any space between. The number can be an integer or decimal number, and the unit is one of these:

cm   centimeters
mm   millimeters
in   inches
pt   points
pc   picas
px   pixels
em   relative to font size

Examples include 8.5in, 12pt, and 0.35cm.

Page layout

You can control the basic page size and layout using stylesheet parameters. You can set the paper size as well as the margins on all sides. You can also turn on landscape, double-sided, and two-column printing.

Paper size

The default paper size is US letter size (8.5 x 11 inches). You can select a different standard paper size by setting the paper.type parameter to one of the designated values. Some of the common values include USletter (the default), A3, A4, and A5. The complete list of paper codes is listed on the reference page for the page.width.portrait parameter. For example:

xsltproc  --output myfile.fo  \
  --stringparam  paper.type  A4 \
  fo/docbook.xsl  myfile.xml

Finished page size

What if you are preparing page masters for a publication that is not a standard paper size, such as for a 7 x 9 inch book? You can set your own custom page size with the page.width and page.height parameters. These override whatever the paper.type parameter is set to. You can still print your page masters on larger paper, with the expectation that you will be trimming it down to the finished page size. If you are submitting PDF files to a publisher, then you need to arrange this process, because the PDF viewer will show the page size as what you specified.

See the Units of measure note about units of measurement.

For example:

xsltproc  --output myfile.fo  \
  --stringparam  page.height 9in \
  --stringparam  page.width 7in \
  fo/docbook.xsl  myfile.xml

If you plan to use your stylesheet for both portrait and landscape books, you should use the page.width.portrait and page.height.portrait parameters instead. Those set the values for page width and height, respectively, when the parameter page.orientation is set to portrait. If the parameter page.orientation is set to landscape, then the values are switched. If you set the page dimensions using the page.width and page.height parameters, then the page.orientation parameter will have no effect.

Left and right margins

The side margins are set using the page.margin.inner and page.margin.outer parameters. They are named this way for double sided and bound output, where the margins alternate for left and right pages of a spread. For single-sided output, the page.margin.inner value corresponds to the left margin on all the pages. The margins are measured inward from the boundaries set by the page size. When you shrink the page size, the margins stay the same but the printed text area shrinks. For example:

xsltproc  --output myfile.fo  \
  --stringparam  page.height 9in \
  --stringparam  page.width 7in \
  --stringparam  page.margin.inner 2in \
  --stringparam  page.margin.outer 1in \
  fo/docbook.xsl  myfile.xml

The remaining width for the text area is 7 minus 2 minus 1, or 4 inches.

You can also indent body text relative to section titles, or add global indents on the right or left to provide space for margin notes. See the section “Indenting body text” for more information.

Top and bottom margins

The top and bottom margins are a bit more complicated because they include the space reserved for any headers and footers. In the DocBook XSL stylesheets, the following figure shows the parameters that control those spaces.

Figure 7.1. Top and bottom margin parameters

Top and bottom margin parameters
Parameter nameWhat it specifies
page.margin.topTop of page edge to top of header area.
region.before.extentHeight of header area, from top of the header text to the bottom of the header area.
body.margin.topTop of header area to top of main text area.
body.margin.bottomBottom of main text area to bottom of footer area.
region.after.extentHeight of footer area, from the top of the footer area to the bottom of the footer text.
page.margin.bottomBottom of footer area to bottom of page edge.

Note that both the region.before.extent and body.margin.top are measured from the page.margin.top, with a similar arrangement at the bottom of the page. An example should make it easier to set your own values. The following could be the FO stylesheet parameter settings for a 7in by 9in page with headers and footers.

Example 7.1. Page margins

<xsl:param name="page.height.portrait">9in</xsl:param> 1
<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>  2 
<xsl:param name="region.before.extent">0.17in</xsl:param>  3
<xsl:param name="body.margin.top">0.33in</xsl:param>  4
<xsl:param name="region.after.extent">0.35in</xsl:param>
<xsl:param name="page.margin.bottom">0.50in</xsl:param>
<xsl:param name="body.margin.bottom">0.65in</xsl:param>
<xsl:param name="double.sided">1</xsl:param>
1

Specifies the finished page size to be 9 inches tall. That means the paper size after it has been trimmed. It can be printed on a larger sheet before being trimmed.

2

Top of page edge to top of header text area. If the header text is vertically aligned to top, then this will also be to the top of the header text itself.

3

Height of the header area.

4

Top of header text to top of body text.

So in this example, the total distance from the top page edge to the top of the body text is 0.17in (page.margin.top) plus 0.33in (body.margin.top), or 0.50 inches total. The bottom distance is 0.50in (page.margin.bottom) plus 0.65in (body.margin.bottom), or 1.15in total. The larger region.after.extent allows for two lines of text in the footer.

Indenting body text

By default, the DocBook XSL stylesheets indent the body text relative to the section titles in print output. Starting with stylesheet version 1.68, the indent is controlled by the body.start.indent parameter. The default value is 4pc (four picas). This parameter is used by the template named set.flow.properties to add a start-indent="4pc" attribute to certain fo:flow elements. There is a similar body.end.indent parameter to add an indent on the right side. That parameter can be used to create space on the right for margin notes, but its default value is 0pt.

If you want to turn off the indenting of body text, then set the body.start.indent parameter to 0pt. You can't just use zero, because a start-indent property requires a unit of measure.

These parameters are used by the template named set.flow.properties, which lets you add properties that apply to an entire fo:flow in a page sequence. By default, these parameters are used only for page-sequences using the body page-master, such as chapters, and for preface and appendix pages. You can customize the set.flow.properties template to change which flows use these indent parameters.

Chapter titles and section titles are not indented by default. That's because they have their own start-indent property that is set to zero in their titlepage specifications. If you do want your chapter or section titles to be indented as well, then add your own start-indent property and set its value to $body.start.indent. See the section “Title fonts and sizes” to learn how to set properties on titles.

Prior to version 1.68, the body indent was implemented differently, using the title.margin.left parameter. The title.margin.left parameter was set to -4pc, a negative four picas that moves the titles left (a pica is about 0.166 inches). The body area's margin was increased by the same amount to provide the body indent. If your stylesheet version is prior to 1.68 and you want to remove the body indent, set this parameter to 0pc. Be sure to keep units on the value, or the stylesheet will generate an error message.

So the use of the body.start.indent parameter has the same effect as the title.margin.left parameter, except body.start.indent is specified with a positive value. The title.margin.left parameter was retained for backwards compatibility, but you should not try to use both parameters at the same time.

Landscape

The default page orientation for the standard paper sizes is portrait (long edge vertical). You can change to landscape (long edge horizontal) using the page.orientation parameter, whose values can be either portrait (the default) or landscape. For example:

xsltproc  --output myfile.fo  \
  --stringparam  page.orientation  landscape \
  fo/docbook.xsl  myfile.xml

See the section “Finished page size” for a discussion of setting page dimensions if you use one stylesheet for both portrait and landscape output.

Double sided

You can choose single-sided or double-sided output. Double-sided means pages are to be printed on both sides of the paper, and the margins, headers, and footers should be mirrored on the two sides. The default is single sided. Set the double.sided parameter to 1 to change it. For example:

xsltproc  --output myfile.fo  \
  --stringparam  double.sided 1 \
  fo/docbook.xsl  myfile.xml

Note

If you are using FOP version 0.20.4 with double sided turned on, you may get a Java StreamRenderer error. Upgrading to version 0.20.5 seems to fix the problem.

Two column

The default formatting uses one wide column for the whole page, except in the index which has two columns by default. You can specify two or more columns for different page types of your document using the set of column.count.* parameters. Here is a list of these parameters and their default values:

<xsl:param name="column.count.titlepage" select="1"/>
<xsl:param name="column.count.lot" select="1"/>
<xsl:param name="column.count.front" select="1"/>
<xsl:param name="column.count.body" select="1"/>
<xsl:param name="column.count.back" select="1"/>
<xsl:param name="column.count.index" select="2"/>

For example, to change your output for chapters (a body page type) and appendixes (a back matter page type) to two column:

xsltproc  --output myfile.fo  \
  --stringparam  column.count.body  2 \
  --stringparam  column.count.back  2 \
  fo/docbook.xsl  myfile.xml

The title pages and table of contents remain single column.

To see which DocBook elements are processed with each page type, see Table 12.3, “DocBook XSL-FO page master names”

Double spacing

If your format calls for double spacing lines of text, which is often needed for editing review, then set the line-height stylesheet parameter to a value of 2 or more. That value is multiplied by the font size to set the line spacing. Since the normal line height is 1.2, you might try a value of 2.4 to double the spacing. The line-height parameter is set at the root element level for the entire document. This will only work if your XSL-FO processor supports the line height property.

Draft mode

When you want to print a document that is marked as draft, you can set the draft.mode parameter as described below. When it is turned on, the default header prints “Draft” in the header. This mode can also print a faint background image across the page that indicates draft status, if the XSL-FO processor supports background images. The pathname for the image file is contained in the draft.watermark.image parameter, which by default is set to a web address, so you might want to set it to a local file.

The draft.mode parameter has three possible values:

yes

Turn on draft printing for the whole document.

no

Turn off draft printing for the whole document.

maybe

Draft printing is off unless the element generating the current page sequence or one of its ancestors has a status="draft" attribute. Putting this attribute in a book element turns on draft mode for the whole book, while putting it in a chapter element only turns it on for that chapter.