From 45834af29b940b3f0411ea2e1de91a0fe7d25141 Mon Sep 17 00:00:00 2001 From: Jose Antonio Ortega Ruiz Date: Wed, 4 Jun 2003 00:03:19 +0000 Subject: documentation for emacs support merged in one file (mdk_emacs.texi), substituting mdk_emixvm.texi and mdk_mixal-mode.texi. --- doc/Makefile.am | 7 +-- doc/mdk.texi | 152 ++++++++++++++++++++++++++++++++++++++++++++---- doc/mdk_emacs.texi | 136 +++++++++++++++++++++++++++++++++++++++++++ doc/mdk_emixvm.texi | 33 ----------- doc/mdk_gstart.texi | 4 +- doc/mdk_intro.texi | 8 ++- doc/mdk_mixal-mode.texi | 97 ------------------------------ doc/mdk_mixasm.texi | 4 +- 8 files changed, 291 insertions(+), 150 deletions(-) create mode 100644 doc/mdk_emacs.texi delete mode 100644 doc/mdk_emixvm.texi delete mode 100644 doc/mdk_mixal-mode.texi (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index 1ffa910..72b5318 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -10,17 +10,16 @@ # WITHOUT ANY WARRANTY, to the extent permitted by law; without even the # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -# $Id: Makefile.am,v 1.9 2003/06/02 23:20:38 jao Exp $ +# $Id: Makefile.am,v 1.10 2003/06/04 00:03:19 jao Exp $ SUBDIRS = img SUFFIXES = .html info_TEXINFOS = mdk.texi mdk_TEXINFOS = mdk_intro.texi mdk_ack.texi mdk_tut.texi mdk_gstart.texi \ - mdk_mixvm.texi mdk_emixvm.texi mdk_mixasm.texi mdk_bugs.texi \ + mdk_mixvm.texi mdk_emacs.texi mdk_mixasm.texi mdk_bugs.texi \ mdk_index.texi mdk_gmixvm.texi mdk_install.texi \ - mdk_mixguile.texi mdk_copying.texi mdk_findex.texi \ - mdk_mixal-mode.texi + mdk_mixguile.texi mdk_copying.texi mdk_findex.texi html_docs = mdk.html diff --git a/doc/mdk.texi b/doc/mdk.texi index 3eeb29d..72dc8ef 100644 --- a/doc/mdk.texi +++ b/doc/mdk.texi @@ -12,9 +12,9 @@ @end direntry -@set UPDATED April, 2002 -@set EDITION 1.0 -@set VERSION 1.0 +@set UPDATED June, 2003 +@set EDITION 1.0.1 +@set VERSION 1.0.1 @set JAO Jose Antonio Ortega Ruiz @set PHILIP Philip E. King @set PIETER Pieter E. J. Pareit @@ -97,10 +97,10 @@ General Public license (@pxref{Copying}), so that users are free to share and improve it. @value{PIETER} is the author of the Emacs @code{MIXAL} mode -(@pxref{mixal-mode.el}), and has also contributed many bug fixes. +(@pxref{MIXAL mode}), and has also contributed many bug fixes. @value{PHILIP} has contributed to this package development with many -helpful discussions, as well as actual code (@pxref{mixvm.el}). +helpful discussions, as well as actual code (@pxref{GUD integration}). @end ifinfo @@ -110,8 +110,7 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}). * Installing MDK:: Installing GNU MDK from the source tarball. * MIX and MIXAL tutorial:: Learn the innards of MIX and MIXAL. * Getting started:: Basic usage of the @sc{mdk} tools. -* mixal-mode.el:: Using Emacs to write MIX code. -* mixvm.el:: Using @code{mixvm} within Emacs. +* Emacs tools:: Programming the MIX using Emacs. * mixasm:: Invoking the MIXAL assembler. * mixvm:: Invoking and using the MIX virtual machine. * gmixvm:: Invoking and using the GTK+ virtual machine. @@ -121,6 +120,140 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}). * Concept Index:: Index of concepts. * Instructions and commands:: Index of MIXAL instructions and MIXVM commands. +@detailmenu + + +@detailmenu + --- The Detailed Node Listing --- + +Installing @sc{mdk} + +* Download:: +* Requirements:: +* Basic installation:: +* Emacs support:: +* Special configure flags:: +* Supported platforms:: + +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 programs. +* Using mixguile:: Using the Scheme interpreter to run and + debug your programs. +* Using Scheme in mixvm and gmixvm:: + +Running the program + +* Non-interactive mode:: Running your programs non-interactively. +* Interactive mode:: Running programs interactively. +* Debugging:: Commands for debugging your programs. + +Using @code{mixguile} + +* The mixguile shell:: Using the Scheme MIX virtual machine. +* Additional functions:: Scheme functions accessing the VM. +* Defining new functions:: Defining your own Scheme functions. +* Hook functions:: Using command and break hook functions. +* Scheme scripts:: + +Hook functions + +* Command hooks:: +* Break hooks:: + +Emacs tools + +* MIXAL mode:: Editing MIXAL files. +* GUD integration:: Invoking @code{mixvm} within Emacs. + +MIXAL mode + +* Basics:: Editing code, font locking and indentation. +* Help system:: Using the interactive help system. +* Compiling and running:: Invoking compiler and/or virtual machine. + +@code{mixasm}, the MIXAL assembler + +* Invoking @code{mixasm}:: @code{mixasm} options + +@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. +* Configuration commands:: Changing and storing mixvm settings. +* Scheme commands:: + +@code{gmixvm}, the GTK virtual machine + +* Invoking @code{gmixvm}:: Invoking the GTK+ interface. +* MIXVM console:: Using @code{mixvm} commands. +* MIX virtual machine:: The MIX virtual machine window. +* MIXAL source view:: Viewing the MIXAL source code. +* MIX devices view:: Device output. +* Menu and status bars:: Available menu commands. + +@code{mixguile}, the Scheme virtual machine + +* Invoking mixguile:: Command line options. +* Scheme functions reference:: Scheme functions accessing the VM. + +Scheme functions reference + +* mixvm wrappers:: Functions invoking mixvm commands. +* Hooks:: Adding hooks to mixvm commands. +* Additional VM functions:: Functions accessing the MIX virtual machine. + +Copying + +* GNU General Public License:: +* GNU Free Documentation License:: + +@end detailmenu @end menu @include mdk_intro.texi @@ -128,8 +261,7 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}). @include mdk_install.texi @include mdk_tut.texi @include mdk_gstart.texi -@include mdk_mixal-mode.texi -@include mdk_emixvm.texi +@include mdk_emacs.texi @include mdk_mixasm.texi @include mdk_mixvm.texi @include mdk_gmixvm.texi @@ -143,4 +275,4 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}). @contents @bye -$Id: mdk.texi,v 1.19 2003/06/02 23:20:38 jao Exp $ +$Id: mdk.texi,v 1.20 2003/06/04 00:03:19 jao Exp $ diff --git a/doc/mdk_emacs.texi b/doc/mdk_emacs.texi new file mode 100644 index 0000000..1fd848a --- /dev/null +++ b/doc/mdk_emacs.texi @@ -0,0 +1,136 @@ +@c -*-texinfo-*- +@c This is part of the GNU MDK Reference Manual. +@c Copyright (C) 2003 +@c Free Software Foundation, Inc. +@c See the file mdk.texi for copying conditions. + +@node Emacs tools, mixasm, Getting started, Top +@chapter Emacs tools + +Everyone writing code knows how important a good editor is. Most +systems already come with Emacs, and excellent programmer's editor. +@sc{mdk} adds support to Emacs for both writing and debugging MIX +programs. A major mode for MIXAL source files eases edition of your +code, while integration with Emacs' debugging interface +(@acronym{GUD}) lets you use @code{mixvm} without leaving your +favourite text editor. + +This chapter shows how to use the Elisp modules included in @sc{mdk}, +assuming that you have followed the installation instructions in +@xref{Emacs support}. + +@menu +* MIXAL mode:: Editing MIXAL files. +* GUD integration:: Invoking @code{mixvm} within Emacs. +@end menu + +@node MIXAL mode, GUD integration, Emacs tools, Emacs tools +@section MIXAL mode + +The module @file{mixal-mode.el} provides a new mode, mixal-mode, for +editing MIXAL source files@footnote{mixal-mode has been developed and +documented by @value{PIETER}}. When everything is installed correctly, +Emacs will select it as the major mode for editing files with extension +@code{.mixal}. You can also activate mixal-mode in any buffer +issuing the Emacs command @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, MIXAL mode +@comment node-name, next, previous, up +@subsection 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 +@comment node-name, next, previous, up +@subsection 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 +@comment node-name, next, previous, up +@subsection 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. + +@node GUD integration, , MIXAL mode, Emacs tools +@section GUD integration + +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_emixvm.texi b/doc/mdk_emixvm.texi deleted file mode 100644 index 4dd1cd5..0000000 --- a/doc/mdk_emixvm.texi +++ /dev/null @@ -1,33 +0,0 @@ -@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. - -@c $Id: mdk_emixvm.texi,v 1.5 2003/06/02 23:20:38 jao Exp $ - -@node mixvm.el, mixasm, mixal-mode.el, 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_gstart.texi b/doc/mdk_gstart.texi index d315279..b9e7766 100644 --- a/doc/mdk_gstart.texi +++ b/doc/mdk_gstart.texi @@ -4,9 +4,9 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_gstart.texi,v 1.14 2003/06/02 23:20:38 jao Exp $ +@c $Id: mdk_gstart.texi,v 1.15 2003/06/04 00:03:19 jao Exp $ -@node Getting started, mixal-mode.el, MIX and MIXAL tutorial, Top +@node Getting started, Emacs tools, MIX and MIXAL tutorial, Top @chapter Getting started @cindex tutorial diff --git a/doc/mdk_intro.texi b/doc/mdk_intro.texi index f7b5a8e..d695770 100644 --- a/doc/mdk_intro.texi +++ b/doc/mdk_intro.texi @@ -4,7 +4,7 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_intro.texi,v 1.6 2003/06/02 23:20:38 jao Exp $ +@c $Id: mdk_intro.texi,v 1.7 2003/06/04 00:03:19 jao Exp $ @node Introduction, Acknowledgments, Top, Top @comment node-name, next, previous, up @@ -45,9 +45,13 @@ functionality accessible through a graphical interface. @item mixguile A Guile shell, with an embedded MIX virtual machine and built-in commands to manipulate it using Scheme. +@item mixal-mode.el +An Emacs major mode for MIXAL source files editing, providing syntax +highlighting, documentation lookup and invocation of @code{mixvm} +within Emacs. @item mixvm.el This elisp program allows running @code{mixvm} inside an Emacs GUD -buffer, allowing concurrent edition and debugging of MIXAL programs. +buffer, providing concurrent edition and debugging of MIXAL programs. @end table @code{mixvm} and @code{gmixvm} implement a simulator of the MIX diff --git a/doc/mdk_mixal-mode.texi b/doc/mdk_mixal-mode.texi deleted file mode 100644 index a3d53b1..0000000 --- a/doc/mdk_mixal-mode.texi +++ /dev/null @@ -1,97 +0,0 @@ -@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. diff --git a/doc/mdk_mixasm.texi b/doc/mdk_mixasm.texi index 06d8736..c5d8765 100644 --- a/doc/mdk_mixasm.texi +++ b/doc/mdk_mixasm.texi @@ -4,9 +4,9 @@ @c Free Software Foundation, Inc. @c See the file mdk.texi for copying conditions. -@c $Id: mdk_mixasm.texi,v 1.6 2003/06/02 23:20:38 jao Exp $ +@c $Id: mdk_mixasm.texi,v 1.7 2003/06/04 00:03:19 jao Exp $ -@node mixasm, mixvm, mixvm.el, Top +@node mixasm, mixvm, Emacs tools, Top @comment node-name, next, previous, up @chapter @code{mixasm}, the MIXAL assembler @cindex @code{mixasm} -- cgit v1.2.3