Krolyxon
Commit 79b8fef

Branches

Refs →

nsxivREADME.md

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