Contents:
=========
This is the AGFL system version 2.5. The subdirectories contain the following:
 - doc: the user documentation
 - libabase: various parts of code, general agfl library.
 - 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
     * as:  the sources of the abstract machine assembler (future work for Agfl 2.6)
     * rts: the sources of the runtime system
     * doc: various documents, mostly system documentation
     * test: various test grammars
 - grammars: large example grammars, with:
     * npx: a grammar for english
     * latin: a grammar for latin

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.ru.nl/cdl3 or
    ftp it from ftp.cs.ru.nl:/pub/cdl3; the latest version is 1.2.7)
 - flex (or lex)
 - the GNU program make,
 - tar and GNU's gzip;
 - a standard shell (usually /bin/sh suffices)

A typical installation procedure looks like:
(If you run BSD, remember to use gmake, not make.)

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

You do not need to specify the --with-cdl3 if the installed CDL3
compiler cdlc is in your path. The AGFL configure script will try
and autodetect your CDL3 installation

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

Currently Agfl has been tested on the following platform combinations:

- Intel i686 with Linux
- Intel i686 with FreeBSD 4
- Alpha with NetBSD
- Sparc (32 bits) with Solaris 2.8
- AMD64 (64 bits) with Linux (memory information is not correct)
- AMD64 (64 bits) with FreeBSD
- AMD64 (64 bits) with NetBSD


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 not faint of heart, required are:
 - MingW32 (or -untested- Cygwin)
 - 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.

With Agfl 2.6, we hope to provide Agfl with native MS Windows support
(i.e. we will provide a workspace and project files for compilation
with Visual C++)


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.
You could also use the commandline yourself to add some options to
the autotools.

	aclocal     [-I /usr/local/share/aclocal]
	libtoolize --copy --force
	aclocal
	autoheader
	automake --copy --add-missing
	autoconf
	./configure --prefix=$HOME --with-cdl3=/usr/local

autogen.sh passes its parameters to configure, so you'll probably
end up running something like
(If you run BSD, remember to use gmake, not make.)

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

This is the right place for a word of warning for freely mixing versions 
of libtool, automake and autoconf. Not al versions of each tool works
with the others. One known source of problems is the combination of
libtool version 1.5 with autoconf 2.59

To find the exact path for the --with-cdl3 option try 

	...> whereis cdlc
	cdlc: /usr/local/bin/cdlc /usr/local/man/man1/cdlc.1

Then use from the first path the part upto but without '/bin/cdlc' 

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/agfl 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 two files. The grammar file
example.gra looks as follows:

GRAMMAR example.

LEXICON simplelex

DEFINES verb(NUMBER, PERSON).

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

On name changes:
===============
Recently the name 'KUN' was changed into 'RU, Radboud University', 
implying a domain change from 'www.kun.nl' to 'www.ru.nl'.
If in some future time, any URL mentioned is no longer available 
and it includes the word 'kun', try the substitution of 'ru' for it.

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 the 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. Since the GNU Readline license is GPL (and not LGPL, as
it should have been), binary-only distribution of generated parsers
linked against the GNU readline library 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 prohibition against binary-only distribution will be lifted with Agfl 2.6.
With Agfl 2.6 only the runtime system will be linked against the Gnu Readline
library and not the code generated by the parser generator and abstract machine
assembler, so distribution of the abstract machine object code for a specific
grammar is allowed without having to distribute the original grammar.

The AGFL team <agfl@cs.ru.nl>.

($Id: README,v 1.22 2006/11/01 11:03:35 marcs Exp $)
