From 3bf78101a7e43057df563fe7a234b991e8de80d0 Mon Sep 17 00:00:00 2001
From: Daniel Friesel <derf@derf.homelinux.org>
Date: Sat, 21 Aug 2010 17:02:10 +0200
Subject: slight manpage reformatting, clean up examples

---
 man/feh.1 | 129 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 115 insertions(+), 14 deletions(-)

diff --git a/man/feh.1 b/man/feh.1
index ebb20f0..88fd49d 100644
--- a/man/feh.1
+++ b/man/feh.1
@@ -2,15 +2,18 @@
 .Dt FEH 1
 .Os
 .
+.
 .Sh NAME
 .Nm feh
 .Nd image viewer and cataloguer
 .
+.
 .Sh SYNOPSIS
 .Nm
 .Op Ar options
 .Ar files or directories ...
 .
+.
 .Sh DESCRIPTION
 .Nm
 is a mode-based image viewer.  It is especially aimed at commandline users who
@@ -24,6 +27,7 @@ supports filelists, various image sorting modes, image captions and more.
 Control happens via keyboard shortcuts; the mouse can also be used to control
 it, but is only required for very few actions.
 .
+.
 .Sh MODES
 .Nm
 is based on various modes, which are selected at startup by comandline
@@ -63,8 +67,10 @@ in the format you choose.
 can also list either all the loadable files in a filelist or all the
 unloadable files.  Useful for preening a directory.
 .
+.
 .Sh OPTIONS
 .Bl -tag -width indent
+.
 .It Cm -A , --action Ar action
 Specify a string as an action to perform on the image.  In slideshow or
 multiwindow modes, the action will be run when the enter key is pressed, in
@@ -78,32 +84,39 @@ 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.
+.
 .It Cm --action1 No .. Cm --action9
 Extra actions which can be set and triggered using the appropiate number key.
+.
 .It Cm -Z , --auto-zoom
 Zoom pictures to screen size in fullscreen
 .Pq affected by Cm --stretch No and Cm --ignore-aspect .
+.
 .It Cm --bg-center Ar file
 Set
 .Ar file
 as centered desktop background
+.
 .It Cm --bg-fill Ar file
 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.
+.
 .It Cm --bg-scale Ar file
 Set
 .Ar file
 as scaled desktop background.  This will fill the whole background with
 .Ar file ,
 but its aspect ratio will not be preserved.
+.
 .It Cm --bg-seamless Ar file
 Like
 .Cm --bg-tile ,
 but with blurry corners so that it is
 .Pq in some cases ;-)
 less obvious that the image is too small for the screen.
+.
 .It Cm --bg-tile Ar file
 Set
 .Ar file
@@ -119,15 +132,19 @@ So to have your background restored when you restart X, add the line
 to your X startup script
 .Pq e.g. Pa ~/.xinitrc .
 Note that you only need to do this for non E window managers.
+.
 .It Cm -x , --borderless
 Create borderless windows.
+.
 .It Cm -Q , --builtin
 Use builtin HTTP client to grab remote files instead of
 .Xr wget 1 .
+.
 .It Cm -P , --cache-thumbnails
 Enable (experimental) thumbnail caching in
 .Pa ~/.thumbnails .
 Only works with thumbnails <= 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
@@ -139,6 +156,7 @@ and viewing image
 .Qq images/foo.jpg ,
 the caption will be looked for in
 .Qq images/captions/foo.jpg.txt .
+.
 .It Cm -c , --collage
 Enable collage mode.  Collage mode is very similar to montage mode, except
 the images are distributed randomly.
@@ -146,18 +164,23 @@ When using collage mode, you should also specify
 .Cm --limit-width
 and
 .Cm --limit-height .
+.
 .It Cm -L , --customlist Ar format
 Use
 .Ar format
 .Pq printf-like string containing image info specifiers
 for list output.  See
 .Sx FORMAT SPECIFIERS .
+.
 .It Cm --cycle-once
 Exit feh 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 -d , --draw-filename
 Draw the filename at the top-left of the image.
+.
 .It Cm -f , --filelist Ar file
 This option is similar to the playlists used by music software.  If
 .Ar file
@@ -176,45 +199,58 @@ when
 .Nm
 exits.  You can add files to filelists by specifying them on the commandline
 when also specifying the list.
+.
 .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 .
+.
 .It Cm -C , --fontpath Ar path
 Specify
 .Ar path
 as extra directory in which to search for fonts; can be used multiple times to
 add multiple paths.
+.
 .It Cm -I , --fullindex
 Same as Index mode, but you also get image size and dimensions printed
 below each thumbnail.
+.
 .It Cm -F , --fullscreen
 Make the window fullscreen.
+.
 .It Cm -g , --geometry Ar width No x Ar height
 Limit (and don't change) the window size.  Takes an X-style geometry
 .Ar string
 like 640x480.
 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 -h , --help
 display help output and exit.
+.
 .It Cm --hide-pointer
 Hide the pointer
 .Pq useful for slideshows etc .
+.
 .It Cm -B , --image-bg Ar style
 Use style as background for transparent image parts and the like.
 Accepted values: white, black, default.
+.
 .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 thumbails, printing the image
 name beneath each thumbnail.  Index mode enables certain other options, see
 .Sx INDEX MODE OPTIONS .
+.
 .It Cm --index-dim Ar bool
 Toggle showing image dimensions in thumbnail/index mode.
+.
 .It Cm --index-name Ar bool
 Toggle showing the filename in thumbnail/index mode.
+.
 .It Cm --index-size Ar bool
 Toggle showing the filesize in thumbnail/index mode.
+.
 .It Cm -k , --keep-http
 When viewing files using HTTP,
 .Nm
@@ -225,83 +261,104 @@ They will be in
 with
 .Qq Nm
 in the name.
+.
 .It Cm -l , --list
 Don't display images.  Analyse them and display an
 .Xr ls 1 - No style
 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.
+.
 .It Cm -) , --menu-bg Ar file
 Use
 .Ar file
 as background image in menus.
+.
 .It Cm -M , --menu-font Ar font
 Use
 .Ar font
 .Pq truetype, with size, like Qq yudit/12
 as menu font.
+.
 .It Cm --menu-style Ar file
 Read
 .Ar file
 to determine menu style.
+.
 .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
 .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.
+.
 .It Cm --no-jump-on-resort
 Don't jump to the first image after resorting the filelist.
+.
 .It Cm -N , --no-menus
 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.
+.
 .It Cm --no-xinerama
 Disable Xinerama support.  Only makes sense when you have Xinerama support
 compiled in.
+.
 .It Cm -j , --output-dir Ar directory
 Save files to
 .Ar directory
 .Pq only useful with -k
+.
 .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.
+.
 .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.
+.
 .It Cm -z , --randomize
 When viewing multiple files in a slideshow, randomize the file list before
 displaying.
+.
 .It Cm -_ , --rcfile Ar file
 Use
 .Ar file
 to parse themes and options from, instead of the default
 .Pa ~/.fehrc , /etc/fehrc
 files.
+.
 .It Cm -r , --recursive
 Recursively expand any directories in the commandline arguments
 to the content of those directories, all the way down to the bottom level.
+.
 .It Cm -R , --reload Ar int
 Reload images after
 .Ar int
 seconds.  Mainly useful when viewing webcams via http.
+.
 .It Cm -n , --reverse
 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.
+.
 .It Cm -D , --slideshow-delay Ar float
 For slideshow mode, wait
 .Ar float
@@ -309,16 +366,19 @@ 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 feh 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.
+.
 .It Cm -| , --start-at Ar filename
 Start the filelist at
 .Ar filename .
 See
 .Sx USAGE EXAMPLES .
+.
 .It Cm -T , --theme Ar theme
 Load options from config file with name
 .Ar theme
@@ -326,28 +386,35 @@ Load options from config file with name
 .Sx CONFIG FILE SYNTAX
 for more info.  Note that options from the theme file always override
 commandline options.
+.
 .It Cm -t , --thumbnails
 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.
+.
 .It Cm -~ , --thumb-title Ar string
 Set
 .Ar title
 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
 .Sx FORMAT SPECIFIERS
+.
 .It Cm -u , --unloadable
 Don't display images.  Just print out their names if imlib2 can NOT
 successfully load them.
+.
 .It Cm -V , --verbose
 output useful information, progress bars, etc.
+.
 .It Cm -v , --version
 output version information and exit.
+.
 .It Cm --zoom Ar percent
 Zoom images by
 .Ar percent
@@ -357,48 +424,62 @@ zooming will be limited to the specified
 .Ar percent .
 .El
 .
+.
 .Sh BUTTON OPTIONS
 .Bl -tag -width indent
+.
 .It Cm -0 , --reload-button Ar int
 Set button to reload the image
 .Pq default: 0 .
+.
 .It Cm -1 , --pan-button Ar int
 Set button to pan the image
 .Pq hold button down and move mouse to move the image .
 When the mouse is not moved, advances to the next image in slideshow mode.
 .Pq default: 1 , usually the left button .
+.
 .It Cm -2 , --zoom-button Ar int
 Set button to enable zoom mode
 .Pq default: 2 , usually the middle button .
+.
 .It Cm -3 , --menu-button Ar int
 Set button to activate the menu.
 .Pq default: 3 , usually the right button .
+.
 .It Cm --menu-ctrl-mask
 Require CTRL+Button for menu activation.
+.
 .It Cm -4 , --prev-button Ar int
 Set button to switch to the previous image in slideshow mode
 .Pq default: 4 , usually Aq mousewheel up .
+.
 .It Cm -5 , --next-button Ar int
 Set button to switch to the next image in slideshow mode
 .Pq default: 5 , usually Aq mousewheel down .
+.
 .It Cm -8 , --rotate-button Ar int
 Use CTRL+Button to rotate the current image
 .Pq default : 2 .
+.
 .It Cm --no-rotate-ctrl-mask
 Don't require CTRL+Button for rotation - just use the button.
+.
 .It Cm -9 , --blur-button Ar int
 Use CTRL+Button for blurring
 .Pq default : 1 .
+.
 .It Cm --no-blur-ctrl-mask
 Don't require CTRL+Button for blurring - just use the button.
 .El
 .
 .Sh MONTAGE MODE OPTIONS
 .Bl -tag -width indent
+.
 .It Cm -a , --alpha Ar int
 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
 Use
 .Ar file
@@ -410,37 +491,46 @@ if no size restrictions were specified.  Alternatively, if
 is
 .Qq trans ,
 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
 .Cm --thumb-width No and Cm --thumb-height .
 This will prevent any empty space in the final montage.
+.
 .It Cm -H , --limit-height Ar pixels
 Limit the height of the montage.  These options can be used together to define
 the image size exactly, or separately.  If only one is specified, the other is
 calculated from the number of files specified and the size of the thumbnails.
 The default is to limit width to 800 pixels and calculate the height as
 necessary.
+.
 .It Cm -W , --limit-width Ar pixels
 Limit the width of the montage.
+.
 .It Cm -o , --output Ar file
 Save the created montage to
 .Ar file .
+.
 .It Cm -O , --output-only Ar file
 Just save the created montage to
 .Ar file
 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 thumnail size.  Aspect ratio will be maintained unles
 .Cm --ignore-aspect
 is specified.
+.
 .It Cm -E , --thumb-height Ar pixels
 Set thumbnail height.
+.
 .It Cm -y , --thumb-width Ar pixels
 Set thumbnail width.
+.
 .It Cm -J , --thumb-redraw Ar n
 Only relevant for
 .Cm --thumbnails :
@@ -463,6 +553,7 @@ will only redraw once all thumbnails are loaded.
 .
 .Sh INDEX MODE OPTIONS
 .Bl -tag -width indent
+.
 .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.
@@ -684,43 +775,53 @@ Switch to previous image
 .Sh USAGE EXAMPLES
 Here are some examples of useful option combinations
 .Bl -tag -width indent
+.
+.It feh /opt/images
+Show all images in /opt/images
+.
 .It feh -r /opt/images
-Recursively scan /opt/images and show all the images in a slideshow
-.It feh -rSname /opt/images
-Same, but sort by filename
-.It feh -m /opt/images/landscapes
-Create a montage from the images in /opt/images/landscapes
-.It feh -Xrm -W 400 --thumb-width 30 --thumb-height 20 landscapes
-Create a montage from the images in ./landscapes and all directories below it.
-Limit the width of the image to 400 and make the thumbnails 30x20, ignoring
-aspect ratio
+Recursively show all images found in /opt/images and subdirectories
+.
+.It feh -rSfilename /opt/images
+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.
+.
+.It feh -t -Sfilename -E 128 -y 128 -W 1024 /opt/images
+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
+Same as above, but enable thumbnail caching in ~/.thumbnails and use a smaller
+font.
+.
 .It feh -irFarial/14 -O index.jpg /opt/images
 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
-.It feh -LrSpixels /opt/images
-List the images in /opt/images and all directories below, sorted by pixel
-size, giving as much info as possible
-.It feh -kR30 http://example.org/webcam.jpg
-View a webcam, reloading every 30 seconds, saving the images in /tmp
+.
 .It feh --unloadable -r /opt/images
 Print all unloadable images in /opt/images, recursively
+.
 .It feh -w /opt/images/holidays
 Open each image in /opt/images/holidays in its own window
+.
 .It feh -FD5 -Sname /opt/images/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
 View all images in /opt/images 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
+.
 .It feh --start-at foo.jpg *
 Same as above
 .El
 .
+.
 .Sh DEPENDENCIES
 .Nm
 requires the
-- 
cgit v1.2.3