Krolyxon
Commit 3e17e46

Branches

Refs →

nsxivREADME.md

227 lines · 7.9 KB · Markdown

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