Quick Navigator

 Search Site Miscellaneous Server Agreement Year 2038 Credits

# Manual Reference Pages  -  M3TOTEX (1)

### Name

m3totex - convert M3 program to TeX source

### CONTENTS

Syntax
Description
Typesetting Rules
Assumptions
Error Messages
Bugs
Author Of Object
Author Of Documentation

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

Search for    or go to Top of page |  Section 1 |  Main Index

 M3TOTEX (1) -->

Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.