This is "step", a vi mode for HOL Light that allows you
to step through proofs in the style of Proof General.
At the moment it only works for proofs in JRH-style:

    prove(`...`, ... THEN ... THENL [...; ...])

This thing has not been used for any big developments yet,
and might change significantly in the future.  It currently
needs the following environment:

- unix, or a sufficiently unix-like system (you might need
  to adapt the "ps" command in "server_up")
- vim with support for "--servername" compiled in (in Debian
  this apparently is provided by "vim-gnome")
- perl

The system consists of five files

- "README": this file
- "step-exrc": to be put in or sourced from your ".exrc"
- "step_goals": a one line script to start the vi that
  displays the goals
- "step_hol_light": the perl script that is the glue between
  vi and the HOL Light session
- "step.ml": the OCaml source of the system

The way this is used:

- make sure "step_hol_light" is in your path (or edit
  "step-exrc" and put the full path there)
- put "step-exrc" in your ".exrc" or source it from there
- start a HOL Light session and loadt "step.ml": this
  is the server, which also can be used for normal work
- in a separate terminal, run "step_goals" to display the
  current goal
- in a third terminal edit the HOL Light file that holds
  your proof, put the vi cursor in that proof and then give
  "step" commands: CTRL-H, CTRL-N, CTRL-P, CTRL-X and CTRL-Y.
  (If you want to use some of these keystrokes with their
  original meaning, modify "step-exrc".)

The system does not operate on the whole file, but just
on the part of it that has the cursor in it, delimited
by blank lines: this is called the "proof".  The current
position in the proof is marked with "|#", like in:

  let DOUBLE_TRUTH = prove
   (`T /\ T`, CONJ_TAC THENL
    [ACCEPT_TAC TRUTH|#; ASM_MESON_TAC[]]);;

Make sure the string "|#" does not occur at any other place
in your file!  The system does not have a state, so this
mark can be moved between steps without telling the system
about it.  The system caches a history, so the fact that
each time the proof is checked all over again from the start
does not hurt performance.  If you want to flush this cache,
enter "the_cache := [];;" in the HOL Light session.

The goal that corresponds to the DOUBLE_TRUTH example will
be displayed like:

  `T`
  ----------------------------------------------------------------------------

  ----------------------------------------------------------------------------
  0/1 ((0)+1)

The "0/1" means that at this point 0 out of 1 goals are
being processed by the script.  These 0 goals are between
the dashed lines.  After processing the ";" by typing CTRL-N,
the goals display will change to:

  `T`
  ----------------------------------------------------------------------------
  1/1 ((1))

The commands of the system are:

- CTRL-H (= "here"): process the proof up to the position
  of the cursor (not the "|#" mark but the vi editing
  cursor).  Everything after this position is ignored
  (at least if you don't change the "stop_here" parameter.)

- CTRL-N (= "next"): run the next tactic after the "|#" mark.

- CTRL-P (= "previous"): idem, but in the opposite direction.

- CTRL-X (= "execute"): run the whole proof from the start
  to the end, or until something fails.

- CTRL-Y (= "what you do after CTRL-X succeeds"): process
  the rest of the file from (and including) the current
  proof.  This is the only command that does not just look
  at the current proof.  It also removes any remaining "|#"
  marks in this part of the file.

If something fails during the processing of the proof,
an error message will appear in the lower right corner of
the goals display and/or in the HOL Light session.  If you
want to interrupt the tactic that is currently executing,
press CTRL-C in the HOL Light session.

The system has a few parameters, which are defined at the
start of "step.ml":

- "strict_checking" (0, 1, 2 or 3; default: 2): disallow
  the system to proceed in certain situations (for example
  if a tactic is run with zero remaining goals).

- "with_valid" (bool; default: true): use "VALID" when
  running the tactics.

- "show_extra_goals" (bool; default: true): also show
  the goals that currently are not being processed, separated
  from the active goals by a dashed line.

- "stop_here" (bool; default: true): ignore everything
  after the cursor position when doing CTRL-H.  This is the
  normal situation.  If "stop_here" is false, the full proof
  text will be considered, while still trying to put the
  "|#" mark near the current vi cursor position.

- "clean_at_end" (bool; default: true): remove the "|#"
  mark after the whole proof has been successfully processed.

- "run_at_qed" (bool; default: true): run the whole proof
  from source when it has been successfully processed, so
  the variable that is the name of the lemma ("DOUBLE_TRUTH"
  in the example) gets its value.

- "report_time" (bool; default: false): print the time that
  HOL Light took for the command in the HOL Light session.
  This excludes the time used by the perl script, which
  generally is quite a bit more: around 0.2 seconds on
  my machine.

- "extra_lines" (int; default: 80): the number of extra
  blank lines added in front of the goals, in order for
  the status line to reach the bottom of the goals display
  window.

- "window_width" (int; default: 80): length of the
  dashed lines that are printed in the goals window.

The system uses five files in /tmp with hardcoded names:

- "/tmp/hol_light_proof": the proof currently being worked on
- "/tmp/hol_light_goals": the current goals
- "/tmp/hol_light_step_pid": the process id of the HOL
  Light session
- "/tmp/hol_light_step_command": the command currently
  being executed; HOL Light will delete this file to signal
  it is done processing the command

The way the system works is that vi filters the proof through
"step_hol_light"; this script puts both that proof and
the command in /tmp, sends a HUP signal to the HOL Light
session, after which the signal handler does the processing;
this then puts an updated proof back in /tmp, also writes
the goals file, and deletes the command file.

Currently the system does not set the "current_goalstack"
variable (from tactics.ml).  For that justifications would
need to be added to the proof_states.  That is conceptually
not difficult, and I might do this at some point, but
not now.

So that's it!  If you have any questions about this, mail
me at <freek@cs.ru.nl> and I might reply.  I wrote this for
my own use, so don't expect too much of it.  But who knows?
