tildearrow / input-modifier

uinput based key bindings and macros tool for Linux
GNU General Public License v2.0
20 stars 6 forks source link

Documentation suggestion #2

Closed TherinS closed 5 years ago

TherinS commented 5 years ago

Two things that you may wish to modify in the documentation:

Firstly, In the "devices" documentation, under the "enabling devices", consider adding to the example:

enable keyboard

add the following

enable 0: (the index number of the keyboard the "listdevices" command returned)

In every instance of the documentation up to the "macro" section, I was able to interact with my Nostromo n52 using the index number of the device. However, I noticed the index number changed if I started imodd and imod-cli , then plugged in the device, as opposed to starting imodd / imod-cli with the Nostromo plugged in.

This indicates that the index number may change for a device between reboots, I think. is there a way to ensure that the index number does not change? It would be easy for me to write a Zenity dialog to load certain profiles for a device if I knew the index number did NOT change each time. With a little more scripting, I could return 'listdevices' to a picker and select which index number to load a profile/map for.

Second, Between the 'startup.md' doc and the 'devices.md' doc, the daemon is started, then the user is told to open a terminal and start 'imod-cli'. I found that I could start 'imodd' and then enter 'imod-cli' in the same terminal after the successful startup message.

Additionally, is there a text file (or any file) that i can populate with my desired keybinds? If this is in the documentation, I over looked it. This would make creating remaps for my devices easier if I could simply populate a text file and have the daemon call it.

tildearrow commented 5 years ago

Firstly, In the "devices" documentation, under the "enabling devices", consider adding to the example:

You can also use your device's name, e.g. "Nostromo" instead of the index number. It seems it isn't clear in the documentation, however.

However, I noticed the index number changed if I started imodd and imod-cli , then plugged in the device, as opposed to starting imodd / imod-cli with the Nostromo plugged in.

The reason why this happens is because the index numbers map directly to the index numbers in the vector which holds connected devices. You aren't supposed to use indexes directly; they're just there for internal usage by the GUI.

(if you're wondering why I can't get rid of the indexes, it's because the CLI was designed to be as human-friendly as possible, but must have the bare minimum to be computer-readable)

Second, Between the 'startup.md' doc and the 'devices.md' doc, the daemon is started, then the user is told to open a terminal and start 'imod-cli'. I found that I could start 'imodd' and then enter 'imod-cli' in the same terminal after the successful startup message.

Would "to open up the utility, and type the following in a terminal:" do better?

Additionally, is there a text file (or any file) that i can populate with my desired keybinds? If this is in the documentation, I over looked it. This would make creating remaps for my devices easier if I could simply populate a text file and have the daemon call it.

There is, in the ~/.config/input-modifier directory. The profiles are stored as JSON files under directories that have your device's names. However, there is little error checking at the moment (I need to fix this) and the files are "minified" due to how they're stored by the JSON library. I'll find a way around that soon, however. (I also plan to add a way to directly load mapping files as a command)

tildearrow commented 5 years ago

I have pushed a new branch called newdoc with several clarifications.

TherinS commented 5 years ago

After running input-modifier again, I see there is a more accurate way to explain the issue I am seeing.

As far as using the index number instead of the name of the device is concerned, I had to do that because every one of the device names that was returned with 'listdevices' had at least 3 words in the name of the device (see pic3).

input-modifier_pic3

Entering "Honey" or "Nostromo" (without quotes) results in "error: invalid number." returned in the terminal, where using the index number allowed device enabling, disabling and key remapping ok.


Upon starting the daemon with 'imodd' as instructed in "startup.md", no further use can come from that terminal window, though I had mentioned that 'imod-cli' could be run right after 'imodd'. However, if the command is run as "imodd &", then "imod-cli" can be run right after "done! running." is seen in that terminal window and used as the documentation says. Otherwise, the first terminal window must remain open (with "imodd" running) and a second terminal window/tab must be opened to run "imod-cli". This might be a nice thing to mention in startup.md

tildearrow commented 5 years ago

Entering "Honey" or "Nostromo" (without quotes) results in "error: invalid number." returned in the terminal, where using the index number allowed device enabling, disabling and key remapping ok.

Thank you for the bug report! It was a bug in the device finding function which didn't work if you used uppercase letters, but now I've fixed it in the upcoming v1.3.3 release (bb417eefaf9fa5861f93ed39cf9a1a2254fbefbc).

I will continue doing more documentation clarifications, and after done, will release v1.3.3.

tildearrow commented 5 years ago

input-modifier v1.3.3 now released. Hopefully the documentation is better now (will close when you confirm)

TherinS commented 5 years ago

Yes, I can now interact with imod-cli to enable, disable. and check keybinds using lowercase for a device.

I have other questions about the use of imodd, and can copy the following to a new Issue thread if you like. Here they are:

I have read most of the documentation in the /doc/reference/command folder, but I do not understand what the difference is between a 'profile' and a 'map' and how they are used. I get loading a map, which is a listing of the rebound keys to apply to a device, but what does a profile do? I can listmaps and see that both Default and test1 exist, and can switch to it also,

When I want to list the profiles available, the following is the returned results:

listprofiles honey [info] client 6: listprofiles honey using device Honey Bee Nostromo SpeedPad2 .

  • teson
  • Default Ready.

I never made a 'teson' profile. I cannot "switchprofile" to teson, nor can I delete it as "delprofile" says it does not exist.

Lastly (for now), some of the documentation uses the index number of a device in the example. "listbinds.md" is an example of this. This could be confusing where a person might not know to use the index number of the device and instead use a name, or may be using an index number of a device they did not intend to interact with.

For a future version, would it be possible to include the action associated with a particular bound key when using the "listbinds" command? Example:

listbinds nostromo [info] client 6: listbinds nostromo using device Honey Bee Nostromo SpeedPad2 . bound keys:

  • KEY_Q = KEY_1
  • KEY_W = KEY_2
  • KEY_E = KEY_3
  • KEY_R = KEY_8 Ready.
tildearrow commented 5 years ago

A profile contains:

The difference between a profile and a mapping is that mappings can be switched instantly (addaction <device> <key> switchmap <mapping> or addaction <device> <key> shiftmap <mapping>) with a keypress.

When I want to list the profiles available, the following is the returned results:

"teson"? That must be a bug. May you provide your input-modifier config directory, to check what could be wrong? (~/.config/input-modifier)

(i'll move it to a new issue, and then look at it tomorrow since I need to sleep) (moved now, see #3)

some of the documentation uses the index number of a device in the example.

I'll be sure to update the reference to remove any usage of device index numbers. Thank you for pointing that out.

For a future version, would it be possible to include the action associated with a particular bound key when using the "listbinds" command?

Sure, will implement it for v1.4.

tildearrow commented 5 years ago

v1.3.4 now released.