Table of Contents

NAME

SYNOPSIS

DESCRIPTION

is an implementation of Kernighan and Bentley's language for typesetting 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 As of this writing, it is available electronically at This version is a black box implementation of and some inconsistencies are to be expected. The remainder of this manual page will briefly outline the language as implemented here. is a pre-processor. It takes commands embedded in a source file which are surrounded by and macros, and rewrites them into 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 which are read in order. A of is the standard input. If no are given, input is read from the standard input. Because is a preprocessor, and gnu will output TeX, it is possible to use with TeX. The option specifies a file of macro definitions to be read at startup, and defaults to /usr/local/share/grap/grap.defines. The option inhibits the reading of any initial macros file. The defines file can also be given using the environment variable. (See below). prints the version information on the standard output and exits. makes labels unaligned by default. This version of uses new features of gnu 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 programs. is followed by a colon-separated list of directories used to search for relative pathnames included via The path is also used to locate the defines file, so if the changes the defines file name to a relative name, it will be searched for in the path given by The search path always includes the current directory, and by default that directory is searched last. All commands are included between and macros, which are consumed by The output contains between and macros. Any arguments to the macro in the input are arguments to the macro in the output, so graphs can be scaled just like diagrams. If 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 commands are sketched below. Refer to Kernighan and Bentley's paper for the details. New versions of will invoke if is given. Commands are separated from one another by newlines or semicolons (;). ...

... This describes how the axes for the graph are drawn. A is a line description, e.g., or the literal If the first is given, the frame is drawn with that style. The default is 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 If no plotting commands have been given before the command is issued, the frame will be output at that point in the plotting stream relative to embedded or commands. Otherwise the frame is output before the first plotted object (even invisible ones). The 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 is given, that coordinate system is defined, if not the default system is modified. A coordinate system created by one command may be modified by subsequent commands. A program may declare a coordinate space using 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 statement. This command also determines if a scale is plotted logarithmically. means the same thing as The command defines the style with which a given line will be plotted. If is given, the style is associated with that name, otherwise the default style is set. is a line description, and the optional is a string to be centered at each point. The default line description is 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 command ends any current line and begins a new one. When defining a line style, that is the first 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 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 statement, the plot string can be removed by specifying "" in the statement. is a synonym for The command plots the given point using the line style given by or the default if none is given. If is given, it should have been defined by an earlier 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 command, if not, grap will exit. If the optional 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 command. The coordinates may optionally be enclosed in parentheses: ... 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 justification modifiers, and absolute and relative modifiers.

sets the string size to
points. If is preceded by a + or -, the size is increased or decreased by that many points. In the second version, the is converted to a string and placed on the graph. is a format string. Only formatting escapes for printing floating point numbers make sense. Points are specified the same way as for 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 expression (See 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 generation for a given side. The or parameter controls the direction and length of the ticks. If a is specified, the ticks are automatically generated using that coordinate system. If no system is specified, the default coordinate system is used. As with and the coordinate system must be declared before the statement that references it. This syntax for requesting automatically generated ticks is an extension, and will not port to older implementations. The second version of the 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 parameter must be given. For each tick a style format string can be given. The defaults to To place ticks with no labels, specify 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 optional direction and expression immediately preceding the The third format of the 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 ending at one unit apart. If the clause is specified, ticks are units apart. If an operator appears before each tick is operated on by that operator instead of +. For example ticks left out from 2 to 32 by *2 will put ticks at 2, 4, 8, 16, and 32. If is specified, all ticks are formatted using it. The parameters preceding the act as described above. The and 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 turns off ticks on a given side. If no side is given the ticks for all sides are cancelled. is a synonym for The command is similar to the command except that specifies the placement of lines in the frame. The syntax is similar to as well. By specifying 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 command, does not cancel them unless is specified. Instead of a direction for ticks, allows the user to pick a line description for the grid lines. The usual line descriptions are allowed. Grids are labelled by default. To omit labels, specify the format string as ... The command places a label on the given axis. It is possible to specify several labels, which will be stacked over each other as in 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 as a This draws an circle at the point indicated. By default, the circle 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., It also accepts the filling extensions described below in the command. This draws a line or arrow from the first point to the second using the given style. The default line style is The can be given either before the or after the 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 given. The command imports data from another file into the current graph. The form with only a filename given is a simple file inclusion; the included file is simply read into the input stream and can contain arbitrary commands. The more common case is that it is a number list; see 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 for more information on macros. The may be omitted if the clause is present. If so the current file is treated as the input file until is encountered at the beginning of the line. is one of the workhorses of Check out the paper and for more details. Prints its argument to the standard error. This passes to Unlike K&B no macro or variable expansion is done. I believe that this is also true for gnu version 1.10. See the section for information on defining blocks. This issues the given statements in the enclosing and at the point where the command is issued. Statements that begin with a period are considered to be and are output in the enclosing and at the point where the command appears. For the purposes of relative placement of or commands, the frame is output immediately before the first plotted object, or the statement, if any. If the user specifies or commands and neither any plottable object nor a command, the commands will not be output. This command is used to position graphs with respect to each other. The current graph is given the name ( names begin with capital letters). Any commands following the graph are used to position the next graph. The frame of the graph is available for use with name 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 ] This assigns to the variable has only numeric (double) variables. Assignment creates a variable if it does not exist. Variables persist across graphs. Assignments can cascade; assigns 35 to and The command facilitates drawing bar graphs. The first form of the command describes the bar somewhat generally and has place it. The bar may extend up or to the right, is centered on and extends up or right units (in the given coordinate system). 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 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 keyword. (The bar described above has corners (2.5, 0) and (3.5, 2).) The line description has been extended to include a keyword 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. The statement provides simple conditional execution. If is non-zero, the after the statement is executed. If not the after the is executed, if present. See for the definition of blocks. Early versions of this implementation of treated the blocks as macros that were defined and expanded in place. This led to unnecessary confusion because explicit separators were sometimes called for. Now, inserts a separator (;) after the last character in 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 block. This command executes iteratively. The variable is set to and incremented by until it exceeds The iteration has the semantics defined in the command. The definition of is discussed in See also the note about implicit separators in the description of the command. An can be used in place of supports a most standard arithmetic operators: + - / * ^. The carat (^) is exponentiation. In an statement also supports the C logical operators ==, !=, &&, || and unary !. Also in an == 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. works as expected; does not execute. supports the following functions that take one argument: The logarithms are base 10 and the trigonometric functions are in radians. returns Euler's number to the given power and returns the natural logarithm. The natural log and exponentiation functions are extensions and are probably not available in other implementations. If is given an argument, it seeds the random number generator with that value. Called with no arguments, it returns a random number uniformly distributed on [0,1). The following two argument functions are supported: works just like Other than string comparison, no expressions can use strings. One string valued function exists: ). It operates like except returning the value. It can be used anywhere a quoted string is used. has a simple but powerful macro facility. Macros are defined using the command : Every occurrence of in the program text is replaced by the contents of is defined by a series of statements in nested { }'s, or a series of statements surrounded by the same letter. An example of the latter is define foo X coord x 1,3 X Each time appears in the text, it will be replaced by 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) ). 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 contains simple macros for plotting common characters. See the file for more examples of macros. 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 can be comma-separated, and this 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 is: copy "./data"

ENVIRONMENT VARIABLES

If the environment variable is defined, will look for its defines file there. If that value is a relative path name the path specified in the option will be searched for it. overrides the compiled in location of the defines file, but may be overridden by the or flags.

FILES

SEE ALSO

BUGS

There are several small incompatibilities with K&R They include the 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 out of memory.

AUTHOR

This implementation was done by contributed many bug fixes, including a considerable revamp of the error reporting code. If you can actually find an error in your code, you can probably thank him. was designed and specified by and


Table of Contents