doc/message-registry.md

   1 # Error index {#error-index}
   2
   3 <!--
   4 NOTE: This file has been generated automatically by “update-message-registry.py”.
   5       Do not edit manually!
   6 -->
   7
   8 This page lists the warnings and errors generated by xkbcommon.
   9 There are currently 21 entries.
  10
  11 @todo The documentation of the log messages is a work in progress.
  12
  13 ## Index
  14
  15 | Code      | Identifier                   | Description | Type |
  16 | --------- | ---------------------------- | ----------- | ---- |
  17 | [XKB-034] | `malformed-number-literal` | Warn on malformed number literals | Error |
  18 | [XKB-060] | `unsupported-modifier-mask` | Warn on unsupported modifier mask | Error |
  19 | [XKB-107] | `unrecognized-keysym` | Warn on unrecognized keysyms | Warning |
  20 | [XKB-183] | `cannot-infer-key-type` | Warn if no key type can be inferred | Warning |
  21 | [XKB-237] | `unsupported-group-index` | Warn when a group index is not supported | Error |
  22 | [XKB-286] | `undefined-key-type` | Warn if using an undefined key type | Warning |
  23 | [XKB-305] | `non-base-group-name` | Warn if a group name was defined for group other than the first one | Warning |
  24 | [XKB-312] | `unsupported-shift-level` | Warn when a shift level is not supported | Error |
  25 | [XKB-461] | `conflicting-key-symbol` | Warn if there are conflicting keysyms while merging keys | Warning |
  26 | [XKB-489] | `numeric-keysym` | Warn on numeric keysym (other than 0-9) | Warning |
  27 | [XKB-516] | `extra-symbols-ignored` | <span class="todo">TODO:</span> add description | Warning |
  28 | [XKB-578] | `wrong-field-type` | Warn when a field has not the expected type | Error |
  29 | [XKB-645] | `unknown-char-escape-sequence` | Warn on unknown escape sequence in string literal | Warning |
  30 | [XKB-700] | `multiple-groups-at-once` | Warn if a key defines multiple groups at once | Warning |
  31 | [XKB-769] | `invalid-syntax` | The syntax is invalid and the file cannot be parsed | Error |
  32 | [XKB-770] | `undefined-keycode` | <span class="todo">TODO:</span> add description | Warning |
  33 | [XKB-800] | `conflicting-modmap` | Warn if there are conflicting modmap definitions | Warning |
  34 | [XKB-883] | `conflicting-key-action` | Warn if there are conflicting actions while merging keys | Warning |
  35 | [XKB-893] | `conflicting-key-type` | Warn if there are conflicting key types while merging groups | Warning |
  36 | [XKB-935] | `conflicting-key-fields` | Warn if there are conflicting fields while merging keys | Warning |
  37 | [XKB-965] | `unresolved-keymap-symbol` | Warn if using a symbol not defined in the keymap | Warning |
  38
  39 ## Details
  40
  41 ### XKB-034 – Malformed number literal {#XKB-034}
  42
  43 <dl>
  44   <dt>Since</dt><dd>1.0.0</dd>
  45   <dt>Type</dt><dd>Error</dd>
  46   <dt>Summary</dt><dd>Warn on malformed number literals</dd>
  47 </dl>
  48
  49 xkbcommon can parse the following number literal formats:
  50
  51 - *decimal integer:* 1, 123, etc.
  52 - *decimal floating-point number:* 1.23, etc.
  53 - *hexadecimal integer:* prefixed with “0x”: 0x123, 0xff, 0xAB, etc.
  54
  55
  56 ### XKB-060 – Unsupported modifier mask {#XKB-060}
  57
  58 <dl>
  59   <dt>Since</dt><dd>1.0.0</dd>
  60   <dt>Type</dt><dd>Error</dd>
  61   <dt>Summary</dt><dd>Warn on unsupported modifier mask</dd>
  62 </dl>
  63
  64 ### XKB-107 – Unrecognized keysym {#XKB-107}
  65
  66 <dl>
  67   <dt>Since</dt><dd>1.0.0</dd>
  68   <dt>Type</dt><dd>Warning</dd>
  69   <dt>Summary</dt><dd>Warn on unrecognized keysyms</dd>
  70 </dl>
  71
  72 xkbcommon replaces keysyms it does not recognize by the keysym `NoSymbol`.
  73
  74 You may find the list of supported keysyms in
  75 `include/xkbcommon/xkbcommon-keysyms.h`.
  76
  77
  78 #### Examples
  79
  80 <details>
  81   <summary>Unrecognized keysym “`coma`”</summary>
  82
  83 **Error message:**
  84
  85 ```
  86 xkbcommon: WARNING: [XKB-107] de:31:20: unrecognized keysym "coma"
  87 ```
  88
  89 xkbcommon does not recognize the keysym “`coma`”. It is most probably
  90 a typo for “<code>com<em>m</em>a</code>”.
  91 See: `XKB_KEY_comma` in `include/xkbcommon/xkbcommon-keysyms.h`.
  92
  93 **Fix:**
  94   <div class="example-container">
  95     <div class="example">
  96       <div class="example-inner">
  97         <div class="example-title">Before</div>
  98 ```c
  99 key <AB08> {[ coma, semicolon, periodcentered, multiply ]};
 100 ```
 101 </div>
 102     </div>
 103     <div class="example">
 104       <div class="example-inner">
 105         <div class="example-title">After</div>
 106 ```c
 107 key <AB08> {[ comma, semicolon, periodcentered, multiply ]};
 108 ```
 109 </div>
 110     </div>
 111   </div>
 112 </details>
 113
 114 ### XKB-183 – Cannot infer key type {#XKB-183}
 115
 116 <dl>
 117   <dt>Since</dt><dd>1.0.0</dd>
 118   <dt>Type</dt><dd>Warning</dd>
 119   <dt>Summary</dt><dd>Warn if no key type can be inferred</dd>
 120 </dl>
 121
 122 ### XKB-237 – Unsupported group index {#XKB-237}
 123
 124 <dl>
 125   <dt>Since</dt><dd>1.0.0</dd>
 126   <dt>Type</dt><dd>Error</dd>
 127   <dt>Summary</dt><dd>Warn when a group index is not supported</dd>
 128 </dl>
 129
 130 xkbcommon supports group index in the range (1..4).
 131
 132
 133 ### XKB-286 – Undefined key type {#XKB-286}
 134
 135 <dl>
 136   <dt>Since</dt><dd>1.0.0</dd>
 137   <dt>Type</dt><dd>Warning</dd>
 138   <dt>Summary</dt><dd>Warn if using an undefined key type</dd>
 139 </dl>
 140
 141 ### XKB-305 – Non base group name {#XKB-305}
 142
 143 <dl>
 144   <dt>Since</dt><dd>1.0.0</dd>
 145   <dt>Type</dt><dd>Warning</dd>
 146   <dt>Summary</dt><dd>Warn if a group name was defined for group other than the first one</dd>
 147 </dl>
 148
 149 ### XKB-312 – Unsupported shift level {#XKB-312}
 150
 151 <dl>
 152   <dt>Since</dt><dd>1.0.0</dd>
 153   <dt>Type</dt><dd>Error</dd>
 154   <dt>Summary</dt><dd>Warn when a shift level is not supported</dd>
 155 </dl>
 156
 157 Shift levels are _one_-indexed. xkbcommon supports two formats of shift levels:
 158 as numbers and as identifiers `LevelN`, where `N` is in the range (1..8).
 159
 160
 161 ### XKB-461 – Conflicting key symbol {#XKB-461}
 162
 163 <dl>
 164   <dt>Since</dt><dd>1.0.0</dd>
 165   <dt>Type</dt><dd>Warning</dd>
 166   <dt>Summary</dt><dd>Warn if there are conflicting keysyms while merging keys</dd>
 167 </dl>
 168
 169 ### XKB-489 – Numeric keysym {#XKB-489}
 170
 171 <dl>
 172   <dt>Since</dt><dd>1.6.0</dd>
 173   <dt>Type</dt><dd>Warning</dd>
 174   <dt>Summary</dt><dd>Warn on numeric keysym (other than 0-9)</dd>
 175 </dl>
 176
 177 Numeric keysyms are not human-friendly. Use the corresponding named keysym
 178 or Unicode keysym, if available.
 179
 180
 181 #### Examples
 182
 183 <details>
 184   <summary>Hexadecimal keysym `0x1001ed0`</summary>
 185
 186 **Error message:**
 187
 188 ```
 189 xkbcommon: WARNING: [XKB-489] numeric keysym "0x1001ed0"
 190 ```
 191
 192 **Fix:**
 193   <div class="example-container">
 194     <div class="example">
 195       <div class="example-inner">
 196         <div class="example-title">Before</div>
 197 ```c
 198 key <AE01> { [ 0x1001ed0] };
 199 ```
 200 </div>
 201     </div>
 202     <div class="example">
 203       <div class="example-inner">
 204         <div class="example-title">After</div>
 205 ```c
 206 // Preferred form: human-friendly
 207 key <AE01> { [ Ocircumflexacute ] };
 208 // or
 209 key <AE01> { [ U1ED0 ] };
 210 ```
 211 </div>
 212     </div>
 213   </div>
 214 </details>
 215
 216 ### XKB-516 – Extra symbols ignored {#XKB-516}
 217
 218 <dl>
 219   <dt>Since</dt><dd>1.0.0</dd>
 220   <dt>Type</dt><dd>Warning</dd>
 221   <dt>Summary</dt><dd><span class="todo">TODO:</span> add description</dd>
 222 </dl>
 223
 224 ### XKB-578 – Wrong field type {#XKB-578}
 225
 226 <dl>
 227   <dt>Since</dt><dd>1.0.0</dd>
 228   <dt>Type</dt><dd>Error</dd>
 229   <dt>Summary</dt><dd>Warn when a field has not the expected type</dd>
 230 </dl>
 231
 232 ### XKB-645 – Unknown char escape sequence {#XKB-645}
 233
 234 <dl>
 235   <dt>Since</dt><dd>1.0.0</dd>
 236   <dt>Type</dt><dd>Warning</dd>
 237   <dt>Summary</dt><dd>Warn on unknown escape sequence in string literal</dd>
 238 </dl>
 239
 240 xkbcommon support the following escape sequences in string literals:
 241
 242 | Escape sequence | Corresponding character             |
 243 | --------------- | ----------------------------------- |
 244 | `\b`            | `U+0008` Backspace                  |
 245 | `\t`            | `U+0009` Character tabulation       |
 246 | `\n`            | `U+000A` Line feed                  |
 247 | `\v`            | `U+000B` Vertical tabulation        |
 248 | `\f`            | `U+000C` Form feed                  |
 249 | `\r`            | `U+000D` Carriage return            |
 250 | `\e`            | `U+001B` Escape                     |
 251 | `\\`            | `U+005C` Backslash                  |
 252 | `\NNN`          | _Octal_ escape, from `\0` to `\777` |
 253
 254
 255 ### XKB-700 – Multiple groups at once {#XKB-700}
 256
 257 <dl>
 258   <dt>Since</dt><dd>1.0.0</dd>
 259   <dt>Type</dt><dd>Warning</dd>
 260   <dt>Summary</dt><dd>Warn if a key defines multiple groups at once</dd>
 261 </dl>
 262
 263 ### XKB-769 – Invalid syntax {#XKB-769}
 264
 265 <dl>
 266   <dt>Since</dt><dd>1.0.0</dd>
 267   <dt>Type</dt><dd>Error</dd>
 268   <dt>Summary</dt><dd>The syntax is invalid and the file cannot be parsed</dd>
 269 </dl>
 270
 271 ### XKB-770 – Undefined keycode {#XKB-770}
 272
 273 <dl>
 274   <dt>Since</dt><dd>1.0.0</dd>
 275   <dt>Type</dt><dd>Warning</dd>
 276   <dt>Summary</dt><dd><span class="todo">TODO:</span> add description</dd>
 277 </dl>
 278
 279 ### XKB-800 – Conflicting modmap {#XKB-800}
 280
 281 <dl>
 282   <dt>Since</dt><dd>1.0.0</dd>
 283   <dt>Type</dt><dd>Warning</dd>
 284   <dt>Summary</dt><dd>Warn if there are conflicting modmap definitions</dd>
 285 </dl>
 286
 287 @todo detailed explanation and examples
 288
 289
 290 ### XKB-883 – Conflicting key action {#XKB-883}
 291
 292 <dl>
 293   <dt>Since</dt><dd>1.0.0</dd>
 294   <dt>Type</dt><dd>Warning</dd>
 295   <dt>Summary</dt><dd>Warn if there are conflicting actions while merging keys</dd>
 296 </dl>
 297
 298 ### XKB-893 – Conflicting key type {#XKB-893}
 299
 300 <dl>
 301   <dt>Since</dt><dd>1.0.0</dd>
 302   <dt>Type</dt><dd>Warning</dd>
 303   <dt>Summary</dt><dd>Warn if there are conflicting key types while merging groups</dd>
 304 </dl>
 305
 306 ### XKB-935 – Conflicting key fields {#XKB-935}
 307
 308 <dl>
 309   <dt>Since</dt><dd>1.0.0</dd>
 310   <dt>Type</dt><dd>Warning</dd>
 311   <dt>Summary</dt><dd>Warn if there are conflicting fields while merging keys</dd>
 312 </dl>
 313
 314 ### XKB-965 – Unresolved keymap symbol {#XKB-965}
 315
 316 <dl>
 317   <dt>Since</dt><dd>1.0.0</dd>
 318   <dt>Type</dt><dd>Warning</dd>
 319   <dt>Summary</dt><dd>Warn if using a symbol not defined in the keymap</dd>
 320 </dl>
 321
 322 [XKB-034]: @ref XKB-034
 323 [XKB-060]: @ref XKB-060
 324 [XKB-107]: @ref XKB-107
 325 [XKB-183]: @ref XKB-183
 326 [XKB-237]: @ref XKB-237
 327 [XKB-286]: @ref XKB-286
 328 [XKB-305]: @ref XKB-305
 329 [XKB-312]: @ref XKB-312
 330 [XKB-461]: @ref XKB-461
 331 [XKB-489]: @ref XKB-489
 332 [XKB-516]: @ref XKB-516
 333 [XKB-578]: @ref XKB-578
 334 [XKB-645]: @ref XKB-645
 335 [XKB-700]: @ref XKB-700
 336 [XKB-769]: @ref XKB-769
 337 [XKB-770]: @ref XKB-770
 338 [XKB-800]: @ref XKB-800
 339 [XKB-883]: @ref XKB-883
 340 [XKB-893]: @ref XKB-893
 341 [XKB-935]: @ref XKB-935
 342 [XKB-965]: @ref XKB-965