Contents:
=========
This is the AGFL system version 3.2. 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:
     * cmp: 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
     * run: 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)
 - 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.

For the not faint of heart, required are:
 - Visual Studio 7.1
 - a CDL3 compiler (not the old CDL3 compiler, but MCDL, available
   at ftp.cs.ru.nl:/pub/vb/mcdl). You must install mcdl before you
   can link agfl and you must adapt the location for the libmrts.lib
   in the project file for agfl-coder
 - a program to extract the source tarball

To compile AGFL, a Visual Studion "solution" file is provided
in the msvc71 directory.

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
If you see the message './ltconfig not found' then, most likely,
your version of libtoolize is out of sync. On a FreeBSD system
try libtoolize13 in stead.

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 AGFL-object-file named "grammar.aob".
You can execute this compiled grammar with agfl-run grammar.aob.
When you start the parser, it 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 "agfl".


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/agfl example.gra

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

$ agfl-run 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:
===============
Some time ago 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:

 - All programs, libraries, header files and documentation are
   subject to version 3 of the GNU GENERAL PUBLIC LICENSE, which
   can be found in the source package in the file named COPYING.
   Alternatively, a copy of this license can be obtained from
   http://www.gnu.org/licenses/licenses.html

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. To enable using the
readline library, configure the package with

   ./configure --with-readline

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

