Provided by: zgv_5.9-4_amd64 bug


       zgv - picture viewer for VGA/SVGA displays


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


       (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 displays. 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 supported 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 Updating 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 display 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 introductions 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.


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

       Matan    Ziv-Av   added   multiple-image   animated   GIF   support,   Photo-CD   support,
       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 generation.

       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, suggestions, 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 CompuServe Incorporated.
       GIF(sm) is a Service Mark property of CompuServe Incorporated.''


       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 section 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-letter  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

       Here's what the options do:

              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

              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  resolution
              higher than 800x600 if possible.

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

              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.

              Use  a  blocky  outline  cursor  in the selector, which is rather unsubtle but more

       `--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 contrast by default.

              (Normally enabled, use e.g. `--centre=off' to  disable.)  By  default  zgv  centres
              pictures  smaller  than  the screen, in whichever dimensions they are smaller. This
              setting gives you a way to disable this, so that pictures always start in the  top-
              Clear  the  screen  on  exit.  (Normally,  zgv  leaves the original screen contents

       `--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 settings 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.

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

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

              (Normally enabled, use `--dither-16col-fast=off' to disable.) By default, zgv  uses
              a  (reasonably  fast)  ordered  dither  when  displaying 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).

              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.

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

              Force the use of the 640x480 16-colour mode for the selector.

              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.

              Use  low-quality  colour thumbnail pictures when the file selector is using 640x480
              16-colour mode. Normally zgv uses  higher-quality  monochrome  thumbnails  in  this

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

              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 discussion of the tradeoffs involved.

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

              `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.

              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.

              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.)

              (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  adjustment.  The  default  is  1.0,  i.e.  no

              GNU  has  POSIXLY_CORRECT  for  compatibility with silly POSIX misfeatures, and zgv

              Display a list of options and a terse description of what the options do.

              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 thumbnails; `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.

              Draw text by drawing lines rather than using bitmap fonts. This looks worse but  is

              Enable  mouse  support  in zgv. /dev/mouse must be (usually a symlink 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. (However, 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.)

              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 seconds 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. :-)

              Normally, any brightness modification  is  applied  after  applying  any  contrast.
              Enabling this reverses the order.

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

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

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

              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'.

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

              Show any .xvpics directories so that the thumbnails can be viewed even if the files
              they referred to no longer exist. (However, 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.

              Loop in slideshows `forever' (or rather, until you exit).

              Randomise picture order in slideshows. Due to the shuffling approach  taken,  there
              will be no repeats or omissions.

              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

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

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

              Show version number.

              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.

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

              Enable zoom mode, which resizes the picture to fit the screen.  See Zoom Mode.

              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

       If started with `zgv file file2 ...' --- i.e. with more than one filename --- 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

       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 config files --- the syntax is `--option=state', where state
       is  `on'/`y'/`yes'/`1' to enable the option, or `off'/`n'/`no'/`0' to disable it. The most
       useful thing about this is that it allows you to disable  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 (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.


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


       Exiting zgv can be achieved two ways:

              Quit zgv normally.

              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.)


       (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 subdirectory .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 thumbnails, or where the thumbnails seem
       to be out of date, you should press `u'.

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

              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 prefixes 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 unfortunately necessary).  The  screen  is
              redrawn when the current thumbnail has been dealt with.

              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 consoles,  and
              you can press `Esc' to abort.

              Create thumbnails for subdirectories. Don't confuse this with the recursive update;
              this generates thumbnails for the directories  themselves,  not  the  files  within
              them.  (Most  people  probably  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 represent. 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 thumbnail 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/wibble.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.  Unfortunately, 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


       The  file  selector  is  simply  a  list  of  subdirectories and filenames, along with any
       thumbnails that exist for them. The list is in asciibetical  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
       filenames  are  truncated  to fit; three dots indicate where this has happened. (See Other
       File Sel Commands, for how to display the full filename.)

       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

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


       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 `special' 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

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

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

       `Cursor Left'
              Move left one column.

       `Cursor Right'
              Move right one column.

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

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

              Move the cursor to the start of the list.

              Move the cursor to the end of the list.

              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

              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
              directories), in which case it has no effect.


       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).

              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.


       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'
              Move the cursor left. (An underline character shows the cursor position.)

       `Cursor Right'
              Move the cursor right.

              Move the cursor to the start of the line.

              Move the cursor to the end of the line.

              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.

              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 the char the cursor is on.


       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 commands 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

       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.

              Tag file.

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

              Tag all files.

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

              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 Commands).

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

              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 Changing 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

       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 subdirectory, 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.

              Copy  tagged  files  (or  the  current file) to a given directory. zgv asks for the
              destination directory using a dialog (see Dialog 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.

              Move tagged files (or the current file) similarly.

              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.


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

              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.


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

       There is an alternative though:

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

              Go  to a specified directory. zgv asks for the destination directory 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. :-)


       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

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

              Sort by name. This is the default.

              Sort by size. The biggest files are listed last.

              Sort by last-modified date/time. The newest files are listed last.

              Sort by extension.


       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).

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

              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.

              Toggle shuffling (randomising) of slideshows. See Slideshows.

              Toggle looping in slideshows. See Slideshows.

              Toggle use of `magic numbers' (identifiers at the start of a file)  to  pick  which
              files  in  a  directory  to list in the selector. 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.

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


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

              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.

              Show  the  number  of  (picture)  files in the current directory, and the number of
              tagged files (see Tagging).

              Rescan the directory contents, and redraw the screen.

              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


       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.)

              Select 640x480 mode. This is the default.

              Select 800x600 mode.

              Select 1024x768 mode.

              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 example, 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.


       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 --- thumbnails (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

       (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.)


       When  a picture is being shown onscreen, you're in the viewer. This section describes what
       you can do while viewing the picture.


       Exiting the viewer is simple:

              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.


       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-

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

       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'
              Move up 100 pixels. `k' and `q' move up 10 pixels.

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

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

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

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

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

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

              Move right (nearly) a screenful.

              Move to the top-left of the picture.

              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 (relatively) 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.

              Toggle zoom mode.

              When in zoom mode, only reduce pictures to fit.  This  can  be  useful  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. :-)

              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.

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

       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 automatically 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.

              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 particular,  no  320x200
       mode is ever chosen, nor is 320x400x8. These exceptions 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.


       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 picture.

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

       (It  may  seem  odd  saying  e.g.  `twice  as wide/high' rather than `twice the size', but
       technically `twice the size' would be referring to scaling 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:

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

              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

              Decrease the ratio by subtracting one.

              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

       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.

              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


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

              `Mirror' the picture (flip it horizontally).

              `Flip' the picture (flip it vertically).

              Rotate the picture 90 degrees clockwise.

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

              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 orientation between pictures, so that the new picture is mirrored,
       flipped, and/or rotated in the same way. Here are two of the ways:

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

              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 Configuring zgv).


       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

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

              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.


       Ah yes, gamma. What fun. The basic problem is this --- differing displays  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 appropriate. 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  probability  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:

              Set gamma adjustment to 1.0, i.e. no adjustment. This is the default setting.

              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.

              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.

              Set  gamma  adjustment  to  its  initial value, as specified by a `-G' command-line
              option (see Options) or gamma  config  file  setting  (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:

              Decrease gamma adjustment (divide it by 1.05).

              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.


       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 pictures.

       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 otherwise, 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:

              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 Configuring zgv).


       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.)

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

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

              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

              View  previous  file  in  dir,  with  progress  indicator. (In slideshow, acts like

              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.


       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.


       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 temporarily stop terminal output:

              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.

              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


       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 single 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 specified 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.)

              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:

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

              Pause (or unpause) the animation.

              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 Picture). Otherwise they act the same as `Esc'.


       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

       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 documentation, 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  consideration,  as  zgv  can  achieve much the same effect with scaling (see
       Scaling). Using video modes to do it is faster, but usually less convenient.

       A more subtle, but much more important, implication of differing modes is related  to  the
       colour  depth.  More  precisely,  it's  due to the differing 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

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

       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
       Configuring 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/bigger 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-changing keys have the
              limits on modes selected that auto-mode-fit has (see Auto-mode-fit).

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

              Select 320x200x8 mode.

              Select 320x240x8 mode.

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

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

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

              Select 640x480x8 mode.

              Select 800x600x8 mode.

              Select 1024x768x8 mode.

              Select 1280x1024x8 mode.

              Select 320x200x15 mode.

              Select 320x200x16 mode.

              Select 320x200x24 mode.

              Select 640x480x15 mode.

              Select 640x480x16 mode.

              Select 640x480x24 mode.

              Select 800x600x15 mode.

              Select 800x600x16 mode.

              Select 800x600x24 mode.

              Select 1024x768x15 mode.

              Select 1024x768x16 mode.

              Select 1024x768x24 mode.

              Select 1280x1024x15 mode.

              Select 1280x1024x16 mode.

              Select 1280x1024x24 mode.

              Select 1152x864x8 mode.

              Select 1152x864x15 mode.

              Select 1152x864x16 mode.

              Select 1152x864x24 mode.

              Select 1600x1200x8 mode.

              Select 1600x1200x15 mode.

              Select 1600x1200x16 mode.

              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

       (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 monitors.

       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 considerably slower.

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

              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 effectively for a colour  dither  without  slowing  things

       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:

              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 representation (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 providing
       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:

              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 cannot 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  /etc/zgv.conf  for such system-wide configuration). See Config Variables, for

       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.


       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 primarily 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  overriding
       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:

              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.

              Rename file.

              Delete file.

              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:

              View previous file in dir.

              View next file in dir.

              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 Animation).)

              Exit viewer (i.e. `close file').

              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

       - 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

       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 picture 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-proportionality
       without a pointer onscreen might seem awfully strange.

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


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


       The  format  a  file  is  in  is  identified  in two different ways. The file selector (by
       default) picks filenames to display based on  the  `extension'  ---  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 supported by zgv (such as JPEG), the format will be figured out and the
       file loaded even though the `extension' is absent.


       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 format 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 to change it.)

       o TIFF.

       o  Photo-CD.  This  is  only  supported  if  `PCD_SUPPORT' was defined at compile-time; by
       default, PCD support is omitted. PCD files  contain  multiple  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  filenames,  and
       thumbnails are their own thumbnails. :-)


       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 lowest 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, transparent pixels are shown as grey, and if the XPM contains  less  than
       256 colours, the screen's background colour is made grey as well.


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


       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.


       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 transparently from X, Emacs,

       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 console when it
       started; often this is number 7.


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


       To use the mouse support for just one zgv session, start zgv with something 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

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


       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'.


       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 different 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 directory 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.


       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 hopefully 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 disturbance 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.


       You can do most things in zgv with the mouse,  but  you  can't  do  everything.  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  equivalent  of  `Esc'  or


       Many aspects of the way zgv works can be modified by using a configuration file.


       A  configuration file lets you alter aspects of zgv's behaviour. zgv supports two possible
       config files --- a system-wide one, /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

       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.


       There are various types of variable:

       -  Boolean.  These are on-or-off, yes-or-no variables. Most of zgv's config 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  fraction.   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).


       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 specified 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 modified in a config
       file. Here they are:

              (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.

              (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.

              (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.


       Many of the config variable names were changed (in an attempt to rationalise 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.)

              = mode-all-bad

              = mode-all-good

              = auto-mode-fit

              = mode-bad

              = reverse-bc-order

              = pgm-truecol

              = col-black

              = block-cursor

              = clear-screen-on-exit

              = col-dark

              = fake-cols

              = dither-16col-fast

              = force-fs-16col

              = fs-ignore-old-pos

              = fs-16col-colour-thumbnails

              = fs-start-mode

              = fs-magic

              = mode-good

              = gnulitically-correct

              = force-viewer-8bit (sense inverted)

              = jpeg-index-style

              = jpeg-speed

              = col-light

              = line-text

              = col-medium

              = mouse-kludge

              = mouse-scale

              = delete-single-prompt (sense inverted)

              = avoid-single-progress (sense inverted)

              = pcd-res

              = fs-perfect-cols

              = revert-scale

              = revert-orient

              = show-xvpics-dir

              = slideshow-randomise

              = fs-slow-thumbnail-update

              = fs-small-text

              = viewer-start-mode

              = col-tagged

              = slideshow-delay

              = fs-thick-text

              = viewer-16col-colour

              = xzgv-keys

              = zoom-reduce-only

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


       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.


       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

       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 concentrating 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' software tools philosophy (see Opening the software toolbox in
       the textutils 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 competition'' 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).)


       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-supported 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.


       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 sentences in  Texinfo  documents.''  But  the
       only circumstance in which spacing 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  format.  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  (sentence-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,, and viper, and I expect there are instances I'm not aware of.


       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. Usually these are not
       serious, or I'd have fixed them before releasing zgv.  Either way, bugs and other problems
       with zgv are noted here.


       -  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  pixels  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

       -  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''. :-)


       - 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  picture's  background  colour isn't black). This is harmless but looks

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


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

       -  XPM  files  with  more than 256 colours are shown with a black background (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.


       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  display  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 programs 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

       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 generate 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 <>.


       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.


       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 <>.

       Here is a list of features and/or changes which may hopefully be implemented 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  custom
       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.


       Russell Marks <> and others; see the section ACKNOWLEDGEMENTS for details.


       xzgv(1), cjpeg(1), djpeg(1), pbm(5), pgm(5), ppm(5), mrf(5), svgalib(7), libvga.config(5)