# Common » Character-Map Template Reference

$Id: charmap.xsl 7266 2007-08-22 11:58:42Z xmldoc $

# Introduction

This is technical reference documentation for the character-map templates in the DocBook XSL Stylesheets.

These templates are defined in a separate file from the set of “common” templates because some of the common templates reference DocBook XSL stylesheet parameters, requiring the entire set of parameters to be imported/included in any stylesheet that imports/includes the common templates.

The character-map templates don’t import or include any DocBook XSL stylesheet parameters, so the character-map templates can be used without importing the whole set of parameters.

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

# apply-character-map

Applies an XSLT character map

    <xsl:template name="apply-character-map">
    <xsl:param name="content"/>
    <xsl:param name="map.contents"/>
      ...
    </xsl:template>

## Description

This template applies an XSLT character map; that is, it causes certain individual characters to be substituted with strings of one or more characters. It is useful mainly for replacing multiple “special” characters or symbols in the same target content. It uses the value of `map.contents` to do substitution on `content`, and then returns the modified contents.

This template is a very slightly modified version of Jeni Tennison’s `replace_strings` template in the multiple string replacements section of Dave Pawson’s XSLT FAQ.

The `apply-string-subst-map` template is essentially the same template as the `apply-character-map` template; the only difference is that in the map that `apply-string-subst-map` expects, `oldstring` and `newstring` attributes are used instead of `character` and `string` attributes.

## Parameters

content

  The content on which to perform the character-map substitution.

map.contents

  A node set of elements, with each element having the following attributes:

  - `character`, a character to be replaced

  - `string`, a string with which to replace `character`

# read-character-map

Reads in all or part of an XSLT character map

    <xsl:template name="read-character-map">
    <xsl:param name="use.subset"/>
    <xsl:param name="subset.profile"/>
    <xsl:param name="uri"/>
      ...
    </xsl:template>

## Description

The XSLT 2.0 specification describes character maps and explains how they may be used to allow a specific character appearing in a text or attribute node in a final result tree to be substituted by a specified string of characters during serialization. The `read-character-map` template provides a means for reading and using character maps with XSLT 1.0-based tools.

This template reads the character-map contents from `uri` (in full or in part, depending on the value of the `use.subset` parameter), then passes those contents to the `apply-character-map` template, along with `content`, the data on which to perform the character substitution.

Using the character map “in part” means that it uses only those `output-character` elements that match the XPath expression given in the value of the `subset.profile` parameter. The current implementation of that capability here relies on the `evaluate` extension XSLT function.

## Parameters

use.subset

  Specifies whether to use a subset of the character map instead of the whole map; boolean `0` or `1`

subset.profile

  XPath expression that specifies what subset of the character map to use

uri

  URI for a character map