NAME
jgraph - filter for graph plotting to postscript
SYNTAX
jgraph [-p] [-P] [-L] [-comments] [filename ...]
DESCRIPTION
Jgraph takes the description of a graph or graphs and pro-
duces a postscript file on the standard output. Jgraph is
ideal for plotting any mixture of scatter point graphs, line
graphs, and/or bar graphs, and embedding the output into
LaTeX, or any other text processing system which can read
postscript.
Jgraph reads its input from the specified files. If no
files are specified, then it reads from standard input.
The graph description language is simple enough to get nice
looking graphs with a minimum of effort, yet powerful enough
to give the user the flexibility to tailor the appearance of
the graph to his or her individual preferences. This
includes plotting multiple graphs and laying them out
separately on the page (or pages).
As an example, if the user wanted to simply plot the points
(2,3), (4,5), (1,6), the following would be enough of a
specification file:
newgraph
newcurve pts 2 3 4 5 1 6
Now, if the user wanted to spruce the graph up by adding
labels to the axes, connecting the points, and titling the
graph, then the input could change to:
newgraph
newcurve pts 2 3 4 5 1 6 linetype solid
xaxis label : X axis
yaxis label : Y axis
title : This is an example graph
If the user instead wanted this to be a bar graph with dif-
ferent endpoints on the axes, he/she could simply change the
input to:
newgraph
xaxis min 0 max 5 label : X axis
yaxis min 0 max 6 label : Y axis
newcurve pts 2 3 4 5 1 6 marktype xbar
title : This is an example bar graph
There are many more features of the description language,
which are described below in the next section. Features
which are not embedded within the description language are:
line and function interpolation, function plotting, and pie
graphs. The latter is impossible to do with the aid of
jgraph, however, the others can be effected with jgraph
mixed with awk or c. See FUNCTION PLOTTING AND OTHER NON-
INHERENT FEATURES below.
Also below is a section HINTS AND EXAMPLE GRAPHS, which may
give good ideas on how to use jgraph more effectively.
OPTIONS
-P The -P option produces postscript which can be piped
directly to lpr, which can be displayed in an Xwindows
environment with gs (ghostscript). Without this
option, the output should be embedded within LaTeX or a
similar text processing system.
-L The -L option produces a landscape plot.
-p The -p option re-prints the input on the standard out-
put, only with all the defaults made explicit. This is
useful for letting the user do his/her own special for-
matting, as it shows the explicit values that the
defaults assume, so that they can be manipulated.
-comments
This option makes jgraph put comments into the output
postscript. These make it easier for the user to wade
through the final postscript if necessary.
THE DESCRIPTION LANGUAGE
The description language is essentially keywords followed by
attributes. All keywords and attributes except for string
attributes are tokens -- non-white-space characters sur-
rounded by white-space. Special tokens are ``(*'', ``*)'',
``include'', ``:'', and ``shell'', which denote comments,
include-file statements, string identifiers, and shell-
include statements:
Comments
Comments are surrounded by the tokens ``(*'' ``*)'' as
in Modula-2 (except that here, the tokens must be sur-
rounded by white- space). Comments may be nested. If
the comment runs to the end of a file, the last ``*)''
may be omitted.
Include-file statements
The token following an ``include'' token is expected to
be a file name. The result of the statement is to
include the contents of the file at that point.
Include-file statments can be nested within included
files, and within shell includes.
Strings
In places where strings are required (as in graph and
curve labels), they are denoted by the token ``:''.
The second character after the ``:'' starts the string,
and the next newline character terminates it. Thus, the
string ``Graph #1'' can be denoted as:
: Graph #1
or
:
Graph #1
One can get multiline strings by making a backslash the
last character before the newline on all but the last
line. Notice that in strings white-space is not
ignored. This way of denoting strings allows the user
to embed leading and trailing spaces, as well as the
null string. For example, the null string ``'' is
represented by:
:
Once a string has been started, it may contain any
character. Specifically, it may contain the sequence
``(*'', ``shell'', or ``include'' without starting a
comment or including a file. Each line of a string
must contain less than 1000 characters. Otherwise
string sizes are limited only by the size of memory.
Shell-include statements
Shell include statements are of the form ``shell'',
``:'', and then a string. The result of the statement
is that the string is executed (using popen, which
passes the string to sh), and the standard output is
included at that point. Shell-includes can be freely
nested within include-files and other shell-includes.
Shell commands may be more than one line, but must not
exceed 1000 characters. The shell statement is not
(yet) available on VMS.
Notation
In the descriptions below:
tk {integer}
means that token tk must be followed by an
integer.
tk [integer]
means that tk may be followed by an integer, but
doesn't have to. In most cases, if tk is not fol-
lowed by an integer, then the command denoted by
tk is ignored.
tk [{integer} {integer}]*
means that tk must be followed by an even number
of integers.
Supported types other than integer are: {float} for
floating point entries, {token} for any token, and
{string} for a string as defined above.
TOP-LEVEL DESCRIPTION COMMANDS
newgraph
This starts editing a new graph (see GRAPH EDITING
COMMANDS). Note that multiple graphs may be drawn
on the same page.
graph {integer}
This edits the graph denoted by {integer}. If the
graph doesn't exist, then this command creates it
and starts editing it. Newgraph is simply an
abbreviation for graph n where n=0 if this is the
first graph, otherwise n=m+1, where m is the larg-
est number of any graph so far.
copygraph [integer]
This creates a new graph, and copies all the
attributes from the graph [integer]'s x and y
axes, as well as its x_translate and y_translate
values, the clipping, the legend defaults, and the
title defaults. If the [integer] is omitted,
then it copies its values from the ``previous''
graph, which is defined to be the graph with the
largest number less than the currrent graph's
number. If the current graph has the smallest
number, then it will take the last graph from the
previous page of graphs. If there is no previous
page, then an error will be flagged. (copygraph
does not copy the values of the hash_at, mhash_at,
and hash_label attributes).
newpage
This command is for plotting graphs on multiple
pages. After a newpage, the graphs that the user
enters will be plotted on a new page. New graphs
and strings will be numbered starting with 0.
Essentially, newpage is the same as appending
together the output of separate calls of jgraph on
the text before the newpage, and on the text after
the newpage. Newpage will most likely produce
bizarre results if the -P option is not specified.
X [float]
Y [float]
Postscript files to be embedded in LaTeX (and some
other programs) contain a ``bounding box'' which
defines the area which LaTeX will allocate for the
postscript. Other programs use this bounding box
as well, sometimes using it to define where to
clip the postscript image. Jgraph uses the axis
lines and labels, and the title to generate its
bounding box. Most of the time that's good enough
to work in LaTeX. The Y and X commands say to
make the height and width of the bounding box at
least Y and X inches, respectively, but to main-
tain the current centering of the graph. If you
still need further control over the bounding box
(e.g. to change the centering), try the bbox com-
mand. If there's more than one page in the jgraph
file, Y, X and bbox values can be given for each
graph.
bbox float float float float
If the Y and X commands aren't enough to help you
define a good bounding box, this command lets you
explicitly enter one which will go directly into
the jgraph output. Its units are the final
postscript units. It's probably best to use the
-pFR option to see what the bounding box is that
jgraph produces, and then alter that accordingly
with bbox. The main use for this is to change the
automatic centering that jgraph performs: Usually
the center of the bounding box that jgraph com-
putes is put at the center of the page. Changing
the bbox changes this center.
preamble : {string}
preamble {token}
epilogue : {string}
epilogue {token}
These two commands allow the user to include
strings or files (the token specifies the
filename) which will be copied directly into
jgraph's output. The preamble is included at the
beginning of the output (after some initial
postscript to set things up for jgraph), and the
epilogue is included at the end. A good use for
the preamble is to set up a postscript dictionary
if you're using postscript marks.
GRAPH EDITING COMMANDS
These commands act on the current graph. Graph editing
is terminated when one of the top-level description
commands is given.
xaxis
yaxis
Edit the x or y axis (see AXIS EDITING COMMANDS)
newcurve
This starts editing a new curve of the graph (see
CURVE EDITING COMMANDS).
curve {integer}
This edits the curve denoted by {integer}. If the
curve doesn't exist, then this command creates it
and starts editing it. Newcurve and curve interact
as newgraph and graph do.
newline
This is an abbreviation for:
newcurve marktype none linetype solid
copycurve [integer]
This starts editing a new curve of the graph, and
copies all its values except for the points from
curve [integer.] If the [integer] is omitted,
then it copies its values from the last curve in
this graph. If this graph currently has no
curves, then it searches backwards from the previ-
ous graph.
title
This edits the title of the graph (see LABEL EDIT-
ING COMMANDS). The title is given a default loca-
tion centered beneath the graph, and a default
font size of 12, however, as with all labels, this
can be changed.
legend
The edits the legend of the graph (see LEGEND
EDITING COMMANDS). As a default, the graph will
contain a legend if any of its curves have labels.
newstring
This edits a new text string (see LABEL EDITING
COMMANDS). This is useful as it allows the user
to plot text on the graph as well as curves.
string {integer}
copystring [integer]
String and copystring are to newstring as curve
and copycurve are to newcurve.
border
noborder
Border draws a square border around the area
defined by the axes. Noborder specifies no
border. Noborder is the default.
clip
noclip
Clip specifies that all curves in the graph will
be clipped -- that is, no points outside of the of
axes will be plotted. Clipping can also be speci-
fied on a per-curve basis. The default is noclip.
inherit_axes
This is an old command which is kept for backward
compatibility. Copycurve. is equivalent to:
newgraph inherit_axes
x_translate [float]
y_translate [float]
By default, the bottom left-hand corner of each
graph is at point (0,0) (final postscript units).
X_translate and Y_translate translate the bottom
left-hand corner of the graph [float] inches. The
main use of this is to draw more than one graph on
a page. Note that jgraph considers all the graphs
drawn on the page when it computes its bounding
box for centering. Thus, if only one graph is
drawn, it will always be centered on the page,
regardless of its X_translate and Y_translate
values. These values are used for relative place-
ment of the graphs.
To change the centering of the graphs, use
bbox.
X [float]
Y [float]
These are the same as X and Y in the Top-level
commands, except that they let the user continue
editing the current graph.
SIMPLE AXIS EDITING COMMANDS
These commands act on the current axis as chosen by
xaxis or yaxis (see GRAPH EDITING COMMANDS). Axis edit-
ing terminates when a graph or top-level command is
given. There are more advanced axis editing commands
given below which have to do with moving the hash
marks, adding new hash marks and labels, etc. See
ADVANCED AXIS EDITING COMMANDS.
linear
log Set the axis to be linear or logarithmic. The
default is linear. If the axis is set to be loga-
rithmic, then values <= 0.0 will be disallowed, as
they are at negative infinity on the axis.
min [float]
max [float]
Set the minimum and maximum values of this axis.
Defaults depend on the points given. They can be
seen by using the -p option. Unless stated, all
units (for example point plotting, string plot-
ting, etc.) will be in terms of the min and max
values of the x and y axes.
size [float]
Set the size of this axis in inches.
log_base [float]
Set the base of the logarithmic axis. Default =
10. This is the value which determines which hash
marks and hash labels are automatically produced.
hash [float]
Hash marks will be [float] units apart. Default =
-1. If this value equals 0, then there will be no
hash marks. If this value is less than 0, then
the hash marks will be automatically set by jgraph
(see -p for the value). By default, each hash
mark will be labeled with its value. Hash and
shash are ignored if the axes are logarithmic.
shash [float]
Make sure there is a hash mark at the point
[float] along the axis. The default is set by
jgraph if hash = -1. If hash is set by the user,
shash is defaulted to the min value of the axis.
mhash [integer]
Put [integer] minor hash marks between the above
hash marks. Default = -1. If this value equals
0, then there will be no minor hash marks. If
this value is negative, then the value will be
chosen by jgraph (see -p for the value).
precision [integer]
hash_format token
These control how jgraph formats the automatic
hash labels. The user shouldn't have to worry
about these values, except in extreme cases.
Jgraph uses printf to format the labels. If
hash_format is ``f'' (the default), then the value
of a hash label is printed with
printf("%.*f", precision, value).
Other valid hash_format values are ``G'', ``g'', ``E'',
and ``e''. ``G'' is a good generic format which con-
verts to scientific notation if the value becomes too
big or too small. If the precision is negative, then
jgraph chooses a default: For ``g'' and ``G'', the
default is 6. For ``e'' and ``E'', the default is 0,
and for ``f'', jgraph tries to determine a reasonable
default. Please read the man page of prinf(1) for a
complete description of how it formats floating point
numbers.
label
Edit the label of this axis (see LABEL EDITING
COMMANDS). By default, the label is in font
``Times-Bold'', and has a font size of 10. If the
user doesn't change any of the plotting attributes
of the label, jgraph chooses an appropriate place
for the axis label.
draw_at [float]
Draw the axis line at this point on the other
axis. The default is usually the other axis's min,
however if hash_scale is positive (see hash_scale
under ADVANCED AXIS EDITING), it will be the other
axis's max.
nodraw
Do not draw the axis, the hash marks or any
labels. This is useful for plotting points with
no axes, and for overlaying graphs on top of one
another with no clashes. This is equivalent to
no_draw_axis, no_draw_axis_label,
no_draw_hash_marks, and no_draw_hash_labels.
draw Cancels the effect of nodraw. Default = draw.
This is equivalent to draw_axis, draw_axis_label,
draw_hash_marks, and draw_hash_labels.
grid_lines
no_grid_lines
Grid_lines specifies to plot a grid line at each
major hash mark on this axis. The default is
no_grid_lines.
mgrid_lines
no_mgrid_lines
Mgrid_lines specifies to plot a grid line at each
minor hash mark on this axis. The default is
no_mgrid_lines.
CURVE EDITING COMMANDS
These commands act on the current curve as chosen by
newcurve or curve (see GRAPH EDITING COMMANDS). Curve
editing terminates when a graph or top-level command is
given.
pts [{float} {float}]*
This sets the points to plot in this curve. The
first float is the x value, and the second float
is the y value of the point. Points are plotted
in the order specified. This command stops read-
ing points when a non-float is given. The user
can specify this command multiple times within a
curve -- each time, simply more points are added
to the curve.
x_epts [{float} {float} {float} {float}]*
y_epts [{float} {float} {float} {float}]*
This allows the user to specify points and ``con-
fidence values'' (otherwise known as ``error
bars''). The first two floats specify the x and y
values of the point, as above. If x_epts is
specified, then the second two floats specify
range or confidence values for the x value of the
point. Error bars will be printed to each of these
x values (using the original point's y value) from
the original point. Similarly, y_epts specifies
range or confidence values for the y value of the
point. pts x_epts and y_epts can all be inter-
mixed.
marktype
This sets the kind of mark that is plotted for
this curve. Valid marks are: circle, box, dia-
mond, triangle, x, cross, ellipse, xbar, ybar,
text, postscript, eps, none, and variants of gen-
eral. Most of these are self-explanatory, except
for the last few:
Xbar makes the curve into a bar graph with the
bars going to the x axis. Ybar has the bars going
to the y axis.
Text lets the user plot text instead of a mark.
The text is editted as a label (see LABEL EDITING
COMMANDS) immediately following the text command.
The x and y fields of the label have special mean-
ings here: They define where the label is to be
printed in relation to the curve points. For
example, if they are both 0, the label will be
printed directly on the curve points. If x is 1.0
and y is -1.0, then the label will be printed one
unit to the right and one unit below the curve
points (units are units of the x and y axes).
Default label values are 0 for x and y, and center
justification.
Postscript: See the postscript token below.
Eps: See the eps token below.
None means that no mark will be plotted (this is
useful for drawing lines).
There are four types of general marks, which
work using the gmarks command described below.
The four marktypes are general, general_nf,
general_bez, and general_bez_nf.
By default, a new mark is chosen for each curve.
marksize [float] [float]
This sets the size of the mark. The first [float]
is the width of the mark, and the second is the
height. Units are those of the x and y axes
respectively, unless that axis is logarithmic, in
which case the units are inches. Negative mark-
sizes are allowed (e.g. a negative height will
flip a triangle mark). The default mark size can
be determined using the -p option of jgraph
mrotate [float]
This allows the user to rotate the mark [float]
degrees. Default is zero.
gray [float]
color [float float float]
These specify either the grayness of the curve or
its color. Values for gray should be from 0
(black) to 1 (white). Values for color should
also be from 0 to 1. They are RGB values, and
thus define the amount of red, green and blue in
the curve respectively. Specifying color nulli-
fies the gray value, and vice versa. The default
is gray 0
fill [float]
cfill [float float float]
This sets the filling of marks which define an
area to fill (e.g. box, circle, xbar). fill
defines a gray value, and cfill defines a color
value (see gray and color above for a description
of the units). The default is fill 0 (black).
pattern token [float]
This defines the how the mark is to be filled.
Token may be solid (the default), stripe, or
estripe. If solid, then the float is ignored, and
the mark is completely filled in with either the
gray value defined by fill or the color value
defined by cfill. If stripe, then the mark will
be filled with stripes of either the gray value
defined by fill or the color defined by cfill.
The stripes will be rotated by float degrees.
Estripe differs from stripe only in that stripe
draws stripes on a white background, while estripe
simply draws the stripes on an empty background.
poly
nopoly
pfill [float]
pcfill [float float float]
ppattern token [float]
Poly allows the user to make jgraph treat the
curve as a closed polygon (or in the case of a
bezier, a closed bezier curve). pfill, pcfill and
ppattern specify the filling of the polygon, and
work like fill, cfill and pattern above. The
default is nopoly.
gmarks [{float} {float}]*
Gmarks is a way for the user to define custom
marks. For each mark on (x,y), Each pair of
{float_x}, {float_y}, will define a point on the
mark (x + (float_x * marksize_x / 2), y + (float_y
* marksize_y / 2)).
Thus, for example, the box mark could be defined
as
gmarks -1 -1 -1 1 1 1 1 -1
marktype general
The marktypes general, general_nf, general_bez, and
general_bez_nf, allow the gmarks points to define a
closed polygon, a line, a closed bezier curve and a
regular bezier curve respectively (the ``nf'' stands
for ``non-filled'').
postscript : {string}
postscript {token}
This allows the user to enter direct postscript as
a mark. It automatically sets the marktype to
postscript. If a string is entered, then that
string is used as the mark in the jgraph output.
If a token is entered, then that token must stand
for a filename, which will be copied to the output
once for every mark. The postscript will be set
up so that when the string or file is put to the
output, (0, 0) of the the axes is in the middle of
the mark, it is rotated by mrotate degrees, and
scaled by (marksize_x / 2), marksize_y / 2).
Thus, the box mark could be defined as:
postscript : 1 setlinewidth -1 -1 moveto -1 1 lineto \
1 1 lineto 1 -1 lineto -1 -1 lineto stroke
If the marksize_x is defined to be (0, 0), then jgraph
does no scaling. This is useful when the postscript
has strings, and the user does not want the strings to
be scaled.
eps {token}
This allows the user to include an encapsulated
postscript file and treat it as a mark. It
automatically sets the marktype to eps. The file
will be scaled so that the bounding box is mark-
size units. Among other things, this allows the
user to include whole jgraph files as marks.
Please see ad.jgr, explained in HINTS AND EXAMPLE
GRAPHS below for an example of this feature.
larrows
rarrows
nolarrows
norarrows
Rarrows specifies to draw an arrow at the end of
every line segment in the curve. Larrows specifies
to draw an arrow at the beginning of every line
segment. The size of the arrows can be changed by
using asize. The default is nolarrows and norar-
rows.
Arrows always go exactly to the point specified,
with the exception of when the marktype is ``cir-
cle''. In this case, the arrow goes to the edge
of the circle.
larrow
rarrow
nolarrow
norarrow
This is analgous to the above, except that with
larrow, the only arrow drawn is to the beginning
of the first segment in the curve, and with rar-
row, the only arrow drawn is to the end of the
last segment.
asize [float] [float]
This sets the size of the arrows. The first
[float] controls the arrow's width. Its units are
those of the x-axis. The second [float] controls
the arrow's height. It is in the units of the y-
axis. Use the -p option of jgraph to see the
default values.
afill [float]
afill [float]
apattern token [float]
These control the grayness or color of arrowheads.
Afill, acfill and apattern work in the same way as
fill, cfill and pattern described above. The
default is afill 0 (black).
linetype [token]
This defines the type of the line connecting the
points. Valid entries are solid, dotted, dashed,
longdash, dotdash, dotdotdash, dotdotdashdash,
general, and none. The default is none. General
lets the user define his own linetype using the
glines command described below. Points are con-
nected in the order in which they are inserted
using the pts command.
glines [float]*
This lets the user specify the exact dashing of a
line. The format is as in postscript -- the first
number is the length of the first dash, the second
is the length of the space after the first dash,
etc. For example, dotdash could be defined as
``glines 5 3 1 3''.
linethickness [float]
This defines the line thickness (in absolute
postscript units) of the connecting line. Default
= 1.0.
bezier
nobezier
Bezier specifies to use the curve's points to
define successive bezier curves. The first point
is the starting point. The next two are control
points for the bezier curve and the next point is
the ending point. If there is another bezier,
this ending point is also the beginning point of
the next curve. The next two points are again
control points, and the next point is the ending
point. Thus, a bezier must have a total of (3n +
1) points, where n is at least 1.
In bezier curves, marks and arrows only apply to
every third point. Nobezier is the default.
clip This specifies that this curve will be clipped --
that is, no points outside of the of axes will be
plotted.
noclip
This turns off clipping. If clipping was speci-
fied for the entire graph, then noclip has no
effect. Noclip is the default.
label
This edits the label of this curve for the pur-
posed of drawing a legend. (see LABEL EDITING
COMMANDS and LEGEND EDITING COMMANDS). Unless the
legend entry is custom, setting any label attri-
bute except for the text itself will have no
effect.
LABEL EDITING COMMANDS
The following commands are used for editing labels.
Unless stated otherwise, the defaults are written with
each command. Label editing terminates when one of
these tokens is not given.
: {string}
This sets the string of the label. If no string
is set, the label will not be printed.
x [float]
y [float]
This sets the x or y coordinate of the label.
Units are the units of the x and y axes respec-
tively.
font [token]
This sets the font. Default is usually ``Times-
Roman''.
fontsize [float]
This sets the fontsize in points. Default is usu-
ally 9.
linesep [float]
This sets the distance between lines in multilined
labels. Units are points. The default is the
fontsize.
hjl
hjc
hjr These set the horizontal justification to left,
center, and right, respectively. Default = hjc.
vjt
vjc
vjb These set the vertical justification to top
center, and bottom, respectively. Default = vjb.
rotate [float]
This will rotate the string [float] degrees. The
point of rotation is defined by the vj and hj com-
mands. For example, to rotate 90 degrees about
the center of a string, one would use vjc hjc
rotate 90.
lgray [float]
lcolor [float float float]
These control the color or the grayness of the
label. It works just as gray and color do for
curves and axes. The default depends on the con-
text. For example, for strings and the title, the
default is black. For axis labels and hash
labels, the default is the color of the axis. For
text as marks, the default is the curve color.
LEGEND EDITING COMMANDS
These commands allow the user to alter the appearance
of the legend. Legends are printed out for each curve
having a non-null label. The legend entries are
printed out in the order of ascending curve numbers.
Legend editing terminates when a graph command or top
level command is issued.
In earlier versions of jgraph (before version 8.0), the
characteristics of each legend entry were set in the
label portion of the entry's curve. Thus, for example,
if you wanted each entry's fontsize to be 18, you had
to set it in each entry's curve. Now, default legend
entry characteristics are set using the defaults key-
word. Unless a custom legend is specified, these
default values override any values set in the entry's
curve. Thus, to get all entries to have a fontsize of
18, it must be set using defaults fontsize 18.
If legend editing seems cryptic, try the following
example:
newgraph
newcurve marktype box linetype solid label : Solid box
pts 0 0 1 1 2 1 3 1
newcurve marktype circle linetype dotted label : Dotted circle
pts 0 1 1 2 2 2 3 2
newcurve marktype x linetype dashed label : Dashed x
pts 0 2 1 3 2 3 3 3
legend defaults
font Times-Italic fontsize 14 x 1.5 y 3.5 hjc vjb
The legend of this graph should be centered over the top of
the graph, and all legend entries should be 14pt Times-
Italic.
on
offR These turn printing of the legend on and off. The
default is on (but, of course, if there are no
curve labels defined, there will be no legend).
linelength [float]
This sets the length of the line printed in front
of legend entries corresponding to curves which
have lines. Units are those of the x axis, unless
the x axis is logarithmic, in which case the units
are inches. The default may be gotten using the
-p option.
linebreak [float]
This sets the vertical distance between individual
legend entries. Units are those of the y axis,
unless the y axis is logarithmic, in which case
the units are inches. The default may be gotten
using the -p option.
midspace [float]
This sets one of two things. If any of the legend
entries have lines in them, then this sets the
distance between the end of the line and the
legend entry text. Otherwise, this sets the dis-
tance between center of the mark and the legend
entry text. Units are those of the x axis, unless
the x axis is logarithmic, in which case the units
are inches. The default may be gotten using the
-p option.
defaults
This lets the user change the attributes of all
legend entries. The defaults are editted as a
label (see LABEL EDITING COMMANDS). A few of the
label fields have special meanings: The : field
is ignored. The x and y fields define where the
label will be printed. The hj and vj fields
define the justification of the legend about the x
and y point. Thus, if x is 10 and y is 15, and
hjc vjb are specified, then the legend will be
centered horizontally about x=10, and the bottom
of the legend will be placed on y=15. This is
analagous to label plotting. The rotate field is
also analagous to label plotting.
Defaults are as follows. Rotate is 0. font is
``Times-Roman'' and fontsize is 9. The color is
black. Default justification is hjl and vjc. The
default x and y values are set according to the hj
and vj fields. See the -p option.
left
right
These will automatically produce a legend to the
left or the right of the graph. Left is equivalent
to defaults hjr vjc and right is equivalent to
defaults hjl vjc.
top
bottom
These will automatically produce a legend on the
top or the bottom of the graph. Top is equivalent
to defaults hjl vjb
and bottom is equivalent to defaults hjl vjt.
x [float]
y [float]
These are included mainly for backward compatabil-
ity to earlier versions of jgraph. Setting x and
y is equivalent to ``defaults x float y float hjl
vjt''
custom
This lets the user control where each individual
legend entry goes. The values of the defaults
fields are ignored, and instead, the values of the
curve's labels are used. All justifications have
defined results, except for hjc. Similarly, rota-
tion other than 0 is likely to produce bad
effects.
ADVANCED AXIS EDITING
These are more advanced commands for editing an axis.
This includes drawing explicit hash marks and labels,
moving the hash marks, axes, and labels, not drawing
the hash marks, labels, axes, etc.
gray [float]
color [float float float]
These specify either the grayness of the axis or
its color. Values for gray should be from 0
(black) to 1 (white). Values for color should
also be from 0 to 1. They are RGB values, and
thus define the amount of red, green and blue in
the axis respectively. Specifying color nullifies
the gray value, and vice versa. The default is
gray 0. These values affect every part of the
axis: the label, the hash marks and labels, the
axis line and the grid lines.
grid_gray [float]
grid_color [float float float]
mgrid_gray [float]
mgrid_color [float float float]
These allow the user to define the grayness or
color of the gridlines and the mgridlines to be
different from those of the axis lines. The
default grid_gray and grid_color is the same as
the axis's gray and color. The default mgrid_gray
and mgrid_color is the same as grid_gray and
grid_color.
hash_at [float]
Draw a hash mark at this point. No label is made
for this hash mark.
mhash_at [float]
Draw a minor hash mark at this point.
hash_label
Edit a hash label (see HASH LABEL EDITING COM-
MANDS).
hash_labels
Edit the default characteristics of the hash
labels. This is so that the user can change the
fontsize, justification, etc., of the hash labels.
Editing hash_labels is just like editing normal
labels (see LABEL EDITING COMMANDS), except that
the :, x, and y values are all ignored. Defaults
for hash labels are as follows: Fontsize=9,
Font=``Times-Roman'', Justification is dependent
on whether it is the x or y axis and whether
hash_scale is positive or negative.
hash_scale [float]
This is to change the size and orientation of the
hash marks. Default = -1.0. Changing this to
-2.0 will double the length of the hash marks.
Changing this to +1.0 will make the hash marks
come above or to the right of the axis.
draw_hash_marks_at [float]
By default, the hash marks are drawn either above
or below the axis. This command changes where
they are drawn. Hash_scale still determines
whether they are drawn above or below this point,
and their size.
draw_hash_labels_at [float]
By default, the hash labels are drawn either above
or below the hash marks (again, this is dependent
on hash_scale). This command changes where they
are drawn. Justification and fontsize, etc., can
be changed with the hash_labels command.
auto_hash_marks
no_auto_hash_marks
This toggles whether or not jgraph will automati-
cally create hash marks according to hash, mhash
and shash (or log_base and mhash for logarithmic
axes). The default is auto_hash_marks.
auto_hash_labels
no_auto_hash_labels
This toggles whether or not jgraph will automati-
cally create hash labels for the auto_hash_marks.
Default = auto_hash_labels.
draw_axis
no_draw_axis
This toggles whether or not the axis line is
drawn. Default = draw_axis.
draw_axis_label
no_draw_axis_label
This toggles whether or not the axis label (as
editted by the label command) is drawn. Default =
draw_axis_label.
draw_hash_marks
no_draw_hash_marks
This toggles whether or not the hash marks (both
automatic and those created with hash_at and
mhash_at) are drawn. Default = draw_hash_marks.
draw_hash_labels
no_draw_hash_labels
This toggles whether or not the hash labels are
drawn. Default = draw_hash_labels.
HASH LABEL EDITING COMMANDS
Hash labels are simply strings printed along the
appropriate axis. As a default, they are printed at
the place denoted by the most recent hash_at or
mhash_at for this axis, but this can be changed by the
at command. If there has been no hash_at or mhash_at,
then an at command must be given, or there will be an
error. Hash editing terminates when either one of
these commands is not given.
: {string}
This sets the string of the hash label (see
Strings above under THE DESCRIPTION LANGUAGE).
at [float]
This sets the location of the hash label along the
current axis.
FUNCTION PLOTTING AND OTHER NON-INHERENT FEATURES
Although jgraph doesn't have any built-in functions for
interpolation or function plotting, both can be effected in
jgraph with a little outside help:
Function plotting
With the include and shell statement, it's easy to
create a file of points of a function with a c or awk
program, and include it into a graph. See the section
HINTS AND EXAMPLE GRAPHS for an example of a sin graph
produced in this manner.
Point interpolation
Point interpolation is essentially the same as function
plotting, and therefore is left out of jgraph. The UNIX
spline(1) routine is a simple way to get interpolation
between points. See bailey.jgr described below. Maybe
in a future release.
HINTS AND EXAMPLE GRAPHS
Jgraph should be able to draw any kind of scatter/line/bar
graph that a user desires. To embellish the graph with
extra text, axes, lines, etc., it is helpful to use copy-
graph. The following example graphs show a few examples of
different features of jgraph. They should be in the direc-
tory JGRAPH_DIR.
- acc.jgr is a simple bar graph. Acc.tex is also included
to show how one can include the output of jgraph in a LaTeX
file. To get this to work, you might have to substitute the
entire pathname of the file acc.jps in the acc.tex file.
- g8.jgr is a simple graph with some plotted text. -
g8col.jgr shows how to produce a color background -- it is
the same as g8.jgr only all on a yellow background. -
ebars.jgr is a simple graph with error bars. - sin.jgr
shows how a sin function can be plotted using a simple c
program to produce the sin wave. Moreover, this file shows
a use of copygraph to plot an extra x and y axis at the 0
point.
- sin1.jgr is a further extension of sin.jgr only with one x
and y axis at 0, but with the axis labels at the left and
the bottom of the graph.
- sin2.jgr is a different sin wave with a logarithmic x
axis.
- sin3.jgr shows how a bizarre effect can be gotten by sort-
ing the points in a different manner.
- bailey.jgr shows how to use the UNIX spline(1) routine to
get interpolation between points.
- gpaper.jgr shows how you can get jgraph to easily produce
graph paper.
- g9n10.jgr contains two graphs with complicated legends.
It contains a description of how the legend was created.
- ex1.jgr and ex2.jgr are two examples which were figures 1
and two in an extended abstract for a paper about jgraph.
- mab2.jgr is a graph created by Matt Blaze which shows how
a complicated output graph can be quite concisely and simply
stated. In this graph, the x axis is a time line. It shows
usage of the hash_label and hash_labels commands, as well as
displaying how jgraph lets you extract data from output
files with awk.
- nr.jgr is an example of a rather complicated bar graph
with stripe-filled bars. It was created by Norman Ramsey.
- hypercube.jgr shows an interesting use of jgraph for
picture-drawing.
- ad.jgr is an example which shows how one can include
jgraph output as jgraph input. The file uses the eps token
to include cube.jgr, a jgraph drawing of an Intel hypercube,
and disk.jgr, a jgraph drawing of a disk, in a picture.
- alb.jgr is another use of jgraph for picture drawing.
This file was created by an awk script which Adam Buchsbaum
wrote to draw trees and graphs.
- wortman.jgr is a neat graph of processor utilization writ-
ten by Dave Wortman for SIGPLAN '92. It was created by an
awk script, which processed the data and emitted the jgraph.
To view these graphs, use jgraph -P, and view the resulting
output file with gs, or a similar postscript viewer. To
make a hard copy of these graphs, pipe the output of jgraph
-P directly to lpr.
USING JGRAPH TO DRAW PICTURES
As hypercube.jgr and alb.jgr show, jgraph can be used as a
postscript preprocessor to make drawings. There are two
advantages using jgraph to draw pictures instead of using
standard drawing tools like xfig, figtool, or idraw. The
first is that with jgraph, you know exactly where strings,
lines, boxes, etc, will end up, because you plot them expli-
citly. The second advantage is that for iterative drawings,
with lots of patters, you can combine jgraph with awk or c
or any other programming language to get complex output in a
simple way. Most what-you-see-is-what-you-get (WYSIWYG)
drawing tools cannot do this.
The major disadvantage of using jgraph to draw pictures is
that jgraph is not WYSIWYG. You have to set up axes and
plot points, lines and strings. It's all a matter of taste.
If you'd like to see some more complex pictures drawn with
jgraph, as well as some hints to make picture-drawing
easier, send me email (jsp@princeton.edu).
EMBEDDING THE OUTPUT IN LATEX
I haven't read the manuals, but the way I've been loading
these files into LaTeX has been as follows:
1. Toward the beginning of my LaTeX file, I've had ``\input{psfig}''
2. Where I've wanted my file, I've put:
\begin{figure}
\centerline{\psfig{figure=/}}
\end{figure}
Some versions of dvips or dvi2ps work without the path-name. Others
require that the path-name be present.
3. After running latex on the file, do
lpr -d file.dvi
4. If that doesn't work, try dvips-ing the file and printing the postscript.
BUGS
Logarithmic axes cannot contain points <= 0. If I have
enough complaints to convince me that this is a bug, I'll
try to fix it.
There is no real way to make the axes such that they
decrease from left to right or low to high -- or at least
not without writing your own hash labels.
There may well be loads of other bugs. Send to
jsp@princeton.edu.