Improve UX of `--keymaps` versus `--keymap`

[shajra]

This is a spinoff issue of a comment in another issue.

Below is the comment from @tremby copy/pasted for convenience:

I also updated the top-level README file to better explain the difference between --keymap and --keymaps. Let me know if that's clearer.

Maybe? Let's see if I understand.

The provided code is relatively compact. In the keymaps directory, you should find familiar files you would edit in QMK or Kaleidoscope projects, respectively. These keymaps are compiled into the flashing scripts provided with this project.

OK, this helps by defining what "compiled into the flashing scripts" means. I wasn't clear on that before. (If you didn't just add that part, I didn't read well enough last time!) So these are "presets" I guess?

For all keyboards, The “shajra” keymap is in its own directory. You can make your own keymap and put it in a sibling directory with the name of your choice, and it will be compiled in as well.

OK, so I can make a mymap directory next to that with my keymap, and that'll be "compiled in". Clear so far.

If you don't want to use keymaps compiled into the flashing scripts, you can point to another directory of keymaps outside the project at runtime with the -K / -keymaps switch.

It raises eyebrows that -keymaps (or is this a typo for --keymaps?) is a different thing from --keymap; IMO this is too similar and if it were my software I'd pick a different name. --external-keymap maybe.

But I think I get it -- without putting a keymap dir next to your one, I could have it elsewhere in the filesystem, and tell the script at runtime where to find it. But am I pointing to the directory with my *.ino file in it, or the directory containing multiple different keymap directories? I think the wording is suggesting the latter, though it's not 100% clear to me.

And then are these merging with the compiled-in ones (what's the priority for collisions if so?) or replacing them?

Whether using the builtin keymaps or pointing to your own directory, you then use the -k / --keymap switch to load your custom keymap by the name you chose for the keymap in the keymaps directory. The scripts should pick up changes, rebuild anything necessary, and flash your keyboard.

So if using a "compiled in" one, I just do -k mymap. If using an external one, I do -K /my/keymaps -k mymap?

I question why one would want to point to a directory of multiple external maps with -K when they're then forced to pick just one with -k anyway. Wouldn't it be simpler for the user to point directly to /my/keymaps/mymap? (Then shell completion is for free too for the full path.)

[shajra]

@tremby I wanted to talk through what I believe is your idea above, but one I thought a little about previously.

We could make --keymap clever and detect whether its argument contains a slash. If it does, we could presume it's a path location outside what's compiled into the script. That would make the usage something like:

• --keymap bjn for the "bjn" keymap found compiled into the script
• --keymap ./bjn for the "bjn" keymap found when running the script relative to the PWD.
• --keymap /some/absolute/path/bjn for the "bjn" keymap found at /some/absolute/path.

That gets rid of the --keymaps switch, but makes the --keymap option clever, with a complexity that surfaces not only in implementation logic, but also in the documentation when explaining how it works. Also, this design disallows subfolders in the compiled-in keymaps, but that was never really part of the original design.

The cleverness/complexity would only be worth it if the CLI option's design were intuitive to use. Otherwise, I think it's a wash when it comes to the tedium of being clear in documentation. What do you think?

In the end, I rarely flash my keyboard, and my personal keymap is the no-argument default. So I personally have the most convenient UX. These CLI options are really there for other users, so it helps me to get feedback from the few external users this project has.

[tremby]

My motivation to have my keymap alongside yours is because I also only flash the keyboard once in a blue moon, and I'll want to update the flasher script whenever I touch it. So by having my keymap there in a fork of the repo I can just pull upstream and merge or rebase my keymap and I'm ready to go (barring any surprises). Note that I would not want to replace your keymap with my own, or next time you make a change to yours I get a conflict. ("Keep mine" would always be the right answer to such conflicts, so they wouldn't be difficult to resolve at all, but it's still an extra pain point I'd want to avoid.)

But I can understand how another user would instead decide to track their keymap in a separate repository. And nobody likes using git submodules, so in that case it'd likely be in a different location on disk.

Because of that I think both "compiled-in" presets and keymap-from-path options are valuable.

But I am not convinced about having a "clever" option. Even if documented, things like that tend to surprise users -- it's easy to assume from observing successful operation that it functions a particular way, only to find later that actually it is being magic in a way you didn't know. Remember, most users are only going to use this very occasionally, so there's a decent chance any gotchas won't be remembered next time.

Consider this approach:

• Have only a --keymaps-dir option (I'm trying to be descriptive in what it should point to).
• Have it default to $SHAJRA_KEYBOARDS_ROOT/keymaps.
• Remove the shajra directories -- have your keymap right there in keymaps/$model.
• Now the user can do --keymap-dir=my-keymaps to use their own tree of keymaps instead of yours.
• Or (possibly better) change the tree structure to look like keymaps -> shajra -> $model -> keymapfiles, and have it default to $SHAJRA_KEYBOARDS_ROOT/keymaps/shajra, which would mean my keymaps can be in keymaps/bjn next to your dir, potentially keeping it a bit more tidy (everything can live in keymaps).
• Now for example the Model 100 script can do $KEYMAP_DIR/model_100` and find its files there, without having to have a separate "subdirectory" variable.
• Possibly introduce a configuration file ($XDG_CONFIG_HOME/shajra-keyboards/shajra-keyboards.conf or whatever) so that the default can be adjusted and we get the same nice easy UX you do.

I'm not sure if things being "compiled in" vs not is affected (or even relevant)?