path: root/doc/NewDoc.texi

\input texinfo   @c -*-texinfo-*-
@c
@c $Id$
@c
@c %**start of header
@setfilename ProofGeneral.info
@settitle Proof General
@setchapternewpage odd
@paragraphindent 0
@iftex
@afourpaper
@end iftex
@c %**end of header

@c 
@c TODO, priority order
@c   . finish incomplete sections
@c   . polish mark-up
@c   . add more index entries
@c   . screenshots might be nice
@c   


@set version 2.0
@set xemacsversion 20.4
@set fsfversion 20.2
@set last-update November 1998

@ifinfo
@format
START-INFO-DIR-ENTRY
* ProofGeneral::Organize your proofs with Emacs!
END-INFO-DIR-ENTRY
@end format
@end ifinfo


@c merge functions and variables into concept index.
@syncodeindex fn cp
@syncodeindex vr cp

@finalout
@titlepage
@title Proof General
@subtitle Organise your proofs with Emacs!
@subtitle Proof General @value{version}
@subtitle @value{last-update}
@iftex
@image{ProofGeneral}
@end iftex
@author D. Aspinall, H. Goguen, T. Kleymann and D. Sequeira
@page
@vskip 0pt plus 1filll
This manual and the program Proof General are
Copyright @copyright{} 1998 Proof General team, LFCS Edinburgh.


@c
@c COPYING NOTICE
@c
@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission notice
identical to this one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).
@end ignore

@sp 2
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.  
@sp 2

This manual documents Proof General, Version @value{version}, for use
with XEmacs @value{xemacsversion} and FSF GNU Emacs @value{fsfversion}
or later versions.
@end titlepage

@page


@ifinfo
@node Top
@top Proof General

This file documents version @value{version} of @b{Proof General}, a
generic Emacs interface for proof assistants.

Proof General @value{version} has been tested with XEmacs
@value{xemacsversion} and FSF GNU Emacs @value{fsfversion}.  It is
supplied ready customized for the proof assistants Coq, Lego, and
Isabelle.

@menu
* Introducing Proof General::   
* Basic Script Management::     
* Advanced Script Management::  
* Support for other Packages::  
* Customizing Proof General::   
* LEGO Proof General::          
* Coq Proof General::           
* Isabelle Proof General::      
* Adapting Proof General to New Provers::  
* Internals of Proof General::  
* Credits and References::      
* Obtaining and Installing Proof General::  
* Known bugs and workarounds::  
* Plans and ideas::             
* Keystroke Index::             
* Index::                       
@end menu

@detailmenu --- The Detailed Node Listing ---

Introducing Proof General

 --- The Detailed Node Listing ---

Introducing Proof General

* Quick start guide::           
* Features of Proof General::   
* Supported proof assistants::  

Basic Script Management

* Proof scripts::               
* The buffer model::            
* Regions in a proof script::   
* Script editing commands::     
* Script processing commands::  
* Toolbar commands::            
* Other commands::              
* Walkthrough example in LEGO::  

Proof scripts

* Goals and saves::             

Advanced Script Management

* Switching between proof scripts::  
* View of processed files ::    
* Retracting across files::     
* Asserting across files::      
* Working directly with the proof shell::  

Support for other Packages

* Support for function menus::  

Customizing Proof General

* Easy customization::          
* Setting user options::        
* Running on another machine::  
* Tweaking configuration settings::  

LEGO Proof General

* LEGO specific commands::      
* LEGO customizations::         

Coq Proof General

* Coq specific commands::       
* Coq customizations::          

Isabelle Proof General

* Isabelle specific commands::  
* Isabelle customizations::     

Adapting Proof General to New Provers

* Skeleton example::            
* Proof script settings::       
* Proof shell settings::        

Proof shell settings

* Special annotations::         

Internals of Proof General

* Proof Script Mode::           
* Proof Shell Mode::            
* Handling Multiple Files::     

Credits and References

* Credits::                     
* References::                  

Obtaining and Installing Proof General

* Obtaining Proof General::     
* Installing Proof General from tarball::  
* Installing Proof General from RPM package::  
* Notes for syssies::           
@end detailmenu

@end ifinfo



@node Introducing Proof General
@chapter Introducing Proof General
@cindex{proof assistant}
@cindex{Proof General}

@c would like the logo on the title page really but
@c it doesn't seem to work there for html.
@ifhtml
<IMG SRC="ProofGeneral.jpg" ALT="[ Proof General logo ]" >
@end ifhtml

A @dfn{proof assistant} is a computerized helper for developing
mathematical proofs.

@dfn{Proof General} is a generic Emacs interface for proof assistants,
developed at the LFCS in the University of Edinburgh.  It works best
under XEmacs, but can also be used with FSF GNU Emacs.

You do not have to be an Emacs militant to use Proof General!  @*

The interface is designed to be very easy to use.  You develop your
proof script in-place rather than line-by-line and later reassembling
the pieces.  Proof General keeps track of which proof steps have been
processed by the prover, and prevents you editing them accidently.  You
can undo steps as usual.

Our aim is provide a powerful and configurable Emacs mode which helps
user-interaction with interactive proof assistants.  Please help us with
this aim!  Configure Proof General for your proof assistant, by adding
features at the generic level wherever possible.  See 
@ref{Adapting Proof General to New Provers}
for more details, and send ideas, comments, patches,
and code to @code{proofgen@@dcs.ed.ac.uk}.


@menu
* Quick start guide::           
* Features of Proof General::   
* Supported proof assistants::  
@end menu

@node Quick start guide
@section Quick start guide

Proof General may have been installed for you already. If so, when you
visit a proof script file for your proof assistant, you'll find commands
to process the proof script are available from the toolbar, menus, and
keyboard.  Type @kbd{C-h m} to get a list of keys for the current mode.

The proof assistant is automatically started inside Emacs when you ask
for some of the proof script to be processed.  To follow an example use
of Proof General on a LEGO proof, see @pxref{Walkthrough example in LEGO}.

If Proof General has not already been installed, you should insert the
line:
@lisp
        (load "@var{ProofGeneral}/generic/proof-site.el")
@end lisp
into your @file{~/.emacs} file, where @var{ProofGeneral} is the
top-level directory that was created when Proof General was unpacked.

For more details on obtaining and installing Proof General,
see @pxref{Obtaining and Installing Proof General}.


@node Features of Proof General
@section Features of Proof General
@cindex{Features}
@cindex{Why use Proof General?}

Why would you want to use Proof General?

Here is an outline of its main features.

@itemize @bullet
@item @i{Simplified communication}@*
The proof assistant's shell is normally hidden from the user.
Communication takes place via two or three buffers.  The @dfn{script
buffer} holds input, the commands to construct a proof.  The @dfn{goals
buffer} displays the current list of subgoals to be solved.  The
@dfn{response buffer} displays other output from the proof assistants.
This means that the user only sees the output from the most recent proof
step, rather than a screen full of output from the proof assistant.
@c Optionally, the goals buffer and script buffer can be identified.

For more details, see @pxref{The buffer model}.
@item @i{Script management}@*
Proof General colours proof script regions blue when they have already
been processed by the prover, and colours regions red when the prover is
currently processing them.  The appearance of Emacs buffers always
matches the proof assistant's state.

For more details, see @pxref{Basic Script Management}
and @pxref{Advanced Script Management}.
@item @i{Script editing mode}@*
Proof General provides useful facilities for editing proof scripts,
including syntax hilighting and a menu to jump to particular goals.
Special editing functions send lines of proof script to the proof
assistant, or undo previous proof steps.

For more details, see @pxref{Script editing commands}
and @pxref{Script processing commands}.
@item @i{Toolbar and menus}@*
A script buffer has a toolbar with navigation buttons for processing
parts of the proof script.  A menu provides further functions for
operations in the proof assistant, as well as customization of Proof
General.

For more details, see @pxref{Toolbar commands}, @pxref{Other commands},
and @pxref{Customizing Proof General}.

@c not yet
@c @item @i{Proof by pointing}
@end itemize


@node Supported proof assistants
@section Supported proof assistants

Proof General comes ready-customised for these proof assistants:

@itemize @bullet
@item 
@b{LEGO Proof General} for LEGO Version 1.3.1@*
@c written by Thomas Kleymann and Dilip Sequeira.
@c
All features of Proof General are supported.  
See @pxref{LEGO Proof General} for more details.

@item 
@b{Coq Proof General} for Coq Version 6.2@*
@c written by Healfdene Goguen.
@c
All of features of Proof General are supported except multiple files.
See @pxref{Coq Proof General} for more details.

@item 
@b{Isabelle Proof General} for Isabelle 98-1@*
@c written by David Aspinall.
All features of Proof General are supported, except for an external tags
program.  Isabelle Proof General handles theory files as well as ML
(proof script files), and has an extensive theory file editing mode
taken from @uref{http://www.dcs.ed.ac.uk/home/da/Isamode,Isamode}.
See @pxref{Isabelle Proof General} for more details.
@end itemize
Proof General is designed to be generic, so you can adapt it to other
proof assistants if you know a little bit of Emacs Lisp.
@itemize @bullet
@item
@b{Your Proof General} for your favourite proof assistant@*
See @pxref{Adapting Proof General to New Provers}
for more details of how to do this.
@end itemize







@c
@c CHAPTER: Basic Script Management
@c
@node Basic Script Management, Advanced Script Management, Introducing Proof General, Top
@chapter Basic Script Management

@menu
* Proof scripts::               
* The buffer model::            
* Regions in a proof script::   
* Script editing commands::     
* Script processing commands::  
* Toolbar commands::            
* Other commands::              
* Walkthrough example in LEGO::  
@end menu

@node Proof scripts, The buffer model, Basic Script Management, Basic Script Management
@section Proof scripts
@cindex proof script

A @dfn{proof script} is a sequence of commands to a proof assistant used
to construct a proof.  Proof General is designed to work with
@i{interactive} proof assistants, where the mode of working is usually a
dialogue between the user and the proof assistant.

Primitive interfaces for proof assistants simply present a shell-like
view of this dialogue: the user repeatedly types commands to the shell
until the proof is completed.  The system responds at each step, maybe
with a new list of subgoals to be solved, or maybe with a failure
report.

Often we want to keep a record of the proof commands used to prove a
theorem, in the form of a proof script kept in a file.  Then we can
@dfn{replay} the proof later on to reprove the theorem, without having
to type in all the commands again.
@c Re-playing a proof script is a non-interactive procedure,
@c since it is supposed to succeed.

Using only a primitive shell interface, it can be tedious to construct
proof scripts with cut-and-paste.  Proof General helps organize
interactive proofs by issuing commands directly from a proof script
file, while it is written and edited.
@c developing them in proof script files.

@menu
* Goals and saves::             
@end menu

@node Goals and saves,  , Proof scripts, Proof scripts
@unnumberedsubsec Goals and saves
@cindex goal
@cindex save
@cindex goal-save region

A proof script contains a sequence of commands used to prove one or more
theorems.  Proof General assumes that for each proved theorem, a proof
script contains a sequence of commands delimited by a pair of special
commands, known as @code{goal} and @code{save}.  So a proof script has a
series of proofs which look something like this (of course, the exact
syntax will depend on the proof assistant you use):
@lisp
   goal @var{mythm} is @var{G}
   @dots{}
   save theorem @var{mythm}
@end lisp
Proof General recognizes the goal-save regions in proof scripts.  The
name @var{mythm} can appear in the menu for the proof script
@pxref{Support for function menus} to help quickly find a proof, and
once a goal-save region has been processed by the proof assistant, it is
treated as atomic when undoing proof steps.


@node The buffer model, Regions in a proof script, Proof scripts, Basic Script Management
@section The buffer model
@cindex script buffer
@cindex goals buffer
@cindex response buffer


@c FIXME: fix this in the light of what gets implemented.

Proof General runs your proof assistant in a shell buffer in Emacs.
This @dfn{proof shell buffer} is usually hidden from view, 
@pxref{Working directly with the proof shell} for further details.
When Proof General sees an error in the shell buffer, it will
highlight the error and display the buffer automatically.

Communication with the proof shell takes place via two or three
intermediate buffers.

The @dfn{script buffer} holds input destined for the proof shell, in the
form of a @i{proof script}.  Normally this is a buffer visiting a file,
which can be later loaded directly by the prover to replay the proof.

The @dfn{goals buffer} displays the current list of subgoals to be
solved for a proof in progress.  This is normally displayed at
the same time as the script buffer.

The @dfn{response buffer} displays other output from the proof
assistant, for example warning or informative messages.

@c Optionally, the goals buffer and script buffer can be identified
@c @pxref{Identify goals and response}.  The disadvantage of this is that
@c the goals display can be replaced by other messages, so you must ask for
@c it to be refreshed.  The advantage is that it is simpler to deal with
@c fewer Emacs buffers.


@node Regions in a proof script
@section Regions in a proof script



@node Script editing commands
@section Script editing commands

@node Script processing commands
@section Script processing commands

@c FIXME: requires formatting
Why is C-c C-b useful?  Could just use the file to read it one go
(will we have a command to do this other than via the process?).
BUT it's nice because it stops exactly where a proof fails, so you can
continue development from there.



@node Toolbar commands
@section Toolbar commands

@node Other commands
@section Other commands

Please explain C-c C-v here.

Perhaps, don't explain C-c C-z here. Instead refer to @pxref{Working
directly with the proof shell}
@node Walkthrough example in LEGO
@section Walkthrough example in LEGO



@c
@c CHAPTER: Advanced Script Management
@c
@node Advanced Script Management
@chapter Advanced Script Management
@cindex Multiple Files

What we really mean by @emph{advanced} is that Proof General supports
large proof developments. These are typically spread across various
files which depend on each other in some way. Proof General knows enough
about the dependencies to allow script management across multiple files.


@menu
* Switching between proof scripts::  
* View of processed files ::    
* Retracting across files::     
* Asserting across files::      
* Working directly with the proof shell::  
@end menu

@node Switching between proof scripts
@section Switching between proof scripts
@cindex Switching between proof scripts

Basic modularity in large proof developments can be achieved by
splitting proof scripts across various files. Let's assume that you are
in the middle of a proof development. You are working on a soundness
proof of Hoare Logic in a file called@footnote{The suffix may depend of
the specific proof assistant you are using e.g, LEGO's proof script
files have to end with @file{.l}.} @file{HSound.l}. It
depends on a number of other files which develop underlying
concepts e.g. syntax and semantics of expressions, assertions,
imperative programs. You notice that the current lemma is too difficult
to prove because you have forgotten to prove some more basic properties
about determinism of the programming language. Or perhaps a previous
definition is too cumbersome or even wrong.

At this stage, you would like to visit the appropriate file, say
@file{sos.l} and retract to where changes are required. For further
details on how to accomplish this, we refer to @ref{Retracting across
files}. Then, using script management, you want to develop some more
basic theory in @file{sos.l}. Once this task has been completed
(possibly involving retraction across even earlier files) and the new
development has been asserted, you want to swich back to @file{HSound.l}
and replay to the point you got stuck previously.

Some hours (or days) later you have completed the soundness proof and
are ready to tackle new challenges. Perhaps, you want to prove a
property that builds on soundness or you want to prove an orthogonal
property such as completeness.

Proof General lets you do all of this while maintaining the consistency
between proof script buffers and the state of the proof assistant.
However, you cannot have more than one buffer where only a fraction of
the proof script contains a locked region. Before you can employ script
management in  another proof script buffer, you must either fully assert
or retract the current script buffer.

@node View of processed files 
@section  View of processed files

Proof General is aware of all files that the proof assistant has
processed or is currently processing. In fact, it relies on the proof
assistant explicitly telling the Proof General whenever it processes a
new file which corresponds@footnote{For example, LEGO generates additional compiled
(optimised) proof script files for efficiency.} to a file containing a proof
script. For further technical
details, @pxref{Handling Multiple Files}. 

If the current proof script buffer depends on background material from
other files, proof assistants typically process these files
automatically. If you visit such a file, the whole file is locked as
having been processed in a single step. From the user's point of view,
you can only retract but not assert in this buffer. Furthermore,
retraction is only possible to the @emph{beginning} of the buffer.

To be more precise, buffers are locked as soon the Proof Assistant
notifies the Proof General of processing a file different from the
current proof script. Thus, if you visit the file while the Proof
Assitant is still processing the file, it is already completely locked.
If the Proof Assistant is not happy with the contents and
complains with an error message, the buffer will still be marked as
having been completely processed. Sorry. You need to visit the
troublesome file, retract (which will always retract to the beginning of 
the file) and debug the problem e.g., by asserting all of the buffer
under the supervision of the Proof General, @pxref{Script processing
commands}. 

In case you wondered, inconsistencies may arise when you have unsaved
changes in a proof script buffer and the Proof Assistant suddenly
decides to automatically process the corresponding file. The good news
is that Proof General detects this problem and flashes up a warning in
the response buffer. You might then want to visit the modified buffer,
save it and retract to the beginning. Then you are back on track.

@node Retracting across files
@section Retracting across files
@cindex Retraction

Make sure that the current script buffer has either been completely
asserted or retracted. Then you can retract proof scripts in a different
file. Simply visit a file that has been processed earlier and retract in
it, using the retraction commands from @ref{Script processing commands}. Apart from removing parts of the locked region in this
buffer, all files which depend on it will be retracted (and thus
unlocked) automatically. Proof General reminds you that now is a good
time to save any unmodified buffers.

@node Asserting across files
@section Asserting across files
@cindex Assertion

Make sure that the current script buffer has either been completely
asserted or retracted. Then you can assert proof scripts in a different
file. Simply visit a file that contains no locked region and assert some
command with the usual assertion commands, @pxref{Script processing
commands}. Proof General reminds you that now is a good time to save any
unmodified buffers. This is particularly useful as assertion may cause
the Proof Assistant to automatically process other files.


@node Working directly with the proof shell
@section Working directly with the proof shell
@cindex Shell

Occasionally you may want to review the dialogue of the entire session
with the proof assistant, or check that it hasn't done something
unexpected. Experienced users may also want to directly communicate with 
the Proof Assistant rather than sending commands via the minibuffer,  
@pxref{Other commands}.


Although the proof shell is usually hidden from view, it is run in a
buffer which provides the usual full editing and history facilities of
Emacs shells (see the package @file{comint.el} distributed with your
version of Emacs). You can switch to it using the menu:

@lisp
  Proof-General -> Switch to buffers -> Proof Shell
@end lisp

@b{Warning:} you can probably cause confusion by typing in the shell
buffer!  Proof General may lose track of the state of the proof
assistant.

Proof General watches the output from the proof assistant to guess when
a file is loaded or when a proof step is taken or undone, but it may not
be guaranteed when the restricted interface is by-passed.  What happens
depends on how complete the communication is between Proof General and
the prover (which depends on the particular instantion of Proof
General).

To resynchronise, you have two options. If you are lucky, it might
suffice to

@table @kbd
@item C-c C-z
move the end of the locked region backwards to the end of the segment
containing the point.
@end table

Otherwise, you will need to restart script management altogether,
@pxref{Toolbar commands}.




@node Support for other Packages
@chapter Support for other Packages

@menu
* Support for function menus::  
* Support for tags::            
@end menu

@node Support for function menus
@section Support for function menus
@vindex proof-goal-with-hole-regexp
@cindex fume-func

fume-func is a handy package which makes a menu from the function
declarations in a buffer.  Proof General configures fume-func so that
you can quickly jump to particular proofs in a script buffer.  This is
done with the configuration variable @code{proof-goal-with-hole-regexp}, 
@pxref{Proof Script Mode} for further details.

If you want to use fume-func, you may need to enable it for yourself.
It is distributed with XEmacs but by not enabled by
default.  To enable it you should find the file func-menu.el and follow
the instructions there.  At the time of writing, the current version of
XEmacs is 20.4, supplied with function menu version 2.45, which suggests
the following code for your @file{.emacs} file:

@lisp
   (require 'func-menu)
   (define-key global-map 'f8 'function-menu)
   (add-hook 'find-file-hooks 'fume-add-menubar-entry)
   (define-key global-map "\C-cl" 'fume-list-functions)
   (define-key global-map "\C-cg" 'fume-prompt-function-goto)
   (define-key global-map '(shift button3) 'mouse-function-menu)
   (define-key global-map '(meta  button1) 'fume-mouse-function-goto)
@end lisp

If you have another version of Emacs, you should check the fume-func.el
file supplied with it.

@node Support for tags
@section Support for tags
@cindex tags

@c FIXME: instructions for setting up etags are needed


@node Customizing Proof General
@chapter Customizing Proof General

There are two kinds of customization for Proof General: it can be
customized for a user's preferences using a particular proof assistant,
or it can be customized by an Emacs expert to add a new proof assistant.
Here we cover the user-level customization for Proof General.

We only consider settings for Proof General itself.  The support for a
particular proof assistant can provide extra customization settings.
See the chapters covering each assistant for details.



@menu
* Easy customization::          
* Setting user options::        
* Tweaking configuration settings::  
@end menu

@node Easy customization
@section Easy customization

Proof General uses the Emacs customization library extensively to
provide a friendly interface.

You can access a menu of the customization settings for Proof General
via the menu:

@lisp
   Options -> Customize -> Emacs -> External -> Proof General
@end lisp
in XEmacs.  

In FSF Emacs, use the menu:
@c FIXME
@lisp
   Help -> Customize -> Specific group
@end lisp
and type @kbd{proof-general RET}.

The complete set of customization settings will only be availabe after
Proof General has been fully loaded.  Proof General is fully loaded when
you visit a script file for the first time.

When visiting a script file, there is a more direct route to the
settings:
@lisp
   Proof-General -> Customize
@end lisp

Using the customize facility is straightforward.  You can select the
setting to customize via the menus, or with @code{M-x
customize-variable}.  When you have selected a setting, you are shown a
buffer with its current value, and facility to edit it.  Once you have
edited it, you can use the special buttons @var{set}, @var{save} and
@var{done}.  You must use one of @var{set} or @var{save} to get any
effect.  The @var{save} button stores the setting in your @file{.emacs}
file.

For more help, see @inforef{Easy Customization, ,xemacs}.


@node Setting user options
@section Setting user options
@c Index entries for each option 'concept'
@cindex{User options}
@cindex{Strict read-only}
@cindex{Query program name}
@cindex{Dedicated windows}
@cindex{Remote host}
@cindex{Toolbar follow mode}
@cindex{Toolbar disabling}
@cindex{Proof script indentation}
@cindex{Indentation}
@cindex{Remote shell}
@cindex{Running proof assistant remotely}
@c @cindex{formatting proof script}


Here are the user options for Proof General.  These can be set via the
customization system, via the old-fashioned @code{M-x edit-options}
mechanism, or simply by adding @code{setq}'s to your @file{.emacs} file.
The first approach is strongly recommended.

Notice that in the customize menus, the variable names may be
abbreviated by omitting the "@code{proof}-" prefix.  Also, some of the
option settings may have more descriptive names (for example, @var{on}
and @var{off}) than the low-level lisp values (non-@code{nil},
@code{nil}) which are mentioned here.

@defopt proof-prog-name-ask
If non-@code{nil}, query user which program to run for the inferior process.
@end defopt

@defopt proof-rsh-command
A string to use as a prefix to allow a proof assistant to be run on
a remote host. For example,
@lisp
   ssh bigjobs
@end lisp
Would cause Proof General to issue the command @code{ssh bigjobs
isabelle} to start Isabelle remotely on our large compute server called
@code{bigjobs}.

The protocol used should be configured so that no user interaction
(passwords, or whatever) is required to get going.
@end defopt

@defopt proof-toolbar-wanted
Whether to use toolbar in proof mode.
@end defopt

@defopt proof-toolbar-follow-mode
Choice of how point moves with toolbar commands.
One of the symbols: @code{locked}, @code{follow}, @code{ignore}.
If @code{locked}, point sticks to the end of the locked region with
toolbar commands. @*
If @code{follow}, point moves just when needed to display the
locked region end. @*
If @code{ignore}, point is never moved after toolbar movement commands.
@end defopt

@defopt proof-window-dedicated
Whether response and goals buffers have dedicated windows.
If non-@code{nil}, windows displaying responses from the prover will not
be switchable to display other windows.  This helps manage your display,
but can sometimes be inconvenient, especially for experienced Emacs
users.
@end defopt
@c FIXME needs to mention that without dedicated windows, buffers may be 
@c hidden. Refer to the XEmacs manual on customising buffer display.

@defopt proof-strict-read-only
Whether Proof General is strict about the read-only region in buffers.
If non-nil, an error is given when an attempt is made to edit the
read-only region.  If nil, Proof General is more relaxed (but may give
you a reprimand!)
@end defopt

@defopt proof-script-indent
If non-nil, enable indentation code for proof scripts.
Currently the indentation code can be rather slow for large scripts,
and is critical on the setting of regular expressions for 
particular provers.  Enable it if it works for you.
@end defopt

@defopt proof-one-command-per-line
If non-@code{nil}, format for newlines after each proof command in a
script.  This option is not fully-functional at the moment.
@end defopt


@node Tweaking configuration settings
@section Tweaking configuration settings

Configuration settings are the per-prover customizations of Proof
General.  Occasionally you may like to adjust some of these settings to
improve the way Proof General works.  Ideally this should not be
necessary.  One case when it may be necessary is when a proof assistant
has a flexible proof script language in which one can define new tactics
or even operations, and you want Proof General to recognize some of
these which the default settings don't mention.  So please feel free to
try adjusting the configuration settings and report to us if you find
better default values than the ones we have provided.

The configuration settings appear in the customization group
@code{prover-config}, or via the menu
@lisp
    Proof-General -> Internals ->  Prover Config
@end lisp

One basic example of a setting you may like to tweak is:

@defvar proof-assistant-home-page
Web address for information on proof assistant.
@end var

Most of the others are more complicated.  More details of the settings
are given in @xref{Adapting Proof General to New Provers}.  To browse
them, you can look through the customization groups
@code{prover-config}, @code{proof-script} and @code{proof-shell}.  The
group @code{proof-script} contains the configuration variables for
scripting, and the group @code{proof-shell} contains those for
interacting with the proof assistant.

Unfortunately, although you can use the customization mechanism to set
and save these variables, saving them may have no effect because the
default settings are often hard-wired into the proof assistant code.  At
present there is no easy way to get around this other than by editing
the source code.  Please contact us if this proves to be a problem.


@node LEGO Proof General
@chapter LEGO Proof General

LEGO proof script mode is a mode derived from proof script mode for
editing LEGO scripts. An important convention is that proof script
buffers @emph{must} start with a module declaration. If the proof script
buffer's file name is @file{fermat.l}, then it must commence with a
declaration of the form

@lisp
Module fermat;
@end lisp

If, in the development of the module @samp{fermat}, you require material
from other module e.g., @samp{lib_nat} and @samp{galois}, you need to
specify this dependency as part of the module declaration:

@lisp
Module fermat Import lib_nat galois;
@end lisp

No need to worry too much about effeciency. When you retract back to a
module declaration to add a new import item, LEGO does not actually
retract the previously imported modules. Therefore, reasserting the
extended module declaration really only processes the newly imported
modules.

Using the LEGO Proof General, you never ever need to use administrative
LEGO commands such as @samp{Forget}, @samp{ForgetMark}, @samp{KillRef},
@samp{Load}, @samp{Make}, @samp{Reload} and @samp{Undo} again
@footnote{And please, don't even think of including those in your LEGO
proof script!}. You can concentrate on your actual proof developments.
Script management in the Proof General will invoke the appropriate
commands for you. Proving with LEGO has never been easier.

@menu
* LEGO specific commands::      
* LEGO tags::                   
* LEGO customizations::         
@end menu

@node LEGO specific commands
@section LEGO specific commands

In addition to the commands provided by the generic Proof General, see
the previous sections, the LEGO Proof General provides a few extensions.
In proof scripts, there are some abbreviations for common commands:

@table @kbd
@item C-c i   
intros
@item C-c I   
Intros
@item C-c R   
Refine
@end table

@node LEGO tags
@section LEGO tags

The LEGO Proof General provides the program @file{legotags} to generate
tags for LEGO proof scripts. Invoking @samp{legotags *.l} produces a
file @file{TAGS} for all LEGO modules in the current directory. The LEGO
library itself is shipped out with all its modules already being tagged.
See @ref{Support for tags} for further details.


@node LEGO customizations
@section LEGO customizations

We refer to chapter @ref{Customizing Proof General} for an introduction
to the customisation mechanism. In addition to customizations at the
generic level, for LEGO you can also customize:

@defopt lego-tags
The directory of the TAGS table for the LEGO library. The default is
@code{"/usr/lib/lego/lib_Type/"}.
@end defopt

@defopt lego-help-menu-list
List of menu items, as defined in @code{easy-menu-define} for LEGO
  specific help.
@end defopt

@c We don't worry about the following for now. These are too obscure.
@c lego-indent
@c lego-test-all-name

@c We also don't document any of the internal variables which have been
@c set to configure the generic Proof General and which the user should
@c not tamper with

In Xemacs 20.4, LEGO script buffer are coloured (fontified as they say)
by default. To automatically switch on fontification in FSF Emacs 20.2,
you need to set
@vindex lego-mode-hooks
@cindex font-lock colour

@lisp
 (add-hook 'lego-mode-hooks 'turn-on-font-lock)
@end lisp

in your @file{~/.emacs} file.



@node Coq Proof General
@chapter Coq Proof General

@menu
* Coq specific commands::       
* Coq customizations::          
@end menu

@node Coq specific commands
@section Coq specific commands

@node Coq customizations
@section Coq customizations



@node Isabelle Proof General
@chapter Isabelle Proof General

@menu
* Isabelle specific commands::  
* Isabelle customizations::     
* Theory file editing
@end menu

@node Isabelle specific commands
@section Isabelle specific commands

@unnumberedsubsec Switching to theory files
@cindex Switching to theory files

In Isabelle proofscript mode, @kbd{C-c C-o} (@code{thy-find-other-file})
finds and switches to the associated theory file, that is, the file with
the same base name but extension @file{.thy} swapped for @file{.ML}.

The same function (and keybinding) switches back to an ML file from the
theory file.

@deffn Command thy-find-other-file
Find and switch to the associated ML file (when editing a theory file)
or theory file (when editing an ML file).  
@end deffn

@node

@node Isabelle customizations
@section Isabelle customizations

@defopt
@end opt



@node Adapting Proof General to New Provers
@chapter Adapting Proof General to New Provers

Proof General has about 60 configuration variables which are set on a
per-prover basis to configure the various features.  However, many of
these variables occcur in pairs (typically regular expressions matching
the start and end of some text), and you can begin by setting just a few
variables to get the basic features working.


@menu
* Skeleton example::            
* Proof script settings::       
* Proof shell settings::        
@end menu


@node Skeleton example
@section Skeleton example

Each proof assistant supported has its own subdirectory under
@var{proof-home-directory}, used to store a root elisp file and any
other files needed to adapt the proof assistant for Proof General.

Here we show how a minimal configuration of Proof General works for
Isabelle, without any special changes to Isabelle.

@itemize @bullet
@item Make a directory called 'myassistant' under the Proof General home
directory, to put the specific customization and associated files in.
@item Add a file myassistant.el to the new directory.
@item Edit proof-site.el to add a new entry to the
  @var{proof-assistants-table} variable.  The new entry should
look like this:

    (myassistant "My New Assistant" "\\.myasst$")

The first item is used to form the name of the internal variables
for the new mode as well as the directory and file where it loads
from.  The second is a string, naming the proof assistant.
The third item is a regular expression to match names of 
proof script files for this assistant.  See the documentation
of @var{proof-assistants-table} for more details.
@item Define the new modes in myassistant.el, by looking at 
 the files for the currently supported assistants for example.
 Basically you need to define some modes using @code{define-derived-mode}
 and set the configuration variables.  You could begin by setting
 a minimum number of the variables, then adjust the 
 settings via the customize menus, under Proof-General -> Internals.
@end itemize



@node Proof script settings
@section Proof script settings

@node Proof shell settings
@section Proof shell settings

@menu
* Special annotations::         
@end menu

@node Special annotations
@unnumberedsubsec Special annotations



@node Internals of Proof General
@chapter Internals of Proof General

@menu
* Proof Script Mode::           
* Proof Shell Mode::            
* Handling Multiple Files::     
@end menu

@node Proof Script Mode
@section Proof Script Mode

@node Proof Shell Mode
@section Proof Shell Mode

@node Handling Multiple Files
@section Handling Multiple Files
@cindex Multiple Files

Large proof developments are typically spread across multiple files.
Many provers support such developments by keeping track of dependencies
and automatically processing scripts. Proof General supports this
mechanism. The user's point of view is
explored further in @ref{Advanced Script Management}. Here, we 
describe the more technical nitty gritty. This is what you need to know
when you customise another proof assistant to work with Proof General.

The key idea is that we leave it to the specific proof assistant to
worry about managing multiple files. But whenever the proof assistant
processes or retracts a file it must clearly say so.

@vindex proof-shell-eager-annotation-start
@vindex proof-shell-eager-annotation-end

Proof General considers @var{output} delimited by the the two regualar
expressions @code{proof-shell-eager-annotation-start} and
@code{proof-shell-eager-annotation-end} as being important. It displays
the @var{output} in the Response buffer and analyses their contents further.
Among possibly other important messages characterised by these regular
expressions, the prover must tell the interface whenver it processes a
file and retracts across file boundaries. 


@vtable @code
@item proof-included-files-list
records the file history. Whenever a new file is being processed, Proof
General adds it to the
front of the list. When the prover retracts across file boundaries, this
list is resynchronised. It contains files in canonical truename format.
@inforef{Truenames,,lispref}. You should not set this variable directly.
The generic Proof General will modify @code{proof-included-files-list}
itself. Instead for a specific proof assistant you need to customise
@code{proof-shell-process-file}. @code{proof-shell-retract-files-regexp} 
and @code{proof-shell-compute-new-files-list}.

@item proof-shell-process-file is either nil or a tuple of the form
(@var{regexp}, @var{function}). If @var{regexp} matches a substring of
@var{str}, then the function @var{function} is invoked with input
@var{str}. It must return a script file name (with complete path) the
system is currently processing. In practice, @var{function} is likely to
inspect the match data. @inforef{Match Data,,lispref}. Care has to be
taken in case the prover only reports on compiled versions of files it
is processing. In this case, @var{function} needs to reconstruct the
corresponding script file name. The new (true) file name is then
automatically added to the front of @code{proof-included-files-list} by
the generic code.

@item proof-shell-retract-files-regexp
is a regular expression. It indicates that the prover has retracted
across file boundaries. At this stage, Proof General's view of the
processed files is out of date and needs to be updated with the help of
the function @code{proof-shell-compute-new-files-list}.
@end vtable

@ftable @code
@item proof-shell-compute-new-files-list
Takes as argument the current output of the prover. It needs to return
an up to date list of all processed files. Its output is then
automatically stored in
@code{proof-included-files-list} by the generic Proof General. In practice, this function is likely
to inspect the previous (global) variable
@code{proof-included-files-list} and the match data
@inforef{Match Data,,lispref} triggered by @code{proof-shell-retract-files-regexp}.
@end ftable


@c
@c
@c CHAPTER: Obtaining and Installing Proof General
@c
@c
@node Credits and References
@chapter Credits and References

@menu
* Credits::                     
* References::                  
@end menu

@node Credits
@unnumberedsec Credits

LEGO Proof General was written by Thomas Kleymann and Dilip Sequeira.

Coq Proof General was written by Healfdene Goguen.

Isabelle Proof General was written by David Aspinall.

The generic base for Proof General was developed by all four of us.

Thomas Kleymann provided the impetus to develop a generic Emacs
interface, following ideas used in Projet CROAP, and with the help of
Yves Bertot.  David Aspinall provided the Proof General name and images.

An early version of this manual was prepared by Dilip Sequeira.  The
present version was written by David Aspinall and Thomas Kleymann.

During the development of Proof General, the following people helped
by providing feedback, testing, or code:
Pascal Brisset,
Rod Burstall, 
Paul Callaghan,
Martin Hofmann,
James McKinna, 
Mark Ruys, 
Martin Steffen, 
Perdita Stevens,
and Markus Wenzel.  Thanks to all of you!


@node References
@unnumberedsec References

Script management as used in Proof General is described in the paper:

@itemize @bullet
@item
Yves Bertot and Laurent Th@'ery. A generic approach to building
user interfaces for theorem provers. To appear in Journal of
Symbolic Computation.
@end itemize

Proof General has the beginnings of support for proof by pointing,
as described in the document:

@itemize @bullet
@item
Yves Bertot, Thomas Kleymann-Schreiber and Dilip Sequeira. Implementing
Proof by Pointing without a
Structure Editor. LFCS Technical Report ECS-LFCS-97-368. Also published as Rapport de recherche de
l'INRIA Sophia Antipolis RR-3286 
@end itemize


@c
@c
@c APPENDIX: Obtaining and Installing Proof General
@c
@c
@node Obtaining and Installing Proof General
@appendix Obtaining and Installing Proof General

Proof General has its own
@uref{http://www.dcs.ed.ac.uk/home/proofgen,home page} hosted at
Edinburgh.  Visit this page for the latest news!

@menu
* Obtaining Proof General::     
* Installing Proof General from tarball::  
* Installing Proof General from RPM package::  
* Notes for syssies::           
@end menu


@node Obtaining Proof General
@section Obtaining Proof General

You can obtain Proof General from the URL
@example
@uref{http://www.dcs.ed.ac.uk/home/proofgen/download.html}.
@end example

The distribution is available in three forms
@itemize @bullet
@item A source tarball, @*
@uref{http://www.dcs.ed.ac.uk/home/proofgen/ProofGeneral-latest.tar.gz}
@item A Linux RPM package (for any architecture), @*
@uref{http://www.dcs.ed.ac.uk/home/proofgen/ProofGeneral-latest.noarch.rpm}
@item A developer's tarball, @*
@uref{http://www.dcs.ed.ac.uk/home/proofgen/ProofGeneral-devel-latest.tar.gz}
@end itemize

Both the tarball and the RPM package include the generic elisp code,
code for LEGO, Coq, and Isabelle, installation instructions (reproduced
below) and this documentation.

@c was Installing Proof General from @file{.tar.gz}
@node Installing Proof General from tarball
@section Installing Proof General from tarball

Copy the distribution to some directory @var{mydir}.
Unpack it there. For example:
@example
# cd @var{mydir}
# gunzip ProofGeneral-@var{version}.tar.gz
# tar -xpf ProofGeneral-@var{version}.tar
@end example
If you downloaded the version called @var{latest}, you'll find it
unpacks to a numeric version number.

Proof General will now be in some subdirectory of @var{mydir}.  The name
of the subdirectory will depend on the version number of Proof General.
For example, it might be @file{ProofGeneral-2.0}.  It's convenient to
link it to a fixed name:
@example
# ln -sf ProofGeneral-2.0 ProofGeneral
@end example
Now put this line in your @file{.emacs} file:
@lisp
    (load-file "@var{mydir}/ProofGeneral/generic/proof-site.el")
@end lisp

This command will load @file{proof-site} which sets the Emacs load path
for Proof General and add auto-loads and modes for the assistants below:

@multitable @columnfractions .3 .3 .4
@item       @b{Prover} @tab @b{Extensions} @tab @b{Modes}
@item       Coq    @tab @file{.v}  @tab @code{coq-mode}
@item       LEGO   @tab @file{.l}  @tab @code{lego-mode}
@item       Isabelle @tab @file{.thy},@file{.ML} @tab @code{isa-mode}
@end multitable
When you load a file with one of these extensions, the corresponding
Proof General mode will be entered.  You can also invoke the mode
command directly.

The default names for proof assistant binaries may work on your system.
If not, you will need to set the appropriate variables.  The easiest way
to do this (and most other customization of Proof General) is via the
Customize mechanism, see the menu item:
@example
  Proof-General -> Customize -> @var{Name of Assistant} -> Prog Name
@end example
The Proof-General menu is available from script buffers after 
Proof General is loaded.  To load it manually, type 
@lisp
  M-x load-library RET proof RET
@end lisp

Notice that the customization mechanism is only available in Emacs 20.x
and XEmacs.  If you cannot use customize, simply add a line like this:
@lisp
  (setq isabelle-prog-name "/usr/bin/isabelle FOL")
@end lisp
to your @file{.emacs} file.


@node Installing Proof General from RPM package
@section Installing Proof General from RPM package

To install an RPM package you need to be root.  Then type
@example
# rpm -Uvh ProofGeneral-latest.noarch.rpm
@end example

Now add the line:
@lisp
   (load-file "/usr/share/emacs/ProofGeneral/generic/proof-site.el")
@end lisp
to your @file{.emacs} or the site-wide initialisation file
@file{site-start.el}.


@node Notes for syssies
@section Notes for syssies

Here are some more notes for installing Proof General in more complex
ways.  Only attempt things in this section if you really understand what
you're doing.

@unnumberedsubsec Byte compilation

Compilation of the Emacs lisp files improves efficiency but can
sometimes cause compatibility problems (especially if you use more than
one version of Emacs at the same time).

You can compile Proof General by typing @code{make} in the directory
where you installed it.


@unnumberedsubsec Site-wide installation

If you are installing Proof General site-wide, you can put the
components in the standard directories of the filesystem if you prefer,
providing the variables in @file{proof-site.el} are adjusted
accordingly.  Make sure that the @file{generic} and assistant-specific
elisp files are kept in subdirectories (@file{coq}, @file{isa},
@file{lego}) of @code{proof-home-directory} so that the autoload
directory calculations are correct.

To prevent every user needing to edit their own @file{.emacs} files, you
can put the @code{load-file} command to load @file{proof-site.el} into
@file{site-start.el} or similar.  Consult the Emacs documention for more
details if you don't know where to find this file.

@unnumberedsubsec Removing support for unwanted provers

You cannot run more than one instance of Proof General at a time: so if
you're using Coq, visiting an @file{.ML} file will not load Isabelle
Proof General, and the buffer remains in fundamental mode.  If there are
some assistants supported that you never want to use, you can remove
them from the variable @code{proof-assistants} in @file{proof-site.el}
to solve this problem.

Via the Customize mechanism, see the menu:
@example
  Options -> Customize -> Emacs -> External -> Proof General
@end example
or, after loading Proof General, in a proof script buffer
@example
  Proof-General -> Customize
@end example



@c
@c
@c APPENDIX: Known bugs and workarounds
@c
@c
@node Known bugs and workarounds
@appendix Known bugs and workarounds

We only mention a few important problems here.  The list is not a
description of all bugs and may be out of date.  @*
Please consult the file
@uref{http://www.dcs.ed.ac.uk/home/proofgen/ProofGeneral/BUGS,@file{BUGS}}
in the distribution for more detailed and up-to-date information.  @*
If you discover a problem which isn't mentioned in @file{BUGS}, please
let us know by sending a note to @code{proofgen@@dcs.ed.ac.uk}.

@menu
* Bugs at the generic level::   
* Bugs specific to LEGO Proof General::  
* Bugs specific to Coq Proof General::  
* Bugs specific to Isabelle Proof General::  
@end menu

@node Bugs at the generic level
@section Bugs at the generic level

@unnumberedsubsec Undo in XEmacs

When @code{proof-strict-read-only} is non-nil, ordinary undo in script
buffer can edit the "uneditable region" in XEmacs.  This doesn't happen
in FSFmacs.  Test case: Insert some nonsense text after the locked
region.  Kill the line. Process to the next command.  Press @kbd{C-x u},
nonsense text appears in locked region.

@strong{Workaround:} be careful with undo.

@unnumberedsubsec Font locking and read-only in FSF Emacs

When @code{proof-strict-read-only} is set and font lock is switched on,
spurious "Region read only" errors are given which break font lock.

@strong{Workaround:} turn off @code{proof-strict-read-only}, font lock,
or for the best of all possible worlds, switch to XEmacs.


@unnumberedsubsec  Pressing keyboard quit @kbd{C-g}

Using @kbd{C-g} can leave script management in a mess.  The code is not
properly protected from Emacs interrupts.

@strong{Workaround:} Don't type @kbd{C-g} while script management is
processing.  If you do, use @code{proof-restart-scripting} to restart
the system.

@unnumberedsubsec One prover at a time
You can't use more than one proof assistant at a time in the same Emacs
session.  Attempting to load Proof General for a second prover will
fail, leaving a buffer in fundamental mode instead of the Proof General
mode for proof scripts.

@strong{Workaround:} stick to one prover per Emacs session, make sure
that the proof-assistants variables only enables Proof General for the
provers you need.


@node Bugs specific to LEGO Proof General
@section Bugs specific to LEGO Proof General

Getting retracting right is tricky when working on proofs. 

@unnumberedsubsec Definitions in a proof state 
A thorny issues are local
definitions in a proof state. LEGO cannot undo them explicitly.

@strong{Workaround:} retract back to a command before a definition.

@unnumberedsubsec Normalisation in proofs
Normalisation commands such as @samp{Dnf}, @samp{Hnf} @samp{Normal}
cannot be undone in a proof state by the Proof General.

@strong{Workaround:} retract back to the start of the proof.

@unnumberedsubsec Not saving proofs. 
After LEGO has issued a @samp{***
QED ***} you may undo steps in the proof as long as you don't issue a
@samp{Save} command or start a new proof. The LEGO Proof General assumes
that all proofs are terminated with a proper @samp{Save} command.

@strong{Workaround:} Always issue a @samp{Save} command after completing
a proof. If you forget one, you should retract to a point before the
offending proof development.

@node Bugs specific to Coq Proof General
@section Bugs specific to Coq Proof General

@unnumberedsubsec Hard-wired tactics

The collection of tactics which Proof General is aware of is hard-wired.
Thus, user-defined tactics cannot be retracted.

@strong{Workaround:} You may need to retract to the start of the proof.


@node Bugs specific to Isabelle Proof General
@section Bugs specific to Isabelle Proof General

@unnumberedsubsec Scripting lanugage limitations

Since Isabelle uses ML as a top-level language for writing
proof-scripts, Proof General may have difficulty understanding scripts
which stray too far away from the standard functions, tactics, and
tacticals.  You will usually notice when a function, or whatever,
doesn't get highlighted as you might expect.  This probably has no
detrimental impact on the interface unless you use your own variants
of the @code{goal} or @code{qed} forms.

@strong{Workaround:} Restrict yourself to standard proof script
functions, or customize some of the variables from @file{isa.el} and
@file{isa-syntax.el} appropriately.



@node Plans and ideas
@appendix Plans and ideas



@node Keystroke Index
@unnumbered Keystroke Index
@printindex ky

@node Index
@unnumbered Index
@printindex cp

@page
@contents
@bye


@c
@c OLD TEXI STUFF HERE
@c 
@c WARNING --- DO NOT EDIT BELOW HERE!!
@c







@b{Proof General} is a generic Emacs interface for proof assistants. It
works ideally under XEmacs, but can also be used with Emacs 19.
It is supplied ready-customised for these proof assistants:

@itemize @bullet
@item 
@b{LEGO Proof General} for LEGO Version 1.3.1@*
by Thomas Kleymann and Dilip Sequeira
@item 
@b{Coq Proof General} for Coq Version 6.2@*
by Healfdene Goguen
@item 
@b{Isabelle Proof General} for Isabelle 98-1@*
by David Aspinall
@end itemize

Proof General itself was written by the above with help from Yves Bertot
and using ideas from Projet CROAP. 

Proof General is suitable for use by pacifists and Emacs lovers alike.

The code is designed to be generic, so you can adapt Proof General to
other proof assistants if you know a little bit of Emacs Lisp. Our aim
is provide a powerful and configurable Emacs mode which helps
user-interaction with interactive proof assistants.

Please help us with this aim! Configure Proof General for your proof
assistant, by adding features at the generic level wherever possible.
Send ideas, comments, patches, code to @email{proofgen@@dcs.ed.ac.uk}.
Please feel free to download Proof General to customize it for another
system, and tell us how you get on.




******************



@menu
* Introduction::                
* Commands::                    
* Multiple Files::              
* An Active Terminator::        
* Proof by Pointing::           
* Walkthrough::                 
* LEGO mode::                   
* Coq mode::                    
* Known Problems::              
* Internals::  
* Variable Index::
* Function Index::
* Concept Index::                 
@end menu


@node Introduction, Commands, Top, Top
@comment node-name, next,          previous, up
@unnumberedsec Introduction

A @strong{Script Buffer} is the primary buffer for developing proof
scripts. Its major mode is @emph{proof mode}. A script buffer is divided
into three regions:

@itemize @bullet
@item The @emph{Locked} region appears in blue (underlined on monochrome
displays) and contains commands which have been sent to the proof process
and verified. The commands in the locked region cannot be edited.

@item The @emph{Queue} region appears in pink (inverse video) and contains
commands waiting to be sent to the proof process. Like those in the
locked region, these commands can't be edited.

@item The @emph{Editing} region contains the commands the user is working
on, and can be edited as normal Emacs text.
@end itemize

These three regions appear in the buffer in the order above; that is,
the locked region is always at the start of the buffer, and the editing
region always at the end. The queue region only exists if there is input
waiting to be sent to the proof process.

Proof mode has two operations which transfer commands between these
regions: assertion and retraction. These cause commands to be sent to
the proof process. The @emph{Process Buffer} records the complete
communication between the prover and the Script Buffers. Error messages
and other important messages are highlighted in the Process Buffer. The
current proof obligations (if any) are always visible in the @emph{Goals
Buffer}.

Proof General is generous. It is not a perfect interface and users may
occasionaly want to freely interact with the prover without being
watched over by the Proof General. Users may interact @emph{directly}
with the prover by entering text in the Process Buffer instead of
invoking commands in a Script Buffer. Proof mode supports a variety of
means to interact with the prover. Try these first!



@cindex Assertion
@strong{Assertion} causes commands from the editing region to be
transferred to the queue region and sent one by one to the proof
process. If the command is accepted, it is transferred to the locked
region, but if an error occurs it is signalled to the user, and the
offending command is transferred back to the editing region together
with any remaining commands in the queue.  

@cindex Retraction
@strong{Retraction} causes
commands to be transferred from the locked region to the editing region
(again via the queue region) and the appropriate 'undo' commands to be
sent to the proof process.

As commands are transferred to the locked region, they are aggregated
into segments which constitute the smallest units which can be
undone. Typically a segment consists of a declaration or definition, or
all the text from a `goal' command to the corresponding `save' command,
or the individual commands in the proof of an unfinished goal.  As the
mouse moves over the the region, the segment containing the pointer will
be highlighted.

Commands in the editing region can be freely edited while
commands in the queue are transferred to the proof process. However,
assertion and retraction commands can only be issued when the queue is
empty.

@node Commands, Multiple Files, Introduction, Top
@section Proof Mode Commands

@table @kbd

@item C-c C-b
assert the commands in the buffer.

@item C-c return
assert the commands in the editing region up to and
including the one containing the point.

@item C-c u
retract the segments in the locked region back to and
including the one containing the point. If point is outside the *Locked*
region, the last segment is undone.

@item C-c C-u
retract the last segment in the locked region, and kill the text in it.
@footnote{Be careful with this, as it may delete more than you anticipate.
However, you can always recover the killed text using Emacs Undo.}

@item C-c '
move the point to the end of the locked region.  If you are in a script
buffer other than the active scripting buffer, this will also transfer
you to the active one.

@item C-c C-e
move the point to the next terminator

@item C-c C-p
display the proof state in the goals buffer

@item C-c c
display the context in the process buffer

@item C-c h
print proof-system specific help text in the process buffer

@item C-c C-c
interrupt the process. This may leave script management or the
proof process (or both) in an inconsistent state.

@item C-c C-z
move the end of the locked region backwards to the end of the segment
containing the point. @footnote{Don't try this one at home, kids.}

@item C-c C-t
Send the command at the point to the subprocess, not
recording it in the locked region. @footnote{This is supplied in order
to enable the user to test the types and values of expressions. There's
some checking that the command won't change the proof state, but it
isn't foolproof.}

@item C-c C-v
Request a command from the minibuffer and send it to
the subprocess. Currently no checking whatsoever is done on the command.
@end table

The command @code{proof-restart-script} can be used to completely
restart script management.


@node Multiple Files, An Active Terminator, Commands, Top
@section Multiple Files

Proof mode has a rudimentary facility for operating with multiple files
in a proof development. This is currently only supported for LEGO. If
the user invokes script management in a different buffer from the one in
which it is running, one of two prompts will appear:

@itemize @bullet
@item ``Steal script management?'' 
if Emacs doesn't think the file is already part of the proof development
@item ``Reprocess this file?'' 
if Emacs thinks the file is already included in the proof process. If
the user confirms, Emacs will cause the proof process to forget the
contents of the file, so that it is processed afresh.
@end itemize

Currently this facility requires each script buffer to have a
corresponding file.

When working with script management in multiple buffers, it is easy
to lose track of which buffer is the current script buffer. As a mnemonic
aid, the word @samp{Scripting} appears in the minor mode list of the
active scripting buffer.

Caveats:
@itemize @minus
@item Note that if processing a buffer causes other files to be loaded 
into the LEGO process, those files will be imported from disk rather
than from any Emacs buffer in which it is being edited, i.e.@: if your
file is going to be included indirectly, save it.

@item However much you move around the file system in Emacs, the
LEGOPATH will be the LEGOPATH you started with. No concept of 
"current directory" is currently supported.
@end itemize

@node An Active Terminator, Proof by Pointing, Multiple Files, Top
@section An Active Terminator

Proof mode has a minor mode which causes the terminator to become
active. When this mode is active, pressing the terminator key (@kbd{;}
for LEGO, @kbd{.} for Coq) outside a comment or quote will cause the
character to be entered into the buffer, and all the commands in the
editing region up to the point to be asserted.

This mode can be toggled with the command
`proof-active-terminator-minor-mode' (@kbd{C-c ;} or @kbd{C-c .})

@node Proof by Pointing, Walkthrough, An Active Terminator, Top
@section Proof by Pointing

@emph{This mode is currently very unreliable, and we do not guarantee
that it will work as discussed in this document.}

Proof by pointing is a facility whereby proof commands can be generated
by using the mouse to select terms. When proving a goal, a summary of
the current proof state will appear in the goals buffer. By moving
the mouse over the buffer, the structure of the goal and hypothesis
terms will be shown by highlighting. 

If a selection is made using the second (usually the middle) mouse
button, Emacs will generate the appropriate commands, insert them in the
script buffer, and send them to the proof process. These commands are
aggregated in the locked region as a single segment, so that a
mouse-generated command sequence can be retracted with a single
retraction command.

Further Information about proof by pointing may be found in the paper
@cite{User Interfaces for Theorem Provers} by Yves Bertot and Laurent
Thery, to appear in @cite{Information and Computation}, from which
the following example is taken.

@menu
* Proof by Pointing Example::          An example using proof by pointing
@end menu

@node Proof by Pointing Example, ,Proof by Pointing,Proof by Pointing

Suppose we wish to prove the lego term:

@example
(((p a) \/ (q b))  /\ @{x:Prop@}(p x) -> (q x)) -> (Ex ([x:Prop] q(x)));
@end example

Asserting this goal will result in the proof state

@example
?0 : ((p a \/ q b) /\ @{x:Prop@}(p x)->q x)->Ex ([x:Prop]q x)
@end example

appearing in the goals buffer. Suppose our strategy is to use a 
case analysis on the disjunction, starting with the @samp{p(a)} subterm.
Clicking on this term will cause script management to insert the following
command sequence in the script buffer, and execute it.

@example
Intros H; Refine H; Intros H0 H1; 
Refine or_elim H0 Then Intros H2; Try Refine H2; 
@end example


The goals buffer will then read 

@example
  H : (p a \/ q b) /\ @{x:Prop@}(p x)->q x
  H0 : p a \/ q b
  H1 : @{x:Prop@}(p x)->q x
  H2 : p a
  ?10 : Ex ([x:Prop]q x)
@end example

Clicking on the subterm @samp{(p x)} in the hypothesis H1 will instruct
script management to prove an instance of @samp{(p x)} and deduce the
corresponding @samp{(q x)}. The commands

@example
allE H1; intros +1 H3; Refine impl_elim H3; Try Assumption;
@end example

are inserted and executed, leaving the proof state as

@example
  H : (p a \/ q b) /\ @{x:Prop@}(p x)->q x
  H0 : p a \/ q b
  H1 : @{x:Prop@}(p x)->q x
  H2 : p a
  H3 : (p a)->q a
  ?20 : (q a)->Ex ([x:Prop]q x)
@end example

Now clicking on the @samp{q x)} subterm in ?20 will prove the subgoal. We are
left with the other half of the original case analysis:

@example
  H : (p a \/ q b) /\ @{x:Prop@}(p x)->q x
  H0 : p a \/ q b
  H1 : @{x:Prop@}(p x)->q x
  H2 : q b
  ?26 : Ex ([x:Prop]q x)
@end example

Clicking on @samp{q x} proves the goal.




@node Walkthrough, LEGO mode, Proof by Pointing, Top
@section A Walkthrough

Here's a LEGO example of how script management is used.

First, we turn on active terminator minor mode by typing @kbd{C-c ;}
Then we enter 

`Module Walkthrough Import lib_logic;'

The command should be lit in pink (or inverse video if you don't have a
colour display).  As LEGO imports each module, a line will appear in the
minibuffer showing the creation of context marks. Eventually the
command should turn blue, indicating that LEGO has successfully
processed it. Then type (on a separate line if you like)

@samp{Goal bland_commutes: @{A,B:Prop@} (and A B) -> (and B A);}

The goal should be echoed in the goals buffer.

@samp{Intros;}

Whoops! @kbd{C-c C-u} to pretend that didn't happen.

@samp{intros; andI;}

A proof summary will appear in the goals buffer. We could solve the
goal by pointing now, but we'll stay with the keyboard.

@samp{Refine H; intros; Immed; Refine H; intros; Immed;}

finishes the Goal. 

@samp{Save bland_commutes;}

Moving the mouse pointer over the locked region now reveals that the
entire proof has been aggregated into a single segment. Suppose we
decide to call the goal something more sensible. Moving the cursor up
into the locked region, somewhere between `Goal' and `Save', we enter
@kbd{C-c u}.  The segment is transferred back into the editing
region. Now we correct the goal name, move the cursor to the end of the
buffer, and type @kbd{C-c return}.  Proof mode queues the commands for
processing and executes them.

@node LEGO mode, Coq mode, Walkthrough, Top
@section LEGO mode

LEGO mode is a mode derived from proof mode for editing LEGO scripts.
There are some abbreviations for common commands, which
add text to the buffer:

@table @kbd
@item C-c i   
intros
@item C-c I   
Intros
@item C-c R   
Refine
@end table


@node Coq mode, Known Problems, LEGO mode, Top
@section Coq mode

Coq mode is a mode derived from proof mode for editing Coq scripts.
As well as custom popup menus, it has the following commands:

@table @kbd

@item C-c C-s
search for items in the library of a given type.  This runs the
@kbd{Search} command of Coq.

@end table

In addition, there are some abbreviations for common commands, which
add text to the buffer:

@table @kbd
@item C-c I   
Intros
@item C-c a
Apply
@end table

@node Known Problems, Internals, Coq mode, Top
@section Known Problems

Since Emacs is pretty flexible, there are a whole bunch of things you
can do to confuse script management. When it gets confused, it may
become distressed, and may eventually sulk. In such instances
@code{proof-restart-script-management} may be of use.

A few things to avoid: 

@itemize @minus
@item If you're using script management with multiple files, don't start
changing the file names.

@item Script Management doesn't understand how to undo @code{Discharge}
commands in LEGO, and any attempts it makes to do so may leave it in an
inconsistent state. If you're undoing the effects of a @code{Discharge}
command, retract back to the declaration of whatever gets discharged.

@item Proof by Pointing doesn't work very well, and is inefficiently
implemented. 

@item The locked and queue regions are not quite read-only: in particular 
Emacs Undo can insert text into them. 

@item When a LEGO import command fails, the created "Mark" is not
forgotten, and the proof process thinks the file has been included. So
if you assert the command again, it will probably be accepted by LEGO,
because the relevant mark is in the namespace.
@end itemize

Fixes for some of these may be provided in a future release.

@node Internals, Variable Index, Known Problems, Top
@comment  node-name,  next,  previous,  up
@section Internals

@menu
* Granularity of Atomic Command Sequences::  
* Handling Multiple Files::     
* Adding A New Proof Assistant::
* Literature::                  
@end menu

@node Granularity of Atomic Command Sequences, Handling Multiple Files, Internals, Internals
@comment  node-name,  next,  previous,  up
@unnumberedsubsec Granularity of Atomic Commands
@cindex Granularity of Atomic Sequences
@cindex Retraction
@cindex Goal
@cindex ACS (Atomic Command Sequence)

The *Locked* region of a script buffer contains the initial segment of
the proof script which has been processed successfully. It consists of
atomic sequences of commands (ACS). Retraction is supported to the
beginning of every ACS. By default, every command is an ACS. But the
granularity of atomicity can be adjusted for different proof assistants.
This is essential when arbitrary retraction is not supported. Usually,
after a theorem has been proved, one may only retract to the start of
the goal. One needs to mark the proof of the theorem as an ACS.

@vtable @code
@item proof-atomic-sequents-list
is a list of instructions for setting up ACSs. Each instruction is a
list of the form @code{(@var{end} @var{start} &optional
@var{forget-command})}. @var{end} is a regular expression to recognise
the last command in an ACS. @var{start} is a function. Its input is the
last command of an ACS. Its output is a regular expression to recognise
the first command of the ACS. It is evaluated once and the output is
successively matched against previously processed commands until a match
occurs (or the beginning of the current buffer is reached). The region
determined by (@var{start},@var{end}) is locked as an ACS. Optionally,
the ACS is annotated with the actual command to retract the ACS. This is 
computed by applying @var{forget-command} to the first and last command
of the ACS.
@end vtable

@node Adding A New Proof Assistant, Literature, Handling Multiple Files, Internals
@comment  node-name,  next,  previous,  up
@unnumberedsubsec Adding Support for a New Proof Assistant

Suppose your new assistant is
called myassistant.

@itemize @minus
@item Make a directory called 'myassistant' under the Proof General home
directory, to put the specific customization and associated files in.
@item Add a file myassistant.el to the new directory.  
@item Edit proof-site.el to add a new entry to the
  @var{proof-assistants-table} variable.  The new entry should
look like this:

    (myassistant "My New Assistant" "\\.myasst$")

The first item is used to form the name of the internal variables
for the new mode as well as the directory and file where it loads
from.  The second is a string, naming the proof assistant.
The third item is a regular expression to match names of 
proof script files for this assistant.  See the documentation
of @var{proof-assistants-table} for more details.
@item Define the new modes in myassistant.el, by looking at 
 the files for the currently supported assistants for example.
 Basically you need to define some modes using @code{define-derived-mode}
 and set the configuration variables.  You could begin by setting
 a minimum number of the variables, then adjust the 
 settings via the customize menus, under Proof-General -> Internals.
@end itemize

@node Literature, , Adding A New Proof Assistant, Internals
@comment  node-name,  next,  previous,  up
@unnumberedsubsec Literature

The current version supports Script Management as documented in:

@itemize @bullet
@item
Yves Bertot and Laurent Th@'ery. A generic approach to building
user interfaces for theorem provers. To appear in Journal of
Symbolic Computation.
@end itemize

It has the beginnings of support for Proof by Pointing, as documented in: 

@itemize @bullet
@item
Yves Bertot, Thomas Kleymann-Schreiber and Dilip Sequeira. Implementing
Proof by Pointing without a
Structure Editor. LFCS Technical Report ECS-LFCS-97-368. Also published as Rapport de recherche de
l'INRIA Sophia Antipolis RR-3286 
@end itemize