Context Navigation

xslt.html @ 21535

Visit:

Revision 21535, 98.1 KB checked in by ghudson, 20 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r21534, which included commits to RCS files with non-trunk default branches.

Line
1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2	"http://www.w3.org/TR/html4/loose.dtd">
3	<html>
4	<head>
5	<title>The XSLT C library for Gnome</title>
6	<meta name="GENERATOR" content="amaya 5.1">
7	<meta http-equiv="Content-Type" content="text/html">
8	</head>
9
10	<body bgcolor="#ffffff">
11	<h1 align="center">The XSLT C library for Gnome</h1>
12
13	<h1 style="text-align: center">libxslt</h1>
14
15	<p>Libxslt is the <a href="http://www.w3.org/TR/xslt">XSLT</a> C library
16	developed for the Gnome project. XSLT itself is a an XML language to define
17	transformation for XML. Libxslt is based on <a
18	href="http://xmlsoft.org/">libxml2</a> the XML C library developed for the
19	Gnome project. It also implements most of the <a
20	href="http://www.exslt.org/">EXSLT</a> set of processor-portable extensions
21	functions and some of Saxon's evaluate and expressions extensions.</p>
22
23	<p>People can either embed the library in their application or use xsltproc
24	the command line processing tool. This library is free software and can be
25	reused in commercial applications (see the <a href="intro.html">intro</a>)</p>
26
27	<p>External documents:</p>
28	<ul>
29	<li>John Fleck wrote <a href="tutorial/libxslttutorial.html">a tutorial for
30	libxslt</a></li>
31	<li><a href="xsltproc.html">xsltproc user manual</a></li>
32	<li><a href="http://xmlsoft.org/">the libxml documentation</a></li>
33	</ul>
34
35	<p></p>
36
37	<p>Logo designed by <a href="mailto:liyanage@access.ch">Marc Liyanage</a>.</p>
38
39	<h2><a name="Introducti">Introduction</a></h2>
40
41	<p>This document describes <a href="http://xmlsoft.org/XSLT/">libxslt</a>,
42	the <a href="http://www.w3.org/TR/xslt">XSLT</a> C library developed for the
43	<a href="http://www.gnome.org/">Gnome</a> project.</p>
44
45	<p>Here are some key points about libxslt:</p>
46	<ul>
47	<li>Libxslt is a C implementation</li>
48	<li>Libxslt is based on libxml for XML parsing, tree manipulation and XPath
49	support</li>
50	<li>It is written in plain C, making as few assumptions as possible, and
51	sticking closely to ANSI C/POSIX for easy embedding. Should works on
52	Linux/Unix/Windows.</li>
53	<li>This library is released under the <a
54	href="http://www.opensource.org/licenses/mit-license.html">MIT
55	Licence</a></li>
56	<li>Though not designed primarily with performances in mind, libxslt seems
57	to be a relatively fast processor.</li>
58	</ul>
59
60	<h2><a name="Documentat">Documentation</a></h2>
61
62	<p>There are some on-line resources about using libxslt:</p>
63	<ol>
64	<li>Check the <a href="html/libxslt-lib.html#LIBXSLT-LIB">API
65	documentation</a> automatically extracted from code comments (using the
66	program apibuild.py, developed for libxml, together with the xsl script
67	'newapi.xsl' and the libxslt xsltproc program).</li>
68	<li>Look at the <a href="http://mail.gnome.org/archives/xslt/">mailing-list
69	archive</a>.</li>
70	<li>Of course since libxslt is based on libxml, it's a good idea to at
71	least read <a href="http://xmlsoft.org/">libxml description</a></li>
72	</ol>
73
74	<h2><a name="Reporting">Reporting bugs and getting help</a></h2>
75
76	<p>If you need help with the XSLT language itself, here are a number of
77	useful resources:</p>
78	<ul>
79	<li>I strongly suggest to subscribe to <a
80	href="http://www.mulberrytech.com/xsl/xsl-list">XSL-list</a>, check <a
81	href="http://www.biglist.com/lists/xsl-list/archives/">the XSL-list
82	archives</a></li>
83	<li>The <a href="http://www.dpawson.co.uk/xsl/xslfaq.html">XSL FAQ</a>.</li>
84	<li>The <a
85	href="http://www.nwalsh.com/docs/tutorials/xsl/xsl/slides.html">tutorial</a>
86	written by Paul Grosso and Norman Walsh is a very good on-line
87	introdution to the language.</li>
88	<li>The <a
89	href="http://www.zvon.org/xxl/XSLTutorial/Books/Book1/index.html">only
90	Zvon XSLT tutorial</a> details a lot of constructs with examples.</li>
91	<li><a href="http://www.jenitennison.com/xslt/index.html">Jeni Tennison's
92	XSLT</a> pages provide links to a lot of answers</li>
93	<li>the <a href="http://incrementaldevelopment.com/xsltrick/">Gallery of
94	XSLT Tricks</a> provides non-standard use case of XSLT</li>
95	<li>And I suggest to buy Michael Kay "XSLT Programmer's Reference" book
96	published by <a href="http://www.wrox.com/">Wrox</a> if you plan to work
97	seriously with XSLT in the future.</li>
98	</ul>
99
100	<p>Well, bugs or missing features are always possible, and I will make a
101	point of fixing them in a timely fashion. The best way to report a bug is to
102	use the <a
103	href="http://bugzilla.gnome.org/enter_bug.cgi?product=libxslt">Gnome bug
104	tracking database</a> (make sure to use the "libxslt" module name). Before
105	filing a bug, check the <a
106	href="http://bugzilla.gnome.org/buglist.cgi?product=libxslt">list of existing
107	libxslt bugs</a> to make sure it hasn't already been filed. I look at reports
108	there regularly and it's good to have a reminder when a bug is still open. Be
109	sure to specify that the bug is for the package libxslt.</p>
110
111	<p>For small problems you can try to get help on IRC, the #xml channel on
112	irc.gnome.org (port 6667) usually have a few person subscribed which may help
113	(but there is no garantee and if a real issue is raised it should go on the
114	mailing-list for archival).</p>
115
116	<p>There is also a mailing-list <a
117	href="mailto:xslt@gnome.org">xslt@gnome.org</a> for libxslt, with an <a
118	href="http://mail.gnome.org/archives/xslt/">on-line archive</a>. To subscribe
119	to this list, please visit the <a
120	href="http://mail.gnome.org/mailman/listinfo/xslt">associated Web</a> page
121	and follow the instructions.</p>
122
123	<p>Alternatively, you can just send the bug to the <a
124	href="mailto:xslt@gnome.org">xslt@gnome.org</a> list, if it's really libxslt
125	related I will approve it.. Please do not send me mail directly especially
126	for portability problem, it makes things really harder to track and in some
127	cases I'm not the best person to answer a given question, ask the list
128	instead. <strong>Do not send code, I won't debug it</strong> (but patches are
129	really appreciated!).</p>
130
131	<p>Please note that with the current amount of virus and SPAM, sending mail
132	to the list without being subscribed won't work. There is *far too many
133	bounces* (in the order of a thousand a day !) I cannot approve them manually
134	anymore. If your mail to the list bounced waiting for administrator approval,
135	it is LOST ! Repost it and fix the problem triggering the error.</p>
136
137	<p>Check the following too <span style="color: #E50000">before
138	posting</span>:</p>
139	<ul>
140	<li><a href="search.php">use the search engine</a> to get informations
141	related to your problem.</li>
142	<li>make sure you are <a href="ftp://xmlsoft.org/">using a recent
143	version</a>, and that the problem still shows up in those</li>
144	<li>check the <a href="http://mail.gnome.org/archives/xslt/">list
145	archives</a> to see if the problem was reported already, in this case
146	there is probably a fix available, similarly check the <a
147	href="http://bugzilla.gnome.org/buglist.cgi?product=libxslt">registered
148	open bugs</a></li>
149	<li>make sure you can reproduce the bug with xsltproc, a very useful thing
150	to do is run the transformation with -v argument and redirect the
151	standard error to a file, then search in this file for the transformation
152	logs just preceding the possible problem</li>
153	<li>Please send the command showing the error as well as the input and
154	stylesheet (as an attachment)</li>
155	</ul>
156
157	<p>Then send the bug with associated informations to reproduce it to the <a
158	href="mailto:xslt@gnome.org">xslt@gnome.org</a> list; if it's really libxslt
159	related I will approve it. Please do not send mail to me directly, it makes
160	things really hard to track and in some cases I am not the best person to
161	answer a given question, ask on the list.</p>
162
163	<p>To <span style="color: #E50000">be really clear about support</span>:</p>
164	<ul>
165	<li>Support or help <span style="color: #E50000">request MUST be sent to
166	the list or on bugzilla</span> in case of problems, so that the Question
167	and Answers can be shared publicly. Failing to do so carries the implicit
168	message "I want free support but I don't want to share the benefits with
169	others" and is not welcome. I will automatically Carbon-Copy the
170	xslt@gnome.org mailing list for any technical reply made about libxml2 or
171	libxslt.</li>
172	<li>There is <span style="color: #E50000">no garantee for support</span>,
173	if your question remains unanswered after a week, repost it, making sure
174	you gave all the detail needed and the informations requested.</li>
175	<li>Failing to provide informations as requested or double checking first
176	for prior feedback also carries the implicit message "the time of the
177	library maintainers is less valuable than my time" and might not be
178	welcome.</li>
179	</ul>
180
181	<p>Of course, bugs reports with a suggested patch for fixing them will
182	probably be processed faster.</p>
183
184	<p>If you're looking for help, a quick look at <a
185	href="http://mail.gnome.org/archives/xslt/">the list archive</a> may actually
186	provide the answer, I usually send source samples when answering libxslt
187	usage questions. The <a
188	href="html/libxslt-lib.html#LIBXSLT-LIB">auto-generated documentation</a> is
189	not as polished as I would like (I need to learn more about Docbook), but
190	it's a good starting point.</p>
191
192	<h2><a name="help">How to help</a></h2>
193
194	<p>You can help the project in various ways, the best thing to do first is to
195	subscribe to the mailing-list as explained before, check the <a
196	href="http://mail.gnome.org/archives/xslt/">archives </a>and the <a
197	href="http://bugzilla.gnome.org/buglist.cgi?product=libxslt">Gnome bug
198	database:</a>:</p>
199	<ol>
200	<li>provide patches when you find problems</li>
201	<li>provide the diffs when you port libxslt to a new platform. They may not
202	be integrated in all cases but help pinpointing portability problems
203	and</li>
204	<li>provide documentation fixes (either as patches to the code comments or
205	as HTML diffs).</li>
206	<li>provide new documentations pieces (translations, examples, etc ...)</li>
207	<li>Check the TODO file and try to close one of the items</li>
208	<li>take one of the points raised in the archive or the bug database and
209	provide a fix. <a href="mailto:daniel@veillard.com">Get in touch with me
210	</a>before to avoid synchronization problems and check that the suggested
211	fix will fit in nicely :-)</li>
212	</ol>
213
214	<h2><a name="Downloads">Downloads</a></h2>
215
216	<p>The latest versions of libxslt can be found on the <a
217	href="ftp://xmlsoft.org/">xmlsoft.org</a> server and on mirrors (<a
218	href="ftp://speakeasy.rpmfind.net/pub/libxml/">Seattle</a>, <a
219	href="ftp://fr.rpmfind.net/pub/libxml/">France</a>) or on the <a
220	href="ftp://ftp.gnome.org/pub/GNOME/MIRRORS.html">Gnome FTP server</a> as a
221	<a href="ftp://ftp.gnome.org/pub/GNOME/sources/libxslt/1.1/">source
222	archive</a>, Antonin Sprinzl also provides <a
223	href="ftp://gd.tuwien.ac.at/pub/libxml/">a mirror in Austria</a>. (NOTE that
224	you need the <a href="http://rpmfind.net/linux/RPM/libxml2.html">libxml2</a>,
225	<a href="http://rpmfind.net/linux/RPM/libxml2-devel.html">libxml2-devel</a>,
226	<a href="http://rpmfind.net/linux/RPM/libxslt.html">libxslt</a> and <a
227	href="http://rpmfind.net/linux/RPM/libxslt-devel.html">libxslt-devel</a>
228	packages installed to compile applications using libxslt.) <a
229	href="mailto:igor@zlatkovic.com">Igor Zlatkovic</a> is now the maintainer of
230	the Windows port, <a
231	href="http://www.zlatkovic.com/projects/libxml/index.html">he provides
232	binaries</a>. <a href="mailto:Gary.Pennington@sun.com">Gary Pennington</a>
233	provides <a href="http://garypennington.net/libxml2/">Solaris binaries</a>.
234	<a href="mailto:Steve.Ball@zveno.com">Steve Ball</a> provides <a
235	href="http://www.zveno.com/open_source/libxml2xslt.html">Mac Os X
236	binaries</a>.</p>
237
238	<p><a name="Contribs">Contribs:</a></p>
239
240	<p>I do accept external contributions, especially if compiling on another
241	platform, get in touch with me to upload the package. I will keep them in the
242	<a href="ftp://xmlsoft.org/contribs/">contrib directory</a></p>
243
244	<p>Libxslt is also available from CVS:</p>
245	<ul>
246	<li><p>The <a href="http://cvs.gnome.org/viewcvs/libxslt/">Gnome CVS
247	base</a>. Check the <a
248	href="http://developer.gnome.org/tools/cvs.html">Gnome CVS Tools</a>
249	page; the CVS module is <b>libxslt</b>.</p>
250	</li>
251	<li><a href="ftp://xmlsoft.org/XSLT/cvs-snapshot.tar.gz">snapshots from
252	CVS</a> updated every hour are also provided</li>
253	</ul>
254
255	<h2><a name="FAQ">FAQ</a></h2>
256	<ol>
257	<li><em>Troubles compiling or linking programs using libxslt</em>
258	<p>Usually the problem comes from the fact that the compiler doesn't get
259	the right compilation or linking flags. There is a small shell script
260	<code>xslt-config</code> which is installed as part of libxslt usual
261	install process which provides those flags. Use</p>
262	<p><code>xslt-config --cflags</code></p>
263	<p>to get the compilation flags and</p>
264	<p><code>xslt-config --libs</code></p>
265	<p>to get the linker flags. Usually this is done directly from the
266	Makefile as:</p>
267	<p><code>CFLAGS=`xslt-config --cflags`</code></p>
268	<p><code>LIBS=`xslt-config --libs`</code></p>
269	<p>Note also that if you use the EXSLT extensions from the program then
270	you should prepend <code>-lexslt</code> to the LIBS options</p>
271	</li>
272	<li><em>passing parameters on the xsltproc command line doesn't work</em>
273	<p><em>xsltproc --param test alpha foo.xsl foo.xml</em></p>
274	<p><em>the param does not get passed and ends up as ""</em></p>
275	<p>In a nutshell do a double escaping at the shell prompt:</p>
276	<p>xsltproc --param test "'alpha'" foo.xsl foo.xml</p>
277	<p>i.e. the string value is surrounded by " and ' then terminated by '
278	and ". Libxslt interpret the parameter values as XPath expressions, so
279	the string -><code>alpha</code><- is intepreted as the node set
280	matching this string. You really want -><code>'alpha'</code><- to
281	be passed to the processor. And to allow this you need to escape the
282	quotes at the shell level using -><code>"'alpha'"</code><- .</p>
283	<p>or use</p>
284	<p>xsltproc --stringparam test alpha foo.xsl foo.xml</p>
285	</li>
286	<li><em>Is there C++ bindings ?</em>
287	<p>Yes for example <a
288	href="http://pmade.org/pjones/software/xmlwrapp/">xmlwrapp</a> , see <a
289	href="python.html">the related pages about bindings</a></p>
290	</li>
291	</ol>
292
293	<h2><a name="News">News</a></h2>
294
295	<p>The <a href="ChangeLog.html">change log</a> describes the recents commits
296	to the <a href="http://cvs.gnome.org/viewcvs/libxslt/">CVS</a> code base.</p>
297
298	<p>Those are the public releases made:</p>
299
300	<h3>1.1.12: Oct 29 2004</h3>
301	<ul>
302	<li>build fixes: warnings removal (William).</li>
303	<li>bug fixes: attribute document pointer fix (Mark Vakoc), exslt date
304	negative periods (William Brack), generated tree structure fixes,
305	namespace lookup fix, use reentrant gmtime_r (William Brack),
306	exslt:funtion namespace fix (William), potential NULL pointer reference
307	(Dennis Dams, William), force string interning on generated
308	documents.</li>
309	<li>documentation: update of the second tutorial (Panagiotis Louridas), add
310	exslt doc in rpm packages, fix the xsltproc man page.</li>
311	</ul>
312
313	<h3>1.1.11: Sep 29 2004</h3>
314	<ul>
315	<li>bug fixes: xsl:include problems (William Brack), UTF8 number pattern
316	(William), date-time validation (William), namespace fix (William),
317	various Exslt date fixes (William), error callback fixes, leak with
318	namespaced global variable, attempt to fix a weird problem #153137</li>
319	<li>improvements: exslt:date-sum tests (Derek Poon)</li>
320	<li>documentation: second tutorial by Panagiotis Lourida</li>
321	</ul>
322
323	<h3>1.1.10: Aug 31 2004</h3>
324	<ul>
325	<li>build fix: NUL in c file blocking compilation on Solaris, Windows build
326	(Igor Zlatkovic)</li>
327	<li>fix: key initialization problem (William Brack)</li>
328	<li>documentation: fixed missing man page description for --path</li>
329	</ul>
330
331	<h3>1.1.9: Aug 22 2004</h3>
332	<ul>
333	<li>build fixes: missing tests (William Brack), Python dependancies, Python
334	on 64bits boxes, --with-crypto flag (Rob Richards),</li>
335	<li>fixes: RVT key handling (William), Python binding (William and Sitsofe
336	Wheeler), key and XPath troubles (William), template priority on imports
337	(William), str:tokenize with empty strings (William), #default namespace
338	alias behaviour (William), doc ordering missing for main document
339	(William), 64bit bug (Andreas Schwab)</li>
340	<li>improvements: EXSLT date:sum added (Joel Reed), hook for document
341	loading for David Hyatt, xsltproc --nodtdattr to avoid defaulting DTD
342	attributes, extend xsltproc --version with CVS stamp (William).</li>
343	<li>Documentation: web page problem reported by Oliver Stoeneberg</li>
344	</ul>
345
346	<h3>1.1.8: July 5 2004</h3>
347	<ul>
348	<li>build fixes: Windows runtime options (Oliver Stoeneberg), Windows
349	binary package layout (Igor Zlatkovic), libgcrypt version test and link
350	(William)</li>
351	<li>documentation: fix libxslt namespace name in doc (William)</li>
352	<li>bug fixes: undefined namespace message (William Brack), search engine
353	(William), multiple namespace fixups (William), namespace fix for key
354	evaluation (William), Python memory debug bindings,</li>
355	<li>improvements: crypto extensions for exslt (Joel Reed, William)</li>
356	</ul>
357
358	<h3>1.1.7: May 17 2004</h3>
359	<ul>
360	<li>build fix: warning about localtime_r on Solaris</li>
361	<li>bug fix: UTF8 string tokenize (William Brack), subtle memory
362	corruption, linefeed after comment at document level (William),
363	disable-output-escaping problem (William), pattern compilation in deep
364	imported stylesheets (William), namespace extension prefix bug,
365	libxslt.m4 bug (Edward Rudd), namespace lookup for attribute, namespaced
366	DOCTYPE name</li>
367	</ul>
368
369	<h3>1.1.6: Apr 18 2004</h3>
370	<ul>
371	<li>2 bug fixes about keys fixed one by Mark Vakoc</li>
372	</ul>
373
374	<h3>1.1.5: Mar 23 2004</h3>
375	<ul>
376	<li>performance: use dictionnary lookup for variables</li>
377	<li>remove use of _private from source documents</li>
378	<li>cleanup of "make tests" output</li>
379	<li>bugfixes: AVT in local variables, use localtime_r to avoid thread
380	troubles (William), dictionary handling bug (William), limited number of
381	stubstitutions in AVT (William), tokenize fix for UTF-8 (William),
382	superfluous namespace (William), xsltproc error code on
383	<xsl:message> halt, OpenVMS fix, dictionnary reference counting
384	change.</li>
385	</ul>
386
387	<h3>1.1.4: Feb 23 2004</h3>
388	<ul>
389	<li>bugfixes: attributes without doc (Mariano Suárez-Alvarez), problem with
390	Yelp, extension problem</li>
391	<li>display extension modules (Steve Little)</li>
392	<li>Windows compilation patch (Mark Vadoc), Mingw (Mikhail Grushinskiy)</li>
393	</ul>
394
395	<h3>1.1.3: Feb 16 2004</h3>
396	<ul>
397	<li>Rewrote the Attribute Value Template code, new XPath compilation
398	interfaces, dictionnary reuses for XSLT with potential for serious
399	performance improvements.</li>
400	<li>bug fixes: portability (William Brack), key() in node-set() results
401	(William), comment before doctype (William), math and node-set() problems
402	(William), cdata element and default namespace (William), behaviour on
403	unknown XSLT elements (Stefan Kost), priority of "//foo" patterns
404	(William), xsl:element and xsl:attribute QName check (William), comments
405	with -- (William), attribute namespace (William), check for ?> in PI
406	(William)</li>
407	<li>Documentations: cleanup (John Fleck and William)</li>
408	<li>Python: patch for OS-X (Gianni Ceccarelli), enums export (Stephane
409	bidoul)</li>
410	</ul>
411
412	<h3>1.1.2: Dec 24 2003</h3>
413	<ul>
414	<li>Documentation fixes (John Fleck, William Brack), EXSLT documentation
415	(William Brack)</li>
416	<li>Windows compilation fixes for MSVC and Mingw (Igor Zlatkovic)</li>
417	<li>Bug fixes: exslt:date returning NULL strings (William Brack),
418	namespaces output (William Brack), key and namespace definition problem,
419	passing options down to the document() parser, xsl:number fixes (William
420	Brack)</li>
421	</ul>
422
423	<h3>1.1.1: Dec 10 2003</h3>
424	<ul>
425	<li>code cleanup (William Brack)</li>
426	<li>Windows: Makefile improvements (Igor Zlatkovic)</li>
427	<li>documentation improvements: William Brack, libexslt man page (Jonathan
428	Wakely)</li>
429	<li>param in EXSLT functions (Shaun McCance)</li>
430	<li>XSLT debugging improvements (Mark Vakoc)</li>
431	<li>bug fixes: number formatting (Bjorn Reese), exslt:tokenize (William
432	Brack), key selector parsing with \| reported by Oleg Paraschenko,
433	xsl:element with computed namespaces (William Brack), xslt:import/include
434	recursion detection (William Brack), exslt:function used in keys (William
435	Brack), bug when CDATA_SECTION are foun in the tree (William Brack),
436	entities handling when using XInclude.</li>
437	</ul>
438
439	<h3>1.1.0: Nov 4 2003</h3>
440	<ul>
441	<li>Removed DocBook SGML broken support</li>
442	<li>fix xsl:key to work with PIs</li>
443	<li>Makefile and build improvement (Graham Wilson), build cleanup (William
444	Brack), macro fix (Justin Fletcher), build outside of source tree (Roumen
445	Petrov)</li>
446	<li>xsltproc option display fix (Alexey Efimov), --load-trace (Crutcher
447	Dunnavant)</li>
448	<li>Python: never use stdout for error</li>
449	<li>extension memory error fix (Karl Eichwalder)</li>
450	<li>header path fixes (Steve Ball)</li>
451	<li>added saxon:line-number() to libexslt (Brett Kail)</li>
452	<li>Fix some tortuous template problems when using predicates (William
453	Brack)</li>
454	<li>Debugger status patch (Kasimier Buchcik)</li>
455	<li>Use new libxml2-2.6.x APIs for faster processing</li>
456	<li>Make sure xsl:sort is empty</li>
457	<li>Fixed a bug in default processing of attributes</li>
458	<li>Removes the deprecated breakpoint library</li>
459	<li>detect invalid names on templates (William Brack)</li>
460	<li>fix exslt:document (and similar) base handling problem</li>
461	</ul>
462
463	<h3>1.0.33: Sep 12 2003</h3>
464
465	<p>This is a bugfix only release</p>
466	<ul>
467	<li>error message missing argument (William Brack)</li>
468	<li>mode not cascaded in template fallbacks (William Brack)</li>
469	<li>catch redefinition of parameter/variables (William Brack)</li>
470	<li>multiple keys with same namespace name (William Brack)</li>
471	<li>patch for compilation using MingW on Windows (Mikhail Grushinskiy)</li>
472	<li>header export macros for Windows (Igor Zlatkovic)</li>
473	<li>cdata-section-elements handling of namespaced names</li>
474	<li>compilation without libxml2 XPointer support (Mark Vadoc)</li>
475	<li>apply-templates crash (William Brack)</li>
476	<li>bug with imported templates (William Brack)</li>
477	<li>imported attribute-sets merging bug (DocBook) (William Brack)</li>
478	</ul>
479
480	<h3>1.0.32: Aug 9 2003</h3>
481	<ul>
482	<li>bugfixes: xsltSaveResultToFile() python binding (Chris Jaeger), EXSLT
483	function (William Brack), RVT for globals (William Brack), EXSLT date
484	(William Brack),
485	<p>speed of large text output, xsl:copy with attributes, strip-space and
486	namespaces prefix, fix for --path xsltproc option, EXST:tokenize (Shaun
487	McCance), EXSLT:seconds (William Brack), sort with multiple keys (William
488	Brack), checking of { and } for attribute value templates (William
489	Brack)</p>
490	</li>
491	<li>Python bindings for extension elements (Sean Treadway)</li>
492	<li>EXSLT:split added (Shaun McCance)</li>
493	<li>portability fixes for HP-UX/Solaris/IRIX (William Brack)</li>
494	<li>doc cleanup</li>
495	</ul>
496
497	<h3>1.0.31: Jul 6 2003</h3>
498	<ul>
499	<li>bugfixes: xsl:copy on namespace nodes, AVT for xsl:sort order, fix for
500	the debugger (Keith Isdale), output filename limitation, trio.h and
501	triodef.h added (Albert Chin), EXSLT node-set (Peter Breitenlohner),
502	xsltChoose and whitespace (Igor Zlatkovic),
503	<p>stylesheet compilation (Igor Zlatkovic), NaN and sort (William Brack),
504	RVT bug introduced in 1.0.30</p>
505	</li>
506	<li>avoid generating &quot; (fix in libxml2-2.5.8)</li>
507	<li>fix 64bit cleaness problem and compilation troubles introduced in
508	1.0.30</li>
509	<li>Windows makefile generation (Igor Zlatkovic)</li>
510	<li>HP-UX portability fix</li>
511	</ul>
512
513	<h3>1.0.30: May 4 2003</h3>
514	<ul>
515	<li>Fixes and new APIs to handle Result Value Trees and avoid leaks</li>
516	<li>Fixes for: EXSLT math pow() function (Charles Bozeman), global
517	parameter and global variables mismatch, a segfault on pattern
518	compilation errors, namespace copy in xsl:copy-of, python generator
519	problem, OpenVMS trio update, premature call to xsltFreeStackElem (Igor),
520	current node when templates applies to attributes</li>
521	</ul>
522
523	<h3>1.0.29: Apr 1 2003</h3>
524	<ul>
525	<li>performance improvements especially for large flat documents</li>
526	<li>bug fixes: Result Value Tree handling, XML IDs, keys(), extra namespace
527	declarations with xsl:elements.</li>
528	<li>portability: python and trio fixes (Albert Chin), python on Solaris
529	(Ben Phillips)</li>
530	</ul>
531
532	<h3>1.0.28: Mar 24 2003</h3>
533	<ul>
534	<li>fixed node() in patterns semantic.</li>
535	<li>fixed a memory access problem in format-number()</li>
536	<li>fixed stack overflow in recursive global variable or params</li>
537	<li>cleaned up Result Value Tree handling, and fixed a couple of old bugs
538	in the process</li>
539	</ul>
540
541	<h3>1.0.27: Feb 24 2003</h3>
542	<ul>
543	<li>bug fixes: spurious xmlns:nsX="" generation, serialization bug (in
544	libxml2), a namespace copy problem, errors in the RPM spec prereqs</li>
545	<li>Windows path canonicalization and document cache fix (Igor)</li>
546	</ul>
547
548	<h3>1.0.26: Feb 10 2003</h3>
549	<ul>
550	<li>Fixed 3 serious bugs in document() and stylesheet compilation which
551	could lead to a crash</li>
552	</ul>
553
554	<h3>1.0.25: Feb 5 2003</h3>
555	<ul>
556	<li>Bug fix: double-free for standalone stylesheets introduced in 1.0.24, C
557	syntax pbm, 3 bugs reported by Eric van der Vlist</li>
558	<li>Some XPath and XInclude related problems were actually fixed in
559	libxml2-2.5.2</li>
560	<li>Documentation: emphasize taht --docbook is not for XML docs.</li>
561	</ul>
562
563	<h3>1.0.24: Jan 14 2003</h3>
564	<ul>
565	<li>bug fixes: imported global varables, python bindings (Stéphane Bidoul),
566	EXSLT memory leak (Charles Bozeman), namespace generation on
567	xsl:attribute, space handling with imports (Daniel Stodden),
568	extension-element-prefixes (Josh Parsons), comments within xsl:text (Matt
569	Sergeant), superfluous xmlns generation, XInclude related bug for
570	numbering, EXSLT strings (Alexey Efimov), attribute-sets computation on
571	imports, extension module init and shutdown callbacks not called</li>
572	<li>HP-UX portability (Alexey Efimov), Windows makefiles (Igor and Stephane
573	Bidoul), VMS makefile updates (Craig A. Berry)</li>
574	<li>adds xsltGetProfileInformation() (Michael Rothwell)</li>
575	<li>fix the API generation scripts</li>
576	<li>API to provide the sorting routines (Richard Jinks)</li>
577	<li>added XML description of the EXSLT API</li>
578	<li>added ESXLT URI (un)escaping (Jörg Walter)</li>
579	<li>Some memory leaks have been found and fixed</li>
580	<li>document() now support fragment identifiers in URIs</li>
581	</ul>
582
583	<h3>1.0.23: Nov 17 2002</h3>
584	<ul>
585	<li>Windows build cleanup (Igor)</li>
586	<li>Unix build and RPM packaging cleanup</li>
587	<li>Improvement of the python bindings: extension functions and activating
588	EXSLT</li>
589	<li>various bug fixes: number formatting, portability for bounded string
590	functions, CData nodes, key(), @*[...] patterns</li>
591	<li>Documentation improvements (John Fleck)</li>
592	<li>added libxslt.m4 (Thomas Schraitle)</li>
593	</ul>
594
595	<h3>1.0.22: Oct 18 2002</h3>
596	<ul>
597	<li>Updates on the Windows Makefiles</li>
598	<li>Added a security module, and a related set of new options to
599	xsltproc</li>
600	<li>Allowed per transformation error handler.</li>
601	<li>Fixed a few bugs: node() semantic, URI escaping, media-type, attribute
602	lists</li>
603	</ul>
604
605	<h3>1.0.21: Sep 26 2002</h3>
606	<ul>
607	<li>Bug fixes: match="node()", date:difference() (Igor and Charlie
608	Bozeman), disable-output-escaping</li>
609	<li>Python bindings: style.saveResultToString() from Ralf Mattes</li>
610	<li>Logos from Marc Liyanage</li>
611	<li>Mem leak fix from Nathan Myers</li>
612	<li>Makefile: DESTDIR fix from Christophe Merlet, AMD x86_64 (Mandrake),
613	Windows (Igor), Python detection</li>
614	<li>Documentation improvements: John Fleck</li>
615	</ul>
616
617	<h3>1.0.20: Aug 23 2002</h3>
618	<ul>
619	<li>Windows makefile updates (Igor) and x86-64 (Frederic Crozat)</li>
620	<li>fixed HTML meta tag saving for Mac/IE users</li>
621	<li>possible leak patches from Nathan Myers</li>
622	<li>try to handle document('') as best as possible depending in the
623	cases</li>
624	<li>Fixed the DocBook stylesheets handling problem</li>
625	<li>Fixed a few XSLT reported errors</li>
626	</ul>
627
628	<h3>1.0.19: July 6 2002</h3>
629	<ul>
630	<li>EXSLT: dynamic functions and date support bug fixes (Mark Vakoc)</li>
631	<li>xsl:number fix: Richard Jinks</li>
632	<li>xsl:format-numbers fix: Ken Neighbors</li>
633	<li>document('') fix: bug pointed by Eric van der Vlist</li>
634	<li>xsl:message with terminate="yes" fixes: William Brack</li>
635	<li>xsl:sort order support added: Ken Neighbors</li>
636	<li>a few other bug fixes, some of them requiring the latest version of
637	libxml2</li>
638	</ul>
639
640	<h3>1.0.18: May 27 2002</h3>
641	<ul>
642	<li>a number of bug fixes: attributes, extra namespace declarations
643	(DocBook), xsl:include crash (Igor), documentation (Christian Cornelssen,
644	Charles Bozeman and Geert Kloosterman), element-available (Richard
645	Jinks)</li>
646	<li>xsltproc can now list teh registered extensions thanks to Mark
647	Vakoc</li>
648	<li>there is a new API to save directly to a string
649	xsltSaveResultToString() by Morus Walter</li>
650	<li>specific error registration function for the python API</li>
651	</ul>
652
653	<h3>1.0.17: April 29 2002</h3>
654	<ul>
655	<li>cleanup in code, XSLT debugger support and Makefiles for Windows by
656	Igor</li>
657	<li>a C++ portability fix by Mark Vakoc</li>
658	<li>EXSLT date improvement and regression tests by Charles Bozeman</li>
659	<li>attempt to fix a bug in xsltProcessUserParamInternal</li>
660	</ul>
661
662	<h3>1.0.16: April 15 2002</h3>
663	<ul>
664	<li>Bug fixes: strip-space, URL in HTML output, error when xsltproc can't
665	save</li>
666	<li>portability fixes: OSF/1, IEEE on alphas, Windows, Python bindings</li>
667	</ul>
668
669	<h3>1.0.15: Mar 25 2002</h3>
670	<ul>
671	<li>Bugfixes: XPath, python Makefile, recursive attribute sets, @foo[..]
672	templates</li>
673	<li>Debug of memory alocation with valgind</li>
674	<li>serious profiling leading to significant improvement for DocBook
675	processing</li>
676	<li>revamp of the Windows build</li>
677	</ul>
678
679	<h3>1.0.14: Mar 18 2002</h3>
680	<ul>
681	<li>Improvement in the XPath engine (libxml2-2.4.18)</li>
682	<li>Nasty bug fix related to exslt:node-set</li>
683	<li>Fixed the python Makefiles, cleanup of doc comments, Windows
684	portability fixes</li>
685	</ul>
686
687	<h3>1.0.13: Mar 8 2002</h3>
688	<ul>
689	<li>a number of bug fixes including "namespace node have no parents"</li>
690	<li>Improvement of the Python bindings</li>
691	<li>Charles Bozeman provided fixes and regression tests for exslt date
692	functions.</li>
693	</ul>
694
695	<h3>1.0.12: Feb 11 2002</h3>
696	<ul>
697	<li>Fixed the makefiles especially the python module ones</li>
698	<li>half a dozen bugs fixes including 2 old ones</li>
699	</ul>
700
701	<h3>1.0.11: Feb 8 2002</h3>
702	<ul>
703	<li>Change of Licence to the <a
704	href="http://www.opensource.org/licenses/mit-license.html">MIT
705	Licence</a></li>
706	<li>Added a beta version of the Python bindings, including support to
707	extend the engine with functions written in Python</li>
708	<li>A number of bug fixes</li>
709	<li>Charlie Bozeman provided more EXSLT functions</li>
710	<li>Portability fixes</li>
711	</ul>
712
713	<h3>1.0.10: Jan 14 2002</h3>
714	<ul>
715	<li>Windows fixes for Win32 from Igor</li>
716	<li>Fixed the Solaris compilation trouble (Albert)</li>
717	<li>Documentation changes and updates: John Fleck</li>
718	<li>Added a stringparam option to avoid escaping hell at the shell
719	level</li>
720	<li>A few bug fixes</li>
721	</ul>
722
723	<h3>1.0.9: Dec 7 2001</h3>
724	<ul>
725	<li>Makefile patches from Peter Williams</li>
726	<li>attempt to fix the compilation problem associated to prelinking</li>
727	<li>obsoleted libxsltbreakpoint now deprecated and frozen to 1.0.8 API</li>
728	<li>xsltproc return codes are now significant, John Fleck updated the
729	documentation</li>
730	<li>patch to allow as much as 40 steps in patterns (Marc Tardif), should be
731	made dynamic really</li>
732	<li>fixed a bug raised by Nik Clayton when using doctypes with HTML
733	output</li>
734	<li>patches from Keith Isdale to interface with xsltdebugger</li>
735	</ul>
736
737	<h3>1.0.8: Nov 26 2001</h3>
738	<ul>
739	<li>fixed an annoying header problem, removed a few bugs and some code
740	cleanup</li>
741	<li>patches for Windows and update of Windows Makefiles by Igor</li>
742	<li>OpenVMS port instructions from John A Fotheringham</li>
743	<li>fixed some Makefiles annoyance and libraries prelinking
744	informations</li>
745	</ul>
746
747	<h3>1.0.7: Nov 10 2001</h3>
748	<ul>
749	<li>remove a compilation problem with LIBXSLT_PUBLIC</li>
750	<li>Finishing the integration steps for Keith Isdale debugger</li>
751	<li>fixes the handling of indent="no" on HTML output</li>
752	<li>fixes on the configure script and RPM spec file</li>
753	</ul>
754
755	<h3>1.0.6: Oct 30 2001</h3>
756	<ul>
757	<li>bug fixes on number formatting (Thomas), date/time functions (Bruce
758	Miller)</li>
759	<li>update of the Windows Makefiles (Igor)</li>
760	<li>fixed DOCTYPE generation rules for HTML output (me)</li>
761	</ul>
762
763	<h3>1.0.5: Oct 10 2001</h3>
764	<ul>
765	<li>some portability fixes, including Windows makefile updates from
766	Igor</li>
767	<li>fixed a dozen bugs on XSLT and EXSLT (me and Thomas Broyer)</li>
768	<li>support for Saxon's evaluate and expressions extensions added (initial
769	contribution from Darren Graves)</li>
770	<li>better handling of XPath evaluation errors</li>
771	</ul>
772
773	<h3>1.0.4: Sep 12 2001</h3>
774	<ul>
775	<li>Documentation updates from John fleck</li>
776	<li>bug fixes (DocBook FO generation should be fixed) and portability
777	improvements</li>
778	<li>Thomas Broyer improved the existing EXSLT support and added String,
779	Time and Date core functions support</li>
780	</ul>
781
782	<h3>1.0.3: Aug 23 2001</h3>
783	<ul>
784	<li>XML Catalog support see the doc</li>
785	<li>New NaN/Infinity floating point code</li>
786	<li>A few bug fixes</li>
787	</ul>
788
789	<h3>1.0.2: Aug 15 2001</h3>
790	<ul>
791	<li>lot of bug fixes, increased the testsuite</li>
792	<li>a large chunk of EXSLT is implemented</li>
793	<li>improvements on the extension framework</li>
794	<li>documentation improvements</li>
795	<li>Windows MSC projects files should be up-to-date</li>
796	<li>handle attributes inherited from the DTD by default</li>
797	</ul>
798
799	<h3>1.0.1: July 24 2001</h3>
800	<ul>
801	<li>initial EXSLT framework</li>
802	<li>better error reporting</li>
803	<li>fixed the profiler on Windows</li>
804	<li>bug fixes</li>
805	</ul>
806
807	<h3>1.0.0: July 10 2001</h3>
808	<ul>
809	<li>a lot of cleanup, a lot of regression tests added or fixed</li>
810	<li>added a documentation for <a href="extensions.html">writing
811	extensions</a></li>
812	<li>fixed some variable evaluation problems (with William)</li>
813	<li>added profiling of stylesheet execution accessible as the xsltproc
814	--profile option</li>
815	<li>fixed element-available() and the implementation of the various
816	chunking methods present, Norm Walsh provided a lot of feedback</li>
817	<li>exclude-result-prefixes and namespaces output should now work as
818	expected</li>
819	<li>added support of embedded stylesheet as described in section 2.7 of the
820	spec</li>
821	</ul>
822
823	<h3>0.14.0: July 5 2001</h3>
824	<ul>
825	<li>lot of bug fixes, and code cleanup</li>
826	<li>completion of the little XSLT-1.0 features left unimplemented</li>
827	<li>Added and implemented the extension API suggested by Thomas Broyer</li>
828	<li>the Windows MSC environment should be complete</li>
829	<li>tested and optimized with a really large document (DocBook Definitive
830	Guide) libxml/libxslt should really be faster on serious workloads</li>
831	</ul>
832
833	<h3>0.13.0: June 26 2001</h3>
834	<ul>
835	<li>lots of cleanups</li>
836	<li>fixed a C++ compilation problem</li>
837	<li>couple of fixes to xsltSaveTo()</li>
838	<li>try to fix Docbook-xslt-1.4 and chunking, updated the regression test
839	with them</li>
840	<li>fixed pattern compilation and priorities problems</li>
841	<li>Patches for Windows and MSC project mostly contributed by Yon Derek</li>
842	<li>update to the Tutorial by John Fleck</li>
843	<li>William fixed bugs in templates and for-each functions</li>
844	<li>added a new interface xsltRunStylesheet() for a more flexible output
845	(incomplete), added -o option to xsltproc</li>
846	</ul>
847
848	<h3>0.12.0: June 18 2001</h3>
849	<ul>
850	<li>fixed a dozen of bugs reported</li>
851	<li>HTML generation should be quite better (requires libxml-2.3.11 upgrade
852	too)</li>
853	<li>William fixed some problems with document()</li>
854	<li>Fix namespace nodes selection and copy (requires libxml-2.3.11 upgrade
855	too)</li>
856	<li>John Fleck added a<a href="tutorial/libxslttutorial.html">
857	tutorial</a></li>
858	<li>Fixes for namespace handling when evaluating variables</li>
859	<li>XInclude global flag added to process XInclude on document() if
860	requested</li>
861	<li>made xsltproc --version more detailed</li>
862	</ul>
863
864	<h3>0.11.0: June 1 2001</h3>
865
866	<p>Mostly a bug fix release.</p>
867	<ul>
868	<li>integration of catalogs from xsltproc</li>
869	<li>added --version to xsltproc for bug reporting</li>
870	<li>fixed errors when handling ID in external parsed entities</li>
871	<li>document() should hopefully work correctly but ...</li>
872	<li>fixed bug with PI and comments processing</li>
873	<li>William fixed the XPath string functions when using unicode</li>
874	</ul>
875
876	<h3>0.10.0: May 19 2001</h3>
877	<ul>
878	<li>cleanups to make stylesheet read-only (not 100% complete)</li>
879	<li>fixed URI resolution in document()</li>
880	<li>force all XPath expression to be compiled at stylesheet parsing time,
881	even if unused ...</li>
882	<li>Fixed HTML default output detection</li>
883	<li>Fixed double attribute generation #54446</li>
884	<li>Fixed {{ handling in attributes #54451</li>
885	<li>More tests and speedups for DocBook document transformations</li>
886	<li>Fixed a really bad race like bug in xsltCopyTreeList()</li>
887	<li>added a documentation on the libxslt internals</li>
888	<li>William Brack and Bjorn Reese improved format-number()</li>
889	<li>Fixed multiple sort, it should really work now</li>
890	<li>added a --docbook option for SGML DocBook input (hackish)</li>
891	<li>a number of other bug fixes and regression test added as people were
892	submitting them</li>
893	</ul>
894
895	<h3>0.9.0: May 3 2001</h3>
896	<ul>
897	<li>lot of various bugfixes, extended the regression suite</li>
898	<li>xsltproc should work with multiple params</li>
899	<li>added an option to use xsltproc with HTML input</li>
900	<li>improved the stylesheet compilation, processing of complex stylesheets
901	should be faster</li>
902	<li>using the same stylesheet for concurrent processing on multithreaded
903	programs should work now</li>
904	<li>fixed another batch of namespace handling problems</li>
905	<li>Implemented multiple level of sorting</li>
906	</ul>
907
908	<h3>0.8.0: Apr 22 2001</h3>
909	<ul>
910	<li>fixed ansidecl.h problem</li>
911	<li>fixed unparsed-entity-uri() and generate-id()</li>
912	<li>sort semantic fixes and priority prob from William M. Brack</li>
913	<li>fixed namespace handling problems in XPath expression computations
914	(requires libxml-2.3.7)</li>
915	<li>fixes to current() and key()</li>
916	<li>other, smaller fixes, lots of testing with N Walsh DocBook HTML
917	stylesheets</li>
918	</ul>
919
920	<h3>0.7.0: Apr 10 2001</h3>
921	<ul>
922	<li>cleanup using stricter compiler flags</li>
923	<li>command line parameter passing</li>
924	<li>fix to xsltApplyTemplates from William M. Brack</li>
925	<li>added the XSLTMark in the regression tests as well as document()</li>
926	</ul>
927
928	<h3>0.6.0: Mar 22 2001</h3>
929	<ul>
930	<li>another beta</li>
931	<li>requires 2.3.5, which provide XPath expression compilation support</li>
932	<li>document() extension should function properly</li>
933	<li>fixed a number or reported bugs</li>
934	</ul>
935
936	<h3>0.5.0: Mar 10 2001</h3>
937	<ul>
938	<li>fifth beta</li>
939	<li>some optimization work, for the moment 2 XSLT transform cannot use the
940	same stylesheet at the same time (to be fixed)</li>
941	<li>fixed problems with handling of tree results</li>
942	<li>fixed a reported strip-spaces problem</li>
943	<li>added more reported/fixed bugs to the test suite</li>
944	<li>incorporated William M. Brack fix for imports and global variables as
945	well as patch for with-param support in apply-templates</li>
946	<li>a bug fix on for-each</li>
947	</ul>
948
949	<h3>0.4.0: Mar 1 2001</h3>
950	<ul>
951	<li>fourth beta test, released at the same time of libxml2-2.3.3</li>
952	<li>bug fixes</li>
953	<li>some optimization</li>
954	<li>started implement extension support, not finished</li>
955	<li>implemented but not tested multiple file output</li>
956	</ul>
957
958	<h3>0.3.0: Feb 24 2001</h3>
959	<ul>
960	<li>third beta test, released at the same time of libxml2-2.3.2</li>
961	<li>lot of bug fixes</li>
962	<li>some optimization</li>
963	<li>added DocBook XSL based testsuite</li>
964	</ul>
965
966	<h3>0.2.0: Feb 15 2001</h3>
967	<ul>
968	<li>second beta version, released at the same time as libxml2-2.3.1</li>
969	<li>getting close to feature completion, lot of bug fixes, some in the HTML
970	and XPath support of libxml</li>
971	<li>start becoming usable for real work. This version can now regenerate
972	the XML 2e HTML from the original XML sources and the associated
973	stylesheets (in <a
974	href="http://www.w3.org/TR/REC-xml#b4d250b6c21">section I of the XML
975	REC</a>)</li>
976	<li>Still misses extension element/function/prefixes support. Support of
977	key() and document() is not complete</li>
978	</ul>
979
980	<h3>0.1.0: Feb 8 2001</h3>
981	<ul>
982	<li>first beta version, released at the same time as libxml2-2.3.0</li>
983	<li>lots of bug fixes, first "testing" version, but incomplete</li>
984	</ul>
985
986	<h3>0.0.1: Jan 25 2001</h3>
987	<ul>
988	<li>first alpha version released at the same time as libxml2-2.2.12</li>
989	<li>Framework in place, should work on simple examples, but far from being
990	feature complete</li>
991	</ul>
992
993	<h2><a name="xsltproc">The xsltproc tool</a></h2>
994
995	<p>This program is the simplest way to use libxslt: from the command line. It
996	is also used for doing the regression tests of the library.</p>
997
998	<p>It takes as first argument the path or URL to an XSLT stylesheet, the next
999	arguments are filenames or URIs of the inputs to be processed. The output of
1000	the processing is redirected on the standard output. There is actually a few
1001	more options available:</p>
1002	<pre>orchis:~ -> xsltproc
1003	Usage: xsltproc [options] stylesheet file [file ...]
1004	Options:
1005	--version or -V: show the version of libxml and libxslt used
1006	--verbose or -v: show logs of what's happening
1007	--output file or -o file: save to a given file
1008	--timing: display the time used
1009	--repeat: run the transformation 20 times
1010	--debug: dump the tree of the result instead
1011	--novalid: skip the Dtd loading phase
1012	--noout: do not dump the result
1013	--maxdepth val : increase the maximum depth
1014	--html: the input document is(are) an HTML file(s)
1015	--docbook: the input document is SGML docbook
1016	--param name value : pass a (parameter,value) pair
1017	--nonet refuse to fetch DTDs or entities over network
1018	--warnnet warn against fetching over the network
1019	--catalogs : use the catalogs from $SGML_CATALOG_FILES
1020	--xinclude : do XInclude processing on document intput
1021	--profile or --norman : dump profiling informations
1022	orchis:~ -></pre>
1023
1024	<h2><a name="DocBook">DocBook</a></h2>
1025
1026	<p><img src="duck.png" align="right" alt="The duck picture"></p>
1027
1028	<p><a href="http://www.oasis-open.org/committees/docbook/">DocBook</a> is an
1029	XML/SGML vocabulary particularly well suited to books and papers about
1030	computer hardware and software.</p>
1031
1032	<p>xsltproc and libxslt are not specifically dependant on DocBook, but since
1033	a lot of people use xsltproc and libxml2 for DocBook formatting, here are a
1034	few pointers and informations which may be helpful:</p>
1035	<ul>
1036	<li>The <a href="http://www.oasis-open.org/committees/docbook/">DocBook
1037	homepage at Oasis</a> you should find pointers there on all the lastest
1038	versions of the DTDs and XSLT stylesheets</li>
1039	<li><a href="http://www.docbook.org/">DocBook: The Definitive Guide</a> is
1040	the official reference documentation for DocBook.</li>
1041	<li><a
1042	href="https://sourceforge.net/docman/index.php?group_id=21935">DocBook
1043	Open Repository</a> contains a lot of informations about DocBook</li>
1044	<li>Bob Stayton provides a <a href="http://www.sagehill.net/">lot of
1045	resources</a> and consulting services around DocBook.</li>
1046	<li>Here is a <a href="/buildDocBookCatalog">shell script</a> to generate
1047	XML Catalogs for DocBook 4.1.2 . If it can write to the /etc/xml/
1048	directory, it will set-up /etc/xml/catalog and /etc/xml/docbook based on
1049	the resources found on the system. Otherwise it will just create
1050	~/xmlcatalog and ~/dbkxmlcatalog and doing:
1051	<p><code>export XMLCATALOG=$HOME/xmlcatalog</code></p>
1052	<p>should allow to process DocBook documentations without requiring
1053	network accesses for the DTd or stylesheets</p>
1054	</li>
1055	<li>I have uploaded <a href="ftp://xmlsoft.org/test/dbk412catalog.tar.gz">a
1056	small tarball</a> containing XML Catalogs for DocBook 4.1.2 which seems
1057	to work fine for me too</li>
1058	<li>Informations on installing a <a
1059	href="http://ourworld.compuserve.com/homepages/hoenicka_markus/ntsgml.html">Windows
1060	DocBook processing setup</a> based on Cygwin (using the binaries from the
1061	official Windows port should be possible too)</li>
1062	<li>Alexander Kirillov's page on <a
1063	href="http://www.math.sunysb.edu/~kirillov/dbxml/">Using DocBook XML
1064	4.1.2</a> (RPM packages)</li>
1065	<li>Tim Waugh's <a href="http://cyberelk.net/tim/xmlto/">xmlto front-end
1066	conversion script</a></li>
1067	<li>Linux Documentation Project <a
1068	href="http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/">
1069	DocBook-Install-mini-HOWTO</a></li>
1070	<li>ScrollKeeper the open documentation cataloging project has a <a
1071	href="http://scrollkeeper.sourceforge.net/docbook.shtml">DocBook
1072	section</a></li>
1073	<li>Dan York presentation on <a
1074	href="http://www.lodestar2.com/people/dyork/talks/2001/xugo/docbook/index.html">Publishing
1075	using DocBook XML</a></li>
1076	</ul>
1077
1078	<p>Do not use the --docbook option of xsltproc to process XML DocBook
1079	documents, this option is only intended to provide some (limited) support of
1080	the SGML version of DocBook.</p>
1081
1082	<p>Points which are not DocBook specific but still worth mentionning
1083	again:</p>
1084	<ul>
1085	<li>if you think DocBook processing time is too slow, make sure you have
1086	XML Catalogs pointing to a local installation of the DTD of DocBook.
1087	Check the <a href="http://xmlsoft.org/catalog.html">XML Catalog page</a>
1088	to understand more on this subject.</li>
1089	<li>before processing a new document, use the command
1090	<p><code>xmllint --valid --noout path_to_document</code></p>
1091	<p>to make sure that your input is valid DocBook. And fixes the errors
1092	before processing further. Note that XSLT processing may work correctly
1093	with some forms of validity errors left, but in general it can give
1094	troubles on output.</p>
1095	</li>
1096	</ul>
1097
1098	<h2><a name="API">The programming API</a></h2>
1099
1100	<p>Okay this section is clearly incomplete. But integrating libxslt into your
1101	application should be relatively easy. First check the few steps described
1102	below, then for more detailed informations, look at the<a
1103	href="html/libxslt-lib.html"> generated pages</a> for the API and the source
1104	of libxslt/xsltproc.c and the <a
1105	href="tutorial/libxslttutorial.html">tutorial</a>.</p>
1106
1107	<p>Basically doing an XSLT transformation can be done in a few steps:</p>
1108	<ol>
1109	<li>configure the parser for XSLT:
1110	<p>xmlSubstituteEntitiesDefault(1);</p>
1111	<p>xmlLoadExtDtdDefaultValue = 1;</p>
1112	</li>
1113	<li>parse the stylesheet with xsltParseStylesheetFile()</li>
1114	<li>parse the document with xmlParseFile()</li>
1115	<li>apply the stylesheet using xsltApplyStylesheet()</li>
1116	<li>save the result using xsltSaveResultToFile() if needed set
1117	xmlIndentTreeOutput to 1</li>
1118	</ol>
1119
1120	<p>Steps 2,3, and 5 will probably need to be changed depending on you
1121	processing needs and environment for example if reading/saving from/to
1122	memory, or if you want to apply XInclude processing to the stylesheet or
1123	input documents.</p>
1124
1125	<h2><a name="Python">Python and bindings</a></h2>
1126
1127	<p>There is a number of language bindings and wrappers available for libxml2,
1128	the list below is not exhaustive. Please contact the <a
1129	href="http://mail.gnome.org/mailman/listinfo/xml-bindings">xml-bindings@gnome.org</a>
1130	(<a href="http://mail.gnome.org/archives/xml-bindings/">archives</a>) in
1131	order to get updates to this list or to discuss the specific topic of libxml2
1132	or libxslt wrappers or bindings:</p>
1133	<ul>
1134	<li><a
1135	href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">Matt
1136	Sergeant</a> developped <a href="http://axkit.org/download/">XML::LibXML
1137	and XML::LibXSLT</a>, Perl wrappers for libxml2/libxslt as part of the <a
1138	href="http://axkit.com/">AxKit XML application server</a></li>
1139	<li><a href="mailto:dkuhlman@cutter.rexx.com">Dave Kuhlman</a> provides and
1140	earlier version of the libxml/libxslt <a
1141	href="http://www.rexx.com/~dkuhlman">wrappers for Python</a></li>
1142	<li>Petr Kozelka provides <a
1143	href="http://sourceforge.net/projects/libxml2-pas">Pascal units to glue
1144	libxml2</a> with Kylix, Delphi and other Pascal compilers</li>
1145	<li>Wai-Sun "Squidster" Chia provides <a
1146	href="http://www.rubycolor.org/arc/redist/">bindings for Ruby</a> and
1147	libxml2 bindings are also available in Ruby through the <a
1148	href="http://libgdome-ruby.berlios.de/">libgdome-ruby</a> module
1149	maintained by Tobias Peters.</li>
1150	<li>Steve Ball and contributors maintains <a
1151	href="http://tclxml.sourceforge.net/">libxml2 and libxslt bindings for
1152	Tcl</a></li>
1153	<li><a href="mailto:xmlwrapp@pmade.org">Peter Jones</a> maintains C++
1154	bindings for libxslt within <a
1155	href="http://pmade.org/pjones/software/xmlwrapp/">xmlwrapp</a></li>
1156	<li><a href="phillim2@comcast.net">Mike Phillips</a> provides a module
1157	using <a href="http://siasl.dyndns.org/projects/projects.html">libxslt
1158	for PHP</a>.</li>
1159	<li><a href="http://savannah.gnu.org/projects/classpathx/">LibxmlJ</a> is
1160	an effort to create a 100% JAXP-compatible Java wrapper for libxml2 and
1161	libxslt as part of GNU ClasspathX project.</li>
1162	<li>Patrick McPhee provides Rexx bindings fof libxml2 and libxslt, look for
1163	<a href="http://www.interlog.com/~ptjm/software.html">RexxXML</a>.</li>
1164	</ul>
1165
1166	<p>The libxslt Python module depends on the <a
1167	href="http://xmlsoft.org/python.html">libxml2 Python</a> module.</p>
1168
1169	<p>The distribution includes a set of Python bindings, which are garanteed to
1170	be maintained as part of the library in the future, though the Python
1171	interface have not yet reached the completeness of the C API.</p>
1172
1173	<p><a href="mailto:stephane.bidoul@softwareag.com">Stéphane Bidoul</a>
1174	maintains <a href="http://users.skynet.be/sbi/libxml-python/">a Windows port
1175	of the Python bindings</a>.</p>
1176
1177	<p>Note to people interested in building bindings, the API is formalized as
1178	<a href="libxslt-api.xml">an XML API description file</a> which allows to
1179	automate a large part of the Python bindings, this includes function
1180	descriptions, enums, structures, typedefs, etc... The Python script used to
1181	build the bindings is python/generator.py in the source distribution.</p>
1182
1183	<p>To install the Python bindings there are 2 options:</p>
1184	<ul>
1185	<li>If you use an RPM based distribution, simply install the <a
1186	href="http://rpmfind.net/linux/rpm2html/search.php?query=libxml2-python">libxml2-python
1187	RPM</a> and the <a
1188	href="http://rpmfind.net/linux/rpm2html/search.php?query=libxslt-python">libxslt-python
1189	RPM</a>.</li>
1190	<li>Otherwise use the <a href="ftp://xmlsoft.org/python/">libxml2-python
1191	module distribution</a> corresponding to your installed version of
1192	libxml2 and libxslt. Note that to install it you will need both libxml2
1193	and libxslt installed and run "python setup.py build install" in the
1194	module tree.</li>
1195	</ul>
1196
1197	<p>The distribution includes a set of examples and regression tests for the
1198	python bindings in the <code>python/tests</code> directory. Here are some
1199	excepts from those tests:</p>
1200
1201	<h3>basic.py:</h3>
1202
1203	<p>This is a basic test of XSLT interfaces: loading a stylesheet and a
1204	document, transforming the document and saving the result.</p>
1205	<pre>import libxml2
1206	import libxslt
1207
1208	styledoc = libxml2.parseFile("test.xsl")
1209	style = libxslt.parseStylesheetDoc(styledoc)
1210	doc = libxml2.parseFile("test.xml")
1211	result = style.applyStylesheet(doc, None)
1212	style.saveResultToFilename("foo", result, 0)
1213	style.freeStylesheet()
1214	doc.freeDoc()
1215	result.freeDoc()</pre>
1216
1217	<p>The Python module is called libxslt, you will also need the libxml2 module
1218	for the operations on XML trees. Let's have a look at the objects manipulated
1219	in that example and how is the processing done:</p>
1220	<ul>
1221	<li><code>styledoc</code> : is a libxml2 document tree. It is obtained by
1222	parsing the XML file "test.xsl" containing the stylesheet.</li>
1223	<li><code>style</code> : this is a precompiled stylesheet ready to be used
1224	by the following transformations (note the plural form, multiple
1225	transformations can resuse the same stylesheet).</li>
1226	<li><code>doc</code> : this is the document to apply the transformation to.
1227	In this case it is simply generated by parsing it from a file but any
1228	other processing is possible as long as one get a libxml2 Doc. Note that
1229	HTML tree are suitable for XSLT processing in libxslt. This is actually
1230	how this page is generated !</li>
1231	<li><code>result</code> : this is a document generated by applying the
1232	stylesheet to the document. Note that some of the stylesheet informations
1233	may be related to the serialization of that document and as in this
1234	example a specific saveResultToFilename() method of the stylesheet should
1235	be used to save it to a file (in that case to "foo").</li>
1236	</ul>
1237
1238	<p>Also note the need to explicitely deallocate documents with freeDoc()
1239	except for the stylesheet document which is freed when its compiled form is
1240	garbage collected.</p>
1241
1242	<h3>extfunc.py:</h3>
1243
1244	<p>This one is a far more complex test. It shows how to modify the behaviour
1245	of an XSLT transformation by passing parameters and how to extend the XSLT
1246	engine with functions defined in python:</p>
1247	<pre>import libxml2
1248	import libxslt
1249	import string
1250
1251	nodeName = None
1252	def f(ctx, str):
1253	global nodeName
1254
1255	#
1256	# Small check to verify the context is correcly accessed
1257	#
1258	try:
1259	pctxt = libxslt.xpathParserContext(_obj=ctx)
1260	ctxt = pctxt.context()
1261	tctxt = ctxt.transformContext()
1262	nodeName = tctxt.insertNode().name
1263	except:
1264	pass
1265
1266	return string.upper(str)
1267
1268	libxslt.registerExtModuleFunction("foo", "http://example.com/foo", f)</pre>
1269
1270	<p>This code defines and register an extension function. Note that the
1271	function can be bound to any name (foo) and how the binding is also
1272	associated to a namespace name "http://example.com/foo". From an XSLT point
1273	of view the function just returns an upper case version of the string passed
1274	as a parameter. But the first part of the function also read some contextual
1275	information from the current XSLT processing environement, in that case it
1276	looks for the current insertion node in the resulting output (either the
1277	resulting document or the Result Value Tree being generated), and saves it to
1278	a global variable for checking that the access actually worked.</p>
1279
1280	<p>For more informations on the xpathParserContext and transformContext
1281	objects check the <a href="internals.html">libray internals description</a>.
1282	The pctxt is actually an object from a class derived from the
1283	libxml2.xpathParserContext() with just a couple more properties including the
1284	possibility to look up the XSLT transformation context from the XPath
1285	context.</p>
1286	<pre>styledoc = libxml2.parseDoc("""
1287	<xsl:stylesheet version='1.0'
1288	xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
1289	xmlns:foo='http://example.com/foo'
1290	xsl:exclude-result-prefixes='foo'>
1291
1292	<xsl:param name='bar'>failure</xsl:param>
1293	<xsl:template match='/'>
1294	<article><xsl:value-of select='foo:foo($bar)'/></article>
1295	</xsl:template>
1296	</xsl:stylesheet>
1297	""")</pre>
1298
1299	<p>Here is a simple example of how to read an XML document from a python
1300	string with libxml2. Note how this stylesheet:</p>
1301	<ul>
1302	<li>Uses a global parameter <code>bar</code></li>
1303	<li>Reference the extension function f</li>
1304	<li>how the Namespace name "http://example.com/foo" has to be bound to a
1305	prefix</li>
1306	<li>how that prefix is excluded from the output</li>
1307	<li>how the function is called from the select</li>
1308	</ul>
1309	<pre>style = libxslt.parseStylesheetDoc(styledoc)
1310	doc = libxml2.parseDoc("<doc/>")
1311	result = style.applyStylesheet(doc, { "bar": "'success'" })
1312	style.freeStylesheet()
1313	doc.freeDoc()</pre>
1314
1315	<p>that part is identical, to the basic example except that the
1316	transformation is passed a dictionnary of parameters. Note that the string
1317	passed "success" had to be quoted, otherwise it is interpreted as an XPath
1318	query for the childs of root named "success".</p>
1319	<pre>root = result.children
1320	if root.name != "article":
1321	print "Unexpected root node name"
1322	sys.exit(1)
1323	if root.content != "SUCCESS":
1324	print "Unexpected root node content, extension function failed"
1325	sys.exit(1)
1326	if nodeName != 'article':
1327	print "The function callback failed to access its context"
1328	sys.exit(1)
1329
1330	result.freeDoc()</pre>
1331
1332	<p>That part just verifies that the transformation worked, that the parameter
1333	got properly passed to the engine, that the function f() got called and that
1334	it properly accessed the context to find the name of the insertion node.</p>
1335
1336	<h3>pyxsltproc.py:</h3>
1337
1338	<p>this module is a bit too long to be described there but it is basically a
1339	rewrite of the xsltproc command line interface of libxslt in Python. It
1340	provides nearly all the functionalities of xsltproc and can be used as a base
1341	module to write Python customized XSLT processors. One of the thing to notice
1342	are:</p>
1343	<pre>libxml2.lineNumbersDefault(1)
1344	libxml2.substituteEntitiesDefault(1)</pre>
1345
1346	<p>those two calls in the main() function are needed to force the libxml2
1347	processor to generate DOM trees compliant with the XPath data model.</p>
1348
1349	<h2><a name="Internals">Library internals</a></h2>
1350
1351	<h3>Table of contents</h3>
1352	<ul>
1353	<li><a href="internals.html#Introducti">Introduction</a></li>
1354	<li><a href="internals.html#Basics">Basics</a></li>
1355	<li><a href="internals.html#Keep">Keep it simple stupid</a></li>
1356	<li><a href="internals.html#libxml">The libxml nodes</a></li>
1357	<li><a href="internals.html#XSLT">The XSLT processing steps</a></li>
1358	<li><a href="internals.html#XSLT1">The XSLT stylesheet compilation</a></li>
1359	<li><a href="internals.html#XSLT2">The XSLT template compilation</a></li>
1360	<li><a href="internals.html#processing">The processing itself</a></li>
1361	<li><a href="internals.html#XPath">XPath expressions compilation</a></li>
1362	<li><a href="internals.html#XPath1">XPath interpretation</a></li>
1363	<li><a href="internals.html#Descriptio">Description of XPath
1364	Objects</a></li>
1365	<li><a href="internals.html#XPath3">XPath functions</a></li>
1366	<li><a href="internals.html#stack">The variables stack frame</a></li>
1367	<li><a href="internals.html#Extension">Extension support</a></li>
1368	<li><a href="internals.html#Futher">Further reading</a></li>
1369	<li><a href="internals.html#TODOs">TODOs</a></li>
1370	</ul>
1371
1372	<h3><a name="Introducti2">Introduction</a></h3>
1373
1374	<p>This document describes the processing of <a
1375	href="http://xmlsoft.org/XSLT/">libxslt</a>, the <a
1376	href="http://www.w3.org/TR/xslt">XSLT</a> C library developed for the <a
1377	href="http://www.gnome.org/">Gnome</a> project.</p>
1378
1379	<p>Note: this documentation is by definition incomplete and I am not good at
1380	spelling, grammar, so patches and suggestions are <a
1381	href="mailto:veillard@redhat.com">really welcome</a>.</p>
1382
1383	<h3><a name="Basics1">Basics</a></h3>
1384
1385	<p>XSLT is a transformation language. It takes an input document and a
1386	stylesheet document and generates an output document:</p>
1387
1388	<p align="center"><img src="processing.gif"
1389	alt="the XSLT processing model"></p>
1390
1391	<p>Libxslt is written in C. It relies on <a
1392	href="http://www.xmlsoft.org/">libxml</a>, the XML C library for Gnome, for
1393	the following operations:</p>
1394	<ul>
1395	<li>parsing files</li>
1396	<li>building the in-memory DOM structure associated with the documents
1397	handled</li>
1398	<li>the XPath implementation</li>
1399	<li>serializing back the result document to XML and HTML. (Text is handled
1400	directly.)</li>
1401	</ul>
1402
1403	<h3><a name="Keep1">Keep it simple stupid</a></h3>
1404
1405	<p>Libxslt is not very specialized. It is built under the assumption that all
1406	nodes from the source and output document can fit in the virtual memory of
1407	the system. There is a big trade-off there. It is fine for reasonably sized
1408	documents but may not be suitable for large sets of data. The gain is that it
1409	can be used in a relatively versatile way. The input or output may never be
1410	serialized, but the size of documents it can handle are limited by the size
1411	of the memory available.</p>
1412
1413	<p>More specialized memory handling approaches are possible, like building
1414	the input tree from a serialization progressively as it is consumed,
1415	factoring repetitive patterns, or even on-the-fly generation of the output as
1416	the input is parsed but it is possible only for a limited subset of the
1417	stylesheets. In general the implementation of libxslt follows the following
1418	pattern:</p>
1419	<ul>
1420	<li>KISS (keep it simple stupid)</li>
1421	<li>when there is a clear bottleneck optimize on top of this simple
1422	framework and refine only as much as is needed to reach the expected
1423	result</li>
1424	</ul>
1425
1426	<p>The result is not that bad, clearly one can do a better job but more
1427	specialized too. Most optimization like building the tree on-demand would
1428	need serious changes to the libxml XPath framework. An easy step would be to
1429	serialize the output directly (or call a set of SAX-like output handler to
1430	keep this a flexible interface) and hence avoid the memory consumption of the
1431	result.</p>
1432
1433	<h3><a name="libxml">The libxml nodes</a></h3>
1434
1435	<p>DOM-like trees, as used and generated by libxml and libxslt, are
1436	relatively complex. Most node types follow the given structure except a few
1437	variations depending on the node type:</p>
1438
1439	<p align="center"><img src="node.gif" alt="description of a libxml node"></p>
1440
1441	<p>Nodes carry a <strong>name</strong> and the node <strong>type</strong>
1442	indicates the kind of node it represents, the most common ones are:</p>
1443	<ul>
1444	<li>document nodes</li>
1445	<li>element nodes</li>
1446	<li>text nodes</li>
1447	</ul>
1448
1449	<p>For the XSLT processing, entity nodes should not be generated (i.e. they
1450	should be replaced by their content). Most nodes also contains the following
1451	"navigation" informations:</p>
1452	<ul>
1453	<li>the containing <strong>doc</strong>ument</li>
1454	<li>the <strong>parent</strong> node</li>
1455	<li>the first <strong>children</strong> node</li>
1456	<li>the <strong>last</strong> children node</li>
1457	<li>the <strong>prev</strong>ious sibling</li>
1458	<li>the following sibling (<strong>next</strong>)</li>
1459	</ul>
1460
1461	<p>Elements nodes carries the list of attributes in the properties, an
1462	attribute itself holds the navigation pointers and the children list (the
1463	attribute value is not represented as a simple string to allow usage of
1464	entities references).</p>
1465
1466	<p>The <strong>ns</strong> points to the namespace declaration for the
1467	namespace associated to the node, <strong>nsDef</strong> is the linked list
1468	of namespace declaration present on element nodes.</p>
1469
1470	<p>Most nodes also carry an <strong>_private</strong> pointer which can be
1471	used by the application to hold specific data on this node.</p>
1472
1473	<h3><a name="XSLT">The XSLT processing steps</a></h3>
1474
1475	<p>There are a few steps which are clearly decoupled at the interface
1476	level:</p>
1477	<ol>
1478	<li>parse the stylesheet and generate a DOM tree</li>
1479	<li>take the stylesheet tree and build a compiled version of it (the
1480	compilation phase)</li>
1481	<li>take the input and generate a DOM tree</li>
1482	<li>process the stylesheet against the input tree and generate an output
1483	tree</li>
1484	<li>serialize the output tree</li>
1485	</ol>
1486
1487	<p>A few things should be noted here:</p>
1488	<ul>
1489	<li>the steps 1/ 3/ and 5/ are optional</li>
1490	<li>the stylesheet obtained at 2/ can be reused by multiple processing 4/
1491	(and this should also work in threaded programs)</li>
1492	<li>the tree provided in 2/ should never be freed using xmlFreeDoc, but by
1493	freeing the stylesheet.</li>
1494	<li>the input tree 4/ is not modified except the _private field which may
1495	be used for labelling keys if used by the stylesheet</li>
1496	</ul>
1497
1498	<h3><a name="XSLT1">The XSLT stylesheet compilation</a></h3>
1499
1500	<p>This is the second step described. It takes a stylesheet tree, and
1501	"compiles" it. This associates to each node a structure stored in the
1502	_private field and containing information computed in the stylesheet:</p>
1503
1504	<p align="center"><img src="stylesheet.gif"
1505	alt="a compiled XSLT stylesheet"></p>
1506
1507	<p>One xsltStylesheet structure is generated per document parsed for the
1508	stylesheet. XSLT documents allow includes and imports of other documents,
1509	imports are stored in the <strong>imports</strong> list (hence keeping the
1510	tree hierarchy of includes which is very important for a proper XSLT
1511	processing model) and includes are stored in the <strong>doclist</strong>
1512	list. An imported stylesheet has a parent link to allow browsing of the
1513	tree.</p>
1514
1515	<p>The DOM tree associated to the document is stored in <strong>doc</strong>.
1516	It is preprocessed to remove ignorable empty nodes and all the nodes in the
1517	XSLT namespace are subject to precomputing. This usually consist of
1518	extracting all the context information from the context tree (attributes,
1519	namespaces, XPath expressions), and storing them in an xsltStylePreComp
1520	structure associated to the <strong>_private</strong> field of the node.</p>
1521
1522	<p>A couple of notable exceptions to this are XSLT template nodes (more on
1523	this later) and attribute value templates. If they are actually templates,
1524	the value cannot be computed at compilation time. (Some preprocessing could
1525	be done like isolation and preparsing of the XPath subexpressions but it's
1526	not done, yet.)</p>
1527
1528	<p>The xsltStylePreComp structure also allows storing of the precompiled form
1529	of an XPath expression that can be associated to an XSLT element (more on
1530	this later).</p>
1531
1532	<h3><a name="XSLT2">The XSLT template compilation</a></h3>
1533
1534	<p>A proper handling of templates lookup is one of the keys of fast XSLT
1535	processing. (Given a node in the source document this is the process of
1536	finding which templates should be applied to this node.) Libxslt follows the
1537	hint suggested in the <a href="http://www.w3.org/TR/xslt#patterns">5.2
1538	Patterns</a> section of the XSLT Recommendation, i.e. it doesn't evaluate it
1539	as an XPath expression but tokenizes it and compiles it as a set of rules to
1540	be evaluated on a candidate node. There usually is an indication of the node
1541	name in the last step of this evaluation and this is used as a key check for
1542	the match. As a result libxslt builds a relatively more complex set of
1543	structures for the templates:</p>
1544
1545	<p align="center"><img src="templates.gif"
1546	alt="The templates related structure"></p>
1547
1548	<p>Let's describe a bit more closely what is built. First the xsltStylesheet
1549	structure holds a pointer to the template hash table. All the XSLT patterns
1550	compiled in this stylesheet are indexed by the value of the the target
1551	element (or attribute, pi ...) name, so when a element or an attribute "foo"
1552	needs to be processed the lookup is done using the name as a key.</p>
1553
1554	<p>Each of the patterns is compiled into an xsltCompMatch structure. It holds
1555	the set of rules based on the tokenization of the pattern stored in reverse
1556	order (matching is easier this way). It also holds some information about the
1557	previous matches used to speed up the process when one iterates over a set of
1558	siblings. (This optimization may be defeated by trashing when running
1559	threaded computation, it's unclear that this is a big deal in practice.)
1560	Predicate expressions are not compiled at this stage, they may be at run-time
1561	if needed, but in this case they are compiled as full XPath expressions (the
1562	use of some fixed predicate can probably be optimized, they are not yet).</p>
1563
1564	<p>The xsltCompMatch are then stored in the hash table, the clash list is
1565	itself sorted by priority of the template to implement "naturally" the XSLT
1566	priority rules.</p>
1567
1568	<p>Associated to the compiled pattern is the xsltTemplate itself containing
1569	the information required for the processing of the pattern including, of
1570	course, a pointer to the list of elements used for building the pattern
1571	result.</p>
1572
1573	<p>Last but not least a number of patterns do not fit in the hash table
1574	because they are not associated to a name, this is the case for patterns
1575	applying to the root, any element, any attributes, text nodes, pi nodes, keys
1576	etc. Those are stored independently in the stylesheet structure as separate
1577	linked lists of xsltCompMatch.</p>
1578
1579	<h3><a name="processing">The processing itself</a></h3>
1580
1581	<p>The processing is defined by the XSLT specification (the basis of the
1582	algorithm is explained in <a
1583	href="http://www.w3.org/TR/xslt#section-Introduction">the Introduction</a>
1584	section). Basically it works by taking the root of the input document and
1585	applying the following algorithm:</p>
1586	<ol>
1587	<li>Finding the template applying to it. This is a lookup in the template
1588	hash table, walking the hash list until the node satisfies all the steps
1589	of the pattern, then checking the appropriate(s) global templates to see
1590	if there isn't a higher priority rule to apply</li>
1591	<li>If there is no template, apply the default rule (recurse on the
1592	children)</li>
1593	<li>else walk the content list of the selected templates, for each of them:
1594	<ul>
1595	<li>if the node is in the XSLT namespace then the node has a _private
1596	field pointing to the preprocessed values, jump to the specific
1597	code</li>
1598	<li>if the node is in an extension namespace, look up the associated
1599	behavior</li>
1600	<li>otherwise copy the node.</li>
1601	</ul>
1602	<p>The closure is usually done through the XSLT
1603	<strong>apply-templates</strong> construct recursing by applying the
1604	adequate template on the input node children or on the result of an
1605	associated XPath selection lookup.</p>
1606	</li>
1607	</ol>
1608
1609	<p>Note that large parts of the input tree may not be processed by a given
1610	stylesheet and that on the opposite some may be processed multiple times.
1611	(This often is the case when a Table of Contents is built).</p>
1612
1613	<p>The module <code>transform.c</code> is the one implementing most of this
1614	logic. <strong>xsltApplyStylesheet()</strong> is the entry point, it
1615	allocates an xsltTransformContext containing the following:</p>
1616	<ul>
1617	<li>a pointer to the stylesheet being processed</li>
1618	<li>a stack of templates</li>
1619	<li>a stack of variables and parameters</li>
1620	<li>an XPath context</li>
1621	<li>the template mode</li>
1622	<li>current document</li>
1623	<li>current input node</li>
1624	<li>current selected node list</li>
1625	<li>the current insertion points in the output document</li>
1626	<li>a couple of hash tables for extension elements and functions</li>
1627	</ul>
1628
1629	<p>Then a new document gets allocated (HTML or XML depending on the type of
1630	output), the user parameters and global variables and parameters are
1631	evaluated. Then <strong>xsltProcessOneNode()</strong> which implements the
1632	1-2-3 algorithm is called on the root element of the input. Step 1/ is
1633	implemented by calling <strong>xsltGetTemplate()</strong>, step 2/ is
1634	implemented by <strong>xsltDefaultProcessOneNode()</strong> and step 3/ is
1635	implemented by <strong>xsltApplyOneTemplate()</strong>.</p>
1636
1637	<h3><a name="XPath">XPath expression compilation</a></h3>
1638
1639	<p>The XPath support is actually implemented in the libxml module (where it
1640	is reused by the XPointer implementation). XPath is a relatively classic
1641	expression language. The only uncommon feature is that it is working on XML
1642	trees and hence has specific syntax and types to handle them.</p>
1643
1644	<p>XPath expressions are compiled using <strong>xmlXPathCompile()</strong>.
1645	It will take an expression string in input and generate a structure
1646	containing the parsed expression tree, for example the expression:</p>
1647	<pre>/doc/chapter[title='Introduction']</pre>
1648
1649	<p>will be compiled as</p>
1650	<pre>Compiled Expression : 10 elements
1651	SORT
1652	COLLECT 'child' 'name' 'node' chapter
1653	COLLECT 'child' 'name' 'node' doc
1654	ROOT
1655	PREDICATE
1656	SORT
1657	EQUAL =
1658	COLLECT 'child' 'name' 'node' title
1659	NODE
1660	ELEM Object is a string : Introduction
1661	COLLECT 'child' 'name' 'node' title
1662	NODE</pre>
1663
1664	<p>This can be tested using the <code>testXPath</code> command (in the
1665	libxml codebase) using the <code>--tree</code> option.</p>
1666
1667	<p>Again, the KISS approach is used. No optimization is done. This could be
1668	an interesting thing to add. <a
1669	href="http://www-106.ibm.com/developerworks/library/x-xslt2/?dwzone=x?open&l=132%2ct=gr%2c+p=saxon">Michael
1670	Kay describes</a> a lot of possible and interesting optimizations done in
1671	Saxon which would be possible at this level. I'm unsure they would provide
1672	much gain since the expressions tends to be relatively simple in general and
1673	stylesheets are still hand generated. Optimizations at the interpretation
1674	sounds likely to be more efficient.</p>
1675
1676	<h3><a name="XPath1">XPath interpretation</a></h3>
1677
1678	<p>The interpreter is implemented by <strong>xmlXPathCompiledEval()</strong>
1679	which is the front-end to <strong>xmlXPathCompOpEval()</strong> the function
1680	implementing the evaluation of the expression tree. This evaluation follows
1681	the KISS approach again. It's recursive and calls
1682	<strong>xmlXPathNodeCollectAndTest()</strong> to collect nodes set when
1683	evaluating a <code>COLLECT</code> node.</p>
1684
1685	<p>An evaluation is done within the framework of an XPath context stored in
1686	an <strong>xmlXPathContext</strong> structure, in the framework of a
1687	transformation the context is maintained within the XSLT context. Its content
1688	follows the requirements from the XPath specification:</p>
1689	<ul>
1690	<li>the current document</li>
1691	<li>the current node</li>
1692	<li>a hash table of defined variables (but not used by XSLT)</li>
1693	<li>a hash table of defined functions</li>
1694	<li>the proximity position (the place of the node in the current node
1695	list)</li>
1696	<li>the context size (the size of the current node list)</li>
1697	<li>the array of namespace declarations in scope (there also is a namespace
1698	hash table but it is not used in the XSLT transformation).</li>
1699	</ul>
1700
1701	<p>For the purpose of XSLT an <strong>extra</strong> pointer has been added
1702	allowing to retrieve the XSLT transformation context. When an XPath
1703	evaluation is about to be performed, an XPath parser context is allocated
1704	containing and XPath object stack (this is actually an XPath evaluation
1705	context, this is a remain of the time where there was no separate parsing and
1706	evaluation phase in the XPath implementation). Here is an overview of the set
1707	of contexts associated to an XPath evaluation within an XSLT
1708	transformation:</p>
1709
1710	<p align="center"><img src="contexts.gif"
1711	alt="The set of contexts associated "></p>
1712
1713	<p>Clearly this is a bit too complex and confusing and should be refactored
1714	at the next set of binary incompatible releases of libxml. For example the
1715	xmlXPathCtxt has a lot of unused parts and should probably be merged with
1716	xmlXPathParserCtxt.</p>
1717
1718	<h3><a name="Descriptio">Description of XPath Objects</a></h3>
1719
1720	<p>An XPath expression manipulates XPath objects. XPath defines the default
1721	types boolean, numbers, strings and node sets. XSLT adds the result tree
1722	fragment type which is basically an unmodifiable node set.</p>
1723
1724	<p>Implementation-wise, libxml follows again a KISS approach, the
1725	xmlXPathObject is a structure containing a type description and the various
1726	possibilities. (Using an enum could have gained some bytes.) In the case of
1727	node sets (or result tree fragments), it points to a separate xmlNodeSet
1728	object which contains the list of pointers to the document nodes:</p>
1729
1730	<p align="center"><img src="object.gif"
1731	alt="An Node set object pointing to "></p>
1732
1733	<p>The <a href="http://xmlsoft.org/html/libxml-xpath.html">XPath API</a> (and
1734	its <a href="http://xmlsoft.org/html/libxml-xpathinternals.html">'internal'
1735	part</a>) includes a number of functions to create, copy, compare, convert or
1736	free XPath objects.</p>
1737
1738	<h3><a name="XPath3">XPath functions</a></h3>
1739
1740	<p>All the XPath functions available to the interpreter are registered in the
1741	function hash table linked from the XPath context. They all share the same
1742	signature:</p>
1743	<pre>void xmlXPathFunc (xmlXPathParserContextPtr ctxt, int nargs);</pre>
1744
1745	<p>The first argument is the XPath interpretation context, holding the
1746	interpretation stack. The second argument defines the number of objects
1747	passed on the stack for the function to consume (last argument is on top of
1748	the stack).</p>
1749
1750	<p>Basically an XPath function does the following:</p>
1751	<ul>
1752	<li>check <code>nargs</code> for proper handling of errors or functions
1753	with variable numbers of parameters</li>
1754	<li>pop the parameters from the stack using <code>obj =
1755	valuePop(ctxt);</code></li>
1756	<li>do the function specific computation</li>
1757	<li>push the result parameter on the stack using <code>valuePush(ctxt,
1758	res);</code></li>
1759	<li>free up the input parameters with
1760	<code>xmlXPathFreeObject(obj);</code></li>
1761	<li>return</li>
1762	</ul>
1763
1764	<p>Sometime the work can be done directly by modifying in-situ the top object
1765	on the stack <code>ctxt->value</code>.</p>
1766
1767	<h3><a name="stack">The XSLT variables stack frame</a></h3>
1768
1769	<p>Not to be confused with XPath object stack, this stack holds the XSLT
1770	variables and parameters as they are defined through the recursive calls of
1771	call-template, apply-templates and default templates. This is used to define
1772	the scope of variables being called.</p>
1773
1774	<p>This part seems to be the most urgent attention right now, first it is
1775	done in a very inefficient way since the location of the variables and
1776	parameters within the stylesheet tree is still done at run time (it really
1777	should be done statically at compile time), and I am still unsure that my
1778	understanding of the template variables and parameter scope is actually
1779	right.</p>
1780
1781	<p>This part of the documentation is still to be written once this part of
1782	the code will be stable. <span
1783	style="background-color: #FF0000">TODO</span></p>
1784
1785	<h3><a name="Extension">Extension support</a></h3>
1786
1787	<p>There is a separate document explaining <a href="extensions.html">how the
1788	extension support works</a>.</p>
1789
1790	<h3><a name="Futher">Further reading</a></h3>
1791
1792	<p>Michael Kay wrote <a
1793	href="http://www-106.ibm.com/developerworks/library/x-xslt2/?dwzone=x?open&l=132%2ct=gr%2c+p=saxon">a
1794	really interesting article on Saxon internals</a> and the work he did on
1795	performance issues. I wishes I had read it before starting libxslt design (I
1796	would probably have avoided a few mistakes and progressed faster). A lot of
1797	the ideas in his papers should be implemented or at least tried in
1798	libxslt.</p>
1799
1800	<p>The <a href="http://xmlsoft.org/">libxml documentation</a>, especially <a
1801	href="http://xmlsoft.org/xmlio.html">the I/O interfaces</a> and the <a
1802	href="http://xmlsoft.org/xmlmem.html">memory management</a>.</p>
1803
1804	<h3><a name="TODOs">TODOs</a></h3>
1805
1806	<p>redesign the XSLT stack frame handling. Far too much work is done at
1807	execution time. Similarly for the attribute value templates handling, at
1808	least the embedded subexpressions ought to be precompiled.</p>
1809
1810	<p>Allow output to be saved to a SAX like output (this notion of SAX like API
1811	for output should be added directly to libxml).</p>
1812
1813	<p>Implement and test some of the optimization explained by Michael Kay
1814	especially:</p>
1815	<ul>
1816	<li>static slot allocation on the stack frame</li>
1817	<li>specific boolean interpretation of an XPath expression</li>
1818	<li>some of the sorting optimization</li>
1819	<li>Lazy evaluation of location path. (this may require more changes but
1820	sounds really interesting. XT does this too.)</li>
1821	<li>Optimization of an expression tree (This could be done as a completely
1822	independent module.)</li>
1823	</ul>
1824
1825	<p></p>
1826
1827	<p>Error reporting, there is a lot of case where the XSLT specification
1828	specify that a given construct is an error are not checked adequately by
1829	libxslt. Basically one should do a complete pass on the XSLT spec again and
1830	add all tests to the stylesheet compilation. Using the DTD provided in the
1831	appendix and making direct checks using the libxml validation API sounds a
1832	good idea too (though one should take care of not raising errors for
1833	elements/attributes in different namespaces).</p>
1834
1835	<p>Double check all the places where the stylesheet compiled form might be
1836	modified at run time (extra removal of blanks nodes, hint on the
1837	xsltCompMatch).</p>
1838
1839	<p></p>
1840
1841	<h2><a name="Extensions">Writing extensions</a></h2>
1842
1843	<h3>Table of content</h3>
1844	<ul>
1845	<li><a href="extensions.html#Introducti">Introduction</a></li>
1846	<li><a href="extensions.html#Basics">Basics</a></li>
1847	<li><a href="extensions.html#Keep">Extension modules</a></li>
1848	<li><a href="extensions.html#Registerin">Registering a module</a></li>
1849	<li><a href="extensions.html#module">Loading a module</a></li>
1850	<li><a href="extensions.html#Registerin1">Registering an extension
1851	function</a></li>
1852	<li><a href="extensions.html#Implementi">Implementing an extension
1853	function</a></li>
1854	<li><a href="extensions.html#Examples">Examples for extension
1855	functions</a></li>
1856	<li><a href="extensions.html#Registerin2">Registering an extension
1857	element</a></li>
1858	<li><a href="extensions.html#Implementi1">Implementing an extension
1859	element</a></li>
1860	<li><a href="extensions.html#Example">Example for extension
1861	elements</a></li>
1862	<li><a href="extensions.html#shutdown">The shutdown of a module</a></li>
1863	<li><a href="extensions.html#Future">Future work</a></li>
1864	</ul>
1865
1866	<h3><a name="Introducti1">Introduction</a></h3>
1867
1868	<p>This document describes the work needed to write extensions to the
1869	standard XSLT library for use with <a
1870	href="http://xmlsoft.org/XSLT/">libxslt</a>, the <a
1871	href="http://www.w3.org/TR/xslt">XSLT</a> C library developed for the <a
1872	href="http://www.gnome.org/">Gnome</a> project.</p>
1873
1874	<p>Before starting reading this document it is highly recommended to get
1875	familiar with <a href="internals.html">the libxslt internals</a>.</p>
1876
1877	<p>Note: this documentation is by definition incomplete and I am not good at
1878	spelling, grammar, so patches and suggestions are <a
1879	href="mailto:veillard@redhat.com">really welcome</a>.</p>
1880
1881	<h3><a name="Basics">Basics</a></h3>
1882
1883	<p>The <a href="http://www.w3.org/TR/xslt">XSLT specification</a> provides
1884	two <a href="http://www.w3.org/TR/xslt">ways to extend an XSLT engine</a>:</p>
1885	<ul>
1886	<li>providing <a href="http://www.w3.org/TR/xslt">new extension
1887	functions</a> which can be called from XPath expressions</li>
1888	<li>providing <a href="http://www.w3.org/TR/xslt">new extension
1889	elements</a> which can be inserted in stylesheets</li>
1890	</ul>
1891
1892	<p>In both cases the extensions need to be associated to a new namespace,
1893	i.e. an URI used as the name for the extension's namespace (there is no need
1894	to have a resource there for this to work).</p>
1895
1896	<p>libxslt provides a few extensions itself, either in the libxslt namespace
1897	"http://xmlsoft.org/XSLT/namespace" or in namespaces for other well known
1898	extensions provided by other XSLT processors like Saxon, Xalan or XT.</p>
1899
1900	<h3><a name="Keep">Extension modules</a></h3>
1901
1902	<p>Since extensions are bound to a namespace name, usually sets of extensions
1903	coming from a given source are using the same namespace name defining in
1904	practice a group of extensions providing elements, functions or both. From
1905	the libxslt point of view those are considered as an "extension module", and
1906	most of the APIs work at a module point of view.</p>
1907
1908	<p>Registration of new functions or elements are bound to the activation of
1909	the module. This is currently done by declaring the namespace as an extension
1910	by using the attribute <code>extension-element-prefixes</code> on the
1911	<code><a href="http://www.w3.org/TR/xslt">xsl:stylesheet</a></code>
1912	element.</p>
1913
1914	<p>An extension module is defined by 3 objects:</p>
1915	<ul>
1916	<li>the namespace name associated</li>
1917	<li>an initialization function</li>
1918	<li>a shutdown function</li>
1919	</ul>
1920
1921	<h3><a name="Registerin">Registering a module</a></h3>
1922
1923	<p>Currently a libxslt module has to be compiled within the application using
1924	libxslt. There is no code to load dynamically shared libraries associated to
1925	a namespace (this may be added but is likely to become a portability
1926	nightmare).</p>
1927
1928	<p>The current way to register a module is to link the code implementing it
1929	with the application and to call a registration function:</p>
1930	<pre>int xsltRegisterExtModule(const xmlChar *URI,
1931	xsltExtInitFunction initFunc,
1932	xsltExtShutdownFunction shutdownFunc);</pre>
1933
1934	<p>The associated header is read by:</p>
1935	<pre>#include<libxslt/extensions.h></pre>
1936
1937	<p>which also defines the type for the initialization and shutdown
1938	functions</p>
1939
1940	<h3><a name="module">Loading a module</a></h3>
1941
1942	<p>Once the module URI has been registered and if the XSLT processor detects
1943	that a given stylesheet needs the functionalities of an extended module, this
1944	one is initialized.</p>
1945
1946	<p>The xsltExtInitFunction type defines the interface for an initialization
1947	function:</p>
1948	<pre>/**
1949	* xsltExtInitFunction:
1950	* @ctxt: an XSLT transformation context
1951	* @URI: the namespace URI for the extension
1952	*
1953	* A function called at initialization time of an XSLT
1954	* extension module
1955	*
1956	* Returns a pointer to the module specific data for this
1957	* transformation
1958	*/
1959	typedef void (xsltExtInitFunction)(xsltTransformContextPtr ctxt,
1960	const xmlChar *URI);</pre>
1961
1962	<p>There are 3 things to notice:</p>
1963	<ul>
1964	<li>The function gets passed the namespace name URI as an argument. This
1965	allows a single function to provide the initialization for multiple
1966	logical modules.</li>
1967	<li>It also gets passed a transformation context. The initialization is
1968	done at run time before any processing occurs on the stylesheet but it
1969	will be invoked separately each time for each transformation.</li>
1970	<li>It returns a pointer. This can be used to store module specific
1971	information which can be retrieved later when a function or an element
1972	from the extension is used. An obvious example is a connection to a
1973	database which should be kept and reused along with the transformation.
1974	NULL is a perfectly valid return; there is no way to indicate a failure
1975	at this level</li>
1976	</ul>
1977
1978	<p>What this function is expected to do is:</p>
1979	<ul>
1980	<li>prepare the context for this module (like opening the database
1981	connection)</li>
1982	<li>register the extensions specific to this module</li>
1983	</ul>
1984
1985	<h3><a name="Registerin1">Registering an extension function</a></h3>
1986
1987	<p>There is a single call to do this registration:</p>
1988	<pre>int xsltRegisterExtFunction(xsltTransformContextPtr ctxt,
1989	const xmlChar *name,
1990	const xmlChar *URI,
1991	xmlXPathEvalFunc function);</pre>
1992
1993	<p>The registration is bound to a single transformation instance referred by
1994	ctxt, name is the UTF8 encoded name for the NCName of the function, and URI
1995	is the namespace name for the extension (no checking is done, a module could
1996	register functions or elements from a different namespace, but it is not
1997	recommended).</p>
1998
1999	<h3><a name="Implementi">Implementing an extension function</a></h3>
2000
2001	<p>The implementation of the function must have the signature of a libxml
2002	XPath function:</p>
2003	<pre>/**
2004	* xmlXPathEvalFunc:
2005	* @ctxt: an XPath parser context
2006	* @nargs: the number of arguments passed to the function
2007	*
2008	* an XPath evaluation function, the parameters are on the
2009	* XPath context stack
2010	*/
2011
2012	typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt,
2013	int nargs);</pre>
2014
2015	<p>The context passed to an XPath function is not an XSLT context but an <a
2016	href="internals.html#XPath1">XPath context</a>. However it is possible to
2017	find one from the other:</p>
2018	<ul>
2019	<li>The function xsltXPathGetTransformContext provides this lookup facility:
2020	<pre>xsltTransformContextPtr
2021	xsltXPathGetTransformContext
2022	(xmlXPathParserContextPtr ctxt);</pre>
2023	</li>
2024	<li>The <code>xmlXPathContextPtr</code> associated to an
2025	<code>xsltTransformContext</code> is stored in the <code>xpathCtxt</code>
2026	field.</li>
2027	</ul>
2028
2029	<p>The first thing an extension function may want to do is to check the
2030	arguments passed on the stack, the <code>nargs</code> parameter will tell how
2031	many of them were provided on the XPath expression. The macro valuePop will
2032	extract them from the XPath stack:</p>
2033	<pre>#include <libxml/xpath.h>
2034	#include <libxml/xpathInternals.h>
2035
2036	xmlXPathObjectPtr obj = valuePop(ctxt); </pre>
2037
2038	<p>Note that <code>ctxt</code> is the XPath context not the XSLT one. It is
2039	then possible to examine the content of the value. Check <a
2040	href="internals.html#Descriptio">the description of XPath objects</a> if
2041	necessary. The following is a common sequence checking whether the argument
2042	passed is a string and converting it using the built-in XPath
2043	<code>string()</code> function if this is not the case:</p>
2044	<pre>if (obj->type != XPATH_STRING) {
2045	valuePush(ctxt, obj);
2046	xmlXPathStringFunction(ctxt, 1);
2047	obj = valuePop(ctxt);
2048	}</pre>
2049
2050	<p>Most common XPath functions are available directly at the C level and are
2051	exported either in <code><libxml/xpath.h></code> or in
2052	<code><libxml/xpathInternals.h></code>.</p>
2053
2054	<p>The extension function may also need to retrieve the data associated to
2055	this module instance (the database connection in the previous example) this
2056	can be done using the xsltGetExtData:</p>
2057	<pre>void * xsltGetExtData(xsltTransformContextPtr ctxt,
2058	const xmlChar *URI);</pre>
2059
2060	<p>Again the URI to be provided is the one which was used when registering
2061	the module.</p>
2062
2063	<p>Once the function finishes, don't forget to:</p>
2064	<ul>
2065	<li>push the return value on the stack using <code>valuePush(ctxt,
2066	obj)</code></li>
2067	<li>deallocate the parameters passed to the function using
2068	<code>xmlXPathFreeObject(obj)</code></li>
2069	</ul>
2070
2071	<h3><a name="Examples">Examples for extension functions</a></h3>
2072
2073	<p>The module libxslt/functions.c contains the sources of the XSLT built-in
2074	functions, including document(), key(), generate-id(), etc. as well as a full
2075	example module at the end. Here is the test function implementation for the
2076	libxslt:test function:</p>
2077	<pre>/**
2078	* xsltExtFunctionTest:
2079	* @ctxt: the XPath Parser context
2080	* @nargs: the number of arguments
2081	*
2082	* function libxslt:test() for testing the extensions support.
2083	*/
2084	static void
2085	xsltExtFunctionTest(xmlXPathParserContextPtr ctxt, int nargs)
2086	{
2087	xsltTransformContextPtr tctxt;
2088	void *data;
2089
2090	tctxt = xsltXPathGetTransformContext(ctxt);
2091	if (tctxt == NULL) {
2092	xsltGenericError(xsltGenericErrorContext,
2093	"xsltExtFunctionTest: failed to get the transformation context\n");
2094	return;
2095	}
2096	data = xsltGetExtData(tctxt, (const xmlChar *) XSLT_DEFAULT_URL);
2097	if (data == NULL) {
2098	xsltGenericError(xsltGenericErrorContext,
2099	"xsltExtFunctionTest: failed to get module data\n");
2100	return;
2101	}
2102	#ifdef WITH_XSLT_DEBUG_FUNCTION
2103	xsltGenericDebug(xsltGenericDebugContext,
2104	"libxslt:test() called with %d args\n", nargs);
2105	#endif
2106	}</pre>
2107
2108	<h3><a name="Registerin2">Registering an extension element</a></h3>
2109
2110	<p>There is a single call to do this registration:</p>
2111	<pre>int xsltRegisterExtElement(xsltTransformContextPtr ctxt,
2112	const xmlChar *name,
2113	const xmlChar *URI,
2114	xsltTransformFunction function);</pre>
2115
2116	<p>It is similar to the mechanism used to register an extension function,
2117	except that the signature of an extension element implementation is
2118	different.</p>
2119
2120	<p>The registration is bound to a single transformation instance referred to
2121	by ctxt, name is the UTF8 encoded name for the NCName of the element, and URI
2122	is the namespace name for the extension (no checking is done, a module could
2123	register elements for a different namespace, but it is not recommended).</p>
2124
2125	<h3><a name="Implementi1">Implementing an extension element</a></h3>
2126
2127	<p>The implementation of the element must have the signature of an XSLT
2128	transformation function:</p>
2129	<pre>/**
2130	* xsltTransformFunction:
2131	* @ctxt: the XSLT transformation context
2132	* @node: the input node
2133	* @inst: the stylesheet node
2134	* @comp: the compiled information from the stylesheet
2135	*
2136	* signature of the function associated to elements part of the
2137	* stylesheet language like xsl:if or xsl:apply-templates.
2138	*/
2139	typedef void (*xsltTransformFunction)
2140	(xsltTransformContextPtr ctxt,
2141	xmlNodePtr node,
2142	xmlNodePtr inst,
2143	xsltStylePreCompPtr comp);</pre>
2144
2145	<p>The first argument is the XSLT transformation context. The second and
2146	third arguments are xmlNodePtr i.e. internal memory <a
2147	href="internals.html#libxml">representation of XML nodes</a>. They are
2148	respectively <code>node</code> from the the input document being transformed
2149	by the stylesheet and <code>inst</code> the extension element in the
2150	stylesheet. The last argument is <code>comp</code> a pointer to a precompiled
2151	representation of <code>inst</code> but usually for an extension function
2152	this value is <code>NULL</code> by default (it could be added and associated
2153	to the instruction in <code>inst->_private</code>).</p>
2154
2155	<p>The same functions are available from a function implementing an extension
2156	element as in an extension function, including
2157	<code>xsltGetExtData()</code>.</p>
2158
2159	<p>The goal of an extension element being usually to enrich the generated
2160	output, it is expected that they will grow the currently generated output
2161	tree. This can be done by grabbing ctxt->insert which is the current
2162	libxml node being generated (Note this can also be the intermediate value
2163	tree being built for example to initialize a variable, the processing should
2164	be similar). The functions for libxml tree manipulation from <a
2165	href="http://xmlsoft.org/html/libxml-tree.html"><libxml/tree.h></a> can
2166	be employed to extend or modify the tree, but it is required to preserve the
2167	insertion node and its ancestors since there are existing pointers to those
2168	elements still in use in the XSLT template execution stack.</p>
2169
2170	<h3><a name="Example">Example for extension elements</a></h3>
2171
2172	<p>The module libxslt/transform.c contains the sources of the XSLT built-in
2173	elements, including xsl:element, xsl:attribute, xsl:if, etc. There is a small
2174	but full example in functions.c providing the implementation for the
2175	libxslt:test element, it will output a comment in the result tree:</p>
2176	<pre>/**
2177	* xsltExtElementTest:
2178	* @ctxt: an XSLT processing context
2179	* @node: The current node
2180	* @inst: the instruction in the stylesheet
2181	* @comp: precomputed informations
2182	*
2183	* Process a libxslt:test node
2184	*/
2185	static void
2186	xsltExtElementTest(xsltTransformContextPtr ctxt, xmlNodePtr node,
2187	xmlNodePtr inst,
2188	xsltStylePreCompPtr comp)
2189	{
2190	xmlNodePtr comment;
2191
2192	if (ctxt == NULL) {
2193	xsltGenericError(xsltGenericErrorContext,
2194	"xsltExtElementTest: no transformation context\n");
2195	return;
2196	}
2197	if (node == NULL) {
2198	xsltGenericError(xsltGenericErrorContext,
2199	"xsltExtElementTest: no current node\n");
2200	return;
2201	}
2202	if (inst == NULL) {
2203	xsltGenericError(xsltGenericErrorContext,
2204	"xsltExtElementTest: no instruction\n");
2205	return;
2206	}
2207	if (ctxt->insert == NULL) {
2208	xsltGenericError(xsltGenericErrorContext,
2209	"xsltExtElementTest: no insertion point\n");
2210	return;
2211	}
2212	comment =
2213	xmlNewComment((const xmlChar *)
2214	"libxslt:test element test worked");
2215	xmlAddChild(ctxt->insert, comment);
2216	}</pre>
2217
2218	<h3><a name="shutdown">The shutdown of a module</a></h3>
2219
2220	<p>When the XSLT processor ends a transformation, the shutdown function (if
2221	it exists) for each of the modules initialized is called. The
2222	xsltExtShutdownFunction type defines the interface for a shutdown
2223	function:</p>
2224	<pre>/**
2225	* xsltExtShutdownFunction:
2226	* @ctxt: an XSLT transformation context
2227	* @URI: the namespace URI for the extension
2228	* @data: the data associated to this module
2229	*
2230	* A function called at shutdown time of an XSLT extension module
2231	*/
2232	typedef void (*xsltExtShutdownFunction) (xsltTransformContextPtr ctxt,
2233	const xmlChar *URI,
2234	void *data);</pre>
2235
2236	<p>This is really similar to a module initialization function except a third
2237	argument is passed, it's the value that was returned by the initialization
2238	function. This allows the routine to deallocate resources from the module for
2239	example close the connection to the database to keep the same example.</p>
2240
2241	<h3><a name="Future">Future work</a></h3>
2242
2243	<p>Well, some of the pieces missing:</p>
2244	<ul>
2245	<li>a way to load shared libraries to instantiate new modules</li>
2246	<li>a better detection of extension functions usage and their registration
2247	without having to use the extension prefix which ought to be reserved to
2248	element extensions.</li>
2249	<li>more examples</li>
2250	<li>implementations of the <a href="http://www.exslt.org/">EXSLT</a> common
2251	extension libraries, Thomas Broyer nearly finished implementing them.</li>
2252	</ul>
2253
2254	<p></p>
2255
2256	<h2><a name="Contributi">Contributions</a></h2>
2257	<ul>
2258	<li>Bjorn Reese is the author of the number support and worked on the
2259	XSLTMark support</li>
2260	<li>William Brack was an early adopted, contributed a number of patches and
2261	spent quite some time debugging non-trivial problems in early versions of
2262	libxslt</li>
2263	<li><a href="mailto:igor@zlatkovic.com">Igor Zlatkovic</a> is now the
2264	maintainer of the Windows port, <a
2265	href="http://www.zlatkovic.com/projects/libxml/index.html">he provides
2266	binaries</a></li>
2267	<li>Thomas Broyer provided a lot of suggestions, and drafted most of the
2268	extension API</li>
2269	<li>John Fleck maintains <a href="tutorial/libxslttutorial.html">a tutorial
2270	for libxslt</a></li>
2271	<li><a
2272	href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">Matt
2273	Sergeant</a> developed <a
2274	href="http://axkit.org/download/">XML::LibXSLT</a>, a perl wrapper for
2275	libxml2/libxslt as part of the <a href="http://axkit.com/">AxKit XML
2276	application server</a></li>
2277	<li>there is a module for <a
2278	href="http://acs-misc.sourceforge.net/nsxml.html">libxml/libxslt support
2279	in OpenNSD/AOLServer</a></li>
2280	<li><a href="mailto:dkuhlman@cutter.rexx.com">Dave Kuhlman</a> provides
2281	libxml/libxslt <a href="http://www.rexx.com/~dkuhlman">wrappers for
2282	Python</a></li>
2283	<li><a href="mailto:Steve.Ball@zveno.com">Steve Ball</a>, <a
2284	href="http://www.zveno.com/">Zveno</a> and contributors maintain <a
2285	href="http://tclxml.sourceforge.net/">tcl bindings for libxml2 and
2286	libxslt</a>, as well as <a
2287	href="http://tclxml.sf.net/tkxmllint.html">tkxmllint</a> a GUI for
2288	xmllint and <a href="http://tclxml.sf.net/tkxsltproc.html">tkxsltproc</a>
2289	a GUI for xsltproc.</li>
2290	<li>If you want to use libxslt in a Mac OS X/Cocoa or Objective-C
2291	framework, Marc Liyanage provides <a
2292	href="http://www.entropy.ch/software/macosx/#testxslt">an application
2293	TestXSLT for XSLT and XML editing</a> including wrapper classes for the
2294	XML parser and XSLT processor.</li>
2295	</ul>
2296
2297	<p></p>
2298
2299	<p><a href="mailto:daniel@veillard.com">Daniel Veillard</a></p>
2300	</body>
2301	</html>

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: trunk/third/libxslt/doc/xslt.html @ 21535

Download in other formats: