backport doc fixes

doc/README.md

@@ -4,7 +4,7 @@ thank you for finding this program! i hope it will be useful to you.
 
 input-modifier is a small utility that allows you to remap your devices, and/or assign actions to its buttons.
 
-please note that this documentation is a work in progress, and as such it is not complete.
+please note that this documentation is a work in progress, and as such it is not complete and may have flaws.
 
 - [basic usage](basic/README.md)
 - [advanced usage](advanced/README.md)

doc/advanced/1-mappings.md

@@ -0,0 +1,79 @@
+# mappings
+
+input-modifier is also capable of having multiple "mappings" for a profile, with the ability to switch them on the fly.
+
+## listing mappings
+
+to see mappings for a device, type, e.g.:
+
+```
+> listmaps <device>
+```
+
+at first the only mapping available is called "Default".
+
+## creating a mapping
+
+to create a new mapping, type something like:
+
+```
+> newmap <device> map2
+```
+
+(`map2` being the mapping's name)
+
+(note that mapping names can't have spaces)
+
+## copying a mapping
+
+if you want to copy a mapping, type something like:
+
+```
+> copymap <device> oldMap newMap
+```
+
+## deleting a mapping
+
+if you want to get rid of a mapping, you can do so:
+
+```
+> delmap <device> map2
+```
+
+but first make sure that's not the current mapping.
+
+## switching between mappings (using the command line)
+
+```
+> switchmap <device> map2
+```
+
+## binding a mapping to a key
+
+```
+> addaction <device> KEY_RIGHTMETA switchmap map2
+```
+
+## mapping shifting
+
+mapping shifting is an ability of input-modifier in where you hold a key to temporarily activate a mapping.
+
+```
+> addaction <device> KEY_RIGHTMETA shiftmap map2
+```
+
+## adding actions to a mapping without changing mappings
+
+yes, you can. as an example:
+
+```
+> addaction <device> @mapName KEY_LSHIFT macro macro1
+```
+
+(replace `@mapName` with the mapping's name preceded by an at symbol (`@`), for example, `@map2`)
+
+the commands `listactions`, `clearactions`, `delaction` and `listbinds` also have this feature:
+
+```
+> listbinds <device> @map2
+```

doc/advanced/README.md

@@ -2,5 +2,7 @@
 
 this covers advanced usage of input-modifier.
 
-1. [mappings](mappings.md)
-2. [macros](macros.md)
+1. [mappings](1-mappings.md)
+2. [macros](2-macros.md)
+
+TODO

doc/basic/installation.md → doc/basic/1-installation.md

@@ -6,6 +6,8 @@ install [input-modifier](https://aur.archlinux.org/packages/input-modifier/). fr
 
 # installation (universal installer)
 
+download the installer from [here](https://github.com/tildearrow/input-modifier/releases) (don't download the source code versions!).
+
 after downloading input-modifier, please follow these instructions for a proper install.
 
 ## extracting
@@ -14,7 +16,7 @@ input-modifier comes in a universal binary package, besides some distribution-sp
 
 input-modifier doesn't run as root, to allow for multi-user support in the future.
 
-to install input-modifier, first extract the installer. open a terminal, and type the following:
+to install input-modifier, first extract the installer. and type the following in a terminal:
 
 ```
 tar -xvf <RELEASE>
@@ -47,7 +49,7 @@ after this, you'll have to re-login before being able to use input-modifier, sin
 
 under special circumstances, a reboot may be necessary.
 
-after this, you're ready to go. see [startup](startup.md).
+after this, you're ready to go. see [startup](2-startup.md).
 
 ## what about an AppImage?
 

doc/basic/startup.md → doc/basic/2-startup.md

@@ -18,7 +18,7 @@ if you see the following:
 [info] done! running.
 ```
 
-then it means you've done everything correctly. let's move on to [devices](devices.md).
+then it means you've done everything correctly. let's move on to [devices](3-devices.md).
 
 ## but wait. what about autostart?
 

doc/basic/3-devices.md

@@ -0,0 +1,92 @@
+# devices
+
+after you've started the input-modifier daemon, you might be wondering how to control the program.
+
+this is done by using a little utility called `imod-cli`, which is a command-line interface to input-modifier.
+
+(don't worry, a GUI will come at some point)
+
+to open up the utility, type the following in a new terminal (because the terminal you used to start up input-modifier is now occupied):
+
+```
+imod-cli
+```
+
+if you've done this correctly, you should be at the input-modifier prompt:
+
+```
+>
+```
+
+now you can begin typing commands.
+
+## but what is better for me to do first?
+
+to list your devices. to do so, type the following at the prompt:
+
+```
+> listdevices
+```
+
+this will return something like:
+
+```
+0: Keyboard
+1: Mouse
+Ready.
+```
+
+the numbers at the left side are device indexes, which may change at any time (and as such discouraged to use in furthercoming commands).
+
+the names at the right side are your device's names, which you can use in the next commands.
+
+## enabling devices
+
+these devices are in the "disabled" state when they are first detected by input-modifier.
+this means keybindings, macros, or the like won't work.
+
+to enable a device, type the following:
+
+```
+> enable <device>
+```
+
+where `<device>` is your device's name. note that you don't have to type the full name, for convenience.
+
+as an example:
+
+```
+> enable Keyboard
+```
+
+enables the device "Keyboard". you may also type:
+
+```
+> enable key
+```
+
+and it will have an equivalent effect.
+
+to disable a device, in case you don't want it to do keybindings anymore, do:
+
+```
+> disable <device>
+```
+
+for example:
+
+```
+> disable keyboard
+```
+
+following is [keybinds](4-keybinds.md). the moment you've been waiting for.
+
+## device name notes
+
+if your device's name contains spaces, then typing the device's name with spaces won't work.
+
+however, you may still type only a portion of its name. as an example, if your device's called "Razer Ornata Chroma", you only have to type "ornata" or similar.
+
+```
+> enable ornata
+```

doc/basic/keybinds.md → doc/basic/4-keybinds.md

@@ -13,17 +13,19 @@ say you want to remap the tab key to the A key.
 to do that, type the following:
 
 ```
-> addaction keyboard KEY_TAB key KEY_A
+> addaction <device> KEY_TAB key KEY_A
 ```
 
+(replace `<device>` with your device's name; see [devices](3-devices.md) for notes)
+
 (if you're wondering what the key names are, see the following: [input-event-codes.h](https://github.com/torvalds/linux/blob/master/include/uapi/linux/input-event-codes.h))
 
 ## I am lost
 
 if you're unsure of a key's name, you can retrieve it by doing:
 
 ```
-> whichkey keyboard
+> whichkey <device>
 ```
 
 and then pressing the key in question.
@@ -33,9 +35,9 @@ and then pressing the key in question.
 yes, you can.
 
 ```
-> addaction keyboard KEY_TAB key KEY_LEFTCTRL
-> addaction keyboard KEY_TAB key KEY_LEFTALT
-> addaction keyboard KEY_TAB key KEY_ESC
+> addaction <device> KEY_TAB key KEY_LEFTCTRL
+> addaction <device> KEY_TAB key KEY_LEFTALT
+> addaction <device> KEY_TAB key KEY_ESC
 ```
 
 after doing this, you've just bound the tab key to Ctrl-Alt-Esc.
@@ -45,9 +47,11 @@ after doing this, you've just bound the tab key to Ctrl-Alt-Esc.
 say you want the side button in your mouse to do fast clicks.
 
 ```
-> addaction mouse BTN_SIDE turbo BTN_LEFT 0.04 0.04
+> addaction <device> BTN_SIDE turbo BTN_LEFT 0.04 0.04
 ```
 
+(replace `<device>` with your mouse's name)
+
 the first 0.04 is the press time, and the next one is the release time.
 all units in seconds.
 
@@ -56,15 +60,15 @@ all units in seconds.
 say you want to disable the Meta/Windows key. you may do so by typing the following:
 
 ```
-> addaction keyboard KEY_LEFTMETA disable
+> addaction <device> KEY_LEFTMETA disable
 ```
 
 ## finding out which keys are bound
 
 this command will do:
 
 ```
-> listbinds keyboard
+> listbinds <device>
 ```
 
 ## I made a mistake
@@ -74,21 +78,23 @@ if you made any mistakes you can delete an action.
 first find out the action index:
 
 ```
-> listactions keyboard KEY_TAB
+> listactions <device> KEY_TAB
 ```
 
 then delete the action, e.g.:
 
 ```
-> delaction keyboard KEY_TAB 2
+> delaction <device> KEY_TAB 2
 ```
 
+(`2` being the action index)
+
 ## resetting a key
 
 you can reset a key to its default state by typing:
 
 ```
-> clearactions keyboard KEY_TAB
+> clearactions <device> KEY_TAB
 ```
 
 ## the rest
@@ -97,4 +103,4 @@ there are more actions available, but they aren't listed here. once you hit the
 
 alternatively, check out the [addaction reference](../reference/command/addaction.md).
 
-now, let's look at [macros](macros.md).
+now, let's look at [macros](5-macros.md).

doc/basic/macros.md → doc/basic/5-macros.md

@@ -12,19 +12,21 @@ to create a macro, type:
 > newmacro macro1
 ```
 
+(`macro1` being the macro's name)
+
 (note that macro names can't have spaces)
 
 ## recording to a macro
 
 the easiest way to prepare a macro is to simply record to it. to do so:
 
 ```
-> recordmacro keyboard macro1
+> recordmacro <device> macro1
 ```
 
 (make sure you've created the macro first)
 
-this will begin recording from your keyboard.
+this will begin recording from your `<device>`. this means any keypresses in other devices won't be registered.
 
 to finish recording, press ESC.
 
@@ -33,7 +35,7 @@ to finish recording, press ESC.
 to assign your macro to a key (e.g. right control), do the following:
 
 ```
-> addaction keyboard KEY_RIGHTCTRL macro macro1
+> addaction <device> KEY_RIGHTCTRL macro macro1
 ```
 
 ## I made a mistake
@@ -106,4 +108,4 @@ then look at the action index you want to delete, and then type:
 
 (the ability to edit actions in-place is coming soon)
 
-next page is [profiles](profiles.md).
+next page is [profiles](6-profiles.md).