----------------------------------------------------------------------
          isa-mode -- GNU Emacs support for Isabelle

             Outline of Features and Usage Hints
----------------------------------------------------------------------


========== What is Isabelle Mode? ==========


This package provides editing and interaction functions for the
theorem prover Isabelle.  When used with FSF Emacs 19 or Lucid Emacs,
there is a system of menus and multiple windows.

Here's what you get:


 * Theory mode    -  for editing theory files

This mode understands the syntax for strings (automatic backslashes)
and allows convenient switching to sml-mode in the "ML" section of
theory files.  It provides templates to help remind you of the syntax
for theory files.  There is a master menu to start-up an Isabelle
session and view Isabelle documentation.


 * Isabelle mode  -  for interacting with Isabelle

Isabelle is run in a shell-like buffer, based on the latest Emacs
command-interpreter software.  This provides useful command history,
filename completion, tactic/tactical/command completion, and the usual
advantages of running Isabelle inside Emacs.  A collection of menus
for common proof commands are provided.  These insert command text
into the Isabelle buffer.  The interaction buffer can be used in
conjunction with other special buffers...


 * Listener       -  a buffer for recording interactive proofs

This receives a copy of the commands you type to Isabelle, to record
interactive proofs.  You can cut from this buffer and use
"isa-batchify" (previously called "goalify") to very easily create
batch proofs from interactive ones.  Future versions of isa-mode will
provide more advanced ways of using a "Listener"-like buffer, so that,
for example, undo() commands may be interpreted.


 * Proof-State    -  a buffer which displays the current proof state

This buffer maintains the display of the current proof state, removing
it from the output in the Isabelle interaction buffer.  The cursor
keys can be used in this buffer to page back through previous levels
of the proof, or select a "denoted" subgoal for the menu-driven tactic
commands to use.


 * Rule-table     -  rule names for the current logic

This buffer displays a formatted table of rule names for the logic in
use.  Mouse-clicking (or key-pressing in Emacs 18) on a rule name
inserts it into the Isabelle interaction buffer, or displays the 
rule (as "prth" would) in a temporary buffer.


In Emacs 19 varieties, each of the Isabelle interaction related
buffers can appear in a separate X-window.  In non-window
environments, the pull-down menus degenerate to Emacs commands, and
the special buffers are displayed in split Emacs "windows".


To find out how to use all this -- try it out!!


See the instructions for starting out in README.txt.

Further documentation of the facilities is available within via Emacs
function and variable documentation strings.




====== How can I add support for my own Logics? ======


Presently this is a bit low-level.  In future, we may introduce
special LOGIC.el lisp files on a per-logic basis, and ways of
automatically generating them.

The ruletable data is held in the variable isa-theory-rules.  On
loading isa-mode, the contents of isa-user-theory-rules is appended to
the default value, so you can set this in your .emacs.

Alternatively, the functions 

  isa-add-theory-rules THEORYLIST
  isa-add-theory-rulegroup THEORYNAME RULEGROUP

can be called to extend the ruletable variable.


The format of the isa-theory-rules is:

  A list of lists, one per theory (or logic).
  Each theory list consists of:  (THYNAME  RULEGROUP1 RULEGROUP2 ...)
  Each rule group constists of:  (RULEGROUPNAME . [rulenames...])
  Each rule-name is either a string or nil - nil represents a further
   (un-named) subgrouping of the rules.

A convenient way to call the extention functions when you are working
on a theory is to add some special lines to a .thy or .ML file,
something like:

  (*
    *** Emacs:
    *** eval: (isa-add-theory-rulegroup "HOL"
  	             '("List" . ["assoc_def" "filter_def"]))
    *** eval: (isa-add-theory-rules 
                 '("Mythy" 
                    ("Group1"  . ["a" "b" "c" () "d" "e" "f"])
		        ("Group2"  . ["h" "i" "j"])))
    *** End:
  *)

When the file is visited by Emacs, the eval forms will extend the
ruletable variable.

Once you have these forms correct, they might be moved to a LOGIC.el
file to be loaded when you start-up the logic, so then you can use the
rules without needing to visit a .thy or .ML file.

(LOGIC.el files aren't automatically loaded at present - you
must use M-x load-file)



========= How can I change default fonts, colours, etc? ==========

In Lucid Emacs, the best way is by X-resources.  See the files
Xdefaults and Xdefaults-full for the pattern of resource names.

In FSF Emacs, you can use the internal functions.

See isa-display.el for global display properties (window geometries).

Emacs faces used at present are:

     ruletableGroupname       -  headings in rule tables.
     proofstateGoal           -  goal in proofstate display
     proofstateSubgoalNumber  -  subgoal numbers in proofstate display

You can set these faces to default to others using the variables
<face-name>-default, e.g.
 
     (setq proofstateGoal-default 'bold)    ; I don't like bold-italic.

Alternatively, make them yourself and set the attributes you wish to.
(Remember all fonts must be the same size in FSF Emacs).


