.TH GIST 1 "1994 August 30"
.UC 4
.SH NAME
gist
.SH SYNOPSIS
.B gist
[[ -in ]
.I cgmfile
] [
.I page-number-list
] [
.I options
]
.br
.SH DESCRIPTION
.I Gist
is a binary CGM (Computer Graphics Metafile) browser.  It reads an input
.I cgmfile
and produces output to the X window system, PostScript files (which can
be printed using lpr(1)), or another binary CGM file.  The
.I cgmfile
may be a family of CGMs; a family is recognized whenever the final one
or two characters of the filenames (excluding an optional trailing ".cgm")
are digits in a numerical sequence (e.g.- myfile00.cgm, myfile01.cgm,
myfile02.cgm, etc.).  In this case, the
.I cgmfile
argument should be the name of the first file in the family; gist will
automatically hop back and forth from file to file as necessary.  (A single
page must not be split across files, and each file must be a legal CGM in
its own right.)  When gist opens a CGM for input, it must catalog the pages
in the file by scanning through the file to find them.  This cataloguing
operation takes place in the background while gist waits for your input.
Therefore, if you open a large family of CGMs, gist will be able to
display the first few pages immediately, but if you ask for the last few
pages, you will have to wait until the catalog is complete.  After gist
has catalogued the input family, you can render any page without delay.
.SS Options
.TP 20
.RI -in \0cgmfile
The -in is necessary if and only if the cgmfile name begins with a
digit or - sign.
.TP
.RI -ps \0psout
to specify a PostScript output file.
.TP
.RI -cgm \0cgmout
to specify a binary CGM output file.
.TP
.RI -display \0host:server.screen
to specify an X server connection.
If this option is not given, gist will use the
DISPLAY environment variable.
.TP
-75
create X window(s) at 75 dpi (small window)
.TP
-100
create X window(s) at 100 dpi (large window, default)
.TP
-gks
create X displays at 8x8 inches (default 6x6).
If your cgm file was NOT created by yorick(1), this may be a better
guess at an appropriate X window size.  You can also resize the
gist window using your window manager.
.TP
-nd
to supress the automatic display of the first
picture when gist starts in interactive mode
.TP
-b
to run in batch mode (either -cgm or -ps must
also be specified, implies -nd)
.TP
-f
to run in filter mode, placing PostScript
output on stdout (implies -b)
.TP
-x
to run as a pure X window program (no keyboard)
.TP
-fmbug
to compensate for a bug in FrameMaker 3.0X,
reverse the EPS preview top-for-bottom in EPS files.
But I recommend using ghostscript(1) from project GNU to convert
gist's PostScript output files into EPS files instead of
gist's EPS command, which makes much cruder preview images.
.TP
-bg0fg1
commercial packages which produce CGM files
may use color index 0 to mean background,
index 1 to mean foreground, despite their own
palette -- this switch compensates
.SS Page-number-list
.PP
is any number of space-delimited list elements; each element has one
of the following forms:
.TP 20
.I m
just page m
.TP
.I m-n
pages m through n, inclusive
.TP
.I m-n-s
pages m through n in steps of s
Using m<=0 or n>=total number of pages
is legal, causing the loop to terminate at
the end-of-file (or end-of-file-family)
.PP
Thus, pages 3, 5, 7, 9, 31, and 17 through 26 (in that order) would be
specified as:
.ti 8
3-9-2 31 17-26
.PP
A page number list on the command line is most useful in conjunction
with the -b or -f options.
.SS Commands
Unless the -b or -f options were specified, gist expects further commands
from the keyboard, or typed in its X window.  Keyboard commands are:
.TP 20
.RI open \0cgmfile
open a new CGM for input, closing the current input CGM.  This has no
effect on any output device.
.TP
quit
finish and close any output files, then exit.  Synonyms for the quit
command are exit and end.
.TP
.RI cgm \0cgmout \0[ size ]
create a new output CGM.  If size is specified, the file will be split
into a family whose members are about that size in bytes as more frames
are added.  The default family member size is four megabytes.
.TP
.RI ps \0psout
create a new output PostScript file.  The lpr(1) utility can print
PostScript files.
.TP
.RI display \0host:server.screen \0[ dpi ]
create a new output X window.  The dpi (dots per inch) can be either 75
(a small window), or 100 (a large window, the default).
.TP
.RI draw \0 [ page-number-list ]
render the specified pages on the "drawing" devices (X windows by default).
.TP
.RI send \0 [ page-number-list ]
render the specified pages on the "sending" devices (PostScript files and
CGMs by default).
.TP
info
list current output devices and their states.  Also prints the current
input CGM and page number.
.TP
.RI draw \0 to \0dev1 \0[ dev2 ...]
specify "drawing" devices; dev1, dev2, etc., are device numbers printed
by the info command.  By default, X windows are the "drawing" devices.
.TP
.RI send \0 to \0dev1 \0[ dev2 ...]
specify "sending" devices; dev1, dev2, etc., are device numbers printed
by the info command.  By default, PostScript files and CGMs are the
"sending" devices.
.TP
.RI free \0dev1 \0[ dev2 \0...]
close the output file or X window; dev1, dev2, etc., are device numbers
printed by the info command.
.TP
.RI eps \0epsout
create an encapsulated PostScript file, render the current page there,
then close it.  This command is provided only for sites without the
project GNU ghostscript(1) program.  Ghostscript's ps2epsi command
produces an infinitely better preview bitmap.  If you are interested
in this command, get ghostscript; it's free software.
.TP
.RI help \0 [ topic ]
prints a summary of these commands.  If specified, topic is one of the
command names; gist prints a more detailed description of that command.
.PP
Any of these commands may be abbreviated to the shortest part of their
name which is unique -- dr for draw, s for send, etc.
.PP
The following commands may be typed either in a gist X window or at the
keyboard prompt.  The
.I n
is a prefix consisting of zero or more digits; if you do not specify
.I n
the default is always 1.
.TP 6
.IR n f
advance
.I n
pages and draw
.TP
.IR n b
back up
.I n
pages and draw
.TP
.IR n g
go to page
.I n
and draw
.TP
s
send the current page to all "sending" devices
.TP
q
quit
.PP
If the -x option is specified on the command line, gist can be run in
the background like other X window programs.  In this case,
.I only
the window commands will be recognized.
.PP
.SH EXAMPLES
.PP
To print every page of a CGM file family myfile00.cgm:
.ti 8
gist myfile00.cgm -f | lpr
.br
To print only pages 3, 5, 7, 9, 31, and 17 through 26 (in that order):
.ti 8
gist myfile00.cgm 3-9-2 31 17-26 -f | lpr
.PP
To start gist as a pure X window program, with output to PostScript file
myfile.ps:
.ti 8
gist myfile00.cgm -ps myfile.ps -x &
.br
Type the f, b or g commands in the gist graphics window to navigate through
myfile00.cgm.  Use the s command to write the current page into myfile.ps;
the q command quits.
.PP
To use gist on foreign.cgm which was not generated by Yorick, try:
.ti 8
gist -75 -gks -bg0fg1 foreign.cgm
.PP
.SH AUTHOR
.PP
David H. Munro, Lawrence Livermore National Laboratory
.PP
.SH FILES
.PP
Y_SITE refers to the Yorick site directory; use the help command in
yorick(1) to find its name at your site:
.TP 25
Y_SITE/gist/*
graphics style sheets, palettes, and PostScript template
.SH BUGS
.PP
Gist is designed to convert yorick(1) binary CGM output files into
PostScript perfectly.  That is, running a yorick binary CGM through
gist will produce exactly the same PostScript file (and X window) as
yorick would have produced directly.
.PP
However, the ANSI CGM standard is not a page description language like
PostScript.  Therefore, non-yorick CGMs may or may not be acceptably
rendered by Gist.  The -gks and -bg0fg1 options may help, but you can
expect fonts, polymarkers, and line styles to look different with
Gist than with other CGM browsers (.e.g- idt from NCAR graphics).
.PP
If gist cannot find the PostScript template Y_SITE/gist/ps.ps, PostScript
output will not work.
.PP
You can't use multiple X windows to compare two different pages (they all
display the same page).  Start a second copy of gist.
.PP
On pseudocolor displays, a color image may require you to move the mouse
into gist's X window to display properly.  Unless your window manager
allows you to set colormap focus independently of keyboard focus, this
can be annoying.
.SH SEE ALSO
yorick(1)