Krolyxon
Commit 127abbe

Branches

Refs →

nsxivREADME.md

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