INTRODUCTION
------------

This is the XDF Perl Package courtesy of the XML Group (formerly
workers at the Astronomical Data Center) at NASA/Goddard Space 
Flight Center. The code is not actively maintained, but should
still be useful.

XDF is the 'eXtensible Data Format' and is an attempt to make
XML behave nicely with scientific/mathematical data. This package
provides the classes for easy manipulation and IO of XDF objects. 
See our website: http://xml.gsfc.nasa.gov/XDF and the linkage 
within for more information on XDF and XML activities in general 
by our group.

This package is "beta", meaning we have all of the forseen functionality
incorportated in the code. "Beta" also means that many bugs remain 
and that the API may undergo minor changes. Please refer to the TODO 
list for an idea of what remains to be done to bring this package to 
full stable reality. One important goal worth mentioning here is 
attempting to bring in support for other XML parsers for XDF. Currently
only the XML-DOM/XML-Parser combination is supported.

A (quite out of date) diagram of the XDF object model appears
in the UML-XDF.gif image, I hope to update this soon. There is 
addtional information in the file-by-file docs. Build the HTML docs 
using the utility contained in utils. 


EXAMPLE FILES AND CODE
----------------------

Refer to the "samples" directory for working code and example XDF 
files.


LICENCE 
-------

This package is released under the GNU Public Licence. Please refer 
LICENCE file for the details.


INSTALL
-------

This package should work on both W9x and UNIX platforms (and
perhaps others, but thats all I've tested on so far); Note
that the makefiles only compliant with UNIX make so W9x users
will have to install by hand. One day, when I have the time, 
I will look into creatation of a PPD file for this distribution.

You will need to install (or verify that they are installed)
the following packages:

   XML-Parser-2.31
   XML-DOM-1.42
 
Many linux distros ship with these nowadays, but you may also 
get both packages from CPAN. Lower numbered Perl packages *may*
work with XDF, but I havent tested it. Upgrade if you dont like
heavy wizardry with your XDF data :) OPTIONAL FOR THE DARING:
For XML-DOM versions *about* 1.31 and lower, I have included a 
patch file that I know you will need to apply. You may do so   
by doing the following:
> cd XML-DOM-1.31
> patch -p0 < <XDFdirectory>/DOM.patch

IF you got your packages from CPAN, you can build them as per
the instructions in each module.

Once you have verified that you have the correct XML software
modules on your system, you are, finally, ready to install 
Perl XDF. Just do:

> cd <XDFdirectory>
> Perl Makefile.PL; make ; make test ; make install

as for any standard Perl package. 

Additional HTML documentation may be made by running the script
util/makeHTMLDoc.pl AFTER you have built the distribution.


Problems with Perl Package
--------------------------

Having said the above, I have noticed that problems will occur
with the handling of external entities (e.g. they arent currently
supported very well) using the basic XML Perl parser. Part of the
problem seems to be the LWP handler, but Im not 100% sure. Hopefully
the maintainers can resolve this issue, but its been a while 
since I first noticed it, and notified the maintainers of the Perl
XML code, so dont get your hopes up. Any eager beavers out there that
want to fix this can ask me about it.

Also, in order to use compression, you will have to edit the path
to the compress executables in Constants.pm. If you have already
installed the package, no problem, just hammer it over with a quick
"make install" from the <XDFdirectory>. I hope to integrate this into 
the make proceedure in the future.

---

Perl XDF Package Maintainer : Brian Thomas