11558c9fcf
the short opt -t does not accept optional argument since it'd break short option chaining. e.g `nsxiv -tp` currently works as `nsxiv -t -p` but if `-t` accepted optional argument then it'd stop working since "p" will be interpreted as argument to `-t` instead of being a flag. ref: https://codeberg.org/nsxiv/nsxiv/issues/404
619 lines
13 KiB
Groff
619 lines
13 KiB
Groff
.TH NSXIV 1 nsxiv\-VERSION
|
|
.SH NAME
|
|
nsxiv \- Neo Simple X Image Viewer
|
|
.SH SYNOPSIS
|
|
.B nsxiv
|
|
.RB [ \-abcfhiopqrtvZ0 ]
|
|
.RB [ \-A
|
|
.IR FRAMERATE ]
|
|
.RB [ \-e
|
|
.IR WID ]
|
|
.RB [ \-G
|
|
.IR GAMMA ]
|
|
.RB [ \-g
|
|
.IR GEOMETRY ]
|
|
.RB [ \-N
|
|
.IR NAME ]
|
|
.RB [ \-n
|
|
.IR NUM ]
|
|
.RB [ \-S
|
|
.IR DELAY ]
|
|
.RB [ \-s
|
|
.IR MODE ]
|
|
.RB [ \-z
|
|
.IR ZOOM ]
|
|
.IR FILE ...
|
|
.SH DESCRIPTION
|
|
nsxiv is a simple image viewer for X.
|
|
.P
|
|
It has two modes of operation: image and thumbnail mode. The default is image
|
|
mode, in which only the current image is shown. In thumbnail mode a grid of
|
|
small previews is displayed, making it easy to choose an image to open.
|
|
.P
|
|
Please note, that the fullscreen mode requires an EWMH/NetWM-compliant window
|
|
manager.
|
|
.SH OPTIONS
|
|
.TP
|
|
.BI "\-A, \-\-framerate " FRAMERATE
|
|
Play animations with a constant frame rate set to
|
|
.IR FRAMERATE .
|
|
.TP
|
|
.B "\-a, \-\-animate"
|
|
Play animations of multi-frame images.
|
|
.TP
|
|
.B "\-b, \-\-no\-bar"
|
|
Do not show statusbar at the bottom of the window.
|
|
.TP
|
|
.B "\-c, \-\-clean\-cache"
|
|
Remove all orphaned cache files from the thumbnail cache directory and exit.
|
|
.TP
|
|
.BI "\-e, \-\-embed " WID
|
|
Embed nsxiv's window into window whose ID is
|
|
.IR WID .
|
|
.TP
|
|
.B "\-f, \-\-fullscreen"
|
|
Start in fullscreen mode.
|
|
.TP
|
|
.BI "\-G, \-\-gamma " GAMMA
|
|
Set image gamma to GAMMA (\-32..32).
|
|
.TP
|
|
.BI "\-g, \-\-geometry " GEOMETRY
|
|
Set window position and size. See section GEOMETRY SPECIFICATIONS of X(7) for
|
|
more information on GEOMETRY argument.
|
|
.TP
|
|
.B "\-h, \-\-help"
|
|
Print brief usage information to standard output and exit.
|
|
.TP
|
|
.B "\-i, \-\-stdin"
|
|
Read names of files to open from standard input. Also done if FILE is `-'.
|
|
.TP
|
|
.BI "\-N, \-\-class " NAME
|
|
Set the resource name (WM_CLASS) of nsxiv's X window to NAME.
|
|
.TP
|
|
.BI "\-n, \-\-start\-at " NUM
|
|
Start at picture number NUM.
|
|
.TP
|
|
.B "\-o, \-\-stdout"
|
|
Write list of all marked files to standard output when quitting. In combination
|
|
with
|
|
.B "\-i, \-\-stdin"
|
|
nsxiv can be used as a visual filter/pipe.
|
|
.TP
|
|
.B "\-p, \-\-private"
|
|
Enable private mode, in which nsxiv does not write any cache or temporary files.
|
|
.TP
|
|
.B "\-q, \-\-quiet"
|
|
Be quiet, and disable warnings to standard error stream.
|
|
.TP
|
|
.B "\-r, \-\-recursive"
|
|
Search the given directories recursively for images to view.
|
|
.TP
|
|
.BI "\-S, \-\-ss\-delay " DELAY
|
|
Start in slideshow mode. Set the delay between images to
|
|
.I DELAY
|
|
seconds.
|
|
.I DELAY
|
|
may be a floating-point number.
|
|
.TP
|
|
.BI "\-s, \-\-scale\-mode " MODE
|
|
Set scale mode according to MODE character. Supported modes are: [d]own,
|
|
[f]it, [F]ill, [w]idth, [h]eight.
|
|
.TP
|
|
.BR "\-t, \-\-thumbnail" [=no]
|
|
Start in thumbnail mode. The long option accepts an optional "no" to disable it.
|
|
.TP
|
|
.B "\-v, \-\-version"
|
|
Print version information to standard output and exit.
|
|
.TP
|
|
.B "\-Z, \-\-zoom\-100"
|
|
The same as `\-z 100'.
|
|
.TP
|
|
.BI "\-z, \-\-zoom " ZOOM
|
|
Set zoom level to ZOOM percent.
|
|
.TP
|
|
.B "\-0, \-\-null"
|
|
Use NULL-separator. With this option, output of \-o and file-list sent to the
|
|
key-handler and the input of \-i will be separated by a NULL character.
|
|
.TP
|
|
.BI "\-\-anti\-alias" [=no]
|
|
Enables anti-aliasing, when given
|
|
.I no
|
|
as an argument, disables it instead.
|
|
.TP
|
|
.BI "\-\-alpha\-layer" [=no]
|
|
Enables checkerboard background for alpha layer, when given
|
|
.I no
|
|
as an argument, disables it instead.
|
|
.TP
|
|
.BI "\-\-cache\-allow, \-\-cache\-deny " "CACHE\-PATHS"
|
|
List of directories to whitelist or blacklist for thumbnail caching.
|
|
See
|
|
.I "THUMBNAIL CACHING"
|
|
section for more information on the argument format.
|
|
These options are mutually exclusive, if they are specified more than once then
|
|
only the final one takes effect.
|
|
.SH KEYBOARD COMMANDS
|
|
.SS General
|
|
The following keyboard commands are available in both image and thumbnail modes:
|
|
.TP
|
|
.BR 0 \- 9
|
|
Prefix the next command with a number (denoted via
|
|
.IR count ).
|
|
.TP
|
|
.B q
|
|
Quit nsxiv.
|
|
.TP
|
|
.B Q
|
|
Quit nsxiv, but additionally print the current filename when \-o is active and
|
|
no files have been marked.
|
|
.TP
|
|
.B Return
|
|
Switch to thumbnail mode / open selected image in image mode.
|
|
.TP
|
|
.B f
|
|
Toggle fullscreen mode.
|
|
.TP
|
|
.B b
|
|
Toggle visibility of statusbar at the bottom of the window.
|
|
.TP
|
|
.B Ctrl-x
|
|
Send the next key to the external key-handler. See section EXTERNAL KEY HANDLER
|
|
for more information.
|
|
.TP
|
|
.B g
|
|
Go to the first image.
|
|
.TP
|
|
.B G
|
|
Go to the last image, or image number
|
|
.IR count .
|
|
.TP
|
|
.B r
|
|
Reload image.
|
|
.TP
|
|
.B D
|
|
Remove current image from file list and go to next image.
|
|
.TP
|
|
.BR Ctrl-h ", " Ctrl-Left
|
|
Scroll left one screen width.
|
|
.TP
|
|
.BR Ctrl-j ", " Ctrl-Down
|
|
Scroll down one screen height.
|
|
.TP
|
|
.BR Ctrl-k ", " Ctrl-Up
|
|
Scroll up one screen height.
|
|
.TP
|
|
.BR Ctrl-l ", " Ctrl-Right
|
|
Scroll right one screen width.
|
|
.TP
|
|
.BR +
|
|
Zoom in.
|
|
.TP
|
|
.B \-
|
|
Zoom out.
|
|
.TP
|
|
.B m
|
|
Mark/unmark the current image.
|
|
.TP
|
|
.B M
|
|
Mark/unmark all images starting from the last marked/unmarked image up to the
|
|
current one.
|
|
.TP
|
|
.B Ctrl-m
|
|
Reverse all image marks.
|
|
.TP
|
|
.B Ctrl-u
|
|
Remove all image marks.
|
|
.TP
|
|
.B N
|
|
Go
|
|
.I count
|
|
marked images forward.
|
|
.TP
|
|
.B P
|
|
Go
|
|
.I count
|
|
marked images backward.
|
|
.TP
|
|
.B {
|
|
Decrease gamma correction by
|
|
.I count
|
|
steps.
|
|
.TP
|
|
.B }
|
|
Increase gamma correction by
|
|
.I count
|
|
steps.
|
|
.TP
|
|
.B Ctrl-g
|
|
Reset gamma correction.
|
|
.TP
|
|
.B Ctrl-[
|
|
Decrease brightness correction by
|
|
.I count
|
|
steps.
|
|
.TP
|
|
.B Ctrl-]
|
|
Increase brightness correction by
|
|
.I count
|
|
steps.
|
|
.TP
|
|
.B (
|
|
Decrease contrast by
|
|
.I count
|
|
steps.
|
|
.TP
|
|
.B )
|
|
Increase contrast by
|
|
.I count
|
|
steps.
|
|
.SS Thumbnail mode
|
|
The following keyboard commands are only available in thumbnail mode:
|
|
.TP
|
|
.BR h ", " Left
|
|
Move selection left
|
|
.I count
|
|
times.
|
|
.TP
|
|
.BR j ", " Down
|
|
Move selection down
|
|
.I count
|
|
times.
|
|
.TP
|
|
.BR k ", " Up
|
|
Move selection up
|
|
.I count
|
|
times.
|
|
.TP
|
|
.BR l ", " Right
|
|
Move selection right
|
|
.I count
|
|
times.
|
|
.TP
|
|
.B R
|
|
Reload all thumbnails.
|
|
.SS Image mode
|
|
The following keyboard commands are only available in image mode:
|
|
.TP
|
|
Navigate image list:
|
|
.TP
|
|
.BR n ", " Space
|
|
Go
|
|
.I count
|
|
images forward.
|
|
.TP
|
|
.BR p ", " Backspace
|
|
Go
|
|
.I count
|
|
images backward.
|
|
.TP
|
|
.B [
|
|
Go
|
|
.I count
|
|
* 10 images backward.
|
|
.TP
|
|
.B ]
|
|
Go
|
|
.I count
|
|
* 10 images forward.
|
|
.TP
|
|
.B Ctrl-6
|
|
Go to the previously viewed image.
|
|
.TP
|
|
Handle multi-frame images:
|
|
.TP
|
|
.B Ctrl-n
|
|
Go
|
|
.I count
|
|
frames of a multi-frame image forward.
|
|
.TP
|
|
.B Ctrl-p
|
|
Go
|
|
.I count
|
|
frames of a multi-frame image backward.
|
|
.TP
|
|
.BR Ctrl-a ", " Ctrl-Space
|
|
Play/stop animations of multi-frame images.
|
|
.TP
|
|
Panning:
|
|
.TP
|
|
.BR h ", " Left
|
|
Scroll image 1/5 of window width or
|
|
.I count
|
|
pixels left.
|
|
.TP
|
|
.BR j ", " Down
|
|
Scroll image 1/5 of window height or
|
|
.I count
|
|
pixels down.
|
|
.TP
|
|
.BR k ", " Up
|
|
Scroll image 1/5 of window height or
|
|
.I count
|
|
pixels up.
|
|
.TP
|
|
.BR l ", " Right
|
|
Scroll image 1/5 of window width or
|
|
.I count
|
|
pixels right.
|
|
.TP
|
|
.B H
|
|
Scroll to left image edge.
|
|
.TP
|
|
.B J
|
|
Scroll to bottom image edge.
|
|
.TP
|
|
.B K
|
|
Scroll to top image edge.
|
|
.TP
|
|
.B L
|
|
Scroll to right image edge.
|
|
.TP
|
|
.B z
|
|
Scroll to image center.
|
|
.TP
|
|
Zooming:
|
|
.TP
|
|
.B =
|
|
Set zoom level to 100%, or
|
|
.IR count %.
|
|
.TP
|
|
.B w
|
|
Set zoom level to 100%, but fit large images into window.
|
|
.TP
|
|
.B W
|
|
Fit image to window.
|
|
.TP
|
|
.B F
|
|
Fill image to window.
|
|
.TP
|
|
.B e
|
|
Fit image to window width.
|
|
.TP
|
|
.B E
|
|
Fit image to window height.
|
|
.TP
|
|
Rotation:
|
|
.TP
|
|
.B <
|
|
Rotate image counter-clockwise by 90 degrees.
|
|
.TP
|
|
.B >
|
|
Rotate image clockwise by 90 degrees.
|
|
.TP
|
|
.B ?
|
|
Rotate image by 180 degrees.
|
|
.TP
|
|
Flipping:
|
|
.TP
|
|
.B |
|
|
Flip image horizontally.
|
|
.TP
|
|
.B _
|
|
Flip image vertically.
|
|
.TP
|
|
Miscellaneous:
|
|
.TP
|
|
.B a
|
|
Toggle anti-aliasing.
|
|
.TP
|
|
.B A
|
|
Toggle visibility of alpha-channel, i.e. image transparency.
|
|
.TP
|
|
.B s
|
|
Toggle slideshow mode and/or set the delay between images to
|
|
.I count
|
|
seconds.
|
|
.SH MOUSE COMMANDS
|
|
.SS Thumbnail mode
|
|
The following mouse mappings are available in thumbnail mode:
|
|
.TP
|
|
.B Button1
|
|
Select the image. Goes into image mode if double\-clicked.
|
|
.TP
|
|
.B Button3
|
|
Mark/unmark the image. Dragging while holding down Button3 will mark/unmark
|
|
multiple images.
|
|
.TP
|
|
.B Button4
|
|
Scroll up by one row.
|
|
.TP
|
|
.B Button5
|
|
Scroll down by one row.
|
|
.TP
|
|
.B Ctrl-Button4
|
|
Scroll up by one page.
|
|
.TP
|
|
.B Ctrl-Button5
|
|
Scroll down by one page.
|
|
.SS Image mode
|
|
The following mouse mappings are available in image mode:
|
|
.TP
|
|
.B Button1
|
|
Go to the next image if the mouse cursor is in the right part of the window or
|
|
to the previous image if it is in the left part.
|
|
.TP
|
|
.B Ctrl-Button1
|
|
Pan the image relative to the mouse cursor.
|
|
.TP
|
|
.B Button2
|
|
Pan the image according to the mouse cursor position in the window while
|
|
keeping this button pressed down.
|
|
.TP
|
|
.B Button3
|
|
Switch to thumbnail mode.
|
|
.TP
|
|
.B Button4
|
|
Zoom in.
|
|
.TP
|
|
.B Button5
|
|
Zoom out.
|
|
.SH CONFIGURATION
|
|
The following X resources are supported under "Nsxiv" (e.g.
|
|
.B Nsxiv.bar.font
|
|
):
|
|
.TP
|
|
.B window.background
|
|
Color of the window background
|
|
.TP
|
|
.B window.foreground
|
|
Color of the window foreground
|
|
.TP
|
|
.B bar.font
|
|
Name of Xft bar font
|
|
.TP
|
|
.B bar.background
|
|
Color of the bar background. Defaults to window.background
|
|
.TP
|
|
.B bar.foreground
|
|
Color of the bar foreground. Defaults to window.foreground
|
|
.TP
|
|
.B mark.foreground
|
|
Color of the mark foreground. Defaults to window.foreground
|
|
.TP
|
|
Please see xrdb(1) on how to change them.
|
|
.LP
|
|
An X resources entry with an empty value means the default
|
|
(defined in config.h) will be used.
|
|
.SH WINDOW TITLE
|
|
The window title can be replaced with the output of a user-provided script,
|
|
which is called by nsxiv whenever any of the relevant information changes.
|
|
The path of this script is
|
|
.I $XDG_CONFIG_HOME/nsxiv/exec/win-title
|
|
and the arguments given to it (where "Optional" arguments might be empty) are:
|
|
.IP $1 4
|
|
resolved absolute path of the current file
|
|
.IP $2 4
|
|
current file number
|
|
.IP $3 4
|
|
total file count
|
|
.IP $4 4
|
|
image width (Optional: Disabled on thumbnails mode)
|
|
.IP $5 4
|
|
image height (Optional: Disabled on thumbnails mode)
|
|
.IP $6 4
|
|
current zoom (Optional: Disabled on thumbnails mode)
|
|
.P
|
|
The term file is used rather than image as nsxiv does not precheck that the
|
|
input files are valid images. Total file count may be different from the actual
|
|
count of valid images.
|
|
.P
|
|
There is also an example script installed together with nsxiv as
|
|
.IR EGPREFIX/win-title .
|
|
.SH STATUS BAR
|
|
The information displayed on the left side of the status bar can be replaced
|
|
with the output of user-provided script.
|
|
.P
|
|
The script that is called by nsxiv whenever an image gets loaded is located at
|
|
.I $XDG_CONFIG_HOME/nsxiv/exec/image-info
|
|
and the arguments given to it are:
|
|
.IP $1 4
|
|
path to image file (as provided by the user)
|
|
.IP $2 4
|
|
image width
|
|
.IP $3 4
|
|
image height
|
|
.IP $4 4
|
|
fully resolved path to the image file
|
|
.P
|
|
In thumbnail mode, the script that is called is located at
|
|
.I $XDG_CONFIG_HOME/nsxiv/exec/thumb-info
|
|
and the arguments given to it are:
|
|
.IP $1 4
|
|
path to image file (as provided by the user)
|
|
.IP $2 4
|
|
empty
|
|
.IP $3 4
|
|
empty
|
|
.IP $4 4
|
|
fully resolved path to the image file
|
|
.P
|
|
There are also example scripts installed together with nsxiv as
|
|
.IR EGPREFIX/image-info
|
|
and
|
|
.IR EGPREFIX/thumb-info .
|
|
.SH EXTERNAL KEY HANDLER
|
|
Additional external keyboard commands can be defined using a handler program
|
|
located in
|
|
.IR $XDG_CONFIG_HOME/nsxiv/exec/key-handler .
|
|
The handler is invoked by pressing
|
|
.BR Ctrl-x .
|
|
The next key combo is passed as its first argument. Passed via stdin are the
|
|
images to act upon: all marked images, if in thumbnail mode and at least one
|
|
image has been marked, otherwise the current image. nsxiv(1) will block until
|
|
the handler terminates. It then checks which images have been modified and
|
|
reloads them.
|
|
|
|
By default nsxiv(1) will send one image per-line to stdin, however when using
|
|
\-0 the image list will be NULL separated and the environment variable
|
|
"$NSXIV_USING_NULL" will be set to 1.
|
|
|
|
The key combo argument has the following form: "[C-][M-][S-]KEY",
|
|
where C/M/S indicate Ctrl/Meta(Alt)/Shift modifier states and KEY is the X
|
|
keysym as listed in /usr/include/X11/keysymdef.h without the "XK_" prefix.
|
|
If KEY has an uppercase equivalent, S-KEY is resolved into it. For instance,
|
|
K replaces S-k and Scedilla replaces S-scedilla, but S-Delete is sent as-is.
|
|
|
|
There is also an example script installed together with nsxiv as
|
|
.IR EGPREFIX/key-handler .
|
|
.SH THUMBNAIL CACHING
|
|
nsxiv stores all thumbnails under
|
|
.IR $XDG_CACHE_HOME/nsxiv/ .
|
|
.P
|
|
Use the command line option
|
|
.I \-c
|
|
to remove all orphaned cache files. Additionally, run the following command
|
|
afterwards inside the cache directory to remove empty subdirectories:
|
|
.P
|
|
.RS
|
|
find . \-depth \-type d \-empty ! \-name '.' \-exec rmdir {} \\;
|
|
.RE
|
|
.P
|
|
The option
|
|
.BR "\-\-cache\-allow " or " \-\-cache\-deny"
|
|
may be used to whitelists or blacklist certain directories from being cached.
|
|
The argument is a
|
|
.B :
|
|
separated list of paths. A
|
|
.B *
|
|
at the beginning of the path indicates that path should be matched recursively.
|
|
.P
|
|
For example:
|
|
.B \-\-cache\-allow \(dq/user/pictures:*/media/pictures\(dq
|
|
whitelists \(dq/user/pictures\(dq directory non-recursively and \(dq/media/pictures\(dq
|
|
directory recursively. Nothing outside these two directories will be cached.
|
|
And
|
|
.B \-\-cache\-deny \(dq*/secret\(dq
|
|
will enable blacklist mode and will not cache anything inside \(dq/secret\(dq
|
|
or it's subdirectories.
|
|
.SH ORIGINAL AUTHOR
|
|
.EX
|
|
Bert Muennich <ber.t at posteo.de>
|
|
.EE
|
|
.SH CURRENT MAINTAINERS
|
|
.EX
|
|
NRK <nrk at disroot.org>
|
|
Berke Kocaoğlu <berke.kocaoglu at metu.edu.tr>
|
|
TAAPArthur <taaparthur at gmail.com>
|
|
eylles <ed.ylles1997 at gmail.com>
|
|
Stein Gunnar Bakkeby <bakkeby at gmail.com>
|
|
explosion-mental <explosion0mental at gmail.com>
|
|
.EE
|
|
.SH CONTRIBUTORS
|
|
.EX
|
|
For a list of contributors, run `git shortlog -s` in the nsxiv git repository.
|
|
.EE
|
|
.SH HOMEPAGE
|
|
.TP
|
|
Website:
|
|
.EE
|
|
https://nsxiv.codeberg.page/
|
|
.EX
|
|
.TP
|
|
Source code:
|
|
.EE
|
|
https://codeberg.org/nsxiv/nsxiv
|
|
.EX
|
|
.SH SEE ALSO
|
|
.BR X (7),
|
|
.BR xrdb (1)
|