  SCCS: @(#)README	73.2 9/21/94
  README: Quintus Prolog Gnu Emacs interface documentation

  This interface works best with XEmacs ( http://www.xemacs.org/ ), but
  has been observed to work on emacs 18.55 & fsf emacs 19.X

  Load qp.el as the primary interface to this package.

  Put in your .emacs file

    (setq load-path (append ("pathname") load-path))
    (load-library "qp")

  where "pathname" is wherever this set of emacs lisp files is
  installed.

  It is recommended that you read qp.el to get an idea of what is going
  on.

  The help system has interesting properties with XEmacs. The help
  "text" buffers behave like XEmac's "man" pages -- that is, cross
  references are mouse-able, written in italics, and are highlighted
  when the mouse is over them. The middle mouse button will follow cross
  references or call help on the word the mouse is over. This makes it
  behave very much like the qui help system. The help "menu" buffers
  behave like "dired", that is, each entry is highlighted when the mouse
  is over it and the middle button (button2) will take you to that
  reference.
  
  A "prolog-mode-hook" and a "comint-prolog-hook" is provided. These
  hooks are called whenever a buffer is opened in prolog-mode and
  whenever a prolog process is started, respectively.

  The interface can be invoked in two ways; 1) From the shell command
  line by typing "prolog +" (not recommended) or 2) From within GNU
  Emacs by typing the command M-x run-prolog.

  The shell command "prolog +" has some bugs. User beware.

  The environment variable QUINTUS_PROLOG_PATH should be initialized
  to the full pathname of the Quintus prolog executable.

  Once you have told Gnu Emacs where to look for the lisp files, you
  need to load them. This for convenience can also be placed in the
  ~/.emacs initialization file,

  In the example the directory "/opt/quintus/editor/gnu3.2" is where
  the Quintus Prolog - GNU Emacs lisp files are and
  "/opt/gnu/emacs/lisp" contains the standard GNU Emacs lisp files.  

  BEWARE!!!!! The existing GNU Emacs lisp directories (standard
  distribution) contains a file "prolog.el" which defines a version of
  the Prolog interface. In order to avoid any clash, place the Quintus
  Prolog - GNU Emacs interface library pathname before all others in the
  load-path. Note that no clash can occur if the autoload function
  described above is used.

  From within Gnu Emacs to achieve the same result use the command
  "M-x load-file" qprolog-mode.el. At this stage all the emacs lisp code
  necessary for the interface has been loaded.

  To run prolog you may then type "M-x run-prolog", which causes the
  current buffer to display the Quintus Prolog logo and the prolog
  prompt.

  KEY BINDINGS
  ------------
  Within the prolog buffer (called *prolog*) a certain set of key
  bindings are in effect. They are:

                 "\t"          prolog-indent-command
                 "ESC  \C-f"   forward-term
                 "ESC  \C-b"   backward-term
                 "ESC  d"      kill-prolog-word
                 "ESC   DEL"   backward-kill-prolog-word
                 "ESC  ."      find-definition
                 "ESC  ,"      find-more-definition
                 "\C-c\C-c"    interrupt-prolog

  But the most useful commands are inherited from the "comint"
  package. In particular "ESC p" for finding previous commands. Once in
  the "*prolog*" buffer, hit "C-h m" for a full description of the key
  bindings.

  find-definition works with tags. So M-* runs pop-tag-mark, which is
  very useful for jumping around in source files.

  In the prolog buffer the command "ESC-x cd" changes the directory of
  both the buffer and the prolog process. Equivalently, a unix(cd(+Path)),
  changes both default directories as well.

  Within a buffer in prolog-mode, the following key bindings are
  available:

                 "ESC  \C-a"   beginning-of-clause
		 "ESC  \C-e"   end-of-clause
                 "ESC  \C-k"   kill-clause
                 "ESC  h"      mark-clause	   
                 "ESC  f"      forward-prolog-word
	         "ESC  b"      backward-prolog-word
                 "ESC  k"      prolog-compile
                 "ESC  i"      prolog-compile (for backward compatibility)  
		 "ESC  d"      kill-prolog-word
                 "ESC  DEL"    backward-kill-prolog-word
                 "ESC  ."      find-definition
                 "ESC  ,"      find-more-definition
		 "ESC C-b"     backward-term
		 "ESC C-f"     forward-term
		 "ESC C-q"     prolog-indent-clause
		 "\t"          prolog-indent-line

  INDENTATION
  ----------- 
  In prolog-mode the TAB and Linefeed keys provide a method of
  indenting user prolog code according to a few rules. There are two
  variables which control indentation in prolog mode. They are:

  1) body-predicate-indent: Default value 3. The column at which the
     body of a predicate is to begin. 
  
  2) if-then-else-indent: Default value 3. Offset within an
     if-then-else statement. This offset is measured beginning at the
     column of the first term in the condition. All subsequent lines
     are indented according to the previous line. ';' and '|' are
     indented according to the column of the corresponding '('. Nested
     if-then-else constructs are handled in the same way. Note that
     this variable refers to the offset for clauses in the "then" part
     alone. Within the "else" part indentation depends on the
     indentation of the previous line. 


  QUI-EMACS INTERFACE
  -------------------
  
  This allows users to invoke Gnu Emacs from QUI (Quintus User
  Interface) and from the debugger. The interface when invoked from
  the QUI main window comes up with a scratch buffer - "*qui-emacs*"
  in qui-mode. When invoked from the debugger the file containing the
  predicate you are currently debugging is displayed and the scratch
  buffer "*qui-emacs*" is hidden. Qui-mode is equivalent to
  prolog-mode in the regular Prolog/Emacs interface. This is the mode
  that all files with ".pl" extension are placed in when first edited.
  The only key bindings which have been disabled are the ones which
  allow for manipulating queries sent to Prolog. This function is
  handled by the QUI main window. The files that define this interface
  are qui.el, qui_filter.el, qui_cmds.el and qui_aux.el.  Please refer
  to the QUI manual for further details about this interface and on
  how to invoke it.
