1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
|
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] [--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.
--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.
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.
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.
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.5 August 19, 1998 FreeBSD 4.5
|
