XMLEye can open directly any XML input document. Other formats will have to be converted first to XML before XMLEye can process them. This is what converters are for, basically.

XMLEye imposes very few restrictions on converters. Most Perl or Python scripts should work fine, for instance. Basically:

• a single shell command from XMLEye's main directory should launch it, possibly using some interpreter in your PATH. Perl scripts, for instance, can use perl foo.pl %s, where %s will be replaced with the path to the input file, or add a shebang sequence in the first line and use ./foo.pl %s, like this:

#!/usr/bin/perl
...

• it has to return 0 upon success and non-zero upon error.
• it must output the resulting XML content through stdout, and conversion status through stderr.

You will also have to write a document format descriptor so XMLEye can tell when your converter should be used.

Optionally, you could write some stylesheets so XMLEye can provide a better visualization, instead of the generic XML one. See StylesheetInfrastructure for more details.

Currently, there are two input converters created for XMLEye. More converters are on the way: check the feature requests at the forge.

Converts ACL2's output from the Lisp source describing the proof. pprocACL2 is a Perl script which uses ACL2::Procesador, the Perl module which does all the work. This converter is backed by an automated test suite which details most of the things first-time users would be interested in while learning about ACL2. Multifile ACL2 projects certifying and using user-defined books are partially supported. ACL2-specific stylesheets are included:

• The ppACL2 stylesheet adds proper labels to the proof elements, hides uninteresting subelements and uses icons to indicate whether the proof of a specific element was successful or not.
• The summaries stylesheet inherits from the ppACL2 stylesheet and strips everything except the summary from each proof.
• The reverse stylesheet inherits from the ppACL2 stylesheet as well, and inverts the order of the proof elements.

This converter requires the libxml2 headers and libraries. If you're in Windows, Strawberry Perl includes it, and works Just Fine (TM).

This converter uses an adaptation of the YAXML XML binding for YAML and the YAML::XS binding to the libyaml library.

Anchors are detected by filtering multiple references to the same memory address. Its yaxml stylesheet is a slight improvement over the generic xml included with XMLEye, supporting maps, vectors and links between anchors and their referenced elements. It includes a battery of test YAML and JSON files which perform a complete YAML→XML→YAML roundtrip transformation using an improved version of the YAXML XSLT stylesheet and make sure that no data was lost or modified.

This converter requires the libxml2, libexslt, gdbm and gcrypt headers and libraries. Use Strawberry Perl in Windows and the XML::LibXSLT PPM. Installing it from CPAN, even if you use these prepackaged binaries does not work. And a quick search on mailing lists and the CPAN bugtracker didn't turn up much.

If you want to use any of the converters, first check whether you can use the standalone/PAR distributions (see below), or the Debian packages available at XMLEye's private repository. If you can't use them for some reason or you want to try the very latest version from SVN, you can follow these steps:

1. Install whatever libraries are required by the converter using your distribution's package manager. If you're using Windows, I recommend Strawberry Perl over ActiveState's ActivePerl. It is much easier to use, at least for me, and everything works. I had problems creating the standalone distributions using ActivePerl. Windows users will need PAR::Packer 0.981 or later, if it exists by now at CPAN, or the latest trunk (revision 656 works fine) from its SVN repository, using the TortoiseSVN client, for instance. Please do not use the 0.980 version from CPAN if you're in Windows: it had a bug which made installing it impossible for most Windows users.
2. Obtain the latest copy of the source from the SVN repository or get a snapshot from the forge. If you use a SVN snapshot, you'll need to install Module::Install first.
3. Run the following commands (use dmake instead of make with Strawberry Perl):

perl Makefile.PL
sudo make
make test
sudo make install

These commands will build, test and install the package. The second command will install any dependencies from CPAN. You will still need to install their stylesheets (provided in the xslt subdirectories) and document format descriptors (formats) manually. See their respective pages for more details.

You can also make up your own PAR and standalone distributions using the generateDistributions.pl script. I haven't got multi-architecture PAR files to work in Windows, so all PAR distributions are either architecture-independent (-noarch) or specific to a single OS/CPU combination.

If you go to the file area in XMLEye's forge, you will see that some converters include files like (module name)-(version)-par-(extra info).tar.gz or (module name)-(version)-standalone-(extra info).tar.gz. Those are ready-to-run prepackaged PAR-based and standalone distributions, respectively: unpack them right on top of XMLEye's main directory. Subdirectories should match, so the files in formats go in the existing formats subfolder, and so on. These distributions include both the converters themselves and their related stylesheets and format descriptors.

There are some differences between PAR and standalone distributions that you should be aware of, though. Standalone distributions do not require any previous setup. Everything needed (even the Perl interpreter itself) is neatly packed into the executable file. They are CPU/OS specific, so check which one matches your environment best first.

PAR distributions are lighter and run slightly faster, but they require a Perl environment and the PAR Perl module. If you've got Perl, you can install PAR with:

cpan PAR

If you're using a Debian-based distribution, better run this instead:

sudo aptitude install libpar-perl

Additionally, if you see -noarch in one of those PAR-based distributions, it means that it will work in any CPU/OS combination (well, so long as your Perl environment is relatively recent: 5.8.8 and 5.10.1 have been tested, but older versions might work as well). Sometimes they will only include support for one or several CPU/OS combinations, though. It all depends on whether it's a pure Perl converter, or if it depends on external libraries.