# 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.

## Alignment of Code

We start here by describing the "normal" behavior of mmstotex and look at the exceptions in later sections. So information that appears later on this page is generally more reliable than information that appears earlier.

The input is considered to be a valid mms file. As such every line has the following form (optional parts are enclosed in square brackets):

[Label] Space Opcode [Space Arguments] [Space Comment]

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


Example:

i	OCTA 1 loop variable

becomes
        &i      &OCTA   &1      &&loop variable\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 optional Argument.

Example:

	SET t,5000; SUB a,a,t Subtract 5000.

becomes:
   &   &SET  &t,5000; SUB a,a,t &&Subtract 5000.\cr


### Line Numbers

You may have noticed that the output lines contain two empty columns, one at the very beginning of the line and one before the comment. The first one is the line number column, the other one the cycle count column (described below).

The cycle counts are usually not part of the mms file, and so they are not given in the output file. The column is left empty; the TeX style file (see below) is supposed to add appropriate code to add the line numbers later. The advantage of adding line numbers later is the greater flexibility.

### Cycle Counts

Many programs shown in The Art of Computer programming or in the MMIX Supplement are displayed together with cycle counts. To get material into the cycle count column, it is sufficient to split the comment into two parts by inserting an & character. For example:
Loop  SUB i,i,1  N & Decrement i.

becomes
  &Loop &SUB &i,i,1 &N & Decrement i.\cr

If the comment does not contain an & character, an empty column is added for the cycle count automatically.

### 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

No such replacement is done in the comments.

## Special Lines

Lines that start with a % character are special. These lines are treated by the mmixal assembler as comments and their content is irrelevant for the running program; their content is however relevant to mmstotex, as we will see.

### Verbatim Output

If a line starts with two % characters, the two characters %% are striped off and the rest of the line is copied verbatim to the output. You can use this to include arbitrary TeX code in your output. For example you can say
%%\noalign{\smallskip}

which simply becomes:
\noalign{\smallskip}

inserting a small amount of white space in the output. You even can insert a line of pseudo code with something like
%%&&\dots&\it Arguments&&\rm Comment\cr

which
&&\dots&\it Arguments&&\rm Comment\cr

A very common use of verbatim output is the use of three % characters like this:
%%%

which becomes
%

and because % is the comment character in TeX, lines that start with %%% are simply ignored by both TeX and mmixal.

### Switching output on and off

Often, we want the mms file to contain a complete program in order to be able to assemble and test it, but we want to show only the relevant lines as part of the TeX document. For this purpose, the output can be switched on an off using %%%on and %%%off at the beginning of a line (the remainder of the line is ignored).

For example

%%%off
******* Author Me, Date Now *****
LOC	#100
Main	IS	@
%%%on
SET	$255,0 Initialize %%%off TRAP 0,Halt,0  becomes:  & &SET &\$255,0 &&Initialize\cr

Occasionally, you want to present and explain the code step by step in small installments. For this purpose, you want to have the TeX code split into separate files that you can \input individually in your main TeX file. To do this, you can also use %%%on filename to redirect the output into the named file. For example:
%%%on init.tex
Loop	SET	$1,100 Initialize %%%off SUB$1,$1,1 %%%on control.tex BP$1,Loop Test
%%%off
TRAP	0,Halt,0

would produce two files: init.tex containing
   &Loop &SET &\$1,100 &&Initialize\cr  and control.tex containing  & &BP &\$1,Loop &&Test\cr


### Running times

There are special lines that start with %%%rt. These lines have the following format:
%%%rt Label & Expression

and will be output as
\rtref|Label|Expression|

These lines will insert a runtime reference into the output file. For a further description of this feature see mmstort.

This concludes the explanation of all lines that start with two or more % characters.

## mmixal Comments

If a line starts with a single % character, it is assumed that it contains a full line comment that is to be shown in the TeX file. It is indented so as to become flush left with the labels. For example
% The Loop starts here:
Loop SUB i,i,1  Decrement $i$.

becomes:
   &\rm  The Loop starts here:\hidewidth\cr
&Loop &SUB &i,i,1 &&Decrement $i$.\cr

Note how the control sequences \rm and \hidewidth\cr are automatically inserted to make the text appear like a normal comment.

This concludes the description of lines that start with a % character. There are, however, two cases that are closely related:

• If a line starts with spaces and then the first non-space character is an % character, it is assumed that this line contains an indented full line comment that should be shown as part of the TeX output, but again indented. Hence, the TeX output will contain an additional & character, which will align the comment with the opcodes. So from
     % The Loop starts here:
Loop SUB i,i,1  Decrement $i$.

we obtain:
 &     &\rm  The Loop starts here:\hidewidth\cr
&Loop &SUB &i,i,1 &&Decrement $i$.\cr


• If a line starts with a character that is not a % character and is not possibly the first character of a label, mmixal will treat it as a comment and mmstotex will do the same, however, the character starting the comment will not be suppressed, but will appear in the output. Special care is taken in case this character is an & in this case the \rm is placed after it and an extra & is suppressed. The situation is the same if the line starts with spaces, and then a character that is neither a % character nor the first character of an OPCODE.

To summarize:

% Hello!
& Hello!
\dots Hello!
% Hello!
& Hello!
\dots Hello!
Main TRAP  0,Halt,0

will result in
        &\rm  Hello!\hidewidth\cr
&\rm  Hello!\hidewidth\cr
&\rm \dots Hello!\hidewidth\cr
&       &\rm  Hello!\hidewidth\cr
&       &\rm  Hello!\hidewidth\cr
&       &\rm \dots Hello! \hidewidth\cr
&Main   &TRAP   &0,Halt,0       &\cr

and as you may expect.

To finish the treatment of comments, here is a final rule: If a regular comment, following the arguments column, starts with a % character, the initial % character will be suppressed. (Otherwise TeX would treat the rest of the line as comment.) Example:

Loop SUB i,i,1  % Decrement $i$.

will give:
  &Loop &SUB &i,i,1 && Decrement $i$.\cr


## Hiding Lines

Occasionally, you want to exclude a single line of code in the output file. Instead of using %%%off before the line and %%%on after this line, you can put an %%hide in the comment position at the end of the line. The line will then not appear in the output file. Example:
     SUB i,i,1  % Decrement $i$.
PUSHJ $255,DebugOutput %%hide  will give:  & &SUB &i,i,1 && Decrement$i$.\cr  ## Modifying the Display of Names The mmstotex program will allow you to display names using an arbitrary TeX code. In order to use this feature you have to start mmstotex with the option -t. If this is done, and you start the comment in a line defining a label with %%tex followed by some tex code. The given TeX code will from then on replace the label where ever it occurs in the code. Example: alpha IS$0             %%tex $\alpha$
Pprime  IS  $1 %%tex${\tt P}^\prime$P IS$2
SUB Pprime,P,alpha

will give:
 &$\alpha$         &IS  &\$0 &\cr &${\tt P}^\prime$&IS &\$1    &\cr
&P                &IS  &\$2 &\cr & &SUB &${\tt P}^\prime$,P,$\alpha$&\cr  In this example the TeX code$\alpha\$ will replace the word alpha whenever it is used as a label or as part of the arguments. Note that the TeX code must not contain spaces except following a control sequence.

## TeX Style File

There is a TeX style file, mmstotex.sty, (for the moment pure TeX not LaTeX) that can be used to typeset such programs. After you \input mmstotex.sty in your TeX file, you can write
\beginmms
\input myprogram.tex
\endmms

and your program contained in the file myprogram.tex generated from myprogram.mms using mmstotex will be typeset as expected, with line numbers starting at 01.

If you need to start the line numbers with some other value, you can say \nextmmsline{value} before \beginmms and the listing will start with line number value.

Similar is the the control sequence \lastmmsline{value}. It will cause the next listing to start with line number value+1.

If you need to refer to line numbers you can say \lineref|name| as part of the comment. This will produce an entry in the reference file that associates |name| with the line number of the current line. You can then say "As you can see from line |name| ... " or "\lastline{|name|}" to refer to this line number in your TeX file.

If you do not want to have line numbers at all, say \mmslinesoff before \beginmms .

If you have a really long program and need three digit line numbers, say \largemms.

## Sources

mmstotex is written as a short lex file mmstotex.l.

## Building mmstotex

Under Linux, to build mmstotex from the source file, you need to generate mmstotex.c using flex, then compile it together with symtab.c, and link it with the flex library. Both c files will need the include file symtab.h.
flex -o mmstotex.c  mmstotex.l
gcc mmstotex.c symtab.c -lfl -o mmstotex


## Executables

You can download an executable for 32-Bit Linux here: mmstotex and for OSX you find it here: mmstotex.

Please help to keep this site up to date! If you want to point out important material or projects that are not listed here, if you find errors or want to suggest improvements, please send email to