Provided by: xzgv_0.9.2-2_amd64 bug

NAME

       xzgv - picture viewer for X, with thumbnail-based file selector

SYNOPSIS

       xzgv [options] [dir | file ...]

DESCRIPTION

       (NB:  This  man  page is automagically generated from xzgv's texinfo file, and so may look a bit odd.  We
       apologise for the inconvenience. :-))

       xzgv is a picture viewer for X, with a thumbnail-based file selector.  The  thumbnails  used  (thumbnails
       being  small  `preview' versions of the pictures) are compatible with xv, zgv, and the Gimp. The kinds of
       pictures xzgv allows  to  be  viewed  are  raster-format  pictures  (sometimes  called  `bitmaps'  and/or
       `pixmaps'); things like GIF files, JPEG files, PNG files, and so on.

       Most  of  the  time,  you  will probably want to use xzgv's file selector (see The File Selector) to pick
       which file(s) to view. This is what appears on the left-hand side of the window when you  start  xzgv  as
       just  `xzgv'  (see  Options).  It  displays  a  list  of  subdirectories and picture files in the current
       directory, along with small `thumbnail' versions of the pictures if they exist. (If no thumbnails  appear
       in  a given directory, or if they are missing for some files, you can create/update them by pressing `u'.
       See Updating Thumbnails.)

       When you've picked a file to view, you can view it by clicking on it, or pressing `Enter'. This reads the
       picture  and  displays it in the right-hand part of the window, the viewer (see The Viewer). You can then
       move around the picture (if it is larger than will fit) by dragging it  with  the  mouse,  or  using  the
       scrollbars, or the cursor keys. You can then select another image with the file selector (though you need
       to press `Esc' or `Tab' first if using the keyboard), or you can quit xzgv by pressing `q'.

       While xzgv works much like any other X program, and is certainly mouse-friendly :-), it's  also  designed
       to  be  keyboard-friendly.   Everything  in  xzgv  can  be  done entirely from the keyboard. Much of this
       keyboard support works like the original zgv (a similar console-based picture viewer for Linux).

       This overview is, as you might expect, only the very simplest of introductions to what xzgv can  do,  and
       describes only a very basic use of xzgv. xzgv can do a lot more; read on to find out what.

ACKNOWLEDGEMENTS

       xzgv  was  primarily written by Russell Marks, also the author of this manual. It is maintained by Reuben
       Thomas, 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 dir-close.xpm. I think Tuomas Kuosmanen was
       responsible for that, judging from the change log.

       `mkinstalldirs' is straight from the `texinfo' package, and was written by Noah Friedman. (This  is  also
       used during installation.)

       Huge  thanks  go  to  the many people responsible for GTK+, without which xzgv would almost certainly not
       have happened. (But no thanks for Electric Eyes, which was nearly nice enough for me not to  bother  with
       xzgv at all! :-))

       getopt*.[ch] are from the GNU libc.

OPTIONS

       Normally  you'd invoke xzgv as plain `xzgv' (perhaps via a window manager menu, or GNOME/KDE menu, etc.).
       However, you can directly specify files to view, or a start directory, on the command-line. In  addition,
       there are various options.

       (If  you're  new  to  xzgv, you should probably skip the rest of this section for now and come back to it
       later.)

       The general format of the xzgv command-line goes roughly like this:

       xzgv [options] [dir | file ...]

       Two types of options are supported --- the traditional Unix single-letter  options,  and  GNU-style  long
       options. Most options can be used in either way, and both forms are listed in the table below.

       Note  that all options are processed after any configuration file(s).  Config file settings are just like
       the long-option names below minus the `--' (see Configuring xzgv), though a few command-line options  are
       not permitted as config file settings (e.g. `help'), and vice versa.

       Here's what the options do:

       `-a'
       `--auto-hide'
              Automatically  hide  selector  when  a  picture  is selected, allowing the viewer to use the whole
              window.

       `--careful-jpeg'
              Enable libjpeg `fancy upsampling'. xzgv defaults to  using  the  faster  method;  as  the  libjpeg
              documentation puts it, ``The visual impact of the sloppier method is often very small.''

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

       `--dither-hicol'
              Use dithering in 15/16-bit, whatever the default setting is.  See Viewer Options, for a discussion
              of benefits/drawbacks. You can also use `--dither-hicol=off' to disable this.

       `--exif-orient'
              In  JPEG  files,  use  Exif  orientation  tags (inserted by e.g. digital cameras) to correct image
              orientation before display. See Viewer Options, for details.

       `--fast-recursive-update'
              When doing a recursive thumbnail update, don't read existing thumbnails before updating.  This  is
              pretty much obsolete as of xzgv 0.7, as the speed increase is now negligible. But, it may still be
              useful if you want to update a huge number of small directories for which few if any  updates  are
              needed.

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

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

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

              Now,  the  `+X+Y'  bit normally specifies where the top-left of the window is. But you can use `-'
              instead of `+' for the x and/or y position, in  which  case  it  specifies  the  gap  between  the
              right/bottom  of  the  window  and the right/bottom of the screen. (Note, however, that any window
              frame your window manager adds to the window is disregarded in this calculation, so you  may  need
              to  experiment  somewhat to get the desired position.) You can also use negative numbers with both
              `+' and `-' --- so `+-50+0' puts the window partly off the left of the screen, and  `+0--50'  puts
              it partly off the bottom of the screen --- but this is of questionable value. :-)

              Finally,  as  mentioned  above,  xzgv  extends  this  syntax by allowing you to use `%' to specify
              percentages of the screen width/height rather than pixels, e.g. `50%x30%-30%-20%'. It also  allows
              you to use real numbers such as `12.34', which can be useful with `%'.

       `-h'
       `--help'
              Display a list of options and a terse description of what the options do.

       `--image-bigness-threshold numpix'
              Set  the  boundary numpix after which images are considered `big', and are no longer rendered all-
              at-once (which gives much nicer scrolling, but is harder on memory and can be slow for big images)
              but  are  instead  rendered  piece-by-piece. Units are number of pixels in image (i.e. width times
              height), and the default is 2000000 pixels.

       `-i'
       `--images-only'
              Shows only directories and image file types in the selector, identified by their extensions.

       `--interpolate'
              Interpolate between the picture's pixels when scaling up (see Scaling). This usually looks  nicer,
              but it's rather slow.

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

       `--revert-orient'
              (Note that this is normally enabled;  use  `--revert-orient=off'  to  disable  it.)  If  disabled,
              orientation (flip/mirror/rotate) state is retained between pictures (see Viewer Options).

       `--revert-scale'
              (Note that this is normally enabled; use `--revert-scale=off' to disable it.) If disabled, scaling
              is retained between pictures (see Viewer Options).

       `--selector-width'
              Set the default/initial size of the selector in pixels. The normal setting is 200.

       `-T'
       `--show-tagged'
              Show names of currently-tagged files on exiting xzgv. (They're listed to stdout,  one  per  line.)
              This  can  be  useful  when  you  want  to select multiple files graphically and work on them with
              something else.

       `--show-thumbnail-messages'
              Show on the status bar when thumbnails are being read. The status bar must be  enabled  for  these
              messages to be visible, of course. :-)

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

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

       `--sort-timestamp-type type'
              Set the timestamp type to use when using time/date sorting order.  Possible settings  are  `mtime'
              (default), `ctime', and `atime'; only the first char of the setting (`m'/`c'/`a') need be given.

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

       `-t'
       `--thin-rows'
              Use  rows  a  third the normal height in the selector. This can be very useful on lower-resolution
              screens, or if you're really interested in filenames, not thumbnails.

       `-v'
       `--version'
              Show version number.

       `--version-gtk'
              Show version number of GTK+ xzgv is using.

       `-z'
       `--zoom'
              Fit picture to viewer window, whatever its actual size (see Zoom Mode).

       `-r'
       `--zoom-reduce-only'
              When in zoom mode, only reduce pictures to fit; i.e. make big pictures viewable all-at-once  while
              leaving small picures intact.

       `-p'
       `--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 fit page width option in PDF readers, but not limited  to  horizontal
              adjusting.

       If  started  with `xzgv files', xzgv hides the file selector and treats the file or files as if they were
       the sole contents of a directory. (It also automatically loads the first file.) As such, you can use  the
       Next Image and Previous Image commands to navigate between the images, or do Exit to Selector and use the
       selector directly.

       If started with `xzgv start-dir', xzgv starts up  as  usual,  but  with  the  selector  starting  on  the
       directory specified (rather than the current directory).

       Settings  which  are  either  on or off (boolean) are, as you might expect, enabled by using e.g. `-z' or
       `--zoom'. However, there's an alternative long-option form for setting these, resembling how they're  set
       in  config  files  ---  the  syntax  is `--option=state', where state is `on'/`y'/`yes'/`1' to enable the
       option, or `off'/`n'/`no'/`0' to disable it. The most useful thing about this is that it  allows  you  to
       disable options which were previously enabled, by using e.g. `--zoom=off'.

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

A NOTE ON NOTATION

       Much of this manual is taken up by a description of xzgv's various commands  in  its  file  selector  and
       viewer.  Most  of these are available both from the keyboard, and from popup menus. (A popup menu appears
       when you press `F10' or `Menu', or right-click on the selector or the viewer; each has its own menu.)  So
       in the manual, you will often see things rather like this:

       `key'
       `Selector menu, Menu the item is in, Menu item'
              Description of what the key/menu item does.

       Sometimes  the key given has a `(Selector)' or `(Viewer)' suffix; this is because some keypresses in xzgv
       are specific to the selector or the viewer, and won't work unless the  relevant  part  of  xzgv  has  the
       keyboard focus.

THE FILE SELECTOR

       Usually,  on  starting  up  xzgv, you'll want to use the file selector --- the list of files on the left.
       (The other subwindow (on the right) is the viewer.) The selector lets you pick files to view (among other
       things).  It  lists  the  subdirectories  and  picture  files  in the current directory, along with small
       `thumbnail' versions of the pictures if they exist.

THE SELECTOR MENU

       Almost all selector commands are available from the selector's pop-up menu, which appears when you right-
       click  anywhere  on  the selector. (You can also press `F10' or `Menu' to bring up the menu, but as there
       are keyboard shortcuts for just about everything in xzgv, this isn't often that useful. :-))

       Usually, it doesn't matter where on the selector you right-click.  However, a few commands  on  the  File
       menu  operate  on a single file, the one selected by the keyboard cursor. A problem when using the mouse,
       you might think --- but when you right-click on the selector, as well as popping up the menu, xzgv  moves
       this cursor to the file you right-clicked on (if any). (You can see this by the way a hollow box is drawn
       around the file.) So to use e.g. Details on the File menu, you need to right-click on the file  you  want
       details on.

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

       `F1'
       `Selector menu, Help, Contents'
       `Viewer menu, Help, Contents'
              View the manual's overall contents.

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

       `Viewer menu, Help, The Viewer'
              View the manual's section on the viewer.

       `Selector menu, Help, Index'
       `Viewer menu, Help, Index'
              View the manual's concept index.

       `Selector menu, Help, About'
       `Viewer menu, Help, About'
              Give some brief information about xzgv, including the version number and homepage.

       Currently,  the  way xzgv lets you read the manual is a bit crude; it runs the `info' program (see Top in
       the info-stnd info file) in an `xterm'.

EXITING XZGV

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

       `q'
       `Ctrl-q'
       `Selector menu, Exit xzgv'
              Quit xzgv.

       (There's  also  an  exit  option  on the selector's File menu (`Selector menu, File, Exit'), as `Exit' is
       generally on any File menu.)

THUMBNAILS

       (This section is deliberately early on in the manual, as  thumbnails  are  probably  the  most  important
       feature  of  the  file  selector, so it's best that you know how to create/update them sooner rather than
       later.)

       Thumbnails are small versions of the pictures they represent, and are displayed by the file  selector  if
       they  exist.  xzgv uses xv-compatible thumbnails --- if you create thumbnails with xv they will work with
       xzgv, and vice versa. xzgv's thumbnails are also compatible with the Gimp, and zgv.

       If no thumbnail exists for a file, a small `document' icon appears instead (similar to the `folder'  icon
       used for directories).

   Updating Thumbnails
       While  thumbnails  can  be made relatively quickly, it's by no means an instant process. For this reason,
       thumbnails have to be created in advance, and are stored as files in their own right  in  a  subdirectory
       .xvpics.

       xzgv  never  creates/updates thumbnails without you telling it to. So, if you enter a directory where the
       picture files don't have any thumbnails, or where the thumbnails seem to be out of date, you should press
       `u',  or  select  Update  Thumbnails  from the selector's menu.  (Even if the thumbnails can't be written
       (say, if you don't have permission to write them), the selector will still show  the  updated  thumbnails
       until you leave the directory.)

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

       `u'
       `Selector menu, Update Thumbnails'
              Create thumbnails for any files which don't have them, and update thumbnails which are older  than
              the  corresponding  file.  While  this  is  going on, a window appears showing how far through the
              process xzgv is.

              While the update is in progress, you can abort it by clicking on the Cancel  button,  or  pressing
              `Esc' or `Enter', or by clicking the delete-window button (if your window manager provides one) on
              the title bar. xzgv will stop once it has finished the thumbnail it is currently  working  on  (if
              any).

       `Alt-u'
       `Selector menu, Recursive Update'
              Create/update  thumbnails  for all files in the current directory and all subdirectories. This can
              take some time, so you are prompted to confirm you really want to  do  this  (see  Dialog  Boxes).
              Progress  is  indicated  in  much  the same way as for a normal update, but only for the directory
              currently being updated --- the overall progress is not indicated, other than by the  current  dir
              being  (as  ever) displayed in the main window's title. You can abort a recursive thumbnail update
              in the same ways as for a normal update (see above).

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

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

       -  xzgv  doesn't  read  the  thumbnails  in a directory all at once. Instead, it just reads the directory
       contents, then starts up what is effectively a kind of background task to read in the thumbnails. So xzgv
       may  not be quite as responsive as usual for a short time after entering a directory with many thumbnails
       (say, a few hundred) --- but on the other hand, at least it is responding. :-)

       - The `background task' makes a special effort to show thumbnails for the files currently visible in  the
       selector first, no matter how much you move around the list, but it reads them all in eventually.

       -  The  thumbnails used in xzgv require 256 colours to display. This can be a problem if you're running X
       in 256 colours or less as, even if you're running  an  8-bit  (256  colour)  server,  there  will  almost
       inevitably  be  fewer  colours  available.  Currently, xzgv just uses whatever gdk reports as the closest
       match to each individual colour used in thumbnails. This gives  a  tolerable  result  on  8-bit  servers,
       assuming  gdk  was  able  to allocate a large number of colours; however, it gives terrible results if it
       couldn't, or if running on 4-bit or 1-bit servers. Sorry about this --- it  should  be  fixed  in  future
       (either  by  using  gdk to draw the thumbnail pixmaps, or by dithering them `by hand' to suit the colours
       available).

       - Finally, when doing a recursive thumbnail update, xzgv (by default)  reads  existing  thumbnails  in  a
       directory  before  updating  any. Or rather, it reads thumbnails for those files currently visible in the
       selector.  This can slow things down very slightly, but keeps the `look and  feel'  consistent  with  the
       normal  update.  (Still, you can disable this with the `--fast-recursive-update' command-line option (see
       Invoking xzgv) or equivalent config file entry (see Configuring xzgv).)

SELECTOR LAYOUT AND RESIZING

       The file selector is simply a list of subdirectories and filenames, along with any thumbnails that  exist
       for  them.  The list is normally in asciibetical order (but you can change this; see Changing the Sorting
       Order). Names of directories are shown first, and they are shown in order at the beginning of  the  list,
       before  all  the  picture  files.  Long  filenames  may  not fit in the visible part of the file selector
       display; if so, there will be a horizontal scrollbar you can use to see the rest of the name(s) (you  can
       use cursor left/right to do this from the keyboard).

       The list is very often larger than can fit on the screen at once. If this is the case, only part is shown
       at a time, but you can move around the list using the (vertical) scrollbar, or with  cursor  up/down  and
       the like.

       If you find the selector window to be too small vertically, and would like to see more files at once, you
       can start xzgv fullscreen by using the -f option (see Options), and/or use `thin  rows'  mode  (see  File
       Selector Options).

       If  you find the selector too small (or too big) horizontally, you can change this by moving the splitter
       line's `handle' (a small square button between the selector and viewer, near the bottom of  the  window),
       which  changes  the  relative  sizes  of the selector and viewer. You can move it by dragging it with the
       mouse, or with these keys:

       `['
              Move the window split left.

       `Ctrl-['
              Move the window split left more slowly.

       `]'
              Move the window split right.

       `Ctrl-]'
              Move the window split right more slowly.

       `~'
              Reset the window split to its default position.

       You can also set the initial/default size of the selector --- in effect, the position of the window split
       --- using `--selector-width' (see Options) or the config file option `selector-width'.

MOVING AROUND THE LIST

       This  section  is mainly for those of us more inclined to the keyboard side of the force. :-) Mouse-happy
       types can freely skip it.

       When the selector has the keyboard focus, the cursor (or in GTK+ jargon, the  `focus  row')  is  normally
       shown as a hollow box around one of the list's rows. This serves the following functions:

       - It selects a file for view commands to operate on.

       -  It  determines which part of the list is shown, as the part of the list shown onscreen always contains
       the cursor (unless you move around using the mouse).

       There are several commands for moving the cursor. In summary, most `special' keys  like  the  cursors  do
       what you'd imagine they do, but in more detail:

       `Cursor Up'
       `k'
              Move up.

       `Cursor Down'
       `j'
              Move down.

       `Page Up'
       `Ctrl-u'
              Move the cursor back roughly a page.

       `Page Down'
       `Ctrl-v'
              Move the cursor forward roughly a page.

       `Ctrl-Home'
       `Ctrl-a'
              Move the cursor to the start of the list.

       `Ctrl-End'
       `Ctrl-e'
              Move the cursor to the end of the list.

       `g'
       `''
              Move the cursor to the first filename starting with the next key pressed, which would generally be
              a letter or number. Case is significant; `a' and `A' are different. If no key is pressed within  2
              seconds, the command is cancelled.

              If  no  files  start  with the specified character, it moves to the first file which starts with a
              later char (in asciibetical order). If there are none for which this is the case, it moves to  the
              last file --- unless there are no files (just directories), in which case it has no effect.

VIEWING A FILE

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

       `Enter'
       `Left-click-on-file'
       `Selector menu, File, Open'
              View the chosen picture file, or if a subdirectory is chosen, make that the current directory.

DIALOG BOXES

       See The Viewer, for details of how the viewer works.  If xzgv has a serious problem reading  a  file,  it
       will  give  an error.  Errors are shown in dialogs which appear in the middle of the screen --- they stay
       there until you click Ok (or press `Enter' or `Esc').

       xzgv also uses similar dialog boxes for other things:

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

       - Showing progress when updating a thumbnail. This is a slightly unusual dialog, in that it automatically
       disappears when the update is complete.  However, it does provide a Cancel button which you can click  to
       abort the update (pressing `Enter' or `Esc' does the same).

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

       `Cursor Left'
       `Ctrl-b'
              Move the cursor left. (A vertical bar shows the cursor position.)

       `Cursor Right'
       `Ctrl-f'
              Move the cursor right.

       `Home'
       `Ctrl-a'
              Move the cursor to the start of the line.

       `End'
       `Ctrl-e'
              Move the cursor to the end of the line.

       `Backspace'
       `Ctrl-h'
              Delete  char to the left of the cursor. (Note that `Backspace' is (usually) the key above the main
              `Enter' key; it is often labelled simply as an arrow.)

       `Delete'
       `Ctrl-d'
              Delete the char the cursor is on.

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

       `Shift-Delete'
       `Ctrl-x'
              Cut text.

       `Ctrl-Insert'
       `Ctrl-c'
              Copy text.

       `Shift-Insert'
       `Ctrl-v'
              Paste text.

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

CLOSING A FILE

       Usually,  when you view a file, the viewer subwindow keeps displaying it until you view a different file.
       However, if you `close' the file, the viewer stops displaying the file and returns to its initial state.

       `Ctrl-w'
       `Selector menu, File, Close'
              `Close' the currently-viewed file, clearing the viewer subwindow.

FILE DETAILS

       The listing the selector gives for a file is pretty sparse --- just the filename and  (if  the  file  has
       one)  the accompanying thumbnail. While this does keep things simple, you sometimes want to know how much
       space a file takes up, when it was last modified, the dimensions of the image, that kind  of  thing.  So,
       you can show details of a single file using the `file details' command:

       `:'
       `;'
       `Selector menu, File, Details'
              Show various details about the file pointed to by the keyboard cursor.  See The Selector Menu, for
              how to choose the file details are given for when using the mouse. (Basically, you right-click  on
              the file when popping up the menu.)

       Most  of  the  details  shown come from the OS (by using the `stat(2)' system call), and should always be
       available unless you have limited permissions for the directory the  file  is  in.  The  file  dimensions
       (width/height),  however,  come from the file's thumbnail. If it doesn't have one, or if it's unreadable,
       or if it has one and it's readable but it doesn't mention the original  image's  width/height,  then  the
       Details from thumbnail area is greyed out.

       (In explanation of the latter point --- pre-5.0 versions of zgv did not generate width/height comments in
       thumbnails, so zgv users in particular may find the width/height details missing. (xzgv has  always  been
       ok,  though,  it's  just zgv which had this problem.) Worse yet, versions 5.0 and 5.1 generated them with
       incorrect sizes for most JPEGs. To fix either problem for a given directory, do `rm -fr .xvpics' in  that
       dir from a shell prompt and recreate the thumbnails with zgv 5.2 or later, or xzgv/xv/Gimp.)

TAGGING

       The  file selector is not restricted to working on one file at a time.  You can `tag' as many (or as few)
       files as you wish, and certain commands described in this section will act on them.

       Initially, all files are untagged, and the filenames usually appear in black (though this depends on  the
       GTK+ theme you're using). Tagged files appear in red.

   Tag and Untag Commands
       There  are  several  ways  to  tag or untag files. The keyboard-based ones which work on individual files
       (also available on the Tagging menu) move the  cursor  down  one  row  afterwards,  to  make  tagging  or
       untagging multiple files easier.

       To tag or untag a single file with the mouse, control-click (i.e. hold down the control key and click) on
       the relevant filename or thumbnail in the selector. It's true that you could use Tag and/or Untag on  the
       Tagging  menu (see The Selector Menu, for how to choose the file tagged/untagged when doing it this way),
       but this is usually much less convenient than using control-click. (The menu entries for those are really
       just for completeness.)

       There  is  also a command available in the viewer to tag the currently-viewed file. See Changing Picture,
       for details.

       `='
       `+'
       `Keypad +'
       `0'
       `Selector menu, Tagging, Tag'
              Tag file.

       `-'
       `Keypad -'
       `9'
       `Selector menu, Tagging, Untag'
              Untag file.

       `Alt ='
       `Alt-Keypad +'
       `Alt-0'
       `Selector menu, Tagging, Tag All'
              Tag all files.

       `Alt -'
       `Alt-Keypad -'
       `Alt-9'
       `Selector menu, Tagging, Untag All'
              Untag all files.

       `Alt-o'
       `Selector menu, Tagging, Toggle All'
              Toggle all tags. This inverts the tagged  state,  so  that  all  previously  tagged  files  become
              untagged, and all previously untagged files become tagged.

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

   Moving Between Tagged Files
       These  commands  let you search for (move to) the next or previous tagged file (if any). Note that `next'
       and `previous' here are relative to the keyboard cursor's position; if you use these from  the  menu,  be
       careful to right-click on the file you want to start the search from.

       `/'
       `Selector menu, Tagging, Next Tagged'
              Move to next tagged file in dir.

       `?'
       `Selector menu, Tagging, Previous Tagged'
              Move to previous tagged file in dir.

       Equivalent commands are also available in the viewer (see Changing Picture).

   Copying/Moving Files
       You  can  copy or move tagged files to a directory you specify. If no files are tagged, xzgv copies/moves
       the file the cursor is currently on --- unless the cursor is on a subdirectory, in which case it gives an
       error.

       `C (Shift-c)'
       `Selector menu, File, Copy'
              Copy  tagged  files  (or  the  current  file)  to a given directory. xzgv asks for the destination
              directory using a dialog (see Dialog Boxes) and copies the files there. If it comes to copy a file
              but  there  is  an existing file in the dir with the same name, the file is not copied and nor are
              any of the remaining files.

       `M (Shift-m)'
       `Selector menu, File, Move'
              Move tagged files (or the current file) similarly.

RENAMING A FILE

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

       `Ctrl-n'
       `Selector menu, File, Rename file'
              Rename  the  current  file  or  directory  ---  xzgv  will  refuse  to  overwrite   any   existing
              files/directories.  The  new name must remain in the current directory. (See Copying/Moving Files,
              for how to move a file to a different directory (albeit keeping the same name).) See The  Selector
              Menu, for how to choose the file renamed when using the mouse.  (Basically, you right-click on the
              file when popping up the menu.)

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

DELETING A FILE

       Deleting a file is pretty straightforward:

       `Ctrl-d'
       `Selector menu, File, Delete file'
              Delete  the  file  pointed  to  by  the  keyboard cursor (and any accompanying thumbnail). See The
              Selector Menu, for how to choose the file deleted when using the  mouse.  (Basically,  you  right-
              click on the file when popping up the menu.)

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

CHANGING DIRECTORY

       The easiest way to change the current directory in xzgv is usually to click on a directory entry  in  the
       file  list  (or  move  the  cursor to it and press `Enter'). Selecting the `..' entry moves to the parent
       directory of the current one.

       There is an alternative though:

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

       `G'
       `Selector menu, Directory, Change'
              Go to a specified directory. xzgv asks for the destination directory using a dialog box which  you
              should type the dir's name into (see Dialog Boxes), and moves to that directory if it exists.

RESCANNING THE DIRECTORY

       Normally,  xzgv  reads  a directory once (on starting up, or when a new directory is selected). So if the
       contents of the directory are changed by another program, this is not automatically reflected.  You  can,
       however,  explicitly  tell xzgv to `rescan' the directory (reread the contents), which will update xzgv's
       notion of what's in it:

       `Ctrl-r'
       `Selector menu, Directory, Rescan'
              Rescan the current directory.

CHANGING THE SORTING ORDER

       Normally, the files are listed in asciibetical order by name. However, you can instead have the file list
       sorted by size, last-modified date/time, or by `extension' (the file type).

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

       `Alt-n'
       `Selector menu, Directory, Sort by Name'
              Sort by name. This is the default.

       `Alt-e'
       `Selector menu, Directory, Sort by Extension'
              Sort by extension.

       `Alt-s'
       `Selector menu, Directory, Sort by Size'
              Sort by size. The biggest files are listed last.

       `Alt-d'
       `Selector menu, Directory, Sort by Time & Date'
              Sort by time/date. The newest files are listed last.

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

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

       `Alt-Shift-m'
       `Selector menu, Directory, Time & Date Type, Modification Time (mtime)'
              Use the last-modified time (`mtime'). This is the default.

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

       `Alt-Shift-a'
       `Selector menu, Directory, Time & Date Type, Access Time (atime)'
              Use the last-accessed time (`mtime'). The selector order is not automatically  updated  when  xzgv
              reads files, since this would probably be annoying; do a manual rescan if need be.

FILE SELECTOR OPTIONS

       Various  aspects of the file selector's behaviour can be configured while xzgv is running, by using these
       toggle commands (which enable the feature if it was previously disabled, and vice versa).

       These settings can also be altered using command-line options (see Options) and/or config  file  settings
       (see Configuring xzgv).

       `Alt-a'
       `Selector menu, Options, Auto Hide'
              Toggle  the  auto-hiding  of the selector when a picture is viewed (off by default). This is handy
              for small screens/windows, or for old-time zgv users who just dig that groovy modal interface, er,
              man. :-)

       `Alt-b'
       `Selector menu, Options, Status Bar'
              Toggle  status  bar  at  the  bottom  of  the selector (off by default). This displays messages in
              certain circumstances --- normally, it just says when a picture is being read.

       `Selector menu, Options, Thumbnail Msgs'
              Toggle reading-thumbnails messages (default is off), only visible if the status  bar  is  enabled.
              These  messages  make  it  clear when all thumbnails have been read, but having something flash up
              every time you change directory is generally just annoying.

       `v'
       `Selector menu, Options, Thin Rows'
              Toggle `thin rows' mode (off by default), in which thumbnails are shown at a  third  their  normal
              size  so  that  many  more  files  can  be  shown  at once. (The odd keyboard shortcut for this is
              inherited from zgv's `visual' mode toggle, which had a roughly similar effect.)

       `Alt-i'
       `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.

THE VIEWER

       Once you've selected a file to view, it's shown in the viewer (the right-hand  part  of  xzgv's  window).
       This section describes what you can do while viewing the picture.

       Like  the selector, the viewer has its own menu --- right-click anywhere on the viewer (or press `F10' or
       `Menu') to show it --- and a similar help menu (see The Selector Menu).

EXITING THE VIEWER

       When using the mouse to control xzgv, it doesn't matter whether the selector or the viewer  has  keyboard
       focus  ---  mouse  operations transcend such petty boundaries. :-) But keyboard control is (of necessity)
       effectively modal, and so you need to `exit' the viewer in  order  to  have  keyboard  control  over  the
       selector again. You also need to exit the viewer if you've enabled auto-hide mode.

       Exiting the viewer is simple:

       `Esc'
       `Tab'
       `Viewer menu, Exit to Selector'
              Exit the viewer. This also returns the selector to its former size, if it was previously `hidden'.

       Another  way  of exiting the viewer is to middle-click on it, but this mouse-only approach is really only
       of use when the selector is `hidden'.

BIG PICTURES

       A picture may well be too large to fit entirely in the viewer window.  There are two  main  things  which
       can help you see more of the picture at once:

       -  Make the xzgv window larger. You could `maximize' it with your window manager, or you could start xzgv
       with a larger window using `--geometry' or fullscreen mode (see Options). The fullscreen mode gives  xzgv
       the maximum window size possible, but needs co-operation from your window manager (and alas, many are not
       as willing as one might like) --- in some cases you may even  find  `--geometry  100%x100%'  to  be  more
       effective.

       -  Hide  the  selector.  To  do  this, either use auto-hide mode (see File Selector Options), or hide the
       selector explicitly (see Hiding the Selector).

       But of course, these are only partial solutions to the problem; there will inevitably always be  pictures
       larger  than  your  screen can show at once. In general, then, there are two ways to see the whole of the
       picture.

   Scrolling
       Scrolling is the default approach to handling big pictures in xzgv. When the viewer is  started  up,  the
       top-left  of  the  picture is shown --- you can either drag the picture around with the mouse (i.e. click
       and hold the button down, then move the mouse around), or use the scrollbars, or use the cursor keys (and
       others) to move around the rest of the picture:

       `Cursor Up'
       `K'
              Move up 100 pixels. `Ctrl-Cursor Up' and `k' both move up 10 pixels.

       `Cursor Down'
       `J'
              Move down 100 pixels. `Ctrl-Cursor Down' and `j' both move down 10 pixels.

       `Cursor Left'
       `H'
              Move left 100 pixels. `Ctrl-Cursor Left' and `h' both move left 10 pixels.

       `Cursor Right'
       `L'
              Move right 100 pixels. `Ctrl-Cursor Right' and `l' both move right 10 pixels.

       `Page Up'
       `Shift-Cursor Up'
       `Ctrl-u'
              Move up (nearly) the window height. (It moves by 90% of the height.)

       `Page Down'
       `Shift-Cursor Down'
       `Ctrl-v'
              Move down (nearly) the window height.

       `-'
       `Shift-Cursor Left'
              Move left (nearly) a window-length. (It moves by 90% of it.)

       `='
       `Shift-Cursor Right'
              Move right (nearly) a window-length.

       `Home'
       `Ctrl-a'
              Move to the top-left of the picture.

       `End'
       `Ctrl-e'
              Move to the bottom-right of the picture.

   Zoom Mode
       An  alternative way of viewing the whole picture, one which lets you see the picture onscreen all at once
       no matter how big (or small) it is, is zoom mode.

       Zoom mode's name derives from the idea of `zooming' a small file up to fit the window. But in reality, it
       is more often used to reduce a large file to fit.

       Zoom  mode  is  not  the  default, and has to be enabled. Once enabled, it stays on until you turn it off
       again (or until you enable scaling, or select Normal (see Scaling)).

       `z'
       `Viewer menu, Options, Zoom (fit to window)'
              Toggle zoom mode.

       `Alt-r'
       `Viewer menu, Options, When Zooming Reduce Only'
              When in zoom mode, only reduce pictures to fit. This can be useful when going  through  a  lot  of
              unpredictably-sized  pictures,  as  it  means that you can see all of a big picture easily without
              also meaning that tiny little icons assume a scale of Biblical proportions. :-)

       `Alt-p'
       `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.

       The way zoom mode reduces a file to fit the window is (relatively) quick but  harsh,  and  may  make  the
       picture  look  a  bit ugly. In future there may be a smoothing option like zgv's vkludge, but for now I'm
       afraid the fairly crude resize is all that's available.

       There is in fact an alternative to zoom mode, as you can scale down an image instead. This  is  generally
       only useful for very large images, however; zoom mode tends to be the Right Thing for the most part.

SCALING

       You  can  scale a picture --- this makes it appear larger (or smaller) onscreen. xzgv acts much as if the
       scaled picture were the real picture; for example, the cursor keys scroll around in steps of  100  scaled
       pixels,  even  if  this  means moving a fraction of a pixel (or many pixels) in the original picture (and
       similarly for movement with the mouse).

       The main limitation of scaling (other than how much it slows things down :-), at least when  scaling  up)
       is  that  you  can  only  scale  by integer values, so you can only make each pixel in the image twice as
       wide/high, or three times as wide/high, or four times, and so on.

       (It may seem odd saying e.g. `twice as wide/high' rather than `twice the size',  but  technically  `twice
       the size' would be referring to scaling up the width (and height) by about 1.414...)

       Normally,  xzgv  does  no  scaling,  which could be considered a ratio of 1:1.  Scaling up increases that
       ratio. How it is increased depends on which option/key you use:

       `d'
       `Viewer menu, Scaling, Double Scaling'
              Increase the ratio by doubling it --- this leads to ratios of 2:1, 4:1, 8:1...

       `s'
       `Viewer menu, Scaling, Add 1 to Scaling'
              Increase the ratio by adding one --- leads to ratios of 2:1, 3:1, 4:1...

       There are similar commands to decrease the ratio:

       `D (Shift-d)'
       `Viewer menu, Scaling, Halve Scaling'
              Decrease the ratio by halving it.

       `S (Shift-s)'
       `Viewer menu, Scaling, Sub 1 from Scaling'
              Decrease the ratio by subtracting one.

       Usually the double/halve scalings are more useful.

       Note that you can also double/halve the scaling by using shift-left-click on the viewer  to  double,  and
       shift-right-click  to  halve.  This  still changes scale `around' the middle of the window though (rather
       than around the point clicked on, as you might expect), which is a little strange  and  may  possibly  be
       changed in future.

       When you scale `below' 1:1, the above commands lead to ratios of (e.g.)  1:2, 1:4, 1:8, etc. --- that is,
       the ratios work the same way, but the other way around. This gives you an increasingly small image.

       The scaling ratio is never decreased below 1:32. It is also never increased beyond the  point  where  the
       overall  image  size  would  exceed  32767x32767 --- this limit is due to the combination of X's limit on
       window sizes, and the implementation used by xzgv for scaling.

       One problem with scaling up, given the way it's currently implemented, is that it's  not  well-suited  to
       dithered display --- so if you're running on an 8-bit server, dragging the image around slowly when using
       scaling (especially scaling with interpolation) may result in  some  nasty,  streaky,  undithered-looking
       parts of the picture. :-(

       You can undo the effect of scaling (up or down) at any time:

       `n'
       `Viewer menu, Scaling, Normal'
              Resume `normal' display --- disables scaling mode, and also zoom mode.

       Normally,  scaling up works by simply making the pixels into larger and larger squares (in effect), which
       remain the same colour. However, you can enable a feature called `interpolation' which smoothly graduates
       the colour change between the top-left corners of each pixel. This is very slow, but looks nice.

       `i'
       `Viewer menu, Options, Interpolate when Scaling'
              Toggle interpolation in scaling mode.

       (If  you  like  the  appearance  of scaling with interpolation, you may also be interested in a program I
       wrote called pnminterp, which can scale up a PGM or PPM file while applying this effect. These days  it's
       part of the netpbm package.)

       Scaling  down,  however,  is  implemented a bit like a special-case zoom mode, and currently there are no
       ways of making that look nicer. :-/

       xzgv normally `reverts' scaling (returning the scale to 1:1) back to normal when you view a new  picture.
       However, it's possible to disable this behaviour (see Viewer Options).

       There  is  also support for an alternative form of scaling --- decoupled, or axis-specific, scaling. When
       you scale in this way, only one axis of the image is scaled at once. For example,  you  might  choose  to
       effectively  double  the height of an image (with the width left unchanged). Indeed, this sort of scaling
       is useful for temporarily correcting pictures intended for display using pixels twice as wide or high  as
       normal.

       `x'
       `Viewer menu, Scaling, X Only, Double Scaling'
              Increase the (x axis) ratio by doubling it.

       `X (Shift-x)'
       `Viewer menu, Scaling, X Only, Halve Scaling'
              Decrease the (x axis) ratio by halving it.

       `Alt-x'
       `Viewer menu, Scaling, X Only, Add 1 to Scaling'
              Increase the (x axis) ratio by adding one.

       `Alt-Shift-x'
       `Viewer menu, Scaling, X Only, Sub 1 from Scaling'
              Decrease the (x axis) ratio by subtracting one.

       `y'
       `Viewer menu, Scaling, Y Only, Double Scaling'
              Increase the (y axis) ratio by doubling it.

       `Y (Shift-y)'
       `Viewer menu, Scaling, Y Only, Halve Scaling'
              Decrease the (y axis) ratio by halving it.

       `Alt-y'
       `Viewer menu, Scaling, Y Only, Add 1 to Scaling'
              Increase the (y axis) ratio by adding one.

       `Alt-Shift-y'
       `Viewer menu, Scaling, Y Only, Sub 1 from Scaling'
              Decrease the (y axis) ratio by subtracting one.

       There  are  also  mouse  shortcuts  for  scaling up/down a single axis; control-left-click scales up, and
       control-right-click scales down. By default this acts on the y axis, but the active axis can  be  toggled
       with `Alt-c', or by toggling the `Ctl+Click Scales X Axis' option (see Viewer Options).

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

MIRROR AND ROTATE

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

       `m'
       `Viewer menu, Orientation, Mirror (horiz)'
              `Mirror' the picture (flip it horizontally).

       `f'
       `Viewer menu, Orientation, Flip (vert)'
              `Flip' the picture (flip it vertically).

       `r'
       `Viewer menu, Orientation, Rotate Right'
              Rotate the picture 90 degrees clockwise.

       `R (Shift-r)'
       `Viewer menu, Orientation, Rotate Left'
              Rotate  the  picture 90 degrees anti-clockwise. (Any US readers surprised and/or annoyed by my not
              saying `counter-clockwise' will realise why the menus say rotate right/left. :-))

       `N (Shift-n)'
       `Viewer menu, Orientation, Normal'
              Restore the picture orientation to normal. This undoes the effect of any  mirrors,  flips,  and/or
              rotations.

       xzgv  normally  `reverts'  the  picture  orientation  (the  way  the  picture  has  been  transformed  by
       mirror/flip/rotate) back to normal when you view a new picture. However, it's possible  to  disable  this
       (see Viewer Options), so that any new pictures are mirrored, flipped, and/or rotated in the same way.

CHANGING PICTURE

       It's  possible to go directly to the previous or next file (or tagged file) in the directory, or to tag a
       file, without having to pick the file from the file selector by hand.  These  commands  are  particularly
       useful  when  using  xzgv  from the keyboard, but there's also a notable mouse shortcut for moving to the
       next image.

       `Space'
       `Viewer menu, Next Image'
              Move to next file in dir, and view it. You can also click on the picture/viewer to  do  this.  (If
              you  find  this  interferes  with dragging the picture around (though it shouldn't), or just don't
              like it, it can be disabled (see Config Variables).)

       `b'
       `Viewer menu, Previous Image'
              Move to previous file in dir, and view it.

       `Ctrl-Space'
       `Viewer menu, Tagging, Tag then Next'
              Tag current file, then move to next file in dir and view it.

       `/'
       `Viewer menu, Tagging, Next Tagged'
              Move to next tagged file in dir, and view it.

       `?'
       `Viewer menu, Tagging, Previous Tagged'
              Move to previous tagged file in dir, and view it.

HIDING THE SELECTOR

       When running on small screens, or in a small window, it can get a bit annoying to lose  viewer  space  by
       having  the  selector  constantly  displayed  when you don't actually need it. The usual solution to this
       problem is to enable auto-hide mode. But what if some pictures you're viewing are small and  some  large?
       It  can  sometimes  be  nearly  as annoying having the selector hidden to `make room for' a small picture
       which didn't need it. So for that reason, or perhaps if you just don't like auto-hide mode :-),  you  may
       prefer to leave auto-hide off and explicitly hide the selector when necessary:

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

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

MINIMIZING XZGV

       Generally it's easy enough to use your window manager to change windows etc., but when running fullscreen
       this  can  sometimes be a little problematic. For this reason, xzgv has built-in support for `iconifying'
       itself:

       `Ctrl-z'
       `Viewer menu, Window, Minimize'
              Minimize the xzgv window.

VIEWER OPTIONS

       As with the selector, various options can be disabled/enabled which relate to the viewer.

       These settings can also be altered using command-line options (see Options) and/or config  file  settings
       (see Configuring xzgv).

       `z'
       `Viewer menu, Options, Zoom (fit to window)'
              Toggle zoom mode, discussed in more detail elsewhere (see Zoom Mode).

       `Alt-r'
       `Viewer menu, Options, When Zooming Reduce Only'
              Toggle reduce-only in zoom mode, also covered elsewhere (see Zoom Mode).

       `Alt-p'
       `Viewer menu, Options, When Zooming Panorama'
              Toggle panorama view in zoom mode, also covered elsewhere (see Zoom Mode).

       `i'
       `Viewer menu, Options, Interpolate when Scaling'
              Toggle  interpolation  when  a  picture is being scaled-up. Again, this has already been mentioned
              (see Scaling).

       `Alt-c'
       `Viewer menu, Options, Ctl+Click Scales X Axis'
              Toggle the axis scaled when you control-click (or control-right-click) on the image.  The  default
              is to scale the y axis.

       `F (shift-f)'
       `Viewer menu, Options, Dither in 15 & 16-bit'
              Toggle  dithering  in  15/16-bit modes. This increases the apparent colour depth making gradations
              look much better, but it's slower than undithered rendering, and can (in 16-bit) slightly  distort
              a  picture's colour balance. (The `F' key was chosen for this as the dither toggle is functionally
              similar to zgv's `fakecols' toggle.)

       `Viewer menu, Options, Revert Scaling For New Pic'
              Normally xzgv returns the scaling back down to 1 (normal) when  a  new  picture  is  selected.  By
              disabling  this,  you can retain scaling across picture selection. (There is currently no keyboard
              shortcut for this fairly-seldom-changed option --- to toggle it from the keyboard, you should  use
              the popup menu (press `F10'), and select the menu item.)

       `Viewer menu, Options, Revert Orient. For New Pic'
              Similarly,  xzgv  returns  to  the  picture's  true  orientation  (not mirrored, rotated, etc.) on
              selecting a new picture. Disabling  this  option  means  that  any  mirrors/flips/rotates  applied
              persist across multiple images.  (No keyboard shortcut --- see above.)

       `Viewer menu, Options, Use Exif Orientation'
              Toggle support for Exif orientation. Devices which create JPEG files in the Exif format (e.g. many
              digital cameras) may add an orientation tag to the file, which says how the camera was being  held
              when  the picture was taken. When this tag is present, xzgv can adjust the image to compensate for
              a camera being held on its side. (This isn't done by default as it misrepresents the  true  image,
              which could be confusing if you don't know why it's happening.) Enabling this option may be useful
              if you take pictures with your camera on its side, but don't want to have to rotate  the  pictures
              before  being  able  to  view  them  properly.  Of  course, for this to work your camera has to be
              inserting the orientation tag in the first place --- but it can't hurt to  try  it  and  see.  (No
              keyboard shortcut --- see above.)

FILE FORMATS

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

FILE TYPE IDENTIFICATION

       The format a file is in is identified by its content. The file-reading code relies on libgdk to determine
       the  file  type and read the file correctly; generally this uses the format's `magic number' to determine
       file type --- e.g. a JPEG/JFIF file starts with the (hex) bytes `FF D8'. So if you start xzgv  with  xzgv
       foo,  and foo is in a supported format (such as JPEG), the format will be figured out and the file loaded
       even though the `extension' is absent.

CONFIGURING XZGV

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

CONFIG FILES

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

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

       # Sample xzgv config file
       # Comment lines begin with `#' and are ignored,
       #  as are blank lines.

       # make pics fit window
       zoom on
       # hog the screen :-)
       fullscreen on

       It is a line-based format. Each line (or rather, each line which is not a comment line and is not  blank)
       assigns  a  value  to  a single predefined `variable'. xzgv has many such variables it lets you modify in
       this way.  For example, the fullscreen option above controls whether or not xzgv tries to use  the  whole
       screen  for  its  window.  If it is given the value `on'/`y'/`yes'/`1' it does; if `off'/`n'/`no'/`0', it
       doesn't. Most variables are of this yes-or-no `boolean' type.

       Since the variables set in a config file have a direct effect on how xzgv works,  it  can  be  easier  to
       simply call them `settings'. Indeed, such terminology is used on occasion in this documentation.

CONFIG VARIABLE TYPES

       There are various types of variable:

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

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

       - Geometry. This window size-and/or-position  specification  format  is  only  used  for  the  `geometry'
       setting. See Options, for a description of how this type works.

CONFIG VARIABLES

       Currently,  most  configuration  variables  (settings)  in  xzgv can also be set by command-line options;
       indeed, the name of the setting in all such cases is identical to that for the long version of the option
       (e.g. `fullscreen', `auto-hide'). As such, they're documented in the section which discusses command-line
       options and the like (see Options).

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

       click-for-next
              This is enabled by default, allowing you to click on the viewer to skip  to  the  next  image.  If
              disabled, clicking on the viewer does nothing.

RATIONALE

       Here  I  (RJM)  attempt  to  explain why I did things the way I did. This is presented in a question-and-
       answer format of sorts.

WHY YET ANOTHER VIEWER?

       Previously, this section concentrated on xv; that may have made sense when I  originally  wrote  it,  and
       still  makes  a  certain limited amount of sense for zgv, but for xzgv it was looking increasingly dated.
       And so here I am writing an update. :-)

       I originally wrote xzgv as I simply wasn't happy with the viewers for X that I was aware of at  the  time
       (mid-1999). At the time of writing (late 2000), other key things about xzgv are becoming apparent, partly
       through responses I've been getting to it:

       o It's `fast'. No, it doesn't do any particular operation faster than other viewers  as  far  as  I  know
       (well,  maybe  thumbnail  updates  :-));  rather,  the interface tries not to get in your way. Click on a
       filename, and the picture appears. No multiplicity of toolbars or windows, it's just there.

       o As with zgv, it tries to do one thing well, viewing pictures. It isn't perfect  in  this  regard,  I'll
       admit, but at least it stays well clear of picture editing.

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

       I  won't  pretend  xzgv is The Ultimate Viewer For Everyone. Some people will prefer other approaches, or
       just simply prefer other viewers. (Some people may even still use xv,  ghod  forbid.)  There  are  a  few
       viewers which you may like to try if you don't think much of xzgv:

       o  gqview.  This  seems  to be well-regarded. I find it a bit gimmicky and kitchen-sink-ish; not quite as
       `pure' or focused as xzgv, IMHO. I think more people use it than xzgv though.

       o xli. I'm not sure if this is maintained these days, but it's not too bad a  viewer.  No  thumbnails  or
       file selector though. (These days I mostly use this for setting the root window pixmap, something I don't
       think belongs in a viewer, but which xli does happen to be quite good at.)

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

       o gtksee. I've not tried this, but I think the idea is that it's an ACDSee clone, and there seem to be an
       awful lot of people who want a clone of that. Which is their problem. :^)

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

       Ah, you say, what of xv? Well, we've emphatically reached the point where no-one need use  xv  any  more.
       Anyone using xv these days really should drop that pile of ill-conceived non-Free crap and use one of the
       better viewers now available. It's that simple.

WHY NO IMAGE-EDITING CAPABILITIES?

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

       (OTOH, if you want a decent image editor, use the Gimp.)

WHY A TEXINFO MANUAL?

       For years, I maintained a conventional `man page' for zgv (which xzgv was loosely  based  on).  But  over
       time, I realised just how impossibly confusing the zgv man page had become.

       So  I wanted to rewrite zgv's documentation in a more sensible way, in some other format than a man page.
       I wanted an established, well-supported format with structure and cross-referencing. I felt this made  it
       a choice between HTML and texinfo. HTML seemed to me to be a moving target like no other, and not as well
       supported on text-only terminals as Info (and thus texinfo). (This latter point  is  admittedly  not  too
       relevant as far as xzgv is concerned.) When I noticed that a converter existed to convert texinfo to HTML
       in any case, the case was closed. xzgv's documentation was then based on zgv's --- the  documentation  is
       probably more similar than the programs are. :-)

       Don't  get  me  wrong  --- I like man pages. And even with the excellent Texinfo documentation and Emacs'
       very helpful Texinfo mode, writing texinfo is hardly easy. (Without Texinfo mode's node- and  menu-update
       commands,  I  personally  would  find  it  near-impossible!)  But big man pages just aren't that good for
       reference, and this is made worse by the relative lack of structure.

WHY ONE-SPACE SENTENCE ENDS?

       The conventional way to write texinfo is to follow each sentence  with  two  spaces  after  the  dot  (or
       whatever  ends  the  sentence).  Many  people normally write this way in a non-texinfo context too. But a
       sizeable proportion of people normally write text with only one space after the dot --- and  I'm  one  of
       them.

       The  Texinfo documentation gives the impression that two-space must be used; it says ``it is important to
       put two spaces at the end of sentences in Texinfo documents.'' But the only circumstance in which spacing
       from  the  texinfo file is preserved at all (in any sense other than `there is a space here') is when the
       texinfo is converted to Info format. So, in fact, the decision to use two-space depends on how the author
       wants  Info  output  to  appear  ---  this  is a subjective decision which should be entirely down to the
       preference of the author, despite the Texinfo documentation's attempt to make  two-space  sound  like  an
       objective you-must-do-this kind of thing.

       You  might  wonder  what  the  problem  with  using  one-space is, then. Well, `makeinfo' has to reformat
       paragraphs, and whenever it needs to insert space at (what appears to it to be) the end of a sentence, it
       inserts  two  spaces.  This  behaviour cannot be altered, unlike in Emacs (sentence-end-double-space; see
       Fill Commands in the emacs info file) and GNU fmt (-u; see fmt invocation in the  textutils  info  file).
       Also,  attempting to `fix' the output Info with sed doesn't work properly because the `tags' used to find
       nodes quickly are then incorrect. These could of course also be fixed, but this would involve a lot  more
       work than a simple sed invocation.

       So  realistically,  anyone  who writes texinfo with one-space has to put up with the occasional two-space
       sentence end being inserted into their text --- worse still, the current `makeinfo' formatting  algorithm
       seems  to  insert two spaces even after abbreviations (such as `e.g.' and `etc.'), which breaks even two-
       space texinfo. (This is particularly ironic, by the way, since  two-space  partisans'  main  argument  in
       favour of the practice is often the way it makes it possible to tell the difference between abbreviations
       and the end of a sentence.)

       One last point may be worth noting; I am not the first person to write texinfo files using one-space.  At
       the  time  of  writing,  it is used in the texinfo documentation for BFD, gdbm, GTK/GDK, (Linux) IPC, and
       viper, and I expect there are instances I'm not aware of.

BUGS AND RESTRICTIONS

       All (non-trivial) programs have bugs. Anyone who denies this...

       - clearly hasn't written too many programs.

       - is wrong. ;-)

       It follows that xzgv, like everything else, always has some bugs.  Usually these are not too serious,  or
       I'd  have  fixed  them before releasing xzgv. But either way, bugs and other problems with xzgv are noted
       here.

KNOWN BUGS

       - In zoom mode, it copes with resizing the window as a whole, but doesn't when you change the size of the
       pane  (apart  from when hiding/showing selector or resizing from keyboard, but that's only 'cos I kludged
       it :-)).

       - When scaling up and dithering, you end up with a crappy-looking picture if you drag the picture  around
       slowly  (since  each  exposed  bit  is dithered independently, with no regard given to matching up to any
       previous error-diffusion).

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

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

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

       -  When  dragging  an image around, if you quickly move the mouse pointer over from the image area to the
       selector area, the image seems to `jump' a little. I think this may have something to do with  the  paned
       window's  window-splitting bit, but I'm not sure. Also, it jumps when moving across scrollbar sliders and
       the paned window splitter handle.

       - It doesn't apply any tranparency mask. The practical result of this seems to be purple transparent bits
       in  thumbnails and scaled-up images, and black transparent bits elsewhere. This doesn't affect PNG files,
       though.

       - If a GIF file is corrupted in such a way that the decompressed image has a larger number of  pixels  in
       it, the extra pixels will be ignored and no error or warning will be generated.

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

SUBOPTIMAL FEATURES

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

       - xzgv doesn't duplicate zgv's behaviour of generating  thumbnails  under  ~/.xvpics/_foo_bar_baz  if  it
       can't  generate them in /foo/bar/baz/.xvpics. I doubt anything else supported it, and it complicated lots
       of things unnecessarily. This isn't particularly suboptimal, but as an incompatibility with zgv it merits
       mention.

RESTRICTIONS

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

REPORTING BUGS

       If you find xzgv does something wrong, which you suspect might be a fault of some sort  (a  bug)  in  the
       program,  it  is  best  to  report it as I may not be aware of the problem. (But first, check it is not a
       `known bug'.  See Known Bugs. It is not usually helpful to report a bug I already know about.)

       It is important to include as much detail in a bug report as you can.  Here are some details  you  should
       include:

       o The version of xzgv you are running. `xzgv --version' reports this.

       o The versions of GTK+ you are using. `xzgv --version-gtk' reports the GTK+ version being used by xzgv.

       o  The  bitdepth your X server is running in (common depths are 16-bit, 24-bit, and 32-bit). If you don't
       know what depth you're running in, try `xdpyinfo|grep depth'.

       o A description of the bug --- what effects it has, the circumstances it occurs in, and so  on.  Does  it
       only  happen  for  certain types of file?  Only when in 8-bit modes? Only when dithering is enabled? Even
       `irrelevant' details can sometimes be useful.

       o Finally, if you are a programmer and believe you have managed to fix  the  bug  yourself,  patches  are
       gratefully accepted. :-) You should generate the patch using `diff -c' or (preferably) `diff -u'.

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

REPORTING DOCUMENTATION BUGS

       Bugs  in  the  documentation  can sometimes cause as much trouble as bugs in the program; if you notice a
       problem in the documentation, it's a good idea to report it.

       For reports of documentation bugs, you should include these details:

       o The version of xzgv the documentation is for.

       o If it is a problem in one specific section of the documentation, specify which part it is  (by  this  I
       mean the heading it comes under; texinfophiles should read this as `the node name' :-)).

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

       o A description of the problem.

FUTURE CHANGES

       See  Reporting Bugs, for details of where to send the bug report.  If you want to suggest a feature you'd
       like in xzgv, or a change to an existing feature, contact me; see See Reporting Bugs for the address.

       Future changes etc. are listed in the TODO file.

AUTHOR

       Russell Marks <rus@svgalib.org> and others; see the section ACKNOWLEDGEMENTS for details.

SEE ALSO

       zgv(1), xv(1), cjpeg(1), djpeg(1), pbm(5), pgm(5), ppm(5), mrf(5)