Common Template Reference

Norman Walsh

$Id: common.xsl 6232 2006-09-01 00:16:45Z xmldoc $


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

is.component — Tests if a given node is a component-level element
is.section — Tests if a given node is a section-level element
section.level — Returns the hierarchical level of a section
qanda.section.level — Returns the hierarchical level of a QandASet
select.mediaobject — Selects and processes an appropriate media object from a list
select.mediaobject.index — Selects the position of the appropriate media object from a list
is.acceptable.mediaobject — Returns '1' if the specified media object is recognized
check.id.unique — Warn users about references to non-unique IDs
check.idref.targets — Warn users about incorrectly typed references
copyright.years — Print a set of years with collapsed ranges
find.path.params — Search in a table for the "best" match for the node
string.upper — Converts a string to all uppercase letters
string.lower — Converts a string to all lowercase letters
select.choice.separator — Returns localized choice separator
evaluate.info.profile — Evaluates an info profile
log.message — Logs/emits formatted notes and warnings

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.


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.


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. The element sect1 is at level 1, sect2 is at level 2, etc.

Recursive sections are calculated down to the fifth level.

Parameters
node

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

Returns

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


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.


Name

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

Synopsis

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

This template takes 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 "select.mediaobject.index" to determine which object in the list is appropriate.

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.


Name

select.mediaobject.index — Selects the position of the appropriate media object from a list

Synopsis

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

This template takes a list of media objects (usually the children of a mediaobject or inlinemediaobject) and determines the "right" object. It returns the position of that object to be used by the calling template.

If the parameter use.role.for.mediaobject is nonzero, then it first checks for an object with a role attribute of the appropriate value. It takes the first of those. Otherwise, it takes the first acceptable object through a recursive pass through the list.

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, no index is returned.

Parameters
olist

The node list of potential objects to examine.

count

The position in the list currently being considered by the recursive process.

Returns

Returns the position in the original list of the selected object.


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


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.


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.


Name

copyright.years — Print a set of years with collapsed ranges

Synopsis

<xsl:template name="copyright.years">
<xsl:param name="years"/>
<xsl:param name="print.ranges" select="1"/>
<xsl:param name="single.year.ranges" select="0"/>
<xsl:param name="firstyear" select="0"/>
<xsl:param name="nextyear" select="0"/>
  ...
</xsl:template>

This template prints a list of year elements with consecutive years printed as a range. In other words:

<year>1992</year>
<year>1993</year>
<year>1994</year>

is printed “1992-1994”, whereas:

<year>1992</year>
<year>1994</year>

is printed “1992, 1994”.

This template assumes that all the year elements contain only decimal year numbers, that the elements are sorted in increasing numerical order, that there are no duplicates, and that all the years are expressed in full “century+year” (“1999” not “99”) notation.

Parameters
years

The initial set of year elements.

print.ranges

If non-zero, multi-year ranges are collapsed. If zero, all years are printed discretely.

single.year.ranges

If non-zero, two consecutive years will be printed as a range, otherwise, they will be printed discretely. In other words, a single year range is “1991-1992” but discretely it's “1991, 1992”.

Returns

This template returns the formatted list of years.


Name

find.path.params — Search in a table for the "best" match for the node

Synopsis

<xsl:template name="find.path.params">
<xsl:param name="node" select="."/>
<xsl:param name="table" select="''"/>
<xsl:param name="location">
    <xsl:call-template name="xpath.location">
      <xsl:with-param name="node" select="$node"/>
    </xsl:call-template>
  </xsl:param>
  ...
</xsl:template>

This template searches in a table for the value that most-closely (in the typical best-match sense of XSLT) matches the current (element) node location.


Name

string.upper — Converts a string to all uppercase letters

Synopsis

<xsl:template name="string.upper">
<xsl:param name="string" select="''"/>
  ...
</xsl:template>

Given a string, this template does a language-aware conversion of that string to all uppercase letters, based on the values of the lowercase.alpha and uppercase.alpha gentext keys for the current locale. It affects only those characters found in the values of lowercase.alpha and uppercase.alpha. All other characters are left unchanged.

Parameters
string

The string to convert to uppercase.


Name

string.lower — Converts a string to all lowercase letters

Synopsis

<xsl:template name="string.lower">
<xsl:param name="string" select="''"/>
  ...
</xsl:template>

Given a string, this template does a language-aware conversion of that string to all lowercase letters, based on the values of the uppercase.alpha and lowercase.alpha gentext keys for the current locale. It affects only those characters found in the values of uppercase.alpha and lowercase.alpha. All other characters are left unchanged.

Parameters
string

The string to convert to lowercase.


Name

select.choice.separator — Returns localized choice separator

Synopsis

<xsl:template name="select.choice.separator"/>

This template enables auto-generation of an appropriate localized "choice" separator (for example, "and" or "or") before the final item in an inline list (though it could also be useful for generating choice separators for non-inline lists).

It currently works by evaluating a processing instruction (PI) of the form <?dbchoice choice="foo"?> :

  • if the value of the choice pseudo-attribute is "and" or "or", returns a localized "and" or "or"
  • otherwise returns the literal value of the choice pseudo-attribute

The latter is provided only as a temporary workaround because the locale files do not currently have translations for the word or. So if you want to generate a a logical "or" separator in French (for example), you currently need to do this:

<?dbchoice choice="ou"?>

[Warning]

The dbchoice processing instruction is an unfortunate hack; support for it may disappear in the future (particularly if and when a more appropriate means for marking up "choice" lists becomes available in DocBook).


Name

evaluate.info.profile — Evaluates an info profile

Synopsis

<xsl:template name="evaluate.info.profile">
<xsl:param name="profile"/>
<xsl:param name="info"/>
  ...
</xsl:template>

This function evaluates an "info profile" matching the XPath expression given by the profile parameter. It relies on the XSLT evaluate() extension function.

The value of the profile parameter can include the literal string $info. If found in the value of the profile parameter, the literal string $info string is replaced with the value of the info parameter, which should be a set of *info nodes; the expression is then evaluated using the XSLT evaluate() extension function.

Parameters
profile

A string representing an XPath expression

info

A set of *info nodes

Returns

Returns a node (the result of evaluating the profile parameter)


Name

log.message — Logs/emits formatted notes and warnings

Synopsis

<xsl:template name="log.message">
<xsl:param name="level"/>
<xsl:param name="source"/>
<xsl:param name="message"/>
<xsl:param name="message-width">50</xsl:param>
  ...
</xsl:template>

The log.message function is a utility function for logging/emitting formatted messages – that is, notes and warnings, along with a given log "level" and an identifier for the "source" that the message relates to.

Parameters
level

Text to indicate the message level (Note or Warning)

source

Text to identify source element the notification/warning relates to

message

Message to lot/emit

message-width

Expected maximum message width

Returns

Outputs a message (generally, to standard error).