diff options
Diffstat (limited to 'man/feh.pre')
| -rw-r--r-- | man/feh.pre | 1239 |
1 files changed, 843 insertions, 396 deletions
diff --git a/man/feh.pre b/man/feh.pre index 4a8b0f8..ca64d37 100644 --- a/man/feh.pre +++ b/man/feh.pre @@ -13,7 +13,8 @@ . .Nm .Op Ar options -.Op Ar files No | Ar directories No | Ar URLs ... +.Op Cm -- +.Op Ar files | Ar directories | Ar URLs ... . . .Sh VERSION @@ -24,34 +25,51 @@ $VERSION$ . .Pp . -Compile-time switches: libcurl support $MAN_CURL$, Xinerama support -$MAN_XINERAMA$, builtin EXIF support $MAN_EXIF$$MAN_DEBUG$ +Compile-time switches in this build: . +.Bl -bullet -compact . -.Sh DESCRIPTION +.It +libcurl remote file support $MAN_CURL$ . -.Nm -is a mode-based image viewer. It is especially aimed at command line users who -need a fast image viewer without huge GUI dependencies, though it can also be -started by -.Pq graphical -file managers to view an image. -By default -.Pq unless arguments or a filelist are specified , -.Nm -displays all files in the current directory. +.It +Xinerama multi-monitor support $MAN_XINERAMA$ . -.Pp +.It +libexif builtin EXIF reader $MAN_EXIF$ +. +.It +inotify-based auto-reload of changed files $MAN_INOTIFY$ +. +.It +libmagic $MAN_MAGIC$ +. +.El +. +$MAN_DEBUG$ +. +. +.Sh DESCRIPTION . .Nm -supports filelists, various image sorting modes, image captions, HTTP and more. -Configurable keyboard and mouse shortcuts are used to control it. +is a light-weight, configurable and versatile image viewer. +It is aimed at command line users, but can also be started from graphical file +managers. +Apart from viewing images, it can compile text and thumbnail +listings, show (un)loadable files, set X11 backgrounds, and more. . .Pp . -In many desktop environments, +Features include filelists, various image sorting modes, custom action scripts, +and image captions. .Nm -can also be used as wallpaper setter. +can be controlled by configurable keyboard and mouse shortcuts, terminal +input and signals. +When no file arguments or filelists are specified and +.Cm --start-at +is not used, +.Nm +displays all files in the current directory. . .Pp . @@ -73,8 +91,9 @@ options. . .Pp . -Slideshow mode is the default. It opens a window and displays the first -image in it; the slideshow position can be advanced +Slideshow mode is the default. +It opens a window and displays the first image in it; +the slideshow position can be advanced .Pq or otherwise changed using keyboard and mouse shortcuts. In slideshow mode, images can be deleted either from the filelist or from the @@ -85,14 +104,17 @@ An image can also be read from stdin via . .Pp . -Montage mode forms a montage from the filelist. The resulting image can be -viewed or saved, and its size can be limited by height, width or both. +Montage mode forms a montage from the filelist. +The resulting image can be viewed or saved, +and its size can be limited by height, width or both. . .Pp . -Index mode forms an index print from the filelist. Image thumbnails are shown -along with the filename, filesize and pixel size, printed using a truetype -font of your choice. The resulting image can be viewed or saved, and its size +Index mode forms an index print from the filelist. +Image thumbnails are shown along with the filename, +size and dimensions, printed using a truetype +font of your choice. +The resulting image can be viewed or saved, and its size can be limited by height, width or both. . .Pp @@ -103,37 +125,71 @@ the selected image in a new window. .Pp . Multiwindow mode shows images in multiple windows, instead of as a slideshow -in one window. Don't use with a large filelist ;) +in one window. +Don't use with a large filelist ;) . .Pp . -List mode doesn't display images. Instead, it outputs an +List mode doesn't display images. +Instead, it outputs an .Cm ls Ns No - Ns style listing of the files in the filelist, including image info such as size, number -of pixels, type, etc. There is also a Customlist mode which prints image info +of pixels, type, etc. +There is also a Customlist mode which prints image info in a custom format specified by a printf-like format string. . .Pp . .Nm can also list either all the loadable files in a filelist or all the -unloadable files. This is useful for preening a directory. +unloadable files. +This is useful for preening a directory. . . .Sh SUPPORTED FORMATS . .Nm -can open any format supported by Imlib2, most notably jpeg, png, -pnm, tiff, and bmp. The gif format is also supported, but only for static -images. In case of animations, only the first frame will be shown. +can open any format supported by imlib2, most notably jpeg, png, +pnm, tiff, and bmp. +The gif format is also supported, but only for static images. +In case of animations, only the first frame will be shown. +. +.Pp +. +When invoked with +.Cm --conversion-timeout Ar timeout +.Po +and a non-negative +.Ar timeout +value +.Pc , +.Nm +also has limited support for various other file types by means of external +conversion programs. +If the dcraw binary is available, +.Nm +will use it to display the thumbnails embedded into RAW files provided by +digital cameras and similar. +If the ImageMagick convert binary is available, +.Nm +will use it to load file types such as svg, xcf, and otf. . -If the convert binary -.Pq supplied by ImageMagick -is available, it also has limited support for many other filetypes, such as -svg, xcf and otf. Use -.Cm --magick-timeout Ar num -with a non-negative value to enable it. +.Pp . +.Pq optional feature, $MAN_MAGIC$ in this build +.Nm +can use libmagic to only pass image files to Imlib2. +When using +.Nm +with lots of non-image files +.Pq especially with Imlib2 version 1.6.x or 1.7.0 , +this can speed up the detection of non-image files significantly. +If you think that Imlib2 can load a file which +.Nm +has determined to be likely not an image, set the environment variable +.Qq FEH_SKIP_MAGIC +to pass all files directly to Imlib2, bypassing this check. +The environment variable's value does not matter, it just needs to be set. . .Sh OPTIONS . @@ -141,11 +197,13 @@ with a non-negative value to enable it. . .It Cm -A , --action Oo Ar flag Oc Ns Oo [ Ar title ] Oc Ns Ar action . -Specify a shell command as an action to perform on the image. In slideshow or -multiwindow mode, the action will be run when the action_0 key is pressed, in -list mode, it will be run for each file. In loadable/unloadable mode, it will -be run for each loadable/unloadable file, respectively. In thumbnail mode, -clicking on an image will cause the action to run instead of opening the image. +Specify a shell command as an action to perform on the image. +In slideshow or multiwindow mode, the action will be run when +the action_0 key is pressed, in list mode, it will be run for each file. +In loadable/unloadable mode, it will be run for each loadable/unloadable +file, respectively. +In thumbnail mode, clicking on an image will cause the action to run instead +of opening the image. . .Pp . @@ -162,7 +220,7 @@ after executing the action. . If -.No [ Ar title ] +.Ar [ title ] is specified .Pq note the literal Qo \&[ Qc and Qo ] Qc , .Cm --draw-actions @@ -170,10 +228,12 @@ will display .Ar title instead of .Ar action -in the action list. Note that +in the action list. +Note that .Ar title -must not start with a space. If it does, the action is handled as if it did -not have a title. This special case exists for backwards compatibility reasons +must not start with a space. +If it does, the action is handled as if it did not have a title. +This special case exists for backwards compatibility reasons and makes sure that actions like .Qq \&[ -L %F \&] && foo still work. @@ -181,20 +241,45 @@ still work. . .Pp . -The action will be executed by /bin/sh. Use format specifiers to refer to -image info, see +The action will be executed by /bin/sh. +Use format specifiers to refer to image info, see .Sx FORMAT SPECIFIERS -for details. Example usage: -.Qq feh -A Qo mv ~/images/%N Qc * . +for details. +Example usage: +.Qq feh -A Qo mv %F ~/images/%N Qc * . . .It Cm --action1 No .. Cm --action9 Oo Ar flag Oc Ns Oo [ Ar title ] Oc Ns Ar action . Extra actions which can be set and triggered using the appropriate number key. . +.It Cm --auto-reload +. +.Pq optional feature, $MAN_INOTIFY$ in this build +automatically reload image when the underlying file changes. +Note that auto-reload +.Pq if enabled in the build +is on by default. +This option is only useful to re-enable auto-reload after it has been +disabled by a preceding +.Cm --reload=0 +option. +. +.Pp +. +Automatic reload is not supported in montage, index, or thumbnail mode. +. .It Cm --auto-rotate . -.Pq only if compiled with exif=1 -Automatically rotate images based on EXIF data. Does not alter the image files. +.Pq optional feature, $MAN_EXIF$ in this build +.Pq deprecated in favor of Imlib2's auto-orientation support +Automatically rotate images based on EXIF data. +Does not alter the image files. +. +.Pp +. +Note that Imlib2 version 1.7.5+ performs auto-rotation by itself, so this option is obsolete on systems with Imlib2 version 1.7.5 or later. +.Nm +currently cannot detect this at runtime. . .It Cm -Z , --auto-zoom . @@ -204,73 +289,115 @@ Zoom pictures to screen size in fullscreen / fixed geometry mode. . Create borderless windows. . +.It Cm --cache-size Ar size +. +Set imlib2 in-memory cache to +.Ar size +MiB. +A higher cache size can significantly improve performance especially for small +slide shows, however at the cost of increased memory consumption. +.Ar size +must be between 0 and 2048 MiB and defaults to 4. +. .It Cm -P , --cache-thumbnails . -Enable thumbnail caching in -.Pa ~/.thumbnails . -Only works with thumbnails <= 256x256 pixels. +Enable thumbnail caching. +Thumbnails are saved in +.Pa $XDG_CACHE_HOME/thumbnails , +which defaults to +.Pa ~/.cache/thumbnails . +Note that thumbnails are only cached if the configured thumbnail size does +not exceed 256x256 pixels. . .It Cm -K , --caption-path Ar path . -Path to directory containing image captions. This turns on caption viewing, -and if captions are found in +Path to directory containing image captions. +This turns on caption viewing, and if captions are found in .Ar path , which is relative to the directory of each image, they are overlayed on the -displayed image. E.g. with caption path +displayed image. +E.g. with caption path .Qq captions/ , and viewing image .Qq images/foo.jpg , the caption will be looked for in .Qq images/captions/foo.jpg.txt . . +.It Cm --conversion-timeout Ar timeout +. +.Nm +can use ImageMagick to try converting unloadable files into a supported +file format. +As this can take a long time, it is disabled by default. +Set +.Ar timeout +to a non-negative value to enable it. +A positive value +specifies after how many seconds conversion attempts should be aborted, +zero causes +.Nm +to try indefinitely. +Negative values restore the default by disabling conversion altogether. +. +.It Cm --class Ar class +. +Set the X11 class hint to +.Ar class . +. +Default: feh +. .It Cm -L , --customlist Ar format . Don't display images, print image info according to .Ar format -instead. See +instead. +See .Sx FORMAT SPECIFIERS . . -.It Cm --cycle-once -. -Exit -.Nm -after one loop through the slideshow. -. .It Cm -G , --draw-actions . Draw the defined actions and what they do at the top-left of the image. . .It Cm --draw-exif . -.Pq only if compiled with exif=1 +.Pq optional feature, $MAN_EXIF$ in this build display some EXIF information in the bottom left corner, similar to using .Cm --info -with exiv2 / exifgrep . +with exiv2 / exifgrep. . .It Cm -d , --draw-filename . -Draw the filename at the top-left of the image. +Draw the file name at the top-left of the image. . .It Cm --draw-tinted . Show overlay texts .Pq as created by Cm --draw-filename No et al -on a semi-transparent background to improve their readability +on a semi-transparent background to improve their readability. +. +.It Cm --edit +. +Enable basic editing of files. +This makes rotation and mirroring +.Pq bound to Qo < Qc , Qo > Qc , Qo | Qc , and Qo _ Qc by default +change the underlying file and not just its displayed content. . .It Cm -f , --filelist Ar file . -This option is similar to the playlists used by music software. If +This option is similar to the playlists used by music software. +If .Ar file exists, it will be read for a list of files to load, in the order they appear. -The format is a list of image filenames, absolute or relative to the current -directory, one filename per line. +The format is a list of image file names, absolute or relative to the current +directory, one file name per line. . .Pp . If .Ar file doesn't exist, it will be created from the internal filelist at the end of a -viewing session. This is best used to store the results of complex sorts +viewing session. +This is best used to store the results of complex sorts .Pq Cm -Spixels No for example for later viewing. . @@ -282,7 +409,8 @@ will be saved to .Ar file when .Nm -exits. You can add files to filelists by specifying them on the command line +exits. +You can add files to filelists by specifying them on the command line when also specifying the list. . .Pp @@ -296,9 +424,11 @@ will read the filelist from its standard input. . .It Cm -e , --font Ar font . -Set global font. Should be a truetype font, resident in the current directory -or the font directory, and should be defined in the form fontname/points, like -.Qq myfont/12 . +Set global font. +Should be a truetype font, resident in the current directory or the font +directory, and should be defined in the form fontname/size, like +.Qq yudit/12 +.Pq which is the default . . .It Cm -C , --fontpath Ar path . @@ -307,9 +437,13 @@ Specify as extra directory in which to search for fonts; can be used multiple times to add multiple paths. . +.It Cm --tap-zones +. +Enable tap zones for previous/next file in slide show mode +. .It Cm --force-aliasing . -Disable antialiasing for zooming, background setting etc. +Disable anti-aliasing for zooming, background setting etc. . .It Cm -I , --fullindex . @@ -325,7 +459,8 @@ Note: This option needs to load all images to calculate the dimensions of the .Nm window, so when using it with many files it will take a while before a .Nm -window is visible. Use +window is visible. +Use .Cm --preload to get a progress bar. . @@ -333,32 +468,34 @@ to get a progress bar. . Make the window fullscreen. Note that in this mode, large images will always be scaled down to fit the -screen, +screen, and .Cm --zoom Ar zoom only affects smaller images and never scales larger than necessary to fit the -screen size. The only exception is a +screen size. +The only exception is a .Ar zoom -of 100, in which case images will always be shown at 100% zoom, no matter -their dimensions. +of 100, in which case images will always be shown at 100% zoom. . .Pp . When combined with .Cm --thumbnails , -this option only affects images opened from the thumbnail overview. The -thumbnail list itself will still be windowed. +this option only affects images opened from the thumbnail overview. +The thumbnail list itself will still be windowed. . -.It Cm -g , --geometry Oo Ar width No x Ar height Oc Op + Ar x No + Ar y +.It Cm -g , --geometry Ar width Cm x Ar height | Cm + Ar x Cm + Ar y | Ar width Cm x Ar height Cm + Ar x Cm + Ar y . -Limit (and don't change) the window size. Takes an X-style geometry -.Ar string -like 640x480 with optional +x+y window offset. -Note that larger images will be zoomed out to fit, but you can see them at 1:1 -by clicking the zoom button. +Use a fixed window size as specified in the X-style geometry +.Ar string , +e.g. 640x480. +An optional +x+y window offset can be specified. +Combine with +.Cm --scale-down +to scale down larger images like in fullscreen mode. . -Also note that this option does not enforce the geometry, changing it by a tiling -WM or manually is still possible. After each resize, the resulting window size -is used as the new size limit. +Note that this option does not enforce the window size; changing it by a tiling +WM or manually is still possible. +However, auto-resize remains disabled. . .It Cm -Y , --hide-pointer . @@ -367,26 +504,38 @@ Hide the pointer . .It Cm -B , --image-bg Ar style . -Use style as background for transparent image parts and the like. -Accepted values: checks, white, black. -. -The default for windowed mode is checks, while fullscreen defaults to black. +Use +.Ar style +as background for transparent image parts and the like. +Accepted values: default, checks, or an XColor +.Pq e.g. Qo black Qc or Qo #428bdd Qc . +Note that some shells treat the hash symbol as a special character, so you +may need to quote or escape it for the XColor code to work. +. +In windowed mode, the default is checks +.Pq a checkered background so transparent image parts are easy to see . +In fullscreen and background setting mode, +.Cm checks +is not accepted and the default is black. . .It Cm -i , --index . -Enable Index mode. Index mode is similar to montage mode, and accepts the -same options. It creates an index print of thumbnails, printing the image -name beneath each thumbnail. Index mode enables certain other options, see +Enable Index mode. +Index mode is similar to montage mode, and accepts the same options. +It creates an index print of thumbnails, printing the image name beneath +each thumbnail. +Index mode enables certain other options, see .Sx INDEX AND THUMBNAIL MODE OPTIONS and .Sx MONTAGE MODE OPTIONS . . -.It Cm --info Oo Ar flag Oc Ns Ar commandline +.It Cm --info Oo Ar flag Oc Ns Ar command_line . Execute -.Ar commandline -and display its output in the bottom left corner of the image. Can be used to -display e.g. image dimensions or EXIF information. Supports +.Ar command_line +and display its output in the bottom left corner of the image. +Can be used to display e.g. image dimensions or EXIF information. +Supports .Sx FORMAT SPECIFIERS . . If @@ -396,6 +545,12 @@ is set to the output will not be displayed by default, but has to be enabled by the toggle_info key. . +.It Cm --insecure +. +When viewing files with HTTPS, this option disables all certificate checks. +It allows images on sites with self-signed or expired certificates to be +opened, but is no more secure than plain HTTP. +. .It Cm -k , --keep-http . When viewing files using HTTP, @@ -406,12 +561,6 @@ specified by .Cm --output-dir , or in the current working directory. . -.It Cm --insecure -. -When viewing files with HTTPS, this option disables strict hostname and peer -checking. This allows images on sites with self-signed certificates to be -opened, but is no more secure than plain HTTP. -. .It Cm --keep-zoom-vp . When switching images, keep zoom and viewport settings @@ -419,25 +568,20 @@ When switching images, keep zoom and viewport settings . .It Cm -l , --list . -Don't display images. Analyze them and display an +Don't display images. +Analyze them and display an .Xr ls 1 - No style -listing. Useful in scripts to hunt out images of a certain -size/resolution/type etc. +listing. +Useful in scripts to hunt out images of a certain size/resolution/type etc. . .It Cm -U , --loadable . -Don't display images. Just print out their names if imlib2 can successfully -load them. +Don't display images. +Just print out their names if imlib2 can successfully load them. Returns false if at least one image failed to load. -. -.It Cm --magick-timeout Ar timeout -. -Stop trying to convert unloadable files after -.Ar timeout -seconds. A negative value disables covert / magick support altogether, a value -of zero causes -.Nm -to try indefinitely. By default, magick support is disabled. +When combined with +.Cm --action , +the specified action will be run for each loadable image. . .It Cm --max-dimension Ar width No x Ar height . @@ -465,15 +609,32 @@ If you only care about one parameter, set the other to 0. . .It Cm -m , --montage . -Enable montage mode. Montage mode creates a new image consisting of a grid of -thumbnails of the images in the filelist. When montage mode is selected, -certain other options become available. See +Enable montage mode. +Montage mode creates a new image consisting of a grid of thumbnails of the +images in the filelist. +When montage mode is selected, certain other options become available. +See .Sx MONTAGE MODE OPTIONS . . .It Cm -w , --multiwindow . -Disable slideshow mode. With this setting, instead of opening multiple files -in slideshow mode, multiple windows will be opened; one per file. +Disable slideshow mode. +With this setting, instead of opening multiple files in slideshow mode, +multiple windows will be opened; one per file. +. +.It Cm --no-conversion-cache +. +When loading images via HTTP, ImageMagick or dcraw, +.Nm +will only load/convert them once and re-use the cached file on subsequent +slideshow passes. +This option disables the cache. +It is also disabled when +.Cm --reload +is used. +Use it if you rely on frequently changing files loaded via one of these +sources. +Note that it will impair performance. . .It Cm --no-jump-on-resort . @@ -485,80 +646,134 @@ Don't load or show any menus. . .It Cm --no-screen-clip . -By default, window sizes are limited to the screen size. With this option, -windows will have the size of the image inside them. Note that they may -become very large this way, making them unmanageable in certain window -managers. +By default, window sizes are limited to the screen size. +With this option, windows will have the size of the image inside them. +Note that they may become very large this way, making them unmanageable +in certain window managers. . .It Cm --no-xinerama . -Disable Xinerama support. Only makes sense when you have Xinerama support -compiled in. +.Pq optional feature, $MAN_XINERAMA$ in this build +Disable Xinerama support. +. +.It Cm --on-last-slide Cm hold | Cm quit | Cm resume +. +Select behaviour when trying to select the next image on the last slide +.Pq or the previous image on the first slide +in a slide show. +. +.Pp +. +With +.Cm hold , +.Nm +will stop advancing images in this case and continue displaying the first/last +image, respectively. +This is intended for linear slide shows. +Behaviour is unspecified when using other navigation commands than previous +and next image. +. +.Pp +. +.Cm quit +will cause +.Nm +to quit when trying to advance past the last image in the slide show. This is +the behavior of the obsolete +.Cm --cycle-once +option. +. +.Pp +. +.Cm resume +is the default behaviour: On the last +.Pq first +image, +.Nm +will wrap around to the first +.Pq last +image. . .It Cm -j , --output-dir Ar directory . Save files to .Ar directory -.Pq only useful with -k . +when using +.Cm --keep-http +or the save_image or save_filelist command. By default, files are saved in the current working directory. . .It Cm -p , --preload . -Preload images. This doesn't mean hold them in RAM, it means run through -them and eliminate unloadable images first. Otherwise they will be removed -as you flick through. This also analyses the images to get data for use in -sorting, such as pixel size, type etc. A preload run will be automatically -performed if you specify one of these sort modes. +Preload images. +This doesn't mean hold them in RAM, it means run through them and eliminate +unloadable images first. +Otherwise they will be removed as you flick through. +This also analyses the images to get data for use in sorting, such as pixel +size, type etc. +A preload run will be automatically performed if you specify one of these +sort modes. . .It Cm -q , --quiet . -Don't report non-fatal errors for failed loads. Verbose and quiet modes are -not mutually exclusive, the first controls informational messages, the second -only errors. +Don't report non-fatal errors for failed loads. +Verbose and quiet modes are not mutually exclusive, the first controls +informational messages, the second only errors. . .It Cm -z , --randomize . When viewing multiple files in a slideshow, randomize the file list before -displaying. The list is re-randomized whenever the slideshow cycles (that is, -transitions from last to first image). +displaying. +The list is re-randomized whenever the slideshow cycles (that is, transitions +from last to first image). . .It Cm -r , --recursive . -Recursively expand any directories in the commandline arguments +Recursively expand any directories in the command line arguments to the content of those directories, all the way down to the bottom level. . .It Cm --no-recursive . -Don't recursively expand any directories (enabled by default). -Useful to override theme options. +Don't recursively expand any directories. +This is the default, but this option is useful to override themes containing +.Cm --recursive . . .It Cm -R , --reload Ar int . Reload filelist and current image after .Ar int -seconds. Useful for viewing HTTP webcams or frequently changing directories. -.Pq Note that the filelist reloading is still experimental. +seconds. +Useful for viewing HTTP webcams or frequently changing directories. +.Pq Note that filelist reloading is still experimental. +Set to zero to disable any kind of automatic reloading. . .Pp . If an image is removed, .Nm -will either show the next one or quit. However, if an image still exists, but -can no longer be loaded, +will either show the next one or quit. +However, if an image still exists, but can no longer be loaded, .Nm will continue to try loading it. . +.Pp +. +Setting this option causes inotify-based auto-reload to be disabled. +Reload is not supported in montage, index, or thumbnail mode. +. .It Cm -n , --reverse . -Reverse the sort order. Use this to invert the order of the filelist. +Reverse the sort order. +Use this to invert the order of the filelist. E.g. to sort in reverse width order, use .Cm -nSwidth . . .It Cm -. , --scale-down . Scale images to fit window geometry (defaults to screen size when no geometry -was specified). Note that the window geometry is not updated when changing -images at the moment. This option is recommended for tiling window managers. +was specified). +Note that the window geometry is not updated when changing images at the moment. +This option is recommended for tiling window managers. . This option is ignored when in fullscreen and thumbnail list mode. . @@ -571,17 +786,19 @@ In tiling environments, this also causes the image to be centered in the window. Scroll .Ar count pixels whenever scroll_up, scroll_down, scroll_left or scroll_right is pressed. -Note that this option accepts negative numbers in case you need to inverse the -scroll direction; see +Note that this option accepts negative numbers in case you need to reverse the +scroll direction. +See .Sx KEYS CONFIG SYNTAX -to change it permanently. +for how to reverse it permanently. Default: 20 . .It Cm -D , --slideshow-delay Ar float . For slideshow mode, wait .Ar float -seconds between automatically changing slides. Useful for presentations. +seconds between automatically changing slides. +Useful for presentations. Specify a negative number to set the delay .Pq which will then be Ar float No * (-1) , but start @@ -590,33 +807,78 @@ in paused mode. . .It Cm -S , --sort Ar sort_type . -The file list may be sorted according to image parameters. Allowed sort types -are: name, filename, dirname, mtime, width, height, pixels, size, format. For -sort modes other than name, filename, dirname, or mtime, a preload run will be +Sort file list according to image parameters. +Allowed sort types are: +.Cm name , none , filename , dirname , mtime , width , height , pixels , size , format . +For sort modes other than +.Cm name , none , filename , dirname , +or +.Cm mtime , +a preload run is necessary, causing a delay proportional to the number of images in the list. . .Pp . -The mtime sort mode sorts images by most recently modified. To sort by oldest -first, reverse the filelist with --reverse. +.Cm mtime +starts with the most recently modified image. +.Cm width , height , pixels +and +.Cm size +start with the smallest. +Use +.Cm --reverse +to sort by oldest or largest first. +. +.Pp +. +For +.Cm name , filename , +and +.Cm dirname +you can use +.Cm --version-sort +to sort numbers naturally, so that e.g. 10.jpg comes after 2.jpg. . +.Pp +. +.Cm none +is the default; you can specify it explicitly to discard a sort mode that has +been specified at an earlier point in the command line arguments. .It Cm -| , --start-at Ar filename . Start the filelist at .Ar filename . -. -Note that at the moment, +If no other files or filelists were specified on the command line, +.Nm +will first load all files from the directory in which .Ar filename -must match an -.Pq expanded -path in the filelist. So, if the file to be matched is passed via an absolute -path in the filelist, +resides. +This way, it's possible to look at a specific image and use the next / prev +keys to browse through the directory. +See +.Sx USAGE EXAMPLES +for examples. +If .Ar filename -must be an absolute path. If the file is passed via a relative path, +is a remote URL and no files or filelists were specified, +.Nm +will show .Ar filename -must be an identical relative path. This is a known issue. -See also -.Sx USAGE EXAMPLES . +and not attempt to load additional files or directories. +. +.Pp +. +Note: If you use relative paths in your filelist, +.Ar filename +should also be a relative path. +If you use absolute paths, it should also be an absolute path. +. +If +.Nm +cannot find an exact match, it will compare basenames +.Pq filenames without the directory suffix . +This may lead to mismatches if several files in your filelist +have the same basename. . .It Cm -T , --theme Ar theme . @@ -624,7 +886,8 @@ Load options from config file with name .Ar theme - see .Sx THEMES CONFIG SYNTAX -for more info. Note that commandline options always override theme options. +for more info. +Note that command line options always override theme options. The theme can also be set via the program name .Pq e.g. with symlinks , so by default @@ -640,8 +903,8 @@ Note that .Cm --fullscreen and .Cm --scale-down -do not affect the thumbnail window. They do, however, work for image windows -launched from thumbnail mode. +do not affect the thumbnail window. +They do, however, work for image windows launched from thumbnail mode. Also supports .Sx INDEX AND THUMBNAIL MODE OPTIONS as well as @@ -651,20 +914,25 @@ as well as . Set .Ar title -for windows opened from thumbnail mode. See also +for windows opened from thumbnail mode. +See also .Sx FORMAT SPECIFIERS . . .It Cm -^ , --title Ar title . -Set window title. Applies to all windows except those opened from thumbnail -mode. See +Set window title. +Applies to all windows except those opened from thumbnail mode. +See .Sx FORMAT SPECIFIERS . . .It Cm -u , --unloadable . -Don't display images. Just print out their names if imlib2 can NOT -successfully load them. +Don't display images. +Just print out their names if imlib2 can NOT successfully load them. Returns false if at least one image was loadable. +When combined with +.Cm --action , +the specified action will be run for each unloadable file. . .It Cm -V , --verbose . @@ -674,35 +942,72 @@ output useful information, progress bars, etc. . output version information and exit. . -.It Cm --xinerama-index Ar screen +.It Cm --version-sort +. +When combined with +.Cm --sort name , --sort filename , +or +.Cm --sort dirname : +use natural sorting for file and directory names. +In this mode, filenames are sorted as an ordinary human would expect, e.g. +.Qq 2.jpg +comes before +.Qq 10.jpg . +Note that this option only has an effect when a sort mode is set using +.Cm --sort . +. +.It Cm --window-id Ar windowid +. +Draw to an existing X11 window by its ID +.Ar windowid . +This option is intended for use with software such as xcreensaver or +xsecurelock, which provide a window for other applications to draw into. +Unexpected things will happen if you specify a window belonging to software +which does not expect +.Nm +to draw into it or attempt to use options or keybindings which affect window +attributes, such as full-screen mode. . +.It Cm --xinerama-index Ar monitor +. +.Pq optional feature, $MAN_XINERAMA$ in this build Override .Nm Ns No 's -idea of the active Xinerama screen. May be useful in certain circumstances -where the window manager places the feh window on Xinerama screen A while +idea of the active Xinerama monitor. +May be useful in certain circumstances where the window manager places the feh +window on Xinerama monitor A while .Nm -assumes that it will be placed on screen B. +assumes that it will be placed on monitor B. . .Pp . In background setting mode: When used with any option other than .Cm --bg-tile : Only set wallpaper on -.Ar screen . -All other screens will be filled black/white. -. -This is most useful in a Xinerama configuration with -overlapping screens. For instance, assume you have two overlapping displays -(index 0 and 1), where index 0 is smaller. To center a background on the -display with index 0 and fill the extra space on index 1 black/white, use +.Ar monitor . +All other monitors will be filled black/white. +. +This is most useful in a Xinerama configuration with overlapping monitors. +For instance, assume you have two overlapping displays (index 0 and 1), +where index 0 is smaller. +To center a background on the display with index 0 and fill the extra space +on index 1 black/white, use .Qq --xinerama-index 0 when setting the wallpaper. . -.It Cm --zoom Ar percent No | Cm max No | Cm fill +.Pp +. +Use +.Cm xrandr --listmonitors +to determine how Xinerama monitor IDs map to screens/monitors in your setup. +. +. +.It Cm --zoom Ar percent | Cm max | Cm fill . Zoom images by .Ar percent -when in full screen mode or when window geometry is fixed. When combined with +when in full screen mode or when window geometry is fixed. +When combined with .Cm --auto-zoom , zooming will be limited to the specified .Ar percent . @@ -718,8 +1023,14 @@ zoom the image like the .Cm --bg-fill mode. . -.El +.It Cm --zoom-step Ar percent . +Zoom images in and out by +.Ar percent +.Pq default: 25 +when using the zoom keys and buttons. +. +.El . .Sh MONTAGE MODE OPTIONS . @@ -735,14 +1046,15 @@ When drawing thumbnails onto the background, set their transparency level to .Ar int .Pq 0 - 255 . . -.It Cm -b , --bg Ar file No | Cm trans +.It Cm -b , --bg Ar file | Cm trans . Use .Ar file -as background for your montage. With this option specified, the montage size -will default to the size of +as background for your montage. +With this option specified, the montage size will default to the size of .Ar file -if no size restrictions were specified. Alternatively, if +if no size restrictions were specified. +Alternatively, if .Ar file is .Qq trans , @@ -751,8 +1063,8 @@ the background will be made transparent. .It Cm -X , --ignore-aspect . By default, the montage thumbnails will retain their aspect ratios, while -fitting into thumb-width/-height. This options forces them to be the size set -by +fitting into thumb-width/-height. +This options forces them to be the size set by .Cm --thumb-width No and Cm --thumb-height . This will prevent any empty space in the final montage. . @@ -786,8 +1098,9 @@ without displaying it. .It Cm -s , --stretch . Normally, if an image is smaller than the specified thumbnail size, it will -not be enlarged. If this option is set, the image will be scaled up to fit -the thumbnail size. Aspect ratio will be maintained unless +not be enlarged. +If this option is set, the image will be scaled up to fit the thumbnail size. +Aspect ratio will be maintained unless .Cm --ignore-aspect is specified. . @@ -799,38 +1112,25 @@ Set thumbnail height. . Set thumbnail width. . -.It Cm -J , --thumb-redraw Ar n -. -Only relevant for -.Cm --thumbnails : -Redraw thumbnail window every -.Ar n -images. In -.Nm -<= 1.5, the thumbnail image used to be redrawn after every computed thumbnail -.Pq so, it updated immediately . -However, since the redrawing takes quite long -.Pq especially for thumbnail mode on a large filelist , -this turned out to be a major performance penalty. -As a workaround, the thumbnail image is redrawn every 10th image now by -default. Set -.Ar n No = 1 -to get the old behaviour, -.Ar n No = 0 -will only redraw once all thumbnails are loaded. -. .El . . .Sh INDEX AND THUMBNAIL MODE OPTIONS . +In addition to +.Sx MONTAGE MODE OPTIONS +.Cm --alpha , --bg , --limit-height , --limit-width , --output , --output-only , +.Cm --thumb-height , --thumb-width , +the following options can be used. +. .Bl -tag -width indent . .It Cm --index-info Ar format . Show image information based on .Ar format -below thumbnails in index / thumbnail mode. See +below thumbnails in index / thumbnail mode. +See .Sx FORMAT SPECIFIERS . May contain newlines. . @@ -846,7 +1146,8 @@ Note: If you specify image-related formats needs to load all images to calculate the dimensions of its own window. So when using them with many files, it will take a while before a .Nm -window becomes visible. Use +window becomes visible. +Use .Cm --preload to get a progress bar. . @@ -854,6 +1155,20 @@ to get a progress bar. . Set font to print a title on the index, if no font is specified, no title will be printed. +. +.It Cm -J , --thumb-redraw Ar n +. +Redraw thumbnail window every +.Ar n +images while generating thumbnails. +Redrawing takes quite long, so the default is 10. +Set +.Ar n No = 1 +to update the thumbnail window immediately. +With +.Ar n No = 0 , +there will only be one redraw once all thumbnails are loaded. +. .El . . @@ -861,89 +1176,98 @@ be printed. . In many desktop environments, .Nm -can also be used as a background setter. Unless you pass the +can also be used as a background setter. +Unless you pass the .Cm --no-fehbg option, it will write a script to set the current background to .Pa ~/.fehbg . So to have your background restored every time you start X, you can add -.Qq sh ~/.fehbg & +.Qq ~/.fehbg & to your X startup script .Pq such as Pa ~/.xinitrc . -As of -.Nm -2.13, this script is executable, so -.Qq ~/.fehbg & -will work as well. +Note that the commandline written to +.Pa ~/.fehbg +always includes the +.Cm --no-fehbg +option to ensure that it is not inadvertently changed by differences in +X11 screen layout or similar. . .Pp . Note that .Nm -does not support setting the wallpaper of GNOME shell desktops. In this -environment, you can use +does not support setting the wallpaper of GNOME shell desktops. +In this environment, you can use .Qq gsettings set org.gnome.desktop.background picture-uri file:/// Ns Ar path instead. . .Pp . -For the -.Cm --bg-center +For +.Cm --bg-center , --bg-fill , and -.Cm --bg-max -options, you can use the +.Cm --bg-max , +you can use .Cm --geometry -option to specify an offset from one side of the screen instead of -centering the image. Positive values will offset from the left/top -side, negative values from the bottom/right. +0 and -0 are both -valid and distinct values. +to specify an offset from one side of the monitor instead of centering the image. +Positive values will offset from the left/top side, negative values from the +bottom/right. ++0 and -0 are both valid and distinct values. . .Pp . Note that all options except .Cm --bg-tile support Xinerama. -For instance, if you have multiple screens connected and use e.g. +For instance, if you have multiple monitors connected and use e.g. .Cm --bg-center , .Nm -will center or appropriately offset the image on each screen. +will center or appropriately offset the image on each monitor. You may even specify more than one file, in that case, the first file is set -on screen 0, the second on screen 1, and so on. +on monitor 0, the second on monitor 1, and so on. +Use +.Cm xrandr --listmonitors +to determine how Xinerama monitor IDs map to screens / monitors in your setup. . .Pp . Use .Cm --no-xinerama -to treat the whole X display as one screen when setting wallpapers. You -may also use +to treat the whole X display as one monitor when setting wallpapers. +You may also use .Cm --xinerama-index to use .Nm -as a background setter for a specific screen. +as a background setter for a specific monitor. . .Bl -tag -width indent . .It Cm --bg-center . -Center the file on the background. If it is too small, it will be surrounded -by a black border +Center the file on the background. +If it is too small, it will be surrounded by a border as specified by +.Cm --image-bg . . .It Cm --bg-fill . Like .Cm --bg-scale , -but preserves aspect ratio by zooming the image until it fits. Either a -horizontal or a vertical part of the image will be cut off +but preserves aspect ratio by zooming the image until it fits. +Either a horizontal or a vertical part of the image will be cut off . .It Cm --bg-max . Like .Cm --bg-fill , -but scale the image to the maximum size that fits the screen with black borders on one side. +but scale the image to the maximum size that fits the screen with borders on one side. +The border color can be set using +.Cm --image-bg . . .It Cm --bg-scale . Fit the file into the background without repeating it, cutting off stuff or -using borders. But the aspect ratio is not preserved either +using borders. +But the aspect ratio is not preserved either . .It Cm --bg-tile . @@ -964,6 +1288,10 @@ file . .Bl -tag -width indent . +.It %a +. +Information about slideshow state (playing/paused) +. .It %f . Image path/filename @@ -973,6 +1301,10 @@ Image path/filename Escaped image path/filename .Pq for use in shell commands . +.It %g +. +w,h window dimensions in pixels (mnemonic: geometry) +. .It %h . Image height @@ -983,7 +1315,8 @@ Total number of files in filelist . .It %L . -Temporary copy of filelist. Multiple uses of %L within the same format string will return the same copy. +Temporary copy of filelist. +Multiple uses of %L within the same format string will return the same copy. . .It %m . @@ -1007,12 +1340,14 @@ Number of image pixels . .It \&%P . -Number of image pixels +Number of image pixels in human-readable format with k/M .Pq kilopixels / megapixels +suffix . .It %r . -Image rotation. A half right turn equals pi. +Image rotation. +A half right turn equals pi. . .It %s . @@ -1035,6 +1370,14 @@ Number of current file . Image width . +.\" .It %W +.\" . +.\" Window dimensions and offset as WxH+x+y +.\" .Pq X11 geometry format . +.\" Note that this is currently only properly updated when changing images; +.\" offsets for the first image after starting feh and after changing window +.\" geometry may be bogus. +. .It %v . .Nm @@ -1046,7 +1389,11 @@ Process ID . .It %z . -current image zoom +Current image zoom, rounded to two decimal places +. +.It %Z +. +Current image zoom, higher precision . .It %% . @@ -1077,7 +1424,7 @@ If the files are not found in that directory, it will also try All config files treat lines starting with a .Qq # character as comments. -Note that mid-line comments are not supported. +Comments at the end of a line are not supported. . . .Sh THEMES CONFIG SYNTAX @@ -1095,29 +1442,42 @@ is the name of the entry and .Ar options are the options which will be applied when the theme is used. . -Note that the options are not parsed by any shell. Therefore, filename expansion -.Po -.Qq *.jpg -and similar -.Pc -is not supported. Quoting with both single and double quotes works, though. +.Pp +. +Note that the option parser does not behave like a normal shell: filename +expansion and backslash escape sequences are not supported and passed to +feh's option parser as-is. +However, quoting of arguments is respected and can be used for arguments +with whitespace. +. +So, the sequence +.Qq --info Qq foo bar +works as intended +.Pq that is, it display the string Qq foo bar , +whereas the option string +.Qq --info foo\e bar +will only display +.Qq foo\e +and complain about the file bar not existing. +Please keep this in mind when writing theme files. . .Pp . -An example entry would be +An example entry is .Qq imagemap -rVq --thumb-width 40 --thumb-height 30 --index-info \&'%n\en\&%wx\&%h\&' . . .Pp . -You can use this theme in two ways. Either call +You can use this theme in two ways. +Either call .Qo .Nm -Timagemap *.jpg .Qc , or create a symbolic link to .Nm -with the name of the theme you want it to use. For the example above, -this would be +with the name of the theme you want it to use. +For the example above, this would be .Qo ln -s `which .Nm @@ -1131,6 +1491,9 @@ to use these options. . Note that you can split a theme over several lines by placing a backslash at the end of an unfinished line. +A single option-argument-pair must not span multiple lines. +A single line must not be longer than 1023 characters, but there's no upper +limit for the length of a theme. . .Pp . @@ -1184,9 +1547,9 @@ without any keys unbinds it (i.e. the default bindings are removed). . .Pp . -.Em Note : -Do not use the same keybinding for multiple actions. When binding an action -to a new key +.Em Note:\& +Do not use the same keybinding for multiple actions. +When binding an action to a new key .Pq or mouse button , make sure to unbind it from its previous action, if present. .Nm @@ -1210,8 +1573,20 @@ do not. . .Sh KEYS . -In an image window, the following keys may be used -.Pq The strings in Bo square brackets Bc are the config action names : +The following actions and default key bindings can be used in an image window. +.Pq The strings in Bo square brackets Bc are the config action names . +. +If +.Nm +is running inside a terminal and its standard input is not used for images or +filelists, key input from the terminal is also accepted. +However, terminal input support is currently limited to most alphanumeric +characters +.Pq 0-9 a-z A-Z and some more , +arrow keys, return and backspace. +The Alt +.Pq Mod1 +modifier is also supported. . .Bl -tag -width indent . @@ -1226,12 +1601,13 @@ Enable/Disable anti-aliasing . .It c Bq toggle_caption . -Caption entry mode. If +Caption entry mode. +If .Cm --caption-path -has been specified, then this enables caption editing. The caption at the -bottom of the screen will turn yellow and can be edited. Hit return to confirm -and save the caption, or escape to cancel editing. Note that you can insert -an actual newline into the caption using +has been specified, then this enables caption editing. +The caption at the bottom of the screen will turn yellow and can be edited. +Hit return to confirm and save the caption, or escape to cancel editing. +Note that you can insert an actual newline into the caption using .Aq Ctrl+return . . .It d Bq toggle_filenames @@ -1241,18 +1617,21 @@ Toggle filename display . .It e Bq toggle_exif . -.Pq only if compiled with exif=1 +.Pq optional feature, $MAN_EXIF$ in this build Toggle EXIF tag display . -.It f Bq save_filelist +.It f Bq toggle_fullscreen . -Save the current filelist as -.Qq feh_PID_ID_filelist +Toggle fullscreen +. +.It g Bq toggle_fixed_geometry +. +Enable/Disable automatic window resize when changing images. . .It h Bq toggle_pause . -Pause/Continue the slideshow. When it is paused, it will not automatically -change slides based on +Pause/Continue the slideshow. +When it is paused, it will not automatically change slides based on .Cm --slideshow-delay . . .It i Bq toggle_info @@ -1262,19 +1641,30 @@ Toggle info display . .It k Bq toggle_keep_vp . -Toggle zoom and viewport keeping. When enabled, +Toggle zoom and viewport keeping. +When enabled, .Nm will keep zoom and X, Y offset when switching images. . +.It L Bq save_filelist +. +Save the current filelist as +.Qq feh_PID_ID_filelist . +It is saved in the directory specified by +.Cm --output-dir , +if set, and in the current working directory otherwise. +. .It m Bq toggle_menu . -Show menu. Use the arrow keys and return to select items, +Show menu. +Use the arrow keys and return to select items, and .Aq escape to close the menu. . .It n , Ao space Ac , Ao Right Ac Bq next_img . -Show next image. Selects the next image in thumbnail mode. +Show next image. +Selects the next image in thumbnail mode. . .It o Bq toggle_pointer . @@ -1282,7 +1672,8 @@ Toggle pointer visibility . .It p , Ao BackSpace Ac , Ao Left Ac Bq prev_img . -Show previous image. Selects the previous image in thumbnail mode. +Show previous image. +Selects the previous image in thumbnail mode. . .It q , Ao Escape Ac Bq quit . @@ -1291,23 +1682,22 @@ Quit . .It r Bq reload_image . -Reload current image. Useful for webcams +Reload current image. +Useful for webcams . .It s Bq save_image . Save the current image as -.Qq feh_PID_ID_FILENAME -. -.It v Bq toggle_fullscreen -. -Toggle fullscreen +.Qq feh_PID_ID_FILENAME . +It is saved in the directory specified by +.Cm --output-dir , +if set, and in the current working directory otherwise. . .It w Bq size_to_image . Change window size to fit current image size .Pq plus/minus zoom, if set . -In scale-down and fixed-geometry mode, this also updates the window size -limits. +In scale-down and fixed-geometry mode, this also updates the window size limits. . .It x Bq close . @@ -1317,37 +1707,59 @@ Close current window . Jump to a random position in the current filelist . +.It Z Bq toggle_auto_zoom +. +Toggle auto-zoom. +. .It \&[, \&] Bq prev_dir, next_dir . Jump to the first image of the previous or next sequence of images sharing -a directory name in the current filelist. Use --sort dirname if you would -like to ensure that all images in a directory are grouped together. +a directory name in the current filelist. +Use --sort dirname if you would like to ensure that all images in a directory +are grouped together. . .It < , > Bq orient_3 , orient_1 . -In place editing - rotate the image 90 degrees (counter)clockwise. -The rotation is lossless, but may create artifacts in some image corners when -used with JPEG images. Rotating in the reverse direction will make them go -away. See +rotate the image 90 degrees (counter)clockwise. +. +.Pp +. +When +.Cm --edit +is used, this also rotates the image in the underlying file. +Rotation is lossless, but may create artifacts in some image corners when +used with JPEG images. +Rotating in the reverse direction will make them go away. +See .Xr jpegtran 1 for more about lossless JPEG rotation. . -.Em Note: +.Em Note:\& .Nm -assumes that this feature is used to normalize image orientation. For JPEG -images, it will unconditionally set the EXIF orientation tag to 1 +assumes that this feature is used to normalize image orientation. +For JPEG images, it will unconditionally set the EXIF orientation +tag to 1 .Pq Qq 0,0 is top left -after every rotation. See +after every rotation. +See .Xr jpegexiforient 1 for details on how to change this flag. . .It _ Bq flip . -In place editing - vertical flip +Vertically flip image. +When +.Cm --edit +is used, this also flips the image in the underlying file +.Pq see above . . .It | Bq mirror . -In place editing - horizontal flip +Horizontally flip image. +When +.Cm --edit +is used, this also flips the image in the underlying file +.Pq see above . . .It 0 .. 9 Bq action_0 .. action_9 . @@ -1406,8 +1818,8 @@ Scroll up .It Ao keypad Down Ac , Ao Ctrl+Down Ac Bq scroll_down . Scroll down. -Note that the scroll keys work without anti-aliasing for performance reasons, -hit the render key after scrolling to antialias the image. +Note that the scroll keys work without anti-aliasing for performance reasons; +hit the render key after scrolling to anti-alias the image. . .It Aq Alt+Left Bq scroll_left_page . @@ -1427,7 +1839,7 @@ Scroll down by one page . .It R, Ao keypad begin Ac Bq render . -Antialias the image. +Anti-alias the image. Opens the currently selected image in thumbnail mode. . .It Ao keypad + Ac , Ao Up Ac Bq zoom_in @@ -1498,8 +1910,8 @@ This works like the keys config file: the entries are of the form . Each .Ar binding -is a button number. It may optionally start with modifiers for things like -Control, in which case +is a button number. +It may optionally start with modifiers for things like Control, in which case .Ar binding looks like .Ar mod Ns No - Ns Ar button @@ -1507,7 +1919,7 @@ looks like . .Pp . -.Em Note : +.Em Note:\& Do not use the same button for multiple actions. .Nm does not check for conflicting bindings, so their behaviour is undefined. @@ -1536,6 +1948,13 @@ section can also be bound to a button. . Reload current image . +.It 0 Ao cursor movement while not panning, zooming, or similar Ac +. +Does not have a default binding. +By binding it to +.Cm quit , +you can turn feh into a simple screensaver. +. .It 1 Ao left mouse button Ac Bq pan . pan the current image @@ -1609,16 +2028,17 @@ will warp your cursor to the opposite border so you can continue panning. .Pp . When clicking the zoom button and immediately releasing it, the image will be -back at 100% zoom. When clicking it and moving the mouse while holding the -button down, the zoom will be continued at the previous zoom level. The zoom -will always happen so that the pixel on which you entered the zoom mode -remains stationary. So, to enlarge a specific part of an image, click the -zoom button on that part. +back at 100% zoom. +When clicking it and moving the mouse while holding the button down, the zoom +will be continued at the previous zoom level. +The zoom will always happen so that the pixel on which you entered the zoom mode +remains stationary. +So, to enlarge a specific part of an image, click the zoom button on that part. . . .Sh SIGNALS . -In slideshow mode, +In slideshow and multiwindow mode, .Nm handles the following signals: . @@ -1626,135 +2046,173 @@ handles the following signals: . .It Dv SIGUSR1 . -Switch to next image +Slideshow mode: switch to next image; +reload current image if the slideshow consists of a single file. +Multiwindow mode: reload all images. . .It Dv SIGUSR2 . -Switch to previous image +Slideshow mode: switch to previous image; +reload current image if the slideshow consists of a single file. +Multiwindow mode: reload all images. . .El . . .Sh USAGE EXAMPLES . -Here are some examples of useful option combinations. See also: -.Aq http://feh.finalrewind.org/examples/ +Here are some examples of useful option combinations. +See also: +.Aq https://feh.finalrewind.org/examples/ . .Bl -tag -width indent . -.It feh /opt/images +.It feh ~/Pictures . -Show all images in /opt/images +Show all images in ~/Pictures . -.It feh -r /opt/images +.It feh -r ~/Pictures . -Recursively show all images found in /opt/images and subdirectories +Recursively show all images found in ~/Pictures and subdirectories . -.It feh -rSfilename /opt/images +.It feh -rSfilename --version-sort ~/Pictures . -Same as above, but sort by filename. By default, feh will show files in the -order it finds them on the hard disk, which is usually somewhat random. +Same as above, but sort naturally. +By default, feh will show files in the string order of their names, meaning e.g. +.Qq foo 10.jpg +will come before +.Qq foo 2.jpg . +In this case, they are instead ordered as a human would expect. . -.It feh -t -Sfilename -E 128 -y 128 -W 1024 /opt/images +.It feh -t -Sfilename -E 128 -y 128 -W 1024 ~/Pictures . Show 128x128 pixel thumbnails, limit window width to 1024 pixels. . -.It feh -t -Sfilename -E 128 -y 128 -W 1024 -P -C /usr/share/fonts/truetype/ttf-dejavu/ -e DejaVuSans/8 /opt/images +.It feh -t -Sfilename -E 128 -y 128 -W 1024 -P -C /usr/share/fonts/truetype/ttf-dejavu/ -e DejaVuSans/8 ~/Pictures . -Same as above, but enable thumbnail caching in ~/.thumbnails and use a smaller -font. +Same as above, but enable thumbnail caching and use a smaller font. . -.It feh -irFarial/14 -O index.jpg /opt/images +.It feh -irFarial/14 -O index.jpg ~/Pictures . -Make an index print of /opt/images and all directories below it, using 14 point -Arial to write the image info under each thumbnail. Save the image as -index.jpg and don't display it, just exit. Note that this even works without -a running X server +Make an index print of ~/Pictures and all directories below it, using 14 point +Arial to write the image info under each thumbnail. +Save the image as index.jpg and don't display it, just exit. +Note that this even works without a running X server . -.It feh --unloadable -r /opt/images +.It feh --unloadable -r ~/Pictures . -Print all unloadable images in /opt/images, recursively +Print all unloadable images in ~/Pictures, recursively . .It feh -f by_width -S width --reverse --list \&. . Write a list of all images in the directory to by_width, sorted by width .Pq widest images first . -.It feh -w /opt/images/holidays +.It feh -w ~/Pictures/holidays . -Open each image in /opt/images/holidays in its own window +Open each image in ~/Pictures/holidays in its own window . -.It feh -FD5 -Sname /opt/images/presentation +.It feh -FD5 -Sname ~/Pictures/presentation . Show the images in .../presentation, sorted by name, in fullscreen, automatically change to the next image after 5 seconds . -.It feh -rSwidth -A Qo mv %F ~/images/\&%N Qc /opt/images +.It feh -rSwidth -A Qo mv %F ~/images/\&%N Qc ~/Pictures . -View all images in /opt/images and below, sorted by width, move an image to +View all images in ~/Pictures and below, sorted by width, move an image to ~/image/image_name when enter is pressed . -.It feh --start-at ./foo.jpg \&. +.It feh --start-at ~/Pictures/foo.jpg . -View all images in the current directory, starting with foo.jpg. All other -images are still in the slideshow and can be viewed normally +View all images in ~/Pictures, starting with foo.jpg. +All other images are still in the slideshow and can be viewed normally . -.It feh --start-at foo.jpg * +.It feh --start-at ~/Pictures/foo.jpg ~/Pictures . -Same as above +Same as above. . .It feh --info \&"exifgrep '\&(Model\&|DateTimeOriginal\&|FNumber\&|ISO\&|Flash\&)' %F \&| cut -d \&. -f 4-\&" \&. . Show some EXIF information, extracted by exifprobe/exifgrep . -.It feh --action 'rm %F' -rl --max-dim 1000x800 +.It feh --action 'rm %F' -rl --max-dimension 1000x800 . Recursively remove all images with dimensions below or equal to 1000x800 pixels from the current directory. . +.It feh -L '%w %h %f' \&| awk '{ if \&($1 > $2\&) { print $0 } }' \&| cut -d ' ' -f 3- \&| feh -f - +. +Show landscape pictures +.Pq image width greater than height +in the current directory. +. .El . . .Sh DEPENDENCIES . +When +.Cm --edit +is used, .Nm -requires the +needs the .Cm jpegtran and .Cm jpegexiforient binaries .Pq usually distributed in Qo libjpeg-progs Qc or similar -for lossless rotation. +for lossless JPEG rotation. . .Pp . -To view images from URLs such as http://, you need +To view images from URLs such as "http://", .Nm -compiled with libcurl support (enabled by default). See the -.Sx VERSION -section. +must be compiled with libcurl support. +It is $MAN_CURL$ in this build. . . -.Sh BUGS +.Sh KNOWN BUGS . +Imlib2 releases prior to 1.7.4 are unable to load gif, tiff, and webp images +if the filename does not end with gif, tiff, or webp, respectively. +Notably, this means that feh is unable to show gif, tiff, and webp images from +stdin or network URLs on systems using an Imlib2 version older than 1.7.4. +. +.Pp +. +Imlib2 releases 1.7.5+ automatically rotate images based on their EXIF tags. +When combined with the +.Cm --auto-rotate +option, this causes images to be rotated twice and end up in an incorrect orientation. +As a workaround, do not use +.Cm --auto-rotate +on systems with Imlib2 version 1.7.5 or later. .Pp . On systems with giflib 5.1.2, .Nm -may be unable to load gif images. For affected mips, mipsel and arm devices, -gif support is completely broken, while on x86 / x86_64 gifs can usually -only be loaded if they are the first image in the filelist. +may be unable to load gif images. +For affected mips, mipsel and arm devices, gif support is completely +broken, while on x86 / x86_64 gifs can usually only be loaded if they are +the first image in the filelist. This appears to be a bug in giflib, see .Aq https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=813729 -for details. Workaround: Use -.Cm --magick-timeout 5 +for details. +Workaround: Use +.Cm --conversion-timeout 5 .Pq or some other positive value to load gifs with imagemagick instead, or downgrade to giflib 5.1.1, or upgrade to giflib 5.1.4. . .Pp . +While loading images using libcurl, +.Nm +will not react to key or mouse actions. +. +.Pp +. Thumbnail mode is somewhat inefficient, and because of that not nearly as fast as it could be. . @@ -1764,40 +2222,28 @@ as it could be. does not take window decorations into account and may therefore make the window slightly too large. . -. .Ss REPORTING BUGS . If you find a bug, please report it to .Aq derf+feh@finalrewind.org or via -.Aq http://github.com/derf/feh/issues . -You are also welcome to direct any feh-related comments/questions/... to #feh -on irc.oftc.net. +.Aq https://github.com/derf/feh/issues . . .Pp . Please include the feh version .Aq the output of Qq feh --version , steps to reproduce the bug and, if necessary, images to reproduce it. -. -. -.Sh FUTURE PLANS -. -Plans for the following releases: -. -.Bl -bullet -compact -. -.It -Make zoom options more intuitive -. -.El +Note that +.Nm +is a hobby project, so bug reports may be addressed with significant delays. . . .Sh LICENSE . Copyright (C) 1999, 2000 by Paul Duncan. -Copyright (C) 1999, 2000 by Tom Gilbert (and various contributors). -Copyright (C) 2010-2016 by Daniel Friesel (and even more contributors). +Copyright (C) 1999, 2000 by Tom Gilbert and contributors. +Copyright (C) 2010-2025 by Birte Kristina Friesel and contributors. . .Pp . @@ -1819,14 +2265,15 @@ used. . THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL -THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER -IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. . .Pp . -Current developer: Daniel Friesel +Current developer: Birte Friesel .Aq derf@finalrewind.org . .Pp @@ -1838,5 +2285,5 @@ Tom Gilbert . .Pp . -See also: -http://feh.finalrewind.org +Website: +https://feh.finalrewind.org |