XZGV(1)

📦
version 0.9.2 · 2 versions
  • 0.9.2 · debian bookworm, debian trixie, fedora 43, fedora 44, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
  • 0.9.2 · nixos 26.05
, in debian bookworm, debian trixie, fedora 43, fedora 44, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

okay bestie, sit DOWN, because you're about to read the xzgv(1) manual page 💖 (it lives in the Graphics Software section of the manual, iykyk) and honestly? she's giving main character energy fr fr.

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

not me reading this and going "yeah, they warned us" 😭 anyway—

xzgv is a picture viewer for X, with a thumbnail-based file selector. The thumbnails it uses (and bestie, a thumbnail is just a tiny preview version of a picture, no biggie) are compatible with xv, zgv, and the Gimp. The kinds of pictures xzgv lets you view are raster-format pictures (sometimes called bitmaps and/or pixmaps); think GIF files, JPEG files, PNG files, and so on. 💅

Most of the time you're probably gonna wanna use xzgv's file selector (peep The File Selector) to pick which file(s) to view. That's the thing on the left-hand side of the window when you start xzgv as just xzgv (see Options). It shows you a list of subdirectories and picture files in the current directory, plus small thumbnail versions of the pictures if those exist. 🦋 (If no thumbnails show up in a given directory, or if they're missing for some files, you can create/update them by pressing u. See Updating Thumbnails.)

Once you've picked a file to view, you view it by clicking on it, or pressing Enter. That reads the picture and displays it in the right-hand part of the window, the viewer (see The Viewer). 👑 Then you can move around the picture (if it's bigger than will fit) by dragging it with the mouse, or using the scrollbars, or the cursor keys. After that you can select another image with the file selector (though you need to press Esc or Tab first if you're using the keyboard), or you can quit xzgv by pressing q. 🫶

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

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

💖 ACKNOWLEDGEMENTS 💖

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

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

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

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

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

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

✨ OPTIONS ✨

Okay bestie, so normally you'd invoke xzgv as plain xzgv — maybe from a window manager menu, or a GNOME/KDE menu, whatever 💅 But you can directly specify files to view, or a start directory, right on the command-line. And on top of that there's a whole pile of options.

(If you're new to xzgv, honestly? Skip the rest of this section for now and come back to it later 🫶)

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

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

Two types of options are supported — the traditional Unix single-letter options, and GNU-style long options. Most options can be used 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 the selector when a picture is selected, letting the viewer use the whole window. giving main character energy fr 🌈
  • --careful-jpeg — Enable libjpeg fancy upsampling. xzgv defaults to the faster method; as the libjpeg documentation puts it, "The visual impact of the sloppier method is often very small."
  • --delete-single-prompt — (Note that this is normally enabled; use --delete-single-prompt=off to disable it.) If disabled, xzgv will immediately delete a file when told to, without prompting for confirmation. (It's single because deleting multiple files at once will be supported in future, and that will have a separate prompt override.)
  • --dither-hicol — Use dithering in 15/16-bit, whatever the default setting is. See Viewer Options for a discussion of the benefits/drawbacks. You can also use --dither-hicol=off to disable this.
  • --exif-orient — In JPEG files, use Exif orientation tags (inserted by e.g. digital cameras) to correct image orientation before display. See Viewer Options for details.
  • --fast-recursive-update — When doing a recursive thumbnail update, don't read existing thumbnails before updating. This is pretty much obsolete as of xzgv 0.7, as the speed increase is now negligible. But it may still be useful if you want to update a huge number of small directories for which few if any updates are needed.
  • -f, --fullscreen — Run fullscreen, using the entire screen for xzgv's window, without even any window-manager decorations (window frame, title bar, etc.) if possible. iconic ✨
  • -g geom, --geometry geom — Set the xzgv window's geometry (position and/or size) to geom. The geometry string should be in the usual X format, with the extension that positions/sizes may have a % suffix meaning that they are treated as percentages of the screen width/height. The default geometry is 92%x85%.

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

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

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

  • -h, --help — Display a list of options and a terse description of what the options do.
  • --image-bigness-threshold numpix — Set the boundary numpix after which images are considered big, and are no longer rendered all-at-once (which gives much nicer scrolling, but is harder on memory and can be slow for big images) but are instead rendered piece-by-piece. Units are number of pixels in image (i.e. width times height), and the default is 2000000 pixels.
  • -i, --images-only — Shows only directories and image file types in the selector, identified by their extensions.
  • --interpolate — Interpolate between the picture's pixels when scaling up (see Scaling). This usually looks nicer, but it's rather slow. 😭
  • --mouse-scale-x — If enabled, control-clicking on the viewer scales only the X axis. (The default is to scale only the Y axis.)
  • --revert-orient — (Note that this is normally enabled; use --revert-orient=off to disable it.) If disabled, orientation (flip/mirror/rotate) state is retained between pictures (see Viewer Options).
  • --revert-scale — (Note that this is normally enabled; use --revert-scale=off to disable it.) If disabled, scaling is retained between pictures (see Viewer Options).
  • --selector-width — Set the default/initial size of the selector in pixels. The normal setting is 200.
  • -T, --show-tagged — Show names of currently-tagged files on exiting xzgv. (They're listed to stdout, one per line.) This can be useful when you want to select multiple files graphically and work on them with something else.
  • --show-thumbnail-messages — Show on the status bar when thumbnails are being read. The status bar must be enabled for these messages to be visible, of course. :-)
  • -k, --skip-parent — For the first directory shown, skip the cursor past .. (the parent dir). This can be useful when you'd like to immediately use space to page through the dir.
  • -o order, --sort-order order — Set the initial sorting order used in the selector. Possible settings are name, ext, size, and date (or time); only the first char of the setting (n/e/s/d/t) need be given. The default is name order.
  • --sort-timestamp-type type — Set the timestamp type to use when using time/date sorting order. Possible settings are mtime (default), ctime, and atime; only the first char of the setting (m/c/a) need be given.
  • --statusbar — Show a status bar below the selector; this, for example, says when a picture is being read.
  • -t, --thin-rows — Use rows a third the normal height in the selector. This can be very useful on lower-resolution screens, or if you're really interested in filenames, not thumbnails.
  • -v, --version — Show version number.
  • --version-gtk — Show version number of GTK+ xzgv is using.
  • -z, --zoom — Fit picture to viewer window, whatever its actual size (see Zoom Mode).
  • -r, --zoom-reduce-only — When in zoom mode, only reduce pictures to fit; i.e. make big pictures viewable all-at-once while leaving small picures intact.
  • -p, --zoom-panorama — When in zoom mode, adjust only the most proportional dimension to fit, and allow scrolling on the other dimension; i.e. like a fit page width option in PDF readers, but not limited to horizontal adjusting.

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

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

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

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

🌸 A NOTE ON NOTATION 🌸

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

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

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

👑 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 ✨

okay so literally almost every single selector command lives in the selector's pop-up menu, which pops up when you right-click anywhere on the selector. (you can also hit F10 or Menu to summon it, but ngl since xzgv has keyboard shortcuts for basically everything, that's not super useful most of the time. :-))

usually it doesn't matter where on the selector you right-click. BUT — a few commands on the File menu act on a single file, the one picked out by the keyboard cursor. sounds like a mouse-user nightmare, right? but bestie, here's the slay: when you right-click on the selector, as well as popping up the menu, xzgv moves that cursor to the file you right-clicked on (if there was one). you can see it happening because a hollow box gets drawn around the file. so to use e.g. Details on the File menu, you gotta right-click on the file you want the details on. periodt. 💅

both the selector and viewer have Help menus, and most of their items just point you at this very 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 — gives you some brief info about xzgv, including the version number and homepage. 👑

ngl the way xzgv lets you read the manual rn is a bit crude — it runs the info program (see Top in the info-stnd info file) inside an xterm. 😭

🚪 EXITING XZGV 🚪

you can dip out of xzgv either with one of two exit keypresses, or by picking the right option from the selector's popup menu:

  • q, Ctrl-q, Selector menu, Exit xzgv — quit xzgv. bye bestie 🫶

(also there's an exit option on the selector's File menu — Selector menu, File, Exit — because Exit is basically on every File menu, iykyk.)

🖼️ THUMBNAILS 🖼️

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

thumbnails are lil baby versions of the pictures they represent, and the file selector shows them if they exist. xzgv uses xv-compatible thumbnails — so if you made thumbnails with xv they'll work with xzgv, and vice versa. xzgv's thumbnails are also compatible with the Gimp and with zgv. ✨

if there's no thumbnail for a file, a small document icon shows up instead (similar to the folder icon used for directories). 📄

🔄 Updating Thumbnails 🔄

so while thumbnails can be made relatively quickly, it is by no means an instant process, bestie. that's why thumbnails have to be created in advance, and get stored as files in their own right in a subdirectory called .xvpics.

xzgv never creates/updates thumbnails without you telling it to. so if you wander into a directory where the picture files have no thumbnails, or where the thumbnails look out of date, you should press u, or pick 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. cute, right?)

alternatively, you can create/update thumbnails for the current directory and all subdirectories 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 that don't have them, and update thumbnails that 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 the Cancel button, or pressing Esc or Enter, or by clicking the delete-window button (if your window manager provides one) on the title bar. xzgv will stop once it has finished the thumbnail it is currently working on (if any).

  • Alt-u, Selector menu, Recursive Update — create/update thumbnails for all files in the current directory and all subdirectories. this can take some time, so you get prompted to confirm you really wanna do this (see Dialog Boxes). progress is shown 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 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 the deets. 👀

💀 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 kicks off 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 because, even if you're running an 8-bit (256 colour) server, there will almost inevitably be fewer colours available. currently, xzgv just uses whatever gdk reports as the closest match to each individual colour used in thumbnails. this gives a tolerable result on 8-bit servers, assuming gdk was able to allocate a large number of colours; however, it gives terrible results if it couldn't, or if running on 4-bit or 1-bit servers. sorry about this 😭 — it should be fixed in future (either by using gdk to draw the thumbnail pixmaps, or by dithering them by hand to suit the colours available).
  • finally, when doing a recursive thumbnail update, xzgv (by default) reads existing thumbnails in a directory before updating any. or rather, it reads thumbnails for those files currently visible in the selector. this can slow things down very slightly, but keeps the look and feel consistent with the normal update. (still, you can disable this with the --fast-recursive-update command-line option (see Invoking xzgv) or equivalent config file entry (see Configuring xzgv).)

📐 SELECTOR LAYOUT AND RESIZING 📐

the file selector is simply a list of subdirectories and filenames, along with any thumbnails that exist for them. the list is normally in asciibetical order (but you can change this; see Changing the Sorting Order). names of directories are shown first, 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'll 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 too).

the list is very often bigger than what fits on the screen at once. if that's 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 too small vertically and wanna see more files at once, you can start xzgv fullscreen by using the -f option (see Options), and/or use thin rows mode (see File Selector Options). 💅

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

  • [ — move the window split left.
  • Ctrl-[ — move the window split left more slowly.
  • ] — move the window split right.
  • Ctrl-] — move the window split right more slowly.
  • ~ — reset the window split to its default position.

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

🎯 MOVING AROUND THE LIST 🎯

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

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

  • it selects a file for view commands to operate on. 👑
  • it determines which part of the list is shown, because the part of the list shown onscreen always contains the cursor (unless you move around using the mouse).

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

  • Cursor Up, k — move up.
  • Cursor Down, j — move down.
  • Page Up, Ctrl-u — move the cursor back roughly a page.
  • Page Down, Ctrl-v — move the cursor forward roughly a page.
  • Ctrl-Home, Ctrl-a — move the cursor to the start of the list.
  • Ctrl-End, Ctrl-e — move the cursor to the end of the list.
  • g, ' — move the cursor to the first filename starting with the next key pressed, which would generally be a letter or number. case is significant; a and A are different. if no key is pressed within 2 seconds, the command is cancelled.

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

👀 VIEWING A FILE

okay bestie, so you've got your file list, you've found The One, and now you wanna actually look at it. three ways, pick your fighter: click on it, move the cursor to it and hit Enter, or right-click on the file and choose File then Open. ✨

  • Enter, Left-click-on-file, Selector menu, File, Open — view the picture file you chose 💖 and if what you chose is a subdirectory instead? congrats, that subdir is now the current directory. moving up in the world fr fr.

💬 DIALOG BOXES

ngl the viewer has its own whole thing going on — go peek at The Viewer for how that works. but here's the tea: if xzgv hits a serious problem reading a file, it's gonna give you an error. these errors show up in dialogs smack in the middle of your screen 🫶 and they just… stay there. forever. until you click Ok, or press Enter, or press Esc. the dialog is not leaving. you are leaving. 💀

xzgv also uses these same lil dialog boxes for other stuff:

  • getting confirmation that you actually wanna do The Thing. Enter or y = yes bestie 💅, Esc or n = no. (and yeah, you can just click the relevant button with your mouse, same vibe.)
  • showing progress while it's updating a thumbnail. this one's a little unusual — it ✨ auto-vanishes ✨ the second the update finishes. but it does give you a Cancel button you can click to abort the whole update (and pressing Enter or Esc does the exact same thing).
  • reading a directory name. type the directory name, then click Ok (or hit Enter) — or click Cancel (or hit Esc) to bail. the text-input widget it uses lets you do a certain amount of editing, including with these keys:

⌨️ moving the cursor around in that text box

  • Cursor Left, Ctrl-b — move the cursor left. (a vertical bar shows you where the cursor is, iconic.)
  • Cursor Right, Ctrl-f — move the cursor right.
  • Home, Ctrl-a — jump the cursor to the start of the line.
  • End, Ctrl-e — jump the cursor to the end of the line.
  • Backspace, Ctrl-h — delete the char to the left of the cursor. (heads up bestie: Backspace is usually the key above the main Enter key — it's often labelled as just an arrow. don't come for me, that's just how keyboards are 🙈)
  • Delete, Ctrl-d — delete the char the cursor is sitting on.

📋 selection + cut/copy/paste

you can also set the X selection (either by selecting text with the mouse, or holding Shift while you move the cursor) so you can paste text into other programs. and you can cut/copy/paste text the usual ways:

  • Shift-Delete, Ctrl-x — cut text ✂️
  • Ctrl-Insert, Ctrl-c — copy text
  • Shift-Insert, Ctrl-v — paste text

and yes, that last one lets you paste text in from (some) other programs too. slay.

🚪 CLOSING A FILE

so normally when you view a file, the viewer subwindow just keeps displaying it until you go view a different file. lowkey committed. but if you close the file, the viewer stops showing it and returns to its initial state — like nothing ever happened 💅

  • Ctrl-w, Selector menu, File, Close — close the currently-viewed file, clearing out the viewer subwindow.

🔍 FILE DETAILS

the listing the selector gives you for a file is pretty sparse ngl — just the filename and, if the file has one, the accompanying thumbnail. which is nice and simple, but sometimes you're nosy and you wanna know how much space a file takes up, when it was last modified, the dimensions of the image, that kind of thing. so bestie, you can show details of a single file with 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 which file the details are given for when you're using the mouse. (basically: you right-click on the file when popping up the menu. that's it.)

most of the details shown come straight from the OS (via the stat(2) system call 🫶) and should always be available unless you've got limited permissions for the directory the file's in. but the file dimensions (width/height) come from the file's thumbnail. so 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. no dimensions for you. 😭

(okay let me explain that last bit, because it's a whole saga. pre-5.0 versions of zgv did not generate width/height comments in thumbnails, so zgv users in particular might find the width/height details missing. (xzgv has always been ok though — it's just zgv that had this problem, not us. 💅) and 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, bestie. you can tag as many (or as few) files as you wish, and certain commands described in this section will act on all of them. main character energy, but for a whole group chat.

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

to tag or untag a single file with the mouse, control-click on the relevant filename or thumbnail in the selector (i.e. hold down the control key and click). 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 that way) — but ngl that's usually much less convenient than control-click. (the menu entries for those are really just for completeness. 🫶)

there's also a command available in the viewer to tag the currently-viewed file. see Changing Picture for the 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 the files 💖
  • Alt -, Alt-Keypad -, Alt-9, Selector menu, Tagging, Untag All — untag all the files
  • Alt-o, Selector menu, Tagging, Toggle All — toggle all tags. this inverts the tagged state, so all previously tagged files become untagged, and all previously untagged files become tagged. ✨ flip it, reverse it.
currently there is no way to toggle a (single) file's tag state from the keyboard. that's just the rules bestie 😔

🧭 Moving Between Tagged Files

these commands let you search for (move to) the next or previous tagged file, if there is one. note that next and previous here are relative to the keyboard cursor's position — so if you're doing this from the menu, be careful to right-click on the file you want to start the search from. 🙈

  • /, Selector menu, Tagging, Next Tagged — move to next tagged file in dir.
  • ?, Selector menu, Tagging, Previous Tagged — move to previous tagged file in dir.

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

📦 Copying/Moving Files

you can copy or move tagged files to a directory you specify. and if no files are tagged, xzgv copies/moves the file the cursor is currently on — unless the cursor is sitting on a subdirectory, in which case it just gives you an error. 💀 no vibes.

  • C (Shift-c), Selector menu, File, Copy — copy tagged files (or the current file) to a given directory. xzgv asks for the destination directory using a dialog (see Dialog Boxes) and copies the files there. and heads up: if it comes to copy a file but there's already an existing file in the dir with the same name, that file is not copied, and neither are any of the remaining files. no cap, it just stops.
  • 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, so don't even try it. the new name must remain in the current directory. (see Copying/Moving Files if you wanna 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. :-/ that's just how it is bestie 😭

🗑️ DELETING A FILE

deleting a file is pretty straightforward:

  • Ctrl-d, Selector menu, File, Delete file — delete the file pointed to by the keyboard cursor (and any accompanying thumbnail). see The Selector Menu for how to choose the file deleted when using the mouse. (basically, you right-click on the file when popping up the menu.)
note that only one file is deleted (hence Delete file — singular, babes). there is currently no way to delete all tagged files. 😔

📁 CHANGING DIRECTORY

the easiest way to change the current directory in xzgv is usually to click on a directory entry in the file list (or move the cursor to it and press Enter). and selecting the .. entry moves you to the parent directory of the current one. classic. 🦋

there is an alternative though:

(note that the key for this command is shift-g, not g. not me warning you twice about this.)

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

🔄 RESCANNING THE DIRECTORY

normally, xzgv reads a directory once (on starting up, or when a new directory is selected). so if the contents of the directory get changed by another program, that is not automatically reflected. lowkey xzgv is just vibing with its old info. but you can explicitly tell xzgv to rescan the directory (reread the contents), which updates xzgv's notion of what's in it:

  • Ctrl-r, Selector menu, Directory, Rescan — rescan the current directory. 🔄✨

✨ CHANGING THE SORTING ORDER ✨

So bestie, by default your files show up in asciibetical order by name 🎀 — but that is not the only option, okay? You can sort by size, by last-modified date/time, or by extension (aka the file type). Main character choices only 💅.

Heads up though: only the order of files can be altered. Directories are always listed first, and always in name order. No exceptions, no negotiating. 👑
  • Alt-n / Selector menu, Directory, Sort by Name — sort by name. This is the default, the OG, the blueprint. 💖
  • 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 get listed last.
  • Alt-d / Selector menu, Directory, Sort by Time & Date — sort by time/date. The newest files get listed last too.

You can set the default sort order via the command-line (see Invoking xzgv) or a config file (see Configuring xzgv). Set it and forget it, fr fr ✨.

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). Okay so listen: this is not always the time the file was created, even though people mistake it for that constantly. For example, moving a file with mv will usually change the ctime. So like, don't @ me about it. 😭
  • Alt-Shift-a / Selector menu, Directory, Time & Date Type, Access Time (atime) — use the last-accessed time (mtime). And no, the selector order does not automatically update when xzgv reads files, because that would lowkey be so annoying — do a manual rescan if you need it. 🦋

🎀 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). Toggle go brrr 🔥.

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

  • Alt-a / Selector menu, Options, Auto Hide — toggle the auto-hiding of the selector when a picture is viewed (off by default). This is so handy for small screens/windows, or for the old-time zgv users who just dig that groovy modal interface, er, man. :-) 💀
  • Alt-b / Selector menu, Options, Status Bar — toggle status bar at the bottom of the selector (off by default). This displays messages in certain circumstances — normally, it just says when a picture is being read. Very demure, very mindful 📊.
  • 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. Truly the vibes are off with that one 🙈.
  • v / Selector menu, Options, Thin Rows — toggle thin rows mode (off by default), in which thumbnails are shown at a third their normal size so that many more files can be shown at once. (The odd keyboard shortcut for this is inherited from zgv's visual mode toggle, which had a roughly similar effect. iykyk 💅)
  • Alt-i / Selector menu, Directory, Images Only — toggle the option to show only directories and image files in the selector (off by default). This is handy in directories where images and other file types are intermingled and you want to avoid the Couldn't load image error on those other files. Images are identified by their extensions. Filtered ✨.

👑 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. Main character energy only, bestie 🫶.

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

🦋 EXITING THE VIEWER 🦋

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

Exiting the viewer is simple:

  • Esc
  • Tab
  • Viewer menu, Exit to Selector

…and any of those exits the viewer. This also returns the selector to its former size, if it was previously hidden. Slay, back to business 💖.

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

🌸 BIG PICTURES 🌸

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

  • Make the xzgv window larger. You could maximize it with your window manager, or you could start xzgv with a larger window using --geometry or fullscreen mode (see Options). The fullscreen mode gives xzgv the maximum window size possible, but needs co-operation from your window manager (and alas, many are not as willing as one might like) — in some cases you may even find --geometry 100%x100% to be more effective.
  • Hide the selector. To do this, either use auto-hide mode (see File Selector Options), or hide the selector explicitly (see Hiding the Selector).

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

⭐ Scrolling ⭐

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

  • Cursor Up / K — move up 100 pixels. Ctrl-Cursor Up and k both move up 10 pixels.
  • Cursor Down / J — move down 100 pixels. Ctrl-Cursor Down and j both move down 10 pixels.
  • Cursor Left / H — move left 100 pixels. Ctrl-Cursor Left and h both move left 10 pixels.
  • Cursor Right / L — move right 100 pixels. Ctrl-Cursor Right and l both move right 10 pixels.
  • Page Up / Shift-Cursor Up / Ctrl-u — move up (nearly) the window height. (It moves by 90% of the height.)
  • Page Down / Shift-Cursor Down / Ctrl-v — move down (nearly) the window height.
  • - / Shift-Cursor Left — move left (nearly) a window-length. (It moves by 90% of it.)
  • = / Shift-Cursor Right — move right (nearly) a window-length.
  • Home / Ctrl-a — move to the top-left of the picture.
  • End / Ctrl-e — move to the bottom-right of the picture.

💜 Zoom Mode 💜

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

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. The duality of zoom 🦋.

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

  • z / Viewer menu, Options, Zoom (fit to window) — toggle zoom mode.
  • Alt-r / Viewer menu, Options, When Zooming Reduce Only — when in zoom mode, only reduce pictures to fit. This can be useful when going through a lot of unpredictably-sized pictures, as it means that you can see all of a big picture easily without also meaning that tiny little icons assume a scale of Biblical proportions. :-) 😭
  • Alt-p / Viewer menu, Options, When Zooming Panorama — when in zoom mode, resize to make the most proportional dimension fit and allow scrolling on the other dimension. This can be useful when viewing images that do not adjust nicely to the window size but you want to see them as big as possible while using the most space available. The cause for this function was to better read comics, so you can guess it works like a fit page width option, but is not limited to horizontal adjustment. Comics girlies, this one's for you 📚💅.
Ngl, 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. We work with what we have 🫶.

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 🌸

okay so bestie, you can scale a picture — which literally just makes it look bigger (or smaller) on your screen. and the way xzgv handles it? it acts much as if the scaled picture were the actual real picture. like, the cursor keys scroll around in steps of 100 scaled pixels, even if that means moving a fraction of a pixel in the original picture (or like, a whole bunch of pixels). same deal for moving with the mouse. iconic behaviour honestly.

the main limitation of scaling (aside from how much it slows everything down 😭), at least when you're scaling up, is that you can only scale by integer values. so each pixel in the image can be twice as wide/high, or three times as wide/high, or four times, and so on. no in-between, sorry.

(and yeah, saying like twice as wide/high instead of twice the size might sound weird, but technically twice the size would mean scaling the width and height up by about 1.414.... math is math 💀)

normally, xzgv does no scaling at all, which you could call a ratio of 1:1. scaling up increases that ratio. and how it increases depends on which option/key you use:

  • d
  • Viewer menu, Scaling, Double Scaling — bump the ratio by doubling it, which gives you ratios like 2:1, 4:1, 8:1...
  • s
  • Viewer menu, Scaling, Add 1 to Scaling — bump the ratio by adding one, which gives you 2:1, 3:1, 4:1...

and there are similar commands to bring the ratio down:

  • 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 the more useful ones. ngl.

alsooo you can double/halve the scaling with the mouse: shift-left-click on the viewer to double, and shift-right-click to halve. 🖱️ but it still changes scale around the middle of the window (rather than around the point you clicked on, like you might expect), which is a little strange and may possibly be changed in future. so, yk, be aware.

when you scale below 1:1, those same commands give you ratios of (e.g.) 1:2, 1:4, 1:8, etc. — the ratios work the same way, just the other way around. this gives you an increasingly small image. tiny little guy 🥺

the scaling ratio is never decreased below 1:32. it's also never increased beyond the point where the overall image size would exceed 32767x32767 — that limit comes from the combination of X's limit on window sizes and the implementation xzgv uses for scaling. so that's your ceiling, bestie.

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 while 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, which disables scaling mode and zoom mode.

normally, scaling up works by just making the pixels into bigger and bigger squares (in effect), which stay the same colour. but you can enable a feature called interpolation which smoothly graduates the colour change between the top-left corners of each pixel. it's very slow, but it looks nice. ✨

  • i
  • Viewer menu, Options, Interpolate when Scaling — toggle interpolation in scaling mode.
(if you like the look of scaling with interpolation, you might 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. but you can disable this behaviour if you want (see Viewer Options).

there's also support for an alternative form of scaling — decoupled, or axis-specific, scaling. when you scale this way, only one axis of the image is scaled at a time. for example, you might choose to effectively double the height of an image (with the width left unchanged). and honestly this sort of scaling is useful for temporarily correcting pictures intended for display using pixels twice as wide or high as normal. so handy 🫶

  • x
  • Viewer menu, Scaling, X Only, Double Scaling — increase the (x axis) ratio by doubling it.
  • X (Shift-x)
  • Viewer menu, Scaling, X Only, Halve Scaling — decrease the (x axis) ratio by halving it.
  • Alt-x
  • Viewer menu, Scaling, X Only, Add 1 to Scaling — increase the (x axis) ratio by adding one.
  • Alt-Shift-x
  • Viewer menu, Scaling, X Only, Sub 1 from Scaling — decrease the (x axis) ratio by subtracting one.
  • y
  • Viewer menu, Scaling, Y Only, Double Scaling — increase the (y axis) ratio by doubling it.
  • Y (Shift-y)
  • Viewer menu, Scaling, Y Only, Halve Scaling — decrease the (y axis) ratio by halving it.
  • Alt-y
  • Viewer menu, Scaling, Y Only, Add 1 to Scaling — increase the (y axis) ratio by adding one.
  • Alt-Shift-y
  • Viewer menu, Scaling, Y Only, Sub 1 from Scaling — decrease the (y axis) ratio by subtracting one.

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

interpolation is not currently supported in situations where the x scaling does not match the y scaling. soz 🥲

🦋 MIRROR AND ROTATE 🦋

sometimes when you're viewing a picture you'll want to flip it horizontally or vertically, or rotate it. main character transformations only:

  • m
  • Viewer menu, Orientation, Mirror (horiz) — Mirror the picture (flip it horizontally).
  • f
  • Viewer menu, Orientation, Flip (vert) — Flip the picture (flip it vertically).
  • r
  • Viewer menu, Orientation, Rotate Right — rotate the picture 90 degrees clockwise.
  • R (Shift-r)
  • Viewer menu, Orientation, Rotate Left — rotate the picture 90 degrees anti-clockwise. (any US readers surprised and/or annoyed by my not saying counter-clockwise will realise why the menus say rotate right/left. :-))
  • N (Shift-n)
  • Viewer menu, Orientation, Normal — restore the picture orientation to normal. this undoes the effect of any mirrors, flips, and/or rotations. 💅

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

🌈 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 especially useful when you're using xzgv from the keyboard, but there's also a notable mouse shortcut for moving to the next image. yw bestie.

  • 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 you 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 you're 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 are large? sometimes it's nearly as annoying having the selector hidden to make room for a small picture that didn't even need the room. so for that reason, or maybe you just don't like auto-hide mode :-), you might prefer to leave auto-hide off and explicitly hide the selector when necessary:

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

you can also hide or unhide the selector by middle-clicking on the viewer. 🖱️✨

👑 MINIMIZING XZGV 👑

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

  • Ctrl-z
  • Viewer menu, Window, Minimize — minimize the xzgv window.

go take a lil nap, xzgv 💤

✨ VIEWER OPTIONS ✨

Okay so bestie, same energy as the selector but now we're in the viewer 💖 — there's a whole lil suite of options you can flip on and off that only matter once you're actually staring at a picture.

And fr, you can also change all of these with command-line options (peep Options) and/or config file settings (peep Configuring xzgv). So many doors, same room 🚪✨

  • z Viewer menu, Options, Zoom (fit to window) — toggles zoom mode. We go into this in more detail elsewhere, so (see Zoom Mode). 🔍
  • Alt-r Viewer menu, Options, When Zooming Reduce Only — toggles reduce-only in zoom mode, also covered elsewhere, (see Zoom Mode). 📉
  • Alt-p Viewer menu, Options, When Zooming Panorama — toggles panorama view in zoom mode, also covered elsewhere, (see Zoom Mode). 🌄
  • i Viewer menu, Options, Interpolate when Scaling — toggles 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 — toggles which axis gets 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 — toggles dithering in 15/16-bit modes. This increases the apparent colour depth, which makes gradations look so much better, but heads up bestie: it's slower than undithered rendering, and it 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. iykyk 💅
  • Viewer menu, Options, Revert Scaling For New Pic — normally xzgv returns the scaling back down to 1 (normal) when a new picture is selected. By disabling this, you can retain scaling across picture selection. There is currently no keyboard shortcut for this fairly-seldom-changed option — to toggle it from the keyboard, you should use the popup menu (press F10), and select the menu item. 🎀
  • Viewer menu, Options, Revert Orient. For New Pic — similarly, xzgv returns to the picture's true orientation (not mirrored, rotated, etc.) on selecting a new picture. Disabling this option means that any mirrors/flips/rotates applied persist across multiple images. (No keyboard shortcut — see above.) 🔄
  • Viewer menu, Options, Use Exif Orientation — toggles support for Exif orientation. Devices which create JPEG files in the Exif format (e.g. many digital cameras) may add an orientation tag to the file, which says how the camera was being held when the picture was taken. When this tag is present, xzgv can adjust the image to compensate for a camera being held on its side. This isn't done by default as it misrepresents the true image, which could be confusing if you don't know why it's happening. Enabling this option may be useful if you take pictures with your camera on its side, but don't want to have to rotate the pictures before being able to view them properly. Of course, for this to work your camera has to be inserting the orientation tag in the first place — but it can't hurt to try it and see. (No keyboard shortcut — see above.) 📸

🌈 FILE FORMATS 🌈

Picture files are stored in a variety of different forms, or file formats. xzgv, via gdk, supports many. no cap, it's got range 💖

🦋 FILE TYPE IDENTIFICATION 🦋

The format a file is in is identified by its content. The file-reading code relies on libgdk to determine the file type and read the file correctly; generally this uses the format's magic number to determine file type — e.g. a JPEG/JFIF file starts with the (hex) bytes FF D8. ✨

So if you start xzgv with xzgv foo, and foo is in a supported format (such as JPEG), the format will be figured out and the file loaded even though the extension is absent. She doesn't need the label to know what she is, periodt 💅

💜 CONFIGURING XZGV 💜

Many aspects of the way xzgv works can be modified by using a configuration file. Yes bestie, you get to customize her 🌸

🎀 CONFIG FILES 🎀

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

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

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

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

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

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

🌸 CONFIG VARIABLE TYPES 🌸

There are various types of variable:

  • Boolean. These are on-or-off, yes-or-no variables. Most of xzgv's config file variables are of this type.
  • Integer. These are whole numbers. The meaning of the number depends on what the variable is used for.
  • Geometry. This window size-and/or-position specification format is only used for the geometry setting. See Options, for a description of how this type works.

⭐ CONFIG VARIABLES ⭐

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

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

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

👑 RATIONALE 👑

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

💭 WHY YET ANOTHER VIEWER? 💭

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

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

  • 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. ⚡
  • 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. 🖼️
  • 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:

  • 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.
  • 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.)
  • qiv. If I read between the lines correctly, this is essentially a modern replacement for xli.
  • 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. :^)
  • Electric Eyes. To be honest, I think this has been outclassed by other viewers these days, which shows how far we've come. ✨

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

🙈 WHY NO IMAGE-EDITING CAPABILITIES? 🙈

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

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

🧚 WHY A TEXINFO MANUAL? 🧚

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

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

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

💅 WHY ONE-SPACE SENTENCE ENDS?

Okay bestie, so the traditional texinfo way is to put two spaces after every sentence-ending dot (or whatever punctuation ends the sentence, you get it). And honestly a ton of people write like that even outside of texinfo. But a big chunk of people — and yeah, I'm one of them — just write with one space after the dot. It's giving personal preference, periodt.

Now the Texinfo documentation kinda gives you the vibe that two-space is mandatory, right? It literally says ``it is important to put two spaces at the end of sentences in Texinfo documents.'' But here's the tea: the only circumstance where the spacing from the texinfo file is preserved at all (in any sense beyond "there is a space here") is when the texinfo gets converted to Info format. So actually, choosing two-space is really just about how the author wants the Info output to look — it's a subjective thing that should be 100% the author's call, despite the Texinfo docs trying to make two-space sound like some objective you-must-do-this situation. 🙄

So you might be like, "okay but what's even the problem with one-space?" Bestie. The problem is makeinfo has to reformat paragraphs, and any time it needs to insert space at (what looks to it like) the end of a sentence, it just inserts two spaces. And you cannot change this behaviour, 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, trying to fix the output Info with sed doesn't work properly because the tags used to find nodes quickly end up incorrect. Sure, you could fix those too, but that's a whole lot more work than one little sed invocation, ngl.

So realistically, anyone writing texinfo with one-space just has to put up with the occasional two-space sentence end getting yeeted into their text. And worse — the current makeinfo formatting algorithm seems to insert two spaces even after abbreviations (like e.g. and etc.), which breaks even two-space texinfo. 😭 The irony? Immaculate. Because two-space partisans' whole main argument is usually that it lets you tell abbreviations apart from the end of a sentence. 💀

One last thing worth noting: I am not the first person to write texinfo files using one-space. At the time of writing, it's used in the texinfo documentation for BFD, gdbm, GTK/GDK, (Linux) IPC, and viper — and I'm sure there are instances I don't even know about. 🌸

🐛 BUGS AND RESTRICTIONS

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

  • clearly hasn't written too many programs.
  • is wrong. ;-)

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

👀 KNOWN BUGS

  • In zoom mode, it copes with resizing the window as a whole, but doesn't when you change the size of the pane (apart from when hiding/showing selector or resizing from keyboard, but that's only 'cos I kludged it :-)).
  • When scaling up and dithering, you end up with a crappy-looking picture if you drag the picture around slowly (since each exposed bit is dithered independently, with no regard given to matching up to any previous error-diffusion).
  • Scaling up is slow. Not sure if I can do much about this.
  • Using an alignment widget to centre the viewer window results in some annoying bounce in certain resizing situations etc.
  • Thumbnails don't look so great in palette-based (e.g. 8-bit) modes.
  • When dragging an image around, if you quickly move the mouse pointer over from the image area to the selector area, the image seems to jump a little. I think this may have something to do with the paned window's window-splitting bit, but I'm not sure. Also, it jumps when moving across scrollbar sliders and the paned window splitter handle.
  • It doesn't apply any tranparency mask. The practical result of this seems to be purple transparent bits in thumbnails and scaled-up images, and black transparent bits elsewhere. This doesn't affect PNG files, though.
  • If a GIF file is corrupted in such a way that the decompressed image has a larger number of pixels in it, the extra pixels will be ignored and no error or warning will be generated.
  • If you look up joe code in a dictionary, right next to see zgv'' it now says but for really in-depth insight into the joe code nature, see xzgv''. :-)

😐 SUBOPTIMAL FEATURES

  • Thumbnails are given an accurate width/height IMGINFO comment, but are always claimed to be "RGB".
  • xzgv doesn't duplicate zgv's behaviour of generating thumbnails under ~/.xvpics/_foo_bar_baz if it can't generate them in /foo/bar/baz/.xvpics. I doubt anything else supported it, and it complicated lots of things unnecessarily. This isn't particularly suboptimal, but as an incompatibility with zgv it merits mention.

🚧 RESTRICTIONS

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

📢 REPORTING BUGS

If you find xzgv does something wrong, and you suspect it might be a fault of some sort (a bug) in the program, it's best to report it, because I may not be aware of the problem. (But first — check it's 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:

  • The version of xzgv you are running. xzgv --version reports this.
  • The versions of GTK+ you are using. xzgv --version-gtk reports the GTK+ version being used by xzgv.
  • 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.
  • A description of the bug --- what effects it has, the circumstances it occurs in, and so on. Does it only happen for certain types of file? Only when in 8-bit modes? Only when dithering is enabled? Even irrelevant details can sometimes be useful.
  • Finally, if you are a programmer and believe you have managed to fix the bug yourself, patches are gratefully accepted. :-) You should generate the patch using diff -c or (preferably) diff -u.

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

📝 REPORTING DOCUMENTATION BUGS

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

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

  • The version of xzgv the documentation is for.
  • 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 :-)).
  • The format of the documentation you saw the problem in (e.g. info, man page, HTML).
  • A description of the problem.

🔮 FUTURE CHANGES

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

Future changes etc. are listed in the TODO file.

👑 AUTHOR

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

🌈 SEE ALSO

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

And that's a wrap, bestie! 🎀 This whole page is Version 0.9, dated the 9th August 2017, and it's the XZGV(1) manual page — you read the entire thing, which is iconic main character energy honestly. Go forth and view some images. 💖🦋🌸

📦 where this page comes from