Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  pic-
       tures  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 ap-
       pears  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  di-
       rectory,	 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 drag-
       ging 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	intro-
       ductions	to what	xzgv can do, and describes only	a very	basic  use  of
       xzgv. xzgv can do a lot more; read on to	find out what.

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

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

       The  directory/file  icons  used	 were  loosely	based  on  gmc's  dir-
       close.xpm. I think Tuomas Kuosmanen was responsible for	that,  judging
       from the	change log.

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

       Huge thanks go to the many people responsible for GTK+,	without	 which
       xzgv would almost certainly not have happened. (But no thanks for Elec-
       tric 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 man-
       ager 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  sec-
       tion 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-let-
       ter options, and	GNU-style long options.	Most options can  be  used  in
       either way, and both forms are listed in	the table below.

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

       Here's what the options do:

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

       `--careful-jpeg'
	      Enable  libjpeg  `fancy  upsampling'. xzgv defaults to using the
	      faster method; as	the libjpeg documentation puts it, ``The  vis-
	      ual 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. digi-
	      tal  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 di-
	      rectories	for which few if any updates are needed.

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

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

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

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

	      Finally,	as mentioned above, xzgv extends this syntax by	allow-
	      ing 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  im-
	      ages)  but are instead rendered piece-by-piece. Units are	number
	      of pixels	in image (i.e. width times height), and	the default is
	      2000000 pixels.

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

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

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

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

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

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

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

       `--show-thumbnail-messages'
	      Show on the status bar when thumbnails are being read. The  sta-
	      tus  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 par-
	      ent  dir). This can be useful when you'd like to immediately use
	      space to `page' through the dir.

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

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

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

       `-t'
       `--thin-rows'
	      Use  rows	a third	the normal height in the selector. This	can be
	      very useful on lower-resolution screens, or if you're really in-
	      terested 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 in-
	      tact.

       `-p'
       `--zoom-panorama'
	      When in zoom mode, adjust	only the most  proportional  dimension
	      to  fit, and allow scrolling on the other	dimension; i.e.	like a
	      fit page width option in PDF readers, but	not limited  to	 hori-
	      zontal adjusting.

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

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

       Settings	which are either on or off (boolean) are, as you might expect,
       enabled by using	e.g. `-z' or `--zoom'. However,	there's	an alternative
       long-option  form for setting these, resembling how they're set in con-
       fig  files  ---	the  syntax  is	 `--option=state',  where   state   is
       `on'/`y'/`yes'/`1'  to enable the option, or `off'/`n'/`no'/`0' to dis-
       able it.	The most useful	thing about this is that it allows you to dis-
       able 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 com-
       mands 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  key-
       board focus.

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

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

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

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

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

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

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

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

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

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

EXITING	XZGV
       You can exit xzgv either	by using one of	two exit keypresses, or	by se-
       lecting the appropriate option from the selector's popup	menu:

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

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

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

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

       If  no thumbnail	exists for a file, a small `document' icon appears in-
       stead (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 ad-
       vance, 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	thumb-
       nails, 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	direc-
       tory and	all subdirectories by using `Alt-u' or Recursive  Update.  But
       be warned that a	recursive update can take some time!

       `u'
       `Selector menu, Update Thumbnails'
	      Create  thumbnails  for any files	which don't have them, and up-
	      date 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	thumb-
	      nail it is currently working on (if any).

       `Alt-u'
       `Selector menu, Recursive Update'
	      Create/update thumbnails for all files in	the current  directory
	      and  all	subdirectories.	 This  can  take some time, so you are
	      prompted to confirm you really  want  to	do  this  (see	Dialog
	      Boxes). Progress is indicated in much the	same way as for	a nor-
	      mal 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  ti-
	      tle. 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	effec-
       tively 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  in-
       evitably	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	Invok-
       ing 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 or-
       der 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 key-
       board).

       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 Se-
       lector 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 but-
       ton between the selector	and viewer, near the bottom  of	 the  window),
       which  changes  the  relative sizes of the selector and viewer. You can
       move it by dragging it with the mouse, or with these keys:

       `['
	      Move the window split left.

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

       `]'
	      Move the window split right.

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

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

       You can also set	the initial/default size of the	selector  ---  in  ef-
       fect,  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+ jar-
       gon, the	`focus row') is	normally shown as a hollow box around  one  of
       the list's rows.	This serves the	following functions:

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

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

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

       `Cursor Up'
       `k'
	      Move up.

       `Cursor Down'
       `j'
	      Move down.

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

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

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

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

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

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

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

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

DIALOG BOXES
       See The Viewer, for details of how the viewer works.  If	xzgv has a se-
       rious 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 rele-
       vant button with	the mouse to do	the same.)

       - Showing progress when updating	a thumbnail. This is  a	 slightly  un-
       usual  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	 posi-
	      tion.)

       `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  la-
	      belled 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  subwin-
	      dow.

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  im-
       age,  that kind of thing. So, you can show details of a single file us-
       ing 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 de-
	      tails 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)' sys-
       tem call), and should always be available unless	you have limited  per-
       missions	 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  particu-
       lar  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 com-
       mands 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 pre-
	      viously  tagged  files  become  untagged,	and all	previously un-
	      tagged 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 Pic-
       ture).

   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 Dia-
	      log 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  re-
	      main  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  ac-
	      companying  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 cur-
       rently no way to	delete all tagged files.

CHANGING DIRECTORY
       The easiest way to change the current directory in xzgv is  usually  to
       click  on  a directory entry in the file	list (or move the cursor to it
       and press `Enter'). Selecting the `..' entry moves to the parent	direc-
       tory 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 di-
	      rectory using a dialog box which you should type the dir's  name
	      into  (see  Dialog Boxes), and moves to that directory if	it ex-
	      ists.

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,  how-
       ever,  explicitly  tell xzgv to `rescan'	the directory (reread the con-
       tents), which will update xzgv's	notion of what's in it:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       `Selector menu, Options,	Thumbnail Msgs'
	      Toggle  reading-thumbnails messages (default is off), only visi-
	      ble 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 in-
	      herited  from  zgv's  `visual'  mode toggle, which had a roughly
	      similar effect.)

       `Alt-i'
       `Selector menu, Directory, Images Only'
	      Toggle the option	to show	only directories and  image  files  in
	      the  selector  (off  by  default).  This is handy	in directories
	      where images and other file types	are intermingled and you  want
	      to avoid the by their extensions.

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

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

EXITING	THE VIEWER
       When using the mouse to control xzgv, it	doesn't	matter whether the se-
       lector or the viewer has	keyboard focus --- mouse operations  transcend
       such  petty  boundaries.	:-) But	keyboard control is (of	necessity) ef-
       fectively 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	 `hid-
       den'.

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  `--geome-
       try'  or	 fullscreen mode (see Options).	The fullscreen mode gives xzgv
       the maximum window size possible, but needs co-operation	from your win-
       dow  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  ef-
       fective.

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

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

   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 scroll-
       bars, 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 use-
	      ful when going through a lot of unpredictably-sized pictures, as
	      it means that you	can see	all of a big  picture  easily  without
	      also  meaning  that tiny little icons assume a scale of Biblical
	      proportions. :-)

       `Alt-p'
       `Viewer menu, Options, When Zooming Panorama'
	      When in zoom mode, resize	to make	the most  proportional	dimen-
	      sion fit and allow scrolling on the other	dimension. This	can be
	      useful when viewing iamges that do not adjust nicely to the win-
	      dow size but you want to see them	as big as possible while using
	      the most space available.	The cause for  this  function  was  to
	      better read comics, so you can guess it works like a

       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 pic-
       ture; 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 pix-
       els) 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 inte-
       ger  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 scal-
       ing 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 lit-
       tle 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  in-
       creased	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  run-
       ning  on	 an  8-bit server, dragging the	image around slowly when using
       scaling (especially scaling with	 interpolation)	 may  result  in  some
       nasty, streaky, undithered-looking parts	of the picture.	:-(

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

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

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

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

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

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

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

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

       `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;  con-
       trol-left-click	scales up, and control-right-click scales down.	By de-
       fault 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  ef-
	      fect 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  ro-
       tated in	the same way.

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

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

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

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

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

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

HIDING THE SELECTOR
       When running on small screens, or in a small window, it can get	a  bit
       annoying	 to  lose  viewer space	by having the selector constantly dis-
       played 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 prefer to leave auto-hide off and explic-
       itly 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 prob-
       lematic.	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 re-
       late to the viewer.

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

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

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

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

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

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

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

       `Viewer menu, Options, Revert Scaling For New Pic'
	      Normally xzgv returns the	scaling	back down to 1 (normal)	when a
	      new picture is selected. By disabling this, you can retain scal-
	      ing  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  pic-
	      tures  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 for-
       mats'. 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 cor-
       rectly; 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 for-
       mat  (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  configu-
       ration file.

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

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

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

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

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

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

CONFIG VARIABLE	TYPES
       There are various types of variable:

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

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

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

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

       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	 file-
       name,  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 view-
       ers which you may like to try if	you don't think	much of	xzgv:

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

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

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

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

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

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

WHY NO IMAGE-EDITING CAPABILITIES?
       It's a fscking viewer, dammit. If you want xv you know  where  to  find
       it.

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

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

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

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

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

       The  Texinfo  documentation gives the impression	that two-space must be
       used; it	says ``it is important to put two spaces at the	 end  of  sen-
       tences in Texinfo documents.'' But the only circumstance	in which spac-
       ing 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 for-
       mat. So,	in fact, the decision to use two-space depends on how the  au-
       thor  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 ob-
       jective 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 (sen-
       tence-end-double-space; see Fill	Commands in the	emacs info  file)  and
       GNU  fmt	(-u; see fmt invocation	in the textutils info file). Also, at-
       tempting	to `fix' the output Info with sed doesn't  work	 properly  be-
       cause  the  `tags' used to find nodes quickly are then incorrect. These
       could of	course also be fixed, but this would involve a lot  more  work
       than a simple sed invocation.

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

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

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

       - clearly hasn't	written	too many programs.

       - is wrong. ;-)

       It follows that xzgv, like everything else, always has some bugs.  Usu-
       ally 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  hid-
       ing/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  pic-
       ture  if	 you drag the picture around slowly (since each	exposed	bit is
       dithered	independently, with no regard given to matching	up to any pre-
       vious error-diffusion).

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

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

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

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

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

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

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

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

       - xzgv doesn't duplicate	zgv's behaviour	of generating thumbnails under
       ~/.xvpics/_foo_bar_baz	  if	 it    can't	generate    them    in
       /foo/bar/baz/.xvpics. I doubt anything else supported it, and  it  com-
       plicated	lots of	things unnecessarily. This isn't particularly subopti-
       mal, 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  al-
       ready 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 `irrele-
       vant' 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 gen-
       erate the patch using `diff -c' or (preferably) `diff -u'.

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

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

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

       o The version of	xzgv the documentation is for.

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

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

       o A description of the problem.

FUTURE CHANGES
       See Reporting Bugs, for details of where	to send	the  bug  report.   If
       you want	to suggest a feature you'd like	in xzgv, or a change to	an ex-
       isting 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  ACKNOWL-
       EDGEMENTS for details.

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

Version	0.9			9th August 2017			       XZGV(1)

NAME | SYNOPSIS | DESCRIPTION | ACKNOWLEDGEMENTS | OPTIONS | A NOTE ON NOTATION | THE FILE SELECTOR | THE SELECTOR MENU | EXITING XZGV | THUMBNAILS | SELECTOR LAYOUT AND RESIZING | MOVING AROUND THE LIST | VIEWING A FILE | DIALOG BOXES | CLOSING A FILE | FILE DETAILS | TAGGING | RENAMING A FILE | DELETING A FILE | CHANGING DIRECTORY | RESCANNING THE DIRECTORY | CHANGING THE SORTING ORDER | FILE SELECTOR OPTIONS | THE VIEWER | EXITING THE VIEWER | BIG PICTURES | SCALING | MIRROR AND ROTATE | CHANGING PICTURE | HIDING THE SELECTOR | MINIMIZING XZGV | VIEWER OPTIONS | FILE FORMATS | FILE TYPE IDENTIFICATION | CONFIGURING XZGV | CONFIG FILES | CONFIG VARIABLE TYPES | CONFIG VARIABLES | RATIONALE | WHY YET ANOTHER VIEWER? | WHY NO IMAGE-EDITING CAPABILITIES? | WHY A TEXINFO MANUAL? | WHY ONE-SPACE SENTENCE ENDS? | BUGS AND RESTRICTIONS | KNOWN BUGS | SUBOPTIMAL FEATURES | RESTRICTIONS | REPORTING BUGS | REPORTING DOCUMENTATION BUGS | FUTURE CHANGES | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=xzgv&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help