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: "unsupported-modifier-mask"
  34   code: 60
  35   added: ALWAYS
  36   type: error
  37   description: "Warn on unsupported modifier mask"
  38 - id: "unrecognized-keysym"
  39   code: 107
  40   added: ALWAYS
  41   type: warning
  42   description: "Warn on unrecognized keysyms"
  43   details: |
  44     xkbcommon replaces keysyms it does not recognize by the keysym `NoSymbol`.
  45
  46     You may find the list of supported keysyms in
  47     `include/xkbcommon/xkbcommon-keysyms.h`.
  48   examples:
  49     - name: Unrecognized keysym “`coma`”
  50       description: |
  51         **Error message:**
  52
  53         ```
  54         xkbcommon: WARNING: [XKB-107] de:31:20: unrecognized keysym "coma"
  55         ```
  56
  57         xkbcommon does not recognize the keysym “`coma`”. It is most probably
  58         a typo for “<code>com<em>m</em>a</code>”.
  59         See: `XKB_KEY_comma` in `include/xkbcommon/xkbcommon-keysyms.h`.
  60       before: |
  61         ```c
  62         key <AB08> {[ coma, semicolon, periodcentered, multiply ]};
  63         ```
  64       after: |
  65         ```c
  66         key <AB08> {[ comma, semicolon, periodcentered, multiply ]};
  67         ```
  68 - id: "cannot-infer-key-type"
  69   code: 183
  70   added: ALWAYS
  71   type: warning
  72   description: "Warn if no key type can be inferred"
  73 - id: "unsupported-group-index"
  74   code: 237
  75   added: ALWAYS
  76   type: error
  77   description: "Warn when a group index is not supported"
  78   details: |
  79     xkbcommon supports group index in the range (1..{{XKB_MAX_GROUPS}}).
  80 - id: "undefined-key-type"
  81   code: 286
  82   added: ALWAYS
  83   type: warning
  84   description: "Warn if using an undefined key type"
  85 - id: "non-base-group-name"
  86   code: 305
  87   added: ALWAYS
  88   type: warning
  89   description: "Warn if a group name was defined for group other than the first one"
  90 - id: "unsupported-shift-level"
  91   code: 312
  92   added: ALWAYS
  93   type: error
  94   description: "Warn when a shift level is not supported"
  95   details: |
  96     Shift levels are _one_-indexed. xkbcommon supports two formats of shift levels:
  97     as numbers and as identifiers `LevelN`, where `N` is in the range (1..8).
  98 - id: "conflicting-key-symbol"
  99   code: 461
 100   added: ALWAYS
 101   type: warning
 102   description: "Warn if there are conflicting keysyms while merging keys"
 103 - id: "extra-symbols-ignored"
 104   code: 516
 105   added: ALWAYS
 106   type: warning
 107   description: "TODO: add description"
 108 - id: "wrong-field-type"
 109   code: 578
 110   added: ALWAYS
 111   type: error
 112   description: "Warn when a field has not the expected type"
 113 - id: "unknown-char-escape-sequence"
 114   code: 645
 115   added: ALWAYS
 116   type: warning
 117   description: "Warn on unknown escape sequence in string literal"
 118   details: |
 119     xkbcommon support the following escape sequences in string literals:
 120
 121     | Escape sequence | Corresponding character             |
 122     | --------------- | ----------------------------------- |
 123     | `\b`            | `U+0008` Backspace                  |
 124     | `\t`            | `U+0009` Character tabulation       |
 125     | `\n`            | `U+000A` Line feed                  |
 126     | `\v`            | `U+000B` Vertical tabulation        |
 127     | `\f`            | `U+000C` Form feed                  |
 128     | `\r`            | `U+000D` Carriage return            |
 129     | `\e`            | `U+001B` Escape                     |
 130     | `\\`            | `U+005C` Backslash                  |
 131     | `\NNN`          | _Octal_ escape, from `\0` to `\777` |
 132 - id: "multiple-groups-at-once"
 133   code: 700
 134   added: ALWAYS
 135   type: warning
 136   description: "Warn if a key defines multiple groups at once"
 137 - id: "invalid-syntax"
 138   code: 769
 139   added: ALWAYS
 140   type: error
 141   description: "The syntax is invalid and the file cannot be parsed"
 142 - id: "undefined-keycode"
 143   code: 770
 144   added: ALWAYS
 145   type: warning
 146   description: "TODO: add description"
 147 - id: "conflicting-modmap"
 148   code: 800
 149   added: ALWAYS
 150   type: warning
 151   description: "Warn if there are conflicting modmap definitions"
 152   details: |
 153     @todo detailed explanation and examples
 154 - id: "conflicting-key-action"
 155   code: 883
 156   added: ALWAYS
 157   type: warning
 158   description: "Warn if there are conflicting actions while merging keys"
 159 - id: "conflicting-key-type"
 160   code: 893
 161   added: ALWAYS
 162   type: warning
 163   description: "Warn if there are conflicting key types while merging groups"
 164 - id: "conflicting-key-fields"
 165   code: 935
 166   added: ALWAYS
 167   type: warning
 168   description: "Warn if there are conflicting fields while merging keys"
 169 - id: "unresolved-keymap-symbol"
 170   code: 965
 171   added: ALWAYS
 172   type: warning
 173   description: "Warn if using a symbol not defined in the keymap"
 174
 175 # TODO: deprecated keysym
 176 # TODO: unicode keysym when named and recommended keysym exists