version 0.4

3 files changed, 123 insertions, 27 deletions

diff --git a/doc/.cvsignore b/doc/.cvsignore
index acd5b54..ff094bd 100644
--- a/doc/.cvsignore
+++ b/doc/.cvsignore
@@ -8,6 +8,7 @@ mdk.info
 mdk.info-1
 mdk.info-2
 mdk.info-3
+mdk.info-4
 semantic.cache
 stamp-vti
 version.texi
diff --git a/doc/mdk.texi b/doc/mdk.texi
index 31c36bf..7760fac 100644
--- a/doc/mdk.texi
+++ b/doc/mdk.texi
@@ -13,8 +13,8 @@
 
 
 @set UPDATED 9 June 2001
-@set EDITION 0.3.4
-@set VERSION 0.3.5
+@set EDITION 0.4
+@set VERSION 0.4
 @set JAO Jose Antonio Ortega Ruiz
 @set PHILIP Philip E. King
 @footnotestyle separate
@@ -119,6 +119,7 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}).
 
 
 
+
 @detailmenu
  --- The Detailed Node Listing ---
 
@@ -190,6 +191,7 @@ Interactive commands
 * File commands::               Loading and executing programs.
 * Debug commands::              Debugging programs.
 * State commands::              Inspecting the virtual machine state.
+* Configuration commands::      
 
 @code{gmixvm}, the GTK virtual machine
 
diff --git a/doc/mdk_mixvm.texi b/doc/mdk_mixvm.texi
index ee932e6..87449b1 100644
--- a/doc/mdk_mixvm.texi
+++ b/doc/mdk_mixvm.texi
@@ -31,7 +31,7 @@ setting to aid you in debugging your code. For a tutorial description of
 @section Invoking @code{mixvm}
 
 @code{mixvm} can be invoked with the following command line options
-(note, that, following GNU's conventions, we provide a long option name
+(note that, following GNU's conventions, we provide a long option name
 for each available single letter switch):
 
 @example
@@ -84,6 +84,11 @@ optional @var{FILE} argument is given, the file @file{FILE.mix} will be
 loaded into the virtual machine memory before entering the interactive
 mode. 
 
+The first time @code{mixvm} is invoked, a directory named @file{.mdk} is
+created in your home directory. It contains the @code{mixvm}
+configuration file, the command history file and (by default) the block
+devices files (@pxref{Devices}).
+
 @node Commands, Devices, Invocation, mixvm
 @comment  node-name,  next,  previous,  up
 @section Interactive commands 
@@ -102,21 +107,31 @@ ready to execute your commands. As we have already mentioned, this
 command prompt offers you command line editing facilities which are
 described in the Readline user's manual (chances are that you are
 already familiar with these command line editing capabilities, as they
-are present in many GNU utilities, e.g. the @code{bash} shell). As a
-beginner, your best friend will be the @code{help} command, which shows
-you a summary of all available MIX commands and their usage; its syntax
-is as follows:
+are present in many GNU utilities, e.g. the @code{bash}
+shell)@footnote{The readline functionality will be available if you have
+compiled @sc{mdk} with readline support, i.e., if GNU readline is
+installed in your system. This is ofte the case in GNU/Linux and BSD
+systems}. In a nutshell, readline provides command completion using the
+@kbd{TAB} key and command history using the cursor keys. A history file
+containing the last commands typed in previous sessions is stored in the
+@sc{mdk} configuration directory (@file{~/.mdk}).
+
+As a beginner, your best friend will be the @code{help} command, which
+shows you a summary of all available MIX commands and their usage; its
+syntax is as follows:
 
 @deffn {@code{mixvm} command} help [command]
 @deffnx {@code{mixvm} command} ? [command]
 Prints a short description of the given @var{command} and its usage. If
-@var{command} is omitted, all available commands are described.
+@var{command} is omitted, @code{help} prints the short description for
+all available commands.
 @end deffn
 
 @menu
 * File commands::               Loading and executing programs.
 * Debug commands::              Debugging programs.
 * State commands::              Inspecting the virtual machine state.
+* Configuration commands::      Storing mixvm settings.
 @end menu
 
 @node File commands, Debug commands, Commands, Commands
@@ -169,13 +184,17 @@ The source file @var{file.mixal} is edited using the editor defined in
 the environment variable @var{MDK_EDITOR}. If this variable is not set,
 the following ones are tried out in order: @var{X_EDITOR}, @var{EDITOR}
 and @var{VISUAL}. If invoked without argument, the source file for the
-currently loaded MIX file is edited.
+currently loaded MIX file is edited. The command used to edit source
+files can also be configured using the @code{sedit} command
+(@pxref{Configuration commands}).
 @end deffn
 
 @deffn {file command} compile file[.mixal]
 The source file @var{file.mixal} is compiled (with debug information
 enabled) using @code{mixasm}. If invoked without argument, the source
-file for the currently loaded MIX file is recompiled.
+file for the currently loaded MIX file is recompiled. The compilation
+command can be set using the @code{sasm} command (@pxref{Configuration
+commands}). 
 @end deffn
 
 
@@ -279,19 +298,21 @@ arguments, @code{psym} will print all defined symbols and their values.
 The virtual machine can also show you the instructions it is executing,
 using the following commands:
 
-@deffn {debug command} tron
-@deffnx troff
-@code{tron} enables instruction tracing. When tracing is enabled, each
-time the virtual machine executes an instruction (due to your issuing a
-@code{run} or @code{next} command), it is printed in its canonical form
-(that is, with all expressions evaluated to their numerical values) and,
-if the program was compiled with debug information, as it was originally
-typed in the MIXAL source file. Instruction tracing is disable with the
-@code{troff} command. A typical tracing session could be like this:
+@deffn {debug command} tracing [on|off]
+@code{tracing on} enables instruction tracing. When tracing is enabled,
+each time the virtual machine executes an instruction (due to your
+issuing a @code{run} or @code{next} command), it is printed in its
+canonical form (that is, with all expressions evaluated to their
+numerical values) and, if the program was compiled with debug
+information, as it was originally typed in the MIXAL source
+file. Instruction tracing is disabled with @code{tracing off}
+command. When run without arguments, @code{tracing} shows the current
+tracing status. A typical tracing session could be like this:
 
 @example
-MIX > tron
-Instruction tracing has been turned ON.
+MIX > tracing on
+MIX > tracing
+Instruction tracing is currently ON.
 MIX > next
 3000: [OUT	3002,0(2:3)]	START	OUT	MSG(TERM)
 MIXAL HELLO WORLD                                                     
@@ -300,16 +321,22 @@ MIX > next
 3001: [HLT	0,0]		HLT
 End of program reached at address 3002
 Elapsed time: 10 /Total program time: 11 (Total uptime: 11)
-MIX > troff
-Instruction tracing has been turned OFF.
+MIX > tracing off
+MIX > tracing
+Instruction tracing is currently OFF.
 MIX > 
 @end example
 @noindent
 The executed instruction, as it was translated, is shown between square
 brackets after the memory address, and, following it, you can see the
-actual MIXAL code that was compiled into the executed instruction.
+actual MIXAL code that was compiled into the executed instruction. The
+tracing behaviour is stored as a configuration parameter in @file{~/.mdk}.
 @end deffn
 
+As you have probably observed, @code{mixvm} prints timing statistics
+when running programs. This behaviour can be controlled using the
+@code{timing} command (@pxref{Configuration commands}).
+
 @code{mixvm} is also able of evaluating w-expressions
 (@pxref{W-expressions}) using the following command:
 
@@ -363,7 +390,7 @@ MIX >
 @end example
 @end deffn
 
-@node State commands,  , Debug commands, Commands
+@node State commands, Configuration commands, Debug commands, Commands
 @comment  node-name,  next,  previous,  up
 @subsection State commands
 
@@ -463,6 +490,70 @@ representation of the module of the stored value.
 
 Finally, you can use the @code{quit} command to exit @code{mixvm}.
 
+@node Configuration commands,  , State commands, Commands
+@comment  node-name,  next,  previous,  up
+@subsection Configuration commands
+
+This section describes commands that allow you to configure the virtual
+machine behaviour. This configuration is stored in the @sc{mdk}
+directory @file{~/.mdk}.
+
+@deffn {config command} timing  [on|off]
+This command (un)sets the printing of timing statistics. When run
+without argument, it prints the current timing statistics.
+
+@example
+MIX > timing
+Elapsed time: 10 /Total program time: 11 (Total uptime: 11)
+MIX >
+@end example
+@end deffn
+
+@deffn {config command} sedit TEMPLATE
+@deffnx pedit
+@code{sedit} sets the command to be used to edit MIXAL source files with
+the @code{edit} command. @var{TEMPLATE} must contain the control
+characters @code{%s} to mark the place where the source's file name will
+be inserted. For instance, if you type
+
+@example
+MIX > sedit emacsclient %s
+MIX >
+@end example
+
+issuing the @code{mixvm} command @w{@code{edit foo.mixal}} will invoke
+the operating system command @w{@code{emacsclient foo.mixal}}.
+
+@code{pedit} prints the current value of the edit command template.
+
+@end deffn
+
+@deffn {config command} sasm TEMPLATE
+@deffnx pasm
+@code{sasm} sets the command to be used to compile MIXAL source files with
+the @code{compile} command. @var{template} must contain the control
+characters @code{%s} to mark the place where the source's file name will
+be inserted. For instance, if you type
+
+@example
+MIX > sasm mixasm -g -l %s
+MIX >
+@end example
+
+issuing the @code{mixvm} command @w{@code{compile foo.mixal}} will invoke
+the operating system command @w{@code{mixasm -g -l foo.mixal}}.
+
+@code{pasm} prints the current value of the compile command template.
+
+@end deffn
+
+@deffn {config command} devdir [DIRNAME]
+MIX devices (@pxref{Devices}) are implemented as regular files
+stored, by default, inside @file{~/.mdk}. This command lets you specify
+an alternative location for storing these device files. When run without
+arguments, @code{devdir} prints the current device directory.
+@end deffn
+
 @node Devices,  , Commands, mixvm
 @comment  node-name,  next,  previous,  up
 @section MIX block devices
@@ -473,13 +564,15 @@ implements these block devices as disk files, with the exception of
 block device no. 19 (typewriter terminal) which is redirected to
 standard output. When you request an output operation on any other
 (output) device, a file named according to the following table will be
-created in the current directory, and the specified MIX words will be
+created, and the specified MIX words will be
 written to the file in binary form (for binary devices) or in ASCII (for
 char devices). Files corresponding to input block devices should be
 created and filled beforehand to be used by the MIX virtual machine (for
 input-output devices this creation can be accomplished by a MIXAL
 program writing to the device the required data, or, if you prefer, with
-your favourite editor).
+your favourite editor). The device files are stored, by default, in the
+directory @file{~/.mdk}; this location can be changed using the
+@code{mixvm} command @code{devdir} (@pxref{Configuration commands}).
 
 @multitable {the device name} { xx-xx } {filename[x-x].dev} {bin  i/o } 
 @item @emph{Device}  @tab @emph{No.} @tab @emph{filename} @tab @emph{type}