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 is the first public release of phpRDFT.

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.

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

=== RELEASE NOTES ===

The software implements all the spec at http://www.semanticplanet.com/2003/08/rdft/spec-20030904
which is not surprising since the spec was re-written to correspond with this implementation. 

There are some notable omissions from the spec and this software:

* Namespaces for output elements and attributes. Currently there is no way to output
  a namespaced element to the result tree. OK for standard HTML, but a bit limiting when
	outputting XML. This is a priority feature for the next version.



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: phprdft-readme-20030911.txt,v 1.1 2004/04/20 08:16:40 ian Exp $