Krolyxon
Commit fddad75

Branches

Refs →

nsxivREADME.md

231 lines · 8.1 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] to get started.
19
20[Codeberg]: https://codeberg.org/nsxiv/nsxiv/issues/new
21[CONTRIBUTING]: etc/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
161You may also view the man-page [online](https://nsxiv.codeberg.page/man/).
162However, note that the online man-page might not accurately represent your local
163copy.
164
165
166F.A.Q.
167------
168
169* Can I open remote urls with nsxiv? <br>
170Yes, see [nsxiv-url](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/scripts/nsxiv-url)
171
172* Can I open all the images in a directory? <br>
173Yes, see [nsxiv-rifle](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/scripts/nsxiv-rifle)
174
175* Can I set default arguments for nsxiv? <br>
176Yes, see [nsxiv-env](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/scripts/nsxiv-env)
177
178* Can I pipe images into nsxiv? <br>
179Yes, see [nsxiv-pipe](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/scripts/nsxiv-pipe)
180
181You may also wish to see the [known issues](https://codeberg.org/nsxiv/nsxiv/issues/242).
182
183
184Customization
185-------------
186
187The main method of customizing nsxiv is by setting values for the variables in *config.h*,
188or by using Xresources as explained in the manual. If these options are not sufficient,
189you may implement your own features by following
190[this guide](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/CUSTOMIZATION.md).
191
192Due to our limited [project scope](etc/CONTRIBUTING.md#project-scope), certain features or
193customization cannot be merged into nsxiv mainline. Following the spirit of suckless
194software, we host the [nsxiv-extra](https://codeberg.org/nsxiv/nsxiv-extra) repo where users
195are free to submit whatever patches or scripts they wish.
196
197If you think your custom features can be beneficial for the general user base and is within
198our project scope, please submit it as a pull request on this repository, then we *may*
199merge it to mainline.
200
201Description on how to use or submit patches can be found on
202nsxiv-extra's [README](https://codeberg.org/nsxiv/nsxiv-extra).
203
204
205Download
206--------
207
208You can [browse](https://codeberg.org/nsxiv/nsxiv) the source code repository
209on CodeBerg or get a copy using git with the following command:
210
211 $ git clone https://codeberg.org/nsxiv/nsxiv.git
212
213You can view the changelog [here](etc/CHANGELOG.md)
214
215
216Similar projects
217----------------
218
219If nsxiv isn't able to fit your needs, check out the image viewer section of
220**[suckless rocks](https://suckless.org/rocks)** to find other minimal image
221viewers to try out.
222
223Below are a couple other lesser known projects not listed in suckless rocks.
224
225* [MAGE](https://codeberg.org/explosion-mental/mage):
226 A smaller/more-suckless version of sxiv.
227* [div](https://codeberg.org/TAAPArthur/div):
228 Minimal and extensive, aimed at C devs willing to build their own features.
229* [mpv-image-viewer](https://github.com/occivink/mpv-image-viewer):
230 Lua script to turn mpv into an image viewer. Supports thumbnails via
231 [mpv-gallery-view](https://github.com/occivink/mpv-gallery-view).