| 1 | <?xml version='1.0'?>
|
|---|
| 2 | <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
|
|---|
| 3 | xmlns:doc="http://nwalsh.com/xsl/documentation/1.0"
|
|---|
| 4 | xmlns:dyn="http://exslt.org/dynamic"
|
|---|
| 5 | xmlns:saxon="http://icl.com/saxon"
|
|---|
| 6 | xmlns:xlink="http://www.w3.org/1999/xlink"
|
|---|
| 7 | exclude-result-prefixes="doc dyn saxon"
|
|---|
| 8 | version='1.0'>
|
|---|
| 9 |
|
|---|
| 10 | <!-- ********************************************************************
|
|---|
| 11 | $Id$
|
|---|
| 12 | ********************************************************************
|
|---|
| 13 |
|
|---|
| 14 | This file is part of the XSL DocBook Stylesheet distribution.
|
|---|
| 15 | See ../README or http://docbook.sf.net/release/xsl/current/ for
|
|---|
| 16 | copyright and other information.
|
|---|
| 17 |
|
|---|
| 18 | ******************************************************************** -->
|
|---|
| 19 | <doc:reference xmlns="" xml:id="utility">
|
|---|
| 20 | <info>
|
|---|
| 21 | <title>Common » Utility Template Reference</title>
|
|---|
| 22 | <releaseinfo role="meta">
|
|---|
| 23 | $Id$
|
|---|
| 24 | </releaseinfo>
|
|---|
| 25 | </info>
|
|---|
| 26 | <!-- * yes, partintro is a valid child of a reference... -->
|
|---|
| 27 | <partintro xml:id="partintro">
|
|---|
| 28 | <title>Introduction</title>
|
|---|
| 29 | <para>This is technical reference documentation for the
|
|---|
| 30 | miscellaneous utility templates in the DocBook XSL
|
|---|
| 31 | Stylesheets.</para>
|
|---|
| 32 | <note>
|
|---|
| 33 | <para>These templates are defined in a separate file from the set
|
|---|
| 34 | of “common” templates because some of the comment templates
|
|---|
| 35 | reference DocBook XSL stylesheet parameters, requiring the
|
|---|
| 36 | entire set of parameters to be imported/included in any
|
|---|
| 37 | stylesheet that imports/includes the common templates.</para>
|
|---|
| 38 | <para>The utility templates don’t import or include any DocBook
|
|---|
| 39 | XSL stylesheet parameters, so the utility templates can be used
|
|---|
| 40 | without importing the whole set of parameters.</para>
|
|---|
| 41 | </note>
|
|---|
| 42 | <para>This is not intended to be user documentation. It is
|
|---|
| 43 | provided for developers writing customization layers for the
|
|---|
| 44 | stylesheets.</para>
|
|---|
| 45 | </partintro>
|
|---|
| 46 | </doc:reference>
|
|---|
| 47 |
|
|---|
| 48 | <!-- ====================================================================== -->
|
|---|
| 49 |
|
|---|
| 50 | <doc:template name="log.message" xmlns="">
|
|---|
| 51 | <refpurpose>Logs/emits formatted notes and warnings</refpurpose>
|
|---|
| 52 |
|
|---|
| 53 | <refdescription id="log.message-desc">
|
|---|
| 54 | <para>The <function>log.message</function> template is a utility
|
|---|
| 55 | template for logging/emitting formatted messages – that is,
|
|---|
| 56 | notes and warnings, along with a given log “level” and an
|
|---|
| 57 | identifier for the “source” that the message relates to.</para>
|
|---|
| 58 | </refdescription>
|
|---|
| 59 |
|
|---|
| 60 | <refparameter id="log.message-params">
|
|---|
| 61 | <variablelist>
|
|---|
| 62 | <varlistentry><term>level</term>
|
|---|
| 63 | <listitem>
|
|---|
| 64 | <para>Text to log/emit in the message-level field to
|
|---|
| 65 | indicate the message level
|
|---|
| 66 | (<literal>Note</literal> or
|
|---|
| 67 | <literal>Warning</literal>)</para>
|
|---|
| 68 | </listitem>
|
|---|
| 69 | </varlistentry>
|
|---|
| 70 | <varlistentry><term>source</term>
|
|---|
| 71 | <listitem>
|
|---|
| 72 | <para>Text to log/emit in the source field to identify the
|
|---|
| 73 | “source” to which the notification/warning relates.
|
|---|
| 74 | This can be any arbitrary string, but because the
|
|---|
| 75 | message lacks line and column numbers to identify the
|
|---|
| 76 | exact part of the source document to which it
|
|---|
| 77 | relates, the intention is that the value you pass
|
|---|
| 78 | into the <literal>source</literal> parameter should
|
|---|
| 79 | give the user some way to identify the portion of
|
|---|
| 80 | their source document on which to take potentially
|
|---|
| 81 | take action in response to the log message (for
|
|---|
| 82 | example, to edit, change, or add content).</para>
|
|---|
| 83 | <para>So the <literal>source</literal> value should be,
|
|---|
| 84 | for example, an ID, book/chapter/article title, title
|
|---|
| 85 | of some formal object, or even a string giving an
|
|---|
| 86 | XPath expression.</para>
|
|---|
| 87 | </listitem>
|
|---|
| 88 | </varlistentry>
|
|---|
| 89 | <varlistentry><term>context-desc</term>
|
|---|
| 90 | <listitem>
|
|---|
| 91 | <para>Text to log/emit in the context-description field to
|
|---|
| 92 | describe the context for the message.</para>
|
|---|
| 93 | </listitem>
|
|---|
| 94 | </varlistentry>
|
|---|
| 95 | <varlistentry><term>context-desc-field-length</term>
|
|---|
| 96 | <listitem>
|
|---|
| 97 | <para>Specifies length of the context-description field
|
|---|
| 98 | (in characters); default is 12</para>
|
|---|
| 99 | <para>If the text specified by the
|
|---|
| 100 | <literal>context-desc</literal> parameter is longer
|
|---|
| 101 | than the number of characters specified in
|
|---|
| 102 | <literal>context-desc-field-length</literal>, it is
|
|---|
| 103 | truncated to <literal>context-desc-field-length</literal>
|
|---|
| 104 | (12 characters by default).</para>
|
|---|
| 105 | <para>If the specified text is shorter than
|
|---|
| 106 | <literal>context-desc-field-length</literal>,
|
|---|
| 107 | it is right-padded out to
|
|---|
| 108 | <literal>context-desc-field-length</literal> (12 by
|
|---|
| 109 | default).</para>
|
|---|
| 110 | <para>If no value has been specified for the
|
|---|
| 111 | <literal>context-desc</literal> parameter, the field is
|
|---|
| 112 | left empty and the text of the log message begins with
|
|---|
| 113 | the value of the <literal>message</literal>
|
|---|
| 114 | parameter.</para>
|
|---|
| 115 | </listitem>
|
|---|
| 116 | </varlistentry>
|
|---|
| 117 | <varlistentry><term>message</term>
|
|---|
| 118 | <listitem>
|
|---|
| 119 | <para>Text to log/emit in the actual message field</para>
|
|---|
| 120 | </listitem>
|
|---|
| 121 | </varlistentry>
|
|---|
| 122 | <varlistentry><term>message-field-length</term>
|
|---|
| 123 | <listitem>
|
|---|
| 124 | <para>Specifies length of the message
|
|---|
| 125 | field (in characters); default is 45</para>
|
|---|
| 126 | </listitem>
|
|---|
| 127 | </varlistentry>
|
|---|
| 128 | </variablelist>
|
|---|
| 129 | </refparameter>
|
|---|
| 130 | <refreturn id="log.message-returns">
|
|---|
| 131 | <para>Outputs a message (generally, to standard error).</para></refreturn>
|
|---|
| 132 | </doc:template>
|
|---|
| 133 | <xsl:template name="log.message">
|
|---|
| 134 | <xsl:param name="level"/>
|
|---|
| 135 | <xsl:param name="source"/>
|
|---|
| 136 | <xsl:param name="context-desc"/>
|
|---|
| 137 | <xsl:param name="context-desc-field-length">12</xsl:param>
|
|---|
| 138 | <xsl:param name="context-desc-padded">
|
|---|
| 139 | <xsl:if test="not($context-desc = '')">
|
|---|
| 140 | <xsl:call-template name="pad-string">
|
|---|
| 141 | <xsl:with-param name="leftRight">right</xsl:with-param>
|
|---|
| 142 | <xsl:with-param name="padVar"
|
|---|
| 143 | select="substring($context-desc, 1, $context-desc-field-length)"/>
|
|---|
| 144 | <xsl:with-param name="length" select="$context-desc-field-length"/>
|
|---|
| 145 | </xsl:call-template>
|
|---|
| 146 | </xsl:if>
|
|---|
| 147 | </xsl:param>
|
|---|
| 148 | <xsl:param name="message"/>
|
|---|
| 149 | <xsl:param name="message-field-length" select="45"/>
|
|---|
| 150 | <xsl:param name="message-padded">
|
|---|
| 151 | <xsl:variable name="spaces-for-blank-level">
|
|---|
| 152 | <!-- * if the level field is blank, we'll need to pad out -->
|
|---|
| 153 | <!-- * the message field with spaces to compensate -->
|
|---|
| 154 | <xsl:choose>
|
|---|
| 155 | <xsl:when test="$level = ''">
|
|---|
| 156 | <xsl:value-of select="4 + 2"/>
|
|---|
| 157 | <!-- * 4 = hard-coded length of comment text ("Note" or "Warn") -->
|
|---|
| 158 | <!-- * + 2 = length of colon-plus-space separator ": " -->
|
|---|
| 159 | </xsl:when>
|
|---|
| 160 | <xsl:otherwise>
|
|---|
| 161 | <xsl:value-of select="0"/>
|
|---|
| 162 | </xsl:otherwise>
|
|---|
| 163 | </xsl:choose>
|
|---|
| 164 | </xsl:variable>
|
|---|
| 165 | <xsl:variable name="spaces-for-blank-context-desc">
|
|---|
| 166 | <!-- * if the context-description field is blank, we'll need -->
|
|---|
| 167 | <!-- * to pad out the message field with spaces to compensate -->
|
|---|
| 168 | <xsl:choose>
|
|---|
| 169 | <xsl:when test="$context-desc = ''">
|
|---|
| 170 | <xsl:value-of select="$context-desc-field-length + 2"/>
|
|---|
| 171 | <!-- * + 2 = length of colon-plus-space separator ": " -->
|
|---|
| 172 | </xsl:when>
|
|---|
| 173 | <xsl:otherwise>
|
|---|
| 174 | <xsl:value-of select="0"/>
|
|---|
| 175 | </xsl:otherwise>
|
|---|
| 176 | </xsl:choose>
|
|---|
| 177 | </xsl:variable>
|
|---|
| 178 | <xsl:variable name="extra-spaces"
|
|---|
| 179 | select="$spaces-for-blank-level + $spaces-for-blank-context-desc"/>
|
|---|
| 180 | <xsl:call-template name="pad-string">
|
|---|
| 181 | <xsl:with-param name="leftRight">right</xsl:with-param>
|
|---|
| 182 | <xsl:with-param name="padVar"
|
|---|
| 183 | select="substring($message, 1, ($message-field-length + $extra-spaces))"/>
|
|---|
| 184 | <xsl:with-param name="length"
|
|---|
| 185 | select="$message-field-length + $extra-spaces"/>
|
|---|
| 186 | </xsl:call-template>
|
|---|
| 187 | </xsl:param>
|
|---|
| 188 | <!-- * emit the actual log message -->
|
|---|
| 189 | <xsl:message>
|
|---|
| 190 | <xsl:if test="not($level = '')">
|
|---|
| 191 | <xsl:value-of select="$level"/>
|
|---|
| 192 | <xsl:text>: </xsl:text>
|
|---|
| 193 | </xsl:if>
|
|---|
| 194 | <xsl:if test="not($context-desc = '')">
|
|---|
| 195 | <xsl:value-of select="$context-desc-padded"/>
|
|---|
| 196 | <xsl:text>: </xsl:text>
|
|---|
| 197 | </xsl:if>
|
|---|
| 198 | <xsl:value-of select="$message-padded"/>
|
|---|
| 199 | <xsl:text> </xsl:text>
|
|---|
| 200 | <xsl:value-of select="$source"/>
|
|---|
| 201 | </xsl:message>
|
|---|
| 202 | </xsl:template>
|
|---|
| 203 |
|
|---|
| 204 | <!-- ===================================== -->
|
|---|
| 205 | <doc:template name="get.doc.title" xmlns="">
|
|---|
| 206 | <refpurpose>Gets a title from the current document</refpurpose>
|
|---|
| 207 | <refdescription id="get.doc.title-desc">
|
|---|
| 208 | <para>The <function>get.doc.title</function> template is a
|
|---|
| 209 | utility template for returning the first title found in the
|
|---|
| 210 | current document.</para>
|
|---|
| 211 | </refdescription>
|
|---|
| 212 | <refreturn id="get.doc.title-returns">
|
|---|
| 213 | <para>Returns a string containing some identifying title for the
|
|---|
| 214 | current document .</para></refreturn>
|
|---|
| 215 | </doc:template>
|
|---|
| 216 | <xsl:template name="get.doc.title">
|
|---|
| 217 | <xsl:choose>
|
|---|
| 218 | <xsl:when test="//*[local-name() = 'title'
|
|---|
| 219 | or local-name() = 'refname']">
|
|---|
| 220 | <xsl:value-of select="//*[local-name() = 'title'
|
|---|
| 221 | or local-name() = 'refname'][1]"/>
|
|---|
| 222 | </xsl:when>
|
|---|
| 223 | <xsl:when test="substring(local-name(*[1]),
|
|---|
| 224 | string-length(local-name(*[1])-3) = 'info')
|
|---|
| 225 | and *[1]/*[local-name() = 'title']">
|
|---|
| 226 | <xsl:value-of select="*[1]/*[local-name() = 'title'][1]"/>
|
|---|
| 227 | </xsl:when>
|
|---|
| 228 | </xsl:choose>
|
|---|
| 229 | </xsl:template>
|
|---|
| 230 |
|
|---|
| 231 | <!-- ===================================== -->
|
|---|
| 232 | <doc:template name="pad-string" xmlns="">
|
|---|
| 233 | <refpurpose>Right-pads or left-pads a string out to a certain length</refpurpose>
|
|---|
| 234 | <refdescription id="pad-string-desc">
|
|---|
| 235 | <para>This function takes string <parameter>padVar</parameter> and
|
|---|
| 236 | pads it out in the direction <parameter>rightLeft</parameter> to
|
|---|
| 237 | the string-length <parameter>length</parameter>, using string
|
|---|
| 238 | <parameter>padChar</parameter> (a space character by default) as
|
|---|
| 239 | the padding string (note that <parameter>padChar</parameter> can
|
|---|
| 240 | be a string; it is not limited to just being a single
|
|---|
| 241 | character).</para>
|
|---|
| 242 | <note>
|
|---|
| 243 | <para>This function began as a copy of Nate Austin's
|
|---|
| 244 | <function>prepend-pad</function> function in the <link
|
|---|
| 245 | xlink:href="http://www.dpawson.co.uk/xsl/sect2/padding.html" >Padding
|
|---|
| 246 | Content</link> section of Dave Pawson's <link
|
|---|
| 247 | xlink:href="http://www.dpawson.co.uk/xsl/index.html" >XSLT
|
|---|
| 248 | FAQ</link>.</para>
|
|---|
| 249 | </note>
|
|---|
| 250 | </refdescription>
|
|---|
| 251 | <refreturn id="pad-string-returns">
|
|---|
| 252 | <para>Returns a (padded) string.</para></refreturn>
|
|---|
| 253 | </doc:template>
|
|---|
| 254 | <xsl:template name="pad-string">
|
|---|
| 255 | <!-- * recursive template to right/left pad the value with -->
|
|---|
| 256 | <!-- * whatever padChar is passed in -->
|
|---|
| 257 | <xsl:param name="padChar" select="' '"/>
|
|---|
| 258 | <xsl:param name="leftRight">left</xsl:param>
|
|---|
| 259 | <xsl:param name="padVar"/>
|
|---|
| 260 | <xsl:param name="length"/>
|
|---|
| 261 | <xsl:choose>
|
|---|
| 262 | <xsl:when test="string-length($padVar) < $length">
|
|---|
| 263 | <xsl:call-template name="pad-string">
|
|---|
| 264 | <xsl:with-param name="padChar" select="$padChar"/>
|
|---|
| 265 | <xsl:with-param name="leftRight" select="$leftRight"/>
|
|---|
| 266 | <xsl:with-param name="padVar">
|
|---|
| 267 | <xsl:choose>
|
|---|
| 268 | <!-- * determine whether string should be -->
|
|---|
| 269 | <!-- * right- or left-padded -->
|
|---|
| 270 | <xsl:when test="$leftRight = 'left'">
|
|---|
| 271 | <!-- * pad it to left -->
|
|---|
| 272 | <xsl:value-of select="concat($padChar,$padVar)"/>
|
|---|
| 273 | </xsl:when>
|
|---|
| 274 | <xsl:otherwise>
|
|---|
| 275 | <!-- * otherwise, right-pad the string -->
|
|---|
| 276 | <xsl:value-of select="concat($padVar,$padChar)"/>
|
|---|
| 277 | </xsl:otherwise>
|
|---|
| 278 | </xsl:choose>
|
|---|
| 279 | </xsl:with-param>
|
|---|
| 280 | <xsl:with-param name="length" select="$length"/>
|
|---|
| 281 | </xsl:call-template>
|
|---|
| 282 | </xsl:when>
|
|---|
| 283 | <xsl:otherwise>
|
|---|
| 284 | <xsl:value-of
|
|---|
| 285 | select="substring($padVar,string-length($padVar) - $length + 1)"/>
|
|---|
| 286 | </xsl:otherwise>
|
|---|
| 287 | </xsl:choose>
|
|---|
| 288 | </xsl:template>
|
|---|
| 289 |
|
|---|
| 290 | </xsl:stylesheet>
|
|---|
