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