jgraph - filter for graph plotting to postscript

     jgraph [-p] [-P] [-L] [-comments] [filename ...]

     Jgraph takes the description of a graph or graphs and pro-
     duces a postscript file on the standard output. Jgraph is
     ideal for plotting any mixture of scatter point graphs, line
     graphs, and/or bar graphs, and embedding the output into
     LaTeX, or any other text processing system which can read

     Jgraph reads its input from the specified files.   If no
     files are specified, then it reads from standard input.

     The graph description language is simple enough to get nice
     looking graphs with a minimum of effort, yet powerful enough
     to give the user the flexibility to tailor the appearance of
     the graph to his or her individual preferences.  This
     includes plotting multiple graphs and laying them out
     separately on the page (or pages).

     As an example, if the user wanted to simply plot the points
     (2,3), (4,5), (1,6), the following would be enough of a
     specification file:

          newcurve pts 2 3 4 5 1 6

     Now, if the user wanted to spruce the graph up by adding
     labels to the axes, connecting the points, and titling the
     graph, then the input could change to:

          newcurve pts 2 3 4 5 1 6 linetype solid
          xaxis label : X axis
          yaxis label : Y axis
          title : This is an example graph

     If the user instead wanted this to be a bar graph with dif-
     ferent endpoints on the axes, he/she could simply change the
     input to:

          xaxis min 0 max 5 label : X axis
          yaxis min 0 max 6 label : Y axis
          newcurve pts 2 3 4 5 1 6 marktype xbar
          title : This is an example bar graph

     There are many more features of the description language,
     which are described below in the next section.  Features
     which are not embedded within the description language are:
     line and function interpolation, function plotting, and pie
     graphs.  The latter is impossible to do with the aid of
     jgraph, however, the others can be effected with jgraph
     mixed with awk or c.  See FUNCTION PLOTTING AND  OTHER  NON-

     Also below is a section HINTS AND EXAMPLE GRAPHS, which may
     give good ideas on how to use jgraph more effectively.

     -P   The -P option produces postscript which can be piped
          directly to lpr, which can be displayed in an Xwindows
          environment with gs (ghostscript).    Without this
          option, the output should be embedded within LaTeX or a
          similar text processing system.

     -L   The -L option produces a landscape plot.

     -p   The -p option re-prints the input on the standard out-
          put, only with all the defaults made explicit.  This is
          useful for letting the user do his/her own special for-
          matting, as it shows the explicit values that the
          defaults assume, so that they can be manipulated.

          This option makes jgraph put comments into the output
          postscript.   These make it easier for the user to wade
          through the final postscript if necessary.

     The description language is essentially keywords followed by
     attributes.   All keywords and attributes except for string
     attributes are tokens --  non-white-space characters sur-
     rounded by white-space. Special tokens are ``(*'', ``*)'',
     ``include'', ``:'', and ``shell'', which denote comments,
     include-file statements, string identifiers, and shell-
     include statements:

          Comments are surrounded by the tokens ``(*'' ``*)''  as
          in Modula-2 (except that here, the tokens must be sur-
          rounded by white- space).  Comments may be nested.   If
          the comment runs to the end of a file, the last ``*)''
          may be omitted.

     Include-file statements
          The token following an ``include'' token is expected to
          be a file name.   The result of the statement is to
          include the contents of the file at that point.
          Include-file statments can be nested within included
          files, and within shell includes.

          In places where strings are required (as in graph and
          curve labels), they are denoted by the token ``:''.
          The second character after the ``:'' starts the string,
          and the next newline character terminates it. Thus, the
          string ``Graph #1'' can be denoted as:

               : Graph #1


               Graph #1

          One can get multiline strings by making a backslash the
          last character before the newline on all but the last
          line.   Notice that in strings white-space is not
          ignored.  This way of denoting strings allows the user
          to embed leading and trailing spaces, as well as the
          null string.   For example, the null string ``'' is
          represented by:


          Once a string has been started, it may contain any
          character.   Specifically, it may contain the sequence
          ``(*'', ``shell'', or ``include''  without starting a
          comment or including a file.  Each line of a string
          must contain less than 1000  characters.   Otherwise
          string sizes are limited only by the size of memory.

     Shell-include statements
          Shell include statements are of the form ``shell'',
          ``:'', and then a string.  The result of the statement
          is that the string is executed (using popen, which
          passes the string to sh), and the standard output is
          included at that point.  Shell-includes can be freely
          nested within include-files and other shell-includes.
          Shell commands may be more than one line, but must not
          exceed 1000  characters.   The shell statement is not
          (yet) available on VMS.

          In the descriptions below:

          tk {integer}
               means that token tk must be followed by an

          tk [integer]
               means that tk may be followed by an integer, but
               doesn't have to.  In most cases, if tk is not fol-
               lowed by an integer, then the command denoted by
               tk is ignored.

          tk [{integer} {integer}]*
               means that tk must be followed by an even number
               of integers.

          Supported types other than integer are:  {float}  for
          floating point entries, {token}  for any token, and
          {string} for a string as defined above.


               This starts editing a new graph (see GRAPH EDITING
               COMMANDS).  Note that multiple graphs may be drawn
               on the same page.

          graph {integer}
               This edits the graph denoted by {integer}. If the
               graph doesn't exist, then this command creates it
               and starts editing it.  Newgraph is simply an
               abbreviation for graph n where n=0 if this is the
               first graph, otherwise n=m+1, where m is the larg-
               est number of any graph so far.

          copygraph [integer]
               This creates a new graph, and copies all the
               attributes from the graph [integer]'s x and y
               axes, as well as its x_translate and y_translate
               values, the clipping, the legend defaults, and the
               title defaults.   If the [integer]  is omitted,
               then it copies its values from the ``previous''
               graph, which is defined to be the graph with the
               largest number less than the currrent graph's
               number.  If the current graph has the smallest
               number, then it will take the last graph from the
               previous page of graphs.  If there is no previous
               page, then an error will be flagged.  (copygraph
               does not copy the values of the hash_at, mhash_at,
               and hash_label attributes).

               This command is for plotting graphs on multiple
               pages.   After a newpage, the graphs that the user
               enters will be plotted on a new page.  New graphs
               and strings will be numbered starting with 0.
               Essentially, newpage is the same as appending
               together the output of separate calls of jgraph on
               the text before the newpage, and on the text after
               the newpage.   Newpage will most likely produce
               bizarre results if the -P option is not specified.

          X [float]
          Y [float]
               Postscript files to be embedded in LaTeX (and some
               other programs)  contain a ``bounding box'' which
               defines the area which LaTeX will allocate for the
               postscript.   Other programs use this bounding box
               as well, sometimes using it to define where to
               clip the postscript image.  Jgraph uses the axis
               lines and labels, and the title to generate its
               bounding box.  Most of the time that's good enough
               to work in LaTeX.  The Y and X  commands say to
               make the height and width of the bounding box at
               least Y and X inches, respectively, but to main-
               tain the current centering of the graph.  If you
               still need further control over the bounding box
               (e.g.  to change the centering), try the bbox com-
               mand.  If there's more than one page in the jgraph
               file, Y, X and bbox values can be given for each

          bbox float float float float
               If the Y and X commands aren't enough to help you
               define a good bounding box, this command lets you
               explicitly enter one which will go directly into
               the jgraph output.   Its units are the final
               postscript units.  It's probably best to use the
               -pFR  option to see what the bounding box is that
               jgraph produces, and then alter that accordingly
               with bbox.  The main use for this is to change the
               automatic centering that jgraph performs:  Usually
               the center of the bounding box that jgraph com-
               putes is put at the center of the page.   Changing
               the bbox changes this center.

          preamble : {string}
          preamble {token}
          epilogue : {string}
          epilogue {token}
               These two commands allow the user to include
               strings or files (the token specifies the
               filename) which will be copied directly into
               jgraph's output.  The preamble is included at the
               beginning of the output (after some initial
               postscript to set things up for jgraph), and the
               epilogue is included at the end.  A good use for
               the preamble is to set up a postscript dictionary
               if you're using postscript marks.

          These commands act on the current graph. Graph editing
          is terminated when one of the top-level description
          commands is given.

               Edit the x or y axis (see AXIS EDITING COMMANDS)

               This starts editing a new curve of the graph (see

          curve {integer}
               This edits the curve denoted by {integer}. If the
               curve doesn't exist, then this command creates it
               and starts editing it. Newcurve and curve interact
               as newgraph and graph do.

               This is an abbreviation for:

                 newcurve marktype none linetype solid

          copycurve [integer]
               This starts editing a new curve of the graph, and
               copies all its values except for the points from
               curve [integer.]  If the [integer]  is omitted,
               then it copies its values from the last curve in
               this graph.   If this graph currently has no
               curves, then it searches backwards from the previ-
               ous graph.

               This edits the title of the graph (see LABEL EDIT-
               ING COMMANDS).  The title is given a default loca-
               tion centered beneath the graph, and a default
               font size of 12, however, as with all labels, this
               can be changed.

               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.

               This edits a new text string (see LABEL  EDITING
               COMMANDS).   This is useful as it allows the user
               to plot text on the graph as well as curves.

          string {integer}
          copystring [integer]
               String and copystring are to newstring as curve
               and copycurve are to newcurve.

               Border draws a square border around the area
               defined by the axes.   Noborder specifies no
               border.  Noborder is the default.

               Clip specifies that all curves in the graph will
               be clipped -- that is, no points outside of the of
               axes will be plotted.  Clipping can also be speci-
               fied on a per-curve basis.  The default is noclip.

               This is an old command which is kept for backward
               compatibility.  Copycurve.  is equivalent to:

                 newgraph inherit_axes

          x_translate [float]
          y_translate [float]
               By default, the bottom left-hand corner of each
               graph is at point (0,0) (final postscript units).
               X_translate and Y_translate translate the bottom
               left-hand corner of the graph [float] inches.  The
               main use of this is to draw more than one graph on
               a page.  Note that jgraph considers all the graphs
               drawn on the page when it computes its bounding
               box for centering.   Thus, if only one graph is
               drawn, it will always be centered on the page,
               regardless of its X_translate and Y_translate
               values.  These values are used for relative place-
               ment of the graphs.
                  To change the centering of the graphs, use

          X [float]
          Y [float]
               These are the same as X and Y  in the Top-level
               commands, except that they let the user continue
               editing the current graph.

          These commands act on the current axis as chosen by
          xaxis or yaxis (see GRAPH EDITING COMMANDS). Axis edit-
          ing terminates when a graph or top-level command is
          given.  There are more advanced axis editing commands
          given below which have to do with moving the hash
          marks, adding new hash marks and labels, etc.  See


          log Set the axis to be linear or logarithmic.  The
               default is linear.  If the axis is set to be loga-
               rithmic, then values <= 0.0 will be disallowed, as
               they are at negative infinity on the axis.

          min [float]
          max [float]
               Set the minimum and maximum values of this axis.
               Defaults depend on the points given.  They can be
               seen by using the -p option.  Unless stated, all
               units (for example point plotting, string plot-
               ting, etc.) will be in terms of the min and max
               values of the x and y axes.

          size [float]
               Set the size of this axis in inches.

          log_base [float]
               Set the base of the logarithmic axis.  Default =
               10.  This is the value which determines which hash
               marks and hash labels are automatically produced.

          hash [float]
               Hash marks will be [float] units apart.  Default =
               -1.  If this value equals 0, then there will be no
               hash marks.  If this value is less than 0, then
               the hash marks will be automatically set by jgraph
               (see -p for the value).   By default, each hash
               mark will be labeled with its value. Hash and
               shash are ignored if the axes are logarithmic.

          shash [float]
               Make sure there is a hash mark at the point
               [float]  along the axis.   The default is set by
               jgraph if hash = -1.  If hash is set by the user,
               shash is defaulted to the min value of the axis.

          mhash [integer]
               Put [integer] minor hash marks between the above
               hash marks.   Default = -1.  If this value equals
               0, then there will be no minor hash marks.   If
               this value is negative, then the value will be
               chosen by jgraph (see -p for the value).

          precision [integer]

          hash_format token
               These control how jgraph formats the automatic
               hash labels.   The user shouldn't have to worry
               about these values, except in extreme cases.
               Jgraph uses printf to format the labels.  If
               hash_format is ``f'' (the default), then the value
               of a hash label is printed with

               printf("%.*f", precision, value).

          Other valid hash_format values are ``G'', ``g'', ``E'',
          and ``e''.   ``G'' is a good generic format which con-
          verts to scientific notation if the value becomes too
          big or too small.  If the precision is negative, then
          jgraph chooses a default:  For ``g''  and ``G'', the
          default is 6.  For ``e'' and ``E'', the default is 0,
          and for ``f'', jgraph tries to determine a reasonable
          default.   Please read the man page of prinf(1) for a
          complete description of how it formats floating point

               Edit the label of this axis (see LABEL  EDITING
               COMMANDS).  By default, the label is in font
               ``Times-Bold'', and has a font size of 10.  If the
               user doesn't change any of the plotting attributes
               of the label, jgraph chooses an appropriate place
               for the axis label.

          draw_at [float]
               Draw the axis line at this point on the other
               axis. The default is usually the other axis's min,
               however if hash_scale is positive (see hash_scale
               under ADVANCED AXIS EDITING), it will be the other
               axis's max.

               Do not draw the axis, the hash marks or any
               labels.   This is useful for plotting points with
               no axes, and for overlaying graphs on top of one
               another with no clashes.  This is equivalent to
               no_draw_axis,                 no_draw_axis_label,
               no_draw_hash_marks, and no_draw_hash_labels.

          draw Cancels the effect of nodraw.  Default =  draw.
               This is equivalent to draw_axis, draw_axis_label,
               draw_hash_marks, and draw_hash_labels.

               Grid_lines specifies to plot a grid line at each
               major hash mark on this axis.  The default is

               Mgrid_lines specifies to plot a grid line at each
               minor hash mark on this axis.  The default is

          These commands act on the current curve as chosen by
          newcurve or curve (see GRAPH EDITING COMMANDS).  Curve
          editing terminates when a graph or top-level command is

          pts [{float} {float}]*
               This sets the points to plot in this curve.   The
               first float is the x value, and the second float
               is the y value of the point.  Points are plotted
               in the order specified.  This command stops read-
               ing points when a non-float is given.   The user
               can specify this command multiple times within a
               curve -- each time, simply more points are added
               to the curve.

          x_epts [{float} {float} {float} {float}]*
          y_epts [{float} {float} {float} {float}]*
               This allows the user to specify points and ``con-
               fidence values'' (otherwise known as ``error
               bars'').  The first two floats specify the x and y
               values of the point, as above.   If x_epts is
               specified, then the second two floats specify
               range or confidence values for the x value of the
               point. Error bars will be printed to each of these
               x values (using the original point's y value) from
               the original point.  Similarly, y_epts specifies
               range or confidence values for the y value of the
               point.  pts x_epts and y_epts can all be inter-

               This sets the kind of mark that is plotted for
               this curve.   Valid marks are: circle, box, dia-
               mond, triangle, x, cross, ellipse, xbar, ybar,
               text, postscript, eps, none, and variants of gen-
               eral.  Most of these are self-explanatory, except
               for the last few:
                 Xbar makes the curve into a bar graph with the
               bars going to the x axis.  Ybar has the bars going
               to the y axis.
                 Text lets the user plot text instead of a mark.
               The text is editted as a label (see LABEL EDITING
               COMMANDS) immediately following the text command.
               The x and y fields of the label have special mean-
               ings here:  They define where the label is to be
               printed in relation to the curve points.  For
               example, if they are both 0, the label will be
               printed directly on the curve points.  If x is 1.0
               and y is -1.0, then the label will be printed one
               unit to the right and one unit below the curve
               points (units are units of the x and y axes).
               Default label values are 0 for x and y, and center
                 Postscript: See the postscript token below.
                 Eps: See the eps token below.
                 None means that no mark will be plotted (this is
               useful for drawing lines).
                 There are four types of general marks, which
               work using the gmarks command described below.
               The four marktypes are general, general_nf,
               general_bez, and general_bez_nf.
                 By default, a new mark is chosen for each curve.

          marksize [float] [float]
               This sets the size of the mark.  The first [float]
               is the width of the mark, and the second is the
               height. Units are those of the x and y axes
               respectively, unless that axis is logarithmic, in
               which case the units are inches.   Negative mark-
               sizes are allowed (e.g.  a negative height will
               flip a triangle mark). The default mark size can
               be determined using the -p option of jgraph

          mrotate [float]
               This allows the user to rotate the mark [float]
               degrees.  Default is zero.

          gray [float]
          color [float float float]
               These specify either the grayness of the curve or
               its color.   Values for gray should be from 0
               (black) to 1 (white).   Values for color should
               also be from 0  to 1.  They are RGB values, and
               thus define the amount of red, green and blue in
               the curve respectively.  Specifying color nulli-
               fies the gray value, and vice versa.  The default
               is gray 0

          fill [float]
          cfill [float float float]
               This sets the filling of marks which define an
               area to fill (e.g.   box, circle, xbar). fill
               defines a gray value, and cfill defines a color
               value (see gray and color above for a description
               of the units).  The default is fill 0 (black).

          pattern token [float]
               This defines the how the mark is to be filled.
               Token may be solid (the default), stripe, or
               estripe.  If solid, then the float is ignored, and
               the mark is completely filled in with either the
               gray value defined by fill or the color value
               defined by cfill.  If stripe, then the mark will
               be filled with stripes of either the gray value
               defined by fill or the color defined by cfill.
               The stripes will be rotated by float degrees.
               Estripe differs from stripe only in that stripe
               draws stripes on a white background, while estripe
               simply draws the stripes on an empty background.

          pfill [float]
          pcfill [float float float]
          ppattern token [float]
               Poly allows the user to make jgraph treat the
               curve as a closed polygon (or in the case of a
               bezier, a closed bezier curve).  pfill, pcfill and
               ppattern specify the filling of the polygon, and
               work like fill, cfill and pattern above.  The
               default is nopoly.

          gmarks [{float} {float}]*
               Gmarks is a way for the user to define custom
               marks.   For each mark on (x,y), Each pair of
               {float_x}, {float_y}, will define a point on the
               mark (x + (float_x * marksize_x / 2), y + (float_y
               * marksize_y / 2)).
                 Thus, for example, the box mark could be defined

               gmarks -1 -1 -1 1 1 1 1 -1
               marktype general

          The marktypes general, general_nf, general_bez, and
          general_bez_nf, allow the gmarks points to define a
          closed polygon, a line, a closed bezier curve and a
          regular bezier curve respectively (the ``nf'' stands
          for ``non-filled'').

          postscript : {string}
          postscript {token}
               This allows the user to enter direct postscript as
               a mark.   It automatically sets the marktype to
               postscript.  If a string is entered, then that
               string is used as the mark in the jgraph output.
               If a token is entered, then that token must stand
               for a filename, which will be copied to the output
               once for every mark.  The postscript will be set
               up so that when the string or file is put to the
               output, (0, 0) of the the axes is in the middle of
               the mark, it is rotated by mrotate degrees, and
               scaled by (marksize_x /  2), marksize_y /  2).
               Thus, the box mark could be defined as:

               postscript : 1 setlinewidth -1 -1 moveto -1 1 lineto \
                            1 1 lineto 1 -1 lineto -1 -1 lineto stroke

          If the marksize_x is defined to be (0, 0), then jgraph
          does no scaling.   This is useful when the postscript
          has strings, and the user does not want the strings to
          be scaled.

          eps {token}
               This allows the user to include an encapsulated
               postscript file and treat it as a mark.  It
               automatically sets the marktype to eps.  The file
               will be scaled so that the bounding box is mark-
               size units.  Among other things, this allows the
               user to include whole jgraph files as marks.
               Please see ad.jgr, explained in HINTS AND  EXAMPLE
               GRAPHS below for an example of this feature.

               Rarrows specifies to draw an arrow at the end of
               every line segment in the curve. Larrows specifies
               to draw an arrow at the beginning of every line
               segment.  The size of the arrows can be changed by
               using asize.  The default is nolarrows and norar-
                 Arrows always go exactly to the point specified,
               with the exception of when the marktype is ``cir-
               cle''.  In this case, the arrow goes to the edge
               of the circle.

               This is analgous to the above, except that with
               larrow, the only arrow drawn is to the beginning
               of the first segment in the curve, and with rar-
               row, the only arrow drawn is to the end of the
               last segment.

          asize [float] [float]
               This sets the size of the arrows.   The first
               [float] controls the arrow's width.  Its units are
               those of the x-axis.  The second [float]  controls
               the arrow's height.  It is in the units of the y-
               axis.  Use the -p option of jgraph to see the
               default values.

          afill [float]
          afill [float]
          apattern token [float]
               These control the grayness or color of arrowheads.
               Afill, acfill and apattern work in the same way as
               fill, cfill and pattern described above.   The
               default is afill 0 (black).

          linetype [token]
               This defines the type of the line connecting the
               points.   Valid entries are solid, dotted, dashed,
               longdash, dotdash, dotdotdash,  dotdotdashdash,
               general, and none.  The default is none.  General
               lets the user define his own linetype using the
               glines command described below.  Points are con-
               nected in the order in which they are inserted
               using the pts command.

          glines [float]*
               This lets the user specify the exact dashing of a
               line.  The format is as in postscript -- the first
               number is the length of the first dash, the second
               is the length of the space after the first dash,
               etc.  For example, dotdash could be defined as
               ``glines 5 3 1 3''.

          linethickness [float]
               This defines the line thickness (in absolute
               postscript units) of the connecting line.  Default
               = 1.0.

               Bezier specifies to use the curve's points to
               define successive bezier curves.  The first point
               is the starting point.  The next two are control
               points for the bezier curve and the next point is
               the ending point.  If there is another bezier,
               this ending point is also the beginning point of
               the next curve.  The next two points are again
               control points, and the next point is the ending
               point.  Thus, a bezier must have a total of (3n +
               1) points, where n is at least 1.
                 In bezier curves, marks and arrows only apply to
               every third point.  Nobezier is the default.

          clip This specifies that this curve will be clipped --
               that is, no points outside of the of axes will be

               This turns off clipping.  If clipping was speci-
               fied for the entire graph, then noclip has no
               effect.  Noclip is the default.

               This edits the label of this curve for the pur-
               posed of drawing a legend.  (see LABEL EDITING
               COMMANDS and LEGEND EDITING COMMANDS).  Unless the
               legend entry is custom, setting any label attri-
               bute except for the text itself will have no

          The following commands are used for editing labels.
          Unless stated otherwise, the defaults are written with
          each command.  Label editing terminates when one of
          these tokens is not given.

          : {string}
               This sets the string of the label.  If no string
               is set, the label will not be printed.

          x [float]
          y [float]
               This sets the x or y coordinate of the label.
               Units are the units of the x and y axes respec-

          font [token]
               This sets the font.  Default is usually ``Times-

          fontsize [float]
               This sets the fontsize in points.  Default is usu-
               ally 9.

          linesep [float]
               This sets the distance between lines in multilined
               labels.   Units are points.   The default is the

          hjr These set the horizontal justification to left,
               center, and right, respectively.  Default = hjc.

          vjb These set the vertical justification to top
               center, and bottom, respectively.  Default = vjb.

          rotate [float]
               This will rotate the string [float] degrees.   The
               point of rotation is defined by the vj and hj com-
               mands.  For example, to rotate 90  degrees about
               the center of a string, one would use vjc hjc
               rotate 90.

          lgray [float]
          lcolor [float float float]
               These control the color or the grayness of the
               label.   It works just as gray and color do for
               curves and axes.  The default depends on the con-
               text.  For example, for strings and the title, the
               default is black.   For axis labels and hash
               labels, the default is the color of the axis.  For
               text as marks, the default is the curve color.

          These commands allow the user to alter the appearance
          of the legend.  Legends are printed out for each curve
          having a non-null label.   The legend entries are
          printed out in the order of ascending curve numbers.
          Legend editing terminates when a graph command or top
          level command is issued.

          In earlier versions of jgraph (before version 8.0), the
          characteristics of each legend entry were set in the
          label portion of the entry's curve.  Thus, for example,
          if you wanted each entry's fontsize to be 18, you had
          to set it in each entry's curve.  Now, default legend
          entry characteristics are set using the defaults key-
          word.  Unless a custom legend is specified, these
          default values override any values set in the entry's
          curve.  Thus, to get all entries to have a fontsize of
          18, it must be set using defaults fontsize 18.

          If legend editing seems cryptic, try the following

          newcurve marktype box linetype solid label : Solid box
               pts 0 0 1 1 2 1 3 1
          newcurve marktype circle linetype dotted label : Dotted circle
               pts 0 1 1 2 2 2 3 2
          newcurve marktype x linetype dashed label : Dashed x
               pts 0 2 1 3 2 3 3 3
             legend defaults
               font Times-Italic fontsize 14 x 1.5 y 3.5 hjc vjb

     The legend of this graph should be centered over the top of
     the graph, and all legend entries should be 14pt Times-

          offR These turn printing of the legend on and off.  The
               default is on (but, of course, if there are no
               curve labels defined, there will be no legend).

          linelength [float]
               This sets the length of the line printed in front
               of legend entries corresponding to curves which
               have lines. Units are those of the x axis, unless
               the x axis is logarithmic, in which case the units
               are inches.  The default may be gotten using the
               -p option.

          linebreak [float]
               This sets the vertical distance between individual
               legend entries.   Units are those of the y axis,
               unless the y axis is logarithmic, in which case
               the units are inches.  The default may be gotten
               using the -p option.

          midspace [float]
               This sets one of two things.  If any of the legend
               entries have lines in them, then this sets the
               distance between the end of the line and the
               legend entry text.  Otherwise, this sets the dis-
               tance between center of the mark and the legend
               entry text.  Units are those of the x axis, unless
               the x axis is logarithmic, in which case the units
               are inches.   The default may be gotten using the
               -p option.

               This lets the user change the attributes of all
               legend entries.   The defaults are editted as a
               label (see LABEL EDITING COMMANDS).  A few of the
               label fields have special meanings:  The : field
               is ignored.  The x and y fields define where the
               label will be printed.   The hj and vj fields
               define the justification of the legend about the x
               and y point.   Thus, if x is 10 and y is 15, and
               hjc vjb are specified, then the legend will be
               centered horizontally about x=10, and the bottom
               of the legend will be placed on y=15.   This is
               analagous to label plotting.  The rotate field is
               also analagous to label plotting.

               Defaults are as follows.  Rotate is 0.   font is
               ``Times-Roman''  and fontsize is 9.  The color is
               black.  Default justification is hjl and vjc.  The
               default x and y values are set according to the hj
               and vj fields.  See the -p option.

               These will automatically produce a legend to the
               left or the right of the graph. Left is equivalent
               to defaults hjr vjc and right is equivalent to
               defaults hjl vjc.

               These will automatically produce a legend on the
               top or the bottom of the graph. Top is equivalent
               to defaults hjl vjb
                and bottom is equivalent to defaults hjl vjt.

          x [float]
          y [float]
               These are included mainly for backward compatabil-
               ity to earlier versions of jgraph.  Setting x and
               y is equivalent to ``defaults x float y float hjl

               This lets the user control where each individual
               legend entry goes.   The values of the defaults
               fields are ignored, and instead, the values of the
               curve's labels are used.  All justifications have
               defined results, except for hjc.  Similarly, rota-
               tion other than 0  is likely to produce bad

          These are more advanced commands for editing an axis.
          This includes drawing explicit hash marks and labels,
          moving the hash marks, axes, and labels, not drawing
          the hash marks, labels, axes, etc.

          gray [float]
          color [float float float]
               These specify either the grayness of the axis or
               its color.   Values for gray should be from 0
               (black) to 1 (white).   Values for color should
               also be from 0  to 1.  They are RGB values, and
               thus define the amount of red, green and blue in
               the axis respectively.  Specifying color nullifies
               the gray value, and vice versa.   The default is
               gray 0.   These values affect every part of the
               axis:  the label, the hash marks and labels, the
               axis line and the grid lines.

          grid_gray [float]
          grid_color [float float float]
          mgrid_gray [float]
          mgrid_color [float float float]
               These allow the user to define the grayness or
               color of the gridlines and the mgridlines to be
               different from those of the axis lines.   The
               default grid_gray and grid_color is the same as
               the axis's gray and color.  The default mgrid_gray
               and mgrid_color is the same as grid_gray and

          hash_at [float]
               Draw a hash mark at this point.  No label is made
               for this hash mark.

          mhash_at [float]
               Draw a minor hash mark at this point.

               Edit a hash label (see HASH  LABEL  EDITING  COM-

               Edit the default characteristics of the hash
               labels.  This is so that the user can change the
               fontsize, justification, etc., of the hash labels.
               Editing hash_labels is just like editing normal
               labels (see LABEL EDITING COMMANDS), except that
               the :, x, and y values are all ignored. Defaults
               for hash labels are as follows:   Fontsize=9,
               Font=``Times-Roman'', Justification is dependent
               on whether it is the x or y axis and whether
               hash_scale is positive or negative.

          hash_scale [float]
               This is to change the size and orientation of the
               hash marks.   Default =  -1.0.  Changing this to
               -2.0 will double the length of the hash marks.
               Changing this to +1.0  will make the hash marks
               come above or to the right of the axis.

          draw_hash_marks_at [float]
               By default, the hash marks are drawn either above
               or below the axis.   This command changes where
               they are drawn.  Hash_scale still determines
               whether they are drawn above or below this point,
               and their size.

          draw_hash_labels_at [float]
               By default, the hash labels are drawn either above
               or below the hash marks (again, this is dependent
               on hash_scale).  This command changes where they
               are drawn.  Justification and fontsize, etc., can
               be changed with the hash_labels command.

               This toggles whether or not jgraph will automati-
               cally create hash marks according to hash, mhash
               and shash (or log_base and mhash for logarithmic
               axes). The default is auto_hash_marks.

               This toggles whether or not jgraph will automati-
               cally create hash labels for the auto_hash_marks.
               Default = auto_hash_labels.

               This toggles whether or not the axis line is
               drawn.  Default = draw_axis.

               This toggles whether or not the axis label (as
               editted by the label command) is drawn.  Default =

               This toggles whether or not the hash marks (both
               automatic and those created with hash_at and
               mhash_at) are drawn.  Default = draw_hash_marks.

               This toggles whether or not the hash labels are
               drawn.  Default = draw_hash_labels.

          Hash labels are simply strings printed along the
          appropriate axis.   As a default, they are printed at
          the place denoted by the most recent hash_at or
          mhash_at for this axis, but this can be changed by the
          at command.  If there has been no hash_at or mhash_at,
          then an at command must be given, or there will be an
          error.  Hash editing terminates when either one of
          these commands is not given.

          : {string}
               This sets the string of the hash label (see
               Strings above under THE DESCRIPTION LANGUAGE).

          at [float]
               This sets the location of the hash label along the
               current axis.

     Although jgraph doesn't have any built-in functions for
     interpolation or function plotting, both can be effected in
     jgraph with a little outside help:

     Function plotting
          With the include and shell statement, it's easy to
          create a file of points of a function with a c or awk
          program, and include it into a graph.  See the section
          HINTS  AND EXAMPLE GRAPHS for an example of a sin graph
          produced in this manner.

     Point interpolation
          Point interpolation is essentially the same as function
          plotting, and therefore is left out of jgraph. The UNIX
          spline(1) routine is a simple way to get interpolation
          between points.  See bailey.jgr described below.  Maybe
          in a future release.

     Jgraph should be able to draw any kind of scatter/line/bar
     graph that a user desires.   To embellish the graph with
     extra text, axes, lines, etc., it is helpful to use copy-
     graph.   The following example graphs show a few examples of
     different features of jgraph.  They should be in the direc-
     tory JGRAPH_DIR.

     - acc.jgr is a simple bar graph.  Acc.tex is also included
     to show how one can include the output of jgraph in a LaTeX
     file.  To get this to work, you might have to substitute the
     entire pathname of the file acc.jps in the acc.tex file.

     - g8.jgr is a simple graph with some plotted text.   -
     g8col.jgr shows how to produce a color background -- it is
       the same as g8.jgr only all on a yellow background.   -
     ebars.jgr is a simple graph with error bars.  - sin.jgr
     shows how a sin function can be plotted using a simple c
     program to produce the sin wave.  Moreover, this file shows
     a use of copygraph to plot an extra x and y axis at the 0

     - sin1.jgr is a further extension of sin.jgr only with one x
     and y axis at 0, but with the axis labels at the left and
     the bottom of the graph.

     - sin2.jgr is a different sin wave with a logarithmic x

     - sin3.jgr shows how a bizarre effect can be gotten by sort-
     ing the points in a different manner.

     - bailey.jgr shows how to use the UNIX spline(1) routine to
     get interpolation between points.

     - gpaper.jgr shows how you can get jgraph to easily produce
     graph paper.

     - g9n10.jgr contains two graphs with complicated legends.
     It contains a description of how the legend was created.

     - ex1.jgr and ex2.jgr are two examples which were figures 1
     and two in an extended abstract for a paper about jgraph.

     - mab2.jgr is a graph created by Matt Blaze which shows how
     a complicated output graph can be quite concisely and simply
     stated.  In this graph, the x axis is a time line.  It shows
     usage of the hash_label and hash_labels commands, as well as
     displaying how jgraph lets you extract data from output
     files with awk.

     - nr.jgr is an example of a rather complicated bar graph
     with stripe-filled bars.  It was created by Norman Ramsey.

     - hypercube.jgr shows an interesting use of jgraph for

     - ad.jgr is an example which shows how one can include
     jgraph output as jgraph input.  The file uses the eps token
     to include cube.jgr, a jgraph drawing of an Intel hypercube,
     and disk.jgr, a jgraph drawing of a disk, in a picture.

     - alb.jgr is another use of jgraph for picture drawing.
     This file was created by an awk script which Adam Buchsbaum
     wrote to draw trees and graphs.

     - wortman.jgr is a neat graph of processor utilization writ-
     ten by Dave Wortman for SIGPLAN '92.  It was created by an
     awk script, which processed the data and emitted the jgraph.

     To view these graphs, use jgraph -P, and view the resulting
     output file with gs, or a similar postscript viewer.  To
     make a hard copy of these graphs, pipe the output of jgraph
     -P directly to lpr.

     As hypercube.jgr and alb.jgr show, jgraph can be used as a
     postscript preprocessor to make drawings.  There are two
     advantages using jgraph to draw pictures instead of using
     standard drawing tools like xfig, figtool, or idraw.  The
     first is that with jgraph, you know exactly where strings,
     lines, boxes, etc, will end up, because you plot them expli-
     citly.  The second advantage is that for iterative drawings,
     with lots of patters, you can combine jgraph with awk or c
     or any other programming language to get complex output in a
     simple way.   Most what-you-see-is-what-you-get (WYSIWYG)
     drawing tools cannot do this.

     The major disadvantage of using jgraph to draw pictures is
     that jgraph is not WYSIWYG.  You have to set up axes and
     plot points, lines and strings.  It's all a matter of taste.

     If you'd like to see some more complex pictures drawn with
     jgraph, as well as some hints to make picture-drawing
     easier, send me email (

     I haven't read the manuals, but the way I've been loading
     these files into LaTeX has been as follows:

     1.  Toward the beginning of my LaTeX file, I've had ``\input{psfig}''
     2.  Where I've wanted my file, I've put:


         Some versions of dvips or dvi2ps work without the path-name.  Others
         require that the path-name be present.

     3.  After running latex on the file, do

         lpr -d file.dvi

     4.  If that doesn't work, try dvips-ing the file and printing the postscript.

     Logarithmic axes cannot contain points <=  0.   If I  have
     enough complaints to convince me that this is a bug, I'll
     try to fix it.

     There is no real way to make the axes such that they
     decrease from left to right or low to high -- or at least
     not without writing your own hash labels.

     There may well be loads of other bugs.    Send to