doc: add note about "short" layout names (#194) Fixes: https://github.com/xkbcommon/libxkbcommon/issues/193 Signed-off-by: Ran Benita <ran@unusedvar.com>
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
diff --git a/xkbcommon/xkbcommon.h b/xkbcommon/xkbcommon.h
index d6a02a7..ee7143c 100644
--- a/xkbcommon/xkbcommon.h
+++ b/xkbcommon/xkbcommon.h
@@ -208,6 +208,15 @@ typedef uint32_t xkb_keysym_t;
* Therefore, it is not safe to use the name as a unique identifier for a
* layout. Layout names are case-sensitive.
*
+ * Layout names are specified in the layout's definition, for example
+ * "English (US)". These are different from the (conventionally) short names
+ * which are used to locate the layout, for example "us" or "us(intl)". These
+ * names are not present in a compiled keymap.
+ *
+ * If the user selects layouts from a list generated from the XKB registry
+ * (using libxkbregistry or directly), and this metadata is needed later on, it
+ * is recommended to store it along with the keymap.
+ *
* Layouts are also called "groups" by XKB.
*
* @sa xkb_keymap_num_layouts() xkb_keymap_num_layouts_for_key()
@@ -1087,6 +1096,7 @@ xkb_keymap_num_layouts(struct xkb_keymap *keymap);
* a name, returns NULL.
*
* @sa xkb_layout_index_t
+ * For notes on layout names.
* @memberof xkb_keymap
*/
const char *
@@ -1099,6 +1109,8 @@ xkb_keymap_layout_get_name(struct xkb_keymap *keymap, xkb_layout_index_t idx);
* XKB_LAYOUT_INVALID. If more than one layout in the keymap has this name,
* returns the lowest index among them.
*
+ * @sa xkb_layout_index_t
+ * For notes on layout names.
* @memberof xkb_keymap
*/
xkb_layout_index_t