This document is a tutorial for  users.   It does not  describe the
program  interface;  all this has  anything  to  say  about  is the user
interface.

     Let's suppose you are using some program which was written with the
keytree matcher for a user interface.  This means you get  some sort  of
prompt (what  this prompt looks like is entirely  up to the  person  who
wrote the program).  What can you do here?

     Well, first off, there must be a number  of commands the programmer
has provided for you to enter.  You can either  enter  one  of  these or
enter something special.

     Let's  start  with  how  you  enter  the  commands  the  programmer
provided.  Well, these can  be just about  anything, though usually they
will  be words  (or something  like  words).   For  example, suppose the
programmer has  provided four commands:  "exit", "display",  "read", and
"write".  Well, suppose you  want to enter "read".   Then you  can  type
"read" (of course  the  quotes aren't to  be entered)  and press  space,
RETURN,  or  ESC.  Then  whatever the  programmer has  arranged to  have
happen when you enter "read" should happen.

     Well now, this isn't really very fancy, is it.  Well, now let's get
into  something a  little more interesting.  Try  typing  "r"  and  then
pressing space.  The matcher will fill in the rest of "read" for you and
then will continue as if that's what you had typed in the first place.

     This is all very nice, but what if two commands begin with the same
letter?  Well, you can enter more than just the first letter if you like
(as in  the first example, where you entered the whole keyword).  If you
have  entered  enough for the  matcher to tell which keyword you  meant,
then it will  fill in the rest  for you.  If you didn't enter enough, it
will beep  at  you and  wait for you to type more.  If what  you entered
matches more than one  keyword,  then of course these  keywords  must be
equal at least for  a  short piece  at the  beginning.   If they are all
equal for more than the piece you entered, the matcher will just fill it
out up  to the next place where they differ  and wait for you to fill in
some more.

     By the way, what if you make a mistake?  For example, let's suppose
we have the same  four  possibilities  as above  and  you  enter "reqad"
instead of "read".  Then the matcher will erase the "qad" part and  beep
at you; then you  can go  on from there.  In short,  the matcher  erases
back far enough that what's left matches some valid keyword.

     Of course, if you notice a  mistake  before you hit space, you  can
use the delete key (backspace works too) to erase it.

     Don't worry  if this seems a little confusing;  the exact algorithm
used is not simple.  But in most cases, the  matcher does the  "obvious"
thing.  If you feel unsure, experiment!

     A  note is in order at this point.  If the programmer wishes, it is
possible for a keyword to require more input to make things happen.  For
example,  in the example  above, the  keyword  "display" could have  you
enter "image" or "mask"  before  it  does anything.  In  this case,  the
matcher will fill out "display" and wait.  Now you are supposed to enter
"image" or  "mask" as above.   Or the extra input  can be  a number or a
string or whatever.

     On to the special things you can do.

     Let's suppose you just want to find out what you can type.  Hit `?'
and you should get a list of the keywords which are valid at that point.
If you're halfway through typing a keyword, the  list will include  only
keywords which match what you've typed so far.

     There is another special character, `*',  which shows all  keywords
you can enter and all the keywords  underneath them.  This  is not  used
very much; the output tends to be rather long.  Don't worry if you never
find a use for it.

     There  are two special things you can do  which are valid only when
they are  right  at the beginning  of an input line.  One of  them  is a
shell  escape; the other allows you to tell the matcher to read commands
from a file.

     To use the shell escape, enter a `!' sign as the first character of
the line.  If you enter anything after the!  before you hit RETURN, then
whatever you enter will be executed as a shell command; then you will be
put back into the matcher and can continue whatever  you were doing.  If
you don't give any  command,  an interactive shell will be  started  up.
Which shell does  it use, you ask?   Well, it tries to be smart about it
and use whichever shell you are currently  using.  If it can't figure it
out, it will say "No shell" and it won't start up anything.

     To tell the matcher to read commands from a file, enter an `@' sign
as the first character of a line; the follow this @ sign with a filename
(no spaces please).  The matcher will then read from that  file; when it
reaches EOF,  it  will return  control to  you.  You can nest @ files as
deeply  as  you like  except that  the  matcher  will  run  out of  file
descriptors if you go  too deep.   This is not a  fixed number since the
program  you are running  may have files  open too;  but  any reasonable
program won't have enough files open to keep you from nesting @ commands
at least (say) ten deep.