Debian Codegraph @

tests/docbook/doc/ch01s03.html

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