Krolyxon
Commit e9a0096

Branches

Refs →

nsxivREADME.md

216 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* Customizable window 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
49<a href="https://repology.org/project/nsxiv/versions">
50 <img align="right" width="192" src="https://repology.org/badge/vertical-allrepos/nsxiv.svg">
51</a>
52
53nsxiv is available on the following distributions/repositories. If you don't see
54your distro listed here, either contact your distro's package maintainer or
55consider packaging it yourself and adding it to the respective community repo.
56
57Repos not tracked by repology:
58
59* Fedora: Enable the copr repo via `dnf copr enable mamg22/nsxiv`.
60
61
62Dependencies
63------------
64
65nsxiv requires the following software to be installed:
66
67 * Imlib2
68 * X11
69
70The following dependencies are optional.
71
72 * inotify : Used for auto-reloading images on change.
73 Disabled via `HAVE_INOTIFY=0`
74 * libXft, freetype2, fontconfig : Used for the status bar.
75 Disabled via `HAVE_LIBFONTS=0`
76 * giflib : Used for animated gif playback.
77 Disabled via `HAVE_LIBGIF=0`.
78 * libexif : Used for auto-orientation and exif thumbnails.
79 Disable via `HAVE_LIBEXIF=0`
80 * libwebp : Used for animated webp playback.
81 (NOTE: animated webp also requires Imlib2 v1.7.5 or above)
82 Disabled via `HAVE_LIBWEBP=0`.
83
84Please make sure to install the corresponding development packages in case that
85you want to build nsxiv on a distribution with separate runtime and development
86packages (e.g. \*-dev on Debian).
87
88
89Building
90--------
91
92nsxiv is built using the commands:
93
94 $ make
95
96You can pass `HAVE_X=0` to `make` to disable an optional dependency.
97For example:
98
99 $ make HAVE_LIBEXIF=0
100
101will disable `libexif` support. Alternatively they can be disabled via editing
102`config.mk`. `OPT_DEP_DEFAULT=0` can be used to disable all optional
103dependencies.
104
105Installing nsxiv:
106
107 # make install
108
109Installing desktop entry:
110
111 # make install-desktop
112
113Installing icons:
114
115 # make install-icon
116
117Installing all of the above:
118
119 # make install-all
120
121Please note, that these requires root privileges.
122By default, nsxiv is installed using the prefix `/usr/local`, so the full path
123of the executable will be `/usr/local/bin/nsxiv`, the `.desktop` entry will be
124`/usr/local/share/applications/nsxiv.desktop` and the icon path will be
125`/usr/local/share/icons/hicolor/{size}/apps/nsxiv.png`.
126
127You can install nsxiv into a directory of your choice by changing this command to:
128
129 $ make PREFIX="/your/dir" install
130
131Example scripts are installed using `EGPREFIX` which defaults to
132`/usr/local/share/doc/nsxiv/examples`. You can change `EGPREFIX` the same way
133you can change `PREFIX` shown above.
134
135The build-time specific settings of nsxiv can be found in the file *config.h*.
136Please check and change them, so that they fit your needs.
137If the file *config.h* does not already exist, then you have to create it with
138the following command:
139
140 $ make config.h
141
142
143Usage
144-----
145
146Please see man page for information on how to use nsxiv. To do so, execute the
147following after the installation:
148
149 $ man nsxiv
150
151
152F.A.Q
153-----
154
155* Can I open remote urls with nsxiv? <br>
156Yes, see [nsxiv-url](https://github.com/nsxiv/nsxiv-extra/tree/master/scripts/nsxiv-url)
157
158* Can I open all the images in a directory? <br>
159Yes, see [nsxiv-rifle](https://github.com/nsxiv/nsxiv-extra/tree/master/scripts/nsxiv-rifle)
160
161* Can I set default arguments for nsxiv? <br>
162Yes, see [nsxiv-env](https://github.com/nsxiv/nsxiv-extra/tree/master/scripts/nsxiv-env)
163
164* Can I pipe images into nsxiv? <br>
165Yes, see [nsxiv-pipe](https://github.com/nsxiv/nsxiv-extra/tree/master/scripts/nsxiv-pipe)
166
167You may also wish to see the [known issues](https://github.com/nsxiv/nsxiv/issues/242).
168
169
170Customization
171-------------
172
173The main method of customizing nsxiv is by setting values for the variables in *config.h*,
174or by using Xresources as explained in the manual. If these options are not sufficient,
175you may implement your own features by following
176[this guide](https://github.com/nsxiv/nsxiv-extra/blob/master/CUSTOMIZATION.md).
177
178Due to our limited [project scope](CONTRIBUTING.md#Project-Scope), certain features or
179customization cannot be merged into nsxiv mainline. Following the spirit of suckless
180software, we host the [nsxiv-extra](https://github.com/nsxiv/nsxiv-extra) repo where users
181are free to submit whatever patches or scripts they wish.
182
183If you think your custom features can be beneficial for the general user base and is within
184our project scope, please submit it as a pull request on this repository, then we *may*
185merge it to mainline.
186
187Description on how to use or submit patches can be found on
188nsxiv-extra's [README](https://github.com/nsxiv/nsxiv-extra).
189
190
191Download
192--------
193
194You can [browse](https://github.com/nsxiv/nsxiv) the source code repository
195on GitHub or get a copy using git with the following command:
196
197 $ git clone https://github.com/nsxiv/nsxiv.git
198
199You can view the changelog [here](CHANGELOG.md)
200
201Similar projects
202----------------
203
204If nsxiv isn't able to fit your needs, check out the image viewer section of
205**[suckless rocks](https://suckless.org/rocks)** to find other minimal image
206viewers to try out.
207
208Below are a couple other lesser known projects not listed in suckless rocks.
209
210* [MAGE](https://github.com/explosion-mental/mage) :
211 A smaller/more-suckless version of sxiv.
212* [div](https://github.com/TAAPArthur/div) :
213 Minimal and extensive, aimed at C devs willing to build their own features.
214* [mpv-image-viewer](https://github.com/occivink/mpv-image-viewer) :
215 Lua script to turn mpv into an image viewer. Supports thumbnails via
216 [mpv-gallery-view](https://github.com/occivink/mpv-gallery-view).