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 common 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> |
---|