Krolyxon
Commit 4c6d26b

Branches

Refs →

nsxivREADME.md

217 lines · 7.5 KB · Markdown

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