Commits

Anonymous committed 5663b47

PLEASE TEST TO MAKE 1.55 POSSIBLE!

Modified Files:
Makefile.PL
o changed to use the new docbook to pod converter to create the
documentation

Added Files:
example/libxml.dkb
Entire documentation inclusive README and LICENSE is now stored within
this docbook file. This file is the base for all documentation of
XML::LibXML.
This was done, so anyone with a docbook editor can edit the documentation
easily.

example/xmllibxmldocs.pl
converts the libxml.dkb into a set of PODs and extracts the README and
LICENSE information.

  • Participants
  • Parent commits 50c6372

Comments (0)

Files changed (3)

     $str .= <<EOF;
 
 docs : pure_all
-\t\@$^X -Iblib/arch -Iblib/lib example/xml2pod.pl example/libxml.xml lib/XML/LibXML/
+\t\@$^X -Iblib/arch -Iblib/lib example/xmllibxmldocs.pl example/libxml.dkb lib/XML/LibXML/
 \t\@$^X -pi.old -e 's/a/a/' Makefile.PL
 \t\@echo "==> YOU MUST NOW RE-RUN $^X Makefile.PL <=="
 \t\@false

File example/libxml.dkb

+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">
+<book lang="en-us">
+  <title>XML::LibXML</title>
+  <bookinfo>
+    <authorgroup>
+      <author>
+        <firstname>Matt</firstname>
+        <surname>Sergeant</surname>
+      </author>
+      <author>
+        <firstname>Christian</firstname>
+        <surname>Glahn</surname>
+      </author>
+    </authorgroup>
+    <edition>1.55</edition>
+    <copyright>
+      <year>2001-2003</year>
+      <holder>AxKit.com Ltd</holder>
+    </copyright>
+  </bookinfo>
+  <chapter>
+    <title>Introduction</title>
+    <titleabbrev>README</titleabbrev>
+    <para>This module implements a Perl interface to the Gnome libxml2
+    library. The libxml2 libxml2 library provides interfaces for parsing and
+    manipulating XML Files. This Module allows Perl programmers to make use of
+    the highly capable validating XML parser and the high performance DOM
+    implementation.</para>
+    <sect1>
+      <title>Important Notes</title>
+      <para>XML::LibXML was almost entirely reimplemented between version 1.40
+      to version 1.49. This may cause problems on some production machines.
+      With version 1.50 a lot of compatibility fixes were applied, so programs
+      written for XML::LibXML 1.40 or less should run with version 1.50 again.</para>
+    </sect1>
+    <sect1>
+      <title>Dependencies</title>
+      <para>Prior to installation you MUST have installed the libxml2 library.
+      You can get the latest libxml2 version from</para>
+      <para>http://xmlsoft.org</para>
+      <para>Without libxml2 installed this module will neither build nor run.</para>
+      <para>Also XML::LibXML requires the following packages:</para>
+      <itemizedlist>
+        <listitem>
+          <para>XML::LibXML::Common - general functions used by various
+          XML::LibXML modules</para>
+        </listitem>
+        <listitem>
+          <para>XML::SAX - DOM building support from SAX</para>
+        </listitem>
+        <listitem>
+          <para>XML::NamespaceSupport - DOM building support from SAX</para>
+        </listitem>
+      </itemizedlist>
+      <para>These packages are required. If one is missing some tests will
+      fail.</para>
+    </sect1>
+    <sect1>
+      <title>Installation</title>
+      <para>To install XML::LibXML just follow the standard installation
+      routine for Perl modules:</para>
+      <orderedlist>
+        <listitem>
+          <para>perl Makefile.PL</para>
+        </listitem>
+        <listitem>
+          <para>make</para>
+        </listitem>
+        <listitem>
+          <para>make test</para>
+        </listitem>
+        <listitem>
+          <para>make install # as superuser</para>
+        </listitem>
+      </orderedlist>
+      <para>Note that you have to rebuild XML::LibXML once you upgrade
+      libxml2. This avoids problems with binary incompatibilities between
+      releases of the library.</para>
+      <sect2>
+        <title>Note On libxml2 Versions</title>
+        <para>libxml2 claims binary compatibility between its patch levels.
+        This is not all true:</para>
+        <para>First of all XML::LibXML requires at least libxml2 2.4.25. For
+        most OS this means that an update of the prebuild packages is
+        required, since most distributors ship ancient libxml2 versions most
+        users will need to upgrade their installation.</para>
+        <para>If you already run an older version of XML::LibXML and you wish
+        to upgrade to a bug fixed version of libxml2. libxml2 2.4.25 and 2.5.x
+        versions are not 100% binary compatible to older versions. So if you
+        intend to upgrade to such a version you will need to recompile
+        XML::LibXML as well.</para>
+        <para>Users of perl 5.005_03 and perl 5.6.1 with thread support will
+        also like to avoid libxml2 version 2.4.25 and use later versions
+        instead.</para>
+        <para>If your libxml2 installation is not within your $PATH. you can
+        set the environment variable XMLPREFIX=$YOURLIBXMLPREFIX to make
+        XML::LibXML recognize the correct libxml2 version in use.</para>
+        <para>e.g.</para>
+        <programlisting> XMLPREFIX=/usr/brand-new perl Makefile.PL</programlisting>
+        <para>will ask &#39;/usr/brand-new/bin/xml2-config&#39; about your
+        real libxml2 configuration.</para>
+        <para>Try to avoid to set INC and LIBS on the commandline. One will
+        skip the configuration tests in these cases. There will be no report,
+        if the given installation is known to be broken.</para>
+      </sect2>
+      <sect2>
+        <title>Which Version of libxml2 should be used?</title>
+        <para>XML::LibXML is tested against many versions of libxml2 before it
+        is released. Thus there are versions of libxml2 that are known not to
+        work properly with XML::LibXML. The Makefile.PL keeps a blacklist of
+        these broken libxml2 versions.</para>
+        <para>If one has one of these versions it will be notified during
+        installation. One may find that XML::LibXML builds and tests fine in a
+        particular environment. But if XML::LibXML is run in such an
+        environment, there will be no support at all!</para>
+        <para>The following versions are tested:</para>
+        <itemizedlist>
+          <listitem>
+            <para>prior to 2.4.25: tested; not working.</para>
+          </listitem>
+          <listitem>
+            <para>past 2.4.25: tested; working</para>
+          </listitem>
+          <listitem>
+            <para>past 2.5.0: tested; working</para>
+          </listitem>
+          <listitem>
+            <para>version 2.5.5: tested; tests pass, but known as broken</para>
+          </listitem>
+          <listitem>
+            <para>version 2.5.6: tested; working</para>
+          </listitem>
+          <listitem>
+            <para>version 2.5.7: tested; working</para>
+          </listitem>
+        </itemizedlist>
+      </sect2>
+      <sect2>
+        <title>Notes for Microsoft Windows</title>
+        <para>Thanks to Randy Kobes there is a precompiled PPM package
+        available on</para>
+        <para>http://theoryx5.uwinnipeg.ca/ppmpackages/</para>
+        <para>Usually it takes a little time to build the package for the
+        latest release.</para>
+      </sect2>
+      <sect2>
+        <title>Notes for Mac OS X</title>
+        <para>Due refactoring the module, XML::LibXML will not run with Mac OS
+        X anymore. It appears this is related to special linker options for
+        that OS prior to version 10.2.2. Since I don&#39;t have full access to
+        this OS, help/ patches from OS X gurus are highly apprecheated.</para>
+        <para>It is confirmed that XML::LibXML builds and runs without
+        problems with Mac OS X 10.2.6.</para>
+      </sect2>
+      <sect2>
+        <title>Notes for HPUX</title>
+        <para>XML::LibXML requires libxml2 2.4.25 or later. That means there
+        may not exist a usable binary libxml2 package for HPUX and
+        XML::LibXML. For some reasons the HPUX cc will not compile libxml2
+        correct, which will force you to recompile perl with gcc (if you
+        havn&#39;t already done that).</para>
+        <para>Additionally I recieved the following Note from Rozi Kovesdi:</para>
+        <programlisting>Here is my report if someone else runs into the same problem:
+
+Finally I am done with installing all the libraries and XML Perl
+modules
+
+The combination that worked best for me was:
+gcc
+GNU make
+
+Most important - before trying to install Perl modules that depend on
+libxml2:
+
+must set SHLIB_PATH  to include  the path to  libxml2 shared library
+ 
+assuming that you used the default:
+
+export  SHLIB=/usr/local/lib
+
+also, make sure that the config  files have execute permission:
+
+/usr/local/bin/xml2-config
+/usr/local/bin/xslt-config
+ 
+they did not have +x after they were installed by &#39;make install&#39;
+and it took me a while to realize that this was my problem
+ 
+or one can use:
+
+perl Makefile.PL LIBS=&#39;-L/path/to/lib&#39; INC=&#39;-I/path/to/include&#39;</programlisting>
+      </sect2>
+    </sect1>
+    <sect1>
+      <title>Contact</title>
+      <para>For suggestions, bugreports etc. you may contact the maintainer
+      directly <email>christian.glahn@uibk.ac.at</email></para>
+      <para>Also XML::LibXML issues are discussed among other things on the
+      perl XML mailing list (<email>perl-xml@listserv.ActiveState.com</email>)</para>
+    </sect1>
+    <sect1>
+      <title>Package History</title>
+      <para>Version &#60; 0.98 were maintained by Matt Sergeant</para>
+      <para>0.98 &#62; Version &#62; 1.49 were maintained by Matt Sergeant and
+      Christian Glahn</para>
+      <para>Version &#62;= 1.49 are maintained by Christian Glahn</para>
+    </sect1>
+    <sect1>
+      <title>Patches and Developer Version</title>
+      <para>As XML::LibXML is open source software help and patches are
+      apprechiated. If you found a bug in the current release, make shure this
+      bug still existis in the developer version of XML::LibXML. This version
+      can get downloaded from cvs. The cvs version can be be loaded via</para>
+      <para>cvs -d:pserver:anonymous@axkit.org:/home/cvs -z3 co XML-LibXML</para>
+      <para>Note this account does not allow direct commits.</para>
+      <para>Please consider the tests as correct. If any test fails it is most
+      certainly related to a bug.</para>
+      <para>If you find documentation bugs, please fix them in the libxml.dkb
+      file, stored in the docs directory.</para>
+    </sect1>
+    <sect1>
+      <title>Kown Issues</title>
+      <para>The push-parser implementation causes memory leaks.</para>
+      <para>Using the direct SAX parser, default namespaces will not get
+      recognized correctly.</para>
+    </sect1>
+  </chapter>
+  <chapter>
+    <title>License</title>
+    <titleabbrev>LICENSE</titleabbrev>
+    <para>This is free software, you may use it and distribute it under the
+    same terms as Perl itself.</para>
+    <para>Copyright 2001-2003 AxKit.com Ltd, All rights reserved.</para>
+    <sect1>
+      <title>Disclaimer</title>
+      <para>THIS PROGRAM IS DISTRIBUTED IN THE HOPE THAT IT WILL BE USEFUL,
+      BUT WITHOUT ANY WARRANTY; WITHOUT EVEN THE IMPLIED WARRANTY OF
+      MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.</para>
+    </sect1>
+  </chapter>
+  <chapter>
+    <title>Perl Binding for libxml2</title>
+    <titleabbrev>XML::LibXML</titleabbrev>
+    <sect1>
+      <title>Synopsis</title>
+      <programlisting>use XML::LibXML;
+my $parser = XML::LibXML-&#62;new();
+
+my $doc = $parser-&#62;parse_string(&#60;&#60;&#39;EOT&#39;);
+&#60;some-xml/&#62;
+EOT</programlisting>
+    </sect1>
+    <sect1>
+      <title>Description</title>
+      <para>This module is an interface to the gnome libxml2 DOM and SAX
+      parser and the DOM tree. It also provides an XML::XPath-like findnodes()
+      interface, providing access to the XPath API in libxml2. The module is
+      split into several packages which are not described in this section.</para>
+      <para>For further information, please check the following documentation:</para>
+      <variablelist>
+        <varlistentry>
+          <term>XML::LibXML-Parser</term>
+          <listitem>
+            <para>Parsing XML Files with XML::LibXML</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML-DOM</term>
+          <listitem>
+            <para>XML::LibXML DOM Implementation</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::SAX</term>
+          <listitem>
+            <para>XML::LibXML direct SAX parser</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::Document</term>
+          <listitem>
+            <para>XML::LibXML DOM Document Class</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::Node</term>
+          <listitem>
+            <para>Abstract Base Class of XML::LibXML Nodes</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::Element</term>
+          <listitem>
+            <para>XML::LibXML Class for Element Nodes</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::Text</term>
+          <listitem>
+            <para>XML::LibXML Class for Text Nodes</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::Comment</term>
+          <listitem>
+            <para>XML::LibXML Comment Nodes</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::CDATASection</term>
+          <listitem>
+            <para>XML::LibXML Class for CDATA Sections</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::Attr</term>
+          <listitem>
+            <para>XML::LibXML Attribute Class</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::DocumentFragment</term>
+          <listitem>
+            <para>XML::LibXML&#39;s DOM L2 Document Fragment Implementation</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::Namespace</term>
+          <listitem>
+            <para>XML::LibXML Namespace Implementation</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::PI</term>
+          <listitem>
+            <para>XML::LibXML Processing Instructions</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::Dtd</term>
+          <listitem>
+            <para>XML::LibXML DTD Support</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXMLguts</term>
+          <listitem>
+            <para>Internal of the Perl Layer for libxml2</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect1>
+    <sect1>
+      <title>Related Modules</title>
+      <para>The modules described in this section are not part of the
+      XML::LibXML package itself. As they support some additional features,
+      they are mentioned here.</para>
+      <variablelist>
+        <varlistentry>
+          <term>XML::LibXSLT</term>
+          <listitem>
+            <para>XSLT Processor using libxslt and XML::LibXML</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::Common</term>
+          <listitem>
+            <para>Common functions for XML::LibXML related Classes</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::Iterator</term>
+          <listitem>
+            <para>XML::LibXML Implementation of the DOM Traversal
+            Specification</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>XML::LibXML::XPathContext</term>
+          <listitem>
+            <para>Advanced XPath processing using libxml2 and XML::LibXML</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect1>
+    <sect1>
+      <title>XML::LibXML and XML::GDOME</title>
+      <para>Note: <emphasis>THE FUNCTIONS DESCRIBED HERE ARE STILL
+      EXPERIMENTAL</emphasis></para>
+      <para>Although both modules make use of libxml2&#39;s XML capabilities,
+      the DOM implementation of both modules are not compatible. But still it
+      is possible to exchange nodes from one DOM to the other. The concept of
+      this exchange is pretty similar to the function cloneNode(): The
+      particular node is copied on the lowlevel to the opposite DOM
+      implementation.</para>
+      <para>Since the DOM implementations cannot coexist with in one document,
+      one is forced to copy each node that should be used. Because of keeping
+      allways two nodes this may cause quite an impact on a machines memory
+      useage.</para>
+      <para>XML::LibXML provides two functions to export or import GDOME
+      nodes: import_GDOME() and export_GDOME(). Both function have two
+      parameters: the node and a flag for recursive import. The flag works as
+      in cloneNode().</para>
+      <para>The two functions allow to export and import XML::GDOME nodes
+      explicitly, however, XML::LibXML allows also the transparent import of
+      XML::GDOME nodes in functions such as appendChild(), insertAfter() and
+      so on. While native nodes are automaticly adopted in most functions
+      XML::GDOME nodes are allways cloned in advance. Thus if the original
+      node is modified after the operation, the node in the XML::LibXML
+      document will not have this information.</para>
+      <variablelist>
+        <varlistentry>
+          <term>import_GDOME</term>
+          <listitem>
+            <funcsynopsis>
+              <funcsynopsisinfo>$libxmlnode = XML::LibXML-&#62;import_GDOME( $node, $deep );</funcsynopsisinfo>
+            </funcsynopsis>
+            <para>This clones an XML::GDOME node to a XML::LibXML node
+            explicitly.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>export_GDOME</term>
+          <listitem>
+            <funcsynopsis>
+              <funcsynopsisinfo>$gdomenode = XML::LibXML-&#62;export_GDOME( $node, $deep );</funcsynopsisinfo>
+            </funcsynopsis>
+            <para>Allows to clone an XML::LibXML node into a XML::GDOME node.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect1>
+  </chapter>
+  <chapter>
+    <title>Parsing XML Files with XML::LibXML</title>
+    <titleabbrev>XML::LibXML-Parser</titleabbrev>
+    <para></para>
+    <sect1>
+      <title>Parsing</title>
+      <para></para>
+      <sect2>
+        <title>Input Callbacks</title>
+        <para></para>
+      </sect2>
+      <sect2>
+        <title>DOM Parser</title>
+        <para></para>
+      </sect2>
+      <sect2>
+        <title>Push Parser</title>
+        <para>XML::LibXML provides a push parser interface. This allows one to
+        parse large documents without actually loading the entire document
+        into memory. While parse_file() and parse_fh() won&#39;t load the
+        document before parsing either. While parse_file() forces the data to
+        be a wellformed XML file, parse_fh() may be used to parse data comming
+        from any kind of source that delivers wellformed XML documents.
+        parse_fh()&#39;s parsing ability is limited to single documents. For a
+        programmer there is no chance to interrupt the parsing process if for
+        example multiple XML documents are recieved through the same channel.
+        XML::LibXML&#39;s push parser works around this imitation and provides
+        an interface to libxml2&#39;s pushparser. This parser will parse the
+        data the application provides to it at the time they are pushed into
+        the parser, rather than pulling the data itself.</para>
+        <para>Through this it is possible to preprocess incoming data if
+        required - i.e. in the given example to find the document boundaries.
+        Different to the pull parser implemented in parse_fh() or
+        parse_file(), the push parser is not able to find out about the
+        documents end itself. Thus the calling program needs to indicate
+        explicitly when the parsing is done.</para>
+        <para>In XML::LibXML this is done by a single function:</para>
+        <variablelist>
+          <varlistentry>
+            <term>parse_chunk</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$parser-&#62;parse_chunk($string, $terminate);</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>parse_chunk() tries to parse a given chunk of data, which
+              isn&#39;t nessecarily well balanced data. The function takes two
+              parameters: The chunk of data as a string and optional a
+              termination flag. If the termination flag is set to a true value
+              (e.g. 1), the parsing will be stopped and the resulting document
+              will be returned as the following exable describes:</para>
+              <programlisting>my $parser = XML::LibXML-&#62;new;
+for my $string ( &#34;&#60;&#34;, &#34;foo&#34;, &#39; bar=&#34;hello worls&#34;&#39;, &#34;/&#62;&#34;) {
+     $parser-&#62;parse_chunk( $string );
+}
+my $doc = $parser-&#62;parse_chunk(&#34;&#34;, 1); # terminate the parsing</programlisting>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+        <para>Internally XML::LibXML provides three functions that controll
+        the push parser process:</para>
+        <variablelist>
+          <varlistentry>
+            <term>start_push</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$parser-&#62;start_push();</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>Initializes the push parser.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>push</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$parser-&#62;push(@data);</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>This function pushs the data stored inside the array to
+              libxml2&#39;s parse. Each entry in @data must be a normal
+              scalar!</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>finish_push</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$doc = $parser-&#62;finish_push( $recover );</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>This function returns the result of the parsing process.
+              If this function is called without a parameter it will complain
+              about non wellformed documents. If $restore is 1, the push
+              parser can be used to restore broken or non well formed (XML)
+              documents as the following example shows:</para>
+              <programlisting>eval {
+    $parser-&#62;push( &#34;&#60;foo&#62;&#34;, &#34;bar&#34; );
+    $doc = $parser-&#62;finish_push();    # will report broken XML
+};
+if ( $@ ) {
+   # ...
+}</programlisting>
+              <para>This can be anoing if the closing tag misses by accident.
+              The following code will restore the document:</para>
+              <programlisting>eval {
+    $parser-&#62;push( &#34;&#60;foo&#62;&#34;, &#34;bar&#34; );
+    $doc = $parser-&#62;finish_push(1);   # will return the data parsed
+                                      # until an error happend
+};
+
+print $doc-&#62;toString(); # returns &#34;&#60;foo&#62;bar&#60;/foo&#62;&#34;</programlisting>
+              <para>Of course finish_push() will return nothing if there was
+              no data pushed to the parser before.</para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+      </sect2>
+      <sect2>
+        <title>SAX Parser</title>
+        <para></para>
+      </sect2>
+    </sect1>
+    <sect1>
+      <title>Serialization</title>
+      <para></para>
+    </sect1>
+    <sect1>
+      <title>Options</title>
+      <para></para>
+    </sect1>
+    <sect1>
+      <title>Error Reporting</title>
+      <para></para>
+    </sect1>
+  </chapter>
+  <chapter>
+    <title>XML::LibXML direct SAX parser</title>
+    <titleabbrev>XML::LibXML::SAX</titleabbrev>
+    <sect1>
+      <title>Description</title>
+      <para>XML::LibXML provides an interface to libxml2 direct SAX interface.
+      Through this interface it is possible to generate SAX events directly
+      while parsing a document. While using the SAX parser XML::LibXML will
+      not create a DOM Document tree.</para>
+      <para>Such an interface is useful if very large XML documents have to be
+      processed and no DOM functions are required. By using this interface it
+      is possible to read data stored within a XML document directly into the
+      application datastructures without loading the document into memory.</para>
+      <para>The SAX interface of XML::LibXML is based on the famous XML::SAX
+      interface. It uses the generic interface as provided by XML::SAX::Base.</para>
+      <para>Additionaly to the generic functions, that are only able to
+      process entire documents, XML::LibXML::SAX provides
+      <emphasis>parse_chunk()</emphasis>. This method allows to generate SAX
+      events from well ballanced data such as is often provided by databases.</para>
+      <para><emphasis>NOTE:</emphasis> At the moment XML::LibXML provides only
+      an incomplete interface to libxml2&#39;s native SAX implementaion. The
+      current implementation is not tested in production environment. It may
+      causes significant memory problems or shows wrong behaviour.</para>
+    </sect1>
+  </chapter>
+  <chapter>
+    <title>XML::LibXML DOM Implementation</title>
+    <titleabbrev>XML::LibXML-DOM</titleabbrev>
+    <sect1>
+      <title>Description</title>
+      <para>XML::LibXML provides an lightwight interface to
+      <emphasis>modify</emphasis> node of the document tree generated by the
+      XML::LibXML parser. This interface follows as far as possible the DOM
+      Level 3 specification. Additionally to the specified functions the
+      XML::LibXML supports some functions that are more handy to use in the
+      perl environment.</para>
+      <para>One also has to remember, that XML::LibXML is an interface to
+      libxml2 nodes which actually reside on the C-Level of XML::LibXML. This
+      means each node is a reference to a structure different than a perl hash
+      or array. The only way to access these structure&#39;s values is through
+      the DOM interface provided by XML::LibXML. This also means, that one
+      <emphasis>can&#39;t</emphasis> simply inherit a XML::LibXML node and add
+      new member variables as they were hash keys.</para>
+      <para>The DOM interface of XML::LibXML does not intend to implement a
+      full DOM interface as it is done by XML::GDOME and used for full
+      featured application. More it offers an simple way to build or modify
+      documents that are created by XML::LibXML&#39;s parser.</para>
+      <para>Another target of the XML::LibXML interface is to make the
+      interfaces of libxml2 available to the perl community. This includes
+      also some workarounds to some features where libxml2 assumes more
+      control over the C-Level that most perl users don&#39;t have.</para>
+      <para>One of the most important parts of the XML::LibXML DOM interface
+      is, that the interfaces try do follow the DOM Level 3 specification
+      rather strict. This means the interface functions are names as the DOM
+      specification says and not what widespread Java interfaces claim to be
+      standard. Although there are several functions that have only a singular
+      interface that is conform to the DOM spec XML::LibXML provides an
+      additional Java style alias interface.</para>
+      <para>Also there are some function interfaces left over from early
+      stages of XML::LibXML for compatibility reasons. These interfaces are
+      for compatibility reasons <emphasis>only</emphasis>. They might
+      disappear in one of the future versions of XML::LibXML, so a user is
+      requested to switch over the official functions.</para>
+      <para>More recent versions of perl (e.g. 5.6.1 or higher) support
+      special flags to disinguish between UTF8 and so called binary data.
+      XML::LibXML provides for these versions functionality to make efficient
+      use of these flags: If a document has set an encoding other than UTF8
+      all strings that are not already in UTF8 are implicitly encoded from the
+      document encoding to UTF8. On output these strings are commonly returned
+      as UTF8 unless a user does request explicitly the original (aka.
+      document) encoding.</para>
+      <para>Older version of perl (such as 5.00503 or less) do not support
+      these flags. If XML::LibXML is build for these versions, all strings
+      have to get encoded to UTF8 manualy before they are passed to any DOM
+      functions.</para>
+      <para><emphasis>NOTE:</emphasis> XML::LibXML&#39;s magic encoding may
+      not work on all plattforms. Some platforms are known to have a broken
+      iconv(), which is partly used by libxml2. To test if your platform works
+      correctly with your language encoding, build a simple document in the
+      particular encoding and try to parse it with XML::LibXML. If your
+      document gets parsed with out causing any segmentation faults, bus
+      errors or whatever your OS throws. An example for such a test can be
+      found in test 19encoding.t of the distribution.</para>
+      <para><emphasis>Namespaces and XML::LibXML&#39;s DOM implementation</emphasis></para>
+      <para>XML::LibXML&#39;s DOM implementation follows the DOM
+      implementation of libxml2. This is important to know if namespaces are
+      used. Namespaces cannot be declared on an document node. This is basicly
+      because XPath doesn&#39;t know about document nodes. Therefore
+      namespaces have to be declared on element nodes. This can happen
+      explicitly by using XML::LibXML:Element&#39;s setNamespace() function or
+      more or less implicitly by using XML::LibXML::Document&#39;s
+      createElementNS() or createAttributeNS() function. If the a namespace is
+      not declared on the documentElement, the namespace will be localy
+      declared for the newly created node. In case of Attributes this may look
+      a bit confusing, since these nodes cannot have namespace declarations
+      itself. In this case the namespace in internally applied to the
+      attribute and later declared on the node the attribute is appended to.</para>
+      <para>The following example may explain this a bit:</para>
+      <programlisting> my $doc = XML::LibXML-&#62;createDocument;
+ my $root = $doc-&#62;createElementNS( &#34;&#34;, &#34;foo&#34; );
+ $doc-&#62;setDocumentElement( $root );
+
+ my $attr = $doc-&#62;createAttributeNS( &#34;bar&#34;, &#34;bar:foo&#34;, &#34;test&#34; );
+ $root-&#62;setAttributeNodeNS( $attr );               </programlisting>
+      <para>This piece of code will result the following document:</para>
+      <programlisting> &#60;?xml version=&#34;1.0&#34;?&#62;
+ &#60;foo xmlns:bar=&#34;bar&#34; bar:foo=&#34;test&#34;/&#62;</programlisting>
+      <para>Note that the namespace is declared on the document element while
+      the setAttributeNodeNS() call.</para>
+      <para>Here it is important to repeat the specification: While working
+      with namespaces you should use the namespace aware functions instead of
+      the simplified versions. For example you should <emphasis>never</emphasis>
+      use setAttributeNode() but setAttributeNodeNS().</para>
+    </sect1>
+  </chapter>
+  <chapter>
+    <title>XML::LibXML DOM Document Class</title>
+    <titleabbrev>XML::LibXML::Document</titleabbrev>
+    <para>The Document Class is in most cases the result of a parsing process.
+    But sometimes it is necessary to create a Document from scratch. The DOM
+    Document Class provides functions that are conform to the DOM Core naming
+    style.</para>
+    <para>It inherits all functions from <function>XML::LibXML::Node</function>
+    as specified in the DOM specification. This enables to access the nodes
+    beside the root element on document level - a <function>DTD</function> for
+    example. The support for these nodes is limited at the moment.</para>
+    <para>While generaly nodes are bound to a document in the DOM concept it
+    is suggested that one should always create a node not bound to any
+    document. There is no need of really including the node to the document,
+    but once the node is bound to a document, it is quite safe that all
+    strings have the correct encoding. If an unbound textnode with an iso
+    encoded string is created (e.g. with $CLASS-&#62;new()), the
+    <function>toString</function> function may not return the expected result.</para>
+    <para>All this seems like a limitation as long UTF8 encoding is ashured.
+    If iso encoded strings come into play it is much safer to use the node
+    creation functions of <emphasis>XML::LibXML::Document</emphasis>.</para>
+    <variablelist>
+      <varlistentry>
+        <term>new</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$dom = XML::LibXML::Document-&#62;new( $version, $encoding );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>alias for createDocument()</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>createDocument</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$dom = XML::LibXML::Document-&#62;createDocument( $version, $encoding );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>The constructor for the document class. As Parameter it takes
+          the version string and (optionally) the ecoding string. Simply
+          calling <emphasis>createDocument</emphasis>() will create the
+          document:</para>
+          <programlisting>&#60;?xml version=&#34;your version&#34; encoding=&#34;your encoding&#34;?&#62;</programlisting>
+          <para>Both parameter are optional. The default value for
+          <emphasis>$version</emphasis> is <function>1.0</function>, of
+          course. If the <emphasis>$encoding</emphasis> parameter is not set,
+          the encoding will be left unset, which means UTF8 is implied.</para>
+          <para>The call of <emphasis>createDocument</emphasis>() without any
+          parameter will result the following code:</para>
+          <programlisting>&#60;?xml version=&#34;1.0&#34;?&#62;              </programlisting>
+          <para>Alternatively one can call this constructor directly from the
+          XML::LibXML class level, to avoid some typing. This will not cause
+          any effect to the class instance, which is alway
+          XML::LibXML::Document.</para>
+          <programlisting> my $document = XML::LibXML-&#62;createDocument( &#34;1.0&#34;, &#34;UTF8&#34; );</programlisting>
+          <para>is therefore a shortcut for</para>
+          <programlisting>my $document = XML::LibXML::Document-&#62;createDocument( &#34;1.0&#34;, &#34;UTF8&#34; );</programlisting>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>encoding</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$strEncoding = $doc-&#62;encoding();</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>returns the encoding string of the document.</para>
+          <programlisting>my $doc = XML::LibXML-&#62;createDocument( &#34;1.0&#34;, &#34;ISO-8859-15&#34; );
+print $doc-&#62;encoding; # prints ISO-8859-15</programlisting>
+          <para>Optionally this function can be accessed by
+          <emphasis>actualEncoding</emphasis> or <emphasis>getEncoding</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>setEncoding</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$doc-&#62;setEncoding($new_encoding);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>From time to time it is useful to change the effective
+          encoding of a document. This method provides the interface to
+          manipulate the encoding of a document.</para>
+          <para>Note that this function has to be used very careful, since you
+          can&#39;t simply convert one encoding in any other, since some (or
+          even all) characters may not exist in the new encoding. XML::LibXML
+          will not test if the operation is allowed or possible for the given
+          document. The only switching ashured to work is to UTF8.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>version</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$strVersion = $doc-&#62;version();</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>returns the version string of the document</para>
+          <para><emphasis>getVersion()</emphasis> is an alternative form of
+          this function.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>standalone</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$doc-&#62;standalone</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function returns the Numerical value of a documents XML
+          declarations standalone attribute. It returns <emphasis>1</emphasis>
+          if standalone=&#34;yes&#34; was found, <emphasis>0</emphasis> if
+          standalone=&#34;no&#34; was found and <emphasis>-1</emphasis> if
+          standalone was not specified (default on creation).</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>setStandalone</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$doc-&#62;setStandalone($numvalue);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Through this method it is possible to alter the value of a
+          documents standalone attribute. Set it to <emphasis>1</emphasis> to
+          set standalone=&#34;yes&#34;, to <emphasis>0</emphasis> to set
+          standalone=&#34;no&#34; or set it to <emphasis>-1</emphasis> to
+          remove the standalone attribute from the XML declaration.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>compression</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>my $compression = $doc-&#62;compression;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>libxml2 allows to read documents directly from gziped files.
+          In this case the compression variable is set to the compression
+          level of that file (0-8). If XML::LibXML parsed a different source
+          or the file wasn&#39;t compressed, the returned value will be
+          <emphasis>-1</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>setCompression</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$doc-&#62;setCompression($ziplevel);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>If one intends to write the document directly to a file, it is
+          possible to set the compression level for a given document. This
+          level can be in the range from 0 to 8. If XML::LibXML should not try
+          to compress use <emphasis>-1</emphasis> (default).</para>
+          <para>Note that this feature will <emphasis>only</emphasis> work if
+          libxml2 is compiled with zlib support and toFile() is used for
+          output.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>toString</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$docstring = $dom-&#62;toString($format);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para><emphasis>toString</emphasis> is a deparsing function, so the
+          DOM Tree can be translated into a string, ready for output.</para>
+          <para>The optional <emphasis>$format</emphasis> parameter sets the
+          indenting of the output. This parameter is expected to be an
+          <function>integer</function> value, that specifies that indentation
+          should be used. The format parameter can have three different values
+          if it is used:</para>
+          <para>If $format is 0, than the document is dumped as it was
+          originally parsed</para>
+          <para>If $format is 1, libxml2 will add ignoreable whitespaces, so
+          the nodes content is easier to read. Existing text nodes will not be
+          altered</para>
+          <para>If $format is 2 (or higher), libxml2 will act as $format == 1
+          but it add a leading and a trailing linebreak to each text node.</para>
+          <para>libxml2 uses a hardcoded indentation of 2 space characters per
+          indentation level. This value can not be altered on runtime.</para>
+          <para><emphasis>NOTE</emphasis>: XML::LibXML::Document::toString
+          returns the data in the document encoding rather than UTF8! If you
+          want UTF8 ecoded XML, you have to change the conding by using
+          <function>setEncoding()</function></para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>toFile</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$state = $doc-&#62;toFile($filename, $format);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function is similar to toString(), but it writes the
+          document directly into a filesystem. This function is very usefull,
+          if one needs to store large documents.</para>
+          <para>The format parameter has the same behaviour as in toString().</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>toFH</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$state = $doc-&#62;toFH($fh, $format);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function is similar to toString(), but it writes the
+          document directly to a filehandler or a stream.</para>
+          <para>The format parameter has the same behaviour as in toString().</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>toStringHTML</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$document-&#62;toStringHTML();</funcsynopsisinfo>
+          </funcsynopsis>
+          <para><emphasis>toStringHTML</emphasis> deparses the tree to a
+          string as HTML. With this method indenting is automatic and managed
+          by libxml2 internally.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>is_valid</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$bool = $dom-&#62;is_valid();</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Returns either TRUE or FALSE depending on the DOM Tree is a
+          valid Document or not.</para>
+          <para>You may also pass in a XML::LibXML::Dtd object, to validate
+          against an external DTD:</para>
+          <programlisting> if (!$dom-&#62;is_valid($dtd)) {
+     warn(&#34;document is not valid!&#34;);
+ }</programlisting>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>validate</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$dom-&#62;validate();</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This is an exception throwing equivalent of is_valid. If the
+          document is not valid it will throw an exception containing the
+          error. This allows you much better error reporting than simply
+          is_valid or not.</para>
+          <para>Again, you may pass in a DTD object</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>documentElement</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$root = $dom-&#62;documentElement();</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Returns the root element of the Document. A document can have
+          just one root element to contain the documents data.</para>
+          <para>Optionaly one can use <emphasis>getDocumentElement</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>setDocumentElement</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$dom-&#62;setDocumentElement( $root );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function enables you to set the root element for a
+          document. The function supports the import of a node from a
+          different document tree.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>createElement</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$element = $dom-&#62;createElement( $nodename );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function creates a new Element Node bound to the DOM with
+          the name <function>$nodename</function>.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>createElementNS</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$element = $dom-&#62;createElementNS( $namespaceURI, $qname );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function creates a new Element Node bound to the DOM with
+          the name <function>$nodename</function> and placed in the given
+          namespace.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>createTextNode</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$text = $dom-&#62;createTextNode( $content_text );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>As an equivalent of <emphasis>createElement</emphasis>, but it
+          creates a <emphasis>Text Node</emphasis> bound to the DOM.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>createComment</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$comment = $dom-&#62;createComment( $comment_text );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>As an equivalent of <emphasis>createElement</emphasis>, but it
+          creates a <emphasis>Comment Node</emphasis> bound to the DOM.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>createAttribute</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$attrnode = $doc-&#62;createAttribute($name [,$value]);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Creates a new Attribute node.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>createAttributeNS</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$attrnode = $doc-&#62;createAttributeNS( namespaceURI, $name [,$value] );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Creates an Attribute bound to a namespace.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>createDocumentFragment</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$fragment = $doc-&#62;createDocumentFragment()</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function creates a DocumentFragment.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>createCDATASection</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$cdata = $dom-&#62;create( $cdata_content );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Similar to createTextNode and createComment, this function
+          creates a CDataSection bound to the current DOM.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>createProcessingInstruction</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>my $pi = $doc-&#62;createProcessingInstruction( $target, $data );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>create a processing instruction node.</para>
+          <para>Since this method is quite long one may use its short form
+          <emphasis>createPI()</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>createEntityReference</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>my $entref = $doc-&#62;createEntityReference($refname);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>If a docuemnt has a DTD specified, one can create entity
+          refereferences by using this function. If one wants to add a entity
+          reference to the document, this reference has to be created by this
+          function.</para>
+          <para>An entity reference is unique to a document and cannot passed
+          to other documents as other nodes can be passed.</para>
+          <para><emphasis>NOTE:</emphasis> A text content containing something
+          that looks like an entity reference, will not be expanded to a real
+          entity reference unless it is a predefined entity</para>
+          <programlisting> my $string = &#34;&#38;foo;&#34;;
+ $some_element-&#62;appendText( $string );
+ print $some_element-&#62;textContent; # prints &#34;&#38;amp;foo;&#34;</programlisting>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>createInternalSubset</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$dtd = $document-&#62;createInternalSubset( $rootnode, $public, $system);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function creates and adds an internal subset to the given
+          document. Because the function automaticly adds the DTD to the
+          document there is no need to add the created node explicitly to the
+          document.</para>
+          <programlisting> my $document = XML::LibXML::Document-&#62;new();
+ my $dtd      = $document-&#62;createInternalSubset( &#34;foo&#34;, undef, &#34;foo.dtd&#34; );</programlisting>
+          <para>will result in the following XML document:</para>
+          <programlisting>&#60;?xml version=&#34;1.0&#34;?&#62;
+ &#60;!DOCTYPE foo SYSTEM &#34;foo.dtd&#34;&#62;                    </programlisting>
+          <para>By setting the public parameter it is possible to set PUBLIC
+          dtds to a given document. So</para>
+          <programlisting>my $document = XML::LibXML::Document-&#62;new();
+my $dtd      = $document-&#62;createInternalSubset( &#34;foo&#34;, &#34;-//FOO//DTD FOO 0.1//EN&#34;, undef );
+</programlisting>
+          <para>will cause the following declaration to be created on the
+          document:</para>
+          <programlisting>&#60;?xml version=&#34;1.0&#34;?&#62;
+&#60;!DOCTYPE foo PUBLIC &#34;-//FOO//DTD FOO 0.1//EN&#34;&#62;</programlisting>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>createExternalSubset</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$dtd = $document-&#62;createExternalSubset( $rootnode, $public, $system);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function is similar to <function>createInternalSubset()</function>
+          but this DTD is concidered to be external and is therefore not added
+          to the document itself. Nevertheless it can be used for validation
+          purposes.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>importNode</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$document-&#62;importNode( $node );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>If a node is not part of a document, it can be imported to
+          another document. As specified in DOM Level 2 Specification the Node
+          will not be altered or removed from its original document (<function>$node-&#62;cloneNode(1)</function>
+          will get called implicitly).</para>
+          <para><emphasis>NOTE:</emphasis> Don&#39;t try to use importNode()
+          to import subtrees that contain an entity reference - even if the
+          entity reference is the root node of the subtree. This will cause
+          serious problems to your program. This is a limitation of libxml2
+          and not of XML::LibXML itself.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>adoptNode</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$document-&#62;adoptNode( $node );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>If a node is not part of a document, it can be imported to
+          another document. As specified in DOM Level 3 Specification the Node
+          will not be altered but it will removed from its original document.</para>
+          <para>After a document adopted a node, the node, its attributes and
+          all its descendants belong to the new document. Because the node
+          does not belong to the old document, it will be unlinked from its
+          old location first.</para>
+          <para><emphasis>NOTE:</emphasis> Don&#39;t try to adoptNode() to
+          import subtrees that contain entity references - even if the entity
+          reference is the root node of the subtree. This will cause serious
+          problems to your program. This is a limitation of libxml2 and not of
+          XML::LibXML itself.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>externalSubset</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>my $dtd = $doc-&#62;externalSubset;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>If a document has an external subset defined it will be
+          returned by this function.</para>
+          <para><emphasis>NOTE</emphasis> Dtd nodes are no ordinary nodes in
+          libxml2. The support for these nodes in XML::LibXML is still
+          limited. In particular one may not want use common node function on
+          doctype declaration nodes!</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>internalSubset</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>my $dtd = $doc-&#62;internalSubset;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>If a document has an internal subset defined it will be
+          returned by this function.</para>
+          <para><emphasis>NOTE</emphasis> Dtd nodes are no ordinary nodes in
+          libxml2. The support for these nodes in XML::LibXML is still
+          limited. In particular one may not want use common node function on
+          doctype declaration nodes!</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>setExternalSubset</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$doc-&#62;setExternalSubset($dtd);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para><emphasis>EXPERIMENTAL!</emphasis></para>
+          <para>This method sets a DTD node as an external subset of the given
+          document.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>setInternalSubset</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$doc-&#62;setInternalSubset($dtd);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para><emphasis>EXPERIMENTAL!</emphasis></para>
+          <para>This method sets a DTD node as an internal subset of the given
+          document.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>removeExternalSubset</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>my $dtd = $doc-&#62;removeExternalSubset();</funcsynopsisinfo>
+          </funcsynopsis>
+          <para><emphasis>EXPERIMENTAL!</emphasis></para>
+          <para>If a document has an external subset defined it can be removed
+          from the document by using this function. The removed dtd node will
+          be returned.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>removeInternalSubset</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>my $dtd = $doc-&#62;removeInternalSubset();</funcsynopsisinfo>
+          </funcsynopsis>
+          <para><emphasis>EXPERIMENTAL!</emphasis></para>
+          <para>If a document has an internal subset defined it can be removed
+          from the document by using this function. The removed dtd node will
+          be returned.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>getElementsByTagName</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>my @nodelist = $doc-&#62;getElementsByTagName($tagname);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Implements the DOM Level 2 function</para>
+          <para>In SCALAR context this function returns a
+          <function>XML::LibXML::NodeList</function> object.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>getElementsByTagNameNS</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>my @nodelist = $doc-&#62;getElementsByTagName($nsURI,$tagname);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Implements the DOM Level 2 function</para>
+          <para>In SCALAR context this function returns a
+          <function>XML::LibXML::NodeList</function> object.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>getElementsByLocalName</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>my @nodelist = $doc-&#62;getElementsByLocalName($localname);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This allows to fetch all nodes from a given document with the
+          given Localname.</para>
+          <para>In SCALAR context this function returns a
+          <function>XML::LibXML::NodeList</function> object.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </chapter>
+  <chapter>
+    <title>Abstract Base Class of XML::LibXML Nodes</title>
+    <titleabbrev>XML::LibXML::Node</titleabbrev>
+    <para>XML::LibXML::Node defines functions that are common to all Node
+    Types. A LibXML::Node should never be created standalone, but as an
+    instance of a high level class such as LibXML::Element or LibXML::Text.
+    The class itself should provide only common functionality. In XML::LibXML
+    each node is part either of a document or a document-fragment. Because of
+    this there is no node without a parent. This may causes confusion with
+    &#34;unbound&#34; nodes.</para>
+    <variablelist>
+      <varlistentry>
+        <term>nodeName</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$name = $node-&#62;nodeName;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Returns the node&#39;s name. This Function is aware about
+          namesaces and returns the full name of the current node (<function>prefix:localname</function>)</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>setNodeName</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node-&#62;setNodeName( $newName );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>In very limited situation it is usefull to change a nodes
+          name. In the DOM specification this should throw an error. This
+          Function is aware about namespaces.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>isSameNode</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$bool = $node-&#62;isSameNode( $other_node );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>returns TRUE (1) if the given nodes refer to the same node
+          structure, otherwise FALSE (0) is returned.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>isEqual</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$bool = $node-&#62;isEqual( $other_node );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>depraced version of isSameNode().</para>
+          <para><emphasis>NOTE</emphasis> isEqual will change behaviour to
+          follow the DOM specification</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>nodeValue</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$content = $node-&#62;nodeValue;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>If the node has any content (such as stored in a
+          <function>text node</function>) it can get requested through this
+          function.</para>
+          <para><emphasis>NOTE:</emphasis> Element Nodes have no content per
+          definition. To get the text value of an Element use textContent()
+          instead!</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>textContent</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$content = $node-&#62;textContent;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>this function returns the content of all text nodes in the
+          descendants of the given node as spacified in DOM.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>nodeType</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$type = $node-&#62;nodeType;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Retrun the node&#39;s type. The possible types are described
+          in the libxml2 <emphasis>tree.h</emphasis> documentation. The return
+          value of this function is a numeric value. Therefore it differst
+          with the result of perl ref function.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>unbindNode</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node-&#62;unbindNode()</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Unbinds the Node from its siblings and Parent, but not from
+          the Document it belongs to. If the node is not inserted into the DOM
+          afterwards it will be lost after the programm terminated. From a low
+          level view, the unbound node is stripped from the context it is and
+          inserted into a (hidden) document-fragment.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>removeChild</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$childnode = $node-&#62;removeChild( $childnode )</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This will unbind the Child Node from its parent
+          <function>$node</function>. The function returns the unbound node.
+          If <function>oldNode</function> is not a child of the given Node the
+          function will fail.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>replaceChild</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$oldnode = $node-&#62;replaceChild( $newNode, $oldNode )</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Replaces the <function>$oldNode</function> with the
+          <function>$newNode</function>. The <function>$oldNode</function>
+          will be unbound from the Node. This function differs from the DOM L2
+          specification, in the case, if the new node is not part of the
+          document, the node will be imported first.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>replaceNode</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node-&#62;replaceNode($newNode);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function is very similar to replaceChild(), but it
+          replaces the node itself rather than a childnode. This is useful if
+          a node found by any XPath function, should be replaced.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>appendChild</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$childnode = $node-&#62;appendChild( $childnode );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>The function will add the <function>$childnode</function> to
+          the end of <function>$node</function>&#39;s children. The function
+          should fail, if the new childnode is allready a child of
+          <function>$node</function>. This function differs from the DOM L2
+          specification, in the case, if the new node is not part of the
+          document, the node will be imported first.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>addChild</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$childnode = $node-&#62;addChild( $chilnode );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>As an alternative to appendChild() one can use the addChild()
+          function. This function is a bit faster, because it avoids all DOM
+          confomity checks. Therefore this function is quite usefull if one
+          builds XML documents in memory where the order and ownership (<function>ownerDocument</function>)
+          is ashured.</para>
+          <para>addChild() uses libxml2&#39;s own xmlAddChild() function. Thus
+          it has to be used with extra care: If a text node is added to a node
+          and the node itself or its last childnode is aswell a text node, the
+          node to add will be merged with the one already available. The
+          current node will be removed from memory after this action. Because
+          perl is not aware about this action, the perl instance is still
+          available. XML::LibXML will catch the loss of a node an avoid to run
+          any function called on that node.</para>
+          <programlisting> my $t1 = $doc-&#62;createTextNode( &#34;foo&#34; );
+ my $t2 = $doc-&#62;createTextNode( &#34;bar&#34; );
+ $t1-&#62;addChild( $t2 );       # is ok
+ my $val = $t2-&#62;nodeValue(); # will fail, script dies</programlisting>
+          <para>Also addChild() will not check it the added node belongs to
+          the same document as the node it will be added to. This could lead
+          to inconsistent documents and in more worse cases even to memory
+          violations, if one does not keep track of this issue.</para>
+          <para>Although this sounds like a lot of trouble, addChild() is
+          usefull if a document is build from a stream, such as happens
+          sometimes in SAX handlers or filters.</para>
+          <para>If you are not shure about the source of your nodes, you
+          better stay with appendChild(), because this function is more user
+          friendly in the sense of more error tolerance.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>addNewChild</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node = $parent-&#62;addNewChild( $nsURI, $name );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Similar to <function>addChild()</function>, this function uses
+          low level libxml2 functionality to provide faster interface for DOM
+          building. <emphasis>addNewChild()</emphasis> uses
+          <function>xmlNewChild()</function> to create a new node on a given
+          parent element.</para>
+          <para>addNewChild() has two parameters $nsURI and $name, where
+          $nsURI is an (optional) namespace URI. $name is the fully qualified
+          element name; addNewChild() will determine the correct prefix if
+          nessecary.</para>
+          <para>The function returns the newly created node.</para>
+          <para>This function is very usefull for DOM building, where a
+          created node can be directly associated to its parent.
+          <emphasis>NOTE</emphasis> this function is not part of the DOM
+          specification and its use will limit your code to XML::LibXML.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>addSibling</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node-&#62;addSibling($newNode);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>addSibling() allows to add an additional node to the end of a
+          nodelist, defined by the given node.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>cloneNode</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$newnode =$node-&#62;cloneNode( $deep )</funcsynopsisinfo>
+          </funcsynopsis>
+          <para><emphasis>cloneNode</emphasis> creates a copy of
+          <function>$node</function>. Wether $deep is set to 1 (true) the
+          function will copy all childnodes as well. If $deep is 0 only the
+          current node will be copied.</para>
+          <para><emphasis>cloneNode</emphasis> will not copy any namespace
+          information if it is not run recursivly.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>parentNode</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$parentnode = $node-&#62;parentNode;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Returns simply the Parent Node of the current node.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>nextSibling</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$nextnode = $node-&#62;nextSibling()</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Returns the next sibling if any .</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>previousSibling</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$prevnode = $node-&#62;previousSibling()</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Analogous to <emphasis>getNextSibling</emphasis> the function
+          returns the previous sibling if any.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>hasChildNodes</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$boolean = $node-&#62;hasChildNodes();</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>If the current node has Childnodes this function returns TRUE
+          (1), otherwise it returns FALSE (0, not undef).</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>firstChild</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$childnode = $node-&#62;firstChild;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>If a node has childnodes this function will return the first
+          node in the childlist.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>lastChild</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$childnode = $node-&#62;lastChild;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>If the <function>$node</function> has childnodes this function
+          returns the last child node.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>ownerDocument</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$documentnode = $node-&#62;ownerDocument;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Through this function it is allways possible to access the
+          document the current node is bound to.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>getOwner</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node = $node-&#62;getOwner;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function returns the node the current node is associated
+          with. In the very most cases this will be a document node or a
+          document fragment node.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>setOwnerDocument</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node-&#62;setOwnerDocument( $doc );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function binds a node to another DOM. This method unbinds
+          the node first, if it is allready bound to another document.</para>
+          <para>This function is the oposite calling of
+          XML::LibXML::Document&#39;s adoptNode() function. Because of this it
+          has the same limitations with Entity References as adoptNode().</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>insertBefore</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node-&#62;insertBefore( $newNode, $refNode )</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>The method inserts <function>$newNode</function> before
+          <function>$refNode</function>. If <function>$refNode</function> is
+          undefined, the newNode will be set as the new first child of the
+          parent node. This function differs from the DOM L2 specification, in
+          the case, if the new node is not part of the document, the node will
+          be imported first.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>insertAfter</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node-&#62;insertAfter( $newNode, $refNode )</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>The method inserts <function>$newNode</function> after
+          <function>$refNode</function>. If <function>$refNode</function> is
+          undefined, the newNode will be set as the new last child of the
+          parent node.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>findnodes</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>@nodes = $node-&#62;findnodes( $xpath_statement );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para><emphasis>findnodes</emphasis> performs the xpath statement on
+          the current node and returns the result as an array. In scalar
+          context returns a <function>XML::LibXML::NodeList</function> object.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>find</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$result = $node-&#62;find( $xpath );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para><emphasis>find</emphasis> performs the xpath expression using
+          the current node as the context of the expression, and returns the
+          result depending on what type of result the XPath expression had.
+          For example, the XPath &#34;1 * 3 + 52&#34; results in a
+          <function>XML::LibXML::Number</function> object being returned.
+          Other expressions might return a <function>XML::LibXML::Boolean</function>
+          object, or a <function>XML::LibXML::Literal</function> object (a
+          string). Each of those objects uses Perl&#39;s overload feature to
+          &#34;do the right thing&#34; in different contexts.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>findvalue</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>print $node-&#62;findvalue( $xpath );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para><emphasis>findvalue</emphasis> is exactly equivalent to:</para>
+          <programlisting> $node-&#62;find( $xpath )-&#62;to_literal;              </programlisting>
+          <para>That is, it returns the literal value of the results. This
+          enables you to ensure that you get a string back from your search,
+          allowing certain shortcuts. This could be used as the equivalent of
+          XSLT&#39;s &#60;xsl:value-of select=&#34;some_xpath&#34;/&#62;.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>childNodes</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>@childnodes = $node-&#62;childNodes;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para><emphasis>getChildnodes</emphasis> implements a more intuitive
+          interface to the childnodes of the current node. It enables you to
+          pass all children directly to a <function>map</function> or
+          <function>grep</function>. If this function is called in scalar
+          context, a <function>XML::LibXML::NodeList</function> object will be
+          returned.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>toString</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$xmlstring = $node-&#62;toString($format,$docencoding);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This is the equivalent to <function>XML::LibXML::Document::toString</function>
+          for a single node. This means a node and all its childnodes will be
+          dumped into the result string.</para>
+          <para>Additionally to the $format flag of XML::LibXML::Document,
+          this version accepts the optional $docencoding flag. If this flag is
+          set this function returns the string in its original encoding (the
+          encoding of the document) rather than UTF8.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>localname</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$localname = $node-&#62;localname;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Returns the local name of a tag. This is the part behind the
+          colon.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>prefix</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$nameprefix = $node-&#62;prefix;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Returns the prefix of a tag. This is the part before the
+          colon.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>namespaceURI</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$uri = $node-&#62;namespaceURI()</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>returns the URI of the current namespace.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>hasAttributes</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$boolean = $node-&#62;hasAttributes();</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>returns 1 (TRUE) if the current node has any attributes set,
+          otherwise 0 (FALSE) is returned.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>attributes</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>@attributelist = $node-&#62;attributes();</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function returns all attributes and namespace
+          declarations assigned to the given node.</para>
+          <para>Because XML::LibXML does not implement namespace declarations
+          and attributes the same way, it is required to test what kind of
+          node is handled while accessing the functions result.</para>
+          <para>If this function is called in array context the attribute
+          nodes are returned as an array. In scalar context the function will
+          return a <function>XML::LibXML::NamedNodeMap</function> object.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>lookupNamespaceURI</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$URI = $node-&#62;lookupNamespaceURI( $prefix );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Find a namespace URI by its prefix starting at the current
+          node.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>lookupNamespacePrefix</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$prefix = $node-&#62;lookupNamespacePrefix( $URI );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Find a namespace prefix by its URI starting at the current
+          node.</para>
+          <para><emphasis>NOTE</emphasis> Only the namespace URIs are ment to
+          be unique. The prefix is only document related. also document might
+          has more than a single prefix defined for a namespace.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>iterator</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$iter = $node-&#62;iterator;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function is depraced sind XML::LibXML 1.54. It is only a
+          dummyfunction that will get removed entirely in one of the next
+          versions.</para>
+          <para>To make use of iterator functions use XML::LibXML::Iterator
+          Module available on CPAN.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>normalize</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node-&#62;normalize;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function normalizes adjacent textnodes. This function is
+          not as strict as libxml2&#39;s xmlTextMerge() function, since it
+          will not free a node that is still refered by the perl layer.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>getNamespaces</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>@nslist = $node-&#62;getNamespaces;</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>If a node has any namespaces defined, this function will
+          return these namespaces. Note, that this will not return all
+          namespaces that are in scope, but only the ones declares explicitly
+          for that node.</para>
+          <para>Although getNamespaces is available for all nodes, it makes
+          only sense if used with element nodes.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>removeChildNodes</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node-&#62;removeChildNodes();</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function is not specified for any DOM level: It removes
+          all childnodes from a node in a single step. Other than the libxml2
+          function itself (xmlFreeNodeList), this function will not imediatly
+          remove the nodes from the memory. This safes one from getting memory
+          violations, if there are nodes still refered from the Perl level.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </chapter>
+  <chapter>
+    <title>XML::LibXML Class for Element Nodes</title>
+    <titleabbrev>XML::LibXML::Element</titleabbrev>
+    <variablelist>
+      <varlistentry>
+        <term>new</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node = XML::LibXML::Element-&#62;new( $name )</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function creates a new node unbound to any DOM.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>setAttribute</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node-&#62;setAttribute( $aname, $avalue );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This method sets or replaces the node&#39;s attribute
+          <function>$aname</function> to the value <function>$avalue</function></para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>setAttributeNS</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node-&#62;setAttributeNS( $nsURI, $aname, $avalue );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Namespaceversion of <function>setAttribute</function>.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>getAttribute</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$avalue = $node-&#62;getAttribute( $aname );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>If <function>$node</function> has an attribute with the name
+          <function>$aname</function>, the value of this attribute will get
+          returned.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>getAttributeNS</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$avalue = $node-&#62;setAttributeNS( $nsURI, $aname );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Namespaceversion of <function>getAttribute</function>.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>getAttributeNode</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$attrnode = $node-&#62;getAttributeNode( $aname );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Returns the attribute as a node if the attribute exists. If
+          the Attribute does not exists <function>undef</function> will be
+          returned.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>getAttributeNodeNS</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$attrnode = $node-&#62;getAttributeNodeNS( $namespaceURI, $aname );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Namespaceversion of <function>getAttributeNode</function>.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>removeAttribute</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node-&#62;removeAttribute( $aname );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>The method removes the attribute <function>$aname</function>
+          from the node&#39;s attribute list, if the attribute can be found.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>removeAttributeNS</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$node-&#62;removeAttributeNS( $nsURI, $aname );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Namespace version of <function>removeAttribute</function></para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>hasAttribute</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$boolean = $node-&#62;hasAttribute( $aname );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This funcion tests if the named attribute is set for the node.
+          If the attribute is specified, TRUE (1) will be returned, otherwise
+          the returnvalue is FALSE (0).</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>hasAttributeNS</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>$boolean = $node-&#62;hasAttributeNS( $nsURI, $aname );</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>namespace version of <function>hasAttribute</function></para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>getChildrenByTagName</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>@nodes = $node-&#62;getChildrenByTagName($tagname);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>The function gives direct access to all childnodes of the
+          current node with the same tagname. It makes things a lot easier if
+          you need to handle big datasets.</para>
+          <para>If this function is called in SCALAR context, it returns the
+          number of Elements found.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>getChildrenByTagNameNS</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>@nodes = $node-&#62;getChildrenByTagNameNS($nsURI,$tagname);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Namespace version of <function>getChildrenByTagName</function>.</para>
+          <para>If this function is called in SCALAR context, it returns the
+          number of Elements found.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>getElementsByTagName</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>@nodes = $node-&#62;;getElementsByTagName($tagname);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function is part of the spec it fetches all descendants
+          of a node with a given tagname. If one is as confused with
+          <function>tagname</function> as I was, tagname is a qualified
+          tagname which is in case of namespace useage prefix and local name</para>
+          <para>In SCALAR context this function returns a
+          <function>XML::LibXML::NodeList</function> object.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>getElementsByTagNameNS</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>@nodes = $node-&#62;getElementsByTagNameNS($nsURI,$localname);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>Namespace version of <function>getElementsByTagName</function>
+          as found in the DOM spec.</para>
+          <para>In SCALAR context this function returns a
+          <function>XML::LibXML::NodeList</function> object.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>getElementsByLocalName</term>
+        <listitem>
+          <funcsynopsis>
+            <funcsynopsisinfo>@nodes = $node-&#62;getElementsByLocalName($localname);</funcsynopsisinfo>
+          </funcsynopsis>
+          <para>This function is not found in the DOM specification. It is a
+          mix of getElementsByTagName and getElementsByTagNameNS. It will
+          fetch all tags matching the given local-name. This alows one to
+          select tags with the same local name across namespace borders.</para>
+          <para>In SCALAR context this function returns a
+          <function>XML::LibXML::NodeList</function> object.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <varlistentry>
+        <term>appendWellBalancedChunk</term>