doc/xslt/common/utility.xml

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