mercurial-quick-start

HowTo: Download code from the repository

I had a little difficulty checking out code from the repository, so I created this page to help those who are new to Mercurial and the Microformats repository.

Introduction

Microformats.org uses Mercurial for source code management. You can find microformat generators, tests, and Brian Suda's X2V scripts in the repository at [1]

Mercurial

Mercurial offers binary packages and source code for Windows, Linux, and Mac OSX. You can read more about how to install Mercurial from their wiki.

Checking out code

Once you have Mercurial installed, the quickest way to get started with the following recipe.

The first time you access a repository, you must first clone the repository on your local drive.

For example: to download the latest code for X2V, you would use the following:

hg clone http://hg.microformats.org/x2v/

Once you have cloned the repository, you can update your local code with the latest from the Microformats repository with:

hg update http://hg.microformats.org/x2v/

Rake

For those of you with Rake installed on your machine you can take advantage of the Rakefile included with the Generators and X2V. The Rakefile makes two commands available:

1. rake hg:pull_update -- Pull and update this repository. May fail if you need to merge
2. rake hg:push_update -- Pushes this repository to microformats.org. Pulls and updates first

Testing the XSLT scripts

The XSLT scripts in the mercurial repository are accompanied by Perl test scripts. With these test scripts you can test the XSLT scripts against the tests from the tests repository using LibXSLT. Various other XSLT engines are also supported: 4xslt, Saxon (Java version), Xalan-J, Xalan-C.

Installing prerequisites

In order for the Perl scripts to work you'll need Perl 5.8 and the following additional modules: XML::LibXML, XML::LibXSLT, Text::Diff.

MacOSX

Install MacPorts

and then run

sudo su
port install p5-xml-libxslt
port install p5-text-diff

*nix

Either use your distributions package management tool or "cpan install" to install the Perl modules listed above.

Windows

Get ActivePerl 5.8 from http://www.activestate.com/Products/activeperl/.

Afterwards see http://theoryx5.uwinnipeg.ca/ppms/ for instructions on how to install the additional modules.

You might also want to install Win32::Console::ANSI.

Preparations

First you need to checkout both the tests and the XSLT repositories:

hg clone http://hg.microformats.org/x2v /home/johndoe/tests
hg clone http://hg.microformats.org/tests /home/johndoe/xslts

The test scripts are in the XSLT repositories, in order to tell them where the test files are located you have to set the MICROFORMATS_TESTS environment variable.

On *nix and MacOSX (assumig you're using the bash shell):

export MICROFORMATS_TESTS=/home/johndoe/tests

On Windows:

set MICROFORMATS_TESTS=C:\path\to\tests

Running the test

First change to the directory where the XSLTS XSLTs are located. Afterwards you can start the test scripts with:

• hcard/test.pl
• hcalendar/test-vcal.pl
• hatom/test.pl

(On Windows: Use backslashes instead of forward slashes)

Here are some examples:

./test.pl -x # Run all tests with libxslt
./test.pl -x 5 # Run tests 1 with all Engines
./test.pl --saxon --4xslt  1-3 12 15  #  Run test 1, 2, 3, 12, 15 with Saxon and 4XSLT
./test.pl --xalan-c 8-18 -e 12-14     #  Run test 8-11 and 15-18 with Xalan-C

Using additional XSLT engines

If you want to use any XSLT engines (besides LibXSLT) you have to install them and make sure that the can be launched from the test script.

For Java based XSLT engines you need to add the the engine's .jar file (saxon8.jar and xalan.jar respectively) to your CLASSPATH environment variable. Enter

java net.sf.saxon.Transform
java org.apache.xalan.xslt.Process

to test if Xalan-J and Saxon can be called by the test scripts.

For all other XSLT engines add the path to their "bin" directories to your PATH environment variable.

Enter

4xslt
Xalan

into the console to test if 4xslt and Xalan-C can be called by the test scripts.