# Guidelines:
# • A message code must always have the same meaning forever.
# • Codes may be retired or introduced in new releases. In order to avoid
#   clashes, retired codes must not be deleted.
# • Codes should not themselves reflect classification, e.g. a range for parse
#   errors and a range for each keymap component.
# • Codes should not be assigned sequentially because it is misleading.
# • Codes must be in the range 1..999. This range may be extended once every
#   code has be assigned.
#
# See the following guidelines for further details on good practices:
# https://github.com/haskellfoundation/error-message-index/blob/main/tool-developers.md#code-assignment-recommendations

# NOTE: Field “added: ALWAYS” means that the precise version is unknown and
# anterior to the introduction of the message registry. It will be replaced by
# the default version 1.0.0 in the generated documentation. While this is deemed
# good enough to avoid spelunking commit history, a more precise version would
# be welcome.

# TODO: fix missing detailed description, examples, resolution

- id: "deprecated-section"
  code: 21
  added: 1.14.0
  type: warning
  description: "XKB section is deprecated"
- id: "malformed-number-literal"
  code: 34
  added: ALWAYS
  type: error
  description: "Warn on malformed number literals"
  details: |
    xkbcommon can parse the following number literal formats:

    - *decimal integer:* 1, 123, etc.
    - *decimal floating-point number:* 1.23, etc.
    - *hexadecimal integer:* prefixed with “0x”: 0x123, 0xff, 0xAB, etc.
- id: "conflicting-key-type-preserve-entries"
  code: 43
  added: ALWAYS
  type: warning
  description: "Conflicting “preserve” entries in a key type"
- id: "integer-overflow"
  code: 52
  added: 1.10.0
  type: error
  description: "The result of the operation is not mathematically correct"
  details: |
    The result of the operation is not representable in the corresponding
    datatype and overflowed.
- id: "unsupported-modifier-mask"
  code: 60
  type: error
  visibility: public
  added:
    internal: ALWAYS
    public: 1.14.0
  description: "Unsupported modifier mask"
  details: |
    The modifier mask does not represent valid modifiers.
- id: "expected-array-entry"
  code: 77
  added: ALWAYS
  type: error
  description: "Expected an array entry, but the index is missing"
- id: "invalid-numeric-keysym"
  code: 82
  added: ALWAYS
  type: error
  description: "Invalid numeric keysym"
  details: |
    Keysyms are 32-bit integers with the 3 most significant bits always set to
    zero. Thus valid keysyms are in the range `0 .. 0x1fffffff` = @ref XKB_KEYSYM_MAX.

    See: Appendix A [“KEYSYM Encoding”][encoding] of the X Window System Protocol.

    [encoding]: https://www.x.org/releases/current/doc/xproto/x11protocol.html#keysym_encoding

    @see keysyms
- id: "illegal-keycode-alias"
  code: 101
  added: ALWAYS
  type: warning
  description: "Illegal keycode alias with the name of a real key"
- id: "unrecognized-keysym"
  code: 107
  added: ALWAYS
  type: warning
  description: "Warn on unrecognized keysyms"
  details: |
    xkbcommon replaces keysyms it does not recognize by the keysym `NoSymbol`.

    You may find the list of supported keysyms in
    `include/xkbcommon/xkbcommon-keysyms.h`.
  examples:
    - name: Unrecognized keysym “`coma`”
      description: |
        **Error message:**

        ```
        xkbcommon: WARNING: [XKB-107] de:31:20: unrecognized keysym "coma"
        ```

        xkbcommon does not recognize the keysym “`coma`”. It is most probably
        a typo for “<code>com<em>m</em>a</code>”.
        See: `XKB_KEY_comma` in `include/xkbcommon/xkbcommon-keysyms.h`.
      before: |
        ```c
        key <AB08> {[ coma, semicolon, periodcentered, multiply ]};
        ```
      after: |
        ```c
        key <AB08> {[ comma, semicolon, periodcentered, multiply ]};
        ```
- id: "undeclared-virtual-modifier"
  code: 123
  added: ALWAYS
  type: error
  description: "A virtual modifier is used before being declared"
- id: "insufficient-buffer-size"
  code: 134
  added: ALWAYS
  type: error
  description: "A buffer has an insufficient size"
- id: "wrong-statement-type"
  code: 150
  added: ALWAYS
  type: error
  description: "The type of the statement is not allowed in the context"
- id: "invalid-path"
  code: 161
  added: ALWAYS
  type: error
  description: "The given path is invalid"
- id: "unsupported-geometry-section"
  code: 172
  added: ALWAYS
  type: warning
  description: "Geometry sections are not supported"
- id: "cannot-infer-key-type"
  code: 183
  added: ALWAYS
  type: warning
  description: "Warn if no key type can be inferred"
- id: "invalid-escape-sequence"
  code: 193
  added: ALWAYS
  type: warning
  description: "Invalid escape sequence in a string"
- id: "illegal-key-type-preserve-result"
  code: 195
  added: ALWAYS
  type: warning
  description: "The result of a key type “preserve” entry must be a subset of its input modifiers."
- id: "invalid-include-statement"
  code: 203
  added: ALWAYS
  type: error
  description: "Syntax error in the include statement"
- id: "invalid-modmap-entry"
  code: 206
  added: ALWAYS
  type: error
  description: "A modmap entry is invalid"
- id: "unsupported-layout-out-of-range-policy"
  code: 214
  type: error
  visibility: public
  added: 1.14.0
  description: The given layout out-of-range policy is not supported
  details: |
    Use the following to check if the linked libxkbcommon library supports a given flag:

    ```c
    xkb_feature_supported(XKB_FEATURE_ENUM_LAYOUT_OUT_OF_RANGE_POLICY, flag)
    ```
- id: "unknown-statement"
  code: 222
  added: "1.14.0"
  type: error
  description: "The statement is unknown"
  details: |
    libxkbcommon encountered an unknown statement and either:
    - rejected it (strict mode);
    - accepted but discarded it in order to provide forward-compatibility (lenient mode).

    Please check if:
    - it is a typo;
    - the [keymap format](@ref xkb_keymap_format) used for parsing is correct;
    - the statement is supported in a [newer version of libxkbcommon](release-notes.md).
- id: "unsupported-layout-index"
  code: 237
  type: error
  visibility: public
  added:
    internal: ALWAYS
    public: 1.14.0
  description: "Layout index is not supported"
  details: |
    libxkbcommon supports different *layout index* ranges, depending on the target
    *keymap format*:
    - `::XKB_KEYMAP_FORMAT_TEXT_V1`: 1..{{XKB_MAX_GROUPS_X11}}
    - `::XKB_KEYMAP_FORMAT_TEXT_V2`: 1..{{XKB_MAX_GROUPS}}
- id: "conflicting-key-type-level-names"
  code: 239
  added: ALWAYS
  type: warning
  description: "The name of a key type level is defined multiple times."
- id: "invalid-set-default-statement"
  code: 254
  added: ALWAYS
  type: error
  description: "Invalid statement setting default values"
- id: "conflicting-key-type-map-entry"
  code: 266
  added: ALWAYS
  type: warning
  description: "Conflicting “map” entries in type definition"
- id: "unsupported-keymap-format"
  code: 277
  added:
    internal: ALWAYS
    public: 1.14.0
  type: error
  visibility: public
  description: "Unsupported keymap format"
  details: |
    See `xkb_keymap_format` for the list of valid values.
- id: "unrecognized-rmlvo-value"
  code: 282
  added: ALWAYS
  type: error
  description: "Unrecognized RMLVO value ignored"
  details: |
    The corresponding [RMLVO] value did not match any [rule][rules] and was ignored,
    possibly resulting in an *incomplete layout*.

    This may be:
    - An issue with the [RMLVO] value not being in sync with the XKB database.
      Updating the keyboard settings should fix it.
    - An issue with the rules:
      - If using *custom* XKB files, please check that you followed the
        [corresponding instructions](@ref custom-configuration).
        E.g. custom *options* requires a [dedicated entry](@ref custom-option).
      - If using the *standard* rules, please file a bug report to the
        [xkeyboard-config] project.

    [RMLVO]: @ref RMLVO-intro
    [xkeyboard-config]: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config
    [rules]: @ref config-rules-def
- id: "undefined-key-type"
  code: 286
  added: ALWAYS
  type: warning
  description: "Warn if using an undefined key type"
- id: "deprecated-keysym"
  code: 301
  added: 1.8.0
  type: warning
  description: "A keysym has been deprecated: consider using an alternative keysym"
  details: |
    Some keysyms have ambiguous meaning. It is advised to migrate to an alternative keysym
    if possible, as deprecated keysyms may be removed in the future. Consider using Unicode
    keysyms (`Unnnn`) if relevant.
- id: "deprecated-keysym-name"
  code: 302
  added: 1.8.0
  type: warning
  description: "A keysym name has been deprecated: use the corresponding canonical name instead"
  details: |
    Some keysym names have typos, unconventional names or are historical aliases.
    Please consider migrating to the reference name reported in the warning message.
- id: "non-base-group-name"
  code: 305
  added: ALWAYS
  type: warning
  description: "Warn if a group name was defined for group other than the first one"
- id: "unsupported-shift-level"
  code: 312
  added: ALWAYS
  type: error
  description: "Warn when a shift level is not supported"
  details: |
    Shift levels are _one_-indexed. xkbcommon supports two formats of shift levels:
    as numbers and as identifiers `LevelN`, where `N` is in the range (1..8).
- id: "included-file-not-found"
  code: 338
  added: ALWAYS
  type: error
  description: "Could not find a file used in an include statement"
- id: "unknown-operator"
  code: 345
  added: ALWAYS
  type: error
  description: "Use of an operator that is unknown and thus unsupported"
- id: "overlapping-overlay"
  code: 355
  added: 1.14.0
  type: error
  description: "Overlapping overlays are not supported"
  details: |
    [Overlays] must be *disjoint* in target keymap format: a key can have
    *at most one* overlay. See “[overlapping overlay]” for further information.

    [Overlays]: @ref key-behavior-overlay
    [overlapping overlay]: @ref overlapping-overlays
- id: "unsupported-legacy-action"
  code: 362
  added: 1.10.0
  type: warning
  description: "Use of a legacy X11 action that is not supported"
  details: |
    This action will be treated as `NoAction()`. See @ref unsupported-legacy-x11-actions ""
    for further information.
- id: "layout-count-limit-exceeded"
  code: 366
  added:
    internal: ALWAYS
    public: 1.14.0
  type: error
  visibility: public
  description: "Layout count limit exceeded for the corresponding keymap format"
  # TODO: details
- id: "unsupported-a11y-flags"
  code: 371
  type: error
  visibility: public
  added: 1.14.0
  description: Unsupported `xkb_a11y_flags` value
  details: |
    Use the following to check if the linked libxkbcommon library supports a given flag:

    ```c
    xkb_feature_supported(XKB_FEATURE_ENUM_A11Y_FLAGS, flag)
    ```
- id: "duplicate-entry"
  code: 378
  added: ALWAYS
  type: warning
  description: "An entry is duplicated and will be ignored"
- id: "recursive-include"
  code: 386
  added: 1.7.0
  type: error
  description: "Included files form cycle"
- id: "unexpected-state-mode"
  code: 399
  type: error
  visibility: public
  added: 1.14.0
  description: "A `xkb_state` object has an unexpected `xkb_state_mode`"
- id: "conflicting-key-type-definitions"
  code: 407
  added: ALWAYS
  type: warning
  description: "Conflicting definitions of a key type"
  details: |
    The given key type is defined multiple times, but only one definition is kept.
- id: "global-defaults-wrong-scope"
  code: 428
  added: ALWAYS
  type: error
  description: "A global defaults statement is in a wrong scope and should be moved"
  examples:
    - name: Default key type in key statement
      description: |
        **Error message:**

        ```
        xkbcommon: ERROR: [XKB-428] Cannot set global defaults for "type" element
        within a key statement: move statements to the global file scope.
        Assignment to "key.type" ignored.
        ```
      before: |
        ```c
        key <AE01> {
            key.type = "FOUR_LEVEL_SEMIALPHABETIC",
            symbols = [q, Q, at]
        };
        ```
      after: |
        ```c
        // Either put default key type in global file scope
        key.type = "FOUR_LEVEL_SEMIALPHABETIC";
        key <AE01> { [q, Q, at] };
        // or use a local setting (unqualified, i.e. without `key.`)
        key <AE01> {
            type = "FOUR_LEVEL_SEMIALPHABETIC",
            symbols = [ q, Q, at ]
        };
        ```
- id: "missing-default-section"
  code: 433
  added: ALWAYS
  type: warning
  description: "Missing default section in included file"
  details: |
    When using an include statement, the included file may contains multiple sections.
    The include statement may specify the name of the section to include, or leave it
    unspecified. In the latter case, the included file must then define a *default* section.
    The present warning is shown when no default section is defined.

    To solve this, either fix the include statement by specifying the exact section to
    include, or declare a default section in the included file.
- id: "abi-invalid-struct-size"
  code: 450
  type: error
  visibility: public
  added: 1.14.0
  description: ABI struct size check failed
  details: |
    The `size` field of a versioned structure does not match any known
    version of that structure. This typically indicates the caller failed
    to initialize the struct correctly, e.g. by omitting:

    ```c
    .size = sizeof(struct xkb_foo)
    ```
- id: "invalid-modifier-map-mask"
  code: 453
  added: 1.14.0
  type: error
  description: "Invalid real modifier mask in modifier map definition"
  details: |
    <dl>
    <dt>Parsing</dt>
    <dd>
    `::XKB_KEYMAP_FORMAT_TEXT_V1` allows only a *single* X11 core modifier
    per [`modifier_map`](@ref modmap-statement) entry.
    </dd>
    <dt>Serializing</dt>
    <dd>
    `::XKB_KEYMAP_FORMAT_TEXT_V1` allows only X11 core modifiers and can
    serialize multiple X11 core modifiers only if some of the original
    [`modifier_map`](@ref modmap-statement) entries used a keysym.
    </dd>
    </dl>
- id: "conflicting-key-symbol"
  code: 461
  added: ALWAYS
  type: warning
  description: "Warn if there are conflicting keysyms while merging keys"
- id: "invalid-operation"
  code: 478
  added: ALWAYS
  type: error
  description: "The operation is invalid in the context"
- id: "numeric-keysym"
  code: 489
  added: 1.6.0
  type: warning
  description: "Warn on numeric keysym (other than 0-9)"
  details: |
    Numeric keysyms are not human-friendly. Use the corresponding named keysym
    or Unicode keysym, if available.
  examples:
    - name: Hexadecimal keysym `0x1001ed0`
      description: |
        **Error message:**

        ```
        xkbcommon: WARNING: [XKB-489] numeric keysym "0x1001ed0"
        ```
      before: |
        ```c
        key <AE01> { [ 0x1001ed0] };
        ```
      after: |
        ```c
        // Preferred form: human-friendly
        key <AE01> { [ Ocircumflexacute ] };
        // or
        key <AE01> { [ U1ED0 ] };
        ```
- id: "extra-symbols-ignored"
  code: 516
  added: ALWAYS
  type: warning
  description: "TODO: add description"
- id: "conflicting-key-name"
  code: 523
  added: ALWAYS
  type: warning
  description: "Conflicting definitions of a key name or alias"
- id: "invalid-file-encoding"
  code: 542
  added: 1.7.0
  type: error
  description: "Invalid file encoding"
- id: "allocation-failure"
  code: 550
  added:
    internal: ALWAYS
    public: 1.14.0
  type: error
  visibility: public
  description: "Cannot allocate memory"
- id: "invalid-action-field"
  code: 563
  added: ALWAYS
  type: error
  description: "Unknown or unsupported action field"
- id: "wrong-field-type"
  code: 578
  added: ALWAYS
  type: error
  description: "Warn when a field has not the expected type"
- id: "unsupported-overlay-index"
  code: 588
  added: 1.14.0
  type: error
  description: "Overlay index is not in the supported range"
- id: "cannot-resolve-rmlvo"
  code: 595
  added: ALWAYS
  type: error
  description: "Cannot resolve a given (Rules, Model, Layout, Variant, Options) configuration"
- id: "invalid-unicode-escape-sequence"
  code: 607
  added: 1.9.0
  type: warning
  description: "Invalid Unicode escape sequence"
  details: |
    xkbcommon support the Unicode sequence `\u{NNNN}`, where `NNNN` denotes a
    Unicode code point in hexadecimal format in the range `1‥0x10ffff`.
- id: "invalid-real-modifier"
  code: 623
  added: ALWAYS
  type: error
  description: "Invalid _real_ modifier"
- id: "no-valid-default-include-path"
  code: 632
  added: 1.13.0
  type: error
  description: "Unable to add any default include path"
  details: |
    xkbcommon requires to define at least one include path in order to look up
    XKB files. See @ref include-path "" for further details.
- id: "unknown-default-field"
  code: 639
  added: 1.10.0
  type: error
  description: "Cannot set default value to a an unknown field"
- id: "unknown-char-escape-sequence"
  code: 645
  added: ALWAYS
  type: warning
  description: "Warn on unknown escape sequence in string literal"
  details: |
    xkbcommon support the following escape sequences in string literals:

    | Escape sequence | Corresponding character                                    |
    | --------------- | ---------------------------------------------------------- |
    | `\b`            | `U+0008` Backspace                                         |
    | `\t`            | `U+0009` Character tabulation                              |
    | `\n`            | `U+000A` Line feed                                         |
    | `\v`            | `U+000B` Vertical tabulation                               |
    | `\f`            | `U+000C` Form feed                                         |
    | `\r`            | `U+000D` Carriage return                                   |
    | `\e`            | `U+001B` Escape                                            |
    | `\\`            | `U+005C` Backslash                                         |
    | `\"`            | `U+0022` Double quote                                      |
    | `\NNNN`         | _Octal_ escape, `NNNN` in range `1‥0o377`                  |
    | `\u{NNNN}`      | _Unicode_ hexadecimal escape, `NNNN` in range `1‥0x10ffff` |
- id: "invalid-included-file"
  code: 661
  added: ALWAYS
  type: error
  description: "The target file of an include statement could not be processed"
- id: "invalid-compose-locale"
  code: 679
  added: 1.12.0
  type: error
  description: "Invalid locale for Compose"
  details: |
    The locale is either invalid (not installed on the system) or not registered
    in the X11 Compose registry.
- id: "invalid-compose-syntax"
  code: 685
  added: ALWAYS
  type: error
  description: "The Compose file syntax is invalid and the entry cannot be parsed"
- id: "incompatible-actions-and-keysyms-count"
  code: 693
  added: 1.8.0
  type: error
  description: "A level has a different number of keysyms and actions"
  details: |
    A level must have exactly the same number of keysyms and actions.
- id: "multiple-groups-at-once"
  code: 700
  added: ALWAYS
  type: warning
  description: "Warn if a key defines multiple groups at once"
- id: "unsupported-symbols-field"
  code: 711
  added: ALWAYS
  type: warning
  description: "A legacy X11 symbol field is not supported"
- id: "incompatible-keymap-text-format"
  code: 742
  added: 1.11.0
  type: error
  description: "The keymap has features unsupported in the target format"
  details: |
    See @ref keymap-support "" for further details.
- id: "rules-invalid-layout-index-percent-expansion"
  code: 762
  added: 1.11.0
  type: error
  description: "Cannot expand `%%i`: missing layout or variant in MLVO rule fields"
  details: |
    In a @ref rule-file-format "rules file", `%%i` denotes the index of the
    matched layout. It can only be used in the [KcCGST] value of the rule if the
    layout or variant is defined in the [MLVO] fields of the rule header.
    Otherwise the rule is always discarded.

    To fix the error, either remove the `:%%i` specifier or add a the relevant
    [MLVO] field, e.g. `layout[any]`.

    [KcCGST]: @ref KcCGST-intro
    [MLVO]: @ref RMLVO-intro
- id: "invalid-xkb-syntax"
  code: 769
  added: ALWAYS
  type: error
  description: "The XKB syntax is invalid and the file cannot be parsed"
  details: |
    See @ref keymap-text-format-v1-v2 "" for further details.
- id: "undefined-keycode"
  code: 770
  added: ALWAYS
  type: warning
  description: "Reference to an undefined keycode"
- id: "invalid-expression-type"
  code: 784
  added: ALWAYS
  type: error
  description: "An expression has not the expected type"
- id: "invalid-value"
  code: 796
  added: ALWAYS
  type: error
  description: "A value is invalid and will be ignored"
- id: "conflicting-modmap"
  code: 800
  added: ALWAYS
  type: warning
  description: "Warn if there are conflicting modmap definitions"
  details: |
    @todo detailed explanation and examples
- id: "unknown-field"
  code: 812
  added: ALWAYS
  type: error
  description: "A field is unknown and will be ignored"
- id: "keymap-compilation-failed"
  code: 822
  added: ALWAYS
  type: error
  description: "Keymap compilation failed"
- id: "unsupported-keymap-serialization-flags"
  code: 829
  added:
    internal: 1.12.0
    public: 1.14.0
  type: error
  visibility: public
  description: "Unsupported keymap serialization flags"
  details: |
    See `::xkb_keymap_serialize_flags` for the list of valid flags.
- id: "unknown-action-type"
  code: 844
  added: ALWAYS
  type: error
  description: "Unknown action type"
  details: |
    See @ref key-actions "" for the list of supported actions.
- id: "abi-forward-compat"
  code: 876
  type: error
  visibility: public
  added: 1.14.0
  description: ABI forward-compatibility check failed
  details: |
    The caller was compiled against a newer version of the library and is
    using fields unknown to this version.
- id: "conflicting-key-action"
  code: 883
  added: ALWAYS
  type: warning
  description: "Warn if there are conflicting actions while merging keys"
- id: "conflicting-key-type-merging-groups"
  code: 893
  added: ALWAYS
  type: warning
  description: "Warn if there are conflicting key types while merging groups"
- id: "conflicting-key-symbols-entry"
  code: 901
  added: ALWAYS
  type: error
  description: "Conflicting symbols entry for a key"
- id: "missing-symbols-group-name-index"
  code: 903
  added: ALWAYS
  type: warning
  description: "Missing group index in a group name entry"
- id: "abi-backward-compat"
  code: 914
  type: error
  visibility: public
  added: 1.14.0
  description: ABI backward-compatibility check failed
  details: |
    The caller was compiled against an older version of the library and is
    missing fields that are mandatory in this version.
- id: "unknown-section-flag"
  code: 917
  added: 1.14.0
  type: error
  description: "Invalid section flag"
  details: |
    See the list of valid [section flags](@ref section-flags-def).
- id: "conflicting-key-fields"
  code: 935
  added: ALWAYS
  type: warning
  description: "Warn if there are conflicting fields in the key definition or while merging keys"
- id: "invalid-identifier"
  code: 949
  added: ALWAYS
  type: error
  description: "An identifier is used but is not built-in"
- id: "unresolved-keymap-symbol"
  code: 965
  added: ALWAYS
  type: warning
  description: "Warn if using a symbol not defined in the keymap"
- id: "invalid-rules-syntax"
  code: 967
  added: ALWAYS
  type: error
  description: "The rules syntax is invalid and the file cannot be parsed"
  details: |
    See @ref rule-file-format "" for further information.
- id: "undeclared-modifiers-in-key-type"
  code: 971
  added: ALWAYS
  type: warning
  description: "Some modifiers used in a key type “map” or “preserve” entry are not declared"
  details: |
    The modifiers used in `map` or `preserve` entries should be declared using the entry
    `modifiers` in the key type.

# TODO: unicode keysym when named and recommended keysym exists