NAME
metafile - graphics command interface, similar to plot(5)
DESCRIPTION
The metafile graphics format was designed with the primary goal of
serving as a temporary file for routines which output to dot-matrix and
other line-at-a-time devices. As a result, all of the "primitives" are
completely self-contained to facilitate sorting.
A primitive is a command which can itself be plotted. Into this
catagory fall line segments, rectangle and triangle fills, matrix and
vector strings. Every primitive has a zeroeth argument which contains
bundled attribute information, and an extent. The extent gives the x
and y minimum and maximum values which enclose the primitive. The
extent is used in sorting, and typically also in describing the
primitive. For example, a line segment will be described completely by
its enclosing rectangle and attributes including specification of which
diagonal the segment falls on. Other primitives will have additional
arguments, such as vector string, which must specify the string to be
output within its extent.
"Global" commands separate the primitives and allow functions which
affect all commands. These are commands such as end of page, pause,
open and close segment, set, unset and reset, and a special global, end
of file. The end of file command is included to facilitate finding the
end of file on systems which do not keep track exactly. Global
commands sometimes have arguments. The open command, for instance,
specifies the name of the segment. Global commands never have extents.
The metafile commands are as follows:
F end of file: no arguments.
When end of file is reached, all processing stops.
E end of page: no arguments.
This causes the device to advance to the next screen or page. If
the output device is a terminal, it will beep and wait for the user
to hit return before clearing the screen.
P pause: arguments specify the message to be printed.
This causes output to be flushed and the controlling terminal to be
opened. The user is then prompted with the specified string
followed by the message "- (hit return to continue)". If no string
is specified, the bell is sounded without a message. After the user
hits return, output continues. This command is useful when the user
is required for some part of the output, such as changing paper or
pens.
D draw global: no arguments.
This global forces flushing of output and updating of device.
I include file: arg0 TRUE if standard file.
The include global causes the contents of the named file to be
substituted in the include command’s location. If arg0 is 1 (TRUE),
a standard location is searched if the file is not found in the
working directory. If arg0 is 0 (FALSE), the file must be in the
working directory. Include files can be nested to the number of
allowed open files.
S set: arg0 specifies what to set (from meta.h):
SALL: place context mark on current settings.
SPAT0: set pattern 0 to the specified value.
SPAT1: set pattern 1 to the specified value.
SPAT2: set pattern 2 to the specified value.
SPAT3: set pattern 3 to the specified value.
The set command is used to globally affect certain attributes. The
zeroeth argument specifies the variable to set, and the arguments
following specify the value. Pattern values can have two forms.
The first form begins with the letter ’P’, immediately followed by
an integer between 0 and 11. This selects one from the following
patterns: solid, thick \\\, thin \\\, mixed \\\, thick ///, thin
///, mixed ///, crisscross, web. The default pattern settings are:
0=P0, 1=P1, 2=P2, 3=P3. The second form gives the explicit values
for a pattern. The set all command makes a context mark with the
current settings. All settings which follow can be undone with the
unset all command.
U unset: arg0 specifies what to unset (from meta.h):
SALL: return to previous context.
SPAT0: set pattern 0 to the previous value.
SPAT1: set pattern 1 to the previous value.
SPAT2: set pattern 2 to the previous value.
SPAT3: set pattern 3 to the previous value.
The unset command returns a variable to its previous value. The
unset all command returns the settings to the values they had in the
previous context. If no context has been marked by set all,
variables are returned to their default values.
R reset: arg0 specifies what to reset (from meta.h):
SALL: reset all variables.
SPAT0: set pattern 0 to the default value.
SPAT1: set pattern 1 to the default value.
SPAT2: set pattern 2 to the default value.
SPAT3: set pattern 3 to the default value.
The reset command returns a variable to its default setting. The
reset all command returns all variables to their initial state.
O open segment: arguments specify segment name.
The commands following up to a C (close segment) are not to be
output, but are to be stored in the named segment. Segment names
can contain any ascii character (except newline) in any sequence of
reasonable length. Segment definitions are local to the enclosing
segment. Side effects should be avoided in segments by balancing
calls to set and unset. A segment cannot reference itself.
C close segment: no arguments.
The current segment is closed, which completes its usable
definition.
l line segment: fields of arg0 are:
100: orientation: positive slope, negative slope.
060: type: solid, dashed, dotted, dotted-dashed.
014: width: 0, 12, 24, 48, 96 units.
003: color: black, red, green, blue.
r rectangle fill: fields of arg0 are:
100: toggle: OR fill, XOR fill.
014: pattern: choice of 4 (see set).
003: color: black, red, green, blue.
Fills the given extent with the specified pattern. Toggle (XOR)
fill allows the reversal of previous fills to an area.
t triangle fill: fields of arg0 are:
100: toggle: OR fill, XOR fill.
060: orientation: right (& down), up, left, down.
014: pattern: choice of 4 (see set).
003: color: black, red, green, blue.
Fills the given half-rectangle with the specified pattern. A
triangle is oriented to the right if the the area between the
positive-sloped diagonal and the lower right corner of the extent is
filled. Rotating this triangle ccw successively yields up, left and
down triangles. Toggle (XOR) fill allows the reversal of previous
fills to an area.
p polygon fill: fields of arg0 are:
100: border: no border, line border.
060: orientation: right (& down), up, left, down.
014: pattern: choice of 4 (see set).
003: color: black, red, green, blue.
The argument string gives a blank separated list of the polygon
vertices in the form: "x0 y0 x1 y1 x2 y2 ... ". The coordinates
must be integers ranging between 0 and 16383. The bounding box and
orientation will be used to fit the original polygon into a scaled
and rotated position. The last vertex will be connected to the
first, and the polygon will be filled in with the specified pattern.
If a border is requested, one will be drawn of solid black zero
width lines. All polygon fills will toggle, therefore other polygon
and toggled triangle and rectangle fills will affect the final
appearance of the image. For example, a polygon drawn inside
another polygon of the same pattern will make a hole.
m matrix string: fields of arg0 are:
100: strike: single, double.
060: density: 10 cpi, 12 cpi, 17 cpi, 20 cpi.
014: size: normal, double width, double height, double both.
003: color: black, red, green, blue.
The upper left corner of the extent is used to place the beginning
of the string specified after the command. More sophisticated
drivers will use the extent for clipping, but the size of the
characters will not be altered.
v vector string: fields of arg0 are:
060: orientation: right, up, left, down.
014: thickness: 0, 12, 24, 48, 96 units.
003: color: black, red, green, blue.
The string specified following the command will be made to fit
within the given extent.
s print segment: fields of arg0 are:
060: orientation: right, up, left, down.
014: thickness: 0, 12, 24, 48, 96 units.
003: color: black, red, green, blue.
The segment whose name is specified in the arguments will be
oriented according to arg0 and made to fit in the given extent. The
thickness and color of the lines in the segment will be changed also
according to arg0. In the case of area fill, it is the pattern
rather than the width which will change. The segment must have been
previously defined using the open segment global. Note that matrix
strings will not transfer well since they cannot be oriented or
scaled.
The metafile has two basic formats. The first format is meant to be
user readable, and has the form:
c arg0 xmin ymin xmax ymax ‘args
Where c is the single letter command, arg0 is the octal value for arg0,
xmin ymin xmax ymax are the extent (ranging from 0 to 16283), and the
optional args following the backquote are additional arguments,
terminated by a newline. If the command is a global, the extent is not
present. If the global has no arg0, 0200 is appropriate. Any global
which has a following string must have a value for arg0 (< 0200).
Comments are permitted on lines beginning with a pound sign (’#’).
The second format is roughly equivalent, but packs the extrema into two
bytes each. It takes between one quarter and one third as much space,
and much less processing to use this type of file, hence it is the
default format for all of the programs. Conversion between formats is
accomplished with cv(1).
FILES
The standard location for metafiles used by the programs is
/usr/lib/meta/, but can be changed by setting the environment variable
MDIR. This is useful for systems where the owner does not have access
to the /usr/lib/ directory. It also allows the user to create his own
metafiles for vector characters and other symbols.
BUGS
The command for line segment (’l’) is awkward at best.
AUTHOR
Greg Ward
SEE ALSO
cv(1), meta(3), pexpand(1), primout(3), psort(1)