/usr/share/doc/gri/html/InvokingGri.html is in gri-html-doc 2.12.23-9build2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Gri: running</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"></head>
<body bgcolor="#FFFFFF" text="#000000" link="#0000EE" vlink="#551A8B" alink="FF0000">
<!-- newfile InvokingGri.html "Gri: running" "Invoking Gri" -->
<!-- @node Invoking Gri, Getting More Control, Simple Example, Top -->
<a name="InvokingGri" ></a>
<img src="./resources/top_banner.gif" alt="navigation map" usemap="#navigate_top" border="0">
<table summary="top banner" border="0" cellspacing="0" cellpadding="0">
<tr>
<td width="150" valign="top">
<font size=-1>
<br>
Chapters:
<br>
<a href="Introduction.html">1: Introduction</a><br>
<a href="SimpleExample.html">2: Simple example</a><br>
<a href="InvokingGri.html">3: Invocation</a><br>
<a href="GettingMoreControl.html">4: Finer Control</a><br>
<a href="X-Y.html">5: X-Y Plots</a><br>
<a href="ContourPlots.html">6: Contour Plots</a><br>
<a href="Images.html">7: Image Plots</a><br>
<a href="Examples.html">8: Examples</a><br>
<a href="Commands.html">9: Gri Commands</a><br>
<a href="Programming.html">10: Programming</a><br>
<a href="Environment.html">11: Environment</a><br>
<a href="Emacs.html">12: Emacs Mode</a><br>
<a href="History.html">13: History</a><br>
<a href="Installation.html">14: Installation</a><br>
<a href="Bugs.html">15: Gri Bugs</a><br>
<a href="TestSuite.html">16: Test Suite</a><br>
<a href="GriInThePress.html">17: Gri in Press</a><br>
<a href="Acknowledgments.html">18: Acknowledgments</a><br>
<a href="License.html">19: License</a><br>
<br>
Indices:<br>
<a href="ConceptIndex.html"><i>Concepts</i></a><br>
<a href="CommandIndex.html"><i>Commands</i></a><br>
<a href="BuiltinIndex.html"><i>Variables</i></a><br>
</font>
<td width="500" valign="top">
<map name="navigate_top">
<area alt="index.html#Top" shape="rect" coords="5,2,218,24" href="index.html#Top">
<area alt="index.html#Top" shape="rect" coords="516,2,532,24" href="index.html#Top">
<area alt="Gri: simple example" shape="rect" coords="557,2,573,24" href="SimpleExample.html">
<area alt="Gri: getting more control" shape="rect" coords="581,2,599,24" href="GettingMoreControl.html">
</map>
<map name="navigate_bottom">
<area alt="index.html#Top" shape="rect" coords="5,2,218,24" href="index.html#Top">
<area alt="Gri: getting more control" shape="rect" coords="581,2,599,24" href="GettingMoreControl.html">
</map>
<h1>3: Invoking Gri</h1>
<h2>3.1: Invoking Gri in a nutshell</h2>
First, the short story. In 90 percent of cases, Gri is run as
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
gri myscript
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
where the file `<font color="#82140F"><samp>myscript.gri</samp></font>' holds a script (list of Gri
commands), and Gri will create a PostScript file called
`<font color="#82140F"><samp>myscript.ps</samp></font>' with the output.
<p>
Some folks like to give the `<font color="#82140F"><samp>.gri</samp></font>' suffix explicitly, so they
would invoke Gri as
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
gri myscript.gri
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
instead.
<p>
If you'd rather not have `<font color="#82140F"><samp>myscript.ps</samp></font>' as the PostScript output file
name (let's say you prefer `<font color="#82140F"><samp>graph1.ps</samp></font>') you'd do
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
gri -output graph1.ps myscript.gri
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
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.
<p>
<h2>3.2: Using Gri to draw things</h2>
To draw things, invoke Gri as
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
gri [OPTIONS] [CmdFile [optional_arguments]]
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
where the square brackets indicate that the enclosed items
are optional. The `<font color="#82140F"><code>OPTIONS</code></font>' item may consist of one
or more of the following (explained below):
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
[-batch]
[-b]
[-chatty N]
[-c N]
[-debug]
[-d]
[-directory_default]
[-directory pathname]
[-help]
[-h]
[-no_bounding_box]
[-no_cmd_in_ps]
[-no_startup_message]
[-output PS_file_name|SVG_file_name]
[-private]
[-no_private]
[-publication]
[-p]
[-superuser N]
[-trace]
[-t]
[-yes]
[-y]
[-version]
[-v]
[-warn_offpage]
[-no_warn_offpage]
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
Here, the optional `<font color="#82140F"><code>optional_arguments</code></font>' are a mechanism to
customize the action of the given Gri script from the commandline.
After Gri processes standard arguments (e.g. `<font color="#82140F"><code>-t</code></font>' 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 `<font color="82140F"><samp>argc</samp></font>' (see <a href="SolitaryOperators.html#SolitaryOperators">Solitary Operators</a>)
and `<font color="82140F"><samp>argv</samp></font>' (see <a href="UnaryOperators.html#UnaryOperators">Unary Operators</a>).
<p>
For a note on usage within the Emacs gri-mode, see see <a href="Emacs5.html#Filenameargumentswhenrunninggri">Filename arguments when running gri</a>.
<p>
<b>Details of command-line options</b>
<p>
<ul>
<p>
<li> `<font color="#82140F"><code>-batch</code></font>' or `<font color="#82140F"><code>-b</code></font>'
Stops Gri from printing out prompts and hints.
<p>
<li> `<font color="#82140F"><code>-chatty N</code></font>' or `<font color="#82140F"><code>-c N</code></font>'
Make Gri print out various informative messages. The numerical
value gives a level of chattiness. A value
of 1, the default if the `<font color="#82140F"><code>-chatty</code></font>' 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:
<p>
Information printed at various chatty levels:
<ul>
<p>
<li> <b>0</b>
The bare minimum is printed. Thus invoking Gri as `<font color="#82140F"><code>gri -c 0</code></font>'...
will make it as quiet as can be.
<p>
<li> <b>1 or higher</b> (the default)
The full filenames of the commandfiles are displayed at startup time.
<p>
`<font color="#82140F"><code>convert columns to grid</code></font>' 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.
<p>
`<font color="#82140F"><code>convert grid to image</code></font>' prints characteristics of image created,
including amount of image clipped.
<p>
`<font color="#82140F"><code>read grid data</code></font>' reports number of data values it could not read
(since they were nonnumeric).
<p>
`<font color="#82140F"><code>draw symbol</code></font>' reports number of data points not drawn because they
were missing or outside clip region (if one exists).
<p>
<li> <b>2 or higher</b>
`<font color="#82140F"><code>draw contour</code></font>' prints value of contour being drawn.
<p>
`<font color="#82140F"><code>open "...|"</code></font>' 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.
<p>
`<font color="#82140F"><code>show image</code></font>' reports histograms in intensity bands of 8 units,
instead of the default 16 units.
<p>
<li> <b>3 or higher</b>
`<font color="#82140F"><code>show image</code></font>' reports histograms in intensity bands of 4 units,
instead of the default 16 units.
<p>
</ul>
<p>
<li> `<font color="#82140F"><code>-debug</code></font>' or `<font color="#82140F"><code>-d</code></font>'
<!-- latex: \index{@code{..debug..}, for debugging (by normal users)} -->
Sets the built-in variable flag `<font color="#82140F"><code>..debug..</code></font>' that you can use to
isolate blocks of code.
<p>
<li> `<font color="#82140F"><code>-directory_default</code></font>'
Reports directory where `<font color="#82140F"><samp>gri.cmd</samp></font>' is expected to be found, either
in the default location or the one specified by `<font color="#82140F"><code>-directory</code></font>'
commandline option.
<p>
<li> `<font color="#82140F"><code>-directory pathname</code></font>'
Specifies the directory where Gri looks for the startup file
`<font color="#82140F"><samp>gri.cmd</samp></font>'. (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
`<font color="#82140F"><samp>gri.cmd</samp></font>' in a standard system directory (sometimes,
but not always,
`<font color="#82140F"><samp>/usr/local/share/gri/2.12.23</samp></font>') which was specified
during the compilation of the Gri program itself. For more on how Gri looks
for `<font color="#82140F"><samp>gri.cmd</samp></font>', see the subsection below.
<p>
<li> `<font color="#82140F"><code>-no_bounding_box</code></font>'
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
`<font color="#82140F"><code>epsfbox</code></font>' macro in `<font color="#82140F"><code>latex</code></font>' 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 `<font color="#82140F"><code>set bounding box</code></font>' command
(see <a href="Set.html#SetBoundingBox">Set Bounding Box</a>).
<p>
<li> `<font color="#82140F"><code>-no_cmd_in_ps</code></font>'
Prevent Gri from inserting the lines of the commandfile into the
PostScript file as comments. (These comments can be used by the
`<font color="#82140F"><code>-creator</code></font>' commandline option (see above), but they take up a little
bit of space and users might sometimes want to get rid of them.)
<p>
<li> `<font color="#82140F"><code>-no_warn_offpage</code></font>'
Do not warn if items are offpage. (Contrast this with `<font color="#82140F"><code>-warn_offpage</code></font>'.)
<p>
<li> `<font color="#82140F"><code>-output PS_file_name</code></font>'
Specify the PostScript filename. If this is not specified, the
PostScript filename is derived from the name of the commandfile
(e.g. `<font color="#82140F"><samp>mygraph.gri</samp></font>' produces `<font color="#82140F"><samp>mygraph.ps</samp></font>'), or, for
interactive use, it will have a name like `<font color="#82140F"><samp>gri-00.ps</samp></font>', or
`<font color="#82140F"><samp>gri-01.ps</samp></font>' if the former file exists, etc.
<p>
<li> `<font color="#82140F"><code>-output SVG_file_name</code></font>'
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 <a href="ReportingBugs.html#ReportingBugs">Reporting Bugs</a>. 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.
<p>
<li> `<font color="#82140F"><code>-no_startup_message</code></font>'
Stops Gri from printing the startup message.
<p>
<li> `<font color="#82140F"><code>-private</code></font>'
Prevents inserting any information about the user into the PostScript
file (see `<font color="#82140F"><code>-no_private</code></font>', next). As of version 2.12.10,
this privacy option is assumed by default.
<p>
<li> `<font color="#82140F"><code>-no_private</code></font>'
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
`<font color="#82140F"><code>-creator</code></font>' commandline argument. Until version 2.12.10,
the default was to include this information, but a change was
made out of privacy concerns.
<p>
<li> `<font color="#82140F"><code>-publication</code></font>' or `<font color="#82140F"><code>-p</code></font>'
Sets the built-in variable `<font color="#82140F"><code>..publication..</code></font>' to 1. You may use
this to distinguish between working plots and publication plots, as in
this example:
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
if !..publication..
draw time stamp
draw title "working version of plot"
end if
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
<li> `<font color="#82140F"><code>-superuser</code></font>'
<!-- latex: \index{@code{..superuser..}, for debugging (by developers)} -->
(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 `<font color="#82140F"><code>-superuser</code></font>' is set in addition to `<font color="#82140F"><code>-debug</code></font>').
An optional value can be inserted (e.g. `<font color="#82140F"><code>-superuser 2</code></font>') to set the
debugging level (retrievable by the function superuser()) to indicated
integer value. Specifying the `<font color="#82140F"><code>-superuser</code></font>' command-line option
sets the built-in variable `<font color="#82140F"><code>..superuser..</code></font>' to 1 or the specified
value.)
<p>
For flag meanings, see `<font color="82140F"><code>superuser</code></font>' command (see <a href="Superuser.html#Superuser">Superuser</a>).
Using the question-mark symbol `<font color="#82140F"><code>?</code></font>' instead of a flag number makes
Gri print out the list of flags.
<p>
<li> `<font color="#82140F"><code>-trace</code></font>' or `<font color="#82140F"><code>-t</code></font>'
Makes Gri print out command lines as they are executed; this has the
same effect as the `<font color="#82140F"><code>set trace</code></font>' command.
<p>
<li> `<font color="#82140F"><code>-version</code></font>' or `<font color="#82140F"><code>-v</code></font>'
Display version information and exit successfully.
<p>
<li> `<font color="#82140F"><code>-warn_offpage</code></font>'
Causes warnings to be issued for all items drawn far off a 8.5x11 inch
page. This is the default. (Contrast with `<font color="#82140F"><code>-no_warn_offpage</code></font>'.)
<p>
<li> `<font color="#82140F"><code>-yes</code></font>' or `<font color="#82140F"><code>-y</code></font>'
<!-- latex: \index{@code{..use_default_for_query..}, simulate @code{-yes} commandline flag} -->
Bypasses all `<font color="#82140F"><code>query</code></font>' commands, making Gri act as though the user
typed a carriage-return (thus giving the default) for each `<font color="#82140F"><code>query</code></font>'.
<p>
<li> `<font color="#82140F"><code>-help</code></font>' or `<font color="#82140F"><code>-h</code></font>'
Prints explanation of options.
<p>
<li> `<font color="#82140F"><code>CommandFile</code></font>'
If a command file `<font color="#82140F"><code>CommandFile</code></font>' is specified, then commands will
be read from that file instead of the keyboard. If the `<font color="#82140F"><code>chatty</code></font>'
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 `<font color="#82140F"><code>.gri</code></font>'. If the filename does end in `<font color="#82140F"><code>.gri</code></font>', you may
delete this suffix; Gri will assume it as implied.
<p>
</ul>
<p>
<b>Executable scripts.</b> If you don't need to supply commandline
options, you can put the following line as the first line in your Gri
program
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
#!/usr/bin/gri
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
(or point to wherever Gri is located on your machine), and
`<font color="#82140F"><code>chmod +x</code></font>' 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.
<p>
<b>How Gri locates the</b> `<font color="#82140F"><samp>gri.cmd</samp></font>' <b>file</b>.
In a normal installation, Gri finds the `<font color="#82140F"><samp>gri.cmd</samp></font>' 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
`<font color="#82140F"><samp>gri.cmd</samp></font>'.
<dl>
<p>
<dt> <i>Case 1</i>
<dd>If `<font color="#82140F"><code>-directory</code></font>' was given on the commandline used to invoke Gri
(e.g. `<font color="#82140F"><code>gri -directory /some/place mycommand_file.gri</code></font>'), then
Gri will use the `<font color="#82140F"><samp>gri.cmd</samp></font>' in the named directory. An error will
result if `<font color="#82140F"><samp>gri.cmd</samp></font>' is not found there.
<p>
<dt> <i>Case 2</i>
<dd>If `<font color="#82140F"><code>-directory</code></font>' was not given on the commandline, then
Gri looks for `<font color="#82140F"><samp>gri.cmd</samp></font>' in a location that was specified during
compilation. If `<font color="#82140F"><samp>gri.cmd</samp></font>' is found there, then it is used. If it
is not found, then Gri checks to see if an environment variable named
`<font color="#82140F"><code>GRI_DIRECTORY_LIBRARY</code></font>' is defined. If so, then Gri takes this to
be the name of a directory that contains the `<font color="#82140F"><samp>gri.cmd</samp></font>' file. If
`<font color="#82140F"><samp>gri.cmd</samp></font>' is not found there, an error results.
</dl>
<p>
<h2>3.3: Extracting commandfile from a PostScript file</h2>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
gri -creator PostScriptFile
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
<b>See also</b> `<font color="#82140F"><code>-no_cmd_in_ps</code></font>'.
<p>
The `<font color="#82140F"><code>-creator</code></font>' 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
`<font color="#82140F"><code>-no_private</code></font>' commandline argument.)
<p>
</table>
<img src="./resources/bottom_banner.gif" alt="navigation map" usemap="#navigate_bottom" border="0">
</body>
</html>
|