XML::Parser Version 2.28

Copyright (c) 1998-2000 Larry Wall and Clark Cooper.
All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. 

This is a Perl extension interface to James Clark's XML parser, expat.
It requires at least version 5.004 of perl. The documentation for this
extension can be found in pod format at the end of the files Parser.pm
and Expat/Expat.pm. The perldoc program, provided with the perl distribution,
can be used to view this documentation.

The necessary parts of the expat library are included in this distribution in
the directory Expat/expat. These components are copyrighted by James Clark,
with patches copyrighted by Clark Cooper. They are licensed under your choice
of either the Mozilla Public License version 1.1 (MPL) or the GNU Public
License (GPL).

This was modified from the original XML::Parser created by Larry Wall.

To configure this module, cd to the directory that contains this README file
and type the following:

	perl Makefile.PL

Alternatively, if you plan to install XML::Parser somewhere other than
your system's perl library directory. You can type something like this:

	perl Makefile.PL PREFIX=/home/me/perl INSTALLDIRS=perl

Then to build you run make.

	make

You can then test the module by typing:

	make test

There are some sample utilities in the samples directory along with an
xml form of the XML specification to test them on. You may need to change
the '#!' line at the top of these utilities to what is appropriate for
your system. If you're going to play around with them prior to installing
the module, you would need to add the blib paths to your perl search
path, like this (assuming your current directory is samples):

    perl -I../blib/lib -I../blib/arch xmlcomments REC-xml-19980210.xml

or set your PERLLIB environment variable.

If you have write access to the installation directories, you may then
install by typing:

	make install

Discussion on features and bugs of this software and general discussion
on topics relating to perl and XML takes place on the perl-xml mailing
list, to which you can subscribe by sending mail to:

    subscribe-perl-xml@lyris.activestate.com

Differences from Version 2.27
=============================

- Junked local (Expat.xs) declaration parsing and patched expat to handle
  XML declarations, element declarations, attlist declarations, and all
  entity declarations. This fixed a segfault that occurred for certain
  syntax errors in declarations. It also fixed a bug in which the doctype
  handler did not get called when parsing an external DTD.

  Unfortunately, a side effect is that the recognized_string, original_string,
  and default_current methods no longer work inside declaration handlers.

- The element declaration handler no longer receives a string for the
  content model, but instead receives an XML::Parser::ContentModel object
  that represents the parsed model. This class of objects is covered in
  the "XML::Parser::ContentModel Methods" section of the XML::Parser::Expat
  documentation. When used as a string, though, an object of this class
  will return a string representation of the content model.

- The doctype declaration handler is now called prior to processing internal
  or external DTD declarations and instead of a string for the internal
  subset parameter, it receives a true or undef value to indicate whether or
  not an internal subset is present.

- A new handler, DoctypeFin, was added. Handlers of this type are called after
  processing all of the DOCTYPE declaration, including any internal or external
  subsets.

- A new handler, ExternEntFin, was added. These are called after parsing
  external entities.

- The parsefile method of XML::Parser and the default external entity
  reference handlers, file_ext_ent_handler & lwp_ext_ent_handler now all
  set the base path.

- The file_ext_ent_handler default external entity reference handler now
  opens a file handle instead of reading the entire external entity at once.

- When using perl version 5.6.0 or greater, strings generated in XML::Parser
  that contain UTF-8 are marked as such. (i.e. perl string operators will
  act on the characters instead of the bytes.)

- Fixed a bug in xml_escape where it got confused over perl regex
  meta-characters.

- Fixed a bug in the Proc handler of the Debug style.

- Fixed a bug in the element index mechanism. It was misreporting the index
  in end tag handlers.

- Fixed some bugs in exception handling. In particular, fixed memory leaks
  associated with exceptions.

- Updated the canonical utility in the samples directory to conform to newer
  version of the Canonical XML working draft.

Clark Cooper
  coopercc@netheaven.com