git-scribe 0.0.3 → 0.0.4

data/docbook-xsl/common/charmap.xml

@@ -0,0 +1,185 @@
+<?xml version="1.0"?>
+
+<reference xml:id="charmap">
+  <info>
+    <title>Common » Character-Map Template Reference</title>
+    <releaseinfo role="meta">
+      $Id: charmap.xsl 7266 2007-08-22 11:58:42Z xmldoc $
+    </releaseinfo>
+  </info>
+  
+  <partintro xml:id="partintro">
+    <title>Introduction</title>
+    
+<para>This is technical reference documentation for the
+      character-map templates in the DocBook XSL Stylesheets.</para>
+
+    <note>
+      
+<para>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.</para>
+
+      
+<para>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.</para>
+
+    </note>
+    
+<para>This is not intended to be user documentation. It is
+      provided for developers writing customization layers for the
+      stylesheets.</para>
+
+  </partintro>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.apply-character-map">
+<refnamediv>
+<refname>apply-character-map</refname>
+<refpurpose>Applies an XSLT character map</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="apply-character-map"&gt;
+&lt;xsl:param name="content"/&gt;
+&lt;xsl:param name="map.contents"/&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+    
+<para>This template applies an <link xlink:href="http://www.w3.org/TR/xslt20/#character-maps">XSLT character map</link>; 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
+      <parameter>map.contents</parameter> to do substitution on
+      <parameter>content</parameter>, and then returns the
+      modified contents.</para>
+
+    <note>
+      
+<para>This template is a very slightly modified version of
+        Jeni Tennison’s <function>replace_strings</function>
+        template in the <link xlink:href="http://www.dpawson.co.uk/xsl/sect2/StringReplace.html#d9351e13">multiple string replacements</link> section of Dave Pawson’s
+        <link xlink:href="http://www.dpawson.co.uk/xsl/index.html">XSLT FAQ</link>.</para>
+
+      
+<para>The <function>apply-string-subst-map</function>
+        template is essentially the same template as the
+        <function>apply-character-map</function> template; the
+        only difference is that in the map that
+        <function>apply-string-subst-map</function> expects, <tag class="attribute">oldstring</tag> and <tag class="attribute">newstring</tag> attributes are used
+        instead of <tag class="attribute">character</tag> and <tag class="attribute">string</tag> attributes.</para>
+
+    </note>
+  </refsect1><refsect1><title>Parameters</title>
+    
+<variablelist>
+      <varlistentry><term>content</term>
+        <listitem>
+          
+<para>The content on which to perform the character-map
+            substitution.</para>
+
+        </listitem>
+      </varlistentry>
+      <varlistentry><term>map.contents</term>
+        <listitem>
+          
+<para>A node set of elements, with each element having
+            the following attributes:
+            
+<itemizedlist>
+              <listitem>
+                <simpara><tag class="attribute">character</tag>, a
+                  character to be replaced</simpara>
+              </listitem>
+              <listitem>
+                <simpara><tag class="attribute">string</tag>, a
+                  string with which to replace <tag class="attribute">character</tag></simpara>
+              </listitem>
+            </itemizedlist>
+
+          </para>
+
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+  </refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.read-character-map">
+<refnamediv>
+<refname>read-character-map</refname>
+<refpurpose>Reads in all or part of an XSLT character map</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="read-character-map"&gt;
+&lt;xsl:param name="use.subset"/&gt;
+&lt;xsl:param name="subset.profile"/&gt;
+&lt;xsl:param name="uri"/&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+    
+<para>The XSLT 2.0 specification describes <link xlink:href="http://www.w3.org/TR/xslt20/#character-maps">character maps</link> 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
+      <function>read-character-map</function> template provides a
+      means for reading and using character maps with XSLT
+      1.0-based tools.</para>
+
+    
+<para>This template reads the character-map contents from
+      <parameter>uri</parameter> (in full or in part, depending on
+      the value of the <parameter>use.subset</parameter>
+      parameter), then passes those contents to the
+      <function>apply-character-map</function> template, along with
+      <parameter>content</parameter>, the data on which to perform
+      the character substitution.</para>
+
+    
+<para>Using the character map “in part” means that it uses only
+      those <tag>output-character</tag> elements that match the
+      XPath expression given in the value of the
+      <parameter>subset.profile</parameter> parameter. The current
+      implementation of that capability here relies on the
+      <function>evaluate</function> extension XSLT function.</para>
+
+  </refsect1><refsect1><title>Parameters</title>
+    
+<variablelist>
+      <varlistentry><term>use.subset</term>
+        <listitem>
+          
+<para>Specifies whether to use a subset of the character
+            map instead of the whole map; boolean
+            <literal>0</literal> or <literal>1</literal></para>
+
+        </listitem>
+      </varlistentry>
+      <varlistentry><term>subset.profile</term>
+        <listitem>
+          
+<para>XPath expression that specifies what subset of the
+            character map to use</para>
+
+        </listitem>
+      </varlistentry>
+      <varlistentry><term>uri</term>
+        <listitem>
+          
+<para>URI for a character map</para>
+
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+  </refsect1></refentry>
+</reference>
+

data/docbook-xsl/common/charmap.xsl

@@ -0,0 +1,221 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:doc="http://nwalsh.com/xsl/documentation/1.0"
+                xmlns:dyn="http://exslt.org/dynamic"
+                xmlns:saxon="http://icl.com/saxon"
+                xmlns:xlink="http://www.w3.org/1999/xlink"
+                exclude-result-prefixes="doc dyn saxon"
+                version='1.0'>
+
+<!-- ********************************************************************
+     $Id: charmap.xsl 7266 2007-08-22 11:58:42Z xmldoc $
+     ********************************************************************
+
+     This file is part of the XSL DocBook Stylesheet distribution.
+     See ../README or http://docbook.sf.net/release/xsl/current/ for
+     copyright and other information.
+
+     ******************************************************************** -->
+<doc:reference xmlns="" xml:id="charmap">
+  <info>
+    <title>Common » Character-Map Template Reference</title>
+    <releaseinfo role="meta">
+      $Id: charmap.xsl 7266 2007-08-22 11:58:42Z xmldoc $
+    </releaseinfo>
+  </info>
+  <!-- * yes, partintro is a valid child of a reference... -->
+  <partintro xml:id="partintro">
+    <title>Introduction</title>
+    <para>This is technical reference documentation for the
+      character-map templates in the DocBook XSL Stylesheets.</para>
+    <note>
+      <para>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.</para>
+      <para>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.</para>
+    </note>
+    <para>This is not intended to be user documentation. It is
+      provided for developers writing customization layers for the
+      stylesheets.</para>
+  </partintro>
+</doc:reference>
+
+<!-- ===================================== -->
+<doc:template name="apply-character-map" xmlns="">
+  <refpurpose>Applies an XSLT character map</refpurpose>
+  <refdescription id="apply-character-map-desc">
+    <para>This template applies an <link
+      xlink:href="http://www.w3.org/TR/xslt20/#character-maps"
+      >XSLT character map</link>; 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
+      <parameter>map.contents</parameter> to do substitution on
+      <parameter>content</parameter>, and then returns the
+      modified contents.</para>
+    <note>
+      <para>This template is a very slightly modified version of
+        Jeni Tennison’s <function>replace_strings</function>
+        template in the <link
+          xlink:href="http://www.dpawson.co.uk/xsl/sect2/StringReplace.html#d9351e13"
+          >multiple string replacements</link> section of Dave Pawson’s
+        <link xlink:href="http://www.dpawson.co.uk/xsl/index.html"
+          >XSLT FAQ</link>.</para>
+      <para>The <function>apply-string-subst-map</function>
+        template is essentially the same template as the
+        <function>apply-character-map</function> template; the
+        only difference is that in the map that
+        <function>apply-string-subst-map</function> expects, <tag
+          class="attribute">oldstring</tag> and <tag
+          class="attribute">newstring</tag> attributes are used
+        instead of <tag class="attribute">character</tag> and <tag
+          class="attribute">string</tag> attributes.</para>
+    </note>
+  </refdescription>
+  <refparameter id="apply-character-map-params">
+    <variablelist>
+      <varlistentry><term>content</term>
+        <listitem>
+          <para>The content on which to perform the character-map
+            substitution.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry><term>map.contents</term>
+        <listitem>
+          <para>A node set of elements, with each element having
+            the following attributes:
+            <itemizedlist>
+              <listitem>
+                <simpara><tag class="attribute">character</tag>, a
+                  character to be replaced</simpara>
+              </listitem>
+              <listitem>
+                <simpara><tag class="attribute">string</tag>, a
+                  string with which to replace <tag
+                    class="attribute">character</tag></simpara>
+              </listitem>
+            </itemizedlist>
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refparameter>
+</doc:template>
+<xsl:template name="apply-character-map">
+  <xsl:param name="content"/>
+  <xsl:param name="map.contents"/>
+  <xsl:variable name="replaced_text">
+    <xsl:call-template name="string.subst">
+      <xsl:with-param name="string" select="$content" />
+      <xsl:with-param name="target" 
+        select="$map.contents[1]/@character" />
+      <xsl:with-param name="replacement" 
+        select="$map.contents[1]/@string" />
+    </xsl:call-template>
+  </xsl:variable>
+  <xsl:choose>
+    <xsl:when test="$map.contents[2]">
+      <xsl:call-template name="apply-character-map">
+        <xsl:with-param name="content" select="$replaced_text" />
+        <xsl:with-param name="map.contents"
+          select="$map.contents[position() > 1]" />
+      </xsl:call-template>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:value-of select="$replaced_text" />
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+<!-- ===================================== -->
+<doc:template name="read-character-map" xmlns="">
+  <refpurpose>Reads in all or part of an XSLT character map</refpurpose>
+  <refdescription id="read-character-map-desc">
+    <para>The XSLT 2.0 specification describes <link
+        xlink:href="http://www.w3.org/TR/xslt20/#character-maps"
+        >character maps</link> 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
+      <function>read-character-map</function> template provides a
+      means for reading and using character maps with XSLT
+      1.0-based tools.</para>
+    <para>This template reads the character-map contents from
+      <parameter>uri</parameter> (in full or in part, depending on
+      the value of the <parameter>use.subset</parameter>
+      parameter), then passes those contents to the
+      <function>apply-character-map</function> template, along with
+      <parameter>content</parameter>, the data on which to perform
+      the character substitution.</para>
+    <para>Using the character map “in part” means that it uses only
+      those <tag>output-character</tag> elements that match the
+      XPath expression given in the value of the
+      <parameter>subset.profile</parameter> parameter. The current
+      implementation of that capability here relies on the
+      <function>evaluate</function> extension XSLT function.</para>
+  </refdescription>
+  <refparameter id="read-character-map-params">
+    <variablelist>
+      <varlistentry><term>use.subset</term>
+        <listitem>
+          <para>Specifies whether to use a subset of the character
+            map instead of the whole map; boolean
+            <literal>0</literal> or <literal>1</literal></para>
+        </listitem>
+      </varlistentry>
+      <varlistentry><term>subset.profile</term>
+        <listitem>
+          <para>XPath expression that specifies what subset of the
+            character map to use</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry><term>uri</term>
+        <listitem>
+          <para>URI for a character map</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refparameter>
+</doc:template>
+<xsl:template name="read-character-map">
+  <xsl:param name="use.subset"/>
+  <xsl:param name="subset.profile"/>
+  <xsl:param name="uri"/>
+  <xsl:choose>
+    <xsl:when test="$use.subset != 0">
+      <!-- *use a subset of the character map instead of the full map -->
+      <xsl:choose>
+        <!-- * xsltproc and Xalan both support dyn:evaluate() -->
+        <xsl:when test="function-available('dyn:evaluate')">
+          <xsl:copy-of select="document($uri)//*[local-name()='output-character']
+            [dyn:evaluate($subset.profile)]"/>
+        </xsl:when>
+        <!-- * Saxon has its own evaluate() and doesn't support dyn:evaluate() -->
+        <xsl:when test="function-available('saxon:evaluate')">
+          <xsl:copy-of select="document($uri)//*[local-name()='output-character']
+            [saxon:evaluate($subset.profile)]"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:message terminate="yes"
+>
+Error: To process character-map subsets, you must use an XSLT engine
+that supports the evaluate() XSLT extension function. Your XSLT engine
+does not support it.
+          </xsl:message>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:when>
+    <xsl:otherwise>
+      <!-- *value of $use.subset is non-zero, so use the full map -->
+      <xsl:copy-of select="document($uri)//*[local-name()='output-character']"/>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+</xsl:stylesheet>

data/docbook-xsl/common/common.xml

@@ -0,0 +1,622 @@
+<?xml version="1.0"?>
+
+<reference xml:id="base">
+  <info>
+    <title>Common » Base Template Reference</title>
+    <releaseinfo role="meta">
+      $Id: common.xsl 8206 2009-01-10 12:05:42Z mzjn $
+    </releaseinfo>
+  </info>
+  
+  <partintro xml:id="partintro">
+    <title>Introduction</title>
+    
+<para>This is technical reference documentation for the “base”
+      set of common templates in the DocBook XSL Stylesheets.</para>
+
+    
+<para>This is not intended to be user documentation. It is
+      provided for developers writing customization layers for the
+      stylesheets.</para>
+
+  </partintro>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.is.component">
+<refnamediv>
+<refname>is.component</refname>
+<refpurpose>Tests if a given node is a component-level element</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="is.component"&gt;
+&lt;xsl:param name="node" select="."/&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+
+<para>This template returns '1' if the specified node is a component
+(Chapter, Appendix, etc.), and '0' otherwise.</para>
+
+</refsect1><refsect1><title>Parameters</title>
+
+<variablelist>
+<varlistentry><term>node</term>
+<listitem>
+
+<para>The node which is to be tested.</para>
+
+</listitem>
+</varlistentry>
+</variablelist>
+
+</refsect1><refsect1><title>Returns</title>
+
+<para>This template returns '1' if the specified node is a component
+(Chapter, Appendix, etc.), and '0' otherwise.</para>
+
+</refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.is.section">
+<refnamediv>
+<refname>is.section</refname>
+<refpurpose>Tests if a given node is a section-level element</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="is.section"&gt;
+&lt;xsl:param name="node" select="."/&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+
+<para>This template returns '1' if the specified node is a section
+(Section, Sect1, Sect2, etc.), and '0' otherwise.</para>
+
+</refsect1><refsect1><title>Parameters</title>
+
+<variablelist>
+<varlistentry><term>node</term>
+<listitem>
+
+<para>The node which is to be tested.</para>
+
+</listitem>
+</varlistentry>
+</variablelist>
+
+</refsect1><refsect1><title>Returns</title>
+
+<para>This template returns '1' if the specified node is a section
+(Section, Sect1, Sect2, etc.), and '0' otherwise.</para>
+
+</refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.section.level">
+<refnamediv>
+<refname>section.level</refname>
+<refpurpose>Returns the hierarchical level of a section</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="section.level"&gt;
+&lt;xsl:param name="node" select="."/&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+
+<para>This template calculates the hierarchical level of a section.
+The element <tag>sect1</tag> is at level 1, <tag>sect2</tag> is
+at level 2, etc.</para>
+
+
+
+<para>Recursive sections are calculated down to the fifth level.</para>
+
+</refsect1><refsect1><title>Parameters</title>
+
+<variablelist>
+<varlistentry><term>node</term>
+<listitem>
+
+<para>The section node for which the level should be calculated.
+Defaults to the context node.</para>
+
+</listitem>
+</varlistentry>
+</variablelist>
+
+</refsect1><refsect1><title>Returns</title>
+
+<para>The section level, <quote>1</quote>, <quote>2</quote>, etc.
+</para>
+
+</refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.qanda.section.level">
+<refnamediv>
+<refname>qanda.section.level</refname>
+<refpurpose>Returns the hierarchical level of a QandASet</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="qanda.section.level"/&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+
+<para>This template calculates the hierarchical level of a QandASet.
+</para>
+
+</refsect1><refsect1><title>Returns</title>
+
+<para>The level, <quote>1</quote>, <quote>2</quote>, etc.
+</para>
+
+</refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.select.mediaobject">
+<refnamediv>
+<refname>select.mediaobject</refname>
+<refpurpose>Selects and processes an appropriate media object from a list</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="select.mediaobject"&gt;
+&lt;xsl:param name="olist" select="imageobject|imageobjectco                      |videoobject|audioobject|textobject"/&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+
+<para>This template takes a list of media objects (usually the
+children of a mediaobject or inlinemediaobject) and processes
+the "right" object.</para>
+
+
+
+<para>This template relies on a template named 
+"select.mediaobject.index" to determine which object
+in the list is appropriate.</para>
+
+
+
+<para>If no acceptable object is located, nothing happens.</para>
+
+</refsect1><refsect1><title>Parameters</title>
+
+<variablelist>
+<varlistentry><term>olist</term>
+<listitem>
+
+<para>The node list of potential objects to examine.</para>
+
+</listitem>
+</varlistentry>
+</variablelist>
+
+</refsect1><refsect1><title>Returns</title>
+
+<para>Calls &lt;xsl:apply-templates&gt; on the selected object.</para>
+
+</refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.select.mediaobject.index">
+<refnamediv>
+<refname>select.mediaobject.index</refname>
+<refpurpose>Selects the position of the appropriate media object from a list</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="select.mediaobject.index"&gt;
+&lt;xsl:param name="olist" select="imageobject|imageobjectco                      |videoobject|audioobject|textobject"/&gt;
+&lt;xsl:param name="count"&gt;1&lt;/xsl:param&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+
+<para>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.</para>
+
+
+
+<para>If the parameter <parameter>use.role.for.mediaobject</parameter>
+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.</para>
+
+
+
+<para>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.
+</para>
+
+
+
+<para>If no acceptable object is located, no index is returned.</para>
+
+</refsect1><refsect1><title>Parameters</title>
+
+<variablelist>
+<varlistentry><term>olist</term>
+<listitem>
+
+<para>The node list of potential objects to examine.</para>
+
+</listitem>
+</varlistentry>
+<varlistentry><term>count</term>
+<listitem>
+
+<para>The position in the list currently being considered by the 
+recursive process.</para>
+
+</listitem>
+</varlistentry>
+</variablelist>
+
+</refsect1><refsect1><title>Returns</title>
+
+<para>Returns the position in the original list of the selected object.</para>
+
+</refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.is.acceptable.mediaobject">
+<refnamediv>
+<refname>is.acceptable.mediaobject</refname>
+<refpurpose>Returns '1' if the specified media object is recognized</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="is.acceptable.mediaobject"&gt;
+&lt;xsl:param name="object"/&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+
+<para>This template examines a media object and returns '1' if the
+object is recognized as a graphic.</para>
+
+</refsect1><refsect1><title>Parameters</title>
+
+<variablelist>
+<varlistentry><term>object</term>
+<listitem>
+
+<para>The media object to consider.</para>
+
+</listitem>
+</varlistentry>
+</variablelist>
+
+</refsect1><refsect1><title>Returns</title>
+
+<para>0 or 1</para>
+
+</refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.check.id.unique">
+<refnamediv>
+<refname>check.id.unique</refname>
+<refpurpose>Warn users about references to non-unique IDs</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="check.id.unique"&gt;
+&lt;xsl:param name="linkend"/&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+
+<para>If passed an ID in <varname>linkend</varname>,
+<function>check.id.unique</function> prints
+a warning message to the user if either the ID does not exist or
+the ID is not unique.</para>
+
+</refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.check.idref.targets">
+<refnamediv>
+<refname>check.idref.targets</refname>
+<refpurpose>Warn users about incorrectly typed references</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="check.idref.targets"&gt;
+&lt;xsl:param name="linkend"/&gt;
+&lt;xsl:param name="element-list"/&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+
+<para>If passed an ID in <varname>linkend</varname>,
+<function>check.idref.targets</function> makes sure that the element
+pointed to by the link is one of the elements listed in
+<varname>element-list</varname> and warns the user otherwise.</para>
+
+</refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.copyright.years">
+<refnamediv>
+<refname>copyright.years</refname>
+<refpurpose>Print a set of years with collapsed ranges</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="copyright.years"&gt;
+&lt;xsl:param name="years"/&gt;
+&lt;xsl:param name="print.ranges" select="1"/&gt;
+&lt;xsl:param name="single.year.ranges" select="0"/&gt;
+&lt;xsl:param name="firstyear" select="0"/&gt;
+&lt;xsl:param name="nextyear" select="0"/&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+
+<para>This template prints a list of year elements with consecutive
+years printed as a range. In other words:</para>
+
+
+<screen>&lt;year&gt;1992&lt;/year&gt;
+&lt;year&gt;1993&lt;/year&gt;
+&lt;year&gt;1994&lt;/year&gt;</screen>
+
+
+<para>is printed <quote>1992-1994</quote>, whereas:</para>
+
+
+<screen>&lt;year&gt;1992&lt;/year&gt;
+&lt;year&gt;1994&lt;/year&gt;</screen>
+
+
+<para>is printed <quote>1992, 1994</quote>.</para>
+
+
+
+<para>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 <quote>century+year</quote>
+(<quote>1999</quote> not <quote>99</quote>) notation.</para>
+
+</refsect1><refsect1><title>Parameters</title>
+
+<variablelist>
+<varlistentry><term>years</term>
+<listitem>
+
+<para>The initial set of year elements.</para>
+
+</listitem>
+</varlistentry>
+<varlistentry><term>print.ranges</term>
+<listitem>
+
+<para>If non-zero, multi-year ranges are collapsed. If zero, all years
+are printed discretely.</para>
+
+</listitem>
+</varlistentry>
+<varlistentry><term>single.year.ranges</term>
+<listitem>
+
+<para>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 <quote>1991-1992</quote> but discretely it's
+<quote>1991, 1992</quote>.</para>
+
+</listitem>
+</varlistentry>
+</variablelist>
+
+</refsect1><refsect1><title>Returns</title>
+
+<para>This template returns the formatted list of years.</para>
+
+</refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.find.path.params">
+<refnamediv>
+<refname>find.path.params</refname>
+<refpurpose>Search in a table for the "best" match for the node</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="find.path.params"&gt;
+&lt;xsl:param name="node" select="."/&gt;
+&lt;xsl:param name="table" select="''"/&gt;
+&lt;xsl:param name="location"&gt;
+    &lt;xsl:call-template name="xpath.location"&gt;
+      &lt;xsl:with-param name="node" select="$node"/&gt;
+    &lt;/xsl:call-template&gt;
+  &lt;/xsl:param&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+
+<para>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.</para>
+
+</refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.string.upper">
+<refnamediv>
+<refname>string.upper</refname>
+<refpurpose>Converts a string to all uppercase letters</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="string.upper"&gt;
+&lt;xsl:param name="string" select="''"/&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+
+<para>Given a string, this template does a language-aware conversion
+of that string to all uppercase letters, based on the values of the
+<literal>lowercase.alpha</literal> and
+<literal>uppercase.alpha</literal> gentext keys for the current
+locale. It affects only those characters found in the values of
+<literal>lowercase.alpha</literal> and
+<literal>uppercase.alpha</literal>. All other characters are left
+unchanged.</para>
+
+</refsect1><refsect1><title>Parameters</title>
+
+<variablelist>
+<varlistentry><term>string</term>
+<listitem>
+
+<para>The string to convert to uppercase.</para>
+
+</listitem>
+</varlistentry>
+</variablelist>
+
+</refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.string.lower">
+<refnamediv>
+<refname>string.lower</refname>
+<refpurpose>Converts a string to all lowercase letters</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="string.lower"&gt;
+&lt;xsl:param name="string" select="''"/&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+
+<para>Given a string, this template does a language-aware conversion
+of that string to all lowercase letters, based on the values of the
+<literal>uppercase.alpha</literal> and
+<literal>lowercase.alpha</literal> gentext keys for the current
+locale. It affects only those characters found in the values of
+<literal>uppercase.alpha</literal> and
+<literal>lowercase.alpha</literal>. All other characters are left
+unchanged.</para>
+
+</refsect1><refsect1><title>Parameters</title>
+
+<variablelist>
+<varlistentry><term>string</term>
+<listitem>
+
+<para>The string to convert to lowercase.</para>
+
+</listitem>
+</varlistentry>
+</variablelist>
+
+</refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.select.choice.separator">
+<refnamediv>
+<refname>select.choice.separator</refname>
+<refpurpose>Returns localized choice separator</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="select.choice.separator"/&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+    
+<para>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).</para>
+
+    
+<para>It currently works by evaluating a processing instruction
+    (PI) of the form &lt;?dbchoice choice="foo"?&gt; :
+    
+<itemizedlist>
+      <listitem>
+        <simpara>if the value of the <tag>choice</tag>
+        pseudo-attribute is "and" or "or", returns a localized "and"
+        or "or"</simpara>
+      </listitem>
+      <listitem>
+        <simpara>otherwise returns the literal value of the
+        <tag>choice</tag> pseudo-attribute</simpara>
+      </listitem>
+    </itemizedlist>
+
+    The latter is provided only as a temporary workaround because the
+    locale files do not currently have translations for the word
+    <wordasword>or</wordasword>. So if you want to generate a a
+    logical "or" separator in French (for example), you currently need
+    to do this:
+    <literallayout>&lt;?dbchoice choice="ou"?&gt;</literallayout>
+    </para>
+
+    <warning>
+      
+<para>The <tag>dbchoice</tag> 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).</para>
+
+    </warning>
+  </refsect1></refentry>
+
+<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.evaluate.info.profile">
+<refnamediv>
+<refname>evaluate.info.profile</refname>
+<refpurpose>Evaluates an info profile</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>&lt;xsl:template name="evaluate.info.profile"&gt;
+&lt;xsl:param name="profile"/&gt;
+&lt;xsl:param name="info"/&gt;
+  ...
+&lt;/xsl:template&gt;</synopsis>
+</refsynopsisdiv>
+<refsect1><title>Description</title>
+    
+<para>This template evaluates an "info profile" matching the XPath
+    expression given by the <parameter>profile</parameter>
+    parameter. It relies on the XSLT <function>evaluate()</function>
+    extension function.</para>
+
+
+    
+<para>The value of the <parameter>profile</parameter> parameter
+    can include the literal string <literal>$info</literal>. If found
+    in the value of the <parameter>profile</parameter> parameter, the
+    literal string <literal>$info</literal> string is replaced with
+    the value of the <parameter>info</parameter> parameter, which
+    should be a set of <replaceable>*info</replaceable> nodes; the
+    expression is then evaluated using the XSLT
+    <function>evaluate()</function> extension function.</para>
+
+  </refsect1><refsect1><title>Parameters</title>
+    
+<variablelist>
+       <varlistentry>
+        <term>profile</term>
+        <listitem>
+          
+<para>A string representing an XPath expression </para>
+
+        </listitem>
+      </varlistentry>
+       <varlistentry>
+        <term>info</term>
+        <listitem>
+          
+<para>A set of *info nodes</para>
+
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+  </refsect1><refsect1><title>Returns</title>
+    
+<para>Returns a node (the result of evaluating the
+    <parameter>profile</parameter> parameter)</para>
+
+  </refsect1></refentry>
+</reference>
+