2001-11-10 14:57:23 +03:00
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
2000-03-04 14:39:43 +03:00
< html >
< head >
2001-10-25 14:53:28 +04:00
< meta content = "text/html; charset=ISO-8859-1" http-equiv = "Content-Type" >
< style type = "text/css" > < ! - -
2002-01-16 18:37:50 +03:00
TD {font-size: 14pt; font-family: Verdana,Arial,Helvetica}
BODY {font-size: 14pt; font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}
H1 {font-size: 20pt; font-family: Verdana,Arial,Helvetica}
H2 {font-size: 18pt; font-family: Verdana,Arial,Helvetica}
H3 {font-size: 16pt; font-family: Verdana,Arial,Helvetica}
2001-10-25 14:53:28 +04:00
A:link, A:visited, A:active { text-decoration: underline }
-->< / style >
< title > Upgrading 1.x code< / title >
2000-03-04 14:39:43 +03:00
< / head >
2001-10-25 14:53:28 +04:00
< body bgcolor = "#8b7765" text = "#000000" link = "#000000" vlink = "#000000" >
< table border = "0" width = "100%" cellpadding = "5" cellspacing = "0" align = "center" > < tr >
< td width = "180" >
< 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 >
< / 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 library for 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 > Main Menu< / b > < / center > < / td > < / tr >
2002-01-21 12:52:27 +03:00
< tr > < td bgcolor = "#fffacd" > < ul >
2001-10-25 14:53:28 +04:00
< li > < a href = "index.html" > Home< / a > < / li >
< li > < a href = "intro.html" > Introduction< / a > < / li >
< li > < a href = "FAQ.html" > FAQ< / a > < / li >
< li > < a href = "docs.html" > Documentation< / a > < / li >
< li > < a href = "bugs.html" > Reporting bugs and getting help< / a > < / li >
< li > < a href = "help.html" > How to help< / a > < / li >
< li > < a href = "downloads.html" > Downloads< / a > < / li >
< li > < a href = "news.html" > News< / a > < / li >
2002-01-08 16:26:00 +03:00
< li > < a href = "XMLinfo.html" > XML< / a > < / li >
2001-10-25 14:53:28 +04:00
< li > < a href = "XSLT.html" > XSLT< / a > < / li >
2002-02-20 17:37:47 +03:00
< li > < a href = "python.html" > Python and bindings< / a > < / li >
2001-10-25 14:53:28 +04:00
< li > < a href = "architecture.html" > libxml 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 = "xmldtd.html" > Validation & DTDs< / a > < / li >
< li > < a href = "xmlmem.html" > Memory Management< / a > < / li >
< li > < a href = "encoding.html" > Encodings support< / a > < / li >
< li > < a href = "xmlio.html" > I/O Interfaces< / a > < / li >
< li > < a href = "catalog.html" > Catalog support< / 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 >
2001-10-30 15:51:17 +03:00
< li > < a href = "threads.html" > Thread safety< / a > < / li >
2001-10-25 14:53:28 +04:00
< li > < a href = "DOM.html" > DOM Principles< / a > < / li >
< li > < a href = "example.html" > A real example< / a > < / li >
< li > < a href = "contribs.html" > Contributions< / 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" >
2002-01-23 15:36:34 +03:00
< tr > < td colspan = "1" bgcolor = "#eecfa1" align = "center" > < center > < b > API Indexes< / b > < / center > < / td > < / tr >
< tr > < td bgcolor = "#fffacd" > < ul >
2002-01-23 20:58:17 +03:00
< li > < a href = "APIchunk0.html" > Alphabetic< / a > < / li >
2002-01-23 15:36:34 +03:00
< 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" >
2001-10-25 14:53:28 +04:00
< tr > < td colspan = "1" bgcolor = "#eecfa1" align = "center" > < center > < b > Related links< / b > < / center > < / td > < / tr >
2002-01-21 12:52:27 +03:00
< tr > < td bgcolor = "#fffacd" > < ul >
2001-10-25 14:53:28 +04:00
< li > < a href = "http://mail.gnome.org/archives/xml/" > Mail archive< / a > < / li >
< li > < a href = "http://xmlsoft.org/XSLT/" > XSLT libxslt< / a > < / li >
2002-01-08 14:49:22 +03:00
< li > < a href = "http://phd.cs.unibo.it/gdome2/" > DOM gdome2< / a > < / li >
2001-10-25 14:53:28 +04:00
< li > < a href = "ftp://xmlsoft.org/" > FTP< / a > < / li >
< li > < a href = "http://www.fh-frankfurt.de/~igor/projects/libxml/" > Windows binaries< / a > < / li >
2001-11-26 20:25:02 +03:00
< li > < a href = "http://garypennington.net/libxml2/" > Solaris binaries< / a > < / li >
2001-10-27 11:50:58 +04:00
< li > < a href = "http://bugzilla.gnome.org/buglist.cgi?product=libxml" > Bug Tracker< / a > < / li >
2001-10-25 14:53:28 +04:00
< / 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 >
2000-03-04 14:39:43 +03:00
< p > Version 2 of libxml is the first version introducing serious backward
incompatible changes. The main goals were:< / p >
< ul >
2001-10-25 14:53:28 +04:00
< li > a general cleanup. A number of mistakes inherited from the very early
2001-10-24 11:26:23 +04:00
versions couldn't be changed due to compatibility constraints. Example
2001-10-25 14:53:28 +04:00
the " childs" element in the nodes.< / li >
< li > Uniformization of the various nodes, at least for their header and link
2000-03-04 14:39:43 +03:00
parts (doc, parent, children, prev, next), the goal is a simpler
programming model and simplifying the task of the DOM implementors.< / li >
2001-10-25 14:53:28 +04:00
< li > better conformances to the XML specification, for example version 1.x
2000-03-04 14:39:43 +03:00
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 >
2001-10-25 14:53:28 +04:00
< h3 > How to fix libxml-1.x code:< / h3 >
2000-03-04 14:39:43 +03:00
< 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.<2E> eillardw3.org" > drop me a
mail< / a > :< / p >
< ol >
2001-10-25 14:53:28 +04:00
< li > The package name have changed from libxml to libxml2, the library name
2001-03-17 01:04:15 +03:00
is now -lxml2 . There is a new xml2-config script which should be used to
select the right parameters libxml2< / li >
2001-10-25 14:53:28 +04:00
< li > Node < strong > childs< / strong > field has been renamed
2000-03-04 14:39:43 +03:00
< strong > children< / strong > so s/childs/children/g should be applied
2001-10-25 14:53:28 +04:00
(probablility of having " childs" anywere else is close to 0+< / li >
< li > The document don't have anymore a < strong > root< / strong > element it has
2001-10-24 11:26:23 +04:00
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
2000-03-04 14:39:43 +03:00
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
2001-03-17 01:04:15 +03:00
PIs or comments before or after the root element
s/-> root/-> children/g will probably do it.< / li >
2001-10-25 14:53:28 +04:00
< li > The white space issue, this one is more complex, unless special case of
2000-03-04 14:39:43 +03:00
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 >
2001-10-25 14:53:28 +04:00
< li > lazy one, use the compatibility call
2000-03-04 14:39:43 +03:00
< strong > xmlKeepBlanksDefault(0)< / strong > but be aware that you are
2001-10-24 11:26:23 +04:00
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 >
2001-10-25 14:53:28 +04:00
< li > the Right Way: change you code to accept possibly unsignificant
2000-03-04 14:39:43 +03:00
blanks characters, or have your tree populated with weird blank text
nodes. You can spot them using the comodity function
< strong > xmlIsBlankNode(node)< / strong > returning 1 for such blank
nodes.< / li >
2001-10-25 14:53:28 +04:00
< / ol >
< p > Note also that with the new default the output functions don't add any
2000-03-04 14:39:43 +03:00
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 >
2001-10-25 14:53:28 +04:00
< / li >
< li > The include path has changed to $prefix/libxml/ and the includes
2000-04-03 23:48:13 +04:00
themselves uses this new prefix in includes instructions... If you are
2000-04-12 17:27:38 +04:00
using (as expected) the
2001-03-17 01:04:15 +03:00
< pre > xml2-config --cflags< / pre >
2001-10-25 14:53:28 +04:00
< p > output to generate you compile commands this will probably work out of
2000-04-03 23:48:13 +04:00
the box< / p >
2001-10-25 14:53:28 +04:00
< / li >
< li > xmlDetectCharEncoding takes an extra argument indicating the lenght in
2001-10-24 11:26:23 +04:00
byte of the head of the document available for character detection.< / li >
2000-03-04 14:39:43 +03:00
< / ol >
2001-10-25 14:53:28 +04:00
< h3 > Ensuring both libxml-1.x and libxml-2.x compatibility< / h3 >
2001-03-17 01:04:15 +03:00
< p > Two new version of libxml (1.8.11) and libxml2 (2.3.4) have been released
to allow smoth upgrade of existing libxml v1code while retaining
compatibility. They offers the following:< / p >
2000-05-06 12:11:19 +04:00
< ol >
2001-10-25 14:53:28 +04:00
< li > similar include naming, one should use
2001-03-17 01:04:15 +03:00
< strong > #include< libxml/...> < / strong > in both cases.< / li >
2001-10-25 14:53:28 +04:00
< li > similar identifiers defined via macros for the child and root fields:
2000-06-29 04:43:27 +04:00
respectively < strong > xmlChildrenNode< / strong > and
2001-10-25 14:53:28 +04:00
< strong > xmlRootNode< / strong >
< / li >
< li > a new macro < strong > LIBXML_TEST_VERSION< / strong > which should be
2000-06-29 04:43:27 +04:00
inserted once in the client code< / li >
< / ol >
< p > So the roadmap to upgrade your existing libxml applications is the
following:< / p >
< ol >
2001-10-25 14:53:28 +04:00
< li > install the libxml-1.8.8 (and libxml-devel-1.8.8) packages< / li >
< li > find all occurences where the xmlDoc < strong > root< / strong > field is
used and change it to < strong > xmlRootNode< / strong >
< / li >
< li > similary find all occurences 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
2000-06-29 04:43:27 +04:00
< strong > main()< / strong > or in the library init entry point< / li >
2001-10-25 14:53:28 +04:00
< li > Recompile, check compatibility, it should still work< / li >
< li > Change your configure script to look first for xml2-config and fallback
2001-03-17 01:04:15 +03:00
using xml-config . Use the --cflags and --libs ouptut of the command as
the Include and Linking parameters needed to use libxml.< / li >
2001-10-25 14:53:28 +04:00
< li > install libxml2-2.3.x and libxml2-devel-2.3.x (libxml-1.8.y and
2001-03-17 01:04:15 +03:00
libxml-devel-1.8.y can be kept simultaneously)< / li >
2001-10-25 14:53:28 +04:00
< li > remove your config.cache, relaunch your configuration mechanism, and
2000-06-29 04:43:27 +04:00
recompile, if steps 2 and 3 were done right it should compile as-is< / li >
2001-10-25 14:53:28 +04:00
< li > Test that your application is still running correctly, if not this may
2000-06-29 04:43:27 +04:00
be due to extra empty nodes due to formating 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 >
2000-05-06 12:11:19 +04:00
< / ol >
2000-06-30 22:39:56 +04:00
< p > Following those steps should work. It worked for some of my own code.< / p >
2000-03-04 14:39:43 +03:00
< p > Let me put some emphasis on the fact that there is far more changes from
2000-05-06 12:11:19 +04:00
libxml 1.x to 2.x than the ones you may have to patch for. The overall code
2001-10-25 14:53:28 +04:00
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 >
2002-02-13 12:19:28 +03:00
< p > < a href = "bugs.html" > Daniel Veillard< / a > < / p >
2001-10-25 14:53:28 +04:00
< / td > < / tr > < / table > < / td > < / tr > < / table > < / td > < / tr > < / table > < / td >
< / tr > < / table > < / td > < / tr > < / table >
2000-03-04 14:39:43 +03:00
< / body >
< / html >