Written by Erik Peterson, eepeter@cs.cmu.edu
 

GenKit Front-end
================

     GenKit can be run in several different modes: server mode,
interactive mode, and batch mode.  Each of these modes include
debugging and tracing options.

Functions used by all modes

  int loadGrammarFile(string filename);

  Load a grammar file named by filename.  Multiple grammar files can
be loaded this way, though the order the files are loaded is important
and can affect generation.

  // Can be called multiple times, order is important
  int loadLexiconFile(string filename, Symbol language);

   Load a lexicon file named by filename whose words are in "language"
(i.e. Symbol("ENG")).  Multiple lexicon files can be loaded this way,
though the order the files are loaded is important and can affect
generation.

  void initFromFile(string initfile);

    Instead of calling loadGrammarFile and loadLexiconFile separately
for each grammar or lexicon file, the specific necessary files to be
loaded for a given system can be listed in a separate file that can
then be loaded.  The format of this initialization file is 

genlang LANG       : specifies the generation language, used in loading
	             lexicons

load grammarfile   : specifies the name of a grammar file (without
                     ".gra" suffix) to load

loadlex lexiconfile: specifies the name of a lexicon file (without
                     ".lex" suffix) to load

The order of loading the grammar files is important, as is
the order of loading the lexicon files, but lexicon files need not be
loaded in any specific order relative to grammar files.  Also, genlang
should be specified before the first lexicon file is loaded.

Example initialization file:

genlang ENG
load new-shared-english
load new-nespole-english
loadlex shared-english
loadlex nespole-english
loadlex airport-english


  int generateFromFStructure(string fstruct, vector<string> &genstrings, string tracing);

    fstruct is a string containing one of more f-structures, 
genstrings is a string vector where the generated strings will be
stored, and tracing can be "rule", "fs", and "off".  "Rule" tracing
will show the sequence of rules that the generator attempts to run on
the f-structure to produce the final generated string.  "Fs" tracing
will also show the rule matches, and also the f-structures before
application of the grammar rule and after application.  "Off" turns
off all tracing.


  int generateFromFStructure(string fstruct, vector<string> &genstrings);

    Same as above, except tracing is always set to "off".
  

  int generateFromFStructureFile(string filename, vector<string> &genstrings, string tracing);

  Allows program to generate strings from a list of f-structures in
filename.  Tracing options are the same as for generateFromFStructure.



Server Mode

     In server mode GenKit can accept client connections that send an
f-structure, process the f-structure, and return the resulting
generated text if successful or an error message if not.  Server mode
is started with the method:

  void runServer(int serverport);

where serverport is the port where the server will listen for client
connections.

     When a client makes a connection on the listening port, the
server expects to receive the following: a string indicating the
action to be taken, followed by a tab, followed by any accompanying
information, ended by a newline (\n).  The concluding newline must be
the only newline in the message.  Currently only one action,
generating a string from an f-structure, is supported.  In this case
the client sends "genf", followed by a tab, followed by a single
f-structure, with any original newlines replaced by spaces, concluded
with a newline.

     After receiving this message from the client, the server attempts
to generate a string based on the f-structure.  Based on the results
of this, the server can return either "res", followed by a tab,
followed by the generated string, followed by a newline, or "err"
followed by a tab, followed the error message, followed by a newline.
As before, the concluding newline is the only one allowed.

Command Line Options

GenKitTest OPTIONS

OPTIONS:

-f init_file		: Specifies initialization file describing
                          what grammars and lexicons to load.
                          Necessary unless running program in
                          interactive mode.

-l language		: Specify generation language (e.g. ENG for
			  English).

-if input_fstruct_file	: Specifies file containing f-structures from
			  which to generate surface forms.  Starts
			  program in batch mode.

-of output_gen_file	: Specifies file where to write generated
			  sentences.  Starts program in batch mode.

-sp server_port	        : Specifies the port number for the genkit
			  server to use.  Starts program in server mode.

-i			: Start program in interactive mode.

-h			: Print help.


Interactive mode

  void GenKit::runInteractive()

Possible Commands:
compgra grammarfile: Load a generation grammar in grammarfile (w/o .gra ending)
load grammarfile   : Same as compgra
loadlex lexiconfile: Load a lexicon file (without .lex ending)
looklex word       : Look up a work in the currently loaded lexicon
debug (on|off)     : If grammar not loading, will show details of loading
generate fstruct   : Generate text from an f-structure
generatef filename : Generate text from f-structure(s) in filename
tracing (rule|fs|off): Trace just rules, rules&fstructures, or turn off
exit|quit|q        : Quit the program


Batch Mode

  int runBatch(string infile, string outfile);

    In batch mode, Genkit can take a file containing one or more
f-structures, generate based on these f-structures, and write out the
resulting strings, one per line, to outfile.