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><xsl:template name="log.message">
|
---|
46 | <xsl:param name="level"/>
|
---|
47 | <xsl:param name="source"/>
|
---|
48 | <xsl:param name="context-desc"/>
|
---|
49 | <xsl:param name="context-desc-field-length">12</xsl:param>
|
---|
50 | <xsl:param name="context-desc-padded">
|
---|
51 | <xsl:if test="not($context-desc = '')">
|
---|
52 | <xsl:call-template name="pad-string">
|
---|
53 | <xsl:with-param name="leftRight">right</xsl:with-param>
|
---|
54 | <xsl:with-param name="padVar" select="substring($context-desc, 1, $context-desc-field-length)"/>
|
---|
55 | <xsl:with-param name="length" select="$context-desc-field-length"/>
|
---|
56 | </xsl:call-template>
|
---|
57 | </xsl:if>
|
---|
58 | </xsl:param>
|
---|
59 | <xsl:param name="message"/>
|
---|
60 | <xsl:param name="message-field-length" select="45"/>
|
---|
61 | <xsl:param name="message-padded">
|
---|
62 | <xsl:variable name="spaces-for-blank-level">
|
---|
63 | <!-- * if the level field is blank, we'll need to pad out -->
|
---|
64 | <!-- * the message field with spaces to compensate -->
|
---|
65 | <xsl:choose>
|
---|
66 | <xsl:when test="$level = ''">
|
---|
67 | <xsl:value-of select="4 + 2"/>
|
---|
68 | <!-- * 4 = hard-coded length of comment text ("Note" or "Warn") -->
|
---|
69 | <!-- * + 2 = length of colon-plus-space separator ": " -->
|
---|
70 | </xsl:when>
|
---|
71 | <xsl:otherwise>
|
---|
72 | <xsl:value-of select="0"/>
|
---|
73 | </xsl:otherwise>
|
---|
74 | </xsl:choose>
|
---|
75 | </xsl:variable>
|
---|
76 | <xsl:variable name="spaces-for-blank-context-desc">
|
---|
77 | <!-- * if the context-description field is blank, we'll need -->
|
---|
78 | <!-- * to pad out the message field with spaces to compensate -->
|
---|
79 | <xsl:choose>
|
---|
80 | <xsl:when test="$context-desc = ''">
|
---|
81 | <xsl:value-of select="$context-desc-field-length + 2"/>
|
---|
82 | <!-- * + 2 = length of colon-plus-space separator ": " -->
|
---|
83 | </xsl:when>
|
---|
84 | <xsl:otherwise>
|
---|
85 | <xsl:value-of select="0"/>
|
---|
86 | </xsl:otherwise>
|
---|
87 | </xsl:choose>
|
---|
88 | </xsl:variable>
|
---|
89 | <xsl:variable name="extra-spaces" select="$spaces-for-blank-level + $spaces-for-blank-context-desc"/>
|
---|
90 | <xsl:call-template name="pad-string">
|
---|
91 | <xsl:with-param name="leftRight">right</xsl:with-param>
|
---|
92 | <xsl:with-param name="padVar" select="substring($message, 1, ($message-field-length + $extra-spaces))"/>
|
---|
93 | <xsl:with-param name="length" select="$message-field-length + $extra-spaces"/>
|
---|
94 | </xsl:call-template>
|
---|
95 | </xsl:param>
|
---|
96 | ...
|
---|
97 | </xsl:template></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><xsl:template name="get.doc.title"/></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><xsl:template name="pad-string">
|
---|
229 | <xsl:param name="padChar" select="' '"/>
|
---|
230 | <xsl:param name="leftRight">left</xsl:param>
|
---|
231 | <xsl:param name="padVar"/>
|
---|
232 | <xsl:param name="length"/>
|
---|
233 | ...
|
---|
234 | </xsl:template></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 |
|
---|