# Common » Base Template Reference

$Id: common.xsl 8274 2009-02-27 07:02:45Z bobstayton $

# Introduction

This is technical reference documentation for the “base” set of common templates in the DocBook XSL Stylesheets.

This is not intended to be user documentation. It is provided for developers writing customization layers for the stylesheets.

# is.component

Tests if a given node is a component-level element

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

## Description

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

Tests if a given node is a section-level element

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

## Description

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

Returns the hierarchical level of a section

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

## Description

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.

# qanda.section.level

Returns the hierarchical level of a QandASet

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

## Description

This template calculates the hierarchical level of a QandASet.

## Returns

The level, 1, 2, etc.

# select.mediaobject

Selects and processes an appropriate media object from a list

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

## Description

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.

# select.mediaobject.index

Selects the position of the appropriate media object from a list

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

## Description

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.

# is.acceptable.mediaobject

Returns '1' if the specified media object is recognized

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

## Description

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

Warn users about references to non-unique IDs

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

## Description

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

Warn users about incorrectly typed references

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

## Description

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.

# copyright.years

Print a set of years with collapsed ranges

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

## Description

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.

# find.path.params

Search in a table for the "best" match for the node

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

## Description

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.

# string.upper

Converts a string to all uppercase letters

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

## Description

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.

# string.lower

Converts a string to all lowercase letters

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

## Description

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.

# select.choice.separator

Returns localized choice separator

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

## Description

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

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

# evaluate.info.profile

Evaluates an info profile

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

## Description

This template 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)