version 0.5 update

4 files changed, 117 insertions, 17 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 0da6530..b06824a 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -10,13 +10,16 @@
 # WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
 # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 
+# $Id: Makefile.am,v 1.7 2001/09/28 23:11:44 jao Exp $
+
 SUBDIRS = img
 SUFFIXES = .html
 
 info_TEXINFOS = mdk.texi
-mdk_TEXINFOS = mdk_intro.texi mdk_tut.texi mdk_gstart.texi \
+mdk_TEXINFOS = mdk_intro.texi mdk_ack.texi mdk_tut.texi mdk_gstart.texi \
                mdk_mixvm.texi mdk_emixvm.texi mdk_mixasm.texi mdk_bugs.texi \
-               mdk_index.texi mdk_gmixvm.texi mdk_install.texi mdk_copying.texi
+               mdk_index.texi mdk_gmixvm.texi mdk_install.texi \
+               mdk_mixguile.texi mdk_copying.texi
 
 html_docs = mdk.html
 
diff --git a/doc/mdk.texi b/doc/mdk.texi
index 0dd4262..495e563 100644
--- a/doc/mdk.texi
+++ b/doc/mdk.texi
@@ -120,6 +120,7 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}).
 
 
 
+
 @detailmenu
  --- The Detailed Node Listing ---
 
@@ -231,8 +232,8 @@ Interactive commands
 Scheme functions reference
 
 * mixvm wrappers::              Functions invoking mixvm commands.
+* Hooks::                       Adding hooks to mixvm commands.
 * Additional VM functions::     Functions accessing the MIX virtual machine.
-* Hooks::                       
 
 Copying
 
@@ -261,4 +262,4 @@ Copying
 @contents
 @bye
 
-$Id: mdk.texi,v 1.16 2001/09/26 23:15:55 jao Exp $
+$Id: mdk.texi,v 1.17 2001/09/28 23:11:44 jao Exp $
diff --git a/doc/mdk_gmixvm.texi b/doc/mdk_gmixvm.texi
index a1fbb6f..987e39b 100644
--- a/doc/mdk_gmixvm.texi
+++ b/doc/mdk_gmixvm.texi
@@ -4,7 +4,7 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_gmixvm.texi,v 1.13 2001/09/18 22:53:18 jao Exp $
+@c $Id: mdk_gmixvm.texi,v 1.14 2001/09/28 23:11:44 jao Exp $
 
 @node gmixvm, mixguile, mixvm, Top
 @comment  node-name,  next,  previous,  up
@@ -13,6 +13,13 @@
 @cindex GUI
 @cindex GTK+
 
+This chapter describes the graphical MIX virtual machine emulator
+shipped with @sc{mdk}. In addition to having all the command-oriented
+functionalities of the other virtual machines (@code{mixvm} and
+@code{mixguile}), @code{gmixvm} offers you a graphical interface
+displaying the status of the virtual machine, the source code of the the
+downloaded programs and the contents of the MIX devices.
+
 @menu
 * Invoking @code{gmixvm}::      Invoking the GTK+ interface.
 * MIXVM console::               Using @code{mixvm} commands.
@@ -31,12 +38,34 @@ graphical front-end for the MIX virtual machine will be available in
 your system. You can invoke it by typing
 
 @example
-gmixvm @key{RET}
+gmixvm [-vhuq] [--version] [--help] [--usage] [--noinit]
 @end example
-
 @noindent
-at your command prompt. The @code{gmixvm} main window will appear,
-offering you a graphical interface to run and debug your MIX programs.
+at your command prompt, where the options have the following meanings:
+
+@defopt -v
+@defoptx --version
+Prints version and copyleft information and exits.
+@end defopt
+
+@defopt -h
+@defoptx --help
+@defoptx -u
+@defoptx --usage
+Prints a summary of available options and exits.
+@end defopt
+
+@defopt -q
+@defoptx --noinit
+Do not load the Guile initialisation file @code{~/.mdk/mixguile.scm} at
+startup. This file contains any local Scheme code to be executed by the
+embedded Guile interpreter at startup (@pxref{Using Scheme in mixvm and
+gmixvm}).
+@end defopt
+
+Typing @code{gmixvm} or @code{gmixvm -q} at your command prompt, the
+main window will appear, offering you a graphical interface to run and
+debug your MIX programs.
 
 @image{img/ss_mix, 400pt}
 
diff --git a/doc/mdk_mixguile.texi b/doc/mdk_mixguile.texi
index 7637dc0..dc2d2b0 100644
--- a/doc/mdk_mixguile.texi
+++ b/doc/mdk_mixguile.texi
@@ -4,7 +4,7 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_mixguile.texi,v 1.2 2001/09/26 23:13:15 jao Exp $
+@c $Id: mdk_mixguile.texi,v 1.3 2001/09/28 23:11:44 jao Exp $
 
 @node mixguile, Problems, gmixvm, Top
 @chapter @code{mixguile}, the Scheme virtual machine
@@ -124,11 +124,11 @@ library.
 
 @menu
 * mixvm wrappers::              Functions invoking mixvm commands.
-* Additional VM functions::     Functions accessing the MIX virtual machine.
 * Hooks::                       Adding hooks to mixvm commands.
+* Additional VM functions::     Functions accessing the MIX virtual machine.
 @end menu
 
-@node mixvm wrappers, Additional VM functions, Scheme functions reference, Scheme functions reference
+@node mixvm wrappers, Hooks, Scheme functions reference, Scheme functions reference
 @subsection @code{mixvm} command wrappers
 
 For each of the @code{mixvm} commands listed in @ref{Commands}, there is
@@ -246,7 +246,7 @@ MIX > next 5
 MIX > (mix-next 5)
 @end example
 
-@node Hooks,  , Additional VM functions, Scheme functions reference
+@node Hooks, Additional VM functions, mixvm wrappers, Scheme functions reference
 @subsection Hook functions
 
 Hooks are functions evaluated before or after executing a @code{mixvm}
@@ -317,7 +317,7 @@ stands for your root install directory, usualy @code{/usr} or
 See @ref{Hook functions} for further examples on using hook functions.
 
 
-@node Additional VM functions, Hooks, mixvm wrappers, Scheme functions reference
+@node Additional VM functions,  , Hooks, Scheme functions reference
 @subsection Additional VM functions
 
 When writing non-trivial Scheme extensions using the MIX/Scheme library,
@@ -331,48 +331,115 @@ problems, the MIX/Scheme library provides the following additional
 functions: 
 
 @defun mixvm-status
+@defunx mix-vm-status
+Return the current status of the virtual machine, as a number
+(@code{mixvm-status}) or as a symbol (@code{mix-vm-status}). Posible
+return values are:
+@multitable {aamixvmaastatusaa} {aamixvmastatusaaaaaaa} {return valuesaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@item @code{(mixvm-status)} @tab @code{(mix-vm-status)} @tab
+@item 0 @tab MIX_ERROR @tab Loading or execution error
+@item 1 @tab MIX_BREAK @tab Breakpoint encountered
+@item 2 @tab MIX_COND_BREAK @tab Conditional breakpoint
+@item 3 @tab MIX_HALTED @tab Execution terminated
+@item 4 @tab MIX_RUNNING @tab Execution stopped after @code{next}
+@item 5 @tab MIX_LOADED @tab Program successfully loaded
+@item 6 @tab MIX_EMPTY @tab No program loaded
+@end multitable
+@end defun
+
+@defun mix-vm-error?
+@defunx mix-vm-break?
+@defunx mix-vm-cond-break?
+@defunx mix-vm-halted?
+@defunx mix-vm-running?
+@defunx mix-vm-loaded?
+@defunx mix-vm-empty?
+Predicates asking whether the current virtual machine status is
+@code{MIX_ERROR}, @code{MIX_BREAK}, etc.
 @end defun
 
 @defun mix-reg register
 @defunx mix-set-reg! register value
+@code{mix-reg} evaluates to a number which is the contents of the
+specified @var{register}. @code{mix-set-reg} sets the contents of the
+given @var{register} to @var{value}. The register can be specified
+either as a string (@code{"A"}, @code{"X"}, etc.) or as a symbol
+(@code{'A}, @code{'X}, etc.). For instance,
+
+@example
+guile> (mix-reg 'A)
+2341
+guile> (mix-set-reg! "A" 2000)
+ok
+guile> (define reg-a (mix-reg 'A))
+guile> (display reg-a)
+2000
+guile> 
+@end example
 @end defun
 
 @defun mix-cell cell_no
-@defunx mix-set-cell cell_no value
+@defunx mix-set-cell! cell_no value
+Evaluate and set the contents of the memory cell number
+@var{cell_no}. Both @var{cell_no} and @var{value} are Scheme numbers.
 @end defun
 
 @defun mix-loc
+Evaluates to the value of the location counter (i.e., the address of the
+next instruction to be executed).
 @end defun
 
 @defun mix-over
 @defunx mix-set-over! #t|#f
+@code{mix-over} evaluates to @code{#t} if the overflow toggle is set,
+and to @code{#f} otherwise. The value of the overflow toggle can be
+modified using @code{mix-set-over!}.
 @end defun
 
 @defun mix-cmp
-@defun mix-set-cmp! 'L|'E|'G
+@defunx mix-set-cmp! 'L|'E|'G
+Evaluate and set the comparison flag. Possible values are the scheme
+symbols @code{L} (lesser), @code{E} (equal) and @code{G} (greater).
 @end defun
 
 @defun mix-up-time
+Evaluates to the current virtual machine uptime.
 @end defun
 
 @defun mix-lap-time
+Evaluates to the current virtual machine lapsed time, i.e., the time
+elapsed since the last @code{run} or @code{next} command.
 @end defun
 
 @defun mix-prog-time
+Evaluates to the total time spent executing the currently loaded program.
 @end defun
 
 @defun mix-prog-name
+Evaluates to a string containing the basename (without any leading path)
+of the currently loaded MIX program.
 @end defun
 
 @defun mix-prog-path
+Evaluates to a string containing the full path to the currently loaded
+MIX program.
 @end defun
 
 @defun mix-src-path
+Evaluates to a string containing the full path to the source file of the
+currently loaded MIX program.
 @end defun
 
-@defun mix-src-line
+@defun mix-src-line [lineno]
 @defunx mix-src-line-no
+@code{mix-src-line-no} evaluates to the current source file number
+during the execution of a program.  @code{mix-src-line} evaluates to a
+string containing the source file line number @var{lineno}; when
+invoked without argument, it evaluates to @code{(mix-src-line
+(mix-src-line-no))}.
 @end defun
 
 @defun mix-ddir
+Evaluates to a string containing the full path of the current device
+directory.
 @end defun