test: add a test for multiple keysyms (and some minimal docs)

I couldn't find any reference to *how* the keymap format actually needs to look
like if you want multiple keysyms per level. So let's add a test for it and a
minimal documentation entry.

doc/keymap-format-text-v1.md

@@ -910,6 +910,17 @@ and separated by commas. Each element of the symbol arrays corresponds to a
 different modifier level. In this example, the symbol (keysym) `XKB_KEY_q` for
 level 1 and `XKB_KEY_Q` for level 2.
 
+As an extension to the XKB format, libxkbcommon supports multiple key symbols
+per level.
+
+    key <AD01> { [ {a, b}, Q ] };
+
+In this example, the keycode `<AD01>` produces two symbols on level 1
+(`XKB_KEY_a` and `XKB_KEY_b`) and one symbol (`XKB_KEY_Q`) on level 2.
+
+@warning Keymaps containing multiple key symbols per level are not supported
+by the various X11-related tools (`setxkbmap`, `xkbcomp`, etc.).
+
 #### Actions
 
 @todo how to bind key actions

test/data/symbols/awesome

@@ -7,11 +7,11 @@ xkb_symbols "awesome" {
     key <AE02> { [ 2, at,          Page_Up,    Page_Up     ] };
     key <AE03> { [ 3, numbersign,  Page_Down,  Page_Down   ] };
 
-    key <AD01> { [ q,  Q,          Escape,     Escape      ] };
+    key <AD01> { [ {q, a, b},  Q,  Escape,     Escape      ] };
     key <AD02> { [ w,  W,          Home,       Home        ] };
     key <AD03> {
         type="THREE_LEVEL",
-        symbols=[ e,  E,           Up]
+        symbols=[ e,  {E, F},      Up]
     };
     key <AD04> { [ r,  R,          End,        End         ] };
     key <AD05> { [ t,  T,          Tab,        Tab         ] };

test/keymap.c

@@ -198,12 +198,45 @@ test_numeric_keysyms(void)
     xkb_context_unref(context);
 }
 
+static void
+test_multiple_keysyms_per_level(void)
+{
+    struct xkb_context *context = test_get_context(0);
+    struct xkb_keymap *keymap;
+    xkb_keycode_t kc;
+    int keysyms_count;
+    const xkb_layout_index_t first_layout = 0;
+    const xkb_keysym_t *keysyms;
+
+    assert(context);
+
+    keymap = test_compile_rules(context, "evdev", "pc104", "awesome", NULL, NULL);
+    assert(keymap);
+
+    kc = xkb_keymap_key_by_name(keymap, "AD01");
+    keysyms_count = xkb_keymap_key_get_syms_by_level(keymap, kc, first_layout, 0, &keysyms);
+    assert(keysyms_count == 3);
+    assert(keysyms[0] == 'q');
+    assert(keysyms[1] == 'a');
+    assert(keysyms[2] == 'b');
+
+    kc = xkb_keymap_key_by_name(keymap, "AD03");
+    keysyms_count = xkb_keymap_key_get_syms_by_level(keymap, kc, first_layout, 1, &keysyms);
+    assert(keysyms_count == 2);
+    assert(keysyms[0] == 'E');
+    assert(keysyms[1] == 'F');
+
+    xkb_keymap_unref(keymap);
+    xkb_context_unref(context);
+}
+
 int
 main(void)
 {
     test_garbage_key();
     test_keymap();
     test_numeric_keysyms();
+    test_multiple_keysyms_per_level();
 
     return 0;
 }