diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/Makefile | 1 | ||||
| -rw-r--r-- | man/feh.pre | 755 |
2 files changed, 469 insertions, 287 deletions
diff --git a/man/Makefile b/man/Makefile index 3be07e3..acf8629 100644 --- a/man/Makefile +++ b/man/Makefile @@ -13,6 +13,7 @@ all: ${TARGETS} -e 's/\$$MAN_DEBUG\$$/${MAN_DEBUG}/' \ -e 's/\$$MAN_EXIF\$$/${MAN_EXIF}/' \ -e 's/\$$MAN_INOTIFY\$$/${MAN_INOTIFY}/' \ + -e 's/\$$MAN_VERSCMP\$$/${MAN_VERSCMP}/' \ -e 's/\$$MAN_XINERAMA\$$/${MAN_XINERAMA}/' \ < ${@:.1=.pre} > $@ diff --git a/man/feh.pre b/man/feh.pre index b258b2b..e1ade10 100644 --- a/man/feh.pre +++ b/man/feh.pre @@ -13,7 +13,7 @@ . .Nm .Op Ar options -.Op Ar files No | Ar directories No | Ar URLs ... +.Op Ar files | Ar directories | Ar URLs ... . . .Sh VERSION @@ -24,7 +24,8 @@ $VERSION$ . .Pp . -Compile-time switches: libcurl support $MAN_CURL$, Xinerama support +Compile-time switches: libcurl support $MAN_CURL$, natural sorting support +$MAN_VERSCMP$, Xinerama support $MAN_XINERAMA$, builtin EXIF support $MAN_EXIF$, inotify support $MAN_INOTIFY$$MAN_DEBUG$ . @@ -32,9 +33,9 @@ $MAN_INOTIFY$$MAN_DEBUG$ .Sh DESCRIPTION . .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 +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 @@ -46,7 +47,8 @@ displays all files in the current directory. . .Nm supports filelists, various image sorting modes, image captions, HTTP and more. -Configurable keyboard and mouse shortcuts are used to control it. +It can be controlled by configurable keyboard and mouse shortcuts, terminal +input and signals. . .Pp . @@ -74,8 +76,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 @@ -86,14 +89,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, +filesize and pixel size, 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 @@ -104,35 +110,45 @@ 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. +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 +svg, xcf and otf. +If dcraw is available, +.Nm +also supports RAW files provided by cameras and will display the embedded +thumbnails. +Use +.Cm --conversion-timeout Ar num with a non-negative value to enable it. . . @@ -142,11 +158,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 . @@ -163,7 +181,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 @@ -171,10 +189,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. @@ -182,25 +202,22 @@ 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: +for details. +Example usage: .Qq feh -A Qo mv ~/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 only if compiled with inotify=1 -automatically reload shown image if file was changed -. .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 +Automatically rotate images based on EXIF data. +Does not alter the image files. . .It Cm -Z , --auto-zoom . @@ -210,19 +227,34 @@ 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 , @@ -233,22 +265,17 @@ the caption will be looked for in . 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 . @@ -265,7 +292,8 @@ on a semi-transparent background to improve their readability . .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 @@ -276,7 +304,8 @@ directory, one filename per line. 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. . @@ -288,7 +317,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 @@ -302,8 +332,9 @@ 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 +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 . . .It Cm -C , --fontpath Ar path @@ -331,7 +362,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. . @@ -342,7 +374,8 @@ Note that in this mode, large images will always be scaled down to fit the screen, .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. @@ -351,20 +384,22 @@ their dimensions. . 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 +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 +.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. +WM or manually is still possible. +After each resize, the resulting window size is used as the new size limit. . .It Cm -Y , --hide-pointer . @@ -373,16 +408,24 @@ 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. +Use +.Ar style +as background for transparent image parts and the like. +Accepted values: default, checks, or an XColor +.Pq eg. Qo black Qc or Qo #428bdd Qc . . -The default for windowed mode is checks, while fullscreen defaults to black. +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, 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 . @@ -391,8 +434,9 @@ and . 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 +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 @@ -415,8 +459,9 @@ 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. +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 . @@ -425,25 +470,27 @@ 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 +.It Cm --conversion-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 +seconds. +Negative values disable conversion altogether, zero causes .Nm -to try indefinitely. By default, magick support is disabled. +to try indefinitely. +By default, conversion is disabled. . .It Cm --max-dimension Ar width No x Ar height . @@ -471,15 +518,18 @@ 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-jump-on-resort . @@ -491,15 +541,50 @@ 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. +. +.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 . @@ -510,23 +595,27 @@ 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 . @@ -542,29 +631,32 @@ Useful to override theme options. . Reload filelist and current image after .Ar int -seconds. Useful for viewing HTTP webcams or frequently changing directories. +seconds. +Useful for viewing HTTP webcams or frequently changing directories. .Pq Note that the filelist reloading is still experimental. . .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. . .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. . @@ -587,7 +679,8 @@ Default: 20 . 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 @@ -596,15 +689,16 @@ 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 -necessary, causing a delay proportional to the number of images in the list. +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 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. +The mtime sort mode sorts images by most recently modified. +To sort by oldest first, reverse the filelist with --reverse. . .It Cm -| , --start-at Ar filename . @@ -615,12 +709,14 @@ Note that at the moment, .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, +path in the filelist. +So, if the file to be matched is passed via an absolute path in the filelist, .Ar filename -must be an absolute path. If the file is passed via a relative path, +must be an absolute path. +If the file is passed via a relative path, .Ar filename -must be an identical relative path. This is a known issue. +must be an identical relative path. +This is a known issue. See also .Sx USAGE EXAMPLES . . @@ -630,7 +726,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 commandline options always override theme options. The theme can also be set via the program name .Pq e.g. with symlinks , so by default @@ -646,8 +743,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 @@ -657,19 +754,21 @@ 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. . .It Cm -V , --verbose @@ -680,12 +779,23 @@ output useful information, progress bars, etc. . output version information and exit. . +.It Cm --version-sort +. +.Pq optional feature, $MAN_VERSCMP$ in this build +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 . +. .It Cm --xinerama-index Ar screen . +.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 screen. +May be useful in certain circumstances where the window manager places the feh +window on Xinerama screen A while .Nm assumes that it will be placed on screen B. . @@ -697,18 +807,20 @@ 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 +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 .Qq --xinerama-index 0 when setting the wallpaper. . -.It Cm --zoom Ar percent No | Cm max No | Cm fill +.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 . @@ -741,14 +853,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 , @@ -757,8 +870,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. . @@ -792,8 +905,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. . @@ -805,38 +919,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. . @@ -852,7 +953,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. . @@ -860,6 +962,26 @@ 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. +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 . . @@ -867,41 +989,37 @@ 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. . .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 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. . .Pp . @@ -919,8 +1037,8 @@ on screen 0, the second on screen 1, and so on. . 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 screen when setting wallpapers. +You may also use .Cm --xinerama-index to use .Nm @@ -930,26 +1048,30 @@ as a background setter for a specific screen. . .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 . @@ -979,6 +1101,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 @@ -989,7 +1115,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 . @@ -1013,12 +1140,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 . @@ -1052,7 +1181,11 @@ Process ID . .It %z . -current image zoom +Current image zoom, rounded to two decimal places +. +.It %Z +. +Current image zoom, higher precision . .It %% . @@ -1101,29 +1234,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 @@ -1190,9 +1336,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 @@ -1216,8 +1362,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 . @@ -1232,12 +1390,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 @@ -1247,7 +1406,7 @@ 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 @@ -1255,10 +1414,14 @@ Toggle EXIF tag display Save the current filelist as .Qq feh_PID_ID_filelist . +.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 @@ -1268,19 +1431,22 @@ 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 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, .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 . @@ -1288,7 +1454,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 . @@ -1297,7 +1464,8 @@ Quit . .It r Bq reload_image . -Reload current image. Useful for webcams +Reload current image. +Useful for webcams . .It s Bq save_image . @@ -1312,8 +1480,7 @@ Toggle fullscreen . 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 . @@ -1323,27 +1490,35 @@ 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 +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. . @@ -1504,8 +1679,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 @@ -1513,7 +1688,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. @@ -1615,11 +1790,12 @@ 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 @@ -1643,67 +1819,71 @@ Switch to previous image . .Sh USAGE EXAMPLES . -Here are some examples of useful option combinations. See also: +Here are some examples of useful option combinations. +See also: .Aq http://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 \&. . -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 the current directory, starting with foo.jpg. +All other images are still in the slideshow and can be viewed normally . .It feh --start-at foo.jpg * . @@ -1736,25 +1916,26 @@ for lossless rotation. . To view images from URLs such as http://, you need .Nm -compiled with libcurl support (enabled by default). See the +compiled with libcurl support (enabled by default). +See the .Sx VERSION section. . . .Sh BUGS . -.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. @@ -1770,7 +1951,6 @@ 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 @@ -1803,7 +1983,7 @@ Make zoom options more intuitive . 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) 2010-2018 by Daniel Friesel (and even more contributors). . .Pp . @@ -1825,10 +2005,11 @@ 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 . |