grap Command

Purpose

Typesets graphs to be processed by the pic command.

Syntax

grap [ -l ] [ -T Name ] [ ] [ File ... ]

Description

The grap command processes grap language input files and generates input to the pic command. The grap language is a language for typesetting graphs. A typical command line is:

grap  File  |  pic  |  troff  |  Typesetter

Graphs are surrounded by the .G1 and .G2 troff command requests. Data enclosed by these requests are scaled and plotted, with tick marks automatically supplied. Commands exist to modify the frame, add labels, override the default ticks, change the plotting style, define coordinate ranges and transformations, and include data from files. In addition, the grap command provides the same loops, conditionals, and macroprocessing as the pic command.

Grap language files contain grap programs. A grap program is written in the form:

.G1
grap Statement
grap Statement
grap Statement
.G2

Parameter

Item Description
File Specifies grap language files (grap programs) to be processed by the grap command for input to the pic command.

grap Statements Summary

Following is a summary of the grap statements you can use to create a grap program:

Item Description
frame Defines the frame that surrounds the graph. The syntax is:
frame [ht Expression] [wid Expression] [[Side] LineDescription]

The attributes are defined as follows:

Height defaults to 2 inches, width defaults to 3 inches, sides default to solid. If side is omitted, the linedesc applies to the entire frame.

Item Description
label Places a label on a specified side of the graph. The syntax is:
label Side StringList ... Shift

The attributes are defined as follows:

Item Description
coord Defines an overriding system. The syntax is:
coord [Name] [x Expression,Expression] [y  Expression,Expression] [[log x] [log y] [log log]]
ticks Places tick marks on one side of the frame. The syntax is:
ticks side [[in] [out] [Expression]] [Shift] [TickLocations]

The attributes are defined as follows:

If no ticks are specified, they will be provided automatically; ticks off suppresses automatic ticks.

Item Description
grid Produces grid lines along (that is, perpendicular to) the named side. The syntax is:
grid Side [LineDescription] [Shift] [TickLocations]

Grids are labeled by the same mechanism as ticks.

Item Description
plot Places text at a point. The syntax is:
StartList at Point plot Expression [Start] at Point

The attributes are defined as follows:

Item Description
line Draws a line or arrow from one point to another. The syntax is:
{line | arrow} from Point to Point [LineDescription]

The attributes linedesc are defined as follows:

Item Description
circle Draws a circle. The syntax is:
circle at Point [radius Expression]

The radius is in inches; the default size is small.

Item Description
draw Defines a sequence of lines. The syntax is:
draw [Name] at Point[LineDescription]
next Continues a sequence. The syntax is:
next [Name] at Point [LineDescription]
new Starts a new sequence. The syntax is:
new [Name] at Point [LineDescription]
numberlist Creates a line from a given set of numbers. The numbers are treated as points x, y1, y2, and so on; and plotted at the single x value. The syntax is:
number x, y1, y2 ...
for Creates a loop. The syntax is:
for Variable {from | =} Expression to Expression \
[by [arithmetic or multiplicative operator] Expression] do X Anything X

X is any single character that does not appear in the string. If X is a left brace {, then the string may contain internally balanced braces followed by a right brace}. The text Anything is repeated as the Variable takes on values from the first Expression to the second Expression.

if Creates a conditional evaluation. The syntax is:
if Expression then X Anything X [else X Anything X]
define Provides the same macroprocessor that Priority Interrupt Controller (PIC) does. The syntax is:
define MacroName X Anything X
copy Copies a file; includes the current contents of the file. The syntax is:
copy Filename
copy-thru Copies the file through the macro.
copy Filename thru MacroName

Each number or quoted string is treated as an argument. Copying continues until end of file or the next .G2. The optional clause until String causes copying to stop when a line whose first field is String occurs.

The following statement copies subsequent lines through the macro:

copy thru MacroName

In all cases, you can specify the macro by inline rather than by name:

copy thru x MacroBody x
sh Passes text through to the UNIX shell. The syntax is:
sh x Anything x

The variable Anything is scanned for macros. The pid macro is built-in. It is a string consisting of the process identification number; you can use it to generate unique file names.

pic Passes text through to pic with the pic removed. Variables and macros are not evaluated. Lines beginning with a period (that are not numbers) are passed through literally, under the assumption that they are troff commands.
graph Defines a new graph named Picname, and resets all coordinate systems. The syntax is:
graph Picname [pic-text]

If graph commands are used in a grap program, the statement after the .G1 must be a graph command. You can use the pic-text to position this graph relative to previous graphs by referring to their Frames as in the following example.

graph First
 ...
graph Second with .Frames.w at First.Frame.e + [0.1,0]

Macros and expressions in pic-text are not evaluated. Picnames must begin with a capital letter according to pic syntax.

print Writes on stderr as grap processes its input. This statement can be helpful in debugging. The syntax is:
print [Expression | String]

grap Language Conventions

The following conventions apply:

Flags

Item Description
-l Stops the grap command from looking for the /usr/lib/dwb/grap.defines library file of macro definitions.
-TName Specifies the value of the Name variable as the grap command output device. The default value is -Tibm3816.
- - (Double dash) Indicates the end of flags.

File

Item Description
/usr/lib/dwb/grap.defines Contains definitions of standard plotting characters.