Krolyxon
Commit 09d2d73

Branches

Refs →

nsxivREADME.md

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