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