2: Simple example
4: Finer Control
5: X-Y Plots
6: Contour Plots
7: Image Plots
9: Gri Commands
12: Emacs Mode
15: Gri Bugs
16: Test Suite
17: Gri in Press
3: Invoking Gri
3.1: Invoking Gri in a nutshell
First, the short story. In 90 percent of cases, Gri is run as
where the file `myscript.gri' holds a script (list of Gri
commands), and Gri will create a PostScript file called
`myscript.ps' with the output.
Some folks like to give the `.gri' suffix explicitly, so they
would invoke Gri as
If you'd rather not have `myscript.ps' as the PostScript output file
name (let's say you prefer `graph1.ps') you'd do
gri -output graph1.ps myscript.gri
Few readers will need to know more than this. But, for the rest, the
table in the next section gives full details on all the optional
arguments that Gri can handle.
3.2: Using Gri to draw things
To draw things, invoke Gri as
gri [OPTIONS] [CmdFile [optional_arguments]]
where the square brackets indicate that the enclosed items
are optional. The `
OPTIONS' item may consist of one
or more of the following (explained below):
Here, the optional `
optional_arguments' are a mechanism to
customize the action of the given Gri script from the commandline.
After Gri processes standard arguments (e.g. `
-t' for tracing), it
puts the remaining commandline arguments into a list. This behavior is
borrowed from C and othe languages, so Gri borrows the name of the list
as well: it's called the "arg" list, and its elements are available with
the RPN operators named `argc' (see Solitary Operators)
and `argv' (see Unary Operators).
For a note on usage within the Emacs gri-mode, see see Filename arguments when running gri.
Details of command-line options
-batch' or `
Stops Gri from printing out prompts and hints.
-chatty N' or `
Make Gri print out various informative messages. The numerical
value gives a level of chattiness. A value
of 1, the default if the `
-chatty' code is not supplied, tells Gri to
keep you informed of some important things, like the success in gridding
data for contouring. Higher values make Gri tell you more:
Information printed at various chatty levels:
The bare minimum is printed. Thus invoking Gri as `
gri -c 0'...
will make it as quiet as can be.
- 1 or higher (the default)
The full filenames of the commandfiles are displayed at startup time.
convert columns to grid' prints percentage of grid filled, as well
as a suite of diagnostics, if you've let it calculate the region of
influence automatically. It also prints a warning of the time it
expects to take, before starting the calculation.
convert grid to image' prints characteristics of image created,
including amount of image clipped.
read grid data' reports number of data values it could not read
(since they were nonnumeric).
draw symbol' reports number of data points not drawn because they
were missing or outside clip region (if one exists).
- 2 or higher
draw contour' prints value of contour being drawn.
open "...|"' prints the command to be passed to the operating
system as well as the name of the temporary file being created; also
notifies user when the temporary file is destroyed.
show image' reports histograms in intensity bands of 8 units,
instead of the default 16 units.
- 3 or higher
show image' reports histograms in intensity bands of 4 units,
instead of the default 16 units.
-debug' or `
Sets the built-in variable flag `
..debug..' that you can use to
isolate blocks of code.
Reports directory where `gri.cmd' is expected to be found, either
in the default location or the one specified by `
Specifies the directory where Gri looks for the startup file
`gri.cmd'. (This file teaches Gri the standard commands; Gri will
report an error and die if it cannot find this file.) If this switch is
not provided -- and it is normally not -- then Gri looks for
`gri.cmd' in a standard system directory (sometimes,
but not always,
`/usr/local/share/gri/2.12.18') which was specified
during the compilation of the Gri program itself. For more on how Gri looks
for `gri.cmd', see the subsection below.
Make the so-called ``bounding box'' in the PostScript file be the full
page. The bounding box is used by some PostScript previewers to clip
the image to just the drawn parts of the page, and is used by the
epsfbox' macro in `
latex' to automatically determine the
geometry of the graph for inclusion in text. Normally the bounding box
is calculated automatically, to enclose all the items drawn on the page.
But the box may also be set with the `
set bounding box' command
(see Set Bounding Box).
Prevent Gri from inserting the lines of the commandfile into the
PostScript file as comments. (These comments can be used by the
-creator' commandline option (see above), but they take up a little
bit of space and users might sometimes want to get rid of them.)
Do not warn if items are offpage. (Contrast this with `
Specify the PostScript filename. If this is not specified, the
PostScript filename is derived from the name of the commandfile
(e.g. `mygraph.gri' produces `mygraph.ps'), or, for
interactive use, it will have a name like `gri-00.ps', or
`gri-01.ps' if the former file exists, etc.
Specify the SVG filename. This is a pre-feature, as of version 2.12.x,
meaning that SVG output is not working properly yet. If you specify an
SVG file name, you will see a long list of warnings. These are
debugging messages, and are not specific to your actual Gri script. For
example, you will see warnings about centring strings, even if you are
not centering any strings. This manual does not contain a list of
working features (or broken features) for SVG output; the idea is that a
discussion of such things be done using the bug-reporting system of the
Gri website see Reporting Bugs. In addition to bugs, the author is
interested in users' opinions on the scheme of the SVG, especially the
hieararchy of groupings of graphical elements. It is because such
things are being altered that this is designated a pre-feature.
Stops Gri from printing the startup message.
Prevents inserting any information about the user into the PostScript
file (see `
-no_private', next). As of version 2.12.10,
this privacy option is assumed by default.
Instructs Gri to include comments in the PostScript file that identify
the user, state the commandline arguments used in invoking Gri, and
that list all the commands that were executed. This information can
be recovered by calling Gri on the PostScript file, with the
-creator' commandline argument. Until version 2.12.10,
the default was to include this information, but a change was
made out of privacy concerns.
-publication' or `
Sets the built-in variable `
..publication..' to 1. You may use
this to distinguish between working plots and publication plots, as in
draw time stamp
draw title "working version of plot"
(This option is included here only for completeness. It should only be
used by developers (who will alter the code to print debugging
information if `
-superuser' is set in addition to `
An optional value can be inserted (e.g. `
-superuser 2') to set the
debugging level (retrievable by the function superuser()) to indicated
integer value. Specifying the `
-superuser' command-line option
sets the built-in variable `
..superuser..' to 1 or the specified
For flag meanings, see `
superuser' command (see Superuser).
Using the question-mark symbol `
?' instead of a flag number makes
Gri print out the list of flags.
-trace' or `
Makes Gri print out command lines as they are executed; this has the
same effect as the `
set trace' command.
-version' or `
Display version information and exit successfully.
Causes warnings to be issued for all items drawn far off a 8.5x11 inch
page. This is the default. (Contrast with `
-yes' or `
Bypasses all `
query' commands, making Gri act as though the user
typed a carriage-return (thus giving the default) for each `
-help' or `
Prints explanation of options.
If a command file `
CommandFile' is specified, then commands will
be read from that file instead of the keyboard. If the `
level is 1 or larger, Gri prints the names of the commandfiles at
startup time. It is conventional but not necessary that the filename
ends in `
.gri'. If the filename does end in `
.gri', you may
delete this suffix; Gri will assume it as implied.
Executable scripts. If you don't need to supply commandline
options, you can put the following line as the first line in your Gri
(or point to wherever Gri is located on your machine), and
chmod +x' the file. Then you can run Gri simply by naming the
file. There is no particular advantage in this, except for saving the
typing of a few characters, but some folks like this.
How Gri locates the `gri.cmd' file.
In a normal installation, Gri finds the `gri.cmd' file all by
itself. However, developers and some others may wish to control where
Gri looks for this file. The rules below specify how Gri looks for
- Case 1
- If `
-directory' was given on the commandline used to invoke Gri
gri -directory /some/place mycommand_file.gri'), then
Gri will use the `gri.cmd' in the named directory. An error will
result if `gri.cmd' is not found there.
- Case 2
- If `
-directory' was not given on the commandline, then
Gri looks for `gri.cmd' in a location that was specified during
compilation. If `gri.cmd' is found there, then it is used. If it
is not found, then Gri checks to see if an environment variable named
GRI_DIRECTORY_LIBRARY' is defined. If so, then Gri takes this to
be the name of a directory that contains the `gri.cmd' file. If
`gri.cmd' is not found there, an error results.
3.3: Extracting commandfile from a PostScript file
gri -creator PostScriptFile
See also `
-creator' flag makes gri examine the indicate PostScript file,
and produce a facsimile of the command file (or interactively-typed
commands) that created this PostScript file. (This only works if the
Gri command that created the PostScript file used the
-no_private' commandline argument.)