Common Template Reference

Norman Walsh

$Id: common.xsl,v 1.13 2001/01/28 12:59:59 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.

Parameters
text-only

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.

label-wrapper

If label-wrapper is not the emtpy string, it must be the name of an element. The element so named will be wrapped around labels on output.

title-wrapper

If title.wrapper is not the emtpy string, it must be the name of an element. The element so named will be wrapped around titles on output.

label-wrapper-class

If a label-wrapper is provided and label-wrapper-class is not the emtpy string, it be used as the value for a class attribute on the label-wrapper element.

This is a dirty hack because it only makes sense for the HTML stylesheet (there's no class attribute on the FO elements). What I'd really like to do is pass an attribute set as a parameter, but I can't.

title-wrapper-class

If a title-wrapper is provided and title-wrapper-class is not the emtpy string, it be used as the value for a class attribute on the title-wrapper element.

This is a dirty hack because it only makes sense for the HTML stylesheet (there's no class attribute on the FO elements). What I'd really like to do is pass an attribute set as a parameter, but I can't.


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