Commits

ph...@9ae0c189-cd1f-4510-a509-f4891f5cf20d  committed 04cb0fd

Modified Files:
LibXML.xs
+ default namespace bug

Changes
+ version notes

example/libxml.dkb
+ finalized parser documentation
+ chapter for XML::LibXML::SAX::Builder
o cleaned up a bit

LibXML.pm
lib/XML/LibXML/SAX/Parser.pm
lib/XML/LibXML/SAX/Builder.pm
- pod section moved to the docbook source
o removed/improved some parts in the related documentation

  • Participants
  • Parent commits 245ab71

Comments (0)

Files changed (6)

 
 1.55
    - Added C14N interface "toStringC14N()" (thanks to Chip Turner)
+   - fixed default namespace bug with libxml2 2.5.8 (by Vaclav Barta)
    - fixed a NOOP in the XPath code.
    - fixed insertBefore() behaviour to be DOM conform
    - fixed a minor problem in Makefile.PL
-   - converted documentation to DocBook   
+   - converted documentation to DocBook
 
 1.54
    - fixed some major bugs, works now with libxml2 2.5.x
      (after realizing some CPAN testers refuse to read their warnings
      from Makefile.PL)
    - improved parser testsuite
-   - improved Makefile.PL
+   - improved M
    - more documentation 
 
 1.53
 # XML::LibXML Parser documentation                                        #
 #-------------------------------------------------------------------------#
 __END__
-
-=head1 NAME
-
-XML::LibXML - Interface to the gnome libxml2 library
-
-=head1 SYNOPSIS
-
-  use XML::LibXML;
-  my $parser = XML::LibXML->new();
-
-  my $doc = $parser->parse_string(<<'EOT');
-  <some-xml/>
-  EOT
-
-=head1 DESCRIPTION
-
-This module is an interface to the gnome libxml2 DOM parser (no SAX
-parser support yet), and the DOM tree. It also provides an
-XML::XPath-like findnodes() interface, providing access to the XPath
-API in libxml2.
-
-=head1 OPTIONS
-
-LibXML options are global (unfortunately this is a limitation of the
-underlying implementation, not this interface). They can either be set
-using C<$parser-E<gt>option(...)>, or C<XML::LibXML-E<gt>option(...)>, both
-are treated in the same manner. Note that even two forked processes
-will share some of the same options, so be careful out there!
-
-Every option returns the previous value, and can be called without
-parameters to get the current value.
-
-=head2 validation
-
-  $parser->validation(1);
-
-Turn validation on (or off). Defaults to off.
-
-=head2 recover
-
-  $parser->recover(1);
-
-Turn the parsers recover mode on (or off). Defaults to off.
-
-This allows to parse broken XML data into memory.  This switch will
-only work with XML data rather than HTML data. Also the validation
-will be switched off automaticly.
-
-The recover mode helps to recover documents that are almost wellformed
-very efficiently. That is for example a document that forgets to close
-the document tag (or any other tag inside the document). The recover
-mode of XML::LibXML has problems though to restore documents that are
-more like well ballanced chunks. In that case XML::LibXML will only
-parse the first tag of the chunk.
-
-=head2 expand_entities
-
-  $parser->expand_entities(0);
-
-Turn entity expansion on or off, enabled by default. If entity expansion
-is off, any external parsed entities in the document are left as entities.
-Probably not very useful for most purposes.
-
-=head2 keep_blanks
-
- $parser->keep_blanks(0);
-
-Allows you to turn off XML::LibXML's default behaviour of maintaining
-whitespace in the document.
-
-=head2 pedantic_parser
-
-  $parser->pedantic_parser(1);
-
-You can make XML::LibXML more pedantic if you want to.
-
-=head2 load_ext_dtd
-
-  $parser->load_ext_dtd(1);
-
-Load external DTD subsets while parsing.
-
-=head2 complete_attributes
-
-  $parser->complete_attributes(1);
-
-Complete the elements attributes lists with the ones defaulted from the DTDs.
-By default, this option is enabled.
-
-=head2 expand_xinclude
-
-  $parser->expand_xinclude
-
-Expands XIinclude tags imidiatly while parsing the document. This flag
-ashures that the parser callbacks are used while parsing the included
-Document.
-
-=head2 load_catalog
-
-  $parser->load_catalog( $catalog_file );
-
-Will use $catalog_file as a catalog during all parsing
-processes. Using a catalog will significantly speed up parsing
-processes if many external ressources are loaded into the parsed
-documents (such as DTDs or XIncludes)
-
-Note that catalogs will not be available if an external entity handler
-was specified. At the current state it is not possible to make use of
-both types of resolving systems at the same time.
-
-=head2 base_uri
-
-  $parser->base_uri( $your_base_uri );
-
-In case of parsing strings or file handles, XML::LibXML doesn't know
-about the base uri of the document. To make relative references such as
-XIncludes work, one has to set a separate base URI, that is then used for
-the parsed documents.
-
-=head2 gdome_dom
-
-  $parser->gdome_dom(1);
-
-Although quite powerful XML:LibXML's DOM implementation is limited if
-one needs or wants full DOM level 2 or level 3 support. XML::GDOME is
-based on libxml2 as well but provides a rather complete DOM
-implementation by wrapping libgdome. This allows you to make use of
-XML::LibXML's full parser options and XML::GDOME's DOM implementation
-at the same time.
-
-All XML::LibXML parser functions recognize this switch.
-
-=head2 match_callback
-
-  $parser->match_callback($subref);
-
-Sets a "match" callback. See L<"Input Callbacks"> below.
-
-=head2 open_callback
-
-  $parser->open_callback($subref);
-
-Sets an open callback. See L<"Input Callbacks"> below.
-
-=head2 read_callback
-
-  $parser->read_callback($subref);
-
-Sets a read callback. See L<"Input Callbacks"> below.
-
-=head2 close_callback
-
-  $parser->close_callback($subref);
-
-Sets a close callback. See L<"Input Callbacks"> below.
-
-=head1 CONSTRUCTOR
-
-The XML::LibXML constructor, C<new()>, takes the following parameters:
-
-=head2 ext_ent_handler
-
-  my $parser = XML::LibXML->new(ext_ent_handler => sub { ... });
-
-The ext_ent_handler sub is called whenever libxml needs to load an external
-parsed entity. The handler sub will be passed two parameters: a
-URL (SYSTEM identifier) and an ID (PUBLIC identifier). It should return
-a string containing the resource at the given URI.
-
-Note that you do not need to enable this - if not supplied libxml will
-get the resource either directly from the filesystem, or using an internal
-http client library.
-
-=head2 catalog
-
-  my $parser = XML::LibXML->new( catalog => $private_catalog );
-
-Alternatively to ext_ent_handler the catalog parameter allows to use
-libxml2's catalog interface directly. The parameter takes a filename
-to a catalog file. This catalog is loaded by libxml2 and will be used
-during parsing processes.
-
-Note that catalogs will not be available if an external entity handler
-was specified. At the current state it is not possible to make use of
-both types of resolving systems at the same time.
-
-=head1 DEFAULT VALUES
-
-The following table gives an overview about the default values of the
-parser attributes.
-
-=over 4
-
-=item validation == off (0)
-
-=item recover == off (0)
-
-=item expand_entities == on (1)
-
-=item keep_blanks == on (1)
-
-=item pedantic_parser == off (0)
-
-=item load_ext_dtd == on (1)
-
-=item complete_attributes == on (1)
-
-=item expand_xinclude == off (0)
-
-=item base_uri == ""
-
-=item gdome_dom == off (0)
-
-=back
-
-By default no callback handler is set.
-
-=head1 PARSING
-
-There are three ways to parse documents - as a string, as a Perl
-filehandle, or as a filename. The return value from each is a
-XML::LibXML::Document object, which is a DOM object (although not all
-DOM methods are implemented yet). See L<"XML::LibXML::Document"> below
-for more details on the methods available on documents.
-
-Each of the below methods will throw an exception if the document is invalid.
-To prevent this causing your program exiting, wrap the call in an eval{}
-block.
-
-=head2 parse_string
-
-  my $doc = $parser->parse_string($string);
-
-or, passing in a directory to use as the "base":
-
-  my $doc = $parser->parse_string($string, $dir);
-
-=head2 parse_fh
-
-  my $doc = $parser->parse_fh($fh);
-
-Here, C<$fh> can be an IOREF, or a subclass of IO::Handle.
-
-And again, you can pass in a directory as the "base":
-
-  my $doc = $parser->parse_fh($fh, $dir);
-
-Note in the above two cases, $dir must end in a trailing slash,
-otherwise the parent of that directory is used. This can actually
-be useful, in that it will accept the filename of what you're
-parsing.
-
-=head2 parse_file
-
-  my $doc = $parser->parse_file($filename);
-
-This function reads an absolute filename into the memory. It causes
-XML::LibXML to use libxml2's file parser instead of letting perl
-reading the file such as with parse_fh(). If you need to parse files
-directly, this function would be the faster choice, since this function
-is about 6-8 times faster then parse_fh().
-
-=head2 Parsing Html
-
-As of version 0.96, XML::LibXML is capable of parsing HTML into a
-regular XML DOM. This gives you the full power of XML::LibXML on HTML
-documents.
-
-The methods work in exactly the same way as the methods above, and
-return exactly the same type of object. If you wish to dump the
-resulting document as HTML again, you can use C<$doc->toStringHTML()>
-to do that.
-
-=head2 parse_html_string
-
-  my $doc = $parser->parse_html_string($string);
-
-=head2 parse_html_fh
-
-  my $doc = $parser->parse_html_fh($fh);
-
-=head2 parse_html_file
-
-  my $doc = $parser->parse_html_file($filename);
-
-=head2 The Push Parser
-
-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'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()'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's push parser works around this
-limitation and provides an interface to libxml2'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.
-
-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.
-
-In XML::LibXML this is done by a single function:
-
-  parse_chunk()
-
-parse_chunk() tries to parse a given chunk of data, which isn't
-nessecarily well balanced data. The function takes two parameters:
-
-=over 4
-
-=item 1. the chunk of data as a single string
-
-=item 2. (optional) a termination flag
-
-=back
-
-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.
-
-the following example may clearify this a bit:
-
-  my $parser = XML::LibXML->new;
-
-  for my $string ( "<", "foo", ' bar="hello worls"', "/>") {
-       $parser->parse_chunk( $string );
-  }
-  my $doc = $parser->parse_chunk("", 1); # terminate the parsing
-
-Internally the push parser uses two functions, push() and finish_push().
-they are not very usefull expect one likes to write a repairing parser.
-How to do this is described in the following part.
-
-Of course XML::LibXML's push parser is available as a SAX parser as
-well. To make use of the SAX capabilities one must any the SAX as the
-parsers SAX handler; otherwise parse_chunk() will work in the default
-mode.
-
-=over 4
-
-=item $parser->push( @data )
-
-This function pushs the data stored inside the array to libxml2's
-parse. Each entry in @data must be a normal scalar!
-
-=item $parser->finish_push( $restore );
-
-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:
-
-  eval {
-      $parser->push( "<foo>", "bar" );
-      $doc = $parser->finish_push();    # will report broken XML
-  };
-  if ( $@ ) {
-     # ...
-  }
-
-This can be anoing if the closing tag misses by accident. The
-following code will restore the document:
-
-  eval {
-      $parser->push( "<foo>", "bar" );
-      $doc = $parser->finish_push(1);   # will return the data parsed
-                                        # until an error happend
-  };
-  warn $doc->toString(); # returns "<foo>bar</foo>"
-
-of course finish_push() will return nothing if there was no data pushed to
-the parser before.
-
-=back
-
-=head2 Extra parsing methods
-
-B<processXIncludes>
-
-  $parser->processXIncludes( $doc );
-
-While the document class implements a separate XInclude processing,
-this method, is stricly related to the parser. The use of this method
-is only required, if the parser implements special callbacks that
-should to be used for the XInclude as well.
-
-If expand_xincludes is set to 1, the method is only required to process
-XIncludes appended to the DOM after its original parsing.
-
-=head2 Error Handling
-
-XML::LibXML throws exceptions during parseing, validation or XPath
-processing. These errors can be catched by useing eval blocks. The
-error then will be stored in B<$@>. Alternatively one can use the
-get_last_error() function of XML::LibXML. It will return the same
-string that is stored in $@. Using get_last_error() makes it still
-nessecary to eval the statement, since these function groups will
-die() on errors.
-
-get_last_error() can be called either by the class itself or by a
-parser instance:
-
-   $errstring = XML::LibXML->get_last_error();
-   $errstring = $parser->get_last_error();
-
-Note that XML::LibXML exceptions are global. That means if
-get_last_error is called on an parser instance, the last B<global>
-error will be returned. This is not nessecarily the error caused by
-the parser instance itself.
-
-=head2 Serialization
-
-The oposite of parsing is serialization. In XML::LibXML this can be
-done by using the functions toString(), toFile() and toFH(). All
-serialization functions understand the flag setTagCompression. if this
-Flag is set to 1 empty tags are displayed as <foo></foo>
-rather than <foo/>.
-
-toString() additionally checks two other flags:
-
-skipDTD and skipXMLDeclaration
-
-If skipDTD is specified and any DTD node is found in the document this
-will not be serialized.
-
-If skipXMLDeclaration is set to 1 the documents xml declaration is not
-serialized. This flag will cause the document to be serialized as UTF8
-even if the document has an other encoding specified.
-
-XML::LibXML does not define these flags itself, therefore they have to
-specify them manually by the caller:
-
- local $XML::LibXML::skipXMLDeclaration = 1;
- local $XML::LibXML::skipDTD = 1;
- local $XML::LibXML::setTagCompression = 1;
-
-will cause the serializer to avoid the XML declaration for a document,
-skip the DTD if found, and expand empty tags.
-
-*NOTE* $XML::LibXML::skipXMLDeclaration and $XML::LibXML::skipDTD are
-only recognized by the Documents toString() function.
-
-Additionally it is possible to serialize single nodes by using
-toString() for the node. Since a node has no DTD and no XML
-Declaration the related flags will take no effect. Nevertheless
-setTagCompression is supported.
-
-All basic serialization function recognize an additional formating
-flag. This flag is an easy way to format complex xml documents without
-adding ignoreable whitespaces.
-
-=head2 Input Callbacks
-
-The input callbacks are used whenever LibXML has to get something B<other
-than external parsed entities> from somewhere. The input callbacks in LibXML
-are stacked on top of the original input callbacks within the libxml library.
-This means that if you decide not to use your own callbacks (see C<match()>),
-then you can revert to the default way of handling input. This allows, for
-example, to only handle certain URI schemes.
-
-Callbacks are only used on files, but not on strings or filehandles. This is
-because LibXML requires the match event to find out about which callback set
-is shall be used for the current input stream. LibXML can decide this only
-before the stream is open. For LibXML strings and filehandles are already
-opened streams.
-
-The following callbacks are defined:
-
-=over 4
-
-=item match(uri)
-
-If you want to handle the URI, simply return a true value from this callback.
-
-=item open(uri)
-
-Open something and return it to handle that resource.
-
-=item read(handle, bytes)
-
-Read a certain number of bytes from the resource. This callback is
-called even if the entire Document has already read.
-
-=item close(handle)
-
-Close the handle associated with the resource.
-
-=back
-
-=head2 Example
-
-This is a purely fictitious example that uses a MyScheme::Handler object
-that responds to methods similar to an IO::Handle.
-
-  $parser->match_callback(\&match_uri);
-  
-  $parser->open_callback(\&open_uri);
-  
-  $parser->read_callback(\&read_uri);
-  
-  $parser->close_callback(\&close_uri);
-  
-  sub match_uri {
-    my $uri = shift;
-    return $uri =~ /^myscheme:/;
-  }
-  
-  sub open_uri {
-    my $uri = shift;
-    return MyScheme::Handler->new($uri);
-  }
-  
-  sub read_uri {
-    my $handler = shift;
-    my $length = shift;
-    my $buffer;
-    read($handler, $buffer, $length);
-    return $buffer;
-  }
-  
-  sub close_uri {
-    my $handler = shift;
-    close($handler);
-  }
-
-A more realistic example can be found in the L<"example"> directory
-
-Since the parser requires all callbacks defined it is also possible to
-set all callbacks with a single call of callbacks(). This would
-simplify the example code to:
-
-  $parser->callbacks( \&match_uri, \&open_uri, \&read_uri, \&close_uri);
-
-All functions that are used to set the callbacks, can also be used to
-retrieve the callbacks from the parser.
-
-=head2 Global Callbacks
-
-Optionaly it is possible to apply global callback on the XML::LibXML
-class level. This allows multiple parses to share the same callbacks.
-To set these global callbacks one can use the callback access
-functions directly on the class.
-
-  XML::LibXML->callbacks( \&match_uri, \&open_uri, \&read_uri, \&close_uri);
-
-The previous code snippet will set the callbacks from the first
-example as global callbacks.
-
-=head2 Encoding
-
-All data will be stored UTF-8 encoded. Nevertheless the input and
-output functions are aware about the encoding of the owner
-document. By default all functions will assume, UTF-8 encoding of the
-passed strings unless the owner document has a different encoding. In
-such a case the functions will assume the encoding of the document to
-be valid.
-
-At the current state of implementation query functions like
-B<findnodes()>, B<getElementsByTagName()> or B<getAttribute()> accept
-B<only> UTF-8 encoded strings, even if the underlaying document has a
-different encoding. At first this seems to be a limitation, but on
-application level there is no way to make save asumptations about the
-encoding of the strings.
-
-Future releases will offer the opportunity to force an application
-wide encoding, so make shure that you installed the latest version of
-XML::LibXML.
-
-To encode or decode a string to or from UTF-8 B<XML::LibXML> exports
-two functions, which use the encoding mechanism of the underlaying
-implementation. These functions should be used, if external encoding
-is required (e.g. for queryfunctions).
-
-=head2 encodeToUTF8
-
-    $encodedstring = encodeToUTF8( $name_of_encoding, $sting_to_encode );
-
-The function will encode a string from the specified encoding to UTF-8.
-
-=head2 decodeFromUTF8
-
-    $decodedstring = decodeFromUTF8($name_of_encoding, $string_to_decode );
-
-This Function transforms an UTF-8 encoded string the specified
-encoding.  While transforms to ISO encodings may cause errors if the
-given stirng contains unsupported characters, this function can
-transform to UTF-16 encodings as well.
-
-
-=head1 XML::LibXML::Dtd
-
-This module allows you to parse and return a DTD object. It has one method
-right now, C<new()>.
-
-=head2 new()
-
-  my $dtd = XML::LibXML::Dtd->new($public, $system);
-
-Creates a new DTD object from the public and system identifiers. It will
-automatically load the objects from the filesystem, or use the input
-callbacks (see L<"Input Callbacks"> below) to load the DTD.
-
-=head1 Processing Instructions - XML::LibXML::PI
-
-Processing instructions are implemented with XML::LibXML with read and
-write access ;) The PI data is the PI without the PI target (as
-specified in XML 1.0 [17]) as a string. This string can be accessed with
-L<getData> as implemented in XML::LibXML::Node.
-
-The write access is aware about the fact, that many processing
-instructions have attribute like data. Therefor L<setData> provides
-besides the DOM spec conform Interface to pass a set of named
-parameter. So the code segment
-
-    my $pi = $dom->createProcessingInstruction("abc");
-    $pi->setData(foo=>'bar', foobar=>'foobar');
-    $dom->appendChild( $pi );
-
-will result the following PI in the DOM:
-
-    <?abc foo="bar" foobar="foobar"?>
-
-The same can be done with
-
-   $pi->setData( 'foo="bar" foobar="foobar"' );
-
-Which is how it is specified in the L<DOM specification>. This three
-step interface creates temporary a node in perl space. This can be
-avoided while using the B<insertProcessingInstruction> method.
-Instead of the three calls described above, the call
-C<$dom->insertProcessingInstruction("abc",'foo="bar" foobar="foobar"');>
-will have the same result as above.
-
-Currently only the B<setData()> function accepts named parameters,
-while only strings are accepted by the other methods.
-
-=head2 createProcessingInstruction
-
-B<SYNOPSIS:>
-
-   $pinode = $dom->createProcessingInstruction( $target );
-
-or
-
-   $pinode = $dom->createProcessingInstruction( $target, $data );
-
-This function creates a new PI and returns this node. The PI is bound
-to the DOM, but is not appended to the DOM itself. To add the PI to
-the DOM, one needs to use B<appendChild()> directly on the dom itself.
-
-=head2 insertProcessingInstruction
-
-B<SYNOPSIS:>
-
-  $dom->insertProcessingInstruction( $target, $data );
-
-Creates a processing instruction and inserts it directly to the
-DOM. The function does not return a node.
-
-=head2 createPI
-
-alias for createProcessingInstruction
-
-=head2 insertPI
-
-alias for insertProcessingInstruction
-
-=head2 setData
-
-B<SYNOPSIS:>
-
-   $pinode->setData( $data_string );
-
-or
-
-   $pinode->setData( name=>string_value [...] );
-
-This method allows to change the content data of a PI. Additionaly to
-the interface specified for DOM Level2, the method provides a named
-parameter interface to set the data. This parameterlist is converted
-into a string before it is appended to the PI.
-
-=head1 AUTHOR
-
-Matt Sergeant, matt@sergeant.org
-Christian Glahn, christian.glahn@uibk.ac.at
-
-=head1 COPYRIGHT
-
-Copyright 2001-2002, AxKit.com Ltd. All rights reserved.
-
-This program is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
-
-
-=head1 SEE ALSO
-
-L<XML::LibXSLT>, L<XML::LibXML::DOM>, L<XML::LibXML::SAX>
-
-=cut
                      * this avoids segfaults in the end.
                      */
                     xmlNsPtr tns = xmlCopyNamespace(ns);
-                    element = sv_newmortal();
-                    XPUSHs(sv_setref_pv( element, 
-                                         (char *)CLASS, 
-                                         (void*)tns));
+                    if ( tns != NULL ) {
+                        element = sv_newmortal();
+                        XPUSHs(sv_setref_pv( element, 
+                                             (char *)CLASS, 
+                                             (void*)tns));
+                    }
                 }
                 ns = ns->next;
                 len++;

File example/libxml.dkb

     <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>
     </sect1>
   </chapter>
   <chapter>
-    <title>Parsing XML Files with XML::LibXML</title>
-    <titleabbrev>XML::LibXML-Parser</titleabbrev>
-    <para>TO BE DONE</para>
+    <title>Parsing XML Data with XML::LibXML</title>
+    <titleabbrev>XML::LibXML::Parser</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
+my $fdoc = $parser-&#62;parse_file( $xmlfile );
+
+my $fhdoc = $parser-&#62;parse_fh( $xmlstream );
+
+my $fragment = $parser-&#62;parse_xml_chunk( $xml_wb_chunk );</programlisting>
+    </sect1>
     <sect1>
       <title>Parsing</title>
-      <para>TO BE DONE</para>
+      <para>A XML document is read into a datastructure such as a DOM tree by
+      a piece of software, called parser. XML::LibXML currently provides four
+      diffrent parser interfaces:</para>
+      <itemizedlist>
+        <listitem>
+          <para>A DOM Pull-Parser</para>
+        </listitem>
+        <listitem>
+          <para>A DOM Push-Parser</para>
+        </listitem>
+        <listitem>
+          <para>A SAX Parser</para>
+        </listitem>
+        <listitem>
+          <para>A DOM based SAX Parser.</para>
+        </listitem>
+      </itemizedlist>
       <sect2>
-        <title>Input Callbacks</title>
-        <para>TO BE DONE</para>
+        <title>Creating a Parser Instance</title>
+        <para>XML::LibXML provides an OO interface to the libxml2 parser
+        functions. Thus you have to create a parser instance before you can
+        parse any XML data.</para>
+        <variablelist>
+          <varlistentry>
+            <term>new</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$parser = XML::LibXML-&#62;new();</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>There is nothing much to say about the constructor. It
+              simply creates a new parser instance.</para>
+              <para>Although libxml2 uses mainly global flags to alter the
+              behaviour of the parser, each XML::LibXML parser instance has
+              its own flags or callbacks and does not interfere with other
+              instances.</para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
       </sect2>
       <sect2>
         <title>DOM Parser</title>
-        <para>TO BE DONE</para>
+        <para>One of the common parser interfaces of XML::LibXML is the DOM
+        parser. This parser reads XML data into a DOM like datastructure, so
+        each tag can get accessed and transformed.</para>
+        <para>XML::LibXML&#39;s DOM parser is not only capable to parse XML
+        data, but also (strict) HTML and SGML files. There are three ways to
+        parse documents - as a string, as a Perl filehandle, or as a filename.
+        The return value from each is a XML::LibXML::Document object, which is
+        a DOM object. </para>
+        <para>All of the functions listed below will throw an exception if the
+        document is invalid. To prevent this causing your program exiting,
+        wrap the call in an eval{} block</para>
+        <variablelist>
+          <varlistentry>
+            <term>parse_file</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$doc = $parser-&#62;parse_file( $xmlfilename );</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>This function reads an absolute filename into the memory.
+              It causes XML::LibXML to use libxml2&#39;s file parser instead
+              of letting perl reading the file such as with parse_fh(). If you
+              need to parse files directly, this function would be the faster
+              choice, since this function is about 6-8 times faster then
+              parse_fh().</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>parse_fh</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$doc = $parser-&#62;parse_fh( $io_fh );</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>parse_fh() parses a IOREF or a subclass of IO::Handle.
+              </para>
+              <para>Because the data comes from an open handle, libxml2&#39;s
+              parser does not know about the base URI of the document. To set
+              the base URI one should use parse_fh() as follows:</para>
+              <programlisting>my $doc = $parser-&#62;parse_fh( $io_fh, $baseuri );</programlisting>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>parse_string</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$doc = $parser-&#62;parse_string( $xmlstring);</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>This function is similar to parse_fh(), but it parses a
+              XML document that is available as a single string in memory.
+              Again, you can pass an optional base URI to the function.</para>
+              <programlisting>my $doc = $parser-&#62;parse_stirng( $xmlstring, $baseuri );</programlisting>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>parse_html_file</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$doc = $parser-&#62;parse_html_file( $htmlfile );</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>Similar to parse_file() but parses HTML (strict)
+              documents.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>parse_html_fh</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$doc = $parser-&#62;parse_html_fh( $io_fh );</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>Similar to parse_fh() but parses HTML (strict) streams.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>parse_html_string</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$doc = $parser-&#62;parse_html_string( $htmlstring );</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>Similar to parse_file() but parses HTML (strict) strings.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>parse_sgml_file</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$doc = $parser-&#62;parse_sgml_file( $sgmlfile );</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>Similar to parse_file() but parses SGML documents.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>parse_sgml_fh</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$doc = $parser-&#62;parse_sgml_fh( $io_fh );</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>Similar to parse_file() but parses SGML streams.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>parse_sgml_string</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$doc = $parser-&#62;parse_sgml_string( $sgmlstring );</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>Similar to parse_file() but parses SGML strings.</para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+        <para>The functions described above are implemented to parse well
+        formed documents. In some cases a program gets well balanced XML
+        instead of well formed documents (e.g. a XML fragment from a
+        Database). With XML::LibXML it is not required to wrap such fragments
+        in the code, because XML::LibXML is capable even to parse well
+        balanced XML fragments.</para>
+        <variablelist>
+          <varlistentry>
+            <term>parse_balanced_chunk</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$fragment = $parser-&#62;parse_balanced_chunk( $wbxmlstring );</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>This function parses a well balanced XML string into a
+              XML::LibXML::DocumentFragment.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>parse_xml_chunk</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$fragment = $parser-&#62;parse_xml_chunk( $wbxmlstring );</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>This is the old name of parse_balanced_chunk(). Because it
+              may causes confusion with the push parser interface, this
+              function should be used anymore.</para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+        <para>By default XML::LibXML does not process XInclude tags within a
+        XML Document (see options section below). XML::LibXML allows to post
+        process a document to expand XInclude tags.</para>
+        <variablelist>
+          <varlistentry>
+            <term>process_xincludes</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$parser-&#62;process_xincludes( $doc );</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>After a document is parsed into a DOM structure, you may
+              want to expand the documents XInclude tags. This function
+              processes the given document structure and expands all XInclude
+              tags (or throws an error) by using the flags and callbacks of
+              the given parser instance.</para>
+              <para>Note that the resulting Tree contains some extra nodes (of
+              type XML_XINCLUDE_START and XML_XINCLUDE_END) after successfully
+              processing the document. These nodes indicate where data was
+              included into the original tree. if the document is serialized,
+              these extra nodes will not show up.</para>
+              <para>Remember: A Document with processed XIncludes differs from
+              the original document after serialization, because the original
+              XInclude tags will not get restored!</para>
+              <para>If the parser flag &#34;expand_xincludes&#34; is set to 1,
+              you need not to post process the parsed document.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>processXIncludes</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$parser-&#62;processXIncludes( $doc );</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>This is an alias to process_xincludes, but through a JAVA
+              like function name.</para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
       </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
+        <para>XML::LibXML provides a push parser interface. Rather than
+        pulling the data from a given source the push parser waits for the
+        data to be pushed into it.</para>
+        <para>This allows one to parse large documents without waiting for the
+        parser to finish. The interface is especially usefull if a program
+        needs to preprocess the incoming pieces of XML (e.g. to detect
+        document boundaries). </para>
+        <para>While XML::LibXML parse_*() functions force the data to be a
+        wellformed XML, the push parser will take any arbitrary string that
+        contains some XML data. The only requirement is that all the pushed
+        strings are together a wellformed document. With the push parser
+        interface a programm can interrupt the parsing process as required,
+        where the parse_*() functions give not enough flexibility.</para>
+        <para>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>
               <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
+                                      # unless an error happend
 };
 
 print $doc-&#62;toString(); # returns &#34;&#60;foo&#62;bar&#60;/foo&#62;&#34;</programlisting>
         </variablelist>
       </sect2>
       <sect2>
-        <title>SAX Parser</title>
-        <para>TO BE DONE</para>
+        <title>DOM based SAX Parser</title>
+        <para>XML::LibXML provides a DOM based SAX parser. The SAX parser is
+        defined in XML::LibXML::SAX::Parser. As it is not a stream based
+        parser, it parses documents into a DOM and traverses the DOM tree
+        instead.</para>
+        <para>The API of this parser is exactly the same as any other Perl
+        SAX2 parser. See XML::SAX::Intro for details.</para>
+        <para>Aside from the regular parsing methods, you can access the DOM
+        tree traverser directly, using the generate() method:</para>
+        <programlisting>my $doc = build_yourself_a_document();
+my $saxparser = $XML::LibXML::SAX::Parser-&#62;new( ... );
+$parser-&#62;generate( $doc );</programlisting>
+        <para>This is useful for serializing DOM trees, for example that you
+        might have done prior processing on, or that you have as a result of
+        XSLT processing.</para>
+        <para><emphasis>WARNING</emphasis></para>
+        <para>This is NOT a streaming SAX parser. As I said above, this parser
+        reads the entire document into a DOM and serialises it. Some people
+        couldn&#39;t read that in the paragraph above so I&#39;ve added this
+        warning.</para>
+        <para>If you want a streaming SAX parser look at the XML::LibXML::SAX
+        man page</para>
       </sect2>
     </sect1>
     <sect1>
       <title>Serialization</title>
-      <para>TO BE DONE</para>
+      <para>XML::LibXML provides some functions to serialize nodes and
+      documents. The serialization functions themself are described at the
+      XML::LibXML::Node manpage or the XML::LibXML::Document manpage.
+      XML::LibXML checks three global flags that alter the serialization
+      process:</para>
+      <itemizedlist>
+        <listitem>
+          <para>skipXMLDeclaration</para>
+        </listitem>
+        <listitem>
+          <para>skipDTD</para>
+        </listitem>
+        <listitem>
+          <para>setTagCompression</para>
+        </listitem>
+      </itemizedlist>
+      <para>of that three functions only setTagCompression is available for
+      all serialization functions. </para>
+      <para>Because XML::LibXML does these flags not itself, one has to define
+      them locally as the following example shows:</para>
+      <programlisting>local $XML::LibXML::skipXMLDeclaration = 1;
+local $XML::LibXML::skipDTD = 1;
+local $XML::LibXML::setTagCompression = 1;</programlisting>
+      <para>If skipXMLDeclaration is defined and not &#39;0&#39;, the XML
+      declaration is omitted during serialization.</para>
+      <para>If skipDTD is defined and not &#39;0&#39;, an existing DTD would
+      not be serialized with the document.</para>
+      <para>If setTagCompression is defined and not &#39;0&#39; empty tags are
+      displayed as open and closing tags ranther than the shortcut. For
+      example the empty tag <emphasis>foo</emphasis> will be rendered as
+      <emphasis>&#60;foo&#62;&#60;/foo&#62;</emphasis> rather than
+      <emphasis>&#60;foo/&#62;</emphasis>.</para>
     </sect1>
     <sect1>
-      <title>Options</title>
-      <para>TO BE DONE</para>
+      <title>Parser Options</title>
+      <para>LibXML options are global (unfortunately this is a limitation of
+      the underlying implementation, not this interface). They can either be
+      set using $parser-&#62;option(...), or XML::LibXML-&#62;option(...),
+      both are treated in the same manner. Note that even two parser processes
+      will share some of the same options, so be careful out there!</para>
+      <para>Every option returns the previous value, and can be called without
+      parameters to get the current value.</para>
+      <variablelist>
+        <varlistentry>
+          <term>validation</term>
+          <listitem>
+            <funcsynopsis>
+              <funcsynopsisinfo>$parser-&#62;validation(1);</funcsynopsisinfo>
+            </funcsynopsis>
+            <para>Turn validation on (or off). Defaults to off.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>recover</term>
+          <listitem>
+            <funcsynopsis>
+              <funcsynopsisinfo>$parser-&#62;recover(1);</funcsynopsisinfo>
+            </funcsynopsis>
+            <para>Turn the parsers recover mode on (or off). Defaults to off.</para>
+            <para>This allows to parse broken XML data into memory. This
+            switch will only work with XML data rather than HTML data. Also
+            the validation will be switched off automaticly.</para>
+            <para>The recover mode helps to recover documents that are almost
+            wellformed very efficiently. That is for example a document that
+            forgets to close the document tag (or any other tag inside the
+            document). The recover mode of XML::LibXML has problems though to
+            restore documents that are more like well ballanced chunks. In
+            that case XML::LibXML will only parse the first tag of the chunk.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>expand_entities</term>
+          <listitem>
+            <funcsynopsis>
+              <funcsynopsisinfo>$parser-&#62;expand_entities(0);</funcsynopsisinfo>
+            </funcsynopsis>
+            <para>Turn entity expansion on or off, enabled by default. If
+            entity expansion is off, any external parsed entities in the
+            document are left as entities. Probably not very useful for most
+            purposes.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>keep_blanks</term>
+          <listitem>
+            <funcsynopsis>
+              <funcsynopsisinfo>$parser-&#62;keep_blanks(0);</funcsynopsisinfo>
+            </funcsynopsis>
+            <para>Allows you to turn off XML::LibXML&#39;s default behaviour
+            of maintaining whitespace in the document.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>pedantic_parser</term>
+          <listitem>
+            <funcsynopsis>
+              <funcsynopsisinfo>$parser-&#62;pedantic_parser(1)</funcsynopsisinfo>
+            </funcsynopsis>
+            <para>You can make XML::LibXML more pedantic if you want to.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>load_ext_dtd</term>
+          <listitem>
+            <funcsynopsis>
+              <funcsynopsisinfo>$parser-&#62;load_ext_dtd(1);</funcsynopsisinfo>
+            </funcsynopsis>
+            <para>Load external DTD subsets while parsing.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>complete_attributes</term>
+          <listitem>
+            <funcsynopsis>
+              <funcsynopsisinfo>$parser-&#62;complete_attributes(1);</funcsynopsisinfo>
+            </funcsynopsis>
+            <para>Complete the elements attributes lists with the ones
+            defaulted from the DTDs. By default, this option is enabled.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>expand_xinclude</term>
+          <listitem>
+            <funcsynopsis>
+              <funcsynopsisinfo>$parser-&#62;expand_xinclude(1);</funcsynopsisinfo>
+            </funcsynopsis>
+            <para>Expands XIinclude tags imidiatly while parsing the document.
+            This flag assures that the parser callbacks are used while parsing
+            the included document.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>load_catalog</term>
+          <listitem>
+            <funcsynopsis>
+              <funcsynopsisinfo>$parser-&#62;load_catalog( $catalog_file );</funcsynopsisinfo>
+            </funcsynopsis>
+            <para>Will use $catalog_file as a catalog during all parsing
+            processes. Using a catalog will significantly speed up parsing
+            processes if many external ressources are loaded into the parsed
+            documents (such as DTDs or XIncludes).</para>
+            <para>Note that catalogs will not be available if an external
+            entity handler was specified. At the current state it is not
+            possible to make use of both types of resolving systems at the
+            same time.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>base_uri</term>
+          <listitem>
+            <funcsynopsis>
+              <funcsynopsisinfo>$parser-&#62;base_uri( $your_base_uri );</funcsynopsisinfo>
+            </funcsynopsis>
+            <para>In case of parsing strings or file handles, XML::LibXML
+            doesn&#39;t know about the base uri of the document. To make
+            relative references such as XIncludes work, one has to set a
+            separate base URI, that is then used for the parsed documents.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>gdome_dom</term>
+          <listitem>
+            <funcsynopsis>
+              <funcsynopsisinfo>$parser-&#62;gdome_dom(1);</funcsynopsisinfo>
+            </funcsynopsis>
+            <para>THIS FLAG IS EXPERIMENTAL!</para>
+            <para>Although quite powerful XML:LibXML&#39;s DOM implementation
+            is limited if one needs or wants full DOM level 2 or level 3
+            support. XML::GDOME is based on libxml2 as well but provides a
+            rather complete DOM implementation by wrapping libgdome. This
+            allows you to make use of XML::LibXML&#39;s full parser options
+            and XML::GDOME&#39;s DOM implementation at the same time.</para>
+            <para>To make use of this function, one has to install libgdome
+            and configure XML::LibXML to use this library.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+      <sect2>
+        <title>Input Callbacks</title>
+        <para>If libxml2 has to load external documents during parsing, this
+        may cause strange results, if the location is not a HTTP, FTP or
+        relative location. To get around this limitation, one may add its own
+        input handler, to open, read and close particular locations or URI
+        classes.</para>
+        <para>The input callbacks are used whenever LibXML has to get
+        something other than external parsed entities from somewhere. The
+        input callbacks in LibXML are stacked on top of the original input
+        callbacks within the libxml library. This means that if you decide not
+        to use your own callbacks (see match()), then you can revert to the
+        default way of handling input. This allows, for example, to only
+        handle certain URI schemes.</para>
+        <para>Callbacks are only used on files, but not on strings or
+        filehandles. This is because LibXML requires the match event to find
+        out about which callback set is shall be used for the current input
+        stream. LibXML can decide this only before the stream is open. For
+        LibXML strings and filehandles are already opened streams.</para>
+        <para>The following callbacks are defined:</para>
+        <variablelist>
+          <varlistentry>
+            <term>match_callback</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$parser-&#62;match_callback($subref);</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>If you want to handle the URI, simply return a true value
+              from this callback.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>open_callback</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$parser-&#62;open_callback($subref);</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>Open something and return it to handle that resource.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>read_callback</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$parser-&#62;read_callback($subref);</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>Read a certain number of bytes from the resource. This
+              callback is called even if the entire Document has already read.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>close_callback</term>
+            <listitem>
+              <funcsynopsis>
+                <funcsynopsisinfo>$parser-&#62;close_callback($subref);</funcsynopsisinfo>
+              </funcsynopsis>
+              <para>Close the handle associated with the resource.</para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+        <para>The following example explains the concept a bit. It is a purely
+        fictitious example that uses a MyScheme::Handler object that responds
+        to methods similar to an IO::Handle.</para>
+        <programlisting>$parser-&#62;match_callback(\&#38;match_uri);
+  
+  $parser-&#62;open_callback(\&#38;open_uri);
+  
+  $parser-&#62;read_callback(\&#38;read_uri);
+  
+  $parser-&#62;close_callback(\&#38;close_uri);
+  
+  sub match_uri {
+    my $uri = shift;
+    return $uri =~ /^myscheme:/;
+  }
+  
+  sub open_uri {
+    my $uri = shift;
+    return MyScheme::Handler-&#62;new($uri);
+  }
+  
+  sub read_uri {
+    my $handler = shift;
+    my $length = shift;
+    my $buffer;
+    read($handler, $buffer, $length);
+    return $buffer;
+  }
+  
+  sub close_uri {
+    my $handler = shift;
+    close($handler);
+  }</programlisting>
+        <para>A more realistic example can be found in the &#34;example&#34;
+        directory.</para>
+        <para>Since the parser requires all callbacks defined it is also
+        possible to set all callbacks with a single call of callbacks(). This
+        would implify the example code to:</para>
+        <programlisting>$parser-&#62;callbacks( \&#38;match_uri, \&#38;open_uri, \&#38;read_uri, \&#38;close_uri);</programlisting>
+        <para>All functions that are used to set the callbacks, can also be
+        used to retrieve the callbacks from the parser.</para>
+        <para>Optionaly it is possible to apply global callback on the
+        XML::LibXML class level. This allows multiple parses to share the same
+        callbacks. To set these global callbacks one can use the callback
+        access functions directly on the class.</para>
+        <programlisting>XML::LibXML-&#62;callbacks( \&#38;match_uri, \&#38;open_uri, \&#38;read_uri, \&#38;close_uri);</programlisting>
+        <para>The previous code snippet will set the callbacks from the first
+        example as global callbacks.</para>
+      </sect2>
     </sect1>
     <sect1>
       <title>Error Reporting</title>
-      <para>TO BE DONE</para>
+      <para>XML::LibXML throws exceptions during parseing, validation or XPath
+      processing. These errors can be catched by useing eval blocks. The error
+      then will be stored in <emphasis>$@</emphasis>. Alternatively one can
+      use the get_last_error() function of XML::LibXML. It will return the
+      same string that is stored in <emphasis>$@</emphasis>. Using
+      get_last_error() makes it still nessecary to eval the statement, since
+      these function groups will die() on errors.</para>
+      <para>get_last_error() can be called either by the class itself or by a
+      parser instance:</para>
+      <programlisting>$errstring = XML::LibXML-&#62;get_last_error();
+$errstring = $parser-&#62;get_last_error();</programlisting>
+      <para>However, XML::LibXML exceptions are global. That means if
+      get_last_error() is called on an parser instance, the last
+      <emphasis>global</emphasis> error will be returned. This is not
+      nessecarily the error caused by the parser instance itself.</para>
     </sect1>
   </chapter>
   <chapter>
     </sect1>
   </chapter>
   <chapter>
+    <title>Building DOM trees from SAX events.</title>
+    <titleabbrev>XML::LibXML::SAX::Builder</titleabbrev>
+    <sect1>
+      <title>Synopsis</title>
+      <programlisting>my $builder = XML::LibXML::SAX::Builder-&#62;new();
+
+my $gen = XML::Generator::DBI-&#62;new(Handler =&#62; $builder, dbh =&#62; $dbh);
+$gen-&#62;execute(&#34;SELECT * FROM Users&#34;);
+
+my $doc = $builder-&#62;result();</programlisting>
+    </sect1>
+    <sect1>
+      <title>Description</title>
+      <para>Building DOM trees from SAX events is quite easy with
+      XML::LibXML::SAX::Builder. The class is designed as a SAX2 final
+      handler. </para>
+      <para>Since SAX is strictly stream oriented, you should not expect
+      anything to return from a generator. Instead you have to ask the builder
+      instance directly to get the document built.
+      XML::LibXML::SAX::Builder&#39;s result function holds the document
+      generated from the last SAX stream.</para>
+      <para>This is a SAX handler that generates a DOM tree from SAX events.
+      Usage is as above. Input is accepted from any SAX1 or SAX2 event
+      generator.</para>
+    </sect1>
+  </chapter>
+  <chapter>
     <title>XML::LibXML DOM Implementation</title>
-    <titleabbrev>XML::LibXML-DOM</titleabbrev>
+    <titleabbrev>XML::LibXML::DOM</titleabbrev>
     <sect1>
       <title>Description</title>
       <para>XML::LibXML provides an lightwight interface to
           <para>The function is similar to toString(). Instead of simply
           searializing the document tree, it transforms it as it is specified
           in the XML-C14N Specification. Such transformation is known as
-          canonization. </para>
+          canonization.</para>
           <para>If $with_comments is 0 or not defined, the result-document
           will not contain any comments that exist in the original document.
           To include comments into the canonized document, $with_comments has
   </chapter>
   <chapter>
     <title>XML::LibXML DTD Handling</title>
-    <subtitle></subtitle>
     <titleabbrev>XML::LibXML::Dtd</titleabbrev>
     <para>This class holds a DTD. You may parse a DTD from either a string, or
     from an external SYSTEM identifier.</para>
       </varlistentry>
     </variablelist>
   </chapter>
-  <chapter>
-    <title>Internals of the Perl Layer for libxml2</title>
-    <titleabbrev>XML::LibXMLguts</titleabbrev>
-    <sect1>
-      <title>General Information</title>
-      <para>TO BE DONE</para>
-    </sect1>
-    <sect1>
-      <title>How To extend XML::LibXML</title>
-      <para>TO BE DONE</para>
-    </sect1>
-    <sect1>
-      <title>Internal API Description</title>
-      <para>TO BE DONE</para>
-    </sect1>
-  </chapter>
 </book>

File lib/XML/LibXML/SAX/Builder.pm

 1;
 
 __END__
-
-=head1 NAME
-
-XML::LibXML::SAX::Builder - build a LibXML tree from SAX events
-
-=head1 SYNOPSIS
-
-  my $builder = XML::LibXML::SAX::Builder->new();
-  my $gen = XML::Generator::DBI->new(Handler => $builder, dbh => $dbh);
-  my $dom = $gen->execute("SELECT * FROM Users");
-
-=head1 DESCRIPTION
-
-This is a SAX handler that generates a DOM tree from SAX events. Usage
-is as above. Input is accepted from any SAX1 or SAX2 event generator.
-
-=cut

File lib/XML/LibXML/SAX/Parser.pm

 1;
 
 __END__
-
-=head1 NAME
-
-XML::LibXML::SAX::Parser - LibXML DOM based SAX Parser
-
-=head1 SYNOPSIS
-
-  my $handler = MySAXHandler->new();
-  my $parser = XML::LibXML::SAX::Parser->new(Handler => $handler);
-  $parser->parse_uri("foo.xml");
-
-=head1 DESCRIPTION
-
-This class allows you to generate SAX2 events using LibXML. Note
-that this is B<not> a stream based parser, instead it parses
-documents into a DOM and traverses the DOM tree. The reason being
-that libxml2's stream based parsing is extremely primitive,
-and would require an extreme amount of work to allow SAX2
-parsing in a stream manner.
-
-=head1 WARNING
-
-WARNING WARNING WARNING
-
-This is NOT a streaming SAX parser. As I said above, this parser
-reads the entire document into a DOM and serialises it. Some
-people couldn't read that in the paragraph above so I've added
-this warning.
-
-There are many reasons, but if you want to write a proper SAX
-parser using the libxml2 library, please feel free and send it
-along to me.
-
-=head1 API
-
-The API is exactly the same as any other Perl SAX2 parser. See
-L<XML::SAX::Intro> for details.
-
-Aside from the regular parsing methods, you can access the
-DOM tree traverser directly, using the generate() method:
-
-  my $parser = XML::LibXML::SAX::Parser->new(...);
-  $parser->generate($dom_tree);
-
-This is useful for serializing DOM trees, for example that
-you might have done prior processing on, or that you have
-as a result of XSLT processing.
-
-=cut