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
%swill 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:
- 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 (see DocumentFormatDescriptors) 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:
ppACL2stylesheet 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.
summariesstylesheet inherits from the
ppACL2stylesheet and strips everything except the summary from each proof.
reversestylesheet inherits from the
ppACL2stylesheet 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¶
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
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.
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 available Debian packages (see InstallationInstructions). 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 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.
- 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.
- Run the following commands (use
makewith 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 manually install the stylesheets (see StylesheetInfrastructure) provided in the
xslt subdirectories and the document format descriptors (see DocumentFormatDescriptors) in the
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 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:
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.