lib/docbook/common/utility.xml

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