Provided by: xzgv_0.9.2-2build1_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)