packages icon

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

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

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

      (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. (Details of file formats supported
      are given elsewhere. See Supported File Formats.)

      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' or `Space'. 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.

      xzgv was primarily written by Russell Marks, also the author of this

                                    - 1 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001


      Costa Sapuntzakis contributed code for much faster JPEG thumbnail
      generation (to zgv, which I adapted for xzgv).

      `install-info' is a (very) slightly modified version of the original
      (which is part of the `texinfo' package). This program is used during
      installation. I think it was mostly written by Karl Berry, but it's
      not terribly clear.

      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. Thanks also to the
      Rasterman (Carsten Haiztler) for Imlib, without which xzgv would most
      likely have been a complete pain to write. (But no thanks for Electric
      Eyes, which was nearly nice enough for me not to bother with xzgv at
      all! :-))

      This program is based in part on the work of the Independent JPEG
      Group. (I don't think I actually need this line any more, but I like
      giving these guys a credit, it's a neat library. :-))

      xzgv uses (or rather it does if `INTERP_MMX' was defined when
      compiling, and if it's running on an MMX-capable CPU) MMX instructions
      for interpolation, with the help of libmmx, by Hank Dietz and Randy

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

      ``The Graphics Interchange Format(c) is the Copyright property of
      CompuServe Incorporated. GIF(sm) is a Service Mark property of
      CompuServe Incorporated.''

      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:

                                    - 2 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      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:

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

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

           (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

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

           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.

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

                                    - 3 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      `-G val'
      `--gamma val'
           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

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

           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

                                    - 4 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

           2000000 pixels.

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

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

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

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

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

           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 on the status bar when thumbnails are being read. The status
           bar must be enabled for these messages to be visible, of course.

           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.

                                    - 5 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

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

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

           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.

           Show version number.

           Show version number of GTK+ xzgv is using.

           Fit picture to viewer window, whatever its actual size (see Zoom

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

      If started with `xzgv files', xzgv hides the file selector and treats
      the file or files as if they were the sole contents of a directory.
      (It also automatically loads the first file.) As such, you can use the
      Next Image and Previous Image commands to navigate between the images,
      or do Exit to Selector and use the selector directly. (By the way,
      running like this also makes it possible to view files without the
      usual extensions such as .gif, etc. See File Type Identification.)

      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

                                    - 6 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      disable it. The most useful thing about this is that it allows you to
      disable options which were previously enabled, by using e.g. `--

      (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

      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:

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

      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.

      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.

                                    - 7 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

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

      `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

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

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

      (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

      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

                                    - 8 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      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

      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!

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

      `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

                                    - 9 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

           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 Imlib reports as the closest match to each individual colour
      used in thumbnails. This gives a tolerable result on 8-bit servers,
      assuming Imlib 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 Imlib 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

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

                                   - 10 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      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.

           Move the window split left more slowly.

           Move the window split right.

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

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

                                   - 11 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

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

      `Cursor Down'
           Move down.

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

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

           Move the cursor to the start of the list.

           Move the cursor to the end of the list.

           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.

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


                                   - 12 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

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

      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'
           Move the cursor left. (A vertical bar shows the cursor position.)

      `Cursor Right'
           Move the cursor right.

           Move the cursor to the start of the line.

           Move the cursor to the end of the line.

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


                                   - 13 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

           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:

           Cut text.

           Copy text.

           Paste text.

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

      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.

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

      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

                                   - 14 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

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

      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 +'
      `Selector menu, Tagging, Tag'
           Tag file.

      `Keypad -'

                                   - 15 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      `Selector menu, Tagging, Untag'
           Untag file.

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

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

      `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

    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.

                                   - 16 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

           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.

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

      `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 is pretty straightforward:

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

      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' or `Space'). 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'.)


                                   - 17 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      `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

      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:

      `Selector menu, Directory, Rescan'
           Rescan the current directory.

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

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

      `Selector menu, Directory, Sort by Extension'
           Sort by extension.

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

      `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:

      `Selector menu, Directory, Time & Date Type, Modification Time

                                   - 18 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

           Use the last-modified time (`mtime'). This is the default.

      `Selector menu, Directory, Time & Date Type, Attribute Change Time
           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.

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

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

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

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

      `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

                                   - 19 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

           from zgv's `visual' mode toggle, which had a roughly similar

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

      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:

      `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

      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

                                   - 20 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      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

      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'
           Move up 100 pixels. `Ctrl-Cursor Up' and `k' both move up 10

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

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

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

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

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

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


                                   - 21 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

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

           Move to the top-left of the picture.

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

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

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

      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

                                   - 22 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      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:

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

      `Viewer menu, Scaling, Add 1 to Scaling'
           Increase the ratio by adding one --- leads to ratios of 2:1, 3: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.

                                   - 23 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      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:

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

      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.

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


                                   - 24 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

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

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

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

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

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

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

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

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


                                   - 25 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

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

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

      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

      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.

                                   - 26 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      Any contrast change is applied before any brightness change, and any
      gamma adjustment is applied before both.

      Ah yes, gamma. What fun. The basic problem is this --- differing
      displays have differing intensity response curves. ``This has made a
      lot of people very angry and been widely regarded as a bad move.'' :-)

      It means that you need some way of adjusting how brightly you display
      the picture to compensate. But since we're dealing with response
      curves, this isn't just a matter of changing the brightness in a
      linear fashion.

      That doesn't seem so hard to deal with, right? All you need is to get
      the gamma (a number which specifies how much the curve bends) for the
      image, and for the screen, divide one by the other and adjust as
      appropriate. Joy.

      But, given that the problem has existed since we started displaying
      more than eight colours, you won't be surprised to find that it's
      already been fixed. And the fixes all tend to clash, and everybody has
      a different notion of how to fix it. The usual `fix' is to assume that
      whoever made the image made it with a gamma matching the gamma of your
      display, so you can just stuff the bits right on the screen. Since
      this is easy, it's the most widespread approach. But it's a bit
      stupid, so not everyone does it. Combine that with the lack of gamma
      specification in most image formats, and the often-bogus values
      specified by people in those that do, and hey presto --- the image
      gamma could be just about anything. And the screen's gamma also tends
      not to be easily determined.

      So how on earth do you deal with something like that in a remotely
      sane fashion?

      The answer chosen in xzgv is to just live with the fact that the
      probability of automatically obtaining correct values for both the
      screen and image gamma is basically zero. Once you accept that, the
      sensible thing to do is to make it very easy and fast to change gamma
      adjustment to commonly-required values. So here's how to do it:

           Set gamma adjustment to 1.0, i.e. no adjustment. This is the
           default setting.

           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.

                                   - 27 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

           Set gamma adjustment to 1 divided by 2.2, i.e. roughly 0.45. This
           is useful for the reverse --- viewing average-PC-monitor-gamma
           files on a linear-gamma display. Historically I believe the
           classic example would have been viewing PC files on a Mac, but I
           don't know how true that is these days.

           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

           Decrease gamma adjustment (divide it by 1.05).

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

      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.

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

                                   - 28 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

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

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

      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

      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:

      `Viewer menu, Window, Minimize'
           Minimize the xzgv window.

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

                                   - 29 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

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

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

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

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

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

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

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

                                   - 30 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      The format a file is in is identified in two different ways. The file
      selector picks filenames to display based on the `extension' --- for
      instance, if a filename ends in .jpg or .jpeg, xzgv assumes it is a
      JPEG. This way of working is not always right, but it's much faster
      than the alternative (reading part of every single file) and is
      usually sufficient.

      The file-reading code relies on Imlib 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 format supported by Imlib (such as JPEG), the format will be
      figured out and the file loaded even though the `extension' is absent.

      One extension to this is xzgv's built-in support for my relatively
      obscure `mrf' format. :-) Since there's probably not much interest in
      supporting this in Imlib, and it's really quite a simple format, it's
      not unreasonable for xzgv to support this directly. But xzgv acts as
      if Imlib supported mrf, so this distinction can be largely ignored.

      In fact, xzgv is gradually moving towards reading several of the more
      popular formats natively, as part of an attempt to avoid being tied to
      a single image rendering/loading backend; at the time of writing, GIF,
      JPEG, PNG, and TIFF are also read in this way.

      xzgv supports the following file formats:

      o GIF.

      o JPEG.

      o PNG.

      o PBM/PGM/PPM, collectively known as `PNM'. This is a nice simple
      format used by pbmplus and netpbm.

      o BMP.

      o TGA (Targa).

      o PCX.

      o mrf. Mrf files can be converted to/from PBM with mrftopbm/pbmtomrf,
      and the format is documented in the mrf(5) man page.

      o PRF. PRF is an extension of mrf, similarly converted with
      prftopnm/pnmtoprf, and documented in the prf(5) man page.

                                   - 31 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      o XBM (X bitmap files).

      o XPM.

      o TIFF.

      o TIM. This is an image format used (on the Sony PlayStation) by some
      games (e.g. Wipeout) for storing 2D images.

      o XWD (X window dumps, as produced by xwd).

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

      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.

      There are various types of variable:

                                   - 32 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

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

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

      - Real (floating-point). This can be a whole number or a decimal
      fraction.  Only the gamma variable is of this type.

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

      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

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

           If enabled, this causes the logo to appear with its colours
           inverted.  This tends to look better with dark GTK+ themes. (I
           may eventually add an option to remove the logo entirely to avoid
           problems of this nature, but for now this is a nice-looking
           kludge. :-))

           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.

      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.

      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:

                                   - 33 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      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

      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.

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

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


                                   - 34 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      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.

      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

                                   - 35 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      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

      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.

      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.

      - 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 imlib is 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

                                   - 36 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      `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 returned by imlib. 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''. :-)

      - Thumbnails are given an accurate width/height `IMGINFO' comment, but
      are always claimed to be "RGB", as Imlib doesn't provide any way to
      find out what type they are.

      - xzgv should have an option to treat all files as images, since it
      currently applies a zgv-like file extension filter. This is a bit
      inflexible, given that Imlib supports `all' formats.

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

      - GIF89a extension blocks are ignored.

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

      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.

                                   - 37 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      o The versions of GTK+ and Imlib you are using. `xzgv --version-gtk'
      reports the GTK+ version being used by xzgv, but Imlib is a little
      more tricky --- `imlib-config --version' should work if you have a
      full Imlib installation, but failing that, try `ls -l
      /usr/lib/libImlib*' or `ls -l /usr/X11R6/lib/libImlib*'.

      o The bitdepth your X server is running in (common depths are 8-bit
      (256 colours), 15-bit, 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 in
      Imlib? Even `irrelevant' details can sometimes be useful.

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

      So, if you think you've found a bug in xzgv, report it by emailing me
      at <>.

      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.

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

      xzgv is rather a moving target at the moment, so for now future
      changes etc. are only listed in the TODO file. Normal service will be
      resumed once things settle down a bit. :-)

                                   - 38 -           Formatted:  June 4, 2020

 XZGV(1)                         Version 0.7                         XZGV(1)
 Graphics Software                                         Graphics Software

                               9th April 2001

      Russell Marks <> and others; see the section
      ACKNOWLEDGEMENTS for details.

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

                                   - 39 -           Formatted:  June 4, 2020