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: "illegal-key-type-preserve-result"
 104   code: 195
 105   added: ALWAYS
 106   type: warning
 107   description: "The result of a key type “preserve” entry must be a subset of its input modifiers."
 108 - id: "invalid-include-statement"
 109   code: 203
 110   added: ALWAYS
 111   type: error
 112   description: "Syntax error in the include statement"
 113 - id: "invalid-modmap-entry"
 114   code: 206
 115   added: ALWAYS
 116   type: error
 117   description: "A modmap entry is invalid"
 118 - id: "unsupported-group-index"
 119   code: 237
 120   added: ALWAYS
 121   type: error
 122   description: "Warn when a group index is not supported"
 123   details: |
 124     xkbcommon supports group index in the range (1..{{XKB_MAX_GROUPS}}).
 125 - id: "conflicting-key-type-level-names"
 126   code: 239
 127   added: ALWAYS
 128   type: warning
 129   description: "The name of a key type level is defined multiple times."
 130 - id: "invalid-set-default-statement"
 131   code: 254
 132   added: ALWAYS
 133   type: error
 134   description: "Invalid statement setting default values"
 135 - id: "conflicting-key-type-map-entry"
 136   code: 266
 137   added: ALWAYS
 138   type: warning
 139   description: "Conflicting “map” entries in type definition"
 140 - id: "undefined-key-type"
 141   code: 286
 142   added: ALWAYS
 143   type: warning
 144   description: "Warn if using an undefined key type"
 145 - id: "non-base-group-name"
 146   code: 305
 147   added: ALWAYS
 148   type: warning
 149   description: "Warn if a group name was defined for group other than the first one"
 150 - id: "unsupported-shift-level"
 151   code: 312
 152   added: ALWAYS
 153   type: error
 154   description: "Warn when a shift level is not supported"
 155   details: |
 156     Shift levels are _one_-indexed. xkbcommon supports two formats of shift levels:
 157     as numbers and as identifiers `LevelN`, where `N` is in the range (1..8).
 158 - id: "included-file-not-found"
 159   code: 338
 160   added: ALWAYS
 161   type: error
 162   description: "Could not find a file used in an include statement"
 163 - id: "unknown-operator"
 164   code: 345
 165   added: ALWAYS
 166   type: error
 167   description: "Use of an operator that is unknown and thus unsupported"
 168 - id: "duplicate-entry"
 169   code: 378
 170   added: ALWAYS
 171   type: warning
 172   description: "An entry is duplicated and will be ignored"
 173 - id: "conflicting-key-type-definitions"
 174   code: 407
 175   added: ALWAYS
 176   type: warning
 177   description: "Conflicting definitions of a key type"
 178   details: |
 179     The given key type is defined multiple times, but only one definition is kept.
 180 - id: "wrong-scope"
 181   code: 428
 182   added: ALWAYS
 183   type: error
 184   description: "A statement is in a wrong scope and should be moved"
 185 - id: "missing-default-section"
 186   code: 433
 187   added: ALWAYS
 188   type: warning
 189   description: "Missing default section in included file"
 190   details: |
 191     When using an include statement, the included file may contains multiple sections.
 192     The include statement may specify the name of the section to include, or leave it
 193     unspecified. In the latter case, the included file must then define a *default* section.
 194     The present warning is shown when no default section is defined.
 195
 196     To solve this, either fix the include statement by specifying the exact section to
 197     include, or declare a default section in the included file.
 198 - id: "conflicting-key-symbol"
 199   code: 461
 200   added: ALWAYS
 201   type: warning
 202   description: "Warn if there are conflicting keysyms while merging keys"
 203 - id: "invalid-operation"
 204   code: 478
 205   added: ALWAYS
 206   type: error
 207   description: "The operation is invalid in the context"
 208 - id: "numeric-keysym"
 209   code: 489
 210   added: 1.6.0
 211   type: warning
 212   description: "Warn on numeric keysym (other than 0-9)"
 213   details: |
 214     Numeric keysyms are not human-friendly. Use the corresponding named keysym
 215     or Unicode keysym, if available.
 216   examples:
 217     - name: Hexadecimal keysym `0x1001ed0`
 218       description: |
 219         **Error message:**
 220
 221         ```
 222         xkbcommon: WARNING: [XKB-489] numeric keysym "0x1001ed0"
 223         ```
 224       before: |
 225         ```c
 226         key <AE01> { [ 0x1001ed0] };
 227         ```
 228       after: |
 229         ```c
 230         // Preferred form: human-friendly
 231         key <AE01> { [ Ocircumflexacute ] };
 232         // or
 233         key <AE01> { [ U1ED0 ] };
 234         ```
 235 - id: "extra-symbols-ignored"
 236   code: 516
 237   added: ALWAYS
 238   type: warning
 239   description: "TODO: add description"
 240 - id: "conflicting-key-name"
 241   code: 523
 242   added: ALWAYS
 243   type: warning
 244   description: "Conflicting definitions of a key name or alias"
 245 - id: "allocation-error"
 246   code: 550
 247   added: ALWAYS
 248   type: error
 249   description: "Cannot allocate memory"
 250 - id: "wrong-field-type"
 251   code: 578
 252   added: ALWAYS
 253   type: error
 254   description: "Warn when a field has not the expected type"
 255 - id: "invalid-real-modifier"
 256   code: 623
 257   added: ALWAYS
 258   type: error
 259   description: "Invalid _real_ modifier"
 260 - id: "unknown-char-escape-sequence"
 261   code: 645
 262   added: ALWAYS
 263   type: warning
 264   description: "Warn on unknown escape sequence in string literal"
 265   details: |
 266     xkbcommon support the following escape sequences in string literals:
 267
 268     | Escape sequence | Corresponding character             |
 269     | --------------- | ----------------------------------- |
 270     | `\b`            | `U+0008` Backspace                  |
 271     | `\t`            | `U+0009` Character tabulation       |
 272     | `\n`            | `U+000A` Line feed                  |
 273     | `\v`            | `U+000B` Vertical tabulation        |
 274     | `\f`            | `U+000C` Form feed                  |
 275     | `\r`            | `U+000D` Carriage return            |
 276     | `\e`            | `U+001B` Escape                     |
 277     | `\\`            | `U+005C` Backslash                  |
 278     | `\NNN`          | _Octal_ escape, from `\0` to `\777` |
 279 - id: "invalid-included-file"
 280   code: 661
 281   added: ALWAYS
 282   type: error
 283   description: "The target file of an include statement could not be processed"
 284 - id: "multiple-groups-at-once"
 285   code: 700
 286   added: ALWAYS
 287   type: warning
 288   description: "Warn if a key defines multiple groups at once"
 289 - id: "unsupported-symbols-field"
 290   code: 711
 291   added: ALWAYS
 292   type: warning
 293   description: "A legacy X11 symbol field is not supported"
 294 - id: "invalid-syntax"
 295   code: 769
 296   added: ALWAYS
 297   type: error
 298   description: "The syntax is invalid and the file cannot be parsed"
 299 - id: "undefined-keycode"
 300   code: 770
 301   added: ALWAYS
 302   type: warning
 303   description: "Reference to an undefined keycode"
 304 - id: "invalid-expression-type"
 305   code: 784
 306   added: ALWAYS
 307   type: error
 308   description: "An expression has not the expected type"
 309 - id: "invalid-value"
 310   code: 796
 311   added: ALWAYS
 312   type: error
 313   description: "A value is invalid and will be ignored"
 314 - id: "conflicting-modmap"
 315   code: 800
 316   added: ALWAYS
 317   type: warning
 318   description: "Warn if there are conflicting modmap definitions"
 319   details: |
 320     @todo detailed explanation and examples
 321 - id: "unknown-field"
 322   code: 812
 323   added: ALWAYS
 324   type: error
 325   description: "A field is unknown and will be ignored"
 326 - id: "conflicting-key-action"
 327   code: 883
 328   added: ALWAYS
 329   type: warning
 330   description: "Warn if there are conflicting actions while merging keys"
 331 - id: "conflicting-key-type-merging-groups"
 332   code: 893
 333   added: ALWAYS
 334   type: warning
 335   description: "Warn if there are conflicting key types while merging groups"
 336 - id: "conflicting-key-symbols-entry"
 337   code: 901
 338   added: ALWAYS
 339   type: error
 340   description: "Conflicting symbols entry for a key"
 341 - id: "missing-symbols-group-name-index"
 342   code: 903
 343   added: ALWAYS
 344   type: warning
 345   description: "Missing group index in a group name entry"
 346 - id: "conflicting-key-fields"
 347   code: 935
 348   added: ALWAYS
 349   type: warning
 350   description: "Warn if there are conflicting fields while merging keys"
 351 - id: "invalid-identifier"
 352   code: 949
 353   added: ALWAYS
 354   type: error
 355   description: "An identifier is used but is not built-in"
 356 - id: "unresolved-keymap-symbol"
 357   code: 965
 358   added: ALWAYS
 359   type: warning
 360   description: "Warn if using a symbol not defined in the keymap"
 361 - id: "undeclared-modifiers-in-key-type"
 362   code: 971
 363   added: ALWAYS
 364   type: warning
 365   description: "Some modifiers used in a key type “map” or “preserve” entry are not declared"
 366   details: |
 367     The modifiers used in `map` or `preserve` entries should be declared using the entry
 368     `modifiers` in the key type.
 369
 370 # TODO: deprecated keysym
 371 # TODO: unicode keysym when named and recommended keysym exists