README file for Perl extension XML::SAX::ExpatXS
================================================

1. Introduction
2. Dependencies
3. Installation
4. Callbacks
5. Encoding


1.Introduction
------------------------------

This module is a direct XS implementation of Perl SAX parser 
using Expat. XML::SAX::Expat is implemented as a layer over 
XML::Parser.

The first version of this module has been created by Matt 
Sergeant reusing sources of XML::Parser. The current maintainer 
is Petr Cimprich <petr AT gingerall DOT cz>.

The wrapper is considered stable. Feedback of any kind is 
appreciated.


2. Dependencies
------------------------------

This module requires Expat XML parser. XML::SAX::ExpatXS 1.10 
or higher requires Expat 1.95.4 or higher (because 
of XML_SetSkippedEntityHandler). For older Expat versions, it 
is recommended to use XML::SAX::ExpatXS 1.09.

You can download Expat from: http://expat.sourceforge.net/

Required Perl modules are: 

	XML::NamespaceSupport
	XML::SAX


3. Installation
------------------------------

perl Makefile.PL
make
make test
make install

You will need a C compiler to build this module from sources. Other 
option is to install a binary PPM package.

Expat must be installed prior to building XML::SAX::ExpatXS.
If expat is installed, but in a non-standard directory, then use 
the following options to Makefile.PL:

    EXPATLIBPATH=...  To set the directory in which to find libexpat

    EXPATINCPATH=...  To set the directory in which to find expat.h

For example:

    perl Makefile.PL EXPATLIBPATH=/home/me/lib EXPATINCPATH=/home/me/include

Note that if you build against a shareable library in a non-standard 
location you may (on some platforms) also have to set your LD_LIBRARY_PATH 
environment variable at run time for perl to find the library. On Windows, 
you have to set your PATH environment variable.


4. Callbacks
------------------------------

These Perl SAX callbacks are supported and tested:

 start_document()
 end_document()
 start_element()
 end_element()
 characters()
 processing_instruction()
 start_prefix_mapping()
 end_prefix_mapping()
 set_document_locator()
 fatal_error()
 comment()
 start_dtd()
 end_dtd()
 start_cdata()
 end_cdata()
 element_decl
 attribute_decl
 notation_decl()
 unparsed_entity_decl()
 external_entity_decl()
 internal_entity_decl()
 start_entity()
 end_entity ()
 resolve_entity()
 skipped_entity()

These methods are never called by XML::SAX::ExpatXS:

 warning()
 error()
 ignorable_whitespace()

This one is deprecated but it works with XML::SAX::ExpatXS:

 xml_decl()


5. Encoding
------------------------------

These charsets and encodings are supported:

UTF-8        (1)
UTF-16	     (1)
US-ASCII     (1)
ISO-8859-1   (1)
ISO-8859-2   (2)
ISO-8859-3   (2)
ISO-8859-4   (2)
ISO-8859-5   (2)
ISO-8859-7   (2)
ISO-8859-8   (2)
ISO-8859-9   (2)
WINDOWS-1250 (2)
WINDOWS-1252 (2)
BIG5	     (2)
EUC-KR	     (2)
EUC-JP	     (2,3)
Shift JIS.   (2,3)

(1) Expat built-in
(2) external handler
(3) see lib/XML/SAX/ExpatXS/Encodings/Japanese_Encodings.msg

Other encodings can be added with XML::Encoding, see 
lib/XML/SAX/ExpatXS/Encodings/README for more info.