mmstotex - a tool to convert mms files to TeX files
Content
mmstotex
A tool to convert mms programs to TeX format.Usage
mmstotex < input.mms > output.texThe 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 variablebecomes
&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.\crIf 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,0becomes:
& SET & \$1,0 & \crNo 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\crwhich
&&\dots&\it Arguments&&\rm Comment\crA 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,0becomes:
& &SET &\$255,0 &&Initialize\crOccasionally, 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,0would produce two files: init.tex containing
&Loop &SET &\$1,100 &&Initialize\crand 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 & Expressionand 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$.\crNote 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,0will 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 &\crand 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 \endmmsand 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
