Add a new warning for numeric keysyms

[platform/upstream/libxkbcommon.git] / doc / message-registry.md

diff --git a/doc/message-registry.md b/doc/message-registry.md
index 69027be..dac4175 100644 (file)
--- a/doc/message-registry.md
+++ b/doc/message-registry.md
@@ -6,7 +6,7 @@ NOTE: This file has been generated automatically by “update-message-registry.p
 -->
 
 This page lists the warnings and errors generated by xkbcommon.
-There are currently 20 entries.
+There are currently 21 entries.
 
 @todo The documentation of the log messages is a work in progress.
 
@@ -23,6 +23,7 @@ There are currently 20 entries.
 | [XKB-305] | `non-base-group-name` | Warn if a group name was defined for group other than the first one | Warning |
 | [XKB-312] | `unsupported-shift-level` | Warn when a shift level is not supported | Error |
 | [XKB-461] | `conflicting-key-symbol` | Warn if there are conflicting keysyms while merging keys | Warning |
+| [XKB-489] | `numeric-keysym` | Warn on numeric keysym (other than 0-9) | Warning |
 | [XKB-516] | `extra-symbols-ignored` | <span class="todo">TODO:</span> add description | Warning |
 | [XKB-578] | `wrong-field-type` | Warn when a field has not the expected type | Error |
 | [XKB-645] | `unknown-char-escape-sequence` | Warn on unknown escape sequence in string literal | Warning |
@@ -165,6 +166,53 @@ as numbers and as identifiers `LevelN`, where `N` is in the range (1..8).
   <dt>Summary</dt><dd>Warn if there are conflicting keysyms while merging keys</dd>
 </dl>
 
+### XKB-489 – Numeric keysym {#XKB-489}
+
+<dl>
+  <dt>Since</dt><dd>1.6.0</dd>
+  <dt>Type</dt><dd>Warning</dd>
+  <dt>Summary</dt><dd>Warn on numeric keysym (other than 0-9)</dd>
+</dl>
+
+Numeric keysyms are not human-friendly. Use the corresponding named keysym
+or Unicode keysym, if available.
+
+
+#### Examples
+
+<details>
+  <summary>Hexadecimal keysym `0x1001ed0`</summary>
+
+**Error message:**
+
+```
+xkbcommon: WARNING: [XKB-489] numeric keysym "0x1001ed0"
+```
+
+**Fix:**
+  <div class="example-container">
+    <div class="example">
+      <div class="example-inner">
+        <div class="example-title">Before</div>
+```c
+key <AE01> { [ 0x1001ed0] };
+```
+</div>
+    </div>
+    <div class="example">
+      <div class="example-inner">
+        <div class="example-title">After</div>
+```c
+// Preferred form: human-friendly
+key <AE01> { [ Ocircumflexacute ] };
+// or
+key <AE01> { [ U1ED0 ] };
+```
+</div>
+    </div>
+  </div>
+</details>
+
 ### XKB-516 – Extra symbols ignored {#XKB-516}
 
 <dl>
@@ -280,6 +328,7 @@ xkbcommon support the following escape sequences in string literals:
 [XKB-305]: @ref XKB-305
 [XKB-312]: @ref XKB-312
 [XKB-461]: @ref XKB-461
+[XKB-489]: @ref XKB-489
 [XKB-516]: @ref XKB-516
 [XKB-578]: @ref XKB-578
 [XKB-645]: @ref XKB-645