partial doc update

8 files changed, 164 insertions, 23 deletions

diff --git a/doc/.cvsignore b/doc/.cvsignore
index 0128ab7..3c56128 100644
--- a/doc/.cvsignore
+++ b/doc/.cvsignore
@@ -15,6 +15,7 @@ mdk.info-1
 mdk.info-2
 mdk.info-3
 mdk.info-4
+mdk.info-5
 mdk.ky
 mdk.log
 mdk.pg
diff --git a/doc/mdk.texi b/doc/mdk.texi
index 6999267..58afc1d 100644
--- a/doc/mdk.texi
+++ b/doc/mdk.texi
@@ -102,6 +102,7 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}).
 
 @menu
 * Introduction::                
+* Acknowledgments::             
 * Installing MDK::              Installing GNU MDK from the source tarball.
 * MIX and MIXAL tutorial::      Learn the innards of MIX and MIXAL.
 * Getting started::             Basic usage of the @sc{mdk} tools.
@@ -111,7 +112,6 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}).
 * mixasm::                      Invoking the MIXAL assembler.
 * Problems::                    Reporting bugs.
 * Copying::                     @sc{mdk} licensing terms.
-* Acknowledgments::             
 * Concept Index::               Index of concepts.
 * Instructions and commands::   Index of MIXAL instructions and MIXVM commands.
 
@@ -132,6 +132,9 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}).
 
 
 
+
+
+
 @detailmenu
  --- The Detailed Node Listing ---
 
@@ -187,6 +190,7 @@ Getting started
 * 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::  
 
 Running the program
 
@@ -196,9 +200,15 @@ Running the program
 
 Using @code{mixguile}
 
-* The mixguile shell::          
-* Additional functions::        
-* Defining new functions::      
+* 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::              
+
+Hook functions
+
+* Command hooks::               
+* Break hooks::                 
 
 @code{mixvm}, the MIX computer simulator
 
@@ -235,6 +245,7 @@ Copying
 @end menu
 
 @include mdk_intro.texi
+@include mdk_ack.texi
 @include mdk_install.texi
 @include mdk_tut.texi
 @include mdk_gstart.texi
@@ -244,7 +255,6 @@ Copying
 @include mdk_mixasm.texi
 @include mdk_bugs.texi
 @include mdk_copying.texi
-@include mdk_ack.texi
 @include mdk_index.texi
 @include mdk_findex.texi
 
@@ -252,4 +262,4 @@ Copying
 @contents
 @bye
 
-$Id: mdk.texi,v 1.13 2001/09/13 00:13:39 jao Exp $
+$Id: mdk.texi,v 1.14 2001/09/16 22:17:33 jao Exp $
diff --git a/doc/mdk_ack.texi b/doc/mdk_ack.texi
index 4145694..cba9251 100644
--- a/doc/mdk_ack.texi
+++ b/doc/mdk_ack.texi
@@ -4,9 +4,9 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_ack.texi,v 1.2 2001/09/14 00:48:29 jao Exp $
+@c $Id: mdk_ack.texi,v 1.3 2001/09/16 22:17:33 jao Exp $
 
-@node Acknowledgments, Concept Index, Copying, Top
+@node Acknowledgments, Installing MDK, Introduction, Top
 @comment  node-name,  next,  previous,  up
 @unnumbered Acknowledgements
 
diff --git a/doc/mdk_copying.texi b/doc/mdk_copying.texi
index bfb6b34..bbcd225 100644
--- a/doc/mdk_copying.texi
+++ b/doc/mdk_copying.texi
@@ -1,4 +1,4 @@
-@node Copying, Acknowledgments, Problems, Top
+@node Copying, Concept Index, Problems, Top
 @appendix Copying
 
 @menu
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.
+
diff --git a/doc/mdk_index.texi b/doc/mdk_index.texi
index 9c3a1db..5aaecc4 100644
--- a/doc/mdk_index.texi
+++ b/doc/mdk_index.texi
@@ -4,9 +4,9 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_index.texi,v 1.4 2001/09/13 00:13:39 jao Exp $
+@c $Id: mdk_index.texi,v 1.5 2001/09/16 22:17:33 jao Exp $
 
-@node Concept Index, Instructions and commands, Acknowledgments, Top
+@node Concept Index, Instructions and commands, Copying, Top
 @unnumbered Concept Index
 
 @cindex tail recursion
diff --git a/doc/mdk_install.texi b/doc/mdk_install.texi
index a9aa9a8..2874d79 100644
--- a/doc/mdk_install.texi
+++ b/doc/mdk_install.texi
@@ -4,7 +4,7 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@node Installing MDK, MIX and MIXAL tutorial, Introduction, Top
+@node Installing MDK, MIX and MIXAL tutorial, Acknowledgments, Top
 @comment  node-name,  next,  previous,  up
 @chapter Installing @sc{mdk}
 
diff --git a/doc/mdk_intro.texi b/doc/mdk_intro.texi
index 5464980..c86ca18 100644
--- a/doc/mdk_intro.texi
+++ b/doc/mdk_intro.texi
@@ -4,9 +4,9 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_intro.texi,v 1.4 2001/09/13 00:13:39 jao Exp $
+@c $Id: mdk_intro.texi,v 1.5 2001/09/16 22:17:33 jao Exp $
 
-@node Introduction, Installing MDK, Top, Top
+@node Introduction, Acknowledgments, Top, Top
 @comment  node-name,  next,  previous,  up
 @unnumbered Introduction
 @cindex Introduction