Formatting Object Parameter Reference
Norman Walsh
This is technical reference documentation for the DocBook XSL
Stylesheets; it documents (some of) the parameters, templates, and
other elements of the stylesheets.
This reference describes each of the Formatting Object
Stylesheet parameters. These are the “easily
customizable” parts of the stylesheet. If you want to specify
an alternate value for one or more of these parameters, you can do so
in a “driver” stylesheet.
For example, if you want to turn on automatic section numbering,
you might create a driver stylesheet like this:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version='1.0'>
<xsl:import href="/path/to/fo/docbook.xsl"/>
<xsl:param name="section.autolabel" select="1"/>
</xsl:stylesheet>Naturally, you have to change the
href attribute on
<xsl:import>
to point to docbook.xsl
on your system.
This is not intended to be “user” documentation.
It is provided for developers writing customization layers for the
stylesheets, and for anyone who's interested in “how it
works”.
Although I am trying to be thorough, this documentation is known
to be incomplete. Don't forget to read the source, too :-)
admon.graphics.extension
Name
admon.graphics.extension — Extension for admonition graphics
Synopsis
<xsl:param name="admon.graphics.extension" select="'.png'" doc:type="string"/>
Sets the extension to use on admonition graphics.
qandadiv.autolabel
Name
qandadiv.autolabel — Are divisions in QAndASets enumerated?
If true (non-zero), unlabeled qandadivs will be enumerated.
qanda.inherit.numeration
Name
qanda.inherit.numeration — Does enumeration of QandASet components inherit the numeration of parent elements?
If true (non-zero), numbered QandADiv elements and Questions and Answers inherit
the numeration of the ancestors of the QandASet.
graphic.default.extension
Name
graphic.default.extension — Default extension for graphic filenames
If a graphic or mediaobject
includes a reference to a filename that does not include an extension,
and the format attribute is
unspecified, the default extension will be used.
formal.title.properties mode
Name
formal.title.properties mode — Properties of formal object titles
This attribute set is used to specify the properties of formal
object titles.
component.title.properties mode
Name
component.title.properties mode — Properties of component titles
This attribute set is used to specify the properties of component
titles.
admonition.title.properties mode
Name
admonition.title.properties mode — Properties of admonition titles
This attribute set is used to specify the properties of admonition
titles.
xref.properties mode
Name
xref.properties mode — Visual properties of hotlinks
This attribute set is used to specify properties of xrefs
insert.xref.page.number
Name
insert.xref.page.number — Turns page numbers in xrefs on and off
Synopsis
<xsl:param name="insert.xref.page.number" select="0" doc:type="boolean"/>
When equal to 1, this parameter triggers generation of page
number citations after xrefs.
normal.para.spacing mode
Name
normal.para.spacing mode — Spacing properties of normal paragraphs
This attribute set is used to specify the spacing properties
of normal paragraphs.
list.block.spacing mode
Name
list.block.spacing mode — Spacing properties of list blocks
This attribute set is used to specify the spacing properties
of list blocks.
list.item.spacing mode
Name
list.item.spacing mode — Spacing properties of list items
This attribute set is used to specify the spacing properties
of list items.
rootid
Name
rootid — Specify the root element to format
Synopsis
<xsl:param name="rootid" select="''"/>
If rootid is specified, it must be the
value of an ID that occurs in the document being formatted. The entire
document will be loaded and parsed, but formatting will begin at the
element identified, rather than at the root. For example, this allows
you to process only chapter 4 of a book.
Because the entire document is available to the processor, automatic
numbering, cross references, and other dependencies are correctly
resolved.
callout.graphics
Name
callout.graphics — Use graphics for callouts?
Synopsis
<xsl:param name="callout.graphics" select="'0'"/>
If non-zero, callouts are presented with graphics (e.g., reverse-video
circled numbers instead of "(1)", "(2)", etc.).
Default graphics are provided in the distribution.
callout.unicode
Name
callout.unicode — First character to use for Unicode callouts
Synopsis
<xsl:param name="callout.unicode" select="1"/>
If non-zero, callouts are presented with Unicode characters
starting with the character specified. Zero indicates that Unicode
callouts should not be used.
callout.dingbats
Name
callout.dingbats — Use Zapf Dingbats for callouts?
Synopsis
<xsl:param name="callout.dingbats" select="'0'"/>
If non-zero, callouts are presented with Zapf Dingbats.
callout.unicode.start.character
Name
callout.unicode.start.character — Number of the largest callout graphic
Synopsis
<xsl:param name="callout.unicode.start.character" select="10102" doc:type="integer"/>
If callout.graphics
is non-zero, graphics are used to represent
callout numbers. The value of
callout.graphics.number.limit
is
the largest number for which a graphic exists. If the callout number
exceeds this limit, the default presentation "(nnn)" will always
be used.
callout.unicode.number.limit
Name
callout.unicode.number.limit — Number of the largest callout graphic
Synopsis
<xsl:param name="callout.unicode.number.limit" select="'10'" doc:type="integer"/>
If callout.graphics
is non-zero, graphics are used to represent
callout numbers. The value of
callout.graphics.number.limit
is
the largest number for which a graphic exists. If the callout number
exceeds this limit, the default presentation "(nnn)" will always
be used.
callout.graphics.extension
Name
callout.graphics.extension — Extension for callout graphics
Synopsis
<xsl:param name="callout.graphics.extension" select="'.png'"/>
Sets the extension to use on callout graphics.
callout.graphics.path
Name
callout.graphics.path — Path to callout graphics
Synopsis
<xsl:param name="callout.graphics.path" select="'../images/callouts/'"/>
Sets the path, probably relative to the directory where the HTML
files are created, to the callout graphics.
callout.graphics.number.limit
Name
callout.graphics.number.limit — Number of the largest callout graphic
Synopsis
<xsl:param name="callout.graphics.number.limit" select="'10'"/>
If callout.graphics
is non-zero, graphics are used to represent
callout numbers. The value of
callout.graphics.number.limit
is
the largest number for which a graphic exists. If the callout number
exceeds this limit, the default presentation "(nnn)" will always
be used.
use.extensions
Name
use.extensions — Enable extensions
Synopsis
<xsl:param name="use.extensions" select="'0'"/>
If non-zero, extensions may be used. Each extension is
further controlled by its own parameter. But if
use.extensions is zero, no extensions will
be used.
textinsert.extension
Name
textinsert.extension — Enable the textinsert extension element
Synopsis
<xsl:param name="textinsert.extension" select="'1'"/>
The textinsert extension element inserts the contents of a
a file into the result tree (as text).
linenumbering.extension
Name
linenumbering.extension — Enable the line numbering extension
Synopsis
<xsl:param name="linenumbering.extension" select="'1'"/>
If true, verbatim environments (elements that have the
format='linespecific' notation attribute: address, literallayout,
programlisting, screen, synopsis) that specify line numbering will
have, surprise, line numbers.
linenumbering.everyNth
Name
linenumbering.everyNth — Indicate which lines should be numbered
Synopsis
<xsl:param name="linenumbering.everyNth" select="'5'"/>
If line numbering is enabled, everyNth line will be numbered.
linenumbering.width
Name
linenumbering.width — Indicates the width of line numbers
Synopsis
<xsl:param name="linenumbering.width" select="'3'"/>
If line numbering is enabled, line numbers will appear right
justified in a field "width" characters wide.
linenumbering.separator
Name
linenumbering.separator — Specify a separator between line numbers and lines
Synopsis
<xsl:param name="linenumbering.separator" select="' '"/>
The separator is inserted between line numbers and lines in
the verbatim environment.
callouts.extension
Name
callouts.extension — Enable the callout extension
Synopsis
<xsl:param name="callouts.extension" select="'1'"/>
The callouts extension processes areaset
elements in ProgramListingCO and other text-based
callout elements.
callout.defaultcolumn
Name
callout.defaultcolumn — Indicates what column callouts appear in by default
Synopsis
<xsl:param name="callout.defaultcolumn" select="'60'"/>
If a callout does not identify a column (for example, if it uses
the linerange unit),
it will appear in the default column.
tablecolumns.extension
Name
tablecolumns.extension — Enable the table columns extension function
Synopsis
<xsl:param name="tablecolumns.extension" select="'1'" doc:type="boolean"/>
The table columns extension function adjusts the widths of table
columns in the HTML result to more accurately reflect the specifications
in the CALS table.
nominal.table.width
Name
nominal.table.width — The (absolute) nominal width of tables
Synopsis
<xsl:param name="nominal.table.width" select="'6in'" doc:type="length"/>
In order to convert CALS column widths into FO column widths, it
is sometimes necessary to have an absolute table width to use for conversion
of mixed absolute and relative widths. This value must be an absolute
length (not a percentage).
default.table.width
Name
default.table.width — The default width of tables
Synopsis
<xsl:param name="default.table.width" select="''" doc:type="length"/>
If specified, this value will be used for the WIDTH attribute on
tables that do not specify an alternate width (with the dbhtml processing
instruction).
paper.type
Name
paper.type — Select the paper type
Synopsis
<xsl:param name="paper.type" select="'USletter'"/>
The paper type is a convenient way to specify the paper size.
The list of known paper sizes includes USletter and most of the A,
B, and C sizes. See page.width.portrait, for example.
page.orientation
Name
page.orientation — Select the page orientation
Synopsis
<xsl:param name="page.orientation" select="'portrait'"/>
In portrait orientation, the short edge is horizontal; in
landscape orientation, it is vertical.
page.width.portrait
Name
page.width.portrait — Specify the physical size of the short edge of the page
Synopsis
<xsl:param name="page.width.portrait">
<xsl:choose>
<xsl:when test="$paper.type = 'USletter'">8.5in</xsl:when>
<xsl:when test="$paper.type = '4A0'">1682mm</xsl:when>
<xsl:when test="$paper.type = '2A0'">1189mm</xsl:when>
<xsl:when test="$paper.type = 'A0'">841mm</xsl:when>
<xsl:when test="$paper.type = 'A1'">594mm</xsl:when>
<xsl:when test="$paper.type = 'A2'">420mm</xsl:when>
<xsl:when test="$paper.type = 'A3'">297mm</xsl:when>
<xsl:when test="$paper.type = 'A4'">210mm</xsl:when>
<xsl:when test="$paper.type = 'A5'">148mm</xsl:when>
<xsl:when test="$paper.type = 'A6'">105mm</xsl:when>
<xsl:when test="$paper.type = 'A7'">74mm</xsl:when>
<xsl:when test="$paper.type = 'A8'">52mm</xsl:when>
<xsl:when test="$paper.type = 'A9'">37mm</xsl:when>
<xsl:when test="$paper.type = 'A10'">26mm</xsl:when>
<xsl:when test="$paper.type = 'B0'">1000mm</xsl:when>
<xsl:when test="$paper.type = 'B1'">707mm</xsl:when>
<xsl:when test="$paper.type = 'B2'">500mm</xsl:when>
<xsl:when test="$paper.type = 'B3'">353mm</xsl:when>
<xsl:when test="$paper.type = 'B4'">250mm</xsl:when>
<xsl:when test="$paper.type = 'B5'">176mm</xsl:when>
<xsl:when test="$paper.type = 'B6'">125mm</xsl:when>
<xsl:when test="$paper.type = 'B7'">88mm</xsl:when>
<xsl:when test="$paper.type = 'B8'">62mm</xsl:when>
<xsl:when test="$paper.type = 'B9'">44mm</xsl:when>
<xsl:when test="$paper.type = 'B10'">31mm</xsl:when>
<xsl:when test="$paper.type = 'C0'">917mm</xsl:when>
<xsl:when test="$paper.type = 'C1'">648mm</xsl:when>
<xsl:when test="$paper.type = 'C2'">458mm</xsl:when>
<xsl:when test="$paper.type = 'C3'">324mm</xsl:when>
<xsl:when test="$paper.type = 'C4'">229mm</xsl:when>
<xsl:when test="$paper.type = 'C5'">162mm</xsl:when>
<xsl:when test="$paper.type = 'C6'">114mm</xsl:when>
<xsl:when test="$paper.type = 'C7'">81mm</xsl:when>
<xsl:when test="$paper.type = 'C8'">57mm</xsl:when>
<xsl:when test="$paper.type = 'C9'">40mm</xsl:when>
<xsl:when test="$paper.type = 'C10'">28mm</xsl:when>
<xsl:otherwise>8.5in</xsl:otherwise>
</xsl:choose>
</xsl:param>
The portrait page width is the length of the short
edge of the physical page.
page.height.portrait
Name
page.height.portrait — Specify the physical size of the long edge of the page
Synopsis
<xsl:param name="page.height.portrait">
<xsl:choose>
<xsl:when test="$paper.type = 'A4landscape'">210mm</xsl:when>
<xsl:when test="$paper.type = 'USletter'">11in</xsl:when>
<xsl:when test="$paper.type = 'USlandscape'">8.5in</xsl:when>
<xsl:when test="$paper.type = '4A0'">2378mm</xsl:when>
<xsl:when test="$paper.type = '2A0'">1682mm</xsl:when>
<xsl:when test="$paper.type = 'A0'">1189mm</xsl:when>
<xsl:when test="$paper.type = 'A1'">841mm</xsl:when>
<xsl:when test="$paper.type = 'A2'">594mm</xsl:when>
<xsl:when test="$paper.type = 'A3'">420mm</xsl:when>
<xsl:when test="$paper.type = 'A4'">297mm</xsl:when>
<xsl:when test="$paper.type = 'A5'">210mm</xsl:when>
<xsl:when test="$paper.type = 'A6'">148mm</xsl:when>
<xsl:when test="$paper.type = 'A7'">105mm</xsl:when>
<xsl:when test="$paper.type = 'A8'">74mm</xsl:when>
<xsl:when test="$paper.type = 'A9'">52mm</xsl:when>
<xsl:when test="$paper.type = 'A10'">37mm</xsl:when>
<xsl:when test="$paper.type = 'B0'">1414mm</xsl:when>
<xsl:when test="$paper.type = 'B1'">1000mm</xsl:when>
<xsl:when test="$paper.type = 'B2'">707mm</xsl:when>
<xsl:when test="$paper.type = 'B3'">500mm</xsl:when>
<xsl:when test="$paper.type = 'B4'">353mm</xsl:when>
<xsl:when test="$paper.type = 'B5'">250mm</xsl:when>
<xsl:when test="$paper.type = 'B6'">176mm</xsl:when>
<xsl:when test="$paper.type = 'B7'">125mm</xsl:when>
<xsl:when test="$paper.type = 'B8'">88mm</xsl:when>
<xsl:when test="$paper.type = 'B9'">62mm</xsl:when>
<xsl:when test="$paper.type = 'B10'">44mm</xsl:when>
<xsl:when test="$paper.type = 'C0'">1297mm</xsl:when>
<xsl:when test="$paper.type = 'C1'">917mm</xsl:when>
<xsl:when test="$paper.type = 'C2'">648mm</xsl:when>
<xsl:when test="$paper.type = 'C3'">458mm</xsl:when>
<xsl:when test="$paper.type = 'C4'">324mm</xsl:when>
<xsl:when test="$paper.type = 'C5'">229mm</xsl:when>
<xsl:when test="$paper.type = 'C6'">162mm</xsl:when>
<xsl:when test="$paper.type = 'C7'">114mm</xsl:when>
<xsl:when test="$paper.type = 'C8'">81mm</xsl:when>
<xsl:when test="$paper.type = 'C9'">57mm</xsl:when>
<xsl:when test="$paper.type = 'C10'">40mm</xsl:when>
<xsl:otherwise>11in</xsl:otherwise>
</xsl:choose>
</xsl:param>
The portrait page height is the length of the long
edge of the physical page.
page.width
Name
page.width — The width of the physical page
Synopsis
<xsl:param name="page.width">
<xsl:choose>
<xsl:when test="$page.orientation = 'portrait'">
<xsl:value-of select="$page.width.portrait"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$page.height.portrait"/>
</xsl:otherwise>
</xsl:choose>
</xsl:param>
The page width is generally calculated from the
paper.type and
page.orientation.
page.height
Name
page.height — The height of the physical page
Synopsis
<xsl:param name="page.height">
<xsl:choose>
<xsl:when test="$page.orientation = 'portrait'">
<xsl:value-of select="$page.height.portrait"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$page.width.portrait"/>
</xsl:otherwise>
</xsl:choose>
</xsl:param>
The page height is generally calculated from the
paper.type and
page.orientation.
double.sided
Name
double.sided — Is the document to be printed double sided?
Synopsis
<xsl:param name="double.sided" select="'0'"/>
Double-sided documents are printed with a slightly wider margin
on the binding edge of the page.
FIXME: The current set of parameters does not take writing direction
into account.
column.count
Name
column.count — Specifies the number of columns of text on the page
Synopsis
<xsl:param name="column.count" select="'1'"/>
The specified number of columns of text will appear on each page.
region.after.extent
Name
region.after.extent — Specifies the height of the footer.
Synopsis
<xsl:param name="region.after.extent" select="'12pt'"/>
The region after extent is the height of the area where footers
are printed.
region.before.extent
Name
region.before.extent — Specifies the height of the header
Synopsis
<xsl:param name="region.before.extent" select="'12pt'"/>
The region before extent is the height of the area where headers
are printed.
page.margin.top
Name
page.margin.top — The top margin of the page
Synopsis
<xsl:param name="page.margin.top">1in</xsl:param>
The top page margin is the distance from the physical top of the
page to the first line of text (body or header).
page.margin.bottom
Name
page.margin.bottom — The bottom margin of the page
Synopsis
<xsl:param name="page.margin.bottom">1in</xsl:param>
The bottom page margin is the distance from the physical bottom of
the page to the last line of text (body or footer).
page.margin.inner
Name
page.margin.inner — The inner page margin
Synopsis
<xsl:param name="page.margin.inner">
<xsl:choose>
<xsl:when test="$double.sided != 0">1.25in</xsl:when>
<xsl:otherwise>1in</xsl:otherwise>
</xsl:choose>
</xsl:param>
The inner page margin is the distance from binding edge of the
page to the first column of text. In the left-to-right, top-to-bottom writing
direction, this is the left margin of recto pages.
The inner and outer margins are usually the same unless the output
is double-sided.
page.margin.outer
Name
page.margin.outer — The outer page margin
Synopsis
<xsl:param name="page.margin.outer">
<xsl:choose>
<xsl:when test="$double.sided != 0">0.75in</xsl:when>
<xsl:otherwise>10pc</xsl:otherwise>
</xsl:choose>
</xsl:param>
The outer page margin is the distance from non-binding edge of the
page to the last column of text. In the left-to-right, top-to-bottom writing
direction, this is the right margin of recto pages.
The inner and outer margins are usually the same unless the output
is double-sided.
body.margin.bottom
Name
body.margin.bottom — The bottom margin of the body text
Synopsis
<xsl:param name="body.margin.bottom">24pt</xsl:param>
The body bottom margin is the distance from the last line of text
in the page body to the bottom page margin. Note that the page footer, if
any, appears in the space between the body bottom margin and the page
bottom margin.
body.margin.top
Name
body.margin.top — FIXME:
Synopsis
<xsl:param name="body.margin.top">24pt</xsl:param>
The body top margin is the distance from the page top margin to
the first line of text
in the page body. Note that the page header, if
any, appears in the space between the page top margin and the body
top margin.
body.font.family
Name
body.font.family — The default font family for body text
Synopsis
<xsl:param name="body.font.family">Times Roman</xsl:param>
The body font family is the default font used for text in the page body.
title.font.family
Name
title.font.family — The default font family for titles
Synopsis
<xsl:param name="title.font.family">Helvetica</xsl:param>
The title font family is used for titles (chapter, section, figure,
etc.)
monospace.font.family
Name
monospace.font.family — The default font family for monospace environments
Synopsis
<xsl:param name="monospace.font.family">Courier</xsl:param>
The monospace font family is used for verbatim environments
(program listings, screens, etc.).
sans.font.family
Name
sans.font.family — The default sans-serif font family
Synopsis
<xsl:param name="sans.font.family">Helvetica</xsl:param>
The default sans-serif font family. At the present, this isn't
actually used by the stylesheets.
body.font.master
Name
body.font.master — Specifies the default point size for body text
Synopsis
<xsl:param name="body.font.master">10</xsl:param>
The body font size is specified in two parameters
(body.font.master and body.font.size)
so that math can be performed on the font size by XSLT.
body.font.size
Name
body.font.size — Specifies the default font size for body text
Synopsis
<xsl:param name="body.font.size">
<xsl:value-of select="$body.font.master"/><xsl:text>pt</xsl:text>
</xsl:param>
The body font size is specified in two parameters
(body.font.master and body.font.size)
so that math can be performed on the font size by XSLT.
footnote.font.size
Name
footnote.font.size — The font size for footnotes
Synopsis
<xsl:param name="footnote.font.size">
<xsl:value-of select="$body.font.master * 0.8"/><xsl:text>pt</xsl:text>
</xsl:param>
The footnote font size is used for...footnotes!
hyphenate
Name
hyphenate — Specify hyphenation behavior
Synopsis
<xsl:param name="hyphenate">true</xsl:param>
If true, words may be hyphenated. Otherwise, they may not.
alignment
Name
alignment — Specify the default text alignment
Synopsis
<xsl:param name="alignment">justify</xsl:param>
The default text alignment is used for most body text.
stylesheet.result.type
Name
stylesheet.result.type — Identifies the output format of this stylesheet
Synopsis
<xsl:param name="stylesheet.result.type" select="'fo'"/>
The extension functions need to know if the output format
is HTML ('html') or XSL Formatting Objects ('fo'). This variable answers
that question. Valid settings are 'html' or 'fo'.
generate.component.toc
Name
generate.component.toc — Generate a table of contents for components?
Synopsis
<xsl:param name="generate.component.toc" select="0" doc:type="boolean"/>
If non-zero, a table of contents is generated at the beginning
of each component (chapters, appendixes, etc.)
generate.division.toc
Name
generate.division.toc — Generate a table of contents for divisions?
Synopsis
<xsl:param name="generate.division.toc" select="1" doc:type="boolean"/>
If non-zero, a table of contents is generated at the beginning
of each division (sets, books, etc.)
generate.division.figure.lot
Name
generate.division.figure.lot — Generate a list of titles for Figures?
Synopsis
<xsl:param name="generate.division.figure.lot" select="1" doc:type="boolean"/>
If non-zero, a list of titles is generated for Figures.
generate.division.example.lot
Name
generate.division.example.lot — Generate a list of titles for Examples?
Synopsis
<xsl:param name="generate.division.example.lot" select="1" doc:type="boolean"/>
If non-zero, a list of titles is generated for Examples.
generate.division.equation.lot
Name
generate.division.equation.lot — Generate a list of titles for Equations?
Synopsis
<xsl:param name="generate.division.equation.lot" select="1" doc:type="boolean"/>
If non-zero, a list of titles is generated for Equations.
generate.division.table.lot
Name
generate.division.table.lot — Generate a list of titles for Tables?
Synopsis
<xsl:param name="generate.division.table.lot" select="1" doc:type="boolean"/>
If non-zero, a list of titles is generated for Tables.
passivetex.extensions
Name
passivetex.extensions — Enable PassiveTeX extensions?
Synopsis
<xsl:param name="passivetex.extensions" select="0" doc:type="boolean"/>
If non-zero,
PassiveTeX
extensions will be used. At present, this consists of PDF bookmarks
and sorted index terms.
arbortext.extensions
Name
arbortext.extensions — Enable Arbortext extensions?
Synopsis
<xsl:param name="arbortext.extensions" select="0" doc:type="boolean"/>
If non-zero,
Arbortext
extensions will be used.
fop.extensions
Name
fop.extensions — Enable FOP extensions?
Synopsis
<xsl:param name="fop.extensions" select="0" doc:type="boolean"/>
If non-zero,
FOP
extensions will be used. At present, this consists of PDF bookmarks.
default.units
Name
default.units — Default units for an unqualified dimension
Synopsis
<xsl:param name="default.units" select="'pt'" doc:type="list" doc:list="cm mm in pt pc px em"/>
If an unqualified dimension is encountered (for example, in a
graphic width), the default-units will be used for the
units. Unqualified dimensions are not allowed in XSL Formatting Objects.
label.from.part
Name
label.from.part — Renumber chapters in each part?
Synopsis
<xsl:param name="label.from.part" select="'0'" doc:type="boolean"/>
If label.from.part is non-zero, components
(chapters, appendixes, etc.)
will be numbered from 1 in each part. Otherwise,
they will be numbered monotonically throughout each
book.