partial doc update

9 files changed, 163 insertions, 48 deletions

diff --git a/NEWS b/NEWS
index f5cd089..354017d 100644
--- a/NEWS
+++ b/NEWS
@@ -10,11 +10,36 @@ Please send mdk bug reports to bug-mdk@gnu.org.
 
 ** Added guile support. New utility 'mixguile'...
 
+** New (g)mixvm commands:
+       - psrc: print the current program's source file path
+       - pprog: print the current program's path
+       - pline: print the current program line
+       - pstat: print the current virtual machine status
+       - slog: set on/off the logging of info messages to stdout (or
+         the command log in gmixvm)
+
+** For the sake of coherence, the following (g)mixvm commands
+   have been renamed:
+       - tracing -> strace
+       - timing -> stime (set on/off timing),
+                   ptime (print timing stats)
+       - devdir -> sddir (set the devices dir),
+                   pddir (print the devices dir)
+
+** In gmixvm, when a font specified in the config file cannot be
+   loaded, it is removed from the configuration.
+
+** Bug fix: when the MIX font is changed in gmixvm, the loc widget
+   font is correctly updated.
+
 ** Bug fix: help messages are now correctly aligned in (g)mixvm.
 
 ** Bug fix: timing statitics for the MOVE instruction are correctly
    computed. 
 
+** Bug fix: pressing return at an empty 'MIX >' prompt does not
+   produce an error message.
+
 ---------------------------------------------------------------------------
 * Version 0.4.2 (17/08/01)
 
@@ -265,4 +290,4 @@ Copyright (C) 2000, 2001, Free Software Foundation, Inc.
 
 
 ---
-$Id: NEWS,v 1.34 2001/09/16 22:17:33 jao Exp $
+$Id: NEWS,v 1.35 2001/09/18 22:53:18 jao Exp $
diff --git a/doc/mdk.texi b/doc/mdk.texi
index 58afc1d..420e37c 100644
--- a/doc/mdk.texi
+++ b/doc/mdk.texi
@@ -107,34 +107,16 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}).
 * MIX and MIXAL tutorial::      Learn the innards of MIX and MIXAL.
 * Getting started::             Basic usage of the @sc{mdk} tools.
 * mixvm.el::                    Using @code{mixvm} within Emacs.
+* mixasm::                      Invoking the MIXAL assembler.
 * mixvm::                       Invoking and using the MIX virtual machine.
 * gmixvm::                      Invoking and using the GTK+ virtual machine.
-* mixasm::                      Invoking the MIXAL assembler.
+* mixguile::                    Invoking and using the Scheme virtual machine.
 * Problems::                    Reporting bugs.
 * Copying::                     @sc{mdk} licensing terms.
 * Concept Index::               Index of concepts.
 * Instructions and commands::   Index of MIXAL instructions and MIXVM commands.
 
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
 @detailmenu
  --- The Detailed Node Listing ---
 
@@ -203,13 +185,18 @@ Using @code{mixguile}
 * 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::              Using command and break hook functions.
+* Scheme scripts::              
 
 Hook functions
 
 * Command hooks::               
 * Break hooks::                 
 
+@code{mixasm}, the MIXAL assembler
+
+* Invoking @code{mixasm}::      @code{mixasm} options
+
 @code{mixvm}, the MIX computer simulator
 
 * Invocation::                  Options when invoking @code{mixvm}.
@@ -222,6 +209,7 @@ Interactive commands
 * Debug commands::              Debugging programs.
 * State commands::              Inspecting the virtual machine state.
 * Configuration commands::      Storing mixvm settings.
+* Scheme commands::             
 
 @code{gmixvm}, the GTK virtual machine
 
@@ -232,10 +220,6 @@ Interactive commands
 * MIX devices view::            Device output.
 * Menu and status bars::        Available menu commands.
 
-@code{mixasm}, the MIXAL assembler
-
-* Invoking @code{mixasm}::      @code{mixasm} options
-
 Copying
 
 * GNU General Public License::  
@@ -250,9 +234,10 @@ Copying
 @include mdk_tut.texi
 @include mdk_gstart.texi
 @include mdk_emixvm.texi
+@include mdk_mixasm.texi
 @include mdk_mixvm.texi
 @include mdk_gmixvm.texi
-@include mdk_mixasm.texi
+@include mdk_mixguile.texi
 @include mdk_bugs.texi
 @include mdk_copying.texi
 @include mdk_index.texi
@@ -262,4 +247,4 @@ Copying
 @contents
 @bye
 
-$Id: mdk.texi,v 1.14 2001/09/16 22:17:33 jao Exp $
+$Id: mdk.texi,v 1.15 2001/09/18 22:53:18 jao Exp $
diff --git a/doc/mdk_bugs.texi b/doc/mdk_bugs.texi
index 65ceb1a..abf9f89 100644
--- a/doc/mdk_bugs.texi
+++ b/doc/mdk_bugs.texi
@@ -4,9 +4,9 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_bugs.texi,v 1.3 2001/09/13 00:13:39 jao Exp $
+@c $Id: mdk_bugs.texi,v 1.4 2001/09/18 22:53:18 jao Exp $
 
-@node Problems, Copying, mixasm, Top
+@node Problems, Copying, mixguile, Top
 @chapter Reporting Bugs
 @cindex bugs
 @cindex problems
diff --git a/doc/mdk_emixvm.texi b/doc/mdk_emixvm.texi
index 111e9de..70e2ae5 100644
--- a/doc/mdk_emixvm.texi
+++ b/doc/mdk_emixvm.texi
@@ -4,9 +4,9 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_emixvm.texi,v 1.3 2001/09/13 00:13:39 jao Exp $
+@c $Id: mdk_emixvm.texi,v 1.4 2001/09/18 22:53:18 jao Exp $
 
-@node mixvm.el, mixvm, Getting started, Top
+@node mixvm.el, mixasm, Getting started, Top
 @comment  node-name,  next,  previous,  up
 @chapter mixvm.el
 
diff --git a/doc/mdk_gmixvm.texi b/doc/mdk_gmixvm.texi
index b5823bb..a1fbb6f 100644
--- a/doc/mdk_gmixvm.texi
+++ b/doc/mdk_gmixvm.texi
@@ -4,9 +4,9 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_gmixvm.texi,v 1.12 2001/09/13 00:13:39 jao Exp $
+@c $Id: mdk_gmixvm.texi,v 1.13 2001/09/18 22:53:18 jao Exp $
 
-@node gmixvm, mixasm, mixvm, Top
+@node gmixvm, mixguile, mixvm, Top
 @comment  node-name,  next,  previous,  up
 @chapter @code{gmixvm}, the GTK virtual machine
 @cindex @code{gmixvm}
diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi
index 14a88d9..1ec501f 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.9 2001/09/16 22:17:33 jao Exp $
+@c $Id: mdk_gstart.texi,v 1.10 2001/09/18 22:53:18 jao Exp $
 
 @node Getting started, mixvm.el, MIX and MIXAL tutorial, Top
 @chapter Getting started
@@ -235,7 +235,9 @@ our sample).
 As you can see, running programs non-interactively has many
 limitations. You cannot peek the virtual machine's memory contents, not
 to mention stepping through your program's instructions or setting
-breakpoints. Enter interactive mode.
+breakpoints@footnote{The @code{mixguile} program allows you to execute
+arbitrary combinations of @code{mixvm} commands (using Scheme)
+non-interactively. @xref{Scheme scripts}.}. Enter interactive mode.
 
 @node Interactive mode, Debugging, Non-interactive mode, Running the program
 @comment  node-name,  next,  previous,  up
@@ -498,7 +500,8 @@ 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::              
+* Hook functions::              Using command and break hook functions.
+* Scheme scripts::              
 @end menu
 
 @node The mixguile shell, Additional functions, Using mixguile, Using mixguile
@@ -616,8 +619,7 @@ guile>
 Other functions returning the contents of the virtual machine components
 are @code{mix-cmp} and @code{mix-over}, which eval to the value of the
 comparison flag and the overflow toggle respectively. For a complete
-list of these additional functions,
-@c see @xref{mixguile----}.
+list of these additional functions, @xref{mixguile}.
 
 In the next section, we'll see a sample of using these functions to
 extend @code{mixguile}'s functionality.
@@ -722,7 +724,7 @@ 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,  , Defining new functions, Using mixguile
+@node Hook functions, Scheme scripts, Defining new functions, Using mixguile
 @subsection Hook functions
 @cindex hook function
 @cindex pre-hook
@@ -934,6 +936,59 @@ 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 Scheme scripts,  , Hook functions, Using mixguile
+@subsection Scheme scripts
+@cindex Scheme script
+@cindex non-interactive
+
+Another useful way of using @code{mixguile} is writing executable
+scripts that perform a set of commands for you. This is done using the
+@code{mixguile} switch @code{-s} (being a Guile shell, @code{mixguile}
+accepts all the command options of @code{guile}; type @code{mixguile -h}
+for a list of all available command options). For instance, if you have
+a very useful MIX program @file{foo.mix} which you want to run often,
+you don't have to fire a MIX virtual machine, load and run it every
+time; you can write a Scheme script instead:
+
+@example
+#! /usr/bin/mixguile -s
+!#
+;;; runprimes: execute the primes.mix program
+
+;; load the file you want to run
+(mix-load "../samples/primes")
+;; execute it
+(mix-run)
+;; print the contents of registers
+(mix-pall)
+;; ...
+@end example
+
+Just save the above script to a file named, say, @file{runtest}, make it
+executable (@code{chmod +x runtest}), and, well, execute it from the
+Unix shell:
+
+@example
+$ ./runtest
+Program loaded. Start address: 3000
+Running ...
+... done
+Elapsed time: 190908 /Total program time: 190908 (Total uptime: 190908)
+rA: + 30 30 30 30 30 (0511305630)
+rX: + 30 30 32 32 39 (0511313959)
+rJ: + 47 18 (3026)
+rI1: + 00 00 (0000)     rI2: + 55 51 (3571)     
+rI3: + 00 19 (0019)     rI4: + 31 51 (2035)     
+rI5: + 00 00 (0000)     rI6: + 00 00 (0000)     
+Overflow: F
+Cmp: L
+$
+@end example
+
+Note that this is far more flexible that running programs
+non-interactively using @code{mixvm} (@pxref{Non-interactive mode}), for
+you can execute any combination of commands you want from a Scheme
+script (not just running and dumping the registers).
 
 @node Using Scheme in mixvm and gmixvm,  , Using mixguile, Getting started
 @section  Using Scheme in @code{mixvm} and @code{gmixvm}
@@ -949,7 +1004,26 @@ 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}
+interpreter). A sample @code{mixvm} session using Scheme expressions
+could be:
+
+@example
+MIX > load hello
+Program loaded. Start address: 3000
+MIX > (define a (mix-loc))
+MIX > run
+Running ...
+MIXAL HELLO WORLD                                                     
+... done
+Elapsed time: 11 /Total program time: 11 (Total uptime: 11)
+MIX > (mix-pmem a)
+3000: + 46 58 00 19 37 (0786957541)
+MIX > (mix-pmem (mix-loc))
+3002: + 14 09 27 01 13 (0237350989)
+MIX >
+@end example
+
+You can also load and evaluate a file, using the @code{scmf}
 command like this:
 
 @example
diff --git a/doc/mdk_mixasm.texi b/doc/mdk_mixasm.texi
index 7d08ef9..e2f7b1b 100644
--- a/doc/mdk_mixasm.texi
+++ b/doc/mdk_mixasm.texi
@@ -4,9 +4,9 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_mixasm.texi,v 1.3 2001/09/13 00:13:39 jao Exp $
+@c $Id: mdk_mixasm.texi,v 1.4 2001/09/18 22:53:18 jao Exp $
 
-@node mixasm, Problems, gmixvm, Top
+@node mixasm, mixvm, mixvm.el, Top
 @comment  node-name,  next,  previous,  up
 @chapter @code{mixasm}, the MIXAL assembler
 @cindex @code{mixasm}
diff --git a/doc/mdk_mixguile.texi b/doc/mdk_mixguile.texi
new file mode 100644
index 0000000..4939f9c
--- /dev/null
+++ b/doc/mdk_mixguile.texi
@@ -0,0 +1,11 @@
+@c -*-texinfo-*-
+@c This is part of the GNU MDK Reference Manual.
+@c Copyright (C) 2000, 2001
+@c   Free Software Foundation, Inc.
+@c See the file mdk.texi for copying conditions.
+
+@c $Id: mdk_mixguile.texi,v 1.1 2001/09/18 22:53:18 jao Exp $
+
+@node mixguile, Problems, gmixvm, Top
+@chapter @code{mixguile}, the Scheme virtual machine
+
diff --git a/doc/mdk_mixvm.texi b/doc/mdk_mixvm.texi
index 61b7d1c..28976fa 100644
--- a/doc/mdk_mixvm.texi
+++ b/doc/mdk_mixvm.texi
@@ -4,9 +4,9 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_mixvm.texi,v 1.8 2001/09/17 23:36:45 jao Exp $
+@c $Id: mdk_mixvm.texi,v 1.9 2001/09/18 22:53:18 jao Exp $
 
-@node mixvm, gmixvm, mixvm.el, Top
+@node mixvm, gmixvm, mixasm, Top
 @comment  node-name,  next,  previous,  up
 @chapter @code{mixvm}, the MIX computer simulator
 
@@ -136,6 +136,7 @@ all available commands.
 * Debug commands::              Debugging programs.
 * State commands::              Inspecting the virtual machine state.
 * Configuration commands::      Storing mixvm settings.
+* Scheme commands::             
 @end menu
 
 @node File commands, Debug commands, Commands, Commands
@@ -628,7 +629,7 @@ representation of the module of the stored value.
 
 @end deffn
 
-@node Configuration commands,  , State commands, Commands
+@node Configuration commands, Scheme commands, State commands, Commands
 @subsection Configuration commands
 
 This section describes commands that allow you to configure the virtual
@@ -704,10 +705,29 @@ specify an alternative location for storing these device files, while
 @code{pddir} prints the current device directory.
 @end deffn
 
-@node Scheme commands
+@node Scheme commands,  , Configuration commands, Commands
 @subsection Scheme commands
 
-:TODO: guile scripts
+If you have compiled @sc{mdk} with @code{libguile} support
+(@pxref{Special configure flags}), @code{mixvm} will start and
+initialise an embedded Guile Scheme interpret when it is invoked. That
+means that you have at your disposal, at @code{mixvm}'s command prompt,
+all the Scheme primitives described in @ref{Using mixguile} and
+@ref{mixguile}, as well as any other function or hook that you have
+defined in the initialisation file @file{~/.mdk/mixguile.scm}. To
+evaluate a Scheme function, simply type it at the @code{mixvm} command
+prompt (see @ref{Using Scheme in mixvm and gmixvm} for a
+sample). Compared to the @code{mixguile} program, this has only one
+limitation: the expressions used in @code{mixvm} cannot span more than
+one line. You can get over this inconvenience writing your multiline
+Scheme expressions in a file and loading it using the @code{scmf}
+command:
+
+@deffn {scheme command} scmf FILE_NAME
+Loads the given Scheme file and evaluates it using the embedded Guile
+interpreter. 
+@end deffn
+
 
 @node Devices,  , Commands, mixvm
 @section MIX block devices