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:

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.

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:

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

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:

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.

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:

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

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:

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

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:

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

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.