source: trunk/Jgraph/jgraph.1@ 594

.\" SCCSID: @(#)jgraph.1        1.1     10/23/89
.\" SCCSID: @(#)jgraph.1        1.1     10/23/89
.TH jgraph 1
.SH NAME
jgraph \- filter for graph plotting to postscript
.SH SYNTAX
.B jgraph 
[\-\fIp\fR\|]
[\-\fIP\fR\|]
[\-\fIL\fR\|]
[\-\fIcomments\fR\|]
[\fIfilename\fR ...\|]
.SH DESCRIPTION
\fBJgraph\fR
takes the description of a graph or graphs
and produces a postscript file on the standard output.  
\fBJgraph\fR
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.
.sp
\fBJgraph\fR reads its input from the specified files.  If no
files are specified, then it reads from standard input.
.sp
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).
.sp
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:
.PP
.nf
        newgraph
        newcurve pts 2 3 4 5 1 6
.fi
.PP
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:
.PP
.nf
        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
.fi
.PP
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:
.PP
.nf
        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
.fi
.PP
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 
\fBjgraph\fR,
however, the others can be effected with
\fBjgraph \fR
mixed with awk or c.  See 
FUNCTION PLOTTING AND OTHER NON-INHERENT FEATURES 
below.
.sp
Also below is a section 
HINTS AND EXAMPLE GRAPHS, which may give good
ideas on how to use 
\fBjgraph \fR
more effectively.
.SH OPTIONS
.TP
.B \-P
The 
\fB\-P\fR
option produces postscript which can be piped directly to 
\fBlpr,\fR  
which can be displayed in an Xwindows environment with
\fBgs\fR
(ghostscript).
Without this option, the output should be embedded within 
\fBLaTeX\fR
or a similar text processing system.
.TP
.B \-L
The 
\fB\-L\fR
option produces a landscape plot.
.TP
.B \-p
The 
\fB\-p\fR
option re-prints the input on the standard output, only
with all the defaults made explicit.  This is useful for letting the
user do his/her own special formatting, as it shows the explicit
values that the defaults assume, so that they can be manipulated.
.TP
.B \-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. 
.SH 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 surrounded by white-space. 
Special tokens are 
``(*'', ``*)'', ``include'', ``:'', and ``shell'', which denote
comments, include-file statements, string identifiers, and shell-include
statements:
.TP 
.B Comments
Comments are surrounded by the tokens ``(*'' ``*)'' as in
Modula-2 (except that here, the tokens must be surrounded by white-
space).  Comments may be nested.  If the comment runs to the end of a
file, the last ``*)'' may be omitted.
.TP 
.B 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.
.TP 
.B 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:
.nf

        : Graph #1<newline>

or

        :<newline>
        Graph #1<newline>

.fi
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:
.nf

        : <newline>

.fi
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.
.TP
.B 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.
.TP
.B Notation
In the descriptions below: 
.RS
.TP
\fBtk \|{\fIinteger\fB\|}\fR
means that token
\fBtk \fR
must be followed by an integer.  
.TP
\fBtk \|[\fIinteger\fB\|]\fR
means that 
\fBtk\fR
may be followed by an integer, but doesn't have to.  In most cases, if
\fBtk\fR
is not followed by an integer, then the command denoted by
\fBtk \fR
is ignored.  
.TP
\fBtk \|[\|{\fIinteger\fB\|} \|{\fIinteger\fB\|}\|]*
means that 
\fBtk\fR
must be
followed by an even number of integers.  
.PD
.LP
Supported types other than
integer are: 
\fB\|{\fIfloat\fB\|} \fR
for floating point entries, 
\fB\|{\fItoken\fB\|} \fR
for any
token, and 
\fB\|{\fIstring\fB\|} \fR
for a string as defined above.
.RE
.TP
.B TOP-LEVEL DESCRIPTION COMMANDS
.RS
.TP
.B newgraph
This starts editing a new graph (see GRAPH EDITING
COMMANDS).  Note that multiple graphs may be drawn on the same page.
.TP
\fBgraph \|{\fIinteger\fB\|}\fR
This edits the graph denoted by 
\fB\|{\fIinteger\fB\|}.  \fR
If the graph doesn't exist, then this command creates it and starts
editing it.  
\fBNewgraph\fR
is simply an abbreviation for 
\fB\fIgraph\fB \fIn\fB\fR
where n=0 if this is the first graph, otherwise n=m+1, where m is the
largest number of any graph so far.
.TP
\fBcopygraph \|[\fIinteger\fB\|]\fR
This creates a new graph, and copies all the attributes from the
graph
\fB\|[\fIinteger\fB\|]'s\fR
x and y axes, as well as its 
\fB\fIx_translate\fB\fR
and 
\fB\fIy_translate\fB\fR
values, the clipping, the legend defaults, and 
the title defaults.   If the
\fB\|[\fIinteger\fB\|]\fR
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 
\fB\fIhash_at\fR, \fImhash_at\fR,\fR
and 
\fB\fI\fIhash_label\fB\fR 
attributes). 
.TP
.B newpage
This command is for plotting graphs on multiple pages.  After a 
\fBnewpage,\fR
the graphs that the user enters will be plotted on a new page.
New graphs and strings will be numbered starting with 0.  
Essentially, 
\fB\fInewpage\fB\fR
is the same as appending together the output of separate calls of
jgraph on the text before the 
\fB\fInewpage\fR,\fR
and on the text after the 
\fB\fInewpage.\fR
\fB\fINewpage\fB\fR
will most likely produce bizarre results if the
\fB\-P\fR
option is not specified.
.TP
\fBX \|[\fIfloat\fB\|]\fR
.br
.ns
.TP
\fBY \|[\fIfloat\fB\|]\fR
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.
\fBJgraph \fR
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 
\fB\fIY\fB\fR
and
\fB\fIX\fB\fR
commands say to make the height and width of the bounding box at least
\fB\fIY\fB\fR
and
\fB\fIX\fB\fR
inches, respectively, but to maintain the current centering of the 
graph.  If you still need further control over the
bounding box (e.g. to change the centering), try the
\fB\fIbbox\fB\fR
command.  If there's more than one page in the jgraph file, 
\fB\fIY\fR,\fR
\fB\fIX\fB\fR
and
\fB\fIbbox\fB\fR
values can be given for each graph.
.TP
\fBbbox \fIfloat\fB \fIfloat\fB \fIfloat\fB \fIfloat\fB\fR
If the 
\fB\fIY\fB\fR
and
\fB\fIX\fB\fR
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 
\fB\-p\fR 
option
to see what the bounding box is that jgraph produces, and then
alter that accordingly with
\fB\fIbbox.\fR
The main use for this is to change the automatic centering that jgraph
performs:  Usually the center of the bounding box that jgraph computes 
is put at the center of the page.  Changing the bbox changes this 
center.
.TP
\fBpreamble : \|{\fIstring\fB\|}\fR   
.br
.ns
.TP
\fBpreamble {\fItoken\fB\|}\fR   
.br
.ns
.TP
\fBepilogue : \|{\fIstring\fB\|}\fR   
.br
.ns
.TP
\fBepilogue {\fItoken\fB\|}\fR   
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 \fIpreamble\fR is included at the beginning of the output
(after some initial postscript to set things up for jgraph), 
and the \fIepilogue\fR is included at the end.  A good use for
the \fIpreamble\fR is to set up a postscript dictionary if you're
using postscript marks.
.PD
.RE
.LP
.TP
.B GRAPH EDITING COMMANDS
These commands act on the current graph. 
Graph editing is terminated when one of the top-level description
commands is given.
.RS
.TP
\fBxaxis\fR
.br
.ns
.TP
\fByaxis\fR
Edit the x or y axis (see AXIS EDITING COMMANDS)
.TP
\fBnewcurve\fR  
This starts editing a new curve of the graph (see CURVE
EDITING COMMANDS).
.TP
\fBcurve \|{\fIinteger\fB\|}\fR   
This edits the curve denoted by 
\fB\|{\fIinteger\fB\|}.  \fR
If the curve doesn't exist, then this command creates it and starts
editing it.  
\fINewcurve\fR
and 
\fIcurve\fR
interact as 
\fInewgraph\fR
and
\fIgraph\fR
do.
.TP
\fBnewline\fR  
This is an abbreviation for:
.PP
.nf
          newcurve marktype none linetype solid
.fi
.PP
.TP
\fBcopycurve \|[\fIinteger\fB\|]\fR
This starts editing a new curve of the graph, and copies all its 
values except for the points from curve 
\fB\|[\fIinteger.\fB\|]\fR
If the 
\fB\|[\fIinteger\fB\|]\fR
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 previous graph.
.TP
\fBtitle\fR   
This edits the title of the graph (see LABEL EDITING
COMMANDS).  The title is given a default location centered beneath
the graph, and a default font size of 12, however, as with all
labels, this can be changed.
.TP
\fBlegend\fR   
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.
.TP
\fBnewstring\fR   
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.
.TP
\fBstring \|{\fIinteger\fB\|}\fR   
.br
.ns
.TP
\fBcopystring \|[\fIinteger\fB\|]\fR
\fIString\fR
and
\fIcopystring\fR
are to 
\fInewstring\fR
as
\fIcurve\fR
and
\fIcopycurve\fR
are to
\fInewcurve\fR.
.TP
\fBborder\fR
.br
.ns
.TP
\fBnoborder\fR
\fIBorder\fR
draws a square border around the area defined by the axes.
\fINoborder\fR
specifies no border.
\fINoborder\fR
is the default.  
.TP
\fBclip\fR
.br
.ns
.TP
\fBnoclip\fR
\fIClip\fR
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
specified on a per-curve basis.  The default is
\fInoclip\fR.
.TP
\fBinherit_axes\fR   
This is an old command which is kept for backward compatibility.
\fICopycurve\fR.
is equivalent to:
.PP
.nf
          newgraph inherit_axes
.fi
.PP
.TP
\fBx_translate \|[\fIfloat\fB\|]\fR   
.br
.ns
.TP
\fBy_translate \|[\fIfloat\fB\|]\fR   
By default, the bottom left-hand corner of each graph is at point
(0,0) (final postscript units).
\fIX_translate\fR
and
\fIY_translate\fR
translate the bottom left-hand corner of the graph 
\fB\|[\fIfloat\fB\|] \fR
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 
\fIX_translate\fR
and
\fIY_translate\fR
values.  These values are used for relative placement of the graphs.
   To change the centering of the graphs, use
\fIbbox.\fR
.TP
\fBX \|[\fIfloat\fB\|]\fR
.br
.ns
.TP
\fBY \|[\fIfloat\fB\|]\fR   
These are the same as 
\fIX\fR
and 
\fIY\fR
in the
Top-level commands, except that they let the user continue editing
the current graph.
.PD
.RE
.LP
.TP
.B SIMPLE AXIS EDITING COMMANDS
These commands act on the current
axis as chosen by 
\fIxaxis\fR
or
\fIyaxis\fR
(see GRAPH EDITING COMMANDS). 
Axis editing 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.
.RS
.TP
\fBlinear\fR
.br
.ns
.TP
.B log
Set the axis to be linear or logarithmic. The
default is linear.  If the axis is set to be logarithmic, then values
<= 0.0 will be disallowed, as they are at negative infinity on the
axis. If you are using logarithmic axes and the labels shows 0 0 1 10
instead of 0.01 0.1 1 10, then you should read "hash_format" in this
section. Hint: xaxis log hash_format g
.TP
\fBmin \|[\fIfloat\fB\|]\fR
.br
.ns
.TP
\fBmax \|[\fIfloat\fB\|]\fR   
Set the minimum and maximum values of
this axis.  Defaults depend on the points given.  They can be seen by
using the 
\fB\-p \fR
option.  Unless stated, all units (for example point
plotting, string plotting, etc.) will be in terms of the
\fImin\fR
and
\fImax\fR
values of the x and y axes.
.TP
\fBsize \|[\fIfloat\fB\|]\fR   
Set the size of this axis in inches.
.TP
\fBlog_base \|[\fIfloat\fB\|]\fR   
Set the base of the logarithmic axis. Default =
10.  This is the value which determines which hash
marks and hash labels are automatically produced.
.TP
\fBhash \|[\fIfloat\fB\|]\fR   
Hash marks will be 
\fB\|[\fIfloat\fB\|] \fR
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 
\fBjgraph \fR
(see 
\fB\-p \fR
for the value).  By default, each hash mark
will be labeled with its value.  
\fIHash\fR
and 
\fIshash\fR
are ignored if
the axes are logarithmic.
.TP
\fBshash \|[\fIfloat\fB\|]\fR   
Make sure there is a hash mark at the point
\fB\|[\fIfloat\fB\|] \fR
along the axis.  The default is set by 
\fBjgraph\fR
if
\fBhash\fR
= -1.
If 
\fIhash\fR
is set by the user, 
\fIshash\fR
is defaulted to the
\fImin\fR
value of the axis.
.TP
\fBmhash \|[\fIinteger\fB\|]\fR   
Put 
\fB\|[\fIinteger\fB\|] \fR
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 
\fBjgraph \fR
(see 
\fB\-p\fR
for the value).
.TP
\fBprecision \|[\fIinteger\fB\|]\fR   
.TP
\fBhash_format \fItoken\fB\fR   
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 \fBprintf\fR to format the labels.
If \fBhash_format\fR is ``f'' (the default), then the 
value of a hash label is printed with 
.PP
.nf
        printf("%.*f", precision, value).
.fi
.PP
Other valid \fBhash_format\fR 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 \fBprinf(1)\fR for a complete description
of how it formats floating point numbers.
.TP
\fBlabel\fR   
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, 
\fBjgraph \fR
chooses an appropriate place for the axis label.
.TP
\fBdraw_at \|[\fIfloat\fB\|]\fR   
Draw the axis line at this point on the other axis. 
The default is usually the other axis's 
\fImin\fR,
however if 
\fIhash_scale \fR
is positive (see 
\fIhash_scale \fR
under ADVANCED AXIS EDITING), it will be
the other axis's 
\fImax\fR.
.TP
\fBnodraw\fR   
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
\fIno_draw_axis\fR,
\fIno_draw_axis_label\fR,
\fIno_draw_hash_marks\fR,
and
\fIno_draw_hash_labels\fR.
.TP
\fBdraw\fR   
Cancels the effect of 
\fInodraw\fR.
Default = 
\fIdraw\fR
This is
equivalent to 
\fIdraw_axis\fR,
\fIdraw_axis_label\fR,
\fIdraw_hash_marks\fR,
and 
\fIdraw_hash_labels\fR.
.TP
\fBgrid_lines\fR
.br
.ns
.TP
\fBno_grid_lines\fR
\fIGrid_lines\fR
specifies to plot a grid line at each major hash
mark on this axis.  The default is 
\fIno_grid_lines.\fR
.TP
\fBmgrid_lines\fR
.br
.ns
.TP
\fBno_mgrid_lines\fR
\fIMgrid_lines\fR
specifies to plot a grid line at each minor hash
mark on this axis.  The default is 
\fIno_mgrid_lines\fR.
.PD
.RE
.LP
.TP
.B CURVE EDITING COMMANDS 
These commands act on the current curve as
chosen by 
\fInewcurve\fR
or 
\fIcurve\fR
(see GRAPH EDITING COMMANDS).  Curve
editing terminates when a graph or top-level command is given.
.RS
.TP
\fBpts \|[\|{\fIfloat\fB\|} \|{\fIfloat\fB\|}\|]*\fR   
This sets the points to plot in this
curve.  The first 
\fIfloat\fR
is the x value, and the second 
\fIfloat\fR
is the y
value of the point.  Points are plotted in the order specified.
This command stops reading 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.
.TP
\fBx_epts \|[\|{\fIfloat\fB\|} \|{\fIfloat\fB\|} \|{\fIfloat\fB\|} \|{\fIfloat\fB\|}\|]*\fR   
.br
.ns
.TP
\fBy_epts \|[\|{\fIfloat\fB\|} \|{\fIfloat\fB\|} \|{\fIfloat\fB\|} \|{\fIfloat\fB\|}\|]*\fR   
This allows the user to specify points and ``confidence values'' (otherwise
known as ``error bars'').  The first two 
\fIfloats\fR
specify the x and y values of
the point, as above.  If
\fBx_epts\fR
is specified,  then the second two
\fIfloats\fR
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,
\fIy_epts\fR
specifies range or confidence values for the y value of the point.
\fIpts\fR
\fIx_epts\fR
and
\fIy_epts\fR
can all be intermixed. 
.TP
\fBmarktype\fR   
This sets the kind of mark that is plotted for this curve.  Valid
marks are: \fIcircle\fR, \fIbox\fR, \fIdiamond\fR, \fItriangle\fR,
\fIx\fR, \fIcross\fR, \fIellipse\fR, \fIxbar\fR, \fIybar\fR,
\fItext\fR, \fIpostscript\fR, \fIeps\fR, \fInone\fR, and variants of
\fIgeneral\fR.  Most of these are self-explanatory, except for the
last few: 
  \fIXbar\fR makes the curve into a bar graph with the bars going
to the x axis.  \fIYbar\fR has the bars going to the y axis. 
  \fIText\fR lets the user plot text instead of a mark.  The text is 
editted as a label (see LABEL EDITING COMMANDS) immediately following
the \fItext\fR command.  The x and y fields of the label have special
meanings 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.
  \fIPostscript\fR: See the \fIpostscript\fR token below.
  \fIEps\fR: See the \fIeps\fR token below.
  \fINone\fR means that no mark will be
plotted (this is useful for drawing lines).  
  There are four types of \fIgeneral\fR marks, which work using the 
\fIgmarks\fR command described below.  The four marktypes are 
\fIgeneral\fR, \fIgeneral_nf\fR, \fIgeneral_bez\fR, and 
\fIgeneral_bez_nf\fR.
  By default, a new mark is chosen for each curve.
.TP
\fBmarksize \|[\fIfloat\fB\|] \|[\fIfloat\fB\|]\fR   
This sets the size of the mark.  The
first 
\fB\|[\fIfloat\fB\|] \fR
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 marksizes
are allowed (e.g.  a negative height will flip a \fItriangle\fR mark). 
The default mark size can be determined using the 
\fB\-p\fR
option of
\fBjgraph\fR
.TP
\fBmrotate \|[\fIfloat\fB\|]\fR
This allows the user to rotate the mark
\fB\|[\fIfloat\fB\|] \fR
degrees.  Default is zero.
.TP
\fBgray \|[\fIfloat\fB\|]\fR
.br
.ns
.TP
\fBcolor \|[\fIfloat\fB \fIfloat\fB \fIfloat\fB\|]\fR   
These specify either the grayness of the curve or its color.  Values 
for 
\fIgray\fR
should be from 0 (black) to 1 (white).  Values for
\fIcolor\fR
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 nullifies the gray value, and vice versa.  The default is 
\fIgray 0\fR
.TP
\fBfill \|[\fIfloat\fB\|]\fR   
.br
.ns
.TP
\fBcfill \|[\fIfloat\fB\| \|\fIfloat\fB\| \|\fIfloat\fB\|]\fR   
This sets the filling of marks which define an area
to fill (e.g.  \fIbox\fR, \fIcircle\fR, \fIxbar\fR).  
\fIfill\fR
defines a gray value, and 
\fIcfill\fR
defines a color value (see 
\fIgray\fR
and
\fIcolor\fR
above for a description of the units).
The default is 
\fIfill 0\fR
(black).
.TP
\fBpattern \fItoken\fB \|[\fIfloat\fB\|]\fR   
This defines the how the mark is to be filled.  \fIToken\fR
may be \fIsolid\fR (the default), \fIstripe\fR, or \fIestripe\fR.  If 
\fIsolid\fR, then the \fIfloat\fR is ignored, and the mark is
completely filled in with either the gray value defined by
\fIfill\fR or the color value defined by \fIcfill\fR.
If \fIstripe\fR, then the mark will be filled with stripes of
either the gray value defined by \fIfill\fR or the color defined
by \fIcfill\fR.  The stripes will be rotated by \fIfloat\fR 
degrees.  \fIEstripe\fR differs from \fIstripe\fR only in that 
\fIstripe\fR draws 
stripes on a white background, while \fIestripe\fR simply draws the 
stripes on an empty background.
.TP
\fBpoly\fR
.br
.ns
.TP
\fBnopoly\fR
.br
.ns
.TP
\fBpfill \|[\fIfloat\fB\|]\fR   
.br
.ns
.TP
\fBpcfill \|[\fIfloat\fB\| \|\fIfloat\fB\| \|\fIfloat\fB\|]\fR   
.br
.ns
.TP
\fBppattern \fItoken\fB \|[\fIfloat\fB\|]\fR   
\fIPoly\fR allows the user to make jgraph treat the curve as a 
closed polygon (or in the case of a bezier, a closed bezier curve).
\fIpfill\fR, \fIpcfill\fR and \fIppattern\fR  specify the 
filling of the polygon,
and work like \fIfill\fR, \fIcfill\fR and \fIpattern\fR above.  
The default is \fInopoly\fR.
.TP
\fBgmarks \|[\|{\fIfloat\fB\|} \|{\fIfloat\fB\|}\|]*\fR   
\fIGmarks\fR
is a way for the user to define custom marks.  For each mark on 
\fI(x,y)\fR,
Each pair of 
\fB\|{\fIfloat_x\fB\|}, \|{\fIfloat_y\fB\|}, \fR
will define a point on the mark (x + 
\fB(\fIfloat_x\fB * \fImarksize_x\fB / 2), y + (\fIfloat_y\fB * \fImarksize_y\fB / 2)).\fR
  Thus, for example, the
\fIbox\fR mark could be defined as 
.PP
.nf
        gmarks -1 -1 -1 1 1 1 1 -1
        marktype general
.fi
.PP
The marktypes \fIgeneral\fR, \fIgeneral_nf\fR, \fIgeneral_bez\fR,
and \fIgeneral_bez_nf\fR, 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'').
.TP
\fBpostscript : \|{\fIstring\fB\|}\fR   
.br
.ns
.TP
\fBpostscript {\fItoken\fB\|}\fR   
This allows the user to enter direct postscript as a mark.  It 
automatically sets the marktype to \fIpostscript\fR.  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
\fImrotate\fR degrees, and scaled by 
(\fImarksize_x\fR / 2), \fImarksize_y\fR / 2).
Thus, the \fIbox\fR mark could be defined as:
.PP
.nf
        postscript : 1 setlinewidth -1 -1 moveto -1 1 lineto \\
                  1 1 lineto 1 -1 lineto -1 -1 lineto stroke
.fi
.PP
If the \fImarksize_x\fR 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.
.TP
\fBeps {\fItoken\fB\|}\fR   
This allows the user to include an encapsulated postscript file
and treat it as a mark.  It automatically sets the marktype to
\fIeps\fR.  The file will be scaled so that the bounding
box is \fImarksize\fR 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.
.TP
\fBlarrows\fR
.br
.ns
.TP
\fBrarrows\fR
.br
.ns
.TP
\fBnolarrows\fR
.br
.ns
.TP
\fBnorarrows\fR
\fIRarrows\fR
specifies to draw an arrow at the end of every line
segment in the curve.  
\fILarrows\fR
specifies to draw an arrow at the beginning of every line segment.
The size of the arrows can be changed by using
\fIasize.\fR
The default is
\fInolarrows\fR
and
\fInorarrows\fR.
  Arrows always go exactly to the point specified, with the exception 
of when the marktype is ``circle''.  In this case, the arrow goes to
the edge of the circle.
.TP
\fBlarrow\fR
.br
.ns
.TP
\fBrarrow\fR
.br
.ns
.TP
\fBnolarrow\fR
.br
.ns
.TP
\fBnorarrow\fR
This is analgous to the above, except that with \fIlarrow\fR, the
only arrow drawn is to the beginning of the first segment in the
curve, and with \fIrarrow\fR, the only arrow drawn is to the end
of the last segment.
.TP
\fBasize \|[\fIfloat\fB\|] \|[\fIfloat\fB\|]\fR   
This sets the size of the arrows.  The first 
\fB\|[\fIfloat\fB\|] \fR
controls the arrow's width.  Its units are those of the x-axis.
The second
\fB\|[\fIfloat\fB\|] \fR
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.
.TP
\fBafill \|[\fIfloat\fB\|]\fR
.br
.ns
.TP
\fBafill \|[\fIfloat\fB\|]\fR
.br
.ns
.TP
\fBapattern \fItoken\fB \|[\fIfloat\fB\|]\fR   
These control the grayness or color of arrowheads.  
\fIAfill\fR,
\fIacfill\fR
and 
\fIapattern\fR
work in the same way as 
\fIfill\fR,
\fIcfill\fR
and
\fIpattern\fR
described above.  The default is
\fIafill 0\fR
(black).
.TP
\fBlinetype \|[\fItoken\fB\|]\fR   
This defines the type of the line connecting the points.  Valid
entries are \fIsolid\fR, \fIdotted\fR, \fIdashed\fR, \fIlongdash\fR,
\fIdotdash\fR, \fIdotdotdash\fR, \fIdotdotdashdash\fR, \fIgeneral\fR, and
\fInone\fR.  The default is \fInone\fR.  \fIGeneral\fR lets the user define
his own linetype using the
\fIglines\fR
command described below.  Points are connected in the
order in which they are inserted using the 
\fIpts\fR
command.
.TP
\fBglines \|[\fIfloat\fB\|]*\fR   
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, \fIdotdash\fR could be defined as ``\fIglines\fR 5 3
1 3''.  
.TP
\fBlinethickness \|[\fIfloat\fB\|]\fR   
This defines the line thickness (in
absolute postscript units) of the connecting line.  Default = 1.0.
.TP
\fBbezier\fR
.br
.ns
.TP
\fBnobezier\fR
.br
.ns
\fIBezier\fR
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.
\fINobezier\fR is the default.

.TP
\fBclip\fR
This specifies that this curve will be clipped -- that is,
no points outside of the of axes will be plotted.  
.TP
\fBnoclip\fR
This turns off clipping.  If clipping was specified for the 
entire graph, then 
\fInoclip\fR
has no effect.
\fINoclip\fR
is the default.
.TP
\fBlabel\fR   
This edits the label of this curve for the purposed of
drawing a legend.  (see LABEL EDITING COMMANDS and LEGEND EDITING
COMMANDS).  Unless the legend entry is 
\fIcustom\fR,
setting any label attribute except for the text itself
will have no effect.
.PD
.RE
.LP
.TP
.B 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.
.RS
.TP
\fB: \|{\fIstring\fB\|}\fR   
This sets the string of the label.  If no string is
set, the label will not be printed.
.TP
\fBx \|[\fIfloat\fB\|]\fR
.br
.ns
.TP
\fBy \|[\fIfloat\fB\|]\fR   
This sets the x or y coordinate of the
label.  Units are the units of the x and y axes respectively.
.TP
\fBfont \|[\fItoken\fB\|]\fR   
This sets the font.  Default is usually ``Times-Roman''.
.TP
\fBfontsize \|[\fIfloat\fB\|]\fR   
This sets the fontsize in points.  Default is usually 9.
.TP
\fBlinesep \|[\fIfloat\fB\|]\fR   
This sets the distance between lines in multilined labels.  Units are points.
The default is the fontsize.
.TP
\fBhjl\fR
.br
.ns
.TP
\fBhjc\fR
.br
.ns
.TP
\fBhjr\fR   
These set the horizontal justification to left,
center, and right, respectively.  Default = 
\fIhjc.\fR
.TP
\fBvjt\fR
.br
.ns
.TP
\fBvjc\fR
.br
.ns
.TP
\fBvjb\fR   
These set the vertical justification to top
center, and bottom, respectively.  Default = 
\fIvjb.\fR
.TP
\fBrotate \|[\fIfloat\fB\|]\fR   
This will rotate the string 
\fB\|[\fIfloat\fB\|] \fR
degrees.  The point of rotation is defined by the
\fIvj\fR
and 
\fIhj\fR
commands.  For example, to rotate 90 degrees about the center of a string, 
one would use
\fIvjc hjc rotate 90.\fR
.TP
\fBlgray \|[\fIfloat\fB\|]\fR
.br
.ns
.TP
\fBlcolor \|[\fIfloat\fB \fIfloat\fB \fIfloat\fB\|]\fR
These control the color or the grayness of the label.  It works just as
\fIgray\fR
and
\fIcolor\fR
do for curves and axes.  The default depends on the context.  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.
.PD
.RE
.LP
.TP
.B 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 
\fIdefaults\fR
keyword.  Unless a
\fIcustom\fR
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 
\fIdefaults fontsize 18\fR.

If legend editing seems cryptic, try the following example:
.PP
.nf
        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
.fi
.PP
The legend of this graph should be centered over the top of the graph,
and all legend entries should be 14pt Times-Italic.
.RS
.TP
\fBon\fR
.br
.ns
.TP
\fBoff\fR
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).
.TP
\fBlinelength \|[\fIfloat\fB\|]\fR   
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
\fB\-p\fR
option.
.TP
\fBlinebreak \|[\fIfloat\fB\|]\fR   
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 
\fB\-p\fR
option.
.TP
\fBmidspace \|[\fIfloat\fB\|]\fR   
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 distance 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 
\fB\-p\fR
option.
.TP
\fBdefaults\fR
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 \fI:\fR field
is ignored.  The \fIx\fR and \fIy\fR fields define where the label
will be printed.  The \fIhj\fR and \fIvj\fR fields define the justification
of the legend about the \fIx\fR and \fIy\fR point.  Thus, if \fIx\fR is 10
and \fIy\fR is 15, and \fIhjc  vjb\fR 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 \fIrotate\fR field is also analagous to label plotting.

Defaults are as follows.  \fIRotate\fR is 0.  \fIfont\fR is ``Times-Roman''
and \fIfontsize\fR is 9.  The color is black.  Default justification is
\fIhjl\fR and \fIvjc\fR.  The default \fIx\fR and \fIy\fR values are set 
according to the \fIhj\fR and \fIvj\fR fields.  See the 
\fB\-p\fR
option.
.TP
\fBleft\fR   
.br
.ns
.TP
\fIright\fR
These will automatically produce a legend to the left or
the right of the graph.  
\fILeft\fR
is equivalent to 
\fIdefaults hjr vjc\fR
and
\fIright\fR
is equivalent to 
\fIdefaults hjl vjc\fR.
.TP
\fBtop\fR   
.br
.ns
.TP
\fBbottom\fR
These will automatically produce a legend on the top or
the bottom of the graph.  
\fITop\fR
is equivalent to 
\fIdefaults hjl vjb\fR
 and
\fIbottom\fR
is equivalent to
\fIdefaults hjl vjt\fR.
.TP
\fBx \|[\fIfloat\fB\|]\fR
.br
.ns
.TP
\fBy \|[\fIfloat\fB\|]\fR   
These are included mainly for backward compatability to earlier
versions of jgraph.  Setting 
\fIx\fR
and 
\fIy\fR
is equivalent to ``defaults x 
\fIfloat\fR
y
\fIfloat\fR
hjl vjt''
.TP
\fBcustom\fR   
This lets the user control where each individual legend
entry goes.  The values of the 
\fIdefaults\fR
fields are ignored, and instead, the values of the curve's
labels are used.  All justifications have defined results, except 
for 
\fIhjc\fR.
Similarly, rotation other than 0 is likely to produce bad effects.
.PD
.RE
.LP
.TP
.B 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.
.RS
.TP
\fBgray \|[\fIfloat\fB\|]\fR
.br
.ns
.TP
\fBcolor \|[\fIfloat\fB \fIfloat\fB \fIfloat\fB\|]\fR
These specify either the grayness of the axis or its color.  Values
for
\fIgray\fR
should be from 0 (black) to 1 (white).  Values for
\fIcolor\fR
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
\fIgray 0\fR.
These values affect every part of the axis:  the label,
the hash marks and labels, the axis line and the grid lines.
.TP
\fBgrid_gray \|[\fIfloat\fB\|]\fR
.br
.ns
.TP
\fBgrid_color \|[\fIfloat\fB \fIfloat\fB \fIfloat\fB\|]\fR
.br
.ns
.TP
\fBmgrid_gray \|[\fIfloat\fB\|]\fR
.br
.ns
.TP
\fBmgrid_color \|[\fIfloat\fB \fIfloat\fB \fIfloat\fB\|]\fR
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
\fIgrid_gray\fR
and
\fIgrid_color\fR
is the same as the axis's
\fIgray\fR
and
\fIcolor\fR.
The default
\fImgrid_gray\fR
and
\fImgrid_color\fR
is the same as 
\fIgrid_gray\fR
and
\fIgrid_color\fR.
.TP
\fBhash_at \|[\fIfloat\fB\|]\fR   
Draw a hash mark at this point.  No label is
made for this hash mark.
.TP
\fBmhash_at \|[\fIfloat\fB\|]\fR   
Draw a minor hash mark at this point.
.TP
\fBhash_label\fR   
Edit a hash label (see HASH LABEL EDITING COMMANDS).
.TP
\fBhash_labels\fR   
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 
\fIhash_labels \fR
is just like editing
normal labels (see LABEL EDITING COMMANDS), except that the 
\fI:\fR,
\fIx\fR,
and
\fIy\fR
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 
\fIhash_scale\fR
is positive or negative.
.TP
\fBhash_scale \|[\fIfloat\fB\|]\fR   
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.
.TP
\fBdraw_hash_marks_at \|[\fIfloat\fB\|]\fR   
By default, the hash marks are drawn
either above or below the axis.  This command changes where they are
drawn.  
\fIHash_scale\fR
still determines whether they are drawn above or
below this point, and their size.
.TP
\fBdraw_hash_labels_at \|[\fIfloat\fB\|]\fR   
By default, the hash labels are
drawn either above or below the hash marks (again, this is dependent
on 
\fIhash_scale\fR).
This command changes where they are drawn. 
Justification and fontsize, etc., can be changed with the
\fIhash_labels\fR
command.
.TP
\fBauto_hash_marks\fR
.br
.ns
.TP
\fBno_auto_hash_marks\fR   
This toggles whether or
not 
\fBjgraph \fR
will automatically create hash marks according to 
\fIhash\fR,
\fImhash\fR
and
\fIshash\fR
(or 
\fIlog_base\fR
and
\fImhash\fR
for logarithmic axes). 
The default is 
\fIauto_hash_marks\fR.
.TP
\fBauto_hash_labels\fR
.br
.ns
.TP
\fBno_auto_hash_labels\fR   
This toggles whether or
not 
\fBjgraph \fR
will automatically create hash labels for the
\fIauto_hash_marks\fR.
Default = 
\fIauto_hash_labels\fR.
.TP
\fBdraw_axis\fR
.br
.ns
.TP
\fBno_draw_axis\fR   
This toggles whether or not the axis
line is drawn.  Default = 
\fIdraw_axis\fR.
.TP
\fBdraw_axis_label\fR
.br
.ns
.TP
\fBno_draw_axis_label\fR   
This toggles whether or
not the axis label (as editted by the 
\fIlabel\fR
command) is drawn.
Default = 
\fIdraw_axis_label\fR.
.TP
\fBdraw_hash_marks\fR
.br
.ns
.TP
\fBno_draw_hash_marks\fR   
This toggles whether or
not the hash marks (both automatic and those created with 
\fIhash_at\fR
and 
\fImhash_at\fR)
are drawn.  Default = 
\fIdraw_hash_marks\fR.
.TP
\fBdraw_hash_labels\fR
.br
.ns
.TP
\fBno_draw_hash_labels\fR   
This toggles whether or
not the hash labels are drawn.  Default = 
\fIdraw_hash_labels\fR.
.PD
.RE
.LP
.TP
.B 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 
\fIhash_at\fR
or 
\fImhash_at\fR
for this
axis, but this can be changed by the 
\fIat\fR
command.  If there has been
no 
\fIhash_at\fR
or 
\fImhash_at\fR,
then an
\fIat\fR
command must be given, or
there will be an error.  Hash editing terminates when either one of
these commands is not given.
.RS
.TP
\fB: \|{\fIstring\fB\|}\fR   
This sets the string of the hash label (see 
\fBStrings\fR
above under THE DESCRIPTION LANGUAGE).
.TP
\fBat \|[\fIfloat\fB\|]\fR   
This sets the location of the hash label along the
current axis.
.PD
.RE
.LP
.SH FUNCTION PLOTTING AND OTHER NON-INHERENT FEATURES
Although 
\fBjgraph \fR
doesn't have any built-in functions for interpolation
or function plotting, both can be effected in 
\fBjgraph \fR
with a little outside help:
.TP
\fBFunction plotting\fR
With the 
\fIinclude\fR
and 
\fIshell\fR
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.
.TP
\fBPoint interpolation\fR
Point interpolation is essentially the same as
function plotting, and therefore is left out of 
\fBjgraph.  \fR
The UNIX spline(1) routine is a simple way to get interpolation
between points.  See bailey.jgr described below.
Maybe in a future release.
.SH HINTS AND EXAMPLE GRAPHS
\fBJgraph \fR
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 
\fIcopygraph.\fR
The following example graphs show a few examples of different features
of jgraph.  They should be in the directory /usr/doc/examples/jgraph.
.sp
- 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.
.sp
- 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
\fIcopygraph\fR
to plot an extra x and y axis at the 0 point.
.sp
- 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.
.sp
- sin2.jgr is a different sin wave with a logarithmic x axis.
.sp
- sin3.jgr shows how a bizarre effect can be gotten by sorting the
points in a different manner.
.sp
- bailey.jgr shows how to use the UNIX spline(1) routine to get
interpolation between points.
.sp
- gpaper.jgr shows how you can get jgraph to easily produce graph paper.
.sp
- g9n10.jgr contains two graphs with complicated legends.  It
contains a description of how the legend was created.
.sp
- ex1.jgr and ex2.jgr are two examples which were figures 1 and
two in an extended abstract for a paper about jgraph.
.sp
- 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 
\fIhash_label\fR
and
\fIhash_labels\fR
commands, as well as displaying how jgraph lets you extract data from
output files with awk.
.sp
- nr.jgr is an example of a rather complicated bar graph with 
stripe-filled bars.  It was created by Norman Ramsey.
.sp
- hypercube.jgr shows an interesting use of jgraph
for picture-drawing.
.sp
- ad.jgr is an example which shows how one can include jgraph 
output as jgraph input.  The file uses the \fIeps\fR token to 
include cube.jgr, a jgraph drawing of an Intel hypercube, and disk.jgr,
a jgraph drawing of a disk, in a picture.
.sp
- 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.
.sp
- 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.
.sp
To view these graphs, use jgraph -P, and view the resulting output
file with
\fIgs\fR,
or a similar postscript viewer.
To make a hard copy of these graphs, pipe the output of jgraph 
-P directly to 
\fIlpr\fR.

.SH 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
\fIxfig\fR,
\fIfigtool\fR,
or
\fIidraw\fR.
The first is that with jgraph, you know exactly where strings, lines,
boxes, etc, will end up, because you plot them explicitly.  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
(plank@cs.utk.edu).

.SH SUPPORT FOR OTHER FONT ENCODINGS
If you want to use non-english characters to set labels or titles,
set enviroment variable JGRAPH_ENCODING with the font encoding that
you need. This value will be passed directly to the postscript.

Ex. to use ISO-8859-1 characters, try:
.nf

   export JGRAPH_ENCODING=ISOLatin1Encoding

.fi
Note: that only works with default fonts. if you use 'font' in stdin
to specify another font, it won't work.

You also have the possibility to expand the bounding box if jgraph
cuts some acute, tilde or special chars near the border; try:
.nf

   export JGRAPH_BORDER=5

.fi
This support is currently 'testing' code. Send bugs about it
to pzn@debian.org

.SH INTEGRATION WITH LATEX
.PP
.nf
1. At the top, say
   \\usepackage{graphics}

2. The floating object is done using:

   \\begin{figure}
   \\begin{center}
   \\includegraphics{a.eps}
   \\end{center}
   \\end{figure}
   
3. Now go through dvips as usual and the .ps file will work.
.fi
.PP
.SH INTEGRATION WITH PDFLATEX

If you are using pdflatex, it requires .pdf files and not .eps
files. In that case, you have to run epstopdf on the .eps file to get
a .pdf file. After that,
.br
   \\includegraphics{a.pdf}
.br
does the trick.
.SH SCALING THE INCLUDED GRAPHICS OBJECT
Sometimes you need to change the size of the included object at LaTeX
time. In that case, you need
.br
   \\usepackage{graphicx}
.br
instead of graphics, and then say something like

    \\includegraphics[width=7cm]{a.eps}
 or
    \\includegraphics[height=7cm]{a.eps}

you can also omit the .eps/.pdf suffix:
    \\includegraphics[height=7cm]{a}

a.eps and a.pdf can both exist, and includegraphics will automatically
choose the correct one for postscript or pdf output, depending if you
are using latex of pdflatex.

.SH AUTOMATION USING MAKE
You can automate the mapping from .jgr -> .eps or .jgr -> .pdf
in your Makefile using these rules:
.nf

--------- cut here ---------
%.eps : %.jgr
        jgraph $< > $@
%.pdf : %.jgr
        jgraph $< | epstopdf --filter > $@
--------- cut here ---------
.fi

jgraph can also return the exit status correctly, so it is also a good
idea to use it in your scripts to prevent bad .eps files if the .jgr
source is bad. The following Makefile can handle its exit status.
.nf

--------- cut here ---------
%.eps : %.jgr
        jgraph $< > $@; \\
        if [ "$$?" != "0" ]; then \\
          rm -f $@; \\
          exit 1; \\
        fi
%.pdf : %.jgr
        TMP=`tempfile`; jgraph $< > $${TMP}; \\
        if [ "$$?" == "0" ]; then \\
          cat $${TMP} | epstopdf --filter > $@; \\
          rm -f $${TMP}; \\
        else \\
          rm -f $${TMP} $@; \\
          exit 1; \\
        fi;
--------- cut here ---------
.fi

.SH 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.
.sp
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.  
.sp
There may well be loads of other bugs.  Send to plank@cs.utk.edu.
.sp

This is $Revision: 8.3 $.