Improve the doc of the XKB keymap text format, V1 (#321)

- Add table of contents
- Add terminology section
- (WIP) Add Introduction to the format
- Improve the keycode section
- Improve the interpret section
- Add guide to create and use modifiers
- (WIP) Add actions documentation
- Add cross-references
- Add keysyms header to documentation

doc/doxygen-extra.css

@@ -7,3 +7,7 @@ div#top, div.header, div.contents {
 .footer {
         display: none;
 }
+
+span.TODO::before {
+        content: '🚧 ';
+}

include/xkbcommon/xkbcommon-keysyms.h

@@ -3,6 +3,11 @@
 
 /* This file is autogenerated; please do not commit directly. */
 
+/**
+ * @file
+ * Key symbols (keysyms) definitions.
+ */
+
 #define XKB_KEY_NoSymbol                    0x000000  /* Special KeySym */
 
 /***********************************************************

meson.build

@@ -791,9 +791,10 @@ You can disable the documentation with -Denable-docs=false.''')
         'doc/rules-format.md',
         'doc/keymap-format-text-v1.md',
         'include/xkbcommon/xkbcommon.h',
+        'include/xkbcommon/xkbcommon-compose.h',
+        'include/xkbcommon/xkbcommon-keysyms.h',
         'include/xkbcommon/xkbcommon-names.h',
         'include/xkbcommon/xkbcommon-x11.h',
-        'include/xkbcommon/xkbcommon-compose.h',
         'include/xkbcommon/xkbregistry.h',
     ]
     doxygen_data = configuration_data()

scripts/makeheader

@@ -21,6 +21,11 @@ print('''#ifndef _XKBCOMMON_KEYSYMS_H
 
 /* This file is autogenerated; please do not commit directly. */
 
+/**
+ * @file
+ * Key symbols (keysyms) definitions.
+ */
+
 #define XKB_KEY_NoSymbol                    0x000000  /* Special KeySym */
 ''')
 for path in HEADERS: