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&lt;libxml/...&gt;</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 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>
</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>

<h2><a name="Thread">Thread safety</a></h2>

<p>Starting with 2.4.7, libxml2 makes provisions to ensure that concurrent
threads can safely work in parallel parsing different documents. There is
however a couple of things to do to ensure it:</p>
<ul>
  <li>configure the library accordingly using the --with-threads options</li>
  <li>call xmlInitParser() in the "main" thread before using any of the
    libxml2 API (except possibly selecting a different memory allocator)</li>
</ul>

<p>Note that the thread safety cannot be ensured for multiple threads sharing
the same document, the locking must be done at the application level, libxml
exports a basic mutex and reentrant mutexes API in &lt;libxml/threads.h&gt;.
The parts of the library checked for thread safety are:</p>
<ul>
  <li>concurrent loading</li>
  <li>file access resolution</li>
  <li>catalog access</li>
  <li>catalog building</li>
  <li>entities lookup/accesses</li>
  <li>validation</li>
  <li>global variables per-thread override</li>
  <li>memory handling</li>
</ul>

<p>XPath is supposed to be thread safe now, but this wasn't tested
seriously.</p>

<h2><a name="DOM"></a><a name="Principles">DOM Principles</a></h2>

<p><a href="http://www.w3.org/DOM/">DOM</a> stands for the <em>Document
Object Model</em>; this is an API for accessing XML or HTML structured
documents. Native support for DOM in Gnome is on the way (module gnome-dom),
and will be based on gnome-xml. This will be a far cleaner interface to
manipulate XML files within Gnome since it won't expose the internal
structure.</p>

<p>The current DOM implementation on top of libxml2 is the <a
href="http:///svn.gnome.org/viewcvs/gdome2/trunk/">gdome2 Gnome module</a>, this
is a full DOM interface, thanks to Paolo Casarini, check the <a
href="http://gdome2.cs.unibo.it/">Gdome2 homepage</a> for more
information.</p>

<h2><a name="Example"></a><a name="real">A real example</a></h2>

<p>Here is a real size example, where the actual content of the application
data is not kept in the DOM tree but uses internal structures. It is based on
a proposal to keep a database of jobs related to Gnome, with an XML based
storage structure. Here is an <a href="gjobs.xml">XML encoded jobs
base</a>:</p>
<pre>&lt;?xml version="1.0"?&gt;
&lt;gjob:Helping xmlns:gjob="http://www.gnome.org/some-location"&gt;
  &lt;gjob:Jobs&gt;

    &lt;gjob:Job&gt;
      &lt;gjob:Project ID="3"/&gt;
      &lt;gjob:Application&gt;GBackup&lt;/gjob:Application&gt;
      &lt;gjob:Category&gt;Development&lt;/gjob:Category&gt;

      &lt;gjob:Update&gt;
        &lt;gjob:Status&gt;Open&lt;/gjob:Status&gt;