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] [--ll] [--MM _i_n_c_l_u_d_e _p_a_t_h] [--RR] [--rr] [--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.  Additional documentation
     and examples, packaged with ggrraapp, may have been installed locally as
     well.  If available, paths to them can be displayed using ggrraapp --hh or ggrraapp
     --vv (or ggrraapp ----hheellpp / ggrraapp ----vveerrssiioonn)

     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 --ll flag is a
     synonym for --DD, though I do not remember why).  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 numbers used internally by ggrraapp are double precision floating point
     values.  Sometimes using floating point numbers has unintended conse-
     quences.  To help avoid these problems, ggrraapp can use two thresholds for
     comparison of floating point numbers, set by --RR or --rr.  The --RR flag sets
     coarse comparison mode, which is suitable for most applications.  If you
     are plotting small values - less than 1e-6 or so - consider using --rr
     which uses very fine comparisons between numbers.  You may also want to
     rescale your plotted values to be larger in magnitude. The coarse
     comarisons are used by default.

     To be precise, the value by which two numbers must differ for ggrraapp to
     consider them not equal is called the comparison limit and the smallest
     non-zero number is called the minimum value.  The values a given version
     of ggrraapp uses for these are included in the output of --vv or --hh.

     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 exits.  ----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.  It may also include a ccoolloorr keyword followed by
           the color to draw the string in double quotes.   Any  color  under-
           stood  by  the underlying groff system can be used.  Color can only
           be used under GNU pic, and is not available in compatibility  mode.
           Similarly,  for pic implementations that understand tthhiicckknneessss, that
           attribute may be used with a real valued parameter.   TThhiicckknneessss  is
           not available in compatibility mode.

           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).

           hhtt and wwiidd are in inches by default, but can be any groff unit.  If
           omitted, the dimensions are 2 inches high by 3 inches wide.

     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.

           If ccoolloorr and a color name in double quotes appears, the string will
           be rendered in that color under a version of GNU  troff  that  sup-
           ports color.  Color is not available in compatibility mode.

           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.   It will also accept a ccoolloorr keyword that gives
           the color of the outline of the  circle  in  double  quotes  and  a
           ffiillllccoolloorr command that sets the color to fill the circle with simi-
           larly.  Colors are only available when compatibility mode  is  off,
           and using a version of GNU pic that supports color.

     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_/_e_x_a_m_p_l_e_s_/_g_r_a_p for more details.  Confirm the loca-
           tion of the examples directory using the --vv flag.
     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 (names used by pic
           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  sec-
           ond 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.  They support the ccoolloorr and ffiillllccoolloorr keywords
           described under cciirrccllee.

           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 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 directory _/_u_s_r_/_l_o_c_a_l_/_s_h_a_r_e_/_e_x_a_m_p_l_e_s_/_g_r_a_p for more  examples
           of  macros.   Confirm  the location of the examples directory using
           the --vv flag.

   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)

     If documentation and examples have been installed, ggrraapp ----vveerrssiioonn or ggrraapp
     ----hheellpp will display the locations.

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 7.0                     March 11, 2006                     FreeBSD 7.0