Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ZGV(1)			       Graphics	Software			ZGV(1)

NAME
       zgv - picture viewer for	VGA/SVGA displays

SYNOPSIS
       zgv [options] [start-dir	| file [file2 ...]]

DESCRIPTION
       (NB:  This man page is automagically generated from zgv's texinfo file,
       and so may look a bit odd.  We apologise	for the	inconvenience. :-))

       zgv lets	you view pictures on Linux or FreeBSD boxes with VGA/SVGA dis-
       plays.  The  kinds  of  pictures	it supports are	raster-format pictures
       (sometimes called `bitmaps' and/or `pixmaps'); things like  GIF	files,
       JPEG  files,  PNG files,	and so on. (The	full list of file formats sup-
       ported is listed	elsewhere. See Supported File Formats.)

       Most of the time, you will probably want	to  use	 zgv's	file  selector
       (see The	File Selector) to pick which file(s) to	view. This is what ap-
       pears when you start zgv	as just	`zgv' (see  Options).  It  displays  a
       list  of	 subdirectories	 and  picture  files in	the current directory,
       along with small	`thumbnail' versions of	the pictures  if  they	exist.
       (If  no thumbnails appear for a given directory,	or if they are missing
       for some	files, you can create/update them by pressing `u'.  See	Updat-
       ing Thumbnails.)

       When you've picked a file to view, you can view it by pressing `Enter'.
       This puts you into the viewer, where the	whole screen is	used  to  dis-
       play the	picture	(see The Viewer). You can then move around the picture
       (if it is larger	than the screen) using the cursor keys.	Pressing `Esc'
       returns	you  to	 the file selector, where you can pick another file to
       view, or	you can	quit zgv by pressing `Esc' again.

       While zgv is by default controlled entirely from	the keyboard, it  does
       have  quite  good mouse support you can enable if you like that sort of
       thing. See Using	a Mouse.

       This overview is, as you	might expect, only the very simplest of	intro-
       ductions	 to  what  zgv	can do,	and describes only a very basic	use of
       zgv. zgv	can do a lot more; read	on to find out what.

ACKNOWLEDGEMENTS
       zgv was primarily written by Russell Marks, who also wrote this manual.

       Matan Ziv-Av added multiple-image animated GIF support,	Photo-CD  sup-
       port,  brightness/contrast  support  in high-colour modes, the original
       file-rename code, and some of the support for 32-bit modes, as well  as
       inspiring a few other changes like high-res file	selector support.

       Carsten Engelmann wrote the BMP support.

       Edwin  Fong  added support for command-line slideshows, and a few other
       features	including the original mouse support.

       Radim Kolar added support for FreeBSD.

       Costa Sapuntzakis contributed code for much faster JPEG thumbnail  gen-
       eration.

       Dimitar Zhekov added SDL	mouse support.

       `install-info'  is  a  (very) slightly modified version of the original
       (which is part of the `texinfo' package). This program is  used	during
       installation. I think it	was mostly written by Karl Berry, but it's not
       terribly	clear.

       The authors of the special-purpose libraries zgv	 uses  deserve	credit
       ---  JPEG and PNG might not have	been supported in zgv without the JPEG
       library,	libpng and zlib. Most of all though, zgv would	certainly  not
       have  been written without VGAlib and later svgalib, and	thanks are due
       to Tommy	Frandsen, Harm Hanemaayer, Michael Weller,  Matan  Ziv-Av  and
       many others for that.

       Thanks  also  to	 the zgv users who've contributed bug reports, sugges-
       tions, ideas for	features, and even... dare I say...  compliments.  zgv
       would be	even worse without their input,	so count your lucky stars. :-)

       This  program  is  based	 in  part  on the work of the Independent JPEG
       Group.

       ``The Graphics Interchange Format(c) is the Copyright property of  Com-
       puServe	Incorporated. GIF(sm) is a Service Mark	property of CompuServe
       Incorporated.''

OPTIONS
       Normally	you'd invoke zgv as plain `zgv'.  However,  you	 can  directly
       specify	files to view or a start directory on the command-line.	In ad-
       dition, there are various options.

       (If you're new to zgv, you should probably skip the rest	of  this  sec-
       tion for	now and	come back to it	later.)

       The general format of the zgv command-line goes roughly like this:

       zgv [options] [start-dir	| file [file2 ...]]

       Two types of options are	supported --- the traditional Unix single-let-
       ter options, and	GNU-style long options.	Both forms are listed  in  the
       table below, but	not all	long options have single-letter	equivalents.

       Note  that  all	options	are processed after any	configuration file(s).
       Config file settings are	just like the long-option  names  below	 minus
       the  `--'  (see Configuring zgv), though	a few command-line options are
       not permitted as	config file settings (e.g. `help'), and	vice versa.

       Here's what the options do:

       `-A'
       `--auto-animate'
	      Automatically animate multiple-image GIF files (see Multiple-im-
	      age  GIF	Animation).  This limits your viewing options greatly,
	      but can be handy for slideshows and the like.

       `--auto-mode-fit'
	      Automatically switch modes to suit image size.

       `--auto-mode-fit-diff diff'
	      When choosing an auto-mode-fit mode, add	diff  to  each	mode's
	      width and	height.	For example, with a value of 20	any picture up
	      to 820x620 will be displayed in an 800x600 mode if possible.  If
	      diff  is	negative, for example -20, the effect is reversed; any
	      picture above 780x580 will be displayed in a mode	with a resolu-
	      tion higher than 800x600 if possible.

       `-p'
       `--avoid-single-progress'
	      Don't  show  progress  indicator when loading a single file from
	      the command-line.

       `--black-background'
	      Try to use a black  (or  nearest-to-black)  background  when  in
	      8-bit modes.  This can be	quite nice for consistency's sake when
	      viewing (say) a mixture of GIFs and JPEGs, but  the  extra  pass
	      over the loaded image slows things down slightly.

       `-b'
       `--block-cursor'
	      Use a blocky outline cursor in the selector, which is rather un-
	      subtle but more obvious.

       `--brightness adjust_val'
	      Specify how much to add to colour	values	to  change  brightness
	      (default	0).  Values less than zero decrease brightness,	values
	      greater than zero	increase it. Brightness	is applied after  con-
	      trast by default.

       `--centre'
       `--center'
	      (Normally	 enabled,  use e.g. `--centre=off' to disable.)	By de-
	      fault zgv	centres	pictures smaller than the screen, in whichever
	      dimensions  they	are  smaller.  This setting gives you a	way to
	      disable this, so that pictures always  start  in	the  top-left.

       `--clear-screen-on-exit'
	      Clear  the  screen  on  exit. (Normally, zgv leaves the original
	      screen contents intact.)

       `--col-black r g	b'
	      Set colour used for  `black'  (text)  in	selector;  RGB	values
	      should  be  in the range 0-63 for	this and the other colour set-
	      tings below, and	the  three  numbers  should  be	 quoted,  e.g.
	      `--col-black "10 20 30"'.

       `--col-dark r g b'
	      Set colour used for lowlights in selector.

       `--col-light r g	b'
	      Set colour used for highlights in	selector.

       `--col-medium r g b'
	      Set colour used for background in	selector.

       `--col-tagged r g b'
	      Set colour used for tagged files in selector.

       `--contrast multiplier'
	      Specify how much to multiply colour values by to change contrast
	      (default 1.0). zgv multiplies each colour's difference from grey
	      by  this	number;	values less than one decrease contrast,	values
	      greater than one increase	it. Negative values are	also  allowed,
	      and  act	in  a  similar way, but	with the picture's colours in-
	      verted. Contrast is applied before brightness by default.

       `--delete-single-prompt'
	      (Normally	enabled, use `--delete-single-prompt=off' to disable.)
	      If  disabled, don't prompt for confirmation when deleting	a sin-
	      gle file.

       `--delete-tagged-prompt'
	      (Normally	enabled, use `--delete-tagged-prompt=off' to disable.)
	      If  disabled,  don't  prompt  for	confirmation when deleting all
	      tagged files.

       `--dither-16col-fast'
	      (Normally	enabled, use `--dither-16col-fast=off' to disable.) By
	      default,	zgv  uses a (reasonably	fast) ordered dither when dis-
	      playing a	dithered colour	image in 640x480x4 mode.  But  if  you
	      disable  this  setting,  it uses error-diffused dithering	(which
	      looks better but is rather noticeably slower).

       `--dither-hicol'
	      If enabled, use dithering	in `high-colour' modes,	i.e. 15/16-bit
	      modes.  This  makes  colour gradients smoother, but slows	things
	      down quite a bit.

       `--fake-cols'
	      (Normally	enabled, use `--fake-cols=off' to  disable.)  If  dis-
	      abled,  don't  fake  extra  greyscales and colour	depth in 8-bit
	      modes.  See Increased Greyscales,	for details.

       `--force-fs-16col'
	      Force the	use of the 640x480 16-colour mode for the selector.

       `-j'
       `--force-viewer-8bit'
	      Force all	images to be loaded as 8-bit. Normally zgv  will  load
	      24-bit  images  (e.g.  colour  JPEGs)  as	24-bit if you have any
	      modes capable of displaying the image in 15, 16, 24,  or	32-bit
	      colour.

       `--fs-16col-colour-thumbnails'
       `--fs-16col-color-thumbnails'
	      Use low-quality colour thumbnail pictures	when the file selector
	      is using 640x480 16-colour mode. Normally	zgv uses  higher-qual-
	      ity monochrome thumbnails	in this	situation.

       `--fs-ignore-old-pos'
	      Don't  recall  previous  cursor position in a directory when re-
	      turning to it later. (This mechanism only	applies	when  changing
	      directory	 `normally';  jumping directly to another dir with `G'
	      never does such a	save/restore (see Changing Directory).)

       `--fs-magic'
	      Use `magic number'-type identification to	determine which	 files
	      should  be  listed  in the file selector.	This is	more accurate,
	      but very much slower. See	File Type Identification, for  a  dis-
	      cussion of the tradeoffs involved.

       `--fs-perfect-cols'
	      Don't  change  thumbnail colours when using the file selector to
	      make the rest of the selector look right.	See Thumbnail Issues.

       `--fs-slow-thumbnail-update'
	      `Walk' through the directory when	 updating  thumbnails,	moving
	      the  cursor  over	every single picture whether it	needs updating
	      or not. Normally,	zgv completely skips any pictures which	 don't
	      need  updating,  which makes it considerably faster on large di-
	      rectories	and/or slow machines.

       `--fs-small-text'
	      Reduce the size of the filename text in the  selector.  You  may
	      find  this  useful if you	think the text is too big, or if you'd
	      like to see more of the filename without having to press `:'.

       `--fs-start-mode	modespec'
	      Specify the video	mode zgv should	start off using	for  the  file
	      selector.	 (The  default	is  640x480x8  if  possible, otherwise
	      640x480x4.)  The `modespec' should be  the  width,  height,  and
	      depth  in	 quotes, e.g.  `"640 480 8"'. See Video	Modes, for de-
	      tails of precisely what this means. The specified	depth is actu-
	      ally  ignored  in	 this case, as you can only choose 8-bit modes
	      for the selector.

       `-t'
       `--fs-thick-text'
	      Thicken the text (filenames etc.)	 in  the  file	selector  (and
	      elsewhere).   (Note that if line-text has	been enabled, then fs-
	      thick-text only has an effect if block-cursor is on as well.)

       `--fullscreen'
	      (Normally	enabled, use `--fullscreen=off'	to disable.) This  op-
	      tion  only  applies  when	using the SDL backend. By default, zgv
	      generally	uses the entire	screen for its	display.  But  if  you
	      disable  this  option, it	tries to run in	a window when possible
	      (e.g. when running under X). Note	that zgv won't be able to fill
	      the screen in modes it doesn't natively support, in either case.

       `-G val'
       `--gamma	val'
	      Set  the gamma adjustment	used (see Gamma	Adjustment). This also
	      sets the `initial	value' used when resetting the	gamma  adjust-
	      ment. The	default	is 1.0,	i.e. no	adjustment.

       `--gnulitically-correct'
	      GNU  has POSIXLY_CORRECT for compatibility with silly POSIX mis-
	      features,	and zgv	has...

       `-h'
       `--help'
	      Display a	list of	options	and a terse description	 of  what  the
	      options do.

       `-i'
       `--ignore-errors'
	      When  loading a single file from the command-line, ignore	(some)
	      errors.  Only meaningful for PNG currently.

       `--jpeg-index-style style'
	      Specify how to read JPEGs	when creating thumbnails. Style	`1' is
	      the quickest, but	sometimes generates rather fuzzy/blocky	thumb-
	      nails; `2' is fairly cautious (and the default), but still quite
	      fast; `3'	is an extremely	cautious and slow method.

       `-J type'
       `--jpeg-speed type'
	      Set  JPEG	speed/quality tradeoff.	Type `1' is slow but accurate;
	      `2' is faster but	not as accurate	(and the default); `3' is  the
	      fastest but the least accurate.

       `--line-text'
	      Draw  text by drawing lines rather than using bitmap fonts. This
	      looks worse but is faster.

       `-M'
       `--mouse'
	      Enable mouse support in zgv. /dev/mouse must be (usually a  sym-
	      link to) the mouse device. The actual configuration of the mouse
	      should be	done via svgalib's config file libvga.config; see  the
	      man page for that	for details.

       `--mouse-scale scale'
	      Set  the	ratio of `mouse	pixels'	to onscreen pixels. The	larger
	      the number, the slower the mouse moves, and  vice	 versa.	 (How-
	      ever,  the  number  must	be  greater  than  zero.) If the mouse
	      pointer moves at the wrong speed for  your  tastes,  play	 about
	      with this	setting	and you	should be able to fix it.

       `--pcd-res resnum'
	      Selects  the  resolution	used  for  Photo-CD  files; 1=192x128,
	      2=384x256, 3=768x512 (default), 4=1536x1024, 5=3072x2048.	 (This
	      setting  only  has  an effect if Photo-CD	support	was enabled at
	      compile-time.)

       `-g'
       `--pgm-truecol'
	      This one needs some background to	fully  explain	---  greyscale
	      files  are normally displayed in 8-bit modes, which due to VGA's
	      limited palette means that only 64 greyscales can	be shown  (zgv
	      normally	fakes  extra  ones, though; see	Increased Greyscales).
	      But for people who work with greyscale files and have  24/32-bit
	      video  modes  available  this  can  be frustrating, as 24/32-bit
	      modes display 256	greyscales. For	this reason, using the `--pgm-
	      truecol'	option	enables	a special-case hack to read (only) PGM
	      files as if they were 24-bit. Using a 24/32-bit mode then	 gives
	      you  256	greyscales.  (Be  careful  to avoid 15/16-bit modes as
	      these will only give 32! See Drawbacks of	15/16-bit Modes.)

       `-r seconds'
       `--reload-delay seconds'
	      If seconds is positive, then any picture	displayed  is  re-read
	      and  redisplayed	(without clearing the screen first) every sec-
	      onds seconds. If it's `0'	(zero),	or negative,  the  picture  is
	      only  read once --- the default. Unless this option has suddenly
	      inspired you to write an interesting little shell	script,	you're
	      unlikely ever to have a use for it. :-)

       `--reverse-bc-order'
	      Normally,	 any brightness	modification is	applied	after applying
	      any contrast. Enabling this reverses the order.

       `--revert-orient'
	      (Normally	enabled, use  `--revert-orient=off'  to	 disable.)  If
	      disabled,	orientation (flip/mirror/rotate) state is retained be-
	      tween pictures.

       `--revert-scale'
	      (Normally	enabled, use `--revert-scale=off' to disable.) If dis-
	      abled, scaling is	retained between pictures.

       `--scrollbar'
	      (Normally	 enabled,  use	`--scrollbar=off' to disable.) If dis-
	      abled, don't show	a scrollbar below the selector.

       `-s'
       `--show-dimensions'
	      Cause zgv	to output the x	and y offsets, and width and height of
	      the  section of the image	being displayed	when you exit zgv. Can
	      be useful	for things like	`pnmcut	`zgv -s	input.ppm` input.ppm >
	      output.ppm'.

       `-T'
       `--show-tagged'
	      Print  names of tagged files on exit. This can be	useful in con-
	      structions something like	`mv `zgv -T`  /tmp',  which  moves  to
	      /tmp only	the files you select.

       `--show-xvpics-dir'
	      Show  any	 .xvpics  directories  so  that	 the thumbnails	can be
	      viewed even if the files they referred to	no longer exist. (How-
	      ever,  it's  usually  easier  to simply start zgv	in the .xvpics
	      dir.)

       `-S delay'
       `--slideshow-delay delay'
	      Set time to wait in seconds before loading the next picture in a
	      slideshow. The default is	4.

       `-l'
       `--slideshow-loop'
	      Loop in slideshows `forever' (or rather, until you exit).

       `-R'
       `--slideshow-randomise'
       `--slideshow-randomize'
	      Randomise	 picture order in slideshows. Due to the shuffling ap-
	      proach taken, there will be no repeats or	omissions.

       `--viewer-16col-colour'
       `--viewer-16col-color'
	      Give a dithered colour image  in	640x480x4  mode	 when  in  the
	      viewer (see The Viewer 640x480x4 Mode), rather than greyscale.

       `-m modespec'
       `--viewer-start-mode modespec'
	      Specify  the  video  mode	 zgv  should  start  off using for the
	      viewer. The default is generally 640x480x8, but it's actually  a
	      bit  more	 complicated  than  that (see Default Video Mode). The
	      `modespec' should	be the width, height,  and  depth  in  quotes,
	      e.g.  `"640  480	8"'. See Video Modes, for details of precisely
	      what this	means.

       `--visual'
	      (Normally	enabled, use `--visual=off' to disable.) If  disabled,
	      no thumbnails are	shown.

       `-k'
       `--vkludge'
	      enables  vkludge,	 which	smoothes slightly when `zooming' a big
	      picture down to screen  size,  and  also	when  in  320x400  and
	      360x480 modes.

       `--version'
	      Show version number.

       `-w'
       `--write-ppm'
	      Write  the file as a PPM to stdout rather	than viewing it. (This
	      only works if you	run zgv	on a single  file,  specified  on  the
	      command-line.)   You're usually better off using a dedicated im-
	      age-converting program, though.

       `--xzgv-keys'
	      Makes zgv	acts a bit more	like xzgv, at least in	terms  of  the
	      keypresses it supports (see xzgv Compatibility).

       `-z'
       `--zoom'
	      Enable  zoom  mode, which	resizes	the picture to fit the screen.
	      See Zoom Mode.

       `--zoom-reduce-only'
	      When in zoom mode, only reduce pictures to fit;  i.e.  make  big
	      pictures	viewable  all-at-once  while leaving small picures in-
	      tact.

       If zgv is started with `zgv file', zgv auto-loads the  file  (bypassing
       the  file  selector), and exits when you	exit from viewing the picture.
       (By the way, this also makes it possible	to view	single	files  without
       the usual extensions such as .gif, etc. See File	Type Identification.)

       If  started with	`zgv file file2	...' --- i.e. with more	than one file-
       name ---	zgv works in a similar way,  except  the  multiple  files  are
       shown as	a slideshow, one after the other. You may want to specify `-l'
       so that zgv will	loop around these pictures until `Esc' is pressed, and
       the `-R'	option to shuffle (randomise) the picture order	may also be of
       interest.

       If started with `zgv start-dir',	zgv starts up with the usual file  se-
       lector, but with	the current directory being the	one specified.

       Settings	which are either on or off (boolean) are, as you might expect,
       enabled by using	e.g. `-z' or `--zoom'. However,	there's	an alternative
       long-option  form for setting these, resembling how they're set in con-
       fig  files  ---	the  syntax  is	 `--option=state',  where   state   is
       `on'/`y'/`yes'/`1'  to enable the option, or `off'/`n'/`no'/`0' to dis-
       able it.	The most useful	thing about this is that it allows you to dis-
       able options which were previously enabled, by using e.g. `--zoom=off'.

       (Readers	 used to the way GNU-style long	options	work should note that,
       since this `on'/`off'/etc. arg is optional, you can't use the `--option
       arg' form in this case; it must be `--option=arg' for it	to work.)

ONLINE HELP
       Online  help  (of  a  sort)  is available in both the file selector and
       viewer:

       `?'
	      Gives online help. This lists some  of  the  most	 commonly-used
	      keypresses in the	current	context.

       In the viewer, you can also get a list of which key combinations	select
       which video modes. See Selecting	a Video	Mode.

THE FILE SELECTOR
       Usually,	on starting up zgv, you	will enter the	file  selector,	 which
       lets you	pick files to view (among other	things). This lists the	subdi-
       rectories and picture files in the current directory, along with	 small
       `thumbnail' versions of the pictures if they exist.

EXITING	ZGV
       Exiting zgv can be achieved two ways:

       `Esc'
       `x'
	      Quit zgv normally.

       `^C'
	      Quit zgv in a rather immediate and nasty way, by sending SIGINT.
	      (This is actually	dealt with by svgalib.)	You should only	use ^C
	      to  quit	if  zgv	appears	to lock	up or takes an unbearably long
	      time to do something.

	      (Technically it may not be `^C'  which  sends  SIGINT,  but  you
	      would have to have a strange setup for this to be	the case.)

THUMBNAILS
       (This section is	deliberately early on in the manual, as	thumbnails are
       probably	the most important feature of the file selector, so it's  best
       that you	know how to create/update them sooner rather than later.)

       Thumbnails  are	small versions of the pictures they represent, and are
       displayed by the	file selector if they exist.  zgv  uses	 xv-compatible
       thumbnails  ---	if  you	 create	thumbnails with	xv they	will work with
       zgv, and	vice versa. zgv's thumbnails  are  also	 compatible  with  the
       Gimp, and xzgv.

       If  no  thumbnail exists	for a file or directory, a small `document' or
       `folder'	graphic	appears	instead.

   Updating Thumbnails
       While thumbnails	can be made relatively quickly,	it's by	 no  means  an
       instant	process. For this reason, thumbnails have to be	created	in ad-
       vance, and are stored as	files in their own right in (usually) a	subdi-
       rectory .xvpics.

       zgv  never creates/updates thumbnails without you telling it to.	So, if
       you enter a directory where the picture files  don't  have  any	thumb-
       nails, or where the thumbnails seem to be out of	date, you should press
       `u'.

       Alternatively, you can create/update thumbnails for the current	direc-
       tory  and all subdirectories by using `Alt-u'. But be warned that a re-
       cursive update can take some time!

       `u'
	      Create thumbnails	for any	files which don't have them,  and  up-
	      date  thumbnails	which  are  older  than	than the corresponding
	      file. While this is going	on, the	text updating  index  of  pre-
	      fixes the	usual display of the current directory's name.

	      You can press `Esc' while	the update is in progress to abort it;
	      zgv will stop once it has	finished the thumbnail it is currently
	      working on (if any).

	      If  you switch consoles while the	update is in progress, it will
	      continue to run `in the background'. When	you  switch  back,  if
	      the  update  is  still in	progress, it may look as though	zgv is
	      doing nothing (or	the screen may look a bit confusing) for  some
	      time. The	reason is that the screen is not updated unless	zgv is
	      running on the currently displayed  console  (this  is  unfortu-
	      nately necessary). The screen is redrawn when the	current	thumb-
	      nail has been dealt with.

       `Alt-u'
	      Create/update thumbnails for all files in	the current  directory
	      and  all	subdirectories	--- in other words, do a recursive up-
	      date. This can take some time, so	you are	 prompted  to  confirm
	      that you really want to do this (see Dialog Boxes). As above, it
	      will continue running `in	the background'	 if  you  switch  con-
	      soles, and you can press `Esc' to	abort.

       `d'
	      Create  thumbnails  for  subdirectories. Don't confuse this with
	      the recursive update; this generates thumbnails for the directo-
	      ries  themselves,	not the	files within them. (Most people	proba-
	      bly won't	want to	bother with these, as they're not  as  helpful
	      as  you  might  think.) These consist of the first four files in
	      the subdir, squeezed together into a single thumbnail. There  is
	      (currently)  no `update' mechanism for subdir thumbnails --- all
	      of them are newly	created	each time you press `d'.

   Thumbnail Storage
       Normally, thumbnails are	stored in the subdirectory  .xvpics  (creating
       the  dir	first if needed), with the same	name as	the filename they rep-
       resent. However,	there are times	when using .xvpics isn't possible  ---
       for  example, the filesystem may	be read-only (such as on a CD),	or may
       not support the .xvpics name (such as on	an msdos filesystem),  or  you
       may not have permission to write	to the directory.

       In  these  situations,  zgv stores the thumbnails elsewhere. They go in
       directories under the .xvpics dir in your home directory. The name  for
       the  directory  they  go	in there is the	directory name they were found
       in, but with slashes (`/') converted to underscores (`_').

       An example should make things clearer. Say zgv needs to create a	thumb-
       nail  for  wibble.jpg,  in  the	directory  /foo/bar/baz, but can't use
       .xvpics.	It will	put the	thumbnail  in  $HOME/.xvpics/_foo_bar_baz/wib-
       ble.jpg,	creating directories as	necessary.

       Where  a	 thumbnail  is stored makes virtually no difference to how zgv
       works; the main difference is that the latter,  more  indirect  way  of
       storing	thumbnails  means that thumbnails will take slighter longer to
       display.

   Thumbnail Issues
       The thumbnails used in zgv require 256 colours  to  display.   Unfortu-
       nately,	the  rest  of  zgv's  file  selector  needs an additional five
       colours.	Normally this is dealt with by finding the `closest' thumbnail
       colours,	and (this is the important part) changing them to the file se-
       lector colours. The disturbance to the thumbnails should	be barely  no-
       ticeable.

       (All  the  same,	you can	disable	this using the config file setting fs-
       perfect-cols (see Configuring zgv). But bear in mind that the  selector
       will then look rather strange!)

       In 16-colour mode (see 16-colour	File Selector),	the way	it works means
       fewer colours are needed, and the file selector's five colours  can  be
       (and are) separate from the thumbnail colours.

SCREEN LAYOUT
       The  file  selector  is	simply a list of subdirectories	and filenames,
       along with any thumbnails that exist for	them. The list is in asciibet-
       ical  order  (but you can change	this; see Changing the Sorting Order).
       Names of	directories are	shown (like this), and they are	shown in order
       at the beginning	of the list, before all	the picture files.  Long file-
       names are truncated to fit; three dots indicate	where  this  has  hap-
       pened.  (See Other File Sel Commands, for how to	display	the full file-
       name.)

       The list	is often larger	than can fit on	the screen at once. If this is
       the  case,  only	 part  is shown	at a time, but you can move around the
       list with the cursor keys and the like.

       The colours used	for the	file selector can be changed, if  you  dislike
       the defaults (see Configuring zgv).

MOVING AROUND THE LIST
       The  cursor in zgv is (normally)	shown as a `raised' entry in the list.
       The cursor has two main functions:

       - It selects a file for `view', `tag' etc. commands to operate on.

       - It determines which part of the list is shown,	as  the	 part  of  the
       list shown onscreen always contains the cursor.

       There  are  many	commands for moving the	cursor.	In summary, most `spe-
       cial' keys like the cursors do what you'd imagine they do ---  also,  a
       few  Emacs-like	keys,  a  few vi-like keys, and	the Sinclair Spectrum-
       style (!) QAOP keys are supported.

       Using a mouse in	the file selector is not covered here. See Mouse Funcs
       in the File Selector, for details of what you can do with a mouse. (Ex-
       perienced users may wish	to consult the Tom _ Jerry and Pinky  and  the
       Brain cartoons for further enlightenment	on this	subject.)

       `Cursor Up'
       `^P'
       `k'
       `q'
	      Move  up.	 Moving	up from	a topmost entry	moves to the bottom of
	      the previous column.

       `Cursor Down'
       `^N'
       `j'
       `a'
	      Move down. Moving	down from a bottommost entry moves to the  top
	      of the next column.

       `Cursor Left'
       `^B'
       `h'
       `o'
	      Move left	one column.

       `Cursor Right'
       `^F'
       `l'
       `p'
	      Move right one column.

       `Page Up'
       `^U'
	      Move the cursor back (nearly) a page.

       `Page Down'
       `^V'
	      Move the cursor forward (nearly) a page.

       `Home'
       `^A'
	      Move the cursor to the start of the list.

       `End'
       `^E'
	      Move the cursor to the end of the	list.

       `g'
       `''
	      Move the cursor to the first filename starting with the next key
	      pressed, which would generally be	a letter or  number.  Case  is
	      significant; `a' and `A' are different.

	      If  no files start with the specified character, it moves	to the
	      first file which starts with a later char	(in  asciibetical  or-
	      der).  If	there are none for which this is the case, it moves to
	      the last file ---	unless there are no files (just	 directories),
	      in which case it has no effect.

VIEWING	A FILE
       There  are two ways to view files from the file selector. The usual way
       is to press `Enter' when	you've moved the cursor	to the file  to	 view.
       However,	 you can also view tagged files	as a `slideshow', which	is de-
       scribed later (see Tagging).

       `Enter'
	      View a picture file, or if the cursor is on a subdirectory, make
	      that  the	 current directory. A progress indicator is shown when
	      reading in a file	--- while this is onscreen, you	can use	 `Esc'
	      to abort.

DIALOG BOXES
       If  zgv	has  a	serious	problem	reading	a file,	it will	give an	error.
       Errors are shown	in boxes which appear in the middle of the screen  ---
       they  stay  there  until	 you press `Enter' or `Esc' (if	using a	mouse,
       clicking	OK has the same	effect).

       zgv also	uses similar dialog boxes for other things:

       - Getting a yes or no answer. `Enter' or	`y' picks `yes'; `Esc' or  `n'
       picks  no.  (Again, you can click on the	relevant button	with the mouse
       to do the same.)

       - Reading a directory name. Here	you should  type  the  directory  name
       then  `Enter', or press `Esc' to	abort. In fact,	this line-input	dialog
       allows a	certain	amount of editing, and so  supports  these  additional
       keys:

       `Cursor Left'
       `^B'
	      Move  the	 cursor	left. (An underline character shows the	cursor
	      position.)

       `Cursor Right'
       `^F'
	      Move the cursor right.

       `Home'
       `^A'
	      Move the cursor to the start of the line.

       `End'
       `^E'
	      Move the cursor to the end of the	line.

       `Insert'
       `^I'
	      Toggle insert/overwrite mode. (Insert mode is the	 default.)  In
	      insert  mode, characters you type	are inserted at	the cursor po-
	      sition. In overwrite mode, they replace the existing chars.

       `Backspace'
       `^H'
	      Delete char to the left of the cursor. (This assumes `Backspace'
	      really  generates	 a  `DEL',  which is the usual setup on	Linux.
	      Note that	`Backspace' is (usually) the key above the  main  `En-
	      ter' key;	it is often labelled simply as an arrow.)

       `Delete'
       `^D'
	      Delete the char the cursor is on.

TAGGING
       The  file  selector is not restricted to	working	on one file at a time.
       You can `tag' as	many (or as few) files as you wish, and	 certain  com-
       mands described in this section will act	on them.

       Initially,  all	files are untagged, and	the filenames appear in	black.
       Tagged files appear in red. (See	Configuring zgv, if you'd  prefer  zgv
       to use different	colours.)

   Tag and Untag Commands
       There  are  several  ways to tag	or untag files.	The ones which work on
       individual files	also move the cursor forward one place afterwards,  to
       make tagging or untagging multiple files	easier.

       As  elsewhere  in  zgv, the case	of the keys is significant --- the `t'
       (unshifted `t') command has quite a different effect  to	 that  of  `T'
       (shifted	`t').

       There  is  also a command available in the viewer to tag	the currently-
       viewed file. See	Changing Picture, for details.

       `t'
	      Tag file.

       `n'
	      Untag file. Note that this is `n'	(for `no tag',	er,  or	 some-
	      thing  like  that);  `u' would be	more logical, but that is used
	      for updating thumbnails.

       `T'
	      Tag all files.

       `N'
	      Untag all	files. This is on `N' rather than `U' for consistency.

       `Space'
	      Toggle the tag status of the file	--- if it's tagged, untag  it;
	      if it's untagged,	tag it.

       To  see how many	files are tagged, use `Alt-f' (see Other File Sel Com-
       mands).

   Slideshows
       A `slideshow' lets you view all the tagged files	in the current	direc-
       tory  one  after	 the other, or in a randomised order if	`shuffling' is
       enabled (see File Selector Toggles):

       `Tab'
	      View the tagged files as a slideshow. (`Tab' is usually the  key
	      above `Caps Lock', which is often	labelled with two arrows.)

       Each  file  is  shown for a certain amount of time, normally 4 seconds.
       (See Options, if	you find this too short	or long.) After	the time  runs
       out, the	next file is shown. You	can cut	this delay short by hand using
       one of the viewer's change-picture commands such	as `Space' (see	Chang-
       ing Picture), or	abort the slideshow prematurely	by pressing `Esc'. You
       can also	pause a	slideshow so that you remain on	the current file until
       you unpause it (see Pausing Slideshows).

       Normally, once each file	has been shown the slideshow ends, and you are
       returned	to the file selector. But if looping is	enabled, the slideshow
       repeats until you press `Esc' (see File Selector	Toggles).

   Copying/Moving/Deleting Files
       You can copy or move tagged files to a directory	you specify, or	delete
       all tagged files. If no files are tagged, zgv copies/moves/deletes  the
       file the	cursor is currently on --- unless the cursor is	on a subdirec-
       tory, in	which case it gives an error.

       Note that the commands given here are uppercase --- lowercase `c', `m',
       and `d' do not do the same thing.

       `C'
	      Copy  tagged  files  (or the current file) to a given directory.
	      zgv asks for the destination directory using a dialog (see  Dia-
	      log  Boxes)  and	copies	the files there. If it comes to	copy a
	      file but there is	an existing file in  the  dir  with  the  same
	      name,  the  file	is not copied and nor are any of the remaining
	      files.

       `M'
	      Move tagged files	(or the	current	file) similarly.

       `D'
	      Delete tagged files (or the current  file)  similarly.  In  this
	      case, there's obviously no need to specify any directory :-) but
	      you're prompted before deletion starts (unless this is disabled,
	      see  Configuring	zgv).  It  also	 deletes thumbnails, for those
	      files which have them.

RENAMING A FILE
       As well as copying/moving files,	you can	rename them:

       `R'
       `Alt-r'
	      Rename the current file or directory  ---	 zgv  will  refuse  to
	      overwrite	 any existing files/directories. The new name must re-
	      main in  the  current  directory.	 (See  Copying/Moving/Deleting
	      Files,  for  how to move a file to a different directory (albeit
	      keeping the same name).)

       It's better to use `R' than `Alt-r'; the	latter never made much	sense,
       and is likely to	be removed before long.

CHANGING DIRECTORY
       The  easiest  way  to change the	current	directory in zgv is usually to
       select a	directory entry	in the file list and press `Enter'.   (Select-
       ing `(..)' moves	to the parent directory	of the current one.)

       There is	an alternative though:

       (Note that this command is shift-`g', not `g'.)

       `G'
	      Go to a specified	directory. zgv asks for	the destination	direc-
	      tory using a dialog box which you	should	type  the  dir's  name
	      into  (see  Dialog Boxes), and moves to that directory if	it ex-
	      ists.

	      If the directory turns out to be unreadable --- i.e. you do  not
	      have permission to read it --- zgv resorts to going to your home
	      directory.  (This	is actually a general mechanism	 in  zgv,  but
	      this  command is the most	likely trigger of it.) If that in turn
	      is unreadable, zgv gives up in disgust and exits.	:-)

CHANGING THE SORTING ORDER
       Normally, the files are listed in asciibetical order by name.  However,
       you  can	 instead  have	the  file  list	 sorted	by size, last-modified
       date/time, or by	`extension' (the file type).

       (Only the order of files	can be altered;	directories are	always	listed
       first, and always in name order.)

       `Alt-n'
	      Sort by name. This is the	default.

       `Alt-s'
	      Sort by size. The	biggest	files are listed last.

       `Alt-d'
       `Alt-t'
	      Sort  by	last-modified  date/time.  The newest files are	listed
	      last.

       `Alt-e'
	      Sort by extension.

FILE SELECTOR TOGGLES
       Various aspects of the file  selector's	behaviour  can	be  configured
       while  zgv is running, by using these toggle commands (which enable the
       feature if it was previously disabled, and vice versa).

       These settings can also be altered using	command-line options (see  Op-
       tions) and/or config file settings (see Configuring zgv).

       `v'
	      Toggle display of	thumbnails (default is on). The	without-thumb-
	      nails display can	sometimes  be  useful  for  navigating	around
	      large  directories  (many	filenames are shown onscreen at	once),
	      and it is	of course faster.

       `s'
	      Toggle scrollbar on/off (default is  on).	 The  scrollbar	 shows
	      which  part  and which proportion	of the list is currently being
	      shown onscreen, and when mouse support is	enabled	can be used to
	      move around the list.

       `S'
	      Toggle shuffling (randomising) of	slideshows. See	Slideshows.

       `L'
	      Toggle looping in	slideshows. See	Slideshows.

       `Alt-m'
	      Toggle  use  of  `magic  numbers'	(identifiers at	the start of a
	      file) to pick which files	in a directory to list in  the	selec-
	      tor.  The	 usual method of doing this is based on	the file's ex-
	      tension (see File	Type Identification, which is much faster  but
	      won't catch e.g. files without extensions.

       `c'
	      If  the  file  selector is running in 16-colour mode (it usually
	      doesn't unless zgv has no	choice --- see 16-colour  File	Selec-
	      tor), toggle between greyscale (default) and colour thumbnails.

OTHER FILE SEL COMMANDS
       There  are  some	other commands in the file selector which don't	easily
       fit anywhere else. Here they are:

       `Delete'
	      Delete (only) the	file the cursor	is on. Asks  for  confirmation
	      (unless  this is disabled, see Configuring zgv). It also deletes
	      the file's thumbnail, if it has one. See Copying/Moving/Deleting
	      Files,  for  a  more  general  command  which deletes all	tagged
	      files.

       `:'
	      Show various details about the file the cursor is	on; the	(full)
	      filename,	the size in kilobytes, width/height if recorded	in any
	      thumbnail, last-modified date, etc. You can also use the `;' key
	      to get this.

       `Alt-f'
	      Show the number of (picture) files in the	current	directory, and
	      the number of tagged files (see Tagging).

       `^L'
       `^R'
	      Rescan the directory contents, and redraw	the screen.

       `K'
	      Kill mouse --- disable mouse for the rest	of this	 zgv  session.
	      (It  prompts  to check if	you really want	to do so.) This	can be
	      useful if	you have the mouse enabled in a	config file,  so  that
	      zgv always starts	up with	the mouse on, but you're currently us-
	      ing just the keyboard. In	such a situation the mouse pointer can
	      be  a bit	annoying. This command lets you	disable	the mouse com-
	      pletely for the current zgv process.

SHOWING	MORE FILES
       The  file  selector  normally  runs  at	a  relatively  low  resolution
       (640x480),  meaning  it can only	show 20	thumbnails at once. This keeps
       the selector running at a reasonable speed even on slow machines.

       If you have  a  faster  machine,	 however,  and	your  video  card  has
       256-colour  modes  with	higher	resolutions  than  640x480  (see Video
       Modes), you may want to see more	thumbnails onscreen at once.

       (zgv tends not to look as `right' in such modes as it does in the usual
       640x480,	but apart from that it's much the same.)

       `F1'
	      Select 640x480 mode. This	is the default.

       `F2'
	      Select 800x600 mode.

       `F3'
	      Select 1024x768 mode.

       `F4'
	      Select 1280x1024 mode.

       If  you	want to	change the default mode	used in	the file selector, use
       the fs-start-mode config	file setting (see Configuring zgv).  For exam-
       ple, to use 800x600 by default, you'd use fs-start-mode 800 600 8.

       Note these modes	are subject to the same	checks as in the viewer	--- in
       particular, this	means that the file selector obeys the viewer's	 mode-
       good, mode-bad, etc. settings. See Config Variables.

       Finally,	 if  you have no 640x480 256-colour mode, or if	force-fs-16col
       has been	set, the 640x480 16-colour mode	is all that is available.

16-COLOUR FILE SELECTOR
       The file	selector normally operates in a	256-colour mode	 (by  default,
       the  640x480  one).  However,  the  original VGA	cards didn't have this
       mode, and SVGA cards not	supported by svgalib won't have	it as  far  as
       zgv is concerned	either.

       For  such  cards,  zgv supports a more limited and slower file selector
       which works in 640x480 16-colour	mode. It should	be easy	to tell	 which
       zgv  is using --- if thumbnails appear in monochrome rather than	colour
       (and the	files are colour pictures ;-)) then it's running in  16-colour
       mode.  (Another	hint is	that 16-colour mode has	an extra border	around
       the edge	of the screen which 256-colour mode probably won't have.)

       As you might imagine, having 240	fewer colours makes things  difficult.
       The default way of coping with this is the greyscale thumbnails (eleven
       grey levels are used), which are	reasonably fast	and quite faithful  to
       the  originals. If you'd	prefer less accurate --- but colour ---	thumb-
       nails (eight colours are	used, with dithering and increased  contrast),
       you  can	 press `c' to toggle between the two, or set zgv up to default
       to using	colour thumbnails instead with	fs-16col-colour-thumbnails  on
       in a config file	(see Configuring zgv).

       (For  those  of	you  out there who have	a 640x480 256-colour mode, but
       feel you're missing out by not seeing this 16-colour file selector :-),
       you can force zgv to use	it by using the	--force-fs-16col option.)

THE VIEWER
       When a picture is being shown onscreen, you're in the viewer. This sec-
       tion describes what you can do while viewing the	picture.

EXITING	THE VIEWER
       Exiting the viewer is simple:

       `Esc'
       `x'
	      Exit the viewer.

	      If you got to the	viewer from the	file selector, you're returned
	      there;  if you bypassed the file selector	(by running zgv	with a
	      file (or files) to view specified	on the	command-line  ---  see
	      Options) then exiting the	viewer also exits zgv.

BIG PICTURES
       A  picture  may	well be	too large to fit entirely on the screen. There
       are two general ways to see the whole of	the picture, and  in  addition
       to  those, you may be able to fit more on by choosing a different video
       mode (see Video Modes), either manually or by using auto-mode-fit.

       (For multi-resolution Photo-CD files, there is yet another  alternative
       approach	(see Supported File Formats).)

   Scrolling
       Scrolling is the	default	approach to handling big pictures in zgv. When
       the viewer is started up, the top-left of the picture is	shown ---  you
       can  use	 the  cursor keys (and many others) to move around the rest of
       the picture.

       `Cursor Up'
       `K'
       `Q'
	      Move up 100 pixels. `k' and `q' move up 10 pixels.

       `Cursor Down'
       `J'
       `A'
	      Move down	100 pixels. `j'	and `a'	move down 10 pixels.

       `Cursor Left'
       `H'
       `O'
	      Move left	100 pixels. `h'	and `o'	move left 10 pixels.

       `Cursor Right'
       `L'
       `P'
	      Move right 100 pixels. `l' and `p' move right 10 pixels.

       `Page Up'
       `^U'
	      Move up (nearly) a  screenful.  (It  moves  90%  of  the	screen
	      height.)

       `Page Down'
       `^V'
	      Move down	(nearly) a screenful.

       `-'
	      Move  left  (nearly)  a  screenful.  (It moves 90% of the	screen
	      width.)

       `='
	      Move right (nearly) a screenful.

       `Home'
       `^A'
	      Move to the top-left of the picture.

       `End'
       `^E'
	      Move to the bottom-right of the picture.

   Zoom	Mode
       An alternative way of viewing the whole picture,	one which lets you see
       the picture onscreen all	at once	no matter how big (or small) it	is, is
       zoom mode.

       Zoom mode's name	derives	from the idea of `zooming' a small file	up  to
       fit the screen. But in reality, it is more often	used to	reduce a large
       file to fit the screen.

       Zoom mode is not	the default, and has to	be enabled. Once  enabled,  it
       stays on	until you turn it off again.

       By default, the way zoom	mode reduces a file to fit the screen is (rel-
       atively)	quick but harsh, and may make the picture look ugly.  Enabling
       vkludge smoothes	the picture, giving a better and more accurate result,
       but takes longer. It too	is not the default, but	stays on until	turned
       off again.

       `z'
	      Toggle zoom mode.

       `Alt-r'
	      When in zoom mode, only reduce pictures to fit. This can be use-
	      ful when going through a lot of unpredictably-sized pictures, as
	      it  means	 that  you can see all of a big	picture	easily without
	      also meaning that	tiny little icons assume a scale  of  Biblical
	      proportions. :-)

       `v'
	      Toggle  vkludge,	which  enables appropriate smoothing when zoom
	      mode is reducing a picture to fit	the screen.  It	 also  enables
	      similar  smoothing  for  non-zoomed  pictures  in	 320x400x8 and
	      360x480x8	modes.	See Virtual Modes.

       `n'
	      Resume `normal' display ---  disables  zoom  mode	 (and  scaling
	      mode).

   Auto-mode-fit
       If  it  seems  strange  to you to use scrolling or zoom mode to see the
       whole picture when you could just use a different video mode (to	change
       the  size of the	pixels displayed onscreen), you	may find auto-mode-fit
       useful.

       If enabled, and when a picture is loaded, the current mode is automati-
       cally  switched	to  the	`smallest' mode	which is both wider and	taller
       than the	picture	is (or of equal	width/height).	In  other  words,  the
       (theoretically)	most  appropriate mode.	If no mode can fit the picture
       onscreen, the `largest' mode is chosen.

       Auto-mode-fit is	not the	default, so you	have to	enable it if you  want
       to use it.

       `Z'
	      Toggle auto-mode-fit mode. Usually this only takes effect	when a
	      picture is loaded	(so that manual	mode switching	still  works),
	      but  when	 you enable it zgv does	a one-off auto-mode-fit	on the
	      current picture. (Note also that disabling it leaves you in  the
	      current  mode,  so  that has no obvious effect; for this reason,
	      the picture is redrawn (as a visual cue that  you	 haven't  just
	      been ignored :-)).)

       I  should  point	 out  that all the mode-switching can be a bit hard on
       your monitor, so	even if	you really like	this option you	might not want
       to  enable  it  all  the	time (e.g. in a	config file), but instead only
       turn it on when you `need' it. Still, it's up to	you.

       Certain modes are excluded from those chosen by auto-mode-fit. In  par-
       ticular,	no 320x200 mode	is ever	chosen,	nor is 320x400x8. These	excep-
       tions are made due to the unusual aspect	ratio. 640x480x4  is  excluded
       due  to the slightly odd	way it works, which makes it ill-suited	to au-
       tomatic selection. 360x480x8 is considered, despite the	aspect	ratio,
       if no 640x480x8 mode exists.

SCALING
       You  can	 scale a picture --- this makes	it appear larger onscreen. zgv
       acts exactly as if the scaled-up	picture	were the real picture; for ex-
       ample, the cursors scroll around	in steps of 100	scaled-up pixels, even
       if this means moving a fraction of a pixel in the original picture.

       The main	limitation of scaling is that you can only scale up by integer
       values,	so  you	 can  only  make  each	pixel  in  the	image twice as
       wide/high, or three times as wide/high, or four times, and so on.

       (It may seem odd	saying e.g. `twice as wide/high'  rather  than	`twice
       the size', but technically `twice the size' would be referring to scal-
       ing up the width	(and height) by	about 1.414...)

       Normally, zgv does no scaling, which could be  considered  a  ratio  of
       1:1.   Scaling  up increases that ratio.	How it is increased depends on
       which key you use:

       `s'
	      Increase the ratio by adding one --- this	 leads	to  ratios  of
	      2:1, 3:1,	4:1...

       `d'
	      Increase	the  ratio  by doubling	it --- leads to	ratios of 2:1,
	      4:1, 8:1...

       Usually `d' is more useful.

       There are similar commands to decrease the ratio	(when it  reaches  1:1
       scaling is disabled):

       `S'
	      Decrease the ratio by subtracting	one.

       `D'
	      Decrease the ratio by halving it.

       The  scaling  ratio  is never decreased below 1:1. It is	also never in-
       creased beyond 512:1, where zgv stops so	that pixels may	 be  conserved
       for future generations. :-)

       You can undo the	effect of scaling at any time by using `n' (which also
       disables	zoom mode).

       Normally, scaling works by simply making	the  pixels  into  larger  and
       larger  squares	(in effect), which remain the same colour. However, if
       you are using a 15/16/24/32-bit mode (see Video Modes), you can	enable
       a  feature  called  `interpolation' which smoothly graduates the	colour
       change between the top-left corners of each pixel. This is  very	 slow,
       but looks nice.

       `i'
	      Toggle interpolation in scaling mode.

       `!'
	      Toggle  off-by-one  interpolation	 (disabled  by default). Using
	      this off-by-one method gives incorrect results, but this can oc-
	      casionally  be  useful  at  ratios of 2:1	and 3:1	for relatively
	      low-quality JPEGs.

       (If you like the	appearance of scaling with interpolation, you may also
       be interested in	a program I wrote called pnminterp, which can scale up
       a PGM or	PPM file while applying	this effect.)

MIRROR AND ROTATE
       Sometimes when viewing a	picture	you will want to flip it  horizontally
       or vertically, or rotate	it:

       `m'
	      `Mirror' the picture (flip it horizontally).

       `f'
	      `Flip' the picture (flip it vertically).

       `r'
	      Rotate the picture 90 degrees clockwise.

       `R'
	      Rotate  the picture 90 degrees anti-clockwise. (This is a	little
	      slower as	it works by effectively	doing `r' then `f' then	`m'.)

       `Alt-n'
	      Restore the picture orientation to normal. This undoes  the  ef-
	      fect of any mirrors, flips, and/or rotations.

       zgv  normally  reverts the picture orientation (the way the picture has
       been transformed	by mirror/flip/rotate) back to normal when you view  a
       new  picture. However, there are	various	ways you can retain the	orien-
       tation between pictures,	so that	the new	picture	is mirrored,  flipped,
       and/or rotated in the same way. Here are	two of the ways:

       `Alt-o'
	      Re-use the previous picture's orientation	for this picture.

       `Alt-s'
	      Save the current picture orientation, making all pictures	viewed
	      until you	press `Esc' use	it. (The orientation reverts to	normal
	      after that, though.)

       Finally,	 you  can  choose  to have the orientation preserved the whole
       time. To	do this, put revert-orient off in a config file	(see Configur-
       ing zgv).

BRIGHTNESS AND CONTRAST
       zgv provides support for	changing brightness and	contrast in all	modes,
       though it does slow things down a little	in 15/16/24/32-bit modes  (see
       Video Modes).

       `,'
	      Decrease contrast.

       `.'
	      Increase contrast.

       `<'
	      Decrease brightness.

       `>'
	      Increase brightness.

       `;'
	      Reset contrast and brightness to normal. (`*' is also supported,
	      for hysterical raisins.)

       Any contrast change is applied before any brightness change by default.
       However,	you can	reverse	the order easily enough:

       `B'
	      Reverse the order	in which brightness and	contrast are applied.

       The order they're applied in does make a	difference --- assuming	you've
       modified	both brightness	and contrast, of course. :-) The normal	 order
       simply  means  you have a increased-contrast image which	you change the
       brightness of. Obviously	then, the reverse order	reverses this, but  it
       has  the	 additional effect of changing the point around	which contrast
       is applied.

GAMMA ADJUSTMENT
       Ah yes, gamma. What fun.	The basic problem is this ---  differing  dis-
       plays  have  differing intensity	response curves. ``This	has made a lot
       of people very angry and	been widely regarded as	a bad move.'' :-)

       It means	that you need some way of adjusting how	brightly  you  display
       the  picture  to	 compensate.  But  since  we're	 dealing with response
       curves, this isn't just a matter	of changing the	brightness in a	linear
       fashion.

       That  doesn't  seem so hard to deal with, right?	All you	need is	to get
       the gamma (a number which specifies how much the	curve bends)  for  the
       image, and for the screen, divide one by	the other and adjust as	appro-
       priate. Joy.

       But, given that the problem has existed	since  we  started  displaying
       more  than  eight colours, you won't be surprised to find that it's al-
       ready been fixed. And the fixes all tend	to clash, and everybody	has  a
       different  notion  of  how to fix it. The usual `fix' is	to assume that
       whoever made the	image made it with a gamma matching the	gamma of  your
       display,	so you can just	stuff the bits right on	the screen. Since this
       is easy,	it's the most widespread approach. But it's a bit  stupid,  so
       not everyone does it. Combine that with the lack	of gamma specification
       in most image formats, and the often-bogus values specified  by	people
       in  those  that	do,  and  hey presto --- the image gamma could be just
       about anything. And the screen's	gamma also tends not to	be easily  de-
       termined.

       So how on earth do you deal with	something like that in a remotely sane
       fashion?

       The answer chosen in zgv	is to just live	with the fact that the	proba-
       bility  of  automatically  obtaining correct values for both the	screen
       and image gamma is basically zero. Once you accept that,	 the  sensible
       thing to	do is to make it very easy and fast to change gamma adjustment
       to commonly-required values. So here's how to do	it:

       `1'
	      Set gamma	adjustment to 1.0, i.e.	no adjustment. This is the de-
	      fault setting.

       `2'
	      Set  gamma adjustment to 2.2. This is useful for viewing linear-
	      gamma files (one classic example being raytracer output)	on  an
	      average PC monitor.

       `3'
	      Set  gamma  adjustment  to  1 divided by 2.2, i.e. roughly 0.45.
	      This is useful for the reverse ---  viewing  average-PC-monitor-
	      gamma  files  on	a linear-gamma display.	Historically I believe
	      the classic example would	have been viewing PC files on  a  Mac,
	      but I don't know how true	that is	these days.

       `4'
	      Set  gamma  adjustment  to  its initial value, as	specified by a
	      `-G' command-line	option (see Options) or	gamma config file set-
	      ting  (see  Configuring zgv). The	default	value used if none was
	      specified	is 1.0.

       A brief clarification is	probably in order. The gamma adjustment	 value
       which  you  set	in zgv is actually inverted from (i.e. one divided by)
       the true	adjustment value used. This is (believe	it  or	not  :-))  in-
       tended  to  avoid confusion by reflecting the fact that screen gamma is
       the one most widely considered/well known.

       You can also tweak the adjustment more precisely, in a similar  way  to
       brightness/contrast:

       `Alt-,'
	      Decrease gamma adjustment	(divide	it by 1.05).

       `Alt-.'
	      Increase gamma adjustment	(multiply it by	1.05).

       Note  that `;', and the other keys which	reset the brightness/contrast,
       deliberately avoid resetting the	gamma adjustment.

INCREASED GREYSCALES
       zgv normally displays greyscale pictures	 in  8-bit  modes  (see	 Video
       Modes). Due to a	limitation of the original VGA cards, these can	have a
       maximum of 64 greyscales. This can give noticeable `edges' in some pic-
       tures.

       So  when	using 8-bit video modes, zgv uses some trickery	to try and in-
       crease the apparent colour depth	a little. The trick zgv	uses is	to in-
       crease  one  or	two  of	 the  red/green/blue channels by one, giving a
       coloured	`pseudo-grey'. Since the eye is	more sensitive	to  brightness
       than colour, this is reasonably convincing under	normal conditions. (It
       can get less convincing if you scale up the  picture,  but  it  usually
       looks reasonable	even then.)

       A  slightly  more unusual use of	this technique in zgv, though, is that
       it carries on using it for colour 8-bit images.	I'm  not  certain  how
       valid  this is; the `sub-depth' value is	calculated as a	greyscale, and
       the channels altered are	the same, with no consideration	given  to  how
       this might affect the colour balance.

       However,	 the  difference  this feature makes is	very slight. The image
       will probably be	very, very slightly brighter than it would  be	other-
       wise, and possibly a little `warmer' because of the minor use of	colour
       and the eye's green/red bias (I think).

       You can toggle this feature in the viewer:

       `G'
	      Toggle whether to	fake some extra	 greyscales/colours  in	 8-bit
	      modes.

       To  disable it by default, put fake-cols	off in a config	file (see Con-
       figuring	zgv).

CHANGING PICTURE
       While in	the viewer, it's possible to go	directly to  the  previous  or
       next  file in the directory without having to exit to the file selector
       and pick	the relevant file by hand.

       There are two ways to do	this; one way leaves the old picture  onscreen
       until  the new one is read in, the other	(on `^P' and `^N') temporarily
       returns to the file selector and	shows  the  usual  progress  indicator
       while it's being	read.

       In addition, one	of the next-file-in-dir	commands lets you tag the file
       currently being viewed first, without having to return to the file  se-
       lector to do it.

       Note  that  the	meanings of the	commands change	when you are viewing a
       slideshow; the details are covered below.

       (See Dialog Boxes, to see what `Backspace' is being used	to mean	here.)

       `Backspace'
	      View previous file  in  dir,  without  progress  indicator.  (In
	      slideshow, move to next file without waiting.)

       `Enter'
	      View   next   file  in  dir,  without  progress  indicator.  (In
	      slideshow, move to next file without waiting.)

       `Space'
	      Tag current file,	then view next file in dir,  without  progress
	      indicator.  (In slideshow, move to next file without waiting; it
	      has no tagging effect during a slideshow.)

       `^P'
	      View  previous  file  in	dir,  with  progress  indicator.   (In
	      slideshow, acts like `Esc'.)

       `^N'
	      View  next  file in dir, with progress indicator.	(In slideshow,
	      acts like	`Esc'.)

       Note that `Space' tags the file,	rather than toggling the tag status as
       it  does	in the file selector. This mismatch is unfortunate, but	in the
       viewer context the always-tag function is more likely to	be what	 you'd
       want,  since  you  can't	 see  the file selector	to see which files are
       tagged.

FILE DETAILS
       While you can get file details when in the file selector, you can't al-
       ways get	to the selector	--- for	example, you might be running zgv on a
       single image from the command-line, or using it in that	way  from  an-
       other  program (such as lynx). So zgv can also report file details when
       in the viewer:

       `:'
	      Show file	details, including such	things as the filename,	 size,
	      and  width/height.  This	is  almost identical to	the equivalent
	      command in the selector (see Other File Sel Commands); the  only
	      difference  is that you can't use	`;' to get this	in the viewer,
	      and the viewer doesn't depend on thumbnails for the width/height
	      info.

PAUSING	SLIDESHOWS
       Sometimes you may want to temporarily stop a slideshow, when you	get to
       an interesting image. You can do	this the same way you would  temporar-
       ily stop	terminal output:

       `^S'
	      Pause  slideshow,	leaving	you on the current image until you re-
	      sume. You	can still abort	early with `Esc', go to	the next image
	      with `Enter', or in fact use any viewer commands at all.

       `^Q'
	      Resume  slideshow.  If  the  timer has already run out (it keeps
	      running while paused), this will go straight to the  next	 image
	      without  any  further  delay, other than that needed to read the
	      new picture.

       The analogy with	XON/XOFF isn't really that close --- for example, it's
       worth  noting  that when	the slideshow is `paused', you can actually do
       anything	you normally might in the viewer.

MULTIPLE-IMAGE GIF ANIMATION
       While zgv is for	the most part a	straightforward	viewer,	it has special
       support	for  multiple-image  animated GIF files. These are loaded as a
       `column'	of images, one on top of the other --- this column is the sin-
       gle image which is then displayed, enabling you to see all the `frames'
       of the GIF. (Though not in an image thumbnail; in those,	only the first
       image is	shown.)

       You  can	 also  switch to an `animation'	mode in	the viewer, where each
       `frame' is shown	one after the other, with (roughly) the	 delay	speci-
       fied in the GIF between updates.

       (This animation mode is automatically enabled if	you start zgv with the
       `-A' or `--auto-animate'	command-line option. See Invoking zgv.)

       `e'
	      Enter animation mode. (I don't know what the `e' stands for  ei-
	      ther.   :-)) In this mode	the normal viewer keys have no effect,
	      and instead, a more limited set of keys are supported:

       `Esc'
       `x'
	      Stop the animation and return to the viewer.  If	auto-animation
	      mode is enabled, it exits	the viewer too.

       `p'
	      Pause (or	unpause) the animation.

       `n'
	      Skip to the next frame. Generally	only useful when paused.

       If  auto-animation  is  enabled,	 the `Backspace', `Enter', and `Space'
       keys do the same	as they	do in the normal  viewer  (see	Changing  Pic-
       ture). Otherwise	they act the same as `Esc'.

VIDEO MODES
       zgv  can	 display  pictures in a	wide variety of	different video	modes.
       While you can kind of get by in	zgv  without  knowing  anything	 about
       video modes, they have a	very direct impact on how the picture appears,
       and it's	important to know why to understand just how zgv works and how
       best to use zgv.

   What	a Video	Mode is
       A  video	 mode  is  essentially a certain way of	displaying dots	on the
       screen. The important aspects of	a video	mode in	zgv are	the number  of
       dots (or	`pixels') that can be shown horizontally and vertically	in the
       mode, and the number of colours that the	mode can handle	simultaneously
       (also called the	`depth'	of the mode).

       In  fact,  this	is  how	a video	mode is	usually	referred to. One might
       talk of a 640x480 256-colour mode, for example;	This  would  have  640
       pixels  from  left  to  right, and 480 from top to bottom, with no more
       than 256	colours	on the screen at once.

       A variant notation widthxheightxdepth is	often used  by	zgv  and  this
       documentation. But here the `depth' is given in bits. This usage, while
       compact,	probably makes more sense to programmers than to anyone	 else.
       Here's a	list showing which `bit	depths'	match which number of colours:

       (These are the only bit depths relevant to zgv.)

       - 4-bit means 16	colours.

       - 8-bit means 256 colours.

       - 15-bit	means 32768 colours.

       - 16-bit	means 65536 colours.

       - 24-bit	means 16777216 colours (over 16	million).

       -  32-bit  means	16777216 colours too (!), since	only 24	of the 32 bits
       are used	for display purposes.

       From the	number of colours available in the latter modes, you  can  see
       why a bit depth notation	is so useful!

       So,  in	the  widthxheightxdepth	 notation, our 640x480 256-colour mode
       would be	640x480x8,  a  16-colour  mode	of  the	 same  size  would  be
       640x480x4,  and	an  equivalent	`true-colour'  (24-bit)	 mode would be
       640x480x24.

       Whenever	you see	a mode referred	to as xxyxz in zgv or in this documen-
       tation, it is always specifying a video mode in this notation.

   Video Mode Issues
       The  obvious  implication  of  differing	video modes is that modes with
       more pixels horizontally	and vertically will have smaller  pixels,  and
       so  be able to show more	of large pictures. The reverse (bigger pixels,
       making small pictures appear large) is not as  important	 a  considera-
       tion,  as  zgv can achieve much the same	effect with scaling (see Scal-
       ing). Using video modes to do it	is faster,  but	 usually  less	conve-
       nient.

       A  more subtle, but much	more important,	implication of differing modes
       is related to the colour	depth. More precisely, it's due	to the differ-
       ing ways	the actual colours shown onscreen are obtained.	In 15, 16, and
       24/32-bit modes,	the colour is specified	`directly'; in 8-bit modes,  a
       pixel's	`colour' is really a number which selects one of 256 different
       colours	to  show.  The	overhead  of   translating   from   8-bit   to
       15/16/24/32-bit	is  relatively	minor,	but  in	the 15/16/24/32-bit to
       8-bit direction,	it's considerable.

       For this	reason,	and since converting from 24-bit  to  15/16/32-bit  is
       very  easy,  when  zgv reads a picture it stores	it in memory in	one of
       two internal formats ---	either as 8-bit, or as 24-bit. See File	Format
       Depths, for discussion on which format zgv uses for which files.

       But  what  difference  does  all	this make when you're using zgv? Well,
       here's the bottom line:

       o A file	loaded as 8-bit	can only ever display in 8-bit	modes.	Trying
       to choose a 15/16/24/32-bit mode	will have no effect.

       o  A  file loaded as 24-bit will	only display in	15/16/24/32-bit	modes,
       unless you have no 15/16/24/32-bit modes, in  which  case  it  will  be
       dithered	 when  it  is  read  in.  (But	the config file	setting	force-
       viewer-8bit can be enabled to force the dithering behaviour.  See  Con-
       figuring	zgv.)

       o  zgv  normally	 remembers  the	last mode you switched to (the initial
       mode is usually 640x480x8), and keeps using that	until you specify  an-
       other  to  use.	However, it will automatically choose the most similar
       15/16/24/32-bit mode for	a 24-bit file if the last mode was 8-bit,  and
       vice versa.

       Confused? Head hurting? Don't worry, it happens to the best of us.  Es-
       pecially	where zgv is concerned.	:-) Just play around with  zgv	for  a
       while,  and  come  back	to this	later on. It may make more sense after
       you've got a feel for what's going on.

   Default Video Mode
       zgv using the last mode you selected is all very	well, but that doesn't
       explain	what happens if	you've not chosen one. What happens is that it
       uses the	default	video mode.

       The default mode	is (unless you change it) the 640x480x8	mode. If  this
       is not available	or has been disabled, zgv defaults to 360x480x8	--- if
       this in turn is not available or	has been disabled, it uses 320x200x8.

   Selecting a Video Mode
       There are many different	video modes supported by svgalib, and zgv lets
       you use most of them. To	do so, it reserves many	different keys for se-
       lecting video modes. These largely fall into four groups:

       - The original VGA modes. These are on the number keys  for  historical
       reasons.	 (The  reason  being, the number keys exactly matched the mode
       numbers used by the old VGAlib.)

       - The first group of SVGA modes.	These are on the function keys `F1' to
       `F10'. These are	generally the first modes to try, if you have them.

       -  The  second  group  of SVGA modes. These are on the shifted function
       keys, here represented as `SF1',	`SF2', and so on. (The	first  two  of
       these  are  also	 available on `F11' and	`F12'.)	Not all	of the shifted
       function	keys are currently used	by zgv.

       - The third group of SVGA modes.	These are again	on unshifted  function
       keys,  but  you	must  press `Tab' before pressing the function key ---
       i.e. press `Tab', let go, then press the	function key. These are	 shown
       below as	`Tab-F1', `Tab-F2', etc.

       There are also the `[' and `]' keys, which select the next smaller/big-
       ger mode. These are especially useful if	you don't  happen  to  have  a
       spare lifetime in which to learn	the `normal' mode-selecting keys. :-)

       So, here's the list of mode-related commands:

       `/'
	      List which key combination selects which video mode.

       `['
	      Select the next smaller (lower-res) mode.

       `]'
	      Select the next bigger (higher-res) mode.	Both these mode-chang-
	      ing keys have the	limits on modes	 selected  that	 auto-mode-fit
	      has (see Auto-mode-fit).

       `0'
	      Select  640x480x4	 mode.	This  emulates	an 8-bit mode. See The
	      Viewer 640x480x4 Mode.

       `5'
	      Select 320x200x8 mode.

       `6'
	      Select 320x240x8 mode.

       `^'
	      Select 320x240x24	mode. (`^' is often on shift-6.)

       `7'
	      Select 320x400x8 mode. This emulates a 640x400 mode. See Virtual
	      Modes.

       `8'
	      Select 360x480x8 mode. This emulates a 720x480 mode. See Virtual
	      Modes.

       `F1'
	      Select 640x480x8 mode.

       `F2'
	      Select 800x600x8 mode.

       `F3'
	      Select 1024x768x8	mode.

       `F4'
	      Select 1280x1024x8 mode.

       `F5'
	      Select 320x200x15	mode.

       `F6'
	      Select 320x200x16	mode.

       `F7'
	      Select 320x200x24	mode.

       `F8'
	      Select 640x480x15	mode.

       `F9'
	      Select 640x480x16	mode.

       `F10'
	      Select 640x480x24	mode.

       `SF1'
       `F11'
	      Select 800x600x15	mode.

       `SF2'
       `F12'
	      Select 800x600x16	mode.

       `SF3'
	      Select 800x600x24	mode.

       `SF4'
	      Select 1024x768x15 mode.

       `SF5'
	      Select 1024x768x16 mode.

       `SF6'
	      Select 1024x768x24 mode.

       `SF7'
	      Select 1280x1024x15 mode.

       `SF8'
	      Select 1280x1024x16 mode.

       `Tab-F1'
	      Select 1280x1024x24 mode.

       `Tab-F2'
	      Select 1152x864x8	mode.

       `Tab-F3'
	      Select 1152x864x15 mode.

       `Tab-F4'
	      Select 1152x864x16 mode.

       `Tab-F5'
	      Select 1152x864x24 mode.

       `Tab-F6'
	      Select 1600x1200x8 mode.

       `Tab-F7'
	      Select 1600x1200x15 mode.

       `Tab-F8'
	      Select 1600x1200x16 mode.

       `Tab-F9'
	      Select 1600x1200x24 mode.

   Special Modes
       Normally, each pixel in the image is written more-or-less  directly  to
       the  screen  from  zgv's	internal copy of the picture (unless zoom mode
       and/or scaling have been	enabled). However, there are three modes where
       zgv does	things differently to make the modes more useful.

       (These  are  mainly intended for	users with only	the original VGA modes
       available.)

   Virtual Modes
       The original VGA	hardware only had one `official' 256-colour mode,  the
       320x200	one.  But it could be reprogrammed to allow other useful modes
       (known as `mode-X' modes) --- the ones svgalib  provides	 are  320x240,
       320x400,	and 360x480.

       These  modes  are  available  on	 all VGA cards.	However, it's possible
       (perhaps	even likely?) that some	non-CRT	displays may not  be  able  to
       cope  with  them.  All monitors should, though, even ordinary VGA moni-
       tors.

       Now, while 320x240 is a nice sensible mode and can  be  used  directly,
       320x400	and 360x480 have very wide pixels. To deal with	this, in these
       latter modes zgv	maps every two pixels horizontally to  one  pixel  on-
       screen.	(Hence	`virtual  modes'  ---  physically they are 320x400 and
       360x480,	but in zgv they	are virtual 640x400 and	720x480	 modes.)  This
       means  that  you	 still	get  a reasonable aspect ratio,	one similar to
       (though not quite the same as) most other modes.

       This raises the question	of how this mapping is done.  The  normal  ap-
       proach is the quickest, but is very crude --- zgv simply	uses the left-
       most pixel of the two, and completely ignores the rightmost one.	But if
       vkludge	mode  is enabled (see Zoom Mode), zgv will average the pixels'
       colours together	and use	the closest match available in	the  picture's
       palette.	 This  usually	gives  a  better  result,  but is considerably
       slower.

   The Viewer 640x480x4	Mode
       As well as the non-standard VGA	modes,	zgv  allows  you  to  use  the
       640x480x4  (16-colour)  VGA mode	as if it were an 8-bit mode. (Pressing
       `0' selects this	mode.) As with the file	selector's 16-colour mode,  it
       can work	either in greyscale (the default) or in	colour.

       `c'
	      If in 640x480x4 mode, toggle between greyscale and colour.

       In  greyscale  mode, the	picture	is displayed using 16 greyscale	levels
       dithered	to give	the appearance of 61. In colour	mode, the  picture  is
       dithered	to eight colours. (It's	difficult to use all 16	colours	effec-
       tively for a colour dither without slowing things down.)

       The greyscale uses an ordered (pattern-based) dither. The  colour  uses
       ordered	dithering  by  default too, which is fast but pretty rough. If
       you'd prefer to sacrifice speed for better dithering, you can switch to
       error-diffused  dithering  by  putting  `dither-16col-fast' in a	config
       file (see Config	Files),	or you can toggle the setting interactively:

       `Alt-c'
	      If in 640x480x4 mode and using colour dithering, toggle  between
	      ordered and error-diffused dither.

       All the features	which work in 8-bit modes work in the 4-bit mode.

   Drawbacks of	15/16-bit Modes
       Since  15 and 16-bit video modes	do not have quite the same representa-
       tion (and depth)	that a file loaded as  24-bit  does,  there  are  some
       drawbacks to using them.	Firstly, the image is converted	to the 2-byte-
       per-pixel format	as it is drawn (see Video Mode Issues, for the	reason
       why  zgv	 works	this  way); and	secondly, the modes actually have less
       colour depth than 256-colour modes.

       In explanation of that last point; although 15 and 16-bit  video	 modes
       show  many  colours onscreen at once, there are fewer colours to	choose
       from.

       A good way to illustrate	this point is by  considering  the  number  of
       greyscales  each	 mode can display. In a	256-colour video mode, only 64
       greys can be shown, since an 18-bit palette is used --- 2^(18/3)	=  64.
       But  with  a  15-bit video mode,	even fewer can be shown	--- 2^(15/3) =
       32.  Because of the way that 16-bit video modes work, which is by  pro-
       viding the green	channel	with twice as much colour depth	(i.e. an extra
       bit), they too can only show 32 greys. Put another way,	2^int(16/3)  =
       32. (Of course, 24/32-bit modes will show all 256 greyscales.)

       One way to gain some illusion of	extra colours in these modes is	to use
       dithering, based	on the colour detail ``below'' the level which can  be
       shown directly:

       `F'
	      Toggle  whether  to use dithering	in 15/16-bit modes. This makes
	      picture display considerably slower when used.

       To enable this by default, put dither-hicol on in a  config  file  (see
       Configuring zgv).

   32-bit Video	Modes
       One  oddity  in mode-land is the	32-bit mode. Like 24-bit modes,	32-bit
       modes can display over 16 million colours. But there are	no obvious ad-
       vantages	 to  using  32-bit modes, at least as far as zgv is concerned.
       So why does it support them?

       Simply put, some	SVGA hardware provides 32-bit modes without  providing
       equivalent 24-bit ones. Hence zgv's support for them.

       That  should  also  explain why zgv treats them the way it does.	Here's
       how it all works:

       o When using zgv, you don't select a 32-bit mode	directly. Instead, you
       select  a  24-bit mode --- and if no matching 24-bit mode exists, but a
       matching	32-bit one does, zgv sneakily uses the 32-bit one behind  your
       back. :-)

       o  zgv's	`choose	most similar mode' code	prefers	24-bit modes to	32-bit
       ones, but similarly, if it has the 32-bit mode without the 24-bit  one,
       it'll take the smoke-and-mirrors	route.

       o  As  an  exception  to	the overall rule, when specifying modes	on the
       command-line or in the config file, you do need to explicitly specify a
       32-bit mode in order to get one.

       For the most part you needn't worry about 32-bit	modes, though; you can
       just ignore them	and think in terms of 8/15/16/24-bit modes and	you'll
       be ok.

   Disabling Video Modes
       In  some	 situations you	might want to disable certain video modes. For
       example,	perhaps	your video card	supports modes which your monitor can-
       not display; clearly you	would want to disable these, as	zgv only knows
       about your video	card.

       (To be fair though, if you have svgalib configured correctly  for  your
       monitor,	 this  should never be a problem. See the libvga.config(5) man
       page for	details.)

       To disable video	modes, you should give appropriate mode-bad entries in
       a  config file (preferably /usr/local/etc/zgv.conf for such system-wide
       configuration). See Config Variables, for details.

       You could also do mode-all-bad then enable a few	modes  with  mode-good
       entries	---  but most cards support so many video modes	that the mode-
       bad approach is usually the right one.

XZGV COMPATIBILITY
       You may well want to skip this section if you don't use xzgv.

       Some time after first writing zgv, I decided to do a  port/rewrite  for
       X, called `xzgv'. Since I started this about six	years after originally
       writing zgv, it's  understandable  that	I  chose  to  do  some	things
       slightly	differently. :-)

       The  main  difference, other than the obvious difference	in appearance,
       is that a few of	the keys used differ. This can be a pain if  you  pri-
       marily  use  xzgv, but use zgv every so often (or vice versa). To avoid
       this problem, zgv supports an  `xzgv-keys'  mode,  enabled  by  putting
       xzgv-keys on in a config	file (see Config Files). This enables an over-
       riding routine which interprets xzgv-like keys to `native' zgv ones ---
       in  practice,  the  effect is of	some xzgv keys being added, overriding
       any conflicting zgv ones.

       So, if you enable xzgv-keys, there are these  differences  in/additions
       to the selector:

       `Space'
	      View a picture file, or if the cursor is on a subdirectory, make
	      that the current directory.  (Like  the  native  `Enter',	 which
	      still works.)

       `-'
	      Untag file.

       `='
	      Tag file.

       `Alt -'
	      (i.e. Alt-minus) Untag all files.

       `Alt ='
	      (i.e. Alt-equals)	Tag all	files.

       `Ctrl-n'
	      Rename file.

       `Ctrl-d'
	      Delete file.

       `q'
       `Ctrl-q'
	      Exit zgv.

       Note that there is no replacement for the usual zgv meaning of `Space';
       that is,	in xzgv-keys mode, there is (currently)	no key which lets  you
       toggle  a  file's tag state. (This will change if/when I	add such a key
       to xzgv.	:-))

       In the viewer, there are	these changes:

       `b'
	      View previous file in dir.

       `Space'
	      View next	file in	dir.

       `Ctrl-Space'
	      Tag current file,	then view next file in dir.

	      (In  short,  `b'/`Space'/`Ctrl-Space'  act   like	  the	native
	      `Backspace'/`Enter'/`Space'.  The	 same mappings also apply when
	      animating	a multiple-image GIF file (see Multiple-image GIF Ani-
	      mation).)

       `Ctrl-w'
	      Exit viewer (i.e.	`close file').

       `N'
	      Restore  the  picture orientation	to normal. This	undoes the ef-
	      fect of any mirrors, flips, and/or rotations. (Like  the	native
	      `Alt-n'.)

       There are some omissions	in the viewer's	xzgv-ish keys:

       -  The `Ctrl' + cursor-key alternatives to `h'/`j'/`k'/`l' don't	exist,
       as these	can't be distinguished from `normal' cursors given the way zgv
       reads keys.

       -    The	  alternative	`Shift'	  +   cursor-key   means   of	paging
       up/down/left/right is similarly missing.

       - Supporting `Ctrl-q' would have	got in the way of  slideshow  pausing,
       so  I decided against it, and omitted `q' from the viewer for some sort
       of consistency.

       - Supporting `Tab' would	break selecting	some video modes, and probably
       would have seemed a bit surreal in zgv anyway. :-)

       That  about wraps it up for the keys... but, of course, there are other
       interface differences.

       One is the way zgv has `flat'  mouse  menus  for	 the  selector/viewer,
       while  xzgv has hierarchical ones. That would be	nice to	replicate, but
       I don't think I'm likely	to.

       A more dramatic difference (IMHO) is the	way moving around the  picture
       with  the  mouse	 works.	 In zgv, you move the screen around `over' the
       picture,	with a fixed amount of mouse movement needed to	cover any pic-
       ture  size.  In	xzgv,  you move	the picture around `under' the window,
       with the	mouse movement needed being proportional to the	 picture  size
       (this  follows  from the	picture	directly mimicking the mouse pointer's
       movement). The most obvious problem here	is that	moving the mouse right
       on  zgv	is like	pressing cursor-right, while doing the same in xzgv is
       like pressing cursor-left. Now, I may eventually	add an option  to  re-
       verse  zgv's  reaction  to mouse	movement, but `fixing' the non-propor-
       tionality without a pointer onscreen might seem awfully strange.

       Hmm. An interesting problem to tackle at	some point, I suppose. :-)

FILE FORMATS
       Picture files are stored	in a variety of	different forms.  These	 forms
       are usually called `file	formats'. zgv supports several.

FILE TYPE IDENTIFICATION
       The  format  a file is in is identified in two different	ways. The file
       selector	(by default) picks filenames to	display	based on  the  `exten-
       sion'  ---  for	instance, if a filename	ends in	.jpg or	.jpeg, zgv as-
       sumes it	is a JPEG. This	way of working is not always right,  but  it's
       much  faster  than  the alternative (reading part of every single file)
       and is usually sufficient. (If it's not,	you can	enable	slower	`magic
       number'-based identification with `Alt-m' (see File Selector Toggles).)

       The  file-reading  code	uses  the format's `magic number' to determine
       file type --- e.g. a JPEG/JFIF file starts with	the  (hex)  bytes  `FF
       D8'.   So  if  you  start zgv with zgv foo, and foo is in a format sup-
       ported by zgv (such as JPEG), the format	will be	figured	 out  and  the
       file loaded even	though the `extension' is absent.

SUPPORTED FILE FORMATS
       zgv supports the	following file formats:

       o  GIF.	Multiple-image	GIFs are treated specially (see	Multiple-image
       GIF Animation).

       o JPEG.

       o PNG.

       o PBM/PGM/PPM, collectively known as `PNM'. This	is a nice simple  for-
       mat used	by pbmplus and netpbm.

       o BMP.

       o TGA (Targa).

       o PCX.

       o  mrf.	Mrf files can be converted to/from PBM with mrftopbm/pbmtomrf,
       and the format is documented in the mrf(5) man page.

       o  PRF.	PRF  is	 an  extension	of  mrf,  similarly   converted	  with
       prftopnm/pnmtoprf, and documented in the	prf(5) man page.

       o XBM (X	bitmap files).

       o  XPM.	zgv  reads  the	 file  /usr/X11R6/lib/X11/rgb.txt to look up X
       colour names. (The location of the file is a compile-time  option;  you
       can edit	config.mk to change it.)

       o TIFF.

       o Photo-CD. This	is only	supported if `PCD_SUPPORT' was defined at com-
       pile-time; by default, PCD support is omitted. PCD files	contain	multi-
       ple image resolutions --- to choose which to view, use `Alt-1' (lowest)
       to `Alt-5' (highest) in the viewer.

       o Xv format thumbnail files. Normally you  won't	 want  to  view	 these
       other  than  in the file	selector, but zgv lets you view	them as	normal
       picture files if	you want. Note that in the  file  selector,  thumbnail
       files  are  indistinguishable from the files they represent (other than
       the .xvpics in the directory's filename)	--- they have the  same	 file-
       names, and thumbnails are their own thumbnails. :-)

FILE FORMAT DEPTHS
       No  matter what bit depth a file	format uses, zgv reads files in	as one
       of two internal formats --- 8-bit (with a palette),  or	24-bit.	  (See
       Video  Mode  Issues,  for why zgv works this way. See What a Video Mode
       is, for more on bit depth.) Usually, zgv	works internally with the low-
       est bit depth which doesn't lose	data. So a 1-bit-per-pixel (mono) file
       is loaded as 8-bit, as are 4-bit	and 8-bit ones,	but a 24-bit  file  is
       loaded as 24-bit.

       For the most part, it's obvious which depth zgv reads a file as,	if you
       know how	the files are stored. But if you don't happen  to  know	 that,
       then  it	can seem like some bizarre black art dependent on the phase of
       the moon. So here's how the differing file formats are read:

       Always 8-bit:
	      GIF, PBM,	PGM, mrf, XBM.

       Always 24-bit:
	      PPM, TIFF.

       24-bit if file is, else 8-bit:
	      JPEG, PNG, BMP, TGA, PCX,	XPM, PRF.

       XPM is really a special case, being a palette-based  format  which  can
       handle  an arbitrary number of colours. (This means XPMs	don't have any
       inherent	`depth'	as such, unlike	most other files --- you couldn't  le-
       gitimately  talk	 of  a `24-bit XPM file'.) XPMs	are loaded as 8-bit if
       they have 256 colours or	less, otherwise	they're	loaded as 24-bit.

       Another special feature of XPM is that, since XPM files	are  primarily
       used  as	 icons,	they are often partly transparent, and usually not de-
       signed to be viewed on a	black background. For this reason, transparent
       pixels  are  shown  as  grey,  and  if  the  XPM	contains less than 256
       colours,	the screen's background	colour is made grey as well.

CONSOLES
       zgv tries to deal sensibly with Linux and FreeBSD's provision for  mul-
       tiple `virtual consoles'. This section covers the details of this.

RUNNING	IN THE BACKGROUND
       Normally	 when  you  do a console switch	away from zgv, it is suspended
       --- nothing at all happens in that zgv process (and it  takes  no  CPU)
       until you switch	back to	it.

       However,	 there	are two	circumstances (both in the file	selector) when
       it makes	sense for zgv to keep running  `in  the	 background',  and  in
       these cases it does keep	running:

       -  When	updating thumbnails. See Updating Thumbnails, for what happens
       in this case.

       - When reading a	picture	file. If it finishes reading it	before you re-
       turn, zgv is suspended as usual.

RUNNING	FROM NON-CONSOLES
       If  it's	 not  run  from	a console tty (and if you are the owner	of the
       currently-selected console), zgv	will  attempt  to  run	on  the	 first
       available  console --- if there are none	free, it will exit with	an er-
       ror message. When it has	to switch consoles like	this, exiting zgv will
       cause  an  automatic  return  to	whichever console was current when the
       program was started. This means you can run  zgv	 reasonably  transpar-
       ently from X, Emacs, etc.

       One  problem  with  this	is that, since zgv uses	`fork()', `zgv -h' and
       other things which give output on stdout	will give  confusing  results;
       the  original zgv process will have exited before the new (replacement)
       zgv process exits. Redirect stdout if you want things  to  make	a  bit
       more  sense --- for example, `zgv -h | less' will do what you'd expect.
       For more	`normal' uses where zgv	doesn't	give any  output,  there's  no
       problem.

       However,	there's	a problem running zgv from X, when it's	invoked	from a
       window manager's	menu. (It works	ok from	an xterm.) The problem is that
       the window manager runs the program with	its stderr attached to the tty
       that the	X server was started from. So zgv will run on the console  you
       started	X from,	but won't switch there.	As luck	would have it, there's
       an easy workaround; when	invoking zgv  from  the	 menu,	just  redirect
       stderr  to  a non-console, such as /dev/null. The details of how	to ar-
       range this vary depending on the	window manager you're using, but  gen-
       erally you'd want a line	ending in something like `Exec zgv 2>/dev/null
       &' to do	this.

       It may seem a bit odd running zgv from X, but it	can be useful  if  you
       have  a	15/16/24/32-bit	card and normally run X	in monochrome or 8-bit
       colour. Or if you just happen to	like zgv. :-)

       Running zgv from	an xterm with a	filename as an	argument  is  probably
       how  you'd  usually do this, though --- e.g. `zgv wibble.jpg'. zgv then
       runs on a free console and switches back	when you exit. If you want  to
       switch  back  to	 X before exiting zgv, it's just a matter of switching
       consoles, as usual. X will be running on	what was the first  free  con-
       sole when it started; often this	is number 7.

USING A	MOUSE
       When mouse support is enabled in	zgv, you can do	almost everything with
       it that you would ordinarily do with the	keyboard.

ENABLING THE MOUSE
       To use the mouse	support	for just one zgv session, start	zgv with some-
       thing  like `zgv	-M'. To	enable it by default, add mouse	on to a	config
       file (see Config	Files).

       zgv uses	svgalib's mouse	configuration; if you have not	set  that  up,
       you  will  probably need	to do so before	zgv's mouse support will work.
       See the libvga.config(5)	man page for details.

       If you find that	the mouse pointer moves	too quickly or too slowly, you
       should change zgv's mouse-scale setting (see Config Variables).

MOUSE MENUS
       The  file  selector  and	 viewer	use the	mouse differently for the most
       part, but they do have one feature in common  ---  clicking  the	 right
       mouse  button  brings up	a menu.	(This is called, not unreasonably, the
       `right-button menu'.)

       All the menu items correspond directly to commands available  from  the
       keyboard.  So  if you are not very familiar with	zgv, it	may be best to
       read all	about those before making extensive use	of the menu.  See  The
       File  Selector,	for file selector commands. See	The Viewer, for	viewer
       commands.

       Some commands are `greyed out' on the menu if they are unavailable. For
       example,	 if  you  are  viewing	an  8-bit  picture  in the viewer, the
       15/16/24-bit modes listed on the	menu will be greyed out.

       To remove the menu from the screen without selecting a command,	either
       click somewhere on the screen not covered by the	menu, or press `Esc'.

MOUSE FUNCS IN THE FILE	SELECTOR
       In  the file selector, the mouse	controls a conventional	mouse pointer.
       In addition to the right	button calling up a menu, there	are these  ac-
       tions you can take with the mouse:

       o Clicking on a file views it.

       o  Clicking  on	the area which shows the current directory prompts you
       for a directory to change to (see Dialog	Boxes).

       o The scrollbar can be used to move along the file list,	in a few  dif-
       ferent ways:

       - Clicking on the scrollbar's arrows moves along	the file list a	column
       at a time.

       - Clicking on either side of the	scrollbar's `slider' (only possible if
       the slider does not fill	the scrollbar, i.e. only possible if there are
       more files than are shown onscreen) moves along the dir	a  page	 at  a
       time.

       -  Clicking  on	the slider and dragging	it moves the file cursor along
       the directory. It works in a slightly unusual way --- if	 you  bear  in
       mind  that  the slider represents the screen `sliding' along the	direc-
       tory listing, and remember that you're moving the cursor	not the	screen
       itself  (at  least  not directly), the way it works may make a bit more
       sense.

       Once you've got used to this, and got used to the menu, you may	wonder
       how  exactly  you're meant to (say) delete a file with the mouse. After
       all, while clicking on it does select it, it also views it! Well, there
       is a way, described below.

       Click  on  the file you want to select, but hold	down the mouse button.
       While holding the button, click the right button. The menu  should  ap-
       pear, and you can let both buttons go. You can then select whatever you
       want to do from the menu.

MOUSE FUNCS IN THE VIEWER
       In the viewer, the mouse	is mainly used for moving around the  picture.
       To  use	it for this, you should	hold down the left button and drag the
       mouse around. It's a little difficult to	explain, but the basic idea is
       that  you drag the screen around	the picture ---	experiment with	it and
       you should get the idea.	No mouse pointer  appears  while  doing	 this,
       which is	a feature not a	bug. :-)

       (If redisplay of	the picture takes a long time, zgv can lag behind your
       mouse movements somewhat. Hopefully this	shouldn't be  too  much	 of  a
       problem.)

       There  is  also	a right-button menu much like the file selector's one,
       and a mouse pointer does	appear when using  that.  Some	notes  on  the
       menu:

       o  Only	a fixed	selection of possible video modes are given as options
       on the menu, to keep things manageable. The others are  only  available
       using the relevant keys.	(See Selecting a Video Mode.)

       o  The  ...smooth  on/off  entries on the menu refer to the vkludge and
       `interpolation in scaling mode' settings	respectively, as should	 hope-
       fully be	clear from the context.

       o When using an 8-bit mode for the viewer, the right-button menu	has to
       allocate	some colours for its display from those	normally used to  show
       the  picture.  This means that the picture might	look a little odd when
       the menu	is onscreen in 8-bit modes. (zgv does try to minimise the dis-
       turbance	by using the closest available colours,	though.)

       o The viewer's menu is disabled in modes	which are less than 480	pixels
       high, since that's the minimum screen height required  to  display  it.
       (This  explains	a  number of the modes omitted from the	menu. If (say)
       320x200x8 was on	there, you'd then be able to switch to the mode	 using
       the  mouse  (of course),	but once there you wouldn't be able to use the
       mouse for anything other	than moving around the picture!)

       Finally,	while viewing an animated GIF file (see	Multiple-image GIF An-
       imation),  you  can right-click to exit the animation, or left-click to
       pause/unpause.

MOUSE DEFICIENCIES
       You can do most things in zgv with the mouse, but you can't  do	every-
       thing.  The main	problem	is that	there are still	a few things which ef-
       fectively ignore	the mouse:

       o When thumbnails are being updated, or a picture being	read,  there's
       no mouse	equivalent of `Esc'.

       o  When	you're prompted	for a directory	name, there's no mouse equiva-
       lent of `Esc' or	`Enter'.

CONFIGURING ZGV
       Many aspects of the way zgv works can be	modified by using a configura-
       tion file.

CONFIG FILES
       A  configuration	 file  lets  you alter aspects of zgv's	behaviour. zgv
       supports	two possible config files  ---	a  system-wide	one,  /usr/lo-
       cal/etc/zgv.conf;  and  one  for	 each  user  in	 their home directory,
       $HOME/.zgvrc. Both are optional.	If $HOME/.zgvrc	exists,	it is used in-
       stead of	/usr/local/etc/zgv.conf.

       Before  describing  the	format of config files,	it may help to give an
       example file:

       # Sample	zgv config file
       # Comment lines begin with `#' and are ignored,
       #  as are blank lines.

       slideshow-randomise on
       # do faster jpeg	thumbnails
       jpeg-index-style	1
       # make tagged files' filenames blue
       col-tagged 0 0 63

       It is a line-based format. Each line (or	rather,	each line which	is not
       a comment line and is not blank)	assigns	a value	to a single predefined
       `variable'. zgv has many	such variables it lets you modify in this way.
       For  example,  the slideshow-randomise option above controls whether or
       not zgv shuffles	the file order in slideshows. If it is given the value
       `on', `yes', or `1' it does; if `off', `no', or `0' it doesn't.

       Most  variables	are of this yes-or-no `boolean'	type. Some others like
       jpeg-index-style	are integers (whole  numbers).	And  there  are	 other
       types, too.

       Since  the  variables  set in a config file have	a direct effect	on how
       zgv works, it can be easier to simply  call  them  `settings'.  Indeed,
       such terminology	is used	on occasion in this documentation.

CONFIG VARIABLE	TYPES
       There are various types of variable:

       - Boolean. These	are on-or-off, yes-or-no variables. Most of zgv's con-
       fig file	variables are of this type. Use	`on', `yes', or	`1' to	enable
       the setting, and	`off', `no', or	`0' to disable.

       -  Integer.  These are whole numbers. The meaning of the	number depends
       on what the variable is used for.

       - Real (floating-point).	This can be a whole number or a	decimal	 frac-
       tion.  Only the contrast	and gamma variables are	of this	type.

       -  RGB. This is a special type used for specifying colours. It consists
       of three	numbers	given one after	the other, in the  order  red,	green,
       blue.   Each  must  be  in  the range 0 to 63 inclusive.	Together these
       specify the colour --- for example, 63 63 63  is	 white,	 32  32	 32  a
       medium grey, and	63 63 0	is yellow.

       -  Video	 mode  (also called just `mode'). This is also a special type,
       used for	specifying a mode. It  uses  the  widthxheightxdepth  notation
       mentioned  elsewhere (see What a	Video Mode is),	but with spaces	and/or
       tabs as separators, so you're actually giving three  separate  numbers.
       For example, 640	480 8 specifies	a 640x480x8 (256-colour) mode.

       -  The  `no args' type. Settings	of this	form aren't variables as such,
       but commands. See Config	Variables, for details of these	 (mode-all-bad
       and mode-all-good).

CONFIG VARIABLES
       Most configuration variables are	directly equivalent to the long	option
       names, and documented elsewhere (see Options). For example, where you'd
       do  --zoom  on  the command-line, you'd do zoom on in a config file. Be
       careful to avoid	quoting	arguments; if you do this in  a	 config	 file,
       you'll get an error. So --viewer-start-mode "800	600 8" on the command-
       line becomes viewer-start-mode 800 600 8	in a config file.

       Now, let's go back to that "most". The options which can	only be	speci-
       fied on the command-line	are the	following, `one-off' options:

       o --help

       o --version

       o --reload-delay

       o --show-tagged

       o --show-dimensions

       o --write-ppm

       Equally,	there are some configuration variables which can only be modi-
       fied in a config	file. Here they	are:

       mode-all-bad
	      (No args;	this is	a command, not a variable as such.) Stops  zgv
	      from  allowing any video modes. This is usually followed by some
	      mode-good	assignments. If	 it  isn't,  zgv  simply  assumes  the
	      320x200x8	mode can be used.

       mode-all-good
	      (No  args;  this is a command, not a variable as such.) This in-
	      structs zgv to assume that all modes can be used,	providing your
	      video card has them. This	is how zgv usually acts.

       mode-bad	modespec
	      Mark  the	specified mode as `bad', so zgv	will not allow it. The
	      `modespec' should	be the width, height, and depth	 separated  by
	      spaces, e.g. `640	480 8'.

       mode-good modespec
	      Mark the specified mode as `good', so zgv	will allow it.

       mouse-kludge
	      (Enabled by default.) If enabled,	throws away any	byte which ap-
	      pears from the mouse device in the first 50ms. This is  to  work
	      around  a	 problem  with my `mouse' (a Logitech trackball) which
	      sends a bogus `M'	byte on	initialisation for no  obvious	reason
	      --- yet input is meant to	be in packets of 3 bytes! Anyway, this
	      fixes it,	and shouldn't break any	other mice, but	 if  you  have
	      inexplicable  mouse  problems you	may want to try	disabling this
	      just to make sure	it's not the problem.

CONFIG FILE BACKWARD COMPATIBILITY
       Many of the config variable names were changed (in an attempt to	ratio-
       nalise  them  to	 some  extent, and behave a bit	more like xzgv)	in zgv
       5.5, when GNU-style long	command-line options were added. However,  be-
       ing  fully  aware  of  the number of complaints I would get if I	made a
       clean break with	the past ;-), almost all the old config	file  variable
       names are still supported (though not on	the command-line).

       Rather  than  document the options again, here's	a simple list of which
       old options map to which	current	ones. (See Options, for	 documentation
       on most.	See Config Variables, for a few	others.)

       allmodesbad
	      =	mode-all-bad

       allmodesgood
	      =	mode-all-good

       automodefit
	      =	auto-mode-fit

       badmode
	      =	mode-bad

       bc_order_rev
	      =	reverse-bc-order

       betterpgm
	      =	pgm-truecol

       black
	      =	col-black

       blockcursor
	      =	block-cursor

       cleartext
	      =	clear-screen-on-exit

       dark
	      =	col-dark

       fakecols
	      =	fake-cols

       fastdither16col
	      =	dither-16col-fast

       force16fs
	      =	force-fs-16col

       forgetoldpos
	      =	fs-ignore-old-pos

       fs16col
	      =	fs-16col-colour-thumbnails

       fs_startmode
	      =	fs-start-mode

       fsmagic
	      =	fs-magic

       goodmode
	      =	mode-good

       gnulitically_correct
	      =	gnulitically-correct

       jpeg24bit
	      =	force-viewer-8bit (sense inverted)

       jpegindexstyle
	      =	jpeg-index-style

       jpegspeed
	      =	jpeg-speed

       light
	      =	col-light

       linetext
	      =	line-text

       medium
	      =	col-medium

       mousekludge
	      =	mouse-kludge

       mousescale
	      =	mouse-scale

       nodelprompt
	      =	delete-single-prompt (sense inverted)

       onefile_progress
	      =	avoid-single-progress (sense inverted)

       pcdres
	      =	pcd-res

       perfectindex
	      =	fs-perfect-cols

       revert
	      =	revert-scale

       revert_orient
	      =	revert-orient

       showxvpicdir
	      =	show-xvpics-dir

       shuffleslideshow
	      =	slideshow-randomise

       slowupdate
	      =	fs-slow-thumbnail-update

       smallfstext
	      =	fs-small-text

       startmode
	      =	viewer-start-mode

       tagged
	      =	col-tagged

       tagtimeout
	      =	slideshow-delay

       thicktext
	      =	fs-thick-text

       viewer16col
	      =	viewer-16col-colour

       xzgvkeys
	      =	xzgv-keys

       zoom_reduce_only
	      =	zoom-reduce-only

       The  old	 fullsel, hicolmodes, and hicontrol options are	no longer sup-
       ported (i.e. zgv's previously-default behaviour for those is now	perma-
       nent), and have no effect other than to give a warning.

RATIONALE
       Here I (RJM) attempt to explain why I did things	the way	I did. This is
       presented in a question-and-answer format of sorts.

WHY YET	ANOTHER	VIEWER?
       Often the simple	answer to this is ``Actually, zgv was here  first  ---
       ask  the	 other	guy.''	This is	true of	any viewer written since 1993,
       anyway.

       Most of the time	though,	this is	phrased	as ``Why not just  use	xv?''.
       That's  a  fair point; xv is quite a good program, and it has some nice
       features. But briefly, here are my problems with	it, the	areas where  I
       personally feel zgv is (at least	arguably) better than xv:

       o xv is shareware. Personally, I	don't think selling picture viewers is
       all that	sensible when things like the Gimp are free.

       o I find	the interface really, really weird. In particular, the	visual
       schnauzer feels rather `bolted on'.

       o  xv  tries  to	be a Swiss-Army	knife of graphics, rather than concen-
       trating on what it really is, a picture viewer. zgv has	some  problems
       in this area too, but it's much closer to the `do one thing well' soft-
       ware tools philosophy (see Opening the software toolbox in  the	textu-
       tils info file).

       I'm  not	 saying	 zgv  is great and xv is terrible, and it's clear that
       many people prefer using	(or have to use) an X picture  viewer  ---  an
       area  where  xv	has no obvious zgv-like	competition (er, not any more;
       see below). But I don't think xv	is even	remotely close	to  being  the
       category-killer	for  picture viewing that some people seem to think it
       is.

       (Update:	Since I	originally wrote the ``no  obvious  zgv-like  competi-
       tion''  line  above,  I've  written  xzgv,  which is a GTK+/Imlib-based
       port/rewrite of zgv for X. What can I say, I liked it so	much  I	 wrote
       the code. :^)

       `Electric  Eyes'	 is  another  alternative to xv, but personally	I find
       that much too xv-like (hence my work on xzgv).)

WHY A TEXINFO MANUAL?
       For years, I maintained a conventional `man page'  for  zgv.  But  over
       time, I realised	just how impossibly confusing the zgv man page had be-
       come.

       So I wanted to rewrite zgv's documentation in a more sensible  way,  in
       some  other  format than	a man page. I wanted an	established, well-sup-
       ported format with structure and	cross-referencing. I felt this made it
       a  choice  between  HTML	 and texinfo. HTML seemed to me	to be a	moving
       target like no other, and not as	well supported on text-only  terminals
       as  Info	(and thus texinfo). When I noticed that	a converter existed to
       convert texinfo to HTML in any case, the	case was closed.

       Don't get me wrong --- I	like man pages.	And even  with	the  excellent
       Texinfo	documentation  and  Emacs'  very helpful Texinfo mode, writing
       texinfo is hardly easy. (Without	Texinfo	mode's node-  and  menu-update
       commands,  I  personally	 would	find  it near-impossible!) But big man
       pages just aren't that good for reference, and this is  made  worse  by
       the relative lack of structure.

WHY ONE-SPACE SENTENCE ENDS?
       The  conventional  way to write texinfo is to follow each sentence with
       two spaces after	the dot	(or whatever ends the sentence).  Many	people
       normally	 write	this  way in a non-texinfo context too.	But a sizeable
       proportion of people normally write text	with only one space after  the
       dot --- and I'm one of them.

       The  Texinfo  documentation gives the impression	that two-space must be
       used; it	says ``it is important to put two spaces at the	 end  of  sen-
       tences in Texinfo documents.'' But the only circumstance	in which spac-
       ing from	the texinfo file is preserved at all (in any sense other  than
       `there  is a space here') is when the texinfo is	converted to Info for-
       mat. So,	in fact, the decision to use two-space depends on how the  au-
       thor  wants  Info  output  to  appear --- this is a subjective decision
       which should be entirely	down to	the preference of the author,  despite
       the Texinfo documentation's attempt to make two-space sound like	an ob-
       jective you-must-do-this	kind of	thing.

       You might wonder	what the problem with using one-space is, then.	 Well,
       `makeinfo'  has to reformat paragraphs, and whenever it needs to	insert
       space at	(what appears to it to be) the end of a	sentence,  it  inserts
       two  spaces.  This  behaviour  cannot be	altered, unlike	in Emacs (sen-
       tence-end-double-space; see Fill	Commands in the	emacs info  file)  and
       GNU  fmt	(-u; see fmt invocation	in the textutils info file). Also, at-
       tempting	to `fix' the output Info with sed doesn't  work	 properly  be-
       cause  the  `tags' used to find nodes quickly are then incorrect. These
       could of	course also be fixed, but this would involve a lot  more  work
       than a simple sed invocation.

       So  realistically,  anyone who writes texinfo with one-space has	to put
       up with the occasional two-space	sentence end being inserted into their
       text ---	worse still, the current `makeinfo' formatting algorithm seems
       to insert two spaces even  after	 abbreviations	(such  as  `e.g.'  and
       `etc.'),	 which	breaks	even  two-space	texinfo. (This is particularly
       ironic, by the way, since two-space partisans' main argument in	favour
       of  the practice	is the way it makes it possible	to tell	the difference
       between abbreviations and the end of a sentence.)

       One last	point may be worth noting; I am	not the	first person to	 write
       texinfo	files  using  one-space. At the	time of	writing, it is used in
       the texinfo documentation for BFD, gdbm,	GTK, IPC,  ld.so,  and	viper,
       and I expect there are instances	I'm not	aware of.

BUGS AND RESTRICTIONS
       All (non-trivial) programs have bugs. Anyone who	denies this...

       - clearly hasn't	written	too many programs.

       - is wrong. ;-)

       It  follows  that zgv, like everything else, always has some bugs. Usu-
       ally these are not serious, or I'd have	fixed  them  before  releasing
       zgv.  Either way, bugs and other	problems with zgv are noted here.

KNOWN BUGS
       - If an XPM file	using a	chars-per-pixel	setting	of two or less uses an
       undefined colour	code in	the image, this	is not reported, and such pix-
       els  are	shown as the background	colour.	(But then, reading XPMs	in the
       three-chars-or-more manner, which does detect undefined colours,	 would
       make it (at best) half as fast.)

       -  If  you have both slideshow looping and shuffling enabled, sometimes
       you can get the same picture twice in a row. This is due	 to  the  last
       picture	chosen	for  one loop round the	pictures being the same	as the
       first of	the next loop.

       - If a GIF file is corrupted in such a way that the decompressed	 image
       has  a  larger number of	pixels in it, the extra	pixels will be ignored
       and no error or warning will be generated.

       - Renaming a file renames the thumbnail too, but	currently  it  ignores
       any ~/.xvpics/_foo_bar/baz thumbnail.

       -  If  you  use the old line-based text,	or use the `fs-thick-text' op-
       tion, some of the text in the right-button menus	slightly overruns  the
       `buttons' they're on, which is harmless but doesn't look	very nice.

       - If you	look up	`joe code' in a	dictionary, it says ``see zgv''. :-)

SUBOPTIMAL FEATURES
       - You don't currently get a progress report when	TIFFs are being	read.

       -  Some	of the things the change-picture viewer	keys do	when viewing a
       slideshow are pretty stupid (`^P' and `^N' suck,	for example).

       - For multiple-image GIFs, the progress indicator  only	indicates  how
       much  of	 the  current image has	been read, rather than how much	of the
       file as a whole has been. There's  some	precedent  for	this  approach
       (e.g. the Gimp),	but it's not terribly elegant.

       - Corrupt JPEG or PNG data warnings are not reported by zgv.

       - In the	640x480x4 mode in the viewer, when scaling a picture where the
       scaled picture remains narrower than the	screen's width,	the background
       to  the	left  and right	of the picture is filled in with the picture's
       background colour (though you'll	only be	able to	see this if  the  pic-
       ture's  background  colour  isn't  black).  This	 is harmless but looks
       strange.

       - The help pages	only list a few	of the keys.

RESTRICTIONS
       - Most GIF89a extension blocks  are  ignored.  (The  exception  is  the
       Graphics	 Control  Block, used for delay	times and transparency in ani-
       mated GIFs.)

       - XPM files with	more than 256 colours are shown	 with  a  black	 back-
       ground  (not the	grey background	usually	used for XPMs),	and those with
       exactly 256 colours are shown  with  the	 background  being  the	 first
       colour specified	in the file.

REPORTING BUGS
       If  you	find  zgv  does	 something wrong, which	you suspect might be a
       fault of	some sort (a bug) in the program, it is	best to	report it as I
       may  not	 be aware of the problem. (But first, check it is not a	`known
       bug'.  See Known	Bugs. It is not	usually	helpful	to report a bug	I  al-
       ready know about.)

       zgv uses	various	libraries; if you find a problem, it could be a	bug in
       one of them. This is not	an attempt at buck-passing :-),	rather concern
       that bugs should	be reported to the people best able to fix them.

       Most bugs will turn out to be in	zgv itself, but	in the past, some dis-
       play bugs have turned out to be bugs in svgalib.	If  it	is  a  display
       bug,  try  zgv on other machines	if you can, and	try other svgalib pro-
       grams which use the same	 video	mode(s).  (Svgalib's  example  program
       `vgatest'  can be useful	for this; see its man page for details.)  This
       should help you determine whether it is an svgalib bug or not. (If  you
       really can't figure out whether it's a bug in zgv or in svgalib,	it may
       be best to report it as a possible bug in both.)

       It is important to include as much detail in a bug report as  you  can.
       Here are	some details you should	include:

       o The version of	zgv you	are running (`zgv --version' reports this).

       o The version of	svgalib	(try `ls /usr/lib/libvga.*' for	this).

       o  What your machine's (S)VGA card is described as, and (generally more
       useful) what svgalib reports it to be. zgv suppresses this report,  but
       most other svgalib programs (`vgatest' which comes with svgalib being a
       simple example) will report it when they	start up.

       o A description of the bug --- what effects it has,  the	 circumstances
       it occurs in, and so on.	Does it	only happen for	certain	types of file?
       Only when in 8-bit modes? Only when avoid-single-progress  is  enabled?
       Even `irrelevant' details can sometimes be useful.

       o  Finally, if you are a	programmer and believe you have	managed	to fix
       the bug yourself, patches are gratefully	accepted. :-) You should  gen-
       erate the patch using `diff -c' or (preferably) `diff -u'.

       So, if you think	you've found a bug in zgv, report it by	emailing me at
       <rus@svgalib.org>.

REPORTING DOCUMENTATION	BUGS
       Bugs in the documentation can sometimes cause as	much trouble  as  bugs
       in  the	program;  if you notice	a problem in the documentation,	it's a
       good idea to report it.

       For reports of documentation bugs, you should include these details:

       o The version of	zgv the	documentation is for.

       o If it is a problem in one  specific  section  of  the	documentation,
       specify	which  part  it	is (by this I mean the heading it comes	under;
       texinfophiles should read this as `the node name' :-)).

       o The format of the documentation you saw the problem  in  (e.g.	 info,
       man page, HTML).

       o A description of the problem.

FUTURE CHANGES
       See  Reporting  Bugs,  for  details of where to send the	bug report.  I
       have given up on	the apparently naive notion  that  zgv	will  ever  be
       `finished'.  Every time I think that, some other	idea for a new feature
       pops into my head (or is	forced there by	someone	else).

       If you want to suggest a	feature	you'd like in zgv, or a	change	to  an
       existing	feature, contact me at <rus@svgalib.org>.

       Here is a list of features and/or changes which may hopefully be	imple-
       mented in future, in approximate	priority order.	(This is updated  less
       often  than zgv's TODO file, so you should check	that too if you're in-
       terested	in this	stuff.)

       o Fix the progress indicator problem with multiple-image	GIFs.

       o Mouse support isn't really finished --- the  goto-dir	dialog	should
       have  ok/cancel buttons,	and currently you can't	interrupt file loading
       and thumbnail updates. The latter two would need	a custom  mouse	 event
       handler	temporarily  installed,	 so  that  we  could  avoid losing any
       clicks.	Actually it might not be too bad an idea to always use a  cus-
       tom handler; that would be easier. After	all, on	a slow machine you can
       already lose clicks during a file-selector screen redraw!

       o File move should probably delete any existing thumbnail for the  file
       if the file itself is moved successfully.

AUTHOR
       Russell	Marks  <rus@svgalib.org>  and others; see the section ACKNOWL-
       EDGEMENTS for details.

SEE ALSO
       xzgv(1),	 cjpeg(1),  djpeg(1),  pbm(5),	pgm(5),	 ppm(5),  mrf(5),  sv-
       galib(7), libvga.config(5)

Version	5.9		       28th January 2005			ZGV(1)

NAME | SYNOPSIS | DESCRIPTION | ACKNOWLEDGEMENTS | OPTIONS | ONLINE HELP | THE FILE SELECTOR | EXITING ZGV | THUMBNAILS | SCREEN LAYOUT | MOVING AROUND THE LIST | VIEWING A FILE | DIALOG BOXES | TAGGING | RENAMING A FILE | CHANGING DIRECTORY | CHANGING THE SORTING ORDER | FILE SELECTOR TOGGLES | OTHER FILE SEL COMMANDS | SHOWING MORE FILES | 16-COLOUR FILE SELECTOR | THE VIEWER | EXITING THE VIEWER | BIG PICTURES | SCALING | MIRROR AND ROTATE | BRIGHTNESS AND CONTRAST | GAMMA ADJUSTMENT | INCREASED GREYSCALES | CHANGING PICTURE | FILE DETAILS | PAUSING SLIDESHOWS | MULTIPLE-IMAGE GIF ANIMATION | VIDEO MODES | XZGV COMPATIBILITY | FILE FORMATS | FILE TYPE IDENTIFICATION | SUPPORTED FILE FORMATS | FILE FORMAT DEPTHS | CONSOLES | RUNNING IN THE BACKGROUND | RUNNING FROM NON-CONSOLES | USING A MOUSE | ENABLING THE MOUSE | MOUSE MENUS | MOUSE FUNCS IN THE FILE SELECTOR | MOUSE FUNCS IN THE VIEWER | MOUSE DEFICIENCIES | CONFIGURING ZGV | CONFIG FILES | CONFIG VARIABLE TYPES | CONFIG VARIABLES | CONFIG FILE BACKWARD COMPATIBILITY | RATIONALE | WHY YET ANOTHER VIEWER? | WHY A TEXINFO MANUAL? | WHY ONE-SPACE SENTENCE ENDS? | BUGS AND RESTRICTIONS | KNOWN BUGS | SUBOPTIMAL FEATURES | RESTRICTIONS | REPORTING BUGS | REPORTING DOCUMENTATION BUGS | FUTURE CHANGES | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zgv&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help