<?xml version="1.0" encoding="utf-8"?>
<!-- This file was generated by weave.xsl version 0.00+. Do not edit! -->
<!-- See http://sourceforge.net/projects/docbook/ -->
<!DOCTYPE book
  PUBLIC "-//DocBook Open Repository//DTD DocBook Literate Programming V0.0//EN" "http://docbook.sourceforge.net/release/litprog/current/dtd/ldocbook.dtd">
<book xmlns:src="http://nwalsh.com/xmlns/litprog/fragment" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<bookinfo>
<title>XSL Library Template Reference</title>
<releaseinfo role="cvs">$Id: lib.xml,v 1.1.1.1 2004/06/22 02:10:38 f8dy Exp $
</releaseinfo>
<corpauthor>DocBook Open Repository Team</corpauthor>
<copyright>
  <year>1999</year>
  <year>2000</year>
  <year>2001</year>
  <year>2002</year>
  <holder>Norman Walsh</holder>
</copyright>
</bookinfo>

<preface><title>Introduction</title>

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

<para>This is not intended to be <quote>user</quote> documentation.
It is provided for developers writing customization layers for the
stylesheets, and for anyone who's interested in <quote>how it
works</quote>.</para>

<para>Although I am trying to be thorough, this documentation is known
to be incomplete. Don't forget to read the source, too :-)</para>

</preface>

<reference>
<title>General Library Templates</title>

<refentry id="dot.count">
<refnamediv>
<refname>dot.count</refname>
<refpurpose>Returns the number of <quote>.</quote> characters in a string</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<programlisting format="linespecific"><src:fragment id="dot.count.frag">&lt;xsl:template name="dot.count"&gt;
  &lt;!-- Returns the number of "." characters in a string --&gt;
  &lt;xsl:param name="string"/&gt;
  &lt;xsl:param name="count"
             select="0"/&gt;
  &lt;xsl:choose&gt;
    &lt;xsl:when test="contains($string, '.')"&gt;
      &lt;xsl:call-template name="dot.count"&gt;
        &lt;xsl:with-param name="string"
                        select="substring-after($string, '.')"/&gt;
        &lt;xsl:with-param name="count"
                        select="$count+1"/&gt;
      &lt;/xsl:call-template&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:otherwise&gt;
      &lt;xsl:value-of select="$count"/&gt;
    &lt;/xsl:otherwise&gt;
  &lt;/xsl:choose&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>

</refsect1>
</refentry>

<!-- ================================================================== -->

<refentry id="copy-string">
<refnamediv>
<refname>copy-string</refname>
<refpurpose>Returns <quote>count</quote> copies of a string</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<programlisting format="linespecific"><src:fragment id="copy-string.frag">&lt;xsl:template name="copy-string"&gt;
  &lt;!-- returns 'count' copies of 'string' --&gt;
  &lt;xsl:param name="string"/&gt;
  &lt;xsl:param name="count"
             select="0"/&gt;
  &lt;xsl:param name="result"/&gt;

  &lt;xsl:choose&gt;
    &lt;xsl:when test="$count&gt;0"&gt;
      &lt;xsl:call-template name="copy-string"&gt;
        &lt;xsl:with-param name="string"
                        select="$string"/&gt;
        &lt;xsl:with-param name="count"
                        select="$count - 1"/&gt;
        &lt;xsl:with-param name="result"&gt;
          &lt;xsl:value-of select="$result"/&gt;
          &lt;xsl:value-of select="$string"/&gt;
        &lt;/xsl:with-param&gt;
      &lt;/xsl:call-template&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:otherwise&gt;
      &lt;xsl:value-of select="$result"/&gt;
    &lt;/xsl:otherwise&gt;
  &lt;/xsl:choose&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>

</refsect1>
</refentry>

<!-- ====================================================================== -->

<refentry id="string.subst">
<refnamediv>
<refname>string.subst</refname>
<refpurpose>Substitute one text string for another in a string</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<para>The <function moreinfo="none">string.subst</function> template replaces all
occurances of <parameter moreinfo="none">target</parameter> in <parameter moreinfo="none">string</parameter>
with <parameter moreinfo="none">replacement</parameter> and returns the result.
</para>

<programlisting format="linespecific"><src:fragment id="string.subst.frag">&lt;xsl:template name="string.subst"&gt;
  &lt;xsl:param name="string"/&gt;
  &lt;xsl:param name="target"/&gt;
  &lt;xsl:param name="replacement"/&gt;

  &lt;xsl:choose&gt;
    &lt;xsl:when test="contains($string, $target)"&gt;
      &lt;xsl:variable name="rest"&gt;
        &lt;xsl:call-template name="string.subst"&gt;
          &lt;xsl:with-param name="string"
                          select="substring-after($string, $target)"/&gt;
          &lt;xsl:with-param name="target"
                          select="$target"/&gt;
          &lt;xsl:with-param name="replacement"
                          select="$replacement"/&gt;
        &lt;/xsl:call-template&gt;
      &lt;/xsl:variable&gt;
      &lt;xsl:value-of select="concat(substring-before($string, $target),                                    $replacement,                                    $rest)"/&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:otherwise&gt;
      &lt;xsl:value-of select="$string"/&gt;
    &lt;/xsl:otherwise&gt;
  &lt;/xsl:choose&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>

</refsect1>
</refentry>

<!-- ================================================================== -->

<refentry id="xpointer.idref">
<refnamediv>
<refname>xpointer.idref</refname>
<refpurpose>Extract IDREF from an XPointer</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<para>The <function moreinfo="none">xpointer.idref</function> 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.</para>
<para>In other words, <function moreinfo="none">xpointer.idref</function> returns
<quote>foo</quote> when passed either <literal moreinfo="none">#foo</literal>
or <literal moreinfo="none">#xpointer(id('foo'))</literal>, otherwise it returns
the empty string.</para>

<programlisting format="linespecific"><src:fragment id="xpointer.idref.frag">&lt;xsl:template name="xpointer.idref"&gt;
  &lt;xsl:param name="xpointer"&gt;http://...&lt;/xsl:param&gt;
  &lt;xsl:choose&gt;
    &lt;xsl:when test="starts-with($xpointer, '#xpointer(id(')"&gt;
      &lt;xsl:variable name="rest"
                    select="substring-after($xpointer, '#xpointer(id(')"/&gt;
      &lt;xsl:variable name="quote"
                    select="substring($rest, 1, 1)"/&gt;
      &lt;xsl:value-of select="substring-before(substring-after($xpointer, $quote), $quote)"/&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:when test="starts-with($xpointer, '#')"&gt;
      &lt;xsl:value-of select="substring-after($xpointer, '#')"/&gt;
    &lt;/xsl:when&gt;
    &lt;!-- otherwise it's a pointer to some other document --&gt;
  &lt;/xsl:choose&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>

</refsect1>
</refentry>


<!-- ================================================================== -->

<refentry id="length-magnitude">
<refnamediv>
<refname>length-magnitude</refname>
<refpurpose>Return the unqualified dimension from a length specification</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<para>The <function moreinfo="none">length-magnitude</function> template returns the
unqualified length ("20" for "20pt") from a dimension.
</para>

<programlisting format="linespecific"><src:fragment id="length-magnitude.frag">&lt;xsl:template name="length-magnitude"&gt;
  &lt;xsl:param name="length"
             select="'0pt'"/&gt;

  &lt;xsl:choose&gt;
    &lt;xsl:when test="string-length($length) = 0"/&gt;
    &lt;xsl:when test="substring($length,1,1) = '0'                     or substring($length,1,1) = '1'                     or substring($length,1,1) = '2'                     or substring($length,1,1) = '3'                     or substring($length,1,1) = '4'                     or substring($length,1,1) = '5'                     or substring($length,1,1) = '6'                     or substring($length,1,1) = '7'                     or substring($length,1,1) = '8'                     or substring($length,1,1) = '9'                     or substring($length,1,1) = '.'"&gt;
      &lt;xsl:value-of select="substring($length,1,1)"/&gt;
      &lt;xsl:call-template name="length-magnitude"&gt;
        &lt;xsl:with-param name="length"
                        select="substring($length,2)"/&gt;
      &lt;/xsl:call-template&gt;
    &lt;/xsl:when&gt;
  &lt;/xsl:choose&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>

</refsect1>
</refentry>

<!-- ================================================================== -->

<refentry id="length-units">
<refnamediv>
<refname>length-units</refname>
<refpurpose>Return the units from a length specification</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<para>The <function moreinfo="none">length-units</function> template returns the
units ("pt" for "20pt") from a length. If no units are supplied on the
length, the <parameter moreinfo="none">defauilt.units</parameter> are returned.</para>

<programlisting format="linespecific"><src:fragment id="length-units.frag">&lt;xsl:template name="length-units"&gt;
  &lt;xsl:param name="length"
             select="'0pt'"/&gt;
  &lt;xsl:param name="default.units"
             select="'px'"/&gt;
  &lt;xsl:variable name="magnitude"&gt;
    &lt;xsl:call-template name="length-magnitude"&gt;
      &lt;xsl:with-param name="length"
                      select="$length"/&gt;
    &lt;/xsl:call-template&gt;
  &lt;/xsl:variable&gt;

  &lt;xsl:variable name="units"&gt;
    &lt;xsl:value-of select="substring($length, string-length($magnitude)+1)"/&gt;
  &lt;/xsl:variable&gt;

  &lt;xsl:choose&gt;
    &lt;xsl:when test="$units = ''"&gt;
      &lt;xsl:value-of select="$default.units"/&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:otherwise&gt;
      &lt;xsl:value-of select="$units"/&gt;
    &lt;/xsl:otherwise&gt;
  &lt;/xsl:choose&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>

</refsect1>
</refentry>

<!-- ================================================================== -->

<refentry id="length-spec">
<refnamediv>
<refname>length-spec</refname>
<refpurpose>Return a fully qualified length specification</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<para>The <function moreinfo="none">length-spec</function> template returns the
qualified length from a dimension. If an unqualified length is given,
the <parameter moreinfo="none">default.units</parameter> will be added to it.
</para>

<programlisting format="linespecific"><src:fragment id="length-spec.frag">&lt;xsl:template name="length-spec"&gt;
  &lt;xsl:param name="length"
             select="'0pt'"/&gt;
  &lt;xsl:param name="default.units"
             select="'px'"/&gt;

  &lt;xsl:variable name="magnitude"&gt;
    &lt;xsl:call-template name="length-magnitude"&gt;
      &lt;xsl:with-param name="length"
                      select="$length"/&gt;
    &lt;/xsl:call-template&gt;
  &lt;/xsl:variable&gt;

  &lt;xsl:variable name="units"&gt;
    &lt;xsl:value-of select="substring($length, string-length($magnitude)+1)"/&gt;
  &lt;/xsl:variable&gt;

  &lt;xsl:value-of select="$magnitude"/&gt;
  &lt;xsl:choose&gt;
    &lt;xsl:when test="$units='cm'                     or $units='mm'                     or $units='in'                     or $units='pt'                     or $units='pc'                     or $units='px'                     or $units='em'"&gt;
      &lt;xsl:value-of select="$units"/&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:when test="$units = ''"&gt;
      &lt;xsl:value-of select="$default.units"/&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:otherwise&gt;
      &lt;xsl:message&gt;
        &lt;xsl:text&gt;Unrecognized unit of measure: &lt;/xsl:text&gt;
        &lt;xsl:value-of select="$units"/&gt;
        &lt;xsl:text&gt;.&lt;/xsl:text&gt;
      &lt;/xsl:message&gt;
    &lt;/xsl:otherwise&gt;
  &lt;/xsl:choose&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>

</refsect1>
</refentry>

<!-- ================================================================== -->

<refentry id="length-in-points">
<refnamediv>
<refname>length-in-points</refname>
<refpurpose>Returns the size, in points, of a specified length</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<para>The <function moreinfo="none">length-in-points</function> template converts a length
specification to points and returns that value as an unqualified
number.
</para>

<caution>
<para>There is no way for the template to infer the size of an
<literal moreinfo="none">em</literal>. It relies on the default <parameter moreinfo="none">em.size</parameter>
which is initially <literal moreinfo="none">10</literal> (for 10pt).</para>

<para>Similarly, converting pixesl to points relies on the
<parameter moreinfo="none">pixels.per.inch</parameter> parameter which is initially
<literal moreinfo="none">90</literal>.
</para>
</caution>

<programlisting format="linespecific"><src:fragment id="length-in-points.frag">&lt;xsl:template name="length-in-points"&gt;
  &lt;xsl:param name="length"
             select="'0pt'"/&gt;
  &lt;xsl:param name="em.size"
             select="10"/&gt;
  &lt;xsl:param name="pixels.per.inch"
             select="90"/&gt;

  &lt;xsl:variable name="magnitude"&gt;
    &lt;xsl:call-template name="length-magnitude"&gt;
      &lt;xsl:with-param name="length"
                      select="$length"/&gt;
    &lt;/xsl:call-template&gt;
  &lt;/xsl:variable&gt;

  &lt;xsl:variable name="units"&gt;
    &lt;xsl:value-of select="substring($length, string-length($magnitude)+1)"/&gt;
  &lt;/xsl:variable&gt;

  &lt;xsl:choose&gt;
    &lt;xsl:when test="$units = 'pt'"&gt;
      &lt;xsl:value-of select="$magnitude"/&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:when test="$units = 'cm'"&gt;
      &lt;xsl:value-of select="$magnitude div 2.54 * 72.0"/&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:when test="$units = 'mm'"&gt;
      &lt;xsl:value-of select="$magnitude div 25.4 * 72.0"/&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:when test="$units = 'in'"&gt;
      &lt;xsl:value-of select="$magnitude * 72.0"/&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:when test="$units = 'pc'"&gt;
      &lt;xsl:value-of select="$magnitude div 6.0 * 72.0"/&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:when test="$units = 'px'"&gt;
      &lt;xsl:value-of select="$magnitude div $pixels.per.inch * 72.0"/&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:when test="$units = 'em'"&gt;
      &lt;xsl:value-of select="$magnitude * $em.size"/&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:otherwise&gt;
      &lt;xsl:message&gt;
        &lt;xsl:text&gt;Unrecognized unit of measure: &lt;/xsl:text&gt;
        &lt;xsl:value-of select="$units"/&gt;
        &lt;xsl:text&gt;.&lt;/xsl:text&gt;
      &lt;/xsl:message&gt;
    &lt;/xsl:otherwise&gt;
  &lt;/xsl:choose&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>

</refsect1>
</refentry>

<!-- ================================================================== -->

<refentry id="pi-attribute">
<refnamediv>
<refname>pi-attribute</refname>
<refpurpose>Extract a pseudo-attribute from a PI</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<para>The <function moreinfo="none">pi-attribute</function> template extracts a pseudo-attribute
from a processing instruction. For example, given the PI
<quote><literal moreinfo="none">&lt;?foo bar="1" baz='red'?&gt;</literal></quote>,</para>
<programlisting format="linespecific">&lt;xsl:call-template name="pi-attribute"&gt;
  &lt;xsl:with-param name="pis" select="processing-instruction('foo')"/&gt;
  &lt;xsl:with-param name="attribute" select="'baz'"/&gt;
&lt;/xsl:call-template&gt;</programlisting>
<para>will return <quote>red</quote>. This template returns the first matching
attribute that it finds. Presented with processing instructions that
contain badly formed pseudo-attributes (missing or unbalanced quotes,
for example), the template may silently return erroneous results.</para>

<programlisting format="linespecific"><src:fragment id="pi-attribute.frag">&lt;xsl:template name="pi-attribute"&gt;
  &lt;xsl:param name="pis"
             select="processing-instruction('')"/&gt;
  &lt;xsl:param name="attribute"&gt;filename&lt;/xsl:param&gt;
  &lt;xsl:param name="count"&gt;1&lt;/xsl:param&gt;

  &lt;xsl:choose&gt;
    &lt;xsl:when test="$count&gt;count($pis)"&gt;
      &lt;!-- not found --&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:otherwise&gt;
      &lt;xsl:variable name="pi"&gt;
        &lt;xsl:value-of select="$pis[$count]"/&gt;
      &lt;/xsl:variable&gt;
      &lt;xsl:choose&gt;
        &lt;xsl:when test="contains($pi,concat($attribute, '='))"&gt;
          &lt;xsl:variable name="rest"
                        select="substring-after($pi,concat($attribute,'='))"/&gt;
          &lt;xsl:variable name="quote"
                        select="substring($rest,1,1)"/&gt;
          &lt;xsl:value-of select="substring-before(substring($rest,2),$quote)"/&gt;
        &lt;/xsl:when&gt;
        &lt;xsl:otherwise&gt;
          &lt;xsl:call-template name="pi-attribute"&gt;
            &lt;xsl:with-param name="pis"
                            select="$pis"/&gt;
            &lt;xsl:with-param name="attribute"
                            select="$attribute"/&gt;
            &lt;xsl:with-param name="count"
                            select="$count + 1"/&gt;
          &lt;/xsl:call-template&gt;
        &lt;/xsl:otherwise&gt;
      &lt;/xsl:choose&gt;
    &lt;/xsl:otherwise&gt;
  &lt;/xsl:choose&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>

</refsect1>
</refentry>

<!-- ================================================================== -->

<refentry id="lookup.key">
<refnamediv>
<refname>lookup.key</refname>
<refpurpose>Retrieve the value associated with a particular key in a table</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<para>Given a table of space-delimited key/value pairs,
the <function moreinfo="none">lookup.key</function> template extracts the value associated
with a particular key.</para>

<programlisting format="linespecific"><src:fragment id="lookup.key.frag">&lt;xsl:template name="lookup.key"&gt;
  &lt;xsl:param name="key"
             select="''"/&gt;
  &lt;xsl:param name="table"
             select="''"/&gt;

  &lt;xsl:if test="contains($table, ' ')"&gt;
    &lt;xsl:choose&gt;
      &lt;xsl:when test="substring-before($table, ' ') = $key"&gt;
        &lt;xsl:variable name="rest"
                      select="substring-after($table, ' ')"/&gt;
        &lt;xsl:choose&gt;
          &lt;xsl:when test="contains($rest, ' ')"&gt;
            &lt;xsl:value-of select="substring-before($rest, ' ')"/&gt;
          &lt;/xsl:when&gt;
          &lt;xsl:otherwise&gt;
            &lt;xsl:value-of select="$rest"/&gt;
          &lt;/xsl:otherwise&gt;
        &lt;/xsl:choose&gt;
      &lt;/xsl:when&gt;
      &lt;xsl:otherwise&gt;
        &lt;xsl:call-template name="lookup.key"&gt;
          &lt;xsl:with-param name="key"
                          select="$key"/&gt;
          &lt;xsl:with-param name="table"
                          select="substring-after(substring-after($table,' '), ' ')"/&gt;
        &lt;/xsl:call-template&gt;
      &lt;/xsl:otherwise&gt;
    &lt;/xsl:choose&gt;
  &lt;/xsl:if&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>

</refsect1>
</refentry>

<!-- ================================================================== -->

<refentry id="xpath.location">
<refnamediv>
<refname>xpath.location</refname>
<refpurpose>Calculate the XPath child-sequence to the current node</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<para>The <function moreinfo="none">xpath.location</function> template calculates the
absolute path from the root of the tree to the current element node.
</para>

<programlisting format="linespecific"><src:fragment id="xpath.location.frag">&lt;xsl:template name="xpath.location"&gt;
  &lt;xsl:param name="node"
             select="."/&gt;
  &lt;xsl:param name="path"
             select="''"/&gt;

  &lt;xsl:variable name="next.path"&gt;
    &lt;xsl:value-of select="local-name($node)"/&gt;
    &lt;xsl:if test="$path != ''"&gt;/&lt;/xsl:if&gt;
    &lt;xsl:value-of select="$path"/&gt;
  &lt;/xsl:variable&gt;

  &lt;xsl:choose&gt;
    &lt;xsl:when test="$node/parent::*"&gt;
      &lt;xsl:call-template name="xpath.location"&gt;
        &lt;xsl:with-param name="node"
                        select="$node/parent::*"/&gt;
        &lt;xsl:with-param name="path"
                        select="$next.path"/&gt;
      &lt;/xsl:call-template&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:otherwise&gt;
      &lt;xsl:text&gt;/&lt;/xsl:text&gt;
      &lt;xsl:value-of select="$next.path"/&gt;
    &lt;/xsl:otherwise&gt;
  &lt;/xsl:choose&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>

</refsect1>
</refentry>

<!-- ================================================================== -->

<refentry id="comment-escape-string">
<refnamediv>
<refname>comment-escape-string</refname>
<refpurpose>Prepare a string for inclusion in an XML comment</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<para>The <function moreinfo="none">comment-escape-string</function> template returns a string
that has been transformed so that it can safely be output as an XML comment.
Internal occurrences of "--" will be replaced with "- -" and a leading and/or
trailing space will be added to the string, if necessary.</para>

<programlisting format="linespecific"><src:fragment id="comment-escape-string">&lt;xsl:template name="comment-escape-string"&gt;
  &lt;xsl:param name="string"
             select="''"/&gt;

  &lt;xsl:if test="starts-with($string, '-')"&gt;
    &lt;xsl:text&gt; &lt;/xsl:text&gt;
  &lt;/xsl:if&gt;

  &lt;xsl:call-template name="comment-escape-string.recursive"&gt;
    &lt;xsl:with-param name="string"
                    select="$string"/&gt;
  &lt;/xsl:call-template&gt;

  &lt;xsl:if test="substring($string, string-length($string), 1) = '-'"&gt;
    &lt;xsl:text&gt; &lt;/xsl:text&gt;
  &lt;/xsl:if&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>

</refsect1>
</refentry>

<refentry id="comment-escape-string.recursive">
<refnamediv>
<refname>comment-escape-string.recursive</refname>
<refpurpose>Internal function used by comment-escape-string</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<para>The <function moreinfo="none">comment-escape-string.recursive</function> template is used
by <function moreinfo="none">comment-escape-string</function>.</para>

<programlisting format="linespecific"><src:fragment id="comment-escape-string.recursive">&lt;xsl:template name="comment-escape-string.recursive"&gt;
  &lt;xsl:param name="string"
             select="''"/&gt;
  &lt;xsl:choose&gt;
    &lt;xsl:when test="contains($string, '--')"&gt;
      &lt;xsl:value-of select="substring-before($string, '--')"/&gt;
      &lt;xsl:value-of select="'- -'"/&gt;
      &lt;xsl:call-template name="comment-escape-string.recursive"&gt;
        &lt;xsl:with-param name="string"
                        select="substring-after($string, '--')"/&gt;
      &lt;/xsl:call-template&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:otherwise&gt;
      &lt;xsl:value-of select="$string"/&gt;
    &lt;/xsl:otherwise&gt;
  &lt;/xsl:choose&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>
</refsect1>
</refentry>

</reference>

<reference>
<title>Relative URI Functions</title>

<partintro><title>Introduction</title>

<para>These functions manipulate relative URI references.</para>

<para>The following assumptions must hold true:</para>

<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>All URIs are relative.</para>
</listitem>
<listitem>
<para>No URI contains the <quote><literal moreinfo="none">../</literal></quote> sequence
which would effectively move <quote>up</quote> the hierarchy.</para>
</listitem>
</orderedlist>

<para>If these assumptions do not hold, the results are unpredictable.</para>

</partintro>

<refentry id="count.uri.path.depth">
<refnamediv>
<refname>count.uri.path.depth</refname>
<refpurpose>Count the number of path components in a relative URI</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<para>This function counts the number of path components in a relative URI.</para>

<programlisting format="linespecific"><src:fragment id="count.uri.path.depth.frag">&lt;xsl:template name="count.uri.path.depth"&gt;
  &lt;xsl:param name="filename"
             select="''"/&gt;
  &lt;xsl:param name="count"
             select="0"/&gt;

  &lt;xsl:choose&gt;
    &lt;xsl:when test="contains($filename, '/')"&gt;
      &lt;xsl:call-template name="count.uri.path.depth"&gt;
        &lt;xsl:with-param name="filename"
                        select="substring-after($filename, '/')"/&gt;
        &lt;xsl:with-param name="count"
                        select="$count + 1"/&gt;
      &lt;/xsl:call-template&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:otherwise&gt;
      &lt;xsl:value-of select="$count"/&gt;
    &lt;/xsl:otherwise&gt;
  &lt;/xsl:choose&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>

</refsect1>
</refentry>

<refentry id="trim.common.uri.paths">
<refnamediv>
<refname>trim.common.uri.paths</refname>
<refpurpose>Trim common leading path components from a relative URI</refpurpose>
</refnamediv>

<refsect1><title>Description</title>

<para>This function trims common leading path components from a relative URI.</para>

<programlisting format="linespecific"><src:fragment id="trim.common.uri.paths.frag">&lt;xsl:template name="trim.common.uri.paths"&gt;
  &lt;xsl:param name="uriA"
             select="''"/&gt;
  &lt;xsl:param name="uriB"
             select="''"/&gt;
  &lt;xsl:param name="return"
             select="'A'"/&gt;

  &lt;xsl:choose&gt;
    &lt;xsl:when test="contains($uriA, '/') and contains($uriB, '/')                     and substring-before($uriA, '/') = substring-before($uriB, '/')"&gt;
      &lt;xsl:call-template name="trim.common.uri.paths"&gt;
        &lt;xsl:with-param name="uriA"
                        select="substring-after($uriA, '/')"/&gt;
        &lt;xsl:with-param name="uriB"
                        select="substring-after($uriB, '/')"/&gt;
        &lt;xsl:with-param name="return"
                        select="$return"/&gt;
      &lt;/xsl:call-template&gt;
    &lt;/xsl:when&gt;
    &lt;xsl:otherwise&gt;
      &lt;xsl:choose&gt;
        &lt;xsl:when test="$return = 'A'"&gt;
          &lt;xsl:value-of select="$uriA"/&gt;
        &lt;/xsl:when&gt;
        &lt;xsl:otherwise&gt;
          &lt;xsl:value-of select="$uriB"/&gt;
        &lt;/xsl:otherwise&gt;
      &lt;/xsl:choose&gt;
    &lt;/xsl:otherwise&gt;
  &lt;/xsl:choose&gt;
&lt;/xsl:template&gt;</src:fragment></programlisting>

</refsect1>
</refentry>

</reference>

<appendix><title>The Stylesheet</title>

<para>The <filename moreinfo="none">lib.xsl</filename> stylesheet is just a wrapper
around these functions.</para>

<src:fragment id="top">
&lt;!-- ********************************************************************
     $Id: lib.xml,v 1.1.1.1 2004/06/22 02:10:38 f8dy Exp $
     ********************************************************************

     This file is part of the XSL DocBook Stylesheet distribution.
     See ../README or http://nwalsh.com/docbook/xsl/ for copyright
     and other information.

     This module implements DTD-independent functions

     ******************************************************************** --&gt;

&lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                exclude-result-prefixes="src"
                version="1.0"&gt;

<src:fragref linkend="dot.count.frag"/>
<src:fragref linkend="copy-string.frag"/>
<src:fragref linkend="string.subst.frag"/>
<src:fragref linkend="xpointer.idref.frag"/>
<src:fragref linkend="length-magnitude.frag"/>
<src:fragref linkend="length-units.frag"/>
<src:fragref linkend="length-spec.frag"/>
<src:fragref linkend="length-in-points.frag"/>
<src:fragref linkend="pi-attribute.frag"/>
<src:fragref linkend="lookup.key.frag"/>
<src:fragref linkend="xpath.location.frag"/>
<src:fragref linkend="comment-escape-string"/>
<src:fragref linkend="comment-escape-string.recursive"/>
<src:fragref linkend="count.uri.path.depth.frag"/>
<src:fragref linkend="trim.common.uri.paths.frag"/>

&lt;/xsl:stylesheet&gt;</src:fragment>

</appendix>
</book>