Krolyxon
Commit ec5a51d

Branches

Refs →

nsxivREADME.md

214 lines · 7.3 KB · Markdown

Raw Blame History Download
1[![nsxiv](https://raw.githubusercontent.com/nsxiv/nsxiv/gh-pages/img/logo.png)](https://github.com/nsxiv/nsxiv)
2
3[![tags](https://img.shields.io/github/v/tag/nsxiv/nsxiv?style=flat-square)](https://github.com/nsxiv/nsxiv/tags)
4[![license](https://img.shields.io/badge/license-GPL--2.0-lightgreen?style=flat-square)](https://github.com/nsxiv/nsxiv/blob/master/LICENSE)
5[![loc](https://img.shields.io/tokei/lines/github/nsxiv/nsxiv?color=red&style=flat-square)](https://github.com/nsxiv/nsxiv)
6
7**Neo (or New or Not) Simple (or Small or Suckless) X Image Viewer**
8--------------------------------------------------------------------
9
10nsxiv is a fork of now unmaintained [sxiv](https://github.com/muennich/sxiv)
11with the purpose of being a drop-in replacement of sxiv, maintaining it and
12adding simple, sensible features. nsxiv is free software licensed under GPLv2
13and aims to be easy to modify and customize.
14
15Please file a bug report if something does not work as documented or
16expected in *this* repository, after making sure you are using the latest
17release of nsxiv. Contributions are welcome, see
18[CONTRIBUTING.md](CONTRIBUTING.md#Contribution-Guideline) for details.
19
20
21Features
22--------
23
24* Basic image operations, e.g. zooming, panning, rotating
25* Customizable key and mouse button mappings (in *config.h*)
26* Script-ability via `key-handler`
27* Thumbnail mode: grid of selectable previews of all images
28* Ability to cache thumbnails for fast re-loading
29* Basic support for animated/multi-frame images (GIF/WebP)
30* Display image information in status bar
31* Display image name/path in X title
32
33
34Screenshots
35-----------
36
37**Image mode: (Default colors)**
38
39![Image](https://raw.githubusercontent.com/nsxiv/nsxiv/gh-pages/img/image.png "Image mode")
40
41**Thumbnail mode: (Custom colors)**
42
43![Thumb](https://raw.githubusercontent.com/nsxiv/nsxiv/gh-pages/img/thumb.png "Thumb mode")
44
45
46Installing via package manager
47------------------------------
48
49nsxiv is available on the following distributions/repositories. If you don't see
50your distro listed here, either contact your distro's package maintainer or
51consider packaging it yourself and adding it to the respective community repo.
52
53[![Packaging status](https://repology.org/badge/vertical-allrepos/nsxiv.svg)](https://repology.org/project/nsxiv/versions)
54
55Repos not tracked by repology:
56
57* Fedora: Enable the copr repo via `dnf copr enable mamg22/nsxiv`.
58
59
60Dependencies
61------------
62
63nsxiv requires the following software to be installed:
64
65 * Imlib2
66 * X11
67
68The following dependencies are optional.
69
70 * inotify : Used for auto-reloading images on change.
71 Disabled via `HAVE_INOTIFY=0`
72 * libXft, freetype2, fontconfig : Used for the status bar.
73 Disabled via `HAVE_LIBFONTS=0`
74 * giflib : Used for animated gif playback.
75 Disabled via `HAVE_LIBGIF=0`.
76 * libexif : Used for auto-orientation and exif thumbnails.
77 Disable via `HAVE_LIBEXIF=0`
78 * libwebp : Used for animated webp playback.
79 (NOTE: animated webp also requires Imlib2 v1.7.5 or above)
80 Disabled via `HAVE_LIBWEBP=0`.
81
82Please make sure to install the corresponding development packages in case that
83you want to build nsxiv on a distribution with separate runtime and development
84packages (e.g. \*-dev on Debian).
85
86
87Building
88--------
89
90nsxiv is built using the commands:
91
92 $ make
93
94You can pass `HAVE_X=0` to `make` to disable an optional dependency.
95For example:
96
97 $ make HAVE_LIBEXIF=0
98
99will disable `libexif` support. Alternatively they can be disabled via editing
100the `Makefile` directly. `OPT_DEP_DEFAULT=0` can be used to disable all
101optional dependencies.
102
103Installing nsxiv:
104
105 # make install
106
107Installing desktop entry:
108
109 # make install-desktop
110
111Installing icons:
112
113 # make install-icon
114
115Installing all of the above:
116
117 # make install-all
118
119Please note, that these requires root privileges.
120By default, nsxiv is installed using the prefix `/usr/local`, so the full path
121of the executable will be `/usr/local/bin/nsxiv`, the `.desktop` entry will be
122`/usr/local/share/applications/nsxiv.desktop` and the icon path will be
123`/usr/local/share/icons/hicolor/{size}/apps/nsxiv.png`.
124
125You can install nsxiv into a directory of your choice by changing this command to:
126
127 $ make PREFIX="/your/dir" install
128
129Example scripts are installed using `EGPREFIX` which defaults to
130`/usr/local/share/doc/nsxiv/examples`. You can change `EGPREFIX` the same way
131you can change `PREFIX` shown above.
132
133The build-time specific settings of nsxiv can be found in the file *config.h*.
134Please check and change them, so that they fit your needs.
135If the file *config.h* does not already exist, then you have to create it with
136the following command:
137
138 $ make config.h
139
140
141Usage
142-----
143
144Please see man page for information on how to use nsxiv. To do so, execute the
145following after the installation:
146
147 $ man nsxiv
148
149
150F.A.Q
151-----
152
153* Can I open remote urls with nsxiv? <br>
154Yes, see [nsxiv-url](https://github.com/nsxiv/nsxiv-extra/tree/master/scripts/nsxiv-url)
155
156* Can I open all the images in a directory? <br>
157Yes, see [nsxiv-rifle](https://github.com/nsxiv/nsxiv-extra/tree/master/scripts/nsxiv-rifle)
158
159* Can I set default arguments for nsxiv? <br>
160Yes, see [nsxiv-env](https://github.com/nsxiv/nsxiv-extra/tree/master/scripts/nsxiv-env)
161
162* Can I pipe images into nsxiv? <br>
163Yes, see [nsxiv-pipe](https://github.com/nsxiv/nsxiv-extra/tree/master/scripts/nsxiv-pipe)
164
165You may also wish to see the [known issues](https://github.com/nsxiv/nsxiv/issues/242).
166
167
168Customization
169-------------
170
171The main method of customizing nsxiv is by setting values for the variables in *config.h*,
172or by using Xresources as explained in the manual. If these options are not sufficient,
173you may implement your own features by following
174[this guide](https://github.com/nsxiv/nsxiv-extra/blob/master/CUSTOMIZATION.md).
175
176Due to our limited [project scope](CONTRIBUTING.md#Project-Scope), certain features or
177customization cannot be merged into nsxiv mainline. Following the spirit of suckless
178software, we host the [nsxiv-extra](https://github.com/nsxiv/nsxiv-extra) repo where users
179are free to submit whatever patches or scripts they wish.
180
181If you think your custom features can be beneficial for the general user base and is within
182our project scope, please submit it as a pull request on this repository, then we *may*
183merge it to mainline.
184
185Description on how to use or submit patches can be found on
186nsxiv-extra's [README](https://github.com/nsxiv/nsxiv-extra).
187
188
189Download
190--------
191
192You can [browse](https://github.com/nsxiv/nsxiv) the source code repository
193on GitHub or get a copy using git with the following command:
194
195 $ git clone https://github.com/nsxiv/nsxiv.git
196
197You can view the changelog [here](CHANGELOG.md)
198
199Related projects
200----------------
201
202If nsxiv isn't able to fit your needs, check out the image viewer section of
203[suckless rocks](https://suckless.org/rocks) to find other minimal image viewers
204to try out.
205
206Below are a couple other lesser known projects not listed in suckless rocks.
207
208* [MAGE](https://github.com/explosion-mental/mage) :
209 A smaller/more-suckless version of sxiv.
210* [div](https://github.com/TAAPArthur/div) :
211 Minimal and extensive, aimed at C devs willing to build their own features.
212* [mpv-image-viewer](https://github.com/occivink/mpv-image-viewer) :
213 Lua script to turn mpv into an image viewer. Supports thumbnails via
214 [mpv-gallery-view](https://github.com/occivink/mpv-gallery-view).