Trying to understand MergeKeys() behavior

[Isopod]

I'm trying to understand how key definitions are merged, but looking at the source code for MergeKeys(), I am left a little confused.

Here is my current understanding: Each KeyInfo has a merge mode, which can be any of {override, replace, augment}. Let's say I want to merge KeyInfo b into KeyInfo a.

• If b's merge mode is override, then all properties carrying a value in b will overwrite the respective properties in a.
• If b's merge mode is augment, only properties will be added to a that don't already have a value in a.
• If b's merge mode is replace, then all properties are first deleted from a and subsequently replaced by b's properties.

So far, so good. My question is: What happens to the merge mode itself? If I merge b into a, does the result inherit a's merge mode or b's merge mode?

To make it more concrete (*):

xkb_symbols "foo" {
  replace key <ABCD> {['a', 'A']}
}
xkb_symbols "bar" {
  key <ABCD> {'b', 'B']}
  include "foo"
}
xkb_symbols "baz" {
  key <ABCD> {[], [['c', 'C']}
  include "bar"
}

Does bar's definition inherit the replace mode from foo or not? Should baz's key definition then be equivalent to

• key <ABCD> {['a', 'A']} or
• key <ABCD> {['a', 'A'], ['c', 'C']} ?

What about other mode combinations? For example, what if foo's mode was augment instead of replace? And so on.

Reading the source code, it looks to me like the current behavior is: When merging b into a, the result inherits

• b's mode if b has the mode replace (line)
• a's mode in all other cases

Is this intentional? Should this be documented somewhere?

(*) I hope these examples makes sense at all, since I'm still trying to understand the format

[bluetech]

Your analysis seems correct to me.

Is this intentional?

This has been decided 25 years ago so it's hard to know for sure. But the behavior does make sense to me.

Should this be documented somewhere?

Currently it isn't documented in this repo. It would be nice to include details on merging in this document https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-format-text-v1.md but it would require some work to untangle it from the code :)