ReadMe.txt - An intro document for UKernel.

092802: Benjamin Han <benhdj@cs.cmu.edu> Updated file list to add 
        fStrucFunc.cpp.
081601: Benjamin Han <benhdj@cs.cmu.edu> Updated file list to add
        the manual doc/uKernelManual.ps and removed Operators.txt, 
        Guidlines.txt, TO-DO.txt, and Diff-GenKit.txt.
071301: Benjamin Han <benhdj@cs.cmu.edu> Version 1.78: updated file list 
	to add fsRegs.*, eFA*.* and eFunc.*.
063001: Benjamin Han <benhdj@cs.cmu.edu> Updated file list to add	
	Guidelines.txt.
062801: Benjamin Han <benhdj@cs.cmu.edu> Updated file list to add	
	Operators.txt.
061501: Benjamin Han <benhdj@cs.cmu.edu> Updated file list; added a section
	explaining the other testing executables.
061201: Benjamin Han <benhdj@cs.cmu.edu> Revised after adding lex*.
052901: Benjamin Han <benhdj@cs.cmu.edu> Version 1.3: indented printing
        is now supported.
052001: Benjamin Han <benhdj@cs.cmu.edu> Version 1.2: now we have *OR*,
        *EOR* and *CASE* equation blocks (eBlock.*).
051501: Benjamin Han <benhdj@cs.cmu.edu> Version 1.1: major overhaul,
        also added *NUMBER*, *INTEGER*, *POSITIVE*.
042201: Benjamin Han <benhdj@cs.cmu.edu> Created.


----------------------------------------------------------------------
1. What is UKernel
----------------------------------------------------------------------

UKernel provides an API for doing unification - this can be either
integrated with a natural language parser or generator which adopts
a unification-based grammar formalism.

Currently UKernel supports pseudo-unifications only (see M. Tomita &
K. Knight, Pseudo-unification and full-unification, CMU CMT memo, 1987).
This is mainly for practical reason - pseudo-unification is easier to
implement and more efficient for practical use. In the future the 
capability of full unification will be added to UKernel.


----------------------------------------------------------------------
2. File list
----------------------------------------------------------------------

License.txt:     GNU Lesser General Public License.
ReadMe.txt:      This file.
ChangeLog.txt:   The change log.
doc/uKernelManual.ps:  The manual of UKernel (in Postscript).

Makefile:       Make file for all binaries.

symbol.hpp:
symbol.cpp:     A symbol is an integralized string - fast to compare.

value.hpp: 
value.cpp:      Value for feature structures.
valTst.cpp:     Testing code for value.*.

fStruc.hpp:
fStruc.cpp:  
fStrucFunc.cpp: Feature structure code.
fsTst.cpp:      Testing code for fStruc.*.

lexicon.hpp:
lexicon.cpp:    Lexicons code.
lexTst.cpp:     Code for demonstrating how to install and search lexicons.

fsRegs.hpp:
fsRegs.cpp:     Feature Structure Regsiters code.

eFArgs.hpp:
eFArgs.cpp:     Arguments for Extension Functions.
eFATst.cpp:     Code for demonstrating/testing eFArgs.*.

eFunc.hpp:
eFunc.cpp:      Extension Functions: for system extension.

equation.hpp:
equation.cpp:   Equation code.

eBlock.hpp:
eBlock.cpp:     Code for an "equation block" (main block, *OR*, *EOR* and
                *CASE* blocks).
equTst.cpp:     Testing code for running an equation block.

grammar.hpp:
grammar.cpp:    Code for a unification-based grammar.

graTst.cpp:
graTstSub.cpp:  Code for demonstrating how to install a grammar.

ush.cpp: 
ush.hpp:        An interactive shell for UKernel.

ushTest.txt:    A sample input file for UShell (./ush < ushTest.txt).


----------------------------------------------------------------------
3. How to build the code
----------------------------------------------------------------------

You need to get Toolbox library to build this code (visit 
http://www.cs.cmu.edu/~benhdj/c_n_s.html). Download both and make the 
directory structure like this:

-+- Toolbox
 |
 +- UKernel

Take a look at Makefile of UKernel and modify parameter settings as you
wish, then

a). For building obj files only: type "make"
b). For building UShell: type "make bin" or "make ush"
c). For building all testing programs: type "make test"

Nothing unusual right?


----------------------------------------------------------------------
4. How to run 'ush' (an interactive shell of UKernel)?
----------------------------------------------------------------------

Type

./ush

and the shell prompt will appear. Type '!?' and '!help' you'll get a
command listing. Type "!? [command/operator]" or "!help [command/operator]" 
to learn more about a specific command/operator ('!' is the prefix of all
shell-level commands).

It should be straightforward enough.


----------------------------------------------------------------------
5. What are the other executables?
----------------------------------------------------------------------

They are "testing/demonstrating" executables - they show you how to
correctly initialize a value, a feature structure, an equation block,
a lexicon, a grammar, etc. Especially pay attention to graTst - it sort
of summarizes all stuff you need to know.


----------------------------------------------------------------------
6. Copyright, disclaimer, comments, etc.
----------------------------------------------------------------------

a. Any bug reports and comments are extremely welcome. Please send
comments to Benjamin Han <benhdj@cs.cmu.edu>.

b. This code is distributed under GNU Lesser General Public License
- you can read a copy enclosed in this package (License.txt). You're free
to use the code provided you give the accurate reference and include
the source code. There is however absolutely no guarantee from the
author in any form and/or for any purposes. Use it at your own risk.
