mmstotex
========
a Tool to convert mms programs to tex format

Usage
=====
mmstotex < input.mms > output.tex

The program reads an mms file from Standard Input and writes
a tex file to Standard Output.

As a Default, the program will copy the input file to the output file.
There are, however, a few exceptions:

Alignment of Code
=================
The input is considered to be a valid mms file. As such every line
has the  form

Optional Label Space Opcode Space Optional Arguments Space Comment

The Comment can be separated in an Analysis and a Comment part using a & sign. 
It has two forms: either Analysis & Comment or just Comment.

To be able to use the output in an \halign or tabular environment (LaTeX)
the different parts of a line are separated by & and the line ends with \cr.
Hence the output has the form:

Optional Label & Opcode & Optional Arguments & & Comment \cr
or 
Optional Label & Opcode & Optional Arguments & Analysis & Comment \cr
The extra &-sign is added if the comment does not contain one.

Example:

-------------------
i	OCTA 1 loop variable
Main	SET a,0 \hfil 1 & Initialize.
-------------------

becomes

-------------------
&i&OCTA&1&&loop variable\cr
&Main&SET&a,0&\hfil 1&Initialize.\cr
-------------------

Spaces are allowed inside the arguments if they are part of a string or a character
constant.

It is Possible to continue an instruction on the same line by using
a semicolon after the optional Argument. Such an Extension is put into
the same column of the \halign or tabular environment as the preceeding argument.

Example:

-------------------
	SET tmp,5000; SUM a,a,tmp Subtract 5000.
-------------------

becomes:

-------------------
&&SET&tmp,5000; SUM a,a,tmp&Subtract 5000.\cr
-------------------


Special Characters
==================
If the following characters  _ & | $ ^ { } \ ~ # %  are part of the
Optional Arguments in the input, they will be
preceded by a backslash in the output.
So they become  \_ \& \| \$ \^ \{ \} \\ \~ \# \%

Example:

-------------------
	SET	$1,0
-------------------

becomes:

-------------------
&&SET&\$1,0&&\cr
-------------------

mmixal Comments
===============

Sometimes a line in an mms file contains only comment.
If this comment starts with a letter, mmixal might confuse it with a Label
or an Opcode; therefore it is necessary to start such a comment with a special 
character to avoid the confusion. To account for this need of the assembler,
the first character of a comment is removed if this first character
is the percent sign '%'. So start the comment with a %-sign if you nedd this
character only to indicate a comment, but dont want it to be in the output.
If the %-sign is in the first column, the comment will start in the label column
if it is indented the comment will start in the opcode column, in both cases
the width of the comment is hidden.
If the line starts with two %-signes, the line is copied verbatim to the
tex output.

Example:

-------------------
%  The procedure
   %computes
   $a_0=b_0$
%%\noalign{smalskip}
-------------------

becomes:

-------------------
\omit\mmsstrut&\rm The procedure\hidewidth\cr
&&\rm  computes\hidewidth\cr
&&&&$a_0=b_0$\cr
\noalign{smalskip}
-------------------

mmixal-Only Text
================
If the output file should contain only parts of the 
input file, the parts that should not go to the output
can be enclosed in %%off and %%on
The %%on and %%off both should start a line (there might be preceeding spaces).
The text beween these lines will go to the output.

Example:

-------------------
%%off
******* Author Me Date Now *****
	LOC	#100
Main	IS	@
%%on
	SET	$1,0	Initialize
%%off
	TRAP	0,Halt,0
-------------------

becomes:

-------------------
&&SET&\$1,0&&Initialize\cr
-------------------

Alternatively, the line can end with %%hide. These lines will not go to the output.

Example
-------------------
	LOC	#100	%%hide
Main	IS	@	%%hide
	SET	$1,0	Initialize %%hide
	TRAP	0,Halt,0
-------------------
becomes:

-------------------
&&TRAP&0,Halt,0\cr
-------------------


Long Arguments
==============
sometimes arguments are so long that you want them to stick
into the space reserved for comments (which better should be empty).
You can achive this by having the comment start with \hidewidth.

Example
--------------
	SET thelongname,thelongvalue \hidewidth \qquad Set it.
-------------------
becomes:

-------------------
&&SET&thelongname,thelongvalue \hidewidth&&\quad Set it.\cr
-------------------

Defining how symbols appear in tex.
===================================

It is possible to define how symbols appear when printed with tex
you can start a line like this

%%def symbol texreplacement

and from then on, the symbol, if found as label or part of the
arguments will be replaced in the output by the texreplacement.
Note that the texrepalcement must not contain any blank space.

Alternatively, you can take the line where the symbol occurs as
a label and begin the comment with %%def texreplacement 
Note that the texreplacement must be separated from a following comment by spaces.
Starting with the next line (unfortunately not with the current line),
the symbol will be replaced by the new texreplacement.

Example
--------------
%%def a0 $a_0$
a0   IS	  $1               Define $a_0$
b0   IS   $2   %%def $b_0$ Define $b_0$.
     SET b0,a0             Set.
-------------------

becomes:

-------------------
&$a_0$ &IS  &\$1         & &Define $a_0$\cr
&b0    &IS  &\$2         & &Define $b_0$.\cr
&      &SET &$b_0$,$a_0$ & &Set.\cr
-------------------