zgv man page on aLinux

Man page or keyword search:  
man Server   7435 pages
apropos Keyword Search (all sections)
Output format
aLinux logo
[printable version]

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
       appears 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
       addition, 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-
	      image  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
	      unsubtle 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
	      default zgv centres pictures smaller than the screen, in	which‐
	      ever  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
	      inverted. 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
	      returning to it later. (This mechanism only applies when	chang‐
	      ing  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
	      directories 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
	      details of precisely what this means.  The  specified  depth  is
	      actually	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
	      option  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
	      between 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
	      approach 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
	      image-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
	      intact.

       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
       selector, 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
       advance, and are stored as files in their own right in (usually) a sub‐
       directory .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
       recursive update can take some time!

       `u'
	      Create thumbnails for any	 files	which  don't  have  them,  and
	      update  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
	      update. 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
       selector colours. The disturbance to the thumbnails  should  be	barely
       noticeable.

       (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.
       (Experienced 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
	      order).  If  there are none for which this is the case, it moves
	      to the last file --- unless there are no	files  (just  directo‐
	      ries), 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
       described 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
	      position. 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
	      `Enter' 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
	      remain 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
	      exists.

	      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
       Options) 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
	      extension (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
	      using just the keyboard. In such a situation the	mouse  pointer
	      can  be  a bit annoying. This command lets you disable the mouse
	      completely 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
       automatic 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
       example,	 the  cursors  scroll around in steps of 100 scaled-up pixels,
       even if this means moving a fraction of a pixel in  the	original  pic‐
       ture.

       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
       increased 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
	      occasionally 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
	      effect 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
       already	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
       determined.

       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
	      default 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 :-))
       intended 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
       increase	 the  apparent colour depth a little. The trick zgv uses is to
       increase 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
       selector 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
       always 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
       another 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
	      resume.  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
	      either.  :-)) 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
       another 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.
       Especially  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
       selecting 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
       onscreen. (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
       approach is the quickest, but is very crude ---	zgv  simply  uses  the
       leftmost	 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 consider‐
       ably 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
       advantages 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
	      effect 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
       reverse 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
       assumes 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
       legitimately 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
       designed to be viewed on a black background. For this reason, transpar‐
       ent 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
       return, 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
       error  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 trans‐
       parently 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
       arrange	this  vary  depending  on the window manager you're using, but
       generally 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
       actions 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
       appear, 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
       Animation), 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
       effectively 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/local/etc/zgv.conf; and one for each user in their home directory,
       $HOME/.zgvrc.  Both  are	 optional.  If $HOME/.zgvrc exists, it is used
       instead 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
	      instructs	 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
	      appears 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,
       being 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
       become.

       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
       author 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
       objective 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,
       attempting  to  `fix'  the  output  Info with sed doesn't work properly
       because 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'
       option,	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
       already 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
       interested 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),
       svgalib(7), libvga.config(5)

Version 5.9		       28th January 2005			ZGV(1)
[top]

List of man pages available for aLinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net