<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE reference
  PUBLIC "-//Norman Walsh//DTD JRefEntry V1.1//EN" "http://docbook.sourceforge.net/release/jrefentry/1.1/jrefentry.dtd">
<reference>
<referenceinfo>
<releaseinfo role="meta">
$Id: common.xsl,v 1.19 2002/03/18 13:39:43 nwalsh Exp $
</releaseinfo>
<author><surname>Walsh</surname>
<firstname>Norman</firstname></author>
<copyright><year>1999</year><year>2000</year>
<holder>Norman Walsh</holder>
</copyright>
</referenceinfo>
<title>Common Template Reference</title>

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

</section>
</partintro>


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

<para>This template returns '1' if the specified node is a component
(Chapter, Appendix, etc.), and '0' otherwise.</para>

</refdescription><refparameter>

<variablelist>
<varlistentry><term>node</term>
<listitem>

<para>The node which is to be tested.</para>

</listitem>
</varlistentry>
</variablelist>

</refparameter><refreturn>

<para>This template returns '1' if the specified node is a component
(Chapter, Appendix, etc.), and '0' otherwise.</para>

</refreturn></refentry>

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

<para>This template returns '1' if the specified node is a section
(Section, Sect1, Sect2, etc.), and '0' otherwise.</para>

</refdescription><refparameter>

<variablelist>
<varlistentry><term>node</term>
<listitem>

<para>The node which is to be tested.</para>

</listitem>
</varlistentry>
</variablelist>

</refparameter><refreturn>

<para>This template returns '1' if the specified node is a section
(Section, Sect1, Sect2, etc.), and '0' otherwise.</para>

</refreturn></refentry>

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

<para>This template calculates the hierarchical level of a section.
Hierarchically, components are <quote>top level</quote>, so a
<sgmltag>sect1</sgmltag> is at level 2, <sgmltag>sect3</sgmltag> is
at level 3, etc.</para>



<para>Recursive sections are calculated down to the sixth level.</para>

</refdescription><refparameter>

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

</refparameter><refreturn>

<para>The section level, <quote>2</quote>, <quote>3</quote>, etc.
</para>

</refreturn></refentry>

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

<para>This template calculates the hierarchical level of a QandASet.
</para>

</refdescription><refreturn>

<para>The level, <quote>1</quote>, <quote>2</quote>, etc.
</para>

</refreturn></refentry>

<refentry id="template.select.mediaobject">
<refnamediv>
<refname>select.mediaobject</refname>
<refpurpose>Selects 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:param name="count"&gt;1&lt;/xsl:param&gt;
  ...
&lt;/xsl:template&gt;</synopsis>
</refsynopsisdiv>
<refdescription>

<para>This template examines 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 "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, nothing happens.</para>

</refdescription><refparameter>

<variablelist>
<varlistentry><term>olist</term>
<listitem>

<para>The node list of potential objects to examine.</para>

</listitem>
</varlistentry>
</variablelist>

</refparameter><refreturn>

<para>Calls &lt;xsl:apply-templates&gt; on the selected object.</para>

</refreturn></refentry>

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

<para>This template examines a media object and returns '1' if the
object is recognized as a graphic.</para>

</refdescription><refparameter>

<variablelist>
<varlistentry><term>object</term>
<listitem>

<para>The media object to consider.</para>

</listitem>
</varlistentry>
</variablelist>

</refparameter><refreturn>

<para>0 or 1</para>

</refreturn></refentry>

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

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

</refdescription></refentry>

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

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

</refdescription></refentry>

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

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

</refdescription><refparameter>

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

</refparameter><refreturn>

<para>This template returns the formatted list of years.</para>

</refreturn></refentry>

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

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

</refdescription></refentry>
</reference>