doc/xslt.html

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