This is gri.info, produced by makeinfo version 4.8 from gri.texi.

INFO-DIR-SECTION Scientific Applications
START-INFO-DIR-ENTRY
* Gri: (gri).  Programming language for scientific illustration
END-INFO-DIR-ENTRY


File: gri.info,  Node: Show,  Next: Skip,  Prev: Set Z Missing,  Up: List Of Gri Commands

9.3.42 `show'
-------------

     `show ...'

Show some information by printing it to standard output.

   * `show all' Show lots of information about plot.

   * `show axes' Show information about axes.

   * `show color' Show the current pen color used for lines and text.
     This is not to be confused with image color, which is independent.

   * `show colornames' Show all colors known by name, as defined by
     `read colornames' command and also the builtin colors defined
     automatically (e.g. `white', `black', `red', etc), (*Note Read
     Colornames::).

   * `show columns' Show x, y, z, u, v column data.

   * `show columns statistics' Show means, std devs, etc for columns.

   * `show flags' Show values of all flags. (Developers only.)

   * `show grid' Show an indication of the grid data (used for
     contouring).

   * `show grid mask' Show 1 if grid data are valid or 0 if contours
     will not extend into this region.

   * `show image' Show information about image, such as a histogram of
     values, and, if the image is small enough, the actual data.

   * `show license' Show the license for Gri, which outlines how users
     are allowed to share it freely.

   * `show misc' Show miscellaneous information about the plot, the
     data, etc.

   * `show next line' Show next line of data-file.

   * `show synonyms' Show values of all synonyms, whether built-in or
     user-defined.

   * `show stopwatch' Show elapsed time since first call to this
     command in the given Gri program.

   * `show time' Show the current time.

   * `show traceback' Show traceback (i.e., the tree of commands being
     done at this instant).

   * `show variables' Show values of all variables, whether built-in or
     user-defined.

   * `show .value.' Show value of indicated variable.

   * `show {rpn ...}' Show result of computing indicated expression.

   * `show "some text"' Print the indicated string.  You may use a
     double-slash to prevent Gri from substituting synonym values; thus
     it is common to do e.g.

          \var = "Temperature"
          show "Plotting \\var = 'var'"

     which will produce the output line

          Plotting \\var = 'Temperature'

   * `show "time=" .time. "; depth=" .depth.' Print strings and values
     as indicated.  If the last item is ellipses (three dots with no
     spaces between them), then no newline is printed; this makes the
     next `show' statement print on the same line.

     To get a newline in a printed string, use the three-character glyph
     `\<<', and to get a horizontal tab, use `\>>', as in the examples
     below

          \a = "HI"
          show "\\a=\a"
          system echo -e "a\\nb"
          show "first line\<<second line"
          show "first line\<<\>>(tabbed) second line"
          show "first line\<<\>>(tabbed) second line"



File: gri.info,  Node: Skip,  Next: Sleep,  Prev: Show,  Up: List Of Gri Commands

9.3.43 `skip'
-------------

     `skip [forward|backward] [.n.]'

   * `skip' For ascii files, skip next line in the data file.  For
     binary files, skip forward 1 byte.

   * `skip backward' For ascii files, skip backward 1 line in the data
     file.  For binary files, skip backward 1 byte.

   * `skip .n.' or `forward .n.' For ascii files, skip forward `.n.'
     lines in the data file.  For binary files, skip forward `.n.'
     bytes.

   * `skip backward .n.' For ascii files, skip backward `.n.' lines in
     the data file.  For binary files, skip backward `.n.' bytes.


File: gri.info,  Node: Sleep,  Next: Smooth,  Prev: Skip,  Up: List Of Gri Commands

9.3.44 `sleep'
--------------

     `sleep .sec.'

   Cause Gri to sleep for the indicated number of seconds, which should
be a positive integer.  This command is ignored if `.sec.' is zero or
negative, and the value of `.sec.' is first rounded to the nearest
integer.

   Normally, this command is used only by the developer, as a way to
slow down Gri execution, to allow easier monitoring for debugging
purposes.  Beware: it is tricky to kill a sleeping job!


File: gri.info,  Node: Smooth,  Next: Source,  Prev: Sleep,  Up: List Of Gri Commands

9.3.45 `smooth'
---------------

All these smoothing commands ignore the *location* of the data.  For
equispaced data these algorithms have the standard interpretation in
terms of digital filters.  For non-equispaced data, the interpretation
is up to the user.

     `smooth {x [.n.]} \
       | {y [.n.]} \
       | {grid data [.f.|{along x|y}]}'

   The `smooth x' command does smoothing by the following formula

     x[i-1]   x[i]   x[i+1]
     ------ + ---- + ------
       4       2       4

   The `smooth x .n.' command does boxcar smoothing with centred
boxcars `.n.' points wide.  The `smooth y' command does the same as
`smooth x', but on the `y' column.

   There are several methods of smoothing grid data.  Note that isolated
missing values are filled in by each method.  (Let the author know if
you'd like that `feature' to be an option.)

   The `smooth grid data' command smooths gridded data, by weighted
average in a plus-shaped window about each gridpoint.  The smoothing
algorithm replaces each interior gridpoint value `z[i][j]' by

     z[i][j]   z[i-1][j] + z[i+1][j] + z[i][j-1] + z[i][j+1]
     ------- + ---------------------------------------------
        2                          8

Points along the edges are smoothed by the same formula, after
inventing image points outside the domain by planar extrapolation.

   The `smooth grid data .f.' command performs partial smoothing.  A
temporary fully-smoothed grid `zSMOOTH[i][h]' is constructed as above,
and a linear combination of this grid and the original grid is used as
the replacement grid:

     z[i][j] = (1-f) * z[i][j] + f * zSMOOTH[i][j]

where `f' is the value indicated on the command line.  Thus, `smooth
grid data 0' performs no smoothing at all, while `smooth grid data 1'
is equivalent to `smooth grid data'.

   The `smooth grid data along x' command smooths the grid data across
`x' (i.e., horizontally), by replacing each value `z[i][j]' with the
value

     z[i][j]   z[i-1][j] + z[i+1][j]
     ------- + ---------------------
        2                4

Points along the edges are smoothed by the same formula, after
inventing image points outside the domain by linear extrapolation.

   The `smooth grid data along y' command does the same thing as
`smooth grid data along x', but the smoothing is along `y'.

   *See also* *Note Filter::, a generalization of `smooth x|y' which
allows for more sophisticated filters.


File: gri.info,  Node: Source,  Next: Sprintf,  Prev: Smooth,  Up: List Of Gri Commands

9.3.46 `source'
---------------

     `source \filename'

Perform the commands in the indicated file.

   If the file cannot be found, an error results.  Contrast this with
the `insert' command (*Note Insert::), which has the ability to search
for the file through a user-specified path (*Note Set Path To::).


File: gri.info,  Node: Sprintf,  Next: State,  Prev: Source,  Up: List Of Gri Commands

9.3.47 `sprintf'
----------------

     `sprintf \synonym "format" .variable. [.variable. [...]]'

Write numbers into a synonym (text string).  This is useful for
labelling plots.

`sprintf \out "a = %lf b = %.2f" .a. .b.' - Create a synonym called
`\out', and print the values of the variables `.a.' and `.b.' into it.
If `.a.' = 1 and `.b.' = 0.112, then `\out' will be `"a = 1 b = 0.11"'

   Formatting codes are as in the C programming language, eg:

     %.2f  -- Use floating point with 2 decimal places.
     %9.2f -- As above, but number takes 9 characters.
     %e    -- Use exponential notation.

*CAUTION*: Variables are stored in the *floating point* in Gri, so you
must use a format like `"%f"', *not* an integer code like `"%d"'.  If
you want an integer, use `"%.0f"'.  


File: gri.info,  Node: State,  Next: Superuser,  Prev: Sprintf,  Up: List Of Gri Commands

9.3.48 `state'
--------------

     `state save|restore|display'

The `save' operation pushes a record of the graphics state (pen and
font characteristics, margins, axis lengths, min/max/inc values on axes,
etc) onto a stack.  The `restore' operation replaces the present state
with whatever is on top of the stack, and then pops the stack.  Use
`display' to see some of the state properties.

   The `state' command is useful for temporary changes of axis
properties, etc.

   BUG: only line characteristics (width, color) and font
characteristics (font, size, color) are saved so far.  In fact, the
full list of what should be saved has not yet been finalized by the
author.


File: gri.info,  Node: Superuser,  Next: System,  Prev: State,  Up: List Of Gri Commands

9.3.49 `superuser'
------------------

     `superuser [value]'

Allow extra debugging information and commands.  Normally, this command
and the corresponding commandline flag `-superuser' are only used by
programmers altering the Gri source.

   These are the flags and their meanings:
   * *1* Print cmdline before/after substituting synonyms.

   * *2* Print cmdline before/after substituting rpn expressions.

   * *4* Print all new commands as they are being defined

   * *8* Print the system commands that are used with `open "...|"' and
     in other instances.

   * *128* Changeable; only author should use this.

   * *256* Changeable; only author should use this.
   Note that all flags are equal to 2 raised to an integer power.  Since
the flag values are detected by a bitwise OR, you can combine flags by
adding; thus specifying a flag of 5 yields flags 1 and 4 together;
specifying 15 yields flags 1, 2, 4 and 8.


File: gri.info,  Node: System,  Next: Unlink,  Prev: Superuser,  Up: List Of Gri Commands

9.3.50 `system'
---------------

     `system \system-command'

Tell the operating system to perform the indicated action.  Whatever
string follows the word `system' is passed directly to the operating
system, *after* substitution of synonyms if any exist.

   If your system command contains double-slashes, you must protect them
from Gri (which will interpret them as comments) by enclosing in
double-quotes, e.g. `system cat A | sed -e "s/foo//g" | cat > B'.  (In
the particular case of the `sed' command you could also do `system cat
A | sed -e "s:foo::g" | cat > B'.

   Note that `rpn' expressions are not evaluated, and variable values
are not substituted before passing the string to the operating system.
The exit status is stored in the builtin variable `..exit_status..'.

   There are two ways to use the system:
   * *Assign output to synonym*: The form `\synonym = system ...' does
     the system command and then inserts the output from that command
     into the indicated synonym.)

   * *Just run a command*: The command `system ls' will list the files
     in the current directory.

   For long commands, there are two approaches, the second preferred:
   * *Use continuation lines*: String a lot of information onto one
     effective system line, using the `\' line-continuation character
     at the ends of lines.  The problem is that it is very easy to lose
     one of these backslashes.  The next method is better.

   * *Here-is syntax* The here-is syntax of many unix shells is also
     provided.  If the system command contains the characters `<<'
     followed by a word (with no space between!) then Gri will issue a
     system command which includes not only this line but also all
     succeeding lines, until a line is found which matches the
     indicated word precisely (with no leading space allowed).  The `<<
     "WORD"' syntax is also supported, meaning that the operating
     system is being told not to mess with the dollar-signs - needed in
     perl.

     Be careful using this inside a new-command.  Gri Recognizes the
     end of the body of a new-command by a line with `}' in the *first
     column*, and no non-white characters thereafter.  If you system
     command happens to use a line with a curly brace (as in a loop in
     perl, for example), you must put whitespace before the brace.
     This won't affect the system command, but it will let Gri correctly
     realize that this is *not* the end of the new-command.  For more
     information on new-commands (*Note Parsing::).

     *Caution:* Before sending the string to the system, Gri first
     translates any synonyms present.  Be careful with this, since
     system commands calling awk, etc, very often use backslashes for
     the newline character `\n' within strings.  If you have a synonym
     whose name starts with `\n', you can get a conflict.  For example,
     the awk command `print "foo\nbar";' should print a line with `foo'
     on it, followed by a line with `bar' on it, but it will instead
     print a single line with `fooMISTAKE', if you had previously
     defined a synonym as `\nbar = "MISTAKE"'.  One way to avoid this
     mistake is to make sure any `\n' characters appear at the end of
     strings, and then simply avoid having a synonym named `\n'.

     Here is a Perl example.

          \m = "Foo bar"
          system perl <<"EOF"
          $a = 100;
          print "foo bar is \m, and a is $a\n";
          print "BETTER: foo bar is \m, and a is $a\n";
          print "Q: was a 100?\n";
          EOF


   *Some more examples*:
   * To get the first 15 lines of a file called `foo.dat' inserted into
     another file called `bar.dat', you might do the following.  Only
     the first method works; the second will fail because `.n.' will not
     be translated before passing to the operating system.

          \num = "-15"
          system head \num foo.dat > bar.dat
          # Following will not work correctly because .num.
          # will not be translated
          .num. = -15
          system head .num. foo.dat > bar.dat

   * Issue a unix command to get a listing of files in the current
     working directory, and pipe them into the `more' system command.

          system ls -l *c | more

   * Store the date and time into a synonym, and use it in a title:

          \time = system date
          ...
          draw title "Plotted at time \time"

   * Use `awk' to prepare a two-column table of x, ranging from 0 to 1
     in steps of 0.1, and sin(x).  The table is stored in a file whose
     suffix is the process ID of the Gri job.  This file is then
     opened, and the data plotted.  Finally, a system command is issued
     to remove the temporary file.

          system awk 'BEGIN { \
              for (x=0; x<1; x+=0.1) { \
                printf("%f %f\n", x, sin(x)) \
              } \
            }'  > tmp.\.pid.
          open tmp.\.pid.
          read columns x y
          close
          system rm tmp.\.pid.
          draw curve

     *Note*: in unix, this command calls the Bourne shell, not the
     C-shell that is often used interactively.  For many simple uses,
     the only difference from normal interactive use will be that `~'
     is not expanded to the home directory.  For example, you should
     write

          system awk -f $HOME/foo/bar/cmd.gawk

     instead of the

          system awk -f ~/foo/bar/cmd.gawk

     that you might expect from interactive C-shell use.  RETURN VALUE: Sets
     `\.return_value' to system status `N status'


File: gri.info,  Node: Unlink,  Next: While,  Prev: System,  Up: List Of Gri Commands

9.3.51 `unlink'
---------------

     `unlink \filename'
Delete a filename and possibly the file to which it refers.  On
non-unix machines, this simply means to delete the file.  On unix
machines, the action is more subtle.  The unix OS permits several
processes to use a given file at once.  Therefore, `unlink' doesn't
immediately remove the file, but instead waits until other processes
are done with it.  Most users will never realize the difference,
however, and it is safe to think of `unlink' as simply removing the
file.  To learn more, type `man unlink' in a unix shell.

   A common use of `unlink' is to remove files that were created with
the `tmpname' facility (*Note Using OS Inside Gri::), e.g.
     \tmp = tmpname
     # do some system commands to put data into this file
     open \tmp
     read columns x y
     draw curve
     unlink \tmp


File: gri.info,  Node: While,  Next: Write,  Prev: Unlink,  Up: List Of Gri Commands

9.3.52 `while'
--------------

     `while .test.|{rpn ...}'

Perform statements in loop while the value of `.test.' or the RPN
expression is nonzero.  The end of the loop designated by a line
containing the words `end while'.  The value `.test.' may be an rpn
expression.  To leave the loop prematurely, use a `break' statement.
Upon encountering a `break' statement, Gri jumps to the line
immediately following the loop.  If the `-chatty' option is nonzero, a
notification is printed every 1000 passes through the loop, as a
debugging measure to catch unintended infinite loops.

*Examples*:

   * Loop forever, printing a message over and over.

          while 1
            show "This loops forever. Need to 'break'"
          end while

   * Read number pairs from a file, plotting bullets at the indicated
     locations.  Note the use of an infinite loop, with a break
     condition following an end-of-file test.  (Do not be tempted to
     write such loops as `while !..eof..' because that would not catch
     the end of file until the next time through the loop.  The result
     would be to draw the last bullet twice, since the `read' will not
     update the variables when the end of file is encountered.)
          while 1
            read .x. .y.
            if ..eof..
              break
            end if
            draw symbol bullet at .x. .y.
          end while

   * Loop 10 times, printing the values of `.i.' as they range 0, 1,
     ..., 9.  After exiting from the loop, `.i.' will equal 10.  Be
     *careful* to use the correct rpn greater-than test to avoid an
     infinite loop.

          .i. = 0
          while {rpn .i. 10 >}
            show .i.
            .i. += 1
          end while



File: gri.info,  Node: Write,  Next: Write Columns,  Prev: While,  Up: List Of Gri Commands

9.3.53 The `write' commands
---------------------------

The `write' commands write various things.  

   If the filename is `stdout', the information is written to the
standard output device (ie, the screen); if it is `stderr', the
information is written to the standard error device (ie, the screen).

   *IMPORTANT NOTE*: The `write' commands *append* to the output file,
as opposed to overwriting the contents of the file.  Therefore if
you've run the Gri script before, and want fresh output, make sure to
do something like the following

     system rm -f the_grid.dat
     write grid to grid.dat

* Menu:

* Write Columns::               Write columns to a file
* Write Contour::               Write contour (x,y) data to a file
* Write Grid::                  Write grid data to a file
* Write Image::                 Write various properties of image to a file


File: gri.info,  Node: Write Columns,  Next: Write Contour,  Prev: Write,  Up: Write

9.3.53.1 `write columns'
........................

     `write columns to \filename'

Append data columns to the end of the indicated file.


File: gri.info,  Node: Write Contour,  Next: Write Grid,  Prev: Write Columns,  Up: Write

9.3.53.2 `write contour'
........................

     `write contour .value. to \filename'

Append to the named file the (x,y) pairs defining the contour of the
indicated value.

   The first line of output is a header line, containing two numbers:
the contour value and the missing value.  Then the (x,y) pairs are
written a line at a time, with missing values being used to indicate
ends of segments.  A blank line is written after the last data pair.
For example, if the contour contained two closed regions, Gri would
output a pair of missing values as one of the xy pairs, to denote the
separation of the two curves.  You could read and plot the output as in
this example

     write contour 10 to contour.out
     open contour.out
     read .contour_value. .missing.
     set missing value .missing.
     read columns x y
     draw curve


File: gri.info,  Node: Write Grid,  Next: Write Image,  Prev: Write Contour,  Up: Write

9.3.53.3 `write grid'
.....................

     `write grid to \filename [bycolumns]'

Append grid to the end of the named file.  Storage is in `%f' format,
and is in normal image order.  If the keyword `bycolumns' is present,
then the grid is transposed first, in such a way that `read grid data
bycolumns' performed on that file will read back the original grid data.


File: gri.info,  Node: Write Image,  Next: Programming,  Prev: Write Grid,  Up: Write

9.3.53.4 `write image'
......................

     `write image ... to \filename'

The variants of this command write various things about the image to the
named file, as illustrated in the following table.

   * `write image to image.dat' Append image to the end of the named
     file.  Storage is by unsigned-char, and is in normal image order.
     There is no header.

   * `write image rasterfile to image.dat' Append image to the end of
     the named file, in Sun Rasterfile format.

   * `write image pgm to mask.dat' Append image mask to the end of the
     named file, in PGM 'rawbits' format.

   * `write image mask to mask.dat' Append image mask to the end of the
     named file. Storage is by unsigned-char, and is in normal image
     order.

   * `write image mask rasterfile to mask.dat' Append image mask to the
     end of the named file, in Sun Rasterfile format.

   * `write image mask pgm to mask.dat' Append image mask to the end of
     the named file, in PGM 'rawbits' format.

   * `write image colorscale to colorscale.dat' Append image colorscale
     transform to the end of the named file.  Storage is a series of
     256 lines, each containing 3 numbers (for Red, Green and Blue) in
     the range 0 to 1.  The file is suitable for reading with the `read
     image colorscale' command.

   * `write image grayscale to grayscale.dat' Append image grayscale
     transform to the end of the named file.  Storage is a series of
     256 lines, each containing a number in the range 0 to 1.  The file
     is suitable for reading with the `read image grayscale' command.

   


File: gri.info,  Node: Programming,  Next: Defaults,  Prev: Write Image,  Up: Top

10 Programming in the Gri Language
**********************************

The Gri programming language has `if' statements to control program
flow, and a `while' statement to repeat commands.  There are two data
types in Gri: "variables" (to store numbers) and "synonyms" (to store
character strings).  Gri recognizes commands by matching statements
against its list of known commands.  This list is extensible; it is
easy to add new commands as extensions to Gri.

* Menu:

* Defaults::                    How Gri normally acts
* Online Help::                 Getting help from gri itself
* Long Command Lines::          Continued lines
* Variables::                   Variables (for storing numbers)
* Synonyms::                    Synonyms (for storing character strings)
* If Statements::               If statements
* Loops::                       Repeating command lines
* Mathematics::                 Doing mathematics on columns, grids etc
* rpn Mathematics::             Doing mathematics on variables
* Text::                        Doing things with characters strings
* Adding New Commands::         How to customize Gri by adding new commands
* Missing Values::              How to specify missing data
* Hints::                       Hints for good Gri programming
* Debugging::                   Debugging Gri programs
* Error Messages::              What to do about Gri error messages
* Missing Values::              Missing value code
* Operating System::            Using Gri in OS and OS in Gri
* Resource File::               Personalizing Gri


File: gri.info,  Node: Defaults,  Next: Online Help,  Prev: Programming,  Up: Programming

10.1 Defaults
=============

At startup time, Gri sets the values of some things, like font size.
Since Gri is still under development, some of these defaults might
change, so you should not rely on them remaining the same.    Presently,
the defaults are equivalent to:

     set arrow size 0.2         # (cm)
     set axes style 0
     set beep off
     set clip off
     set clip postscript off
     set contour format %lg
     set contour label position ? ?
     set contour labels horizontal
     set contour labels whiteunder
     set dash off
     set font size 12           # (pt)
     set font to helvetica
     set graylevel 0            # Black ink
     set ignore initial newline off
     set input data window x off
     set input data window y off
     # Following set (curve, axes, symbol) widths to width
     # of rapidograph pens called (6x0, 3x0,  6x0)
     set line width 0.709        # (pt) for curves
     set line width axis 0.369   # (pt) for axes
     set line width symbol 0.369 # (pt) for symbols
     set missing value 1.0e22
     set page portrait
     set page factor 1
     set symbol size 0.1        # (cm)
     set tic size 0.2           # (cm)
     set tics out
     set trace off
     set x format %lg
     set x margin 6.0           # (cm)
     set x name "x"
     set x size 10              # (cm)
     set x type linear
     set y axis name vertical
     set y format %lg
     set y margin 6.0           # (cm)
     set y name "y"
     set y size 10              # (cm)
     set y type linear

(NOTE: Programmers may alter the gri source file `defaults.h' and then
recompile Gri, if they feel the need to change these things.  Also, see
the file `startup.c' and the function `gr_begin()' in `gr.c'.)


File: gri.info,  Node: Online Help,  Next: Long Command Lines,  Prev: Defaults,  Up: Programming

10.2 Online Help
================

Type `help' to get a list of available commands and other topics of
interest. Here's how Gri responds

     Type `help' followed by a command-name:
      assert      cd            close         convert
      create      debug         delete        differentiate
      draw        expecting     filter        flip
      get         help          if            ignore
      input       insert        interpolate   list
      ls          mask          move          new
      open        pwd           query         quit
      read        regress       reorder       rescale
      resize      return        rewind        set
      show        skip          sleep         smooth
      source      sprintf       state         superuser
      system      write
     Or type `help -' followed by a topic from this list:
      example     extending     files         math
      strings     synonyms      variables     manual

   Some commands have more words than shown.  You can type these
additional words to narrow the help down; otherwise Gri will give you
help on all commands that begin with the indicated words.  For example,
try `help set' and `help set x'.  When you ask for help on a multi-word
command, Gri tells you about all commands which begin with the words
you've typed.  Thus,

     help
     help draw
     help draw zero
     help draw zero line

narrow in on the command `draw zero line'.  The response to the most
complete request is

     `draw zero line [horizontally|vertically]'
       draw zero line
         Draw line y=0 if it is within axes
       draw zero line horizontally
         Draw line y=0 if it is within axes
       draw zero line vertically
         Draw line x=0 if it is within axes

   The part enclosed in angled quotes is the syntactical description of
the command.  (NOTE: The square brackets indicate an optional word (in
this case) or words.  The vertical bar indicates that either the item
on the left or the item on the right may appear; it is a logical OR
operator.  The only other special characters in syntax descriptions are
the braces `{}', which are used to enclose multiple words which act as
one unit; they are used to clarify the choices presented to the OR
operator.)  Following the syntactical description are examples.  Each
example is indented 2 spaces, and a description of it (which always
starts with an upper-case character and ends with a period, to indicate
that it is an English description) follows that, indented by an
additional 2 spaces.


File: gri.info,  Node: Long Command Lines,  Next: Variables,  Prev: Online Help,  Up: Programming

10.3 Long Command Lines
=======================

To extend a command across several lines, use a backslash `\' at the
*very* end of all lines but the last:

     draw line from \
       10 20 \
       to \
       10 30


File: gri.info,  Node: Variables,  Next: About Variables,  Prev: Long Command Lines,  Up: Programming

10.4 Variables
==============

* Menu:

* About Variables::             What variables are used for, and how
* User Variables::              Defining your own variables
* Built-in Variables::          Variables pre-defined by Gri


File: gri.info,  Node: About Variables,  Next: User Variables,  Prev: Variables,  Up: Variables

10.4.1 About variables
----------------------

Variables store numbers.  As it reads your program, Gri substitutes
variable values any place a variable appears where a number normally
would.  For example, in the code below `.number.' is a variable storing
the value 10, so the two `read' statements have the same effect:

     .number. = 10
     read columns .number. x y
     read columns 10 x y

   Variable names begin and end with a single period (example:
`.num.').  (Gri uses this odd notation to distinguish variable names
from "normal" words, which is necessary because Gri does not have a
limited list of keywords as other languages do.  Thus, the C
programming language is happy to let you use a variable name like
`latitude', since it is not a keyword, but Gri is not, since it might
like to use that word itself in a new command.)

   You should not use names beginning and ending with double periods,
because Gri uses names like that to store built-in variables for its own
use (e.g., `..xsize..' saves the width of the plot).

   To store a number into a variable, use a command like

     .time. = 10

or

     .time. = {rpn 10 sin}

   Storage is automatically set aside when you assign into a nonexistent
variable; no "declaration" statements are required as in the C language.

   The Gri command, `new' (*Note New::), allows you to have several
"versions" of a variable.  This is useful for local storage in new
commands, inside `if' statements, etc, since it lets you use temporary
variables without worrying about overwriting values outside the local
block of code.  The syntax is `new .variable. = value' (where, as
usual, `value' may be an rpn expression (*Note rpn Mathematics::).
Here is an example:

     `foo bar'
     {
       new .a.         # Get storage
       .a. = 10        # Store a local value
       show "Locally, .a.=" .a. " (expect 10)"
       delete .a.      # Delete this local one
     }
     .a. = 1
     show "Global version has .a.=" .a. " (expect 1)"
     foo bar

   To see if a given named variable (or synonym) exists, use the RPN
operator `defined' (*Note rpn Mathematics::).


File: gri.info,  Node: User Variables,  Next: Built-in Variables,  Prev: About Variables,  Up: Variables

10.4.2 User variables
---------------------

You can get Gri to read values for variables from your file.  Here's how
to read a number from a header line and then read that many lines of
columnar data:

     open file.dat
     read .num.
     read columns .num. x y

   You can define variables within the Gri program:

     .num. = 10
     read columns .num. x y

   You can get variables interactively from the user, using the `query'
command.  (If the user types carriage-return, or if the command-line
flag `-y' was specified when invoking Gri, the value 100 will be
assigned to `.num.').  For example,

     query .num. "Number of rows to read?" (100)
     read columns .num. x y

   Gri allows you to use a previous value of the variable in the default
string, as in this example:

     .start. = 8                             # default
     .stop. = 2                              # default
     query .start. "Start time? " (.start.)
     query .stop.  "Stop time?  " (.stop.)

   Variables can be manipulated using reverse polish notation (RPN)
mathematical operations (*Note rpn Mathematics::).

   Variables are often useful in `if' statements.  Here are some
examples:

     read .num_pts.
     if .num_pts.
       show "There are some data"
       read columns .num_pts. x y
     else
       show "There are no data"
     end if
     # ...
     read .latitude.
     if {rpn .latitude. 10 <}
       read .num.
       read .num. x y
       draw curve
     else
       show "Skipping data North of 10deg N"
       read .num.
       skip .num.
     end if


File: gri.info,  Node: Built-in Variables,  Next: Synonyms,  Prev: User Variables,  Up: Variables

10.4.3 Built-in variables
-------------------------

Built-in variables (*Note Index of Builtins::) have names which begin
and end with *two* periods.  For example, `..xsize..' is the width of
the x-axis in centimetres.  You may use these variables as you wish
(example: `..xsize.. = 4' is an alternative to `set x size 4'), but you
must be aware that these are not "free" variables for you to use for
arbitrary purposes.  You can find out what the built-in variables are
by the command `show variables'.

   There are two types of variables
   * *Startup* variables, which are created by Gri at startup time.
     These variables can be relied upon to exist (barring changes in Gri
     itself), unless you `delete' them.

   * *Spontaneous* variables (which are created by certain Gri commands,
     and only exist if these commands have been executed).  For
     example, the `regress' command defines `..coeff0..' (the intercept
     of the fitted line), `..coeff1..' (the slope of the fitted line),
     `..R2..' (the correlation coefficient).

   To see the values of the built-in variables (along with the user
variables), use `show variables'.  Here are some useful builtin
variables:

   * `..arrowsize..' Stores either a positive number representing the
     halfwidth of arrowheads measured in centimetres, or a negative
     number giving the negative of the ratio of arrowhead halfwidth to
     arrow length (*Note Set Arrow Size::).

   * `..batch..' Flag used for batch mode.

   * `..debug..' Equal to 1 if the `-debug' command-line flag was set.
     Flag used for debugging (*Note Invoking Gri::).  The `..debug..'
     built-in variable is useful in isolating code to use only in test
     runs.  For example, you might use

          if ..debug..
            show "Following are the column data"
            show columns
          end if

     When you run the program with command-line `gri -debug file.gri'
     the code in the `if' block will print out the columnar data, but
     when you run it with `gri file.gri' these lines are not printed.

   * `..eof..' Flag indicating whether an end-of-file was encountered
     on the last `read columns'.

   * `..words_in_dataline..' Number of words on last dataline.  This is
     useful in constructs like

          open tmp.dat
          .num. = 0
          while 1
            read .a. .b.
            if !..words_in_dataline..
              show "Got empty line or EOF, so break loop"
              break
            end if
            show "a=" .a. "b=" .b.
            show "; words in line=" ..words_in_dataline..
            .num. += 1
          end while
          show "Got " .num. "data lines."

   * `..fontsize..' Size of letters, measured in points; there are
     72.27 points in an inch and 28.45 points in a centimetre.  The
     mathematical operators `pttocm' and `cmtopt', which do conversion
     between points and centimetres, are often useful in labelling data
     curves (*Note rpn Mathematics::).

   * `..graylevel..' Graylevel to use in drawing lines, text, etc.
     Black ink is 0; white paper is 1.  *See also* `..red..' etc.

   * `..image_height..' Height of image, or 0 if no image defined yet.

   * `..image_width..' Width of image, or 0 if no image defined yet.

   * `..length_dash..' Length in cm of dashes in dashed lines.

   * `..length_blank..' Length in cm of blanks in dashed lines.

   * `..linewidth..' Width of lines for data curves (*Note Set Line
     Width::).

   * `..linewidthaxis..' Width of lines on axes (*Note Set Line
     Width::).

   * `..linewidthsymbol..' Width of lines in symbols (*Note Set Line
     Width::).

   * `..missingvalue..' Missing value code, also stored in the synonym
     `\.missingvalue.'; (*Note Set Missing Value::).

   * `..num_col_data..' Number of column data that exist.  You might
     want to use this after `read columns' to see if a data file
     actually had any data in it, or use it in accessing individual
     elements of columns (*Note rpn Mathematics::).

   * `..publication..' Flag for final copy of plot.  The command-line
     option `-p' sets the value of `..publication..' to 1.  A typical,
     and highly recommended, code fragment is

          if !..publication..
            draw time stamp
          end if

   * `..red..', `..green..', `..blue..' Description of present color.
     The values are between 0 and 1, with (0,0,0) being black and
     (1,1,1) being white.  If color is gray, all these will be equal.
     You may assign to these, but it will *not* change the color.

   * `..symbolsize..' Size of symbols in centimetres.

   * `..superuser..' Equal to 0 if the flag was not set, or equal to
     the flag if it was.

   * `..tic_direction..' Direction of axis tics, 1 for inside or 0 for
     outside.

   * `..tic_size..' Size of axis tics in centimetres.

   * `..trace..' Equal to 1 if the `-trace' command-line flag was set.
     Used for tracing program execution.

   * `..xinc..' x increment on axes.

   * `..xleft..' x value at left of plot.

   * `..xmargin..' Left margin, in centimetres.

   * `..xright..' x value at right of plot.

   * `..xsize..' x-axis length in centimetres.

   * `..ybottom..' y value at bottom of plot.

   * `..yinc..' y increment on axes.

   * `..ymargin..' Bottom margin in centimetres.

   * `..ysize..' y-axis length in centimetres.

   * `..ytop..' y value at top of plot

   * `..exit_status..' The exit status from the most recent `system'
     call (or 0 if no system calls have been done yet).

   You may use any of these built-in variables anywhere.  For example,
here's how to stack 3 graphs vertically on the page:

     .offset. = {rpn ..ysize.. 3 + }
     open file1
     read columns x y
     close
     draw axes
     draw curve

     ..ymargin.. += .offset.
     open file2
     read columns x y
     draw axes
     draw curve
     close

     ..ymargin.. += .offset.
     open file3
     read columns x y
     draw axes
     draw curve
     close

   The first line needs a bit of explanation. It is a reverse-polish
expression.  The format is `{' followed by `rpn' followed by an
expression followed by `}'.  Within the expression, spaces must
separate operands.  This makes `.offset.' equal to the height of y-axis
plus 3 cm, so plots are separated by 3 cm.  To learn more about `{rpn
... }' (*Note rpn Mathematics::).

   Another possibly unfamiliar thing is the code `+='.  It means take
the thing on the left hand side, and add to it the thing on the right
hand side.  (In this case, it is used to increase the y margin by the
value of `.offset.'.)


File: gri.info,  Node: Synonyms,  Next: Naming Convention,  Prev: Built-in Variables,  Up: Programming

10.5 Synonyms
=============

Synonyms are used by Gri to store character strings.  Gri denotes
synonyms with words beginning with backslash (e.g., `\syn'), following
the TeX convention.

* Menu:

* Naming Convention::             Their names with a backslash, e.g. `\syn'
* Using Synonyms::                Some usage examples
* Important Builtin Synonyms::    e.g. `\.command_file.'
* Alias Synonyms::                e.g. `\@alias'
* Local Synonyms::                Working with the arguments of newcommands


File: gri.info,  Node: Naming Convention,  Next: Using Synonyms,  Prev: Synonyms,  Up: Synonyms

10.5.1 Naming convention for synonyms
-------------------------------------

Synonym names begin with a backslash (e.g., `\filename').  After the
backslash, Gri expects a letter (upper or lower case) or one or more
periods.  Following this is an arbitrary string of letters, numbers, or
underscores.  If there are periods at the start, then the same number of
periods must be used at the end.  The following are some examples
     \simple = "Howdie"
     \.longer_example. = "Dots and underscores are ok too"
     \a2 = "OK for number at end ..."
     \a3bb = "... and inside"

   Gri defines several synonyms for its own use, so that if you modify
these, you may get strange results.  Each of these starts and ends with
a single period.

   There is an exception to the above rule, one which mostly comes up
when using netCDF files which may have variable names that may contain
punctuation.  Gri permits synonym names to have punctuation characters
(but not blanks or tabs) in synonym names, provided that the second
character in the name is an opening brace and that the last character is
a closing brace, e.g.

     \{foo.bar} = "Foo bar"

This is used particularly for files in the netCDF format, for reading
variable attributes, which by netCDF convention use a colon (`:') to
separate variable name and attribute name (*Note Read Synonym or
Variable::).  For more information on netCDF format, see

   `http://www.unidata.ucar.edu/packages/netcdf/index.html'

   Synonyms may be freely embedded in strings (a common example is
`draw title "Data from file `\datafile'"'.  They may also appear
anywhere in commands (e.g., `open \filename').  The exception to this
rule is that Gri ignores your synonyms within math mode, in order to
prevent clashes (e.g. you might define `\alpha' as a synonym storing
the value `"foo bar"', but Gri will ignore this within math-mode, so
that `$\alpha$' will still mean the Greek letter alpha).

   To get a backslash in a string without Gri thinking it is part of a
synonym, use two backslashes (e.g., `show "The backslash character \\
is used for synonyms."').  This may sometimes be required in `system'
commands (*Note System::), to prevent Gri from converting substrings
like `\n' (which many system commands use to represent the newline
character).  For example, the command `system perl -e 'print
"foo\nbar";'' will be mangled if Gri has already been told that `\nbar'
is a synonym.  (There will be no problem if `\nbar' is not an existing
synonym, since Gri will then just leave it in place.)  To be sure that
no mangling can occur, replace each backslash with two backslashes.
This tells Gri not to try to substitute a synonym at that location.  In
the example below, the first system call prints `fooled you!' on one
line line, because Gri substituted for what it thought was a synonym
called `\nbar'; the second (correctly) prints `foo' on one line and
`bar' on the next.  

     \nbar = "led you!"
     system perl -e 'print "foo\nbar\n";'
     system perl -e 'print "foo\\nbar\\n";'

   Similarly, if your system command is expecting to see `\t' (for a
tab character), then you must write `\\t' to prevent Gri from trying to
substitute a synonym named `\t'.

   The `show' command has a special syntax for permitting newlines and
tabs in strings (*Note Show::).


File: gri.info,  Node: Using Synonyms,  Next: Generalizing Code,  Prev: Naming Convention,  Up: Synonyms

10.5.2 Some uses for synonyms
-----------------------------

Synonyms store strings and are useful for anything strings are useful
for, e.g. filenames, plot labels, names of variables, etc.

* Menu:

* Generalizing Code::
* Storing OS Output::
* Storing User Responses::
* Storing File Contents::
* Extracting Words From Strings::


File: gri.info,  Node: Generalizing Code,  Next: Storing OS Output,  Prev: Using Synonyms,  Up: Using Synonyms

10.5.2.1 Using synonyms to generalize code
..........................................

Synonyms are often used to store filenames, since then only a single
line of a file may need to be altered, in order to work with another
file, e.g.

     \filename = "columns.dat"
     open \filename
     # a lot more code using the file name


File: gri.info,  Node: Storing OS Output,  Next: Storing User Responses,  Prev: Generalizing Code,  Up: Using Synonyms

10.5.2.2 Using synonyms to store OS output
..........................................

Synonyms provided a convenient way to store information from the OS.

     # Show the date.
     \date = system date
     show "Time is \date"

     # Show the command file name, then use the system
     # to construct a filename with the same beginning
     # but ".dat" as the ending instead of ".gri".
     show "The commandfile name is \.command_file."
     \fn = system echo `basename \.command_file. .gri`.dat
     show "A filename constructed from this is \fn"

   This example uses the Unix system commands `echo' and `basename' to
construct a filename ending in `.dat', from the command file name
(stored in the builtin string `\.command_file.'), assuming that the
command file name ends in `.gri'.

   NOTE: As usual, if the system command contains the Gri comment
designator (the string `#'), protect it with double-quotes (*Note
System::).


File: gri.info,  Node: Storing User Responses,  Next: Storing File Contents,  Prev: Storing OS Output,  Up: Using Synonyms

10.5.2.3 Storing user responses via `query'
...........................................

You can ask the user for the contents of strings: 

     query \filename "What's the data file?" ("file.dat")

The prompt `What's the name of the data file?' is typed to the
terminal, and whatever string the user types is inserted into the
synonym `\filename'. If the user types nothing, but simply presses
carriage return, the (optional) default string (which must be enclosed
in parentheses as shown) is put into `\filename'. Note that the default
is ignored if it is not written properly: it must be enclosed in double
quotes enclosed in parentheses, with no intervening spaces.


File: gri.info,  Node: Storing File Contents,  Next: Extracting Words From Strings,  Prev: Storing User Responses,  Up: Using Synonyms

10.5.2.4 Storing File Contents
..............................

You can read the contents of synonyms from a file:

     open \directory_file
     read \file_name
     close
     open \file_name
     read columns x y

The first (space-separated) word is read into the the first synonym
after the `read' command, the second word into the second synonym, and
so on.  If the word you want is not near the front of the line, you can
use the command `read line' to get the whole line, then use the method
described above to extract the word you want.  Indexing begins with 0,
remember.


File: gri.info,  Node: Extracting Words From Strings,  Next: Important Builtin Synonyms,  Prev: Storing File Contents,  Up: Using Synonyms

10.5.2.5 Working with words within strings
..........................................

Sometimes a synonym will contain several words that you need to work
with indidually (e.g. it might contain a list of files that should be
processed).  There are two ways to do this.

_The `word of' syntax._
          \sentence = "This sentence has five words"
          \first_word = word 0 of "\sentence"
          \last_word = word 4 of "This sentence has five words"

_The `[]' syntax_
     Individual words of synonyms may be accessed by prefixing the
     synonym name with the index number of the word (starting at 0)
     enclosed in square brackets.

     The number in the square brackets may be a constant, a variable,
     or a synonym, but not a more complicated expression.  If the index
     value is a floating-point number, it is first rounded to the
     nearest integer.  If the index value is negative or exceeds the
     number of words minus 1, then an empty string is retrieved.

     If *no number* appears in the square brackets, the result is the
     number of words in a synonym.

          \syn = "This has 4 words in it"
          show "\[0]syn   ... gives 'This'"
          show "\[1]syn   ... gives 'has'"
          .i. = 3
          show \[.i.]syn  ... gives 'words'"
          \i = "3"
          show \[\i]syn   ... gives 'words'"
          show "\[]syn    ... gives '6', i.e. number of words"



File: gri.info,  Node: Important Builtin Synonyms,  Next: Alias Synonyms,  Prev: Extracting Words From Strings,  Up: Synonyms

10.5.3 Some important builtin synonyms
--------------------------------------

Within mathematics mode (portions of strings enclosed within
dollar-signs), Gri stores the definitions of many Greek letters and
mathematical symbols as math-mode synonyms (*Note Mathematical Text::).

   Global synonyms are shared among commands.  To see the built-in
global synonyms (*Note Index of Builtins::) use `show synonyms', which
produces output that looks something like the following.

     Synonyms...
         \.missingvalue.           = "10000000000000000000000.000000"
         \.return_value.           = ""
         \.version.                = "2.7.0"
         \.pid.                    = "3043"
         \.wd.                     = "/home/kelley"
         \.time.                   = "Sun May 20 13:18:32 2001"
         \.user.                   = "kelley"
         \.host.                   = "Intrusion.phys.ocean.dal.ca"
         \.system.                 = "unix"
         \.home.                   = "/home/kelley"
         \.lib_dir.                = "/usr/share/gri"
         \.command_file.           = "stdin"
         \.readfrom_file.          = "stdin"
         \.ps_file.                = "gri-00.ps"
         \.path_data.              = "."
         \.path_commands.          = "."

   These things will be obvious to unix users; for example `\.pid.' is
the process ID of the job (often used in names for temporary files),
and `\.wd.' is the working directory (often used in `draw title'
commands to indicate in which directory the gri job was run.

   Some commands set `\.return_value.' to non-blank; the meaning of the
return value varies from command to command.


File: gri.info,  Node: Alias Synonyms,  Next: Local Synonyms,  Prev: Important Builtin Synonyms,  Up: Synonyms

10.5.4 Alias synonyms: the `\@alias' syntax
-------------------------------------------

Sometimes you need to work with a variable or a synonym whose name can
only be determined at run-time, perhaps through interaction with the
user, examination of a datafile, or examination of the command provided
to the OS when invoking Gri.

   Gri handles this by so-called "alias" synonyms, which store the
names of other items.

   The syntax is simple.  Suppose that a synonym, called `\pointer'
say, contains the *name of* another synonym, or a variable.  Then you
may use `\@pointer' anyplace you would normally use the item named.

_Illustrations of using the value of a named item_
     The following prints an approximation to Pi followed by the name of
     movie star.
          .pi. = 3.14
          \pi_pointer = ".pi."
          show \@pi_pointer  # just like 'show .pi.'

          \hero = "Gregory Peck"
          \our_hero = "\\hero"
          show "\@our_hero"  # just like 'show "\hero"'

_Illustrations of assigning to a named item_
     The following prints an approximation to 2*Pi and yet another
     star; the point is that the alias appears to the left of an
     assignment operator.
          # Print approximation to 2*Pi
          .pi. = 3.14
          \pi_pointer = ".pi."
          \@pi_pointer *= 2
          show .pi.

          # Stars don't shine alone
          \hero = "Gregory Peck"
          \our_hero = "\\hero"
          \@our_hero = "Harrison Ford"
          show "\hero"



File: gri.info,  Node: Local Synonyms,  Next: If Statements,  Prev: Alias Synonyms,  Up: Synonyms

10.5.5 Local synonyms
---------------------

Local synonyms are created by Gri upon entry to a Gri command.  You use
them to parse the command line that was used in calling the new command,
to look for options, gather filenames, etc.  Local synonyms are known
only from within the local Gri command.  They are not listed by `show
synonyms', but they can be used freely in commands like `show "Number
of words is \.words."'.

   * Within any new Gri command, the number of words in the line that
     called the command is available in `\.words.'.  The RPN operator
     `wordc' also yields the same value (*Note Solitary Operators::).

   * The first word in the calling line is `\.word0.', the second
     `\.word1.', etc.  (Note that this is the C convention, *not* the
     FORTRAN convention.  If `\.words.' is 2, then `\.word0.' and
     `\.word1.' are defined, but `\.word2.', which FORTRAN programmers
     expect, will not be defined.)  If you don't know the place of the
     synonym in advance (i.e. 0 versus 1, for `\.word0.' versus
     `\.word1.'), then use the RPN operator `wordv' instead (*Note
     Unary Operators::).

   * Within any new Gri command, the proper calling usage is available
     in `\.proper_usage.'.  This is useful in tests of syntax (*Note
     Adding New Commands::).  For example:

          `draw depths from \file'
          Draw depth data stored in indicated file.  If the
          filename contains periods or slashes, you'll
          have to enclose it in double quotes, as
          in the second example:
            draw depths from file upper_cove
            draw depths from file ../old_data/upper_cove
          {
            if {rpn \.words. 4 !=}
              show "FATAL ERROR in `\.proper_usage.':"
              show "  Need 4 words; got \.words. words."
              quit
            end if
            # Right number of words, so continue onward...
          }

   These synonyms help you scan for optional words in commands.  Suppose
you have defined a new command `New Thing [option]'.  If you call it
with `New Thing', then (within `New Thing') `\.words.' will be `"2"',
`\.word0.' will be `"New"' and `\.word1.' will be `"Thing"'.  On the
other hand, if you call it with `New Thing 22.3' then `\.words.' will
be `3', `\.word0.' will be `"New"', `\.word1.' will be `"Thing"' as
before, and `\.word2.' will be `"22.3"'.

   *EXAMPLE*  Here is a new command to label lines drawn by `draw
curve':

     `Draw Label For Last Curve "label"'
     Draw a label for the last curve drawn, using
     ..xlast.. and ..ylast.. built-in variables.
     {
       new .draw_label_for_last_curve_graylevel.
       .draw_label_for_last_curve_graylevel. = ..graylevel..
       set graylevel 0
       draw label "\.word5." at \
           {rpn ..xlast.. xusertocm 0.1 + xcmtouser} \
           {rpn ..ylast.. yusertocm \
               ..fontsize.. pttocm 2 / -
               ycmtouser}
       set graylevel .draw_label_for_last_curve_graylevel.
       delete .draw_label_for_last_curve_graylevel.
     }
     open file.dat
     read columns x y
     draw curve
     \label = "Illustration"
     Draw Label For Last Curve "\label"

(Note that Gri has a built-in command `draw label for last curve
"\label"' written much as above, so there is no need for you to enter
this new command into your `.grirc' file.  But you might want to check
`gri.cmd' to see how a full command does checking of the calling syntax
(*Note Invoking Gri::).


File: gri.info,  Node: If Statements,  Next: Loops,  Prev: Local Synonyms,  Up: Programming

10.6 If Statements
==================

Gri has `if' statements to make your programs more flexible.  Here's an
example: 

     query \thick "Use thick lines? (0 or 1)" ("0")
     if \thick
       set line width 2
     else
       set line width 0.5
     end if

If you answer 1 to the question, the line thickness will be set at 2
points.  If you answer 0 then a thin line will be used.  If you press
carriage return a thin line will be used.

   The item following the `if' can be
   * a number (1 means true; anything else means false)

   * a variable (1 means true; anything else means false). Example:

          if .plot_contours.
            draw contour
          end if

   * a synonym which expands to a number (1 means true; anything else
     means false). Example:

          \plot_contours = "1"
          if \plot_contours
            draw contour
          end if

     (Don't worry about the fact that synonyms are strings; Gri expands
     the string value before interpreting the `if' statement.)

   * an expression of the form `{string1 == string2 }'.  The symbol
     `==' is an operator which tests for string equality.  This expands
     to `1' if the strings are equal, or `0' otherwise.  The strings
     may be either synonyms or string constants.  If the string
     constant contains only one word, then it is not necessary to
     enclose it in quotes, but it is clearer to do so.  Examples: 

          if {"\variable" == "Salinity"}
            set x name "Salinity"
          else
            set x name "Unknown"
          end if

   * a rpn (reverse polish notation) expression (*Note rpn
     Mathematics::):

          if {rpn .time. 100 <}
            # ie, (100 < time), not (time < 100)
            show "Time > 100"
          else if {rpn .time. 100 >}
            show "Time < 100"
          else if {rpn "\item" "later" ==}
            show "Time ... later babe"
          else
            show "Time is equal to 100"
          end if
          if {rpn .time. 10 * 100 ==}
            show "Time is equal to 10"
          else
            show "Time is not equal to 10"
          end if


   There is no need to put the else part in if you don't need it. You
can do

     set line width 0.5
     if \use_thick_lines
       set line width 2
     end if

if you wish.

   If you want just the else part, you can do

     if ! \use_thick_lines
       set line width 0.5
     end if

   (The exclamation point denotes logical negation: `! true' equals
`false'.)

   If statements may be nested many levels deep.  You may also have
`else if' blocks, as in:

     if {"\variable" == "S"}
       set x name "Salinity"
       set x axis 32 33 0.5 .1
     else if {"\variable" == "T"}
       set x name "Temperature"
       set x axis 15 20 1 0.5
     else
       set x name "Unknown"
     end if


File: gri.info,  Node: Loops,  Next: Mathematics,  Prev: If Statements,  Up: Programming

10.7 Loops
==========

Gri provides only one type of loop, the `while' loop, described
elsewhere (*Note While::).


File: gri.info,  Node: Mathematics,  Next: rpn Mathematics,  Prev: Loops,  Up: Programming

10.8 Mathematics
================

Gri lets you do some simple mathematical manipulations on your column
and grid data.

10.8.1 Column data
------------------

The column operators are `=', `+=', `-=', `*=', `/=', `^='
(exponentiation) and `_=' (logarithm).  There must be spaces before and
after the operators, but no space between the 2 letters of the
operators. The operations may be applied not only to `x' and `y' as
shown, but also to `z' (used to hold data to be contoured or written as
symbols), and `u' and `v' (used to store vector fields).

   The axis scales are *not* changed by mathematical operations on the
columns, regardless of whether the scales were set manually or by Gri
command (*Note Axis Scaling::).

   Elements of columns are available by the `@' reverse polish operator
(*Note rpn Mathematics::).

   Examples:
   * To multiply all the x data by 10, use `x *= 10'; to add 5 to each
     y-value, use `y += 5'.

   * To set all the y data to 10, do `y = 10'.  (This will only work if
     you've already read column data.)

   See also *Note Tertiary Operators:: for a method of assigning or
altering column data using the RPN operator.

10.8.2 Grid data
----------------

Various commands let you alter grid data as used in contouring (*Note
Contour Plots::).  Possible commands are as follows.

     grid data = number
     grid data += number
     grid data -= number
     grid data *= number
     grid data /= number
     grid data ^= number # take data to power 'number'
     grid data _= number # take log base 'number'
     grid x = number
     grid x += number
     #... others as in `grid data'
     grid y = number
     grid y += number
     #... others as in `grid data'

10.8.2.1 Image data
...................

Various commands let you alter image data (*Note Images::.).  Possible
commands are as follows.

     image += number
     image -= number
     image *= number
     image /= number
     image ^= number # power
     image _= number # logarithm

10.8.2.2 Image grayscale/colorscale
...................................

Various commands let you alter image data (*Note Images::).  Possible
commands are as follows.

     image grayscale += number
     image grayscale  -= number
     image grayscale  *= number
     image grayscale  /= number
     image grayscale  ^= number # power
     image grayscale  _= number # logarithm
     image colorscale += number
     image colorscale  -= number
     image colorscale  *= number
     image colorscale  /= number
     image colorscale  ^= number # power
     image colorscale  _= number # logarithm

10.8.2.3 Variables
..................

Possible commands are:

     .variable. = number
     .variable. += number
     .variable. -= number
     .variable. *= number
     .variable. /= number
     .variable. ^= number # power
     .variable. _= number # logarithm


File: gri.info,  Node: rpn Mathematics,  Next: Stack Operators,  Prev: Mathematics,  Up: Programming

10.9 Rpn (reverse-polish notation) Calculator
=============================================

Gri can do simple mathematics on numbers.  The syntax is reverse-polish
notation (`rpn'), which is used in some calculators.  Most users can
learn rpn in a few minutes, so don't worry if you don't know RPN yet.

   *Syntax*: rpn expressions can be used anywhere Gri expects a number.
RPN expressions start with a opening curly brace (`{') which is
immediately followed by the word `rpn'.  rpn expressions end with a
closing curly brace (`}').  Instead of `set x size 10' you could write
`set x size {rpn 20 2 /}', where the expression `{rpn 20 2 /}' tells
Gri to insert the number 20 onto a stack, then insert the number 2
above it on the stack, and then divide the top two items on the stack.
The following are equivalent:

     set x size {rpn 20 2 /}           # 10 = 20/2
     set x size {rpn 30 2 / 5 -}       # 10 = (30/2-5)
     set x size {rpn pi 3.1415 / 10 *} # 10 = 10*pi/pi

   If an rpn expression contains a variable whose value is "missing",
then the value of the result of the expression will also be missing
(unless the value of the missing variable is thrown away with a "pop"
operator).  However, if a missing value just happens to occur as the
result of an intermediate calculation, then the result is not
considered to be missing.

   RPN operations can be divided roughly into the following groups.

* Menu:

* Stack Operators::             Operate on the rpn stack
* Rpn Functions::               Define a new rpn operator
* Tertiary Operators::          Act on top three items on stack
* Binary Operators::            Act on top two items on stack
* Unary Operators::             Act on top item on stack
* Solitary Operators::          Act alone
* Manipulation of Columns etc:: Act on data columns
* rpn Examples::                A few examples


File: gri.info,  Node: Stack Operators,  Next: Rpn Functions,  Prev: rpn Mathematics,  Up: rpn Mathematics

10.9.1 Stack Operators
----------------------

Stack operators manipulate or display the stack.

   `pop' removes the top item from the stack (*Note Unary Operators::).

   `dup' duplicates the top item on the stack (*Note Unary Operators::).

   `exch' reorders the top two items on the stack (*Note Binary
Operators::).

   `pstack' prints the items on the stack (without changing the stack).

   `roll_right' rolls the items to the right.

   `roll_left' rolls the items to the left.

   For example, the following shows how you might use `exch' or
`roll_right' to change the sense of a subtraction.

     show {rpn 1 2            -} " ... yields -1"
     show {rpn 1 2 exch       -} " ... yields  1"
     show {rpn 1 2 roll_right -} " ... yields  1"


File: gri.info,  Node: Rpn Functions,  Next: Tertiary Operators,  Prev: Stack Operators,  Up: rpn Mathematics

10.9.2 Rpn function Operators
-----------------------------

`rpnfunction' operators are user-defined operators.  The parser
replaces any such operator with the user-defined rpn expression.  The
`rpnfunction' operators are both general and powerful.  An
`rpnfunction' may be composed of any legal primitive rpn constructs or
even other legal `rpnfunction' constructs.  For details, (*Note
Rpnfunction::).


File: gri.info,  Node: Tertiary Operators,  Next: Binary Operators,  Prev: Rpn Functions,  Up: rpn Mathematics

10.9.3 Tertiary Rpn Operators
-----------------------------

`{rpn 0 4 "hello" substr }'
     Extract 4 characters from the indicated string, starting at
     character number 0 (i.e. the start of the string).  In other
     words, replace the three items on the top of the stack with the
     single item `\"hell\"'.


File: gri.info,  Node: Binary Operators,  Next: Unary Operators,  Prev: Tertiary Operators,  Up: rpn Mathematics

10.9.4 Binary Operators
-----------------------

Binary operators act on the *top two* items on the stack.  Most binary
operators replace two items on the stack with one item, e.g.  `{rpn 1 2
/}' yields 0.5.  However, a few binary operators replace one pair of
items with a new pair of items, e.g. the `xyusertocm' operator replaces
an (x,y) pair in user coordinates with an (xcm,ycm) pair in coordinates
of centimeters on the page.

   The binary operators are illustrated below, in rough alphabetical
order.

`{rpn 3 2 +}'
     Add 2 to 3.

`{rpn 3 2 -}'
     Subtract 2 from 3.

`{rpn 3 2 *}'
     Multiply 3 by 2.

`{rpn 3 2 /}'
     Divide 3 by 2.

`{rpn 3 2 <}'
     Test whether 2 is less than 3, yielding 1.  Note: this convention
     may be confusing to users who are familiar with HP calculators from
     decades past.  Present-day calculators use this convention, but
     possibly older calculators used the reverse convention, using `>'
     where Gri uses `<'.

`{rpn 3 2 <=}'
     Test whether 2 is less than or equal to 3.

`{rpn 3 2 >}'
     Test whether 2 is greater than 3, yielding 0.

`{rpn 3 2 >=}'
     Test whether 2 is greater than or equal to 3, yielding 0.

`{rpn 3 2 ==}'
     Test whether 2 and 3 are equal, yielding 0.  (Do not confuse this
     with the asignment operator `=', described next.)

`{rpn 10 ".ten." =}'
     Assign the value `10' to the variable named `.ten.'.  The variable
     name must be put in quotes, or else Gri will insert the value of
     the variable (if it exists) into the expression, instead of trying
     to assign to it.

     After the assignment is done, the stack is cleared of both the
     value and the variable name.  For example, in the following code
          {rpn 3.1415 ".pi." =}
          show .pi.
     the first line evaluates to a blank line, and the second prints
     the value of Pi.

     NOTE: Do not confuse this with the `==' equality operator
     described above.

`{rpn "hello" "\\greeting" =}'
     Assign the value `"hello"' to the synonym `\greeting'.  See notes
     at the above item.

`{rpn 3.14159 0 "x" =}'
     Assign the value Pi to the first element (at index `0') of the `x'
     column.  All columns may be assigned to in this way, e.g.  the
     following is a technique for plotting a quadratic function:
          .i. = 0
          .n. = 10
          while {rpn .i. .n. >}
              {rpn .i. .n. 1 - /     .i. "x" =}
              {rpn x .i. @ 2 power  .i. "y" =}
              .i. += 1
          end while
          draw curve

`{rpn 0 1 &}'
     Test whether 0 and 1 are both true, yielding 0.

`{rpn 0 1 and}'
     Test whether 0 and 1 are both true, yielding 0.

`{rpn y x area}'
     Calculate the area under the curve y=y(x).  For details (*Note
     Manipulation of Columns etc::).

`{rpn 0 1 |}'
     Test whether either 0 or 1 is true, yielding 1.

`{rpn 0 1 or}'
     Test whether either 0 or 1 is true, yielding 1.

`{rpn 2 3 exch}'
     Exchange 2 and 3 on the stack, yielding `3 2' on the stack.  (See
     also `pop' and `dup'.)

`{rpn x 0 @}'
     Yields the value of the first number in the x column.  A similar
     form also works for `y', etc.  (*Note Manipulation of Columns
     etc::).

`{rpn 2 3 inf}'
     Pick the smaller of two values, yielding 3.  (Opposite to `sup'.)

`{rpn 2 3 power}'
     Take 2 to the 3rd power, yielding 8.  Note: This convention may be
     confusing to users who are familiar with HP calculators from
     decades past.  Present-day calculators use this convention, which
     they write as `y^x', but older calculators used the reverse
     convention, labelling the key `x^y'.

`{rpn 2 3 remainder}'
     Calculate the remainder after dividing 2 by 3, yielding 2.  The
     return value for `{rpn A B remainder}' is `B - n * A', where `n' is
     the quotient of `A/B', rounded towards zero to an integer.  In this
     case, `2/3' rounds to an `n' value of zero, yielding 2 as the
     resulting remainder.

`{rpn "heLLo" "s/L/l/g" sed}'
     Switch all instances of `L' into `l', yielding the string
     `"hello"' on the stack.  This can be helpful for working with
     filenames, etc.  The work is preformed with a system call to the
     `sed' utility (present on unix systems), and therefore this
     command will fail if `sed' is not installed, or if the OS cannot
     be contacted.

`{rpn "file" ".dat" strcat}'
     Concatenate the two strings, yielding the string `"file.dat"'.

`{rpn 2 3 sup}'
     Pick the larger of two values, yielding 3.  (Opposite to `inf'.)



File: gri.info,  Node: Unary Operators,  Next: Solitary Operators,  Prev: Binary Operators,  Up: rpn Mathematics

10.9.5 Unary Operators
----------------------

Unary operators replace the last item on the stack with another item.
For example, the `sin' operator takes the sine of the number on the top
of the stack; e.g., `{rpn 45 sin}' yields the sine of 45 degrees.

   The unary operators are illustrated below, in rough alphabetical
order.

`{rpn 0 !}'
     Replace 0 (false) with its logical negation 1 (true).

`{rpn 0 not}'
     Replace 0 (false) with its logical negation 1 (true).

`{rpn -3 abs}'
     Calculate the absolute value of `-3'.

`{rpn 0.5 acos}'
     Calculate the inverse cosine of 0.5, yielding 60 (degrees).

`{rpn 2 acosh}'
     Calculate the inverse hyperbolic cosine of 2, yielding 1.317.
     (Note: argument must equal or exceed 1, or an error results.)

`{rpn "filename" age}'
     Calculate the "age" of the indicated file, in seconds.  An age of
     zero indicates that the file was created, or last modified, within
     1 second of the execution of the `age' operator.

     On unix (and similar) machines, the calculation is done on unix
     machines with the `stat()' subroutine.  On other machines, the
     `age' operator may cause an error.

     The age of a non-existent file is reported as the number of seconds
     since the system clock's reference time, i.e. since 1970-jan-1 on
     unix machines.  This convention is so that scripts like that in
     the example below will work as intended.

     A typical use of this command is the creation of data-files from
     shell scripts, as illustrated below.  The idea is to update (or
     create) the file `file.dat' using the system-executable script
     `creator.pl', but only to do so if `creator.pl' is younger than
     `file.dat'.
          if {rpn "file.dat" age "creator.pl" age <}
             system "./creator.pl > file.dat"
          end if
          open file.dat
     For the convenience in such usage, a non-existent file is assigned
     the maximum possible file age on the given OS, e.g. on a unix
     machine, the age is reported as though the non-existent file had
     been created on January 1, 1970 on a unix machine.

`{rpn 0.5 asin}'
     Calculate the inverse sine of 0.5, yielding 30 (degrees).

`{rpn 1 atan}'
     Calculate the inverse tangent of 1, yielding 45 (degrees).

`{rpn 0.5 atanh}'
     Calculate the inverse hyperbolic tangent of 0.5, yielding 0.549306
     (radians).

`{rpn 0 argv}'
     Returns the name of the Gri command-file, which is considered as
     the first "optional" argument.  (It may seem odd that the name of
     the command-file is considered an option, but Gri does this for
     consistency with C and other languages.  It is useful.)  Other
     arguments provided when Gri was invoked are provided as `rpn 1
     argv', etc.

     A string consisting of a single blank character results if one
     tries to access beyond the list of arguments that were actually
     supplied.  See also the `argc' solitary operator (*Note Solitary
     Operators::), which returns the number of optional arguments.

     For example, if Gri is invoked as

          gri myscript.gri file1.dat file2.dat

     and if `myscript.gri' contained

          .n. = {rpn argc}
          .i. = 0
          while {rpn .n. .i. <}
              show "argument " .i. " is " {rpn .i. argv}
              .i. += 1
          end while

     then the output would be

          argument 0 is myscript.gri
          argument 1 is file1.dat
          argument 2 is file2.dat

     For usage within the Emacs gri-mode, see *Note Filename arguments
     when running gri::.

`{rpn "hi" ascent}'
     Determine ascent of this string (in cm), in the present font and
     fontsize.  (See also `descent' and `width'.)

`{rpn "3.1" atof}'
     Calculate the numerical value contained in indicated string.

`{rpn 1.5 ceil}'
     Calculate the next higher integer, yielding 2.  (Opposite of
     `floor'.)

`{rpn 45 cos}'
     Calculate the cosine of 45 degrees, yielding 0.707.

`{rpn 1 cosh}'
     Calculate the hyperbolic cosine of 1 (radian), yielding 1.543.

`{rpn 1 cmtopt}'
     Convert from 1 centimeter to so-called "point" units, yielding
     28.45.  (Opposite of `pttocm'.)

`{rpn 170 dec2hex}'
     Convert a number into a string which is its hexadecimal
     representation.  Before the conversion, the number is rounded to
     the nearest integer, and if the result is negative, an error
     results.  The string is double-quoted, with letters (if there are
     any) being in upper case.

     For example `\hex = {rpn  63  dec2hex}' is equivalent to `\hex =
     "3F"'.

     Compare with `hex2dec', the inverse.

`{rpn "\\syn" defined}'
     Test whether the synonym is defined at the moment, returning 1 if
     so and 0 if not.  (Note the double-backslash in the synonym name,
     which is required.)

`{rpn ".var." defined}'
     Test whether the variable is defined at the moment, returning 1 if
     so and 0 if not.

`{rpn "\\@alias" defined}'
     Test whether the variable/synonym item that is named by the alias
     (*Note Alias Synonyms::) is defined at the moment, returning 1 if
     so and 0 if not.

`{rpn "hi" descent}'
     Calculate the descent (below the baseline in cm) for the given
     string, in the present font and fontsize.  (See also `ascent' and
     `width'.)

`{rpn "/home/me/data/timeseries" directory_exists}'
     Determine whether indicate directory exists, yielding `1' if it
     does and `0' otherwise.  (See also `file_exists'.)

`{rpn 2 dup}'
     Duplicate the top item on stack, yielding `2 2' on the stack.
     (See also `exch' and `pop'.)

`{rpn 1 exp}'
     Calculate the value of `e' raised to the indicated power, yielding
     2.71828.

`{rpn 2 exp10}'
     Calculate the value of `10' raised to the indicated power,
     yielding 100.

`{rpn "foo.dat" file_exists}'
     Determine whether the indicate file exists, yielding `1' if it does
     and `0' otherwise.  (See also `directory_exists'.)

`{rpn 1.5 floor}'
     Calculate the nearest smaller integer, yielding 1.  (Opposite of
     `ceil'.)

`{rpn "AA" hex2dec}'
     Convert a string, representing a hexadecimal value, into an
     integer.  The string must be double-quoted, and it may contain
     either lower- or upper-case letters; this is in contrast to the
     inverse function, `dec2hex', which returns upper-case.

     This operator is most often used in working with colours, since Gri
     handles colour components in decimal terms, whereas many other
     applications refer to the components in hexadecimal notation.

     Compare with `dec2hex', the inverse.

`{rpn 3 ismissing}'
     Yields 1 if the indicated value is a "missing value" or 0
     otherwise.

`{rpn 100 log}'
     Calculate the base-10 logarithm of 100, yielding 2.

`{rpn 10 ln}'
     Calculate the natural logarithm of 10, yielding 2.30259.

`{rpn x mean}'
     Yields the mean value of the (non-missing) numbers in the x
     column.  A similar form also works for `y', etc.  (*Note
     Manipulation of Columns etc::).

`{rpn x max}'
     Yields the largest value of the (non-missing) numbers in the x
     column.  A similar form also works for `y', etc.  (*Note
     Manipulation of Columns etc::).

`{rpn x min}'
     Yields the smallest value of the (non-missing) numbers in the x
     column.  A similar form also works for `y', etc.  (*Note
     Manipulation of Columns etc::).

`{rpn 28.45 pttocm}'
     Calculate the number of centimeters in 28.45 printers points,
     yielding 1.  (Opposite of `cmtopt'.)

`{rpn 1 2 pop}'
     Remove the top item from the stack, yielding `1' on the stack.
     Generates an error if the stack is empty.  (See also `exch' and
     `dup'.)

`{rpn 4 sqrt}'
     Calculate the square root of 4, yielding 2.  (Negative arguments
     yield errors.)

`{rpn 45 sin}'
     Calculate the sine of 45 (degrees), yielding 0.707107.

`{rpn 2 sinh}'
     Calculate the hyperbolic sine of 2, yielding 3.62686.

`{rpn "hello" strlen}'
     Determine the number of characters in string, e.g. 6 here.

`{rpn "date" system}'
     Call the indicated system function and insert its ouput on the
     stack, yielding the date as a character string.

`{rpn 45 tan}'
     Calculate the tangent of 45 (degrees), yielding 1.

`{rpn tanh}'
     Calculate the hyperbolic tangent of 2, yielding 0.964028.

`{rpn "hi" width}'
     Determine width of this string (in cm), in the present font and
     fontsize.  (See also `ascent' and `descent'.)

`{rpn 0 wordv}'
     Returns the first word used in invoking the present command.
     Similar to the `\.word0.' synonym (*Note Local Synonyms::).
     Example:

          `let us test .it.'
          {
            .w. = 0
            while {rpn .w. wordc >}
              show "The " .w. "-th word is `" {rpn .w. wordv} "'."
              .w. += 1
            end while
          }
          let us test "this thing"
          let us test "this" "thing"
          let us test "Pi is" {rpn 3.14}

     If you are using this to parse options given to the command, it is
     up to you to skip the non-optional words in the command.  In this
     case, for example, we skipped the first three words (`let', `us',
     and `test').

`{rpn 1 xusertocm}'
     Calculate the x coordinate, in centimeters measured from left-hand
     side of page, corresponding to a user-value of x=1.  (Opposite of
     `xcmtouser'.)

`{rpn 1 xcmtouser}'
     Calculate the x value, in user units, for a point that is 1
     centimeter from the left-hand edge of the paper.  (Opposite of
     `xusertocm'.)

`{rpn 1 yusertocm}'
     Calculate the y coordinate, in centimeters measured from bottom
     side of page, corresponding to a user-value of x=1.  (Opposite of
     `ycmtouser'.)

`{rpn 1 ycmtouser}'
     Calculate the y value, in user units, for a point that is 1
     centimeter from the bottom edge of the paper.  (Opposite of
     `yusertocm'.)



File: gri.info,  Node: Solitary Operators,  Next: Manipulation of Columns etc,  Prev: Unary Operators,  Up: rpn Mathematics

10.9.6 Solitary Operators
-------------------------

Solitary operators do not act on items on the stack; rather, they
generate items themselves and insert them on the stack.

   The solitary operators are illustrated below, in alphabetical order.

`{rpn argc}'
     Yields number of command-line arguments given by the user when Gri
     was invoked.  Thus, invoking Gri as

          gri myfile.gri file1.dat file2.dat

     yields 3, for arguments `myfile.gri', `file1.dat', and
     `file2.dat'.  These arguments are accessible through the `argv'
     unary operator (*Note Unary Operators::).

`{rpn e}'
     Yields the base of natural logarithms, i.e. `2.718'...

`{rpn pi}'
     Yields Pi, i.e. `3.141'...

`{rpn rand}'
     Generate a random number in the range 0 to 1, using the C
     subroutine `drand48()' if it is available, otherwise the less
     well-distributed `rand()' subroutine.

`{rpn wordc}'
     Returns number of words used in invoking the present command.
     Similar to the `\.words.' synonym (*Note Local Synonyms::).
     Example:

          `let us test .it.'
          {
            show "This command has " {rpn wordc} " words"
          }
          let us test 10
          let us test {rpn 3 1 +}
          let us test "this"
          let us test "this thing"

     The operator `wordv' may be used to extract the words of the
     command (*Note Unary Operators::).


File: gri.info,  Node: Manipulation of Columns etc,  Next: rpn Examples,  Prev: Solitary Operators,  Up: rpn Mathematics

10.9.7 Manipulation of Columns etc
----------------------------------

10.9.7.1 Columns
................

Individual data in the `x', `y', `z', `u', `v' and `weight' columns can
be accessed with the `@' operator.  The first point has index 0.
Examples:

     show "first x is " {rpn x 0 @ }
     show "last  x is " {rpn x ..num_col_data.. 1 - @ }
     show "and here are all the data:"
     .i. = 0
     while {rpn .i. ..num_col_data.. >}
         show {rpn x .i. @ }
         .i. += 1
     end while

   The mean value is available from the `mean' operator (e.g., `.xmean.
= {rpn x mean }', while the standard deviation is given by `stddev',
the skewness is given by `skewness', and the kurtosis is given by
`kurtosis' (using the definition that yields 3 for a gaussian
distribution).

   The minimal and maximal values are given by `min' and `max'.

   The area under the curve y=y(x) is found by `{rpn y x area }',
defined by `0.5 * sum ( (y[i] + y[i-1]) * (x[i] - x[i-1]) )' for `i'
ranging from 1 to `..num_col_data..'-1.

10.9.7.2 Grid
.............

Grid data can be accessed with e.g. `{rpn grid min } ', `{rpn grid max
} ', and `{rpn grid mean } '.

   The value of the grid at a given `(.x.,.y.)' coordinate may be found
by by e.g. `{rpn grid .x. .y. interpolate}'.  The interpolation scheme
is the same as that used in converting grids to images.


File: gri.info,  Node: rpn Examples,  Next: Text,  Prev: Manipulation of Columns etc,  Up: rpn Mathematics

10.9.8 rpn Examples
-------------------

Here are some reverse-polish expressions and the corresponding algebraic
interpretations:

   * `{rpn 1 2 + 10 / }' = (1+2)/10

   * `{rpn .a. .b. + .c. + .d. / }' = (.a.+.b.+.c.)/.d.

   * `{rpn e 2 / }' = e/2 (Gri knows values of "e" and "pi")

   * `{rpn 23 sin 100 * 12 cos + }' = cos(12) + 100sin(23)

   * `{rpn 5 2 power }' = 25

   * `{rpn 2 log exp }' = exp(log 2)

   * `{rpn 2 ln exp10 }' = 10^ln2

   * `{rpn 1.7 floor }' = 1 (rounds down to nearest integer.  Note that
     the floor of -1.7 is -2)

   * `{rpn 10.1 2 remainder }' = 0.1 (remainder of 10.1 after division
     by 2; see C function `remainder(x,y)')

   * `{rpn -10.1 2 remainder }' = -0.1

   * `{rpn -10.1 -2 remainder }' = -0.1

   * `{rpn .num. 10 > }' = 1 if 10 exceeds .num., or 0 otherwise

NOTES:
   * The units of `sin', `cos', etc, are degrees, not radians.

   * The scales of the plot are accessible to `rpn'.  For example, with
     the command

          draw label "hi" at 10 20

     you draw the indicated string at the indicated location in user
     coordinates.  To put it 0.15 centimetres to the right of this
     location and 0.1 centimetres lower, you could do as follows:

          draw label "\label" at \
              {rpn .x. xusertocm 0.15 + xcmtouser} \
              {rpn .y. yusertocm 0.10 - ycmtouser}

     (Note that the x and y scales have individual translations from
     "user" to "cm" coordinates.)

   * Some conversion factors are built into `rpn'; `cmtopt' converts
     from centimetres to points (by dividing by 28.45; the conversion
     factor to inches is 72.27) while `pttocm' converts from points to
     centimetres.  For example, here is how to label a data curve with
     a label placed near the last y-value of the data set: 

          draw curve
          .y. = {rpn ..ylast.. yusertocm 0.5 - ycmtouser}
          draw label "Smoothed" at ..xlast.. .y.



File: gri.info,  Node: Text,  Next: Embedded Synonyms,  Prev: rpn Examples,  Up: Programming

10.10 Text Strings
==================

Any text can be drawn in any size; Gri does not limit font size to a
list, e.g. 10 point, 12 points, etc.  Several fonts are available in
Gri, e.g. Times, Helvetica, etc.; these are all standard PostScript
fonts.  Support for some non-English languages (e.g. French) is also
provided.  And, finally, Gri supports inclusion of simple mathematical
expressions (Greek letters, superscripts, etc.) in text, using a
LaTeX-style syntax.

* Menu:

* Embedded Synonyms::           Embedding synonyms in text strings
* Mathematical Text::           Mathematical symbols and Greek letters
* Non-English Text::            French, etc.
* Adjustment Of Character Position:: thinspaces


File: gri.info,  Node: Embedded Synonyms,  Next: Mathematical Text,  Prev: Text,  Up: Text

10.10.1 Embedding synonyms in quoted text strings
-------------------------------------------------

*Outside* math strings, you can embed your synonyms at will.  For
example, you can include the name of a data file in the title of your
plot as follows 

     query \filename "File to read from?" ("data.file")
     open \filename
     read columns x y
     draw curve
     draw title "data from \filename"

   Within math strings (ie, between matched dollar-signs), these
synonyms are disabled, and only the mathematical symbols and Greek
letters work.


File: gri.info,  Node: Mathematical Text,  Next: Non-English Text,  Prev: Embedded Synonyms,  Up: Text

10.10.2 Mathematical text
-------------------------

10.10.2.1 Subscripts
....................

As in TeX and LaTeX, you must be in math-mode to use subscripts; in
other words, you must enclose the string or substring in dollar-signs.
For single-character subscripts, insert an underline prior to the
character to be subscripted:

     draw title "$a_2$"

For multiple-character subscripts, insert braces before and after the
item to be subscripted:

     draw title "$a_{22}$"

10.10.2.2 Superscripts
......................

As in TeX and LaTeX, you must be in math-mode to use superscripts; in
other words, you must enclose the string or substring in dollar-signs.
For single-character superscripts, insert a carat prior to the
character to be superscripted:

     draw title "$a^2$"

For multiple-character superscripts, insert braces before and after the
item to be superscripted:

     draw title "$a^{22}$"

10.10.2.3 Mathematical symbols
..............................

As in TeX and LaTeX, you indicate mathematical symbols and Greek
letters with backslash sequences.  The following LaTeX symbols are
defined in math mode in Gri (cf tables in Lamport's section 3):

     \Delta \Downarrow \Gamma \Im \Lambda \Leftarrow
     \Leftrightarrow \Omega \Pi \Phi \Psi \Re
     \Rightarrow \Sigma \Theta \Uparrow \Upsilon \Xi
     \alpha \approx \ast \beta \bullet \chi \circ
     \cong \delta \div \downarrow \epsilon \equiv
     \eta \exists \forall \gamma \geq \gg \in \infty
     \iota \kappa \lambda \langle \leftarrow
     \leftrightarrow \leq \ll \mu \nabla \neq \nu
     \omega \partial \phi \pi \pm \prod \propto \psi
     \rangle \rho \rightarrow \sigma \sim \subset
     \subseteq \sum \supset \supseteq \surd \sqrt
     \tau \theta \times \uparrow \upsilon \varpi
     \wedge \xi \zeta \vartheta \varsigma \varphi
     \aleph \oplus \otimes \wp \prime \emptyset
     \angle \neg \clubsuit \diamondsuit \spadesuit
     \cdot \lfloor \lceil \rceil \rfloor

For example, you might use these as follows:

     draw title "$\alpha$ = thermal expansion coefficient"

   Sometimes you'll want a mathematical symbol to be adjacent to a
normal text string, with no space between.  You can do this by
enclosing in braces, as in LaTeX.

   TeX and LaTeX handle combinations of superscripts and subscripts
very cleanly, putting one above the other.  Presently, Gri does not do
this; for example `set x name "$A_1^2$"' will have the 2 appearing to
the right of the 1 instead of above it.  Proper positioning will be
added to a later version of Gri, but in the meantime you can achieve the
desired effect with the TeX "negative thinspace" psuedo-character in
math-mode.  Using this feature will not hurt you when the new Gri
becomes available.  The symbol for a negative thinspace is `\!' in
math-mode.  It has no meaning in nonmath mode.  A thinspace is 1/6 of an
"em-space" (a TeX term, normally equal to the width of the character
"M" in the current font).  In most fonts, numbers are half the width of
the letter "M", so that 3 negative thinspaces will move leftward over a
single number.  Thus, if the example above becomes `set x name
"$A_1\!\!\!^2"', the 2 will be positioned above the 1.  (Equivalently,
you could write `set x name "$A^2\!\!_1$"'.)  Depending on the actual
characters you have in the super/subscripts, you might need more or
less thinspaces; some experimentation might be required.  Also, note
that the symbol `\,' in math mode is a positive thinspace (which moves
the next character a little bit to the right).  Thus, you can add a
little extra spaces between characters by doing something like `set x
name "A$\,$B"'.

   To get a hat over a single character, do something like the following
(which draws a hat over the character "h"): 

     draw label "h${\!\!\!^{^\wedge}}$" at 10 12 cm

   To get an overbar on a rho, do this:

     draw label "$\rho\!\!\!\!^-$" at 3 3 cm


File: gri.info,  Node: Non-English Text,  Next: Adjustment Of Character Position,  Prev: Mathematical Text,  Up: Text

10.10.3 Non-English characters
------------------------------

Gri relies on the "standard" PostScript fonts, however, and it suffers
all limitations of these fonts.

   Gri supports both English and some other European-derived languages,
permitting text with accents on letters.  (It does not support Oriental
or other languages at this time.)  The accents are supported by using
the so-called ISO-Latin-1 font-encoding scheme (also called the
ISO-8859-1 scheme), and so, from what the author can gather from his
reading, Gri should support various languages from western European,
e.g. English, French, Spanish, Catalan, Basque, Portuguese, Italian,
Albanian, Rhaeto-Romanic, Dutch, German, Danish, Swedish, Norwegian,
Finnish, Faroese, Icelandic, Irish, Scottish, and as well as Afrikaans
and Swahili.

   Gri uses the ISO-Latin-1 font encodings by default, although the
so-called `standard' font-encoding may also be selected with the `Set
Font Encoding' command (*Note Set Font Encoding::).  For more on font
encodings see any book on PostScript fonts ... although the bottom line
is that if you are using accented characters in your work, then you
probably already know about encodings, and if you don't use accents
then you needn't learn about this topic except for the pleasure of
learning about other languages.

   The method of handling accented characters is very simple.  If you
can type it, Gri can draw it!  It is up to you to determine how to
enter the accents.  Most text editors permit this.  Since many users
will prefer the Emacs editor, a few words about that are in order.

   For complete information about entering iso-latin-1 characters in
Emacs, consult your Emacs manual in the section *Note
(emacs)Single-Byte Character Support:: which describes the available
methods suitable for the Emacs version you are using.  A few examples
are nevertheless provided below.

   Consider the task of inserting French text, with the Emacs
text-editor. There are several ways of doing this (and you may wish to
consult your emacs info manual).  A method that works in emacs-19 up to
current emacs-20 versions uses the emacs `iso-transl.el' package by
putting the following in your `~/.emacs' file:

     (require 'iso-transl)
     (iso-transl-set-language "French")
     (standard-display-european t)

   Loading the iso-transl package defines three ways of entering the
non-ASCII printable characters with codes above 127: the prefix `C-x
8', or the <Alt> key, or a dead accent key.  For example, you can enter
uppercase A-umlaut as `C-x 8 " A' or `Alt-" A' (if you have an Alt key)
or `umlaut A' (if you have an umlaut/diaeresis key).

   A more recently introduced method is to enter the mode which allows
quick insertion of iso-latin-1 characters. Do the Emacs command `M-x
iso-accents-mode' (either manually, or in a hook that's done
automatically). Now, suppose the x-axis is to represent temperature. All
you'd have to do is type in the command

     set x name "Temp'erature"

   As you type, the quote mark will dissappear, and reappear as an
accent on the `e'.  And then, Gri will recognize this accented `é', and
it will draw the accent on the axis label.

   Perhaps the future default way of accomplishing this task is to use
MULE support directly.  First, customize MULE using `M-x
customize-group RET mule' setting the `current language environment'
(e.g. latin-1) and the `default input method' (e.g. latin-1-prefix).
Then, invoking `M-x toggle-input-method' (e.g. <C-\>) toggles into a
mode similar to the `iso-accents-mode' minor-mode described above.


File: gri.info,  Node: Adjustment Of Character Position,  Next: Adding New Commands,  Prev: Non-English Text,  Up: Text

10.10.4 Adjustment Of Character Position
----------------------------------------

Micro-positioning is available within math-mode, via the symbols `\!'
(which means go left one thin-space) and `\,' (which means go right one
thin-space).  (A thin-space is 1/6 the width of the letter "M").


File: gri.info,  Node: Adding New Commands,  Next: Purpose,  Prev: Adjustment Of Character Position,  Up: Programming

10.11 Adding new commands to Gri
================================

Gri provides so-called "newcommands" as a sort of subroutine syntax on
steroids.

* Menu:

* Purpose::                       What newcommands are for
* Parsing::                       How Gri parses commands
* Simple New Command::            Simple example of adding new command
* Complicated New Command::       More complicated example
* Changeable Command Arguments::  The &.var. and &\syn syntax


File: gri.info,  Node: Purpose,  Next: Parsing,  Prev: Adding New Commands,  Up: Adding New Commands

10.11.1 Purpose of newcommands
------------------------------

Gri can be extended easily.  Primitive commands (e.g. `set x name') can
be supplemented with so-called "new commands."  New commands are a
little like subroutines other programming languages.  For example, you
might find that you often draw filled curves with a particular graylevel
(say 0.5), and then return the graylevel to the previous value.  This
requires you to do the following each time:

     new .old_graylevel.
     .old_graylevel. = ..graylevel..
     set graylevel 0.5
     draw curve filled to 0 y
     set graylevel .old_graylevel.
     delete .old_graylevel.

This gets a bit tedious, and it would obviously be nicer to just say
something like

     Draw my kinda curve

   To make this shortcut, you'd tell Gri about the existence of a new
command called `Draw my kinda curve', and tell it that the new command
can be accomplished by the longer code fragment written above.

   Once you've learned how to make new commands, you are likely to use
them a lot.  The following explains how you add new commands.  For
advice on programming style, etc., (*Note Resource File::).


File: gri.info,  Node: Parsing,  Next: Simple New Command,  Prev: Purpose,  Up: Adding New Commands

10.11.2 How Gri parses commands
-------------------------------

Whenever Gri reads a command line, it compares it with its list of
commands.  This list is searched in this order: (1) the universal
`gri.cmd' file (*Note Invoking Gri::), (2) your resource file (*Note
Resource File::), if it exists, and then (3) your command file itself.
Gri stops searching when it finds a Gri command that matches the
command line.  "Matching" means that the command line is identical in
all words in a Gri command, scanning from the left, until it encounters
a word containing
   * A quote (e.g. `"string"')

   * A synonym name (e.g. `\file')

   * A variable name (e.g. `.number.')

   * An opening square bracket (e.g. `[option]')

   * An opening brace (e.g.  `{a|b}')

   * A choice between two items (e.g.  `first|second')

   * A variable-name with a `&' character immediately to the left (e.g.
     `&.var.').  This is a signal that the variable may be changed
     inside the newcommand (*Note The Ampersand Syntax::).

   * A synonym-name with a `&' character immediately to the left (e.g.
     `&\syn').  This is a signal that the synonym may be changed inside
     the newcommand (*Note The Ampersand Syntax::).

   When Gri finds a command that matches your command line, it assumes
that this is the intended command, and searches no further.  This means
that you must be careful not to have your command hidden by other
commands.  For example, if your resource file contained these lines,
Gri would *never* execute the second new command, because calls to it
match the first command.  To avoid this, you may either reverse the
order of the definitions, so that Gri will find the proper routine, or
rename one of the routines.

     `Draw foo'
     Draw a foo.
     {
       show "drawing a foo"
     }
     `Draw foo bar'
     Draw a foo bar.
     {
       show "drawing a foo bar"
     }

   Gri searches the `gri.cmd' file first, so any new command that you
create that clashes with built-in commands will be ignored by Gri
(*Note Invoking Gri::).  Gri will warn you of this, and proceed,
ignoring your newer definition.  To get around this, you can use
capital letters to begin the words of your new command.  By convention,
Gri never uses capital letters in this way, so a clash is impossible
(except with any similar command you might have defined previously,
such as in your `~/.grirc' file).


File: gri.info,  Node: Simple New Command,  Next: Complicated New Command,  Prev: Parsing,  Up: Adding New Commands

10.11.3 Simple example of a new command
---------------------------------------

To make a new command called `Show The Time' insert the following into
your `~/.grirc' resource file or into your command-file somewhere near
the top, or at least before you use the command.

     `Show The Time'
     New command to show the time of day.
     {
       show "\.time."
     }

EXPLANATION:
   * The name of the new command is enclosed in angled single-quote
     marks.  The words of the new command should begin with upper-case
     letters to prevent a name clash with a present or future built-in
     Gri command.  *Formatting convention:* Make sure that the entire
     definition string, from the opening angled quote to the ending
     angled quote, appears on one line.  Otherwise Gri will give an
     error like

          ERROR: Can't extract syntax for new command

   * Following the name line, you may optionally insert any number of
     lines which will become the `help' information for the new
     command.  See the file `gri.cmd' for the recommended stylistic
     conventions in writing help information (*Note Invoking Gri::). If
     your `help' text includes an example that uses an opening brace
     (`{') you must escape the brace with a backslash, e.g. (`\{').

   * Following the help lines, if they exist, the body of the new
     command is given, sandwiched between a starting line containing an
     opening brace (`{') as the *only* nonwhite character, and an
     ending line containing a closing brace (`}') as the only nonwhite
     character.  Any valid Gri commands may be used in the body of the
     new command.  It is acceptable to use other new commands in the
     body. Recursion is also allowed - a new command is allowed to call
     itself (although there is a limit on nesting, of perhaps a
     thousand or so; this varies with the version of Gri).  *Formatting
     convention:* It is usual, but not necessary, to use an indentation
     level of 2 spaces in the body of the new command.
   The new command is invoked by `Show The Time'.  Help for the command
is found by `help Show The Time' or `help Show'.


File: gri.info,  Node: Complicated New Command,  Next: Changeable Command Arguments,  Prev: Simple New Command,  Up: Adding New Commands

10.11.4 Complicated example of a new command
--------------------------------------------

The following example from the global `gri.cmd' file illustrates how to
parse/check the commandline (*Note Local Synonyms::), which is a good
practice in any code you expect to re-use.  The first `if' statement
checks that the word `at' is in the right place (this would not have
been checked by the syntax matcher, the word having followed a string).
The presence of the keyword `cm' is checked for, and user units or cm
units are used accordingly.  Local variables are created (`new') and
then destroyed (`delete') so that this new command cannot affect
outside code.

     `draw label whiteunder "\string" at .xleft. .ybottom. [cm]'
     Draw label for plot, located with lower-left corner
     at indicated (x,y) position (specified in user
     units or in cm on the page).  Whiteout is used
     to clean up the area under the label.  BUGS:
     Cannot handle angled text; doesn't check for
     super/subscripts.
     {
         if {rpn "\.word4." "at" !=}
           show "ERROR: 5th word must be `at', not `\.word4.'"
           show traceback
           quit
         end if
         new .x. .y. .oldgray. .space.
         if {rpn \.words. 7 ==}
           .x. = {rpn \.word5. xusertocm}
           .y. = {rpn \.word6. yusertocm}
         else if {rpn \.words. 8 ==}
           if {rpn "\.word7." "cm" !=}
             show "ERROR: Require 8th word to be `cm'"
             show traceback
             quit
           end if
           .x. = \.word5.
           .y. = \.word6.
         else
           show "ERROR: Require 7 or 8 words, not \.words."
           show traceback
           quit
         end if
         # Coordinates now in cm.  Next, white out a box
         # under the text (and .space. centimetres
         # beyond text), then draw label.
         .space. = 0.1               # Space of 1mm
         .oldgray. = ..graylevel..
         set graylevel white
         draw box filled                          \
           {rpn .x. .space. -}                    \
           {rpn .y. .space. -}                    \
           {rpn .x. "\.word3." width + .space. +} \
           {rpn .y. "M" ascent + .space. + } cm
         set graylevel .oldgray.
         draw label "\.word3." at .x. .y. cm
         delete .x. .y. .oldgray. .space.
     }


File: gri.info,  Node: Changeable Command Arguments,  Next: The Ampersand Syntax,  Prev: Complicated New Command,  Up: Adding New Commands

10.11.5 Altering command arguments - the `&' syntax
---------------------------------------------------

The Gri language permits a newcommand to change variables and synonyms
passed as arguments, using a syntax that is quite similar to that
employed by the C++ language.

* Menu:

* The Ampersand Syntax::                Denoting changeable arguments
* Doubling A Variable::                 Variables (e.g. `&.variable.')
* Manipulating A Synonym::              Synonyms (e.g. `&\synonym')
* Nesting::                             Newcommands called by newcommands
* Using New And Delete::                Isolating local variables and synonyms
* Determining Calling Information::     The `\&.word?.' and `\&&.word?.' syntax
* Implementation of Ampersand Syntax::  Algorithm Gri uses


File: gri.info,  Node: The Ampersand Syntax,  Next: Doubling A Variable,  Prev: Changeable Command Arguments,  Up: Changeable Command Arguments

10.11.5.1 Overview of the `&' syntax
....................................

Normally the arguments to a newcommand are parsed into either numerical
values or strings, before execution is passed into the newcommand.  This
is a akin to the scheme called "call by value" in some programming
languages.  Gri also provides a syntax, borrowed from C++, that permits
a newcommand to alter the contents of variable or synonym arguments.

   The technique is simple.  To permit a newcommand to modify an
argument that is a variable or a synonym, just put a `&' to the left of
the item on the calling line.  Then, within the newcommand, the
corresponding local synonym (i.e. `\.word1.', etc.) will behave as
though it were the instance of the original variable or synonym.

   The `&' is placed to the left of the variable-name or synonym-name
without intervening space.  For example `foo &.var. &\syn' tells the
parser that the newcommand named `foo' may possibly alter the values of
the variable `.var.' and the synonym `\syn', as they exist in the
calling context.

   It is important to note that Gri pays very little attention to the
`&' in a syntax-declaration line.  All it does is to note that the item
to the right of the `&' is not a fixed word in the newcommand being
defined; this follows the usual rules for parsing newcommand syntax
(*Note Parsing::).


File: gri.info,  Node: Doubling A Variable,  Next: Manipulating A Synonym,  Prev: The Ampersand Syntax,  Up: Changeable Command Arguments

10.11.5.2 Example: doubling a variable
......................................

Consider the task of adding a fixed amount to a variable.  If the
variable we wish to double is `.x.', we might write

     `double_a_particular_variable'
     {
         .x. = {rpn .x. 2 *}
     }
     .x. = 10
     double_a_particular_variable

Code such as that presented above occurs in many applications.  (Turn
the multiplication into an addition, and change `.x.' to `..ymargin..',
and you'll start to see the core of an application that draws multiple
graph panels, one above another.)  However, the code is too specific to
be of much general use!

   What if we want to double some other variable instead?  The code
below shows how to do that.

     `double &.value.'
     {
         \.word1. = {rpn \.word1. 2 *}      # line 3
     }
     .x. = 10                               # line 5
     double &.x.
     .y. = 3.14
     double &.y.

At line 3 Gri interprets the `\.word1.' to the *left* of the equals
sign as a reference to the variable that is set to the value 10 in line
5.  Similarly, the `\.word1.' to the *right* of the equals sign
evaluates to 10, the value in the calling program.

   Gri automatically determines whether an item is a variable or a
synonym, and does the correct thing.  Thus, for example, if line 3
above were written as

     \.word1. = "hello"                 # ERROR

an error would be reported, since `double' was called with a variable
as an argument, and variables cannot hold strings.


File: gri.info,  Node: Manipulating A Synonym,  Next: Nesting,  Prev: Doubling A Variable,  Up: Changeable Command Arguments

10.11.5.3 Example: manipulating a synonym
.........................................

Synonyms are treated in the same way, as is illustrated in the following
example.

Q: what does the following print?

     `add_a_dat &\filename'
     {
         \.word1. = {rpn "\.word1." ".dat" strcat}
     }
     \filename = "test"
     add_a_dat &\filename
     show "\filename"

A: it prints `test.dat'.


File: gri.info,  Node: Nesting,  Next: Using New And Delete,  Prev: Manipulating A Synonym,  Up: Changeable Command Arguments

10.11.5.4 Nesting
.................

One newcommand may call another, letting a deeply-nested newcommand
alter values of synonyms and variables that may otherwise be hidden
behind `new' items of the same name.  This is done by using the `&'
notation at each step.  The following provides an example of passing a
variable through two levels of newcommands.

Q: what does the following print?

     `food critic &food'
     {
         \.word2. = "\.word2.s"
         yummy &\.word2.
     }
     `yummy &foods'
     {
         \.word1. = "\.word1. are tasty"
     }
     \a = "apple"
     food critic &\a
     show "\a"

A: it prints `apples are tasty'.


File: gri.info,  Node: Using New And Delete,  Next: Determining Calling Information,  Prev: Nesting,  Up: Changeable Command Arguments

10.11.5.5 About `new' and `delete'
..................................

If `new' and `delete' are executed on local synonyms inside newcommands
(e.g.  `new \.word1.')  they create and destroy variables and synonyms
in the context of the *calling program*.

   For example, consider the following.

Q: what does the following print?

     `poetry &\s'
     {
         new \s                             # line 3
         \s = "rose"
         \.word1. = "\.word1. is a \s"      # line 5
         delete \s                          # line 6
     }
     \s = "A rose "                         # line 8
     poetry &\s
     show "\s"

A: it prints `A rose is a rose'.

   The key point here is that the instance of the synonym named `\s' in
the calling program, set in line 8, is modified by the `poetry'
newcommand, in line 6.  This modification involves the use of a synonym,
*also named* `\s', that "lives" wholly within the newcommand, being
created in line 3 and destroyed in line 6.


File: gri.info,  Node: Determining Calling Information,  Next: Implementation of Ampersand Syntax,  Prev: Using New And Delete,  Up: Changeable Command Arguments

10.11.5.6 Determining calling information
.........................................

Newcommands may determine the name and the nesting level of changeable
calling arguments.  To get the name, put a single ampersand after the
backslash of the local synonym of interest.  To get the nesting level (0
for main program, etc.) put two ampersands after the backslash.
     `NC &.var.'
     {
         show "\&.word1. (expect '.a.')"
         show "\&&.word1. (expect 0)"
     }
     .a. = 1
     NC &.a.

   *Note*: neither of these items may be used an lvalue.  That is, they
may not be used to the left of an equals sign.  But you can always get
around that by clever use of alias synonyms (*Note Alias Synonyms::).


File: gri.info,  Node: Implementation of Ampersand Syntax,  Next: Hints,  Prev: Determining Calling Information,  Up: Changeable Command Arguments

10.11.5.7 How Gri implements the `&' syntax
...........................................

When the parser encounters an unquoted `&' followed immediately by the
name of a variable or a synonym, it converts the whole token (`&' plus
name) into a specially-encoded string that can be recognized inside
newcommands.  (This is *only* done if the `&' and the variable name are
*not* enclosed in double quotes.)

   This specially-encoded string contains not just the name of the
variable or synonym, but also the current level of nesting of
newcommands.  In this way a newcommand can have its own private
versions of variables, created by `new', that won't be misinterpreted
for the identically-named variables in the calling program.

   The format of these specially-encoded strings is
`#\bn\ba\bm\be\b:\bN \b_ \bl\be\bv\be\bl\b:\bL#\b', where `N' stands for
the name of the variable/synonym, `L' stands for the current level, and
`\b' is the backspace character (hexadecimal 08 in the ascii table).
This string is designed to be strange enough that users are unlikely to
use it themselves.  The coding scheme is not entirely arbitrary,
however; note that if the backspace characters are ignored the result
has the form `name:N_level:L'.  It's also worth noting that if this
string were printed on a terminal that erased characters when typing
backspaces the result would be of the form `N_L'.

   Examples: `.a.' in the main program (i.e. at level 0) encodes to
`#\bn\ba\bm\be\b:\b.a. \b_ \bl\be\bv\be\bl\b:\b0#\b' and `&\my_syn'
inside a newcommand called by the main program (i.e. at level 1)
encodes to `#\bn\ba\bm\be\b:\b\my_syn \b_ \bl\be\bv\be\bl\b:\b1#\b'.

   Inside a newcommand, Gri checks to see if builtin synonyms (e.g.
`\.word1.') hold such specially-encoded strings.  If so, then the
appropriate versions of the variables are used in preference to any
variables that may have been newly created by `new' inside the
newcommand.


File: gri.info,  Node: Hints,  Next: Debugging,  Prev: Implementation of Ampersand Syntax,  Up: Programming

10.12 Hints for Gri Programming
===============================

Here are some hints for good Gri programs:

   * Whenever working with grids (for contouring) or images, make use
     of the `show grid' or `show image' commands.  They will give you
     useful information about the statistics (min/max/histogram) of the
     items.

   * Use the operating system, not Gri, to manipulate your data.  For
     example, if you have a file whose first column is x times 100, and
     third is the arcsin of y, you could do:

          open "gawk '{print $1/100, sin($3)}' |"
          read columns x y

     If you have x and y in a non-decimal geographical format (e.g.
     hour.minute-second format), use the operating system to convert
     for you (*Note Open::).

   * Use the `pstack' operator liberally in your rpn expressions to see
     what is going on (*Note rpn Mathematics::).

   * While developing programs, put a `show columns statistics' command
     after every `read column' command, to check that the data have been
     read correctly.

   * Development time can be minimized by limiting the number of data
     being processed.  For example, in a multi-panel plot, it is often
     necessary to try various alternatives before aesthetic scales and
     page layout is achieved.  The process can be speeded up by
     limiting the number of data being processed, as shown below.  (If
     Gri finds fewer data in the file than specified, it will simply
     use the data that it found; so when the program works, just change
     `.n.' into something large.)

          .n. = 100 # 10000 for later
          ...
          # Panel 1
          read columns .n. x y
          ...
          # Panel 2
          read columns .n. x y
          ...

   * Create new commands to do repetitive work.

   * Use `draw time stamp' on all plots except for publication versions:

          if !..publication..
            draw time stamp
          end if

   * For multiple panels on one page, do `delete x scale' or `delete y
     scale' before each new panel, so you will start afresh.  Clearly
     identify code for particular panels with comments.  This reduces
     errors you might get if you shuffle things later.

   * Use the `..num_col_data..' built-in variable to see how many data
     have passed the `set input data window' data window in the last
     `read columns' command.  The following example shows how to avoid
     drawing an unwanted curve:

          open \f
          read columns x y
          close
          if ..num_col_data..
            draw curve
            draw label "\f" at \
                {rpn ..xlast.. xusertocm 0.5} \
                {rpn ..ylast.. yusertocm 0.2} cm
          end if

   * Use synonyms and `query' for filenames.  This makes programs much
     more flexible.  Note that you can string synonyms together:

          \dir = "~/EOS/iso0/"
          query \file "Give file in directory \dir" ("1.dat")
          open \dir/\file

     It is also a good idea to give a restrictive list of possibilities
     in your `query' command, to avoid complicated `if' commands later
     (*Note Query::).

   * Use multiple `draw title' commands:

          draw title "Atlantic water entering Arctic Ocean"
          draw title "\.command_file. \.time."

   * Use the `query' command to interact with the user (*Note Query::).
     The results can be stored in variables and synonyms.



File: gri.info,  Node: Debugging,  Next: Error Messages,  Prev: Hints,  Up: Programming

10.13 Debugging Gri Programs
============================

Here are some hints for debugging Gri programs:
   * If no data appear on an xy plot, insert `show columns statistics'
     or `show columns' after the `read columns' command.  It may be
     that you have fixed your axes, and that the axes frame does not
     include the data.

   * If you get an error message, rerun your Gri program using the
     `-trace' command-line option, to see which line is causing the
     problem.  This often reveals logic errors (e.g. in (`if'
     statements).  You may also turn tracing on or off at any point in
     your Gri program by setting the built-in variable `..trace..' to 1
     or 0.  Many Gri users have the Gri command aliased to be in trace
     mode by default.

   * If Gri complains of a syntax error, consult the printed manual,
     one of the online manuals, or the online help facility (*Note
     Online Help::).

   * Check the version number (printed at startup) to see if a new
     version of Gri has been installed, and check the manual for known
     incompatabilities.

   * Sprinkle `show' commands throughout your program, to see what's
     happening.  Even when you are sure your program works, it is a
     good idea to embed `show' statements so are they executed if the
     `-debug' flag is set:

          if ..debug..
            show "X=" .x. "and label is `\label'"
          end if

   * If your `draw' commands don't draw anything, check to see whether
     you've fooled yourself by enforcing an improper scaling; remove
     explict scaling (`set x axis ...'), clipping (`set clip'), data
     selection windows (`set input data window x|y') and missing values
     (`set missing value').  Another trick is to read only a portion of
     the data set (`read columns 10 x y') and then print out all the
     values (`show columns').

   If you determine that the bug is in Gri, not in your program, please
report the bug, so that other users will not have the same hassle;
(*Note Bugs::).


File: gri.info,  Node: Error Messages,  Next: Missing Values,  Prev: Debugging,  Up: Programming

10.14 Error Messages
====================

Gri error messages are in three types:
  1. Operating system error messages, such as `segmentation fault'.
     These should never appear, and indicate a bug in Gri.  Please
     report these to the author (*Note Reporting Bugs::).

  2. Internal Gri error messages.  The message starts with the words
     `FATAL error', and quotes a file number and a line number, e.g.

          FATAL error: startup.c:199: ...

     Such errors indicate either a deficiency in your computer (e.g.
     insufficient storage space) or an internal bug in Gri.  If the
     message does not indicate running out of storage, please report
     the error to the author (*Note Reporting Bugs::).

     For fatal error messages on a unix system, Gri dumps core, unless
     you have turned that feature off, with the `ulimit -c 0' unix
     command in a startup file.  This creates a file called `core',
     which can help you in diagnosing the Gri bug.  If you have the
     `gdb' debugger, just type `gdb gri core' and then type `where' to
     get a traceback stack.  Please email this with your other
     information about the Gri bug.

  3. An indication that your commandfile is flawed, either in syntax or
     in meaning.  These messages end with a line indicating the
     offending line in your commandfile, e.g. the command `set x axis 0
     1 -1' yields:

          ERROR: `set x axis .left. .right. .incBig.'
                  has .incBig. of wrong sign
           Bad command:  `set x axis 0 1 -1 '

     Normally, such error messages do not indicate a flaw in Gri, but
     rather in your reasoning, so report them to the author only if you
     are very sure that a Gri bug must underly them.


File: gri.info,  Node: Missing Values,  Next: Operating System,  Prev: Error Messages,  Up: Programming

10.15 Missing data
==================

Most Gri commands will ignore data points equal to a "missing value."
For example, `draw curve' connects only points which are not equal (to
within 0.01 percent) of the missing value.  The curve has holes at
missing data.  Initially the missing-value is set to 1.0e22.  You may
alter this value with `set missing value .value.'.  The built-in
variable `..missingvalue..' stores the current value of the
missing-value.

   Additionally, Gri will ignore anything it reads that is equal to the
string `NaN' or `Inf'.  These are produced by matlab, C, and other
programs when dividing by zero, etc.

   Gri also ignores mathematical operations on data items which are
equal to the missing value.  Thus, for example, if your missing value
is -99 then the command `x += 1' will not change the values equal to
-99 to -98, since this would have the side-effect of making the datum
no longer be considered missing.


File: gri.info,  Node: Operating System,  Next: Using OS Inside Gri,  Prev: Missing Values,  Up: Programming

10.16 Interaction Between Gri and Operating System
==================================================

* Menu:

* Using OS Inside Gri::         Accessing the OS from inside Gri
* Using Gri Inside OS::         Tricks for using Gri in unix


File: gri.info,  Node: Using OS Inside Gri,  Next: Using Gri Inside OS,  Prev: Operating System,  Up: Operating System

10.16.1 Using the OS from within Gri
------------------------------------

Gri uses the operating system internally for things like paging through
help information.

   The operating system may be called *within* Gri commands, using a
syntax borrowed from the `Bash' unix shell.  After substituting
synonyms in the commandline, Gri scans for dollar-parenthesis blocks
(e.g. `\$(system-command)', replacing them with the textual result of
sending the indicated system-command to the OS.  The replacements are
done from left to right in the commandline, starting at the deepest
nesting level.

   Often the dollar-parentheis syntax is used in title commands, to
indicate the full pathname of the Gri commandfile, e.g.

     draw title "\$(pwd)/\.command_file."

   In assignment to synonyms, expansion of dollar-parenthesis is not
done.  Thus the operating system is called twice on the second line
below, and not at all on the first line; to see this, run it as `gri
-s8 -t'.

     \dir = "\$(echo $MY_DIR)"
     show "\$(head -1 \dir/MY_FILE)"

   *Syntax Note* Dollar-parenthesis blocks must be prefixed with
backslash to avoid confusion with math expressions within strings, for
example to avoid breaking `draw label "$(x,y)$" at 3 3 cm'.  This is an
example of how TeX notation and unix shell notation collide.

   *Example* It is a good idea to employ unix environment variables to
name directories containing data, so that Gri scripts will work
unchanged even if the data are moved (so long as the environment
variables are altered), e.g.

     # Figure how many lines in a file
     \dir ="$(echo DIRECTORY_WHERE_I_STORE_SOLAR_DATA)"
     open "\dir/solar_data_file_name`
     ...
     open "\$(echo DIR_ANOTHER)/another_data_set"

Another method is to pass instructions to the operating system with the
`system' command.  This discards output.  Whatever follows the word
`system' is first scanned for synonyms (but not rpn expressions or
variables); after replacement of any existing synonyms, the line is
passed directly to the operating system.  Any results are printed on the
terminal.

   Frequently used system commands are `awk', `head', `grep' and `sed'.
Examples:

   * Here's how to paste several files together to form a temporary
     file for plotting.  (Notice that a temporary file incorporating
     the PID of the job is created and later removed.)

          system paste -d" " 1.dat 2.dat 3.dat > tmp.\.pid.
          open tmp.\.pid.
          read columns x y
          close
          system rm tmp.\.pid.

   * Here's how to plot each line in a file called `inp' which has the
     string `;' at the start of the line.

          system cat inp | grep -v "^;" | cat > tmp.\.pid.
          open tmp.\.pid.
          read columns x y
          system rm tmp.\.pid.

   * Here's how to use the `awk' system command to create a tabulated
     function for plotting.

          system awk                             \
              'BEGIN {                           \
                 for (x=0; x<1; x+=0.1) {        \
                   printf ("%f %f\n", x, sin(x)) \
                 }                               \
               }'                                \
              > tmp.\.pid.
          open tmp.\.pid.
          read columns x y
          close
          system rm tmp.\.pid.
          draw curve

     This example is more cleanly written using the piping facility of
     the `open' command (which automatically creates a temporary file,
     and destroys it when `close' is done)

          open "awk 'BEGIN {       \
            for(x=0;x<1;x+=0.1) {  \
              print(x,sin(x))      \
            }                      \
          }'|"
          read columns x y
          close
          draw curve

   * Sometimes you need just a single output item from the operating
     system.  In this case, you can store the results from the operating
     system in a synonym by using the `\synonym = system ...'
     assignment command.

   * subroutine A related command is `\synonym = tmpname', which stores
     in the synonym the name of a temporary file created by the system.
     The file is created with the `tmpname' system call, so it is
     guaranteed not to clash with any existing files.  Typically, the
     filename is something like `/usr/tmp/griAAAa1233'.  In many cases
     you'll want to remove the file within Gri, once you're done, and
     that can be done with `unlink' (*Note Unlink::) or with a `system
     rm -f' command.  A useful bit of code is as follows
          \file = tmpname
          system ... SOME_SYSTEM_COMMANDS ... > \file
          ... use this new file for something ...
          unlink \file



File: gri.info,  Node: Using Gri Inside OS,  Next: Resource File,  Prev: Using OS Inside Gri,  Up: Operating System

10.16.2 Using Gri from within the OS
------------------------------------

*This section only applies to unix systems.*

   Save the following into a file called `p' and then make it
executable using `chmod'.  It runs Gri on a named file, with the `-yes'
flag set so that any `query' commands are automatically answered in the
affirmative, and then displays the results in a Ghostscript window.
(USAGE: `p cmdfile.gri')

     #!/usr/bin/sh
     # Run Gri, then plot in gs window
     case $# in
     1)
             base=`basename $1 .gri | sed -e s/.*,#`
             gri -yes $base.gri && ghostview $base.ps
             ;;
     *)
             echo "Proper usage: $0 cmdfile.gri"
             ;;
     esac


File: gri.info,  Node: Resource File,  Next: Environment,  Prev: Using Gri Inside OS,  Up: Programming

10.17 Sample Resource File
==========================

The following shows a sample `~/.grirc' resource file.  Much of the
code here is adding new commands (*Note Adding New Commands::.)

     # Some folks like tics to point inwards ...
     set tics in

     # Hey, I'm bored with Helvetica font, and
     # Palatino is a bit prettier than Times
     set font to PalatinoRoman

     # Now for something a bit less trivial.
     # This lets me draw a set of y-values
     # against a single x-value, by e.g.
     #    open xyyy.dat
     #    draw curves time T1 T2 T3
     # where the first column of the file is
     # time, and the others are temperatures
     # at various sensors.
     `draw curves \xname \y1name ...'
     Draw multiple y columns versus an x column.  Assumes
     that the datafile is open, and that x is in the first
     column, with the y values in one or more following
     columns.

     The number of columns is figured out from the options,
     as is the name of the x-axis, and the labels to be
     used on each of the y curves.
     {
       # NB. the 3 below lets us skip the words 'draw'
       # and 'curves', and the name of the x-column.
       .num_of_y_columns. = {rpn wordc 3 -}
       if {rpn .num_of_y_columns. 1 >}
         show "ERROR: `draw curves' needs at least 1 y column!"
         quit
       end if

       set x name {rpn 2 wordv}
       set y name ""

       # Loop through the columns.
       .col. = 0
       while {rpn .num_of_y_columns. .col. <}
         # The x-values will be in column 1, with y-values
         # in columns 2, 3, ..., of the file.
         .ycol. = {rpn .col. 2 +}
         rewind
         read columns x=1 y=.ycol.
         # At this point, you may want to change line thickness,
         # thickness, color, dash-type, etc.  For illustration,
         # let's set dash type to the column number.
         set dash .col.
         draw curve
         draw label for last curve {rpn .col. 3 + wordv}
         .col. += 1
       end while
     }


File: gri.info,  Node: Environment,  Next: Extras,  Prev: Resource File,  Up: Top

11 Environment
**************

Gri comes with a few ancillary programs that may be useful.  Gri also
provides a simple scheme to use other system tools (e.g. `awk').  These
are discussed here.  And speaking of discussing, this chapter ends with
a note about a mail-list Gri discussion group.

* Menu:

* Extras::                      Extra things provided with Gri
* Using System Tools::          Using Gri with other tools
* Discussion Group::            Gri email list


File: gri.info,  Node: Extras,  Next: gri_merge,  Prev: Environment,  Up: Environment

11.1 Extra things provided with Gri
===================================

* Menu:

* gri_merge::                   Merge files to one page
* gri_unpage::                  Separate multipage doc into separate files


File: gri.info,  Node: gri_merge,  Next: gri_unpage,  Prev: Extras,  Up: Extras

11.1.1 `gri_merge' - combine PostScript files
---------------------------------------------

Merge separate PostScript files, created by Gri, into one page.  To
learn how it works, type `gri_merge -h' at the system prompt, to see:

     PURPOSE: Strings Gri PostScript files together.

     BUGS:    With old versions, of gri, make sure to match each `set clip
      postscript on' with a `set clip postscript off'.

     USAGE (style 1):
         gri_merge [OPTIONS] CxR a.ps b.ps ... > merged_file.ps
      Merges the files onto one page, in 'C' columns and 'R' rows.  The C*R
      files are given in the order of words on a page.  The page is
      presumed to be 8.5x11 in size, as are all the input files, and the
      input files are sized to fit, and kept in natural scale.

     USAGE (style 2):
         gri_merge [OPTIONS] xcm ycm enlarge a.ps [b.ps ...] > merged_file.ps
      Where `enlarge' is a scale factor applied after offsetting `xcm' to
      the right and `ycm' upward.

     EXAMPLE (style 2):
      The following
        gri_merge  2 12 .5 a.ps \
                 12 12 .5 b.ps \
                  2  2 .5 c.ps \
                 12  2 .5 d.ps > all.ps
      produces 4 panels from gri plots done using margins and sizes
      as specified in the following lines in a gri commandfile
        set x margin 2
        set x size 15
        set y margin 2
        set y size 15
      The OPTIONS, available if your 'perl' has 'getopts' library, are:
        -u graylevel -- set graylevel for underlay beneath panels, by default 0.75.
                        Values range from 0 (black) to 1 (white), although a value
                        of precisely 1 means do NOT draw underlay.
        -b graylevel -- Set value for background under individual panels, again 0
                        for black to 1 for white, with 1 meaning no drawing.
        -h           -- Print this help message and quit.


File: gri.info,  Node: gri_unpage,  Next: Using System Tools,  Prev: gri_merge,  Up: Extras

11.1.2 `gri_unpage' - split pages into files
--------------------------------------------

Given a multipage PostScript file, `gri_unpage' creates several new
PostScript files, one for each page.  To learn how it works, type
`gri_unpage -h' at the system prompt, to see:

     PURPOSE: Chop multipage Gri PostScript file into one file per page.
     USAGE:   gri_unpage name.ps -- create files name-1.ps, name-2.ps, etc, one
                                    for each page of name.ps.
              gri_unpage -h      -- print this help message

     BUGS:    1. Bounding box is always 8.5x11 inches.
              2. Assumes that all Gri fonts are used even if they aren't.


File: gri.info,  Node: Using System Tools,  Next: Why Use The Environment,  Prev: gri_unpage,  Up: Environment

11.2 Using System Tools With Gri
================================

Using system tools to manipulate your data makes sense for several
reasons.  First, you may be familiar with those tools already.  Second,
learning these tools will help you in all your work.

* Menu:

* Why Use The Environment::     Introduction
* Grep::                        Search files for patterns
* Sed::                         Serial editor
* Awk::                         Search and manipulate data
* Perl::                        Search and manipulate data


File: gri.info,  Node: Why Use The Environment,  Next: Grep,  Prev: Using System Tools,  Up: Using System Tools

11.2.1 Introduction
-------------------

Each of the programs listed in the sections below is available for Unix.
Some (e.g. Perl and the Awk variant called Gawk) are available on other
operating systems as well.  Each of these tools is fully documented in
Unix manpages, so here I'll just give an indication of a couple of
useful techniques you might want to use.

   Bear in mind that these tools can do very similar jobs.  For example,
Awk can do much of what Sed and Grep can do, but also a whole lot more.
If you don't know Sed or Grep, I suggest you learn Awk instead.  Then
again, Perl can also do anything Gawk can do, and a whole lot more!
(For one thing, it is easier to work with multiple files in Perl.)  In
fact, Perl is the most powerful of this list.  If you know none of these
tools, you might want to learn Perl instead of the others.  But Perl is
more complicated for simple work than Awk is, so the most reasonable
path might be to learn both Awk and Perl.

   For simple applications, you will probably want to use these tools
in a piped open command, e.g.

     open "awk '{print $1, $3/$2}' MyFile |"

which creates a temporary file (automatically erased when Gri finishes)
which contains the output from running the system command that preceeds
the pipe symbol (`|') (*Note Open::).

   (Here and in all the examples of this chapter, it is assumed that the
user's input file is named `MyFile'.)

   For more complicated appplications, you may use the Gri `system'
command as follows.

     system perl   >tmp  <<"EOF"
     open(IN, "MyFile");
     while(<IN>) {
         ($x, $y) = split;
         print "$x", " ", cos($y), "\n";
     }
     EOF
     open tmp
     read columns x y
     draw curve
     system rm -f tmp

Here a temporary file, named `tmp', has been used to store the results
of the calculation.  Note that this file was specifically cleaned up by
the second `system' command.  (Many folks, including the author, would
prefer to take the perl script out of the above and make it a
standalone executable script, calling it from Gri with the one-line
form.  But it is just a matter of style.)


File: gri.info,  Node: Grep,  Next: Sed,  Prev: Why Use The Environment,  Up: Using System Tools

11.2.2 Grep
-----------

The most common application of Grep is to select lines matching a
pattern, or not matching a pattern.  Here is how to skip all lines with
the word "HEADER" in them:

     open "grep -v 'HEADER' MyFile |"
     ...

Note that Gawk and Perl do this just as easily.


File: gri.info,  Node: Sed,  Next: Awk,  Prev: Grep,  Up: Using System Tools

11.2.3 Sed
----------

Sed is normally used for simple changes to files.  For example, if you
have columnar data which are separated with comma characters instead of
whitespace, you could make it Gri compatible by

     open "sed -e 's/,/ /g' MyFile |"

Where the `-e' flag indicates that the next item is a command to Sed,
in this case a command to switch ("s") the comma character with the
blank character, globally ("g") across each line of the file.  See also
the overview of Perl.


File: gri.info,  Node: Awk,  Next: Perl,  Prev: Sed,  Up: Using System Tools

11.2.4 Awk
----------

Awk is great for one-liners.  If your system lacks Awk, you can procure
the GNU version, called Gawk, from the web for free.  For better or
worse, Gawk is not fully compatible with Awk.  The good thing is that
Gawk is pretty much the same on all operating systems, whereas the
installed Awk may not be.  I use Gawk instead of Awk, for this reason
and because it is normally faster.

   The main concept in Awk is of "patterns" and "actions."  In the Awk
syntax, actions are written in braces following patterns written with no
braces.  (This will become clear presently.)

   Whenever a line in the data file matches the pattern, the action is
done.

   The default pattern is to match to every line in the file.  This is
done if no pattern is supplied.

   The default action is to print the line, and this is done if no
action is supplied.

   Here are a few examples.  To skip first 10 lines of a file:

     open "awk 'NR>10' MyFile |"
     read ...

Here the pattern was that `NR' (a special Awk variable for the number
of the record, starting with 1 for the first line of the file) exceeded
10.  And the action was taken by default since nothing was supplied
between braces, to print this line.

To plot the cosine of the second column against the first column:

     open "awk '{print ($1, cos($2))}' MyFile |"
     read columns x y
     draw curve

Here no pattern was supplied, so the action was done for every line.

   Combining these two forms, then, and supplying both a pattern and an
action, here is how one might print the first and eighth columns of the
file `MyFile', but only for the first 10 lines of the file:

     open "awk NR<=10 {print ($1, $8)} MyFile |"


File: gri.info,  Node: Perl,  Next: Discussion Group,  Prev: Awk,  Up: Using System Tools

11.2.5 Perl
-----------

Perl can do almost *anything* with your data, since it is a full
programming language designed to also emulate several Unix utilities.

   In perl, as in other commands, the commandline switch `-e' indicates
that a Perl command is given in the next word of the command line.  The
commandline switch `-p' indicates to print the line, after any
indicated Perl actions have been done on it.  Here, for example, is how
one would emulate a Sed replacement of comma by blank:

     open "perl -pe 's/,/ /g' MyFile |"

   Perl also has a commandline switch `-a' indicating that lines should
be "autosplit" into an array called `$F'.  The first element of this
array is `$F[0]'.  Splitting is normally done on white-space
character(s), although this may be changed if desired.  Here, for
example, is how to take the cosine of the second column of a file, and
print this after the first column:

     open "perl -pea 'print($F[0], cos($F[1]))' MyFile |"


File: gri.info,  Node: Discussion Group,  Next: Emacs Mode,  Prev: Perl,  Up: Environment

11.3 Gri Discussion Group
=========================

Before emailing to the Gri newsgroup, it is a good idea to consult the
list of answers to Frequently Asked Questions.

   As of summer 2000, Gri traffic has been moved to the web-based
discussion groups at the SourceForge website
`http://gri.sourceforge.net' about which little need be said here,
because the website is very easy to use.


File: gri.info,  Node: Emacs Mode,  Next: About Gri Mode,  Prev: Discussion Group,  Up: Top

12 Editing Gri Files in GNU Emacs
*********************************

If you use the GNU Emacs (or XEmacs) text editor, writing Gri command
files is made easier with the Gri editing mode (gri-mode.el), written
by Peter S. Galbraith `<psg@debian.org>'.

* Menu:

* About Gri Mode::
* Gri-mode screenshots::                  What it looks like.
* Installing gri-mode.el::                The nuts and bolts.
* Major Gri-mode commands::               It knows about Gri commands.
* Other features::                        IMenu, Toolbar, etc.
* Dealing with many Gri versions::        gri-mode handles it.
* Filename arguments when running gri::   gri-set-command-postarguments.


File: gri.info,  Node: About Gri Mode,  Next: Gri-mode screenshots,  Prev: Emacs Mode,  Up: Emacs Mode

12.1 About Gri Mode
===================

Gri mode has all the wonderful things you've come to expect from Emacs
modes.  Here's a brief overview of the features:
   * It can *complete* partially typed commands, builtin variables and
     synonyms (`gri-complete', <M-Tab>) and help you edit the syntax
     that was thus inserted for you (`gri-option-select', `C-c C-o';
     `gri-option-kill', `C-c C-k').

   * It can provide a short help synopsis concerning the command on the
     current line (`gri-help-this-command', `C-c C-h'), or load the
     info manual for that command (`gri-info-this-command', `C-c C-i').
     It knows the list of all Gri commands, and can provide help or
     info regarding any of them (`gri-help', `C-c M-h'; `gri-info',
     `C-c M-i') using command name completion at the prompt (<Tab>).

   * All Gri commands are listed in a pull-down menu from the menubar,
     which you can use to either enter the text of the selected
     command, or obtain help or info about it.

   * It can help you find an unknown command by listing all containing
     a given word (`gri-apropos', `C-c C-a').

   * It fontifies your Gri code using colour coding.

   * It indents if statements, loops, and so on (`gri-indent-line',
     <Tab>).

   * It can let you run Gri and view its output without leaving the
     editor (`gri-run', `C-c C-r').  If an error is encountered, Emacs
     will rearrange the buffer so the cursor is on the bad line of the
     Gri command-file.

   * If you've already run Gri, and therefore have a PostScript output
     file, the mode will let you view that file (`gri-view', `C-c C-v')
     even if that file is compressed.

Thus one never has to leave Emacs; type `C-c C-r' to run Gri, and if
there is no error, the graph comes up automatically.  If there was an
error, gri-mode will move editing point to the line with the error and
display the error message. Given that the mode can complete partially
typed commands, this means a substantial saving in development time.

   Inside gri-mode, type `C-h m' for help on the mode, including a list
of all commands and key definitions.


File: gri.info,  Node: Gri-mode screenshots,  Next: Screenshot 1,  Prev: About Gri Mode,  Up: Emacs Mode

12.2 Gri-mode screenshots, what it looks like.
==============================================

* Menu:

* Screenshot 1::
* Screenshot 2::
* Screenshot 3::
* Screenshot 4::


File: gri.info,  Node: Screenshot 1,  Next: Screenshot 2,  Prev: Gri-mode screenshots,  Up: Gri-mode screenshots

12.2.1 Screenshot 1
-------------------

Screenshots are not visible in the info node; see the online HTML
documents.

In the first screenshot, the user has entered the text `set font' and
has pressed <M-Tab> twice to see the list of possible completions.  The
`*Completions*' buffer is displayed in a separate frame because the
user is using the `framepop.el' add-on package.  A similar effect can
be obtained using `special buffers' in Emacs.


File: gri.info,  Node: Screenshot 2,  Next: Screenshot 3,  Prev: Screenshot 1,  Up: Gri-mode screenshots

12.2.2 Screenshot 2
-------------------

Screenshots are not visible in the info node; see the online HTML
documents.

Here, the user has selected the command `set font to' and, forgetting
what valid font name could be used, then invoked `C-c C-h' to get help
about that command. The user found the needed information and finished
typing in `Courier'.  Meanwhile, an idle timer displays the default
setting for this command in the minibuffer after a few seconds of
inactivity.


File: gri.info,  Node: Screenshot 3,  Next: Screenshot 4,  Prev: Screenshot 2,  Up: Gri-mode screenshots

12.2.3 Screenshot 3
-------------------

Screenshots are not visible in the info node; see the online HTML
documents.

Here we see the user cascading through the Gri commands pull-down menu
until `draw axes' is reached.  This menu can be used to display Info
(or help) about a given command, or to insert the selection.  The
default is Info.  This menu is a good way to browse for a command when
you don't exactly remember its name.


File: gri.info,  Node: Screenshot 4,  Next: Installing gri-mode.el,  Prev: Screenshot 3,  Up: Gri-mode screenshots

12.2.4 Screenshot 4
-------------------

Screenshots are not visible in the info node; see the online HTML
documents.

With the output previewed in a `gv' window after pressing `C-c C-v' (or
pressing the `gv' icon in the toolbar, or selecting it from the
`Perform' pull-down menu), the user is ready to print the file, here
using the `Perform' pull-down menu.


File: gri.info,  Node: Installing gri-mode.el,  Next: Step 1,  Prev: Screenshot 4,  Up: Emacs Mode

12.3 Installing gri-mode.el, the nuts and bolts.
================================================

The Emacs `gri-mode.el' file is now bundled with gri, so odds are you
already have it.  If not, you will find it at gri's web site
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/gri/gri/gri-mode.el

   The following installation steps appear a *bit* complicated.  That's
only because gri has changed how it gets installed a few times, and
gri-mode.el works with all of these various methods.  If you use gri
from a Linux package (Debian or Red Hat) or if you compiled it yourself
using the default configuration, you won't need to do much.

   To install `gri-mode.el', follow these 4 steps.  If gri-mode is
already installed, you can skip the first two steps and move on to the
last two, in which you tell Emacs that you'd like to use Gri mode when
you edit files that end in `.gri', the Gri suffix.  (Actually, if
you're using Debian linux, you can skip all of these steps since the
system will assume that you want gri-mode if you're editing a Gri file.)

* Menu:

* Step 1::  Placing gri-mode.el where Emacs can find it.
* Step 2::  Configuring gri-mode to where gri lives on your system.
* Step 3::  Telling emacs to load gri-mode
* Step 4::  Extra user configuration of gri-mode.


File: gri.info,  Node: Step 1,  Next: Step 2,  Prev: Installing gri-mode.el,  Up: Installing gri-mode.el

12.3.1 Placing gri-mode.el where Emacs can find it.
---------------------------------------------------

(Those using gri from gri's *RPM* package, a *Debian* package or a *Red
Hat* package users can skip this, as it is done for them)

   Extra `.el' files like `gri-mode.el' that are not part of Emacs
should be stored in a directory where Emacs will find them when you ask
it to load them.  The files should therefore be found in Emacs'
*load-path*.  To see the directory list currently in the load-path, do
this in Emacs:

     C-h v load-path

   If you have access to system directories, put gri-mode.el in a
*site-lisp* directory, such as `/usr/local/share/emacs/site-lisp/' That
way all users will have access to the files.

   If you don't have access to a site-lisp directory (e.g. you have
only a user account), then create a directory where your extra `.el'
files will be stored and add it to Emacs' load-path.  For example, say
you created the directory `~/emacs' and stored gri-mode.el there, you
would then put this near the top of your `~/.emacs' file:

     (setq load-path (cons "~/emacs" load-path))


File: gri.info,  Node: Step 2,  Next: Step 3,  Prev: Step 1,  Up: Installing gri-mode.el

12.3.2 Telling gri-mode where gri resides
-----------------------------------------

(Those using gri from gri's *RPM* package, a *Debian* package or a *Red
Hat* package users can skip this, as it is done for them)

   You may skip this section if gri is installed on your system as
`/usr/local/bin/gri-2.12.15' and `/usr/local/share/gri/2.12.15/gri.cmd'
(the default when compiling gri yourself).  If not, then you may need
to set the Emacs variable `gri*directory-tree' in a startup file such
as in your `~/.emacs' file.

   The Emacs variable `gri*directory-tree' is used to configure
gri-mode to tell it where Gri is installed on your system. For the
default gri installation paths used in this gri release, gri-mode
expects to find the gri executable and the file gri.cmd as:
`gri*directory-tree/2.12.15/gri.cmd' and
`/usr/local/bin/gri-'2.12.15 where `gri*directory-tree' is by default
set to `/usr/local/share/gri/'.

   If you have only one version of gri installed on your system,
gri-mode will also look to find `gri.cmd' and the gri executable like
so:
  1. Gri executable in the PATH, with startup file
     `gri*directory-tree/gri.cmd'.

  2. Gri executable in the PATH, with startup file
     `gri*directory-tree/lib/gri.cmd'.

  3. Gri executable `gri*directory-tree/bin/gri', with startup file
     `gri*directory-tree/lib/gri.cmd'.

   However, gri-mode was designed to support, and ease the use of,
*multiple installed versions* of gri.  To use this feature, you must
use the gri version number as a directory name under the
`gri*directory-tree' path, like this:

     gri*directory-tree/VERSION/bin/gri
     gri*directory-tree/VERSION/lib/gri.cmd

   (e.g. `/opt/gri/2.040/bin/gri' and `/opt/gri/2.040/lib/gri.cmd' with
`gri*directory-tree' set to `"/opt/gri"')

   or without the *lib* and *bin* subdirectories if the executable is
found in the PATH named like `gri-VERSION' (This is the way Debian
packages are set up): the file `gri*directory-tree/VERSION/gri.cmd' and
the `gri-VERSION' executable in the PATH (e.g.
`/usr/share/gri/2.1.17/gri.cmd' and `/usr/bin/gri-2.1.17' with
`gri*directory-tree' set to `"/usr/share/gri"')

   *Important note:* You may have more than one tree and make a list of
them:

     (setq gri*directory-tree '("/opt/gri/" "/usr/share/gri/"))

   *Examples:*

  1.  If you use a RedHat package  installed like:

          /usr/bin/gri
          /usr/share/gri/gri.cmd

     then you'd also use:

          (setq gri*directory-tree "/usr/share/gri/")

     but gri-mode would know of only one installed version of gri.

  2.  If you use a Debian GNU/Linux installation like:

          /usr/bin/gri -> /usr/bin/gri-2.1.17
          /usr/share/gri/2.1.17/gri.cmd

     then you'd use:

          (setq gri*directory-tree "/usr/share/gri/")

     Note that all gri binaries must exist in the path with version
     number  suffixes (e.g. `gri-2.1.17') since there is no
     `/usr/share/gri/2.1.17/bin/' directory (using a similar structure
     to `opt/gri' below) where gri-mode can find the binary
     corresponding to a given version number.

  3.  If you had multiple versions of Gri installed like so (this
     reflects  the installation paths used in older gri releases):

          /opt/gri/2.040/bin/gri
          /opt/gri/2.040/lib/gri.cmd
          /opt/gri/2.041/bin/gri
          /opt/gri/2.041/lib/gri.cmd

     then you'd use:

          (setq gri*directory-tree "/opt/gri/")



File: gri.info,  Node: Step 3,  Next: Step 4,  Prev: Step 2,  Up: Installing gri-mode.el

12.3.3 Telling emacs to load gri-mode
-------------------------------------

(Those using a *Debian* package can skip this, as it is done for them)

   To tell emacs to use this mode with `.gri' files, you can load
gri-mode whenever a new emacs session is starting by adding the
following line to your `~/.emacs' file:

     (require 'gri-mode)

   This is a good method when you only start emacs once a week and use
it for every file you edit (as you should).

   If you startup a fresh emacs every time you edit then you probably
only want to load gri-mode into emacs when you need it.  In that case,
instead of the `require' statement above, add the following lines to
your `~/.emacs' file:

     (autoload 'gri-mode "gri-mode" "Enter Gri-mode." t)
     (setq auto-mode-alist (cons '("\\.gri$" . gri-mode) auto-mode-alist))

   The first line tells Emacs that it will find out what it needs to
know about running the command `M-x gri-mode' by loading the file
`gri-mode.el'.  The second line tells it to run the command `M-x
gri-mode' when a file with extension `.gri' is visited (thus using
gri-mode with all those files).


File: gri.info,  Node: Step 4,  Next: Major Gri-mode commands,  Prev: Step 3,  Up: Installing gri-mode.el

12.3.4 Extra user configuration of gri-mode
-------------------------------------------

*All users should do this at some time.*

   At this point, gri-mode should start up when you edit a gri file.
You may optionally customize gri-mode by:

  1.  using the Custom interface (see the Help or Gri-Help menu or run
     the  command `M-x gri-customize'), or

  2.  manually setting variables in your `~/.emacs' file.  These are
     briefly described by typing `C-h m' while in gri-mode.  Then, for
     further infomation, use emacs' `describe-variable' command, bound
     to `C-h v'.  For example, for more information about the
     `gri*WWW-program' variable, you'd type `C-h v gri*WWW-program'
     (note that emacs does <Tab> completion, so pressing the  <Tab> key
     after typing-in gri will display all gri related  variables.)


File: gri.info,  Node: Major Gri-mode commands,  Next: Gri command names,  Prev: Step 4,  Up: Emacs Mode

12.4 Major Gri-mode commands.
=============================

This section describes the major gri-mode commands, briefly showing how
they can increase your productivity.

* Menu:

* Gri command names::     How gri-mode names all gri commands.
* Possible completions::  A list of all valid commands matching so far.
* Command abbreviations:: Abbreviating many words at one time.
* Variable completion::   Completion of builtin variable and synonyms.
* Editing the syntax::    What to do after gri-complete.
* User commands::         gri-mode knows about ~/.grirc.
* Gri code fragments::    Use them as short-cuts.
* Info interface::        Getting help about the current command.


File: gri.info,  Node: Gri command names,  Next: Possible completions,  Prev: Major Gri-mode commands,  Up: Major Gri-mode commands

12.4.1 How gri-mode names Gri commands
--------------------------------------

A major feature of Gri mode is the completion of partially typed
commands.  Let's examine how gri-mode decides to name gri commands.  A
name is determined by removing bracketed options from the syntax line
of a given command.  This is different from what the gri parser does.
In this way, the gri command

     draw label "\string" [centered|rightjustified] at .x. .y. [cm] [rotated .deg.]

is named by gri-mode simply `draw label at'.  Note how the `at' stays
in the name because it is not optional.  So when you see `draw label
at' in gri-mode's menus or prompts, you are more likely to associate
the name with what the command actually does.


File: gri.info,  Node: Possible completions,  Next: Command abbreviations,  Prev: Gri command names,  Up: Major Gri-mode commands

12.4.2 Possible completions of gri command names
------------------------------------------------

When you press <M-tab> to complete a command name (or a variable or
synonym name as described below), gri-mode will expand it as much as it
can and do nothing further.  If you type in nothing more and insist by
using `gri-complete' (<M-tab>) again, gri-mode will respond by showing
all possible completions in the `*completions*' buffer.  In this way
you can use `gri-complete' word-by-word to abbreviate commands without
ever displaying completions, like you would for file completion in
emacs or bash.

   If a completion is ambiguous, but could be exact, invoke
gri-complete a second time to complete it. e.g.

     sh<M-tab>

expands to

     show

and informs you that 12 possible completions exists; then

     show<M-tab>

will display these completions in the completions buffer; then typing
<M-tab> again forces completion to a complete but not unique
possibility:

     show .value.|{rpn ...}|"\text" [.value.|{rpn ...}|text [...]]

   Completions are shown immediately (without invoking gri-complete
again) if the completions window is already displayed or if there are 3
possibilities or less.  In this case they are displayed in the
minibuffer.

   Note: The `*completions*' window is deleted after a command is fully
completed.  `gri-complete' uses its own `*completions*' buffer, which
is not displayed in the buffer-list to avoid clutter.


File: gri.info,  Node: Command abbreviations,  Next: Variable completion,  Prev: Possible completions,  Up: Major Gri-mode commands

12.4.3 Command name abbreviation
--------------------------------

gri-mode uses command name abbreviations in a non-Unix way in that all
words that compose the command name may be abbreviated (and not only
the word preceding the cursor).  For example, one can type in

     dr x a<M-tab>

and it will expand1 all the words to

     draw x axis [at bottom|top|{.y. [cm]} [lower|upper]]

   This is reminiscent of VMS, which the author was used to when
gri-mode.el was initially created.  It's likely that a gri-mode.el
rewritten from scratch wouldn't have this feature since it's not part
of the Unix mindset.


File: gri.info,  Node: Variable completion,  Next: Editing the syntax,  Prev: Command abbreviations,  Up: Major Gri-mode commands

12.4.4 Variable (and synonym) completion
----------------------------------------

It's also possible to do <M-tab> completion on gri builtin variable and
synonym names while editing a command.  Simply type in the leading `.'
(dot) or `\' (slash) character and invoke completion with <M-tab>.

   For example,

     ..x<M-tab>

displays a completions buffer listing the possible completions:

     ..xmargin..                        ..xsize..
     ..xleft..                          ..xright..
     ..xlast..

Typing in an extra `m' will complete to `..xmargin..' and the following
help information will be displayed in the minibuffer:

     margin to left of axis area. Default is 6 cm.


File: gri.info,  Node: Editing the syntax,  Next: User commands,  Prev: Variable completion,  Up: Major Gri-mode commands

12.4.5 Editing the syntax output by gri-complete
------------------------------------------------

You might wonder what to do with all the bracketed code left behind by
`gri-complete'.  It certainly won't go through the gri parser without
error, so you have to edit it out.

   The tools provided in gri-mode are `gri-option-select' (`C-C C-o')
and `gri-kill-option' (`C-C C-k') to narrow in on a particular gri
command, given a syntax description left on the line by `gri-complete'.
The cursor location is used to decide which gri command(s) to narrow
to.

   For example, if `gri-complete' is used on the line `dr x a', the
result will be a line like

     draw x axis [at bottom|top|{.y. [cm]} [lower|upper]]

   This is the gri way of describing many commands at once.  The above
syntax description is a shortcut formulation for all of:

     draw x axis
     draw x axis at bottom
     draw x axis at bottom top
     draw x axis at bottom bottom
     draw x axis at top
     draw x axis at top top
     draw x axis at top bottom
     draw x axis at .y. cm
     draw x axis at .y. cm lower
     draw x axis at .y. cm upper

   The `gri-option-select' (`C-C C-o') command provides easy navigation
to select one of these commands.  The narrowing process is governed by
the cursor position.  For example, to get the command narrowed down to

     draw x axis at bottom [lower|upper]

place the cursor somewhere in the word `bottom' and invoke
`gri-option-select'.  To complete the narrowing process, selecting

     draw x axis at bottom lower

move the cursor to some place in the word `lower' and invoke
`gri-option-select again'.  On the other hand, to get

     draw x axis at bottom

you would have put the cursor over either the word `lower' or `upper',
and invoke `gri-kill-option' (`C-C C-k') instead.

   You might want to practice using this example to learn how to do it.
If you make a mistake, note that the normal Emacs undo works.


File: gri.info,  Node: User commands,  Next: Gri code fragments,  Prev: Editing the syntax,  Up: Major Gri-mode commands

12.4.6 User commands with gri-mode
----------------------------------

User gri commands defined in `~/.grirc' (*Note Resource File::) or at
the beginning of a gri file can also be used with `gri-complete'.  Note
that user commands are added from the current buffer whenever
`gri-mode' is invoked.  They may override previous user commands, but
not gri system commands.


File: gri.info,  Node: Gri code fragments,  Next: Info interface,  Prev: User commands,  Up: Major Gri-mode commands

12.4.7 Inserting gri code fragments in Emacs
--------------------------------------------

Since gri version 1.063, gri has special commands that begin with a
question mark `?'.  These special commands have no options, and are
composed only of standard gri commands.  Their purpose is to provide a
short-cut for entering many lines of gri at once (e.g.  bits of sample
code about contouring grids, or your own preamble which you use at the
time to set fonts and line widths).

   `gri-complete' acts in a special way with these commands, by
replacing the abbreviated name which you are completing by all the lines
contained within the gri command.

   The user is allowed to define new fragments in `~/.grirc', and also
to override the gri system fragments.  You can therefore fine-tune gri's
fragments to your taste.  To see the names of all gri fragments, type in
a question mark at the beginning of a line in a gri buffer and press
<M-Tab> twice to `gri-complete' it and display possible choices.  The
gri commands used to replace them are found in the `*gri-syntax*'
buffer.


File: gri.info,  Node: Info interface,  Next: Other features,  Prev: Gri code fragments,  Up: Major Gri-mode commands

12.4.8 Info interface for help on current command
-------------------------------------------------

The Info system is built into Emacs (`C-h i'), and provides an easy
method of navigation on-line help (including this manual).  We suggest
that you install the gri info files on your system (they are already
installed with packaged versions of gri in Debian or Red Hat formats).

   Not only will Info (`C-h i') be able to navigate through all of
gri's inline manual, but gri-mode's function `gri-info-this-command'
(`C-c C-i') will display the correct info page about the gri command
being edited on the current line.

   Additionally, gri-mode has the command `gri-info' (`C-c M-i') which
will prompt you (using <tab> completion) for any command to list Info
about.  There's also a menu-bar pull-down menu which lists all gri
commands, and you can get to Info from that too.


File: gri.info,  Node: Other features,  Next: Dealing with many Gri versions,  Prev: Info interface,  Up: Emacs Mode

12.5 Other features of gri-mode
===============================

   * `IMenu support': IMenu is a GNU/Emacs package used to source code
     files.  It can be setup for a particular mode to list a menu of
     function definitions and variable declarations.  In gri-mode, the
     IMenu is available from the menubar and provides links to `new
     command declarations' as well as value settings for `variables'
     and `synomyns'.

   * `Toolbar support': XEmacs21 and Emacs-21 have support for a
     toolbar (a set of iconic buttons that are shortcuts for commands),
     however the two editors don't not have compatible toolbar setups.
     Currently gri-mode only defines a single icon for XEmacs (to run
     gri on the current buffer) and defines three for GNU/Emacs (to run
     gri, to view the postscript file, and to lookup Info about the
     command on the current line).

   * `Idle Help': When GNU/Emacs sits idle with the cursor on a command
     line, it looks up any defaults the command may have and displays
     the information in the minibuffer.  For example, sitting on a line
     that says `set font size 10', it will display `set font size:
     default is 12 point in variable ..fontsize..'.


File: gri.info,  Node: Dealing with many Gri versions,  Next: Filename arguments when running gri,  Prev: Other features,  Up: Emacs Mode

12.6 Dealing with many Gri versions, gri-mode handles it.
=========================================================

Earlier we explained that you might have many versions of gri installed
on your system (*Note Installing gri-mode.el::).  You may use gri-mode
to access these various versions with the following gri-mode commands:

   * `gri-set-version': Tells gri-mode to use a given version as the
     default for all your gri files.  Tab completion is available
     listing all available versions (if they are not all listed, that
     means that the Emacs variable `gri*directory-tree' is not
     correctly set (*Note Installing gri-mode.el::)).  Your selection
     is stored in the file `~/.gri-using-version' and is remembered
     across editing sessions. If you select *default* as your answer,
     gri-mode reverts to using the default version of gri as installed
     on your system (which may change after you update it) and deletes
     the `~/.gri-using-version' file.

   * `gri-set-local-version': Tells gri-mode to use a given version of
     gri *this* gri file (the one currently being edited when you
     invoke the command).  Tab completion is again available to list
     all available versions.  Your selection overrides the default
     version selected by `gri-set-version' for this file, and is stored
     as an Emacs variable at the bottom of the gri file.  It is
     remembered across editing sessions. If you select *default* as
     your answer, gri-mode reverts to using the default version of gri
     as selected by `gri-set-version' and deletes the Emacs variable
     setting at the bottom of the gri file.


File: gri.info,  Node: Filename arguments when running gri,  Next: History,  Prev: Dealing with many Gri versions,  Up: Emacs Mode

12.7 Filename arguments when running gri
========================================

Usually, gri is run specifying only a gri command file to process, which
lends itself well to the gri-mode command `gri-run'.  But Gri can be
also invoked from the command line using optional arguments, usually
filenames but not necessarily, e.g.

     $ gri somefile.gri datafile.dat datafile2.dat ...

or

     $ gri somefile.gri *.dat

   The arguments are accessed with RPN operators `argc' and `argv'
(*Note Unary Operators::).

   gri-mode provides a method to set the arguments (usually filenames)
to use when `gri-run' is called in a specific gri script.  Use the
gri-mode command `gri-set-command-postarguments' to setup a string that
gri-mode will use, and the gri-mode command
`gri-unset-command-postarguments' to clear it.  For ease-of-use, these
commands are made available from the menubar under the `Perform -> Run
Settings' entries.  The specified string will be stored in the
locally-defined (aka buffer-local) variable `gri-command-postarguments'
and will be written within a gri comment at the bottom of the file such
that Emacs remembers it across editing sessions.


File: gri.info,  Node: History,  Next: Stable Stream,  Prev: Filename arguments when running gri,  Up: Top

13 History of Gri Versions
**************************

Gri, like many modern software projects, has two "streams" of
development running side by side.  One is called "stable," the other
"unstable."  _Most users should use the stable stream_, which has been
well tested.  (The unstable version is for users who wish to try out
new features that are under development.)

   Stable versions always have an even number as the middle number in
their version designation, e.g. `2.6.0', while unstable versions always
have an odd number there, e.g. `2.7.0'.  This middle number indicates a
sort of family of related releases.  Within a stable stream, all
versions sharing a given middle number have the same features; new
releases are made only to fix bugs.  Thus, version `2.6.1' fixed bugs
in version `2.6.0'.

   To learn more about the bugs, and their resolution, visit the bugs
page at gri.sourceforge.net
(http://sourceforge.net/tracker/?func=browse&group_id=5511&atid=105511)
and adjust the "status" menu to read "closed".

* Menu:

* Stable Stream::
* Unstable Stream::
* Deprecated Commands::


File: gri.info,  Node: Stable Stream,  Next: Version 2.12,  Prev: History,  Up: History

13.1 Stable Stream
==================

In any given stable stream, only the version with a `0' as the last
number in the triplet has new features; the later versions only correct
flaws.  For example, version `2.6.0' offers new features compared to
any of the `2.4.x' versions, but `2.6.1' differs only in the fixing of
bugs.

* Menu:

* Version 2.12::
* Version 2.10::
* Version 2.8::
* Version 2.6::
* Version 2.4::
* Version 2.2::


File: gri.info,  Node: Version 2.12,  Next: Version 2.10,  Prev: Stable Stream,  Up: Stable Stream

13.1.1 Version 2.12
-------------------

13.1.1.1 Version 2.12.15 [2007 Apr 16 Mawlid (http://en.wikipedia.org/wiki/Mawlid), celebration of birthday of Muhammad]
........................................................................................................................

*Bug Fixes*
   * Fix SourceForge bug #1700978
     (https://sourceforge.net/tracker/index.php?func=detail&aid=1700978&group_id=5511&atid=105511)
     ... html concept index mostly broken

   * Fix SourceForge bug #1698924
     (https://sourceforge.net/tracker/index.php?func=detail&aid=1698924&group_id=5511&atid=105511)
     ... box plots show missing data

   * Fix Debian bug #417217 ... will not compile in GCC 4.3

   * Fix SourceForge bug #1698116
     (https://sourceforge.net/tracker/index.php?func=detail&aid=1698116&group_id=5511&atid=105511)
     ... poorly-positioned name of RHS y-axis


13.1.1.2 Version 2.12.14 [2007 Jan 08: Coming-of-Age Day (Japan) (http://en.wikipedia.org/wiki/Seijin_shiki)]
.............................................................................................................

*Bug Fixes*
   * Fix SourceForge bug #1630768
     (https://sourceforge.net/tracker/index.php?func=detail&aid=1630768&group_id=5511&atid=105511)
     ... Fix to segfault in clipped images (a bug that may have
     developed after version 2.13.3)

13.1.1.3 Version 2.12.13 [2006 Nov 06: Constitution Day (Tajikistan) (http://en.wikipedia.org/wiki/Public_holidays_in_Tajikistan)]
..................................................................................................................................

*Bug Fixes*
   * Fix SourceForge bug #1591475
     (https://sourceforge.net/tracker/index.php?func=detail&aid=1591475&group_id=5511&atid=105511)
     ... Fix to compile in Solaris CC

   * Fix SourceForge bug #1591062
     (https://sourceforge.net/tracker/index.php?func=detail&aid=1591062&group_id=5511&atid=105511)
     ... Fix to compile in OpenBSD


13.1.1.4 Version 2.12.12 [2006 July 16: Yellow Pigs Day (http://en.wikipedia.org/wiki/Yellow_Pig%27s_Day)]
..........................................................................................................

*Bug Fixes*
   * Fix SourceForge bug #1523033
     (https://sourceforge.net/tracker/index.php?func=detail&aid=1523033&group_id=5511&atid=105511)
     ... Malloc error (freeing something already freed?)

   * Fix SourceForge bug #1523032
     (https://sourceforge.net/tracker/index.php?func=detail&aid=1523032&group_id=5511&atid=105511)
     ... `create columns from function' bug, if there is an existing
     directory called `tmp'.

   * Fix SourceForge bug #1491105
     (https://sourceforge.net/tracker/index.php?func=detail&aid=1491105&group_id=5511&atid=105511)
     ... `set x axis labels' had no affect for log axes (same for y)


13.1.1.5 Version 2.12.11 [2006 Mar 30: Hindu New Year]
......................................................

*Bug Fixes*
   * Fix SourceForge bug #1449546
     (https://sourceforge.net/tracker/index.php?func=detail&aid=1449546&group_id=5511&atid=105511)
     ... x axis limits not correctly inferred from `set x grid' (same
     for y).


13.1.1.6 Version 2.12.10 [2006 Jan 26: Australia Day]
.....................................................

*Bug Fixes*
   * Fix SourceForge bug #1408259
     (https://sourceforge.net/tracker/?func=detail&atid=105511&aid=1408259&group_id=5511)
     ... PostScript file contained private information.  This was fixed
     by adding new commandline arguments `-private' and `-no_private',
     the former of which (the new default) means to not include the
     user's name, the invocation arguments, or the command-file
     contents (*Note Invoking Gri::).

   * Fix SourceForge bug #1285180
     (http://sourceforge.net/tracker/index.php?func=detail&aid=12851803&group_id=5511&atid=105511)
     ... NaN was mishandled.  (The bug may have arisen in version
     2.12.7 or thereabouts.)

   * Port to the FreeBSD (http://www.freebsd.org/) operating system,
     with help from Christopher Illies and Roman Neuhauser.

   * Fix SourceForge bug #1217273
     (http://sourceforge.net/tracker/index.php?func=detail&aid=1217273&group_id=5511&atid=105511)
     ... missing some version numbers within docs

   * Fix SourceForge bug #1196613
     (http://sourceforge.net/tracker/index.php?func=detail&aid=1196613&group_id=5511&atid=105511)
     ... user-supplied x-axis labels can run offscale (fix for y-axis
     later...)

   * Fix SourceForge bug #1198341
     (http://sourceforge.net/tracker/index.php?func=detail&aid=1198341&group_id=5511&atid=105511)
     ... x-axis labels incorrectly rotated (sometimes)

   * Fix SourceForge bug #1199280
     (http://sourceforge.net/tracker/index.php?func=detail&aid=1199280&group_id=5511&atid=105511)
     ... warning about `malloc' for RPN assignments

   * Fix SourceForge bug #1196115
     (http://sourceforge.net/tracker/index.php?func=detail&aid=1196115&group_id=5511&atid=105511)
     ... `gri_unpage' and `gri_merge' mis-installed

   * Fix SourceForge bug #1153209
     (http://sourceforge.net/tracker/index.php?func=detail&aid=1153209&group_id=5511&atid=105511)
     ... Emacs mode incompatible with new version of `gv' PostScript
     viewer

     Fix SourceForge bug #1101172
     (http://sourceforge.net/tracker/index.php?func=detail&aid=1101172&group_id=5511&atid=105511)
     ... `gri -help' incorrectly stated meaning of last argument(s)

   * Fix SourceForge bug #835711
     (http://sourceforge.net/tracker/index.php?func=detail&aid=835711&group_id=5511&atid=105511)
     ... `draw gri logo' fails.

   * Fix SourceForge bug #1098269
     (http://sourceforge.net/tracker/index.php?func=detail&aid=1098269&group_id=5511&atid=105511)
     ... problem compiling on AMD64 machine.  (Solution provided by
     Andreas Jochens, a Debian user.)

   * Fix SourceForge bug #867515
     (http://sourceforge.net/tracker/index.php?func=detail&aid=867515&group_id=5511&atid=105511)
     ... problem with junk appearing in images.

   * Fix SourceForge bug #875881
     (http://sourceforge.net/tracker/index.php?func=detail&aid=875881&group_id=5511&atid=105511)
     ... problem compiling with gcc 2.95.3 compiler.


13.1.1.7 Version 2.12.9 [2005 Jan 6: Feast of Epiphany (http://en.wikipedia.org/wiki/Epiphany_%28feast%29)]
...........................................................................................................

*Bug Fixes*
   * Fix SourceForge bug #1094087
     (http://sourceforge.net/tracker/index.php?func=detail&aid=1094087&group_id=5511&atid=105511)
     ... `set path to' incorrectly parsed colon-separated paths

   * Fix SourceForge bug #1085788
     (http://sourceforge.net/tracker/index.php?func=detail&aid=1085788&group_id=5511&atid=105511)
     ... `image *=', `image /=', `image ^=', and `image _=' all gave
     incorrect results

   * Fix SourceForge bug #1084123
     (http://sourceforge.net/tracker/index.php?func=detail&aid=1084123&group_id=5511&atid=105511)
     ... does not compile in fink

   * Fix SourceForge bug #676767
     (http://sourceforge.net/tracker/index.php?func=detail&aid=676767&group_id=5511&atid=105511)
     ... on fink systems, `help' does not work


13.1.1.8 Version 2.12.8 [2004]
..............................

*Bug Fixes*
   * Fix SourceForge bug #1019141
     (http://sourceforge.net/tracker/index.php?func=detail&aid=1019141&group_id=5511&atid=105511)
     ... `draw arc' ignores the present pen color

   * Fix SourceForge bug #997741
     (http://sourceforge.net/tracker/index.php?func=detail&aid=997741&group_id=5511&atid=105511)
     ... PostScript broken on images with y-axis decreasing, and
     enclosed by PostScript clipping

   * Fix SourceForge bug #978822
     (http://sourceforge.net/tracker/index.php?func=detail&aid=978822&group_id=5511&atid=105511)
     ... documentation wrong on `set path to'

   * Fix SourceForge bug #932203
     (http://sourceforge.net/tracker/index.php?func=detail&aid=932203&group_id=5511&atid=105511)
     ... misplaced labels caused by `set x axis labels'

   * Fix SourceForge bug #928277
     (http://sourceforge.net/tracker/index.php?func=detail&aid=928277&group_id=5511&atid=105511)
     ... `draw polygon' should take `cm' and `pt' units

   * Fix SourceForge bug #930259
     (http://sourceforge.net/tracker/index.php?func=detail&aid=930259&group_id=5511&atid=105511)
     ... fix `draw arc''s drawing of an extra line (thanks for the fix,
     Wolfgang Voegeli)

   * Fix SourceForge bug #923719
     (http://sourceforge.net/tracker/index.php?func=detail&aid=923719&group_id=5511&atid=105511)
     ... `draw curve overlying' ignored the effect of `set dash'

   * Fix SourceForge bug #914125
     (http://sourceforge.net/tracker/index.php?func=detail&aid=914125&group_id=5511&atid=105511)
     ... offpage points in axes were reported as having been drawn by
     `draw curve'.

   * Fix SourceForge bug #877613
     (http://sourceforge.net/tracker/index.php?func=detail&aid=877613&group_id=5511&atid=105511)
     ... `help' (and other commands using temporary files) does not
     work in OSX/Fink version.

   * Fix SourceForge bug #874483
     (http://sourceforge.net/tracker/index.php?func=detail&aid=874483&group_id=5511&atid=105511)
     ... `state save' doesn't keep track of `dash' settings.

   * Fix SourceForge bug #873245
     (http://sourceforge.net/tracker/index.php?func=detail&aid=873245&group_id=5511&atid=105511)
     ... inaccurate times are given in the warnings about slow
     operations on OSX platform (days are reported instead of seconds)

   * Fix SourceForge bug #871477
     (http://sourceforge.net/tracker/index.php?func=detail&aid=871477&group_id=5511&atid=105511)
     ... the `missing value' feature should not be the default.  The
     solution involved adding a new command `set missing value none',
     which is now the default.


13.1.1.9 Version 2.12.7 [2003 Sep 4]
....................................

*Bug Fixes*
   * Fix SourceForge bug #800022
     (http://sourceforge.net/tracker/index.php?func=detail&aid=800022&group_id=5511&atid=105511)
     AKA Debian bug #208589
     (http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=208589), ... did
     not build on some Debian platforms because it was based on an old
     version of `automake'.


13.1.1.10 Version 2.12.6 [2003 Sep 1: Labour Day]
.................................................

*New Features*
   * Add `age' RPN function, for testing file ages (*Note
     age-rpn-operator::).


   *Bug Fixes*
   * Fix SourceForge bug #773850
     (http://sourceforge.net/tracker/index.php?func=detail&aid=773850&group_id=5511&atid=105511)
     ... bounding-box is increased by `draw symbol' even if
     (rectangular) postscript clipping is active.

   * Fix SourceForge bug #760130
     (http://sourceforge.net/tracker/index.php?func=detail&aid=760130&group_id=5511&atid=105511)
     ... Solaris cannot compile with <C-l> in Makefile.

   * Fix SourceForge bug #743134
     (http://sourceforge.net/tracker/index.php?func=detail&aid=743134&group_id=5511&atid=105511)
     ... bounding box not limited by `set clip postscript'

   * Fix SourceForge bug #750561
     (http://sourceforge.net/tracker/index.php?func=detail&aid=750561&group_id=5511&atid=105511)
     ... during compilation, `make' rebuilds HTML docs even if
     up-to-date


13.1.1.11 Version 2.12.5 [2003 May 19: Victoria Day]
....................................................

*New Features*
   * Apply a patch provided Kawamura Masao, relating to (a) errors in
     the documentation of file locations and (b) a programming error
     hidden behind an unset precompiler flag.

   * Add hexadecimal colornames (*Note pen-color-hexadecimal::).


   *Bug Fixes*
   * Fix SourceForge bug #739761
     (http://sourceforge.net/tracker/index.php?func=detail&aid=739761&group_id=5511&atid=105511)
     ... `draw time stamp' named the command-file incorrectly

   * Fix SourceForge bug #720607
     (http://sourceforge.net/tracker/index.php?func=detail&aid=720607&group_id=5511&atid=105511)
     ... the emacs mode looked for html documentation files in an
     incorrect location on linux/redhat systems


13.1.1.12 Version 2.12.4 [2003 Apr 06]
......................................

*Bug Fixes*
   * Fix SourceForge bug #696073
     (http://sourceforge.net/tracker/index.php?func=detail&aid=696073&group_id=5511&atid=105511)
     ... did not handle `\$()' syntax correctly.

   * Fix SourceForge bug #715884
     (http://sourceforge.net/tracker/index.php?func=detail&aid=715884&group_id=5511&atid=105511)
     ... mixup on protected-quotes within double-quoted strings

   * Fix Debian bug #183912
     (http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=183912) ...
     would not compile on m86k architecture.

   * Fix SourceForge bug #711354
     (http://sourceforge.net/tracker/index.php?func=detail&aid=711354&group_id=5511&atid=105511)
     ... `Creator:' comment in PostScript file named the command-file
     incorrectly, if there were options on the gri invocation command.
     Since this naming of the command-file was not especially useful,
     and since nobody has complained of this bug but the author, the
     feature has simply been deleted.  Just complain if you want it
     back!

   * Fix SourceForge bug #706202
     (http://sourceforge.net/tracker/index.php?func=detail&aid=706202&group_id=5511&atid=105511)
     ... A hint about the page orientation was not given in the
     Postscript comments.  The lack of this hint has no affect on
     printing, etc., only viewing in some viewers.


13.1.1.13 Version 2.12.3 [2003 Mar 1]
.....................................

*Bug Fixes*
   * Fix SourceForge bug #685919
     (http://sourceforge.net/tracker/index.php?func=detail&aid=685919&group_id=5511&atid=105511)
     ... `-output' commandline argument failed on `.eps' file extension.


13.1.1.14 Version 2.12.2 [2003 Feb 7: Munro Day at Dalhousie University (http://www.dal.ca/)]
.............................................................................................

*Bug Fixes*

   * Fix SourceForge bug #675304
     (http://sourceforge.net/tracker/index.php?func=detail&aid=675304&group_id=5511&atid=105511)
     ... Segmentation fault can occur on `read image pgm' if an image
     already exists, e.g. created by `convert grid to image'.

   * Fix SourceForge bug #647234
     (http://sourceforge.net/tracker/index.php?func=detail&aid=647234&group_id=5511&atid=105511)
     ... Source file `draw.cc' will not compile on MAC OS X 10.1.5 at
     optimization level 2, so drop the level to no optimization, as a
     temporary measure.

   * Fix SourceForge bug #671022
     (http://sourceforge.net/tracker/index.php?func=detail&aid=671022&group_id=5511&atid=105511)
     ... `flip image x|y' did not flip images correctly, except in
     special circumstances.

   * Fix SourceForge bug #669603
     (http://sourceforge.net/tracker/index.php?func=detail&aid=669603&group_id=5511&atid=105511)
     ... `skip backward .n.' erroneously skipped forward

   * Fix SourceForge bug #667754
     (http://sourceforge.net/tracker/index.php?func=detail&aid=667754&group_id=5511&atid=105511)
     ... `read image pgm' segfaults on memory if an image has already
     been created by `convert grid to image'

   * Fix SourceForge bug #664388
     (http://sourceforge.net/tracker/index.php?func=detail&aid=664388&group_id=5511&atid=105511)
     ... `read image pgm' fails if an image already exists

   * Fix SourceForge bug #654129
     (http://sourceforge.net/tracker/index.php?func=detail&aid=654129&group_id=5511&atid=105511)
     ... ignoring `~/.grirc' file

   * Fix SourceForge bug #654127
     (http://sourceforge.net/tracker/index.php?func=detail&aid=654127&group_id=5511&atid=105511)
     ... configure scripts are broken

   * Fix SourceForge bug #649132
     (http://sourceforge.net/tracker/index.php?func=detail&aid=649132&group_id=5511&atid=105511)
     ... removed unused LDFLAGS phrase from Makefile

   * Fix SourceForge bug #649134
     (http://sourceforge.net/tracker/index.php?func=detail&aid=649134&group_id=5511&atid=105511)
     ... tweak gcc optimization

   * Fix SourceForge bug #649136
     (http://sourceforge.net/tracker/index.php?func=detail&aid=649136&group_id=5511&atid=105511)
     ... examples 8 and 9 broken

   * Fix SourceForge bug #641406
     (http://sourceforge.net/tracker/index.php?func=detail&aid=641406&group_id=5511&atid=105511)
     ... RPN too aggressive on missing values


13.1.1.15 Version 2.12.1 [2002 Sep 25]
......................................

*Bug Fixes*

   * Fix SourceForge bug #613075
     (http://sourceforge.net/tracker/index.php?func=detail&aid=613075&group_id=5511&atid=105511)
     ... RPN operators `sin', `cos', and `tan' were limited in range
     (new bug in last release)


13.1.1.16 Version 2.12.0 [2002 Sep 15: Terry Fox Day (http://www.terryfox.org/), Canada.]
.........................................................................................

*New Features*

   * Add `sed' RPN operator, to work on strings *Note Binary
     Operators::.

   * Add `skewness' and `kurtosis' RPN operators, to work on columns
     *Note Manipulation of Columns etc::.


   *Removed Features*

   * n/a


   *Bug Fixes*

   * Fix SourceForge bug #606303
     (http://sourceforge.net/tracker/index.php?func=detail&aid=606303&group_id=5511&atid=105511)
     ... web-pages were not valid html-4.0.

   * Fix SourceForge bug #593958
     (http://sourceforge.net/tracker/index.php?func=detail&aid=593958&group_id=5511&atid=105511)
     ... missing-values should be ignored if they occur in intermediate
     results of RPN calculations.

   * Fix SourceForge bug #600395
     (http://sourceforge.net/tracker/index.php?func=detail&aid=600395&group_id=5511&atid=105511)
     ... won't compile with recently released version (3.2) of GCC
     compiler.

   * Fix SourceForge bug #600233
     (http://sourceforge.net/tracker/index.php?func=detail&aid=600223&group_id=5511&atid=105511)
     ... segfaults if some RPN operators are used on stacks that do not
     contain enough entries (e.g. `show {rpn cosh}').


File: gri.info,  Node: Version 2.10,  Next: Version 2.8,  Prev: Version 2.12,  Up: Stable Stream

13.1.2 Version 2.10
-------------------

13.1.2.1 Version 2.10.1 [2002 Jun 1]
....................................

*Bug Fixes*

   * Fix SourceForge bug #562911
     (http://sourceforge.net/tracker/index.php?func=detail&aid=562911&group_id=5511&atid=105511)
     ... won't build with `gcc-3.0' compiler.  This was reported by the
     Debian hppa builder as Debian bug #148572
     (http://bugs.debian.org/148572).

   * Fix SourceForge bug #562558
     (http://sourceforge.net/tracker/index.php?func=detail&aid=562558&group_id=5511&atid=105511)
     ... `draw title' terminates program if have non-positive data and
     had initially specified log axes.

   * Fix SourceForge bug #562014
     (http://sourceforge.net/tracker/index.php?func=detail&aid=562014&group_id=5511&atid=105511)
     ... won't build if `popt' library is unavailable.  This was
     reported by the Debian ia64 builder as Debian bug #148493
     (http://bugs.debian.org/148493).

   * Fix SourceForge bug #558463
     (http://sourceforge.net/tracker/index.php?func=detail&aid=558463&group_id=5511&atid=105511)
     ... in HTML docs, the "press" margin tag was misdirected.

   * Fix SourceForge bug #562017
     (http://sourceforge.net/tracker/index.php?func=detail&aid=562017&group_id=5511&atid=105511)
     ... parser fails with DOS end-of-line.

   * Fix SourceForge bug #562113
     (http://sourceforge.net/tracker/index.php?func=detail&aid=562113&group_id=5511&atid=105511)
     ... `new page' postscript error in `gv' viewer.


13.1.2.2 Version 2.10.0 [2002 May 20: Victoria Day]
...................................................

*New Features*

   * In the documentation, change the names of some variables to be
     clearer: `ll_x' is now written `xleft', etc.

   * Add RPN binary operators `and', `or' for logical operations *Note
     Binary Operators::, along with negation operator `not' *Note Unary
     Operators::.

   * Add `draw arc' command (*Note Draw Arc::).

   * Add `set x axis labels' (*Note Set X Axis::) and `set y axis
     labels' (*Note Set Y Axis::) commands.

   * Permit specification of `pt' units for `draw label' (*Note Draw
     Label::), `draw box' (*Note Draw Box::), `draw symbol at' (*Note
     Draw Symbol At::), and `draw line from' (*Note Draw Line From::).

   * Add `set clip to curve' (*Note Set Clip::) command.  _Caution:_
     this needs extension, and may have a bug if called twice in
     succession [but is this with an intervening `set clip off']

   * Add `group' and `end group' commands, in preparation for SVG
     output.  So far these commands do nothing, and are basically just a
     signal that users should not create commands with these names
     since Gri will need them soon.

   * Add `..xinc..' and `..yinc..' builtin variables (*Note Axis
     Scaling::).

   * Make the `open' command accept URLs as filenames (*Note Open::).


   *Removed Features*

   * Remove `gri -repair old.ps new.ps' since (a) it was only half
     functional, (b) it was hard to code in the new scheme of
     argument-processing and (c) the author was not aware of anybody
     every having used it.

   * Make the `-chatty' commandline option require a value (*Note
     Invoking Gri::).


   *Bug Fixes*

   * Fix SourceForge bug #552009 (`rpn' can segfault if `!=' operator
     is written as `=!')

   * Fix SourceForge bug #546109 (bounding box wrong if postscript
     clipping used)

   * Fix SourceForge bug #514495 in which `set clip to curve' failed to
     handle missing values in the curve.

   * Fix SourceForge bug #450465 (`create columns from function' was
     broken).



File: gri.info,  Node: Version 2.8,  Next: Version 2.6,  Prev: Version 2.10,  Up: Stable Stream

13.1.3 Version 2.8
------------------

13.1.3.1 Version 2.8.7 [2002 Apr 03]
....................................

   * Fix SourceForge bug #482120 (`regress' ignores data weights)

   * Fix SourceForge bug #508657 (missing backslash in drawing
     undefined synonyms)

   * Fix SourceForge bug #523450 (log axes detect non-positive values
     too late)

   * Fix SourceForge bug #521045 (installation/compilation with Solaris
     Workshop V6 Update 2 compiler)

13.1.3.2 Version 2.8.6 [2002 Feb 14]
....................................

   * Fix SourceForge bug #513002 (minor documentation error in `set
     clip')

   * Fix SourceForge bug #509592 (HTML docs had midordered indices)

   * Fix SourceForge bug #506534 (map axes give wrong minutes in
     negative regions).  Thanks, Brian, for the patch on this!

   * Fix SourceForge bug #508088 (grimode: gv should update, not be
     relaunched)

   * Fix SourceForge bug #506490 (`-v' commandline option returned
     wrong version number)

13.1.3.3 Version 2.8.5 [2001 Dec 13]
....................................

   * Fix SourceForge bug #492472 (`inf' rpn operator caused segfault)

13.1.4 Version 2.8.4 [2001 Oct 4]
---------------------------------

   * Fix SourceForge bug #467973 (`gri -version' gave wrong version
     number, breaking the Emacs Gri mode.)

   * Fix SourceForge bug #468014 (`draw grid' disobeyed pencolor.)

13.1.4.1 Version 2.8.3 [2001 Oct 1]
...................................

   * Fix SourceForge bug #462243 (endian problem in Rasterfile images +
     reading problem in PGM images).

13.1.4.2 Version 2.8.2 [2001 Sep 19]
....................................

   * Fix SourceForge bug #461444 (wouldn't compile with the `mingw32'
     compiler, for windows 32 machines).

   * Fix SourceForge bug #454557 (wouldn't compile with the pre-release
     version 3.0.1 of the GNU c++ compiler, in the case in which netCDF
     was already installed)

13.1.4.3 Version 2.8.1 [2001 Sep 7]
...................................

   * Fix SourceForge bug #450465 (`create columns from function' was
     broken).

   * Fix SourceForge bug #454557 (wouldn't compile with the pre-release
     version 3.0.1 of the GNU c++ compiler)

13.1.5 Version 2.8.0 [2001 Jul 30]
----------------------------------

New command syntax
   * Add `unlink' command as a unix-familiar way to delete files (*Note
     Unlink::).

   * Add `set page size' command to clip to a given page size (*Note
     Set Page::).

   * Add `substr' RPN operator to permit extraction of sub-strings
     (*Note Tertiary Operators::).

   * Add `default' possibility for the `set x name' and the `set y
     name' commands.

   * Add Perl-like ability to put underscores in numerical constants, to
     guide your eye.  These underscores are ignored by Gri, so that for
     example `.v. = 1_000' and `.v. = 1000' are equivalent as far as
     Gri is concerned.

   Emacs mode (*Note Emacs Mode::)
   * Give <M-Tab> the ability to complete builtin variables and
     synonyms as well as commands

   * Add "idle-timer minibuffer help" to display defaults for builtin
     variables under the cursor.

   * Add fontification of builtin variables _only_ if they are spelled
     correctly.

   Developer changes
   * Add `make source-arch-indep' target in sources.  This will build a
     source tar file in which all the architecture-independent material
     (documentation in HTML, postscript and Info formats) is pre-made.
     This makes it easier to install gri on a host that doesn't have
     TeX and ImageMagick installed.

   * Complete the port to IBM's compiler for their AIX operating system.


File: gri.info,  Node: Version 2.6,  Next: Version 2.4,  Prev: Version 2.8,  Up: Stable Stream

13.1.6 Version 2.6
------------------

13.1.7 Version 2.6.4 [2001 Jul 9: Dan's birthday]
-------------------------------------------------

   * Fix SourceForge bug #435688 (remnants of `polar' column type, no
     longer supported, remained in documentation)

   * Fix SourceForge bug #435603 (`set dash' produced broken PostScript)

   * Fix SourceForge bug #431114 (`-0' could appear on axes)

13.1.8 Version 2.6.3 [2001 Jun 22]
----------------------------------

   * Fix SourceForge bug #433250 (`draw symbol' ignored dashing state
     sometimes)

   * Fix SourceForge bug #432549 (contours sometimes unlabelled)

   * Tweak internal coding for compilation on AIX compilers.

13.1.8.1 Version 2.6.2 [2001 May 19]
....................................

   * Fix SourceForge bug #425174 (synonym interpolation broken on e.g.
     `show "[\syn]"'

   * Fix SourceForge bug #425175 (`while !..eof..' acted ignored end of
     file)

13.1.8.2 Version 2.6.1 [2001 May 10]
....................................

   * Fix SourceForge bug #420499 (gri-mode.el compatibility issues with
     emacs-21;  Mostly bad old code.)

   * Fix SourceForge bug #421076 (byte-compiled gri-mode.el has broken
     IMenu support;  Affects Debian package.)

   * Fix SourceForge bug #419599 (wouldn't compile under GNU g++ 3.x
     compiler)

   * Fix SourceForge bug #418065 (documentation mentions back-tic
     notation, which is not available)

   * Fix SourceForge bug #417333 (vague error message `RPN string
     operator')

   * Fix SourceForge bug #415277 (make fails on MSDOS)

   * Fix SourceForge bug #415149 (`file.cc' parse error on MSDOS)

   * Fix SourceForge bug #414520 (`draw symbol ... at' should
     automatically produces axes unless the location is in `cm'
     coordinates)

   * Fix SourceForge bug #414010 (items in the html concept index were
     in an odd order)

   * Fix SourceForge bug #413986 (`~username' was broken in `open')

   * Fix SourceForge bug #411904 (`/' was ugly in math mode)

13.1.8.3 Version 2.6.0 [2001 April 1]
.....................................

   * Permit `rewind' to take a filename.

   * Make `open' set `\.return_value.' to the full pathname of the file
     that was opened.

   * Add `set path' command (*Note Set Path To::).

   * Remove functioning of `GRIINPUTS' environment variable, since this
     is more cleanly handled with the newly added `set path to' command
     (*Note Set Path To::).

   * Remove `\.awk.' synonym, which was deemed to be unhelpful.  Users
     with many scripts that use this variable might wish to put a line
     like
          \.awk. = "gawk"
     in their `~/.grirc' file.

   * Change the format of images in the PostScript output file, as a
     workaround for a bug in the `ps2pdf' program.

   * Add "ampersand" (`\&' and `\&&') syntax to permit newcommands to
     look up the name and nesting level of changeable arguments (*Note
     Changeable Command Arguments::).

   * Add "at-sign" (`@') syntax for aliases (*Note Alias Synonyms::).

   * Add ability to embed newlines in `show' commands with the `\<<'
     sequence (*Note Show::).

   * Add ability to embed TAB characters in `show' commands with the
     `\>>' sequence (*Note Show::).

   * Make various `read' commands (*Note Read::) able to decode synonyms
     as well as variables and simple numbers.

   * Add `strlen' RPN operator (*Note Unary Operators::).

   * Add `default' option to `set x format' and `set y format' commands.

   * Add `new postscript file' (*Note New Postscript File::) command.

   * Switch email list from `majordomo' to GNU `mailman'.

   * No longer remove comments from data lines that are read.  This
     served little function, interfered with recent user code, and
     could be accomplished by reading through a `sed' pipe in any case.

   * Make the first element of the `argv' array be the name of the
     command-file.  (This makes Gri consistent with languages such as
     C.)

   * Add chapter on test suite (*Note Test Suite::).

   * Let newcommands have changeable arguments (*Note Changeable
     Command Arguments::).

   * Remove `-s' as an abbreviation for the commandline option
     `-superuser'.

   * Remove the `:' syntax from the commandline options.

   * Add commandline option `-output PS_file_name'.

   * Add `assert' command (*Note Assert::).

   * Add test suite (mainly for developers).

   * Add `sleep' command (*Note Sleep::).

   * Remove command `show hint of the day', since I no longer permission
     to use cgi-bin to provide the hints via web-server.

   * Permit indexing of synonym words with variables, in addition to
     constants.

   * Fix bug in interpolating synonyms in the test-expression of
     `while' loops.

   * Put source on the Source Forge open-source development website, at
     `http://gri.sourceforge.net'.  Gri users can benefit from this
     site in may ways.  First, it is a great way to keep track of new
     versions.  With a mouse-click you can cause SourceForge to email
     you whenever a new version of Gri is released.  Second,
     SourceForge has newsgroups
     (`http://sourceforge.net/forum/?group_id=5511') and email lists
     (`http://sourceforge.net/mail/?group_id=5511') devoted to Gri.
     These are archived, so that you can stop monitoring them for a
     while and then go back and see what you've missed.  Third, Source
     Forge has a powerful bug-tracking facility.
     (`http://sourceforge.net/bugs/?group_id=5511') With this you may
     check for existing bugs reported by users, submit new bug reports,
     and also track the process of bug removal (e.g. optionally
     receiving emails when the bug is removed).

   * Add `set colorname' command (*Note Set Colorname::).

   * Add `source' command (*Note Source::).

   * Add RPN operators `wordc' (*Note Solitary Operators::) and `wordv'
     (*Note Unary Operators::) for accessing the words in the present
     Gri command.

   * Add RPN operators `argc' (*Note Solitary Operators::) and `argv'
     (*Note Unary Operators::) for accessing the command-line arguments
     used when Gri was invoked from the operating system.

   * Add automatic support for compressed data files.  So far, this only
     works with gzipped files (*Note Open::).

   * Add two new RPN operators, `file_exists' and `directory_exists'
     (*Note Unary Operators::).

   * Reorganize parts of manual (e.g.  changing the section about the
     Emacs `gri-mode.el' into a chapter, with screen snapshots).

   * Improve the HTML form of the manual (e.g. color-code the Gri
     syntax in examples, provide access to all the indices, use Jpeg
     format, et.).

   * Add several new features to `gri-mode.el':

     1) Add a menubar pull-down menu listing all Gri commands,
     allowing the user to get `Help' or `Info' on any command or
     `Insert' it in the current Gri file.

     2) Add a menubar pull-down entry to `Perform' to set
     `gri-run' settings such as flag options passed to gri.

     3) Gri info file can have *.info* extension now.

     4) Made `gri-apropos' an alias for `gri-help-apropos'.

     5) gri-mode now uses the customize interface (See
     `gri-customize').

     6) The `~/.gri-syntax' file has changed format.  As a
     side-effect, spaces are used instead of hyphens to display Gri
     commands,       and one can now select a command with the mouse in
     the       *Completions* buffer.



File: gri.info,  Node: Version 2.4,  Next: Version 2.2,  Prev: Version 2.6,  Up: Stable Stream

13.1.9 Version 2.4
------------------

13.1.9.1 Version 2.4.4 [2000 May 7]
...................................

Change so that only a warning is printed if mathematical operations are
requested on empty arrays (e.g. `y += 10').  Previously, an error was
reported and Gri exited with an error condition, which is bothersome in
scripts that rely on successful completion of the Gri job.

   Port to the BeOS operating system.

13.1.9.2 Version 2.4.3 [2000 Apr 1]
...................................

Change location of all files, to be consistent with Redhat convention.
Previously, things were in `/opt/gri'; now they are in more standard
locations.

13.1.9.3 Version 2.4.2 [2000 Mar 25]
....................................

Remove bug in which `convert grid to image' produced incorrect images,
visible as a patchy appearance with coarse grids.

13.1.9.4 Version 2.4.1 [2000Jan 31]
...................................

Remove bug in which `convert image to grid' failed to take note of the
gri minimum and maximum, so that contouring of the grid was not
possible for grids created from images.

13.1.9.5 Version 2.4.0 [2000 Jan 05]
....................................

Add `set input data separator'.  Make `read columns' work with various
input separators. Make `read .x.', etc, work with various input
separators.


File: gri.info,  Node: Version 2.2,  Next: Unstable Stream,  Prev: Version 2.4,  Up: Stable Stream

13.1.10 Version 2.2
-------------------

13.1.10.1 Version 2.2.6 [1999 Nov 25]
.....................................

Make web-based manual easier to read by putting a light-grey background
under sample code.

13.1.10.2 Version 2.2.5 [1999 Nov 10]
.....................................

Fix bug in RPN calculations that prevented using a negative exponent.

13.1.10.3 Version 2.2.4 [1999 Nov 7]
....................................

Add `set font encoding', and also change the encoding to ISO-Latin-1.
(This doesn't hurt old code since Gri didn't make any claims to handle
characters outside the normal printing-set before anyway.)

   Fix bug in which there were 4 dead links in the HTML version of
manual.

   Clean up some problems with Debian distribution (thanks, Peter
Galbraith!).

13.1.10.4 Version 2.2.3 [1999 Jun 30]
.....................................

Fix bug in which word-of-synonym (e.g. `\[0]mysyn') was not detected
correctly (thanks to bug report from Kazuhiko Nakayama in Japan)

13.1.10.5 Version 2.2.2 [-]
...........................

Clean a few spelling and cross-reference errors in documentation.

13.1.10.6 Version 2.2.1 [1999 Mar 31]
.....................................

For debian, properly locate the `netcdf' library, if it is installed.

   Remove remnants of old commands for polar axes.

   Correct error in which the right-most and upper-most pixel of images
created by `convert grid to image' may be blank (or not, depending on
roundoff error) under certain conditions of exact matchup between grid
spacing and image spacing.

   Don't create PostScript file if the commandfile is non-existent, or
if there were errors on the commandline.

13.1.10.7 Version 2.2.0 [1999 Mar 25]
.....................................

First debian release.  Versions exist for intel, alpha, 68K and powerpc.


File: gri.info,  Node: Unstable Stream,  Next: Development Version,  Prev: Version 2.2,  Up: History

13.2 Unstable Stream
====================

* Menu:

* Development Version::
* Plans::


File: gri.info,  Node: Development Version,  Next: Plans,  Prev: Unstable Stream,  Up: Unstable Stream

13.2.1 Development Version
--------------------------

The list below shows changes that have been made in the development
version of Gri, i.e. the version on CVS at
`http://gri.sourceforge.net'.  Some or all of these features may enter
the next stable stream of Gri, but it is important to note that
_anything_ that's listed here may be changed without notice!  The main
exception is bug fixes, which will enter the stable stream unless they
are found to create new bugs.

13.2.1.1 New Features
.....................

   * n/a

13.2.1.2 Removed Features
.........................

   * n/a

13.2.1.3 Bug Fixes
..................

   * Fix SourceForge bug #618041
     (http://sourceforge.net/tracker/index.php?func=detail&aid=618041&group_id=5511&atid=105511)
     ... solaris compile error, relating to the subroutine
     `gethostname()' in the `startup.cc' source code file.



File: gri.info,  Node: Plans,  Next: Deprecated Commands,  Prev: Development Version,  Up: Unstable Stream

13.2.2 Plans
------------

Some plans for future versions are given below.  A more extensive list,
together with target timescales and notes on the progress towards
completion, is available in the to-do list at the development site
(`http://gri.sourceforge.net'), which is also the place to go if you
have suggestions for other changes to Gri.

13.2.2.1 High Priority
......................

  1. Add ability to generate SVG (scalable vector graphics) output.
     This file type can be edited with GUI-based tools, making it easy
     for users to put the final touches on graphs "manually."  This
     feature will require a great deal of work, mainly to do with
     grouping of graphical elements, and so I'll need to rely on advice
     from users.

  2. Switch to `popt' library for the processing of command-line
     options.  (Docs on this are at
     `http://cvs.gnome.org/lxr/source/popt'.)

  3. Change `set axes style' from number-based selection to word-based
     selection, and print a deprecation warning if the number-based
     syntax is used.

  4. Switch from `tmpname' to `mkstemp' subroutine, for temporary
     filenames.

  5. Add readline support, to handle history, command-line editing, etc,
     for interactive usage (Docs on this are at
     `http://cnswww.cns.cwru.edu/~chet/readline/readline.html'.)


13.2.2.2 Medium priority
........................

  1. Add optimal interpolation as another method for gridding data
     (*Note Convert Columns To Grid::).

  2. Add ability to read PNG images (*Note Read Image::) (Docs on this
     are at `http://www.libpng.org/pub/png/'.)


13.2.2.3 Low priority
.....................

  1. Add non-RPN mathematics.

  2. Add graphical output to the screen as commands are executed.

  3. Add support for both little-endian and big-endian binary data.



File: gri.info,  Node: Deprecated Commands,  Next: Installation,  Prev: Plans,  Up: History

13.3 Deprecated Commands
========================

   * _version 2.9.0_
        * Replace `set y axis label horizontal' with `set y axis name
          horizontal'.

        * Replace `set y axis label vertical' with `set y axis name
          vertical'.


File: gri.info,  Node: Installation,  Next: Unix-install,  Prev: Deprecated Commands,  Up: Top

14 Installing Gri
*****************

* Menu:

* Unix-install::
* Msdos-install::
* OS2-install::
* Mac-install::
* Beos-install::


File: gri.info,  Node: Unix-install,  Next: Archiving Old Versions,  Prev: Installation,  Up: Installation

14.1 Unix Installation
======================

* Menu:

* Archiving Old Versions::      Keeping the old and the new
* Linux::                       Installing on linux
* Precompiled Unix::            Installing precompiled versions
* Uncompiled Unix::             Compiling and installing


File: gri.info,  Node: Archiving Old Versions,  Next: Linux,  Prev: Unix-install,  Up: Unix-install

14.2 Archiving Old Versions
===========================

Gri, like other complex programs, sometimes changes in such a way as to
break old scripts.  This is less so of changes since about 1998 or so,
since the syntax became pretty firm about that time.

   Still, disk costs are so cheap that you would be well-advised to
keep a backup version of Gri, whenever you update.  This is pretty
simple; you need to keep a copy of the executable and the library file,
and you need to write a tiny shellscript that calls this particular
executable with this particular library file.  For example, you might
do the following

     mkdir -m 755 -p           /usr/local/share/gri/2.12.15
     cp /usr/bin/gri           /usr/local/share/gri/2.12.15
     cp /usr/share/gri/gri.cmd /usr/local/share/gri/2.12.15

and then create a shellscript called `/usr/local/bin/gri-2.12.15'
containing

     #!/usr/bin/sh
     /usr/local/share/gri/2.12.15/gri \
         -directory /usr/local/share/gri/2.12.15 \
         "$@"

to invoke this version of Gri.

   To be able to access this old version of gri from within the Emacs
gri-mode, you would reset the Emacs variable `gri*directory-tree' like
so in the file `~/.emacs' (*Note Step 2:: in *Note Installing
gri-mode.el::)

     (setq gri*directory-tree
         '("/usr/local/share/gri/" "/usr/share/gri/"))


File: gri.info,  Node: Linux,  Next: Precompiled Unix,  Prev: Archiving Old Versions,  Up: Unix-install

14.2.1 Installation on Linux computers
--------------------------------------

Installation is easy on RedHat and Debian flavors of linux.  Versions
are available from the official distributions and also at
`http://sourceforge.net/project/showfiles.php?group_id=5511'

   The RedHat version supports intel platforms only, while the Debian
version supports intel, alpha, 68K and powerpc.  Installation follows
the normal method for these distributions ... if you have the
distribution, you surely know what to do.  If you don't, you may want to
switch when you see that you can install Gri by clicking an icon in a
window, or by typing, e.g. in RedHat linux:

     rpm -i gri-2.12.15

   Debian-linux installation may be done with any of several GUI-based
tools, or with the following system command:

     dkpg -i gri_2.12.15-1_i386.deb

or via a properly configured `apt' interface that will fetch the latest
version from the net:

     apt-get install gri


File: gri.info,  Node: Precompiled Unix,  Next: Uncompiled Unix,  Prev: Linux,  Up: Unix-install

14.2.2 Pre-compiled unix versions
---------------------------------

Pre-compiled versions of Gri exist for various computers, e.g. SPARC
(both sunOS and solaris), IBM-RS, Sequent, and Linux.  The following
instructions, which assume a version number 2.12.15, and a SPARC
solaris machine, show how to install these.

   The compressed tar file, with a name like
`gri-binary-SunOS5-2.12.15.tar.gz' (in this example a Sun OS 5 binary
is assumed, with gri version number 2.12.15) contains a directory which
holds the executable Gri file, `gri', the library file `gri.cmd', an
instructions file, `README', and a Makefile to install Gri.

   Here's how to install Gri, starting with this tar file:

  1. First, uncompress (unzip) the file, and un-tar it, by doing

          gunzip -c gri-binary-SunOS5-2.12.15.tar.gz | tar xvf -

     or

          zcat gri-binary-SunOS5-2.12.15.tar.gz | tar xvf -

     This will yield a new directory, with a name like
     `gri-binary-SunOS5-2.12.15', which contains the indicated files.

  2. Follow the instructions in the `README' file to install Gri.


File: gri.info,  Node: Uncompiled Unix,  Next: Msdos-install,  Prev: Precompiled Unix,  Up: Unix-install

14.3 Compilation on Unix computers
==================================

The following steps indicate how to compile Gri on unix computers.  The
procedure is quite standard.

_Requirements_
     You'll need a C++ compiler that is modern enough to handle
     'templates' (i.e. almost any compiler from 1998 onward).  Don't
     worry - if your compiler isn't new enough, you'll see that in a
     minute or two!

     You'll need TeX and texinfo to make the info files, and optionally
     the netCDF library (if you wish gri to be able to read netCDF
     binary data files).  To make the HTML manual, you'll need
     imagemagick, info, gs and its fonts.

     On Debian GNU/Linux systems, the required packages are listed as
     Build-Depends in the `control' file found in the `debian'
     directory, to which you must add the package `build-essential'.

_Unpack the source_
     Type

          gunzip gri-2.12.15.tgz
          tar xvf gri-2.12.15.tar

     (or similar commands) to uncompress and untar the contents.  This
     will yield a new directory named `gri-2.12.15' which contains many
     files.

_Move to the Gri directory_
          cd gri-2.12.15

_Configure your compiler_
     Next you must "configure" the Gri source files.  During this step,
     a series of tests will be made about your operating system and your
     compiler.  Most of these tests need no interaction from you, but
     there is one overall choice that you may wish to make: the place
     on your filesystem where Gri (and many associated library and
     documentation files) will reside.  To get the default
     installation, with files residing within the directory
     `/usr/local', type

          ./configure

     at this time.  If you'd rather the files go into another location,
     run the `configure' script differently, e.g.  to get the Gri files
     to reside within the `/opt' directory, type:

          ./configure --prefix=/opt

     In response, you'll see the results of several tests of the
     properties of your operating system, your C++ compiler, etc.
     Normally you can ignore these results.

     As an example, typing `./configure' without a `--prefix' option
     yields the directory tree (`...' indicates several files not
     displayed in this list, for brevity).  In this example, the most
     up-to-date version is 2.12.15, but a previous version
     2.12.14 has also been retained.  (Note that only one copy of the
     documentation is retained; this is all that's needed, since old
     versions are documented there as well as new versions.)

          /usr/local
          |-- bin
          |   |-- gri -> gri-2.12.15
          |   |-- gri-2.12.15
          |   |-- gri-2.12.14
          |   |-- gri_merge
          |   `-- gri_unpage
          |-- info
          |   |-- ...
          `-- share
              `-- gri
                  |-- 2.6.0
                  |   |-- gri.cmd
                  |   |-- license.txt
                  |   |-- logo.dat
                  |   `-- startup.msg
                  |-- 2.4.0
                  |   |-- gri.cmd
                  |   |-- license.txt
                  |   |-- logo.dat
                  |   `-- startup.msg
                  `-- doc
                      |-- examples
                      |   |-- ...
                      `-- html
                          |-- ...
                          |-- resources
                          |   |-- ...
                          `-- screenshots
                              |-- ...

     Trouble-shooting 1: If the permission of the `configure' file is
     wrong, you'll get an error like `Permission denied'; if so, try
     typing `sh ./configure' to run it in the Bourne shell.  If that
     fails, you are going to have to do some old-fashioned work!  Start
     by copying the generic Makefile called `Makefile.generic' into
     `Makefile', and try the following steps, perhaps editing the
     `Makefile' if you run into errors.

     Trouble-shooting 2: Gri uses a C++ feature called 'templates'.
     Unfortunately, templates are handled in different ways by different
     compilers.  At least as of Spring 1997, the GNU compiler, vsn 2.7.x
     (used by many Gri folks) has problems with templates.  Therefore
     the configure script will check to see if you are using the GNU c++
     compiler, and if you are it will check whether the ("template
     repository") compiler flag `-frepo' is known on your machine.  If
     it is not, an alternative method of templates will be used.  But
     if it is, you'll be asked, for confirmation, whether you wish to
     use the `-frepo' flag.  On many machines (e.g. Solaris) you should
     answer `n' to this question.  The prompt will explain.  Also, note
     that you can avoid the prompt by running configure as either of
     the two below:

          ./configure --enable-frepo
          ./configure --disable-frepo

     (Such switches will be ignored unless you're using the GNU
     compiler.)

     Trouble-shooting 3: If optional system libraries like the netCDF
     library, if it exists, are installed in nonstandard places, you
     might have to change the unix environment variable
     `LD_LIBRARY_PATH'.  For example, on my machine the `netcdf'
     library is not installed in `/usr/lib', as the `configure' script
     assumes, but rather in `/usr/local/share/netcdf/lib'.  Therefore I
     have the following line in one of my startup files:

          export LD_LIBRARY_PATH=/usr/lib:/usr/local/share/netcdf/lib

_Compiling Gri_
     Now compile Gri by typing

          make

_Testing Gri_
     Type

          make test

     to do some tests on the version of Gri that you just compiled.  If
     no errors are reported, you may go to the next step.

_Installing Gri_
     Assuming compilation succeeds, install `gri' and the ancillary file
     `gri.cmd', by typing

          make install

     If you wish to see where files where be installed, first try a dry
     run typing

          make -n install

_Cleaning up_
     Once these things are done, you may type

          make clean
          cd doc ; make clean

     to clean up some files.  Of course, you could just erase the whole
     source, but the source is probably worth a penny of hard-drive
     space, isn't it?


File: gri.info,  Node: Msdos-install,  Next: OS2-install,  Prev: Uncompiled Unix,  Up: Installation

14.4 Compilation on x86 (PC-style) Computers
============================================

Versions exist for MSDOS, windows, and Linux operating systems.
(Actually, the windows version is just the MSDOS version, which can be
run inside an msdos window within windows-95, windows-NT, etc.)

14.4.0.1 MSDOS Operating System
...............................

To compile and install Gri under MSDOS, do this:
  1. To begin, install `DJGPP V2', if it is not on your system already.
     It can be found at `http://www.delorie.com/djgpp'

  2. Uncompress and extract from gri source package (*Note Uncompiled
     Unix::).

  3. Type `make -f Makefile.dj2' to compile.  If it fails, you might
     have to edit the file `Makefile.dj2' to match the characteristics
     of your system.  Please inform the author, Dan Kelley at
     Dan.Kelley@Dal.CA, if you think your modifications might be useful
     to others.

  4. Type `make -f Makefile.dj2 install' to install it (normally on the
     `C:' drive).

   If you encounter problems, read the first few lines of the Makefile
(i.e. the file `Makefile.dj2') for hints on things to try.  For
example, in the present version of `Makefile.dj2' these hints are given:
  1. There is a good chance that this Makefile will work as is, so try
     that first.

  2. If you have the `netcdf' library (used for certain types of
     atmospheric and oceanographic datasets), then un-comment and
     possibly edit the appropriate `NETCDF_...' lines below, as
     instructed by the comments preceding these lines.

  3. If you don't want Gri inserted in the directory `c:/gri', edit the
     `instdir = ...' line below.

  4. If you get error messages about the `stdcxx' library, edit the
     `LIBS' line below, rewriting `-lstdcxx' as `-lstdcx'.

  5. If you get compilation errors relating to `time' or to `ftime',
     try putting the token `-DHAVE_FTIME=1' in the list of similar
     token in the `DEFS = ...' line.  For consistency (basically, so
     the author can help you if you do this), put it right after the
     `-D_GRI_=1' token.

   To view the output, use a PostScript viewer such as GSview.
(`http://www.cs.wisc.edu/~ghost/index.html').

14.4.0.2 LINUX Operating System
...............................

Linux is a good emulation of unix, and it is free.  Gri for linux is
compiled and installed according to the normal unix instructions.  The
compiled version is with a name like
`gri-binary-solaris-2.1.10.tar.gz'; treat it as in other unix systems
(*Note Uncompiled Unix::).


File: gri.info,  Node: OS2-install,  Next: Mac-install,  Prev: Msdos-install,  Up: Installation

14.5 Compilation under OS/2
===========================

Gri compiles, using the gcc compiler under OS/2, provided that the
included `Makefile.os2' is used.  Be sure to edit the first few lines
to change filenames as required, especially taking care to account for
whether the netCDF library is installed, etc.


File: gri.info,  Node: Mac-install,  Next: Beos-install,  Prev: OS2-install,  Up: Installation

14.6 Compilation under Macintosh Unix
=====================================

The MachTen version of unix for Macintosh acts like a normal unix.
Provided that the associated `gcc' compiler is sufficiently up-to-date,
Gri can be compiled following the normal unix instructions.


File: gri.info,  Node: Beos-install,  Next: Bugs,  Prev: Mac-install,  Up: Installation

14.7 Compilation under BeOS
===========================

The BeOS system compiles Gri cleanly without modification; just follow
the instructions for unix.


File: gri.info,  Node: Bugs,  Next: Known Bugs,  Prev: Beos-install,  Up: Top

15 Bugs
*******

* Menu:

* Known Bugs::                  Bugs in the current version
* Reporting Bugs::              How to report bugs
* Killing Bugs::                How to (try to) kill bugs


File: gri.info,  Node: Known Bugs,  Next: Reporting Bugs,  Prev: Bugs,  Up: Bugs

15.1 Known bugs
===============

The ultimate reference for Gri bugs is the development website
`http://gri.sourceforge.net', which has a powerful bug-tracking
facility at
`http://sourceforge.net/tracker/?atid=105511&group_id=5511&func=browse'
that permits you to view bugs that have been fixed and bugs that still
exist, and that also lets you report bugs.

   A summary of some known bugs, some reported on the development site
and some not, follows.

   * The PDF version of the manual, created by `make gri.pdf', won't
     work unless the following patch is applied to one of the files of
     TexInfo, version 1999-03-26.17.  (This patch entered the official
     TeX sources in April 2001.)

          *** /usr/share/texmf/pdftex/texinfo/pdftexinfo.tex	Wed Dec 20 11:54:04 2000
          --- /usr/share/texmf/pdftex/texinfo/pdftexinfo.tex~	Mon Mar 29 06:17:02 1999
          ***************
          *** 5481,5487 ****
                  \fi
                \endgroup
              \else
          !     \centerline{\pdfimage {#1.pdf}}%
              \fi
            }

          --- 5481,5487 ----
                  \fi
                \endgroup
              \else
          !     \centerline{\pdfimage #1.pdf}%
              \fi
            }

   * The EPSF bounding-box defaults to an 8.5 by 11 inch page, if
     `-no_bounding_box' is specified on the commandline (*Note Invoking
     Gri::).  It should probably know about more paper sizes.

   * `draw contour labels nowhiteunder' does not break the line under
     the label, as it should.

   * `reorder columns' is slow because it uses a bubble-sort.

   * Support for `netCDF' binary files is limited, e.g. (1) consistency
     of grid x/y/data is not checked as it is in ascii/binary formats;
     (2) Gri cannot read image data; (3) `set input data window' has no
     effect: use `set clip' instead; and (4) Gri cannot output to
     `netCDF' files.

   * Errors sometimes report inaccurate line numbers.  (E.G.: errors
     inside newcommands report wrong line numbers if continued lines
     are present before the bad line.)

   * Images in rasterfile format: only mapless images permitted.

   * In an `insert'ed file, `read' commands which expect input from the
     commandfile, as opposed to a datafile, do not work.

   * The string size rpnfunctions `ascent("string")' and
     `descent("string")' are inaccurate.

   * Commands in the false part of `if' statements are not checked for
     proper syntax.  All commands in false parts of `if' statements are
     simply skipped, except for `end if' or `else [if]'.

   * Clipped lines should extend as far as the axis frame, but they
     don't.  Gri only draws line segments which connect two points each
     of which is inside the axis frame.  Workaround: use `set clip
     postscript' instead of `set clip'.

   * Aesthetics (y-axes): labels are sometimes ugly because they are
     right-justified, and the number of decimal points is not
     necessarily uniform in all labels.  Workaround: Set the format
     yourself (example: `set y format %.1f').


File: gri.info,  Node: Reporting Bugs,  Next: Killing Bugs,  Prev: Known Bugs,  Up: Bugs

15.2 Reporting Bugs
===================

Please report any bugs you find in Gri.  Bug reports help make Gri more
reliable and useful for all users.  The procedure for reporting bugs,
described below, is quite standard.

  1. Go to the bug-tracking part of the Source Forge Gri development
     site, at `http://sourceforge.net/bugs/?group_id=5511' to see
     whether your bug has already been reported.  You may find that it
     has been reported and fixed already in a new version, in which
     case you should archive your existing Gri version and upgrade.  If
     the bug has been reported and *not* fixed, then you may still wish
     to add a supplemental bug report, so the author knows that this
     bug is of concern to you as well as the others.  (Plus, reporting
     it this way ensures that you'll receive an email when the bug is
     fixed.)

  2. Debugging is made easier if the problem is reduced in scope.
     Therefore, please reduce your application and your data to the
     simplest case that produces the error.

  3. If you know how, please try to find the bug yourself.  After all,
     Gri is open-source for a reason!  The procedure is described in
     the next section (*Note Killing Bugs::).



File: gri.info,  Node: Killing Bugs,  Next: Debugging Software You Will Need,  Prev: Reporting Bugs,  Up: Bugs

15.3 Killing Bugs
=================

* Menu:

* Debugging Software You Will Need::
* Debugging at a Glance::
* Debugging Example::


File: gri.info,  Node: Debugging Software You Will Need,  Next: Debugging at a Glance,  Prev: Killing Bugs,  Up: Killing Bugs

15.3.1 Software that you'll need
--------------------------------

This section is intended to help you find and kill bugs yourself, by
indicating how the author does this work.  Since Gri is open-source,
all users are invited to try to kill bugs themselves!

   If you know nothing of C or C++, you may as well not read further,
since there is little chance of your making progress.  On the other
hand, experienced programmers won't need any of the advice I give below.

   You'll need the Gri source and a C++ compiler.  It also helps if you
have `gdb', the GNU debugger, installed; the instructions below assume
that's the case.  Also, the instructions assume that you're using the
Emacs editor, and running `gdb' from within Emacs.  Otherwise, you'll
want to glance at the documentation on `gdb' to see how to use it in
standalone mode.


File: gri.info,  Node: Debugging at a Glance,  Next: Debugging Example,  Prev: Debugging Software You Will Need,  Up: Killing Bugs

15.3.2 Debugging at a glance
----------------------------

The list below is a sketch of what you might try, and in what order.

   * Check the bug list to see if other users have found your bug, and
     also to see if there is a workaround.

   * Try a more recent version of gri.  If it works, you might wish to
     archive the version you have at the moment and upgrade.

   * If you suspect your bug has something to do with system calls, as
     in the `system' command (*Note System::) or as in piped input
     files (*Note Open::), you should re-run the script with `gri
     -superuser8' instead of with `gri'.  This will cause Gri to print
     out all commands that it is handing over to the operating system;
     you may see the error that way.  (Hint: it may help to
     interactively cut/paste the commands into your OS shell to see
     what the action of the command is.)

   * If your bug results in early termination, you should run Gri
     inside a debugger (e.g. GDB, assumed henceforth).  When the program
     terminates, type `where' to see where termination occured.  Often
     this will give a clue.  In many cases, early termination results
     from faults in memory allocation.  To check memory allocation,
     you'll need to recompile Gri, linking it against a debugging
     memory allocator.  Many such tools exist; see comments in the
     `Makefile' for a hint at how to use a popular one, called
     "Electric Fence."

   * If your bug does not result in early termination, you may find the
     best scheme is to trim your example down as much as possible, and
     then run Gri inside the GDB (or other debugger) so that you can
     monitor program execution.  The next section explains this in
     detail.


File: gri.info,  Node: Debugging Example,  Next: Test Suite,  Prev: Debugging at a Glance,  Up: Killing Bugs

15.3.3 A debugging Example
--------------------------

Let's take a recent bug as an example.  Peter Galbraith found that the
gri script

     set color hsb 0.999 1 1
     draw box filled 2 2 3 3 cm
     set color hsb 1.000 1 1
     draw box filled 4 2 5 3 cm

produced odd results in a previous version of Gri; the color patches
should have been of nearly the same color, but the first one was red, as
expected, and the second was magenta.

   The list below shows how I found Peter's bug.  Experienced C or C++
programmers will find all of this very familiar, and will really only
need to read item 6 of the list below, since that's the only action that
is really specific to Gri.  (Note: for display purposes, I've broken
some of the lines in the files into two lines in this list.)

  1. Copy the above script (called `test.gri') into the Gri source
     directory, and the script into an Emacs buffer.  Note: all the
     following steps are done within Emacs, and the items in
     parentheses are the Emacs keys to get the indicated actions.

  2. If you're working from a pre-compiled version, you'll need to get
     the source first and do a compile yourself (*Note Uncompiled
     Unix::).  Then do a `make tags' command (type this to the unix
     shell) to create a so-called "tag" table.

  3. Run Gri in this emacs buffer (`C-cC-r') noting from the postscript
     window that pops up that the colors are, indeed, mixed up.

  4. Load up the `gdb' debugger by typing `M-x gdb gri'.  This will
     open a new Emacs buffer in which you may type commands.  We'll be
     switching back and forth between this buffer and various source
     files.

  5. Reasoning that the error probably occurs at `set color' or `draw
     box', try replacing the latter by a command such as `draw label
     "hi" at 3 3 cm"'.  The color is still wrong, indicating that it is
     the `set color' command that has the problem.

  6. Next, we must find where the C++ code corresponding to the `set
     color' command resides.  As it turns out, all `set' commands are
     defined in the source file `set.cc', and this command is defined
     in a subroutine called `set_colorCmd()'.  But the author knows
     this - how would you?  The answer is to look in the `gri.cmd'
     file, for the `set color' command.  (Search for the string ``set
     color '.) Then read down to see the body of the command, enclosed
     in braces; you'll see

          {
              extern "C" bool set_colorCmd(void);
          }

     which indicates that the subroutine name is `set_colorCmd()'.

  7. Next we need to edit this subroutine to see what it is doing.
     There are several ways to find it (e.g. `grep' through the source
     files), but the easiest is to use the "tags" feature of Emacs, by
     typing `M-. set_colorCmd'.  This will bring you to the indicated
     subroutine.

  8. Have a look through this subroutine to see what it is doing.  It
     looks very much like many other Gri subroutines.  A check is done
     on the number of words provided to the command, in the

          	switch (_nword) {

     line.  (That's line `set.cc:484' at the moment - but it may be
     different by the time you read this file, if I've changed it!)  We
     are calling it with 6 words (`set color hsb 1.000 1 1'), so move
     down to the line

          	case 6:

     and you'll see that there is an `if' statement seeing whether this
     word is `rgb' or `hsv'.  These statements are checking `_word[2]',
     which is the third word of the command.  (In Gri, as in C, words
     start at zero.  Thus, for this command, `_word[0]' is `set',
     `_word[1]' is `color', and `_word[2]' is expected to be either
     `rgb' or `hsb'.  We are having problems with the `hsb' style, so
     we'll move down to that code.  The code that's being executed is
     as follows.

          } else if (!strcmp(_word[2], "hsb")) {
                  // `set color hsb .hue. .saturation. .brightness.'
                  double          hue, saturation, brightness;
                  Require(getdnum(_word[3], &hue),
                          READ_WORD_ERROR(".hue."));
                  Require(getdnum(_word[4], &saturation),
                          READ_WORD_ERROR(".saturation."));
                  Require(getdnum(_word[5], &brightness),
                          READ_WORD_ERROR(".brightness."));
                  // Clip if necessary
                  CHECK_HSB_RANGE(hue);
                  CHECK_HSB_RANGE(saturation);
                  CHECK_HSB_RANGE(brightness);
                  gr_hsv2rgb(hue, saturation, brightness,
                          &red, &green, &blue);
                  PUT_VAR("..red..", red);
                  PUT_VAR("..green..", green);
                  PUT_VAR("..blue..", blue);
                  c.setHSV(hue, saturation, brightness);
                  _griState.set_color_line(c);
                  if (_griState.separate_text_color() == false)
                          _griState.set_color_text(c);
                  return true;

     The `Require' lines are ensuring that we could decode the values of
     the variables `hue', etc, from the commandline.  Then we clip the
     range of these values.  Then we convert from `hsb' color format to
     `rgb' color format, save the values of the colors in Gri variables
     with `PUT_VAR', and then set the color with `c.setHSV'.  Finally
     we save this color in the Gri "state" with
     `_griState.set_color_line(c)'.

     As it turns out, Gri outputs all colors to the PostScript file in
     RGB format, so the we may well suspect that the problem is in the
     `gr_hsv2rgb()' line.

  9. We have an idea where to look now, so let's go to the line just
     after it, in the editor, and insert a "breakpoint" there by typing
     `C-x SPC'.  Then move to the `gdb' buffer and re-run Gri by typing

          run -directory . test.gri

     to run Gri on our script.  Then, magic happens!  Gri stops at the
     indicated breakpoint, and Emacs will display both the `gdb' buffer
     and the `set.cc' buffer.  The latter has a margin indication
     telling what line were are on.  You may now type `gdb' commands in
     the `gdb' buffer.  In particular, type

          p hue

     to print the hue.  Then type

          p red

     to see the red value.  Then type

          c

     to continue running Gri.  It will pause again.  Check the hue and
     red values again, as above.  If you like, play around with hue
     value in the Gri script `test.gri' and run gri again (type `r' in
     `gdb').  This seems to indicate that the conversion is working
     strangely.

 10. To see how the conversion is done, clear the breakpoints by typing
     `delete' in the `gdb' buffer, then insert a breakpoint *before*
     `gr_hsv2rgb' is called.  Then, run Gri again (`r' in the `gdb'
     buffer).  When it stops just before this subroutine, type `s' to
     "step into" the subroutine.  Then you'll see a conversion code
     from the (wonderful) textbook of Foley and Van Dam.  You'll see

          void
          gr_hsv2rgb(double h, double s, double v,
                     double *r, double *g, double *b)
          {
          	h = 6.0 * pin0_1(h);
          	s = pin0_1(s);
          	v = pin0_1(v);
          	int i = (int) floor(h);
          	if (i > 5)
          		i = 5; // Prevent problem if hue is exactly 1
          	double f = h - i;
          	double p = v * (1.0 - s);
                  ...

     in the present version of Gri, but in the previous (buggy)
     version, the `if' statement was missing.  Without this `if'
     statement, Gri produced wrong colors.  With the statement, the
     colors are correct.
        And so ends the example.  You may wish to read the Foley and
Van Dam textbook to see just what I'm doing in `gr_hsv2rgb', but
suffice it to say that the problem in the (older) version of Gri was
that `i' could take the value 6 if the hue was exactly equal to 1, and
that was erroneous.

   In reading the code, you may notice that it is formatted in a uniform
way: the Kernighan and Ritchie scheme (from their classic C textbook),
with 8-character indents.  I get this by putting the following lines in
the `~/.emacs' file, which is used to customize the Emacs editor:

     (defun my-c-mode-common-hook ()
       (c-set-style "K&R")
       (setq c-basic-offset 8)
       )
     (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)

   If you submit patches, please use the same format as I've done, so
that I can more easily see the changes you've made.


File: gri.info,  Node: Test Suite,  Next: Gri in the Press,  Prev: Debugging Example,  Up: Top

16 Test Suite
*************

The following test files are invoked by typing `make test', after
compiling Gri.  They are provided here because they are examples of
scripts that are *known to work* for the version of Gri described in
this manual.

   Heavy use is made of the `assert' command (*Note Assert::) in these
test files.  Thus the *code itself* demonstrates the features, instead
of comments in the code.  This is advantageous since comments tend to
be incorrect!


File: gri.info,  Node: Gri in the Press,  Next: Acknowledgments,  Prev: Test Suite,  Up: Top

17 Gri in the Press
*******************

A gentle introduction to Gri is provided in a Linux Journal article,
available at `http://www2.linuxjournal.com/lj-issues/issue75/3743.html'
on the web.

   In March 2000, I emailed some Gri users to ask for the names of
scientific journals in which they have published Gri-produced graphs.
The list, which mainly arrived on Sunday in response to an email I sent
Saturday (don't Gri users take a break?) is presented below, to
indicate the range of Gri use in the press.

   Journals in Oceanography, Atmospheric Science, Earth Science, etc.
   * *Bulletin on Coastal Oceanography* (in Japanese with English
     abstract)

   * *Fisheries Oceanography*

   * *Deep-Sea Research*

   * *EOS, Transactions of the American Geophysical Union*

   * *Estuarine, Coastal and Shelf Science*

   * *Geophysical Research Letters*

   * *Journal of Atmospheric and Oceanic Technology*

   * *Journal of Geophysical Research*

   * *Journal of Marine Research*

   * *Journal of Plankton Research*

   * *Journal of Physical Oceanography*

   * *Journal of the Japan Scoiety for Marine Surveys and Technology*
     (in Japanese with English abstract)

   * *Limnology and Oceanography*

   * *Marine Biology*

   * *Marine Ecology Progress Series*

   * *Monthly Weather Review*

   * *Oceanography*

   * *Paleoceanography*

   * *Progress in Oceanography*

   * *Quaternary Research*

   * *Scientia Marina*

   * *South African Journal of Marine Science*

   * *Umi no Kenkyu* (Japanese version for Journal of Oceanography, in
     Japanese with English abstract)

   Journals in Physics, Chemistry, etc.
   * *Applied Physics A*

   * *Journal of Fluid Mechanics*

   * *Journal of Physical Chemistry B*

   * *Physica D*

   * *Physics of Fluids*

   * *Physics A*

   * *Physics Letters B*

   * *Physical Review C*

   * *Physical Review Letters*

   * *Research on Chemical Intermediates*

   * *Theoretical Computational Fluid Dynamics*

   Other Journals
   * *Nature*

   Books, Monographs, etc.
   * *The Atlas of Hawai'i* (University of Hawai'i Press)

   * *Differential Equations with Applications to Biology* (American
     Mathematical Society)

   * *Ocean Drilling Program* publications


File: gri.info,  Node: Acknowledgments,  Next: License,  Prev: Gri in the Press,  Up: Top

18 Acknowledgments
******************

Over the years, many Gri users have been kind enough to help in its
development. Some have done so by sending in bug reports, others by
requesting features, others by submitting patches.  A few of their
names are: Ivo Alxneit, Karin Bryan, Sara Bennett, Luke Blaikie, Dave
Brickman, Steve Cayford, Clyde Clements, Andrew Collier, Pierre Flament, Peter
Galbraith, Dave Hebert, Christopher Illies, Cody Kirkpatrick, Thomas
Larsen, Alejandro López-Valencia, Kawamura Masao, Steve Matheson, Brian
May, Ed Nather, Roman Neuhauser, Carl Osterwisch, Richard Andrew Miles
Outerbridge, Tim Powers, Jinyu Sheng, Toru Suzuki, Keith Thompson, David
Trueman, Wolfgang Voegeli, Jeff Whitaker, and George White.  

   Prime among these is Peter Galbraith, who has been a close
collaborator in Gri development and in my scientific work, for well
over a decade.

   To all, thanks.


File: gri.info,  Node: License,  Next: Concept Index,  Prev: Acknowledgments,  Up: Top

19 License
**********

Gri is distributed under the GPL public license, an Open Source license
that provides certain rights and freedom to users, notably the access
to source code and the right to modify it and/or redistribute it.  The
full text of the GPL license is given below.

     		    GNU GENERAL PUBLIC LICENSE
     		       Version 2, June 1991

      Copyright (C) 1989, 1991 Free Software
          Foundation, Inc.  59 Temple Place, Suite
          330, Boston, MA 02111-1307 USA

      Everyone is permitted to copy and distribute
      verbatim copies of this license document, but
      changing it is not allowed.

     			    Preamble

       The licenses for most software are designed to
     take away your freedom to share and change it.
     By contrast, the GNU General Public License is
     intended to guarantee your freedom to share and
     change free software--to make sure the software
     is free for all its users.  This General Public
     License applies to most of the Free Software
     Foundation's software and to any other program
     whose authors commit to using it.  (Some other
     Free Software Foundation software is covered by
     the GNU Library General Public License instead.)
     You can apply it to your programs, too.

       When we speak of free software, we are
     referring to freedom, not price.  Our General
     Public Licenses are designed to make sure that
     you have the freedom to distribute copies of free
     software (and charge for this service if you
     wish), that you receive source code or can get it
     if you want it, that you can change the software
     or use pieces of it in new free programs; and
     that you know you can do these things.

       To protect your rights, we need to make
     restrictions that forbid anyone to deny you these
     rights or to ask you to surrender the rights.
     These restrictions translate to certain
     responsibilities for you if you distribute copies
     of the software, or if you modify it.

       For example, if you distribute copies of such a
     program, whether gratis or for a fee, you must
     give the recipients all the rights that you have.
     You must make sure that they, too, receive or can
     get the source code.  And you must show them
     these terms so they know their rights.

       We protect your rights with two steps: (1)
     copyright the software, and (2) offer you this
     license which gives you legal permission to copy,
     distribute and/or modify the software.

       Also, for each author's protection and ours, we
     want to make certain that everyone understands
     that there is no warranty for this free software.
     If the software is modified by someone else and
     passed on, we want its recipients to know that
     what they have is not the original, so that any
     problems introduced by others will not reflect on
     the original authors' reputations.

       Finally, any free program is threatened
     constantly by software patents.  We wish to avoid
     the danger that redistributors of a free program
     will individually obtain patent licenses, in
     effect making the program proprietary.  To
     prevent this, we have made it clear that any
     patent must be licensed for everyone's free use
     or not licensed at all.

       The precise terms and conditions for copying,
     distribution and modification follow.

     		    GNU GENERAL PUBLIC LICENSE

        TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION
        AND MODIFICATION

       0. This License applies to any program or other
     work which contains a notice placed by the
     copyright holder saying it may be distributed
     under the terms of this General Public License.
     The "Program", below, refers to any such program
     or work, and a "work based on the Program" means
     either the Program or any derivative work under
     copyright law: that is to say, a work containing
     the Program or a portion of it, either verbatim
     or with modifications and/or translated into
     another language.  (Hereinafter, translation is
     included without limitation in the term
     "modification".)  Each licensee is addressed as
     "you".

     Activities other than copying, distribution and
     modification are not covered by this License;
     they are outside its scope.  The act of running
     the Program is not restricted, and the output
     from the Program is covered only if its contents
     constitute a work based on the Program
     (independent of having been made by running the
     Program).  Whether that is true depends on what
     the Program does.

       1. You may copy and distribute verbatim copies
     of the Program's source code as you receive it,
     in any medium, provided that you conspicuously
     and appropriately publish on each copy an
     appropriate copyright notice and disclaimer of
     warranty; keep intact all the notices that refer
     to this License and to the absence of any
     warranty; and give any other recipients of the
     Program a copy of this License along with the
     Program.

     You may charge a fee for the physical act of
     transferring a copy, and you may at your option
     offer warranty protection in exchange for a fee.

       2. You may modify your copy or copies of the
     Program or any portion of it, thus forming a work
     based on the Program, and copy and distribute
     such modifications or work under the terms of
     Section 1 above, provided that you also meet all
     of these conditions:

         a) You must cause the modified files to carry
         prominent notices stating that you changed
         the files and the date of any change.

         b) You must cause any work that you
         distribute or publish, that in whole or in
         part contains or is derived from the Program
         or any part thereof, to be licensed as a
         whole at no charge to all third parties under
         the terms of this License.

         c) If the modified program normally reads
         commands interactively when run, you must
         cause it, when started running for such
         interactive use in the most ordinary way, to
         print or display an announcement including an
         appropriate copyright notice and a notice
         that there is no warranty (or else, saying
         that you provide a warranty) and that users
         may redistribute the program under these
         conditions, and telling the user how to view
         a copy of this License.  (Exception: if the
         Program itself is interactive but does not
         normally print such an announcement, your
         work based on the Program is not required to
         print an announcement.)

     These requirements apply to the modified work as
     a whole.  If identifiable sections of that work
     are not derived from the Program, and can be
     reasonably considered independent and separate
     works in themselves, then this License, and its
     terms, do not apply to those sections when you
     distribute them as separate works.  But when you
     distribute the same sections as part of a whole
     which is a work based on the Program, the
     distribution of the whole must be on the terms of
     this License, whose permissions for other
     licensees extend to the entire whole, and thus to
     each and every part regardless of who wrote it.

     Thus, it is not the intent of this section to
     claim rights or contest your rights to work
     written entirely by you; rather, the intent is to
     exercise the right to control the distribution of
     derivative or collective works based on the
     Program.

     In addition, mere aggregation of another work not
     based on the Program with the Program (or with a
     work based on the Program) on a volume of a
     storage or distribution medium does not bring the
     other work under the scope of this License.

       3. You may copy and distribute the Program (or
     a work based on it, under Section 2) in object
     code or executable form under the terms of
     Sections 1 and 2 above provided that you also do
     one of the following:

         a) Accompany it with the complete
         corresponding machine-readable source code,
         which must be distributed under the terms of
         Sections 1 and 2 above on a medium
         customarily used for software interchange;
         or,

         b) Accompany it with a written offer, valid
         for at least three years, to give any third
         party, for a charge no more than your cost of
         physically performing source distribution, a
         complete machine-readable copy of the
         corresponding source code, to be distributed
         under the terms of Sections 1 and 2 above on
         a medium customarily used for software
         interchange; or,

         c) Accompany it with the information you
         received as to the offer to distribute
         corresponding source code.  (This alternative
         is allowed only for noncommercial
         distribution and only if you received the
         program in object code or executable form
         with such an offer, in accord with Subsection
         b above.)

     The source code for a work means the preferred
     form of the work for making modifications to it.
     For an executable work, complete source code
     means all the source code for all modules it
     contains, plus any associated interface
     definition files, plus the scripts used to
     control compilation and installation of the
     executable.  However, as a special exception, the
     source code distributed need not include anything
     that is normally distributed (in either source or
     binary form) with the major components (compiler,
     kernel, and so on) of the operating system on
     which the executable runs, unless that component
     itself accompanies the executable.

     If distribution of executable or object code is
     made by offering access to copy from a designated
     place, then offering equivalent access to copy
     the source code from the same place counts as
     distribution of the source code, even though
     third parties are not compelled to copy the
     source along with the object code.

       4. You may not copy, modify, sublicense, or
     distribute the Program except as expressly
     provided under this License.  Any attempt
     otherwise to copy, modify, sublicense or
     distribute the Program is void, and will
     automatically terminate your rights under this
     License.  However, parties who have received
     copies, or rights, from you under this License
     will not have their licenses terminated so long
     as such parties remain in full compliance.

       5. You are not required to accept this License,
     since you have not signed it.  However, nothing
     else grants you permission to modify or
     distribute the Program or its derivative works.
     These actions are prohibited by law if you do not
     accept this License.  Therefore, by modifying or
     distributing the Program (or any work based on
     the Program), you indicate your acceptance of
     this License to do so, and all its terms and
     conditions for copying, distributing or modifying
     the Program or works based on it.

       6. Each time you redistribute the Program (or
     any work based on the Program), the recipient
     automatically receives a license from the
     original licensor to copy, distribute or modify
     the Program subject to these terms and
     conditions.  You may not impose any further
     restrictions on the recipients' exercise of the
     rights granted herein.  You are not responsible
     for enforcing compliance by third parties to this
     License.

       7. If, as a consequence of a court judgment or
     allegation of patent infringement or for any
     other reason (not limited to patent issues),
     conditions are imposed on you (whether by court
     order, agreement or otherwise) that contradict
     the conditions of this License, they do not
     excuse you from the conditions of this License.
     If you cannot distribute so as to satisfy
     simultaneously your obligations under this
     License and any other pertinent obligations, then
     as a consequence you may not distribute the
     Program at all.  For example, if a patent license
     would not permit royalty-free redistribution of
     the Program by all those who receive copies
     directly or indirectly through you, then the only
     way you could satisfy both it and this License
     would be to refrain entirely from distribution of
     the Program.

     If any portion of this section is held invalid or
     unenforceable under any particular circumstance,
     the balance of the section is intended to apply
     and the section as a whole is intended to apply
     in other circumstances.

     It is not the purpose of this section to induce
     you to infringe any patents or other property
     right claims or to contest validity of any such
     claims; this section has the sole purpose of
     protecting the integrity of the free software
     distribution system, which is implemented by
     public license practices.  Many people have made
     generous contributions to the wide range of
     software distributed through that system in
     reliance on consistent application of that
     system; it is up to the author/donor to decide if
     he or she is willing to distribute software
     through any other system and a licensee cannot
     impose that choice.

     This section is intended to make thoroughly clear
     what is believed to be a consequence of the rest
     of this License.

       8. If the distribution and/or use of the
     Program is restricted in certain countries either
     by patents or by copyrighted interfaces, the
     original copyright holder who places the Program
     under this License may add an explicit
     geographical distribution limitation excluding
     those countries, so that distribution is
     permitted only in or among countries not thus
     excluded.  In such case, this License
     incorporates the limitation as if written in the
     body of this License.

       9. The Free Software Foundation may publish
     revised and/or new versions of the General Public
     License from time to time.  Such new versions
     will be similar in spirit to the present version,
     but may differ in detail to address new problems
     or concerns.

     Each version is given a distinguishing version
     number.  If the Program specifies a version
     number of this License which applies to it and
     "any later version", you have the option of
     following the terms and conditions either of that
     version or of any later version published by the
     Free Software Foundation.  If the Program does
     not specify a version number of this License, you
     may choose any version ever published by the Free
     Software Foundation.

       10. If you wish to incorporate parts of the
     Program into other free programs whose
     distribution conditions are different, write to
     the author to ask for permission.  For software
     which is copyrighted by the Free Software
     Foundation, write to the Free Software
     Foundation; we sometimes make exceptions for
     this.  Our decision will be guided by the two
     goals of preserving the free status of all
     derivatives of our free software and of promoting
     the sharing and reuse of software generally.

     			    NO WARRANTY

       11. BECAUSE THE PROGRAM IS LICENSED FREE OF
     CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO
     THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT
     WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM
     "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
     EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED
     TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE
     RISK AS TO THE QUALITY AND PERFORMANCE OF THE
     PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE
     DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
     SERVICING, REPAIR OR CORRECTION.

       12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE
     LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT
     HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
     REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL,
     SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
     ARISING OUT OF THE USE OR INABILITY TO USE THE
     PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
     SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
     THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
     EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

     		     END OF TERMS AND CONDITIONS

     	    How to Apply These Terms to Your New
     	    Programs

       If you develop a new program, and you want it
     to be of the greatest possible use to the public,
     the best way to achieve this is to make it free
     software which everyone can redistribute and
     change under these terms.

       To do so, attach the following notices to the
     program.  It is safest to attach them to the
     start of each source file to most effectively
     convey the exclusion of warranty; and each file
     should have at least the "copyright" line and a
     pointer to where the full notice is found.

         <one line to give the program's name and a
         brief idea of what it does.> Copyright (C)
         yyyy <name of author>

         This program is free software; you can
         redistribute it and/or modify it under the
         terms of the GNU General Public License as
         published by the Free Software Foundation;
         either version 2 of the License, or (at your
         option) any later version.

         This program is distributed in the hope that
         it will be useful, but WITHOUT ANY WARRANTY;
         without even the implied warranty of
         MERCHANTABILITY or FITNESS FOR A PARTICULAR
         PURPOSE.  See the GNU General Public License
         for more details.

         You should have received a copy of the GNU
         General Public License along with this
         program; if not, write to the Free Software
         Foundation, Inc., 59 Temple Place, Suite 330,
         Boston, MA 02111-1307 USA


     Also add information on how to contact you by
     electronic and paper mail.

     If the program is interactive, make it output a
     short notice like this when it starts in an
     interactive mode:

         Gnomovision version 69, Copyright (C) yyyy
         name of author Gnomovision comes with
         ABSOLUTELY NO WARRANTY; for details type
         `show w'.  This is free software, and you are
         welcome to redistribute it under certain
         conditions; type `show c' for details.

     The hypothetical commands `show w' and `show c'
     should show the appropriate parts of the General
     Public License.  Of course, the commands you use
     may be called something other than `show w' and
     `show c'; they could even be mouse-clicks or menu
     items--whatever suits your program.

     You should also get your employer (if you work as
     a programmer) or your school, if any, to sign a
     "copyright disclaimer" for the program, if
     necessary.  Here is a sample; alter the names:

       Yoyodyne, Inc., hereby disclaims all copyright
       interest in the program `Gnomovision' (which
       makes passes at compilers) written by James
       Hacker.

       <signature of Ty Coon>, 1 April 1989
       Ty Coon, President of Vice

     This General Public License does not permit
     incorporating your program into proprietary
     programs.  If your program is a subroutine
     library, you may consider it more useful to
     permit linking proprietary applications with the
     library.  If this is what you want to do, use the
     GNU Library General Public License instead of
     this License.

