Krolyxon
Commit 0262988

Branches

Refs →

nsxivREADME.md

201 lines · 6.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?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
164User patches
165------------
166
167Due to our limited [project scope](CONTRIBUTING.md#Project-Scope), certain features or
168customization cannot be merged into nsxiv mainline. Following the spirit of
169suckless software, we host the [nsxiv-extra](https://github.com/nsxiv/nsxiv-extra)
170repo where users are free to submit whatever patches or scripts they wish.
171
172Description on how to use or submit patches can be found on
173[nsxiv-extra's](https://github.com/nsxiv/nsxiv-extra) README.
174
175
176Download
177--------
178
179You can [browse](https://github.com/nsxiv/nsxiv) the source code repository
180on GitHub or get a copy using git with the following command:
181
182 $ git clone https://github.com/nsxiv/nsxiv.git
183
184You can view the changelog [here](CHANGELOG.md)
185
186Related projects
187----------------
188
189If nsxiv isn't able to fit your needs, check out the image viewer section of
190[suckless rocks](https://suckless.org/rocks) to find other minimal image viewers
191to try out.
192
193Below are a couple other lesser known projects not listed in suckless rocks.
194
195* [MAGE](https://github.com/explosion-mental/mage) :
196 Aims to be a smaller/more-suckless version of sxiv.
197* [div](https://github.com/TAAPArthur/div) :
198 Minimal and extensive, aimed at C devs willing to build their own features.
199* [mpv-image-viewer](https://github.com/occivink/mpv-image-viewer) :
200 Lua script to turn mpv into an image viewer. Supports thumbnails via
201 [mpv-gallery-view](https://github.com/occivink/mpv-gallery-view).