PC World Komputer 1996 February/PCWK0296.iso/sharewar/os2/grafika/splot/splot.hlp

Text File | 1994-07-28 | 46.3 KB | 1,766 lines

<general>

    To plot a figure load a .spt file.
 For example:

 <esc> edit demo\logaxes.spt

 then hit CTRL G or 'exec' button.

    The next section explains how to
 use the mouse. For help with the
 editor or specific functions use the
 'edit ?' or 'func ?' buttons at the
 bottom.

 Using The Mouse

    Pressing the left mouse button
 with the mouse on the drawing page
 inserts the current x,y coordinates
 into the text file at the current text
 cursor location. If the mouse cursor
 is in the text region then hitting the
 left mouse button will move the
 current text cursor to the mouse
 cursor location. The left mouse button
 is also used to select items in drop
 down menus as well as to activate an
 action associated with mouse buttons
 along the periphery of the display.

    The right mouse button is used for
 highlighting elements of a drawing. If
 the mouse cursor is on top of a
 displayed element on the drawing page
 and the right mouse button is hit then
 the corresponding element is
 highlighted in intense white and the
 text cursor jumps to the corresponding
 line in the text that generated that
 element. Conversely, if the mouse
 cursor is on the text side hitting the
 right mouse button will highlight any
 graphics elements generated by the
 line under the mouse cursor. This
 feature is very useful for finding the
 code associated with a particular
 element of a drawing or the reverse.
 For the pull down selection lists the
 right mouse button (or the <esc> key)
 closes the menu without making a
 selection.

    When the mouse cursor is on the
 drawing page the current coordinates
 are printed on the bottom. The units
 and origin used are those in effect at
 the end of the last program execution.
 The default units are cm with the
 origin in the bottom left corner of
 the page. Pressing the middle mouse
 button (or both the left and right
 mouse buttons together on two button
 mice) with the mouse pointer on the
 drawing page causes the current
 coordinate reference point to be reset
 so that the current coordinate line
 subsequently reports the distance from
 this point. The coordinate reference
 point is also relevant to the zoom
 in/out mouse buttons. Zooms are done
 in such a manner that the coordinate
 reference point remains in the same
 location on the screen. While in a
 pull down menu the middle mouse button
 gets help for the item under the
 cursor if any exists.


    Actions associated with the mouse
 buttons

    There are several mouse buttons
 along the top and sides of the
 display. The action of these buttons
 is as follows. Starting at the left
 top there are four buttons labelled
 'draw', 'sopt', 'misc' and 'keyw'.
 These activate drop down menus which
 allow a function to be selected and
 inserted into the text. The 'draw'
 functions are a suite of drawing
 routines which cause lines, arcs, text
 etc. to be drawn to the page. The
 'sopt' menu is a list of textual names
 for numerical constants which are used
 in conjunction with the set(); command
 to change attributes of the current
 graphics state such as the current
 colour, line width, line style, axes
 type, etc. Choosing set from the list
 of drawing functions automatically
 opens a menu with only an appropriate
 subset of these and is the recommended
 approach. The 'misc' button allows
 selection of a standard C library
 function. Most of these are math
 functions such as sin() and will not
 be required for making ordinary plots.
 They are however useful for
 manipulating data before plotting or
 generating data mathematically all
 from within Splot. The last button of
 this group 'keyw' opens a list of C
 keywords for selection. The only one
 of these that is of interest for
 ordinary plots is 'main'. Every file
 that generates a plot or drawing must
 start with

 #include splot.h
 main
    {
    /* list of drawing commands go
    here between the braces on as many*/
    /* lines as necessary */
    }

    This is all automatically inserted
 in the text by selecting 'main'. The
 remaining keywords in this list are
 only of interest when constructing
 loops or branches.

    The next set of buttons along the
 top are concerned with displaying the
 drawing. The default size of the
 drawing is one which fits on a
 standard 8 x 11 inch piece of paper if
 printed. However, as the screen
 resolution is not as good as that of
 printers it is possible to zoom in on
 part of a drawing in order to get a
 better view. The 'zmin' button
 accomplishes this. The scale is
 increased by a factor of two and
 positioned so that the current
 reference point remains in the same
 location. The current reference point
 is set with the middle mouse button as
 described above. The 'zout' button
 reverses this process. Zooms are
 cumulative and thus it is possible to
 hit each button more than once to go
 to even larger magnifications. The
 next button is a pan button with four
 sub fields within it allowing the
 displayed drawing to be shifted by
 half a page in the indicated
 direction.

    The next two buttons are labelled
 'rset' and 'rdrw'. The 'rset' button
 erases the current drawing and resets
 the graphics state to its initial
 default value. The 'rdrw' button just
 redraws the screen with the current
 set of graphics elements (This is not
 of much use yet but will be in a
 future version).

    The next buttons to the right are
 essentially editor functions which
 have an associated mouse button. As
 such they all have key board keys
 which accomplish the same thing. The
 'exec' (same as CTRL G) button causes
 the current file to be executed and
 the result displayed. The 'quit'
 button (CTRL Q) removes the current
 file. The 'file' button opens a drop
 down menu containing several editor
 commands associated with files. These
 include 'load', 'save', 'quit' ,
 'rename', 'next', 'prev'. Some of
 these choices are duplicates of ones
 directly accessible from the menu bar.
 writes the current file to disk. The
 'next' button makes the next file
 within memory if any the current one
 to be displayed in the text window.
 Lastly, the 'undo' button (CTRL U)
 reverses the last editing operation
 performed on a line in the file. It is
 possible to step back step by step
 undoing previous changes.

    There are some buttons along the
 right side of the text window. These
 serve to scroll the text up a page at
 a time or go to the top or bottom of a
 file. These also have key pad
 equivalents in <PgUp>, <PgDn>, <CTRL
 PgUp> and <CTRL PgDn>. Along the
 bottom there are also some
 corresponding horizontal scrolling
 buttons with the key pad equivalents
 <Home> and <End>.

    At the bottom there are three
 buttons associated with getting on
 line help. The button 'edit?' is used
 to bring up the editor help file.
 Positioning the text cursor underneath
 a function name and then selecting
 'func?' with the mouse causes the
 corresponding help text to be loaded
 in to the editor. The help text for
 each function will include a brief
 explanation of its action as well as a
 list of required parameters for it.
 The button labelled 'data?' is used to
 print the value of a global variable.
 Again the text cursor must first be
 positioned underneath the variable of
 interest. If the variable is an array
 then the entire contents is put into a
 file for viewing and the max and min
 of each column is calculated. These
 values can be very useful for picking
 the scale factors and end points of a
 data plot.

    Finally beside the coordinate
 display there are two buttons
 associated with the coordinate format.
 The one labelled 'delt' toggles
 relative coordinates on and off. If
 off then the absolute coordinates are
 displayed otherwise the x an y
 distances from the last reference
 point is displayed (See above for how
 to set a reference point). The button
 labelled 'cmat' toggles coordinate
 matching on and off. If on then the
 page coordinate system is set so as to
 match the internal coordinates used
 for the last 'axes_box();'. Thus this
 button is only meaningful if an axes
 box has been put down previously.

<abs>
 int abs(int i);

 Returns the absolute value of i;

<acos>
 double acos(double x);

 Returns the arc cosine of the value
 x. x must be between -1 and 1.
 Returns a value between 0 and pi.

<asin>
 double asin(double x);

 Returns the arc sine of the value x.
 x must be between -1 and 1. Returns
 a value between -pi/2 and pi/2.

<atan>
 double atan(double x);

 Returns the arc tangent of the value
 x. Returns a value between -pi/2 and
 pi/2.

<atan2>
 double atan2(double y,double x);

 Returns the arc tangent of the value
 y/x. Returns a value between -pi and
 pi.

<atoi>
 int atoi(char *str);

 Converts a string to an integer. The
 string must contain only digits.

<atof>
 double atof(char *str);

 Converts a string to a double. The
 string must contain only digits and
 'e', 'E', '.', '-' and '+' .

<ceil>
 double ceil(double x);

 Rounds up x to nearest integer value.

<cos>
 double cos(double x);

 Returns the cosine of x. x is specified
 in degrees.

<exit>
 void exit(int status);

 Terminates the execution of the
 program. If the status is 0 then it
 will be considered a normal exit
 otherwise an error induced exit.

<exp>
 double exp(double x);

 Calculates the exponential function
 e^x.

<fabs>
 double fabs(double x);

 Returns the absolute value of x. It is
 like abs() but works with floating
 point numbers rather than integers.

<floor>
 double floor(double x);

 Rounds down x to the nearest integer.

<fmod>
 double fmod(double x,double y);

 Returns the remainder of x/y.

<free>
 void free(char *ptr);

 Frees the block of memory pointed to
 by ptr. The memory must have been
 previously allocated using malloc().

<log>
 double log(double x);

 Returns the natural log of x.

<log10>
 double log10(double x);

 Returns the log base 10 of x.

<malloc>
 char *malloc(int size);

 Allocates a block of memory of size
 bytes and returns a pointer to the
 block. malloc returns NULL if there
 is insufficient free memory.

<pow>
 double pow(double x,double y);

 Calculates x to the power y.

<puts>
 int puts(char *str);

 This routine writes the string str
 to the output file and starts a new
 line.

<printf>
 int printf(char *format,...);

 Prints the formatted data to the
 output file. The format string
 specifies the type and number of
 values to print. Some common
 examples include:

 printf("i = %d",i); prints the
 integer value i.

 printf("x = %g",x); prints the
 floating point value x.

 printf("text = %s",str); prints the
 string str.

 Multiple values can be printed as in
 printf("%d %d %g %s",i,j,x,str);

 The format specifiers can also
 include field width information and
 justification etc. Consult a
 standard C text for more details.

<print>
 void print(v,...);

 Prints the value v which can be of
 any scalar type. i.e int, char,
 float, double or a pointer. This is
 not a function found in the standard
 C library.

<sin>
 double sin(double x);

 Returns the sine of x. x must be
 specified in degrees.

<sqrt>
 double sqrt(double x);

 Calculates the square root of x.
 x must be a positive number.

<sizeof>
 int sizeof(t);

 Returns the number of bytes required
 to store the value of type t.

<sprintf>
 int sprintf(char str,char
     *format,...);

 Prints the formatted data to the
 string str. The format string
 specifies the type and number of
 values to print. Some common
 examples include:

 printf("i = %d",i); prints the
 integer value i.

 printf("x = %g",x); prints the
 floating point value x.

 printf("text = %s",str); prints the
 string str.

 Multiple values can be printed as in
 printf("%d %d %g %s",i,j,x,str);

 The format specifiers can also
 include field width information and
 justification etc. Consult a
 standard C text for more details.

<strcat>
 void strcat(char *dest, char
      *source);

 Concatenates the string source to
 the string dest.

<strcpy>
 void strcpy(char *dest, char
      *source);

 Copies the string source to the
 string dest.

<strlen>
 int strlen(char *str);

 Returns the length of the string
 str.

<tan>
 double tan(double x);

 Calculates the value of the tangent
 of x. x should be specified in
 degrees.

<abox>
 void abox(double xsi, double
       ysi, double xorig,
       double yorig);

    Adds an axes box to the current
 path. The box is drawn with a size of
 xsi by ysi and centered on the page.
 No internal coordinate system is set
 up. Use ascale() for this or use
 axes_box() to combine both functions.
 The last two parameters are optional
 and if present specify the position
 of the axes origin relative to the
 page origin. For the last two
 parameters the special constants
 XCENTER and YCENTER can be used for
 the x or y position coordinate
 respectively and will cause
 the axes box to be centered on the
 page along that axis. Using both
 XCENTER and YCENTER is equivalent to
 the default behaviour with the last
 two parameters absent.

<alineto>
 void alineto(double len, double
     ang);

 Adds a line of length len at an
 angle of ang with respect to the
 previous line to the current path.
 Generates an error if there is no
 previous line in the current path.

<arc>
 void arc(double xcen, double ycen,
 double rad, double alpha, double
 beta);

 Adds a circular arc of radius rad
 centered at (xcen, ycen) to the
 current path. The starting angle is
 alpha and the stopping angle is
 beta. The arc is drawn in the
 counter clockwise direction. A
 straight line section will be added
 from the previous current point if
 any to the starting point of the
 arc.

<arcn>
 void arcn(double xcen, double ycen,
 double rad, double alpha, double
 beta);

 Adds a circular arc of radius rad
 centered at (xcen, ycen) to the
 current path. The starting angle is
 alpha and the stopping angle is
 beta. The arc is drawn in the
 clockwise direction. A straight line
 section will be added from the
 previous current point if any to the
 starting point of the arc. Exactly
 as arc() but draws the arc in the
 opposite direction.

<arcto>
 void arcto(double x1, double y1,
 double x2, double y2, double rad);

 Adds a circular arc of radius rad to
 the current path. The center and
 angles are chosen so that the arc is
 tangent to the line formed by
 (x1,y1) and the current point at its
 start and tangent to the line
 (x1,y1) - (x2,y2) at its end point.
 A straight line segment is added
 from the current point to the start
 of the arc. An error is generated is
 there is no current point.

<arrowto>
 void arrowto(double
 x,double y,...);

 Adds a line segment to the current
 path from the current point to
 (x,y). The line is terminated by
 drawing an arrow head oriented in
 the direction of the line. More than
 one coordinate point can be
 specified in the command in which
 case a series of line segments
 terminated by arrows connecting the
 points will be added to the current
 path. If there is no current point
 then an error will be generated.

<ascale>
 void ascale(int axes, double xstart,
       double ystart, double xend,
       double yend);

  or

 void ascale(int axes, double *data,
     int col,...);

 An internal coordinate system is set
 up for subsequent plotting of data
 within the existing axes box. The x
 axis start and stop values are xstart
 and xend respectively and ystart, yend
 for the y axis. for the y axis. If the
 axis choice is XAXES or YAXES rather
 than XYAXES then only two numbers
 follow the axes specifier rather than
 four. This allows the x and y axes
 scales to be set indendently of each
 other.
 The alternate format allows for auto
 scaling to the specified data. There
 can be more than one data array in the
 list in which case the scales are
 choosen so that they will all fit.
 Each data array can optionally be
 followed by one or two integers
 specifying which columns to use
 for the x and y values. If axes
 is not XYAXES only one integer is
 allowed.

<axes_box>
 void axes_box(double xsi, double
       ysi, double xstart, double
       ystart, double xend,
       double yend,double xorig,
       double yorig);

    Adds an axes box to the current
 path. The box is drawn with a size of
 xsi by ysi and centered on the page.
 An internal coordinate system is set
 up for subsequent plotting of data
 within the box. The x axis start and
 stop values are xstart and xend
 respectively and ystart, yend for the
 y axis. for the y axis. The last two
 parameters are optional and if present
 specify the position of the axes
 origin relative to the page origin.
 For the last two parameters the
 special constants XCENTER and YCENTER
 can be used for the x or y position
 coordinate respectively and will cause
 the axes box to be centered on the
 page along that axis. Using both
 XCENTER and YCENTER is equivalent to
 the default behaviour with the last
 two parameters absent.

<box>
 void box(double x1, double y1,
      double x2, double y2);

 Adds a box to the current path. The
 two end points of the box are
 (x1,y1) and (x2,y2);

<clear>
 void clear();

 Clears the screen when the program
 is executed.

<clip>
 void clip()

 Converts the currently defined path
 into a clipping path. All subsequent
 drawing operations are then clipped
 against this path and only portions
 of the drawing on the inside of the
 clip path are displayed. What is
 inside and what is outside depends
 on whether even-odd or non-zero wind
 has been selected as the fill rule
 using a set(); If the current path
 is not closed then the current path
 is first closed. If there is no
 current path an error is generated.
 Clip() is implicitly stroked and
 takes effect immediately.

<closepath>
 void closepath();

 Closes the current path. A straight
 line segment is added from the
 current point to the start of the
 current path as set by the moveto()
 of rmoveto() command at the
 beginning of the path definition.
 Generates an error if there is no
 current point.

<cmatch>
 void cmatch(int on);

 If the passed parameter is TRUE then
 it does the necessary translations and
 scaling so that the coordinate system
 for the page matches that used within
 the axes_box. An error is generated if
 there is no current axes_box. The
 font scale is compensated automatically
 for the change in coordinate system so
 that characters will still be the same
 size as before. If the parameter is
 FALSE then the previous unmatched
 coordinates will be restored. If there
 is no parameter TRUE is assumed.

<curveto>
 void curveto(double x1, double y1,
         double x2, double y2,
         double x3, double y3);

 Adds a Bezier curve section to the
 current path starting at the current
 point. The curve starts tangent to
 (xcur,ycur) - (x1,x2) and ends
 tangential to (x2,y2) - (x3,y3) at
 (x3,y3) An error is generated
 if there is no current point.

<drawdata>
 void drawdata(double *data, int xcol,
        int ycol);

 Draws the data contained in the
 array data in the current axes_box.
 The numbers xcol and ycol are the
 columns of the array data that are
 to be used for the x-axis and y-axis
 data respectively. Each row of the
 array data represents one coordinate
 point to be plotted. The values will
 be plotted using the internal
 coordinate system established by the
 the call to axes_box. If there is no
 current axes box an error will be
 generated. The xcol and ycol params
 are optional. If no values are given
 then xcol = 0 and ycol = 1 are
 assumed.

<errorbars>
void errorbars(int axes,double *data,
     int xcol, int ycol, int errcol);

    Draws error bars for the data
points in the array "data". The first
parameter is either XVALS or YVALS
indicating along which axes the error
bars are to be drawn. The numbers xcol
and ycol are the columns of the array
data that are to be used for the x-axis
and y-axis data respectively. Each row
of the array data represents one
coordinate point to be plotted. The
values will be plotted using the
internal coordinate system established
by the the call to axes_box. The last
parameter "errcol" is the column of the
array "data" which holds the size of
the error for the corresponding data
point in the same row. If there is no
current axes box an error will be
generated.

<fill>
 void fill();

 Closes the current path if not
 already closed and fills the
 interior region with the current
 colour as specified by the last
 set() call. What is inside and what
 is outside the path depends on the
 currently chosen fill rule. The fill
 rule is either even-odd or non-zero
 wind (the default) and is specified
 using a set() call. An error is
 generated if there is no current
 path.

<fitline>
 void fitline(double *data, int xcol,
  int ycol,double *yint,double *slope);

   Fits the best straight line to the
 data in the array "data" using the
 column xcol of the array as the x
 values and the column ycol as the
 corresponding y values. The best line
 is drawn constrained to the current
 axes box. If there is no current axes
 box an error is generated. The last
 two parameters are the returned values
 giving the y intercept and slope of
 the fitted line. Note that they are
 pointers to doubles which must be
 declared at the top of the program.
 Given a declaration of the form:

     double slope,yint;

 Call fitline using:

     fitline(data,0,1,&yiny,&slope);

 Assuming that the first and second
 column of data are the x and y values
 respectively.
 Data points can be excluded from the
 fit by using the set(XRANGE,xmin,xmax);
 or set(YRANGE,ymin,ymax); commands.
 Only data points within the limits will
 be used for the fit.

<get>
 int or double get(int option,
    char *str);

 Returns the value of the specified
 option in the current graphics state.
 The numerical value for single valued
 elements is returned by the function
 otherwise the return value is 0. A
 text representation of the value is
 optionally returned in str. If used,
 be sure to allocate a character array
 with sufficient space for str before
 calling this function. The valid option
 values are deined in splot.h. See also
 set() for a description of the various
 options. The returned string can be
 printed using the command puts(str);
 in the program where "str" is the
 name of the array in the call to get().
 Returned numerical values can be
 printed using print(value);
 The second array parameter is optional
 and is only really needed for getting
 options that are more than just a single
 value such as line patterns.

<grestore>
 void grestore();

 Pops a graphics state off the state
 stack thereby restoring the graphics
 state that was in effect at the time
 the matching gsave() was executed.
 In particular the path, the
 clip_path, the line styles, line
 colours etc. are restored to their
 previous values.

<gsave>
 void gsave();

 Pushes the current graphics state
 onto the state stack. The current
 path, clip path, line style, colour
 etc are saved so that they can be
 restored later using a grestore()
 command.

<label>
 void label(int axis, char *label);

 Add labels to the axes box
 previously defined. The first
 parameter is which axis to label
 either BOTTOM, TOP, LEFT or RIGHT.
 The following parameter is the label
 to be printed. The label will be
 printed centered between the
 appropriate edges of the current
 axes_box. An error is generated if
 there is no current axes_box.


<lineto>
 void lineto(double x,double y,...);

 Adds a line segment to the current
 path from the current point to
 (x,y). More than one coordinate
 point can be specified in the
 command in which case a series of
 line segments connecting the points
 will be added to the current path.
 If there is no current point then an
 error will be generated.

<moveto>
 void moveto(double x, double y);

 Sets the current point to (x,y).
 Also sets the path close point to
 (x,y) for subsequent use with
 closepath(). Many path building
 commands such as curveto and lineto
 require that a current point exist
 before calling them.

<newpath>
 void newpath();

 Resets the current path to NULL and
 also causes the current point to be
 undefined. Furthermore, it turns off
 the implicit stroking of elements
 that are normally implicitly stroked
 such as text();. Thus using newpath();
 these elements can be added to a path
 which must then be explicitly stroked.
 stroke() turns on implicit stroking
 again.

<plotdata>
 void plotdata(double *data, int xcol,
           int ycol);

 Plots the data found in array data
 in a box. This command chooses the
 scale sizes tick marks etc. to
 display the data which is assumed to
 be in order of monotonically
 increasing or decreasing x value
 order. The parameters xcol and ycol
 specify which columns of the array
 data to use for the x and y values
 respectively. The xcol and ycol params
 are optional. If no values are given
 then xcol = 0 and ycol = 1 are
 assumed. If the default choices of
 plotdata are not acceptable a plot
 can be generated using the step by
 step method using axes_box(),
 tickmarks(), ticklabels() and
 drawdata(). The data must first be
 read in to array data using
 readdata().

<rarrowto>
 void rarrowto(double x,
           double y,...);

 Adds a line segment to the current
 path from the current point to the
 current point plus x, y. The line is
 terminated by drawing an arrow head
 oriented in the direction of the
 line. This command is identical to
 arrowto except that the displacement
 is specified relative to the current
 point. More than one coordinate
 point can be specified in the
 command in which case a series of
 line segments terminated by arrows
 connecting the points will be added
 to the current path. If there is no
 current point then an error will be
 generated.

<reset>
 void reset();

 Restores all setable parameters to
 their default values. Clears the
 current path and clip path.

<rlineto>
 void rlineto(double x,double y,...);

 Adds a line segment to the current
 path from the current point to the
 current point plus x, y. This
 command is identical to lineto
 except that the displacement is
 specified relative to the current
 point. More than one coordinate
 point can be specified in the
 command in which case a series of
 line segments connecting the points
 will be added to the current path.
 If there is no current point then an
 error will be generated.

<rmoveto>
 void rmoveto(double x, double y);

 Sets the current point to the
 current point plus x,y. This command
 is the same as moveto except that a
 relative move is specified. It also
 sets the path close point for
 subsequent use with closepath().
 Many path building commands such as
 curveto and lineto require that a
 current point exist before calling
 them.

<rotate>
 void rotate(double ang);

 Rotates the figure about the
 current origin by the the angle
 specified. The angle units are
 degrees and the +ve direction
 is counterclockwise.
 Changes in rotation are cumulative.

<scale>
 void scale(double xs, double ys);

 Changes the scale of the figure
 by the factors specified for
 the x and y axes respectively.
 Changes in scale are cumulative.

<set>
 void set(int option, ...);

 All setable parameters can be set
 using the set command. The first
 parameter specifies which option to
 set. The defined constants
 corresponding to valid options are
 defined in the header file splot.h.
 What follows is a very brief
 description of all the values
 setable using set().

 set(AXESCLIP,val);
 If val is ON then the data values are
 clipped to the limits of the axes box.
 This is temporarily added to the user
 set clip limits if any. If val is OFF
 (the default) then the user specified
 clip limits from the last clip() call
 are used. Alternatively the range
 of data values plotted can be set
 using set(XRANGE,...); or
 set(YRANGE,...); .

 set(AXESTYPE,val);
 Axestype may be one of the following.
 LINEAR (the default), LOGX, LOGY,
 LOGLOG, INVX, INVY, INVINV, INVXLOGY
 or LOGXINVY. The position of data
 points and tickmarks are automatically
 adjusted to account for the axes type.

 set(CURSYMBOL,sym);
 Sets the symbol to use when plotting
 data with symbols. sym nust be one
 of OCIRCLE, OSQUARE, OTRIANGLE ,
 ODIAMOND OSTAR, OARROW, PLUS, CROSS,
 MULT, CIRCLE, SQUARE, TRIANGLE,
 DIAMOND, STAR, or ARROW. The default
 symbol is CIRCLE. The size of a symbol
 can be changed using set(FONTWIDTH,
 val_in_cm); since symbols are just a
 special font. The size relative to
 the current FONTWIDTH can be set
 using set(SYMMULT,mult);.

 set(FILLRULE,type);
 Determines the rule to be used when
 filling a path. Type must be one of
 NONZWIND (default) or EVENODD.

 set(FLATNESS,num);
 Sets the maximum allowable error in
 pixels when converting a curve to a
 set of straight line segments.
 Smaller values of num give smother
 curves but take longer to process.
 The default value of num is 1.

 set(FONT,fonttype);
 Sets the font type to use for
 subsequent text written using the
 text(); routine. fontname type be
 either SIMPLEX (default) or COMPLEX.

 set(FONTASPECT,asp);
 Sets the ratio of the gyph height to
 width used for text written using
 text();. The default value is 2.0

 set(FONTDIR,angle);
 Sets the rotation angle with respect
 to the x axis to use when writting
 text using text(); The default is
 0.

 set(FONTMULT,factor);
 Multiplies the current font size by
 the given factor.

 set(FONTWIDTH,wid);
 Sets the average width of the
 characters written using text(). The
 default value is 0.7 cm. FONTWIDTH
 applies also to symbols.

 set(LABELMARG,val);
 Sets the additional margin between
 the axes box and the labels. The
 default is 0.0 cm.

 set(LINECAP,type);
 Determines how thick lines are to be
 terminated. The allowed types are
 BUTTCAP (default), ROUNDCAP and
 PROJCAP.

 set(LINECOLOUR,col);
 Where col is one of INVIS, BLACK, BLUE,
 GREEN CYAN, RED, MAGENTA, BROWN or
 WHITE. This set the colour to use
 when the current path is stroked or
 filled. The default colour is BLACK
 with the background WHITE.

 set(LINEJOIN,type);
 Determines how thick lines are
 joined together. The allowed join
 types are MITERJOIN (default),
 BEVELJOIN and ROUNDJOIN.

 set(LINESTYLE,pattern,...);
 Sets the line style to use for the
 path when it is stroked. The
 constant LINESTYLE is followed by a
 list of floating point values that
 define the pattern. The values are
 interpreted as the length along the
 path that the line is visible
 followed by the length that it is
 invisible as an alternating sequence
 wrapping back to the beginning when
 the pattern reaches the end. For
 example a pattern of 1.0,1.0 implies
 on for 1 cm follwed by off for 1 cm.
 A pattern of 1.0,0.5 is on for 1 cm
 followed by off for 0.5 cm. The
 predefined patterns are: SOLID 0
 (default) DASHED 1.0,0.5 DOTTED 0.2,
 0.2 and DOTDASH 1.0,0.5,0.2,0.5.
 There must always be an even number
 of comma separated values in a
 pattern definition.

 set(LINEWIDTH,width);
 Sets the linewidth to width cm
 (default 0.05 cm). This linewidth is
 used when the current path is
 stroked.

 set(MITERLIMIT,maxratio);
 Sets the maximum length of spikes
 formed by miter joining two lines at
 an acute angle. If the ratio of the
 length of the spike to the width
 exceeds the value of maxratio then a
 BEVELJOIN is done instead. The
 default value is 10.0.

 set(PAGEROT,flag);
 Selects landscape orientation if
 flag is ON. Default is portrait.

 set(PATTOFF,offset);
 Sets the offset into the current
 LINESTYLE pattern. Can be used to
 adjust the starting point of a
 pattern for aesthetic reasons.

 set(PLOTTYPE,type);
 Sets the current plot type. type
 must be one of LINES (default),
 SYMBOLS or SYM_LINES. LINES connects
 data points with line segments while
 SYMBOLS causes the current symbol to
 be drawn at each data point.
 SYM_LINES does both. The size of a
 symbol can be changed using
 set(FONTWIDTH, val_in_cm); since
 symbols are just a special font.
 The size relative to the current
 FONTWIDTH can be set using
 set(SYMMULT,mult);.

 set(SCALEALL,val);
 If val is ON then the XSHIFT, YSHIFT,
 XMULT, YMULT values are applied to
 all coordinates (ie in lineto, moveto
 etc.). The default is OFF in which
 case only data plotted using plotdata
 or drawdata is affected by these
 values.


 set(SCRIPTSCALE,val);
    Sets the relative height of a
 super/sub script as compared to
 ordinary text. The default value
 is 0.5.

 set(SCRIPTSHIFT,val);
 Sets the distance that a
 super/sub script is shifted above/below
 ordinary text. The value is specified
 as a fraction of the ordianry text
 height. The default value is 0.7.

 set(SYMMULT,val)
 Sets the symbol size multiplier
 used when drawing symbols. The default
 value is 1.0. The actual symbol size
 is determined the current FONTWIDTH
 multiplied by the curent SYMMULT
 value.

 set(TICKLENGTH,len);
 Sets the length of axis tick marks
 to be used. The default value is 0.3
 cm.

 set(TICKLMARG,len);
 Sets the margin between the axes box
 and the tick labels. The default is
 0.0 cm.

 set(XMULT,xmul);
 Causes each x value to be multiplied
 by xmul before being plotted.

 set(XRANGE,xmin,ymin);
 data plotted using drawdata is const-
 rained to have x values between xmin
 and xmax. There is also a corresponding
 YRANGE set option. The default is no
 constraints. The values should be
 specified in user coordinates ie those
 established by the current axes_box.

 set(XSHIFT,xshft);
 Causes the value xshft to be added
 to all x values before plotting.

 set(YMULT,ymul);
 Causes each y value to be multiplied
 by ymul before being plotted.

 set(YSHIFT,yshft);
 Causes the value yshft to be added
 to all y values before plotting.


<showpage>
 void showpage();

 Transfers the marked page created in
 memory by the stroke and fill commands
 to the physical page. This is
 automatically done at the end of the
 file and thus this command is only
 needed if it is desirable to draw
 parts of the figure before the end
 of execution.

<stroke>
 void stroke();

 Marks the page in memory with the
 current path. The path coordinates
 are transformed using the current
 coordinate transformation matrix and
 the path is fleshed out using the
 current line width, style and colour
 in effect at the time of the stroke
 command.

<symbol>
 void symbol(double x, double y,
         int symbol_const);
 or

 void symbol(int symbol_const);

 Plots the symbol chosen by symbol_const
 at the point x,y. symbol_const must be
 one of OCIRCLE, OSQUARE, OTRIANGLE,
 ODIAMOND OSTAR, OARROW, PLUS, CROSS,
 MULT, CIRCLE, SQUARE, TRIANGLE,
 DIAMOND, STAR,or ARROW. If the point
 x,y is omitted the symbol is drawn at
 the current point as set by a previous
 moveto();. symbol() is not implicitly
 stroked so follow with a stroke();.
 The size of a symbol can be changed
 using set(FONTWIDTH, val_in_cm); since
 symbols are just a special font. The
 size relative to the current FONTWIDTH
 can be set using set(SYMMULT,mult);.

<readdata>
 void readdata(char * filename,
           double * data);

 Reads a file of name filename
 and puts the data into the array
 "data". The file should be in ASCII
 format with the x data in one column
 and the y data values next column(s).
 Any line containing non numeric
 characters or is blank will be
 considered a comment and ignored.
 WARNING! As an optimization data is
 only read from disk once. Subsequent
 executions use the stored data already
 in memory (except after a reset). This
 means that if you modify the array
 "data" after reading in values the
 next time the file is executed you
 will get strange results. Similarly
 if you reuse the same array for
 different plots in the same drawing
 you will have trouble. The motto is
 never change the values in the array
 "data".

<text>
  void text(double x, double y,
     char * str,int just);

    Adds the text string str to
 the current path starting at location
 (x,y). The current font, size and
 orientation as set using the set()
 command are used. Super/sub scripts
 can be entered as ^2^ and _2_
 respectively. Letters surrounded by
 '!' or '#' are printed in greek or
 italics respectively. For example !m!
 generates the greek lower case mu. The
 special charcters "^_!#$\" can be
 printed by preceeding them with \ as
 in \!. The combination \b back spaces
 by one character. Symbols may be
 included in the text string by
 enclosing them with $ as in $3$.
 If the starting x,y coordinates
 are omitted then the current string
 is positioned one line below the
 previous string added to the path
 using text(). The last parameter
 is the justification and must be one
 of LEFT, RIGHT or CENTER. This last
 parameter can be omitted in which case
 the default value of LEFT will be
 used.

<ticklabel>
 void ticklabel(int axis, double v,
        char *label,...);

    Add tick labels to the axes box
 previously defined. The first
 parameter is which axis to label
 either BOTTOM, TOP, LEFT or RIGHT. The
 following parameters are paired values
 giving the tick position in data
 coordinates as established by a prior
 call to axes_box() and the text string
 to be placed at that location. An
 error is generated if there is no
 current axes_box. There are several
 default posibilities. If
 'ticklabel();' is called without any
 parameters then if tick marks have
 been generated previously using
 'tickmarks();' then they will be
 selectively labelled along the left
 and bottom axes. If only an axis
 parameter is given then the
 corresponding axis tick marks if any
 will be labelled. If the axis
 parameter is followed by a list of
 numbers only those numbers will be
 assumed to be both the tick position
 and the desired label. If the numbers
 are paired with stirngs in the
 parameter list then the number will be
 used as the tick label position and
 the string will be used as the literal
 label.

<tickmarks>
 void tickmarks(int axis,
        double v,...);


    Add tick marks to the axes box
 previously defined. The first
 parameter is which axis either BOTTOM
 , TOP, LEFT, RIGHT ,XAXES or YAXES.
 The following numbers are the
 positions were tickmarks are to to be
 placed. The length of the ticks is set
 using a set(TICKLENGTH,val) command.
 The location of the ticks is specified
 in data coordinates as established by
 the prior call to axes_box(). An error
 is generated if there is no current
 axes_box. All the above parameters are
 optional. The default behaviour is as
 follows. If all parameters are omitted
 tick marks will be automatically
 generated for all axes. If only an
 axis specifier is given then tick
 marks will be generated for the
 corresponding axis or axes. In these
 cases 'tickmarks();' will try to find
 reasonable positions for a set of tick
 marks. If this default behaviour is
 unacceptable then the actual tick
 positions can be specified as a list
 of values following the axis
 specifier.

<translate>
 void translate(double tx, double ty);

 Translates the origin of the
 figure by the x and y distances
 specified. Translations are
 cumulative.

<whereis>
 void whereis(double *x,double *y);

 Returns the coordinates of the
 current point as set by the last
 moveto(), lineto() etc.

<break>
 C keyword

 Used to prematurely terminate a
 loop;

 Example:

 for (i = 0;i< 100; i++)
    {
    if (cond == 1) break;
    /* if cond == 1 break out of the
    loop regardless of the value of
    i and continue at end of loop. */
    }

<case>
 C keyword

 Used in conjunction with a switch to
 select one of a set of choices.

 Example:

  switch(code)
     {
     case 0:/* do something if code = 0*/
        break;
     case 1:/* do this if code = 1*/
        break;
     case 2:
     case 3:/* do this if code = 1 or 2*/
        break;
     default:/* do this if none of the
           above */
       break;
     }

<char>
 C keyword

 Used to allocate memory for a
 variable of size one byte. All
 chars are between -128 and 127.
 All variable declarations must
 be done outside of the main
 routine for globals or immediately
 after the function declaration for
 local variables.

 Example:

  char c;

  Arrays of base types can be specified
  using the syntax:

  char tmp[80];

  Pointers to a base type are specified
  as

  char *tp;

<continue>
 C keyword

 Used to skip the remainder of a
 loop and test the condition again.

 Example:

 for (i = 0;i< 100; i++)
    {
    if (cond == 1) continue;
    /* if not cond == 1 do the rest
    of the loop below the above line
    otherwise increment i and test
    again.
    }


<default>
 C keyword

 Used in conjunction with a switch to
 select the remaining not explicitly
 specified choices.

 Example:

 switch(code)
    {
    case 0:/* do something if code = 0*/
       break;
    case 1:/* do this if code = 1*/
       break;
    case 2:
    case 3:/* do this if code = 1 or 2*/
       break;
    default:/* do this if none of the
           above */
       break;
    }

<do>
 C keyword

 Used in conjunction with while to set
 up loops that are executed at least
 once. For Example:

 do
    {
    /* loop body */
    }
 while (cond ==  1);

<double>
 C keyword

 Used to allocate memory for a
 double precision floating point
 value. All variable declarations must
 be done outside of the main routine
 for globals or immediately after the
 function declaration for local
 variables.

 Example:

 double d;

 Arrays of base types can be specified
 using the syntax (2 x 400 array):

 double data[2][400];

 Pointers to a base type are specified
 as

 double *tp;

<else>
 C keyword

 Used as part of an if statement to
 select the converse case.
 Example

 if (cond == 1)
    {
    /* execute this if cond = 1 */
    }
 else
    {
    /* execute this if cond not 1 */
    }

<float>
 C keyword

 Used to allocate memory for a
 single precision floating point
 value. All variable declarations must
 be done outside of the main routine
 for globals or immediately after the
 function declaration for local
 variables.

 Example:

 float f;

 Arrays of base types can be specified
 using the syntax (2 x 400 array):

 float data[2][400];

 Pointers to a base type are specified
 as:

 float *tp;

<for>
 C keyword

 Used to set up loops which are meant
 to run for a predetermined number of
 iterations. For example:

 for (i = 0;i< 100; i = i + 2)
    {
    /* execute this loop body 50
    times. ie until i = 100 with
    i starting at zero and incremented
    by 2 after each iteration */
    }

<int>
 C keyword

 Used to allocate memory for a
 variable of size one integer.
 All variable declarations must
 be done outside of the main routine
 for globals or immediately after the
 function declaration for local
 variables.

 Example:

 int i,j;

 Arrays of base types can be specified
 using the syntax (2 x 400 array):

 int data[2][400];

 Pointers to a base type are specified
 as

 int *tp;

<if>
 C keyword

 Used to conditionally execute a block
 of code depending if the conditional
 expression is true (non zero) or false
 (zero). Can be used in conjunction with
 the keyword else. For example:

 if (i > j && k != 10)
    {
    /* execute this block if i greater
    than j and k not equal to 10 */
    }
 else
    {
    /* otherwise to this block */
    }

<main>
 C keyword

 This is actually a function and is the
 starting point of the code. The
 function main is called by hitting
 CTRL G. The syntax is

 main()
    {
    /* program to be executed */
    }

<return>
 C Keyword

 This exits a sub routine and returns
 an optional value to the calling
 routine. For example:

 main()
    {
    int x;
    i = sub(x);
    print(i);
    }

 int sub(int x)
    {
    /* calculate i based on input x */
    return i;
    }

<switch>
 C keyword

 Used to select one of a number of
 choices based on the value of the
 expression code.

 Example:

 switch(code)
    {
    case 0:/* do something if code = 0*/
       break;
    case 1:/* do this if code = 1*/
       break;
    case 2:
    case 3:/* do this if code = 1 or 2*/
       break;
    default:/* do this if none of the
           above */
       break;
    }

<while>
 C keyword

 Used to construct loops which run an
 non predetermined number of times. For
 example:

 cond = 1;
 while (code == 1)
    {
    /* execute this loop body until
    something in here sets cond to
    something other than 1. */
    }