candidate release 1.0

6 files changed, 97 insertions, 53 deletions

diff --git a/doc/mdk.texi b/doc/mdk.texi
index 495e563..63c2aec 100644
--- a/doc/mdk.texi
+++ b/doc/mdk.texi
@@ -12,9 +12,9 @@
 @end direntry
 
 
-@set UPDATED September 10th, 2001
-@set EDITION 0.5
-@set VERSION 0.5
+@set UPDATED April, 2002
+@set EDITION 1.0
+@set VERSION 1.0
 @set JAO Jose Antonio Ortega Ruiz
 @set PHILIP Philip E. King
 @footnotestyle separate
@@ -23,7 +23,7 @@
 This file documents the the GNU @sc{mdk} utilities for developing
 programs using Donald Knuth's MIX language.
 
-Copyright (C) 2000, 2001 Free Software Foundation, Inc.
+Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this
 document under the terms of the GNU Free Documentation License,
@@ -262,4 +262,4 @@ Copying
 @contents
 @bye
 
-$Id: mdk.texi,v 1.17 2001/09/28 23:11:44 jao Exp $
+$Id: mdk.texi,v 1.18 2002/04/08 00:26:38 jao Exp $
diff --git a/doc/mdk_ack.texi b/doc/mdk_ack.texi
index cba9251..532bd02 100644
--- a/doc/mdk_ack.texi
+++ b/doc/mdk_ack.texi
@@ -1,10 +1,10 @@
 @c -*-texinfo-*-
 @c This is part of the GNU MDK Reference Manual.
-@c Copyright (C) 2000, 2001
+@c Copyright (C) 2000, 2001, 2002
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_ack.texi,v 1.3 2001/09/16 22:17:33 jao Exp $
+@c $Id: mdk_ack.texi,v 1.4 2002/04/08 00:26:38 jao Exp $
 
 @node Acknowledgments, Installing MDK, Introduction, Top
 @comment  node-name,  next,  previous,  up
@@ -33,12 +33,16 @@ Mandrake packages.
 pointed out various bugs and provided helpful suggestions for improving
 mixvm. 
 
+@item Francesc Xavier Noria (@email{fxn@@retemail.es})
+kindly and thoroughly reviewed the @sc{mdk} documentation, providing
+insightful advice.
+
 @item Ying-Chieh Liao (@email{ijliao@@csie.nctu.edu.tw})
 tested @sc{mdk} on a FreeBSD system, and developed and maintains a port for
 it.
 
 @item Adrian Bunk (@email{bunk@@fs.tum.de})
-created and maintains the @sc{mdk} Debian packages.
+created and maintained the @sc{mdk} Debian packages.
 
 @item Christoph von Nathusius (@email{nathusiu@@gmx.net})
 tested @sc{mdk} on Windows/Cygwin and reported a bug on pmem.
@@ -46,6 +50,10 @@ tested @sc{mdk} on Windows/Cygwin and reported a bug on pmem.
 @item Stephen Ramsay (@email{sjr3a@@virginia.edu})
 tested @sc{mdk} on Sun/Solaris.
 
+@item Johan Swanljung (@email{johanswa@@yahoo.com})
+tested @sc{mdk} on Mac OS X, and helped fix the configuration process
+to support this platfom.
+
 @item Jason Uhlenkott
 also reported the pmem problem.
 
@@ -58,9 +66,8 @@ reported a bug in mixvm's MOVE implementation.
 @item Milan Bella (@email{milanbella@@hotmail.com})
 reported a bug in @sc{mdk} documentation.
 
-@item @sc{mdk} was inspired by Darius Bacon's MIXAL program
-(@email{djello@@well.sf.ca.us}) which can be installed in Debian 2.3 as
-the package "mixal".
+@item @sc{mdk} was inspired by Darius Bacon's
+@uref{http://www.accesscom.com/~darius/, MIXAL program}.
 
 @end itemize
 
diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi
index c9b936b..f04e5c1 100644
--- a/doc/mdk_gstart.texi
+++ b/doc/mdk_gstart.texi
@@ -1,10 +1,10 @@
 @c -*-texinfo-*-
 @c This is part of the GNU MDK Reference Manual.
-@c Copyright (C) 2000, 2001
+@c Copyright (C) 2000, 2001, 2002
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_gstart.texi,v 1.12 2002/03/19 22:38:13 jao Exp $
+@c $Id: mdk_gstart.texi,v 1.13 2002/04/08 00:26:38 jao Exp $
 
 @node Getting started, mixvm.el, MIX and MIXAL tutorial, Top
 @chapter Getting started
@@ -72,8 +72,11 @@ column in its line, for the first whitespace in the line maks the
 beginning of the second field),
 @item
 an operation mnemonic, which can represent either a MIX instruction
-(@code{OUT} and @code{HLT} in lines 6 and 7 above), or an assembly
-pseudoinstruction.
+(@code{OUT} and @code{HLT} in lines 7 and 8 above), or an assembly
+pseudoinstruction (e.g., the @code{ORIG} pseudoinstruction in line
+6@footnote{If an @code{ORIG} directive is not used, the program will
+be loaded by the virtual machine at address 0. @code{ORIG} allows
+allocating the executable code where you see fit.}.
 @item
 an optional operand for the (pseudo)instruction, and
 @item
@@ -88,10 +91,12 @@ the operand always starts at a fixed column number, and the use of
 quotation is therefore unnecessary. As @code{mixasm} releases this
 requirement, marking the beginning and end of the @code{ALF} operand
 disambiguates the parser's recognition of this operand when it includes
-blanks}. 
+blanks. Note that double-quotes (") are not part of the MIX character
+set, and, therefore, no escape characters are needed within
+@code{ALF}'s operands.}. 
 
 The workings of this sample program should be straightforward if you are
-familiar with MIXAL. See TAOCP vol. 1 for a thorought definition or
+familiar with MIXAL. See TAOCP vol. 1 for a thorough definition or
 @ref{MIX and MIXAL tutorial}, for a tutorial.
 
 @node Compiling, Running the program, Writing a source file, Getting started
@@ -120,7 +125,7 @@ If the source file contains no errors, this will produce a binary file
 called @file{hello.mix} which can be loaded and run by the MIX virtual
 machine. The @code{-g} flag tells the assembler to include debug
 information in the executable file (for a complete description of all
-the compilation options, see @ref{mixasm}.) Now, your are ready to run
+the compilation options, see @ref{mixasm}). Now, your are ready to run
 your first MIX program, as described in the following section.
 
 
@@ -154,12 +159,12 @@ Using the MIX simulators, you can run your MIXAL programs, after
 compiling them with @code{mixasm} into binary @file{.mix}
 files. @code{mixvm} can be used either in @dfn{interactive} or
 @dfn{non-interactive} mode. In the second case, @code{mixvm} will load
-your program into memory, execute it (producing any output due to MIXAL
-@code{OUT} instructions present in the program), and exit when it
-encounters a @code{HLT} instruction. In interactive mode, you will enter
-a shell prompt which allows you issuing commands to the running virtual
-machine. This commands will permit you loading, running and debugging
-programs, as well as inspecting the MIX computer state (register
+your program into memory, execute it (producing any output due to
+MIXAL @code{OUT} instructions present in the program), and exit when
+it encounters a @code{HLT} instruction. In interactive mode, you will
+enter a shell prompt which allows you issuing commands to the running
+virtual machine. This commands will permit you to load, run and debug
+programs, as well as to inspect the MIX computer state (register
 contents, memory cells contents and so on).
 
 @menu
@@ -184,7 +189,6 @@ mixvm -r hello @key{RET}
 
 @example
 MIXAL HELLO WORLD
-** Execution time: 11
 @end example
 
 @noindent Since our hello world program uses MIX's device number 19 as
@@ -196,10 +200,24 @@ and written its output there@footnote{The device files are stored, by
 default, in a directory called @file{.mdk}, which is created in your
 home directory the first time @code{mixvm} is run. You can change this
 default directory using the command @code{devdir} when running
-@code{mixvm} in interactive mode (@pxref{Configuration commands})}. Note
-also that the virtual machine reports the execution time of the program,
+@code{mixvm} in interactive mode (@pxref{Configuration commands})}. 
+
+The virtual machine can also report the execution time of the program,
 according to the (virtual) time spent in each of the binary instructions
-(@pxref{Execution times}).
+(@pxref{Execution times}). Printing of execution time statistics is
+activated with the @code{-t} flag; running
+
+@example
+mixvm -t -r hello @key{RET}
+@end example
+
+@noindent
+produces the following output:
+
+@example
+MIXAL HELLO WORLD
+** Execution time: 11
+@end example
 
 Sometimes, you will prefer to store the results of your program in MIX
 registers rather than writing them to a device. In such cases,
@@ -216,7 +234,6 @@ mixvm -d -r hello
 
 @example
 MIXAL HELLO WORLD
-** Execution time: 11
 rA: + 00 00 00 00 00 (0000000000)
 rX: + 00 00 00 00 00 (0000000000)
 rJ: + 00 00 (0000)
diff --git a/doc/mdk_install.texi b/doc/mdk_install.texi
index c240c57..2c09a52 100644
--- a/doc/mdk_install.texi
+++ b/doc/mdk_install.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU MDK Reference Manual.
-@c Copyright (C) 2000, 2001
+@c Copyright (C) 2000, 2001, 2002
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
@@ -114,7 +114,7 @@ you should see a message with the configuration results like the
 following:
 
 @example
-*** GNU MDK 0.5 has been successfully configured. ***
+*** GNU MDK 1.0 has been successfully configured. ***
 
 Type 'make' to build the following utilities:
     - mixasm (MIX assembler)
@@ -208,13 +208,13 @@ GNU MDK has been tested in the following platforms:
 
 @itemize
 @item
-Debian GNU/Linux 2.2/2.3
+Debian GNU/Linux 2.2/2.3/3.0
 @item
 Redhat GNU/Linux 7.0 (Agustin Navarro), 6.2 (Roberto Ferrero)
 @item
 Mandrake 8.0 (Agustin Navarro)
 @item
-FreeBSD 4.2, 4.3 (Ying-Chieh Liao)
+FreeBSD 4.2, 4.3, 4.4, 4.5 (Ying-Chieh Liao)
 @item
 Solaris 2.8/gcc 2.95.3 (Stephen Ramsay)
 @item
@@ -225,6 +225,8 @@ Nathusius)@footnote{Caveats: Christoph has only tested @code{mixvm} and
 functionalities on a first try. If you find problems with
 history/readline functionality, please try a newer/manually installed
 readline version.}
+@item
+Mac OS X 10.1.2 (Johan Swanljung)
 @end itemize
 
 MDK will probably work on any GNU/Linux and BSD platform. If you try it
diff --git a/doc/mdk_mixvm.texi b/doc/mdk_mixvm.texi
index 2eae874..7992567 100644
--- a/doc/mdk_mixvm.texi
+++ b/doc/mdk_mixvm.texi
@@ -1,10 +1,10 @@
 @c -*-texinfo-*-
 @c This is part of the GNU MDK Reference Manual.
-@c Copyright (C) 2000, 2001
+@c Copyright (C) 2000, 2001, 2002
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_mixvm.texi,v 1.10 2001/09/26 23:15:55 jao Exp $
+@c $Id: mdk_mixvm.texi,v 1.11 2002/04/08 00:26:37 jao Exp $
 
 @node mixvm, gmixvm, mixasm, Top
 @comment  node-name,  next,  previous,  up
@@ -37,8 +37,8 @@ setting to aid you in debugging your code. For a tutorial description of
 for each available single letter switch):
 
 @example
-mixvm [-vhurdq] [--version] [--help] [--usage] [--run] [--dump]
-      [--noinit]  [FILE[.mix]]
+mixvm [-vhurdtq] [--version] [--help] [--usage] [--run] [--dump]
+      [--time] [--noinit]  [FILE[.mix]]
 @end example
 
 @noindent
@@ -73,6 +73,13 @@ comparison flag and overflow toggle after executing the program named
 @var{FILE}. See @xref{Non-interactive mode}, for sample usage.
 @end defopt
 
+@defopt -t
+@defoptx --time
+This option must be used in conjuction with @code{-r}, and tells
+@code{mixvm} to print virtual time statistics for the program's
+execution.
+@end defopt
+
 When run without the @code{-r} flag, @code{mixvm} enters its interactive
 mode, showing you a prompt like this one:
 
@@ -107,7 +114,8 @@ startup.
 
 You can enter the interactive mode of the MIX virtual machine by simply
 invoking @code{mixvm} without arguments. You will then presented a shell
-prompt 
+prompt@footnote{The default command prompt, @samp{MIX > }, can be
+changed using the @code{prompt} command (@pxref{Configuration commands})}
 
 @example
 MIX >
@@ -142,7 +150,7 @@ all available commands.
 * File commands::               Loading and executing programs.
 * Debug commands::              Debugging programs.
 * State commands::              Inspecting the virtual machine state.
-* Configuration commands::      Storing mixvm settings.
+* Configuration commands::      Changing and storing mixvm settings.
 * Scheme commands::             
 @end menu
 
@@ -712,6 +720,15 @@ specify an alternative location for storing these device files, while
 @code{pddir} prints the current device directory.
 @end deffn
 
+Finally, you can change the default command prompt, @samp{MIX > },
+using the @code{prompt} command:
+
+@deffn {config command} prompt PROMPT
+Changes the command prompt to @var{prompt}. If you want to include
+white space(s) at the end of the new prompt, bracket @var{prompt} using
+double quotes (e.g., @code{prompt ">> "}).
+@end deffn
+
 @node Scheme commands,  , Configuration commands, Commands
 @subsection Scheme commands
 
diff --git a/doc/mdk_tut.texi b/doc/mdk_tut.texi
index 461fcf6..c2b3ab1 100644
--- a/doc/mdk_tut.texi
+++ b/doc/mdk_tut.texi
@@ -4,7 +4,7 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_tut.texi,v 1.6 2002/03/19 22:38:13 jao Exp $
+@c $Id: mdk_tut.texi,v 1.7 2002/04/08 00:26:37 jao Exp $
 
 @node MIX and MIXAL tutorial, Getting started, Installing MDK, Top
 @comment  node-name,  next,  previous,  up
@@ -793,19 +793,20 @@ counter, while @samp{HLT} usually marks program termination.
 @cindex exection time
 @cindex time
 
-When writing MIXAL programs (or any kind of programs, for that matter),
-whe shall often be interested in their execution time. Loosely speaking,
-we will interested in the answer to the question: how long takes a
-program to execute? Of course, this execution time will be a function of
-the input size, and the answer to our question is commonly given as the
-asymptotic behaviour as a function of the input size. At any rate, to
-compute this asymptotic behaviour, we need a measure of how long
-execution of a single instruction takes in our (virtual) CPU. Therefore,
-each MIX instruction will have an associated execution time, given in
-arbitrary units (in a real computer, the value of this unit will depend
-on the hardware configuration). When our MIX virtual machine executes
-programs, it will give you the value of their execution time based upon
-the execution time of each single instruction.
+When writing MIXAL programs (or any kind of programs, for that
+matter), whe shall often be interested in their execution
+time. Loosely speaking, we will interested in the answer to the
+question: how long takes a program to execute? Of course, this
+execution time will be a function of the input size, and the answer to
+our question is commonly given as the asymptotic behaviour as a
+function of the input size. At any rate, to compute this asymptotic
+behaviour, we need a measure of how long execution of a single
+instruction takes in our (virtual) CPU. Therefore, each MIX
+instruction will have an associated execution time, given in arbitrary
+units (in a real computer, the value of this unit will depend on the
+hardware configuration). When our MIX virtual machine executes
+programs, it will (optionally) give you the value of their execution
+time based upon the execution time of each single instruction.
 
 In the following table, the execution times (in the above mentioned
 arbitrary units) of the MIX instructions are given.