source: trunk/Jgraph/jgraph.1 @ 419

Last change on this file since 419 was 419, checked in by Nicholas Riley, 12 years ago

Jgraph: Debian changes by pzn@…

File size: 48.6 KB
Line 
1.\" SCCSID: @(#)jgraph.1        1.1     10/23/89
2.\" SCCSID: @(#)jgraph.1        1.1     10/23/89
3.TH jgraph 1
4.SH NAME
5jgraph \- filter for graph plotting to postscript
6.SH SYNTAX
7.B jgraph
8[\-\fIp\fR\|]
9[\-\fIP\fR\|]
10[\-\fIL\fR\|]
11[\-\fIcomments\fR\|]
12[\fIfilename\fR ...\|]
13.SH DESCRIPTION
14\fBJgraph\fR
15takes the description of a graph or graphs
16and produces a postscript file on the standard output. 
17\fBJgraph\fR
18is ideal for plotting any mixture of scatter point graphs, line
19graphs, and/or bar graphs, and embedding the output into LaTeX, or
20any other text processing system which can read postscript.
21.sp
22\fBJgraph\fR reads its input from the specified files.  If no
23files are specified, then it reads from standard input.
24.sp
25The graph description language is simple enough to get nice looking
26graphs with a minimum of effort, yet powerful enough to give the user
27the flexibility to tailor the appearance of the graph to his or her
28individual preferences.  This includes plotting multiple graphs and
29laying them out separately on the page (or pages).
30.sp
31As an example, if the user wanted to simply plot the points (2,3),
32(4,5), (1,6), the following would be enough of a specification file:
33.PP
34.nf
35        newgraph
36        newcurve pts 2 3 4 5 1 6
37.fi
38.PP
39Now, if the user wanted to spruce the graph up by adding labels to
40the axes, connecting the points, and titling the graph, then the
41input could change to:
42.PP
43.nf
44        newgraph
45        newcurve pts 2 3 4 5 1 6 linetype solid
46        xaxis label : X axis
47        yaxis label : Y axis
48        title : This is an example graph
49.fi
50.PP
51If the user instead wanted this to be a bar graph with different
52endpoints on the axes, he/she could simply change the input to:
53.PP
54.nf
55        newgraph
56        xaxis min 0 max 5 label : X axis
57        yaxis min 0 max 6 label : Y axis
58        newcurve pts 2 3 4 5 1 6 marktype xbar
59        title : This is an example bar graph
60.fi
61.PP
62There are many more features of the description language, which are
63described below in the next section.  Features which are not embedded
64within the description language are: line and function interpolation,
65function plotting, and pie graphs.  The latter is impossible to do
66with the aid of
67\fBjgraph\fR,
68however, the others can be effected with
69\fBjgraph \fR
70mixed with awk or c.  See
71FUNCTION PLOTTING AND OTHER NON-INHERENT FEATURES
72below.
73.sp
74Also below is a section
75HINTS AND EXAMPLE GRAPHS, which may give good
76ideas on how to use
77\fBjgraph \fR
78more effectively.
79.SH OPTIONS
80.TP
81.B \-P
82The
83\fB\-P\fR
84option produces postscript which can be piped directly to
85\fBlpr,\fR 
86which can be displayed in an Xwindows environment with
87\fBgs\fR
88(ghostscript).
89Without this option, the output should be embedded within
90\fBLaTeX\fR
91or a similar text processing system.
92.TP
93.B \-L
94The
95\fB\-L\fR
96option produces a landscape plot.
97.TP
98.B \-p
99The
100\fB\-p\fR
101option re-prints the input on the standard output, only
102with all the defaults made explicit.  This is useful for letting the
103user do his/her own special formatting, as it shows the explicit
104values that the defaults assume, so that they can be manipulated.
105.TP
106.B \-comments
107This option makes jgraph put comments into the output postscript.  These
108make it easier for the user to wade through the final postscript if
109necessary.
110.SH THE DESCRIPTION LANGUAGE
111The description language is essentially keywords followed by
112attributes.  All keywords and attributes except for string attributes
113are tokens -- non-white-space characters surrounded by white-space.
114Special tokens are
115``(*'', ``*)'', ``include'', ``:'', and ``shell'', which denote
116comments, include-file statements, string identifiers, and shell-include
117statements:
118.TP
119.B Comments
120Comments are surrounded by the tokens ``(*'' ``*)'' as in
121Modula-2 (except that here, the tokens must be surrounded by white-
122space).  Comments may be nested.  If the comment runs to the end of a
123file, the last ``*)'' may be omitted.
124.TP
125.B Include\-file statements
126The token following an ``include'' token is
127expected to be a file name.  The result of the statement is to
128include the contents of the file at that point.  Include-file
129statments can be nested within included files, and within shell
130includes.
131.TP
132.B Strings
133In places where strings are required (as in graph and
134curve labels), they are denoted by the token ``:''.  The second
135character after the ``:'' starts the string, and the next newline
136character terminates it. 
137Thus, the string ``Graph #1'' can be denoted as:
138.nf
139
140        : Graph #1<newline>
141
142or
143
144        :<newline>
145        Graph #1<newline>
146
147.fi
148One can get multiline strings by making
149a backslash the last character before the newline on all but the
150last line.  Notice that in strings white-space is not ignored. 
151This way of denoting strings allows the user to embed leading and
152trailing spaces, as well as the null string.  For example, the
153null string ``'' is represented by:
154.nf
155
156        : <newline>
157
158.fi
159Once a string has been started, it may contain any character.
160Specifically, it may contain the sequence ``(*'', ``shell'',
161or ``include'' without starting a comment or including a file.
162Each line of a string must contain less than 1000 characters.  Otherwise
163string sizes are limited only by the size of memory.
164.TP
165.B Shell\-include statements
166Shell include statements are of the form ``shell'', ``:'', and then
167a string.  The result of the statement is that the string is executed
168(using popen, which passes the string to sh), and the standard
169output is included at that point.  Shell-includes can be freely
170nested within include-files and other shell-includes.  Shell
171commands may be more than one line, but must not exceed 1000 characters.
172The shell statement is not (yet) available on VMS.
173.TP
174.B Notation
175In the descriptions below:
176.RS
177.TP
178\fBtk \|{\fIinteger\fB\|}\fR
179means that token
180\fBtk \fR
181must be followed by an integer. 
182.TP
183\fBtk \|[\fIinteger\fB\|]\fR
184means that
185\fBtk\fR
186may be followed by an integer, but doesn't have to.  In most cases, if
187\fBtk\fR
188is not followed by an integer, then the command denoted by
189\fBtk \fR
190is ignored. 
191.TP
192\fBtk \|[\|{\fIinteger\fB\|} \|{\fIinteger\fB\|}\|]*
193means that
194\fBtk\fR
195must be
196followed by an even number of integers. 
197.PD
198.LP
199Supported types other than
200integer are:
201\fB\|{\fIfloat\fB\|} \fR
202for floating point entries,
203\fB\|{\fItoken\fB\|} \fR
204for any
205token, and
206\fB\|{\fIstring\fB\|} \fR
207for a string as defined above.
208.RE
209.TP
210.B TOP-LEVEL DESCRIPTION COMMANDS
211.RS
212.TP
213.B newgraph
214This starts editing a new graph (see GRAPH EDITING
215COMMANDS).  Note that multiple graphs may be drawn on the same page.
216.TP
217\fBgraph \|{\fIinteger\fB\|}\fR
218This edits the graph denoted by
219\fB\|{\fIinteger\fB\|}.  \fR
220If the graph doesn't exist, then this command creates it and starts
221editing it. 
222\fBNewgraph\fR
223is simply an abbreviation for
224\fB\fIgraph\fB \fIn\fB\fR
225where n=0 if this is the first graph, otherwise n=m+1, where m is the
226largest number of any graph so far.
227.TP
228\fBcopygraph \|[\fIinteger\fB\|]\fR
229This creates a new graph, and copies all the attributes from the
230graph
231\fB\|[\fIinteger\fB\|]'s\fR
232x and y axes, as well as its
233\fB\fIx_translate\fB\fR
234and
235\fB\fIy_translate\fB\fR
236values, the clipping, the legend defaults, and
237the title defaults.   If the
238\fB\|[\fIinteger\fB\|]\fR
239is omitted, then it copies its values from the ``previous''
240graph, which is
241defined to be the graph with the largest number
242less than the currrent graph's number.  If the current
243graph has the smallest number, then it will take the last graph from
244the previous page of graphs.  If there is no previous page, then an
245error will be flagged.
246(copygraph does not copy the values of the
247\fB\fIhash_at\fR, \fImhash_at\fR,\fR
248and
249\fB\fI\fIhash_label\fB\fR
250attributes).
251.TP
252.B newpage
253This command is for plotting graphs on multiple pages.  After a
254\fBnewpage,\fR
255the graphs that the user enters will be plotted on a new page.
256New graphs and strings will be numbered starting with 0. 
257Essentially,
258\fB\fInewpage\fB\fR
259is the same as appending together the output of separate calls of
260jgraph on the text before the
261\fB\fInewpage\fR,\fR
262and on the text after the
263\fB\fInewpage.\fR
264\fB\fINewpage\fB\fR
265will most likely produce bizarre results if the
266\fB\-P\fR
267option is not specified.
268.TP
269\fBX \|[\fIfloat\fB\|]\fR
270.br
271.ns
272.TP
273\fBY \|[\fIfloat\fB\|]\fR
274Postscript files to be embedded in LaTeX (and some other programs)
275contain a ``bounding box''
276which defines the area which LaTeX will allocate for the postscript.
277Other programs use this bounding box as well, sometimes using it
278to define where to clip the postscript image.
279\fBJgraph \fR
280uses the axis lines and labels, and the title to generate its
281bounding box.  Most of the time that's good enough to work in
282LaTeX.  The
283\fB\fIY\fB\fR
284and
285\fB\fIX\fB\fR
286commands say to make the height and width of the bounding box at least
287\fB\fIY\fB\fR
288and
289\fB\fIX\fB\fR
290inches, respectively, but to maintain the current centering of the
291graph.  If you still need further control over the
292bounding box (e.g. to change the centering), try the
293\fB\fIbbox\fB\fR
294command.  If there's more than one page in the jgraph file,
295\fB\fIY\fR,\fR
296\fB\fIX\fB\fR
297and
298\fB\fIbbox\fB\fR
299values can be given for each graph.
300.TP
301\fBbbox \fIfloat\fB \fIfloat\fB \fIfloat\fB \fIfloat\fB\fR
302If the
303\fB\fIY\fB\fR
304and
305\fB\fIX\fB\fR
306commands aren't enough to help you define a good bounding box, this
307command lets you explicitly enter one which will go directly into the
308jgraph output.  Its units are the
309final postscript units.  It's probably best to use the
310\fB\-p\fR
311option
312to see what the bounding box is that jgraph produces, and then
313alter that accordingly with
314\fB\fIbbox.\fR
315The main use for this is to change the automatic centering that jgraph
316performs:  Usually the center of the bounding box that jgraph computes
317is put at the center of the page.  Changing the bbox changes this
318center.
319.TP
320\fBpreamble : \|{\fIstring\fB\|}\fR   
321.br
322.ns
323.TP
324\fBpreamble {\fItoken\fB\|}\fR   
325.br
326.ns
327.TP
328\fBepilogue : \|{\fIstring\fB\|}\fR   
329.br
330.ns
331.TP
332\fBepilogue {\fItoken\fB\|}\fR   
333These two commands allow the user to include strings or
334files (the token specifies the filename) which will be copied directly
335into jgraph's output.
336The \fIpreamble\fR is included at the beginning of the output
337(after some initial postscript to set things up for jgraph),
338and the \fIepilogue\fR is included at the end.  A good use for
339the \fIpreamble\fR is to set up a postscript dictionary if you're
340using postscript marks.
341.PD
342.RE
343.LP
344.TP
345.B GRAPH EDITING COMMANDS
346These commands act on the current graph.
347Graph editing is terminated when one of the top-level description
348commands is given.
349.RS
350.TP
351\fBxaxis\fR
352.br
353.ns
354.TP
355\fByaxis\fR
356Edit the x or y axis (see AXIS EDITING COMMANDS)
357.TP
358\fBnewcurve\fR 
359This starts editing a new curve of the graph (see CURVE
360EDITING COMMANDS).
361.TP
362\fBcurve \|{\fIinteger\fB\|}\fR   
363This edits the curve denoted by
364\fB\|{\fIinteger\fB\|}.  \fR
365If the curve doesn't exist, then this command creates it and starts
366editing it. 
367\fINewcurve\fR
368and
369\fIcurve\fR
370interact as
371\fInewgraph\fR
372and
373\fIgraph\fR
374do.
375.TP
376\fBnewline\fR 
377This is an abbreviation for:
378.PP
379.nf
380          newcurve marktype none linetype solid
381.fi
382.PP
383.TP
384\fBcopycurve \|[\fIinteger\fB\|]\fR
385This starts editing a new curve of the graph, and copies all its
386values except for the points from curve
387\fB\|[\fIinteger.\fB\|]\fR
388If the
389\fB\|[\fIinteger\fB\|]\fR
390is omitted, then it copies its values from the
391last curve in this graph.  If this graph currently has
392no curves, then it searches backwards from the previous graph.
393.TP
394\fBtitle\fR   
395This edits the title of the graph (see LABEL EDITING
396COMMANDS).  The title is given a default location centered beneath
397the graph, and a default font size of 12, however, as with all
398labels, this can be changed.
399.TP
400\fBlegend\fR   
401The edits the legend of the graph (see LEGEND EDITING
402COMMANDS).  As a default, the graph will contain a legend
403if any of its curves have labels.
404.TP
405\fBnewstring\fR   
406This edits a new text string (see LABEL EDITING
407COMMANDS).  This is useful as it allows the user to plot text on the
408graph as well as curves.
409.TP
410\fBstring \|{\fIinteger\fB\|}\fR   
411.br
412.ns
413.TP
414\fBcopystring \|[\fIinteger\fB\|]\fR
415\fIString\fR
416and
417\fIcopystring\fR
418are to
419\fInewstring\fR
420as
421\fIcurve\fR
422and
423\fIcopycurve\fR
424are to
425\fInewcurve\fR.
426.TP
427\fBborder\fR
428.br
429.ns
430.TP
431\fBnoborder\fR
432\fIBorder\fR
433draws a square border around the area defined by the axes.
434\fINoborder\fR
435specifies no border.
436\fINoborder\fR
437is the default. 
438.TP
439\fBclip\fR
440.br
441.ns
442.TP
443\fBnoclip\fR
444\fIClip\fR
445specifies that all curves in the graph will be clipped -- that is,
446no points outside of the of axes will be plotted.  Clipping can also be
447specified on a per-curve basis.  The default is
448\fInoclip\fR.
449.TP
450\fBinherit_axes\fR   
451This is an old command which is kept for backward compatibility.
452\fICopycurve\fR.
453is equivalent to:
454.PP
455.nf
456          newgraph inherit_axes
457.fi
458.PP
459.TP
460\fBx_translate \|[\fIfloat\fB\|]\fR   
461.br
462.ns
463.TP
464\fBy_translate \|[\fIfloat\fB\|]\fR   
465By default, the bottom left-hand corner of each graph is at point
466(0,0) (final postscript units).
467\fIX_translate\fR
468and
469\fIY_translate\fR
470translate the bottom left-hand corner of the graph
471\fB\|[\fIfloat\fB\|] \fR
472inches.  The main use of this is to draw more than one graph on
473a page.  Note that jgraph considers all the graphs drawn on the
474page when it computes its bounding box for centering.  Thus, if
475only one graph is drawn, it will always be centered on the page,
476regardless of its
477\fIX_translate\fR
478and
479\fIY_translate\fR
480values.  These values are used for relative placement of the graphs.
481   To change the centering of the graphs, use
482\fIbbox.\fR
483.TP
484\fBX \|[\fIfloat\fB\|]\fR
485.br
486.ns
487.TP
488\fBY \|[\fIfloat\fB\|]\fR   
489These are the same as
490\fIX\fR
491and
492\fIY\fR
493in the
494Top-level commands, except that they let the user continue editing
495the current graph.
496.PD
497.RE
498.LP
499.TP
500.B SIMPLE AXIS EDITING COMMANDS
501These commands act on the current
502axis as chosen by
503\fIxaxis\fR
504or
505\fIyaxis\fR
506(see GRAPH EDITING COMMANDS).
507Axis editing terminates when a graph or top-level command is given.
508There are more advanced axis editing commands given below which have
509to do with moving the hash marks, adding new hash marks and labels,
510etc.  See ADVANCED AXIS EDITING COMMANDS.
511.RS
512.TP
513\fBlinear\fR
514.br
515.ns
516.TP
517.B log
518Set the axis to be linear or logarithmic. The
519default is linear.  If the axis is set to be logarithmic, then values
520<= 0.0 will be disallowed, as they are at negative infinity on the
521axis. If you are using logarithmic axes and the labels shows 0 0 1 10
522instead of 0.01 0.1 1 10, then you should read "hash_format" in this
523section. Hint: xaxis log hash_format g
524.TP
525\fBmin \|[\fIfloat\fB\|]\fR
526.br
527.ns
528.TP
529\fBmax \|[\fIfloat\fB\|]\fR   
530Set the minimum and maximum values of
531this axis.  Defaults depend on the points given.  They can be seen by
532using the
533\fB\-p \fR
534option.  Unless stated, all units (for example point
535plotting, string plotting, etc.) will be in terms of the
536\fImin\fR
537and
538\fImax\fR
539values of the x and y axes.
540.TP
541\fBsize \|[\fIfloat\fB\|]\fR   
542Set the size of this axis in inches.
543.TP
544\fBlog_base \|[\fIfloat\fB\|]\fR   
545Set the base of the logarithmic axis. Default =
54610.  This is the value which determines which hash
547marks and hash labels are automatically produced.
548.TP
549\fBhash \|[\fIfloat\fB\|]\fR   
550Hash marks will be
551\fB\|[\fIfloat\fB\|] \fR
552units apart.  Default = -1. 
553If this value equals 0, then there will be no hash marks.  If
554this value is less than 0, then the hash marks will be automatically
555set by
556\fBjgraph \fR
557(see
558\fB\-p \fR
559for the value).  By default, each hash mark
560will be labeled with its value. 
561\fIHash\fR
562and
563\fIshash\fR
564are ignored if
565the axes are logarithmic.
566.TP
567\fBshash \|[\fIfloat\fB\|]\fR   
568Make sure there is a hash mark at the point
569\fB\|[\fIfloat\fB\|] \fR
570along the axis.  The default is set by
571\fBjgraph\fR
572if
573\fBhash\fR
574= -1.
575If
576\fIhash\fR
577is set by the user,
578\fIshash\fR
579is defaulted to the
580\fImin\fR
581value of the axis.
582.TP
583\fBmhash \|[\fIinteger\fB\|]\fR   
584Put
585\fB\|[\fIinteger\fB\|] \fR
586minor hash marks between the above
587hash marks.  Default = -1.  If this value equals 0, then there will
588be no minor hash marks.  If this value is negative, then the value
589will be chosen by
590\fBjgraph \fR
591(see
592\fB\-p\fR
593for the value).
594.TP
595\fBprecision \|[\fIinteger\fB\|]\fR   
596.TP
597\fBhash_format \fItoken\fB\fR   
598These control how jgraph formats the automatic hash labels.
599The user shouldn't have to worry about these values, except in
600extreme cases.  Jgraph uses \fBprintf\fR to format the labels.
601If \fBhash_format\fR is ``f'' (the default), then the
602value of a hash label is printed with
603.PP
604.nf
605        printf("%.*f", precision, value).
606.fi
607.PP
608Other valid \fBhash_format\fR values are ``G'', ``g'', ``E'', and ``e''.
609``G'' is a good generic format which converts to scientific notation
610if the value becomes too big or too small.
611If the precision is negative, then jgraph chooses a default:  For
612``g'' and ``G'', the default is 6.  For ``e'' and ``E'', the default
613is 0, and for ``f'', jgraph tries to determine a reasonable default.
614Please read the man page of \fBprinf(1)\fR for a complete description
615of how it formats floating point numbers.
616.TP
617\fBlabel\fR   
618Edit the label of this axis (see LABEL EDITING COMMANDS).
619By default, the label is in font ``Times-Bold'', and has a font size of
62010.  If the user doesn't change any of the plotting attributes of the
621label,
622\fBjgraph \fR
623chooses an appropriate place for the axis label.
624.TP
625\fBdraw_at \|[\fIfloat\fB\|]\fR   
626Draw the axis line at this point on the other axis.
627The default is usually the other axis's
628\fImin\fR,
629however if
630\fIhash_scale \fR
631is positive (see
632\fIhash_scale \fR
633under ADVANCED AXIS EDITING), it will be
634the other axis's
635\fImax\fR.
636.TP
637\fBnodraw\fR   
638Do not draw the axis, the hash marks or any labels.  This
639is useful for plotting points with no axes, and for overlaying graphs
640on top of one another with no clashes.  This is equivalent to
641\fIno_draw_axis\fR,
642\fIno_draw_axis_label\fR,
643\fIno_draw_hash_marks\fR,
644and
645\fIno_draw_hash_labels\fR.
646.TP
647\fBdraw\fR   
648Cancels the effect of
649\fInodraw\fR.
650Default =
651\fIdraw\fR
652This is
653equivalent to
654\fIdraw_axis\fR,
655\fIdraw_axis_label\fR,
656\fIdraw_hash_marks\fR,
657and
658\fIdraw_hash_labels\fR.
659.TP
660\fBgrid_lines\fR
661.br
662.ns
663.TP
664\fBno_grid_lines\fR
665\fIGrid_lines\fR
666specifies to plot a grid line at each major hash
667mark on this axis.  The default is
668\fIno_grid_lines.\fR
669.TP
670\fBmgrid_lines\fR
671.br
672.ns
673.TP
674\fBno_mgrid_lines\fR
675\fIMgrid_lines\fR
676specifies to plot a grid line at each minor hash
677mark on this axis.  The default is
678\fIno_mgrid_lines\fR.
679.PD
680.RE
681.LP
682.TP
683.B CURVE EDITING COMMANDS
684These commands act on the current curve as
685chosen by
686\fInewcurve\fR
687or
688\fIcurve\fR
689(see GRAPH EDITING COMMANDS).  Curve
690editing terminates when a graph or top-level command is given.
691.RS
692.TP
693\fBpts \|[\|{\fIfloat\fB\|} \|{\fIfloat\fB\|}\|]*\fR   
694This sets the points to plot in this
695curve.  The first
696\fIfloat\fR
697is the x value, and the second
698\fIfloat\fR
699is the y
700value of the point.  Points are plotted in the order specified.
701This command stops reading points when a non-float is given.
702The user can specify this command multiple times within a curve --
703each time, simply more points are added to the curve.
704.TP
705\fBx_epts \|[\|{\fIfloat\fB\|} \|{\fIfloat\fB\|} \|{\fIfloat\fB\|} \|{\fIfloat\fB\|}\|]*\fR   
706.br
707.ns
708.TP
709\fBy_epts \|[\|{\fIfloat\fB\|} \|{\fIfloat\fB\|} \|{\fIfloat\fB\|} \|{\fIfloat\fB\|}\|]*\fR   
710This allows the user to specify points and ``confidence values'' (otherwise
711known as ``error bars'').  The first two
712\fIfloats\fR
713specify the x and y values of
714the point, as above.  If
715\fBx_epts\fR
716is specified,  then the second two
717\fIfloats\fR
718specify range or confidence values
719for the x value of the point. 
720Error bars will be printed to each of these x values (using the
721original point's y value)
722from the original point.  Similarly,
723\fIy_epts\fR
724specifies range or confidence values for the y value of the point.
725\fIpts\fR
726\fIx_epts\fR
727and
728\fIy_epts\fR
729can all be intermixed.
730.TP
731\fBmarktype\fR   
732This sets the kind of mark that is plotted for this curve.  Valid
733marks are: \fIcircle\fR, \fIbox\fR, \fIdiamond\fR, \fItriangle\fR,
734\fIx\fR, \fIcross\fR, \fIellipse\fR, \fIxbar\fR, \fIybar\fR,
735\fItext\fR, \fIpostscript\fR, \fIeps\fR, \fInone\fR, and variants of
736\fIgeneral\fR.  Most of these are self-explanatory, except for the
737last few:
738  \fIXbar\fR makes the curve into a bar graph with the bars going
739to the x axis.  \fIYbar\fR has the bars going to the y axis.
740  \fIText\fR lets the user plot text instead of a mark.  The text is
741editted as a label (see LABEL EDITING COMMANDS) immediately following
742the \fItext\fR command.  The x and y fields of the label have special
743meanings here:  They define where the label is to be printed in relation
744to the curve points.  For example, if they are both 0, the label will
745be printed directly on the curve points.  If x is 1.0 and y is -1.0, then
746the label will be printed one unit to the right and one unit below the
747curve points (units are units of the x and y axes).
748Default label values are 0 for x and y, and center justification.
749  \fIPostscript\fR: See the \fIpostscript\fR token below.
750  \fIEps\fR: See the \fIeps\fR token below.
751  \fINone\fR means that no mark will be
752plotted (this is useful for drawing lines). 
753  There are four types of \fIgeneral\fR marks, which work using the
754\fIgmarks\fR command described below.  The four marktypes are
755\fIgeneral\fR, \fIgeneral_nf\fR, \fIgeneral_bez\fR, and
756\fIgeneral_bez_nf\fR.
757  By default, a new mark is chosen for each curve.
758.TP
759\fBmarksize \|[\fIfloat\fB\|] \|[\fIfloat\fB\|]\fR   
760This sets the size of the mark.  The
761first
762\fB\|[\fIfloat\fB\|] \fR
763is the width of the mark, and the second is the height.
764Units are those of the x and y axes respectively, unless that axis is
765logarithmic, in which case the units are inches.  Negative marksizes
766are allowed (e.g.  a negative height will flip a \fItriangle\fR mark).
767The default mark size can be determined using the
768\fB\-p\fR
769option of
770\fBjgraph\fR
771.TP
772\fBmrotate \|[\fIfloat\fB\|]\fR
773This allows the user to rotate the mark
774\fB\|[\fIfloat\fB\|] \fR
775degrees.  Default is zero.
776.TP
777\fBgray \|[\fIfloat\fB\|]\fR
778.br
779.ns
780.TP
781\fBcolor \|[\fIfloat\fB \fIfloat\fB \fIfloat\fB\|]\fR   
782These specify either the grayness of the curve or its color.  Values
783for
784\fIgray\fR
785should be from 0 (black) to 1 (white).  Values for
786\fIcolor\fR
787should also be from 0 to 1.  They are RGB values, and thus define the
788amount of red, green and blue in the curve respectively.  Specifying
789color nullifies the gray value, and vice versa.  The default is
790\fIgray 0\fR
791.TP
792\fBfill \|[\fIfloat\fB\|]\fR   
793.br
794.ns
795.TP
796\fBcfill \|[\fIfloat\fB\| \|\fIfloat\fB\| \|\fIfloat\fB\|]\fR   
797This sets the filling of marks which define an area
798to fill (e.g.  \fIbox\fR, \fIcircle\fR, \fIxbar\fR). 
799\fIfill\fR
800defines a gray value, and
801\fIcfill\fR
802defines a color value (see
803\fIgray\fR
804and
805\fIcolor\fR
806above for a description of the units).
807The default is
808\fIfill 0\fR
809(black).
810.TP
811\fBpattern \fItoken\fB \|[\fIfloat\fB\|]\fR   
812This defines the how the mark is to be filled.  \fIToken\fR
813may be \fIsolid\fR (the default), \fIstripe\fR, or \fIestripe\fR.  If
814\fIsolid\fR, then the \fIfloat\fR is ignored, and the mark is
815completely filled in with either the gray value defined by
816\fIfill\fR or the color value defined by \fIcfill\fR.
817If \fIstripe\fR, then the mark will be filled with stripes of
818either the gray value defined by \fIfill\fR or the color defined
819by \fIcfill\fR.  The stripes will be rotated by \fIfloat\fR
820degrees.  \fIEstripe\fR differs from \fIstripe\fR only in that
821\fIstripe\fR draws
822stripes on a white background, while \fIestripe\fR simply draws the
823stripes on an empty background.
824.TP
825\fBpoly\fR
826.br
827.ns
828.TP
829\fBnopoly\fR
830.br
831.ns
832.TP
833\fBpfill \|[\fIfloat\fB\|]\fR   
834.br
835.ns
836.TP
837\fBpcfill \|[\fIfloat\fB\| \|\fIfloat\fB\| \|\fIfloat\fB\|]\fR   
838.br
839.ns
840.TP
841\fBppattern \fItoken\fB \|[\fIfloat\fB\|]\fR   
842\fIPoly\fR allows the user to make jgraph treat the curve as a
843closed polygon (or in the case of a bezier, a closed bezier curve).
844\fIpfill\fR, \fIpcfill\fR and \fIppattern\fR  specify the
845filling of the polygon,
846and work like \fIfill\fR, \fIcfill\fR and \fIpattern\fR above. 
847The default is \fInopoly\fR.
848.TP
849\fBgmarks \|[\|{\fIfloat\fB\|} \|{\fIfloat\fB\|}\|]*\fR   
850\fIGmarks\fR
851is a way for the user to define custom marks.  For each mark on
852\fI(x,y)\fR,
853Each pair of
854\fB\|{\fIfloat_x\fB\|}, \|{\fIfloat_y\fB\|}, \fR
855will define a point on the mark (x +
856\fB(\fIfloat_x\fB * \fImarksize_x\fB / 2), y + (\fIfloat_y\fB * \fImarksize_y\fB / 2)).\fR
857  Thus, for example, the
858\fIbox\fR mark could be defined as
859.PP
860.nf
861        gmarks -1 -1 -1 1 1 1 1 -1
862        marktype general
863.fi
864.PP
865The marktypes \fIgeneral\fR, \fIgeneral_nf\fR, \fIgeneral_bez\fR,
866and \fIgeneral_bez_nf\fR, allow the gmarks points to define
867a closed polygon, a line, a closed bezier curve and a
868regular bezier curve respectively (the ``nf'' stands for
869``non-filled'').
870.TP
871\fBpostscript : \|{\fIstring\fB\|}\fR   
872.br
873.ns
874.TP
875\fBpostscript {\fItoken\fB\|}\fR   
876This allows the user to enter direct postscript as a mark.  It
877automatically sets the marktype to \fIpostscript\fR.  If a string is
878entered, then that string is used as the mark in the jgraph output.
879If a token is entered, then that token must stand for a filename, which
880will be copied to the output once for every mark.  The postscript will
881be set up so that when the string or file is put to the output, (0, 0) of
882the the axes is in the middle of the mark, it is rotated by
883\fImrotate\fR degrees, and scaled by
884(\fImarksize_x\fR / 2), \fImarksize_y\fR / 2).
885Thus, the \fIbox\fR mark could be defined as:
886.PP
887.nf
888        postscript : 1 setlinewidth -1 -1 moveto -1 1 lineto \\
889                  1 1 lineto 1 -1 lineto -1 -1 lineto stroke
890.fi
891.PP
892If the \fImarksize_x\fR is defined to be (0, 0), then jgraph does no
893scaling.  This is useful when the postscript has strings, and the
894user does not want the strings to be scaled.
895.TP
896\fBeps {\fItoken\fB\|}\fR   
897This allows the user to include an encapsulated postscript file
898and treat it as a mark.  It automatically sets the marktype to
899\fIeps\fR.  The file will be scaled so that the bounding
900box is \fImarksize\fR units.  Among other things, this allows the
901user to include whole jgraph files as marks.  Please see ad.jgr,
902explained in HINTS AND EXAMPLE GRAPHS below for an example of this feature.
903.TP
904\fBlarrows\fR
905.br
906.ns
907.TP
908\fBrarrows\fR
909.br
910.ns
911.TP
912\fBnolarrows\fR
913.br
914.ns
915.TP
916\fBnorarrows\fR
917\fIRarrows\fR
918specifies to draw an arrow at the end of every line
919segment in the curve. 
920\fILarrows\fR
921specifies to draw an arrow at the beginning of every line segment.
922The size of the arrows can be changed by using
923\fIasize.\fR
924The default is
925\fInolarrows\fR
926and
927\fInorarrows\fR.
928  Arrows always go exactly to the point specified, with the exception
929of when the marktype is ``circle''.  In this case, the arrow goes to
930the edge of the circle.
931.TP
932\fBlarrow\fR
933.br
934.ns
935.TP
936\fBrarrow\fR
937.br
938.ns
939.TP
940\fBnolarrow\fR
941.br
942.ns
943.TP
944\fBnorarrow\fR
945This is analgous to the above, except that with \fIlarrow\fR, the
946only arrow drawn is to the beginning of the first segment in the
947curve, and with \fIrarrow\fR, the only arrow drawn is to the end
948of the last segment.
949.TP
950\fBasize \|[\fIfloat\fB\|] \|[\fIfloat\fB\|]\fR   
951This sets the size of the arrows.  The first
952\fB\|[\fIfloat\fB\|] \fR
953controls the arrow's width.  Its units are those of the x-axis.
954The second
955\fB\|[\fIfloat\fB\|] \fR
956controls the arrow's height.  It is in the units of the y-axis.
957Use the -p option of jgraph to see the default values.
958.TP
959\fBafill \|[\fIfloat\fB\|]\fR
960.br
961.ns
962.TP
963\fBafill \|[\fIfloat\fB\|]\fR
964.br
965.ns
966.TP
967\fBapattern \fItoken\fB \|[\fIfloat\fB\|]\fR   
968These control the grayness or color of arrowheads. 
969\fIAfill\fR,
970\fIacfill\fR
971and
972\fIapattern\fR
973work in the same way as
974\fIfill\fR,
975\fIcfill\fR
976and
977\fIpattern\fR
978described above.  The default is
979\fIafill 0\fR
980(black).
981.TP
982\fBlinetype \|[\fItoken\fB\|]\fR   
983This defines the type of the line connecting the points.  Valid
984entries are \fIsolid\fR, \fIdotted\fR, \fIdashed\fR, \fIlongdash\fR,
985\fIdotdash\fR, \fIdotdotdash\fR, \fIdotdotdashdash\fR, \fIgeneral\fR, and
986\fInone\fR.  The default is \fInone\fR.  \fIGeneral\fR lets the user define
987his own linetype using the
988\fIglines\fR
989command described below.  Points are connected in the
990order in which they are inserted using the
991\fIpts\fR
992command.
993.TP
994\fBglines \|[\fIfloat\fB\|]*\fR   
995This lets the user specify the exact dashing of a line.  The format
996is as in postscript -- the first number is the length of the first
997dash, the second is the length of the space after the first dash,
998etc.  For example, \fIdotdash\fR could be defined as ``\fIglines\fR 5 3
9991 3''. 
1000.TP
1001\fBlinethickness \|[\fIfloat\fB\|]\fR   
1002This defines the line thickness (in
1003absolute postscript units) of the connecting line.  Default = 1.0.
1004.TP
1005\fBbezier\fR
1006.br
1007.ns
1008.TP
1009\fBnobezier\fR
1010.br
1011.ns
1012\fIBezier\fR
1013specifies to use the curve's points to define successive bezier curves.
1014The first point is the starting point.  The next two are control points
1015for the bezier curve and the next point is the ending point.  If there
1016is another bezier, this ending point is also the beginning point of the
1017next curve.  The next two points are again control points, and the next
1018point is the ending point.  Thus, a bezier must have a total of (3n + 1)
1019points, where n is at least 1.
1020  In bezier curves, marks and arrows only apply to every third point.
1021\fINobezier\fR is the default.
1022
1023.TP
1024\fBclip\fR
1025This specifies that this curve will be clipped -- that is,
1026no points outside of the of axes will be plotted. 
1027.TP
1028\fBnoclip\fR
1029This turns off clipping.  If clipping was specified for the
1030entire graph, then
1031\fInoclip\fR
1032has no effect.
1033\fINoclip\fR
1034is the default.
1035.TP
1036\fBlabel\fR   
1037This edits the label of this curve for the purposed of
1038drawing a legend.  (see LABEL EDITING COMMANDS and LEGEND EDITING
1039COMMANDS).  Unless the legend entry is
1040\fIcustom\fR,
1041setting any label attribute except for the text itself
1042will have no effect.
1043.PD
1044.RE
1045.LP
1046.TP
1047.B LABEL EDITING COMMANDS
1048The following commands are used for editing
1049labels.  Unless stated otherwise, the defaults are written with each
1050command.  Label editing terminates when one of these tokens is not
1051given.
1052.RS
1053.TP
1054\fB: \|{\fIstring\fB\|}\fR   
1055This sets the string of the label.  If no string is
1056set, the label will not be printed.
1057.TP
1058\fBx \|[\fIfloat\fB\|]\fR
1059.br
1060.ns
1061.TP
1062\fBy \|[\fIfloat\fB\|]\fR   
1063This sets the x or y coordinate of the
1064label.  Units are the units of the x and y axes respectively.
1065.TP
1066\fBfont \|[\fItoken\fB\|]\fR   
1067This sets the font.  Default is usually ``Times-Roman''.
1068.TP
1069\fBfontsize \|[\fIfloat\fB\|]\fR   
1070This sets the fontsize in points.  Default is usually 9.
1071.TP
1072\fBlinesep \|[\fIfloat\fB\|]\fR   
1073This sets the distance between lines in multilined labels.  Units are points.
1074The default is the fontsize.
1075.TP
1076\fBhjl\fR
1077.br
1078.ns
1079.TP
1080\fBhjc\fR
1081.br
1082.ns
1083.TP
1084\fBhjr\fR   
1085These set the horizontal justification to left,
1086center, and right, respectively.  Default =
1087\fIhjc.\fR
1088.TP
1089\fBvjt\fR
1090.br
1091.ns
1092.TP
1093\fBvjc\fR
1094.br
1095.ns
1096.TP
1097\fBvjb\fR   
1098These set the vertical justification to top
1099center, and bottom, respectively.  Default =
1100\fIvjb.\fR
1101.TP
1102\fBrotate \|[\fIfloat\fB\|]\fR   
1103This will rotate the string
1104\fB\|[\fIfloat\fB\|] \fR
1105degrees.  The point of rotation is defined by the
1106\fIvj\fR
1107and
1108\fIhj\fR
1109commands.  For example, to rotate 90 degrees about the center of a string,
1110one would use
1111\fIvjc hjc rotate 90.\fR
1112.TP
1113\fBlgray \|[\fIfloat\fB\|]\fR
1114.br
1115.ns
1116.TP
1117\fBlcolor \|[\fIfloat\fB \fIfloat\fB \fIfloat\fB\|]\fR
1118These control the color or the grayness of the label.  It works just as
1119\fIgray\fR
1120and
1121\fIcolor\fR
1122do for curves and axes.  The default depends on the context.  For example,
1123for strings and the title, the default is black.  For axis labels and hash
1124labels, the default is the color of the axis.  For text as marks, the
1125default is the curve color.
1126.PD
1127.RE
1128.LP
1129.TP
1130.B LEGEND EDITING COMMANDS
1131These commands allow the user to alter the
1132appearance of the legend.  Legends are printed out for each curve
1133having a non-null label.  The legend entries are printed out
1134in the order of ascending curve numbers.
1135Legend editing terminates when a graph command or top level command
1136is issued.
1137
1138In earlier versions of jgraph (before version 8.0), the
1139characteristics of each legend entry were set in the label portion
1140of the entry's curve.  Thus, for example, if you wanted each entry's
1141fontsize to be 18, you had to set it in each entry's curve.  Now,
1142default legend entry characteristics are set using the
1143\fIdefaults\fR
1144keyword.  Unless a
1145\fIcustom\fR
1146legend is specified, these default values override any values set in
1147the entry's curve.  Thus, to get all entries to have a fontsize of
114818, it must be set using
1149\fIdefaults fontsize 18\fR.
1150
1151If legend editing seems cryptic, try the following example:
1152.PP
1153.nf
1154        newgraph
1155        newcurve marktype box linetype solid label : Solid box
1156          pts 0 0 1 1 2 1 3 1
1157        newcurve marktype circle linetype dotted label : Dotted circle
1158          pts 0 1 1 2 2 2 3 2
1159        newcurve marktype x linetype dashed label : Dashed x
1160          pts 0 2 1 3 2 3 3 3
1161        legend defaults
1162          font Times-Italic fontsize 14 x 1.5 y 3.5 hjc vjb
1163.fi
1164.PP
1165The legend of this graph should be centered over the top of the graph,
1166and all legend entries should be 14pt Times-Italic.
1167.RS
1168.TP
1169\fBon\fR
1170.br
1171.ns
1172.TP
1173\fBoff\fR
1174These turn printing of the legend on and off.  The default is on
1175(but, of course, if there are no curve labels defined, there will
1176be no legend).
1177.TP
1178\fBlinelength \|[\fIfloat\fB\|]\fR   
1179This sets the length of the line printed in
1180front of legend entries corresponding to curves which have lines.
1181Units are those of the x axis, unless the x axis is logarithmic, in
1182which case the units are inches.  The default may be gotten using the
1183\fB\-p\fR
1184option.
1185.TP
1186\fBlinebreak \|[\fIfloat\fB\|]\fR   
1187This sets the vertical distance between
1188individual legend entries.  Units are those of the y axis, unless the
1189y axis is logarithmic, in which case the units are inches.  The
1190default may be gotten using the
1191\fB\-p\fR
1192option.
1193.TP
1194\fBmidspace \|[\fIfloat\fB\|]\fR   
1195This sets one of two things.  If any of the
1196legend entries have lines in them, then this sets the distance
1197between the end of the line and the legend entry text.  Otherwise,
1198this sets the distance between center of the mark and the legend
1199entry text.  Units are those of the x axis, unless the x axis is
1200logarithmic, in which case the units are inches.  The default may be
1201gotten using the
1202\fB\-p\fR
1203option.
1204.TP
1205\fBdefaults\fR
1206This lets the user change the attributes of all legend entries.
1207The defaults are editted as a label (see LABEL EDITING COMMANDS).
1208A few of the label fields have special meanings:  The \fI:\fR field
1209is ignored.  The \fIx\fR and \fIy\fR fields define where the label
1210will be printed.  The \fIhj\fR and \fIvj\fR fields define the justification
1211of the legend about the \fIx\fR and \fIy\fR point.  Thus, if \fIx\fR is 10
1212and \fIy\fR is 15, and \fIhjc  vjb\fR are specified, then the legend will
1213be centered horizontally about x=10, and the bottom of the legend
1214will be placed on y=15.  This is analagous to label plotting.
1215The \fIrotate\fR field is also analagous to label plotting.
1216
1217Defaults are as follows.  \fIRotate\fR is 0.  \fIfont\fR is ``Times-Roman''
1218and \fIfontsize\fR is 9.  The color is black.  Default justification is
1219\fIhjl\fR and \fIvjc\fR.  The default \fIx\fR and \fIy\fR values are set
1220according to the \fIhj\fR and \fIvj\fR fields.  See the
1221\fB\-p\fR
1222option.
1223.TP
1224\fBleft\fR   
1225.br
1226.ns
1227.TP
1228\fIright\fR
1229These will automatically produce a legend to the left or
1230the right of the graph. 
1231\fILeft\fR
1232is equivalent to
1233\fIdefaults hjr vjc\fR
1234and
1235\fIright\fR
1236is equivalent to
1237\fIdefaults hjl vjc\fR.
1238.TP
1239\fBtop\fR   
1240.br
1241.ns
1242.TP
1243\fBbottom\fR
1244These will automatically produce a legend on the top or
1245the bottom of the graph. 
1246\fITop\fR
1247is equivalent to
1248\fIdefaults hjl vjb\fR
1249 and
1250\fIbottom\fR
1251is equivalent to
1252\fIdefaults hjl vjt\fR.
1253.TP
1254\fBx \|[\fIfloat\fB\|]\fR
1255.br
1256.ns
1257.TP
1258\fBy \|[\fIfloat\fB\|]\fR   
1259These are included mainly for backward compatability to earlier
1260versions of jgraph.  Setting
1261\fIx\fR
1262and
1263\fIy\fR
1264is equivalent to ``defaults x
1265\fIfloat\fR
1266y
1267\fIfloat\fR
1268hjl vjt''
1269.TP
1270\fBcustom\fR   
1271This lets the user control where each individual legend
1272entry goes.  The values of the
1273\fIdefaults\fR
1274fields are ignored, and instead, the values of the curve's
1275labels are used.  All justifications have defined results, except
1276for
1277\fIhjc\fR.
1278Similarly, rotation other than 0 is likely to produce bad effects.
1279.PD
1280.RE
1281.LP
1282.TP
1283.B ADVANCED AXIS EDITING
1284These are more advanced commands for
1285editing an axis.  This includes drawing explicit hash marks and
1286labels, moving the hash marks, axes, and labels, not drawing the hash
1287marks, labels, axes, etc.
1288.RS
1289.TP
1290\fBgray \|[\fIfloat\fB\|]\fR
1291.br
1292.ns
1293.TP
1294\fBcolor \|[\fIfloat\fB \fIfloat\fB \fIfloat\fB\|]\fR
1295These specify either the grayness of the axis or its color.  Values
1296for
1297\fIgray\fR
1298should be from 0 (black) to 1 (white).  Values for
1299\fIcolor\fR
1300should also be from 0 to 1.  They are RGB values, and thus define the
1301amount of red, green and blue in the axis respectively.  Specifying
1302color nullifies the gray value, and vice versa.  The default is
1303\fIgray 0\fR.
1304These values affect every part of the axis:  the label,
1305the hash marks and labels, the axis line and the grid lines.
1306.TP
1307\fBgrid_gray \|[\fIfloat\fB\|]\fR
1308.br
1309.ns
1310.TP
1311\fBgrid_color \|[\fIfloat\fB \fIfloat\fB \fIfloat\fB\|]\fR
1312.br
1313.ns
1314.TP
1315\fBmgrid_gray \|[\fIfloat\fB\|]\fR
1316.br
1317.ns
1318.TP
1319\fBmgrid_color \|[\fIfloat\fB \fIfloat\fB \fIfloat\fB\|]\fR
1320These allow the user to define the grayness or color of the
1321gridlines and the mgridlines to be different from those of the
1322axis lines.
1323The default
1324\fIgrid_gray\fR
1325and
1326\fIgrid_color\fR
1327is the same as the axis's
1328\fIgray\fR
1329and
1330\fIcolor\fR.
1331The default
1332\fImgrid_gray\fR
1333and
1334\fImgrid_color\fR
1335is the same as
1336\fIgrid_gray\fR
1337and
1338\fIgrid_color\fR.
1339.TP
1340\fBhash_at \|[\fIfloat\fB\|]\fR   
1341Draw a hash mark at this point.  No label is
1342made for this hash mark.
1343.TP
1344\fBmhash_at \|[\fIfloat\fB\|]\fR   
1345Draw a minor hash mark at this point.
1346.TP
1347\fBhash_label\fR   
1348Edit a hash label (see HASH LABEL EDITING COMMANDS).
1349.TP
1350\fBhash_labels\fR   
1351Edit the default characteristics of the hash labels.
1352This is so that the user can change the fontsize, justification,
1353etc., of the hash labels.  Editing
1354\fIhash_labels \fR
1355is just like editing
1356normal labels (see LABEL EDITING COMMANDS), except that the
1357\fI:\fR,
1358\fIx\fR,
1359and
1360\fIy\fR
1361values are all ignored. Defaults for hash labels are as
1362follows: Fontsize=9, Font=``Times-Roman'', Justification is dependent
1363on whether it is the x or y axis and whether
1364\fIhash_scale\fR
1365is positive or negative.
1366.TP
1367\fBhash_scale \|[\fIfloat\fB\|]\fR   
1368This is to change the size and orientation of
1369the hash marks.  Default = -1.0.  Changing this to -2.0 will double
1370the length of the hash marks.  Changing this to +1.0 will make the
1371hash marks come above or to the right of the axis.
1372.TP
1373\fBdraw_hash_marks_at \|[\fIfloat\fB\|]\fR   
1374By default, the hash marks are drawn
1375either above or below the axis.  This command changes where they are
1376drawn. 
1377\fIHash_scale\fR
1378still determines whether they are drawn above or
1379below this point, and their size.
1380.TP
1381\fBdraw_hash_labels_at \|[\fIfloat\fB\|]\fR   
1382By default, the hash labels are
1383drawn either above or below the hash marks (again, this is dependent
1384on
1385\fIhash_scale\fR).
1386This command changes where they are drawn.
1387Justification and fontsize, etc., can be changed with the
1388\fIhash_labels\fR
1389command.
1390.TP
1391\fBauto_hash_marks\fR
1392.br
1393.ns
1394.TP
1395\fBno_auto_hash_marks\fR   
1396This toggles whether or
1397not
1398\fBjgraph \fR
1399will automatically create hash marks according to
1400\fIhash\fR,
1401\fImhash\fR
1402and
1403\fIshash\fR
1404(or
1405\fIlog_base\fR
1406and
1407\fImhash\fR
1408for logarithmic axes).
1409The default is
1410\fIauto_hash_marks\fR.
1411.TP
1412\fBauto_hash_labels\fR
1413.br
1414.ns
1415.TP
1416\fBno_auto_hash_labels\fR   
1417This toggles whether or
1418not
1419\fBjgraph \fR
1420will automatically create hash labels for the
1421\fIauto_hash_marks\fR.
1422Default =
1423\fIauto_hash_labels\fR.
1424.TP
1425\fBdraw_axis\fR
1426.br
1427.ns
1428.TP
1429\fBno_draw_axis\fR   
1430This toggles whether or not the axis
1431line is drawn.  Default =
1432\fIdraw_axis\fR.
1433.TP
1434\fBdraw_axis_label\fR
1435.br
1436.ns
1437.TP
1438\fBno_draw_axis_label\fR   
1439This toggles whether or
1440not the axis label (as editted by the
1441\fIlabel\fR
1442command) is drawn.
1443Default =
1444\fIdraw_axis_label\fR.
1445.TP
1446\fBdraw_hash_marks\fR
1447.br
1448.ns
1449.TP
1450\fBno_draw_hash_marks\fR   
1451This toggles whether or
1452not the hash marks (both automatic and those created with
1453\fIhash_at\fR
1454and
1455\fImhash_at\fR)
1456are drawn.  Default =
1457\fIdraw_hash_marks\fR.
1458.TP
1459\fBdraw_hash_labels\fR
1460.br
1461.ns
1462.TP
1463\fBno_draw_hash_labels\fR   
1464This toggles whether or
1465not the hash labels are drawn.  Default =
1466\fIdraw_hash_labels\fR.
1467.PD
1468.RE
1469.LP
1470.TP
1471.B HASH LABEL EDITING COMMANDS
1472Hash labels are simply strings printed
1473along the appropriate axis.  As a default, they are printed at the
1474place denoted by the most recent
1475\fIhash_at\fR
1476or
1477\fImhash_at\fR
1478for this
1479axis, but this can be changed by the
1480\fIat\fR
1481command.  If there has been
1482no
1483\fIhash_at\fR
1484or
1485\fImhash_at\fR,
1486then an
1487\fIat\fR
1488command must be given, or
1489there will be an error.  Hash editing terminates when either one of
1490these commands is not given.
1491.RS
1492.TP
1493\fB: \|{\fIstring\fB\|}\fR   
1494This sets the string of the hash label (see
1495\fBStrings\fR
1496above under THE DESCRIPTION LANGUAGE).
1497.TP
1498\fBat \|[\fIfloat\fB\|]\fR   
1499This sets the location of the hash label along the
1500current axis.
1501.PD
1502.RE
1503.LP
1504.SH FUNCTION PLOTTING AND OTHER NON-INHERENT FEATURES
1505Although
1506\fBjgraph \fR
1507doesn't have any built-in functions for interpolation
1508or function plotting, both can be effected in
1509\fBjgraph \fR
1510with a little outside help:
1511.TP
1512\fBFunction plotting\fR
1513With the
1514\fIinclude\fR
1515and
1516\fIshell\fR
1517statement, it's easy to
1518create a file of points of a function with a c or awk program, and
1519include it into a graph.  See the section HINTS AND EXAMPLE GRAPHS
1520for an example of a sin graph produced in this manner.
1521.TP
1522\fBPoint interpolation\fR
1523Point interpolation is essentially the same as
1524function plotting, and therefore is left out of
1525\fBjgraph.  \fR
1526The UNIX spline(1) routine is a simple way to get interpolation
1527between points.  See bailey.jgr described below.
1528Maybe in a future release.
1529.SH HINTS AND EXAMPLE GRAPHS
1530\fBJgraph \fR
1531should be able to draw any kind of scatter/line/bar graph that
1532a user desires.  To embellish the graph with extra text, axes, lines,
1533etc., it is helpful to use
1534\fIcopygraph.\fR
1535The following example graphs show a few examples of different features
1536of jgraph.  They should be in the directory /usr/doc/examples/jgraph.
1537.sp
1538- acc.jgr is a simple bar graph.  Acc.tex is also included to show
1539how one can include the output of jgraph in a LaTeX file.  To get
1540this to work, you might have to substitute the entire pathname of
1541the file acc.jps in the acc.tex file.
1542.sp
1543- g8.jgr is a simple graph with some plotted text.
1544- g8col.jgr shows how to produce a color background -- it is
1545  the same as g8.jgr only all on a yellow background.
1546- ebars.jgr is a simple graph with error bars.
1547- sin.jgr shows how a sin function can be plotted using a simple c
1548program to produce the sin wave.  Moreover, this file shows a use of
1549\fIcopygraph\fR
1550to plot an extra x and y axis at the 0 point.
1551.sp
1552- sin1.jgr is a further extension of sin.jgr only with one x and y
1553axis at 0, but with the axis labels at the left and the bottom of the
1554graph.
1555.sp
1556- sin2.jgr is a different sin wave with a logarithmic x axis.
1557.sp
1558- sin3.jgr shows how a bizarre effect can be gotten by sorting the
1559points in a different manner.
1560.sp
1561- bailey.jgr shows how to use the UNIX spline(1) routine to get
1562interpolation between points.
1563.sp
1564- gpaper.jgr shows how you can get jgraph to easily produce graph paper.
1565.sp
1566- g9n10.jgr contains two graphs with complicated legends.  It
1567contains a description of how the legend was created.
1568.sp
1569- ex1.jgr and ex2.jgr are two examples which were figures 1 and
1570two in an extended abstract for a paper about jgraph.
1571.sp
1572- mab2.jgr is a graph created by Matt Blaze which shows how a
1573complicated output graph can be quite concisely and simply stated.
1574In this graph, the x axis is a time line.  It shows usage of the
1575\fIhash_label\fR
1576and
1577\fIhash_labels\fR
1578commands, as well as displaying how jgraph lets you extract data from
1579output files with awk.
1580.sp
1581- nr.jgr is an example of a rather complicated bar graph with
1582stripe-filled bars.  It was created by Norman Ramsey.
1583.sp
1584- hypercube.jgr shows an interesting use of jgraph
1585for picture-drawing.
1586.sp
1587- ad.jgr is an example which shows how one can include jgraph
1588output as jgraph input.  The file uses the \fIeps\fR token to
1589include cube.jgr, a jgraph drawing of an Intel hypercube, and disk.jgr,
1590a jgraph drawing of a disk, in a picture.
1591.sp
1592- alb.jgr is another use of jgraph for picture drawing.  This file
1593was created by an awk script which Adam Buchsbaum wrote to draw
1594trees and graphs.
1595.sp
1596- wortman.jgr is a neat graph of processor utilization written
1597by Dave Wortman for SIGPLAN '92.  It was created by an awk script,
1598which processed the data and emitted the jgraph.
1599.sp
1600To view these graphs, use jgraph -P, and view the resulting output
1601file with
1602\fIgs\fR,
1603or a similar postscript viewer.
1604To make a hard copy of these graphs, pipe the output of jgraph
1605-P directly to
1606\fIlpr\fR.
1607
1608.SH USING JGRAPH TO DRAW PICTURES
1609As hypercube.jgr and alb.jgr show, jgraph can be used as a postscript
1610preprocessor to make drawings.  There are two advantages
1611using jgraph to draw pictures instead of using standard drawing tools like
1612\fIxfig\fR,
1613\fIfigtool\fR,
1614or
1615\fIidraw\fR.
1616The first is that with jgraph, you know exactly where strings, lines,
1617boxes, etc, will end up, because you plot them explicitly.  The second
1618advantage is that for iterative drawings, with lots of patters, you
1619can combine jgraph with awk or c or any other programming language
1620to get complex output in a simple way.  Most what-you-see-is-what-you-get
1621(WYSIWYG) drawing tools cannot do this. 
1622
1623The major disadvantage of using jgraph to draw pictures is that jgraph
1624is not WYSIWYG.  You have to set up axes and plot points, lines and
1625strings.  It's all a matter of taste.
1626
1627If you'd like to see some more complex pictures drawn with jgraph, as
1628well as some hints to make picture-drawing easier, send me email
1629(plank@cs.utk.edu).
1630
1631.SH SUPPORT FOR OTHER FONT ENCODINGS
1632If you want to use non-english characters to set labels or titles,
1633set enviroment variable JGRAPH_ENCODING with the font encoding that
1634you need. This value will be passed directly to the postscript.
1635
1636Ex. to use ISO-8859-1 characters, try:
1637.nf
1638
1639   export JGRAPH_ENCODING=ISOLatin1Encoding
1640
1641.fi
1642Note: that only works with default fonts. if you use 'font' in stdin
1643to specify another font, it won't work.
1644
1645You also have the possibility to expand the bounding box if jgraph
1646cuts some acute, tilde or special chars near the border; try:
1647.nf
1648
1649   export JGRAPH_BORDER=5
1650
1651.fi
1652This support is currently 'testing' code. Send bugs about it
1653to pzn@debian.org
1654
1655.SH INTEGRATION WITH LATEX
1656.PP
1657.nf
16581. At the top, say
1659   \\usepackage{graphics}
1660
16612. The floating object is done using:
1662
1663   \\begin{figure}
1664   \\begin{center}
1665   \\includegraphics{a.eps}
1666   \\end{center}
1667   \\end{figure}
1668   
16693. Now go through dvips as usual and the .ps file will work.
1670.fi
1671.PP
1672.SH INTEGRATION WITH PDFLATEX
1673
1674If you are using pdflatex, it requires .pdf files and not .eps
1675files. In that case, you have to run epstopdf on the .eps file to get
1676a .pdf file. After that,
1677.br
1678   \\includegraphics{a.pdf}
1679.br
1680does the trick.
1681.SH SCALING THE INCLUDED GRAPHICS OBJECT
1682Sometimes you need to change the size of the included object at LaTeX
1683time. In that case, you need
1684.br
1685   \\usepackage{graphicx}
1686.br
1687instead of graphics, and then say something like
1688
1689    \\includegraphics[width=7cm]{a.eps}
1690 or
1691    \\includegraphics[height=7cm]{a.eps}
1692
1693you can also omit the .eps/.pdf suffix:
1694    \\includegraphics[height=7cm]{a}
1695
1696a.eps and a.pdf can both exist, and includegraphics will automatically
1697choose the correct one for postscript or pdf output, depending if you
1698are using latex of pdflatex.
1699
1700.SH AUTOMATION USING MAKE
1701You can automate the mapping from .jgr -> .eps or .jgr -> .pdf
1702in your Makefile using these rules:
1703.nf
1704
1705--------- cut here ---------
1706%.eps : %.jgr
1707        jgraph $< > $@
1708%.pdf : %.jgr
1709        jgraph $< | epstopdf --filter > $@
1710--------- cut here ---------
1711.fi
1712
1713jgraph can also return the exit status correctly, so it is also a good
1714idea to use it in your scripts to prevent bad .eps files if the .jgr
1715source is bad. The following Makefile can handle its exit status.
1716.nf
1717
1718--------- cut here ---------
1719%.eps : %.jgr
1720        jgraph $< > $@; \\
1721        if [ "$$?" != "0" ]; then \\
1722          rm -f $@; \\
1723          exit 1; \\
1724        fi
1725%.pdf : %.jgr
1726        TMP=`tempfile`; jgraph $< > $${TMP}; \\
1727        if [ "$$?" == "0" ]; then \\
1728          cat $${TMP} | epstopdf --filter > $@; \\
1729          rm -f $${TMP}; \\
1730        else \\
1731          rm -f $${TMP} $@; \\
1732          exit 1; \\
1733        fi;
1734--------- cut here ---------
1735.fi
1736
1737.SH BUGS
1738Logarithmic axes cannot contain points <= 0.  If I have
1739enough complaints to convince me that this is a bug, I'll try to fix it.
1740.sp
1741There is no real way to make the axes such that they decrease from
1742left to right or low to high -- or at least not without writing your
1743own hash labels. 
1744.sp
1745There may well be loads of other bugs.  Send to plank@cs.utk.edu.
1746.sp
1747
1748This is $Revision: 8.3 $.
Note: See TracBrowser for help on using the repository browser.