initial import (sf 0.3beta)

19 files changed, 3330 insertions, 0 deletions

diff --git a/doc/.cvsignore b/doc/.cvsignore
new file mode 100644
index 0000000..cad9468
--- /dev/null
+++ b/doc/.cvsignore
@@ -0,0 +1,12 @@
+Makefile
+Makefile.in
+mdk-0.1
+mdk-doc-html-0.2.tar.gz
+mdk-doc.tar.gz
+mdk.html
+mdk.info
+mdk.info-1
+mdk.info-2
+mdk.info-3
+stamp-vti
+version.texi
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..42953a8
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,28 @@
+## Process this file with automake to produce Makefile.in
+
+# Copyright (C) 2000 Free Software Foundation, Inc.
+#  
+# 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
+SUFFIXES = .html
+
+
+info_TEXINFOS = mdk.texi
+mdk_TEXINFOS = gpl.texi mdk_intro.texi mdk_tut.texi mdk_gstart.texi \
+               mdk_mixvm.texi mdk_emixvm.texi mdk_mixasm.texi mdk_bugs.texi \
+               mdk_index.texi
+
+html_docs = mdk.html
+
+.texi.html:
+	$(MAKEINFO) --html $<
+
+.PHONY: html
+html: version.texi gpl.texi $(html_docs)
\ No newline at end of file
diff --git a/doc/gpl.texi b/doc/gpl.texi
new file mode 100644
index 0000000..361504a
--- /dev/null
+++ b/doc/gpl.texi
@@ -0,0 +1,400 @@
+@node Copying, Problems, mixasm, Top
+@chapter Copying
+@lowersections
+
+@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.
+
+@raisesections
diff --git a/doc/mdk.texi b/doc/mdk.texi
new file mode 100644
index 0000000..ba5b94f
--- /dev/null
+++ b/doc/mdk.texi
@@ -0,0 +1,213 @@
+\input texinfo 
+@c %**start of header
+@setfilename mdk.info
+@settitle GNU MIX Development Kit (mdk)
+@finalout
+@setchapternewpage odd
+@c %**end of header
+
+@set UPDATED 20 February 2001
+@set EDITION 0.3
+@set VERSION 0.3
+@set JAO Jos@'e Antonio Ortega Ruiz
+@set PHILIP Philip E. King
+@footnotestyle separate
+
+@ifinfo
+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.
+
+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 GNU MDK
+@subtitle GNU MIX Development Kit
+@subtitle Edition @value{EDITION}, for GNU @sc{mdk} Version @value{VERSION}
+@subtitle @value{UPDATED}
+@author by @value{JAO}
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.
+
+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 GNU @sc{mdk} utilities to develop, run and debug
+programs written in the MIXAL programming language.  MIXAL is an
+assembler-like language for programming a virtual computer called
+MIX. They were created by Donald Knuth in the first volume of @cite{The
+Art of Computer Programming} (Addison Wesley, 1997).
+
+GNU @sc{mdk} is an official GNU package.
+
+GNU @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 improve it.
+
+@value{PHILIP} has contributed to this package development with many
+helpful discussions, as well as actual code (@pxref{mixvm.el}).
+
+@end ifinfo
+
+@menu
+* Introduction::		
+* Installing MDK::		
+* MIX and MIXAL tutorial::	Learn the innards of MIX and MIXAL.
+* Getting started::		Basic usage of the @sc{mdk} tools.
+* mixvm.el::			Using @code{mixvm} within Emacs.
+* mixvm::			Invoking and using the MIX virtual machine.
+* gmixvm::			
+* mixasm::			Invoking the MIXAL assembler.
+* Copying::			@sc{mdk} licensing terms.
+* Problems::			Reporting bugs.
+* Concept Index::		Index of concepts.
+
+
+
+
+
+
+
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Installing @sc{mdk}
+
+* Download::                    
+* Requirements::                
+* Basic installation::          
+* Emacs support::               
+* Special configure flags::     
+
+MIX and MIXAL tutorial
+
+* 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
+
+* Instruction structure::       
+* Loading operators::           
+* Storing operators::           
+* Arithmetic operators::        
+* Address transfer operators::  
+* Comparison operators::        
+* Jump operators::              
+* Input-output operators::      
+* Conversion operators::        
+* Shift operators::             
+* Miscellaneous operators::     
+* Execution times::             
+
+MIXAL
+
+* Basic structure::             Writing basic MIXAL programs.
+* MIXAL directives::            Assembler directives.
+* Expressions::                 Evaluation of expressions.
+* W-expressions::               Evaluation of w-expressions.
+* Local symbols::               Special symbol table entries.
+* Literal constants::           Specifying an immediate operand.
+
+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.
+
+Interactive commands 
+
+* File commands::               Loading and executing programs.
+* Debug commands::              Debugging programs.
+* State commands::              Inspecting the virtual machine state.
+
+gmixvm
+
+* Invoking @code{gmixvm}::      
+* MIX virtual machine::         
+* Menu and status bars::        
+
+@code{mixasm}, the MIXAL assembler
+
+* Invoking @code{mixasm}::      @code{mixasm} options
+
+@end detailmenu
+@end menu
+
+@include mdk_intro.texi
+@include mdk_install.texi
+@include mdk_tut.texi
+@include mdk_gstart.texi
+@include mdk_emixvm.texi
+@include mdk_mixvm.texi
+@include mdk_gmixvm.texi
+@include mdk_mixasm.texi
+@include gpl.texi
+@include mdk_bugs.texi
+@include mdk_index.texi
+
+
+@shortcontents
+@contents
+@bye
diff --git a/doc/mdk_bugs.texi b/doc/mdk_bugs.texi
new file mode 100644
index 0000000..7531daa
--- /dev/null
+++ b/doc/mdk_bugs.texi
@@ -0,0 +1,16 @@
+@node Problems, Concept Index, Copying, Top
+@chapter Reporting Bugs
+@cindex bugs
+@cindex problems
+@cindex questions
+@cindex suggestions
+
+If you have any questions, comments or suggestions, please send
+electronic mail to @email{jao@@gnu.org, the author}.
+
+If you find a bug in @sc{mdk}, please send electronic mail to
+@email{bug-mdk@@gnu.org, the @sc{mdk} bug list}.
+
+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.
diff --git a/doc/mdk_emixvm.texi b/doc/mdk_emixvm.texi
new file mode 100644
index 0000000..8fcbf55
--- /dev/null
+++ b/doc/mdk_emixvm.texi
@@ -0,0 +1,25 @@
+@node mixvm.el, mixvm, Getting started, Top
+@comment  node-name,  next,  previous,  up
+@chapter mixvm.el
+
+If you are an Emacs user and write your MIXAL programs using this
+editor, you will find the elisp program @file{mixvm.el} quite
+useful@footnote{@file{mixvm.el} has been kindly contributed by
+@value{PHILIP}. @file{mixvm.el} is based on a study of gdb, perldb, and
+pdb as found in @file{gud.el}, and @file{rubydb3x.el} distributed with
+the source code to the Ruby language.}. @file{mixvm.el} allows running
+the MIX virtual machine @code{mixvm} (@pxref{mixvm}) inside an Emacs
+@acronym{GUD} buffer, while visiting the MIXAL source file in another
+buffer.
+
+After installing @file{mixvm.el} (@pxref{Emacs support}), you can
+initiate an @sc{mdk}/@acronym{GUD} session inside Emacs with the command
+
+@example
+M-x mixvm
+@end example
+
+@noindent
+and you will have a @code{mixvm} prompt inside a newly created
+@acronym{GUD} buffer. @acronym{GUD} will reflect the current line in the
+corresponding source file buffer.
diff --git a/doc/mdk_gmixvm.texi b/doc/mdk_gmixvm.texi
new file mode 100644
index 0000000..f3ed33b
--- /dev/null
+++ b/doc/mdk_gmixvm.texi
@@ -0,0 +1,118 @@
+@node gmixvm, mixasm, mixvm, Top
+@comment  node-name,  next,  previous,  up
+@chapter gmixvm
+@cindex @code{gmixvm}
+@cindex GUI
+@cindex GTK+
+
+@menu
+* Invoking @code{gmixvm}::      Invoking the GTK+ interface.
+* MIX virtual machine::         The MIX virtual machine window.
+* Menu and status bars::        Available menu commands.
+@end menu
+
+@node Invoking @code{gmixvm}, MIX virtual machine, gmixvm, gmixvm
+@comment  node-name,  next,  previous,  up
+@section Invoking @code{gmixvm}
+
+If you have built @sc{mdk} with GTK+ support (@pxref{Installing MDK}), a
+graphical front-end for the MIX virtual machine will be available in
+your system. You can invoke it by typing
+
+@example
+gmixvm @kbd{RET}
+@end example
+
+@noindent
+at your command prompt. The @code{gmixvm} main window will appear,
+offering you a graphical interface to run and debug your MIX programs.
+
+@image{ss_mix}
+
+Apart from the menu and status bars, we can distinguish two zones (or
+halves) in this main window. In the upper half of @code{gmixvm}'s main
+window there is a notebook with three pages, namely,
+
+@itemize
+@item
+a MIX virtual machine view, which shows you the registers, flags, memory
+contents and time statistics of the virtual machine;
+@item
+a MIXAL source view, which shows the MIXAL file and lets you manage
+breakpoints;
+@item
+a Devices view, which shows you the output to character based MIX block
+devices.
+@end itemize
+
+@noindent
+On the other hand, the main window's lower half presents you a
+@code{mixvm} command prompt and a logging area where results of the
+issued commands are presented.
+
+The following sections describe the above mentioned components of
+@code{gmixvm}. 
+
+@node MIX virtual machine, Menu and status bars, Invoking @code{gmixvm}, gmixvm
+@comment  node-name,  next,  previous,  up
+@section MIX virtual machine
+
+The first notebook's page displays the current status of the virtual
+machine. There you can find the registers' contents, the value of the
+comparison and overflow flags, the location pointer, a list with all MIX
+memory cells and their contents, and the time statistics (including
+total uptime, elapsed time since the last run command and total
+execution time for the currently loaded MIX program).
+
+Clicking any register entry, you will be prompted for a new register's
+contents
+@ifnotinfo
+(as shown in the next figure).
+@image{ss_worddlg}
+@end ifnotinfo
+
+In the same manner, click on any address of the memory cells list to be
+prompted for the new contents of the clicked cell. If you click the
+address column's title, a dialog asking you for a memory address will
+appear; if you introduce a valid address, this will be the first cell
+displayed in the scrollable list after you click the OK button.
+
+
+@node Menu and status bars,  , MIX virtual machine, gmixvm
+@comment  node-name,  next,  previous,  up
+@section Menu and status bars
+
+The menu bar gives you access to the following commands:
+
+@deffn File Load...
+Opens a file dialog that lets you specify a binary MIX file to be loaded
+in the virtual machine's memory. It is equivalent to the @code{mixvm}'s
+@code{load} command (@pxref{File commands}).
+@end deffn
+
+@deffn File Exit
+Exits the application.
+@end deffn
+
+@deffn Debug Run
+Runs the currently loaded MIX program, up to the next breakpoint. It is
+equivalent to the @code{mixvm}'s @code{run} command (@pxref{Debug
+commands}). 
+@end deffn
+
+@deffn Debug Next
+Executes the next MIX instruction. It is equivalent to the
+@code{mixvm}'s @code{next} command (@pxref{Debug commands}).
+@end deffn
+
+@deffn Debug Clear breakpoints
+Clears all currently set breakpoints. It is equivalent to the
+@code{mixvm}'s @code{cabp} command.
+@end deffn
+
+@deffn Help About...
+Shows information about @code{gmixvm}'s version and copyright.
+@end deffn
+
+On the other hand, the status bar displays the name of the last loaded
+MIX file.
diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi
new file mode 100644
index 0000000..bde4160
--- /dev/null
+++ b/doc/mdk_gstart.texi
@@ -0,0 +1,433 @@
+@node Getting started, mixvm.el, MIX and MIXAL tutorial, 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 tutorial}. 
+
+@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 tutorial}, 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
+** Execution time: 11
+@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. Note also that the virtual machine reports
+the execution time of the program, according to the (virtual) time spent
+in each of the binary instructions (@pxref{Execution times}).
+
+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
+** Execution time: 11
+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 and execution
+time, 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
+Elapsed time: 11 /Total program time: 11 (Total uptime: 11)
+MIX > 
+@end example
+
+@noindent Note that now the timing statistics are richer. You obtain the
+elapsed execution time (i.e., the time spent executing instructions
+since the last breakpoint), the total execution time for the program up
+to now (which in our case coincides with the elapsed time, since there
+were no breakpoints), and the total uptime for the virtual machine (you
+can load and run more than one program in the same session). 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
+Elapsed time: 1 /Total program time: 1 (Total uptime: 1)
+MIX > pc
+Current address: 3001
+MIX > next
+End of program reached at address 3002
+Elapsed time: 10 /Total program time: 11 (Total uptime: 11)
+MIX > pc
+Current address: 3002
+MIX > next
+MIXAL HELLO WORLD
+Elapsed time: 1 /Total program time: 1 (Total uptime: 12)
+MIX > 
+MIX > run
+Running ...
+... done
+Elapsed time: 10 /Total program time: 11 (Total uptime: 22)
+MIX > @end example
+@noindent
+(As an aside, the above sample also shows how the virtual machine
+handles cummulative time statistics and automatic program restart).
+
+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)
+Elapsed time: 1 /Total program time: 1 (Total uptime: 23)
+MIX > run
+Running ...
+... done
+Elapsed time: 10 /Total program time: 11 (Total uptime: 33)
+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
+
+Other useful commands for debugging are @code{tron} (which turns on
+tracing of executed intructions) and @code{weval} (which evaluates
+w-expressions on the fly). For a complete description of all available
+MIX commands, @xref{mixvm}.
diff --git a/doc/mdk_index.texi b/doc/mdk_index.texi
new file mode 100644
index 0000000..cb752f0
--- /dev/null
+++ b/doc/mdk_index.texi
@@ -0,0 +1,10 @@
+@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
diff --git a/doc/mdk_install.texi b/doc/mdk_install.texi
new file mode 100644
index 0000000..78690ba
--- /dev/null
+++ b/doc/mdk_install.texi
@@ -0,0 +1,180 @@
+@node Installing MDK, MIX and MIXAL tutorial, Introduction, Top
+@comment  node-name,  next,  previous,  up
+@chapter Installing @sc{mdk}
+
+@menu
+* Download::                    
+* Requirements::                
+* Basic installation::          
+* Emacs support::               
+* Special configure flags::     
+@end menu
+
+@node Download, Requirements, Installing MDK, Installing MDK
+@comment  node-name,  next,  previous,  up
+@section Download the source tarball
+
+GNU @sc{mdk} is distributed as a source tarball available for download in
+the following @acronym{URL}s:
+
+@itemize @bullet
+@item
+@url{ftp://ftp.gnu.org/pub/gnu/mdk} (or one of
+@uref{http://www.gnu.org/prep/ftp.html, its mirrors})
+@item
+@uref{http://sourceforge.net/project/showfiles.php?group_id=13897}
+@end itemize
+ 
+The above sites contain the latest stable releases of @sc{mdk}. The
+development branch is available at:
+
+@itemize @bullet
+@item
+@uref{http://sourceforge.net/cvs/?group_id=13897}
+@end itemize
+
+After you have downloaded the source tarball, unpack it in a directory
+of your choice using the command:
+
+@example
+tar xfvz mdk-X.Y.tar.gz
+@end example
+
+@noindent
+where @var{X.Y} stands for the downloaded version (the current stable
+release being version @value{VERSION}).
+
+@node Requirements, Basic installation, Download, Installing MDK
+@comment  node-name,  next,  previous,  up
+@section Requirements
+
+In order to build and install @sc{mdk}, you will need the following
+libraries installed in your system:
+
+@itemize @minus
+@item
+@uref{http://www.gtk.org, GLIB 1.2.0} (required)
+@item
+@uref{http://www.gnu.org/software/flex/flex.html, GNU Flex 2.3} (required)
+@item
+@uref{http://www.gtk.org, GTK+ 1.2.0} (optional)
+@item
+@uref{ftp://ftp.gnome.org/pub/GNOME/stable/sources/libglade/, libglade}
+(optional)
+@item
+GNU readline and history libraries (optional)
+@end itemize
+
+If present, readline and history are used to provide command completion
+and history management to the command line MIX virtual machine, @code{mixvm}
+GTK+ and libglade are needed if you want to build the graphical
+interface to the MIX virtual machine, @code{gmixvm}.
+
+@strong{Please note}: you need both the libraries @emph{and} the
+headers; this means both the library package and the @file{-dev} package
+if you do not compile your libraries yourself (ex: installing
+@file{libgtk1.2} and @file{libgtk1.2-dev} on Debian).
+
+@node Basic installation, Emacs support, Requirements, Installing MDK
+@comment  node-name,  next,  previous,  up
+@section Basic installation
+
+@sc{mdk} uses GNU Autoconf and Automake tools, and, therefore, should
+be built and installed without hassle using the following commands
+inside the source directory:
+
+@example
+./configure
+make
+make install
+@end example
+
+@noindent
+where the last one must be run as root.
+
+The first command, @code{configure}, will setup the makefiles for your
+system. In particular, @code{configure} will look for GTK+ and libglade,
+and, if they are present, will generate the appropiate makefiles for
+building the @code{gmixvm} graphical user interface. Upon completion,
+you should see a message with the configuration results like the
+following:
+
+@example
+*** GNU MDK 0.3 has been successfully configured. ***
+
+Type make to build the following utilities:
+    - mixasm (MIX assembler)
+    - mixvm (MIX virtual machine, with readline support)
+    - gmixvm (mixvm GTK+ GUI)
+@end example
+
+@noindent
+where the last line may be missing if you lack the above mentioned
+libraries. 
+
+The next command, @code{make}, will actually build the @sc{mdk} programs
+in the following locations:
+
+@itemize @minus
+@item
+@file{mixutils/mixasm}
+@item
+@file{mixutils/mixvm}
+@item
+@file{mixgtk/gmixvm}
+@end itemize
+
+You can run these programs from within their directories, but I
+recommend you to install them in proper locations using @code{make
+install} from a root shell.
+
+@node Emacs support, Special configure flags, Basic installation, Installing MDK
+@comment  node-name,  next,  previous,  up
+@section Emacs support
+
+@code{mixvm} can be run within an Emacs GUD buffer using the elisp
+program @file{misc/mixvm.el}, kindly contributed by @value{PHILIP}.
+
+@file{mixvm.el} provides an interface between @sc{mdk}'s @code{mixvm}
+and Emacs, via @acronym{GUD}.  Place this file in your load-path,
+optionally adding the following line to your @file{.emacs} file:
+
+@lisp
+(autoload 'mixvm "mixvm" "mixvm/gud interaction" t)
+@end lisp
+
+
+
+@node Special configure flags,  , Emacs support, Installing MDK
+@comment  node-name,  next,  previous,  up
+@section Special configure flags
+
+You can fine tunning the configuration process using the following
+switches with configure:
+
+@defopt --enable-gui[=yes|no]
+@defoptx --disable-gui
+Enables/disables the built of the MIX virtual machine GUI
+(@code{gmixvm}). If the required libraries are missing
+(@pxref{Requirements}) the configure script with automatically disable
+this feature.
+@end defopt
+
+@defopt --with-readline[=yes|no]
+@defoptx --without-readline
+Enables/disables the GNU Readline support for @code{mixvm}.  If the
+required libraries are missing (@pxref{Requirements}) the configure
+script with automatically disable this feature.
+@end defopt
+
+For additional, boilerplate configure options, see the @file{INSTALL}
+file, or run
+
+@example
+configure --help
+@end example
+
+
+
+
+
diff --git a/doc/mdk_intro.texi b/doc/mdk_intro.texi
new file mode 100644
index 0000000..2a3f95d
--- /dev/null
+++ b/doc/mdk_intro.texi
@@ -0,0 +1,48 @@
+@node Introduction, Installing MDK, 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
+CISC CPUs, and the MIX assembly language (MIXAL) 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 learn or improve your programming skills, 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 mixasm
+MIXAL assembler. Assembler which translates MIXAL source files into
+programs that can be run (and debugged) by @code{mixvm} or @code{gmixvm}.
+@item mixvm
+MIX virtual machine. Emulation of the MIX computer with a @acronym{CLI}.
+@item gmixvm
+A GTK+ GUI for the MIX virtual machine. Provides all of @code{mixvm}
+functionality accessible through a graphical interface.
+@item mixvm.el
+This elisp program allows running @code{mixvm} inside an Emacs GUD
+buffer, allowing concurrent edition and debugging of MIXAL programs.
+@end table 
+
+@code{mixvm} and @code{gmixvm} implement 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 tutorial of MIX and MIXAL, and a thorough
+description of the use of the @sc{mdk} utilities.
diff --git a/doc/mdk_mixasm.texi b/doc/mdk_mixasm.texi
new file mode 100644
index 0000000..753aa33
--- /dev/null
+++ b/doc/mdk_mixasm.texi
@@ -0,0 +1,79 @@
+@node mixasm, Copying, gmixvm, 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
diff --git a/doc/mdk_mixvm.texi b/doc/mdk_mixvm.texi
new file mode 100644
index 0000000..8289472
--- /dev/null
+++ b/doc/mdk_mixvm.texi
@@ -0,0 +1,478 @@
+@node mixvm, gmixvm, mixvm.el, 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 which are
+described in the Readline user's manual (chances are that you are
+already familiar with these command line editing capabilities, as they
+are present in many GNU utilities, e.g. the @code{bash} shell). As a
+beginner, your best friend will be the @code{help} command, which shows
+you a summary of all available MIX commands and their usage; its syntax
+is as follows:
+
+@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
+
+@menu
+* File commands::               Loading and executing programs.
+* Debug commands::              Debugging programs.
+* State commands::              Inspecting the virtual machine state.
+@end menu
+
+@node File commands, Debug commands, Commands, Commands
+@comment  node-name,  next,  previous,  up
+@subsection File commands
+
+You have at your disposal a series of commands that let you load and
+execute MIX executable files, 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{MDK_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
+
+
+@node Debug commands, State commands, File commands, Commands
+@comment  node-name,  next,  previous,  up
+@subsection Debug commands
+
+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
+
+The virtual machine can also show you the instructions it is executing,
+using the following commands:
+
+@deffn {debug command} tron
+@deffnx troff
+@code{tron} enables instruction tracing. When tracing is enabled, each
+time the virtual machine executes an instruction (due to your issuing a
+@code{run} or @code{next} command), it is printed in its canonical form
+(that is, with all expressions evaluated to their numerical values) and,
+if the program was compiled with debug information, as it was originally
+typed in the MIXAL source file. Instruction tracing is disable with the
+@code{troff} command. A typical tracing session could be like this:
+
+@example
+MIX > tron
+Instruction tracing has been turned ON.
+MIX > next
+3000: [OUT	3002,0(2:3)]	START	OUT	MSG(TERM)
+MIXAL HELLO WORLD                                                     
+Elapsed time: 1 /Total program time: 1 (Total uptime: 1)
+MIX > next
+3001: [HLT	0,0]		HLT
+End of program reached at address 3002
+Elapsed time: 10 /Total program time: 11 (Total uptime: 11)
+MIX > troff
+Instruction tracing has been turned OFF.
+MIX > 
+@end example
+@noindent
+The executed instruction, as it was translated, is shown between square
+brackets after the memory address, and, following it, you can see the
+actual MIXAL code that was compiled into the executed instruction.
+@end deffn
+
+@code{mixvm} is also able of evaluating w-expressions
+(@pxref{W-expressions}) using the following command:
+
+@deffn {debug command} weval WEXP
+Evaluates the given w-expression, @var{WEXP}. The w-expression can
+contain any currently defined symbol. For instance:
+
+@example
+MIX > psym START
++ 00 00 00 46 56 (0000003000)
+MIX > weval START(0:1),START(3:4)
++ 56 00 46 56 00 (0939716096)
+MIX >
+@end example
+@end deffn
+
+New symbols can be defined using the @code{ssym} command:
+@deffn {debug command} ssym SYM WEXP
+Defines the symbol named @var{SYM} with the value resulting from
+evaluating @var{WEXP}, an w-expression. The newly defined symbol can be
+used in subsequent @code{weval} commands, as part of the expression to
+be evaluated. E.g.,
+
+@example
+MIX > ssym S 2+23*START
++ 00 00 18 19 56 (0000075000)
+MIX > psym S
++ 00 00 18 19 56 (0000075000)
+MIX > weval S(3:4)
++ 00 00 19 56 00 (0000081408)
+MIX > 
+@end example
+@end deffn
+
+Finally, if you want to discover which is the decimal value of a MIX
+word expressed as five bytes plus sign, you can use
+
+@deffn {debug command} w2d WORD
+Computes the decimal value of the given word. @var{WORD} must be
+expressed as a sign (+/-) followed by five space-delimited, two-digit
+decimal values representing the five bytes composing the word. The
+reverse operation (showing the word representation of a decimal value)
+can be accomplished with @code{weval}. For instance: 
+
+@example
+MIX > w2d - 01 00 00 02 02
+-16777346
+MIX > weval -16777346
+- 01 00 00 02 02 (0016777346)
+MIX > 
+@end example
+@end deffn
+
+@node State commands,  , Debug commands, Commands
+@comment  node-name,  next,  previous,  up
+@subsection State commands
+
+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 } {filename[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
diff --git a/doc/mdk_tut.texi b/doc/mdk_tut.texi
new file mode 100644
index 0000000..12bfb42
--- /dev/null
+++ b/doc/mdk_tut.texi
@@ -0,0 +1,1259 @@
+@node MIX and MIXAL tutorial, Getting started, Installing MDK, Top
+@comment  node-name,  next,  previous,  up
+@chapter MIX and MIXAL tutorial
+@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) to illustrate
+the algorithms and skills that every serious programmer should
+master. 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.  In the following subsections you will find a tutorial
+on these topics, which will teach you the basics of the MIX architecture
+and how to program a MIX computer using MIXAL.
+
+@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 tutorial, MIX and MIXAL tutorial
+@comment  node-name,  next,  previous,  up
+@section The MIX computer
+
+In this section, you will find a 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 from 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
+@noindent
+Sample MIX words are @samp{- 12 00 11 01 63} and @samp{+ 12 11 34 43
+00}.
+
+You can refer to subfields within a word using a @dfn{field
+specification} or @dfn{fspec} of the form ``(@var{l}:@var{r})'', where
+@var{l} denotes the first byte, and @var{r} the last byte of the
+subfield.
+When @var{l} is zero, the subfield includes the word's
+sign. An fspec can also be represented as a single value @code{F}, given
+by @code{F = 8*L + R} (thus the fspec @samp{(1:3)}, denoting the first
+three bytes of a word, is represented by the integer 11).
+
+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:
+
+@cindex rA
+@cindex rX
+@cindex rJ
+@cindex rIn
+@cindex register
+
+@table @asis
+@item @code{rA}
+A register. General purpose register holding a word. Usually its
+contents serves as the operand of arithmetic and storing instructions.
+@item @code{rX}
+X register. General purpose register holding a word. Often it acts as an
+extension or a replacement of @samp{rA}.
+@item @code{rJ}
+J (jump) register. This register stores positive two-byte values,
+usually representing a jump address.
+@item @code{rI1}, @code{rI2}, @code{rI3}, @code{rI4}, @code{rI5}, @code{rI6}
+Index registers. These six registers can store a signed two-byte
+value. Their contents is used as indexing values for the computation of
+effective memory addresses.
+@end table
+
+@cindex @sc{ov}
+@cindex @sc{cm}
+@cindex @code{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}, and its possible values are abbreviated as @dfn{E}, @dfn{G} and
+@dfn{L}.
+@item
+Input-output block devices. Each device is labelled as @code{un}, where
+@code{n} runs from 0 to 20. In Knuth's definition, @code{u0} through
+@code{u7} are magnetic tape units, @code{u8} through @code{15} are disks
+and drums, @code{u16} is a card reader, @code{u17} is a card writer,
+@code{u18} is 
+a line printer and, @code{u19} is a typewriter terminal, and @code{u20},
+a paper tape. Our implementation maps these devices to disk files,
+except for @code{u19}, which represents the standard output.
+@end itemize
+
+As noted above, the MIX computer communicates with the external world by
+a set of input-output devices which can be ``connected'' to it. The
+computer interchanges information using blocks of words whose length
+depends on the device at hand (@pxref{Devices}). These words are
+interpreted by the device either as binary information (for devices
+0-16), or as representing printable characters (devices 17-20). In the
+last case, each MIX byte is mapped onto a character according to the
+following table:
+
+@multitable  {00} {C} {00} {C} {00} {C} {00} {C}
+@item  00 @tab  @tab 01 @tab A @tab 02 @tab B @tab 03 @tab C
+@item  04 @tab D @tab 05 @tab E @tab 06 @tab F @tab 07 @tab G
+@item  08 @tab H @tab 09 @tab I @tab 10 @tab d @tab 11 @tab J
+@item  12 @tab K @tab 13 @tab L @tab 14 @tab M @tab 15 @tab N
+@item  16 @tab O @tab 17 @tab P @tab 18 @tab Q @tab 19 @tab R
+@item  20 @tab s @tab 21 @tab p @tab 22 @tab S @tab 23 @tab T
+@item  24 @tab U @tab 25 @tab V @tab 26 @tab W @tab 27 @tab X
+@item  28 @tab Y @tab 29 @tab Z @tab 30 @tab 0 @tab 31 @tab 1 
+@item  32 @tab 2 @tab 33 @tab 3 @tab 34 @tab 4 @tab 35 @tab 5
+@item  36 @tab 6 @tab 37 @tab 7 @tab 38 @tab 8 @tab 39 @tab 9
+@item  40 @tab . @tab 41 @tab , @tab 42 @tab ( @tab 43 @tab )
+@item  44 @tab + @tab 45 @tab - @tab 46 @tab * @tab 47 @tab /
+@item  48 @tab = @tab 49 @tab $ @tab 50 @tab < @tab 51 @tab >
+@item  52 @tab @@ @tab 53 @tab ; @tab 54 @tab : @tab 55 @tab '
+@end multitable
+@noindent
+The value 0 represents a whitespace. Lowercase letters (d, s, p)
+correspond to symbols not representable as ASCII characters (uppercase
+delta, sigma and gamma, respectively), and byte values 56-63 have no
+associated character.
+
+Finally, the MIX computer features a virtual CPU which controls the
+above components, and which is able to execute a rich set of
+instructions (constituting its machine language, similar to those
+commonly found in real CPUs), including arithmetic, logical, storing,
+comparison and jump instructions. Being a typical von Neumann computer,
+the MIX CPU fetchs binary instructions from memory sequentially (unless
+a jump instruction is found), and stores the address of the next
+instruction to be executed in an internal register called @dfn{location
+counter} (also known as program counter in other architectures).
+
+The next section, @xref{MIX instruction set}, gives a complete description
+of the available MIX binary 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 fully describe the instruction set of the MIX
+computer. We begin with a description of the structure of binary
+instructions and the notation used to refer to their subfields. The
+remaininig subsections are devoted to describing the actual instructions
+available to the MIX programmer.
+
+@menu
+* Instruction structure::       
+* Loading operators::           
+* Storing operators::           
+* Arithmetic operators::        
+* Address transfer operators::  
+* Comparison operators::        
+* Jump operators::              
+* Input-output operators::      
+* Conversion operators::        
+* Shift operators::             
+* Miscellaneous operators::     
+* Execution times::             
+@end menu
+
+@node Instruction structure, Loading operators, MIX instruction set, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Instruction structure
+
+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
+
+For a given instruction, @samp{M} stands for
+the memory address obtained after indexing the ADDRESS subfield 
+(using its INDEX byte), and @samp{V} is the contents of the
+subfield indicated by MOD of the memory cell with address @samp{M}. For
+instance, suppose that we have the following contents of MIX registers
+and memory cells:
+
+@example
+[rI2] = + 00 63
+[31] = - 10 11 00 11 22
+@end example
+@noindent
+where @samp{[n]} denotes the contents of the nth memory cell and
+@samp{[rI2]} the contents of register @samp{rI2}@footnote{In general,
+@samp{[X]} will denote the contents of entity @samp{X}; thus, by
+definition, @w{@samp{V = [M](MOD)}}.}.  Let us consider the binary
+instruction @w{@samp{I = - 00 32 02 11 10}}. For this instruction we
+have:
+
+@example
+ADDRESS = - 00 32 = -32
+INDEX = 02 = 2
+MOD = 11 = (1:3)
+OPCODE = 10
+
+M = ADDRESS + [rI2] = -32 + 63 = 31
+V = [M](MOD) = (- 10 11 00 11 22)(1:3) = + 00 00 10 11 00
+@end example
+
+In the following subsections, we will assing to each MIX instruction a
+mnemonic, or symbolic name. For instance, the mnemonic of @samp{OPCODE}
+10 is @samp{LD2}. Thus we can rewrite the above instruction as
+
+@example
+LD2  -32,2(1:3)
+@end example
+@noindent
+or, for a generic instruction:
+
+@example
+MNEMONIC  ADDRESS,INDEX(MOD)
+@end example
+@noindent
+Some instructions are identified by both the OPCODE and the MOD
+fields. In these cases, the MOD will not appear in the above symbolic
+representation. Also when ADDRESS or INDEX are zero, they can be
+omitted.  Finally, MOD defaults to (0:5) (meaning the
+whole word).
+
+@node Loading operators, Storing operators, Instruction structure, 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
+Put in rA the contents of cell no. M.
+OPCODE = 8, MOD = fspec. @code{rA <- V}.
+@item LDX
+Put in rX the contents of cell no. M.
+OPCODE = 15, MOD = fspec. @code{rX <- V}.
+@item LDi
+Put in rIi the contents of cell no. M.
+OPCODE = 8 + i, MOD = fspec. @code{rIi <- V}.
+@item LDAN
+Put in rA the negative contents of cell no. M.
+OPCODE = 16, MOD = fspec. @code{rA <- -V}.
+@item LDXN
+Put in rX the negative contents of cell no. M.
+OPCODE = 23, MOD = fspec. @code{rX <- -V}.
+@item LDiN
+Put in rIi the negative contents of cell no. M.
+OPCODE = 16 + i, MOD = fspec. @code{rIi <- -V}.
+@end ftable
+
+In all the above load instructions the @samp{MOD} field selects the
+bytes of the memory cell with address @samp{M} which are loaded into the
+requisite register (indicated by the @samp{OPCODE}).  For instance, the
+word @w{@samp{+ 00 13 01 27 11}} represents the instruction
+
+@example
+LD3    13,1(3:3)
+ ^      ^ ^  ^
+ |      | |  |
+ |      | |   --- MOD = 27 = 3*8 + 7
+ |      |  --- INDEX = 1
+ |       --- ADDRESS = 00 13
+  --- OPCODE = 11
+@end example
+Let us suppose that, prior to this instruction execution, the state of
+the MIX computer is the following:
+
+@example
+[rI1] = - 00 01
+[rI3] = + 24 12
+[12] = - 01 02 03 04 05
+@end example
+@noindent
+As, in this case, @w{@samp{M = 13 + [rI1] = 12}}, we have
+@w{@samp{V = [M](3:3) = (- 01 02 03 04 05)(3:3) = + 00 00 00 00 03}}
+(note that the specified subfield is left-padded with null bytes to
+complete a word). Hence, the MIX state, after the instruction execution,
+will be
+
+@example
+[rI1] = - 00 01
+[rI3] = + 00 03
+[12] = - 01 02 03 04 05
+@end example
+
+To further illustrate loading operators, the following table shows the
+contents of @samp{rX} after different @samp{LDX} instructions:
+
+@table @samp
+@item LDX 12(0:0)     [rX] = - 00 00 00 00 00
+@item LDX 12(0:1)     [rX] = - 00 00 00 00 01
+@item LDX 12(3:5)     [rX] = + 00 00 03 04 05
+@item LDX 12(3:4)     [rX] = + 00 00 00 03 04
+@item LDX 12(0:5)     [rX] = - 01 02 03 04 05
+@end table
+
+
+@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 the inverse of the load
+operations: they are used to store a subfield of a register
+into a memory location. Here, MOD represents the subfield of the memory
+cell that is to be overwritten with bytes from a register. These bytes
+are taken beginning by the rightmost side of the register.
+
+@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
+
+By way of example, consider the instruction @samp{STA 1200(2:3)}. It
+causes the MIX to fetch bytes no. 4 and 5 of register A and copy them to
+bytes 2 and 3 of memory cell no. 1200 (remember that, for these
+instructions, MOD specifies a subfield of @emph{the memory
+address}). The others bytes of the memory cell retain their
+values. Thus, if prior to the instruction execution we have
+
+@example
+[1200] = - 20 21 22 23 24
+[rA] = + 01 02 03 04 05
+@end example
+@noindent
+we will end up with
+
+@example
+[1200] = - 20 04 05 23 24
+[rA] = + 01 02 03 04 05
+@end example
+
+As a second example, @samp{ST2 1000(0)} will set the sign of
+@samp{[1000]} to that of @samp{[rI2]}.
+
+@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. 
+@w{@code{rA <- rA +V}}.
+@item SUB
+Sub and set OV if overflow. OPCODE = 2, MOD = fspec.
+@w{@code{rA <- rA - V}}.
+@item MUL
+Multiply V times rA and store the 10-bytes product in rAX.
+OPCODE = 3, MOD = fspec. @w{@code{rAX <- rA x V}}.
+@item DIV
+rAX is considered a 10-bytes number, and it is divided by V.
+OPCODE = 4, MOD = fspec. @w{@code{rA <- rAX / V}}, @code{rX} <- reminder.
+@end ftable
+
+In all the above instructions, @samp{[rA]} is one of the operands
+of the binary arithmetic operation, the other being @samp{V} (that is,
+the specified subfield of the memory cell with address @samp{M}), padded
+with zero bytes on its left-side to complete a word. In multiplication
+and division, the register @samp{X} comes into play as a right-extension
+of the register @samp{A}, so that we are able to handle 10-byte numbers
+whose more significant bytes are those of @samp{rA} (the sign of this
+10-byte number is that of @samp{rA}: @samp{rX}'s sign is ignored).
+
+Addition and substraction of MIX words can give rise to overflows, since
+the result is stored in a register with room to only 5 bytes (plus
+sign). When this occurs, the operation result modulo @w{1,073,741,823}
+(the maximum value storable in a MIX word) is stored in @samp{rA}, and
+the overflow toggle is set to TRUE.
+
+@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, @samp{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
+
+In the above instructions, the subfield @samp{ADDRESS} acts as an
+immediate (indexed) operand, and allow us to set directly the contents
+of the MIX registers without an indirection to the memory cells (in a
+real CPU this would mean that they are faster that the previously
+discussed instructions, whose operands are fetched from memory). So, if
+you want to store in @samp{rA} the value -2000 (- 00 00 00 31 16), you
+can use the binary instruction @w{+ 31 16 00 03 48}, or, symbolically,
+
+@example
+ENNA 2000
+@end example
+@noindent
+Used in conjuction with the store operations (@samp{STA}, @samp{STX},
+etc.), these instructions also allow you to set memory cells contents to
+concrete values.
+
+Note that in these address transfer operators, the @samp{MOD} field is
+not a subfield specificator, but serves to define (together with
+@samp{OPCODE}) the concrete operation to be performed.
+
+@node Comparison operators, Jump operators, Address transfer operators, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Comparison operators
+@cindex comparison operators
+
+So far, we have learned how to move values around between the MIX
+registers and its memory cells, and also how to perform arithmetic
+operations using these values. But, in order to write non-trivial
+programs, other functionalities are needed. One of the most common is
+the ability to compare two values, which, combined with jumps, will
+allow the execution of conditional statements.
+The following instructions compare the value of a register with @samp{V}, and
+set the @sc{cm} indicator to the result of the comparison (i.e. to
+@samp{E}, @samp{G} or @samp{L}, equal, greater or lesser respectively).
+
+@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
+
+As explained above, these instructions modify the value of the MIX
+comparison indicator; but maybe you are asking yourself how do you use
+this value: enter jump operators, in the next subsection.
+
+@node Jump operators, Input-output operators, Comparison operators, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Jump operators
+@cindex jump operators
+
+The MIX computer has an internal register, called the @dfn{location
+counter}, which stores the address of the next instruction to be fetched
+and executed by the virtual CPU. You cannot directly modify the contents
+of this internal register with a load instruction: after fetching the
+current instruction from memory, it is automatically increased in one
+unit by the MIX. However, the is a set of instructions (which we call
+jump instructions) which can alter the contents of the location counter
+provided some condition is met. When this occurs, the value of the next
+instruction address that would have been fetched in the absence of the
+jump is stored in @samp{rJ} (except for @code{JSJ}), and the location
+counter is set to the value of @samp{M} (so that the next instruction is
+fetched from this new address). Later on, you can return to the point
+when the jump occurred reading the address stored in @samp{rJ}.
+
+The MIX computer provides the following jump instructions:
+With these instructions you force a jump to the specified address. Use
+@samp{JSJ} if you do not care about the return address.
+
+@ftable @code
+@item JMP
+Unconditional jump. OPCODE = 39, MOD = 0.
+@item JSJ
+Unconditional jump, but rJ is not modified. OPCODE = 39, MOD = 1.
+@end ftable
+
+These instructions check the overflow toggle to decide whether to jump
+or not.
+
+@ftable @code
+@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.
+@end ftable
+
+In the following instructions, the jump is conditioned to the contents of the
+comparison flag:
+
+@ftable @code
+@item JL
+Jump if @w{@code{[CM] = L}}. OPCODE = 39, MOD = 4.
+@itemx JE
+Jump if @w{@code{[CM] = E}}. OPCODE = 39, MOD = 5.
+@itemx JG
+Jump if @w{@code{[CM] = G}}. OPCODE = 39, MOD = 6.
+@itemx JGE
+Jump if @code{[CM]} does not equal @code{L}. OPCODE = 39, MOD = 7.
+@itemx JNE
+Jump if @code{[CM]} does not equal @code{E}. OPCODE = 39, MOD = 8.
+@itemx JLE
+Jump if @code{[CM]} does not equal @code{G}. OPCODE = 39, MOD = 9.
+@end ftable
+
+You can also jump conditioned to the value stored in the MIX registers,
+using the following instructions:
+
+@ftable @code
+@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 Input-output operators, Conversion operators, Jump operators, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Input-output operators
+@cindex input-output operators
+
+As explained in previous sections (@pxref{MIX architecture}), the MIX
+computer can interact with a series of block devices. To that end, you
+have at your disposal the following instructions:
+
+@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
+@noindent
+In all the above instructions, the @samp{MOD} subfile must be in the
+range 0-20, since it denotes the operation's target device. The
+@samp{IOC} instruction only makes sense for tape devices (@samp{MOD} =
+0-7 or 20): it shifts the read/write pointer by the number of words
+given by @samp{M} (if it equals zero, the tape is rewound)@footnote{In
+Knuth's original definition, there are other control operations
+available, but they do not make sense when implementing the block
+devices as disk files (as we do in @sc{mdk} simulator). For the same
+reason, @sc{mdk} devices are always ready, since all input-output
+operations are performed using synchronous system calls.}.
+
+
+@node Conversion operators, Shift 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
+@noindent
+Digits are represented in MIX by the range of values 30-39 (digits
+9-0). Thus, if the contents of @samp{rA} and @samp{rX} is, for instance,
+
+@example
+[rA] = + 30 30 31 32 33
+[rX] = + 31 35 39 30 34
+@end example
+@noindent
+the represented number is 0012315904, and @samp{NUM} will store this
+value in @samp{rA} (i.e., we end up with @samp{[rA]} = @w{+ 0 46 62 52
+0} = 12315904. @samp{CHAR} performs the inverse operation.
+
+@node Shift operators, Miscellaneous operators, Conversion operators, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Shift operators
+@cindex shift
+@cindex shift operators
+
+The following instructions perform byte-wise shifts of the contents of
+@samp{rA} and @samp{rX}.
+
+@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.
+@end ftable
+@noindent
+If we begin with, say, @samp{[rA]} = @w{- 01 02 03 04 05}, we would
+have the following modifications to @samp{rA} contents when performing
+the instructions on the left column:
+
+@multitable {SLA 00} {[rA] = - 00 00 00 00 00}
+@item SLA 2 @tab [rA] = - 03 04 05 00 00
+@item SRA 1 @tab [rA] = - 00 01 02 03 04
+@item SLC 3 @tab [rA] = - 04 05 01 02 03
+@item SRC 24 @tab [rA] = - 05 01 02 03 04
+@end multitable
+@noindent
+Note that the sign is unaffected by shift operations. On the other hand,
+@samp{SLAX} and @samp{SRAX} treat @samp{rA} and @samp{rX} as a single
+10-bytes register (ignoring again the signs), so that, if we begin with
+@samp{[rA]} = @w{+ 01 02 03 04 05} and @samp{[rX]} = @w{- 06 07 08 09
+10}, executing @samp{SLAX 3} would yield:
+
+@example
+[rA] = + 04 05 06 07 08  [rX] = - 09 10 00 00 00
+@end example
+
+@node Miscellaneous operators, Execution times, Shift operators, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Miscellaneous operators
+@cindex miscellaneous operators
+
+Finally, we list in the following table three miscellaneous MIX
+instructions which do not fit in any of the previous subsections:
+
+@ftable @code
+@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
+@noindent
+The only effect of executing @samp{NOP} is increasing the location
+counter, while @samp{HLT} usually marks program termination.
+
+@node Execution times,  , Miscellaneous operators, MIX instruction set
+@comment  node-name,  next,  previous,  up
+@subsubsection Execution times
+
+@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.
+
+In the following table, the execution times (in the above mentioned
+arbitrary units) of the MIX instructions are given.
+
+@multitable {INSSSS} {01} {INSSSS} {01} {INSSSS} {01} {INSSSS} {01}
+@item @code{NOP} @tab 1 @tab @code{ADD} @tab 2 @tab @code{SUB}
+@tab 2 @tab @code{MUL} @tab 10
+@item @code{DIV} @tab 12 @tab @code{NUM} @tab 10 @tab @code{CHAR}
+@tab 10 @tab @code{HLT} @tab 10
+@item @code{SLx} @tab 2 @tab @code{SRx} @tab 2 @tab @code{LDx}
+@tab  2 @tab @code{STx} @tab 2 
+@item @code{JBUS} @tab 1 @tab @code{IOC} @tab 1 @tab @code{IN}
+@tab  1@tab @code{OUT} @tab 1
+@item @code{JRED} @tab 1 @tab @code{Jx} @tab 1 @tab @code{INCx}
+@tab  1 @tab @code{DECx} @tab 1 
+@item @code{ENTx} @tab 1 @tab @code{ENNx} @tab 1 @tab @code{CMPx}
+@tab  1 @tab @code{MOVE} @tab 1+F  
+@end multitable
+
+In the above table, 'F' stands for the number of blocks to be moved
+(given by the @code{FSPEC} subfield of the instruction); @code{SLx} and
+@code{SRx} are a short cut for the byte-shifting operations; @code{LDx}
+denote all the loading operations; @code{STx} are the storing
+operations; @code{Jx} stands for all the jump operations, and so on with
+the rest of abbreviations.
+
+@node MIXAL,  , The MIX computer, MIX and MIXAL tutorial
+@comment  node-name,  next,  previous,  up
+@section MIXAL
+@cindex MIXAL
+@cindex MIX assembly language
+@cindex assembly
+
+In the previous sections we have listed all the available MIX binary
+instructions. As we have shown, each instruction is represented by a
+word which is fetched from memory and executed by the MIX virtual
+CPU. As is the case with real computers, the MIX knows how to decode
+instructions in binary format (the so--called machine language), but a
+human programmer would have a tough time if she were to write her
+programs in machine language. Fortunately, 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 source files are translated
+to machine language by a MIX assembler, which produces a binary file (the
+actual MIX program) which can be directly loaded into the MIX memory and
+subsequently executed.
+
+In this section, we describe MIXAL, the MIX assembly language. The
+implementation of the MIX assembler program and MIX computer simulator
+provided by @sc{mdk} are described later on (@pxref{Getting started}).
+
+@menu
+* Basic structure::             Writing basic MIXAL programs.
+* MIXAL directives::            Assembler directives.
+* Expressions::                 Evaluation of expressions.
+* W-expressions::               Evaluation of w-expressions.
+* Local symbols::               Special symbol table entries.
+* Literal constants::           Specifying an immediate operand.
+@end menu
+
+@node Basic structure, MIXAL directives, MIXAL, MIXAL
+@comment  node-name,  next,  previous,  up
+@subsection Basic program structure
+
+The MIX assembler reads MIXAL files line by line, producing, when
+required, a binary instruction, which is associated to a predefined
+memory address. To keep track of the current address, the assembler
+maintains an internal location counter which is incremented each time an
+instruction is compiled. In addition to MIX instructions, you can
+include in MIXAL file assembly directives (or pseudoinstructions)
+addressed at the assembler itself (for instance, telling it where the
+program starts and ends, or to reposition the location counter; see below).
+
+MIX instructions and assembler directives@footnote{We shall call them,
+collectively, MIXAL instructions.} are written in MIXAL (one per
+source file line) according to the following pattern:
+
+@example
+[LABEL]   MNEMONIC  [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 current
+value of the location counter, and can be used in subsequent
+expressions.
+@item MNEMONIC
+Is a literal denoting the operation code of the instruction
+(e.g. @code{LDA}, @code{STA}; see @pxref{MIX instruction set}) 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.}.
+
+We have already listed the mnemonics associated will each MIX
+instructions; sample MIXAL instructions representing MIX instructions
+are:
+@example
+HERE     LDA  2000         HERE represents the current location counter
+         LDX  HERE,2(1:3)  this is a comment
+         JMP  1234
+@end example
+
+@node MIXAL directives, Expressions, Basic structure, MIXAL
+@comment  node-name,  next,  previous,  up
+@subsection MIXAL directives
+
+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
+
+The operand of @code{ORIG}, @code{EQU}, @code{CON} and @code{END} can be
+any expression evaluating to a constant MIX word, i.e., either a simple
+MIXAL expression (composed of numbers, symbols and binary operators,
+@pxref{Expressions}) or a w-expression (@pxref{W-expressions}).
+
+All MIXAL programs must contain an @code{END} directive, with a twofold
+end: first, it marks the end of the assembler job, and, in the second
+place, its (mandatory) operand indicates the start address for the
+compiled program (that is, the address at which the virtual MIX machine
+must begin fetching instructions after loading the program). It is also
+very common (although not mandatory) to include at least an @code{ORIG}
+directive to mark the initial value of the assembler's location counter
+(remember that it stores the address associated with each compiled MIX
+instruction). Thus, a minimal MIXAL program would be
+
+@example
+          ORIG  2000    set the initial compilation adress
+          NOP           this instruction will be loaded at adress 2000
+          HLT           and this one at address 2001
+          END   2000    end of program; execution will start at address 2000
+this line is not parsed by the assembler
+@end example
+@noindent
+The assembler will generate two binary instructions (@code{NOP} (@w{+ 00
+00 00 00 00}) and @code{HLT} (+ 00 00 02 05)), which will be loaded at
+addresses 2000 and 2001. Execution of the program will begin at address
+2000. Every MIXAL program should also include a @code{HLT} instruction,
+which will mark the end of program execution (but not of program
+compilation). 
+
+The @code{EQU} directive allows the definition of symbolic names for
+specific values. For instance, we could rewrite the above program as
+follows:
+
+@example
+START     EQU   2000
+          ORIG  START
+          NOP
+          HLT
+          END   START
+@end example
+@noindent
+which would give rise to the same compiled code. Symbolic constants (or
+symbols, for short) can also be implicitly defined placing them in the
+@code{LABEL} field of a MIXAL instruction: in this case, the assembler
+assigns to the symbol the value of the location counter before compiling
+the line. Hence, a third way of writing our trivial program is
+
+@example
+          ORIG  2000
+START     NOP
+          HLT
+          END   START
+@end example
+
+The @code{CON} directive allows you to directly specify the contents of
+the memory address pointed by the location counter. For instance, when
+the assembler encounters the following code snippet
+
+@example
+          ORIG  1150
+          CON   -1823473
+@end example
+@noindent
+it will assign to the memory cell number 1150 the contents @w{- 00 06 61
+11 49} (which corresponds to the decimal value -1823473). 
+
+Finally, the @code{ALF} directive let's you specify the memory contents
+as a set of five (quoted) characters, which are translated by the
+assembler to their byte values, conforming in that way the binary word
+that is to be stored in the corresponding memory cell. This directive
+comes in handy when you need to store printable messages in a memory
+address, as in the following example:
+
+@example
+          OUT  MSG       MSG is not yet defined here (future reference)
+MSG       ALF  "THIS "   MSG gets defined here
+          ALF  "IS A "
+          ALF  "MESSA"
+          ALF  "GE.  "
+@end example
+@noindent
+The above snippet also shows the use of a @dfn{future reference}, that
+is, the usage of a symbol (@code{MSG} in the example) prior of its actual
+definition. The MIXAL assembler is able to handle future references
+subject to some limitations which are described in the following section
+(@pxref{Expressions}).
+
+@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
+@code{MNEMONIC} 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, W-expressions, MIXAL directives, 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.
+
+The special binary operator @code{:} has the same meaning as in fspecs,
+i.e.,
+
+@example
+A:B = 8*A + B
+@end example
+@noindent
+while @code{A//B} stands for the quotient of the ten-byte number @w{@code{A} 00
+00 00 00 00} (that is, A right-padded with 5 null bytes or, what amounts
+to the same, multiplied by 64 to the fifth power) divided by
+@code{B}. Sample expressions are:
+
+@example
+18-8*3 = 30
+14/3 = 4
+1+3:11 = 4:11 = 43
+1//64 = (01 00 00 00 00 00)/(00 00 00 01 00) = (01 00 00 00 00 00)
+@end example
+@noindent
+Note that all MIXAL expressions evaluate to a MIX word (by definition).
+
+All symbols appearing within an expression must be previously 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 W-expressions, Local symbols, Expressions, MIXAL
+@comment  node-name,  next,  previous,  up
+@subsection W-expressions
+@cindex w-expressions
+
+Besides expressions, as described above (@pxref{Expressions}), the MIXAL
+assembler is able to handle the so called @dfn{w-expressions} as the
+operands of the directives @code{ORIG}, @code{EQU}, @code{CON} and
+@code{END} (@pxref{MIXAL directives}). The general form of a
+w-expression is the following:
+
+@example
+     WEXP = EXP[(EXP)][,WEXP]
+@end example
+@noindent
+where @code{EXP} stands for an expression and square brackets denote
+optional items. Thus, a w-expression is made by a regular expression
+followed by an optional expression between parenthesis, followed by any
+number of similar constructs separated by commas. Sample w-expressions
+are:
+
+@example
+2000
+235(3)
+S1+3(S2),3000
+S1,S2(3:5),23
+@end example
+
+W-expressions are evaluated as follows. First, all expressions are
+evaluated according to the rules given in the previous section. Thus, if
+we start with, say, @samp{S1+2(2:4)} where @samp{S1} equals 265230, we
+have @samp{265232(2:4)}. The expression between parenthesis must be a
+valid f-spec, for it specifies the bytes to be taken from the preceding
+word. In our example, we must take 3 bytes of the word @w{@samp{+ 00 01
+00 48 16}} (which is 265232), and store them in positions 2, 3 and 4 of
+the result, resulting in the new word @w{@samp{+ 00 00 48 16 00}} (i.e.,
+the decimal value 197632). When we have two expressions separated with a
+comma, we take, for each one, the subfield specified and compose the
+word to obtain the result. For instance, in the w-expression
+
+@example
+1(1:2),66(4:5)
+@end example
+@noindent
+we first take two bytes from 1 (00 and 01) and store them as bytes 1 and
+2 of the result (obtaining @w{@samp{+ 00 01 00 00 00}}) and, afterwards,
+take two bytes from 66 (01 and 02) and store them as bytes 4 and 5 of
+the result, obtaining @w{@samp{+ 00 01 00 01 02}} (262210). The process
+is repeated for each new comma-separated example. For instance:
+
+@example
+1(1:1),2(2:2),3(3:3),4(4:4) = 01 02 03 04 00
+@end example
+
+As stated before, w-expressions can only appear as the operands of MIXAL
+directives taking a constant value (@code{ORIG}, @code{EQU}, @code{CON}
+and @code{END}). Future references are @emph{not} allowed within
+w-expressions (i.e., all symbols appearing in a w-expression must be
+defined before they are used).
+
+@node Local symbols, Literal constants, W-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
+
+Note that a @code{B} local symbol never refers to a definition in its
+own line, that is, in the following program:
+
+@example
+		ORIG 1999
+ST		NOP
+3H		EQU 69
+3H		ENTA 3B  local symbol 3B refers to 3H in previous line
+		HLT
+		END ST
+@end example
+@noindent
+the contents of @samp{rA} is set to 69 and @emph{not} to 2001. An
+specially tricky case occurs when using local symbols in conjunction
+with @code{ORIG} pseudoinstructions. To wit@footnote{The author wants to
+thank Philip E. King for pointing these two special cases of local
+symbol usage to him.},
+
+@example
+		ORIG 1999 
+ST		NOP
+3H		CON 10
+		ENT1 *
+		LDA 3B
+** rI1 is 2001, rA is 10.  So far so good!
+3H		ORIG 3B+1000
+** at this point 3H equals 2003
+** and the location counter equals 3000.
+		ENT2 *
+		LDX 3B
+** rI2 contains 3000, rX contains 2003.
+		HLT
+		END ST
+@end example
+
+@node Literal constants,  , Local symbols, MIXAL
+@comment  node-name,  next,  previous,  up
+@subsection Literal constants
+@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{=wexp=}, where
+@code{exp} is an w-expression (@pxref{W-expressions}). 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
+
diff --git a/doc/ss_devices.png b/doc/ss_devices.png
new file mode 100644
index 0000000..bb2ee83
--- /dev/null
+++ b/doc/ss_devices.png
diff --git a/doc/ss_mix.png b/doc/ss_mix.png
new file mode 100644
index 0000000..9d0e6b6
--- /dev/null
+++ b/doc/ss_mix.png
diff --git a/doc/ss_mix.txt b/doc/ss_mix.txt
new file mode 100644
index 0000000..757026e
--- /dev/null
+++ b/doc/ss_mix.txt
@@ -0,0 +1,31 @@
+|-----------------------------------------------------------|
+|   Menu       	       	  	         	            |
+|-----------------------------------------------------------|
+|            	      	       	         	            |
+|            	      	       	         	            |
+|            	      	       	         	            |
+|      	   	      	       	         	            |
+|               MIXVM / MIXAL / Devices  	            |
+|                     	       	         	            |
+|          	   	       	         	            |
+|                              	         	            |
+|      			       	         	            |
+|      			       	         	            |
+|                              	         	            |
+|-----------------------------------------------------------|
+|      				         	            |
+|                     Command output     	            |
+|      				    		            |
+|      				    		            |
+|                                                           |
+|-----------------------------------------------------------|
+|                     Command prompt               	    |
+|-----------------------------------------------------------|
+|  Status bar						    |
+|-----------------------------------------------------------|
+       							    
+       							    
+       							    
+
+
+
diff --git a/doc/ss_mixal.png b/doc/ss_mixal.png
new file mode 100644
index 0000000..506a170
--- /dev/null
+++ b/doc/ss_mixal.png
diff --git a/doc/ss_worddlg.png b/doc/ss_worddlg.png
new file mode 100644
index 0000000..be6e7f2
--- /dev/null
+++ b/doc/ss_worddlg.png