Copyright (C) 2003 Ian Davis.

This program is free software; you can redistribute it and/or modify it under the 
terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT 
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License along with this 
program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, 
Suite 330, Boston, MA 02111-1307 USA

=== INTRODUCTION ===

phpRDFT is a PHP implementation of the RDF Templates language specified at:

http://www.semanticplanet.com/2003/08/rdft/spec

This version of the software is the reference implementation of the following 
version of the RDF Templates specification:

http://www.semanticplanet.com/2003/08/rdft/spec-20030916

The first thing to be aware of when using this software is that it is _SLOW_. The
code has been written for clarity and conformance to the spec, not for
performance. Any optimisations present in the code are purely for speeding up
the unit test cycle. The main optimisation has been the introduction of the IndexedModel
class which provides about a 20x speedup over the standard RAP Model class.

This software was built test-first which means that in theory there are no pieces of
functionality that do not have a unit test. In practice this is not entirely true as short
spikes were performed during development that may not be fully covered. However, the
overall test coverage is pretty good - certainly all essential features have unit tests.

=== GETTING STARTED ===

phpRDFT requires RAP which can be obtained from:

http://www.wiwiss.fu-berlin.de/suhl/bizer/rdfapi/

This version requires at least RAP 0.6

If you want to develop phpRDFT further you'll also need phpunit which can be found here:

http://phpunit.sourceforge.net/

The test cases can be run by executing runtests.php

Using phpRDFT is very simple:

1. Create a StylesheetParser object
2. Create a Stylesheet object by calling StylesheetParser's parse method, 
    supplying the XML content of the stylesheet document
3. Get some output from the stylesheet by calling its process method, 
    passing in the RDF content the stylesheet is to act upon.

Here's some sample code:

<?php
	require_once 'StylesheetParser.php';
	
	$stylesheetParser = new StylesheetParser();

	$stylesheet = $stylesheetParser->parse($stylesheetContent);
		
	$output = $stylesheet->process($sourceRdf);
?>

The Stylesheet object can be re-used with different RDF sources to get different
output.


=== COMMAND LINE USAGE ===

It is also possible to run phpRDFT from the command line. There is a script called
rdft.php which can be run as follows:

php rdft.php <template> <source>

where:
  <template> is the filename of an RDFT template
	<source> is the filename of some RDF
	
The script outputs the result to STDOUT.	


=== DEBUGGING ===

Debugging phpRDFT is not so simple.

Stylesheet has an 'asString()' method which returns a string representation of 
the Stylesheet. This is the best way to see what is going on when parsing a stylesheet.

There is some basic syntax checking on stylesheets and nodepaths. These raise PHP
errors if syntax errors are found. More checks can and should be added.

The unit tests in StylesheetTest.php are good examples of how to build a Stylesheet up
from its component objects.

There is no documentation. Every class of any significance has a corresponding unit test.
The unit tests form a specification of the software and also provide usage documentation.
The best way to find out the capabilities of each class is to examine the unit test. You 
should be able to copy and paste code straight from the tests into your own program and
expect the code to work correctly.


Ian Davis, September 2003

Contact me at <iand@internetalchemy.org>. I'm interested in comments, patches, bugs
and real uses of this software. If you're interested in porting to a different language
or re-implementing then drop me a mail since I've got lots more to say about the 
pitfalls etc. 

$Id: readme.txt,v 1.1 2004/04/20 08:16:40 ian Exp $