1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
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">
10 <body bgcolor="#ffffff">
11 <h1 align="center">The XSLT C library for GNOME</h1>
13 <h1 style="text-align: center">libxslt</h1>
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>
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>
27 <p>External documents:</p>
29 <li>John Fleck wrote <a href="tutorial/libxslttutorial.html">a tutorial for
31 <li><a href="xsltproc.html">xsltproc user manual</a></li>
32 <li><a href="http://xmlsoft.org/">the libxml documentation</a></li>
37 <p>Logo designed by <a href="mailto:liyanage@access.ch">Marc Liyanage</a>.</p>
39 <h2><a name="Introducti">Introduction</a></h2>
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>
45 <p>Here are some key points about libxslt:</p>
47 <li>Libxslt is a C implementation</li>
48 <li>Libxslt is based on libxml for XML parsing, tree manipulation and XPath
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
56 <li>Though not designed primarily with performances in mind, libxslt seems
57 to be a relatively fast processor.</li>
60 <h2><a name="Documentat">Documentation</a></h2>
62 <p>There are some on-line resources about using libxslt:</p>
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
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>
74 <h2><a name="Reporting">Reporting bugs and getting help</a></h2>
76 <p>If you need help with the XSLT language itself, here are a number of
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
83 <li>The <a href="http://www.dpawson.co.uk/xsl/xslfaq.html">XSL FAQ</a>.</li>
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>
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>
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
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>
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>
116 <p>There is also a mailing-list <a
117 href="mailto:xslt@gnome.org">xslt@gnome.org</a> for libxslt, with an <a
118 href="http://mail.gnome.org/archives/xslt/">on-line archive</a>. To subscribe
119 to this list, please visit the <a
120 href="http://mail.gnome.org/mailman/listinfo/xslt">associated Web</a> page
121 and follow the instructions.</p>
123 <p>Alternatively, you can just send the bug to the <a
124 href="mailto:xslt@gnome.org">xslt@gnome.org</a> list, if it's really libxslt
125 related I will approve it.. Please do not send me mail directly especially
126 for portability problem, it makes things really harder to track and in some
127 cases I'm not the best person to answer a given question, ask the list
128 instead. <strong>Do not send code, I won't debug it</strong> (but patches are
129 really appreciated!).</p>
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
145 <p>Check the following too <span style="color: #E50000">before
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
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>
165 <p>Then send the bug with associated information to reproduce it to the <a
166 href="mailto:xslt@gnome.org">xslt@gnome.org</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>
171 <p>To <span style="color: #E50000">be really clear about support</span>:</p>
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 xslt@gnome.org mailing list for any technical reply made about libxml2 or
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
189 <p>Of course, bugs reports with a suggested patch for fixing them will
190 probably be processed faster.</p>
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>
200 <h2><a name="help">How to help</a></h2>
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
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
212 <li>provide documentation fixes (either as patches to the code comments or
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:daniel@veillard.com">Get in touch with me
218 </a>before to avoid synchronization problems and check that the suggested
219 fix will fit in nicely :-)</li>
222 <h2><a name="Downloads">Downloads</a></h2>
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:igor@zlatkovic.com">Igor Zlatkovic</a> is now the maintainer of
238 href="http://www.zlatkovic.com/projects/libxml/index.html">he provides
239 binaries</a>. <a href="http://opencsw.org/">CSW</a> provides
240 <a href="http://opencsw.org/packages/libxslt">Solaris binaries</a>, and
241 <a href="mailto:Steve.Ball@explain.com.au">Steve Ball</a> provides <a
242 href="http://www.explain.com.au/oss/libxml2xslt.html">Mac Os X
245 <p><a name="Contribs">Contribs:</a></p>
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>
251 <p>Libxslt is also available from SVN:</p>
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>
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>
262 <h2><a name="FAQ">FAQ</a></h2>
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
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>
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>
291 <p>xsltproc --stringparam test alpha foo.xsl foo.xml</p>
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>
300 <h2><a name="News">News</a></h2>
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>
305 <p>Those are the public releases made:</p>
307 <h3>1.1.25: Sep 17 2009</h3>
310 Add API versioning and various cleanups (Daniel Veillard),
311 xsl:sort lang support using the locale (Nick Wellnhofer and Roumen Petrov)
314 Fix the download links for Solaris (Daniel Veillard),
315 Fix makefile and spec file to include doc in rpm (Daniel Veillard)
318 Make sure testThreads is linked with pthreads (Daniel Veillard),
319 Fix potential crash on debug of extensions Solaris (Ben Walton),
320 applied patch from Roumen Petrov for mingw cross compilation problems (Roumen Petrov),
321 patch from Richard Jones to build shared libs with MinGW cross-compiler (Richard Jones),
322 fix include path when compiling with MinGW (Roumen Petrov),
323 portability fixes ( Nick Wellnhofer and Roumen Petrov)
326 Big fixes of pattern compilations (Nick Wellnhofer),
327 Fix uses of xmlAddChild for error handling (Daniel Veillard),
328 Detect deep recusion on function calls (Daniel Veillard),
329 Avoid an error in namespace generation (Martin),
330 Fix importing of encoding from included stylesheets (Nick Wellnhofer),
331 Fix problems with embedded stylesheets and namespaces (Martin),
332 QName parsing fix for patterns (Martin),
333 Crash compiling stylesheet with DTD (Martin),
334 Fix xsl:strip-space with namespace and wildcard (Nick Wellnhofer),
335 Fix a mutex deadlock on unregistered extensions (Nix),
336 567192 xsltproc --output option ignore --xinclude (Joachim Breitner),
337 Fix redundant headers in list (Daniel Veillard),
338 134754 Configure's --with-html-dir related fixes (Julio M. Merino Vidal),
339 305913 a serious problem in extensions reentrancy (Daniel Veillard),
340 Fix an idness issue when building the tree (Daniel Veillard),
341 Fixed indexing error reported by Ron Burk on the mailing list. (William M. Brack),
342 prevent some unchecked pointer accesses (Jake Goulding),
343 fix for CVE-2008-2935 libexslt RC4 encryption/decryption functions Daniel (Daniel Veillard),
344 avoid a quadratic behaviour when hitting duplicates (Daniel Veillard),
345 544829 fixed option --with-debugger (Arun Ragnavan),
346 541965 fixed incorrect argument popping in exsltMathAtan2Function (William M. Brack),
347 fix problem with string check for element-available (Ron Burk),
348 539741 added code to handle literal within an AVT (William M. Brack)
351 Allow use of EXSLT outside XSLT (Martin),
352 Support Esperanto locale (Nick Wellnhofer),
353 Change how attributes are copied for id and speed (Daniel Veillard),
354 Add API versioning and various cleanups (Daniel Veillard),
355 Adding a test program to check thread reentrancy (Daniel Veillard),
356 big patch from finishing xsl:sort lang support (Roumen Petrov),
357 add xsl:sort lang support using the locale (Nick Wellnhofer)
360 Label xsltProcessOneNode as static (Daniel Veillard),
361 git setup (Daniel Veillard),
362 fixed typo detected by new libxml2 code (William M. Brack),
363 xsltExtFunctionLookup was defined but never implemented (Ralf Junker)
366 <h3>1.1.24: May 13 2008</h3>
368 <li>Documentation: man page fix (Vincent Lefevre).</li>
369 <li>Bug fixes: pattern bug fix, key initialization problems, exclusion of
370 unknown namespaced element on top of stylesheets, python generator
371 syntactic cleanup (Martin)</li>
373 <h3>1.1.23: Apr 8 2008</h3>
375 <li>Documentation: fix links for Cygwin DocBook setup (Philippe Bourcier),
376 xsltParseStylesheetDoc doc fix (Jason Viers), fix manpage default
378 <li>Bug fixes: python segfault (Daniel Gryniewicz), week-in-year bug fix
379 (Maurice van der Pot), fix python iterator problem (William Brack),
380 avoid garbage collection problems on str:tokenize and str:split
381 and function results (William Brack and Peter Pawlowski)
382 superfluous re-generation of keys (William Brack), remove superfluous
383 code in xsltExtInitTest (Tony Graham), func:result segfault fix
384 (William Brack), timezone offset problem (Peter Pawlowski),</li>
385 <li>Portability fixes: old gcrypt support fix (Brent Cowgill), Python
386 portability patch (Stephane Bidoul), VS 2008 fix (Rob Richard) </li>
388 <h3>1.1.22: Aug 23 2007</h3>
390 <li>Bug fixes: RVT cleanup problems (William Brack), exclude-result-prefix
391 bug (William Brack), stylesheet compilation error handling (Rob Richards).
393 <li>Portability fixes: improve build with VS2005 (Rob Richards),
394 fixing build on AIX (Bjorn Wiberg), fix the security file checks on
395 Windows (Roland Schwarz and Rob Richards). </li>
396 <li>Improvement: add an --encoding option to xsltproc (Drazen Kacar). </li>
398 <h3>1.1.21: Jun 12 2007</h3>
400 <li>Bug fixes: out of memory allocation errors (William Brack),
401 namespace problem on compound predicates (William Brack),
402 python space/tab inconsistencies (Andreas Hanke), hook xsl:message
403 to per transformation error callbacks (Shaun McCance),
404 cached RVT problem (William Brack), XPath context maintainance
405 on choose (William Brack), memory leaks in the math module (William
406 Brack), exclude-result-prefix induced namespace problem (William
408 <li>Build: configure setup for TRIO_REPLACE_STDIO (William Brack)
409 <li>Documentation: updated after change from CVs to SVN (William Brack)</li>
411 <h3>1.1.20: Jan 17 2007</h3>
413 <li>Portability fixes: strict aliasing fix (Marcus Meissner), BSD portability
414 patches (Roland Illig)</li>
415 <li>Bug fixes: Result Value Tree handling fix (William Brack), function
416 parameters fix (William), uninitialized variable (Kjartan Maraas),
417 empty text node handling (William), plugin support and test fixes (William),
418 fragment support fixes (William)</li>
419 <li>Improvements: python stylesheet compare and transform context
420 access (Nic Ferrier), EXSLT string replace support (Joel Reed),
421 xsltproc better low level error handling (Mike Hommey and William)</li>
423 <h3>1.1.19: Nov 29 2006</h3>
425 <li>Bug fixes: entities within attributes (William Brack), Python detection
426 problem (Joseph Sacco), in-scope namespace bug (Mike Hommey), Result
427 value tree caching bug (William Brack)</li>
429 <h3>1.1.18: Oct 26 2006</h3>
431 <li>portability and build fixes: DESTDIR problem, build paths in python
432 shared lib, compile when libxml2 doesn't support XInclude (Gary Coady).</li>
433 <li>bug fixes: a number of namespace related bugs (Kasimier Buchcik),
434 parameters bugs (Kasimier Buchcik), proximity position in predicates
435 of match patterns (Kasimier), exslt-node-set troubles with strings
436 (Kasimier), CDATA serialization, Python floats and booleans XPath
437 conversions, XInclude support fixes, RVT cleanup problem (William Brack
438 and Kasimier), attribute checking in stylesheets (Kasimier), xsltForEach
439 context problem (Kasimier), security check should pass full URLs (Shane
440 Corgatelli), security cleanup patch (Mikhail Zabaluev), some python
441 accessor for stylesheet were broken, memory errors when compiling
442 stylesheets (Mike Hommey), EXSLT current date end-of-month problem
443 (William Brack).</li>
444 <li>improvements: refactoring of namespace handling, value-of impleemntation
445 and template internal processing (Kasimier Buchcik), new xsltproc
446 flag to apply Xinclude to stylesheets.</li>
447 <li>documentation: xsltproc man pages (Daniel Leidert), tests updates
448 (William Brack), various typo fixes (Daniel Leidert), comments on
449 versions macros (Peter Breitenlohner).</li>
451 <h3>1.1.17: Jun 6 2006</h3>
453 <li>portability fixes: python detection</li>
454 <li>bug fixes: some regression tests, attribute/namespaces output (Kasimier
455 Buchcik), problem in mixed xsl:value-of and xsl:text uses (Kasimier)</li>
456 <li>improvements: internal refactoring (Kasimier Buchcik), use of the XPath
457 object cache in libxml2-2.6.25 (Kasimier)</li>
460 <h3>1.1.16: May 01 2006</h3>
462 <li>portability fixes: EXSLT date/time on Solaris and IRIX (Albert Chin),
463 HP-UX build (Albert Chin),
464 <li>build fixes: Python detection(Joseph Sacco), plugin configurei
466 <li>bug fixes: pattern compilation fix(William Brack), EXSLT date/time
467 fix (Thomas Broyer), EXSLT function bug, potential loop on variable
468 eval, startup race (Christopher Palmer), debug statement left in python
469 (Nic Ferrier), various cleanup based on Coverity reports), error on
470 Out of memory condition (Charles Hardin), various namespace prefixes
471 fixes (Kasimier Buchcik), </li>
472 <li>improvement: speed up sortingi, start of internals refactoring (Kasimier
474 <li>documentation: man page fixes and updates (Daniel Leidert)
477 <h3>1.1.15: Sep 04 2005</h3>
479 <li>build fixes: Windows build cleanups and updates (Igor Zlatkovic),
480 remove jhbuild warnings</li>
481 <li>bug fixes: negative number formatting (William Brack), number
482 formatting per mille definition (William Brack), XInclude default values
483 (William), text copy bugs (William), bug related to xmlXPathContext size,
484 reuse libxml2 memory management for text nodes, dictionary text bug,
485 forbid variables in match (needs libxml2-2.6.21)</li>
486 <li>improvements: EXSLT dyn:map (Mark Vakoc),</li>
487 <li>documentation: EXSLT date and time functions namespace in man (Jonathan
491 <h3>1.1.14: Apr 02 2005</h3>
493 <li>bug fixes: text node on stylesheet document without a dictionary
494 (William Brack), more checking of XSLT syntax, calling xsltInit()
495 multiple times, mode values interning raised by Mark Vakoc, bug in
496 pattern matching with ancestors, bug in patterna matching with cascading
497 select, xinclude and document() problem, build outside of source tree
499 <li>improvement: added a --nodict mode to xsltproc to check problems for
500 docuemtns without dictionaries</li>
503 <h3>1.1.13: Mar 13 2005</h3>
505 <li>build fixes: 64bits cleanup (William Brack), python 2.4 test (William),
506 LIBXSLT_VERSION_EXTRA on Windows (William), Windows makefiles fixes (Joel
507 Reed), libgcrypt-devel requires for RPM spec.</li>
508 <li>bug fixes: exslt day-of-week-in-month (Sal Paradise), xsl:call-template
509 should not change the current template rule (William Brack), evaluation
510 of global variables (William Brack), RVT's in XPath predicates (William),
511 namespace URI on template names (Mark Vakoc), stat() for Windows patch
512 (Aleksey Gurtovoy), pattern expression fixes (William Brack), out of
513 memory detection misses (William), parserOptions propagation (William),
514 exclude-result-prefixes fix (William), // patten fix (William).</li>
515 <li>extensions: module support (Joel Reed), dictionary based speedups
516 trying to get rid of xmlStrEqual as much as possible.</li>
517 <li>documentation: added Wiki (Joel Reed)</li>
520 <h3>1.1.12: Oct 29 2004</h3>
522 <li>build fixes: warnings removal (William).</li>
523 <li>bug fixes: attribute document pointer fix (Mark Vakoc), exslt date
524 negative periods (William Brack), generated tree structure fixes,
525 namespace lookup fix, use reentrant gmtime_r (William Brack),
526 exslt:funtion namespace fix (William), potential NULL pointer reference
527 (Dennis Dams, William), force string interning on generated
529 <li>documentation: update of the second tutorial (Panagiotis Louridas), add
530 exslt doc in rpm packages, fix the xsltproc man page.</li>
533 <h3>1.1.11: Sep 29 2004</h3>
535 <li>bug fixes: xsl:include problems (William Brack), UTF8 number pattern
536 (William), date-time validation (William), namespace fix (William),
537 various Exslt date fixes (William), error callback fixes, leak with
538 namespaced global variable, attempt to fix a weird problem #153137</li>
539 <li>improvements: exslt:date-sum tests (Derek Poon)</li>
540 <li>documentation: second tutorial by Panagiotis Lourida</li>
543 <h3>1.1.10: Aug 31 2004</h3>
545 <li>build fix: NUL in c file blocking compilation on Solaris, Windows build
546 (Igor Zlatkovic)</li>
547 <li>fix: key initialization problem (William Brack)</li>
548 <li>documentation: fixed missing man page description for --path</li>
551 <h3>1.1.9: Aug 22 2004</h3>
553 <li>build fixes: missing tests (William Brack), Python dependancies, Python
554 on 64bits boxes, --with-crypto flag (Rob Richards),</li>
555 <li>fixes: RVT key handling (William), Python binding (William and Sitsofe
556 Wheeler), key and XPath troubles (William), template priority on imports
557 (William), str:tokenize with empty strings (William), #default namespace
558 alias behaviour (William), doc ordering missing for main document
559 (William), 64bit bug (Andreas Schwab)</li>
560 <li>improvements: EXSLT date:sum added (Joel Reed), hook for document
561 loading for David Hyatt, xsltproc --nodtdattr to avoid defaulting DTD
562 attributes, extend xsltproc --version with CVS stamp (William).</li>
563 <li>Documentation: web page problem reported by Oliver Stoeneberg</li>
566 <h3>1.1.8: July 5 2004</h3>
568 <li>build fixes: Windows runtime options (Oliver Stoeneberg), Windows
569 binary package layout (Igor Zlatkovic), libgcrypt version test and link
571 <li>documentation: fix libxslt namespace name in doc (William)</li>
572 <li>bug fixes: undefined namespace message (William Brack), search engine
573 (William), multiple namespace fixups (William), namespace fix for key
574 evaluation (William), Python memory debug bindings,</li>
575 <li>improvements: crypto extensions for exslt (Joel Reed, William)</li>
578 <h3>1.1.7: May 17 2004</h3>
580 <li>build fix: warning about localtime_r on Solaris</li>
581 <li>bug fix: UTF8 string tokenize (William Brack), subtle memory
582 corruption, linefeed after comment at document level (William),
583 disable-output-escaping problem (William), pattern compilation in deep
584 imported stylesheets (William), namespace extension prefix bug,
585 libxslt.m4 bug (Edward Rudd), namespace lookup for attribute, namespaced
589 <h3>1.1.6: Apr 18 2004</h3>
591 <li>2 bug fixes about keys fixed one by Mark Vakoc</li>
594 <h3>1.1.5: Mar 23 2004</h3>
596 <li>performance: use dictionary lookup for variables</li>
597 <li>remove use of _private from source documents</li>
598 <li>cleanup of "make tests" output</li>
599 <li>bugfixes: AVT in local variables, use localtime_r to avoid thread
600 troubles (William), dictionary handling bug (William), limited number of
601 stubstitutions in AVT (William), tokenize fix for UTF-8 (William),
602 superfluous namespace (William), xsltproc error code on
603 <xsl:message> halt, OpenVMS fix, dictionary reference counting
607 <h3>1.1.4: Feb 23 2004</h3>
609 <li>bugfixes: attributes without doc (Mariano Suárez-Alvarez), problem with
610 Yelp, extension problem</li>
611 <li>display extension modules (Steve Little)</li>
612 <li>Windows compilation patch (Mark Vadoc), Mingw (Mikhail Grushinskiy)</li>
615 <h3>1.1.3: Feb 16 2004</h3>
617 <li>Rewrote the Attribute Value Template code, new XPath compilation
618 interfaces, dictionary reuses for XSLT with potential for serious
619 performance improvements.</li>
620 <li>bug fixes: portability (William Brack), key() in node-set() results
621 (William), comment before doctype (William), math and node-set() problems
622 (William), cdata element and default namespace (William), behaviour on
623 unknown XSLT elements (Stefan Kost), priority of "//foo" patterns
624 (William), xsl:element and xsl:attribute QName check (William), comments
625 with -- (William), attribute namespace (William), check for ?> in PI
627 <li>Documentations: cleanup (John Fleck and William)</li>
628 <li>Python: patch for OS-X (Gianni Ceccarelli), enums export (Stephane
632 <h3>1.1.2: Dec 24 2003</h3>
634 <li>Documentation fixes (John Fleck, William Brack), EXSLT documentation
636 <li>Windows compilation fixes for MSVC and Mingw (Igor Zlatkovic)</li>
637 <li>Bug fixes: exslt:date returning NULL strings (William Brack),
638 namespaces output (William Brack), key and namespace definition problem,
639 passing options down to the document() parser, xsl:number fixes (William
643 <h3>1.1.1: Dec 10 2003</h3>
645 <li>code cleanup (William Brack)</li>
646 <li>Windows: Makefile improvements (Igor Zlatkovic)</li>
647 <li>documentation improvements: William Brack, libexslt man page (Jonathan
649 <li>param in EXSLT functions (Shaun McCance)</li>
650 <li>XSLT debugging improvements (Mark Vakoc)</li>
651 <li>bug fixes: number formatting (Bjorn Reese), exslt:tokenize (William
652 Brack), key selector parsing with | reported by Oleg Paraschenko,
653 xsl:element with computed namespaces (William Brack), xslt:import/include
654 recursion detection (William Brack), exslt:function used in keys (William
655 Brack), bug when CDATA_SECTION are foun in the tree (William Brack),
656 entities handling when using XInclude.</li>
659 <h3>1.1.0: Nov 4 2003</h3>
661 <li>Removed DocBook SGML broken support</li>
662 <li>fix xsl:key to work with PIs</li>
663 <li>Makefile and build improvement (Graham Wilson), build cleanup (William
664 Brack), macro fix (Justin Fletcher), build outside of source tree (Roumen
666 <li>xsltproc option display fix (Alexey Efimov), --load-trace (Crutcher
668 <li>Python: never use stdout for error</li>
669 <li>extension memory error fix (Karl Eichwalder)</li>
670 <li>header path fixes (Steve Ball)</li>
671 <li>added saxon:line-number() to libexslt (Brett Kail)</li>
672 <li>Fix some tortuous template problems when using predicates (William
674 <li>Debugger status patch (Kasimier Buchcik)</li>
675 <li>Use new libxml2-2.6.x APIs for faster processing</li>
676 <li>Make sure xsl:sort is empty</li>
677 <li>Fixed a bug in default processing of attributes</li>
678 <li>Removes the deprecated breakpoint library</li>
679 <li>detect invalid names on templates (William Brack)</li>
680 <li>fix exslt:document (and similar) base handling problem</li>
683 <h3>1.0.33: Sep 12 2003</h3>
685 <p>This is a bugfix only release</p>
687 <li>error message missing argument (William Brack)</li>
688 <li>mode not cascaded in template fallbacks (William Brack)</li>
689 <li>catch redefinition of parameter/variables (William Brack)</li>
690 <li>multiple keys with same namespace name (William Brack)</li>
691 <li>patch for compilation using MingW on Windows (Mikhail Grushinskiy)</li>
692 <li>header export macros for Windows (Igor Zlatkovic)</li>
693 <li>cdata-section-elements handling of namespaced names</li>
694 <li>compilation without libxml2 XPointer support (Mark Vadoc)</li>
695 <li>apply-templates crash (William Brack)</li>
696 <li>bug with imported templates (William Brack)</li>
697 <li>imported attribute-sets merging bug (DocBook) (William Brack)</li>
700 <h3>1.0.32: Aug 9 2003</h3>
702 <li>bugfixes: xsltSaveResultToFile() python binding (Chris Jaeger), EXSLT
703 function (William Brack), RVT for globals (William Brack), EXSLT date
705 <p>speed of large text output, xsl:copy with attributes, strip-space and
706 namespaces prefix, fix for --path xsltproc option, EXST:tokenize (Shaun
707 McCance), EXSLT:seconds (William Brack), sort with multiple keys (William
708 Brack), checking of { and } for attribute value templates (William
711 <li>Python bindings for extension elements (Sean Treadway)</li>
712 <li>EXSLT:split added (Shaun McCance)</li>
713 <li>portability fixes for HP-UX/Solaris/IRIX (William Brack)</li>
717 <h3>1.0.31: Jul 6 2003</h3>
719 <li>bugfixes: xsl:copy on namespace nodes, AVT for xsl:sort order, fix for
720 the debugger (Keith Isdale), output filename limitation, trio.h and
721 triodef.h added (Albert Chin), EXSLT node-set (Peter Breitenlohner),
722 xsltChoose and whitespace (Igor Zlatkovic),
723 <p>stylesheet compilation (Igor Zlatkovic), NaN and sort (William Brack),
724 RVT bug introduced in 1.0.30</p>
726 <li>avoid generating &quot; (fix in libxml2-2.5.8)</li>
727 <li>fix 64bit cleaness problem and compilation troubles introduced in
729 <li>Windows makefile generation (Igor Zlatkovic)</li>
730 <li>HP-UX portability fix</li>
733 <h3>1.0.30: May 4 2003</h3>
735 <li>Fixes and new APIs to handle Result Value Trees and avoid leaks</li>
736 <li>Fixes for: EXSLT math pow() function (Charles Bozeman), global
737 parameter and global variables mismatch, a segfault on pattern
738 compilation errors, namespace copy in xsl:copy-of, python generator
739 problem, OpenVMS trio update, premature call to xsltFreeStackElem (Igor),
740 current node when templates applies to attributes</li>
743 <h3>1.0.29: Apr 1 2003</h3>
745 <li>performance improvements especially for large flat documents</li>
746 <li>bug fixes: Result Value Tree handling, XML IDs, keys(), extra namespace
747 declarations with xsl:elements.</li>
748 <li>portability: python and trio fixes (Albert Chin), python on Solaris
752 <h3>1.0.28: Mar 24 2003</h3>
754 <li>fixed node() in patterns semantic.</li>
755 <li>fixed a memory access problem in format-number()</li>
756 <li>fixed stack overflow in recursive global variable or params</li>
757 <li>cleaned up Result Value Tree handling, and fixed a couple of old bugs
761 <h3>1.0.27: Feb 24 2003</h3>
763 <li>bug fixes: spurious xmlns:nsX="" generation, serialization bug (in
764 libxml2), a namespace copy problem, errors in the RPM spec prereqs</li>
765 <li>Windows path canonicalization and document cache fix (Igor)</li>
768 <h3>1.0.26: Feb 10 2003</h3>
770 <li>Fixed 3 serious bugs in document() and stylesheet compilation which
771 could lead to a crash</li>
774 <h3>1.0.25: Feb 5 2003</h3>
776 <li>Bug fix: double-free for standalone stylesheets introduced in 1.0.24, C
777 syntax pbm, 3 bugs reported by Eric van der Vlist</li>
778 <li>Some XPath and XInclude related problems were actually fixed in
780 <li>Documentation: emphasize taht --docbook is not for XML docs.</li>
783 <h3>1.0.24: Jan 14 2003</h3>
785 <li>bug fixes: imported global varables, python bindings (Stéphane Bidoul),
786 EXSLT memory leak (Charles Bozeman), namespace generation on
787 xsl:attribute, space handling with imports (Daniel Stodden),
788 extension-element-prefixes (Josh Parsons), comments within xsl:text (Matt
789 Sergeant), superfluous xmlns generation, XInclude related bug for
790 numbering, EXSLT strings (Alexey Efimov), attribute-sets computation on
791 imports, extension module init and shutdown callbacks not called</li>
792 <li>HP-UX portability (Alexey Efimov), Windows makefiles (Igor and Stephane
793 Bidoul), VMS makefile updates (Craig A. Berry)</li>
794 <li>adds xsltGetProfileInformation() (Michael Rothwell)</li>
795 <li>fix the API generation scripts</li>
796 <li>API to provide the sorting routines (Richard Jinks)</li>
797 <li>added XML description of the EXSLT API</li>
798 <li>added ESXLT URI (un)escaping (Jörg Walter)</li>
799 <li>Some memory leaks have been found and fixed</li>
800 <li>document() now support fragment identifiers in URIs</li>
803 <h3>1.0.23: Nov 17 2002</h3>
805 <li>Windows build cleanup (Igor)</li>
806 <li>Unix build and RPM packaging cleanup</li>
807 <li>Improvement of the python bindings: extension functions and activating
809 <li>various bug fixes: number formatting, portability for bounded string
810 functions, CData nodes, key(), @*[...] patterns</li>
811 <li>Documentation improvements (John Fleck)</li>
812 <li>added libxslt.m4 (Thomas Schraitle)</li>
815 <h3>1.0.22: Oct 18 2002</h3>
817 <li>Updates on the Windows Makefiles</li>
818 <li>Added a security module, and a related set of new options to
820 <li>Allowed per transformation error handler.</li>
821 <li>Fixed a few bugs: node() semantic, URI escaping, media-type, attribute
825 <h3>1.0.21: Sep 26 2002</h3>
827 <li>Bug fixes: match="node()", date:difference() (Igor and Charlie
828 Bozeman), disable-output-escaping</li>
829 <li>Python bindings: style.saveResultToString() from Ralf Mattes</li>
830 <li>Logos from Marc Liyanage</li>
831 <li>Mem leak fix from Nathan Myers</li>
832 <li>Makefile: DESTDIR fix from Christophe Merlet, AMD x86_64 (Mandrake),
833 Windows (Igor), Python detection</li>
834 <li>Documentation improvements: John Fleck</li>
837 <h3>1.0.20: Aug 23 2002</h3>
839 <li>Windows makefile updates (Igor) and x86-64 (Frederic Crozat)</li>
840 <li>fixed HTML meta tag saving for Mac/IE users</li>
841 <li>possible leak patches from Nathan Myers</li>
842 <li>try to handle document('') as best as possible depending in the
844 <li>Fixed the DocBook stylesheets handling problem</li>
845 <li>Fixed a few XSLT reported errors</li>
848 <h3>1.0.19: July 6 2002</h3>
850 <li>EXSLT: dynamic functions and date support bug fixes (Mark Vakoc)</li>
851 <li>xsl:number fix: Richard Jinks</li>
852 <li>xsl:format-numbers fix: Ken Neighbors</li>
853 <li>document('') fix: bug pointed by Eric van der Vlist</li>
854 <li>xsl:message with terminate="yes" fixes: William Brack</li>
855 <li>xsl:sort order support added: Ken Neighbors</li>
856 <li>a few other bug fixes, some of them requiring the latest version of
860 <h3>1.0.18: May 27 2002</h3>
862 <li>a number of bug fixes: attributes, extra namespace declarations
863 (DocBook), xsl:include crash (Igor), documentation (Christian Cornelssen,
864 Charles Bozeman and Geert Kloosterman), element-available (Richard
866 <li>xsltproc can now list teh registered extensions thanks to Mark
868 <li>there is a new API to save directly to a string
869 xsltSaveResultToString() by Morus Walter</li>
870 <li>specific error registration function for the python API</li>
873 <h3>1.0.17: April 29 2002</h3>
875 <li>cleanup in code, XSLT debugger support and Makefiles for Windows by
877 <li>a C++ portability fix by Mark Vakoc</li>
878 <li>EXSLT date improvement and regression tests by Charles Bozeman</li>
879 <li>attempt to fix a bug in xsltProcessUserParamInternal</li>
882 <h3>1.0.16: April 15 2002</h3>
884 <li>Bug fixes: strip-space, URL in HTML output, error when xsltproc can't
886 <li>portability fixes: OSF/1, IEEE on alphas, Windows, Python bindings</li>
889 <h3>1.0.15: Mar 25 2002</h3>
891 <li>Bugfixes: XPath, python Makefile, recursive attribute sets, @foo[..]
893 <li>Debug of memory alocation with valgind</li>
894 <li>serious profiling leading to significant improvement for DocBook
896 <li>revamp of the Windows build</li>
899 <h3>1.0.14: Mar 18 2002</h3>
901 <li>Improvement in the XPath engine (libxml2-2.4.18)</li>
902 <li>Nasty bug fix related to exslt:node-set</li>
903 <li>Fixed the python Makefiles, cleanup of doc comments, Windows
904 portability fixes</li>
907 <h3>1.0.13: Mar 8 2002</h3>
909 <li>a number of bug fixes including "namespace node have no parents"</li>
910 <li>Improvement of the Python bindings</li>
911 <li>Charles Bozeman provided fixes and regression tests for exslt date
915 <h3>1.0.12: Feb 11 2002</h3>
917 <li>Fixed the makefiles especially the python module ones</li>
918 <li>half a dozen bugs fixes including 2 old ones</li>
921 <h3>1.0.11: Feb 8 2002</h3>
923 <li>Change of Licence to the <a
924 href="http://www.opensource.org/licenses/mit-license.html">MIT
926 <li>Added a beta version of the Python bindings, including support to
927 extend the engine with functions written in Python</li>
928 <li>A number of bug fixes</li>
929 <li>Charlie Bozeman provided more EXSLT functions</li>
930 <li>Portability fixes</li>
933 <h3>1.0.10: Jan 14 2002</h3>
935 <li>Windows fixes for Win32 from Igor</li>
936 <li>Fixed the Solaris compilation trouble (Albert)</li>
937 <li>Documentation changes and updates: John Fleck</li>
938 <li>Added a stringparam option to avoid escaping hell at the shell
940 <li>A few bug fixes</li>
943 <h3>1.0.9: Dec 7 2001</h3>
945 <li>Makefile patches from Peter Williams</li>
946 <li>attempt to fix the compilation problem associated to prelinking</li>
947 <li>obsoleted libxsltbreakpoint now deprecated and frozen to 1.0.8 API</li>
948 <li>xsltproc return codes are now significant, John Fleck updated the
950 <li>patch to allow as much as 40 steps in patterns (Marc Tardif), should be
951 made dynamic really</li>
952 <li>fixed a bug raised by Nik Clayton when using doctypes with HTML
954 <li>patches from Keith Isdale to interface with xsltdebugger</li>
957 <h3>1.0.8: Nov 26 2001</h3>
959 <li>fixed an annoying header problem, removed a few bugs and some code
961 <li>patches for Windows and update of Windows Makefiles by Igor</li>
962 <li>OpenVMS port instructions from John A Fotheringham</li>
963 <li>fixed some Makefiles annoyance and libraries prelinking
967 <h3>1.0.7: Nov 10 2001</h3>
969 <li>remove a compilation problem with LIBXSLT_PUBLIC</li>
970 <li>Finishing the integration steps for Keith Isdale debugger</li>
971 <li>fixes the handling of indent="no" on HTML output</li>
972 <li>fixes on the configure script and RPM spec file</li>
975 <h3>1.0.6: Oct 30 2001</h3>
977 <li>bug fixes on number formatting (Thomas), date/time functions (Bruce
979 <li>update of the Windows Makefiles (Igor)</li>
980 <li>fixed DOCTYPE generation rules for HTML output (me)</li>
983 <h3>1.0.5: Oct 10 2001</h3>
985 <li>some portability fixes, including Windows makefile updates from
987 <li>fixed a dozen bugs on XSLT and EXSLT (me and Thomas Broyer)</li>
988 <li>support for Saxon's evaluate and expressions extensions added (initial
989 contribution from Darren Graves)</li>
990 <li>better handling of XPath evaluation errors</li>
993 <h3>1.0.4: Sep 12 2001</h3>
995 <li>Documentation updates from John fleck</li>
996 <li>bug fixes (DocBook FO generation should be fixed) and portability
998 <li>Thomas Broyer improved the existing EXSLT support and added String,
999 Time and Date core functions support</li>
1002 <h3>1.0.3: Aug 23 2001</h3>
1004 <li>XML Catalog support see the doc</li>
1005 <li>New NaN/Infinity floating point code</li>
1006 <li>A few bug fixes</li>
1009 <h3>1.0.2: Aug 15 2001</h3>
1011 <li>lot of bug fixes, increased the testsuite</li>
1012 <li>a large chunk of EXSLT is implemented</li>
1013 <li>improvements on the extension framework</li>
1014 <li>documentation improvements</li>
1015 <li>Windows MSC projects files should be up-to-date</li>
1016 <li>handle attributes inherited from the DTD by default</li>
1019 <h3>1.0.1: July 24 2001</h3>
1021 <li>initial EXSLT framework</li>
1022 <li>better error reporting</li>
1023 <li>fixed the profiler on Windows</li>
1027 <h3>1.0.0: July 10 2001</h3>
1029 <li>a lot of cleanup, a lot of regression tests added or fixed</li>
1030 <li>added a documentation for <a href="extensions.html">writing
1032 <li>fixed some variable evaluation problems (with William)</li>
1033 <li>added profiling of stylesheet execution accessible as the xsltproc
1034 --profile option</li>
1035 <li>fixed element-available() and the implementation of the various
1036 chunking methods present, Norm Walsh provided a lot of feedback</li>
1037 <li>exclude-result-prefixes and namespaces output should now work as
1039 <li>added support of embedded stylesheet as described in section 2.7 of the
1043 <h3>0.14.0: July 5 2001</h3>
1045 <li>lot of bug fixes, and code cleanup</li>
1046 <li>completion of the little XSLT-1.0 features left unimplemented</li>
1047 <li>Added and implemented the extension API suggested by Thomas Broyer</li>
1048 <li>the Windows MSC environment should be complete</li>
1049 <li>tested and optimized with a really large document (DocBook Definitive
1050 Guide) libxml/libxslt should really be faster on serious workloads</li>
1053 <h3>0.13.0: June 26 2001</h3>
1055 <li>lots of cleanups</li>
1056 <li>fixed a C++ compilation problem</li>
1057 <li>couple of fixes to xsltSaveTo()</li>
1058 <li>try to fix Docbook-xslt-1.4 and chunking, updated the regression test
1060 <li>fixed pattern compilation and priorities problems</li>
1061 <li>Patches for Windows and MSC project mostly contributed by Yon Derek</li>
1062 <li>update to the Tutorial by John Fleck</li>
1063 <li>William fixed bugs in templates and for-each functions</li>
1064 <li>added a new interface xsltRunStylesheet() for a more flexible output
1065 (incomplete), added -o option to xsltproc</li>
1068 <h3>0.12.0: June 18 2001</h3>
1070 <li>fixed a dozen of bugs reported</li>
1071 <li>HTML generation should be quite better (requires libxml-2.3.11 upgrade
1073 <li>William fixed some problems with document()</li>
1074 <li>Fix namespace nodes selection and copy (requires libxml-2.3.11 upgrade
1076 <li>John Fleck added a<a href="tutorial/libxslttutorial.html">
1078 <li>Fixes for namespace handling when evaluating variables</li>
1079 <li>XInclude global flag added to process XInclude on document() if
1081 <li>made xsltproc --version more detailed</li>
1084 <h3>0.11.0: June 1 2001</h3>
1086 <p>Mostly a bug fix release.</p>
1088 <li>integration of catalogs from xsltproc</li>
1089 <li>added --version to xsltproc for bug reporting</li>
1090 <li>fixed errors when handling ID in external parsed entities</li>
1091 <li>document() should hopefully work correctly but ...</li>
1092 <li>fixed bug with PI and comments processing</li>
1093 <li>William fixed the XPath string functions when using unicode</li>
1096 <h3>0.10.0: May 19 2001</h3>
1098 <li>cleanups to make stylesheet read-only (not 100% complete)</li>
1099 <li>fixed URI resolution in document()</li>
1100 <li>force all XPath expression to be compiled at stylesheet parsing time,
1101 even if unused ...</li>
1102 <li>Fixed HTML default output detection</li>
1103 <li>Fixed double attribute generation #54446</li>
1104 <li>Fixed {{ handling in attributes #54451</li>
1105 <li>More tests and speedups for DocBook document transformations</li>
1106 <li>Fixed a really bad race like bug in xsltCopyTreeList()</li>
1107 <li>added a documentation on the libxslt internals</li>
1108 <li>William Brack and Bjorn Reese improved format-number()</li>
1109 <li>Fixed multiple sort, it should really work now</li>
1110 <li>added a --docbook option for SGML DocBook input (hackish)</li>
1111 <li>a number of other bug fixes and regression test added as people were
1112 submitting them</li>
1115 <h3>0.9.0: May 3 2001</h3>
1117 <li>lot of various bugfixes, extended the regression suite</li>
1118 <li>xsltproc should work with multiple params</li>
1119 <li>added an option to use xsltproc with HTML input</li>
1120 <li>improved the stylesheet compilation, processing of complex stylesheets
1121 should be faster</li>
1122 <li>using the same stylesheet for concurrent processing on multithreaded
1123 programs should work now</li>
1124 <li>fixed another batch of namespace handling problems</li>
1125 <li>Implemented multiple level of sorting</li>
1128 <h3>0.8.0: Apr 22 2001</h3>
1130 <li>fixed ansidecl.h problem</li>
1131 <li>fixed unparsed-entity-uri() and generate-id()</li>
1132 <li>sort semantic fixes and priority prob from William M. Brack</li>
1133 <li>fixed namespace handling problems in XPath expression computations
1134 (requires libxml-2.3.7)</li>
1135 <li>fixes to current() and key()</li>
1136 <li>other, smaller fixes, lots of testing with N Walsh DocBook HTML
1140 <h3>0.7.0: Apr 10 2001</h3>
1142 <li>cleanup using stricter compiler flags</li>
1143 <li>command line parameter passing</li>
1144 <li>fix to xsltApplyTemplates from William M. Brack</li>
1145 <li>added the XSLTMark in the regression tests as well as document()</li>
1148 <h3>0.6.0: Mar 22 2001</h3>
1150 <li>another beta</li>
1151 <li>requires 2.3.5, which provide XPath expression compilation support</li>
1152 <li>document() extension should function properly</li>
1153 <li>fixed a number or reported bugs</li>
1156 <h3>0.5.0: Mar 10 2001</h3>
1159 <li>some optimization work, for the moment 2 XSLT transform cannot use the
1160 same stylesheet at the same time (to be fixed)</li>
1161 <li>fixed problems with handling of tree results</li>
1162 <li>fixed a reported strip-spaces problem</li>
1163 <li>added more reported/fixed bugs to the test suite</li>
1164 <li>incorporated William M. Brack fix for imports and global variables as
1165 well as patch for with-param support in apply-templates</li>
1166 <li>a bug fix on for-each</li>
1169 <h3>0.4.0: Mar 1 2001</h3>
1171 <li>fourth beta test, released at the same time of libxml2-2.3.3</li>
1173 <li>some optimization</li>
1174 <li>started implement extension support, not finished</li>
1175 <li>implemented but not tested multiple file output</li>
1178 <h3>0.3.0: Feb 24 2001</h3>
1180 <li>third beta test, released at the same time of libxml2-2.3.2</li>
1181 <li>lot of bug fixes</li>
1182 <li>some optimization</li>
1183 <li>added DocBook XSL based testsuite</li>
1186 <h3>0.2.0: Feb 15 2001</h3>
1188 <li>second beta version, released at the same time as libxml2-2.3.1</li>
1189 <li>getting close to feature completion, lot of bug fixes, some in the HTML
1190 and XPath support of libxml</li>
1191 <li>start becoming usable for real work. This version can now regenerate
1192 the XML 2e HTML from the original XML sources and the associated
1194 href="http://www.w3.org/TR/REC-xml#b4d250b6c21">section I of the XML
1196 <li>Still misses extension element/function/prefixes support. Support of
1197 key() and document() is not complete</li>
1200 <h3>0.1.0: Feb 8 2001</h3>
1202 <li>first beta version, released at the same time as libxml2-2.3.0</li>
1203 <li>lots of bug fixes, first "testing" version, but incomplete</li>
1206 <h3>0.0.1: Jan 25 2001</h3>
1208 <li>first alpha version released at the same time as libxml2-2.2.12</li>
1209 <li>Framework in place, should work on simple examples, but far from being
1210 feature complete</li>
1213 <h2><a name="xsltproc">The xsltproc tool</a></h2>
1215 <p>This program is the simplest way to use libxslt: from the command line. It
1216 is also used for doing the regression tests of the library.</p>
1218 <p>It takes as first argument the path or URL to an XSLT stylesheet, the next
1219 arguments are filenames or URIs of the inputs to be processed. The output of
1220 the processing is redirected on the standard output. There is actually a few
1221 more options available:</p>
1222 <pre>orchis:~ -> xsltproc
1223 Usage: xsltproc [options] stylesheet file [file ...]
1225 --version or -V: show the version of libxml and libxslt used
1226 --verbose or -v: show logs of what's happening
1227 --output file or -o file: save to a given file
1228 --timing: display the time used
1229 --repeat: run the transformation 20 times
1230 --debug: dump the tree of the result instead
1231 --novalid: skip the Dtd loading phase
1232 --noout: do not dump the result
1233 --maxdepth val : increase the maximum depth
1234 --html: the input document is(are) an HTML file(s)
1235 --docbook: the input document is SGML docbook
1236 --param name value : pass a (parameter,value) pair
1237 --nonet refuse to fetch DTDs or entities over network
1238 --warnnet warn against fetching over the network
1239 --catalogs : use the catalogs from $SGML_CATALOG_FILES
1240 --xinclude : do XInclude processing on document input
1241 --profile or --norman : dump profiling information
1242 orchis:~ -></pre>
1244 <h2><a name="DocBook">DocBook</a></h2>
1246 <p><img src="duck.png" align="right" alt="The duck picture"></p>
1248 <p><a href="http://www.oasis-open.org/committees/docbook/">DocBook</a> is an
1249 XML/SGML vocabulary particularly well suited to books and papers about
1250 computer hardware and software.</p>
1252 <p>xsltproc and libxslt are not specifically dependant on DocBook, but since
1253 a lot of people use xsltproc and libxml2 for DocBook formatting, here are a
1254 few pointers and information which may be helpful:</p>
1256 <li>The <a href="http://www.oasis-open.org/committees/docbook/">DocBook
1257 homepage at Oasis</a> you should find pointers there on all the lastest
1258 versions of the DTDs and XSLT stylesheets</li>
1259 <li><a href="http://www.docbook.org/">DocBook: The Definitive Guide</a> is
1260 the official reference documentation for DocBook.</li>
1262 href="https://sourceforge.net/docman/index.php?group_id=21935">DocBook
1263 Open Repository</a> contains a lot of information about DocBook</li>
1264 <li>Bob Stayton provides a <a href="http://www.sagehill.net/">lot of
1265 resources</a> and consulting services around DocBook.</li>
1266 <li>Here is a <a href="/buildDocBookCatalog">shell script</a> to generate
1267 XML Catalogs for DocBook 4.1.2 . If it can write to the /etc/xml/
1268 directory, it will set-up /etc/xml/catalog and /etc/xml/docbook based on
1269 the resources found on the system. Otherwise it will just create
1270 ~/xmlcatalog and ~/dbkxmlcatalog and doing:
1271 <p><code>export XMLCATALOG=$HOME/xmlcatalog</code></p>
1272 <p>should allow to process DocBook documentations without requiring
1273 network accesses for the DTd or stylesheets</p>
1275 <li>I have uploaded <a href="ftp://xmlsoft.org/libxml2/test/dbk412catalog.tar.gz">a
1276 small tarball</a> containing XML Catalogs for DocBook 4.1.2 which seems
1277 to work fine for me too</li>
1278 <li>Informations on installing a <a
1279 href="http://wiki.docbook.org/topic/CygwinPackages">Windows
1280 DocBook processing setup</a> based on Cygwin (using the binaries from the
1281 official Windows port should be possible too)</li>
1282 <li>Alexander Kirillov's page on <a
1283 href="http://www.math.sunysb.edu/~kirillov/dbxml/">Using DocBook XML
1284 4.1.2</a> (RPM packages)</li>
1285 <li>Tim Waugh's <a href="http://cyberelk.net/tim/xmlto/">xmlto front-end
1286 conversion script</a></li>
1287 <li>Linux Documentation Project <a
1288 href="http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/">
1289 DocBook-Install-mini-HOWTO</a></li>
1290 <li>ScrollKeeper the open documentation cataloging project has a <a
1291 href="http://scrollkeeper.sourceforge.net/docbook.shtml">DocBook
1293 <li>Dan York presentation on <a
1294 href="http://www.lodestar2.com/people/dyork/talks/2001/xugo/docbook/index.html">Publishing
1295 using DocBook XML</a></li>
1298 <p>Do not use the --docbook option of xsltproc to process XML DocBook
1299 documents, this option is only intended to provide some (limited) support of
1300 the SGML version of DocBook.</p>
1302 <p>Points which are not DocBook specific but still worth mentionning
1305 <li>if you think DocBook processing time is too slow, make sure you have
1306 XML Catalogs pointing to a local installation of the DTD of DocBook.
1307 Check the <a href="http://xmlsoft.org/catalog.html">XML Catalog page</a>
1308 to understand more on this subject.</li>
1309 <li>before processing a new document, use the command
1310 <p><code>xmllint --valid --noout path_to_document</code></p>
1311 <p>to make sure that your input is valid DocBook. And fixes the errors
1312 before processing further. Note that XSLT processing may work correctly
1313 with some forms of validity errors left, but in general it can give
1314 troubles on output.</p>
1318 <h2><a name="API">The programming API</a></h2>
1320 <p>Okay this section is clearly incomplete. But integrating libxslt into your
1321 application should be relatively easy. First check the few steps described
1322 below, then for more detailed information, look at the<a
1323 href="html/libxslt-lib.html"> generated pages</a> for the API and the source
1324 of libxslt/xsltproc.c and the <a
1325 href="tutorial/libxslttutorial.html">tutorial</a>.</p>
1327 <p>Basically doing an XSLT transformation can be done in a few steps:</p>
1329 <li>configure the parser for XSLT:
1330 <p>xmlSubstituteEntitiesDefault(1);</p>
1331 <p>xmlLoadExtDtdDefaultValue = 1;</p>
1333 <li>parse the stylesheet with xsltParseStylesheetFile()</li>
1334 <li>parse the document with xmlParseFile()</li>
1335 <li>apply the stylesheet using xsltApplyStylesheet()</li>
1336 <li>save the result using xsltSaveResultToFile() if needed set
1337 xmlIndentTreeOutput to 1</li>
1340 <p>Steps 2,3, and 5 will probably need to be changed depending on you
1341 processing needs and environment for example if reading/saving from/to
1342 memory, or if you want to apply XInclude processing to the stylesheet or
1343 input documents.</p>
1345 <h2><a name="Python">Python and bindings</a></h2>
1347 <p>There is a number of language bindings and wrappers available for libxml2,
1348 the list below is not exhaustive. Please contact the <a
1349 href="http://mail.gnome.org/mailman/listinfo/xml-bindings">xml-bindings@gnome.org</a>
1350 (<a href="http://mail.gnome.org/archives/xml-bindings/">archives</a>) in
1351 order to get updates to this list or to discuss the specific topic of libxml2
1352 or libxslt wrappers or bindings:</p>
1355 href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">Matt
1356 Sergeant</a> developped <a href="http://axkit.org/download/">XML::LibXML
1357 and XML::LibXSLT</a>, Perl wrappers for libxml2/libxslt as part of the <a
1358 href="http://axkit.com/">AxKit XML application server</a></li>
1359 <li><a href="mailto:dkuhlman@cutter.rexx.com">Dave Kuhlman</a> provides and
1360 earlier version of the libxml/libxslt <a
1361 href="http://www.rexx.com/~dkuhlman">wrappers for Python</a></li>
1362 <li>Petr Kozelka provides <a
1363 href="http://sourceforge.net/projects/libxml2-pas">Pascal units to glue
1364 libxml2</a> with Kylix, Delphi and other Pascal compilers</li>
1365 <li>Wai-Sun "Squidster" Chia provides <a
1366 href="http://www.rubycolor.org/arc/redist/">bindings for Ruby</a> and
1367 libxml2 bindings are also available in Ruby through the <a
1368 href="http://libgdome-ruby.berlios.de/">libgdome-ruby</a> module
1369 maintained by Tobias Peters.</li>
1370 <li>Steve Ball and contributors maintains <a
1371 href="http://tclxml.sourceforge.net/">libxml2 and libxslt bindings for
1373 <li><a href="mailto:xmlwrapp@pmade.org">Peter Jones</a> maintains C++
1374 bindings for libxslt within <a
1375 href="http://pmade.org/pjones/software/xmlwrapp/">xmlwrapp</a></li>
1376 <li><a href="phillim2@comcast.net">Mike Phillips</a> provides a module
1377 using <a href="http://siasl.dyndns.org/projects/projects.html">libxslt
1379 <li><a href="http://savannah.gnu.org/projects/classpathx/">LibxmlJ</a> is
1380 an effort to create a 100% JAXP-compatible Java wrapper for libxml2 and
1381 libxslt as part of GNU ClasspathX project.</li>
1382 <li>Patrick McPhee provides Rexx bindings fof libxml2 and libxslt, look for
1383 <a href="http://www.interlog.com/~ptjm/software.html">RexxXML</a>.</li>
1385 href="http://www.satimage.fr/software/en/xml_suite.html">Satimage</a>
1387 href="http://www.satimage.fr/software/en/downloads_osaxen.html">XMLLib
1388 osax</a>. This is an osax for Mac OS X with a set of commands to
1389 implement in AppleScript the XML DOM, XPATH and XSLT.</li>
1392 <p>The libxslt Python module depends on the <a
1393 href="http://xmlsoft.org/python.html">libxml2 Python</a> module.</p>
1395 <p>The distribution includes a set of Python bindings, which are guaranteed to
1396 be maintained as part of the library in the future, though the Python
1397 interface have not yet reached the completeness of the C API.</p>
1399 <p><a href="mailto:stephane.bidoul@softwareag.com">Stéphane Bidoul</a>
1400 maintains <a href="http://users.skynet.be/sbi/libxml-python/">a Windows port
1401 of the Python bindings</a>.</p>
1403 <p>Note to people interested in building bindings, the API is formalized as
1404 <a href="libxslt-api.xml">an XML API description file</a> which allows to
1405 automate a large part of the Python bindings, this includes function
1406 descriptions, enums, structures, typedefs, etc... The Python script used to
1407 build the bindings is python/generator.py in the source distribution.</p>
1409 <p>To install the Python bindings there are 2 options:</p>
1411 <li>If you use an RPM based distribution, simply install the <a
1412 href="http://rpmfind.net/linux/rpm2html/search.php?query=libxml2-python">libxml2-python
1414 href="http://rpmfind.net/linux/rpm2html/search.php?query=libxslt-python">libxslt-python
1416 <li>Otherwise use the <a href="ftp://xmlsoft.org/libxml2/python/">libxml2-python
1417 module distribution</a> corresponding to your installed version of
1418 libxml2 and libxslt. Note that to install it you will need both libxml2
1419 and libxslt installed and run "python setup.py build install" in the
1423 <p>The distribution includes a set of examples and regression tests for the
1424 python bindings in the <code>python/tests</code> directory. Here are some
1425 excepts from those tests:</p>
1429 <p>This is a basic test of XSLT interfaces: loading a stylesheet and a
1430 document, transforming the document and saving the result.</p>
1434 styledoc = libxml2.parseFile("test.xsl")
1435 style = libxslt.parseStylesheetDoc(styledoc)
1436 doc = libxml2.parseFile("test.xml")
1437 result = style.applyStylesheet(doc, None)
1438 style.saveResultToFilename("foo", result, 0)
1439 style.freeStylesheet()
1441 result.freeDoc()</pre>
1443 <p>The Python module is called libxslt, you will also need the libxml2 module
1444 for the operations on XML trees. Let's have a look at the objects manipulated
1445 in that example and how is the processing done:</p>
1447 <li><code>styledoc</code> : is a libxml2 document tree. It is obtained by
1448 parsing the XML file "test.xsl" containing the stylesheet.</li>
1449 <li><code>style</code> : this is a precompiled stylesheet ready to be used
1450 by the following transformations (note the plural form, multiple
1451 transformations can resuse the same stylesheet).</li>
1452 <li><code>doc</code> : this is the document to apply the transformation to.
1453 In this case it is simply generated by parsing it from a file but any
1454 other processing is possible as long as one get a libxml2 Doc. Note that
1455 HTML tree are suitable for XSLT processing in libxslt. This is actually
1456 how this page is generated !</li>
1457 <li><code>result</code> : this is a document generated by applying the
1458 stylesheet to the document. Note that some of the stylesheet information
1459 may be related to the serialization of that document and as in this
1460 example a specific saveResultToFilename() method of the stylesheet should
1461 be used to save it to a file (in that case to "foo").</li>
1464 <p>Also note the need to explicitely deallocate documents with freeDoc()
1465 except for the stylesheet document which is freed when its compiled form is
1466 garbage collected.</p>
1468 <h3>extfunc.py:</h3>
1470 <p>This one is a far more complex test. It shows how to modify the behaviour
1471 of an XSLT transformation by passing parameters and how to extend the XSLT
1472 engine with functions defined in python:</p>
1482 # Small check to verify the context is correcly accessed
1485 pctxt = libxslt.xpathParserContext(_obj=ctx)
1486 ctxt = pctxt.context()
1487 tctxt = ctxt.transformContext()
1488 nodeName = tctxt.insertNode().name
1492 return string.upper(str)
1494 libxslt.registerExtModuleFunction("foo", "http://example.com/foo", f)</pre>
1496 <p>This code defines and register an extension function. Note that the
1497 function can be bound to any name (foo) and how the binding is also
1498 associated to a namespace name "http://example.com/foo". From an XSLT point
1499 of view the function just returns an upper case version of the string passed
1500 as a parameter. But the first part of the function also read some contextual
1501 information from the current XSLT processing environement, in that case it
1502 looks for the current insertion node in the resulting output (either the
1503 resulting document or the Result Value Tree being generated), and saves it to
1504 a global variable for checking that the access actually worked.</p>
1506 <p>For more information on the xpathParserContext and transformContext
1507 objects check the <a href="internals.html">libray internals description</a>.
1508 The pctxt is actually an object from a class derived from the
1509 libxml2.xpathParserContext() with just a couple more properties including the
1510 possibility to look up the XSLT transformation context from the XPath
1512 <pre>styledoc = libxml2.parseDoc("""
1513 <xsl:stylesheet version='1.0'
1514 xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
1515 xmlns:foo='http://example.com/foo'
1516 xsl:exclude-result-prefixes='foo'>
1518 <xsl:param name='bar'>failure</xsl:param>
1519 <xsl:template match='/'>
1520 <article><xsl:value-of select='foo:foo($bar)'/></article>
1521 </xsl:template>
1522 </xsl:stylesheet>
1525 <p>Here is a simple example of how to read an XML document from a python
1526 string with libxml2. Note how this stylesheet:</p>
1528 <li>Uses a global parameter <code>bar</code></li>
1529 <li>Reference the extension function f</li>
1530 <li>how the Namespace name "http://example.com/foo" has to be bound to a
1532 <li>how that prefix is excluded from the output</li>
1533 <li>how the function is called from the select</li>
1535 <pre>style = libxslt.parseStylesheetDoc(styledoc)
1536 doc = libxml2.parseDoc("<doc/>")
1537 result = style.applyStylesheet(doc, { "bar": "'success'" })
1538 style.freeStylesheet()
1541 <p>that part is identical, to the basic example except that the
1542 transformation is passed a dictionary of parameters. Note that the string
1543 passed "success" had to be quoted, otherwise it is interpreted as an XPath
1544 query for the childs of root named "success".</p>
1545 <pre>root = result.children
1546 if root.name != "article":
1547 print "Unexpected root node name"
1549 if root.content != "SUCCESS":
1550 print "Unexpected root node content, extension function failed"
1552 if nodeName != 'article':
1553 print "The function callback failed to access its context"
1556 result.freeDoc()</pre>
1558 <p>That part just verifies that the transformation worked, that the parameter
1559 got properly passed to the engine, that the function f() got called and that
1560 it properly accessed the context to find the name of the insertion node.</p>
1562 <h3>pyxsltproc.py:</h3>
1564 <p>this module is a bit too long to be described there but it is basically a
1565 rewrite of the xsltproc command line interface of libxslt in Python. It
1566 provides nearly all the functionalities of xsltproc and can be used as a base
1567 module to write Python customized XSLT processors. One of the thing to notice
1569 <pre>libxml2.lineNumbersDefault(1)
1570 libxml2.substituteEntitiesDefault(1)</pre>
1572 <p>those two calls in the main() function are needed to force the libxml2
1573 processor to generate DOM trees compliant with the XPath data model.</p>
1575 <h2><a name="Internals">Library internals</a></h2>
1577 <h3>Table of contents</h3>
1579 <li><a href="internals.html#Introducti">Introduction</a></li>
1580 <li><a href="internals.html#Basics">Basics</a></li>
1581 <li><a href="internals.html#Keep">Keep it simple stupid</a></li>
1582 <li><a href="internals.html#libxml">The libxml nodes</a></li>
1583 <li><a href="internals.html#XSLT">The XSLT processing steps</a></li>
1584 <li><a href="internals.html#XSLT1">The XSLT stylesheet compilation</a></li>
1585 <li><a href="internals.html#XSLT2">The XSLT template compilation</a></li>
1586 <li><a href="internals.html#processing">The processing itself</a></li>
1587 <li><a href="internals.html#XPath">XPath expressions compilation</a></li>
1588 <li><a href="internals.html#XPath1">XPath interpretation</a></li>
1589 <li><a href="internals.html#Descriptio">Description of XPath
1591 <li><a href="internals.html#XPath3">XPath functions</a></li>
1592 <li><a href="internals.html#stack">The variables stack frame</a></li>
1593 <li><a href="internals.html#Extension">Extension support</a></li>
1594 <li><a href="internals.html#Futher">Further reading</a></li>
1595 <li><a href="internals.html#TODOs">TODOs</a></li>
1598 <h3><a name="Introducti2">Introduction</a></h3>
1600 <p>This document describes the processing of <a
1601 href="http://xmlsoft.org/XSLT/">libxslt</a>, the <a
1602 href="http://www.w3.org/TR/xslt">XSLT</a> C library developed for the <a
1603 href="http://www.gnome.org/">GNOME</a> project.</p>
1605 <p>Note: this documentation is by definition incomplete and I am not good at
1606 spelling, grammar, so patches and suggestions are <a
1607 href="mailto:veillard@redhat.com">really welcome</a>.</p>
1609 <h3><a name="Basics1">Basics</a></h3>
1611 <p>XSLT is a transformation language. It takes an input document and a
1612 stylesheet document and generates an output document:</p>
1614 <p align="center"><img src="processing.gif"
1615 alt="the XSLT processing model"></p>
1617 <p>Libxslt is written in C. It relies on <a
1618 href="http://www.xmlsoft.org/">libxml</a>, the XML C library for GNOME, for
1619 the following operations:</p>
1621 <li>parsing files</li>
1622 <li>building the in-memory DOM structure associated with the documents
1624 <li>the XPath implementation</li>
1625 <li>serializing back the result document to XML and HTML. (Text is handled
1629 <h3><a name="Keep1">Keep it simple stupid</a></h3>
1631 <p>Libxslt is not very specialized. It is built under the assumption that all
1632 nodes from the source and output document can fit in the virtual memory of
1633 the system. There is a big trade-off there. It is fine for reasonably sized
1634 documents but may not be suitable for large sets of data. The gain is that it
1635 can be used in a relatively versatile way. The input or output may never be
1636 serialized, but the size of documents it can handle are limited by the size
1637 of the memory available.</p>
1639 <p>More specialized memory handling approaches are possible, like building
1640 the input tree from a serialization progressively as it is consumed,
1641 factoring repetitive patterns, or even on-the-fly generation of the output as
1642 the input is parsed but it is possible only for a limited subset of the
1643 stylesheets. In general the implementation of libxslt follows the following
1646 <li>KISS (keep it simple stupid)</li>
1647 <li>when there is a clear bottleneck optimize on top of this simple
1648 framework and refine only as much as is needed to reach the expected
1652 <p>The result is not that bad, clearly one can do a better job but more
1653 specialized too. Most optimization like building the tree on-demand would
1654 need serious changes to the libxml XPath framework. An easy step would be to
1655 serialize the output directly (or call a set of SAX-like output handler to
1656 keep this a flexible interface) and hence avoid the memory consumption of the
1659 <h3><a name="libxml">The libxml nodes</a></h3>
1661 <p>DOM-like trees, as used and generated by libxml and libxslt, are
1662 relatively complex. Most node types follow the given structure except a few
1663 variations depending on the node type:</p>
1665 <p align="center"><img src="node.gif" alt="description of a libxml node"></p>
1667 <p>Nodes carry a <strong>name</strong> and the node <strong>type</strong>
1668 indicates the kind of node it represents, the most common ones are:</p>
1670 <li>document nodes</li>
1671 <li>element nodes</li>
1675 <p>For the XSLT processing, entity nodes should not be generated (i.e. they
1676 should be replaced by their content). Most nodes also contains the following
1677 "navigation" information:</p>
1679 <li>the containing <strong>doc</strong>ument</li>
1680 <li>the <strong>parent</strong> node</li>
1681 <li>the first <strong>children</strong> node</li>
1682 <li>the <strong>last</strong> children node</li>
1683 <li>the <strong>prev</strong>ious sibling</li>
1684 <li>the following sibling (<strong>next</strong>)</li>
1687 <p>Elements nodes carries the list of attributes in the properties, an
1688 attribute itself holds the navigation pointers and the children list (the
1689 attribute value is not represented as a simple string to allow usage of
1690 entities references).</p>
1692 <p>The <strong>ns</strong> points to the namespace declaration for the
1693 namespace associated to the node, <strong>nsDef</strong> is the linked list
1694 of namespace declaration present on element nodes.</p>
1696 <p>Most nodes also carry an <strong>_private</strong> pointer which can be
1697 used by the application to hold specific data on this node.</p>
1699 <h3><a name="XSLT">The XSLT processing steps</a></h3>
1701 <p>There are a few steps which are clearly decoupled at the interface
1704 <li>parse the stylesheet and generate a DOM tree</li>
1705 <li>take the stylesheet tree and build a compiled version of it (the
1706 compilation phase)</li>
1707 <li>take the input and generate a DOM tree</li>
1708 <li>process the stylesheet against the input tree and generate an output
1710 <li>serialize the output tree</li>
1713 <p>A few things should be noted here:</p>
1715 <li>the steps 1/ 3/ and 5/ are optional</li>
1716 <li>the stylesheet obtained at 2/ can be reused by multiple processing 4/
1717 (and this should also work in threaded programs)</li>
1718 <li>the tree provided in 2/ should never be freed using xmlFreeDoc, but by
1719 freeing the stylesheet.</li>
1720 <li>the input tree 4/ is not modified except the _private field which may
1721 be used for labelling keys if used by the stylesheet</li>
1724 <h3><a name="XSLT1">The XSLT stylesheet compilation</a></h3>
1726 <p>This is the second step described. It takes a stylesheet tree, and
1727 "compiles" it. This associates to each node a structure stored in the
1728 _private field and containing information computed in the stylesheet:</p>
1730 <p align="center"><img src="stylesheet.gif"
1731 alt="a compiled XSLT stylesheet"></p>
1733 <p>One xsltStylesheet structure is generated per document parsed for the
1734 stylesheet. XSLT documents allow includes and imports of other documents,
1735 imports are stored in the <strong>imports</strong> list (hence keeping the
1736 tree hierarchy of includes which is very important for a proper XSLT
1737 processing model) and includes are stored in the <strong>doclist</strong>
1738 list. An imported stylesheet has a parent link to allow browsing of the
1741 <p>The DOM tree associated to the document is stored in <strong>doc</strong>.
1742 It is preprocessed to remove ignorable empty nodes and all the nodes in the
1743 XSLT namespace are subject to precomputing. This usually consist of
1744 extracting all the context information from the context tree (attributes,
1745 namespaces, XPath expressions), and storing them in an xsltStylePreComp
1746 structure associated to the <strong>_private</strong> field of the node.</p>
1748 <p>A couple of notable exceptions to this are XSLT template nodes (more on
1749 this later) and attribute value templates. If they are actually templates,
1750 the value cannot be computed at compilation time. (Some preprocessing could
1751 be done like isolation and preparsing of the XPath subexpressions but it's
1754 <p>The xsltStylePreComp structure also allows storing of the precompiled form
1755 of an XPath expression that can be associated to an XSLT element (more on
1758 <h3><a name="XSLT2">The XSLT template compilation</a></h3>
1760 <p>A proper handling of templates lookup is one of the keys of fast XSLT
1761 processing. (Given a node in the source document this is the process of
1762 finding which templates should be applied to this node.) Libxslt follows the
1763 hint suggested in the <a href="http://www.w3.org/TR/xslt#patterns">5.2
1764 Patterns</a> section of the XSLT Recommendation, i.e. it doesn't evaluate it
1765 as an XPath expression but tokenizes it and compiles it as a set of rules to
1766 be evaluated on a candidate node. There usually is an indication of the node
1767 name in the last step of this evaluation and this is used as a key check for
1768 the match. As a result libxslt builds a relatively more complex set of
1769 structures for the templates:</p>
1771 <p align="center"><img src="templates.gif"
1772 alt="The templates related structure"></p>
1774 <p>Let's describe a bit more closely what is built. First the xsltStylesheet
1775 structure holds a pointer to the template hash table. All the XSLT patterns
1776 compiled in this stylesheet are indexed by the value of the the target
1777 element (or attribute, pi ...) name, so when a element or an attribute "foo"
1778 needs to be processed the lookup is done using the name as a key.</p>
1780 <p>Each of the patterns is compiled into an xsltCompMatch structure. It holds
1781 the set of rules based on the tokenization of the pattern stored in reverse
1782 order (matching is easier this way). It also holds some information about the
1783 previous matches used to speed up the process when one iterates over a set of
1784 siblings. (This optimization may be defeated by trashing when running
1785 threaded computation, it's unclear that this is a big deal in practice.)
1786 Predicate expressions are not compiled at this stage, they may be at run-time
1787 if needed, but in this case they are compiled as full XPath expressions (the
1788 use of some fixed predicate can probably be optimized, they are not yet).</p>
1790 <p>The xsltCompMatch are then stored in the hash table, the clash list is
1791 itself sorted by priority of the template to implement "naturally" the XSLT
1794 <p>Associated to the compiled pattern is the xsltTemplate itself containing
1795 the information required for the processing of the pattern including, of
1796 course, a pointer to the list of elements used for building the pattern
1799 <p>Last but not least a number of patterns do not fit in the hash table
1800 because they are not associated to a name, this is the case for patterns
1801 applying to the root, any element, any attributes, text nodes, pi nodes, keys
1802 etc. Those are stored independently in the stylesheet structure as separate
1803 linked lists of xsltCompMatch.</p>
1805 <h3><a name="processing">The processing itself</a></h3>
1807 <p>The processing is defined by the XSLT specification (the basis of the
1808 algorithm is explained in <a
1809 href="http://www.w3.org/TR/xslt#section-Introduction">the Introduction</a>
1810 section). Basically it works by taking the root of the input document and
1811 applying the following algorithm:</p>
1813 <li>Finding the template applying to it. This is a lookup in the template
1814 hash table, walking the hash list until the node satisfies all the steps
1815 of the pattern, then checking the appropriate(s) global templates to see
1816 if there isn't a higher priority rule to apply</li>
1817 <li>If there is no template, apply the default rule (recurse on the
1819 <li>else walk the content list of the selected templates, for each of them:
1821 <li>if the node is in the XSLT namespace then the node has a _private
1822 field pointing to the preprocessed values, jump to the specific
1824 <li>if the node is in an extension namespace, look up the associated
1826 <li>otherwise copy the node.</li>
1828 <p>The closure is usually done through the XSLT
1829 <strong>apply-templates</strong> construct recursing by applying the
1830 adequate template on the input node children or on the result of an
1831 associated XPath selection lookup.</p>
1835 <p>Note that large parts of the input tree may not be processed by a given
1836 stylesheet and that on the opposite some may be processed multiple times.
1837 (This often is the case when a Table of Contents is built).</p>
1839 <p>The module <code>transform.c</code> is the one implementing most of this
1840 logic. <strong>xsltApplyStylesheet()</strong> is the entry point, it
1841 allocates an xsltTransformContext containing the following:</p>
1843 <li>a pointer to the stylesheet being processed</li>
1844 <li>a stack of templates</li>
1845 <li>a stack of variables and parameters</li>
1846 <li>an XPath context</li>
1847 <li>the template mode</li>
1848 <li>current document</li>
1849 <li>current input node</li>
1850 <li>current selected node list</li>
1851 <li>the current insertion points in the output document</li>
1852 <li>a couple of hash tables for extension elements and functions</li>
1855 <p>Then a new document gets allocated (HTML or XML depending on the type of
1856 output), the user parameters and global variables and parameters are
1857 evaluated. Then <strong>xsltProcessOneNode()</strong> which implements the
1858 1-2-3 algorithm is called on the root element of the input. Step 1/ is
1859 implemented by calling <strong>xsltGetTemplate()</strong>, step 2/ is
1860 implemented by <strong>xsltDefaultProcessOneNode()</strong> and step 3/ is
1861 implemented by <strong>xsltApplyOneTemplate()</strong>.</p>
1863 <h3><a name="XPath">XPath expression compilation</a></h3>
1865 <p>The XPath support is actually implemented in the libxml module (where it
1866 is reused by the XPointer implementation). XPath is a relatively classic
1867 expression language. The only uncommon feature is that it is working on XML
1868 trees and hence has specific syntax and types to handle them.</p>
1870 <p>XPath expressions are compiled using <strong>xmlXPathCompile()</strong>.
1871 It will take an expression string in input and generate a structure
1872 containing the parsed expression tree, for example the expression:</p>
1873 <pre>/doc/chapter[title='Introduction']</pre>
1875 <p>will be compiled as</p>
1876 <pre>Compiled Expression : 10 elements
1878 COLLECT 'child' 'name' 'node' chapter
1879 COLLECT 'child' 'name' 'node' doc
1884 COLLECT 'child' 'name' 'node' title
1886 ELEM Object is a string : Introduction
1887 COLLECT 'child' 'name' 'node' title
1890 <p>This can be tested using the <code>testXPath</code> command (in the
1891 libxml codebase) using the <code>--tree</code> option.</p>
1893 <p>Again, the KISS approach is used. No optimization is done. This could be
1894 an interesting thing to add. <a
1895 href="http://www-106.ibm.com/developerworks/library/x-xslt2/?dwzone=x?open&l=132%2ct=gr%2c+p=saxon">Michael
1896 Kay describes</a> a lot of possible and interesting optimizations done in
1897 Saxon which would be possible at this level. I'm unsure they would provide
1898 much gain since the expressions tends to be relatively simple in general and
1899 stylesheets are still hand generated. Optimizations at the interpretation
1900 sounds likely to be more efficient.</p>
1902 <h3><a name="XPath1">XPath interpretation</a></h3>
1904 <p>The interpreter is implemented by <strong>xmlXPathCompiledEval()</strong>
1905 which is the front-end to <strong>xmlXPathCompOpEval()</strong> the function
1906 implementing the evaluation of the expression tree. This evaluation follows
1907 the KISS approach again. It's recursive and calls
1908 <strong>xmlXPathNodeCollectAndTest()</strong> to collect nodes set when
1909 evaluating a <code>COLLECT</code> node.</p>
1911 <p>An evaluation is done within the framework of an XPath context stored in
1912 an <strong>xmlXPathContext</strong> structure, in the framework of a
1913 transformation the context is maintained within the XSLT context. Its content
1914 follows the requirements from the XPath specification:</p>
1916 <li>the current document</li>
1917 <li>the current node</li>
1918 <li>a hash table of defined variables (but not used by XSLT)</li>
1919 <li>a hash table of defined functions</li>
1920 <li>the proximity position (the place of the node in the current node
1922 <li>the context size (the size of the current node list)</li>
1923 <li>the array of namespace declarations in scope (there also is a namespace
1924 hash table but it is not used in the XSLT transformation).</li>
1927 <p>For the purpose of XSLT an <strong>extra</strong> pointer has been added
1928 allowing to retrieve the XSLT transformation context. When an XPath
1929 evaluation is about to be performed, an XPath parser context is allocated
1930 containing and XPath object stack (this is actually an XPath evaluation
1931 context, this is a remain of the time where there was no separate parsing and
1932 evaluation phase in the XPath implementation). Here is an overview of the set
1933 of contexts associated to an XPath evaluation within an XSLT
1936 <p align="center"><img src="contexts.gif"
1937 alt="The set of contexts associated "></p>
1939 <p>Clearly this is a bit too complex and confusing and should be refactored
1940 at the next set of binary incompatible releases of libxml. For example the
1941 xmlXPathCtxt has a lot of unused parts and should probably be merged with
1942 xmlXPathParserCtxt.</p>
1944 <h3><a name="Descriptio">Description of XPath Objects</a></h3>
1946 <p>An XPath expression manipulates XPath objects. XPath defines the default
1947 types boolean, numbers, strings and node sets. XSLT adds the result tree
1948 fragment type which is basically an unmodifiable node set.</p>
1950 <p>Implementation-wise, libxml follows again a KISS approach, the
1951 xmlXPathObject is a structure containing a type description and the various
1952 possibilities. (Using an enum could have gained some bytes.) In the case of
1953 node sets (or result tree fragments), it points to a separate xmlNodeSet
1954 object which contains the list of pointers to the document nodes:</p>
1956 <p align="center"><img src="object.gif"
1957 alt="An Node set object pointing to "></p>
1959 <p>The <a href="http://xmlsoft.org/html/libxml-xpath.html">XPath API</a> (and
1960 its <a href="http://xmlsoft.org/html/libxml-xpathinternals.html">'internal'
1961 part</a>) includes a number of functions to create, copy, compare, convert or
1962 free XPath objects.</p>
1964 <h3><a name="XPath3">XPath functions</a></h3>
1966 <p>All the XPath functions available to the interpreter are registered in the
1967 function hash table linked from the XPath context. They all share the same
1969 <pre>void xmlXPathFunc (xmlXPathParserContextPtr ctxt, int nargs);</pre>
1971 <p>The first argument is the XPath interpretation context, holding the
1972 interpretation stack. The second argument defines the number of objects
1973 passed on the stack for the function to consume (last argument is on top of
1976 <p>Basically an XPath function does the following:</p>
1978 <li>check <code>nargs</code> for proper handling of errors or functions
1979 with variable numbers of parameters</li>
1980 <li>pop the parameters from the stack using <code>obj =
1981 valuePop(ctxt);</code></li>
1982 <li>do the function specific computation</li>
1983 <li>push the result parameter on the stack using <code>valuePush(ctxt,
1985 <li>free up the input parameters with
1986 <code>xmlXPathFreeObject(obj);</code></li>
1990 <p>Sometime the work can be done directly by modifying in-situ the top object
1991 on the stack <code>ctxt->value</code>.</p>
1993 <h3><a name="stack">The XSLT variables stack frame</a></h3>
1995 <p>Not to be confused with XPath object stack, this stack holds the XSLT
1996 variables and parameters as they are defined through the recursive calls of
1997 call-template, apply-templates and default templates. This is used to define
1998 the scope of variables being called.</p>
2000 <p>This part seems to be the most urgent attention right now, first it is
2001 done in a very inefficient way since the location of the variables and
2002 parameters within the stylesheet tree is still done at run time (it really
2003 should be done statically at compile time), and I am still unsure that my
2004 understanding of the template variables and parameter scope is actually
2007 <p>This part of the documentation is still to be written once this part of
2008 the code will be stable. <span
2009 style="background-color: #FF0000">TODO</span></p>
2011 <h3><a name="Extension">Extension support</a></h3>
2013 <p>There is a separate document explaining <a href="extensions.html">how the
2014 extension support works</a>.</p>
2016 <h3><a name="Futher">Further reading</a></h3>
2018 <p>Michael Kay wrote <a
2019 href="http://www-106.ibm.com/developerworks/library/x-xslt2/?dwzone=x?open&l=132%2ct=gr%2c+p=saxon">a
2020 really interesting article on Saxon internals</a> and the work he did on
2021 performance issues. I wishes I had read it before starting libxslt design (I
2022 would probably have avoided a few mistakes and progressed faster). A lot of
2023 the ideas in his papers should be implemented or at least tried in
2026 <p>The <a href="http://xmlsoft.org/">libxml documentation</a>, especially <a
2027 href="http://xmlsoft.org/xmlio.html">the I/O interfaces</a> and the <a
2028 href="http://xmlsoft.org/xmlmem.html">memory management</a>.</p>
2030 <h3><a name="TODOs">TODOs</a></h3>
2032 <p>redesign the XSLT stack frame handling. Far too much work is done at
2033 execution time. Similarly for the attribute value templates handling, at
2034 least the embedded subexpressions ought to be precompiled.</p>
2036 <p>Allow output to be saved to a SAX like output (this notion of SAX like API
2037 for output should be added directly to libxml).</p>
2039 <p>Implement and test some of the optimization explained by Michael Kay
2042 <li>static slot allocation on the stack frame</li>
2043 <li>specific boolean interpretation of an XPath expression</li>
2044 <li>some of the sorting optimization</li>
2045 <li>Lazy evaluation of location path. (this may require more changes but
2046 sounds really interesting. XT does this too.)</li>
2047 <li>Optimization of an expression tree (This could be done as a completely
2048 independent module.)</li>
2053 <p>Error reporting, there is a lot of case where the XSLT specification
2054 specify that a given construct is an error are not checked adequately by
2055 libxslt. Basically one should do a complete pass on the XSLT spec again and
2056 add all tests to the stylesheet compilation. Using the DTD provided in the
2057 appendix and making direct checks using the libxml validation API sounds a
2058 good idea too (though one should take care of not raising errors for
2059 elements/attributes in different namespaces).</p>
2061 <p>Double check all the places where the stylesheet compiled form might be
2062 modified at run time (extra removal of blanks nodes, hint on the
2067 <h2><a name="Extensions">Writing extensions</a></h2>
2069 <h3>Table of content</h3>
2071 <li><a href="extensions.html#Introducti">Introduction</a></li>
2072 <li><a href="extensions.html#Basics">Basics</a></li>
2073 <li><a href="extensions.html#Keep">Extension modules</a></li>
2074 <li><a href="extensions.html#Registerin">Registering a module</a></li>
2075 <li><a href="extensions.html#module">Loading a module</a></li>
2076 <li><a href="extensions.html#Registerin1">Registering an extension
2078 <li><a href="extensions.html#Implementi">Implementing an extension
2080 <li><a href="extensions.html#Examples">Examples for extension
2082 <li><a href="extensions.html#Registerin2">Registering an extension
2084 <li><a href="extensions.html#Implementi1">Implementing an extension
2086 <li><a href="extensions.html#Example">Example for extension
2088 <li><a href="extensions.html#shutdown">The shutdown of a module</a></li>
2089 <li><a href="extensions.html#Future">Future work</a></li>
2092 <h3><a name="Introducti1">Introduction</a></h3>
2094 <p>This document describes the work needed to write extensions to the
2095 standard XSLT library for use with <a
2096 href="http://xmlsoft.org/XSLT/">libxslt</a>, the <a
2097 href="http://www.w3.org/TR/xslt">XSLT</a> C library developed for the <a
2098 href="http://www.gnome.org/">GNOME</a> project.</p>
2100 <p>Before starting reading this document it is highly recommended to get
2101 familiar with <a href="internals.html">the libxslt internals</a>.</p>
2103 <p>Note: this documentation is by definition incomplete and I am not good at
2104 spelling, grammar, so patches and suggestions are <a
2105 href="mailto:veillard@redhat.com">really welcome</a>.</p>
2107 <h3><a name="Basics">Basics</a></h3>
2109 <p>The <a href="http://www.w3.org/TR/xslt">XSLT specification</a> provides
2110 two <a href="http://www.w3.org/TR/xslt">ways to extend an XSLT engine</a>:</p>
2112 <li>providing <a href="http://www.w3.org/TR/xslt">new extension
2113 functions</a> which can be called from XPath expressions</li>
2114 <li>providing <a href="http://www.w3.org/TR/xslt">new extension
2115 elements</a> which can be inserted in stylesheets</li>
2118 <p>In both cases the extensions need to be associated to a new namespace,
2119 i.e. an URI used as the name for the extension's namespace (there is no need
2120 to have a resource there for this to work).</p>
2122 <p>libxslt provides a few extensions itself, either in the libxslt namespace
2123 "http://xmlsoft.org/XSLT/namespace" or in namespaces for other well known
2124 extensions provided by other XSLT processors like Saxon, Xalan or XT.</p>
2126 <h3><a name="Keep">Extension modules</a></h3>
2128 <p>Since extensions are bound to a namespace name, usually sets of extensions
2129 coming from a given source are using the same namespace name defining in
2130 practice a group of extensions providing elements, functions or both. From
2131 the libxslt point of view those are considered as an "extension module", and
2132 most of the APIs work at a module point of view.</p>
2134 <p>Registration of new functions or elements are bound to the activation of
2135 the module. This is currently done by declaring the namespace as an extension
2136 by using the attribute <code>extension-element-prefixes</code> on the
2137 <code><a href="http://www.w3.org/TR/xslt">xsl:stylesheet</a></code>
2140 <p>An extension module is defined by 3 objects:</p>
2142 <li>the namespace name associated</li>
2143 <li>an initialization function</li>
2144 <li>a shutdown function</li>
2147 <h3><a name="Registerin">Registering a module</a></h3>
2149 <p>Currently a libxslt module has to be compiled within the application using
2150 libxslt. There is no code to load dynamically shared libraries associated to
2151 a namespace (this may be added but is likely to become a portability
2154 <p>The current way to register a module is to link the code implementing it
2155 with the application and to call a registration function:</p>
2156 <pre>int xsltRegisterExtModule(const xmlChar *URI,
2157 xsltExtInitFunction initFunc,
2158 xsltExtShutdownFunction shutdownFunc);</pre>
2160 <p>The associated header is read by:</p>
2161 <pre>#include<libxslt/extensions.h></pre>
2163 <p>which also defines the type for the initialization and shutdown
2166 <h3><a name="module">Loading a module</a></h3>
2168 <p>Once the module URI has been registered and if the XSLT processor detects
2169 that a given stylesheet needs the functionalities of an extended module, this
2170 one is initialized.</p>
2172 <p>The xsltExtInitFunction type defines the interface for an initialization
2175 * xsltExtInitFunction:
2176 * @ctxt: an XSLT transformation context
2177 * @URI: the namespace URI for the extension
2179 * A function called at initialization time of an XSLT
2182 * Returns a pointer to the module specific data for this
2185 typedef void *(*xsltExtInitFunction)(xsltTransformContextPtr ctxt,
2186 const xmlChar *URI);</pre>
2188 <p>There are 3 things to notice:</p>
2190 <li>The function gets passed the namespace name URI as an argument. This
2191 allows a single function to provide the initialization for multiple
2192 logical modules.</li>
2193 <li>It also gets passed a transformation context. The initialization is
2194 done at run time before any processing occurs on the stylesheet but it
2195 will be invoked separately each time for each transformation.</li>
2196 <li>It returns a pointer. This can be used to store module specific
2197 information which can be retrieved later when a function or an element
2198 from the extension is used. An obvious example is a connection to a
2199 database which should be kept and reused along with the transformation.
2200 NULL is a perfectly valid return; there is no way to indicate a failure
2204 <p>What this function is expected to do is:</p>
2206 <li>prepare the context for this module (like opening the database
2208 <li>register the extensions specific to this module</li>
2211 <h3><a name="Registerin1">Registering an extension function</a></h3>
2213 <p>There is a single call to do this registration:</p>
2214 <pre>int xsltRegisterExtFunction(xsltTransformContextPtr ctxt,
2215 const xmlChar *name,
2217 xmlXPathEvalFunc function);</pre>
2219 <p>The registration is bound to a single transformation instance referred by
2220 ctxt, name is the UTF8 encoded name for the NCName of the function, and URI
2221 is the namespace name for the extension (no checking is done, a module could
2222 register functions or elements from a different namespace, but it is not
2225 <h3><a name="Implementi">Implementing an extension function</a></h3>
2227 <p>The implementation of the function must have the signature of a libxml
2231 * @ctxt: an XPath parser context
2232 * @nargs: the number of arguments passed to the function
2234 * an XPath evaluation function, the parameters are on the
2235 * XPath context stack
2238 typedef void (*xmlXPathEvalFunc)(xmlXPathParserContextPtr ctxt,
2241 <p>The context passed to an XPath function is not an XSLT context but an <a
2242 href="internals.html#XPath1">XPath context</a>. However it is possible to
2243 find one from the other:</p>
2245 <li>The function xsltXPathGetTransformContext provides this lookup facility:
2246 <pre>xsltTransformContextPtr
2247 xsltXPathGetTransformContext
2248 (xmlXPathParserContextPtr ctxt);</pre>
2250 <li>The <code>xmlXPathContextPtr</code> associated to an
2251 <code>xsltTransformContext</code> is stored in the <code>xpathCtxt</code>
2255 <p>The first thing an extension function may want to do is to check the
2256 arguments passed on the stack, the <code>nargs</code> parameter will tell how
2257 many of them were provided on the XPath expression. The macro valuePop will
2258 extract them from the XPath stack:</p>
2259 <pre>#include <libxml/xpath.h>
2260 #include <libxml/xpathInternals.h>
2262 xmlXPathObjectPtr obj = valuePop(ctxt); </pre>
2264 <p>Note that <code>ctxt</code> is the XPath context not the XSLT one. It is
2265 then possible to examine the content of the value. Check <a
2266 href="internals.html#Descriptio">the description of XPath objects</a> if
2267 necessary. The following is a common sequence checking whether the argument
2268 passed is a string and converting it using the built-in XPath
2269 <code>string()</code> function if this is not the case:</p>
2270 <pre>if (obj->type != XPATH_STRING) {
2271 valuePush(ctxt, obj);
2272 xmlXPathStringFunction(ctxt, 1);
2273 obj = valuePop(ctxt);
2276 <p>Most common XPath functions are available directly at the C level and are
2277 exported either in <code><libxml/xpath.h></code> or in
2278 <code><libxml/xpathInternals.h></code>.</p>
2280 <p>The extension function may also need to retrieve the data associated to
2281 this module instance (the database connection in the previous example) this
2282 can be done using the xsltGetExtData:</p>
2283 <pre>void * xsltGetExtData(xsltTransformContextPtr ctxt,
2284 const xmlChar *URI);</pre>
2286 <p>Again the URI to be provided is the one which was used when registering
2289 <p>Once the function finishes, don't forget to:</p>
2291 <li>push the return value on the stack using <code>valuePush(ctxt,
2293 <li>deallocate the parameters passed to the function using
2294 <code>xmlXPathFreeObject(obj)</code></li>
2297 <h3><a name="Examples">Examples for extension functions</a></h3>
2299 <p>The module libxslt/functions.c contains the sources of the XSLT built-in
2300 functions, including document(), key(), generate-id(), etc. as well as a full
2301 example module at the end. Here is the test function implementation for the
2302 libxslt:test function:</p>
2304 * xsltExtFunctionTest:
2305 * @ctxt: the XPath Parser context
2306 * @nargs: the number of arguments
2308 * function libxslt:test() for testing the extensions support.
2311 xsltExtFunctionTest(xmlXPathParserContextPtr ctxt, int nargs)
2313 xsltTransformContextPtr tctxt;
2316 tctxt = xsltXPathGetTransformContext(ctxt);
2317 if (tctxt == NULL) {
2318 xsltGenericError(xsltGenericErrorContext,
2319 "xsltExtFunctionTest: failed to get the transformation context\n");
2322 data = xsltGetExtData(tctxt, (const xmlChar *) XSLT_DEFAULT_URL);
2324 xsltGenericError(xsltGenericErrorContext,
2325 "xsltExtFunctionTest: failed to get module data\n");
2328 #ifdef WITH_XSLT_DEBUG_FUNCTION
2329 xsltGenericDebug(xsltGenericDebugContext,
2330 "libxslt:test() called with %d args\n", nargs);
2334 <h3><a name="Registerin2">Registering an extension element</a></h3>
2336 <p>There is a single call to do this registration:</p>
2337 <pre>int xsltRegisterExtElement(xsltTransformContextPtr ctxt,
2338 const xmlChar *name,
2340 xsltTransformFunction function);</pre>
2342 <p>It is similar to the mechanism used to register an extension function,
2343 except that the signature of an extension element implementation is
2346 <p>The registration is bound to a single transformation instance referred to
2347 by ctxt, name is the UTF8 encoded name for the NCName of the element, and URI
2348 is the namespace name for the extension (no checking is done, a module could
2349 register elements for a different namespace, but it is not recommended).</p>
2351 <h3><a name="Implementi1">Implementing an extension element</a></h3>
2353 <p>The implementation of the element must have the signature of an XSLT
2354 transformation function:</p>
2356 * xsltTransformFunction:
2357 * @ctxt: the XSLT transformation context
2358 * @node: the input node
2359 * @inst: the stylesheet node
2360 * @comp: the compiled information from the stylesheet
2362 * signature of the function associated to elements part of the
2363 * stylesheet language like xsl:if or xsl:apply-templates.
2365 typedef void (*xsltTransformFunction)
2366 (xsltTransformContextPtr ctxt,
2369 xsltStylePreCompPtr comp);</pre>
2371 <p>The first argument is the XSLT transformation context. The second and
2372 third arguments are xmlNodePtr i.e. internal memory <a
2373 href="internals.html#libxml">representation of XML nodes</a>. They are
2374 respectively <code>node</code> from the the input document being transformed
2375 by the stylesheet and <code>inst</code> the extension element in the
2376 stylesheet. The last argument is <code>comp</code> a pointer to a precompiled
2377 representation of <code>inst</code> but usually for an extension function
2378 this value is <code>NULL</code> by default (it could be added and associated
2379 to the instruction in <code>inst->_private</code>).</p>
2381 <p>The same functions are available from a function implementing an extension
2382 element as in an extension function, including
2383 <code>xsltGetExtData()</code>.</p>
2385 <p>The goal of an extension element being usually to enrich the generated
2386 output, it is expected that they will grow the currently generated output
2387 tree. This can be done by grabbing ctxt->insert which is the current
2388 libxml node being generated (Note this can also be the intermediate value
2389 tree being built for example to initialize a variable, the processing should
2390 be similar). The functions for libxml tree manipulation from <a
2391 href="http://xmlsoft.org/html/libxml-tree.html"><libxml/tree.h></a> can
2392 be employed to extend or modify the tree, but it is required to preserve the
2393 insertion node and its ancestors since there are existing pointers to those
2394 elements still in use in the XSLT template execution stack.</p>
2396 <h3><a name="Example">Example for extension elements</a></h3>
2398 <p>The module libxslt/transform.c contains the sources of the XSLT built-in
2399 elements, including xsl:element, xsl:attribute, xsl:if, etc. There is a small
2400 but full example in functions.c providing the implementation for the
2401 libxslt:test element, it will output a comment in the result tree:</p>
2403 * xsltExtElementTest:
2404 * @ctxt: an XSLT processing context
2405 * @node: The current node
2406 * @inst: the instruction in the stylesheet
2407 * @comp: precomputed information
2409 * Process a libxslt:test node
2412 xsltExtElementTest(xsltTransformContextPtr ctxt, xmlNodePtr node,
2414 xsltStylePreCompPtr comp)
2419 xsltGenericError(xsltGenericErrorContext,
2420 "xsltExtElementTest: no transformation context\n");
2424 xsltGenericError(xsltGenericErrorContext,
2425 "xsltExtElementTest: no current node\n");
2429 xsltGenericError(xsltGenericErrorContext,
2430 "xsltExtElementTest: no instruction\n");
2433 if (ctxt->insert == NULL) {
2434 xsltGenericError(xsltGenericErrorContext,
2435 "xsltExtElementTest: no insertion point\n");
2439 xmlNewComment((const xmlChar *)
2440 "libxslt:test element test worked");
2441 xmlAddChild(ctxt->insert, comment);
2444 <h3><a name="shutdown">The shutdown of a module</a></h3>
2446 <p>When the XSLT processor ends a transformation, the shutdown function (if
2447 it exists) for each of the modules initialized is called. The
2448 xsltExtShutdownFunction type defines the interface for a shutdown
2451 * xsltExtShutdownFunction:
2452 * @ctxt: an XSLT transformation context
2453 * @URI: the namespace URI for the extension
2454 * @data: the data associated to this module
2456 * A function called at shutdown time of an XSLT extension module
2458 typedef void (*xsltExtShutdownFunction) (xsltTransformContextPtr ctxt,
2462 <p>This is really similar to a module initialization function except a third
2463 argument is passed, it's the value that was returned by the initialization
2464 function. This allows the routine to deallocate resources from the module for
2465 example close the connection to the database to keep the same example.</p>
2467 <h3><a name="Future">Future work</a></h3>
2469 <p>Well, some of the pieces missing:</p>
2471 <li>a way to load shared libraries to instantiate new modules</li>
2472 <li>a better detection of extension functions usage and their registration
2473 without having to use the extension prefix which ought to be reserved to
2474 element extensions.</li>
2475 <li>more examples</li>
2476 <li>implementations of the <a href="http://www.exslt.org/">EXSLT</a> common
2477 extension libraries, Thomas Broyer nearly finished implementing them.</li>
2482 <h2><a name="Contributi">Contributions</a></h2>
2484 <li>Bjorn Reese is the author of the number support and worked on the
2485 XSLTMark support</li>
2486 <li>William Brack was an early adopted, contributed a number of patches and
2487 spent quite some time debugging non-trivial problems in early versions of
2489 <li><a href="mailto:igor@zlatkovic.com">Igor Zlatkovic</a> is now the
2490 maintainer of the Windows port, <a
2491 href="http://www.zlatkovic.com/projects/libxml/index.html">he provides
2493 <li>Thomas Broyer provided a lot of suggestions, and drafted most of the
2495 <li>John Fleck maintains <a href="tutorial/libxslttutorial.html">a tutorial
2496 for libxslt</a></li>
2498 href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">Matt
2499 Sergeant</a> developed <a
2500 href="http://axkit.org/download/">XML::LibXSLT</a>, a perl wrapper for
2501 libxml2/libxslt as part of the <a href="http://axkit.com/">AxKit XML
2502 application server</a></li>
2503 <li>there is a module for <a
2504 href="http://acs-misc.sourceforge.net/nsxml.html">libxml/libxslt support
2505 in OpenNSD/AOLServer</a></li>
2506 <li><a href="mailto:dkuhlman@cutter.rexx.com">Dave Kuhlman</a> provides
2507 libxml/libxslt <a href="http://www.rexx.com/~dkuhlman">wrappers for
2509 <li><a href="mailto:Steve.Ball@explain.com.au">Steve Ball</a>, and
2510 contributors maintain <a href="http://tclxml.sourceforge.net/">tcl
2511 bindings for libxml2 and libxslt</a>, as well as <a
2512 href="http://tclxml.sf.net/tkxmllint.html">tkxmllint</a> a GUI for
2513 xmllint and <a href="http://tclxml.sf.net/tkxsltproc.html">tkxsltproc</a>
2514 a GUI for xsltproc.</li>
2515 <li>If you want to use libxslt in a Mac OS X/Cocoa or Objective-C
2516 framework, Marc Liyanage provides <a
2517 href="http://www.entropy.ch/software/macosx/#testxslt">an application
2518 TestXSLT for XSLT and XML editing</a> including wrapper classes for the
2519 XML parser and XSLT processor.</li>
2524 <p><a href="mailto:daniel@veillard.com">Daniel Veillard</a></p>
projects / platform / upstream / libxslt.git / blob