1 files changed, 79 insertions, 34 deletions
diff --git a/man/feh.pre b/man/feh.pre
index c2a4cd1..5290f79 100644
--- a/man/feh.pre
+++ b/man/feh.pre
@@ -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$$MAN_DEBUG$
 .
 .
@@ -194,7 +195,7 @@ Extra actions which can be set and triggered using the appropriate number key.
 .
 .It Cm --auto-rotate
 .
-.Pq only if compiled with exif=1
+.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
@@ -253,7 +254,7 @@ 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 .
@@ -378,10 +379,16 @@ 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
 .
@@ -450,6 +457,11 @@ of zero causes
 .Nm
 to try indefinitely. By default, magick support is disabled.
 .
+Note that feh may clutter
+.Pa /tmp
+with temporary files created by ImageMagick for each failed conversion attempt.
+This is a known bug.
+.
 .It Cm --max-dimension Ar width No x Ar height
 .
 Only show images with width <=
@@ -503,8 +515,8 @@ 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 -j , --output-dir Ar directory
 .
@@ -685,8 +697,18 @@ 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
@@ -1106,16 +1128,27 @@ 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
@@ -1260,7 +1293,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
@@ -1665,56 +1698,60 @@ Here are some examples of useful option combinations. See also:
 .
 .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.
 .
-.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
+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 \&.
@@ -1787,6 +1824,14 @@ as it could be.
 does not take window decorations into account and may therefore make the
 window slightly too large.
 .
+.Pp
+.
+When enabled,
+.Cm --magick-timeout
+may clutter
+.Pa /tmp
+with temporary files produced by ImageMagick. This happens whenever an image
+is not loaded due to the conversion taking longer than the specified timeout.
 .
 .Ss REPORTING BUGS
 .