Confusing terminology in docs and config file

[Liam Proven]

I suggest avoiding the use of the name "Meta", and possibly, of that key at all.

"Meta" is Emacs terminology and is confusing for non-Emacs users. "Alt" is the standard name for the key in x86/Arm contexts. That key is called "Opt" or "Option" on Macs.

KDE calls the "Windows" key by the name "Meta". It is wrong but consistent in their docs:

https://forum.endeavouros.com/t/meta-key-super-key-not-working-in-kde/31359

https://askubuntu.com/questions/246886/how-do-i-open-the-application-launcher-on-kde-with-just-the-meta-windows-key

Other products and projects think Meta is a totally different key. E.g. Wikipedia thinks it is the Mac "Command" key:

https://en.wikipedia.org/wiki/Meta_key

That's wrong: the Mac "Command" key is not that. This is the Command key:

https://en.wikipedia.org/wiki/Command_key

It is in fact "Super," AKA the "Windows key" on later Windows keyboards.

https://en.wikipedia.org/wiki/Windows_key

This is generically called the Super key:

https://en.wikipedia.org/wiki/Super_key_(keyboard_button)

Summary: do not use the name Meta key

Second request: use unambiguous standard names. I want to use the Super/Windows key but I don't know what you call it or what to put in the miracle-wm.yaml file.

[Liam Proven]

Additional request:

Please list in your docs the names miracle-wm uses/understands for all modifier keys. I have tried setting the modifier to super but it does not register.

[Matthew Kosarek]

Hiya @lproven
That's some good feedback. I am learning towards Super key over Windows key since its OS-agnostic. WDYT?

The types that miracle-wm understands is in the userguide at the "Types" header with the ModifierKey type. I should really publish much nicer docs in this area. If you have any examples of other projects that do this better, I'd love to see it! I am using C++ pseudo-code to describe my yaml file format, which isn't great.

[Liam Proven]

Hiya @lproven That's some good feedback.

Happy to help. :-) I am working on a 2nd article about Miracle for the Register.

I am learning towards Super key over Windows key since its OS-agnostic. WDYT?

Agreed.

The types that miracle-wm understands is in the userguide at the "Types" header with the ModifierKey type.

This part?

  "alt" | "alt_left" | "alt_right" | "shift" | "shift_left" | "shift_right" | "sym" | "function" | "ctrl"
  | "ctrl_left" | "ctrl_right" | "meta" | "meta_left" | "meta_right" | "caps_lock" | "num_lock" | "scroll_lock"
  | "primary";

The thing is that I don't see Super or Windows in that list at all...

I should really publish much nicer docs in this area.

Um, yes...

If you have any examples of other projects that do this better, I'd love to see it! I am using C++ pseudo-code to describe my yaml file format, which isn't great.

I went looking but this is a bit outside my comfort zone TBH.

xmodmap may help?

$ xmodmap -pm
xmodmap:  up to 4 keys per modifier, (keycodes in parentheses):

shift       Shift_L (0x32),  Shift_R (0x3e)
lock        Caps_Lock (0x42)
control     Control_L (0x25),  Control_R (0x69)
mod1        Alt_L (0x40),  Alt_L (0xcc),  Meta_L (0xcd)
mod2        Num_Lock (0x4d)
mod3        ISO_Level5_Shift (0xcb)
mod4        Super_L (0x85),  Super_R (0x86),  Super_L (0xce),  Hyper_L (0xcf)
mod5        ISO_Level3_Shift (0x5c)

[Matthew Kosarek]

As for a better presentation, I moved all of the documentation here this week: https://mattkae.github.io/miracle-wm-wiki/

It's a bit more presentable now 😄 I'll tackle the other issues tagged here when I get a moment this weekend.

[Luis Pabon]

"Super" is a good name that's actually also used by other compositors, like Sway for instance.