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 different 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.
: Graph #1<newline>
or
:<newline>
Graph #1<newline>
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:
: <newline>
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.
Supported types other than integer are: {float} for floating point entries, {token} for any token, and {string} for a string as defined above.
newcurve marktype none linetype solid
newgraph inherit_axes
printf("%.*f", precision, value).
Other valid hash_format values are ``G'', ``g'', ``E'', and ``e''. ``G'' is a good generic format which converts 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.
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 : 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.
token}
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 keyword. 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.
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.
- 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 sorting 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 written 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.
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).
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=<path-name>/<filename-of-jgraph-output>}}
\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.
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.
This is $Revision: 8.3 $.