\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename xzgv.info
@settitle The xzgv manual
@setchapternewpage odd
@c %**end of header

@c To make an Info file from this, do `make info'.
@c To make a DVI file from this (usually for printing), do `make dvi'.

@set VERSION 0.9
@set UPDATED 9th August 2017


@c XXX could do with a general discussion of the window layout
@c (selector on left, viewer on right, splitter (w/`handle') determining
@c relative size), to add to `a note on notation' section (which would
@c presumably then need renaming).


@c Most categories seem to suffer from being too specific, making them
@c effectively useless; hopefully this one is at least nicely generic.
@c This is `ifinfo' to stop texi2{html,roff} seeing it, as they don't
@c handle it.
@ifinfo
@dircategory Graphics Utilities
@direntry
* xzgv: (xzgv). A picture viewer for X, with a thumbnail-based file
                selector.
@end direntry
@end ifinfo

@c Some notes on the use of indexes here:
@c - The keystroke index is used for keys, but called the `keyboard
@c   commands index'.
@c - The function index is used for menu items.
@c - The variable index is used for config file entries, as that's
@c   pretty much what they are.


@c Texinfo's way of handling copyright messages is, to say the least,
@c bloody awful. You have to have the whole lot twice. (I'm not sure I can
@c think of a better way, but that's not the point. :-))

@ifinfo
The xzgv manual, for version @value{VERSION}, last updated
@value{UPDATED}.

Copyright 1999-2001 Russell Marks.
Copyright 2007 Reuben Thomas.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
@end ifinfo

@titlepage
@title xzgv
@subtitle A picture viewer for X, with thumbnail-based file selector
@subtitle version @value{VERSION}
@author Russell Marks and Reuben Thomas

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1999-2001 Russell Marks.
Copyright @copyright{} 2007 Reuben Thomas.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.

@end titlepage

@ifinfo
@node    Top, Overview, (dir), (dir)
@top The xzgv manual

xzgv is a reasonably full-featured picture viewer for X, with a
thumbnail-based file selector. (xzgv uses the GTK+ libraries.)
It can read most file formats.

This documentation is for xzgv version @value{VERSION}, last updated
@value{UPDATED}.

@menu
* Overview::                    A simple look at how to use xzgv.
* Acknowledgements::            Who did what.

* Invoking xzgv::               Command-line options.

* A Note on Notation::          How keys and menu items are shown.

* The File Selector::           How to pick files to view, and more.
* The Viewer::                  What you can do when a picture is onscreen.
* File Formats::                Issues related to the way picture files
                                  are stored.
* Configuring xzgv::            You can change aspects of xzgv's behaviour.

* Rationale::                   The thinking behind certain things.
* Bugs and Restrictions::       Problems with xzgv, and how to report bugs.
* Future Changes::              Pending ideas for xzgv features etc.

 --- Indexes ---

* Keyboard Commands Index::     What various keys do in xzgv.
* Menu Item Index::             An index of the popup menus.
* Configuration Variables Index::  Settings in xzgv's config file(s).
* Concept Index::               General index of topics covered.
@end menu

@end ifinfo


@node  Overview, Acknowledgements, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Overview

@cindex introduction to xzgv
@cindex overview

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
(@pxref{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
@code{xzgv} (@pxref{Invoking xzgv}). 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 @kbd{u}. @xref{Updating
Thumbnails}.)

When you've picked a file to view, you can view it by clicking on it, or
pressing @kbd{Enter}. This reads the picture and displays
it in the right-hand part of the window, the viewer (@pxref{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 @kbd{Esc} or @kbd{Tab} first if using the
keyboard), or you can quit xzgv by pressing @kbd{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.


@node  Acknowledgements, Invoking xzgv, Overview, Top
@comment  node-name,  next,  previous,  up
@chapter Acknowledgements

@cindex acknowledgements
@cindex credits

@c first, direct (or direct-ish :-)) xzgv contributions:

xzgv was primarily written by Russell Marks, also the author of this
manual. It is maintained by Reuben Thomas, who ported it to Gtk+ 2.

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
@file{dir-close.xpm}. I think Tuomas Kuosmanen was responsible for
that, judging from the change log.

@code{mkinstalldirs} is straight from the @code{texinfo} package, and
was written by Noah Friedman. (This is also used during installation.)

@c now libraries etc.:

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! :-))

@file{getopt*.[ch]} are from the GNU libc.

@node  Invoking xzgv, A Note on Notation, Acknowledgements, Top
@comment  node-name,  next,  previous,  up
@chapter Invoking xzgv

@cindex invoking xzgv
@cindex starting xzgv
@cindex running xzgv
@cindex command-line options
@cindex options, command-line
@cindex arguments, command-line
@c NB: no `command-line args' since you'll see `command-line options' if
@c you look for that.

@c some for `xzgv file', `xzgv dir'
@cindex starting on given directory
@cindex directory, starting on given
@cindex viewing only one file
@cindex file, viewing only one
@cindex picture, viewing only one

@c for --geometry
@cindex geometry, specifying the window
@cindex size, changing initial window
@cindex dimensions, changing initial window
@cindex position, changing initial window
@cindex location, changing initial window

@c for --selector-width
@cindex initial selector size, specifying
@cindex default selector size, specifying
@cindex size, changing default selector

Normally you'd invoke xzgv as plain @code{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:

@example
xzgv [@var{options}] [@var{dir} | @var{file} ...]
@end example

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
@code{--} (@pxref{Configuring xzgv}), though a few command-line options
are not permitted as config file settings (e.g. @code{help}), and vice
versa.

Here's what the options do:

@table @code
@item -a
@vindex auto-hide
@itemx --auto-hide
Automatically hide selector when a picture is selected, allowing the
viewer to use the whole window.

@vindex careful-jpeg
@item --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.''

@vindex delete-single-prompt
@item --delete-single-prompt
(Note that this is normally enabled; use
@code{--delete-single-prompt=off} to disable it.) If @emph{disabled},
xzgv will immediately delete a file when told to, without prompting for
confirmation. (It's @code{single} because deleting multiple files at
once will be supported in future, and that will have a separate prompt
override.)

@vindex dither-hicol
@item --dither-hicol
Use dithering in 15/16-bit, whatever the default setting is.
@xref{Viewer Options}, for a discussion of benefits/drawbacks. You can
also use @code{--dither-hicol=off} to disable this.

@vindex exif-orient
@item --exif-orient
In JPEG files, use Exif orientation tags (inserted by e.g. digital
cameras) to correct image orientation before display. @xref{Viewer
Options}, for details.

@vindex fast-recursive-update
@item --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 @emph{huge} number of small directories for which few
if any updates are needed.

@item -f
@vindex fullscreen
@itemx --fullscreen
Run fullscreen, using the entire screen for xzgv's window, without even
any window-manager decorations (window frame, title bar, etc.) if
possible.

@item -g @var{geom}
@vindex geometry
@itemx --geometry @var{geom}
Set the xzgv window's geometry (position and/or size) to @var{geom}. The
geometry string should be in the usual X format, with the extension that
positions/sizes may have a @code{%} suffix meaning that they are treated
as percentages of the screen width/height. The default geometry is
@code{92%x85%}.

@c not using @var below because it produces lowercase italics in TeX
@c output, which is nasty in this context IMHO.

For those unfamiliar with the way `geometry' works, here's a brief
description of the syntax. It's @code{WxH}, or @code{+X+Y}, or
@code{WxH+X+Y}, where @code{W} is width, @code{H} height, @code{X} the x
position, and @code{Y} the y position. The first form specifies only the
size, the second only the position --- the @code{WxH+X+Y} form specifies
both.

Now, the @code{+X+Y} bit normally specifies where the top-left of the
window is. But you can use @code{-} instead of @code{+} 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 @code{+}
and @code{-} --- so @code{+-50+0} puts the window partly off the left of
the screen, and @code{+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 @code{%} to specify percentages of the screen width/height rather
than pixels, e.g. @code{50%x30%-30%-20%}. It also allows you to use real
numbers such as @code{12.34}, which can be useful with @code{%}.

@item -h
@c not config var
@itemx --help
Display a list of options and a terse description of what the options
do.

@vindex image-bigness-threshold
@item --image-bigness-threshold @var{numpix}
Set the boundary @var{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.

@item -i
@vindex images-only
@itemx --images-only
Shows only directories and image file types in the selector, identified
by their extensions.

@vindex interpolate
@item --interpolate
Interpolate between the picture's pixels when scaling up
(@pxref{Scaling}). This usually looks nicer, but it's rather slow.

@vindex mouse-scale-x
@item --mouse-scale-x
If enabled, control-clicking on the viewer scales only the X axis. (The
default is to scale only the Y axis.)

@vindex revert-orient
@item --revert-orient
(Note that this is normally enabled; use @code{--revert-orient=off} to
disable it.) If @emph{disabled}, orientation (flip/mirror/rotate) state
is retained between pictures (@pxref{Viewer Options}).

@vindex revert-scale
@item --revert-scale
(Note that this is normally enabled; use @code{--revert-scale=off} to
disable it.) If @emph{disabled}, scaling is retained between pictures
(@pxref{Viewer Options}).

@vindex selector-width
@item --selector-width
Set the default/initial size of the selector in pixels. The normal
setting is 200.

@item -T
@c not config var
@itemx --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.

@vindex show-thumbnail-messages
@item --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. :-)

@item -k
@vindex skip-parent
@itemx --skip-parent
For the first directory shown, skip the cursor past @file{..} (the
parent dir). This can be useful when you'd like to immediately use space
to `page' through the dir.

@item -o @var{order}
@vindex sort-order
@itemx --sort-order @var{order}
Set the initial sorting order used in the selector. Possible settings
are @code{name}, @code{ext}, @code{size}, and @code{date} (or
@code{time}); only the first char of the setting
(@code{n}/@code{e}/@code{s}/@code{d}/@code{t}) need be given. The
default is name order.

@vindex sort-timestamp-type
@item --sort-timestamp-type @var{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 (@code{m}/@code{c}/@code{a}) need be given.

@vindex statusbar
@item --statusbar
Show a status bar below the selector; this, for example, says when a
picture is being read.

@item -t
@vindex thin-rows
@itemx --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.

@item -v
@c not config var
@itemx --version
Show version number.

@c not config var
@item --version-gtk
Show version number of GTK+ xzgv is using.

@item -z
@vindex zoom
@itemx --zoom
Fit picture to viewer window, whatever its actual size (@pxref{Zoom
Mode}).

@item -r
@vindex zoom-reduce-only
@itemx --zoom-reduce-only
When in zoom mode, only @emph{reduce} pictures to fit; i.e. make big
pictures viewable all-at-once while leaving small picures intact.

@item -p
@vindex zoom-panorama
@itemx --zoom-panorama
When in zoom mode, adjust only the most proportional dimension to fit,
and allow scrolling on the other dimension; i.e. like a @emph{fit page width}
option in PDF readers, but not limited to horizontal adjusting.
@end table

If started with @code{xzgv @var{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 @code{xzgv @var{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. @code{-z} or @code{--zoom}. However, there's an
alternative long-option form for setting these, resembling how they're
set in config files --- the syntax is @code{--option=@var{state}}, where
@var{state} is @code{on}/@code{y}/@code{yes}/@code{1} to enable the
option, or @code{off}/@code{n}/@code{no}/@code{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. @code{--zoom=off}.

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


@node  A Note on Notation, The File Selector, Invoking xzgv, Top
@comment  node-name,  next,  previous,  up
@chapter A Note on Notation

@cindex notation used in this manual
@cindex conventions used in this manual
@cindex menu item descriptions, format of
@cindex format of menu item descriptions
@cindex help on this manual's 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 @kbd{F10} or @kbd{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:

@table @kbd
@item key
@itemx Selector menu, Menu the item is in, Menu item
Description of what the key/menu item does.
@end table

Sometimes the key given has a @kbd{(Selector)} or @kbd{(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.


@node  The File Selector, The Viewer, A Note on Notation, Top
@comment  node-name,  next,  previous,  up
@chapter The File Selector

@c XXX could do with synonyms for `selector' here...
@cindex file selector
@cindex the file selector
@cindex 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.

@menu
* The Selector Menu::           Right-click on the selector to see its
                                  menu.
* Exiting xzgv::                Why would you want to? :-)
* Thumbnails::                  How to create thumbnails, and how they
                                  work.
* Selector Layout and Resizing::  The file selector lists dirs/files,
                                  and can be resized if you find it too
                                  large/small.
* Moving Around The List::      How to see all of the list, and how to
                                  move the keyboard cursor.
* Viewing a File::              How to view a single file.
* Dialog Boxes::                How xzgv reports errors and asks you things.
* Closing a File::              Closing files is unnecessary, but it
                                  does clear the viewer subwindow.
* File Details::                Showing a file's size, date/time, etc.
* Tagging::                     You can tag (mark) multiple files, then
                                  copy/move them.
* Renaming a File::             Renaming a single file or directory.
* Deleting a File::             Redirecting a file to the great bit
                                  bucket in the sky.
* Changing Directory::          As well as the normal dir-by-dir way,
                                  you can jump directly to a directory.
* Rescanning the Directory::    Updating xzgv's view of a directory's
                                  contents.
* Changing the Sorting Order::  Files can be sorted by name,
                                  `extension', size, and date/time.
* File Selector Options::       Some selector-related options can be
                                  changed while xzgv is running.
@end menu


@node  The Selector Menu, Exiting xzgv, The File Selector, The File Selector
@comment  node-name,  next,  previous,  up
@section The Selector Menu

@cindex selector menu, getting the
@cindex menu, getting the selector
@cindex getting the selector menu
@cindex showing the selector menu
@cindex online help
@cindex help
@cindex menus, help
@kindex F10 (Selector)
@kindex Menu (Selector)

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 @kbd{F10} or @kbd{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 @samp{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. @samp{Details} on the @samp{File}
menu, you need to right-click @emph{on the file you want details on}.

Both the selector and viewer have `Help' menus, most items of which
refer you to this manual:

@table @kbd
@kindex F1
@item F1
@findex Selector menu, Help, Contents
@itemx Selector menu, Help, Contents
@findex Viewer menu, Help, Contents
@itemx Viewer menu, Help, Contents
View the manual's overall contents.

@findex Selector menu, Help, The File Selector
@item Selector menu, Help, The File Selector
View the manual's section on the file selector.

@findex Viewer menu, Help, The Viewer
@item Viewer menu, Help, The Viewer
View the manual's section on the viewer.

@findex Selector menu, Help, Index
@item Selector menu, Help, Index
@findex Viewer menu, Help, Index
@itemx Viewer menu, Help, Index
View the manual's concept index.

@findex Selector menu, Help, About
@item Selector menu, Help, About
@findex Viewer menu, Help, About
@itemx Viewer menu, Help, About
Give some brief information about xzgv, including the version number and
homepage.
@end table

Currently, the way xzgv lets you read the manual is a bit crude; it runs
the @code{info} program (@pxref{Top,,,info-stnd,Standalone info
program}) in an @code{xterm}.


@node  Exiting xzgv, Thumbnails, The Selector Menu, The File Selector
@comment  node-name,  next,  previous,  up
@section Exiting xzgv

@cindex exiting xzgv
@cindex quitting xzgv
@cindex leaving xzgv
@cindex xzgv, exiting

You can exit xzgv either by using one of two exit keypresses, or by
selecting the appropriate option from the selector's popup menu:

@table @kbd
@kindex q
@item q
@kindex Ctrl-q
@itemx Ctrl-q
@findex Selector menu, Exit xzgv
@itemx Selector menu, Exit xzgv
Quit xzgv.

@end table

@findex Selector menu, File, Exit
(There's also an exit option on the selector's @samp{File} menu
(@code{Selector menu, File, Exit}), as `Exit' is generally on any File
menu.)


@node  Thumbnails, Selector Layout and Resizing, Exiting xzgv, The File Selector
@comment  node-name,  next,  previous,  up
@section Thumbnails

@cindex thumbnails
@cindex picture thumbnails
@cindex file thumbnails
@cindex xv-compatible thumbnails
@cindex Gimp-compatible 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).

@menu
* Updating Thumbnails::         How to create or update thumbnails.
* Thumbnail Issues::            Thumbnails are read `in the background',
                                  and need 256 colours to be shown
                                  correctly.
@end menu

@node  Updating Thumbnails, Thumbnail Issues, Thumbnails, Thumbnails
@comment  node-name,  next,  previous,  up
@subsection Updating Thumbnails

@cindex updating thumbnails
@cindex creating thumbnails
@cindex making thumbnails
@cindex thumbnails, creating
@cindex thumbnails, updating
@cindex directory, updating thumbnails in a
@cindex recursively, updating thumbnails
@cindex tree, updating all thumbnails in a directory

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
@file{.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
@kbd{u}, or select @samp{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 @kbd{Alt-u} or @samp{Recursive
Update}. But be warned that a recursive update can take some time!

@table @kbd
@kindex u
@item u
@findex Selector menu, Update Thumbnails
@itemx 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
@samp{Cancel} button, or pressing @kbd{Esc} or @kbd{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).

@kindex Alt-u
@item Alt-u
@findex Selector menu, Recursive Update
@itemx 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 (@pxref{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).

@c a reference to the next node is pretty dire, but if I say `next
@c node', how would that look in a printed copy? :-/

By default, xzgv behaves a little oddly when doing a recursive update,
to give some consistency with the normal update. @xref{Thumbnail
Issues}, for details.

@end table


@node  Thumbnail Issues,  , Updating Thumbnails, Thumbnails
@comment  node-name,  next,  previous,  up
@subsection Thumbnail Issues

@c XXX could do with one here which doesn't start "thumbnails" :-)
@cindex thumbnails, issues relating to
@cindex thumbnails, problems with displaying
@cindex recursive update, problem with
@cindex tree, problem with updating directory

Dealing with thumbnails can be `interesting' at times, and there are a
few ways this influences things:

@itemize @minus
@item
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 @emph{is} responding. :-)

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

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

@item
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
@code{--fast-recursive-update} command-line option (@pxref{Invoking
xzgv}) or equivalent config file entry (@pxref{Configuring xzgv}).)
@end itemize


@node  Selector Layout and Resizing, Moving Around The List, Thumbnails, The File Selector
@comment  node-name,  next,  previous,  up
@section Selector Layout and Resizing

@cindex selector layout
@cindex layout, selector
@cindex file selector, layout of
@cindex resizing selector/viewer
@cindex size, changing selector/viewer
@cindex changing relative sizes of selector/viewer
@cindex normal size, returning selector to

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; @pxref{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 @samp{-f} option (@pxref{Invoking xzgv}), and/or use `thin rows'
mode (@pxref{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:

@table @kbd
@kindex [
@item [
Move the window split left.

@kindex Ctrl-[
@item Ctrl-[
Move the window split left more slowly.

@kindex ]
@item ]
Move the window split right.

@kindex Ctrl-]
@item Ctrl-]
Move the window split right more slowly.

@kindex ~
@item ~
Reset the window split to its default position.
@end table

You can also set the initial/default size of the selector --- in effect,
the position of the window split --- using @code{--selector-width}
(@pxref{Invoking xzgv}) or the config file option @code{selector-width}.


@node  Moving Around The List, Viewing a File, Selector Layout and Resizing, The File Selector
@comment  node-name,  next,  previous,  up
@section Moving Around The List

@cindex moving around the file list
@cindex file selector, moving around
@cindex file selector, cursor movement in
@cindex keyboard, moving around the selector via
@cindex cursor, file selector
@cindex choosing a file
@cindex selecting a file
@cindex picture, selecting

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:

@itemize @minus
@item
It selects a file for view commands to operate on.

@item
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).
@end itemize

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:

@table @kbd
@kindex Cursor Up (Selector)
@item Cursor Up
@kindex k (Selector)
@itemx k
Move up.

@kindex Cursor Down (Selector)
@item Cursor Down
@kindex j (Selector)
@itemx j
Move down.

@kindex Page Up (Selector)
@item Page Up
@kindex Ctrl-a (Selector)
@itemx Ctrl-u
Move the cursor back roughly a page.

@kindex Page Down (Selector)
@item Page Down
@kindex Ctrl-v (Selector)
@itemx Ctrl-v
Move the cursor forward roughly a page.

@kindex Ctrl-Home (Selector)
@item Ctrl-Home
@kindex Ctrl-a (Selector)
@itemx Ctrl-a
Move the cursor to the start of the list.

@kindex Ctrl-End (Selector)
@item Ctrl-End
@kindex Ctrl-e (Selector)
@itemx Ctrl-e
Move the cursor to the end of the list.

@kindex g (Selector)
@item g
@kindex ' (Selector)
@itemx '
Move the cursor to the first filename starting with the next key
pressed, which would generally be a letter or number. Case is
significant; @kbd{a} and @kbd{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.

@end table


@node  Viewing a File, Dialog Boxes, Moving Around The List, The File Selector
@comment  node-name,  next,  previous,  up
@section Viewing a File

@cindex viewing a file
@cindex file selector, viewing a file from the
@cindex picture, viewing a

To view a file from the selector, you can click on it, or press
@kbd{Enter} after moving the cursor to the relevant file,
or right-click on the file and choose `File' then `Open'.

@table @kbd
@kindex Enter (Selector)
@item Enter
@itemx Left-click-on-file
@itemx Selector menu, File, Open
View the chosen picture file, or if a subdirectory is chosen, make that
the current directory.
@end table

@xref{The Viewer}, for details of how the viewer works.


@node  Dialog Boxes, Closing a File, Viewing a File, The File Selector
@comment  node-name,  next,  previous,  up
@section Dialog Boxes

@cindex dialog boxes
@cindex messages
@cindex errors
@cindex directory dialog

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 @samp{Ok} (or press @kbd{Enter} or
@kbd{Esc}).

xzgv also uses similar dialog boxes for other things:

@itemize @minus
@item
Getting confirmation that you want to do something. @kbd{Enter} or
@kbd{y} picks `yes'; @kbd{Esc} or @kbd{n} picks no. (Again, you can
click on the relevant button with the mouse to do the same.)

@item
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 @samp{Cancel} button which you can click to
abort the update (pressing @kbd{Enter} or @kbd{Esc} does the same).

@item
Reading a directory name. Here you should type the directory name then
click @samp{Ok} (or press @kbd{Enter}), or click @samp{Cancel} (or press
@kbd{Esc}) to abort. The text-input `widget' used allows a certain
amount of editing, including these keys:

@table @kbd
@kindex Cursor Left (Dir dialog)
@item Cursor Left
@kindex Ctrl-b (Dir dialog)
@itemx Ctrl-b
Move the cursor left. (A vertical bar shows the cursor position.)

@kindex Cursor Right (Dir dialog)
@item Cursor Right
@kindex Ctrl-f (Dir dialog)
@itemx Ctrl-f
Move the cursor right.

@kindex Home (Dir dialog)
@item Home
@kindex Ctrl-a (Dir dialog)
@itemx Ctrl-a
Move the cursor to the start of the line.

@kindex End (Dir dialog)
@item End
@kindex Ctrl-e (Dir dialog)
@itemx Ctrl-e
Move the cursor to the end of the line.

@kindex Backspace (Dir dialog)
@item Backspace
@kindex Ctrl-h (Dir dialog)
@itemx Ctrl-h
Delete char to the left of the cursor. (Note that @kbd{Backspace} is
(usually) the key above the main @kbd{Enter} key; it is often labelled
simply as an arrow.)

@kindex Delete (Dir dialog)
@item Delete
@kindex Ctrl-d (Dir dialog)
@itemx Ctrl-d
Delete the char the cursor is on.
@end table

You can also set the X selection (by selecting text with the mouse, or
holding @kbd{Shift} while moving the cursor) to allow pasting text into
other programs, and you can cut/copy/paste text in the usual ways:

@table @kbd
@kindex Shift-Delete (Dir dialog)
@item Shift-Delete
@kindex Ctrl-x (Dir dialog)
@itemx Ctrl-x
Cut text.

@kindex Ctrl-Insert (Dir dialog)
@item Ctrl-Insert
@kindex Ctrl-c (Dir dialog)
@itemx Ctrl-c
Copy text.

@kindex Shift-Insert (Dir dialog)
@item Shift-Insert
@kindex Ctrl-v (Dir dialog)
@itemx Ctrl-v
Paste text.
@end table

You can paste text from (some) other programs using the latter command,
too.
@end itemize


@node  Closing a File, File Details, Dialog Boxes, The File Selector
@comment  node-name,  next,  previous,  up
@section Closing a File

@cindex closing a file
@cindex file, closing a
@cindex clearing the viewer
@cindex viewer, clearing the

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.

@table @kbd
@kindex Ctrl-w
@item Ctrl-w
@findex Selector menu, File, Close
@itemx Selector menu, File, Close
`Close' the currently-viewed file, clearing the viewer subwindow.
@end table


@node  File Details, Tagging, Closing a File, The File Selector
@comment  node-name,  next,  previous,  up
@section File Details

@c This is a bit severe, but there are so many ways of thinking about it...
@cindex file details
@cindex details on a file, getting
@cindex showing file size, date, etc.
@cindex size, showing a file's
@cindex date, showing a file's time and
@cindex time, showing a file's date and
@cindex modification date/time, showing a file's
@cindex last-modified date/time, showing a file's
@cindex dimensions, showing a file's
@cindex width/height, showing a file's
@cindex height/width, showing a file's
@cindex zgv, problem with pre-5.2 versions of

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:

@table @kbd
@c Since colons aren't allowed in index entries, saying `colon' is
@c pretty much the best I can do. :-/
@kindex colon (Selector)
@item :
@kindex ; (Selector)
@itemx ;
@findex Selector menu, File, Details
@itemx Selector menu, File, Details
Show various details about the file pointed to by the keyboard cursor.
@xref{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.)
@end table

Most of the details shown come from the OS (by using the @code{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
@samp{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 @code{rm -fr .xvpics} in that
dir from a shell prompt and recreate the thumbnails with zgv 5.2 or
later, or xzgv/xv/Gimp.)


@node  Tagging, Renaming a File, File Details, The File Selector
@comment  node-name,  next,  previous,  up
@section Tagging

@cindex tagging
@cindex files, tagging
@cindex marking files
@cindex selecting multiple files
@cindex multiple files, selecting
@cindex file, selecting more than one

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.
@c XXX
@c (@xref{File Selector Config}, if you'd prefer zgv to use
@c different colours.)

@menu
* Tag and Untag Commands::      Selecting multiple files.
* Moving Between Tagged Files::  Finding the files once they're tagged.
* Copying/Moving Files::        Simple file management.
@end menu
@c XXX
@c * Slideshows::                  How to view them all in turn.

@node  Tag and Untag Commands, Moving Between Tagged Files, Tagging, Tagging
@comment  node-name,  next,  previous,  up
@subsection Tag and Untag Commands

@cindex tag and untag commands
@cindex tagging, how to use

There are several ways to tag or untag files. The keyboard-based ones
which work on individual files (also available on the @samp{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 @samp{Tag} and/or
@samp{Untag} on the @samp{Tagging} menu (@pxref{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. @xref{Changing Picture}, for details.

@table @kbd
@kindex = (Selector)
@item =
@kindex + (Selector)
@itemx +
@kindex Keypad + (Selector)
@itemx Keypad +
@kindex 0 (Selector)
@itemx 0
@findex Selector menu, Tagging, Tag
@itemx Selector menu, Tagging, Tag
Tag file.

@kindex - (Selector)
@item -
@kindex Keypad - (Selector)
@itemx Keypad -
@kindex 9 (Selector)
@itemx 9
@findex Selector menu, Tagging, Untag
@itemx Selector menu, Tagging, Untag
Untag file.

@kindex Alt = (Selector)
@item Alt =
@kindex Alt-Keypad + (Selector)
@itemx Alt-Keypad +
@kindex Alt-0 (Selector)
@itemx Alt-0
@findex Selector menu, Tagging, Tag All
@itemx Selector menu, Tagging, Tag All
Tag all files.

@kindex Alt - (Selector)
@item Alt -
@kindex Alt-Keypad - (Selector)
@itemx Alt-Keypad -
@kindex Alt-9 (Selector)
@itemx Alt-9
@findex Selector menu, Tagging, Untag All
@itemx Selector menu, Tagging, Untag All
Untag all files.

@kindex Alt-o (Selector)
@item Alt-o
@findex Selector menu, Tagging, Toggle All
@itemx 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.
@end table

@c XXX
Currently there is no way to toggle a (single) file's tag state from the
keyboard.


@node  Moving Between Tagged Files, Copying/Moving Files, Tag and Untag Commands, Tagging
@comment  node-name,  next,  previous,  up
@subsection Moving Between Tagged Files

@cindex files, moving between tagged
@cindex tagged files, moving between
@cindex next tagged file

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.

@table @kbd
@kindex / (Selector)
@item /
@findex Selector menu, Tagging, Next Tagged
@itemx Selector menu, Tagging, Next Tagged
Move to next tagged file in dir.

@kindex ? (Selector)
@item ?
@findex Selector menu, Tagging, Previous Tagged
@itemx Selector menu, Tagging, Previous Tagged
Move to previous tagged file in dir.

@end table

Equivalent commands are also available in the viewer (@pxref{Changing
Picture}).


@node  Copying/Moving Files,  , Moving Between Tagged Files, Tagging
@comment  node-name,  next,  previous,  up
@subsection Copying/Moving Files

@cindex copying files
@cindex moving files
@cindex files, copying
@cindex files, moving
@cindex pictures, copying
@c one for us Rush fans...
@cindex pictures, moving
@c :-)

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.

@table @kbd
@kindex C (Selector)
@item C (Shift-c)
@findex Selector menu, File, Copy
@itemx Selector menu, File, Copy
Copy tagged files (or the current file) to a given directory. xzgv asks
for the destination directory using a dialog (@pxref{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.

@kindex M (Selector)
@item M (Shift-m)
@findex Selector menu, File, Move
@itemx Selector menu, File, Move
Move tagged files (or the current file) similarly.
@end table


@node  Renaming a File, Deleting a File, Tagging, The File Selector
@comment  node-name,  next,  previous,  up
@section Renaming a File

@cindex renaming a file
@cindex file, renaming a
@cindex changing a file's name

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

@table @kbd
@kindex Ctrl-n (Selector)
@item Ctrl-n
@findex Selector menu, File, Rename file
@itemx 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. (@xref{Copying/Moving Files}, for how to move a file to a
different directory (albeit keeping the same name).) @xref{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.)
@end table

I know @kbd{Ctrl-n} isn't the most mnemonic keypress possible for
`rename', but all the good ones were taken. :-/


@node  Deleting a File, Changing Directory, Renaming a File, The File Selector
@comment  node-name,  next,  previous,  up
@section Deleting a File

@cindex deleting a file
@cindex file, deleting a
@cindex removing a file

Deleting a file is pretty straightforward:

@table @kbd
@kindex Ctrl-d
@item Ctrl-d
@findex Selector menu, File, Delete file
@itemx Selector menu, File, Delete file
Delete the file pointed to by the keyboard cursor (and any accompanying
thumbnail). @xref{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.)
@end table

Note that only one file is deleted (hence `Delete file'); there is
currently no way to delete all tagged files.


@node  Changing Directory, Rescanning the Directory, Deleting a File, The File Selector
@comment  node-name,  next,  previous,  up
@section Changing Directory

@cindex changing directory
@cindex directory, changing
@cindex selecting directory
@cindex current directory
@cindex moving directory
@cindex jumping to a directory
@cindex go to 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 @kbd{Enter}). Selecting the @code{..} entry
moves to the parent directory of the current one.

There is an alternative though:

(Note that the key for this command is shift-@kbd{g}, not @kbd{g}.)

@table @kbd
@kindex G (Selector)
@item G
@findex Selector menu, Directory, Change
@itemx 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
(@pxref{Dialog Boxes}), and moves to that directory if it exists.

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


@node  Rescanning the Directory, Changing the Sorting Order, Changing Directory, The File Selector
@comment  node-name,  next,  previous,  up
@section Rescanning the Directory

@cindex rescanning the directory
@cindex refreshing directory contents
@cindex directory, rescanning
@cindex filenames, rescanning

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:

@table @kbd
@kindex Ctrl-r
@item Ctrl-r
@findex Selector menu, Directory, Rescan
@itemx Selector menu, Directory, Rescan
Rescan the current directory.
@end table


@node  Changing the Sorting Order, File Selector Options, Rescanning the Directory, The File Selector
@comment  node-name,  next,  previous,  up
@section Changing the Sorting Order

@cindex file selector, sorting order of the
@cindex changing the file selector sorting order
@cindex sorting order, changing the file selector's
@cindex order, changing the file selector's sorting
@cindex size, showing files in order of
@cindex extension, showing files in order of
@cindex date order, showing files in

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

@table @kbd
@kindex Alt-n
@item Alt-n
@findex Selector menu, Directory, Sort by Name
@itemx Selector menu, Directory, Sort by Name
Sort by name. This is the default.

@kindex Alt-e
@item Alt-e
@findex Selector menu, Directory, Sort by Extension
@itemx Selector menu, Directory, Sort by Extension
Sort by extension.

@kindex Alt-s
@item Alt-s
@findex Selector menu, Directory, Sort by Size
@itemx Selector menu, Directory, Sort by Size
Sort by size. The biggest files are listed last.

@kindex Alt-d
@item Alt-d
@findex Selector menu, Directory, Sort by Time & Date
@itemx Selector menu, Directory, Sort by Time & Date
Sort by time/date. The newest files are listed last.

@end table

You can set the default sort order via the command-line (@pxref{Invoking
xzgv}) or a config file (@pxref{Configuring xzgv}).

There are three possible timestamps you can use for the `Time & Date'
sorting order:

@table @kbd
@kindex Alt-Shift-m
@item Alt-Shift-m
@findex Selector menu, Directory, Time & Date Type, Modification Time (mtime)
@itemx Selector menu, Directory, Time & Date Type, Modification Time (mtime)
Use the last-modified time (`mtime'). This is the default.

@kindex Alt-Shift-c
@item Alt-Shift-c
@findex Selector menu, Directory, Time & Date Type, Attribute Change Time (ctime)
@itemx Selector menu, Directory, Time & Date Type, Attribute Change Time (ctime)
Use the last-attribute-change time (`ctime'). Note that this is
@emph{not} always the time the file was created, which it's sometimes
mistaken for; for example, moving a file with @code{mv} will usually
change the ctime.

@kindex Alt-Shift-a
@item Alt-Shift-a
@findex Selector menu, Directory, Time & Date Type, Access Time (atime)
@itemx 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.

@end table


@node  File Selector Options,  , Changing the Sorting Order, The File Selector
@comment  node-name,  next,  previous,  up
@section File Selector Options

@cindex file selector options
@cindex file selector, run-time configuration of
@cindex file selector, options in
@cindex options in file selector
@cindex auto-hide selector, toggling
@cindex status bar, toggling
@cindex thumbnail display, toggling size of
@cindex thin rows mode, toggling

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
(@pxref{Invoking xzgv}) and/or config file settings (@pxref{Configuring
xzgv}).

@table @kbd
@kindex Alt-a
@item Alt-a
@findex Selector menu, Options, Auto Hide
@itemx 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. :-)

@kindex Alt-b
@item Alt-b
@findex Selector menu, Options, Status Bar
@itemx 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.

@c XXX no keyboard shortcut yet
@findex Selector menu, Options, Thumbnail Msgs
@item 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.

@kindex v
@item v
@findex Selector menu, Options, Thin Rows
@itemx 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.)

@kindex Alt-i
@item Alt-i
@findex Selector menu, Directory, Images Only
@itemx Selector menu, Directory, Images Only
Toggle the option to show only directories and image files in the
selector (off by default). This is handy in directories where images
and other file types are intermingled and you want to avoid the
'Couldn't load image' error on those other files. Images are identified
by their extensions.
@end table


@node  The Viewer, File Formats, The File Selector, Top
@comment  node-name,  next,  previous,  up
@chapter The Viewer

@cindex the viewer
@cindex using the viewer
@cindex viewer, using the
@c also, for menu mention:
@cindex viewer menu, getting the
@cindex menu, getting the viewer
@cindex getting the viewer menu
@cindex showing the viewer menu
@kindex F10 (Viewer)
@kindex Menu (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 @kbd{F10} or @kbd{Menu}) to show it --- and a
similar help menu (@pxref{The Selector Menu}).

@menu
* Exiting the Viewer::          If you're using the keyboard, this is
                                  required to return keyboard focus to the
                                  selector.
* Big Pictures::                Scrolling and zoom mode, and hiding the
                                  selector to enlarge the viewer.
* Scaling::                     Making the picture appear larger/smaller.
* Mirror and Rotate::           Distorting your sense of reality on a budget.
* Changing Picture::            You can change the currently-viewed
                                  picture without using the file
                                  selector.
* Hiding the Selector::         Hiding the selector gives the viewer
                                  a bigger share of the window.
* Minimizing xzgv::             Hiding the window gives everything else
                                  a bigger share of the screen. :-)
* Viewer Options::              The way the viewer works can be altered.
@end menu


@node  Exiting the Viewer, Big Pictures, The Viewer, The Viewer
@comment  node-name,  next,  previous,  up
@section Exiting the Viewer

@cindex exiting the viewer
@cindex quitting the viewer
@cindex leaving the viewer
@cindex returning to file selector
@cindex file selector, returning to

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:

@table @kbd
@kindex Esc (Viewer)
@item Esc
@kindex Tab (Viewer)
@itemx Tab
@findex Viewer menu, Exit to Selector
@itemx Viewer menu, Exit to Selector
Exit the viewer. This also returns the selector to its former size, if
it was previously `hidden'.
@end table

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


@node  Big Pictures, Scaling, Exiting the Viewer, The Viewer
@comment  node-name,  next,  previous,  up
@section Big Pictures

@cindex dealing with big pictures
@cindex pictures, big
@cindex large pictures
@cindex big pictures
@cindex small screen/window, coping with a

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:

@itemize @minus
@item
Make the xzgv window larger. You could `maximize' it with your window
manager, or you could start xzgv with a larger window using
@code{--geometry} or fullscreen mode (@pxref{Invoking xzgv}). 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 @code{--geometry
100%x100%} to be more effective.

@item
Hide the selector. To do this, either use auto-hide mode (@pxref{File
Selector Options}), or hide the selector explicitly (@pxref{Hiding the
Selector}).
@end itemize

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.

@menu
* Scrolling::                   Moving around the picture.
* Zoom Mode::                   Fitting the picture to the window.
@end menu

@node  Scrolling, Zoom Mode, Big Pictures, Big Pictures
@comment  node-name,  next,  previous,  up
@subsection Scrolling

@cindex scrolling
@cindex panning
@cindex viewer, scrolling in the
@cindex picture, moving around a
@cindex viewer, moving around in the
@cindex moving around the picture
@cindex keyboard, moving in the viewer via

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:

@table @kbd
@kindex Cursor Up (Viewer)
@item Cursor Up
@kindex K (Viewer)
@itemx K
@kindex k (Viewer)
@kindex Ctrl-Cursor Up (Viewer)
Move up 100 pixels. @kbd{Ctrl-Cursor Up} and @kbd{k} both move up 10
pixels.

@kindex Cursor Down (Viewer)
@item Cursor Down
@kindex J (Viewer)
@itemx J
@kindex j (Viewer)
@kindex Ctrl-Cursor Down (Viewer)
Move down 100 pixels. @kbd{Ctrl-Cursor Down} and @kbd{j} both move down
10 pixels.

@kindex Cursor Left (Viewer)
@item Cursor Left
@kindex H (Viewer)
@itemx H
@kindex h (Viewer)
@kindex Ctrl-Cursor Left (Viewer)
Move left 100 pixels. @kbd{Ctrl-Cursor Left} and @kbd{h} both move left
10 pixels.

@kindex Cursor Right (Viewer)
@item Cursor Right
@kindex L (Viewer)
@itemx L
@kindex l (Viewer)
@kindex Ctrl-Cursor Right (Viewer)
Move right 100 pixels. @kbd{Ctrl-Cursor Right} and @kbd{l} both move
right 10 pixels.

@kindex Page Up (Viewer)
@item Page Up
@kindex Shift-Cursor Up (Viewer)
@itemx Shift-Cursor Up
@kindex Ctrl-u (Viewer)
@itemx Ctrl-u
Move up (nearly) the window height. (It moves by 90% of the height.)

@kindex Page Down (Viewer)
@item Page Down
@kindex Shift-Cursor Down (Viewer)
@itemx Shift-Cursor Down
@kindex Ctrl-v (Viewer)
@itemx Ctrl-v
Move down (nearly) the window height.

@kindex - (Viewer)
@item -
@kindex Shift-Cursor Left (Viewer)
@itemx Shift-Cursor Left
Move left (nearly) a window-length. (It moves by 90% of it.)

@kindex = (Viewer)
@item =
@kindex Shift-Cursor Right (Viewer)
@itemx Shift-Cursor Right
Move right (nearly) a window-length.

@kindex Home (Viewer)
@item Home
@kindex Ctrl-a (Viewer)
@itemx Ctrl-a
Move to the top-left of the picture.

@kindex End (Viewer)
@item End
@kindex Ctrl-e (Viewer)
@itemx Ctrl-e
Move to the bottom-right of the picture.
@end table


@node  Zoom Mode,  , Scrolling, Big Pictures
@comment  node-name,  next,  previous,  up
@subsection Zoom Mode

@cindex zoom mode
@cindex fitting picture to window
@cindex small window, making picture fit a
@cindex small picture, making window fit a
@cindex small pictures, not zooming
@cindex zooming big but not small pictures
@cindex zoom mode, reduce-only in
@cindex reduce-only in zoom mode
@cindex use panorama view in 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 @samp{Normal} (@pxref{Scaling})).

@table @kbd
@kindex z
@item z
@findex Viewer menu, Options, Zoom (fit to window)
@itemx Viewer menu, Options, Zoom (fit to window)
Toggle zoom mode.

@kindex Alt-r
@item Alt-r
@findex Viewer menu, Options, When Zooming Reduce Only
@itemx Viewer menu, Options, When Zooming Reduce Only
When in zoom mode, only @emph{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. :-)

@kindex Alt-p
@item Alt-p
@findex Viewer menu, Options, When Zooming Panorama
@itemx Viewer menu, Options, When Zooming Panorama
When in zoom mode, resize to make the most proportional dimension fit and
allow scrolling on the other dimension. This can be useful when viewing
iamges that do not adjust nicely to the window size but you want to see them
as big as possible while using the most space available. The cause for this
function was to better read comics, so you can guess it works like a
'fit page width' option, but is not limited to horizontal adjustment.
@end table

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 @samp{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.


@node  Scaling, Mirror and Rotate, Big Pictures, The Viewer
@comment  node-name,  next,  previous,  up
@section Scaling

@cindex scaling up/down a picture
@cindex enlarging a picture
@cindex picture, enlarging
@cindex reducing a picture
@cindex picture, reducing
@cindex zooming into a picture
@cindex making a picture bigger/smaller
@cindex small picture, enlarging a
@cindex normal, returning display to
@cindex aspect ratio, altering
@cindex decoupled scaling
@cindex axis-specific scaling
@cindex scaling, axis-specific

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@dots{})

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:

@table @kbd
@kindex d
@item d
@findex Viewer menu, Scaling, Double Scaling
@itemx Viewer menu, Scaling, Double Scaling
Increase the ratio by doubling it --- this leads to ratios of 2:1, 4:1,
8:1@dots{}

@kindex s
@item s
@findex Viewer menu, Scaling, Add 1 to Scaling
@itemx Viewer menu, Scaling, Add 1 to Scaling
Increase the ratio by adding one --- leads to ratios of 2:1, 3:1,
4:1@dots{}
@end table

There are similar commands to decrease the ratio:

@table @kbd
@kindex D
@item D (Shift-d)
@findex Viewer menu, Scaling, Halve Scaling
@itemx Viewer menu, Scaling, Halve Scaling
Decrease the ratio by halving it.

@kindex S
@item S (Shift-s)
@findex Viewer menu, Scaling, Sub 1 from Scaling
@itemx Viewer menu, Scaling, Sub 1 from Scaling
Decrease the ratio by subtracting one.
@end table

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:

@table @kbd
@kindex n
@item n
@findex Viewer menu, Scaling, Normal
@itemx Viewer menu, Scaling, Normal
Resume `normal' display --- disables scaling mode, and also zoom mode.
@end table

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
@emph{very} slow, but looks nice.

@table @kbd
@kindex i
@item i
@findex Viewer menu, Options, Interpolate when Scaling
@itemx Viewer menu, Options, Interpolate when Scaling
Toggle interpolation in scaling mode.
@end table

(If you like the appearance of scaling with interpolation, you may also
be interested in a program I wrote called @cite{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 (@pxref{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.

@table @kbd
@kindex x
@item x
@findex Viewer menu, Scaling, X Only, Double Scaling
@itemx Viewer menu, Scaling, X Only, Double Scaling
Increase the (x axis) ratio by doubling it.

@kindex X
@item X (Shift-x)
@findex Viewer menu, Scaling, X Only, Halve Scaling
@itemx Viewer menu, Scaling, X Only, Halve Scaling
Decrease the (x axis) ratio by halving it.

@kindex Alt-x
@item Alt-x
@findex Viewer menu, Scaling, X Only, Add 1 to Scaling
@itemx Viewer menu, Scaling, X Only, Add 1 to Scaling
Increase the (x axis) ratio by adding one.

@kindex Alt-Shift-x
@item Alt-Shift-x
@findex Viewer menu, Scaling, X Only, Sub 1 from Scaling
@itemx Viewer menu, Scaling, X Only, Sub 1 from Scaling
Decrease the (x axis) ratio by subtracting one.

@kindex y
@item y
@findex Viewer menu, Scaling, Y Only, Double Scaling
@itemx Viewer menu, Scaling, Y Only, Double Scaling
Increase the (y axis) ratio by doubling it.

@kindex Y
@item Y (Shift-y)
@findex Viewer menu, Scaling, Y Only, Halve Scaling
@itemx Viewer menu, Scaling, Y Only, Halve Scaling
Decrease the (y axis) ratio by halving it.

@kindex Alt-y
@item Alt-y
@findex Viewer menu, Scaling, Y Only, Add 1 to Scaling
@itemx Viewer menu, Scaling, Y Only, Add 1 to Scaling
Increase the (y axis) ratio by adding one.

@kindex Alt-Shift-y
@item Alt-Shift-y
@findex Viewer menu, Scaling, Y Only, Sub 1 from Scaling
@itemx Viewer menu, Scaling, Y Only, Sub 1 from Scaling
Decrease the (y axis) ratio by subtracting one.
@end table

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
@kbd{Alt-c}, or by toggling the @kbd{Ctl+Click Scales X Axis} option
(@pxref{Viewer Options}).

Interpolation is not currently supported in situations where the x
scaling does not match the y scaling.


@node  Mirror and Rotate, Changing Picture, Scaling, The Viewer
@comment  node-name,  next,  previous,  up
@section Mirror and Rotate

@cindex mirroring a picture
@cindex flipping a picture
@cindex rotating a picture
@cindex picture, mirroring a
@cindex picture, flipping a
@cindex picture, rotating a
@cindex picture orientation
@cindex orientation, picture
@cindex restoring picture orientation

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

@table @kbd
@kindex m
@item m
@findex Viewer menu, Orientation, Mirror (horiz)
@itemx Viewer menu, Orientation, Mirror (horiz)
`Mirror' the picture (flip it horizontally).

@kindex f
@item f
@findex Viewer menu, Orientation, Flip (vert)
@itemx Viewer menu, Orientation, Flip (vert)
`Flip' the picture (flip it vertically).

@kindex r
@item r
@findex Viewer menu, Orientation, Rotate Right
@itemx Viewer menu, Orientation, Rotate Right
Rotate the picture 90 degrees clockwise.

@kindex R
@item R (Shift-r)
@findex Viewer menu, Orientation, Rotate Left
@itemx 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. :-))

@kindex N
@item N (Shift-n)
@findex Viewer menu, Orientation, Normal
@itemx Viewer menu, Orientation, Normal
Restore the picture orientation to normal. This undoes the effect of any
mirrors, flips, and/or rotations.
@end table

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 (@pxref{Viewer
Options}), so that any new pictures are mirrored, flipped, and/or
rotated in the same way.


@node  Changing Picture, Hiding the Selector, Mirror and Rotate, The Viewer
@comment  node-name,  next,  previous,  up
@section Changing Picture

@cindex pictures, changing
@cindex viewer, changing pictures from the
@cindex changing pictures
@cindex next picture
@cindex previous picture
@cindex tagging pictures in the viewer
@cindex viewer, tagging pictures in the

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.

@table @kbd
@c XXX should have alternative way of getting next image which works
@c from both selector and viewer, perhaps? Could use ^p and ^n,
@c I s'pose - there's precedent for that in zgv, if nothing else.
@kindex Space (Viewer)
@item Space
@findex Viewer menu, Next Image
@itemx 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 (@pxref{Config Variables}).)

@kindex b
@item b
@findex Viewer menu, Previous Image
@itemx Viewer menu, Previous Image
Move to previous file in dir, and view it.

@kindex Ctrl-Space (Viewer)
@item Ctrl-Space
@findex Viewer menu, Tagging, Tag then Next
@itemx Viewer menu, Tagging, Tag then Next
Tag current file, then move to next file in dir and view it.

@kindex / (Viewer)
@item /
@findex Viewer menu, Tagging, Next Tagged
@itemx Viewer menu, Tagging, Next Tagged
Move to next tagged file in dir, and view it.

@kindex ? (Viewer)
@item ?
@findex Viewer menu, Tagging, Previous Tagged
@itemx Viewer menu, Tagging, Previous Tagged
Move to previous tagged file in dir, and view it.

@end table


@node  Hiding the Selector, Minimizing xzgv, Changing Picture, The Viewer
@comment  node-name,  next,  previous,  up
@section 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:

@table @kbd
@kindex Z
@item Z (shift-z)
@findex Viewer menu, Window, Hide Selector
@itemx Viewer menu, Window, Hide Selector
Hide the selector. (This is actually a toggle, of sorts; `hide selector'
when it's already hidden unhides it.)
@end table

You can also hide or unhide the selector by middle-clicking on the
viewer.


@node  Minimizing xzgv, Viewer Options, Hiding the Selector, The Viewer
@comment  node-name,  next,  previous,  up
@section Minimizing xzgv

@c XXX this is only really here because it's on the viewer's menu. A
@c more general place would be better, but it's difficult to see where
@c that would be.

@c ghod it's painful writing `minimize'. :-/ See main.c's viewer menu
@c definition for the rationale behind my not writing `minimise', even
@c though that's my preferred -ise/-ize form.

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:

@table @kbd
@kindex Ctrl-z
@item Ctrl-z
@findex Viewer menu, Window, Minimize
@itemx Viewer menu, Window, Minimize
Minimize the xzgv window.
@end table


@node  Viewer Options,  , Minimizing xzgv, The Viewer
@comment  node-name,  next,  previous,  up
@section Viewer Options

@cindex viewer options
@cindex viewer, run-time configuration of
@cindex viewer, options in
@cindex options in the viewer

@c thesaurus, how to sound like a    :-)
@cindex fit to window, toggling
@cindex zoom, toggling
@cindex interpolation when scaling, toggling
@cindex scaling with interpolation, toggling
@cindex enlarged pictures, toggling interpolation for
@cindex revert scaling, toggling
@cindex revert orientation, toggling
@cindex preserving scaling
@cindex preserving orientation
@cindex scaling, preserving
@cindex orientation, preserving
@cindex mirrors, preserving
@cindex flips, preserving
@cindex rotation, preserving
@cindex correcting digital camera pictures
@cindex digital camera pictures, correcting
@cindex exif orientation support
@cindex orientation, exif
@cindex dithering in 15/16-bit modes
@cindex 15/16-bit modes, toggling dithering in
@cindex high-colour modes, toggling dithering in
@cindex mouse scaling axis, toggling
@cindex scaling axis, toggling mouse
@cindex axis, toggling mouse scaling

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
(@pxref{Invoking xzgv}) and/or config file settings (@pxref{Configuring
xzgv}).

@table @kbd
@c no index entries here, it's already been done (in Zoom Mode)
@item z
@itemx Viewer menu, Options, Zoom (fit to window)
Toggle zoom mode, discussed in more detail elsewhere (@pxref{Zoom Mode}).

@c same here...
@item Alt-r
@itemx Viewer menu, Options, When Zooming Reduce Only
Toggle reduce-only in zoom mode, also covered elsewhere (@pxref{Zoom
Mode}).

@c and here...
@item Alt-p
@itemx Viewer menu, Options, When Zooming Panorama
Toggle panorama view in zoom mode, also covered elsewhere (@pxref{Zoom
Mode}).

@c and here...
@item i
@itemx Viewer menu, Options, Interpolate when Scaling
Toggle interpolation when a picture is being scaled-up. Again, this has
already been mentioned (@pxref{Scaling}).

@kindex Alt-c
@item Alt-c
@findex Viewer menu, Options, Ctl+Click Scales X Axis
@itemx 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.

@kindex F
@item F (shift-f)
@findex Viewer menu, Options, Dither in 15 & 16-bit
@itemx 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 @kbd{F} key was chosen for this as the dither
toggle is functionally similar to zgv's `fakecols' toggle.)

@findex Viewer menu, Options, Revert Scaling For New Pic
@item 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 @kbd{F10}), and select the menu item.)

@findex Viewer menu, Options, Revert Orient. For New Pic
@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.)

@findex Viewer menu, Options, Use Exif Orientation
@item 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.)
@end table


@node  File Formats, Configuring xzgv, The Viewer, Top
@comment  node-name,  next,  previous,  up
@chapter File Formats

@cindex file formats
@cindex pictures, file formats used by

Picture files are stored in a variety of different forms, or `file
formats'. xzgv, via gdk, supports many.

@menu
* File Type Identification::    How xzgv identifies the type of a file.
@end menu

@node  File Type Identification,  , File Formats, File Formats
@comment  node-name,  next,  previous,  up
@section File Type Identification

@cindex identifying files
@cindex files, identification of
@cindex picture format, identification of
@cindex file format, identification of

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 @code{FF
D8}. So if you start xzgv with @samp{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.

@node  Configuring xzgv, Rationale, File Formats, Top
@comment  node-name,  next,  previous,  up
@chapter Configuring xzgv

@cindex configuration
@cindex customising
@cindex changing xzgv's behaviour
@cindex defaults, changing
@cindex options, setting default
@cindex settings, changing

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

@menu
* Config Files::                There are two possible config files.
* Config Variable Types::       Most settings are on/off, but not all.
* Config Variables::            Most options are identical to the
                                  command-line long-options, but here are
                                  names, defaults, and descriptions for
                                  those which aren't.
@end menu

@node  Config Files, Config Variable Types, Configuring xzgv, Configuring xzgv
@comment  node-name,  next,  previous,  up
@section Config Files

@cindex files, config
@cindex config files
@cindex @file{xzgvrc}
@cindex @file{xzgv.conf}
@cindex format of config files

A configuration file lets you alter aspects of xzgv's behaviour. xzgv
supports two possible config files --- a system-wide one,
@file{/etc/xzgv.conf}; and one for each user in their home directory,
@file{$HOME/.xzgvrc}. Both are optional. If @file{$HOME/.xzgvrc} exists,
it is used @emph{instead of} @file{/etc/xzgv.conf}.

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

@example
# 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
@end example

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 @samp{fullscreen} option above controls whether or not
xzgv tries to use the whole screen for its window. If it is given the
value @code{on}/@code{y}/@code{yes}/@code{1} it does; if
@code{off}/@code{n}/@code{no}/@code{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.


@node  Config Variable Types, Config Variables, Config Files, Configuring xzgv
@comment  node-name,  next,  previous,  up
@section Config Variable Types

@cindex types, config variable
@cindex variable, types of config
@cindex config variables types
@cindex config files, types in

There are various types of variable:

@itemize @minus
@item
Boolean. These are on-or-off, yes-or-no variables. Most of xzgv's config
file variables are of this type.

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

@item
Geometry. This window size-and/or-position specification format is only
used for the @code{geometry} setting. @xref{Invoking xzgv}, for a
description of how this type works.

@end itemize


@node  Config Variables,  , Config Variable Types, Configuring xzgv
@comment  node-name,  next,  previous,  up
@section Config Variables

@cindex config variables
@cindex variables, config
@cindex themes, adjusting for dark GTK+
@cindex GTK+ themes, adjusting for dark
@cindex dark GTK+ themes, adjusting for

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 @emph{identical} to that for the long version of the option
(e.g. @code{fullscreen}, @code{auto-hide}). As such, they're documented
in the section which discusses command-line options and the like
(@pxref{Invoking xzgv}).

However, there are some settings only available in the config file:

@vtable @samp
@item 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.
@end vtable


@node  Rationale, Bugs and Restrictions, Configuring xzgv, Top
@comment  node-name,  next,  previous,  up
@chapter Rationale

@cindex rationale
@cindex moaning for fun and profit
@c many a true word... :-)

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.

@menu
* Why Yet Another Viewer?::     Because we're here.
* Why no image-editing capabilities?::  You're kidding, right?
* Why a Texinfo Manual?::       Large man pages are hard to deal with.
* Why One-space Sentence Ends?::  Not everyone uses two-space ones.
@end menu

@node  Why Yet Another Viewer?, Why no image-editing capabilities?, Rationale, Rationale
@comment  node-name,  next,  previous,  up
@section Why Yet Another Viewer?

@cindex why another viewer?
@cindex other viewers, comparison with

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:

@itemize @bullet
@item
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.

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

@item
It's, er, quite a lot like zgv. Some of us old fogies like this. :-)

@end itemize

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:

@itemize @bullet
@item
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.

@item
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 @emph{don't}
think belongs in a viewer, but which xli does happen to be quite good
at.)

@item
qiv. If I read between the lines correctly, this is essentially a modern
replacement for xli.

@item
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. :^)

@item
Electric Eyes. To be honest, I think this has been outclassed by other
viewers these days, which shows how far we've come.

@end itemize

Ah, you say, what of xv? Well, we've @emph{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.


@node  Why no image-editing capabilities?, Why a Texinfo Manual?, Why Yet Another Viewer?, Rationale
@comment  node-name,  next,  previous,  up
@section Why no image-editing capabilities?

It's a fscking @emph{viewer}, dammit. If you want xv you know where to
find it.

(OTOH, if you want a @emph{decent} image editor, use the Gimp.)


@node  Why a Texinfo Manual?, Why One-space Sentence Ends?, Why no image-editing capabilities?, Rationale
@comment  node-name,  next,  previous,  up
@section Why a Texinfo Manual?

@cindex why a texinfo manual?
@cindex Texinfo, why xzgv doc. is in
@cindex man page, why not just have a

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.


@node  Why One-space Sentence Ends?,  , Why a Texinfo Manual?, Rationale
@comment  node-name,  next,  previous,  up
@section Why One-space Sentence Ends?

@cindex why one-space sentence ends?
@cindex Texinfo, problems with

@c XXX when printed, is emacs texinfo file's title really "The Emacs
@c Editor"? Should check this for the relevant @pxref here.

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
@emph{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 @emph{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
(@samp{sentence-end-double-space}; @pxref{Fill Commands,,,emacs,The
Emacs Editor}) and GNU fmt (@samp{-u}; @pxref{fmt
invocation,,,textutils,GNU Text Utilities}). 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.

@node  Bugs and Restrictions, Future Changes, Rationale, Top
@comment  node-name,  next,  previous,  up
@chapter Bugs and Restrictions

@cindex bugs and restrictions

All (non-trivial) programs have bugs. Anyone who denies this@dots{}

@itemize @minus
@item
clearly hasn't written too many programs.
@item
is wrong. ;-)
@end itemize

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.

@menu
* Known Bugs::                  Known bugs in xzgv which have yet to be
                                  fixed.
* Suboptimal Features::         Aspects of xzgv which aren't exactly
                                  ideal, but are at least intentional.
* Restrictions::                Limits and similar shortcomings.
* Reporting Bugs::              What to do if you spot a problem.
* Reporting Documentation Bugs::  Documentation errors are also worth
                                  reporting.
@end menu


@node  Known Bugs, Suboptimal Features, Bugs and Restrictions, Bugs and Restrictions
@comment  node-name,  next,  previous,  up
@section Known Bugs

@cindex known bugs
@cindex bugs, known

@itemize @minus
@item
In zoom mode, it copes with resizing the window as a whole, but
@emph{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 :-)).

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

@item
Scaling up is slow. Not sure if I can do much about this.

@item
Using an alignment widget to centre the viewer window results in some
annoying `bounce' in certain resizing situations etc.

@item
Thumbnails don't look so great in palette-based (e.g. 8-bit) modes.

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

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

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

@item
If you look up `joe code' in a dictionary, right next to ``see zgv'' it
now says ``but for @emph{really} in-depth insight into the joe code
nature, see xzgv''. :-)

@end itemize


@node  Suboptimal Features, Restrictions, Known Bugs, Bugs and Restrictions
@comment  node-name,  next,  previous,  up
@section Suboptimal Features

@cindex suboptimal features
@cindex problematic features
@cindex bug, that's a feature not a

@itemize @minus
@item
Thumbnails are given an accurate width/height `IMGINFO' comment, but are
always claimed to be "RGB".

@item
xzgv @emph{doesn't} duplicate zgv's behaviour of generating thumbnails
under @file{~/.xvpics/_foo_bar_baz} if it can't generate them in
@file{/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.

@end itemize


@node  Restrictions, Reporting Bugs, Suboptimal Features, Bugs and Restrictions
@comment  node-name,  next,  previous,  up
@section Restrictions

@cindex restrictions

@itemize @minus
@item
Only the first image of a multiple-image GIF is used. (These days,
multiple-image GIFs are usually animations.)
@end itemize


@node  Reporting Bugs, Reporting Documentation Bugs, Restrictions, Bugs and Restrictions
@comment  node-name,  next,  previous,  up
@section Reporting Bugs

@cindex reporting bugs
@cindex bugs, reporting
@cindex problems, reporting
@cindex faults, reporting
@cindex contacting the author
@cindex author, contacting the

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'.
@xref{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:

@itemize @bullet
@item
The version of xzgv you are running. @code{xzgv --version} reports this.

@item
The versions of GTK+ you are using. @code{xzgv --version-gtk} reports
the GTK+ version being used by xzgv.

@item
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
@code{xdpyinfo|grep depth}.

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

@item
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 @code{diff -c} or (preferably) @code{diff -u}.

@end itemize

Then, please file a bug report in the SourceForge bug tracker.
See @indicateurl{https://sourceforge.net/p/xzgv}.


@node  Reporting Documentation Bugs,  , Reporting Bugs, Bugs and Restrictions
@comment  node-name,  next,  previous,  up
@section Reporting Documentation Bugs

@cindex reporting documentation bugs
@cindex documentation, reporting bugs in the
@cindex bugs, reporting documentation
@cindex Texinfo documentation, reporting bugs in the
@cindex Info file, reporting bugs in the
@cindex manual, reporting bugs in the

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:

@itemize @bullet
@item
The version of xzgv the documentation is for.

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

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

@item
A description of the problem.

@end itemize

@xref{Reporting Bugs}, for details of where to send the bug report.


@node  Future Changes, Keyboard Commands Index, Bugs and Restrictions, Top
@comment  node-name,  next,  previous,  up
@chapter Future Changes

@cindex TODO list
@cindex future changes
@cindex changes, possible future
@cindex wish-list

If you want to suggest a feature you'd like in xzgv, or a change to an
existing feature, contact me; see @xref{Reporting Bugs} for the address.

Future changes etc. are listed in the @file{TODO} file.


@node  Keyboard Commands Index, Menu Item Index, Future Changes, Top
@comment  node-name,  next,  previous,  up
@unnumbered Keyboard Commands Index

@cindex index, keyboard commands

@printindex ky


@node  Menu Item Index, Configuration Variables Index, Keyboard Commands Index, Top
@comment  node-name,  next,  previous,  up
@unnumbered Menu Item Index

@cindex index, menu item

@printindex fn


@node  Configuration Variables Index, Concept Index, Menu Item Index, Top
@comment  node-name,  next,  previous,  up
@unnumbered Configuration Variables Index

@cindex index, configuration variables

@printindex vr


@node    Concept Index,  , Configuration Variables Index, Top
@comment  node-name,  next,  previous,  up
@unnumbered Concept Index

@cindex recursion joke, ANSI standard

@printindex cp


@contents
@bye
