$Id: README,v 1.8 2002/10/20 23:40:09 mrodrigu Exp $

NAME

    XML::Twig - Tree interface to XML documents allowing processing chunk
                by chunk of huge documents.

WARNING

    XML::Twig and various versions of Perl, XML::Parser and expat:
    XML::Twig is tested under the following environments:

    Linux, perl 5.004_005, expat 1.95.2 and 1.95.5, XML::Parser 2.27 and 2.31
    Linux, perl 5.005_03, expat 1.95.2 and 1.95.5, XML::Parser 2.27 and 2.31
    Linux, perl 5.6.1, expat 1.95.2 and 1.95.5, XML::Parser 2.27 and 2.31 
    Linux, perl 5.8.0, expat 1.95.2 and 1.95.5, XML::Parser 2.31 

    Windows NT 4.0 ActivePerl 5.6.1 build 631
    Windows 2000  ActivePerl 5.6.1 build 633
    You need nmake to make the module on Windows (or you can just copy
    Twig.pm to the appropriate directory)

    XML::Twig does NOT work with expat 1.95.4 (upgrade to 1.95.5)
    XML::Parser 2.27 does NOT work under perl 5.8.0
               
    Notes about specific versions:

    You cannot use the output_encoding option with perl 5.004_005
    Parsing utf-8 Asian characters with perl 5.8.0 seems not to work
    (this is under investigation, and probably due to XML::Parser)

SUMMARY (see perldoc XML::Twig for full details)

    single-tree mode    
        my $t= XML::Twig->new();
        $t->parsefile( 'doc.xml');
        $t->print;

    chunk mode 
        my $t= XML::Twig->new( TwigHandlers => { section => \&flush});
        $t->parsefile( 'doc.xml');
        $t->flush;
        sub flush { $_[0]->flush; }
    
    sub-tree mode 
        # print all title's in the document
        my $t= XML::Twig->new( TwigRoots => { title => 1 },
                               TwigHandlers => { title => \&list});
        $t->parsefile( 'doc.xml');
        sub list { print $_->print . "\n"; }
    
INSTALLATION

    perl Makefile.PL
    make
    make test
    make install

NOTES

   It is very much recommended to install Text::Iconv (for easy character
   encoding conversions, at least for versions of Perl pre-5.8) and WeakRef
   (to avoid memory leaks) with this version if you can.

CHANGES


    See the Changes file    

AUTHOR

    Michel Rodriguez (mirod@xmltwig.com)
    The Twig page is at http://www.xmltwig.com/ 
    A tutorial is at http://www.xmltwig.com/xmltwig/tutorial/index.html

COPYRIGHT

       Copyright (c) 1999-2002, Michel Rodriguez. All Rights Reserved.
     This module is free software. It may be used, redistributed
     and/or modified under the terms of the Perl Artistic License
          (see http://www.perl.com/perl/misc/Artistic.html)