Gri: running

Running Gri 1: Introduction 2: Simple example 3: Fancy example 4: Running Gri 5: Programming Gri 6: General Issues 7: X-Y Plots 8: Contour Plots 9: Image Plots 10: Examples 11: Handling Data 12: Gri Commands 13: Gri Extras 14: Evolution of Gri 15: Installing Gri 16: Gri Bugs 17: System Tools 18: Acknowledgments 19: License 20: Newsgroup 21: Concept Index | # 4: Running Gri and Viewing and Printing Output This chapter tells how to run Gri, and how to view and print Gri output. Launching: Running Gri (short) Options On Command Line: Various options Viewing: Viewing the PostScript output Printing: Printing the PostScript output ## 4.1: Launching Gri If you specify a commandfile when you launch Gri, you will be using it noninteractively, and errors will cause Gri to exit. Gri may be used interactively by launching it without naming a commandfile. When you strike carriage-return after a command, Gri will interpret your command and do the appropriate thing. Errors will give a message but leave you in Gri. Mostly, Gri is used interactively to get help on commands. For example, a user might type the following to learn about drawing labels (the boldface string gri: is a prompt typed by gri):
    gri
    gri - scientific graphic program (version 2.4.4)
     GPL Copyright 2000 by Dan E. Kelley.

     Type `help' to view list of commands, or
     type `show license' to view license.  View
     /usr/doc/gri-2.4.4/html/gri1.html or access `gri'
     INFO node for the online manual.

    gri:  help             # get help in general
    gri:  help draw        # get help on draw commands
    gri:  help draw label  # focus on relevant command
    gri:  quit             # get out of Gri
- ## 4.2: Options on command line Gri is normally used to draw things, but it may also be used to extract the commands which were used to create a given postscript file, or to repair a damaged postscript file. These forms of usage are explained below. To make Gri plot things:
      gri [OPTIONS] [CmdFiles [PSFile] [Answers]]
  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):
      [-directory pathname]
      [-directory_default]
      [-yes]
      [-batch]
      [-debug]
      [-warn_offpage]
      [-trace]
      [-publication]
      [-no_bounding_box]
      [-no_startup_message]
      [-chatty[N]]
      [-no_cmd_in_ps]
      [-s[uperuser][N]]
- and the optional ``Answers`' is a mechanism to provide answers to any ``query`' commands that Gri is instructed to do see Query. ``Answeres`' must consist of 2 or more words, separated by whitespace. The first word must be the single character ``:`'. The following words are supplied individually as answers to ``query`' commands, one word per ``query`' command. To get whitespace within one of these words, use quotes around it. Extra words, beyond the requirements of ``query`' commands, are ignored. If there are too few words, then ``query`' reverts to it's normal behaviour of requesting this input from the user at the keyboard. To make Gri extract the commands that created a PostScript file:
      `gri -creator PostScriptFile'
- See also ``-no_cmd_in_ps`'. To make Gri repair (make printable) a PostScript file created by a Gri job that failed midway through:
      `gri -repair bad.ps good.ps'
- NOTES: Typically Gri is run with a command-line like the following (in which Gri is told to do the commands in the file ``timeseries.gri`' and put the PostScript output in a file named ``timeseries.ps`'):
      gri timeseries.gri
- Gri returns an exit code of 0 if everything is OK. Here is a unix shellscript which uses Gri to create a PostScript file, and preview it using the ghostview postscript viewing command.
      #!/usr/bin/sh
      # Run gri, then plot in X window
      case $# in
      1)
        gri -yes `basename $1 .gri`.gri
        ghostview `basename $1 .gri`.ps
       ;;
      *)
        echo "Proper usage: $0 cmdfile.gri"
        ;;
      esac
- Details of command-line options ``-yes`' or ``-y`' Bypasses all ``query`' commands, making Gri act as though the user typed a carriage-return (thus giving the default) for each ``query`'. ``-help`' or ``-h`' Prints explanation of options. ``-batch`' or ``-b`' Stops Gri from printing out prompts and hints. ``-no_bounding_box`' 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. ``-no_startup_message`' Stops Gri from printing startup message. ``-debug`' or ``-d`' Sets the built-in variable flag ``..debug..`' that you can use to isolate blocks of code. ``-warn_offpage`' Causes warnings to be issued for all items drawn far off a 8.5x11 inch page. ``-directory pathname`' 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 (normally ``/usr/share/gri/lib`') which was specified during the compilation of the Gri program itself. ``-directory_default`' Reports directory where ``gri.cmd`' is expected to be found, either in the default location or the one specified by ``-directory`' commandline option. ``-trace`' or ``-t`' Makes Gri print out command lines as they are executed; this has the same effect as the ``set trace`' command. ``-publication`' or ``-p`' Sets the built-in variable ``..publication..`' to 1. You may use this to distinguish between working plots and publication plots, as in this example:
      if !..publication..
        draw time stamp
        draw title "working version of plot"
      end if
``-no_startup_message`' Prevent Gri from printing startup message. It is not a good idea to use this option in general. ``-chatty[N]`' or ``-c[N]`' Make Gri print out various informative messages. The optional numerical value -- inserted with NO space -- 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: 0 The bare minimum is printed. Thus invoking Gri as ``gri -c0`'... 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. ``-no_cmd_in_ps`' 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.) ``-superuser`' or ``-s`' (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 ``-debug`'). An optional value can be inserted (e.g. -s2) 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 value.) For flag meanings, see ``superuser`' command see Superuser. ``-version`' or ``-v`' Display version information and exit successfully. ``CommandFile`' If a command file ``CommandFile`' is specified, then commands will be read from that file instead of the keyboard. If the ``chatty`' level is 1 or larger, Gri prints the names of the commandfiles at startup time. It's 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. Gri looks for commandfiles in the local directory. ``PostscriptFile`' If a command file is specified, then an additional file, ``PostScriptfile`', can be specified as the file in which to store the PostScript description of the plot. If no PostScript filename is given, Gri will make up a filename from the CommandFile name, by first removing a trailing ``".gri"`' if it exists, and then appending ``".ps"`'; thus ``gri foo.gri`' creates a PostScript file named ``foo.ps`'. If there are multiple commandfiles separated by commas, Gri forms the name of the PostScript file based on the last commandfile; thus ``gri foo,bar`' creates ``bar.ps`'. NOTE: If you don't need to supply commandline options, you can put the following line as the first line in your Gri program
    #!/usr/bin/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.