*========================================================================
*
* Name - README
*
* Version:	1.8
*
* ccsid:	@(#)README	1.8 - 7/6/92 10:52:21
* from: 	../work/ccs/s.README
* date: 	7/6/92 10:54:25
*
* Copyright (C) 1990-92 Bruce Schuchardt
* See either the man page or the file cpyright.h for full copyright
* information.
*
* Description:  README for xgrabsc v2.0
*
*========================================================================

INTRO TO xgrabsc

When I first wrote xgrabsc, there were a number of programs available
for getting X-Window screen dumps (e.g., xwd and xwps), but they
were all restricted to dumping a single window in a single format.
I wrote xgrabsc in an effort to get around these restrictions.

The main contribution of this program is its use of root-window
rubberbanding to allow capture of arbitrary portions of the screen,
and its multiple output formats (x-bitmap, x-pixmap, xwd, puzzle,
"simple", and several Postscript formats).

The Postscript dumps will use run-length encoding if it results in
any savings in size.  A typical xterm window dump on a mono system
runs around 40K bytes (20K for binary output).  An xwd dump on the
same screen will be around 650K bytes.  While the xpr program has a
"compress" option, it only compresses white samples.  Reducing the 
size of the output increases the cost of computing the dump and the
final printing of the dump, but it reduces the cost of storage and
the time to transfer the dump to your printer.  The latter is
especially important for large screen dumps.

The xgrabsc program is not interactive.  You specify all processing
options on the command line with obscure option characters.  These
are all detailed in the man page.  An interactive interface to xgrabsc,
named xgrab, is also included in this release.  xgrab allows you to
do most of the setup with a mouse, and then uses the xgrabsc program
to actually do the processing.  To use xgrab you must have the xgrabsc
program in your execution path.



OPTIONS FOR BUILDING xgrabsc

The file config.h contains all the configuration options for xgrabsc.
Please take a moment to look through that file before building xgrabsc.



BUILDING xgrabsc

Xgrabsc should build easily enough.  If you don't have the imake
program, use simple.mak (i.e., make -f simple.mak).  There are targets
for xgrabsc, install, install.man, and clean.  E.g.,
  make
  make install
  make install.man
  make clean

The install target will put xgrabsc in /usr/bin/X11 and the
man page in /usr/man/man1.  Change simple.mak before installing
with it if you don't like these locations.

For Vax/VMS installations, this release includes a VMSMAKE.COM script that was
contributed by a user, as well as a GETOPT.C module that implements the
getopt() function.  I am informed that you will also need a copy of the
XWDfile.h include file from the MIT XWindows distribution, so I've included a
copy of that file.  I do not have a Vax to test with so I can't claim you won't
have problems in building xgrabsc under VMS, but this gives you a running start
at it. 



Please send comments, bugs, and enhancements to bruce@slc.com.  Please
read the Bugs file before sending bug reports.


 Manifest
 ---------------------------------
 README              this file
 README.xx_yy        files describing incremental changes to xgrabsc

 Acks                acknowledgements for code gleaned from other
                     systems, and people who have been very helpful
                     in adding features and removing bugs from xgrabsc

 Bugs                known bugs - read this before sending bug reports

 Imakefile           Input for "imake" program
 simple.mak          Simpler input for standard "make"

 checkvm.h           Memory-check Postscript operator
 config.h            Configuration options
 cpyright.h          Copyright notice for this software (READ IT)
 ps_color.h          Bob Tatar's colorimage operator for mono systems
 patchlevel.h        Current patch level
 virtual.h           Support for virtual window managers
 xgrab.c             Source for window interface to xgrabsc
 xgrabsc.c           Program source

 *.hc                function include files for xgrabsc.c

 GETOPT.C            getopt() for VAX/VMS
 VMSMAKE.COM         a DCL command script to make xgrabsc and xgrab under VMS
                     (this is untested - I no longer have a VAX at my disposal)
 XWDfile.h           xwd structure definition needed for VAX/VMS builds
 
 ad2c.sed            sed script to convert XGrab.ad to fallback resources
                     for xgrab

 xgrabsc.man         Man page for xgrabsc
 xgrab.man           Man page for xgrab

 XGrab.ad            Resources for the xgrab program



BUGS:

Common problems and known bugs are described in the Bugs file.



TO DO:

Support for 24-bit displays.  If someone wants to give this a shot, please
let me know.

Selectable paper size for Postscript output.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Bruce Schuchardt          bruce@SLC.COM
  Servio Corp.
  Beaverton, OR