lib.xml

Revision 23dea7e00df87480acb58bb3398283c2bb227949, 45.5 kB (checked in by Theo Schlossnagle <jesus@omniti.com>, 2 years ago)
pull docs into master
Property mode set to `100644`

Line
1	<?xml version="1.0" encoding="utf-8"?>
2	<!DOCTYPE book
3	PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4	<book>
5	<bookinfo>
6	<title>XSL Library Template Reference</title>
7	<releaseinfo role="cvs">$Id: lib.xweb,v 1.13 2005/07/08 10:35:55 xmldoc Exp $
8	</releaseinfo>
9	<corpauthor>DocBook Open Repository Team</corpauthor>
10	<copyright>
11	<year>1999</year>
12	<year>2000</year>
13	<year>2001</year>
14	<year>2002</year>
15	<year>2005</year>
16	<holder>Norman Walsh</holder>
17	</copyright>
18	</bookinfo>
19
20	<preface><title>Introduction</title>
21
22	<para>This is technical reference documentation for the DocBook XSL
23	Stylesheets; it documents (some of) the parameters, templates, and
24	other elements of the stylesheets.</para>
25
26	<para>This is not intended to be <quote>user</quote> documentation.
27	It is provided for developers writing customization layers for the
28	stylesheets, and for anyone who's interested in <quote>how it
29	works</quote>.</para>
30
31	<para>Although I am trying to be thorough, this documentation is known
32	to be incomplete. Don't forget to read the source, too :-)</para>
33
34	</preface>
35
36	<reference>
37	<title>General Library Templates</title>
38
39	<refentry id="dot.count">
40	<refnamediv>
41	<refname>dot.count</refname>
42	<refpurpose>Returns the number of <quote>.</quote> characters in a string</refpurpose>
43	</refnamediv>
44
45	<refsect1><title>Description</title>
46
47	<programlisting format="linespecific"><programlisting id="dot.count.frag">
48	<xsl:template name="dot.count">
49	<!-- Returns the number of "." characters in a string -->
50	<xsl:param name="string"></xsl:param>
51	<xsl:param name="count" select="0"></xsl:param>
52	<xsl:choose>
53	<xsl:when test="contains($string, '.')">
54	<xsl:call-template name="dot.count">
55	<xsl:with-param name="string" select="substring-after($string, '.')"></xsl:with-param>
56	<xsl:with-param name="count" select="$count+1"></xsl:with-param>
57	</xsl:call-template>
58	</xsl:when>
59	<xsl:otherwise>
60	<xsl:value-of select="$count"></xsl:value-of>
61	</xsl:otherwise>
62	</xsl:choose>
63	</xsl:template>
64	</programlisting></programlisting>
65
66	</refsect1>
67	</refentry>
68
69
70
71	<refentry id="copy-string">
72	<refnamediv>
73	<refname>copy-string</refname>
74	<refpurpose>Returns <quote>count</quote> copies of a string</refpurpose>
75	</refnamediv>
76
77	<refsect1><title>Description</title>
78
79	<programlisting format="linespecific"><programlisting id="copy-string.frag">
80	<xsl:template name="copy-string">
81	<!-- returns 'count' copies of 'string' -->
82	<xsl:param name="string"></xsl:param>
83	<xsl:param name="count" select="0"></xsl:param>
84	<xsl:param name="result"></xsl:param>
85
86	<xsl:choose>
87	<xsl:when test="$count>0">
88	<xsl:call-template name="copy-string">
89	<xsl:with-param name="string" select="$string"></xsl:with-param>
90	<xsl:with-param name="count" select="$count - 1"></xsl:with-param>
91	<xsl:with-param name="result">
92	<xsl:value-of select="$result"></xsl:value-of>
93	<xsl:value-of select="$string"></xsl:value-of>
94	</xsl:with-param>
95	</xsl:call-template>
96	</xsl:when>
97	<xsl:otherwise>
98	<xsl:value-of select="$result"></xsl:value-of>
99	</xsl:otherwise>
100	</xsl:choose>
101	</xsl:template>
102	</programlisting></programlisting>
103
104	</refsect1>
105	</refentry>
106
107
108
109	<refentry id="string.subst">
110	<refnamediv>
111	<refname>string.subst</refname>
112	<refpurpose>Substitute one text string for another in a string</refpurpose>
113	</refnamediv>
114
115	<refsect1><title>Description</title>
116
117	<para>The <function moreinfo="none">string.subst</function> template replaces all
118	occurances of <parameter moreinfo="none">target</parameter> in <parameter moreinfo="none">string</parameter>
119	with <parameter moreinfo="none">replacement</parameter> and returns the result.
120	</para>
121
122	<programlisting format="linespecific"><programlisting id="string.subst.frag">
123	<xsl:template name="string.subst">
124	<xsl:param name="string"></xsl:param>
125	<xsl:param name="target"></xsl:param>
126	<xsl:param name="replacement"></xsl:param>
127
128	<xsl:choose>
129	<xsl:when test="contains($string, $target)">
130	<xsl:variable name="rest">
131	<xsl:call-template name="string.subst">
132	<xsl:with-param name="string" select="substring-after($string, $target)"></xsl:with-param>
133	<xsl:with-param name="target" select="$target"></xsl:with-param>
134	<xsl:with-param name="replacement" select="$replacement"></xsl:with-param>
135	</xsl:call-template>
136	</xsl:variable>
137	<xsl:value-of select="concat(substring-before($string, $target), $replacement, $rest)"></xsl:value-of>
138	</xsl:when>
139	<xsl:otherwise>
140	<xsl:value-of select="$string"></xsl:value-of>
141	</xsl:otherwise>
142	</xsl:choose>
143	</xsl:template>
144	</programlisting></programlisting>
145
146	</refsect1>
147	</refentry>
148
149
150
151	<refentry id="xpointer.idref">
152	<refnamediv>
153	<refname>xpointer.idref</refname>
154	<refpurpose>Extract IDREF from an XPointer</refpurpose>
155	</refnamediv>
156
157	<refsect1><title>Description</title>
158
159	<para>The <function moreinfo="none">xpointer.idref</function> template returns the
160	ID portion of an XPointer which is a pointer to an ID within the current
161	document, or the empty string if it is not.</para>
162	<para>In other words, <function moreinfo="none">xpointer.idref</function> returns
163	<quote>foo</quote> when passed either <literal moreinfo="none">#foo</literal>
164	or <literal moreinfo="none">#xpointer(id('foo'))</literal>, otherwise it returns
165	the empty string.</para>
166
167	<programlisting format="linespecific"><programlisting id="xpointer.idref.frag">
168	<xsl:template name="xpointer.idref">
169	<xsl:param name="xpointer">http://...</xsl:param>
170	<xsl:choose>
171	<xsl:when test="starts-with($xpointer, '#xpointer(id(')">
172	<xsl:variable name="rest" select="substring-after($xpointer, '#xpointer(id(')"></xsl:variable>
173	<xsl:variable name="quote" select="substring($rest, 1, 1)"></xsl:variable>
174	<xsl:value-of select="substring-before(substring-after($xpointer, $quote), $quote)"></xsl:value-of>
175	</xsl:when>
176	<xsl:when test="starts-with($xpointer, '#')">
177	<xsl:value-of select="substring-after($xpointer, '#')"></xsl:value-of>
178	</xsl:when>
179	<!-- otherwise it's a pointer to some other document -->
180	</xsl:choose>
181	</xsl:template>
182	</programlisting></programlisting>
183
184	</refsect1>
185	</refentry>
186
187
188
189
190	<refentry id="length-magnitude">
191	<refnamediv>
192	<refname>length-magnitude</refname>
193	<refpurpose>Return the unqualified dimension from a length specification</refpurpose>
194	</refnamediv>
195
196	<refsect1><title>Description</title>
197
198	<para>The <function moreinfo="none">length-magnitude</function> template returns the
199	unqualified length ("20" for "20pt") from a dimension.
200	</para>
201
202	<programlisting format="linespecific"><programlisting id="length-magnitude.frag">
203	<xsl:template name="length-magnitude">
204	<xsl:param name="length" select="'0pt'"></xsl:param>
205
206	<xsl:choose>
207	<xsl:when test="string-length($length) = 0"></xsl:when>
208	<xsl:when test="substring($length,1,1) = '0' or substring($length,1,1) = '1' or substring($length,1,1) = '2' or substring($length,1,1) = '3' or substring($length,1,1) = '4' or substring($length,1,1) = '5' or substring($length,1,1) = '6' or substring($length,1,1) = '7' or substring($length,1,1) = '8' or substring($length,1,1) = '9' or substring($length,1,1) = '.'">
209	<xsl:value-of select="substring($length,1,1)"></xsl:value-of>
210	<xsl:call-template name="length-magnitude">
211	<xsl:with-param name="length" select="substring($length,2)"></xsl:with-param>
212	</xsl:call-template>
213	</xsl:when>
214	</xsl:choose>
215	</xsl:template>
216	</programlisting></programlisting>
217
218	</refsect1>
219	</refentry>
220
221
222
223	<refentry id="length-units">
224	<refnamediv>
225	<refname>length-units</refname>
226	<refpurpose>Return the units from a length specification</refpurpose>
227	</refnamediv>
228
229	<refsect1><title>Description</title>
230
231	<para>The <function moreinfo="none">length-units</function> template returns the
232	units ("pt" for "20pt") from a length. If no units are supplied on the
233	length, the <parameter moreinfo="none">defauilt.units</parameter> are returned.</para>
234
235	<programlisting format="linespecific"><programlisting id="length-units.frag">
236	<xsl:template name="length-units">
237	<xsl:param name="length" select="'0pt'"></xsl:param>
238	<xsl:param name="default.units" select="'px'"></xsl:param>
239	<xsl:variable name="magnitude">
240	<xsl:call-template name="length-magnitude">
241	<xsl:with-param name="length" select="$length"></xsl:with-param>
242	</xsl:call-template>
243	</xsl:variable>
244
245	<xsl:variable name="units">
246	<xsl:value-of select="substring($length, string-length($magnitude)+1)"></xsl:value-of>
247	</xsl:variable>
248
249	<xsl:choose>
250	<xsl:when test="$units = ''">
251	<xsl:value-of select="$default.units"></xsl:value-of>
252	</xsl:when>
253	<xsl:otherwise>
254	<xsl:value-of select="$units"></xsl:value-of>
255	</xsl:otherwise>
256	</xsl:choose>
257	</xsl:template>
258	</programlisting></programlisting>
259
260	</refsect1>
261	</refentry>
262
263
264
265	<refentry id="length-spec">
266	<refnamediv>
267	<refname>length-spec</refname>
268	<refpurpose>Return a fully qualified length specification</refpurpose>
269	</refnamediv>
270
271	<refsect1><title>Description</title>
272
273	<para>The <function moreinfo="none">length-spec</function> template returns the
274	qualified length from a dimension. If an unqualified length is given,
275	the <parameter moreinfo="none">default.units</parameter> will be added to it.
276	</para>
277
278	<programlisting format="linespecific"><programlisting id="length-spec.frag">
279	<xsl:template name="length-spec">
280	<xsl:param name="length" select="'0pt'"></xsl:param>
281	<xsl:param name="default.units" select="'px'"></xsl:param>
282
283	<xsl:variable name="magnitude">
284	<xsl:call-template name="length-magnitude">
285	<xsl:with-param name="length" select="$length"></xsl:with-param>
286	</xsl:call-template>
287	</xsl:variable>
288
289	<xsl:variable name="units">
290	<xsl:value-of select="substring($length, string-length($magnitude)+1)"></xsl:value-of>
291	</xsl:variable>
292
293	<xsl:value-of select="$magnitude"></xsl:value-of>
294	<xsl:choose>
295	<xsl:when test="$units='cm' or $units='mm' or $units='in' or $units='pt' or $units='pc' or $units='px' or $units='em'">
296	<xsl:value-of select="$units"></xsl:value-of>
297	</xsl:when>
298	<xsl:when test="$units = ''">
299	<xsl:value-of select="$default.units"></xsl:value-of>
300	</xsl:when>
301	<xsl:otherwise>
302	<xsl:message>
303	<xsl:text>Unrecognized unit of measure: </xsl:text>
304	<xsl:value-of select="$units"></xsl:value-of>
305	<xsl:text>.</xsl:text>
306	</xsl:message>
307	</xsl:otherwise>
308	</xsl:choose>
309	</xsl:template>
310	</programlisting></programlisting>
311
312	</refsect1>
313	</refentry>
314
315
316
317	<refentry id="length-in-points">
318	<refnamediv>
319	<refname>length-in-points</refname>
320	<refpurpose>Returns the size, in points, of a specified length</refpurpose>
321	</refnamediv>
322
323	<refsect1><title>Description</title>
324
325	<para>The <function moreinfo="none">length-in-points</function> template converts a length
326	specification to points and returns that value as an unqualified
327	number.
328	</para>
329
330	<caution>
331	<para>There is no way for the template to infer the size of an
332	<literal moreinfo="none">em</literal>. It relies on the default <parameter moreinfo="none">em.size</parameter>
333	which is initially <literal moreinfo="none">10</literal> (for 10pt).</para>
334
335	<para>Similarly, converting pixels to points relies on the
336	<parameter moreinfo="none">pixels.per.inch</parameter> parameter which is initially
337	<literal moreinfo="none">90</literal>.
338	</para>
339	</caution>
340
341	<programlisting format="linespecific"><programlisting id="length-in-points.frag">
342	<xsl:template name="length-in-points">
343	<xsl:param name="length" select="'0pt'"></xsl:param>
344	<xsl:param name="em.size" select="10"></xsl:param>
345	<xsl:param name="pixels.per.inch" select="90"></xsl:param>
346
347	<xsl:variable name="magnitude">
348	<xsl:call-template name="length-magnitude">
349	<xsl:with-param name="length" select="$length"></xsl:with-param>
350	</xsl:call-template>
351	</xsl:variable>
352
353	<xsl:variable name="units">
354	<xsl:value-of select="substring($length, string-length($magnitude)+1)"></xsl:value-of>
355	</xsl:variable>
356
357	<xsl:choose>
358	<xsl:when test="$units = 'pt'">
359	<xsl:value-of select="$magnitude"></xsl:value-of>
360	</xsl:when>
361	<xsl:when test="$units = 'cm'">
362	<xsl:value-of select="$magnitude div 2.54 * 72.0"></xsl:value-of>
363	</xsl:when>
364	<xsl:when test="$units = 'mm'">
365	<xsl:value-of select="$magnitude div 25.4 * 72.0"></xsl:value-of>
366	</xsl:when>
367	<xsl:when test="$units = 'in'">
368	<xsl:value-of select="$magnitude * 72.0"></xsl:value-of>
369	</xsl:when>
370	<xsl:when test="$units = 'pc'">
371	<xsl:value-of select="$magnitude * 12.0"></xsl:value-of>
372	</xsl:when>
373	<xsl:when test="$units = 'px'">
374	<xsl:value-of select="$magnitude div $pixels.per.inch * 72.0"></xsl:value-of>
375	</xsl:when>
376	<xsl:when test="$units = 'em'">
377	<xsl:value-of select="$magnitude * $em.size"></xsl:value-of>
378	</xsl:when>
379	<xsl:otherwise>
380	<xsl:message>
381	<xsl:text>Unrecognized unit of measure: </xsl:text>
382	<xsl:value-of select="$units"></xsl:value-of>
383	<xsl:text>.</xsl:text>
384	</xsl:message>
385	</xsl:otherwise>
386	</xsl:choose>
387	</xsl:template>
388	</programlisting></programlisting>
389
390	</refsect1>
391	</refentry>
392
393
394
395	<refentry id="pi-attribute">
396	<refnamediv>
397	<refname>pi-attribute</refname>
398	<refpurpose>Extract a pseudo-attribute from a PI</refpurpose>
399	</refnamediv>
400
401	<refsect1><title>Description</title>
402
403	<para>The <function moreinfo="none">pi-attribute</function> template extracts a pseudo-attribute
404	from a processing instruction. For example, given the PI
405	<quote><literal moreinfo="none"><?foo bar="1" baz='red'?></literal></quote>,</para>
406	<programlisting format="linespecific"><xsl:call-template name="pi-attribute">
407	<xsl:with-param name="pis" select="processing-instruction('foo')"/>
408	<xsl:with-param name="attribute" select="'baz'"/>
409	</xsl:call-template></programlisting>
410	<para>will return <quote>red</quote>. This template returns the first matching
411	attribute that it finds. Presented with processing instructions that
412	contain badly formed pseudo-attributes (missing or unbalanced quotes,
413	for example), the template may silently return erroneous results.</para>
414
415	<programlisting format="linespecific"><programlisting id="pi-attribute.frag">
416	<xsl:template name="pi-attribute">
417	<xsl:param name="pis" select="processing-instruction('BOGUS_PI')"></xsl:param>
418	<xsl:param name="attribute">filename</xsl:param>
419	<xsl:param name="count">1</xsl:param>
420
421	<xsl:choose>
422	<xsl:when test="$count>count($pis)">
423	<!-- not found -->
424	</xsl:when>
425	<xsl:otherwise>
426	<xsl:variable name="pi">
427	<xsl:value-of select="$pis[$count]"></xsl:value-of>
428	</xsl:variable>
429	<xsl:variable name="pivalue">
430	<xsl:value-of select="concat(' ', normalize-space($pi))"></xsl:value-of>
431	</xsl:variable>
432	<xsl:choose>
433	<xsl:when test="contains($pivalue,concat(' ', $attribute, '='))">
434	<xsl:variable name="rest" select="substring-after($pivalue,concat(' ', $attribute,'='))"></xsl:variable>
435	<xsl:variable name="quote" select="substring($rest,1,1)"></xsl:variable>
436	<xsl:value-of select="substring-before(substring($rest,2),$quote)"></xsl:value-of>
437	</xsl:when>
438	<xsl:otherwise>
439	<xsl:call-template name="pi-attribute">
440	<xsl:with-param name="pis" select="$pis"></xsl:with-param>
441	<xsl:with-param name="attribute" select="$attribute"></xsl:with-param>
442	<xsl:with-param name="count" select="$count + 1"></xsl:with-param>
443	</xsl:call-template>
444	</xsl:otherwise>
445	</xsl:choose>
446	</xsl:otherwise>
447	</xsl:choose>
448	</xsl:template>
449	</programlisting></programlisting>
450
451	</refsect1>
452	</refentry>
453
454
455
456	<refentry id="lookup.key">
457	<refnamediv>
458	<refname>lookup.key</refname>
459	<refpurpose>Retrieve the value associated with a particular key in a table</refpurpose>
460	</refnamediv>
461
462	<refsect1><title>Description</title>
463
464	<para>Given a table of space-delimited key/value pairs,
465	the <function moreinfo="none">lookup.key</function> template extracts the value associated
466	with a particular key.</para>
467
468	<programlisting format="linespecific"><programlisting id="lookup.key.frag">
469	<xsl:template name="lookup.key">
470	<xsl:param name="key" select="''"></xsl:param>
471	<xsl:param name="table" select="''"></xsl:param>
472
473	<xsl:if test="contains($table, ' ')">
474	<xsl:choose>
475	<xsl:when test="substring-before($table, ' ') = $key">
476	<xsl:variable name="rest" select="substring-after($table, ' ')"></xsl:variable>
477	<xsl:choose>
478	<xsl:when test="contains($rest, ' ')">
479	<xsl:value-of select="substring-before($rest, ' ')"></xsl:value-of>
480	</xsl:when>
481	<xsl:otherwise>
482	<xsl:value-of select="$rest"></xsl:value-of>
483	</xsl:otherwise>
484	</xsl:choose>
485	</xsl:when>
486	<xsl:otherwise>
487	<xsl:call-template name="lookup.key">
488	<xsl:with-param name="key" select="$key"></xsl:with-param>
489	<xsl:with-param name="table" select="substring-after(substring-after($table,' '), ' ')"></xsl:with-param>
490	</xsl:call-template>
491	</xsl:otherwise>
492	</xsl:choose>
493	</xsl:if>
494	</xsl:template>
495	</programlisting></programlisting>
496
497	</refsect1>
498	</refentry>
499
500
501
502	<refentry id="xpath.location">
503	<refnamediv>
504	<refname>xpath.location</refname>
505	<refpurpose>Calculate the XPath child-sequence to the current node</refpurpose>
506	</refnamediv>
507
508	<refsect1><title>Description</title>
509
510	<para>The <function moreinfo="none">xpath.location</function> template calculates the
511	absolute path from the root of the tree to the current element node.
512	</para>
513
514	<programlisting format="linespecific"><programlisting id="xpath.location.frag">
515	<xsl:template name="xpath.location">
516	<xsl:param name="node" select="."></xsl:param>
517	<xsl:param name="path" select="''"></xsl:param>
518
519	<xsl:variable name="next.path">
520	<xsl:value-of select="local-name($node)"></xsl:value-of>
521	<xsl:if test="$path != ''">/</xsl:if>
522	<xsl:value-of select="$path"></xsl:value-of>
523	</xsl:variable>
524
525	<xsl:choose>
526	<xsl:when test="$node/parent::*">
527	<xsl:call-template name="xpath.location">
528	<xsl:with-param name="node" select="$node/parent::*"></xsl:with-param>
529	<xsl:with-param name="path" select="$next.path"></xsl:with-param>
530	</xsl:call-template>
531	</xsl:when>
532	<xsl:otherwise>
533	<xsl:text>/</xsl:text>
534	<xsl:value-of select="$next.path"></xsl:value-of>
535	</xsl:otherwise>
536	</xsl:choose>
537	</xsl:template>
538	</programlisting></programlisting>
539
540	</refsect1>
541	</refentry>
542
543
544
545	<refentry id="comment-escape-string">
546	<refnamediv>
547	<refname>comment-escape-string</refname>
548	<refpurpose>Prepare a string for inclusion in an XML comment</refpurpose>
549	</refnamediv>
550
551	<refsect1><title>Description</title>
552
553	<para>The <function moreinfo="none">comment-escape-string</function> template returns a string
554	that has been transformed so that it can safely be output as an XML comment.
555	Internal occurrences of "--" will be replaced with "- -" and a leading and/or
556	trailing space will be added to the string, if necessary.</para>
557
558	<programlisting format="linespecific"><programlisting id="comment-escape-string">
559	<xsl:template name="comment-escape-string">
560	<xsl:param name="string" select="''"></xsl:param>
561
562	<xsl:if test="starts-with($string, '-')">
563	<xsl:text> </xsl:text>
564	</xsl:if>
565
566	<xsl:call-template name="comment-escape-string.recursive">
567	<xsl:with-param name="string" select="$string"></xsl:with-param>
568	</xsl:call-template>
569
570	<xsl:if test="substring($string, string-length($string), 1) = '-'">
571	<xsl:text> </xsl:text>
572	</xsl:if>
573	</xsl:template>
574	</programlisting></programlisting>
575
576	</refsect1>
577	</refentry>
578
579
580
581	<refentry id="comment-escape-string.recursive">
582	<refnamediv>
583	<refname>comment-escape-string.recursive</refname>
584	<refpurpose>Internal function used by comment-escape-string</refpurpose>
585	</refnamediv>
586
587	<refsect1><title>Description</title>
588
589	<para>The <function moreinfo="none">comment-escape-string.recursive</function> template is used
590	by <function moreinfo="none">comment-escape-string</function>.</para>
591
592	<programlisting format="linespecific"><programlisting id="comment-escape-string.recursive">
593	<xsl:template name="comment-escape-string.recursive">
594	<xsl:param name="string" select="''"></xsl:param>
595	<xsl:choose>
596	<xsl:when test="contains($string, '--')">
597	<xsl:value-of select="substring-before($string, '--')"></xsl:value-of>
598	<xsl:value-of select="'- -'"></xsl:value-of>
599	<xsl:call-template name="comment-escape-string.recursive">
600	<xsl:with-param name="string" select="substring-after($string, '--')"></xsl:with-param>
601	</xsl:call-template>
602	</xsl:when>
603	<xsl:otherwise>
604	<xsl:value-of select="$string"></xsl:value-of>
605	</xsl:otherwise>
606	</xsl:choose>
607	</xsl:template>
608	</programlisting></programlisting>
609	</refsect1>
610	</refentry>
611
612
613
614	<refentry id="prepend-pad">
615	<refnamediv>
616	<refname>prepend-pad</refname>
617	<refpurpose>Right-pad a string out to a certain length</refpurpose>
618	</refnamediv>
619
620	<refsect1><title>Description</title>
621
622	<para>This function takes string <parameter moreinfo="none">padVar</parameter> and
623	pads it out to the string-length <parameter moreinfo="none">length</parameter>, using
624	string <parameter moreinfo="none">padChar</parameter> (a space character by default)
625	as the padding string (note that <parameter moreinfo="none">padChar</parameter> can be
626	a string; it is not limited to just being a single character).</para>
627
628	<note>
629	<para>This function is a copy of Nate Austin's
630	<function moreinfo="none">prepend-pad</function> function in the <ulink url="http://www.dpawson.co.uk/xsl/sect2/padding.html">Padding
631	Content</ulink> section of Dave Pawson's <ulink url="http://www.dpawson.co.uk/xsl/index.html">XSLT
632	FAQ</ulink>.</para>
633	</note>
634
635	<programlisting format="linespecific"><programlisting id="prepend-pad.frag">
636	<xsl:template name="prepend-pad">
637	<!-- recursive template to right justify and prepend-->
638	<!-- the value with whatever padChar is passed in -->
639	<xsl:param name="padChar" select="' '"></xsl:param>
640	<xsl:param name="padVar"></xsl:param>
641	<xsl:param name="length"></xsl:param>
642	<xsl:choose>
643	<xsl:when test="string-length($padVar) < $length">
644	<xsl:call-template name="prepend-pad">
645	<xsl:with-param name="padChar" select="$padChar"></xsl:with-param>
646	<xsl:with-param name="padVar" select="concat($padChar,$padVar)"></xsl:with-param>
647	<xsl:with-param name="length" select="$length"></xsl:with-param>
648	</xsl:call-template>
649	</xsl:when>
650	<xsl:otherwise>
651	<xsl:value-of select="substring($padVar,string-length($padVar) - $length + 1)"></xsl:value-of>
652	</xsl:otherwise>
653	</xsl:choose>
654	</xsl:template>
655	</programlisting></programlisting>
656
657	</refsect1>
658	</refentry>
659
660
661
662	<refentry id="str.tokenize.keep.delimiters">
663	<refnamediv>
664	<refname>str.tokenize.keep.delimiters</refname>
665	<refpurpose>Tokenize a string while preserving any delimiters</refpurpose>
666	</refnamediv>
667
668	<refsect1><title>Description</title>
669
670	<para>Based on the occurrence of one or more delimiter characters,
671	this function breaks a string into a list of tokens and delimiters,
672	marking up each of the tokens with a <sgmltag>token</sgmltag> element
673	and preserving the delimiters as text nodes between the tokens.</para>
674
675	<note>
676	<para>This function is a very slightly modified version of a
677	function from the <ulink url="http://www.exslt.org/">EXSLT
678	site</ulink>. The original is available at:
679
680	<blockquote><para><ulink url="http://www.exslt.org/str/functions/tokenize/str.tokenize.template.xsl"/></para></blockquote>
681
682	The <function moreinfo="none">str.tokenize.keep.delimiters</function> function
683	differs only in that it preserves the delimiters instead of
684	discarding them.</para>
685	</note>
686
687	<programlisting format="linespecific"><programlisting id="str.tokenize.keep.delimiters.frag">
688
689	<xsl:template name="str.tokenize.keep.delimiters">
690	<xsl:param name="string" select="''"></xsl:param>
691	<xsl:param name="delimiters" select="' '"></xsl:param>
692	<xsl:choose>
693	<xsl:when test="not($string)"></xsl:when>
694	<xsl:when test="not($delimiters)">
695	<xsl:call-template name="str.tokenize.keep.delimiters-characters">
696	<xsl:with-param name="string" select="$string"></xsl:with-param>
697	</xsl:call-template>
698	</xsl:when>
699	<xsl:otherwise>
700	<xsl:call-template name="str.tokenize.keep.delimiters-delimiters">
701	<xsl:with-param name="string" select="$string"></xsl:with-param>
702	<xsl:with-param name="delimiters" select="$delimiters"></xsl:with-param>
703	</xsl:call-template>
704	</xsl:otherwise>
705	</xsl:choose>
706	</xsl:template>
707
708	<xsl:template name="str.tokenize.keep.delimiters-characters">
709	<xsl:param name="string"></xsl:param>
710	<xsl:if test="$string">
711	<token><xsl:value-of select="substring($string, 1, 1)"></xsl:value-of></token>
712	<xsl:call-template name="str.tokenize.keep.delimiters-characters">
713	<xsl:with-param name="string" select="substring($string, 2)"></xsl:with-param>
714	</xsl:call-template>
715	</xsl:if>
716	</xsl:template>
717
718	<xsl:template name="str.tokenize.keep.delimiters-delimiters">
719	<xsl:param name="string"></xsl:param>
720	<xsl:param name="delimiters"></xsl:param>
721	<xsl:variable name="delimiter" select="substring($delimiters, 1, 1)"></xsl:variable>
722	<xsl:choose>
723	<xsl:when test="not($delimiter)">
724	<token><xsl:value-of select="$string"></xsl:value-of></token>
725	</xsl:when>
726	<xsl:when test="contains($string, $delimiter)">
727	<xsl:if test="not(starts-with($string, $delimiter))">
728	<xsl:call-template name="str.tokenize.keep.delimiters-delimiters">
729	<xsl:with-param name="string" select="substring-before($string, $delimiter)"></xsl:with-param>
730	<xsl:with-param name="delimiters" select="substring($delimiters, 2)"></xsl:with-param>
731	</xsl:call-template>
732	</xsl:if>
733	<!-- output each delimiter -->
734	<xsl:value-of select="$delimiter"></xsl:value-of>
735	<xsl:call-template name="str.tokenize.keep.delimiters-delimiters">
736	<xsl:with-param name="string" select="substring-after($string, $delimiter)"></xsl:with-param>
737	<xsl:with-param name="delimiters" select="$delimiters"></xsl:with-param>
738	</xsl:call-template>
739	</xsl:when>
740	<xsl:otherwise>
741	<xsl:call-template name="str.tokenize.keep.delimiters-delimiters">
742	<xsl:with-param name="string" select="$string"></xsl:with-param>
743	<xsl:with-param name="delimiters" select="substring($delimiters, 2)"></xsl:with-param>
744	</xsl:call-template>
745	</xsl:otherwise>
746	</xsl:choose>
747	</xsl:template>
748	</programlisting></programlisting>
749
750	</refsect1>
751	</refentry>
752
753
754
755	<refentry id="apply-string-subst-map">
756	<refnamediv>
757	<refname>apply-string-subst-map</refname>
758	<refpurpose>Apply a string-substitution map</refpurpose>
759	</refnamediv>
760
761	<refsect1><title>Description</title>
762
763	<para>This function applies a "string substitution" map. Use it when
764	you want to do multiple string substitutions on the same target
765	content. It reads in two things: <parameter moreinfo="none">content</parameter>, the
766	content on which to perform the substitution, and
767	<parameter moreinfo="none">map.contents</parameter>, a node set of
768	elements (the names of the elements don't matter), with each element
769	having the following attributes:
770	<itemizedlist>
771	<listitem>
772	<simpara><tag class="attribute">oldstring</tag>, a string to
773	be replaced</simpara>
774	</listitem>
775	<listitem>
776	<simpara><tag class="attribute">newstring</tag>, a string with
777	which to replace <tag class="attribute">oldstring</tag></simpara>
778	</listitem>
779	</itemizedlist>
780	The function uses <parameter moreinfo="none">map.contents</parameter> to
781	do substitution on <parameter moreinfo="none">content</parameter>, and then
782	returns the modified contents.</para>
783
784	<note>
785	<para>This function is a very slightly modified version of Jeni
786	Tennison's <function moreinfo="none">replace_strings</function> function in the
787	<ulink url="http://www.dpawson.co.uk/xsl/sect2/StringReplace.html#d9351e13">multiple string replacements</ulink> section of Dave Pawson's
788	<ulink url="http://www.dpawson.co.uk/xsl/index.html">XSLT
789	FAQ</ulink>.</para>
790
791	<para>The <function moreinfo="none">apply-string-subst-map</function> function is
792	essentially the same function as the
793	<function moreinfo="none">apply-character-map</function> function; the only
794	difference is that in the map that
795	<function moreinfo="none">apply-string-subst-map</function> expects, <tag class="attribute">oldstring</tag> and <tag class="attribute">newstring</tag> attributes are used instead of
796	<tag class="attribute">character</tag> and <tag class="attribute">string</tag> attributes.</para>
797	</note>
798
799	<programlisting format="linespecific"><programlisting id="apply-string-subst-map.frag">
800	<xsl:template name="apply-string-subst-map">
801	<xsl:param name="content"></xsl:param>
802	<xsl:param name="map.contents"></xsl:param>
803	<xsl:variable name="replaced_text">
804	<xsl:call-template name="string.subst">
805	<xsl:with-param name="string" select="$content"></xsl:with-param>
806	<xsl:with-param name="target" select="$map.contents[1]/@oldstring"></xsl:with-param>
807	<xsl:with-param name="replacement" select="$map.contents[1]/@newstring"></xsl:with-param>
808	</xsl:call-template>
809	</xsl:variable>
810	<xsl:choose>
811	<xsl:when test="$map.contents[2]">
812	<xsl:call-template name="apply-string-subst-map">
813	<xsl:with-param name="content" select="$replaced_text"></xsl:with-param>
814	<xsl:with-param name="map.contents" select="$map.contents[position() > 1]"></xsl:with-param>
815	</xsl:call-template>
816	</xsl:when>
817	<xsl:otherwise>
818	<xsl:value-of select="$replaced_text"></xsl:value-of>
819	</xsl:otherwise>
820	</xsl:choose>
821	</xsl:template>
822
823	</programlisting></programlisting>
824	</refsect1>
825	</refentry>
826
827
828
829	<refentry id="apply-character-map">
830	<refnamediv>
831	<refname>apply-character-map</refname>
832	<refpurpose>Apply an XSLT character map</refpurpose>
833	</refnamediv>
834
835	<refsect1><title>Description</title>
836
837	<para>This function applies an <ulink url="http://www.w3.org/TR/xslt20/#character-maps">XSLT character
838	map</ulink>; that is, it cause certain individual characters to be
839	substituted with strings of one or more characters. It is useful
840	mainly for replacing multiple "special" chararacters or symbols in
841	the same target content. It reads in two things:
842	<parameter moreinfo="none">content</parameter>, the content on which to perform the
843	substitution, and <parameter moreinfo="none">map.contents</parameter>, a
844	node set of elements (the names of the elements don't matter), with
845	each element having the following attributes:
846	<itemizedlist>
847	<listitem>
848	<simpara><tag class="attribute">character</tag>, a character to
849	be replaced</simpara>
850	</listitem>
851	<listitem>
852	<simpara><tag class="attribute">string</tag>, a string with
853	which to replace <tag class="attribute">character</tag></simpara>
854	</listitem>
855	</itemizedlist>
856	This function uses <parameter moreinfo="none">map.contents</parameter> to
857	do substitution on <parameter moreinfo="none">content</parameter>, and then returns
858	the modified contents.</para>
859
860	<note>
861	<para>This function is a very slightly modified version of Jeni
862	Tennison's <function moreinfo="none">replace_strings</function> function in the
863	<ulink url="http://www.dpawson.co.uk/xsl/sect2/StringReplace.html#d9351e13">multiple string replacements</ulink> section of Dave Pawson's
864	<ulink url="http://www.dpawson.co.uk/xsl/index.html">XSLT
865	FAQ</ulink>.</para>
866
867	<para>The <function moreinfo="none">apply-string-subst-map</function> function is
868	essentially the same function as the
869	<function moreinfo="none">apply-character-map</function> function; the only
870	difference is that in the map that
871	<function moreinfo="none">apply-string-subst-map</function> expects, <tag class="attribute">oldstring</tag> and <tag class="attribute">newstring</tag> attributes are used instead of
872	<tag class="attribute">character</tag> and <tag class="attribute">string</tag> attributes.</para>
873	</note>
874
875	<programlisting format="linespecific"><programlisting id="apply-character-map.frag">
876	<xsl:template name="apply-character-map">
877	<xsl:param name="content"></xsl:param>
878	<xsl:param name="map.contents"></xsl:param>
879	<xsl:variable name="replaced_text">
880	<xsl:call-template name="string.subst">
881	<xsl:with-param name="string" select="$content"></xsl:with-param>
882	<xsl:with-param name="target" select="$map.contents[1]/@character"></xsl:with-param>
883	<xsl:with-param name="replacement" select="$map.contents[1]/@string"></xsl:with-param>
884	</xsl:call-template>
885	</xsl:variable>
886	<xsl:choose>
887	<xsl:when test="$map.contents[2]">
888	<xsl:call-template name="apply-character-map">
889	<xsl:with-param name="content" select="$replaced_text"></xsl:with-param>
890	<xsl:with-param name="map.contents" select="$map.contents[position() > 1]"></xsl:with-param>
891	</xsl:call-template>
892	</xsl:when>
893	<xsl:otherwise>
894	<xsl:value-of select="$replaced_text"></xsl:value-of>
895	</xsl:otherwise>
896	</xsl:choose>
897	</xsl:template>
898
899	</programlisting></programlisting>
900	</refsect1>
901	</refentry>
902
903
904
905	<refentry id="read-character-map">
906	<refnamediv>
907	<refname>read-character-map</refname>
908	<refpurpose>Read in all or part of an XSLT character map</refpurpose>
909	</refnamediv>
910
911	<refsect1><title>Description</title>
912
913	<para>The XSLT 2.0 specification describes <ulink url="http://www.w3.org/TR/xslt20/#character-maps">character
914	maps</ulink> and explains how they may be used to allow a specific
915	character appearing in a text or attribute node in a final results
916	tree to be substituted by a specified string of characters during
917	serialization. The <function moreinfo="none">read-character-map</function> function
918	provides a means for reading and using character maps with XSLT
919	1.0-based tools.</para>
920
921	<para>It reads the character-map contents from
922	<parameter moreinfo="none">uri</parameter> (in full or in part, depending on the value
923	of the <parameter moreinfo="none">use.subset</parameter> parameter), then passes those
924	contents to the <function moreinfo="none">apply-character-map</function> function,
925	along with <parameter moreinfo="none">content</parameter>, the data on which to
926	perform the character substition.</para>
927
928	<para>Using the character map "in part" means that it uses only those
929	<tag>output-character</tag> elements that match the XPATH expression
930	given in the value of the <parameter moreinfo="none">subset.profile</parameter>
931	parameter. The current implementation of that capability here relies
932	on the <function moreinfo="none">evaluate</function> extension XSLT function.</para>
933
934	<programlisting format="linespecific"><programlisting id="read-character-map.frag">
935	<xsl:template name="read-character-map">
936	<xsl:param name="use.subset"></xsl:param>
937	<xsl:param name="subset.profile"></xsl:param>
938	<xsl:param name="uri"></xsl:param>
939	<xsl:choose>
940	<xsl:when test="$use.subset != 0">
941	<!-- use a subset of the character map instead of the full map -->
942	<xsl:choose>
943	<!-- xsltproc and Xalan both support dyn:evaluate() -->
944	<xsl:when test="function-available('dyn:evaluate')">
945	<xsl:copy-of select="document($uri)//*[local-name()='output-character'] [dyn:evaluate($subset.profile)]"></xsl:copy-of>
946	</xsl:when>
947	<!-- Saxon has its own evaluate() & doesn't support dyn:evaluate() -->
948	<xsl:when test="function-available('saxon:evaluate')">
949	<xsl:copy-of select="document($uri)//*[local-name()='output-character'] [saxon:evaluate($subset.profile)]"></xsl:copy-of>
950	</xsl:when>
951	<xsl:otherwise>
952	<xsl:message terminate="yes">
953	Error: To process character-map subsets, you must use an XSLT engine
954	that supports the evaluate() XSLT extension function. Your XSLT engine
955	does not support it.
956	</xsl:message>
957	</xsl:otherwise>
958	</xsl:choose>
959	</xsl:when>
960	<xsl:otherwise>
961	<!-- value of $use.subet is non-zero, so use the full map -->
962	<xsl:copy-of select="document($uri)//*[local-name()='output-character']"></xsl:copy-of>
963	</xsl:otherwise>
964	</xsl:choose>
965	</xsl:template>
966	</programlisting></programlisting>
967	</refsect1>
968	</refentry>
969
970	</reference>
971
972
973
974	<reference>
975	<title>Relative URI Functions</title>
976
977	<partintro><title>Introduction</title>
978
979	<para>These functions manipulate relative URI references.</para>
980
981	<para>The following assumptions must hold true:</para>
982
983	<orderedlist inheritnum="ignore" continuation="restarts">
984	<listitem>
985	<para>All URIs are relative.</para>
986	</listitem>
987	<listitem>
988	<para>No URI contains the <quote><literal moreinfo="none">../</literal></quote> sequence
989	which would effectively move <quote>up</quote> the hierarchy.</para>
990	</listitem>
991	</orderedlist>
992
993	<para>If these assumptions do not hold, the results are unpredictable.</para>
994
995	</partintro>
996
997
998
999	<refentry id="count.uri.path.depth">
1000	<refnamediv>
1001	<refname>count.uri.path.depth</refname>
1002	<refpurpose>Count the number of path components in a relative URI</refpurpose>
1003	</refnamediv>
1004
1005	<refsect1><title>Description</title>
1006
1007	<para>This function counts the number of path components in a relative URI.</para>
1008
1009	<programlisting format="linespecific"><programlisting id="count.uri.path.depth.frag">
1010	<xsl:template name="count.uri.path.depth">
1011	<xsl:param name="filename" select="''"></xsl:param>
1012	<xsl:param name="count" select="0"></xsl:param>
1013
1014	<xsl:choose>
1015	<xsl:when test="contains($filename, '/')">
1016	<xsl:call-template name="count.uri.path.depth">
1017	<xsl:with-param name="filename" select="substring-after($filename, '/')"></xsl:with-param>
1018	<xsl:with-param name="count" select="$count + 1"></xsl:with-param>
1019	</xsl:call-template>
1020	</xsl:when>
1021	<xsl:otherwise>
1022	<xsl:value-of select="$count"></xsl:value-of>
1023	</xsl:otherwise>
1024	</xsl:choose>
1025	</xsl:template>
1026	</programlisting></programlisting>
1027
1028	</refsect1>
1029	</refentry>
1030
1031
1032
1033	<refentry id="trim.common.uri.paths">
1034	<refnamediv>
1035	<refname>trim.common.uri.paths</refname>
1036	<refpurpose>Trim common leading path components from a relative URI</refpurpose>
1037	</refnamediv>
1038
1039	<refsect1><title>Description</title>
1040
1041	<para>This function trims common leading path components from a relative URI.</para>
1042
1043	<programlisting format="linespecific"><programlisting id="trim.common.uri.paths.frag">
1044	<xsl:template name="trim.common.uri.paths">
1045	<xsl:param name="uriA" select="''"></xsl:param>
1046	<xsl:param name="uriB" select="''"></xsl:param>
1047	<xsl:param name="return" select="'A'"></xsl:param>
1048
1049	<xsl:choose>
1050	<xsl:when test="contains($uriA, '/') and contains($uriB, '/') and substring-before($uriA, '/') = substring-before($uriB, '/')">
1051	<xsl:call-template name="trim.common.uri.paths">
1052	<xsl:with-param name="uriA" select="substring-after($uriA, '/')"></xsl:with-param>
1053	<xsl:with-param name="uriB" select="substring-after($uriB, '/')"></xsl:with-param>
1054	<xsl:with-param name="return" select="$return"></xsl:with-param>
1055	</xsl:call-template>
1056	</xsl:when>
1057	<xsl:otherwise>
1058	<xsl:choose>
1059	<xsl:when test="$return = 'A'">
1060	<xsl:value-of select="$uriA"></xsl:value-of>
1061	</xsl:when>
1062	<xsl:otherwise>
1063	<xsl:value-of select="$uriB"></xsl:value-of>
1064	</xsl:otherwise>
1065	</xsl:choose>
1066	</xsl:otherwise>
1067	</xsl:choose>
1068	</xsl:template>
1069	</programlisting></programlisting>
1070
1071	</refsect1>
1072	</refentry>
1073
1074	</reference>
1075
1076
1077
1078	<appendix><title>The Stylesheet</title>
1079
1080	<para>The <filename moreinfo="none">lib.xsl</filename> stylesheet is just a wrapper
1081	around these functions.</para>
1082
1083	<programlisting id="top">
1084
1085	<!-- ********************************************************************
1086	$Id: lib.xweb,v 1.13 2005/07/08 10:35:55 xmldoc Exp $
1087	********************************************************************
1088
1089	This file is part of the XSL DocBook Stylesheet distribution.
1090	See ../README or http://nwalsh.com/docbook/xsl/ for copyright
1091	and other information.
1092
1093	This module implements DTD-independent functions
1094
1095	******************************************************************** -->
1096
1097	<xsl:stylesheet exclude-result-prefixes="src" version="1.0">
1098
1099	<src:fragref linkend="dot.count.frag"></src:fragref>
1100	<src:fragref linkend="copy-string.frag"></src:fragref>
1101	<src:fragref linkend="string.subst.frag"></src:fragref>
1102	<src:fragref linkend="xpointer.idref.frag"></src:fragref>
1103	<src:fragref linkend="length-magnitude.frag"></src:fragref>
1104	<src:fragref linkend="length-units.frag"></src:fragref>
1105	<src:fragref linkend="length-spec.frag"></src:fragref>
1106	<src:fragref linkend="length-in-points.frag"></src:fragref>
1107	<src:fragref linkend="pi-attribute.frag"></src:fragref>
1108	<src:fragref linkend="lookup.key.frag"></src:fragref>
1109	<src:fragref linkend="xpath.location.frag"></src:fragref>
1110	<src:fragref linkend="comment-escape-string"></src:fragref>
1111	<src:fragref linkend="comment-escape-string.recursive"></src:fragref>
1112	<src:fragref linkend="prepend-pad.frag"></src:fragref>
1113	<src:fragref linkend="str.tokenize.keep.delimiters.frag"></src:fragref>
1114	<src:fragref linkend="apply-string-subst-map.frag"></src:fragref>
1115	<src:fragref linkend="apply-character-map.frag"></src:fragref>
1116	<src:fragref linkend="read-character-map.frag"></src:fragref>
1117	<src:fragref linkend="count.uri.path.depth.frag"></src:fragref>
1118	<src:fragref linkend="trim.common.uri.paths.frag"></src:fragref>
1119
1120	</xsl:stylesheet>
1121	</programlisting>
1122
1123	</appendix>
1124	</book>

Note: See TracBrowser for help on using the browser.

root/docs/docbook-xsl/lib/lib.xml

Download in other formats: