doc update for version 0.5

1 files changed, 84 insertions, 19 deletions

diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi
index b35fea7..9cdebf3 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.6 2001/09/13 00:13:39 jao Exp $
+@c $Id: mdk_gstart.texi,v 1.7 2001/09/14 00:41:40 jao Exp $
 
 @node Getting started, mixvm.el, MIX and MIXAL tutorial, Top
 @chapter Getting started
@@ -494,9 +494,9 @@ non-interactive modes. The following subsections provide a quick tour on
 using this MIX emulator.
 
 @menu
-* 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.
 @end menu
 
 @node The mixguile shell, Additional functions, Using mixguile, Using mixguile
@@ -571,8 +571,56 @@ advantage of the Guile interpreter.
 @node Additional functions, Defining new functions, The mixguile shell, Using mixguile
 @subsection Additional MIX Scheme functions
 
+The @code{mix-} function counterparts of the @code{mixvm} commands don't
+return any value, and are evaluated only for their side-effects
+(possibly including informational messages to the standard output and/or
+error stream). When writting your own Scheme functions to manipulate the
+MIX virtual machine within @code{mixguile} (@pxref{Defining new
+functions}), you'll probably need Scheme functions returning the value
+of the registers, memory cells and so on. Don't worry: @code{mixguile}
+also offers you such functions. For instance, to access the (numerical)
+value of a register you can use @code{mix-reg}:
+
+@example
+guile> (mix-reg 'I2)
+0
+guile> 
+@end example
+@noindent
+Note that, unlike @code{(mix-preg 'I2)}, the expression @code{(mix-reg
+'I2)} in the above example evaluates to a Scheme number and does not
+produce any side-effect:
+
+@example
+guile> (number? (mix-reg 'I2))
+#t
+guile> (number? (mix-preg 'I2))
+rI2: + 00 00 (0000)	
+#f
+guile> 
+@end example
+
+In a similar fashion, you can access the memory contents using
+@code{(mix-cell)}, or the program counter using @code{(mix-loc)}:
+
+@example
+guile> (mix-cell 3000)
+786957541
+guile> (mix-loc)
+3002
+guile> 
+@end example
+
+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, see @xref{mixguile----}.
+
+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
-@subsection Definining new functions
+@subsection Defining new functions
 @cindex Scheme functions
 
 Scheme is a powerful language, and you can use it inside @code{mixguile}
@@ -629,28 +677,45 @@ Elapsed time: 1 /Total program time: 1 (Total uptime: 45)
 guile>
 @end example
 
-As you can see, the possibilities are virtually unlimited. Of course,
-you don't need to type a function definition each time you start
-@code{mixguile}. You can write it in a file, and load it using Scheme's
-@code{load} function. For instance, you can create a file named, say,
-@file{functions.scm} with the contents:
+As a third example, the following function loads a program, runs it and
+prints the contents of the memory between the program's start and end
+addresses: 
 
 @example
-(define my-load-and-run-with-bp
-  (lambda (file line)
-    (mix-load file)
-    (mix-sbp line)
-    (mix-run)))
+guile> (define my-run
+         (lambda (file)
+           (mix-load file)
+           (let ((start (mix-loc)))
+             (mix-run)
+             (mix-pmem start (mix-loc)))))
+guile> (my-run "hello")
+Program loaded. Start address: 3000
+Running ...
+MIXAL HELLO WORLD                                                     
+... done
+Elapsed time: 11 /Total program time: 11 (Total uptime: 11)
+3000: + 46 58 00 19 37 (0786957541)
+3001: + 00 00 00 02 05 (0000000133)
+3002: + 14 09 27 01 13 (0237350989)
+guile> 
 @end example
 
+
+As you can see, the possibilities are virtually unlimited. Of course,
+you don't need to type a function definition each time you start
+@code{mixguile}. You can write it in a file, and load it using Scheme's
+@code{load} function. For instance, you can create a file named, say,
+@file{functions.scm} with your definitions (or any Scheme expression)
 and load it at the @code{mixguile} prompt:
 
 @example
 guile> (load "functions.scm")
 @end example
 
+Alternatively, you can make @code{mixguile} to load it for you. When
+@code{mixguile} starts, it looks for a file named @file{mixguile.scm} in
+your MDK configuration directory (@file{~/.mdk}) and, if it exists,
+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}.
 
-
-As a third example, the following function loads a program, runs it and
-prints the contents of the memory between the program's start and end
-addresses: