M3TOTEX(1)

Name
m3totex - convert M3 program to TeX source

Syntax
m3totex [-raw] infile outfile
m3totex -example
m3totex -defs

Description
The command
    m3totex infile outfile
writes onto outfile a TeX source program that will typeset the Modula-3 program contained in infile, according to the typesetting rules described below. If outfile is omitted, then it is defaulted as follows: if infile is of the form a.i3, outfile is a.i.tex; if infile is of the form a.m3, outfile is a.m.tex; if infile is of the form a.frag, outfile is a.f.tex. The command
    m3totex -example
writes three files onto the current directory:
       Example.i3  * an interface illustrating m3totex comment conventions
       Example.tex * a latex file containing the boilerplate necessary to
                   * make a document with one section for Example.i3
       makefile    * a makefile with some useful targets

A good way to start using m3totex is to type
    m3totex -example
    make proof
in an empty directory; this will run m3totex, latex, dvips and psview to typeset the file Example.i3 and proof-read it on-line. Or type make print to print the document on your default printer. By default, the various TeX macros that the formatted Modula-3 programs use are defined at the start of outfile. Use the -raw option to prevent the definitions from appearing. The command
    m3totex -defs
writes a file called m3totex.tex onto the current directory. This file contains exactly the text that is not output when the -raw option is specified.

Typesetting Rules
All lines of infile up to and including the first blank line are skipped. (This makes it easy to omit the copyright notice from the typeset version, for example.) The portions of infile that are not in comments will be typeset verbatim, in typewriter font, obeying line breaks and indentation. Any characters that have special significance to TeX will be quoted. The portions of infile that are in comments will be treated differently depending on the position of the comment. There are three cases: 1. Comments that do not begin in the first column are typeset in a fixed-width font, including the "(*" and "*)" markers, obeying line breaks and indentation, just like program text. For example, if your program includes
    PROCEDURE P(VAR (*OUT*) x: INTEGER);
then the "(*OUT*)" will be typeset in typewriter font, just like rest of the line. 2. Comments that begin in the first column and are not preceded by a blank line are indented and typeset in slanted roman text, except that double-quoted expressions are typeset in slanted typewriter font. The purpose of this is to allow a brief comment after a procedure declaration, indicating what the procedure does. For example, here is the specification of "Path.LineTo":
    PROCEDURE LineTo(path: T; READONLY p: Point.T);
    (* Extend "path" with a linear segment that starts
       at its current point and ends at "p". *)
It is recommended that these slanted comments be kept brief; additional details can be provided in longer type 3 comments. 3. Comments that begin in the first column and are preceded by a blank line are typeset in a roman font and justified by TeX's usual rules to the document's margins. Items enclosed in double-quotes are set in unslanted typewriter font; for example, program identifiers should be double-quoted this way. Line breaks and indentation have no effect in these comments, since TeX is doing the line-breaking. For example, here is the specification of "Path.Close":
    PROCEDURE Close(path: T);
    (* Add a linear segment to create a closed loop in "path". *)
    (* More precisely, let "p" be the current point of "path", and let
      "q" be last point of "path" that was added by a call to "MoveTo".
      (Thus "q" is the startpoint of the first segment of the last subpath
      of "path".)  "Close" adds a linear segment from "p" to "q" and marks
      the sequence of segments from "q" to the end of the path as a closed
      subpath.  *)
Sometimes you want a portion of a comment to be treated verbatim, like program text---for example, when including an example program or a table. Therefore, m3totex treats any line that starts with "| " (vertical bar followed by space) like program text, typesetting it verbatim in typewriter font. For example, here is the specification of "Path.CurveTo":
    PROCEDURE CurveTo(path: T; READONLY q, r, s: Point.T);
    (* Extend "path" with a curved segment that starts
       at its current point and ends at "s".  *)
    (* "CurveTo" adds a curve that starts from the current point of "path"
       in the direction of "q", and ends at "s" coming from the direction
       of "r".  More precisely, let "p" be the current point of "path"
       and let "h(t)" and "v(t)" be the cubic polynomials such that

    | (h(0), v(0)) = p
    | (h(1), v(1)) = s
    | (h'(0), v'(0)) = 3 * (q - p)
    | (h'(1), v'(1)) = 3 * (s - r)
       (Where the primes denote differentiation with respect to "t".)
       Then "CurveTo" adds the segment "(h(t), v(t))" for "t" between zero
       and one.  (This is called the {\it Bezier} arc determined by "p",
       "q", "r", and "s".)  *)
Notice that the type-three comment included the TeX command "\it" to print "Bezier" in italic type. In general you can use TeX commands freely in type-three comments, but if you indulge yourself in this you may baffle programmers who read your interfaces on-line. Lines in type-three comments that begin with "| " are treated just like program text with one exception: you can slip in words in roman font by enclosing them in back-quotes. For example:
    PROCEDURE Map(path: T; map: MapObject)
      RAISES {Malformed};
    (* Apply the appropriate method of "map" to each segment of "path". *)

    (* That is, for each segment "s" of "path", in order, "Map" excecutes
       the following:

    | IF s `is a linear segment` (p, q) THEN
    |   IF s `was generated by` MoveTo THEN
    |      (* p = q *)
    |      map.move(p)
    |   ELSIF s `was generated by` LineTo THEN
    |     map.line(p, q)
    |   ELSE (* s `was generated by` Close *)
    |     map.close(p, q)
    |   END
    | ELSE (* s `is a curved segment` (p, q, r, s) *)
    |   map.curve(p, q, r, s)
    | END

    "Map" raises the exception if it is passed a malformed path. *)

Assumptions
We assume that the TeX or LaTex environment into which you include the TeX source contains the usual definitions of the following control sequences:
    \par \medskip \char \smallskip \noindent \rm
Furthermore the TeX source generated by m3totex uses local definitions of the following control sequences:
    \tab \progmode \procspec \display \indentation \tt \ignorerm
If you redefine any of these there could be unexpected results.

Error Messages
    ? can't read file
The given source file could not be opened for reading.
    ? can't write file
The target file could not be opened for writing (or, in -example mode, one of the example files could not be opened for writing).
    ? usage: m3ToTex name.extension [name.extension]
The command line was malformed.

Bugs
There is no way to include a literal double-quote within a double-quoted phrase in a comment.

Author Of Object
Greg Nelson. Marc H. Brown added -raw and -defs

Author Of Documentation
Greg Nelson