====== What are converters for? ======

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.

====== How do I make one? ======

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:
<code perl>
#!/usr/bin/perl
...
</code>
  * 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 descriptors|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.

====== Available converters ======

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

===== ACL2 proofs =====

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).

===== YAML 1.1 / JSON documents =====

This converter uses an adaptation of the [[http://www.yaml.org/xml.html|YAXML]] XML binding for YAML and the [[http://search.cpan.org/~ingy/YAML-LibYAML-0.26/lib/YAML/XS.pm|YAML::XS]] binding to the [[http://pyyaml.org/wiki/LibYAML|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 [[http://www.zlatkovic.com/libxml.en.html|prepackaged binaries]] does **not** work. And a quick search on mailing lists and the CPAN bugtracker didn't turn up much.

====== Installation from source ======

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 [[installation from debian package repository|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:

  - Install whatever libraries are required by the converter using your distribution's package manager. If you're using Windows, I recommend [[http://strawberryperl.com/|Strawberry Perl]] over ActiveState's [[http://www.activestate.com/Products/activeperl/index.mhtml|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 [[http://svn.openfoundry.org/par/PAR-Packer/trunk/|its SVN repository]], using the [[http://tortoisesvn.tigris.org/|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.
  - Obtain the latest copy of the source from the SVN repository or get a snapshot from the [[http://forja.rediris.es/scm/?group_id=233|forge]]. If you use a SVN snapshot, you'll need to install Module::Install first.
  - Run the following commands (use ''dmake'' instead of ''make'' with Strawberry Perl):
<code>
perl Makefile.PL
sudo make
make test
sudo make install
</code>

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 [[StylesheetInfrastructure|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.

====== Installation from prepackaged PAR-based/standalone distributions ======

If you go to the [[http://forja.rediris.es/frs/?group_id=233|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:

<code>
cpan PAR
</code>

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

<code>
sudo aptitude install libpar-perl
</code>

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.