doc: add note about "short" layout names (#194)

Fixes: https://github.com/xkbcommon/libxkbcommon/issues/193
Signed-off-by: Ran Benita <ran@unusedvar.com>

diff --git a/xkbcommon/xkbcommon.h b/xkbcommon/xkbcommon.h
index d6a02a7..ee7143c 100644 (file)
--- 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