Debian Codegraph @

doc/FAQ.html

raw
1 <!--
2 UPDATE SourceForge site by the command:
3
4 scp FAQ.html [email protected]:/home/groups/g/gr/gri/htdocs/gridoc/html
5
6 -->
7
8
9 <html>
10 <head> <title>
11 Gri Frequently Asked Questions
12 </title>
13 <style type="text/css">
14 <!--
15 BODY { background-color: #FFFFFF }
16
17 A { text-decoration: none; color #6666DD; }
18 A:visited { text-decoration: none; color: #6666DD; }
19 A:link { text-decoration: none; color: #6666DD; }
20 A:active { text-decoration: none; color: #6666DD; }
21 A:hover { text-decoration: underline; color: #6666DD; }
22 A:mail { text-decoration: none; color: #6666DD; font-weight: bold }
23 OL,UL,P,BODY,TD,TR,TH,FORM,SPAN { font-family: arial,helvetica,sans-serif;color: #333333 }
24 H1,H2,H3,H4,H5,H6 { font-family: arial,helvetica,sans-serif }
25 CODE,PRE,TT { font-family: courier,sans-serif; color: #82140F; }
26
27 SPAN.center { text-align: center }
28 SPAN.boxspace { font-size: 2pt; }
29
30 A.maintitlebar { color: #FFFFFF; }
31 A.bottombar { color: #FFFFFF; text-decoration: none; }
32 A.sortbutton { color: #FFFFFF; text-decoration: none; }
33 A.menus { color: #6666DD; text-decoration: none; }
34 A.menus:hover { text-decoration: underline; }
35 A.tabs { color: #000000; text-decoration: none; }
36 A.date { color: #ff0000; text-decoration: none; }
37 SPAN.alignright { text-align: right }
38 SPAN.maintitlebar { font-size: 10pt; color: #FFFFFF; font-weight: bold }
39 SPAN.bottombar { font-size: 10pt; color: #FFFFFF; font-weight: bold }
40 SPAN.titlebar { text-align: center; font-size: 10pt; color: #FFFFFF; font-weight: bold }
41 TD.featurebox { font-size: small; }
42 TD.newsbox { font-size: 8pt; }
43 TD.menus { color: #000000; }
44 -->
45 </style>
46 </head>
47
48 <body bgcolor="#FFFFFF">
49
50 <h1> Introduction</h1>
51
52 This is the FAQ ("frequently asked questions") document for the Gri
53 scientific graphing language, (c) 1991-2003 Dan Kelley,
54 to whom you are asked to <A
55 HREF="mailto:[email protected]"> email</A> reports of Gri errors, or
56 suggestions for Gri improvements or new features.
57
58
59
60 <h1> The Questions</h1>
61
62 <h2> Q1 Features</h2>
63 <UL>
64 <LI>
65 <A NAME="Q1.1">Q1.1</A>
66 <A HREF="#A1.1">What is Gri?</A>
67 <LI>
68 <A NAME="Q1.2">Q1.2</A>
69 <A HREF="#A1.2">What does `Gri' stand for? How is it pronounced?</A>
70 <LI>
71 <A NAME="Q1.3">Q1.3</A>
72 <A HREF="#A1.3">What does Gri cost?</A>
73 <LI>
74 <A NAME="Q1.4">Q1.4</A>
75 <A HREF="#A1.4">How long will it take to learn Gri?</A>
76 </UL>
77
78
79 <h2> Q2 Documentation </h2>
80 <UL>
81 <LI>
82 <A NAME="Q2.1">Q2.1</A>
83 <A HREF="#A2.1">Is there a quick-reference card for Gri?</A>
84 <LI>
85 <A NAME="Q2.2">Q2.2</A>
86 <A HREF="#A2.2">Where can I get documentation for Gri?</A>
87 <LI>
88 <A NAME="Q2.3">Q2.3</A>
89 <A HREF="#A2.3">Is there a cookbook of Gri program to use for guidance?</A>
90 <LI>
91 <A NAME="Q2.4">Q2.4</A>
92 <A HREF="#A2.4">Is there a newsgroup for Gri?</A>
93 <LI>
94 <A NAME="Q2.5">Q2.5</A>
95 <A HREF="#A2.5">Where can I get some sample Gri input files?</A>
96 </UL>
97
98
99 <h2> Q3 Can Gri do ... ?</h2>
100 <UL>
101 <LI>
102 <A NAME="Q3.1">Q3.1</A>
103 <A HREF="#A3.1"> Can Gri do barcharts?</A>
104 <LI>
105 <A NAME="Q3.2">Q3.2</A>
106 <A HREF="#A3.2"> Can Gri do histograms?</A>
107 <LI>
108 <A NAME="Q3.3">Q3.3</A>
109 <A HREF="#A3.3"> Can Gri do error bars?</A>
110 <LI>
111 <A NAME="Q3.4">Q3.4</A>
112 <A HREF="#A3.4"> Can Gri draw labels for Tukey box plots?</A>
113 <LI>
114 <A NAME="Q3.5">Q3.5</A>
115 <A HREF="#A3.5"> Can Gri read compressed data files?</A>
116 <LI>
117 <A NAME="Q3.6">Q3.6</A>
118 <A HREF="#A3.6"> Can Gri use scientific notation on axes?</A>
119 <LI>
120 <A NAME="Q3.7">Q3.7</A>
121 <A HREF="#A3.7"> Can Gri label x-axis with day of week?</A>
122 <LI>
123 <A NAME="Q3.8">Q3.8</A>
124 <A HREF="#A3.8"> Can Gri draw maps?</A>
125 <LI>
126 <A NAME="Q3.9">Q3.9</A>
127 <A HREF="#A3.9"> Can Gri draw residuals on regressions?</A>
128
129 </UL>
130
131
132 <h2> Q4 Gri and other programs</h2>
133 <UL>
134 <LI>
135 <A NAME="Q4.1">Q4.1</A>
136 <A HREF="#A4.1">Is Gri better than Fortran/C/... plotting subroutines?</A>
137 <LI>
138 <A NAME="Q4.2">Q4.2</A>
139 <A HREF="#A4.2">How can I include Gri plots in LaTeX/word/... files?</A>
140 <LI>
141 <A NAME="Q4.3">Q4.3</A>
142 <A HREF="#A4.3">How may I convert Gri output to GIF format?</A>
143 <LI>
144 <A NAME="Q4.4">Q4.4</A>
145 <A HREF="#A4.4">Is there an Emacs mode for Gri?</A>
146 <LI>
147 <A NAME="Q4.5">Q4.5</A>
148 <A HREF="#A4.5">Is there a Gri module for perl/python/R/octave/...?</A>
149 </UL>
150
151
152 <h2> Q5 Evolution of Gri</h2>
153 <UL>
154 <LI>
155 <A NAME="Q5.1">Q5.1</A>
156 <A HREF="#A5.1">Where can I get the latest version of Gri?</A>
157 <LI>
158 <A NAME="Q5.2">Q5.2</A>
159 <A HREF="#A5.2">How can I find out the most recent features of Gri?</A>
160 <LI>
161 <A NAME="Q5.3">Q5.3</A>
162 <A HREF="#A5.3">Should I keep my copy of Gri up-to-date?</A>
163 <LI>
164 <A NAME="Q5.4">Q5.4</A>
165 <A HREF="#A5.4">How can I protect myself against changes to Gri?</A>
166 </UL>
167
168 <h2> Q6 Gri on various computers</h2>
169 <UL>
170 <LI>
171 <A NAME="Q6.1">Q6.1</A>
172 <A HREF="#A6.1">What computers does Gri work on?</A>
173 <LI>
174 <A NAME="Q6.2">Q6.2</A>
175 <A HREF="#A6.2">What kind of compiler is required to compile gri?</A>
176 <LI>
177 <A NAME="Q6.3">Q6.3</A>
178 <A HREF="#A6.3">Why can't I link my compiled gri? (on HP computer)</a>
179 <LI>
180 <A NAME="Q6.4">Q6.4</A>
181 <A HREF="#A6.4">Is there a Macintosh version of Gri?</A>
182 <LI>
183 <A NAME="Q6.5">Q6.5</A>
184 <A HREF="#A6.5">Is there a DOS/Windows version of Gri?</A>
185 <LI>
186 <A NAME="Q6.6">Q6.6</A>
187 <A HREF="#A6.6">Is there a linux version of Gri?</A>
188 </UL>
189
190
191 <h2> Q7 Gri bugs</h2>
192 <UL>
193 <LI>
194 <A NAME="Q7.1">Q7.1</A>
195 <A HREF="#A7.1"> What are known bugs in Gri?</A>
196 <LI>
197 <A NAME="Q7.2">Q7.2</A>
198 <A HREF="#A7.2"> How can I report Gri bugs?</A>
199 </UL>
200
201
202 <h1> The Answers</h1>
203
204 <hr>
205
206 <h2> A1 Features </h2>
207
208 <A NAME="A1.1"></A>
209 <A HREF="#Q1.1"><h3>A1.1 What is Gri?</h3></A>
210
211 <p> Gri is a program for drawing scientific graphs. It makes xy plots
212 (linegraphs and scattergraphs), contour plots, and image plots.
213 Unlike many scientific plotting packages, Gri provides precise control
214 over fonts, line widths, grayscales, colors, etc. Since Gri was
215 written by a scientist, it does the kinds of plots scientists want.
216 It has few frills; e.g., it does not do 3D mesh plots, because the
217 author dislikes them. Gri is command-driven, not mouse driven.
218
219 <p>
220 <A NAME="A1.2"></A>
221 <A HREF="#Q1.2"><h3>A1.2 What does `Gri' stand for? How is it pronounced?</h3></A>
222
223 <p> Gri stands for `<tt>gr-interactive</tt>', and `<tt>gr</tt>' is the
224 name of a subroutine library that preceded Gri. The `interactive'
225 adjective indicates that Gri can be used interactively -- that is, Gri
226 is an interpreted language whereas Gr is a compiled language. `Gri'
227 rhymes with `tree'.
228
229
230 <p>
231 <A NAME="A1.3"></A>
232 <A HREF="#Q1.3"><h3>A1.3 What does Gri cost?</h3></a>
233
234 <p> Gri is free. A commercial version, called <A
235 HREF="http://www.phys.ocean.dal.ca/~kelley/gre">Gre</A>
236 will be made available soon. It
237 contains most of Gri as a subset, but also contains quite a lot of the
238 <tt>Perl</tt> language as well, making it a fully functional and
239 efficient programming language.
240
241
242 <p>
243 <A NAME="A1.4"></A>
244 <A HREF="#Q1.4"><h3>A1.4 How long will it take to learn Gri?</h3></a>
245
246 <p> Most users can get Gri working after spending half an hour with
247 manual (see <a href="#Q2.1">Q2.1</a>). Familiarity with your
248 operating system (for example for viewing PostScript files) will speed
249 this somewhat. After that, it's best to learn new features only as
250 you come to need them. To begin with, you should skim the manual and
251 the cookbook (see <a href="#Q2.3">Q2.3</a>), looking just at the
252 illustrations. This will take no more than an hour.
253
254 <p> The Gri manual is like most computer manuals: it would be a waste
255 of time to read it cover to cover before starting to use Gri. But
256 you'll find the manual helpful as you branch out, modifying the
257 existing examples and inventing code of your own.
258
259 <p> Learning how to use a new command usually takes only a minute but
260 realizing that the command exists can take longer. That's why many
261 users with sophisticated needs find it useful to spend an afternoon
262 leafing through the entire manual at some point.
263
264 <p> Most things in Gri can be done elegantly or crudely. The elegant
265 approach may require a little investment in time at the beginning, but
266 this will pay off constantly as your needs grow. For example, folks
267 who like computer programming often start using Gri "newcommands" (a
268 form of subroutines) within a few days. Other folks might avoid
269 newcommands, instead putting their entire program in one long "main
270 routine". What's right for you depends on how you think and the sort
271 of work you do.
272
273
274
275
276 <hr>
277 <h2> A2 Documentation </h2>
278
279 <A NAME="A2.1"></A>
280 <A HREF="#Q2.1"><h3>A2.1 Is there a quick-reference card for Gri?</h3></A>
281
282 <p> Yes, two quick-reference cards are stored on the
283 Gri development site
284 <A HREF="http://gri.sourceforge.net">
285 <code>http://gri.sourceforge.net</code>,
286 </A>
287 and these are also installed when gri is installed.
288 <p>
289 <A NAME="A2.2"></A>
290 <A HREF="#Q2.2"><h3>A2.2 Where can I get documentation for Gri?</h3></A>
291
292 <p> Full documentation is available in several forms on the Gri
293 development site
294 Gri development site
295 <A HREF="http://gri.sourceforge.net">
296 <code>http://gri.sourceforge.net</code>,
297 </A>
298 Check out the FAQ file (which you are
299 reading now), reference cards (see previous answer), etc.
300
301 <P> The Gri manual is available on the WWW (world wide web) at the URL
302 <a href="http://gri.sourceforge.net/gridoc/html/index.html">
303 http://gri.sourceforge.net/gridoc/html/index.html
304 </A>.
305
306 <A NAME="A2.3"></A>
307 <A HREF="#Q2.3"><h3>A2.3 Is there a cookbook of Gri programs to use for guidance?</h3></A>
308
309 Yes, at the website
310 <A HREF="http://gri.sourceforge.net/gri-cookbook/index.html">
311 <code>
312 http://gri.sourceforge.net/gri-cookbook/index.html
313 </code>
314 </a>
315
316
317 <p>
318 <A NAME="A2.4"></A>
319 <A HREF="#Q2.4"><h3>A2.4 Is there a newsgroup for Gri?</h3></A>
320
321 <p> Gri has several discussion forums at the development site
322 <A HREF="http://gri.sourceforge.net">
323 <code>http://gri.sourceforge.net</code>,
324 </A> and users are highly encouraged to participate!
325
326
327 <p>
328 <A NAME="A2.5"></A>
329 <A HREF="#Q2.5"><h3>A2.5 Where can I get some sample Gri input files?</h3></A>
330
331 Sample files are scattered throughout the Gri manual and cookbook; the
332 manual also contains a test-suite that you may find helpful in
333 learning the language syntax, especially for programming.
334
335
336
337 <hr>
338 <h2> A3 Can Gri do ... ?</h2>
339 <A NAME="A3.1"></A>
340 <A HREF="#Q3.1"><h3>A3.1 Can Gri do barcharts?</h3></A>
341
342 <P> Gri has no specific command for barcharts, but the operating
343 system can easily rearrange your data into a form that lets Gri draw
344 barcharts. In the following example, the synonym <CODE>\width</CODE>
345 is set to the desired width of the bars and <CODE>\missing</CODE> is
346 set to an arbitrary missing value. The rest of the code will make
347 sense to any Perl programmer. If you don't know Perl, you should
348 learn it.
349
350 <pre>
351 \width = "1" // width of bars, in x units
352 \missing = "-99" // missing value
353 set missing value \missing
354 set x axis 0 6 1
355 set y axis 0 20 10
356 draw axes none // will get whited out by the chart anyway
357
358 // Create dataset
359 system cat &gt; barchart.dat &lt;&lt; "EOF"
360 1 12
361 2 14
362 3 15
363 4 13
364 5 10
365 EOF
366
367 // Create barchart style dataset and plot it
368 system perl &lt;&lt;"EOF"
369 open (IN, "barchart.dat") || die "Cannot open barchart.dat";
370 while(&lt;IN&gt;) {
371 ($x[$i], $y[$i]) = split(' ');
372 $i++;
373 }
374 $n = $i;
375 open (TMP, "&gt;tmp") || die "Cannot open tmp";
376 for ($i = 0; $i &lt; $n; $i++) {
377 print TMP $x[$i] - \width / 2, " ", 0, "\n";
378 print TMP $x[$i] - \width / 2, " ", $y[$i], "\n";
379 print TMP $x[$i] + \width / 2, " ", $y[$i], "\n";
380 print TMP $x[$i] + \width / 2, " ", 0, "\n";
381 print TMP \missing, " ", \missing, "\n";
382 }
383 EOF
384 open tmp
385 read columns x y
386 set graylevel 0.95
387 draw curve filled to 0 y
388 set graylevel 0
389 draw curve
390 draw axes
391 draw title "Demonstrate Gri barchart"
392
393 </pre>
394
395 <A NAME="A3.2"></A>
396 <A HREF="#Q3.2"><h3>A3.2 Can Gri do histograms?</h3></A>
397
398 <P> Gri has no specific command for histograms, but the operating
399 system can easily rearrange your data into a histogram format.
400
401 <P> Here is Gri code to do it:
402 <pre>
403 open "histogram -l 0 -h 10 -i 0.5 &lt inputfile |"
404 read columns x y // y is number of obs
405 draw curve filled to 0 y
406 </pre>
407
408 <P> where <code>histogram</code> is a perlscript which creates a
409 histogram file named <code>inputfile</code>. An example of histogram
410 is:
411
412 <pre>
413 #!/opt/bin/perl
414 # Calculate histogram of 1-column data
415 $usage ="\
416 NAME\
417 histogram -- create histogram file, given data file (1 column)\
418 \
419 SYNOPSIS\
420 histogram -l low -h high -i increment &lt input_file &gt output_file\
421 \
422 DESCRIPTION\
423 Scans the input values and finds the percentage of data in bins\
424 starting at value `low', ending at value `high', and incrementing by\
425 value `inc'.\
426 \
427 FILES\
428 Standard input: column of numbers\
429 Standard output: columns: (bin_centre, per, cum_per, num, cum_num)\
430 where 'per'=percentage and 'num'=number.\
431 ";
432 require "getopts.pl";
433 $opt_l = 0;
434 $opt_h = 0;
435 $opt_i = 0;
436 &Getopts('l:h:i:');
437 die "You must supply commandline arguments!\n$usage" if ($opt_l == $opt_h || $opt_i == 0);
438 $n = ($opt_h - $opt_l) / $opt_i;
439 print STDERR "Will have $n bins, running from $opt_l to $opt_h in steps of $opt_i\n";
440 for ($i = 0; $i &lt= $n; $i++) {
441 $bin[$i] = 0;
442 }
443 while(&lt&gt) {
444 chop;
445 ($x) = split;
446 $i = int(0.5 + ($x - $opt_l) / $opt_i);
447 $i = 0 if ($i &lt 0);
448 $i = $n if ($i &gt $n);
449 $bin[$i]++;
450 }
451 for ($i = 0; $i &lt= $n; $i++) {
452 $x = $opt_l + $opt_i * ($i - 0.5);
453 print "$x $bin[$i]\n";
454 $x = $opt_l + $opt_i * ($i + 0.5);
455 print "$x $bin[$i]\n";
456 }
457 </pre>
458
459
460 <p>
461 <A NAME="A3.3"></A>
462 <A HREF="#Q3.3"><h3>A3.3 Can Gri do error bars?</h3></A>
463
464 <P> Gri has no specific command for error bars. It has no internal
465 representation of error bar data -- that is, you can't get them by a
466 <code>read columns</code> command. However, you can get error bars
467 quite easily, simply by reading the data line by line, plotting each
468 one as individually. Here's an example of error bars in y, where the
469 third column stores the error:
470
471 <pre>
472 open a.dat
473 while 1
474 read .x. .y. .ey.
475 if ..eof..
476 break
477 end if
478 draw symbol bullet at .x. .y.
479 draw line from .x. {rpn .y. .ey. -} to .x. {rpn .y. .ey. +}
480 end while
481 </pre>
482
483
484 <A NAME="A3.4"></A>
485 <A HREF="#Q3.4"><h3>A3.4 Can Gri draw labels for Tukey box plots?</h3></A>
486
487 <P> Yes. Here is sample code, in which a label "My Label" is drawn to
488 the right of the median of a Tukey plot extending in the y direction:
489
490 <pre>
491 read columns x y
492 1 11
493 2 22
494 1.2 3
495 3 5
496 2 20
497 3 10
498
499 draw y box plot at 2
500 draw label "My Label" at {rpn 2 xusertocm 0.4 +} \
501 {rpn y median yusertocm "M" ascent 2 / -} \
502 cm
503 </pre>
504
505
506 <p>
507 <A NAME="A3.5"></A>
508 <A HREF="#Q3.5"><h3>A3.5 Can Gri read compressed data files?</h3></A>
509
510 <P> Yes, as of version 2.6 Gri can read compressed files, e.g.
511 <pre>
512 open myfile.gz
513 read columns x y
514 </pre>
515 will work. You may also, of course, do
516 <pre>
517 open "zcat myfile.gz |"
518 read columns x y
519 </pre>
520 if you like.
521
522
523 <p>
524 <A NAME="A3.6"></A>
525 <A HREF="#Q3.6"><h3>A3.6 Can Gri use scientific notation on axes?</h3></A>
526
527 <P> You have to trick it. Here's an example:
528 <pre>
529 // NOTE: this requires manual setting of axes.
530 read columns x y
531 1 1.1e3
532 2 1.0e3
533 3 1.4e3
534 4 2.3e3
535 4 1.0e4
536
537 y /= 1e3
538 set y axis 1 5 1
539 set y format "%g$\times10^3$"
540 draw curve
541 </pre>
542
543
544 <p>
545 <A NAME="A3.7"></A>
546 <A HREF="#Q3.7"><h3>A3.7 Can Gri label x-axis with day of week?</h3></A>
547
548 <P> A future version of Gri will have much more powerful and general
549 ways of handling axes labelling. In the meantime, you have to trick
550 Gri to get such special effects. Here's an example:
551
552 <pre>
553 set x axis 1 8 1
554 set y axis 0 1 .1
555 set font size 0
556 draw x axis at top
557 draw y axis at right
558 draw x axis at bottom
559 set font size 12
560 draw y axis at left
561 draw label "Mon" centered at 1.5 {rpn ..ymargin.. 0.7 - ycmtouser}
562 draw label "Tue" centered at 2.5 {rpn ..ymargin.. 0.7 - ycmtouser}
563 draw label "Wed" centered at 3.5 {rpn ..ymargin.. 0.7 - ycmtouser}
564 draw label "Thu" centered at 4.5 {rpn ..ymargin.. 0.7 - ycmtouser}
565 draw label "Fri" centered at 5.5 {rpn ..ymargin.. 0.7 - ycmtouser}
566 draw label "Sat" centered at 6.5 {rpn ..ymargin.. 0.7 - ycmtouser}
567 draw label "Sun" centered at 7.5 {rpn ..ymargin.. 0.7 - ycmtouser}
568 </pre>
569
570 Note that the offset of <code>0.7</code> centimeters looks OK to me,
571 with a 12 point font, but you may wish to experiment if you don't like
572 the placement.
573
574
575 <p>
576 <A NAME="A3.8"></A>
577 <A HREF="#Q3.8"><h3>A3.8 Can Gri draw maps?</h3></A>
578
579 <P> Gri can draw maps, but it lacks builtin support for map
580 projections. (A previous version had projections, but they were not
581 working correctly and were removed.) Gri does not have builtin
582 coastline files, either. Many good coastline files are on the web;
583 see, for example, Rich Signell's site
584 <A HREF="http://crusty.er.usgs.gov/coast/getcoast.html">
585 http://crusty.er.usgs.gov/coast/getcoast.html </A> or the USGS mapping
586 site <A HREF="http://www.usgs.gov"> http://www.usgs.gov </A> or the
587 Global Self-consistent Hierarchical High-resolution Shoreline site <A
588 HREF="http://www.ngdc.noaa.gov/mgg/shorelines/gshhs.html">
589 http://www.ngdc.noaa.gov/mgg/shorelines/gshhs.html </A>
590
591 <p>
592 <A NAME="A3.9"></A>
593 <A HREF="#Q3.9"><h3>A3.9 Can Gri draw residuals on regressions?</h3></A>
594 <p>There is no builtin command for that, but it's easy enough to
595 code, as follows:</p>
596 <pre>
597 read columns x y
598 0.05 12.5
599 0.25 19
600 0.5 15
601 0.75 15
602 0.95 13
603
604 draw regression line
605 # Draw the residuals individually
606 .i. = 0
607 while {rpn .i. ..num_col_data.. >}
608 .x. = {rpn x .i. @}
609 .y. = {rpn y .i. @}
610 .ypred. = {rpn .x. ..coeff1.. * ..coeff0.. +}
611 draw line from .x. .y. to .x. .ypred.
612 .i. += 1
613 end while
614 </pre>
615
616
617 <hr>
618 <h2> A4 Gri and other programs </h2>
619 <A NAME="A4.1"></A>
620 <A HREF="#Q4.1"><h3>A4.1 Is Gri better than Fortran/C/... plotting subroutines?</h3></A>
621
622 <P> Gri started out as a set of subroutines. The set is called `gr';
623 the name `gri' means gr-interactive. Although I wrote both `gr' and
624 `gri', I haven't used gr in years. I am unaware of anybody else who
625 ever used `gr'. Thus, in at least this case, the interpreted Gri
626 language is superior to subroutines.
627
628 <P> In some applications the graphics are hard-wired into the
629 computation so using Gri might not make sense. An example is the SPEM
630 numerical model, which has builtin NCAR plotting calls. But this
631 approach is inefficient in user-time and computer-time, because
632 changing the format of the output may require re-running a model. The
633 best approach is to decouple preparation of data from presentation of
634 data.
635
636 <P> In highly interactive applications, such as many uses of matlab
637 and statistical programs such as S and S-plus, it may make sense to
638 use the builtin graphics routines because they are so tightly bound to
639 the processing.
640
641
642
643 <A NAME="A4.2"></A>
644 <A HREF="#Q4.2"><h3>A4.2 How can I include Gri plots in LaTeX/Word/... files?</h3></A>
645
646 <h4>Latex</h4>
647 <P> There are several schemes for including PostScript figures, such
648 as those created by Gri, into LaTeX files. That's unfortunate, in the
649 sense that it can confuse folks who are not experts. The example
650 below works great at the moment, but 5 years ago a typical user might
651 have another command instead of <tt>includegraphics</tt>, and 5 years
652 from now there may be something new. Still, I've found that
653 decade-old LaTeX files still work for me, so you shouldn't worry about
654 the chagnes.
655
656 <p>The example below includes the file <tt>fig.ps</tt> as a figure.
657 To test this, you may run a Gri script named <tt>fig.gri</tt>
658 consisting of the single command <tt>draw axes</tt>, and then save the
659 following into a file named <tt>test.tex</tt>, and then run LaTeX on
660 it, which in unix would mean typing <tt>latex test</tt> at the prompt.
661
662 <pre>
663 \documentclass{article}
664 \usepackage[dvips]{graphicx}
665
666 \begin{document}
667
668 \begin{figure}
669 \includegraphics{fig.ps}
670 \caption{Isn't this a nice graph?}
671 \end{figure}
672
673 Nice graph, eh?
674
675 \end{document}
676 </pre>
677 <p>
678 It is worth noting that LaTeX has handled graphics in various ways
679 over the years. The above indicates the preferred scheme as of 2001
680 or so, but other older schemes still work.
681
682 <h4>MS Word</h4>
683
684 All you need to do is to convert the file to GIF or PNG (see the next
685 question), or to another file format that MS word handles. It is a
686 bad idea to use a JPEG format, since that doesn't work well on
687 linegraphs.
688
689 <p>
690 <A NAME="A4.3"></A>
691 <A HREF="#Q4.3"><h3>A4.3 How may I convert Gri output to GIF format?</h3></A>
692
693 <p> Conversion of the Gri PostScript output to GIF is normally done
694 for inclusion in web-pages. For a discussion of the merits of various
695 image formats, see <A
696 HREF="http://www.lanl.gov/projects/ia">Information Architecture</A>.
697 I have been told that GIF images suffer from both technical
698 limitations (no gamma value is stored in the file) and license
699 restrictions. The PNG format was designed to overcome these
700 limitations, and is expected to replace GIF over time.
701
702 <p> It should also be noted that there is no generally acceptable way
703 to convert PostScript to gif, especially when the PostScript is vector
704 based. One problem is that of resolution: if the output GIF is
705 low-resolution, then the text may be drawn roughly because of
706 rasterization. In many convertors one may specify the size of the
707 output image, which permits control over this resolution problem,
708 giving the user the task of weighing file size against output quality.
709 Note also that the colour table frequently gets reordered in the
710 conversion, possibly leading to inaccurate results. Simply stated,
711 PostScript is superior to GIF and other raster-based formats. That's
712 why Gri chose PostScript for the output model.
713
714 <p> There are several ways to convert Gri PostScript into GIF or PNG images.
715
716 <ul>
717
718 <LI> METHOD 1. Use the <code>convert</code> program, which is a part
719 of the <code>ImageMagick</code> set of software. The
720 <code>convert</code> software is quite powerful, being able to convert
721 from almost any format into almost any other, e.g.
722 <pre>
723 $ convert gri-1.ps gri-1.png
724 </pre>
725 If the output is to be used for the web, the above is fine. If it's to be
726 imported into a word processor such as MS-Word, then the pixel resolution
727 is insufficient because the default is 72 dpi. Try this instead:
728 <pre>
729 $ convert -density 300x300 gri-1.ps gri-1.png
730 </pre>
731 The <code>ImageMagick</code> software is free, and available on the
732 world-wide-web at URL <a
733 href="http://www.wizards.dupont.com/cristy/ImageMagick.html">
734 <code>http://www.wizards.dupont.com/cristy/ImageMagick.html</code>
735 </a>
736
737 <p>
738 <LI> METHOD 2: The GNU program <code>gs</code> can also do this
739 conversion. In newer versions, this conversion to GIF is builtin.
740 Here is a shellscript
741 <pre>
742 #!/usr/bin/sh
743 gri -y -p -b $1.gri
744 gs -q -dNOPAUSE -sDEVICE=ppm -sOutputFile=$1.ppm $1.ps -c quit
745 ppmtogif -interlace -transparent rgb:ff/ff/ff $1.ppm > $1.gif
746 rm -f $1.ppm
747 </pre>
748
749 <p>
750 <LI> METHOD 3: In older versions of <code>gs</code>, you must run a
751 little program in the <code>gs</code> interpreter, by typing
752 <pre>
753 $ gs foo.ps
754 GS> (pstoppm.ps)run
755 GS> (foo) ppm1run
756 GS> quit
757 </pre>
758
759 This creates a file called <code>foo.ppm</code>, in the so-called PPM
760 format. Various programs exist for converting image types,
761 e.g. <code>convert</code>.
762
763 </ul>
764
765 <p> Availability of software: ImageMagick uses Aladdin Ghostscript,
766 another free program, to rasterize the PostScript file created by gri.
767 Ghostscript is available from <A
768 HREF="http://www.cs.wisc.edu/~ghost/index.html">
769 <code>http://www.cs.wisc.edu/~ghost/index.html</code> </A> and many
770 other sites (including any CTAN archive). Older version of
771 ghostscript are available under the GNU GPL. Speaking of GNU,
772 <code>gs</code> and other GNU software are freely available at many
773 locations on the web, e.g. <a href="ftp://prep.ai.mit.edu/pub/gnu">
774 <code>ftp://prep.ai.mit.edu/pub/gnu</code> </a>.
775
776
777 <p> <i>Author's note</i>: this answer was compiled with advice from
778 Peter Galbraith, Toru Suzuki, and George White, to each of whom I am
779 very grateful for the help. In fact, the answer is mostly a patchwork
780 of their suggestions, and all the helpful pointers to information on
781 the web are theirs, not mine.
782
783
784 <p>
785 <A NAME="A4.4"></A>
786 <A HREF="#Q4.4"><h3>A4.4 Is there an Emacs mode for Gri?</h3></A>
787
788 <p> Yes. Peter Galbraith has written a very powerful mode for Gri
789 commandfiles which is supplied with Gri and which is fully documented
790 in the manual. The capabilities of the mode include the following.
791
792 <UL>
793
794 <LI> Indents loops, if statements, newcommands, etc.
795
796 <LI> Uses built-in knowledge of Gri commands to 'complete' your
797 commands. For example, typing 'drM-TAB' (where M-TAB is the completion
798 keystroke) causes the mode to write 'draw' in place of the
799 'dr'. Pressing M-TAB again gives a list of all Gri commands starting
800 with 'draw'.
801
802 <LI> Provides complete access to Gri help on commands, including the
803 full Gri 'info' manual if your machine has that installed. There is
804 even an 'apropos' feature to let you search for commands you're not
805 sure even exist.
806
807 <LI> Lets you run Gri from within the buffer. If syntax or runtime
808 Gri errors are encountered, the cursor (usually) moves to the
809 offending line in the Gri editing buffer.
810
811 <LI> Lets you run Ghostview without leaving Emacs.
812
813 </UL>
814
815
816 <p>
817 <A NAME="A4.5"></A>
818 <A HREF="#Q4.5"><h3>A4.5 Is there a Gri module for perl/python/R/octave/...?</h3></A>
819
820 <p> No. The task of creating such modules is so time-consuming that
821 the Gri author cannot undertake it without help. (Note: Gri contains
822 about 40,000 lines of C++ code.)
823
824 <hr>
825 <h2> A5 Evolution of Gri </h2>
826 <A NAME="A5.1"></A>
827 <A HREF="#Q5.1"><h3>A5.1 Where can I get the latest version of Gri?</h3></A>
828
829 Gri is available at the
830 Gri development site
831 <A HREF="http://gri.sourceforge.net">
832 <code>http://gri.sourceforge.net</code>,
833 </A>
834
835
836 <p>
837 <A NAME="A5.2"></A>
838 <A HREF="#Q5.2"><h3>A5.2 How can I find out the most recent features of Gri?</h3></A>
839
840 <P> Just visit the
841 <a href="http://gri.sourceforge.net">
842 gri website
843 </a>
844 and look around; it's pretty simple.
845
846
847 <A NAME="A5.3"></A>
848 <A HREF="#Q5.3"><h3>A5.3 Should I keep my copy of Gri up-to-date?</h3></A>
849
850
851 <P> The advantages of being up-do-date are:
852
853 <UL>
854 <LI>You get new features.
855
856 <LI> There is a better chance of getting your bugs repaired, since all
857 bug fixes are applied only to the current version.) The disadvantages
858 of being up-to-date are:
859
860 <LI> You can get clobbered by new bugs. (You should avoid this by
861 keeping your old versions of Gri. That means archiving both
862 <code>gri</code>, the executable, and <code>gri.cmd</code>, the
863 startup file.)
864
865 <LI> You can get clobbered by changes in the syntax. This is the
866 penalty you pay for using a program under active development. To
867 protect yourself, use the <code>expecting version</code> command,
868 which will warn you of any incompatibilites between the version you
869 expect and the version that is presently installed.
870
871 </UL>
872
873 <P> Most people should not be more than 5-10 versions out of date. To
874 keep in touch, subscribe to the gri maillist (...see <a
875 href="#Q2.3">Q2.3</A>). Also, keep track of the file ChangeLog in the FTP
876 location. As with most software, the supplier may be more
877 enthusiastic about new versions than the users are. Other Gri users
878 may therefore provide the best advice on whether it is worth
879 upgrading.
880
881
882
883 <p>
884 <A NAME="A5.4"></A>
885 <A HREF="#Q5.4"><h3>A5.4 How can I protect myself against changes to Gri?</h3></A>
886
887
888 <P> The most important thing is to save old versions of Gri. At
889 hard-disk street prices of about a cent per megabyte, an archive will
890 cost under a nickle.
891
892 <p> Archiving the source is just a matter of copying the files you've
893 downloaded to a location of your choosing. Since the directory name
894 is of the form <code>gri-VERSION</code>, keeping track of old sources
895 is trivial.
896
897 <p> If you're using a prepackaged version of Gri (e.g. in RedHat or in
898 Debian linux), then you'll probably know how to update Gri already.
899 At any rate, you can skip some of the steps below, since <code> rpm
900 -ql gri</code> will list all the relevant files, saving you the part
901 of the steps below that involves locating files.
902
903 <p> Archiving the Gri binary and library file is quite easy, but
904 archiving the documentation is complicated since there are a
905 <emph>lot</emph> of documentation files, and they are scattered across
906 your filesystem. For example, 'info' files go in the
907 <code>/usr/info</code> directory, while 'manpage' files go in the
908 <code>/usr/man/man*</code> directory, and the 'html' files go
909 someplace else). This isn't specific to Gri; the filesystem is just
910 defined that way, for historical reasons. Your first step is to
911 determine whether you wish to archive the documentation. In most case
912 you won't want to. The point is just that you have an old set of
913 scripts that you need to work; you won't be writing new scripts, and
914 if you wrote these ones, then you understand Gri well enough anyway.
915 Besides, Gri doesn't change that much from version to version, and the
916 changes mostly involve additions.
917
918 <p> If you <emph>do</emph> wish to archive the documentation and emacs
919 files, locate the files and copy them. (If you do not, skip the
920 remainder of this paragraph.) In Redhat linux, do <code>rpm -ql
921 gri</code> to locate the files. In debian linux, do something
922 similar. If 'locate' is working on your computer, do <code>locate
923 gri</code> and examine the list that you get. If none of the above is
924 true, look in the second-last paragraph above for directories where
925 Gri documentation files are often found, and move them to wherever
926 seems appropriate. You'll probably have to alter other things as
927 well, to tell the <code>info</code> and <code>man</code> programs
928 where to find the documentation. If you use the Emacs editing mode,
929 move that appropriately and edit whatever dot-files and system
930 configuration files that Emacs uses to locate mode files. (Note that
931 all emacs modes understand about using different versions; see the
932 <code>C-c C-r</code> or by calling the command <code>M-x
933 gri-version</code>. If, as is likely, you're only archiving Gri for
934 old scripts that you don't need to edit, you may not need to worry
935 about changes to gri-mode and you may as well go ahead and install the
936 new gri-mode and forget about the old one.)
937
938 <p> If you <emph>only</emph> wish to archive Gri itself, things are
939 <emph>much</emph> easier! You need to copy only two files, the
940 executable (often <code>/usr/bin/gri</code>) and a library file (often
941 <code>/usr/share/gri/gri.cmd</code>) to a directory of your choosing,
942 and then create a shell alias (or a shellscript), which uses these two
943 files you've copied. Let me take it step by step.
944
945 <p>
946 First, type
947 <pre>
948 gri -version
949 </pre>
950 and make note of the present version number. For concreteness, let's
951 say it is version 2.6.0.
952
953 <p>
954 Next, decide where you wish to keep this gri version. For
955 concreteness, let's say that you'd like to keep it in
956 a directory named <code>/usr/local/gri/2.6.0</code>. Create that
957 directory if it doesn't exist already:
958 <pre>
959 mkdir -p /usr/local/gri/2.6.0
960 </pre>
961
962 <p>
963 Next, type
964 <pre>
965 gri -directory_default
966 </pre>
967 to find out where the <code>gri.cmd</code> file is located. Let's say
968 it's in the common location <code>usr/share/gri</code>, for
969 concreteness; then you need to move this to your chosen directory:
970 <pre>
971 mv /usr/share/gri/gri.cmd /usr/local/gri/2.6.0
972 </pre>
973
974 <p>
975 Now, we need to copy the executable. If you don't know where it is, type
976 <pre>
977 which gri
978 </pre>
979 to find out. Then move it also, e.g. if Gri is located in the
980 <code>/usr/bin</code> directory, you'd type
981 <pre>
982 mv /usr/bin/gri /usr/local/gri/2.6.0
983 </pre>
984
985 <p>
986 Now we just have to make an alias to run this particular copy of Gri,
987 with this particular library file. In the Bash shell, just put the
988 following line in your <code>~/.aliases</code> file:
989 <pre>
990 alias gri2.6.0='/usr/local/gri/2.6.0/gri -directory /usr/local/gri/2.6.0'
991 </pre>
992 and then you have a new command, <code>gri2.6.0</code> that runs this
993 particular copy of Gri. Alternatively, you could create a shellscript
994 to run this Gri, e.g. a script named <code>gri2.6.0</code> that
995 contains the lines:
996 <pre>
997 #!/usr/bin/sh
998 # Run numbered version of gri
999 /usr/local/gri/2.6.0/gri -directory /usr/local/gri/2.6.0 "$@"
1000 </pre>
1001
1002
1003
1004 <hr>
1005 <h2> <strong>A6</strong> Gri on various computers </h2>
1006
1007 <A NAME="A6.1"></A>
1008 <A HREF="#Q6.1"><h3>A6.1 What computers does Gri work on?</h3></A>
1009
1010 <P> Gri has been ported to several Unix machines (e.g. Sun solaris and
1011 sunOS; IBM RISC; HP RISC; SGI; DEC alpha; and x86 linux) and to x86
1012 MS-DOS. An old version is available for DEC vax VMS.
1013
1014
1015 <P>
1016 <A NAME="A6.2"></A>
1017 <A HREF="#Q6.2"><h3>A6.2 What kind of compiler is required to compile gri?</h3></A>
1018
1019 <p> Gri requires a C++ compiler capable of handling the language
1020 feature called "templates," and it also needs the so-called "standard
1021 template library" (STL). Templates have been a feature of C++ since
1022 about 1994, and STL became part of the draft C++ library standard in
1023 early 1996. If your compiler vendor does not support templates or
1024 STL, you should obtain a newer compiler.
1025
1026 <p> The free C++ compiler called <code>g++</code>, available from the
1027 Free Software Foundation, is known to compile Gri on at least a
1028 half-dozen problems. The compiler version must be 2.7.2 or higher for
1029 success.
1030
1031
1032 <P>
1033 <A NAME="A6.3"></A>
1034 <A HREF="#Q6.3"><h3>A6.3 Why can't I link my compiled gri? (on HP computer)</h3></A>
1035
1036 <p> Unfortunately, I made a bad programming decision several versions
1037 ago -- I decided to start using the STL (the standard template
1038 library). The STL is part of the draft ANSI C++ standard, so I
1039 figured I'd be safe. And my tests on solaris and linux platforms
1040 indicated that STL worked as advertised, in g++ 2.7.x. However, I
1041 should have checked further. It turns out that g++ on some platforms
1042 (e.g. HP's unix and IBMRS's AIX unix) does not handle templates
1043 properly. The linker cannot locate templates defined in one file and
1044 used in another. This issue is discussed at some length in the g++
1045 documentation, where three methods are presented for solving the
1046 problem. (In the info-format documentation, you can find the relevant
1047 parts by searching for the string "where's the template?") In Gri
1048 I've used what method 3 as defined in the g++ manual. Apparently this
1049 fails on some platforms. Although I'd welcome tests by users on the
1050 other two g++ methods, and I'd be happy to switch if one of them
1051 appeared to work more universally, I have to say that I'm not
1052 optimistic: from what I read on the newsgroups, nobody is having much
1053 success on this. The GNU folks say that g++ version 2.8 will handle
1054 templates much better, so I'm waiting for that. Unfortunately it's
1055 been, so far, a two-year wait.
1056
1057 <p> Almost certainly, commercial compilers handle templates better,
1058 but I lack resources to purchase these for the various platforms. I'd
1059 be happy, though, to act as a broker for anyone who is able to compile
1060 Gri on the problematic platforms, and who is willing to share their
1061 results.
1062
1063
1064 <p>
1065 <A NAME="A6.4"></A>
1066 <A HREF="#Q6.4"><h3>A6.4 Is there a Macintosh version of Gri?</h3></A>
1067
1068 <P> There once was a clicky-pointy Macintosh version of gri, but I got
1069 frustrated with modifying the code each time Apple upgraded the OS and
1070 stopped maintaining the code. After several years of living (happily)
1071 without the Macintosh, I flushed the Mac code down the drain.
1072
1073 <P> However, with the advent of OS-X, Gri compiles without
1074 modification. It has also been packaged for this system; check out
1075 the
1076 <a href="http://fink.sourceforge.net/pdb/package.php/gri">
1077 FINK</a> site to learn more about this project.
1078
1079 <p>
1080 <A NAME="A6.5"></A>
1081 <A HREF="#Q6.5"><h3>A6.5 Is there a DOS/Windows version of Gri?</h3></A>
1082
1083 <P> Versions of Gri have been available for MSDOS/Windows platforms
1084 for years, kindly provided by Gri users with MSDOS/Windows machines.
1085 In summer 2001, the porting procedure was systematized within the
1086 GnuWin32 project. This project provides win32 ports of GNU tools. It
1087 has been keeping very up-to-date with Gri development, trailing the
1088 Unix versions by only a week or so.
1089
1090 Please visit
1091 <A HREF="http://gnuwin32.sourceforge.net">
1092 <code>http://gnuwin32.sourceforge.net</code>
1093 </A>
1094 for more on the GnuWin32 project, and to download Gri (and other GNU
1095 software) for your windows platform.
1096
1097 <p> If, for some reason, you'd like to compile your own MSDOS/Windows
1098 version, check the Gri manual under the heading
1099 <A HREF="http://gri.sourceforge.net/gridoc/html/msdos-install.html#Msdos-install">
1100 Compilation on x86 (PC-style) Computers</A>.
1101
1102 <p> As for viewing Gri output, I recommend obtaining a copy of the
1103 Ghostview program (which is a general PostScript display program), in
1104 the version called
1105 <A HREF="http://www.cs.wisc.edu/~ghost/index.html">
1106 GSview</A>.
1107
1108 <p>
1109 <A NAME="A6.6"></A>
1110 <A HREF="#Q6.6"><h3>A6.6 Is there a linux version of Gri?</h3></A>
1111
1112 <p> For non-RedHat versions of linux, one compiles and installs Gri in
1113 the usual way; see
1114 <a href="http://gri.sourceforge.net/gridoc/html/index.html">
1115 the manual
1116 </a> for more details.
1117
1118 <P> Users of RedHat linux have it much easier though! A RPM (RedHat
1119 Program Manager) version of Gri exists, so that installing it takes
1120 just one line of typing, or one mouse-click in a GUI interface to RPM.
1121
1122 <p> The RPM (RedHat Package Manager) version exists at the
1123 Gri development site
1124 <A HREF="http://gri.sourceforge.net">
1125 <code>http://gri.sourceforge.net</code>,
1126 </a>
1127 Once you've downloaded this, install Gri by typing
1128 <pre>
1129 rpm -i gri-2.1.17-1.i386.rpm
1130 </pre>
1131
1132 Later on, Gri may be uninstalled ('extracted') by typing
1133 <pre>
1134 rpm -e gri
1135 </pre>
1136
1137 <p>
1138 Knowledgeable RedHat users will know that RPM can also give
1139 information about Gri; for non-experts, here are a few examples:
1140 <pre>
1141 rpm -qa -- list all installed packages
1142 rpm -qi gri -- summarize gri capabilities (if it's installed)
1143 rpm -ql gri -- list all files related to gri
1144 </pre>
1145
1146
1147 <hr>
1148 <h2> <strong>A7</strong> Gri bugs </h2>
1149
1150 <A NAME="A7.1"></A>
1151 <A HREF="#Q7.1"><h3>A7.1 What are known bugs in Gri?</h3></A>
1152
1153 <p> Gri is used daily by many users, including the author, so that it
1154 suffers few serious bugs. Generally, more recent versions of Gri
1155 suffer fewer bugs than earlier versions. This improvement owes much
1156 to the trial of daily usage by folks with differing working styles;
1157 and all users can thank those who send in bug reports (see <A
1158 HREF="#Q7.2">Q7.2</A>).
1159
1160 <p> One of the main problems with recent versions of Gri is that line
1161 numbers of syntax errors are reported inaccurately, if the error
1162 occured inside a new-command.
1163
1164 <p> A list of
1165 <A HREF="http://gri.sourceforge.net/gridoc/html/KnownBugs.html#KnownBugs">
1166 Gri bugs
1167 </A>
1168 is maintained in the manual.
1169
1170 <p>
1171 <A NAME="A7.2"></A>
1172 <A HREF="#Q7.2"><h3>A7.2 How can I report Gri bugs?</h3></A>
1173
1174 <p> The first step is to make sure it is actually a bug. You might
1175 try, for example, posting a question to the Gri newsgroup (see <a
1176 href="#Q2.3">Q2.3</A>), and getting advice from other users. Please
1177 be clear, so you don't waste others users' time. If you think you've
1178 found a bug, let the author know. Here's the advice from the manual
1179 (see especially item 4, for directions on emailing bug reports):
1180
1181 <P> Your bug reports help make Gri reliable and useful. Reporting
1182 bugs often results in quick changes to gri which will solve your
1183 problem. This is especially true if your version is reasonably
1184 up-to-date, for then you can simply get the corrected version and
1185 replace the version you were using. Here is how to report bugs.
1186
1187 <p> The details of how to report bugs is in the <a
1188 href="http://gri.sourceforge.net/gridoc/html/ReportingBugs.html#ReportingBugs">online
1189 documents </a>, but the quick answer is to go to
1190 the
1191 <a href="http://sourceforge.net/bugs/?group_id=5511">
1192 Sourceforge Gri/bug site</a> and use the slick GUI
1193 interface there.
1194
1195 </body>
1196
1197 </html>