
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] [_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/troff.html

     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 start-
     up, 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.

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

     --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 rela-
     tive 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.

     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 de-
           fault line style can be over-ridden for sides of the frame by spec-
           ifying additional parameters to ffrraammee.

     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.

           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, and absolute and
           relative size modifiers.  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.

           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 de-
           fault, 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 di-
           rection 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". To place ticks with no labels,
           specify _f_o_r_m_a_t___s_t_r_i_n_g as "".


           The labels on the ticks may be shifted by specifying a direction
           and the distance in inches to offset the label.  That is the op-
           tional 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 "".

     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 en-
           countered 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_/_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
           macros before the pic commands to draw the graph.

           Statements that begin with a period are considered to be
           troff(statements) and are output in the enclosing ..PPSS and ..PPEE
           macros before the pic commands to draw the graph.

     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 (dou-
           ble) 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 overriden 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 [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 The logarithms are base 10 and the trigonometric functions
     are in radians.  eeeexxpp returns Euler's number to the given power and llnn
     returns the natural logarithm.  The natural log and exponentiation func-
     tions are extensions and are probably not available in other ggrraapp imple-
     mentations.

     If rraanndd is given an argument, it seeds the random number generator with
     that value.  Called with no arguments, it returns a random number uni-
     formly distributed on [0,1).  The following two argument functions are
     supported: aattaann22, mmiinn, mmaaxx. aattaann22 works just like atan2(3).

     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.

   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

           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 al-
           lowed.  Also, there is no way to say argument 1 followed by a digit
           (${1}0 in sh(1)).  A macro can have at most 32 arguments.

           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.

           See the file _/_u_s_r_/_l_o_c_a_l_/_s_h_a_r_e_/_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 de-
     fault 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:

                 copy "./data"

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.

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 adher-
     ence 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
     Lilley <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.

BSD                             August 19, 1998                              9
