installing the program

once you've built the executable, put it somewhere on the path and it 
should run ok (he said).  it needs no resource files or environment
variables or anything like that. it does need the shared libraries for
X11 (the X windowing system), Xt (the X intrinsics toolkit), Xaw (the 
athena widget set), and the standard c library, but if you got it to
build then the loader should be able to find all these at run-time.  if
you do get problems with `ld.so: can't find ...' messages, set the
variable LD_LIBRARY_PATH to point to the directory/directories where the
shared libraries live.  see the man pages for ld(1) for more on that.
you shouldn't have this problem, anyway.  



command-line options

usage xtiff: [options] tiff-file
	standard Xt options
	-help
	-gamma gamma
	-usePixmap (True | False)
	-viewportWidth pixels
	-viewportHeight pixels
	-translate pixels
	-verbose (True | False)
	-zf zoomfactor (-1 == best fit)

o	standard Xt options (the useful ones)

	-display display:screen
		tell xtiff to connect to X display `display' and to use 
		screen `screen'.

	-name name-of-application
	-title name-of-application
		set the name of the application to `name-of-application' (the
		default is xtiff). the name is displayed on the top bar of the
		program window.

	-font fontname
	-fn fontname
		tell xtiff to display strings in the font `fontname'.  there's
		no default, but a good one is fixed.

	-geometry xpixelsxypixels
		tell xtiff to try and open a window xpixels wide and ypixels
		high.  this overrides -viewportHeight and -viewportWidth
		(see below).

o	-help
		print a summary of the command line options xtiff recognises
		then exit.

o	-gamma gamma
		specifies the value used to build compensation tables for
		simple gamma correction for colour values.  not very useful
		or effective for cern preprints, which are all mono.

o	-translate pixels
		tells xtiff how many pixels to move the displayed image
		when the arrow keys are pressed.  the default is 20.

o	-usePixmap (True | False)
		tells xtiff not to use a pixmap to store the image on a server.
		this may be necessary if the X server limits the size of 
		pixmaps and may refuse to allow xtiff to create one (and so
		prevent you from displaying your image unless you set this
		option to false).

o	-viewportWidth pixels
		tells xtiff the width in pixels of the image viewport.  the
		default is 700 pixels or the image width, whichever is less.

o	-viewportHeight pixels
		tells xtiff the height in pixels of the image viewport.  the
		default is 500 pixels or the image height, whichever is less.

o	-verbose (True | False)
		tells xtiff whether to display libtiff error messages or
		not.

o	-zf zoomfactor
		tells xtiff how much to shrink the displayed image by
		before displaying it.  the default is 1 (ie don't shrink).
		setting this value to -1 tells xtiff to shrink the
		displayed image so that it fits into the program window.

if you're using xtiff with mosaic to view cern preprints then good
values to set for it in the mosaic defaults are
	-fn fixed 
	-geom 800x600 
	-zf 3
which gives xtiff a 800 x 600 pixel window, a nice readable font and
shrinks the displayed images by a factor of 3, which is a reasonable
compromise between how much you can see and whether you can read it.



operating the program

the major interface to the program is via the button bar along the top.
the buttons are supposed to be comprised of meaningful text or pictures
that make obvious what each button does (if you don't think this is the
case you can change them or design your own - see buttons.notes).  below
is a list of each button's name and what it does (going from left to
right along the button bar):


button name	what it does
------------------------------------------------------------------------------
  quit		quit the program, leave xtiff altogether  
  prev		go to & view the previous page in the document, eg to page 1 
		from page 2
  next		go to & view the next page in the document, eg to page 7 
		from page 6
  first		go to & view the very first page of the document
  last		go to & view the very last page in the document
  shrink	make the page smaller, fit more text into the window
  grow		make the page larger, make the text bigger
  full		display the page at full size (as scanned)
  fit		shrink the document enough to fit it all into the window
  zero		display the page unrotated (as scanned)
  ninety	display the page rotated to 90 degrees clockwise,  
  		ie ^  becomes >
  oneeighty	display the page rotated to 180 degrees clockwise,  
		ie ^ becomes v
  twoseventy	display the page rotated to 270 degrees clockwise,
		ie ^ becomes <
  goto		select, go to & view an arbitrary page in the document
  help		display a window with a list of the buttons and what
		they do


if the displayed image is too big for the program window you can grab it
with the left mouse button and scroll it, or you can move it with the
arrow keys.

note that any rotation or shrink factor you specify will be applied to
all pages of the tiff document currently displayed.


BUGS

this is a primary release, so it is by no means bug-free.  the major
problem is that occasionally the program gets very unhappy with a
particular file and insists that it has compression encoding errors and
displays a great many black lines rather than the text and diagrams one
might expect to see.  there seems to be no rhyme or reason to this and
the author would be very pleased to hear anyone's theories.

cern preprint tiff files seem to be riddled with a tag (0x8335) that the 
libtiff package doesn't know and complains about.  this doesn't
bring the program down in flames, but it does clutter up your screen.  if
you don't want to be irritated by libtiff's complaints about this unknown
tag, run xtiff like this (cshell only):
	xtiff [options] file |& grep -v 0x8335

rotations are V E R Y   S L O W.

all fixes, comments etc (see bugreport.notes) to

dave@preprints.cern.ch (there until august 1995)

xtiff.notes