Contents:
=========

This is the AGFL system. The directories contain the following items:
 - doc: the user documentation
 - liblexicon: the directories with:
     * src: the lexicon library reading routines
     * doc: the system documentation for the lexicon library
 - lexgen: the lexicon generator, with:
     * src: the C++ sources of the lexicon generator
     * doc: the system documentation of the lexicon generator
 - gen: which contains the parser generator, with:
     * src: the sources of the parser generator and the runtime system
     * doc: various documents, mostly system documentation
     * test: various test grammars
 - test: a directory with various test grammars with lexicon.



Installation on UNIX:
=====================

Compiling and installing AGFL on Unix and alike systems is quite
straightforward. Required are:
 - a recent C and C++ compiler, preferably GCC
 - a recent CDL3 compiler 
   (You can download it from the CDL3 website at http://www.cs.kun.nl/cdl3 )
 - GLib version 1.2.10 or later.
 - flex (or lex)
 - bison (or yacc)
 - the GNU programs make, libtool, autoconf, automake;
 - tar and GNU's gzip;
 - a standard shell (usually /bin/sh suffices)


A typical installation procedure looks like:

	./configure --prefix=/usr/local --with-cdl3=/usr/local
	make
	make install

If you run BSD, remember to use gmake, not make.

General installation instructions are in the INSTALL file.
Remember to remove the config.cache file if the ./configure step 
repeatedly gives trouble.

The compilation of utils/scanner.cc (which is generated by flex) can 
fail on systems with GCC 3.x and flex 2.4. This is a bug in flex.
In that case, this is the patch for either flex 2.4 or scanner.cc:

--- flex.skl    Wed Sep 11 01:58:54 1996
+++ flex.skl    Fri Oct 17 13:17:42 2003
@@ -25,7 +25,7 @@
 
 #include <stdlib.h>
 %+
-class istream;
+#include <iostream.h>
 %*
 #include <unistd.h>



Installation on Windows:
========================

Compiling AGFL for MS Windows is harder than compiling AGFL for a
Unix flavour. Instead, you can opt for the binary package, which
contains a stripped-down version of the MingW32 suite as well, 
because AGFL needs it to generate parsers.

For the wild-hearted, required are:
 - MingW32 (or -untested- Cygwin)
 - the Win32 GLib port
 - a CDL3 compiler
 - a program to extract the source tarball

To compile AGFL, special makefiles are included. These files are 
called Makefile.cygwin for historical reasons. These makefiles need 
modifications in order to find various programs.

Both binary and source packages contain a script called setagfl.bat.
It might need modifications to reflect the actual place where AGFL
is installed. You can use any text editor for this.

To use AGFL, start a command prompt and run the setagfl.bat once for
each session, or put the contents in the autoexec.bat file.


Installation from CVS:
======================

If you have checked out AGFL from CVS, you'll need to create a few
extra files before using the previous instructions for stable
AGFL releases.
The autogen.sh script will run these utilities for you:

	aclocal     [-I /usr/local/share/aclocal]
	libtoolize
	autoheader
	automake
	autoconf
	configure
	
autogen.sh passes its parameters to configure, so you'll probably
end up running something like

	./autogen.sh --prefix=/usr/local/kun --with-cdl3=/usr/local/kun
	make
	make install


Usage:
======

After installing the AGFL system, grammars and lexica can be compiled.
Suppose there is a grammar in the file "grammar.gra":

    /path/to/agfl/bin/gen grammar.gra

This will generate an executable named "grammar". When you start the
executable, the program will give you a prompt:

    >>

Here you can type the input to the parser. After pressing <enter>, the
parser will start to recognize the input according to the grammar. The
parser can give more (verbose) output putting options on the
command-line. The -h option will give an overview of the possible
options. This also works for the parser generator "gen".


A Simple Grammar
================

Writing the various text files can be done using any text editor which
can write plain ASCII text files.

To show the behaviour of the AGFL system and generated parsers, we
will use a toy grammar that consists of three files. The grammar file
example.gra looks as follows:

GRAMMAR example.

ROOT toy.

NUMBER :: singular | plural.
PERSON :: first | second | third.

toy:
  subject (NUMBER, PERSON),
    verb (NUMBER, PERSON).

subject (singular, first): "I".
subject (NUMBER, second): "you".
subject (singular, third):
  "he";
  "she";
  "it".
subject (plural, first): "we".
subject (plural, third): "they".


The lexicon file example.lex contains this:

LEXICON example.

verb(NUMBER, PERSON).

INCLUDES simplelex.


The file simplelex.dat contains this:

"walk"          verb (singular, first | second)
"walks"         verb (singular, third)
"walk"          verb (plural, PERSON)


You can generate a parser by typing, like explained above,

    /path/to/agfl/bin/gen example.gra

After starting the generated program 'example', a prompt ( >> ) is 
shown and we type 'I walk', which returns:

$ example
>> I walk
toy
  subject(singular, first)
    "I"
  verb(singular, first)
    "walk"


The sentence ``I walk'' has just one parse tree. The sentence ``you
walk'' results in two parse trees.

For much more information, see the user documentation.


Licenses:
=========

The components of the AGFL system are licensed as follows:
 - the programs (which reside in the "${prefix}/bin" directory) are
   subject to the GNU GENERAL PUBLIC LICENSE, which can be found in the
   source package in the file named COPYING. If not, write to the Free
   Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
   MA 02111-1307  USA
 - the libraries (residing in the "${prefix}/lib" directory) and the
   include files (residing in the "${prefix}/include" directory) are
   distributed under the GNU LIBRARY GENERAL PUBLIC LICENSE. You should
   have received a copy of the GNU Library General Public License along
   with this library; if not, write to the Free Software Foundation,
   Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

In addition, each source file has the appropriate license mentioned at
the start.

AGFL supports use of the GNU Readline library, to enable end-users to
use the up/down arrow keys in generated parsers. However, by default
this is disabled. The GNU Readline license is GPL (and not LGPL, as it
should have been), which means that binary-only distribution of generated
parsers is prohibited.
However, for end users who are willing to distribute their source grammars,
we recommend to run configure additionally with the next option:

   ./configure --with-readline


-- The AGFL team <agfl@cs.kun.nl>.

($Id: README,v 1.11 2003/11/09 16:18:33 pspiertz Exp $)
