Provided by: xzgv_0.9.1-3_amd64 
NAME
xzgv - picture viewer for X, with thumbnail-based file selector
SYNOPSIS
xzgv [options] [dir | file ...]
DESCRIPTION
(NB: This man page is automagically generated from xzgv's texinfo file, and so may look a
bit odd. We apologise for the inconvenience. :-))
xzgv is a picture viewer for X, with a thumbnail-based file selector. The thumbnails used
(thumbnails being small `preview' versions of the pictures) are compatible with xv, zgv,
and the Gimp. The kinds of pictures xzgv allows to be viewed are raster-format pictures
(sometimes called `bitmaps' and/or `pixmaps'); things like GIF files, JPEG files, PNG
files, and so on.
Most of the time, you will probably want to use xzgv's file selector (see The File
Selector) to pick which file(s) to view. This is what appears on the left-hand side of the
window when you start xzgv as just `xzgv' (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 in a given directory, or
if they are missing for some files, you can create/update them by pressing `u'. See
Updating Thumbnails.)
When you've picked a file to view, you can view it by clicking on it, or pressing `Enter'.
This reads the picture and displays it in the right-hand part of the window, the viewer
(see The Viewer). You can then move around the picture (if it is larger than will fit) by
dragging it with the mouse, or using the scrollbars, or the cursor keys. You can then
select another image with the file selector (though you need to press `Esc' or `Tab' first
if using the keyboard), or you can quit xzgv by pressing `q'.
While xzgv works much like any other X program, and is certainly mouse-friendly :-), it's
also designed to be keyboard-friendly. Everything in xzgv can be done entirely from the
keyboard. Much of this keyboard support works like the original zgv (a similar console-
based picture viewer for Linux).
This overview is, as you might expect, only the very simplest of introductions to what
xzgv can do, and describes only a very basic use of xzgv. xzgv can do a lot more; read on
to find out what.
ACKNOWLEDGEMENTS
xzgv was primarily written by Russell Marks, also the author of this manual. It is
maintained by Reuben Thomas.
Costa Sapuntzakis contributed code for much faster JPEG thumbnail generation (to zgv,
which I adapted for xzgv).
The directory/file icons used were loosely based on gmc's dir-close.xpm. I think Tuomas
Kuosmanen was responsible for that, judging from the change log.
`mkinstalldirs' is straight from the `texinfo' package, and was written by Noah Friedman.
(This is also used during installation.)
Huge thanks go to the many people responsible for GTK+, without which xzgv would almost
certainly not have happened. (But no thanks for Electric Eyes, which was nearly nice
enough for me not to bother with xzgv at all! :-))
getopt*.[ch] are from the GNU libc.
OPTIONS
Normally you'd invoke xzgv as plain `xzgv' (perhaps via a window manager menu, or
GNOME/KDE menu, etc.). However, you can directly specify files to view, or a start
directory, on the command-line. In addition, there are various options.
(If you're new to xzgv, you should probably skip the rest of this section for now and come
back to it later.)
The general format of the xzgv command-line goes roughly like this:
xzgv [options] [dir | file ...]
Two types of options are supported --- the traditional Unix single-letter options, and
GNU-style long options. Most options can be used in either way, and both forms are listed
in the table below.
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 xzgv), though a
few command-line options are not permitted as config file settings (e.g. `help'), and vice
versa.
Here's what the options do:
`-a'
`--auto-hide'
Automatically hide selector when a picture is selected, allowing the viewer to use
the whole window.
`--careful-jpeg'
Enable libjpeg `fancy upsampling'. xzgv defaults to using the faster method; as the
libjpeg documentation puts it, ``The visual impact of the sloppier method is often
very small.''
`--delete-single-prompt'
(Note that this is normally enabled; use `--delete-single-prompt=off' to disable
it.) If disabled, xzgv will immediately delete a file when told to, without
prompting for confirmation. (It's `single' because deleting multiple files at once
will be supported in future, and that will have a separate prompt override.)
`--dither-hicol'
Use dithering in 15/16-bit, whatever the default setting is. See Viewer Options,
for a discussion of benefits/drawbacks. You can also use `--dither-hicol=off' to
disable this.
`--exif-orient'
In JPEG files, use Exif orientation tags (inserted by e.g. digital cameras) to
correct image orientation before display. See Viewer Options, for details.
`--fast-recursive-update'
When doing a recursive thumbnail update, don't read existing thumbnails before
updating. This is pretty much obsolete as of xzgv 0.7, as the speed increase is now
negligible. But, it may still be useful if you want to update a huge number of
small directories for which few if any updates are needed.
`-f'
`--fullscreen'
Run fullscreen, using the entire screen for xzgv's window, without even any window-
manager decorations (window frame, title bar, etc.) if possible.
`-G val'
`--gamma val'
[Not supported in 0.9.] Set the gamma adjustment used (see Gamma Adjustment). The
default is 1.0. This also sets the `initial value' used when resetting the gamma
adjustment.
`-g geom'
`--geometry geom'
Set the xzgv window's geometry (position and/or size) to geom. The geometry string
should be in the usual X format, with the extension that positions/sizes may have a
`%' suffix meaning that they are treated as percentages of the screen width/height.
The default geometry is `92%x85%'.
For those unfamiliar with the way `geometry' works, here's a brief description of
the syntax. It's `WxH', or `+X+Y', or `WxH+X+Y', where `W' is width, `H' height,
`X' the x position, and `Y' the y position. The first form specifies only the size,
the second only the position --- the `WxH+X+Y' form specifies both.
Now, the `+X+Y' bit normally specifies where the top-left of the window is. But you
can use `-' instead of `+' for the x and/or y position, in which case it specifies
the gap between the right/bottom of the window and the right/bottom of the screen.
(Note, however, that any window frame your window manager adds to the window is
disregarded in this calculation, so you may need to experiment somewhat to get the
desired position.) You can also use negative numbers with both `+' and `-' --- so
`+-50+0' puts the window partly off the left of the screen, and `+0--50' puts it
partly off the bottom of the screen --- but this is of questionable value. :-)
Finally, as mentioned above, xzgv extends this syntax by allowing you to use `%' to
specify percentages of the screen width/height rather than pixels, e.g.
`50%x30%-30%-20%'. It also allows you to use real numbers such as `12.34', which
can be useful with `%'.
`-h'
`--help'
Display a list of options and a terse description of what the options do.
`--image-bigness-threshold numpix'
Set the boundary numpix after which images are considered `big', and are no longer
rendered all-at-once (which gives much nicer scrolling, but is harder on memory and
can be slow for big images) but are instead rendered piece-by-piece. Units are
number of pixels in image (i.e. width times height), and the default is 2000000
pixels.
`--interpolate'
Interpolate between the picture's pixels when scaling up (see Scaling). This
usually looks nicer, but it's rather slow.
`--mouse-scale-x'
If enabled, control-clicking on the viewer scales only the X axis. (The default is
to scale only the Y axis.)
`--revert-orient'
(Note that this is normally enabled; use `--revert-orient=off' to disable it.) If
disabled, orientation (flip/mirror/rotate) state is retained between pictures (see
Viewer Options).
`--revert-scale'
(Note that this is normally enabled; use `--revert-scale=off' to disable it.) If
disabled, scaling is retained between pictures (see Viewer Options).
`--selector-width'
Set the default/initial size of the selector in pixels. The normal setting is 200.
`-T'
`--show-tagged'
Show names of currently-tagged files on exiting xzgv. (They're listed to stdout,
one per line.) This can be useful when you want to select multiple files
graphically and work on them with something else.
`--show-thumbnail-messages'
Show on the status bar when thumbnails are being read. The status bar must be
enabled for these messages to be visible, of course. :-)
`-k'
`--skip-parent'
For the first directory shown, skip the cursor past .. (the parent dir). This can
be useful when you'd like to immediately use space to `page' through the dir.
`-o order'
`--sort-order order'
Set the initial sorting order used in the selector. Possible settings are `name',
`ext', `size', and `date' (or `time'); only the first char of the setting
(`n'/`e'/`s'/`d'/`t') need be given. The default is name order.
`--sort-timestamp-type type'
Set the timestamp type to use when using time/date sorting order. Possible
settings are `mtime' (default), `ctime', and `atime'; only the first char of the
setting (`m'/`c'/`a') need be given.
`--statusbar'
Show a status bar below the selector; this, for example, says when a picture is
being read.
`-t'
`--thin-rows'
Use rows a third the normal height in the selector. This can be very useful on
lower-resolution screens, or if you're really interested in filenames, not
thumbnails.
`-v'
`--version'
Show version number.
`--version-gtk'
Show version number of GTK+ xzgv is using.
`-z'
`--zoom'
Fit picture to viewer window, whatever its actual size (see Zoom Mode).
`-r'
`--zoom-reduce-only'
When in zoom mode, only reduce pictures to fit; i.e. make big pictures viewable
all-at-once while leaving small picures intact.
If started with `xzgv files', xzgv hides the file selector and treats the file or files as
if they were the sole contents of a directory. (It also automatically loads the first
file.) As such, you can use the Next Image and Previous Image commands to navigate between
the images, or do Exit to Selector and use the selector directly.
If started with `xzgv start-dir', xzgv starts up as usual, but with the selector starting
on the directory specified (rather than the current directory).
Settings which are either on or off (boolean) are, as you might expect, enabled by using
e.g. `-z' or `--zoom'. However, there's an alternative long-option form for setting these,
resembling how they're set in config files --- the syntax is `--option=state', where state
is `on'/`y'/`yes'/`1' to enable the option, or `off'/`n'/`no'/`0' to disable it. The most
useful thing about this is that it allows you to disable options which were previously
enabled, by using e.g. `--zoom=off'.
(Readers used to the way GNU-style long options work should note that, since this
`on'/`off'/etc. arg is optional, you can't use the `--option arg' form in this case; it
must be `--option=arg' for it to work.)
A NOTE ON NOTATION
Much of this manual is taken up by a description of xzgv's various commands in its file
selector and viewer. Most of these are available both from the keyboard, and from popup
menus. (A popup menu appears when you press `F10' or `Menu', or right-click on the
selector or the viewer; each has its own menu.) So in the manual, you will often see
things rather like this:
`key'
`Selector menu, Menu the item is in, Menu item'
Description of what the key/menu item does.
Sometimes the key given has a `(Selector)' or `(Viewer)' suffix; this is because some
keypresses in xzgv are specific to the selector or the viewer, and won't work unless the
relevant part of xzgv has the keyboard focus.
THE FILE SELECTOR
Usually, on starting up xzgv, you'll want to use the file selector --- the list of files
on the left. (The other subwindow (on the right) is the viewer.) The selector lets you
pick files to view (among other things). It lists the subdirectories and picture files in
the current directory, along with small `thumbnail' versions of the pictures if they
exist.
THE SELECTOR MENU
Almost all selector commands are available from the selector's pop-up menu, which appears
when you right-click anywhere on the selector. (You can also press `F10' or `Menu' to
bring up the menu, but as there are keyboard shortcuts for just about everything in xzgv,
this isn't often that useful. :-))
Usually, it doesn't matter where on the selector you right-click. However, a few commands
on the File menu operate on a single file, the one selected by the keyboard cursor. A
problem when using the mouse, you might think --- but when you right-click on the
selector, as well as popping up the menu, xzgv moves this cursor to the file you right-
clicked on (if any). (You can see this by the way a hollow box is drawn around the file.)
So to use e.g. Details on the File menu, you need to right-click on the file you want
details on.
Both the selector and viewer have `Help' menus, most items of which refer you to this
manual:
`F1'
`Selector menu, Help, Contents'
`Viewer menu, Help, Contents'
View the manual's overall contents.
`Selector menu, Help, The File Selector'
View the manual's section on the file selector.
`Viewer menu, Help, The Viewer'
View the manual's section on the viewer.
`Selector menu, Help, Index'
`Viewer menu, Help, Index'
View the manual's concept index.
`Selector menu, Help, About'
`Viewer menu, Help, About'
Give some brief information about xzgv, including the version number and homepage.
Currently, the way xzgv lets you read the manual is a bit crude; it runs the `info'
program (see Top in the info-stnd info file) in an `xterm'.
EXITING XZGV
You can exit xzgv either by using one of two exit keypresses, or by selecting the
appropriate option from the selector's popup menu:
`q'
`Ctrl-q'
`Selector menu, Exit xzgv'
Quit xzgv.
(There's also an exit option on the selector's File menu (`Selector menu, File, Exit'), as
`Exit' is generally on any File menu.)
THUMBNAILS
(This section is deliberately early on in the manual, as thumbnails are probably the most
important feature of the file selector, so it's best that you know how to create/update
them sooner rather than later.)
Thumbnails are small versions of the pictures they represent, and are displayed by the
file selector if they exist. xzgv uses xv-compatible thumbnails --- if you create
thumbnails with xv they will work with xzgv, and vice versa. xzgv's thumbnails are also
compatible with the Gimp, and zgv.
If no thumbnail exists for a file, a small `document' icon appears instead (similar to the
`folder' icon used for directories).
Updating Thumbnails
While thumbnails can be made relatively quickly, it's by no means an instant process. For
this reason, thumbnails have to be created in advance, and are stored as files in their
own right in a subdirectory .xvpics.
xzgv never creates/updates thumbnails without you telling it to. So, if you enter a
directory where the picture files don't have any thumbnails, or where the thumbnails seem
to be out of date, you should press `u', or select Update Thumbnails from the selector's
menu. (Even if the thumbnails can't be written (say, if you don't have permission to
write them), the selector will still show the updated thumbnails until you leave the
directory.)
Alternatively, you can create/update thumbnails for the current directory and all
subdirectories by using `Alt-u' or Recursive Update. But be warned that a recursive update
can take some time!
`u'
`Selector menu, Update Thumbnails'
Create thumbnails for any files which don't have them, and update thumbnails which
are older than the corresponding file. While this is going on, a window appears
showing how far through the process xzgv is.
While the update is in progress, you can abort it by clicking on the Cancel button,
or pressing `Esc' or `Enter', or by clicking the delete-window button (if your
window manager provides one) on the title bar. xzgv will stop once it has finished
the thumbnail it is currently working on (if any).
`Alt-u'
`Selector menu, Recursive Update'
Create/update thumbnails for all files in the current directory and all
subdirectories. This can take some time, so you are prompted to confirm you really
want to do this (see Dialog Boxes). Progress is indicated in much the same way as
for a normal update, but only for the directory currently being updated --- the
overall progress is not indicated, other than by the current dir being (as ever)
displayed in the main window's title. You can abort a recursive thumbnail update in
the same ways as for a normal update (see above).
By default, xzgv behaves a little oddly when doing a recursive update, to give some
consistency with the normal update. See Thumbnail Issues, for details.
Thumbnail Issues
Dealing with thumbnails can be `interesting' at times, and there are a few ways this
influences things:
- xzgv doesn't read the thumbnails in a directory all at once. Instead, it just reads the
directory contents, then starts up what is effectively a kind of background task to read
in the thumbnails. So xzgv may not be quite as responsive as usual for a short time after
entering a directory with many thumbnails (say, a few hundred) --- but on the other hand,
at least it is responding. :-)
- The `background task' makes a special effort to show thumbnails for the files currently
visible in the selector first, no matter how much you move around the list, but it reads
them all in eventually.
- The thumbnails used in xzgv require 256 colours to display. This can be a problem if
you're running X in 256 colours or less as, even if you're running an 8-bit (256 colour)
server, there will almost inevitably be fewer colours available. Currently, xzgv just uses
whatever gdk reports as the closest match to each individual colour used in thumbnails.
This gives a tolerable result on 8-bit servers, assuming gdk was able to allocate a large
number of colours; however, it gives terrible results if it couldn't, or if running on
4-bit or 1-bit servers. Sorry about this --- it should be fixed in future (either by using
gdk to draw the thumbnail pixmaps, or by dithering them `by hand' to suit the colours
available).
- Finally, when doing a recursive thumbnail update, xzgv (by default) reads existing
thumbnails in a directory before updating any. Or rather, it reads thumbnails for those
files currently visible in the selector. This can slow things down very slightly, but
keeps the `look and feel' consistent with the normal update. (Still, you can disable this
with the `--fast-recursive-update' command-line option (see Invoking xzgv) or equivalent
config file entry (see Configuring xzgv).)
SELECTOR LAYOUT AND RESIZING
The file selector is simply a list of subdirectories and filenames, along with any
thumbnails that exist for them. The list is normally in asciibetical order (but you can
change this; see Changing the Sorting Order). Names of directories are shown first, and
they are shown in order at the beginning of the list, before all the picture files. Long
filenames may not fit in the visible part of the file selector display; if so, there will
be a horizontal scrollbar you can use to see the rest of the name(s) (you can use cursor
left/right to do this from the keyboard).
The list is very 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 using the (vertical)
scrollbar, or with cursor up/down and the like.
If you find the selector window to be too small vertically, and would like to see more
files at once, you can start xzgv fullscreen by using the -f option (see Options), and/or
use `thin rows' mode (see File Selector Options).
If you find the selector too small (or too big) horizontally, you can change this by
moving the splitter line's `handle' (a small square button between the selector and
viewer, near the bottom of the window), which changes the relative sizes of the selector
and viewer. You can move it by dragging it with the mouse, or with these keys:
`['
Move the window split left.
`Ctrl-['
Move the window split left more slowly.
`]'
Move the window split right.
`Ctrl-]'
Move the window split right more slowly.
`~'
Reset the window split to its default position.
You can also set the initial/default size of the selector --- in effect, the position of
the window split --- using `--selector-width' (see Options) or the config file option
`selector-width'.
MOVING AROUND THE LIST
This section is mainly for those of us more inclined to the keyboard side of the force.
:-) Mouse-happy types can freely skip it.
When the selector has the keyboard focus, the cursor (or in GTK+ jargon, the `focus row')
is normally shown as a hollow box around one of the list's rows. This serves the following
functions:
- It selects a file for view 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 (unless you move around using the mouse).
There are several commands for moving the cursor. In summary, most `special' keys like the
cursors do what you'd imagine they do, but in more detail:
`Cursor Up'
`k'
Move up.
`Cursor Down'
`j'
Move down.
`Page Up'
`Ctrl-u'
Move the cursor back roughly a page.
`Page Down'
`Ctrl-v'
Move the cursor forward roughly a page.
`Ctrl-Home'
`Ctrl-a'
Move the cursor to the start of the list.
`Ctrl-End'
`Ctrl-e'
Move the cursor to the end of the list.
`g'
`''
Move the cursor to the first filename starting with the next key pressed, which
would generally be a letter or number. Case is significant; `a' and `A' are
different. If no key is pressed within 2 seconds, the command is cancelled.
If no files start with the specified character, it moves to the first file which
starts with a later char (in asciibetical order). If there are none for which this
is the case, it moves to the last file --- unless there are no files (just
directories), in which case it has no effect.
VIEWING A FILE
To view a file from the selector, you can click on it, or press `Enter' after moving the
cursor to the relevant file, or right-click on the file and choose `File' then `Open'.
`Enter'
`Left-click-on-file'
`Selector menu, File, Open'
View the chosen picture file, or if a subdirectory is chosen, make that the current
directory.
DIALOG BOXES
See The Viewer, for details of how the viewer works. If xzgv has a serious problem
reading a file, it will give an error. Errors are shown in dialogs which appear in the
middle of the screen --- they stay there until you click Ok (or press `Enter' or `Esc').
xzgv also uses similar dialog boxes for other things:
- Getting confirmation that you want to do something. `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.)
- Showing progress when updating a thumbnail. This is a slightly unusual dialog, in that
it automatically disappears when the update is complete. However, it does provide a
Cancel button which you can click to abort the update (pressing `Enter' or `Esc' does the
same).
- Reading a directory name. Here you should type the directory name then click Ok (or
press `Enter'), or click Cancel (or press `Esc') to abort. The text-input `widget' used
allows a certain amount of editing, including these keys:
`Cursor Left'
`Ctrl-b'
Move the cursor left. (A vertical bar shows the cursor position.)
`Cursor Right'
`Ctrl-f'
Move the cursor right.
`Home'
`Ctrl-a'
Move the cursor to the start of the line.
`End'
`Ctrl-e'
Move the cursor to the end of the line.
`Backspace'
`Ctrl-h'
Delete char to the left of the cursor. (Note that `Backspace' is (usually) the key
above the main `Enter' key; it is often labelled simply as an arrow.)
`Delete'
`Ctrl-d'
Delete the char the cursor is on.
You can also set the X selection (by selecting text with the mouse, or holding `Shift'
while moving the cursor) to allow pasting text into other programs, and you can
cut/copy/paste text in the usual ways:
`Shift-Delete'
`Ctrl-x'
Cut text.
`Ctrl-Insert'
`Ctrl-c'
Copy text.
`Shift-Insert'
`Ctrl-v'
Paste text.
You can paste text from (some) other programs using the latter command, too.
CLOSING A FILE
Usually, when you view a file, the viewer subwindow keeps displaying it until you view a
different file. However, if you `close' the file, the viewer stops displaying the file and
returns to its initial state.
`Ctrl-w'
`Selector menu, File, Close'
`Close' the currently-viewed file, clearing the viewer subwindow.
FILE DETAILS
The listing the selector gives for a file is pretty sparse --- just the filename and (if
the file has one) the accompanying thumbnail. While this does keep things simple, you
sometimes want to know how much space a file takes up, when it was last modified, the
dimensions of the image, that kind of thing. So, you can show details of a single file
using the `file details' command:
`:'
`;'
`Selector menu, File, Details'
Show various details about the file pointed to by the keyboard cursor. See The
Selector Menu, for how to choose the file details are given for when using the
mouse. (Basically, you right-click on the file when popping up the menu.)
Most of the details shown come from the OS (by using the `stat(2)' system call), and
should always be available unless you have limited permissions for the directory the file
is in. The file dimensions (width/height), however, come from the file's thumbnail. If it
doesn't have one, or if it's unreadable, or if it has one and it's readable but it doesn't
mention the original image's width/height, then the Details from thumbnail area is greyed
out.
(In explanation of the latter point --- pre-5.0 versions of zgv did not generate
width/height comments in thumbnails, so zgv users in particular may find the width/height
details missing. (xzgv has always been ok, though, it's just zgv which had this problem.)
Worse yet, versions 5.0 and 5.1 generated them with incorrect sizes for most JPEGs. To fix
either problem for a given directory, do `rm -fr .xvpics' in that dir from a shell prompt
and recreate the thumbnails with zgv 5.2 or later, or xzgv/xv/Gimp.)
TAGGING
The file selector is not restricted to working on one file at a time. You can `tag' as
many (or as few) files as you wish, and certain commands described in this section will
act on them.
Initially, all files are untagged, and the filenames usually appear in black (though this
depends on the GTK+ theme you're using). Tagged files appear in red.
Tag and Untag Commands
There are several ways to tag or untag files. The keyboard-based ones which work on
individual files (also available on the Tagging menu) move the cursor down one row
afterwards, to make tagging or untagging multiple files easier.
To tag or untag a single file with the mouse, control-click (i.e. hold down the control
key and click) on the relevant filename or thumbnail in the selector. It's true that you
could use Tag and/or Untag on the Tagging menu (see The Selector Menu, for how to choose
the file tagged/untagged when doing it this way), but this is usually much less convenient
than using control-click. (The menu entries for those are really just for completeness.)
There is also a command available in the viewer to tag the currently-viewed file. See
Changing Picture, for details.
`='
`+'
`Keypad +'
`0'
`Selector menu, Tagging, Tag'
Tag file.
`-'
`Keypad -'
`9'
`Selector menu, Tagging, Untag'
Untag file.
`Alt ='
`Alt-Keypad +'
`Alt-0'
`Selector menu, Tagging, Tag All'
Tag all files.
`Alt -'
`Alt-Keypad -'
`Alt-9'
`Selector menu, Tagging, Untag All'
Untag all files.
`Alt-o'
`Selector menu, Tagging, Toggle All'
Toggle all tags. This inverts the tagged state, so that all previously tagged files
become untagged, and all previously untagged files become tagged.
Currently there is no way to toggle a (single) file's tag state from the keyboard.
Moving Between Tagged Files
These commands let you search for (move to) the next or previous tagged file (if any).
Note that `next' and `previous' here are relative to the keyboard cursor's position; if
you use these from the menu, be careful to right-click on the file you want to start the
search from.
`/'
`Selector menu, Tagging, Next Tagged'
Move to next tagged file in dir.
`?'
`Selector menu, Tagging, Previous Tagged'
Move to previous tagged file in dir.
Equivalent commands are also available in the viewer (see Changing Picture).
Copying/Moving Files
You can copy or move tagged files to a directory you specify. If no files are tagged, xzgv
copies/moves the file the cursor is currently on --- unless the cursor is on a
subdirectory, in which case it gives an error.
`C (Shift-c)'
`Selector menu, File, Copy'
Copy tagged files (or the current file) to a given directory. xzgv 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.
`M (Shift-m)'
`Selector menu, File, Move'
Move tagged files (or the current file) similarly.
RENAMING A FILE
As well as copying/moving files, you can rename them:
`Ctrl-n'
`Selector menu, File, Rename file'
Rename the current file or directory --- xzgv will refuse to overwrite any existing
files/directories. The new name must remain in the current directory. (See
Copying/Moving Files, for how to move a file to a different directory (albeit
keeping the same name).) See The Selector Menu, for how to choose the file renamed
when using the mouse. (Basically, you right-click on the file when popping up the
menu.)
I know `Ctrl-n' isn't the most mnemonic keypress possible for `rename', but all the good
ones were taken. :-/
DELETING A FILE
Deleting a file is pretty straightforward:
`Ctrl-d'
`Selector menu, File, Delete file'
Delete the file pointed to by the keyboard cursor (and any accompanying thumbnail).
See The Selector Menu, for how to choose the file deleted when using the mouse.
(Basically, you right-click on the file when popping up the menu.)
Note that only one file is deleted (hence `Delete file'); there is currently no way to
delete all tagged files.
CHANGING DIRECTORY
The easiest way to change the current directory in xzgv is usually to click on a directory
entry in the file list (or move the cursor to it and press `Enter'). Selecting the `..'
entry moves to the parent directory of the current one.
There is an alternative though:
(Note that the key for this command is shift-`g', not `g'.)
`G'
`Selector menu, Directory, Change'
Go to a specified directory. xzgv asks for the destination directory using a dialog
box which you should type the dir's name into (see Dialog Boxes), and moves to that
directory if it exists.
RESCANNING THE DIRECTORY
Normally, xzgv reads a directory once (on starting up, or when a new directory is
selected). So if the contents of the directory are changed by another program, this is not
automatically reflected. You can, however, explicitly tell xzgv to `rescan' the directory
(reread the contents), which will update xzgv's notion of what's in it:
`Ctrl-r'
`Selector menu, Directory, Rescan'
Rescan the current directory.
CHANGING THE SORTING ORDER
Normally, the files are listed in asciibetical order by name. However, you can instead
have the file list sorted by size, last-modified date/time, or by `extension' (the file
type).
(Only the order of files can be altered; directories are always listed first, and always
in name order.)
`Alt-n'
`Selector menu, Directory, Sort by Name'
Sort by name. This is the default.
`Alt-e'
`Selector menu, Directory, Sort by Extension'
Sort by extension.
`Alt-s'
`Selector menu, Directory, Sort by Size'
Sort by size. The biggest files are listed last.
`Alt-d'
`Selector menu, Directory, Sort by Time & Date'
Sort by time/date. The newest files are listed last.
You can set the default sort order via the command-line (see Invoking xzgv) or a config
file (see Configuring xzgv).
There are three possible timestamps you can use for the `Time & Date' sorting order:
`Alt-Shift-m'
`Selector menu, Directory, Time & Date Type, Modification Time (mtime)'
Use the last-modified time (`mtime'). This is the default.
`Alt-Shift-c'
`Selector menu, Directory, Time & Date Type, Attribute Change Time (ctime)'
Use the last-attribute-change time (`ctime'). Note that this is not always the time
the file was created, which it's sometimes mistaken for; for example, moving a file
with `mv' will usually change the ctime.
`Alt-Shift-a'
`Selector menu, Directory, Time & Date Type, Access Time (atime)'
Use the last-accessed time (`mtime'). The selector order is not automatically
updated when xzgv reads files, since this would probably be annoying; do a manual
rescan if need be.
FILE SELECTOR OPTIONS
Various aspects of the file selector's behaviour can be configured while xzgv 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 xzgv).
`Alt-a'
`Selector menu, Options, Auto Hide'
Toggle the auto-hiding of the selector when a picture is viewed (off by default).
This is handy for small screens/windows, or for old-time zgv users who just dig
that groovy modal interface, er, man. :-)
`Alt-b'
`Selector menu, Options, Status Bar'
Toggle status bar at the bottom of the selector (off by default). This displays
messages in certain circumstances --- normally, it just says when a picture is
being read.
`Selector menu, Options, Thumbnail Msgs'
Toggle reading-thumbnails messages (default is off), only visible if the status bar
is enabled. These messages make it clear when all thumbnails have been read, but
having something flash up every time you change directory is generally just
annoying.
`v'
`Selector menu, Options, Thin Rows'
Toggle `thin rows' mode (off by default), in which thumbnails are shown at a third
their normal size so that many more files can be shown at once. (The odd keyboard
shortcut for this is inherited from zgv's `visual' mode toggle, which had a roughly
similar effect.)
THE VIEWER
Once you've selected a file to view, it's shown in the viewer (the right-hand part of
xzgv's window). This section describes what you can do while viewing the picture.
Like the selector, the viewer has its own menu --- right-click anywhere on the viewer (or
press `F10' or `Menu') to show it --- and a similar help menu (see The Selector Menu).
EXITING THE VIEWER
When using the mouse to control xzgv, it doesn't matter whether the selector or the viewer
has keyboard focus --- mouse operations transcend such petty boundaries. :-) But keyboard
control is (of necessity) effectively modal, and so you need to `exit' the viewer in order
to have keyboard control over the selector again. You also need to exit the viewer if
you've enabled auto-hide mode.
Exiting the viewer is simple:
`Esc'
`Tab'
`Viewer menu, Exit to Selector'
Exit the viewer. This also returns the selector to its former size, if it was
previously `hidden'.
Another way of exiting the viewer is to middle-click on it, but this mouse-only approach
is really only of use when the selector is `hidden'.
BIG PICTURES
A picture may well be too large to fit entirely in the viewer window. There are two main
things which can help you see more of the picture at once:
- Make the xzgv window larger. You could `maximize' it with your window manager, or you
could start xzgv with a larger window using `--geometry' or fullscreen mode (see Options).
The fullscreen mode gives xzgv the maximum window size possible, but needs co-operation
from your window manager (and alas, many are not as willing as one might like) --- in some
cases you may even find `--geometry 100%x100%' to be more effective.
- Hide the selector. To do this, either use auto-hide mode (see File Selector Options), or
hide the selector explicitly (see Hiding the Selector).
But of course, these are only partial solutions to the problem; there will inevitably
always be pictures larger than your screen can show at once. In general, then, there are
two ways to see the whole of the picture.
Scrolling
Scrolling is the default approach to handling big pictures in xzgv. When the viewer is
started up, the top-left of the picture is shown --- you can either drag the picture
around with the mouse (i.e. click and hold the button down, then move the mouse around),
or use the scrollbars, or use the cursor keys (and others) to move around the rest of the
picture:
`Cursor Up'
`K'
Move up 100 pixels. `Ctrl-Cursor Up' and `k' both move up 10 pixels.
`Cursor Down'
`J'
Move down 100 pixels. `Ctrl-Cursor Down' and `j' both move down 10 pixels.
`Cursor Left'
`H'
Move left 100 pixels. `Ctrl-Cursor Left' and `h' both move left 10 pixels.
`Cursor Right'
`L'
Move right 100 pixels. `Ctrl-Cursor Right' and `l' both move right 10 pixels.
`Page Up'
`Shift-Cursor Up'
`Ctrl-u'
Move up (nearly) the window height. (It moves by 90% of the height.)
`Page Down'
`Shift-Cursor Down'
`Ctrl-v'
Move down (nearly) the window height.
`-'
`Shift-Cursor Left'
Move left (nearly) a window-length. (It moves by 90% of it.)
`='
`Shift-Cursor Right'
Move right (nearly) a window-length.
`Home'
`Ctrl-a'
Move to the top-left of the picture.
`End'
`Ctrl-e'
Move to the bottom-right of the picture.
Zoom Mode
An alternative way of viewing the whole picture, one which lets you see the picture
onscreen all at once no matter how big (or small) it is, is zoom mode.
Zoom mode's name derives from the idea of `zooming' a small file up to fit the window. But
in reality, it is more often used to reduce a large file to fit.
Zoom mode is not the default, and has to be enabled. Once enabled, it stays on until you
turn it off again (or until you enable scaling, or select Normal (see Scaling)).
`z'
`Viewer menu, Options, Zoom (fit to window)'
Toggle zoom mode.
`Alt-r'
`Viewer menu, Options, When Zooming Reduce Only'
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. :-)
The way zoom mode reduces a file to fit the window is (relatively) quick but harsh, and
may make the picture look a bit ugly. In future there may be a smoothing option like zgv's
vkludge, but for now I'm afraid the fairly crude resize is all that's available.
There is in fact an alternative to zoom mode, as you can scale down an image instead. This
is generally only useful for very large images, however; zoom mode tends to be the Right
Thing for the most part.
SCALING
You can scale a picture --- this makes it appear larger (or smaller) onscreen. xzgv acts
much as if the scaled picture were the real picture; for example, the cursor keys scroll
around in steps of 100 scaled pixels, even if this means moving a fraction of a pixel (or
many pixels) in the original picture (and similarly for movement with the mouse).
The main limitation of scaling (other than how much it slows things down :-), at least
when scaling up) is that you can only scale 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, xzgv does no scaling, which could be considered a ratio of 1:1. Scaling up
increases that ratio. How it is increased depends on which option/key you use:
`d'
`Viewer menu, Scaling, Double Scaling'
Increase the ratio by doubling it --- this leads to ratios of 2:1, 4:1, 8:1...
`s'
`Viewer menu, Scaling, Add 1 to Scaling'
Increase the ratio by adding one --- leads to ratios of 2:1, 3:1, 4:1...
There are similar commands to decrease the ratio:
`D (Shift-d)'
`Viewer menu, Scaling, Halve Scaling'
Decrease the ratio by halving it.
`S (Shift-s)'
`Viewer menu, Scaling, Sub 1 from Scaling'
Decrease the ratio by subtracting one.
Usually the double/halve scalings are more useful.
Note that you can also double/halve the scaling by using shift-left-click on the viewer to
double, and shift-right-click to halve. This still changes scale `around' the middle of
the window though (rather than around the point clicked on, as you might expect), which is
a little strange and may possibly be changed in future.
When you scale `below' 1:1, the above commands lead to ratios of (e.g.) 1:2, 1:4, 1:8,
etc. --- that is, the ratios work the same way, but the other way around. This gives you
an increasingly small image.
The scaling ratio is never decreased below 1:32. It is also never increased beyond the
point where the overall image size would exceed 32767x32767 --- this limit is due to the
combination of X's limit on window sizes, and the implementation used by xzgv for scaling.
One problem with scaling up, given the way it's currently implemented, is that it's not
well-suited to dithered display --- so if you're running on an 8-bit server, dragging the
image around slowly when using scaling (especially scaling with interpolation) may result
in some nasty, streaky, undithered-looking parts of the picture. :-(
You can undo the effect of scaling (up or down) at any time:
`n'
`Viewer menu, Scaling, Normal'
Resume `normal' display --- disables scaling mode, and also zoom mode.
Normally, scaling up works by simply making the pixels into larger and larger squares (in
effect), which remain the same colour. However, you can enable a feature called
`interpolation' which smoothly graduates the colour change between the top-left corners of
each pixel. This is very slow, but looks nice.
`i'
`Viewer menu, Options, Interpolate when Scaling'
Toggle interpolation in scaling mode.
(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. These days it's part of the netpbm package.)
Scaling down, however, is implemented a bit like a special-case zoom mode, and currently
there are no ways of making that look nicer. :-/
xzgv normally `reverts' scaling (returning the scale to 1:1) back to normal when you view
a new picture. However, it's possible to disable this behaviour (see Viewer Options).
There is also support for an alternative form of scaling --- decoupled, or axis-specific,
scaling. When you scale in this way, only one axis of the image is scaled at once. For
example, you might choose to effectively double the height of an image (with the width
left unchanged). Indeed, this sort of scaling is useful for temporarily correcting
pictures intended for display using pixels twice as wide or high as normal.
`x'
`Viewer menu, Scaling, X Only, Double Scaling'
Increase the (x axis) ratio by doubling it.
`X (Shift-x)'
`Viewer menu, Scaling, X Only, Halve Scaling'
Decrease the (x axis) ratio by halving it.
`Alt-x'
`Viewer menu, Scaling, X Only, Add 1 to Scaling'
Increase the (x axis) ratio by adding one.
`Alt-Shift-x'
`Viewer menu, Scaling, X Only, Sub 1 from Scaling'
Decrease the (x axis) ratio by subtracting one.
`y'
`Viewer menu, Scaling, Y Only, Double Scaling'
Increase the (y axis) ratio by doubling it.
`Y (Shift-y)'
`Viewer menu, Scaling, Y Only, Halve Scaling'
Decrease the (y axis) ratio by halving it.
`Alt-y'
`Viewer menu, Scaling, Y Only, Add 1 to Scaling'
Increase the (y axis) ratio by adding one.
`Alt-Shift-y'
`Viewer menu, Scaling, Y Only, Sub 1 from Scaling'
Decrease the (y axis) ratio by subtracting one.
There are also mouse shortcuts for scaling up/down a single axis; control-left-click
scales up, and control-right-click scales down. By default this acts on the y axis, but
the active axis can be toggled with `Alt-c', or by toggling the `Ctl+Click Scales X Axis'
option (see Viewer Options).
Interpolation is not currently supported in situations where the x scaling does not match
the y scaling.
MIRROR AND ROTATE
Sometimes when viewing a picture you will want to flip it horizontally or vertically, or
rotate it:
`m'
`Viewer menu, Orientation, Mirror (horiz)'
`Mirror' the picture (flip it horizontally).
`f'
`Viewer menu, Orientation, Flip (vert)'
`Flip' the picture (flip it vertically).
`r'
`Viewer menu, Orientation, Rotate Right'
Rotate the picture 90 degrees clockwise.
`R (Shift-r)'
`Viewer menu, Orientation, Rotate Left'
Rotate the picture 90 degrees anti-clockwise. (Any US readers surprised and/or
annoyed by my not saying `counter-clockwise' will realise why the menus say rotate
right/left. :-))
`N (Shift-n)'
`Viewer menu, Orientation, Normal'
Restore the picture orientation to normal. This undoes the effect of any mirrors,
flips, and/or rotations.
xzgv 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, it's possible
to disable this (see Viewer Options), so that any new pictures are mirrored, flipped,
and/or rotated in the same way.
BRIGHTNESS AND CONTRAST
[Brightness and contrast changing is not supported in xzgv 0.9.] xzgv provides support
for changing brightness and contrast, though given the way it has to redraw the image to
do so, it can be a little slow.
Currently there is no way to do this with the mouse; this should be fixed soon.
`,'
Decrease contrast.
`.'
Increase contrast.
`<'
Decrease brightness.
`>'
Increase brightness.
`:'
`;'
Reset contrast and brightness to normal. (`*' is also supported, for hysterical
raisins.) Note that this deliberately does not affect the gamma adjustment.
Any contrast change is applied before any brightness change, and any gamma adjustment is
applied before both.
GAMMA ADJUSTMENT
[Gamma is not supported in xzgv 0.9.] Ah yes, gamma. What fun. The basic problem is this
--- differing displays have differing intensity response curves. ``This has made a lot of
people very angry and been widely regarded as a bad move.'' :-)
It means that you need some way of adjusting how brightly you display the picture to
compensate. But since we're dealing with response curves, this isn't just a matter of
changing the brightness in a linear fashion.
That doesn't seem so hard to deal with, right? All you need is to get the gamma (a number
which specifies how much the curve bends) for the image, and for the screen, divide one by
the other and adjust as appropriate. Joy.
But, given that the problem has existed since we started displaying more than eight
colours, you won't be surprised to find that it's already been fixed. And the fixes all
tend to clash, and everybody has a different notion of how to fix it. The usual `fix' is
to assume that whoever made the image made it with a gamma matching the gamma of your
display, so you can just stuff the bits right on the screen. Since this is easy, it's the
most widespread approach. But it's a bit stupid, so not everyone does it. Combine that
with the lack of gamma specification in most image formats, and the often-bogus values
specified by people in those that do, and hey presto --- the image gamma could be just
about anything. And the screen's gamma also tends not to be easily determined.
So how on earth do you deal with something like that in a remotely sane fashion?
The answer chosen in xzgv is to just live with the fact that the probability of
automatically obtaining correct values for both the screen and image gamma is basically
zero. Once you accept that, the sensible thing to do is to make it very easy and fast to
change gamma adjustment to commonly-required values. So here's how to do it:
`1'
Set gamma adjustment to 1.0, i.e. no adjustment. This is the default setting.
`2'
Set gamma adjustment to 2.2. This is useful for viewing linear-gamma files (one
classic example being raytracer output) on an average PC monitor.
`3'
Set gamma adjustment to 1 divided by 2.2, i.e. roughly 0.45. This is useful for the
reverse --- viewing average-PC-monitor-gamma files on a linear-gamma display.
Historically I believe the classic example would have been viewing PC files on a
Mac, but I don't know how true that is these days.
`4'
Set gamma adjustment to its initial value, as specified by a `--gamma' command-line
option (see Options) or equivalent config file setting (see Configuring xzgv). 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
xzgv is actually inverted from (i.e. one divided by) the true adjustment value used. This
is (believe it or not :-)) intended to avoid confusion by reflecting the fact that screen
gamma is the one most widely considered/well known.
You can also tweak the adjustment more precisely, in a similar way to brightness/contrast:
`Alt-,'
Decrease gamma adjustment (divide it by 1.05).
`Alt-.'
Increase gamma adjustment (multiply it by 1.05).
Note that `:', and the other keys which reset the brightness/contrast, deliberately avoid
resetting the gamma adjustment.
As with brightness/contrast, there is currently no way to adjust gamma with the mouse;
this should be fixed soon. (But the 1/2/3/4 keyboard-based method is likely to still be
the faster method.)
CHANGING PICTURE
It's possible to go directly to the previous or next file (or tagged file) in the
directory, or to tag a file, without having to pick the file from the file selector by
hand. These commands are particularly useful when using xzgv from the keyboard, but
there's also a notable mouse shortcut for moving to the next image.
`Space'
`Viewer menu, Next Image'
Move to next file in dir, and view it. You can also click on the picture/viewer to
do this. (If you find this interferes with dragging the picture around (though it
shouldn't), or just don't like it, it can be disabled (see Config Variables).)
`b'
`Viewer menu, Previous Image'
Move to previous file in dir, and view it.
`Ctrl-Space'
`Viewer menu, Tagging, Tag then Next'
Tag current file, then move to next file in dir and view it.
`/'
`Viewer menu, Tagging, Next Tagged'
Move to next tagged file in dir, and view it.
`?'
`Viewer menu, Tagging, Previous Tagged'
Move to previous tagged file in dir, and view it.
HIDING THE SELECTOR
When running on small screens, or in a small window, it can get a bit annoying to lose
viewer space by having the selector constantly displayed when you don't actually need it.
The usual solution to this problem is to enable auto-hide mode. But what if some pictures
you're viewing are small and some large? It can sometimes be nearly as annoying having the
selector hidden to `make room for' a small picture which didn't need it. So for that
reason, or perhaps if you just don't like auto-hide mode :-), you may prefer to leave
auto-hide off and explicitly hide the selector when necessary:
`Z (shift-z)'
`Viewer menu, Window, Hide Selector'
Hide the selector. (This is actually a toggle, of sorts; `hide selector' when it's
already hidden unhides it.)
You can also hide or unhide the selector by middle-clicking on the viewer.
MINIMIZING XZGV
Generally it's easy enough to use your window manager to change windows etc., but when
running fullscreen this can sometimes be a little problematic. For this reason, xzgv has
built-in support for `iconifying' itself:
`Ctrl-z'
`Viewer menu, Window, Minimize'
Minimize the xzgv window.
VIEWER OPTIONS
As with the selector, various options can be disabled/enabled which relate to the viewer.
These settings can also be altered using command-line options (see Options) and/or config
file settings (see Configuring xzgv).
`z'
`Viewer menu, Options, Zoom (fit to window)'
Toggle zoom mode, discussed in more detail elsewhere (see Zoom Mode).
`Alt-r'
`Viewer menu, Options, When Zooming Reduce Only'
Toggle reduce-only in zoom mode, also covered elsewhere (see Zoom Mode).
`i'
`Viewer menu, Options, Interpolate when Scaling'
Toggle interpolation when a picture is being scaled-up. Again, this has already
been mentioned (see Scaling).
`Alt-c'
`Viewer menu, Options, Ctl+Click Scales X Axis'
Toggle the axis scaled when you control-click (or control-right-click) on the
image. The default is to scale the y axis.
`F (shift-f)'
`Viewer menu, Options, Dither in 15 & 16-bit'
Toggle dithering in 15/16-bit modes. This increases the apparent colour depth
making gradations look much better, but it's slower than undithered rendering, and
can (in 16-bit) slightly distort a picture's colour balance. (The `F' key was
chosen for this as the dither toggle is functionally similar to zgv's `fakecols'
toggle.)
`Viewer menu, Options, Revert Scaling For New Pic'
Normally xzgv returns the scaling back down to 1 (normal) when a new picture is
selected. By disabling this, you can retain scaling across picture selection.
(There is currently no keyboard shortcut for this fairly-seldom-changed option ---
to toggle it from the keyboard, you should use the popup menu (press `F10'), and
select the menu item.)
`Viewer menu, Options, Revert Orient. For New Pic'
Similarly, xzgv returns to the picture's true orientation (not mirrored, rotated,
etc.) on selecting a new picture. Disabling this option means that any
mirrors/flips/rotates applied persist across multiple images. (No keyboard
shortcut --- see above.)
`Viewer menu, Options, Use Exif Orientation'
Toggle support for Exif orientation. Devices which create JPEG files in the Exif
format (e.g. many digital cameras) may add an orientation tag to the file, which
says how the camera was being held when the picture was taken. When this tag is
present, xzgv can adjust the image to compensate for a camera being held on its
side. (This isn't done by default as it misrepresents the true image, which could
be confusing if you don't know why it's happening.) Enabling this option may be
useful if you take pictures with your camera on its side, but don't want to have to
rotate the pictures before being able to view them properly. Of course, for this to
work your camera has to be inserting the orientation tag in the first place --- but
it can't hurt to try it and see. (No keyboard shortcut --- see above.)
FILE FORMATS
Picture files are stored in a variety of different forms, or `file formats'. xzgv, via
gdk, supports many.
FILE TYPE IDENTIFICATION
The format a file is in is identified by its content. The file-reading code relies on
libgdk to determine the file type and read the file correctly; generally this uses the
format's `magic number' to determine file type --- e.g. a JPEG/JFIF file starts with the
(hex) bytes `FF D8'. So if you start xzgv with xzgv foo, and foo is in a supported format
(such as JPEG), the format will be figured out and the file loaded even though the
`extension' is absent.
CONFIGURING XZGV
Many aspects of the way xzgv works can be modified by using a configuration file.
CONFIG FILES
A configuration file lets you alter aspects of xzgv's behaviour. xzgv supports two
possible config files --- a system-wide one, /etc/xzgv.conf; and one for each user in
their home directory, $HOME/.xzgvrc. Both are optional. If $HOME/.xzgvrc exists, it is
used instead of /etc/xzgv.conf.
Before describing the format of config files, it may help to give an example file:
# Sample xzgv config file
# Comment lines begin with `#' and are ignored,
# as are blank lines.
# make pics fit window
zoom on
# hog the screen :-)
fullscreen on
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'. xzgv has many such
variables it lets you modify in this way. For example, the fullscreen option above
controls whether or not xzgv tries to use the whole screen for its window. If it is given
the value `on'/`y'/`yes'/`1' it does; if `off'/`n'/`no'/`0', it doesn't. Most variables
are of this yes-or-no `boolean' type.
Since the variables set in a config file have a direct effect on how xzgv 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 xzgv's config file variables
are of this type.
- Integer (currently unused). 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 gamma
variable is of this type.
- Geometry. This window size-and/or-position specification format is only used for the
`geometry' setting. See Options, for a description of how this type works.
CONFIG VARIABLES
Currently, most configuration variables (settings) in xzgv can also be set by command-line
options; indeed, the name of the setting in all such cases is identical to that for the
long version of the option (e.g. `fullscreen', `auto-hide'). As such, they're documented
in the section which discusses command-line options and the like (see Options).
However, there are some settings only available in the config file:
click-for-next
This is enabled by default, allowing you to click on the viewer to skip to the next
image. If disabled, clicking on the viewer does nothing.
RATIONALE
Here I (RJM) attempt to explain why I did things the way I did. This is presented in a
question-and-answer format of sorts.
WHY YET ANOTHER VIEWER?
Previously, this section concentrated on xv; that may have made sense when I originally
wrote it, and still makes a certain limited amount of sense for zgv, but for xzgv it was
looking increasingly dated. And so here I am writing an update. :-)
I originally wrote xzgv as I simply wasn't happy with the viewers for X that I was aware
of at the time (mid-1999). At the time of writing (late 2000), other key things about xzgv
are becoming apparent, partly through responses I've been getting to it:
o It's `fast'. No, it doesn't do any particular operation faster than other viewers as far
as I know (well, maybe thumbnail updates :-)); rather, the interface tries not to get in
your way. Click on a filename, and the picture appears. No multiplicity of toolbars or
windows, it's just there.
o As with zgv, it tries to do one thing well, viewing pictures. It isn't perfect in this
regard, I'll admit, but at least it stays well clear of picture editing.
o It's, er, quite a lot like zgv. Some of us old fogies like this. :-)
I won't pretend xzgv is The Ultimate Viewer For Everyone. Some people will prefer other
approaches, or just simply prefer other viewers. (Some people may even still use xv, ghod
forbid.) There are a few viewers which you may like to try if you don't think much of
xzgv:
o gqview. This seems to be well-regarded. I find it a bit gimmicky and kitchen-sink-ish;
not quite as `pure' or focused as xzgv, IMHO. I think more people use it than xzgv though.
o xli. I'm not sure if this is maintained these days, but it's not too bad a viewer. No
thumbnails or file selector though. (These days I mostly use this for setting the root
window pixmap, something I don't think belongs in a viewer, but which xli does happen to
be quite good at.)
o qiv. If I read between the lines correctly, this is essentially a modern replacement for
xli.
o gtksee. I've not tried this, but I think the idea is that it's an ACDSee clone, and
there seem to be an awful lot of people who want a clone of that. Which is their problem.
:^)
o Electric Eyes. To be honest, I think this has been outclassed by other viewers these
days, which shows how far we've come.
Ah, you say, what of xv? Well, we've emphatically reached the point where no-one need use
xv any more. Anyone using xv these days really should drop that pile of ill-conceived non-
Free crap and use one of the better viewers now available. It's that simple.
WHY NO IMAGE-EDITING CAPABILITIES?
It's a fscking viewer, dammit. If you want xv you know where to find it.
(OTOH, if you want a decent image editor, use the Gimp.)
WHY A TEXINFO MANUAL?
For years, I maintained a conventional `man page' for zgv (which xzgv was loosely based
on). But over time, I realised just how impossibly confusing the zgv man page had become.
So I wanted to rewrite zgv's documentation in a more sensible way, in some other format
than a man page. I wanted an established, well-supported format with structure and cross-
referencing. I felt this made it a choice between HTML and texinfo. HTML seemed to me to
be a moving target like no other, and not as well supported on text-only terminals as Info
(and thus texinfo). (This latter point is admittedly not too relevant as far as xzgv is
concerned.) When I noticed that a converter existed to convert texinfo to HTML in any
case, the case was closed. xzgv's documentation was then based on zgv's --- the
documentation is probably more similar than the programs are. :-)
Don't get me wrong --- I like man pages. And even with the excellent Texinfo documentation
and Emacs' very helpful Texinfo mode, writing texinfo is hardly easy. (Without Texinfo
mode's node- and menu-update commands, I personally would find it near-impossible!) But
big man pages just aren't that good for reference, and this is made worse by the relative
lack of structure.
WHY ONE-SPACE SENTENCE ENDS?
The conventional way to write texinfo is to follow each sentence with two spaces after the
dot (or whatever ends the sentence). Many people normally write this way in a non-texinfo
context too. But a sizeable proportion of people normally write text with only one space
after the dot --- and I'm one of them.
The Texinfo documentation gives the impression that two-space must be used; it says ``it
is important to put two spaces at the end of sentences in Texinfo documents.'' But the
only circumstance in which spacing from the texinfo file is preserved at all (in any sense
other than `there is a space here') is when the texinfo is converted to Info format. So,
in fact, the decision to use two-space depends on how the author wants Info output to
appear --- this is a subjective decision which should be entirely down to the preference
of the author, despite the Texinfo documentation's attempt to make two-space sound like an
objective you-must-do-this kind of thing.
You might wonder what the problem with using one-space is, then. Well, `makeinfo' has to
reformat paragraphs, and whenever it needs to insert space at (what appears to it to be)
the end of a sentence, it inserts two spaces. This behaviour cannot be altered, unlike in
Emacs (sentence-end-double-space; see Fill Commands in the emacs info file) and GNU fmt
(-u; see fmt invocation in the textutils info file). Also, attempting to `fix' the output
Info with sed doesn't work properly because the `tags' used to find nodes quickly are then
incorrect. These could of course also be fixed, but this would involve a lot more work
than a simple sed invocation.
So realistically, anyone who writes texinfo with one-space has to put up with the
occasional two-space sentence end being inserted into their text --- worse still, the
current `makeinfo' formatting algorithm seems to insert two spaces even after
abbreviations (such as `e.g.' and `etc.'), which breaks even two-space texinfo. (This is
particularly ironic, by the way, since two-space partisans' main argument in favour of the
practice is often 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/GDK, (Linux) IPC, and viper, and I expect there are instances I'm not aware of.
BUGS AND RESTRICTIONS
All (non-trivial) programs have bugs. Anyone who denies this...
- clearly hasn't written too many programs.
- is wrong. ;-)
It follows that xzgv, like everything else, always has some bugs. Usually these are not
too serious, or I'd have fixed them before releasing xzgv. But either way, bugs and other
problems with xzgv are noted here.
KNOWN BUGS
- In zoom mode, it copes with resizing the window as a whole, but doesn't when you change
the size of the pane (apart from when hiding/showing selector or resizing from keyboard,
but that's only 'cos I kludged it :-)).
- When scaling up and dithering, you end up with a crappy-looking picture if you drag the
picture around slowly (since each exposed bit is dithered independently, with no regard
given to matching up to any previous error-diffusion).
- Scaling up is slow. Not sure if I can do much about this.
- Using an alignment widget to centre the viewer window results in some annoying `bounce'
in certain resizing situations etc.
- Thumbnails don't look so great in palette-based (e.g. 8-bit) modes.
- When dragging an image around, if you quickly move the mouse pointer over from the image
area to the selector area, the image seems to `jump' a little. I think this may have
something to do with the paned window's window-splitting bit, but I'm not sure. Also, it
jumps when moving across scrollbar sliders and the paned window splitter handle.
- It doesn't apply any tranparency mask. The practical result of this seems to be purple
transparent bits in thumbnails and scaled-up images, and black transparent bits elsewhere.
This doesn't affect PNG files, though.
- 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.
- If you look up `joe code' in a dictionary, right next to ``see zgv'' it now says ``but
for really in-depth insight into the joe code nature, see xzgv''. :-)
SUBOPTIMAL FEATURES
- Thumbnails are given an accurate width/height `IMGINFO' comment, but are always claimed
to be "RGB".
- xzgv doesn't duplicate zgv's behaviour of generating thumbnails under
~/.xvpics/_foo_bar_baz if it can't generate them in /foo/bar/baz/.xvpics. I doubt anything
else supported it, and it complicated lots of things unnecessarily. This isn't
particularly suboptimal, but as an incompatibility with zgv it merits mention.
RESTRICTIONS
- Only the first image of a multiple-image GIF is used. (These days, multiple-image GIFs
are usually animations.)
REPORTING BUGS
If you find xzgv does something wrong, which you suspect might be a fault of some sort (a
bug) in the program, it is best to report it as I may not be aware of the problem. (But
first, check it is not a `known bug'. See Known Bugs. It is not usually helpful to report
a bug I already know about.)
It is important to include as much detail in a bug report as you can. Here are some
details you should include:
o The version of xzgv you are running. `xzgv --version' reports this.
o The versions of GTK+ you are using. `xzgv --version-gtk' reports the GTK+ version being
used by xzgv.
o The bitdepth your X server is running in (common depths are 16-bit, 24-bit, and 32-bit).
If you don't know what depth you're running in, try `xdpyinfo|grep depth'.
o A description of the bug --- what effects it has, the circumstances it occurs in, and so
on. Does it only happen for certain types of file? Only when in 8-bit modes? Only when
dithering is enabled? Even `irrelevant' details can sometimes be useful.
o Finally, if you are a programmer and believe you have managed to fix the bug yourself,
patches are gratefully accepted. :-) You should generate the patch using `diff -c' or
(preferably) `diff -u'.
So, if you think you've found a bug in xzgv, report it by emailing me at <rrt@sc3d.org>.
REPORTING DOCUMENTATION BUGS
Bugs in the documentation can sometimes cause as much trouble as bugs in the program; if
you notice a problem in the documentation, it's a good idea to report it.
For reports of documentation bugs, you should include these details:
o The version of xzgv the documentation is for.
o If it is a problem in one specific section of the documentation, specify which part it
is (by this I mean the heading it comes under; texinfophiles should read this as `the node
name' :-)).
o The format of the documentation you saw the problem in (e.g. info, man page, HTML).
o A description of the problem.
FUTURE CHANGES
See Reporting Bugs, for details of where to send the bug report. If you want to suggest a
feature you'd like in xzgv, or a change to an existing feature, contact me; see See
Reporting Bugs for the address.
Future changes etc. are listed in the TODO file.
AUTHOR
Russell Marks <rus@svgalib.org> and others; see the section ACKNOWLEDGEMENTS for details.
SEE ALSO
zgv(1), xv(1), cjpeg(1), djpeg(1), pbm(5), pgm(5), ppm(5), mrf(5)