/usr/share/doc/libxml2-devel
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><link rel="SHORTCUT ICON" href="/favicon.ico" /><style type="text/css"> TD {font-family: Verdana,Arial,Helvetica} BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em} H1 {font-family: Verdana,Arial,Helvetica} H2 {font-family: Verdana,Arial,Helvetica} H3 {font-family: Verdana,Arial,Helvetica} A:link, A:visited, A:active { text-decoration: underline } </style><title>Upgrading 1.x code</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 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><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>Upgrading 1.x code</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Developer Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html" style="font-weight:bold">Main Menu</a></li><li><a href="html/index.html" style="font-weight:bold">Reference Manual</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="tutorial/index.html">Tutorial</a></li><li><a href="xmlreader.html">The Reader Interface</a></li><li><a href="ChangeLog.html">ChangeLog</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="python.html">Python and bindings</a></li><li><a href="architecture.html">libxml2 architecture</a></li><li><a href="tree.html">The tree output</a></li><li><a href="interface.html">The SAX interface</a></li><li><a href="xmlmem.html">Memory Management</a></li><li><a href="xmlio.html">I/O Interfaces</a></li><li><a href="library.html">The parser interfaces</a></li><li><a href="entities.html">Entities or no entities</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="upgrade.html">Upgrading 1.x code</a></li><li><a href="threads.html">Thread safety</a></li><li><a href="DOM.html">DOM Principles</a></li><li><a href="example.html">A real example</a></li><li><a href="xml.html">flat page</a>, <a href="site.xsl">stylesheet</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>API Indexes</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="APIchunk0.html">Alphabetic</a></li><li><a href="APIconstructors.html">Constructors</a></li><li><a href="APIfunctions.html">Functions/Types</a></li><li><a href="APIfiles.html">Modules</a></li><li><a href="APIsymbols.html">Symbols</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://opencsw.org/packages/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://lxml.de/">lxml Python bindings</a></li><li><a href="http://cpan.uwinnipeg.ca/dist/XML-LibXML">Perl bindings</a></li><li><a href="https://libxmlplusplus.github.io/libxmlplusplus/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="https://gitlab.gnome.org/GNOME/libxml2/issues">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>Incompatible changes:</p><p>Version 2 of libxml2 is the first version introducing serious backward incompatible changes. The main goals were:</p><ul> <li>a general cleanup. A number of mistakes inherited from the very early versions couldn't be changed due to compatibility constraints. Example the "childs" element in the nodes.</li> <li>Uniformization of the various nodes, at least for their header and link parts (doc, parent, children, prev, next), the goal is a simpler programming model and simplifying the task of the DOM implementors.</li> <li>better conformances to the XML specification, for example version 1.x had an heuristic to try to detect ignorable white spaces. As a result the SAX event generated were ignorableWhitespace() while the spec requires character() in that case. This also mean that a number of DOM node containing blank text may populate the DOM tree which were not present before.</li> </ul><h3>How to fix libxml-1.x code:</h3><p>So client code of libxml designed to run with version 1.x may have to be changed to compile against version 2.x of libxml. Here is a list of changes that I have collected, they may not be sufficient, so in case you find other change which are required, <a href="mailto:Daniel.Veillard@w3.org">drop me a mail</a>:</p><ol> <li>The package name have changed from libxml to libxml2, the library name is now -lxml2 . There is a new xml2-config script which should be used to select the right parameters libxml2</li> <li>Node <strong>childs</strong> field has been renamed <strong>children</strong> so s/childs/children/g should be applied (probability of having "childs" anywhere else is close to 0+</li> <li>The document don't have anymore a <strong>root</strong> element it has been replaced by <strong>children</strong> and usually you will get a list of element here. For example a Dtd element for the internal subset and it's declaration may be found in that list, as well as processing instructions or comments found before or after the document root element. Use <strong>xmlDocGetRootElement(doc)</strong> to get the root element of a document. Alternatively if you are sure to not reference DTDs nor have PIs or comments before or after the root element s/->root/->children/g will probably do it.</li> <li>The white space issue, this one is more complex, unless special case of validating parsing, the line breaks and spaces usually used for indenting and formatting the document content becomes significant. So they are reported by SAX and if your using the DOM tree, corresponding nodes are generated. Too approach can be taken: <ol> <li>lazy one, use the compatibility call <strong>xmlKeepBlanksDefault(0)</strong> but be aware that you are relying on a special (and possibly broken) set of heuristics of libxml to detect ignorable blanks. Don't complain if it breaks or make your application not 100% clean w.r.t. to it's input.</li> <li>the Right Way: change you code to accept possibly insignificant blanks characters, or have your tree populated with weird blank text nodes. You can spot them using the commodity function <strong>xmlIsBlankNode(node)</strong> returning 1 for such blank nodes.</li> </ol> <p>Note also that with the new default the output functions don't add any extra indentation when saving a tree in order to be able to round trip (read and save) without inflating the document with extra formatting chars.</p> </li> <li>The include path has changed to $prefix/libxml/ and the includes themselves uses this new prefix in includes instructions... If you are using (as expected) the <pre>xml2-config --cflags</pre> <p>output to generate you compile commands this will probably work out of the box</p> </li> <li>xmlDetectCharEncoding takes an extra argument indicating the length in byte of the head of the document available for character detection.</li> </ol><h3>Ensuring both libxml-1.x and libxml-2.x compatibility</h3><p>Two new version of libxml (1.8.11) and libxml2 (2.3.4) have been released to allow smooth upgrade of existing libxml v1code while retaining compatibility. They offers the following:</p><ol> <li>similar include naming, one should use <strong>#include<libxml/...></strong> in both cases.</li> <li>similar identifiers defined via macros for the child and root fields: respectively <strong>xmlChildrenNode</strong> and <strong>xmlRootNode</strong></li> <li>a new macro <strong>LIBXML_TEST_VERSION</strong> which should be inserted once in the client code</li> </ol><p>So the roadmap to upgrade your existing libxml applications is the following:</p><ol> <li>install the libxml-1.8.8 (and libxml-devel-1.8.8) packages</li> <li>find all occurrences where the xmlDoc <strong>root</strong> field is used and change it to <strong>xmlRootNode</strong></li> <li>similarly find all occurrences where the xmlNode <strong>childs</strong> field is used and change it to <strong>xmlChildrenNode</strong></li> <li>add a <strong>LIBXML_TEST_VERSION</strong> macro somewhere in your <strong>main()</strong> or in the library init entry point</li> <li>Recompile, check compatibility, it should still work</li> <li>Change your configure script to look first for xml2-config and fall back using xml-config . Use the --cflags and --libs output of the command as the Include and Linking parameters needed to use libxml.</li> <li>install libxml2-2.3.x and libxml2-devel-2.3.x (libxml-1.8.y and libxml-devel-1.8.y can be kept simultaneously)</li> <li>remove your config.cache, relaunch your configuration mechanism, and recompile, if steps 2 and 3 were done right it should compile as-is</li> <li>Test that your application is still running correctly, if not this may be due to extra empty nodes due to formatting spaces being kept in libxml2 contrary to libxml1, in that case insert xmlKeepBlanksDefault(1) in your code before calling the parser (next to <strong>LIBXML_TEST_VERSION</strong> is a fine place).</li> </ol><p>Following those steps should work. It worked for some of my own code.</p><p>Let me put some emphasis on the fact that there is far more changes from libxml 1.x to 2.x than the ones you may have to patch for. The overall code has been considerably cleaned up and the conformance to the XML specification has been drastically improved too. Don't take those changes as an excuse to not upgrade, it may cost a lot on the long term ...</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>
.
Edit
..
Edit
APIchunk0.html
Edit
APIchunk1.html
Edit
APIchunk10.html
Edit
APIchunk11.html
Edit
APIchunk12.html
Edit
APIchunk13.html
Edit
APIchunk14.html
Edit
APIchunk15.html
Edit
APIchunk16.html
Edit
APIchunk17.html
Edit
APIchunk18.html
Edit
APIchunk19.html
Edit
APIchunk2.html
Edit
APIchunk20.html
Edit
APIchunk21.html
Edit
APIchunk22.html
Edit
APIchunk23.html
Edit
APIchunk24.html
Edit
APIchunk25.html
Edit
APIchunk26.html
Edit
APIchunk27.html
Edit
APIchunk28.html
Edit
APIchunk29.html
Edit
APIchunk3.html
Edit
APIchunk4.html
Edit
APIchunk5.html
Edit
APIchunk6.html
Edit
APIchunk7.html
Edit
APIchunk8.html
Edit
APIchunk9.html
Edit
APIconstructors.html
Edit
APIfiles.html
Edit
APIfunctions.html
Edit
APIsymbols.html
Edit
DOM.gif
Edit
DOM.html
Edit
FAQ.html
Edit
Libxml2-Logo-180x168.gif
Edit
Libxml2-Logo-90x34.gif
Edit
XMLinfo.html
Edit
XSLT.html
Edit
architecture.html
Edit
bugs.html
Edit
catalog.gif
Edit
catalog.html
Edit
contribs.html
Edit
docs.html
Edit
downloads.html
Edit
encoding.html
Edit
entities.html
Edit
example.html
Edit
examples
Edit
guidelines.html
Edit
help.html
Edit
html
Edit
index.html
Edit
interface.html
Edit
intro.html
Edit
library.html
Edit
libxml.gif
Edit
libxml2-api.xml.gz
Edit
namespaces.html
Edit
news.html
Edit
python.html
Edit
redhat.gif
Edit
searches.html
Edit
smallfootonly.gif
Edit
structure.gif
Edit
threads.html
Edit
tree.html
Edit
tutorial
Edit
upgrade.html
Edit
w3c.png
Edit
xml.html
Edit
xmlcatalog_man.html
Edit
xmldtd.html
Edit
xmlio.html
Edit
xmllint.html
Edit
xmlmem.html
Edit
xmlreader.html
Edit
