Manual Reference Pages - ZGV (1)
zgv - picture viewer for VGA/SVGA displays
zgv [options] [start-dir | file [file2 ...]]
(NB: This man page is automagically generated from zgvs
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 zgvs 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 youve 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
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
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 its 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 whove 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
The Graphics Interchange Format(c) is the Copyright property of
CompuServe Incorporated. GIF(sm) is a Service Mark property of
Normally youd 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 youre 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
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
Heres 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 like.
Automatically switch modes to suit image size.
When choosing an auto-mode-fit mode, add diff to each modes
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.
Dont show progress indicator when loading a single file from the
Try to use a black (or nearest-to-black) background when in 8-bit modes.
This can be quite nice for consistencys 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 obvious.
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-left.
Clear the screen on exit. (Normally, zgv leaves the original screen
--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.
Specify how much to multiply colour values by to change contrast
(default 1.0). zgv multiplies each colours 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 pictures colours inverted. Contrast is applied before
brightness by default.
(Normally enabled, use --delete-single-prompt=off to disable.) If
disabled, dont prompt for confirmation when deleting a single file.
(Normally enabled, use --delete-tagged-prompt=off to disable.)
If disabled, dont prompt for confirmation when deleting all tagged
(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,
dont 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 situation.
Dont 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
Dont 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 dont 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 youd like to see more of
the filename without having to press :.
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
(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 wont be able to fill the screen in
modes it doesnt natively support, in either case.
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 adjustment.
GNU has POSIXLY_CORRECT for compatibility with silly POSIX
misfeatures, and zgv has...
Display a list of options and a terse description of what the options
When loading a single file from the command-line, ignore (some) errors.
Only meaningful for PNG currently.
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.
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 faster.
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 svgalibs config file libvga.config; see the
man page for that for details.
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.
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 VGAs 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.)
If seconds is positive, then any picture displayed is re-read
and redisplayed (without clearing the screen first) every
seconds seconds. If its 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,
youre 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
(Normally enabled, use --revert-scale=off to disable.) If
disabled, scaling is retained between pictures.
(Normally enabled, use --scrollbar=off to disable.) If disabled,
dont 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, its
usually easier to simply start zgv in the .xvpics dir.)
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.
Specify the video mode zgv should start off using for the viewer. The
default is generally 640x480x8, but its actually a bit more complicated
than that (see Default Video Mode). The modespec should be the
width, height, and depth in quotes, e.g. "640 480 8". See Video
Modes, for details of precisely what this means.
(Normally enabled, use --visual=off to disable.) If disabled, no
thumbnails are shown.
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.)
Youre usually better off using a dedicated image-converting program,
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 interest.
If started with zgv start-dir, zgv starts up with the usual
file selector, but with the current directory being the one specified.
Settings which are either on or off (boolean) are, as you might expect,
enabled by using e.g. -z or --zoom. However, theres an
alternative long-option form for setting these, resembling how theyre
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 cant 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
Gives online help. This lists some of the most commonly-used keypresses
in the current context.
In the viewer, you can also get a list of which key combinations select
which video modes. See Selecting a Video Mode.
THE FILE SELECTOR
Usually, on starting up zgv, you will enter the file selector, which
lets you pick files to view (among other things). This lists the
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
(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 its 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. zgvs thumbnails are also compatible with the Gimp, and
If no thumbnail exists for a file or directory, a small document or
folder graphic appears instead.
While thumbnails can be made relatively quickly, its 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
zgv never creates/updates thumbnails without you telling it to. So, if
you enter a directory where the picture files dont have any thumbnails,
or where the thumbnails seem to be out of date, you should press
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 dont 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 directorys 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 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
Create thumbnails for subdirectories. Dont confuse this with the
recursive update; this generates thumbnails for the directories
themselves, not the files within them. (Most people probably
wont want to bother with these, as theyre 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.
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 isnt
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
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 cant use .xvpics. It will put the thumbnail in
$HOME/.xvpics/_foo_bar_baz/wibble.jpg, creating directories as
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
The thumbnails used in zgv require 256 colours to display.
Unfortunately, the rest of zgvs 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
(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 selectors five colours can
be (and are) separate from the thumbnail colours.
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
The list is often larger than can fit on the screen at once. If this is
the case, only part is shown at a time, but you can move around the list
with the cursor keys and the like.
The colours used for the file selector can be changed, if you dislike
the defaults (see Configuring zgv).
MOVING AROUND THE LIST
The cursor in zgv is (normally) shown as a raised entry in the list.
The cursor has two main functions:
It selects a file for view, tag etc. commands to operate on.
It determines which part of the list is shown, as the part of the list
shown onscreen always contains the cursor.
There are many commands for moving the cursor. In summary, most
special keys like the cursors do what youd 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
Move up. Moving up from a topmost entry moves to the bottom of the
Move down. Moving down from a bottommost entry moves to the top of the
Move left one column.
Move right one column.
Move the cursor back (nearly) a page.
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 different.
If no files start with the specified character, it moves to the first
file which starts with a later char (in asciibetical order). If there
are none for which this is the case, it moves to the last file ---
unless there are no files (just directories), in which case it has no
VIEWING A FILE
There are two ways to view files from the file selector. The usual way
is to press Enter when youve 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
Move the cursor left. (An underline character shows the cursor
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 youd prefer zgv
to use different colours.)
Tag and Untag Commands
There are several ways to tag or untag files. The ones which work on
individual files also move the cursor forward one place afterwards, to
make tagging or untagging multiple files easier.
As elsewhere in zgv, the case of the keys is significant --- the t
(unshifted t) command has quite a different effect to that of
T (shifted t).
There is also a command available in the viewer to tag the
currently-viewed file. See Changing Picture, for details.
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
Tag all files.
Untag all files. This is on N rather than U for consistency.
Toggle the tag status of the file --- if its tagged, untag it; if its
untagged, tag it.
To see how many files are tagged, use Alt-f (see Other File Sel
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 viewers 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).
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,
theres obviously no need to specify any directory :-) but youre
prompted before deletion starts (unless this is disabled,
see Configuring zgv). It also deletes thumbnails, for those files
which have them.
RENAMING A FILE
As well as copying/moving files, you can rename them:
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).)
Its 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
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 dirs name into
(see Dialog Boxes), and moves to that directory if it exists.
If the directory turns out to be unreadable --- i.e. you do not have
permission to read it --- zgv resorts to going to your home directory.
(This is actually a general mechanism in zgv, but this command is the
most likely trigger of it.) If that in turn is unreadable, zgv gives up
in disgust and exits. :-)
CHANGING THE SORTING ORDER
Normally, the files are listed in asciibetical order by name. However,
you can instead have the file list sorted by size, last-modified
date/time, or by extension (the file type).
(Only the order of files can be altered; directories are always listed
first, and always in name order.)
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.
FILE SELECTOR TOGGLES
Various aspects of the file selectors 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
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 files extension (see File Type
Identification, which is much faster but wont catch e.g. files without
If the file selector is running in 16-colour mode (it usually doesnt
unless zgv has no choice --- see 16-colour File Selector), toggle
between greyscale (default) and colour thumbnails.
OTHER FILE SEL COMMANDS
There are some other commands in the file selector which dont 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 files
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
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 youre currently using just the keyboard. In such
a situation the mouse pointer can be a bit annoying. This command lets
you disable the mouse completely for the current zgv process.
SHOWING MORE FILES
The file selector normally runs at a relatively low resolution
(640x480), meaning it can only show 20 thumbnails at once. This keeps
the selector running at a reasonable speed even on slow machines.
If you have a faster machine, however, and your video card has
256-colour modes with higher resolutions than 640x480 (see Video
Modes), you may want to see more thumbnails onscreen at once.
(zgv tends not to look as right in such modes as it does in the usual
640x480, but apart from that its 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, youd 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 viewers
mode-good, mode-bad, etc. settings. See Config
Finally, if you have no 640x480 256-colour mode, or if
force-fs-16col has been set, the 640x480 16-colour mode is all
that is available.
16-COLOUR FILE SELECTOR
The file selector normally operates in a 256-colour mode (by default,
the 640x480 one). However, the original VGA cards didnt have this mode,
and SVGA cards not supported by svgalib wont have it as far as zgv is
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 its 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 wont 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 youd 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 zgv).
(For those of you out there who have a 640x480 256-colour mode, but feel
youre 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, youre in the viewer. This
section describes what you can do while viewing the picture.
EXITING THE VIEWER
Exiting the viewer is simple:
Exit the viewer.
If you got to the viewer from the file selector, youre 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-mode-fit.
(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
Move up 100 pixels. k and q move up 10 pixels.
Move down 100 pixels. j and a move down 10 pixels.
Move left 100 pixels. h and o move left 10 pixels.
Move right 100 pixels. l and p move right 10 pixels.
Move up (nearly) a screenful. (It moves 90% of the screen height.)
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.
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 modes 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
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 havent 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, its 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,
Increase the ratio by doubling it --- leads to ratios of 2:1, 4:1,
Usually d is more useful.
There are similar commands to decrease the ratio (when it reaches 1:1
scaling is disabled):
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 mode).
Normally, scaling works by simply making the pixels into larger and
larger squares (in effect), which remain the same colour. However, if
you are using a 15/16/24/32-bit mode (see Video Modes), you can
enable a feature called interpolation which smoothly graduates the
colour change between the top-left corners of each pixel. This is
very slow, but looks nice.
Toggle interpolation in scaling mode.
Toggle off-by-one interpolation (disabled by default). Using this
off-by-one method gives incorrect results, but this can occasionally be
useful at ratios of 2:1 and 3:1 for relatively low-quality JPEGs.
(If you like the appearance of scaling with interpolation, you may also
be interested in a program I wrote called pnminterp, which can
scale up a PGM or PPM file while applying this effect.)
MIRROR AND ROTATE
Sometimes when viewing a picture you will want to flip it horizontally
or vertically, or rotate it:
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 pictures 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
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).
BRIGHTNESS AND CONTRAST
zgv provides support for changing brightness and contrast in all modes,
though it does slow things down a little in 15/16/24/32-bit modes
(see Video Modes).
Reset contrast and brightness to normal. (* is also supported, for
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 theyre applied in does make a difference --- assuming youve
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
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 were dealing with response curves,
this isnt just a matter of changing the brightness in a linear fashion.
That doesnt 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
But, given that the problem has existed since we started displaying more
than eight colours, you wont be surprised to find that its 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, its the most widespread approach. But its 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 screens 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 heres how to do it:
Set gamma adjustment to 1.0, i.e. no adjustment. This is the default
Set gamma adjustment to 2.2. This is useful for viewing linear-gamma
files (one classic example being raytracer output) on an average PC
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 dont know how true that is
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
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
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. Im 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 eyes 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, its 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 its 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
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 slideshow.)
View previous file in dir, with progress indicator. (In slideshow, acts
View next file in dir, with progress indicator. (In slideshow, acts
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
youd want, since you cant see the file selector to see which files are
While you can get file details when in the file selector, you cant
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 cant use ; to get this in the viewer, and the viewer doesnt
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 isnt really that close --- for example, its
worth noting that when the slideshow is paused, you can actually do
anything you normally might in the viewer.
MULTIPLE-IMAGE GIF ANIMATION
While zgv is for the most part a straightforward viewer, it has special
support for multiple-image animated GIF files. These are loaded as a
column of images, one on top of the other --- this column is the
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
Enter animation mode. (I dont 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
its 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. Heres a list showing which bit depths match which number
(These are the only bit depths relevant to zgv.)
4-bit means 16 colours.
8-bit means 256 colours.
15-bit means 32768 colours.
16-bit means 65536 colours.
24-bit means 16777216 colours (over 16 million).
32-bit means 16777216 colours too (!), since only 24 of the 32 bits are
used for display purposes.
From the number of colours available in the latter modes, you can see
why a bit depth notation is so useful!
So, in the widthxheightxdepth notation, our 640x480
256-colour mode would be 640x480x8, a 16-colour mode of the same size
would be 640x480x4, and an equivalent true-colour (24-bit) mode would
Whenever you see a mode referred to as xxyxz in zgv or
in this documentation, it is always specifying a video mode in
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, its 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 pixels 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, its considerable.
For this reason, and since converting from 24-bit to 15/16/32-bit is
very easy, when zgv reads a picture it stores it in memory in one of two
internal formats --- either as 8-bit, or as 24-bit. See File Format
Depths, for discussion on which format zgv uses for which files.
But what difference does all this make when youre using zgv? Well,
heres the bottom line:
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.
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.)
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
Confused? Head hurting? Dont 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
youve got a feel for whats going on.
Default Video Mode
zgv using the last mode you selected is all very well, but that doesnt
explain what happens if youve 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
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 dont happen to
have a spare lifetime in which to learn the normal mode-selecting
So, heres 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
Select 640x480x4 mode. This emulates an 8-bit mode. See The Viewer
Select 320x200x8 mode.
Select 320x240x8 mode.
Select 320x240x24 mode. (^ is often on shift-6.)
Select 320x400x8 mode. This emulates a 640x400 mode. See Virtual
Select 360x480x8 mode. This emulates a 720x480 mode. See Virtual
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.
Normally, each pixel in the image is written more-or-less directly to
the screen from zgvs internal copy of the picture (unless zoom mode
and/or scaling have been enabled). However, there are three modes where
zgv does things differently to make the modes more useful.
(These are mainly intended for users with only the original VGA modes
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, its 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
pictures palette. This usually gives a better result, but is
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 selectors 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. (Its difficult to use all 16 colours
effectively for a colour dither without slowing things down.)
The greyscale uses an ordered (pattern-based) dither. The colour uses
ordered dithering by default too, which is fast but pretty rough. If
youd 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
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 zgvs support for them.
That should also explain why zgv treats them the way it does. Heres how
it all works:
When using zgv, you dont 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. :-)
zgvs 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,
itll take the smoke-and-mirrors route.
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 neednt worry about 32-bit modes, though; you can
just ignore them and think in terms of 8/15/16/24-bit modes and youll
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 /usr/local/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 dont 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, its understandable that I chose to do some things slightly
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
View a picture file, or if the cursor is on a subdirectory, make that
the current directory. (Like the native Enter, which still works.)
(i.e. Alt-minus) Untag all files.
(i.e. Alt-equals) Tag all files.
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 files 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
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 viewers xzgv-ish keys:
The Ctrl + cursor-key alternatives to
h/j/k/l dont exist, as these cant be
distinguished from normal cursors given the way zgv reads keys.
The alternative Shift + cursor-key means of paging
up/down/left/right is similarly missing.
Supporting Ctrl-q would have got in the way of slideshow pausing,
so I decided against it, and omitted q from the viewer for some
sort of consistency.
Supporting Tab would break selecting some video modes, and
probably would have seemed a bit surreal in zgv anyway. :-)
That about wraps it up for the keys... but, of course, there
are other interface differences.
One is the way zgv has flat mouse menus for the selector/viewer, while
xzgv has hierarchical ones. That would be nice to replicate, but I dont
think Im 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 pointers
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 zgvs reaction to mouse movement, but fixing the
non-proportionality without a pointer onscreen might seem awfully
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.
FILE TYPE IDENTIFICATION
The format a file is in is identified in two different ways. The file
selector (by default) picks filenames to display based on the
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 its much faster than the alternative (reading part of
every single file) and is usually sufficient. (If its not, you can
enable slower magic number-based identification with Alt-m
(see File Selector Toggles).)
The file-reading code uses the formats 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.
SUPPORTED FILE FORMATS
zgv supports the following file formats:
GIF. Multiple-image GIFs are treated specially (see Multiple-image
PBM/PGM/PPM, collectively known as PNM. This is a nice simple format
used by pbmplus and netpbm.
mrf. Mrf files can be converted to/from PBM with mrftopbm/pbmtomrf, and
the format is documented in the mrf(5) man page.
PRF. PRF is an extension of mrf, similarly converted with
prftopnm/pnmtoprf, and documented in the prf(5) man page.
XBM (X bitmap files).
XPM. zgv reads the file /usr/X11R6/lib/X11/rgb.txt to look up X
colour names. (The location of the file is a compile-time option; you
can edit config.mk to change it.)
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.
Xv format thumbnail files. Normally you wont 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 directorys filename) --- they have the same
filenames, and thumbnails are their own thumbnails. :-)
FILE FORMAT DEPTHS
No matter what bit depth a file format uses, zgv reads files in as one
of two internal formats --- 8-bit (with a palette), or 24-bit.
(See Video Mode Issues, for why zgv works this way. See What a
Video Mode is, for more on bit depth.) Usually, zgv works internally
with the lowest bit depth which doesnt 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, its obvious which depth zgv reads a file as, if you
know how the files are stored. But if you dont happen to know that,
then it can seem like some bizarre black art dependent on the phase of
the moon. So heres how the differing file formats are read:
GIF, PBM, PGM, mrf, XBM.
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 dont have any
inherent depth as such, unlike most other files --- you couldnt
legitimately talk of a 24-bit XPM file.) XPMs are loaded as 8-bit if
they have 256 colours or less, otherwise theyre 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 screens background colour is made grey as well.
zgv tries to deal sensibly with Linux and FreeBSDs provision for
multiple virtual consoles. This section covers the details of this.
RUNNING IN THE BACKGROUND
Normally when you do a console switch away from zgv, it is suspended ---
nothing at all happens in that zgv process (and it takes no CPU) until
you switch back to it.
However, there are two circumstances (both in the file selector) when it
makes sense for zgv to keep running in the background, and in these
cases it does keep running:
When updating thumbnails. See Updating Thumbnails, for what happens
in this case.
When reading a picture file. If it finishes reading it before you
return, zgv is suspended as usual.
RUNNING FROM NON-CONSOLES
If its 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, etc.
One problem with this is that, since zgv uses fork(), zgv
-h and other things which give output on stdout will give confusing
results; the original zgv process will have exited before the new
(replacement) zgv process exits. Redirect stdout if you want things to
make a bit more sense --- for example, zgv -h | less will do what
youd expect. For more normal uses where zgv doesnt give any output,
theres no problem.
However, theres a problem running zgv from X, when its invoked from a
window managers 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 wont switch there. As luck would have it, theres
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 youre using, but
generally youd 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
youd 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, its 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.
USING A MOUSE
When mouse support is enabled in zgv, you can do almost everything with
it that you would ordinarily do with the keyboard.
ENABLING THE MOUSE
To use the mouse support for just one zgv session, start zgv with
something like zgv -M. To enable it by default, add mouse
on to a config file (see Config Files).
zgv uses svgalibs mouse configuration; if you have not set that up, you
will probably need to do so before zgvs mouse support will work. See
the libvga.config(5) man page for details.
If you find that the mouse pointer moves too quickly or too slowly, you
should change zgvs mouse-scale setting (see Config
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
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
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
MOUSE FUNCS IN THE FILE SELECTOR
In the file selector, the mouse controls a conventional mouse pointer.
In addition to the right button calling up a menu, there are these
actions you can take with the mouse:
Clicking on a file views it.
Clicking on the area which shows the current directory prompts you for a
directory to change to (see Dialog Boxes).
The scrollbar can be used to move along the file list, in a few
Clicking on the scrollbars arrows moves along the file list a column at
Clicking on either side of the scrollbars 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
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 youre moving the cursor not the
screen itself (at least not directly), the way it works may make a bit
Once youve got used to this, and got used to the menu, you may wonder
how exactly youre meant to (say) delete a file with the mouse. After
all, while clicking on it does select it, it also views it! Well, there
is a way, described below.
Click on the file you want to select, but hold down the mouse button.
While holding the button, click the right button. The menu should
appear, and you can let both buttons go. You can then select whatever
you want to do from the menu.
MOUSE FUNCS IN THE VIEWER
In the viewer, the mouse is mainly used for moving around the picture.
To use it for this, you should hold down the left button and drag the
mouse around. Its 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 shouldnt be too much of a
There is also a right-button menu much like the file selectors one, and
a mouse pointer does appear when using that. Some notes on the menu:
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.)
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.
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.)
The viewers menu is disabled in modes which are less than 480 pixels
high, since thats 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, youd then be able to switch to the mode using
the mouse (of course), but once there you wouldnt 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
You can do most things in zgv with the mouse, but you cant do
everything. The main problem is that there are still a few things which
effectively ignore the mouse:
When thumbnails are being updated, or a picture being read, theres no
mouse equivalent of Esc.
When youre prompted for a directory name, theres no mouse equivalent
of Esc or Enter.
Many aspects of the way zgv works can be modified by using a
A configuration file lets you alter aspects of zgvs behaviour. zgv
supports two possible config files --- a system-wide one,
/usr/local/etc/zgv.conf; and one for each user in their home
directory, $HOME/.zgvrc. Both are optional. If
$HOME/.zgvrc exists, it is used instead of
Before describing the format of config files, it may help to give an
# Sample zgv config file
# Comment lines begin with # and are ignored,
# as are blank lines.
# do faster jpeg thumbnails
# 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
Most variables are of this yes-or-no boolean type. Some others like
jpeg-index-style are integers (whole numbers). And there are
other types, too.
Since the variables set in a config file have a direct effect on how zgv
works, it can be easier to simply call them settings. Indeed, such
terminology is used on occasion in this documentation.
CONFIG VARIABLE TYPES
There are various types of variable:
Boolean. These are on-or-off, yes-or-no variables. Most of zgvs 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 youre actually giving three
separate numbers. For example, 640 480 8 specifies a 640x480x8
The no args type. Settings of this form arent 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 youd do --zoom on the command-line, youd do zoom
on in a config file. Be careful to avoid quoting arguments; if you do
this in a config file, youll 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, lets go back to that "most". The options which can only be
specified on the command-line are the following, one-off options:
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 isnt, 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.
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.
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 shouldnt
break any other mice, but if you have inexplicable mouse problems you
may want to try disabling this just to make sure its not the
CONFIG FILE BACKWARD COMPATIBILITY
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, heres 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.)
= force-viewer-8bit (sense inverted)
= delete-single-prompt (sense inverted)
= avoid-single-progress (sense inverted)
The old fullsel, hicolmodes, and hicontrol options
are no longer supported (i.e. zgvs previously-default behaviour for
those is now permanent), and have no effect other than to give a
Here I (RJM) attempt to explain why I did things the way I did. This is
presented in a question-and-answer format of sorts.
WHY YET ANOTHER VIEWER?
Often the simple answer to this is Actually, zgv was here first ---
ask the other guy. This is true of any viewer written since 1993,
Most of the time though, this is phrased as Why not just use xv?.
Thats a fair point; xv is quite a good program, and it has some nice
features. But briefly, here are my problems with it, the areas where I
personally feel zgv is (at least arguably) better than xv:
xv is shareware. Personally, I dont think selling picture viewers is
all that sensible when things like the Gimp are free.
I find the interface really, really weird. In particular, the visual
schnauzer feels rather bolted on.
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 its much closer to the do one thing well software tools
philosophy (see Opening the software toolbox in the textutils info file).
Im not saying zgv is great and xv is terrible, and its 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 dont think xv is even remotely close to being the
category-killer for picture viewing that some people seem to think it
(Update: Since I originally wrote the no obvious zgv-like
competition line above, Ive written xzgv, which is a GTK+/Imlib-based
port/rewrite of zgv for X. What can I say, I liked it so much I wrote
the code. :^)
Electric Eyes is another alternative to xv, but personally I find that
much too xv-like (hence my work on xzgv).)
WHY A TEXINFO MANUAL?
For years, I maintained a conventional man page for zgv. But over
time, I realised just how impossibly confusing the zgv man page had
So I wanted to rewrite zgvs 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.
Dont 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 modes node- and menu-update
commands, I personally would find it near-impossible!) But big man pages
just arent that good for reference, and this is made worse by the
relative lack of structure.
WHY ONE-SPACE SENTENCE ENDS?
The conventional way to write texinfo is to follow each sentence with
two spaces after the dot (or whatever ends the sentence). Many people
normally write this way in a non-texinfo context too. But a sizeable
proportion of people normally write text with only one space after the
dot --- and Im 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 documentations 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 doesnt 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
So realistically, anyone who writes texinfo with one-space has to put up
with the occasional two-space sentence end being inserted into their
text --- worse still, the current makeinfo formatting algorithm seems
to insert two spaces even after abbreviations (such as e.g. and
etc.), which breaks even two-space texinfo. (This is particularly
ironic, by the way, since two-space partisans main argument in favour
of the practice is the way it makes it possible to tell the difference
between abbreviations and the end of a sentence.)
One last point may be worth noting; I am not the first person to write
texinfo files using one-space. At the time of writing, it is used in the
texinfo documentation for BFD, gdbm, GTK, IPC, ld.so, and viper, and I
expect there are instances Im not aware of.
BUGS AND RESTRICTIONS
All (non-trivial) programs have bugs. Anyone who denies this...
clearly hasnt written too many programs.
is wrong. ;-)
It follows that zgv, like everything else, always has some bugs. Usually
these are not serious, or Id 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 generated.
Renaming a file renames the thumbnail too, but currently it ignores any
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 theyre on, which is harmless but doesnt look very nice.
If you look up joe code in a dictionary, it says see zgv. :-)
You dont 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. Theres some precedent for this approach (e.g. the
Gimp), but its 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 screens width, the background
to the left and right of the picture is filled in with the pictures
background colour (though youll only be able to see this if the
pictures background colour isnt 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
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
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). (Svgalibs 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 cant figure out whether its 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:
The version of zgv you are running (zgv --version reports this).
The version of svgalib (try ls /usr/lib/libvga.* for this).
What your machines (S)VGA card is described as, and (generally more
useful) what svgalib reports it to be. zgv suppresses this report, but
most other svgalib programs (vgatest which comes with svgalib being
a simple example) will report it when they start up.
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.
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 youve found a bug in zgv, report it by emailing me
REPORTING DOCUMENTATION BUGS
Bugs in the documentation can sometimes cause as much trouble as bugs in
the program; if you notice a problem in the documentation, its a good
idea to report it.
For reports of documentation bugs, you should include these details:
The version of zgv the documentation is for.
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 :-)).
The format of the documentation you saw the problem in (e.g. info, man
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 youd like in zgv, or a change to an
existing feature, contact me at <firstname.lastname@example.org>.
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 zgvs TODO file, so you should check that too if
youre interested in this stuff.)
Fix the progress indicator problem with multiple-image GIFs.
Mouse support isnt really finished --- the goto-dir dialog should have
ok/cancel buttons, and currently you cant 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!
File move should probably delete any existing thumbnail for the file
if the file itself is moved successfully.
Russell Marks <email@example.com> and others;
see the section ACKNOWLEDGEMENTS for details.
|Version 5.9 ||ZGV (1) ||28th January 2005 |
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.