initial revision, with minor editing of Pieter's original documentation.

1 files changed, 97 insertions, 0 deletions

diff --git a/doc/mdk_mixal-mode.texi b/doc/mdk_mixal-mode.texi
new file mode 100644
index 0000000..a3d53b1
--- /dev/null
+++ b/doc/mdk_mixal-mode.texi
@@ -0,0 +1,97 @@
+@c -*-texinfo-*-
+@c This is part of the GNU MDK Reference Manual.
+@c Copyright (C) 2000, 2001, 2003
+@c   Free Software Foundation, Inc.
+@c See the file mdk.texi for copying conditions.
+
+@node mixal-mode.el, mixvm.el, Getting started, Top
+@comment  node-name,  next,  previous,  up
+@chapter mixal-mode.el
+
+Everyone writing code will know how important a good editor is. Most
+systems already come with Emacs. @sc{mdk} adds support to Emacs for
+both writing and debugging MIX programs, see (@pxref{Emacs support})
+for installing instructions. This chapter discusses the support for the
+writing code, see (@pxref{mixvm.el}) for the discussion of the MIX
+virtual machine support.
+
+When everything is installed correctly, Emacs will select the right
+mode for editing files ending with @code{.mixal}. If however you would
+want to load mixal-mode on another file, you can do so with @code{M-x
+mixal-mode}.
+
+@menu
+* Basics::                      Editing code, font locking and indentation.
+* Help system::                 Using the interactive help system.
+* Compiling and running::       Invoking compiler and/or virtual machine.
+@end menu
+
+@node Basics, Help system, mixal-mode.el, mixal-mode.el
+@comment node-name, next, previous, up
+@section Basics
+
+The mode for editing mixal source files is inherited from
+fundamental-mode, meaning that all your favorite editing operations
+will still work. If you want a short introduction to Emacs, type
+@kbd{C-h t} inside Emacs to start the tutorial.
+
+Mixal mode adds font locking. If you do not have font locking globally
+enabled, you can turn it on for mixal-mode by placing the following
+line in your @file{.emacs} file:
+
+@lisp
+(add-hook 'mixal-mode-hook 'turn-on-font-lock)
+@end lisp
+
+You can also customize the colors used to colour your mixal code by
+changing the requisite faces. This is the list of faces used by
+mixal-mode:
+
+@itemize
+@item @var{font-lock-comment-face}
+Face to use for comments.
+@item @var{mixal-font-lock-label-face}
+Face to use for label names.
+@item @var{mixal-font-lock-operation-code-face}
+Face to use for operation code names.
+@item @var{mixal-font-lock-assembly-pseudoinstruction-face}
+Face to use for assembly pseudo-instruction names.
+@end itemize
+
+@node Help system, Compiling and running, Basics, mixal-mode.el
+@comment node-name, next, previous, up
+@section Help system
+
+When coding your program, you will be thinking, looking up
+documentation and editing files. Emacs already helps you with editing
+files, but Emacs can do much more. In particular, looking up
+documentation is one of its strong points. Besides the info system
+(which you are probably already using), mixal-mode defines commands
+for getting particular information about a MIX operation code.
+
+With @kbd{M-x mixal-describe-operation-code} (or its keyboard shortcut
+@kbd{C-h o}) you will get the documentation about a particular MIX
+operation code. Keep in mind that these are not assembly (MIXAL)
+pseudoinstructions. When the @code{point} is around a MIXAL
+pseudoinstruction in your source file, Emacs will recognize it and
+will suggest the right MIX operation code.
+
+@node Compiling and running, , Help system, mixal-mode.el
+@comment node-name, next, previous, up
+@section Compiling and running
+
+After you have written your MIXAL program, you'll probably want to
+test it. This can be done with the MIX virtual machine. First you will
+need to compile your code into MIX byte code. This can be done within
+Emacs with the command @kbd{M-x compile} (@kbd{C-c c}). In case of
+compilation errors, you can jump to the offending source code line
+with @kbd{M-x next-error}.
+
+Once the program compiles without errors, you can debug or run
+it. To invoke the debugger, use @kbd{M-x mixal-debug} (@kbd{C-c d}).
+Emacs will open a @code{GUD} buffer where you can
+use the debugging commands described in @xref{mixvm}.
+
+If you just want to execute the program, you can do so with @kbd{M-x
+mixal-run} (@kbd{C-c r}). This will invoke mixvm,
+execute the program and show its output in a separate buffer.