.\" Copyright (C) 1992, Digital Equipment Corporation
.\" All rights reserved.
.\" See the file COPYRIGHT for a full description.
.\"
.\" Last modified on Sat Oct 17 23:29:56 PDT 1992 by mhb                      .
.\"      modified on Tue Jul  7 13:15:26 PDT 1992 by muller                   .
.nh
.TH M3ZUME 1
.SH NAME
m3zume \- create Zeus IE (interesting event) stubs from event specs

.\"------------------------------------------------------------------------
.SH SYNTAX
.B m3zume
[-testdir <template directory>] <eventfile>

.\"------------------------------------------------------------------------
.SH DESCRIPTION

.PP
.B m3zume
takes a relatively terse specification of events for a Zeus
animation and produces from it the Modula-3 .i3 and .m3 files
that define the Zeus-mediated communication between the algorithm and
the views.  The event specification is a file named <eventfile>.evt.

M3zume reads the event file and combines it with template files
to produce derived files:

            <basename>AlgClass.{i3,m3}, 
            <basename>ViewClas.{i3,m3},
            <basename>IE.{i3,m3},
            <basename>TranscriptView.{i3,m3,fv}, and
            <basename>EventData.fv.  

where <basename> is the basename of the <eventfile>.

For testing purposes, the template file directory may be overridden
using the -testdir command-line option.

If Baz() is an event procedure defined in Foo.evt, then FooIE.Baz
is called to signal the occurrence of the event.

.SH FILE FORMAT
    
The main part of the event file is a list of slightly modified
Modula-3 headers for the procedures that the algorithm will call
to generate events.  Before any of these procedure headers, the
.evt file contains the IMPORT statements necessary to define the
procedure arguments, followed by a section introduced by the keyword
ALGDATA that contains the data fields that should belong to a
<basename>AlgClass.T.
    
The procedure headers use keywords OUTPUT, FEEDBACK, and UPDATE
in lieu of PROCEDURE.  Output events (PROCEDURE is allowed as a
synonym for OUTPUT) are generated by an algorithm and delivered
to views; they occur with VBT.mu unlocked and the algorithm Running.
Feedback events are delivered to the algorithm; they are typically
generated by a view.  Feedback events occur with VBT.mu locked and
the algorithm Paused.  Update events are generated by an algorithm
in response to feedback events and are delivered to views; they
occur with VBT.mu locked and the algorithm Paused.
    
Each argument type in a procedure header is followed by the name
of a function [in square brackets] that will convert the argument
to a printable TEXT.  This function name is generally
Fmt.<something>, or the empty string if the argument type is TEXT.
You don't need to IMPORT the Fmt interface, but you should IMPORT
any other interfaces needed for format conversion.

M3zume allows only a restricted set of argument types.  The names
of argument types may not contain blanks (for example, "REF BOOLEAN"
is not allowed); you may need to create an auxiliary interface that
gives names to the types you want to use in your .evt file.  Open
arrays are not allowed.  Default values for arguments are not
allowed.

Each event has an integer priority in the range 1-9, which Zeus
uses to decide whether to pause after the event while
single-stepping (1 means it's always OK to pause).  To specify a
priority, append the appropriate integer to the OUTPUT, FEEDBACK,
or PROCEDURE keyword.  Omitting the priority is the same as
specifying priority 1. Most users should omit priorities.

.SH
    *tem.{i3,m3,fv}              template files

.SH DIAGNOSTICS 

Poor.  Malformed event files may be accepted by the first phase of
m3zume processing, only to be rejected during the second phase (m3pp).
Even worse, if the first phase detects an error, the error message it
produces will only show up in the output file as an unparsable
statement flagged by m3pp.

.SH BUGS

The derived modules that m3zume produces may have unused interfaces,
variables, and/or procedures.  Expect a few warnings from the
compiler.

.SH CAVEAT TO WIZARDS

(Ignore this unless you have to modify a template file.)
The IMPORT statements in template files must have the word "IMPORT"
at the head of the line and have all the imports on a single line.
This simplifies the task of complying with Modula-3's restriction
that interfaces may be imported only once.

.SH AUTHOR OF OBJECT

John Hershberger

.SH AUTHOR OF DOCUMENTATION

John Hershberger