Xzgv

From CleanPosts

Jump to: navigation, search

XZGV(1) Graphics Software XZGV(1)

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 sub‐
      directories  and  picture  files in the current directory, along with small `thumbnail'
      versions of the pictures if they exist. (If no thumbnails appear in a given  directory,
      or  if they are missing for some files, you can create/update them by pressing `u'. See
      Updating Thumbnails.)
      When you've picked a file to view, you can view it  by  clicking  on  it,  or  pressing
      `Enter'.  This  reads the picture and displays it in the right-hand part of the window,
      the viewer (see The Viewer). You can then move around the picture (if it is larger than
      will  fit)  by dragging it with the mouse, or using the scrollbars, or the cursor keys.
      You can then select another image with the file selector  (though  you  need  to  press
      `Esc' or `Tab' first if using the keyboard), or you can quit xzgv by pressing `q'.
      While  xzgv  works  much like any other X program, and is certainly mouse-friendly :-),
      it's also designed to be keyboard-friendly.  Everything in xzgv can  be  done  entirely
      from the keyboard. Much of this keyboard support works like the original zgv (a similar
      console-based picture viewer for Linux).
      This overview is, as you might expect, only the very simplest of introductions to  what
      xzgv  can do, and describes only a very basic use of xzgv. xzgv can do a lot more; read
      on to find out what.

ACKNOWLEDGEMENTS

      xzgv was primarily written by Russell Marks, also the author  of  this  manual.  It  is
      maintained by Reuben Thomas.
      Costa  Sapuntzakis  contributed code for much faster JPEG thumbnail generation (to zgv,
      which I adapted for xzgv).
      The directory/file icons used were loosely based on gmc's dir-close.xpm. I think Tuomas
      Kuosmanen was responsible for that, judging from the change log.
      `mkinstalldirs'  is straight from the `texinfo' package, and was written by Noah Fried‐
      man. (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 set‐
      tings 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  over‐
             ride.)
      `--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 win‐
             dow-manager decorations (window frame, title bar, etc.) if possible.
      `-G val'
      `--gamma val'
             [Not supported in 0.9.] Set the gamma adjustment used  (see  Gamma  Adjustment).
             The  default  is 1.0. This also sets the `initial value' used when resetting the
             gamma adjustment.
      `-g geom'
      `--geometry geom'
             Set the xzgv window's geometry (position and/or  size)  to  geom.  The  geometry
             string  should be in the usual X format, with the extension that positions/sizes
             may have a `%' suffix meaning that they are treated as percentages of the screen
             width/height. The default geometry is `92%x85%'.
             For  those  unfamiliar with the way `geometry' works, here's a brief description
             of the syntax. It's `WxH', or `+X+Y', or `WxH+X+Y',  where  `W'  is  width,  `H'
             height,  `X'  the  x  position, and `Y' the y position. The first form specifies
             only the size, the second only the position ---  the  `WxH+X+Y'  form  specifies
             both.
             Now,  the `+X+Y' bit normally specifies where the top-left of the window is. But
             you can use `-' instead of `+' for the x and/or y position,  in  which  case  it
             specifies the gap between the right/bottom of the window and the right/bottom of
             the screen. (Note, however, that any window frame your window  manager  adds  to
             the  window  is  disregarded  in this calculation, so you may need to experiment
             somewhat to get the desired position.) You can also use  negative  numbers  with
             both  `+'  and  `-'  ---  so `+-50+0' puts the window partly off the left of the
             screen, and `+0--50' puts it partly off the bottom of the screen --- but this is
             of questionable value. :-)
             Finally, as mentioned above, xzgv extends this syntax by allowing you to use `%'
             to specify percentages of the  screen  width/height  rather  than  pixels,  e.g.
             `50%x30%-30%-20%'. It also allows you to use real numbers such as `12.34', which
             can be useful with `%'.
      `-h'
      `--help'
             Display a list of options and a terse description of what the options do.
      `--image-bigness-threshold numpix'
             Set the boundary numpix after which images are  considered  `big',  and  are  no
             longer  rendered all-at-once (which gives much nicer scrolling, but is harder on
             memory and can be slow for big images) but are instead rendered  piece-by-piece.
             Units  are  number of pixels in image (i.e. width times height), and the default
             is 2000000 pixels.
      `--interpolate'
             Interpolate between the picture's pixels when scaling  up  (see  Scaling).  This
             usually looks nicer, but it's rather slow.
      `--mouse-scale-x'
             If  enabled, control-clicking on the viewer scales only the X axis. (The default
             is to scale only the Y axis.)
      `--revert-orient'
             (Note that this is normally enabled; use `--revert-orient=off' to  disable  it.)
             If disabled, orientation (flip/mirror/rotate) state is retained between pictures
             (see Viewer Options).
      `--revert-scale'
             (Note that this is normally enabled; use `--revert-scale=off' to disable it.) If
             disabled, scaling is retained between pictures (see Viewer Options).
      `--selector-width'
             Set  the  default/initial  size of the selector in pixels. The normal setting is
             200.
      `-T'
      `--show-tagged'
             Show names of currently-tagged files on exiting xzgv. (They're listed to stdout,
             one per line.) This can be useful when you want to select multiple files graphi‐
             cally 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  set‐
             ting (`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 set‐
             tings are `mtime' (default), `ctime', and `atime'; only the first  char  of  the
             setting (`m'/`c'/`a') need be given.
      `--statusbar'
             Show  a status bar below the selector; this, for example, says when a picture is
             being read.
      `-t'
      `--thin-rows'
             Use rows a third the normal height in the selector. This can be very  useful  on
             lower-resolution  screens,  or  if  you're  really  interested in filenames, not
             thumbnails.
      `-v'
      `--version'
             Show version number.
      `--version-gtk'
             Show version number of GTK+ xzgv is using.
      `-z'
      `--zoom'
             Fit picture to viewer window, whatever its actual size (see Zoom Mode).
      `-r'
      `--zoom-reduce-only'
             When in zoom mode, only reduce pictures to fit; i.e. make big pictures  viewable
             all-at-once while leaving small picures intact.
      If started with `xzgv files', xzgv hides the file selector and treats the file or files
      as if they were the sole contents of a directory.  (It  also  automatically  loads  the
      first  file.)  As such, you can use the Next Image and Previous Image commands to navi‐
      gate 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 start‐
      ing 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  set‐
      ting   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  pic‐
      ture  files in the current directory, along with small `thumbnail' versions of the pic‐
      tures 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  every‐
      thing in xzgv, this isn't often that useful. :-))
      Usually,  it doesn't matter where on the selector you right-click.  However, a few com‐
      mands on the File menu operate on a single file, the one selected by the keyboard  cur‐
      sor.  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  home‐
             page.
      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 cre‐
      ate/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 per‐
      mission 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 sub‐
      directories 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 but‐
             ton, 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  subdi‐
             rectories.  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  cur‐
      rently  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 selec‐
      tor 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 dif‐
             ferent. 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 cur‐
             rent 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  thumb‐
      nail. 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  thumb‐
      nail 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 thumb‐
             nail). 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 direc‐
      tory 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,  mov‐
             ing 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  man‐
             ual rescan if need be.

FILE SELECTOR OPTIONS

      Various  aspects  of the file selector's behaviour can be configured while xzgv is run‐
      ning, 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 con‐
      fig file settings (see Configuring xzgv).
      `Alt-a'
      `Selector menu, Options, Auto Hide'
             Toggle the auto-hiding of  the  selector  when  a  picture  is  viewed  (off  by
             default). This is handy for small screens/windows, or for old-time zgv users who
             just dig that groovy modal interface, er, man. :-)
      `Alt-b'
      `Selector menu, Options, Status Bar'
             Toggle status bar at the bottom of the selector (off by default). This  displays
             messages  in  certain circumstances --- normally, it just says when a picture is
             being read.
      `Selector menu, Options, Thumbnail Msgs'
             Toggle reading-thumbnails messages (default is off), only visible if the  status
             bar is enabled. These messages make it clear when all thumbnails have been read,
             but having something flash up every time you change directory is generally  just
             annoying.
      `v'
      `Selector menu, Options, Thin Rows'
             Toggle  `thin  rows'  mode  (off by default), in which thumbnails are shown at a
             third their normal size so that many more files can be shown at once.  (The  odd
             keyboard  shortcut  for this is inherited from zgv's `visual' mode toggle, which
             had a roughly similar effect.)

THE VIEWER

      Once you've selected a file to view, it's shown in the viewer (the right-hand  part  of
      xzgv's window). This section describes what you can do while viewing the picture.
      Like  the  selector, the viewer has its own menu --- right-click anywhere on the viewer
      (or press `F10' or `Menu') to show it --- and a similar help  menu  (see  The  Selector
      Menu).

EXITING THE VIEWER

      When  using  the  mouse  to control xzgv, it doesn't matter whether the selector or the
      viewer has keyboard focus --- mouse operations transcend such petty boundaries. :-) But
      keyboard  control  is  (of  necessity) effectively modal, and so you need to `exit' the
      viewer in order to have keyboard control over the selector again. You also need to exit
      the viewer if you've enabled auto-hide mode.
      Exiting the viewer is simple:
      `Esc'
      `Tab'
      `Viewer menu, Exit to Selector'
             Exit  the  viewer.  This also returns the selector to its former size, if it was
             previously `hidden'.
      Another way of exiting the viewer  is  to  middle-click  on  it,  but  this  mouse-only
      approach is really only of use when the selector is `hidden'.

BIG PICTURES

      A  picture  may  well be too large to fit entirely in the viewer window.  There are two
      main things which can help you see more of the picture at once:
      - Make the xzgv window larger. You could `maximize' it with your window manager, or you
      could  start  xzgv  with  a  larger  window  using `--geometry' or fullscreen mode (see
      Options). The fullscreen mode gives xzgv the maximum window size  possible,  but  needs
      co-operation  from  your window manager (and alas, many are not as willing as one might
      like) --- in some cases you may even find `--geometry 100%x100%' to be more effective.
      - Hide the selector. To do this, either use auto-hide mode (see File Selector Options),
      or hide the selector explicitly (see Hiding the Selector).
      But  of  course, these are only partial solutions to the problem; there will inevitably
      always be pictures larger than your screen can show at once. In  general,  then,  there
      are two ways to see the whole of the picture.
  Scrolling
      Scrolling  is the default approach to handling big pictures in xzgv. When the viewer is
      started up, the top-left of the picture is shown --- you can either  drag  the  picture
      around  with  the  mouse  (i.e.  click  and  hold  the button down, then move the mouse
      around), or use the scrollbars, or use the cursor keys (and others) to move around  the
      rest of the picture:
      `Cursor Up'
      `K'
             Move up 100 pixels. `Ctrl-Cursor Up' and `k' both move up 10 pixels.
      `Cursor Down'
      `J'
             Move down 100 pixels. `Ctrl-Cursor Down' and `j' both move down 10 pixels.
      `Cursor Left'
      `H'
             Move left 100 pixels. `Ctrl-Cursor Left' and `h' both move left 10 pixels.
      `Cursor Right'
      `L'
             Move right 100 pixels. `Ctrl-Cursor Right' and `l' both move right 10 pixels.
      `Page Up'
      `Shift-Cursor Up'
      `Ctrl-u'
             Move up (nearly) the window height. (It moves by 90% of the height.)
      `Page Down'
      `Shift-Cursor Down'
      `Ctrl-v'
             Move down (nearly) the window height.
      `-'
      `Shift-Cursor Left'
             Move left (nearly) a window-length. (It moves by 90% of it.)
      `='
      `Shift-Cursor Right'
             Move right (nearly) a window-length.
      `Home'
      `Ctrl-a'
             Move to the top-left of the picture.
      `End'
      `Ctrl-e'
             Move to the bottom-right of the picture.
  Zoom Mode
      An  alternative  way  of  viewing the whole picture, one which lets you see the picture
      onscreen all at once no matter how big (or small) it is, is zoom mode.
      Zoom mode's name derives from the idea of `zooming' a small file up to fit the  window.
      But in reality, it is more often used to reduce a large file to fit.
      Zoom  mode  is  not the default, and has to be enabled. Once enabled, it stays on until
      you turn it off again (or until you enable scaling, or select Normal (see Scaling)).
      `z'
      `Viewer menu, Options, Zoom (fit to window)'
             Toggle zoom mode.
      `Alt-r'
      `Viewer menu, Options, When Zooming Reduce Only'
             When in zoom mode, only reduce pictures to fit. This can be  useful  when  going
             through  a lot of unpredictably-sized pictures, as it means that you can see all
             of a big picture easily without also meaning that tiny  little  icons  assume  a
             scale of Biblical proportions. :-)
      The way zoom mode reduces a file to fit the window is (relatively) quick but harsh, and
      may make the picture look a bit ugly. In future there may be a  smoothing  option  like
      zgv's vkludge, but for now I'm afraid the fairly crude resize is all that's available.
      There  is  in fact an alternative to zoom mode, as you can scale down an image instead.
      This is generally only useful for very large images, however; zoom mode tends to be the
      Right Thing for the most part.

SCALING

      You  can  scale  a  picture --- this makes it appear larger (or smaller) onscreen. xzgv
      acts much as if the scaled picture were the real picture; for example, the cursor  keys
      scroll  around in steps of 100 scaled pixels, even if this means moving a fraction of a
      pixel (or many pixels) in the original picture (and similarly  for  movement  with  the
      mouse).
      The  main limitation of scaling (other than how much it slows things down :-), at least
      when scaling up) is that you can only scale by integer values, so  you  can  only  make
      each pixel in the image twice as wide/high, or three times as wide/high, or four times,
      and so on.
      (It may seem odd saying e.g. `twice as wide/high' rather than  `twice  the  size',  but
      technically `twice the size' would be referring to scaling up the width (and height) by
      about 1.414...)
      Normally, xzgv does no scaling, which could be considered a ratio of 1:1.   Scaling  up
      increases that ratio. How it is increased depends on which option/key you use:
      `d'
      `Viewer menu, Scaling, Double Scaling'
             Increase the ratio by doubling it --- this leads to ratios of 2:1, 4:1, 8:1...
      `s'
      `Viewer menu, Scaling, Add 1 to Scaling'
             Increase the ratio by adding one --- leads to ratios of 2:1, 3:1, 4:1...
      There are similar commands to decrease the ratio:
      `D (Shift-d)'
      `Viewer menu, Scaling, Halve Scaling'
             Decrease the ratio by halving it.
      `S (Shift-s)'
      `Viewer menu, Scaling, Sub 1 from Scaling'
             Decrease the ratio by subtracting one.
      Usually the double/halve scalings are more useful.
      Note that you can also double/halve the scaling by using shift-left-click on the viewer
      to double, and shift-right-click to halve. This still changes scale `around' the middle
      of  the  window  though (rather than around the point clicked on, as you might expect),
      which is a little strange and may possibly be changed in future.
      When you scale `below' 1:1, the above commands lead to ratios of (e.g.)  1:2, 1:4, 1:8,
      etc.  ---  that  is, the ratios work the same way, but the other way around. This gives
      you an increasingly small image.
      The scaling ratio is never decreased below 1:32. It is also never increased beyond  the
      point  where  the  overall image size would exceed 32767x32767 --- this limit is due to
      the combination of X's limit on window sizes, and the implementation used by  xzgv  for
      scaling.
      One problem with scaling up, given the way it's currently implemented, is that it's not
      well-suited to dithered display --- so if you're running on an 8-bit  server,  dragging
      the  image around slowly when using scaling (especially scaling with interpolation) may
      result in some nasty, streaky, undithered-looking parts of the picture. :-(
      You can undo the effect of scaling (up or down) at any time:
      `n'
      `Viewer menu, Scaling, Normal'
             Resume `normal' display --- disables scaling mode, and also zoom mode.
      Normally, scaling up works by simply making the pixels into larger and  larger  squares
      (in  effect),  which  remain  the same colour. However, you can enable a feature called
      `interpolation' which smoothly graduates the colour change between the top-left corners
      of each pixel. This is very slow, but looks nice.
      `i'
      `Viewer menu, Options, Interpolate when Scaling'
             Toggle interpolation in scaling mode.
      (If  you  like the appearance of scaling with interpolation, you may also be interested
      in a program I wrote called pnminterp, which can scale up  a  PGM  or  PPM  file  while
      applying this effect. These days it's part of the netpbm package.)
      Scaling  down,  however,  is  implemented a bit like a special-case zoom mode, and cur‐
      rently 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-spe‐
      cific,  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 cor‐
      recting 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 mir‐
             rors, flips, and/or rotations.
      xzgv normally `reverts' the picture orientation (the way the picture  has  been  trans‐
      formed by mirror/flip/rotate) back to normal when you view a new picture. However, it's
      possible to disable this (see Viewer Options), so that any new pictures  are  mirrored,
      flipped, and/or rotated in the same way.

BRIGHTNESS AND CONTRAST

      [Brightness and contrast changing is not supported in xzgv 0.9.]  xzgv provides support
      for changing brightness and contrast, though given the way it has to redraw  the  image
      to do so, it can be a little slow.
      Currently there is no way to do this with the mouse; this should be fixed soon.
      `,'
             Decrease contrast.
      `.'
             Increase contrast.
      `<'
             Decrease brightness.
      `>'
             Increase brightness.
      `:'
      `;'
             Reset  contrast and brightness to normal. (`*' is also supported, for hysterical
             raisins.) Note that this deliberately does not affect the gamma adjustment.
      Any contrast change is applied before any brightness change, and any  gamma  adjustment
      is applied before both.

GAMMA ADJUSTMENT

      [Gamma  is  not  supported in xzgv 0.9.]  Ah yes, gamma. What fun. The basic problem is
      this --- differing displays have differing intensity response curves. ``This has made a
      lot of people very angry and been widely regarded as a bad move. :-)
      It  means  that  you need some way of adjusting how brightly you display the picture to
      compensate. But since we're dealing with response curves, this isn't just a  matter  of
      changing the brightness in a linear fashion.
      That doesn't seem so hard to deal with, right? All you need is to get the gamma (a num‐
      ber which specifies how much the curve bends) for the image, and for the screen, divide
      one by the other and adjust as appropriate. Joy.
      But,  given  that  the  problem has existed since we started displaying more than eight
      colours, you won't be surprised to find that it's already been fixed. And the fixes all
      tend  to  clash, and everybody has a different notion of how to fix it. The usual `fix'
      is to assume that whoever made the image made it with a gamma  matching  the  gamma  of
      your  display,  so you can just stuff the bits right on the screen. Since this is easy,
      it's the most widespread approach. But it's a bit stupid, so not everyone does it. Com‐
      bine  that  with  the lack of gamma specification in most image formats, and the often-
      bogus values specified by people in those that do, and hey presto --- the  image  gamma
      could be just about anything. And the screen's gamma also tends not to be easily deter‐
      mined.
      So how on earth do you deal with something like that in a remotely sane fashion?
      The answer chosen in xzgv is to just live with the fact that the probability  of  auto‐
      matically  obtaining  correct  values  for both the screen and image gamma is basically
      zero. Once you accept that, the sensible thing to do is to make it very easy  and  fast
      to change gamma adjustment to commonly-required values. So here's how to do it:
      `1'
             Set gamma adjustment to 1.0, i.e. no adjustment. This is the default setting.
      `2'
             Set  gamma adjustment to 2.2. This is useful for viewing linear-gamma files (one
             classic example being raytracer output) on an average PC monitor.
      `3'
             Set gamma adjustment to 1 divided by 2.2, i.e. roughly 0.45. This is useful  for
             the  reverse  ---  viewing average-PC-monitor-gamma files on a linear-gamma dis‐
             play. Historically I believe the classic example  would  have  been  viewing  PC
             files on a Mac, but I don't know how true that is these days.
      `4'
             Set  gamma adjustment to its initial value, as specified by a `--gamma' command-
             line option (see Options) or equivalent config  file  setting  (see  Configuring
             xzgv). The default value used if none was specified is 1.0.
      A brief clarification is probably in order. The gamma adjustment value which you set in
      xzgv is actually inverted from (i.e. one divided by) the true  adjustment  value  used.
      This is (believe it or not :-)) intended to avoid confusion by reflecting the fact that
      screen gamma is the one most widely considered/well known.
      You can also tweak the adjustment more precisely, in a similar way  to  brightness/con‐
      trast:
      `Alt-,'
             Decrease gamma adjustment (divide it by 1.05).
      `Alt-.'
             Increase gamma adjustment (multiply it by 1.05).
      Note  that  `:',  and  the other keys which reset the brightness/contrast, deliberately
      avoid resetting the gamma adjustment.
      As with brightness/contrast, there is currently no way to adjust gamma with the  mouse;
      this should be fixed soon. (But the 1/2/3/4 keyboard-based method is likely to still be
      the faster method.)

CHANGING PICTURE

      It's possible to go directly to the previous or next  file  (or  tagged  file)  in  the
      directory,  or to tag a file, without having to pick the file from the file selector by
      hand. These commands are particularly useful when using xzgv  from  the  keyboard,  but
      there's also a notable mouse shortcut for moving to the next image.
      `Space'
      `Viewer menu, Next Image'
             Move  to next file in dir, and view it. You can also click on the picture/viewer
             to do this. (If you find  this  interferes  with  dragging  the  picture  around
             (though  it  shouldn't),  or  just don't like it, it can be disabled (see Config
             Variables).)
      `b'
      `Viewer menu, Previous Image'
             Move to previous file in dir, and view it.
      `Ctrl-Space'
      `Viewer menu, Tagging, Tag then Next'
             Tag current file, then move to next file in dir and view it.
      `/'
      `Viewer menu, Tagging, Next Tagged'
             Move to next tagged file in dir, and view it.
      `?'
      `Viewer menu, Tagging, Previous Tagged'
             Move to previous tagged file in dir, and view it.

HIDING THE SELECTOR

      When running on small screens, or in a small window, it can get a bit annoying to  lose
      viewer  space  by having the selector constantly displayed when you don't actually need
      it. The usual solution to this problem is to enable auto-hide mode. But  what  if  some
      pictures  you're viewing are small and some large? It can sometimes be nearly as annoy‐
      ing 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 pre‐
      fer 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 con‐
      fig file settings (see Configuring xzgv).
      `z'
      `Viewer menu, Options, Zoom (fit to window)'
             Toggle zoom mode, discussed in more detail elsewhere (see Zoom Mode).
      `Alt-r'
      `Viewer menu, Options, When Zooming Reduce Only'
             Toggle reduce-only in zoom mode, also covered elsewhere (see Zoom Mode).
      `i'
      `Viewer menu, Options, Interpolate when Scaling'
             Toggle  interpolation when a picture is being scaled-up. Again, this has already
             been mentioned (see Scaling).
      `Alt-c'
      `Viewer menu, Options, Ctl+Click Scales X Axis'
             Toggle the axis scaled when you control-click (or  control-right-click)  on  the
             image. The default is to scale the y axis.
      `F (shift-f)'
      `Viewer menu, Options, Dither in 15 & 16-bit'
             Toggle  dithering  in  15/16-bit modes. This increases the apparent colour depth
             making gradations look much better, but it's slower than  undithered  rendering,
             and  can  (in  16-bit) slightly distort a picture's colour balance. (The `F' key
             was chosen for this as the  dither  toggle  is  functionally  similar  to  zgv's
             `fakecols' toggle.)
      `Viewer menu, Options, Revert Scaling For New Pic'
             Normally  xzgv returns the scaling back down to 1 (normal) when a new picture is
             selected. By disabling this, you can retain scaling  across  picture  selection.
             (There  is  currently no keyboard shortcut for this fairly-seldom-changed option
             --- to toggle it from the keyboard, you should use the popup menu (press `F10'),
             and select the menu item.)
      `Viewer menu, Options, Revert Orient. For New Pic'
             Similarly,  xzgv  returns  to  the  picture's  true  orientation  (not mirrored,
             rotated, etc.) on selecting a new picture. Disabling this option means that  any
             mirrors/flips/rotates  applied  persist  across  multiple  images.  (No keyboard
             shortcut --- see above.)
      `Viewer menu, Options, Use Exif Orientation'
             Toggle support for Exif orientation. Devices which create JPEG files in the Exif
             format (e.g. many digital cameras) may add an orientation tag to the file, which
             says how the camera was being held when the picture was taken. When this tag  is
             present,  xzgv can adjust the image to compensate for a camera being held on its
             side. (This isn't done by default as it  misrepresents  the  true  image,  which
             could  be  confusing if you don't know why it's happening.) Enabling this option
             may be useful if you take pictures with your camera on its side, but don't  want
             to  have  to  rotate  the  pictures  before being able to view them properly. Of
             course, for this to work your camera has to be inserting the orientation tag  in
             the  first  place --- but it can't hurt to try it and see. (No keyboard shortcut
             --- see above.)

FILE FORMATS

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

FILE TYPE IDENTIFICATION

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

CONFIGURING XZGV

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

CONFIG FILES

      A configuration file lets you alter aspects of xzgv's behaviour. xzgv supports two pos‐
      sible  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  vari‐
      ables are of this type.
      -  Integer  (currently  unused).  These  are  whole  numbers. The meaning of the number
      depends on what the variable is used for.
      - Real (floating-point). This can be a whole number or a decimal  fraction.   Only  the
      gamma variable is of this type.
      -  Geometry. This window size-and/or-position specification format is only used for the
      `geometry' setting. See Options, for a description of how this type works.

CONFIG VARIABLES

      Currently, most configuration variables (settings) in xzgv can also be set by  command-
      line  options;  indeed,  the name of the setting in all such cases is identical to that
      for the long version of the option (e.g. `fullscreen', `auto-hide'). As  such,  they're
      documented  in  the  section  which  discusses  command-line  options and the like (see
      Options).
      However, there are some settings only available in the config file:
      click-for-next
             This is enabled by default, allowing you to click on the viewer to skip  to  the
             next image. If disabled, clicking on the viewer does nothing.

RATIONALE

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

WHY YET ANOTHER VIEWER?

      Previously, this section concentrated on xv; that may have made sense when I originally
      wrote  it,  and  still makes a certain limited amount of sense for zgv, but for xzgv it
      was looking increasingly dated. And so here I am writing an update. :-)
      I originally wrote xzgv as I simply wasn't happy with the viewers  for  X  that  I  was
      aware  of  at the time (mid-1999). At the time of writing (late 2000), other key things
      about xzgv are becoming apparent, partly through responses I've been getting to it:
      o It's `fast'. No, it doesn't do any particular operation faster than other viewers  as
      far  as  I know (well, maybe thumbnail updates :-)); rather, the interface tries not to
      get in your way. Click on a filename, and the picture appears. No multiplicity of tool‐
      bars 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  prob‐
      lem. :^)
      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-con‐
      ceived 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 ter‐
      minals 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 documenta‐
      tion 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-impossi‐
      ble!) 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 occa‐
      sional  two-space sentence end being inserted into their text --- worse still, the cur‐
      rent `makeinfo' formatting algorithm seems to insert two spaces  even  after  abbrevia‐
      tions  (such  as `e.g.' and `etc.'), which breaks even two-space texinfo. (This is par‐
      ticularly 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 abbrevia‐
      tions 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 han‐
      dle.
      - It doesn't apply any tranparency mask. The practical result of this seems to be  pur‐
      ple  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 any‐
      thing 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  your‐
      self,  patches  are  gratefully accepted. :-) You should generate the patch using `diff
      -c' or (preferably) `diff -u'.
      So,  if  you  think  you've  found  a  bug  in  xzgv,  report  it  by  emailing  me  at
      <rrt@sc3d.org>.

REPORTING DOCUMENTATION BUGS

      Bugs  in  the documentation can sometimes cause as much trouble as bugs in the program;
      if you notice a problem in the documentation, it's a good idea to report it.
      For reports of documentation bugs, you should include these details:
      o The version of xzgv the documentation is for.
      o If it is a problem in one specific section of the documentation, specify  which  part
      it  is  (by  this  I mean the heading it comes under; texinfophiles should read this as
      `the node name' :-)).
      o The format of the documentation you saw the problem in (e.g. info, man page, HTML).
      o A description of the problem.

FUTURE CHANGES

      See Reporting Bugs, for details of where to send the bug report.  If you want  to  sug‐
      gest  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)

Version 0.9 9th September 2007 XZGV(1)

Personal tools
Strangers In Paradise