Provided by: radiance_4R0+20110410-1build1_i386 bug

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)