diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/Makefile | 4 | ||||
| -rw-r--r-- | man/feh-cam.pre | 57 | ||||
| -rw-r--r-- | man/feh.pre | 1505 | ||||
| -rw-r--r-- | man/gen-cam-menu.pre | 33 |
4 files changed, 1097 insertions, 502 deletions
diff --git a/man/Makefile b/man/Makefile index 1927963..8fe2cbd 100644 --- a/man/Makefile +++ b/man/Makefile @@ -8,10 +8,12 @@ all: ${TARGETS} .pre.1: sed \ -e 's/\$$VERSION\$$/${VERSION}/g' \ - -e 's/\$$DATE\$$/'"$$(date '+%B %d, %Y')"/g \ + -e 's/\$$DATE\$$/${MAN_DATE}/g' \ -e 's/\$$MAN_CURL\$$/${MAN_CURL}/' \ -e 's/\$$MAN_DEBUG\$$/${MAN_DEBUG}/' \ -e 's/\$$MAN_EXIF\$$/${MAN_EXIF}/' \ + -e 's/\$$MAN_INOTIFY\$$/${MAN_INOTIFY}/' \ + -e 's/\$$MAN_MAGIC\$$/${MAN_MAGIC}/' \ -e 's/\$$MAN_XINERAMA\$$/${MAN_XINERAMA}/' \ < ${@:.1=.pre} > $@ diff --git a/man/feh-cam.pre b/man/feh-cam.pre deleted file mode 100644 index 4a02753..0000000 --- a/man/feh-cam.pre +++ /dev/null @@ -1,57 +0,0 @@ -.Dd $DATE$ -.Dt FEH-CAM 1 -.Os -. -.Sh NAME -.Nm feh-cam -.Nd utility for viewing live webcam images -.Sh SYNOPSIS -.Nm -.Op Ar options -.Ar keys -. -.Sh VERSION -This manual documents feh-cam, shipped with feh version $VERSION$ -. -.Sh DEPRECATION WARNING -. -This tool will be removed from the feh distribution by 2013. -. -.Pp -. -If you still use it, please contact me at -.Aq derf@finalrewind.org -. -.Sh DESCRIPTION -.Nm -is a perl wrapper for feh which simplifies viewing webcams using keyed -bookmarks. It helps manage viewing your favourite webcam sites with feh. -. -.Sh OPTIONS -.Bl -tag -width indent -.It Cm -a , --add Ar key url refresh -Add -.Ar url -as -.Ar key -to the bookmarks file; when viewing, reload it every -.Ar refresh -seconds -.It Cm -l , --list -List each url / key pair in the bookmarks file -.It Cm -f , --full-screen -Start feh in full-screen mode -.It Cm -k , --keep-images -Save each webcam image in the current directory -.It Cm -g , --geometry Ar width No x Ar height -Use window geometry -.Ar width No x Ar height -.It Cm -v , --verbose -Start feh in verbose mode -.El -. -.Sh FILES -The bookmarks are stored in -.Pa ~/.cam_bookmarks -.Sh SEE ALSO -.Xr feh 1 diff --git a/man/feh.pre b/man/feh.pre index fc45a3d..ca64d37 100644 --- a/man/feh.pre +++ b/man/feh.pre @@ -13,7 +13,8 @@ . .Nm .Op Ar options -.Ar files or directories or URLs ... +.Op Cm -- +.Op Ar files | Ar directories | Ar URLs ... . . .Sh VERSION @@ -24,38 +25,62 @@ $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. +.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 shortcuts are used to control it; the mouse is also -supported, but only required for very few actions. +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 . +Features include filelists, various image sorting modes, custom action scripts, +and image captions. +.Nm +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 -can also be used as wallpaper setter. +displays all files in the current directory. . .Pp . -A little note about EXIF support: The recommended way to display EXIF data is -using exiv2 / exifgrep via +EXIF tags are supported either using exiv2 / exifgrep via .Cm --info -.Pq see the Sx USAGE EXAMPLES No section . -However, if you compile feh with exif=1, you can also display it directly. +.Pq see the Sx USAGE EXAMPLES No section , +or as a builtin feature by compiling +.Nm +with exif=1. In this build of +.Nm , +builtin EXIF support is $MAN_EXIF$. . . .Sh MODES @@ -66,23 +91,30 @@ options. . .Pp . -Slideshow mode is the default. It opens one window and displays the first -image in it, the keyboard and mouse can be used to change slides -.Pq images . +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 -disk, the new filelist can then be saved to the disk and reopened at a later +disk, a changed filelist can also be saved to the disk and reopened at a later time. +An image can also be read from stdin via +.Qq feh - . . .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 @@ -93,48 +125,85 @@ 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. Outputs an -.Cm ls - No style -listing of the files in the filelist, including image info such as size, -pixels, type, etc. Customlist mode will display whatever image info you want, -in the format you choose. +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 +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. 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 and png. +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. . -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 . -For animated images, only the first frame is shown. +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. . +.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 . .Bl -tag -width indent . -.It Cm -A , --action Oo Ar flag Oc Ns Ar action +.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. +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 . @@ -143,23 +212,75 @@ If is .Qq \&; , .Nm -will reload the current image instead of switching to the next one after +will reload the current image instead of switching to the next one +.Pq slideshow mode +or closing the window +.Pq multiwindow mode +after executing the action. . +If +.Ar [ title ] +is specified +.Pq note the literal Qo \&[ Qc and Qo ] Qc , +.Cm --draw-actions +will display +.Ar title +instead of +.Ar action +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 +and makes sure that actions like +.Qq \&[ -L %F \&] && foo +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 examples. E.g. -.Qq feh -A "mv ~/images/%n" * . -In slideshow mode, the next image will be shown after running the action, in -multiwindow mode, the window will be closed. +for details. +Example usage: +.Qq feh -A Qo mv %F ~/images/%N Qc * . . -.It Cm --action1 No .. Cm --action9 +.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 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 . Zoom pictures to screen size in fullscreen / fixed geometry mode. @@ -168,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. . @@ -246,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 @@ -260,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 . @@ -271,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 . @@ -289,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. . @@ -297,24 +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. . -.It Cm -g , --geometry Oo Ar width No x Ar height Oc Op + Ar x No + Ar y +.Pp +. +When combined with +.Cm --thumbnails , +this option only affects images opened from the thumbnail overview. +The thumbnail list itself will still be windowed. . -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. +.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 . -Note that this option does not enforce the geometry, changing it by a tiling +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. +. +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 . @@ -323,79 +504,93 @@ Hide the pointer . .It Cm -B , --image-bg Ar style . -Use style as background for transparent image parts and the like. -Accepted values: checks (default), white, 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 -.Sx INDEX MODE OPTIONS +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 --index-info Ar format +.It Cm --info Oo Ar flag Oc Ns Ar command_line . -Show image information based on -.Ar format -below thumbnails in index / thumbnail mode. See +Execute +.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 . -May contain newlines. . -.Pp -. -Note: If you specify image-related formats -.Pq such as \&%w or \&%s , -.Nm -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 -.Cm --preload -to get a progress bar. +If +.Ar flag +is set to +.Qo ; Qc , +the output will not be displayed by default, but has to be enabled by the +toggle_info key. . -.It Cm --info Ar commandline +.It Cm --insecure . -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 -.Sx FORMAT SPECIFIERS . +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, .Nm normally deletes the local copies after viewing, or, if caching, on exit. -This option prevents this so that you get to keep the local copies. -They will be in -.Pa /tmp -with -.Qq Nm -in the name. +This option permanently stores them on disk, either in the directory +specified by +.Cm --output-dir , +or in the current working directory. +. +.It Cm --keep-zoom-vp +. +When switching images, keep zoom and viewport settings +.Pq zoom level and X, Y offsets . .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. +When combined with +.Cm --action , +the specified action will be run for each loadable image. . -.It Cm --magick-timeout Ar timeout +.It Cm --max-dimension Ar width No x Ar height . -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. +Only show images with width <= +.Ar width +and height <= +.Ar height . +If you only care about one parameter, set the other to 0 +.Pq or a negative value . . .It Cm -M , --menu-font Ar font . @@ -404,17 +599,42 @@ Use .Pq truetype, with size, like Qq yudit/12 as menu font. . +.It Cm --min-dimension Ar width No x Ar height +. +Only show images with width >= +.Ar width +and height >= +.Ar height . +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 . @@ -426,81 +646,159 @@ 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). . .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. +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 . -When not in fullscreen: Scale images to screen size if they are too big. +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. +. +This option is ignored when in fullscreen and thumbnail list mode. . .Pp . In tiling environments, this also causes the image to be centered in the window. . +.It Cm --scroll-step Ar count +. +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 reverse the +scroll direction. +See +.Sx KEYS CONFIG SYNTAX +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 @@ -509,17 +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, width, height, pixels, size, format. For sort -modes other than name or filename, a preload run will be necessary, -causing a delay proportional to the number of images in the list. +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 +. +.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 . +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 +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 . +.Sx USAGE EXAMPLES +for examples. +If +.Ar filename +is a remote URL and no files or filelists were specified, +.Nm +will show +.Ar filename +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 . @@ -527,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 @@ -541,29 +901,38 @@ theme. Same as Index mode, but the thumbnails are clickable image launchers. Note that .Cm --fullscreen -does not affect the thumbnail window. It does, however, work for the image -windows launched from thumbnail mode. +and +.Cm --scale-down +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 .Sx MONTAGE MODE OPTIONS . . .It Cm -~ , --thumb-title Ar string . 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 . @@ -573,11 +942,72 @@ output useful information, progress bars, etc. . output version information and exit. . -.It Cm --zoom Ar percent No | Cm max No | Cm fill +.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 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 monitor B. +. +.Pp +. +In background setting mode: When used with any option other than +.Cm --bg-tile : +Only set wallpaper on +.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. +. +.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 . @@ -593,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 . @@ -610,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 , @@ -626,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. . @@ -661,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. . @@ -674,94 +1112,162 @@ 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 MODE OPTIONS +.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 +.Sx FORMAT SPECIFIERS . +May contain newlines. +. +Use +.Qq --index-info '' +to display thumbnails without any info text +. +.Pp +. +Note: If you specify image-related formats +.Pq such as \&%w or \&%s , +.Nm +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 +.Cm --preload +to get a progress bar. +. .It Cm -@ , --title-font Ar font . 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 . . .Sh BACKGROUND SETTING . +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 store the command line necessary to set the background in -.Pa ~/.fehbg , -so to have your background restored every time you start X, you can add -.Qq eval $(cat ~/.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 ~/.fehbg & to your X startup script -.Pq like Pa ~/.xinitrc . +.Pq such as Pa ~/.xinitrc . +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 +.Qq gsettings set org.gnome.desktop.background picture-uri file:/// Ns Ar path +instead. +. +.Pp +. +For +.Cm --bg-center , --bg-fill , +and +.Cm --bg-max , +you can use +.Cm --geometry +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 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. +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 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 . @@ -782,6 +1288,10 @@ file . .Bl -tag -width indent . +.It %a +. +Information about slideshow state (playing/paused) +. .It %f . Image path/filename @@ -791,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 @@ -799,6 +1313,11 @@ Image height . 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. +. .It %m . Current mode @@ -821,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 . @@ -849,14 +1370,34 @@ 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 version . +.It \&%V +. +Process ID +. .It %z . -current image zoom +Current image zoom, rounded to two decimal places +. +.It %Z +. +Current image zoom, higher precision +. +.It %% +. +A literal % . .El . @@ -883,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 @@ -903,19 +1444,40 @@ are the options which will be applied when the theme is used. . .Pp . -An example entry would be -.Qq imagemap -rVq --thumb-width 40 --thumb-height 30 . +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 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 +.Qc , or create a symbolic link to .Nm -with the name of the theme you want it to use. So from the example above: +with the name of the theme you want it to use. +For the example above, this would be .Qo ln -s `which .Nm @@ -928,11 +1490,14 @@ to use these options. .Pp . Note that you can split a theme over several lines by placing a backslash at -the end of a line, like in the shell. +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 . -You can combine these themes with commandline options. +Command line options always override theme options. . . .Sh KEYS CONFIG SYNTAX @@ -982,27 +1547,46 @@ without any keys unbinds it (i.e. the default bindings are removed). . .Pp . -.Em Note : +.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 does not check for conflicting bindings, so their behaviour is undefined. . -Either unbind the unwanted action, or bind it to another unused key. -. -The order in which you bind / unbind does not matter, though. -. .Pp . For a list of the .Ar action names, see .Sx KEYS . +Note that not all of the key names used there correspond to X11 keysyms. +Most notably, page up +.Pq Prior / Page_Up , +page down +.Pq Next / Page_Down +and the keypad keys +.Pq KP_* +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 . @@ -1017,32 +1601,37 @@ 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 -.Aq CTRL+return . +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 +. +Toggle filename display +.Pq see Cm --draw-filename . .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 d Bq toggle_filenames +.It f Bq toggle_fullscreen . -Toggle filename display -.Pq see Cm --draw-filename +Toggle fullscreen . -.It f Bq save_filelist +.It g Bq toggle_fixed_geometry . -Save the current filelist to a unique filename +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 @@ -1050,23 +1639,41 @@ change slides based on Toggle info display .Pq see Cm --info . +.It k Bq toggle_keep_vp +. +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 +.It n , Ao space Ac , Ao Right Ac Bq next_img . -Show next image +Show next image. +Selects the next image in thumbnail mode. . .It o Bq toggle_pointer . Toggle pointer visibility . -.It p , Ao Backspace Ac , Ao Left Ac Bq prev_img +.It p , Ao BackSpace Ac , Ao Left Ac Bq prev_img . -Show previous image +Show previous image. +Selects the previous image in thumbnail mode. . .It q , Ao Escape Ac Bq quit . @@ -1075,19 +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 to a unique filename -. -.It v Bq toggle_fullscreen -. -Toggle fullscreen +Save the current image as +.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. . .It x Bq close . @@ -1097,35 +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. +. .It < , > Bq orient_3 , orient_1 . -In place editing - rotate the images 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: -jpegtran does not update EXIF orientation tags. However, +.Em Note:\& .Nm -assumes that you use the feature to normalize image orientation and want it to -be displayed this way everywhere. After every rotation, it will unconditionally -set the EXIF orientation to 1 -.Pq Qq 0,0 is top left . -Should you need to reverse this, see -.Xr jpegexiforient 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 +.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. -Again, see -.Xr jpegtran 1 -for more information. +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 . @@ -1137,11 +1771,11 @@ Execute the corresponding action Run the command defined by .Cm --action . -.It Ao home Ac Bq jump_first +.It Ao Home Ac Bq jump_first . Show first image . -.It Ao end Ac Bq jump_last +.It Ao End Ac Bq jump_last . Show last image . @@ -1161,19 +1795,19 @@ Increase reload delay by 1 second . Decrease reload delay by 1 second . -.It Ao delete Ac Bq remove +.It Ao Delete Ac Bq remove . Remove current file from filelist . -.It Ao CTRL+delete Ac Bq delete +.It Ao Ctrl+Delete Ac Bq delete . Remove current file from filelist and delete it . -.It Ao keypad left Ac , Ao Ctrl+Left Ac Bq scroll_left +.It Ao keypad Left Ac , Ao Ctrl+Left Ac Bq scroll_left . Scroll to the left . -.It Ao keypad right Ac , Ao Ctrl+Right Ac Bq scroll_right +.It Ao keypad Right Ac , Ao Ctrl+Right Ac Bq scroll_right . Scroll to the right . @@ -1181,11 +1815,11 @@ Scroll to the right . Scroll up . -.It Ao keypad down Ac , Ao Ctrl+Down Ac Bq scroll_down +.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 . @@ -1205,7 +1839,8 @@ 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 . @@ -1223,6 +1858,11 @@ Zoom to 100% . Zoom to fit the window size . +.It ! Bq zoom_fill +. +Zoom to fill the window size like +.Cm --bg-fill +. .El . .Ss MENU KEYS @@ -1253,7 +1893,7 @@ Highlight parent menu item . Highlight child menu item . -.It Ao Return Ac , Ao Space Ac Bq menu_select +.It Ao Return Ac , Ao space Ac Bq menu_select . Select highlighted menu item . @@ -1270,8 +1910,8 @@ This works like the keys config file: the entries are of the form . Each .Ar binding -is a button name. 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 @@ -1279,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. @@ -1297,14 +1937,24 @@ For the available modifiers, see .Ss BUTTONS . In an image window, the following buttons may be used -.Pq The strings in Bo square brackets Bc are the config action names : +.Pq The strings in Bo square brackets Bc are the config action names . +Additionally, all actions specified in the +.Sx KEYS +section can also be bound to a button. . .Bl -tag -width indent . -.It Bq reload +.It unbound Bq reload . 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 @@ -1313,15 +1963,15 @@ pan the current image . Zoom the current image . -.It 3 Ao right mouse button Ac Bq menu +.It 3 Ao right mouse button Ac Bq toggle_menu . Toggle menu . -.It 4 Ao mousewheel down Ac Bq prev +.It 4 Ao mousewheel down Ac Bq prev_img . Show previous image . -.It 5 Ao mousewheel up Ac Bq next +.It 5 Ao mousewheel up Ac Bq next_img . Show next image . @@ -1333,26 +1983,39 @@ Blur current image . Rotate current image . +.It unbound Bq zoom_in +. +Zoom in +. +.It unbound Bq zoom_out +. +Zoom out +. +. .El . . .Sh MOUSE ACTIONS . -When viewing an image, by default mouse button 1 pans -.Pq moves the image around +Default Bindings: +When viewing an image, mouse button 1 pans the image +.Pq moves it around or, when only clicked, moves to the next image -.Pq slideshow mode only ; -button 2 zooms +.Pq slideshow mode only . +Quick drags with less than 2px of movement per axis will be treated as clicks +to aid graphics tablet users. +. +Mouse button 2 zooms .Po click and drag left->right to zoom in, right->left to zoom out, click once to restore zoom to 100% -.Pc ; +.Pc and mouse button 3 opens the menu. . .Pp . -CTRL+Button 1 blurs or sharpens the image +Ctrl+Button 1 blurs or sharpens the image .Pq drag left to blur, right to sharpen ; -CTRL+Button 2 rotates the image around the center point. +Ctrl+Button 2 rotates the image around the center point. . .Pp . @@ -1365,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: . @@ -1382,141 +2046,170 @@ 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 . -.El -. -. -.Sh TILING WINDOW MANAGERS +.It feh --action 'rm %F' -rl --max-dimension 1000x800 . -.Nm -was created with a floating window layout in mind. However, as of 2.0.1, it -has limited support for tiling window managers. -. -.Pp +Recursively remove all images with dimensions below or equal to 1000x800 pixels +from the current directory. . -Specifically, the -.Cm --scale-down No and Cm --auto-zoom -options will detect a tiling environment and scale the image up / down to the -current window size. Unfortunately, this causes every image to be rendered -twice: First in a normal fashion, and then -.Pq after noticing that the window is being tiled -again with the correct zoom level. +.It feh -L '%w %h %f' \&| awk '{ if \&($1 > $2\&) { print $0 } }' \&| cut -d ' ' -f 3- \&| feh -f - . -.Pp +Show landscape pictures +.Pq image width greater than height +in the current directory. . -This is a known bug and will hopefully get fixed some time. For now, it can be -avoided by using -.Cm --geometry 500x500 Pq or any other geometry . -This will have the same behaviour as -.Cm --scale-down , -but without the flickering. +.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 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. +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 --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. . -.Sh BUGS +.Pp . -In a Xinerama setup, fullscreen mode only works properly on screen 0. Set -.Ev XINERAMA_SCREEN -to the correct screen number or toggle fullscreen off, then on as a workaround. +While loading images using libcurl, +.Nm +will not react to key or mouse actions. . .Pp . @@ -1529,39 +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 Tom Gilbert (and various contributors). -Copyright (C) 2010 by Daniel Friesel (and even more contributors). +Copyright (C) 1999, 2000 by Paul Duncan. +Copyright (C) 1999, 2000 by Tom Gilbert and contributors. +Copyright (C) 2010-2025 by Birte Kristina Friesel and contributors. . .Pp . @@ -1583,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 @@ -1602,5 +2285,5 @@ Tom Gilbert . .Pp . -See also: -http://feh.finalrewind.org +Website: +https://feh.finalrewind.org diff --git a/man/gen-cam-menu.pre b/man/gen-cam-menu.pre deleted file mode 100644 index 18064f1..0000000 --- a/man/gen-cam-menu.pre +++ /dev/null @@ -1,33 +0,0 @@ -.Dd $DATE$ -.Dt GEN-CAM-MENU 1 -.Os -. -.Sh NAME -.Nm gen-cam-menu -.Nd utility for updating Enlightenment user menus for feh-cam -.Sh SYNOPSIS -.Nm -. -.Sh VERSION -This manual documents gen-cam-menu, shipped with feh version $VERSION$ -. -.Sh DEPRECATION WARNING -. -This tool will be removed from the feh distribution by 2013. -. -.Pp -. -If you still use it, please contact me at -.Aq derf@finalrewind.org -. -.Sh DESCRIPTION -.Nm -is a shell script which creates Enlightenment user menu entries for the -bookmarks stored by -.Xr feh-cam 1 -in -.Pa ~/.enlightenment/ . -. -.Sh SEE ALSO -.Xr feh 1 , -.Xr feh-cam 1 |