$Id: param.xweb,v 1.7 2001/11/06 02:26:59 bobstayton Exp $
Copyright © 1999, 2000, 2001 Norman Walsh
Table of Contents
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="http://docbook.sourceforge.net/release/xsl/snapshot/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 :-)
Table of Contents
admon.graphics.extension — Extension for admonition graphics
Sets the extension to use on admonition graphics.
admon.graphics.path — Path to admonition graphics
Sets the path, probably relative to the directory where the HTML files are created, to the admonition graphics.
admon.graphics — Use graphics in admonitions?
If true (non-zero), admonitions are presented in an alternate style that uses a graphic. Default graphics are provided in the distribution.
admon.style — CSS style attributes for admonitions
|
§4: §129 |
<xsl:param name="admon.style"> <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.
Table of Contents
callout.defaultcolumn — Indicates what column callouts appear in by default
If a callout does not identify a column (for example, if it uses the linerange unit), it will appear in the default column.
callout.graphics.extension — Extension for callout graphics
Sets the extension to use on callout graphics.
callout.graphics.number.limit — Number of the largest callout graphic
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.path — Path to callout graphics
Sets the path, probably relative to the directory where the HTML files are created, to the callout graphics.
callout.graphics — Use graphics for callouts?
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.list.table — Present callout lists using a table?
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.unicode.font — Specify a font for Unicode glyphs
The name of the font to specify around Unicode callout glyphs. If set to the empty string, no font change will occur.
callout.unicode.number.limit — Number of the largest callout graphic
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.start.character — First Unicode character to use, decimal value.
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 — Use Unicode characters rather than images for callouts.
The stylesheets can use either an image of the numbers one to ten, or the single Unicode character which represents the numeral, in white on a black background. Use this to select the Unicode character option.
Table of Contents
ebnf.table.bgcolor — Background color for EBNF tables
Sets the background color for EBNF tables. No bgcolor attribute is output if ebnf.table.bgcolor is set to the null string. The default value matches the value used in recent online versions of the W3C's XML Spec productions.
Table of Contents
annotate.toc — Annotate the Table of Contents?
If true, TOCs will be annotated. At present, this just means that the RefPurpose of RefEntry TOC entries will be displayed.
autotoc.label.separator — Separator between labels and titles in the ToC
String to use to seperate labels and title in a table of contents.
generate.appendix.toc — Specify if a table of contents is required for an appendix
Specify whether you want a table of contents in each appendix.
generate.article.toc — Specify if a toc is wanted for an article.
Specify whether a table of contents is required for an article.
generate.book.toc — Do you want a table of contents in the book?
Specify if a table of contents is required in the book.
generate.chapter.toc — Do you want a table of contents for chapters?
Specify if a table of contents should be generated for each chapter.
generate.component.toc — Should TOCs be genereated in components (Chapters, Appendixes, etc.)?
If true (non-zero), they are.
generate.division.toc — Should TOCs be genereated in divisions (Books, Parts, etc.)?
If true (non-zero), they are.
generate.part.toc — Do you want an index for each part?
Specify if an index should be generated for each part.
generate.preface.toc — Do you want a table of contents for the preface?
Specify if a table of contents should be generated for the preface
generate.qandadiv.toc — Is a Table of Contents created for QandADivs?
If true (non-zero), a ToC is constructed for QandADivs.
generate.qandaset.toc — Is a Table of Contents created for QandASets?
If true (non-zero), a ToC is constructed for QandASets.
generate.reference.toc — Do you want a list of references?
Specify if a list of references should be generated, similar to a table of contents, but for all reference elements.
generate.section.toc — Generate TOCs inside Sections?
If non-zero, a Table of Contents will be generated inside section elements. Note that generate.section.toc.level may suppress some section TOCs.
generate.set.toc — Do you want a table of contents in each set?
Specify if a table of contents is required in each set.
generate.section.toc.level — Control depth of TOC generation in sections
The generate.section.toc.level parameter controls the depth of section in which TOCs will be generated. Note that this is related to, but not the same as toc.section.depth, which controls the depth to which TOC entries will be generated in a given TOC.
If, for example, generate.section.toc.level is 3, TOCs will be generated in first, second, and third level sections, but not in fourth level sections.
toc.list.type — Type of HTML list element to use for Tables of Contents
When an automatically generated Table of Contents (or List of Titles) is produced, this HTML element will be used to make the list.
toc.section.depth — How deep should recursive sections appear in the TOC?
Specifies the depth to which recursive sections should appear in the TOC.
Table of Contents
saxon.callouts — Enable the callout extension
The callouts extension processes areaset elements in ProgramListingCO and other text-based callout elements.
saxon.linenumbering — Enable the line numbering extension
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.
saxon.tablecolumns — Enable the table columns extension function
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.
linenumbering.everyNth — Indicate which lines should be numbered
If line numbering is enabled, everyNth line will be numbered.
linenumbering.extension — Enable the line numbering extension
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.separator — Specify a separator between line numbers and lines
The separator is inserted between line numbers and lines in the verbatim environment.
linenumbering.width — Indicates the width of line numbers
If line numbering is enabled, line numbers will appear right justified in a field "width" characters wide.
tablecolumns.extension — Enable the table columns extension function
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.
textinsert.extension — Enable the textinsert extension element
The textinsert extension element inserts the contents of a a file into the result tree (as text).
Table of Contents
chapter.autolabel — Are chapters automatically enumerated?
If true (non-zero), unlabeled chapters will be enumerated.
appendix.autolabel — Are Appendixes automatically enumerated?
If true (non-zero), unlabeled appendixes will be enumerated.
part.autolabel — Are parts and references enumerated?
If true (non-zero), unlabeled parts and references will be enumerated.
preface.autolabel — Are prefaces enumerated?
If true (non-zero), unlabeled prefaces will be enumerated.
qandadiv.autolabel — Are divisions in QAndASets enumerated?
If true (non-zero), unlabeled qandadivs will be enumerated.
section.autolabel — Are sections enumerated?
If true (non-zero), unlabeled sections will be enumerated.
section.label.includes.component.label — Do section labels include the component label?
If true (non-zero), section labels are prefixed with the label of the component that contains them.
Table of Contents
html.base — An HTML base 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.
html.stylesheet.type — The type of the stylesheet used in the generated HTML
The type of the stylesheet to place in the HTML link tag.
html.stylesheet — Name of the stylesheet to use in the generated HTML
The name of the stylesheet to place in the HTML LINK tag, or the empty string to suppress the stylesheet LINK.
use.id.as.filename — Use ID value of chunk elements as the filename?
If use.id.as.filename is non-zero, the filename of chunk elements that have IDs will be derived from the ID value.
using.chunker — Will the output be chunked?
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.
css.decoration — Enable CSS decoration of elements
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".
spacing.paras — Insert additional <p> elements for spacing?
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.
emphasis.propagates.style — Pass emphasis role attribute through to HTML?
If true, the role attribute of emphasis elements will be passed through to the HTML as a class attribute on a span that surrounds the emphasis.
phrase.propagates.style — Pass phrase role attribute through to HTML?
If true, the role attribute of phrase elements will be passed through to the HTML as a class attribute on a span that surrounds the phrase.
stylesheet.result.type — Identifies the output format of this stylesheet
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'.
html.longdesc — Should longdesc URIs be created?
If non-zero, HTML files will be created for the longdesc attribute. These files are created from the textobjects in mediaobjects and inlinemediaobject.
html.longdesc.link — Should a link to the longdesc be included in the HTML?
If non-zero, links will be created to the HTML files created for the longdesc attribute. It makes no sense to turn enable this option without also enabling the $html.longdesc parameter.
The longdesc.link named template is called to construct the link.
Table of Contents
use.id.function — Use the XPath id() function to find link targets?
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.
rootid — Specify the root element to format
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.
Table of Contents
inherit.keywords — Inherit keywords from ancestor elements?
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.
make.single.year.ranges — Print single-year ranges (e.g., 1998-1999)
If non-zero, year ranges that span a single year will be printed in range notation (1998-1999) instead of discrete notation (1998, 1999).
make.year.ranges — Collate copyright years into ranges?
If non-zero, copyright years will be collated into ranges.
author.othername.in.middle — Is othername in author a middle name?
If true (non-zero), the othername of an author appears between the firstname and surname. Otherwise, othername is suppressed.
Table of Contents
funcsynopsis.decoration — Decorate elements of a FuncSynopsis?
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.
funcsynopsis.style — What style of 'FuncSynopsis' should be generated?
If funcsynopsis.style is ansi, ANSI-style function synopses are generated for a funcsynopsis, otherwise K&R-style function synopses are generated.
function.parens — Generate parens after a function?
If not 0, the formatting of a <function> element will include generated parenthesis.
refentry.generate.name — Output NAME header before 'RefName'(s)?
If true (non-zero), a "NAME" section title is output before the list of 'RefName's.
refentry.xref.manvolnum — Output manvolnum as part of refentry cross-reference?
if true (non-zero), the manvolnum is used when cross-referencing refentrys, either with xref or citerefentry.
citerefentry.link — Generate URL links when cross-referencing RefEntrys?
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.
Table of Contents
default.table.width — The default width of tables
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).
nominal.table.width — The (absolute) nominal width of tables
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).
table.borders.with.css — Use CSS to specify table, row, and cell borders?
If true (non-zero), CSS will be used to draw table borders.
Table of Contents
qanda.defaultlabel — Sets the default for defaultlabel on QandASet.
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.
Table of Contents
link.mailto.url — Mailto URL for the LINK REL=made HTML HEAD element
If not the empty string, this address will be used for the REL=made LINK element in the HTML HEAD.
ulink.target — The HTML anchor target for ULinks
If ulink.target is set, its value will be used for the target attribute on anchors generated for ulinks.
olink.fragid — Names the fragment identifier portion of an OLink resolver query
FIXME:
olink.pubid — Names the public identifier portion of an OLink resolver query
FIXME:
olink.sysid — Names the system identifier portion of an OLink resolver query
FIXME:
Table of Contents
biblioentry.item.separator — Text to separate bibliography entries
Text to separate bibliography entries
bibliography.collection — Name of the bibliography collection file
|
§101: §129 |
<xsl:param name="bibliography.collection"
select="'http://docbook.sourceforge.net/release/bibliography/bibliography.xml'"/>
|
Tired of copying bibliography entries from one document to another? Now you can maintain a central bibliography and let the stylesheets do the copying for you. This parameter identifies the file (by URI reference) that contains your complete bibliography collection.
Table of Contents
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.procedures — Selects formal or informal procedures
Formal procedures are numbered and always hav a title.
runinhead.default.title.end.punct — Default punctuation character on a run-in-head
FIXME:
runinhead.title.end.punct — Characters that count as punctuation on a run-in-head
FIXME:
show.comments — Display comment elements?
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.
show.revisionflag — Enable decoration of elements that have a revisionflag
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.
shade.verbatim.style — Properties that specify the style of shaded verbatim listings
|
§109: §129 |
<xsl:attribute-set name="shade.verbatim.style"> <xsl:attribute name="border">0</xsl:attribute> <xsl:attribute name="bgcolor">#E0E0E0</xsl:attribute> </xsl:attribute-set> |
FIXME:
Table of Contents
html.ext — Identifies the extension of generated HTML files
The extension identified by html.ext will be used as the filename extension for chunks created by this stylesheet.
root.filename — Identifies the name of the root HTML file when chunking
The root.filename is the base filename for the chunk created for the root of each document processed.
base.dir — The base directory of chunks
If specified, the base.dir identifies the output directory for chunks. (If not specified, the output directory is system dependent.)
chunk.sections — Should top-level sections be chunks in their own right?
If non-zero, chunks will be created for top-level sect1 and section elements in each component.
chunk.first.sections — Chunk the first top-level section?
If non-zero, a chunk will be created for the first top-level sect1 or section elements in each component. Otherwise, that section will be part of the chunk for its parent.
saxon.character.representation — Saxon character representation used in generated HTML pages
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.
default.encoding — Encoding used in generated HTML pages
This encoding is used in files generated by chunking stylesheet. Currently only Saxon is able to change output encoding.
chunk.datafile — Name of the temporary file used to hold chunking data
Chunking is now a two-step process. The chunk.datafile is the name of the file used to hold the chunking data.
navig.graphics — Use graphics in navigational headers and footers?
If true (non-zero), the navigational headers and footers in chunked HTML are presented in an alternate style that uses graphical icons for Next, Previous, Up, and Home. Default graphics are provided in the distribution.
navig.graphics.extension — Extension for navigational graphics
Sets the filename extension to use on navigational graphics used in the headers and footers of chunked HTML.
navig.graphics.path — Path to navigational graphics
Sets the path, probably relative to the directory where the HTML files are created, to the navigational graphics used in the headers and footers of chunked HTML.
navig.showtitles — Display titles in HTML headers and footers?
If true (non-zero), the headers and footers of chunked HTML display the titles of the next and previous chunks, along with the words 'Next' and 'Previous' (or the equivalent graphical icons if navig.graphics is true). If false (zero), then only the words 'Next' and 'Previous' (or the icons) are displayed.
Table of Contents
htmlhelp.encoding — Character encoding to use in files for HTML Help compiler.
HTML Help Compiler is not UTF-8 aware, so you should always use apropriate single-byte encoding here.
htmlhelp.autolabel — Should tree-like ToC use autonumbering feature?
If you want to include chapter and section numbers into ToC in the left panel, set this parameter to 1.
htmlhelp.chm — Filename of output HTML Help file.
Change this parameter if you want different name of result CHM file than htmlhelp.chm.
htmlhelp.hhp — Filename of project file.
Change this parameter if you want different name of project file than htmlhelp.hhp.
htmlhelp.hhc — Filename of TOC file.
Change this parameter if you want different name of TOC file than toc.hhc.
htmlhelp.hhp.tail — Additional content for project file.
If you want to include some additional parameters into project file, store appropriate part of project file into this parameter.
The param.xsl stylesheet is just a wrapper around all these parameters.