Table of Contents
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.
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
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.
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),
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
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.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.
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.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.height parameters, then the
page.orientation parameter will have no effect.
The side margins are set using the
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.
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.
|Parameter name||What it specifies|
|page.margin.top||Top of page edge to top of header area.|
|region.before.extent||Height of header area, from top of the header text to the bottom of the header area.|
|body.margin.top||Top of header area to top of main text area.|
|body.margin.bottom||Bottom of main text area to bottom of footer area.|
|region.after.extent||Height of footer area, from the top of the footer area to the bottom of the footer text.|
|page.margin.bottom||Bottom of footer area to bottom of page edge.|
Note that both the
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> <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="region.before.extent">0.17in</xsl:param> <xsl:param name="body.margin.top">0.33in</xsl:param> <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>
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.
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.
Height of the header area.
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
body.margin.top), or 0.50 inches total. The bottom distance is
body.margin.bottom), or 1.15in total. The larger
region.after.extent allows for two lines of text in the footer.
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
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
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.
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.
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
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.
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”
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
line-height parameter is set at the root element level
entire document. This will only work if your XSL-FO processor
the line height property.
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
file is contained in the
draft.watermark.image parameter, which by default is set to a web
you might want to set it to a local file.
draft.mode parameter has three possible values:
Turn on draft printing for the whole document.
Turn off draft printing for the whole document.
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.
|DocBook XSL: The Complete Guide - 3rd Edition||PDF version available|
Copyright © 2002-2005 Sagehill Enterprises