diff options
Diffstat (limited to 'common/utility.xsl')
| -rw-r--r-- | common/utility.xsl | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/common/utility.xsl b/common/utility.xsl new file mode 100644 index 0000000..37092b7 --- /dev/null +++ b/common/utility.xsl @@ -0,0 +1,290 @@ +<?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: utility.xsl 7101 2007-07-20 15:32:12Z 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="utility"> + <info> + <title>Common » Utility Template Reference</title> + <releaseinfo role="meta"> + $Id: utility.xsl 7101 2007-07-20 15:32:12Z 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 + miscellaneous utility 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 utility templates don’t import or include any DocBook + XSL stylesheet parameters, so the utility 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="log.message" xmlns=""> + <refpurpose>Logs/emits formatted notes and warnings</refpurpose> + + <refdescription id="log.message-desc"> + <para>The <function>log.message</function> template is a utility + template for logging/emitting formatted messages – that is, + notes and warnings, along with a given log “level” and an + identifier for the “source” that the message relates to.</para> + </refdescription> + + <refparameter id="log.message-params"> + <variablelist> + <varlistentry><term>level</term> + <listitem> + <para>Text to log/emit in the message-level field to + indicate the message level + (<literal>Note</literal> or + <literal>Warning</literal>)</para> + </listitem> + </varlistentry> + <varlistentry><term>source</term> + <listitem> + <para>Text to log/emit in the source field to identify the + “source” to which the notification/warning relates. + This can be any arbitrary string, but because the + message lacks line and column numbers to identify the + exact part of the source document to which it + relates, the intention is that the value you pass + into the <literal>source</literal> parameter should + give the user some way to identify the portion of + their source document on which to take potentially + take action in response to the log message (for + example, to edit, change, or add content).</para> + <para>So the <literal>source</literal> value should be, + for example, an ID, book/chapter/article title, title + of some formal object, or even a string giving an + XPath expression.</para> + </listitem> + </varlistentry> + <varlistentry><term>context-desc</term> + <listitem> + <para>Text to log/emit in the context-description field to + describe the context for the message.</para> + </listitem> + </varlistentry> + <varlistentry><term>context-desc-field-length</term> + <listitem> + <para>Specifies length of the context-description field + (in characters); default is 12</para> + <para>If the text specified by the + <literal>context-desc</literal> parameter is longer + than the number of characters specified in + <literal>context-desc-field-length</literal>, it is + truncated to <literal>context-desc-field-length</literal> + (12 characters by default).</para> + <para>If the specified text is shorter than + <literal>context-desc-field-length</literal>, + it is right-padded out to + <literal>context-desc-field-length</literal> (12 by + default).</para> + <para>If no value has been specified for the + <literal>context-desc</literal> parameter, the field is + left empty and the text of the log message begins with + the value of the <literal>message</literal> + parameter.</para> + </listitem> + </varlistentry> + <varlistentry><term>message</term> + <listitem> + <para>Text to log/emit in the actual message field</para> + </listitem> + </varlistentry> + <varlistentry><term>message-field-length</term> + <listitem> + <para>Specifies length of the message + field (in characters); default is 45</para> + </listitem> + </varlistentry> + </variablelist> + </refparameter> + <refreturn id="log.message-returns"> + <para>Outputs a message (generally, to standard error).</para></refreturn> +</doc:template> +<xsl:template name="log.message"> + <xsl:param name="level"/> + <xsl:param name="source"/> + <xsl:param name="context-desc"/> + <xsl:param name="context-desc-field-length">12</xsl:param> + <xsl:param name="context-desc-padded"> + <xsl:if test="not($context-desc = '')"> + <xsl:call-template name="pad-string"> + <xsl:with-param name="leftRight">right</xsl:with-param> + <xsl:with-param name="padVar" + select="substring($context-desc, 1, $context-desc-field-length)"/> + <xsl:with-param name="length" select="$context-desc-field-length"/> + </xsl:call-template> + </xsl:if> + </xsl:param> + <xsl:param name="message"/> + <xsl:param name="message-field-length" select="45"/> + <xsl:param name="message-padded"> + <xsl:variable name="spaces-for-blank-level"> + <!-- * if the level field is blank, we'll need to pad out --> + <!-- * the message field with spaces to compensate --> + <xsl:choose> + <xsl:when test="$level = ''"> + <xsl:value-of select="4 + 2"/> + <!-- * 4 = hard-coded length of comment text ("Note" or "Warn") --> + <!-- * + 2 = length of colon-plus-space separator ": " --> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="0"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:variable name="spaces-for-blank-context-desc"> + <!-- * if the context-description field is blank, we'll need --> + <!-- * to pad out the message field with spaces to compensate --> + <xsl:choose> + <xsl:when test="$context-desc = ''"> + <xsl:value-of select="$context-desc-field-length + 2"/> + <!-- * + 2 = length of colon-plus-space separator ": " --> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="0"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:variable name="extra-spaces" + select="$spaces-for-blank-level + $spaces-for-blank-context-desc"/> + <xsl:call-template name="pad-string"> + <xsl:with-param name="leftRight">right</xsl:with-param> + <xsl:with-param name="padVar" + select="substring($message, 1, ($message-field-length + $extra-spaces))"/> + <xsl:with-param name="length" + select="$message-field-length + $extra-spaces"/> + </xsl:call-template> + </xsl:param> + <!-- * emit the actual log message --> + <xsl:message> + <xsl:if test="not($level = '')"> + <xsl:value-of select="$level"/> + <xsl:text>: </xsl:text> + </xsl:if> + <xsl:if test="not($context-desc = '')"> + <xsl:value-of select="$context-desc-padded"/> + <xsl:text>: </xsl:text> + </xsl:if> + <xsl:value-of select="$message-padded"/> + <xsl:text> </xsl:text> + <xsl:value-of select="$source"/> + </xsl:message> +</xsl:template> + +<!-- ===================================== --> +<doc:template name="get.doc.title" xmlns=""> + <refpurpose>Gets a title from the current document</refpurpose> + <refdescription id="get.doc.title-desc"> + <para>The <function>get.doc.title</function> template is a + utility template for returning the first title found in the + current document.</para> + </refdescription> + <refreturn id="get.doc.title-returns"> + <para>Returns a string containing some identifying title for the + current document .</para></refreturn> +</doc:template> +<xsl:template name="get.doc.title"> + <xsl:choose> + <xsl:when test="//*[local-name() = 'title' + or local-name() = 'refname']"> + <xsl:value-of select="//*[local-name() = 'title' + or local-name() = 'refname'][1]"/> + </xsl:when> + <xsl:when test="substring(local-name(*[1]), + string-length(local-name(*[1])-3) = 'info') + and *[1]/*[local-name() = 'title']"> + <xsl:value-of select="*[1]/*[local-name() = 'title'][1]"/> + </xsl:when> + </xsl:choose> +</xsl:template> + +<!-- ===================================== --> +<doc:template name="pad-string" xmlns=""> + <refpurpose>Right-pads or left-pads a string out to a certain length</refpurpose> + <refdescription id="pad-string-desc"> + <para>This function takes string <parameter>padVar</parameter> and + pads it out in the direction <parameter>rightLeft</parameter> to + the string-length <parameter>length</parameter>, using string + <parameter>padChar</parameter> (a space character by default) as + the padding string (note that <parameter>padChar</parameter> can + be a string; it is not limited to just being a single + character).</para> + <note> + <para>This function began as a copy of Nate Austin's + <function>prepend-pad</function> function in the <link + xlink:href="http://www.dpawson.co.uk/xsl/sect2/padding.html" >Padding + Content</link> section of Dave Pawson's <link + xlink:href="http://www.dpawson.co.uk/xsl/index.html" >XSLT + FAQ</link>.</para> + </note> + </refdescription> + <refreturn id="pad-string-returns"> + <para>Returns a (padded) string.</para></refreturn> +</doc:template> +<xsl:template name="pad-string"> + <!-- * recursive template to right/left pad the value with --> + <!-- * whatever padChar is passed in --> + <xsl:param name="padChar" select="' '"/> + <xsl:param name="leftRight">left</xsl:param> + <xsl:param name="padVar"/> + <xsl:param name="length"/> + <xsl:choose> + <xsl:when test="string-length($padVar) < $length"> + <xsl:call-template name="pad-string"> + <xsl:with-param name="padChar" select="$padChar"/> + <xsl:with-param name="leftRight" select="$leftRight"/> + <xsl:with-param name="padVar"> + <xsl:choose> + <!-- * determine whether string should be --> + <!-- * right- or left-padded --> + <xsl:when test="$leftRight = 'left'"> + <!-- * pad it to left --> + <xsl:value-of select="concat($padChar,$padVar)"/> + </xsl:when> + <xsl:otherwise> + <!-- * otherwise, right-pad the string --> + <xsl:value-of select="concat($padVar,$padChar)"/> + </xsl:otherwise> + </xsl:choose> + </xsl:with-param> + <xsl:with-param name="length" select="$length"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:value-of + select="substring($padVar,string-length($padVar) - $length + 1)"/> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +</xsl:stylesheet> |