xml.html revision 81781103cd3636c70a6f28665badd5608bbbf7a8
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 XML C library for Gnome</title> 6 <meta name="GENERATOR" content="amaya V4.1"> 7 <meta http-equiv="Content-Type" content="text/html"> 8</head> 9 10<body bgcolor="#ffffff"> 11<p><a href="http://www.gnome.org/"><img src="smallfootonly.gif" 12alt="Gnome Logo"></a><a href="http://www.w3.org/Status"><img src="w3c.png" 13alt="W3C Logo"></a></p> 14 15<h1 align="center">The XML C library for Gnome</h1> 16 17<h2 style="text-align: center">libxml, a.k.a. gnome-xml</h2> 18 19<p></p> 20<ul> 21 <li><a href="#Introducti">Introduction</a></li> 22 <li><a href="#Documentat">Documentation</a></li> 23 <li><a href="#Reporting">Reporting bugs and getting help</a></li> 24 <li><a href="#help">how to help</a></li> 25 <li><a href="#Downloads">Downloads</a></li> 26 <li><a href="#News">News</a></li> 27 <li><a href="#XML">XML</a></li> 28 <li><a href="#XSLT">XSLT</a></li> 29 <li><a href="#tree">The tree output</a></li> 30 <li><a href="#interface">The SAX interface</a></li> 31 <li><a href="#library">The XML library interfaces</a> 32 <ul> 33 <li><a href="#Invoking">Invoking the parser: the pull way</a></li> 34 <li><a href="#Invoking">Invoking the parser: the push way</a></li> 35 <li><a href="#Invoking2">Invoking the parser: the SAX interface</a></li> 36 <li><a href="#Building">Building a tree from scratch</a></li> 37 <li><a href="#Traversing">Traversing the tree</a></li> 38 <li><a href="#Modifying">Modifying the tree</a></li> 39 <li><a href="#Saving">Saving the tree</a></li> 40 <li><a href="#Compressio">Compression</a></li> 41 </ul> 42 </li> 43 <li><a href="#Entities">Entities or no entities</a></li> 44 <li><a href="#Namespaces">Namespaces</a></li> 45 <li><a href="#Validation">Validation</a></li> 46 <li><a href="#Principles">DOM principles</a></li> 47 <li><a href="#real">A real example</a></li> 48 <li><a href="#Contributi">Contributions</a></li> 49</ul> 50 51<p>Separate documents:</p> 52<ul> 53 <li><a href="upgrade.html">upgrade instructions for migrating to 54 libxml2</a></li> 55 <li><a href="encoding.html">libxml Internationalization support</a></li> 56 <li><a href="xmlio.html">libxml Input/Output interfaces</a></li> 57 <li><a href="xmlmem.html">libxml Memory interfaces</a></li> 58 <li><a href="xmldtd.html">a short introduction about DTDs and 59 libxml</a></li> 60 <li><a href="http://xmlsoft.org/XSLT/">the libxslt page</a></li> 61</ul> 62 63<h2><a name="Introducti">Introduction</a></h2> 64 65<p>This document describes libxml, the <a 66href="http://www.w3.org/XML/">XML</a> C library developped for the <a 67href="http://www.gnome.org/">Gnome</a> project. <a 68href="http://www.w3.org/XML/">XML is a standard</a> for building tag-based 69structured documents/data.</p> 70 71<p>Here are some key points about libxml:</p> 72<ul> 73 <li>Libxml exports Push and Pull type parser interfaces for both XML and 74 HTML.</li> 75 <li>Libxml can do DTD validation at parse time, using a parsed document 76 instance, or with an arbitrary DTD.</li> 77 <li>Libxml now includes nearly complete <a 78 href="http://www.w3.org/TR/xpath">XPath</a> and <a 79 href="http://www.w3.org/TR/xptr">XPointer</a> implementations.</li> 80 <li>It is written in plain C, making as few assumptions as possible, and 81 sticking closely to ANSI C/POSIX for easy embedding. Works on 82 Linux/Unix/Windows, ported to a number of other platforms.</li> 83 <li>Basic support for HTTP and FTP client allowing aplications to fetch 84 remote resources</li> 85 <li>The design is modular, most of the extensions can be compiled out.</li> 86 <li>The internal document repesentation is as close as possible to the <a 87 href="http://www.w3.org/DOM/">DOM</a> interfaces.</li> 88 <li>Libxml also has a <a href="http://www.megginson.com/SAX/index.html">SAX 89 like interface</a>; the interface is designed to be compatible with <a 90 href="http://www.jclark.com/xml/expat.html">Expat</a>.</li> 91 <li>This library is released both under the <a 92 href="http://www.w3.org/Consortium/Legal/copyright-software-19980720.html">W3C 93 IPR</a> and the <a href="http://www.gnu.org/copyleft/lesser.html">GNU 94 LGPL</a>. Use either at your convenience, basically this should make 95 everybody happy, if not, drop me a mail.</li> 96</ul> 97 98<h2><a name="Documentat">Documentation</a></h2> 99 100<p>There are some on-line resources about using libxml:</p> 101<ol> 102 <li>Check the <a href="FAQ.html">FAQ</a></li> 103 <li>Check the <a href="http://xmlsoft.org/html/libxml-lib.html">extensive 104 documentation</a> automatically extracted from code comments (using <a 105 href="http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&dir=gtk-doc">gtk 106 doc</a>).</li> 107 <li>Look at the documentation about <a href="encoding.html">libxml 108 internationalization support</a></li> 109 <li>This page provides a global overview and <a href="#real">some 110 examples</a> on how to use libxml.</li> 111 <li><a href="mailto:james@daa.com.au">James Henstridge</a> wrote <a 112 href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">some nice 113 documentation</a> explaining how to use the libxml SAX interface.</li> 114 <li>George Lebl wrote <a 115 href="http://www-4.ibm.com/software/developer/library/gnome3/">an article 116 for IBM developerWorks</a> about using libxml.</li> 117 <li>It is also a good idea to check to <a href="mailto:raph@levien.com">Raph 118 Levien</a>'s <a href="http://levien.com/gnome/">web site</a> since he is 119 building the <a href="http://levien.com/gnome/gdome.html">DOM interface 120 gdome</a> on top of libxml result tree and an implementation of <a 121 href="http://www.w3.org/Graphics/SVG/">SVG</a> called <a 122 href="http://www.levien.com/svg/">gill</a>. Check his <a 123 href="http://www.levien.com/gnome/domination.html">DOMination 124 paper</a>.</li> 125 <li>Check <a href="http://cvs.gnome.org/lxr/source/gnome-xml/TODO">the TODO 126 file</a></li> 127 <li>Read the <a href="upgrade.html">1.x to 2.x upgrade path</a>. If you are 128 starting a new project using libxml you should really use the 2.x 129 version.</li> 130 <li>And don't forget to look at the <a href="/messages/">mailing-list 131 archive</a>.</li> 132</ol> 133 134<h2><a name="Reporting">Reporting bugs and getting help</a></h2> 135 136<p>Well, bugs or missing features are always possible, and I will make a point 137of fixing them in a timely fashion. The best way to report a bug is to use the 138<a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml">Gnome bug 139tracking database</a> (make sure to use the "libxml" module name). I look at 140reports there regularly and it's good to have a reminder when a bug is still 141open. Check the <a href="http://bugs.gnome.org/Reporting.html">instructions on 142reporting bugs</a> and be sure to specify that the bug is for the package 143libxml.</p> 144 145<p>There is also a mailing-list <a 146href="mailto:xml@rpmfind.net">xml@rpmfind.net</a> for libxml, with an <a 147href="http://xmlsoft.org/messages">on-line archive</a>. To subscribe to this 148majordomo based list, send a mail message to <a 149href="mailto:majordomo@rpmfind.net">majordomo@rpmfind.net</a> with "subscribe 150xml" in the <strong>content</strong> of the message.</p> 151 152<p>Alternatively, you can just send the bug to the <a 153href="mailto:xml@rpmfind.net">xml@rpmfind.net</a> list; if it's really libxml 154related I will approve it..</p> 155 156<p>Of course, bugs reported with a suggested patch for fixing them will 157probably be processed faster.</p> 158 159<p>If you're looking for help, a quick look at <a 160href="http://xmlsoft.org/messages/#407">the list archive</a> may actually 161provide the answer, I usually send source samples when answering libxml usage 162questions. The <a href="http://xmlsoft.org/html/book1.html">auto-generated 163documentantion</a> is not as polished as I would like (i need to learn more 164about Docbook), but it's a good starting point.</p> 165 166<h2><a name="help">How to help</a></h2> 167 168<p>You can help the project in various ways, the best thing to do first is to 169subscribe to the mailing-list as explained before, check the <a 170href="http://xmlsoft.org/messages/">archives </a>and the <a 171href="http://bugs.gnome.org/db/pa/lgnome-xml.html">Gnome bug 172database:</a>:</p> 173<ol> 174 <li>provide patches when you find problems</li> 175 <li>provide the diffs when you port libxml to a new platform. They may not 176 be integrated in all cases but help pinpointing portability problems 177 and</li> 178 <li>provide documentation fixes (either as patches to the code comments or 179 as HTML diffs).</li> 180 <li>provide new documentations pieces (translations, examples, etc ...)</li> 181 <li>Check the TODO file and try to close one of the items</li> 182 <li>take one of the points raised in the archive or the bug database and 183 provide a fix. <a href="mailto:Daniel.Veillard@w3.org">Get in touch with 184 me </a>before to avoid synchronization problems and check that the 185 suggested fix will fit in nicely :-)</li> 186</ol> 187 188<h2><a name="Downloads">Downloads</a></h2> 189 190<p>The latest versions of libxml can be found on <a 191href="ftp://rpmfind.net/pub/libxml/">rpmfind.net</a> or on the <a 192href="ftp://ftp.gnome.org/pub/GNOME/MIRRORS.html">Gnome FTP server</a> either 193as a <a href="ftp://ftp.gnome.org/pub/GNOME/stable/sources/libxml/">source 194archive</a> or <a 195href="ftp://ftp.gnome.org/pub/GNOME/contrib/redhat/SRPMS/">RPM packages</a>. 196(NOTE that you need both the <a 197href="http://rpmfind.net/linux/RPM/libxml2.html">libxml(2)</a> and <a 198href="http://rpmfind.net/linux/RPM/libxml2-devel.html">libxml(2)-devel</a> 199packages installed to compile applications using libxml.)</p> 200 201<p><a name="Snapshot">Snapshot:</a></p> 202<ul> 203 <li>Code from the W3C cvs base libxml <a 204 href="ftp://rpmfind.net/pub/libxml/cvs-snapshot.tar.gz">cvs-snapshot.tar.gz</a></li> 205 <li>Docs, content of the web site, the list archive included <a 206 href="ftp://rpmfind.net/pub/libxml/libxml-docs.tar.gz">libxml-docs.tar.gz</a></li> 207</ul> 208 209<p><a name="Contribs">Contribs:</a></p> 210 211<p>I do accept external contributions, especially if compiling on another 212platform, get in touch with me to upload the package. I will keep them in the 213<a href="ftp://rpmfind.net/pub/libxml/contribs/">contrib directory</a></p> 214 215<p>Libxml is also available from CVS:</p> 216<ul> 217 <li><p>The <a 218 href="http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&dir=gnome-xml">Gnome 219 CVS base</a>. Check the <a 220 href="http://developer.gnome.org/tools/cvs.html">Gnome CVS Tools</a> page; 221 the CVS module is <b>gnome-xml</b>.</p> 222 </li> 223 <li>The <strong>libxslt</strong> module is also present there</li> 224</ul> 225 226<h2><a name="News">News</a></h2> 227 228<h3>CVS only : check the <a 229href="http://cvs.gnome.org/lxr/source/gnome-xml/ChangeLog">Changelog</a> file 230for a really accurate description</h3> 231 232<p>Items floating around but not actively worked on, get in touch with me if 233you want to test those</p> 234<ul> 235 <li>Implementing <a href="http://xmlsoft.org/XSLT">XSLT</a>, this is done as 236 a separate C library on top of libxml called libxslt, not released yet but 237 available from CVS</li> 238 <li>Finishing up <a href="http://www.w3.org/TR/xptr">XPointer</a> and <a 239 href="http://www.w3.org/TR/xinclude">XInclude</a></li> 240 <li>(seeems working but delayed from release) parsing/import of Docbook SGML 241 docs</li> 242</ul> 243 244<h3>2.3.3: Mar 1 2001</h3> 245<ul> 246 <li>small change in XPath for XSLT</li> 247 <li>documentation cleanups</li> 248 <li>fix in validation by Gary Pennington</li> 249 <li>serious parsing performances improvements</li> 250</ul> 251 252<h3>2.3.2: Feb 24 2001</h3> 253<ul> 254 <li>chasing XPath bugs, found a bunch, completed some TODO</li> 255 <li>fixed a Dtd parsing bug</li> 256 <li>fixed a bug in xmlNodeGetContent</li> 257 <li>ID/IDREF support partly rewritten by Gary Pennington</li> 258</ul> 259 260<h3>2.3.1: Feb 15 2001</h3> 261<ul> 262 <li>some XPath and HTML bug fixes for XSLT</li> 263 <li>small extension of the hash table interfaces for DOM gdome2 264 implementation</li> 265 <li>A few bug fixes</li> 266</ul> 267 268<h3>2.3.0: Feb 8 2001 (2.2.12 was on 25 Jan but I didn't kept track)</h3> 269<ul> 270 <li>Lots of XPath bug fixes</li> 271 <li>Add a mode with Dtd lookup but without validation error reporting for 272 XSLT</li> 273 <li>Add support for text node without escaping (XSLT)</li> 274 <li>bug fixes for xmlCheckFilename</li> 275 <li>validation code bug fixes from Gary Pennington</li> 276 <li>Patch from Paul D. Smith correcting URI path normalization</li> 277 <li>Patch to allow simultaneous install of libxml-devel and 278 libxml2-devel</li> 279 <li>the example Makefile is now fixed</li> 280 <li>added HTML to the RPM packages</li> 281 <li>tree copying bugfixes</li> 282 <li>updates to Windows makefiles</li> 283 <li>optimisation patch from Bjorn Reese</li> 284</ul> 285 286<h3>2.2.11: Jan 4 2001</h3> 287<ul> 288 <li>bunch of bug fixes (memory I/O, xpath, ftp/http, ...)</li> 289 <li>added htmlHandleOmittedElem()</li> 290 <li>Applied Bjorn Reese's IPV6 first patch</li> 291 <li>Applied Paul D. Smith patches for validation of XInclude results</li> 292 <li>added XPointer xmlns() new scheme support</li> 293</ul> 294 295<h3>2.2.10: Nov 25 2000</h3> 296<ul> 297 <li>Fix the Windows problems of 2.2.8</li> 298 <li>integrate OpenVMS patches</li> 299 <li>better handling of some nasty HTML input</li> 300 <li>Improved the XPointer implementation</li> 301 <li>integrate a number of provided patches</li> 302</ul> 303 304<h3>2.2.9: Nov 25 2000</h3> 305<ul> 306 <li>erroneous release :-(</li> 307</ul> 308 309<h3>2.2.8: Nov 13 2000</h3> 310<ul> 311 <li>First version of <a href="http://www.w3.org/TR/xinclude">XInclude</a> 312 support</li> 313 <li>Patch in conditional section handling</li> 314 <li>updated MS compiler project</li> 315 <li>fixed some XPath problems</li> 316 <li>added an URI escaping function</li> 317 <li>some other bug fixes</li> 318</ul> 319 320<h3>2.2.7: Oct 31 2000</h3> 321<ul> 322 <li>added message redirection</li> 323 <li>XPath improvements (thanks TOM !)</li> 324 <li>xmlIOParseDTD() added</li> 325 <li>various small fixes in the HTML, URI, HTTP and XPointer support</li> 326 <li>some cleanup of the Makefile, autoconf and the distribution content</li> 327</ul> 328 329<h3>2.2.6: Oct 25 2000:</h3> 330<ul> 331 <li>Added an hash table module, migrated a number of internal structure to 332 those</li> 333 <li>Fixed a posteriori validation problems</li> 334 <li>HTTP module cleanups</li> 335 <li>HTML parser improvements (tag errors, script/style handling, attribute 336 normalization)</li> 337 <li>coalescing of adjacent text nodes</li> 338 <li>couple of XPath bug fixes, exported the internal API</li> 339</ul> 340 341<h3>2.2.5: Oct 15 2000:</h3> 342<ul> 343 <li>XPointer implementation and testsuite</li> 344 <li>Lot of XPath fixes, added variable and functions registration, more 345 tests</li> 346 <li>Portability fixes, lots of enhancements toward an easy Windows build and 347 release</li> 348 <li>Late validation fixes</li> 349 <li>Integrated a lot of contributed patches</li> 350 <li>added memory management docs</li> 351 <li>a performance problem when using large buffer seems fixed</li> 352</ul> 353 354<h3>2.2.4: Oct 1 2000:</h3> 355<ul> 356 <li>main XPath problem fixed</li> 357 <li>Integrated portability patches for Windows</li> 358 <li>Serious bug fixes on the URI and HTML code</li> 359</ul> 360 361<h3>2.2.3: Sep 17 2000</h3> 362<ul> 363 <li>bug fixes</li> 364 <li>cleanup of entity handling code</li> 365 <li>overall review of all loops in the parsers, all sprintf usage has been 366 checked too</li> 367 <li>Far better handling of larges Dtd. Validating against Docbook XML Dtd 368 works smoothly now.</li> 369</ul> 370 371<h3>1.8.10: Sep 6 2000</h3> 372<ul> 373 <li>bug fix release for some Gnome projects</li> 374</ul> 375 376<h3>2.2.2: August 12 2000</h3> 377<ul> 378 <li>mostly bug fixes</li> 379 <li>started adding routines to access xml parser context options</li> 380</ul> 381 382<h3>2.2.1: July 21 2000</h3> 383<ul> 384 <li>a purely bug fixes release</li> 385 <li>fixed an encoding support problem when parsing from a memory block</li> 386 <li>fixed a DOCTYPE parsing problem</li> 387 <li>removed a bug in the function allowing to override the memory allocation 388 routines</li> 389</ul> 390 391<h3>2.2.0: July 14 2000</h3> 392<ul> 393 <li>applied a lot of portability fixes</li> 394 <li>better encoding support/cleanup and saving (content is now always 395 encoded in UTF-8)</li> 396 <li>the HTML parser now correctly handles encodings</li> 397 <li>added xmlHasProp()</li> 398 <li>fixed a serious problem with &#38;</li> 399 <li>propagated the fix to FTP client</li> 400 <li>cleanup, bugfixes, etc ...</li> 401 <li>Added a page about <a href="encoding.html">libxml Internationalization 402 support</a></li> 403</ul> 404 405<h3>1.8.9: July 9 2000</h3> 406<ul> 407 <li>fixed the spec the RPMs should be better</li> 408 <li>fixed a serious bug in the FTP implementation, released 1.8.9 to solve 409 rpmfind users problem</li> 410</ul> 411 412<h3>2.1.1: July 1 2000</h3> 413<ul> 414 <li>fixes a couple of bugs in the 2.1.0 packaging</li> 415 <li>improvements on the HTML parser</li> 416</ul> 417 418<h3>2.1.0 and 1.8.8: June 29 2000</h3> 419<ul> 420 <li>1.8.8 is mostly a comodity package for upgrading to libxml2 accoding to 421 <a href="upgrade.html">new instructions</a>. It fixes a nasty problem 422 about &#38; charref parsing</li> 423 <li>2.1.0 also ease the upgrade from libxml v1 to the recent version. it 424 also contains numerous fixes and enhancements: 425 <ul> 426 <li>added xmlStopParser() to stop parsing</li> 427 <li>improved a lot parsing speed when there is large CDATA blocs</li> 428 <li>includes XPath patches provided by Picdar Technology</li> 429 <li>tried to fix as much as possible DtD validation and namespace 430 related problems</li> 431 <li>output to a given encoding has been added/tested</li> 432 <li>lot of various fixes</li> 433 </ul> 434 </li> 435</ul> 436 437<h3>2.0.0: Apr 12 2000</h3> 438<ul> 439 <li>First public release of libxml2. If you are using libxml, it's a good 440 idea to check the 1.x to 2.x upgrade instructions. NOTE: while initally 441 scheduled for Apr 3 the relase occured only on Apr 12 due to massive 442 workload.</li> 443 <li>The include are now located under $prefix/include/libxml (instead of 444 $prefix/include/gnome-xml), they also are referenced by 445 <pre>#include <libxml/xxx.h></pre> 446 <p>instead of</p> 447 <pre>#include "xxx.h"</pre> 448 </li> 449 <li>a new URI module for parsing URIs and following strictly RFC 2396</li> 450 <li>the memory allocation routines used by libxml can now be overloaded 451 dynamically by using xmlMemSetup()</li> 452 <li>The previously CVS only tool tester has been renamed 453 <strong>xmllint</strong> and is now installed as part of the libxml2 454 package</li> 455 <li>The I/O interface has been revamped. There is now ways to plug in 456 specific I/O modules, either at the URI scheme detection level using 457 xmlRegisterInputCallbacks() or by passing I/O functions when creating a 458 parser context using xmlCreateIOParserCtxt()</li> 459 <li>there is a C preprocessor macro LIBXML_VERSION providing the version 460 number of the libxml module in use</li> 461 <li>a number of optional features of libxml can now be excluded at configure 462 time (FTP/HTTP/HTML/XPath/Debug)</li> 463</ul> 464 465<h3>2.0.0beta: Mar 14 2000</h3> 466<ul> 467 <li>This is a first Beta release of libxml version 2</li> 468 <li>It's available only from<a href="ftp://rpmfind.net/pub/libxml/"> 469 rpmfind.net FTP</a>, it's packaged as libxml2-2.0.0beta and available as 470 tar and RPMs</li> 471 <li>This version is now the head in the Gnome CVS base, the old one is 472 available under the tag LIB_XML_1_X</li> 473 <li>This includes a very large set of changes. Froma programmatic point of 474 view applications should not have to be modified too much, check the <a 475 href="upgrade.html">upgrade page</a></li> 476 <li>Some interfaces may changes (especially a bit about encoding).</li> 477 <li>the updates includes: 478 <ul> 479 <li>fix I18N support. ISO-Latin-x/UTF-8/UTF-16 (nearly) seems correctly 480 handled now</li> 481 <li>Better handling of entities, especially well formedness checking and 482 proper PEref extensions in external subsets</li> 483 <li>DTD conditional sections</li> 484 <li>Validation now correcly handle entities content</li> 485 <li><a href="http://rpmfind.net/tools/gdome/messages/0039.html">change 486 structures to accomodate DOM</a></li> 487 </ul> 488 </li> 489 <li>Serious progress were made toward compliance, <a 490 href="conf/result.html">here are the result of the test</a> against the 491 OASIS testsuite (except the japanese tests since I don't support that 492 encoding yet). This URL is rebuilt every couple of hours using the CVS 493 head version.</li> 494</ul> 495 496<h3>1.8.7: Mar 6 2000</h3> 497<ul> 498 <li>This is a bug fix release:</li> 499 <li>It is possible to disable the ignorable blanks heuristic used by 500 libxml-1.x, a new function xmlKeepBlanksDefault(0) will allow this. Note 501 that for adherence to XML spec, this behaviour will be disabled by default 502 in 2.x . The same function will allow to keep compatibility for old 503 code.</li> 504 <li>Blanks in <a> </a> constructs are not ignored anymore, 505 avoiding heuristic is really the Right Way :-\</li> 506 <li>The unchecked use of snprintf which was breaking libxml-1.8.6 507 compilation on some platforms has been fixed</li> 508 <li>nanoftp.c nanohttp.c: Fixed '#' and '?' stripping when processing 509 URIs</li> 510</ul> 511 512<h3>1.8.6: Jan 31 2000</h3> 513<ul> 514 <li>added a nanoFTP transport module, debugged until the new version of <a 515 href="http://rpmfind.net/linux/rpm2html/rpmfind.html">rpmfind</a> can use 516 it without troubles</li> 517</ul> 518 519<h3>1.8.5: Jan 21 2000</h3> 520<ul> 521 <li>adding APIs to parse a well balanced chunk of XML (production <a 522 href="http://www.w3.org/TR/REC-xml#NT-content">[43] content</a> of the XML 523 spec)</li> 524 <li>fixed a hideous bug in xmlGetProp pointed by Rune.Djurhuus@fast.no</li> 525 <li>Jody Goldberg <jgoldberg@home.com> provided another patch trying 526 to solve the zlib checks problems</li> 527 <li>The current state in gnome CVS base is expected to ship as 1.8.5 with 528 gnumeric soon</li> 529</ul> 530 531<h3>1.8.4: Jan 13 2000</h3> 532<ul> 533 <li>bug fixes, reintroduced xmlNewGlobalNs(), fixed xmlNewNs()</li> 534 <li>all exit() call should have been removed from libxml</li> 535 <li>fixed a problem with INCLUDE_WINSOCK on WIN32 platform</li> 536 <li>added newDocFragment()</li> 537</ul> 538 539<h3>1.8.3: Jan 5 2000</h3> 540<ul> 541 <li>a Push interface for the XML and HTML parsers</li> 542 <li>a shell-like interface to the document tree (try tester --shell :-)</li> 543 <li>lots of bug fixes and improvement added over XMas hollidays</li> 544 <li>fixed the DTD parsing code to work with the xhtml DTD</li> 545 <li>added xmlRemoveProp(), xmlRemoveID() and xmlRemoveRef()</li> 546 <li>Fixed bugs in xmlNewNs()</li> 547 <li>External entity loading code has been revamped, now it uses 548 xmlLoadExternalEntity(), some fix on entities processing were added</li> 549 <li>cleaned up WIN32 includes of socket stuff</li> 550</ul> 551 552<h3>1.8.2: Dec 21 1999</h3> 553<ul> 554 <li>I got another problem with includes and C++, I hope this issue is fixed 555 for good this time</li> 556 <li>Added a few tree modification functions: xmlReplaceNode, 557 xmlAddPrevSibling, xmlAddNextSibling, xmlNodeSetName and 558 xmlDocSetRootElement</li> 559 <li>Tried to improve the HTML output with help from <a 560 href="mailto:clahey@umich.edu">Chris Lahey</a></li> 561</ul> 562 563<h3>1.8.1: Dec 18 1999</h3> 564<ul> 565 <li>various patches to avoid troubles when using libxml with C++ compilers 566 the "namespace" keyword and C escaping in include files</li> 567 <li>a problem in one of the core macros IS_CHAR was corrected</li> 568 <li>fixed a bug introduced in 1.8.0 breaking default namespace processing, 569 and more specifically the Dia application</li> 570 <li>fixed a posteriori validation (validation after parsing, or by using a 571 Dtd not specified in the original document)</li> 572 <li>fixed a bug in</li> 573</ul> 574 575<h3>1.8.0: Dec 12 1999</h3> 576<ul> 577 <li>cleanup, especially memory wise</li> 578 <li>the parser should be more reliable, especially the HTML one, it should 579 not crash, whatever the input !</li> 580 <li>Integrated various patches, especially a speedup improvement for large 581 dataset from <a href="mailto:cnygard@bellatlantic.net">Carl Nygard</a>, 582 configure with --with-buffers to enable them.</li> 583 <li>attribute normalization, oops should have been added long ago !</li> 584 <li>attributes defaulted from Dtds should be available, xmlSetProp() now 585 does entities escapting by default.</li> 586</ul> 587 588<h3>1.7.4: Oct 25 1999</h3> 589<ul> 590 <li>Lots of HTML improvement</li> 591 <li>Fixed some errors when saving both XML and HTML</li> 592 <li>More examples, the regression tests should now look clean</li> 593 <li>Fixed a bug with contiguous charref</li> 594</ul> 595 596<h3>1.7.3: Sep 29 1999</h3> 597<ul> 598 <li>portability problems fixed</li> 599 <li>snprintf was used unconditionnally, leading to link problems on system 600 were it's not available, fixed</li> 601</ul> 602 603<h3>1.7.1: Sep 24 1999</h3> 604<ul> 605 <li>The basic type for strings manipulated by libxml has been renamed in 606 1.7.1 from <strong>CHAR</strong> to <strong>xmlChar</strong>. The reason 607 is that CHAR was conflicting with a predefined type on Windows. However on 608 non WIN32 environment, compatibility is provided by the way of a 609 <strong>#define </strong>.</li> 610 <li>Changed another error : the use of a structure field called errno, and 611 leading to troubles on platforms where it's a macro</li> 612</ul> 613 614<h3>1.7.0: sep 23 1999</h3> 615<ul> 616 <li>Added the ability to fetch remote DTD or parsed entities, see the <a 617 href="html/libxml-nanohttp.html">nanohttp</a> module.</li> 618 <li>Added an errno to report errors by another mean than a simple printf 619 like callback</li> 620 <li>Finished ID/IDREF support and checking when validation</li> 621 <li>Serious memory leaks fixed (there is now a <a 622 href="html/libxml-xmlmemory.html">memory wrapper</a> module)</li> 623 <li>Improvement of <a href="http://www.w3.org/TR/xpath">XPath</a> 624 implementation</li> 625 <li>Added an HTML parser front-end</li> 626</ul> 627 628<h2><a name="XML">XML</a></h2> 629 630<p><a href="http://www.w3.org/TR/REC-xml">XML is a standard</a> for 631markup-based structured documents. Here is <a name="example">an example XML 632document</a>:</p> 633<pre><?xml version="1.0"?> 634<EXAMPLE prop1="gnome is great" prop2="&amp; linux too"> 635 <head> 636 <title>Welcome to Gnome</title> 637 </head> 638 <chapter> 639 <title>The Linux adventure</title> 640 <p>bla bla bla ...</p> 641 <image href="linus.gif"/> 642 <p>...</p> 643 </chapter> 644</EXAMPLE></pre> 645 646<p>The first line specifies that it's an XML document and gives useful 647information about its encoding. Then the document is a text format whose 648structure is specified by tags between brackets. <strong>Each tag opened has 649to be closed</strong>. XML is pedantic about this. However, if a tag is empty 650(no content), a single tag can serve as both the opening and closing tag if it 651ends with <code>/></code> rather than with <code>></code>. Note that, 652for example, the image tag has no content (just an attribute) and is closed by 653ending the tag with <code>/></code>.</p> 654 655<p>XML can be applied sucessfully to a wide range of uses, from long term 656structured document maintenance (where it follows the steps of SGML) to simple 657data encoding mechanisms like configuration file formatting (glade), 658spreadsheets (gnumeric), or even shorter lived documents such as WebDAV where 659it is used to encode remote calls between a client and a server.</p> 660 661<h2><a name="XSLT">XSLT</a></h2> 662 663<p>Check <a href="http://xmlsoft.org/XSLT">the separate libxslt page</a></p> 664 665<p><a href="http://www.w3.org/TR/xslt">XSL Transformations</a>, is a language 666for transforming XML documents into other XML documents (or HTML/textual 667output).</p> 668 669<p>A separate library called libxslt is being built on top of libxml2. This 670module "libxslt" can be found in the Gnome CVS base too.</p> 671 672<p>You can check the <a 673href="http://cvs.gnome.org/lxr/source/libxslt/FEATURES">features</a> supported 674and the progresses on the <a 675href="http://cvs.gnome.org/lxr/source/libxslt/ChangeLog">Changelog</a></p> 676 677<h2>An overview of libxml architecture</h2> 678 679<p>Libxml is made of multiple components; some of them are optional, and most 680of the block interfaces are public. The main components are:</p> 681<ul> 682 <li>an Input/Output layer</li> 683 <li>FTP and HTTP client layers (optional)</li> 684 <li>an Internationalization layer managing the encodings support</li> 685 <li>a URI module</li> 686 <li>the XML parser and its basic SAX interface</li> 687 <li>an HTML parser using the same SAX interface (optional)</li> 688 <li>a SAX tree module to build an in-memory DOM representation</li> 689 <li>a tree module to manipulate the DOM representation</li> 690 <li>a validation module using the DOM representation (optional)</li> 691 <li>an XPath module for global lookup in a DOM representation 692 (optional)</li> 693 <li>a debug module (optional)</li> 694</ul> 695 696<p>Graphically this gives the following:</p> 697 698<p><img src="libxml.gif" alt="a graphical view of the various"></p> 699 700<p></p> 701 702<h2><a name="tree">The tree output</a></h2> 703 704<p>The parser returns a tree built during the document analysis. The value 705returned is an <strong>xmlDocPtr</strong> (i.e., a pointer to an 706<strong>xmlDoc</strong> structure). This structure contains information such 707as the file name, the document type, and a <strong>children</strong> pointer 708which is the root of the document (or more exactly the first child under the 709root which is the document). The tree is made of <strong>xmlNode</strong>s, 710chained in double-linked lists of siblings and with a children<->parent 711relationship. An xmlNode can also carry properties (a chain of xmlAttr 712structures). An attribute may have a value which is a list of TEXT or 713ENTITY_REF nodes.</p> 714 715<p>Here is an example (erroneous with respect to the XML spec since there 716should be only one ELEMENT under the root):</p> 717 718<p><img src="structure.gif" alt=" structure.gif "></p> 719 720<p>In the source package there is a small program (not installed by default) 721called <strong>xmllint</strong> which parses XML files given as argument and 722prints them back as parsed. This is useful for detecting errors both in XML 723code and in the XML parser itself. It has an option <strong>--debug</strong> 724which prints the actual in-memory structure of the document; here is the 725result with the <a href="#example">example</a> given before:</p> 726<pre>DOCUMENT 727version=1.0 728standalone=true 729 ELEMENT EXAMPLE 730 ATTRIBUTE prop1 731 TEXT 732 content=gnome is great 733 ATTRIBUTE prop2 734 ENTITY_REF 735 TEXT 736 content= linux too 737 ELEMENT head 738 ELEMENT title 739 TEXT 740 content=Welcome to Gnome 741 ELEMENT chapter 742 ELEMENT title 743 TEXT 744 content=The Linux adventure 745 ELEMENT p 746 TEXT 747 content=bla bla bla ... 748 ELEMENT image 749 ATTRIBUTE href 750 TEXT 751 content=linus.gif 752 ELEMENT p 753 TEXT 754 content=...</pre> 755 756<p>This should be useful for learning the internal representation model.</p> 757 758<h2><a name="interface">The SAX interface</a></h2> 759 760<p>Sometimes the DOM tree output is just too large to fit reasonably into 761memory. In that case (and if you don't expect to save back the XML document 762loaded using libxml), it's better to use the SAX interface of libxml. SAX is a 763<strong>callback-based interface</strong> to the parser. Before parsing, the 764application layer registers a customized set of callbacks which are called by 765the library as it progresses through the XML input.</p> 766 767<p>To get more detailed step-by-step guidance on using the SAX interface of 768libxml, see the <a 769href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">nice 770documentation</a>.written by <a href="mailto:james@daa.com.au">James 771Henstridge</a>.</p> 772 773<p>You can debug the SAX behaviour by using the <strong>testSAX</strong> 774program located in the gnome-xml module (it's usually not shipped in the 775binary packages of libxml, but you can find it in the tar source 776distribution). Here is the sequence of callbacks that would be reported by 777testSAX when parsing the example XML document shown earlier:</p> 778<pre>SAX.setDocumentLocator() 779SAX.startDocument() 780SAX.getEntity(amp) 781SAX.startElement(EXAMPLE, prop1='gnome is great', prop2='&amp; linux too') 782SAX.characters( , 3) 783SAX.startElement(head) 784SAX.characters( , 4) 785SAX.startElement(title) 786SAX.characters(Welcome to Gnome, 16) 787SAX.endElement(title) 788SAX.characters( , 3) 789SAX.endElement(head) 790SAX.characters( , 3) 791SAX.startElement(chapter) 792SAX.characters( , 4) 793SAX.startElement(title) 794SAX.characters(The Linux adventure, 19) 795SAX.endElement(title) 796SAX.characters( , 4) 797SAX.startElement(p) 798SAX.characters(bla bla bla ..., 15) 799SAX.endElement(p) 800SAX.characters( , 4) 801SAX.startElement(image, href='linus.gif') 802SAX.endElement(image) 803SAX.characters( , 4) 804SAX.startElement(p) 805SAX.characters(..., 3) 806SAX.endElement(p) 807SAX.characters( , 3) 808SAX.endElement(chapter) 809SAX.characters( , 1) 810SAX.endElement(EXAMPLE) 811SAX.endDocument()</pre> 812 813<p>Most of the other interfaces of libxml are based on the DOM tree-building 814facility, so nearly everything up to the end of this document presupposes the 815use of the standard DOM tree build. Note that the DOM tree itself is built by 816a set of registered default callbacks, without internal specific 817interface.</p> 818 819<h2><a name="library">The XML library interfaces</a></h2> 820 821<p>This section is directly intended to help programmers getting bootstrapped 822using the XML library from the C language. It is not intended to be extensive. 823I hope the automatically generated documents will provide the completeness 824required, but as a separate set of documents. The interfaces of the XML 825library are by principle low level, there is nearly zero abstraction. Those 826interested in a higher level API should <a href="#DOM">look at DOM</a>.</p> 827 828<p>The <a href="html/libxml-parser.html">parser interfaces for XML</a> are 829separated from the <a href="html/libxml-htmlparser.html">HTML parser 830interfaces</a>. Let's have a look at how the XML parser can be called:</p> 831 832<h3><a name="Invoking">Invoking the parser : the pull method</a></h3> 833 834<p>Usually, the first thing to do is to read an XML input. The parser accepts 835documents either from in-memory strings or from files. The functions are 836defined in "parser.h":</p> 837<dl> 838 <dt><code>xmlDocPtr xmlParseMemory(char *buffer, int size);</code></dt> 839 <dd><p>Parse a null-terminated string containing the document.</p> 840 </dd> 841</dl> 842<dl> 843 <dt><code>xmlDocPtr xmlParseFile(const char *filename);</code></dt> 844 <dd><p>Parse an XML document contained in a (possibly compressed) 845 file.</p> 846 </dd> 847</dl> 848 849<p>The parser returns a pointer to the document structure (or NULL in case of 850failure).</p> 851 852<h3 id="Invoking1">Invoking the parser: the push method</h3> 853 854<p>In order for the application to keep the control when the document is being 855fetched (which is common for GUI based programs) libxml provides a push 856interface, too, as of version 1.8.3. Here are the interface functions:</p> 857<pre>xmlParserCtxtPtr xmlCreatePushParserCtxt(xmlSAXHandlerPtr sax, 858 void *user_data, 859 const char *chunk, 860 int size, 861 const char *filename); 862int xmlParseChunk (xmlParserCtxtPtr ctxt, 863 const char *chunk, 864 int size, 865 int terminate);</pre> 866 867<p>and here is a simple example showing how to use the interface:</p> 868<pre> FILE *f; 869 870 f = fopen(filename, "r"); 871 if (f != NULL) { 872 int res, size = 1024; 873 char chars[1024]; 874 xmlParserCtxtPtr ctxt; 875 876 res = fread(chars, 1, 4, f); 877 if (res > 0) { 878 ctxt = xmlCreatePushParserCtxt(NULL, NULL, 879 chars, res, filename); 880 while ((res = fread(chars, 1, size, f)) > 0) { 881 xmlParseChunk(ctxt, chars, res, 0); 882 } 883 xmlParseChunk(ctxt, chars, 0, 1); 884 doc = ctxt->myDoc; 885 xmlFreeParserCtxt(ctxt); 886 } 887 }</pre> 888 889<p>The HTML parser embedded into libxml also has a push interface; the 890functions are just prefixed by "html" rather than "xml".</p> 891 892<h3 id="Invoking2">Invoking the parser: the SAX interface</h3> 893 894<p>The tree-building interface makes the parser memory-hungry, first loading 895the document in memory and then building the tree itself. Reading a document 896without building the tree is possible using the SAX interfaces (see SAX.h and 897<a href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">James 898Henstridge's documentation</a>). Note also that the push interface can be 899limited to SAX: just use the two first arguments of 900<code>xmlCreatePushParserCtxt()</code>.</p> 901 902<h3><a name="Building">Building a tree from scratch</a></h3> 903 904<p>The other way to get an XML tree in memory is by building it. Basically 905there is a set of functions dedicated to building new elements. (These are 906also described in <libxml/tree.h>.) For example, here is a piece of code 907that produces the XML document used in the previous examples:</p> 908<pre> #include <libxml/tree.h> 909 xmlDocPtr doc; 910 xmlNodePtr tree, subtree; 911 912 doc = xmlNewDoc("1.0"); 913 doc->children = xmlNewDocNode(doc, NULL, "EXAMPLE", NULL); 914 xmlSetProp(doc->children, "prop1", "gnome is great"); 915 xmlSetProp(doc->children, "prop2", "& linux too"); 916 tree = xmlNewChild(doc->children, NULL, "head", NULL); 917 subtree = xmlNewChild(tree, NULL, "title", "Welcome to Gnome"); 918 tree = xmlNewChild(doc->children, NULL, "chapter", NULL); 919 subtree = xmlNewChild(tree, NULL, "title", "The Linux adventure"); 920 subtree = xmlNewChild(tree, NULL, "p", "bla bla bla ..."); 921 subtree = xmlNewChild(tree, NULL, "image", NULL); 922 xmlSetProp(subtree, "href", "linus.gif");</pre> 923 924<p>Not really rocket science ...</p> 925 926<h3><a name="Traversing">Traversing the tree</a></h3> 927 928<p>Basically by <a href="html/libxml-tree.html">including "tree.h"</a> your 929code has access to the internal structure of all the elements of the tree. The 930names should be somewhat simple like <strong>parent</strong>, 931<strong>children</strong>, <strong>next</strong>, <strong>prev</strong>, 932<strong>properties</strong>, etc... For example, still with the previous 933example:</p> 934<pre><code>doc->children->children->children</code></pre> 935 936<p>points to the title element,</p> 937<pre>doc->children->children->next->children->children</pre> 938 939<p>points to the text node containing the chapter title "The Linux 940adventure".</p> 941 942<p><strong>NOTE</strong>: XML allows <em>PI</em>s and <em>comments</em> to be 943present before the document root, so <code>doc->children</code> may point 944to an element which is not the document Root Element; a function 945<code>xmlDocGetRootElement()</code> was added for this purpose.</p> 946 947<h3><a name="Modifying">Modifying the tree</a></h3> 948 949<p>Functions are provided for reading and writing the document content. Here 950is an excerpt from the <a href="html/libxml-tree.html">tree API</a>:</p> 951<dl> 952 <dt><code>xmlAttrPtr xmlSetProp(xmlNodePtr node, const xmlChar *name, const 953 xmlChar *value);</code></dt> 954 <dd><p>This sets (or changes) an attribute carried by an ELEMENT node. The 955 value can be NULL.</p> 956 </dd> 957</dl> 958<dl> 959 <dt><code>const xmlChar *xmlGetProp(xmlNodePtr node, const xmlChar 960 *name);</code></dt> 961 <dd><p>This function returns a pointer to new copy of the property 962 content. Note that the user must deallocate the result.</p> 963 </dd> 964</dl> 965 966<p>Two functions are provided for reading and writing the text associated with 967elements:</p> 968<dl> 969 <dt><code>xmlNodePtr xmlStringGetNodeList(xmlDocPtr doc, const xmlChar 970 *value);</code></dt> 971 <dd><p>This function takes an "external" string and converts it to one 972 text node or possibly to a list of entity and text nodes. All 973 non-predefined entity references like &Gnome; will be stored 974 internally as entity nodes, hence the result of the function may not be 975 a single node.</p> 976 </dd> 977</dl> 978<dl> 979 <dt><code>xmlChar *xmlNodeListGetString(xmlDocPtr doc, xmlNodePtr list, int 980 inLine);</code></dt> 981 <dd><p>This function is the inverse of 982 <code>xmlStringGetNodeList()</code>. It generates a new string 983 containing the content of the text and entity nodes. Note the extra 984 argument inLine. If this argument is set to 1, the function will expand 985 entity references. For example, instead of returning the &Gnome; 986 XML encoding in the string, it will substitute it with its value (say, 987 "GNU Network Object Model Environment").</p> 988 </dd> 989</dl> 990 991<h3><a name="Saving">Saving a tree</a></h3> 992 993<p>Basically 3 options are possible:</p> 994<dl> 995 <dt><code>void xmlDocDumpMemory(xmlDocPtr cur, xmlChar**mem, int 996 *size);</code></dt> 997 <dd><p>Returns a buffer into which the document has been saved.</p> 998 </dd> 999</dl> 1000<dl> 1001 <dt><code>extern void xmlDocDump(FILE *f, xmlDocPtr doc);</code></dt> 1002 <dd><p>Dumps a document to an open file descriptor.</p> 1003 </dd> 1004</dl> 1005<dl> 1006 <dt><code>int xmlSaveFile(const char *filename, xmlDocPtr cur);</code></dt> 1007 <dd><p>Saves the document to a file. In this case, the compression 1008 interface is triggered if it has been turned on.</p> 1009 </dd> 1010</dl> 1011 1012<h3><a name="Compressio">Compression</a></h3> 1013 1014<p>The library transparently handles compression when doing file-based 1015accesses. The level of compression on saves can be turned on either globally 1016or individually for one file:</p> 1017<dl> 1018 <dt><code>int xmlGetDocCompressMode (xmlDocPtr doc);</code></dt> 1019 <dd><p>Gets the document compression ratio (0-9).</p> 1020 </dd> 1021</dl> 1022<dl> 1023 <dt><code>void xmlSetDocCompressMode (xmlDocPtr doc, int mode);</code></dt> 1024 <dd><p>Sets the document compression ratio.</p> 1025 </dd> 1026</dl> 1027<dl> 1028 <dt><code>int xmlGetCompressMode(void);</code></dt> 1029 <dd><p>Gets the default compression ratio.</p> 1030 </dd> 1031</dl> 1032<dl> 1033 <dt><code>void xmlSetCompressMode(int mode);</code></dt> 1034 <dd><p>Sets the default compression ratio.</p> 1035 </dd> 1036</dl> 1037 1038<h2><a name="Entities">Entities or no entities</a></h2> 1039 1040<p>Entities in principle are similar to simple C macros. An entity defines an 1041abbreviation for a given string that you can reuse many times throughout the 1042content of your document. Entities are especially useful when a given string 1043may occur frequently within a document, or to confine the change needed to a 1044document to a restricted area in the internal subset of the document (at the 1045beginning). Example:</p> 1046<pre>1 <?xml version="1.0"?> 10472 <!DOCTYPE EXAMPLE SYSTEM "example.dtd" [ 10483 <!ENTITY xml "Extensible Markup Language"> 10494 ]> 10505 <EXAMPLE> 10516 &xml; 10527 </EXAMPLE></pre> 1053 1054<p>Line 3 declares the xml entity. Line 6 uses the xml entity, by prefixing 1055its name with '&' and following it by ';' without any spaces added. There 1056are 5 predefined entities in libxml allowing you to escape charaters with 1057predefined meaning in some parts of the xml document content: 1058<strong>&lt;</strong> for the character '<', <strong>&gt;</strong> 1059for the character '>', <strong>&apos;</strong> for the character ''', 1060<strong>&quot;</strong> for the character '"', and 1061<strong>&amp;</strong> for the character '&'.</p> 1062 1063<p>One of the problems related to entities is that you may want the parser to 1064substitute an entity's content so that you can see the replacement text in 1065your application. Or you may prefer to keep entity references as such in the 1066content to be able to save the document back without losing this usually 1067precious information (if the user went through the pain of explicitly defining 1068entities, he may have a a rather negative attitude if you blindly susbtitute 1069them as saving time). The <a 1070href="html/libxml-parser.html#XMLSUBSTITUTEENTITIESDEFAULT">xmlSubstituteEntitiesDefault()</a> 1071function allows you to check and change the behaviour, which is to not 1072substitute entities by default.</p> 1073 1074<p>Here is the DOM tree built by libxml for the previous document in the 1075default case:</p> 1076<pre>/gnome/src/gnome-xml -> /xmllint --debug test/ent1 1077DOCUMENT 1078version=1.0 1079 ELEMENT EXAMPLE 1080 TEXT 1081 content= 1082 ENTITY_REF 1083 INTERNAL_GENERAL_ENTITY xml 1084 content=Extensible Markup Language 1085 TEXT 1086 content=</pre> 1087 1088<p>And here is the result when substituting entities:</p> 1089<pre>/gnome/src/gnome-xml -> /tester --debug --noent test/ent1 1090DOCUMENT 1091version=1.0 1092 ELEMENT EXAMPLE 1093 TEXT 1094 content= Extensible Markup Language</pre> 1095 1096<p>So, entities or no entities? Basically, it depends on your use case. I 1097suggest that you keep the non-substituting default behaviour and avoid using 1098entities in your XML document or data if you are not willing to handle the 1099entity references elements in the DOM tree.</p> 1100 1101<p>Note that at save time libxml enforces the conversion of the predefined 1102entities where necessary to prevent well-formedness problems, and will also 1103transparently replace those with chars (i.e. it will not generate entity 1104reference elements in the DOM tree or call the reference() SAX callback when 1105finding them in the input).</p> 1106 1107<p><span style="background-color: #FF0000">WARNING</span>: handling entities 1108on top of the libxml SAX interface is difficult!!! If you plan to use 1109non-predefined entities in your documents, then the learning cuvre to handle 1110then using the SAX API may be long. If you plan to use complex documents, I 1111strongly suggest you consider using the DOM interface instead and let libxml 1112deal with the complexity rather than trying to do it yourself.</p> 1113 1114<h2><a name="Namespaces">Namespaces</a></h2> 1115 1116<p>The libxml library implements <a 1117href="http://www.w3.org/TR/REC-xml-names/">XML namespaces</a> support by 1118recognizing namespace contructs in the input, and does namespace lookup 1119automatically when building the DOM tree. A namespace declaration is 1120associated with an in-memory structure and all elements or attributes within 1121that namespace point to it. Hence testing the namespace is a simple and fast 1122equality operation at the user level.</p> 1123 1124<p>I suggest that people using libxml use a namespace, and declare it in the 1125root element of their document as the default namespace. Then they don't need 1126to use the prefix in the content but we will have a basis for future semantic 1127refinement and merging of data from different sources. This doesn't increase 1128the size of the XML output significantly, but significantly increases its 1129value in the long-term. Example:</p> 1130<pre><mydoc xmlns="http://mydoc.example.org/schemas/"> 1131 <elem1>...</elem1> 1132 <elem2>...</elem2> 1133</mydoc></pre> 1134 1135<p>The namespace value has to be an absolute URL, but the URL doesn't have to 1136point to any existing resource on the Web. It will bind all the element and 1137atributes with that URL. I suggest to use an URL within a domain you control, 1138and that the URL should contain some kind of version information if possible. 1139For example, <code>"http://www.gnome.org/gnumeric/1.0/"</code> is a good 1140namespace scheme.</p> 1141 1142<p>Then when you load a file, make sure that a namespace carrying the 1143version-independent prefix is installed on the root element of your document, 1144and if the version information don't match something you know, warn the user 1145and be liberal in what you accept as the input. Also do *not* try to base 1146namespace checking on the prefix value. <foo:text> may be exactly the 1147same as <bar:text> in another document. What really matters is the URI 1148associated with the element or the attribute, not the prefix string (which is 1149just a shortcut for the full URI). In libxml, element and attributes have an 1150<code>ns</code> field pointing to an xmlNs structure detailing the namespace 1151prefix and its URI.</p> 1152 1153<p>@@Interfaces@@</p> 1154 1155<p>@@Examples@@</p> 1156 1157<p>Usually people object to using namespaces together with validity checking. 1158I will try to make sure that using namespaces won't break validity checking, 1159so even if you plan to use or currently are using validation I strongly 1160suggest adding namespaces to your document. A default namespace scheme 1161<code>xmlns="http://...."</code> should not break validity even on less 1162flexible parsers. Using namespaces to mix and differentiate content coming 1163from multiple DTDs will certainly break current validation schemes. I will try 1164to provide ways to do this, but this may not be portable or standardized.</p> 1165 1166<h2><a name="Validation">Validation, or are you afraid of DTDs ?</a></h2> 1167 1168<p>Well what is validation and what is a DTD ?</p> 1169 1170<p>Validation is the process of checking a document against a set of 1171construction rules; a <strong>DTD</strong> (Document Type Definition) is such 1172a set of rules.</p> 1173 1174<p>The validation process and building DTDs are the two most difficult parts 1175of the XML life cycle. Briefly a DTD defines all the possibles element to be 1176found within your document, what is the formal shape of your document tree (by 1177defining the allowed content of an element, either text, a regular expression 1178for the allowed list of children, or mixed content i.e. both text and 1179children). The DTD also defines the allowed attributes for all elements and 1180the types of the attributes. For more detailed information, I suggest that you 1181read the related parts of the XML specification, the examples found under 1182gnome-xml/test/valid/dtd and any of the large number of books available on 1183XML. The dia example in gnome-xml/test/valid should be both simple and 1184complete enough to allow you to build your own.</p> 1185 1186<p>A word of warning, building a good DTD which will fit the needs of your 1187application in the long-term is far from trivial; however, the extra level of 1188quality it can ensure is well worth the price for some sets of applications or 1189if you already have already a DTD defined for your application field.</p> 1190 1191<p>The validation is not completely finished but in a (very IMHO) usable 1192state. Until a real validation interface is defined the way to do it is to 1193define and set the <strong>xmlDoValidityCheckingDefaultValue</strong> external 1194variable to 1, this will of course be changed at some point:</p> 1195 1196<p>extern int xmlDoValidityCheckingDefaultValue;</p> 1197 1198<p>...</p> 1199 1200<p>xmlDoValidityCheckingDefaultValue = 1;</p> 1201 1202<p></p> 1203 1204<p>To handle external entities, use the function 1205<strong>xmlSetExternalEntityLoader</strong>(xmlExternalEntityLoader f); to 1206link in you HTTP/FTP/Entities database library to the standard libxml 1207core.</p> 1208 1209<p>@@interfaces@@</p> 1210 1211<h2><a name="DOM"></a><a name="Principles">DOM Principles</a></h2> 1212 1213<p><a href="http://www.w3.org/DOM/">DOM</a> stands for the <em>Document Object 1214Model</em>; this is an API for accessing XML or HTML structured documents. 1215Native support for DOM in Gnome is on the way (module gnome-dom), and will be 1216based on gnome-xml. This will be a far cleaner interface to manipulate XML 1217files within Gnome since it won't expose the internal structure. DOM defines a 1218set of IDL (or Java) interfaces allowing you to traverse and manipulate a 1219document. The DOM library will allow accessing and modifying "live" documents 1220present in other programs like this:</p> 1221 1222<p><img src="DOM.gif" alt=" DOM.gif "></p> 1223 1224<p>This should help greatly doing things like modifying a gnumeric spreadsheet 1225embedded in a GWP document for example.</p> 1226 1227<p>The current DOM implementation on top of libxml is the <a 1228href="http://cvs.gnome.org/lxr/source/gdome/">gdome Gnome module</a>, this is 1229a full DOM interface, thanks to <a href="mailto:raph@levien.com">Raph 1230Levien</a>.</p> 1231 1232<p>The gnome-dom module in the Gnome CVS base is obsolete</p> 1233 1234<h2><a name="Example"></a><a name="real">A real example</a></h2> 1235 1236<p>Here is a real size example, where the actual content of the application 1237data is not kept in the DOM tree but uses internal structures. It is based on 1238a proposal to keep a database of jobs related to Gnome, with an XML based 1239storage structure. Here is an <a href="gjobs.xml">XML encoded jobs 1240base</a>:</p> 1241<pre><?xml version="1.0"?> 1242<gjob:Helping xmlns:gjob="http://www.gnome.org/some-location"> 1243 <gjob:Jobs> 1244 1245 <gjob:Job> 1246 <gjob:Project ID="3"/> 1247 <gjob:Application>GBackup</gjob:Application> 1248 <gjob:Category>Development</gjob:Category> 1249 1250 <gjob:Update> 1251 <gjob:Status>Open</gjob:Status> 1252 <gjob:Modified>Mon, 07 Jun 1999 20:27:45 -0400 MET DST</gjob:Modified> 1253 <gjob:Salary>USD 0.00</gjob:Salary> 1254 </gjob:Update> 1255 1256 <gjob:Developers> 1257 <gjob:Developer> 1258 </gjob:Developer> 1259 </gjob:Developers> 1260 1261 <gjob:Contact> 1262 <gjob:Person>Nathan Clemons</gjob:Person> 1263 <gjob:Email>nathan@windsofstorm.net</gjob:Email> 1264 <gjob:Company> 1265 </gjob:Company> 1266 <gjob:Organisation> 1267 </gjob:Organisation> 1268 <gjob:Webpage> 1269 </gjob:Webpage> 1270 <gjob:Snailmail> 1271 </gjob:Snailmail> 1272 <gjob:Phone> 1273 </gjob:Phone> 1274 </gjob:Contact> 1275 1276 <gjob:Requirements> 1277 The program should be released as free software, under the GPL. 1278 </gjob:Requirements> 1279 1280 <gjob:Skills> 1281 </gjob:Skills> 1282 1283 <gjob:Details> 1284 A GNOME based system that will allow a superuser to configure 1285 compressed and uncompressed files and/or file systems to be backed 1286 up with a supported media in the system. This should be able to 1287 perform via find commands generating a list of files that are passed 1288 to tar, dd, cpio, cp, gzip, etc., to be directed to the tape machine 1289 or via operations performed on the filesystem itself. Email 1290 notification and GUI status display very important. 1291 </gjob:Details> 1292 1293 </gjob:Job> 1294 1295 </gjob:Jobs> 1296</gjob:Helping></pre> 1297 1298<p>While loading the XML file into an internal DOM tree is a matter of calling 1299only a couple of functions, browsing the tree to gather the ata and generate 1300the internal structures is harder, and more error prone.</p> 1301 1302<p>The suggested principle is to be tolerant with respect to the input 1303structure. For example, the ordering of the attributes is not significant, the 1304XML specification is clear about it. It's also usually a good idea not to 1305depend on the order of the children of a given node, unless it really makes 1306things harder. Here is some code to parse the information for a person:</p> 1307<pre>/* 1308 * A person record 1309 */ 1310typedef struct person { 1311 char *name; 1312 char *email; 1313 char *company; 1314 char *organisation; 1315 char *smail; 1316 char *webPage; 1317 char *phone; 1318} person, *personPtr; 1319 1320/* 1321 * And the code needed to parse it 1322 */ 1323personPtr parsePerson(xmlDocPtr doc, xmlNsPtr ns, xmlNodePtr cur) { 1324 personPtr ret = NULL; 1325 1326DEBUG("parsePerson\n"); 1327 /* 1328 * allocate the struct 1329 */ 1330 ret = (personPtr) malloc(sizeof(person)); 1331 if (ret == NULL) { 1332 fprintf(stderr,"out of memory\n"); 1333 return(NULL); 1334 } 1335 memset(ret, 0, sizeof(person)); 1336 1337 /* We don't care what the top level element name is */ 1338 cur = cur->xmlChildrenNode; 1339 while (cur != NULL) { 1340 if ((!strcmp(cur->name, "Person")) && (cur->ns == ns)) 1341 ret->name = xmlNodeListGetString(doc, cur->xmlChildrenNode, 1); 1342 if ((!strcmp(cur->name, "Email")) && (cur->ns == ns)) 1343 ret->email = xmlNodeListGetString(doc, cur->xmlChildrenNode, 1); 1344 cur = cur->next; 1345 } 1346 1347 return(ret); 1348}</pre> 1349 1350<p>Here are a couple of things to notice:</p> 1351<ul> 1352 <li>Usually a recursive parsing style is the more convenient one: XML data 1353 is by nature subject to repetitive constructs and usually exibits highly 1354 stuctured patterns.</li> 1355 <li>The two arguments of type <em>xmlDocPtr</em> and <em>xmlNsPtr</em>, i.e. 1356 the pointer to the global XML document and the namespace reserved to the 1357 application. Document wide information are needed for example to decode 1358 entities and it's a good coding practice to define a namespace for your 1359 application set of data and test that the element and attributes you're 1360 analyzing actually pertains to your application space. This is done by a 1361 simple equality test (cur->ns == ns).</li> 1362 <li>To retrieve text and attributes value, you can use the function 1363 <em>xmlNodeListGetString</em> to gather all the text and entity reference 1364 nodes generated by the DOM output and produce an single text string.</li> 1365</ul> 1366 1367<p>Here is another piece of code used to parse another level of the 1368structure:</p> 1369<pre>#include <libxml/tree.h> 1370/* 1371 * a Description for a Job 1372 */ 1373typedef struct job { 1374 char *projectID; 1375 char *application; 1376 char *category; 1377 personPtr contact; 1378 int nbDevelopers; 1379 personPtr developers[100]; /* using dynamic alloc is left as an exercise */ 1380} job, *jobPtr; 1381 1382/* 1383 * And the code needed to parse it 1384 */ 1385jobPtr parseJob(xmlDocPtr doc, xmlNsPtr ns, xmlNodePtr cur) { 1386 jobPtr ret = NULL; 1387 1388DEBUG("parseJob\n"); 1389 /* 1390 * allocate the struct 1391 */ 1392 ret = (jobPtr) malloc(sizeof(job)); 1393 if (ret == NULL) { 1394 fprintf(stderr,"out of memory\n"); 1395 return(NULL); 1396 } 1397 memset(ret, 0, sizeof(job)); 1398 1399 /* We don't care what the top level element name is */ 1400 cur = cur->xmlChildrenNode; 1401 while (cur != NULL) { 1402 1403 if ((!strcmp(cur->name, "Project")) && (cur->ns == ns)) { 1404 ret->projectID = xmlGetProp(cur, "ID"); 1405 if (ret->projectID == NULL) { 1406 fprintf(stderr, "Project has no ID\n"); 1407 } 1408 } 1409 if ((!strcmp(cur->name, "Application")) && (cur->ns == ns)) 1410 ret->application = xmlNodeListGetString(doc, cur->xmlChildrenNode, 1); 1411 if ((!strcmp(cur->name, "Category")) && (cur->ns == ns)) 1412 ret->category = xmlNodeListGetString(doc, cur->xmlChildrenNode, 1); 1413 if ((!strcmp(cur->name, "Contact")) && (cur->ns == ns)) 1414 ret->contact = parsePerson(doc, ns, cur); 1415 cur = cur->next; 1416 } 1417 1418 return(ret); 1419}</pre> 1420 1421<p>Once you are used to it, writing this kind of code is quite simple, but 1422boring. Ultimately, it could be possble to write stubbers taking either C data 1423structure definitions, a set of XML examples or an XML DTD and produce the 1424code needed to import and export the content between C data and XML storage. 1425This is left as an exercise to the reader :-)</p> 1426 1427<p>Feel free to use <a href="example/gjobread.c">the code for the full C 1428parsing example</a> as a template, it is also available with Makefile in the 1429Gnome CVS base under gnome-xml/example</p> 1430 1431<h2><a name="Contributi">Contributions</a></h2> 1432<ul> 1433 <li><a href="mailto:ari@lusis.org">Ari Johnson</a> provides a C++ wrapper 1434 for libxml: 1435 <p>Website: <a 1436 href="http://lusis.org/~ari/xml++/">http://lusis.org/~ari/xml++/</a></p> 1437 <p>Download: <a 1438 href="http://lusis.org/~ari/xml++/libxml++.tar.gz">http://lusis.org/~ari/xml++/libxml++.tar.gz</a></p> 1439 </li> 1440 <li><a href="mailto:doolin@cs.utk.edu">David Doolin</a> provides a 1441 precompiled Windows version 1442 <p><a 1443 href="http://www.ce.berkeley.edu/~doolin/code/libxmlwin32/">http://www.ce.berkeley.edu/~doolin/code/libxmlwin32/</a></p> 1444 </li> 1445 <li><a href="mailto:fnatter@gmx.net">Felix Natter</a> provided <a 1446 href="libxml-doc.el">an emacs module</a> to lookup libxml functions 1447 documentation</li> 1448 <li><a href="mailto:sherwin@nlm.nih.gov">Ziying Sherwin</a> provided <a 1449 href="http://xmlsoft.org/messages/0488.html">man pages</a> (not yet 1450 integrated in the distribution)</li> 1451</ul> 1452 1453<p></p> 1454 1455<p><a href="mailto:Daniel.Veillard@w3.org">Daniel Veillard</a></p> 1456 1457<p>$Id: xml.html,v 1.71 2001/03/01 17:28:58 veillard Exp $</p> 1458</body> 1459</html> 1460
