... This describes how the axes
for the graph are drawn. A is a line description, e.g., or the literal
It may also include a keyword followed by the color to draw the string
in double quotes. Any color understood by the underlying groff system can
be used. Color can only be used under GNU pic, and is not available in
compatibility mode. Similarly, for pic implementations that understand
that attribute may be used with a real valued parameter. is not available
in compatibility mode. 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). and are in inches by default, but can be any unit. If omitted,
the dimensions are 2 inches high by 3 inches wide. 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. The plot string can have
its format changed through several string_modifiers. String_modifiers are
described in the description of the command. The standard defines file
includes several macros useful as plot strings, including and 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 and absolute and relative modifiers.
See the documentation for the description of the justification modifiers.
also supports the and modifiers which are briefly noted in the description
of the command. The standard defines file includes several macros useful
as plot strings, including and Strings placed by either format of
the command are restricted to being within the frame. This can be overriden
by using the attribute, which allows a string to be plotted in or out
of the frame. The and flags set on all strings, and to prevent a
string from being plotted outside the frame when those flags are active,
the attribute can be used to retore clipping behavior. Though or
can be applied to any string, it only has meaning for statements. sets
the string size to points. If is preceded by a + or -, the size is increased
or decreased by that many points. If and a color name in double quotes
appears, the string will be rendered in that color under a version of GNU
troff that supports color. Color is not available in compatibility mode.
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. The format string is only respected if the
command is also active. See the description of for the various ways to
disable it. and respond differently when is running safely. ignores
any arguments, passing the format string through without substitution.
ignores the format string completely, plotting using the format. 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 The format string can also take string modifiers
as described in the command. To place ticks with no labels, specify
as If is disabled, behaves as 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 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 If is disabled, behaves as with respect
to the format string. ... 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. It will also accept
a keyword that gives the color of the outline of the circle in double
quotes and a command that sets the color to fill the circle with similarly.
Colors are only available when compatibility mode is off, and using a
version of GNU pic that supports color. 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. Confirm the location of the examples directory using the
flag. 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 plotable 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 used by 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 overridden 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. They support the and keywords described
under 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 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.
returns a random number uniformly distributed on [0,1). The following
two-argument functions are supported: works just like The random number
generator can be seeded by calling with a single parameter (converted
internally to an integer). Because its return value is of no use, you must
use as a separate statement, it is not part of a valid expression. is
not portable. The function takes no arguments and returns the process
id. This may be used to seed the random number generator, but do not expect
cryptographically random values to result. 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. If is run with the environment variable is
defined, or has been compiled for safer operation, the command will
return the format string. This mode of operation is only intended to be
used only if is being used as part of a super-user enabled print system.
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)
). 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. The command deletes a macro. See
the directory for more examples of macros. Confirm the location of the
examples directory using the flag. 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: .G1 copy "./data" .G2 defines pic macros that can be used in embedded pic code to place elements in the graph. The macros are and 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 with the name of the coordinate space. A coordinate space named cannot be reliably accessed by these macros. The macros are emitted immediately before the frame is drawn. DWB may use these as part of its implementation. This provides them only for compatibility. Note that these are very simple macros, and may not do what you expect under complex conditions.