home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-387-Vol-3of3.iso / p / plbin.zip / pl / lisp / README < prev    next >
Lisp/Scheme  |  1992-05-26  |  10KB  |  221 lines
  1.   SCCS: @(#)README    2.8 2/7/91
  2.   SCCS: @(#)89/12/11 README    2.4
  3.   README: Quintus Prolog Gnu Emacs interface documentation
  4.   Date  : 1/8/91
  5.  
  6.   The following is a brief introduction to the Quintus Prolog Gnu Emacs
  7.   interface. Refer to the Quintus Prolog manual for further details.
  8.  
  9.   This directory contains the files: 
  10.      qpaux.el, qpcommands.el, qpfile-compl.el, qprolog.el, qptokens.el,
  11.      qpshell-command-ring.el, qprocess.el, qprolog-mode.el, qpfindpred.el,
  12.      qphelp-functions.el, qphelp.el, qprolog-indent.el, qpdelete.el, 
  13.      quintaux.el, qpstart.el qui.el, qui_filter.el, qui_cmds.el,
  14.      qui_aux.el and README. 
  15.  
  16.   The interface can be invoked in two ways; 1) From the shell command
  17.   line by typing "prolog +" or 2) From within GNU Emacs by typing the
  18.   command M-x run-prolog. For invoking the interface from the shell
  19.   command line refer to the Quintus Prolog manual. If the latter
  20.   method of firing up the interface is to be used, you must specify
  21.   the directory in which the Quintus Prolog - GNU emacs interface
  22.   files are stored. To do so, add this directory to your load-path,
  23.   which is a list of directories that GNU Emacs searches to load lisp
  24.   files. This can be best achieved by placing the following in your
  25.   ~/.emacs file:
  26.   
  27.               (setq load-path ("pathname"
  28.                        "lispdir1"
  29.                        ...))
  30.   
  31.   where "pathname" is the directory in which Quintus Prolog - Gnu Emacs
  32.   interface lisp files are stored, lispdir1 is the pathname where the
  33.   lisp code for emacs itself is stored. Note that the inverted commas
  34.   are needed, pathnames being strings.
  35.  
  36.   The environment variable QUINTUS_PROLOG_PATH should be initialized
  37.   to the full pathname of the Quintus prolog executable.
  38.  
  39.   Once you have told Gnu Emacs where to look for the lisp files, you
  40.   need to load them. This for convenience can also be placed in the
  41.   ~/.emacs initialization file,
  42.  
  43.   (autoload 'run-prolog "qprolog-mode" "Run an inferior prolog process"
  44.   t) 
  45.  
  46.   This causes the required lisp files to be autoloaded only when you
  47.   desire to run a prolog session.
  48.  
  49.   Here is an example of how ~/.emacs can be set up:
  50.   ;---------------------------------------------------------------------
  51.   ;; load-path for all functions
  52.     (setq load-path '("/ports/emacs/GNU/el3.1/"
  53.               "/hughes/gnu/local-lisp"))
  54.   ;; autoload gnu-prolog interface library
  55.     (autoload 'run-prolog "prolog-mode" 
  56.           "Run an inferior prolog process" t)
  57.   ;---------------------------------------------------------------------
  58.  
  59.   In the example the directory "/ports/emacs/GNU/el3.1/" is where the
  60.   Quintus Prolog - GNU Emacs lisp files are and
  61.   "/hughes/gnu/local-lisp" contains the standard GNU Emacs lisp files.  
  62.  
  63.   The existing GNU Emacs lisp directories (standard distribution)
  64.   contains a file "prolog.el" which defines a version of the Prolog
  65.   interface. In order to avoid any clash, place the Quintus Prolog -
  66.   GNU Emacs interface library pathname before all others in the
  67.   load-path. Note that no clash can occur if the autoload function
  68.   described above is used.
  69.  
  70.   From within Gnu Emacs to achieve the same result use the command
  71.   "M-x load-file" qprolog-mode.el. At this stage all the emacs lisp code
  72.   necessary for the interface has been loaded.
  73.  
  74.   To run prolog you may then type "M-x run-prolog", which causes the
  75.   current buffer to display the Quintus Prolog logo and the prolog
  76.   prompt.
  77.  
  78.   KEY BINDINGS
  79.   ------------
  80.   Within the prolog buffer (called *prolog*) a certain set of key
  81.   bindings are in effect. They are:
  82.  
  83.                  "\t"          prolog-indent-command
  84.                  "ESC  \C-f"   forward-term
  85.                  "ESC  \C-b"   backward-term
  86.                  "ESC  d"      kill-prolog-word
  87.                  "ESC   DEL"   backward-kill-prolog-word
  88.                  "ESC  ."      find-definition
  89.                  "ESC  ,"      find-more-definition
  90.                  "\C-c\C-c"    interrupt-prolog
  91.                  "\C-x\C-e"    goal-history
  92.                  "\C-x\C-y"    repeat-matching-goal-command
  93.          "ESC #"       shell-filename-complete
  94.   (\C-u # or ESC # provides a numeric argument # to \C-x\C-e) 
  95.  
  96.   In the prolog buffer the command "ESC-x cd" changes the directory of
  97.   both the buffer and the prolog process. Equivalently, a unix(cd(+Path)),
  98.   changes both default directories as well.
  99.  
  100.   GOAL HISTORY
  101.   ------------ 
  102.   The "\C-x\C-e" command requires a little more explanation. There are
  103.   two possibilities:
  104.     a) Typing the command at the current prolog prompt,
  105.        causes the last query typed to be displayed in the
  106.        minibuffer. This query can be modified using the usual
  107.        editing keys, or one can go to the previous item in the
  108.        goal-history by typing "ESC-p". Actually within the
  109.        minibuffer the following key bindings exist, in addition to
  110.        the usual ones:
  111.         ESC-p       previous item in goal-history
  112.         ESC-n       next item in goal-history
  113.             LFD,RET    Select query displayed in the minibuffer.
  114.     
  115.      b) If the cursor (point) is at any position above the current
  116.        end-of-buffer, the last valid query, searching backwards from
  117.        "point" is selected, and a copy placed at the prolog prompt. 
  118.        
  119.   In either case the selected query is placed at the prolog prompt, and
  120.   is executed by prolog only when a RET is hit again. Therefore, the
  121.   query can be edited even after being placed at the prolog prompt. The
  122.   query just executed is then added to the goal-history.
  123.  
  124.   Multiline queries are displayed in the minibuffer one line at a time,
  125.   and one can display the next or the previous line of such a query with
  126.   the usual C-n or C-p key sequence.
  127.  
  128.   The command "\C-x\C-y" provides a mechanism whereby a goal matching
  129.   a regular expression can be retrieved from the prolog-goal-history.
  130.   When you type in the said key-sequence, you are first prompted for a
  131.   regular expression; the most recent query matching this regular
  132.   expression is displayed in the minibuffer. If you type "y" then you
  133.   can either edit the query or simply type return to place it in the
  134.   prolog buffer. If you respond with "n" the next query which matches
  135.   the regular expression (if any) is displayed. 
  136.  
  137.   Within a buffer in prolog-mode, the following key bindings are
  138.   available:
  139.  
  140.                  "ESC  \C-a"   beginning-of-clause
  141.          "ESC  \C-e"   end-of-clause
  142.                  "ESC  \C-k"   kill-clause
  143.                  "ESC  h"      mark-clause       
  144.                  "ESC  f"      forward-prolog-word
  145.              "ESC  b"      backward-prolog-word
  146.                  "ESC  k"      prolog-compile
  147.                  "ESC  i"      prolog-compile (for backward compatibility)  
  148.          "ESC  d"      kill-prolog-word
  149.                  "ESC  DEL"    backward-kill-prolog-word
  150.                  "ESC  ."      find-definition
  151.                  "ESC  ,"      find-more-definition
  152.          "ESC C-b"     backward-term
  153.          "ESC C-f"     forward-term
  154.          "ESC C-q"     prolog-indent-clause
  155.          "\t"          prolog-indent-line
  156.          "ESC #"       shell-filename-complete
  157.  
  158.   This mode is automatically entered when a prolog file is visited (with
  159.   a filename extension of .pl) 
  160.  
  161.   FILENAME COMPLETION
  162.   -------------------
  163.   Within either the prolog buffer or any buffer in prolog-mode, the key
  164.   sequence "ESC #" provides filename completion. For example when typing
  165.   in the query unix(cd(+Path)), "ESC #" can be used to provide filename
  166.   completion for "Path".
  167.  
  168.   In a nutshell, the following steps should be followed to install the
  169.   interface:
  170.  
  171.   1) Create or update your ~/.emacs file as described above.
  172.      Specifically, add the directory where the emacs lisp files are
  173.      located to the load-path variable. Note that you don't have to do
  174.      this if you plan to invoke the Quintus Prolog - GNU Emacs
  175.      interface from the command line.
  176.  
  177.   2) Set the environment variable QUINTUS_PROLOG_PATH to the full
  178.      pathname desired prolog executable. 
  179.  
  180.  
  181.   INDENTATION
  182.   ----------- 
  183.   In prolog-mode the TAB and Linefeed keys provide a method of
  184.   indenting user prolog code according to a few rules. There are two
  185.   variables which control indentation in prolog mode. They are:
  186.  
  187.   1) body-predicate-indent: Default value 8. The column at which the
  188.      body of a predicate is to begin. 
  189.   
  190.   2) if-then-else-indent: Default value 4. Offset within an
  191.      if-then-else statement. This offset is measured beginning at the
  192.      column of the first term in the condition. All subsequent lines
  193.      are indented according to the previous line. ';' and '|' are
  194.      indented according to the column of the corresponding '('. Nested
  195.      if-then-else constructs are handled in the same way. Note that
  196.      this variable refers to the offset for clauses in the "then" part
  197.      alone. Within the "else" part indentation depends on the
  198.      indentation of the previous line. 
  199.  
  200.  
  201.   QUI-EMACS INTERFACE
  202.   -------------------
  203.   
  204.   For Quintus Prolog 3.1 a QUI Gnu Emacs interface has been added.
  205.   This allows users to invoke Gnu Emacs from QUI (Quintus User
  206.   Interface) and from the debugger. The interface when invoked from
  207.   the QUI main window comes up with a scratch buffer - "*qui-emacs*"
  208.   in qui-mode. When invoked from the debugger the file containing the
  209.   predicate you are currently debugging is displayed and the scratch
  210.   buffer "*qui-emacs*" is hidden. Qui-mode is equivalent to
  211.   prolog-mode in the regular Prolog/Emacs interface. This is the mode
  212.   that all files with ".pl" extension are placed in when first edited.
  213.   The only key bindings which have been disabled are the ones which
  214.   allow for manipulating queries sent to Prolog. This function is
  215.   handled by the QUI main window. The files that define this interface
  216.   are qui.el, qui_filter.el, qui_cmds.el and qui_aux.el.  Please refer
  217.   to the QUI manual for further details about this interface and on
  218.   how to invoke it.
  219.  
  220.  
  221.