From 750b5028a18de8a958db63849b5bae84180dad84 Mon Sep 17 00:00:00 2001
From: jaortega <jaortega>
Date: Wed, 1 Nov 2000 22:53:21 +0000
Subject:

---
 doc/.cvsignore         |    8 +
 doc/Makefile.am        |   15 +
 doc/gpl.texi           |  396 +++++++++++
 doc/html/.cvsignore    |   16 +
 doc/html/Makefile.am   |   14 +
 doc/html/download.html |  105 +++
 doc/html/index.html    |  104 +++
 doc/mdk.texi           | 1763 ++++++++++++++++++++++++++++++++++++++++++++++++
 8 files changed, 2421 insertions(+)
 create mode 100644 doc/.cvsignore
 create mode 100644 doc/Makefile.am
 create mode 100644 doc/gpl.texi
 create mode 100644 doc/html/.cvsignore
 create mode 100644 doc/html/Makefile.am
 create mode 100644 doc/html/download.html
 create mode 100644 doc/html/index.html
 create mode 100644 doc/mdk.texi

(limited to 'doc')

diff --git a/doc/.cvsignore b/doc/.cvsignore
new file mode 100644
index 0000000..26676b1
--- /dev/null
+++ b/doc/.cvsignore
@@ -0,0 +1,8 @@
+Makefile
+Makefile.in
+mdk.html
+mdk.info
+mdk.info-1
+mdk.info-2
+stamp-vti
+version.texi
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..754ab11
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,15 @@
+## Process this file with automake to produce Makefile.in
+
+# Copyright (C) 2000 jose antonio ortega ruiz <jaortega@retemail.es>
+#  
+# This file is free software; as a special exception the author gives
+# unlimited permission to copy and/or distribute it, with or without 
+# modifications, as long as this notice is preserved.
+# 
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+SUBDIRS = html
+info_TEXINFOS = mdk.texi
+mdk_TEXINFOS = gpl.texi
diff --git a/doc/gpl.texi b/doc/gpl.texi
new file mode 100644
index 0000000..5b0da1a
--- /dev/null
+++ b/doc/gpl.texi
@@ -0,0 +1,396 @@
+@setfilename gpl.info
+
+@unnumbered GNU GENERAL PUBLIC LICENSE
+@center Version 2, June 1991
+
+@display
+Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
+675 Mass Ave, Cambridge, MA 02139, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@unnumberedsec Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software---to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+@iftex
+@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end iftex
+@ifinfo
+@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end ifinfo
+
+@enumerate
+@item
+This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The ``Program'', below,
+refers to any such program or work, and a ``work based on the Program''
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term ``modification''.)  Each licensee is addressed as ``you''.
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+@item
+You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+@item
+You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+@enumerate a
+@item
+You must cause the modified files to carry prominent notices
+stating that you changed the files and the date of any change.
+
+@item
+You must cause any work that you distribute or publish, that in
+whole or in part contains or is derived from the Program or any
+part thereof, to be licensed as a whole at no charge to all third
+parties under the terms of this License.
+
+@item
+If the modified program normally reads commands interactively
+when run, you must cause it, when started running for such
+interactive use in the most ordinary way, to print or display an
+announcement including an appropriate copyright notice and a
+notice that there is no warranty (or else, saying that you provide
+a warranty) and that users may redistribute the program under
+these conditions, and telling the user how to view a copy of this
+License.  (Exception: if the Program itself is interactive but
+does not normally print such an announcement, your work based on
+the Program is not required to print an announcement.)
+@end enumerate
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+@item
+You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+@enumerate a
+@item
+Accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of Sections
+1 and 2 above on a medium customarily used for software interchange; or,
+
+@item
+Accompany it with a written offer, valid for at least three
+years, to give any third party, for a charge no more than your
+cost of physically performing source distribution, a complete
+machine-readable copy of the corresponding source code, to be
+distributed under the terms of Sections 1 and 2 above on a medium
+customarily used for software interchange; or,
+
+@item
+Accompany it with the information you received as to the offer
+to distribute corresponding source code.  (This alternative is
+allowed only for noncommercial distribution and only if you
+received the program in object code or executable form with such
+an offer, in accord with Subsection b above.)
+@end enumerate
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+@item
+You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+@item
+You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+@item
+Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+@item
+If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+@item
+If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+@item
+The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and ``any
+later version'', you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+@item
+If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+@iftex
+@heading NO WARRANTY
+@end iftex
+@ifinfo
+@center NO WARRANTY
+@end ifinfo
+
+@item
+BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+@item
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+@end enumerate
+
+@iftex
+@heading END OF TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center END OF TERMS AND CONDITIONS
+@end ifinfo
+
+@page
+@unnumberedsec How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the ``copyright'' line and a pointer to where the full notice is found.
+
+@smallexample
+@var{one line to give the program's name and an idea of what it does.}
+Copyright (C) 19@var{yy}  @var{name of author}
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+@end smallexample
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+@smallexample
+Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
+Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+type `show w'.  This is free software, and you are welcome
+to redistribute it under certain conditions; type `show c' 
+for details.
+@end smallexample
+
+The hypothetical commands @samp{show w} and @samp{show c} should show
+the appropriate parts of the General Public License.  Of course, the
+commands you use may be called something other than @samp{show w} and
+@samp{show c}; they could even be mouse-clicks or menu items---whatever
+suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a ``copyright disclaimer'' for the program, if
+necessary.  Here is a sample; alter the names:
+
+@smallexample
+@group
+Yoyodyne, Inc., hereby disclaims all copyright
+interest in the program `Gnomovision'
+(which makes passes at compilers) written 
+by James Hacker.
+
+@var{signature of Ty Coon}, 1 April 1989
+Ty Coon, President of Vice
+@end group
+@end smallexample
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Library General
+Public License instead of this License.
diff --git a/doc/html/.cvsignore b/doc/html/.cvsignore
new file mode 100644
index 0000000..b44cc40
--- /dev/null
+++ b/doc/html/.cvsignore
@@ -0,0 +1,16 @@
+Makefile
+Makefile.in
+doc.html
+mdk.html
+mdk_1.html
+mdk_2.html
+mdk_3.html
+mdk_4.html
+mdk_5.html
+mdk_6.html
+mdk_7.html
+mdk_8.html
+mdk_abt.html
+mdk_fot.html
+mdk_ovr.html
+mdk_toc.html
diff --git a/doc/html/Makefile.am b/doc/html/Makefile.am
new file mode 100644
index 0000000..ecd8550
--- /dev/null
+++ b/doc/html/Makefile.am
@@ -0,0 +1,14 @@
+## Process this file with automake to produce Makefile.in
+
+# Copyright (C) 2000 Jose Antonio Ortega Ruiz <jaortega@retemail.es>
+#  
+# This file is free software; as a special exception the author gives
+# unlimited permission to copy and/or distribute it, with or without 
+# modifications, as long as this notice is preserved.
+# 
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+EXTRA_DIST = index.html download.html
+
diff --git a/doc/html/download.html b/doc/html/download.html
new file mode 100644
index 0000000..0749404
--- /dev/null
+++ b/doc/html/download.html
@@ -0,0 +1,105 @@
+<!-- -*-html-*- -->
+<html>
+
+  <head>
+    <title>MDK download</title>
+  </head>
+
+  <body bgcolor="white" link="#ff0000" vlink="#a00000">
+    <a  name="top"></a>
+    <table  cellspacing="0" cellpadding="5" border="0" align="center">
+      <tr>
+        <td width="100" bgcolor="#696969">&nbsp;</td>
+        <td bgcolor="#696969" width="600" align="center"> 
+           <font color="white"><b>MDK download</b></font>
+	</td>
+	<td bgcolor="#696969" width="10">&nbsp;</td>
+      </tr>
+      <tr>
+        <td colspan="2">&nbsp;</td>
+	<td bgcolor="#696969" >&nbsp;</td>
+      </tr>
+      <tr>
+        <td  bgcolor="#909090" valign="top">
+	  <br>
+	  <a href="index.html">MDK home</a><br>
+	  <a href="mdk.html">Documentation</a><br>
+	  <a href="http://sourceforge.net/projects/mdk">
+	    MDK at SourceForge</a><br>
+	  <a href="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/?cvsroot=mdk">
+	    CVS repository</a><br><br>
+	  <p align="center">Thanks to<br>
+	  <A href="http://sourceforge.net"> 
+          <IMG src="http://sourceforge.net/sflogo.php?group_id=13897&type=1"
+	       width="88" height="31" border="0"
+               alt="SourceForge Logo"> </A> 
+	</td>
+        <td >
+	  <p align="right"><font color="#000069" size="+1">
+           Download
+	  </font></p>
+	  <p>The latest version (0.1) source tarball is available for
+	  download <a href="http://sourceforge.net/projects/mdk">here.</a></p>
+	  <p>A tarball containing the HTML documentation is available
+          <a href="mdk-doc.tar.gz">here.</a></p>
+	  <p align="right"><font color="#000069" size="+1">
+           <a name="reqs">Requirements</a>
+	  </font></p>
+	  MDK is written in ANSI C and uses the following libraries:
+	  <ul>
+	    <li>GNU readline and history
+	    <li><a href="http://www.gnu.org/software/flex/flex.html">
+	         GNU Flex</a>, version 2.3 or latter
+            <li><a href="http://www.gtk.org">glib</a>, version 1.2.0 or latter
+	  </ul>
+	  These libraries are fairly common in any GNU/Linux distribution
+	  (MDK is developed on a <a href="www.debian.org">Debian 2.3</a>
+          box). Although I haven't tested it, MDK should be also installable
+	  on BSD operating systems such as FreeBSD if the above libraries
+          are installed. Please, 
+	  <a href="mailto:jaortega@acm.org">drop me</a> a line if you install
+	  MDK, and I'll add your platform to the list of supported ones.
+	  <p align="right"><font color="#000069" size="+1">
+           Installation
+	  </font></p>
+	  MDK uses autoconf/automake, so that compilation and installation
+	  should follow the typical uncompress, configure, make, install cycle.
+	  First, uncompress the source tarball using:
+	  <pre>
+    tar xvfz mdk-latest.tar.gz
+          </pre>
+	  This will create a folder named mdk-X.Y (where X.Y stands for
+	  the version you downloaded, e.g., 0.1). To build the MDK tools,
+	  enter this folder and type
+	  <pre>
+    ./configure
+    make
+          </pre>
+	  Finally, to install the binaries and documentation, type, as root
+          <pre>
+    make install
+          </pre>
+	  See the file named INSTALL in the source folder for fine tuning 
+          of build and installation options.
+	  <p align="right">
+	   Contact the <a href="mailto:jaortega@acm.org">author.</a>
+	  </p>
+        </td>
+	<td bgcolor="#696969" >&nbsp;</td>
+      </tr>
+      <tr>
+        <td bgcolor="#909090">&nbsp;</td>
+        <td colspan="2">&nbsp;</td>
+      </tr>
+      <tr>
+        <td bgcolor="#909090">&nbsp;</td>
+        <td colspan="2" bgcolor="#909090" align="right">
+	  &nbsp;
+	</td>
+      </tr>
+    </table>
+    
+  </body>
+</html>
+
+
diff --git a/doc/html/index.html b/doc/html/index.html
new file mode 100644
index 0000000..f4d4549
--- /dev/null
+++ b/doc/html/index.html
@@ -0,0 +1,104 @@
+<!-- -*-html-*- -->
+<html>
+
+  <head>
+    <title>MIX Development Kit</title>
+  </head>
+
+  <body bgcolor="white" link="#ff0000" vlink="#a00000">
+    <a  name="top"></a>
+    <table  cellspacing="0" cellpadding="5" border="0" align="center">
+      <tr>
+        <td width="100" bgcolor="#696969">&nbsp;</td>
+        <td bgcolor="#696969" width="600" align="center"> 
+           <font color="white"><b>MDK, the MIX development kit</b></font>
+	</td>
+	<td bgcolor="#696969" width="10">&nbsp;</td>
+      </tr>
+      <tr>
+        <td colspan="2">&nbsp;</td>
+	<td bgcolor="#696969" >&nbsp;</td>
+      </tr>
+      <tr>
+        <td  bgcolor="#909090" valign="top">
+	  <br>
+	  <a href="download.html">Download</a><br>
+	  <a href="mdk.html">Documentation</a><br>
+	  <a href="http://sourceforge.net/projects/mdk">
+	    MDK at SourceForge</a><br>
+	  <a href="http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/?cvsroot=mdk">
+	    CVS repository</a><br><br>
+	  <p align="center">Thanks to<br>
+	  <A href="http://sourceforge.net"> 
+          <IMG src="http://sourceforge.net/sflogo.php?group_id=13897&type=1"
+	       width="88" height="31" border="0"
+               alt="SourceForge Logo"> </A> 
+	</td>
+        <td >
+	  <p align="right"><font color="#000069" size="+1">
+           What is the MIX?
+	  </font></p>
+	  <b>MIX</b> is Donald Knuth's mythical computer as described
+	  in his monumental work <a
+	  href="http://Sunburn.Stanford.EDU/~knuth/taocp.html"> The
+	  Art Of Computer Programming</a>. As any of its real
+	  counterparts, the MIX features registers, memory cells, an
+	  overflow toggle, comparison flags, input-output devices, and
+	  a set of binary instructions executable by its virtual
+	  CPU. You can programme the MIX using an assembly language
+	  called <b>MIXAL</b>, the MIX Assembly Language.  <p> So,
+	  what's the use of learning MIXAL? Well, if you're interested
+	  in programming, please buy, borrow or steal a copy of TAOCP,
+	  and you'll see the use.  
+	  &nbsp;<br>&nbsp;<br>
+	  <p align="right"><font color="#000069" size="+1">
+            What is the MDK?
+	  </font></p> 
+	  The <b>M</b>IX <b>D</b>evelopment <b>K</b>it offers an emulation of
+	  <b>MIX</b> and <b>MIXAL</b>. The <a href="download.html">
+	  current version</a> of MDK includes two applications:
+	  <ul>
+	    <li><b><i>mixasm</i></b> A MIXAL compiler, which
+	    translates your source files into binary ones, executable
+	    by the MIX virtual machine.
+            <li><b><i>mixvm</i></b> A MIX virtual machine which is
+	    able to run and debug compiled MIXAL programs, using a
+	    command line interface with readline's line editting
+	    capabilities.
+	  </ul>
+	  Using the MDK tools, you'll be able to
+	  <ul>
+	    <li>write, compile and execute MIXAL programs,
+	    <li>set breakpoints and run your programs step by step,
+	    <li>inspect and modify the MIX registers, flags and memory
+	    contents at any step,
+	    <li>simulate MIX input-output devices using the standard
+	    output and your file system.
+	  </ul>
+	  See the MDK <a href="mdk.html">user's manual</a> for a complete
+	  description of the toolkit.
+	  The MDK utils will run on any GNU/Linux box (see
+	  <a href="download.html#reqs">requirements</a>) and, of course, are
+	  <a href="http://www.gnu.org/copyleft/gpl.html">free software</a>.
+	  <p align="right">
+	   Contact the <a href="mailto:jaortega@acm.org">author.</a>
+	  </p>
+        </td>
+	<td bgcolor="#696969" >&nbsp;</td>
+      </tr>
+      <tr>
+        <td bgcolor="#909090">&nbsp;</td>
+        <td colspan="2">&nbsp;</td>
+      </tr>
+      <tr>
+        <td bgcolor="#909090">&nbsp;</td>
+        <td colspan="2" bgcolor="#909090" align="right">
+	  &nbsp;
+	</td>
+      </tr>
+    </table>
+    
+  </body>
+</html>
+
+
diff --git a/doc/mdk.texi b/doc/mdk.texi
new file mode 100644
index 0000000..47dc6b9
--- /dev/null
+++ b/doc/mdk.texi
@@ -0,0 +1,1763 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename mdk.info
+@settitle MIX Development Kit (mdk)
+@finalout
+@setchapternewpage odd
+@c %**end of header
+
+@include version.texi
+@set JAO Jos@'e Antonio Ortega Ruiz
+@footnotestyle separate
+
+@ifinfo
+This file documents the the @sc{mdk} utilities for developing
+programs using Donald Knuth's MIX language.
+
+Copyright (C) 2000 @value{JAO}
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+sections entitled ``Copying'' and ``GNU General Public License'' are
+included exactly as in the original, and provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation
+approved by the Free Software Foundation.
+@end ifinfo
+
+@titlepage
+@title MDK
+@subtitle MIX Development Kit
+@subtitle Edition @value{EDITION}, for @sc{mdk} Version @value{VERSION}
+@subtitle @value{UPDATED}
+@author by @value{JAO}
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 2000 @value{JAO}
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+sections entitled ``Copying'' and ``GNU General Public License'' are
+included exactly as in the original, and provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation
+approved by the Free Software Foundation.
+@end titlepage
+
+@node Top, Introduction, (dir), (dir)
+
+@ifinfo
+This file documents the @sc{mdk} utilities to develop programs
+using Donald Knuth's MIXAL language.  MIXAL is an assembler-like
+language for writing programs for the (virtual) MIX computer. They are
+described in the first volume of @cite{The Art of Computer Programming}
+by D. Knuth (Addison Wesley, 1997), and used throughout the (up to now)
+three published volumes.
+
+@sc{mdk} was written by @value{JAO} and is released under the GNU
+General Public license (@pxref{Copying}), so that users are free to share
+and change it.
+
+@end ifinfo
+
+@menu
+* Introduction::                
+* MIX and MIXAL overview::      Quick tutorial of Knuth's MIX computer.
+* Getting started::             Basic usage of the @sc{mdk} tools.
+* mixvm::                       Invoking the MIX virtual machine.
+* mixasm::                      Invoking the MIXAL assembler.
+* Copying::                     @sc{mdk} licensing terms.
+* Problems::                    Reporting bugs.
+* Concept Index::               Index of concepts.
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+MIX and MIXAL overview
+
+* The MIX computer::            Architecture and instruction set 
+                                of the MIX computer.
+* MIXAL::                       The MIX assembly language.
+
+The MIX computer
+
+* MIX architecture::            
+* MIX instruction set::         
+
+MIX instruction set
+
+* Loading operators::           
+* Storing operators::           
+* Arithmetic operators::        
+* Address transfer operators::  
+* Comparison operators::        
+* Jump operators::              
+* Miscellaneous operators::     
+* Input-output operators::      
+* Conversion operators::        
+
+MIXAL
+
+* Instructions::                
+* Comments::                    
+* Expressions::                 
+* Local symbols::               
+* Miscellaneous::               
+
+Getting started
+
+* Writing a source file::       A sample MIXAL source file.
+* Compiling::                   Using @code{mixasm} to compile source
+                                files into binary format.
+* Running the program::         Running and debugging your program.
+
+Running the program
+
+* Non-interactive mode::        Running your programs non-interactively.
+* Interactive mode::            Running programs interactively.
+* Debugging::                   Commands for debugging your programs.
+
+@code{mixvm}, the MIX computer simulator
+
+* Invocation::                  Options when invoking @code{mixvm}.
+* Commands::                    Commands available in interactive mode.
+* Devices::                     MIX block devices implementation.
+
+@code{mixasm}, the MIXAL assembler
+
+* Invoking @code{mixasm}::      @code{mixasm} options
+
+@end detailmenu
+@end menu
+
+@node Introduction, MIX and MIXAL overview, Top, Top
+@comment  node-name,  next,  previous,  up
+@unnumbered Introduction
+@cindex Introduction
+
+In his book series @cite{The Art of Computer Programming} (published by
+Addison Wesley), D. Knuth uses an imaginary computer, the MIX, and its
+associated machine-code and assembly languages to ilustrate the
+concepts and algorithms as they are presented. 
+
+The MIX's architecture is a simplified version of those found in real
+CSIC CPUs, and the MIX assembly language provides a set of primitives
+that will be very familiar to any person with a minimum experience in
+assembly programming. The MIX/MIXAL definition is powerful and complete
+enough to provide a virtual development platform for writing quite
+complex programs, and close enough to real computers to be worth using
+when learning programming techniques. At any rate, if you want to read
+and learn from Knuth excellent books on computer programming, a MIX
+development environment would come in handy.
+
+The @sc{mdk} package aims at providing such virtual development
+environment on a GNU box. Thus, @sc{mdk} offers you a set of utilities
+to simulate the MIX computer and to write, compile, run and debug MIXAL
+programs. As of version @value{VERSION}, @sc{mdk} includes
+the following programs:
+
+@table @code
+@item mixvm
+MIX virtual machine. Emulation of the MIX computer.
+@item mixasm
+MIXAL assembler. Assembler which translates MIXAL source files into
+programs that can be run (and debugged) by @code{mixvm}.
+@end table 
+
+@code{mixvm} implements a simulator of the MIX computer, giving you a
+virtual machine for executing and debugging MIX programs. These binary
+programs could be written by hand, but it is easier to produce them
+compiling MIXAL source files, using the MIXAL assembler @code{mixasm}.
+
+This manual gives you a brief survey of MIX and MIXAL, and a thorough
+description of the use of the @sc{mdk} utilities.
+
+
+
+@node MIX and MIXAL overview, Getting started, Introduction, Top
+@comment  node-name,  next,  previous,  up
+@chapter MIX and MIXAL overview
+@cindex MIX
+@cindex MIXAL
+
+In the book series @cite{The Art of Computer Programming}, by D. Knuth,
+a virtual computer, the MIX, is used by the author, together with the
+set of binary instructions that the virtual CPU accepts, in the example
+programs and exercises. Like any other real computer, there is a
+symbolic assembler language that can be used to program the MIX: the MIX
+assembly language, or MIXAL for short. The MIX computer architecture and
+the MIXAL language are defined in volume 1 of the series,
+@cite{Fundamental Algorithms}. In the following subsections you will
+find a brief survey of these topics, which is not meant to replace the
+precise description given in the book (if you are interested in using
+the @sc{mdk} utilities, most probably the reason is that you have access
+to a copy of TAOCP), but to serve as a quick reminder of key points and
+nomenclature used in the rest of this manual.
+
+@menu
+* The MIX computer::            Architecture and instruction set 
+                                of the MIX computer.
+* MIXAL::                       The MIX assembly language.
+@end menu
+
+@node The MIX computer, MIXAL, MIX and MIXAL overview, MIX and MIXAL overview
+@comment  node-name,  next,  previous,  up
+@section The MIX computer
+
+In this section, you will find a brief description of the MIX computer,
+its components and instruction set.
+
+@menu
+* MIX architecture::            
+* MIX instruction set::         
+@end menu
+
+@node MIX architecture, MIX instruction set, The MIX computer, The MIX computer
+@comment  node-name,  next,  previous,  up
+@subsection MIX architecture
+@cindex byte
+@cindex MIX byte
+@cindex word
+@cindex MIX word
+@cindex MIX architecture
+@cindex MIX computer
+@cindex register
+@cindex MIX register
+@cindex field specification
+@cindex fspec
+@cindex instruction
+@cindex MIX instruction
+@cindex address
+@cindex memory cell
+@cindex cell
+@cindex memory
+@cindex index
+
+The basic information storage unit in the MIX computer is the
+@dfn{byte}, which stores positive values in the range 0-63 . Note that a
+MIX byte can be then represented as 6 bits, instead of the common 8 bits
+for a @emph{regular} byte. Unless otherwise stated, we shall use the
+word @dfn{byte} to refer to a MIX 6-bit byte.
+
+A MIX @dfn{word} is defined as a set of 5 bytes plus a sign. The bytes
+within a word are numbered for 1 to 5, being byte number one the most
+significant one. The sign is denoted by index 0. Graphically,
+
+@example
+ -----------------------------------------------
+|   0   |   1   |   2   |   3   |   4   |   5   |
+ -----------------------------------------------
+|  +/-  | byte  | byte  | byte  | byte  | byte  |     
+ -----------------------------------------------
+@end example
+
+You can refer to subfields within a word using a
+@dfn{field specification} or @dfn{fspec} of the form @samp{(L:R)}, where
+@samp{L} denotes the first byte and @samp{R} the last byte of the
+subfield. When @samp{L} is zero, the subfield includes the word's
+sign. An fspec can be also represented as a single value @samp{F}, given
+by @code{F = 8*L + R}.
+
+The MIX computer stores information in @dfn{registers}, that can store
+either a word or two bytes and sign (see below), and @dfn{memory cells},
+each one containing a word. Specifically, the MIX computer has 4000
+memory cells with addresses 0 to 3999 (i.e., two bytes are enough to
+address a memory cell) and the following registers:
+
+@table @samp
+@item rA
+A register. General purpose register holding a word. Usually its
+contents serves as operator for arithmetic and storing instructions.
+@item rX
+X register. General purpose register holding a word. Often it acts as an
+extension or a replacement of @samp{rA}.
+@item rJ
+J (jump) register. This register stores positive two-byte values,
+usually representing a jump address.
+@item rI[1-6]
+Index registers. These six registers can store a signed two-byte
+value. Their contents is used as indexing values for the computation of
+an effective memory address.
+@end table
+
+@cindex @sc{ov}
+@cindex @sc{cm}
+@cindex @samp{Un}
+@cindex overflow toggle
+@cindex comparison indicator
+@cindex input-output devices
+@noindent
+In addition, the MIX computer contains:
+
+@itemize @minus
+@item
+An @dfn{overflow toggle} (a single bit with values @dfn{on} or
+@dfn{off}). In this manual, this toggle is denoted @sc{ov}.
+@item
+A @dfn{comparison indicator} (having three values: @dfn{EQUAL},
+@dfn{GREATER} or @dfn{LESS}). In this manual, this indicator is denoted
+@sc{cm}.
+@item
+Input-output devices. Each device is labelled as @samp{Un}, where
+@samp{n} runs from 0 to 19@footnote{@samp{U0-7} are magnetic tape units,
+@samp{U8-15} are disks and drums, @samp{U16} is a card reader,
+@samp{U17} is a card writer, @samp{U18} is a line printer and
+@samp{U19}, a paper tape.}.
+@end itemize
+
+MIX @dfn{instructions} are codified as words with the following subfield
+structure:
+
+@multitable @columnfractions .15 .20 .65
+@item @emph{Subfield} @tab @emph{fspec} @tab @emph{Description}
+
+@item ADDRESS @tab (0:2)
+@tab The first two bytes plus sign are the @dfn{address} field. Combined
+with the INDEX field, denotes the memory address to be used by the
+instruction.
+@item INDEX @tab (3:3) @tab
+The third byte is the @dfn{index}, normally used for indexing the
+address@footnote{The actual memory address the instruction refers to, is
+obtained by adding to ADDRESS the value of the @samp{rI} register
+denoted by INDEX.}.
+@item MOD @tab (4:4) @tab
+Byte four is used either as an operation code modifier or as a field
+specification.
+@item OPCODE @tab (5:5) @tab
+The last (least significant) byte in the word denotes the operation
+code.
+@end multitable
+
+@noindent
+or, graphically,
+
+@example
+ ------------------------------------------------
+|   0   |   1   |   2   |   3   |   4   |   5    |
+ ------------------------------------------------
+|        ADDRESS        | INDEX |  MOD  | OPCODE |     
+ ------------------------------------------------
+@end example
+
+The MIX computer understands a quite complete set of instructions
+commonly found in real computers, including arithmetic, logical,
+storing, comparison and jump instructions. We refer the reader to
+D. Knuth's TAOCP (volume 1, section 1.3.1) for a complete description of
+these instructions. @xref{MIX instruction set}, gives a quick synopsis
+of the available instructions.
+
+@node MIX instruction set,  , MIX architecture, The MIX computer
+@comment  node-name,  next,  previous,  up
+@subsection MIX instruction set
+@cindex instruction set
+
+The following subsections summarize the instruction set of the MIX
+computer. In this description @samp{M} stands for
+the memory address obtained after indexing the ADDRESS subfield of the
+instruction (using its INDEX byte), and @samp{V} is the contents of the
+subfield indicated by MOD of the memory cell with address @samp{M}.
+
+@menu
+* Loading operators::           
+* Storing operators::           
+* Arithmetic operators::        
+* Address transfer operators::  
+* Comparison operators::        
+* Jump operators::              
+* Miscellaneous operators::     
+* Input-output operators::      
+* Conversion operators::        
+@end menu
+
+@node Loading operators, Storing operators, MIX instruction set, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Loading operators
+@cindex loading operators
+
+The following instructions are used to load memory contents into a
+register.
+
+@ftable @code
+@item LDA
+Load rA. OPCODE = 8, MOD = fspec. @code{rA <- V}.
+@item LDX
+Load rX. OPCODE = 15, MOD = fspec. @code{rX <- V}.
+@item LDi
+Load rIi. OPCODE = 8 + i, MOD = fspec. @code{rIi <- V}.
+@item LDAN
+Load rA negative. OPCODE = 16, MOD = fspec. @code{rA <- -V}.
+@item LDXN
+Load rX negative. OPCODE = 23, MOD = fspec. @code{rX <- -V}.
+@item LDiN
+Load rIi negative. OPCODE = 16 + i, MOD = fspec. @code{rIi <- -V}.
+@end ftable
+
+
+@node Storing operators, Arithmetic operators, Loading operators, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Storing operators
+@cindex storing operators
+
+The following instructions are used to store a subfield of a register
+into a memory location.
+
+@ftable @code
+@item STA
+Store rA. OPCODE = 24, MOD = fspec. @code{V <- rA}.
+@item STX
+Store rX. OPCODE = 31, MOD = fspec. @code{V <- rX}.
+@item STi
+Store rIi. OPCODE = 24 + i, MOD = fspec. @code{V <- rIi}.
+@item STJ
+Store rJ. OPCODE = 32, MOD = fspec. @code{V <- rJ}.
+@item STZ
+Store zero. OPCODE = 33, MOD = fspec. @code{V <- 0}.
+@end ftable
+
+
+@node Arithmetic operators, Address transfer operators, Storing operators, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Arithmetic operators
+@cindex arithmetic operators
+
+The following instructions perform arithmetic operations between rA and
+rX register and memory contents.
+
+@ftable @code
+@item ADD
+Add and set OV if overflow. OPCODE = 1, MOD = fspec. 
+@code{rA <- rA +V}.
+@item SUB
+Sub and set OV if overflow. OPCODE = 2, MOD = fspec.
+@code{rA <- rA - V}.
+@item MUL
+Multiply V times rA and store the 10-bytes product in rAX.
+OPCODE = 3, MOD = fspec. @code{rAX <- rA x V}.
+@item DIV
+rAX is considered a 10-bytes number, and it is divided by V.
+OPCODE = 4, MOD = fspec. @code{rA <- rAX / V}, @code{rX} <- reminder.
+@end ftable
+
+@node Address transfer operators, Comparison operators, Arithmetic operators, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Address transfer operators
+@cindex address transfer operators
+
+In these instructions, M (the address of the instruction after indexing)
+is used as a number instead of as the address of a memory cell.
+
+@ftable @code
+@item ENTA
+Enter rA. OPCODE = 48, MOD = 2. @code{rA <- M}.
+@item ENTX
+Enter rX. OPCODE = 55, MOD = 2. @code{rX <- M}.
+@item ENTi
+Enter rIi. OPCODE = 48 + i, MOD = 2. @code{rIi <- M}.
+@item ENNA
+Enter negative rA. OPCODE = 48, MOD = 3. @code{rA <- -M}.
+@item ENNX
+Enter negative rX. OPCODE = 55, MOD = 3. @code{rX <- -M}.
+@item ENNi
+Enter negative rIi. OPCODE = 48 + i, MOD = 3. @code{rIi <- -M}.
+@item INCA
+Increase rA. OPCODE = 48, MOD = 0. @code{rA <- rA + M}.
+@item INCX
+Increase rX. OPCODE = 55, MOD = 0. @code{rX <- rX + M}.
+@item INCi
+Increase rIi. OPCODE = 48 + i, MOD = 0. @code{rIi <- rIi + M}.
+@item DECA
+Decrease rA. OPCODE = 48, MOD = 1. @code{rA <- rA - M}.
+@item DECX
+Decrease rX. OPCODE = 55, MOD = 0. @code{rX <- rX - M}.
+@item DECi
+Decrease rIi. OPCODE = 48 + i, MOD = 0. @code{rIi <- rIi - M}.
+@end ftable
+
+
+@node Comparison operators, Jump operators, Address transfer operators, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Comparison operators
+@cindex comparison operators
+
+The following instructions compare the value of a register with V, and
+set the CM indicator to the result of the comparison.
+
+@ftable @code
+@item CMPA
+Compare rA with V. OPCODE = 56, MOD = fspec.
+@item CMPX
+Compare rX with V. OPCODE = 63, MOD = fspec.
+@item CMPi
+Compare rIi with V. OPCODE = 56 + i, MOD = fspec.
+@end ftable
+
+@node Jump operators, Miscellaneous operators, Comparison operators, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Jump operators
+@cindex jump operators
+
+The following instructions provoke jumps by setting the program
+counter (address of the next instruction to fetch) to M (if a condition
+is met). If a jump occurs, the value of the next instruction address
+that would have been fetched in the absence of the jump is stored in rJ
+(except for @code{JSJ}).
+
+@ftable @code
+@item JMP
+Unconditional jump. OPCODE = 39, MOD = 0.
+@item JSJ
+Unconditional jump, but rJ is not modified. OPCODE = 39, MOD = 1.
+@item JOV
+Jump if OV is set (and turn it off). OPCODE = 39, MOD = 2.
+@item JNOV
+Jump if OV is not set (and turn it off). OPCODE = 39, MOD = 3.
+@item JL
+@itemx JE
+@itemx JG
+@itemx JGE
+@itemx JNE
+@itemx JLE
+Jump according to the value of CM. OPCODE = 39, MOD = 4, 5, 6, 7, 8, 9.
+@item JAN
+@itemx JAZ
+@itemx JAP
+@itemx JANN
+@itemx JANZ
+@itemx JANP
+Jump if the contents of rA is, respectively, negative, zero, positive,
+non-negative, non-zero or non-positive. 
+OPCODE = 40, MOD = 0, 1, 2, 3, 4, 5.
+@item JXN
+@itemx JXZ
+@itemx JXP
+@itemx JXNN
+@itemx JXNZ
+@itemx JXNP
+Jump if the contents of rX is, respectively, negative, zero, positive,
+non-negative, non-zero or non-positive. 
+OPCODE = 47, MOD = 0, 1, 2, 3, 4, 5.
+@item JiN
+@itemx JiZ
+@itemx JiP
+@itemx JiNN
+@itemx JiNZ
+@itemx JiNP
+Jump if the contents of rIi is, respectively, negative, zero, positive,
+non-negative, non-zero or non-positive. 
+OPCODE = 40 + i, MOD = 0, 1, 2, 3, 4, 5.
+@end ftable
+
+@node Miscellaneous operators, Input-output operators, Jump operators, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Miscellaneous operators
+@cindex miscellaneous operators
+
+@ftable @code
+@item SLA
+@itemx SRA
+@itemx SLAX
+@itemx SRAX
+@itemx SLC
+@itemx SRC
+Shift rA or rAX left, right, or rAX circularly left or right. M
+specifies the number of bytes to be shifted.
+OPCODE = 6, MOD = 0, 1, 2, 3, 4, 5.
+@item MOVE
+Move MOD words from M to the location stored in rI1.
+OPCODE = 7, MOD = no. of bytes.
+@item NOP
+No operation. OPCODE = 0, MOD = 0.
+@item HLT
+Halt. Stops instruction fetching. OPCODE = 5, MOD = 2.
+@end ftable
+
+@node Input-output operators, Conversion operators, Miscellaneous operators, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Input-output operators
+@cindex input-output operators
+
+The following instructions perform input-output operations. 
+
+@ftable @code
+@item IN
+Transfer a block of words from the specified unit to memory, starting at
+address M.
+OPCODE = 36, MOD = I/O unit.
+@item OUT
+Transfer a block of words from memory (starting at address M) to the
+specified unit.
+OPCODE = 37, MOD = I/O unit.
+@item IOC
+Perfom a control operation (given by M) on the specified unit.
+OPCODE = 35, MOD = I/O unit.
+@item JRED
+Jump to M if the specified unit is ready.
+OPCODE = 38, MOD = I/O unit.
+@item JBUS
+Jump to M if the specified unit is busy.
+OPCODE = 34, MOD = I/O unit.
+@end ftable
+
+@node Conversion operators,  , Input-output operators, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Conversion operators
+@cindex conversion operators
+
+The following instructions convert between numerical values and their
+character representations.
+
+@ftable @code
+@item NUM
+Convert rAX, assumed to contain a character representation of a number,
+to its numerical value and store it in rA.
+OPCODE = 5, MOD = 0.
+@item CHAR
+Convert the number stored in rA to a character representation and store
+it in rAX.
+OPCODE = 5, MOD = 1.
+@end ftable
+
+@node MIXAL,  , The MIX computer, MIX and MIXAL overview
+@comment  node-name,  next,  previous,  up
+@section MIXAL
+@cindex MIXAL
+@cindex MIX assembly language
+@cindex assembly
+
+The MIX computer can be programmed using an assembly language, MIXAL,
+which provides a symbolic way of writing the binary instructions
+understood by the imaginary MIX computer. If you have used assembler
+languages before, you will find MIXAL a very familiar language. MIXAL is
+fully described in volume 1 of D. Knuth's TAOCP. This section is not
+meant as a replacement of the book's description, but as a brief survey
+of MIXAL.
+
+@menu
+* Instructions::                
+* Comments::                    
+* Expressions::                 
+* Local symbols::               
+* Miscellaneous::               
+@end menu
+
+@node Instructions, Comments, MIXAL, MIXAL
+@comment  node-name,  next,  previous,  up
+@subsection Instructions
+@cindex MIXAL instructions
+@cindex instructions
+@cindex instruction parts
+
+MIX instructions are written in MIXAL according to the following
+pattern:
+
+@example
+[LABEL]   OPCODE  [OPERAND]   [COMMENT]
+@end example
+
+@noindent
+where @samp{OPERAND} is of the form
+
+@example
+[ADDRESS][,INDEX][(MOD)]
+@end example
+
+Items between square brackets are optional, and
+
+@table @code
+@item LABEL
+Is an alphanumeric identifier (a @dfn{symbol}) which gets the value of
+the current compilation address, and can be used in subsequent
+expressions.
+@item OPCODE
+Is a literal denoting the operation code of the instruction
+(e.g. @code{LDA}, @code{STA}) or an assembly pseudoinstruction
+(e.g. @code{ORG}, @code{EQU}).
+@item ADDRESS
+Expression evaluating to the address subfield of the instruction.
+@item INDEX
+Expression evaluating to the index subfield of the instruction. It
+defaults to 0 (i.e., no use of indexing) and can only be used when 
+@code{ADDRESS} is present.
+@item MOD
+Expression evaluating to the mod subfield of the instruction. Its
+default value, when omitted, depends on @code{OPCODE}.
+@item COMMENT
+Any number of spaces after the operand mark the beggining of a comment,
+i.e. any text separated by white space from the operand is ignored by
+the assembler (note that spaces are not allowed within the
+@samp{OPERAND} field).
+@end table
+
+Note that spaces are @emph{not} allowed between the @code{ADDRESS},
+@code{INDEX} and @code{MOD} fields if they are present. White space is
+used to separate the label, operation code and operand parts of the
+instruction@footnote{In fact, Knuth's definition of MIXAL restricts the
+column number at which each of these instruction parts must start. The
+MIXAL assembler included in @sc{mdk}, @code{mixasm}, does not impose
+such restriction.}.
+
+MIXAL instructions can be either one of the MIX machine instructions
+(@pxref{MIX instruction set}) or one of the following assembly
+pseudoinstructions:
+
+@ftable @code
+@item ORIG
+Sets the value of the memory address to which following instructions
+will be allocated after compilation.
+@item EQU
+Used to define a symbol's value, e.g. @w{@code{SYM  EQU  2*200/3}}.
+@item CON
+The value of the given expression is copied directly into the current
+memory address.
+@item ALF
+Takes as operand five characters, constituting the five bytes of a word
+which is copied directly into the current memory address.
+@item END
+Marks the end of the program. Its operand gives the start address for
+program execution.
+@end ftable
+
+Sample MIXAL instructions are
+
+@example
+HERE     LDA  2000
+         LDX  HERE,2(1:3)  this is a comment
+         JMP  1234
+NEXT     STA  HERE*2(8)
+         ORG  4000
+VALUE    EQU  NEXT+HERE//2
+@end example
+
+@node Comments, Expressions, Instructions, MIXAL
+@comment  node-name,  next,  previous,  up
+@subsection Comments
+@cindex comments
+
+Any line starting with an asterisk is treated as a comment and ignored
+by the assembler.
+
+@example
+* This is a comment: this line is ignored.
+    * This line is an error: * must be in column 1.
+@end example
+
+As noted in the previous section, comments can also be located after the
+@samp{OPERAND} field of an instruction, separated from it by white
+space, as in
+
+@example
+LABEL     LDA   100  This is also a comment
+@end example
+
+@node Expressions, Local symbols, Comments, MIXAL
+@comment  node-name,  next,  previous,  up
+@subsection Expressions
+@cindex operator
+@cindex binary operator
+@cindex unary operator
+The @code{ADDRESS}, @code{INDEX} and @code{MOD} fields of a MIXAL
+instruction can be expressions, formed by numbers, identifiers and
+binary operators (@code{+ - * / // :}). @code{+} and @code{-} can also
+be used as unary operators. Order of evaluation is from left to right:
+there is no other operator precedence rule, and parentheses cannot be
+used for grouping. A stand-alone asterisk denotes the current memory
+location; thus, for instance,
+
+@example
+     4+2**
+@end example
+
+@noindent
+evaluates to 4 plus two times the current memory location. White space
+is not allowed within expressions.
+
+All symbols appearing within an expression must be defined. Future
+references are only allowed when appearing stand-alone (or modified by
+an unary operator) in the @code{ADDRESS} part of a MIXAL instruction,
+e.g.
+
+@example
+* OK: stand alone future reference 
+         STA  -S1(1:5)
+* ERROR: future reference in expression
+         LDX  2-S1
+S1       LD1  2000
+@end example
+
+@node Local symbols, Miscellaneous, Expressions, MIXAL
+@comment  node-name,  next,  previous,  up
+@subsection Local symbols
+@cindex local symbols
+
+Besides user defined symbols, MIXAL programmers can use the so called
+@dfn{local symbols}, which are symbols of the form @code{[1-9][HBF]}. A
+local symbol @code{nB} refers to the address of the last previous
+occurrence of @code{nH} as a label, while @code{nF} refers to the next
+@code{nH} occurrence. Unlike user defined symbols, @code{nH} can appear
+multiple times in the @code{LABEL} part of different MIXAL
+instructions. The following code shows an instance of local symbols'
+usage:
+
+@example
+* line 1
+1H    LDA  100
+* line 2: 1B refers to address of line 1, 3F refers to address of line 4
+      STA  3F,2(1B//2)
+* line 3: redefinition of 1H
+1H    STZ
+* line 4: 1B refers to address of line 3
+3H    JMP  1B
+@end example
+
+@node Miscellaneous,  , Local symbols, MIXAL
+@comment  node-name,  next,  previous,  up
+@subsection Miscellaneous
+@cindex literal constants
+
+MIXAL allows the introduction of @dfn{literal constants}, which are
+automatically stored in memory addresses after the end of the program by
+the assembler. Literal constants are denoted as @code{=exp=}, where
+@code{exp} is an expression. For instance, the code
+
+@example
+L         EQU   10
+          LDA   =20-L=
+@end example
+
+causes the assembler to add after the program's end an instruction with
+contents 10, and to assemble the above code as the instruction @w{@code{
+LDA a}}, where @code{a} stands for the address in which the value 10 is
+stored. In other words, the compiled code is equivalent to the
+following:
+
+@example
+L         EQU  10
+          LDA  a
+@dots{}
+a         CON  20-L    
+          END  start
+@end example
+
+
+@node Getting started, mixvm, MIX and MIXAL overview, Top
+@comment  node-name,  next,  previous,  up
+@chapter Getting started
+
+In this chapter, you will find a sample code-compile-run-debug session
+using the @sc{mdk} utilities. Familiarity with the MIX mythical computer
+and its assembly language MIXAL (as described in Knuth's TAOCP) is
+assumed; for a compact reminder, see @ref{MIX and MIXAL overview}. 
+
+@menu
+* Writing a source file::       A sample MIXAL source file.
+* Compiling::                   Using @code{mixasm} to compile source
+                                files into binary format.
+* Running the program::         Running and debugging your program.
+@end menu
+
+@node Writing a source file, Compiling, Getting started, Getting started
+@comment  node-name,  next,  previous,  up
+@section Writing a source file
+@cindex MIXAL
+@cindex source file
+
+MIXAL programs can be written as ASCII files with your editor of choice.
+Here you have the mandatory @emph{hello world} as written in the MIXAL
+assembly language:
+
+@example
+*                                                        (1)
+* hello.mixal: say 'hello world' in MIXAL                (2)
+*                                                        (3)
+* label ins    operand     comment                       (4)
+TERM    EQU    19          the MIX console device number (5)
+        ORIG   1000        start address                 (6)
+START   OUT    MSG(TERM)   output data at address MSG    (7)
+        HLT                halt execution                (8)
+MSG     ALF    "MIXAL"                                   (9)
+        ALF    " HELL"                                   (10)
+        ALF    "O WOR"                                   (11)
+        ALF    "LD   "                                   (12)
+        END    START       end of the program            (13)
+@end example
+         
+@noindent MIXAL source files should have the extension @file{.mixal}
+when used with the @sc{mdk} utilities. As you can see in the above
+sample, each line in a MIXAL file can be divided into four fields
+separated by an arbitrary amount of whitespace characters (blanks and or
+tabs). While Knuth's definition of MIXAL each field must start at a
+fixed pre-defined column number, the @sc{mdk} assembler loosens this
+requirement and lets you format the file as you see fit. The only
+restrictions retained are for comment lines (like 1-4) which must begin
+with an asterisk (*) placed at column 1, and for the label field (see
+below) which, if present, must also start at column 1. The four fields
+in each non-comment line are:
+
+@itemize @minus
+@item
+an optional label, which either refers to the current memory address (as
+@code{START} and @code{MSG} in lines 7 and 9) or a defined symbol
+(@code{TERM}) (if present, the label must always start at the first
+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.
+@item
+an optional operand for the (pseudo)instruction, and
+@item
+an optional free text comment.
+@end itemize
+
+@noindent Lines 9-12 of the @file{hello.mixal} file above also show the
+second (and last) difference between Knuth's MIXAL definition and ours:
+the operand of the @code{ALF} pseudoinstruction (a word of five
+characters) must be quoted with using ""@footnote{In Knuth's definition,
+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}. 
+
+The workings of this sample program should be straightforward if you are
+familiar with MIXAL. See TAOCP vol. 1 for a thorought definition or
+@ref{MIX and MIXAL overview}, for a quick tutorial.
+
+@node Compiling, Running the program, Writing a source file, Getting started
+@comment  node-name,  next,  previous,  up
+@section Compiling
+@cindex compiling
+@cindex binary programs
+@cindex virtual machine
+@cindex assembler
+@cindex @code{mixasm}
+
+A simulator of the MIX computer, called @code{mixvm} (MIX virtual
+machine) is included in the @sc{mdk} tools. It is able to run binary
+files containing MIX instructions written in their binary
+representation. You can translate MIXAL source files into this binary
+form using @code{mixasm}, the MIXAL assembler. So, in order to compile
+the @file{hello.mixal} file, you can type the following 
+command at your shell prompt:
+
+@example
+mixasm -g hello @key{RET}
+@end example
+
+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
+your first MIX program, as described in the following section.
+
+
+@node Running the program,  , Compiling, Getting started
+@comment  node-name,  next,  previous,  up
+@section Running the program
+@cindex @code{mixvm}
+@cindex non-interactive mode
+@cindex interactive mode
+
+MIX is a mythical computer, so it is no use ordering it from your
+favorite hardware provider. @sc{mdk} provides a software simulator of
+the computer, though. It is called @code{mixvm}, which stands for
+@dfn{MIX virtual machine}. Using it, 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
+contents, memory cells contents and so on).
+
+@menu
+* Non-interactive mode::        Running your programs non-interactively.
+* Interactive mode::            Running programs interactively.
+* Debugging::                   Commands for debugging your programs.
+@end menu
+
+@node Non-interactive mode, Interactive mode, Running the program, Running the program
+@comment  node-name,  next,  previous,  up
+@subsection Non-interactive mode
+@cindex non-interactive mode
+
+To make @code{mixvm} work in non-interactive mode, use the @code{-r}
+flag. Thus, to run our @file{hello.mix} program, simply type
+
+@example
+mixvm -r hello @key{RET}
+@end example
+
+@noindent at your command prompt, and you will get the following output:
+
+@example
+MIXAL HELLO WORLD
+@end example
+
+@noindent Since our hello world program uses MIX's device number 19 as
+its output device (@pxref{Writing a source file}), the output is
+redirected to the shell's standard output. Had you used any other MIX
+output devices (disks, drums, line printer, etc.), @code{mixvm} would
+have created a file named after the device used (e.g. @file{disk4.dev})
+and written its output there.
+
+Sometimes, you will prefer to store the results of your program in MIX
+registers rather than writing them to a device. In such cases,
+@code{mixvm}'s @code{-d} flag is your friend: it makes @code{mixvm} to
+dump the contents of its registers and flags after executing the loaded
+program. For instance, typing the following command at your shell's
+prompt
+
+@example
+mixvm -d -r hello
+@end example
+
+@noindent you will obtain the following output:
+
+@example
+MIXAL HELLO WORLD
+rA: + 00 00 00 00 00 (0000000000)
+rX: + 00 00 00 00 00 (0000000000)
+rJ: + 00 00 (0000)
+rI1: + 00 00 (0000)     rI2: + 00 00 (0000)     
+rI3: + 00 00 (0000)     rI4: + 00 00 (0000)     
+rI5: + 00 00 (0000)     rI6: + 00 00 (0000)     
+Overflow: F
+Cmp: E
+@end example
+
+@noindent which, in addition to the program's outputs, gives you the
+contents of the MIX registers and the values of the overflow toggle and
+comparison flag (admittedly, rather uninteresting in 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.
+
+@node Interactive mode, Debugging, Non-interactive mode, Running the program
+@comment  node-name,  next,  previous,  up
+@subsection Interactive mode
+@cindex interactive mode
+
+To enter the MIX virtual machine interactive mode, simply type
+
+@example
+mixvm @key{RET}
+@end example
+
+@noindent at your shell command prompt. This command enters the
+@code{mixvm} command shell. You will be presented the following command
+prompt:
+
+@example
+MIX >
+@end example
+
+@noindent The virtual machine is initialised and ready to accept your
+commands. The @code{mixvm} command shell uses GNU's readline, so that
+you have at your disposal command completion (using @key{TAB}) and
+history functionality, as well as other line editing shortcuts common to
+all utilities using this library (for a complete description of
+readline's line editing usage, see @ref{Command Line
+Editing,,,Readline}.)
+
+Usually, the first thing you will want to do is loading a compiled MIX
+program into memory. This is acomplished by the @code{load} command,
+which takes as an argument the name of the @file{.mix} file to be
+loaded. Thus, typing
+
+@example
+MIX > load hello @key{RET}
+Program loaded. Start address: 3000
+MIX >
+@end example
+
+@noindent will load @file{hello.mix} into the virtual machine's memory
+and set the program counter to the address of the first instruction. You
+can obtain the contents of the program counter using the command
+@code{pc}:
+
+@example
+MIX > pc
+Current address: 3000
+MIX >
+@end example
+
+After loading it, you are ready to run the program,
+using, as you surely have guessed, the @code{run} command:
+
+@example
+MIX > run
+Running ...
+MIXAL HELLO WORLD                                                     
+... done
+MIX > 
+@end example
+
+@noindent After running the program, the program counter will point to
+the address after the one containing the @code{HLT} instruction. In our
+case, asking the value of the program counter after executing the
+program will give us
+
+@example
+MIX > pc
+Current address: 3002
+MIX >
+@end example
+
+@noindent You can check the contents of a memory cell giving its address
+as an argument of the command @code{pmem}, like this
+
+@example
+MIX > pmem 3001
+3001: + 00 00 00 02 05 (0000000133)
+MIX >
+@end example
+
+@noindent
+and convince yourself that address 3001 contains the binary
+representation of the instruction @code{HLT}. An address range of the
+form FROM-TO can also be used as the argument of @code{pmem}:
+
+@example
+MIX > pmem 3000-3006
+3000: + 46 58 00 19 37 (0786957541)
+3001: + 00 00 00 02 05 (0000000133)
+3002: + 14 09 27 01 13 (0237350989)
+3003: + 00 08 05 13 13 (0002118477)
+3004: + 16 00 26 16 19 (0268542995)
+3005: + 13 04 00 00 00 (0219152384)
+3006: + 00 00 00 00 00 (0000000000)
+MIX >
+@end example
+
+@noindent
+In a similar manner, you can look at the contents of the MIX registers
+and flags. For instance, to ask for the contents of the A register you
+can type
+
+@example
+MIX > preg A
+rA: + 00 00 00 00 00 (0000000000)
+MIX >
+@end example
+
+@noindent
+Use the comand @code{help} to obtain a list of all available commands,
+and @code{help COMMAND} for help on a specific command, e.g.
+
+@example
+MIX > help run
+run             Run loaded or given MIX code file. Usage: run [FILENAME]
+MIX > 
+@end example
+
+@noindent
+For a complete list of commands available at the MIX propmt,
+@xref{mixvm}. In the following subsection, you will find a quick tour
+over commands useful for debugging your programs.
+
+@node Debugging,  , Interactive mode, Running the program
+@comment  node-name,  next,  previous,  up
+@subsection Debugging commands
+
+The interactive mode of @code{mixvm} lets you step by step execution of
+programs as well as breakpoint setting. Use @code{next} to step through
+the program, running its instructions one by one. To run our
+two-instruction @file{hello.mix} sample you can do the following:
+
+@example
+MIX > load hello
+Program loaded. Start address: 3000
+MIX > pc
+Current address: 3000
+MIX > next
+MIXAL HELLO WORLD                                                     
+MIX > pc
+Current address: 3001
+MIX > next
+MIX > pc
+Current address: 3002
+MIX > next
+End of program reached at address 3002
+MIX > 
+@end example
+
+You can set a breakpoint at a given address using the command
+@code{sbpa} (set breakpoint at address). When a breakpoint is set,
+@code{run} will stop before executing the instruction at the given
+address. Typing @code{run} again will resume program execution. Coming
+back to our hello world example, we would have:
+
+@example
+MIX > sbpa 3001
+Breakpoint set at address 3001
+MIX > run
+Running ...
+MIXAL HELLO WORLD                                                     
+... stopped: breakpoint at line 8 (address 3001)
+MIX > run
+Running ...
+... done
+MIX >
+@end example
+
+@noindent
+Note that, since we compiled @file{hello.mixal} with debug info enabled
+(the @code{-g} flag of @code{mixasm}), the virtual machine is able to
+tell us the line in the source file corresponding to the breakpoint we
+are setting. As a matter of fact, you can directly set breakpoints at
+source code lines using the command @code{sbp LINE_NO}, e.g.
+
+@example
+MIX > sbp 4
+Breakpoint set at line 7
+MIX > 
+@end example
+
+@noindent
+@code{sbp} sets the breakpoint at the first meaningful source code line;
+thus, in the above example we have requested a breakpoint at a line
+which does not correspond to a MIX instruction and the breakpoint is set
+at the first line containing a real instruction after the given one. To
+unset breakpoints, use @code{cbpa ADDRESS} and @code{cbp LINE_NO}, or
+@code{cabp} to remove all currently set breakpoints. 
+
+MIXAL lets you define symbolic constants, either using the @code{EQU}
+pseudoinstruction or starting an instruction line with a label (which
+assigns to the label the value of the current memory address). Each
+MIXAL program has, therefore, an associated symbol table which you can
+inspect using the @code{psym} command. For our hello world sample, you
+will obtain the following output:
+
+@example
+MIX > psym
+START:  3000
+TERM:  19
+MSG:  3002
+MIX > 
+@end example
+
+For a complete description of all available MIX commands, @xref{mixvm}.
+
+
+
+@node mixvm, mixasm, Getting started, Top
+@comment  node-name,  next,  previous,  up
+@chapter @code{mixvm}, the MIX computer simulator
+
+@cindex mixvm
+
+This chapter describes @code{mixvm}, the MIX computer
+simulator. @code{mixvm} is a command line interface programme which
+simulates the MIX computer (@pxref{The MIX computer}). It is able
+to run MIXAL programs (@pxref{MIXAL}) previously compiled with the MIX
+assembler (@pxref{mixasm}). The simulator allows inspection of the MIX
+computer components (registers, memory cells, comparison flag and overflow
+toggle), step by step execution of MIX programmes, and breakpoint
+setting to aid you in debugging your code. For a tutorial description of
+@code{mixvm} usage, @xref{Running the program}.
+
+@menu
+* Invocation::                  Options when invoking @code{mixvm}.
+* Commands::                    Commands available in interactive mode.
+* Devices::                     MIX block devices implementation.
+@end menu
+
+@node Invocation, Commands, mixvm, mixvm
+@comment  node-name,  next,  previous,  up
+@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
+for each available single letter switch):
+
+@example
+mixvm [-vhurd] [--version] [--help] [--usage] [--run] [--dump]
+      [FILE[.mix]]
+@end example
+
+@noindent
+The meaning of these options is as follows:
+
+@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 -r
+@defoptx --run
+Loads the specified @var{FILE} and executes it. After the program
+execution, @code{mixvm} exits. @var{FILE} must be the name of a binary
+@file{.mix} program compiled with @code{mixasm}. If your program does
+not produce any output, use the @code{-d} flag (see below) to peek at
+the virtual machine's state after execution.
+@end defopt
+
+@defopt -d
+@defoptx --dump
+This option must be used in conjuction with @code{-r}, and tells
+@code{mixvm} to print the value of the virtual machine's registers,
+comparison flag and overflow toggle after executing the program named
+@var{FILE}. See @xref{Non-interactive mode}, for sample usage.
+@end defopt
+
+When run without the @code{-r} flag, @code{mixvm} enters its interactive
+mode, showing you a prompt like this one:
+
+@example
+MIX >
+@end example
+
+@noindent
+and waiting for your commands (@pxref{Commands}). If the
+optional @var{FILE} argument is given, the file @file{FILE.mix} will be
+loaded into the virtual machine memory before entering the interactive
+mode. 
+
+@node Commands, Devices, Invocation, mixvm
+@comment  node-name,  next,  previous,  up
+@section Interactive commands 
+
+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 
+
+@example
+MIX >
+@end example
+
+@noindent
+which indicates that a new virtual machine has been initialised and is
+ready to execute your commands. As we have already mentioned, this
+command prompt offers you command line editing facilities as 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:
+
+@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.
+@end deffn
+
+You have at your disposal a series of commands that let you load and
+execute MIX executable file, as well as manipulate MIXAL source files:
+
+@deffn {file command} load file[.mix]
+This command loads a binary file, @var{file.mix} into the virtual
+machine memory, and positions the program counter at the beginning of
+the loaded program. This address is indicated in the MIXAL source file
+as the operand of the @code{END} pseudoinstruction. Thus, if your
+@file{sample.mixal} source file contains the line:
+
+@example
+     END 3000
+@end example
+
+@noindent
+and you compile it with @code{mixasm} to produce the binary file
+@file{sample.mix}, you will load it into the virtual machine as follows:
+
+@example
+MIX > load sample
+Program loaded. Start address: 3000
+MIX >
+@end example
+
+@end deffn
+
+@deffn {file command} run [file[.mix]]
+When executed without argument, this command initiates or resumes
+execution of instructions from the current program counter
+address. Therefore, issuing this command after a successful @code{load},
+will run the loaded program until either a @code{HLT} instruction or a
+breakpoint is found. If you provide a MIX filename as argument, the
+given file will be loaded (as with @code{load} @var{file}) and
+executed. If @code{run} is invoked again after program execution
+completion (i.e., after the @code{HLT} instruction has been found in a
+previous run), the program counter is repositioned and execution starts
+again from the beginning. 
+@end deffn
+
+@deffn {file command} edit file[.mixal]
+The source file @var{file.mixal} is edited using the editor defined in
+the environment variable @var{MIX_EDITOR}. If this variable is not set,
+the following ones are tried out in order: @var{X_EDITOR}, @var{EDITOR}
+and @var{VISUAL}.
+@end deffn
+
+@deffn {file command} compile file[.mixal]
+The source file @var{file.mixal} is compiled (with debug information
+enabled) using @code{mixasm}.
+@end deffn
+
+Sequential execution of loaded programs can be interrupted using the
+following debug commands:
+
+@deffn {debug command} next [ins_number]
+This command causes the virtual machine to fetch and execute  up to
+@var{ins_number} instructions, beginning from the current program
+counter position. Execution is interrupted either when the specified
+number of instructions have been fetched or a breakpoint is found,
+whatever happens first. If run without arguments, one instruction is
+executed. 
+@end deffn
+
+@deffn {debug command} sbp line_number
+Sets a breakpoint at the specified source file line number. If the line
+specified corresponds to a command or to a MIXAL pseudoinstruction which
+does not produce a MIX instruction in the binary file (such as
+@code{ORIG} or @code{EQU}) the breakpoint is set at the first source
+code line giving rise to a MIX instruction after the specified
+one. Thus, for our sample @file{hello.mixal} file:
+
+@example
+*                                                        (1)
+* hello.mixal: say 'hello world' in MIXAL                (2)
+*                                                        (3)
+* label ins    operand     comment                       (4)
+TERM    EQU    19          the MIX console device number (5)
+        ORIG   1000        start address                 (6)
+START   OUT    MSG(TERM)   output data at address MSG    (7)
+...
+@end example
+
+@noindent
+trying to set a breakpoint at line 5, will produce the following result:
+
+@example
+MIX > sbp 5
+Breakpoint set at line 7
+MIX > 
+@end example
+
+@noindent
+since line 7 is the first one compiled into a MIX instruction (at
+address 3000). In order to @code{sbp} to work, the source file must be
+compiled using the @code{-g} flags, which tells @code{mixasm} to include
+debug information in the binary @file{.mix} file.
+@end deffn
+
+@deffn {debug command} spba address
+Sets a breakpoint at the given memory @var{address}. The argument must
+be a valid MIX memory address, i.e., it must belong into the range
+@w{[0-3999]}. Note that no check is performed to verify that the
+specified address is reachable during program execution. No debug
+information is needed to set a breakpoint by address with @code{sbpa}.
+@end deffn
+
+@deffn {debug command} cbp line_no
+Clears a (previously set) breakpoint at the given source file line.
+@end deffn
+
+@deffn {debug command} cbpa address
+Clears a (previously set) breakpoint at the given memory address.
+@end deffn
+
+@deffn {debug command} cabp
+Clears all currently set breakpoints.
+@end deffn
+
+@deffn {debug command} psym [symbol_name]
+MIXAL programs can define symbolic constants, using either the
+@code{EQU} pseudoinstruction or a label at the beginning of a
+line. Thus, in the program fragment
+
+@example
+VAR     EQU  2168
+        ORIG 4000
+START   LDA  VAR
+@end example
+
+@noindent
+the symbol @code{VAR} stands for the value 2168, while @code{START} is
+assigned the value 4000. When MIXAL programs are compiled using the
+@code{-g} flag (which tells @code{mixasm} to include debug information
+in the binary @file{.mix} file), the symbol table can be consulted from
+the @code{mixvm} command line using @code{psym} followed by the name of
+the symbol whose contents you are interested in. When run without
+arguments, @code{psym} will print all defined symbols and their values.
+@end deffn
+
+Inspection and modification of the virtual machine state (memory,
+registers, overflow toggle and comparison flag contents) is accomplished
+using the following commands:
+
+@deffn {state command} pc
+Prints the current value of the program counter, which stores the
+address of the next instruction to be executed in a non-halted program.
+@end deffn
+
+@deffn {state command} preg [A | X | J | I[1-6]]
+@deffnx {state command} pall
+@deffnx {state command} sreg A | X | J | I[1-6] value
+@code{preg} prints the contents of a given MIX register. For instance,
+@w{@code{preg} @var{A}} will print the contents of the A-register. When
+invoked without arguments, all registers shall be printed:
+
+@example
+MIX > preg
+rA: - 00 00 00 00 35 (0000000035)
+rX: + 00 00 00 15 40 (0000001000)
+rJ: + 00 00 (0000)
+rI1: + 00 00 (0000)	rI2: + 00 00 (0000)	
+rI3: + 00 00 (0000)	rI4: + 00 00 (0000)	
+rI5: + 00 00 (0000)	rI6: + 00 00 (0000)	
+MIX > 
+@end example
+
+As you can see in the above sample, the contents is printed as the sign
+plus the values of the MIX bytes stored in the register and, between
+parenthesis, the decimal representation of its module.
+
+@code{pall} prints the contents of all registers plus the comparison
+flag and overflow toggle.
+
+Finally, @code{sreg} Sets the contents of the given register to
+@var{value}, expressed as a decimal constant. If @var{value} exceeds the
+maximum value storable in the given register, @math{VALUE mod
+MAXIMU_VALUE} is stored, e.g.
+
+@example
+MIX > sreg I1 1000
+MIX > preg I1
+rI1: + 15 40 (1000)	
+MIX > sreg I1 1000000
+MIX > preg I1
+rI1: + 09 00 (0576)	
+MIX > 
+@end example
+
+@end deffn
+
+
+@deffn {state command} pflags
+@deffnx {state command} scmp E | G | L
+@deffnx {state command} sover F | T
+@code{pflags} prints the value of the comparison flag and overflow
+toggle of the virtual machine, e.g.
+
+@example
+MIX > pflags
+Overflow: F
+Cmp: E
+MIX > 
+@end example
+
+@noindent
+The values of the overflow toggle are either @var{F} (false) or @var{T}
+(true), and, for the comparison flag, @var{E}, @var{G}, @var{L} (equal,
+greater, lesser). @code{scmp} and @code{sover} are setters of the
+comparison flag and overflow toggle values.
+@end deffn
+
+@deffn {state command} pmem from[-to]
+@deffnx {state command} smem address value
+@code{pmem} prints the contents of memory cells in the address range
+@w{[@var{FROM}-@var{TO}]}. If the upper limit @var{to} is omitted, only
+the contents of the memory cell with address @var{FROM} is printed, as
+in
+
+@example
+MIX > pmem 3000
+3000: + 46 58 00 19 37 (0786957541)
+MIX >
+@end example
+
+The memory contents is displayed both as the set of five MIX bytes plus
+sign composing the stored MIX word and, between parenthesis, the decimal
+representation of the module of the stored value.
+
+@code{smem} sets the content of the memory cell with address
+@var{address} to @var{value}, expressed as a decimal constant.
+
+@end deffn
+
+Finally, you can use the @code{quit} command to exit @code{mixvm}.
+
+@node Devices,  , Commands, mixvm
+@comment  node-name,  next,  previous,  up
+@section MIX block devices
+
+The MIX computer comes equipped with a set of block devices for
+input-output operations (@pxref{Input-output operators}). @code{mixvm}
+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
+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).
+
+@multitable {the device name} {xx-xx} {filena[x-x].dev} {bin  i/o} 
+@item @emph{Device}  @tab @emph{No.} @tab @emph{filename} @tab @emph{type}
+@item Tape @tab 0-7 @tab @file{tape[0-7].dev} @tab bin i/o
+@item Disks @tab 8-15 @tab @file{disk[0-7].dev} @tab bin i/o
+@item Card reader @tab 16 @tab @file{cardrd.dev} @tab char in
+@item Card writer @tab 17 @tab @file{cardwr.dev} @tab char out
+@item Line printer @tab 18 @tab @file{printer.dev} @tab char out
+@item Terminal @tab 19 @tab @code{stdout} @tab char out
+@item Paper tape @tab 20 @tab @file{paper.dev} @tab char out
+@end multitable
+
+
+
+@node mixasm, Copying, mixvm, Top
+@comment  node-name,  next,  previous,  up
+@chapter @code{mixasm}, the MIXAL assembler
+@cindex @code{mixasm}
+@cindex MIXAL
+@cindex assembler
+
+MIX programs, as executed by @code{mixvm}, are composed of binary
+instructions loaded into the virtual machine memory as MIX
+words. Although you could write your MIX programs directly as a series
+of words in binary format, you have at your disposal a more friendly
+assembly language, MIXAL (@pxref{MIXAL}) which is compiled into binary
+form by @code{mixasm}, the MIXAL assembler included in @sc{mdk}. In this
+chapter, you will find a complete description of @code{mixasm} options.
+
+@menu
+* Invoking @code{mixasm}::      @code{mixasm} options
+@end menu
+
+@node Invoking @code{mixasm},  , mixasm, mixasm
+@comment  node-name,  next,  previous,  up
+@section Invoking @code{mixasm}
+
+In its simplest form, @code{mixasm} is invoked with a single argument,
+which is the name of the MIXAL file to be compiled, e.g.
+
+@example
+mixasm hello
+@end example
+
+@noindent
+will compile either @file{hello} or @file{hello.mixal}, producing a
+binary file named @file{hello.mix} if no errors are found.
+
+In addition, @code{mixasm} can be invoked with the following command
+line options (note, that, following GNU's conventions, we provide a long
+option name for each available single letter switch):
+
+@example
+mixasm [-vhulg] [-o OUTPUT_FILE] [--version] [--help]
+       [--usage] [--debug] [--output=OUTPUT_FILE] [--list[=LIST_FILE]] file
+@end example
+
+@noindent
+The meaning of these options is as follows:
+
+@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 -g
+@defoptx --debug
+Includes debugging information in the compiled file, allowing breakpoint
+setting at source level and symbol table inspection under @code{mixvm}.
+@end defopt
+
+@defopt -o output_file
+@defoptx --output=output_file
+By default, the given source file @var{file.mixal} is compiled into
+@var{file.mix}. You can provide a different name for the output file
+using this option.
+@end defopt
+
+@defopt -l
+@defoptx --list[=list_file]
+This option causes @code{mixasm} to produce, in addion to the
+@file{.mix} file, an ASCII file containing a summary of the compilation
+results. The file is named after the MIXAL source file, changing its
+extension to @file{.mls} if no argument is provided; otherwise, the
+listing file is named according to the argument.
+@end defopt
+
+
+
+@node Copying, Problems, mixasm, Top
+@chapter Copying
+@lowersections
+@include gpl.texi
+@raisesections
+
+@node Problems, Concept Index, Copying, Top
+@chapter Reporting Bugs
+@cindex bugs
+@cindex problems
+
+If you find a bug in @sc{mdk} (or have questions, comments or suggestions
+about it), please send electronic mail to @email{jaortega@@acm.org,
+the author}. 
+
+In your report, please include the version number, which you can find by
+running @w{@samp{mixasm --version}}.  Also include in your message the
+output that the program produced and the output you expected.
+
+@node Concept Index,  , Problems, Top
+@unnumbered Concept Index
+
+@cindex tail recursion
+@printindex cp
+
+@c @node MIXAL instructions,  , Concept Index, Top
+@comment  node-name,  next,  previous,  up
+@c @unnumbered MIXAL instructions
+@c @printindex fn
+
+@shortcontents
+@contents
+@bye
-- 
cgit v1.2.3