Edit
kc3-lang/libxml2/doc/xml.html
Daniel Veillard
- doc/xml.html
-
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <title>The XML C library for Gnome</title> <meta name="GENERATOR" content="amaya V5.0"> <meta http-equiv="Content-Type" content="text/html"> </head> <body bgcolor="#ffffff"> <p><a href="http://www.gnome.org/"><img src="smallfootonly.gif" alt="Gnome Logo"></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo"></a><a href="http://www.redhat.com"><img src="redhat.gif" alt="Red Hat Logo"></a></p> <h1 align="center">The XML C library for Gnome</h1> <h2 style="text-align: center">libxml, a.k.a. gnome-xml</h2> <p></p> <ul> <li><a href="#Introducti">Introduction</a></li> <li><a href="#Documentat">Documentation</a></li> <li><a href="#Reporting">Reporting bugs and getting help</a></li> <li><a href="#help">how to help</a></li> <li><a href="#Downloads">Downloads</a></li> <li><a href="#News">News</a></li> <li><a href="#XML">XML</a></li> <li><a href="#XSLT">XSLT</a></li> <li><a href="#tree">The tree output</a></li> <li><a href="#interface">The SAX interface</a></li> <li><a href="#library">The XML library interfaces</a> <ul> <li><a href="#Invoking">Invoking the parser: the pull way</a></li> <li><a href="#Invoking">Invoking the parser: the push way</a></li> <li><a href="#Invoking2">Invoking the parser: the SAX interface</a></li> <li><a href="#Building">Building a tree from scratch</a></li> <li><a href="#Traversing">Traversing the tree</a></li> <li><a href="#Modifying">Modifying the tree</a></li> <li><a href="#Saving">Saving the tree</a></li> <li><a href="#Compressio">Compression</a></li> </ul> </li> <li><a href="#Entities">Entities or no entities</a></li> <li><a href="#Namespaces">Namespaces</a></li> <li><a href="#Validation">Validation</a></li> <li><a href="#Principles">DOM principles</a></li> <li><a href="#real">A real example</a></li> <li><a href="#Contributi">Contributions</a></li> </ul> <p>Separate documents:</p> <ul> <li><a href="upgrade.html">upgrade instructions for migrating to libxml2</a></li> <li><a href="encoding.html">libxml Internationalization support</a></li> <li><a href="xmlio.html">libxml Input/Output interfaces</a></li> <li><a href="xmlmem.html">libxml Memory interfaces</a></li> <li><a href="xmldtd.html">a short introduction about DTDs and libxml</a></li> <li><a href="http://xmlsoft.org/XSLT/">the libxslt page</a></li> <li><a href="http://www.cs.unibo.it/~casarini/gdome2/">the gdome2 page: a standard DOM interface for libxml2</a></li> </ul> <h2><a name="Introducti">Introduction</a></h2> <p>This document describes libxml, the <a href="http://www.w3.org/XML/">XML</a> C library developped for the <a href="http://www.gnome.org/">Gnome</a> project. <a href="http://www.w3.org/XML/">XML is a standard</a> for building tag-based structured documents/data.</p> <p>Here are some key points about libxml:</p> <ul> <li>Libxml exports Push and Pull type parser interfaces for both XML and HTML.</li> <li>Libxml can do DTD validation at parse time, using a parsed document instance, or with an arbitrary DTD.</li> <li>Libxml now includes nearly complete <a href="http://www.w3.org/TR/xpath">XPath</a>, <a href="http://www.w3.org/TR/xptr">XPointer</a> and <a href="http://www.w3.org/TR/xinclude">XInclude</a> implementations.</li> <li>It is written in plain C, making as few assumptions as possible, and sticking closely to ANSI C/POSIX for easy embedding. Works on Linux/Unix/Windows, ported to a number of other platforms.</li> <li>Basic support for HTTP and FTP client allowing aplications to fetch remote resources</li> <li>The design is modular, most of the extensions can be compiled out.</li> <li>The internal document repesentation is as close as possible to the <a href="http://www.w3.org/DOM/">DOM</a> interfaces.</li> <li>Libxml also has a <a href="http://www.megginson.com/SAX/index.html">SAX like interface</a>; the interface is designed to be compatible with <a href="http://www.jclark.com/xml/expat.html">Expat</a>.</li> <li>This library is released both under the <a href="http://www.w3.org/Consortium/Legal/copyright-software-19980720.html">W3C IPR</a> and the <a href="http://www.gnu.org/copyleft/lesser.html">GNU LGPL</a>. Use either at your convenience, basically this should make everybody happy, if not, drop me a mail.</li> </ul> <p>Warning: unless you are forced to because your application links with a Gnome library requiring it, <strong><span style="background-color: #FF0000">Do Not Use libxml1</span></strong>, use libxml2</p> <h2><a name="Documentat">Documentation</a></h2> <p>There are some on-line resources about using libxml:</p> <ol> <li>Check the <a href="FAQ.html">FAQ</a></li> <li>Check the <a href="http://xmlsoft.org/html/libxml-lib.html">extensive documentation</a> automatically extracted from code comments (using <a href="http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&dir=gtk-doc">gtk doc</a>).</li> <li>Look at the documentation about <a href="encoding.html">libxml internationalization support</a></li> <li>This page provides a global overview and <a href="#real">some examples</a> on how to use libxml.</li> <li><a href="mailto:james@daa.com.au">James Henstridge</a> wrote <a href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">some nice documentation</a> explaining how to use the libxml SAX interface.</li> <li>George Lebl wrote <a href="http://www-4.ibm.com/software/developer/library/gnome3/">an article for IBM developerWorks</a> about using libxml.</li> <li>Check <a href="http://cvs.gnome.org/lxr/source/gnome-xml/TODO">the TODO file</a></li> <li>Read the <a href="upgrade.html">1.x to 2.x upgrade path</a>. If you are starting a new project using libxml you should really use the 2.x version.</li> <li>And don't forget to look at the <a href="/messages/">mailing-list archive</a>.</li> </ol> <h2><a name="Reporting">Reporting bugs and getting help</a></h2> <p>Well, bugs or missing features are always possible, and I will make a point of fixing them in a timely fashion. The best way to report a bug is to use the <a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml">Gnome bug tracking database</a> (make sure to use the "libxml" module name). I look at reports there regularly and it's good to have a reminder when a bug is still open. Check the <a href="http://bugzilla.gnome.org/bugwritinghelp.html">instructions on reporting bugs</a> and be sure to specify that the bug is for the package libxml.</p> <p>There is also a mailing-list <a href="mailto:xml@gnome.org">xml@gnome.org</a> for libxml, with an <a href="http://mail.gnome.org/archives/xml/">on-line archive</a> (<a href="http://xmlsoft.org/messages">old</a>). To subscribe to this list, please visit the <a href="http://mail.gnome.org/mailman/listinfo/xml">associated Web</a> page and follow the instructions. <strong>Do not send code, I won't debug it</strong> (but patches are really appreciated!).</p> <p>Check the following too before posting:</p> <ul> <li>make sure you are <a href="ftp://xmlsoft.org/">using a recent version</a>, and that the problem still shows up in those</li> <li>check the <a href="http://mail.gnome.org/archives/xml/">list archives</a> to see if the problem was reported already, in this case there is probably a fix available, similary check the <a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml&product=libxslt&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=NEEDINFO&bug_status=REOPENED&bug_status=RESOLVED&bug_status=VERIFIED&email1=&emailtype1=substring&emailassigned_to1=1&emailreporter1=1&emailcc1=1&emaillongdesc1=1&email2=&emailtype2=substring&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emaillongdesc2=1&changedin=&chfieldfrom=&chfieldto=Now&chfieldvalue=&short_desc=&short_desc_type=substring&long_desc=&long_desc_type=substring&bug_file_loc=&bug_file_loc_type=substring&status_whiteboard=&status_whiteboard_type=substring&keywords=&keywords_type=anywords&op_sys_details=&op_sys_details_type=substring&version_details=&version_details_type=substring&cmdtype=doit&newqueryname=&order=Reuse+same+sort+as+last+time&form_name=query">registered open bugs</a></li> <li>make sure you can reproduce the bug with xmllint or one of the test programs found in source in the distribution</li> <li>Please send the command showing the error as well as the input (as an attachement)</li> </ul> <p>Alternatively, you can just send the bug to the <a href="mailto:xml@gnome.org">xml@gnome.org</a> list; if it's really libxml related I will approve it.. Please do not send me mail directly especially for portability problem, it makes things really harder to track and in some cases I'm not the best person to answer a given question, ask the list instead.</p> <p>Of course, bugs reported with a suggested patch for fixing them will probably be processed faster.</p> <p>If you're looking for help, a quick look at <a href="http://xmlsoft.org/messages/#407">the list archive</a> may actually provide the answer, I usually send source samples when answering libxml usage questions. The <a href="http://xmlsoft.org/html/book1.html">auto-generated documentantion</a> is not as polished as I would like (i need to learn more about Docbook), but it's a good starting point.</p> <h2><a name="help">How to help</a></h2> <p>You can help the project in various ways, the best thing to do first is to subscribe to the mailing-list as explained before, check the <a href="http://xmlsoft.org/messages/">archives </a>and the <a href="http://bugs.gnome.org/db/pa/lgnome-xml.html">Gnome bug database:</a>:</p> <ol> <li>provide patches when you find problems</li> <li>provide the diffs when you port libxml to a new platform. They may not be integrated in all cases but help pinpointing portability problems and</li> <li>provide documentation fixes (either as patches to the code comments or as HTML diffs).</li> <li>provide new documentations pieces (translations, examples, etc ...)</li> <li>Check the TODO file and try to close one of the items</li> <li>take one of the points raised in the archive or the bug database and provide a fix. <a href="mailto:Daniel.Veillard@imag.fr">Get in touch with me </a>before to avoid synchronization problems and check that the suggested fix will fit in nicely :-)</li> </ol> <h2><a name="Downloads">Downloads</a></h2> <p>The latest versions of libxml can be found on <a href="ftp://xmlsoft.org/">xmlsoft.org</a> (<a href="ftp://speakeasy.rpmfind.net/pub/libxml/">Seattle</a>, <a href="ftp://fr.rpmfind.net/pub/libxml/">France</a>) or on the <a href="ftp://ftp.gnome.org/pub/GNOME/MIRRORS.html">Gnome FTP server</a> either as a <a href="ftp://ftp.gnome.org/pub/GNOME/stable/sources/libxml/">source archive</a> or <a href="ftp://ftp.gnome.org/pub/GNOME/stable/redhat/i386/libxml/">RPM packages</a>. (NOTE that you need both the <a href="http://rpmfind.net/linux/RPM/libxml2.html">libxml(2)</a> and <a href="http://rpmfind.net/linux/RPM/libxml2-devel.html">libxml(2)-devel</a> packages installed to compile applications using libxml.)</p> <p><a name="Snapshot">Snapshot:</a></p> <ul> <li>Code from the W3C cvs base libxml <a href="ftp://xmlsoft.org/cvs-snapshot.tar.gz">cvs-snapshot.tar.gz</a></li> <li>Docs, content of the web site, the list archive included <a href="ftp://xmlsoft.org/libxml-docs.tar.gz">libxml-docs.tar.gz</a></li> </ul> <p><a name="Contribs">Contribs:</a></p> <p>I do accept external contributions, especially if compiling on another platform, get in touch with me to upload the package. I will keep them in the <a href="ftp://xmlsoft.org/contribs/">contrib directory</a></p> <p>Libxml is also available from CVS:</p> <ul> <li><p>The <a href="http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&dir=gnome-xml">Gnome CVS base</a>. Check the <a href="http://developer.gnome.org/tools/cvs.html">Gnome CVS Tools</a> page; the CVS module is <b>gnome-xml</b>.</p> </li> <li>The <strong>libxslt</strong> module is also present there</li> </ul> <h2><a name="News">News</a></h2> <h3>CVS only : check the <a href="http://cvs.gnome.org/lxr/source/gnome-xml/ChangeLog">Changelog</a> file for a really accurate description</h3> <p>Items floating around but not actively worked on, get in touch with me if you want to test those</p> <ul> <li>Implementing <a href="http://xmlsoft.org/XSLT">XSLT</a>, this is done as a separate C library on top of libxml called libxslt</li> <li>Finishing up <a href="http://www.w3.org/TR/xptr">XPointer</a> and <a href="http://www.w3.org/TR/xinclude">XInclude</a></li> <li>(seeems working but delayed from release) parsing/import of Docbook SGML docs</li> </ul> <h3>2.4.0: July 10 2001</h3> <ul> <li>Fixed a few bugs in XPath, validation, and tree handling.</li> <li>Fixed XML Base implementation, added a coupel of examples to the regression tests</li> <li>A bit of cleanup</li> </ul> <h3>2.3.14: July 5 2001</h3> <ul> <li>fixed some entities problems and reduce mem requirement when substituing them</li> <li>lots of improvements in the XPath queries interpreter can be substancially faster</li> <li>Makefiles and configure cleanups</li> <li>Fixes to XPath variable eval, and compare on empty node set</li> <li>HTML tag closing bug fixed</li> <li>Fixed an URI reference computating problem when validating</li> </ul> <h3>2.3.13: June 28 2001</h3> <ul> <li>2.3.12 configure.in was broken as well as the push mode XML parser</li> <li>a few more fixes for compilation on Windows MSC by Yon Derek</li> </ul> <h3>1.8.14: June 28 2001</h3> <ul> <li>Zbigniew Chyla gave a patch to use the old XML parser in push mode</li> <li>Small Makefile fix</li> </ul> <h3>2.3.12: June 26 2001</h3> <ul> <li>lots of cleanup</li> <li>a couple of validation fix</li> <li>fixed line number counting</li> <li>fixed serious problems in the XInclude processing</li> <li>added support for UTF8 BOM at beginning of entities</li> <li>fixed a strange gcc optimizer bugs in xpath handling of float, gcc-3.0 miscompile uri.c (William), Thomas Leitner provided a fix for the optimizer on Tru64</li> <li>incorporated Yon Derek and Igor Zlatkovic fixes and improvements for compilation on Windows MSC</li> <li>update of libxml-doc.el (Felix Natter)</li> <li>fixed 2 bugs in URI normalization code</li> </ul> <h3>2.3.11: June 17 2001</h3> <ul> <li>updates to trio, Makefiles and configure should fix some portability problems (alpha)</li> <li>fixed some HTML serialization problems (pre, script, and block/inline handling), added encoding aware APIs, cleanup of this code</li> <li>added xmlHasNsProp()</li> <li>implemented a specific PI for encoding support in the DocBook SGML parser</li> <li>some XPath fixes (-Infinity, / as a function parameter and namespaces node selection)</li> <li>fixed a performance problem and an error in the validation code</li> <li>fixed XInclude routine to implement the recursive behaviour</li> <li>fixed xmlFreeNode problem when libxml is included statically twice</li> <li>added --version to xmllint for bug reports</li> </ul> <h3>2.3.10: June 1 2001</h3> <ul> <li>fixed the SGML catalog support</li> <li>a number of reported bugs got fixed, in XPath, iconv detection, XInclude processing</li> <li>XPath string function should now handle unicode correctly</li> </ul> <h3>2.3.9: May 19 2001</h3> <p>Lots of bugfixes, and added a basic SGML catalog support:</p> <ul> <li>HTML push bugfix #54891 and another patch from Jonas Borgstr