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 HTML 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 change the html.stylesheet
to reference.css, 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/html/docbook.xsl"/>
<xsl:param name="html.stylesheet">reference.css</xsl:param>
</xsl:stylesheet>Naturally, you have to change the
href attribute on
<xsl:import>
to point to docbook.xsl
on your system. (Or chunk.xsl, if you're using
chunking.)
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 :-)
author.othername.in.middle
Name
author.othername.in.middle — Is
othername in
author a
middle name?
Synopsis
<xsl:param name="author.othername.in.middle" select="1" doc:type="boolean"/>
If true (non-zero), the othername of an author
appears between the firstname and
surname. Otherwise, othername
is suppressed.
html.stylesheet
Name
html.stylesheet — Name of the stylesheet to use in the generated HTML
Synopsis
<xsl:param name="html.stylesheet" select="''" doc:type="string"/>
The name of the stylesheet to place in the HTML LINK
tag, or the empty string to suppress the stylesheet LINK.
html.stylesheet.type
Name
html.stylesheet.type — The type of the stylesheet used in the generated HTML
Synopsis
<xsl:param name="html.stylesheet.type" doc:type="string">text/css</xsl:param>
The type of the stylesheet to place in the HTML link tag.
html.base
Name
html.base — An HTML base URI
Synopsis
<xsl:param name="html.base" doc:type="uri"/>
If html.base is set, it is used for the BASE
element in the HEAD of the HTML documents.
This is useful for dynamically served HTML where the base URI needs
to be shifted.
ulink.target
Name
ulink.target — The HTML anchor target for ULinks
Synopsis
<xsl:param name="ulink.target" select="'_top'" doc:type="string"/>
If ulink.target is set, its value will
be used for the target attribute
on anchors generated for ulinks.
refentry.xref.manvolnum
Name
refentry.xref.manvolnum — Output
manvolnum as part of
refentry cross-reference?
Synopsis
<xsl:param name="refentry.xref.manvolnum" select="1" doc:type="boolean"/>
if true (non-zero), the manvolnum is used when cross-referencing
refentrys, either with xref
or citerefentry.
show.comments
Name
show.comments — Display
comment elements?
Synopsis
<xsl:param name="show.comments" doc:type="boolean">1</xsl:param>
If true (non-zero), comments will be displayed, otherwise they are suppressed.
Comments here refers to the comment element,
which will be renamed remark in DocBook V4.0,
not XML comments (<-- like this -->) which are unavailable.
funcsynopsis.style
Name
funcsynopsis.style — What style of 'FuncSynopsis' should be generated?
Synopsis
<xsl:param name="funcsynopsis.style" doc:type="list" doc:list="ansi kr">kr</xsl:param>
If funcsynopsis.style is ansi,
ANSI-style function synopses are generated for a
funcsynopsis, otherwise K&R-style
function synopses are generated.
funcsynopsis.decoration
Name
funcsynopsis.decoration — Decorate elements of a FuncSynopsis?
Synopsis
<xsl:param name="funcsynopsis.decoration" select="1" doc:type="boolean"/>
If true (non-zero), elements of the FuncSynopsis will be decorated (e.g. bold or
italic). The decoration is controlled by functions that can be redefined
in a customization layer.
function.parens
Name
function.parens — Generate parens after a function?
Synopsis
<xsl:param name="function.parens" doc:type="boolean">0</xsl:param>
If not 0, the formatting of
a <function> element will include
generated parenthesis.
refentry.generate.name
Name
refentry.generate.name — Output NAME header before 'RefName'(s)?
Synopsis
<xsl:param name="refentry.generate.name" select="1" doc:type="boolean"/>
If true (non-zero), a "NAME" section title is output before the list
of 'RefName's.
admon.graphics
Name
admon.graphics — Use graphics in admonitions?
Synopsis
<xsl:param name="admon.graphics" select="0" doc:type="boolean"/>
If true (non-zero), admonitions are presented in an alternate style that uses
a graphic. Default graphics are provided in the distribution.
admon.graphics.path
Name
admon.graphics.path — Path to admonition graphics
Synopsis
<xsl:param name="admon.graphics.path" doc:type="string">../images/</xsl:param>
Sets the path, probably relative to the directory where the HTML
files are created, to the admonition graphics.
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.
admon.style
Name
admon.style — CSS style attributes for admonitions
Synopsis
<xsl:param name="admon.style" doc:type="string">
<xsl:text>margin-left: 0.5in; margin-right: 0.5in;</xsl:text>
</xsl:param>
Specifies the value of the STYLE
attribute that should be added to admonitions.
section.autolabel
Name
section.autolabel — Are sections enumerated?
Synopsis
<xsl:param name="section.autolabel" select="0" doc:type="boolean"/>
If true (non-zero), unlabeled sections will be enumerated.
section.label.includes.component.label
Name
section.label.includes.component.label — Do section labels include the component label?
Synopsis
<xsl:param name="section.label.includes.component.label" select="0" doc:type="boolean"/>
If true (non-zero), section labels are prefixed with the label of the
component that contains them.
chapter.autolabel
Name
chapter.autolabel — Are chapters and appendixes enumerated?
Synopsis
<xsl:param name="chapter.autolabel" select="1" doc:type="boolean"/>
If true (non-zero), unlabeled chapters and appendixes will be enumerated.
preface.autolabel
Name
preface.autolabel — Are prefaces enumerated?
Synopsis
<xsl:param name="preface.autolabel" select="0" doc:type="boolean"/>
If true (non-zero), unlabeled prefaces will be enumerated.
part.autolabel
Name
part.autolabel — Are parts and references enumerated?
Synopsis
<xsl:param name="part.autolabel" select="1" doc:type="boolean"/>
If true (non-zero), unlabeled parts and references will be enumerated.
qandadiv.autolabel
Name
qandadiv.autolabel — Are divisions in QAndASets enumerated?
Synopsis
<xsl:param name="qandadiv.autolabel" select="1" doc:type="boolean"/>
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?
Synopsis
<xsl:param name="qanda.inherit.numeration" select="1" doc:type="boolean"/>
If true (non-zero), numbered QandADiv elements and Questions and Answers inherit
the numeration of the ancestors of the QandASet.
qanda.defaultlabel
Name
qanda.defaultlabel — Sets the default for defaultlabel on QandASet.
Synopsis
<xsl:param name="qanda.defaultlabel" doc:type="boolean" doc:list="qanda number none">number</xsl:param>
If no defaultlabel attribute is specified on a QandASet, this
value is used. It must be one of the legal values for the defaultlabel
attribute.
generate.qandaset.toc
Name
generate.qandaset.toc — Is a Table of Contents created for QandASets?
Synopsis
<xsl:param name="generate.qandaset.toc" doc:type="boolean">1</xsl:param>
If true (non-zero), a ToC is constructed for QandASets.
generate.qandadiv.toc
Name
generate.qandadiv.toc — Is a Table of Contents created for QandADivs?
Synopsis
<xsl:param name="generate.qandadiv.toc" doc:type="boolean">0</xsl:param>
If true (non-zero), a ToC is constructed for QandADivs.
biblioentry.item.separator
Name
biblioentry.item.separator — Text to separate bibliography entries
Synopsis
<xsl:param name="biblioentry.item.separator" doc:type="string">. </xsl:param>
Text to separate bibliography entries
toc.section.depth
Name
toc.section.depth — How deep should recursive
sections appear
in the TOC?
Synopsis
<xsl:param name="toc.section.depth" doc:type="integer" doc:min="1" doc:max="10">2</xsl:param>
Specifies the depth to which recursive sections should appear in the
TOC.
using.chunker
Name
using.chunker — Will the output be chunked?
Synopsis
<xsl:param name="using.chunker" select="0" doc:type="boolean"/>
In addition to providing chunking, the chunker can cleanup a
number of XML to HTML issues. If the chunker is not being used, the
stylesheets try to avoid producing results that will not appear properly
in browsers.
generate.component.toc
Name
generate.component.toc — Should TOCs be genereated in components (Chapters, Appendixes, etc.)?
Synopsis
<xsl:param name="generate.component.toc" select="1" doc:type="boolean"/>
If true (non-zero), they are.
generate.division.toc
Name
generate.division.toc — Should TOCs be genereated in divisions (Books, Parts, etc.)?
Synopsis
<xsl:param name="generate.division.toc" select="1" doc:type="boolean"/>
If true (non-zero), they are.
link.mailto.url
Name
link.mailto.url — Mailto URL for the LINK REL=made HTML HEAD element
Synopsis
<xsl:param name="link.mailto.url" doc:type="string"/>
If not the empty string, this address will be used for the
REL=made LINK element in the HTML HEAD.
graphic.default.extension
Name
graphic.default.extension — Default extension for graphic filenames
Synopsis
<xsl:param name="graphic.default.extension" doc:type="string"/>
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.
toc.list.type
Name
toc.list.type — Type of HTML list element to use for Tables of Contents
Synopsis
<xsl:param name="toc.list.type" doc:type="list" doc:list="dl ul ol">dl</xsl:param>
When an automatically generated Table of Contents (or List of Titles)
is produced, this HTML element will be used to make the list.
check.idref
Name
check.idref — Test the target of IDREF attributes?
Synopsis
<xsl:param name="check.idref" doc:type="boolean">1</xsl:param>
If 1, the target of IDREF attributes are tested for presence
(and uniqueness). This can be very expensive in large documents.
use.id.function
Name
use.id.function — Use the XPath id() function to find link targets?
Synopsis
<xsl:param name="use.id.function" doc:type="boolean" select="'1'"/>
If 1, the stylesheets use the id() function
to find the targets of cross reference elements. This is more
efficient, but only works if your XSLT processor implements the
id() function, naturally.
THIS PARAMETER IS NOT SUPPORTED. IT IS ALWAYS ASSUMED TO BE 1.
SEE xref.xsl IF YOU NEED TO TURN IT OFF.
spacing.paras
Name
spacing.paras — Insert additional <p> elements for spacing?
Synopsis
<xsl:param name="spacing.paras" doc:type="boolean" select="'0'"/>
When non-zero, additional, empty paragraphs are inserted in
several contexts (for example, around informal figures), to create a
more pleasing visual appearance in many browsers.
body.attrs mode
Name
body.attrs mode — Additional attributes for the HTML body tag
The attributes defined by this attribute set are added to the
HTML <body> tag.
css.decoration
Name
css.decoration — Enable CSS decoration of elements
Synopsis
<xsl:param name="css.decoration" doc:type="boolean">1</xsl:param>
If css.decoration is turned on, then HTML elements
produced by the
stylesheet may be decorated with STYLE attributes. For example, the
LI tags produced for list items may include a fragment of CSS in the
STYLE attribute which sets the CSS property "list-style-type".
show.revisionflag
Name
show.revisionflag — Enable decoration of elements that have a revisionflag
Synopsis
<xsl:param name="show.revisionflag" doc:type="boolean">0</xsl:param>
If show.revisionflag is turned on, then the stylesheets
may produce additional markup designed to allow a CSS stylesheet to
highlight elements that have specific revisionflag settings.
The markup inserted will be usually be either a <span> or <div>
with an appropriate class attribute. (The value of
the class attribute will be the same as the value of the revisionflag
attribute). In some contexts, for example tables, where extra markup
would be structurally illegal, the class attribute will be added to the
appropriate container element.
In general, the stylesheets only test for revisionflag in contexts
where an importing stylesheet would have to redefine whole templates.
Most of the revisionflag processing is expected to be done by another
stylesheet, for example changebars.xsl.
suppress.navigation
Name
suppress.navigation — Disable header and footer navigation
Synopsis
<xsl:param name="suppress.navigation" doc:type="boolean">0</xsl:param>
If suppress.navigation is turned on, header and
footer navigation will be suppressed.
rootid
Name
rootid — Specify the root element to format
Synopsis
<xsl:param name="rootid" select="''" doc:type="string"/>
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.list.table
Name
callout.list.table — Present callout lists using a table?
Synopsis
<xsl:param name="callout.list.table" select="'1'" doc:type="boolean"/>
The default presentation of CalloutLists uses
an HTML DL. Some browsers don't align DLs very well
if callout.graphics are used. With this option
turned on, CalloutLists are presented in an HTML
TABLE, which usually results in better alignment
of the callout number with the callout description.
callout.graphics
Name
callout.graphics — Use graphics for callouts?
Synopsis
<xsl:param name="callout.graphics" select="'1'" doc:type="boolean"/>
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.graphics.extension
Name
callout.graphics.extension — Extension for callout graphics
Synopsis
<xsl:param name="callout.graphics.extension" select="'.png'" doc:type="string"/>
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/'" doc:type="string"/>
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'" 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.
use.extensions
Name
use.extensions — Enable extensions
Synopsis
<xsl:param name="use.extensions" select="'0'" doc:type="boolean"/>
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'" doc:type="boolean"/>
The textinsert extension element inserts the contents of a
a file into the result tree (as text).
saxon.linenumbering
Name
saxon.linenumbering — Enable the line numbering extension
Synopsis
<xsl:param name="saxon.linenumbering" select="'1'" doc:type="boolean"/>
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.extension
Name
linenumbering.extension — Enable the line numbering extension
Synopsis
<xsl:param name="linenumbering.extension" select="'1'" doc:type="boolean"/>
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'" doc:type="integer"/>
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'" doc:type="integer"/>
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="' '" doc:type="string"/>
The separator is inserted between line numbers and lines in
the verbatim environment.
saxon.callouts
Name
saxon.callouts — Enable the callout extension
Synopsis
<xsl:param name="saxon.callouts" select="'1'" doc:type="boolean"/>
The callouts extension processes areaset
elements in ProgramListingCO and other text-based
callout elements.
callouts.extension
Name
callouts.extension — Enable the callout extension
Synopsis
<xsl:param name="callouts.extension" select="'1'" doc:type="boolean"/>
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'" doc:type="integer"/>
If a callout does not identify a column (for example, if it uses
the linerange unit),
it will appear in the default column.
stylesheet.result.type
Name
stylesheet.result.type — Identifies the output format of this stylesheet
Synopsis
<xsl:param name="stylesheet.result.type" select="'html'" doc:type="list" doc:list="html fo"/>
The Saxon 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'.
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 HTML 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 percentag).
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).
saxon.tablecolumns
Name
saxon.tablecolumns — Enable the table columns extension function
Synopsis
<xsl:param name="saxon.tablecolumns" 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.
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.
generate.set.toc
Name
generate.set.toc — FIXME:
Synopsis
<xsl:param name="generate.set.toc" select="1" doc:type="boolean"/>
generate.book.toc
Name
generate.book.toc — FIXME:
Synopsis
<xsl:param name="generate.book.toc" select="1" doc:type="boolean"/>
generate.part.toc
Name
generate.part.toc — FIXME:
Synopsis
<xsl:param name="generate.part.toc" select="1" doc:type="boolean"/>
generate.reference.toc
Name
generate.reference.toc — FIXME:
Synopsis
<xsl:param name="generate.reference.toc" select="1" doc:type="boolean"/>
generate.preface.toc
Name
generate.preface.toc — FIXME:
Synopsis
<xsl:param name="generate.preface.toc" select="1" doc:type="boolean"/>
generate.chapter.toc
Name
generate.chapter.toc — FIXME:
Synopsis
<xsl:param name="generate.chapter.toc" select="1" doc:type="boolean"/>
generate.appendix.toc
Name
generate.appendix.toc — FIXME:
Synopsis
<xsl:param name="generate.appendix.toc" select="1" doc:type="boolean"/>
generate.article.toc
Name
generate.article.toc — FIXME:
Synopsis
<xsl:param name="generate.article.toc" select="1" doc:type="boolean"/>
generate.section.toc
Name
generate.section.toc — FIXME:
Synopsis
<xsl:param name="generate.section.toc" select="0" doc:type="boolean"/>
process.source.toc
Name
process.source.toc — FIXME:
Synopsis
<xsl:param name="process.source.toc" select="0" doc:type="boolean"/>
process.empty.source.toc
Name
process.empty.source.toc — FIXME:
Synopsis
<xsl:param name="process.empty.source.toc" select="0" doc:type="boolean"/>
bridgehead.in.toc
Name
bridgehead.in.toc — Should bridgehead elements appear in the TOC?
Synopsis
<xsl:param name="bridgehead.in.toc" select="0" doc:type="boolean"/>
If non-zero, bridgeheads appear in the TOC. Note that this option
is not fully supported and may be removed in a future version of the
stylesheets.
generate.index
Name
generate.index — FIXME:
Synopsis
<xsl:param name="generate.index" select="1" doc:type="boolean"/>
callout.unicode
Name
callout.unicode — FIXME:
Synopsis
<xsl:param name="callout.unicode" select="0" doc:type="boolean"/>
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.
use.id.as.filename
Name
use.id.as.filename — Use ID value of chunk elements as the filename?
Synopsis
<xsl:param name="use.id.as.filename" select="'0'" doc:type="boolean"/>
If use.id.as.filename
is non-zero, the filename of chunk elements that have IDs will be
derived from the ID value.
inherit.keywords
Name
inherit.keywords — Inherit keywords from ancestor elements?
Synopsis
<xsl:param name="inherit.keywords" select="'1'" doc:type="boolean"/>
If inherit.keywords
is non-zero, the keyword META for each HTML
HEAD element will include all of the keywords from
ancestral elements. Otherwise, only the keywords from the current section
will be used.
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.
citerefentry.link
Name
citerefentry.link — Generate URL links when cross-referencing RefEntrys?
Synopsis
<xsl:param name="citerefentry.link" select="'0'" doc:type="boolean"/>
If true, a web link will be generated, presumably
to an online man->HTML gateway. The text of the link is
generated by the generate.citerefentry.link template.
default.encoding
Name
default.encoding — Encoding used in generated HTML pages
Synopsis
<xsl:param name="default.encoding" select="'ISO-8859-1'" doc:type="string"/>
This encoding is used in files generated by chunking stylesheet. Currently
only Saxon is able to change output encoding.
saxon.character.representation
Name
saxon.character.representation — Saxon character representation used in generated HTML pages
Synopsis
<xsl:param name="saxon.character.representation" select="'entity;decimal'" doc:type="string"/>
This character representation is used in files generated by chunking stylesheet. If
you want to suppress entity references for characters with direct representation
in default.encoding, set this parameter to value native.