doc/message-registry.yaml

   1 # Guidelines:
   2 # • A message code must always have the same meaning forever.
   3 # • Codes may be retired or introduced in new releases. In order to avoid
   4 #   clashes, retired codes must not be deleted.
   5 # • Codes should not themselves reflect classification, e.g. a range for parse
   6 #   errors and a range for each keymap component.
   7 # • Codes should not be assigned sequentially because it is misleading.
   8 # • Codes must be in the range 1..999. This range may be extended once every
   9 #   code has be assigned.
  10 #
  11 # See the following guidelines for futher details on good practices:
  12 # https://github.com/haskellfoundation/error-message-index/blob/main/tool-developers.md#code-assignment-recommendations
  13
  14 # NOTE: Field “added: ALWAYS” means that the precise version is unknown and
  15 # anterior to the introduction of the message registry. It will be replaced by
  16 # the default version 1.0.0 in the generated documentation. While this is deemed
  17 # good enough to avoid spelunking commit history, a more precise version would
  18 # be welcome.
  19
  20 # TODO: fix missing detailed description, examples, resolution
  21
  22 - id: "malformed-number-literal"
  23   code: 34
  24   added: ALWAYS
  25   type: error
  26   description: "Warn on malformed number literals"
  27   details: |
  28     xkbcommon can parse the following number literal formats:
  29
  30     - *decimal integer:* 1, 123, etc.
  31     - *decimal floating-point number:* 1.23, etc.
  32     - *hexadecimal integer:* prefixed with “0x”: 0x123, 0xff, 0xAB, etc.
  33 - id: "conflicting-key-type-preserve-entries"
  34   code: 43
  35   added: ALWAYS
  36   type: warning
  37   description: "Conflicting “preserve” entries in a key type"
  38 - id: "unsupported-modifier-mask"
  39   code: 60
  40   added: ALWAYS
  41   type: error
  42   description: "Warn on unsupported modifier mask"
  43 - id: "expected-array-entry"
  44   code: 77
  45   added: ALWAYS
  46   type: error
  47   description: "Expected an array entry, but the index is missing"
  48 - id: "illegal-keycode-alias"
  49   code: 101
  50   added: ALWAYS
  51   type: warning
  52   description: "Illegal keycode alias with the name of a real key"
  53 - id: "unrecognized-keysym"
  54   code: 107
  55   added: ALWAYS
  56   type: warning
  57   description: "Warn on unrecognized keysyms"
  58   details: |
  59     xkbcommon replaces keysyms it does not recognize by the keysym `NoSymbol`.
  60
  61     You may find the list of supported keysyms in
  62     `include/xkbcommon/xkbcommon-keysyms.h`.
  63   examples:
  64     - name: Unrecognized keysym “`coma`”
  65       description: |
  66         **Error message:**
  67
  68         ```
  69         xkbcommon: WARNING: [XKB-107] de:31:20: unrecognized keysym "coma"
  70         ```
  71
  72         xkbcommon does not recognize the keysym “`coma`”. It is most probably
  73         a typo for “<code>com<em>m</em>a</code>”.
  74         See: `XKB_KEY_comma` in `include/xkbcommon/xkbcommon-keysyms.h`.
  75       before: |
  76         ```c
  77         key <AB08> {[ coma, semicolon, periodcentered, multiply ]};
  78         ```
  79       after: |
  80         ```c
  81         key <AB08> {[ comma, semicolon, periodcentered, multiply ]};
  82         ```
  83 - id: "undeclared-virtual-modifier"
  84   code: 123
  85   added: ALWAYS
  86   type: error
  87   description: "A virtual modifier is used before being declared"
  88 - id: "wrong-statement-type"
  89   code: 150
  90   added: ALWAYS
  91   type: error
  92   description: "The type of the statement is not allowed in the context"
  93 - id: "unsupported-geometry-section"
  94   code: 172
  95   added: ALWAYS
  96   type: warning
  97   description: "Geometry sections are not supported"
  98 - id: "cannot-infer-key-type"
  99   code: 183
 100   added: ALWAYS
 101   type: warning
 102   description: "Warn if no key type can be inferred"
 103 - id: "invalid-escape-sequence"
 104   code: 193
 105   added: ALWAYS
 106   type: warning
 107   description: "Invalid escape sequence in a string"
 108 - id: "illegal-key-type-preserve-result"
 109   code: 195
 110   added: ALWAYS
 111   type: warning
 112   description: "The result of a key type “preserve” entry must be a subset of its input modifiers."
 113 - id: "invalid-include-statement"
 114   code: 203
 115   added: ALWAYS
 116   type: error
 117   description: "Syntax error in the include statement"
 118 - id: "invalid-modmap-entry"
 119   code: 206
 120   added: ALWAYS
 121   type: error
 122   description: "A modmap entry is invalid"
 123 - id: "unsupported-group-index"
 124   code: 237
 125   added: ALWAYS
 126   type: error
 127   description: "Warn when a group index is not supported"
 128   details: |
 129     xkbcommon supports group index in the range (1..{{XKB_MAX_GROUPS}}).
 130 - id: "conflicting-key-type-level-names"
 131   code: 239
 132   added: ALWAYS
 133   type: warning
 134   description: "The name of a key type level is defined multiple times."
 135 - id: "invalid-set-default-statement"
 136   code: 254
 137   added: ALWAYS
 138   type: error
 139   description: "Invalid statement setting default values"
 140 - id: "conflicting-key-type-map-entry"
 141   code: 266
 142   added: ALWAYS
 143   type: warning
 144   description: "Conflicting “map” entries in type definition"
 145 - id: "undefined-key-type"
 146   code: 286
 147   added: ALWAYS
 148   type: warning
 149   description: "Warn if using an undefined key type"
 150 - id: "non-base-group-name"
 151   code: 305
 152   added: ALWAYS
 153   type: warning
 154   description: "Warn if a group name was defined for group other than the first one"
 155 - id: "unsupported-shift-level"
 156   code: 312
 157   added: ALWAYS
 158   type: error
 159   description: "Warn when a shift level is not supported"
 160   details: |
 161     Shift levels are _one_-indexed. xkbcommon supports two formats of shift levels:
 162     as numbers and as identifiers `LevelN`, where `N` is in the range (1..8).
 163 - id: "included-file-not-found"
 164   code: 338
 165   added: ALWAYS
 166   type: error
 167   description: "Could not find a file used in an include statement"
 168 - id: "unknown-operator"
 169   code: 345
 170   added: ALWAYS
 171   type: error
 172   description: "Use of an operator that is unknown and thus unsupported"
 173 - id: "duplicate-entry"
 174   code: 378
 175   added: ALWAYS
 176   type: warning
 177   description: "An entry is duplicated and will be ignored"
 178 - id: "conflicting-key-type-definitions"
 179   code: 407
 180   added: ALWAYS
 181   type: warning
 182   description: "Conflicting definitions of a key type"
 183   details: |
 184     The given key type is defined multiple times, but only one definition is kept.
 185 - id: "wrong-scope"
 186   code: 428
 187   added: ALWAYS
 188   type: error
 189   description: "A statement is in a wrong scope and should be moved"
 190 - id: "missing-default-section"
 191   code: 433
 192   added: ALWAYS
 193   type: warning
 194   description: "Missing default section in included file"
 195   details: |
 196     When using an include statement, the included file may contains multiple sections.
 197     The include statement may specify the name of the section to include, or leave it
 198     unspecified. In the latter case, the included file must then define a *default* section.
 199     The present warning is shown when no default section is defined.
 200
 201     To solve this, either fix the include statement by specifying the exact section to
 202     include, or declare a default section in the included file.
 203 - id: "conflicting-key-symbol"
 204   code: 461
 205   added: ALWAYS
 206   type: warning
 207   description: "Warn if there are conflicting keysyms while merging keys"
 208 - id: "invalid-operation"
 209   code: 478
 210   added: ALWAYS
 211   type: error
 212   description: "The operation is invalid in the context"
 213 - id: "numeric-keysym"
 214   code: 489
 215   added: 1.6.0
 216   type: warning
 217   description: "Warn on numeric keysym (other than 0-9)"
 218   details: |
 219     Numeric keysyms are not human-friendly. Use the corresponding named keysym
 220     or Unicode keysym, if available.
 221   examples:
 222     - name: Hexadecimal keysym `0x1001ed0`
 223       description: |
 224         **Error message:**
 225
 226         ```
 227         xkbcommon: WARNING: [XKB-489] numeric keysym "0x1001ed0"
 228         ```
 229       before: |
 230         ```c
 231         key <AE01> { [ 0x1001ed0] };
 232         ```
 233       after: |
 234         ```c
 235         // Preferred form: human-friendly
 236         key <AE01> { [ Ocircumflexacute ] };
 237         // or
 238         key <AE01> { [ U1ED0 ] };
 239         ```
 240 - id: "extra-symbols-ignored"
 241   code: 516
 242   added: ALWAYS
 243   type: warning
 244   description: "TODO: add description"
 245 - id: "conflicting-key-name"
 246   code: 523
 247   added: ALWAYS
 248   type: warning
 249   description: "Conflicting definitions of a key name or alias"
 250 - id: "allocation-error"
 251   code: 550
 252   added: ALWAYS
 253   type: error
 254   description: "Cannot allocate memory"
 255 - id: "wrong-field-type"
 256   code: 578
 257   added: ALWAYS
 258   type: error
 259   description: "Warn when a field has not the expected type"
 260 - id: "invalid-real-modifier"
 261   code: 623
 262   added: ALWAYS
 263   type: error
 264   description: "Invalid _real_ modifier"
 265 - id: "unknown-char-escape-sequence"
 266   code: 645
 267   added: ALWAYS
 268   type: warning
 269   description: "Warn on unknown escape sequence in string literal"
 270   details: |
 271     xkbcommon support the following escape sequences in string literals:
 272
 273     | Escape sequence | Corresponding character             |
 274     | --------------- | ----------------------------------- |
 275     | `\b`            | `U+0008` Backspace                  |
 276     | `\t`            | `U+0009` Character tabulation       |
 277     | `\n`            | `U+000A` Line feed                  |
 278     | `\v`            | `U+000B` Vertical tabulation        |
 279     | `\f`            | `U+000C` Form feed                  |
 280     | `\r`            | `U+000D` Carriage return            |
 281     | `\e`            | `U+001B` Escape                     |
 282     | `\\`            | `U+005C` Backslash                  |
 283     | `\NNN`          | _Octal_ escape, from `\0` to `\777` |
 284 - id: "invalid-included-file"
 285   code: 661
 286   added: ALWAYS
 287   type: error
 288   description: "The target file of an include statement could not be processed"
 289 - id: "multiple-groups-at-once"
 290   code: 700
 291   added: ALWAYS
 292   type: warning
 293   description: "Warn if a key defines multiple groups at once"
 294 - id: "unsupported-symbols-field"
 295   code: 711
 296   added: ALWAYS
 297   type: warning
 298   description: "A legacy X11 symbol field is not supported"
 299 - id: "invalid-syntax"
 300   code: 769
 301   added: ALWAYS
 302   type: error
 303   description: "The syntax is invalid and the file cannot be parsed"
 304 - id: "undefined-keycode"
 305   code: 770
 306   added: ALWAYS
 307   type: warning
 308   description: "Reference to an undefined keycode"
 309 - id: "invalid-expression-type"
 310   code: 784
 311   added: ALWAYS
 312   type: error
 313   description: "An expression has not the expected type"
 314 - id: "invalid-value"
 315   code: 796
 316   added: ALWAYS
 317   type: error
 318   description: "A value is invalid and will be ignored"
 319 - id: "conflicting-modmap"
 320   code: 800
 321   added: ALWAYS
 322   type: warning
 323   description: "Warn if there are conflicting modmap definitions"
 324   details: |
 325     @todo detailed explanation and examples
 326 - id: "unknown-field"
 327   code: 812
 328   added: ALWAYS
 329   type: error
 330   description: "A field is unknown and will be ignored"
 331 - id: "conflicting-key-action"
 332   code: 883
 333   added: ALWAYS
 334   type: warning
 335   description: "Warn if there are conflicting actions while merging keys"
 336 - id: "conflicting-key-type-merging-groups"
 337   code: 893
 338   added: ALWAYS
 339   type: warning
 340   description: "Warn if there are conflicting key types while merging groups"
 341 - id: "conflicting-key-symbols-entry"
 342   code: 901
 343   added: ALWAYS
 344   type: error
 345   description: "Conflicting symbols entry for a key"
 346 - id: "missing-symbols-group-name-index"
 347   code: 903
 348   added: ALWAYS
 349   type: warning
 350   description: "Missing group index in a group name entry"
 351 - id: "conflicting-key-fields"
 352   code: 935
 353   added: ALWAYS
 354   type: warning
 355   description: "Warn if there are conflicting fields while merging keys"
 356 - id: "invalid-identifier"
 357   code: 949
 358   added: ALWAYS
 359   type: error
 360   description: "An identifier is used but is not built-in"
 361 - id: "unresolved-keymap-symbol"
 362   code: 965
 363   added: ALWAYS
 364   type: warning
 365   description: "Warn if using a symbol not defined in the keymap"
 366 - id: "undeclared-modifiers-in-key-type"
 367   code: 971
 368   added: ALWAYS
 369   type: warning
 370   description: "Some modifiers used in a key type “map” or “preserve” entry are not declared"
 371   details: |
 372     The modifiers used in `map` or `preserve` entries should be declared using the entry
 373     `modifiers` in the key type.
 374
 375 # TODO: deprecated keysym
 376 # TODO: unicode keysym when named and recommended keysym exists