add a migration document (#507)

this should've been added ages ago back when `nsxiv` was first
released. but even now, there's still plently of people who
might be looking to migrate.

so add a simple MIGRATION.md which covers some of the
differences to be aware of when migrating.

this does not cover patches and `config.h` since any conflicts
in patches would be evident anyways.

ref: https://codeberg.org/nsxiv/nsxiv/issues/369
ref: https://codeberg.org/nsxiv/nsxiv/issues/506
ref: https://codeberg.org/nsxiv/nsxiv/issues/420

Reviewed-on: https://codeberg.org/nsxiv/nsxiv/pulls/507
Reviewed-by: eylles <eylles@noreply.codeberg.org>

2 files changed, 57 insertions, 2 deletions

diff --git a/README.md b/README.md
index e8ce9e9..6c97250 100644
--- a/README.md
+++ b/README.md
@@ -14,11 +14,13 @@ interface and adding simple, sensible features. nsxiv is free software licensed
 under GPL-2.0-or-later and aims to be easy to modify and customize.
 
 Please file a bug report if something does not work as documented or expected on
-[Codeberg] after making sure you are using the latest release. Contributions
-are welcome, see [CONTRIBUTING] to get started.
+[Codeberg] after making sure you are using the latest release. If you're looking
+to migrate from `sxiv`, see [MIGRATION]. Contributions are welcome, see
+[CONTRIBUTING] to get started.
 
 [Codeberg]: https://codeberg.org/nsxiv/nsxiv/issues/new
 [CONTRIBUTING]: etc/CONTRIBUTING.md#contribution-guideline
+[MIGRATION]: etc/MIGRATION.md
 
 
 Features
diff --git a/etc/MIGRATION.md b/etc/MIGRATION.md
new file mode 100644
index 0000000..db776e0
--- /dev/null
+++ b/etc/MIGRATION.md
@@ -0,0 +1,53 @@
+# Migrating from `sxiv`
+
+`nsxiv` is *mostly* a drop-in replacement for `sxiv`, but not fully.
+This document outlines some key differences to be aware of if you're migrating
+from `sxiv`.
+
+### Configuration directory
+
+`sxiv` looks for config files under the directory
+`${XDG_CONFIG_HOME:-${HOME}/.config}/sxiv`. E.g
+`~/.config/sxiv/exec/key-handler`.
+
+`nsxiv` uses the same logic to find the config dir but uses the name "nsxiv".
+E.g `~/.config/nsxiv/...`.
+
+The "exec" scripts such as `key-handler` and `image-info` in `nsxiv` has some
+more features, but all previous argument order are preserved. And so if you have
+any exec scripts, you can simply copy them over and they should just work.
+
+### Xresources
+
+The xresources config for `nsxiv` is under the "Nsxiv" namespace whereas `sxiv`
+uses the "Sxiv" namespace. Some of the variables are also different between
+`nsxiv` and `sxiv`, below is a table that shows the old and new names:
+
+| sxiv                | nsxiv                    |
+| :--                 | :--                      |
+| Sxiv.background     | Nsxiv.window.background  |
+| Sxiv.foreground     | Nsxiv.window.foreground  |
+| Sxiv.barBackground  | Nsxiv.bar.background     |
+| Sxiv.barForeground  | Nsxiv.bar.foreground     |
+| Sxiv.font           | Nsxiv.bar.font           |
+
+### Default window class
+
+The window class of `nsxiv` is set to "Nsxiv" by default (can be overwritten via
+`-N` flag). This usually shouldn't matter, unless you have scripts that search
+for "Sxiv" window class.
+
+### Thumbnail cache directory
+
+Similar to config dir, the thumbnail cache dir of `nsxiv` is under the "nsxiv"
+name instead of "sxiv". E.g `~/.cache/nsxiv`.
+
+The "caching structure" in `nsxiv` is the same as `sxiv`. Which means that you
+can simply rename the directory to `nsxiv`:
+
+```console
+$ mv  ~/.cache/sxiv  ~/.cache/nsxiv
+```
+
+If you want to have both `sxiv` and `nsxiv` installed at the same time, you can
+even use symlink to avoid duplicate cache.