X-Git-Url: http://jsfdemo.indexdata.com/?a=blobdiff_plain;ds=sidebyside;f=README;h=08a76a510651aa6d0504b698a4dca24054241a11;hb=768c20f64b8b2ce463aab27cf844fad5865995fa;hp=d0b3d9f2ad9c297536f68a79aa1de1d4178458ac;hpb=99c44fee61010958478dea758d7b1322cd7a9ae6;p=cql-java-moved-to-github.git

diff --git a/README b/README
index d0b3d9f..08a76a5 100644
--- a/README
+++ b/README
@@ -1,13 +1,22 @@
-$Id: README,v 1.2 2002-10-24 16:06:34 mike Exp $
+$Id: README,v 1.18 2002-11-14 22:04:16 mike Exp $
 
-cql-java -- a free CQL compiler for Java
+cql-java - a free CQL compiler, and other CQL tools, for Java
 
 
-This project provides a set of classes for representing a CQL parse
-tree (CQLBooleanNode, CQLTermNode, etc.) and a Compiler class which
-builds a parse tree given a CQL query as input.  It also provides
-compiler back-ends to render out the parse tree either as XCQL or
-Yaz-style Prefix Query Format (PQF).
+INTRODUCTION
+------------
+
+cql-java is a Free Software project that provides:
+
+* A set of classes for representing a CQL parse tree (a base CQLNode
+  class, CQLBooleanNode and its subclasses, CQLTermNode, etc.)
+* A CQLCompiler class (and its lexer) which builds a parse tree given
+  a CQL query as input.
+* A selection of compiler back-ends to render out the parse tree as:
+	* XCQL (the standard XML representation)
+	* CQL (i.e. decompiling the parse-tree)
+	* PQF (Yaz-style Prefix Query Format)
+* A random query generator, useful for testing.
 
 CQL is "Common Query Language", a new query language designed under
 the umbrella of the ZING initiative (Z39.59-International Next
@@ -22,44 +31,76 @@ which is supposed to be easier to parse.  More information at
 But if you didn't know that, why are you even reading this?  :-)
 
 
+What's what in this distribution?
+
+	README	This file
+	VERSION	The version-number of this distribution
+	src	Source-code for the cql-java library
+	lib	The compiled library file, "cql-java.jar"
+	bin	Simple shell-scripts to invoke the test-harnesses
+	docs	Documentation automatically generated by "javadoc"
+	test	Various testing and sanity-checking frameworks
+	etc	Other files: CQL Grammar, generator properties, etc.
+
+"Installation" of this package would consist of putting the bin
+directory on your PATH and lib/cql-java.jar on your CLASSPATH.
+
+
 SYNOPSIS
 --------
 
-Test-harness:
+Using the test-harnesses:
 
-	$ echo "foo and (bar or baz)" | java org.z3950.zing.cql.CQLParser
+	$ CQLParser 'title=foo and author=(bar or baz)'
+	$ CQLLexer 'title=foo and author=(bar or baz)'
+		(not very interesting unless you're debugging)
+	$ CQLGenerator etc/generate.properties seed 18
 
-Library:
+Using the library in your own applications:
 
 	import org.z3950.zing.cql.*
 
+	// Building a parse-tree by hand
+	CQLNode n1 = new CQLTermNode("dc.author", new CQLRelation("="),
+				     "kernighan");
+	CQLNode n2 = new CQLTermNode("dc.title", new CQLRelation("all"),
+				     "elements style");
+	CQLNode root = new CQLAndNode(n1, n2);
+	System.out.println(root.toXCQL(0));
+
+	// Parsing a CQL query
 	CQLParser parser = new CQLParser();
 	CQLNode root = parser.parse("title=dinosaur");
-	print root.toXCQL();
-	print root.toPQF(qualSet);
-	// ... where `qualSet' specifies CQL-qualfier => Z-attr mapping
+	System.out.print(root.toXCQL(0));
+	System.out.println(root.toCQL());
+	System.out.println(root.toPQF(config));
+	// ... where `config' specifies CQL-qualfier => Z-attr mapping
 
 
 DESCRIPTION
 -----------
 
-Se the automatically generated class documentation in the "doc"
-subdirectory.  (### It's not there yet, of course)
+See the automatically generated class documentation in the "doc"
+subdirectory.
 
 
 AUTHOR
 ------
 
-Mike Taylor <mike@z3950.org>
-http://www.miketaylor.org.uk
+All code and documentation by Mike Taylor <mike@z3950.org>
+	http://www.miketaylor.org.uk
+Please email me with bug-reports, wishlist items, patches, deployment
+stories and, of course, large cash donations.
 
 
 LICENCE
 -------
 
-This software is open source, but I've not yet decided exactly what
+This software is Open Source, but I've not yet decided exactly what
 licence to use.  Be good.  Assume I'm going with the GPL (most
-restrictive) until I say otherwise.
+restrictive) until I say otherwise.  For what it's worth, I think the
+most likely licence is the LGPL (GNU's Lesser General Public Licence)
+which lets you deploy cql-java as a part of a non-free larger work.
 
 
 SEE ALSO
@@ -67,4 +108,11 @@ SEE ALSO
 
 Adam Dickmeiss's CQL compiler, written in C.
 Rob Sanderson's CQL compiler, written in Python.
-All the other free CQL compilers everyone's going to write.
+All the other free CQL compilers everyone's going to write  :-)
+
+
+THINGS TO DO
+------------
+
+[See the final "Still to do" section of the "Changes" file.]
+