Commands Reference, Volume 2

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

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:

frame

Defines the frame that surrounds the graph. The syntax is:

frame [ht Expression] [wid Expression] [[Side] LineDescription]

The attributes are defined as follows:

Side: top, bot, left, right
LineDescription: solid, invis, dotted [Expression], dashed [Expression]

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.

label

Places a label on a specified side of the graph. The syntax is:

label Side StringList ... Shift

The attributes are defined as follows:

Shift: left, right, up, or down expression
StringList: str ... rjust, ljust, above, below [size (+)Expression] ...
String: "..."

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:

Shift: left, right, up, down Expression
TickLocations: at [Name] Expression [String], Expression [String], ... from [Name] Expression to Expression [by [Operation] Expression] String

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

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.

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

The attributes are defined as follows:

StringList: str ... rjust, ljust, above, below [size +)Expression] ...
Point: [Name] Expression Expression

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:

Point: [Name] Expression Expression
LineDescription: solid, invis, dotted [Expression], dashed Expression]

circle

Draws a circle. The syntax is:

circle at Point [radius Expression]

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

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:

The # (pound sign) introduces a comment. The comment ends automatically at the end of a line.
Statements that continue for more than one line must be preceded by a \ (backslash character) at the beginning of each new line.
Multiple statements appearing on one line must be separated by semicolons.
The grap language ignores blank lines.
Predefined strings include bullet, plus, box, star, dot, times, htick, vtick, square, and delta.
Built-in functions available in grap include log (base 10), exp (base 10), int, sin, cos, atan2, sqrt, min, max, and rand.

Flags

-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

/usr/lib/dwb/grap.defines

Contains definitions of standard plotting characters.

Related Information

The pic command.