Krolyxon
Commit 675db4b

Branches

Refs →

nsxivREADME.md

166 lines · 4.9 KB · Markdown

Raw Blame History Download
1![nsxiv](https://raw.githubusercontent.com/nsxiv/nsxiv/gh-pages/img/logo.png "nsxiv")
2
3**Neo (or New or Not) Simple (or Small or Suckless) X Image Viewer**
4--------------------------------------------------------------------
5
6nsxiv is a fork of now unmaintained [sxiv](https://github.com/muennich/sxiv)
7with the purpose of maintaining it and adding simple, sensible features.
8nsxiv is free software licensed under GPLv2 and aims to be easy to modify and customize.
9
10Please file a bug report if something does not work as documented or
11expected in *this* repository, after making sure you are using the latest
12release of nsxiv. Contributions are welcome, see
13[CONTRIBUTING.md](CONTRIBUTING.md#Contribution-Guideline) for details.
14
15
16Features
17--------
18
19* Basic image operations, e.g. zooming, panning, rotating
20* Customizable key and mouse button mappings (in *config.h*)
21* Thumbnail mode: grid of selectable previews of all images
22* Ability to cache thumbnails for fast re-loading
23* Basic support for multi-frame images
24* Play GIF animations
25* Display image information in status bar
26* Display image name/path in X title
27
28
29Screenshots
30-----------
31
32**Image mode: (Default colors)**
33
34![Image](https://raw.githubusercontent.com/nsxiv/nsxiv/gh-pages/img/image.png "Image mode")
35
36**Thumbnail mode: (Custom colors)**
37
38![Thumb](https://raw.githubusercontent.com/nsxiv/nsxiv/gh-pages/img/thumb.png "Thumb mode")
39
40
41Dependencies
42------------
43
44nsxiv requires the following software to be installed:
45
46 * Imlib2
47 * X11
48
49The following dependencies are optional.
50
51 * inotify : Used for auto-reloading images on change.
52 Disabled via `HAVE_INOTIFY=0`
53 * libXft, freetype2, fontconfig : Used for the status bar.
54 Disabled via `HAVE_LIBFONTS=0`
55 * giflib : Used for animated gif playback.
56 Disabled via `HAVE_LIBGIF=0`.
57 * libexif : Used for auto-orientation and exif thumbnails.
58 Disable via `HAVE_LIBEXIF=0`
59 * libwebp : Used for animated webp playback.
60 Disabled via `HAVE_LIBWEBP=0`.
61
62Please make sure to install the corresponding development packages in case that
63you want to build nsxiv on a distribution with separate runtime and development
64packages (e.g. \*-dev on Debian).
65
66
67Building
68--------
69
70nsxiv is built using the commands:
71
72 $ make
73
74You can pass `HAVE_X=0` to `make` to disable an optional dependency.
75For example:
76
77 $ make HAVE_LIBEXIF=0
78
79will disable `libexif` support. Alternatively they can be disabled via editing
80the `Makefile` directly. `OPT_DEP_DEFAULT=0` can be used to disable all
81optional dependencies.
82
83Installing nsxiv:
84
85 # make install
86
87Installing desktop entry:
88
89 # make install-desktop
90
91Installing icons:
92
93 # make install-icon
94
95Installing all of the above:
96
97 # make install-all
98
99Please note, that these requires root privileges.
100By default, nsxiv is installed using the prefix `/usr/local`, so the full path
101of the executable will be `/usr/local/bin/nsxiv`, the `.desktop` entry will be
102`/usr/local/share/applications/nsxiv.desktop` and the icon path will be
103`/usr/local/share/icons/hicolor/{size}/apps/nsxiv.png`.
104
105You can install nsxiv into a directory of your choice by changing this command to:
106
107 $ make PREFIX="/your/dir" install
108
109Example scripts are installed using `EGPREFIX` which defaults to
110`/usr/local/share/doc/nsxiv/examples`. You can change `EGPREFIX` the same way
111you can change `PREFIX` shown above.
112
113The build-time specific settings of nsxiv can be found in the file *config.h*.
114Please check and change them, so that they fit your needs.
115If the file *config.h* does not already exist, then you have to create it with
116the following command:
117
118 $ make config.h
119
120
121Usage
122-----
123
124Please see man page for information on how to use nsxiv. To do so, execute the
125following after the installation:
126
127 $ man nsxiv
128
129
130F.A.Q
131-----
132
133* Can I open remote urls with nsxiv? <br>
134Yes, see [nsxiv-url](https://github.com/nsxiv/nsxiv-extra/tree/master/scripts/nsxiv-url)
135
136* Can I open all the images in a directory? <br>
137Yes, see [nsxiv-rifle](https://github.com/nsxiv/nsxiv-extra/tree/master/scripts/nsxiv-rifle)
138
139* Can I set default arguments for nsxiv? <br>
140Yes, see [nsxiv-env](https://github.com/nsxiv/nsxiv-extra/tree/master/scripts/nsxiv-env)
141
142* Can I pipe images into nsxiv? <br>
143No, not yet. See [#32](https://github.com/nsxiv/nsxiv/issues/32)
144
145
146User patches
147------------
148
149Due to our limited [project scope](CONTRIBUTING.md#Project-Scope), certain features or
150customization cannot be merged into nsxiv mainline. Following the spirit of
151suckless software, we host the [nsxiv-extra](https://github.com/nsxiv/nsxiv-extra)
152repo where users are free to submit whatever patches or scripts they wish.
153
154Description on how to use or submit patches can be found on
155[nsxiv-extra's](https://github.com/nsxiv/nsxiv-extra) README.
156
157
158Download
159--------
160
161You can [browse](https://github.com/nsxiv/nsxiv) the source code repository
162on GitHub or get a copy using git with the following command:
163
164 $ git clone https://github.com/nsxiv/nsxiv.git
165
166You can view the changelog [here](CHANGELOG.md)