mercurial-quick-start
HowTo: Download code from the 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
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:
rake hg:pull_update
-- Pull and update this repository. May fail if you need to mergerake hg:push_update
-- Pushes this repository to microformats.org. Pulls and updates first. (you need Ryan King to grant you access 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 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 -A 5 # Run test #5 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.