622 lines
18 KiB
XML
622 lines
18 KiB
XML
<?xml version="1.0"?>
|
||
|
||
<reference xml:id="base">
|
||
<info>
|
||
<title>Common » Base Template Reference</title>
|
||
<releaseinfo role="meta">
|
||
$Id: common.xsl 8784 2010-07-28 12:32:54Z 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><xsl:template name="is.component">
|
||
<xsl:param name="node" select="."/>
|
||
...
|
||
</xsl:template></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><xsl:template name="is.section">
|
||
<xsl:param name="node" select="."/>
|
||
...
|
||
</xsl:template></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><xsl:template name="section.level">
|
||
<xsl:param name="node" select="."/>
|
||
...
|
||
</xsl:template></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><xsl:template name="qanda.section.level"/></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><xsl:template name="select.mediaobject">
|
||
<xsl:param name="olist" select="imageobject|imageobjectco |videoobject|audioobject|textobject"/>
|
||
...
|
||
</xsl:template></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 <xsl:apply-templates> 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><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></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><xsl:template name="is.acceptable.mediaobject">
|
||
<xsl:param name="object"/>
|
||
...
|
||
</xsl:template></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><xsl:template name="check.id.unique">
|
||
<xsl:param name="linkend"/>
|
||
...
|
||
</xsl:template></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><xsl:template name="check.idref.targets">
|
||
<xsl:param name="linkend"/>
|
||
<xsl:param name="element-list"/>
|
||
...
|
||
</xsl:template></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><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></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><year>1992</year>
|
||
<year>1993</year>
|
||
<year>1994</year></screen>
|
||
|
||
|
||
<para>is printed <quote>1992-1994</quote>, whereas:</para>
|
||
|
||
|
||
<screen><year>1992</year>
|
||
<year>1994</year></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><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></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><xsl:template name="string.upper">
|
||
<xsl:param name="string" select="''"/>
|
||
...
|
||
</xsl:template></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><xsl:template name="string.lower">
|
||
<xsl:param name="string" select="''"/>
|
||
...
|
||
</xsl:template></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><xsl:template name="select.choice.separator"/></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 <?dbchoice choice="foo"?> :
|
||
|
||
<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><?dbchoice choice="ou"?></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><xsl:template name="evaluate.info.profile">
|
||
<xsl:param name="profile"/>
|
||
<xsl:param name="info"/>
|
||
...
|
||
</xsl:template></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>
|
||
|