This file refers to pari.el version 2.19

               Some Notes on pari-mode
               =======================

pari-mode runs pari-gp as a sub process of (gnu-)emacs.

INSTALATION.
===========

pari-mode consists of three files: pariemacs.txt (this file, for information
only), pari.el and pari.menu. When GP is installed, those three files are
placed in a convenient directory (/usr/local/lib/pari by default) and pari.el
is byte-compiled, producing a file pari.elc. (If this directory is not in
your EMACSLOADPATH, read a full path and not only "pari" in the line below.)

To use pari-mode, users should add the following line to their .emacs:

(load "pari" nil t)

Some specific highlighting is then enabled when editing *.gp files
(gp-scripts) and three new commands are made available:

M-x gp      starts up the pari-gp process in a new buffer,  *PARI*.
C-u M-x gp  same as M-x gp, but prompts for the command line arguments.
M-x gpman   starts up a dvi previewer with the PARI-GP manual. 

To use gpman, you must copy (or link) the file doc/users.dvi (from the
standard distribution) to the directory pari.el was installed in.
===========================================================================

GP-MODE
=======

Inside the buffer *PARI*, the following extra commands are available.

KEY      LISP-NAME             DESCRIPTION
===      =========             ===========
RET      gp-send-input         Copy current expression to the end,
                                  and send to gp.
M-RET    gp-copy-input         Copy current expression to the end.
TAB      gp-complete           Complete the partly typed gp input line
M-?      gp-get-man-entry      Display the manual entry for a gp command.
M-\ p    gp-set-prompt         Set the gp prompt.
M-\ c    gp-help-menu          Menu driven help. (Uses the file pari.menu.)
M-\ t    gp-meta-t       \
M-\ d    gp-meta-d        |                                 
M-\ r    gp-meta-r        |        
M-\ w    gp-meta-w        |    
M-\ v    gp-meta-v        |   
M-\ x    gp-meta-x         \  Versions of the gp meta-commands, which    
M-\ s    gp-meta-s         /  prompt for arguments in the mini-buffer  
M-\ a    gp-meta-a        |   and display output in the help buffer.     
M-\ b    gp-meta-b        |        
M-\ m    gp-meta-m        |        
M-\ k    gp-meta-k        |       
M-\ q    gp-meta-q       /        
M-\ \    gp-break-long-line    Break a long line at col. 100, inserting \.

Note that most of these commands use the emacs meta key.
This may be marked `left' `right' `extended character'  `<>'
or various other markings. If your keyboard has not got a meta key. You
can use the escape key as a prefix.

Thus M-\ corresponds to pressing meta and \ together, or pressing 
ESC followed by \ .
===========================================================================

RET
===
If point is after the last gp prompt,  pressing RET sends current gp
expression to the gp process. If point is at some previous expression, this
expression (which may be several lines long) is copied to the end of the
buffer and then executed.

M-RET
=====
M-RET, acts like RET, except that the expression is not sent to the gp
process. It is just copied to the end, so that it may be edited, and then
RET pressed, to send the new expression to gp.

TAB
=====
TAB Tries to complete the partly typed gp command in the *PARI* buffer.
If GP was compiled with the readline library, it knows about all symbols
meaningful tp GP, plus some extra keywords (bnf, nf, ell, etc.)

Otherwise, it originally `knows' about the commands listed in pari.menu.
user-defined commands will be known to the completion system if they are
given as arguments to M-?. Commands to teach the system large numbers of new
command names will be described later on.

M-?
===
M-? prompts for the name of a gp command (which may include symbolic names
like +). It then finds the appropriate paragraphs of section 3 of the
manual, strips off some of the TeX commands, and displays the result in a
new window. If the command is not found in the manual, sends ?command to
gp, and displays the output in the help window. Thus M-? also works with
user-defined commands. You may use space and tab to complete the
command name, in the mini-buffer. M-? tries to guess which command you
may want help for. If this is incorrect, simply delete that command,
and type in the command required.

M-\ p
=====
M-\ p prompts for a new string in the mini-buffer. The command

default(prompt,"<new string>")

is then sent to gp, so that gp will now prompt for input with <new string>.
The variable gp-prompt-pattern is also reset so that RET and M-RET know
that gp expressions now start with <new string>. Expressions typed to the
old prompt are still recognised. 

  Note that if you want to use a dynamic prompt (using % constructs, which
then go through strftime), you have to set the prompt regexp pattern in your
.emacs, you can't do it with this function (more about this later).

M-\ c
=====
This shows a menu of subject headings. Pressing RET selects the menu of
commands for that heading. Pressing RET by one of the commands displays the
manual entry for that command, as if M-? command had been typed.
Since most of the TeX syntax is not stripped, the output does not look nice
(you really should use ?? or gphelp if it is available on your installation),
but should be legible. (Instructions are displayed in the mini-buffer.)

M-\ \
=====
If the line is longer than 100, a \<newline> is inserted every 100
characters. This is necessary if the line is longer than 256 characters as gp
does not accept line longer than this. M-\ \ moves point to the end of the
current line.

M-\ 
===
The other comands on the M-\ prefix send the appropriate meta command to
gp. However they use the mini-buffer to read arguments (eg so that you can
use filename completion) and display any output in the *gp-help* buffer.

===========================================================================

Notes
=====

1) You may edit previous expressions, and then type RET to send them to gp.
   However if you want the *PARI* buffer to contain a script of a valid gp
   session, you may prefer to use M-RET to copy the expression to the end
   of the buffer, before editing it.

2) M-\ c is supposed to be a version of the gp meta comand \c, although
   it does not send \c to gp.
   M-\ p does not correspond to the gp meta command \p but rather to the
   command default(prompt,...). If this disturbs you it is easy enough to bind
   M-\ p to a command that inserts \p into the *PARI* buffer. The command
   gp-set-prompt can then be bound to any key sequence that you wish. 
   All the other commands on the M-\ prefix do work by sending a gp meta
   command to the *PARI* buffer.

3) gp-mode-hook.
   Individual users can customise gp-mode without having to make copies of
   the file pari.el.
   In your .emacs define a gp-mode-hook, this will be run by the gp command.
   The format is:

       (setq gp-mode-hook 
         (function (lambda ()
          ... commands to run when starting up gp ...
        )))

   An example is:

       (setq gp-mode-hook 
         (function (lambda ()
           (define-key gp-map "\M-\\p" 'gp-meta-p)
           (define-key gp-map "\M-p" 'gp-set-prompt)
           (setq gp-stack-size "1000000")
           (setq gp-prime-limit "2000")
           (setq gp-menu "my-menu")
           (gp-completion-file my-file)
       )))

  This: 
        Binds a function which sends \p to gp (which would need to be defined
             somewhere else), to M-\ p.
        Binds gp-set-prompt to M-p.
        Defines the default stack size and prime limit as 10000 and 2000.
        Defines the menu file to be my-menu rather than the file pari.menu.

        Let the completion system use all the commands listed in the
        file my-file (this last one is useless if GP was built with readline)

4) Command line arguments.
   The gp executable file is specified in the variable gp-file-name. This
   is set in the file pari.el, but users can override this setting, either
   in their gp-mode-hook, or by using the C-u prefix to gp. In either case,
   the full path name need not be given if gp is in a directory specified
   in your PATH variable (or the equivalent in csh).
   The variables gp-stack-size, gp-buffer-size and gp-prime-limit should be
   set to strings specifying the arguments to gp. See the above example.


   If these variables are  set to "", then the appropriate flags 
      "-s", "-b" or "-p" are *not* sent to gp. 
   If RET is typed in response to any of the prompts produced by C-u M-x gp
      then the default value, ie., the value of gp-file-name, gp-stack-size,
       gp-buffer-size or gp-prime-limit, is assumed. 
   If a space is sent to the prompt (ie SPC RET) then the appropriate argument
       is not  sent to gp, even if the default is non-empty.

   People who often use different settings for these arguments, may like to
   add the line

   (setq gp-prompt-for-args t)
   to their gp-mode-hook. This makes M-x gp act like C-u M-x gp.

5) Prompt.
   Emacs needs to know at all time what your prompt looks like: it's stored
   at all times in gp-prompt-pattern, and you must never change your prompt
   (e.g. with default(prompt,...) without telling emacs about it. This is the
   purpose of the M-\ p command. 

   Since GP-2.0, users can set a self-modifying prompt (patterns of the form
   %c are expanded, where c is any character). Thus there's no easy way to
   know automatically what the prompt will look like and pari-mode does not
   attempt to guess it: it always assume you use the default prompt "? ".
   Thus if you intend to change your prompt in your .gprc, you have to modify
   the gp-prompt-pattern regular expression yourself (AFTER loading pari.el
   in your .emacs). For instance:

   (setq gp-prompt-pattern
     (concat "^> [\C-j\t ]*\\|" gp-prompt-pattern))

   caters for a 'prompt = "> "' in .gprc. Don't forget to anchor your prompt
   at the beginning of the line (the '^' at the beggining). And don't forget
   to concatenate the old prompt pattern as well. A more complicated one to
   deal with 'prompt = "(%R) gp > "':

   (setq gp-prompt-pattern
     (concat
       "^([0-9][0-9]:[0-9][0-9]) gp > [\C-j\t ]*\\|" gp-prompt-pattern))

6) Syntax highlighting.
   If you're using X Windows on a color monitor, Emacs will use different
   colors to display various parts of the *PARI* buffer (where GP is
   running), or in gp-script mode (while editing a file with suffix .gp or 
   after typing M-x gp-script-mode).

   NOTE: in order to set the colours, emacs has to be in charge from the
   moment you send a command until GP outputs an answer. Thus it will appear
   to hang if you input a command which takes a long time for GP to process.
   You can hit C-g at any time, which will not affect GP (like C-c would),
   but will let you back in control of emacs. The output of this specific
   command will then not be highlighted, but it will be so as soon as GP
   answers the next one, so you can highlight it by typing 0 RET for instance.

   You can customize this in the following way (in your .emacs, AFTER "pari"
   has been loaded): 

   to disable all highlighting.
     (setq gp-no-hilit t)

   if you run emacs with a dark background (e.g. in reverse video mode)
     (setq hilit-background-mode 'dark)

   The default colors should not be too painful to look at. In any case they
   are easily configurable using the function hilit-translate. Emacs knows
   about the following symbolic hilight groups:

    in gp-mode (corresponding to what default(colors,...) would do):  
      gp-error   gp-history   gp-prompt   gp-output  
      gp-input   gp-timer     gp-help

    in gp-script-mode:
      gp-control-statement   gp-default-keywords   gp-default-set
      gp-input-cmd           gp-string             gp-function-proto
      gp-function-args       gp-comment

    An actual face (font shape + color) is associated to all patterns belong
    to a group using hilit-translate. For instance

      (hilit-translate
         gp-string   'magenta3    ; all strings will be set in magenta3
         gp-comment  'italic-red  ; all comments in italic + red
         gp-timer    'hex-ffff60  ; timer output set in RGB color (ff ff 60)
         gp-prompt   nil          ; don't highlight the prompt
      )
    See the documentation of hilit-lookup-face-create for valid face names.

    In practice, you could include the following code in your .emacs:

      (setq gp-mode-hook
        (function (lambda ()
           ... ; as above for instance
          (if gp-can-hilit
            (progn
              (hilit-translate gp-prompt 'tomato4)
              (hilit-translate gp-timer  nil))))))
      (setq gp-script-mode-hook
        (function (lambda ()
          (if gp-can-hilit
            (progn
              (hilit-translate gp-string  'tomato4)
              (hilit-translate gp-comment nil))))))

===========================================================================

  Karim Belabas. 
  Modified from the original file pari.txt written by David Carlisle

        13-January-1998  (This file refers to pari.el version 2.19)
