1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
|
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>XSL processing model</title><link rel="stylesheet" href="reference.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.37"><link rel="home" href="index.html" title="DocBook XSL Stylesheet Documentation"><link rel="up" href="publishing.html" title="Chapter 1. DocBook XSL"><link rel="previous" href="ch01s02.html" title="A brief introduction to XSL"><link rel="next" href="ch01s04.html" title="Customizing DocBook XSL stylesheets"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">XSL processing model</th></tr><tr><td width="20%" align="left"><a href="ch01s02.html">Prev</a> </td><th width="60%" align="center">Chapter 1. DocBook XSL</th><td width="20%" align="right"> <a href="ch01s04.html">Next</a></td></tr></table><hr></div><p>XSL is a template language, not a procedural
language. That means a stylesheet specifies a sample of the
output, not a sequence of programming steps to generate it.
A stylesheet consists of a mixture of output samples with
instructions of what to put in each sample. Each bit of
output sample and instructions is called
a <i>template</i>.</p><p>In general, you write a template for each element
type in your document. That lets you concentrate on
handling just one element at a time, and keeps a stylesheet
modular. The power of XSL comes from processing the
templates recursively. That is, each template handles the
processing of its own element, and then calls other
templates to process its children, and so on. Since an XML
document is always a single root element at the top level
that contains all of the nested descendent elements, the
XSL templates also start at the top and work their way down
through the hierarchy of elements.</p><p>Take the
DocBook <tt><para></tt> paragraph element as
an example. To convert this to HTML, you want to wrap the
paragraph content with the HTML
tags <tt><p></tt> and <tt></p></tt>.
But a DocBook <tt><para></tt> can contain
any number of in-line DocBook elements marking up the text.
Fortunately, you can let other templates take care of those
elements, so your XSL template
for <tt><para></tt> can be quite
simple:</p><pre class="programlisting"><xsl:template match="para">
<p>
<xsl:apply-templates/>
</p>
</xsl:template>
</pre><p>The <tt><xsl:template></tt> element
starts a new template, and
its <tt>match</tt> attribute indicates where to
apply the template, in this case to
any <tt><para></tt> elements. The template
says to output a literal <tt><p></tt> string
and then execute
the <tt><xsl:apply-templates/></tt> instruction.
This tells the XSL processor to look among all the
templates in the stylesheet for any that should be applied
to the content of the paragraph. If each template in the
stylesheet includes
an <tt><xsl:apply-templates/></tt> instruction,
then all descendents will eventually be processed. When it
is through recursively applying templates to the paragraph
content, it outputs the <tt></p></tt> closing
tag.</p><div class="sect2"><a name="c44b1b3b6b7"></a><div class="titlepage"><div><h3 class="title"><a name="c44b1b3b6b7"></a>Context is important</h3></div></div><p>Since you aren't writing a linear procedure to
process your document, the context of where and how to
apply each modular template is important.
The <tt>match</tt> attribute
of <tt><xsl:template></tt> provides that
context for most templates. There is an entire expression
language, XPath, for identifying what parts of your
document should be handled by each template. The simplest
context is just an element name, as in the example above.
But you can also specify elements as children of other
elements, elements with certain attribute values, the first
or last elements in a sequence, and so on. Here is how the
DocBook <tt><formalpara></tt> element is
handled:</p><pre class="programlisting"><xsl:template match="formalpara">
<p>
<xsl:apply-templates/>
</p>
</xsl:template>
<xsl:template match="formalpara/title">
<b><xsl:apply-templates/></b>
<xsl:text> </xsl:text>
</xsl:template>
<xsl:template match="formalpara/para">
<xsl:apply-templates/>
</xsl:template>
</pre><p>There are three templates defined, one for
the <tt><formalpara></tt> element itself,
and one for each of its children elements. The <tt>match</tt> attribute
value <tt>formalpara/title</tt> in the second
template is an XPath expression indicating
a <tt><title></tt> element that is an
immediate child of
a <tt><formalpara></tt> element. This
distinguishes such titles from
other <tt><title></tt> elements used in
DocBook. XPath expressions are the key to controlling how
your templates are applied.</p><p>In general, the XSL processor has internal rules that
apply templates that are more specific before templates
that are less specific. That lets you control the details,
but also provides a fallback mechanism to a less specific
template when you don't supply the full context for every
combination of elements. This feature is illustrated by the
third template, for <tt>formalpara/para</tt>. By
including this template, the stylesheet processes a <tt><para></tt> within <tt><formalpara></tt> in
a special way, in this case by not outputting the HTML <tt><p></tt> tags already output by its parent. If this template had not been included, then the processor would have fallen back to the template
specified by <tt>match="para"</tt> described
above, which would have output a second set of <tt><p></tt> tags.</p><p>You can also control template context with
XSL <i>modes</i>, which are used extensively
in the DocBook stylesheets. Modes let you process the same
input more than once in different ways.
A <tt>mode</tt> attribute in
an <tt><xsl:template></tt> definition adds a
specific mode name to that template. When the same mode
name is used
in <tt><xsl:apply-templates/></tt>, it acts
as a filter to narrow the selection of templates to only
those selected by
the <tt>match</tt> expression <i>and</i> that
have that mode name. This lets you define two different
templates for the same element match that are applied under
different contexts. For example, there are two templates
defined for
DocBook <tt><listitem></tt> elements:</p><pre class="programlisting"><xsl:template match="listitem">
<li><xsl:apply-templates/></li>
</xsl:template>
<xsl:template match="listitem" mode="xref">
<xsl:number format="1"/>
</xsl:template>
</pre><p>The first template is for the normal list item
context where you want to output the
HTML <tt><li></tt> tags. The second template
is called with <tt><xsl:apply-templates
select="$target" mode="xref"/></tt> in the context
of processing <tt><xref></tt> elements. In
this case the <tt>select</tt> attribute locates
the ID of the specific list item and
the <tt>mode</tt> attribute selects the second
template, whose effect is to output its item number when it
is in an ordered list. Because there are many such special
needs when
processing <tt><xref></tt> elements, it is
convenient to define a mode name <tt>xref</tt> to
handle them all. Keep in mind that mode settings
do <i>not</i> automatically get passed down to
other templates
through <tt><xsl:apply-templates/></tt>.</p></div><div class="sect2"><a name="c44b1b3b6b8"></a><div class="titlepage"><div><h3 class="title"><a name="c44b1b3b6b8"></a>Programming features</h3></div></div><p>Although XSL is template-driven, it also has some
features of traditional programming languages. Here are
some examples from the DocBook stylesheets. </p><pre class="programlisting">Assign a value to a variable:
<xsl:variable name="refelem" select="name($target)"/>
If statement:
<xsl:if test="$show.comments">
<i><xsl:call-template name="inline.charseq"/></i>
</xsl:if>
Case statement:
<xsl:choose>
<xsl:when test="@columns">
<xsl:value-of select="@columns"/>
</xsl:when>
<xsl:otherwise>1</xsl:otherwise>
</xsl:choose>
Call a template by name like a subroutine, passing parameter values and accepting a return value:
<xsl:call-template name="xref.xreflabel">
<xsl:with-param name="target" select="$target"/>
</xsl:call-template>
</pre><p>However, you can't always use these constructs as you
do in other programming languages. Variables in particular
have very different behavior.</p><div class="sect3"><a name="c44b1b3b6b8b5"></a><div class="titlepage"><div><h4 class="title"><a name="c44b1b3b6b8b5"></a>Using variables and parameters</h4></div></div><p>XSL provides two elements that let you assign a value
to a
name: <tt><xsl:variable></tt> and <tt><xsl:param></tt>.
These share the same name space and syntax for assigning
names and values. Both can be referred to using
the <tt>$name</tt> syntax. The main difference
between these two elements is that a param's value acts as
a default value that can be overridden when a template is
called using
a <tt><xsl:with-param></tt> element as in the
last example above.</p><p>Here are two examples from DocBook:</p><pre class="programlisting"><xsl:param name="cols">1</xsl:param>
<xsl:variable name="segnum" select="position()"/>
</pre><p>In both elements, the name of the parameter or
variable is specified with
the <tt>name</tt> attribute. So the name of
the <tt>param</tt> here
is <tt>cols</tt> and the name of
the <tt>variable</tt> is <tt>segnum</tt>.
The value of either can be supplied in two ways. The value
of the first example is the text node "1" and is supplied
as the content of the element. The value of the second
example is supplied as the result of the expression in
its <tt>select</tt> attribute, and the element
itself has no content.</p><p>The feature of XSL variables that is odd to new users
is that once you assign a value to a variable, you cannot
assign a new value within the same scope. Doing so will
generate an error. So variables are not used as dynamic
storage bins they way they are in other languages. They
hold a fixed value within their scope of application, and
then disappear when the scope is exited. This feature is a
result of the design of XSL, which is template-driven and
not procedural. This means there is no definite order of
processing, so you can't rely on the values of changing
variables. To use variables in XSL, you need to understand
how their scope is defined.</p><p>Variables defined outside of all templates are
considered global variables, and they are readable within
all templates. The value of a global variable is fixed, and
its global value can't be altered from within any template.
However, a template can create a local variable of the same
name and give it a different value. That local value
remains in effect only within the scope of the local
variable.</p><p>Variables defined within a template remain in effect
only within their permitted scope, which is defined as all
following siblings and their descendants. To understand
such a scope, you have to remember that XSL instructions
are true XML elements that are embedded in an XML family
hierarchy of XSL elements, often referred to as parents,
children, siblings, ancestors and descendants. Taking the
family analogy a step further, think of a variable
assignment as a piece of advice that you are allowed to
give to certain family members. You can give your advice
only to your younger siblings (those that follow you) and
their descendents. Your older siblings won't listen,
neither will your parents or any of your ancestors. To
stretch the analogy a bit, it is an error to try to give
different advice under the same name to the same group of
listeners (in other words, to redefine the variable). Keep
in mind that this family is not the elements of your
document, but just the XSL instructions in your stylesheet.
To help you keep track of such scopes in hand-written
stylesheets, it helps to indent nested XSL elements. Here
is an edited snippet from the DocBook stylesheet
file <tt>pi.xsl</tt> that illustrates different
scopes for two variables:</p><pre class="programlisting">
1 <xsl:template name="dbhtml-attribute">
2 ...
3 <xsl:choose>
4 <xsl:when test="$count>count($pis)">
5 <!-- not found -->
6 </xsl:when>
7 <xsl:otherwise>
8 <xsl:variable name="pi">
9 <xsl:value-of select="$pis[$count]"/>
10 </xsl:variable>
11 <xsl:choose>
12 <xsl:when test="contains($pi,concat($attribute, '='))">
13 <xsl:variable name="rest" select="substring-after($pi,concat($attribute,'='))"/>
14 <xsl:variable name="quote" select="substring($rest,1,1)"/>
15 <xsl:value-of select="substring-before(substring($rest,2),$quote)"/>
16 </xsl:when>
17 <xsl:otherwise>
18 ...
19 </xsl:otherwise>
20 </xsl:choose>
21 </xsl:otherwise>
22 </xsl:choose>
23 </xsl:template>
</pre><p>The scope of the variable <tt>pi</tt> begins
on line 8 where it is defined in this template, and ends on
line 20 when its last sibling ends.<sup>[<a name="c44b1b3b6b8b5c10b4" href="#ftn.c44b1b3b6b8b5c10b4">1</a>]</sup> The scope of the
variable <tt>rest</tt> begins on line 13 and ends
on line 15. Fortunately, line 15 outputs an expression
using the value before it goes out of scope.</p><p>What happens when
an <tt><xsl:apply-templates/></tt> element
is used within the scope of a local variable? Do the
templates that are applied to the document children get the
variable? The answer is no. The templates that are applied
are not actually within the scope of the variable. They
exist elsewhere in the stylesheet and are not following
siblings or their descendants. </p><p>To pass a value to another template, you pass a
parameter using
the <tt><xsl:with-param></tt> element. This
parameter passing is usually done with calls to a specific
named template
using <tt><xsl:call-template></tt>, although
it works
with <tt><xsl:apply-templates></tt> too.
That's because the called template must be expecting the
parameter by defining it using
a <tt><xsl:param></tt> element with the same
parameter name. Any passed parameters whose names are not
defined in the called template are ignored.</p><p>Here is an example of parameter passing
from <tt>docbook.xsl</tt>:</p><pre class="programlisting"><xsl:call-template name="head.content">
<xsl:with-param name="node" select="$doc"/>
</xsl:call-template>
</pre><p>Here a template
named <tt>head.content</tt> is being called and
passed a parameter named <tt>node</tt> whose
content is the value of the <tt>$doc</tt> variable
in the current context. The top of that template looks like
this:</p><pre class="programlisting"><xsl:template name="head.content">
<xsl:param name="node" select="."/>
</pre><p>The template is expecting the parameter because it
has a <tt><xsl:param></tt> defined with the
same name. The value in this definition is the default
value. This would be the parameter value used in the
template if the template was called without passing that
parameter.</p></div></div><div class="sect2"><a name="c44b1b3b6b9"></a><div class="titlepage"><div><h3 class="title"><a name="c44b1b3b6b9"></a>Generating HTML output.</h3></div></div><p>You generate HTML from your DocBook XML files by
applying the HTML version of the stylesheets. This is done
by using the HTML driver
file <tt>docbook/html/docbook.xsl</tt> as your
stylesheet. That is the master stylesheet file that
uses <tt><xsl:include></tt> to pull in the
component files it needs to assemble a complete stylesheet
for producing HTML. </p><p>The way the DocBook stylesheet generates HTML is to
apply templates that output a mix of text content and HTML
elements. Starting at the top level in the main
file <tt>docbook.xsl</tt>:</p><pre class="programlisting"><xsl:template match="/">
<xsl:variable name="doc" select="*[1]"/>
<html>
<head>
<xsl:call-template name="head.content">
<xsl:with-param name="node" select="$doc"/>
</xsl:call-template>
</head>
<body>
<xsl:apply-templates/>
</body>
</html>
</xsl:template>
</pre><p>This template matches the root element of your input
document, and starts the process of recursively applying
templates. It first defines a variable
named <tt>doc</tt> and then outputs two literal
HTML elements <tt><html></tt> and <tt><head></tt>.
Then it calls a named
template <tt>head.content</tt> to process the
content of the HTML <tt><head></tt>, closes
the <tt><head></tt> and starts
the <tt><body></tt>. There it
uses <tt><xsl:apply-templates/></tt> to
recursively process the entire input document. Then it just
closes out the HTML file.</p><p>Simple HTML elements can generated as literal
elements as shown here. But if the HTML being output
depends on the context, you need something more powerful to
select the element name and possibly add attributes and
their values. Here is a fragment
from <tt>sections.xsl</tt> that shows how a
heading tag is generated using
the <tt><xsl:element></tt> and <tt><xsl:attribute></tt> elements:</p><pre class="programlisting">
1 <xsl:element name="h{$level}">
2 <xsl:attribute name="class">title</xsl:attribute>
3 <xsl:if test="$level<3">
4 <xsl:attribute name="style">clear: all</xsl:attribute>
5 </xsl:if>
6 <a>
7 <xsl:attribute name="name">
8 <xsl:call-template name="object.id"/>
9 </xsl:attribute>
10 <b><xsl:copy-of select="$title"/></b>
11 </a>
12 </xsl:element>
</pre><p>This whole example is generating a single HTML
heading element. Line 1 begins the HTML element definition
by identifying the name of the element. In this case, the
name is an expression that includes the
variable <tt>$level</tt> passed as a parameter to
this template. Thus a single template can
generate <tt><h1></tt>, <tt><h2></tt>,
etc. depending on the context in which it is called. Line 2
defines a <tt>class="title"</tt> attribute that is
added to this element. Lines 3 to 5 add
a <tt>style="clear all"</tt> attribute, but only
if the heading level is less than 3. Line 6 opens
an <tt><a></tt> anchor element. Although this
looks like a literal output string, it is actually modified
by lines 7 to 9 that insert
the <tt>name</tt> attribute into
the <tt><a></tt> element. This illustrates
that XSL is managing output elements as active element
nodes, not just text strings. Line 10 outputs the text of
the heading title, also passed as a parameter to the
template, enclosed in HTML boldface tags. Line 11 closes
the anchor tag with the
literal <tt></a></tt> syntax, while line 12
closes the heading tag by closing the element definition.
Since the actual element name is a variable, it couldn't
use the literal syntax.</p><p>As you follow the sequence of nested templates
processing elements, you might be wondering how the
ordinary text of your input document gets to the output. In
the file <tt>docbook.xsl</tt> you will find
this template that handles any text not processed by any
other template:</p><pre class="programlisting"><xsl:template match="text()">
<xsl:value-of select="."/>
</xsl:template>
</pre><p>This template's body consists of the "value" of the text node,
which is just its text. In general, all XSL processors have
some built-in templates to handle any content for which
your stylesheet doesn't supply a matching template. This
template serves the same function but appears explicitly in
the stylesheet.</p></div><div class="sect2"><a name="c44b1b3b6c10"></a><div class="titlepage"><div><h3 class="title"><a name="c44b1b3b6c10"></a>Generating formatting objects.</h3></div></div><p>You generate formatting objects from your DocBook XML
files by applying the fo version of the stylesheets. This
is done by using the fo driver
file <tt>docbook/fo/docbook.xsl</tt> as your
stylesheet. That is the master stylesheet file that
uses <tt><xsl:include></tt> to pull in the
component files it needs to assemble a complete stylesheet
for producing formatting objects. Generating a formatting
objects file is only half the process of producing typeset
output. You also need a formatting object processor such as
the Apache XML Project's FOP as described in an earlier
section.</p><p>The DocBook fo stylesheet works in a similar manner
to the HTML stylesheet. Instead of outputting HTML tags, it
outputs text marked up
with <tt><fo:<i><tt>something</tt></i>></tt> tags.
For example, to indicate that some text should be kept
in-line and typeset with a monospace font, it might look
like this:</p><pre class="programlisting"><fo:inline-sequence font-family="monospace">/usr/man</fo:inline-sequence></pre><p>The templates
in <tt>docbook/fo/inline.xsl</tt> that produce
this output for a
DocBook <tt><filename></tt> element look
like this:</p><pre class="programlisting"><xsl:template match="filename">
<xsl:call-template name="inline.monoseq"/>
</xsl:template>
<xsl:template name="inline.monoseq">
<xsl:param name="content">
<xsl:apply-templates/>
</xsl:param>
<fo:inline-sequence font-family="monospace">
<xsl:copy-of select="$content"/>
</fo:inline-sequence>
</xsl:template>
</pre><p>There are dozens of fo tags and attributes specified
in the XSL standard. It is beyond the scope of this
document to cover how all of them are used in the DocBook
stylesheets. Fortunately, this is only an intermediate
format that you probably won't have to deal with very much
directly unless you are writing your own
stylesheets.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a href="ch01s02.html">Prev</a> </td><td width="20%" align="center"><a href="index.html">Home</a></td><td width="40%" align="right"> <a href="ch01s04.html">Next</a></td></tr><tr><td width="40%" align="left">A brief introduction to XSL </td><td width="20%" align="center"><a href="publishing.html">Up</a></td><td width="40%" align="right"> Customizing DocBook XSL stylesheets</td></tr></table></div></body></html>
|
