Fix javadoc comments

[cql-java-moved-to-github.git] / README

diff --git a/README b/README
index d0b3d9f..08a76a5 100644 (file)
--- 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
 
 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?  :-)
 
 
 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
 --------
 
 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.*
 
 
        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");
        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
 -----------
 
 
 
 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
 ------
 
 
 
 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
 -------
 
 
 
 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
 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
 
 
 SEE ALSO

@@ -67,4 +108,11 @@ SEE ALSO
 
 Adam Dickmeiss's CQL compiler, written in C.
 Rob Sanderson's CQL compiler, written in Python.
 
 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.]
+