xslt.html@ 7979

Last change on this file since 7979 was 7296, checked in by vboxsync, 17 years ago
Added libxslt-1.1.22 sources.
Property svn:eol-style set to `native` Property svn:keywords set to `Date Revision Author Id`
File size: 105.5 KB

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

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

source: vbox/trunk/src/libs/libxslt-1.1.22/doc/xslt.html@ 7979

Download in other formats: