partial doc update

1 files changed, 139 insertions, 9 deletions

diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi
index 67758f5..14a88d9 100644
--- a/doc/mdk_gstart.texi
+++ b/doc/mdk_gstart.texi
@@ -4,7 +4,7 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_gstart.texi,v 1.8 2001/09/15 02:14:01 jao Exp $
+@c $Id: mdk_gstart.texi,v 1.9 2001/09/16 22:17:33 jao Exp $
 
 @node Getting started, mixvm.el, MIX and MIXAL tutorial, Top
 @chapter Getting started
@@ -22,6 +22,7 @@ assumed; for a compact reminder, see @ref{MIX and MIXAL tutorial}.
 * Running the program::         Running and debugging your programs.
 * Using mixguile::              Using the Scheme interpreter to run and
                                 debug your programs.
+* Using Scheme in mixvm and gmixvm::  
 @end menu
 
 @node Writing a source file, Compiling, Getting started, Getting started
@@ -484,7 +485,7 @@ of executed instructions) and @code{weval} (which evaluates
 w-expressions on the fly). For a complete description of all available
 MIX commands, @xref{mixvm}.
 
-@node Using mixguile,  , Running the program, Getting started
+@node Using mixguile, Using Scheme in mixvm and gmixvm, Running the program, Getting started
 @section Using @code{mixguile}
 
 With @code{mixguile} you can run a MIX simulator embedded in a Guile
@@ -497,6 +498,7 @@ using this MIX emulator.
 * The mixguile shell::          Using the Scheme MIX virtual machine.
 * Additional functions::        Scheme functions accessing the VM.
 * Defining new functions::      Defining your own Scheme functions.
+* Hook functions::              
 @end menu
 
 @node The mixguile shell, Additional functions, Using mixguile, Using mixguile
@@ -620,7 +622,7 @@ list of these additional functions,
 In the next section, we'll see a sample of using these functions to
 extend @code{mixguile}'s functionality.
 
-@node Defining new functions,  , Additional functions, Using mixguile
+@node Defining new functions, Hook functions, Additional functions, Using mixguile
 @subsection Defining new functions
 @cindex Scheme functions
 
@@ -720,12 +722,26 @@ loads it before entering the REPL. Therefore, you can copy your
 definitions in that file, or load the @file{functions.scm} file in
 @file{mixguile.scm}.
 
-@node Hook functions
+@node Hook functions,  , Defining new functions, Using mixguile
 @subsection Hook functions
 @cindex hook function
 @cindex pre-hook
 @cindex post-hook
 
+Hooks are functions called before or after a given event occurs. In
+@code{mixguile}, you can define command and break hooks, which are
+associated, respectively, with command execution and program
+interruption events. The following sections give you a tutorial on using
+hook functions within @code{mixguile}.
+
+@menu
+* Command hooks::               
+* Break hooks::                 
+@end menu
+
+@node Command hooks, Break hooks, Hook functions, Hook functions
+@subsubsection Command hooks
+
 In the previous section, we have seen how to extend @code{mixguile}'s
 functionality through the use of user defined functions. Frequently,
 you'll write new functions that improve in some way the workings of a
@@ -787,11 +803,9 @@ Stopped at line 6:             HLT
 guile> 
 @end example
 
-You can add any number of hooks to a given command. They will be
-executed in the same order as they are registered. As a second, more
-elaborated example, let's define hooks which print the address and
-contents of a cell being modified using @code{smem}. The hook functions
-could be something like this:
+As a second, more elaborated, example, let's define hooks which print
+the address and contents of a cell being modified using @code{smem}. The
+hook functions could be something like this:
 
 @example
 (define smem-pre-hook
@@ -832,3 +846,119 @@ New contents: 100
 guile>
 @end example
 
+@cindex global hook
+
+You can add any number of hooks to a given command. They will be
+executed in the same order as they are registered. You can also define
+global post (pre) hooks, which will be called before (after) any
+@code{mixvm} command is executed. Global hook functions must admit two
+arguments, namely, a string naming the invoked command and a string list
+of its arguments, and they are installed using the Scheme functions
+@code{mix-add-global-pre-hook} and @code{mix-add-global-post-hook}. A
+simple example of global hook would be:
+
+@example
+guile> (define pre-hook
+         (lambda (cmd args)
+           (display cmd)
+           (display " invoked with arguments ")
+           (display args)
+           (newline)))
+guile> (mix-add-global-pre-hook pre-hook)
+ok
+guile> (mix-pmem 120 125)
+pmem invoked with arguments (120-125)
+0120: + 00 00 00 00 00 (0000000000)
+0121: + 00 00 00 00 00 (0000000000)
+0122: + 00 00 00 00 00 (0000000000)
+0123: + 00 00 00 00 00 (0000000000)
+0124: + 00 00 00 00 00 (0000000000)
+0125: + 00 00 00 00 00 (0000000000)
+guile>
+@end example
+
+Note that if you invoke @code{mixvm} commands within a global hook, its
+associated command hooks will be run. Thus, if you have installed both
+the @code{next} hooks described earlier and the global hook above,
+executing @code{mix-next} will yield the following result:
+
+@example
+guile> (mix-next 5)
+next invoked with arguments (5)
+slog invoked with arguments (off)
+MIXAL HELLO WORLD                                                     
+Stopped at line 7: MSG         ALF   "MIXAL"
+slog invoked with arguments (on)
+guile> 
+@end example
+
+Adventurous readers may see the above global hook as the beginning of a
+command log utility or a macro recorder that saves your commands for
+replay.
+
+@node Break hooks,  , Command hooks, Hook functions
+@subsubsection Break hooks
+
+@cindex break hook
+
+We have seen in the previous section how to associate hooks to command
+execution, but they are not the whole story. You can also associate hook
+functions to program interruption, that is, specify functions that
+should be called every time the execution of a MIX program is stopped
+due to the presence of a breakpoint, either explicit or
+conditional. Break hooks take as arguments the line number and memory
+address at which the break occurred. A simple hook that logs the line
+and address of the breakpoint could be defined as:
+
+@example
+(define break-hook
+  (lambda (line address)
+    (display "Breakpoint encountered at line ")
+    (display line)
+    (display " and address ")
+    (display address)
+    (newline)))
+@end example
+@noindent
+and installed for explicit and conditional breakpoints using
+
+@example
+(mix-add-break-hook break-hook)
+(mix-add-cond-break-hook break-hook)
+@end example
+@noindent
+after that, every time the virtual machine encounters a breakpoint,
+@code{break-code} shall be evaluated for you@footnote{You may have
+noticed that break hooks can be implemented in terms of command hooks
+associated to @code{mix-run} and @code{mix-next}. As a matter of fact,
+they @emph{are} implemented this way: take a look at the file
+@file{@emph{install_dir}/share/mdk/mix-vm-stat.scm} if you are curious.}.
+
+
+@node Using Scheme in mixvm and gmixvm,  , Using mixguile, Getting started
+@section  Using Scheme in @code{mixvm} and @code{gmixvm}
+@cindex @code{scmf}
+
+In the previous section (@pxref{Using mixguile}) we have seen how the
+Guile shell @code{mixguile} offers you the possibility of using Scheme
+to manipulate a MIx virtual machine and extend the set of commands
+offered by @code{mixvm} and @code{gmixvm}. This possibility is not
+limited to the @code{mixguile} shell. Actually, both @code{mixvm} and
+@code{gmixvm} incorporate an embedded Guile interpreter, and can
+evaluate Scheme expressions. To evaluate a single-line expression at the
+@code{mixvm} or @code{gmixvm} command prompt, simply write it and press
+return (the command parser will recognise it as a Scheme expression
+because it is parenthesized, and will pass it to the Guile
+interpreter). You can also load and evaluate a file, using the @code{scmf}
+command like this:
+
+@example
+MIX> scmf /path/to/file/file.scm
+@end example
+
+Therefore, you have at your disposal all the @code{mixguile} goodies
+described above (new functions, new command definitions, hooks...)
+inside @code{mixvm} and @code{gmixvm}. In other words, these programs
+are extensible using Scheme. See @ref{Using mixguile} for examples of
+how to do it.
+