HTML EBNF Reference

Norman Walsh

$Id: ebnf.xsl,v 1.4 2000/10/19 20:55:37 ndw Exp $

Introduction

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 the templates and parameters relevant to formatting EBNF markup.

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

Library Template Reference
Common Template Reference
add-empty-entries
entry.colnum
HTML Parameter Reference
ebnf.table.bgcolor
ebnf.table.border

Library Template Reference

Norman Walsh

$Id: lib.xsl,v 1.4 2000/10/19 20:56:08 ndw Exp $

Introduction

This is technical reference documentation for the DocBook XSL Stylesheets; it documents (some of) the parameters, templates, and other elements of the stylesheets.

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

xpointer.idref

xpointer.idref

Name

xpointer.idref — Extract IDREF from an XPointer

Synopsis

<xsl:template name="xpointer.idref">
<xsl:param name="xpointer">http://...</xsl:param>
  ...
</xsl:template>

The xpointer.idref template returns the ID portion of an XPointer which is a pointer to an ID within the current document, or the empty string if it is not.

In other words, xpointer.idref returns “foo” when passed either #foo or #xpointer(id('foo')), otherwise it returns the empty string.

Common Template Reference

Norman Walsh

$Id: common.xsl,v 1.9 2000/10/30 20:17:21 ndw Exp $

Introduction

This is technical reference documentation for the DocBook XSL Stylesheets; it documents (some of) the parameters, templates, and other elements of the stylesheets.

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 :-)


is.component

Name

is.component — Tests if a given node is a component-level element

Synopsis

<xsl:template name="is.component">
<xsl:param name="node" select="."/>
  ...
</xsl:template>

This template returns '1' if the specified node is a component (Chapter, Appendix, etc.), and '0' otherwise.

Parameters
node

The node which is to be tested.

Returns

This template returns '1' if the specified node is a component (Chapter, Appendix, etc.), and '0' otherwise.


is.section

Name

is.section — Tests if a given node is a section-level element

Synopsis

<xsl:template name="is.section">
<xsl:param name="node" select="."/>
  ...
</xsl:template>

This template returns '1' if the specified node is a section (Section, Sect1, Sect2, etc.), and '0' otherwise.

Parameters
node

The node which is to be tested.

Returns

This template returns '1' if the specified node is a section (Section, Sect1, Sect2, etc.), and '0' otherwise.


section.level

Name

section.level — Returns the hierarchical level of a section.

Synopsis

<xsl:template name="section.level">
<xsl:param name="node" select="."/>
  ...
</xsl:template>

This template calculates the hierarchical level of a section. Hierarchically, components are “top level”, so a sect1 is at level 2, sect3 is at level 3, etc.

Recursive sections are calculated down to the sixth level.

Parameters
node

The section node for which the level should be calculated. Defaults to the context node.

Returns

The section level, “2”, “3”, etc.


qanda.section.level

Name

qanda.section.level — Returns the hierarchical level of a QandASet.

Synopsis

<xsl:template name="qanda.section.level"/>

This template calculates the hierarchical level of a QandASet.

Returns

The level, “1”, “2”, etc.


label.content mode

Name

label.content mode — Provides access to element labels

Processing an element in the label.content mode produces the element label.

If the label is non-null, either because the label attribute was present on the element or the stylesheet automatically generated a label, trailing punctuation is automatically added.


label.this.section

Name

label.this.section — Returns true if $section should be labelled

Synopsis

<xsl:template name="label.this.section">
<xsl:param name="section" select="."/>
  ...
</xsl:template>

Returns true if the specified section should be labelled. By default, this template simply returns $section.autolabel, but custom stylesheets may override it to get more selective behavior.


title.content mode

Name

title.content mode — Provides access to element titles

Processing an element in the title.content mode produces the title of the element. This does not include the label. If text-only is true, the text of the title is returned, without inline markup, otherwise inline markup is processed (in the default mode). By default, text-only is false.


subtitle.content mode

Name

subtitle.content mode — Provides access to element subtitles

Processing an element in the subtitle.content mode produces the subtitle of the element. If text-only is true, the text of the title is returned, without inline markup, otherwise inline markup is processed (in the default mode). By default, text-only is false.


title.ref mode

Name

title.ref mode — Provides reference text for an element

Processing an element in the title.ref mode produces the label and title of the element. If text-only is true, the text of the title is returned, without inline markup, otherwise inline markup is processed (in the default mode). By default, text-only is false.


select.mediaobject

Name

select.mediaobject — Selects an appropriate media object from a list

Synopsis

<xsl:template name="select.mediaobject">
<xsl:param name="olist" select="imageobject|videoobject|audioobject|textobject"/>
<xsl:param name="count">1</xsl:param>
  ...
</xsl:template>

This template examines a list of media objects (usually the children of a mediaobject or inlinemediaobject) and processes the "right" object.

This template relies on a template named "is.acceptable.mediaobject" to determine if a given object is an acceptable graphic. The semantics of media objects is that the first acceptable graphic should be used.

If no acceptable object is located, nothing happens.

Parameters
olist

The node list of potential objects to examine.

Returns

Calls <xsl:apply-templates> on the selected object.


is.acceptable.mediaobject

Name

is.acceptable.mediaobject — Returns '1' if the specified media object is recognized.

Synopsis

<xsl:template name="is.acceptable.mediaobject">
<xsl:param name="object"/>
  ...
</xsl:template>

This template examines a media object and returns '1' if the object is recognized as a graphic.

Parameters
object

The media object to consider.

Returns

0 or 1


check.id.unique

Name

check.id.unique — Warn users about references to non-unique IDs

Synopsis

<xsl:template name="check.id.unique">
<xsl:param name="linkend"/>
  ...
</xsl:template>

If passed an ID in linkend, check.id.unique prints a warning message to the user if either the ID does not exist or the ID is not unique.


check.idref.targets

Name

check.idref.targets — Warn users about incorrectly typed references

Synopsis

<xsl:template name="check.idref.targets">
<xsl:param name="linkend"/>
<xsl:param name="element-list"/>
  ...
</xsl:template>

If passed an ID in linkend, check.idref.targets makes sure that the element pointed to by the link is one of the elements listed in element-list and warns the user otherwise.


add-empty-entries

Name

add-empty-entries — Insert empty TDs into a table row

Synopsis

<xsl:template name="add-empty-entries">
<xsl:param name="number" select="'0'"/>
  ...
</xsl:template>

This template inserts empty TDs into a table row.

Parameters
number

The number of empty TDs to add.

Returns

Nothing


entry.colnum

Name

entry.colnum — Determine the column number in which a given entry occurs

Synopsis

<xsl:template name="entry.colnum">
<xsl:param name="entry" select="."/>
  ...
</xsl:template>

If an entry has a colname or namest attribute, this template will determine the number of the column in which the entry should occur. For other entrys, nothing is returned.

Parameters
entry

The entry-element which is to be tested.

Returns

This template returns the column number if it can be determined, or nothing (the empty string)

HTML Parameter Reference

Norman Walsh

$Id: param.xsl,v 1.7 2000/10/26 01:04:25 ndw Exp $

Introduction

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"/>

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="''"/>

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">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"/>

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.


refentry.xref.manvolnum

Name

refentry.xref.manvolnum — Output manvolnum as part of refentry cross-reference?

Synopsis

<xsl:param name="refentry.xref.manvolnum" select="1"/>

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">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">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"/>

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">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"/>

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"/>

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">../images/</xsl:param>

Sets the path, probably relative to the directory where the HTML files are created, to the admonition graphics.


admon.style

Name

admon.style — CSS style attributes for admonitions

Synopsis

<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.


section.autolabel

Name

section.autolabel — Are sections enumerated?

Synopsis

<xsl:param name="section.autolabel" select="0"/>

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"/>

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"/>

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"/>

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"/>

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"/>

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"/>

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">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">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">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">. </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">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"/>

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"/>

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"/>

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"/>

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"/>

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">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">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">1</xsl:param>

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">1</xsl:param>

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.


mode

Name

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">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">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">0</xsl:param>

If suppress.navigation is turned on, header and footer navigation will be suppressed.


ebnf.table.bgcolor

Name

ebnf.table.bgcolor — Background color for EBNF tables

Synopsis

<xsl:param name="ebnf.table.bgcolor">#F5DCB3</xsl:param>

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.


ebnf.table.border

Name

ebnf.table.border — Selects border on EBNF tables

Synopsis

<xsl:param name="ebnf.table.border">1</xsl:param>

Selects the border on EBNF tables. If non-zero, the tables have borders, otherwise they don't.