GRAP(1)                 FreeBSD General Commands Manual                GRAP(1)

NNAAMMEE
     ggrraapp - Kernighan and Bentley's language for typesetting graphs

SSYYNNOOPPSSIISS
     ggrraapp [--dd _d_e_f_i_n_e_s___f_i_l_e] [--DD] [--MM _i_n_c_l_u_d_e _p_a_t_h] [--vv] [--uu] [--CC] [--cc] [--hh]
          [_f_i_l_e_n_a_m_e _._._.]

DDEESSCCRRIIPPTTIIOONN
     ggrraapp is an implementation of Kernighan and Bentley's language for type-
     setting graphs, as described in ``Grap-A Language for Typesetting Graphs,
     Tutorial and User Manual,'' by Jon L. Bentley and Brian W.  Kernighan,
     revised May 1991, which is the primary source for information on how to
     use ggrraapp.  As of this writing, it is available electronically at
     http://www.kohala.com/start/troff/cstr114.ps

     This version is a black box implementation of ggrraapp, and some inconsisten-
     cies are to be expected.  The remainder of this manual page will briefly
     outline the ggrraapp language as implemented here.

     ggrraapp is a pic(1) pre-processor.  It takes commands embedded in a troff(1)
     source file which are surrounded by ..GG11 and ..GG22 macros, and rewrites them
     into pic commands to display the graph.  Other lines are copied.  Output
     is always to the standard output, which is usually redirected.  Input is
     from the given _f_i_l_e_n_a_m_es, which are read in order.  A _f_i_l_e_n_a_m_e of -- is
     the standard input.  If no _f_i_l_e_n_a_m_es are given, input is read from the
     standard input.

     Because ggrraapp is a pic preprocessor, and gnu pic will output TeX, it is
     possible to use ggrraapp with TeX.

     The --dd option specifies a file of macro definitions to be read at
     startup, and defaults to /usr/local/share/grap/grap.defines.  The --DD
     option inhibits the reading of any initial macros file.  The defines file
     can also be given using the GRAP_DEFINES environment variable. (See
     below).

     --vv prints the version information on the standard output and exits.
     ----vveerrssiioonn is a synonym for --vv.

     --uu makes labels unaligned by default.  This version of ggrraapp uses new fea-
     tures of GNU pic to align the left and right labels with the axes, that
     is that the left and right labels run at right angles to the text of the
     paper.  This may be useful in porting old ggrraapp programs.  --cc makes plot
     strings unclipped by default.  Some versions of ggrraapp allow users to place
     a string anywhere in the coordinate space, rather than only in the frame.
     By default this version of ggrraapp does not plot any string centered outside
     the frame.  --cc allows strings to be placed anywhere.  See also the
     cclliippppeedd and uunncclliippppeedd string modifiers described in the pplloott statement.

     --MM is followed by a colon-separated list of directories used to search
     for relative pathnames included via ccooppyy.  The path is also used to
     locate the defines file, so if the --dd changes the defines file name to a
     relative name, it will be searched for in the path given by --MM.  The
     search path always includes the current directory, and by default that
     directory is searched last.

     All ggrraapp commands are included between ..GG11 and ..GG22 macros, which are con-
     sumed by ggrraapp.  The output contains pic between ..PPSS and ..PPEE macros.  Any
     arguments to the ..GG11 macro in the input are arguments to the ..PPSS macro in
     the output, so graphs can be scaled just like pic diagrams.  If --CC is
     given, any macro beginning with .G1 or .G2 is treated as a .G1 or .G2
     macro, for compatibility with old versions of troff.  Using --CC also
     forces pure troff syntax on embedded font change commands when strings
     have the ssiizzee attribute, and all strings to be uunncclliippppeedd.

     The --hh flag prints a brief help message and exist.  ----hheellpp is a synonym
     for --hh.

     It is possible for someone to cause ggrraapp to fail by passing a bad format
     string and data to the sspprriinnttff command.  If ggrraapp is integrated as part of
     the printing system, this could conceivably provided a path to breaching
     security on the machine.  If you choose to use ggrraapp as part of a printing
     system run by the super-user, you should disable sspprriinnttff commands.  This
     can be done by calling ggrraapp with the --SS flag, setting the GRAP_SAFER
     environment variable, or compiling with the GRAP_SAFER preprocessor sym-
     bol defined.  (The GNU configure script included with ggrraapp will define
     that preprocessor symbol if the ----wwiitthh--ggrraapp--ssaaffee option is given.)

     The ggrraapp commands are sketched below.  Refer to Kernighan and Bentley's
     paper for the details.

     New versions of groff(1) will invoke ggrraapp if --GG is given.

   CCoommmmaannddss

     Commands are separated from one another by newlines or semicolons (;).

     ffrraammee [_l_i_n_e___d_e_s_c_r_i_p_t_i_o_n] [hhtt _h_e_i_g_h_t | wwiidd _w_i_d_t_h] [[(ttoopp|bboottttoomm|lleefftt|
     rriigghhtt) _l_i_n_e___d_e_s_c_r_i_p_t_i_o_n] ...]

     ffrraammee [hhtt _h_e_i_g_h_t | wwiidd _w_i_d_t_h] [_l_i_n_e___d_e_s_c_r_i_p_t_i_o_n] [[(ttoopp|bboottttoomm|lleefftt|
     rriigghhtt) _l_i_n_e___d_e_s_c_r_i_p_t_i_o_n] ...]

           This   describes   how   the  axes  for  the  graph  are  drawn.  A
           _l_i_n_e___d_e_s_c_r_i_p_t_i_o_n is a pic line description, e.g.,  dashed  0.5,  or
           the  literal  solid.   If  the first _l_i_n_e___d_e_s_c_r_i_p_t_i_o_n is given, the
           frame is drawn with that style.  The default is solid.  The  height
           and  width  of  the  frame  can  also  be specified in inches.  The
           default line style can be over-ridden for sides  of  the  frame  by
           specifying additional parameters to ffrraammee.

           If no plotting commands have been given before the ffrraammee command is
           issued, the frame will be output at  that  point  in  the  plotting
           stream  relative  to embedded troff or pic commands.  Otherwise the
           frame is output before the first  plotted  object  (even  invisible
           ones).

     ccoooorrdd [_n_a_m_e] [xx _e_x_p_r, _e_x_p_r] [yy _e_x_p_r, _e_x_p_r] [lloogg xx | lloogg yy | lloogg lloogg]

           The  ccoooorrdd command specifies a new coordinate system or sets limits
           on the default system.  It defines the largest and smallest  values
           that  can  be  plotted,  and therefore the scale of the data in the
           frame.  The limits for the x and y coordinate systems can be  given
           separately.  If a _n_a_m_e is given, that coordinate system is defined,
           if not the default system is modified.

           A coordinate system created by one ccoooorrdd command may be modified by
           subsequent ccoooorrdd commands.  A ggrraapp program may declare a coordinate
           space using ccoooorrdd, ccooppyy a file of data through a macro  that  plots
           the  data and finds its maxima and minima, and then define the size
           of the coordinate system with a second ccoooorrdd statement.

           This command also determines if a scale is plotted logarithmically.
           lloogg lloogg means the same thing as lloogg xx lloogg yy.

     ddrraaww [_l_i_n_e___n_a_m_e] [_l_i_n_e___d_e_s_c_r_i_p_t_i_o_n] [_p_l_o_t___s_t_r_i_n_g]

           The  ddrraaww command defines the style with which a given line will be
           plotted.  If _l_i_n_e___n_a_m_e is given, the style is associated with  that
           name,  otherwise  the  default style is set.  _l_i_n_e___d_e_s_c_r_i_p_t_i_o_n is a
           pic line description, and the optional _p_l_o_t___s_t_r_i_n_g is a  string  to
           be  centered at each point.  The default line description is invis,
           and the default plotting string is a centered bullet, so by default
           each point is a filled circle, and they are unconnected.  If points
           are being connected, each ddrraaww command ends any  current  line  and
           begins a new one.

           When  defining  a  line style, that is the first ddrraaww command for a
           given line name, specifying no plot string means that there are  to
           be  no  plot  strings.  Omitting the plot string on subsequent ddrraaww
           commands addressing the same named line means  not  to  change  the
           plot  string.   If  a line has been defined with a plot string, and
           the format is changed by a  subsequent  ddrraaww  statement,  the  plot
           string can be removed by specifying "" in the ddrraaww statement.

           The  plot  string  can  have  its  format  changed  through several
           string_modifiers.  String_modifiers are described in  the  descrip-
           tion of the pplloott command.

           nneeww is a synonym for ddrraaww.

     nneexxtt [_l_i_n_e___n_a_m_e] aatt [_c_o_o_r_d_i_n_a_t_e_s___n_a_m_e] _e_x_p_r, _e_x_p_r [_l_i_n_e___d_e_s_c_r_i_p_t_i_o_n]

           The  nneexxtt  command plots the given point using the line style given
           by _l_i_n_e___n_a_m_e, or the default if none is  given.   If  _l_i_n_e___n_a_m_e  is
           given,  it  should have been defined by an earlier ddrraaww command, if
           not a new line style with that name  is  created,  initialized  the
           same  way  as  the  default  style.   The  two expressions give the
           point's x and y values, relative to the optional coordinate system.
           That  system  should have been defined by an earlier ccoooorrdd command,
           if not, grap will exit.  If the optional _l_i_n_e___d_e_s_c_r_i_p_t_i_o_n is given,
           it  overrides  the  style's  default  line description.  You cannot
           over-ride the plotting string.  To use a different plotting  string
           use the pplloott command.

           The  coordinates  may optionally be enclosed in parentheses: (_e_x_p_r,
           _e_x_p_r)

     _q_u_o_t_e_d___s_t_r_i_n_g [_s_t_r_i_n_g___m_o_d_i_f_i_e_r_s] [, _q_u_o_t_e_d___s_t_r_i_n_g [_s_t_r_i_n_g___m_o_d_i_f_i_e_r_s]] ...
     aatt [_c_o_o_r_d_i_n_a_t_e_s___n_a_m_e] _e_x_p_r, _e_x_p_r

     pplloott _e_x_p_r [_f_o_r_m_a_t___s_t_r_i_n_g] aatt [_c_o_o_r_d_i_n_a_t_e_s___n_a_m_e] _e_x_p_r, _e_x_p_r

           These commands both plot a string at the given point.  In the first
           case the  literal  strings  are  stacked  above  each  other.   The
           string_modifiers  include  the  pic justification modifiers (lljjuusstt,
           rrjjuusstt, aabboovvee, and bbeellooww), and absolute and relative size modifiers.
           See  the pic documentation for the description of the justification
           modifiers.  ggrraapp also supports the aalliiggnneedd and uunnaalliiggnneedd  modifiers
           which are briefly noted in the description of the llaabbeell command.

           Strings  placed by either format of the pplloott command are restricted
           to being within the frame.  This can  be  overriden  by  using  the
           uunncclliippppeedd  attribute, which allows a string to be plotted in or out
           of the frame.  The --cc and --CC flags set uunncclliippppeedd  on  all  strings,
           and  to  prevent a string from being plotted outside the frame when
           those flags are active, the cclliippppeedd attribute can be used to retore
           clipping  behavior.   Though cclliippppeedd or uunncclliippppeedd can be applied to
           any string, it only has meaning for pplloott statements.

           size _e_x_p_r sets the string size to _e_x_p_r points.  If _e_x_p_r is preceded
           by  a  +  or  -,  the  size  is increased or decreased by that many
           points.

           In the second version, the _e_x_p_r is converted to a string and placed
           on  the  graph.   _f_o_r_m_a_t___s_t_r_i_n_g is a printf(3) format string.  Only
           formatting escapes for printing floating point numbers make  sense.
           The  format string is only respected if the sspprriinnttff command is also
           active.  See the description of sspprriinnttff for  the  various  ways  to
           disable it.  PPlloott and sspprriinnttff respond differently when ggrraapp is run-
           ning safely.  SSpprriinnttff ignores any  arguments,  passing  the  format
           string  through  without  substitution.   pplloott  ignores  the format
           string completely, plotting _e_x_p_r using the "%g" format.

           Points are specified the same way as for nneexxtt  commands,  with  the
           same consequences for undefined coordinate systems.

           The  second  form  of this command is because the first form can be
           used with a ggrraapp sspprriinnttff expression (See _E_x_p_r_e_s_s_i_o_n_s).

     ttiicckkss (lleefftt|rriigghhtt|ttoopp|bboottttoomm)[ (iinn|oouutt) [_e_x_p_r]] [oonn||aauuttoo _c_o_o_r_d___n_a_m_e]

     ttiicckkss (lleefftt|rriigghhtt|ttoopp|bboottttoomm) (iinn|oouutt) [_e_x_p_r] [uupp _e_x_p_r | ddoowwnn _e_x_p_r | lleefftt
     _e_x_p_r | rriigghhtt _e_x_p_r] aatt [_c_o_o_r_d___n_a_m_e] _e_x_p_r [_f_o_r_m_a_t___s_t_r_i_n_g] [[, _e_x_p_r
     [_f_o_r_m_a_t___s_t_r_i_n_g]] ...]

     ttiicckkss (lleefftt|rriigghhtt|ttoopp|bboottttoomm) (iinn|oouutt) [_e_x_p_r] [uupp _e_x_p_r | ddoowwnn _e_x_p_r | lleefftt
     _e_x_p_r | rriigghhtt _e_x_p_r] ffrroomm [coord_name] _s_t_a_r_t___e_x_p_r ttoo _e_n_d___e_x_p_r [bbyy [+|-|*|/]
     _b_y___e_x_p_r] [format_string]

     ttiicckkss [lleefftt|rriigghhtt|ttoopp|bboottttoomm] ooffff

           This command controls the placement of  ticks  on  the  frame.   By
           default,  ticks  are automatically generated on the left and bottom
           sides of the frame.

           The first version of this command turns on the automatic tick  gen-
           eration  for  a  given  side.  The iinn or oouutt parameter controls the
           direction and length of the ticks.  If a _c_o_o_r_d___n_a_m_e  is  specified,
           the ticks are automatically generated using that coordinate system.
           If no system is specified, the default coordinate system  is  used.
           As  with  nneexxtt  and  pplloott,  the  coordinate system must be declared
           before the ttiicckkss statement that references  it.   This  syntax  for
           requesting  automatically generated ticks is an extension, and will
           not port to older ggrraapp implementations.

           The second version of the ttiicckkss  command  overrides  the  automatic
           placement of the ticks by specifying a list of coordinates at which
           to place the ticks.  If the ticks are not defined with  respect  to
           the  default  coordinate  system,  the _c_o_o_r_d___n_a_m_e parameter must be
           given.  For each tick a printf(3) style format string can be given.
           The  _f_o_r_m_a_t___s_t_r_i_n_g  defaults  to  "%g".  The format string can also
           take string modifiers as described in the pplloott command.   To  place
           ticks with no labels, specify _f_o_r_m_a_t___s_t_r_i_n_g as "".

           If  sspprriinnttff  is disabled, ttiicckkss behaves as pplloott with respect to the
           format string.

           The labels on the ticks may be shifted by  specifying  a  direction
           and  the  distance  in  inches  to  offset  the label.  That is the
           optional direction and expression immediately preceding the aatt.

           The third format of the ttiicckkss command over-rides the  default  tick
           generation with a set of ticks ar regular intervals.  The syntax is
           reminiscent of programming language for loops.   Ticks  are  placed
           starting  at  _s_t_a_r_t___e_x_p_r ending at _e_n_d___e_x_p_r one unit apart.  If the
           bbyy clause is specified, ticks are _b_y___e_x_p_r units apart.  If an oper-
           ator appears before _b_y___e_x_p_r each tick is operated on by that opera-
           tor instead of +.  For example

                       ticks left out from 2 to 32 by *2

           will put ticks at 2, 4, 8, 16, and 32.  If _f_o_r_m_a_t___s_t_r_i_n_g is  speci-
           fied, all ticks are formatted using it.

           The parameters preceding the ffrroomm act as described above.

           The aatt and ffoorr forms of tick command may both be issued on the same
           side of a frame.  For example:

                       ticks left out from 2 to 32 by *2
                       ticks left in 3, 5, 7

           will put ticks on the left side of the frame pointing out at 2,  4,
           8, 16, and 32 and in at 3, 5, and 7.

           The  final  form  of  ttiicckkss turns off ticks on a given side.  If no
           side is given the ticks for all sides are cancelled.

           ttiicckk is a synonym for ttiicckkss.

     ggrriidd (lleefftt|rriigghhtt|ttoopp|bboottttoomm) [ticks off] [_l_i_n_e___d_e_s_c_r_i_p_t_i_o_n] [uupp _e_x_p_r |
     ddoowwnn _e_x_p_r | lleefftt _e_x_p_r | rriigghhtt _e_x_p_r] [oonn||aauuttoo [_c_o_o_r_d___n_a_m_e]]

     ggrriidd (lleefftt|rriigghhtt|ttoopp|bboottttoomm) [ticks off] [_l_i_n_e___d_e_s_c_r_i_p_t_i_o_n] [uupp _e_x_p_r |
     ddoowwnn _e_x_p_r | lleefftt _e_x_p_r | rriigghhtt _e_x_p_r] aatt [_c_o_o_r_d___n_a_m_e] _e_x_p_r [_f_o_r_m_a_t___s_t_r_i_n_g]
     [[, _e_x_p_r [_f_o_r_m_a_t___s_t_r_i_n_g]] ...]

     ggrriidd (lleefftt|rriigghhtt|ttoopp|bboottttoomm) [ticks off] [_l_i_n_e___d_e_s_c_r_i_p_t_i_o_n] [uupp _e_x_p_r |
     ddoowwnn _e_x_p_r | lleefftt _e_x_p_r | rriigghhtt _e_x_p_r] ffrroomm [coord_name] _s_t_a_r_t___e_x_p_r ttoo
     _e_n_d___e_x_p_r [bbyy [+|-|*|/] _b_y___e_x_p_r] [format_string]

           The  ggrriidd  command is similar to the ttiicckkss command except that ggrriidd
           specifies the placement of lines in the frame.  The syntax is simi-
           lar to ttiicckkss as well.

           By  specifying ticks off in the command, no ticks are drawn on that
           side of the frame.  If ticks appear on a side by default,  or  have
           been  declared  by  an  earlier ttiicckkss command, ggrriidd does not cancel
           them unless ticks off is specified.

           Instead of a direction for ticks, ggrriidd allows the user  to  pick  a
           line  description  for the grid lines.  The usual pic line descrip-
           tions are allowed.

           Grids are labelled by default.  To omit labels, specify the  format
           string as "".

           If  sspprriinnttff  is  disabled, ggrriidd behaves as pplloott with respect to the
           format string.

     llaabbeell (lleefftt|rriigghhtt|ttoopp|bboottttoomm) _q_u_o_t_e_d___s_t_r_i_n_g [_s_t_r_i_n_g___m_o_d_i_f_i_e_r_s] [,
     _q_u_o_t_e_d___s_t_r_i_n_g [_s_t_r_i_n_g___m_o_d_i_f_i_e_r_s]] ...  [uupp _e_x_p_r | ddoowwnn _e_x_p_r | lleefftt _e_x_p_r |
     rriigghhtt _e_x_p_r]

           The llaabbeell command places a label on the given axis.  It is possible
           to specify several labels, which will be stacked over each other as
           in pic.  The final argument, if present, specifies how many  inches
           the label is shifted from the axis.

           By  default the labels on the left and right labels run parallel to
           the frame.  You can  cancel  this  by  specifying  unaligned  as  a
           _s_t_r_i_n_g___m_o_d_i_f_i_e_r.

     cciirrccllee aatt [_c_o_o_r_d_i_n_a_t_e___n_a_m_e] _e_x_p_r, _e_x_p_r [rraaddiiuuss _e_x_p_r] [_l_i_n_e_d_e_s_c]

           This  draws an circle at the point indicated.  By default, the cir-
           cle is small, 0.025 inches.  This can be over-ridden by  specifying
           a  radius.   The coordinates of the point are relative to the named
           coordinate system, or the default system if none is specified.

           This command has been extended to take a  line  description,  e.g.,
           dotted.   It also accepts the filling extensions described below in
           the bbaarr command.

     lliinnee [_l_i_n_e___d_e_s_c_r_i_p_t_i_o_n] ffrroomm [_c_o_o_r_d_i_n_a_t_e___n_a_m_e] _e_x_p_r, _e_x_p_r ttoo
     [_c_o_o_r_d_i_n_a_t_e___n_a_m_e] _e_x_p_r, _e_x_p_r [_l_i_n_e___d_e_s_c_r_i_p_t_i_o_n]

     aarrrrooww [_l_i_n_e___d_e_s_c_r_i_p_t_i_o_n] ffrroomm [_c_o_o_r_d_i_n_a_t_e___n_a_m_e] _e_x_p_r, _e_x_p_r ttoo
     [_c_o_o_r_d_i_n_a_t_e___n_a_m_e] _e_x_p_r, _e_x_p_r [_l_i_n_e___d_e_s_c_r_i_p_t_i_o_n]

           This draws a line or arrow from the first point to the second using
           the   given   style.    The  default  line  style  is  solid.   The
           _l_i_n_e___d_e_s_c_r_i_p_t_i_o_n can be given either before the ffrroomm or  after  the
           ttoo  clause.   If both are given the second is used.  It is possible
           to specify one point in one coordinate system and one  in  another,
           note  that if both points are in a named coordinate system (even if
           they are in the same named coordinate  system),  both  points  must
           have _c_o_o_r_d_i_n_a_t_e___n_a_m_e given.

     ccooppyy ["_f_i_l_e_n_a_m_e"] [uunnttiill "_s_t_r_i_n_g"] [tthhrruu _m_a_c_r_o]

           The  ccooppyy  command  imports data from another file into the current
           graph.  The form with only a filename given is a simple file inclu-
           sion;  the  included  file is simply read into the input stream and
           can contain arbitrary ggrraapp commands.  The more common case is  that
           it is a number list; see _N_u_m_b_e_r _L_i_s_t_s below.

           The  second  form takes lines from the file, splits them into words
           delimited by one or more spaces, and calls  the  given  macro  with
           those  words  as parameters.  The macro may either be defined here,
           or be a macro defined earlier.  See _M_a_c_r_o_s for more information  on
           macros.

           The  _f_i_l_e_n_a_m_e may be omitted if the uunnttiill clause is present.  If so
           the current file is treated as  the  input  file  until  _s_t_r_i_n_g  is
           encountered at the beginning of the line.

           ccooppyy  is  one  of  the workhorses of ggrraapp.  Check out the paper and
           _/_u_s_r_/_l_o_c_a_l_/_s_h_a_r_e_/_d_o_c_/_g_r_a_p_/_e_x_a_m_p_l_e_s for more details.
     pprriinntt (_e_x_p_r_|_s_t_r_i_n_g)

           Prints its argument to the standard error.

     sshh _b_l_o_c_k

           This passes _b_l_o_c_k to sh(1).  Unlike K&B ggrraapp no macro  or  variable
           expansion  is  done.   I believe that this is also true for gnu pic
           version 1.10.  See the _M_a_c_r_o_s section for information  on  defining
           blocks.

     ppiicc _p_i_c___s_t_a_t_e_m_e_n_t

           This  issues the given pic statements  in the enclosing ..PPSS and ..PPEE
           at the point where the command is issued.

           Statements  that  begin  with  a  period  are  considered   to   be
           troff(statements)  and  are  output in the enclosing ..PPSS and ..PPEE at
           the point where the command appears.

           For the purposes of relative placement of pic  or  troff  commands,
           the frame is output immediately before the first plotted object, or
           the ffrraammee statement, if any.  If the user specifies  pic  or  troff
           commands  and  neither any plotable object nor a ffrraammee command, the
           commands will not be output.

     ggrraapphh _N_a_m_e _p_i_c___c_o_m_m_a_n_d_s

           This command is used to position graphs with respect to each other.
           The current graph is given the pic name _N_a_m_e ( pic names begin with
           capital letters).  Any pic commands following the graph are used to
           position  the  next graph.  The frame of the graph is available for
           use with pic name Frame. The following places a second graph  below
           the first:

                       graph Linear
                       [ graph description ]
                       graph Exponential with .Frame.n at \
                               Linear.Frame.s - (0, .05)
                       [ graph description ]

     _n_a_m_e _= _e_x_p_r

           This  assigns  _e_x_p_r  to  the  variable _n_a_m_e.  ggrraapp has only numeric
           (double) variables.

           Assignment creates a variable if it does not exist.  Variables per-
           sist across graphs.  Assignments can cascade; a = b = 35 assigns 35
           to a and b.

     bbaarr (uupp|rriigghhtt) [_c_o_o_r_d_i_n_a_t_e_s___n_a_m_e] _o_f_f_s_e_t hhtt _h_e_i_g_h_t [wwiidd _w_i_d_t_h] [bbaassee
     _b_a_s_e___o_f_f_s_e_t] [_l_i_n_e___d_e_s_c_r_i_p_t_i_o_n]

     bbaarr [_c_o_o_r_d_i_n_a_t_e_s___n_a_m_e] _e_x_p_r, _e_x_p_r, [_c_o_o_r_d_i_n_a_t_e_s___n_a_m_e] _e_x_p_r, _e_x_p_r,
     [_l_i_n_e___d_e_s_c_r_i_p_t_i_o_n]

           The bbaarr command facilitates drawing bar graphs.  The first form  of
           the command describes the bar somewhat generally and has ggrraapp place
           it.  The bar may extend up or to the right, is centered  on  _o_f_f_s_e_t
           and  extends up or right _h_e_i_g_h_t units (in the given coordinate sys-
           tem).  For example

                       bar up 3 ht 2

           draws a 2 unit high bar sitting on the x axis, centered on x=3.  By
           default  bars are 1 unit wide, but this can be changed with the wwiidd
           keyword.  By default bars sit on the base axis, i.e., bars directed
           up  will  extend from y=0.  That may be overridden by the bbaassee key-
           word.  (The bar described above has corners (2.5, 0) and (3.5, 2).)

           The  line description has been extended to include a ffiillll _e_x_p_r key-
           word that specifies the shading inside the bar.  Bars may be  drawn
           in any line style.

           The  second  form of the command draws a box with the two points as
           corners.  This can be used to draw boxes highlighting certain  data
           as well as bar graphs.  Note that filled bars will cover data drawn
           under them.

   CCoonnttrrooll FFllooww

     iiff _e_x_p_r tthheenn _b_l_o_c_k [eellssee _b_l_o_c_k]

           The iiff statement provides simple conditional execution.  If _e_x_p_r is
           non-zero,  the  _b_l_o_c_k after the tthheenn statement is executed.  If not
           the _b_l_o_c_k after the eellssee is executed, if present.  See  _M_a_c_r_o_s  for
           the definition of blocks.  Early versions of this implementation of
           ggrraapp treated the blocks as macros that were defined and expanded in
           place.   This led to unnecessary confusion because explicit separa-
           tors were sometimes called for.  Now, ggrraapp inserts a separator  (;)
           after the last character in _b_l_o_c_k, so constructs like

           if (x == 3) { y = y + 1 }
           x = x + 1

           behave  as  expected.  A separator is also appended to the end of a
           ffoorr block.

     ffoorr _n_a_m_e ffrroomm _f_r_o_m___e_x_p_r ttoo _t_o___e_x_p_r [bbyy [+|-|*|/] _b_y___e_x_p_r] ddoo _b_l_o_c_k

           This command executes _b_l_o_c_k iteratively.  The variable _n_a_m_e is  set
           to  _f_r_o_m___e_x_p_r  and incremented by _b_y___e_x_p_r until it exceeds _t_o___e_x_p_r.
           The iteration has the semantics defined in the ttiicckkss command.   The
           definition  of  _b_l_o_c_k  is  discussed  in _M_a_r_c_o_s.  See also the note
           about implicit separators in the description of the iiff command.

           An == can be used in place of ffrroomm.

   EExxpprreessssiioonnss

     ggrraapp supports a most standard arithmetic operators: + - / * ^.  The carat
     (^) is exponentiation.  In an iiff statement ggrraapp also supports the C logi-
     cal operators ==, !=, &&, || and unary !.  Also in an iiff, == and != are
     overloaded for the comparison of quoted strings.  Parentheses are used
     for grouping.

     Assignment is not allowed in an expression in any context, except for
     simple cascading of assignments.  a = b = 35 works as expected; a = 3.5 *
     (b = 10) does not execute.

     ggrraapp supports the following functions that take one argument: lloogg, eexxpp,
     iinntt, ssiinn, ccooss, ssqqrrtt, rraanndd.  The logarithms are base 10 and the trigono-
     metric functions are in radians.  eeeexxpp returns Euler's number to the
     given power and llnn returns the natural logarithm.  The natural log and
     exponentiation functions are extensions and are probably not available in
     other ggrraapp implementations.

     rraanndd returns a random number uniformly distributed on [0,1).  The follow-
     ing two argument functions are supported: aattaann22, mmiinn, mmaaxx.  aattaann22 works
     just like atan2(3).  The random number generator can be seeded by calling
     ssrraanndd with a single parameter (converted internally to an integer).
     Because its return value is of no use, you must use ssrraanndd as a separate
     statement, it is not part of a valid expression.  ssrraanndd is not portable.

     The ggeettppiidd function takes no arguments and returns the process id.  This
     may be used to seed the random number generator, but do not expect cryp-
     tographically random values to result.

     Other than string comparison, no expressions can use strings.  One string
     valued function exists: sspprriinnttff (_f_o_r_m_a_t, [_e_x_p_r [_, _e_x_p_r]] ).  It operates
     like sprintf(3), except returning the value.  It can be used anywhere a
     quoted string is used.  If ggrraapp is run with --SS, the environment variable
     GRAP_SAFER is defined, or ggrraapp has been compiled for safer operation, the
     sspprriinnttff command will return the format string.  This mode of operation is
     only intended to be used only if ggrraapp is being used as part of a super-
     user enabled print system.

   MMaaccrrooss
     ggrraapp has a simple but powerful macro facility.  Macros are defined using
     the ddeeffiinnee command :

     ddeeffiinnee _n_a_m_e _b_l_o_c_k
     uunnddeeffiinnee _n_a_m_e

           Every  occurrence  of  _n_a_m_e  in the program text is replaced by the
           contents of _b_l_o_c_k.  _b_l_o_c_k is defined by a series of  statements  in
           nested { }'s, or a series of statements surrounded by the same let-
           ter.  An example of the latter is

                       define foo  X coord x 1,3 X
           Each time foo appears in the text, it will be replaced by  coord  x
           1,3.   Macros  are  literal,  and can contain newlines.  If a macro
           does not span multiple lines, it should end in a semicolon to avoid
           parsing errors.

           Macros  can take parameters, too.  If a macro call is followed by a
           parenthesized, comma-separated list the  values  starting  with  $1
           will  be  replaced in the macro with the elements of the list.  A $
           not followed by a digit is left unchanged.  This  parsing  is  very
           rudimentary,  no  nesting  or  parentheses or escaping of commas is
           allowed.  Also, there is no way to say argument  1  followed  by  a
           digit (${1}0 in sh(1)).

           The following will draw a line with slope 1.

                       define foo { next at $1, $2 }
                       for i from 1 to 5 { foo(i,i) }
           Macros       persist       across       graphs.       The      file
           _/_u_s_r_/_l_o_c_a_l_/_s_h_a_r_e_/_g_r_a_p_/_g_r_a_p_._d_e_f_i_n_e_s contains simple macros for plot-
           ting common characters.  The uunnddeeffiinnee command deletes a macro.

           See  the  file _/_u_s_r_/_l_o_c_a_l_/_s_h_a_r_e_/_d_o_c_/_g_r_a_p_/_e_x_a_m_p_l_e_s for more examples
           of macros.

   NNuummbbeerr LLiissttss

     A whitespace-separated list of numbers is treated specially.  The list is
     taken to be points to be plotted using the default line style on the
     default coordinate system.  If more than two numbers are given, the extra
     numbers are taken to be additional y values to plot at the first x value.
     Number lists in DWB ggrraapp can be comma-separated, and this ggrraapp supports
     that as well.  More precisely, numbers in number lists can be separated
     by either whitespace, commas, or both.

           1 2 3
           4 5 6

     Will plot points using the default line style at (1,2), (1,3),(4,5) and
     (4,6).  A simple way to plot a set of numbers in a file named _._/_d_a_t_a is:

           .G1
           copy "./data"
           .G2

   PPiicc MMaaccrrooss

     ggrraapp defines pic macros that can be used in embedded pic code to place
     elements in the graph.  The macros are xx__gggg, yy__gggg, and xxyy__gggg.  These
     macros define pic distances that correspond to the given argument.  They
     can be used to size boxes or to plot pic constructs on the graph.  To
     place a given construct on the graph, you should add Frame.Origin to it.
     Other coordinate spaces can be used by replacing gggg with the name of the
     coordinate space.  A coordinate space named gggg cannot be reliably
     accessed by these macros.

     The macros are emitted immediately before the frame is drawn.

     DWB ggrraapp may use these as part of its implementation.  This ggrraapp provides
     them only for compatibility.  Note that these are very simple macros, and
     may not do what you expect under complex conditions.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
     If the environment variable GRAP_DEFINES is defined, ggrraapp will look for
     its defines file there.  If that value is a relative path name the path
     specified in the --MM option will be searched for it.  GRAP_DEFINES over-
     rides the compiled in location of the defines file, but may be overridden
     by the --dd or --DD flags.

     If GRAP_SAFER is set, sspprriinnttff is disabled to prevent forcing ggrraapp to core
     dump or smash the stack.

FFIILLEESS
     _/_u_s_r_/_l_o_c_a_l_/_s_h_a_r_e_/_g_r_a_p_/_g_r_a_p_._d_e_f_i_n_e_s

SSEEEE AALLSSOO
     atan2(3), groff(1), pic(1), printf(3), sh(1), sprintf(3), troff(1)

BBUUGGSS
     There are several small incompatibilities with K&R ggrraapp.  They include
     the sshh command not expanding variables and macros, and a more strict
     adherence to parameter order in the internal commands.

     Although much improved, the error reporting code can still be confused.
     Notably, an error in a macro is not detected until the macro is used, and
     it produces unusual output in the error message.

     Iterating many times over a macro with no newlines can run ggrraapp out of
     memory.

AAUUTTHHOORR
     This implementation was done by Ted Faber <faber@lunabase.org>.  Bruce
     Lilly <blilly@erols.com> contributed many bug fixes, including a consid-
     erable revamp of the error reporting code.  If you can actually find an
     error in your ggrraapp code, you can probably thank him.  ggrraapp was designed
     and specified by Brian Kernighan and Jon Bentley.

FreeBSD 4.7                     August 19, 1998                    FreeBSD 4.7
