*******************************************
              **                                       **
              **    An EMACS user interface to ALE.    **
              **             Version 1.0               **
              *******************************************
                                          Olivier Laurens
                                        laurens@cs.sfu.ca
                                             May 30, 1995

                This Emacs Lisp library defines a user 
                interface to ALE in Emacs; it provides
                automatic start up of ALE and tools 
                  for working with ALE grammars.


                   ALE = Attribute Logic Engine
                     B.Carpenter, G.Penn, CMU

                  **Refer to Emacs' documentation**
                   **for all that concerns Emacs**
                   **And to ALE's documentation**
                   **for all that concerns ALE**


Files
-----

The emacs interface to Ale lives in two files:

   - ale.el defines Emacs-Lisp (elisp) functions and modes; 
            it has to be loaded in emacs.

   - emacs.pl defines prolog predicates that implement various utilities, 
            and tools and that implement links between the emacs interface
            and ALE itself. 

On top of these 2 files, you also need a copy of ale.pl which defines
ALE (ftp j.gp.cs.cmu.edu /usr1/carp/ftp), version beta or higher. The
system described here has been tested with version beta and version
2.0.2 only (does anyone use anything else?). The system was developed
under SICStus prolog version 2.1#9. It has not been tested in any
other prolog but it should run quite straightforwardly under Quintus.

You also need two Emacs-list libraries: comint.el and prolog.el.
They should already exist on your system if Emacs and SICStus are 
installed. Note that a version of these libraries is shipped with
SICStus. You should use these rather than the ones that come in the 
Emacs distribution. 

Of course, you also need to have GNU Emacs installed on your
system. The system described here has been tested in emacs version
19.16.1 only. It should work with any version that has X capabilities
(mouse menubar, multiple frames), ie version 18 or higher.


Prerequisites
-------------

Basic knowledge of Emacs is assumed as well as familiarity with Prolog.
Some familiarity with ALE might not be superfluous either.


How to run it?
--------------

insert the following lines in your .emacs file:

     (setq load-path 
	     (cons "<path>" load-path))

     ;;where <path> is the directory where ale.el is to be found
     ;; SFU users: <path> = /net/local-nll1/elisp

     (autoload 'run-prolog "prolog"
	       "Start a Prolog sub-process." t)

     (autoload 'prolog-mode "prolog"
	       "Major mode for editing prolog programs" t)

     (autoload 'run-ale "ale"
	       "Major mode for running ALE sessions" t)

     (autoload 'ale-prolog-mode "ale"
           "Major mode for editing ALE grammars" t)

	 (setq ale-command "<myale>")

     ;;where <myale> is a shell command that runs 
     ;;ale (usually a prolog saved state); see ale.el for more
     ;;information about that
	 ;; SFU users: <myale> = /net/local-nll1/bin/ale001

Prior to starting emacs, make sure the environment has the variable
EPROLOG set to sicstus (''setenv EPROLOG sicstus''). You should also
byte-compile the elisp libraries prolog.el, comint.el, and, of course
ale.el. To byte compile a library, just start an emacs, and, for each
library to byte-compile do M-x byte-compile-file RET.

In your ALE grammar, add the following on the FIRST line of the file:
				% -*-ale-prolog-*-

Once this is done, proceed as follows:

     - create a directory for your grammar, say ~/english-gram and copy
       your ALE grammar into it. The interface will always make sure
	   that ALE's compiled files are written in that directory.

     - Start emacs ('gemacs' on an X terminal or 'gemacs -nw' otherwise)

     At this point you can either

     - Visit your grammar (if you already have one) in emacs. If your grammar
       contains the string 
                            % -*-ale-prolog-*-
       on the first line, the file will be visited with 'ale-prolog-mode',
       which gives the key bindings described further down in the present
       document. If you don't want to insert this line in your grammar,
       you can turn on 'ale-prolog-mode' manually (M-x ale-prolog-mode)

     - type C-cC-c in the buffer that contains your grammar, sit back, and
       watch...

     Or

      - type M-x run-ale and load your grammar from the main menu



Emacs
-----

If you are familiar with Emacs V18 or higher, skip this section...

The Ale interface makes use of various Emacs facilities, one of which
is the possibility to display multiple windows/frames. A 'frame` in
Emacs is what is called a window in X, and 'windows' in Emacs are
subdivisions of frames. A 'buffer', in Emacs terms, is an object that
contains text or a process (together with its input/output streams). A
buffer can be displayed in a window, or even in several windows
simultaneously, and each of these windows may appear in different
frames.

If you are running Emacs from a dumb terminal, then you can have only
one frame (the terminal), but this frame can still contain multiple
windows.

A major-mode is associated with each frame. A major-mode defines how
the contents of the buffer should be interpreted and what keyboard
input does among other things. The 'status line' (reverse video, at
the bottom of each window) tells the name of the buffer currently
displayed in the window and it's mode (in parenthesis).

Useful keys to know to operate on buffers, windows and frames:

	 C-xb  switch to another buffer
	 M-<  go to beginning of buffer
	 M->  go to end of buffer
	 C-xo  switch to another window
	 C-x1  make current window the only one
	 C-x0  get rid of current window
	 C-x2  split current window horizontally
	 C-x3  split current window vertically
	 C-x5b switch to another buffer in another frame


The Interface
-------------

The Ale interface has two major components: the 'ale-interaction' buffer
and the '*prolog*' buffer. The former is a main menu, the latter is the
actual prolog process running Ale. The following describes the use of these
components.


ALE-INTERACTION

In this buffer, you can fire the commands in 3 different ways:

   - Bring the point on the line that describes what you want to do
     and hit return
   - or hit the letter shown between <...> (case sensitive)
   - or if you are running under X, select the option you want from the
     'Ale' menu on the menu bar with the mouse.

The choices are:
                 Compile <S>ig and Gram
				 Compile <G>rammar only
				 Compile <R>ules only
				 Compile <L>ex only
				 Compile <D>cs only
				 Compile <E>mpty only
				 <r>eload Grammar
				 <e>dit Grammar
				 <p>arse
				 Parse string <a>gain
				 Show <l>ast Parse
				 <d>erivation Tree
				 <s>ignature
				 Lookup <w>ord
				 Show <g>rammar rule
				 Show <m>acro
				 Pr<o>log Prompt
				 <B>uffers list
				 <Q>uit Ale

   - Compile <S>ig and Gram: compiles a grammar. Prompts you for the
     filename in the minibuffer.

   - Compile <G>rammar only: This option recompiles only the grammar itself. Use
     it if you haven't made any changes to the signature.

   - Compile <R>ules only: compiles the grammar rules only

   - Compile <L>ex only: compiles the lexicon only

   - Compile <D>cs only: compiles the definite clauses only

   - Compile <E>mpty only: compiles empty categories only

   - <r>eload Grammar: use this to load a grammar, say at the beginning of
     a session, if you do not want to (ale-)recompile it (faster)

   - <e>dit Grammar: This displays the buffer containg your grammar source code.
     It prompts your for a grammar name if no grammar has been loaded yet. In 
     the grammar buffer, the following key bindings are available for interaction
     with Ale (on top of all standard Emacs text editing commands): 

            - C-cC-k	consult the grammar source code in Prolog
            - C-cC-c    consult the grammar source code and do compile_gram
                        (ale compiles grammar and signature)
            - C-cC-g    consult the grammar source code and do compile_grammar
                        (ale compiles the grammar only)
            - C-cC-l    consult the grammar source code and do compile_lex
                        (ale compiles the lexicon only)
            - C-cC-r    consult the grammar source code and do compile_rules
                        (ale compiles the rules only)
            - C-cC-o	consult the grammar source and reload from compiled files
            - C-cC-x    return to Ale main menu (ale-interaction)

   - <P>arse: self explanatory. Note, you will get weird output if you haven't
     loaded a grammar. If the parse fails, you will see whatever Ale returns.
     Watch the minibuffer: the number of parses found will be shown in it.
     If you want the system to show the derivation automatically, set the 
     variable ale-show-derivation-on-parse to non-nil; If you'd rather see the
     feature structure of the edge(s) spanning the entire string, set the variable
     ale-pp-on-parse to non nil. (note if both variable are non nil, 
     ale-show-derivation-on-parse will win)

   - Parse string <a>gain: this will show a buffer that contains the 
     strings that have already been parsed in the current session. You can 
     reparse any of the strings by putting the point on it and hitting 
     'line feed' or C-J. You can insert the contents of a file in this buffer
     with C-xi. You can save this buffer to a file with C-xw. It is also 
     possible to visit a file and set its mode to ale-text (M-x ale-text-mode)
     so that you can parse its contents with C-J.

   - Show <l>ast Parse: shows the features structures of the edges spanning the
     entire sentence. 

   - <d>erivation Tree: this displays a diagram of the parse chart. See DERIVATION
     for details about what you can do with it.

   - <s>ignature: this displays the signature. See SIGNATURE for details about 
     what you can do with it. 

   - Lookup <w>ord: Pretty prints the lexical entry(ies) for a word

   - Show <g>rammar rule: pretty prints a rule

   - Show <m>acro: pretty prints a macro. You must give the macro name and
     its arguments (as anonymous variables) at the prompt, for example
     ''noun(_,_)''

   - Pr<o>log Prompt: this shows you the *prolog* buffer. Any processing 
     in progress will be aborted. If you want to see the prolog buffer 
     without interrupting whatever is happening in it, use ''C-xb *prolog*''. 
     You can use the prolog prompt in the prolog buffer as a normal prolog 
     prompt. The following keys are defined in the prolog buffer:

            - C-cC-q	quit Ale and the interface
            - C-cC-x    return to Ale main menu (ale-interaction)
            - C-cC-g    be used if the prolog prompt doesn't seem to 
                        behave normally (performs an emacs 'keyboard-quit' and
                        a prolog 'abort')
	        - C-cC-e	edit the grammar source code

     Additionally, the usual prolog-mode key bindings are available (see Emacs'
     Prolog mode documentation)

    - <B>uffers list: this will bring up a buffer containing the list of all
      the buffers currently defined in Ale interface. You can switch to the 
      ale-buffer you want by bringing the point on it and hitting return. The 
      same choices are defined in the mouse-menu. The last 2 options of the 
      buffers list permit refreshing the buffer list and quitting it (back to 
      ale-interaction)

    - <Q>uit Ale: Self explanatory. Asks for confirmation.



FEATURE STRUCTURES

The feature structures are displayed in buffers of their own that have a special
mode for handling them. The commands available to you are shown at the top of 
the buffer. They are

             - 's'    shrink the feature where the point is
             - 'e'    expand the feature where the point is
             - 't'    hide all the lines indented beyond where the point 
                      is when you hit 't'; a '...' indicates that there is
                      hidden text under that feature. This command is a toggle, 
                      hitting it again will restore all hidden text
             - 'b'    show the buffers list
             - 'q'    quit this buffer and go back to the previous one
             - '>' and '<'  Horizontal scrolling

When you shrink a feature, it is still displayed but all that is below
it is pruned and is replace by '...'. Due to Ale's feature shrinking
routines, all occurrences of the feature in a feature structure will
be shrunk. Note that if you don't expand again a shrunk feature, this 
feature will remain shrunk in any feature structure displayed subsequently,
unlike the 't' command that affects only the current buffer.

Tip: how to display 2 feature structures side by side if you are not running
under X? It is easy. First, display the first FS you want. Then type C-x3 
followed by C-xo. Now, use C-xb to switch to the buffer that contains the
second feature structure (or, for example, to ale-interaction from which you
can obtain a lexical entry...)


DERIVATION

The derivation buffer shows the derivation(s) of the last string
parsed.  It also shows a chart of the inactive edges, ie those edges
that were not used to derive an edge spanning the entire string. If
there were no parse, eg there is no edge spanning the entire string,
then all the edges are inactive.

The commands available in this buffer are:

             - 'e'    show the feature structure corresponding to the edge where
                      the point is in an other frame. If you are running under X
                      this will create a new frame, otherwise it will display the
                      feature structure in the current frame.
             - 'E'    Same as above, but displays the feature structure in the 
                      current frame
             - 'd'    show the derivation of the edge where the point is in an 
                      other frame (under X)
             - 'D'    show the derivation of the edge where the point is in the
                      current frame
             - 'b'    shows the buffers list
             - '<' and '>'  use these keys to scroll horizontally in case the 
                      diagrams are wider than the window.
             - 'q'    quit this buffer and go back to the previous one


SIGNATURE

This buffers shows a 'graphic' representation of the signature. 
Here is a simple illustration:

   The signature is:

         bot sub [a, b, d, e].
         a sub [b, c] intro [f1: e].
         b sub [] intro [f2: d].
         c sub [].
         d sub [].
         e sub [].

   The graphic representation is:

	 bot .....
			 :a .....
			 :       :b 
			 :       :c 
			 :b 
			 :d 
			 :e 

The commands available in the signature buffer are:

     - 'h' hide the type where the point is. When a type is 'hidden',
       it is shown enclosed between square brackets and none
       of its subtypes are shown, ie the branch is pruned. In the 
       example below, the type 'a' is hidden:

		   bot ....
			   :[a]
			   :b
			   :d 
			   :e 

     - 'r' restore a hidden type, ie show the subtypes
     - 't' shows information about the type where the point is.
       Here is what you get if you type 't' after you moved the point on
       the type 'b' (refer to ALE's user's manual for an explanation):

			TYPE: b
			SUBTYPES: []
						SUPERTYPES: [bot]
						IMMEDIATE CONSTRAINT: none
			MOST GENERAL SATISFIER:
			b 
			F1 e 
			F2 d 

       When the signature buffer is displaying an MGSAT, use the following 
       commands:

                - 'q' to return to ale-interaction
                - 'f' to display the signature again
                - 't' to display yet again type information (of the type 
                  where the point is)

     - 'q' quit the signature buffer and kills the frame (if under X)


Emacs Variables
---------------
The following variables are defined. They can be set in the .emacs file
by a line like 
				(setq var-name value)

or interactively from within emacs (M-x set-variable). They are described
in Emacs by M-x describe-variable.

Variable Name                  type of the value	default value
-------------                  -----------------    -------------
ale-command                        string               "ale"
ale-startup-file                   string/nil			nil
ale-grammar-directory              string               "~/"
ale-grammar-name                   string               ""
ale-show-derivation-on-parse       boolean              nil
ale-pp-on-parse                    boolean              nil


Description of the variables: 

ale-command: the name of the executable to lauch to run ALE 
             (a sicstus saved state usually)

ale-startup-file: the name of a file to consult into prolog 
                  upon startup

ale-grammar-name: the name of the file containing the ALE grammar

ale-grammar-directory: the directory where the grammar lives 
                       (the path must end with a '/')

ale-show-derivation-on-parse: if non-nil, the derivation tree(s) 
                      will be displayed on completion of the parse.

ale-pp-on-parse: if non-nil, the feature structure(s) of the edge(s) 
                      spanning the entire sentence will be displayed 
                      on completion of the parse


Warning
-------

I don't provide support nor user assistance. However, I'll be glad to
hear about bugs you may find and suggestions you may have. I can't
promise I will fix/implement them, but, if time permits, I may do so
and release new versions later.  

If anyone wants to modify either the elisp code in ale.el or the
prolog code in emacs.pl, they may do so. If you feel your changes may
be useful to others, send them to me so that I can integrate them in
the next release when it comes.


------------------------------------------------------------------------
Copyright (C) 1995 Olivier Laurens  <laurens@cs.sfu.ca>
All rights reserved