Doc refactoring > README.md and installation.md

README.md

@@ -2,74 +2,24 @@
 
 <h1 align="center">Input Remapper</h1>
 
+An easy to use tool to change the behaviour of your input devices.
+Supports `X11`, `Wayland`, key/button combinations, programmable macros,
+joysticks, wheels, triggers, keyboards, mouse-movements and much
+more. Maps any input to any other input.  This tool may also be helpful
+for those with repetitive strain issues.
+
 <p align="center">
-  An easy to use tool to change the behaviour of your input devices.<br/>
-  Supports X11, Wayland, combinations, programmable macros, joysticks, wheels,<br/>
-  triggers, keys, mouse-movements and more. Maps any input to any other input.
+<a href="readme/installation.md">Installation</a></br> 
+<a href="readme/usage.md">Usage</a> - 
+<a href="readme/macros.md">Macros</a> - 
+<a href="readme/development.md">Development</a> -
+<a href="readme/examples.md">Examples</a>
 </p>
 
-<p align="center"><a href="readme/usage.md">Usage</a> - <a href="readme/macros.md">Macros</a> - <a href="#installation">Installation</a> - <a href="readme/development.md">Development</a> - <a href="readme/examples.md">Examples</a></p>
-
 <p align="center"><img src="readme/pylint.svg"/> <img src="readme/coverage.svg"/></p>
 
-
 <p align="center">
   <img src="readme/screenshot.png" width="48%"/>
   &#160;
   <img src="readme/screenshot_2.png" width="48%"/>
 </p>
-
-## Installation
-
-##### Manjaro/Arch
-
-```bash
-yay -S input-remapper-git
-sudo systemctl restart input-remapper
-sudo systemctl enable input-remapper
-```
-
-##### Ubuntu/Debian
-
-Get a .deb file from the [release page](https://github.com/sezanzeb/input-remapper/releases)
-or install the latest changes via:
-
-```bash
-sudo apt install git python3-setuptools gettext
-git clone https://github.com/sezanzeb/input-remapper.git
-cd input-remapper && ./scripts/build.sh
-sudo apt install -f ./dist/input-remapper-2.0.0.deb
-```
-
-input-remapper is available in [Debian](https://tracker.debian.org/pkg/input-remapper)
-and [Ubuntu](https://packages.ubuntu.com/jammy/input-remapper)
-
-##### Manual
-
-Dependencies: `python3-evdev` ≥1.3.0, `gtksourceview4`, `python3-devel`, `python3-pydantic`, `python3-pydbus`
-
-Python packages need to be installed globally for the service to be able to import them. Don't use `--user`
-
-Conda can cause problems due to changed python paths and versions.
-
-If it doesn't seem to install, you can also try `sudo python3 setup.py install`
-
-```bash
-sudo pip install evdev -U  # If newest version not in distros repo
-sudo pip uninstall key-mapper  # In case the old package is still installed
-sudo pip install --no-binary :all: git+https://github.com/sezanzeb/input-remapper.git
-sudo systemctl enable input-remapper
-sudo systemctl restart input-remapper
-```
-
-## Migrating beta configs to version 2
-
-By default, Input Remapper will not migrate configurations from the beta.
-If you want to use those you will need to copy them manually.
-
-```bash
-rm ~/.config/input-remapper-2 -r
-cp ~/.config/input-remapper/beta_1.6.0-beta ~/.config/input-remapper-2 -r
-```
-
-Then start input-remapper

readme/installation.md

@@ -0,0 +1,107 @@
+# Installation
+
+Below are installation instructions for certain distributions as well as
+<a href="#manual-installation">Manual installation</a> instructions.
+
+We welcome contributors to maintain missing distributions.
+
+Please note that distributions may lag with the latest bug fixes.  To
+get the latest bug fixes, use the <a href="#manual-installation">Manual
+installation</a> method.
+
+## Manjaro/Arch
+
+```bash
+yay -S input-remapper-git
+sudo systemctl restart input-remapper
+sudo systemctl enable input-remapper
+```
+
+Please note that the above version may lag from the latest version.  See
+the <a href="#manual-installation">Manual installation</a> method to
+install the latest version.
+
+## Ubuntu/Debian
+
+To get the latest version, use the following method:
+
+```bash
+sudo apt install git python3-setuptools gettext
+git clone https://github.com/sezanzeb/input-remapper.git
+cd input-remapper && ./scripts/build.sh
+sudo apt install -f ./dist/input-remapper-2.0.0.deb
+```
+
+The next two methods may result in the installed version not having the
+latest bug fixes.
+
+### Install using a .deb file
+
+1. Download the `.deb` file from the
+[release page](https://github.com/sezanzeb/input-remapper/releases)
+2. Manually install it
+
+### Distribution repository
+
+input-remapper is available on [Debian](https://tracker.debian.org/pkg/input-remapper)
+and [Ubuntu](https://packages.ubuntu.com/jammy/input-remapper)
+distributions.  Use your package manager to install the software.
+
+## Manual installation
+
+Ensure that the following dependencies are met:
+
+- `python3-evdev` ≥1.3.0
+- `gtksourceview4`
+- `python3-devel`
+- `python3-pydantic`
+- `python3-pydbus`
+
+Python packages need to be installed globally for the service to be able
+to import them.  Do not use `--user`.
+
+`Conda` can cause problems due to changed python paths and versions.
+
+### Install method #1
+
+```bash
+sudo pip install evdev -U  # If newest version not in distros repo
+sudo pip uninstall key-mapper  # In case the old package is still installed
+sudo pip install --no-binary :all: git+https://github.com/sezanzeb/input-remapper.git
+sudo systemctl enable input-remapper
+sudo systemctl restart input-remapper
+```
+
+### Install method #2
+
+Use this installation method if the above method is problematic:
+
+```bash
+# Obtain the software:
+mkdir -p ~/src
+cd ~/src
+git clone https://github.com/sezanzeb/input-remapper.git
+
+# Install
+cd ~/src/input-remapper
+sudo python3 setup.py install
+```
+
+# Migrating beta configs to version 2
+
+<i><b>Warning:</b>  the following will remove any existing <b>new</b>
+configurations.</i>
+
+By default, input-remapper will not migrate configurations from the beta
+release.
+
+To manually migrate beta configurations, *before* creating any
+configurations, perform the following:
+
+```bash
+# Ignore whether the subdirectory exists ...
+rm -fr ~/.config/input-remapper-2
+cp -r ~/.config/input-remapper/beta_1.6.0-beta ~/.config/input-remapper-2
+```
+
+Once completed, start input-remapper.